Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Execute comandos shell no workspace. exec é uma superfície shell mutável: comandos podem criar, editar ou excluir arquivos onde quer que o host selecionado ou o sistema de arquivos do sandbox permita. Desabilitar ferramentas de sistema de arquivos do OpenClaw, como write, edit ou apply_patch, não torna exec somente leitura. Oferece suporte à execução em primeiro plano + segundo plano via process. Se process não for permitido, exec executa de forma síncrona e ignora yieldMs/background. Sessões em segundo plano têm escopo por agente; process só vê sessões do mesmo agente.

​
Parâmetros

​
command
string
obrigatório
Comando shell a executar.
​
workdir
string
padrão:"cwd"
Diretório de trabalho do comando.
​
env
object
Substituições de ambiente de chave/valor mescladas sobre o ambiente herdado.
​
yieldMs
number
padrão:"10000"
Coloca automaticamente o comando em segundo plano após este atraso (ms).
​
background
boolean
padrão:"false"
Coloca o comando em segundo plano imediatamente em vez de esperar por yieldMs.
​
timeout
number
padrão:"tools.exec.timeoutSec"
Substitui o tempo limite de exec configurado para esta chamada. Defina timeout: 0 somente quando o comando deve executar sem o tempo limite do processo exec.
​
pty
boolean
padrão:"false"
Executa em um pseudoterminal quando disponível. Use para CLIs somente TTY, agentes de codificação e UIs de terminal.
​
host
'auto' | 'sandbox' | 'gateway' | 'node'
padrão:"auto"
Onde executar. auto resolve para sandbox quando um runtime de sandbox está ativo e para gateway caso contrário.
​
security
'deny' | 'allowlist' | 'full'
Ignorado para chamadas normais de ferramentas. A segurança de gateway / node é controlada por tools.exec.security e ~/.openclaw/exec-approvals.json; o modo elevado pode forçar security=full somente quando o operador concede explicitamente acesso elevado.
​
ask
'off' | 'on-miss' | 'always'
Comportamento do prompt de aprovação para execução em gateway / node.
​
node
string
ID/nome do Node quando host=node.
​
elevated
boolean
padrão:"false"
Solicita modo elevado — escapa do sandbox para o caminho de host configurado. security=full é forçado somente quando elevated resolve para full.
Observações:
  • host tem auto como padrão: sandbox quando o runtime de sandbox está ativo para a sessão, caso contrário gateway.
  • host aceita apenas auto, sandbox, gateway ou node. Ele não é um seletor de nome de host; valores parecidos com nomes de host são rejeitados antes de o comando executar.
  • 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, resolve para gateway; com um sandbox ativo, permanece no sandbox.
  • elevated escapa do sandbox para o caminho de host configurado: 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/provedor atual.
  • Aprovações de gateway/node são controladas por ~/.openclaw/exec-approvals.json.
  • node requer um node pareado (aplicativo companheiro ou host de node headless).
  • 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 shell para nodes; o wrapper legado nodes.run foi removido.
  • timeout se aplica à execução em primeiro plano, segundo plano, yieldMs, gateway, sandbox e node system.run. Se omitido, o OpenClaw usa tools.exec.timeoutSec; timeout: 0 explícito desabilita o tempo limite do processo exec para essa chamada.
  • Em hosts não Windows, exec usa SHELL quando definido; se SHELL for fish, ele prefere bash (ou sh) de PATH para evitar scripts incompatíveis com fish, depois recorre a SHELL se nenhum deles existir.
  • Em hosts Windows, exec prefere a descoberta do PowerShell 7 (pwsh) (Program Files, ProgramW6432, depois PATH), depois recorre ao Windows PowerShell 5.1.
  • A execução no host (gateway/node) rejeita substituições de env.PATH e de loader (LD_*/DYLD_*) para impedir sequestro de binário ou código injetado.
  • O OpenClaw define OPENCLAW_SHELL=exec no ambiente do comando gerado (incluindo execução PTY e sandbox) para que regras de shell/perfil possam detectar o contexto da ferramenta exec.
  • openclaw channels login é bloqueado em exec porque é um fluxo interativo de autenticação de canal; execute-o em um terminal no host gateway ou use a ferramenta de login nativa do canal no chat quando existir.
  • Importante: o sandboxing fica desativado por padrão. Se o sandboxing estiver desativado, host=auto implícito resolve para gateway. host=sandbox explícito ainda falha fechado em vez de executar silenciosamente no host gateway. Habilite o sandboxing ou use host=gateway com aprovações.
  • Verificações de pré-voo de scripts (para erros comuns de sintaxe shell em Python/Node) inspecionam apenas arquivos dentro do limite efetivo de workdir. Se um caminho de script resolver para fora de workdir, o pré-voo é ignorado para esse arquivo.
  • Para trabalho de longa duração que começa agora, inicie-o uma vez e conte com o despertar 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 emule agendamento com loops de sleep, loops de timeout ou polling repetido.
  • Para trabalho que deve acontecer depois ou em uma agenda, use cron em vez de padrões de sleep/atraso 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 um exec com aprovação obrigatória executa por mais tempo que isso (0 desabilita).
  • tools.exec.timeoutSec (padrão: 1800): tempo limite exec padrão por comando em segundos. timeout por chamada o substitui; timeout: 0 por chamada desabilita o tempo limite do processo exec.
  • 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)
  • Exec de host sem aprovação é o padrão para gateway + node. Se quiser comportamento de aprovações/allowlist, restrinja tanto tools.exec.* quanto o ~/.openclaw/exec-approvals.json do host; consulte Aprovações de exec.
  • YOLO vem dos padrões de política do host (security=full, ask=off), não de host=auto. Se quiser forçar o roteamento por gateway ou node, defina tools.exec.host ou use /exec host=....
  • No modo security=full mais ask=off, exec de host segue diretamente a política configurada; não há camada extra de pré-filtro heurístico de ofuscação de comando nem rejeição de pré-voo de script.
  • tools.exec.node (padrão: não definido)
  • tools.exec.strictInlineEval (padrão: false): quando true, formas de eval inline de 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 inline-eval ainda solicitam aprovação a cada vez.
  • tools.exec.commandHighlighting (padrão: false): quando true, prompts de aprovação podem destacar spans de comando derivados do parser no texto do comando. Defina como true globalmente ou por agente para habilitar o destaque de texto de comando sem alterar a política de aprovação de exec.
  • tools.exec.pathPrepend: lista de diretórios a antepor a PATH para execuções de exec (somente gateway + sandbox).
  • tools.exec.safeBins: binários seguros somente stdin que podem executar sem entradas explícitas de allowlist. Para detalhes de comportamento, consulte Bins seguros.
  • tools.exec.safeBinTrustedDirs: diretórios explícitos adicionais confiáveis para verificações de caminho de 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 argv personalizada opcional por bin seguro (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 exec. Substituições de env.PATH são rejeitadas para execução no host. O daemon em si ainda executa 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 antepõe env.PATH após carregar o perfil 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 substituições de ambiente não bloqueadas que você passa 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 precisar de entradas PATH adicionais em um node, configure o ambiente de serviço do host de 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 “Vinculação de node de exec” para as mesmas configurações.

​
Substituições de 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ó é honrado para remetentes autorizados (allowlists/pareamento de canais 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 via política de ferramenta (tools.deny: ["exec"] ou por agente). Aprovações de host ainda se aplicam, a menos que você defina explicitamente security=full e ask=off.

​
Aprovações de exec (aplicativo companheiro / host de node)

Agentes em sandbox podem exigir aprovação por solicitação antes que exec execute no gateway ou no host de node. Consulte Aprovações de exec para a política, allowlist e 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 de aprovado (ou negado / expirado), 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 de aprovação nativos, o agente deve confiar primeiro nessa UI nativa e incluir apenas um comando manual /approve quando o resultado da ferramenta disser explicitamente que aprovações por chat não estão disponíveis ou que a aprovação manual é o único caminho.

​
Allowlist + bins seguros

A aplicação manual de allowlist corresponde a globs de caminho de binário resolvido e globs de nome de comando puro. Nomes puros correspondem apenas a comandos invocados por meio de PATH, então rg pode corresponder a /opt/homebrew/bin/rg quando o comando é rg, mas não a ./rg ou /tmp/rg. Quando security=allowlist, comandos shell são permitidos automaticamente somente se cada segmento do pipeline estiver na allowlist ou for um bin seguro. Encadeamento (;, &&, ||) e redirecionamentos são rejeitados no modo allowlist, a menos que cada segmento de nível superior satisfaça a allowlist (incluindo bins seguros). 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 nas aprovações de exec. Ele não é o mesmo que entradas manuais de allowlist de caminho. Para confiança explícita estrita, mantenha autoAllowSkills desabilitado. Use os dois controles para tarefas diferentes:
  • tools.exec.safeBins: filtros de fluxo pequenos, somente via stdin.
  • tools.exec.safeBinTrustedDirs: diretórios confiáveis extras explícitos para caminhos de executáveis safe-bin.
  • tools.exec.safeBinProfiles: política argv explícita para safe bins personalizados.
  • lista de permissões: confiança explícita para caminhos de executáveis.
Não trate safeBins como uma lista de permissões genérica e não adicione binários de intérprete/runtime (por exemplo, python3, node, ruby, bash). Se você precisar deles, use entradas explícitas de lista de permissões e mantenha os prompts de aprovação habilitados. openclaw security audit avisa quando entradas safeBins de intérprete/runtime não têm perfis explícitos, e openclaw doctor --fix pode estruturar entradas safeBinProfiles personalizadas ausentes. openclaw security audit e openclaw doctor também avisam quando você adiciona explicitamente bins de comportamento amplo, como jq, de volta a safeBins. Se você permitir intérpretes explicitamente na lista de permissões, habilite tools.exec.strictInlineEval para que formas de avaliação de código inline ainda exijam uma nova aprovação. Para detalhes completos da política e exemplos, consulte Aprovações de Exec e Safe bins versus lista de permissões.

​
Exemplos

Primeiro plano: 
{ "tool": "exec", "command": "ls -la" }
Segundo plano + consulta: 
{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}
A consulta é para status sob demanda, não para loops de espera. Se a ativação automática ao concluir estiver habilitada, o comando pode ativar 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 (somente CR): 
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
Colar (entre colchetes por 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 somente quando quiser desabilitá-la ou restringi-la a modelos específicos: 
{
  tools: {
    exec: {
      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.5"] },
    },
  },
}
Observações:
  • Disponível apenas para modelos OpenAI/OpenAI Codex.
  • 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 gravações de patch também devem ser bloqueadas.
  • A configuração fica em tools.exec.applyPatch.
  • tools.exec.applyPatch.enabled usa true como padrão; defina como false para desabilitar a ferramenta para modelos OpenAI.
  • tools.exec.applyPatch.workspaceOnly usa true como padrão (contido no workspace). Defina como false somente se você quiser intencionalmente que apply_patch grave/exclua fora do diretório do workspace.

​
Relacionados