ACP agents

openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true

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.

- "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](/plugins/codex-harness#v1-support-contract).

- "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.

/codex bind                                              # native Codex bind, route future messages here
/codex model gpt-5.4                                     # tune the bound native Codex thread
/codex stop                                              # control the active native Codex turn
/acp spawn codex --bind here                             # explicit ACP fallback for Codex
/acp spawn codex --thread auto                           # may create a child thread/topic and bind there
/acp spawn codex --bind here --cwd /workspace/repo       # same chat binding, Codex runs in /workspace/repo

- 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.

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
      {
        id: "claude",
        runtime: {
          type: "acp",
          acp: { agent: "claude", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
    {
      type: "acp",
      agentId: "claude",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
      acp: { cwd: "/workspace/repo-b" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "discord", accountId: "default" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "telegram", accountId: "default" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": { requireMention: false },
          },
        },
      },
    },
    telegram: {
      groups: {
        "-1001234567890": {
          topics: { "42": { requireMention: false } },
        },
      },
    },
  },
}

```json
{
  "task": "Open the repo and summarize failing tests",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}
```

<Note>
`runtime` defaults to `subagent`, so set `runtime: "acp"` explicitly
for ACP sessions. If `agentId` is omitted, OpenClaw uses
`acp.defaultAgent` when configured. `mode: "session"` requires
`thread: true` to keep a persistent bound conversation.
</Note>

```text
/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --bind here
/acp spawn codex --thread here
```

Key flags:

- `--mode persistent|oneshot`
- `--bind here|off`
- `--thread auto|here|off`
- `--cwd <absolute-path>`
- `--label <name>`

See [Slash commands](/tools/slash-commands).

Notes:

- `--bind here` is the simplest operator path for "make this channel or chat Codex-backed."
- `--bind here` does not create a child thread.
- `--bind here` is only available on channels that expose current-conversation binding support.
- `--bind` and `--thread` cannot be combined in the same `/acp spawn` call.

Notes:

- On non-thread binding surfaces, default behavior is effectively `off`.
- Thread-bound spawn requires channel policy support:
  - Discord: `channels.discord.threadBindings.spawnSessions=true`
  - Telegram: `channels.telegram.threadBindings.spawnSessions=true`
- Use `--bind here` when you want to pin the current conversation without creating a child thread.

- `/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 `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>` 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.

- 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.

- 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.

```json
{
  "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.

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.