OpenClaw ACP Agents 通过 Agent Client Protocol（ACP）让外部编程助手（Codex、Claude Code、Cursor、Gemini CLI 等）在聊天界面中直接运行。安装 @openclaw/acpx 插件并启用后，可使用 /acp spawn --bind here 或 --thread auto 将当前对话或 Discord/Telegram 线程绑定到该助手；后续消息自动路由。提供持久/单次会话模式、模型切换、权限配置，以及 /acp doctor 健康检查。ACP 运行时在宿主机上，不在 OpenClaw 沙箱内。

OpenClaw ACP Agents 配置绑定额与故障排查指南 #

Agent Client Protocol（ACP） 会话让 OpenClaw 通过 ACP 后端插件运行外部编程助手（例如 Pi、Claude Code、Codex、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI 以及其他受支持的 ACPX 助手）。

每个 ACP 会话 spawn 都会作为后台任务被追踪。

::: info ACP 是外部助手路径，不是默认的 Codex 路径。 原生 Codex app-server 插件拥有 /codex ... 控制和默认的 openai/gpt-* 嵌入式运行时用于 agent 轮次；ACP 拥有 /acp ... 控制和 sessions_spawn({ runtime: "acp" }) 会话。

如果你希望 Codex 或 Claude Code 作为外部 MCP 客户端直接连接到现有 OpenClaw 频道对话，使用 openclaw mcp serve 而非 ACP。 :::

我该用哪一页？ #

开箱即用吗？ #

安装官方 ACP 运行时插件后即可：

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

源码检出可以使用本地 extensions/acpx 工作区插件（需先 pnpm install）。运行 /acp doctor 检查就绪状态。

OpenClaw 只在 ACP 真正可用时才会向 agent 暴露 ACP spawn 能力：ACP 必须启用、dispatch 不得关闭、当前会话不得被沙箱阻止、并且运行时后端必须加载。若条件不满足，ACP 插件技能和 sessions_spawn ACP 指引保持隐藏，这样 agent 不会建议不可用的后端。

首次使用可能遇到的问题

- 如果设置了 `plugins.allow`，它是一个限制性插件清单，**必须**包含 `acpx`；否则已安装的 ACP 后端被故意阻止，`/acp doctor` 会报告缺少 allowlist 条目。
- Codex ACP 适配器随 `acpx` 插件一起准备，在可能时本地启动。
- Codex ACP 使用独立的 `CODEX_HOME` 运行；OpenClaw 从宿主机 Codex 配置拷贝受信任的项目条目和安全模型/提供商路由配置，而认证、通知和 hooks 保留在宿主机配置上。
- 其他目标助手适配器可能在第一次使用时通过 `npx` 按需获取。
- 该助手的供应商认证仍需在宿主机上存在。
- 若宿主机无 npm 或网络访问，首次运行适配器获取可能失败，直到缓存预热或适配器另行安装。

运行时前提条件

ACP 启动一个真实的外部助手进程。OpenClaw 拥有路由、后台任务状态、投递、绑定和策略；助手拥有其提供商登录、模型目录、文件系统行为和原生工具。

在责问 OpenClaw 之前，请验证：

- `/acp doctor` 报告已启用、健康的后端。
- 如果设置了 `acp.allowedAgents` 允许列表，目标 id 必须在列表中。
- 助手命令可以在 Gateway 宿主机上启动。
- 该助手的提供商认证存在（`claude`、`codex`、`gemini`、`opencode`、`droid` 等）。
- 所选模型在该助手中存在 —— 模型 id 在不同助手间不可移植。
- 请求的 `cwd` 存在且可访问，或者省略 `cwd` 让后端使用其默认值。
- 权限模式与工作匹配。非交互式会话无法点击原生权限提示，因此写入/执行密集型的编码运行通常需要一个可以无头执行的 ACPX 权限配置。

默认情况下，OpenClaw 插件工具和内置 OpenClaw 工具不会暴露给 ACP 助手。仅在需要助手直接调用这些工具时，启用ACP agents - setup中的显式 MCP 桥接。

支持的助手目标 #

使用 acpx 后端，这些助手 id 可用于 /acp spawn <id> 或 sessions_spawn({ runtime: "acp", agentId: "<id>" })：

