透過 OpenClaw 整合 ACP：5 分鐘內串接外部編碼工具

快速操作流程

當你需要一份實用的 /acp 操作手冊時，可以參考這裡：

啟動會話：
- /acp spawn codex --mode persistent --thread auto
在綁定的線程中工作（或明確指定該會話金鑰）。
檢查運行狀態：
- /acp status
根據需要調整運行選項：
- /acp model <provider/model>
- /acp permissions <profile>
- /acp timeout <seconds>
在不替換上下文的情況下微調活動中的會話：
- /acp steer tighten logging and continue
停止工作：
- /acp cancel（停止當前輪次），或
- /acp close（關閉會話並移除綁定）

給人類的快速上手指南

自然語言請求的範例：

「在這裡的線程中啟動一個持久的 Codex 會話，並讓它保持專注。」
「將此作為一次性的 Claude Code ACP 會話運行並總結結果。」
「針對此任務在線程中使用 Gemini CLI，然後在同一個線程中進行後續跟進。」

OpenClaw 應該執行的操作：

選擇 runtime: "acp"。
解析請求的 harness 目標（agentId，例如 codex）。
如果請求了線程綁定，且當前頻道支援，則將 ACP 會話綁定到該線程。
將後續的線程訊息路由到同一個 ACP 會話，直到取消關注、關閉或過期。

ACP 與 sub-agents 的區別

當你需要外部 harness 運行環境時，請使用 ACP。當你想要 OpenClaw 原生的委託執行時，請使用 sub-agents。

領域	ACP 會話	Sub-agent 執行
Runtime	ACP backend plugin (例如 acpx)	OpenClaw native sub-agent runtime
Session key	`agent:<agentId>:acp:<uuid>`	`agent:<agentId>:subagent:<uuid>`
主要指令	`/acp ...`	`/subagents ...`
啟動工具	`sessions_spawn` 搭配 `runtime:"acp"`	`sessions_spawn` (預設 runtime)

另請參閱 Sub-agents。

線程綁定會話（與頻道無關）

當頻道適配器（channel adapter）啟用了線程綁定功能時，ACP 會話可以綁定到線程：

OpenClaw 將線程綁定到目標 ACP 會話。
該線程中的後續訊息會路由到綁定的 ACP 會話。
ACP 的輸出會傳回到同一個線程中。
取消關注、關閉、封存、閒置超時或達到最大時長限制後，綁定會被移除。

線程綁定支援取決於具體的適配器。如果當前使用的頻道適配器不支援線程綁定，OpenClaw 會回傳明確的不支援或不可用訊息。

線程綁定 ACP 所需的 feature flags：

acp.enabled=true
acp.dispatch.enabled 預設為開啟（設置為 false 可暫停 ACP 調度）
頻道適配器的 ACP 線程啟動標記已啟用（視適配器而定）
- Discord: channels.discord.threadBindings.spawnAcpSessions=true
- Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

支援線程的頻道

任何提供會話或線程綁定能力的頻道適配器。
目前內建支援：
- Discord 線程與頻道
- Telegram 主題（群組/超級群組中的論壇主題以及 DM 主題）
Plugin 頻道可以透過相同的綁定介面增加支援。

頻道特定設定

對於非臨時性的工作流，你可以在頂層的 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 agent id。
選填的 ACP 覆蓋設定位於 bindings[].acp 下：
- mode (persistent 或 oneshot)
- label
- cwd
- backend

每個 Agent 的 Runtime 預設值

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

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

ACP 綁定會話的覆蓋優先順序：

bindings[].acp.*
agents.list[].runtime.acp.*
全域 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 會話金鑰。
臨時的 Runtime 綁定（例如由討論串聚焦流建立的）在存在時仍然適用。

啟動 ACP 會話（介面）

透過 `sessions_spawn`

