Przejdź do głównej treści

​
Architektura IPC OpenClaw w macOS

Obecny model: lokalne gniazdo Unix łączy usługę hosta węzła z aplikacją macOS w celu zatwierdzania exec + system.run. Istnieje debugowe CLI openclaw-mac do wykrywania/sprawdzania połączeń; działania agentów nadal przepływają przez WebSocket Gateway oraz node.invoke. Automatyzacja UI wykorzystuje PeekabooBridge.

​
Cele

  • Jedna instancja aplikacji GUI, która obsługuje wszystkie działania skierowane do TCC (powiadomienia, nagrywanie ekranu, mikrofon, mowa, AppleScript).
  • Mała powierzchnia automatyzacji: Gateway + polecenia węzła oraz PeekabooBridge do automatyzacji UI.
  • Przewidywalne uprawnienia: zawsze ten sam podpisany bundle ID, uruchamiany przez launchd, dzięki czemu przyznania TCC są trwałe.

​
Jak to działa

​
Gateway + transport węzła

  • Aplikacja uruchamia Gateway (tryb lokalny) i łączy się z nim jako węzeł.
  • Działania agentów są wykonywane przez node.invoke (np. system.run, system.notify, canvas.*).

​
Usługa węzła + IPC aplikacji

  • Bezinterfejsowa usługa hosta węzła łączy się z WebSocket Gateway.
  • Żądania system.run są przekazywane do aplikacji macOS przez lokalne gniazdo Unix.
  • Aplikacja wykonuje exec w kontekście UI, w razie potrzeby wyświetla monit i zwraca wynik.
Diagram (SCI): 
Agent -> Gateway -> Node Service (WS)
                      |  IPC (UDS + token + HMAC + TTL)
                      v
                  Mac App (UI + TCC + system.run)

​
PeekabooBridge (automatyzacja UI)

  • Automatyzacja UI używa osobnego gniazda UNIX o nazwie bridge.sock oraz protokołu JSON PeekabooBridge.
  • Kolejność preferencji hostów (po stronie klienta): Peekaboo.app → Claude.app → OpenClaw.app → wykonanie lokalne.
  • Bezpieczeństwo: hosty mostu wymagają dozwolonego TeamID; furtka DEBUG-only dla tego samego UID jest chroniona przez PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (konwencja Peekaboo).
  • Zobacz: Użycie PeekabooBridge po szczegóły.

​
Przepływy operacyjne

  • Restart/przebudowa: SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh
    • Zabija istniejące instancje
    • Kompilacja Swift + pakietowanie
    • Zapisywanie/bootstrap/kickstart LaunchAgent
  • Pojedyncza instancja: aplikacja kończy się wcześnie, jeśli działa inna instancja z tym samym bundle ID.

​
Uwagi dotyczące utwardzania

  • Preferuj wymaganie dopasowania TeamID dla wszystkich uprzywilejowanych powierzchni.
  • PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (DEBUG-only) może zezwalać na wywołania z tego samego UID na potrzeby lokalnego rozwoju.
  • Cała komunikacja pozostaje wyłącznie lokalna; żadne gniazda sieciowe nie są wystawione.
  • Monity TCC pochodzą wyłącznie z pakietu aplikacji GUI; utrzymuj stabilny podpisany bundle ID między przebudowami.
  • Utwardzanie IPC: tryb gniazda 0600, token, sprawdzanie UID rówieśnika, wyzwanie/odpowiedź HMAC, krótki TTL.