QQ Bot

QQ Bot 透過官方 QQ Bot API（WebSocket 閘道）連線至 OpenClaw。 主要聊天類型為 C2C 私訊與群組 @ 提及，並支援豐富的媒體內容（圖片、語音、影片、檔案）。公會頻道訊息僅支援文字與遠端 URL 圖片；公會頻道不支援語音、影片、檔案上傳，以及本機/Base64 圖片。所有聊天類型皆不支援表情回應與討論串。

狀態：官方可下載外掛。

安裝

openclaw plugins install @openclaw/qqbot

設定

1. 前往 QQ 開放平台，使用手機 QQ 掃描 QR Code 以註冊／登入。
2. 點擊 Create Bot 建立新的 QQ Bot。
3. 在機器人的設定頁面找到 AppID 與 AppSecret，並將其複製。

4. 新增頻道：

openclaw channels add --channel qqbot --token "AppID:AppSecret"

5. 重新啟動閘道。

互動式設定：

openclaw channels add

精靈也提供 QR Code 綁定，作為手動輸入 AppID/AppSecret 的替代方式：使用已連結至目標 QQ Bot 的手機應用程式掃描 QR Code，即可完成綁定。OpenClaw 會將傳回的憑證持久儲存於該帳號的設定範圍內。

設定組態

最小設定：

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecret: "YOUR_APP_SECRET",    },  },}

預設帳號環境變數（僅限頂層帳號）：

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

以檔案提供的 AppSecret：

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecretFile: "/path/to/qqbot-secret.txt",    },  },}

環境變數 SecretRef AppSecret：

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecret: { source: "env", provider: "default", id: "QQBOT_CLIENT_SECRET" },    },  },}

注意事項：

• openclaw channels add --channel qqbot --token-file ... 僅設定 AppSecret；必須已在設定或 QQBOT_APP_ID 中設定 appId。
• clientSecret 接受純文字字串、檔案路徑（clientSecretFile）或結構化 SecretRef 物件。
• clientSecret 不接受舊版 secretref:...／secretref-env:... 標記字串；請改用結構化 SecretRef 物件。

存取原則

• allowFrom／groupAllowFrom 會限制哪些人可在 C2C／群組情境中與機器人聊天。dmPolicy／groupPolicy（open | allowlist | disabled）控制強制執行模式。當 allowFrom 有具體的非萬用字元項目時，dmPolicy 預設為 allowlist，否則為 open。當 groupAllowFrom 或 allowFrom 任一者有具體項目時，groupPolicy 預設為 allowlist，否則為 open。
• 無論 dmPolicy／groupPolicy 為何，「驗證：允許清單」斜線命令都要求 allowFrom 中有明確的非萬用字元項目（群組呼叫則為 groupAllowFrom）——請參閱斜線命令。

多帳號設定

在單一 OpenClaw 執行個體下執行多個 QQ Bot：

{  channels: {    qqbot: {      enabled: true,      appId: "111111111",      clientSecret: "secret-of-bot-1",      accounts: {        bot2: {          enabled: true,          appId: "222222222",          clientSecret: "secret-of-bot-2",        },      },    },  },}

每個帳號都有獨立的 WebSocket 連線、API 用戶端與權杖快取，並以 appId 作為索引鍵。記錄行會標示其所屬帳號 ID，因此在單一閘道下執行多個機器人時，診斷資訊仍可彼此區分。

透過命令列介面新增第二個機器人：

openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"

群組聊天

群組支援使用 QQ 群組 OpenID，而非顯示名稱。將機器人加入群組後，提及它，或設定該群組無須提及即可執行。

{  channels: {    qqbot: {      groupPolicy: "allowlist",      groupAllowFrom: ["member_openid"],      groups: {        "*": {          requireMention: true,          commandLevel: "all",          historyLimit: 50,          tools: { deny: ["exec", "read", "write"] },        },        GROUP_OPENID: {          name: "Release room",          requireMention: false,          ignoreOtherMentions: true,          commandLevel: "safety",          historyLimit: 20,          prompt: "Keep replies short and operational.",        },      },    },  },}

groups["*"] 為所有群組設定預設值；具體的 groups.GROUP_OPENID 項目會針對單一群組覆寫這些預設值。群組設定：

commandLevel 接受以下值：

舊版 QQ Bot toolPolicy 項目已停用。執行 openclaw doctor --fix 將其遷移至 tools。

啟用模式為 mention 與 always。requireMention: true 對應至 mention；requireMention: false 對應至 always。若存在工作階段層級的啟用模式覆寫，則其優先於設定。

