From 5474796735aeb17c76cecf047c9b014cf2f8096e Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Tue, 31 Mar 2026 20:53:27 +0900
Subject: [PATCH] docs(security): clarify acpx yolo mode

---
 docs/cli/acp.md                        |  1 +
 docs/gateway/security/index.md         |  1 +
 docs/tools/acp-agents.md               |  2 ++
 src/security/audit.test.ts             | 16 ++++++++++++++++
 src/security/dangerous-config-flags.ts |  3 +++
 5 files changed, 23 insertions(+)

diff --git a/docs/cli/acp.md b/docs/cli/acp.md
index 76566879d1e..429862407c2 100644
--- a/docs/cli/acp.md
+++ b/docs/cli/acp.md
@@ -102,6 +102,7 @@ Permission model (client debug mode):
 - `read` auto-approval is scoped to the current working directory (`--cwd` when set).
 - ACP only auto-approves narrow readonly classes: scoped `read` calls under the active cwd plus readonly search tools (`search`, `web_search`, `memory_search`). Unknown/non-core tools, out-of-scope reads, exec-capable tools, control-plane tools, mutating tools, and interactive flows always require explicit prompt approval.
 - Server-provided `toolCall.kind` is treated as untrusted metadata (not an authorization source).
+- This ACP bridge policy is separate from ACPX harness permissions. If you run OpenClaw through the `acpx` backend, `plugins.entries.acpx.config.permissionMode=approve-all` is the break-glass “yolo” switch for that harness session.
 
 ## How to use this
 
diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md
index 0ffe4ba381a..db8cfc8bb6a 100644
--- a/docs/gateway/security/index.md
+++ b/docs/gateway/security/index.md
@@ -285,6 +285,7 @@ aggregates:
 - `hooks.gmail.allowUnsafeExternalContent=true`
 - `hooks.mappings[<index>].allowUnsafeExternalContent=true`
 - `tools.exec.applyPatch.workspaceOnly=false`
+- `plugins.entries.acpx.config.permissionMode=approve-all`
 
 Complete `dangerous*` / `dangerously*` config keys defined in OpenClaw config
 schema:
diff --git a/docs/tools/acp-agents.md b/docs/tools/acp-agents.md
index ae7d34cd220..ae987cd24db 100644
--- a/docs/tools/acp-agents.md
+++ b/docs/tools/acp-agents.md
@@ -714,6 +714,8 @@ additional opt-in convenience, not a replacement for generic MCP server config.
 
 ACP sessions run non-interactively — there is no TTY to approve or deny file-write and shell-exec permission prompts. The acpx plugin provides two config keys that control how permissions are handled:
 
+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.
+
 ### `permissionMode`
 
 Controls which operations the harness agent can perform without prompting.
diff --git a/src/security/audit.test.ts b/src/security/audit.test.ts
index bb8c8e652df..527cbcb276d 100644
--- a/src/security/audit.test.ts
+++ b/src/security/audit.test.ts
@@ -1838,6 +1838,22 @@ description: test skill
           "tools.exec.applyPatch.workspaceOnly=false",
         ],
       },
+      {
+        name: "acpx approve-all is treated as a dangerous break-glass flag",
+        cfg: {
+          plugins: {
+            entries: {
+              acpx: {
+                enabled: true,
+                config: {
+                  permissionMode: "approve-all",
+                },
+              },
+            },
+          },
+        } satisfies OpenClawConfig,
+        expectedDangerousDetails: ["plugins.entries.acpx.config.permissionMode=approve-all"],
+      },
     ] as const;
 
     await runConfigAuditCases(cases, (res, testCase) => {
diff --git a/src/security/dangerous-config-flags.ts b/src/security/dangerous-config-flags.ts
index 1dbbd39cc31..0e2a702c089 100644
--- a/src/security/dangerous-config-flags.ts
+++ b/src/security/dangerous-config-flags.ts
@@ -24,5 +24,8 @@ export function collectEnabledInsecureOrDangerousFlags(cfg: OpenClawConfig): str
   if (cfg.tools?.exec?.applyPatch?.workspaceOnly === false) {
     enabledFlags.push("tools.exec.applyPatch.workspaceOnly=false");
   }
+  if (cfg.plugins?.entries?.acpx?.config?.permissionMode === "approve-all") {
+    enabledFlags.push("plugins.entries.acpx.config.permissionMode=approve-all");
+  }
   return enabledFlags;
 }