OpenClaw macOS Companion (menu bar + gateway broker)

Ứng dụng macOS là công cụ đồng hành trên menu bar cho OpenClaw. Nó quản lý quyền truy cập, quản lý/kết nối với Gateway cục bộ (qua launchd hoặc thủ công), và cung cấp các khả năng của macOS cho agent dưới dạng một node.

Chức năng

  • Hiển thị thông báo native và trạng thái trên menu bar.
  • Quản lý các prompt TCC (Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, Automation/AppleScript).
  • Chạy hoặc kết nối với Gateway (local hoặc remote).
  • Cung cấp các công cụ chỉ có trên macOS (Canvas, Camera, Screen Recording, system.run).
  • Khởi động local node host service ở chế độ remote (launchd), và dừng nó ở chế độ local.
  • Tùy chọn host PeekabooBridge cho UI automation.
  • Cài đặt CLI toàn cục (openclaw) qua npm/pnpm khi được yêu cầu (không khuyên dùng bun cho Gateway runtime).

Chế độ Local vs Remote

  • Local (mặc định): ứng dụng kết nối với Gateway local đang chạy nếu có; nếu không thì nó sẽ bật launchd service qua openclaw gateway install.
  • Remote: ứng dụng kết nối với Gateway qua SSH/Tailscale và không bao giờ khởi động process local. Ứng dụng khởi động node host service local để Gateway remote có thể kết nối với Mac này. Ứng dụng không spawn Gateway như một child process.

Điều khiển Launchd

Ứng dụng quản lý một LaunchAgent theo từng user với label bot.molt.gateway (hoặc bot.molt.<profile> khi dùng --profile/OPENCLAW_PROFILE; legacy com.openclaw.* vẫn được unload).

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

Thay label bằng bot.molt.<profile> khi chạy một named profile.

Nếu LaunchAgent chưa được cài đặt, các bạn có thể bật nó từ ứng dụng hoặc chạy openclaw gateway install.

Khả năng của Node (mac)

Ứng dụng macOS tự giới thiệu như một node. Các lệnh phổ biến:

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

Node báo cáo một permissions map để các agent có thể quyết định những gì được phép.

Node service + app IPC:

  • Khi headless node host service đang chạy (chế độ remote), nó kết nối với Gateway WS như một node.
  • system.run thực thi trong ứng dụng macOS (UI/TCC context) qua local Unix socket; các prompt + output vẫn ở trong ứng dụng.

Sơ đồ (SCI):

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

Exec approvals (system.run)

system.run được kiểm soát bởi Exec approvals trong ứng dụng macOS (Settings → Exec approvals). Security + ask + allowlist được lưu trữ cục bộ trên Mac tại:

~/.openclaw/exec-approvals.json

Ví dụ:

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

Lưu ý:

  • Các mục allowlist là glob patterns cho các đường dẫn binary đã được resolve.
  • Chọn “Always Allow” trong prompt sẽ thêm lệnh đó vào allowlist.
  • Các environment override của system.run được lọc (loại bỏ PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT) và sau đó merge với environment của ứng dụng.

Ứng dụng đăng ký URL scheme openclaw:// cho các hành động local.

openclaw://agent

Kích hoạt một Gateway agent request.

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

Query parameters:

  • message (bắt buộc)
  • sessionKey (tùy chọn)
  • thinking (tùy chọn)
  • deliver / to / channel (tùy chọn)
  • timeoutSeconds (tùy chọn)
  • key (tùy chọn unattended mode key)

An toàn:

  • Không có key, ứng dụng sẽ prompt để xác nhận.
  • Với key hợp lệ, việc chạy là unattended (dành cho các automation cá nhân).

Quy trình onboarding (điển hình)

  1. Cài đặt và khởi chạy OpenClaw.app.
  2. Hoàn thành checklist quyền truy cập (TCC prompts).
  3. Đảm bảo chế độ Local đang hoạt động và Gateway đang chạy.
  4. Cài đặt CLI nếu các bạn muốn truy cập từ terminal.

Build & dev workflow (native)

  • cd apps/macos && swift build
  • swift run OpenClaw (hoặc Xcode)
  • Package app: scripts/package-mac-app.sh

Debug gateway connectivity (macOS CLI)

Dùng debug CLI để thực hiện cùng Gateway WebSocket handshake và discovery logic mà ứng dụng macOS sử dụng, mà không cần khởi chạy ứng dụng.

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

Connect options:

  • --url <ws://host:port>: override config
  • --mode <local|remote>: resolve từ config (mặc định: config hoặc local)
  • --probe: force một health probe mới
  • --timeout <ms>: request timeout (mặc định: 15000)
  • --json: structured output để diffing

Discovery options:

  • --include-local: bao gồm các gateway sẽ bị lọc là “local”
  • --timeout <ms>: overall discovery window (mặc định: 2000)
  • --json: structured output để diffing

Mẹo: so sánh với openclaw gateway discover --json để xem liệu discovery pipeline của ứng dụng macOS (NWBrowser + tailnet DNS‑SD fallback) có khác với discovery dựa trên dns-sd của Node CLI không.

Remote connection plumbing (SSH tunnels)

Khi ứng dụng macOS chạy ở chế độ Remote, nó mở một SSH tunnel để các component UI local có thể giao tiếp với Gateway remote như thể nó đang ở localhost.

Control tunnel (Gateway WebSocket port)

  • Mục đích: health checks, status, Web Chat, config, và các control-plane calls khác.
  • Local port: Gateway port (mặc định 18789), luôn ổn định.
  • Remote port: cùng Gateway port trên remote host.
  • Hành vi: không có random local port; ứng dụng tái sử dụng tunnel healthy hiện có hoặc restart nó nếu cần.
  • SSH shape: ssh -N -L <local>:127.0.0.1:<remote> với BatchMode + ExitOnForwardFailure + keepalive options.
  • IP reporting: SSH tunnel sử dụng loopback, nên gateway sẽ thấy node IP là 127.0.0.1. Dùng transport Direct (ws/wss) nếu các bạn muốn IP client thực sự xuất hiện (xem macOS remote access).

Để biết các bước setup, xem macOS remote access. Để biết chi tiết protocol, xem Gateway protocol.

Tài liệu liên quan