OneBot V11 / NapCat 設定ガイド
この記事では、OneBot V11 / NapCat を設定して Nekro Agent を QQ に接続する方法を説明します。
ヒント
NekroAgent Windows ランチャーでインストールした場合は、ランチャーの NapCat ページからワンクリックでネットワーク設定を完了できます。
事前準備
- Nekro Agent のデプロイが完了しており、WebUI を開ける
- Bot 用に使用する QQ アカウントがある
- Nekro Agent のアクセス先を把握している。例:
http://<server-ip>:8021
ステップ1: 先に Nekro Agent で OneBot V11 を有効にする
- Nekro Agent WebUI を開く
アダプター->OneBot V11を開く設定ページを開くアダプターを有効化をオンにするBot QQ 番号を入力するNapCat WebUI URLを入力する- アダプター設定を保存する
- Nekro Agent を再起動する
OneBot V11アダプターに戻り、NapCatページを開く- 画面に表示される
OneBot Service Access KeyとNapCat Login Tokenを控える
主な項目の入力方法
BOT_QQ: Bot に使用する QQ 番号RESOLVE_CQ_CODE: 通常はデフォルトのままで問題ありません。プロトコル側で CQ コードを解析する必要がある場合だけ有効にしてくださいNAPCAT_ACCESS_URL: NapCat WebUI のアドレス。一般的にはhttp://<server-ip>:6099/webuiNAPCAT_CONTAINER_NAME: 標準的なデプロイでは通常変更不要です
ステップ2: NapCat にログインする
- NapCat WebUI を開く。一般的なアドレスは
http://<server-ip>:6099/webui - 先ほど控えた
NapCat Login Tokenでログインする - 画面の案内に従って QQ にログインする
- NapCat がオンライン状態になっていることを確認する
- 初回アクセスの場合は、先に
システム設定->パスワード変更でデフォルトパスワードを変更する
ステップ3: NapCat でリバース WebSocket を設定する
- NapCat の
ネットワーク設定を開く WebSocket クライアントを追加する- アドレスに次を入力する:
text
ws://nekro_agent:8021/onebot/v11/ws一体化コンテナ構成ではない場合は、次のように変更できます:
text
ws://<your-server-ip>:8021/onebot/v11/ws- 認証キーには、先ほど Nekro Agent 側で表示された
OneBot Service Access Keyを入力する - 保存して、この接続を有効化する
ステップ4: 接続できたか確認する
設定が完了したら、次の順で確認してください:
- NapCat の
Cat Logsを開く - WebSocket 関連のエラーがないか確認する
- Bot にプライベートメッセージを送る
- Nekro Agent に戻り、
システムログに送信したメッセージが表示されるか確認する - 表示されていれば設定完了です
NapCat を使わない場合
ほかの OneBot V11 互換プロトコル実装を使う場合も、リバース WebSocket の接続先を次に向ければ利用できます:
text
ws://<your-server-ip>:8021/onebot/v11/ws画像やファイル送信も使う場合は、Nekro Agent とプロトコル実装が同じマウントパスを参照していることも確認してください。
設定後に表示されるチャット名
- グループチャット:
onebot_v11-group_<group-id> - プライベートチャット:
onebot_v11-private_<qq-number>
どちらも正常な表示なので、手動で変更する必要はありません。
よくある問題
NapCat はログイン済みなのに、Nekro Agent がメッセージを受け取らない
まず次を確認してください:
- リバース WebSocket の URL が正しいか
OneBot Service Access Keyが正しいか- NapCat 側で接続スイッチが本当に有効になっているか
- Nekro Agent 側の
OneBot V11アダプターが有効になっているか
メッセージは受信できるが送信できない
主な原因は次のとおりです:
- Bot アカウントがプラットフォーム側で制限されている
- Bot アカウントがミュートされている
- プロトコル実装と Nekro Agent の接続が切れている
画像やファイルの送信に失敗する
標準の一体化デプロイではない場合、まず次を確認してください:
- プロトコル実装が画像やファイル送信に対応しているか
- Nekro Agent とプロトコル実装の両方から同じファイルパスが参照できるか
- ファイルサイズがプラットフォームの制限を超えていないか