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。

我该用哪一页？

你想做什么	用这个	备注
在当前对话中绑定或控制 Codex	/codex bind、/codex threads	原生 Codex app-server 路径，需启用 codex 插件；包含绑定回复、图片转发、模型/快速/权限、停止和引导控制。ACP 是显式回退
通过 OpenClaw 运行 Claude Code、Gemini CLI、显式 Codex ACP 或其他外部助手	本页	对话绑定会话、/acp spawn、sessions_spawn({ runtime: "acp" })、后台任务、运行时控制
将 OpenClaw Gateway 会话暴露为 ACP 服务器供编辑器或客户端使用	openclaw acp	桥接模式。IDE/客户端通过 stdio/WebSocket 以 ACP 协议连接到 OpenClaw
将本地 AI CLI 复用作纯文本回退模型	CLI Backends	不是 ACP。没有 OpenClaw 工具，没有 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>" })：

助手 id	典型后端	备注
claude	Claude Code ACP 适配器	需要在宿主机上具有 Claude Code 认证。
codex	Codex ACP 适配器	仅在原生 /codex 不可用或明确请求 ACP 时作为回退。
copilot	GitHub Copilot ACP 适配器	需要 Copilot CLI/运行时认证。
cursor	Cursor CLI ACP (cursor-agent acp)	若本地安装暴露了不同的 ACP 入口点，可覆盖 acpx 命令。
droid	Factory Droid CLI	需要 Factory/Droid 认证或 FACTORY_API_KEY 在助手环境中。
gemini	Gemini CLI ACP 适配器	需要 Gemini CLI 认证或 API key 设置。
iflow	iFlow CLI	适配器可用性和模型控制取决于已安装的 CLI。
kilocode	Kilo Code CLI	适配器可用性和模型控制取决于已安装的 CLI。
kimi	Kimi/Moonshot CLI	需要在宿主机上具有 Kimi/Moonshot 认证。
kiro	Kiro CLI	适配器可用性和模型控制取决于已安装的 CLI。
opencode	OpenCode ACP 适配器	需要 OpenCode CLI/提供商认证。
openclaw	通过 openclaw acp 的 OpenClaw Gateway 桥接	让 ACP 感知的助手能够回连到 OpenClaw Gateway 会话。
pi	Pi/嵌入式 OpenClaw 运行时	用于 OpenClaw 原生助手实验。
qwen	Qwen Code / Qwen CLI	需要在宿主机上具有 Qwen 兼容认证。

自定义 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。

维度	ACP 会话	子 Agent 运行
运行时	ACP 后端插件（例如 acpx）	OpenClaw 原生子 agent 运行时
会话 key	agent:<agentId>:acp:&lt;uuid&gt;	agent:<agentId>:subagent:&lt;uuid&gt;
主要命令	/acp ...	/subagents ...
启动工具	sessions_spawn with runtime:"acp"	sessions_spawn（默认运行时）

另见 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 spawn	创建 ACP 会话；可选当前绑定或线程绑定。	/acp spawn codex --bind here --cwd /repo
/acp cancel	取消目标会话的进行中轮次。	/acp cancel agent:codex:acp:<uuid>
/acp steer	向运行中的会话发送引导指令。	/acp steer --session support inbox prioritize failing tests
/acp close	关闭会话并移除线程绑定。	/acp close
/acp status	显示后端、模式、状态、运行时选项、能力。	/acp status
/acp set-mode	设置目标会话的运行时模式。	/acp set-mode plan
/acp set	通用运行时配置选项写入。	/acp set model openai/gpt-5.4
/acp cwd	设置运行时工作目录覆盖。	/acp cwd /Users/user/Projects/repo
/acp permissions	设置审批策略配置。	/acp permissions strict
/acp timeout	设置运行时超时（秒）。	/acp timeout 120
/acp model	设置运行时模型覆盖。	/acp model anthropic/claude-opus-4-6
/acp reset-options	移除会话运行时选项覆盖。	/acp reset-options
/acp sessions	从存储中列出最近的 ACP 会话。	/acp sessions
/acp doctor	后端健康状态、能力、可操作修复。	/acp doctor
/acp install	打印确定的安装和启用步骤。	/acp install

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

运行时选项映射

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

命令	映射到	备注
/acp model <id>	运行时配置 key model	对于 Codex ACP，OpenClaw 将 openai-codex/<model> 规范化为适配器模型 id，并将斜杠推理后缀（如 openai-codex/gpt-5.4/high）映射到 reasoning_effort。
/acp set thinking <level>	规范选项 thinking	OpenClaw 发送后端通告的等效项（如果存在），优先选择 thinking，然后是 effort、reasoning_effort 或 thought_level。对于 Codex ACP，适配器将值映射到 reasoning_effort。
/acp permissions <profile>	规范选项 permissionProfile	OpenClaw 发送后端通告的等效项（如果存在），如 approval_policy、permission_profile、permissions 或 permission_mode。
/acp timeout <seconds>	规范选项 timeoutSeconds	OpenClaw 发送后端通告的等效项（如果存在），如 timeout 或 timeout_seconds。
/acp cwd <path>	运行时 cwd 覆盖	直接更新。
/acp set <key> <value>	通用	key=cwd 使用 cwd 覆盖路径。
/acp reset-options	清除所有运行时覆盖	-

