QQBot OpenClaw 設定ガイド
このガイドでは、QQBot OpenClaw チャンネルを通じて Nekro Agent を QQ 開放プラットフォーム公式ボット（グループ / 個人チャット）に接続する方法を説明します。
これは Nekro Agent を QQ に接続するための公式チャンネル方式です。QQ 開放プラットフォームの OpenClaw エントリーでボットを作成します。これは OneBot V11 / NapCat のように「QQ アカウントをログインしてプロトコルクライアントを動かす」方式とは異なります。 前者は公式ボットアプリケーションであり、身分はプラットフォームが割り当てる openid であって、自分の QQ 番号ではありません。
始める前の準備
- Nekro Agent を導入済みで、WebUI を開けること
- QQ 開放プラットフォームにログインするためのモバイル QQ アカウントを持っていること
- Nekro Agent のアクセスアドレス（例：
http://<サーバーIP>:8021）を知っていること
ステップ 1：QR コードをスキャンしてボットを作成
- Nekro Agent WebUI を開く
アダプター->QQBot OpenClawに移動オンボーディング（onboarding）ページを開く- 右側の QR コードをモバイル QQ でスキャンし、QQ 開放プラットフォームの OpenClaw 専用エントリーに入る （エントリーアドレス：https://q.qq.com/qqbot/openclaw/index.html）
- ログイン後、画面の指示に従ってボットを作成
ヒント
QR コードをスキャンするのはプラットフォームのエントリーを開いてボットを作るためだけで、Nekro がログイン済みになるわけではありません。実行時には次のステップ 2 で取得した認証情報を入力する必要があります。
ステップ 2：認証情報をコピー
ボットを作成すると、ページに以下の情報が表示されます。
- AppID（
APP_ID）：ボットのアプリケーション ID - AppSecret（
CLIENT_SECRET）：ボットのシークレット。OpenClaw QQBot Gateway の AccessToken を取得するために使用
⚠️ AppSecret はプラットフォームページを離れると再び平文で表示されない場合があります。 すぐにコピーして安全に保管してください。
ステップ 3：認証情報を入力して接続
- Nekro Agent WebUI に戻る
QQBot OpenClawアダプターの設定ページを開くアダプターを有効にするをオンにするAPP_IDとCLIENT_SECRETを入力- アダプター設定を保存
- Nekro Agent を再起動（または
オンボーディングページの再接続をクリックして Gateway を再接続）
保存して再起動すると、オンボーディング ページ上部のステータスは 未設定 から 設定済み -> 実行中 -> 接続済み へ進みます。
各項目の入力方法
| 項目 | 説明 |
|---|---|
APP_ID | QQ 開放プラットフォーム OpenClaw エントリーでボットを作成後に取得する AppID。必須、変更後は再起動が必要 |
CLIENT_SECRET | ボット作成後に取得する AppSecret。機密項目。Gateway AccessToken の取得に使用、変更後は再起動が必要 |
GROUP_POLICY | グループポリシー：open はすべてのグループを受信、allowlist はホワイトリストのみ、disabled はグループを無効化 |
GROUP_ALLOW_FROM | GROUP_POLICY=allowlist のときに許可する group_openid の一覧。* で全許可 |
DEFAULT_REQUIRE_MENTION | 通常のグループメッセージは既定ではコンテキストとしてのみ記録し、トリガーしない。オフにするとトリガーする（既定オン） |
IGNORE_OTHER_MENTIONS | 「@」を含むが本ボットを「@」していないグループメッセージを無視するか |
GROUP_HISTORY_LIMIT | グループコンテキストの記録上限（既定 50、OpenClaw 既定に従う） |
PROACTIVE_SEND_ENABLED | 最近のインバウンド/参照メッセージがない場合でも能動的に送信を試みる（既定オン） |
グループのトリガールール
QQBot OpenClaw のグループメッセージは既定ではコンテキストとしてのみ記録され、自動返信しません。返信をトリガーするには：
- グループで
本ボットを @ - または、本ボットが送信した以前のメッセージを
引用
これはボットが大規模グループで連投するのを防ぐためです。通常のグループメッセージのトリガーは上記の DEFAULT_REQUIRE_MENTION で調整できます。
メンテナンス操作
オンボーディング ページの メンテナンス 領域では以下が可能です。
トークンをテスト：現在のCLIENT_SECRETが AccessToken を取得できるか確認再接続：Gateway バックグラウンド接続を再起動セッションをクリア：短期セッション状態をクリア参照インデックスをクリア：メッセージ引用に使う参照インデックスをクリア
設定完了後に表示されるもの
- 個人チャット：
qqoc-c2c:{user_openid} - グループチャット：
qqoc-group:{group_openid}
身分 ID（
openid）は QQ 開放プラットフォーム / OpenClaw が割り当てるものです。伝統的な QQ 番号ではありません。 これは正常で、手動変更は不要です。
よくある質問
ステータスが 未設定 のまま
設定ページでAPP_ID/CLIENT_SECRETを保存したか確認- 保存後に Nekro Agent を再起動したか確認
- 再起動後に
オンボーディングページで状態を更新をクリック
設定済み / 実行中 だが 接続済み にならない
オンボーディングページでトークンをテストをクリックし、認証情報が有効かを確認- 無効な場合はプラットフォームから AppSecret を再コピーして更新
- プラットフォーム側でボットが公開状態かを確認
グループメッセージに返信されない
- 本ボットが実際に公式ボットチャンネルにあり、グループに居ることを確認
- グループで
本ボットを @またはボットのメッセージを引用してトリガー GROUP_POLICYがdisabledでないか、allowlistの制限に該当していないか確認
次のステップ
- アダプターは設定済みだがボットが返信しない？ システム設定 でチャットモデルグループを 1 つ以上設定
- 「QQ アカウントのログイン + プロトコルクライアント」方式で QQ に接続したい？ OneBot V11 / NapCat
- ボットにペルソナを設定したい？ ペルソナのヒント