> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# QQ Bot

> CowAgent を QQ Bot に接続する（WebSocket ロングコネクション）

> QQ オープンプラットフォームの Bot API を介して CowAgent を接続し、QQ のダイレクトメッセージ、グループチャット（@bot）、ギルドチャネルメッセージ、ギルド DM に対応します。パブリック IP は不要で、WebSocket ロングコネクションを使用します。

<Note>
  QQ Bot は QQ オープンプラットフォームを通じて作成します。WebSocket ロングコネクションでメッセージを受信し、OpenAPI でメッセージを送信します。パブリック IP やドメインは不要です。
</Note>

## 1. QQ Bot の作成

> [QQ オープンプラットフォーム](https://q.qq.com)にアクセスし、QQ でサインインします。未登録の場合は、先に[アカウント登録](https://q.qq.com/#/register)を完了してください。

1.[QQ オープンプラットフォーム - Bot 一覧](https://q.qq.com/#/apps)に移動し、**Bot を作成**をクリックします：

<img src="https://cdn.link-ai.tech/doc/20260317162900.png" width="800" />

2.Bot 名、アバター、その他の基本情報を入力して作成を完了します：

<img src="https://cdn.link-ai.tech/doc/20260317163005.png" width="800" />

3.Bot 設定ページに入り、**開発管理**に移動して以下の手順を完了します：

* **AppID**（Bot ID）をコピーして保存します
* **AppSecret**（Bot Secret）を生成して保存します

<img src="https://cdn.link-ai.tech/doc/20260317164955.png" width="800" />

## 2. 設定と起動

### 方法 A: Web コンソール

プログラムを起動し、Web コンソール（ローカルアクセス: [http://127.0.0.1:9899/）を開きます。\*\*チャネル\*\*タブに移動し、\*\*チャネルを接続\*\*をクリックして](http://127.0.0.1:9899/）を開きます。**チャネル**タブに移動し、**チャネルを接続**をクリックして) **QQ Bot** を選択し、前のステップで取得した AppID と AppSecret を入力して接続をクリックします。

<img src="https://cdn.link-ai.tech/doc/20260317165425.png" width="800" />

### 方法 B: 設定ファイル

`config.json` に以下を追加します：

```json theme={null}
{
  "channel_type": "qq",
  "qq_app_id": "YOUR_APP_ID",
  "qq_app_secret": "YOUR_APP_SECRET"
}
```

| パラメータ           | 説明                                          |
| --------------- | ------------------------------------------- |
| `qq_app_id`     | QQ Bot の AppID。オープンプラットフォームの開発管理で確認できます     |
| `qq_app_secret` | QQ Bot の AppSecret。オープンプラットフォームの開発管理で確認できます |

設定後、プログラムを起動します。ログに `[QQ] ✅ Connected successfully` と表示されれば接続成功です。

## 3. 使い方

QQ オープンプラットフォームで、**管理 → 利用範囲とメンバー**に移動し、「グループとメッセージリストに追加」の QR コードを QQ クライアントでスキャンして Bot とのチャットを開始します：

<img src="https://cdn.link-ai.tech/doc/20260317165947.png" width="800" />

チャット例:

<img src="https://cdn.link-ai.tech/doc/20260317171508.png" width="800" />

## 4. 対応機能

> 注意: グループチャットやギルドチャネルで QQ Bot を使用するには、公開審査を完了し、利用範囲の権限を設定する必要があります。

| 機能                | 状態                    |
| ----------------- | --------------------- |
| QQ ダイレクトメッセージ     | ✅                     |
| QQ グループチャット（@bot） | ✅                     |
| ギルドチャネル（@bot）     | ✅                     |
| ギルド DM            | ✅                     |
| テキストメッセージ         | ✅ 送受信                 |
| 画像メッセージ           | ✅ 送受信（グループ・ダイレクト）     |
| ファイルメッセージ         | ✅ 送信（グループ・ダイレクト）      |
| スケジュールタスク         | ✅ 能動的プッシュ（ユーザーあたり月4回） |

## 5. 注意事項

* **受動メッセージの制限**: QQ ダイレクトメッセージの返信は60分間有効です（1メッセージあたり最大5回返信可能）。グループチャットの返信は5分間有効です。
* **能動メッセージの制限**: ダイレクトメッセージとグループチャットの両方で、月あたりの能動メッセージは4件までです。スケジュールタスク機能を使用する際はこの点にご注意ください。
* **イベント権限**: デフォルトでは `GROUP_AND_C2C_EVENT`（QQ グループ/ダイレクト）と `PUBLIC_GUILD_MESSAGES`（ギルド公開メッセージ）がサブスクライブされています。追加の権限が必要な場合は、オープンプラットフォームで申請してください。