> ## Documentation Index > Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt > Use this file to discover all available pages before exploring further. # Ferramenta Exec # Ferramenta Exec Execute comandos de shell no workspace. Suporta 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`. As sessões em segundo plano são delimitadas por agente; `process` só vê sessões do mesmo agente. ## Parâmetros * `command` (obrigatório) * `workdir` (padrão: cwd) * `env` (substituições chave/valor) * `yieldMs` (padrão 10000): coloca automaticamente em segundo plano após atraso * `background` (bool): segundo plano imediatamente * `timeout` (segundos, padrão 1800): encerra ao expirar * `pty` (bool): executa em um pseudo-terminal quando disponível (CLIs somente TTY, agentes de código, UIs de terminal) * `host` (`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 (host do Gateway); `security=full` só é forçado quando o elevado resolve para `full` Notas: * `host` tem como padrão `sandbox`. * `elevated` é ignorado quando o sandboxing está desativado (exec já roda no host). * As aprovações `gateway`/`node` são controladas por `~/.openclaw/exec-approvals.json`. * `node` requer um nó pareado (aplicativo complementar ou host de nó headless). * Se vários nós estiverem disponíveis, defina `exec.node` ou `tools.exec.node` para selecionar um. * Em hosts não Windows, o exec usa `SHELL` quando definido; se `SHELL` for `fish`, ele prefere `bash` (ou `sh`) de `PATH` para evitar scripts incompatíveis com fish, depois faz fallback para `SHELL` se nenhum existir. * A execução no host (`gateway`/`node`) rejeita `env.PATH` e substituições de loader (`LD_*`/`DYLD_*`) para evitar sequestro de binários ou código injetado. * Importante: o sandboxing está **desativado por padrão**. Se o sandboxing estiver desativado, `host=sandbox` executa diretamente no host do gateway (sem contêiner) e **não requer aprovações**. Para exigir aprovações, execute com `host=gateway` e configure as aprovações do exec (ou habilite o sandboxing). ## Configuração * `tools.exec.notifyOnExit` (padrão: true): quando true, sessões de exec em segundo plano enfileiram um evento de sistema e solicitam um heartbeat ao sair. * `tools.exec.approvalRunningNoticeMs` (padrão: 10000): emite um único aviso “em execução” quando um exec com aprovação demora mais que isso (0 desativa). * `tools.exec.host` (padrão: `sandbox`) * `tools.exec.security` (padrão: `deny` para sandbox, `allowlist` para gateway + nó quando não definido) * `tools.exec.ask` (padrão: `on-miss`) * `tools.exec.node` (padrão: não definido) * `tools.exec.pathPrepend`: lista de diretórios a serem adicionados antes de `PATH` para execuções do exec. * `tools.exec.safeBins`: binários seguros somente stdin que podem rodar sem entradas explícitas na allowlist. Exemplo: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { tools: { exec: { pathPrepend: ["~/bin", "/opt/oss/bin"], }, }, } ``` ### Manipulação de PATH * `host=gateway`: mescla seu `PATH` do shell de login no ambiente do exec. Substituições de `env.PATH` são rejeitadas para execução no host. O daemon em si ainda roda 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 adiciona `env.PATH` antes após o carregamento de perfil via uma variável de ambiente interna (sem interpolação de shell); `tools.exec.pathPrepend` também se aplica aqui. * `host=node`: somente substituições de env não bloqueadas que você passar são enviadas ao nó. Substituições de `env.PATH` são rejeitadas para execução no host. Se você precisar de entradas adicionais no PATH em um nó, configure o ambiente do serviço do host do nó (systemd/launchd) ou instale ferramentas em locais padrão. Vinculação de nó por agente (use o índice da lista de agentes na configuração): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 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=gateway security=allowlist ask=on-miss node=mac-1 ``` ## Modelo de autorização `/exec` só é respeitado para **remetentes autorizados** (allowlists de canal/pareamento mais `commands.useAccessGroups`). Ele atualiza **apenas o estado da sessão** e não grava configuração. Para desativar o exec de forma definitiva, negue-o via política de ferramentas (`tools.deny: ["exec"]` ou por agente). Aprovações no host ainda se aplicam, a menos que você defina explicitamente `security=full` e `ask=off`. ## Aprovações do Exec (aplicativo complementar / host do nó) Agentes em sandbox podem exigir aprovação por solicitação antes que `exec` execute no gateway ou no host do nó. Veja [Exec approvals](/tools/exec-approvals) 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. Após aprovado (ou negado / expirado), o Gateway emite eventos de sistema (`Exec finished` / `Exec denied`). Se o comando ainda estiver em execução após `tools.exec.approvalRunningNoticeMs`, um único aviso `Exec running` é emitido. ## Allowlist + bins seguros A aplicação da allowlist corresponde **apenas a caminhos de binários resolvidos** (sem correspondência por basename). Quando `security=allowlist`, comandos de shell são auto-permitidos somente se cada segmento do pipeline estiver na allowlist ou for um bin seguro. Encadeamentos (`;`, `&&`, `||`) e redirecionamentos são rejeitados no modo allowlist, a menos que cada segmento de nível superior satisfaça a allowlist (incluindo safe bins). Redirecionamentos continuam não suportados. ## Exemplos Primeiro plano: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "tool": "exec", "command": "ls -la" } ``` Segundo plano + polling: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} {"tool":"exec","command":"npm run build","yieldMs":1000} {"tool":"process","action":"poll","sessionId":""} ``` Enviar teclas (estilo tmux): ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} {"tool":"process","action":"send-keys","sessionId":"","keys":["Enter"]} {"tool":"process","action":"send-keys","sessionId":"","keys":["C-c"]} {"tool":"process","action":"send-keys","sessionId":"","keys":["Up","Up","Enter"]} ``` Enviar (somente CR): ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "tool": "process", "action": "submit", "sessionId": "" } ``` Colar (pulverizado por padrão): ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "tool": "process", "action": "paste", "sessionId": "", "text": "line1\nline2\n" } ``` ## apply\_patch (experimental) `apply_patch` é um subtool de `exec` para edições estruturadas em vários arquivos. Habilite explicitamente: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { tools: { exec: { applyPatch: { enabled: true, allowModels: ["gpt-5.2"] }, }, }, } ``` Notas: * Disponível apenas para modelos OpenAI/OpenAI Codex. * A política de ferramentas ainda se aplica; `allow: ["exec"]` permite implicitamente `apply_patch`. * A configuração fica em `tools.exec.applyPatch`. * `tools.exec.applyPatch.workspaceOnly` é definido como `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.