From 36dfd462a8077b0a2300c2dd8c055e888dd0706f Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Tue, 3 Mar 2026 00:47:25 +0000
Subject: [PATCH] feat(acp): enable dispatch by default

---
 CHANGELOG.md              | 1 +
 docs/tools/acp-agents.md  | 3 ++-
 src/acp/policy.test.ts    | 6 +++---
 src/acp/policy.ts         | 3 ++-
 src/config/schema.help.ts | 2 +-
 5 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4ba97974cd9..80bcd534a81 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -28,6 +28,7 @@ Docs: https://docs.openclaw.ai
 - **BREAKING:** Plugin SDK removed `api.registerHttpHandler(...)`. Plugins must register explicit HTTP routes via `api.registerHttpRoute({ path, auth, match, handler })`, and dynamic webhook lifecycles should use `registerPluginHttpRoute(...)`.
 - **BREAKING:** Zalo Personal plugin (`@openclaw/zalouser`) no longer depends on external `zca`-compatible CLI binaries (`openzca`, `zca-cli`) for runtime send/listen/login; operators should use `openclaw channels login --channel zalouser` after upgrade to refresh sessions in the new JS-native path.
 - **BREAKING:** Onboarding now defaults `tools.profile` to `messaging` for new local installs (interactive + non-interactive). New setups no longer start with broad coding/system tools unless explicitly configured.
+- **BREAKING:** ACP dispatch now defaults to enabled unless explicitly disabled (`acp.dispatch.enabled=false`). If you need to pause ACP turn routing while keeping `/acp` controls, set `acp.dispatch.enabled=false`. Docs: https://docs.openclaw.ai/tools/acp-agents
 
 ### Fixes
 
diff --git a/docs/tools/acp-agents.md b/docs/tools/acp-agents.md
index fe4827a266e..0eb36a43c09 100644
--- a/docs/tools/acp-agents.md
+++ b/docs/tools/acp-agents.md
@@ -75,7 +75,7 @@ Thread binding support is adapter-specific. If the active channel adapter does n
 Required feature flags for thread-bound ACP:
 
 - `acp.enabled=true`
-- `acp.dispatch.enabled=true`
+- `acp.dispatch.enabled` is on by default (set `false` to pause ACP dispatch)
 - Channel-adapter ACP thread-spawn flag enabled (adapter-specific)
   - Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
 
@@ -249,6 +249,7 @@ Core ACP baseline:
 {
   acp: {
     enabled: true,
+    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
     dispatch: { enabled: true },
     backend: "acpx",
     defaultAgent: "codex",
diff --git a/src/acp/policy.test.ts b/src/acp/policy.test.ts
index 3a623373a7b..b88334b1376 100644
--- a/src/acp/policy.test.ts
+++ b/src/acp/policy.test.ts
@@ -11,11 +11,11 @@ import {
 } from "./policy.js";
 
 describe("acp policy", () => {
-  it("treats ACP as enabled by default", () => {
+  it("treats ACP + ACP dispatch as enabled by default", () => {
     const cfg = {} satisfies OpenClawConfig;
     expect(isAcpEnabledByPolicy(cfg)).toBe(true);
-    expect(isAcpDispatchEnabledByPolicy(cfg)).toBe(false);
-    expect(resolveAcpDispatchPolicyState(cfg)).toBe("dispatch_disabled");
+    expect(isAcpDispatchEnabledByPolicy(cfg)).toBe(true);
+    expect(resolveAcpDispatchPolicyState(cfg)).toBe("enabled");
   });
 
   it("reports ACP disabled state when acp.enabled is false", () => {
diff --git a/src/acp/policy.ts b/src/acp/policy.ts
index 8297783b62d..c752828ffdc 100644
--- a/src/acp/policy.ts
+++ b/src/acp/policy.ts
@@ -16,7 +16,8 @@ export function resolveAcpDispatchPolicyState(cfg: OpenClawConfig): AcpDispatchP
   if (!isAcpEnabledByPolicy(cfg)) {
     return "acp_disabled";
   }
-  if (cfg.acp?.dispatch?.enabled !== true) {
+  // ACP dispatch is enabled unless explicitly disabled.
+  if (cfg.acp?.dispatch?.enabled === false) {
     return "dispatch_disabled";
   }
   return "enabled";
diff --git a/src/config/schema.help.ts b/src/config/schema.help.ts
index f64d90aedd0..3e4d558f349 100644
--- a/src/config/schema.help.ts
+++ b/src/config/schema.help.ts
@@ -163,7 +163,7 @@ export const FIELD_HELP: Record<string, string> = {
   "acp.enabled":
     "Global ACP feature gate. Keep disabled unless ACP runtime + policy are configured.",
   "acp.dispatch.enabled":
-    "Independent dispatch gate for ACP session turns. Disable to keep ACP commands available while blocking ACP turn execution.",
+    "Independent dispatch gate for ACP session turns (default: true). Set false to keep ACP commands available while blocking ACP turn execution.",
   "acp.backend":
     "Default ACP runtime backend id (for example: acpx). Must match a registered ACP runtime plugin backend.",
   "acp.defaultAgent":