配置不生效

本页帮助解决 settings.json 配置未按预期生效的问题。配置机制见 配置文件与生效顺序 与 配置项、环境变量与文件路径。

​

配置未生效

• 需要重启：部分配置项标注“需重启”，修改后必须重新启动 Qoder CLI 才生效。对照 配置项、环境变量与文件路径 确认。
• 被更高优先级覆盖：检查是否在更高优先级的层级（本地级 > 项目级 > 用户级）设置了同一项，导致低优先级被覆盖。
• 命令行覆盖：--settings 传入的配置优先于所有文件，会覆盖文件中的同名项。

​

覆盖顺序回顾

配置从低到高优先级合并，高优先级覆盖低优先级：

1. 内置默认值
2. 用户级（~/.qoder/settings.json）
3. 项目级（<项目>/.qoder/settings.json）
4. 本地级（<项目>/.qoder/settings.local.json）
5. 命令行 --settings

对象按字段深度合并；单值直接覆盖；部分数组（如禁用/排除列表）取并集。

​

项目配置被忽略

出于安全考虑，项目级与本地级配置只在当前工作目录被信任时才应用。若项目内的 settings.json 完全未生效：

• 确认当前目录已被信任（security.folderTrust.enabled 默认开启）。
• 未信任时仅加载用户级配置。当前工作目录的信任由启动时的信任提示决定（可选“仅本次会话”或“记住”，后者写入 settings.local.json）；也可在全局 settings 中用 permissions.trustDirectories 将常用目录永久信任。
• /add-dir 与 --add-dir 只为当前会话增加额外的可信目录，不能把未信任的项目目录变为可信。

​

格式错误

• 配置文件为 JSON 格式，允许 // 与 /* */ 注释（解析前会被剥离）。常见错误：多余逗号、引号不匹配、括号未闭合。
• 文件开头的 BOM 会被自动忽略，但仍建议保存为无 BOM 的 UTF-8。
• 借助编辑器与 JSON Schema（schemas/settings.schema.json）获得校验与补全。
• 字段需放在正确的分组下（如 ui.theme 而非顶层 theme）。
• 用 /settings 面板查看和修改，可避免手写格式错误。

​

验证当前配置

• 运行 /settings 查看当前生效的配置项。
• 逐层排查：临时移除本地级/项目级文件，确认是哪一层引入了问题。

​

下一步

• 配置机制：配置文件与生效顺序。
• 配置项全表：配置项、环境变量与文件路径。
• 加载问题（记忆/技能/Agent 未加载）：Memory、Skills 和 Agent 未加载。