配置系统
Yuxi 的配置分成两类：启动进程时读取的环境变量，以及运行中由管理员在页面维护的系统配置。区分这两类，可以判断修改后需要保存、清缓存还是重启服务。本页拥有配置的生效规则；各主题的具体配置见对应 Owner 页面。
配置来源和优先级
对支持运行时修改的字段，生效顺序是：
代码默认值 < 环境变量 < PostgreSQL 中保存的系统配置字符串字段使用数据库非空值，保存为空会恢复环境变量或默认值。列表字段保留明确保存的空列表；整数按字段定义校验并保留合法的 0。各字段的类型、默认值与可选项由所属模块的 Option 定义，不把所有字段都按字符串的空值规则处理。
启动期环境变量由 Docker Compose 注入 API、worker 和依赖服务。它们决定服务地址、密钥、存储位置和沙盒承载方式。修改环境变量后需要重新创建读取它的容器；只执行 docker compose restart 不会更新容器环境：
docker compose up -d --force-recreate api workerCube 连接参数供 API/worker 使用，节点挂载目录必须与 Yuxi 共享同一份文件；生产环境还要带上 --env-file .env.prod -f docker-compose.prod.yml。
管理员系统配置
超级管理员在设置中维护系统级配置：基本设置选择默认模型和协作深度，OCR 配置选择解析引擎及服务，网络搜索选择 Search/Fetch 供应商及凭证。跨域配置定义由 bootstrap/options.py 汇总，各业务模块拥有自己的配置定义，system 只保留系统级默认配置；普通管理员不能调用系统配置写入接口。
系统配置保存到 PostgreSQL 的 config_options 表。非敏感 Option 使用 Redis 短期缓存，提交后执行缓存失效；带敏感字段的 Option 每次回源 PostgreSQL，密钥不进入 Redis 配置缓存。读取缓存失败时回源数据库；提交后的缓存失效失败会记录日志，已有非敏感缓存最长保留到其 300 秒 TTL 到期。事务内读取直接使用数据库值。
页面保存的运行时配置按各模块的读取时机生效；已经冻结的 Input Context 或已初始化组件仍遵循自身生命周期。环境变量只随进程启动环境更新，修改模型 Key、OCR 地址、沙盒连接或数据库地址等环境变量后，重新创建实际读取这些变量的 API/worker。模型供应商的页面保存与刷新规则见模型配置。
用户 Agent 环境变量
登录用户在“设置 → Agent 环境”保存自己的沙盒环境变量。Run 开始执行时从 PostgreSQL 读取一次配置，同一次执行中的所有普通 shell 命令使用该快照，无需重启 VM。保存、修改或删除变量对后续新启动的运行生效，当前执行保持原配置；重试 attempt 和人工等待后恢复产生的新 Run 重新读取配置。快照只保留在执行内存中，不写入运行清单或 checkpoint。平台启动变量和管理密钥不注入用户 VM。
保存后点击“验证配置”，系统在用户 VM 中启动普通账号命令，逐项显示“已生效”或“值不一致”，响应不包含变量值。验证会创建或唤醒环境，结果仅证明该次新命令；用户 shell 启动配置覆盖变量时允许不匹配。未保存编辑禁止验证，编辑、刷新、保存使旧结果失效；验证期间其他页面修改配置时需刷新后重新验证。
当前固定 Cube 版本不提供保留软件与 Home 配置的重启入口。休眠恢复保留进程状态，重建清除软件与 Home；两者都不替代重启。环境状态与重建操作见沙盒配置与运维。
各主题的配置入口
- 模型供应商、聊天模型、嵌入模型和重排模型：模型配置。
- OCR 引擎和各服务凭证：文档处理与 OCR，其中字段读取规则遵循本页的优先级。
- 沙盒应用层与 Cube 执行节点：沙盒配置与运维。
- 环境变量集中在仓库根
.env.template，不另外维护重复配置清单；Agent 并发相关变量的联动核算见 Agent 并发容量。
网络搜索与网页正文
超级管理员在「设置 → 网络搜索」分别选择默认 Search 与 Fetch 供应商。三个服务配置项按 Tavily、DeepSeek、豆包 Custom 展示，每项独立保存 API Key。Tavily 与 DeepSeek 同时支持搜索和按 URL 抓取正文；豆包 Custom 只参与搜索选择，因此可以组合豆包搜索与 DeepSeek 正文抓取。
Key 使用本页的优先级：设置保存值优先，未保存时分别读取 TAVILY_API_KEY、DEEPSEEK_API_KEY、DOUBAO_SEARCH_API_KEY。页面只显示来源与脱敏预览；点击「编辑」填写 Key，点击「保存」生效；编辑时留空并保存会清除数据库配置，恢复读取环境变量。修改环境变量需要重新创建 API 与 worker 容器，页面保存的配置在下一次工具调用时读取。新 Run 装配时只绑定已经配置的网页能力；启动时没有配置也可以稍后在页面启用，无需重启服务。
未保存默认供应商时，Search 优先使用 WEB_SEARCH_PROVIDER；该变量也未指定时，按 Tavily、DeepSeek、豆包顺序选择有 Key 的供应商。Fetch 按 Tavily、DeepSeek 顺序选择。显式指定的供应商不可用时直接报错，调用失败不会自动换到另一家。Agent 使用 web_search 获取标题、链接、短摘要、相关片段与可选正文，通过 web_fetch 深入读取具体 URL 的 Markdown 正文；供应商分数按原始量程展示，不能跨供应商直接比较。
各服务卡片右上角的「测试」使用固定查询与 Python 官方文档地址，分别检查搜索和正文抓取；豆包仅检查搜索。非编辑状态使用当前有效配置，编辑时需填写非空 Key 后测试草稿。测试不保存配置、不改变默认项，只展示「搜索通过」「Fetch 通过」或对应失败原因，空结果不算通过。测试请求可能消耗供应商额度；Tavily 的免费额度和收费规则以官方说明为准。
修改后的确认方式
修改系统配置后，重新打开配置页面确认保存值，并用一次真实请求确认行为。只看到 HTTP 200 或提示“保存成功”不能证明模型、OCR 或检索链路已经可用：模型在供应商页面执行连接测试后再发起一次真实对话，OCR 查看健康状态后解析一份测试文件，知识库回到文件列表确认状态和检索结果，沙盒在用户设置检查环境状态后执行一次真实文件操作。