文档 / 开始
把它跑起来
目标很简单:让一个没写过 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_ID | QQ 开放平台机器人 AppID | 必填 |
APP_SECRET | QQ 开放平台机器人 AppSecret | 必填 |
ADMIN_TOKEN | 管理面板与写接口令牌 | 自动生成 |
HOST | 管理接口监听地址 | 127.0.0.1 |
PORT | 管理接口端口 | 8000 |
LOG_LEVEL | DEBUG / INFO / WARNING / ERROR | INFO |
DB_PATH | SQLite 文件路径(日志持久化) | qmin.db |
LOG_MAX_ROWS | 日志表最多保留行数 | 50000 |
LOG_SDK | SDK 日志导流:off 只导 WARNING+,all 连 INFO | off |
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 复制的令牌登录。
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 与端口。