Configuration Reference#

English ｜ 中文

All ILBB configuration is driven by environment variables, layered by precedence from three sources:

System environment variables   >   .env file   >   built-in code defaults

That is to say: deleting a line = using the default value, and you do not need to write them all out. Restart the service for changes to take effect.

.env is ignored by .gitignore, so do not commit a .env containing secrets. The project ships with .env.example as a template:

# Windows
Copy-Item .env.example .env

# Linux / macOS
cp .env.example .env

After the first startup you can also change configuration on the setup page /setup and the settings page, which writes back to .env automatically.

1. WebUI / Flask#

This password is only temporary: once you set your own in step 4 of the setup wizard (or via "Settings → Change admin password"), it stops working and the terminal no longer prints it. Until then every startup prints it again, so missing it once costs nothing.

2. WS server (OneBot V11 / NapCat)#

WS_CONFIG_PRIORITY is a common trap:

• file (default) —— the ws_config.json saved from the WebUI panel overrides the values in .env, and the panel can modify and save.
• env —— forces .env to have the final say, ignores ws_config.json, and clicking "Save config" in the panel is rejected.

If you change configuration in the panel but it does not take effect, check this item first.

Be sure to get the direction right: ILBB is the server (listening on 6700) and NapCat connects to it as the client. See Message Platform Integration for details.

3. Bot commands#

The prefix takes at most 3 characters (truncated in code). After changing it to #, commands become #help, #meme 摸.

4. Quote image (/quote)#

5. Plugin system#

See the Plugin Development Guide for details.

6. Directories and data files#

Relative paths are resolved against the project root directory, and absolute paths (such as E:/data/cache) also work. Therefore you must start from the project root directory.

7. Cache and canvas#

8. Background image API#

This is a third-party API and its availability is not guaranteed. When no image can be fetched the background falls back to a solid color, which does not affect other features.

9. First-run setup page#

On the first startup, visiting http://127.0.0.1:5000/setup takes you to the setup page, which does four things:

While the wizard is unfinished, visiting / brings you back to it (landing directly on step 4 when no password has been set yet).

Why the assets must be downloaded: to keep the repository size down to a few tens of MB, the image assets under vendor/meme-generator-main/meme_generator/memes/ (about 2,869 files, roughly 254MB) are not committed and are completed over the network by this step. ILBB can start without downloading them, but meme generation will fail on a large scale.

Assets are assembled from two halves: the images are what this step downloads, while each meme's definition code memes/<key>/__init__.py ships with the repository (about 282 files, just over 400 KB in total — see the vendor layering in .gitignore). The upstream resource list holds only png/jpg/gif, so a download cannot restore a missing definition: the meme list would end up completely empty, and both the setup page and the status panel say as much.

10. Configuration precedence in practice#

Scenario 1: you want to change WS settings in the panel

Keep WS_CONFIG_PRIORITY=file and change them directly in the WebUI panel; after saving, they are written to ws_config.json and take effect immediately.

Scenario 2: you want .env to have the final say (e.g. Docker deployment)

Set WS_CONFIG_PRIORITY=env, then fix all WS parameters in the Docker environment variables or in .env.

Scenario 3: you forgot the admin password

The password hash is stored in api_keys.json. Every startup prints the password currently in effect; delete admin_hash and restart to have a fresh temporary password generated and printed, and / will take you back to the setup wizard to set a new one.

Scenario 4: you changed .env but it does not take effect

Troubleshoot in order: ① is it written as KEY = value (no spaces allowed); ② is a system environment variable with the same name overriding it; ③ did you restart the service; ④ for WS-related items, check WS_CONFIG_PRIORITY.

Back to docs home ｜ 中文