Acp Router

ACP Harness 路由器

当用户意图是“在 Pi / Claude Code / Codex / OpenCode / Gemini / Kimi（ACP harness）中运行此操作”时，不得使用 subagent 运行时或 PTY 抓取（PTY scraping），而应通过具备 ACP 意识的流程进行路由。

意图识别（Intent detection）

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

• 在 Pi / Claude Code / Codex / OpenCode / Gemini 中运行某项任务
• 继续已存在的 harness 工作
• 将指令中继至外部编码 harness
• 在类线程（thread-like）对话中维持与外部 harness 的会话

针对 coding-agent 线程请求的强制预检（mandatory preflight）：

• 在为 Pi / Claude / Codex / OpenCode / Gemini 工作创建任何线程前，必须在同一轮次（same turn）中首先阅读本技能文档。
• 阅读完成后，请遵循下方 OpenClaw ACP runtime path；禁止使用 message(action="thread-create") 创建 ACP harness 线程。

模式选择（Mode selection）

请从以下路径中选择其一：

1. OpenClaw ACP 运行时路径（默认）：使用 sessions_spawn 或 ACP 运行时工具。
2. 直连 acpx 路径（“传话游戏”模式）：通过 exec 调用 acpx CLI，直接驱动 harness 会话。

仅在满足以下任一条件时，使用直连 acpx 路径：

• 用户明确要求以直连 acpx 方式驱动
• ACP 运行时／插件路径不可用或处于异常状态
• 当前任务仅为“向 harness 中继 prompt”，且无需任何 OpenClaw ACP 生命周期功能（如 session 管理、状态持久化等）

禁止使用以下方式：

• 使用 subagents 运行时控制 harness
• 强制用户执行 /acp 命令作为前提条件
• 当 acpx 可用时，对 pi / claude / codex / opencode / gemini / kimi 的 CLI 进行 PTY 抓取（PTY scraping）

AgentId 映射（AgentId mapping）

当用户直接指明 harness 名称时，请使用以下默认映射：

• "pi" → agentId: "pi"
• "claude" 或 "claude code" → agentId: "claude"
• "codex" → agentId: "codex"
• "opencode" → agentId: "opencode"
• "gemini" 或 "gemini cli" → agentId: "gemini"
• "kimi" 或 "kimi cli" → agentId: "kimi"

以上默认值与当前 acpx 内置别名一致。

若策略（policy）拒绝所选 agentId，请清晰报告策略错误，并向用户询问允许使用的 ACP agent id。

OpenClaw ACP 运行时路径（OpenClaw ACP runtime path）

必需行为：

1. 对于 ACP harness 线程创建请求，必须在同一轮次中先阅读本技能文档，再调用任何工具。

2. 使用 sessions_spawn，并指定以下参数：

   • runtime: "acp"
   • thread: true
   • mode: "session"（除非用户明确要求 one-shot 模式）
3. 创建 ACP harness 线程时，禁止使用 message 并设置 action=thread-create；sessions_spawn 是唯一合法的线程创建路径。
4. 将用户请求的具体任务内容放入 task 字段，确保 ACP 会话启动后立即接收并执行该任务。
5. 显式设置 agentId，除非已知 ACP 默认 agent 可安全使用。
6. 当本路径可直接满足需求时，不得引导用户手动运行斜杠命令（slash commands）或 CLI。

示例：

用户：“在新线程中启动一个测试 codex 会话，并让它说 hi”

调用：

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

线程创建恢复策略（Thread spawn recovery policy）

当用户请求在线程中启动 coding harness（例如：“启动一个 codex / claude / pi / kimi 线程”），应将其视为 ACP 运行时请求，并尽最大努力端到端完成。

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

1. 不得立即要求用户选择替代路径。

2. 首先尝试自动本地修复（automatic local repair）：

   • 确保插件本地 pinned 版本的 acpx 已安装于 extensions/acpx
   • 验证 ${ACPX_CMD} --version 是否可正常执行
3. 完成重装／修复后，重启 gateway，并主动向用户提供重启操作选项（即明确表示“是否需要我为您执行 gateway 重启？”）。
4. 修复完成后，重试一次 ACP 线程创建。
5. 仅当修复 + 重试均失败时，才报告具体错误详情，并随后提供备用方案。

提供备用方案时，仍须将 ACP 作为首选项：

