From dc6190fd0fbcdae5b3ed6ce72ff1a3a040457af3 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Sat, 25 Apr 2026 23:37:39 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@12c16576cd81acfa19514ce7e82a4aee69bddae9 --- .openclaw-sync/source.json | 4 ++-- docs/gateway/configuration-reference.md | 5 +++-- docs/tools/acp-agents.md | 17 ++++++++++------- docs/tools/subagents.md | 2 +- 4 files changed, 16 insertions(+), 12 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index f292d3768..041b5ff2f 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "41b27024bbfc4e42654845c9fc7058ef528dd461", - "syncedAt": "2026-04-25T23:27:30.433Z" + "sha": "12c16576cd81acfa19514ce7e82a4aee69bddae9", + "syncedAt": "2026-04-25T23:36:06.411Z" } diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index 6e4c27b2d..eab8453bf 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -958,7 +958,7 @@ Notes: ```json5 { acp: { - enabled: false, + enabled: true, dispatch: { enabled: true }, backend: "acpx", defaultAgent: "main", @@ -982,9 +982,10 @@ Notes: } ``` -- `enabled`: global ACP feature gate (default: `false`). +- `enabled`: global ACP feature gate (default: `true`; set `false` to hide ACP dispatch and spawn affordances). - `dispatch.enabled`: independent gate for ACP session turn dispatch (default: `true`). Set `false` to keep ACP commands available while blocking execution. - `backend`: default ACP runtime backend id (must match a registered ACP runtime plugin). + If `plugins.allow` is set, include the backend plugin id (for example `acpx`) or the bundled default plugin will not load. - `defaultAgent`: fallback ACP target agent id when spawns do not specify an explicit target. - `allowedAgents`: allowlist of agent ids permitted for ACP runtime sessions; empty means no additional restriction. - `maxConcurrentSessions`: maximum concurrently active ACP sessions. diff --git a/docs/tools/acp-agents.md b/docs/tools/acp-agents.md index a7fa21574..3ce29df5a 100644 --- a/docs/tools/acp-agents.md +++ b/docs/tools/acp-agents.md @@ -37,6 +37,7 @@ Usually, yes. Fresh installs ship the bundled `acpx` runtime plugin enabled by d First-run gotchas: +- If `plugins.allow` is set, it is a restrictive plugin inventory and must include `acpx`; otherwise the bundled default is intentionally blocked and `/acp doctor` reports the missing allowlist entry. - Target harness adapters (Codex, Claude, etc.) may be fetched on demand with `npx` the first time you use them. - Vendor auth still has to exist on the host for that harness. - If the host has no npm or network access, first-run adapter fetches fail until caches are pre-warmed or the adapter is installed another way. @@ -78,12 +79,14 @@ Natural-language triggers that should route to the ACP runtime: OpenClaw picks `runtime: "acp"`, resolves the harness `agentId`, binds to the current conversation or thread when supported, and routes follow-ups to that session until close/expiry. Codex only follows this path when ACP is explicit or the requested background runtime still needs ACP. -For `sessions_spawn`, `runtime: "acp"` targets ACP harness ids such as `codex`, -`claude`, `gemini`, or `opencode`. Do not pass a normal OpenClaw config agent -id from `agents_list` unless that entry is explicitly configured with -`agents.list[].runtime.type="acp"`; otherwise use the default sub-agent runtime. -When an OpenClaw agent is configured with `runtime.type="acp"`, OpenClaw uses -`runtime.acp.agent` as the underlying harness id. +For `sessions_spawn`, `runtime: "acp"` is advertised only when ACP is enabled, +the requester is not sandboxed, and an ACP runtime backend is loaded. It targets +ACP harness ids such as `codex`, `claude`, `gemini`, or `opencode`. Do not pass +a normal OpenClaw config agent id from `agents_list` unless that entry is +explicitly configured with `agents.list[].runtime.type="acp"`; otherwise use +the default sub-agent runtime. When an OpenClaw agent is configured with +`runtime.type="acp"`, OpenClaw uses `runtime.acp.agent` as the underlying +harness id. ## ACP versus sub-agents @@ -551,7 +554,7 @@ plugin-tools and OpenClaw-tools MCP bridges, and ACP permission modes, see | Symptom | Likely cause | Fix | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ACP runtime backend is not configured` | Backend plugin missing or disabled. | Install and enable backend plugin, then run `/acp doctor`. | +| `ACP runtime backend is not configured` | Backend plugin missing, disabled, or blocked by `plugins.allow`. | Install and enable backend plugin, include `acpx` in `plugins.allow` when that allowlist is set, then run `/acp doctor`. | | `ACP is disabled by policy (acp.enabled=false)` | ACP globally disabled. | Set `acp.enabled=true`. | | `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Dispatch from normal thread messages disabled. | Set `acp.dispatch.enabled=true`. | | `ACP agent "" is not allowed by policy` | Agent not in allowlist. | Use allowed `agentId` or update `acp.allowedAgents`. | diff --git a/docs/tools/subagents.md b/docs/tools/subagents.md index 899be1c9d..9c9132c96 100644 --- a/docs/tools/subagents.md +++ b/docs/tools/subagents.md @@ -60,7 +60,7 @@ transcript path on disk when you need the raw full transcript. - `--model` and `--thinking` override defaults for that specific run. - Use `info`/`log` to inspect details and output after completion. - `/subagents spawn` is one-shot mode (`mode: "run"`). For persistent thread-bound sessions, use `sessions_spawn` with `thread: true` and `mode: "session"`. -- For ACP harness sessions (Codex, Claude Code, Gemini CLI, OpenCode), use `sessions_spawn` with `runtime: "acp"` and see [ACP Agents](/tools/acp-agents), especially the [ACP delivery model](/tools/acp-agents#delivery-model) when debugging completions or agent-to-agent loops. `runtime: "acp"` expects an external ACP harness id, or an `agents.list[]` entry with `runtime.type="acp"`; use the default sub-agent runtime for normal OpenClaw config agents from `agents_list`. +- For ACP harness sessions (Codex, Claude Code, Gemini CLI, OpenCode), use `sessions_spawn` with `runtime: "acp"` when the tool advertises that runtime, and see [ACP Agents](/tools/acp-agents), especially the [ACP delivery model](/tools/acp-agents#delivery-model) when debugging completions or agent-to-agent loops. OpenClaw hides `runtime: "acp"` until ACP is enabled, the requester is not sandboxed, and a backend plugin such as `acpx` is loaded. `runtime: "acp"` expects an external ACP harness id, or an `agents.list[]` entry with `runtime.type="acp"`; use the default sub-agent runtime for normal OpenClaw config agents from `agents_list`. Primary goals: