Permission Modes for Host Exec, Codex Guardian, and ACPX Harness Sessions
Learn about permission modes that control agent authority for host commands, file writes, and backend access. Essential for configuring coding agents with practical host access.
Read this when
- Choosing auto, ask, allowlist, full, or deny for command permissions
- Configuring Codex Guardian-reviewed approvals through tools.exec.mode
- Comparing OpenClaw exec approvals with ACPX harness permissions
Permission modes determine the level of authority an agent holds before it can run host commands, write files, or request additional access from a backend harness.
Note
Permission mode is distinct from
tools.exec.host=auto.tools.exec.hostspecifies the execution location for a command.tools.exec.modedetermines how host execution is authorized.
Recommended default
For coding agents that require practical host access without triggering a human prompt for every mistake, use auto:
openclaw config set tools.exec.mode auto
openclaw approvals get
openclaw gateway restart
After that, check the effective policy:
openclaw exec-policy show
OpenClaw host exec modes
The normalized policy surface for host exec is tools.exec.mode. Every mode resolves into a combination of an underlying security (allowlist strictness) and a ask (prompt-on-miss) setting:
| Mode | security / ask | Behavior | Use when |
|---|---|---|---|
deny | deny / off | Block all host execution. | No host commands should be permitted. |
allowlist | allowlist / off | Execute only commands on the allowlist; silently deny anything else. | Your command set is known and safe. |
ask | allowlist / on-miss | Execute allowlisted commands; ask a human for anything not on the list. | Every new command requires human review. |
auto | allowlist / on-miss | Execute allowlisted commands; route misses through auto-review before falling back to a human. | Coding sessions need guarded but practical access. |
full | full / off | Execute host commands without any prompts. | Skip approval gates for this trusted host or session. |
Both ask and auto use the same allowlist and ask settings; auto additionally activates the native auto-reviewer, which handles misses on its own and only escalates to the configured human approval route when it cannot safely approve.
For the complete host exec policy, local approvals file, allowlist schema, safe binaries, and forwarding behavior, refer to Exec approvals.
Codex Guardian mapping
In native Codex app-server sessions, tools.exec.mode: "auto" steers Codex toward Guardian-reviewed approvals when local Codex requirements permit it. Typical resulting values are:
| Codex field | Typical value |
|---|---|
approvalPolicy | on-request |
approvalsReviewer | auto_review |
sandbox | workspace-write |
The auto mode enforces this policy over any configured Codex sandbox or approval overrides, so it does not preserve legacy unsafe combinations like approvalPolicy: "never" with sandbox: "danger-full-access". Local execution in Codex app-server is entirely blocked by tools.exec.mode: "deny" and "allowlist". Only use tools.exec.mode: "full" when you deliberately want a no-approval posture.
For app-server setup, authentication order, and native Codex runtime details, see Codex harness.
ACPX harness permissions
Because ACPX sessions are non-interactive, 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 | Automatically approve read-only operations. |
permissionMode | approve-all | Automatically approve writes and shell commands. |
permissionMode | deny-all | Deny all permission prompts. |
nonInteractivePermissions | fail | Abort when a prompt would be necessary. |
nonInteractivePermissions | deny | Deny the prompt and continue when feasible. |
Configure ACPX permissions independently 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
Treat approve-all as the ACPX break-glass alternative to a no-prompt harness session. Refer to ACP agents setup for configuration instructions and failure scenarios.
Choosing a mode
| Goal | Configure |
|---|---|
| Prevent all host commands from running | tools.exec.mode: "deny" |
| Permit only commands that are known safe | tools.exec.mode: "allowlist" |
| Require human approval for each new command pattern | tools.exec.mode: "ask" |
| Have Codex/OpenClaw auto-review before a human sees it | tools.exec.mode: "auto" |
| Remove all host exec approval requirements | tools.exec.mode: "full" plus matching host approvals file |
| Allow non-interactive ACPX sessions to write and exec | plugins.entries.acpx.config.permissionMode: "approve-all" |
If a command still triggers a prompt or fails after you switch modes, check both layers:
openclaw approvals get
openclaw exec-policy show
Host exec applies the stricter result from the OpenClaw config combined with the host-local approvals file. ACPX harness permissions cannot override host exec approvals, and host exec approvals cannot override ACPX harness prompts.