メインコンテンツへスキップ

​
QQ Bot

QQ Botは、公式のQQ Bot API（WebSocket Gateway）を介してOpenClawに接続します。 このプラグインは、C2Cプライベートチャット、グループの@メッセージ、ギルドチャンネルメッセージと、 リッチメディア（画像、音声、動画、ファイル）をサポートします。 ステータス: バンドル済みプラグイン。ダイレクトメッセージ、グループチャット、ギルドチャンネル、 メディアをサポートしています。リアクションとスレッドはサポートしていません。

​
バンドル済みプラグイン

現在のOpenClawリリースにはQQ Botがバンドルされているため、通常のパッケージ済みビルドでは 別途openclaw plugins install手順は不要です。

​
セットアップ

  1. QQ Open Platformにアクセスし、 スマートフォンのQQでQRコードをスキャンして登録またはログインします。
  2. Create Botをクリックして、新しいQQボットを作成します。
  3. ボットの設定ページでAppIDとAppSecretを見つけてコピーします。
AppSecretは平文では保存されません。保存せずにページを離れると、 新しいものを再生成する必要があります。
  1. チャンネルを追加します。
openclaw channels add --channel qqbot --token "AppID:AppSecret"
  1. 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",
    },
  },
}
注意事項:
  • 環境変数のフォールバックは、デフォルトのQQ Botアカウントにのみ適用されます。
  • openclaw channels add --channel qqbot --token-file ...は AppSecretのみを提供します。AppIDは設定またはQQBOT_APP_IDですでに設定されている必要があります。
  • clientSecretは平文文字列だけでなく、SecretRef入力も受け付けます。

​
複数アカウント設定

1つの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接続を起動し、 独立したトークンキャッシュ（appIdごとに分離）を維持します。 CLIで2つ目のボットを追加する: 
openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"

​
音声（STT / TTS）

STTとTTSは、優先度付きフォールバックを持つ2段階設定をサポートします。
設定プラグイン固有フレームワークのフォールバック
STTchannels.qqbot.stttools.media.audio.models[0]
TTSchannels.qqbot.ttsmessages.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セットを持ちます。Bot Aで受信したOpenIDは、Bot B経由でメッセージ送信に使用できません。

​
スラッシュコマンド

AIキューより前にインターセプトされる組み込みコマンド:
コマンド説明
/bot-pingレイテンシーテスト
/bot-versionOpenClawフレームワークのバージョンを表示
/bot-helpすべてのコマンドを一覧表示
/bot-upgradeQQBotアップグレードガイドのリンクを表示
/bot-logs最近のGatewayログをファイルとしてエクスポート
使用方法のヘルプを見るには、任意のコマンドに?を付けます（例: /bot-upgrade ?）。

​
トラブルシューティング

  • ボットが「gone to Mars」と返信する: 認証情報が設定されていないか、Gatewayが起動していません。
  • 受信メッセージがない: appIdとclientSecretが正しいこと、および QQ Open Platformでボットが有効になっていることを確認してください。
  • --token-fileでセットアップしても未設定と表示される: --token-fileは AppSecretのみを設定します。appIdは設定またはQQBOT_APP_IDで別途必要です。
  • プロアクティブメッセージが届かない: ユーザーが最近やり取りしていない場合、 QQがボット主導メッセージを遮断することがあります。
  • 音声が文字起こしされない: STTが設定されており、プロバイダーに到達可能であることを確認してください。