Euler OneBot

一个无聊的 OneBot 实现，完全使用 python 语言，基于 lagrange-python

项目特点

本项目基本目的在于为曾经使用 Lagrange.OneBot 、在 Lagrange.OneBot 停止维护后暂时不愿迁移到 milky 或期望基于协议库而非 hook 方案的 OneBot 实现的用户。

环境要求

若您使用：

Apple M 系列或 A 系列芯片的 macOS 设备
几乎任何 Windows x64/arm64 设备
几乎任何非 musl 的 x64/arm64 Linux 发行版

则您可以跳过环境配置，前往 actions 下载打包的可执行文件。

Python >= 3.11
lagrange-python ¹²
兼容 Lagrange V2 的签名服务（见签名服务）

安装与使用

方式一：使用预编译可执行文件（推荐）

前往 Actions 下载与您设备架构对应的产物（ -linux-x64 / -linux-arm64 / -macos-arm64 / -windows-x64 / -windows-arm64）并解压，随后运行：

./euler-onebot-<版本号>       # Linux / macOS（macOS 提供普通命令行程序）
euler-onebot-<版本号>.exe     # Windows

首次启动会在可执行文件旁自动生成 appconfig.json 配置模板并显示提示，填写后重启即可。源码运行时配置仍在当前目录生成。

方式二：从源码运行

克隆本项目：

git clone https://github.com/HarcicYang/EulerOneBot.git
cd EulerOneBot

安装依赖并运行（首次启动会自动生成 appconfig.json）：
```
uv sync
uv run main.py
```
若您不希望使用 uv：
```
pip install .
python main.py
```

配置文件

首次运行会自动生成 appconfig.json，编辑后重启。配置项如下：

{
  "$schema": "./appconfig.schema.json",
  "log_level": "INFO",
  "log_nf": true,
  "access_token": "",
  "connections": [
    {
      "type": "ForwardWebSocket",
      "url": "ws://127.0.0.1:5004"
    }
  ],
  "login": {
    "uin": 0,
    "signer_url": "https://sign.lagrangecore.org",
    "signer_token": "",
    "use_custom": false,
    "appinfo_path": "./appinfo.json",
    "setup_watchdog": false,
    "use_ipv6": false,
    "use_optimum": true
  },
  "heartbeat": {
    "enabled": true,
    "interval": 15000
  }
}

仓库附有 appconfig.schema.json（由 BotConfig 模型自动生成，可通过 python scripts/gen_schema.py 重新生成）。保留配置开头的 $schema 字段后，VS Code / IDEA 等编辑器即可获得自动补全与校验。若模型有改动，CI 会校验 schema 文件与模型保持同步。

字段	说明
`log_level`	日志级别：`TRACE` / `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`
`log_nf`	是否为日志输出启用 NerdFont
`access_token`	鉴权 Token，配置后 HTTP / 正向 WebSocket / 反向 WebSocket 需携带（空为不鉴权）
`connections`	通信连接列表（见下方连接类型）
`login.uin`	QQ 账号（不要真的写0哦）
`login.signer_url`	签名服务地址（见签名服务）
`login.signer_token`	签名服务 access token
`login.use_custom`	是否加载自定义协议参数；设为 `true` 后读取 `appinfo_path` 指定的 JSON 文件
`login.appinfo_path`	自定义协议参数文件路径，默认 `./appinfo.json`，相对当前工作目录
`login.setup_watchdog`	是否启用看门狗；连续 10 分钟没有处理事件时触发重新登录
`login.use_ipv6`	是否使用 IPv6 连接
`login.use_optimum`	是否启用最优服务器选择
`heartbeat.enabled`	是否启用心跳
`heartbeat.interval`	心跳间隔（毫秒）

签名服务

登录 QQ 时需要签名服务为关键数据包签名。除上面的示例所用的公开签名服务 https://sign.lagrangecore.org，本项目也提供自建的 Harcic 签名 API，可按下面的步骤获取 access token 后使用：