自定义 acpx agent 别名可以在 acpx 自身内配置，但 OpenClaw 策略在 dispatch 前仍会检查 acp.allowedAgents 和任何 agents.list[].runtime.acp.agent 映射。

操作手册 #

从聊天的快速 /acp 流程：

启动

`/acp spawn claude --bind here`、
`/acp spawn gemini --mode persistent --thread auto` 或显式
`/acp spawn codex --bind here`。

工作

在绑定的对话或线程中继续（或显式指定会话 key）。

检查状态

`/acp status`

调整

`/acp model <provider/model>`、
`/acp permissions &lt;profile&gt;`、
`/acp timeout &lt;seconds&gt;`。

引导

不替换上下文：`/acp steer tighten logging and continue`。

停止

`/acp cancel`（停止当前轮次）或 `/acp close`（关闭会话 + 移除绑定）。

生命周期细节

- Spawn 创建或恢复 ACP 运行时会话，在 OpenClaw 会话存储中记录 ACP 元数据，并在运行有父 agent 归属时可能创建后台任务。
- 父归属的 ACP 会话被视为后台工作，即使运行时会话是持久性的；完成和跨界面投递通过父任务通知器进行，而不是像正常用户可见的聊天会话那样。
- 任务维护会关闭已终止或孤立的父归属一次性 ACP 会话。持久 ACP 会话在存在活跃对话绑定时保留；没有活跃绑定的过期持久会话会被关闭，这样它们不会在拥有任务完成或任务记录消失后被静默恢复。
- 绑定后的后续消息直接进入 ACP 会话，直到绑定被关闭、取消焦点、重置或过期。
- Gateway 命令保持本地。`/acp ...`、`/status` 和 `/unfocus` 永远不会作为正常提示文本发送到绑定的 ACP 助手。
- `cancel` 在后端支持取消时中止活跃轮次；它不会删除绑定或会话元数据。
- `close` 从 OpenClaw 角度结束 ACP 会话并移除绑定。助手可能仍然保留自己的上游历史（如果支持 resume）。
- acpx 插件会在 `close` 后清理 OpenClaw 拥有的包装器和适配器进程树，并在 Gateway 启动时回收 OpenClaw 拥有的陈旧 ACPX 孤儿进程。
- 空闲运行时工作者在超过 `acp.runtime.ttlMinutes` 后可被清理；存储的会话元数据仍可通过 `/acp sessions` 获取。

原生 Codex 路由规则

当原生 Codex 插件已启用时，以下自然语言触发应路由到**原生 Codex 插件**：

- "将这条 Discord 频道绑定到 Codex。"
- "将此聊天附加到 Codex 线程 `<id>`。"
- "显示 Codex 线程，然后绑定这个。"

