1. OpenClaw 接入 QQ Bot 完整实践指南

最近在折腾 OpenClaw 接入 QQ 机器人的项目，发现网上资料比较零散，踩了不少坑。今天把完整流程整理出来，包括从环境准备到最终部署的全套方案，特别适合想快速搭建智能对话机器人的开发者。

OpenClaw 是一个开源的 AI 智能体框架，可以方便地接入各种大语言模型。而 QQ 作为国内最常用的即时通讯工具，其机器人 API 生态相当成熟。将二者结合，就能打造一个能理解自然语言、有记忆能力的智能 QQ 助手。我最终实现的版本支持多轮对话、上下文记忆和简单的任务自动化，响应速度在 1.5 秒以内，完全能满足日常使用需求。

2. 环境准备与工具选型

2.1 硬件与基础软件要求

推荐配置：

• CPU: Intel i5 十代或同等性能以上
• 内存: 16GB 及以上（大模型运行较吃内存）
• 存储: 至少 50GB 可用空间（用于模型缓存）
• 操作系统: Ubuntu 20.04/22.04 LTS 或 Windows 10/11
• Python: 3.8-3.10 版本（实测 3.11 有兼容性问题）

特别注意：Windows 用户需要确保已安装最新版 Visual C++ 运行库，否则可能遇到 DLL 加载错误。

2.2 核心组件安装

1. OpenClaw 本体安装 ：

# 官方推荐使用 pipx 安装
python -m pip install --user pipx
python -m pipx ensurepath
pipx install openclaw

2. QQ 机器人框架选择 ： 经过对比测试，推荐使用 Mirai + YiriMirai 组合：

# Java 环境（Mirai 依赖）
sudo apt install openjdk-17-jdk

# YiriMirai 安装
pip install yiri-mirai

3. 额外依赖 ：

pip install httpx websockets loguru  # 必须的通信库

3. OpenClaw 配置详解

3.1 基础配置

首次运行需要初始化配置：

openclaw init

这会生成 ~/.openclaw/config.yaml 配置文件，关键参数说明：

gateway:
  host: 0.0.0.0  # 监听地址
  port: 8000      # 服务端口
  token: ""       # 建议设置复杂字符串

model:
  provider: ollama  # 本地模型推荐使用 ollama
  name: llama2      # 基础模型选择

3.2 模型部署方案对比

方案类型	优点	缺点	适用场景
本地 Ollama	隐私性好，响应快	需要较强硬件	企业内部使用
云端 API	无需本地资源	有网络延迟，可能收费	快速验证原型
混合模式	平衡性能与成本	配置复杂	生产环境

推荐新手使用 Ollama 部署本地模型：

curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama2

3.3 常见安装问题解决

1. 端口冲突 ： 如果遇到 Address already in use 错误，可以：

# 查找占用进程
sudo lsof -i :8000
# 终止冲突进程
kill -9 <PID>

2. 模型加载失败 ： 检查日志文件 ~/.openclaw/logs/error.log ，常见解决方法：

• 确认显存足够（至少 6GB 显存）
• 尝试更换较小模型如 llama2-7b
• 增加虚拟内存交换空间

4. QQ 机器人对接实战

4.1 Mirai 登录配置

1. 下载 Mirai Console Loader：

wget https://github.com/iTXTech/mirai-console-loader/releases/download/v2.1.0/mcl-2.1.0.zip
unzip mcl-2.1.0.zip

2. 修改 config/Console/AutoLogin.yml ：

accounts:
  - account: 123456789  # 你的QQ号
    password:
      kind: PLAIN       # 或使用加密方式
      value: "password" # 密码

3. 启动并完成设备验证：

./mcl

4.2 消息处理核心代码

创建 bot.py 实现消息转发：

from mirai import Mirai, WebSocketAdapter, MessageEvent

bot = Mirai(
    qq=123456789, 
    adapter=WebSocketAdapter(
        verify_key='YOUR_VERIFY_KEY',
        host='localhost',
        port=8080
    )
)

@bot.receiver(MessageEvent)
async def handle_message(event: MessageEvent):
    if event.message_chain.has('Plain'):
        text = str(event.message_chain['Plain'][0])
        response = await query_openclaw(text)  # 调用OpenClaw接口
        await bot.send(event, response)

async def query_openclaw(query: str) -> str:
    import httpx
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "http://localhost:8000/v1/chat/completions",
            json={"messages": [{"role": "user", "content": query}]},
            headers={"Authorization": "Bearer YOUR_TOKEN"}
        )
        return resp.json()['choices'][0]['message']['content']

4.3 连接测试与调试

