macOS companion app
Permissões do macOS
As concessões de permissão do macOS são frágeis. O TCC associa uma concessão de permissão à assinatura de código do app, ao identificador do pacote e ao caminho em disco. Se qualquer um deles mudar, o macOS trata o app como novo e pode descartar ou ocultar prompts.
Requisitos para permissões estáveis
- Mesmo caminho: execute o app a partir de um local fixo (para OpenClaw,
dist/OpenClaw.app). - Mesmo identificador do pacote: alterar o ID do pacote cria uma nova identidade de permissão.
- App assinado: compilações não assinadas ou assinadas ad hoc não persistem permissões.
- Assinatura consistente: use um certificado real Apple Development ou Developer ID para que a assinatura permaneça estável entre recompilações.
Assinaturas ad hoc geram uma nova identidade a cada compilação. O macOS esquecerá concessões anteriores, e os prompts podem desaparecer completamente até que as entradas obsoletas sejam limpas.
Concessões de Acessibilidade para runtimes Node e CLI
Prefira conceder Acessibilidade ao OpenClaw.app, Peekaboo.app ou outro auxiliar assinado
com seu próprio identificador de pacote em vez de um binário node genérico.
O TCC do macOS concede Acessibilidade à identidade de código do processo que ele vê. Se um
fluxo de trabalho Homebrew, nvm, pnpm ou npm fizer com que um executável node compartilhado
receba Acessibilidade, qualquer pacote JavaScript iniciado por meio desse mesmo
executável poderá herdar privilégios de automação de GUI.
Trate uma entrada node nos Ajustes do Sistema como permissão ampla para esse runtime
Node, não como permissão para um pacote npm. Evite conceder Acessibilidade ao
node a menos que você confie em todos os scripts e pacotes iniciados por meio dessa instalação
Node exata.
Se você concedeu Acessibilidade ao node por acidente, remova essa entrada de
Ajustes do Sistema -> Privacidade e Segurança -> Acessibilidade. Em seguida, conceda ao app ou
auxiliar assinado que deve ser responsável pela automação de UI.
Lista de verificação de recuperação quando os prompts desaparecem
- Encerre o app.
- Remova a entrada do app em Ajustes do Sistema -> Privacidade e Segurança.
- Reinicie o app a partir do mesmo caminho e conceda as permissões novamente.
- Se o prompt ainda não aparecer, redefina as entradas do TCC com
tccutile tente novamente. - Algumas permissões só reaparecem após uma reinicialização completa do macOS.
Exemplos de redefinições (substitua o ID do pacote conforme necessário):
sudo tccutil reset Accessibility ai.openclaw.macsudo tccutil reset ScreenCapture ai.openclaw.macsudo tccutil reset AppleEventsPermissões de arquivos e pastas (Mesa/Documentos/Downloads)
O macOS também pode bloquear Mesa, Documentos e Downloads para processos de terminal/em segundo plano. Se leituras de arquivos ou listagens de diretórios travarem, conceda acesso ao mesmo contexto de processo que executa as operações de arquivo (por exemplo, Terminal/iTerm, app iniciado por LaunchAgent ou processo SSH).
Solução alternativa: mova os arquivos para o workspace do OpenClaw (~/.openclaw/workspace) se quiser evitar concessões por pasta.
Se estiver testando permissões, sempre assine com um certificado real. Compilações ad hoc só são aceitáveis para execuções locais rápidas em que permissões não importam.
