ACP Harness 路由器

ACP Harness 路由器 是做什么的？

当用户意图是“在 Claude Code/Cursor/Copilot/OpenClaw/OpenCode/Gemini/Qwen/Kiro/Kimi/iFlow/Droid/Kilocode (ACP harness) 中运行此操作”时，请勿使用子代理运行时或 PTY 采样。通过 ACP 感知的流程进行路由。

Codex 是特殊情况：普通的聊天/对话绑定和控制应使用原生的 Codex 应用服务器插件（/codex bind、/codex threads、/codex resume），而非默认的 ACP 路径。仅当用户明确指定 ACP//acp/acpx 时，或通过 sessions_spawn 生成后台子会话（此时尚无原生的 Codex 运行时生成功能可用）时，才对 Codex 使用 ACP。

意图检测

当用户要求 OpenClaw 执行以下操作时，触发此技能：

• 在 Claude Code / Cursor / Copilot / OpenClaw / OpenCode / Gemini / Qwen / Kiro / Kimi / iFlow / Droid / Kilocode 中运行某些内容
• 通过 ACP、/acp 或 acpx 显式运行 Codex
• 继续现有的工具链工作
• 将指令转发到外部编码工具链
• 在类似线程的对话中维护外部工具链对话

编码代理线程请求的强制性预检查：

• 在创建任何用于 ACP 工具链工作的线程之前，在同一个轮次中首先阅读此技能。
• 阅读后，遵循下面的 OpenClaw ACP runtime path；不要使用 message(action="thread-create") 来生成 ACP 工具链线程。

模式选择

选择以下路径之一：

1. OpenClaw ACP 运行时路径（默认）：使用 sessions_spawn / ACP 运行时工具。
2. 直接 acpx 路径（电话游戏）：通过 exec 使用 acpx CLI 直接驱动工具链会话。

当以下任一条件成立时，使用直接 acpx 路径：

• 用户明确要求直接使用 acpx 驱动
• ACP 运行时/插件路径不可用或不健康
• 任务只是“将提示转发给工具链”，不需要 OpenClaw ACP 的生命周期功能

请勿使用：

• subagents 运行时控制工具链
• 要求用户通过 /acp 命令委派
• 当 acpx 可用时，对支持的 ACP 工具链 CLI 进行 PTY 采样

AgentId 映射

当用户直接命名工具链时，使用以下默认值：

• "openclaw" -> agentId: "openclaw"
• "claude" 或 "claude code" -> agentId: "claude"
• "codex" -> agentId: "codex"（仅用于显式 ACP/acpx 请求或后台 ACP 运行时生成）
• "copilot" 或 "github copilot" -> agentId: "copilot"
• "cursor" 或 "cursor cli" -> agentId: "cursor"
• "droid" 或 "factory droid" -> agentId: "droid"
• "opencode" -> agentId: "opencode"
• "gemini" 或 "gemini cli" -> agentId: "gemini"
• "iflow" -> agentId: "iflow"
• "kilocode" -> agentId: "kilocode"
• "kimi" 或 "kimi cli" -> agentId: "kimi"
• "kiro" 或 "kiro cli" -> agentId: "kiro"
• "qwen" 或 "qwen code" -> agentId: "qwen"

这些默认值与当前的 acpx 内置别名匹配。

如果策略拒绝了所选的 id，请清晰地报告策略错误，并询问允许的 ACP 代理 ID。

OpenClaw ACP 运行时路径

必需的行为：

1. 对于 ACP 工具链线程生成请求，在调用工具之前，在同一轮次中首先阅读此技能。
2. 使用 sessions_spawn，并设置：
   • runtime: "acp"
   • thread: true
   • mode: "session"（除非用户明确要求一次性模式）
3. 对于 ACP 工具链线程创建，请勿使用带有 action=thread-create 的 message；sessions_spawn 是唯一的线程创建路径。
4. 将请求的工作放入 task 中，以便 ACP 会话立即获得它。
5. 除非已知 ACP 默认代理，否则显式设置 agentId。
6. 当此路径可直接工作时，不要要求用户运行斜杠命令或 CLI。

示例：

用户：“生成一个测试 codex ACP 会话到线程中，并告诉它打个招呼”

调用：

