配置

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

完整配置

# 必填：从 QQ 开放平台获取
bot:
  appId: "你的BotAppID"
  appSecret: "你的BotAppSecret"

  # 可选：HTTP 请求超时（秒），默认 5
  # timeout: 5

  # 可选：是否使用沙箱环境 API（默认 false）
  # sandbox: false

  # 可选：协程模式（默认 false，当前未使用）
  # retCoroutine: false

  # 可选：事件接入方式二选一（默认 websocket）
  # mode: websocket            # websocket（网关长连接，默认）| webhook（HTTP 回调）

  # webhook 模式配置（仅 mode: webhook 时生效）
  # webhook:
  #   host: "0.0.0.0"          # 回调监听地址
  #   port: 8080               # 回调监听端口（官方限定 80/443/8080/8443）
  #   path: "/"                # 回调路径（必须以 / 开头）
  #   verifySignature: true    # 校验事件请求签名（默认 true，生产必须开启）

配置项说明

字段	必填	类型	默认值	说明
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.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.mode 决定机器人如何接收事件：WebSocket 网关长连接（默认，自动重连）或 Webhook HTTP 回调（零出站连接，需公网 HTTPS 回调地址）。两者分发到插件的路径完全一致，插件无需感知差异。详见 Webhook 模式。

事件意图不在 config.yml 配置

事件意图（Intents）默认订阅群+C2C+互动全部事件，config.yml 暂未开放该配置项。如需精确控制，请通过代码方式使用 BotConfig.builder().intents(...) 创建配置（见 Intents 意图）。

沙箱环境

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

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

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