openclaw/docs/tools/exec-approvals.md

summary	read_when	title	sidebarTitle
Host exec approvals: policy knobs, allowlists, and the YOLO/strict workflow	Configuring exec approvals or allowlists Inspecting or revoking durable MCP tool grants Implementing exec approval UX in the macOS app Reviewing host-execution approval prompts from a sandboxed agent and their implications	Exec approvals	Exec approvals

Exec approvals are the companion app / node host guardrail for letting a sandboxed agent run commands on a real host (gateway or node). Commands run only when policy + allowlist + (optional) user approval all agree. Approvals stack on top of tool policy and elevated gating. Gateway full-session and qualifying elevated-full paths can skip host approval evaluation. See the strict inline-eval exceptions.

For a mode-first overview of deny, allowlist, ask, auto, full, Codex Guardian mapping, and ACPX harness permissions, see Permission modes.

Outside the full-permission Gateway session exception described below, effective policy is the **stricter** of `tools.exec.*` and approvals defaults: approvals can only tighten config-derived security/ask, never loosen them. 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 the execution host approvals document keeps prompting even if session or config defaults request `ask: "on-miss"`. An unconfigured node uses the same `full` / `off` baseline as the Gateway. Node execution still checks the target policy before dispatch: caller `allowlist` / `off` denies an unmatched command, and target `ask: "always"` requires approval even when the caller requests `full` / `off`.

Where it applies

Exec approvals are enforced locally on the execution host:

• Gateway host -> openclaw process on the gateway machine.
• Node host -> node runner (macOS companion app or headless node host).

The claude-cli backend also checks native Bash commands against the agent's exec allowlist when ask: "on-miss". This authorizes command arguments while Claude Code owns execution. It does not provide OpenClaw sandboxing. See Native Bash and the exec allowlist for matching, prompting, and binding restrictions.

Trust model

• Gateway-authenticated callers are trusted operators for that Gateway.
• Paired nodes extend that trusted operator capability onto the node host.
• Approvals reduce accidental execution risk, but are not a per-user auth boundary or filesystem read-only policy.
• Once approved, a command can mutate files according to the selected host or sandbox filesystem permissions.
• Approved node-host runs bind the exact execution context: cwd, exact argv, env binding when present, and pinned executable path when applicable.
• Gateway approval-backed commands bind every resolved command-segment executable before review and re-check it before launch. Node hosts capture these identities during local policy evaluation and re-check before dispatch. This does not cover inner shell executables across a remote human approval wait. Protected executables use resolved real-path identity only. Writable executables also use a content hash. A changed resolution during the bound window, including a new executable earlier on PATH, denies the run. Identity-only binding preserves otherwise eligible allow-always decisions. See Interpreter/runtime commands.
• For shell scripts and direct interpreter/runtime file invocations, OpenClaw also tries to bind one concrete local file operand. If that file changes after approval but before execution, the run is denied instead of executing drifted content.
• File binding is best-effort, not a complete model of every interpreter/runtime loader path. If exactly one concrete local file cannot be identified, OpenClaw refuses to mint an approval-backed run rather than pretend full coverage.

macOS split

OpenClaw keeps its native macOS human-approval panels out of Peekaboo screen snapshots and refuses native computer input while approvals are pending, including the menu-bar queue. Human approval controls remain usable. These native guards do not cover browser automation, the separate CUA driver, or third-party automation on the same machine. Do not combine ask-mode exec with unrestricted computer use for a model you do not trust. This is hardening, not an isolation boundary.

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

Inspecting the effective policy

Command	What it shows
openclaw approvals get / --gateway / --node <id|name|ip>	Requested policy, host policy sources, and the effective result.
openclaw exec-policy show	Terminal tool policies and local command approvals; add --session <key> for a session tool preview.
openclaw exec-policy set / preset	Synchronize the local requested policy with the local host approvals document in one step.

Per-session `/exec` overrides are not included. Run `/exec` in the relevant session to inspect its current defaults. See [session overrides](/tools/exec#session-overrides-%2Fexec).

Tool availability and command approvals are separate: a messaging tool profile can exclude exec and process even when approvals permit commands. exec-policy show explains local exclusions offline and identifies the policy source. --session <key> previews tools from saved session settings. Inclusion does not guarantee execution, and absence does not prove a tool is disabled. Verify execution in a run; command approvals still apply. Use --agent <id> to select an agent and --verbose for all approval scopes.

Full CLI reference (flags, JSON output, allowlist add/remove): Approvals CLI.

When a local scope requests host=node, exec-policy show reports that scope as node-managed at runtime instead of treating the local approvals file as 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: deny).

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

