Ferramenta de execução

​

Parâmetros

• host aceita somente auto, sandbox, gateway ou node. Ele não é um seletor de nome de host; valores semelhantes a nomes de host são rejeitados antes da execução do comando.
• 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 adicional, host=auto ainda “simplesmente funciona”: sem sandbox, ele é resolvido como gateway; com um sandbox ativo, permanece no sandbox.
• elevated sai do sandbox para o caminho configurado do host: gateway por padrão ou node quando tools.exec.host=node (ou o padrão da sessão é host=node). Ele só está disponível quando o acesso elevado está habilitado para a sessão/o provedor atual.
• As aprovações de gateway/node são controladas pelo arquivo de aprovações do host.
• node requer um Node pareado (aplicativo complementar ou host de Node sem interface gráfica). Se vários Nodes 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 Nodes; 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) do PATH para evitar construções de bash incompatíveis com fish e, em seguida, recorre a SHELL se nenhum deles existir.
• Em hosts Windows, exec prioriza a descoberta do PowerShell 7 (pwsh) (Program Files, ProgramW6432 e depois PATH) e, em seguida, recorre ao Windows PowerShell 5.1.
• Em hosts Gateway que não sejam Windows, comandos exec de bash e zsh usam um snapshot de inicialização. O OpenClaw captura aliases/funções que podem ser carregados e um pequeno conjunto seguro de variáveis de ambiente dos arquivos de inicialização do shell em $OPENCLAW_STATE_DIR/cache/shell-snapshots/ e, em seguida, carrega esse snapshot antes de cada comando exec. Variáveis que aparentam conter segredos são excluídas; exec no sandbox e no Node não usa esse snapshot. Defina OPENCLAW_EXEC_SHELL_SNAPSHOT=0 no ambiente do processo do Gateway para desabilitar esse caminho de snapshot.
• A execução no host (gateway/node) rejeita env.PATH e substituições do carregador (LD_*/DYLD_*) para evitar sequestro de binários ou código injetado.
• O OpenClaw define OPENCLAW_SHELL=exec no ambiente do comando iniciado (incluindo execução em PTY e sandbox) para que as regras do shell/perfil possam detectar o contexto da ferramenta exec.
• Para execuções originadas em canais, o OpenClaw também expõe uma carga JSON restrita de identidade do remetente/chat em OPENCLAW_CHANNEL_CONTEXT quando o canal fornece esses IDs.
• exec não pode executar comandos de shell openclaw channels login ou /approve: openclaw channels login é um fluxo interativo de autenticação de canal, e /approve precisa passar pelo manipulador de comandos de aprovação, não por um shell. Execute o login do canal em um terminal no host Gateway ou use uma ferramenta de agente de login específica do canal quando houver uma (por exemplo, whatsapp_login).
• Importante: o sandbox está desativado por padrão. Se o sandbox estiver desativado, host=auto implícito será resolvido como gateway. host=sandbox explícito ainda falhará de forma segura, em vez de executar silenciosamente no host Gateway. Habilite o sandbox ou use host=gateway com aprovações.
• As verificações preliminares de scripts (para erros comuns de sintaxe de shell em Python/Node) inspecionam somente arquivos dentro do limite efetivo de workdir. Se o caminho de um script for resolvido fora de workdir, a verificação preliminar será ignorada para esse arquivo. A verificação preliminar também será totalmente ignorada quando host=gateway e a política efetiva for security=full com ask=off.
• Para trabalhos de longa duração iniciados agora, inicie-os uma vez e confie no acionamento automático de conclusão quando ele estiver habilitado e o comando produzir saída ou falhar. Use process para logs, status, entrada ou intervenção; não simule agendamento com loops de suspensão, loops de tempo limite ou sondagens repetidas.
• Para trabalhos que devem ocorrer posteriormente ou de forma agendada, use cron em vez de padrões de suspensão/atraso com exec.

​

Configuração

{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

​

Modos

​

Avaliação inline (strictInlineEval)

​

Tratamento de PATH

• host=gateway: mescla o PATH do seu shell de login no ambiente de execução. 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
  • Para impedir que a configuração do shell do usuário (como ~/.zshenv ou /etc/zshenv) substitua caminhos prioritários durante a inicialização, as entradas de tools.exec.pathPrepend são adicionadas com segurança ao início do PATH final dentro do comando de shell imediatamente antes da execução.
• host=sandbox: executa sh -lc (shell de login) dentro do contêiner, portanto /etc/profile pode redefinir o PATH. O OpenClaw adiciona env.PATH ao início após carregar o perfil por meio de uma variável de ambiente interna (sem interpolação do shell); tools.exec.pathPrepend também se aplica aqui.
• host=node: somente as substituições de ambiente não bloqueadas que você fornecer serão enviadas ao Node. Substituições de env.PATH são rejeitadas para execução no host e ignoradas pelos hosts Node. Se precisar de entradas adicionais no PATH de um Node, configure o ambiente do serviço do host Node (systemd/launchd) ou instale as ferramentas em locais padrão.

openclaw config get agents.list
openclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name"

​

Substituições da sessão (/exec)

/exec host=auto security=allowlist ask=on-miss node=mac-1

​

Aprovações de execução (aplicativo complementar/host Node)

​

Lista de permissões + bins seguros

• tools.exec.safeBins: filtros pequenos de fluxo, somente por stdin.
• tools.exec.safeBinTrustedDirs: diretórios confiáveis adicionais explícitos para caminhos de executáveis de bins seguros.
• tools.exec.safeBinProfiles: política explícita de argv para bins seguros personalizados.
• lista de permissões: confiança explícita em caminhos de executáveis.

​

Exemplos

{ "tool": "exec", "command": "ls -la" }

{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}

{"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"]}

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

​

apply_patch

{
  tools: {
    exec: {
      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.6-sol"] },
    },
  },
}

• A política de ferramentas ainda se aplica; allow: ["write"] permite implicitamente apply_patch.
• deny: ["write"] não nega apply_patch; negue apply_patch explicitamente ou use deny: ["group:fs"] quando as gravações de patches também precisarem ser bloqueadas.
• A configuração fica em tools.exec.applyPatch.
• tools.exec.applyPatch.enabled assume true por padrão; defina como false para desativar a ferramenta.
• tools.exec.applyPatch.workspaceOnly assume true por padrão (restrito ao espaço de trabalho). Defina como false somente se quiser intencionalmente que apply_patch grave/exclua fora do diretório do espaço de trabalho.
• tools.exec.applyPatch.allowModels é uma lista de permissões opcional de IDs de modelos (simples, como gpt-5.4, ou completos, como openai/gpt-5.4). Quando definida, somente os modelos correspondentes recebem a ferramenta; quando não definida, todos os modelos a recebem.

​

Relacionado

• Aprovações de execução — controles de aprovação para comandos de shell
• Sandbox — execução de comandos em ambientes em sandbox
• Processo em segundo plano — ferramentas de execução e processo de longa duração
• Segurança — política de ferramentas e acesso elevado