vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 16:40:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix: gate acp spawn affordances

Browse Source
This commit is contained in:
Peter Steinberger
2026-04-26 00:30:02 +01:00
parent d228463120
commit 12c16576cd
17 changed files with 368 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/gateway/configuration-reference.md
View File

@@ -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.

17
docs/tools/acp-agents.md
View File

@@ -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 "<id>" is not allowed by policy` | Agent not in allowlist. | Use allowed `agentId` or update `acp.allowedAgents`. |

2
docs/tools/subagents.md
View File

@@ -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: