配置

Bngeuit 启动时在运行目录自动生成 config.yml。配置文件采用 bot: 顶层块嵌套所有项。

完整配置

yaml

# Bngeuit 机器人配置文件

bot:
  appId: "your-app-id"
  appSecret: "your-secret"

  # 以下为可选配置（均有默认值）
  # timeout: 5          # HTTP 请求超时（秒），默认 5
  # sandbox: false      # 是否沙箱环境，默认 false
  # retCoroutine: false # 协程模式，默认 false

  # 事件接入方式，二选一：
  #   websocket（默认）—— WebSocket 网关长连接，框架主动连接开放平台网关，由网关推送事件
  #   webhook           —— HTTP 回调，框架启动本地回调服务，由开放平台 POST 推送事件
  # 说明：webhook 模式无需公网 IP 出站连接，但回调地址需能被开放平台访问
  #       （官方限定端口 80/443/8080/8443；本地无公网 IP 时建议配合内网穿透/反向代理提供 HTTPS）。
  mode: websocket

  # ─── 线程池 / 队列参数（可选，默认值 = 原有硬编码值，不填即保持原行为）───
  # 说明：线程数上限 32。handler 里有同步 I/O（数据库、HTTP）时才需要调大；
  #       它是"提高消费速度"的补救手段，不能替代"别在事件线程里做阻塞 I/O"。
  eventBus:
    threads: 8               # 事件分发线程数 event-worker，默认 8

  scheduler:
    asyncThreads: 4          # 调度器异步任务线程数 scheduler-async，默认 4（sync 池固定 1，不可配）

  # ─── 仅 mode: webhook 时生效 ───
  webhook:
    host: "0.0.0.0"          # 回调监听地址，默认 0.0.0.0
    port: 8080               # 回调监听端口，默认 8080
    path: "/"                # 回调路径，默认 /（在开放平台填写的回调地址 = https://你的域名:端口 + 此路径）
    verifySignature: true    # 校验事件请求签名（X-Signature-Ed25519），默认 true；仅调试时可关
    backlog: 128             # 监听套接字 TCP accept 队列长度，默认 128（突发并发连接多时可调大）
    callbackThreads: 4       # 回调处理线程数 webhook-callback，默认 4

配置项说明

字段	必填	类型	默认值	说明
`bot.appId`	✅	`string`	—	QQ 机器人 BotAppID
`bot.appSecret`	✅	`string`	—	QQ 机器人 BotAppSecret
`bot.timeout`	❌	`int`	`5`	HTTP 请求超时时间（秒）
`bot.sandbox`	❌	`boolean`	`false`	是否使用沙箱环境 API
`bot.retCoroutine`	❌	`boolean`	`false`	协程模式（当前未使用）
`bot.mode`	❌	`string`	`websocket`	事件接入方式：`websocket`（网关长连接，默认）或 `webhook`（HTTP 回调）
`bot.eventBus.threads`	❌	`int`	`8`	事件分发线程数（1-32）
`bot.scheduler.asyncThreads`	❌	`int`	`4`	调度器异步任务线程数（1-32）
`bot.webhook.host`	❌	`string`	`0.0.0.0`	回调监听地址（仅 webhook 模式）
`bot.webhook.port`	❌	`int`	`8080`	回调监听端口（官方限定 80/443/8080/8443）
`bot.webhook.path`	❌	`string`	`/`	回调路径（必须以 `/` 开头，与开放平台回调地址一致）
`bot.webhook.verifySignature`	❌	`boolean`	`true`	校验事件请求签名（生产必须开启）
`bot.webhook.backlog`	❌	`int`	`128`	监听套接字 TCP accept 队列长度（1-4096）
`bot.webhook.callbackThreads`	❌	`int`	`4`	回调处理线程数（1-32）

数值校验

bot.eventBus.threads 与 bot.scheduler.asyncThreads 超出 1-32 时，无论接入方式都会在启动阶段直接抛 IllegalArgumentException。bot.webhook.* 下的 port（1-65535）、path（以 / 开头）、backlog（1-4096）、callbackThreads（1-32）只在 bot.mode: webhook 时校验，websocket 模式下这些配置不生效也不校验。抛错信息会写明配置项路径，不会静默回退默认值。

接入方式二选一

bot.mode 决定机器人如何接收事件：WebSocket 网关长连接（默认，自动重连）或 Webhook HTTP 回调（零出站连接，需公网 HTTPS 回调地址）。两者分发到插件的路径完全一致，插件无需感知差异。详见 Webhook 模式。

事件意图不在 config.yml 配置

事件意图（Intents）由框架固定使用默认值（群 + C2C + 互动全部事件），config.yml 不开放该配置项。详见 Intents 意图。

沙箱环境

沙箱环境使用独立的 API 地址 https://sandbox.api.sgroup.qq.com/，用于开发测试：

yaml

bot:
  appId: "你的BotAppID"
  appSecret: "你的BotAppSecret"
  sandbox: true

正式上线时设为 false 或不填。

配置 ​

完整配置 ​

配置项说明 ​

沙箱环境 ​

配置

完整配置

配置项说明

沙箱环境