OpenClaw ACP 协议解析：让 IDE 直接驱动 AI Agent

OpenClaw ACP 协议解析：让 IDE 直接驱动 AI Agent

🔗 ACP（Agent Client Protocol）是 OpenClaw 的核心基础设施升级之一。它把 IDE 和 OpenClaw Gateway 之间的通信打通，让你在 VS Code / Zed 里直接驱动 AI Agent，不必再把上下文在编辑器、终端和聊天工具之间来回搬运。

为什么需要 ACP

做过一段时间 AI 辅助开发的人，大多都绕不开这种流程：在 VS Code 里写代码，觉得某段逻辑需要 Agent 帮忙；切到 Telegram、终端或 WebChat 发需求；把生成结果复制回编辑器；发现还要改，再把报错贴回去。循环几轮，心流基本就断了。

麻烦不只在切换窗口。更大的问题是，Agent 看不到你眼前的开发状态：光标在哪、打开了哪些文件、终端刚报了什么错、当前分支有没有脏文件。这些信息本来就该自动传过去，而不是靠你手动整理一遍。

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

30 秒速懂 ACP

如果你用过 VS Code，大概率知道语法高亮、自动补全、跳转定义这些能力不是编辑器自己'猜'出来的，而是通过 LSP（Language Server Protocol） 跟语言服务器通信拿到的。

ACP 的思路很像，只是对象从语言服务器换成了 AI Agent。

LSP 的世界：
VS Code ←──LSP──→ TypeScript Language Server
你输入一个字 → VS Code 问服务器'这里能补全什么' → 服务器返回建议

ACP 的世界：
VS Code ←──ACP──→ OpenClaw Gateway
你选中一段代码 → VS Code 问 Agent'帮我重构这个' → Agent 返回修改

💡 一句话说清：ACP（Agent Client Protocol）是连接 IDE 和 AI Agent 的标准化通信协议。它让编辑器不只是'显示代码'，而是能直接和 Agent 交互。

OpenClaw ACP 本身是一个命令行工具，负责在 IDE 和 OpenClaw Gateway 之间搭桥。它通过 stdio（标准输入/输出） 通信，所以只要编辑器能启动子进程，并和 stdin/stdout 对话，就能接入。VS Code、Zed、Neovim、JetBrains 都属于这类场景。

ACP 架构长什么样

┌──────────────────────────────────────────────────────────────────┐
│ 你的开发机器                                                     │
│                                                                  │
│  ┌──────────────┐ stdio ┌──────────────────┐                    │
│  │ VS Code      │ ←────────────→ │ openclaw acp │                    │
│  │ / Zed        │ JSON-RPC │ (CLI Bridge) │                    │
│  │              │          │              │                    │
│  │              │          │ 功能：       │                    │
│  │              │          │ • stdio ↔ WS 转换│                    │
│  │              │          │ • 认证管理   │                    │
│  │              │          │ • 消息路由   │                    │
│  │              │          └──────────────┘                    │
│  └──────────────┘          │                                    │
│                            │                                    │
│                            │ WebSocket                          │
│                            │ (本地或 Tailscale)                 │
│                            ▼                                    │
│  ┌────────────────────────────────────────────────────┐         │
│  │ OpenClaw Gateway                                   │         │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────────────┐    │         │
│  │  │ Session  │ │ Agent    │ │ Tools / Skills / │    │         │
│  │  │ Manager  │ │ Runtime  │ │ MCP Servers      │    │         │
│  │  └──────────┘ └──────────┘ └──────────────────┘    │         │
│  └────────────────────────────────────────────────────┘         │
│                                                                  │
│  ┌────────────────────────────────────────────────────┐         │
│  │ 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 管理) │

桥接层的价值主要在'翻译协议'。IDE 只需要发标准的 JSON-RPC 消息，Bridge 负责把它转成 Gateway 能懂的 WebSocket 通信。对 IDE 来说，这比单独接一套 OpenClaw SDK 轻得多。

ACP、MCP、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 里发起一个任务，ACP 把请求送到 OpenClaw；OpenClaw 先调用 Skill 编排流程，再通过 MCP 去查数据库、写 Notion，最后把结果沿 ACP 回传给 IDE。

你在 VS Code 里说：
'查询数据库，生成本月报告，发到 Notion'
│
ACP Protocol
│
OpenClaw Agent 接收指令
│
├── 调用 Skill 'monthly-report'
│   │
│   ├── 调用 MCP Server: pg.query
│   ├── AI 生成分析报告
│   └── 调用 MCP Server: notion.create_page
│
└── 通过 ACP 把结果流式返回到 VS Code

可以把它们理解成三层：ACP 是入口，MCP 是出口，Skill 是内部的执行逻辑。不是替代关系。

ACP 的两种运行模式

OpenClaw 对 ACP 的支持分成两种角色，这个地方要分清，不然配置时很容易绕晕。

