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 delaybackground(bool): background immediatelytimeout(seconds, default 1800): kill on expirypty(bool): run in a pseudo-terminal (use for TTY-only CLIs, coding agents, terminal UIs)host(sandbox | gateway | node): where to executesecurity(deny | allowlist | full): enforcement mode forgateway/nodeask(off | on-miss | always): approval prompts forgateway/nodenode(string): node id/name forhost=nodeelevated(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.
- Allow once — run now
- Always allow — add to allowlist and run
- Deny — block this command
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-writingsecurity / ask / safeBins / allowlist entries, set a named preset on the agent:
- readonly — read-only diagnostics:
ls,cat,df,ps,grep,sortand 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").
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 rawfull where possible. To skip approval prompts entirely for an agent, set security: "full" and ask: "off":
Trusting specific commands
Two ways to allow commands without full trust:Safe bins (narrow stdin filters)
Add small stream-filter utilities totools.exec.safeBins. These run without allowlist entries but only accept stdin — no file arguments.
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:
Per-session overrides (/exec)
Change exec behavior for your current session without touching config:/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 thanapprovalRunningNoticeMs(default 10 s)Exec finished— command completedExec denied— blocked by policy or explicit denial