mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 08:20:43 +00:00
docs(exec-approvals): rewrite around ParamField, Steps, and tables
The exec-approvals doc was 379 lines mixing inspection commands as
free bullets, bullet-list policy knobs (security/ask/askFallback/
strictInlineEval), a long YOLO-mode walkthrough split between two
shell blocks, and a stray dangling HTML comment from a prior split
to the advanced page.
Restructure for scan-first reading without losing operational detail:
- Convert 'Inspecting the effective policy' command bullets into a
command/result table.
- Convert each policy knob (security, ask, askFallback,
strictInlineEval) into a ParamField definition so type/values are
visually distinct.
- Wrap the persistent gateway-host YOLO setup in a Steps component
(config -> approvals file).
- Move the YOLO 'pick which layer' note and 'auto vs YOLO'
distinctions into a Warning callout instead of buried inline
bullets.
- Convert the YOLO layer summary into a 3-row layer/setting table.
- Move the local-only exec-policy limitations into a Note callout.
- Convert allowlist entry fields (id, lastUsedAt, lastUsedCommand,
lastResolvedPath) into a 4-row table.
- Surface Auto-allow trust caveats as a Warning callout.
- Drop the dangling HTML comment '<!-- moved to /tools/exec-approvals-advanced -->'.
- Sentence-case 'YOLO mode (no-approval)' replacing the inverted
quote variant ('No-approval YOLO mode').
- Add sidebarTitle for explicit nav.
Trust model, schema example, host approvals JSON shape, allowlist
glob rules, ask-fallback semantics, system-event names, deny-rerun
guard, and the trailing CardGroup of related entries are unchanged.
Pure restructure plus Mintlify component upgrades.
This commit is contained in:
Vincent Koc
@@ -1,77 +1,78 @@
|
||||
---
|
||||
summary: "Exec approvals, allowlists, and sandbox escape prompts"
|
||||
summary: "Host exec approvals: policy knobs, allowlists, and the YOLO/strict workflow"
|
||||
read_when:
|
||||
- Configuring exec approvals or allowlists
|
||||
- Implementing exec approval UX in the macOS app
|
||||
- Reviewing sandbox escape prompts and implications
|
||||
- Reviewing sandbox-escape prompts and their implications
|
||||
title: "Exec approvals"
|
||||
sidebarTitle: "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`). 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 `full`, which skips approvals).
|
||||
Exec approvals are the **companion app / node host guardrail** for letting
|
||||
a sandboxed agent run commands on a real host (`gateway` or `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 `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"`.
|
||||
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"`.
|
||||
</Note>
|
||||
|
||||
## Inspecting the effective policy
|
||||
|
||||
- `openclaw approvals get`, `... --gateway`, `... --node <id|name|ip>` — show requested policy, host policy sources, and the effective result.
|
||||
- `openclaw exec-policy show` — local-machine merged view.
|
||||
- `openclaw exec-policy set|preset` — synchronize the local requested policy with the local host approvals file in one step.
|
||||
| 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` | Local-machine merged view. |
|
||||
| `openclaw exec-policy set` / `preset` | Synchronize the local requested policy with the local host approvals file in one step. |
|
||||
|
||||
When a local scope requests `host=node`, `exec-policy show` reports that scope
|
||||
as node-managed at runtime instead of pretending the local approvals file is
|
||||
the source of truth.
|
||||
When a local scope requests `host=node`, `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: deny).
|
||||
If the companion app UI is **not available**, any request that would
|
||||
normally prompt is resolved by the **ask fallback** (default: `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.
|
||||
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.
|
||||
</Tip>
|
||||
|
||||
## 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)
|
||||
- **Gateway host** → `openclaw` process on the gateway machine.
|
||||
- **Node host** → node runner (macOS companion app or headless node host).
|
||||
|
||||
Trust model note:
|
||||
### 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.
|
||||
- This 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.
|
||||
- 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:
|
||||
### macOS split
|
||||
|
||||
- **node host service** forwards `system.run` to the **macOS app** over local IPC.
|
||||
- **macOS app** enforces approvals + executes the command in UI context.
|
||||
- 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.
|
||||
|
||||
## Settings and storage
|
||||
|
||||
Approvals live in a local JSON file on the execution host:
|
||||
|
||||
`~/.openclaw/exec-approvals.json`
|
||||
```text
|
||||
~/.openclaw/exec-approvals.json
|
||||
```
|
||||
|
||||
Example schema:
|
||||
|
||||
@@ -108,59 +109,120 @@ Example schema:
|
||||
}
|
||||
```
|
||||
|
||||
## No-approval "YOLO" mode
|
||||
## Policy knobs
|
||||
|
||||
If you want host exec to run without approval prompts, you must open **both** policy layers:
|
||||
### `exec.security`
|
||||
|
||||
- requested exec policy in OpenClaw config (`tools.exec.*`)
|
||||
- host-local approvals policy in `~/.openclaw/exec-approvals.json`
|
||||
<ParamField path="security" type='"deny" | "allowlist" | "full"'>
|
||||
- `deny` — block all host exec requests.
|
||||
- `allowlist` — allow only allowlisted commands.
|
||||
- `full` — allow everything (equivalent to elevated).
|
||||
</ParamField>
|
||||
|
||||
This is now the default host behavior unless you tighten it explicitly:
|
||||
### `exec.ask`
|
||||
|
||||
- `tools.exec.security`: `full` on `gateway`/`node`
|
||||
- `tools.exec.ask`: `off`
|
||||
- host `askFallback`: `full`
|
||||
<ParamField path="ask" type='"off" | "on-miss" | "always"'>
|
||||
- `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`.
|
||||
</ParamField>
|
||||
|
||||
Important distinction:
|
||||
### `askFallback`
|
||||
|
||||
- `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`.
|
||||
- CLI-backed providers that expose their own noninteractive permission mode can follow this policy.
|
||||
Claude CLI adds `--permission-mode bypassPermissions` when OpenClaw's requested exec policy is
|
||||
YOLO. Override that backend behavior with explicit Claude args under
|
||||
`agents.defaults.cliBackends.claude-cli.args` / `resumeArgs`, for example
|
||||
`--permission-mode default`, `acceptEdits`, or `bypassPermissions`.
|
||||
- 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.
|
||||
- `auto` does not make gateway routing a free override from a sandboxed session. A per-call `host=node` request is allowed from `auto`, and `host=gateway` is only allowed from `auto` when no sandbox runtime is active. If you want a stable non-auto default, set `tools.exec.host` or use `/exec host=...` explicitly.
|
||||
<ParamField path="askFallback" type='"deny" | "allowlist" | "full"'>
|
||||
Resolution when a prompt is required but no UI is reachable.
|
||||
|
||||
If you want a more conservative setup, tighten either layer back to `allowlist` / `on-miss`
|
||||
or `deny`.
|
||||
- `deny` — block.
|
||||
- `allowlist` — allow only if allowlist matches.
|
||||
- `full` — allow.
|
||||
</ParamField>
|
||||
|
||||
Persistent gateway-host "never prompt" setup:
|
||||
### `tools.exec.strictInlineEval`
|
||||
|
||||
```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
|
||||
```
|
||||
<ParamField path="strictInlineEval" type="boolean">
|
||||
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.
|
||||
</ParamField>
|
||||
|
||||
Then set the host approvals file to match:
|
||||
Examples that strict mode catches:
|
||||
|
||||
```bash
|
||||
openclaw approvals set --stdin <<'EOF'
|
||||
{
|
||||
version: 1,
|
||||
defaults: {
|
||||
security: "full",
|
||||
ask: "off",
|
||||
askFallback: "full"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
- `python -c`
|
||||
- `node -e`, `node --eval`, `node -p`
|
||||
- `ruby -e`
|
||||
- `perl -e`, `perl -E`
|
||||
- `php -r`
|
||||
- `lua -e`
|
||||
- `osascript -e`
|
||||
|
||||
Local shortcut for the same gateway-host policy on the current machine:
|
||||
In strict mode these commands still need explicit approval, and
|
||||
`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
|
||||
(`tools.exec.*`) **and** host-local approvals policy in
|
||||
`~/.openclaw/exec-approvals.json`.
|
||||
|
||||
YOLO is the default host behavior unless you tighten it explicitly:
|
||||
|
||||
| Layer | YOLO setting |
|
||||
| --------------------- | -------------------------- |
|
||||
| `tools.exec.security` | `full` on `gateway`/`node` |
|
||||
| `tools.exec.ask` | `off` |
|
||||
| Host `askFallback` | `full` |
|
||||
|
||||
<Warning>
|
||||
**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`.
|
||||
- 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.
|
||||
- `auto` does not make gateway routing a free override from a sandboxed session. A per-call `host=node` request is allowed from `auto`; `host=gateway` is only allowed from `auto` when no sandbox runtime is active. For a stable non-auto default, set `tools.exec.host` or use `/exec host=...` explicitly.
|
||||
</Warning>
|
||||
|
||||
CLI-backed providers that expose their own noninteractive permission mode
|
||||
can follow this policy. Claude CLI adds
|
||||
`--permission-mode bypassPermissions` when OpenClaw's requested exec
|
||||
policy is YOLO. Override that backend behavior with explicit Claude args
|
||||
under `agents.defaults.cliBackends.claude-cli.args` / `resumeArgs` —
|
||||
for example `--permission-mode default`, `acceptEdits`, or
|
||||
`bypassPermissions`.
|
||||
|
||||
If you want a more conservative setup, tighten either layer back to
|
||||
`allowlist` / `on-miss` or `deny`.
|
||||
|
||||
### Persistent gateway-host "never prompt" setup
|
||||
|
||||
<Steps>
|
||||
<Step title="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
|
||||
```
|
||||
</Step>
|
||||
<Step title="Match the host approvals file">
|
||||
```bash
|
||||
openclaw approvals set --stdin <<'EOF'
|
||||
{
|
||||
version: 1,
|
||||
defaults: {
|
||||
security: "full",
|
||||
ask: "off",
|
||||
askFallback: "full"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Local shortcut
|
||||
|
||||
```bash
|
||||
openclaw exec-policy preset yolo
|
||||
@@ -168,13 +230,15 @@ openclaw exec-policy preset yolo
|
||||
|
||||
That local shortcut updates both:
|
||||
|
||||
- local `tools.exec.host/security/ask`
|
||||
- local `~/.openclaw/exec-approvals.json` defaults
|
||||
- Local `tools.exec.host/security/ask`.
|
||||
- Local `~/.openclaw/exec-approvals.json` defaults.
|
||||
|
||||
It is intentionally local-only. If you need to change gateway-host or node-host approvals
|
||||
remotely, continue using `openclaw approvals set --gateway` or
|
||||
It is intentionally local-only. To change gateway-host or node-host
|
||||
approvals remotely, use `openclaw approvals set --gateway` or
|
||||
`openclaw approvals set --node <id|name|ip>`.
|
||||
|
||||
### Node host
|
||||
|
||||
For a node host, apply the same approvals file on that node instead:
|
||||
|
||||
```bash
|
||||
@@ -190,71 +254,36 @@ openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
|
||||
EOF
|
||||
```
|
||||
|
||||
Important local-only limitation:
|
||||
<Note>
|
||||
**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, so node-targeted updates must use `openclaw approvals --node ...`
|
||||
- `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, so node-targeted updates must use `openclaw approvals --node ...`.
|
||||
</Note>
|
||||
|
||||
Session-only shortcut:
|
||||
### Session-only shortcut
|
||||
|
||||
- `/exec security=full ask=off` changes only the current session.
|
||||
- `/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.
|
||||
|
||||
## Policy knobs
|
||||
|
||||
### Security (`exec.security`)
|
||||
|
||||
- **deny**: block all host exec requests.
|
||||
- **allowlist**: allow only allowlisted commands.
|
||||
- **full**: allow everything (equivalent to elevated).
|
||||
|
||||
### Ask (`exec.ask`)
|
||||
|
||||
- **off**: never prompt.
|
||||
- **on-miss**: prompt only when allowlist does not match.
|
||||
- **always**: prompt on every command.
|
||||
- `allow-always` durable trust does not suppress prompts when effective ask mode is `always`
|
||||
|
||||
### Ask fallback (`askFallback`)
|
||||
|
||||
If a prompt is required but no UI is reachable, fallback decides:
|
||||
|
||||
- **deny**: block.
|
||||
- **allowlist**: allow only if allowlist matches.
|
||||
- **full**: allow.
|
||||
|
||||
### Inline interpreter eval hardening (`tools.exec.strictInlineEval`)
|
||||
|
||||
When `tools.exec.strictInlineEval=true`, OpenClaw treats inline code-eval forms as approval-only even if the interpreter binary itself is allowlisted.
|
||||
|
||||
Examples:
|
||||
|
||||
- `python -c`
|
||||
- `node -e`, `node --eval`, `node -p`
|
||||
- `ruby -e`
|
||||
- `perl -e`, `perl -E`
|
||||
- `php -r`
|
||||
- `lua -e`
|
||||
- `osascript -e`
|
||||
|
||||
This is defense-in-depth for interpreter loaders that do not map cleanly to one stable file operand. In strict mode:
|
||||
|
||||
- these commands still need explicit approval;
|
||||
- `allow-always` does not persist new allowlist entries for them automatically.
|
||||
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’re
|
||||
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 when you
|
||||
want to trust one specific binary location.
|
||||
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 when you want to trust one specific binary
|
||||
location.
|
||||
|
||||
Legacy `agents.default` entries are migrated to `agents.main` on load.
|
||||
Shell chains such as `echo ok && pwd` still need every top-level segment to satisfy allowlist rules.
|
||||
Shell chains such as `echo ok && pwd` still need every top-level segment
|
||||
to satisfy allowlist rules.
|
||||
|
||||
Examples:
|
||||
|
||||
@@ -265,89 +294,94 @@ Examples:
|
||||
|
||||
Each allowlist entry tracks:
|
||||
|
||||
- **id** stable UUID used for UI identity (optional)
|
||||
- **last used** timestamp
|
||||
- **last used command**
|
||||
- **last resolved path**
|
||||
| Field | Meaning |
|
||||
| ------------------ | -------------------------------- |
|
||||
| `id` | Stable UUID used for UI identity |
|
||||
| `lastUsedAt` | Last-used timestamp |
|
||||
| `lastUsedCommand` | Last command that matched |
|
||||
| `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
|
||||
`skills.bins` over the Gateway RPC to fetch the skill bin list. Disable this if you want strict manual allowlists.
|
||||
|
||||
Important trust notes:
|
||||
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 `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.
|
||||
</Warning>
|
||||
|
||||
## 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](/tools/exec-approvals-advanced).
|
||||
|
||||
<!-- moved to /tools/exec-approvals-advanced -->
|
||||
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](/tools/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.
|
||||
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).
|
||||
If a node does not advertise exec approvals yet, edit its local
|
||||
`~/.openclaw/exec-approvals.json` directly.
|
||||
The target selector chooses **Gateway** (local approvals) or a **Node**.
|
||||
Nodes must advertise `system.execApprovals.get/set` (macOS app or
|
||||
headless node host). If a node does not advertise exec approvals yet,
|
||||
edit its local `~/.openclaw/exec-approvals.json` directly.
|
||||
|
||||
CLI: `openclaw approvals` supports gateway or node editing (see [Approvals CLI](/cli/approvals)).
|
||||
CLI: `openclaw approvals` supports gateway or node editing — see
|
||||
[Approvals CLI](/cli/approvals).
|
||||
|
||||
## 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
|
||||
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.
|
||||
|
||||
For `host=node`, approval requests include a canonical `systemRunPlan` payload. The gateway uses
|
||||
that plan as the authoritative command/cwd/session context when forwarding approved `system.run`
|
||||
For `host=node`, approval requests include a canonical `systemRunPlan`
|
||||
payload. The gateway uses that plan as the authoritative
|
||||
command/cwd/session context when forwarding approved `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 `system.run` call reuses the stored plan
|
||||
instead of trusting later caller edits
|
||||
- if the caller changes `command`, `rawCommand`, `cwd`, `agentId`, or
|
||||
`sessionKey` after the approval request was created, the gateway rejects the
|
||||
forwarded run as an approval mismatch
|
||||
- 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 `system.run` call reuses the stored plan instead of trusting later caller edits.
|
||||
- If the caller changes `command`, `rawCommand`, `cwd`, `agentId`, or `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:
|
||||
|
||||
- `Exec running` (only if the command exceeds the running notice threshold)
|
||||
- `Exec finished`
|
||||
- `Exec denied`
|
||||
- `Exec running` (only if the command exceeds the running notice threshold).
|
||||
- `Exec finished`.
|
||||
- `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 `runId` in these messages for easy correlation.
|
||||
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 `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.
|
||||
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
|
||||
|
||||
- **full** is powerful; prefer allowlists when possible.
|
||||
- **ask** keeps you in the loop while still allowing fast approvals.
|
||||
- **`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` is a session-level convenience for authorized operators and skips approvals by design. To hard-block host exec, set approvals security to `deny` or deny the `exec` tool via tool policy.
|
||||
|
||||
Reference in New Issue
Block a user