Aprovações de execução

Exec approvals são a proteção do app complementar / host de nó para permitir que um agente em sandbox execute comandos em um host real (gateway ou node). Um intertravamento de segurança: comandos são permitidos somente quando política + lista de permissões + aprovação do usuário (opcional) concordam. Exec approvals ficam acima de política de ferramentas e bloqueio elevado (a menos que elevated esteja definido como full, o que pula aprovações).

Para uma visão geral baseada em modos de deny, allowlist, ask, auto, full, mapeamento do Codex Guardian e permissões do harness ACPX, veja Modos de permissão.

Inspecionando a política efetiva

Quando um escopo local solicita host=node, exec-policy show relata esse escopo como gerenciado por nó em tempo de execução, em vez de fingir que o arquivo local de approvals é a fonte da verdade.

Se a UI do app complementar não estiver disponível, qualquer solicitação que normalmente exibiria um prompt é resolvida pelo fallback de ask (padrão: deny).

Onde se aplica

Exec approvals são aplicadas localmente no host de execução:

• Host Gateway → processo openclaw na máquina do gateway.
• Host de nó → executor de nó (app complementar do macOS ou host de nó headless).

Modelo de confiança

• Chamadores autenticados pelo Gateway são operadores confiáveis para esse Gateway.
• Nós pareados estendem essa capacidade de operador confiável ao host de nó.
• Exec approvals reduzem o risco de execução acidental, mas não são uma fronteira de autenticação por usuário nem uma política de sistema de arquivos somente leitura.
• Depois de aprovado, um comando pode alterar arquivos de acordo com as permissões selecionadas do host ou do sistema de arquivos em sandbox.
• Execuções aprovadas em host de nó vinculam o contexto de execução canônico: cwd canônico, argv exato, vínculo de env quando presente e caminho de executável fixado quando aplicável.
• Para scripts de shell e invocações diretas de arquivos de interpretador/runtime, o OpenClaw também tenta vincular um operando de arquivo local concreto. Se esse arquivo vinculado mudar após a aprovação, mas antes da execução, a execução é negada em vez de executar conteúdo divergente.
• O vínculo de arquivo é intencionalmente de melhor esforço, não um modelo semântico completo de todos os caminhos de carregador de interpretador/runtime. Se o modo de aprovação não conseguir identificar exatamente um arquivo local concreto para vincular, ele se recusa a emitir uma execução apoiada por aprovação em vez de fingir cobertura total.

Divisão no macOS

• O serviço de host de nó encaminha system.run para o app macOS por IPC local.
• O app macOS aplica approvals e executa o comando no contexto da UI.

Configurações e armazenamento

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

$OPENCLAW_STATE_DIR/exec-approvals.json# otherwise~/.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.

Exemplo de schema:

