Does this work out of the box?

Yes, after installing the official ACP runtime plugin:

apus plugins install @openclaw/acpx
apus 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.

Apus 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 Apus state directory (APUS_STATE_DIR, normally ~/.apus). 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 <workspace>/state default are migrated automatically at ACPX startup or by apus 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`. Apus 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.
Runtime prerequisites 
ACP launches a real external harness process. Apus owns routing,
background-task state, delivery, bindings, and policy; the harness owns
its provider login, model catalog, filesystem behavior, and native tools.

Before blaming Apus, 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.

Apus plugin tools and built-in Apus 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:

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.
apus Apus Gateway bridge through apus acp Lets an ACP-aware harness talk back to an Apus 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 Apus policy still checks acp.allowedAgents and any agents.entries.*.runtime.acp.agent mapping before dispatch.