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 | 3.9+ | 推荐 Python 3.11+ | | pip | 21.0+ | Python 包管理器 |

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

| 软件 | 用途 | |------|------| | Windows 10/11 | 运行环境 | | PowerShell 5.1+ | 运行安装脚本 |

Python 依赖

| 包名 | 版本 | 用途 | |------|------|------| | mcp | >=1.0.0 | MCP 协议实现 | | websockets | >=12.0 | WebSocket 通信 | | python-dotenv | >=1.0.0 | 环境变量管理 |

📦 安装指南

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

# 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

访问小智 MCP 平台
创建您的 Agent
复制包含 token 的 WebSocket URL
提取 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 | string | ✅ | 用户意图或请求内容 | | context | object | ❌ | 可选的上下文信息 |

请求示例：

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

响应示例：

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

2. get_task_result

查询任务处理结果。

参数： | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | task_id | string | ✅ | 任务 ID（由 process_intent 返回） |

请求示例：

{"task_id": "task_1"}

响应示例（完成）：

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

响应示例（处理中）：

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

3. ask_jarvis

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

参数： | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | question | string | ✅ | 要问的问题 | | context | object | ❌ | 可选的上下文信息 |

4. execute_task

让贾维斯执行特定任务。

参数： | 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | task_description | string | ✅ | 任务描述 | | parameters | object | ❌ | 任务参数 |

5. get_status

获取贾维斯当前状态。

响应示例：

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

🖥️ 部署选项

方案一：Windows 服务（推荐用于生产环境）

特点：

✅ 最稳定，系统级服务
✅ 开机自动启动
✅ 进程崩溃自动重启
✅ 完善的日志管理
⚠️ 需要管理员权限

安装步骤：

右键点击 install-service.ps1
选择 "以管理员身份运行"
按提示完成安装

管理命令：

# 启动服务
net start JarvisMCPBridge

# 停止服务
net stop JarvisMCPBridge

# 查看状态
sc query JarvisMCPBridge

# 查看日志
Get-Content service.log -Tail 50

# 卸载服务（管理员）
.\uninstall-service.ps1

方案二：任务计划程序（适合个人使用）

特点：

✅ 无需管理员权限
✅ 用户登录时自动启动
✅ 进程崩溃自动重启

安装步骤：

双击运行 install-task.ps1
按提示完成安装

管理命令：

# 启动任务
Start-ScheduledTask -TaskName JarvisMCPBridge_AutoStart

# 停止任务
Stop-ScheduledTask -TaskName JarvisMCPBridge_AutoStart

# 查看状态
Get-ScheduledTask -TaskName JarvisMCPBridge_AutoStart

方案三：开机启动文件夹（简单测试）

步骤：

按 Win + R
输入 shell:startup
创建 start-service.bat 的快捷方式

部署方案对比

| 特性 | Windows 服务 | 任务计划 | 启动文件夹 | |------|-------------|---------|-----------| | 管理员权限 | 需要 | 不需要 | 不需要 | | 开机启动 | ✅ | ✅ (登录时) | ✅ (登录时) | | 自动重启 | ✅ | ✅ | ❌ | | 日志管理 | ✅ | ⚠️ | ❌ | | 稳定性 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | | 推荐场景 | 生产环境 | 个人使用 | 临时测试 |

🐛 故障排除

常见问题

1. OPENCLAW_TOKEN 未设置

错误信息：

ValueError: 请设置 OPENCLAW_TOKEN 环境变量

解决方案：

确保 .env 文件存在于项目根目录
检查 .env 文件中 OPENCLAW_TOKEN 是否正确设置

2. WebSocket 连接失败

错误信息：

连接失败：...

解决方案：

检查网络连接
验证 Token 是否有效
检查防火墙设置

3. 依赖安装失败

解决方案：

# 升级 pip
python -m pip install --upgrade pip

# 重新安装依赖
pip install -r requirements.txt --force-reinstall

4. 服务无法启动

诊断步骤：

# 查看详细错误
sc qc JarvisMCPBridge

# 手动测试运行
cd C:\Users\user\Desktop\openclaw-mcp-server
venv\Scripts\activate
python bridge.py

日志查看

# 查看服务日志
Get-Content service.log -Tail 100

# 持续跟踪日志
Get-Content service.log -Wait -Tail 20

检查 Python 环境

# 确认 Python 路径
where python

# 确认虚拟环境激活
echo %VIRTUAL_ENV%

# 检查已安装的包
pip list | Select-String "websockets|mcp|dotenv"

📁 项目结构

openclaw-mcp-server/
├── server.py                 # MCP 服务器主程序
├── bridge.py                 # 小智桥接器（完整 MCP 协议）
├── openclaw_client.py        # OpenClaw WebSocket 客户端
├── tools.py                  # MCP 工具定义
├── config.py                 # 配置管理
├── requirements.txt          # Python 依赖
├── .env                      # 环境变量（需自行创建）
├── .env.example              # 环境变量示例
├── manifest.json             # 项目清单
├── mcp-client-config.json    # MCP 客户端配置示例
│
├── run.bat                   # 快速运行脚本
├── start-service.bat         # 服务启动脚本
├── install-service.ps1       # 安装 Windows 服务
├── uninstall-service.ps1     # 卸载服务
├── install-task.ps1          # 安装任务计划
├── install-startup.bat       # 快速安装脚本
│
├── test_client.py            # 客户端测试
├── test_mcp_full.py          # 完整 MCP 测试
│
├── README.md                 # 本文档
├── SERVICE_GUIDE.md          # 服务部署指南
├── SETUP_COMPLETE.md         # 安装完成说明
└── TEST_REPORT.md            # 测试报告

🔧 开发指南

添加新工具

在 tools.py 中添加新的工具定义：

@mcp.tool()
def your_new_tool(param1: str, param2: int = 0) -> dict:
    """
    工具描述
    
    Args:
        param1: 参数 1 说明
        param2: 参数 2 说明
    
    Returns:
        返回结果
    """
    # 实现逻辑
    return {"result": "success"}

调试模式

# 启用详细日志
python -u server.py 2>&1 | tee debug.log

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

如有问题，请提交 Issue 或联系维护者。

OpenClaw--xiaozhi MCP Server

📖 目录

✨ 功能特点

🏗️ 系统架构

工作流程

📋 环境要求

必需软件

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

Python 依赖

📦 安装指南

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

方法二：使用 install-startup.bat

⚙️ 配置说明

1. 环境变量配置

2. 获取 Token

3. MCP 客户端配置

Claude Desktop 配置

其他 MCP 客户端

🚀 使用方法

启动服务器

使用 run.bat 脚本

测试连接

📡 API 参考

工具列表

1. process_intent

2. get_task_result

3. ask_jarvis

4. execute_task

5. get_status

🖥️ 部署选项

方案一：Windows 服务（推荐用于生产环境）

方案二：任务计划程序（适合个人使用）

方案三：开机启动文件夹（简单测试）

部署方案对比

🐛 故障排除

常见问题

1. OPENCLAW_TOKEN 未设置

2. WebSocket 连接失败

3. 依赖安装失败

4. 服务无法启动

日志查看

检查 Python 环境

📁 项目结构

🔧 开发指南

添加新工具

调试模式

📄 许可证

🤝 贡献

📞 支持

Install Package (if required)

Cursor configuration (mcp.json)