@@ -0,0 +1,291 @@
1+---
2+summary: "Setting up ACP agents: acpx harness config, plugin setup, permissions"
3+read_when:
4+ - Installing or configuring the acpx harness for Claude Code / Codex / Gemini CLI
5+ - Enabling the plugin-tools or OpenClaw-tools MCP bridge
6+ - Configuring ACP permission modes
7+title: "ACP agents — setup"
8+---
9+10+For the overview, operator runbook, and concepts, see [ACP agents](/tools/acp-agents).
11+This page covers acpx harness config, plugin setup for the MCP bridges, and
12+permission configuration.
13+14+## acpx harness support (current)
15+16+Current acpx built-in harness aliases:
17+18+- `claude`
19+- `codex`
20+- `copilot`
21+- `cursor` (Cursor CLI: `cursor-agent acp`)
22+- `droid`
23+- `gemini`
24+- `iflow`
25+- `kilocode`
26+- `kimi`
27+- `kiro`
28+- `openclaw`
29+- `opencode`
30+- `pi`
31+- `qwen`
32+33+When OpenClaw uses the acpx backend, prefer these values for `agentId` unless your acpx config defines custom agent aliases.
34+If your local Cursor install still exposes ACP as `agent acp`, override the `cursor` agent command in your acpx config instead of changing the built-in default.
35+36+Direct acpx CLI usage can also target arbitrary adapters via `--agent <command>`, but that raw escape hatch is an acpx CLI feature (not the normal OpenClaw `agentId` path).
37+38+## Required config
39+40+Core ACP baseline:
41+42+```json5
43+{
44+ acp: {
45+ enabled: true,
46+// Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
47+ dispatch: { enabled: true },
48+ backend: "acpx",
49+ defaultAgent: "codex",
50+ allowedAgents: [
51+"claude",
52+"codex",
53+"copilot",
54+"cursor",
55+"droid",
56+"gemini",
57+"iflow",
58+"kilocode",
59+"kimi",
60+"kiro",
61+"openclaw",
62+"opencode",
63+"pi",
64+"qwen",
65+ ],
66+ maxConcurrentSessions: 8,
67+ stream: {
68+ coalesceIdleMs: 300,
69+ maxChunkChars: 1200,
70+ },
71+ runtime: {
72+ ttlMinutes: 120,
73+ },
74+ },
75+}
76+```
77+78+Thread binding config is channel-adapter specific. Example for Discord:
79+80+```json5
81+{
82+ session: {
83+ threadBindings: {
84+ enabled: true,
85+ idleHours: 24,
86+ maxAgeHours: 0,
87+ },
88+ },
89+ channels: {
90+ discord: {
91+ threadBindings: {
92+ enabled: true,
93+ spawnAcpSessions: true,
94+ },
95+ },
96+ },
97+}
98+```
99+100+If thread-bound ACP spawn does not work, verify the adapter feature flag first:
101+102+- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
103+104+Current-conversation binds do not require child-thread creation. They require an active conversation context and a channel adapter that exposes ACP conversation bindings.
105+106+See [Configuration Reference](/gateway/configuration-reference).
107+108+## Plugin setup for acpx backend
109+110+Fresh installs ship the bundled `acpx` runtime plugin enabled by default, so ACP
111+usually works without a manual plugin install step.
112+113+Start with:
114+115+```text
116+/acp doctor
117+```
118+119+If you disabled `acpx`, denied it via `plugins.allow` / `plugins.deny`, or want
120+to switch to a local development checkout, use the explicit plugin path:
121+122+```bash
123+openclaw plugins install acpx
124+openclaw config set plugins.entries.acpx.enabled true
125+```
126+127+Local workspace install during development:
128+129+```bash
130+openclaw plugins install ./path/to/local/acpx-plugin
131+```
132+133+Then verify backend health:
134+135+```text
136+/acp doctor
137+```
138+139+### acpx command and version configuration
140+141+By default, the bundled `acpx` plugin uses its plugin-local pinned binary (`node_modules/.bin/acpx` inside the plugin package). Startup registers the backend as not-ready and a background job verifies `acpx --version`; if the binary is missing or mismatched, it runs `npm install --omit=dev --no-save acpx@<pinned>` and re-verifies. The gateway stays non-blocking throughout.
142+143+Override the command or version in plugin config:
144+145+```json
146+{
147+"plugins": {
148+"entries": {
149+"acpx": {
150+"enabled": true,
151+"config": {
152+"command": "../acpx/dist/cli.js",
153+"expectedVersion": "any"
154+ }
155+ }
156+ }
157+ }
158+}
159+```
160+161+- `command` accepts an absolute path, relative path (resolved from the OpenClaw workspace), or command name.
162+- `expectedVersion: "any"` disables strict version matching.
163+- Custom `command` paths disable plugin-local auto-install.
164+165+See [Plugins](/tools/plugin).
166+167+### Automatic dependency install
168+169+When you install OpenClaw globally with `npm install -g openclaw`, the acpx
170+runtime dependencies (platform-specific binaries) are installed automatically
171+via a postinstall hook. If the automatic install fails, the gateway still starts
172+normally and reports the missing dependency through `openclaw acp doctor`.
173+174+### Plugin tools MCP bridge
175+176+By default, ACPX sessions do **not** expose OpenClaw plugin-registered tools to
177+the ACP harness.
178+179+If you want ACP agents such as Codex or Claude Code to call installed
180+OpenClaw plugin tools such as memory recall/store, enable the dedicated bridge:
181+182+```bash
183+openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
184+```
185+186+What this does:
187+188+- Injects a built-in MCP server named `openclaw-plugin-tools` into ACPX session
189+ bootstrap.
190+- Exposes plugin tools already registered by installed and enabled OpenClaw
191+ plugins.
192+- Keeps the feature explicit and default-off.
193+194+Security and trust notes:
195+196+- This expands the ACP harness tool surface.
197+- ACP agents get access only to plugin tools already active in the gateway.
198+- Treat this as the same trust boundary as letting those plugins execute in
199+ OpenClaw itself.
200+- Review installed plugins before enabling it.
201+202+Custom `mcpServers` still work as before. The built-in plugin-tools bridge is an
203+additional opt-in convenience, not a replacement for generic MCP server config.
204+205+### OpenClaw tools MCP bridge
206+207+By default, ACPX sessions also do **not** expose built-in OpenClaw tools through
208+MCP. Enable the separate core-tools bridge when an ACP agent needs selected
209+built-in tools such as `cron`:
210+211+```bash
212+openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true
213+```
214+215+What this does:
216+217+- Injects a built-in MCP server named `openclaw-tools` into ACPX session
218+ bootstrap.
219+- Exposes selected built-in OpenClaw tools. The initial server exposes `cron`.
220+- Keeps core-tool exposure explicit and default-off.
221+222+### Runtime timeout configuration
223+224+The bundled `acpx` plugin defaults embedded runtime turns to a 120-second
225+timeout. This gives slower harnesses such as Gemini CLI enough time to complete
226+ACP startup and initialization. Override it if your host needs a different
227+runtime limit:
228+229+```bash
230+openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
231+```
232+233+Restart the gateway after changing this value.
234+235+### Health probe agent configuration
236+237+The bundled `acpx` plugin probes one harness agent while deciding whether the
238+embedded runtime backend is ready. It defaults to `codex`. If your deployment
239+uses a different default ACP agent, set the probe agent to the same id:
240+241+```bash
242+openclaw config set plugins.entries.acpx.config.probeAgent claude
243+```
244+245+Restart the gateway after changing this value.
246+247+## Permission configuration
248+249+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:
250+251+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.
252+253+### `permissionMode`
254+255+Controls which operations the harness agent can perform without prompting.
256+257+| Value | Behavior |
258+| --------------- | --------------------------------------------------------- |
259+| `approve-all` | Auto-approve all file writes and shell commands. |
260+| `approve-reads` | Auto-approve reads only; writes and exec require prompts. |
261+| `deny-all` | Deny all permission prompts. |
262+263+### `nonInteractivePermissions`
264+265+Controls what happens when a permission prompt would be shown but no interactive TTY is available (which is always the case for ACP sessions).
266+267+| Value | Behavior |
268+| ------ | ----------------------------------------------------------------- |
269+| `fail` | Abort the session with `AcpRuntimeError`. **(default)** |
270+| `deny` | Silently deny the permission and continue (graceful degradation). |
271+272+### Configuration
273+274+Set via plugin config:
275+276+```bash
277+openclaw config set plugins.entries.acpx.config.permissionMode approve-all
278+openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
279+```
280+281+Restart the gateway after changing these values.
282+283+> **Important:** OpenClaw currently defaults to `permissionMode=approve-reads` and `nonInteractivePermissions=fail`. In non-interactive ACP sessions, any write or exec that triggers a permission prompt can fail with `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`.
284+>
285+> If you need to restrict permissions, set `nonInteractivePermissions` to `deny` so sessions degrade gracefully instead of crashing.
286+287+## Related
288+289+- [ACP agents](/tools/acp-agents) — overview, operator runbook, concepts
290+- [Sub-agents](/tools/subagents)
291+- [Multi-agent routing](/concepts/multi-agent)
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。