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 は config または QQBOT_APP_ID にすでに設定されている必要があります。
• clientSecret は平文文字列、ファイルパス（clientSecretFile）、 または構造化された SecretRef オブジェクトを受け付けます。
• 従来の secretref:... / secretref-env:... マーカー文字列は clientSecret では拒否されます。代わりに構造化された SecretRef オブジェクトを使用してください。

​

アクセスポリシー

• allowFrom / groupAllowFrom は、C2C / グループコンテキストで bot とチャットできる相手を制限します。dmPolicy / groupPolicy（open | allowlist | disabled） は適用モードを制御します。dmPolicy は、allowFrom に具体的な（ワイルドカードでない）エントリがあると allowlist にデフォルト設定され、それ以外は open になります。 groupPolicy は、groupAllowFrom または allowFrom のいずれかに具体的なエントリがあると allowlist にデフォルト設定され、それ以外は open になります。
• 「Auth: allowlist」の slash commands には、 dmPolicy / groupPolicy に関係なく、allowFrom（またはグループ呼び出しでは groupAllowFrom）に明示的な非ワイルドカードのエントリが必要です。 slash commands を参照してください。

​

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

{
  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

​

ターゲット形式

​

Slash commands

​

メディアとストレージ

• 受信、送信、Gateway ブリッジのメディアは、~/.openclaw/media/qqbot（OPENCLAW_HOME が設定されている場合はそれに従う）配下の 1 つのペイロードルートを共有するため、アップロード、ダウンロード、トランスコードキャッシュは 1 つの保護されたディレクトリ配下に保たれます。
• C2C とグループターゲットへのリッチメディア配信は、1 つの sendMedia パスを通ります。5 MiB 以上のローカルファイルとメモリ内バッファは QQ のチャンクアップロードエンドポイントを使い、それより小さいペイロードとリモート URL/Base64 ソースはワンショットアップロード 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 が設定され、プロバイダーに到達できることを確認してください。

​

関連

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