Qmin简Q

文档 / 开始

把它跑起来

目标很简单:让一个没写过 QQ 机器人的人,半小时内看到群里有人 @ 它、它回话。 下面三步就是全部。

安装与运行

环境要求:Python 3.11 及以上。需要 Node.js 18+ 的只有 Web 面板,机器人不需要。

git clone https://github.com/qqmin52/qmin.git
cd qmin
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -e .
qmin init
qmin doctor
qmin start

qmin init 会依次询问 AppID、AppSecret、监听地址、端口、日志级别、SQLite 路径,并自动生成管理令牌写入 .env。

不需要构建前端也能跑机器人。 qmin start 照常连接与收发消息;只是打开面板地址会返回一段 JSON 提示,告诉你构建命令。

获取 AppID / AppSecret:q.qq.com → 你的机器人 → 开发设置。机器人还需要在「沙箱配置」里加入测试群,群里必须 @ 它。

第一次运行

qmin doctor 是只读检查:不写文件、不发网络请求。全部通过时退出码 0:

OK  .env 存在:.env
OK  app_id 已填写
OK  app_secret 已填写
OK  admin_token 已设置
OK  插件目录:plugins
OK  插件文件数量:1

配置缺失时退出码为 1,并列出缺什么、去哪儿填:

缺少必要的 QQ 机器人配置,请检查项目根目录的 .env 文件:
  1. app_id(.env 变量名 APP_ID):QQ 开放平台 → 机器人 → 开发设置 → AppID
  2. app_secret(.env 变量名 APP_SECRET):同一页面的 AppSecret
  3. admin_token(.env 变量名 ADMIN_TOKEN):执行 `qmin init` 可自动生成

qmin start 一条命令启动:配置完整就自动连机器人;配置缺失就进入配置向导模式(面板未构建时用 qmin init 补配置)。

命令

命令作用
qmin init交互式生成 .env,并自动创建管理令牌。
qmin doctor只读检查配置与插件目录,不写文件、不发网络请求。
qmin start一条命令启动:有配置自动连机器人,没配置进入配置向导。
qmin token复制管理令牌到剪贴板;加 --show 直接打印明文。

旧版的 qmin run / qmin api 已合并为 qmin start,旧命令会报 No such command。

配置

所有配置都在项目根目录的 .env。同名进程环境变量会覆盖文件里的值。

键含义默认
APP_IDQQ 开放平台机器人 AppID必填
APP_SECRETQQ 开放平台机器人 AppSecret必填
ADMIN_TOKEN管理面板与写接口令牌自动生成
HOST管理接口监听地址127.0.0.1
PORT管理接口端口8000
LOG_LEVELDEBUG / INFO / WARNING / ERRORINFO
DB_PATHSQLite 文件路径(日志持久化)qmin.db
LOG_MAX_ROWS日志表最多保留行数50000
LOG_SDKSDK 日志导流:off 只导 WARNING+,all 连 INFOoff
LOG_MESSAGE_CONTENT入站日志是否记录消息正文true
不要在面板「设置」里改 HOST / PORT 后指望立刻生效——监听地址变了要重启进程;改凭证则点启动即生效。

Web 面板(可选)

想要可视化界面,构建一次前端即可。产物写入 api/static/,由同一个服务托管:

cd webui
npm install
npm run build
cd ..
qmin start

打开 http://127.0.0.1:8000,用 qmin token 复制的令牌登录。

Windows 用户:npm 命令请写成 npm.cmd(npm.cmd install、npm.cmd run build),否则 PowerShell 可能因执行策略拒绝运行 npm.ps1。

面板包含:仪表盘(连接状态、运行时长、插件数、日志数)、日志(SQLite 落库、级别/来源/关键词筛选、加载更早)、插件(安装 / 启用 / 重新加载 / 删除)、设置(凭证与网络配置)。

管理接口默认只绑 127.0.0.1,写操作要求管理令牌与同源 Origin。面板是单机工具,不是公网后台。

常见问题

收不到群消息?

群里必须 @ 机器人,普通聊天不会触发;机器人需要被拉进群,且该群在开放平台「沙箱配置」里。被动回复需在收到消息后 5 分钟内完成。

面板打开是一段 JSON?

前端没构建。qmin start 启动时也会提示构建命令;执行一遍 npm run build 后重启即可。

插件没生效?

面板安装 / 重新加载是即时的;直接放进 plugins/ 的文件需要重启。仍不生效就看面板「日志」页的加载错误,或 qmin doctor 的插件数量。

能同时跑多个机器人吗?

一个 qmin start 管理一个 AppID。多个就多开实例,用不同的 .env 与端口。