QQ ボット

QQ Bot は公式 QQ Bot API（WebSocket gateway）経由で OpenClaw に接続します。この Plugin は C2C プライベートチャット、グループ @メッセージ、リッチメディア（画像、音声、動画、ファイル）付きのギルドチャンネルメッセージに対応しています。

状態: ダウンロード可能なPlugin。ダイレクトメッセージ、グループチャット、ギルドチャンネル、メディアに対応しています。リアクションとスレッドには対応していません。

インストール

セットアップ前に QQ Bot をインストールします。

openclaw plugins install @openclaw/qqbot

セットアップ

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

AppSecret は平文では保存されません。保存せずにページを離れると、 新しいものを再生成する必要があります。

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

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

5. Gateway を再起動します。

対話型セットアップのパス:

openclaw channels addopenclaw 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",    },  },}

環境変数 SecretRef AppSecret:

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

注記:

• 環境変数のフォールバックは、デフォルトの QQ Bot アカウントにのみ適用されます。
• openclaw channels add --channel qqbot --token-file ... は AppSecret のみを提供します。AppID はすでに設定内または QQBOT_APP_ID に設定されている必要があります。
• clientSecret は平文文字列だけでなく、SecretRef 入力も受け付けます。
• レガシーな secretref:/... マーカー文字列は有効な clientSecret 値ではありません。 上の例のような構造化された SecretRef オブジェクトを使用してください。

マルチアカウントセットアップ

単一の 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 接続を起動し、独立した トークンキャッシュ（appId で分離）を維持します。

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

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

グループチャット

QQ Bot のグループチャット対応では、表示名ではなく 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 エントリは 1 つのグループについてそれらのデフォルトを上書きします。グループ 設定には次が含まれます。

• requireMention: bot が返信する前に @メンションを必須にします。デフォルト: true。
• commandLevel: グループ内で実行できる組み込みスラッシュコマンドを制御します。 デフォルト: all。この設定を省略した場合、既存の QQBot グループ動作を維持します。
• ignoreOtherMentions: bot ではなく他の誰かにメンションしているメッセージを破棄します。
• historyLimit: 次にメンションされたターンのコンテキストとして、最近の非メンショングループメッセージを保持します。無効にするには 0 を設定します。
• tools: グループ全体のツールを許可/拒否します。
• toolsBySender: 送信者ごとのグループツール上書きです。グループ を参照してください。
• name: ログとグループコンテキストで使用される分かりやすいラベルです。
• prompt: エージェントコンテキストに追加される、グループごとの動作プロンプトです。

commandLevel は次を受け付けます。

• all: 認識済みの組み込みコマンドを以前どおり利用可能にします。一部のコマンドは メニューから非表示のままになる場合がありますが、承認されたユーザーは引き続きグループ内で実行できます。
• safety: /help、/btw、/stop などの一般的なコラボレーションコマンドを許可します。 /config、/tools、/bash などの機密性の高いコマンドは プライベートチャットで実行するようユーザーに求めます。
• strict: 厳格なグループ運用に必要なグループセッション制御のみを許可します。 /stop は引き続き緊急扱いのため、承認された送信者は アクティブな実行を中断できます。

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

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

受信キューはピアごとです。グループピアではキュー上限が大きくなり、満杯時には 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 設定の上に ディープマージされます。

受信した QQ 音声添付ファイルは、raw 音声ファイルを汎用 MediaPaths から除外したまま、 音声メディアメタデータとしてエージェントに公開されます。TTS が 設定されている場合、[[audio_as_voice]] のプレーン テキスト返信は TTS を合成し、ネイティブ QQ 音声メッセージを送信します。

送信音声のアップロード/トランスコード動作は、 channels.qqbot.audioFormatPolicy でも調整できます。

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

ターゲット形式

各 bot には独自のユーザー OpenID セットがあります。Bot A が受け取った OpenID は、Bot B 経由でメッセージを送信するために 使用することはできません。

スラッシュコマンド

AI キューの前にインターセプトされる組み込みコマンド:

使用方法のヘルプを表示するには、任意のコマンドに ? を追加します（例: /bot-upgrade ?）。