使用 runtime: "acp" 從 Agent 輪次或工具調用中啟動 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 目標 harness id。如果已設定，則回退到 acp.defaultAgent。
thread（選填，預設為 false）：在支援的情況下請求討論串綁定流。
mode（選填）：run（一次性）或 session（持久）。
- 預設為 run
- 如果 thread: true 且省略 mode，OpenClaw 可能會根據 runtime 路徑預設為持久行為
- mode: "session" 需要 thread: true
cwd（選填）：請求的 runtime 工作目錄（由 backend/runtime 策略驗證）。
label（選填）：用於會話/橫幅文字的維運人員面向標籤。
resumeSessionId（選填）：恢復現有的 ACP 會話而不是建立新會話。Agent 會透過 session/load 重播其對話歷史。需要 runtime: "acp"。
streamTo（選填）："parent" 會將初始 ACP 運行的進度摘要作為系統事件串流回請求者會話。
- 當可用時，接受的響應包括指向會話範圍 JSONL 日誌（<sessionId>.acp-stream.jsonl）的 streamLogPath，你可以追蹤該日誌以獲取完整的轉發歷史。

恢復現有會話

使用 resumeSessionId 繼續之前的 ACP 會話，而不是重新開始。Agent 會透過 session/load 重播其對話歷史，因此它會帶著之前的完整上下文繼續。

