接入 ACP

ACP 的目标是让编辑器和 AI Coding Agent 用同一种协议通信。对新手来说，可以把它理解成“编辑器启动 OpenCode 子进程，然后通过标准协议把对话、文件和工具请求交给它”。

OpenCode 支持 Agent Client Protocol（ACP），允许你直接在兼容的编辑器和 IDE 中使用它。

有关支持 ACP 的编辑器和工具列表，请查看 ACP 进展报告。

先给结论：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 作为参数传进去。

方式	启动方式	适合场景
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 配置文件（~/.config/zed/settings.json）中：

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

打开方式：在命令面板中执行 agent: new thread 操作。

快捷键不是必须项。先确认命令面板能启动，再考虑把 agent::NewExternalAgentThread 绑定到自己的 keymap。

配置时建议先不绑定快捷键，减少变量。能从 Command Palette 创建新 thread 后，再加 keymap。

根据文档，将以下内容添加到你的 JetBrains IDE 的 acp.json 中：

重点是 command 要写绝对路径，例如 /absolute/path/bin/opencode，参数仍然是 ["acp"]。配置完成后，在 AI Chat 代理选择器中选择新的 OpenCode 代理。

JetBrains 场景最常见的问题是 GUI App 的 PATH 和 shell PATH 不一致。绝对路径可以绕过这个问题。用下面命令先找路径：

which opencode

然后把输出填进 command。

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"),
}

成功状态通常有三个信号：

如果编辑器提示找不到命令，先用终端确认 opencode acp 能启动，再把 command 改成绝对路径。

更完整的验收可以按这个顺序：

不要用生产仓库的大改动作为 ACP 首测。首测目标是验证协议、路径、权限和上下文，不是验证模型能力。

OpenCode 通过 ACP 使用时与在终端中使用的效果完全一致。所有功能均受支持：

部分内置斜杠命令（如 /undo 和 /redo）目前暂不支持。遇到差异时，先判断这是 ACP 客户端限制，还是 OpenCode 本身能力限制。