​

Ứng dụng đồng hành OpenClaw trên macOS (thanh menu + gateway broker)

​

Chức năng

• Hiển thị thông báo gốc và trạng thái trên thanh menu.
• Quản lý các yêu cầu TCC (Thông báo, Trợ năng, Ghi màn hình, Microphone, Nhận diện giọng nói, Tự động hóa/AppleScript).
• Chạy hoặc kết nối với Gateway (cục bộ hoặc từ xa).
• Cung cấp các công cụ chỉ có trên macOS (Canvas, Camera, Ghi màn hình, system.run).
• Khởi động dịch vụ host node cục bộ ở chế độ remote (launchd), và dừng nó ở chế độ local.
• Tùy chọn host PeekabooBridge cho tự động hóa giao diện người dùng.
• Cài đặt CLI toàn cầu (openclaw) qua npm/pnpm theo yêu cầu (không khuyến nghị dùng bun cho runtime Gateway).

​

Chế độ cục bộ và từ xa

• Cục bộ (mặc định): ứng dụng kết nối với Gateway cục bộ đang chạy nếu có; nếu không, nó kích hoạt dịch vụ launchd qua openclaw gateway install.
• Từ xa: ứng dụng kết nối với Gateway qua SSH/Tailscale và không bao giờ khởi động một tiến trình cục bộ. Ứng dụng khởi động dịch vụ node host cục bộ để Gateway từ xa có thể truy cập vào máy Mac này. Ứng dụng không tạo Gateway như một tiến trình con.

​

Quản lý launchd

launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway

​

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

• Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
• Camera: camera.snap, camera.clip
• Màn hình: screen.record
• Hệ thống: system.run, system.notify

• Khi dịch vụ host node không giao diện đang chạy (chế độ từ xa), nó kết nối với Gateway WS như một node.
• system.run thực thi trong ứng dụng macOS (ngữ cảnh UI/TCC) qua một socket Unix cục bộ; các yêu cầu và kết quả được giữ trong ứng dụng.

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

​

Phê duyệt thực thi (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" }]
    }
  }
}

• Các mục allowlist là các mẫu glob cho đường dẫn nhị phân đã được giải quyết.
• Văn bản lệnh shell thô chứa cú pháp điều khiển hoặc mở rộng shell (&&, ||, ;, |, `, $, <, >, (, )) được coi là không có trong danh sách cho phép và yêu cầu phê duyệt rõ ràng (hoặc cho phép shell nhị phân).
• Chọn “Luôn cho phép” trong yêu cầu sẽ thêm lệnh đó vào danh sách cho phép.
• Các ghi đè môi trường system.run bị lọc (bỏ PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4) và sau đó được hợp nhất với môi trường của ứng dụng.
• Đối với các shell wrapper (bash|sh|zsh ... -c/-lc), các ghi đè môi trường theo yêu cầu được giảm xuống một danh sách cho phép rõ ràng nhỏ (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
• Đối với các quyết định cho phép luôn trong chế độ danh sách cho phép, các wrapper phân phối đã biết (env, nice, nohup, stdbuf, timeout) lưu giữ đường dẫn thực thi bên trong thay vì đường dẫn wrapper. Nếu không thể mở gói an toàn, không có mục danh sách cho phép nào được lưu tự động.

​

Liên kết sâu

​

openclaw://agent

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

• 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 (khóa chế độ không giám sát tùy chọn)

• Không có key, ứng dụng sẽ yêu cầu xác nhận.
• Không có key, ứng dụng giới hạn độ dài thông điệp ngắn cho yêu cầu xác nhận và bỏ qua deliver / to / channel.
• Với key hợp lệ, việc chạy không cần giám sát (dành cho tự động hóa cá nhân).

​

Quy trình giới thiệu (thông thường)

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

​

Vị trí thư mục trạng thái (macOS)

OPENCLAW_STATE_DIR=~/.openclaw

• ~/Library/Mobile Documents/com~apple~CloudDocs/...
• ~/Library/CloudStorage/...

​

Quy trình xây dựng & phát triển (native)

• cd apps/macos && swift build
• swift run OpenClaw (hoặc Xcode)
• Đóng gói ứng dụng: scripts/package-mac-app.sh

​

Gỡ lỗi kết nối gateway (macOS CLI)

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

• --url <ws://host:port>: ghi đè cấu hình
• --mode <local|remote>: giải quyết từ cấu hình (mặc định: cấu hình hoặc cục bộ)
• --probe: buộc kiểm tra sức khỏe mới
• --timeout <ms>: thời gian chờ yêu cầu (mặc định: 15000)
• --json: đầu ra có cấu trúc để so sánh

• --include-local: bao gồm các gateway sẽ bị lọc là “cục bộ”
• --timeout <ms>: cửa sổ khám phá tổng thể (mặc định: 2000)
• --json: đầu ra có cấu trúc để so sánh

​

Kết nối từ xa (SSH tunnels)

​

Đường hầm điều khiển (cổng WebSocket Gateway)

• Mục đích: kiểm tra sức khỏe, trạng thái, Web Chat, cấu hình và các cuộc gọi mặt phẳng điều khiển khác.
• Cổng cục bộ: cổng Gateway (mặc định 18789), luôn ổn định.
• Cổng từ xa: cùng cổng Gateway trên máy chủ từ xa.
• Hành vi: không có cổng cục bộ ngẫu nhiên; ứng dụng tái sử dụng một đường hầm khỏe mạnh hiện có hoặc khởi động lại nếu cần.
• Hình dạng SSH: ssh -N -L <local>:127.0.0.1:<remote> với các tùy chọn BatchMode + ExitOnForwardFailure + keepalive.
• Báo cáo IP: đường hầm SSH sử dụng loopback, vì vậy gateway sẽ thấy IP node là 127.0.0.1. Sử dụng Direct (ws/wss) transport nếu muốn IP client thực xuất hiện (xem truy cập từ xa macOS).

​

Tài liệu liên quan

• Sổ tay Gateway
• Gateway (macOS)
• Quyền macOS
• Canvas