QQ ボット

QQ Bot は、公式 QQ Bot API（WebSocket Gateway）を介して OpenClaw に接続します。 主なチャット形式は C2C プライベートチャットとグループでの @ メンションで、リッチ メディア（画像、音声、動画、ファイル）に対応しています。ギルドチャンネルのメッセージは テキストとリモート URL の画像のみをサポートします。ギルドチャンネルでは、音声、動画、 ファイルのアップロード、ローカル画像および Base64 画像は利用できません。リアクションと スレッドは、いずれの場所でもサポートされません。

状態：公式にダウンロード可能な Plugin。

インストール

openclaw plugins install @openclaw/qqbot

セットアップ

1. QQ Open Platform にアクセスし、スマートフォンの QQ で QR コードを スキャンして登録またはログインします。
2. Create Bot をクリックして、新しい QQ Bot を作成します。
3. Bot の設定ページで AppID と AppSecret を見つけ、コピーします。

4. チャンネルを追加します。

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

5. Gateway を再起動します。

対話形式のセットアップ：

openclaw channels add

ウィザードでは、AppID/AppSecret を手動入力する代わりに QR コードでバインドすることもできます。 対象の 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 オブジェクトを使用してください。

アクセスポリシー

• allowFrom / groupAllowFrom は、C2C / グループのコンテキストで Bot とチャットできるユーザーを制限します。 dmPolicy / groupPolicy（open | allowlist | disabled）は、適用モードを制御します。 allowFrom に具体的な（ワイルドカードではない）エントリがある場合、dmPolicy のデフォルトは allowlist になり、それ以外の場合は open になります。 groupAllowFrom または allowFrom のいずれかに具体的なエントリがある場合、 groupPolicy のデフォルトは allowlist になり、それ以外の場合は open になります。
• 「認可：許可リスト」のスラッシュコマンドには、dmPolicy / groupPolicy に関係なく、 allowFrom（グループからの実行では groupAllowFrom）にワイルドカードではない明示的な エントリが必要です。スラッシュコマンドを参照してください。

複数アカウントのセットアップ

1 つの 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",        },      },    },  },}

各アカウントは、appId をキーとして、独立した WebSocket 接続、API クライアント、 トークンキャッシュを所有します。ログ行には所有元のアカウント ID が付与されるため、 1 つの Gateway で複数の Bot を実行しても診断情報を個別に識別できます。

CLI で 2 つ目の Bot を追加します。

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

グループチャット

グループサポートでは、表示名ではなく QQ グループの OpenID を使用します。Bot をグループに追加し、 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 エントリは、1 つのグループについてそのデフォルトを上書きします。グループ設定：

commandLevel には次を指定できます。

古い QQBot の toolPolicy エントリは廃止されています。openclaw doctor --fix を実行して tools に移行してください。

アクティベーションモードは mention と always です。requireMention: true は mention に、requireMention: false は always に対応します。セッションレベルの アクティベーション上書きが存在する場合は、設定より優先されます。

受信キューはピアごとに管理されます。グループピアにはダイレクトピアより大きなキュー上限 （50 対 20）が設定されます。キューが満杯になると人間が作成したメッセージより先に Bot が作成した メッセージを削除し、通常のグループメッセージの連続を、送信元情報付きの 1 ターンにまとめます。 スラッシュコマンドは、マージバッチとは独立して 1 つずつ実行されます。

音声（STT / TTS）

STT と TTS は、優先順位に基づくフォールバックを備えた 2 段階の設定をサポートします。

{  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 秒後にタイムアウトします。Plugin 固有の 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 を設定します。ネイティブの実行承認は デフォルトで有効です。

メディアとストレージ

• 受信、送信、Gateway ブリッジのメディアは、 ~/.openclaw/media/qqbot（OPENCLAW_HOME が設定されている場合はそれに従います）配下の単一のペイロードルートを共有するため、アップロード、 ダウンロード、トランスコードキャッシュは、保護された単一のディレクトリ内に保持されます。
• C2C およびグループ宛てのリッチメディア配信は、単一の sendMedia パスを通ります。5 MiB 以上のローカルファイルとメモリ内バッファには QQ の チャンク分割アップロードエンドポイントを使用し、それより小さいペイロードとリモート URL/Base64 ソースには 単発アップロード API を使用します。
• ホットアップグレードにより、openclaw.json の書き込みが完了する前に Gateway が中断された場合、 Plugin は次回起動時に内部スナップショットから、そのアカウントで最後に確認された appId / clientSecret を復元します（意図的な設定変更を上書きすることはありません）。そのため、QR コードを再スキャンする 必要はありません。

トラブルシューティング

• Gateway が起動しない / 受信メッセージがない: appId と clientSecret が正しく、QQ Open Platform でボットが有効になっていることを確認してください。 認証情報が不足している場合は、"QQBot が設定されていません（appId または clientSecret がありません）" と表示されます。
• --token-file を使用してセットアップしても未設定と表示される: --token-file が 設定するのは AppSecret のみです。appId は、設定または QQBOT_APP_ID で引き続き指定する必要があります。
• グループ返信が集中すると衝突する: ピアのキューが満杯になった場合、受信キューは 人間が送信したメッセージより先にボットが送信したメッセージを削除し、通常の（コマンドではない）グループメッセージの 集中を、送信者情報付きの単一ターンにまとめます。そのため、ボットの会話が大量に発生しても、 人間のメッセージが処理されなくなることはありません。
• プロアクティブメッセージが届かない: ユーザーが最近やり取りしていない場合、 QQ がボットから開始されたメッセージをブロックすることがあります。
• 音声が文字起こしされない: STT が設定され、プロバイダーに 到達できることを確認してください。

関連項目

• ペアリング
• グループ
• チャンネルのトラブルシューティング