ACP 智能体操作员运行手册

• 启动（Spawn）会创建或恢复 ACP 运行时会话，并在 OpenClaw 会话存储中记录 ACP 元数据。父级拥有的运行使用原生子代理生命周期来完成。
• 启动失败时，会等待任何已开始的临时会话删除完成后再返回，包括清理请求截止时间已到期的情况。
• 即使运行时会话是持久性的，父级拥有的 ACP 会话也被视为后台工作；完成和跨界面交付遵循其已接受的原生完成路径，而不是像正常的面向用户的聊天会话那样运作。
• ACP 控制平面会在回合结束后关闭一次性运行时句柄。持久性会话保留其 ACP 会话和绑定生命周期；使用 /acp close 显式结束会话。清理不依赖于 Tasks 记录。
• 绑定的后续消息会直接发送到 ACP 会话，直到绑定被关闭、解除、重置或过期。
• 网关命令保持本地处理。/acp ...、/status 和 /session 永远不会作为普通提示文本发送到绑定的 ACP harness。
• cancel 在后端支持取消时中止当前回合；它不会删除绑定或会话元数据。
• 回合完成会等待排队输出的交付。如果交付失败，OpenClaw 会取消当前回合，并在配置的回合超时时间内等待后端清理完毕，然后再开始下一个排队的回合。
• close 从 OpenClaw 的角度结束 ACP 会话并移除绑定。如果 harness 支持恢复，它可能仍会保留自己的上游历史。
• acpx 插件会在 close 之后清理 OpenClaw 拥有的包装器和适配器进程树，并在 Gateway 启动期间回收过期的 OpenClaw 拥有的 ACPX 孤立进程。
• 空闲的运行时工作进程在内置空闲期过后可被清理；存储的会话元数据仍然可通过 /acp sessions 获取。

启用后应路由到原生 Codex 插件的自然语言触发器：

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

原生 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 支持合同 中有文档说明。

• legacy Codex model refs —— 由 doctor 修复的 legacy 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，在支持时 绑定到当前会话或线程，并将后续消息路由到该会话，直到关闭/过期。 Codex 仅在 ACP/acpx 是显式指定的，或原生 Codex 插件无法执行所请求的 操作时，才会遵循此路径。

对于 sessions_spawn，仅当 ACP 已启用、请求者未被沙箱化且已加载 ACP 运行时后端时，才会公布 runtime: "acp"。acp.dispatch.enabled=false 会暂停自动 ACP 线程调度，但不会隐藏或阻止显式的 sessions_spawn({ runtime: "acp" }) 调用。它针对 codex、claude、 droid、gemini 或 opencode 等 ACP harness 标识符。不要传递 agents_list 中的普通 OpenClaw 配置代理 ID，除非该条目已显式配置为 agents.entries.*.runtime.type="acp"；否则请使用默认子代理运行时。 当 OpenClaw 代理配置了 runtime.type="acp" 时，OpenClaw 将使用 runtime.acp.agent 作为底层 harness 标识符。