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

Exec approvals

Exec approvals are the companion app / node host guardrail for letting a sandboxed agent run commands on a real host (

text

gateway

text

node

). A safety interlock: commands are allowed only when policy + allowlist + (optional) user approval all agree. Exec approvals stack on top of tool policy and elevated gating (unless elevated is set to

text

full

, which skips approvals).

note

Effective policy is the **stricter** of `tools.exec.*` and approvals defaults; if an approvals field is omitted, the `tools.exec` value is used. Host exec also uses local approvals state on that machine — a host-local `ask: "always"` in `~/.openclaw/exec-approvals.json` keeps prompting even if session or config defaults request `ask: "on-miss"`.

Inspecting the effective policy

Command	What it shows
text `openclaw approvals get` / text `--gateway` / text `--node <id\|name\|ip>`	Requested policy, host policy sources, and the effective result.
text `openclaw exec-policy show`	Local-machine merged view.
text `openclaw exec-policy set` / text `preset`	Synchronize the local requested policy with the local host approvals file in one step.

When a local scope requests

text

host=node

text

exec-policy show

reports that scope as node-managed at runtime instead of pretending the local approvals file is the source of truth.

If the companion app UI is not available, any request that would normally prompt is resolved by the ask fallback (default:

text

deny

tip

Native chat approval clients can seed channel-specific affordances on the pending approval message. For example, Matrix seeds reaction shortcuts (`✅` allow once, `❌` deny, `♾️` allow always) while still leaving `/approve ...` commands in the message as a fallback.

Where it applies

Exec approvals are enforced locally on the execution host:

Gateway host →
text
openclaw
process on the gateway machine.
Node host → node runner (macOS companion app or headless node host).

Trust model

Gateway-authenticated callers are trusted operators for that Gateway.
Paired nodes extend that trusted operator capability onto the node host.
Exec approvals reduce accidental execution risk, but are not a per-user auth boundary.
Approved node-host runs bind canonical execution context: canonical cwd, exact argv, env binding when present, and pinned executable path when applicable.
For shell scripts and direct interpreter/runtime file invocations, OpenClaw also tries to bind one concrete local file operand. If that bound file changes after approval but before execution, the run is denied instead of executing drifted content.
File binding is intentionally best-effort, not a complete semantic model of every interpreter/runtime loader path. If approval mode cannot identify exactly one concrete local file to bind, it refuses to mint an approval-backed run instead of pretending full coverage.

macOS split

The node host service forwards
text
system.run
to the macOS app over local IPC.
The macOS app enforces approvals and executes the command in UI context.

Settings and storage

Approvals live in a local JSON file on the execution host:


text
~/.openclaw/exec-approvals.json

Example schema:


json
{
  "version": 1,
  "socket": {
    "path": "~/.openclaw/exec-approvals.sock",
    "token": "base64url-token"
  },
  "defaults": {
    "security": "deny",
    "ask": "on-miss",
    "askFallback": "deny",
    "autoAllowSkills": false
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "askFallback": "deny",
      "autoAllowSkills": true,
      "allowlist": [
        {
          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
          "pattern": "~/Projects/**/bin/rg",
          "source": "allow-always",
          "commandText": "rg -n TODO",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg -n TODO",
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        }
      ]
    }
  }
}

Policy knobs

text
`exec.security`

* `deny` — block all host exec requests. * `allowlist` — allow only allowlisted commands. * `full` — allow everything (equivalent to elevated).

text
`exec.ask`

* `off` — never prompt. * `on-miss` — prompt only when the allowlist does not match. * `always` — prompt on every command. `allow-always` durable trust does **not** suppress prompts when effective ask mode is `always`.

text
`askFallback`

Resolution when a prompt is required but no UI is reachable.

text
deny
— block.
text
allowlist
— allow only if allowlist matches.
text
full
— allow.

text
`tools.exec.strictInlineEval`

When `true`, OpenClaw treats inline code-eval forms as approval-only even if the interpreter binary itself is allowlisted. Defense-in-depth for interpreter loaders that do not map cleanly to one stable file operand.

Examples that strict mode catches:

text
python -c
text
node -e
,
text
node --eval
,
text
node -p
text
ruby -e
text
perl -e
,
text
perl -E
text
php -r
text
lua -e
text
osascript -e

In strict mode these commands still need explicit approval, and

text

allow-always

does not persist new allowlist entries for them automatically.

YOLO mode (no-approval)

If you want host exec to run without approval prompts, you must open both policy layers — requested exec policy in OpenClaw config (

text

tools.exec.*

) and host-local approvals policy in

text

~/.openclaw/exec-approvals.json

