GenericAgent + QQ 机器人部署 SOP (NapCat + onebot_qq)
概述
本SOP指导你从零开始部署 GenericAgent 的 QQ 机器人网关。通过 NapCat 作为 QQ 协议端，onebot_qq 项目作为中间网关，将 QQ 消息转发给 GenericAgent 处理。
支持系统：Windows / Linux 双平台
前置条件
- 已安装 GenericAgent（目录结构完整）
- Python 3.8+
- 支持系统：Windows / Linux
- 已安装 QQ NT 版本（推荐 9.9.26+，最低版本 40768）
- 一个用于机器人的 QQ 账号
第一部分：NapCat 安装
1.1 下载 NapCat
方法一：GitHub Release（推荐）
- 访问 https://github.com/NapNeko/NapCatQQ/releases/tag/v4.18.1
- 下载对应系统的包：
- Windows: NapCat.Shell.Windows.OneKey.zip
- Linux: NapCat.Shell.Linux.x86_64.zip
- 解压到任意目录（建议路径不含中文和空格）
方法二：备用下载
1.2 安装 NapCat
- 确保已安装 QQ NT 版本（9.9.26+）并登录过一次
- 解压 NapCat 到目标目录
- Windows:
D:\NapCat - Linux:
~/NapCat
- Windows:
- 运行：
- Windows: 运行一键包中的
napcat.bat或login.bat - Linux:
./napcat.sh或bash login.sh
- Windows: 运行一键包中的
- 首次运行会要求登录 QQ（扫码或输入账号密码）
- 登录成功后，控制台会显示 WebUI 地址（通常是
http://127.0.0.1:6099） - 注意：WebUI 的登录密码在控制台输出中查看（默认是随机密码）
1.3 NapCat WebUI 配置
- 浏览器打开 WebUI 地址（如
http://127.0.0.1:6099） - 输入控制台显示的密码登录
- 进入 网络配置 或 适配器配置
- 找到 OneBot v11 适配器
- 启用 WebSocket 服务端（正向WS）
- 配置参数：
- Host:
127.0.0.1 - Port:
8080 - Path:
/onebot/v11/ws - Access Token: 留空（或自定义，需与 onebot_qq 的 .env 一致）
- 消息格式:
array（推荐）
- Host:
- 保存配置
- 确认 OneBot 服务状态为 已启用/运行中
第二部分：onebot_qq 项目部署
2.1 克隆项目
# Windows
cd D:\GenericAgent\temp
git clone https://github.com/jlu005807/GA_onebot_qq.git onebot_qq
# Linux
cd ~/GenericAgent/temp
git clone https://github.com/jlu005807/GA_onebot_qq.git onebot_qq
注意：必须克隆到 GenericAgent 的 temp 目录下，项目依赖 GA 的路径注入。
2.2 安装依赖
# Windows
cd D:\GenericAgent\temp\onebot_qq
pip install -r requirements.txt
# Linux
cd ~/GenericAgent/temp/onebot_qq
pip3 install -r requirements.txt
如果 onebot_qq 和 GenericAgent 使用同一个虚拟环境，可以跳过此步。
2.3 配置 .env
- 复制配置模板：
# Windows
copy .env.example .env
# Linux
cp .env.example .env
如需英文注释模板，可使用
.env.example-en
- 编辑
.env文件，修改以下必填项：
# NapCat 的 WebSocket 地址（必填，与 NapCat WebUI 配置一致）
ONEBOT_WS_URL=ws://127.0.0.1:8080/onebot/v11/ws
# 你的管理员 QQ 号（必填，用于权限控制）
ONEBOT_ADMIN_QQ=你的QQ号
# 访问令牌（如果 NapCat 设置了 token 则填，否则留空）
ONEBOT_ACCESS_TOKEN=
- 其他可选配置：
| 配置项 | 默认值 | 说明 |
|---|---|---|
ONEBOT_ALLOWED_USERS |
* |
允许使用的用户列表，*表示全部 |
ONEBOT_ALLOW_GROUP |
1 |
是否启用群聊（1=启用） |
ONEBOT_ALLOWED_GROUPS |
* |
允许的群号，*表示全部 |
ONEBOT_GROUP_REQUIRE_AT |
空 | 群聊触发模式：1/true=需@机器人；0/false/空=任意消息可触发 |
ONEBOT_GROUP_TRIGGER_WORDS |
空 | 群聊触发词，逗号分隔，命中任一即可触发 |
ONEBOT_CONTEXT_MESSAGES |
0 |
传递触发前历史消息条数，0关闭，最大20 |
ONEBOT_MAX_MSG_LENGTH |
500 |
单条消息最大长度 |
ONEBOT_MAX_QUEUE_SIZE |
5 |
每用户待处理队列上限 |
ONEBOT_PLAIN_TEXT_HINT |
内置 | 附加给Agent的文本提示，0/false/off可关闭 |
ONEBOT_DATA_DIR |
data |
附件保存目录，相对路径基于运行目录 |
ONEBOT_MAX_FILE_BYTES |
10485760 |
单附件最大字节数（默认10MB） |
2.3.1 常用配置组合
-
仅@机器人回复（群内更克制）
ONEBOT_GROUP_REQUIRE_AT=1 ONEBOT_GROUP_TRIGGER_WORDS= ONEBOT_CONTEXT_MESSAGES=0 -
任意群消息触发（测试联调常用）
ONEBOT_GROUP_REQUIRE_AT= ONEBOT_GROUP_TRIGGER_WORDS= ONEBOT_CONTEXT_MESSAGES=0 -
@或触发词+上下文（推荐）
ONEBOT_GROUP_REQUIRE_AT=1 ONEBOT_GROUP_TRIGGER_WORDS=小宇,助手,bot ONEBOT_CONTEXT_MESSAGES=3
2.4 启动 onebot_qq
# Windows
cd D:\GenericAgent\temp\onebot_qq
python src/main.py
# Linux
cd ~/GenericAgent/temp/onebot_qq
python3 src/main.py
启动成功后，控制台应显示：
- WebSocket 连接成功
- GenericAgent 后台线程启动
- OneBot 服务就绪
第三部分：验证与测试
3.1 基础功能测试
- 私聊测试：用其他 QQ 给机器人发送一条消息，确认有回复
- 群聊测试：在群里 @机器人 发送消息，确认有回复
- 附件测试：发送图片/文件，检查
data/image和data/file目录是否有落盘文件
3.2 常见问题排查
| 问题 | 解决方案 |
|---|---|
| 连接被拒绝 (connection refused) | 检查 NapCat 是否启动、OneBot WS 是否启用、端口是否正确 |
| Token 验证失败 (retcode=1403) | 检查 NapCat token 与 .env 的 ONEBOT_ACCESS_TOKEN 是否一致 |
| 群聊不回复 | 确认消息有 @机器人、ONEBOT_ALLOW_GROUP=1、群号在白名单中 |
| 附件未保存 | 检查 NapCat 上报的附件 URL/path 是否有效，确认 ONEBOT_MAX_FILE_BYTES 不过小 |
| 启动报 websockets 参数错误 | 升级 websockets：pip install --upgrade websockets |
| 群聊只想要@触发 | 设置 ONEBOT_GROUP_REQUIRE_AT=1，清空 ONEBOT_GROUP_TRIGGER_WORDS |
| 想要触发词触发 | 设置 ONEBOT_GROUP_TRIGGER_WORDS=词1,词2，逗号分隔 |
| Agent 没有上下文 | 设置 ONEBOT_CONTEXT_MESSAGES=3（或其他数值） |
| 消息被截断 | 调大 ONEBOT_MAX_MSG_LENGTH |
| 用户消息丢失 | 调大 ONEBOT_MAX_QUEUE_SIZE，或让 Agent 快速处理 |
| 附件保存失败 | 检查 ONEBOT_DATA_DIR 路径权限，确认 ONEBOT_MAX_FILE_BYTES 足够 |
| Linux python命令不存在 | 使用 python3 替代 python |
3.3 日志查看
- onebot_qq 日志：
temp/onebot_YYYYMMDD_HHMMSS.log（每次启动生成新文件） - NapCat 日志：NapCat 控制台输出
第四部分：高级配置（可选）
4.1 开机自启动
Windows： 将启动命令写入批处理文件，放入 Windows 启动目录：
@echo off
cd /d D:\GenericAgent\temp\onebot_qq
python src/main.py
Linux： 使用 systemd 或 crontab：
# crontab 示例
@reboot cd ~/GenericAgent/temp/onebot_qq && python3 src/main.py &
4.2 多机器人实例
如需运行多个机器人账号，每个实例需要：
- 独立的 NapCat 实例（不同端口）
- 独立的 onebot_qq 目录（复制一份，修改 .env 端口）
- 修改
lock_port避免冲突
文件结构参考
GenericAgent/
├── temp/
│ └── onebot_qq/ # 本项目
│ ├── src/ # 源代码
│ ├── data/ # 附件存储
│ │ ├── image/
│ │ ├── record/
│ │ └── file/
│ ├── .env # 配置文件
│ ├── .env.example # 配置模板（中文注释）
│ ├── .env.example-en # 配置模板（英文注释）
│ ├── requirements.txt # Python 依赖
│ └── README.md
相关链接
- 项目仓库：https://github.com/jlu005807/GA_onebot_qq
- NapCat GitHub：https://github.com/NapNeko/NapCatQQ
- NapCat 文档：https://napneko.github.io/
更新日志
- 2026-05-05：初始版本，包含 NapCat 安装、onebot_qq 配置、验证测试完整流程
- 2026-05-05：新增配置表、常用配置组合、FAQ
- 2026-05-05：新增 Linux 双平台支持、
python3命令、.env.example-en英文模板、日志文件名格式说明