Pular para o conteúdo principal

​
Ferramenta Exec

Execute comandos de shell no workspace. Oferece suporte a execução em primeiro plano + em segundo plano via process. Se process não for permitido, exec é executado de forma síncrona e ignora yieldMs/background. As sessões em segundo plano têm escopo por agente; process só vê sessões do mesmo agente.

​
Parâmetros

  • command (obrigatório)
  • workdir (o padrão é cwd)
  • env (substituições de chave/valor)
  • yieldMs (padrão 10000): passa automaticamente para segundo plano após o atraso
  • background (bool): envia imediatamente para segundo plano
  • timeout (segundos, padrão 1800): encerra ao expirar
  • pty (bool): executa em um pseudo-terminal quando disponível (CLIs somente TTY, agentes de coding, UIs de terminal)
  • host (auto | sandbox | gateway | node): onde executar
  • security (deny | allowlist | full): modo de aplicação para gateway/node
  • ask (off | on-miss | always): prompts de aprovação para gateway/node
  • node (string): id/nome do nó para host=node
  • elevated (bool): solicita modo elevado (sair do sandbox para o caminho de host configurado); security=full só é forçado quando elevado resolve para full
Observações:
  • host usa auto por padrão: sandbox quando o runtime de sandbox está ativo para a sessão, caso contrário gateway.
  • auto é a estratégia de roteamento padrão, não um curinga. host=node por chamada é permitido a partir de auto; host=gateway por chamada só é permitido quando nenhum runtime de sandbox está ativo.
  • Sem configuração extra, host=auto ainda “simplesmente funciona”: sem sandbox, ele resolve para gateway; com um sandbox ativo, ele permanece no sandbox.
  • elevated sai do sandbox para o caminho de host configurado: gateway por padrão, ou node quando tools.exec.host=node (ou quando o padrão da sessão é host=node). Ele só está disponível quando o acesso elevado está habilitado para a sessão/provedor atual.
  • Aprovações de gateway/node são controladas por ~/.openclaw/exec-approvals.json.
  • node exige um nó emparelhado (app complementar ou host de nó headless).
  • Se vários nós estiverem disponíveis, defina exec.node ou tools.exec.node para selecionar um.
  • exec host=node é o único caminho de execução de shell para nós; o wrapper legado nodes.run foi removido.
  • Em hosts que não sejam Windows, exec usa SHELL quando definido; se SHELL for fish, ele prefere bash (ou sh) de PATH para evitar scripts incompatíveis com fish, e depois faz fallback para SHELL se nenhum dos dois existir.
  • Em hosts Windows, exec prefere descobrir o PowerShell 7 (pwsh) (Program Files, ProgramW6432 e depois PATH), e depois faz fallback para o Windows PowerShell 5.1.
  • A execução no host (gateway/node) rejeita substituições de env.PATH e de loaders (LD_*/DYLD_*) para impedir sequestro de binários ou código injetado.
  • O OpenClaw define OPENCLAW_SHELL=exec no ambiente do comando iniciado (incluindo execução com PTY e em sandbox), para que regras de shell/profile possam detectar o contexto da ferramenta exec.
  • Importante: o sandboxing fica desativado por padrão. Se o sandboxing estiver desativado, o host=auto implícito resolve para gateway. host=sandbox explícito ainda falha de forma fechada em vez de executar silenciosamente no host gateway. Habilite o sandboxing ou use host=gateway com aprovações.
  • Verificações preliminares de script (para erros comuns de sintaxe de shell em Python/Node) inspecionam apenas arquivos dentro do limite efetivo de workdir. Se um caminho de script resolver para fora de workdir, a verificação preliminar será ignorada para esse arquivo.
  • Para trabalhos de longa duração que começam agora, inicie-os uma vez e conte com o acionamento automático de conclusão quando ele estiver habilitado e o comando emitir saída ou falhar. Use process para logs, status, entrada ou intervenção; não tente emular agendamento com loops de sleep, loops de timeout ou polling repetido.
  • Para trabalhos que devem acontecer mais tarde ou em um agendamento, use cron em vez de padrões de sleep/delay com exec.

