設定 OpenClaw QQ Bot：5 分鐘內完成串接教學

想要在 QQ 上跑一個 AI 機器人，最煩人的通常不是寫程式碼，而是處理那些繁瑣的 API 對接跟環境配置。如果你也曾經卡在 WebSocket 連線或是權限設定，這篇教學會幫你快速搞定，讓你把精力花在更有趣的功能開發上。

QQ Bot

QQ Bot 透過官方的 QQ Bot API (WebSocket Gateway) 連接到 OpenClaw。這個外掛支援 C2C 私聊、群組 @ 訊息，以及頻道訊息，並支援豐富的媒體格式（圖片、語音、影片、檔案）。

狀態：內建頻道外掛。支援私訊、群組聊天、頻道訊息和媒體。目前不支援表情回應 (Reactions) 和討論串 (Threads)。

內建於 OpenClaw

目前的 OpenClaw 安裝包已經內建了 QQ Bot。對於一般設定，你不需要額外執行 openclaw plugins install。

設定步驟

1. 前往 QQ 開放平台，用手機 QQ 掃碼登入。
2. 點擊 建立機器人 來建立一個新的 QQ 機器人。
3. 在機器人的設定頁面找到 AppID 和 AppSecret 並複製下來。

AppSecret 不會以明文儲存 — 如果你沒儲存就離開頁面，就得重新產生一個。

4. 新增頻道：

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

5. 重啟 Gateway。

互動式設定路徑：

openclaw channels add
openclaw configure --section channels

設定選項

最簡設定：

{
  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",
    },
  },
}

注意：

• 環境變數回退 (Fallback) 只適用於預設的 QQ Bot 帳號。
• openclaw channels add --channel qqbot --token-file ... 只提供 AppSecret；AppID 必須已經在設定檔或 QQBOT_APP_ID 中設好。
• clientSecret 也支援 SecretRef 輸入，不只是明文字串。

多帳號設定

在單個 OpenClaw 實例下執行多個 QQ 機器人：

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

每個帳號會啟動自己的 WebSocket 連線並維護獨立的 token 快取（透過 appId 隔離）。

透過 CLI 新增第二個機器人：

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

語音 (STT / TTS)

STT 和 TTS 支援兩層級的設定與優先權回退機制：

設定	外掛特定設定	框架回退設定
STT	channels.qqbot.stt	tools.media.audio.models[0]
TTS	channels.qqbot.tts	messages.tts

{
  channels: {
    qqbot: {
      stt: {
        provider: "your-provider",
        model: "your-stt-model",
      },
      tts: {
        provider: "your-provider",
        model: "your-tts-model",
        voice: "your-voice",
      },
    },
  },
}

將任一項設為 enabled: false 即可停用。

出站音訊的上傳/轉碼行為也可以透過 channels.qqbot.audioFormatPolicy 調整：

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

目標格式

格式	描述
qqbot:c2c:OPENID	私聊 (C2C)
qqbot:group:GROUP_OPENID	群組聊天
qqbot:channel:CHANNEL_ID	頻道訊息

每個機器人都有自己的使用者 OpenID。從機器人 A 收到的 OpenID 不能 用來透過機器人 B 傳送訊息。

斜線指令

在進入 AI 隊列前會被攔截的內建指令：

指令	描述
/bot-ping	延遲測試
/bot-version	顯示 OpenClaw 框架版本
/bot-help	列出所有指令
/bot-upgrade	顯示 QQBot 升級指南連結
/bot-logs	將最近的 Gateway 日誌匯出為檔案

在任何指令後面加上 ? 可以查看用法說明（例如 /bot-upgrade ?）。

疑難排解

• 機器人回覆「去火星了」： 憑證未設定或 Gateway 未啟動。
• 收不到進站訊息： 確認 appId 和 clientSecret 正確，且機器人在 QQ 開放平台已啟用。
• 使用 --token-file 設定後仍顯示未配置： --token-file 只會設定 AppSecret。你還需要在設定檔或 QQBOT_APP_ID 中提供 appId。
• 主動訊息沒送到： 如果使用者最近沒跟機器人互動，QQ 可能會攔截機器人主動發送的訊息。
• 語音沒轉成文字： 確保 STT 已設定且 Provider 可以連通。

AI Setup Assistant