ACP 代理程式 — 設定

如需概覽、操作手冊與概念說明，請參閱 ACP 代理程式。

本頁涵蓋 acpx 執行框架設定、MCP 橋接器的外掛設定，以及權限設定。

僅在設定 ACP/acpx 路徑時使用本頁。若要設定原生 Codex app-server 執行階段，請參閱 Codex 執行框架。若要設定 OpenAI API 金鑰或 Codex OAuth 模型供應商，請參閱 OpenAI。

Codex 有兩種 OpenClaw 路徑：

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

acpx 執行框架支援（目前）

內建 acpx 執行框架別名（來自鎖定版本的 acpx 相依套件）：

factory-droid 和 factorydroid 也會解析為內建的 droid 轉接器。

OpenClaw 使用 acpx 後端時，除非 acpx 設定定義了自訂代理程式別名，否則請優先對 agentId 使用這些值。 如果本機 Cursor 安裝仍將 ACP 公開為 agent acp，請在 acpx 設定中覆寫 cursor 代理程式命令，而不要變更內建預設值。

直接使用 acpx 命令列介面時，也可透過 --agent <command> 指定任意轉接器，但這個原始的逃生出口是 acpx 命令列介面功能（並非一般的 OpenClaw agentId 路徑）。

模型控制取決於轉接器能力。Codex ACP 模型參照會在啟動前由 OpenClaw 正規化。其他執行框架需要 ACP models 加上 session/set_model 支援；如果執行框架既未公開該 ACP 能力，也沒有 自己的啟動模型旗標，OpenClaw/acpx 就無法強制選擇模型。

必要設定

核心 ACP 基準設定：

{  acp: {    enabled: true,    // 選用。預設為 true；設為 false 可暫停 ACP 分派，同時保留 /acp 控制功能。    dispatch: { enabled: true },    backend: "acpx",    defaultAgent: "codex",    allowedAgents: [      "claude",      "codex",      "copilot",      "cursor",      "droid",      "gemini",      "iflow",      "kilocode",      "kimi",      "kiro",      "openclaw",      "opencode",      "qwen",    ],    stream: {      deliveryMode: "live",    },  },}

討論串繫結設定由支援的頻道轉接器共用：

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

如果繫結討論串的 ACP 衍生功能無法運作，請先確認轉接器功能旗標：

• Discord：session.threadBindings.spawnSessions=true

目前對話繫結不需要建立子討論串。它需要有效的對話內容，以及公開 ACP 對話繫結的頻道轉接器。

請參閱設定參考。

acpx 後端的外掛設定

套件安裝會使用官方 @openclaw/acpx 執行階段外掛來支援 ACP。 使用 ACP 執行框架工作階段前，請先安裝並啟用：

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

原始碼簽出版本也可在 pnpm install 之後使用本機工作區外掛。

請先執行：

/acp doctor

如果你已停用 acpx、透過 plugins.allow／plugins.deny 拒絕它，或想要 切回套件外掛，請使用明確的套件路徑：

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

開發期間安裝本機工作區：

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

接著確認後端健康狀態：

/acp doctor

acpx 執行階段啟動探測

acpx 外掛直接內嵌 ACP 執行階段（不需設定個別的 acpx 二進位檔或 版本）。預設會在閘道啟動期間註冊內嵌後端，並在閘道 ready 訊號前等待啟動探測。只有對刻意停用啟動探測的指令碼或環境，才設定 OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 或 OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1。執行 /acp doctor 可明確進行 隨選探測。

當路徑或旗標值應保持為單一 argv 權杖時，可使用結構化引數覆寫個別 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 為選用。OpenClaw 將每個陣列項目傳入目前的 acpx 命令字串登錄檔前，會先以 shell 引號括住。

請參閱外掛。

自動下載轉接器

acpx 會在首次使用時透過 npx 自動下載 ACP 轉接器（例如 Claude 和 Codex ACP 橋接器）。你不需要手動安裝轉接器套件，OpenClaw 本身也沒有個別的 postinstall 步驟。如果 轉接器下載或衍生失敗，/acp doctor 會回報失敗。

外掛工具 MCP 橋接器

預設情況下，ACPX 工作階段不會向 ACP 執行框架公開由 OpenClaw 外掛註冊的工具。

如果你希望 Codex 或 Claude Code 等 ACP 代理程式能呼叫已安裝的 OpenClaw 外掛工具（例如記憶回想／儲存），請啟用專用橋接器：

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

其作用如下：

• 在 ACPX 工作階段啟動程序中注入名為 openclaw-plugin-tools 的內建 MCP 伺服器。
• 公開已由安裝且啟用的 OpenClaw 外掛註冊的外掛工具。
• 將作用中的 ACP 工作階段身分傳遞給外掛工具工廠，讓代理程式範圍工具維持在該代理程式的命名空間中。
• 維持此功能需明確啟用，且預設關閉。

安全性與信任注意事項：

• 這會擴大 ACP 執行框架的工具介面範圍。
• ACP 代理程式只能存取已在閘道中啟用的外掛工具。
• 請將此視為與允許這些外掛在 OpenClaw 本身執行相同的信任邊界。
• 啟用前請檢查已安裝的外掛。

自訂 mcpServers 仍會如以往運作。內建外掛工具橋接器是額外的選用便利功能，並非一般 MCP 伺服器設定的替代方案。

OpenClaw 工具 MCP 橋接器

預設情況下，ACPX 工作階段也不會透過 MCP 公開內建 OpenClaw 工具。當 ACP 代理程式需要 cron 等特定內建工具時，請啟用個別的核心工具橋接器：

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

其作用如下：

• 在 ACPX 工作階段啟動程序中注入名為 openclaw-tools 的內建 MCP 伺服器。
• 公開所選的內建 OpenClaw 工具。初始伺服器會公開 cron。
• 維持核心工具公開功能需明確啟用，且預設關閉。

執行階段作業逾時設定

acpx 外掛預設為內嵌執行階段啟動與控制作業提供 120 秒。這可讓 Gemini 命令列介面等速度較慢的執行框架有足夠時間 完成 ACP 啟動與初始化。如果主機需要不同的作業時間限制，請覆寫此值：

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

執行階段輪次使用 OpenClaw 代理程式／執行逾時，包括 /acp timeout。 sessions_spawn 不接受個別呼叫的逾時覆寫；操作人員應使用 agents.defaults.subagents.runTimeoutSeconds。變更 timeoutSeconds 後，請重新啟動閘道。

健康探測代理程式設定

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

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

變更此值後，請重新啟動閘道。

權限設定

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

這些 ACPX 工具框架權限與 OpenClaw 執行核准彼此獨立，也與 Claude 命令列介面 --permission-mode bypassPermissions 等命令列介面後端廠商略過旗標分開。ACPX approve-all 是 ACP 工作階段在工具框架層級的緊急解鎖開關。

如需瞭解 OpenClaw tools.exec.mode、Codex Guardian 核准與 ACPX 工具框架權限之間更廣泛的比較，請參閱 權限模式。

permissionMode

控制工具框架代理程式無須提示即可執行哪些作業。

nonInteractivePermissions

控制在原本應顯示權限提示，但沒有可用的互動式終端介面時會發生什麼情況（ACP 工作階段一律如此）。

設定

透過外掛設定：

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

變更這些值後，請重新啟動閘道。

相關內容

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