OpenClaw ACP 协议深度解析：让 IDE 直接驱动你的 AI Agent

OpenClaw ACP 协议深度解析：让 IDE 直接驱动你的 AI Agent

🔗 ACP（Agent Client Protocol）是 OpenClaw 最新的核心基础设施升级 —— 一个连接 IDE 和 OpenClaw Gateway 的通信隧道，让你在 VS Code / Zed 中直接驱动 AI Agent，一切都无需离开编辑器

📑 文章目录

1. 为什么需要 ACP：在 IDE 和 Agent 之间反复横跳的痛苦
2. ACP 30 秒速懂：AI 世界的 Language Server Protocol
3. ACP 架构全景：从 IDE 到 Gateway 的完整链路
4. ACP vs MCP vs Skill：三大协议一次搞清
5. ACP 的两种运行模式：Bridge 模式 vs Client 模式
6. 实战一：在 VS Code 中配置 ACP 连接 OpenClaw
7. 实战二：在 Zed 中配置 ACP 连接 OpenClaw
8. ACP 核心消息流解析：一次完整的交互长什么样
9. 进阶配置：多 Agent 路由、Workspace 感知、审批流
10. 调试技巧：从"连不上"到"没反应"
11. 安全注意事项
12. 完整配置汇总 & 总结

1. 为什么需要 ACP：在 IDE 和 Agent 之间反复横跳的痛苦

如果你是一个日常使用 OpenClaw 的开发者，你一定经历过这种工作流：

1. 在 VS Code 里写代码，发现需要 Agent 帮忙 2. 切到 Telegram / 终端 / WebChat，跟 Agent 说需求 3. Agent 生成了代码，你手动复制 4. 切回 VS Code，粘贴到对应文件 5. 发现需要调整，再切到 Agent 对话 6. 把报错信息复制给 Agent 7. Agent 改完了，再复制回来 8. 重复 5-7 步骤 N 次... 

你在 IDE 和 Agent 之间反复横跳。 每次切换窗口都打断心流（Flow State），每次复制粘贴都可能出错（忘了复制完整、粘贴到错误的文件）。

更深层的问题是：Agent 看不到你的编辑器状态。它不知道你的光标在哪里、打开了哪些文件、终端里报了什么错。你必须手动把这些上下文"搬运"给它——而这恰恰是最该自动化的部分。

这就是 ACP 要解决的问题：让 IDE 和 Agent 直接对话，不需要你做中间人。

2. ACP 30 秒速懂：AI 世界的 Language Server Protocol

类比理解

如果你用过 VS Code，你一定享受过语法高亮、自动补全、跳转定义这些功能。这些功能不是 VS Code 自己实现的——它通过 LSP（Language Server Protocol） 跟一个后台运行的语言服务器通信，语言服务器才是真正"懂"代码的大脑。

LSP 的世界： VS Code ←──LSP──→ TypeScript Language Server 你打了一个字 → VS Code 通过 LSP 问服务器"这里能补全什么" → 服务器返回建议 ACP 的世界： VS Code ←──ACP──→ OpenClaw Gateway 你选中一段代码 → VS Code 通过 ACP 问 Agent"帮我重构这个" → Agent 返回修改 

💡 一句话定义：ACP（Agent Client Protocol）是一个连接 IDE 和 AI Agent 的标准化通信协议。就像 LSP 让任何编辑器都能获得语言智能一样，ACP 让任何编辑器都能驱动 AI Agent。

ACP 的核心身份

OpenClaw ACP 是一个命令行工具，实现 Agent Client Protocol，作为 IDE 和 OpenClaw Gateway 实例之间的通信隧道，让代码编辑器直接发送 prompt 并接收响应——一切都无需离开开发环境。

ACP 桥通过 stdio（标准输入/输出） 通信，使其与任何支持该协议的 IDE 或工具兼容。这意味着：不管是 VS Code、Zed、Neovim、JetBrains 还是未来的某个新编辑器，只要它能启动一个子进程并跟它的 stdin/stdout 通信，就能接入 ACP。

3. ACP 架构全景：从 IDE 到 Gateway 的完整链路