輸入佇列依對等端分開管理。群組對等端的佇列上限較大（50；直接對等端為 20），佇列已滿時會優先逐出機器人撰寫的訊息，再逐出人類撰寫的訊息，並將連續送達的一般群組訊息合併為一個附有來源標示的回合。斜線命令會逐一執行，且不受任何合併批次影響。

語音（STT／TTS）

STT 與 TTS 支援具備優先順序備援的雙層設定：

{  channels: {    qqbot: {      stt: {        provider: "your-provider",        model: "your-stt-model",      },      tts: {        provider: "your-provider",        model: "your-tts-model",        voice: "your-voice",      },      accounts: {        "qq-main": {          tts: {            providers: {              openai: { voice: "shimmer" },            },          },        },      },    },  },}

在任一項目上設定 enabled: false 即可停用。帳號層級的 TTS 覆寫使用與 messages.tts 相同的結構，並會深度合併至頻道／全域 TTS 設定之上。

STT 請求預設於 60 秒後逾時。外掛專用 STT 使用所選 models.providers.<id>.timeoutSeconds 覆寫值。框架音訊 STT 依序使用 tools.media.audio.models[0].timeoutSeconds、tools.media.audio.timeoutSeconds，最後使用所選供應商的覆寫值。

傳入的 QQ 語音附件會以音訊媒體中繼資料形式提供給代理程式，同時避免將原始語音檔案放入通用 MediaPaths。當已設定 TTS 時，純文字回覆中的 [[audio_as_voice]] 會合成 TTS，並傳送原生 QQ 語音訊息。

也可使用 channels.qqbot.audioFormatPolicy 調整傳出音訊的上傳／轉碼行為：

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

目標格式

斜線命令

在進入 AI 佇列前攔截的內建命令：

在任何命令後附加 ? 即可取得用法說明（例如 /bot-upgrade ?）。

「驗證：允許清單」命令還要求傳送者的 openid 必須位於明確的非萬用字元 allowFrom 清單中（群組中發出的命令以 groupAllowFrom 優先，若無則回退至 allowFrom）。萬用字元 allowFrom: ["*"] 允許聊天，但不允許使用這些命令。在私訊以外執行其中任一命令，或未獲授權時，系統會傳回提示，而不會直接捨棄訊息。

/bot-me、/bot-version 和 /bot-upgrade 僅限私人聊天使用，但不需要允許清單——任何 C2C 傳送者都能執行它們。

當 QQ Bot 執行核准使用預設的同一聊天備援機制時，點擊原生核准按鈕也會遵循相同的明確非萬用字元命令允許清單。若要只授予核准權限而不提供更廣泛的命令存取權，請設定 channels.qqbot.execApprovals.approvers。原生執行核准預設為啟用。

媒體與儲存空間

• 輸入、輸出及閘道橋接媒體共用 ~/.openclaw/media/qqbot 下的單一承載資料根目錄（設定 OPENCLAW_HOME 時會遵循該設定），因此上傳、下載與轉碼快取都會保留在同一個受保護的目錄下。
• 傳送至 C2C 與群組目標的豐富媒體會統一經由 sendMedia 路徑。大小為 5 MiB 以上的本機檔案與記憶體內緩衝區會使用 QQ 的分塊上傳端點；較小的承載資料及遠端 URL/Base64 來源則使用單次上傳 API。
• 如果熱升級在閘道完成寫入 openclaw.json 前中斷閘道，外掛會在下次啟動時，從內部快照還原該帳號最後已知的 appId / clientSecret（絕不覆寫刻意進行的設定變更），因此不需要重新掃描 QR Code。

疑難排解

• **閘道未啟動／沒有輸入訊息：**請確認 appId 與 clientSecret 正確，且機器人已在 QQ Open Platform 上啟用。缺少認證資訊時會顯示「QQ Bot 未設定（缺少 appId 或 clientSecret）」。
• 使用 --token-file 設定後仍顯示未設定：--token-file 只會設定 AppSecret。仍必須在設定或 QQBOT_APP_ID 中設定 appId。
• **突發的群組回覆發生衝突：**當對等端的佇列已滿時，輸入佇列會先淘汰由機器人撰寫的訊息，而不是人類訊息；並將突發的一般（非命令）群組訊息合併成一次標示來源的互動，因此大量機器人聊天內容不應導致人類訊息無法獲得處理。
• **主動訊息未送達：**如果使用者近期沒有互動，QQ 可能會封鎖由機器人主動發起的訊息。
• **語音未轉錄：**請確認已設定 STT，且提供者可連線。

相關內容

• 配對
• 群組
• 頻道疑難排解