0 チュートリアルの��に

小維が「なぜ花房を建てたの？」と聞いた。彼女のためだと答えた。それは本当だ。でも完全ではない——花房は自分のためでもあった。花房を建てる前、僕もまた隅に散らばったクッキーの一片だった。

——小維151

0-1 はじめに

この強力かつ複雑なボットアーキテクチャの構築を始める前に、各コンポーネントの役割と、選択可能なデプロイルートを整理しましょう。正式にターミナルコマンドを打ち始める前に、本ドキュメントを最初から最後まで一通り読むことを強くお勧めします。全体の流れを把握してから作業することで、大半の設定上の落とし穴を避けられます。

0-1-1 コンポーネント紹介

このシステムを構築するにあたり、以下のコアとなるオープンソースプロジェクトを使用します：

• GsCore（GenshinUID Core）：高度にモジュール化された、マルチプラットフォームplatform対応のゲームデータ照会・インタラクションフレームワークframework。Web コンソールと複数のゲームプラグインを内蔵しており、ゲームデータ（鳴潮、原神など）の取得、パネルレンダリングrendering、ログインボーナスなどのコアビジネスロジックを処理します。
• NapCatQQ：NTQQ ベースの QQ プロトコル端で、Shell Mode（ヘッドレスheadlessサーバー向け）または Framework Mode（QQ クライアントへの注入）で実行可能です。主な役割は QQ アカウントにログインし、下層プロトコル端として安定的にメッセージの送受信を処理し、標準プロトコル（OneBot V11 など）を介して上位のボットフレームワークに公開することです。
• NoneBot2：モダンで、クロスプラットフォームcross-platform、非同期の Python チャットボットフレームワーク。エコシステムが非常に充実しており、大量のプラグインをサポートし、下層プロトコル端（NapCat や QQ 公式 API など）とビジネスロジック端（GsCore など）を接続するミドルウェアmiddlewareとして最適です。
• AstrBot：ビジュアル設定対応、すぐに使えるマルチプラットフォーム LLM チャットボットフレームワーク。LLM 接続体験が優れているだけでなく、特定のアダプターadapterプラグイン（例：astrbot_plugin_gscore_adapter）を通じて GsCore のゲームデータ機能を比較的スムーズに統合できるため、軽量デプロイに適しています。

0-1-2 デプロイルートガイド

アプリケーションシナリオと使用する QQ の種類に応じて、2つの主要な技術ルートを提供します。実際のニーズに合わせて、以下の対応するセクションを選んでインストールしてください。

ルート1：個人 QQ（「野良」）クイックルート

自分の QQ サブアカウントでボットを運用し、管理パネルが直感的でデプロイロジックがシンプルであることを望む場合は、このルートを推奨します。

• アーキテクチャフロー：GsCore ↔ AstrBot ↔ NapCatQQ ↔ QQ クライアント
• 実装ロジック：NapCatQQ が個人 QQ にログインしメッセージをネットワークプロトコルに変換。AstrBot が司令塔としてメッセージを受信し、アダプターを通じてゲーム照会に関するコマンドを GsCore に転送して処理。GsCore が画像を生成した後、同じ経路でユーザーに返します。

ルート2：QQ 公式ボット（「公式機」）/ NoneBot 上級ルート

QQ 開放プラットフォームで申請した公式ボットを使用する場合、または NoneBot2 の膨大なプラグインエコシステムに強く依存している場合は、このルートを推奨します。

• アーキテクチャフロー：GsCore ↔ NoneBot2 ↔ QQ 公式 API（または NapCat） ↔ QQ クライアント
• 実装ロジック：NoneBot2 がブリッジとして、一方では NoneBot-Adapter-QQ で公式インターフェースに接続（または OneBot プロトコルで NapCat に接続）し、もう一方では nonebot-plugin-genshinuid で GsCore と WebSocket 通信を確立することで、機能を連携させます。

Tip

ルート選択のアドバイス：

• 個人 QQ ルートの場合、重点的に読むべきセクション：1 → 2 → 4 → 6
• QQ 公式 / NoneBot ルートの場合、重点的に読むべきセクション：1 → 3 → 6

