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 之间反复横跳的痛苦

如果你是一个日常使用 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_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}"
}
}
]
}

参数说明：

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 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 常见问题排查表

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

📚 参考资料

• 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 集成文档

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

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