OneBot V11 协议配置

OneBot V11 协议的完整配置项说明。

配置位置

可以在 general 中设置默认值，也可以在账号级别单独配置：

# 全局默认配置
general:
  onebot.v11:
    use_http: true
    use_ws: false

# 账号级别配置（覆盖 general）
{platform}.{account_id}:
  onebot.v11:
    use_http: true
    use_ws: true

配置项说明

字段名	类型	必填	描述	默认值
use_http	boolean	否	是否启用 HTTP API	true
use_ws	boolean	否	是否启用正向 WebSocket	false
use_ws_reverse	boolean	否	是否启用反向 WebSocket	false
access_token	string	否	API 访问令牌，用于鉴权	-
secret	string	否	上报数据 SHA1 签名密钥	-
post_timeout	number	否	HTTP POST 请求超时时间（毫秒）	5000
post_message_format	string	否	消息上报格式：string(CQ码) 或 array(消息段数组)	string
enable_heartbeat	boolean	否	是否启用心跳	true
heartbeat_interval	number	否	心跳间隔（毫秒）	15000
enable_cors	boolean	否	是否允许跨域	true
ws_reverse_url	string	否	反向 WebSocket 连接地址	-
ws_reverse_api_url	string	否	反向 WebSocket API 连接地址（可选）	-
ws_reverse_event_url	string	否	反向 WebSocket 事件连接地址（可选）	-
ws_reverse_reconnect_interval	number	否	反向 WebSocket 重连间隔（毫秒）	3000
http_reverse	string[]	否	HTTP Webhook 上报地址列表	[]
ws_reverse	string[]	否	反向 WebSocket 连接地址列表	[]

通信方式

HTTP API

启用 HTTP API 后，提供 HTTP POST 接口调用 API。

访问地址: http://localhost:6727/{platform}/{account_id}/onebot/v11/{action}

配置示例:

onebot.v11:
  use_http: true
  access_token: 'your_token'  # 可选，API 鉴权
  post_timeout: 5000          # 请求超时（毫秒）

正向 WebSocket

客户端主动连接到 onebots，实时接收事件。

访问地址: ws://localhost:6727/{platform}/{account_id}/onebot/v11

配置示例:

onebot.v11:
  use_ws: true
  access_token: 'your_token'  # 可选，连接鉴权

反向 WebSocket

onebots 主动连接到指定服务器。

配置示例:

onebot.v11:
  use_ws_reverse: true
  ws_reverse_url: 'ws://localhost:8080/ws'
  access_token: 'your_token'  # 可选，鉴权

完整配置示例

general:
  onebot.v11:
    use_http: true
    use_ws: false
    use_ws_reverse: false
    access_token: 'default_token'
    enable_heartbeat: true
    heartbeat_interval: 15000
    post_message_format: 'array'
    post_timeout: 5000
    enable_cors: true

相关链接

• 协议配置
• 通用配置
• OneBot V11 协议文档