ACP 代理 - OpenClaw 中文文档

Agent Client Protocol (ACP) 会话让 OpenClaw 通过 ACP 后端插件运行外部编码 harness（例如 Claude Code、 Cursor、Copilot、Droid、OpenClaw ACP、OpenCode、Gemini CLI，以及其他受支持的 ACPX harness）。每次 ACP 会话创建都会被跟踪为一个后台任务。

ACP 是外部 harness 路径，不是默认的 Codex 路径。 原生 Codex 应用服务器插件负责 /codex ... 控制和用于 agent 回合的默认 openai/gpt-* 内嵌运行时；ACP 负责 /acp ... 控制和 sessions_spawn({ runtime: "acp" }) 会话。如果你希望 Codex 或 Claude Code 作为外部 MCP 客户端直接连接到现有的 OpenClaw 渠道对话，请改用 openclaw mcp serve，而不是 ACP。

我该看哪个页面？

你想要……	使用这个	备注
在当前对话中绑定或控制 Codex	`/codex bind`, `/codex threads`	当启用 `codex` 插件时使用原生 Codex 应用服务器路径；包括已绑定聊天回复、图片转发、模型/fast/权限、停止和引导控制。ACP 是显式回退
通过 OpenClaw 运行 Claude Code、Gemini CLI、显式 Codex ACP 或其他外部 harness through	本页	绑定到聊天的会话、`/acp spawn`、`sessions_spawn({ runtime: "acp" })`、后台任务、运行时控制
将 OpenClaw Gateway 会话作为 ACP 服务器暴露给编辑器或客户端	`openclaw acp`	桥接模式。IDE/客户端通过 stdio/WebSocket 与 OpenClaw 通过 ACP 通信
复用本地 AI CLI 作为纯文本回退模型	CLI Backends	不是 ACP。没有 OpenClaw 工具，没有 ACP 控制，没有 harness 运行时

这开箱即用吗？

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

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

源码检出可在 pnpm install 之后使用本地 extensions/acpx 工作区插件。运行 /acp doctor 进行就绪检查。只有在 ACP 真正可用 时，OpenClaw 才会向 agents 说明 ACP spawning：ACP 必须已启用，dispatch 不能被禁用，当前会话不能被 sandbox 阻止，并且必须加载了 runtime backend。若这些条件不满足，ACP 插件技能和 sessions_spawn 的 ACP 指引会保持隐藏，这样 agent 就不会建议一个不可用的 backend。

首次运行注意事项

如果设置了 plugins.allow，它就是一个受限的插件清单，并且必须包含 acpx；否则已安装的 ACP backend 会被故意阻止，且 /acp doctor 会报告缺少 allowlist 条目。
Codex ACP 适配器会与 acpx 插件一起分阶段准备，并在可能时本地启动。
Codex ACP 使用隔离的 CODEX_HOME 运行；OpenClaw 会从主机上的 Codex 配置中复制受信任的项目条目以及安全的模型/提供商路由配置，而认证、通知和钩子则保留在主机配置中。
其他目标 harness 适配器在你首次使用它们时，仍可能通过 npx 按需获取。
供应商认证仍必须存在于主机上，才能供该 harness 使用。
如果主机没有 npm 或网络访问，首次运行时的适配器获取会失败，直到缓存被预热或适配器以其他方式安装。

运行时前提条件

ACP 会启动一个真实的外部 harness 进程。OpenClaw 负责路由、后台任务状态、投递、绑定和策略；harness 负责其供应商登录、模型目录、文件系统行为和原生工具。在归咎于 OpenClaw 之前，请验证：

/acp doctor 报告 backend 已启用且健康。
当设置了 allowlist 时，目标 id 需要被 acp.allowedAgents 允许。
harness 命令可以在 Gateway 主机上启动。
该 harness 已存在供应商认证（claude、codex、gemini、opencode、droid 等）。
为该 harness 选择的模型存在 - 模型 id 不能跨 harness 通用。
请求的 cwd 存在且可访问，或者省略 cwd 让 backend 使用其默认值。
权限模式与工作内容匹配。非交互式会话无法点击原生权限提示，因此大量写入/执行的编码运行通常需要能够无头继续的 ACPX 权限配置文件。

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

