ACP agents

• If plugins.allow is set, it is a restrictive plugin inventory and must include acpx; otherwise the installed ACP backend is intentionally blocked and /acp doctor reports the missing allowlist entry.
• The Codex ACP adapter is staged with the acpx plugin and launched locally when possible.
• Codex ACP runs with an isolated CODEX_HOME; OpenClaw copies only trusted project entries from the host Codex config and trusts the active workspace, leaving auth, notifications, and hooks on the host config.
• Other target harness adapters may still be fetched on demand with npx the first time you use them.
• Vendor auth still has to 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.

• Spawn creates or resumes an ACP runtime session, records ACP metadata in the OpenClaw session store, and may create a background task when the run is parent-owned.
• Parent-owned ACP sessions are treated as background work even when the runtime session is persistent; completion and cross-surface delivery go through the parent task notifier rather than acting like a normal user-facing chat session.
• Task maintenance closes terminal or orphaned parent-owned one-shot ACP sessions. Persistent ACP sessions are preserved while an active conversation binding remains; stale persistent sessions without an active binding are closed so they cannot be silently resumed after the owning task is done or its task record is gone.
• Bound follow-up messages go directly to the ACP session until the binding is closed, unfocused, reset, or expired.
• Gateway commands stay local. /acp ..., /status, and /unfocus are never sent as normal prompt text to a bound ACP harness.
• cancel aborts the active turn when the backend supports cancellation; it does not delete the binding or session metadata.
• close ends the ACP session from OpenClaw's point of view and removes the binding. A harness may still keep its own upstream history if it supports resume.
• The acpx plugin cleans up OpenClaw-owned wrapper and adapter process trees after close, and reaps stale OpenClaw-owned ACPX orphans during Gateway startup.
• Idle runtime workers are eligible for cleanup after acp.runtime.ttlMinutes; stored session metadata remains available for /acp sessions.

Natural-language triggers that should route to the native Codex plugin when it is enabled:

• "Bind this Discord channel to Codex."
• "Attach this chat to Codex thread <id>."
• "Show Codex threads, then bind this one."

Native Codex conversation binding is the default chat-control path. OpenClaw dynamic tools still execute through OpenClaw, while Codex-native tools such as shell/apply-patch execute inside Codex. For Codex-native tool events, OpenClaw injects a per-turn native hook relay so plugin hooks can block before_tool_call, observe after_tool_call, and route Codex PermissionRequest events through OpenClaw approvals. Codex Stop hooks are relayed to OpenClaw before_agent_finalize, where plugins can request one more model pass before Codex finalizes its answer. The relay remains deliberately conservative: it does not mutate Codex-native tool arguments or rewrite Codex thread records. Use explicit ACP only when you want the ACP runtime/session model. The embedded Codex support boundary is documented in the Codex harness v1 support contract.