原生 Codex 对话绑定是默认的聊天控制路径。OpenClaw 动态工具仍通过 OpenClaw 执行，而 Codex 原生工具如 shell/apply-patch 在 Codex 内执行。对于 Codex 原生工具事件，OpenClaw 注入每轮原生 hook 中继，使插件 hook 可以阻止 `before_tool_call`、观察 `after_tool_call`，并通过 OpenClaw 审批路由 Codex `PermissionRequest` 事件。Codex `Stop` hook 被中继到 OpenClaw `before_agent_finalize`，在那里插件可以在 Codex 最终回答前请求一次额外的模型轮次。该中继故意保守：它不会修改 Codex 原生工具参数或重写 Codex 线程记录。仅当你想要 ACP 运行时/会话模型时使用显式 ACP。嵌入式 Codex 支持边界在 [Codex harness v1 支持契约](/ai/ai-tools/openclaw/plugins/codex-harness-runtime#v1-support-contract) 中记录。

模型 / 提供商 / 运行时选择速查

- `openai-codex/*` - 遗留 Codex OAuth/订阅模型路由，由 doctor 修复。
- `openai/*` - 原生 Codex app-server 嵌入式运行时，用于 OpenAI agent 轮次。
- `/codex ...` - 原生 Codex 对话控制。
- `/acp ...` 或 `runtime: "acp"` - 显式 ACP/acpx 控制。

ACP 路由的自然语言触发

应路由到 ACP 运行时的触发：

- "将此作为一次性 Claude Code ACP 会话运行并总结结果。"
- "使用 Gemini CLI 在某个线程中执行此任务，然后在该线程中保持后续对话。"
- "在后台线程中通过 ACP 运行 Codex。"

OpenClaw 选择 `runtime: "acp"`，解析助手 `agentId`，在支持时绑定到当前对话或线程，并将后续消息路由到该会话直到关闭/过期。Codex 仅在 ACP/acpx 显式或原生 Codex 插件对所请求操作不可用时才走此路径。

对于 `sessions_spawn`，仅当 ACP 已启用、请求者未被沙箱化且已加载 ACP 运行时后端时，才会通告 `runtime: "acp"`。`acp.dispatch.enabled=false` 会暂停自动 ACP 线程 dispatch，但不会隐藏或阻止显式 `sessions_spawn({ runtime: "acp" })` 调用。它针对 ACP 助手 id，如 `codex`、`claude`、`droid`、`gemini` 或 `opencode`。不要传递来自 `agents_list` 的正常 OpenClaw 配置 agent id，除非该条目显式配置了 `agents.list[].runtime.type="acp"`；否则使用默认的子 agent 运行时。当 OpenClaw agent 配置了 `runtime.type="acp"` 时，OpenClaw 使用 `runtime.acp.agent` 作为底层助手 id。

ACP 与子 Agent 对比 #

需要外部助手运行时使用 ACP。需要 OpenClaw 原生委派运行时使用原生 Codex app-server（当 codex 插件启用时用于 Codex 对话绑定/控制）或子 agent。

另见 Sub-agents。

ACP 如何运行 Claude Code #

对于通过 ACP 运行的 Claude Code，技术栈如下：

1. OpenClaw ACP 会话控制平面。
2. 官方 @openclaw/acpx 运行时插件。
3. Claude ACP 适配器。
4. Claude 方运行时/会话机制。

ACP Claude 是一个助手会话，具有 ACP 控制、会话恢复、后台任务跟踪和可选的对话/线程绑定。

CLI backends 是独立的纯文本本地回退运行时 —— 见 CLI Backends。

对于操作者，实用规则是：

• 想要 /acp spawn、可绑定会话、运行时控制或持久助手工作？ 使用 ACP。
• 想要通过原始 CLI 的简单本地文本回退？ 使用 CLI backends。

绑定会话 #

心智模型 #

• 聊天表面 - 人们继续对话的地方（Discord 频道、Telegram 主题、iMessage 会话）。
• ACP 会话 - OpenClaw 路由到的持久 Codex/Claude/Gemini 运行时状态。
• 子线程/主题 - 仅由 --thread ... 创建的可选额外消息传递表面。
• 运行时工作区 - 文件系统位置（cwd、repo 检出、后端工作区），助手在此运行。独立于聊天表面。

当前对话绑定 #

/acp spawn <harness> --bind here 将当前对话固定到启动的 ACP 会话 —— 没有子线程，同一聊天表面。OpenClaw 继续持有传输、认证、安全和投递。该对话的后续消息路由到同一会话；/new 和 /reset 就地重置会话；/acp close 移除绑定。

示例：

/codex bind                                              # 原生 Codex 绑定，未来消息路由到这里
/codex model gpt-5.4                                     # 调整绑定的原生 Codex 线程
/codex stop                                              # 控制活跃的原生 Codex 轮次
/acp spawn codex --bind here                             # Codex 的显式 ACP 回退
/acp spawn codex --thread auto                           # 可能创建子线程并在那里绑定
/acp spawn codex --bind here --cwd /workspace/repo       # 同一聊天绑定，Codex 在 /workspace/repo 中运行

绑定规则和独占性

- `--bind here` 和 `--thread ...` 在同一个 `/acp spawn` 调用中互斥。
- `--bind here` 仅适用于那些通告了当前对话绑定能力的频道；否则 OpenClaw 返回清晰的不支持消息。绑定在 Gateway 重启后持续存在。
- 在 Discord 上，`spawnSessions` 控制子线程创建对于 `--thread auto|here` —— 不是 `--bind here`。
- 如果你启动到不同的 ACP agent 而没有 `--cwd`，OpenClaw 默认继承**目标 agent** 的工作区。缺失的继承路径（`ENOENT`/`ENOTDIR`）会回退到后端默认值；其他访问错误（如 `EACCES`）会作为 spawn 错误呈现。
- Gateway 管理命令在绑定的对话中保持本地 —— `/acp ...` 命令由 OpenClaw 处理，即使正常的后续文本路由到绑定的 ACP 会话；`/status` 和 `/unfocus` 也保持本地（只要对该表面启用了命令处理）。

线程绑定会话

当频道适配器启用了线程绑定时：

- OpenClaw 将线程绑定到目标 ACP 会话。
- 该线程的后续消息路由到绑定的 ACP 会话。
- ACP 输出被投递回同一线程。
- 取消焦点/关闭/归档/空闲超时或最大年龄过期会移除绑定。
- `/acp close`、`/acp cancel`、`/acp status`、`/status` 和 `/unfocus` 是 Gateway 命令，不是发送给 ACP 助手的提示。

线程绑定 ACP 所需的功能标志：

- `acp.enabled=true`
- `acp.dispatch.enabled` 默认开启（设为 `false` 可暂停自动 ACP 线程 dispatch；显式 `sessions_spawn({ runtime: "acp" })` 调用仍有效）。
- 频道适配器线程会话 spawn 已启用（默认：`true`）：
  - Discord：`channels.discord.threadBindings.spawnSessions=true`
  - Telegram：`channels.telegram.threadBindings.spawnSessions=true`

线程绑定支持因适配器而异。如果活跃频道适配器不支持线程绑定，OpenClaw 返回清晰的不支持/不可用消息。

支持线程的频道

- 任何暴露会话/线程绑定能力的频道适配器。
- 当前内置支持：**Discord** 线程/频道、**Telegram** 主题（群组/超级群组中的论坛主题和 DM 主题）。
- 插件频道可以通过相同的绑定接口添加支持。

持久频道绑定 #

对于非临时工作流，在顶层 bindings[] 条目中配置持久 ACP 绑定。

绑定模型 #

bindings[].type

标记持久 ACP 对话绑定。

bindings[].match object

标识目标对话。每个频道的结构：

• Discord 频道/线程： match.channel="discord" + match.peer.id="<channelOrThreadId>"
• Slack 频道/DM： match.channel="slack" + match.peer.id="<channelId|channel:<channelId>|#<channelId>|userId|user:<userId>|slack:<userId>|<@userId>>"。优先使用稳定的 Slack id；频道绑定也匹配该频道线程内的回复。
• Telegram 论坛主题： match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
• iMessage DM/群组： match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"。对于稳定的群组绑定，优先使用 chat_id:*。

bindings[].agentId string

所属 OpenClaw agent 的 id。

bindings[].acp.mode

可选的 ACP 覆盖。

bindings[].acp.label string

可选的面向操作员的标签。

bindings[].acp.cwd string

可选的运行时工作目录。

bindings[].acp.backend string

可选的后端覆盖。

每个 Agent 的运行时默认值 #

使用 agents.list[].runtime 为每个 agent 定义 ACP 默认值：

• agents.list[].runtime.type="acp"
• agents.list[].runtime.acp.agent（助手 id，例如 codex 或 claude）
• agents.list[].runtime.acp.backend
• agents.list[].runtime.acp.mode
• agents.list[].runtime.acp.cwd

ACP 绑定会话的覆盖优先级：

1. bindings[].acp.*
2. agents.list[].runtime.acp.*
3. 全局 ACP 默认值（如 acp.backend）

示例 #

{
  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 } },
        },
      },
    },
  },
}

