Skip to Content
ユーザーガイド機能チャンネルQQ Bot (QQ机器人)

QQ Bot (QQ机器人)

このガイドでは、公式 QQ Bot オープンプラットフォーム API を使って Qwen Code の QQ チャンネルをセットアップする方法を説明します。

前提条件

  • QQ アカウント（QR コードをスキャンするためのモバイルアプリ）

セットアップ

QR コードログイン

チャンネルを起動します。初回起動時に QR コードが表示されます。QQ アプリでスキャンして有効化してください。開発者アカウントや手動登録は不要です。認証情報は自動的に保存・再利用されます。

{
  "channels": {
    "my-qq": {
      "type": "qq"
    }
  }
}
qwen channel start my-qq
# ターミナルに表示された QR コードを QQ アプリでスキャンしてください

手動設定（デベロッパーポータル）

QQ Bot オープンプラットフォーム でアプリを登録済みの場合は、そのデベロッパーポータルの認証情報を使うこともできます。

{
  "channels": {
    "my-qq": {
      "type": "qq",
      "appID": "YOUR_APP_ID",
      "appSecret": "$QQ_APP_SECRET"
    }
  }
}

シークレットを環境変数に設定します。

export QQ_APP_SECRET=<your-app-secret>

設定

{
  "channels": {
    "my-qq": {
      "type": "qq",
      "appID": "YOUR_APP_ID",
      "appSecret": "$QQ_APP_SECRET",
      "sandbox": false,
      "senderPolicy": "open",
      "sessionScope": "user",
      "cwd": "/path/to/your/project",
      "instructions": "你是一个通过 QQ Bot 对话的 AI 助手。回复控制在 2000 字符以内。",
      "blockStreaming": "on",
      "groupPolicy": "disabled",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

QQ 固有のオプション

オプションデフォルト説明
appID—デベロッパーポータルの QQ Bot AppID。省略時は QR コードログインが使用されます。
appSecret—QQ Bot AppSecret。$ENV_VAR 構文に対応。省略時は QR コードログインが使用されます。
sandboxfalsetrue に設定すると QQ サンドボックス API 環境（sandbox.api.sgroup.qq.com）を使用します。

標準チャンネルオプション（チャンネル概要を参照）もすべてサポートされています: senderPolicy, allowedUsers, sessionScope, cwd, instructions, groupPolicy, groups, dispatchMode, blockStreaming, blockStreamingChunk, blockStreamingCoalesce

起動

# QQ チャンネルのみ起動
qwen channel start my-qq
 
# または設定済みのすべてのチャンネルをまとめて起動
qwen channel start

QQ を開いてボットにメッセージを送信してください。チャット画面に返答が届くはずです。

グループチャット

QQ グループでボットを使用するには:

  1. チャンネル設定の groupPolicy を "allowlist" または "open" に設定する
  2. QQ Bot オープンプラットフォームのダッシュボードから、またはグループ管理者にボットを招待してもらい、QQ グループに追加する
  3. グループメンバーは返答をトリガーするためにボットを @メンション する必要がある

QQ Bot API V2 はボットを @メンションしたグループメッセージのみ配信します。ボットはすべてのグループメッセージを受信できるわけではありません。デフォルトで requireMention は true になっており、QQ ではそのままにしておくことを推奨します。

グループポリシーとメンションゲーティングの詳細は グループチャット を参照してください。

Markdown サポート

QQ Bot チャンネルは Markdown 形式（msg_type=2）をサポートしています。エージェントの Markdown 応答はそのまま送信され、QQ 側でリッチフォーマット（太字、斜体、コードブロック、リンク、リスト）としてレンダリングされます。

QQ サーバーが何らかの理由で Markdown メッセージを拒否した場合、チャンネルは自動的にプレーンテキストで再送信します。ボットの Markdown 機能がサーバー側で制限されている場合でも、メッセージは必ず届きます。

これは WeChat チャンネル（すべての Markdown が除去される）とは逆の挙動です。QQ チャンネルではエージェントに Markdown をフル活用させることができます。

トークン管理

アクセストークンは約 2 時間で失効します。チャンネルは TTL の 80%（通常 約 1.6 時間）のタイミングで自動的にトークンを更新します。更新に失敗した場合は 60 秒後に再試行されます。

WebSocket の再接続をまたいでもトークン更新は継続されます。AppID と AppSecret が有効である限り、トークンの失効によってチャンネルがオフラインになることはありません。

接続の堅牢性

  • 自動再接続: WebSocket が切断された場合、指数バックオフ（最大 20 回試行、再試行間隔は最大 30 秒）でリトライします
  • セッション再開: WebSocket が一時的に切断された場合、QQ の RESUME オペコードを使用してセッションを復元し、処理中のメッセージが失われません
  • サーバー跨ぎのコンテキスト継続: チャットセッションとルーティング状態はディスクに永続化されます。デーモンが再起動しても会話は中断した時点から再開されます
  • ハートビート監視: HEARTBEAT_ACK タイムアウトを検出して強制的に再接続し、ゾンビ接続を防止します
  • メッセージ重複排除: 再接続後に再生されたメッセージを検出してスキップします

ヒント

  • Markdown を積極的に活用する — WeChat と異なり、QQ は Markdown をネイティブにレンダリングします。太字、コードブロック、リスト、リンクがすべて機能します。
  • 返答は 2000 文字以内に収める — それより長い返答は自動的に分割されます。instructions に文字数のヒントを追加すると、エージェントが簡潔に返答するようになります。
  • テストにはサンドボックスを使用する — 開発中は "sandbox": true を設定してサンドボックス API を使用します。本番環境のメッセージには影響しません。
  • アクセスを制限する — 特定の QQ ユーザーのみに制限するには senderPolicy: "allowlist" を使用し、CLI から新しいユーザーを承認するには "pairing" を使用します。詳細は DM ペアリング を参照してください。

Telegram との主な違い

項目QQ BotTelegram
認証QR コードログインまたは AppID/AppSecretBotFather による静的ボットトークン
Markdownネイティブ QQ Markdown（プレーンテキストフォールバックあり）エージェントの Markdown から HTML 形式に変換
トークンライフサイクル2 時間 TTL、80% のタイミングで自動更新永続的なボットトークン
グループメッセージ@メンションされたメッセージのみボットに配信ボットはすべてのメッセージを受信（プライバシーモードオフ時）
タイピングインジケーター非対応（QQ API の制限）「Working…」メッセージ
サンドボックスモードテスト用にサポート非対応

トラブルシューティング

ボットが返答しない

  • ターミナルの出力でエラーを確認する
  • チャンネルが動作しているか確認する（qwen channel status）
  • senderPolicy: "allowlist" を使用している場合、自分の QQ ユーザー ID が allowedUsers に含まれているか確認する
  • 初回起動時はターミナルに QR コードが表示されます。QQ アプリでスキャンしてください

グループでボットが返答しない

  • groupPolicy が "allowlist" または "open" に設定されているか確認する（デフォルトは "disabled"）
  • ボットを @メンションする必要があります — QQ はボットをタグ付けしたメッセージのみ配信します
  • ボットがグループに追加されているか確認する

QR コードログインが進まない

  • QR コードはターミナルに表示されます。QQ モバイルアプリ（マイページ → スキャン）でスキャンしてください
  • QR コードが期限切れ（通常数分）になった場合は、チャンネルを再起動して新しい QR コードを取得してください

Markdown メッセージがプレーンテキストで表示される

  • QQ サーバーが Markdown メッセージを拒否し、チャンネルがサイレントにプレーンテキストにフォールバックした可能性があります。ターミナルで "Markdown rejected" のログメッセージを確認してください
  • QQ Bot オープンプラットフォームでは通常発生しませんが、ボットの Markdown 機能がサーバー側で制限されている場合に起こることがあります

長時間オフライン後にトークンが失効している

  • チャンネルが 2 時間以上オフラインだった場合、アクセストークンが失効している可能性があります。チャンネルは再接続時に新しいトークンを取得します。何も操作は不要です
  • AppSecret 自体が無効（デベロッパーポータルでローテーションされたなど）の場合は、appSecret フィールドを更新するか、~/.qwen/channels/<name>-credentials.json を削除して QR コードログインを再トリガーしてください
Last updated on
Feishu (Lark)フック