Kiến trúc IPC của OpenClaw trên macOS

Mô hình hiện tại: một Unix socket cục bộ kết nối node host service với ứng dụng macOS để xử lý exec approvals + system.run. CLI debug openclaw-mac dùng để kiểm tra discovery/connect; các hành động của Agent vẫn chạy qua Gateway WebSocket và node.invoke. UI automation sử dụng PeekabooBridge.

Mục tiêu

  • Một instance ứng dụng GUI duy nhất xử lý toàn bộ công việc liên quan đến TCC (thông báo, screen recording, mic, speech, AppleScript).
  • Bề mặt automation nhỏ gọn: Gateway + các lệnh node, cộng thêm PeekabooBridge cho UI automation.
  • Quyền hạn dự đoán được: luôn dùng cùng một signed bundle ID, được khởi chạy bởi launchd, để các quyền TCC được giữ nguyên.

Cách hoạt động

Gateway + node transport

  • Ứng dụng chạy Gateway (chế độ local) và kết nối đến nó như một node.
  • Các hành động của Agent được thực hiện qua node.invoke (ví dụ: system.run, system.notify, canvas.*).

Node service + app IPC

  • Một node host service chạy headless kết nối đến Gateway WebSocket.
  • Các yêu cầu system.run được chuyển tiếp đến ứng dụng macOS qua Unix socket cục bộ.
  • Ứng dụng thực thi exec trong ngữ cảnh UI, hiển thị prompt nếu cần, và trả về output.

Sơ đồ (SCI):

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

PeekabooBridge (UI automation)

  • UI automation sử dụng một UNIX socket riêng tên là bridge.sock và giao thức JSON PeekabooBridge.
  • Thứ tự ưu tiên host (phía client): Peekaboo.app → Claude.app → OpenClaw.app → thực thi cục bộ.
  • Bảo mật: các bridge host yêu cầu TeamID được cho phép; escape hatch same-UID chỉ dành cho DEBUG được bảo vệ bởi PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (quy ước của Peekaboo).
  • Xem thêm: Cách sử dụng PeekabooBridge để biết chi tiết.

Quy trình vận hành

  • Restart/rebuild: SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh
    • Dừng các instance đang chạy
    • Swift build + package
    • Ghi/bootstrap/kickstart LaunchAgent
  • Single instance: ứng dụng thoát sớm nếu có instance khác với cùng bundle ID đang chạy.

Lưu ý về bảo mật

  • Nên yêu cầu TeamID khớp cho tất cả các bề mặt đặc quyền.
  • PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (chỉ DEBUG) có thể cho phép các caller cùng UID trong quá trình phát triển cục bộ.
  • Tất cả giao tiếp đều chỉ ở local; không có network socket nào được expose.
  • Các prompt TCC chỉ xuất phát từ GUI app bundle; giữ signed bundle ID ổn định qua các lần rebuild.
  • Bảo mật IPC: socket mode 0600, token, kiểm tra peer-UID, HMAC challenge/response, TTL ngắn.