🦞 OpenClaw MCP Server：用 Model Context Protocol 打通 Claude.ai 与自托管 AI 助手

想象一个场景：你在 Claude.ai 网页上与 Claude 对话时，突然遇到一个需要访问本地开发环境的复杂问题——以往只能靠截图加描述来传递上下文，信息损耗不说，还容易出错。现在，OpenClaw MCP Server 让这件事变得优雅：Claude 可以直接"召唤"你部署在本地的 OpenClaw 机器人，让它调用 Claude Code 去修复代码，整个过程无需你手动复制粘贴任何内容。

这就是 MCP（Model Context Protocol）协议的魅力——它让 AI 助手之间的互相调用像调用普通 API 一样自然流畅。

背景：为什么需要一座「桥」

OpenClaw 是一个功能强大的自托管 AI 助手框架，支持 Claude Code、Claude CLI 等多种后端，内置 WebSocket 通信网关。用户既可以通过钉钉、飞书等即时通讯工具与 OpenClaw 互动，也可以通过命令行直接调用。

然而，当用户想要借助 Claude.ai 的网页界面来管理 OpenClaw 时，却发现两者之间缺乏一个统一的标准协议来沟通——Claude.ai 不知道如何找到你的本地 OpenClaw 服务，而 OpenClaw 也无法直接响应 Claude.ai 发来的请求。

作者 Tomáš Grasl 正是带着这个痛点，亲手构建了这座「桥」。他的核心理念是：一个 AI 助手调用另一个 AI 助手的编排（orchestration），这种"AI 操控 AI"的场景，代表了 AI Agent 工作流的一个重要方向。

核心功能：一座双向通行的桥

OpenClaw MCP Server 的本质是一个 MCP 协议服务器，它同时扮演两个角色：

对 Claude.ai / Claude Desktop（MCP Client）：

以标准 MCP 服务器的姿态注册，Claude.ai 可以像调用本地工具一样调用它的工具函数。这些函数背后实际上是通往 OpenClaw Gateway 的请求通道，让 Claude 的推理能力与 OpenClaw 的执行能力无缝衔接。

对 OpenClaw Gateway（API Client）：

通过 OpenAI 兼容的 HTTP API 与 OpenClaw 网关通信（默认端口 18789）。支持 OpenClaw 实例的认证令牌管理、超时控制、模型参数配置等。

同步工具（Immediate Response）

工具名	作用
`openclaw_chat`	向 OpenClaw 发送消息，立即获取回复
`openclaw_status`	检查 OpenClaw 网关健康状态
`openclaw_instances`	列出所有已配置的 OpenClaw 实例

异步工具（Long-running Operations）

对于耗时较长的任务（如运行 Claude Code 修复一个复杂的 bug），系统支持异步模式：

工具名	作用
`openclaw_chat_async`	队列消息，立即返回 task_id
`openclaw_task_status`	轮询任务进度，获取结果
`openclaw_task_list`	列出所有任务，支持过滤
`openclaw_task_cancel`	取消待处理任务

这种设计非常实用——Claude 在发起任务后可以继续与用户对话，用户无需原地等待；任务完成后再通知 Claude 继续处理后续逻辑。

OpenClaw MCP 在 Claude.ai 中的实际演示

图1：Claude.ai 中调用 OpenClaw MCP 的实际效果演示

多实例编排：一桥连多「爪」

项目最具特色的功能之一是多实例模式（Multi-Instance Mode）。通过一个 MCP 服务器，同时管理多个 OpenClaw 网关实例——可以按环境（prod / staging / dev）分组，也可以按业务线隔离，每个实例拥有独立的认证令牌、超时时间和 API 地址。

调用时只需在工具参数中指定 instance="staging"，即可将请求路由到对应网关。这对于管理多个 Claude 实例的团队尤其有价值。

架构解析：安全加固的每一步

项目采用了多阶段安全设计：

