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

QQ Bot (QQ机器人)

このガイドでは、公式の QQ Bot Open Platform API を介して QQ 上に Qwen Code チャンネルを設定する方法を説明します。

前提条件

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

セットアップ

QR コードログイン

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

{
  "channels": {
    "my-qq": {
      "type": "qq"
    }
  }
}
qwen channel start my-qq
# Scan the QR code in the terminal with your QQ app

手動設定（開発者ポータル）

QQ Bot Open Platform の開発者ポータルにアプリを登録している場合は、そこから取得した認証情報を使用することもできます。

{
  "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 Open Platform のダッシュボードから、またはグループ管理者に招待してもらって、ボットを QQ グループに追加します
  3. グループメンバーは応答をトリガーするためにボットを @メンション する必要があります

QQ Bot API V2 は、ボットを @メンションしたグループメッセージのみを配信します。ボットはすべてのグループメッセージを認識しません。デフォルトでは requireMention は true であり、QQ ではそのままにしておく必要があります。

グループポリシーとメンション制限の詳細については、グループチャット を参照してください。

Markdown サポート

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

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

これは、すべての Markdown を削除する WeChat チャンネルとは逆です。QQ チャンネルでは、エージェントに完全な Markdown を使用させることができます。

トークン管理

アクセストークンは約2時間で期限切れになります。チャンネルは TTL の80%（通常約1.6時間）で自動的に更新します。更新に失敗した場合、60秒後に再試行します。

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

接続の回復力

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

ヒント

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

Telegram との主な違い

項目QQ BotTelegram
認証QR コードログインまたは AppID/AppSecretBotFather からの静的ボットトークン
Markdownネイティブ QQ Markdown（プレーンテキストフォールバック付き）エージェント Markdown からの HTML 形式
トークンライフサイクル2時間 TTL、80%で自動更新永続的ボットトークン
グループメッセージ@メンションされたメッセージのみボットに配信ボットは全メッセージを認識（プライバシーモードオフ時）
入力中インジケーター利用不可（QQ API の制限）“作業中…” メッセージ
サンドボックスモードテスト用にサポート利用不可

トラブルシューティング

ボットが応答しない

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

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

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

QR コードログインが停止する

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

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

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

長時間のダウンタイム後にトークンが期限切れになる

  • チャンネルが2時間以上オフラインになると、アクセストークンが期限切れになります。チャンネルは再接続時に新しいトークンを取得します。操作は不要です。
  • AppSecret 自体が無効な場合（例：開発者ポータルでローテーションされた場合）、appSecret フィールドを更新するか、~/.qwen/channels/<name>-credentials.json を削除して QR コードログインを再トリガーしてください。
Last updated on
Feishu (Lark)WeCom (Enterprise WeChat)