QQ ボット

​

インストール

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

​

設定

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecret: "YOUR_APP_SECRET",
    },
  },
}

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecretFile: "/path/to/qqbot-secret.txt",
    },
  },
}

{
  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, // DM で QQ 公式の C2C stream_messages API を使用
      },
    },
  },
}

• streaming.mode: "off" は、アカウントのブロックストリーミングを無効にします。
• streaming.nativeTransport: true は、QQ 公式の stream_messages API を介して C2C（DM）の返信をストリーミングします。グループおよびチャンネルのターゲットには影響しません。
• 従来の streaming: true|false スカラー値と streaming.c2cStreamApi キーは、openclaw doctor --fix によってこの形式へ移行されます。
• /bot-streaming on|off を使用すると、DM から同じ設定を切り替えられます。

​

アクセスポリシー

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

​

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

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

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

​

グループチャット

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

​

音声（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" },
            },
          },
        },
      },
    },
  },
}

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

​

ターゲット形式

​

スラッシュコマンド

​

メディアとストレージ

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

​

トラブルシューティング

• Gateway が起動しない / 受信メッセージがない: appId と clientSecret が正しいこと、および QQ Open Platform でボットが有効になっていることを確認してください。 認証情報がない場合は「QQBot not configured (missing appId or clientSecret)」と表示されます。
• --token-file で設定しても未設定と表示される: --token-file は AppSecret のみを設定します。appId は引き続き設定または QQBOT_APP_ID で指定する必要があります。
• 突発的なグループ返信が衝突する: ピアのキューがいっぱいになると、受信キューは人間が作成した メッセージより先にボットが作成したメッセージを除去し、通常の（コマンドではない）グループメッセージの バーストを送信者情報付きの 1 ターンに統合します。そのため、大量のボットチャットによって 人間のメッセージが処理されなくなることはありません。
• 能動的なメッセージが届かない: ユーザーが最近やり取りしていない場合、 QQ がボットから開始されたメッセージをブロックすることがあります。
• 音声が文字起こしされない: STT が設定され、プロバイダーに 到達できることを確認してください。

​

関連項目

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