配置

配置

Lingchu Bot 将部署配置与在线可编辑设置分离。NoneBot 从操作系统环境变量、.env 文件或全局配置解析部署字段，随后使用模型默认值。Lingchu 不再实现第二套 dotenv 或 TOML 优先级。

在线可编辑的覆盖项存储在 localstore 管理的 runtime-overrides.toml 中。启动过程既不会创建部署配置，也不会安装 JSON Schema；这些写入必须显式使用 CLI。

双配置平面

部署字段属于 NoneBot 配置。只有 permission_platform_runtime_passthrough、command_trigger_overrides 和 menu_page_trigger_overrides 属于 runtime-overrides.toml。

部署配置与可变设置

字段	类型	默认值	说明
superuser_key	string	123456789abcdef	超级用户认证密钥
message_store_enabled	boolean	true	是否启用消息存储运行时钩子
message_store_retention_days	number	30	消息记录保留天数；0 禁用基于天数的过期
message_store_summary_limit	number	500	文本、数据和结果摘要的最大长度
message_store_record_api_calls	boolean	true	是否记录平台 API 调用摘要
message_store_cleanup_enabled	boolean	true	是否在关闭时清理过期的消息记录
recall_message_default_count	number	10	群消息撤回命令省略数量时使用的默认条数
permission_platform_runtime_passthrough	boolean | object	true	平台运行时角色是否可满足 Lingchu 命令授权
command_trigger_overrides	object	{}	按 command_key 覆盖命令主触发词和别名
menu_page_trigger_overrides	object	{}	按菜单页 id 覆盖菜单页命令触发词
protected_subject_feature_keys	string[]	管理类副作用命令	目标用户受白名单保护时会被拦截的命令键
lingchu_adapter	string	未设置	选择各平台启用的适配器（环境变量：LINGCHUAdapter / LINGCHU_ADAPTER）
lingchu_superusers	object（可选）	省略	Lingchu SUPERUSERS 的 UID 到平台账号映射

runtime-overrides.toml 示例：

#:schema ./runtime-overrides.schema.json
permission_platform_runtime_passthrough = true

[command_trigger_overrides.member_mute]
chinese = "禁言"
english = "mute"

[menu_page_trigger_overrides.member-management]
chinese = "成员管理"
english = "member-management"

通过部署环境的 localstore 工具管理 runtime-overrides.toml。请将部署设置放入 NoneBot 环境变量，将可变设置放入 runtime-overrides.toml。程序写回 TOML 时不会保留自定义注释或排版。

部署字段可通过 NoneBot 全局配置提供：

LINGCHUAdapter = "~onebot.v11"

或在 .env 文件中：

LINGCHUAdapter=~onebot.v11

runtime-overrides.toml 拥有不同的字段，因此不会与部署配置竞争优先级。

llm.toml

托管 LLM 运行时在同一个 localstore 配置目录中独立管理 llm.toml 和 llm.schema.json。AI 功能必须配置 [pydantic-ai] 段；部署级 LLM 字段不再 作为兜底来源。旧的 [profiles]、[router]、[eve] 段会被忽略并以弃用 警告提示。

把密钥保存在环境变量中

api_key_env 填写的是环境变量名称，不是凭据本身。Lingchu 在该 profile 首次 使用时解析它。指定的变量不存在或为空时，只会让该 profile 无效，不会阻塞未使用 profile 的初始化或重载；错误信息不会打印密钥或原始校验输入。

#:schema ./llm.schema.json
[pydantic-ai]
model = "openai:gpt-5.2"
api_key_env = "LINGCHU_AI_API_KEY"
base_url = "https://api.openai.com/v1"
timeout = 60.0

[mcp]
enabled = false
review_profile = "default"
max_tool_rounds = 5

[mcp.servers.local_docs]
transport = "stdio"
command = "uvx"
args = ["example-mcp-server"]

[observability]
enabled = true

model 字段必须匹配 ^[\w.-]+:[\w./-]+$；前缀选择 Pydantic AI 提供商（如 openai:、anthropic:、google-gla:、google-vertex:）。Pydantic AI 在 调用时从 api_key_env 声明的环境变量读取凭据，defer_model_check=True 使 运行时可在该环境变量尚未就位前先完成构造。稳定的 LLMRuntime.respond() / stream() 接口委托给 pydantic_ai.Agent.run() / run_stream()，且绝不执行 工具调用；工具执行仅由 [mcp] 配置的显式审查 MCP Agent 承担。

