🔧 阿川の電商水電行

Shopify 顧問、維護與客製化

💡

小任務 / 單次支援方案

單次處理 Shopify 修正／微調

⭐️

維護方案

每月 Shopify 技術支援 + 小修改 + 諮詢

🚀

專案建置

Shopify 功能導入、培訓 + 分階段交付

👉 瞭解詳情 / 免費諮詢

小編精選 - 技術文章翻譯 · 03月10日

OpenClaw 接入 QQ Bot 完整實作指南

============================

一、概述

本文檔記錄了在 OpenClaw 平台上接入 QQ 機器人的完整實作過程，包括：

QQ 開放平台帳號註冊與機器人建立
OpenClaw 外掛安裝與設定
遇到的問題及解決方案
最佳實務建議

1.1 功能特色

QQ 機器人外掛支援以下功能：

🔒 多場景支援 - C2C 私聊、群組 @ 訊息、頻道訊息、頻道私信
🖼️ 富媒體訊息 - 支援圖片、語音、影片、檔案收發
⏰ 定時推送 - 支援定時任務主動推送
🔗 URL 無限制 - 私聊可直接傳送 URL
⌨️ 輸入狀態 - 機器人正在輸入中狀態提示
🔄 熱更新 - 支援 npm 方式安裝與熱更新
📝 Markdown - 支援 Markdown 格式

二、前置條件

2.1 環境需求

OpenClaw 已安裝並正常運行
Node.js 18+ 環境
能夠存取 QQ 開放平台（open.qq.com）
手機 QQ 用於掃碼驗證

2.2 所需資訊

QQ 開放平台帳號（需實名認證）
QQ 機器人的 AppID 與 AppSecret

三、QQ 開放平台設定

3.1 註冊 QQ 開放平台帳號

造訪 QQ 開放平台的龍蝦專用入口

q.qq.com/qqbot/openc…

3.2 建立 QQ 機器人

進入「QQ 機器人」頁面

用你的 QQ 掃碼登入

點選「建立機器人」

點選建立機器人。

3.3 取得憑證

建立後會提供 QQ 機器人的 AppID 與 AppSecret，用於在 OpenClaw 中設定。
重要：AppSecret 第一次查看後無法再次顯示，請立即儲存

四、OpenClaw 外掛安裝

4.1 安裝 QQ 機器人外掛

<div><div><div></div><span>bash</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span><span># 方式一：通过 npm 安装（推荐）</span></span>
<span>openclaw plugins install @sliverp/qqbot@latest</span>
<span></span>
<span><span># 方式二：从源码安装</span></span>
<span>git <span>clone</span> https://github.com/sliverp/qqbot.git && <span>cd</span> qqbot</span>
<span>openclaw plugins install .</span>


### 4.2 安裝相依套件

執行外掛安裝指令：

<div><div><div></div><span>css</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span>openclaw plugins install span>@sliverp</span/qqbotspan>@latest</span</span>

安裝過程中可能出現警告與相依安裝失敗：

<div><div><div></div><span>bash</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span>Downloading @sliverp/qqbot@latest…</span>
<span>Extracting /tmp/openclaw-npm-pack-4j5i0f/sliverp-qqbot-1.5.3.tgz…</span>
<span>WARNING: Plugin <span>"qqbot"</span> contains dangerous code patterns: Environment variable access combined with network send — possible credential harvesting (/tmp/openclaw-plugin-bRKZJH/extract/package/src/gateway.ts:140); Shell <span>command</span> execution detected (child_process) (/tmp/openclaw-plugin-bRKZJH/extract/package/src/utils/audio-convert.ts:565); Shell <span>command</span> execution detected (child_process) (/tmp/openclaw-plugin-bRKZJH/extract/package/src/utils/platform.ts:274); Shell <span>command</span> execution detected (child_process) (/tmp/openclaw-plugin-bRKZJH/extract/package/bin/qqbot-cli.js:109)</span>
<span>Installing to /root/.openclaw/extensions/qqbot…</span>
<span>Installing plugin dependencies…</span>
<span>npm install failed:</span>


若遇到 `npm install failed`，需至外掛目錄手動安裝相依套件：

4.3 驗證安裝

<div><div><div></div><span>bash</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span><span># 查看插件目录</span></span>
<span><span>ls</span> -la ~/.openclaw/extensions/qqbot/</span>
<span></span>
<span><span># 确认以下文件存在：</span></span>
<span><span># - openclaw.plugin.json</span></span>
<span><span># - package.json</span></span>
<span><span># - node_modules/</span></span>


---