1. OAuth 2.1 认证（MCP Client 侧）：

通过 MCP_CLIENT_ID + MCP_CLIENT_SECRET 对接入 MCP 服务器的客户端进行认证。结合 MCP_REDIRECT_URIS 白名单机制（必须精确匹配 https://claude.ai/api/mcp/auth_callback），防止授权码被劫持投递到恶意地址。

2. CORS 保护：

CORS_ORIGINS 环境变量限制跨域访问，生产环境应只允许 https://claude.ai。反向代理场景下必须设置 TRUST_PROXY=1，否则 rate-limit 中间件会误判 IP 导致 /token 接口崩溃。

3. 容器层加固：

Dockerfile 中指定非 root 用户运行，docker-compose 配置 read_only: true（文件系统只读）、tmpfs: /tmp（敏感数据写入内存）、no-new-privileges（禁止容器内提权）。

4. 威胁模型文档：

项目提供了详细的威胁模型（docs/threat-model.md），明确列出了 Claude 能/不能触发的操作边界——这是 MCP 生态中少有的安全透明度。

技术栈：TypeScript + MCP SDK

项目主体使用 TypeScript（src/ 目录），核心依赖只有两个：

@modelcontextprotocol/sdk ^1.29.0 — 官方 MCP SDK，处理协议握手、工具注册、传输层
yargs ^17.7.2 — CLI 参数解析

构建工具使用 tsup（比 tsc 更快的 bundler），输出为 dist/index.js，支持两种传输协议：

Streamable HTTP（推荐，v1.5.0+ 默认）：标准 MCP HTTP 传输，主端点 POST/GET/DELETE /mcp
SSE（已废弃但兼容）：旧版 Claude Desktop 使用，主端点 GET /sse

源码目录结构清晰：

目录	职责
`src/auth/`	OAuth Provider 实现
`src/cli.ts`	命令行参数解析
`src/config/`	常量定义
`src/mcp/`	MCP 工具注册（tasks / tools 子目录）
`src/openclaw/`	OpenClaw 客户端封装（registry / client / types）
`src/server/`	HTTP 服务端（Express + CORS + rate-limit）
`src/types/`	TypeScript 类型定义
`src/utils/`	日志工具

OpenClaw MCP 官方 Logo 图

图2：OpenClaw MCP 官方宣传图

上手体验

方式一：Docker 一键部署（推荐远程 Claude.ai 使用）

官方将构建好的镜像发布到 GitHub Container Registry，直接 docker pull 即可运行，配置文件仅需填入几个关键环境变量：

export OPENCLAW_URL=http://your-openclaw:18789
export OPENCLAW_GATEWAY_TOKEN=your-token
export MCP_CLIENT_SECRET=$(openssl rand -hex 32)
docker compose up -d

然后在 Claude.ai 添加自定义 MCP 连接器，URL 指向你的域名（必须以 /mcp 结尾！）。

方式二：本地 Claude Desktop

npx openclaw-mcp

配置好 OPENCLAW_URL 和 OPENCLAW_GATEWAY_TOKEN 后，Claude Desktop 即可识别该 MCP 服务器。

依赖条件

Node.js ≥ 20（项目使用原生 ESM 模块）
OpenClaw Gateway 需开启 HTTP API：在 openclaw.json 中配置 gateway.http.endpoints.chatCompletions.enabled: true

局限与挑战

项目文档诚实列出了几个现实限制：

远程部署门槛较高：需要公网 HTTPS 域名、反向代理（Caddy/nginx/Traefik/Cloudflare Tunnel），配置链路较长，对新手不友好。
OAuth 调试困难：redirect_uri 必须精确匹配（包括末尾路径），配错一步就只能收到 Unregistered redirect_uri 错误，缺乏友好的错误提示。
单点依赖：Claude 与 OpenClaw 的沟通完全依赖这座桥，一旦 MCP 服务器宕机，两端的工具调用全部失效。
安全与便利的权衡：为了安全，项目默认 AUTH_ENABLED=true，但这也意味着每次部署都要处理 OAuth 流程，对快速尝鲜不够友好。