能力探测基于纯模型字符串启发式返回 supported 或 unknown（openai:、 anthropic:、google-gla:、google-vertex: 前缀对 web_search 返回 supported）。可辅助界面和降级决策，但不会拦截显式调用。配置重载会先对候选的 [pydantic-ai] 段做结构校验，再原子切换；凭据仍按 profile 延迟解析。失败时 当前版本不受影响；成功后关闭退役 Agent 并清空能力缓存。

网络与工具安全

• HTTP 出站层仍须重新校验 DNS 结果与重定向，因为静态配置校验不会执行阻塞式 DNS 解析。[pydantic-ai] 段不会对 base_url 做 SSRF 校验；请在部署出站边界 强制网络策略。
• 普通 LLM 调用只把模型工具调用作为数据返回，绝不执行。只有 llm.toml 中 [mcp] 配置的显式审查 Agent 可以执行 MCP；它要求身份组预授权，并将多轮工具 循环委托给一个配置了已授权 MCPToolset 的 pydantic_ai.Agent。旧版项目侧 审查步骤与确认流程已移除。设置 enabled = false 会禁用全部 MCP 发现与执行。

Pydantic AI Agent 保持惰性加载：导入 Lingchu 或在没有可用 [pydantic-ai] 段时 启动，不会导入提供商 SDK。可选依赖缺失只会在首次请求对应提供商时失败，不影响 其他机器人功能。

menu.toml

Lingchu Bot 也会在插件配置目录创建 menu.toml。这个文件只控制菜单展示。

可编辑字段：

• 页面 title
• 功能 summary 和 usage
• 页面、子页面和条目的顺序

代码拥有的字段不能通过 TOML 编辑。command_key 集合、菜单页 command、platform_capability 和实现级 availability 保留在代码中，避免菜单宣称不存在的命令或适配器能力。如需修改菜单页触发词，请使用 config.toml 中的 menu_page_trigger_overrides。如果 menu.toml 引用了未知 command_key，Lingchu 会拒绝该文件并保留代码默认菜单。未知页面 id 会记录警告并跳过。

novelai_image.toml

可选的 NovelAI 嵌套子插件独立拥有该文件及同目录的 novelai_image.schema.json。缺省模型为 nai-diffusion-4-5-full，尺寸 832x1216，28 步，scale 5，采样器 k_euler_ancestral，超时 120 秒。 建议通过 LINGCHU_NOVELAI_TOKEN 设置 token，不要把密钥写入 TOML。

也可以设置 username 并通过环境变量 LINGCHU_NOVELAI_PASSWORD 提供密码， 由子插件向 account_base_url（默认 https://api.novelai.net）换取内存 token。 自定义反向代理可分别设置 base_url 和 account_base_url。

完整图片 API 的通用默认值还包括 n_samples（1-8）、quality、uc_preset （0-3）、noise_schedule、cfg_rescale、dynamic_thresholding、auto_smea、 prefer_brownian、vibe_cache_entries 和 image_download_max_bytes。最后两项 分别限制内存 vibe token 缓存和群聊图片下载大小。

提示词管线使用托管 LLM 的默认 profile 完成语言理解、翻译和参数提示提取。请在 llm.toml 中配置；旧版全局或子插件专用 LLM 兜底键均已删除并会被忽略。Pydantic AI 迁移后不再支持提供商原生联网搜索。

TIPO 提示词扩写由独立、可选的 llama.cpp 服务提供：

tipo_enabled = true
tipo_base_url = "http://127.0.0.1:8081/v1"
tipo_model = "tipo-500m-ft"
tipo_timeout = 30.0
tipo_max_tokens = 512
tipo_temperature = 0.5
tipo_top_p = 0.95
tipo_top_k = 40

tipo_api_key 可选，未设置时不会写入生成的 TOML。所有字段也可以加 LINGCHU_NOVELAI_ 前缀通过环境变量提供，例如 LINGCHU_NOVELAI_TIPO_BASE_URL。设置 tipo_enabled = false 可跳过 TIPO， 直接使用 LLM 产生的英文描述和标签。TIPO 超时、传输失败或返回不可用内容时也会 执行相同降级，不会阻断生图。参见 使用 llama.cpp 部署 TIPO。

权限和触发词自定义