打开管理页并用 GitHub 账号登录，然后设置 Owner QQ（仅用于标识账户，不占用 token 的绑定名额）；
创建 access token。每个 GitHub 账号同时只能有一个有效 token，每个 token 最多绑定 3 个 QQ，且 token 仅显示一次，请立即复制保存；
在管理页的「客户端配置示例」切到 EulerOneBot 标签复制配置，或按下面的形式手动填写：

{
  "login": {
    "uin": 1234567890,
    "signer_url": "https://api.harcic.me",
    "signer_token": "YOUR_ACCESS_TOKEN"
  }
}

signer_url 只填服务地址即可，Euler OneBot 会自行追加 /api/sign/sec-sign，并以 Authorization: Bearer <signer_token> 的方式携带 token，因此不要照搬 Lagrange.Milky 示例中带有 /api/ 后缀的 BaseUrl。启动时使用的 QQ 必须已绑定到该 token，否则签名接口会返回 Invalid access token。

若需要接入其它签名服务，把 signer_url 与 signer_token 换成对应服务提供的信息即可。

自定义 appinfo.json

appinfo.json 是可选文件。不使用自定义协议时，无需创建它，保持 login.use_custom 为 false 即可继续使用内置 Linux 参数。

如需使用自定义协议，请将下面的示例保存为本地 appinfo.json（或替换为目标客户端对应的参数），再在 appconfig.json 的 login 中启用自定义协议并填写该文件路径：

注意，自定义协议版本可能与前文提到的签名服务不兼容。遇到这种情况时，需要自行准备兼容的签名服务，并在 login.signer_url 和 login.signer_token 中填写对应配置。

{
  "use_custom": true,
  "appinfo_path": "./appinfo.json"
}

appinfo.json 需要包含 Lagrange AppInfo 使用的字段。下面以项目当前内置的 Linux 协议参数展示完整格式；若要模拟其他客户端，请替换为与目标客户端版本匹配的参数：

{
  "Os": "Linux",
  "Kernel": "Linux",
  "VendorOs": "linux",
  "CurrentVersion": "3.2.26-46494",
  "MiscBitmap": 32764,
  "PtVersion": "2.0.0",
  "SsoVersion": 19,
  "PackageName": "com.tencent.qq",
  "WtLoginSdk": "nt.wtlogin.0.0.1",
  "AppId": 1600001615,
  "SubAppId": 537345891,
  "AppIdQrCode": 13697054,
  "AppClientVersion": 46494,
  "MainSigMap": 169742560,
  "SubSigMap": 0,
  "NtLoginType": 1,
  "Qua": "V1_LNX_NQ_3.2.26_46494_GW_B"
}

已经支持的连接类型

连接类型	`type` 值	说明
HTTP	`HTTP`	在 `url` 指定的地址提供 HTTP API 服务（`GET`/`POST /:action`）
HTTP POST	`HTTPPost`	将事件上报到 `url` 指定的 Webhook，可配置 `secret` 签名与 `timeout`
正向 WebSocket	`ForwardWebSocket`	在 `url` 指定的地址监听,提供 WebSocket 服务供 OneBot 客户端连接
反向 WebSocket	`ReverseWebSocket`	主动连接 `url` 指定的服务端，可配置 `api_url`、`event_url`、`use_universal_client`、`reconnect_interval`

每类连接可能有额外的配置字段（如 ReverseWebSocket 的 api_url、event_url 等），详见 ForwardWebsocketConfig、 ReverseWebsocketConfig 等 Pydantic 模型定义。

开发

Euler OneBot 使用 uv 进行依赖与项目管理：

uv sync

支持情况

API 类型