┌──────────────────────────────────────────────────────────────────┐ │ 你的开发机器 │ │ │ │ ┌──────────────┐ stdio ┌──────────────────┐ │ │ │ VS Code │ ←────────────→ │ openclaw acp │ │ │ │ / Zed │ JSON-RPC │ (CLI Bridge) │ │ │ │ │ │ │ │ │ │ ┌──────────┐ │ │ 功能： │ │ │ │ │ Agent │ │ │ • stdio ↔ WS 转换│ │ │ │ │ Panel │ │ │ • 认证管理 │ │ │ │ └──────────┘ │ │ • 消息路由 │ │ │ └──────────────┘ └────────┬─────────┘ │ │ │ │ │ │ WebSocket │ │ │ (本地或 Tailscale) │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────┐ │ │ │ OpenClaw Gateway │ │ │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ │ │ │ Session │ │ Agent │ │ Tools / Skills / │ │ │ │ │ │ Manager │ │ Runtime │ │ MCP Servers │ │ │ │ │ └──────────┘ └──────────┘ └──────────────────┘ │ │ │ └────────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────────┐ │ │ │ Workspace 文件系统（Agent 可读写的项目目录） │ │ │ └────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────┘ 

关键组件：

通信协议栈

IDE ←─stdio─→ ACP Bridge ←─WebSocket─→ Gateway │ │ │ JSON-RPC 2.0 │ OpenClaw 内部协议 │ (标准化消息格式) │ (session/agent 管理) │ │ 

ACP Bridge 的核心价值在于协议翻译：IDE 只需要通过标准的 stdio 发送 JSON-RPC 消息，Bridge 负责把它转换成 Gateway 能理解的 WebSocket 通信。这让 IDE 侧的实现极其简单——不需要任何 OpenClaw 专用 SDK。

4. ACP vs MCP vs Skill：三大协议一次搞清

OpenClaw 现在有三个重要协议/扩展机制，新手很容易混淆：

它们的关系

你在 VS Code 里说： "查询数据库，生成本月报告，发到 Notion" │ │ ACP Protocol ▼ OpenClaw Agent 接收指令 │ ├── 调用 Skill "monthly-report"（编排工作流） │ │ │ ├── 调用 MCP Server: pg.query（查数据库） │ ├── AI 生成分析报告 │ └── 调用 MCP Server: notion.create_page（写 Notion） │ └── 通过 ACP 把结果流式返回到 VS Code │ ▼ VS Code 显示结果 / 自动应用代码修改 

一句话总结：ACP 是入口（人→Agent），MCP 是出口（Agent→工具），Skill 是内功（Agent 的行为逻辑）。三者互补，不是竞争。

5. ACP 的两种运行模式：Bridge 模式 vs Client 模式

OpenClaw 对 ACP 的支持分为两个维度，理解它们是正确配置的前提。

模式一：ACP Bridge（OpenClaw 作为 ACP Server）

这是最常用的模式——你的 IDE 通过 ACP 连接到 OpenClaw，让 OpenClaw 为 IDE 提供 Agent 能力。

IDE (ACP Client) ──→ openclaw acp (Bridge) ──→ OpenClaw Gateway (Server) 你在 IDE 里说话 ──→ Bridge 转发 ──→ Gateway 的 Agent 执行 ──→ 结果流回 IDE 

使用场景：你想在 VS Code / Zed 中使用 OpenClaw Agent 写代码、重构、调试。

模式二：ACP Client（OpenClaw 作为 ACP Client）

这是更新的能力——OpenClaw 已将 ACP Agents 提升为一等运行时，意味着 OpenClaw 现在可以作为 ACP Client 连接到任何 ACP Agent。

OpenClaw Gateway (ACP Client) ──→ 外部 ACP Agent (Server) OpenClaw 调用外部 Agent ──→ 外部 Agent 执行 ──→ 结果返回 OpenClaw 

使用场景：你想让 OpenClaw 调用其他 AI Agent（如 Devin、Cursor Agent 等遵循 ACP 协议的 Agent），把它们当作"子代理"使用。

对比

6. 实战一：在 VS Code 中配置 ACP 连接 OpenClaw

前置条件

# 1. OpenClaw 已安装并运行 openclaw --version# openclaw v2026.3.x# 2. Gateway 正在运行 openclaw doctor # ✅ Gateway running (PID xxxx)# ✅ Auth token configured# 3. 确认 acp 子命令可用 openclaw acp --help# Usage: openclaw acp [options]# Start ACP bridge for IDE integration

Step 1：获取 Gateway 认证信息

# 如果你使用 Token 认证# 确认 .env 中有 OPENCLAW_GATEWAY_TOKENcat ~/.openclaw/.env |grep GATEWAY_TOKEN # 如果你使用 Tailscale 认证（推荐）# 确认 Tailscale 正在运行 tailscale status # 获取 Gateway 的访问地址# 本地部署：ws://127.0.0.1:18789# Tailscale：wss://your-node.tail1234.ts.net

