nonebot-plugin-qqdetail 教學（NoneBot2 + NapCat / OneBot v11）

這篇教學會帶你從 0 建好 NoneBot2 專案、安裝並啟用nonebot-plugin-qqdetail，並用 NapCat（OneBot v11）把 QQ 的事件用 WebSocket 轉給 NoneBot（同機、正向 WS）。

前置安裝（建議環境）

• Python：建議 Python 3.10 / 3.11
• Git
• VS Code

1) 建立 NoneBot 專案（最省事：用 nb-cli）

在你要放專案的資料夾打開 PowerShell（或 VS Code 內建 Terminal），依序輸入：

python -m venv .venv
.\.venv\Scripts\activate
python -m pip install -U pip
pip install nb-cli

接著用 nb-cli 建立專案（這一步會生成專案結構與基本設定）：

nb create

照提示選：

• Driver：通常選 FastAPI
• Adapter：用 QQ 常見轉發方式通常選 OneBot v11
• Project name：隨便取

建立完成後，進入專案資料夾（如果你新開視窗也記得重新啟動 venv）：

cd 你的專案資料夾
.\.venv\Scripts\activate

補充：先 nb create 再在專案內建立 .venv 也可以；重點是你知道 .venv 建在哪裡。

2) 安裝插件 nonebot-plugin-qqdetail

在專案根目錄（有 pyproject.toml 的那層）執行：

pip install nonebot-plugin-qqdetail

3) 啟用插件

打開專案內的 .env（沒有就自己建立），加上這一行：

NONEBOT_PLUGINS=["nonebot_plugin_qqdetail"]

提醒：這裡填的是 Python 模組名；本插件使用 nonebot_plugin_qqdetail。

4) 配好 NapCat（OneBot v11 / WebSocket：同機正向連線）

重要觀念：NoneBot 本身不直接登入 QQ。
你需要 NapCat（OneBot 實作）登入 QQ，並把事件透過 OneBot v11 協議轉發給 NoneBot。

你目前的 WS 位址是：

ws://127.0.0.1:8080/onebot/v11/ws

4-1. NapCat 端設定（WebSocket Server）

在 NapCat 的 OneBot v11 設定中，請確認（或新增）WebSocket 入口，至少要符合：

• 協議：OneBot v11
• 傳輸：WebSocket
• 監聽：127.0.0.1 / 8080
• 路徑（Path）：/onebot/v11/ws

安全提醒：127.0.0.1 只允許本機連線；不要把 WS 直接暴露到公網。
若 NapCat 支援 Access Token，建議設定一個。

4-2. NoneBot 端設定（WS Client 連 NapCat）

打開 NoneBot 專案根目錄的 .env（或 .env.prod），加入（或確認）下列內容：

DRIVER=~fastapi
HOST=127.0.0.1
PORT=8081

ONEBOT_WS_URLS=["ws://127.0.0.1:8080/onebot/v11/ws"]

重點：PORT=8081 是 NoneBot 自己用的埠，請不要跟 NapCat 的 8080 衝突。
ONEBOT_WS_URLS 才是 NoneBot 去連 NapCat 的地址。

如果 NapCat 設了 Access Token：

ONEBOT_ACCESS_TOKEN=你在NapCat設定的token

補充：若你專案的 OneBot v11 adapter 對環境變數命名有差異，請以實際文件為準，再對照調整。

4-3. 啟動順序

1. 先啟動 NapCat（確認 WS 已開始監聽）
2. 再啟動 NoneBot（下一節）

5) 啟動

在專案根目錄執行：

nb run

啟動後你應該能看到：

• NoneBot log 顯示已連上 OneBot v11 WebSocket（或類似訊息）
• NapCat 端顯示有 WebSocket Client 連入 / 連線已建立

常見問題排查

Q1：一直連不上 / 一直重連

• 確認 NapCat 的 WS 位址是否真的是 ws://127.0.0.1:8080/onebot/v11/ws
• 確認你填的是 ws://（不是 http://）
• 確認 NoneBot 的 PORT 沒有設成 8080（避免埠衝突）
• 若 NapCat 設了 token：確認 ONEBOT_ACCESS_TOKEN 完全一致（含大小寫）

Q2：NapCat 正常，但 NoneBot 沒收到事件

• 確認插件已啟用，且 OneBot v11 adapter 正常載入
• 確認你是在專案根目錄執行 nb run，且 .env 有被讀到
• 確認 NapCat 顯示 WS 連線已建立

然後配置 NapCatQQ

https://github.com/NapNeko/NapCatQQ/releases/download/v4.17.55/NapCat.Shell.Windows.OneKey.zip