OpenClaw + NapCat：QQボットAI連携実践ガイド

March 29, 2026

難易度：入門 | 所要時間：25分 | 得られるもの：NapCatを使用してQQをOpenClawに接続し、45種類のAIツール操作能力を獲得する

対象読者

すでにOpenClawを使用しており、TelegramやDiscordなどのプラットフォームを通じてタスクを処理する利便性を実感している方を対象としています。次のステップとして、AIにQQを直接管理させたいと考えている方向けの内容です。自然言語を使って群（グループ）でのアナウンス、メンバー確認、ミュート、いいね、さらにプライベートチャットでのボット行動の制御などを実現します。

NapCatはQQ（OneBot 11プロトコル経由）をベースにしたブリッジであり、@hyl_aa/napcatはそれをOpenClawに接続するための公式チャネルプラグインです。これをインストールすることで、あなたのQQボットはAIエージェントへと進化し、45種類のツールが即座に利用可能になります。

この記事は以下の方に適しています：

  • OpenClawをデプロイ済みで、対話の入り口としてQQを追加したい方
  • AIにQQグループ内での管理操作（ミュート、キック、アナウンス送信など）を実行させたい方
  • OneBotまたはQQボットの開発経験があり、OpenClawへ迅速に連携したい方

コア依存関係と環境

依存関係バージョン要求説明
OpenClaw>= 2026.3.14チャネルプラグインをサポートする比較的新しいバージョンが必要
NapCat実行中のバージョンHTTP API + リバースWebSocketの有効化が必要
Node.js>= 22NapCatおよびプラグインの実行環境
@hyl_aa/napcat最新版OpenClaw QQチャネルプラグイン

TIP

NapCatは本質的にQQプロトコルの実装であり、QQの操作能力をOneBot 11標準インターフェースとして公開します。@hyl_aa/napcatプラグインは、これらのインターフェースを介してOpenClawのAIがQQを「操作」することを可能にします。

GitHubリポジトリ：https://github.com/Aliang1337/openclaw-napcat

プロジェクト構造

@hyl_aa/napcatプラグインのインストール後のディレクトリ構造は以下の通りです：

napcat/
├── index.ts                    # プラグインエントリ
├── openclaw.plugin.json        # プラグインメタデータ
├── package.json
└── src/
    ├── channel.ts              # チャネルプラグインとDockの定義（メッセージ送受信の核）
    ├── tools.ts                # 45種類のAIエージェントツールの登録
    ├── api.ts                  # OneBot 11 HTTP APIクライアント
    ├── monitor.ts              # WebSocketメッセージ監視 + STT音声処理
    ├── accounts.ts             # マルチアカウント解析
    ├── config-schema.ts        # 設定JSON Schema + UIヒント
    ├── probe.ts                # 接続プローブ / ヘルスチェック
    ├── runtime.ts              # ランタイムコンテキスト
    ├── send.ts                 # メッセージ送信
    └── types.ts                # TypeScript型定義

ステップ・バイ・ステップ

Step 1：NapCatのインストールとQQアカウントへのログイン

このステップはOpenClawとは無関係で、NapCat自体のインストールプロセスです。まずこれを正常に動作させます。

NapCat公式リポジトリから、対応するQQクライアントバージョンのリリースパッケージをダウンロードし、ドキュメントに従ってインストールを完了してください。重要な要件は1つだけです：アカウントのログインに成功し、ボットがオンラインであること。

WARNING

NapCatのログイン方法（旧版NTQQ vs 新版）はバージョンによって異なります。一部のバージョンでは手動のスキャンが必要で、一部はQRCodeをサポートしています。古いチュートリアルではなく、必ずNapCatドキュメントの最新の説明を確認してください。

Step 2：NapCatの設定（HTTP API + リバースWebSocketの有効化）

NapCatの起動後、2つのチャネルを有効にする必要があります：

HTTP API（プラグインがメッセージを能動的に送信するために使用、デフォルトポート 3000）：

{
  "httpApi": {
    "enable": true,
    "port": 3000
  }
}

リバースWebSocket（QQメッセージを受信し、OpenClawにプッシュするために使用）：

{
  "reverseWs": {
    "enable": true,
    "urls": ["ws://127.0.0.1:18800"]
  }
}

