1. 为什么我要把 QQ 接上 DeepSeek：从消息堆积到自动回复的真实场景

每天打开 QQ，群消息、私聊、文件、@提醒混在一起，很多重复问题被反复问，手动回复既费时间又容易漏。我想要的不是再开一个网页去问 AI，而是让 AI 直接待在 QQ 里：群友问“这段报错什么意思”，机器人能答；问“帮我写个正则”，机器人能给；甚至点歌、查车次也能顺手完成。QQ 接入 DeepSeek 这件事，本质是把「聊天入口」和「大模型能力」缝在一起，让消息流里直接长出智能回复。

但真正动手会发现，这不是装一个软件就完事。QQ 本身不开放机器人 API，需要一层协议适配；大模型也不会自己读 QQ 消息，需要一个调度中枢。于是链路被拆成三段：NapCat 负责登录 QQ 并把消息转成 OneBot 标准接口，AstrBot 负责收消息、调模型、跑插件，DeepSeek 负责生成内容。三者用 Docker 跑在同一台机器上，通过 HTTP/WebSocket 通信，任何一段断了，机器人就哑了。

这篇教程面向想自建群聊助手的开发者，重点放在 Docker 环境下的可复制配置：docker-compose 怎么写、NapCat 怎么扫码登录、AstrBot 适配器参数怎么填、DeepSeek 的 Key 和 Base URL 怎么接、发消息怎么验证链路。如果你后面还想统一管理多个模型的 Key 和通道，可以了解 TaoToken（https://taotoken.net/?utm_source=taotoken_aicg_blog_end），它提供兼容 OpenAI 风格的 API 入口，方便把 DeepSeek 等模型统一接入。下面从零开始，每一步都给命令和参数。

2. TaoToken 前置准备：统一 Key 与 API 通道，避免多模型切换踩坑

在正式部署前，先把「模型通道」这件事想清楚。AstrBot 支持 DeepSeek、OpenAI、Claude、GLM 等多家模型，如果你只接一个 DeepSeek，直接去官网拿 Key 就行；但如果你后面想换模型、做对比、或者同时给多个机器人用不同模型，每个平台单独注册、单独充值、单独记 Key，很快就会乱。这时候一个统一的 API 通道会省很多事。

TaoToken 的定位就是统一 Key 和 API 通道：它提供兼容 OpenAI 风格的接口，你拿到一个 Base URL 和一个 API Key，就能在 AstrBot 里按 OpenAI 兼容方式接入，模型 ID 填对应名称即可。对 AstrBot 来说，它不关心你背后是 DeepSeek 还是别的模型，只要接口格式对、Key 有效、模型 ID 存在，就能正常对话。这样你换模型时只改一个 Model ID，不用改代码、不用换适配器。

具体要准备三样东西，我把它叫「三件套」：Base URL、API Key、Model ID。以 TaoToken 为例，Base URL 用 https://taotoken.net/api，API Key 在控制台创建，Model ID 填你要用的模型名（比如 deepseek-chat）。如果你直接用 DeepSeek 官方，Base URL 是 https://api.deepseek.com，Key 在 DeepSeek 平台创建，Model ID 同样是 deepseek-chat。两种方式在 AstrBot 里的配置位置一样，区别只是填的地址和 Key 不同。

这里要提醒一句：不管用哪种通道，Key 都不要写进公开的 docker-compose 文件或截图里。AstrBot 后台会保存 Key，NapCat 的 Token 也会出现在容器日志里，这些都属于敏感信息。建议用一个专门的测试 QQ 号跑机器人，不要一上来就把主号交出去。准备好 Key 之后，我们进入 Docker 部署环节。

3. 可复制配置：docker-compose 部署 AstrBot + NapCat 并接入 DeepSeek

这一节是全文的核心，所有配置都可以直接复制。我以 Windows 11 + Docker Desktop 为例，Linux 和 macOS 步骤一致，只是路径和命令前缀不同。先确认 Docker 已经装好并且能正常运行，然后在 PowerShell 里执行一键脚本，或者手动创建目录和 compose 文件。