acpx 助手、插件设置和权限

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

故障排查

症状	可能原因	修复
ACP runtime backend is not configured	后端插件缺失、禁用或被 plugins.allow 阻止。	安装并启用后端插件，当设置了 allowlist 时包含 acpx，然后运行 /acp doctor。
ACP is disabled by policy (acp.enabled=false)	ACP 全局禁用。	设置 acp.enabled=true。
ACP dispatch is disabled by policy (acp.dispatch.enabled=false)	来自正常线程消息的自动分发已禁用。	设置 acp.dispatch.enabled=true 以恢复自动线程路由；显式 sessions_spawn({ runtime: "acp" }) 调用仍有效。
ACP agent "<id>" is not allowed by policy	Agent 不在允许列表中。	使用允许的 agentId 或更新 acp.allowedAgents。
/acp doctor 报告后端在启动后未就绪	后端插件缺失、禁用、被允许/拒绝策略阻止或配置的可执行文件不可用。	安装/启用后端插件，重新运行 /acp doctor，如果仍不健康，检查后端安装或策略错误。
助手命令未找到	适配器 CLI 未安装、外部插件缺失或非 Codex 适配器的首次 npx 获取失败。	运行 /acp doctor，在 Gateway 宿主机上安装/预热适配器，或显式配置 acpx agent 命令。
助手报告模型未找到	模型 id 对另一个提供商/助手有效，但对此 ACP 目标无效。	使用该助手列出的模型，在助手中配置模型，或省略覆盖。
助手报告供应商认证错误	OpenClaw 健康，但目标 CLI/提供商未登录。	登录或在 Gateway 宿主机环境中提供所需的提供商 key。
Unable to resolve session target: ...	错误的 key/id/label 令牌。	运行 /acp sessions，复制精确的 key/label，重试。
--bind here requires running /acp spawn inside an active ... conversation	在没有可绑定的活跃对话时使用 --bind here。	移动到目标聊天/频道并重试，或使用未绑定的 spawn。
Conversation bindings are unavailable for <channel>.	适配器缺少当前对话 ACP 绑定能力。	在支持的地方使用 /acp spawn ... --thread ...，配置顶层 bindings[]，或移动到支持的频道。
--thread here requires running /acp spawn inside an active ... thread	在线程上下文之外使用 --thread here。	移动到目标线程或使用 --thread auto/off。
Only <user-id> can rebind this channel/conversation/thread.	另一个用户拥有活跃绑定目标。	以所有者身份重新绑定或使用不同的对话或线程。
Thread bindings are unavailable for <channel>.	适配器缺少线程绑定能力。	使用 --thread off 或移动到支持的适配器/频道。
Sandboxed sessions cannot spawn ACP sessions ...	ACP 运行时在宿主机上；请求者会话被沙箱化。	从沙箱会话中使用 runtime="subagent"，或从非沙箱会话运行 ACP spawn。
sessions_spawn sandbox="require" is unsupported for runtime="acp" ...	为 ACP 运行时请求了 sandbox="require"。	如果需要沙箱，使用 runtime="subagent"，或从非沙箱会话使用 ACP 且 sandbox="inherit"。
Cannot apply --model ... did not advertise model support	目标助手不暴露通用 ACP 模型切换。	使用通告了 ACP models/session/set_model 的助手，使用 Codex ACP 模型引用，或在助手中直接配置模型（如果助手有自己的启动标志）。
绑定会话缺少 ACP 元数据	陈旧的/已删除的 ACP 会话元数据。	使用 /acp spawn 重新创建，然后重新绑定/聚焦线程。
AcpRuntimeError: Permission prompt unavailable in non-interactive mode	permissionMode 阻止非交互式 ACP 会话中的写入/执行。	设置 plugins.entries.acpx.config.permissionMode 为 approve-all 并重启 gateway。参见权限配置。
ACP 会话早期失败，输出很少	权限提示被 permissionMode/nonInteractivePermissions 阻止。	检查 gateway 日志中的 AcpRuntimeError。对于完全权限，设置 permissionMode=approve-all；对于优雅降级，设置 nonInteractivePermissions=deny。
ACP 会话在完成工作后无限期停滞	助手进程已完成但 ACP 会话未报告完成。	更新 OpenClaw；当前 acpx 清理在关闭和 Gateway 启动时回收 OpenClaw 拥有的陈旧包装器和适配器进程。
助手看到 <<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>	内部事件信封泄漏到 ACP 边界。	更新 OpenClaw 并重新运行完成流程；外部助手应该只收到纯完成提示。

相关

• 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 助手访问哪些已安装的插件工具，因为这会扩展其能力范围。