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

关键组件可以直接对上：

通信链路也很直接：

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 里这三套东西很容易混在一起。它们确实会一起出现，但职责完全不同。

它们的关系可以这样理解：你在 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 去做局部任务。

在 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}"
      }
    }
  ]
}

参数含义如下：

验证连接

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

关键消息类型

上下文是怎么传过去的

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

常见问题

日志调试

# 启用 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 和命令预览放到同一个视野里，少一次工具切换，就少一次误操作。