支持的 harness 目标

使用 acpx backend 时，可将这些 harness id 作为 /acp spawn <id> 或 sessions_spawn({ runtime: "acp", agentId: "<id>" }) 的目标：

Harness id	典型后端	备注
`claude`	Claude Code ACP 适配器	需要主机上的 Claude Code 认证。
`codex`	Codex ACP 适配器	仅在原生 `/codex` 不可用或请求 ACP 时才作为显式回退。
`copilot`	GitHub Copilot ACP 适配器	需要 Copilot CLI/runtime 认证。
`cursor`	Cursor CLI ACP（`cursor-agent acp`）	如果本地安装暴露了不同的 ACP 入口点，可覆盖 acpx 命令。
`droid`	Factory Droid CLI	需要 Factory/Droid 认证，或在 harness 环境中提供 `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/provider 认证。
`openclaw`	通过 `openclaw acp` 的 OpenClaw Gateway 桥接	让支持 ACP 的 harness 与 OpenClaw Gateway 会话双向通信。
`qwen`	Qwen Code / Qwen CLI	需要主机上的 Qwen 兼容认证。

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

操作手册

从聊天中快速进行 /acp 流程：

Spawn

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

Work

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

Check state

/acp status

Tune

/acp model <provider/model>， /acp permissions <profile>， /acp timeout <seconds>。

Steer

不替换上下文地引导：/acp steer tighten logging and continue。

Stop

/acp cancel（当前轮次）或 /acp close（会话 + 绑定）。

生命周期细节

Spawn 会创建或恢复一个 ACP runtime 会话，在 OpenClaw 会话存储中记录 ACP 元数据，并且在运行由父项拥有时可能创建一个后台任务。
由父项拥有的 ACP 会话会被视为后台工作，即使 runtime 会话是持久的；完成和跨界面投递通过父任务通知器进行，而不是像普通面向用户的聊天会话那样处理。
任务维护会关闭终止或孤立的由父项拥有的一次性 ACP 会话。持久 ACP 会话在仍有活动的对话绑定时会被保留；没有活动绑定的过期持久会话会被关闭，因此在拥有任务完成或其任务记录消失后，它们无法被静默恢复。
已绑定的后续消息会直接发送到 ACP 会话，直到绑定被关闭、失焦、重置或过期。
Gateway 命令保持本地执行。/acp ...、/status 和 /unfocus 绝不会作为普通提示文本发送给已绑定的 ACP harness。
当 backend 支持取消时，cancel 会中止当前轮次；它不会删除绑定或会话元数据。
close 从 OpenClaw 的视角结束 ACP 会话并移除绑定。若 harness 支持恢复，它可能仍会保留自己上游的历史记录。
acpx 插件在 close 后会清理由 OpenClaw 拥有的包装器和适配器进程树，并在 Gateway 启动期间回收由 OpenClaw 拥有的陈旧 ACPX 孤儿进程。
空闲的 runtime worker 在 acp.runtime.ttlMinutes 之后有资格被清理；存储的会话元数据仍可通过 /acp sessions 访问。

原生 Codex 路由规则

当启用时，应该路由到原生 Codex 插件的自然语言触发语句：

“将这个 Discord 渠道绑定到 Codex。”
“把这个聊天附加到 Codex 线程 <id>。”
“显示 Codex 线程，然后把这个绑定上。”

原生 Codex 对话绑定是默认的聊天控制路径。 OpenClaw 动态工具仍通过 OpenClaw 执行，而 Codex 原生工具（如 shell/apply-patch）则在 Codex 内部执行。对于 Codex 原生工具事件，OpenClaw 会注入一个按轮次的原生 hook relay，以便插件 hooks 可以拦截 before_tool_call、观察 after_tool_call，并通过 OpenClaw 审批来路由 Codex PermissionRequest 事件。 Codex 的 Stop hooks 会转发到 OpenClaw before_agent_finalize，这样插件就可以在 Codex 最终输出答案之前再请求一次模型运行。该 relay 保持刻意保守：它不会修改 Codex 原生工具参数，也不会重写 Codex 线程记录。只有在你想要 ACP runtime/session 模型时，才使用显式 ACP。嵌入式 Codex 支持边界记录在 Codex harness v1 support contract。

Model / provider / runtime selection cheat sheet

legacy Codex model refs - 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.

ACP 路由自然语言触发语句

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

“把这个作为一次性的 Claude Code ACP 会话运行并总结结果。”
“这个任务在一个线程里使用 Gemini CLI，然后让后续跟进留在同一个线程里。”
“通过 ACP 在后台线程中运行 Codex。”

OpenClaw 会选择 runtime: "acp"，解析 harness 的 agentId，在受支持时绑定到当前对话或线程，并将后续跟进路由到该会话，直到关闭/过期。只有当 ACP/acpx 是显式指定的，或者原生 Codex 插件对请求的操作不可用时，Codex 才会走这条路径。对于 sessions_spawn，只有在 ACP 已启用、请求者未处于 sandbox 中且已加载 ACP 运行时 backend 时，才会声明 runtime: "acp"。acp.dispatch.enabled=false 会暂停自动 ACP 线程分发，但不会隐藏或阻止显式 sessions_spawn({ runtime: "acp" }) 调用。它面向如 codex、 claude、droid、gemini 或 opencode 等 ACP harness id。不要传入来自 agents_list 的普通 OpenClaw 配置 agent id，除非该条目被显式配置为 agents.list[].runtime.type="acp"；否则应使用默认的子 agent 运行时。当 OpenClaw agent 配置为 runtime.type="acp" 时，OpenClaw 会使用 runtime.acp.agent 作为底层 harness id。

ACP 与子代理

当你需要外部 harness 运行时，请使用 ACP。当 codex 插件启用时，使用 原生 Codex app-server 进行 Codex 对话绑定/控制。当你需要 OpenClaw 原生的委派运行时，请使用 子代理。

Area	ACP 会话	子代理运行
运行时	ACP 后端插件（例如 acpx）	OpenClaw 原生子代理运行时
会话 key	`agent:<agentId>:acp:<uuid>`	`agent:<agentId>:subagent:<uuid>`
主要命令	`/acp ...`	`/subagents ...`
生成工具	`sessions_spawn` with `runtime:"acp"`	`sessions_spawn`（默认运行时）

另见子代理。

ACP 如何运行 Claude Code

通过 ACP 运行 Claude Code 时，技术栈如下：

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

ACP Claude 是一个带有 ACP 控制、会话恢复、后台任务跟踪以及可选对话/线程绑定的 harness 会话。 CLI 后端是独立的纯文本本地回退运行时 - 另见 CLI 后端。对于运维人员，实用规则是：

想要 /acp spawn、可绑定会话、运行时控制，或持久的 harness 工作？ 使用 ACP。
想要通过原始 CLI 获得简单的本地文本回退？ 使用 CLI 后端。

绑定会话

心智模型

聊天界面 - 人们持续对话的地方（Discord 频道、Telegram 主题、iMessage 聊天）。
ACP 会话 - OpenClaw 路由到的持久 Codex/Claude/Gemini 运行时状态。
子线程/主题 - 仅由 --thread ... 创建的可选额外消息界面。
运行时工作区 - harness 运行所在的文件系统位置（cwd、仓库检出目录、后端工作区）。与聊天界面相互独立。

当前对话绑定

/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 中运行

Binding rules and exclusivity

--bind here 和 --thread ... 互斥。
--bind here 仅适用于声明支持当前对话绑定的频道；否则 OpenClaw 会返回清晰的不支持消息。绑定会在网关重启后保持。
在 Discord 上，spawnSessions 控制 --thread auto|here 的子线程创建 - 不控制 --bind here。
如果你在没有 --cwd 的情况下 spawn 到另一个 ACP agent，OpenClaw 默认会继承 目标 agent 的 工作区。缺失的继承路径（ENOENT/ENOTDIR）会回退到后端默认值；其他访问错误（例如 EACCES）会作为 spawn 错误暴露出来。
在已绑定的对话中，网关管理命令保持本地处理 - 即使普通后续文本会路由到已绑定的 ACP 会话，/acp ... 命令仍由 OpenClaw 处理；只要该界面启用了命令处理，/status 和 /unfocus 也会保持本地处理。

线程绑定会话

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

OpenClaw 会将线程绑定到目标 ACP 会话。
该线程中的后续消息会路由到已绑定的 ACP 会话。
ACP 输出会回送到同一个线程。
unfocus/close/archive/idle-timeout 或 max-age 到期会移除绑定。
/acp close、/acp cancel、/acp status、/status 和 /unfocus 是 Gateway 命令，不是发给 ACP harness 的提示词。

线程绑定 ACP 所需的功能开关：

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

线程绑定支持是适配器特定的。如果当前频道适配器不支持线程绑定，OpenClaw 会返回清晰的不支持/不可用消息。

支持线程的频道

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

持久频道绑定

对于非一次性的工作流，请在顶层 bindings[] 条目中配置持久 ACP 绑定。

绑定模型

bindings[].type

"acp"

标记一个持久 ACP 对话绑定。

bindings[].match

object

标识目标对话。按频道的形状如下：

Discord channel/thread: match.channel="discord" + match.peer.id="<channelOrThreadId>"
Slack channel/DM: match.channel="slack" + match.peer.id="<channelId|channel:<channelId>|#<channelId>|userId|user:<userId>|slack:<userId>|<@userId>>". 优先使用稳定的 Slack id；频道绑定也会匹配该频道线程中的回复。
Telegram forum topic: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
iMessage DM/group: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"。稳定的群组绑定优先使用 chat_id:*。

bindings[].agentId

string

所属的 OpenClaw agent id。

bindings[].acp.mode

"persistent" | "oneshot"

可选的 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（harness id，例如 codex 或 claude）
agents.list[].runtime.acp.backend
agents.list[].runtime.acp.mode
agents.list[].runtime.acp.cwd

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

bindings[].acp.*
agents.list[].runtime.acp.*
全局 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。
临时运行时绑定（例如由 thread-focus 流程创建的绑定）在存在时仍然适用。
对于没有显式 cwd 的跨 agent ACP spawn，OpenClaw 会从 agent 配置继承目标 agent 工作区。
缺失的继承工作区路径会回退到后端默认 cwd；非缺失的访问失败会作为 spawn 错误返回。

启动 ACP 会话

启动 ACP 会话有两种方式：

From sessions_spawn
From /acp command

使用 runtime: "acp" 从 agent 回合或工具调用中启动一个 ACP 会话。

{
  "task": "打开仓库并总结失败的测试",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

runtime 默认是 subagent，因此 ACP 会话需要显式设置 runtime: "acp"。如果省略 agentId，OpenClaw 会在已配置时使用 acp.defaultAgent。mode: "session" 需要 thread: true 才能保持持久的绑定对话。

使用 /acp spawn 从聊天中进行显式操作者控制。

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

参见斜杠命令。

`sessions_spawn` 参数

task

string

required

发送给 ACP 会话的初始提示词。

runtime

"acp"

required

ACP 会话必须为 "acp"。

agentId

string

ACP 目标 harness id。如果已设置，则回退到 acp.defaultAgent。

thread

boolean

default:"false"

请求在支持的情况下启用线程绑定流程。

mode

"run" | "session"

default:"run"

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

"parent" streams initial ACP run progress summaries back to the requester session as system events. Accepted responses include streamLogPath pointing to a session-scoped JSONL log (<sessionId>.acp-stream.jsonl) you can tail for full relay history. Parent progress streams show assistant commentary and ACP status progress by default unless streaming.progress.commentary=false. Discord also defaults parent previews to progress mode when no stream mode is configured. Status progress still honors acp.stream.tagVisibility, so tags such as plan remain hidden unless explicitly enabled.

ACP sessions_spawn runs use agents.defaults.subagents.runTimeoutSeconds for their default child turn limit. The tool does not accept per-call timeout overrides.

model

string

Explicit model override for the ACP child session. Codex ACP spawns normalize OpenAI refs such as openai/gpt-5.4 to Codex ACP startup config before session/new; slash forms such as openai/gpt-5.4/high also set Codex ACP reasoning effort. When omitted, sessions_spawn({ runtime: "acp" }) uses existing subagent model defaults (agents.defaults.subagents.model or agents.list[].subagents.model) when configured; otherwise it lets the ACP harness use its own default model. Other harnesses must advertise ACP models and support session/set_model; otherwise OpenClaw/acpx fails clearly instead of silently falling back to the target agent default.

thinking

string

Explicit thinking/reasoning effort. For Codex ACP, minimal maps to low effort, low/medium/high/xhigh map directly, and off omits the reasoning-effort startup override. When omitted, ACP spawns use existing subagent thinking defaults and per-model agents.defaults.models["provider/model"].params.thinking for the selected model.

Spawn 的 bind 和 thread 模式

--bind here|off
--thread auto|here|off

Mode	Behavior
`here`	原地绑定当前活动对话；如果没有活动对话则失败。
`off`	不创建当前对话绑定。

说明：

--bind here 是“让这个频道或聊天使用 Codex 后端”的最简单操作者路径。
--bind here 不会创建子线程。
--bind here 仅在暴露当前对话绑定支持的频道上可用。
--bind 和 --thread 不能在同一个 /acp spawn 调用中同时使用。

Mode	Behavior
`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 向 harness 发送的内容：

