Use this file to discover all available pages before exploring further.
Exec tool
Run shell commands in the workspace. Supports foreground + background execution via
.
If
is disallowed,
runs synchronously and ignores
/
.
Background sessions are scoped per agent;
only sees sessions from the same agent.
Parameters
Shell command to run.
Working directory for the command.
Key/value environment overrides merged on top of the inherited environment.
Auto-background the command after this delay (ms).
Background the command immediately instead of waiting for `yieldMs`.
Override the configured exec timeout for this call. Set `timeout: 0` only when the command should run without the exec process timeout.
Run in a pseudo-terminal when available. Use for TTY-only CLIs, coding agents, and terminal UIs.
Where to execute. `auto` resolves to `sandbox` when a sandbox runtime is active and `gateway` otherwise.
Enforcement mode for `gateway` / `node` execution.
Approval prompt behavior for `gateway` / `node` execution.
Node id/name when `host=node`.
Request elevated mode — escape the sandbox onto the configured host path. `security=full` is forced only when elevated resolves to `full`.
Notes:
- defaults to : sandbox when sandbox runtime is active for the session, otherwise gateway.
- only accepts , , , or . It is not a hostname selector; hostname-like values are rejected before the command runs.
- is the default routing strategy, not a wildcard. Per-call is allowed from ; per-call is only allowed when no sandbox runtime is active.
- With no extra config, still "just works": no sandbox means it resolves to ; a live sandbox means it stays in the sandbox.
- escapes the sandbox onto the configured host path: by default, or when (or the session default is ). It is only available when elevated access is enabled for the current session/provider.
- / approvals are controlled by
~/.openclaw/exec-approvals.json
- requires a paired node (companion app or headless node host).
- If multiple nodes are available, set or to select one.
- is the only shell-execution path for nodes; the legacy wrapper has been removed.
- applies to foreground, background, , gateway, sandbox, and node execution. If omitted, OpenClaw uses ; explicit disables the exec process timeout for that call.
- On non-Windows hosts, exec uses when set; if is , it prefers (or )
from to avoid fish-incompatible scripts, then falls back to if neither exists.
- On Windows hosts, exec prefers PowerShell 7 () discovery (Program Files, ProgramW6432, then PATH),
then falls back to Windows PowerShell 5.1.
- Host execution (/) rejects and loader overrides (/) to
prevent binary hijacking or injected code.
- OpenClaw sets in the spawned command environment (including PTY and sandbox execution) so shell/profile rules can detect exec-tool context.
- is blocked from because it is an interactive channel-auth flow; run it in a terminal on the gateway host, or use the channel-native login tool from chat when one exists.
- Important: sandboxing is off by default. If sandboxing is off, implicit
resolves to . Explicit still fails closed instead of silently
running on the gateway host. Enable sandboxing or use with approvals.
- Script preflight checks (for common Python/Node shell-syntax mistakes) only inspect files inside the
effective boundary. If a script path resolves outside , preflight is skipped for
that file.
- For long-running work that starts now, start it once and rely on automatic
completion wake when it is enabled and the command emits output or fails.
Use for logs, status, input, or intervention; do not emulate
scheduling with sleep loops, timeout loops, or repeated polling.
- For work that should happen later or on a schedule, use cron instead of
sleep/delay patterns.
Config
- (default: true): when true, backgrounded exec sessions enqueue a system event and request a heartbeat on exit.
tools.exec.approvalRunningNoticeMs
- (default: 1800): default per-command exec timeout in seconds. Per-call overrides it; per-call disables the exec process timeout.
- (default: ; resolves to when sandbox runtime is active, otherwise)
- (default: for sandbox, for gateway + node when unset)
- (default: )
- No-approval host exec is the default for gateway + node. If you want approvals/allowlist behavior, tighten both and the host
~/.openclaw/exec-approvals.json
- YOLO comes from the host-policy defaults (, ), not from . If you want to force gateway or node routing, set or use .
- In plus mode, host exec follows the configured policy directly; there is no extra heuristic command-obfuscation prefilter or script-preflight rejection layer.
- (default: unset)
tools.exec.strictInlineEval
- : list of directories to prepend to for exec runs (gateway + sandbox only).
- : stdin-only safe binaries that can run without explicit allowlist entries. For behavior details, see Safe bins.
tools.exec.safeBinTrustedDirs
tools.exec.safeBinProfiles
Example:
{
tools: {
exec: {
pathPrepend: ["~/bin", "/opt/oss/bin"],
},
},
}
PATH handling
- : merges your login-shell into the exec environment. overrides are
rejected for host execution. The daemon itself still runs with a minimal :
- : runs (login shell) inside the container, so may reset .
OpenClaw prepends after profile sourcing via an internal env var (no shell interpolation);
applies here too.
- : only non-blocked env overrides you pass are sent to the node. overrides are
rejected for host execution and ignored by node hosts. If you need additional PATH entries on a node,
configure the node host service environment (systemd/launchd) or install tools in standard locations.
Per-agent node binding (use the agent list index in config):
openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
Control UI: the Nodes tab includes a small “Exec node binding” panel for the same settings.
Session overrides ()
Use
to set
per-session defaults for
,
,
, and
.
Send
with no arguments to show the current values.
Example:
/exec host=auto security=allowlist ask=on-miss node=mac-1
Authorization model
is only honored for
authorized senders (channel allowlists/pairing plus
).
It updates
session state only and does not write config. To hard-disable exec, deny it via tool
policy (
or per-agent). Host approvals still apply unless you explicitly set
and
.
Exec approvals (companion app / node host)
Sandboxed agents can require per-request approval before
runs on the gateway or node host.
See
Exec approvals for the policy, allowlist, and UI flow.
When approvals are required, the exec tool returns immediately with
status: "approval-pending"
and an approval id. Once approved (or denied / timed out),
the Gateway emits system events (
/
). If the command is still
running after
tools.exec.approvalRunningNoticeMs
, a single
notice is emitted.
On channels with native approval cards/buttons, the agent should rely on that
native UI first and only include a manual
command when the tool
result explicitly says chat approvals are unavailable or manual approval is the
only path.
Allowlist + safe bins
Manual allowlist enforcement matches resolved binary path globs and bare command-name
globs. Bare names match only commands invoked through PATH, so
can match
when the command is
, but not
or
.
When
, shell commands are auto-allowed only if every pipeline
segment is allowlisted or a safe bin. Chaining (
,
,
) and redirections
are rejected in allowlist mode unless every top-level segment satisfies the
allowlist (including safe bins). Redirections remain unsupported.
Durable
trust does not bypass that rule: a chained command still requires every
top-level segment to match.
is a separate convenience path in exec approvals. It is not the same as
manual path allowlist entries. For strict explicit trust, keep
disabled.
Use the two controls for different jobs:
- : small, stdin-only stream filters.
tools.exec.safeBinTrustedDirs
tools.exec.safeBinProfiles
- allowlist: explicit trust for executable paths.
Do not treat
as a generic allowlist, and do not add interpreter/runtime binaries (for example
,
,
,
). If you need those, use explicit allowlist entries and keep approval prompts enabled.
warns when interpreter/runtime
entries are missing explicit profiles, and
can scaffold missing custom
entries.
and
also warn when you explicitly add broad-behavior bins such as
back into
.
If you explicitly allowlist interpreters, enable
tools.exec.strictInlineEval
so inline code-eval forms still require a fresh approval.
For full policy details and examples, see Exec approvals and Safe bins versus allowlist.
Examples
Foreground:
{ "tool": "exec", "command": "ls -la" }
Background + poll:
{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}
Polling is for on-demand status, not waiting loops. If automatic completion wake
is enabled, the command can wake the session when it emits output or fails.
Send keys (tmux-style):
{"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"]}
Submit (send CR only):
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
Paste (bracketed by default):
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
apply_patch
is a subtool of
for structured multi-file edits.
It is enabled by default for OpenAI and OpenAI Codex models. Use config only
when you want to disable it or restrict it to specific models:
{
tools: {
exec: {
applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.5"] },
},
},
}
Notes:
- Only available for OpenAI/OpenAI Codex models.
- Tool policy still applies; implicitly allows .
- Config lives under .
tools.exec.applyPatch.enabled
tools.exec.applyPatch.workspaceOnly
Related