Hermes OneBot Adapter

OneBot 11 适配器服务 + Hermes 插件，经独立服务对接 NapCat / go-cqhttp 等 OneBot 11 实现（目前仅在 NapCat 下测试过）。

架构

OneBot ──WS──  适配器服务  ──WS── Hermes 插件 ── Hermes Agent

适配器服务承担全部 OneBot 交互；插件只与适配器服务通信，不直接接触 OneBot；不修改 Hermes 本身的代码。

环境要求

• Python >= 3.11
• pipx（推荐）或 pip

快速开始

pipx install hermes-onebot-adapter    # 从 PyPI 安装
hermes-onebot-adapter                 # 启动服务，WebUI 默认 http://localhost:18820

从源码安装需先编译前端：

./scripts/build_frontend.sh           # 编译前端 (需要 Node.js)
pipx install .                        # 安装
hermes-onebot-adapter                 # 启动服务

首次启动会自动生成 ~/.onebot_adapter/config.json（含随机 token）。也可先手动生成：

hermes-onebot-adapter --init-config   # 生成默认配置后退出

配置流程

1. 启动适配器服务 — hermes-onebot-adapter
2. 打开 WebUI — 浏览器访问 http://localhost:18820，登录后进入管理界面
3. 配置 OneBot 连接 — 在 WebUI 的"连接管理"页选择连接模式（反向 WS / 正向 WS），填写 WS 地址和 token
4. 安装 Hermes 插件 — 在 WebUI 的"连接管理"页填写 Hermes 安装目录（默认 ~/.hermes），点击"安装插件到 Hermes"
5. 启用插件 — hermes plugins enable onebot-platform
6. 重启 Hermes 网关 — hermes gateway restart

安装插件时，Installer 自动完成三件事：

以上均需启用插件并重启 Hermes 网关后生效。

也可通过 CLI 安装：

hermes-onebot-adapter install --hermes-dir ~/.hermes

CLI 用法

# 启动服务
hermes-onebot-adapter                         # 默认 127.0.0.1
hermes-onebot-adapter --host 0.0.0.0          # 监听所有网络接口
hermes-onebot-adapter --port 18820            # 指定 WebUI 端口
hermes-onebot-adapter --no-webui              # 不启动 WebUI (仅 WS 服务)

# 配置管理
hermes-onebot-adapter --init-config           # 生成默认配置文件后退出
hermes-onebot-adapter --init-config --force   # 覆盖已有配置 (保留 token，其余重置为默认)
hermes-onebot-adapter --generate-api-key --enable-api  # 生成自动化 API key 并启用
hermes-onebot-adapter --rotate-api-key         # 轮换 key（仅显示一次）
hermes-onebot-adapter --revoke-api-key         # 撤销 key 并关闭自动化 API
hermes-onebot-adapter --enable-api             # 启用已有 key
hermes-onebot-adapter --disable-api            # 关闭自动化 API

# 插件安装 (默认从 config.json 读取 URL 和 token)
hermes-onebot-adapter install                          # 安装到 ~/.hermes
hermes-onebot-adapter install --hermes-dir /opt/hermes # 指定安装目录
hermes-onebot-adapter install --adapter-url ws://host:18810/hermes --adapter-token xxx  # 手动指定连接参数
hermes-onebot-adapter uninstall                        # 卸载
hermes-onebot-adapter uninstall --hermes-dir /opt/hermes

自动化工具 API

自动化 API 默认关闭。它使用独立于 WebUI 登录的全权限 key，可调用 Hermes 插件提供的全部 OneBot 工具以及文件上传工具：

# key 只显示一次；请保存到调用脚本的安全环境变量中
hermes-onebot-adapter --generate-api-key --enable-api

curl -H "Authorization: Bearer hoa_xxx" \
  http://127.0.0.1:18820/api/v1/tools

