Lingchu Bot 使用 NoneBot2 的环境变量系统。将 .env.example 复制为 .env 并根据你的环境调整取值。
项目提供跨平台初始化脚本（./scripts/setup.sh），可自动生成 .env、.env.development、.env.test、.env.production 四个环境配置文件。你也可以手动创建这些文件。
| 变量 |
默认值 |
说明 |
ENVIRONMENT |
prod |
运行环境（prod 或 dev） |
HOST |
0.0.0.0 |
FastAPI 监听地址 |
PORT |
8080 |
FastAPI 监听端口 |
DRIVER |
~fastapi+~httpx+~websockets |
NoneBot 驱动栈；前缀 ~ 启用默认适配器配置 |
| 变量 |
默认值 |
说明 |
COMMAND_START |
["/", ""] |
命令起始前缀；空字符串允许无前缀命令 |
COMMAND_SEP |
[".", " "] |
命令分段分隔符 |
| 变量 |
默认值 |
说明 |
LOG_LEVEL |
INFO |
Python 日志级别 |
FASTAPI_OPENAPI_URL |
/openapi.json |
OpenAPI schema 路径；设为空字符串以禁用 |
FASTAPI_DOCS_URL |
/docs |
Swagger UI 路径；生产环境应禁用 |
FASTAPI_REDOC_URL |
/redoc |
ReDoc 文档路径；生产环境应禁用 |
| 变量 |
默认值 |
说明 |
ALEMBIC_STARTUP_CHECK |
false |
生产环境设为 true 以在启动时强制执行 schema 迁移检查 |
SQLALCHEMY_DATABASE_URL |
（未设置） |
用于多数据库测试的 SQLAlchemy 数据库 URL；支持 SQLite / PostgreSQL / MySQL / MariaDB 四个后端，未设置时使用默认 SQLite |
| 变量 |
默认值 |
说明 |
LINGCHU_IN_CONTAINERS |
false |
在 Docker / Kubernetes 内运行时设为 true。必须为小写 true / false —— NoneBot2 在此只接受 JSON 标准布尔值 |
| 变量 |
默认值 |
说明 |
LINGCHU_SUPERUSERS |
（未设置） |
Lingchu UID 到平台账号映射的 JSON 对象；参见超级用户身份 |
LINGCHU_SUPERUSER_KEY |
123456789abcdef |
未配置 Lingchu 超级用户时用于根级操作的轻量认证密钥。生产环境应覆盖为强随机值 |
参见超级用户身份了解详细配置。
| 变量 |
默认值 |
说明 |
LINGCHU_ADAPTER |
（未设置） |
适配器选择。使用 ~ 前缀启用 NoneBot 适配器简写（如 ~onebot.v11）。接受字符串或字符串列表 |
LINGCHU_LOCALE |
en_US |
Lingchu i18n 语言。支持的目录：zh_CN、en_US。NoneBot 会自动将其转换为 lingchu_locale 配置字段 |
| 变量 |
默认值 |
说明 |
LINGCHU_MESSAGE_STORE_ENABLED |
true |
启用消息存储钩子（群消息历史、审计、摘要） |
LINGCHU_MESSAGE_STORE_RETENTION_DAYS |
30 |
已存储消息的保留天数。0 = 永久保留。必须 >= 0 |
LINGCHU_MESSAGE_STORE_SUMMARY_LIMIT |
500 |
单次摘要包含的最大消息数。必须 >= 0 |
LINGCHU_MESSAGE_STORE_RECORD_API_CALLS |
true |
是否记录平台 API 调用摘要 |
LINGCHU_MESSAGE_STORE_CLEANUP_ENABLED |
true |
启用过期消息记录的自动清理 |
Pydantic AI Agent 通过 localstore 管理的 llm.toml 中的 [pydantic-ai] 段配置，由部署者手动维护（可按 llm.schema.json 生成）。
请把提供商凭据放在 LINGCHU_AI_API_KEY 这类部署环境变量中，再通过 api_key_env
引用变量名；LINGCHU_AI_MODEL（Pydantic AI 模型字符串，如 openai:gpt-5.2 或
anthropic:claude-sonnet-4-5）用于填充 [pydantic-ai] model 字段。部署级 LLM 变量不再作为兜底来源。
| 变量 |
默认值 |
说明 |
LINGCHU_RECALL_MESSAGE_DEFAULT_COUNT |
10 |
未显式指定数量时默认撤回的消息数。范围：1–100 |
| 变量 |
默认值 |
说明 |
LINGCHU_PERMISSION_PLATFORM_RUNTIME_PASSTHROUGH |
true |
平台权限解析器是否透传到运行时配置。true = 透传；false = 严格；或按平台的映射（严格 JSON） |
| 变量 |
默认值 |
说明 |
LINGCHU_COMMAND_TRIGGER_OVERRIDES |
{} |
按命令的触发词覆盖（严格 JSON）。空 = 使用默认值。示例：{"kick_member":{"triggers":["kick","踢"]}} |
LINGCHU_MENU_PAGE_TRIGGER_OVERRIDES |
{} |
按菜单页的触发词覆盖（严格 JSON）。空 = 使用默认值 |
| 变量 |
默认值 |
说明 |
LINGCHU_PROTECTED_SUBJECT_FEATURE_KEYS |
（内置集合） |
需要提升主体权限的功能键。严格 JSON 字符串列表。默认为内置的 12 项敏感操作（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） |