​

OpenClaw macOS 컴패니언 (메뉴 바 + 게이트웨이 브로커)

​

What it does

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

​

로컬 모드 vs 원격 모드

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

​

Launchd 제어

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

​

노드 기능(mac)

• 캔버스: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
• 카메라: camera.snap, camera.clip
• 화면: screen.record
• 시스템: system.run, system.notify

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

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

​

Exec 승인(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. 로컬 모드가 활성화되어 있고 Gateway(게이트웨이) 가 실행 중인지 확인합니다.
4. 터미널 접근이 필요하면 CLI 를 설치합니다.

​

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

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

​

Gateway(게이트웨이) 연결 디버그(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 터널)

​

제어 터널(Gateway WebSocket 포트)

• 목적: 헬스 체크, 상태, Web Chat, 설정 및 기타 제어 플레인 호출.
• 로컬 포트: Gateway(게이트웨이) 포트(기본값 18789), 항상 고정.
• 원격 포트: 원격 호스트의 동일한 Gateway(게이트웨이) 포트.
• 동작: 임의의 로컬 포트를 사용하지 않으며, 기존의 정상 터널을 재사용하거나 필요 시 재시작합니다.
• SSH 형태: BatchMode + ExitOnForwardFailure + keepalive 옵션을 사용하는 ssh -N -L <local>:127.0.0.1:<remote>.
• IP 보고: SSH 터널은 loopback 을 사용하므로, 게이트웨이는 노드 IP 를 127.0.0.1 로 인식합니다. 실제 클라이언트 IP 가 표시되도록 하려면 Direct (ws/wss) 전송을 사용하십시오(macOS 원격 액세스 참조).

​

관련 문서

• Gateway 런북
• Gateway(macOS)
• macOS 권한
• Canvas