之前一直在折腾 AI Agent 与本地代码库的对接问题，最困扰我的不是模型能力，而是“AI 在网页端能看代码，进了编辑器就失灵”。要么把代码复制到聊天框，要么让 Agent 直接操作整个文件系统，权限大得让人不放心。后来接触了 OpenHands 与 ACP 协议，才找到一套比较规整的解决方案。本文记录的是 OpenHands 系列教程第六章第 2 节内容：ACP 协议如何让 AI 进驻四种主流编辑器生态。整个方案的核心思路是“编辑器不需要直接内置 Agent，而是通过统一协议与 Agent 通信”，这样既降低了编辑器侧的接入成本，又让 Agent 本身可以在多个 IDE 之间复用。
如果你正在做 AI Agent 产品，或者想把本地 IDE 改造成 AI 可操作的编程环境，这套协议和接入方式值得花半小时读完。文中的配置步骤、代码示例和踩坑清单都是我实际验证过的思路，照着做基本能跑通。
1. 为什么AI Agent需要进驻编辑器
1.1 常见痛点：AI在网页端聊天，但代码改动要反复复制粘贴
早期使用 AI 编程助手的时候，最常见的姿势是：打开网页版对话窗口，把当前文件代码粘贴进去，让模型生成修改建议，再手动把建议代码复制回编辑器。如果是几十行的函数还好，一旦涉及跨文件重构、批量重命名、多文件调试，这种“贴来贴去”的方式效率极低，而且容易漏贴、错贴。
后来出现了各种 AI 插件，但大部分插件只是把聊天面板搬进了 IDE，本质上仍然是把代码片段交给模型，并没有让 Agent 真正理解“编辑器当前打开了什么文件、光标在哪里、终端输出是什么”。真正成熟的 AI Agent 需要能够像人一样操作编辑器：读文件、写文件、执行命令、查看编译错误、调整光标位置。
1.2 ACP协议是什么：一个让AI代理与编辑器“对话”的桥梁
ACP 全称是 Agent Client Protocol，中文可以理解为“代理端与客户端通信协议”。它定义了 AI 代理（Agent）与编辑器、IDE、以及其他开发者工具之间的通信标准。通过 ACP，编辑器不需要知道 Agent 内部运行的是什么模型、什么提示词策略，只需要按照协议发送会话消息、接收事件流即可。
这就像 LSP（Language Server Protocol）解决了“编辑器如何与语言服务器通信”的问题一样，ACP 解决的是“编辑器如何与 AI 代理通信”的问题。AKA 把语言分析能力和编程 AI 能力统一抽象成协议接口，让整个生态往更开放的方向发展。
1.3 四种编辑器生态概述
本文重点讲解四种编辑器生态的接入方式：
- Visual Studio Code 以及兼容 VS Code 扩展机制的编辑器。
- JetBrains 全家桶（IntelliJ IDEA、PyCharm、GoLand 等）。
- Vim / Neovim 这一类键盘驱动型编辑器。
- Positron、Zed 等开源编辑器。
它们分别代表了“最流行”“最常见”“最极客”“最前沿”四类用户画像。通过 ACP，我们可以用同一套 OpenHands Agent 后端，在不同的编辑器前端中获得类似的 AI 协作体验。
2. 认识ACP协议：设计目标与核心概念
2.1 从LSP到ACP：编辑器协议的发展脉络
编辑器协议化设计已经有成功的先例。LSP 协议将“自动补全、跳转定义、查找引用”这类语言智能从编辑器中抽离出来，让编辑器只需要实现协议客户端，就能接入各种语言服务。MCP（Model Context Protocol）则把 AI 模型与外部工具、数据源连接起来，解决“模型怎么能取到工具返回的数据”的问题。
ACP 的定位在两者之间偏上层：它不负责语法分析，也不负责工具调用，而是负责“编辑器（客户端）与 AI 代理（Agent）之间完整的会话管理、事件同步、动作执行”。可以理解为 ACP 把 Agent 当成一个可以驱动的子进程服务，编辑器作为控制端，向 Agent 发送打开会话、推送消息、执行动作等指令。
2.2 ACP的两端：Agent Endpoint与Client Endpoint
在 ACP 协议中，参与通信的两端分别是：
- Agent Endpoint：由 Agent 运行时提供，负责接收客户端请求、运行模型推理、调度工具、生成事件。OpenHands 启动 ACP 服务后，就是作为 Agent Endpoint 存在。
- Client Endpoint：由编辑器插件提供，负责将用户的操作（聊天发送、文件打开、选中等）转换为 ACP 请求，并把 Agent 返回的事件渲染到界面。
这种端到端的抽象使得 Agent 与编辑器客户端的职责非常清晰：编辑器不需要关心模型怎么选、工具怎么调用；Agent 也不需要关心用户用的是 VS Code 还是 Neovim。
2.3 ACP与MCP的区别
很多初学者容易把 ACP 与 MCP 混淆。简单来说：
- MCP 解决的是“AI 与外部工具/数据源”的连接问题。比如让 AI 调用一个天气 API，或者查询数据库。
- ACP 解决的是“客户端（编辑器）与 Agent”的连接问题。比如让编辑器中的聊天面板可以查看到 Agent 正在执行的命令，并允许用户取消。
在实际产品中，这两者常常配合使用：ACP 负责编辑器与 Agent 的通信，Agent 内部再通过 MCP 调用外部工具。不要把它们当成同一个协议。
2.4 传输层与消息通道
ACP 协议在传输层比较灵活，支持标准输入输出（stdio）传输，也支持 HTTP 或 WebSocket 传输。本地开发时最常用的是 stdio 模式：编辑器插件直接启动一个 Agent 子进程，通过标准输入输出与 Agent 交换 JSON 消息。远程开发或跨机协作时，可以启动 HTTP 模式，让 Agent 运行在一台高配服务器上，编辑器在本机连接。
+------------------+ ACP协议 +------------------+ | Client Endpoint | <----------------------> | Agent Endpoint | | VS Code / JetBrains | stdio / HTTP/WS | OpenHands | | Neovim / Zed | | 内置Agent运行时 | +------------------+ +------------------+3. ACP协议的核心消息与工作流程
3.1 会话生命周期
在 ACP 协议中，一个完整的人机协作过程以“会话（Session）”为单位。生命周期大致如下：
- 编辑器插件发起创建会话请求。
- Agent 接收请求，初始化运行时环境，返回会话 ID。
- 编辑器向会话中发送用户消息。
- Agent 生成事件流（包括中间思考、工具调用、最终回复）。
- 编辑器可以发送取消、停止等控制指令。
- 会话结束或超时后，编辑器主动关闭会话。
这个模型与很多 AI Agent 产品的设计高度一致。关键区别在于：ACP 将“会话”定义为协议层的一等公民，编辑器和 Agent 之间不依赖任何特定的前端框架或云服务。
3.2 核心消息类型
尽管 ACP 协议还在不断演进，但有几类消息是所有客户端和 Agent 都必须支持的：
- 创建会话：用于初始化一个新的 Agent 会话。
- 发送消息：将用户输入发送给 Agent。
- 事件流：Agent 返回的流式事件，包括文本片段、状态变更、需要用户操作的通知等。
- 执行动作：Agent 需要编辑器执行某些操作时，可以通过动作消息请求，例如打开某个文件、跳转到某一行。
- 关闭会话：结束当前会话，释放资源。
这些消息看起来不多，但已经覆盖了日常 AI 结对编程的绝大多数交互场景。
3.3 一个典型交互流程的ASCII图
下面用一个简单的 ASCII 图展示用户在编辑器中向 Agent 提问时，ACP 协议层的消息走向：
用户输入问题 | v 编辑器插件 -> [创建会话] -> OpenHands Agent | | | v | Agent处理请求 | | | <--- 事件流（逐步返回） --| v 编辑器界面渲染回复4. 环境准备与版本说明
4.1 运行环境
在开始接入之前，你需要准备一个可以运行 OpenHands 的环境。本文示例以常见环境为例：
- 操作系统：Linux、macOS 或 Windows（Windows 建议使用 WSL2 获得更好兼容性）。
- Node.js 版本：建议 18 及以上，部分编辑器的插件依赖高版本 Node。
- Python 版本：建议 3.10 及以上，OpenHands 的 Python 运行时对较新版本支持更好。
- Docker：如果希望使用容器化方式运行 OpenHands，需要提前安装 Docker 并确保服务可用。
版本需要根据你的项目实际情况调整，重点演示配置思路，不要固守某一个具体的版本号。
4.2 OpenHands与编辑器版本建议
OpenHands 目前处于快速迭代阶段，不同版本的 CLI 子命令和配置项可能存在差异。建议尽量使用最新稳定版。编辑器侧，VS Code 建议使用 1.80 以上版本；JetBrains 系列建议使用 2023.1 以上版本；Neovim 建议 0.9 及以上；Zed 和 Positron 这类更新较快的编辑器，直接使用最新版本即可。
如果你使用的版本较旧，遇到接口不一致时优先查看官方更新日志。
4.3 安装OpenHands CLI
OpenHands 可以通过多种方式安装。最简单的方式是直接安装官方发布的 CLI 工具：
# 通过 pip 安装（示例思路，具体以官方文档为准） pip install openhands-ai # 验证安装 openhands --version如果网络环境受限，也可以选择从源码构建或者使用官方 Docker 镜像。安装完成后，可以尝试执行以下命令查看 ACP 相关子命令：
openhands acp --help如果 CLI 支持 show-help 输出，你会看到类似serve、start之类的子命令。这些命令用于启动一个 ACP 服务进程，由编辑器插件管理其生命周期。
4.4 验证环境
为了确认 OpenHands 能正常启动，可以运行一个简单的测试会话：
# 进入交互模式，确认 OpenAI 或本地模型可以正常响应 openhands建议先跑通最基础的非 ACP 交互模式，再进入编辑器集成阶段。因为如果模型调用本身就没配置好，后面无论用哪种编辑器接入，都会在 ACP 通信之前就失败。
5. 实战：OpenHands通过ACP接入VS Code
5.1 安装VS Code扩展
VS Code 是目前生态最丰富的编辑器，也是接入 ACP 最顺滑的编辑器之一。在 VS Code 扩展市场搜索 “OpenHands” 或 “ACP” 即可找到官方扩展。安装之后，扩展会自动检测系统是否安装了 OpenHands CLI。
如果你使用的是 Cursor 或其他兼容 VS Code 扩展的编辑器，也可以尝试同样方式安装，但需要注意不同编辑器对进程管理的限制可能略有差异。
5.2 配置ACP Server
安装扩展后，需要配置 OpenHands CLI 的启动命令。打开 VS Code 设置文件（settings.json），添加以下内容：
{ "openhands.acpServer.command": "openhands", "openhands.acpServer.args": ["acp", "serve"], "openhands.acpServer.autoStart": true, "openhands.acpServer.env": { "OPENHANDS_VERBOSE": "true" } }其中command指定 OpenHands CLI 的路径。如果openhands不在 PATH 环境变量中，需要写成绝对路径，例如/usr/local/bin/openhands或C:\\Users\\你的用户名\\AppData\\Local\\Programs\\Python\\Python311\\Scripts\\openhands.exe。
autoStart控制扩展是否在 VS Code 启动时自动拉起 Agent 进程。建议开发环境开启，生产环境按需调整。
5.3 使用效果与验证
配置完成后，重启 VS Code。在左侧或侧边栏找到 OpenHands 面板，点击“新建会话”。如果一切正常，面板会展示一个类似聊天窗口的界面，你可以在其中输入问题，例如“帮我看看当前文件第 20 行有什么潜在 bug”。
Agent 在回答过程中，会通过 ACP 事件流返回状态信息，例如正在读取文件、正在执行搜索、正在生成补丁。你还可以在设置中开启“自动应用补丁”功能，让 Agent 的修改直接写入当前工作区，但建议先让 Agent 输出 diff，人工确认后再应用。
6. 实战：OpenHands通过ACP接入JetBrains系列
6.1 安装插件
JetBrains 系编辑器（IntelliJ IDEA、PyCharm、GoLand、WebStorm 等）同样通过 ACP 协议接入 OpenHands。打开 Settings → Plugins，搜索 “OpenHands”，安装官方插件后重启 IDE。
安装完成后，IDE 顶部菜单栏会出现 OpenHands 入口，底部工具窗口会多出一个 AI 面板。
6.2 设置中的配置
JetBrains 插件的配置入口一般在 Settings → Tools → OpenHands（不同版本可能显示为 Other Settings → OpenHands）。需要配置的关键项是 Agent 可执行文件路径。
如果你希望通过远程或容器方式运行 Agent，可以填写远程服务器地址；如果希望本地运行，直接填写openhands或绝对路径。
配置示例：
Agent 可执行文件：/usr/local/bin/openhands ACP 启动参数：acp serve 工作目录：当前项目目录 自动创建会话：开启需要特别注意的是，JetBrains 插件对“工作目录”的处理与 VS Code 略有不同。为了让 Agent 能正确感知项目文件结构，建议将工作目录设置为当前项目根目录，而不是 IDE 安装目录。
6.3 首次会话体验
配置完成后，在 OpenHands 面板中发起一个会话请求。注意 JetBrains 系列编辑器对文件操作的权限管理比较严格，当 Agent 尝试修改文件时，IDE 可能会弹出“外部进程尝试修改文件”的确认框。这是 JetBrains 的默认安全策略，并不代表插件异常。
为了减少打断，可以在设置中将 OpenHands 工作目录加入信任区域，或者开启“允许自动同步外部文件变化”。同时建议保留对删除操作的手动确认，避免 Agent 误删文件。
7. 实战：OpenHands通过ACP接入Vim/Neovim
7.1 安装openhands.nvim
Vim/Neovim 用户通常对快捷键和键盘流有很高的要求。社区已经出现了一些基于 ACP 的 Neovim 插件，例如 openhands.nvim。它的工作方式与 claude-code.nvim 类似：插件在 Neovim 中启动一个 ACP 子进程，并通过 RPC 调用与 Agent 通信。
在 Neovim 中，可以使用 lazy.nvim 或 packer.nvim 安装插件。以 lazy.nvim 为例：
{ "yourname/openhands.nvim", dependencies = { "nvim-lua/plenary.nvim", "nvim-telescope/telescope.nvim", }, config = function() require("openhands").setup() end, }7.2 配置示例
openhands.nvim 同样需要指定 OpenHands CLI 的启动方式。示例思路如下，需按实际插件版本调整：
require("openhands").setup({ server = { command = "openhands", args = { "acp", "serve" }, }, ui = { border = "rounded", keymaps = { send = "<CR>", stop = "<C-c>", }, }, })配置完成后，在 Neovim 中执行:OpenHands即可打开对话悬浮窗口。你可以选中一段代码后发送给 Agent，也可以让 Agent 基于当前 buffer 内容生成修改建议。
7.3 快捷键与buffer交互
Neovim 接入 ACP 后，最核心的交互方式有两种：
- 对话模式：在悬浮窗口中输入自然语言指令，Agent 会返回文本和代码片段。
- Buffer 操作：Agent 可以读取当前打开的 buffer 内容，也可以将回复写入新 buffer 或临时文件。
由于 Vim/Neovim 没有传统意义上的文件树和鼠标操作，Agent 修改文件的方式通常是通过生成 diff 补丁，再由用户选择是否应用。建议在 Neovim 中预装vim-fugitive或diffview等插件，以便更直观地预览和合并 Agent 生成的补丁。
8. 实战：OpenHands通过ACP接入Positron与Zed等开源编辑器
8.1 Positron：数据科学场景下的AI编辑器
Positron 是 RStudio 团队推出的开源 IDE，主要面向数据科学场景，同时支持 Python 和 R 语言。与通用 IDE 相比，Positron 在数据探索、notebook、变量查看等方面有明显优势。
Positron 对 AI Agent 支持力度较大，它与 OpenHands 合作，将 OpenHands 作为内置 AI 引擎。在 Positron 中，你不需要额外下载插件，只需要在设置中启用 AI 功能并配置 OpenHands 的可执行文件：
- 打开 Preferences → AI。
- 在 Runtime 或 Agent 路径中填写 OpenHands CLI 路径。
- 打开聊天面板，选择 OpenAI 或本地模型作为后端。
8.2 Zed：轻量高性能编辑器接入ACP
Zed 是一款新兴的高性能编辑器，主打低延迟和多人协作，也参与了 ACP 协议的早期建设。Zed 对代理协议的支持比较原生，用户可以通过扩展机制接入 OpenHands。
在 Zed 的扩展市场搜索 OpenHands 并安装后，需要在设置中添加 ACP 服务地址。Zed 可以选择连接本地 stdio 启动的 Agent 进程，也可以连接远程 HTTP 服务：
{ "openhands": { "command": "openhands", "args": ["acp", "serve"], "devServer": "http://localhost:3000" } }由于 Zed 更新速度较快，不同版本的配置项名称可能会有变化。如果找不到对应的设置项，可以参考 Zed 官方文档中关于 Dev Server 和 Agent 扩展的说明。
8.3 其他开源编辑器的集成思路
除了以上编辑器，理论上任何支持自定义插件或扩展机制的编辑器都可以通过 ACP 协议接入 AI Agent。接入思路通常是：
- 判断编辑器能否启动子进程并与子进程进行标准输入输出通信。
- 参考 ACP 协议消息格式，实现一个最简单的客户端插件。
- 将插件中的用户输入转换为 ACP 会话消息。
- 将 Agent 返回的事件流渲染到编辑器的某个面板或 buffer。
如果编辑器不支持自定义插件，也可以通过外部终端启动 OpenHands 的 ACP 客户端，将内容通过系统剪贴板与编辑器交互。这种方式虽然不如原生插件方便，但至少能让 Agent 的能力延伸到更多场景。
9. 高频问题与排查思路
9.1 ACP连接失败
| 问题现象 | 常见原因 | 解决思路 |
|---|---|---|
| 扩展提示“无法连接 ACP 服务” | OpenHands CLI 未安装或不在 PATH 中 | 检查openhands --version是否能执行，若失败则配置绝对路径 |
| 启动后提示“子进程退出” | Node.js 或 Python 版本过旧 | 升级到受支持的版本，并查看扩展日志 |
| 网络环境受限，模型无法请求 | 模型 API 域名被网络策略拦截 | 在 OpenHands 的配置文件或环境变量中配置代理，注意合规使用网络 |
最常见的原因其实是 PATH 路径问题。VS Code 的图形化启动环境有时不会加载用户在.bashrc或.zshrc中配置的 PATH，导致 GUI 环境中找不到openhands命令。解决办法是在扩展设置中显式指定可执行文件的绝对路径。
9.2 编辑器扩展一直转圈
出现“转圈”或“加载中”状态，通常不是 ACP 协议本身出了问题，而是 Agent 正在等待模型响应，或者模型响应速度过慢。可以按以下步骤检查：
- 查看 OpenHands CLI 所在终端是否输出日志。
- 在扩展设置中开启详细日志（verbose）。
- 尝试在终端直接运行
openhands acp serve，观察是否能正常启动会话。
如果终端中启动正常，但扩展连接异常，说明问题出在编辑器插件配置，而不是 OpenHands 本身。
9.3 Agent执行工具失败
Agent 在分析代码时可能尝试执行终端命令，例如npm run build、pytest等。如果执行失败，通常是由于工作目录不对或权限不足。
建议在配置中明确设置工作目录，或者通过环境变量将项目根目录传递给 Agent。如果 Agent 需要调用 Docker 相关命令，还需要确保当前用户有 Docker 访问权限。
9.4 Windows路径与用户权限问题
Windows 环境下，路径分隔符、编码、命令执行策略都会成为隐藏坑。常见的报错包括：
- 反斜杠路径被误解析。
- Python 脚本编码问题导致日志乱码。
- PowerShell 执行策略限制脚本运行。
建议在 Windows 中使用 WSL2 作为 OpenHands 的运行环境，再将编辑器的 ACP 命令指向 WSL 中的openhands可执行文件。这样能规避大部分路径与权限问题。
9.5 不同编辑器资源占用过高
如果同时打开多个编辑器，且每个编辑器都启动了一个 ACP 会话，会导致多个 Agent 进程同时运行，资源占用迅速上升。
解决方案是：不要在所有编辑器窗口中开启“自动启动”功能，仅在需要时手动创建会话。或者在配置中指定复用同一个远程 ACP 服务，避免每个窗口都起一个子进程。
10. 最佳实践与工程建议
10.1 命令与PATH管理
在配置 ACP 客户端时，不要依赖系统的 PATH 环境变量。无论是 VS Code、JetBrains 还是 Neovim，都尽量在配置中写入 OpenHands CLI 的绝对路径。这样能避免图形化启动环境与终端环境不一致带来的难排查问题。
推荐在项目根目录维护一个.env文件，存放模型 API Key、Agent 配置等敏感内容，并通过编辑器插件或 OpenHands 的配置文件读取，而不是把 API Key 直接写进设置项。
10.2 日志与调试
接入 ACP 的过程中，日志是排查问题的第一手段。在 VS Code 中可以通过命令面板切换 OpenHands 的输出面板；在 JetBrains 中可以通过 Help → Show Log 查看插件日志；在 Neovim 中可以通过:messages查看插件输出。
建议在首次接入时开启详细日志，调试完成后关闭，避免生产环境日志过多。
10.3 安全与最小权限
让 AI Agent 操作编辑器意味着 Agent 可以读取代码、修改文件、执行命令。在涉及安全、权限、认证时，应遵循最小权限原则：
- 不要让 Agent 使用管理员权限运行。
- 在测试环境中验证 Agent 能执行的操作范围。
- 对删除、批量替换等高风险操作保持手动确认。
- 不要将生产环境的 API Key、数据库连接串直接暴露给 Agent。
如果 Agent 需要修改多个文件，建议让 Agent 先生成 diff，人工 review 后再统一应用。这比让 Agent 直接写文件安全得多。
10.4 多项目与工作区隔离
如果一个 OpenHands Agent 服务被多个项目复用，可能会发生上下文污染。比如 Agent 在 A 项目读取过的文件路径，在 B 项目中可能不适用。
建议为每个项目启动独立的 ACP 会话，或者在打开新项目时显式重置会话。部分编辑器插件已经实现了按工作区隔离会话，只需在配置中开启“独立会话”选项。
10.5 生产环境的注意事项
在团队协作或 CI/CD 环境中使用 ACP，需要额外注意：
- 版本锁定：OpenHands、编辑器插件、ACP 协议的版本都要记录，避免升级后接口变化影响协作。
- 超时控制：配置合理的请求超时时间，防止 Agent 长任务拖垮编辑器的 CPU 和内存。
- 备份与回滚：如果 Agent 会自动修改代码，建议在开启前做好 Git 提交或快照备份，确保可以一键回滚。
- 权限联动：如果编辑器服务端部署在多用户环境中，需要确保 Agent 操作的文件范围与用户权限一致，防止越权读写。
这些建议不一定全部适用于个人项目，但一旦进入团队协作或生产环境，缺了其中任何一项都可能带来明显问题。
11. 总结与下一步学习路线
11.1 本次掌握的关键点
通过本文，我们完成了以下知识闭环：
- 理解了 ACP 协议在 AI Agent 与编辑器协作中的定位与价值。
- 梳理了 ACP 的会话生命周期、核心消息类型和传输层工作机制。
- 完成了 VS Code、JetBrains、Neovim、Zed/Positron 四类编辑器生态的接入配置。
- 总结了一套通用的 ACP 接入排查思路与工程安全建议。
这套方案的收益在于：你的 Agent 能力不再被绑定在某一个特定 IDE 上，只要支持 ACP，同一个 OpenHands Agent 就可以在多个编辑器中复用。对于团队中有人用 VS Code、有人用 PyCharm、有人用 Neovim 的场景，这比各自维护一套定制插件要高效得多。
11.2 推荐的进阶方向
如果你已经能在编辑器中正常使用 ACP，可以继续深入以下方向：
- 学习 ACP 协议库的源码，了解事件流和动作执行的底层实现。
- 尝试自己为一个轻量编辑器编写一个最小 ACP 客户端插件。
- 研究 OpenHands 的事件系统，看如何将 Agent 的工具调用过程可视化到编辑器面板。
- 结合实际项目，把“AI 生成 diff → 人工 review → 自动测试 → 应用补丁”这一流程固化到团队工作流中。
如果你的项目也用到了 ACP 接入，欢迎在评论区分享你遇到过的坑和解决方案，这对后面继续写 OpenHands 系列其他章节会有很大帮助。
