​

OpenClaw macOS Companion (메뉴 막대 + 게이트웨이 브로커)

​

기능

• 메뉴 막대에 네이티브 알림과 상태를 표시합니다.
• TCC 프롬프트(알림, 접근성, 화면 녹화, 마이크, 음성 인식, 자동화/AppleScript)를 소유합니다.
• 게이트웨이를 로컬 또는 원격으로 실행하거나 연결합니다.
• macOS 전용 도구(Canvas, Camera, Screen Recording, system.run을 노출합니다).
• 원격 모드에서 로컬 노드 호스트 서비스를 시작하고, 로컬 모드에서 중지합니다.
• UI 자동화를 위해 PeekabooBridge를 선택적으로 호스팅합니다.
• 요청 시 npm/pnpm을 통해 전역 CLI(openclaw)를 설치합니다(Gateway 런타임에는 bun 권장되지 않음).

​

로컬 vs 원격 모드

• 로컬(기본값): 실행 중인 로컬 게이트웨이에 앱이 연결되고, 그렇지 않은 경우 openclaw gateway install을 통해 launchd 서비스를 활성화합니다.
• 원격: 앱이 SSH/Tailscale을 통해 게이트웨이에 연결되며, 로컬 프로세스를 시작하지 않습니다. 앱이 로컬 노드 호스트 서비스를 시작하여 원격 게이트웨이가 이 Mac에 도달할 수 있습니다. 앱은 게이트웨이를 자식 프로세스로 스폰하지 않습니다.

​

Launchd 제어

launchctl kickstart -k gui/$UID/bot.molt.gateway
launchctl bootout gui/$UID/bot.molt.gateway

​

노드 기능 (mac)

• Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
• Camera: camera.snap, camera.clip
• Screen: screen.record
• System: system.run, system.notify

• 헤드리스 노드 호스트 서비스가 실행 중일 때(원격 모드), 게이트웨이 WS에 노드로 연결됩니다.
• 로컬 Unix 소켓을 통해 macOS 앱(UI/TCC 컨텍스트)에서 system.run이 실행됩니다; 프롬프트 + 출력은 앱 내에 유지됩니다.

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + TCC + system.run)

​

실행 승인 (system.run)

~/.openclaw/exec-approvals.json

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
    }
  }
}

• allowlist 항목들은 해석된 바이너리 경로의 glob 패턴입니다.
• 프롬프트의 “항상 허용”을 선택하면 해당 명령어가 허용 목록에 추가됩니다.
• system.run 환경 오버라이드는 필터링되고 (PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT를 드롭) 앱의 환경과 병합됩니다.

​

심층 링크

​

openclaw://agent

open 'openclaw://agent?message=Hello%20from%20deep%20link'

• message (필수)
• sessionKey (선택 사항)
• thinking (선택 사항)
• deliver / to / channel (선택 사항)
• timeoutSeconds (선택 사항)
• key (선택적 비감독 모드 키)

• key가 없으면 앱은 확인을 요청합니다.
• key가 없으면 앱은 확인 프롬프트를 위해 짧은 메시지 제한을 강제하고 deliver / to / channel을 무시합니다.
• 유효한 key가 있으면 실행은 비감독 모드입니다(개인 자동화를 위해 의도됨).

​

온보딩 흐름 (일반적인)

1. OpenClaw.app을 설치하고 실행합니다.
2. 권한 체크리스트(TCC 프롬프트)를 완료합니다.
3. 로컬 모드가 활성화되고 게이트웨이가 실행 중인지 확인합니다.
4. 터미널 접근을 원하시면 CLI를 설치합니다.

​

빌드 & 개발 워크플로우 (네이티브)

• cd apps/macos && swift build
• swift run OpenClaw (또는 Xcode)
• 앱 패키지: scripts/package-mac-app.sh

​

게이트웨이 연결 디버그 (macOS CLI)

cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json

• --url <ws://host:port>: 구성 무시
• --mode <local|remote>: 구성을 통해 확인 (기본값: 구성 또는 로컬)
• --probe: 새 건강 상태 프로브 강제
• --timeout <ms>: 요청 시간 초과 (기본값: 15000)
• --json: 차등 출력을 위한 구조적 출력

• --include-local: “로컬”로 필터링될 게이트웨이를 포함
• --timeout <ms>: 전체 검색 창 (기본값: 2000)
• --json: 차등 출력을 위한 구조적 출력

​

원격 연결 배관 (SSH 터널)

​

제어 터널 (게이트웨이 WebSocket 포트)

• 목적: 상태 확인, 상태, 웹 채팅, 구성 및 기타 제어 평면 호출
• 로컬 포트: 게이트웨이 포트 (기본값 18789), 항상 안정적
• 원격 포트: 원격 호스트의 동일한 게이트웨이 포트
• 동작: 임의의 로컬 포트 없음; 앱은 기존의 건강한 터널을 재사용하거나 필요 시 재시작합니다.
• SSH 형식: ssh -N -L <local>:127.0.0.1:<remote> BatchMode + ExitOnForwardFailure + keepalive 옵션 포함
• IP 보고: SSH 터널은 루프백을 사용하므로 게이트웨이는 노드 IP를 127.0.0.1로 봅니다. 실제 클라이언트 IP가 표시되기를 원한다면 Direct (ws/wss) 전송을 사용하십시오 (macOS 원격 접속 참조).

​

관련 문서

• 게이트웨이 런북
• 게이트웨이 (macOS)
• macOS 권한
• Canvas