• openai-codex/* - legacy Codex OAuth/subscription model route repaired by doctor.
• openai/* - native Codex app-server embedded runtime for OpenAI agent turns.
• /codex ... - native Codex conversation control.
• /acp ... or runtime: "acp" - explicit ACP/acpx control.

Triggers that should route to the ACP runtime:

• "Run this as a one-shot Claude Code ACP session and summarize the result."
• "Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread."
• "Run Codex through ACP in a background thread."

OpenClaw picks runtime: "acp", resolves the harness agentId, binds to the current conversation or thread when supported, and routes follow-ups to that session until close/expiry. Codex only follows this path when ACP/acpx is explicit or the native Codex plugin is unavailable for the requested operation.

For sessions_spawn, runtime: "acp" is advertised only when ACP is enabled, the requester is not sandboxed, and an ACP runtime backend is loaded. acp.dispatch.enabled=false pauses automatic ACP thread dispatch but does not hide or block explicit sessions_spawn({ runtime: "acp" }) calls. It targets ACP harness ids such as codex, claude, droid, gemini, or opencode. Do not pass a normal OpenClaw config agent id from agents_list unless that entry is explicitly configured with agents.list[].runtime.type="acp"; otherwise use the default sub-agent runtime. When an OpenClaw agent is configured with runtime.type="acp", OpenClaw uses runtime.acp.agent as the underlying harness id.

• --bind here and --thread ... are mutually exclusive.
• --bind here only works on channels that advertise current-conversation binding; OpenClaw returns a clear unsupported message otherwise. Bindings persist across gateway restarts.
• On Discord, spawnSessions gates child thread creation for --thread auto|here - not --bind here.
• If you spawn to a different ACP agent without --cwd, OpenClaw inherits the target agent's workspace by default. Missing inherited paths (ENOENT/ENOTDIR) fall back to the backend default; other access errors (e.g. EACCES) surface as spawn errors.
• Gateway management commands stay local in bound conversations - /acp ... commands are handled by OpenClaw even when normal follow-up text routes to the bound ACP session; /status and /unfocus also stay local whenever command handling is enabled for that surface.

When thread bindings are enabled for a channel adapter:

• OpenClaw binds a thread to a target ACP session.
• Follow-up messages in that thread route to the bound ACP session.
• ACP output is delivered back to the same thread.
• Unfocus/close/archive/idle-timeout or max-age expiry removes the binding.
• /acp close, /acp cancel, /acp status, /status, and /unfocus are Gateway commands, not prompts to the ACP harness.

Required feature flags for thread-bound ACP:

• acp.enabled=true
• acp.dispatch.enabled is on by default (set false to pause automatic ACP thread dispatch; explicit sessions_spawn({ runtime: "acp" }) calls still work).
• Channel-adapter thread session spawns enabled (default: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

Thread binding support is adapter-specific. If the active channel adapter does not support thread bindings, OpenClaw returns a clear unsupported/unavailable message.

• Any channel adapter that exposes session/thread binding capability.
• Current built-in support: Discord threads/channels, Telegram topics (forum topics in groups/supergroups and DM topics).
• Plugin channels can add support through the same binding interface.

Interactive sessions are meant to keep talking on a visible chat surface:

• /acp spawn ... --bind here binds the current conversation to the ACP session.
• /acp spawn ... --thread ... binds a channel thread/topic to the ACP session.
• Persistent configured bindings[].type="acp" route matching conversations to the same ACP session.

Follow-up messages in the bound conversation route directly to the ACP session, and ACP output is delivered back to that same channel/thread/topic.

What OpenClaw sends to the harness:

• Normal bound follow-ups are sent as prompt text, plus attachments only when the harness/backend supports them.
• /acp management commands and local Gateway commands are intercepted before ACP dispatch.
• Runtime-generated completion events are materialized per target. OpenClaw agents get OpenClaw's internal runtime-context envelope; external ACP harnesses get a plain prompt with the child result and instruction. The raw <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> envelope should never be sent to external harnesses or persisted as ACP user transcript text.
• ACP transcript entries use the user-visible trigger text or the plain completion prompt. Internal event metadata stays structured in OpenClaw where possible and is not treated as user-authored chat content.

One-shot ACP sessions spawned by another agent run are background children, similar to sub-agents:

• The parent asks for work with sessions_spawn({ runtime: "acp", mode: "run" }).
• The child runs in its own ACP harness session.
• Child turns run on the same background lane used by native sub-agent spawns, so a slow ACP harness does not block unrelated main-session work.
• Completion reports back through the task-completion announce path. OpenClaw converts internal completion metadata into a plain ACP prompt before sending it to an external harness, so harnesses do not see OpenClaw-only runtime context markers.
• The parent rewrites the child result in normal assistant voice when a user-facing reply is useful.

Do not treat this path as a peer-to-peer chat between parent and child. The child already has a completion channel back to the parent.

sessions_send can target another session after spawn. For normal peer sessions, OpenClaw uses an agent-to-agent (A2A) follow-up path after injecting the message:

• Wait for the target session's reply.
• Optionally let requester and target exchange a bounded number of follow-up turns.
• Ask the target to produce an announce message.
• Deliver that announce to the visible channel or thread.

That A2A path is a fallback for peer sends where the sender needs a visible follow-up. It stays enabled when an unrelated session can see and message an ACP target, for example under broad tools.sessions.visibility settings.

OpenClaw skips the A2A follow-up only when the requester is the parent of its own parent-owned one-shot ACP child. In that case, running A2A on top of task completion can wake the parent with the child's result, forward the parent's reply back into the child, and create a parent/child echo loop. The sessions_send result reports delivery.status="skipped" for that owned-child case because the completion path is already responsible for the result.

Use resumeSessionId to continue a previous ACP session instead of starting fresh. The agent replays its conversation history via session/load, so it picks up with full context of what came before.

{
  "task": "Continue where we left off - fix the remaining test failures",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

Common use cases:

• Hand off a Codex session from your laptop to your phone - tell your agent to pick up where you left off.
• Continue a coding session you started interactively in the CLI, now headlessly through your agent.
• Pick up work that was interrupted by a gateway restart or idle timeout.

Notes:

• resumeSessionId only applies when runtime: "acp"; the default sub-agent runtime ignores this ACP-only field.
• streamTo only applies when runtime: "acp"; the default sub-agent runtime ignores this ACP-only field.
• resumeSessionId is a host-local ACP/harness resume id, not an OpenClaw channel session key; OpenClaw still checks ACP spawn policy and target agent policy before dispatch, while the ACP backend or harness owns authorization for loading that upstream id.
• resumeSessionId restores the upstream ACP conversation history; thread and mode still apply normally to the new OpenClaw session you are creating, so mode: "session" still requires thread: true.
• The target agent must support session/load (Codex and Claude Code do).
• If the session id is not found, the spawn fails with a clear error - no silent fallback to a new session.

After a gateway deploy, run a live end-to-end check rather than trusting unit tests:

1. Verify the deployed gateway version and commit on the target host.
2. Open a temporary ACPX bridge session to a live agent.
3. Ask that agent to call sessions_spawn with runtime: "acp", agentId: "codex", mode: "run", and task Reply with exactly LIVE-ACP-SPAWN-OK.
4. Verify accepted=yes, a real childSessionKey, and no validator error.
5. Clean up the temporary bridge session.

Keep the gate on mode: "run" and skip streamTo: "parent" - thread-bound mode: "session" and stream-relay paths are separate richer integration passes.