Skip to main content

​
Overview

The OneBot configuration file (onebot.json) manages OneBot 11 protocol settings, including network adapters, message formatting, and additional features like music signing and file URL conversion.

​
Configuration File Location

config/onebot.json

​
Configuration Schema

​
Network Configuration

​
network
object
required
Network adapter configuration. Contains arrays of different adapter types (HTTP servers, WebSocket servers, clients, etc.).See the Network Adapters page for detailed configuration of each adapter type.

​
Message Format Settings

​
network.*.messagePostFormat
string
default:"array"
Format for posting messages. Available in each network adapter configuration.
  • array: Message segments as an array of objects (CQ code format)
  • string: Message as a plain string
​
network.*.reportSelfMessage
boolean
default:false
Whether to report messages sent by the bot itself. Available in most network adapters.

​
Music Signing

​
musicSignUrl
string
default:""
URL for music card signing service. Required for sending music cards (QQ music, NetEase music, etc.).Example: https://your-signing-service.com/sign

​
File and Media Options

​
enableLocalFile2Url
boolean
default:false
Convert local file paths to URLs automatically. Useful when your bot needs to serve files over HTTP.
​
imageDownloadProxy
string
default:""
HTTP proxy for downloading images. Format: http://proxy-host:portUseful in restricted network environments or to avoid rate limiting.

​
Message Parsing

​
parseMultMsg
boolean
default:false
Parse forwarded/merged messages (multi-message nodes) into individual messages.When enabled, composite messages will be expanded into their constituent parts.

​
Configuration Examples

{
  "network": {
    "httpServers": [
      {
        "name": "http-server",
        "enable": true,
        "port": 3000,
        "host": "127.0.0.1",
        "messagePostFormat": "array",
        "token": "your-secret-token"
      }
    ],
    "websocketServers": [],
    "httpClients": [],
    "websocketClients": [],
    "httpSseServers": [],
    "plugins": []
  },
  "musicSignUrl": "",
  "enableLocalFile2Url": false,
  "parseMultMsg": false,
  "imageDownloadProxy": ""
}

​
Network Adapter Types

The network object contains arrays for different adapter types:
  • httpServers: HTTP server adapters (receive requests)
  • httpSseServers: HTTP SSE server adapters (server-sent events)
  • websocketServers: WebSocket server adapters (bidirectional)
  • httpClients: HTTP client adapters (reverse connections, POST events)
  • websocketClients: WebSocket client adapters (reverse connections)
  • plugins: Plugin adapters for custom integrations
Each array can contain multiple adapter configurations. See the Network Adapters page for detailed information on each type.

​
Notes

  • You can enable multiple network adapters simultaneously
  • Each network adapter must have a unique name field
  • Token authentication is optional but strongly recommended for production use
  • The configuration file is validated and merged with default values on startup
  • Message format affects how your application receives and parses messages

Build docs developers (and LLMs) love

Get started for freeTalk to us