permission_platform_runtime_passthrough 控制 QQ 群主、管理员、成员等平台侧运行时角色是否可以通过运行时身份组满足 Lingchu 授权。设为 false 会要求显式 Lingchu 成员关系，也可以用 [permission_platform_runtime_passthrough] table 配合 qq = false 做平台级控制。

command_trigger_overrides 和 menu_page_trigger_overrides 会在 matcher 注册前加载。因此主触发词变更需要重启生效。覆盖加载器会拒绝跨命令重复的触发词。

白名单保护通过 subject policy API 和 protected_subject_feature_keys 配置。当受保护用户是列表中副作用命令的目标时，Lingchu 会拦截该命令；受保护用户本人仍可执行其有权限执行的命令。

核心路径设置

core_version、data_dir、config_dir、cache_dir 和系统平台辅助信息仍由核心 Config 提供。路径来自 nonebot-plugin-localstore：

路径	用途
data_dir	数据文件目录
config_dir	配置文件目录
cache_dir	缓存文件目录

国际化设置

运行时翻译读取 lingchu_locale NoneBot 配置键。推荐的 .env 项目专用键：

LINGCHU_LOCALE=zh_CN

当前可用目录包括 zh_CN 和 en_US。locale 名称在使用前会进行规范化，因此 en-US 和 en_US.UTF-8 都会变为 en_US。当设置缺失、为空或 NoneBot 尚未初始化时，默认 locale 为 zh_CN。

容器环境标志

in_containers 来自 NoneBot 全局配置。必须为布尔值。

LINGCHU_IN_CONTAINERS=true

布尔值格式

不要写 LINGCHU_IN_CONTAINERS=True。NoneBot 配置文件只接受标准 JSON 小写 true / false。如果传入字符串形式的布尔值，项目会抛出明确的配置错误。

本地运行路径

仓库根目录当前不包含已提交的本地 bot.py。项目级 localstore 路径由 NoneBot 配置控制；参见 .env.example：

LOCALSTORE_USE_CWD=true

这意味着 localstore 相关目录优先使用当前工作目录，便于本地开发和调试。

Handle级配置文件

Lingchu Bot 支持每个 handle 的独立配置文件，实现对单个命令行为的精细控制。每个 handle（命令）都可以有自己的 TOML 配置文件，覆盖代码默认值。

文件命名与位置

Handle 配置文件遵循 <command_key>.toml 的命名规范，存储在由 nonebot-plugin-localstore 管理的插件配置目录中。例如：

• recall_message.toml — 消息撤回命令的配置
• member_mute.toml — 成员禁言命令的配置
• kick_member.toml — 成员踢出命令的配置

标准字段

所有 handle 配置文件共享由 handle_config.schema.json 验证的通用结构：

字段	类型	默认值	说明
enabled	boolean	true	是否启用该 handle
defaults	object	{}	Handle 专用默认值（如 recall_message 的 default_count）
policies	object	{}	该 handle 的策略配置

defaults 对象可以包含 handle 专用字段。例如，recall_message.toml 可能定义 default_count 字段，设置用户省略数量参数时的默认撤回条数。

配置管理器

HandleConfigManager 类提供对 handle 配置的集中访问：

• get_config(command_key) — 读取特定 handle 的配置
• update_config(command_key, updates) — 用部分变更更新配置
• get_all_configs() — 获取所有已注册 handle 的配置
• ensure_config_files() — 用默认值创建缺失的配置文件

管理器会自动：

• 缓存已加载的配置以提升性能
• 文件缺失或无效时回退到已注册的默认值
• 持久化更新前根据 JSON Schema 验证配置

模块独立原则

每个 handle 模块必须在 handle_config_defaults/ 中使用 register_handle_defaults() 注册其默认配置。这确保了：

1. Handle 有规范的默认配置
2. HandleConfigManager 能验证 command_key
3. 缺失的配置文件能回退到已知默认值

必须注册默认配置

尝试读取或更新未注册默认值的 handle 配置会抛出 ValueError: command_key not registered。在使用 HandleConfigManager 访问新 handle 前，务必注册默认配置。

配置文件示例

#:schema ./handle_config.schema.json
enabled = true

[defaults]
default_count = 10

[policies]

此示例展示了 recall_message.toml 文件的标准结构。defaults.default_count 字段覆盖了撤回命令的代码定义默认值。

相关页面

• 环境变量 — .env 变量参考
• 适配器选择 — LINGCHUAdapter 配置
• 超级用户身份 — LINGCHU_SUPERUSERS 设置