Permission Modes Overview

Permission modes control how much authority an agent has before it runs host commands, writes files, or requests additional access from a backend harness.

Note

Permission mode is separate from tools.exec.host=auto. tools.exec.host determines where a command executes. tools.exec.mode determines how host execution is approved.

Recommended default

Use auto for coding agents that require practical host access without prompting a human on every miss:

openclaw config set tools.exec.mode auto
openclaw approvals get
openclaw gateway restart

Then confirm the effective policy:

openclaw exec-policy show

OpenClaw host exec modes

tools.exec.mode is the normalized policy surface for host exec. Each mode resolves to an underlying security (allowlist strictness) and ask (prompt-on-miss) pair:

Mode	security / ask	Behavior	Use when
`deny`	`deny` / `off`	Block host execution entirely.	No host commands are permitted.
`allowlist`	`allowlist` / `off`	Execute only allowlisted commands; silently reject misses.	You have a known-safe command set.
`ask`	`allowlist` / `on-miss`	Execute allowlist matches; prompt a human on misses.	A human should review each new command.
`auto`	`allowlist` / `on-miss`	Execute allowlist matches; send misses through auto-review before falling back to human approval.	Coding sessions need practical guarded access.
`full`	`full` / `off`	Execute host commands without prompts.	This trusted host or session should skip approval gates.

ask and auto share the same allowlist and ask settings; auto additionally enables the native auto-reviewer, which decides misses on its own and only falls back to the configured human approval route when it cannot safely approve.

For the full host execution policy, local approvals file, allowlist schema, safe binaries, and forwarding behavior, see Exec approvals.

Codex Guardian mapping

For native Codex app-server sessions, tools.exec.mode: "auto" drives Codex toward Guardian-reviewed approvals when local Codex requirements allow it. Typical resulting values:

Codex field	Typical value
`approvalPolicy`	`on-request`
`approvalsReviewer`	`auto_review`
`sandbox`	`workspace-write`

auto mode forces this policy over any configured Codex sandbox or approval overrides, so it does not preserve legacy unsafe combinations such as approvalPolicy: "never" with sandbox: "danger-full-access". tools.exec.mode: "deny" and "allowlist" block Codex app-server local execution entirely. Use tools.exec.mode: "full" only when you intentionally want the no-approval posture.

For app-server setup, auth order, and native Codex runtime details, see Codex harness.

ACPX harness permissions

ACPX sessions are non-interactive, so they cannot respond to a TTY permission prompt. ACPX uses separate harness-level settings under plugins.entries.acpx.config:

Setting	Values	Meaning
`permissionMode`	`approve-reads`	Auto-approve reads only.
`permissionMode`	`approve-all`	Auto-approve writes and shell commands.
`permissionMode`	`deny-all`	Deny all permission prompts.
`nonInteractivePermissions`	`fail`	Abort when a prompt would be required.
`nonInteractivePermissions`	`deny`	Deny the prompt and continue when possible.

Set ACPX permissions separately from OpenClaw exec approvals:

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
openclaw gateway restart

Use approve-all as the ACPX break-glass equivalent of a no-prompt harness session. For setup details and failure modes, see ACP agents setup.

Choosing a mode

Goal	Configure
Block host commands completely	`tools.exec.mode: "deny"`
Let known-safe commands run only	`tools.exec.mode: "allowlist"`
Ask a human for every new command shape	`tools.exec.mode: "ask"`
Use Codex or OpenClaw auto-review before humans	`tools.exec.mode: "auto"`
Skip host exec approvals entirely	`tools.exec.mode: "full"` plus matching host approvals file
Make non-interactive ACPX sessions write or exec	`plugins.entries.acpx.config.permissionMode: "approve-all"`

If a command still prompts or fails after changing mode, inspect both layers:

openclaw approvals get
openclaw exec-policy show

Host execution uses the stricter result of OpenClaw config and the host-local approvals file. ACPX harness permissions do not relax host execution approvals, and host execution approvals do not relax ACPX harness prompts.