macOS companion app

IPC do macOS

Arquitetura de IPC do OpenClaw no macOS

Um socket Unix local conecta o serviço host do Node ao aplicativo para macOS para aprovações de execução e system.run. Uma CLI de depuração openclaw-mac (apps/macos/Sources/OpenClawMacCLI) está disponível para verificações de descoberta/conexão; as ações do agente ainda fluem pelo WebSocket do Gateway e por node.invoke. O caminho computer.act apoiado pelo Node executa a automação integrada do Peekaboo no processo; clientes autônomos do Peekaboo usam o PeekabooBridge.

Objetivos

Uma única instância do aplicativo com interface gráfica, responsável por todo o trabalho voltado ao TCC (notificações, gravação de tela, microfone, fala e AppleScript).
Uma pequena superfície para automação: Gateway + comandos do Node, computer.act no processo e PeekabooBridge para clientes autônomos de automação da interface.
Permissões previsíveis: sempre o mesmo ID de pacote assinado, iniciado pelo launchd, para que as concessões do TCC sejam mantidas.

Como funciona

Transporte do Gateway + Node

O aplicativo executa o Gateway (modo local) e se conecta a ele como um Node.
As ações do agente são realizadas por meio de node.invoke (por exemplo, system.run, system.notify, canvas.*).
Os comandos do Node incluem canvas.*, camera.snap, camera.clip, screen.snapshot, screen.record, computer.act, system.run e system.notify.
O Node informa um mapa permissions para que os agentes possam verificar se o acesso à tela, câmera, microfone, fala, automação ou acessibilidade está disponível.

Serviço do Node + IPC do aplicativo

Um serviço host do Node sem interface gráfica se conecta ao WebSocket do Gateway.
As solicitações system.run são encaminhadas ao aplicativo para macOS por um socket Unix local (ExecApprovalsSocket.swift).
O aplicativo realiza a execução no contexto da interface, solicita confirmação se necessário e retorna a saída.

Diagrama (SCI):

text

Agente -> Gateway -> Serviço do Node (WS)                       |  IPC (UDS + token + HMAC + TTL)                       v                   Aplicativo para Mac (interface + TCC + system.run)

PeekabooBridge (automação da interface)

A ferramenta computer integrada do agente não usa esse socket. Um Node do macOS emparelhado realiza computer.act no processo do aplicativo com serviços integrados do Peekaboo.
A automação da interface usa um socket UNIX separado (~/Library/Application Support/OpenClaw/<socket>) 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: os hosts da ponte exigem um TeamID incluído na lista de permissões (o PeekabooBridgeHostCoordinator fornecido inclui na lista uma equipe fixa e a própria equipe de assinatura do aplicativo); uma alternativa restrita a DEBUG para o mesmo UID é protegida por PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (convenção do Peekaboo).
Consulte: Uso do PeekabooBridge para obter detalhes.

Fluxos operacionais

Reinicialização/recompilação: scripts/restart-mac.sh encerra as instâncias existentes, recompila por meio do Swift, reempacota e reinicia. Ele detecta automaticamente uma identidade de assinatura disponível e usa --no-sign como alternativa se nenhuma for encontrada; passe --sign para exigir assinatura (falha se nenhuma chave estiver disponível) ou --no-sign para forçar o caminho sem assinatura. A variável SIGN_IDENTITY definida no ambiente é removida no caminho assinado, para que a detecção automática de identidade do próprio scripts/codesign-mac-app.sh selecione o certificado.
Instância única: o aplicativo verifica NSWorkspace.runningApplications em busca de um ID de pacote duplicado e encerra se mais de uma instância for encontrada (isDuplicateInstance() em MenuBar.swift).

Notas de reforço de segurança

Prefira exigir uma correspondência de TeamID para todas as superfícies privilegiadas.
PeekabooBridge: PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 (somente DEBUG) pode permitir chamadores com o mesmo UID para desenvolvimento local.
Toda a comunicação permanece exclusivamente local; nenhum socket de rede é exposto.
As solicitações do TCC são originadas somente pelo pacote do aplicativo com interface gráfica; mantenha o ID de pacote assinado estável entre recompilações.
Reforço de segurança do socket de aprovações de execução: modo de arquivo 0600, token compartilhado, verificação do UID do par (getpeereid), desafio/resposta HMAC-SHA256 e um TTL curto para as solicitações.

Relacionado

Was this useful?