行为 #

• OpenClaw 确保配置的 ACP 会话在使用前存在。
• 该频道或主题中的消息路由到配置的 ACP 会话。
• 在绑定的对话中，/new 和 /reset 就地重置相同的 ACP 会话 key。
• 临时运行时绑定（例如由线程焦点流程创建的）在存在时仍有效。
• 对于跨 agent ACP spawn 而没有显式 cwd，OpenClaw 从 agent 配置继承目标 agent 工作区。
• 缺失的继承工作区路径会回退到后端默认 cwd；非缺失的访问失败作为 spawn 错误呈现。

启动 ACP 会话 #

两种方式启动 ACP 会话：

从 sessions_spawn

使用 `runtime: "acp"` 从 agent 轮次或工具调用启动 ACP 会话。

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

::: info runtime 默认为 subagent，所以需要显式设置 runtime: "acp" 用于 ACP 会话。如果省略 agentId，OpenClaw 在配置了 acp.defaultAgent 时使用它。mode: "session" 需要 thread: true 以保持持久的绑定对话。 :::

从 /acp 命令

使用 `/acp spawn` 从聊天中显式操作。

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

关键标志：

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

参见 [Slash commands](/ai/ai-tools/openclaw/tools/slash-commands)。

sessions_spawn 参数 #

