Arquitectura IPC de OpenClaw en macOS

Modelo actual: un socket Unix local conecta el servicio de host de nodo con la app de macOS para aprobaciones de ejecución + system.run. Un CLI de debug openclaw-mac existe para verificaciones de descubrimiento/conexión; las acciones del agente siguen fluyendo a través del WebSocket del Gateway y node.invoke. La automatización de UI usa PeekabooBridge.

Objetivos

• Una única instancia de app GUI que gestiona todo el trabajo con TCC (notificaciones, grabación de pantalla, micrófono, voz, AppleScript).
• Una superficie pequeña para automatización: comandos del Gateway + nodo, más PeekabooBridge para automatización de UI.
• Permisos predecibles: siempre el mismo bundle ID firmado, lanzado por launchd, para que las concesiones TCC persistan.

Cómo funciona

Transporte del Gateway + nodo

• La app ejecuta el Gateway (modo local) y se conecta a él como un nodo.
• Las acciones del agente se realizan vía node.invoke (p. ej. system.run, system.notify, canvas.*).

Servicio de nodo + IPC de la app

• Un servicio headless de host de nodo se conecta al WebSocket del Gateway.
• Las solicitudes de system.run se reenvían a la app de macOS a través de un socket Unix local.
• La app ejecuta el comando en contexto de UI, solicita confirmación si es necesario y devuelve la salida.

Diagrama (SCI):

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

PeekabooBridge (automatización de UI)

• La automatización de UI usa un socket UNIX separado llamado bridge.sock y el protocolo JSON de PeekabooBridge.
• Orden de preferencia del host (lado cliente): Peekaboo.app → Claude.app → OpenClaw.app → ejecución local.
• Seguridad: los hosts del bridge requieren un TeamID permitido; la vía de escape DEBUG de mismo UID está protegida por PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (convención de Peekaboo).
• Ver: Uso de PeekabooBridge para detalles.

Flujos operativos

• Reiniciar/recompilar: SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh
  • Mata instancias existentes
  • Build de Swift + empaquetado
  • Escribe/inicializa/reinicia el LaunchAgent
• Instancia única: la app se cierra temprano si otra instancia con el mismo bundle ID está ejecutándose.

Notas de endurecimiento

• Prefiere requerir coincidencia de TeamID para todas las superficies privilegiadas.
• PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (solo DEBUG) puede permitir llamadores del mismo UID para desarrollo local.
• Toda la comunicación permanece solo local; no se exponen sockets de red.
• Los prompts TCC se originan solo desde el bundle de la app GUI; mantén el bundle ID firmado estable entre recompilaciones.
• Endurecimiento IPC: modo del socket 0600, token, verificaciones de peer-UID, challenge/response HMAC, TTL corto.