ACP 代理 — 設定

如需概觀、操作員手冊和概念，請參閱 ACP 代理程式。

以下章節涵蓋 acpx harness 設定、MCP 橋接的 Plugin 設定，以及權限設定。

只有在設定 ACP/acpx 路由時才使用此頁。若要設定原生 Codex app-server 執行階段，請使用 Codex harness。若要設定 OpenAI API 金鑰或 Codex OAuth 模型提供者設定，請使用 OpenAI。

Codex 有兩種 OpenClaw 路由：

除非你明確需要 ACP/acpx 行為，否則請優先使用原生路由。

acpx harness 支援（目前）

目前 acpx 內建 harness 別名：

• claude
• codex
• copilot
• cursor（Cursor CLI：cursor-agent acp）
• droid
• gemini
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• pi
• qwen

當 OpenClaw 使用 acpx 後端時，除非你的 acpx 設定定義了自訂代理程式別名，否則請優先將這些值用於 agentId。 如果你的本機 Cursor 安裝仍以 agent acp 暴露 ACP，請在你的 acpx 設定中覆寫 cursor 代理程式指令，而不是變更內建預設值。

直接使用 acpx CLI 也可以透過 --agent <command> 指向任意 adapter，但該原始逃生口是 acpx CLI 功能（不是一般 OpenClaw agentId 路徑）。

模型控制取決於 adapter 能力。Codex ACP 模型參照會在啟動前由 OpenClaw 正規化。其他 harness 需要 ACP models 加上 session/set_model 支援；如果某個 harness 既未暴露該 ACP 能力， 也沒有自己的啟動模型旗標，OpenClaw/acpx 就無法強制選擇模型。

必要設定

核心 ACP baseline：

{  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: [      "claude",      "codex",      "copilot",      "cursor",      "droid",      "gemini",      "iflow",      "kilocode",      "kimi",      "kiro",      "openclaw",      "opencode",      "pi",      "qwen",    ],    maxConcurrentSessions: 8,    stream: {      coalesceIdleMs: 300,      maxChunkChars: 1200,    },    runtime: {      ttlMinutes: 120,    },  },}

執行緒繫結設定依 channel adapter 而定。Discord 範例：

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

如果執行緒繫結的 ACP spawn 無法運作，請先驗證 adapter 功能旗標：

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

目前對話繫結不需要建立子執行緒。它們需要作用中的對話情境，以及暴露 ACP 對話繫結的 channel adapter。

請參閱 設定參考。

acpx 後端的 Plugin 設定

封裝安裝會使用官方 @openclaw/acpx 執行階段 Plugin 來支援 ACP。 請先安裝並啟用它，再使用 ACP harness 工作階段：

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

原始碼 checkout 也可以在 pnpm install 後使用本機 workspace Plugin。

從這裡開始：

/acp doctor

如果你停用了 acpx、透過 plugins.allow / plugins.deny 拒絕它，或想要 切回封裝 Plugin，請使用明確的套件路徑：

openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

開發期間的本機 workspace 安裝：

openclaw plugins install ./path/to/local/acpx-plugin

接著驗證後端健康狀態：

/acp doctor

acpx 指令與版本設定

預設情況下，acpx Plugin 會在 Gateway 啟動期間探測嵌入式 ACP 後端， 並在 gateway ready 訊號前等待該探測完成。將 OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 設為跳過啟動探測，並改為延遲註冊 後端。執行 /acp doctor 可進行明確的隨選探測。

在 Plugin 設定中覆寫指令或版本：

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

• command 接受絕對路徑、相對路徑（從 OpenClaw workspace 解析），或指令名稱。
• expectedVersion: "any" 會停用嚴格版本比對。
• 自訂 command 路徑會停用 Plugin 本機自動安裝。

當路徑或旗標值應維持為單一 argv token 時，請使用結構化引數覆寫個別 ACP 代理程式指令：

