macOS companion app

IPC trên macOS

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

Một socket Unix cục bộ kết nối dịch vụ máy chủ Node với ứng dụng macOS để phê duyệt việc thực thi và system.run. CLI gỡ lỗi openclaw-mac (apps/macos/Sources/OpenClawMacCLI) được cung cấp để kiểm tra khả năng phát hiện/kết nối; các hành động của tác tử vẫn đi qua WebSocket của Gateway và node.invoke. Luồng computer.act dựa trên Node chạy tính năng tự động hóa Peekaboo nhúng ngay trong tiến trình; các ứng dụng khách Peekaboo độc lập sử dụng PeekabooBridge.

Mục tiêu

Một phiên bản ứng dụng GUI duy nhất sở hữu toàn bộ công việc liên quan đến TCC (thông báo, ghi màn hình, micrô, giọng nói, AppleScript).
Một bề mặt nhỏ gọn dành cho tự động hóa: Gateway + các lệnh Node, computer.act trong tiến trình, cùng với PeekabooBridge dành cho các ứng dụng khách tự động hóa giao diện người dùng độc lập.
Quyền có thể dự đoán: luôn dùng cùng một ID gói đã ký, được launchd khởi chạy, để các quyền TCC được duy trì.

Cách hoạt động

Gateway + cơ chế truyền tải Node

Ứng dụng chạy Gateway (chế độ cục bộ) và kết nối với Gateway dưới dạng một Node.
Các hành động của tác tử được thực hiện qua node.invoke (ví dụ: system.run, system.notify, canvas.*).
Các lệnh Node bao gồm canvas.*, camera.snap, camera.clip, screen.snapshot, screen.record, computer.act, system.run và system.notify.
Node báo cáo một ánh xạ permissions để các tác tử có thể biết liệu quyền truy cập màn hình, camera, micrô, giọng nói, tự động hóa hoặc trợ năng có khả dụng hay không.

Dịch vụ Node + IPC của ứng dụng

Một dịch vụ máy chủ Node không giao diện kết nối với WebSocket của Gateway.
Các yêu cầu system.run được chuyển tiếp đến ứng dụng macOS qua một socket Unix cục bộ (ExecApprovalsSocket.swift).
Ứng dụng thực hiện lệnh trong ngữ cảnh giao diện người dùng, nhắc xác nhận nếu cần và trả về đầu ra.

Sơ đồ (SCI):

text

Tác tử -> Gateway -> Dịch vụ Node (WS)                         |  IPC (UDS + mã thông báo + HMAC + TTL)                         v                     Ứng dụng Mac (UI + TCC + system.run)

PeekabooBridge (tự động hóa giao diện người dùng)

Công cụ computer tích hợp sẵn của tác tử không sử dụng socket này. Một Node macOS đã ghép đôi thực hiện computer.act trong tiến trình ứng dụng bằng các dịch vụ Peekaboo nhúng.
Tính năng tự động hóa giao diện người dùng sử dụng một socket UNIX riêng (~/Library/Application Support/OpenClaw/<socket>) và giao thức JSON của PeekabooBridge.
Thứ tự ưu tiên máy chủ (phía ứng dụng khách): Peekaboo.app -> Claude.app -> OpenClaw.app -> thực thi cục bộ.
Bảo mật: các máy chủ cầu nối yêu cầu TeamID nằm trong danh sách cho phép (PeekabooBridgeHostCoordinator đi kèm cho phép một nhóm cố định cùng nhóm ký của chính ứng dụng); một lối thoát chỉ dành cho DEBUG để chấp nhận cùng UID được bảo vệ bằng PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (quy ước của Peekaboo).
Xem: Cách sử dụng PeekabooBridge để biết chi tiết.

Luồng vận hành

Khởi động lại/biên dịch lại: scripts/restart-mac.sh dừng các phiên bản hiện có, biên dịch lại bằng Swift, đóng gói lại và khởi chạy lại. Tập lệnh tự động phát hiện danh tính ký khả dụng và chuyển sang --no-sign nếu không tìm thấy; truyền --sign để bắt buộc ký (sẽ thất bại nếu không có khóa) hoặc --no-sign để bắt buộc dùng luồng không ký. Biến SIGN_IDENTITY được đặt trong môi trường sẽ bị bỏ đặt trên luồng có ký, để cơ chế tự động phát hiện danh tính của chính scripts/codesign-mac-app.sh chọn chứng chỉ.
Một phiên bản duy nhất: ứng dụng kiểm tra NSWorkspace.runningApplications để tìm ID gói trùng lặp và thoát nếu phát hiện nhiều hơn một phiên bản (isDuplicateInstance() trong MenuBar.swift).

Ghi chú tăng cường bảo mật

Ưu tiên yêu cầu TeamID khớp trên tất cả các bề mặt đặc quyền.
PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (chỉ dành cho DEBUG) có thể cho phép các bên gọi cùng UID phục vụ phát triển cục bộ.
Toàn bộ giao tiếp chỉ diễn ra cục bộ; không có socket mạng nào được mở ra bên ngoài.
Lời nhắc TCC chỉ bắt nguồn từ gói ứng dụng GUI; hãy giữ ổn định ID gói đã ký giữa các lần biên dịch lại.
Tăng cường bảo mật cho socket phê duyệt thực thi: chế độ tệp 0600, mã thông báo dùng chung, kiểm tra UID của bên ngang hàng (getpeereid), cơ chế thử thách/phản hồi HMAC-SHA256 và TTL ngắn cho các yêu cầu.

Liên quan

Was this useful?