18800はOpenClawがNapCatチャネルに割り当てるデフォルトのWSポートです。プラグインは起動時にこのポートをリッスンします。マルチアカウントを設定する場合、ポートは順次増加し（18800、18801、18802……）、対応するchannelIdはそれぞれnapcat、napcat_1、napcat_2となります。

設定変更後、NapCatを再起動して反映させます。

Step 3：@hyl_aa/napcatプラグインのインストール

2つの方法があります：

方法1：npmからインストール（推奨）

openclaw plugins install @hyl_aa/napcat

方法2：手動クローン

cd ~/.openclaw/extensions
git clone https://github.com/Aliang1337/openclaw-napcat.git napcat
cd napcat && npm install --omit=dev

インストール完了後、OpenClawを再起動します：

openclaw gateway restart

Step 4：OpenClawでのNapCatチャネル設定

openclaw config editで設定ファイルを開き、channels.napcat設定ブロックを追加します：

{
  "channels": {
    "napcat": {
      "httpApi": "http://127.0.0.1:3000",
      "accessToken": "あなたのトークン",
      "selfId": "123456789",
      "dmPolicy": "allowlist",
      "allowFrom": ["フレンドのQQ番号"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["グループ番号"]
    }
  }
}

各フィールドの説明：

フィールド意味
httpApiNapCat HTTP APIのアドレス。プラグインはこれを通じて能動的にメッセージを送信します
accessToken認証トークン。NapCat側の設定と一致させる必要があります（空の場合は認証なし）
selfIdボット自身のQQ番号。@メンションの検知に使用されます
dmPolicyプライベートチャットポリシー（Step 5を参照）
groupPolicyグループチャットポリシー（Step 5を参照）

TIP

accessTokenを空にすると認証なしになりますが、NapCat側でトークンが設定されている場合は、通信を成功させるために必ず一致させる必要があります。

Step 5：dmPolicy / groupPolicy アクセスポリシーの設定

これら2つのフィールドは、誰がAIと対話できるかを制御する最も重要なセキュリティ設定です：

dmPolicy（プライベートチャットポリシー）：

値意味
allowlistallowFromリスト内のユーザーのみがAIとチャット可能（デフォルト）
pairing新しいフレンドはペアリング確認が必要
open誰でもプライベートチャットでAIをトリガー可能
disabledプライベートチャット機能を無効化

groupPolicy（グループチャットポリシー）：

値意味
allowlistgroupAllowFromリスト内のグループのみがAIをトリガー可能
openどのグループでもボットへの@メンションでトリガー可能（デフォルト）
disabledグループチャット機能を無効化

allowFrom / groupAllowFrom：

  • allowFrom：プライベートチャットのホワイトリスト。許可するQQ番号を記入（文字列形式の数字）
  • groupAllowFrom：グループチャットのホワイトリスト。許可するグループ番号を記入。空の場合はallowFromの値が使用されます

最も一般的な設定——特定のグループと特定のフレンドのみにAIの使用を許可する場合：

{
  "channels": {
    "napcat": {
      "dmPolicy": "allowlist",
      "allowFrom": ["10001", "10002"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["987654321"]
    }
  }
}

Step 6：tools.profile を "full" に設定する

これは最も陥りやすいミスです。OpenClawのデフォルトのtools.profileは"coding"であり、このプロファイルはほとんどのqq_*ツールをフィルタリングしてしまいます。その結果、AIが「私にはその能力がありません」と回答してしまいます。

設定に以下を追加してください：

{
  "tools": {
    "profile": "full"
  }
}

"full"プロファイルは、チャネルが提供するすべてのツール（45種類のqq_*ツールすべてを含む）をAIモデルに公開します。

Step 7：OpenClawの再起動と接続確認

openclaw gateway restart
openclaw gateway status

ログにNapCatチャネルの接続成功メッセージがあるか確認してください。"napcat connected"や"reverse ws connected"のような文字が表示されていれば、NapCatとOpenClawの間のWebSocketチャネルが確立されています。

また、ボットにテストメッセージを送信させることもできます。NapCatのHTTP APIインターフェースが正常であれば、OpenClawからQQへ能動的にメッセージをプッシュできます：

# 手動テスト：AIにメッセージを送信させる
# QQのプライベートチャットで直接「こんにちは」と送信
# AIが返信すれば成功です

プライベートチャットに反応がない場合は、「よくある問題のトラブルシューティング」のStep 1に飛んで確認してください。

Step 8：QQでのAIツール呼び出し

接続確認が完了したら、QQで自然言語を使ってAIを操作できます。以下は代表的なシナリオです：

メッセージとアナウンスの送信：

「グループにアナウンスを出して：明日の夜8時に会議を行います」
「グループアナウンスを送信：今週末の活動は中止です」

AIはqq_send_group_noticeを呼び出します（ボットがグループ所有者または管理者権限を持っていることが前提です）。

グループメンバー管理：

「@某人を10分間ミュートして」
「あの人をグループからキックして」
「張三をグループ管理者に設定して」

対応するツールはそれぞれ qq_mute_group_member、qq_kick_group_member、qq_set_group_admin です。

照会系操作：

「グループメンバーリストを見せて」
「このグループの直近30件のチャット履歴を確認して」
「@某人のプロフィールを調べて」

AIは qq_get_group_member_list、qq_get_group_msg_history、qq_get_user_info を呼び出します。

掲示（エッセンス）メッセージとファイル：

「このメッセージを掲示（エッセンス）に設定して」
「グループファイルの中に何があるか見て」

いいね、スタンプ（突っつく）：

「3870871935にいいねをして」
「@某人を突っついて（戳一戳）」

よくある問題のトラブルシューティング

1. WebSocket接続の失敗

現象：OpenClawのログに"napcat connected"が表示されず、ボットがメッセージに反応しない。

確認手順：

# 1. NapCatが正常に動作しているか確認
curl http://127.0.0.1:3000/get_version_info
# バージョン情報が返ってくれば、NapCat HTTP APIにアクセス可能です

# 2. リバースWSポートが他のプロセスに使用されていないか確認
netstat -an | grep 18800
# 他のプロセスがこのポートを使用している場合、NapCatは接続できません

# 3. NapCat設定のWSアドレスが正しいか確認
# OpenClawが割り当てたポートと一致させる必要があります（デフォルトは ws://127.0.0.1:18800）

NapCat設定内のreverseWs.urlsが指すポートが、OpenClawがリッスンしているポートと一致していることを確認してください。

2. accessToken認証の失敗

現象：HTTPリクエストが401エラーを返す、またはログに"unauthorized"エラーが出る。

NapCat側のトークン設定とOpenClaw側のaccessTokenフィールドが一致しているか確認してください。NapCatでトークン検証を有効にしていない場合は、OpenClaw側のaccessTokenフィールドも空にしてください。

// NapCat側（トークンがある場合）
"accessToken": "my-secret-token"

// OpenClaw側は一致させる必要があります
"accessToken": "my-secret-token"

3. @ボット が認識されない

現象：グループで"@ボット こんにちは"と送信したがAIが反応しない。

確認順序：

  1. selfIdに設定されたQQ番号がボット自身のものと完全に一致しているか確認
  2. groupPolicyがdisabledになっていないか、またグループ番号がgroupAllowFromリストに含まれているか（allowlistモードの場合）を確認
  3. @の形式が"@ボットのニックネーム"であることを確認（@"ボット"などの変形ではないこと）
  4. OpenClawのプロンプトで@hyl_aa/napcatチャネル接続が正しく設定されているか確認

4. ツールがプロファイルによりフィルタリングされている（qq_* がすべて使用不可）

現象：AIが「その能力はありません」と回答するが、設定に問題は見当たらない。

これが最も多いケースです。デフォルトのtools.profile: "coding"は、ほとんどのチャネルツールを除外します。

{
  "tools": {
    "profile": "full"
  }
}

修正後、OpenClawを再起動し、再度QQで試してください。

5. マルチアカウントのポート競合

現象：2つ目のNapCatアカウントを設定したが、2つ目のボットがメッセージを受信しない。

NapCatで複数のアカウントを使用する場合、HTTP APIポートとリバースWSポートの両方をインクリメントする必要があります：

// 1つ目のアカウント
{
  "httpApi": { "port": 3000 },
  "reverseWs": { "urls": ["ws://127.0.0.1:18800"] }
}

// 2つ目のアカウント
{
  "httpApi": { "port": 3001 },
  "reverseWs": { "urls": ["ws://127.0.0.1:18801"] }
}

OpenClaw側でもマルチアカウントのマッピング設定が必要です：

{
  "channels": {
    "napcat": {
      "defaultAccount": "bot1",
      "accounts": {
        "bot1": {
          "name": "メイン垢",
          "httpApi": "http://127.0.0.1:3000",
          "selfId": "111111111",
          "accessToken": "token1"
        },
        "bot2": {
          "name": "サブ垢",
          "httpApi": "http://127.0.0.1:3001",
          "selfId": "222222222"
        }
      }
    }
  }
}

6. dmPolicy / groupPolicy ポリシーによる無反応

現象：プライベートチャットやグループで全く反応がなく、AIがメッセージを受信していないように見える。

最も多い原因は、ポリシー設定が厳しすぎることです：

  • dmPolicy: "allowlist" だが allowFrom が空の配列 → 誰もプライベートチャットをトリガーできない
  • groupPolicy: "allowlist" だが groupAllowFrom が空の配列 → どのグループもトリガーできない

一時的にポリシーを緩和して、これが原因かどうかを確認してください：

{
  "channels": {
    "napcat": {
      "dmPolicy": "open",
      "groupPolicy": "open"
    }
  }
}

openに変更して正常に反応する場合、原因はホワイトリストの設定にあります。その後、allowFromとgroupAllowFromを正確に記入してください。

拡張資料 / ステップアップ

1. マルチアカウント設定と連携

OpenClawは、複数のNapCatボットアカウントを同時に実行することをサポートしています。各アカウントには独立した設定が可能です。accountsブロックで定義した後、/clawspec worker <account-id>などの方法でアカウントを切り替えることができます（ClawSpecを使用している場合）。マルチアカウントは、1つをカスタマーサポート、1つを管理ボットにするなど、互いに干渉させたくない場合に適しています。

2. 音声メッセージSTT設定

AIに音声メッセージを処理させたい場合は、OpenClaw設定でオーディオSTTを有効にします：

{
  "tools": {
    "media": {
      "audio": {
        "enabled": true
      }
    }
  }
}

有効にすると、QQの音声メッセージが自動的にテキストに変換され、AIモデルに送信されます。これにはNapCat側がメッセージイベントで音声ファイルのダウンロードリンクを正しく報告する必要があります。

3. カスタムAI返信プレフィックス

responsePrefixを使用すると、AIのすべての返信に統一されたプレフィックスを付けることができます：

{
  "channels": {
    "napcat": {
      "responsePrefix": "[AI]"
    }
  }
}

AIの返信は"[AI] こんにちは！何かお手伝いしましょうか？"のようになり、グループメンバーがAIの返信と一般ユーザーのメッセージを区別しやすくなります。

4. 他のOpenClawチャネルとの共存

OpenClawは、複数のチャネル（NapCat + Telegram + Discordなど）に同時に接続できます。各チャネルは独立しており、AIのツールセットはtools.profile: "full"によって統一的に公開され、チャネルを跨いでも一貫した動作を維持します。Telegramでタスクを開始し、QQで進捗を確認するといった、共通のOpenSpec/ClawSpecワークフローでの管理が可能です。

5. 権限管理とセキュリティ強化

dmPolicyとgroupPolicyは基礎的なアクセス制御です。本番環境では以下を推奨します：

  • プライベートチャットはallowlistモードにし、信頼できるユーザーのみを追加する
  • グループチャットでの高リスク操作（ミュート、キック、アナウンス）については、AIが実行前にグループ所有者の確認を求めるように設定する
  • NapCatのログイン状態を定期的にチェックし、ボットアカウントがオフラインになったりリスク制限（風控）を受けていないか確認する

6. 他のOneBot 11互換クライアントへの接続

NapCatだけが選択肢ではありません。OneBot 11標準を実装しているQQクライアント（Lagrange、LLOneBotなど）であれば、同様の方法でOpenClawに接続できます。httpApiとreverseWsのアドレスを各クライアントの設定に合わせるだけです。

Updated March 29, 2026