• 当前位置：首页
  • 技术
  • OpenClaw 升级与 QQ Bot 接入完整指南

OpenClaw 升级与 QQ Bot 接入完整指南

2026-02-07 09:16:56
技术博客
原创
38
摘要：详细记录从 Clawdbot 迁移到 OpenClaw 的完整过程，包括升级、故障排查，以及如何接入 QQ 开放平台机器人的实战指南。

OpenClaw 升级与 QQ Bot 接入完整指南

> 从 Clawdbot 迁移到 OpenClaw，并成功接入 QQ 开放平台机器人

前言

OpenClaw（前身为 Clawdbot）是一个开源的 AI 助手框架，支持多平台消息集成。本文记录了从 Clawdbot 迁移到 OpenClaw 的完整过程，以及如何接入 QQ 开放平台机器人，希望能帮助到有类似需求的开发者。

环境信息

  • 系统: macOS 15.3.1 (arm64)
  • Node.js: v25.2.1
  • 安装方式: npm 全局安装
  • 原版本: Clawdbot 2026.1.24-3
  • 目标版本: OpenClaw 2026.2.3-1

第一步：卸载 Clawdbot

首先需要卸载旧的 Clawdbot，为 OpenClaw 让路。

1.1 检查已安装的版本

检查 clawdbot 是否存在

which clawdbot

输出: /opt/homebrew/bin/clawdbot


检查 openclaw 是否已安装

which openclaw

输出: /opt/homebrew/bin/openclaw


查看全局安装的包

npm list -g clawdbot
npm list -g openclaw

1.2 卸载 Clawdbot

卸载 clawdbot 全局包

npm uninstall -g clawdbot

成功移除 673 个包

1.3 验证卸载结果

验证 clawdbot 已被移除

which clawdbot

输出: clawdbot not found


确认 openclaw 仍然存在

which openclaw

输出: /opt/homebrew/bin/openclaw

openclaw --version

输出: 2026.1.30

第二步：启动 OpenClaw 服务

2.1 安装 Gateway 服务

OpenClaw 使用 LaunchAgent 来管理 Gateway 服务。 
安装 gateway 服务

openclaw gateway install

输出: Installed LaunchAgent: /Users/xxx/Library/LaunchAgents/ai.openclaw.gateway.plist


启动 gateway 服务

openclaw gateway start

输出: Restarted LaunchAgent: gui/501/ai.openclaw.gateway

2.2 检查服务状态

查看完整状态

openclaw status

关键信息：

  • Dashboard: http://127.0.0.1:18789/
  • Gateway: ws://127.0.0.1:18789
  • Gateway service: LaunchAgent installed · loaded · running

第三步：升级 OpenClaw

3.1 检查更新状态

查看当前版本和可用更新

openclaw update status

输出示例：

Install: pnpm
Channel: stable (config)
Update: available · pnpm · npm update 2026.2.3-1

3.2 执行升级

升级到最新版本

openclaw update

升级过程：

  • 更新耗时：约 66 秒
  • 升级前版本：2026.1.30
  • 升级后版本：2026.2.3-1

3.3 重启服务

手动重启 gateway 服务

openclaw gateway restart

验证新版本

openclaw --version

输出: 2026.2.3-1

第四步：解决控制面板访问问题

4.1 问题现象

访问 http://127.0.0.1:18789/ 时出现错误： 
Control UI assets not found. Build them with pnpm ui:build

4.2 问题原因

升级后残留了旧的 Clawdbot Gateway 服务，导致与 OpenClaw Gateway 冲突。

4.3 解决方案

运行 doctor 检查问题

openclaw doctor

清理旧的 clawdbot 服务

rm -f ~/Library/LaunchAgents/com.clawdbot.gateway.plist
launchctl bootout gui/$(id -u)/com.clawdbot.gateway

重启 openclaw gateway

openclaw gateway restart

验证控制面板

curl -s http://127.0.0.1:18789/ | head -5

成功后应该能看到 HTML 页面内容。

4.4 获取访问 Token

控制面板需要认证 token： 
方式一：使用命令打开（推荐）

openclaw dashboard

会自动打开带 token 的 URL


方式二：手动获取 token

openclaw config get gateway.auth.token

第五步：接入 QQ Bot

5.1 安装 QQ Bot 插件

OpenClaw 通过插件系统支持 QQ 开放平台机器人。 
安装 QQ Bot 插件

openclaw plugins install @openclaw-china/qqbot

重启 gateway 加载插件

openclaw gateway restart

等待几秒后检查插件状态

sleep 3
openclaw plugins list | grep qq

成功后会看到：

QQ Bot | qqbot | loaded | ~/.openclaw/extensions/qqbot/dist/index.js | 0.1.0

5.2 获取 QQ 开放平台凭证

在配置 OpenClaw 之前，需要先从 QQ 开放平台获取凭证：
  1. 访问 QQ 开放平台: https://q.qq.com
  2. 注册开发者账号并完成审核
  3. 创建一个机器人应用（注意：选择机器人应用，不是小程序）
  4. 在"开发管理"页面获取：
- AppID: 你的机器人 ID

- AppSecret: 你的机器人密钥（也叫 ClientSecret）

5.3 配置 QQ Bot 凭证

有三种配置方式，推荐使用命令行方式： 方式一：命令行配置（推荐） 
使用 AppID:AppSecret 格式配置

openclaw channels add --channel qqbot --token "你的AppID:你的AppSecret"
方式二：交互式配置 
启动交互式配置向导

openclaw channels add

选择 "QQ Bot"


按提示输入 AppID 和 AppSecret
方式三：手动编辑配置文件

编辑 ~/.openclaw/openclaw.json，在 channels 部分添加：

{
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "你的AppID",
      "clientSecret": "你的AppSecret"
    }
  }
}

5.4 验证 QQ Bot 连接

配置完成后，重启 gateway 并检查连接状态： 
重启 gateway

openclaw gateway restart

等待几秒后检查状态

sleep 5
openclaw channels status

成功后会显示：

- QQ Bot default: enabled, configured

查看日志确认连接：

查看最近的日志

tail -50 ~/.openclaw/logs/gateway.log | grep qqbot

成功连接的日志示例：

[qqbot] starting gateway for account default
[qqbot] connecting gateway: wss://api.sgroup.qq.com/websocket
[qqbot] gateway socket opened
[qqbot] gateway ready

第六步：在 QQ 中使用机器人

6.1 配置沙箱环境

在正式使用前，需要在 QQ 开放平台配置沙箱环境：
  1. 登录 https://q.qq.com/#/app/bot
  2. 进入你的机器人管理页面
  3. 找到"沙箱配置"部分
  4. 添加测试成员（你的 QQ 号）或绑定测试频道

6.2 使用方式

QQ Bot 支持三种使用场景： 1. QQ 频道（推荐）
  • 创建一个 QQ 频道
  • 在沙箱配置中绑定频道 ID
  • 在频道的文字子频道中 @机器人
  • 机器人会自动回复
2. QQ 群聊
  • 在手机 QQ 中进入群设置
  • 找到"群机器人"菜单
  • 添加你的机器人
  • 在群中 @机器人进行对话
3. 私聊
  • 在沙箱配置中添加你的 QQ 号为测试成员
  • 在 QQ 中搜索机器人的 AppID 或名称
  • 直接发送消息测试

6.3 QQ Bot 功能特性

  • ✅ 支持私聊消息（C2C）
  • ✅ 支持群聊 @消息
  • ✅ 支持频道消息
  • ✅ 自动重连机制
  • ✅ 消息去重
  • ✅ 可自定义系统提示词

常见问题与解决方案

Q1: 控制面板显示 "unauthorized: gateway token missing"

原因: 访问控制面板时缺少认证 token。 解决方案: 
使用命令自动打开带 token 的 URL

openclaw dashboard

Q2: QQ Bot 显示 "not configured"

原因: AppID 和 AppSecret 没有正确保存到配置文件。 解决方案: 手动编辑 ~/.openclaw/openclaw.json，确保 channels.qqbot 部分包含 appId 和 clientSecret。

Q3: Gateway 无法连接到 QQ 服务器

原因: 网络问题或 IP 白名单限制。 解决方案:
  1. 检查网络连接
  2. 在 QQ 开放平台添加服务器公网 IP 到白名单
  3. 查看日志排查具体错误：tail -f ~/.openclaw/logs/gateway.log

Q4: 升级后旧服务冲突

原因: Clawdbot 的 LaunchAgent 服务未清理。 解决方案: 
openclaw doctor
rm -f ~/Library/LaunchAgents/com.clawdbot.gateway.plist
openclaw gateway restart

总结

本文详细记录了从 Clawdbot 迁移到 OpenClaw 的完整过程，以及如何接入 QQ 开放平台机器人。主要步骤包括：
  1. 卸载 Clawdbot: 使用 npm uninstall 清理旧版本
  2. 启动 OpenClaw: 安装并启动 Gateway 服务
  3. 升级到最新版: 从 2026.1.30 升级到 2026.2.3-1
  4. 解决冲突: 清理旧服务，修复控制面板访问问题
  5. 安装 QQ 插件: 使用 @openclaw-china/qqbot 插件
  6. 配置凭证: 添加 QQ 开放平台的 AppID 和 AppSecret
  7. 验证连接: 确认 QQ Bot 成功连接到 WebSocket 服务

实用命令速查

查看服务状态

openclaw status

查看 channels 状态

openclaw channels status

查看插件列表

openclaw plugins list

查看日志

tail -f ~/.openclaw/logs/gateway.log

重启 gateway

openclaw gateway restart

打开控制面板

openclaw dashboard

参考资源

  • OpenClaw 官网: https://openclaw.ai
  • OpenClaw 文档: https://docs.openclaw.ai
  • QQ 开放平台: https://q.qq.com
  • OpenClaw China 插件: https://github.com/BytePioneer-AI/openclaw-china
发表评论
评论通过审核后显示。
文章分类
联系我们
danmaku
流量统计