Step 2：安装 VS Code 扩展

OpenClaw 的 ACP 支持有两种接入 VS Code 的方式：

方式 A：通过 VS Code 的 Chat/Agent API（推荐）

VS Code 2026.x 原生支持 ACP 协议的 Agent Provider。你只需要在 settings.json 中注册 OpenClaw 为一个 Agent Provider：

// .vscode/settings.json{"chat.agent.providers":[{"id":"openclaw","name":"OpenClaw","command":"openclaw","args":["acp"],"env":{"OPENCLAW_GATEWAY_URL":"ws://127.0.0.1:18789","OPENCLAW_GATEWAY_TOKEN":"${env:OPENCLAW_GATEWAY_TOKEN}"}}]}

方式 B：通过独立扩展

# 安装社区开发的 OpenClaw ACP 扩展 code --install-extension openclaw.openclaw-acp # 或者在 VS Code 扩展市场中搜索 "OpenClaw ACP"

Step 3：配置 ACP Bridge 参数

// .vscode/settings.json — 完整 ACP 配置{"chat.agent.providers":[{"id":"openclaw","name":"OpenClaw Agent","command":"openclaw","args":["acp","--gateway","ws://127.0.0.1:18789","--agent","main","--workspace","${workspaceFolder}"],"env":{"OPENCLAW_GATEWAY_TOKEN":"${env:OPENCLAW_GATEWAY_TOKEN}"}}]}

参数说明：

Step 4：验证连接

1. 打开 VS Code 2. 按 Ctrl+Shift+P → 输入 "Chat: Open" 3. 在 Agent 选择器中选择 "OpenClaw Agent" 4. 输入测试消息："你好，请告诉我你的名字和当前工作区路径" 期望响应： 🤖 你好！我是 [Agent 名称]，当前工作区是 /path/to/your/project。 我可以帮你编写代码、重构文件、运行命令等。有什么需要？ 

✅ 推荐做法：在 .vscode/settings.json 中配置而不是全局 settings，这样每个项目可以连接不同的 Agent（如 main 用于日常开发，code-reviewer 用于代码审查）。

Step 5：日常使用

# 在 VS Code Chat 面板中，你现在可以直接： 💬 你：重构当前文件中的 getUserById 函数，使用 Result<T,E> 模式 🤖 Agent： [读取当前打开的文件] [分析 getUserById 函数] [生成重构后的代码] 我已经为 getUserById 生成了重构方案： - 返回类型改为 Result<User, DatabaseError> - 添加了 try-catch 错误处理 - 添加了 JSDoc 注释 [VS Code 自动显示 Diff 视图] 要应用这个修改吗？ 💬 你：应用，然后运行测试 🤖 Agent： [应用代码修改] [在终端中运行 npm test] ✅ 所有测试通过。 

7. ACP 核心消息流解析：一次完整的交互长什么样

理解底层消息流有助于排查问题和进阶使用。

7.1 完整的请求-响应生命周期

IDE (VS Code) ACP Bridge Gateway │ │ │ │ ① initialize │ │ │ ───────────────────→ │ │ │ │ ② connect + auth │ │ │ ─────────────────→ │ │ │ ③ session created │ │ │ ←───────────────── │ │ ④ initialized │ │ │ ←─────────────────── │ │ │ │ │ │ ⑤ agent/prompt │ │ │ ───────────────────→ │ │ │ │ ⑥ forward prompt │ │ │ ─────────────────→ │ │ │ │ │ │ ⑦ streaming response │ │ │ ←─── token ────── │ │ ⑧ stream token │ ←─── token ────── │ │ ←─── token ───────── │ ←─── token ────── │ │ ←─── token ───────── │ │ │ ←─── token ───────── │ ⑨ tool_use request │ │ │ ←───────────────── │ │ ⑩ tool_approval │ │ │ ←─────────────────── │ │ │ (用户在 IDE 中审批) │ │ │ ───────────────────→ │ │ │ │ ⑪ approval result │ │ │ ─────────────────→ │ │ │ │ │ │ ⑫ final response │ │ ⑬ completion │ ←───────────────── │ │ ←─────────────────── │ │ │ │ │ 

7.2 关键消息类型

7.3 上下文传递：IDE 怎么把编辑器状态告诉 Agent

这是 ACP 最有价值的特性——IDE 会自动在 prompt 中附带编辑器上下文：

