用途
OpenClaw MCP Server 是一个 Model Context Protocol（MCP）服务器，用于将 OpenClaw AI 助手集成到 Claude 生态中。作者构建它的初衷是不想只依赖消息渠道与 OpenClaw 通信，而是希望把 OpenClaw 连接到 Claude 网页界面，让聊天可以委派任务给 Claw 机器人，由后者处理后续工作，例如启动 Claude Code 修复问题。可以理解为让一个 AI 助手编排另一个 AI 助手。
主要能力
- 在 Claude.ai 与自托管 OpenClaw 助手之间建立安全桥接，支持 OAuth2 认证。
- 提供同步与异步工具；异步工具用于长时间运行的操作。
- 任务作用域绑定到创建它的 MCP 连接：在 HTTP 模式下，一个进程服务多个客户端时，客户端只能查看和取消自己的任务，其他客户端的 task_id 会显示为“not found”；重新连接会开启新的作用域，因此应在排队任务的连接上轮询该任务。
- 多实例模式：可从单个 MCP 服务器编排多个 OpenClaw 网关，将请求路由到 prod、staging、dev 等自定义名称的实例。所有工具接受可选的 instance 参数以指定目标网关；省略时使用默认实例。每个实例拥有独立的认证令牌、超时和 URL，完全隔离。该模式支持零迁移升级，现有单实例部署无需更改配置；令牌不会通过 openclaw_instances 暴露。
使用方式
Docker（推荐）
预构建镜像在每次发布时推送到 GitHub Container Registry。创建 docker-compose.yml，生成密钥并启动。然后在 Claude.ai 中添加自定义 MCP 连接器，指向 https://your-domain.com/mcp，并使用 MCP_CLIENT_ID=openclaw 和 MCP_CLIENT_SECRET。
重要：连接器 URL 必须以 /mcp 结尾，这是 Streamable HTTP 端点。裸域名（https://your-domain.com）会命中服务器根路径，在 OAuth 完成后返回 404。
提示：生产环境建议固定具体版本而非 latest，例如 ghcr.io/freema/openclaw-mcp:1.1.0。
本地（Claude Desktop）
将相应配置添加到 Claude Desktop 配置中。
远程（Claude.ai）不使用 Docker
重要：当运行在反向代理（Caddy、nginx、Traefik、Cloudflare Tunnel 等）之后时，必须设置：
- MCP_ISSUER_URL（或 --issuer-url）为公开 HTTPS URL，否则 OAuth 元数据会公布 http://localhost:3000，导致客户端认证失败。
- TRUST_PROXY=1（或 --trust-proxy 1），否则 express-rate-limit 会拒绝代理的 X-Forwarded-For 头，/token 会因 ERR_ERL_UNEXPECTED_X_FORWARDED_FOR 崩溃。
建议设置 MCP_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback，使授权码只能投递到 Claude 的回调地址。注意精确的 /api/mcp/auth_callback 路径，匹配是精确的，写错会导致 OAuth 失败并报 Unregistered redirect_uri。
传输方式迁移
从 v1.5.0 起，主要传输方式是 Streamable HTTP（--transport http）。旧版 SSE 传输（--transport sse）已弃用但仍可向后兼容。迁移时，CLI / Docker 将 --transport sse 替换为 --transport http；Claude.ai 连接器 URL 无需更改，因为 Claude.ai 已使用 /mcp（Streamable HTTP）；旧客户端仍可使用 /sse 和 /messages 端点，每次 SSE 连接会记录弃用警告；使用官方 Docker 镜像时 Dockerfile ENTRYPOINT 会自动更新。--transport sse 将继续作为弃用别名工作，无论使用哪个标志，两种传输方式都会同时提供。
升级到 1.7.0
两个默认值出于安全考虑发生变化，仅影响 HTTP 模式，stdio 不变：
- CORS 现在默认关闭。此前未设置 CORS_ORIGINS 会发送 Access-Control-Allow-Origin: 。如果浏览器客户端依赖该行为，请显式设置来源（CORS_ORIGINS=https://your-app.com），或设置 CORS_ORIGINS= 恢复旧行为。
- 异步任务作用域绑定到创建它的连接。此前轮询其他连接排队的 task_id 的客户端现在会得到“not found”。
适用场景
- 希望从 Claude.ai 网页界面委派任务给自托管 OpenClaw 助手。
- 需要让一个 AI 助手编排另一个 AI 助手，例如触发 Claude Code 修复问题。
- 需要从单个 MCP 服务器管理多个 OpenClaw 网关（生产、预发布、开发等）。
- 需要 OAuth2 认证与安全桥接的自托管部署。
限制与注意事项
- 生产环境务必启用认证。
- CORS 默认禁用，除非主动开启；仅当浏览器客户端需要直接访问服务器时才设置 CORS_ORIGINS。
- 连接器 URL 必须以 /mcp 结尾，否则 OAuth 完成后返回 404。
- 反向代理后必须正确设置 MCP_ISSUER_URL 与 TRUST_PROXY，否则认证或 /token 会失败。
- 重定向 URI 匹配是精确的，写错会导致 OAuth 失败。
- 异步任务只能在创建它的连接上轮询，跨连接会显示“not found”。
- OpenClaw 网关需启用 HTTP API，例如在 openclaw.json 中配置 gateway.http.endpoints.chatCompletions.enabled 为 true。
项目由 Tomáš Grasl 创建。相关项目包括 OpenClaw（本 MCP 连接的 AI 助手）与 MCP Specification（Model Context Protocol 文档）。
