ACP 代理程式 — 設定

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

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

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

Codex 有兩種 OpenClaw 路徑：

路徑	設定／命令	設定頁面
原生 Codex app-server	/codex ...、openai/gpt-* 代理程式參照	Codex 執行框架
明確指定的 Codex ACP 轉接器	/acp spawn codex、runtime: "acp", agentId: "codex"	本頁

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

​

acpx 執行框架支援（目前）

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

別名	封裝
claude	Claude Code
codex	Codex 命令列介面
copilot	GitHub Copilot 命令列介面
cursor	Cursor 命令列介面（cursor-agent acp）
droid	Factory Droid
fast-agent	fast-agent
gemini	Gemini 命令列介面
iflow	iFlow 命令列介面
kilocode	Kilocode
kimi	Kimi 命令列介面
kiro	Kiro 命令列介面
mux	Mux
opencode	OpenCode
openclaw	OpenClaw ACP 橋接器（原生 openclaw acp）
pi	Pi 程式設計代理程式
qoder	Qoder 命令列介面
qwen	Qwen Code
trae	Trae 命令列介面

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

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

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

模型控制取決於轉接器的功能。OpenClaw 會在啟動前正規化 Codex ACP 模型參照。其他執行框架需要 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/acpx
openclaw config set plugins.entries.acpx.enabled true

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

請從以下命令開始：

/acp doctor

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

openclaw plugins install @openclaw/acpx
openclaw 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 本身也沒有個別的安裝後步驟。如果轉接器下載或產生失敗， /acp doctor 會回報失敗。

​

外掛工具 MCP 橋接器

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

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

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

此功能會：

• 將名為 openclaw-plugin-tools 的內建 MCP 伺服器注入 ACPX 工作階段 啟動程序。
• 公開已安裝且已啟用的 OpenClaw 外掛所註冊的外掛工具。
• 將有效的 ACP 工作階段身分傳遞給外掛工具處理站，讓 代理程式範圍工具保留在該代理程式的命名空間中。
• 讓此功能必須明確啟用，且預設為停用。

安全性與信任注意事項：

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

自訂 mcpServers 仍會照常運作。內建的外掛工具橋接器是額外的選用便利功能， 而不是通用 MCP 伺服器設定的替代方案。

​

OpenClaw 工具 MCP 橋接器

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

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

此功能會：

• 將名為 openclaw-tools 的內建 MCP 伺服器注入 ACPX 工作階段 啟動程序。
• 公開特定的 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 工作階段以非互動方式執行，因此沒有可用來核准或拒絕檔案寫入與 shell 執行權限提示的 TTY。acpx 外掛提供兩個設定鍵，用來控制權限的處理方式：

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

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

​

permissionMode

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

值	行為
approve-all	自動核准所有檔案寫入與殼層命令。
approve-reads	僅自動核准讀取；寫入與執行需要提示。
deny-all	拒絕所有權限提示。

​

nonInteractivePermissions

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

值	行為
fail	以 PermissionPromptUnavailableError 中止工作階段。（預設）
deny	靜默拒絕權限並繼續執行（優雅降級）。

​

設定

透過外掛設定來設置：

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

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

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

若需要限制權限，請將 nonInteractivePermissions 設為 deny，讓工作階段優雅降級而非當機。

​

相關內容

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