五、設定 QQ 機器人頻道
-------------------

### 5.1 方式一：使用指令列設定（建議）

<div><div><div></div><span>csharp</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span>openclaw channels <span>add</span> --channel qqbot --token <span>"你的AppID:你的AppSecret"</span></span>

執行成功後會顯示：

<div><div><div></div><span>erlang</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span>Added QQ Bot account <span>"default"</span>.</span>


### 5.2 方式二：手動編輯設定檔

編輯 `~/.openclaw/openclaw.json`：

5.3 啟用外掛

在 ~/.openclaw/openclaw.json 中新增：

<div><div><div></div><span>perl</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span>{</span>
<span>  <span>"plugins"</span>: {</span>
<span>    <span>"allow"</span>: [</span>
<span>      <span>"qqbot"</span></span>
<span>    ],</span>
<span>    <span>"entries"</span>: {</span>
<span>      <span>"qqbot"</span>: {</span>
<span>        <span>"enabled"</span>: true</span>
<span>      }</span>
<span>    },</span>
<span>    <span>"installs"</span>: {</span>
<span>      <span>"qqbot"</span>: {</span>
<span>        <span>"source"</span>: <span>"npm"</span>,</span>
<span>        <span>"spec"</span>: <span>"@sliverp/qqbot@latest"</span>,</span>
<span>        <span>"installPath"</span>: <span>"/root/.openclaw/extensions/qqbot"</span>,</span>
<span>        <span>"version"</span>: <span>"1.5.3"</span></span>
<span>      }</span>
<span>    }</span>
<span>  }</span>
<span>}</span>


---

六、啟動與驗證
-------

### 6.1 重啟 Gateway

<div><div><div></div><span></span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span>openclaw gateway restart</span>

6.2 檢查狀態

<div><div><div></div><span>lua</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span>openclaw <span>status</span></span>


確認 Channels 區段：

<div><div><div></div><span>vbnet</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span>│ QQ Bot │ <span>ON</span> │ OK │ configured │</span>

6.3 測試對話

打開手機 QQ
找到已新增的機器人
傳送訊息進行測試

七、遇到的問題及解決方案

7.1 問題一：`openclaw: command not found`

原因：openclaw 指令的符號連結不在 PATH 中

解決方案：

<div><div><div></div><span>bash</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span><span>ln</span> -sf /usr/lib/node_modules/openclaw/openclaw.mjs /usr/local/bin/openclaw</span>
<span><span>chmod</span> +x /usr/local/bin/openclaw</span>


### 7.2 問題二：`Unknown channel: qqbot`

**原因**：QQ 機器人不是 OpenClaw 內建的頻道（channel），需要先安裝外掛。如果安裝外掛時相依套件安裝失敗（`npm install failed`），雖然外掛檔案已複製，但未被正確註冊，導致 OpenClaw 無法識別 qqbot 頻道。

**解決方案**：

1. 先安裝外掛：`openclaw plugins install @sliverp/qqbot@latest`
2. 如果相依安裝失敗，手動安裝：`cd ~/.openclaw/extensions/qqbot && npm install`
3. 使用指令設定：`openclaw channels add --channel qqbot --token "你的AppID:你的AppSecret"`
4. 重啟 gateway：`openclaw gateway restart`

### 7.3 問題三：JSON 設定檔語法錯誤

**錯誤訊息**：

<div><div><div></div><span>javascript</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span><span>JSON</span>5: invalid character <span>'"'</span> at <span>198</span>:<span>7</span></span>

原因：手動編輯 JSON 時，在新增 qqbot 外掛安裝紀錄時遺漏逗號

錯誤程式碼：