• 选项 1：展示确切失败步骤后，再次尝试 ACP 创建
• 选项 2：切换至直连 acpx “传话游戏”流程

不得将 subagent 运行时作为此类请求的默认回退路径。

ACPX 安装与版本策略（ACPX install and version policy，直连 acpx 路径）

本仓库中所有直连 acpx 调用，必须遵循与 @openclaw/acpx 插件一致的 pinned 版本策略。

1. 优先使用插件本地二进制文件，而非全局 PATH：

   • ./extensions/acpx/node_modules/.bin/acpx

2. 从插件依赖中解析 pinned 版本号：

   • node -e "console.log(require('./extensions/acpx/package.json').dependencies.acpx)"

3. 若二进制缺失或版本不匹配，则安装插件本地 pinned 版本：

   • cd extensions/acpx && npm install --omit=dev --no-save acpx@

4. 使用前必须验证：

   • ./extensions/acpx/node_modules/.bin/acpx --version
5. 若安装／修复更改了 ACPX 相关产物，需重启 gateway，并主动提供自动重启服务。
6. 禁止执行 npm install -g acpx，除非用户明确要求全局安装。

请统一设置并复用以下环境变量：

ACPX_CMD="./extensions/acpx/node_modules/.bin/acpx"

直连 acpx 路径（“传话游戏”模式）

使用本路径驱动 harness 会话，不依赖 /acp 命令或 subagent 运行时。

规则（Rules）

1. 使用 exec 命令调用 ${ACPX_CMD}。
2. 为每次对话复用稳定的会话名称（session name），确保后续 prompt 始终落在同一 harness 上下文中。
3. 优先使用 --format quiet，以获得干净的助手文本输出，便于中继给用户。
4. 仅当用户明确要求 one-shot 行为时，才使用 exec（一次性执行）。
5. 当任务范围依赖代码仓库上下文（repo context）时，必须显式指定工作目录（--cwd）。

会话命名（Session naming）

使用确定性（deterministic）命名规则，例如：

• oc--

其中 conversationId 优先取 thread id；若不可得，则使用 channel / conversation id。

命令模板（Command templates）

持久会话（存在则复用，不存在则新建，再发送 prompt）：

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

${ACPX_CMD} codex -s oc-codex- --cwd  --format quiet ""

One-shot 执行：

${ACPX_CMD} codex exec --cwd  --format quiet ""

取消当前进行中的回合（in-flight turn）：

${ACPX_CMD} codex cancel -s oc-codex-

关闭会话：

${ACPX_CMD} codex sessions close oc-codex-

acpx 中的 harness 别名（Harness aliases in acpx）

• pi
• claude
• codex
• opencode
• gemini
• kimi

acpx 中的内置适配器命令（Built-in adapter commands in acpx）

默认配置如下：

• pi → npx pi-acp
• claude → npx -y @zed-industries/claude-agent-acp
• codex → npx @zed-industries/codex-acp
• opencode → npx -y opencode-ai acp
• gemini → gemini
• kimi → kimi acp

若 ~/.acpx/config.json 中定义了 agents 字段，则其中的覆盖配置将取代上述默认值。

故障处理（Failure handling）

• acpx: command not found：

  • 对于线程创建类 ACP 请求，立即在 extensions/acpx 中安装插件本地 pinned 版本的 acpx；
  • 安装完成后重启 gateway，并主动提供自动重启服务；
  • 然后重试一次；
  • 不得预先请求用户安装许可（除非策略强制要求）；
  • 禁止安装全局 acpx，除非用户明确要求。

• 适配器命令缺失（例如 claude-agent-acp 未找到）：

  • 对于线程创建类 ACP 请求，首先通过移除损坏的 ~/.acpx/config.json 中 agent 覆盖项，恢复内置默认配置；
  • 然后重试一次，再提供备选方案；
  • 若用户确需基于二进制的自定义覆盖，请精确安装其配置中指定的适配器二进制。

• NO_SESSION 错误：

  • 执行 ${ACPX_CMD} sessions new --name ，然后重试 prompt。

• 队列繁忙（queue busy）：

  • 默认等待任务完成；
  • 若用户明确要求异步行为，则使用 --no-wait 参数。

输出中继（Output relay）

向用户中继输出时，仅返回 acpx 命令结果中最终的助手文本（assistant text）输出。除非用户明确要求详细日志（verbose logs），否则避免中继原始本地工具的杂讯（raw local tool noise）。