openclaw Approvals & Exec-Policy CLI Reference

`openclaw approvals`

Manage execution approvals for the local host, gateway host, or a node host. When no target flag is given, commands read from or write to the local approvals file on disk. Target the gateway with --gateway, or a specific node with --node <id|name|ip>.

Alias: openclaw exec-approvals

Related: Exec approvals, Nodes

`openclaw exec-policy`

openclaw exec-policy is a local-only convenience command that synchronizes the requested tools.exec.* configuration with the local host approvals file in a single step:

openclaw exec-policy show
openclaw exec-policy show --json

openclaw exec-policy preset yolo
openclaw exec-policy preset cautious --json

openclaw exec-policy set --host gateway --security full --ask off --ask-fallback full

Scope:

Updates the local config file and local approvals file together; does not push policy to the gateway or a node host.
--host node is rejected: node exec approvals are retrieved from the node at runtime, so local exec-policy cannot synchronize them. Use openclaw approvals set --node <id|name|ip> instead.
exec-policy show marks host=node scopes as node-managed at runtime rather than deriving an effective policy from the local approvals file.

For remote host approvals, use openclaw approvals set --gateway or openclaw approvals set --node <id|name|ip> directly.

Common commands

openclaw approvals get
openclaw approvals get --node <id|name|ip>
openclaw approvals get --gateway
openclaw approvals pending
openclaw approvals resolve <id> <allow-once|allow-always|deny>

get displays the effective exec policy for the target: the requested tools.exec policy, the host approvals-file policy, and the merged effective result. Nodes with a host-native policy, such as the Windows companion, show that policy directly instead of applying OpenClaw approvals-file policy math.

For file-backed nodes, the merged view requires a host-resolved policy snapshot. Older nodes show the effective policy as unavailable rather than assuming the Gateway's requested policy also applies on the host.

Note

Per-session /exec overrides are not included. Run /exec in the relevant session to inspect its current defaults.

Precedence:

The host approvals file is the enforceable source of truth.
Requested tools.exec policy can narrow or broaden intent, but the effective result is derived from host rules.
--node combines the node host approvals file with gateway tools.exec policy (both apply at runtime).
If gateway config is unavailable, the CLI falls back to the node approvals snapshot and notes that the final runtime policy could not be computed.

Pending approvals

List pending exec, plugin, and OpenClaw system-agent approvals from the Gateway:

openclaw approvals pending
openclaw approvals pending --json

Complete enumeration and the matching operator-wide resolve flow use operator.admin because approval records otherwise retain requester/reviewer filtering. Resolution also requests the dedicated operator.approvals scope. The standard CLI operator grant includes both scopes; a restricted third-party client should not request admin merely to emulate this command.

Human output shows the approval kind, agent/session attribution, request age, time until expiry, a shortened command or summary, and a shell-neutral id64_<base64url> id token. A Full request text block always follows the compact table with every complete token and a losslessly escaped request, so terminal-width shortening cannot hide a suffix or the token needed for resolution. Copy the complete token into resolve. Unsafe terminal characters in other fields are shown as visible Unicode escapes. JSON output returns normalized entries under approvals, preserving the original raw id, summary, createdAtMs, and expiresAtMs for scripts; raw ids remain accepted by resolve unless they use the reserved id64_ display-token prefix.

If a supplied id64_ value matches both a literal raw id and the decoded display token for another approval, the CLI rejects it as ambiguous instead of risking resolution of the wrong request.

Resolve one approval by its full id:

openclaw approvals resolve <id> allow-once
openclaw approvals resolve <id> allow-always
openclaw approvals resolve <id> deny --reason "Not expected during maintenance"

The CLI reads the unified approval record to select its kind, checks the requested decision against the record's allowed decisions, and then calls the unified resolver. A first successful decision exits 0. Repeating the recorded decision also exits 0 and reports already resolved (same decision). A conflicting decision, missing approval, expired approval, or decision unavailable for that approval kind prints a clear error and exits non-zero.

--reason adds a local note to the CLI confirmation. The current Gateway approval record has no free-text resolution-reason field, so this note is not persisted or sent to other approval surfaces.

Replace approvals from a file

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

set handles JSON5 input, not just plain JSON. Supply either --file or --stdin, but not both at the same time.

Nodes running a host-native Windows policy follow a different format:

openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
{
  defaultAction: "deny",
  rules: [{ pattern: "hostname", action: "allow" }]
}
EOF

Before applying an update, the CLI reads the node's current hash and includes it in the request. This causes concurrent local edits to be rejected rather than overwritten. rules is mandatory because this action replaces the entire rule list on the node; defaultAction can be left out. A node reporting its native policy as disabled cannot be managed remotely; first enable or configure that policy directly on the host. The allowlist add|remove helper functions do not apply to host-native policies.

"Never prompt" / YOLO example

To configure a host that should never pause for exec approvals, set the host approvals defaults to full + off:

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

For nodes that expose an OpenClaw approvals file, reuse the same body with openclaw approvals set --node <id|name|ip> --stdin. Host-native nodes require the owner-specific format shown earlier.

This modifies only the host approvals file. To keep the requested OpenClaw policy in sync, also apply:

openclaw config set tools.exec.host gateway
openclaw config set tools.exec.mode full

tools.exec.host=gateway is written explicitly here because host=auto still means "sandbox when available, otherwise gateway": YOLO controls approvals, not routing. Use gateway (or /exec host=gateway) when you want host exec even if a sandbox is configured.

When askFallback is omitted, it defaults to deny. Set askFallback: "full" explicitly when upgrading a host without a UI that should retain never-prompt behavior.

A local shortcut for the same purpose, affecting only the local machine:

openclaw exec-policy preset yolo

Allowlist helpers

openclaw approvals allowlist add "~/Projects/**/bin/rg"
openclaw approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"
openclaw approvals allowlist add --agent "*" "/usr/bin/uname"

openclaw approvals allowlist remove "~/Projects/**/bin/rg"

Common options

The following flags are supported by get, set, and allowlist add|remove:

--node <id|name|ip> (resolves id, name, IP, or id prefix; uses the same resolver as openclaw nodes)
--gateway
shared node RPC options: --url, --token, --timeout, --json

Omitting the target flag applies the command to the local approvals file on disk.

allowlist add|remove additionally accepts --agent <id> (defaults to "*", affecting all agents).

pending and resolve always route through the Gateway because pending requests are live Gateway state. They support the shared Gateway connection options --url, --token, and --timeout; pending also supports --json.

Notes

The node host must advertise system.execApprovals.get/set (macOS app, headless node host, or Windows companion).
Approvals files are stored per host in the OpenClaw state directory: $OPENCLAW_STATE_DIR/exec-approvals.json, or ~/.openclaw/exec-approvals.json when the variable is not set.