OpenClaw-xiaozhi MCP Server

OpenClaw--xiaozhi MCP Server

OpenClaw-xiaozhi MCP Server 是一个基于 Model Context Protocol (MCP) 协议的智能桥接服务器，用于将用户意图通过 MCP 转发给 OpenClaw（贾维斯）AI 助手处理。支持异步任务处理、WebSocket 实时通信和任务完成回调通知。

📖 目录

• 功能特点
• 系统架构
• 环境要求
• 安装指南
• 配置说明
• 使用方法
• API 参考
• 部署选项
• 故障排除
• 许可证

✨ 功能特点

• 🚀 异步处理 - 立即返回"处理中"状态，不阻塞客户端
• 🔄 WebSocket 实时通信 - 与小智 MCP 服务器保持长连接
• 📬 回调通知 - 任务完成后自动通知用户
• 🛠️ 多工具支持 - 提供多种工具接口（ask_jarvis, execute_task, process_intent 等）
• 🔌 自动重连 - 连接断开后自动重连，支持指数退避
• 📊 完整 MCP 协议 - 支持 JSON-RPC 2.0 和 MCP 2024-11-05 协议
• 💼 生产就绪 - 支持 Windows 服务、任务计划程序等多种部署方式

🏗️ 系统架构

┌─────────────────┐     ┌─────────────────────┐     ┌─────────────────┐
│  MCP 客户端     │────▶│  OpenClaw MCP       │────▶│  小智 MCP       │
│  (Claude 等)    │◀────│  Server (本服务)    │◀────│  WebSocket      │
└─────────────────┘     └─────────────────────┘     └─────────────────┘
                                │
                                ▼
                        ┌─────────────────┐
                        │  OpenClaw       │
                        │  (贾维斯 AI)    │
                        └─────────────────┘

工作流程

1. MCP 客户端发送意图
         │
         ▼
2. MCP Server 立即返回 task_id（状态：processing）
         │
         ▼
3. 异步发送给 OpenClaw 处理
         │
         ▼
4. OpenClaw 处理完成后通过 WebSocket 回调
         │
         ▼
5. 客户端可通过 get_task_result 查询结果

📋 环境要求

必需软件

可选软件（用于生产部署）

Python 依赖

📦 安装指南

方法一：源码安装（推荐）

# 1. 克隆或下载项目
cd C:\Users\user\Desktop\openclaw-mcp-server

# 2. 创建虚拟环境
python -m venv venv

# 3. 激活虚拟环境（Windows）
venv\Scripts\activate

# 4. 安装依赖
pip install -r requirements.txt

方法二：使用 install-startup.bat

# 双击运行或命令行执行
install-startup.bat

⚙️ 配置说明

1. 环境变量配置

复制 .env.example 为 .env：

copy .env.example .env

编辑 .env 文件，设置您的 Token：

# OpenClaw MCP Token
# 从 wss://api.xiaozhi.me/mcp/?token=xxx 中获取
OPENCLAW_TOKEN=your_token_here

2. 获取 Token

1. 访问小智 MCP 平台
2. 创建您的 Agent
3. 复制包含 token 的 WebSocket URL
4. 提取 token= 后面的值填入 .env

3. MCP 客户端配置

Claude Desktop 配置

编辑 Claude Desktop 配置文件（通常位于 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "openclaw": {
      "command": "python",
      "args": ["C:/Users/user/Desktop/openclaw-mcp-server/server.py"],
      "env": {
        "OPENCLAW_TOKEN": "your_token_here"
      }
    }
  }
}

其他 MCP 客户端

{
  "mcpServers": {
    "openclaw": {
      "command": "path/to/your/python",
      "args": ["path/to/openclaw-mcp-server/server.py"],
      "env": {
        "OPENCLAW_TOKEN": "your_token"
      }
    }
  }
}

🚀 使用方法

启动服务器

# 激活虚拟环境
venv\Scripts\activate

# 运行服务器
python server.py

使用 run.bat 脚本

# 直接运行
run.bat

测试连接

# 运行测试脚本
python test_mcp_full.py

📡 API 参考

工具列表

1. process_intent

发送用户意图并立即返回任务 ID（异步处理）。

参数：

请求示例：

{
  "intent": "帮我写一封邮件",
  "context": {
    "tone": "formal",
    "recipient": "client"
  }
}

响应示例：

{
  "status": "processing",
  "task_id": "task_1",
  "message": "意图已接收，正在处理中...",
  "intent_preview": "帮我写一封邮件"
}

2. get_task_result

查询任务处理结果。

参数：

请求示例：

{"task_id": "task_1"}

响应示例（完成）：

{
  "status": "completed",
  "result": {
    "content": "尊敬的客户，..."
  }
}

响应示例（处理中）：

{
  "status": "processing",
  "message": "任务仍在处理中，请稍后查询"
}

3. ask_jarvis

向贾维斯提问获取智能回答。

参数：

4. execute_task

让贾维斯执行特定任务。

参数：

5. get_status

获取贾维斯当前状态。

响应示例：

{
  "name": "贾维斯",
  "status": "online",
  "version": "1.0.0",
  "capabilities": [
    "自然语言理解",
    "任务执行",
    "信息查询",