Skip to main content

Exec Tool — User Guide

Run shell commands from your agent session. Supports foreground and background execution.

Parameters

  • command (required)
  • workdir (defaults to cwd)
  • env (key/value overrides)
  • yieldMs (default 10000): auto-background after this delay
  • background (bool): background immediately
  • timeout (seconds, default 1800): kill on expiry
  • pty (bool): run in a pseudo-terminal (use for TTY-only CLIs, coding agents, terminal UIs)
  • host (sandbox | gateway | node): where to execute
  • security (deny | allowlist | full): enforcement mode for gateway/node
  • ask (off | on-miss | always): approval prompts for gateway/node
  • node (string): node id/name for host=node
  • elevated (bool): request elevated host execution when sandboxed

When exec asks for approval

When exec runs on the gateway or a node host, it goes through the approval gate. Depending on your policy:
  • deny — host exec is blocked entirely.
  • allowlist — approved only if the command matches an allowlisted path.
  • on-miss — you get a prompt when no allowlist entry matches.
  • always — you get a prompt for every command.
When a prompt fires, you see the command, cwd, agent id, and resolved binary path. You can:
  • Allow once — run now
  • Always allow — add to allowlist and run
  • Deny — block this command
If no UI is available to respond, the request falls back (usually to deny).

Policy engine (new)

Behind the scenes, the approval gate now runs through a policy engine that evaluates deny/ask/allow rules before deciding whether to prompt you. The engine is opt-in: if you have not authored any v2 policies in ~/.openclaw/exec-approvals.json, the engine is a no-op and the existing security/ask/allowlist behaviour you are used to is unchanged. When your operator adds policies (deny rules for dangerous commands, allow rules for trusted executables), the engine applies them with deny-first precedence — a single deny rule beats any number of allow rules.

Using exec presets

Instead of hand-writing security / ask / safeBins / allowlist entries, set a named preset on the agent:
  • readonly — read-only diagnostics: ls, cat, df, ps, grep, sort and friends, plus stdin filters. Good default for non-technical agents.
  • minimal — only the 7 default stdin-safe bins (jq, cut, uniq, head, tail, tr, wc).
  • coding — readonly plus git, node, npm, pnpm, python3, rg.
  • full — no restrictions (security: "full", ask: "off").
When a command falls outside what the preset allows, what happens depends on the policy: with the default ask: "on-miss" (and security: "allowlist") you get an approval prompt rather than a silent failure; with security: "deny", ask: "off", or when no approval UI is attached, the command is denied or resolved via the configured ask fallback instead of prompting. Explicit security / ask / safeBins fields you set yourself override the preset. The Agents → Tools panel in the Control UI (v2: Configure → Agents → Tools) shows the effective policy and offers the same picker. See Exec policy presets for the full pack contents.

Giving an agent full exec permission

Prefer a preset (above) over raw full where possible. To skip approval prompts entirely for an agent, set security: "full" and ask: "off":
Or just for a specific agent:

Trusting specific commands

Two ways to allow commands without full trust:

Safe bins (narrow stdin filters)

Add small stream-filter utilities to tools.exec.safeBins. These run without allowlist entries but only accept stdin — no file arguments.
Default safe bins: jq, cut, uniq, head, tail, tr, wc. Do not add interpreter/runtime binaries (python3, node, bash) to safeBins — use explicit allowlist entries for those.

Allowlist (exec-approvals.json)

Add patterns to ~/.openclaw/exec-approvals.json under your agent’s allowlist. Patterns are case-insensitive globs matching the resolved binary path:
Or use the Control UI v2 → Fleet → Nodes & devices → Exec approvals panel to add patterns interactively.

Per-session overrides (/exec)

Change exec behavior for your current session without touching config:
Send /exec with no arguments to see current session values. Session overrides reset when the session ends; they don’t persist to config.

System events

Exec lifecycle appears as system messages in your session:
  • Exec running — emitted if the command runs longer than approvalRunningNoticeMs (default 10 s)
  • Exec finished — command completed
  • Exec denied — blocked by policy or explicit denial

Quick config reference

Examples

Foreground:
Background + poll:
Related: Exec Approvals (admin) · Sandboxing