Skip to main content

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 openclaw gateway process
  • node host → enforced by the 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 to the node host.
  • Exec approvals reduce accidental execution risk; they are not a per-user auth boundary.
macOS split:
  • The node host service forwards system.run to 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 by loadExecApprovalsV2 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:
Migration behaviour: v1 is read into v2 in memory on every load. The 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 one CompiledExecutionPolicy 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 (in openclaw.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:
In 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
Each entry tracks: stable UUID, last used timestamp, last used command, last resolved path. The Control UI shows this metadata to keep the list tidy. Legacy 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.
Reply in chat:

Security posture recommendations

  • Prefer allowlists over security: "full" when possible.
  • Per-agent allowlists prevent one agent’s approvals from leaking into others.
  • ask keeps you in the loop while still allowing fast approvals.
  • /exec security=full is a session-level convenience for authorized operators; it does not persist to config.
  • To hard-block host exec, set security: "deny" or deny the exec tool 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-shell PATH into the exec environment. env.PATH overrides are rejected.
    • macOS minimal PATH: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
    • Linux minimal PATH: /usr/local/bin, /usr/bin, /bin
  • host=sandbox: runs sh -lc inside the container; tools.exec.pathPrepend applies after profile sourcing.
  • host=node: env.PATH overrides 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

Security:
  • Unix socket mode 0600, token stored in exec-approvals.json.
  • Same-UID peer check.
  • Challenge/response (nonce + HMAC token + request hash) + short TTL.

Approval flow

When a prompt is required, the gateway broadcasts exec.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)