For native chat approval surfaces, a node exec waits for the decision within the originating tool call and returns the command output there. Closing or cancelling that turn invalidates its pending authority. A late approval cannot restart it. A typed SYSTEM_RUN_DENIED result means the node rejected execution, not that the command may have run.

Settings and storage

Approval policy lives in the selected shared state database on the execution host. For SQLite, OPENCLAW_STATE_DIR selects the state directory; otherwise the default OpenClaw state directory is used:

$OPENCLAW_STATE_DIR/state/openclaw.sqlite#exec_approvals_config
# otherwise
~/.openclaw/state/openclaw.sqlite#exec_approvals_config

The #exec_approvals_config suffix is a display locator for the singleton row, not part of the database filename. With PostgreSQL selected, that row lives in the selected PostgreSQL database. The local state/openclaw.sqlite is only the engine anchor and contains no approval policy. The row keeps the JSON document shown below as its authoritative value.

The macOS app reads and edits this policy through bounded operations in the local OpenClaw CLI on both engines. The CLI routes to the running shared-state owner, or acquires exclusive offline custody when no owner is running. It never falls back to opening the shared database from Swift. Saving a policy requires the last observed hash; a stale save fails and must be reloaded. Gateway and headless execution enforce the same policy through the shared owner.

The native final commit re-authorizes the command against the current effective policy inside the locked write transaction. Policy edits that keep the command allowed do not deny it; execution does not require an unchanged policy hash.

An unavailable owner or PostgreSQL database denies native execution with an Exec policy unavailable diagnostic. Inspect openclaw gateway status and the selected database, or update the app and CLI if the required operation is missing. Stopping the Gateway permits offline policy operations only when the selected database remains reachable. A policy snapshot shown in the UI is for display; it cannot authorize execution.

Socket paths and authentication tokens live separately in the local client/credentials.sqlite store under the resolved client state root. They never enter the shared policy row or its compare-and-swap hash. The default approval socket follows that local root: $OPENCLAW_STATE_DIR/exec-approvals.sock, or ~/.openclaw/exec-approvals.sock when the variable is unset.

The native policy cutover does not change the shared schema or move policy data. Keep the app and local CLI compatible when updating or rolling back. An older app that is still admitted on SQLite reads the same shared policy row; it cannot read PostgreSQL policy. Existing refusal of retired shared credential access still requires updating the app and running the matching Doctor repair. A new app with an older CLI or Gateway that lacks the owner operation denies execution with a diagnostic. Rollback requires a compatible app, CLI, and policy format; restoring an older policy snapshot would rewind permissions and is not a rollback step.

State directories are independent trust scopes. When OPENCLAW_STATE_DIR points somewhere else, OpenClaw never imports or archives approvals from the default state directory. Configure approvals separately for the custom state directory. If the active state directory still contains a legacy exec-approvals.json, stop the Gateway and run openclaw doctor --fix once to import it. Doctor also imports legacy plugin-binding-approvals.json only when it belongs to the active state directory.

Legacy allowlist entries may contain null for lastUsedAt or lastUsedCommand. Doctor treats those two usage fields as absent during import, including when the config still needs repair. This does not relax validation of the current policy: other malformed fields or conflicting legacy policies remain preserved for operator recovery, and exec approvals stay blocked until the legacy file is resolved. After repair, verify with openclaw approvals get using the same state directory.

Example shared policy (socket credentials are held by the local client owner):

{
  "version": 1,
  "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": "~/path/to/**/bin/rg",
          "argPattern": "sha256:argv:...",
          "source": "allow-always",
          "lastUsedAt": 1737150000000,
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        },
        {
          "pattern": "~/path/to/**/bin/git"
        }
      ],
      "mcpTools": [
        {
          "server": "project-docs",
          "tool": "publish_page",
          "source": "allow-always",
          "addedAt": 1737150000000
        }
      ]
    }
  }
}

Policy knobs

tools.exec.mode

tools.exec.mode is the preferred normalized policy surface for host exec:

