Aprovações de execução

As aprovações de exec são a proteção do aplicativo complementar / host de Node para permitir que um agente em sandbox execute comandos em um host real (gateway ou node). Um intertravamento de segurança: comandos só são permitidos quando política + lista de permissão + aprovação do usuário (opcional) concordam. As aprovações de exec são aplicadas por cima da política de ferramentas e do bloqueio elevado (a menos que elevado esteja definido como full, o que ignora aprovações).

# Inspecionando a política efetiva

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

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

# Onde se aplica

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

• Host do Gateway → processo openclaw na máquina do Gateway.
• Host de Node → executor de Node (aplicativo complementar do macOS ou host de Node headless).

# Modelo de confiança

• Chamadores autenticados pelo Gateway são operadores confiáveis para esse Gateway.
• Nodes pareados estendem essa capacidade de operador confiável para o host de Node.
• Aprovações de exec reduzem o risco de execução acidental, mas não são um limite de autenticação por usuário.
• Execuções aprovadas no host de Node vinculam o contexto canônico de execução: cwd canônico, argv exato, vínculo de env quando presente e caminho fixado do executável 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 será negada em vez de executar conteúdo alterado.
• A vinculação de arquivos é intencionalmente de melhor esforço, não um modelo semântico completo de todos os caminhos de carregamento de cada interpretador/runtime. Se o modo de aprovação não conseguir identificar exatamente um arquivo local concreto para vincular, ele se recusará a emitir uma execução respaldada por aprovação em vez de fingir cobertura total.

# Divisão no macOS

• O serviço de host de Node encaminha system.run para o app macOS por IPC local.
• O app macOS aplica aprovações e executa o comando no contexto da UI.

# Configurações e armazenamento

As aprovações ficam em um arquivo JSON local no host de execução:

~/.openclaw/exec-approvals.json

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",
          "commandText": "rg -n TODO",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg -n TODO",
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        }
      ]
    }
  }
}

# Ajustes de política

# 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ão para eles automaticamente.

# Modo YOLO (sem aprovação)

Se você quiser que exec no host rode sem prompts de aprovação, deverá abrir ambas as camadas de política - a política de exec solicitada na configuração do OpenClaw (tools.exec.*) e a política local de aprovações do host em ~/.openclaw/exec-approvals.json.

YOLO é o comportamento padrão do host, a menos que você o restrinja explicitamente:

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 solicitada pelo OpenClaw é YOLO. Substitua esse comportamento de backend com argumentos explícitos da Claude em agents.defaults.cliBackends.claude-cli.args / resumeArgs - por exemplo --permission-mode default, acceptEdits ou bypassPermissions.

Se quiser uma configuração mais conservadora, restrinja qualquer uma das camadas de volta para allowlist / on-miss ou deny.

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

openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw 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 locais de ~/.openclaw/exec-approvals.json.

Ele é intencionalmente apenas local. Para alterar aprovações de host do Gateway ou host de Node remotamente, use openclaw approvals set --gateway ou openclaw approvals set --node <id|name|ip>.

# Host de Node

Para um host de Node, aplique o mesmo arquivo de aprovações nesse Node:

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

# Atalho somente de sessão

• /exec security=full ask=off altera apenas a sessão atual.
• /elevated full é um atalho de emergência que também ignora aprovações de exec para essa sessã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ão (por agente)

Listas de permissão são por agente. Se existirem vários agentes, alterne qual agente você está editando no app macOS. Padrões são correspondências glob.

Os padrões podem ser globs de caminho de binário resolvido ou globs de nome de comando simples. Nomes simples correspondem apenas a comandos invocados por PATH, então 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 específica de binário.

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

Exemplos:

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

# Restringindo argumentos com argPattern

Adicione argPattern quando uma entrada de lista de permissão deve corresponder a um binário e a um formato específico de argumentos. O OpenClaw avalia a expressão regular contra os argumentos de comando analisados, excluindo o token executável (argv[0]). Para entradas escritas manualmente, os argumentos são unidos com 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 lista de permissão. Se uma entrada somente de caminho para o mesmo binário também estiver presente, argumentos sem correspondência ainda podem voltar para 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 de 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 lista de permissão oferece suporte a:

# CLIs de Skills com permissão automática

Quando CLIs de Skills com permissão automática está habilitado, executáveis referenciados por Skills conhecidas são tratados como incluídos na lista de permissões em nodes (node macOS ou host de node headless). Isso usa skills.bins sobre o RPC do Gateway para buscar a lista de bins de Skills. Desabilite isso se quiser listas de permissões manuais estritas.

# Bins seguros e encaminhamento de aprovação

Para bins seguros (o caminho rápido somente por stdin), detalhes de vinculação de interpretador e como encaminhar prompts de aprovação para Slack/Discord/Telegram (ou executá-los como clientes de aprovação nativos), consulte Aprovações de exec - avançado.

# Edição na Control UI

Use o cartão Control UI → Nodes → Aprovações de exec para editar padrões, substituições por agente e 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 então 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 Node. Nodes devem anunciar system.execApprovals.get/set (app macOS ou host de node headless). Se um node ainda não anunciar aprovações de exec, edite diretamente o ~/.openclaw/exec-approvals.json local dele.

CLI: openclaw approvals oferece suporte à edição de Gateway ou node - consulte CLI de aprovações.

# Fluxo de aprovação

Quando um prompt é necessário, o gateway transmite exec.approval.requested para clientes operadores. A Control UI e o app macOS resolvem isso via exec.approval.resolve; então o gateway encaminha a solicitação aprovada para o host do node.

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

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

• O caminho de exec do node prepara um plano canônico antecipadamente.
• O registro de aprovação armazena esse plano e seus metadados de vinculação.
• Depois de aprovado, a chamada system.run final encaminhada reutiliza o plano armazenado em vez de confiar em edições posteriores do chamador.
• Se o chamador alterar command, rawCommand, cwd, agentId ou sessionKey depois que a solicitação de aprovação foi criada, 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.
• Exec denied.

Elas são publicadas na sessão do agente depois que o node relata o evento. 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 controlados por aprovação reutilizam o ID de aprovação como o runId nessas mensagens para facilitar a correlação.

# Comportamento de aprovação negada

Quando uma aprovação de exec assíncrona é negada, o OpenClaw impede que o agente reutilize a saída de qualquer execução anterior do mesmo comando na sessão. O motivo da negação é passado com orientação explícita de que nenhuma saída de comando está disponível, o que impede o agente de afirmar que há uma nova saída ou repetir o comando negado com resultados obsoletos de uma execução bem-sucedida anterior.

# Implicações

• full é poderoso; prefira listas de permissões quando possível.
• ask mantém você no loop, mas ainda permite aprovações rápidas.
• Listas de permissões por agente impedem que as aprovações de um agente vazem para outros.
• Aprovações só se aplicam a solicitações de exec de host de remetentes autorizados. Remetentes não autorizados não podem emitir /exec.
• /exec security=full é uma conveniência em nível de sessão para operadores autorizados e ignora aprovações intencionalmente. Para bloquear rigidamente exec de host, defina a segurança de aprovações como deny ou negue a ferramenta exec via política de ferramentas.

# Relacionados