一 Key 配置與 NapCat WebSocket 驗證)
1. 為什么要在 QQ 里跑一個 AI 助手OpenClaw 是一個支持多渠道消息接入的 AI Agent 框架NapCat 是基于 NTQQ 的 QQ 機器人框架兩者通過 WebSocket 對接后你的 QQ 私聊就能直接和 AI 對話。這套組合適合想搭建私人 AI 助手的開發(fā)者不用公網(wǎng)服務(wù)器、不用備案域名本地跑起來就能用。而模型調(diào)用這一層我用 TaoToken 的統(tǒng)一 Key 來收口——一個 Key 同時驅(qū)動對話模型和編碼模型省得在 OpenClaw 的 config.toml 里塞好幾家廠商的密鑰。整條鏈路是這樣的QQ 消息 → NapCatWebSocket 服務(wù)端→ OpenClaw 的 QQ 通道插件 → OpenClaw Gateway → AI Agent → 原路返回。本文按這條鏈路從 TaoToken 拿 Key 開始到 NapCat 反向 WS 配置、OpenClaw 的 config.toml 骨架最后用一條真實消息做端到端驗證。全程命令可直接復(fù)制踩坑點我會單獨標出來。2. TaoToken 前置統(tǒng)一 Key 與模型入口TaoToken 在這里的角色是模型網(wǎng)關(guān)。OpenClaw 的 Agent 需要調(diào)用大模型與其在配置里分別填 Anthropic、OpenAI 的地址和密鑰不如統(tǒng)一走 TaoToken 的 API 端點一個 Key 管所有模型。對 QQ 助手這種場景很實用白天用對話模型陪聊晚上切編碼模型幫你寫腳本改的只是 config.toml 里一行 model 字段。先拿 Key。打開控制臺登錄后在 API Keys 頁面創(chuàng)建一個新 Key復(fù)制出來只顯示一次丟了就重建。地址是 https://taotoken.net/api 注意這個端點不帶任何查詢參數(shù)直接作為 base_url 用。模型選擇上日常對話用 claude-sonnet 系列響應(yīng)快、語氣自然需要長上下文或復(fù)雜推理時換更強的型號。如果你打算讓這個 QQ 助手長期掛著跑編碼任務(wù)可以了解下 Coding Plan額度模型更適合高頻調(diào)用。想先試試模型效果模型對話頁面可以直接在線驗證不用寫代碼。注意Key 屬于敏感憑證別寫進會提交到 Git 的配置文件里。下面 config.toml 里我用環(huán)境變量占位實際部署時用export注入。3. 可復(fù)制配置NapCat 反向 WS OpenClaw config.toml3.1 安裝 QQ 通道插件OpenClaw 側(cè)先裝插件一條命令openclaw plugins install izhimu/qq裝完確認版本OpenClaw 本體要求 2026.2.1 以上openclaw --version3.2 NapCat 開啟 WebSocket 服務(wù)NapCat 的配置文件位置按系統(tǒng)區(qū)分# Linux ~/.config/NapCat/config/config.yml # Windows %APPDATA%\NapCat\config\config.yml編輯 config.yml啟用 WS 服務(wù)并設(shè)置 token。這里配的是 NapCat 作為服務(wù)端監(jiān)聽OpenClaw 作為客戶端連過來ws: servers: - url: ws://0.0.0.0:3001 token: your-napcat-token enableHeart: true0.0.0.0表示監(jiān)聽所有網(wǎng)卡本機自用改成127.0.0.1更安全。token 自己設(shè)一個隨機串后面 OpenClaw 要填一樣的值。改完重啟 NapCat 生效。3.3 OpenClaw 的 config.toml 骨架OpenClaw 支持交互式配置但手動寫 config.toml 更可控。完整骨架如下重點看 channels.qq 和 agents 兩段[channels.qq] wsUrl ws://127.0.0.1:3001 accessToken your-napcat-token enabled true [agents.assistant] provider taotoken baseUrl https://taotoken.net/api apiKey ${TAOTOKEN_API_KEY} model claude-sonnet-4-5-20250929 systemPrompt 你是一個友好專業(yè)的 AI 助手回答簡潔準確語氣自然。 [routing] qq:private:* assistant幾個關(guān)鍵點wsUrl必須和 NapCat 里配的地址端口一致accessToken填 NapCat 那個 token兩邊不匹配會直接握手失敗apiKey用${TAOTOKEN_API_KEY}引用環(huán)境變量啟動前先export TAOTOKEN_API_KEY你的Keyrouting里qq:private:*把所有私聊消息路由到 assistant 這個 Agent。如果你更習(xí)慣向?qū)脚渲门躱penclaw onboard按提示填也行生成的字段和上面一一對應(yīng)。3.4 啟動 Gatewayopenclaw gateway restart重啟后 Gateway 會讀取 config.toml主動去連 NapCat 的 WS 端口。4. 驗證請求一條消息從 QQ 到 AI 回復(fù)配置寫完別急著慶祝先做端到端驗證。分三步。第一步確認 NapCat 的 WS 服務(wù)活著curl http://localhost:3001/get_status返回 JSON 里 status 為 ok 就說明服務(wù)端正常。第二步看 OpenClaw 的 QQ 通道有沒有連上openclaw channels輸出里 qq 通道狀態(tài)應(yīng)該是 connected。如果是 disconnected直接看日志openclaw logs --channel qq --verbose第三步真實發(fā)消息。用另一個 QQ 號給你的機器人發(fā)一條私聊比如「你好幫我算下 23 乘 47」。正常的話幾秒內(nèi)會收到 AI 回復(fù)。如果沒反應(yīng)用命令行主動發(fā)一條測試openclaw message send 測試消息 --to qq:private:123456789目標格式是qq:private:QQ號冒號別寫錯。帶圖片的消息加--media參數(shù)openclaw message send 看這張圖 --to qq:private:123456789 --media https://example.com/image.jpg實測下來從 QQ 發(fā)出到收到回復(fù)本地鏈路延遲通常在 2 到 5 秒取決于模型響應(yīng)速度。如果超過 30 秒沒動靜基本可以判定是連接或鑒權(quán)問題往下看排查。5. 本篇常見錯排查連接類問題占九成。最常見的是 wsUrl 和 NapCat 配置對不上——NapCat 監(jiān)聽 3001OpenClaw 卻連 3000握手直接失敗。其次是 token 不匹配NapCat 設(shè)了 token 但 OpenClaw 的 accessToken 留空或者反過來。這兩個字段必須完全一致?，F(xiàn)象可能原因處理方式通道一直 disconnectedwsUrl 端口寫錯核對 NapCat config.yml 與 config.toml握手失敗 401accessToken 不一致兩邊 token 改成同一個值消息發(fā)出無回復(fù)routing 未命中檢查qq:private:*拼寫模型報鑒權(quán)錯誤TaoToken Key 無效重新生成 Key 并 export圖片發(fā)送失敗URL 不可公網(wǎng)訪問換可訪問的圖片地址模型側(cè)報錯單獨說下。如果日志里出現(xiàn) 401 或 invalid api key是 TaoToken 的 Key 沒生效確認環(huán)境變量在當前 shell 里echo $TAOTOKEN_API_KEY有值。如果報 model not found檢查 model 字段拼寫別把日期后綴寫錯。想快速確認 Key 和模型是否可用去模型對話頁面發(fā)一條消息能正?；鼐驼f明 Key 沒問題問題在 OpenClaw 配置側(cè)。還有一個隱蔽的坑NapCat 重啟后 token 如果重新生成OpenClaw 側(cè)不會自動更新需要手動改 config.toml 再openclaw gateway restart。建議 token 設(shè)成固定值別用隨機生成。6. 把 Key 和接入文檔收進工具箱鏈路跑通后日常維護主要盯兩件事NapCat 的 WS 連接狀態(tài)和 TaoToken 的額度消耗。前者用openclaw channels一眼看后者在控制臺看用量。如果你要把這個 QQ 助手長期掛著建議把 Key 管理、模型切換、額度監(jiān)控都收口到 TaoToken 一處省得散落在多個配置文件里。接入過程中遇到鑒權(quán)或通道配置問題直接翻接入文檔對照字段需要新建或輪換 Key去 API Keys 頁面操作想先驗證模型輸出質(zhì)量再決定用哪個型號模型對話頁面最省事。長期跑編碼類 Agent 的話Coding Plan 的額度模型比按次調(diào)用更劃算。整套配置的核心就一句話NapCat 管 QQ 連接OpenClaw 管消息路由TaoToken 管模型調(diào)用三層各司其職出問題按層排查就不會亂。 OpenClaw 接入 QQ 完全指南：TaoToken 統(tǒng)一 Key 配置與 NapCat WebSocket 驗證
1. 為什么要在 QQ 里跑一個 AI 助手OpenClaw 是一個支持多渠道消息接入的 AI Agent 框架NapCat 是基于 NTQQ 的 QQ 機器人框架兩者通過 WebSocket 對接后你的 QQ 私聊就能直接和 AI 對話。這套組合適合想搭建私人 AI 助手的開發(fā)者不用公網(wǎng)服務(wù)器、不用備案域名本地跑起來就能用。而模型調(diào)用這一層我用 TaoToken 的統(tǒng)一 Key 來收口——一個 Key 同時驅(qū)動對話模型和編碼模型省得在 OpenClaw 的 config.toml 里塞好幾家廠商的密鑰。整條鏈路是這樣的QQ 消息 → NapCatWebSocket 服務(wù)端→ OpenClaw 的 QQ 通道插件 → OpenClaw Gateway → AI Agent → 原路返回。本文按這條鏈路從 TaoToken 拿 Key 開始到 NapCat 反向 WS 配置、OpenClaw 的 config.toml 骨架最后用一條真實消息做端到端驗證。全程命令可直接復(fù)制踩坑點我會單獨標出來。2. TaoToken 前置統(tǒng)一 Key 與模型入口TaoToken 在這里的角色是模型網(wǎng)關(guān)。OpenClaw 的 Agent 需要調(diào)用大模型與其在配置里分別填 Anthropic、OpenAI 的地址和密鑰不如統(tǒng)一走 TaoToken 的 API 端點一個 Key 管所有模型。對 QQ 助手這種場景很實用白天用對話模型陪聊晚上切編碼模型幫你寫腳本改的只是 config.toml 里一行 model 字段。先拿 Key。打開控制臺登錄后在 API Keys 頁面創(chuàng)建一個新 Key復(fù)制出來只顯示一次丟了就重建。地址是 https://taotoken.net/api 注意這個端點不帶任何查詢參數(shù)直接作為 base_url 用。模型選擇上日常對話用 claude-sonnet 系列響應(yīng)快、語氣自然需要長上下文或復(fù)雜推理時換更強的型號。如果你打算讓這個 QQ 助手長期掛著跑編碼任務(wù)可以了解下 Coding Plan額度模型更適合高頻調(diào)用。想先試試模型效果模型對話頁面可以直接在線驗證不用寫代碼。注意Key 屬于敏感憑證別寫進會提交到 Git 的配置文件里。下面 config.toml 里我用環(huán)境變量占位實際部署時用export注入。3. 可復(fù)制配置NapCat 反向 WS OpenClaw config.toml3.1 安裝 QQ 通道插件OpenClaw 側(cè)先裝插件一條命令openclaw plugins install izhimu/qq裝完確認版本OpenClaw 本體要求 2026.2.1 以上openclaw --version3.2 NapCat 開啟 WebSocket 服務(wù)NapCat 的配置文件位置按系統(tǒng)區(qū)分# Linux ~/.config/NapCat/config/config.yml # Windows %APPDATA%\NapCat\config\config.yml編輯 config.yml啟用 WS 服務(wù)并設(shè)置 token。這里配的是 NapCat 作為服務(wù)端監(jiān)聽OpenClaw 作為客戶端連過來ws: servers: - url: ws://0.0.0.0:3001 token: your-napcat-token enableHeart: true0.0.0.0表示監(jiān)聽所有網(wǎng)卡本機自用改成127.0.0.1更安全。token 自己設(shè)一個隨機串后面 OpenClaw 要填一樣的值。改完重啟 NapCat 生效。3.3 OpenClaw 的 config.toml 骨架OpenClaw 支持交互式配置但手動寫 config.toml 更可控。完整骨架如下重點看 channels.qq 和 agents 兩段[channels.qq] wsUrl ws://127.0.0.1:3001 accessToken your-napcat-token enabled true [agents.assistant] provider taotoken baseUrl https://taotoken.net/api apiKey ${TAOTOKEN_API_KEY} model claude-sonnet-4-5-20250929 systemPrompt 你是一個友好專業(yè)的 AI 助手回答簡潔準確語氣自然。 [routing] qq:private:* assistant幾個關(guān)鍵點wsUrl必須和 NapCat 里配的地址端口一致accessToken填 NapCat 那個 token兩邊不匹配會直接握手失敗apiKey用${TAOTOKEN_API_KEY}引用環(huán)境變量啟動前先export TAOTOKEN_API_KEY你的Keyrouting里qq:private:*把所有私聊消息路由到 assistant 這個 Agent。如果你更習(xí)慣向?qū)脚渲门躱penclaw onboard按提示填也行生成的字段和上面一一對應(yīng)。3.4 啟動 Gatewayopenclaw gateway restart重啟后 Gateway 會讀取 config.toml主動去連 NapCat 的 WS 端口。4. 驗證請求一條消息從 QQ 到 AI 回復(fù)配置寫完別急著慶祝先做端到端驗證。分三步。第一步確認 NapCat 的 WS 服務(wù)活著curl http://localhost:3001/get_status返回 JSON 里 status 為 ok 就說明服務(wù)端正常。第二步看 OpenClaw 的 QQ 通道有沒有連上openclaw channels輸出里 qq 通道狀態(tài)應(yīng)該是 connected。如果是 disconnected直接看日志openclaw logs --channel qq --verbose第三步真實發(fā)消息。用另一個 QQ 號給你的機器人發(fā)一條私聊比如「你好幫我算下 23 乘 47」。正常的話幾秒內(nèi)會收到 AI 回復(fù)。如果沒反應(yīng)用命令行主動發(fā)一條測試openclaw message send 測試消息 --to qq:private:123456789目標格式是qq:private:QQ號冒號別寫錯。帶圖片的消息加--media參數(shù)openclaw message send 看這張圖 --to qq:private:123456789 --media https://example.com/image.jpg實測下來從 QQ 發(fā)出到收到回復(fù)本地鏈路延遲通常在 2 到 5 秒取決于模型響應(yīng)速度。如果超過 30 秒沒動靜基本可以判定是連接或鑒權(quán)問題往下看排查。5. 本篇常見錯排查連接類問題占九成。最常見的是 wsUrl 和 NapCat 配置對不上——NapCat 監(jiān)聽 3001OpenClaw 卻連 3000握手直接失敗。其次是 token 不匹配NapCat 設(shè)了 token 但 OpenClaw 的 accessToken 留空或者反過來。這兩個字段必須完全一致?，F(xiàn)象可能原因處理方式通道一直 disconnectedwsUrl 端口寫錯核對 NapCat config.yml 與 config.toml握手失敗 401accessToken 不一致兩邊 token 改成同一個值消息發(fā)出無回復(fù)routing 未命中檢查qq:private:*拼寫模型報鑒權(quán)錯誤TaoToken Key 無效重新生成 Key 并 export圖片發(fā)送失敗URL 不可公網(wǎng)訪問換可訪問的圖片地址模型側(cè)報錯單獨說下。如果日志里出現(xiàn) 401 或 invalid api key是 TaoToken 的 Key 沒生效確認環(huán)境變量在當前 shell 里echo $TAOTOKEN_API_KEY有值。如果報 model not found檢查 model 字段拼寫別把日期后綴寫錯。想快速確認 Key 和模型是否可用去模型對話頁面發(fā)一條消息能正?；鼐驼f明 Key 沒問題問題在 OpenClaw 配置側(cè)。還有一個隱蔽的坑NapCat 重啟后 token 如果重新生成OpenClaw 側(cè)不會自動更新需要手動改 config.toml 再openclaw gateway restart。建議 token 設(shè)成固定值別用隨機生成。6. 把 Key 和接入文檔收進工具箱鏈路跑通后日常維護主要盯兩件事NapCat 的 WS 連接狀態(tài)和 TaoToken 的額度消耗。前者用openclaw channels一眼看后者在控制臺看用量。如果你要把這個 QQ 助手長期掛著建議把 Key 管理、模型切換、額度監(jiān)控都收口到 TaoToken 一處省得散落在多個配置文件里。接入過程中遇到鑒權(quán)或通道配置問題直接翻接入文檔對照字段需要新建或輪換 Key去 API Keys 頁面操作想先驗證模型輸出質(zhì)量再決定用哪個型號模型對話頁面最省事。長期跑編碼類 Agent 的話Coding Plan 的額度模型比按次調(diào)用更劃算。整套配置的核心就一句話NapCat 管 QQ 連接OpenClaw 管消息路由TaoToken 管模型調(diào)用三層各司其職出問題按層排查就不會亂。