ACP 智能体

• 如果设置了 plugins.allow，它就是限制性的插件清单，并且必须包含 acpx；否则已安装的 ACP 后端会被有意阻止，/acp doctor 会报告缺少 allowlist 条目。
• Codex ACP 适配器随 acpx 插件暂存，并在可能时本地启动。
• Codex ACP 使用隔离的 CODEX_HOME 运行；OpenClaw 只从主机 Codex 配置复制受信任的项目条目，并信任活动工作区，将凭证、通知和钩子留在主机配置中。
• 其他目标 harness 适配器可能仍会在首次使用时按需通过 npx 获取。
• 该 harness 的供应商凭证仍必须存在于主机上。
• 如果主机没有 npm 或网络访问权限，首次运行的适配器获取会失败，直到缓存已预热或通过其他方式安装适配器。

ACP 会启动真实的外部 harness 进程。OpenClaw 负责路由、 后台任务状态、投递、绑定和策略；harness 负责自己的提供商登录、 模型目录、文件系统行为和原生工具。

在归因于 OpenClaw 之前，请验证：

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

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

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

• “将这个 Discord 渠道绑定到 Codex。”
• “将这个聊天附加到 Codex thread <id>。”
• “显示 Codex threads，然后绑定这一个。”

原生 Codex 会话绑定是默认的聊天控制路径。 OpenClaw 动态工具仍通过 OpenClaw 执行，而 Codex 原生工具（如 shell/apply-patch）在 Codex 内执行。 对于 Codex 原生工具事件，OpenClaw 会注入按轮次的原生 钩子中继，使插件钩子可以阻止 before_tool_call、观察 after_tool_call，并通过 OpenClaw 审批路由 Codex PermissionRequest 事件。 Codex Stop 钩子会被中继到 OpenClaw before_agent_finalize，插件可在 Codex 定稿答案之前请求再进行一次 模型传递。该中继有意保持保守：它不会修改 Codex 原生工具 参数，也不会重写 Codex 线程记录。只有在你需要 ACP 运行时/会话模型时， 才使用显式 ACP。嵌入式 Codex 支持边界记录在 Codex harness v1 支持契约中。

