OpenClaw ACP agents

You want to drive Claude Code or Gemini CLI from a Telegram message instead of a terminal, and OpenClaw can do that over the Agent Client Protocol. An ACP session launches the real external harness as a process on the Gateway host, tracks each spawn as a background task, and can bind a conversation or a thread so follow-ups keep reaching the same harness. It needs a runtime plugin first, and a short list of conditions decides whether your agent is ever told the path exists.

Installing the acpx runtime plugin

• Packaged installs use the official acpx runtime plugin, published under the openclaw scope on npm, and it is two commands: openclaw plugins install, naming that scoped package, then openclaw config set plugins.entries.acpx.enabled true. Source checkouts can use the local extensions/acpx workspace plugin after pnpm install instead. Run /acp doctor afterwards for a readiness check, or /acp install to have OpenClaw print the deterministic install and enable steps.
• If plugins.allow is set, it is a restrictive plugin inventory rather than a hint, and it must include acpx or the installed ACP backend is intentionally blocked. That is the first-run failure most often misread as a broken install, surfacing as the error saying the ACP runtime backend is not configured; /acp doctor reports the missing allowlist entry instead of leaving you to guess.
• The acpx plugin embeds the ACP runtime directly, so there is no separate acpx binary or version to configure. It registers the embedded backend during Gateway startup and waits for one health probe before the gateway ready signal, and that probe also supplies the failure diagnostics. It is bounded by plugins.entries.acpx.config.timeoutSeconds, which defaults to 120 seconds so slower harnesses such as Gemini CLI can finish ACP startup and initialisation.
• The Codex ACP adapter ships with the acpx plugin and launches locally when possible, running with an isolated CODEX_HOME into which OpenClaw copies trusted project trust entries plus safe model and provider routing config, while auth, notifications and hooks stay on the host config only. Other harness adapters may be fetched on demand with npx on first use, so a host without npm or network access fails those fetches until caches are pre-warmed or the adapter is installed another way.

If any condition fails, ACP skills and sessions_spawn ACP guidance stay hidden so the agent does not suggest an unavailable backend.

Why the ACP skills can be invisible

The conditions are listed in full: 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. An agent that has never once offered an ACP spawn is usually reporting its own configuration accurately rather than ignoring you. The two halves fail differently: acp.dispatch.enabled=false pauses automatic ACP thread dispatch without hiding or blocking an explicit sessions_spawn call with runtime acp, while a sandboxed requester is refused outright because the ACP runtime is host-side. From a sandboxed session the documented answer is the subagent runtime.

The prerequisites checklist

• Before blaming OpenClaw, confirm that /acp doctor reports an enabled and healthy backend, that the target id is allowed by acp.allowedAgents when that allowlist is set, and that the harness command can actually start on the Gateway host. Each of those has its own error text rather than one generic failure, so the message you get already narrows the cause.
• Provider auth must already exist on the host for the harness you are targeting: claude, codex, gemini, opencode, droid and the rest each own their own login. A vendor auth error means OpenClaw is healthy and the target CLI or provider simply is not logged in, which you fix by logging in or providing the provider key in the Gateway host environment, not by editing OpenClaw config.
• The selected model must exist for that harness, because model ids are not portable across harnesses, and model control is adapter-capability dependent: a harness that advertises neither the ACP models capability nor its own startup model flag cannot be forced onto a model at all. The requested cwd must exist and be accessible, or you omit it and let the backend use its default.

One thing decides the choice before you write any config: OpenClaw plugin tools and built-in OpenClaw tools are not exposed to ACP harnesses by default, and the two MCP bridges that change that are explicit and off by default. If what you want is an OpenClaw-native delegated run with OpenClaw's own tools, that is a OpenClaw sub-agents run, with its own session key and its own slash command; if you only want a local AI CLI as a text-only fallback model, OpenClaw CLI backends are neither ACP nor a harness runtime, with no OpenClaw tools and no ACP controls.

The seventeen harness target ids

With the acpx backend these are the ids you pass to /acp spawn or to sessions_spawn as agentId: claude, codex, copilot, cursor, droid, fast-agent, gemini, iflow, kilocode, kimi, kiro, mux, opencode, openclaw, qoder, qwen and trae. claude wants Claude Code auth on the host, copilot a Copilot CLI or runtime login, cursor runs cursor-agent acp, droid wants Factory or Droid auth or FACTORY_API_KEY in the harness environment, gemini wants Gemini CLI auth or API key setup, opencode wants OpenCode CLI or provider auth, and openclaw is the Gateway bridge that lets an ACP-aware harness talk back to an OpenClaw Gateway session. codex is the explicit ACP fallback, used only when the native /codex path is unavailable or when ACP is asked for by name. pi is registered in the acpx backend too but is not a coding harness in the same sense. Every spawn lands in OpenClaw background tasks, and OpenClaw permission modes is where the harness-level settings sit beside OpenClaw exec approvals: an ACP session has no interactive TTY, so write-heavy and exec-heavy coding usually needs a profile that can proceed headlessly.

On Diali

Diali hosts OpenClaw for you, and each customer runs their own assistant rather than a slice of a shared one. The runtime configuration is generated from the dashboard and replaced at each release, so policy keys are written for you instead of hand-edited on a box you have to remember. State lives on a persistent volume, which is what keeps a session and its history across an upgrade; daily snapshots and one-click restore are available through the Backups add-on (included on Max). Hosted OpenClaw on Diali sets out what the hosted runtime covers and Diali pricing has the plans.

• Two commands install acpx, then /acp doctor before anything else.
• Hidden ACP guidance means a failed condition, not a missing feature.
• Seventeen harness ids, each with its own host login.