Configuration
OneBot instance config and runtime config file reference
SnowLuma stores configuration in two JSON files:
config/onebot.json+config/onebot_<uin>.json— OneBot network adapters (HTTP/WebSocket listeners, reverse WS, HTTP event reporting).config/runtime.json— process-level settings (WebUI port, auto-injection toggle).
Both files are auto-generated on first run and normalized on every load.
OneBot config
File locations
config/onebot.json # global defaults
config/onebot_<uin>.json # per-account overrides- Global:
config/onebot.json— the default for every account. - Per-account:
config/onebot_<uin>.json— overrides the global file. - Auto-generated: missing per-account config or access tokens are written automatically in normalized form on first run.
Default config
Adapters are grouped by kind under a single networks object:
{
"networks": {
"httpServers": [
{
"name": "http-default",
"enabled": true,
"host": "0.0.0.0",
"port": 3000,
"path": "/",
"accessToken": "auto-generated",
"messageFormat": "array",
"reportSelfMessage": false
}
],
"httpClients": [],
"wsServers": [
{
"name": "ws-default",
"enabled": true,
"host": "0.0.0.0",
"port": 3001,
"path": "/",
"role": "Universal",
"accessToken": "auto-generated",
"messageFormat": "array",
"reportSelfMessage": false
}
],
"wsClients": []
},
"musicSignUrl": ""
}Info
Migrating from the old format: earlier versions kept httpServers / wsServers arrays at the top level and used httpPostEndpoints for reporting. SnowLuma detects this layout, moves the entries into the networks object, renames httpPostEndpoints to httpClients, and writes the result back to disk. If you maintain configs by hand, use the new shape.
Shared fields
Every adapter accepts these (NetworkBase):
| Field | Type | Default | Notes |
|---|---|---|---|
name | string | required | Identifier unique within its kind array; hot-reload addresses it by (kind, name). |
enabled | bool | true | Set false to keep the configuration but skip starting this adapter. |
accessToken | string | auto | OneBot bearer / ?access_token=. |
messageFormat | string | array | array or string — controls whether the event message field is a segment array or a flattened string. |
reportSelfMessage | bool | false | When true, this adapter sees post_type='message_sent' events. |
httpServers
OneBot HTTP API listener.
| Field | Type | Default | Notes |
|---|---|---|---|
host | string | 0.0.0.0 | Bind address. |
port | number | 3000 | Listen port. |
path | string | / | API path prefix. |
httpClients
Push events to external endpoints (formerly httpPostEndpoints).
| Field | Type | Default | Notes |
|---|---|---|---|
url | string | required | Report URL. |
timeoutMs | number | 5000 | Request timeout. |
wsServers
OneBot WebSocket server.
| Field | Type | Default | Notes |
|---|---|---|---|
host | string | 0.0.0.0 | Bind address. |
port | number | 3001 | Listen port. |
path | string | / | WebSocket path. |
role | string | Universal | Api, Event, or Universal (TitleCase; older lowercase values are no longer accepted). |
wsClients
Connect outbound to reverse WebSocket servers.
| Field | Type | Default | Notes |
|---|---|---|---|
url | string | required | Reverse WebSocket URL. |
role | string | Universal | Same values as wsServers.role. |
reconnectIntervalMs | number | 5000 | Reconnect interval; clamped to a 1000 minimum. |
musicSignUrl
Optional URL for a custom music-card signing service. Empty string disables.
Runtime config (runtime.json)
config/runtime.json carries process-wide settings — not per-account.
{
"webuiPort": 5099,
"hookAutoLoad": false
}| Field | Type | Default | Notes |
|---|---|---|---|
webuiPort | number | 5099 | WebUI listen port; out-of-range values fall back to the default. |
hookAutoLoad | bool | false | Auto-inject the hook into every newly discovered QQ process. The Docker image flips this on. |
Environment variables
| Var | Notes |
|---|---|
SNOWLUMA_HOOK_AUTOLOAD | 1 / true forces auto-injection on; 0 / false off. Wins over runtime.json, which makes Docker overrides ergonomic. |
SNOWLUMA_LOG_LEVEL | Log level (error / warn / info / debug). |
SNOWLUMA_VERBOSE_WARMUP=1 | Verbose friend / group / member warm-up logs. |
SNOWLUMA_DEV_MODE=1 | Enable dev mode (relaxes WebUI auth for local debugging). |
SNOWLUMA_DEV_WEBUI=1 | Force-start the bundled WebUI under dev mode. |
Port conflicts
If 3000 / 3001 / 5099 are taken, change the matching port / webuiPort and restart. Docker users can also remap host ports via Compose (see Docker deployment).
Was this page helpful?
Last updated on