{  "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",          "commandText": "rg -n TODO",          "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 exec no host. Os valores são:

• deny - bloqueia exec no host.
• allowlist - executa somente comandos na lista de permissões sem perguntar.
• ask - usa a política de lista de permissões e pergunta em ausências.
• auto - usa a política de lista de permissões, executa correspondências determinísticas diretamente e envia ausências de aprovação pelo revisor automático nativo do OpenClaw antes de recorrer a uma rota de aprovação humana.
• full - executa exec no host sem prompts de aprovação.

tools.exec.security / tools.exec.ask legados continuam compatíveis e ainda prevalecem quando definidos no escopo mais estreito de sessão ou agente.

exec.security

exec.ask

askFallback

tools.exec.strictInlineEval

Exemplos que o modo estrito captura:

• python -c
• node -e, node --eval, node -p
• ruby -e
• perl -e, perl -E
• php -r
• lua -e
• osascript -e

No modo estrito, esses comandos ainda precisam de aprovação explícita, e allow-always não persiste novas entradas de lista de permissões para eles automaticamente.

tools.exec.commandHighlighting

Essa configuração não altera security, ask, correspondência da lista de permissões, comportamento de eval inline estrito, encaminhamento de aprovação ou execução de comandos. Ela pode ser definida globalmente em tools.exec.commandHighlighting ou por agente em agents.list[].tools.exec.commandHighlighting.

Modo YOLO (sem aprovação)

Se você quiser que exec no host execute sem prompts de aprovação, precisa abrir ambas as camadas de política - política de exec solicitada na configuração do OpenClaw (tools.exec.*) e política de approvals local do host no arquivo de approvals do host de execução.

O OpenClaw usa deny como padrão para askFallback omitido. Defina askFallback do host como full explicitamente quando um prompt de aprovação sem UI deve recorrer a permitir.

Provedores baseados em CLI que expõem seu próprio modo de permissão não interativo podem seguir essa política. A Claude CLI adiciona --permission-mode bypassPermissions quando a política de exec efetiva do OpenClaw é YOLO. Para sessões live Claude gerenciadas pelo OpenClaw, a política de exec efetiva do OpenClaw tem autoridade sobre o modo de permissão nativo da Claude: YOLO normaliza inicializações live para --permission-mode bypassPermissions, e política de exec efetiva restritiva normaliza inicializações live para --permission-mode default, mesmo que args brutos do backend Claude especifiquem outro modo.

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

Configuração persistente "nunca solicitar" no host 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

Esse atalho local atualiza ambos:

• tools.exec.host/security/ask local.
• Padrões do arquivo local de approvals, incluindo askFallback: "full".

Ele é intencionalmente apenas local. Para alterar approvals de host Gateway ou host de nó remotamente, use openclaw approvals set --gateway ou openclaw approvals set --node <id|name|ip>.

Host de nó

Para um host de nó, aplique o mesmo arquivo de approvals nesse nó:

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

Atalho apenas de sessão

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

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

Allowlist (por agente)

Allowlists são por agente. Se houver vários agentes, alterne qual agente você está editando no app macOS. Os padrões são correspondências glob.

Os padrões podem ser globs de caminho binário resolvido ou globs de nome de comando simples. 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 quando quiser confiar em uma localização binária específica.

Entradas legadas de agents.default são migradas para agents.main ao carregar. Cadeias de shell como echo ok && pwd ainda precisam que cada segmento de nível superior satisfaça as regras da allowlist.

Exemplos:

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

Restringindo argumentos com argPattern

Adicione argPattern quando uma entrada de allowlist deve corresponder a um binário e a um formato específico de argumentos. O OpenClaw avalia a expressão regular contra os argumentos do comando analisados, excluindo o token do executável (argv[0]). Para entradas escritas manualmente, os argumentos são unidos por um único espaço, então 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 é uma falha de correspondência da allowlist. Se uma entrada somente de caminho para o mesmo binário também estiver presente, argumentos sem correspondência ainda podem recorrer a essa entrada somente de caminho. Omita a entrada somente de caminho quando o objetivo for restringir o binário aos argumentos declarados.

Entradas salvas por fluxos de aprovação podem usar um formato separador interno para correspondência exata de argv. Prefira a UI ou o fluxo de aprovação para regenerar essas entradas em vez de editar manualmente o valor codificado. Se o OpenClaw não conseguir analisar argv para um segmento de comando, entradas com argPattern não correspondem.

Cada entrada de allowlist aceita:

Permitir automaticamente CLIs de Skills

Quando Permitir automaticamente CLIs de Skills está ativado, executáveis referenciados por Skills conhecidas são tratados como incluídos na allowlist em nós (nó macOS ou host de nó headless). Isso usa skills.bins pelo RPC do Gateway para buscar a lista de binários de Skills. Desative isso se quiser allowlists manuais estritas.

Binários seguros e encaminhamento de aprovação

Para binários seguros (o caminho rápido somente stdin), detalhes de vinculação de interpretador 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 exec - avançado.

Edição da Control UI

Use o cartão Control UI → Nós → Aprovações de exec para editar padrões, substituições por agente e allowlists. Escolha um escopo (Padrões ou um agente), ajuste a política, adicione/remova padrões da allowlist e depois Salve. A UI mostra metadados de último uso por padrão para que você possa manter a lista organizada.

O seletor de destino escolhe Gateway (aprovações locais) ou um Nó. Os nós devem anunciar system.execApprovals.get/set (app macOS ou host de nó headless). Se um nó ainda não anunciar aprovações de exec, edite diretamente o arquivo de aprovações local dele.

CLI: openclaw approvals aceita edição de gateway ou nó - consulte CLI de aprovações.

Fluxo de aprovação

Quando uma solicitação é necessária, o gateway transmite exec.approval.requested para clientes operadores. A Control UI e o app macOS resolvem isso via exec.approval.resolve; em seguida, o gateway encaminha a solicitação aprovada para o host do nó.

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

Isso importa para a latência de aprovação assíncrona:

• O caminho de exec do nó prepara um plano canônico antecipadamente.
• O registro de aprovação armazena esse plano e seus metadados de vinculação.
• Uma vez aprovado, a chamada final encaminhada de system.run reutiliza o plano armazenado em vez de confiar em ediçõ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 rejeita a execução encaminhada como uma incompatibilidade de aprovação.

Eventos do sistema

O ciclo de vida de exec é exposto como mensagens do sistema:

• Exec running (somente se o comando exceder o limite de aviso de execução).
• Exec finished.

Elas são publicadas na sessão do agente depois que o nó relata o evento. Aprovações de exec negadas são terminais para o próprio comando do host: o comando não é executado. Para aprovações assíncronas do agente principal com uma sessão de origem, o OpenClaw publica a negação de volta nessa sessão como um acompanhamento interno, para que o agente possa parar de aguardar o comando assíncrono e evitar um reparo por resultado ausente. Se não houver sessão ou se a sessão não puder ser retomada, o OpenClaw ainda pode relatar uma negação concisa ao operador ou à rota de chat direta. Negações para sessões de subagente não são publicadas de volta no subagente. Aprovações de exec hospedadas no Gateway emitem os mesmos eventos de ciclo de vida quando o comando termina (e opcionalmente quando fica em execução por mais tempo que o limite). Execs protegidos por aprovação reutilizam o id de aprovação como runId nessas mensagens para facilitar a correlação.

Comportamento de aprovação negada

Quando uma aprovação de exec assíncrona é negada, o OpenClaw trata o comando do host como terminal e fail-closed. Para sessões do agente principal, a negação é entregue como um acompanhamento interno da sessão que informa ao agente que o comando assíncrono não foi executado. Isso preserva a continuidade da transcrição sem expor saída obsoleta do comando. Se a entrega da sessão não estiver disponível, o OpenClaw recorre a uma negação concisa ao operador ou ao chat direto quando existe uma rota segura.

Implicações

• full é poderoso; prefira allowlists quando possível.
• ask mantém você no controle, ao mesmo tempo em que permite aprovações rápidas.
• Allowlists por agente impedem que aprovações de um agente vazem para outros.
• Aprovações só se aplicam a solicitações de exec do host 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 design. Para bloquear rigidamente exec do host, defina a segurança de aprovações como deny ou negue a ferramenta exec via política de ferramentas.

Relacionados