ACP agents
Agent Client Protocol (ACP) sessions 讓 OpenClaw 能透過 ACP backend plugin 執行外部編碼 harnesses(例如 Pi、Claude Code、Codex、OpenCode 和 Gemini CLI)。 如果你在 OpenClaw 中以自然語言要求「在 Codex 中執行這個」或「在 thread 中啟動 Claude Code」,OpenClaw 應該將該請求路由到 ACP runtime(而不是原生 sub-agent runtime)。快速運營流程
當你想要實用的/acp 運行手冊時,使用以下方式:
- 產生 session:
/acp spawn codex --mode persistent --thread auto
- 在繫結的 thread 中工作(或明確指定該 session key)。
- 檢查 runtime 狀態:
/acp status
- 視需要調整 runtime 選項:
/acp model <provider/model>/acp permissions <profile>/acp timeout <seconds>
- 在不取代 context 的情況下調整活躍 session:
/acp steer tighten logging and continue
- 停止工作:
/acp cancel(停止目前 turn),或/acp close(關閉 session + 移除繫結)
給人類的快速開始
自然請求的範例:- 「在 thread 中啟動持久 Codex session,並保持聚焦。」
- 「以單次 Claude Code ACP session 執行此操作,並總結結果。」
- 「在 thread 中使用 Gemini CLI 執行此任務,然後在同一 thread 中進行後續操作。」
- 選擇
runtime: "acp"。 - 解析請求的 harness 目標(
agentId,例如codex)。 - 如果要求 thread 繫結且目前頻道支援它,將 ACP session 繫結到 thread。
- 將後續 thread 訊息路由到同一個 ACP session,直到取消聚焦/關閉/過期。
ACP 與 sub-agents
當你想要外部 harness runtime 時使用 ACP。當你想要 OpenClaw 原生委派執行時使用 sub-agents。
另見 Sub-agents。
Thread 繫結的 sessions(通道無關)
當為頻道 adapter 啟用 thread 繫結時,ACP sessions 可以繫結到 threads:- OpenClaw 將 thread 繫結到目標 ACP session。
- 該 thread 中的後續訊息路由到繫結的 ACP session。
- ACP 輸出傳回同一 thread。
- 取消聚焦/關閉/存檔/閒置逾時或最大年齡過期會移除繫結。
acp.enabled=trueacp.dispatch.enabled預設為開啟(設定false暫停 ACP dispatch)- 頻道 adapter ACP thread 產生旗標已啟用(adapter 特定)
- Discord:
channels.discord.threadBindings.spawnAcpSessions=true - Telegram:
channels.telegram.threadBindings.spawnAcpSessions=true
- Discord:
支援 thread 的頻道
- 任何公開 session/thread 繫結能力的頻道 adapter。
- 目前的內建支援:
- Discord threads/channels
- Telegram topics(群組/超級群組和 DM topics 中的論壇主題)
- Plugin 頻道可以透過相同繫結介面新增支援。
通道特定設定
對於非暫時性工作流程,在頂層bindings[] 項目中設定持久 ACP 繫結。
繫結模型
bindings[].type="acp"標記持久 ACP conversation 繫結。bindings[].match識別目標 conversation:- Discord channel 或 thread:
match.channel="discord"+match.peer.id="<channelOrThreadId>" - Telegram 論壇主題:
match.channel="telegram"+match.peer.id="<chatId>:topic:<topicId>"
- Discord channel 或 thread:
bindings[].agentId是擁有的 OpenClaw agent id。- 選擇性 ACP 覆蓋位於
bindings[].acp下:mode(persistent或oneshot)labelcwdbackend
每個 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.backendagents.list[].runtime.acp.modeagents.list[].runtime.acp.cwd
bindings[].acp.*agents.list[].runtime.acp.*- 全域 ACP 預設值(例如
acp.backend)
- OpenClaw 確保在使用前設定的 ACP session 存在。
- 該頻道或主題中的訊息路由到設定的 ACP session。
- 在繫結的 conversations 中,
/new和/reset在原地重設相同的 ACP session key。 - 臨時 runtime 繫結(例如由 thread 聚焦流程建立的)在存在時仍然適用。
啟動 ACP sessions(介面)
從 sessions_spawn
使用 runtime: "acp" 從 agent turn 或工具呼叫啟動 ACP session。
runtime預設為subagent,因此明確為 ACP sessions 設定runtime: "acp"。- 如果省略
agentId,OpenClaw 會在設定時使用acp.defaultAgent。 mode: "session"需要thread: true來保持持久繫結 conversation。
task(必需):傳送給 ACP session 的初始提示。runtime(ACP 必需):必須是"acp"。agentId(選擇性):ACP 目標 harness id。如果設定,回退到acp.defaultAgent。thread(選擇性,預設false):在支援的位置要求 thread 繫結流程。mode(選擇性):run(單次)或session(持久)。- 預設是
run - 如果
thread: true且 mode 省略,OpenClaw 可能根據 runtime 路徑預設為持久行為 mode: "session"需要thread: true
- 預設是
cwd(選擇性):請求的 runtime 工作目錄(由 backend/runtime 原則驗證)。label(選擇性):操作人員面向的標籤,用於 session/banner 文字。resumeSessionId(選擇性):恢復現有 ACP session,而不是建立新的。該 agent 透過session/load重放其對話歷史。需要runtime: "acp"。streamTo(選擇性):"parent"將初始 ACP 執行進度摘要串流回請求者 session 作為系統事件。- 在可用時,接受的回應包括
streamLogPath,指向 session 範圍的 JSONL 日誌(<sessionId>.acp-stream.jsonl),你可以跟蹤完整中繼歷史。
- 在可用時,接受的回應包括
恢復現有 session
使用resumeSessionId 繼續先前的 ACP session,而不是重新開始。該 agent 透過 session/load 重放其對話歷史,因此它會以之前內容的完整 context 繼續。
- 將 Codex session 從你的筆記本電腦遞交到手機 — 告訴你的 agent 從之前的位置繼續
- 繼續你在 CLI 中互動式啟動的編碼 session,現在透過你的 agent 無頭執行
- 拿起被 gateway 重啟或閒置逾時中斷的工作
resumeSessionId需要runtime: "acp"— 如果與 sub-agent runtime 搭配使用會傳回錯誤。resumeSessionId恢復上游 ACP conversation 歷史;thread和mode仍然正常適用於你正在建立的新 OpenClaw session,所以mode: "session"仍然需要thread: true。- 目標 agent 必須支援
session/load(Codex 和 Claude Code 都支援)。 - 如果找不到 session ID,spawn 會失敗並顯示清晰的錯誤 — 不會默默回退到新 session。
運營煙霧測試
在 gateway 部署後,當你想要快速現場檢查 ACP spawn 確實在運作端到端(而不僅僅通過單元測試)時,使用這個。 推薦閘門:- 驗證目標主機上的已部署 gateway 版本/commit。
- 確認已部署的源程式碼包括 ACP 血統接受在
src/gateway/sessions-patch.ts(subagent:*或acp:*sessions)。 - 開啟臨時 ACPX 橋接 session 到即時 agent(例如
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 橋接 session。
- 除非你有意測試 thread 繫結持久 ACP sessions,否則在
mode: "run"上保持此煙霧測試。 - 不要為基本閘門要求
streamTo: "parent"。該路徑取決於請求者/session 能力,是一個單獨的整合檢查。 - 將 thread 繫結
mode: "session"測試作為第二個、更豐富的整合通過,來自真實 Discord thread 或 Telegram topic。
Sandbox 相容性
ACP sessions 目前在主機 runtime 上執行,而不是在 OpenClaw sandbox 內。 目前的限制:- 如果請求者 session 已沙箱化,ACP spawns 會被阻止,無論是針對
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.
- 錯誤:
- 具有
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 來從 chat 進行明確的運營人員控制。
--mode persistent|oneshot--thread auto|here|off--cwd <absolute-path>--label <name>
Session 目標解析
大多數/acp 動作接受選擇性 session 目標(session-key、session-id 或 session-label)。
解析順序:
- 明確目標引數(或
/acp steer的--session)- 嘗試 key
- 然後是 UUID 形狀的 session id
- 然後是 label
- 目前的 thread 繫結(如果此 conversation/thread 繫結到 ACP session)
- 目前的請求者 session 回退
Unable to resolve session target: ...)。
Spawn thread 模式
/acp spawn 支援 --thread auto|here|off。
注意:
- 在非 thread 繫結表面上,預設行為有效地是
off。 - Thread 繫結 spawn 需要頻道原則支援:
- Discord:
channels.discord.threadBindings.spawnAcpSessions=true - Telegram:
channels.telegram.threadBindings.spawnAcpSessions=true
- Discord:
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 傳回清晰的不支援控制錯誤。
ACP 命令手冊
/acp sessions 讀取目前繫結或請求者 session 的儲存。接受 session-key、session-id 或 session-label tokens 的命令透過 gateway session 發現解析目標,包括自訂每 agent session.store 根目錄。
Runtime 選項對映
/acp 有便利命令和通用 setter。
對等操作:
/acp model <id>對映到 runtime config keymodel。/acp permissions <profile>對映到 runtime config keyapproval_policy。/acp timeout <seconds>對映到 runtime config keytimeout。/acp cwd <path>直接更新 runtime cwd 覆蓋。/acp set <key> <value>是通用路徑。- 特殊情況:
key=cwd使用 cwd 覆蓋路徑。
- 特殊情況:
/acp reset-options清除目標 session 的所有 runtime 覆蓋。
acpx harness 支援(目前)
目前 acpx 內建 harness 別名:piclaudecodexopencodegeminikimi
agentId 偏好這些值。
直接 acpx CLI 使用也可以透過 --agent <command> 針對任意 adapters,但該原始逃逸舱口是 acpx CLI 功能(不是正常的 OpenClaw agentId 路徑)。
必需配置
核心 ACP 基線:- Discord:
channels.discord.threadBindings.spawnAcpSessions=true
acpx backend 的 Plugin 設定
安裝並啟用 plugin:acpx 命令和版本配置
預設情況下,acpx plugin(發佈為@openclaw/acpx)使用 plugin 本機固定的二進位檔:
- 命令預設為
extensions/acpx/node_modules/.bin/acpx。 - 預期版本預設為擴充功能 pin。
- 啟動將 ACP backend 立即註冊為尚未就緒。
- 背景確保任務驗證
acpx --version。 - 如果 plugin 本機二進位遺漏或不匹配,它會執行:
npm install --omit=dev --no-save acpx@<pinned>並重新驗證。
command接受絕對路徑、相對路徑或命令名稱(acpx)。- 相對路徑從 OpenClaw 工作區目錄解析。
expectedVersion: "any"禁用嚴格版本比對。- 當
command指向自訂二進位/路徑時,plugin 本機自動安裝會被禁用。 - OpenClaw 啟動在 backend 健康檢查執行期間保持非阻止。
許可權配置
ACP sessions 以非互動方式執行 — 沒有 TTY 來核准或拒絕檔案寫入和 shell exec 許可權提示。acpx plugin 提供兩個控制許可權如何處理的配置鍵:permissionMode
控制 harness agent 可以在不提示情況下執行的操作。
nonInteractivePermissions
控制當許可權提示將被顯示但沒有互動 TTY 可用時會發生什麼(ACP sessions 總是如此)。
配置
透過 plugin 配置設定:重要: OpenClaw 目前預設為permissionMode=approve-reads和nonInteractivePermissions=fail。在非互動 ACP sessions 中,任何觸發許可權提示的寫入或 exec 都可能失敗,並出現AcpRuntimeError: Permission prompt unavailable in non-interactive mode。 如果需要限制許可權,設定nonInteractivePermissions為deny,以便 sessions 優雅地降級,而不是崩潰。