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

# Exec Tool — User Guide

Run shell commands from your agent session. Supports foreground and background execution.

## Parameters

* `command` (required)
* `workdir` (defaults to cwd)
* `env` (key/value overrides)
* `yieldMs` (default 10000): auto-background after this delay
* `background` (bool): background immediately
* `timeout` (seconds, default 1800): kill on expiry
* `pty` (bool): run in a pseudo-terminal (use for TTY-only CLIs, coding agents, terminal UIs)
* `host` (`sandbox | gateway | node`): where to execute
* `security` (`deny | allowlist | full`): enforcement mode for `gateway`/`node`
* `ask` (`off | on-miss | always`): approval prompts for `gateway`/`node`
* `node` (string): node id/name for `host=node`
* `elevated` (bool): request elevated host execution when sandboxed

## When exec asks for approval

When exec runs on the gateway or a node host, it goes through the approval gate. Depending on your policy:

* **deny** — host exec is blocked entirely.
* **allowlist** — approved only if the command matches an allowlisted path.
* **on-miss** — you get a prompt when no allowlist entry matches.
* **always** — you get a prompt for every command.

When a prompt fires, you see the command, cwd, agent id, and resolved binary path. You can:

* **Allow once** — run now
* **Always allow** — add to allowlist and run
* **Deny** — block this command

If no UI is available to respond, the request falls back (usually to deny).

## Policy engine (new)

Behind the scenes, the approval gate now runs through a **policy engine** that evaluates
deny/ask/allow rules before deciding whether to prompt you. The engine is opt-in: if you have not
authored any v2 policies in `~/.openclaw/exec-approvals.json`, the engine is a no-op and the
existing security/ask/allowlist behaviour you are used to is unchanged. When your operator adds
policies (deny rules for dangerous commands, allow rules for trusted executables), the engine
applies them with deny-first precedence — a single `deny` rule beats any number of `allow` rules.

## Using exec presets

Instead of hand-writing `security` / `ask` / `safeBins` / allowlist entries, set a named preset on the agent:

```json theme={"dark"}
{
  "agents": {
    "list": [
      { "id": "main", "tools": { "exec": { "preset": "coding" } } },
      { "id": "teacher", "tools": { "exec": { "preset": "readonly" } } }
    ]
  }
}
```

* **readonly** — read-only diagnostics: `ls`, `cat`, `df`, `ps`, `grep`, `sort` and friends, plus stdin filters. Good default for non-technical agents.
* **minimal** — only the 7 default stdin-safe bins (`jq`, `cut`, `uniq`, `head`, `tail`, `tr`, `wc`).
* **coding** — readonly plus `git`, `node`, `npm`, `pnpm`, `python3`, `rg`.
* **full** — no restrictions (`security: "full"`, `ask: "off"`).

When a command falls outside what the preset allows, what happens depends on the policy: with the default `ask: "on-miss"` (and `security: "allowlist"`) you get an approval prompt rather than a silent failure; with `security: "deny"`, `ask: "off"`, or when no approval UI is attached, the command is denied or resolved via the configured ask fallback instead of prompting. Explicit `security` / `ask` / `safeBins` fields you set yourself override the preset. The Agents → Tools panel in the Control UI (v2: **Configure → Agents → Tools**) shows the effective policy and offers the same picker.

See [Exec policy presets](https://docs.wednesdayai.dev/next/users/tools/exec-approvals.md#exec-policy-presets) for the full pack contents.

## Giving an agent full exec permission

Prefer a preset (above) over raw `full` where possible. To skip approval prompts entirely for an agent, set `security: "full"` and `ask: "off"`:

```json theme={"dark"}
{
  "agents": {
    "defaults": {
      "tools": {
        "exec": {
          "security": "full",
          "ask": "off"
        }
      }
    }
  }
}
```

Or just for a specific agent:

```json theme={"dark"}
{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "exec": {
            "security": "full",
            "ask": "off"
          }
        }
      }
    ]
  }
}
```

## Trusting specific commands

Two ways to allow commands without full trust:

### Safe bins (narrow stdin filters)

Add small stream-filter utilities to `tools.exec.safeBins`. These run without allowlist entries but only accept stdin — no file arguments.

```json theme={"dark"}
{ "tools": { "exec": { "safeBins": ["jq", "my-filter"] } } }
```

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

Do **not** add interpreter/runtime binaries (`python3`, `node`, `bash`) to `safeBins` — use explicit allowlist entries for those.

### Allowlist (exec-approvals.json)

Add patterns to `~/.openclaw/exec-approvals.json` under your agent's `allowlist`. Patterns are case-insensitive globs matching the resolved binary path:

```json theme={"dark"}
{
  "version": 1,
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }, { "pattern": "~/.local/bin/*" }]
    }
  }
}
```

Or use the **Control UI v2 → Fleet → Nodes & devices → Exec approvals** panel to add patterns interactively.

## Per-session overrides (/exec)

Change exec behavior for your current session without touching config:

```
/exec host=gateway security=allowlist ask=on-miss node=mac-1
```

Send `/exec` with no arguments to see current session values. Session overrides reset when the session ends; they don't persist to config.

## System events

Exec lifecycle appears as system messages in your session:

* `Exec running` — emitted if the command runs longer than `approvalRunningNoticeMs` (default 10 s)
* `Exec finished` — command completed
* `Exec denied` — blocked by policy or explicit denial

## Quick config reference

| Key | Default | What it does |
| - | - | - |
| `tools.exec.host` | `sandbox` | Where exec runs |
| `tools.exec.security` | `deny` | `deny` / `allowlist` / `full` |
| `tools.exec.ask` | `on-miss` | When to prompt |
| `tools.exec.preset` | unset | Named policy baseline (readonly / minimal / coding / full) |
| `tools.exec.safeBins` | (list above) | Stdin-only auto-trusted binaries |
| `agents.list[].tools.exec.*` | (inherits defaults) | Per-agent overrides |

## Examples

Foreground:

```json theme={"dark"}
{ "tool": "exec", "command": "ls -la" }
```

Background + poll:

```json theme={"dark"}
{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}
```

Related: [Exec Approvals (admin)](https://docs.wednesdayai.dev/next/users/tools/exec-approvals.md) · [Sandboxing](https://docs.wednesdayai.dev/next/admin/gateway/sandboxing.md)


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