Aprovações de execução

As aprovações de execução são a proteção do aplicativo complementar / host Node para permitir que um agente em sandbox execute comandos em um host real (gateway ou node). Os comandos são executados somente quando a política + a lista de permissões + a aprovação (opcional) do usuário estão todas de acordo. As aprovações são aplicadas além da política de ferramentas e do controle de elevação (o modo elevado full as ignora).

Para uma visão geral centrada nos modos deny, allowlist, ask, auto, full, no mapeamento do Codex Guardian e nas permissões do ambiente de execução ACPX, consulte Modos de permissão.

Onde se aplica

As aprovações de execução são impostas localmente no host de execução:

• Host do Gateway -> processo openclaw na máquina do Gateway.
• Host Node -> executor Node (aplicativo complementar para macOS ou host Node sem interface gráfica).

Modelo de confiança

• Chamadores autenticados pelo Gateway são operadores confiáveis desse Gateway.
• Nodes pareados estendem essa capacidade de operador confiável ao host Node.
• As aprovações reduzem o risco de execução acidental, mas não são um limite de autenticação por usuário nem uma política de sistema de arquivos somente leitura.
• Depois de aprovado, um comando pode modificar arquivos de acordo com as permissões do sistema de arquivos do host ou da sandbox selecionada.
• Execuções aprovadas no host Node vinculam o contexto de execução canônico: cwd, argv exato, vinculação de ambiente quando presente e caminho fixado do executável quando aplicável.
• Para scripts de shell e invocações diretas de arquivos por interpretadores/ambientes de execução, o OpenClaw também tenta vincular um operando de arquivo local concreto. Se esse arquivo for alterado depois da aprovação, mas antes da execução, a execução será negada em vez de executar conteúdo divergente.
• A vinculação de arquivos é feita com o melhor esforço possível, não sendo um modelo completo de todos os caminhos de carregamento de interpretadores/ambientes de execução. Se não for possível identificar exatamente um arquivo local concreto, o OpenClaw se recusará a emitir uma execução respaldada por aprovação, em vez de simular cobertura completa.

Divisão no macOS

• O serviço do host Node encaminha system.run ao aplicativo para macOS por IPC local.
• O aplicativo para macOS impõe as aprovações e executa o comando no contexto da interface.

Inspeção da política efetiva

Referência completa da CLI (flags, saída JSON, adição/remoção da lista de permissões): CLI de aprovações.

Quando um escopo local solicita host=node, exec-policy show informa que esse escopo é gerenciado pelo Node em tempo de execução, em vez de tratar o arquivo local de aprovações como a fonte da verdade.

Se a interface do aplicativo complementar não estiver disponível, qualquer solicitação que normalmente exibiria uma confirmação será resolvida pelo fallback de consulta (padrão: deny).

Configurações e armazenamento

As aprovações ficam em um arquivo JSON local no host de execução. Quando OPENCLAW_STATE_DIR está definido, o arquivo acompanha esse diretório de estado; caso contrário, usa o diretório de estado padrão do OpenClaw:

$OPENCLAW_STATE_DIR/exec-approvals.json# caso contrário~/.openclaw/exec-approvals.json

O socket de aprovação padrão segue a mesma raiz: $OPENCLAW_STATE_DIR/exec-approvals.sock, ou ~/.openclaw/exec-approvals.sock quando a variável não está definida.

Versões anteriores à 2026.6.6 sempre mantinham o arquivo em ~/.openclaw. Se OPENCLAW_STATE_DIR apontar para outro local e ainda existir um arquivo de aprovações no diretório padrão, execute openclaw doctor --fix diretamente uma vez para importá-lo para o diretório de estado (o original será arquivado com o sufixo .migrated). O doctor interativo também pode visualizar e confirmar a importação. As execuções automatizadas de atualização e reparo de monitoramento do Gateway nunca importam dados entre diretórios de estado: um diretório de estado temporário ou de preparação não deve capturar as aprovações da instalação padrão. O mesmo limite se aplica às importações legadas de plugin-binding-approvals.json para o estado SQLite compartilhado.