Bridge 模式

这是最常见的方式。IDE 通过 ACP 连到 OpenClaw，OpenClaw 给 IDE 提供 Agent 能力。

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

这个模式适合在 VS Code 或 Zed 里写代码、重构、调试。

Client 模式

OpenClaw 也可以作为 ACP Client 去连别的 ACP Agent。这个能力更像编排层，OpenClaw 不只是被调用，也可以去调用别人。

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

这种方式适合把其他 Agent 当'子代理'使用，比如交给专门的审查 Agent、检索 Agent 去做局部任务。

维度	Bridge 模式	Client 模式
OpenClaw 的角色	ACP Server	ACP Client
启动命令	openclaw acp	在 openclaw.json 中配置
典型场景	IDE 里写代码	Agent 编排子任务
本文重点	是	简要提一下

在 VS Code 里配置 ACP

前置条件

# 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

获取 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

安装 VS Code 扩展

OpenClaw 的 ACP 支持有两种接入方式。

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

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

// .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"

配置 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

验证连接

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 专门做审查。

日常使用

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

ACP 的消息流

理解底层消息流，排查问题时会省很多时间。

一次完整交互的生命周期

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 │ ←───────────────── │
│ ←───────────────────              │
│               │                   │

关键消息类型

消息	方向	说明
initialize	IDE → Bridge	初始化连接，传递 IDE 能力声明
agent/prompt	IDE → Bridge → Gateway	用户发送的 prompt，可包含上下文
agent/response	Gateway → Bridge → IDE	Agent 的流式响应
tool_use	Gateway → Bridge → IDE	Agent 请求执行工具操作，需要审批
tool_approval	IDE → Bridge → Gateway	用户批准或拒绝工具执行
file/edit	Gateway → Bridge → IDE	Agent 请求修改文件，IDE 可显示 Diff
terminal/exec	Gateway → Bridge → IDE	Agent 请求在 IDE 终端中执行命令

上下文是怎么传过去的

ACP 里最实用的一点，其实不是'能说话'，而是 IDE 会自动把编辑器状态塞进上下文里。这样 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 现在是什么状态。这个比单纯'发一句话'有用得多。

进阶配置

多 Agent 路由

如果你经常做的任务不一样，最好别只挂一个 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 快速回答，省钱

Workspace 感知

让 Agent 在连接时自动读取项目结构，效果会稳定很多，尤其是它需要理解约定文件的时候。

// openclaw.json — ACP 的 workspace 配置
{
  "acp": {
    "workspace": {
      "autoLoadFiles": ["CLAUDE.md", ".conventions.md", "README.md", "package.json", "tsconfig.json"],
      "maxAutoLoadFiles": 10,
      "maxAutoLoadTokens": 5000
    }
  }
}

IDE 内审批流

危险操作最好留在 IDE 里审批，不要再切到别的工具里确认。这样至少你能直接看到 Diff 和命令预览。

// openclaw.json — ACP 审批配置
{
  "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> {     │
│ ...                                    │
└────────────────────────────────────────┘
[✅ 应用] [❌ 拒绝] [📝 修改后应用]

调试时怎么排

连接测试

# 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 在监听

常见问题

症状	可能原因	解决方案
IDE 中看不到 OpenClaw Agent 选项	配置文件语法错误	检查 JSON 语法，确认写在正确的 settings 文件中
选择 Agent 后一直'连接中'	Gateway 未运行 / 地址错误	运行 openclaw doctor，检查 --gateway 地址
连接成功但发消息无响应	Agent 名称不存在	检查 --agent 参数是否匹配 openclaw.json 中的 Agent 名称
连接后立即断开	认证失败	检查 OPENCLAW_GATEWAY_TOKEN 环境变量是否正确设置
响应到一半中断	Gateway 崩溃 / 内存不足	查看 Gateway 日志，必要时提高资源限制
文件修改未生效	工作区路径错误	检查 --workspace 是否指向正确的项目目录
Agent 看不到打开的文件	IDE 扩展版本过低	更新 IDE 和 ACP 扩展到最新版本
Tailscale 远程连接失败	WSS 证书问题	使用 wss:// 而不是 ws://，并确认 Tailscale Serve 已配置

日志调试

# 启用 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" 相关的日志

万能调试 Prompt

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

完整配置汇总

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 配置

// ~/.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
          }
        }
      }
    ]
  }
}

我会怎么理解这套东西

• ACP 解决的是'IDE 和 Agent 怎么接上'的问题。
• 它的桥接层通过 stdio 做输入输出，部署和接入都比较轻。
• IDE 上下文会自动送到 Agent 侧，这比复制粘贴报错信息高效得多。
• 多 Agent 路由很实用，主力模型、快速问答、审查职责分开后，成本和体验都更好控。
• 审批放在 IDE 内完成，至少能把 Diff 和命令预览放到同一个视野里，少一次工具切换，就少一次误操作。