管理者コマンド（/bot-me、/bot-upgrade、/bot-logs、/bot-clear-storage、/bot-streaming、/bot-approve）はダイレクトメッセージ専用で、明示的な非ワイルドカード allowFrom リストに送信者の openid が含まれている必要があります。ワイルドカード allowFrom: ["*"] はチャットを許可しますが、管理者コマンドアクセスは付与しません。グループメッセージは最初に groupAllowFrom と照合され、該当しない場合は allowFrom にフォールバックします。グループで管理者コマンドを実行すると、黙って破棄するのではなくヒントを返します。

QQ Bot の exec 承認がデフォルトの同一チャットフォールバックを使用する場合、ネイティブ承認 ボタンのクリックは、同じ明示的な非ワイルドカードのコマンド許可リストに従います。より広範なコマンドアクセスなしで 承認専用アクセスを付与するには、 channels.qqbot.execApprovals.approvers を設定します。

エンジンアーキテクチャ

QQ Bot は Plugin 内の自己完結型エンジンとして提供されます。

• 各アカウントは、appId をキーにした分離済みリソーススタック（WebSocket 接続、API クライアント、トークンキャッシュ、メディアストレージルート）を所有します。アカウント間で受信/送信状態が共有されることはありません。
• マルチアカウントロガーは、所有アカウントでログ行にタグ付けするため、1 つの gateway で複数の bot を実行しても診断を分離できます。
• 受信、送信、gateway ブリッジの各パスは、~/.openclaw/media 配下の単一のメディアペイロードルートを共有するため、アップロード、ダウンロード、トランスコードキャッシュはサブシステムごとのツリーではなく、1 つの保護されたディレクトリ配下に置かれます。
• リッチメディア配信は、C2C とグループターゲットの両方で 1 つの sendMedia パスを通ります。大容量ファイルしきい値を超えるローカルファイルとバッファは QQ のチャンクアップロードエンドポイントを使用し、それより小さいペイロードはワンショットメディア API を使用します。
• 認証情報は標準の OpenClaw 認証情報スナップショットの一部としてバックアップおよび復元できます。エンジンは復元時に、新しい QR コードペアを要求せずに各アカウントのリソーススタックを再接続します。

QR コードオンボーディング

AppID:AppSecret を手動で貼り付ける代わりに、エンジンは QQ Bot を OpenClaw にリンクする QR コードオンボーディングフローに対応しています。

1. QQ Bot セットアップパス（例: openclaw channels add --channel qqbot）を実行し、プロンプトで QR コードフローを選択します。
2. ターゲットの QQ Bot に紐付いたスマートフォンアプリで、生成された QR コードをスキャンします。
3. スマートフォンでペアリングを承認します。OpenClaw は返された認証情報を、適切なアカウントスコープ配下の credentials/ に保存します。

bot 自体によって生成された承認プロンプト（たとえば、QQ Bot API によって公開される「このアクションを許可しますか？」フロー）は、raw QQ クライアントで返信するのではなく /bot-approve で受け入れられるネイティブ OpenClaw プロンプトとして表示されます。

トラブルシューティング

• Bot が「gone to Mars」と返信する: 認証情報が設定されていないか、Gateway が起動していません。
• 受信メッセージがない: appId と clientSecret が正しいこと、および bot が QQ Open Platform で有効になっていることを確認してください。
• 自己返信が繰り返される: OpenClaw は QQ の送信 ref インデックスを bot 作成として記録し、現在の msgIdx が同じ bot アカウントと一致する受信イベントを無視します。 これにより、ユーザーが以前の bot メッセージを引用または返信できる状態を保ちながら、プラットフォームのエコーループを防ぎます。
• --token-file でセットアップしても未設定と表示される: --token-file は AppSecret のみを設定します。設定内の appId または QQBOT_APP_ID が引き続き必要です。
• プロアクティブメッセージが届かない: ユーザーが最近操作していない場合、QQ が bot 起点のメッセージをインターセプトすることがあります。
• 音声が文字起こしされない: STT が設定されており、プロバイダーに到達できることを確認してください。

関連

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