{
  "task": "Say hi.",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

线程生成恢复策略

当用户要求在线程中启动一个编码工具链时，将其视为 ACP 运行时请求，并尝试端到端地满足它。

ACP 后端不可用时的必需行为：

1. 不要立即要求用户选择替代路径。
2. 首先尝试自动本地修复：
   • 检查 ACPX 插件包中是否安装了插件本地的固定版本 acpx
   • 验证 ${ACPX_CMD} --version
3. 重新安装/修复后，重启网关并显式提供为用户运行该重启的选项。
4. 修复后重试一次 ACP 线程生成。
5. 仅在修复+重试失败后，报告具体错误，然后提供回退选项。

在提供回退时，始终将 ACP 选项放在首位：

• 选项 1：在显示确切的失败步骤后重试 ACP 生成
• 选项 2：直接 acpx 电话游戏流程

对于这些请求，不要默认使用子代理运行时。

ACPX 安装和版本策略（直接 acpx 路径）

对于此仓库，直接的 acpx 调用必须遵循与 @openclaw/acpx 扩展包相同的固定版本策略。

1. 优先使用插件本地二进制文件，而非全局 PATH：
   • ${ACPX_PLUGIN_ROOT}/node_modules/.bin/acpx
2. 从扩展依赖项解析固定版本：
   • node -e "console.log(require(process.env.ACPX_PLUGIN_ROOT + '/package.json').dependencies.acpx)"
3. 如果二进制文件缺失或版本不匹配，安装插件本地的固定版本：
   • cd "$ACPX_PLUGIN_ROOT" && npm install --omit=dev --no-save acpx@<pinnedVersion>
4. 使用前验证：
   • ${ACPX_PLUGIN_ROOT}/node_modules/.bin/acpx --version
5. 如果安装/修复更改了 ACPX 工件，请重启网关并提供运行重启的选项。
6. 除非用户明确要求全局安装，否则不要运行 npm install -g acpx。

设置并复用：

ACPX_PLUGIN_ROOT="<bundled-acpx-plugin-root>"
ACPX_CMD="$ACPX_PLUGIN_ROOT/node_modules/.bin/acpx"

直接 acpx 路径（“电话游戏”）

使用此路径来驱动工具链会话，无需 /acp 或子代理运行时。

规则

1. 使用调用 ${ACPX_CMD} 的 exec 命令。
2. 每个对话复用稳定的会话名称，以便后续提示停留在同一工具链上下文中。
3. 优先使用 --format quiet，以获得干净的助理文本以转发回用户。
4. 仅当用户想要一次性行为时，才使用 exec（一次性）。
5. 当任务范围依赖于仓库上下文时，保持工作目录显式设置（--cwd）。

会话命名

使用稳定的名称，例如：

• oc-<harness>-<conversationId>

其中 conversationId 在线程可用时是线程 ID，否则是渠道/对话 ID。

命令模板

持久性会话（不存在则创建，然后提示）：

${ACPX_CMD} codex sessions show oc-codex-<conversationId> \
  || ${ACPX_CMD} codex sessions new --name oc-codex-<conversationId>

${ACPX_CMD} codex -s oc-codex-<conversationId> --cwd <workspacePath> --format quiet "<prompt>"

一次性：

${ACPX_CMD} codex exec --cwd <workspacePath> --format quiet "<prompt>"

取消正在进行的轮次：

${ACPX_CMD} codex cancel -s oc-codex-<conversationId>

关闭会话：

${ACPX_CMD} codex sessions close oc-codex-<conversationId>

acpx 中的工具链别名

• claude
• codex
• copilot
• cursor
• droid
• gemini
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• qwen

acpx 中的内置适配器命令

默认值为：

• openclaw -> openclaw acp
• claude -> bundled @agentclientprotocol/[email protected]
• codex -> bundled @agentclientprotocol/[email protected]，通过 OpenClaw 隔离的 CODEX_HOME 包装器
• copilot -> copilot --acp --stdio
• cursor -> cursor-agent acp
• droid -> droid exec --output-format acp
• gemini -> gemini --acp
• iflow -> iflow --experimental-acp
• kilocode -> npx -y @kilocode/cli acp
• kimi -> kimi acp
• kiro -> kiro-cli acp
• opencode -> npx -y opencode-ai acp
• qwen -> qwen --acp

如果 ~/.acpx/config.json 覆盖了 agents，则这些覆盖项将替换默认值。 如果您的本地 Cursor 安装仍将 ACP 暴露为 agent acp，请显式将 cursor 代理覆盖设置为该值。

故障处理

• acpx: command not found：
  • 对于线程生成的 ACP 请求，立即在 ACPX 插件包中安装插件本地的固定版本 acpx
  • 安装后重启网关，并提供自动运行该重启的选项
  • 然后重试一次
  • 除非策略明确要求，否则不要先请求安装权限
  • 除非用户明确要求，否则不要安装全局 acpx
• 适配器命令缺失（例如找不到 claude-agent-acp）：
  • 对于线程生成的 ACP 请求，首先通过移除损坏的 ~/.acpx/config.json 代理覆盖来恢复内置默认值
  • 然后在提供回退之前重试一次
  • 如果用户想要基于二进制文件的覆盖，请精确安装配置的适配器二进制文件
• NO_SESSION：运行 ${ACPX_CMD} <agent> sessions new --name <sessionName>，然后重试提示。
• 队列忙碌：要么等待完成（默认），要么在明确希望异步行为时使用 --no-wait。

输出中继

当向用户中继时，返回 acpx 命令结果的最终助理文本输出。除非用户要求详细日志，否则避免中继原始的本地工具噪音。