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

┌──────────────────────────────────────────────────────────────────┐
│ 你的开发机器                                                     │
│                                                                  │
│ ┌──────────────┐ stdio ┌──────────────────┐                    │
│ │ VS Code      │←───────→│ openclaw acp     │                    │
│ │ / Zed        │ JSON-RPC│ (CLI Bridge)     │                    │
│ └──────────────┘         └──────────────────┘                    │
│                              │                                    │
│                              │ 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"
          │
          ▼
   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 ───────── │                │
│                  │                    │
│ ⑨ 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": {
      "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 消息）

# 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

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、命令执行显示预览，在编辑器中一键批准或拒绝