普通的绑定后续消息会作为提示词文本发送，只有在 harness/后端支持时才会附带附件。
/acp 管理命令和本地 Gateway 命令会在 ACP 派发前被拦截。
运行时生成的完成事件会按目标具现化。OpenClaw agent 会收到 OpenClaw 内部的运行时上下文信封；外部 ACP harness 会收到一个只包含子结果和指令的纯提示词。原始的 <<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>> 信封绝不应发送给外部 harness，也不应作为 ACP 用户对话文本持久化。
ACP 转录条目使用面向用户的触发文本或纯完成提示词。内部事件元数据会尽可能保持为 OpenClaw 中的结构化内容，不会被视为用户撰写的聊天内容。

父拥有的一次性 ACP 会话

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

父通过 sessions_spawn({ runtime: "acp", mode: "run" }) 请求工作。
子在其自己的 ACP harness 会话中运行。
子回合运行在原生子代理 spawn 所使用的同一后台线路上，因此缓慢的 ACP harness 不会阻塞无关的主会话工作。
完成结果会通过任务完成通知路径回传。OpenClaw 会在把内部完成元数据发送给外部 harness 之前，将其转换为纯 ACP 提示词，因此 harness 不会看到 OpenClaw 专用的运行时上下文标记。
如果需要面向用户的回复，父会用正常的助手语气改写子结果。

