---
title: "接入 ACP"
description: "理解 Agent Client Protocol：如何把 OpenCode 接入 Zed、JetBrains 和 Neovim 等編輯器。"
verifiedAt: "2026-05-09"
---

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

OpenCode 支援 [Agent Client Protocol](https://agentclientprotocol.com)（ACP），允許你直接在相容的編輯器和 IDE 中使用它。

有關支援 ACP 的編輯器和工具列表，請檢視 [ACP 進展報告](https://zed.dev/blog/acp-progress-report#available-now)。

> [!NOTE]
> **先給結論**：ACP 不是另一套 OpenCode 配置。它只是讓編輯器用 `opencode acp` 啟動一個 JSON-RPC over stdio 的子程序。模型、工具、MCP、AGENTS.md、許可權仍然回到 OpenCode 自己的配置。

## 配置時先理解什麼

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

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

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

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

| 方式 | 啟動方式 | 適合場景 |
| --- | --- | --- |
| IDE terminal integration | 在 VS Code、Cursor、Windsurf 終端裡執行 `opencode` | 已經以終端為主，只想快速傳當前檔案上下文 |
| ACP | 編輯器啟動 `opencode acp` 子程序 | Zed、JetBrains、Neovim 等希望直接把 OpenCode 放進 agent 面板 |
| CLI/TUI | 直接在終端執行 `opencode` | 最穩定的基礎路徑，也是排障基準 |

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

## Zed

新增到你的 [Zed](https://zed.dev) 配置檔案（`~/.config/zed/settings.json`）中：

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

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

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

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

## JetBrains IDEs

根據[文件](https://www.jetbrains.com/help/ai-assistant/acp.html)，將以下內容新增到你的 [JetBrains IDE](https://www.jetbrains.com/) 的 acp.json 中：

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

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

```bash
which opencode
```

然後把輸出填進 `command`。

## Neovim

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

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

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

```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 本身能力限制。

## 失敗時怎麼分層

| 症狀 | 優先檢查 |
| --- | --- |
| 找不到 `opencode` | 編輯器 PATH 或 `command` 絕對路徑 |
| Agent thread 建立失敗 | ACP 客戶端配置 JSON 是否正確 |
| 能啟動但不能讀專案 | workspace 許可權、沙箱或客戶端授權 |
| 行為和終端不同 | 客戶端傳入的上下文、工作目錄和 env |
| MCP 或自定義命令不可用 | OpenCode config 是否被同一個程序讀取 |
| `/undo`、`/redo` 不可用 | 先按官方已知限制處理 |

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

## 官方來源

- [OpenCode ACP](https://opencode.ai/docs/acp)
- [Agent Client Protocol](https://agentclientprotocol.com)

## 接下來去哪

<Cards>
  <Card title="Windows / WSL" href="/zh-Hant/docs/opencode/official/08-platform/windows-wsl" description="另一類啟動入口：Windows 子系統" />
  <Card title="排障" href="/zh-Hant/docs/opencode/official/08-platform/troubleshooting" description="ACP 啟動失敗時的分層排障" />
  <Card title="Zen 模式" href="/zh-Hant/docs/opencode/official/08-platform/zen" description="另一種深度專注式入口" />
  <Card title="網路配置" href="/zh-Hant/docs/opencode/official/05-security/network" description="ACP 也是子程序，受同一套代理影響" />
  <Card title="許可權控制" href="/zh-Hant/docs/opencode/official/05-security/permissions" description="ACP 不繞過 OpenCode 的許可權系統" />
</Cards>
