OpenClaw本地配置QQ Bot的使用流程
發(fā)布時(shí)間：2026-03-18 10:58:58 作者：kishu_iOS&AI 
我要評(píng)論
我要評(píng)論本文檔詳細(xì)介紹了在Mac本地環(huán)境配置OpenClaw與QQ機(jī)器人對(duì)接的完整流程,文中通過示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧
本文檔用于在本地 Mac 環(huán)境把 OpenClaw + QQ Bot 打通，并完成：
- QQ 機(jī)器人接入 OpenClaw
- 多賬號(hào)配置（可選）
- 指定 QQ Bot 路由到指定 Agent
- 啟動(dòng)后可直接在 QQ 對(duì)話觸發(fā)對(duì)應(yīng) Agent
1. 前置條件
確保以下條件已滿足：
- 已安裝 OpenClaw CLI
- 已有可用的 QQ 機(jī)器人 AppID 與 AppSecret
- 本機(jī)可訪問 registry.npmjs.org、bots.qq.com、api.sgroup.qq.com
可先檢查版本：
openclaw --version node -v npm -v
2. 安裝 QQ Bot 插件
openclaw plugins install @tencent-connect/openclaw-qqbot@latest
安裝后可確認(rèn)插件已加載：
openclaw plugins list | rg -i qqbot
3.（可選）修復(fù) npm TLS 證書問題
如果安裝插件時(shí)報(bào)錯(cuò) UNABLE_TO_GET_ISSUER_CERT_LOCALLY，執(zhí)行：
mkdir -p ~/.certs security find-certificate -a -p /System/Library/Keychains/SystemRootCertificates.keychain > ~/.certs/macos-root-certs.pem security find-certificate -a -p /Library/Keychains/System.keychain > ~/.certs/macos-system-certs.pem cat ~/.certs/macos-root-certs.pem ~/.certs/macos-system-certs.pem > ~/.certs/macos-all-certs.pem npm config set cafile "$HOME/.certs/macos-all-certs.pem" npm config set strict-ssl true
然后重試插件安裝。
4. 把 QQ Token 存入 Keychain（推薦）
建議把憑據(jù)存 Keychain，不要把明文寫到文檔或腳本里。
4.1 概念澄清（重要）
AppID：QQ 開放平臺(tái)里的機(jī)器人 ID（純數(shù)字）AppSecret：機(jī)器人密鑰token（OpenClaw 命令里）：AppID:AppSecretaccountId（例如bot1）：OpenClaw 路由用的賬號(hào)標(biāo)識(shí)，不是密鑰
也就是說：bot1 不是 token，本質(zhì)是你在 --account 配置后用于路由匹配的賬號(hào) ID（插件會(huì)做小寫規(guī)范化）。
QQ Token 格式：
AppID:AppSecret
示例（會(huì)覆蓋同名項(xiàng)）：
security add-generic-password -a "$USER" -s "Key1" -w "APPID_1:APPSECRET_1" -U security add-generic-password -a "$USER" -s "Key2" -w "APPID_2:APPSECRET_2" -U
驗(yàn)證能讀到（只驗(yàn)證，不要泄漏到聊天記錄）：
security find-generic-password -a "$USER" -s "Key1" -w
5. 配置 QQ Bot 賬號(hào)到 OpenClaw
5.0 對(duì)應(yīng) QQ 開放平臺(tái)截圖
https://q.qq.com/qqbot/openclaw/
QQ 開放平臺(tái)“OpenClaw 原生接入流程”里的 3 條命令，含義如下：
- 安裝插件
openclaw plugins install @tencent-connect/openclaw-qqbot@latest
- 綁定當(dāng)前 QQ 機(jī)器人（
--token就是AppID:AppSecret）
openclaw channels add --channel qqbot --token "AppID:AppSecret"
- 重啟 OpenClaw 服務(wù)
openclaw gateway restart
補(bǔ)充說明：
- 如果是多機(jī)器人，建議加
--account，例如--account bot1 - 之后在
agents bind使用的是accountId（如bot1），不是 token - 截圖里如果出現(xiàn)過完整
AppSecret，建議在 QQ 開放平臺(tái)立即輪換（重置）AppSecret
5.1 單賬號(hào)
openclaw channels add \ --channel qqbot \ --account bot1 \ --token "$(security find-generic-password -a "$USER" -s "Key1" -w)"
5.2 多賬號(hào)
openclaw channels add \ --channel qqbot \ --account bot1 \ --token "$(security find-generic-password -a "$USER" -s "Key1" -w)" openclaw channels add \ --channel qqbot \ --account bot2 \ --token "$(security find-generic-password -a "$USER" -s "Key2" -w)"
查看已配置賬號(hào)：
openclaw channels list --json | sed -n '/^{/,$p' | jq '.chat.qqbot'注意：插件通常會(huì)把 accountId 規(guī)范成小寫，例如 Bot1 -> bot1。
6. 創(chuàng)建 Agent 并綁定到指定 QQ Bot
6.1 創(chuàng)建 Agent
openclaw agents add qq_agent_bot \ --non-interactive \ --workspace ~/.openclaw/workspace-qq_agent_bot \ --json openclaw agents add qq_agent_edit_bot \ --non-interactive \ --workspace ~/.openclaw/workspace-qq_agent_edit_bot \ --json
6.2 綁定路由（精準(zhǔn)綁定到賬號(hào)）
openclaw agents bind --agent qq_agent_bot --bind qqbot:bot1 --json openclaw agents bind --agent qq_agent_edit_bot --bind qqbot:bot2 --json
查看綁定結(jié)果：
openclaw agents bindings --json | sed -n '/^\\[/,$p' | jq '.'
如果之前綁過泛路由（qqbot），建議移除，避免沖突：
openclaw agents unbind --agent qq_agent_bot --bind qqbot --json
7. 重啟網(wǎng)關(guān)使配置生效
openclaw gateway restart
8. 驗(yàn)證是否真正打通
8.1 看配置層狀態(tài)
openclaw channels status
期望看到類似：
- QQ Bot bot1: enabled, configured
- QQ Bot bot2: enabled, configured
8.2 看運(yùn)行日志（最關(guān)鍵）
rg -n "qqbot:bot1|qqbot:bot2|READY|WebSocket connected|Access token obtained" \ ~/.openclaw/logs/gateway.log -S | tail -n 80
出現(xiàn)以下日志即表示在線：
- Access token obtained successfully
- WebSocket connected
- Dispatch event: t=READY 或 t=RESUMED
9. 日常運(yùn)維命令
# 查看所有 agent openclaw agents list # 查看綁定關(guān)系 openclaw agents bindings # 重啟網(wǎng)關(guān) openclaw gateway restart # 查看網(wǎng)關(guān)日志 tail -f ~/.openclaw/logs/gateway.log
10. 常見問題排查
Q1：插件安裝失敗，報(bào) TLS/證書錯(cuò)誤
- 參考本文第 3 節(jié)設(shè)置 npm cafile
- 確保 ~/.certs/macos-all-certs.pem 不是空文件
Q2：channels status提示很多 env var 缺失
- 這是當(dāng)前 shell 未加載對(duì)應(yīng)環(huán)境變量導(dǎo)致
- 若你依賴 ~/.zshrc + Keychain 注入，先執(zhí)行 source ~/.zshrc
Q3：已連上 QQ，但消息沒進(jìn)目標(biāo) Agent
優(yōu)先檢查：
- 是否綁定成了錯(cuò)誤的 accountId（大小寫）
- 是否還保留了泛路由 qqbot 搶路由
- openclaw agents bindings 是否存在精準(zhǔn)規(guī)則 qqbot:<accountId>
Q4：多賬號(hào)時(shí)默認(rèn)路由不明確
- 顯式給每個(gè) QQ Bot 配 agent bind
- 避免只依賴默認(rèn)路由
11. 最小可用流程（速記）
# 1) 安裝插件 openclaw plugins install @tencent-connect/openclaw-qqbot@latest # 2) 存 token 到 keychain（示例） security add-generic-password -a "$USER" -s "Key1" -w "APPID_1:APPSECRET_1" -U # 3) 配置頻道賬號(hào) openclaw channels add --channel qqbot --account bot1 --token "$(security find-generic-password -a "$USER" -s "Key1" -w)" # 4) 創(chuàng)建并綁定 agent openclaw agents add qq_agent_bot --non-interactive --workspace ~/.openclaw/workspace-qq_agent_bot openclaw agents bind --agent qq_agent_bot --bind qqbot:bot1 # 5) 重啟并看日志 openclaw gateway restart rg -n "qqbot:bot1|READY|WebSocket connected" ~/.openclaw/logs/gateway.log -S | tail -n 50
到此這篇關(guān)于OpenClaw本地配置QQ Bot的使用流程的文章就介紹到這了,更多相關(guān)OpenClaw 本地配置 QQ Bot內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！
相關(guān)文章
本文檔詳細(xì)介紹了在OpenClaw平臺(tái)上接入QQBot的完整實(shí)踐過程,包括QQ開放平臺(tái)賬號(hào)注冊(cè)、機(jī)器人創(chuàng)建、插件安裝與配置、啟動(dòng)與驗(yàn)證、常見問題解答等，本文通過實(shí)例代碼給大家講2026-03-09