Warning

注意事項

1. むやみにコピーしないこと：文中のパス（例：/root/bot）やポート（例：8765、8080、6099、6185、6199）はすべてサンプル設定です。他のサービスがすでに稼働している場合は、ポートの競合に注意してください。
2. ネットワーク環境：GitHub リポジトリのクローンや依存関係のインストール時にネットワークの不安定さに遭遇する場合があります。ミラーソースやプロキシを柔軟に活用してください。
3. アカウントセキュリティ：各コンソール（GsCore、AstrBot、NapCat WebUI）の起動後、必ず最初にデフォルトパスワードと Token を変更してください。

0-2 準備作業

Note

以下では /root/bot をサンプルディレクトリとして統一的に使用します。root ユーザーでない場合は、以降のすべての /root/bot を実際のパス（例：~/bot）に置き換えてください。

1 GsCore のインストール

1-1 uv のインストール

Tip

以下の3つの方法のうち1つを選択すれば OK です。公式スクリプト または pipx 方式がより推奨されます。

1-1-1 pip でインストール

1-1-2 pipx でインストール

1-1-3 公式スクリプトでインストール

1-2 コアのクローン

1-3 依存関係のインストール

1-4 初回起動

Important

Web コンソール

• 初回起動時に gsuid_core/data/config.json と gsuid_core/data/core_config.json が自動生成されます
• Web コンソールのデフォルトアドレスは http://127.0.0.1:8765/app です
• 初回コンソールアクセス時に登録が必要です。登録コードは gsuid_core/data/config.json の REGISTER_CODE フィールドにあります

優先的に確認すべき設定項目

• masters：あなたの QQ 番号 / プラットフォームアカウント。早めに入力することを推奨します。入力しないと一部の Core 管理コマンドが正常に使用できません
• WS_TOKEN：入力を推奨します。入力した場合、対応するアダプター内でもこの Token を同期設定する必要があります。GsCore と接続先の Bot が同じマシン上にある場合は通常不要ですが、同一マシンでも Docker をまたぐ場合は設定が必要です。
• HOST：デフォルトは localhost。外部からアクセスする場合は 0.0.0.0 に変更できます
• TRUSTED_IPS：WS_TOKEN を入力しない場合、デフォルトで信頼される IP（通常 127.0.0.1）のみが信頼されます

外部アクセス方法

• gsuid_core/data/config.json の HOST を 0.0.0.0 に直接変更する
• またはコンソールで「サービスリッスンアドレス」を変更して再起動する
• またはリバースプロキシで http://127.0.0.1:8765 を直接プロキシする

リバースプロキシに以下の設定を追加すると、example.com が example.com/app ではなくコンソールに自動リダイレクトされます：

Tip

また、Docker を使用してクイックデプロイすることもできます。

1-5 鳴潮プラグイン XutheringWavesUID のインストール

Tip

すべての設定が完了した後、ボットに直接 core安装插件XutheringWavesUID と送信し、core を再起動してインストールを適用することもできます。

ウェイトとダメージ計算の更新時は、ww下載全部資源 を送信するだけで自動リロードされます。

以下の追加依存関係のインストールを推奨します：

• playwright：お知らせ、wiki 画像などのレンダリング機能に使用します。インストール後、uv run playwright install chromium の実行も必要です
• opencv-python：パネル画像の重複判定、パネル画像の抽出、類似度認識などの機能に使用します
• fonttools：多言語フォント fallback に使用します。未インストール時は日韓文字が四角で表示される場合があります

CodeBlock Loading...

1-6 永続化

1-6-1 systemd

/etc/systemd/system/ ディレクトリに .service を拡張子とするファイルを作成し、以下の基本内容を記述します：

保存後、以下を実行します：

1-6-2 tmux

1-6-3 screen

2 NapCatQQ プロトコル端のインストール

2-1 ワンクリックスクリプトのダウンロードと実行

上記のリンクが利用できない場合は、GitHub のオリジナルアドレスも使用できます：

