ACP Harness Router

ACP Harness Router 是做什麼的？

當使用者意圖為「在 Claude Code/Cursor/Copilot/OpenClaw/OpenCode/Gemini/Qwen/Kiro/Kimi/iFlow/Droid/Kilocode (ACP harness) 中執行此操作」時，請勿使用子代理執行階段或 PTY 擷取。改為透過 ACP 感知流程進行路由。

Codex 則較特殊：純文字聊天/對話綁定與控制應使用原生的 Codex app-server 插件（/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
• 繼續現有的 harness 工作
• 將指示轉發至外部程式碼 harness
• 以類似執行緒的對話方式維持外部 harness 交談

針對程式碼代理執行緒請求的強制檢查：

• 在為 ACP harness 工作建立任何執行緒之前，請在同一個回合中先閱讀此技能。
• 閱讀後，請遵循下面的「OpenClaw ACP 執行階段路徑」；請勿為 ACP harness 執行緒生成使用 message(action="thread-create")。

模式選擇

選擇以下其中一條路徑：

1. OpenClaw ACP 執行階段路徑（預設）：使用 sessions_spawn / ACP 執行階段工具。
2. 直接 acpx 路徑（傳話遊戲）：透過 exec 使用 acpx CLI 直接驅動 harness 工作階段。

當以下任一條件成立時，使用直接 acpx：

• 使用者明確要求直接 acpx 驅動
• ACP 執行階段/插件路徑不可用或不健康
• 任務僅為「將提示轉發至 harness」且不需要 OpenClaw ACP 生命週期功能

請勿使用：

• subagents 執行階段來控制 harness
• /acp 命令委派作為使用者的需求
• 當 acpx 可用時，對支援的 ACP harness CLI 進行 PTY 擷取

代理 ID 對應

當使用者直接命名 harness 時，使用這些預設值：

• "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 harness 執行緒生成請求，請在同一個回合中呼叫工具之前先閱讀此技能。
2. 使用 sessions_spawn 並設定：
   • runtime: "acp"
   • thread: true
   • mode: "session"（除非使用者明確想要一次性）
3. 對於 ACP harness 執行緒建立，請勿使用帶有 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"
}

執行緒生成復原策略

當使用者要求在執行緒中啟動程式碼 harness 時，將其視為 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 路徑（「傳話遊戲」）

使用此路徑來驅動 harness 工作階段，而不需透過 /acp 或子代理執行階段。

規則

1. 使用呼叫 ${ACPX_CMD} 的 exec 命令。
2. 每次對話重複使用穩定的工作階段名稱，以便後續提示保持在同一個 harness 上下文中。
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 中的 Harness 別名

• 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 命令結果的最終助理文字輸出。除非使用者要求詳細日誌，否則避免轉發原始的本機工具噪音。