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

先给结论:四步跑起 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 消息平台页给出的提示回填,两边握手成功后平台状态会变成已连接。

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

接入 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 协议问题分开排查,少走弯路。

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

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

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

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

常见问题