Exemplo de esquema:

{  "version": 1,  "socket": {    "path": "~/.openclaw/exec-approvals.sock",    "token": "base64url-token"  },  "defaults": {    "security": "deny",    "ask": "on-miss",    "askFallback": "deny",    "autoAllowSkills": false  },  "agents": {    "main": {      "security": "allowlist",      "ask": "on-miss",      "askFallback": "deny",      "autoAllowSkills": true,      "allowlist": [        {          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",          "pattern": "~/Projects/**/bin/rg",          "source": "allow-always",          "lastUsedAt": 1737150000000,          "lastUsedCommand": "rg -n TODO",          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"        }      ]    }  }}

Controles de política

tools.exec.mode

tools.exec.mode é a superfície de política normalizada preferencial para execução no host:

Os campos legados tools.exec.security / tools.exec.ask continuam compatíveis e ainda se aplicam sempre que mode não estiver definido nesse escopo.

exec.security

exec.ask

askFallback

tools.exec.strictInlineEval

Exemplos detectados pelo modo estrito: python -c, node -e/--eval/-p, ruby -e, perl -e/-E, php -r, lua -e, osascript -e (também formas em linha de awk, sed, make, find -exec e xargs).

No modo estrito, esses comandos precisam de aprovação do revisor ou de uma aprovação explícita. Com tools.exec.mode: "auto", o revisor pode conceder uma execução única de baixo risco quando o comando tiver um plano aplicável; caso contrário, o OpenClaw solicitará aprovação humana. As aprovações de comandos do Codex app-server que chegam ao fallback do revisor solicitam aprovação humana porque suas solicitações de aprovação não expõem um executável resolvido que possa ser imposto. allow-always não persiste novas entradas na lista de permissões para comandos de avaliação em linha.

tools.exec.commandHighlighting

Defina globalmente em tools.exec.commandHighlighting ou por agente em agents.list[].tools.exec.commandHighlighting.

Modo YOLO (sem aprovação)

Para executar no host sem solicitações de aprovação, abra ambas as camadas de política: a política de execução solicitada na configuração do OpenClaw (tools.exec.*) e a política local de aprovações do host no arquivo de aprovações do host de execução.

Quando omitido, askFallback usa deny como padrão. Defina explicitamente askFallback do host como full quando uma solicitação de aprovação sem interface deva recorrer à permissão.

Provedores baseados em CLI que expõem seu próprio modo de permissão não interativo podem seguir esta política. A CLI do Claude adiciona --permission-mode bypassPermissions quando a política efetiva de execução do OpenClaw é YOLO. Para sessões ativas do Claude gerenciadas pelo OpenClaw, a política efetiva de execução do OpenClaw prevalece sobre o modo de permissão nativo do Claude: YOLO normaliza as inicializações de sessões ativas para --permission-mode bypassPermissions, e uma política efetiva de execução restritiva normaliza as inicializações de sessões ativas para --permission-mode default, mesmo que os argumentos brutos do backend do Claude especifiquem outro modo.

Se você quiser uma configuração mais conservadora, restrinja novamente a política de execução do OpenClaw para allowlist / on-miss ou deny.

Configuração persistente de "nunca solicitar" no host do Gateway

openclaw config set tools.exec.host gatewayopenclaw config set tools.exec.security fullopenclaw config set tools.exec.ask offopenclaw gateway restart

openclaw approvals set --stdin <<'EOF'{  version: 1,  defaults: {    security: "full",    ask: "off",    askFallback: "full"  }}EOF

Atalho local

openclaw exec-policy preset yolo

Atualiza tanto tools.exec.host/security/ask localmente quanto os padrões do arquivo local de aprovações (incluindo askFallback: "full"). Ele é intencionalmente exclusivo para uso local. Para alterar remotamente as aprovações do host do Gateway ou do host do Node, use openclaw approvals set --gateway ou openclaw approvals set --node <id|name|ip>.

Outras predefinições integradas: cautious (host=gateway, security=allowlist, ask=on-miss, askFallback=deny) e deny-all (host=gateway, security=deny, ask=off, askFallback=deny). Aplique da mesma forma: openclaw exec-policy preset cautious.