task string (必填)

发送到 ACP 会话的初始提示。

runtime (必填)

对于 ACP 会话必须为 "acp"。

agentId string

ACP 目标助手 id。如果设置了 acp.defaultAgent 则回退到该值。

thread boolean

在支持的地方请求线程绑定流程。

mode

"run" 是单次；"session" 是持久。如果 thread: true 且省略 mode，OpenClaw 可能根据运行时路径默认持久行为。mode: "session" 需要 thread: true。

cwd string

请求的运行时工作目录（由后端/运行时策略验证）。如果省略，ACP spawn 继承目标 agent 工作区（如果已配置）；缺失的继承路径回退到后端默认值，真正的访问错误会返回。

label string

用于会话/横幅文本的面向操作员标签。

resumeSessionId string

恢复现有 ACP 会话而不是创建新会话。agent 通过 session/load 重放其对话历史。需要 runtime: "acp"。

streamTo

"parent" 将初始 ACP 运行进度摘要作为系统事件流式传回请求者会话。接受响应包括 streamLogPath，指向一个会话范围的 JSONL 日志（<sessionId>.acp-stream.jsonl），你可以 tail 该文件获取完整的中继历史。

runTimeoutSeconds number

在 N 秒后中止 ACP 子轮次。0 将轮次保持在 gateway 的无超时路径上。相同的值应用于 Gateway 运行和 ACP 运行时，这样停滞/配额耗尽的助手不会无限期占用父 agent 通道。

model string

对 ACP 子会话的显式模型覆盖。Codex ACP spawn 会在 session/new 前将 OpenClaw Codex 引用（如 openai-codex/gpt-5.4）规范化为 Codex ACP 启动配置；斜杠形式如 openai-codex/gpt-5.4/high 也会设置 Codex ACP 推理努力。其他助手必须通告 ACP models 并支持 session/set_model；否则 OpenClaw/acpx 会清晰失败而不是静默回退到目标 agent 默认值。

thinking string

显式思考/推理努力。对于 Codex ACP，minimal 映射到低努力，low/medium/high/xhigh 直接映射，off 省略推理努力启动覆盖。

Spawn 绑定和线程模式 #

–bind here|off

| 模式    | 行为                                                       |
| ------- | --------------------------------------------------------- |
| `here`  | 就地绑定当前活跃对话；如果没有活跃对话则失败。              |
| `off`   | 不创建当前对话绑定。                                       |

注意：

- `--bind here` 是最简单的操作路径，用于"使这个频道或聊天由 Codex 支持"。
- `--bind here` 不会创建子线程。
- `--bind here` 仅适用于那些暴露当前对话绑定能力的频道。
- `--bind` 和 `--thread` 不能在同一个 `/acp spawn` 调用中组合。

–thread auto|here|off

| 模式    | 行为                                                                     |
| ------- | ----------------------------------------------------------------------- |
| `auto`  | 在活跃线程中：绑定该线程。在线程外：在支持的地方创建/绑定子线程。          |
| `here`  | 要求当前活跃线程；如果不在线程中则失败。                                  |
| `off`   | 不绑定。会话以未绑定状态启动。                                           |

注意：

- 在非线程绑定表面上，默认行为实际上是 `off`。
- 线程绑定 spawn 需要频道策略支持：
  - Discord：`channels.discord.threadBindings.spawnSessions=true`
  - Telegram：`channels.telegram.threadBindings.spawnSessions=true`
- 使用 `--bind here` 当你想将当前对话固定而不创建子线程。

投递模型 #

ACP 会话可以是交互式工作区或父归属的后台工作。投递路径取决于该形状。

交互式 ACP 会话

交互式会话用于在可见的聊天表面上继续对话：

