OpenClaw MCP Server

OpenClaw MCP 服务

🦞 面向 OpenClaw AI 助手集成的模型上下文协议（MCP）服务。

演示

我为何构建它

嗨！我创建这个 MCP 服务，是因为我不想只依靠消息渠道与 OpenClaw 交流。最让我兴奋的是能够将 OpenClaw 连接到 Claude 网页界面。本质上，我的聊天可以把任务委托给我的 Claw 机器人，之后由它处理所有事情——比如启动 Claude Code 来替我修复问题。

可以把它想成一个 AI 助手在协调另一个 AI 助手。很酷，对吧？

快速开始

Docker（推荐）

每次发布时，都会将预构建镜像发布到 GitHub Container Registry。

docker pull ghcr.io/freema/openclaw-mcp:latest

创建一个 docker-compose.yml：

services:
  mcp-bridge:
    image: ghcr.io/freema/openclaw-mcp:latest
    container_name: openclaw-mcp
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - OPENCLAW_URL=http://host.docker.internal:18789
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - OPENCLAW_AGENT_ID=${OPENCLAW_AGENT_ID:-}
      - OPENCLAW_MODEL=openclaw
      - MCP_CLIENT_ID=openclaw
      - MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET}
      - MCP_ISSUER_URL=${MCP_ISSUER_URL:-}
      - MCP_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback
      - TRUST_PROXY=1
      - CORS_ORIGINS=https://claude.ai
    extra_hosts:
      - "host.docker.internal:host-gateway"
    read_only: true
    security_opt:
      - no-new-privileges

生成密钥并启动：

export MCP_CLIENT_SECRET=$(openssl rand -hex 32)
export OPENCLAW_GATEWAY_TOKEN=your-gateway-token
docker compose up -d

然后，在 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）

npx openclaw-mcp

添加到你的 Claude Desktop 配置中：

{
  "mcpServers": {
    "openclaw": {
      "command": "npx",
      "args": ["openclaw-mcp"],
      "env": {
        "OPENCLAW_URL": "http://127.0.0.1:18789",
        "OPENCLAW_GATEWAY_TOKEN": "your-gateway-token",
        "OPENCLAW_AGENT_ID": "main",
        "OPENCLAW_MODEL": "openclaw",
        "OPENCLAW_TIMEOUT_MS": "300000"
      }
    }
  }
}

远程（Claude.ai），不使用 Docker

MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=your-secret \
  MCP_ISSUER_URL=https://mcp.your-domain.com \
  CORS_ORIGINS=https://claude.ai OPENCLAW_GATEWAY_TOKEN=your-gateway-token \
  npx openclaw-mcp --transport http --port 3000

**重要：**在反向代理（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（参见故障排除）。

详情请参阅安装指南。

架构

┌─────────────────────────────────────────────────────────────────┐
│                         Your Server                             │
│                                                                 │
│  ┌─────────────────┐      ┌─────────────────────────┐          │
│  │   OpenClaw      │      │    OpenClaw MCP         │          │
│  │   Gateway       │◄────►│    Bridge Server        │          │
│  │   :18789        │      │    :3000                │          │
│  │                 │      │                         │          │
│  │  OpenAI-compat  │      │  - OAuth 2.1 auth       │          │
│  │  /v1/chat/...   │      │  - CORS protection      │          │
│  └─────────────────┘      │  - Input validation     │          │
│                           └──────────┬──────────────┘          │
│                                      │                          │
└──────────────────────────────────────┼──────────────────────────┘
                                       │ HTTPS + OAuth 2.1
                                       ▼
                              ┌─────────────────┐
                              │   Claude.ai     │
                              │   (MCP Client)  │
                              └─────────────────┘

可用工具

同步工具

工具	描述
openclaw_chat	向 OpenClaw 发送消息并获取回复
openclaw_status	检查 OpenClaw 网关运行状况
openclaw_instances	列出所有已配置的 OpenClaw 实例

异步工具（用于长时间运行的操作）

