---
title: QQ Bot
description: 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/）を開きます。**チャネル**タブに移動し、**チャネルを接続**をクリックして **QQ Bot** を選択し、前のステップで取得した AppID と AppSecret を入力して接続をクリックします。

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

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

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

```json
{
  "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`（ギルド公開メッセージ）がサブスクライブされています。追加の権限が必要な場合は、オープンプラットフォームで申請してください。