配置文件与生效顺序

Qoder CLI 的行为可以通过 JSON 格式的配置文件（settings.json）进行定制。配置采用分层设计：同一项配置可以在不同层级分别设置，最终按固定优先级合并成生效值。理解这套分层与合并规则，是管理个人偏好和团队约定的基础。本页介绍配置文件的位置、合并优先级，以及常用配置项。完整的配置项与环境变量清单见配置项、环境变量与文件路径。

配置文件位置

Qoder CLI 读取三层配置文件：

层级	路径	说明
用户级	`~/.qoder/settings.json`	个人偏好，对当前用户的所有项目生效。
项目级	`<项目>/.qoder/settings.json`	项目共享配置，随版本库提交，团队成员共用。
本地级	`<项目>/.qoder/settings.local.json`	个人的项目内覆盖配置，通常不提交到版本库。

配置目录默认为 ~/.qoder，可通过环境变量 QODER_CONFIG_DIR 修改。关于 .qoder/ 目录的完整结构，见 .qoder 目录。

合并优先级

当同一项配置在多个层级出现时，Qoder CLI 按以下优先级从低到高合并，高优先级覆盖低优先级：

内置默认值（Schema 默认）
用户级设置（~/.qoder/settings.json）
项目级设置（<项目>/.qoder/settings.json）
本地级设置（<项目>/.qoder/settings.local.json）
命令行 --settings 指定的配置（最高优先级）

也就是说：本地级会覆盖项目级，项目级会覆盖用户级，命令行显式传入的配置优先于所有文件。

合并方式

配置采用深度合并（deep merge），而不是整体替换：

对象：逐字段递归合并，只覆盖出现的字段，其余保留低优先级的值。
单值（字符串、数字、布尔）：高优先级直接覆盖。
数组：部分配置项（如禁用列表、排除列表）采用“并集合并”，把各层级的值合并去重；其余数组默认按覆盖处理。

因此，你在项目级只需写出想要覆盖的字段，不必复制整份用户配置。

文件夹信任的影响

出于安全考虑，项目级与本地级配置只在当前工作目录被信任时才会应用。若工作目录未被信任，Qoder CLI 只加载用户级配置，忽略项目内的 settings.json 与 settings.local.json。文件夹信任由 security.folderTrust.enabled（默认开启）控制。

文件格式

配置文件为 JSON 格式（支持 // 注释，见下文），顶层为一个对象，配置项大多按分组嵌套，少数配置项直接位于顶层（如 outputStyle、language、agent）。例如：

{
  "outputStyle": "concise",
  "ui": {
    "theme": "Tokyo Night",
    "autoThemeSwitching": true
  },
  "model": {
    "name": "auto",
    "maxSessionTurns": -1
  },
  "tools": {
    "useRipgrep": true
  }
}

说明：

配置文件允许包含注释（解析时会被忽略），方便你为团队约定写说明。
值中可以引用环境变量，运行时会被解析替换。
修改部分配置项需要重启 Qoder CLI 才能生效（见下文标注）。

常用配置项

以下列出最常调整的配置项，按分组组织。标注“需重启”的项修改后需重新启动才生效。

顶层配置项

以下配置项直接写在配置文件顶层，不属于任何分组：

配置项	类型	默认值	说明
`outputStyle`	string	无	激活的输出风格名称（需重启）。兼容 `general.outputStyle` 写法，顶层优先。见输出风格。
`language`	string	无	AI 回复的首选语言（需重启）。
`agent`	string	无	主线程使用的 Agent 名称（需重启）。

ui（界面）

配置项	类型	默认值	说明
`ui.theme`	string	无	颜色主题名称。
`ui.autoThemeSwitching`	boolean	`true`	根据终端背景色自动切换明暗主题。
`ui.customThemes`	object	`{}`	自定义主题定义。
`ui.hideBanner`	boolean	`false`	隐藏启动横幅。
`ui.showLineNumbers`	boolean	`true`	在对话中显示行号。
`ui.loadingPhrases`	enum	`off`	加载时显示内容：`tips` / `witty` / `all` / `off`。
`ui.accessibility.screenReader`	boolean	`false`	屏幕阅读器模式，输出纯文本（需重启）。

更多界面与快捷键配置见界面与快捷键。

model（模型）

配置项	类型	默认值	说明
`model.name`	string	无	对话使用的模型。
`model.reasoningEffort`	enum	无	推理努力级别：`low` / `medium` / `high` 等。
`model.maxSessionTurns`	number	`-1`	会话保留的最大回合数，`-1` 为不限。
`modelConfigs.customModels`	array	`[]`	自定义 BYOK 模型（需重启）。见自定义模型。

tools（工具）

配置项	类型	默认值	说明
`tools.sandbox`	string/boolean/object	无	沙箱执行环境（需重启）。见沙箱。
`tools.sandboxAllowedPaths`	string[]	`[]`	沙箱额外可访问的路径（需重启）。
`tools.sandboxNetworkAccess`	boolean	`false`	沙箱是否允许访问网络（需重启）。
`tools.useRipgrep`	boolean	`true`	使用 ripgrep 进行内容搜索。
`tools.shell.inactivityTimeout`	number	`300`	Shell 命令无输出超时秒数。
`tools.core`	string[]	无	内置工具白名单，仅允许列出的工具（需重启）。
`tools.exclude`	string[]	无	从发现中排除的工具名（需重启）。

security（安全）

配置项	类型	默认值	说明
`security.folderTrust.enabled`	boolean	`true`	是否启用文件夹信任（需重启）。
`security.toolSandboxing`	boolean	`false`	工具级沙箱隔离（需重启）。
`security.disableYoloMode`	boolean	`false`	禁用 `bypass_permissions`（YOLO）权限模式（需重启）。
`security.blockGitExtensions`	boolean	`false`	阻止从 Git 安装和加载扩展（需重启）。
`security.environmentVariableRedaction.enabled`	boolean	`false`	对可能含密钥的环境变量做脱敏（需重启）。

mcp（MCP 服务器）

配置项	类型	默认值	说明
`mcpServers`	object	`{}`	MCP 服务器配置（需重启）。见 MCP。
`mcp.allowed`	string[]	无	允许的 MCP 服务器列表（需重启）。
`mcp.excluded`	string[]	无	排除的 MCP 服务器列表（需重启）。

statusLine（状态栏）

配置项	类型	默认值	说明
`statusLine.type`	string	`command`	状态栏类型，目前仅支持 `command`。
`statusLine.command`	string	`""`	生成状态栏的 Shell 命令，通过 stdin 接收会话数据 JSON。
`statusLine.padding`	number	`0`	状态栏水平填充字符数。

编辑配置

有两种方式修改配置：

在交互界面中：运行 /settings 打开设置面板，直接查看和调整常用配置项。
手动编辑文件：用编辑器打开对应层级的 settings.json，按上表添加或修改字段。

修改后，未标注“需重启”的项通常即时生效；标注“需重启”的项需要重新启动 Qoder CLI。

下一步

查看全部配置项与环境变量：配置项、环境变量与文件路径。
配置自定义模型：自定义模型。
定制界面与快捷键：界面与快捷键。
配置沙箱隔离：沙箱。
排查配置问题：配置不生效。

​配置文件位置

​合并优先级

​合并方式

​文件夹信任的影响

​文件格式

​常用配置项

​顶层配置项

​ui（界面）

​model（模型）

​tools（工具）

​security（安全）

​mcp（MCP 服务器）

​statusLine（状态栏）

​编辑配置

​下一步