想给 QQ 群加一个能自动回答问题、写文案、查资料的 AI 机器人在当下已经不算复杂。核心是打通两条链路一条是 DeepSeek 开放平台提供的模型 API一条是 QQ 机器人开放平台提供的事件消息通道。真正让新手卡住的往往是中间那一层申请凭证、订阅事件、异步调用模型、回复消息任何一步没接上机器人都会“假装存在”但完全没有反应。这篇文章会用 Python 3 从零开始带你完整实现 DeepSeek 接入 QQ 机器人的全过程。全程使用 DeepSeek 官方 API 和 QQ 官方机器人 SDK不涉及非官方协议。内容包括平台注册与凭证申请、本地环境搭建、完整可运行代码、启动验证、高频报错排查以及工程化建议。即使你之前没有写过 QQ 机器人只要照着操作也能跑通。1. 接入方案与整体原理1.1 为什么优先选官方渠道不少人在搜索 QQ 机器人接入时会看到各种基于第三方协议的方案。这些方案确实功能花哨但本质上大多通过逆向、模拟客户端等方式接入存在账号风控、封号、隐私泄露等风险而且很容易随着 QQ 客户端更新而失效。本文采用官方渠道原因很明确稳定官方接口和官方 SDK 会持续维护不会因为客户端升级而突然失效。安全AppID、AppSecret、API Key 都掌握在自己手里不经过第三方转发。合规符合平台规则适合学习、测试以及正式上线的业务场景。省事不需要额外搭建消息中转服务官方 SDK 使用 WebSocket 长连接收消息本地就能跑。1.2 消息链路拆解整个系统最核心的消息流转过程可以拆成下面几个步骤用户 机器人 或 私聊机器人 ↓ QQ 服务器推送事件 ↓ 官方 SDKbotpy收到消息事件 ↓ 程序提取用户文本内容 ↓ 调用 DeepSeek API携带参数请求模型 ↓ DeepSeek 返回 AI 回复文本 ↓ 程序调用 QQ 官方 API 把回复发回群/私聊从代码角度来说我们要做的事其实只有三件收到 QQ 消息事件。把消息文本提交给 DeepSeek。把 DeepSeek 的回复再发出去。1.3 技术选型WebSocket 和 WebHook 怎么选QQ 机器人官方提供了两种接收消息的方式。WebSocket 模式由 SDK 主动和 QQ 服务器建立长连接。不需要公网 IP不需要域名不需要配置 HTTPS 证书。适合本地开发和个人项目。适合新手入门。WebHook 模式由 QQ 服务器向你的公网接口推送事件。需要公网服务器、域名和 HTTPS 证书。适合正式线上服务也适合和现有后端服务集成。配置相对复杂。本文选择 WebSocket 模式原因很简单零公网成本本地就能完成全部联调。2. 前置准备DeepSeek 开放平台配置在写代码之前需要先把几个“通行证”准备好。第一步就是 DeepSeek 开放平台的 API Key。2.1 注册并创建 API Key打开 DeepSeek 开放平台使用手机号或邮箱注册登录。登录后进入控制台找到 API Key 管理页面。创建 API Key 时注意以下几点API Key 通常以sk-开头创建完成后只会完整显示一次之后无法再次查看必须先复制保存到本地。不要把 API Key 直接写在代码里提交到 GitHub后面会专门讲密钥管理。一个账号可以创建多个 Key建议区分开发环境、测试环境和生产环境方便出问题时单独吊销。2.2 确认 API 地址与模型名DeepSeek 官方接口兼容 OpenAI 的调用格式。也就是说Python 代码里可以直接使用openai这个包把base_url指向 DeepSeek 的接口地址。常用的 model 名称有两个deepseek-chat通用对话模型适合绝大多数问答、写作、总结场景。deepseek-reasoner深度推理模型适合复杂逻辑推导但响应速度通常比 chat 模型慢。部分第三方中转服务可能提供其他自定义模型名本文以 DeepSeek 官方模型名为准。需要注意平台功能和模型名称可能随着版本调整具体以 DeepSeek 开放平台文档为准。2.3 费用与配额提示DeepSeek 的计费方式是按 token 计费。token 可以简单理解为“模型看到的字符片段”中文、英文、标点都会消耗 token。对个人开发来说日常测试和群聊机器人调用量不大成本一般可控。但建议在控制台设置“余额预警”避免不知不觉消耗完。代码中限制单次回复长度控制max_tokens。不带上下文记忆时每次请求只包含当前问题避免历史消息反复计费。3. 前置准备QQ 机器人开放平台配置DeepSeek 这边准备好之后接下来是 QQ 官方机器人平台。3.1 创建机器人应用进入 QQ 开放平台使用 QQ 扫码登录。登录后找到“机器人”相关入口创建一个新的机器人应用。创建时需要填写机器人名称。头像。功能介绍。这些信息会和机器人形象直接相关建议认真填写。名称和头像在审核阶段会被检查不要包含明显违规或夸张表述。3.2 获取 AppID 与 AppSecret机器人创建完成后进入开发设置页面能看到两个关键字段AppID机器人的唯一身份标识。AppSecret机器人的密钥用于 SDK 鉴权连接。AppSecret 的敏感程度和 DeepSeek API Key 一样不要泄露、不要提交到公开仓库。后续代码中这两个值会传给 botpy SDK 的client.run()方法。3.3 配置事件订阅要让机器人能处理群消息和私聊消息必须在开放平台打开对应的事件订阅。在开发设置里选择 WebSocket 模式然后申请以下事件权限接收群聊消息通常对应“群 机器人”事件。接收 C2C 消息也就是用户私聊机器人。不同版本的平台界面可能略有差异但核心逻辑一致申请权限、等待审核或加入沙箱白名单、然后才能收到对应消息事件。如果只申请了群消息权限私聊事件就永远不会触发。3.4 沙箱环境与上线前准备QQ 开放平台提供了沙箱测试机制。沙箱模式下机器人不是对所有用户开放而是只对指定的测试人员或白名单用户生效。这对调试阶段非常友好可以避免机器人还没写好就被陌生人反复调用。在沙箱里测试时需要把测试 QQ 号添加到白名单。需要把机器人拉到一个测试群群里至少要有白名单用户。群内测试时必须是“机器人 内容”的格式群机器人通常不支持自动响应所有消息。功能稳定、准备对外发布时再提交上架审核。审核通过后机器人才能在更多群或用户范围内使用。4. 本地环境搭建平台配置完成接下来进入代码环节。4.1 安装 Python本文示例使用 Python 3建议使用 3.9 及以上版本。可以在终端输入以下命令确认版本python --version如果没有安装 Python去官网下载对应系统版本安装即可。Windows 用户安装时记得勾选“Add Python to PATH”。4.2 创建项目目录在本地新建一个项目目录例如qq-deepseek-botmkdir qq-deepseek-bot cd qq-deepseek-bot4.3 安装依赖在项目里创建虚拟环境然后安装依赖。Linux / macOS 执行python3 -m venv venv source venv/bin/activateWindows 执行python -m venv venv venv\Scripts\activate然后安装两个核心库pip install qq-botpy openai说明一下它们的作用qq-botpy腾讯官方提供的 QQ 机器人 Python SDK封装了 WebSocket 连接、事件接收、消息发送等能力。openai官方 OpenAI Python SDKDeepSeek 接口兼容 OpenAI 格式因此可以直接用它来调用 DeepSeek 模型。为了统一管理依赖可以在项目目录下创建requirements.txtqq-botpy openai后续换环境时直接执行pip install -r requirements.txt5. 完整代码实现环境准备完毕后开始编写核心代码。5.1 目录结构与配置入口建议把代码拆成三个文件职责清晰后面扩展也方便qq-deepseek-bot/ ├── config.py # 配置文件负责读取环境变量 ├── deepseek_client.py # DeepSeek 调用封装 ├── bot.py # QQ 机器人主程序 └── requirements.txt # 依赖清单先创建config.py# 文件路径config.py import os # DeepSeek 配置 DEEPSEEK_API_KEY os.getenv(DEEPSEEK_API_KEY, ) DEEPSEEK_BASE_URL os.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com) DEEPSEEK_MODEL os.getenv(DEEPSEEK_MODEL, deepseek-chat) # QQ 机器人配置 QQ_APP_ID os.getenv(QQ_APP_ID, ) QQ_APP_SECRET os.getenv(QQ_APP_SECRET, ) # 回复消息最大长度避免触发平台长度限制 MAX_REPLY_LEN 500这里使用os.getenv读取环境变量好处是敏感信息不会硬编码在代码文件里。如果某个环境变量没有设置程序会使用空字符串后续启动时会统一检查。5.2 封装 DeepSeek 客户端接下来创建deepseek_client.py负责调用 DeepSeek API# 文件路径deepseek_client.py import asyncio from openai import AsyncOpenAI from config import ( DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL, DEEPSEEK_MODEL, ) _client None def get_client(): global _client if _client is None: _client AsyncOpenAI( api_keyDEEPSEEK_API_KEY, base_urlDEEPSEEK_BASE_URL, ) return _client async def ask_deepseek(user_content: str, system_content: str ): 调用 DeepSeek 对话接口返回文本回复。 if not DEEPSEEK_API_KEY: return DeepSeek API Key 未配置请检查环境变量 DEEPSEEK_API_KEY。 if not user_content.strip(): return 你好像没有输入内容哦。 system_content system_content or 你是一个友好的QQ群AI助手回答简洁、准确、友好。 try: # 使用 wait_for 设置 30 秒超时避免一直等待模型响应 resp await asyncio.wait_for( get_client().chat.completions.create( modelDEEPSEEK_MODEL, messages[ {role: system, content: system_content}, {role: user, content: user_content}, ], temperature0.7, max_tokens1024, ), timeout30, ) return resp.choices[0].message.content.strip() except asyncio.TimeoutError: return 抱歉AI 响应超时了请稍后再试。 except Exception as e: return f抱歉调用 DeepSeek 时出现异常{e}这段代码有几个细节值得说明使用AsyncOpenAI是因为 QQ 机器人的 SDK 是异步框架事件回调本身就是async函数。如果在这里使用同步请求会阻塞整个事件循环导致机器人同时只能处理一条消息体验很差。asyncio.wait_for用于设置超时时间防止 DeepSeek 接口迟迟不返回时机器人卡死。msg_id在原生 OpenAI SDK 里并不是一个参数不需要传消息的msg_id是在 QQ 机器人层控制的。5.3 编写 QQ 机器人主程序创建bot.py这是整个机器人的入口# 文件路径bot.py import re import botpy from botpy.message import C2CMessage, GroupMessage from config import ( DEEPSEEK_API_KEY, MAX_REPLY_LEN, QQ_APP_ID, QQ_APP_SECRET, ) from deepseek_client import ask_deepseek SYSTEM_PROMPT 你是一个跑在QQ群和私聊里的AI助手回答要简洁、准确、友好。 def clean_message(text: str) - str: 清洗消息内容去掉 QQ 消息里的 占位符。 不同版本 SDK 返回的格式可能不同这里做通用处理。 if not text: return # 去掉 !123456 或 123456 这类占位符 text re.sub(r!?\d, , text).strip() return text def cut_reply(text: str, max_len: int MAX_REPLY_LEN) - str: 超长回复截断避免触发平台长度限制。 if len(text) max_len: return text return text[:max_len] ……消息过长已截断 class QQDeepSeekBot(botpy.Client): async def on_group_at_message_create(self, message: GroupMessage): 群聊中 机器人 时触发。 prompt clean_message(message.content) if not prompt: await message._api.post_group_message( group_openidmessage.group_openid, msg_type0, msg_idmessage.id, content请直接在群里 我 并输入你想问的问题, ) return reply await ask_deepseek(prompt, system_contentSYSTEM_PROMPT) reply cut_reply(reply) await message._api.post_group_message( group_openidmessage.group_openid, msg_type0, msg_idmessage.id, contentreply, ) async def on_c2c_message_create(self, message: C2CMessage): 用户私聊机器人时触发。 prompt clean_message(message.content) if not prompt: await message._api.post_c2c_message( openidmessage.author.user_openid, msg_type0, msg_idmessage.id, content请输入你想问的问题, ) return reply await ask_deepseek(prompt, system_contentSYSTEM_PROMPT) reply cut_reply(reply) await message._api.post_c2c_message( openidmessage.author.user_openid, msg_type0, msg_idmessage.id, contentreply, ) def main(): if not QQ_APP_ID or not QQ_APP_SECRET: raise RuntimeError(请先配置 QQ_APP_ID 和 QQ_APP_SECRET 环境变量) if not DEEPSEEK_API_KEY: raise RuntimeError(请先配置 DEEPSEEK_API_KEY 环境变量) intents botpy.Intents( group_messageTrue, c2c_messageTrue, ) client QQDeepSeekBot(intentsintents) client.run(appidQQ_APP_ID, secretQQ_APP_SECRET) if __name__ __main__: main()这段代码看起来不长但它已经覆盖了完整闭环。关键点说明on_group_at_message_create是群聊 事件回调方法SDK 收到事件后会自动调用。on_c2c_message_create是私聊事件回调方法。message._api是 SDK 内部封装的消息发送 API可以直接调用发送接口。post_group_message和post_c2c_message都是被动回复消息msg_id用于告诉平台“这是对某条消息的回复”。botpy.Intents用于声明要订阅哪些事件这里订阅了群消息和私聊消息。5.4 配置环境变量在运行之前需要把密钥配置到环境变量里。Linux / macOSexport DEEPSEEK_API_KEYsk-你的key export QQ_APP_ID你的AppID export QQ_APP_SECRET你的AppSecretWindows CMDset DEEPSEEK_API_KEYsk-你的key set QQ_APP_ID你的AppID set QQ_APP_SECRET你的AppSecretWindows PowerShell$env:DEEPSEEK_API_KEYsk-你的key $env:QQ_APP_ID你的AppID $env:QQ_APP_SECRET你的AppSecret如果你不想每次打开终端都重新设置也可以在项目目录下创建.env文件并交给加载工具处理。但要注意.env文件同样不能提交到 git 仓库。6. 运行与效果验证6.1 启动机器人在项目目录下执行python bot.py如果配置无误SDK 会输出类似“连接成功”或开始接收事件的相关日志。此时程序会一直前台运行不要关闭窗口。6.2 在群里 机器人打开测试群确保机器人已经被拉进群。发送机器人 你好请介绍一下你自己正常情况下机器人会很快回复一段 AI 生成的自我介绍。这里要特别注意群机器人通常只能响应“机器人”的消息不会自动回复群内所有消息。如果希望机器人只被 时响应也就是说群内所有消息都处理需要额外申请“接收群聊消息”权限并且在代码里做更多过滤逻辑。本文示例默认只处理 事件比较安全。6.3 私聊机器人在 QQ 上找到机器人发送帮我写一段关于机器学习的 100 字介绍机器人会通过on_c2c_message_create事件收到这条消息然后调用 DeepSeek 生成内容再通过post_c2c_message回复。6.4 观察日志运行期间终端会打印 SDK 日志和可能的异常信息。建议保持终端可见。如果 DeepSeek 调用失败ask_deepseek会把错误信息拼在回复里返回到 QQ方便排查。一个比较实用的调试技巧在启动机器人之前直接单独测试 DeepSeek 链路。可以写一个临时脚本import asyncio from deepseek_client import ask_deepseek async def main(): result await ask_deepseek(你好) print(result) asyncio.run(main())这样可以做到“先验证模型接口通不通再验证 QQ 消息链路通不通”问题定位会高效很多。7. 常见问题与排查清单7.1 高频问题对照表问题现象常见原因解决思路机器人启动报缺少 AppID/AppSecret环境变量未设置或设置后未在当前终端生效检查 export/set 命令重新打开终端再试机器人不掉线但群里收不到消息开放平台事件订阅未开启或沙箱白名单未配置检查 QQ 开放平台事件权限确认机器人已拉入测试群私聊机器人无反应未申请 C2C 消息权限或用户不在白名单检查开放平台 C2C 权限和白名单调用 DeepSeek 报 401API Key 错误、过期或 Key 复制多了空格重新生成 Key检查环境变量前后是否有空格机器人回复超时网络问题或 DeepSeek 响应较慢增大asyncio.wait_for超时时间检查网络连通性回复内容被平台拒绝回复内容过长或包含敏感词在cut_reply中缩短 max_len设置更严格的内容校验运行报ModuleNotFoundError: No module named botpy未安装qq-botpy执行pip install qq-botpyWebSocket 连接频繁断开网络不稳定或长时间没有心跳官方 SDK 通常会自动重连检查本地网络7.2 深挖两个典型错误第一个典型错误DeepSeek 返回401 Authentication Fails。这个错误绝大多数情况下是 API Key 没配好Key 是否复制完整sk-开头末尾没有空格。是否在启动python bot.py之前设置环境变量export只对当前终端会话生效。是否使用了错误的 Key可以在 DeepSeek 平台重新创建。第二个典型错误机器人能跑但群里 之后没有任何反应。这个问题大概率不在代码而在平台配置。按顺序检查机器人的“事件订阅”是否勾选了群聊消息。机器人是否真的在测试群里。测试号是否在白名单里。是否发送了 机器人的消息而不是普通群消息。如果这些都确认没问题再看本地日志。日志中如果没有任何事件输出说明事件根本没推到本地问题依然在平台侧。8. 工程化建议与安全边界个人小玩具能跑通之后如果要进一步做成稳定的服务需要考虑下面几个方面。8.1 密钥管理现在很多项目的翻车现场都是把 API Key 或 AppSecret 提交到了 GitHub。建议从一开始就养成习惯所有密钥通过环境变量注入。项目根目录添加.gitignore把.env、venv、日志文件排除在外。不同环境使用不同的 API Key方便单独吊销。定期检查代码仓库历史一旦发现密钥泄露立即去平台吊销并重新生成。8.2 超时与重试DeepSeek API 偶尔会因为网络波动或高峰期排队而变慢。asyncio.wait_for设置了超时时间但超时后直接返回错误用户会看到“响应超时”的提示。更健壮的做法是加入重试机制第一次调用失败后等待 1-2 秒重试一次。重试次数建议不超过 3 次。针对 401/403 等鉴权错误不要重试因为重试也没用。8.3 消息长度与频率控制QQ 官方接口对单条消息长度有限制群聊和私聊可能不完全一样。代码里的cut_reply函数只做了简单截断。更优雅的方案是超长回复拆成多条消息按顺序发送。根据问题类型决定是否启用deepseek-reasoner因为推理模型生成内容更长。对同一用户的请求做频率限制防止有人恶意刷消息导致 API 费用飙升。8.4 内容安全问题DeepSeek 本身有一定的内容安全机制但接入 QQ 群后机器人会被很多人使用。建议在 system prompt 中明确说明“拒绝回答违法、暴力、低俗内容”。对用户输入和 AI 输出都做简单敏感词过滤。保留运行日志但日志中不要记录完整消息内容尤其是包含手机号、身份证号等个人信息时要做脱敏处理。8.5 关于第三方协议的风险提示市面上存在着大量基于非官方协议的 QQ 机器人框架它们最吸引人的地方是“功能多、不需要审核、什么都能做”。但代价也很明显违反平台用户协议账号可能被限制或封禁。通过逆向和模拟客户端实现一旦协议更新随时失效。中间可能经过第三方服务器消息内容存在泄露风险。很多“免费框架”会夹带广告、挖矿脚本等不可控代码。如果你的目标是长期稳定运行建议老老实实使用官方平台能力。官方权限不够用就去申请更多官方权限。9. 最后给你一个调试建议把整个流程跑通之后你会发现代码本身并不复杂复杂的是环境配置和平台权限。最后一个实用的调试技巧开发阶段不要把验证步骤耦合在一起。先把ask_deepseek()单独测试确认 DeepSeek 链路是通的再启动机器人确认 QQ 事件能收到最后再合到一起测完整流程。很多“机器人没反应”的问题其实都是因为 DeepSeek 调用抛了异常而异常信息只打印在终端里没有注意。如果你按本文操作成功跑通了机器人下一步可以考虑加离线记忆、关键词指令、多轮上下文甚至用 Docker 部署到服务器上常驻运行。如果这篇文章对你有帮助可以收藏备用运行中遇到其他问题欢迎在评论区留言交流。