{
  "task": "Continue where we left off — fix the remaining test failures",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

常見使用場景：

將 Codex 會話從筆記型電腦移交到手機 —— 告訴你的 Agent 從你離開的地方繼續
繼續你在 CLI 中以互動方式開始的編碼會話，現在透過你的 Agent 以無頭模式進行
接手因 Gateway 重啟或閒置逾時而中斷的工作

注意：

resumeSessionId 需要 runtime: "acp" —— 如果與 sub-agent runtime 一起使用會返回錯誤。
resumeSessionId 會恢復上游 ACP 對話歷史；thread 和 mode 仍然正常適用於你正在建立的新 OpenClaw 會話，因此 mode: "session" 仍然需要 thread: true。
目標 Agent 必須支援 session/load（Codex 和 Claude Code 支援）。
如果找不到會話 ID，spawn 會失敗並顯示明確的錯誤 —— 不會靜默回退到新會話。

維運人員冒煙測試

當你想要快速現場檢查 ACP spawn 是否真的端到端工作（而不僅僅是通過單元測試）時，請在 Gateway 部署後使用此測試。

推薦步驟：

驗證目標主機上部署的 Gateway 版本/提交。
確認部署的原始碼包含 src/gateway/sessions-patch.ts 中的 ACP 譜系驗收（subagent:* or acp:* sessions）。
開啟一個到活動 Agent 的臨時 ACPX 橋接會話（例如 jpclawhq 上的 razor(main)）。
要求該 Agent 調用 sessions_spawn 並帶上：
- runtime: "acp"
- agentId: "codex"
- mode: "run"
- task: Reply with exactly LIVE-ACP-SPAWN-OK
驗證 Agent 報告：
- accepted=yes
- 一個真實的 childSessionKey
- 沒有驗證器錯誤
清理臨時 ACPX 橋接會話。

給活動 Agent 的範例提示詞：

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 主題的第二次、更豐富的整合測試。

Sandbox 相容性

ACP 會話目前在主機 runtime 上運行，而不是在 OpenClaw Sandbox 內。

目前的限制：

如果請求者會話是被沙盒化的（sandboxed），則 sessions_spawn({ runtime: "acp" }) 和 /acp spawn 的 ACP spawn 都會被阻擋。
- 錯誤：Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.
帶有 runtime: "acp" 的 sessions_spawn 不支援 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

關鍵 flags：

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

參見 Slash Commands。

會話目標解析

大多數 /acp 動作都接受一個選填的會話目標（session-key、session-id 或 session-label）。

解析順序：

明確的目標參數（或 /acp steer 的 --session）
- 先嘗試 key
- 然後是 UUID 格式的 session id
- 最後是 label
當前討論串綁定（如果此對話/討論串已綁定到某個 ACP 會話）
當前請求者會話回退

如果無法解析任何目標，OpenClaw 會返回明確的錯誤（Unable to resolve session target: ...）。

Spawn 執行緒模式

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

模式	行為
`auto`	在活躍的執行緒中：綁定該執行緒。在執行緒外：在支援的情況下建立/綁定子執行緒。
`here`	要求目前的活躍執行緒；如果不在執行緒中則失敗。
`off`	不進行綁定。Session 開始時處於未綁定狀態。

注意：

在不支援執行緒綁定的介面上，預設行為實際上就是 off。
執行緒綁定的 spawn 需要頻道政策支援：
- 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 會顯示有效的 runtime 選項，並在可用時同時顯示 runtime 層級與 backend 層級的 session 識別碼。

部分控制功能取決於 backend 的能力。如果 backend 不支援某項控制，OpenClaw 會回傳明確的 unsupported-control 錯誤。

ACP 指令大全

指令	功能說明	範例
`/acp spawn`	建立 ACP session；可選擇是否綁定 thread。	`/acp spawn codex --mode persistent --thread auto --cwd /repo`
`/acp cancel`	取消目標 session 正在進行中的回合。	`/acp cancel agent:codex:acp:<uuid>`
`/acp steer`	向執行中的 session 發送引導指令。	`/acp steer --session support inbox prioritize failing tests`
`/acp close`	關閉 session 並解除 thread 綁定。	`/acp close`
`/acp status`	顯示 backend, mode, state, runtime 選項與能力。	`/acp status`
`/acp set-mode`	設定目標 session 的 runtime 模式。	`/acp set-mode plan`
`/acp set`	通用的 runtime 配置選項寫入。	`/acp set model openai/gpt-5.2`
`/acp cwd`	設定 runtime 工作目錄覆寫。	`/acp cwd /Users/user/Projects/repo`
`/acp permissions`	設定審核策略設定檔。	`/acp permissions strict`
`/acp timeout`	設定 runtime 超時時間（秒）。	`/acp timeout 120`
`/acp model`	設定 runtime 模型覆寫。	`/acp model anthropic/claude-opus-4-5`
`/acp reset-options`	移除 session 的 runtime 選項覆寫。	`/acp reset-options`
`/acp sessions`	列出儲存庫中最近的 ACP session。	`/acp sessions`
`/acp doctor`	backend 健康狀況、能力以及可執行的修復建議。	`/acp doctor`
`/acp install`	印出確定的安裝與啟用步驟。	`/acp install`

Runtime 選項映射

/acp 提供了便捷指令和通用的 setter。

等效操作如下：

/acp model <id> 對應到 runtime 配置 key model。
/acp permissions <profile> 對應到 runtime 配置 key approval_policy。
/acp timeout <seconds> 對應到 runtime 配置 key timeout。
/acp cwd <path> 直接更新 runtime 的 cwd 覆寫。
/acp set <key> <value> 是通用路徑。
- 特殊情況：key=cwd 會使用 cwd 覆寫路徑。
/acp reset-options 會清除目標 session 的所有 runtime 覆寫。

acpx harness 支援情況 (目前)

目前 acpx 內建的 harness 別名有：

pi
claude
codex
opencode
gemini
kimi

當 OpenClaw 使用 acpx backend 時，除非你的 acpx 設定有定義自訂的 agent 別名，否則建議優先使用這些值作為 agentId。

直接使用 acpx CLI 也可以透過 --agent <command> 來指向任何 adapter，但那是 acpx CLI 的原生功能，不屬於一般的 OpenClaw agentId 路徑。

必要配置

核心 ACP 基準設定：

{
  acp: {
    enabled: true,
    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: ["pi", "claude", "codex", "opencode", "gemini", "kimi"],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

Thread binding 設定會根據 channel-adapter 而有所不同。以 Discord 為例：

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

如果 thread-bound ACP 啟動失敗，請先檢查 adapter 的 feature flag：

Discord: channels.discord.threadBindings.spawnAcpSessions=true

參考 Configuration Reference。

acpx 後端 Plugin 設定

安裝並啟用 plugin：

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

開發期間的 Local workspace 安裝：

openclaw plugins install ./extensions/acpx

接著驗證後端狀態：

/acp doctor

acpx 指令與版本配置

預設情況下，acpx plugin（以 @openclaw/acpx 發佈）會使用 plugin 本地鎖定的 binary：

指令預設為 extensions/acpx/node_modules/.bin/acpx。
預期版本預設為 extension 鎖定的版本。
啟動時會立即將 ACP 後端註冊為未就緒（not-ready）。
背景任務會執行 acpx --version 進行驗證。
如果缺少本地 binary 或版本不符，會執行：npm install --omit=dev --no-save acpx@<pinned> 並重新驗證。

你可以在 plugin 設定中覆蓋指令或版本：

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

備註：

command 接受絕對路徑、相對路徑或指令名稱（acpx）。
相對路徑會從 OpenClaw workspace 目錄開始解析。
expectedVersion: "any" 會停用嚴格的版本比對。
當 command 指向自定義的 binary 或路徑時，plugin 本地的自動安裝功能會被停用。
在後端狀態檢查執行時，OpenClaw 的啟動過程不會被阻塞。

參考 Plugins。

權限配置

ACP session 是以非互動（non-interactively）方式執行的 —— 這代表沒有 TTY 可以讓你手動同意或拒絕檔案寫入與 shell 執行權限的提示。acpx plugin 提供兩個設定項來控制權限的處理方式：

`permissionMode`

控制 harness agent 在不詢問的情況下可以執行哪些操作。

數值	行為
`approve-all`	自動同意所有檔案寫入與 shell 指令。
`approve-reads`	僅自動同意讀取；寫入與執行（exec）需要權限提示。
`deny-all`	拒絕所有權限提示。

`nonInteractivePermissions`

控制當需要顯示權限提示，但沒有互動式 TTY 可用時（ACP session 總是如此）該如何處理。

數值	行為
`fail`	中止 session 並拋出 `AcpRuntimeError`。(預設值)
`deny`	靜默拒絕該權限並繼續執行（優雅降級）。

設定方式

透過 plugin 設定進行配置：

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 session 中，任何觸發權限提示的寫入或執行操作都可能導致失敗，並出現 AcpRuntimeError: Permission prompt unavailable in non-interactive mode。

如果你需要限制權限，請將 nonInteractivePermissions 設定為 deny，這樣 session 會以功能降級的方式繼續運作，而不會直接崩潰。

疑難排解

症狀	可能原因	修正方法
`ACP runtime backend is not configured`	後端 plugin 遺失或未啟用。	安裝並啟用後端 plugin，然後執行 `/acp doctor`。
`ACP is disabled by policy (acp.enabled=false)`	ACP 被全域停用。	將 `acp.enabled` 設定為 `true`。
`ACP dispatch is disabled by policy (acp.dispatch.enabled=false)`	來自一般 thread 訊息的 dispatch 功能被停用。	將 `acp.dispatch.enabled` 設定為 `true`。
`ACP agent "<id>" is not allowed by policy`	Agent 不在允許清單中。	使用被允許的 `agentId` 或更新 `acp.allowedAgents`。
`Unable to resolve session target: ...`	錯誤的 key/id/label token。	執行 `/acp sessions`，複製正確的 key/label 後重試。
`--thread here requires running /acp spawn inside an active ... thread`	在 thread 上下文之外使用了 `--thread here`。	移動到目標 thread 或使用 `--thread auto`/`off`。
`Only <user-id> can rebind this thread.`	另一個使用者擁有該 thread 的綁定權限。	以擁有者身份重新綁定，或使用不同的 thread。
`Thread bindings are unavailable for <channel>.`	Adapter 缺乏 thread 綁定能力。	使用 `--thread off` 或移動到支援的 adapter/channel。
`Sandboxed sessions cannot spawn ACP sessions ...`	ACP runtime 位於 host 端；請求者的 session 處於 sandbox 中。	從沙盒 session 使用 `runtime="subagent"`，或從非沙盒 session 執行 ACP spawn。
`sessions_spawn sandbox="require" is unsupported for runtime="acp" ...`	對 ACP runtime 請求了 `sandbox="require"`。	若需要沙盒化請使用 `runtime="subagent"`，或在非沙盒 session 中搭配 `sandbox="inherit"` 使用 ACP。
遺失已綁定 session 的 ACP metadata	ACP session metadata 已過期或被刪除。	使用 `/acp spawn` 重新建立，然後重新綁定/聚焦 thread。
`AcpRuntimeError: Permission prompt unavailable in non-interactive mode`	`permissionMode` 阻擋了非互動式 ACP session 中的寫入/執行。	將 `plugins.entries.acpx.config.permissionMode` 設定為 `approve-all` 並重啟 Gateway。請參閱權限配置。
ACP session 太早結束且幾乎沒有輸出	權限提示被 `permissionMode`/`nonInteractivePermissions` 阻擋。	檢查 Gateway 記錄是否有 `AcpRuntimeError`。若要完整權限，請設定 `permissionMode=approve-all`；若要優雅降級，請設定 `nonInteractivePermissions=deny`。
ACP session 在完成工作後無限期停滯	Harness 程序已結束，但 ACP session 未回報完成。	使用 `ps aux \| grep acpx` 進行監控；手動刪除殘留程序。

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。