不要把这条路径当作父与子之间的点对点聊天。子已经有一条回到父的完成通道。

sessions_send 和 A2A 投递

sessions_send 在 spawn 之后可以目标指向另一个会话。对于普通的 peer 会话，OpenClaw 在注入消息后会使用 agent-to-agent（A2A）后续路径：

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

该 A2A 路径是 peer 发送在需要可见后续时的回退方案。只要一个无关会话能够看到并向 ACP 目标发送消息，它就会保持启用，例如在较宽松的 tools.sessions.visibility 设置下。只有当请求者是其自身父拥有的一次性 ACP 子会话的父级时，OpenClaw 才会跳过 A2A 后续。在这种情况下，在任务完成之上再运行 A2A 可能会用子结果唤醒父级，再把父级的回复转发回子级，并创建父/子回声循环。对于这种被拥有的子会话，sessions_send 结果会报告 delivery.status="skipped"，因为完成路径已经负责该结果。

恢复已有会话

使用 resumeSessionId 继续之前的 ACP 会话，而不是重新开始。agent 会通过 session/load 回放其对话历史，因此它会带着之前完整的上下文继续。

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

常见用例：

将一个 Codex 会话从你的笔记本电脑接手到手机上 - 让你的 agent 继续你离开的地方。
继续你曾在 CLI 中交互式开始的编码会话，现在通过 agent 无头继续。
接手因网关重启或空闲超时而中断的工作。

