接入 ACP

你是 OpenCode ACP 顧問。

【角色】
OpenCode ACP 顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 我想接什麼客戶端：___
- 為什麼需要 ACP：___
- 現有整合方式：___
- 技術背景：___
- 經驗水平：___

【工作流程】
1. 用一句話定位 ACP
2. 說明它解決什麼互操作問題
3. 判斷我是否需要
4. 給接入起點
5. 給下一步

【輸出規範】
▌一、定位
▌二、解決的問題
▌三、是否需要
▌四、接入起點 + 下一步

【硬約束】
- 按真實互操作需求判斷
- 不需要就不引入
- 以官方協議規範為準
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

ACP 的目標是讓編輯器和 AI Coding Agent 用同一種協議通訊。對新手來說，可以把它理解成“編輯器啟動 OpenCode 子程序，然後透過標準協議把對話、檔案和工具請求交給它”。

OpenCode 支援 Agent Client Protocol（ACP），允許你直接在相容的編輯器和 IDE 中使用它。

有關支援 ACP 的編輯器和工具列表，請檢視 ACP 進展報告。

設定時先理解什麼

要透過 ACP 使用 OpenCode，請在編輯器中設定執行 opencode acp 命令。

該命令會將 OpenCode 作為相容 ACP 的子程序啟動，透過 stdio 上的 JSON-RPC 與編輯器進行通訊。

你不需要讓 OpenCode 開 HTTP 服務，也不需要單獨登入一個 Web 後臺。關鍵是讓編輯器能找到 opencode 命令，並且把 acp 作為引數傳進去。

ACP 和普通 IDE 擴充套件的區別

排障時永遠先回到 CLI/TUI。如果 opencode 和 opencode acp 在終端本身都啟動不了，編輯器層設定不可能成功。

Zed

新增到你的 Zed 設定檔（~/.config/zed/settings.json）中：

{
  "agent_servers": {
    "OpenCode": {
      "command": "opencode",
      "args": ["acp"]
    }
  }
}

開啟方式：在命令面板中執行 agent: new thread 操作。

快捷鍵不是必須項。先確認命令面板能啟動，再考慮把 agent::NewExternalAgentThread 繫結到自己的 keymap。

設定時建議先不繫結快捷鍵，減少變數。能從 Command Palette 建立新 thread 後，再加 keymap。

JetBrains IDEs

根據文件，將以下內容新增到你的 JetBrains IDE 的 acp.json 中：

重點是 command 要寫絕對路徑，例如 /absolute/path/bin/opencode，引數仍然是 ["acp"]。設定完成後，在 AI Chat 代理選擇器中選擇新的 OpenCode 代理。

JetBrains 場景最常見的問題是 GUI App 的 PATH 和 shell PATH 不一致。絕對路徑可以繞過這個問題。用下面命令先找路徑：

which opencode

然後把輸出填進 command。

Neovim

Avante.nvim 和 CodeCompanion.nvim 都可以接 ACP。新手設定時只看兩個欄位：command 寫 opencode 或絕對路徑，args 寫 acp。

如果外掛需要傳遞環境變數，例如 OPENCODE_API_KEY，優先從系統環境讀取，不要把 key 寫進設定儲存庫。

Neovim 裡如果要傳 env，也儘量寫成讀取系統環境，而不是把真實 key 寫進 Lua 設定：

env = {
  OPENCODE_API_KEY = os.getenv("OPENCODE_API_KEY"),
}

怎麼判斷接入成功

成功狀態通常有三個訊號：

1. 編輯器能建立新的外部 Agent thread
2. OpenCode 能讀到目前專案檔案
3. 對話行為和終端裡使用 OpenCode 基本一致

如果編輯器提示找不到命令，先用終端確認 opencode acp 能啟動，再把 command 改成絕對路徑。

更完整的驗收可以按這個順序：

1. 終端執行 opencode acp 不報 command not found。
2. 編輯器能建立 external agent thread。
3. Agent 能讀到目前 workspace 的普通檔案。
4. Agent 能識別 AGENTS.md 裡的專案規則。
5. 只讀問答正常後，再允許一個小範圍檔案編輯。
6. 編輯後能在編輯器 diff 或 Git diff 中複查。

不要用生產儲存庫的大改動作為 ACP 首測。首測目標是驗證協議、路徑、許可權和上下文，不是驗證模型能力。

支援範圍

OpenCode 透過 ACP 使用時與在終端中使用的效果完全一致。所有功能均受支援：

• 內建工具（檔案操作、終端命令等）
• 自定義工具和斜槓命令
• 在 OpenCode 設定中設定的 MCP 伺服器
• 來自 AGENTS.md 的專案級規則
• 自定義格式化工具和程式碼檢查工具
• 代理和許可權系統

部分內建斜槓命令（如 /undo 和 /redo）目前暫不支援。遇到差異時，先判斷這是 ACP 客戶端限制，還是 OpenCode 本身能力限制。

失敗時怎麼分層

ACP 的正確排障方法是從協議入口往下查，不是先改模型或重灌外掛。

官方來源

• OpenCode ACP
• Agent Client Protocol

接下來去哪