Value	Behavior
deny	Block host exec.
allowlist	Run only allowlisted commands without asking.
ask	Use allowlist policy and ask on misses.
auto	Run allowlist matches directly; review eligible misses with allow (once), deny (reason returned to the agent), or ask (human approval).
full	Run host exec without ordinary policy prompts; see strict inline-eval behavior below.

Doctor migrates supported legacy tools.exec.security / tools.exec.ask pairs to tools.exec.mode. If a deploy script, template, or config generator still sends the old fields, config patch and Gateway config.patch reject the mixed policy without changing the file. Update that source in the same exec object named by the error, including agents.entries.<agentId>.tools.exec for an agent override. Replace security / ask with the suggested mode value when an exact equivalent exists. For example, security: "full", ask: "off" becomes mode: "full".

An incomplete pair needs an explicit choice of the intended policy before conversion. Pairs with ask: "always", or security: "full", ask: "on-miss", have no exact mode equivalent: retain both legacy fields and remove mode from that same object to keep their policy. Preserve other exec settings when replacing an object. Run openclaw doctor --fix for a saved file that still needs migration. Running it again does not update a stale deployment source.

exec.security

- `deny` - block all host exec requests. - `allowlist` - allow only allowlisted commands. - `full` - do not require an allowlist match. This does not grant elevated access.

Default is full for gateway/node hosts. A sandbox host defaults to deny instead.

exec.ask

Configured ask policy for host exec. Controls the baseline approval prompt behavior from `tools.exec.mode` and host approvals defaults. Default is `off`. The per-call `ask` tool parameter (see [Exec tool](/tools/exec#parameters)) can only harden that baseline, and channel-origin model calls ignore it when the effective host ask is `off`.

• off - no ordinary policy prompts. Separately enabled strict inline-eval checks can still require approval.
• 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.

askFallback

Resolution when a prompt is required but no UI is reachable (or the prompt times out). Defaults to `deny` when omitted.

• deny - block.
• allowlist - allow only if allowlist matches.
• full - add no stricter fallback limit to the active security policy. Allowlist restrictions and explicit-approval requirements, such as recognized strict inline-eval forms, still apply.

tools.exec.strictInlineEval

When ordinary host approval evaluation runs, `true` treats recognized inline code-eval forms as approval-only, including under ordinary `full`/`off` policy or an allowlisted interpreter binary. Defense-in-depth for interpreter loaders that do not map cleanly to one stable file operand.

Examples that strict mode catches: python -c, node -e/--eval/-p, ruby -e, perl -e/-E, php -r, lua -e, osascript -e (also awk, sed, make, find -exec, and xargs inline forms).

On that approval path, these commands need reviewer or explicit approval. With tools.exec.mode: "auto", eligible commands receive an allow, deny, or ask verdict. The reviewer may grant one low- or medium-risk execution, return a denial reason to the agent, or ask a human. Gateway commands must pass mutable-file binding checks, but do not need a rendered command with pinned paths to receive review. POSIX login or interactive shell wrappers skip the reviewer and require human approval when binding succeeds because their implicit startup files are outside operand binding. Existing binding rejections, including interactive code-loading forms, remain denied. See Exec modes for binding limits and escalation. Codex app-server command approvals that reach the reviewer fallback ask a human because their approval requests do not expose an enforceable resolved executable. allow-always does not persist new allowlist entries for inline-eval commands.

Configured tools.exec.mode: "full" alone does not bypass this setting. On the Gateway, a full-permission session with effective security full and ask off skips host approval evaluation. Permitted elevated-full execution also skips it when both exec and host approval policies allow full/off. Those paths skip strict inline-eval detection. Ask-only tightening of a full session restores the approval path while retaining its host-file-floor exception. See Inline eval.

tools.exec.commandHighlighting

Presentation only: when enabled, OpenClaw may attach parser-derived command spans so Web approval prompts can highlight command tokens. Does **not** change `security`, `ask`, allowlist matching, strict inline-eval behavior, approval forwarding, or command execution.

Set globally under tools.exec.commandHighlighting or per agent under agents.entries.*.tools.exec.commandHighlighting.

YOLO mode (no-approval)

To run host exec without approval prompts, open both policy layers: requested exec policy in OpenClaw config (tools.exec.*) and host-local approvals policy in the execution host approvals document.

For ordinary configured full-mode execution of recognized inline-eval forms without prompts, leave tools.exec.strictInlineEval unset or set it to false (the default). If detection runs with strict mode enabled, askFallback: "full" does not replace reviewer or explicit approval. The Gateway session and elevated exceptions described above skip that detection.

Omitted askFallback defaults to deny. Set host askFallback to full explicitly when a no-UI approval prompt should fall back to allow.

Layer	YOLO setting
tools.exec.mode	full on gateway/node
Host askFallback	full

**Important distinctions:**

• tools.exec.host=auto chooses where exec runs: sandbox when available, otherwise gateway.
• YOLO chooses how host exec is approved: security=full plus ask=off.
• YOLO does not add a separate heuristic command-obfuscation approval gate or script-preflight rejection layer on top of the configured host exec policy. Node preparation still reads the target policy and resolves the working directory once. If both sides allow full/off and strict inline eval is disabled, ordinary path aliases and inline scripts do not require approval binding. Restrictive policy and later policy changes remain enforced.
• auto does not make node or gateway routing a free override from a sandboxed session. Per-call host=node and host=gateway requests are allowed from auto only when no sandbox runtime is active. For a stable non-auto default, set tools.exec.host or use /exec host=... explicitly.

For OpenClaw-managed Claude sessions, OpenClaw launches Claude Code in its default permission mode. OpenClaw's effective exec policy remains authoritative through native tool hooks and permission requests, including YOLO and restrictive policies, even if raw Claude backend args request bypassPermissions.

If you want a more conservative setup, tighten OpenClaw exec policy back to allowlist / on-miss or deny.

Persistent gateway-host "never prompt" setup

```bash openclaw config set tools.exec.host gateway openclaw config set tools.exec.mode full openclaw config set tools.exec.strictInlineEval false openclaw gateway restart ``` ```bash openclaw approvals set --stdin <<'EOF' { version: 1, defaults: { security: "full", ask: "off", askFallback: "full" } } EOF ```

Local shortcut

openclaw exec-policy preset yolo

Updates both local tools.exec.host/security/ask and the local approvals file defaults (including askFallback: "full"). It is intentionally local-only and requires exclusive offline ownership of the selected state. Stop a running Gateway through its service owner before using exec-policy set or preset; these commands refuse before changing policy while another live Gateway owns the state. To change gateway-host or node-host approvals remotely, use openclaw approvals set --gateway or openclaw approvals set --node <id|name|ip>.

A Gateway policy change that withdraws permission may be refused while a cron command is starting. Retry after command startup settles; the refusal leaves the previous policy in place.

Other built-in presets: cautious (host=gateway, security=allowlist, ask=on-miss, askFallback=deny) and deny-all (host=gateway, security=deny, ask=off, askFallback=deny). Apply the same way: openclaw exec-policy preset cautious.

To set individual fields instead of a full preset, use openclaw exec-policy set --host <auto|sandbox|gateway|node> --security <deny|allowlist|full> --ask <off|on-miss|always> --ask-fallback <deny|allowlist|full> with any subset of those flags.

Node host

Apply the same approvals document on the node instead:

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

**Local-only limitations:**

• openclaw exec-policy does not synchronize node approvals.
• openclaw exec-policy set --host node is rejected.
• Node exec approvals are fetched from the node at runtime. Inspect them with openclaw approvals get --node <id|name|ip> and replace them with openclaw approvals set --node <id|name|ip> --file <path> (or --stdin); see the Approvals CLI.

Session and turn shortcuts

• /exec security=full ask=off <task> requests that policy for the current message only. Include the task in the same message. A standalone directive does not affect the next message. Session permission modes and host policy can still restrict the request.
• /elevated full is a break-glass shortcut that skips exec approvals only when both the requested policy and the host approvals document resolve to security: "full" and ask: "off". A stricter host file, such as ask: "always", still prompts.

Outside the full-permission Gateway session exception, if the host approvals document 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 PATH, so rg can match /opt/homebrew/bin/rg when the command is rg, but not ./rg or /tmp/rg. Use a path glob to trust one specific binary location.

Saved policies that still use the legacy agents.default key or commandText fields are not converted on load. OpenClaw refuses them until openclaw doctor --fix moves agents.default to agents.main and drops commandText; openclaw update runs the same Doctor pass. Plugin and operator APIs still accept the legacy shape as input and normalize it before saving. See Exec approval policy. Shell chains such as echo ok && pwd still need every top-level segment to satisfy allowlist rules.

Examples:

• rg
• ~/path/to/**/bin/peekaboo
• ~/.local/bin/*
• /opt/homebrew/bin/rg

Restricting arguments with argPattern

Add argPattern when an allowlist entry should match a binary and a specific argument shape. OpenClaw uses ECMAScript (JavaScript) regular expression semantics on every host and evaluates the expression against the parsed command arguments, excluding the executable token (argv[0]). For hand-authored entries, arguments are joined with a single space, so anchor the pattern when you need an exact match.

{
  "version": 1,
  "agents": {
    "main": {
      "allowlist": [
        {
          "pattern": "python3",
          "argPattern": "^safe\\.py$"
        }
      ]
    }
  }
}

That entry allows python3 safe.py. python3 other.py is an allowlist miss. If a path-only entry for the same binary is also present, unmatched arguments can still fall back to that path-only entry. Omit the path-only entry when the goal is to restrict the binary to the declared arguments.

Entries saved by approval flows use an internal separator format for exact argv matching. Prefer the UI or approval flow to regenerate those entries instead of hand-editing the encoded value. If OpenClaw cannot parse argv for a command segment, entries with argPattern do not match.

Generated allow-always entries are bound to both the exact argv and the working directory where you approved them. Choosing Always allow here authorizes the same command only in that directory. Running it elsewhere is an allowlist miss.

Generated entries saved before 2026.8.1 are not directory-bound and are inactive after upgrading. openclaw update removes them during its automatic Doctor pass, or you can run openclaw doctor --fix yourself. Rerun an affected workflow and choose Always allow here to create the replacement. Manual allowlist rules are not changed. For a manual path-only rule, omit both source and argPattern.

Each allowlist entry supports:

Field	Meaning
pattern	Resolved binary path glob or bare command-name glob
argPattern	ECMAScript argv regex or generated exact-argv hash; omitted is path-only
id	Stable opaque ID; generated as a UUID when absent
source	Generated entry source, such as allow-always; omit for manual entries
commandText	Legacy plaintext input; saved entries need openclaw doctor --fix
lastUsedAt	Last-used timestamp
lastUsedCommand	Last command that matched; omitted for generated hashed argv entries
lastResolvedPath	Last resolved binary path

MCP tool grants

For Gateway-hosted Codex runs, Allow Always can save a durable grant for one MCP tool on a server configured in mcp.servers. The Gateway writes the grant to agents.<agentId>.mcpTools in this same approvals document. It covers the exact agent, configured server name, and tool name, with any arguments. It does not grant access to other agents, servers, or tools.

Each entry has server, tool, source: "allow-always", and addedAt (Unix milliseconds). lastUsedAt is optional. Codex apps, native plugin servers, and computer-use servers do not receive OpenClaw MCP tool grants. OpenClaw only mints when durable persistence is offered and it can unambiguously match the approval to a live Gateway-owned tool call. Missing or ambiguous correlation retains Codex's existing native/session behavior instead.

Grants apply when the server's codex.defaultToolsApprovalMode is auto or unspecified. Explicit prompt wins over a stored grant and keeps asking. Explicit approve already bypasses per-call approval. See Codex tool approvals.

The durable grant is read when OpenClaw next prepares the Codex thread configuration and hook registration, such as for a new session or after a restart. The current session continues using Codex's remembered decision. OpenClaw does not reload grants for every tool call.

To inspect grants, run openclaw approvals get --gateway. To revoke one, export the document, remove its entry from agents.<agentId>.mcpTools, and replace the document with the existing set command:

openclaw approvals get --gateway --json | jq '.file' > approvals.json
# Edit approvals.json, preserving other settings, allowlists, and grants.
openclaw approvals set --gateway --file approvals.json

Omit --gateway from both commands to edit local approvals. Revocation takes effect at the next thread preparation/registration too. Start a new session or restart to discard the active session's remembered approval. If Codex also persisted a separate approval in its native config, remove that native grant there as well.

Standing grants for automations

Approvals raised by gateway-host automation (cron) runs are delivered only to connected exec approval clients: the Control UI, the macOS/iOS/Android apps, and API clients that declare the approvals or exec-approvals capability. The TUI does not render exec approval cards, and chat channels never receive automation approvals, which would repeat a card on every occurrence. While a reviewer surface is connected, the scheduled run waits for the decision like an interactive run. Automations are single-flight, so at most one card per job is pending at a time. With no approval surface connected, the request is denied immediately and the run's error explains the policy fix. Node-host automation execs keep the fully headless policy (no cards) until node execution gains its own standing-grant path.

When an approval originates from an automation's isolated run, resolving it with Always allow does not write a JSON allowlist entry. Instead the Gateway mints a scoped standing grant bound to that exact agent, automation, job configuration, and operation (command text, working directory, and requested environment). Later occurrences of the same job execute that exact operation without prompting while the grant is valid. The approval card says so up front: automation approvals carry a scope line describing exactly what Always allow will mint.

What a grant covers, and when it stops

A grant is rejected and a normal prompt is required when the job is deleted or its substantive definition changes, even if a later edit restores the earlier definition. Pausing and re-enabling the unchanged automation preserves the grant. The grant also stops matching when the command, working directory, or environment differs by even one byte, when it is revoked or expired, or when the original approval record is gone. Each use checks the current grant and approval rows. Once a use commits, it authorizes that one start; a revocation or job edit can race that checked launch. Run liveness and host policy are still checked immediately before the process spawns. Mutable file operands and commands that require explicit review (heredocs, strict inline eval, audit suppression) keep prompting per occurrence. Non-automation approvals are unchanged.

Grant lifetime

By default a grant lives until revoked — the same meaning Always allow has everywhere else in the product. Terms freeze at mint time and never change retroactively:

• tools.exec.grantExpiryDays (unset by default) sets the default lifetime, in days, for future grants. Existing grants keep the terms they were minted with. Use revocation to retire them early. This is the fleet-policy knob for managed deployments that require periodic re-approval.
• A resolving surface may override the default per grant with the grantExpiresInDays field on approval.resolve / exec.approval.resolve, or openclaw approvals resolve <id> allow-always --expires-in-days <n>. The override wins over the config default.
• Expired grants fall back to prompting and are pruned opportunistically.

Listing and revoking

Every standing grant is visible and revocable:

• Control UI: Settings → Approvals shows the standing-grant ledger — automation, exact command, use count, and state (until revoked, expires in N days, expired, revoked) — with a Revoke action per active row.
• CLI: openclaw approvals grants list renders the same ledger. openclaw approvals grants revoke <grant-id> revokes one grant. Repeating a revocation has no additional effect. It blocks subsequent grant consumption, which prompts again. An already-consumed use may still start.
• Deleting or substantively editing the automation, or reversing the minting approval, also invalidates the grant without touching the grants surface. Pausing and re-enabling the unchanged automation does not.

The minting operator_approvals row remains the sole authorization owner: a grant is derivative correlation, revalidated against the live approval row, automation row, and revocation state on every use.

Auto-allow skill CLIs

When Auto-allow skill CLIs (autoAllowSkills) is enabled, executables referenced by known skills are treated as allowlisted on nodes (macOS node or headless node host). This uses skills.bins over the Gateway RPC to fetch the skill bin list. Disable this if you want strict manual allowlists.

Skill trust belongs to the Gateway that supplied it. Switching Gateways retires the previous cache, including the Mac app's trusted-binary list and an approval check that is still in progress. A failed refresh can keep the last known trust from the same Gateway. It cannot import another Gateway's trust.

The Mac's Exec Approvals pane refreshes its trusted binaries and agent choices when the selected Gateway connects. Local policy, the selected scope, and unfinished allowlist edits stay on the Mac.

- 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 system.execApprovals.get/set (macOS app or headless node host). These requests continue to route through exec.approvals.node.get/set to the selected node. If a node does not advertise exec approvals yet, use the owner-backed openclaw approvals commands locally on that host.

Some node hosts, including the Windows companion, own a different approval policy format. Control UI shows these host-native policies read-only. Use the companion app or openclaw approvals set --node <id|name|ip> with the native policy shape to edit them. See Approvals CLI.

CLI: openclaw approvals supports gateway or node editing - see Approvals CLI.

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.

An approval accepted before its prompt deadline remains valid during the Gateway's live handoff window. Crossing the prompt deadline during dispatch does not undo that decision. Closed runs, expired handoff windows, and reused Allow Once approvals still reject execution.

Recording or consuming an Allow Once approval and reading it for notifications do not change exec policy. These operations do not block an approved command's final policy check. Policy edits and durable MCP tool grants still fence execution while pending, and the command must pass the current policy immediately before launch.

The macOS approval panel keeps ordinary commands compact, with the supplied agent and host in one summary. It shows the working directory beneath the full, wrapping command. Longer commands scroll. Expand Details to inspect the executable path. Directory and executable paths remain fully selectable. Copy copies the displayed command, including visible escapes for control and invisible characters. The host comes from the request. A gateway or node can be remote from the Mac displaying the panel.

Choose Allow Once or press Command-Return to approve one execution. Return alone does not approve. Escape dismisses the panel, denying the request when Don't Allow is available. Otherwise it closes without a decision. Always Allow Here appears only when the request's policy permits durable approval.

Before native execution, the shared owner checks the current policy and commits the decision together with any allow-always grant and usage update. A policy revocation while the prompt is open, an agent-deletion fence, or a failed commit denies execution. After the commit returns, the app checks that the original socket request is still live and rechecks the bound executable and working directory before spawning. Cancelling or disconnecting the request cannot revive it through a late approval. No database transaction spans the IPC wait.

For host=node, approval requests include a prepared systemRunPlan payload. The gateway uses that plan as the authoritative command/cwd/session context when forwarding approved system.run requests:

• The node exec path prepares one plan up front.
• The approval record stores that plan and its binding metadata.
• Once approved, the final forwarded system.run call reuses the stored plan instead of trusting later caller edits.
• Edits to command, rawCommand, cwd, agentId, or sessionKey after the approval request was created are discarded: the gateway forwards the stored values instead. Changed env overrides are still rejected as an approval mismatch.

Approval scope summaries

An approval owner can attach a typed, display-only scope describing which people or resources the action affects. OpenClaw renders the sanitized summary on channel approval cards and includes the bounded scope in the safe approval presentation available to Control UI clients. Standalone approval links display the supplied scope before the decision buttons, including automation grant terms. Scope never grants authorization or changes approval policy.

• message-send: destination, recipient count, optional recipient preview, and whether the audience is internal or external.
• payment: exact decimal amount, currency, and payee or payment system.
• external-post: destination and whether the post is public or restricted.

For example, an email approval might show Send to 3 recipients via email (external): alice@example.com, bob@example.com, +1 more. Owners supply these facts. Channels never infer them from commands or message text. Without a declared scope, approval cards render exactly as before.

System events and denials

When an approval can be delivered, ordinary agent runs wait for the decision and receive the exec result in the same turn. The final reply uses the original delivery path, including an inbound A2A task. An operator denial returns a denied tool result without running the command.

Diagnostic and export commands that explicitly use asynchronous execution retain their separate follow-up delivery. For those workflows:

Exec lifecycle posts an Exec finished system message to the agent's session after the node reports completion. OpenClaw can also emit an in-progress notice once an approval is granted, after tools.exec.approvalRunningNoticeMs elapses (default 10000, 0 disables it). Denied exec approvals are terminal for the host command: the command does not run.

• For main-agent async approvals with an originating session, OpenClaw posts the denial back into that session as an internal followup so the agent can stop waiting on the async command and avoid a missing-result repair.
• If there is no session or the session cannot be resumed, OpenClaw can still report a concise denial to the operator or direct chat route.
• Denials for subagent and cron sessions are not posted back into that session.

Gateway-host exec approvals emit the same completion lifecycle event. Approval-gated execs reuse the approval id to correlate the pending request with its completion/denial message (Exec finished (gateway id=...) / Exec denied (gateway id=...)).

Implications

• full is powerful. Prefer allowlists when possible.
• 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 /exec.
• /exec security=full <task> is a current-turn request by an authorized operator, subject to effective session and host policy. To hard-block exec, deny the exec tool via tool policy. See session overrides for the full-access session exception to host approval floors.

Related

Safe bins, interpreter binding, and approval forwarding to chat. Shell command execution tool. Break-glass path that also skips approvals. Sandbox modes and workspace access. Security model and hardening. When to reach for each control. Skill-backed auto-allow behavior.