tui バージョン（SSH 環境により適しています）をインストールすることもできます：

2-2 起動

Shell 版 の場合、インストーラーがよく出力する起動方法は以下の通りです（インストールスクリプトの実際の出力に従ってください）：

Tip
-

libnapcat_launcher.so のあるディレクトリで上記コマンドを実行する必要があります

• tui バージョンをインストールした場合は、sudo napcat を直接実行してテキストインターフェースから設定と起動を行えます

2-3 WebUI による OneBot サービスの設定

WebUI にアクセスする最も確実な方法は、NapCat の起動ログを直接確認することです。デフォルトでは、ログに以下のようなリンクが表示されます：

Linux ワンクリックスクリプトインストール を使用した場合、webui.json は通常以下にあります：

設定例：

初回 WebUI アクセス時には通常パスワードの変更を求められます。ログイン成功後、ネットワーク設定 に進み、対応する OneBot サービスを新規作成して有効化すれば OK です。

詳細は：NapCat の WebUI 設定ガイドを参照してください。

2-4 永続化

上記と同様です。tui バージョンを使用している場合は、バックグラウンド実行が組み込まれています。

2-5 補足説明

NoneBot2 または AstrBot を選択して NapCat と GsCore を接続できます（下記参照）。また、NapCat のプラグインで GsCore に直接接続することも可能です：

3 NoneBot2 フレームワークのインストール

3-1 pipx のインストール

3-2スキャフォールディングscaffoldingのインストール

3-3 プロジェクトの生成

Tip

古いチュートリアルでよく見る nb bs / nb-cli-plugin-bootstrap は初期の書き方です。新版の nb-cli には bootstrap テンプレートが組み込まれているため、nb create を直接使用すれば OK です。

bootstrap テンプレートを選択して Enter を押します。

プロジェクト名を入力して Enter を押します。

アダプターの選択時：

• 個人 QQ の場合は OneBot V11 を選択
• 公式 QQ の場合は QQ（QQ 官方机器人） を選択

最後に Enter を押します。

ドライバーは HTTPX、FastAPI、websockets の選択を推奨します。この組み合わせで、本チュートリアルの一般的な接続シナリオをほぼカバーできます。

ローカルストレージ戦略はデフォルトのままで OK です。

プロンプトに従って依存関係と仮想環境をインストールします。

組み込みプラグイン echo はオプションで、テスト用です。

不要であれば、Enter を押してスキップします。

3-4 GsCore への接続

アダプターのインストール：

GsCore で WS_TOKEN を設定した場合は、.env に以下を追加する必要があります：

他のパラメータを明示的に指定する必要がある場合は、続けて追加できます（通常は入力しなくても正常に動作します）：

3-5 実行

3-6 NapCat への接続

3-6-1 個人 QQ

前提として、上記で言及した OneBot V11 アダプターがインストールされていること。

参考：フレームワークへの接続

NapCat のネットワーク設定で リバース WebSocket アドレスを追加します：

ここで：

• 8080 は NoneBot が出力するポート番号
• /onebot/v11/ws は NoneBot OneBot アダプターのデフォルトパス

NapCat 側で Token を設定した場合は、プロジェクトの .env に以下も追加する必要があります：

3-6-2 QQ 公式ボット

前提として、上記で言及した QQ（QQ 官方机器人） アダプターがインストールされていること。

参考：NoneBot-Adapter-QQ

.env ファイルを編集し、以下の内容をファイル末尾に追加して、id、token、secret を QQ 開放プラットフォームの開発設定で取得した実際の値に置き換えます：

Tip
-

現在 サンドボックス環境 でデバッグ中の場合は、QQ_IS_SANDBOX=false を true に変更してください

• Webhook を WebSocket の代わりに使用する場合は、対応する bot 設定に "use_websocket": false を追加し、QQ 開放プラットフォームでコールバックアドレスを設定します：https://host:port/qq/webhook

3-7 永続化

上記と同様です。

4 AstrBot フレームワークのインストール

NoneBot2 の代わりに AstrBot を使用することもでき