Exec Tool — Administrator Guide
Exec approvals are the guardrail for letting a sandboxed agent run commands on a real host (gateway or node). Commands are allowed only when policy + allowlist + optional user approval all agree. Approvals are in addition to tool policy and elevated gating (unless elevated is set to full, which skips approvals). Effective policy is the stricter of tools.exec.* and exec-approvals.json; omitted approvals fields fall back to tools.exec values. When the approvals file is stricter than tools.exec.security, denials name the floor (for example tools.exec.security=full is floored to allowlist by defaults.security in ~/.openclaw/exec-approvals.json), and the agent’s tools panel (tools.catalog execPolicy.warning) shows the same note.
Where it applies
- gateway host → enforced by the
openclawgateway process - node host → enforced by the node runner (macOS companion app or headless node host)
- Gateway-authenticated callers are trusted operators for that gateway.
- Paired nodes extend that trusted operator capability to the node host.
- Exec approvals reduce accidental execution risk; they are not a per-user auth boundary.
- The node host service forwards
system.runto the macOS app over local IPC. - The macOS app enforces approvals + executes the command in UI context.
exec-approvals.json
Approvals live in a local JSON file on the execution host: Location:~/.openclaw/exec-approvals.json
v1 schema (legacy on-disk format, still accepted)
v2 schema (canonical execution model)
The v2 schema is the in-memory shape produced byloadExecApprovalsV2 after migrating a v1 file.
It is a super-set of v1 — the socket, defaults, and per-agent agents fields are preserved
so the gateway’s legacy enforcement surfaces (IPC token, security/ask defaults, per-agent
allowlists) continue to work alongside the new policy engine. The on-disk file is NOT
auto-overwritten; you can author a v2 file directly if you prefer:
policies array is
compiled from v1 agents.<id>.allowlist entries (pattern → executableName: basename(pattern)
when the pattern ends in a leaf executable; glob patterns are preserved). The approvals array is
empty until the gateway binds an approval to a canonical request at runtime.
Runtime hot-reload: the gateway watches this file and applies changes without restart.
Canonical execution model (policy engine)
The exec tool’s host-execution path now runs through a canonical execution model policy engine. The engine is opt-in: when zero policies are loaded (the default), the pipeline is a no-op and the request is allowed (the pre-policy-engine behaviour is preserved). Deny-first enforcement only activates when at least oneCompiledExecutionPolicy is present in the v2 policies array.
Deny-first + source precedence: when multiple policies match the same request, the evaluator
sorts by effect precedence (deny > ask > allow) then by source precedence
(managed > project > user > session > approval). A single deny policy beats any number of allow
policies, regardless of source.
Non-interactive ask: when a policy yields ask and no UI is reachable, the request falls back
to askFallback (default deny) — the same behaviour as the v1 security/ask knobs, but now driven
by the policy engine when policies are loaded.
PATH re-resolution (B17): when a request carries an envDelta that mutates PATH, the gateway
re-resolves the executable against the sanitized env and re-runs the policy pipeline on the
re-resolved request. This closes a path-hijack vector where a mutated PATH could point to a
malicious shadowed binary after the policy check passed.
Audit trail (S8): every policy-evaluation outcome emits a structured audit record via the
infra/exec-audit subsystem logger. Secret-looking values (sk-*, Bearer *,
Authorization: Bearer * spans) are redacted before the record is written. Early-deny sites
(RPC command-id gate, approval-replay binding, PATH re-eval) do not emit audit today — this is a
known-open gap tracked in the plan-fidelity review.
Approval-replay binding (anti-tamper): when an operator approves a request, the gateway binds
the approval to a SHA-256 of the canonical request’s authoritative fields (display text excluded
per ADR 0307). Replaying the approval later compares the presented hash to the stored hash using a
timing-safe comparison — a tampered canonical request (e.g. swapped executable path) is rejected.
Policy knobs
security
deny(default) — block all host exec requests.allowlist— allow only commands matching the allowlist.full— allow everything (equivalent to elevated; use only for trusted operator setups).
ask
off— never prompt.on-miss(default) — prompt only when allowlist does not match.always— prompt on every command.
askFallback
When a prompt is required but no UI is reachable:
deny(default) — block.allowlist— allow only if allowlist matches.full— allow.
preset
tools.exec.preset (global or per-agent) selects a named baseline: readonly (read-only diagnostics pack), minimal (stdin-safe bins only), coding (readonly plus dev tooling), full (no restrictions). Explicit security / ask / safeBins fields override the preset; a per-agent preset overrides the global one. The preset allowlist pack is unioned with the agent’s exec-approvals.json allowlist at evaluation time and is never written to that file; minSecurity flooring against the approvals file still applies. Unknown preset ids are ignored with a logged warning. Full contents: Exec policy presets.
autoAllowSkills
When enabled, executables referenced by known skills are treated as allowlisted on nodes. This uses skills.bins over the Gateway RPC. Intended for trusted operator environments where Gateway and node are in the same trust boundary. Keep false for strict explicit trust.
Global vs per-agent config
Settings can be applied globally (inopenclaw.json) or per-agent (in exec-approvals.json under agents.<agentId>). Per-agent overrides replace the default for that agent. Agent-level exec-approvals.json entries replace defaults; global tools.exec.* config provides the baseline.
In openclaw.json:
exec-approvals.json (runtime override, hot-reloaded):
Allowlists
Allowlists are per agent. Patterns are case-insensitive glob matches against the resolved binary path (basename-only entries are ignored). Examples:~/Projects/**/bin/peekaboo~/.local/bin/*/opt/homebrew/bin/rg
agents.default entries are migrated to agents.main on load.
Approval forwarding to chat channels
Forward exec approval prompts to any chat channel, approved via/approve:
mode:
"session"— deliver to the originating chat session."targets"— deliver to explicit targets."both"— both.
Security posture recommendations
- Prefer allowlists over
security: "full"when possible. - Per-agent allowlists prevent one agent’s approvals from leaking into others.
askkeeps you in the loop while still allowing fast approvals./exec security=fullis a session-level convenience for authorized operators; it does not persist to config.- To hard-block host exec, set
security: "deny"or deny theexectool via tool policy (tools.deny: ["exec"]).
Safe bins configuration
tools.exec.safeBins — stdin-only binaries allowed without allowlist entries. Add your own narrow stream filters here. Custom entries require an explicit profile in tools.exec.safeBinProfiles.
tools.exec.safeBinTrustedDirs — additional trusted directories for safe-bin path checks. System defaults are /bin and /usr/bin. Add package-manager paths (e.g. /opt/homebrew/bin) explicitly.
Do not add interpreter/runtime binaries (python3, node, bash) to safeBins. Use explicit allowlist entries for those.
wednesdayai security audit warns when interpreter/runtime bins appear in safeBins without explicit profiles.
wednesdayai doctor --fix can scaffold missing safeBinProfiles entries.
PATH handling
host=gateway: merges your login-shellPATHinto the exec environment.env.PATHoverrides are rejected.- macOS minimal PATH:
/opt/homebrew/bin,/usr/local/bin,/usr/bin,/bin - Linux minimal PATH:
/usr/local/bin,/usr/bin,/bin
- macOS minimal PATH:
host=sandbox: runssh -lcinside the container;tools.exec.pathPrependapplies after profile sourcing.host=node:env.PATHoverrides are rejected. Configure the node host service environment (systemd/launchd) for additional PATH entries.
tools.exec.pathPrepend prepends directories to PATH for gateway + sandbox exec.
macOS IPC flow
- Unix socket mode
0600, token stored inexec-approvals.json. - Same-UID peer check.
- Challenge/response (nonce + HMAC token + request hash) + short TTL.
Approval flow
When a prompt is required, the gateway broadcastsexec.approval.requested to operator clients. The Control UI and macOS app resolve it via exec.approval.resolve, then the gateway forwards the approved request to the node host.
When approvals are required, the exec tool returns immediately with an approval id. System events (Exec finished / Exec denied) arrive after the node reports the result. If no decision arrives before the timeout (default 120 s), the request is treated as a timeout denial.
Elevated default
agents.defaults.elevatedDefault controls the default elevated level when no /elevated directive is present:
"off"— elevated is off by default."on"— elevated is on by default (host exec when sandboxed)."ask"— ask per command."full"— elevated + skip approvals.
All exec config keys
Non-OpenAI models have no
apply_patch; use the workspace-contained delete tool to remove files.
Control UI
Control UI v2 → Configure → Agents → Tools — per-agent exec policy preset picker (Inherit / Readonly / Minimal / Coding / Full), an effective-policy line (preset, ask, capability), and a warning banner when the exec tool is enabled but the effective policy can run nothing. Control UI v2 → Fleet → Nodes & devices → Exec approvals — edit defaults, per-agent overrides, and allowlists. Pick a scope (Defaults or an agent), tweak policy, add/remove allowlist patterns, then Save. Shows last-used metadata per pattern. Target selector: Gateway (local approvals) or a Node. If a node does not advertise exec approvals yet, edit its local~/.openclaw/exec-approvals.json directly.
CLI: wednesdayai approvals (see Approvals CLI).
Related: Exec Tool (user) · Elevated Mode · Sandboxing (admin)