🔗 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 Bridge) │ │
│ │ │ │ │ │
│ └──────────────┘ └────────┬─────────┘ │
│ │ │
│ ┌──────────┐ │ │
│ │ Agent │ ▼ │
│ │ Panel │ ┌────────────────────────────────────┐ │
│ └──────────┘ │ OpenClaw Gateway │ │
│ │ ┌──────────┐ ┌──────────┐ ┌────────┐ │ │
│ │ │ Session │ │ Agent │ │ Tools │ │ │
│ │ │ Manager │ │ Runtime │ │ / Skills│ │ │
│ │ └──────────┘ └──────────┘ └────────┘ │ │
│ └────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Workspace 文件系统（Agent 可读写的项目目录） │ │
│ └────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
关键组件：
| 组件 | 角色 | 说明 |
|---|---|---|
| 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
前置条件
# 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_TOKEN
cat ~/.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}"
}
}
]
}
参数说明：
| 参数 | 说明 | 默认值 |
|---|---|---|
--gateway | Gateway 地址 | 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：日常使用
# 在 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 ────────│ │
│ │ │
│ ⑨ tool_use request│ │
│ ←──────────────────│ │
│ │ │
│ ⑩ tool_approval │ │
│ ←──────────────────│ │
│ (用户在 IDE 中审批) │ │
│ │ │
│ ⑪ approval result │ │
│ ──────────────────→│ │
│ │ │
│ ⑫ final response │ │
│ ⑬ completion │ │
│ ←──────────────────│ │
│ │ │
7.2 关键消息类型
| 消息 | 方向 | 说明 |
|---|---|---|
initialize | IDE → Bridge | 初始化连接，传递 IDE 能力声明（支持哪些功能） |
agent/prompt | IDE → Bridge → Gateway | 用户发送的 prompt，可包含上下文（当前文件、选中文本等） |
agent/response | Gateway → Bridge → IDE | Agent 的响应（流式传输，逐 Token 返回） |
tool_use | Gateway → Bridge → IDE | Agent 要执行工具操作，请求 IDE 端审批 |
tool_approval | IDE → Bridge → Gateway | 用户批准/拒绝工具执行 |
file/edit | Gateway → Bridge → IDE | Agent 请求修改文件（IDE 可显示 Diff 供用户审核） |
terminal/exec | Gateway → Bridge → IDE | Agent 请求在 IDE 终端中执行命令 |
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
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",
# 在 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": {
"autoLoadFiles": ["CLAUDE.md", ".conventions.md", "README.md", "package.json", "tsconfig.json"],
"maxAutoLoadFiles": 10,
"maxAutoLoadTokens": 5000
}
}
}
8.3 IDE 端审批流
ACP 支持在 IDE 中审批 Agent 的危险操作——不需要切到 Telegram 或终端：
// openclaw.json — ACP 审批配置
{
"tools": {
"elevated": {
"mode": "ask",
"gates": ["exec", "write", "apply_patch"]
}
},
"acp": {
"approval": {
"uiMode": "ide",
"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 Bridge
echo '{"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 --verbose 2>&1 | head -20
# 查看是否有 auth 相关的错误
# 4. 检查端口
ss -tlnp | grep 18789
# 确认 Gateway 在监听
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 日志调试
# 启用 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.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"
🎯 五个关键 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、命令执行显示预览，在编辑器中一键批准或拒绝
