ACP 代理

Agent Client Protocol (ACP) 讓 OpenClaw 可以透過 ACP 後端外掛來執行外部編程工具（例如 Pi、Claude Code、Codex、OpenCode、Gemini CLI）。

你可以用自然語言告訴 OpenClaw「用 Codex 跑這個」或「在討論串中啟動 Claude Code」，OpenClaw 會自動將請求導向 ACP 執行環境（而非原生子代理執行環境）。

快速操作流程

需要一份實用的 /acp 操作手冊時，按以下步驟進行：

1. 建立工作階段：
   • /acp spawn codex --mode persistent --thread auto
2. 在綁定的討論串中工作（或明確指定該工作階段的 key）。
3. 查看執行狀態：
   • /acp status
4. 視需要調整執行參數：
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
5. 在不替換上下文的情況下微調進行中的工作階段：
   • /acp steer tighten logging and continue
6. 停止工作：
   • /acp cancel（中止目前回合），或
   • /acp close（關閉工作階段並移除綁定）

快速上手

自然語言請求範例：

• 「在這裡的討論串中開一個持續性的 Codex 工作階段，讓它保持專注。」
• 「用一次性的 Claude Code ACP 工作階段跑這個，完成後摘要結果。」
• 「用 Gemini CLI 在討論串中處理這個任務，後續的對話也在同一個串裡進行。」

OpenClaw 的處理邏輯：

1. 選擇 runtime: "acp"。
2. 解析請求的目標工具（agentId，例如 codex）。
3. 如果要求綁定討論串，且目前的頻道支援，就將 ACP 工作階段綁定到該討論串。
4. 後續在該討論串中的訊息會持續導向同一個 ACP 工作階段，直到解除焦點 / 關閉 / 過期為止。

ACP 與子代理的差異

需要外部工具執行環境時用 ACP；需要 OpenClaw 原生委派執行時用子代理。

另請參閱 子代理。

討論串綁定工作階段（不限頻道類型）

頻道轉接器啟用討論串綁定後，ACP 工作階段即可與討論串綁定：

• OpenClaw 將討論串綁定到目標 ACP 工作階段。
• 該討論串中的後續訊息會導向綁定的 ACP 工作階段。
• ACP 的輸出會回傳至同一個討論串。
• 解除焦點 / 關閉 / 封存 / 閒置逾時或達到最大存續時間時，綁定會自動移除。

討論串綁定支援因轉接器而異。如果目前的頻道轉接器不支援討論串綁定，OpenClaw 會回傳一則明確的不支援訊息。

啟用討論串綁定 ACP 所需的功能旗標：

• acp.enabled=true
• acp.dispatch.enabled 預設為啟用（設為 false 可暫停 ACP 分派）
• 頻道轉接器的 ACP 討論串啟動旗標已啟用（依轉接器而定）
  • Discord：channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram：channels.telegram.threadBindings.spawnAcpSessions=true

支援討論串的頻道

• 任何公開工作階段 / 討論串綁定功能的頻道轉接器。
• 目前內建支援：
  • Discord 討論串 / 頻道
  • Telegram 主題（群組 / 超級群組中的論壇主題，以及私訊主題）
• 外掛頻道可透過相同的綁定介面新增支援。

頻道專屬設定

對於非臨時性的工作流程，可在頂層 bindings[] 設定持久性 ACP 綁定。

綁定模型

• bindings[].type="acp" 標記為持久性 ACP 對話綁定。
• bindings[].match 用來辨識目標對話：
  • Discord 頻道或討論串：match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Telegram 論壇主題：match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
• bindings[].agentId 是所屬的 OpenClaw 代理 id。
• 可選的 ACP 覆寫設定放在 bindings[].acp 底下：
  • mode（persistent 或 oneshot）
  • label
  • cwd
  • backend

每個代理的執行環境預設值

使用 agents.list[].runtime 為每個代理定義一次 ACP 預設值：

• agents.list[].runtime.type="acp"
• agents.list[].runtime.acp.agent（工具 id，例如 codex 或 claude）
• agents.list[].runtime.acp.backend
• agents.list[].runtime.acp.mode
• agents.list[].runtime.acp.cwd

ACP 綁定工作階段的覆寫優先順序：

1. bindings[].acp.*
2. agents.list[].runtime.acp.*
3. 全域 ACP 預設值（例如 acp.backend）

範例：

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
      {
        id: "claude",
        runtime: {
          type: "acp",
          acp: { agent: "claude", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
    {
      type: "acp",
      agentId: "claude",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
      acp: { cwd: "/workspace/repo-b" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "discord", accountId: "default" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "telegram", accountId: "default" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": { requireMention: false },
          },
        },
      },
    },
    telegram: {
      groups: {
        "-1001234567890": {
          topics: { "42": { requireMention: false } },
        },
      },
    },
  },
}

行為說明：

• OpenClaw 會在使用前確認設定的 ACP 工作階段已存在。
• 該頻道或主題中的訊息會導向設定的 ACP 工作階段。
• 在綁定的對話中，/new 和 /reset 會就地重設同一個 ACP 工作階段 key。
• 臨時性的執行環境綁定（例如由討論串焦點流程建立的）仍會在有效時套用。

