# ACP agents quickstart > Install the acpx ACP runtime plugin, confirm it is usable, and pick a harness target id - 网址：https://funcoding.ai/agents/openclaw/tools/acp-agents/quickstart/ - 来源：OpenClaw 官方文档原文（英文），MIT 许可，同步于 2026-10-11 - 官方原文：https://docs.openclaw.ai/zh-CN/tools/acp-agents/quickstart --- ## Does this work out of the box? Yes, after installing the official ACP runtime plugin: ```bash openclaw plugins install @openclaw/acpx openclaw config set plugins.entries.acpx.enabled true ``` Source checkouts can use the local `extensions/acpx` workspace plugin after `pnpm install`. Run `/acp doctor` for a readiness check. OpenClaw only teaches agents about ACP spawning when ACP is **truly usable**: ACP must be enabled, dispatch must not be disabled, the current session must not be sandbox-blocked, and a runtime backend must be loaded and healthy. If any condition fails, ACP skills and `sessions_spawn` ACP guidance stay hidden so the agent does not suggest an unavailable backend. ACP policy changes apply without restarting the Gateway. Enablement, dispatch, the default agent, and allowed agents govern new admissions; backend and fallback settings govern subsequent turns. Admitted turns retain their session ownership. The ACPX health check selects from the current allowed agents unless its plugin config sets an explicit `probeAgent`. ACPX session state defaults to `acpx/` inside the OpenClaw state directory (`OPENCLAW_STATE_DIR`, normally `~/.openclaw`). The working directory and installed package directory do not need to be writable for session resets. An explicit `plugins.entries.acpx.config.stateDir` still overrides this location. Sessions in the former `/state` default are migrated automatically at ACPX startup or by `openclaw doctor --fix` when the new default is empty. Set `stateDir` only if you want to keep the old location. If migration fails, ACPX warns and keeps using the old location for that process; the warning names the override to set.
First-run gotchas - If `plugins.allow` is set, it is a restrictive plugin inventory and **must** include `acpx`, or the installed ACP backend is intentionally blocked (`/acp doctor` reports the missing allowlist entry). - The Codex ACP adapter ships with the `acpx` plugin and launches locally when possible. - Codex ACP runs with an isolated `CODEX_HOME`. OpenClaw copies trusted project trust entries plus safe model/provider routing config (`model`, `model_provider`, `model_reasoning_effort`, `sandbox_mode`, and safe `model_providers.` fields) from the host Codex config; auth, notifications, and hooks stay on the host config only. - Other target harness adapters may be fetched on demand with `npx` on first use. - Vendor auth must already 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.
Runtime prerequisites ACP launches a real external harness process. OpenClaw owns routing, background-task state, delivery, bindings, and policy; the harness owns its provider login, model catalog, filesystem behavior, and native tools. Before blaming OpenClaw, verify: - `/acp doctor` reports an enabled, healthy backend. - The target id is allowed by `acp.allowedAgents` when that allowlist is set. - The harness command can start on the Gateway host. - Provider auth is present for that harness (`claude`, `codex`, `gemini`, `opencode`, `droid`, etc.). - The selected model exists for that harness - model ids are not portable across harnesses. - The requested `cwd` exists and is accessible, or omit `cwd` and let the backend use its default. - Permission mode matches the work. Non-interactive sessions cannot click native permission prompts, so write/exec-heavy coding runs usually need an ACPX permission profile that can proceed headlessly.
OpenClaw plugin tools and built-in OpenClaw tools are **not** exposed to ACP harnesses by default. Enable the explicit MCP bridges in [ACP agents - setup](https://funcoding.ai/agents/openclaw/tools/acp-agents-setup/) only when the harness should call those tools directly. ## Supported harness targets With the `acpx` backend, use these ids as `/acp spawn ` or `sessions_spawn({ runtime: "acp", agentId: "" })` targets: | Harness id | Typical backend | Notes | | ------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------- | | `claude` | Claude Code ACP adapter | Requires Claude Code auth on the host. | | `codex` | Codex ACP adapter | Explicit ACP fallback only when native `/codex` is unavailable or ACP is requested. | | `copilot` | GitHub Copilot ACP adapter | Requires Copilot CLI/runtime auth. | | `cursor` | Cursor CLI ACP (`cursor-agent acp`) | Override the acpx command if a local install exposes a different ACP entrypoint. | | `droid` | Factory Droid CLI | Requires Factory/Droid auth or `FACTORY_API_KEY` in the harness environment. | | `fast-agent` | fast-agent-mcp ACP adapter | Fetched on demand with `uvx`. | | `gemini` | Gemini CLI ACP adapter | Requires Gemini CLI auth or API key setup. | | `iflow` | iFlow CLI | Adapter availability and model control depend on the installed CLI. | | `kilocode` | Kilo Code CLI | Adapter availability and model control depend on the installed CLI. | | `kimi` | Kimi/Moonshot CLI | Requires Kimi/Moonshot auth on the host. | | `kiro` | Kiro CLI | Adapter availability and model control depend on the installed CLI. | | `mux` | Mux CLI ACP adapter | Fetched on demand with `npx`. | | `opencode` | OpenCode ACP adapter | Requires OpenCode CLI/provider auth. | | `openclaw` | OpenClaw Gateway bridge through `openclaw acp` | Lets an ACP-aware harness talk back to an OpenClaw Gateway session. | | `qoder` | Qoder CLI | Adapter availability and model control depend on the installed CLI. | | `qwen` | Qwen Code / Qwen CLI | Requires Qwen-compatible auth on the host. | | `trae` | Trae CLI ACP adapter | Adapter availability and model control depend on the installed CLI. | `pi` (pi-acp) is also registered in the acpx backend but is not a coding harness in the same sense as the others above. Custom acpx agent aliases can be configured in acpx itself, but OpenClaw policy still checks `acp.allowedAgents` and any `agents.entries.*.runtime.acp.agent` mapping before dispatch.