作者：騰訊QQ機(jī)器人團(tuán)隊(duì)
快速注冊一個(gè) QQBot
QQ 機(jī)器人開放平臺提供了快捷創(chuàng)建 QQ 機(jī)器人的通道，三步即可創(chuàng)建一個(gè)可用的 QQBot，用于接入 OpenClaw。
1. PC 端打開：https://q.qq.com/qqbot/openclaw/login.html，QQ 掃碼登錄。
2. 點(diǎn)擊創(chuàng)建機(jī)器人。點(diǎn)擊后會立刻成功，此時(shí) BOT 會給你 QQ 發(fā)一條成功消息，頭像昵稱可按用戶喜好自定義編輯。
3. 復(fù)制 AppID 和 AppSecret 到 ?? 部署地配置即可，配置成功后，即可通過 QQ 使喚你的 ??。
這個(gè) BOT 僅創(chuàng)建人可用，暫時(shí)不支持將 BOT 拉入QQ群內(nèi)。
機(jī)器人創(chuàng)建成功后，此時(shí)你的 BOT 還沒有“靈魂”，需要接入到你自己的 OpenClaw 運(yùn)行環(huán)境，這里也推薦使用騰訊云的 Lighthouse 接入。
• “云上養(yǎng)蝦”教程：??玩轉(zhuǎn) OpenClaw｜云上 OpenClaw(Clawdbot) 快速接入 QQ 指南
• OpenClaw 官方安裝教程：OpenClaw — Personal AI Assistant
其實(shí)也并不復(fù)雜，在終端執(zhí)行個(gè)命令，按部就班配置一些 model、skills、channel 即可。
QQ 作為 OpenClaw 的通訊渠道，需要在 OpenClaw 安裝配置 QQBot 插件，才能與 QQBot 通信。多數(shù)云平臺（如騰訊云）幫你簡化了該步驟，用戶僅需復(fù)制粘貼相關(guān)密鑰到云上的管理端頁面即可。以下內(nèi)容講述如何手動安裝 QQBot 插件與更新。
QQ Bot 插件消息收發(fā)能力總覽：
在原生 OpenClaw 中安裝 QQBot 插件
本文介紹在原生 OpenClaw 環(huán)境中安裝或升級 QQBot 插件的幾種常見方式。你可以根據(jù)自己的使用習(xí)慣，選擇遠(yuǎn)程一鍵執(zhí)行、本地腳本執(zhí)行，或手動安裝
QQBot 插件官方倉庫：
https://github.com/tencent-connect/openclaw-qqbot
歡迎大家前往查看最新代碼與更新說明，也歡迎通過 Issue 和 PR 提出問題反饋與改進(jìn)建議，共同完善插件能力與接入體驗(yàn)。
方式一：遠(yuǎn)程一鍵安裝升級（推薦）
適合希望快速完成安裝或升級的場景，無需手動 clone 倉庫。
首次安裝時(shí)，需提供 QQBot 通道憑證：
curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh \
| bash -s -- --appid YOUR_APPID --secret YOUR_SECRET
該命令會自動完成以下步驟：
• 下載安裝腳本
• 清理舊插件
• 安裝新插件
• 配置 QQBot 通道
• 啟動或重啟 OpenClaw 服務(wù)
完成后即可打開 QQ 開始使用。
如果此前已經(jīng)完成過通道配置，后續(xù)升級可直接執(zhí)行：
curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
說明：如果想要升級QQBot官方插件版本，也可以執(zhí)行該腳本，這個(gè)腳本是帶升級能力的，而且默認(rèn)行為是升級到 npm 上的 latest 版本。如果是想安裝指定版本，后面可以跟--version命令：
curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash -s -- --version 1.5.7 --appid YOUR_APPID --secret YOUR_SECRET
常用參數(shù)如下：
![50S0`HR]))40}R5$5S7R$70.png](http://objectnsg.oss-cn-beijing.aliyuncs.com/default/202603/16/202603162335271257356656.png)
方式二：源碼安裝升級
適合希望先查看倉庫內(nèi)容、在本地執(zhí)行腳本，或希望更靈活控制安裝流程的場景。
先拉取倉庫：
git clone https://github.com/tencent-connect/openclaw-qqbot.git
cd openclaw-qqbot
通過本地腳本進(jìn)行源碼安裝或升級（該腳本同樣具有升級到最新版本的能力）：
bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET
說明：腳本執(zhí)行到后面會讓選擇 是否后臺重啟 openclaw 網(wǎng)關(guān)服務(wù)？[Y/n]，一般選擇 Y。如果后臺啟動正常，會執(zhí)行 openclaw logs --follow 持續(xù)輸出 OpenClaw 運(yùn)行日志。后面看到有日志持續(xù)輸出代表已經(jīng)正常啟動了，不代表還沒升級完，可以 Ctrl+C 關(guān)掉前臺日志。
正常執(zhí)行腳本到最后會輸出日志：
方式三：npm方式手動安裝升級
適合希望完全手動控制安裝步驟，或需要排查安裝問題的場景。
安裝命令：
# （首次安裝可跳過）卸載qqbot舊插件，卸載openclaw-qqbot舊版本插件
openclaw plugins uninstall qqbot
openclaw plugins uninstall openclaw-qqbot
# 安裝openclaw-qqbot最新版本
openclaw plugins install @tencent-connect/openclaw-qqbot@latest
# 配置通道（首次安裝必做）
openclaw channels add --channel qqbot --token "AppID:AppSecret"
# 啟動 / 重啟服務(wù)
openclaw gateway restart
已安裝官方openclaw-qqbot，升級版本命令：
# 通過npm 包升級（適用于之前插件本身就是通過可更新來源安裝的情況：openclaw plugins install @tencent-connect/openclaw-qqbot）
openclaw plugins update openclaw-qqbot
# 啟動 / 重啟服務(wù)
openclaw gateway restart
安裝選擇建議
• 想快速安裝：優(yōu)先使用方式一：遠(yuǎn)程一鍵安裝升級
• 想先查看腳本再執(zhí)行：使用方式二：本地源碼安裝升級
• 想自行控制每一步：使用方式三：npm方式手動安裝升級
安裝結(jié)果檢查
QQBot 插件是否正常加載
安裝完成后，可通過以下命令檢查插件是否已成功加載：
openclaw plugins list | grep openclaw-qqbot
如果輸出中存在對應(yīng)插件條目，且狀態(tài)為 loaded，說明 QQBot 插件已經(jīng)安裝好了，而且已經(jīng)被 OpenClaw 成功加載。但并不能說明通道一定連上了。
QQBot 通道是否正常連通
執(zhí)行以下命令查看通道狀態(tài)：
openclaw channels status
openclaw channels status 中 QQ Bot 通道顯示為 enabled, configured, running，且機(jī)器人實(shí)際可以正常收發(fā)消息或 in/out 時(shí)間持續(xù)更新時(shí)，可認(rèn)為QQBot 通道已正常連通。
這里的 in:2m ago, out:2m ago 說明：
• in:2m ago：2 分鐘前還有入站消息
• out:2m ago：2 分鐘前還有出站消息
插件的能力及消息示例
OpenClaw QQBot 插件提供了富媒體收發(fā)支持，覆蓋圖片、語音、視頻、文件的雙向交互。需要聲明的是，QQ Bot 插件僅作為消息通道使用——負(fù)責(zé)在 QQ 與 OpenClaw 之間中轉(zhuǎn)消息。諸如圖像理解、語音轉(zhuǎn)錄、繪圖等功能，取決于您所配置的 AI 模型以及 OpenClaw 內(nèi)部已安裝的技能，而非本插件本身。
AI 能接收什么
除了接收日常的文本消息以外，QQBot 通道還支持接收多種媒體消息。
接收語音配置示例
其中語音消息（STT）需要單獨(dú)配置模型能力，用于語音轉(zhuǎn)文字后交給文本大模型處理，配置方式如下：
STT 支持兩級配置，按優(yōu)先級查找：channels.qqbot.stt（插件專屬）-> tools.media.audio.models[0]（框架級回退）。以框架級配置為例：
{
"tools": {
"media": {
"audio": {
"models": [
{ "provider": "xxx", "model": "模型名稱" }
]
}
}
}
}
這里的 provider 引用 models.providers 中的 key，自動繼承 baseUrl 和 apiKey，支持任何 OpenAI 兼容的 STT 接口，也可在條目中直接寫 baseUrl / apiKey 覆蓋。
另外，插件版本1.5.6已經(jīng)支持當(dāng) STT 未配置或轉(zhuǎn)寫失敗時(shí)，使用 QQ 平臺內(nèi)置 ASR 文本作為低置信度兜底結(jié)果，方便沒有STT模型的用戶可以使用QQ機(jī)器人平臺側(cè)提供的語音轉(zhuǎn)文本結(jié)果。
AI 能發(fā)送什么
除了常用的 markdown 消息、文本消息以外，QQBot 插件通道支持發(fā)送語音、文件、圖片、視頻等常用的多媒體消息。
發(fā)送語音配置示例
語音（TTS）需要單獨(dú)配置模型能力，把文字轉(zhuǎn)成語音通過 QQ 發(fā)給你。配置 TTS 后，AI 可以把文字變成語音消息發(fā)出來。比如讓它講個(gè)笑話，回復(fù)直接就是一條語音。
TTS 同樣支持兩級配置：channels.qqbot.tts（插件專屬）-> messages.tts（框架級回退）。以插件專屬配置為例：
{
"channels": {
"qqbot": {
"tts": {
"provider": "xxx",
"model": "模型名稱",
"voice": "模型名稱:音色名稱"
}
}
}
}
provider 引用 models.providers 中的 key，自動繼承 baseUrl 和 apiKey。可通過 voice 選擇音色，設(shè)置 enabled: false 可禁用。
另外如果沒有現(xiàn)成可使用的 TTS 模型，也可以使用 TTS/Edge（OpenClaw 原生支持的一種 TTS provider），配置如下（在messages里增加tts的配置）：
{
"messages": {
"tts": {
"auto": "inbound",
"provider": "edge",
"edge": {
"enabled": true,
"voice": "zh-CN-XiaoxiaoNeural",
"lang": "zh-CN"
}
}
}
}
驗(yàn)證通道發(fā)送圖片或者文件正常
可以用以下方式驗(yàn)證 QQ Bot 通道發(fā)送圖片/文件能力是否正常：發(fā)給模型一張圖片，讓模型把這張圖回給你。如果能正?；貜?fù)，說明通道能力正常。注意，生成圖片或者對文件進(jìn)行理解等都是 OpenClaw 自己的能力，需要配置對應(yīng)的模型或者 Skills，QQ Bot 插件只負(fù)責(zé)傳輸。
體驗(yàn)演示場景
以下是幾個(gè)可以直接復(fù)現(xiàn)的玩法：
如何配置 Skills
在騰訊云 Lighthouse 安裝 clawhub 的 Skills
在 Lighthouse 實(shí)例的應(yīng)用管理頁面上可以直接安裝 skills，如圖：
點(diǎn)擊頁面上【獲取更多 skills】的鏈接跳到開源社區(qū) ClawHub 的官網(wǎng)，選擇你需要的 skills。注意這里 skills 的名字，就是點(diǎn)擊跳轉(zhuǎn)某個(gè) skills 的頁面鏈接 URL 最后的內(nèi)容：
確定名字后，直接在 Lighthouse 應(yīng)用管理頁面上點(diǎn)擊【安裝技能】即可。
手動安裝 clawhub 的 Skills
如果想手動安裝 ClawHub 上的 skills，具體步驟如下：
# 1. 安裝 clawhub cli
npm i -g clawhub
# 2. 裝完確定下是否可用：
clawhub --help
# 3. 進(jìn)入 OpenClaw workspace
cd ~/.openclaw/workspace
# 4. 搜索 skill
clawhub search "你想要的功能關(guān)鍵詞"
# 5. 安裝 skill
clawhub install
# 6. 檢查是否識別到
openclaw skills list
openclaw skills check
# 7. 如需配置 API Key，則編輯配置文件
vi ~/.openclaw/openclaw.json
# 8. 重啟 gateway
openclaw gateway restart
# 9. 看日志
openclaw logs --follow
# 10. 檢查目前已經(jīng)安裝了哪些 skills
openclaw skills list --eligible
openclaw skills info <這里填 list="" skills="">
如果完成以上安裝后，agent 提示仍找不到對應(yīng) skills，可以通過和 agent 對話的方式讓 OpenClaw 分析問題并完成安裝：
也推薦大家遇到各種包括 skills 安裝在內(nèi)的問題時(shí)，嘗試習(xí)慣通過和 agent 交流，讓它幫你分析并解決問題。
手動安裝自己寫的 Skills
安裝自己寫的 skills，最主要的就是把你的 skills 建一個(gè)文件夾放在 ~/.openclaw/workspace/skills/ 目錄下。
這里提供了一個(gè)安裝 my-demo-skill 的簡單示例：
# 1. 創(chuàng)建 skills 目錄，假設(shè)這里的 skills 叫 my-demo-skill
mkdir -p ~/.openclaw/workspace/skills/my-demo-skill
# 2. 寫入 skills，或者把已經(jīng)寫好的 skills 放在對應(yīng)目錄下
cat > ~/.openclaw/workspace/skills/my-demo-skill/SKILL.md <<'SKILL_EOF'
---
name: my_demo_skill
description: A simple custom skill for testing.
---
# My Demo Skill
當(dāng)用戶要求測試自定義 skill 時(shí)，優(yōu)先遵循這里的說明。
觸發(fā)示例：
- “調(diào)用 my demo skill”
行為：
- 回復(fù)：“已命中 my_demo_skill”
SKILL_EOF
# 3. 讓 OpenClaw 重新發(fā)現(xiàn)這個(gè) skill，可以通過對話讓 agent “refresh skills”，或者直接重啟 gateway
openclaw gateway restart
openclaw skills list
openclaw skills info my_demo_skill
通過對話驗(yàn)證 my-demo-skill 觸發(fā)成功：
FAQ（持續(xù)更新）
Q：為什么一直輸出“你好，我不能提供相關(guān)信息”？
A：模型輸入輸出內(nèi)容會進(jìn)行安全審查，可以嘗試以下方法：
• 通過 /new 開啟新對話
• 更換模型后再試
Q：為什么設(shè)置好 QQ 機(jī)器人信息后，與機(jī)器人對話時(shí)小灰條提示“我的靈魂不在線”等錯(cuò)誤？
A1：如果是第一次配置，OpenClaw 與機(jī)器人建立聯(lián)系可能需要一點(diǎn)時(shí)間，可以嘗試重啟幾次 openclaw gateway restart
A2：如果原來已經(jīng)有機(jī)器人，又重新更換配置了新的APPID，如果機(jī)器人無法回復(fù)：
● 解決方式1：刪除 ~/.openclaw/qqbot/sessions/session-default.json 然后重啟
● 解決方式2：更新 QQBot 插件（見前文插件更新教程）
A3：如果一直提示此錯(cuò)誤，是因?yàn)闄C(jī)器人沒有在線，檢查機(jī)器人APPID和密鑰配置是否正常。
Q：機(jī)器人提示已經(jīng)被注銷怎么辦？
A：解決方案：檢查是否刪除了機(jī)器人，如果刪除了7天內(nèi)可以前往 QQ開放平臺 進(jìn)行恢復(fù)。
Q：為什么在群里面@機(jī)器人，遇到提示："該機(jī)器人當(dāng)前服務(wù)狀態(tài)異常，暫時(shí)無法回復(fù)消息"？創(chuàng)建的openclaw機(jī)器人是否支持加群？
A：因?yàn)閛penclaw機(jī)器人暫不支持加群，僅支持個(gè)人用戶私聊使用。如果有下一步支持計(jì)劃，會及時(shí)更新文檔通知大家。
Q：快速創(chuàng)建的openclaw機(jī)器人是否支持在開放平臺修改信息？
A：支持，方式如下：
Q：機(jī)器人為什么回復(fù)“401 not authorized”？
A：模型配置沒有成功，請注意檢查下模型 api key 配置，注意并不是 qqbot 的 secret 哦。
Q：機(jī)器人為什么回復(fù)“API rate limit reached. Please try again later.”
A：模型調(diào)用頻率太快了，請檢查模型使用情況或更換模型。
Q：如何聯(lián)系官方人員？
A：可加入討論群、討論頻道或添加機(jī)器人進(jìn)行反饋，見文本最后的二維碼。
Q：如何查詢?nèi)罩荆?/strong>
A：請登錄openclaw運(yùn)行的機(jī)器，使用終端輸入“openclaw logs --follow”以顯示實(shí)時(shí)日志。
Q：為什么openclaw機(jī)器人發(fā)不出圖片？
A：可以發(fā)一張圖片讓機(jī)器人原樣回給你，驗(yàn)證下是通道的問題，還是模型沒有畫圖skills工具。如果是需要畫圖能力，需要自己配置畫圖skills，一般需要自己購買生圖模型獲得生圖的api key。
Q：如果我從其他渠道的 qqbot 插件想升級到官方插件 @tencent-connect/openclaw-qqbot，應(yīng)該怎么操作？
A：升級方式參考本文里的【原生 OpenClaw 安裝插件 QQBot 插件】這部分內(nèi)容。
交流與反饋
如果QQ 交流群已經(jīng)滿員，可前往 PC 管理端掃碼添加最新群聊：
https://q.qq.com/qqbot/openclaw/login.html
最后，QQBot 官方接入指南仍在持續(xù)更新，歡迎訪問在線文檔 《QQ機(jī)器人接入 OpenClaw 的官方“養(yǎng)蝦”指南》 查看最新內(nèi)容。如果你在養(yǎng)蝦過程中遇到問題，或有任何建議與反饋，也歡迎隨時(shí)交流。我們會持續(xù)補(bǔ)充和完善文檔內(nèi)容，陪大家一起把蝦養(yǎng)得更輕松、更順手。
關(guān)鍵詞：
營業(yè)執(zhí)照公示信息