QQ Bot

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

狀態：官方可下載外掛。

安裝

openclaw plugins install @openclaw/qqbot

設定

1. 前往 QQ 開放平台，並使用手機 QQ 掃描 QR 圖碼以 註冊／登入。
2. 按一下 Create Bot 以建立新的 QQ Bot。
3. 在 Bot 的設定頁面找到 AppID 和 AppSecret，並複製它們。

4. 新增頻道：

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

5. 重新啟動閘道。

傳入持久性

對於 QQ 閘道的回合事件，OpenClaw 會先保存原始事件，再推進已儲存的閘道續傳序號。待處理或可重試的回合可在閘道重新啟動後繼續存在、依對話維持循序處理，並在有效或保留的完成記錄存在期間，使用供應商事件 ID 避免重複的佇列項目。

如果持久化接納失敗，OpenClaw 會終止目前的閘道通訊端而不推進序號。重新連線／續傳路徑之後便能再次要求尚未提交的事件。從佇列到代理程式的邊界仍採用至少一次傳遞，因此在交接期間當機可能會重播回合。

互動式設定：

openclaw channels add

精靈也提供 QR 圖碼綁定，作為手動輸入 AppID/AppSecret 的替代方式： 使用與目標 QQ Bot 綁定的手機應用程式掃描圖碼以完成 綁定。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； appId 必須已在設定組態或 QQBOT_APP_ID 中設定。
• clientSecret 接受純文字字串、檔案路徑（clientSecretFile） 或結構化 SecretRef 物件。
• 舊版 secretref:...／secretref-env:... 標記字串不適用於 clientSecret，因此會遭拒絕；請改用結構化 SecretRef 物件。

串流

{  channels: {    qqbot: {      streaming: {        mode: "partial", // 區塊串流："partial"（預設）或 "off"        nativeTransport: true, // 對私人訊息使用 QQ 官方 C2C stream_messages API      },    },  },}

• streaming.mode: "off" 會停用該帳號的區塊串流。
• streaming.nativeTransport: true 透過 QQ 官方 stream_messages API 串流 C2C（私人訊息）回覆；群組／頻道目標不受影響。
• 舊版 streaming: true|false 純量值和 streaming.c2cStreamApi 鍵 會透過 openclaw doctor --fix 遷移為此結構。
• /bot-streaming on|off 可從私人訊息切換相同的設定組態。

存取原則

• allowFrom／groupAllowFrom 限制誰能在 C2C／ 群組情境中與 Bot 聊天。dmPolicy／groupPolicy（open | allowlist | disabled） 控制強制執行模式。當 allowFrom 包含明確的 （非萬用字元）項目時，dmPolicy 預設為 allowlist，否則為 open。 當 groupAllowFrom 或 allowFrom 任一者包含明確項目時， groupPolicy 預設為 allowlist，否則為 open。
• 無論 dmPolicy／groupPolicy 為何，“Auth: allowlist”斜線指令都需要 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 標記，因此 在一個閘道下執行多個 Bot 時，診斷資訊仍可彼此區分。

透過命令列介面新增第二個 Bot：

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

群組聊天

群組支援使用 QQ 群組 OpenID，而非顯示名稱。將 Bot 新增至 群組，然後提及它，或設定該群組無須提及即可執行。

{  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）；佇列已滿時，先移除由 Bot 撰寫的訊息，再移除人類訊息； 並將一連串一般群組訊息合併為一個標明來源的回合。斜線 指令會逐一執行，不受任何合併批次影響。

語音（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 覆寫使用與 tts 相同的結構，並在頻道／全域 TTS 設定組態之上進行深度合併。

STT 要求預設在 60 秒後逾時。外掛專屬 STT 使用所選的 models.providers.<id>.timeoutSeconds 覆寫。框架音訊 STT 會先使用所選支援音訊之 tools.media.models[] 項目的 timeoutSeconds，接著使用所選供應商覆寫。

傳入的 QQ 語音附件會以音訊媒體中繼資料形式提供給代理程式， 同時讓原始語音檔案不進入通用 MediaPaths。純文字回覆中的 [[audio_as_voice]] 會在已設定 TTS 時合成 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，且可連線至供應商。

相關內容

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