配置总览¶

主体配置由五份 TOML 文件组成，修改时应按功能归属定位文件及其关联配置。 默认真实配置位于项目根的 config/；模板在配置示例目录。 模板仅用于参考，修改模板不会改变实际运行配置。

五份文件的分工¶

QQ 还有插件目录下的一份 config.toml，保存地址、QQ 身份和访问名单。 它不在主体 config/ 下，备份时不能遗漏。 主体四份内容配置使用统一版本；插件连接配置独立维护版本；选择文件仅声明插件。 各类配置应保留对应版本号，不应统一修改。

引用链决定修改顺序¶

读取时，从任务一路找到连接：

任务的 model_list → 模型的 name
模型的 api_provider → 厂商的 name
厂商 → 实际服务地址与鉴权

填写时从厂商开始，再填模型，最后分配任务。 例如厂商从 dashscope 改名为 my-provider， 必须同步更新所有引用该名称的模型 api_provider。 模型条目 name 改名，也要更新所有任务候选列表。 仅更新厂商接受的 model_identifier，则无需改任务列表。

厂商名称和模型名称各自必须唯一；任务列表也不能重复写同一个模型。 不存在的引用会在启动时直接报错，未被任务选中的模型也会检查厂商引用。 删除旧连接前，先确认模型目录里已经没有任何条目指向它。 目录里保留的鉴权连接即使暂时不用，也必须有合法凭据。

功能开关与模型是两项配置¶

预填模型不代表已经打开对应功能。 语音开启需要语音候选与音色，视觉开启需要标记了视觉能力的候选， 向量开启需要嵌入候选和可选依赖。 打开开关却留下空任务列表会在加载时失败。 具体依赖关系见功能配置；任务段名错误与候选列表为空属于不同配置状态。

用面板修改¶

启动后进入管理面板的「月璃设置」，选择对应文件和配置段。 完成修改后选择「保存配置」，确认成功后选择「重启后端」。 保存会做字段和引用校验；失败时阅读具体字段信息并修正。 保存成功只证明配置可以写入，不证明外部模型或 QQ 已连通。

模型与厂商也可在「模型与厂商」工作台编辑、分配任务。 密钥输入框留空可保持已保存的密钥，首次新增连接必须填写。 面板页面中的适配器配置是当前插件的连接内容； 切换插件目录名仍需编辑主体 adapter.toml，详见适配器配置。

面板保存会重写相关文件，不能依赖手写注释或排版继续保留。 应避免在编辑器修改文件的同时保存未刷新的面板草稿，以免覆盖文件变更。 单次修改应使用一种编辑方式，保存后重新读取并核对结果。

直接编辑 TOML¶

停止应用或选择可以中断对话的时机，用文本编辑器打开真实文件。 应修改已有表中的键，避免追加同名表；字符串加引号，布尔值用小写 true/false。 保存为 UTF-8，再重启后端；配置错误会在终端输出，修正后重新启动。

文件保存本身不会触发持续监视式热更新。 名字、会话策略、模型客户端与功能服务的生效方式不同， 日常修改统一按「保存后重启」操作，避免部分设置仍被旧实例持有。 启动成功后用一轮相同输入核对行为，模型连接再做实际请求验证。

模板和备份¶

完整注释见模板说明，实例配置应在真实配置文件中修改。 首次运行只补缺失文件，不会覆盖已有密钥或自动替换现有模型目录。 新增字段的自动对账、版本不匹配与备份位置见升级与回退。 真实配置和备份都可能含密钥，不进入版本控制。 原理细节见开发手册：配置体系。