OpenClaw MCP 服务器

npm version License: MIT GHCR Website

🦞 用于 OpenClaw AI 助手集成的模型上下文协议 (MCP) 服务器。

演示

构建初衷

嘿！我创建这个 MCP 服务器是因为我不想仅仅依赖消息渠道来与 OpenClaw 通信。真正让我兴奋的是能够将 OpenClaw 连接到 Claude Web UI。本质上，我的聊天可以委派任务给我的 Claw 机器人，然后由它处理所有其他事情——比如启动 Claude Code 来为我修复问题。

把它想象成一个 AI 助手在编排另一个 AI 助手。很酷，对吧？

快速入门

Docker (推荐)

预构建的镜像在每次发布时都会发布到 GitHub 容器注册表。

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_MODEL=openclaw
      - AUTH_ENABLED=true
      - MCP_CLIENT_ID=openclaw
      - MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET}
      - MCP_ISSUER_URL=${MCP_ISSUER_URL:-}
      - 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 连接器，指向您的服务器，并设置 MCP_CLIENT_ID=openclaw 和您的 MCP_CLIENT_SECRET。

提示： 在生产环境中，请固定特定版本而不是使用 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_MODEL": "openclaw",
        "OPENCLAW_TIMEOUT_MS": "300000"
      }
    }
  }
}

远程 (Claude.ai) 不使用 Docker

AUTH_ENABLED=true 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 sse --port 3000

重要： 当在反向代理（Caddy、nginx 等）后面运行时，您必须将 MCP_ISSUER_URL（或 --issuer-url）设置为您的公共 HTTPS URL。否则，OAuth 元数据将广播 http://localhost:3000，导致客户端无法进行身份验证。

详情请参阅安装指南。

架构

┌─────────────────────────────────────────────────────────────────┐
│                         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 服务器编排多个 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
AUTH_ENABLED=true MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=$MCP_CLIENT_SECRET \
  openclaw-mcp --transport sse

配置 CORS 以限制访问：

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

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

要求

Node.js ≥ 20

运行启用了 HTTP API 的 OpenClaw 网关：

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

许可证

MIT

作者

由 Tomáš Grasl 创建

openclaw-mcp