// IDE 发送给 Bridge 的 agent/prompt 消息示例{"jsonrpc":"2.0","method":"agent/prompt","params":{"prompt":"重构这个函数，使用 Result 模式","context":{"activeFile":{"path":"src/utils/auth.ts","language":"typescript","content":"... 文件完整内容 ...","selection":{"startLine":42,"endLine":67,"text":"... 选中的代码 ..."},"cursorPosition":{"line":55,"column":12}},"openFiles":["src/utils/auth.ts","src/types/result.ts","tests/auth.test.ts"],"workspace":{"root":"/home/user/projects/myapp","gitBranch":"feature/auth-refactor","gitStatus":"3 files modified"},"terminal":{"lastOutput":"npm test\n\n FAIL tests/auth.test.ts\n ..."},"diagnostics":[{"file":"src/utils/auth.ts","line":55,"severity":"error","message":"Type 'string' is not assignable to type 'Result<User, Error>'"}]}}}

Agent 收到这些信息后，就能精确理解你的开发状态：你在哪个文件、选中了什么、终端报了什么错、git 在哪个分支——不需要你手动复制任何东西。

8. 进阶配置：多 Agent 路由、Workspace 感知、审批流

8.1 多 Agent 路由

你可以在 IDE 中配置多个 Agent，按任务类型切换：

// .vscode/settings.json — 多 Agent 配置{"chat.agent.providers":[{"id":"openclaw-main","name":"OpenClaw: Main Agent","command":"openclaw","args":["acp","--agent","main"],"env":{"OPENCLAW_GATEWAY_TOKEN":"${env:OPENCLAW_GATEWAY_TOKEN}"}},{"id":"openclaw-reviewer","name":"OpenClaw: Code Reviewer","command":"openclaw","args":["acp","--agent","code-reviewer"],"env":{"OPENCLAW_GATEWAY_TOKEN":"${env:OPENCLAW_GATEWAY_TOKEN}"}},{"id":"openclaw-quick","name":"OpenClaw: Quick (Haiku)","command":"openclaw","args":["acp","--agent","quick"],"env":{"OPENCLAW_GATEWAY_TOKEN":"${env:OPENCLAW_GATEWAY_TOKEN}"}}]}

# 在 VS Code Chat 中切换： @openclaw-main 帮我实现这个功能 ← Sonnet 4.5 主力模型 @openclaw-reviewer 审查我的 PR ← 专门的代码审查 Agent @openclaw-quick 这个错误是什么意思 ← Haiku 快速回答，省钱 

8.2 Workspace 感知配置

让 Agent 在连接时自动理解项目结构：

// openclaw.json — ACP 的 workspace 配置{"acp":{"workspace":{// Agent 连接时自动读取的上下文文件"autoLoadFiles":["CLAUDE.md",".conventions.md","README.md","package.json","tsconfig.json"],// 最大自动加载文件数（防止大型 monorepo 爆上下文）"maxAutoLoadFiles":10,// 自动加载文件的最大 Token"maxAutoLoadTokens":5000}}}

8.3 IDE 端审批流

ACP 支持在 IDE 中审批 Agent 的危险操作——不需要切到 Telegram 或终端：

// openclaw.json — ACP 审批配置{"tools":{"elevated":{"mode":"ask","gates":["exec","write","apply_patch"]}},"acp":{"approval":{// 审批在 IDE 中完成（而不是 Telegram 或终端）"uiMode":"ide",// 文件修改自动显示 Diff 视图"showDiffForEdits":true,// 命令执行显示预览"showCommandPreview":true,// 自动批准安全操作（只读操作不需要审批）"autoApproveReadOnly":true}}}

IDE 端审批效果：