每个工具使用独立的 RPC 路径 POST /api/v1/tools/<tool_name>。完整参数可从 GET /api/v1/tools 或 /api/v1/openapi.json 获取。HTTP 调用不会继承 Hermes 的当前聊天上下文，发送消息或上传文件时必须显式提供与 message_type 匹配的 group_id 或 user_id。Key 可执行踢人、禁言、退群、删好友等高风险操作，不要放入 URL、日志或前端代码。

本地文件默认只允许来自 /tmp/hermes-onebot-adapter-uploads；可在 WebUI 高级设置中调整 automation_upload_allowed_roots。qBittorrent hook 需要在其进程环境中设置：

ONEBOT_AUTOMATION_API_KEY=hoa_xxx

三端口

环境变量

适配器服务

自动化客户端

Hermes 插件

OneBot 连接模式

反向 WS（推荐）

OneBot 主动连接适配器服务。在 OneBot WebUI 中配置反向 WS 地址：

ws://127.0.0.1:18800/onebot

正向 WS

适配器主动连接 OneBot。在适配器 WebUI 中配置 OneBot 的正向 WS 地址：

ws://127.0.0.1:3001

模式切换可在 WebUI 中热重载，无需重启服务。

WebUI 功能

工具集管理

安装插件时会自动写入默认工具集配置到 <hermes>/config.yaml。之后可通过 WebUI 的"工具管理"页面自主启停工具集。

工具集修改后写入 Hermes 的 config.yaml，需重启 Hermes 网关生效。适配器只负责写配置文件，不触发热重载。

OneBot API 工具

插件自带 41 个 OneBot 工具（toolset: onebot），LLM 可直接调用：

• 只读：获取群列表/成员/信息、好友列表、消息历史、合并转发内容
• 消息：发送消息、撤回、合并转发、戳一戳、表情回应
• 文件：获取文件、上传群文件或私聊文件、设置头像
• 管理（需适配器管理员权限）：踢人、禁言、全员禁言、设置管理员/名片/群名、退群、处理加群/好友请求
• 动态黑名单：查看或临时拉黑群聊、私聊或全部会话中的用户；管理员始终豁免

使用统计

适配器记录通过准入与指令过滤的消息元数据（QQ 号、群号、时间、是否系统事件，不含消息正文或媒体地址）到 ~/.onebot_adapter/usage_stats.sqlite3，默认保留 365 天。WebUI 仪表盘展示趋势、活跃群、活跃用户图表，可按时间、范围（全部/私聊/群聊）、群、用户过滤。

数据也可通过 REST API 查询/清空（见 API 文档）。

入站消息限流

适配器在准入控制和指令过滤通过后、转发 Hermes 之前对消息限流。全局、群聊、个人三个维度同时检查，命中任一维度即回复原消息并拦截。全局管理员和对应群管理员不受限流；个人计数在私聊和所有群之间共享。限额 0 表示禁用该维度。

算法支持滑动窗口（sliding_window，窗口内消息数上限）和令牌桶（token_bucket，按速率补充令牌）。拦截提示模板 rate_limit_reject_message 支持 {scope}/{retry_after}/{user_id} 占位符。配置在 WebUI「聊天配置」页。

配置备份与审计

每次保存配置时自动备份现有文件为 config.json.bak.<时间戳>，保留最近 5 个。同时追加一条 JSON 审计记录到 ~/.onebot_adapter/logs/config-audit.log（按日轮转，保留 365 天），记录改动字段、来源、操作者、客户端 IP 及新旧配置指纹。检测到疑似重置（≥5 字段回退默认值或群配置清空）时额外输出告警日志。

配置文件损坏或字段非法时，适配器启动 fail-fast（ConfigLoadError），不再回退默认配置并覆盖原文件——需修正配置或从 .bak 备份恢复后才能启动。

准入控制

适配器服务对群与私聊分别提供准入控制，均在 WebUI 配置。适配器在消息转发到 Hermes 之前完成所有过滤/鉴权，Hermes 网关侧无需重复配置准入名单。

