# Architettura IPC macOS di OpenClaw

Modello attuale: un socket Unix locale connette il servizio host Node alla app macOS per approvazioni exec e system.run. Esiste una CLI di debug openclaw-mac per controlli di discovery/connessione; le azioni dell'agente continuano comunque a passare attraverso il Gateway WebSocket e node.invoke. L'automazione UI usa PeekabooBridge.

# Obiettivi

• Un'unica istanza dell'app GUI che possiede tutto il lavoro lato TCC (notifiche, registrazione schermo, microfono, voce, AppleScript).
• Una piccola superficie per l'automazione: Gateway + comandi Node, più PeekabooBridge per l'automazione UI.
• Permessi prevedibili: sempre lo stesso bundle ID firmato, avviato da launchd, così le concessioni TCC persistono.

# Come funziona

# Gateway + trasporto Node

• L'app esegue il Gateway (modalità locale) e si connette ad esso come Node.
• Le azioni dell'agente vengono eseguite tramite node.invoke (ad esempio system.run, system.notify, canvas.*).

# Servizio Node + IPC dell'app

• Un servizio host Node headless si connette al Gateway WebSocket.
• Le richieste system.run vengono inoltrate all'app macOS tramite un socket Unix locale.
• L'app esegue l'exec nel contesto UI, mostra un prompt se necessario e restituisce l'output.

Diagramma (SCI):

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

# PeekabooBridge (automazione UI)

• L'automazione UI usa un socket UNIX separato chiamato bridge.sock e il protocollo JSON PeekabooBridge.
• Ordine di preferenza host (lato client): Peekaboo.app → Claude.app → OpenClaw.app → esecuzione locale.
• Sicurezza: gli host bridge richiedono un TeamID consentito; la via di fuga DEBUG-only per stesso UID è protetta da PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (convenzione Peekaboo).
• Vedi: Uso di PeekabooBridge per i dettagli.

# Flussi operativi

• Riavvio/ricostruzione: SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh
  • Termina le istanze esistenti
  • Build + package Swift
  • Scrive/inizializza/riattiva il LaunchAgent
• Istanza singola: l'app esce subito se è già in esecuzione un'altra istanza con lo stesso bundle ID.

# Note di hardening

• Preferisci richiedere una corrispondenza di TeamID per tutte le superfici privilegiate.
• PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (solo DEBUG) può consentire chiamanti con lo stesso UID per lo sviluppo locale.
• Tutta la comunicazione resta solo locale; non vengono esposti socket di rete.
• I prompt TCC provengono solo dal bundle dell'app GUI; mantieni stabile il bundle ID firmato tra una build e l'altra.
• Hardening IPC: modalità socket 0600, token, controlli peer-UID, challenge/response HMAC, TTL breve.

# Correlati

• App macOS
• Flusso IPC macOS (approvazioni Exec)