ACP 智能体

• 如果设置了 plugins.allow，它就是限制性插件清单，且必须包含 acpx，否则已安装的 ACP 后端会被有意阻止（/acp doctor 会报告缺少允许列表条目）。
• Codex ACP 适配器随 acpx 插件一起提供，并会尽可能在本地启动。
• Codex ACP 使用隔离的 CODEX_HOME 运行。OpenClaw 会从主机 Codex 配置中复制受信任项目的信任条目，以及安全的模型/提供商路由配置（model、model_provider、model_reasoning_effort、sandbox_mode 和安全的 model_providers.<name> 字段）；身份验证、通知和钩子仅保留在主机配置中。
• 其他目标执行框架适配器可能会在首次使用时通过 npx 按需获取。
• 该执行框架所需的供应商身份验证必须已存在于主机上。
• 如果主机无法使用 npm 或访问网络，首次运行时获取适配器会失败，直到预热缓存或通过其他方式安装适配器。

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

在归咎于 OpenClaw 之前，请确认：

• /acp doctor 报告后端已启用且运行状况正常。
• 设置 acp.allowedAgents 允许列表后，目标 ID 位于其中。
• 执行框架命令可以在 Gateway 网关主机上启动。
• 该执行框架具备提供商身份验证（claude、codex、gemini、opencode、droid 等）。
• 所选模型存在于该执行框架中——模型 ID 无法跨执行框架通用。
• 请求的 cwd 存在且可访问；或者省略 cwd，让后端使用其默认值。
• 权限模式与工作内容匹配。非交互式会话无法点击原生权限提示，因此涉及大量写入/执行操作的编码任务通常需要能够以无头方式继续运行的 ACPX 权限配置文件。

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

启用原生 Codex 插件后，以下自然语言触发语句应路由到该插件：

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

原生 Codex 对话绑定是默认的聊天控制路径。 OpenClaw 动态工具仍通过 OpenClaw 执行，而 shell/apply-patch 等 Codex 原生工具则在 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 支持契约 中。

• 旧版 Codex 模型引用 - 由 Doctor 修复的旧版 Codex OAuth/订阅模型路由。
• openai/* - 用于 OpenAI 智能体轮次的原生 Codex app-server 嵌入式运行时。
• /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" }) 调用。它以 codex、claude、 droid、gemini 或 opencode 等 ACP harness ID 为目标。除非 agents_list 中的普通 OpenClaw 配置智能体 ID 已通过 agents.list[].runtime.type="acp" 明确配置，否则不要传递该 ID； 应改用默认子智能体运行时。当 OpenClaw 智能体配置了 runtime.type="acp" 时，OpenClaw 使用 runtime.acp.agent 作为底层 harness ID。

• --bind here 与 --thread ... 互斥。
• --bind here 仅适用于声明支持当前对话绑定的渠道；否则 OpenClaw 会返回清晰的不支持提示。绑定会在 Gateway 网关重启后继续保留。
• 在 Discord 上，spawnSessions 控制 --thread auto|here 的子线程创建，而不控制 --bind here。
• 如果你生成到另一个 ACP 智能体且未指定 --cwd，OpenClaw 默认继承目标智能体的工作区。继承的路径不存在（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 发送给 harness 的内容：

• 普通的已绑定后续消息会作为提示词文本发送，仅在 harness/后端支持时附带附件。
• /acp 管理命令和本地 Gateway 网关命令会在分派到 ACP 之前被拦截。
• 运行时生成的完成事件会针对每个目标进行具体化。OpenClaw 智能体会收到 OpenClaw 的内部运行时上下文信封；外部 ACP harness 会收到包含子任务结果和指令的纯提示词。原始 <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> 信封绝不能发送到外部 harness，也不能作为 ACP 用户转录文本持久化。
• ACP 转录条目使用用户可见的触发文本或纯完成提示词。内部事件元数据会尽可能以结构化形式保留在 OpenClaw 中，不会被视为用户编写的聊天内容。

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

• 父会话使用 sessions_spawn({ runtime: "acp", mode: "run" }) 请求执行工作。
• 子会话在其自身的 ACP harness 会话中运行。
• 子轮次在原生子智能体派生所用的同一个后台通道中运行，因此缓慢的 ACP harness 不会阻塞无关的主会话工作。
• 完成结果通过任务完成通知路径报告回来。OpenClaw 在将内部完成元数据发送到外部 harness 之前，会将其转换为纯 ACP 提示词，因此 harness 不会看到仅供 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/harness 恢复 ID，而不是 OpenClaw 渠道会话键；OpenClaw 在分派前仍会检查 ACP 生成策略和目标智能体策略，而加载该上游 ID 的授权由 ACP 后端或 harness 负责。
• 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" 和流中继路径属于另外两项功能更丰富的集成验证。