- `/acp spawn ... --bind here` 将当前对话绑定到 ACP 会话。
- `/acp spawn ... --thread ...` 将频道线程/主题绑定到 ACP 会话。
- 持久配置的 `bindings[].type="acp"` 将匹配的对话路由到同一 ACP 会话。

绑定对话中的后续消息直接路由到 ACP 会话，ACP 输出被投递回同一频道/线程/主题。

OpenClaw 发送给助手的内容：

- 正常绑定的后续消息作为提示文本发送，加上附件（仅当助手/后端支持时）。
- `/acp` 管理命令和本地 Gateway 命令在 ACP dispatch 前被拦截。
- 运行时生成的完成事件按目标具体化。OpenClaw agent 获得 OpenClaw 的内部运行时上下文信封；外部 ACP 助手获得纯提示（包含子结果和指令）。原始 `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>` 信封绝不应发送到外部助手或作为 ACP 用户转录文本持久化。
- ACP 转录条目使用用户可见的触发文本或纯完成提示。内部事件元数据尽可能在 OpenClaw 中保持结构化，不被视为用户创作的聊天内容。

父归属的一次性 ACP 会话

由另一个 agent 运行启动的一次性 ACP 会话是后台子任务，类似于子 agent：

- 父 agent 通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求工作。
- 子任务在自己的 ACP 助手会话中运行。
- 子轮次在与原生子 agent spawn 使用的相同后台通道上运行，因此慢的 ACP 助手不会阻塞不相关的主会话工作。
- 完成通过任务完成 announce 路径报告。OpenClaw 在将内部完成元数据发送到外部助手前将其转换为纯 ACP 提示，这样助手不会看到 OpenClaw 独有的运行时上下文标记。
- 当需要面向用户的回复时，父 agent 以正常助手语气重写子结果。

不要将此路径视为父子之间的点对点聊天。子任务已经有完成通道返回给父 agent。

sessions_send 和 A2A 投递

`sessions_send` 可以在 spawn 后定位另一个会话。对于正常的对等会话，OpenClaw 在注入消息后使用 agent-to-agent（A2A）后续路径：

- 等待目标会话的回复。
- 可选地让请求者和目标交换有限数量的后续轮次。
- 要求目标生成 announce 消息。
- 将该 announce 投递到可见的频道或线程。

该 A2A 路径是当发送者需要可见后续的对等发送的回退。当不相关的会话可以看到并向 ACP 目标发送消息时，它保持启用，例如在广泛的 `tools.sessions.visibility` 设置下。

OpenClaw 仅在请求者是其自身父归属的一次性 ACP 子任务的父 agent 时跳过 A2A 后续。在这种情况下，在任务完成之上运行 A2A 可能会用子结果唤醒父 agent，将父 agent 的回复转发回子任务，从而创建父/子回显循环。对于该归属子任务情况，`sessions_send` 结果报告 `delivery.status="skipped"`，因为完成路径已经负责结果。

恢复现有会话

使用 `resumeSessionId` 继续之前的 ACP 会话而不是从头开始。agent 通过 `session/load` 重放其对话历史，因此它拥有之前发生的一切的完整上下文。

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

常见用例：

- 将 Codex 会话从笔记本交接到手机 —— 告诉你的 agent 从停下的地方继续。
- 继续你在 CLI 中以交互方式开始的编码会话，现在通过 agent 无头地继续。
- 接手因 gateway 重启或空闲超时而中断的工作。

注意：

- `resumeSessionId` 仅适用于 `runtime: "acp"`；默认的子 agent 运行时忽略此 ACP 专有字段。
- `streamTo` 仅适用于 `runtime: "acp"`；默认的子 agent 运行时忽略此 ACP 专有字段。
- `resumeSessionId` 是宿主机本地的 ACP/助手恢复 id，不是 OpenClaw 频道会话 key；OpenClaw 在 dispatch 前仍检查 ACP spawn 策略和目标 agent 策略，而 ACP 后端或助手拥有授权来加载该上游 id。
- `resumeSessionId` 恢复上游 ACP 对话历史；`thread` 和 `mode` 仍正常应用于你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍需要 `thread: true`。
- 目标 agent 必须支持 `session/load`（Codex 和 Claude Code 都支持）。
- 如果未找到会话 id，spawn 失败并显示清晰错误 —— 不会静默回退到新会话。

