OpenClawでQQ Botを構築：5分でメッセージ連携を完了

チャットボットを開発していると、プラットフォームごとの API 仕様の違いや、認証情報の管理に頭を悩ませることがよくありますよね。特に、大規模なユーザー基盤を持つプラットフォームへの接続は、設定が複雑になりがちです。

OpenClaw を使えば、QQ Bot との連携もスムーズに進めることができます。公式の API を活用して、メッセージのやり取りからメディア送信まで、効率的に構築する方法を見ていきましょう。

QQ Bot

QQ Bot は、公式の QQ Bot API（WebSocket gateway）を介して OpenClaw に接続します。このプラグインは、C2C プライベートチャット、グループでの @メッセージ、およびリッチメディア（画像、音声、ビデオ、ファイル）を含むギルドチャンネルメッセージをサポートしています。

ステータス：同梱されているチャンネルプラグインです。ダイレクトメッセージ、グループチャット、ギルドチャンネル、およびメディアがサポートされています。Reactions と threads はサポートされていません。

OpenClaw に同梱

現在の OpenClaw のインストールには QQ Bot が同梱されています。通常のセットアップでは、別途 openclaw plugins install を実行するステップは必要ありません。

セットアップ

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 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 入力も受け入れます。

マルチアカウント設定

単一の 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"

音声 (STT / TTS)

STT と TTS は、優先順位付きの 2 レベル設定をサポートしています：

設定	プラグイン固有の設定	フレームワークのフォールバック
STT	channels.qqbot.stt	tools.media.audio.models[0]
TTS	channels.qqbot.tts	messages.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	ギルドチャンネル

各 bot は独自のユーザー OpenID セットを持っています。Bot A で受信した OpenID を使用して Bot B 経由でメッセージを送信することはできません。

スラッシュコマンド

AI キューに入る前にインターセプトされる組み込みコマンドです：

コマンド	説明
/bot-ping	レイテンシテスト
/bot-version	OpenClaw フレームワークのバージョンを表示
/bot-help	すべてのコマンドをリスト表示
/bot-upgrade	QQBot アップグレードガイドのリンクを表示
/bot-logs	最近の Gateway ログをファイルとしてエクスポート

コマンドに ? を付けると、使い方のヘルプが表示されます（例：/bot-upgrade ?）。

トラブルシューティング

• bot が “gone to Mars” と返信する: 認証情報が設定されていないか、Gateway が起動していません。
• インバウンドメッセージが届かない: appId と clientSecret が正しいこと、および QQ Open Platform で bot が有効になっていることを確認してください。
• --token-file でセットアップしても未設定と表示される: --token-file は AppSecret のみを設定します。設定ファイルまたは QQBOT_APP_ID に appId を設定する必要があります。
• プロアクティブメッセージが届かない: ユーザーが最近対話していない場合、QQ が bot 起点のメッセージを遮断することがあります。
• 音声が文字起こしされない: STT が設定されており、プロバイダーにアクセスできることを確認してください。

AI Setup Assistant