Para definir campos individuais em vez de uma predefinição completa, use openclaw exec-policy set --host <auto|sandbox|gateway|node> --security <deny|allowlist|full> --ask <off|on-miss|always> --ask-fallback <deny|allowlist|full> com qualquer subconjunto dessas opções.

Host do Node

Em vez disso, aplique o mesmo arquivo de aprovações no Node:

openclaw approvals set --node <id|name|ip> --stdin <<'EOF'{  version: 1,  defaults: {    security: "full",    ask: "off",    askFallback: "full"  }}EOF

Atalho exclusivo da sessão

• /exec security=full ask=off altera apenas a sessão atual.
• /elevated full é um atalho de emergência que ignora as aprovações de execução somente quando tanto a política solicitada quanto o arquivo de aprovações do host resultam em security: "full" e ask: "off". Um arquivo de host mais restritivo, como ask: "always", ainda solicita aprovação.

Se o arquivo de aprovações do host permanecer mais restritivo que a configuração, a política mais restritiva do host ainda prevalecerá.

Lista de permissões (por agente)

As listas de permissões são por agente. Se houver vários agentes, alterne o agente que você está editando no aplicativo para macOS. Os padrões usam correspondência glob.

Os padrões podem ser globs de caminhos resolvidos de binários ou globs de nomes simples de comandos. Nomes simples correspondem apenas a comandos invocados por meio de PATH, portanto rg pode corresponder a /opt/homebrew/bin/rg quando o comando é rg, mas não a ./rg ou /tmp/rg. Use um glob de caminho para confiar em um local específico do binário.

Entradas legadas em agents.default são migradas para agents.main durante o carregamento. Encadeamentos de shell, como echo ok && pwd, ainda exigem que cada segmento de nível superior atenda às regras da lista de permissões.

Exemplos:

• rg
• ~/Projects/**/bin/peekaboo
• ~/.local/bin/*
• /opt/homebrew/bin/rg

Restrição de argumentos com argPattern

Adicione argPattern quando uma entrada da lista de permissões precisar corresponder a um binário e a um formato específico de argumentos. O OpenClaw usa a semântica de expressões regulares ECMAScript (JavaScript) em todos os hosts e avalia a expressão em relação aos argumentos analisados do comando, excluindo o token do executável (argv[0]). Para entradas criadas manualmente, os argumentos são unidos com um único espaço; portanto, ancore o padrão quando precisar de uma correspondência exata.

{  "version": 1,  "agents": {    "main": {      "allowlist": [        {          "pattern": "python3",          "argPattern": "^safe\\.py$"        }      ]    }  }}

Essa entrada permite python3 safe.py; python3 other.py não corresponde à lista de permissões. Se também houver uma entrada baseada somente no caminho para o mesmo binário, argumentos sem correspondência ainda poderão recorrer a essa entrada baseada somente no caminho. Omita a entrada baseada somente no caminho quando o objetivo for restringir o binário aos argumentos declarados.

As entradas salvas pelos fluxos de aprovação usam um formato interno de separador para a correspondência exata de argv. Prefira usar a interface ou o fluxo de aprovação para gerar novamente essas entradas, em vez de editar manualmente o valor codificado. Se o OpenClaw não conseguir analisar argv para um segmento de comando, as entradas com argPattern não corresponderão.

Cada entrada da lista de permissões oferece suporte a:

Permissão automática de CLIs de Skills

Quando Permitir automaticamente CLIs de Skills (autoAllowSkills) está habilitado, os executáveis referenciados por Skills conhecidas são tratados como permitidos nos Nodes (Node do macOS ou host de Node sem interface gráfica). Isso usa skills.bins por meio do RPC do Gateway para obter a lista de binários das Skills. Desabilite essa opção se quiser listas de permissões manuais estritas.

Binários seguros e encaminhamento de aprovações

Para binários seguros (o caminho rápido exclusivo para stdin), detalhes da vinculação de interpretadores e como encaminhar solicitações de aprovação para Slack/Discord/Telegram (ou executá-las como clientes nativos de aprovação), consulte Aprovações de execução — avançado.

Edição na interface de controle

Use o cartão Interface de controle -> Nodes -> Aprovações de execução para editar os padrões, as substituições por agente e as listas de permissões. Escolha um escopo (Padrões ou um agente), ajuste a política, adicione/remova padrões da lista de permissões e clique em Salvar. A interface mostra os metadados do último uso por padrão para ajudar você a manter a lista organizada.

O seletor de destino escolhe Gateway (aprovações locais) ou um Node. Os Nodes devem anunciar system.execApprovals.get/set (aplicativo para macOS ou host de Node sem interface gráfica). Se um Node ainda não anunciar aprovações de execução, edite diretamente seu arquivo local de aprovações.

Alguns hosts de Node, incluindo o aplicativo complementar para Windows, usam um formato diferente de política de aprovação. A interface de controle mostra essas políticas nativas do host como somente leitura. Use o aplicativo complementar ou openclaw approvals set --node <id|name|ip> com o formato nativo da política para editá-las; consulte CLI de aprovações.

CLI: openclaw approvals oferece suporte à edição no Gateway ou no Node — consulte CLI de aprovações.

Fluxo de aprovação

Quando uma solicitação é necessária, o Gateway transmite exec.approval.requested aos clientes dos operadores. A interface de controle e o aplicativo para macOS a resolvem por meio de exec.approval.resolve; em seguida, o Gateway encaminha a solicitação aprovada ao host do Node.

Para host=node, as solicitações de aprovação incluem uma carga útil canônica systemRunPlan. O Gateway usa esse plano como contexto autoritativo de comando/cwd/sessão ao encaminhar solicitações system.run aprovadas:

• O caminho de execução do Node prepara antecipadamente um único plano canônico.
• O registro de aprovação armazena esse plano e seus metadados de vinculação.
• Após a aprovação, a chamada system.run final encaminhada reutiliza o plano armazenado, em vez de confiar em alterações posteriores do chamador.
• Se o chamador alterar command, rawCommand, cwd, agentId ou sessionKey após a criação da solicitação de aprovação, o Gateway rejeitará a execução encaminhada por incompatibilidade de aprovação.

Eventos do sistema e recusas

O ciclo de vida da execução publica uma mensagem de sistema Exec finished na sessão do agente depois que o Node informa a conclusão. O OpenClaw também pode emitir um aviso de execução em andamento após a concessão de uma aprovação, depois que tools.exec.approvalRunningNoticeMs decorrer (o padrão é 10000; 0 o desabilita). A recusa de uma aprovação de execução é terminal para o comando no host: o comando não é executado.

• Para aprovações assíncronas do agente principal com uma sessão de origem, o OpenClaw publica a recusa novamente nessa sessão como um acompanhamento interno, para que o agente possa parar de aguardar o comando assíncrono e evitar uma correção por resultado ausente.
• Se não houver uma sessão ou não for possível retomá-la, o OpenClaw ainda poderá informar uma recusa concisa ao operador ou à rota direta de conversa.
• As recusas de sessões de subagentes e Cron não são publicadas novamente nessas sessões.

As aprovações de execução no host do Gateway emitem o mesmo evento de conclusão do ciclo de vida. Execuções sujeitas a aprovação reutilizam o ID da aprovação para correlacionar a solicitação pendente com sua mensagem de conclusão/recusa (Exec finished (gateway id=...) / Exec denied (gateway id=...)).

Implicações

• full é poderoso; prefira listas de permissões quando possível.
• ask mantém você informado e ainda permite aprovações rápidas.
• Listas de permissões por agente impedem que as aprovações de um agente sejam aplicadas a outros.
• As aprovações se aplicam somente a solicitações de execução no host provenientes de remetentes autorizados. Remetentes não autorizados não podem emitir /exec.
• /exec security=full é uma conveniência no nível da sessão para operadores autorizados e ignora aprovações por definição. Para bloquear integralmente a execução no host, defina a segurança das aprovações como deny ou negue a ferramenta exec por meio da política de ferramentas.

Relacionados