OpenClaw 陞級與 QQ Bot 接入完整指南

前言

環境信息

• 繫統: macOS 15.3.1 (arm64)
• Node.js: v25.2.1
• 安裝方式: npm 全局安裝
• 原版本: Clawdbot 2026.1.24-3
• 目標版本: OpenClaw 2026.2.3-1

第一步：卸載 Clawdbot

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 服務

安裝 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 問題現象

Control UI assets not found. Build them with pnpm ui:build

4.2 問題原因

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

方式一：使用命令打開（推薦）
openclaw dashboard
會自動打開帶 token 的 URL
方式二：手動穫取 token
openclaw config get gateway.auth.token

第五步：接入 QQ Bot

5.1 安裝 QQ Bot 插件

安裝 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 開放平颱憑證

1. 訪問 QQ 開放平颱: https://q.qq.com
2. 註冊開髮者賬號併完成審核
3. 創建一箇機器人應用（註意：選擇機器人應用，不是小程序）
4. 在"開髮管理"頁麵穫取：

- 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
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 配置沙箱環境

1. 登録 https://q.qq.com/#/app/bot
2. 進入你的機器人管理頁麵
3. 找到"沙箱配置"部分
4. 添加測試成員（你的 QQ 號）或綁定測試頻道

6.2 使用方式

• 創建一箇 QQ 頻道
• 在沙箱配置中綁定頻道 ID
• 在頻道的文字子頻道中 @機器人
• 機器人會自動回覆

• 在手機 QQ 中進入群設置
• 找到"群機器人"菜單
• 添加你的機器人
• 在群中 @機器人進行對話

• 在沙箱配置中添加你的 QQ 號爲測試成員
• 在 QQ 中搜索機器人的 AppID 或名稱
• 直接髮送消息測試

6.3 QQ Bot 功能特性

• ✅ 支持私聊消息（C2C）
• ✅ 支持群聊 @消息
• ✅ 支持頻道消息
• ✅ 自動重連機製
• ✅ 消息去重
• ✅ 可自定義繫統提示詞

常見問題與解決方案

Q1: 控製麵闆顯示 "unauthorized: gateway token missing"

使用命令自動打開帶 token 的 URL
openclaw dashboard

Q2: QQ Bot 顯示 "not configured"

Q3: Gateway 無法連接到 QQ 服務器

1. 檢查網絡連接
2. 在 QQ 開放平颱添加服務器公網 IP 到白名單
3. 查看日誌排查具體錯誤：tail -f ~/.openclaw/logs/gateway.log

Q4: 陞級後舊服務衝突

openclaw doctor
rm -f ~/Library/LaunchAgents/com.clawdbot.gateway.plist
openclaw gateway restart

總結

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