​

Companion do OpenClaw para macOS (barra de menus + broker do Gateway)

​

O que ele faz

• Mostra notificações nativas e status na barra de menus.
• Controla prompts do TCC (Notificações, Acessibilidade, Gravação de Tela, Microfone, Reconhecimento de Fala, Automação/AppleScript).
• Executa ou se conecta ao Gateway (local ou remoto).
• Expõe ferramentas exclusivas do macOS (Canvas, Câmera, Gravação de Tela, system.run).
• Inicia o serviço local de host de node no modo remoto (launchd) e o interrompe no modo local.
• Opcionalmente hospeda a PeekabooBridge para automação de UI.
• Instala a CLI global (openclaw) sob demanda via npm, pnpm ou bun (o app prefere npm, depois pnpm, depois bun; Node continua sendo o runtime recomendado para o Gateway).

​

Modo local vs remoto

• Local (padrão): o app se conecta a um Gateway local em execução, se houver; caso contrário, ele habilita o serviço launchd via openclaw gateway install.
• Remoto: o app se conecta a um Gateway por SSH/Tailscale e nunca inicia um processo local. O app inicia o serviço local de host de node para que o Gateway remoto possa alcançar este Mac. O app não inicia o Gateway como um processo filho. A descoberta do Gateway agora prefere nomes MagicDNS do Tailscale a IPs brutos da tailnet, para que o app do Mac se recupere com mais confiabilidade quando os IPs da tailnet mudarem.

​

Controle do launchd

launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway

​

Recursos do node (Mac)

• Canvas: canvas.present, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*
• Câmera: camera.snap, camera.clip
• Tela: screen.record
• Sistema: system.run, system.notify

• Quando o serviço headless de host de node está em execução (modo remoto), ele se conecta ao WS do Gateway como um node.
• system.run é executado no app do macOS (contexto de UI/TCC) por um socket Unix local; prompts + saída permanecem no app.

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

​

Aprovações de execução (system.run)

~/.openclaw/exec-approvals.json

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
    }
  }
}

• Entradas de allowlist são padrões glob para caminhos de binários resolvidos.
• Texto bruto de comando shell que contém sintaxe de controle ou expansão do shell (&&, ||, ;, |, `, $, <, >, (, )) é tratado como ausência na allowlist e exige aprovação explícita (ou inclusão do binário do shell na allowlist).
• Escolher “Sempre permitir” no prompt adiciona esse comando à allowlist.
• Substituições de ambiente de system.run são filtradas (remove PATH, DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4) e depois mescladas com o ambiente do app.
• Para wrappers de shell (bash|sh|zsh ... -c/-lc), as substituições de ambiente no escopo da solicitação são reduzidas a uma pequena allowlist explícita (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
• Para decisões de sempre permitir no modo allowlist, wrappers de despacho conhecidos (env, nice, nohup, stdbuf, timeout) persistem caminhos do executável interno em vez dos caminhos do wrapper. Se o desembrulho não for seguro, nenhuma entrada de allowlist é persistida automaticamente.

​

Links profundos

​

openclaw://agent

• message (obrigatório)
• sessionKey (opcional)
• thinking (opcional)
• deliver / to / channel (opcional)
• timeoutSeconds (opcional)
• key (opcional, chave do modo não assistido)

• Sem key, o app solicita confirmação.
• Sem key, o app aplica um limite curto de mensagem para o prompt de confirmação e ignora deliver / to / channel.
• Com uma key válida, a execução é não assistida (destinada a automações pessoais).

​

Fluxo de onboarding (típico)

1. Instale e execute o OpenClaw.app.
2. Conclua a checklist de permissões (prompts do TCC).
3. Garanta que o modo Local esteja ativo e que o Gateway esteja em execução.
4. Instale a CLI se quiser acesso pelo terminal.

​

Localização do diretório de estado (macOS)

• ~/Library/Mobile Documents/com~apple~CloudDocs/...
• ~/Library/CloudStorage/...

​

Workflow de build e desenvolvimento (nativo)

• cd apps/macos && swift build
• swift run OpenClaw (ou Xcode)
• Empacotar o app: scripts/package-mac-app.sh

​

Depurar conectividade com o Gateway (CLI do macOS)

• --url <ws://host:port>: substitui a configuração
• --mode <local|remote>: resolve a partir da configuração (padrão: configuração ou local)
• --probe: força uma sondagem de integridade nova
• --timeout <ms>: tempo limite da solicitação (padrão: 15000)
• --json: saída estruturada para comparação

• --include-local: inclui gateways que seriam filtrados como “locais”
• --timeout <ms>: janela geral de descoberta (padrão: 2000)
• --json: saída estruturada para comparação

​

Infraestrutura de conexão remota (túneis SSH)

​

Túnel de controle (porta WebSocket do Gateway)

• Objetivo: verificações de integridade, status, Chat Web, configuração e outras chamadas do plano de controle.
• Porta local: a porta do Gateway (padrão 18789), sempre estável.
• Porta remota: a mesma porta do Gateway no host remoto.
• Comportamento: sem porta local aleatória; o app reutiliza um túnel íntegro existente ou o reinicia se necessário.
• Formato do SSH: ssh -N -L <local>:127.0.0.1:<remote> com BatchMode + ExitOnForwardFailure + opções de keepalive.
• Relato de IP: o túnel SSH usa loopback, então o gateway verá o IP do node como 127.0.0.1. Use o transporte Direct (ws/wss) se quiser que o IP real do cliente apareça (consulte acesso remoto no macOS).

​

Documentação relacionada

• Runbook do Gateway
• Gateway (macOS)
• permissões do macOS
• Canvas