工具	描述
openclaw_chat_async	将消息加入队列，并立即获取 task_id
openclaw_task_status	检查任务进度并获取结果
openclaw_task_list	使用筛选条件列出你的任务
openclaw_task_cancel	取消待处理的任务

任务仅限创建它们的 MCP 连接使用。在 HTTP 模式下，一个进程会为多个客户端提供服务；客户端只能查看和取消自己的任务——即使知道其他客户端的 task_id，读取时也会显示“未找到”。 重新连接后会启用新的作用域，因此请在提交任务的连接上轮询任务状态。

多实例模式

通过单个 MCP 服务编排多个 OpenClaw 网关。一个桥接器，多个钳爪——将请求路由到生产、预发布、开发环境，或任何你命名的实例（lobster-supreme 和 the-claw-abides 都是完全有效的名称）。

┌──────────────────────────────────────────────────────────────────────┐
│                        Claude.ai / Claude Desktop                    │
│                              (MCP Client)                            │
└──────────────────────┬───────────────────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────────────────────┐
│                     OpenClaw MCP Bridge Server                        │
│                                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
│  │  Instance     │  │  Instance     │  │  Instance     │              │
│  │  Registry     │  │  Resolver     │  │  Validator    │              │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
│         │                 │                  │                        │
│  ┌──────┴─────────────────┴──────────────────┴───────┐               │
│  │              Per-Instance OpenClaw Clients          │              │
│  │     (separate auth, timeout, URL per instance)     │              │
│  └────────┬──────────────┬──────────────┬────────────┘               │
└───────────┼──────────────┼──────────────┼────────────────────────────┘
            │              │              │
            ▼              ▼              ▼
   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
   │  🦞 prod     │ │  🦞 staging  │ │  🦞 dev      │
   │  (default)   │ │              │ │              │
   │  :18789      │ │  :18789      │ │  :18789      │
   │  OpenClaw GW │ │  OpenClaw GW │ │  OpenClaw GW │
   └──────────────┘ └──────────────┘ └──────────────┘

设置

OPENCLAW_INSTANCES='[
  {"name": "prod", "url": "http://prod:18789", "token": "tok1", "default": true},
  {"name": "staging", "url": "http://staging:18789", "token": "tok2"},
  {"name": "dev", "url": "http://dev:18789", "token": "tok3"}
]'

用法

所有工具都接受可选的 instance 参数，以指定目标网关：

# Chat with staging instance
openclaw_chat message="Deploy status?" instance="staging"

# Check health of prod
openclaw_status instance="prod"

# List all configured instances
openclaw_instances

# Async task targeting dev
openclaw_chat_async message="Run tests" instance="dev"

如果省略 instance，则使用默认实例。每个实例都有独立的身份验证令牌、超时设置和 URL，彼此完全隔离。

主要功能

• 零迁移升级 — 现有的单实例部署无需更改任何配置即可运行
• 按实例隔离 — 使用独立的身份验证令牌、超时设置和 URL
• 动态路由 — Claude 会针对每个请求选择合适的实例
• 任务跟踪 — 异步任务会记住其目标实例
• 安全性 — 令牌绝不会通过 openclaw_instances 暴露

完整参考请参阅配置 — 多实例模式。

文档

• 安装 — Claude Desktop 和 Claude.ai 的设置方法
• 配置 — 环境变量和选项
• 部署 — Docker 和生产环境设置
• 威胁模型 — Claude 可以和不可以触发的操作、信任边界及攻击面
• 日志记录 — 记录哪些内容、记录位置，以及绝不记录的内容
• 开发 — 参与贡献和添加工具
• 安全 — 安全策略和最佳实践

安全性

⚠️ 在生产环境中务必启用身份验证！

# Generate secure client secret
export MCP_CLIENT_SECRET=$(openssl rand -hex 32)

# Run with auth enabled
MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=$MCP_CLIENT_SECRET \
  openclaw-mcp --transport http

