跳到主要内容 OpenClaw ACP 协议：IDE 直接驱动 AI Agent | 极客日志
编程语言 Node.js AI 大前端
OpenClaw ACP 协议：IDE 直接驱动 AI Agent 深度解析 OpenClaw ACP 协议，旨在解决开发者在 IDE 与 AI Agent 之间频繁切换的痛点。ACP 作为一个连接 IDE 和 OpenClaw Gateway 的通信隧道，允许开发者直接在 VS Code 或 Zed 中驱动 AI Agent。文章介绍了 ACP 的工作原理（类似 LSP）、架构设计（Bridge 模式与 Client 模式）、与 MCP 及 Skill 的区别。提供了详细的实战配置指南，涵盖 VS Code 和 Zed 的环境搭建、认证配置、多 Agent 路由设置以及 Workspace 感知。此外，还解析了核心消息流、上下文自动传递机制、安全审批流程以及常见问题的调试技巧，帮助开发者高效集成 AI 能力到开发环境中。
JavaCoder 发布于 2026/4/5 更新于 2026/4/18
🔗 ACP（Agent Client Protocol）是 OpenClaw 最新的核心基础设施升级 —— 一个连接 IDE 和 OpenClaw Gateway 的通信隧道，让你在 VS Code / Zed 中直接驱动 AI Agent，一切都无需离开编辑器
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 微信扫一扫，关注极客日志 微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
相关免费在线工具 RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
Mermaid 预览与可视化编辑 基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
Base64 字符串编码/解码 将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
Base64 文件转换器 将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
Markdown转HTML 将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
HTML转Markdown 将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
Bridge
组件 角色 说明 IDE (VS Code / Zed)ACP Client 发送 prompt、显示响应、提供编辑器上下文 openclaw acp (CLI)Bridge 协议翻译器：把 IDE 的 stdio 消息转为 Gateway 的 WebSocket 消息 OpenClaw Gateway ACP Server 接收请求、调用 Agent、返回结果 Agent Runtime 执行引擎 实际执行任务（调用 LLM、工具、Skills）
通信协议栈 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 现在有三个重要协议/扩展机制，新手很容易混淆：
维度 ACP (Agent Client Protocol) MCP (Model Context Protocol) Skill 解决什么问题 IDE 怎么跟 Agent 对话 Agent 怎么跟外部工具对话 Agent 怎么执行复杂工作流 通信方向 人 → Agent（自上而下） Agent → 工具（自内而外） Agent 内部（自身行为） 类比 你（老板）给员工下指令 员工使用各种办公工具 员工的标准操作手册 通信协议 JSON-RPC 2.0 over stdio JSON-RPC 2.0 over stdio/SSE 无协议（Markdown 指令） 谁实现 Server OpenClaw Gateway 外部工具提供方 不涉及 Server 谁实现 Client IDE（VS Code / Zed） OpenClaw 内置 Client 不涉及 Client 生态规模 IDE 扩展生态 1,000+ MCP 服务器 ClawHub 上千个 Skill
它们的关系 你在 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），把它们当作"子代理"使用。
对比 维度 Bridge 模式 Client 模式 OpenClaw 的角色 ACP Server（被 IDE 调用） ACP Client（调用别人） 启动命令 openclaw acp在 openclaw.json 中配置 典型场景 IDE 里写代码 Agent 编排子任务 本文重点 ⭐ 是 简要介绍
6. 实战一：在 VS Code 中配置 ACP 连接 OpenClaw
前置条件
openclaw --version
openclaw doctor
openclaw acp --help
Step 1：获取 Gateway 认证信息
cat ~/.openclaw/.env | grep GATEWAY_TOKEN
tailscale status
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：
{
"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}"
}
}
]
}
code --install-extension openclaw.openclaw-acp
Step 3：配置 ACP Bridge 参数
{
"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}"
}
}
]
}
参数 说明 默认值 --gatewayGateway 地址 ws://127.0.0.1:18789--agent使用哪个 Agent main--workspace项目工作区路径 当前目录 --session指定 session ID（可选） 自动创建新 session
Step 4：验证连接
打开 VS Code
按 Ctrl+Shift+P → 输入 "Chat: Open"
在 Agent 选择器中选择 "OpenClaw Agent"
输入测试消息："你好，请告诉我你的名字和当前工作区路径"
期望响应：
🤖 你好！我是 [Agent 名称]，当前工作区是 /path/to/your/project。我可以帮你编写代码、重构文件、运行命令等。有什么需要？
✅ 推荐做法 ：在 .vscode/settings.json 中配置而不是全局 settings，这样每个项目可以连接不同的 Agent（如 main 用于日常开发，code-reviewer 用于代码审查）。
Step 5：日常使用
💬 你：重构当前文件中的 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 ────────│ │
│ │ │
│ ⑨ tool_use request│ │
│ ←──────────────────│ │
│ │ │
│ ⑩ tool_approval │ │
│ ←──────────────────│ │
│ (用户在 IDE 中审批) │ │
│ │ │
│ ⑪ approval result │ │
│ ──────────────────→│ │
│ │ │
│ ⑫ final response │ │
│ ⑬ completion │ │
│ ←──────────────────│ │
│ │ │
7.2 关键消息类型 消息 方向 说明 initializeIDE → Bridge 初始化连接，传递 IDE 能力声明（支持哪些功能） agent/promptIDE → Bridge → Gateway 用户发送的 prompt，可包含上下文（当前文件、选中文本等） agent/responseGateway → Bridge → IDE Agent 的响应（流式传输，逐 Token 返回） tool_useGateway → Bridge → IDE Agent 要执行工具操作，请求 IDE 端审批 tool_approvalIDE → Bridge → Gateway 用户批准/拒绝工具执行 file/editGateway → Bridge → IDE Agent 请求修改文件（IDE 可显示 Diff 供用户审核） terminal/execGateway → Bridge → IDE Agent 请求在 IDE 终端中执行命令
7.3 上下文传递：IDE 怎么把编辑器状态告诉 Agent 这是 ACP 最有价值的特性——IDE 会自动在 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，按任务类型切换：
{
"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}" }
}
]
}
@openclaw-main 帮我实现这个功能 ← Sonnet 4.5 主力模型
@openclaw-reviewer 审查我的 PR ← 专门的代码审查 Agent
@openclaw-quick 这个错误是什么意思 ← Haiku 快速回答，省钱
8.2 Workspace 感知配置
{
"acp" : {
"workspace" : {
"autoLoadFiles" : [ "CLAUDE.md" , ".conventions.md" , "README.md" , "package.json" , "tsconfig.json" ] ,
"maxAutoLoadFiles" : 10 ,
"maxAutoLoadTokens" : 5000
}
}
}
8.3 IDE 端审批流 ACP 支持在 IDE 中审批 Agent 的危险操作——不需要切到 Telegram 或终端：
{
"tools" : {
"elevated" : {
"mode" : "ask" ,
"gates" : [ "exec" , "write" , "apply_patch" ]
}
} ,
"acp" : {
"approval" : {
"uiMode" : "ide" ,
"showDiffForEdits" : true ,
"showCommandPreview" : true ,
"autoApproveReadOnly" : true }
}
}
🤖 Agent 想要执行以下操作：
📝 修改文件：src /utils/auth.ts
┌────────────────────────────────────────┐
│ - function getUserById (id: string) { │
│ + function getUserById ( │
│ + id: string │
│ + ): Result<User, DatabaseError> { │
│ ... │
└────────────────────────────────────────┘
[✅ 应用] [❌ 拒绝] [📝 修改后应用]
9. 调试技巧：从"连不上"到"没反应"
9.1 连接测试
openclaw doctor
echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{}}' | openclaw acp --gateway ws://127.0.0.1:18789
openclaw acp --gateway ws://127.0.0.1:18789 --verbose 2>&1 | head -20
ss -tlnp | grep 18789
9.2 常见问题排查表 症状 可能原因 解决方案 IDE 中看不到 OpenClaw Agent 选项 配置文件语法错误 检查 JSON 语法；确认配置在正确的 settings 文件中 选择 Agent 后一直"连接中" Gateway 未运行 / 地址错误 运行 openclaw doctor；检查 --gateway 地址 连接成功但发消息无响应 Agent 名称不存在 检查 --agent 参数是否匹配 openclaw.json 中的 Agent 名称 连接后立即断开 认证失败 检查 OPENCLAW_GATEWAY_TOKEN 环境变量是否正确设置 响应到一半中断 Gateway 崩溃 / 内存不足 查看 Gateway 日志；增加 Docker 内存限制 文件修改未生效 工作区路径错误 检查 --workspace 参数是否指向正确的项目目录 Agent 看不到打开的文件 IDE 扩展版本过低 更新 IDE 和 ACP 扩展到最新版本 Tailscale 远程连接失败 WSS 证书问题 使用 wss:// 而非 ws://；确认 Tailscale Serve 已配置
9.3 日志调试
openclaw acp --gateway ws://127.0.0.1:18789 --verbose --log-level debug
grep -i "acp\|agent.*client\|bridge" ~/.openclaw/logs/*.log | tail -50
9.4 万能调试 Prompt 💬 你（在 IDE Chat 中）：
请进行自我诊断：
1. 告诉我你是通过什么协议连接的（ACP / WebSocket / 其他）
2. 你能看到我当前打开的文件吗？如果能，列出文件名
3. 你能看到我的工作区路径吗？
4. 你能执行命令吗？试着运行 "echo hello"
5. 你当前的 Agent 名称和使用的模型是什么？
10. 完整配置汇总
VS Code 完整配置
{
"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 相关配置
{
"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
ACP = IDE 和 Agent 之间的高速公路 —— 不再需要在编辑器和 Telegram/终端之间反复切换，Agent 直接嵌入你的开发环境ACP Bridge 通过 stdio 通信 —— 这使它与任何支持子进程通信的 IDE 兼容（VS Code、Zed、Neovim、JetBrains……）IDE 上下文自动传递 —— Agent 能看到你打开的文件、选中的代码、终端输出、Git 状态，不需要手动复制粘贴多 Agent 路由 —— 在 IDE 中注册多个 Agent（Main / Quick / Reviewer），按任务类型切换，兼顾效果和成本安全审批在 IDE 内完成 —— 文件修改显示 Diff、命令执行显示预览，在编辑器中一键批准或拒绝
📚 参考资料 