🤖 Agent 想要执行以下操作： 📝 修改文件: src/utils/auth.ts ┌────────────────────────────────────────┐ │ - function getUserById(id: string) { │ │ + function getUserById( │ │ + id: string │ │ + ): Result<User, DatabaseError> { │ │ ... │ └────────────────────────────────────────┘ [✅ 应用] [❌ 拒绝] [📝 修改后应用] 

9. 调试技巧：从"连不上"到"没反应"

9.1 连接测试

# 1. 确认 Gateway 正在运行 openclaw doctor # ✅ Gateway running# 2. 手动测试 ACP Bridgeecho'{"jsonrpc":"2.0","method":"initialize","id":1,"params":{}}'|\ openclaw acp --gateway ws://127.0.0.1:18789 # 期望：收到 JSON-RPC 响应（initialized 消息）# 如果超时或报错，说明 Gateway 连接有问题# 3. 检查认证 openclaw acp --gateway ws://127.0.0.1:18789 --verbose2>&1|head-20# 查看是否有 auth 相关的错误# 4. 检查端口 ss -tlnp|grep18789# 确认 Gateway 在监听

9.2 常见问题排查表

9.3 日志调试

# 启用 ACP Bridge 的详细日志 openclaw acp --gateway ws://127.0.0.1:18789 --verbose --log-level debug # 查看 Gateway 端的 ACP 相关日志grep-i"acp\|agent.*client\|bridge" ~/.openclaw/logs/*.log |tail-50# VS Code 开发者控制台（Help → Toggle Developer Tools → Console）# 搜索 "openclaw" 或 "acp" 相关的日志

9.4 万能调试 Prompt

💬 你（在 IDE Chat 中）： 请进行自我诊断： 1. 告诉我你是通过什么协议连接的（ACP / WebSocket / 其他） 2. 你能看到我当前打开的文件吗？如果能，列出文件名 3. 你能看到我的工作区路径吗？ 4. 你能执行命令吗？试着运行 "echo hello" 5. 你当前的 Agent 名称和使用的模型是什么？ 

10. 完整配置汇总

VS Code 完整配置

// .vscode/settings.json{"chat.agent.providers":[{"id":"openclaw-main","name":"OpenClaw: Main","command":"openclaw","args":["acp","--gateway","ws://127.0.0.1:18789","--agent","main","--workspace","${workspaceFolder}"],"env":{"OPENCLAW_GATEWAY_TOKEN":"${env:OPENCLAW_GATEWAY_TOKEN}"}},{"id":"openclaw-quick","name":"OpenClaw: Quick (Haiku)","command":"openclaw","args":["acp","--gateway","ws://127.0.0.1:18789","--agent","quick","--workspace","${workspaceFolder}"],"env":{"OPENCLAW_GATEWAY_TOKEN":"${env:OPENCLAW_GATEWAY_TOKEN}"}}]}

openclaw.json ACP 相关配置

// ~/.openclaw/openclaw.json — ACP 完整配置{"gateway":{"bind":"loopback","auth":{"mode":"token","token":"${OPENCLAW_GATEWAY_TOKEN}","allowTailscale":true}},"acp":{"workspace":{"autoLoadFiles":["CLAUDE.md",".conventions.md","README.md","package.json"],"maxAutoLoadFiles":10,"maxAutoLoadTokens":5000,"excludePatterns":["**/.env","**/.env.*","**/secrets/**","**/*.pem","**/*.key"]},"approval":{"uiMode":"ide","showDiffForEdits":true,"showCommandPreview":true,"autoApproveReadOnly":true}},"tools":{"elevated":{"mode":"ask","gates":["exec","write","apply_patch"]}},"agents":{"list":[{"name":"main","model":{"primary":"anthropic/claude-sonnet-4-5","thinkingBudget":{"type":"tokens","maxTokens":5000}}},{"name":"quick","model":{"primary":"anthropic/claude-haiku-3-5","thinkingBudget":{"type":"tokens","maxTokens":1000}}},{"name":"code-reviewer","model":{"primary":"anthropic/claude-sonnet-4-5","thinkingBudget":{"type":"tokens","maxTokens":8000}}}]}}

🎯 五个关键 Takeaway

1. ACP = IDE 和 Agent 之间的高速公路 —— 不再需要在编辑器和 Telegram/终端之间反复切换，Agent 直接嵌入你的开发环境
2. ACP Bridge 通过 stdio 通信 —— 这使它与任何支持子进程通信的 IDE 兼容（VS Code、Zed、Neovim、JetBrains……）
3. IDE 上下文自动传递 —— Agent 能看到你打开的文件、选中的代码、终端输出、Git 状态，不需要手动复制粘贴
4. 多 Agent 路由 —— 在 IDE 中注册多个 Agent（Main / Quick / Reviewer），按任务类型切换，兼顾效果和成本
5. 安全审批在 IDE 内完成 —— 文件修改显示 Diff、命令执行显示预览，在编辑器中一键批准或拒绝

📚 参考资料

• Run OpenClaw in VS Code through ACP
• 2026 Complete Guide: OpenClaw ACP
• OpenClaw ACP 官方文档
• Agent Client Protocol 规范
• OpenClaw GitHub: ACP 相关 PR
• Zed Agent 文档
• VS Code Chat API
• OpenClaw Tailscale 集成文档

如果觉得有帮助，欢迎 点赞 👍 收藏 ⭐ 关注 🔔，有问题评论区见！

本文为原创内容，转载请注明出处。