​
Configuração

  • tools.exec.notifyOnExit (padrão: true): quando true, sessões exec em segundo plano enfileiram um evento do sistema e solicitam um heartbeat ao sair.
  • tools.exec.approvalRunningNoticeMs (padrão: 10000): emite um único aviso de “em execução” quando uma execução exec protegida por aprovação ultrapassa esse tempo (0 desabilita).
  • tools.exec.host (padrão: auto; resolve para sandbox quando o runtime de sandbox está ativo, gateway caso contrário)
  • tools.exec.security (padrão: deny para sandbox, full para gateway + node quando não definido)
  • tools.exec.ask (padrão: off)
  • Execução no host sem aprovação é o padrão para gateway + node. Se você quiser comportamento de aprovações/allowlist, restrinja tanto tools.exec.* quanto o ~/.openclaw/exec-approvals.json do host; veja Aprovações de Exec.
  • O modo YOLO vem dos padrões de política do host (security=full, ask=off), não de host=auto. Se você quiser forçar roteamento para gateway ou node, defina tools.exec.host ou use /exec host=....
  • tools.exec.node (padrão: não definido)
  • tools.exec.strictInlineEval (padrão: false): quando true, formas inline de avaliação por interpretador como python -c, node -e, ruby -e, perl -e, php -r, lua -e e osascript -e sempre exigem aprovação explícita. allow-always ainda pode persistir invocações benignas de interpretador/script, mas formas de avaliação inline ainda solicitam aprovação a cada vez.
  • tools.exec.pathPrepend: lista de diretórios a acrescentar no início de PATH para execuções exec (somente gateway + sandbox).
  • tools.exec.safeBins: binários seguros somente-stdin que podem ser executados sem entradas explícitas de allowlist. Para detalhes de comportamento, veja Safe bins.
  • tools.exec.safeBinTrustedDirs: diretórios explícitos adicionais confiáveis para verificações de caminho de executável em safeBins. Entradas de PATH nunca são automaticamente confiáveis. Os padrões integrados são /bin e /usr/bin.
  • tools.exec.safeBinProfiles: política opcional de argv personalizada por safe bin (minPositional, maxPositional, allowedValueFlags, deniedFlags).