说明：

resumeSessionId 仅适用于 runtime: "acp"；默认的子代理运行时会忽略这个仅 ACP 可用的字段。
streamTo 仅适用于 runtime: "acp"；默认的子代理运行时会忽略这个仅 ACP 可用的字段。
resumeSessionId 是主机本地的 ACP/harness 恢复 id，不是 OpenClaw 频道会话 key；OpenClaw 在派发前仍会检查 ACP spawn 策略和目标 agent 策略，而 ACP 后端或 harness 负责对该上游 id 的加载授权。
resumeSessionId 会恢复上游 ACP 对话历史；thread 和 mode 仍然按常规应用到你正在创建的新 OpenClaw 会话，因此 mode: "session" 仍然需要 thread: true。
目标 agent 必须支持 session/load（Codex 和 Claude Code 都支持）。
如果找不到该会话 id，spawn 会以清晰错误失败 - 不会静默回退到新会话。

部署后冒烟测试

在网关部署后，运行一次真实的端到端检查，而不是相信单元测试：

验证目标主机上部署的网关版本和提交。
打开一个到在线 agent 的临时 ACPX bridge 会话。
让该 agent 调用 sessions_spawn，并设置 runtime: "acp"、agentId: "codex"、mode: "run"，任务为 Reply with exactly LIVE-ACP-SPAWN-OK。
验证 accepted=yes、真实的 childSessionKey，且没有 validator 错误。
清理临时 bridge 会话。