YOLO is the default host behavior unless you tighten it explicitly:

Layer	YOLO setting
text `tools.exec.security`	text `full` on text `gateway` / text `node`
text `tools.exec.ask`	text `off`
Host text `askFallback`	text `full`

warning

**Important distinctions:**

text
tools.exec.host=auto
chooses where exec runs: sandbox when available, otherwise gateway.
YOLO chooses how host exec is approved:
text
security=full
plus
text
ask=off
.
In YOLO mode, OpenClaw does not add a separate heuristic command-obfuscation approval gate or script-preflight rejection layer on top of the configured host exec policy.
text
auto
does not make gateway routing a free override from a sandboxed session. A per-call
text
host=node
request is allowed from
text
auto
;
text
host=gateway
is only allowed from
text
auto
when no sandbox runtime is active. For a stable non-auto default, set
text
tools.exec.host
or use
text
/exec host=...
explicitly.

CLI-backed providers that expose their own noninteractive permission mode can follow this policy. Claude CLI adds

text

--permission-mode bypassPermissions

when OpenClaw's requested exec policy is YOLO. Override that backend behavior with explicit Claude args under

text

agents.defaults.cliBackends.claude-cli.args

text

resumeArgs

— for example

text

--permission-mode default

text

acceptEdits

, or

text

bypassPermissions

If you want a more conservative setup, tighten either layer back to

text

allowlist

text

on-miss

text

deny

Persistent gateway-host "never prompt" setup

Set the requested config policy

```bash} openclaw config set tools.exec.host gateway openclaw config set tools.exec.security full openclaw config set tools.exec.ask off openclaw gateway restart ```

Match the host approvals file

```bash} openclaw approvals set --stdin <<'EOF' { version: 1, defaults: { security: "full", ask: "off", askFallback: "full" } } EOF ```

Local shortcut


bash
openclaw exec-policy preset yolo

That local shortcut updates both:

Local
text
tools.exec.host/security/ask
.
Local
text
~/.openclaw/exec-approvals.json
defaults.

It is intentionally local-only. To change gateway-host or node-host approvals remotely, use

text

openclaw approvals set --gateway

text

openclaw approvals set --node <id|name|ip>

Node host

For a node host, apply the same approvals file on that node instead:


bash
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
{
  version: 1,
  defaults: {
    security: "full",
    ask: "off",
    askFallback: "full"
  }
}
EOF

note

**Local-only limitations:**

text
openclaw exec-policy
does not synchronize node approvals.
text
openclaw exec-policy set --host node
is rejected.
Node exec approvals are fetched from the node at runtime, so node-targeted updates must use
text
openclaw approvals --node ...
.

Session-only shortcut

text
/exec security=full ask=off
changes only the current session.
text
/elevated full
is a break-glass shortcut that also skips exec approvals for that session.

If the host approvals file stays stricter than config, the stricter host policy still wins.

Allowlist (per agent)

Allowlists are per agent. If multiple agents exist, switch which agent you are editing in the macOS app. Patterns are glob matches.

Patterns can be resolved binary path globs or bare command-name globs. Bare names match only commands invoked through

text

PATH

, so

text

rg

can match

text

/opt/homebrew/bin/rg

when the command is

text

rg

, but not

text

./rg

text

/tmp/rg

. Use a path glob when you want to trust one specific binary location.

Legacy

text

agents.default

entries are migrated to

text

agents.main

on load. Shell chains such as

text

echo ok && pwd

still need every top-level segment to satisfy allowlist rules.

Examples:

text
rg
text
~/Projects/**/bin/peekaboo
text
~/.local/bin/*
text
/opt/homebrew/bin/rg

Each allowlist entry tracks:

Field	Meaning
text `id`	Stable UUID used for UI identity
text `lastUsedAt`	Last-used timestamp
text `lastUsedCommand`	Last command that matched
text `lastResolvedPath`	Last resolved binary path

Auto-allow skill CLIs

When Auto-allow skill CLIs is enabled, executables referenced by known skills are treated as allowlisted on nodes (macOS node or headless node host). This uses

text

skills.bins

over the Gateway RPC to fetch the skill bin list. Disable this if you want strict manual allowlists.

warning

* This is an **implicit convenience allowlist**, separate from manual path allowlist entries. * It is intended for trusted operator environments where Gateway and node are in the same trust boundary. * If you require strict explicit trust, keep `autoAllowSkills: false` and use manual path allowlist entries only.

Safe bins and approval forwarding

For safe bins (the stdin-only fast-path), interpreter binding details, and how to forward approval prompts to Slack/Discord/Telegram (or run them as native approval clients), see Exec approvals — advanced.

Control UI editing

Use the Control UI → Nodes → Exec approvals card to edit defaults, per-agent overrides, and allowlists. Pick a scope (Defaults or an agent), tweak the policy, add/remove allowlist patterns, then Save. The UI shows last-used metadata per pattern so you can keep the list tidy.

The target selector chooses Gateway (local approvals) or a Node. Nodes must advertise

text

system.execApprovals.get/set

(macOS app or headless node host). If a node does not advertise exec approvals yet, edit its local

text

~/.openclaw/exec-approvals.json

directly.

CLI:

text

openclaw approvals

supports gateway or node editing — see Approvals CLI.

Approval flow

When a prompt is required, the gateway broadcasts

text

exec.approval.requested

to operator clients. The Control UI and macOS app resolve it via

text

exec.approval.resolve

, then the gateway forwards the approved request to the node host.

For

text

host=node

, approval requests include a canonical

text

systemRunPlan

payload. The gateway uses that plan as the authoritative command/cwd/session context when forwarding approved

text

system.run

requests.

That matters for async approval latency:

The node exec path prepares one canonical plan up front.
The approval record stores that plan and its binding metadata.
Once approved, the final forwarded
text
system.run
call reuses the stored plan instead of trusting later caller edits.
If the caller changes
text
command
,
text
rawCommand
,
text
cwd
,
text
agentId
, or
text
sessionKey
after the approval request was created, the gateway rejects the forwarded run as an approval mismatch.

System events

Exec lifecycle is surfaced as system messages:

text
Exec running
(only if the command exceeds the running notice threshold).
text
Exec finished
.
text
Exec denied
.

These are posted to the agent's session after the node reports the event. Gateway-host exec approvals emit the same lifecycle events when the command finishes (and optionally when running longer than the threshold). Approval-gated execs reuse the approval id as the

text

runId

in these messages for easy correlation.

Denied approval behavior

When an async exec approval is denied, OpenClaw prevents the agent from reusing output from any earlier run of the same command in the session. The denial reason is passed with explicit guidance that no command output is available, which stops the agent from claiming there is new output or repeating the denied command with stale results from a prior successful run.

Implications

text
full
is powerful; prefer allowlists when possible.
text
ask
keeps you in the loop while still allowing fast approvals.
Per-agent allowlists prevent one agent's approvals from leaking into others.
Approvals only apply to host exec requests from authorized senders. Unauthorized senders cannot issue
text
/exec
.
text
/exec security=full
is a session-level convenience for authorized operators and skips approvals by design. To hard-block host exec, set approvals security to
text
deny
or deny the
text
exec
tool via tool policy.

Exec approvals — advanced

Safe bins, interpreter binding, and approval forwarding to chat.

Exec tool

Shell command execution tool.

Elevated mode

Break-glass path that also skips approvals.

Sandboxing

Sandbox modes and workspace access.

Security

Security model and hardening.

Sandbox vs tool policy vs elevated

When to reach for each control.

Skills

Skill-backed auto-allow behavior.

OpenClaw Docs

Exec approvals

note

Inspecting the effective policy

tip

Where it applies

Trust model

macOS split

Settings and storage

Policy knobs

text
`exec.security`

text
`exec.ask`

text
`askFallback`

text
`tools.exec.strictInlineEval`

YOLO mode (no-approval)

warning

Persistent gateway-host "never prompt" setup

Set the requested config policy

Match the host approvals file

Local shortcut

Node host

note

Session-only shortcut

Allowlist (per agent)

Auto-allow skill CLIs

warning

Safe bins and approval forwarding

Control UI editing

Approval flow

System events

Denied approval behavior

Implications

Related

Exec approvals — advanced

Exec tool

Elevated mode

Sandboxing

Security

Sandbox vs tool policy vs elevated

Skills

OpenClaw Docs

Exec approvals

note

Inspecting the effective policy

tip

Where it applies

Trust model

macOS split

Settings and storage

Policy knobs

textCopyexec.security

textCopyexec.ask

textCopyaskFallback

textCopytools.exec.strictInlineEval

YOLO mode (no-approval)

warning

Persistent gateway-host "never prompt" setup

Set the requested config policy

Match the host approvals file

Local shortcut

Node host

note

Session-only shortcut

Allowlist (per agent)

Auto-allow skill CLIs

warning

Safe bins and approval forwarding

Control UI editing

Approval flow

System events

Denied approval behavior

Implications

Related

Exec approvals — advanced

Exec tool

Elevated mode

Sandboxing

Security

Sandbox vs tool policy vs elevated

Skills

text
`exec.security`

text
`exec.ask`

text
`askFallback`

text
`tools.exec.strictInlineEval`