Exemplo: 
{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

​
Tratamento de PATH

  • host=gateway: mescla o PATH do seu shell de login ao ambiente de execução exec. Substituições de env.PATH são rejeitadas para execução no host. O próprio daemon ainda é executado com um PATH mínimo:
    • macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
    • Linux: /usr/local/bin, /usr/bin, /bin
  • host=sandbox: executa sh -lc (shell de login) dentro do contêiner, então /etc/profile pode redefinir PATH. O OpenClaw acrescenta env.PATH após o carregamento do profile por meio de uma variável de ambiente interna (sem interpolação de shell); tools.exec.pathPrepend também se aplica aqui.
  • host=node: apenas as substituições de ambiente não bloqueadas que você passar são enviadas ao node. Substituições de env.PATH são rejeitadas para execução no host e ignoradas por hosts de node. Se você precisar de entradas adicionais em PATH em um node, configure o ambiente do serviço do host do node (systemd/launchd) ou instale ferramentas em locais padrão.
Vinculação de node por agente (use o índice da lista de agentes na configuração): 
openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
UI de controle: a aba Nodes inclui um pequeno painel “Exec node binding” para as mesmas configurações.

​
Substituições por sessão (/exec)

Use /exec para definir padrões por sessão para host, security, ask e node. Envie /exec sem argumentos para mostrar os valores atuais. Exemplo: 
/exec host=auto security=allowlist ask=on-miss node=mac-1

​
Modelo de autorização

/exec só é respeitado para remetentes autorizados (allowlists/emparelhamento de canal mais commands.useAccessGroups). Ele atualiza apenas o estado da sessão e não grava configuração. Para desabilitar exec de forma rígida, negue-o pela política de ferramentas (tools.deny: ["exec"] ou por agente). Aprovações do host ainda se aplicam, a menos que você defina explicitamente security=full e ask=off.

​
Aprovações de Exec (app complementar / host de node)

Agentes em sandbox podem exigir aprovação por solicitação antes que exec seja executado no host gateway ou node. Veja Aprovações de Exec para a política, a allowlist e o fluxo de UI. Quando aprovações são exigidas, a ferramenta exec retorna imediatamente com status: "approval-pending" e um id de aprovação. Depois que aprovada (ou negada / expirada), o Gateway emite eventos do sistema (Exec finished / Exec denied). Se o comando ainda estiver em execução após tools.exec.approvalRunningNoticeMs, um único aviso Exec running será emitido. Em canais com cartões/botões nativos de aprovação, o agente deve contar primeiro com essa UI nativa e incluir um comando manual /approve apenas quando o resultado da ferramenta disser explicitamente que aprovações via chat não estão disponíveis ou que a aprovação manual é o único caminho.

​
Allowlist + safe bins

A aplicação manual de allowlist corresponde apenas a caminhos resolvidos de binários (sem correspondência por basename). Quando security=allowlist, comandos de shell só são permitidos automaticamente se cada segmento do pipeline estiver na allowlist ou for um safe bin. Encadeamento (;, &&, ||) e redirecionamentos são rejeitados em modo allowlist, a menos que cada segmento de nível superior satisfaça a allowlist (incluindo safe bins). Redirecionamentos continuam sem suporte. A confiança durável allow-always não contorna essa regra: um comando encadeado ainda exige que cada segmento de nível superior corresponda. autoAllowSkills é um caminho de conveniência separado em aprovações de exec. Não é o mesmo que entradas manuais de allowlist por caminho. Para confiança estritamente explícita, mantenha autoAllowSkills desabilitado. Use os dois controles para tarefas diferentes:
  • tools.exec.safeBins: pequenos filtros de fluxo somente-stdin.
  • tools.exec.safeBinTrustedDirs: diretórios adicionais explicitamente confiáveis para caminhos de executável de safe bins.
  • tools.exec.safeBinProfiles: política explícita de argv para safe bins personalizados.
  • allowlist: confiança explícita para caminhos de executáveis.
Não trate safeBins como uma allowlist genérica e não adicione binários de interpretador/runtime (por exemplo python3, node, ruby, bash). Se você precisar deles, use entradas explícitas de allowlist e mantenha os prompts de aprovação habilitados. openclaw security audit avisa quando entradas safeBins de interpretador/runtime não têm perfis explícitos, e openclaw doctor --fix pode criar entradas personalizadas ausentes em safeBinProfiles. openclaw security audit e openclaw doctor também avisam quando você adiciona explicitamente de volta em safeBins binários de comportamento amplo, como jq. Se você incluir explicitamente interpretadores na allowlist, habilite tools.exec.strictInlineEval para que formas inline de avaliação de código ainda exijam uma nova aprovação. Para detalhes completos de política e exemplos, veja Aprovações de Exec e Safe bins versus allowlist.

​
Exemplos

Primeiro plano: 
{ "tool": "exec", "command": "ls -la" }
Segundo plano + poll: 
{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}
Polling é para status sob demanda, não para loops de espera. Se o acionamento automático de conclusão estiver habilitado, o comando pode acordar a sessão quando emitir saída ou falhar. Enviar teclas (estilo tmux): 
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}
Enviar (apenas CR): 
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
Colar (com delimitação padrão): 
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

​
apply_patch

apply_patch é uma subferramenta de exec para edições estruturadas em vários arquivos. Ela é habilitada por padrão para modelos OpenAI e OpenAI Codex. Use configuração apenas quando quiser desabilitá-la ou restringi-la a modelos específicos: 
{
  tools: {
    exec: {
      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.4"] },
    },
  },
}
Observações:
  • Disponível apenas para modelos OpenAI/OpenAI Codex.
  • A política de ferramentas ainda se aplica; allow: ["write"] permite implicitamente apply_patch.
  • A configuração fica em tools.exec.applyPatch.
  • tools.exec.applyPatch.enabled usa true por padrão; defina como false para desabilitar a ferramenta para modelos OpenAI.
  • tools.exec.applyPatch.workspaceOnly usa true por padrão (contido no workspace). Defina como false apenas se você intencionalmente quiser que apply_patch grave/exclua fora do diretório do workspace.

​
Relacionado