{  "plugins": {    "entries": {      "acpx": {        "enabled": true,        "config": {          "agents": {            "claude": {              "command": "node",              "args": ["/path/to/custom adapter.mjs", "--verbose"]            }          }        }      }    }  }}

• agents.<id>.command 是該 ACP 代理程式的可執行檔或既有指令字串。
• agents.<id>.args 為選用。每個陣列項目都會先進行 shell quote，OpenClaw 再透過目前的 acpx 指令字串 registry 傳遞它。

請參閱 Plugin。

自動相依性安裝

當你使用 npm install -g openclaw 全域安裝 OpenClaw 時，acpx 執行階段相依性（平台特定二進位檔）會透過 postinstall hook 自動安裝。 如果自動安裝失敗，gateway 仍會正常啟動，並透過 openclaw acp doctor 回報缺少的相依性。

Plugin 工具 MCP 橋接

預設情況下，ACPX 工作階段不會將 OpenClaw Plugin 註冊的工具暴露給 ACP harness。

如果你想讓 Codex 或 Claude Code 等 ACP 代理程式呼叫已安裝的 OpenClaw Plugin 工具，例如記憶回想/儲存，請啟用專用橋接：

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

這會執行以下事項：

• 將名為 openclaw-plugin-tools 的內建 MCP server 注入 ACPX 工作階段 bootstrap。
• 暴露已安裝且已啟用的 OpenClaw Plugin 已註冊的 Plugin 工具。
• 讓此功能保持明確啟用且預設關閉。

安全性與信任注意事項：

• 這會擴大 ACP harness 工具介面。
• ACP 代理程式只能存取 gateway 中已作用的 Plugin 工具。
• 請將此視為與允許那些 Plugin 在 OpenClaw 本身執行相同的信任邊界。
• 啟用前請審查已安裝的 Plugin。

自訂 mcpServers 仍會如同先前運作。內建 Plugin 工具橋接是額外的選擇性便利功能，不是一般 MCP server 設定的替代品。

OpenClaw 工具 MCP 橋接

預設情況下，ACPX 工作階段也不會透過 MCP 暴露內建 OpenClaw 工具。 當 ACP 代理程式需要選定的內建工具（例如 cron）時，請啟用獨立的核心工具橋接：

openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true

這會執行以下事項：

• 將名為 openclaw-tools 的內建 MCP server 注入 ACPX 工作階段 bootstrap。
• 暴露選定的內建 OpenClaw 工具。初始 server 暴露 cron。
• 讓核心工具暴露保持明確啟用且預設關閉。

執行階段逾時設定

acpx Plugin 預設將嵌入式執行階段 turn 設為 120 秒 逾時。這讓 Gemini CLI 等較慢的 harness 有足夠時間完成 ACP 啟動和初始化。如果你的主機需要不同的執行階段限制，請覆寫它：

openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

變更此值後請重新啟動 gateway。

健康探測代理程式設定

當 /acp doctor 或啟動探測檢查後端時，隨附的 acpx Plugin 會探測一個 harness 代理程式。如果已設定 acp.allowedAgents，它預設使用 第一個允許的代理程式；否則預設使用 codex。如果你的部署需要不同的 ACP 代理程式來執行健康檢查，請明確設定探測代理程式：

openclaw config set plugins.entries.acpx.config.probeAgent claude

變更此值後請重新啟動 gateway。

權限設定

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

這些 ACPX harness 權限與 OpenClaw exec 核准分開，也與 CLI 後端供應商旁路旗標（例如 Claude CLI --permission-mode bypassPermissions）分開。ACPX approve-all 是 ACP 工作階段在 harness 層級的 break-glass 開關。

permissionMode

控制 harness 代理程式可在不提示的情況下執行哪些操作。

nonInteractivePermissions

控制當權限提示原本會顯示，但沒有可用互動式 TTY 時會發生什麼事（ACP 工作階段一律如此）。

設定

透過 Plugin 設定：

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

變更這些值後請重新啟動 gateway。

相關

• ACP 代理程式 — 概觀、操作員手冊、概念
• 子代理程式
• 多代理程式路由