diff --git a/docs/docs.json b/docs/docs.json index 2fc2fcf69351..803027d9b2c4 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1280,6 +1280,7 @@ "tools/code-execution", "tools/diffs", "tools/elevated", + "tools/permission-modes", "tools/exec-approvals", "tools/exec-approvals-advanced", "tools/exec", diff --git a/docs/plugins/codex-harness.md b/docs/plugins/codex-harness.md index b2a358582b28..4412e1db417a 100644 --- a/docs/plugins/codex-harness.md +++ b/docs/plugins/codex-harness.md @@ -393,6 +393,9 @@ In `tools.exec.mode: "auto"`, OpenClaw does not preserve legacy unsafe Codex legacy `plugins.entries.codex.config.appServer.mode: "guardian"` preset still works, but `tools.exec.mode: "auto"` is the normalized OpenClaw surface. +For the mode-level comparison with host exec approvals and ACPX permissions, +see [Permission modes](/tools/permission-modes). + For every app-server field, auth order, environment isolation, discovery, and timeout behavior, see [Codex harness reference](/plugins/codex-harness-reference). diff --git a/docs/tools/acp-agents-setup.md b/docs/tools/acp-agents-setup.md index d59faa75b6cf..b4a786de4213 100644 --- a/docs/tools/acp-agents-setup.md +++ b/docs/tools/acp-agents-setup.md @@ -308,6 +308,10 @@ ACP sessions run non-interactively — there is no TTY to approve or deny file-w These ACPX harness permissions are separate from OpenClaw exec approvals and separate from CLI-backend vendor bypass flags such as Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` is the harness-level break-glass switch for ACP sessions. +For the broader comparison between OpenClaw `tools.exec.mode`, Codex Guardian +approvals, and ACPX harness permissions, see +[Permission modes](/tools/permission-modes). + ### `permissionMode` Controls which operations the harness agent can perform without prompting. diff --git a/docs/tools/exec-approvals.md b/docs/tools/exec-approvals.md index a1a0af551842..d71c521f6f10 100644 --- a/docs/tools/exec-approvals.md +++ b/docs/tools/exec-approvals.md @@ -15,6 +15,10 @@ safety interlock: commands are allowed only when policy + allowlist + tool policy and elevated gating (unless elevated is set to `full`, which skips approvals). +For a mode-first overview of `deny`, `allowlist`, `ask`, `auto`, `full`, +Codex Guardian mapping, and ACPX harness permissions, see +[Permission modes](/tools/permission-modes). + Effective policy is the **stricter** of `tools.exec.*` and approvals defaults; if an approvals field is omitted, the `tools.exec` value is diff --git a/docs/tools/permission-modes.md b/docs/tools/permission-modes.md new file mode 100644 index 000000000000..1c101db588be --- /dev/null +++ b/docs/tools/permission-modes.md @@ -0,0 +1,111 @@ +--- +summary: "Permission modes for host exec, Codex Guardian approvals, and ACPX harness sessions" +read_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 +title: "Permission modes" +--- + +Permission modes decide how much authority an agent has before it can run host commands, write files, or ask a backend harness for extra access. Start with `tools.exec.mode: "auto"` when you want OpenClaw to use allowlists first, then Codex native auto-review or a human approval route for misses. + + + Permission mode is separate from `tools.exec.host=auto`. `tools.exec.host` + chooses where a command runs. `tools.exec.mode` chooses how host exec is + approved. + + +## Recommended default + +Use `auto` for coding agents that need useful host access without making every miss a human prompt: + +```bash +openclaw config set tools.exec.mode auto +openclaw approvals get +openclaw gateway restart +``` + +Then verify the effective policy: + +```bash +openclaw exec-policy show +``` + +In `auto` mode, OpenClaw runs deterministic allowlist matches directly. Approval misses go through OpenClaw's native auto reviewer first, then fall back to the configured human approval route when needed. + +## OpenClaw host exec modes + +`tools.exec.mode` is the normalized policy surface for host `exec`. + +| Mode | Behavior | Use when | +| ----------- | -------------------------------------------- | ----------------------------------------------------- | +| `deny` | Block host exec. | No host commands are allowed. | +| `allowlist` | Run only allowlisted commands. | You have a known-safe command set. | +| `ask` | Run allowlist matches and ask on misses. | A human should review new commands. | +| `auto` | Run allowlist matches, then use auto-review. | Coding sessions need practical guarded access. | +| `full` | Run host exec without prompts. | This trusted host/session should skip approval gates. | + +For the full host exec policy, local approvals file, allowlist schema, safe bins, and forwarding behavior, see [Exec approvals](/tools/exec-approvals). + +## Codex Guardian mapping + +For native Codex app-server sessions, `tools.exec.mode: "auto"` maps to Codex Guardian-reviewed approvals when the local Codex requirements allow it. OpenClaw usually sends: + +| Codex field | Typical value | +| ------------------- | ----------------- | +| `approvalPolicy` | `on-request` | +| `approvalsReviewer` | `auto_review` | +| `sandbox` | `workspace-write` | + +In `auto` mode, OpenClaw does not preserve legacy unsafe Codex overrides such as `approvalPolicy: "never"` or `sandbox: "danger-full-access"`. 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](/plugins/codex-harness). + +## ACPX harness permissions + +ACPX sessions are non-interactive, so they cannot click a TTY permission prompt. ACPX uses separate harness-level settings under `plugins.entries.acpx.config`: + +| Setting | Common value | 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: + +```bash +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](/tools/acp-agents-setup#permission-configuration). + +## 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/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/exec | `plugins.entries.acpx.config.permissionMode: "approve-all"` | + +If a command still prompts or fails after changing mode, inspect both layers: + +```bash +openclaw approvals get +openclaw exec-policy show +``` + +Host exec uses the stricter result of OpenClaw config and the host-local approvals file. ACPX harness permissions do not loosen host exec approvals, and host exec approvals do not loosen ACPX harness prompts. + +## Related + +- [Exec approvals](/tools/exec-approvals) +- [Exec approvals - advanced](/tools/exec-approvals-advanced) +- [Codex harness](/plugins/codex-harness) +- [ACP agents setup](/tools/acp-agents-setup#permission-configuration)