AstrBot 教程:QQ AI 机器人搭建与配置指南

Q: AstrBot 怎么接入 DeepSeek 或第三方 API?

在 WebUI 的 服务提供商 页添加 OpenAI 类型提供商,API Base URL 填 https://api.kkaiapi.com/v1,Key 用 kkaiapi 控制台生成的令牌,模型填 deepseek-v4-flash 等 ID。一个 Key 可以同时调 DeepSeek、GLM、Kimi、Claude、GPT,不用维护多家账号。

最后更新: 2026-07-13

AstrBot 用 Docker 一条命令部署,在 WebUI 添加 OpenAI 兼容提供商,API Base URL 填 https://api.kkaiapi.com/v1,再用 NapCat 或 QQ 官方接口接入 QQ,群里就有了 AI 机器人。群聊高频场景把默认模型设为 deepseek-v4-flash,配合唤醒前缀和白名单控制触发,成本能压得很低。

先给结论:四步跑起 QQ AI 机器人

kkaiapi 是面向中文开发者的 OpenAI 兼容模型中转,一个 Key 可同时调用 DeepSeek、GLM、Kimi、Claude、GPT 等模型,支付宝或微信充值,按量计费无订阅。还没有 Key 的话先到充值页开通并在控制台生成令牌,再跟着下面逐步展开。

第一步:Docker 部署 AstrBot,浏览器打开 6185 端口进 WebUI,默认账号密码均为 astrbot,登录后立即修改
第二步:在服务提供商页添加 OpenAI 类型提供商,API Base URL 填 https://api.kkaiapi.com/v1,粘贴 sk- 开头的 Key,模型填 deepseek-v4-flash
第三步:在消息平台页添加 QQ 适配器,个人号走 NapCat 反向 WebSocket,或走 QQ 开放平台官方接口
第四步:在人格页写好系统提示词,设置唤醒前缀,把机器人拉进群 @ 它测试

部署 AstrBot 并接入 QQ:两条协议路线怎么选

用下面的 docker-compose 起服务,data 目录务必挂载出来,配置和聊天记录都在里面。启动后浏览器访问 http://服务器IP:6185 进 WebUI。接 QQ 有两条路线,个人玩家想要完整群聊体验一般选 NapCat:单独部署 NapCat 登录一个 QQ 小号,在它的网络配置里添加反向 WebSocket,地址按 AstrBot 消息平台页给出的提示回填,两边握手成功后平台状态会变成已连接。

docker-compose.yml

services:
  astrbot:
    image: soulter/astrbot:latest
    ports:
      - "6185:6185"
    volumes:
      - ./data:/AstrBot/data
    restart: unless-stopped

接入路线	优点	限制与风险
QQ 开放平台官方接口	合规稳定,不怕风控,适合长期运营	需要注册审核,个人主体能力受限,主要靠 @ 触发被动回复
NapCat / Lagrange(OneBot 协议)	功能完整,主动发言、群管理、表情回应都能做	基于个人 QQ 号,存在风控与冻结风险,建议用小号并控制发送频率

接入 OpenAI 兼容模型源:三项配置就够

AstrBot 把模型源抽象成统一的服务提供商,任何 OpenAI 兼容端点都能接。在 WebUI 的服务提供商页新增,类型选 OpenAI,按下面示例填三项。模型 ID 必须逐字符一致,当前可用:deepseek-v4-flash、deepseek-v4-pro、glm-5、kimi-k2.6、claude-sonnet-4-6、claude-opus-4-7、gpt-5.5、grok-4.5。保存后先在 WebUI 的对话调试页发一句话:通了说明模型源没问题,再去 QQ 里测;不通就查 Key 和 Base URL。这样能把模型源问题和 QQ 协议问题分开排查,少走弯路。

AstrBot 服务提供商配置

提供商类型: OpenAI
API Base URL: https://api.kkaiapi.com/v1
API Key: sk-你的密钥
模型: deepseek-v4-flash

人设与群聊配置:让机器人像个正经群友

人设在 WebUI 的人格页配置,本质是系统提示词。写清楚三件事:它是谁、怎么说话、什么不能说。群聊场景务必限制回复长度,机器人刷屏是被踢出群的头号原因。群聊行为有四个关键开关。唤醒前缀:默认斜杠,建议保留,加上 @ 唤醒,只在被点名时说话。会话隔离:开启后群内按成员隔离上下文,避免几个人的话题互相串线。上下文条数:直接决定每次请求携带的 token 量,群聊压到 8 到 12 条足够。白名单:先在自己的测试群跑几天,确认行为稳定再进大群。