群聊：每群通过「启用 Bot」开关控制是否处理该群；群内成员通过群配置的「群成员过滤模式 + 名单」控制（默认黑名单空 = 允许所有群成员）。不再使用全局群白/黑名单。

私聊：通过全局「私聊过滤模式 + 名单」控制（默认白名单空 = 拒绝所有私聊，需显式加入白名单才放行）。

管理工具（踢人/禁言等）的鉴权由适配器的 global_admins / 群配置 admins 决定，非管理员调用时适配器直接拒绝。

Bot 动态黑名单独立保存到 ~/.onebot_adapter/bot_blacklist.sqlite3，不与上述准入名单混用。Bot 通过 onebot_get_bot_blacklist / onebot_edit_bot_blacklist 工具临时拉黑用户（全局管理员和对应群管理员始终豁免），WebUI「聊天配置」页可设置 bot_blacklist_enabled/bot_blacklist_max_duration_seconds/bot_blacklist_reject_message，也可查看及人工解除有效记录。群聊仅在消息本应触发 bot 时检查并回复提示；私聊记录、群记录和全局记录按各自作用域生效。

/指令过滤

适配器启动后，Hermes 插件会将 Hermes 已注册的所有 / 指令（内置 + 插件注册）推送给适配器服务。适配器在消息进入 Hermes 之前，根据指令权限配置进行过滤。

匹配方式：去除消息中所有 @bot 段后，从开头匹配 /xxx（小写化、支持别名解析、兼容 Telegram 风格 /cmd@BotName）。

权限级别（每指令可配置）：

配置项（WebUI「指令过滤」页面）：

每群覆盖：群配置中可覆盖 command_filter_enabled、command_filter_unknown、command_permissions，与现有群配置模式一致（None=跟随全局）。

被过滤的指令会通过当前 OneBot WebSocket 上的 API 调用向原聊天发送拒绝消息，不会送入 Hermes 处理。指令过滤在媒体下载之前执行，避免浪费带宽。

群聊消息排队

适配器内置 shared 群聊消息排队机制，防止群聊中多个群成员的消息互相打断 agent 当前任务。只在 Hermes 配置 group_sessions_per_user: false（全群共享 session）且适配器 event_queue_enabled: true 时生效；per_user 模式每人独立 session，无需排队。

排队规则

Hermes 会话隔离配置

group_sessions_per_user 是 Hermes 顶层的唯一真相源。适配器 WebUI（连接管理页）可直接修改 Hermes config.yaml 的此字段，修改后需重启 Hermes 网关生效。插件连接后会上报当前值给适配器，适配器据此决定是否排队。

idle 信号

处理完成的"idle"信号由 Hermes 插件通过 register_post_delivery_callback 钩子发送：每轮 agent 处理结束后插件向适配器发 idle 帧，适配器清空 busy 并从队列取下一条转发。若插件崩溃或 idle 帧丢失，看门狗会在超时后强制清空 busy。

/stop、/new、/reset 命令会导致 Hermes 中断当前 turn 但不触发 idle 帧，适配器会在 broadcast 这些命令 3 秒后主动清空 busy 槽防止队列卡死。

配置项（WebUI「连接管理」页面）

开发

pip install -e ".[dev]"          # 开发安装（可编辑模式 + dev 依赖）
pytest -q                        # 运行测试
ruff check .                     # 代码检查
cd frontend && npm install && npm run dev   # 前端开发 (Vite 代理到 :18820)
./scripts/build_frontend.sh      # 构建前端到 webui/static/

配置文件

适配器服务配置持久化于 ~/.onebot_adapter/config.json（或 ONEBOT_ADAPTER_CONFIG 指定路径），WebUI 修改即保存。

技术栈

• 后端：aiohttp（WS 服务端/客户端、HTTP API、静态托管）
• 前端：Vue 3 + Vite + TypeScript + Vue Router
• 打包：pyproject.toml + setuptools，hermes-onebot-adapter CLI entry point

License

MIT