啟動 ACP 工作階段（介面方式）

透過 sessions_spawn

使用 runtime: "acp" 從代理回合或工具呼叫啟動 ACP 工作階段。

{
  "task": "Open the repo and summarize failing tests",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

注意事項：

• runtime 預設為 subagent，因此 ACP 工作階段必須明確設定 runtime: "acp"。
• 省略 agentId 時，OpenClaw 會使用已設定的 acp.defaultAgent。
• mode: "session" 需搭配 thread: true 才能維持持續性的綁定對話。

介面詳細參數：

• task（必填）：傳送給 ACP 工作階段的初始提示。
• runtime（ACP 必填）：必須為 "acp"。
• agentId（選填）：ACP 目標工具 id。若有設定 acp.defaultAgent 則會作為後備。
• thread（選填，預設 false）：在支援的環境中啟用討論串綁定流程。
• mode（選填）：run（一次性）或 session（持續性）。
  • 預設為 run
  • 若 thread: true 且未指定 mode，OpenClaw 可能會根據執行路徑預設為持續性行為
  • mode: "session" 需搭配 thread: true
• cwd（選填）：指定的執行工作目錄（由後端 / 執行環境策略驗證）。
• label（選填）：操作人員可見的標籤，用於工作階段 / 橫幅文字。
• resumeSessionId（選填）：恢復既有 ACP 工作階段而非建立新的。代理會透過 session/load 重播對話紀錄。需搭配 runtime: "acp"。
• streamTo（選填）："parent" 會將 ACP 初始執行進度摘要以系統事件串流回請求端工作階段。
  • 可用時，回應會包含 streamLogPath，指向以工作階段為範圍的 JSONL 日誌（<sessionId>.acp-stream.jsonl），可透過 tail 查看完整的轉發紀錄。

恢復既有工作階段

使用 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" —— 若搭配子代理執行環境使用會回傳錯誤。
• resumeSessionId 會還原上游 ACP 對話紀錄；thread 和 mode 仍照常套用到你正在建立的新 OpenClaw 工作階段，因此 mode: "session" 仍需搭配 thread: true。
• 目標代理必須支援 session/load（Codex 和 Claude Code 都有支援）。
• 若找不到該工作階段 ID，啟動會明確報錯 —— 不會靜默降級為新工作階段。

操作驗證測試

在 Gateway 部署後想快速確認 ACP 啟動功能是否端對端正常運作（而不只是通過單元測試）時使用。

建議步驟：

1. 確認目標主機上部署的 Gateway 版本 / commit。
2. 確認部署的原始碼包含 src/gateway/sessions-patch.ts 中的 ACP 血統驗收邏輯（subagent:* or acp:* sessions）。
3. 對即時代理（例如 jpclawhq 上的 razor(main)）開啟一個臨時 ACPX 橋接工作階段。
4. 請該代理呼叫 sessions_spawn，參數如下：
   • runtime: "acp"
   • agentId: "codex"
   • mode: "run"
   • task：Reply with exactly LIVE-ACP-SPAWN-OK
5. 確認代理回報：
   • accepted=yes
   • 真實的 childSessionKey
   • 無驗證錯誤
6. 清理臨時 ACPX 橋接工作階段。

給即時代理的提示範例：

Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
Set the task to: "Reply with exactly LIVE-ACP-SPAWN-OK".
Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exact text or none>.

注意事項：

• 除非刻意測試討論串綁定的持續性 ACP 工作階段，否則此驗證測試請使用 mode: "run"。
• 基本驗證不需要 streamTo: "parent"。該路徑依賴請求端 / 工作階段的能力，屬於獨立的整合檢查。
• 將討論串綁定的 mode: "session" 測試視為第二階段、更完整的整合測試，從真實的 Discord 討論串或 Telegram 主題進行。

沙箱相容性

ACP 工作階段目前執行在主機的執行環境上，而非 OpenClaw 沙箱內部。

目前的限制：

• 如果請求端工作階段已沙箱化，ACP 啟動會被阻擋，包括 sessions_spawn({ runtime: "acp" }) 和 /acp spawn。
  • 錯誤訊息：Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.
• sessions_spawn 搭配 runtime: "acp" 不支援 sandbox: "require"。
  • 錯誤訊息：sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".

需要沙箱內執行時，請改用 runtime: "subagent"。

透過 /acp 指令

需要在聊天中進行明確的操作控制時，使用 /acp spawn。

/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --thread here

主要旗標：

• --mode persistent|oneshot
• --thread auto|here|off
• --cwd <absolute-path>
• --label <name>

請參閱 斜線指令。

工作階段目標解析

大多數 /acp 操作接受一個可選的工作階段目標（session-key、session-id 或 session-label）。

解析順序：

1. 明確的目標參數（或 /acp steer 的 --session）
   • 先嘗試 key
   • 再嘗試 UUID 格式的 session id
   • 最後嘗試 label
2. 目前討論串綁定（如果目前的對話 / 討論串已綁定到 ACP 工作階段）
3. 以目前請求端的工作階段作為後備

如果沒有任何目標能解析，OpenClaw 會回傳明確的錯誤訊息（Unable to resolve session target: ...）。

啟動討論串模式

/acp spawn 支援 --thread auto|here|off。

注意事項：

• 在不支援討論串綁定的介面上，預設行為等同於 off。
• 討論串綁定啟動需要頻道策略支援：
  • Discord：channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram：channels.telegram.threadBindings.spawnAcpSessions=true

ACP 控制指令

可用的指令家族：

• /acp spawn
• /acp cancel
• /acp steer
• /acp close
• /acp status
• /acp set-mode
• /acp set
• /acp cwd
• /acp permissions
• /acp timeout
• /acp model
• /acp reset-options
• /acp sessions
• /acp doctor
• /acp install

/acp status 會顯示有效的執行選項，以及在可用時同時顯示執行環境層級和後端層級的工作階段識別碼。

部分控制指令取決於後端的能力。如果後端不支援某個控制指令，OpenClaw 會回傳明確的不支援錯誤。

ACP 指令速查表

/acp sessions 會讀取目前綁定或請求端工作階段的儲存區。接受 session-key、session-id 或 session-label 的指令會透過 Gateway 工作階段探索來解析目標，包括每個代理自訂的 session.store 根目錄。

執行選項對應關係

/acp 提供便捷指令和通用設定器。

等效操作：

• /acp model <id> 對應執行設定 key model。
• /acp permissions <profile> 對應執行設定 key approval_policy。
• /acp timeout <seconds> 對應執行設定 key timeout。
• /acp cwd <path> 直接更新執行 cwd 覆寫。
• /acp set <key> <value> 是通用路徑。
  • 特殊情況：key=cwd 使用 cwd 覆寫路徑。
• /acp reset-options 清除目標工作階段的所有執行覆寫。

acpx 工具支援（目前）

目前 acpx 內建的工具別名：

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

當 OpenClaw 使用 acpx 後端時，除非你的 acpx 設定中定義了自訂代理別名，否則建議使用這些值作為 agentId。

透過 acpx CLI 也可以用 --agent <command> 直接指定任意轉接器，但那是 acpx CLI 的原始逃逸機制（不是 OpenClaw 常規的 agentId 路徑）。

必要設定

ACP 基本設定：

{
  acp: {
    enabled: true,
    // 選填。預設為 true；設為 false 可暫停 ACP 分派但保留 /acp 控制指令。
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: ["pi", "claude", "codex", "opencode", "gemini", "kimi"],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

討論串綁定設定因頻道轉接器而異。Discord 範例：

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}

如果討論串綁定 ACP 啟動不起作用，請先檢查轉接器的功能旗標：

• Discord：channels.discord.threadBindings.spawnAcpSessions=true

請參閱 設定參考。

acpx 後端的外掛設定

安裝並啟用外掛：

openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true

開發期間的本地工作區安裝：

openclaw plugins install ./extensions/acpx

然後驗證後端健康狀態：

/acp doctor

acpx 指令與版本設定

預設情況下，acpx 外掛（以 @openclaw/acpx 發布）使用外掛本地固定的二進位檔：

1. 指令預設為 extensions/acpx/node_modules/.bin/acpx。
2. 預期版本預設為擴充套件的固定版本。
3. 啟動時立即將 ACP 後端註冊為未就緒狀態。
4. 背景確認任務會驗證 acpx --version。
5. 如果外掛本地的二進位檔遺失或版本不符，會執行： npm install --omit=dev --no-save acpx@<pinned> 然後重新驗證。

可以在外掛設定中覆寫指令 / 版本：

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}

注意事項：

• command 接受絕對路徑、相對路徑或指令名稱（acpx）。
• 相對路徑從 OpenClaw 工作區目錄解析。
• expectedVersion: "any" 停用嚴格版本比對。
• 當 command 指向自訂二進位檔 / 路徑時，外掛本地的自動安裝會停用。
• 後端健康檢查執行期間，OpenClaw 的啟動不會被阻塞。

請參閱 外掛。

權限設定

ACP 工作階段以非互動方式執行 —— 沒有 TTY 可以核准或拒絕檔案寫入和 shell 執行的權限提示。acpx 外掛提供兩個設定值來控制權限的處理方式：

permissionMode

控制代理工具可以在不提示的情況下執行哪些操作。

nonInteractivePermissions

控制當需要顯示權限提示但沒有互動式 TTY 可用時的行為（ACP 工作階段一律如此）。

設定方式

透過外掛設定：

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

更改這些值後需重新啟動 Gateway。

重要： OpenClaw 目前預設為 permissionMode=approve-reads 和 nonInteractivePermissions=fail。在非互動式的 ACP 工作階段中，任何觸發權限提示的寫入或執行操作都可能以 AcpRuntimeError: Permission prompt unavailable in non-interactive mode 失敗。

如果需要限制權限，請將 nonInteractivePermissions 設為 deny，讓工作階段能優雅降級而不是直接崩潰。

疑難排解