macOS companion app

IPC w macOS

Architektura IPC OpenClaw w systemie macOS

Lokalne gniazdo uniksowe łączy usługę hosta Node z aplikacją macOS na potrzeby zatwierdzania wykonywania poleceń i system.run. Dostępne jest debugowe CLI openclaw-mac (apps/macos/Sources/OpenClawMacCLI) do sprawdzania wykrywania i połączenia; działania agenta nadal przepływają przez WebSocket Gateway i node.invoke. Ścieżka computer.act obsługiwana przez Node uruchamia osadzoną automatyzację Peekaboo bezpośrednio w procesie; samodzielne klienty Peekaboo korzystają z PeekabooBridge.

Cele

Pojedyncza instancja aplikacji GUI obsługująca wszystkie operacje wymagające TCC (powiadomienia, nagrywanie ekranu, mikrofon, rozpoznawanie mowy, AppleScript).
Niewielki interfejs automatyzacji: Gateway i polecenia Node, działające w procesie computer.act oraz PeekabooBridge dla samodzielnych klientów automatyzacji interfejsu.
Przewidywalne uprawnienia: zawsze ten sam podpisany identyfikator pakietu, uruchamiany przez launchd, dzięki czemu zezwolenia TCC pozostają ważne.

Jak to działa

Transport Gateway + Node

Aplikacja uruchamia Gateway (w trybie lokalnym) i łączy się z nim jako Node.
Działania agenta są wykonywane za pośrednictwem node.invoke (np. system.run, system.notify, canvas.*).
Polecenia Node obejmują canvas.*, camera.snap, camera.clip, screen.snapshot, screen.record, computer.act, system.run i system.notify.
Node udostępnia mapę permissions, dzięki czemu agenci mogą sprawdzić dostępność uprawnień do ekranu, kamery, mikrofonu, rozpoznawania mowy, automatyzacji i ułatwień dostępu.

Usługa Node + IPC aplikacji

Bezinterfejsowa usługa hosta Node łączy się z WebSocketem Gateway.
Żądania system.run są przekazywane do aplikacji macOS przez lokalne gniazdo uniksowe (ExecApprovalsSocket.swift).
Aplikacja wykonuje polecenie w kontekście interfejsu, w razie potrzeby wyświetla monit i zwraca dane wyjściowe.

Diagram (SCI):

text

Agent -> Gateway -> Usługa Node (WS)                      |  IPC (UDS + token + HMAC + TTL)                      v                  Aplikacja Mac (UI + TCC + system.run)

PeekabooBridge (automatyzacja interfejsu)

Wbudowane narzędzie agenta computer nie korzysta z tego gniazda. Sparowany Node macOS realizuje computer.act w procesie aplikacji za pomocą osadzonych usług Peekaboo.
Automatyzacja interfejsu korzysta z osobnego gniazda UNIX (~/Library/Application Support/OpenClaw/<socket>) i protokołu JSON PeekabooBridge.
Kolejność preferencji hostów (po stronie klienta): Peekaboo.app -> Claude.app -> OpenClaw.app -> wykonanie lokalne.
Bezpieczeństwo: hosty mostu wymagają identyfikatora TeamID z listy dozwolonych (dołączony PeekabooBridgeHostCoordinator zezwala na stały zespół oraz własny zespół podpisujący aplikację); dostępne tylko w trybie DEBUG obejście dla tego samego UID jest chronione przez PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (konwencja Peekaboo).
Szczegółowe informacje: korzystanie z PeekabooBridge.

Przepływy operacyjne

Ponowne uruchomienie/przebudowa: scripts/restart-mac.sh kończy istniejące instancje, przebudowuje aplikację za pomocą Swift, ponownie ją pakuje i uruchamia. Automatycznie wykrywa dostępną tożsamość podpisującą, a jeśli jej nie znajdzie, przechodzi na --no-sign; przekaż --sign, aby wymagać podpisania (operacja kończy się niepowodzeniem, jeśli żaden klucz nie jest dostępny), lub --no-sign, aby wymusić ścieżkę bez podpisu. Zmienna SIGN_IDENTITY ustawiona w środowisku jest usuwana na ścieżce z podpisem, dzięki czemu własne automatyczne wykrywanie tożsamości przez scripts/codesign-mac-app.sh wybiera certyfikat.
Pojedyncza instancja: aplikacja sprawdza NSWorkspace.runningApplications pod kątem zduplikowanego identyfikatora pakietu i kończy działanie, jeśli znajdzie więcej niż jedną instancję (isDuplicateInstance() w MenuBar.swift).

Uwagi dotyczące zabezpieczeń

Dla wszystkich uprzywilejowanych interfejsów należy preferować wymaganie zgodności TeamID.
PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (tylko w trybie DEBUG) może zezwalać wywołującym z tym samym UID na potrzeby lokalnego programowania.
Cała komunikacja pozostaje wyłącznie lokalna; żadne gniazda sieciowe nie są udostępniane.
Monity TCC pochodzą wyłącznie z pakietu aplikacji GUI; zachowaj stabilny identyfikator podpisanego pakietu między przebudowami.
Zabezpieczenia gniazda zatwierdzania wykonywania poleceń: tryb pliku 0600, współdzielony token, sprawdzanie UID drugiej strony (getpeereid), mechanizm wezwanie–odpowiedź HMAC-SHA256 oraz krótki TTL żądań.

Powiązane

Was this useful?