API 名称	支持状态	类型
send_private_msg	✅	标准
send_group_msg	✅	标准
send_msg	✅	标准
delete_msg	✅	标准
get_msg	✅	标准
get_forward_msg	✅	标准
send_like	✅	标准
set_group_kick	✅	标准
set_group_ban	✅	标准
set_group_whole_ban	✅	标准
set_group_admin	✅	标准
set_group_card	✅	标准
set_group_name	✅	标准
set_group_leave	✅	标准
set_group_special_title	✅	标准
set_friend_add_request	✅	标准
set_group_add_request	✅	标准
get_login_info	✅	标准
get_stranger_info	✅	标准
get_friend_list	✅	标准
get_group_info	✅	标准
get_group_list	✅	标准
get_group_member_info	✅	标准
get_group_member_list	✅	标准
get_cookies	✅	标准
get_csrf_token	✅	标准
get_status	✅	标准
get_version_info	✅	标准
send_poke	✅	扩展
group_reaction	✅	扩展
upload_group_file	✅	扩展
upload_private_file	✅	扩展
get_group_file_url	✅	扩展
get_private_file_url	✅	扩展

事件类型

事件名称	支持状态	类型
message.private	✅	标准
message.group	✅	标准
notice.group_upload	✅	标准
notice.group_admin	✅	标准
notice.group_decrease	✅	标准
notice.group_increase	✅	标准
notice.group_ban	✅	标准
notice.friend_add	✅	标准
notice.group_recall	✅	标准
notice.friend_recall	✅	标准
notice.notify.poke	✅	标准
notice.notify.lucky_king	Never	标准
notice.notify.honor	Never	标准
request.friend	✅	标准
request.group	✅	标准
meta_event.lifecycle	✅	标准
meta_event.heartbeat	✅	标准
notice.friend_upload	✅	扩展
notice.reaction	✅	扩展

消息段类型

消息段类型	支持状态	类型
text	✅	标准
at	✅	标准
reply	✅	标准
face	✅	标准
poke	✅ API	标准
node	✅	标准
forward	✅	标准
image	✅	标准
record	✅	标准
video	✅	标准
file	✅ Recv only	扩展
contact	❌	标准
location	❌	标准
music	❌	标准
rps	❌	标准
dice	❌	标准
shake	❌	标准
json	✅	标准
xml	❌	标准
mface	✅	扩展

通信方式

通信方式	支持状态	类型
HTTP	✅	标准
HTTP POST	✅	标准
正向 WebSocket	✅	标准
反向 WebSocket	✅	标准

性能基准

在 i5-1135G7 / 16GB 上使用 uv run python scripts/benchmark.py 测得：

场景	吞吐
HTTP 端到端（send_group_msg）	~600 req/s
正向 WS 请求-响应（单连接）	~3,700 req/s
WS 事件推送	~60,000 条/s
队列分发（含 SQLite 入库）	~6,400 req/s

内存占用：峰值约 80 MB (benchmark 数据), 静默状态～= 60 MB (观察数据)

尽管这里的连接指向 LagrangeDev ，本仓库的依赖项中该包裹指向我自己的fork ，这是因为我为了该项目，在fork中照葫芦画瓢做了一些自己的实现。因此，如果您安装了 LagrangeDev 提供的包裹，该项目可能无法正常运行。

↩
部分环境下，安装有关依赖库可能需要额外配置 openssl 和 rust 开发环境. ↩

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
patches/lagrange/utils/crypto		patches/lagrange/utils/crypto
scripts		scripts
src/euleronebot		src/euleronebot
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
appconfig.schema.json		appconfig.schema.json
main.py		main.py
pyproject.toml		pyproject.toml
readme.md		readme.md
uv.lock		uv.lock

Navigation Menu

Repository files navigation

Euler OneBot

项目特点

环境要求

安装与使用

方式一：使用预编译可执行文件（推荐）

方式二：从源码运行

配置文件

签名服务

自定义 appinfo.json

已经支持的连接类型

开发

支持情况

性能基准

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Euler OneBot

项目特点

环境要求

安装与使用

方式一：使用预编译可执行文件（推荐）

方式二：从源码运行

配置文件

签名服务

自定义 appinfo.json

已经支持的连接类型

开发

支持情况

性能基准

Footnotes

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages