Skip to main content

​
Does this work out of the box?

Yes, after installing the official ACP runtime plugin:
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.
  • 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.<name> 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.
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 only when the harness should call those tools directly.

​
Supported harness targets

With the acpx backend, use these ids as /acp spawn <id> or sessions_spawn({ runtime: "acp", agentId: "<id>" }) targets: 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.