> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`). Think of it like a safety interlock:
commands are allowed only when policy + allowlist + (optional) user approval all agree.
Exec 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 approvals defaults; if an approvals field is omitted, the `tools.exec` value is used.
When the approvals file is the stricter side, denials name it: the message names the winning key (`agents.<id>.security`, `agents.*.security` or `defaults.security`) and the file path, for example `tools.exec.security=full is floored to allowlist by defaults.security in ~/.openclaw/exec-approvals.json; the stricter setting applies`. The agent's tools panel shows the same note via `tools.catalog` `execPolicy.warning`; see [Exec Tool (admin)](https://docs.wednesdayai.dev/users/tools/exec-admin.md).

If the companion app UI is **not available**, any request that requires a prompt is
resolved by the **ask fallback** (default: deny).

## 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)

Trust model note:

* 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.

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.

## Settings and storage

Approvals live in a local JSON file on the execution host:

`~/.openclaw/exec-approvals.json`

### v1 schema (legacy on-disk format, still accepted)

```json theme={"dark"}
{
  "version": 1,
  "socket": {
    "path": "~/.openclaw/exec-approvals.sock",
    "token": "base64url-token"
  },
  "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": "~/Projects/**/bin/rg",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg -n TODO",
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        }
      ]
    }
  }
}
```

`lastUsedCommand` holds the command that last matched the entry. A `system.run` caller can pass
`redactArgvIndexes` (indexes into `command`) to keep argument values out of it: the node host
writes those elements as `[redacted]`, keeping a `--flag=` prefix, in `lastUsedCommand` and in
exec events. The command itself still runs with the real arguments.

### v2 schema (canonical execution model)

The v2 schema adds a `policies` array (compiled execution policies evaluated deny-first) and an
`approvals` array (anti-tamper binding records). It is a **super-set** of v1: the `socket`,
`defaults`, and per-agent `agents` fields are preserved so the legacy enforcement surfaces
(IPC token, security/ask defaults, per-agent allowlists) continue to work alongside the policy
engine. v1 is migrated to v2 in memory on every load; the on-disk file is not auto-overwritten.

```json theme={"dark"}
{
  "version": 2,
  "policies": [
    {
      "id": "allow-pnpm-test",
      "effect": "allow",
      "source": "user",
      "namespace": "exec.argv",
      "match": { "executableName": "pnpm", "argvPattern": "test", "matchAnyTrailingArgs": true }
    },
    {
      "id": "deny-rm",
      "effect": "deny",
      "source": "managed",
      "namespace": "exec.argv",
      "match": { "executableName": "rm" }
    }
  ],
  "approvals": [
    {
      "id": "approval-uuid",
      "requestHash": "sha256-hex-of-canonical-request",
      "scope": { "agentId": "main", "sessionKey": "sess-1" },
      "boundAt": 1737150000000
    }
  ],
  "socket": { "path": "~/.openclaw/exec-approvals.sock", "token": "base64url-token" },
  "defaults": { "security": "allowlist", "ask": "on-miss" },
  "agents": { "main": { "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }] } }
}
```

The policy engine is **opt-in**: when zero policies are loaded (the default), the pipeline is a
no-op and the pre-policy-engine behaviour is preserved. Deny-first enforcement only activates when
at least one policy is present. See [Exec Tool (developer)](https://docs.wednesdayai.dev/users/tools/exec-developer.md#canonical-execution-model)
for the full type definitions, evaluator semantics, and wiring status.

## 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.

### 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.

### Exec policy presets

The `tools.exec.preset` key sets a named baseline for `security`, `ask`, `safeBins`, and a built-in allowlist pack. Explicit `tools.exec` fields override preset values. Per-agent `tools.exec.preset` overrides the global preset. Omitting the key means no preset (inherit defaults).

| Preset ID | Security | Ask | Safe bins |
| - | - | - | - |
| readonly | allowlist | on-miss | jq, cut, uniq, head, tail, tr, wc, grep, sort |
| minimal | allowlist | on-miss | jq, cut, uniq, head, tail, tr, wc |
| coding | allowlist | on-miss | jq, cut, uniq, head, tail, tr, wc, grep, sort |
| full | full | off | (all) |

Each preset also includes an **allowlist pack** of exact absolute paths:

* **readonly**: `ls`, `cat`, `df`, `du`, `ps`, `uname`, `whoami`, `hostname`, `date`, `pwd`, `which`, `file`, `stat` at `/usr/bin`, `/bin`, `/usr/local/bin` (39 paths total).
* **minimal**: no pack.
* **coding**: readonly pack plus `git`, `node`, `npm`, `pnpm`, `python3`, `rg` at `/usr/bin`, `/bin`, `/usr/local/bin`, `/opt/homebrew/bin`, `/home/linuxbrew/.linuxbrew/bin` (69 paths total). Warning: node, python3, npm, and pnpm execute arbitrary code with no argument constraints — the coding preset is equivalent to full code-execution capability for the agent; grant it only to agents that would otherwise warrant tools.exec security "full".
* **full**: no pack (all tools allowed).

Pack entries are exact absolute paths, not glob patterns. The allowlist engine matches path patterns against the resolved executable path; bare names never match. Exact paths prevent accidentally allowing neighbor binaries in the same directory.

**find is deliberately NOT in the readonly pack.** The `find` utility can mutate with `-exec` and `-delete`. Allowlist entries constrain the executable, not its arguments. Add `find` to your own allowlist only if you accept that risk.

Pack entries are **never materialized** in `~/.openclaw/exec-approvals.json`. Presets are unioned at evaluation time only; the per-agent allowlist in the approvals file remains authoritative. The approvals file can still floor the security level via `minSecurity`.

Unknown preset ids are ignored with a logged warning. Explicit `tools.exec` fields still apply.

Per-agent allowlist entries from `~/.openclaw/exec-approvals.json` apply **alongside** the preset pack (they are unioned at evaluation time, and remain editable per agent); see [v2 schema (canonical)](#v2-schema-canonical-execution-model) for the file format.

**Agent mapping suggestion:** messaging/non-technical agents → `readonly`; developer/research agents → `coding`.

## Allowlist (per agent)

Allowlists are **per agent**. If multiple agents exist, switch which agent you’re
editing in the macOS app. Patterns are **case-insensitive glob matches**.
Patterns should resolve to **binary paths** (basename-only entries are ignored).
Legacy `agents.default` entries are migrated to `agents.main` on load.

Examples:

* `~/Projects/**/bin/peekaboo`
* `~/.local/bin/*`
* `/opt/homebrew/bin/rg`

Each allowlist entry tracks:

* **id** stable UUID used for UI identity (optional)
* **last used** timestamp
* **last used command**
* **last resolved path**

Entries under the `"*"` agent apply to every agent. The last-used fields go on the entry that
matched: the agent's own entry when it has one for the pattern, otherwise the `"*"` entry.

## 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:

* 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 (stdin-only)

`tools.exec.safeBins` defines a small list of **stdin-only** binaries (for example `jq`)
that can run in allowlist mode **without** explicit allowlist entries. Safe bins reject
positional file args and path-like tokens, so they can only operate on the incoming stream.
Treat this as a narrow fast-path for stream filters, not a general trust list.
Do **not** add interpreter or runtime binaries (for example `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`) to `safeBins`.
If a command can evaluate code, execute subcommands, or read files by design, prefer explicit allowlist entries and keep approval prompts enabled.
Custom safe bins must define an explicit profile in `tools.exec.safeBinProfiles.<bin>`.
Validation is deterministic from argv shape only (no host filesystem existence checks), which
prevents file-existence oracle behavior from allow/deny differences.
File-oriented options are denied for default safe bins (for example `sort -o`, `sort --output`,
`sort --files0-from`, `sort --compress-program`, `sort --random-source`,
`sort --temporary-directory`/`-T`, `wc --files0-from`, `jq -f/--from-file`,
`grep -f/--file`).
Safe bins also enforce explicit per-binary flag policy for options that break stdin-only
behavior (for example `sort -o/--output/--compress-program` and grep recursive flags).
Long options are validated fail-closed in safe-bin mode: unknown flags and ambiguous
abbreviations are rejected.
Denied flags by safe-bin profile:

{/_ SAFE_BIN_DENIED_FLAGS:START _/ && null}

* `grep`: `--dereference-recursive`, `--directories`, `--exclude-from`, `--file`, `--recursive`, `-R`, `-d`, `-f`, `-r`
* `jq`: `--argfile`, `--from-file`, `--library-path`, `--rawfile`, `--slurpfile`, `-L`, `-f`
* `sort`: `--compress-program`, `--files0-from`, `--output`, `--random-source`, `--temporary-directory`, `-T`, `-o`
* `wc`: `--files0-from`
  {/_ SAFE_BIN_DENIED_FLAGS:END _/ && null}

Safe bins also force argv tokens to be treated as **literal text** at execution time (no globbing
and no `$VARS` expansion) for stdin-only segments, so patterns like `*` or `$HOME/...` cannot be
used to smuggle file reads.
Safe bins must also resolve from trusted binary directories (system defaults plus optional
`tools.exec.safeBinTrustedDirs`). `PATH` entries are never auto-trusted.
Default trusted safe-bin directories are intentionally minimal: `/bin`, `/usr/bin`.
If your safe-bin executable lives in package-manager/user paths (for example
`/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), add them explicitly
to `tools.exec.safeBinTrustedDirs`.
Shell chaining and redirections are not auto-allowed in allowlist mode.

Shell chaining (`&&`, `||`, `;`) is allowed when every top-level segment satisfies the allowlist
(including safe bins or skill auto-allow). Redirections remain unsupported in allowlist mode.
Command substitution (`$()` / backticks) is rejected during allowlist parsing, including inside
double quotes; use single quotes if you need literal `$()` text.
On macOS companion-app approvals, raw shell text containing shell control or expansion syntax
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) is treated as an allowlist miss unless
the shell binary itself is allowlisted.
For shell wrappers (`bash|sh|zsh ... -c/-lc`), request-scoped env overrides are reduced to a
small explicit allowlist (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
For allow-always decisions in allowlist mode, known dispatch wrappers
(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) persist inner executable paths instead of wrapper
paths. Shell multiplexers (`busybox`, `toybox`) are also unwrapped for shell applets (`sh`, `ash`,
etc.) so inner executables are persisted instead of multiplexer binaries. If a wrapper or
multiplexer cannot be safely unwrapped, no allowlist entry is persisted automatically.

Default safe bins: `jq`, `cut`, `uniq`, `head`, `tail`, `tr`, `wc`.

`grep` and `sort` are not in the default list. If you opt in, keep explicit allowlist entries for
their non-stdin workflows.
For `grep` in safe-bin mode, provide the pattern with `-e`/`--regexp`; positional pattern form is
rejected so file operands cannot be smuggled as ambiguous positionals.

### Safe bins versus allowlist

| Topic | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) |
| - | - | - |
| Goal | Auto-allow narrow stdin filters | Explicitly trust specific executables |
| Match type | Executable name + safe-bin argv policy | Resolved executable path glob pattern |
| Argument scope | Restricted by safe-bin profile and literal-token rules | Path match only; arguments are otherwise your responsibility |
| Typical examples | `jq`, `head`, `tail`, `wc` | `python3`, `node`, `ffmpeg`, custom CLIs |
| Best use | Low-risk text transforms in pipelines | Any tool with broader behavior or side effects |

Configuration location:

* `safeBins` comes from config (`tools.exec.safeBins` or per-agent `agents.list[].tools.exec.safeBins`).
* `safeBinTrustedDirs` comes from config (`tools.exec.safeBinTrustedDirs` or per-agent `agents.list[].tools.exec.safeBinTrustedDirs`).
* `safeBinProfiles` comes from config (`tools.exec.safeBinProfiles` or per-agent `agents.list[].tools.exec.safeBinProfiles`). Per-agent profile keys override global keys.
* allowlist entries live in host-local `~/.openclaw/exec-approvals.json` under `agents.<id>.allowlist` (or via Control UI / `wednesdayai approvals allowlist ...`).
* `wednesdayai security audit` warns with `tools.exec.safe_bins_interpreter_unprofiled` when interpreter/runtime bins appear in `safeBins` without explicit profiles.
* `wednesdayai doctor --fix` can scaffold missing custom `safeBinProfiles.<bin>` entries as `{}` (review and tighten afterward). Interpreter/runtime bins are not auto-scaffolded.

Custom profile example:

```json5 theme={"dark"}
{
  tools: {
    exec: {
      safeBins: ["jq", "myfilter"],
      safeBinProfiles: {
        myfilter: {
          minPositional: 0,
          maxPositional: 0,
          allowedValueFlags: ["-n", "--limit"],
          deniedFlags: ["-f", "--file", "-c", "--command"],
        },
      },
    },
  },
}
```

## Control UI editing

Use the **Control UI v2 → Fleet → Nodes & devices → Exec approvals** panel 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.

CLI: `wednesdayai approvals` supports gateway or node editing (see [Approvals CLI](https://docs.wednesdayai.dev/users/cli/approvals.md)).

## 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.

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.

When approvals are required, the exec tool returns immediately with an approval id. Use that id to
correlate later system events (`Exec finished` / `Exec denied`). If no decision arrives before the
timeout, the request is treated as an approval timeout and surfaced as a denial reason.

The confirmation dialog includes:

* command + args
* cwd
* agent id
* resolved executable path
* host + policy metadata

Actions:

* **Allow once** → run now
* **Always allow** → add to allowlist + run
* **Deny** → block

## Approval forwarding to chat channels

You can forward exec approval prompts to any chat channel (including plugin channels) and approve
them with `/approve`. This uses the normal outbound delivery pipeline.

Config:

```json5 theme={"dark"}
{
  approvals: {
    exec: {
      enabled: true,
      mode: "session", // "session" | "targets" | "both"
      agentFilter: ["main"],
      sessionFilter: ["discord"], // substring or regex
      targets: [
        { channel: "slack", to: "U12345678" },
        { channel: "telegram", to: "123456789" },
      ],
    },
  },
}
```

Reply in chat:

```
/approve <id> allow-once
/approve <id> allow-always
/approve <id> deny
```

### macOS IPC flow

```
Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + approvals + system.run)
```

Security notes:

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

## System events

Exec lifecycle is surfaced as system messages:

* `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.

## 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` 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.

Related:

* [Exec tool](https://docs.wednesdayai.dev/users/tools/exec.md)
* [Elevated mode](https://docs.wednesdayai.dev/users/tools/elevated.md)
* [Skills](https://docs.wednesdayai.dev/users/tools/skills.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.