1. 为什么我要把 QQ 个人号接上大模型
先说清楚这套东西到底是什么。OpenClaw QQ Manager v2.0 是一个把 NapCat（QQ 协议层）、OpenClaw（AI 引擎）和 Web 管理后台打包进单个 Docker 容器的开源项目，能让你用一条docker-compose up -d就把 QQ 个人号变成会说话的 AI 助手。它适合谁？适合手里有台闲置 Linux 小主机、想折腾私聊自动回复和群聊 @ 回复、又不想一个个手动装 NapCat 和 OpenClaw 的人。
我之前的做法是 NapCat 单独跑一个容器，OpenClaw 跑在宿主机 systemd 里，两边靠端口映射通信。问题出在 NapCat 的 OneBot WebSocket 只监听容器内的127.0.0.1:3001，Docker 的-p映射根本转发不了这个回环地址，每次重启都要手动改配置，二维码还得跳外部链接看。v2.0 把管理后台塞进同一个容器，内置了一个/onebot的 WS 代理路径，宿主机上的 OpenClaw 连ws://127.0.0.1:6199/onebot就能穿透到容器内的 NapCat，这个设计直接解决了我最头疼的网络连通问题。
另一个痛点是登录持久化。v1.0 重启容器就得重新扫码，因为 QQ 的 session 没挂出来。v2.0 把/app/.config/QQ挂到 Docker Volume，重启不掉线。再加上登录方式从「必须访问 NapCat WebUI」变成管理后台内集成扫码/快速/账密三种，整个体验顺了一大截。
这篇要解决的核心场景是：你有一台 Ubuntu 服务器，装好了 Docker 和 OpenClaw，现在想把模型调用统一改到 TaoToken 的 API 通道，然后让 QQ 消息触发 AI 回复。我会给出可复制的 docker-compose 配置、环境变量清单、NapCat 登录验证步骤，最后演示一条 QQ 消息端到端跑通的全过程。全程不需要你懂 QQ 协议，照着敲命令就行。
需要提前说明的是，这类第三方客户端登录 QQ 存在账号风险，强烈建议用小号测试，别拿主力号折腾。项目本身是 CC BY-NC-SA 4.0 许可，禁止商用，自己学习研究没问题。
2. 部署前把 TaoToken 通道准备好
在动 Docker 之前，先把模型调用这条链路理清楚。OpenClaw 本身是个 Agent 框架，它需要一个能调用的模型后端。默认它可能指向某些官方端点，但如果你想让所有 QQ 消息的 AI 回复都走统一通道，把 Base URL 改到 TaoToken 是最省事的做法——一个 Key 就能切换不同模型，不用为每个模型单独配环境。
TaoToken 在这里扮演的角色是模型 API 网关。你注册后在控制台创建一个 API Key，拿到形如sk-xxxx的密钥，然后把 OpenClaw 的模型配置指向https://taotoken.net/api。这样 QQ 消息进来后，OpenClaw 调用模型时走的就是 TaoToken 通道，模型选择、额度管理都在一个地方看。
具体操作分三步。第一步，打开 https://taotoken.net/api-keys 创建密钥，复制保存好，这个 Key 只显示一次。第二步，确认你要用的模型 ID，比如claude-sonnet-4-5或者gpt-4o这类，TaoToken 的模型列表在文档里能查到。第三步，把这两样东西填进 OpenClaw 的配置。
如果你还没装 OpenClaw，先跑这两条：
curl -fsSL https://get.openclaw.ai | bash openclaw onboard openclaw gateway startonboard过程会问你模型提供商，这里可以先随便选，后面我们直接改配置文件覆盖。装完后 OpenClaw 的配置在~/.openclaw/openclaw.json，这是接下来要反复编辑的文件。
关于模型 ID 的写法，OpenClaw 的配置里agents.defaults.model.primary字段接受provider/model格式。走 TaoToken 时，provider 部分填你自定义的名称，model 填实际模型 ID。我实测下来，把 provider 的 baseUrl 指向https://taotoken.net/api，再配上sk-开头的 Key，就能正常出结果。
这里有个细节要注意：TaoToken 的 API 地址不带 UTM 参数，就是干净的https://taotoken.net/api，别把推广链接那串 query 拼进去，否则可能 404。Key 的权限建议只开模型调用，别开管理权限，降低泄露风险。
准备好 Key 和模型 ID 后，先别急着配 QQ，单独验证一下模型通道通不通。可以用 curl 直接打一发：
curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "说一句你好"}] }'返回里有choices[0].message.content就说明通道没问题。这一步过了，后面 QQ 消息没回复时就能排除掉模型层的问题，直接查 QQ 连接。
3. 可复制的 docker-compose 与环境变量配置
现在进入部署正题。先把项目拉下来：
git clone https://github.com/zhaoxinyi02/openclaw-qq-plugin.git cd openclaw-qq-plugin cp .env.example .env然后编辑.env，这是环境变量清单，必须改的有三项：
# 管理后台登录密码，务必改掉默认值 ADMIN_TOKEN=换成你自己的强密码 # NapCat WebUI Token，建议和 ADMIN_TOKEN 保持一致 WEBUI_TOKEN=换成你自己的强密码 # 你的 QQ 号，用于接收通知推送 OWNER_QQ=123456789ADMIN_TOKEN是你登录http://服务器IP:6199管理后台的密码，WEBUI_TOKEN是管理后台代理 NapCat 接口时用的认证 token，两者一致能省去记忆负担。OWNER_QQ填你自己的 QQ 号，系统有成员变动、被禁言这类事件时会推给你。
接下来看docker-compose.yml，核心是 Volume 挂载和端口映射。项目自带的 compose 文件已经配好了，我把它关键部分贴出来对照：
services: openclaw-qq: build: . container_name: openclaw-qq restart: unless-stopped ports: - "6199:6199" # 管理后台 + OneBot WS 代理 volumes: - qq-session:/app/.config/QQ # QQ 登录 session，重启不掉线 - napcat-data:/app/napcat/config # NapCat 配置 - manager-data:/app/manager/data # 管理后台配置 - ~/.openclaw:/root/.openclaw # 挂载宿主机 OpenClaw 配置 environment: - ADMIN_TOKEN=${ADMIN_TOKEN} - WEBUI_TOKEN=${WEBUI_TOKEN} - OWNER_QQ=${OWNER_QQ} volumes: qq-session: napcat-data: manager-data:这里有个关键点：~/.openclaw:/root/.openclaw这行把宿主机的 OpenClaw 配置目录挂进了容器。容器启动时会自动往openclaw.json里注册 QQ 频道插件，把extensions/qq/装好。如果你不想让容器改你的 OpenClaw 配置，可以去掉这行，但那样就得手动装插件，不推荐。
启动命令就一条：
docker-compose up -d首次启动要构建镜像，大概 2 到 5 分钟。容器起来后会自动完成解压 NapCat、配置 OneBot11 WebSocket、安装 QQ Channel 插件、注册频道、启动管理后台这一串动作。你可以用docker logs -f openclaw-qq看进度，看到管理后台监听 6199 就说明好了。
关于模型通道的配置，容器启动后编辑宿主机的~/.openclaw/openclaw.json，把模型指向 TaoToken。用下面这段 Python 脚本改，路径和字段名跟实际文件一致：
import json, os config_path = os.path.expanduser('~/.openclaw/openclaw.json') with open(config_path, 'r') as f: c = json.load(f) # 配置模型走 TaoToken 通道 c.setdefault('agents', {}).setdefault('defaults', {}).setdefault('model', {}) c['agents']['defaults']['model']['primary'] = 'taotoken/claude-sonnet-4-5' c.setdefault('providers', {})['taotoken'] = { 'baseUrl': 'https://taotoken.net/api', 'apiKey': 'sk-你的Key' } # 配置 QQ 频道连接管理后台的 WS 代理 c.setdefault('channels', {}).setdefault('qq', {}) c['channels']['qq']['enabled'] = True c['channels']['qq']['wsUrl'] = 'ws://127.0.0.1:6199/onebot' c['channels']['qq']['accessToken'] = '' with open(config_path, 'w') as f: json.dump(c, f, indent=4, ensure_ascii=False) print('配置已更新')跑完这个脚本，openclaw.json里就有了三件套：Base URL 是https://taotoken.net/api，Key 是sk-开头那串，Model ID 是claude-sonnet-4-5。然后重启 OpenClaw：
systemctl restart openclaw到这里，模型通道和 QQ 通道的配置都齐了。下一步是登录 QQ 并验证整条链路。
4. 扫码登录与端到端消息验证
配置写完后，打开浏览器访问http://你的服务器IP:6199，输入.env里设的ADMIN_TOKEN登录管理后台。左侧菜单点「QQ 登录」，v2.0 把三种登录方式都集成进来了：扫码、快速、账密。推荐扫码，最稳。
点扫码后，页面会用本地 QRCode 库把 NapCat 返回的 URL 渲染成二维码，不用跳外部链接。手机 QQ 扫一下，确认登录。成功后左上角会显示 QQ 昵称和号码，仪表盘上 NapCat 连接状态变成已连接。
登录这一步有个坑：如果你的服务器没有图形界面，NapCat 是靠容器内的 Xvfb 虚拟显示器跑 QQ 桌面客户端的，这是项目已经处理好的，你不用管。但如果容器内存给得太小（低于 2GB），QQ 客户端可能起不来，扫码会一直转圈。建议给容器至少 2GB 内存。
登录成功后，验证 OpenClaw 有没有连上 NapCat。在宿主机跑：
journalctl -u openclaw -f正常的话能看到[QQ] Connected to OneBot server这行日志。如果没看到，八成是openclaw.json里channels.qq.wsUrl写错了，确认是ws://127.0.0.1:6199/onebot，注意是127.0.0.1不是localhost，有些环境 localhost 解析会出问题。
现在做端到端验证。用另一个 QQ 号（或者让朋友帮忙）给机器人发一条私聊消息，内容随便，比如「你好」。预期结果是几秒内收到 AI 回复。这条消息的完整链路是：QQ 消息 → NapCat 收到 → 通过 OneBot WS 推给管理后台的/onebot代理 → 转发到宿主机 OpenClaw → OpenClaw 调用 TaoToken 的https://taotoken.net/api→ 模型返回 → 原路回传到 QQ。
如果收到回复，说明整条链路通了。你可以再试试群聊里 @ 机器人，看群消息能不能触发。群聊需要在管理后台的「QQ Bot 管理」里确认机器人已经加入了目标群，没加的话先拉进去。
验证模型确实走的是 TaoToken，可以看 OpenClaw 的日志里有没有对taotoken.net的请求记录，或者在 TaoToken 控制台的用量页面看有没有新的调用计数。两个地方对得上，就说明模型通道配置生效了。
到这一步，一条 QQ 消息触发 AI 回复的端到端动作就完成了。整个过程从docker-compose up -d到收到第一条回复，熟练的话五分钟内能搞定。
5. 常见报错排查：401、local proxy failed 与 OAuth
部署过程中最容易卡住的几个报错，我按实际遇到的频率排一下。
401 Unauthorized。这个分两种。一种是访问管理后台时 401，说明ADMIN_TOKEN输错了，或者.env改了但没重启容器。改完.env必须docker-compose down && docker-compose up -d才生效。另一种是模型调用返回 401，那是 TaoToken 的 Key 有问题——要么 Key 复制时带了空格，要么 Key 被禁用或额度耗尽。去 https://taotoken.net/api-keys 重新生成一个，注意sk-前缀要完整。
local proxy failed。这个报错通常出现在 OpenClaw 连 NapCat 的时候，日志里会写local proxy failed或者dial tcp 127.0.0.1:6199 connection refused。原因是管理后台没起来，或者 6199 端口没映射出来。先docker ps看容器在不在运行，再docker logs openclaw-qq看管理后台有没有报错。如果容器起来了但端口不通，检查docker-compose.yml里ports那行有没有被注释掉。还有一种情况是宿主机防火墙挡了 6199，ufw allow 6199放行一下。
reading choices 相关报错。这个一般出现在模型返回解析阶段，日志里可能是error reading choices或者unexpected response format。根因通常是 Base URL 配错了。TaoToken 的地址是https://taotoken.net/api，如果你手滑写成https://taotoken.net/api/v1，有些模型端点会重复拼/v1导致 404，返回体不是标准格式，解析就炸了。确认providers.taotoken.baseUrl就是https://taotoken.net/api，不带多余的路径。
OAuth 相关报错。如果你在 OpenClaw 里配了某些需要 OAuth 的 provider，日志可能出现oauth token expired或refresh failed。走 TaoToken 通道的话不涉及 OAuth，直接用 API Key 就行。如果报这个错，说明agents.defaults.model.primary还指向了旧的 OAuth provider，把它改成taotoken/模型ID就好。
QQ 登录后发消息没回复。先看journalctl -u openclaw -f有没有[QQ] Connected to OneBot server。没有的话是 WS 没连上，检查wsUrl。有这行但没回复，看 OpenClaw 有没有收到消息事件，再往下查模型调用。可以用docker logs -f openclaw-qq同时看容器侧日志，两边对照能快速定位是 QQ 层还是模型层的问题。
重启容器后要重新扫码。正常不该发生，因为 session 挂在qq-sessionvolume 里。如果真遇到了，检查docker-compose.yml里qq-session:/app/.config/QQ这行在不在。volume 被误删或者路径写错都会导致 session 丢失。
排查时记住一个原则：先确认容器活着，再确认端口通，再确认 WS 连上，最后确认模型能调。按这个顺序查，基本不会绕弯路。
6. 后续怎么用与通道选择建议
跑通之后，日常使用就是管理后台那套。仪表盘看连接状态和实时事件流，QQ Bot 管理里能主动发私聊和群消息，审核中心处理好友和入群请求，设置页开防撤回、戳一戳回复、入群欢迎、自动审核这些。防撤回和戳一戳是个人号才有的玩法，群管理场景挺实用。
模型切换在「OpenClaw 配置」页直接编辑agents.defaults.model.primary，比如从taotoken/claude-sonnet-4-5换成taotoken/gpt-4o，保存后重启 OpenClaw 生效。因为走的是 TaoToken 统一通道，换模型不用改 Key 和 Base URL，只改模型 ID 那一截。
如果你打算长期跑，建议把 OpenClaw 的模型调用都收敛到 TaoToken 通道，好处是额度、模型、日志在一个控制台看，不用为每个 provider 单独维护密钥。创建和管理 Key 在 https://taotoken.net/api-keys，接入细节和参数说明在 https://taotoken.net/doc 能查到。想先试试模型对话效果，可以直接在 https://taotoken.net/models 里体验，确认模型 ID 和返回格式再往配置里填。
对于要跑 coding 或 Agent 类长任务的场景，TaoToken 的 Coding Plan 在 https://taotoken.net/coding-plan 有专门的套餐，比按量调用更适合高频使用。控制台在 https://taotoken.net/console，日常看用量和调额度都在那。
最后提醒一句，QQ 个人号接第三方客户端有封号风险，用小号玩，别拿主力号试。项目本身禁止商用，自己学习研究就好。跑通之后你会发现，真正花时间的不是部署，而是调 prompt 和审核规则，那部分就看你自己的需求慢慢磨了。