部署后冒烟测试

Gateway 部署后，运行实时端到端检查，而不是依赖单元测试：

1. 验证目标主机上的已部署 gateway 版本和提交。
2. 打开与实时 agent 的临时 ACPX 桥接会话。
3. 让该 agent 调用 `sessions_spawn`，使用 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"` 和任务 `Reply with exactly LIVE-ACP-SPAWN-OK`。
4. 验证 `accepted=yes`、真实的 `childSessionKey` 且没有校验器错误。
5. 清理临时桥接会话。

保持在 `mode: "run"` 并跳过 `streamTo: "parent"` —— 线程绑定的 `mode: "session"` 和流中继路径是单独的更丰富的集成测试。

沙箱兼容性 #

ACP 会话当前运行在宿主机运行时上，不在 OpenClaw 沙箱内。

::: warning 安全边界：

• 外部助手可以根据其自己的 CLI 权限和所选的 cwd 进行读取/写入。
• OpenClaw 的沙箱策略不会包装 ACP 助手执行。
• OpenClaw 仍执行 ACP 功能门控、允许 agent、会话所有权、频道绑定和 Gateway 投递策略。
• 使用 runtime: "subagent" 进行沙箱强制执行的 OpenClaw 原生工作。

:::

当前限制：

• 如果请求者会话被沙箱化，则对 sessions_spawn({ runtime: "acp" }) 和 /acp spawn 都阻止 ACP spawn。
• 使用 runtime: "acp" 的 sessions_spawn 不支持 sandbox: "require"。

会话目标解析 #

大多数 /acp 动作接受可选的会话目标（session-key、session-id 或 session-label）。

解析顺序：

1. 显式目标参数（或 /acp steer 的 --session）
   • 尝试 key
   • 然后 UUID 形状的会话 id
   • 然后 label
2. 当前线程绑定（如果此对话/线程绑定到 ACP 会话）。
3. 当前请求者会话回退。

当前对话绑定和线程绑定都参与第 2 步。

如果未解析目标，OpenClaw 返回清晰错误（Unable to resolve session target: ...）。

ACP 控制命令速查 #

/acp status 显示有效的运行时选项加上运行时级别和后端级别的会话标识符。不支持的控制错误会清晰显示（当后端缺少能力时）。/acp sessions 读取当前绑定或请求者会话的存储；目标令牌（session-key、session-id 或 session-label）通过 gateway 会话发现解析，包括自定义每个 agent 的 session.store 根。

运行时选项映射 #

/acp 有便捷命令和通用 setter。等效操作：

acpx 助手、插件设置和权限 #

有关 acpx 助手配置（Claude Code / Codex / Gemini CLI 别名）、插件工具和 OpenClaw 工具 MCP 桥接以及 ACP 权限模式，请参阅 ACP agents - setup。

故障排查 #

相关 #

• ACP agents - setup
• Agent send
• CLI Backends
• Codex harness
• Codex harness runtime
• Multi-agent sandbox tools
• openclaw acp (bridge mode)
• Sub-agents

常见问题 #

为什么 /acp spawn 提示 “ACP runtime backend is not configured”？ #

ACP 后端插件未安装或未启用。运行 openclaw plugins install @openclaw/acpx 安装，然后执行 openclaw config set plugins.entries.acpx.enabled true 启用。如果设置了 plugins.allow 允许列表，必须包含 acpx。安装后使用 /acp doctor 检查状态。

--bind here 在 Discord/Telegram 中不生效怎么办？ #

--bind here 需要频道适配器支持当前对话绑定。如果收到 “Conversation bindings are unavailable” 错误，说明该适配器不支持。可改用 --thread auto（需要适配器支持线程绑定）或配置顶层 bindings[] 进行持久绑定。另外检查 /acp spawn 是否在活跃的对话中执行。

如何让 ACP 助手（如 Claude Code）调用 OpenClaw 的工具？ #

默认情况下，ACP 助手不会看到 OpenClaw 插件工具。需要启用插件工具 MCP 桥接：openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true。启用前确认你希望 ACP 助手访问哪些已安装的插件工具，因为这会扩展其能力范围。