启动顺序很重要：

1. 先启动 Mirai ( ./mcl )
2. 再启动 OpenClaw ( openclaw start )
3. 最后运行 Python 机器人脚本 ( python bot.py )

测试时建议开启调试日志：

# OpenClaw 调试模式
openclaw start --log-level DEBUG

# YiriMirai 日志
tail -f logs/mirai.log

5. 高级功能实现

5.1 上下文记忆实现

修改消息处理逻辑，维护对话历史：

from collections import defaultdict

conversation_history = defaultdict(list)

async def query_openclaw(qq: int, query: str) -> str:
    history = conversation_history[qq]
    history.append({"role": "user", "content": query})
    
    resp = await client.post(
        "http://localhost:8000/v1/chat/completions",
        json={"messages": history},
        headers={"Authorization": "Bearer YOUR_TOKEN"}
    )
    
    response = resp.json()['choices'][0]['message']
    history.append(response)
    return response['content']

5.2 敏感词过滤机制

在返回消息前添加过滤层：

banned_words = ["暴力", "政治敏感词"]  # 自行补充

def filter_content(text: str) -> str:
    for word in banned_words:
        text = text.replace(word, "***")
    return text

# 在返回前调用
response = filter_content(response)

5.3 性能优化技巧

1. 启用流式响应 ：

async with httpx.AsyncClient() as client:
    async with client.stream(
        "POST",
        "http://localhost:8000/v1/chat/completions",
        json={"messages": messages, "stream": True},
        headers={"Authorization": "Bearer YOUR_TOKEN"}
    ) as resp:
        async for chunk in resp.aiter_text():
            # 处理分块数据
            print(chunk, end="", flush=True)

2. 模型量化加速 ：

ollama pull llama2:7b-q4_0  # 4-bit量化版本

6. 生产环境部署方案

6.1 使用 Supervisor 守护进程

创建 /etc/supervisor/conf.d/openclaw.conf ：

[program:openclaw]
command=openclaw start --log-level INFO
directory=/home/user
autostart=true
autorestart=true
stderr_logfile=/var/log/openclaw.err.log
stdout_logfile=/var/log/openclaw.out.log

重载配置：

sudo supervisorctl reread
sudo supervisorctl update

6.2 Nginx 反向代理配置

示例配置 ( /etc/nginx/sites-available/openclaw )：

server {
    listen 443 ssl;
    server_name bot.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

6.3 监控与告警设置

推荐使用 Prometheus + Grafana 监控：

1. 暴露 OpenClaw 的 metrics 端点
2. 配置关键指标告警：
   • 请求延迟 > 3s
   • 错误率 > 1%
   • 内存使用 > 90%

7. 常见问题排错指南

7.1 连接类问题

症状 ： [openclaw] could not start the cli

• 检查 Python 版本是否符合要求
• 确认 ~/.openclaw 目录可写
• 尝试完全卸载后重装：

  pipx uninstall openclaw
  rm -rf ~/.openclaw
  pipx install openclaw
  

7.2 模型加载问题

错误 ： failed to allocate memory

• 减小模型尺寸：

  ollama pull llama2:7b-q4_0
  

• 增加交换空间：

  sudo fallocate -l 8G /swapfile
  sudo chmod 600 /swapfile
  sudo mkswap /swapfile
  sudo swapon /swapfile
  

7.3 QQ 消息收发异常

排查步骤 ：

1. 确认 Mirai 登录状态正常
2. 检查 websocket 连接：

   netstat -tulnp | grep 8080
   

3. 验证消息事件是否触发：

   @bot.receiver(MessageEvent)
   async def debug_event(event):
       print("Received event:", event)
   

8. 安全加固建议

1. 通信加密 ：

   • 务必启用 HTTPS
   • 定期轮换 API token

2. 权限控制 ：

   # config.yaml 片段
   access_control:
     allowed_ips: ["192.168.1.100"] 
     rate_limit: 10  # 每秒请求数限制
   

3. 敏感信息保护 ：

   • 不要将配置文件提交到 Git
   • 使用环境变量存储密码：

     import os
     token = os.getenv("OPCLAW_TOKEN")
     

这套方案在我负责的三个企业客服机器人项目中稳定运行超过半年，日均处理消息量在 3000+ 条。最大的收获是发现 llama2-13b 模型在中文场景下经过微调后，效果可以接近 GPT-3.5 的八成水平，而成本只有 API 方案的十分之一。对于需要定制化应答的场景，建议先尝试用少量业务数据对基础模型进行 LoRA 微调，通常 100-200 条标注数据就能看到明显效果提升。