AI导哈

QQ聊天机器人

基于NapCat（OneBot）和OpenAI兼容LLM的QQ机器人，具备消息收发、提醒功能、每日使用统计及可选外部工具集成。

  • by Miaoge-Ge
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Miaoge-Ge/qq-llm-bot

使用说明

QQ LLM机器人（NapCat/OneBot）

中文说明

一个基于NapCat（OneBot）的实用QQ机器人，由OpenAI兼容的LLM提供支持。包括MCP工具、提醒和日常使用统计数据（愿景通过MCP提供）。

特性

  • NapCatQQ（OneBot）接收/发送
  • 分组路由模式：提及/关键字/全部
  • 提及/关键字后的小组跟进窗口（继续回复几圈，不再提及）
  • 提醒：在私人或群聊中创建/列出/取消提醒
  • 可选MCP工具（外部工具服务器）
  • 每日每个用户的使用统计数据（令牌/调用/工具调用）保存到CSV

项目布局

  • src/ TypeScript源代码
  • dist/ 构建输出(npm run build)
  • data/ 运行时数据（笔记、提醒、统计数据）。被git忽略了。
  • prompts/ 系统提示文件
  • knowledge/ 知识示例/RAG资源
  • .env 本地配置（被git忽略）和 .env.example 模板

需求

  • Node.js 18+
  • NapCatQQ在OneBot WebSocket事件+启用HTTP API的情况下运行

快速开始

npm install
cp .env.example .env
npm run doctor
npm run dev

配置

复制 .env.example 到 .env 只改变自己的价值观。

NapCat/QQ

  • NAPCAT_HTTP_URL NapCat HTTP API基础URL
  • NAPCAT_WS_URL NapCat WebSocket事件URL
  • NAPCAT_HTTP_TOKEN / NAPCAT_WS_TOKEN 可选令牌
    • 如果不在中设置令牌 .env，机器人可以从本地NapCat OneBot配置（如果可用）自动加载它们。
  • BOT_QQ_ID 可选（自动检测自 self_id 如果未设置）
  • BOT_NAME 机器人昵称（默认值： 小助手)

LLM

  • LLM_BASE_URL OpenAI兼容网关基础URL
  • LLM_API_KEY API密钥
  • LLM_MODEL 型号名称
  • LLM_TEMPERATURE 采样温度（默认值： 0.3)

脚本

npm run dev     # run bot in dev mode
npm run doctor  # check NapCat HTTP/WS connectivity
npm run build   # compile to dist/
npm run start   # run dist/ output
npm run test    # run tests

组回复模式

  • GROUP_REPLY_MODE:
    • mention （默认）：提及时回复；如果已配置，还可以回复昵称/关键字
    • keyword：当出现任何关键字时回复
    • all：回复所有群消息
  • GROUP_KEYWORDS 关键字数组（JSON）或逗号分隔列表
  • GROUP_FOLLOWUP_TURNS 触发后要处理的后续消息数（默认值： 4)
  • GROUP_FOLLOWUP_TTL_MS 后续窗口TTL（毫秒）（默认值： 120000)

使用统计数据（每日CSV）

  • 机器人记录每个用户的每日使用统计数据：
    • 如果网关返回，LLM调用和令牌（提示/完成/总计） usage
    • 工具调用计数（包括MCP和内置工具）
  • 文件写入到：
    • STATS_DIR/YYYY-MM-DD.csv （推荐）或 DATA_DIR/stats/YYYY-MM-DD.csv 默认情况下
  • 聊天中的查询：
    • token统计 / 今日统计 / 我的统计 / 今日用量 / 我的用量

系统提示

选择一个：

  • SYSTEM_PROMPT_FILE=prompts/system.txt （推荐）
  • SYSTEM_PROMPT=...

MCP（可选外部工具）

此项目使用 mcp.servers.json 启动/连接MCP服务器。一台服务器可以暴露多个工具，机器人通过以下方式发现它们 listTools.

例子：

{
  "servers": [
    {
      "name": "tools",
      "command": "node",
      "args": ["dist/mcp/servers/tools.js"],
      "enabled": true,
      "tools": {
        "weather_query": true,
        "web_search": true
      }
    }
  ]
}
  • enabled：启用/禁用整个服务器
  • tools：可选。两种模式：
    • 允许列表：如果有值 true，仅标记工具 true 已启用
    • Denylist：如果没有 true，默认情况下启用所有工具；集 false 禁用特定工具

安全说明

  • 永不承诺 .env 或任何真正的API密钥。此回购忽略 .env 和 .env.* 默认情况下，并保持 .env.example.
  • 如果你不小心将一个密钥推送到GitHub，请立即旋转它，并在需要时重写历史记录。
  • 本地NapCat捆绑包(NapCat.Shell.Windows.Node/)以及运行时数据(data/)被忽略以避免泄露令牌和聊天日志。

故障排除

  • HTTP显示 403 token verify failed：set NAPCAT_HTTP_TOKEN 正确地。
  • Bot收到消息但不回复：检查路由模式(GROUP_REPLY_MODE)以及该消息是否触发了提及/关键字逻辑。

学分

  • NapCatQQ（OneBot/NTQQ协议端）：https://github.com/NapNeko/NapCatQQ

相关 MCP