Skip to content
Lingchu Bot

Environment Variables

Lingchu Bot uses NoneBot2’s environment variable system. Copy .env.example to .env and adjust values for your environment.

The project provides a cross-platform setup script (./scripts/setup.sh) that automatically generates .env, .env.development, .env.test, and .env.production from templates. You can also create these files manually.

Server settings

Section titled “Server settings”
Variable Default Description
ENVIRONMENT prod Runtime environment (prod or dev)
HOST 0.0.0.0 FastAPI listen address
PORT 8080 FastAPI listen port
DRIVER ~fastapi+~httpx+~websockets NoneBot driver stack; prefix ~ enables default adapter config

Command settings

Section titled “Command settings”
Variable Default Description
COMMAND_START ["/", ""] Command start prefixes; empty string allows no-prefix commands
COMMAND_SEP [".", " "] Command segment separators

Logging and API docs

Section titled “Logging and API docs”
Variable Default Description
LOG_LEVEL INFO Python logging level
FASTAPI_OPENAPI_URL /openapi.json OpenAPI schema path; set to empty string to disable
FASTAPI_DOCS_URL /docs Swagger UI path; disable in production
FASTAPI_REDOC_URL /redoc ReDoc documentation path; disable in production

Database settings

Section titled “Database settings”
Variable Default Description
ALEMBIC_STARTUP_CHECK false Set to true in production to enforce schema migration checks on startup
SQLALCHEMY_DATABASE_URL (unset) SQLAlchemy database URL for multi-database testing; supports four backends (SQLite / PostgreSQL / MySQL / MariaDB); unset uses default SQLite

Container detection

Section titled “Container detection”
Variable Default Description
LINGCHU_IN_CONTAINERS false Set to true when running inside Docker / Kubernetes. MUST be lowercase true / false — NoneBot2 only accepts JSON-standard booleans here

Superuser settings

Section titled “Superuser settings”
Variable Default Description
LINGCHU_SUPERUSERS (unset) JSON object mapping Lingchu UIDs to platform accounts; see Superuser Identity
LINGCHU_SUPERUSER_KEY 123456789abcdef Lightweight auth key used for root-level operations when no Lingchu superuser is configured. Override in production with a strong random value

See Superuser Identity for detailed configuration.

Adapter and locale

Section titled “Adapter and locale”
Variable Default Description
LINGCHU_ADAPTER (unset) Adapter selection. Use ~ prefix to use NoneBot adapter shorthand (e.g. ~onebot.v11). Accepts a string or a list of strings
LINGCHU_LOCALE en_US Lingchu i18n locale. Supported catalogs: zh_CN, en_US. NoneBot automatically converts this to the lingchu_locale config field

Message store

Section titled “Message store”
Variable Default Description
LINGCHU_MESSAGE_STORE_ENABLED true Enable message storage hooks (group message history, audit, summary)
LINGCHU_MESSAGE_STORE_RETENTION_DAYS 30 Days to retain stored messages. 0 = unlimited. Must be >= 0
LINGCHU_MESSAGE_STORE_SUMMARY_LIMIT 500 Maximum number of messages included in a single summary. Must be >= 0
LINGCHU_MESSAGE_STORE_RECORD_API_CALLS true Whether platform API call summaries are recorded
LINGCHU_MESSAGE_STORE_CLEANUP_ENABLED true Enable automatic cleanup of expired message records

Recall settings

Section titled “Recall settings”
Variable Default Description
LINGCHU_RECALL_MESSAGE_DEFAULT_COUNT 10 Default number of messages to recall when no explicit count is given. Range: 1–100

Permissions

Section titled “Permissions”
Variable Default Description
LINGCHU_PERMISSION_PLATFORM_RUNTIME_PASSTHROUGH true Whether platform permission resolvers pass through to runtime config. true = passthrough; false = strict; or a per-platform mapping (strict JSON)

Trigger overrides

Section titled “Trigger overrides”
Variable Default Description
LINGCHU_COMMAND_TRIGGER_OVERRIDES {} Per-command trigger word overrides (strict JSON). Empty = use defaults. Example: {"kick_member":{"triggers":["kick","踢"]}}
LINGCHU_MENU_PAGE_TRIGGER_OVERRIDES {} Per-menu-page trigger overrides (strict JSON). Empty = use defaults

Protected subject feature keys

Section titled “Protected subject feature keys”
Variable Default Description
LINGCHU_PROTECTED_SUBJECT_FEATURE_KEYS (built-in set) Feature keys that require elevated subject permission. Strict JSON string list. Defaults to a built-in set of 12 sensitive operations (kick_member, block_member, global_block_member, member_mute, recall_message, set_member_card, set_member_title, set_member_admin, unset_member_admin, remote_kick, remote_block, remote_mute)