---
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="/docs/opencode/official/08-platform/windows-wsl" description="另一类启动入口：Windows 子系统" />
  <Card title="排障" href="/docs/opencode/official/08-platform/troubleshooting" description="ACP 启动失败时的分层排障" />
  <Card title="Zen 模式" href="/docs/opencode/official/08-platform/zen" description="另一种深度专注式入口" />
  <Card title="网络配置" href="/docs/opencode/official/05-security/network" description="ACP 也是子进程，受同一套代理影响" />
  <Card title="权限控制" href="/docs/opencode/official/05-security/permissions" description="ACP 不绕过 OpenCode 的权限系统" />
</Cards>