<div><div><div></div><span>json</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span><span>"installedAt"</span><span>:</span> <span>"2026-03-06T13:49:46.622Z"</span></span>
<span><span>}</span>          ← 缺少逗號</span>
<span><span>"qqbot"</span><span>:</span> <span>{</span></span>


**解決方案**：

<div><div><div></div><span>less</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span># 修复语法错误</span>
<span><span>sed</span> <span>-i</span> '<span>197s</span>/}/},/' /<span>root</span>/<span>.openclaw</span>/<span>openclaw</span><span>.json</span></span>
<span></span>
<span># 验证 <span>JSON</span> 语法</span>
<span><span>node</span> <span>-e</span> "<span>JSON</span><span>.parse</span>(<span>require</span>(<span>'fs'</span>).<span>readFileSync</span>(<span>'/root/.openclaw/openclaw.json'</span>, <span>'utf8'</span>)); <span>console</span><span>.log</span>(<span>'JSON OK'</span>)"</span>

經驗教訓：

編輯 JSON 時要確保相鄰屬性之間有逗號
編輯大型檔案後應用 node -e "JSON.parse(...)" 驗證語法
或者編輯後立即執行 openclaw status 檢查設定是否有效

7.4 問題四：npm 相依安裝失敗

原因：外掛安裝過程中 npm install 可能失敗

解決方案：

<div><div><div></div><span>bash</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span><span>cd</span> ~/.openclaw/extensions/qqbot</span>
<span>npm install</span>


---

八、設定檔參考
--------

### 8.1 完整設定範例

<div><div><div></div><span>json</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span><span>{</span></span>
<span> <span>"channels"</span><span>:</span> <span>{</span></span>
<span> <span>"feishu"</span><span>:</span> <span>{</span></span>
<span> <span>"appId"</span><span>:</span> <span>"cli_xxx"</span><span>,</span></span>
<span> <span>"appSecret"</span><span>:</span> <span>"xxx"</span><span>,</span></span>
<span> <span>"enabled"</span><span>:</span> <span><span>true</span></span>
<span> <span>}</span><span>,</span></span>
<span> <span>"qqbot"</span><span>:</span> <span>{</span></span>
<span> <span>"enabled"</span><span>:</span> <span><span>true</span></span><span>,</span></span>
<span> <span>"appId"</span><span>:</span> <span>"你的AppID"</span><span>,</span></span>
<span> <span>"clientSecret"</span><span>:</span> <span>"你的AppSecret"</span></span>
<span> <span>}</span></span>
<span> <span>}</span><span>,</span></span>
<span> <span>"plugins"</span><span>:</span> <span>{</span></span>
<span> <span>"allow"</span><span>:</span> <span>[</span></span>
<span> <span>"feishu-openclaw-plugin"</span><span>,</span></span>
<span> <span>"qqbot"</span></span>
<span> <span>]</span><span>,</span></span>
<span> <span>"entries"</span><span>:</span> <span>{</span></span>
<span> <span>"feishu-openclaw-plugin"</span><span>:</span> <span>{</span></span>
<span> <span>"enabled"</span><span>:</span> <span><span>true</span></span>
<span> <span>}</span><span>,</span></span>
<span> <span>"qqbot"</span><span>:</span> <span>{</span></span>
<span> <span>"enabled"</span><span>:</span> <span><span>true</span></span>
<span> <span>}</span></span>
<span> <span>}</span><span>,</span></span>
<span> <span>"installs"</span><span>:</span> <span>{</span></span>
<span> <span>"feishu-openclaw-plugin"</span><span>:</span> <span>{</span></span>
<span> <span>"source"</span><span>:</span> <span>"npm"</span><span>,</span></span>
<span> <span>"spec"</span><span>:</span> span>"@larksuiteoapi/feishu-openclaw-plugin"</span<span>,</span></span>
<span> <span>"installPath"</span><span>:</span> <span>"/root/.openclaw/extensions/feishu-openclaw-plugin"</span><span>,</span></span>
<span> <span>"version"</span><span>:</span> <span>"2026.3.7-beta.1"</span></span>
<span> <span>}</span><span>,</span></span>
<span> <span>"qqbot"</span><span>:</span> <span>{</span></span>
<span> <span>"source"</span><span>:</span> <span>"npm"</span><span>,</span></span>
<span> <span>"spec"</span><span>:</span> span>"@sliverp/qqbot@latest"</span<span>,</span></span>
<span> <span>"installPath"</span><span>:</span> <span>"/root/.openclaw/extensions/qqbot"</span><span>,</span></span>
<span> <span>"version"</span><span>:</span> <span>"1.5.3"</span></span>
<span> <span>}</span></span>
<span> <span>}</span></span>
<span> <span>}</span></span>
<span><span>}</span></span>

九、語音功能設定（可選）

9.1 STT（語音轉文字）

在 ~/.openclaw/openclaw.json 中設定：

<div><div><div></div><span>json</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span><span>{</span></span>
<span>  <span>"channels"</span><span>:</span> <span>{</span></span>
<span>    <span>"qqbot"</span><span>:</span> <span>{</span></span>
<span>      <span>"stt"</span><span>:</span> <span>{</span></span>
<span>        <span>"provider"</span><span>:</span> <span>"your-provider"</span><span>,</span></span>
<span>        <span>"model"</span><span>:</span> <span>"your-stt-model"</span></span>
<span>      <span>}</span></span>
<span>    <span>}</span></span>
<span>  <span>}</span></span>
<span><span>}</span></span>


### 9.2 TTS（文字轉語音）

十、升級外掛

10.1 使用 openclaw 指令升級

<div><div><div></div><span>css</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span>openclaw plugins upgrade <span>@sliverp</span>/qqbot<span>@latest</span></span>


### 10.2 使用 npx 升級

<div><div><div></div><span>css</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span>npx -y span>@sliverp</span/qqbotspan>@latest</span upgrade</span>

10.3 從原始碼升級

<div><div><div></div><span>bash</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span><span>cd</span> ~/.openclaw/extensions/qqbot</span>
<span>git pull</span>
<span>npm install</span>
<span>openclaw gateway restart</span>


---

十一、最佳實務
-------

### 11.1 設定檔管理

- ✅ 修改設定前先備份：`cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak`
- ✅ 修改後驗證語法：`node -e "JSON.parse(...)"`
- ✅ 使用版本控制管理設定檔

### 11.2 安全建議

- ⚠️ 不要將 AppSecret 提交到公開倉庫
- ⚠️ 定期輪換 AppSecret
- ⚠️ 限制測試成員範圍

### 11.3 除錯技巧

<div><div><div></div><span>bash</span></div><div><div> <span>体验AI代码助手</span></div><div> <span>代码解读</span></div><div>复制代码</div></div></div>```
<span><span># 查看 gateway 日志</span></span>
<span>openclaw logs --follow</span>
<span></span>
<span><span># 檢查外掛狀態</span></span>
<span>openclaw doctor --fix</span>
<span></span>
<span><span># 查看運行狀態</span></span>
<span>openclaw status</span>

十二、常見問題 FAQ

Q1: 機器人回覆「去火星了」怎麼辦？

A: 這是因為 OpenClaw 尚未成功連線到 QQ 機器人。請檢查：

AppID 與 AppSecret 是否正確
Gateway 是否正常運行
外掛是否正確安裝

Q2: 如何新增多個測試用戶？

A: 在 QQ 開放平台的「沙箱配置」中新增更多成員。

Q3: 支援群組嗎？

A: QQ 開放平台目前不支援機器人在 QQ 群的配置，僅支援私聊模式。

十三、參考資源

十四、更新日誌

日期｜版本｜更新內容
2026-03-08｜v1.0｜初始版本

原文出處：https://juejin.cn/post/7614020998103662598

小編精選 - 技術文章翻譯

精選技術文章翻譯，幫助開發者持續吸收新知。

0個讚 0留言 8瀏覽

共有 0 則留言

登入之後發表留言

文字內容提供幾種功能：
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式

小編精選 - 技術文章翻譯

精選技術文章翻譯，幫助開發者持續吸收新知。

🏆 本月排行榜

🥇

站長阿川

📝26 💬4

788

🥈

我愛JS

💬5

🥉

徐浩瑋

評分標準：發文×10 + 留言×3 + 獲讚×5 + 點讚×1 + 瀏覽數÷10

本數據每小時更新一次

🔧 阿川の電商水電行

Shopify 顧問、維護與客製化

💡

小任務 / 單次支援方案

單次處理 Shopify 修正／微調

⭐️

維護方案

每月 Shopify 技術支援 + 小修改 + 諮詢

🚀

專案建置

Shopify 功能導入、培訓 + 分階段交付

👉 瞭解詳情 / 免費諮詢

🔧 阿川の電商水電行

OpenClaw 接入 QQ Bot 完整實作指南

OpenClaw 接入 QQ Bot 完整實作指南

1.1 功能特色

二、前置條件

2.1 環境需求

2.2 所需資訊

三、QQ 開放平台設定

3.1 註冊 QQ 開放平台帳號

3.2 建立 QQ 機器人

3.3 取得憑證

四、OpenClaw 外掛安裝

4.1 安裝 QQ 機器人外掛

4.3 驗證安裝

5.3 啟用外掛

6.2 檢查狀態

6.3 測試對話

七、遇到的問題及解決方案

7.1 問題一：openclaw: command not found

7.4 問題四：npm 相依安裝失敗

九、語音功能設定（可選）

9.1 STT（語音轉文字）

十、升級外掛

10.1 使用 openclaw 指令升級

10.3 從原始碼升級

十二、常見問題 FAQ

Q1: 機器人回覆「去火星了」怎麼辦？

Q2: 如何新增多個測試用戶？

Q3: 支援群組嗎？

十三、參考資源

十四、更新日誌

小編精選 - 技術文章翻譯

🏆 本月排行榜

🔧 阿川の電商水電行

7.1 問題一：`openclaw: command not found`