群聊人设提示词示例

你是群里的助理"小柯",说话简短、活泼、有梗。
规则:
1. 回答控制在 100 字以内,群聊不要刷屏
2. 技术问题给可操作的答案,不确定就直说
3. 拒绝违规话题,不讨论群成员隐私

成本控制:群聊高频场景选便宜模型

群聊机器人的成本特点是请求频次高、单次输出短,大头是每次都要重复携带的上下文输入。三个开关按顺序拧:默认模型用 deepseek-v4-flash;上下文条数压低;唤醒方式收紧,只允许前缀和 @ 触发,不开全量监听。需要高质量长文时,比如群周报总结或重要文案,临时切 claude-sonnet-4-6 或 gpt-5.5,用完切回。按下表价格算,一个活跃群每天触发两百次,每次两千输入五百输出 tokens,用 deepseek-v4-flash 一天成本不到五毛钱。价格全文只列这一次:

完整列表以价格页为准,充值入口见 /topup
模型 ID	kkaiapi(¥/1M tokens,输入/输出)	官方价对比	机器人场景定位
deepseek-v4-flash	0.5 / 1	官方 1 / 2	群聊日常主力,闲聊问答性价比最高
glm-5	3 / 13.5	官方 4 / 18	中文人设扮演、创意回复
kimi-k2.6	5 / 20	官方 6.5 / 27	长上下文,长文总结
claude-sonnet-4-6	3 / 15	/	代码问答、复杂推理
claude-opus-4-7	5 / 25	/	最强文笔,重要文案偶尔用
gpt-5.5	4 / 25	/	通用旗舰、工具调用
grok-4.5	2 / 6	官方 14 / 42	轻量问答

合规提醒:别让机器人变成风险源

协议层:官方接口按平台规范使用即可;NapCat 等第三方协议注意风控,不要高频主动私聊陌生人,不要做营销群发,小号运行、控制频率。内容层:人设提示词里写明边界,群聊输出要符合 QQ 平台的内容规范。各家模型有各自的内容政策:DeepSeek V4 系创作自由度、角色一致性和成本平衡得最好,是社区角色扮演首选;GLM-5 和 Kimi 适合长设定;Claude 文笔最强但 Anthropic 政策较严,适合普通创作场景。详细对比见站内的模型内容政策专文。数据层:群聊消息会作为上下文发给模型 API,涉及内部信息或隐私的群要慎接,日志目录里也别长期留存敏感内容。

常见问题

AstrBot 怎么接入 DeepSeek 或第三方 API?

在 WebUI 的服务提供商页添加 OpenAI 类型提供商,API Base URL 填 https://api.kkaiapi.com/v1,Key 用 kkaiapi 控制台生成的令牌,模型填 deepseek-v4-flash 等 ID。一个 Key 可以同时调 DeepSeek、GLM、Kimi、Claude、GPT,不用维护多家账号。

AstrBot 和 NoneBot、Koishi 有什么区别,该选哪个?

AstrBot 开箱即用,自带 WebUI 和 LLM 对话能力,适合想直接跑 AI 机器人的玩家。NoneBot 和 Koishi 是更通用的机器人框架,插件生态大,适合要深度定制的开发者,但接 LLM 需要额外装插件。两条路线的配置站内都有教程。

用 AstrBot 搭 QQ 机器人会被封号吗?

QQ 开放平台官方接口没有封号风险。NapCat、Lagrange 等第三方协议基于个人 QQ 号,存在风控可能:用小号运行、控制发送频率、不做营销群发能显著降低概率,但无法完全排除,重要大号不要拿来跑机器人。

AstrBot 机器人在群里不回复怎么排查?

三步定位。先在 WebUI 对话调试页直接发消息,通了说明模型源正常;再看消息平台页的连接状态,NapCat 反向 WebSocket 掉线是常见原因;最后查唤醒条件,默认需要 @ 机器人或带前缀触发,用普通消息测是不会回的。

群聊机器人 token 消耗太快怎么办?

按顺序拧三个开关:默认模型换成 deepseek-v4-flash;上下文条数压到 8 到 12 条;唤醒收紧到只响应 @ 和前缀。另外人设提示词精简到几百字以内,它每次请求都会计入输入 tokens,写得越长烧得越快。