手动方式更可控，推荐自己建目录。新建一个文件夹，比如 D:\qq-ai-bot，在里面创建 docker-compose.yml，内容如下。这份配置同时起两个服务：napcat 负责 QQ 登录和 OneBot 接口，astrbot 负责消息处理和模型调用。端口映射上，NapCat 的 WebUI 用 6099，OneBot 的 HTTP 和 WebSocket 用 3000 和 3001，AstrBot 的 WebUI 用 6185。

version: "3.8"

services:
  napcat:
    image: mlikiowa/napcat-docker:latest
    container_name: napcat
    restart: unless-stopped
    environment:
      - NAPCAT_UID=1000
      - NAPCAT_GID=1000
    ports:
      - "6099:6099"   # NapCat WebUI
      - "3000:3000"   # OneBot HTTP
      - "3001:3001"   # OneBot WebSocket
    volumes:
      - ./napcat/config:/app/napcat/config
      - ./napcat/data:/app/napcat/data
    networks:
      - botnet

  astrbot:
    image: soulter/astrbot:latest
    container_name: astrbot
    restart: unless-stopped
    ports:
      - "6185:6185"   # AstrBot WebUI
    volumes:
      - ./astrbot/data:/AstrBot/data
    environment:
      - TZ=Asia/Shanghai
    depends_on:
      - napcat
    networks:
      - botnet

networks:
  botnet:
    driver: bridge

保存后，在 D:\qq-ai-bot 目录下打开终端，执行 docker compose up -d。第一次会拉镜像，耐心等几分钟。启动完成后用 docker ps 确认两个容器都是 Up 状态。如果 NapCat 起不来，多半是端口被占用，改一下宿主机端口即可。

接下来配置 AstrBot 的模型提供商。打开 http://localhost:6185，默认账号密码都是 astrbot，登录后先改密码。进入「模型提供商」→「新增模型提供商」，如果走 TaoToken 统一通道，选择「OpenAI 兼容」类型，填入三件套：Base URL 填 https://taotoken.net/api，API Key 填你在控制台创建的 Key，Model ID 填 deepseek-chat。如果直接用 DeepSeek 官方，Base URL 填 https://api.deepseek.com，其余同理。保存后点「测试」，返回成功即通道打通。

然后配置 AstrBot 关联 NapCat。进入「机器人」→「创建机器人」，消息类别选「QQ 个人号」，启用并保存。AstrBot 会通过 OneBot 协议连接 NapCat 的 3001 端口 WebSocket。如果你改了 NapCat 的端口或 Token，这里要对应填上。保存后展开平台日志，用另一个 QQ 号给机器人发消息，日志里出现消息记录就说明链路通了。

4. 验证请求与成功结果：发消息、切人格、看日志确认链路打通

配置完成后必须验证，否则你不知道是模型没通还是 QQ 没通。验证分三层：先确认 NapCat 登录成功，再确认 AstrBot 收到消息，最后确认 DeepSeek 返回内容。三层都过，机器人就算跑起来了。

第一层，打开 http://localhost:6099，输入容器日志里的 Token 登录 NapCat WebUI。Token 可以用 docker logs napcat | Select-String "Token" 找。登录后扫码登录你的测试 QQ 号，看到头像和在线状态就说明 QQ 登录成功。这一步如果失败，通常是 QQ 风控或扫码超时，换个网络环境重试，或者用手机 QQ 确认登录。

第二层，回到 AstrBot 后台，展开「平台日志」。用另一个 QQ 号给机器人发一句「你好」，日志里应该出现类似 received message 的记录。如果日志没动静，检查 AstrBot 机器人配置里的 WebSocket 地址是不是 ws://napcat:3001，容器间通信用服务名而不是 localhost。这是最容易踩的坑：在 compose 网络里，localhost 指向容器自己，不是宿主机。

第三层，看机器人是否回复。如果 QQ 里收到回复，说明 DeepSeek 通道也通了。如果收到的是报错或空回复，去 AstrBot 日志里找 choices 或 401 关键字。401 一般是 Key 无效或 Base URL 写错；reading choices 通常是返回格式不对，检查 Model ID 是否拼错。我实测下来，把 Base URL 末尾的斜杠去掉、Model ID 用官方文档里的准确名称，能解决大部分问题。