行业意义与趋势

MCP（Model Context Protocol）正在成为 AI Agent 互联互通的「USB-C 接口」——Anthropic 在 2024 年底开源了 MCP 协议规范后，社区迅速跟进，目前已有数百个 MCP 服务器实现。OpenClaw MCP Server 属于其中技术含量较高的一类：它不只是提供工具调用，而是实现了双向认证 + 多实例编排 + 异步任务管理的完整链路。

从增长趋势看，MCP 生态的繁荣程度直接影响这类项目的价值——接入了更多 MCP 服务器，OpenClaw 能调用的工具就越多，Claude.ai 能访问的能力也就越丰富。这是一个典型的网络效应赛道。

总结

维度	评分	说明
部署便捷性	⭐⭐⭐⭐	Docker 一键启动，但远程部署配置略复杂
代码质量	⭐⭐⭐⭐⭐	TypeScript 类型完备，多阶段构建，完整测试套件
文档完整性	⭐⭐⭐⭐⭐	架构图、威胁模型、部署指南、故障排查文档齐全
创新程度	⭐⭐⭐⭐	多实例编排 + 异步任务链路是 MCP 生态的差异化亮点
安全设计	⭐⭐⭐⭐	OAuth 2.1 + CORS + 容器加固，但依赖端到端 HTTPS

一句话评价：OpenClaw MCP Server 是 MCP 生态中"AI 操控 AI"理念的标杆实现，适合已部署 OpenClaw 并希望将其能力延伸至 Claude.ai 网页界面的进阶用户。部署有一定门槛，但一旦跑通，体验非常流畅。

🦞 OpenClaw MCP Server：用 Model Context Protocol 打通 Claude.ai 与自托管 AI 助手

这就是 MCP（Model Context Protocol）协议的魅力——它让 AI 助手之间的互相调用像调用普通 API 一样自然流畅。

背景：为什么需要一座「桥」

核心功能：一座双向通行的桥

OpenClaw MCP Server 的本质是一个 MCP 协议服务器，它同时扮演两个角色：

对 Claude.ai / Claude Desktop（MCP Client）：

对 OpenClaw Gateway（API Client）：

通过 OpenAI 兼容的 HTTP API 与 OpenClaw 网关通信（默认端口 18789）。支持 OpenClaw 实例的认证令牌管理、超时控制、模型参数配置等。

同步工具（Immediate Response）

工具名	作用
`openclaw_chat`	向 OpenClaw 发送消息，立即获取回复
`openclaw_status`	检查 OpenClaw 网关健康状态
`openclaw_instances`	列出所有已配置的 OpenClaw 实例

异步工具（Long-running Operations）

对于耗时较长的任务（如运行 Claude Code 修复一个复杂的 bug），系统支持异步模式：

工具名	作用
`openclaw_chat_async`	队列消息，立即返回 task_id
`openclaw_task_status`	轮询任务进度，获取结果
`openclaw_task_list`	列出所有任务，支持过滤
`openclaw_task_cancel`	取消待处理任务

这种设计非常实用——Claude 在发起任务后可以继续与用户对话，用户无需原地等待；任务完成后再通知 Claude 继续处理后续逻辑。

OpenClaw MCP 在 Claude.ai 中的实际演示

图1：Claude.ai 中调用 OpenClaw MCP 的实际效果演示

多实例编排：一桥连多「爪」

调用时只需在工具参数中指定 instance="staging"，即可将请求路由到对应网关。这对于管理多个 Claude 实例的团队尤其有价值。

架构解析：安全加固的每一步

项目采用了多阶段安全设计：

1. OAuth 2.1 认证（MCP Client 侧）：

2. CORS 保护：

