Arquitetura de IPC do OpenClaw no macOS

Modelo atual: um soquete Unix local conecta o serviço host de nó ao app macOS para aprovações de exec + system.run. Existe uma CLI de depuração openclaw-mac para verificações de descoberta/conexão; as ações do agente ainda fluem pelo WebSocket do Gateway e por node.invoke. A automação de UI usa PeekabooBridge.

Objetivos

• Uma única instância do app GUI que controla todo o trabalho voltado ao TCC (notificações, gravação de tela, microfone, fala, AppleScript).
• Uma superfície pequena para automação: Gateway + comandos de nó, além do PeekabooBridge para automação de UI.
• Permissões previsíveis: sempre o mesmo ID de pacote assinado, iniciado pelo launchd, para que as concessões do TCC persistam.

Como funciona

Transporte Gateway + nó

• O app executa o Gateway (modo local) e se conecta a ele como um nó.
• As ações do agente são executadas via node.invoke (por exemplo, system.run, system.notify, canvas.*).
• Comandos comuns do nó no Mac incluem canvas.*, camera.snap, camera.clip, screen.snapshot, screen.record, system.run e system.notify.
• O nó informa um mapa permissions para que agentes possam ver se acesso a tela, câmera, microfone, fala, automação ou acessibilidade está disponível.

Serviço de nó + IPC do app

• Um serviço host de nó sem interface se conecta ao WebSocket do Gateway.
• Solicitações system.run são encaminhadas ao app macOS por um soquete Unix local.
• O app executa o exec no contexto da UI, solicita aprovação se necessário e retorna a saída.

Diagrama (SCI):

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

PeekabooBridge (automação de UI)

• A automação de UI usa um soquete UNIX separado chamado bridge.sock e o protocolo JSON do PeekabooBridge.
• Ordem de preferência de host (no lado do cliente): Peekaboo.app → Claude.app → OpenClaw.app → execução local.
• Segurança: hosts de bridge exigem um TeamID permitido; a saída de emergência DEBUG-only para mesmo UID é protegida por PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (convenção do Peekaboo).
• Veja: Uso do PeekabooBridge para detalhes.

Fluxos operacionais

• Reiniciar/recompilar: SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh
  • Encerra instâncias existentes
  • Build Swift + pacote
  • Grava/inicializa/reinicia o LaunchAgent
• Instância única: o app sai antecipadamente se outra instância com o mesmo ID de pacote estiver em execução.

Notas de reforço de segurança

• Prefira exigir correspondência de TeamID para todas as superfícies privilegiadas.
• PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (DEBUG-only) pode permitir chamadores com o mesmo UID para desenvolvimento local.
• Toda a comunicação permanece somente local; nenhum soquete de rede é exposto.
• Prompts do TCC se originam somente do pacote do app GUI; mantenha o ID de pacote assinado estável entre recompilações.
• Reforço de IPC: modo de soquete 0600, token, verificações de peer-UID, desafio/resposta HMAC, TTL curto.

Relacionado

• App macOS
• Fluxo de IPC do macOS (aprovações de exec)