验证通过后，可以试一下人格切换。在 QQ 里发 /persona list 查看人格列表，发 /persona 猫娘 切换（把「猫娘」换成你创建的人格 ID）。切换前建议先发 /reset 清空上下文，否则旧人格的对话会影响新人格。再发一条消息，如果回复风格变了，说明人格生效。最后开启「流式回复」，让长回复分段发送，聊天节奏更自然。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth 报错对照

部署过程中最容易卡在几个固定报错上，我把它们整理成对照表，遇到时直接查。这些报错我在不同环境里都遇到过，原因和解法比较稳定。

报错关键字	常见原因	解决方式
401 Unauthorized	API Key 无效、过期或复制时带了空格	重新创建 Key，确认 Base URL 和 Key 匹配同一平台
local proxy failed	容器内访问外部 API 网络不通	检查 Docker 网络，确认容器能解析外网域名
reading choices	返回 JSON 结构不符合 OpenAI 格式	检查 Model ID 和 Base URL，确认接口是 OpenAI 兼容
OAuth 相关	NapCat 登录态失效或 QQ 风控	重新扫码登录，换测试号，避免频繁登录
connection refused	AstrBot 连不上 NapCat 的 WebSocket	容器间用服务名 ws://napcat:3001，不要用 localhost
Token invalid	NapCat Token 填错或日志已滚动	用 docker logs napcat 重新找 Token

重点说 local proxy failed。这个报错通常出现在容器里访问外部 API 时，宿主机能通但容器不通。原因是 Docker 的网络配置或 DNS 问题。可以先在容器里执行 docker exec -it astrbot ping api.deepseek.com，如果 ping 不通，检查 Docker Desktop 的网络设置，或者给 compose 加上 DNS 配置。如果走 TaoToken 通道，确认 Base URL 是 https://taotoken.net/api，不要多加路径。

reading choices 这个报错比较隐蔽，它表示 AstrBot 收到了响应，但解析不出 choices 字段。常见于 Base URL 填成了网页地址而不是 API 地址，或者 Model ID 写成了展示名称。解决方式是回到模型提供商配置，确认 Base URL 以 /v1 或 /api 结尾（按平台文档），Model ID 用准确的模型标识。改完保存，重新测试。

OAuth 报错多出现在 NapCat 登录环节。QQ 对频繁登录、异地登录比较敏感，测试号也可能触发验证。遇到时不要反复扫码，等几分钟再试，或者用手机 QQ 确认账号状态。如果一直失败，换一个测试号。记住，NapCat 的登录态保存在 ./napcat/data 里，删掉这个目录会丢失登录，需要重新扫码。

6. 语义一致 CTA：把 Key、模型和机器人管理收拢到一条通道

链路跑通之后，你会发现真正需要长期维护的不是 Docker 命令，而是 Key 和模型的管理。AstrBot 里可能同时配了 DeepSeek、OpenAI、Claude 多个提供商，每个都有自己的 Key 和余额，时间一长就容易混。这时候用 TaoToken 这类统一通道的价值就体现出来了：一个 Base URL、一个 Key，切换模型只改 Model ID，AstrBot 侧配置不用动。

如果你还在排障阶段，建议先去 TaoToken 的 API Keys 页面创建 Key，再对照接入文档确认 Base URL 和参数格式。文档里有各语言的调用示例，照着填 AstrBot 的 OpenAI 兼容配置即可。如果你已经跑通、想验证模型效果，可以直接用模型对话页面测试不同模型的回复质量，确认哪个更适合你的群聊场景。如果你打算长期跑编码类或 Agent 类任务，Coding Plan 会更划算，适合把机器人做成持续在线的助手。

最后提醒一句：AstrBot 后台保存着 API Key、插件配置和 MCP 命令，公网开放前一定要改默认密码，限制访问范围。NapCat 的 Token 和 QQ 登录态同样敏感，不要出现在公开截图里。用独立测试号逐步验证，确认稳定后再考虑接入更多群。这套组合的价值不在于「一键全能」，而在于你可以按自己的需求，一点点把 QQ 变成顺手的 AI 入口。