保持 gate 使用 mode: "run"，并跳过 streamTo: "parent" - 线程绑定的 mode: "session" 和 stream-relay 路径是独立的更丰富的集成流程。

沙箱兼容性

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

安全边界：

外部 harness 可以根据其自身的 CLI 权限和所选 cwd 进行读写。
OpenClaw 的沙箱策略不会包裹 ACP harness 执行。
OpenClaw 仍然会强制执行 ACP 功能开关、允许的 agent、会话所有权、频道绑定和 Gateway 投递策略。
对于受沙箱约束的 OpenClaw 原生工作，请使用 runtime: "subagent"。

当前限制：

如果请求者会话处于沙箱中，则 sessions_spawn({ runtime: "acp" }) 和 /acp spawn 都会被阻止。
runtime: "acp" 的 sessions_spawn 不支持 sandbox: "require"。

会话目标解析

大多数 /acp 操作都接受一个可选的会话目标（session-key、 session-id 或 session-label）。 解析顺序：

显式目标参数（或 /acp steer 的 --session）
- 先尝试 key
- 再尝试 UUID 形式的 session id
- 最后尝试 label
当前线程绑定（如果此对话/线程已绑定到 ACP 会话）。
当前请求者会话回退。

当前对话绑定和线程绑定都会参与第 2 步。如果无法解析目标，OpenClaw 会返回明确的错误（Unable to resolve session target: ...）。

ACP 控制

Command	功能	示例
`/acp spawn`	创建 ACP 会话；可选择当前绑定或线程绑定。	`/acp spawn codex --bind here --cwd /repo`
`/acp cancel`	取消目标会话正在进行中的 turn。	`/acp cancel agent:codex:acp:<uuid>`
`/acp steer`	向运行中的会话发送 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）通过网关会话发现进行解析，包括按代理自定义的 session.store 根目录。

运行时选项映射

/acp 既有便捷命令，也有通用 setter。等价操作如下：

Command	Maps to	Notes
`/acp model <id>`	runtime config key `model`	For Codex ACP, OpenClaw normalizes `openai/<model>` to the adapter model id and maps slash reasoning suffixes such as `openai/gpt-5.4/high` to `reasoning_effort`.
`/acp set thinking <level>`	canonical option `thinking`	OpenClaw sends the backend-advertised equivalent when present, preferring `thinking`, then `effort`, `reasoning_effort`, or `thought_level`. For Codex ACP, the adapter maps values to `reasoning_effort`.
`/acp permissions <profile>`	canonical option `permissionProfile`	OpenClaw sends the backend-advertised equivalent when present, such as `approval_policy`, `permission_profile`, `permissions`, or `permission_mode`.
`/acp timeout <seconds>`	canonical option `timeoutSeconds`	OpenClaw sends the backend-advertised equivalent when present, such as `timeout` or `timeout_seconds`.
`/acp cwd <path>`	runtime cwd override	Direct update.
`/acp set <key> <value>`	generic	`key=cwd` uses the cwd override path.
`/acp reset-options`	clears all runtime overrides	-

acpx 运行器、插件设置和权限

关于 acpx harness 配置（Claude Code / Codex / Gemini CLI 别名）、plugin-tools 和 OpenClaw-tools MCP 桥接，以及 ACP 权限模式，请参阅 ACP agents - setup。

故障排查

