为 Hermes Agent 提供 QQ OneBot v11 平台支持。
支持 LLOneBot、LLBot、Lagrange.OneBot、NapCatQQ、go-cqhttp 等 OneBot 兼容实现。
- Hermes Agent
>= 0.20.0 - 一个提供 OneBot v11 WebSocket 或 HTTP API 的 QQ 实现
- Hermes 使用的 Python 环境通常已经包含
websockets；只有插件检查提示缺失时才需要手动安装
hermes plugins install chrysoljq/hermes_qq_onebot --enable检查插件状态：
hermes plugins list如果插件检查提示缺少 websockets，再在 Hermes 使用的 Python 环境中安装：
python -m pip install "websockets>=13"修改配置后重启 Gateway：
hermes gateway restart如果同时存在同名的 bundled plugin 和 user plugin，只保留一个，避免加载旧版本。
在 Hermes 配置文件的 platforms 下添加：
platforms:
qqonebot:
enabled: true
extra:
# 推荐：OneBot 连接 Hermes 的反向 WebSocket
reverse_mode: true
reverse_host: "127.0.0.1"
reverse_port: 6700
# OneBot HTTP API
http_api_url: "http://127.0.0.1:5700"
# 启用了 OneBot token 时填写
access_token: ""
# 群聊关键词触发；支持字符串或列表，按正则匹配
mention_patterns:
- "芙芙"
# 逗号分隔的 QQ 号；留空表示不限制
allowed_qq_ids: "123456789,987654321"
# 是否在用户名中显示 QQ 号
show_qq_id: false
# 默认关闭
allow_private_media_urls: false
allow_local_media_paths: false如果由 Hermes 主动连接 OneBot：
platforms:
qqonebot:
enabled: true
extra:
reverse_mode: false
ws_host: "127.0.0.1"
ws_port: 3001
ws_path: "/onebot/v11/ws"
http_api_url: "http://127.0.0.1:5700"也可以使用完整地址：
platforms:
qqonebot:
extra:
ws_url_override: "ws://127.0.0.1:3001/onebot/v11/ws"环境变量适合保存 token 和部署参数：
QQ_ONEBOT_WS_URL=ws://127.0.0.1:3001/onebot/v11/ws
QQ_WS_URL=ws://127.0.0.1:3001/onebot/v11/ws
QQ_REVERSE_MODE=true
QQ_REVERSE_HOST=127.0.0.1
QQ_REVERSE_PORT=6700
QQ_ACCESS_TOKEN=<your-access-token>
QQ_BOT_SELF_ID=123456789
QQ_HTTP_API_URL=http://127.0.0.1:5700
QQ_ONEBOT_ALLOWED_USERS=123456789,987654321
QQ_ONEBOT_ALLOW_ALL_USERS=false
QQ_MENTION_PATTERNS=芙芙,帮我
QQ_ONEBOT_HOME_CHANNEL=qq_group_123456789
QQ_SHOW_QQ_ID=false不要将真实 token 或其他凭据提交到仓库、README 或日志中。
默认端口关系：
OneBot HTTP API 127.0.0.1:5700
Hermes reverse WS 127.0.0.1:6700
正向 WebSocket 的端口由 ws_host、ws_port、ws_path 决定。
无 token 时，反向 WS 只能监听回环地址。需要监听外部地址时，必须配置 access_token，并限制网络访问来源。
- 群聊中
@机器人会触发处理。 - 配置
mention_patterns后，匹配关键词的群聊消息也会触发。 - 私聊不需要
@或关键词。 - QQ 发送纯
@机器人时通常会附带一个默认空格，插件会将其识别为仅艾特。
支持以下目标格式：
qq_group_123456789
group:123456789
qq_123456789
user:123456789
123456789
裸数字默认按群号处理。发送私聊时建议使用 user:<qq_id> 或 qq_<qq_id>。
回复会以普通文本发送，不要依赖 Markdown 渲染。**加粗**、代码围栏和 Markdown 表格不会转换为 QQ 富文本。
send_message(
target="qqonebot:qq_group_123456789",
message="你好"
)
使用 MEDIA: 发送文件：
send_message(
target="qqonebot:qq_group_123456789",
message="说明文字\nMEDIA:/path/to/image.png"
)
常见媒体类型包括图片、音频、视频和普通文件。使用 [[as_document]] 可以强制按文件发送：
[[as_document]]MEDIA:/path/to/data.json
媒体文件仍需通过 Hermes 的媒体路径安全检查，不要发送不受信任的任意系统路径。
支持普通文本、回复、@、图片、语音、视频、文件、JSON/XML/Markdown 卡片、音乐、联系人、表情、戳一戳、骰子、猜拳和合并转发。
卡片消息会提取标题、描述、来源、链接和正文等有限字段。
普通合并转发和嵌套合并转发会展开为可读摘要，默认限制：
- 最大嵌套深度：3
get_forward_msg调用：12 次- 转发节点：60 个
- 消息段：200 个
- 摘要总字符：12,000
超出限制时保留已处理内容并截断。
- 普通入站图片会交给 Hermes 媒体处理链路，模型可以查看。
- 转发里的图片、语音、视频和文件目前只显示占位或文件名，不会自动下载。
- 转发里的 JSON/XML/Markdown/音乐卡片会保留文字摘要。
- QQ 表情夹在文字中间时，当前不做完整的消息段重组。
- OneBot action 的 JSON 响应体上限：2 MiB。
- 图片下载上限：10 MiB。
- 音频、视频和普通文件下载上限：50 MiB。
- 默认拒绝
file://、回环、链路本地和私网媒体 URL。 - HTTP 重定向目标同样会检查。
allow_private_media_urls和allow_local_media_paths默认关闭。
2 MiB 只限制 OneBot action 的 JSON 响应，不限制图片、语音、视频和文件正文下载。
查看插件状态：
hermes plugins list | grep -i qqonebot查看 Gateway 日志：
grep -Ei 'qqonebot|Reverse WS|OneBot|websocket' ~/.hermes/logs/gateway.log | tail -50反向 WS 正常时，Gateway 日志应出现：
Reverse WS client connected
HTTP API 的 get_login_info 成功只能证明 OneBot HTTP 服务正常，不代表反向 WS 已连接。
修改配置或代码后需要重启 Gateway。
hermes plugins disable qqonebot
hermes plugins remove qqonebot