Configuration

Configuration

Lingchu Bot stores lightweight runtime settings in a plugin-owned JSON5 configuration file while reusing NoneBot2's global configuration parser.

On first startup, the plugin creates config.json5. Its path is provided by nonebot-plugin-localstore and belongs to the plugin configuration directory, not the data or cache directory.

Runtime settings

Example config.json5:

{
  superuser_key: "123456789abcdef",
  message_store_enabled: true,
  message_store_retention_days: 30,
  message_store_summary_limit: 500,
  message_store_record_api_calls: true,
  message_store_cleanup_enabled: true,
  recall_message_default_count: 10,
  permission_platform_runtime_passthrough: true,
  command_trigger_overrides: {
    member_mute: {
      chinese: "禁言",
      chinese_aliases: ["禁言用户", "禁"],
      english: "mute",
      english_aliases: ["ban"],
    },
  },
  menu_page_trigger_overrides: {
    "member-management": {
      chinese: "成员管理",
      english: "member-management",
    },
  },
  protected_subject_feature_keys: ["kick_member", "member_mute", "recall_message", "block_member"],
  lingchu_adapter: "~onebot.v11",
  lingchu_superusers: null,
}

NoneBot global configuration can still override JSON5:

LINGCHUAdapter = "~onebot.v11"

Or in a .env file:

LINGCHUAdapter=~onebot.v11

If the same key appears in OS environment variables, dotenv, and config.json5, the OS environment variable wins.

menu.json5

Lingchu Bot also creates menu.json5 in the plugin configuration directory. This file controls menu presentation only.

Editable fields:

• Page title
• Feature summary and usage
• Page, child page, and item order

Code-owned fields are not editable from JSON5. The command_key set, menu page command, platform_capability, and implementation availability stay in code so the menu cannot claim a command or adapter capability that does not exist. Use menu_page_trigger_overrides in config.json5 to change menu page triggers. If menu.json5 references an unknown command_key, Lingchu rejects the file and keeps the code defaults. Unknown page ids are skipped with a warning.

Permission and trigger customization

permission_platform_runtime_passthrough controls whether platform-side roles such as QQ group owner/admin/member can satisfy Lingchu permission grants through runtime identity groups. Set it to false to require explicit Lingchu memberships, or to an object such as { qq: false } for platform-specific behavior.

command_trigger_overrides and menu_page_trigger_overrides are loaded before matchers are registered. Primary trigger changes therefore take effect on restart. The override loader rejects duplicate triggers across commands.

Whitelist protection is configured through subject policy APIs and protected_subject_feature_keys. When a protected user is the target of a listed side-effect command, Lingchu blocks that command; protected users may still operate commands they are otherwise allowed to use.

Core path settings

core_version, data_dir, config_dir, cache_dir, and system platform helpers are still provided by the core Config. Paths come from nonebot-plugin-localstore:

Announcement image path bridge

For NapCat Docker announcement image path bridging, see NapCat Docker.

Internationalization settings

Runtime translation reads these NoneBot configuration keys in order:

1. lingchu_locale
2. lc_locale
3. locale

The recommended project-specific key in .env is:

LINGCHU_LOCALE=zh_CN

Available catalogs currently include zh_CN and en_US. Locale names are normalized before use, so en-US and en_US.UTF-8 both become en_US. When the setting is missing, empty, or NoneBot has not been initialized, the default locale is zh_CN.

Container environment flag

in_containers comes from global NoneBot configuration. It must be a Boolean value.

IN_CONTAINERS=true

Local runtime paths

The repository root currently does not ship a committed local bot.py. Project-level localstore paths are controlled by NoneBot configuration; see .env.example:

LOCALSTORE_USE_CWD=true

This means localstore-related directories prefer the current working directory, which is convenient for local development and debugging.

Handle-level configuration files

Lingchu Bot supports per-handle configuration files for granular control of individual command behaviors. Each handle (command) can have its own JSON5 configuration file that overrides code defaults.

File naming and location

Handle configuration files follow the naming convention <command_key>.json5 and are stored in the plugin configuration directory managed by nonebot-plugin-localstore. For example:

• recall_message.json5 — Configuration for the message recall command
• member_mute.json5 — Configuration for the member mute command
• kick_member.json5 — Configuration for the kick member command

Standard fields

All handle configuration files share a common structure validated by handle_config.schema.json5:

The defaults object can contain handle-specific fields. For example, recall_message.json5 might define a default_count field that sets the default number of messages to recall when the user omits the count parameter.

Configuration manager

The HandleConfigManager class provides centralized access to handle configurations:

• get_config(command_key) — Read configuration for a specific handle
• update_config(command_key, updates) — Update configuration with partial changes
• get_all_configs() — Get configurations for all registered handles
• ensure_config_files() — Create missing configuration files with defaults

The manager automatically:

• Caches loaded configurations for performance
• Falls back to registered defaults when files are missing or invalid
• Validates configurations against JSON Schema before persisting updates

Module independence principle

Each handle module must register its default configuration in handle_config_defaults/ using register_handle_defaults(). This ensures:

1. The handle has a canonical default configuration
2. HandleConfigManager can validate the command_key
3. Missing configuration files fall back to known defaults

Example configuration file

{
  "$schema": "handle_config.schema.json5",
  enabled: true,
  defaults: {
    default_count: 10,
  },
  policies: {},
}

This example shows a recall_message.json5 file with the standard structure. The defaults.default_count field overrides the code-defined default for the recall command.

Related pages

• Environment Variables — .env variable reference
• Adapter Selection — LINGCHUAdapter configuration
• Superuser Identity — LINGCHU_SUPERUSERS settings