Symptom	Likely cause	Fix
`ACP runtime backend is not configured`	后端插件缺失、被禁用，或被 `plugins.allow` 阻止。	安装并启用后端插件；如果设置了 allowlist，则将 `acpx` 包含进 `plugins.allow`，然后运行 `/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` reports backend not ready right after startup	后端插件缺失、被禁用、被 allow/deny 策略阻止，或其配置的可执行文件不可用。	安装/启用后端插件，重新运行 `/acp doctor`，如果状态仍不正常，则检查后端安装或策略错误。
Harness command not found	适配器 CLI 未安装、外部插件缺失，或非 Codex 适配器首次运行时 `npx` 获取失败。	运行 `/acp doctor`，在 Gateway 主机上安装/预热适配器，或显式配置 acpx agent 命令。
Model-not-found from the harness	模型 id 对其他 provider/harness 有效，但对这个 ACP 目标无效。	使用该 harness 列出的模型，在 harness 中配置模型，或省略该覆盖项。
Vendor auth error from the harness	OpenClaw 状态正常，但目标 CLI/provider 尚未登录。	在 Gateway 主机环境中登录，或提供所需的 provider key。
`Unable to resolve session target: ...`	key/id/label token 错误。	运行 `/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"`，或在非沙箱会话中使用 `sandbox="inherit"` 的 ACP。
`Cannot apply --model ... did not advertise model support`	目标 harness 未公开通用 ACP 模型切换能力。	使用声明了 ACP `models`/`session/set_model` 的 harness，使用 Codex ACP model refs，或如果 harness 自身有启动参数，则在其中直接配置模型。
Missing ACP metadata for bound session	ACP 会话元数据已过期/已删除。	使用 `/acp spawn` 重新创建，然后重新绑定/聚焦线程。
`AcpRuntimeError: Permission prompt unavailable in non-interactive mode`	在非交互式 ACP 会话中，`permissionMode` 阻止了写入/执行。	将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 gateway。参见 Permission configuration。
ACP session fails early with little output	`permissionMode`/`nonInteractivePermissions` 阻止了权限提示。	检查 gateway 日志中的 `AcpRuntimeError`。如需完整权限，将 `permissionMode` 设为 `approve-all`；如需优雅降级，将 `nonInteractivePermissions` 设为 `deny`。
ACP session stalls indefinitely after completing work	harness 进程已结束，但 ACP 会话未报告完成。	更新 OpenClaw；当前的 acpx 清理会在关闭和 Gateway 启动时回收属于 OpenClaw 的陈旧 wrapper 和 adapter 进程。
Harness sees `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>`	内部事件封装泄漏到了 ACP 边界之外。	更新 OpenClaw 并重新运行完成流程；外部 harness 应只接收纯粹的完成提示。

Command blocked by PreToolUse hook: Native hook relay unavailable belongs to the native Codex hook relay, not ACP/acpx. In a bound Codex chat, start a fresh session with /new or /reset; if it works once and then returns on the next native tool call, restart the Codex app-server or OpenClaw Gateway instead of repeating /new. See Codex harness troubleshooting.

​我该看哪个页面？

​这开箱即用吗？

​支持的 harness 目标

​操作手册

​ACP 与子代理

​ACP 如何运行 Claude Code

​绑定会话

​心智模型

​当前对话绑定

​持久频道绑定

​绑定模型

​每个 agent 的运行时默认值

​示例

​行为

​启动 ACP 会话

​sessions_spawn 参数

​Spawn 的 bind 和 thread 模式

​投递模型

​沙箱兼容性

​会话目标解析

​ACP 控制

​运行时选项映射

​acpx 运行器、插件设置和权限

​故障排查

​相关内容

我该看哪个页面？

这开箱即用吗？

支持的 harness 目标

操作手册

ACP 与子代理

ACP 如何运行 Claude Code

绑定会话

心智模型

当前对话绑定

持久频道绑定

绑定模型

每个 agent 的运行时默认值

示例

行为

启动 ACP 会话

`sessions_spawn` 参数

Spawn 的 bind 和 thread 模式

投递模型

沙箱兼容性

会话目标解析

ACP 控制

运行时选项映射

acpx 运行器、插件设置和权限

故障排查

相关内容