3. 容器层加固：

4. 威胁模型文档：

项目提供了详细的威胁模型（docs/threat-model.md），明确列出了 Claude 能/不能触发的操作边界——这是 MCP 生态中少有的安全透明度。

技术栈：TypeScript + MCP SDK

项目主体使用 TypeScript（src/ 目录），核心依赖只有两个：

@modelcontextprotocol/sdk ^1.29.0 — 官方 MCP SDK，处理协议握手、工具注册、传输层
yargs ^17.7.2 — CLI 参数解析

构建工具使用 tsup（比 tsc 更快的 bundler），输出为 dist/index.js，支持两种传输协议：

Streamable HTTP（推荐，v1.5.0+ 默认）：标准 MCP HTTP 传输，主端点 POST/GET/DELETE /mcp
SSE（已废弃但兼容）：旧版 Claude Desktop 使用，主端点 GET /sse

源码目录结构清晰：

目录	职责
`src/auth/`	OAuth Provider 实现
`src/cli.ts`	命令行参数解析
`src/config/`	常量定义
`src/mcp/`	MCP 工具注册（tasks / tools 子目录）
`src/openclaw/`	OpenClaw 客户端封装（registry / client / types）
`src/server/`	HTTP 服务端（Express + CORS + rate-limit）
`src/types/`	TypeScript 类型定义
`src/utils/`	日志工具

OpenClaw MCP 官方 Logo 图

图2：OpenClaw MCP 官方宣传图

上手体验

方式一：Docker 一键部署（推荐远程 Claude.ai 使用）

官方将构建好的镜像发布到 GitHub Container Registry，直接 docker pull 即可运行，配置文件仅需填入几个关键环境变量：

export OPENCLAW_URL=http://your-openclaw:18789
export OPENCLAW_GATEWAY_TOKEN=your-token
export MCP_CLIENT_SECRET=$(openssl rand -hex 32)
docker compose up -d

然后在 Claude.ai 添加自定义 MCP 连接器，URL 指向你的域名（必须以 /mcp 结尾！）。

方式二：本地 Claude Desktop

npx openclaw-mcp

配置好 OPENCLAW_URL 和 OPENCLAW_GATEWAY_TOKEN 后，Claude Desktop 即可识别该 MCP 服务器。

依赖条件

Node.js ≥ 20（项目使用原生 ESM 模块）
OpenClaw Gateway 需开启 HTTP API：在 openclaw.json 中配置 gateway.http.endpoints.chatCompletions.enabled: true

局限与挑战

项目文档诚实列出了几个现实限制：

远程部署门槛较高：需要公网 HTTPS 域名、反向代理（Caddy/nginx/Traefik/Cloudflare Tunnel），配置链路较长，对新手不友好。
OAuth 调试困难：redirect_uri 必须精确匹配（包括末尾路径），配错一步就只能收到 Unregistered redirect_uri 错误，缺乏友好的错误提示。
单点依赖：Claude 与 OpenClaw 的沟通完全依赖这座桥，一旦 MCP 服务器宕机，两端的工具调用全部失效。
安全与便利的权衡：为了安全，项目默认 AUTH_ENABLED=true，但这也意味着每次部署都要处理 OAuth 流程，对快速尝鲜不够友好。

行业意义与趋势

总结

维度	评分	说明
部署便捷性	⭐⭐⭐⭐	Docker 一键启动，但远程部署配置略复杂
代码质量	⭐⭐⭐⭐⭐	TypeScript 类型完备，多阶段构建，完整测试套件
文档完整性	⭐⭐⭐⭐⭐	架构图、威胁模型、部署指南、故障排查文档齐全
创新程度	⭐⭐⭐⭐	多实例编排 + 异步任务链路是 MCP 生态的差异化亮点
安全设计	⭐⭐⭐⭐	OAuth 2.1 + CORS + 容器加固，但依赖端到端 HTTPS