• openai-codex/* - 由 Doctor 修复的旧版 Codex OAuth/订阅模型路由。
• openai/* - 用于 OpenAI agent 轮次的原生 Codex 应用服务器嵌入式运行时。
• /codex ... - 原生 Codex 会话控制。
• /acp ... 或 runtime: "acp" - 显式 ACP/acpx 控制。

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

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

OpenClaw 会选择 runtime: "acp"，解析 harness agentId， 在受支持时绑定到当前会话或线程，并 将后续跟进路由到该会话，直到关闭/过期。只有在 ACP/acpx 被显式指定， 或原生 Codex 插件无法用于所请求操作时，Codex 才会走此路径。

对于 sessions_spawn，只有在 ACP 已启用、请求者未被沙箱隔离，并且已加载 ACP 运行时 后端时，才会公告 runtime: "acp"。acp.dispatch.enabled=false 会暂停自动 ACP 线程分派，但不会隐藏或阻止显式 sessions_spawn({ runtime: "acp" }) 调用。它面向 ACP harness 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 作为底层 harness id。

• --bind here 和 --thread ... 相互排斥。
• --bind here 仅适用于公告当前会话绑定能力的渠道；否则 OpenClaw 会返回清晰的不支持消息。绑定会在 gateway 重启后保留。
• 在 Discord 上，spawnSessions 会门控 --thread auto|here 的子线程创建 - 不门控 --bind here。
• 如果你生成到另一个 ACP agent 且不带 --cwd，OpenClaw 默认继承目标 agent 的工作区。缺失的继承路径（ENOENT/ENOTDIR）会回退到后端默认值；其他访问错误（例如 EACCES）会作为生成错误显示。
• Gateway 网关管理命令在绑定会话中保持本地处理 - 即使普通后续文本会路由到绑定的 ACP 会话，/acp ... 命令仍由 OpenClaw 处理；只要该界面启用了命令处理，/status 和 /unfocus 也会保持本地处理。

当某个渠道适配器启用线程绑定时：

• OpenClaw 会将线程绑定到目标 ACP 会话。
• 该线程中的后续消息会路由到绑定的 ACP 会话。
• ACP 输出会投递回同一个线程。
• 取消聚焦/关闭/归档/空闲超时或最大年龄过期会移除绑定。
• /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 话题（群组/超级群组中的论坛话题以及私信话题）。
• 插件渠道可以通过同一绑定接口添加支持。

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

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

已绑定对话中的后续消息会直接路由到 ACP 会话，ACP 输出也会交付回同一个渠道/线程/主题。

OpenClaw 发送给运行框架的内容：

• 普通绑定后续消息会作为提示文本发送，并且仅在运行框架/后端支持时附带附件。
• /acp 管理命令和本地 Gateway 网关命令会在 ACP 分发前被拦截。
• 运行时生成的完成事件会按目标实体化。OpenClaw 智能体会收到 OpenClaw 的内部运行时上下文信封；外部 ACP 运行框架会收到包含子结果和指令的普通提示。原始 <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> 信封绝不应发送给外部运行框架，也不应作为 ACP 用户转录文本持久化。
• ACP 转录条目使用用户可见的触发文本或普通完成提示。在可行时，内部事件元数据会在 OpenClaw 中保持结构化，并且不会被视为用户撰写的聊天内容。

由另一个智能体运行派生的一次性 ACP 会话是后台子任务，类似子智能体：

• 父级使用 sessions_spawn({ runtime: "acp", mode: "run" }) 请求工作。
• 子级在自己的 ACP 运行框架会话中运行。
• 子轮次运行在原生子智能体派生使用的同一个后台通道上，因此缓慢的 ACP 运行框架不会阻塞无关的主会话工作。
• 完成结果会通过任务完成公告路径回报。OpenClaw 会先把内部完成元数据转换成普通 ACP 提示，再发送给外部运行框架，因此运行框架不会看到仅 OpenClaw 使用的运行时上下文标记。
• 当用户可见回复有用时，父级会用正常助手语气重写子结果。

不要把此路径视为父级和子级之间的点对点聊天。子级已经有返回父级的完成渠道。

sessions_send 可以在派生后指向另一个会话。对于普通对等会话，OpenClaw 在注入消息后使用智能体到智能体（A2A）后续路径：

• 等待目标会话的回复。
• 可选地让请求方和目标交换有限数量的后续轮次。
• 要求目标生成一条公告消息。
• 将该公告交付到可见渠道或线程。

该 A2A 路径是对等发送的回退方案，适用于发送方需要可见后续回复的场景。当无关会话可以看到并向 ACP 目标发送消息时，例如在宽泛的 tools.sessions.visibility 设置下，它仍会保持启用。

只有当请求方是其自己父级拥有的一次性 ACP 子级的父级时，OpenClaw 才会跳过 A2A 后续。在这种情况下，在任务完成之上运行 A2A 可能会用子结果唤醒父级，把父级回复转发回子级，并产生父/子回声循环。对于这种自有子级情况，sessions_send 结果会报告 delivery.status="skipped"，因为完成路径已经负责交付结果。

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

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

常见用例：

• 将 Codex 会话从你的笔记本电脑交接到手机上，即告诉你的智能体从上次中断处继续。
• 继续你先前在 CLI 中以交互方式启动的编码会话，现在通过你的智能体以无头方式继续。
• 继续因 Gateway 网关重启或空闲超时而中断的工作。

注意事项：

• resumeSessionId 仅在 runtime: "acp" 时适用；默认子智能体运行时会忽略这个仅 ACP 使用的字段。
• streamTo 仅在 runtime: "acp" 时适用；默认子智能体运行时会忽略这个仅 ACP 使用的字段。
• resumeSessionId 是主机本地 ACP/运行框架恢复 ID，不是 OpenClaw 渠道会话键；OpenClaw 在分发前仍会检查 ACP 派生策略和目标智能体策略，而 ACP 后端或运行框架负责加载该上游 ID 的授权。
• resumeSessionId 会恢复上游 ACP 对话历史；thread 和 mode 仍正常应用于你正在创建的新 OpenClaw 会话，因此 mode: "session" 仍需要 thread: true。
• 目标智能体必须支持 session/load（Codex 和 Claude Code 支持）。
• 如果找不到会话 ID，派生会以明确错误失败，不会静默回退到新会话。

Gateway 网关部署后，请运行一次实时端到端检查，而不是信任单元测试：

1. 验证目标主机上已部署的 Gateway 网关版本和提交。
2. 打开一个连接到实时智能体的临时 ACPX 桥接会话。
3. 要求该智能体调用 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" 和流中继路径属于单独的、 更完整的集成验证流程。