除非你主动启用，否则 CORS 处于禁用状态。只有在浏览器客户端需要直接访问服务器时，才设置 CORS_ORIGINS：

CORS_ORIGINS=https://claude.ai,https://your-app.com

所有安全选项请参阅配置。

升级到 1.8.0

HTTP 传输现在必须使用 OAuth。 在 1.8.0 之前，除非设置了 AUTH_ENABLED=true，否则 HTTP 模式不会进行身份验证，因此直接运行镜像的 docker run 命令会将所有工具暴露给任何能够访问该端口的人。现在：

• 如果未设置 MCP_CLIENT_ID 和 MCP_CLIENT_SECRET，服务将拒绝启动。AUTH_ENABLED=true 仍然有效，但不再需要。
• 设置 AUTH_ENABLED=false / --no-auth 时，服务会拒绝启动，而不是静默禁用身份验证。如果确实需要不进行身份验证的服务（例如，前置代理已对每个请求进行身份验证），请设置 MCP_DANGEROUSLY_DISABLE_AUTH=true（--dangerously-disable-auth）。
• stdio 保持不变。

异步任务现在归 OAuth 客户端所有，而不是归 MCP 连接所有。 在工具调用之间开启新 MCP 会话的客户端可以轮询其创建的任务（#44）。该桥接服务是单租户的——持有客户端密钥的人已经可以完全访问同一个 OpenClaw 网关——因此 OAuth 客户端就是隔离边界。动态注册的客户端各自拥有独立的命名空间。未启用身份验证时，任务仍限定在连接范围内。

新增 ALLOWED_HOSTS，用于通过保留公共 Host 标头的反向代理进行环回绑定（Tailscale Serve、使用 proxy_set_header Host $host 的 nginx）。此前这会导致 403 Invalid Host（#41）。请参阅配置。

升级到 1.7.0

出于安全考虑，两个默认设置已更改。它们仅影响 HTTP 模式；stdio 保持不变。

• 默认关闭 CORS。 之前，未设置 CORS_ORIGINS 时会发送 Access-Control-Allow-Origin: *。如果浏览器客户端依赖此设置，请显式设置允许的来源（CORS_ORIGINS=https://your-app.com），或设置 CORS_ORIGINS=* 以恢复旧行为。
• 异步任务限定在创建它们的连接范围内。 以前轮询其他连接所排入队列的 task_id 的客户端，现在会收到“not found”。（1.8.0 将此范围放宽至经过身份验证的 OAuth 客户端。）

从 SSE 迁移到 HTTP 传输

从 v1.5.0 开始，主要传输方式为 Streamable HTTP（--transport http）。旧版 SSE 传输（--transport sse）已弃用，但仍可用于向后兼容。

变更内容

之前	之后
--transport sse	--transport http（推荐）
主要端点：GET /sse	主要端点：POST/GET/DELETE /mcp
健康状态："transport": "sse"	健康状态："transport": "streamable-http"

迁移步骤

1. CLI / Docker：将 --transport sse 替换为 --transport http

   # Before
   openclaw-mcp --transport sse --port 3000
   # After
   openclaw-mcp --transport http --port 3000
   

2. Claude.ai 连接器 URL：无需更改——Claude.ai 已使用 /mcp（Streamable HTTP）

3. 旧版客户端：/sse 和 /messages 端点仍可使用。每次 SSE 连接都会记录一条弃用警告。

4. Dockerfile ENTRYPOINT：如果使用官方 Docker 镜像，则会自动更新

注意： --transport sse 将继续作为已弃用的别名使用。无论使用哪个标志，两种传输方式都会同时提供服务。

要求

• Node.js ≥ 20
• OpenClaw 网关正在运行，并已启用 HTTP API：

  // openclaw.json
  { "gateway": { "http": { "endpoints": { "chatCompletions": { "enabled": true } } } } }
  

许可证

MIT

作者

由 Tomáš Grasl 创建

相关项目

• OpenClaw — 此 MCP 所连接的 AI 助手
• MCP Specification — Model Context Protocol 文档