配置的使用范围

概述

Qoder CLI 的配置分成三个使用范围：个人、项目和本地。理解它们各自适合解决什么问题，能帮助你把设置放到正确的位置——既不会把个人偏好错误地强加给团队，也不会把团队约定散落在各自机器上。三个范围对应三个不同的文件：

范围	文件	适合内容	是否随项目提交
个人	`~/.qoder/settings.json`	跨所有项目的个人偏好，例如主题、界面、个人默认模型	否
项目	`<项目>/.qoder/settings.json`	团队共享的项目约定，例如权限规则、项目级模型选择	是
本地	`<项目>/.qoder/settings.local.json`	当前机器上的项目私有设置，例如本地服务地址、个人临时覆盖	否

配置项如何逐层合并、覆盖顺序如何，见配置文件与生效顺序。

个人配置

个人配置放在用户配置目录下的 ~/.qoder/settings.json，对你打开的每一个项目都生效。它适合承载与具体项目无关的个人偏好：

界面主题、状态栏、快捷键等界面偏好。
个人默认使用的模型和推理强度。
自动升级等个人级开关。

个人配置只属于你自己，不会随项目仓库分发给团队。

项目配置

项目配置放在项目根目录的 <项目>/.qoder/settings.json，只对该项目生效，并且适合提交到版本库与团队共享。它适合承载团队希望统一的约定：

权限规则和目录信任策略。
项目统一的模型选择或参数。
项目级的扩展配置（MCP、Hooks 等）。

把这些设置提交到仓库后，团队成员在该项目中使用 Qoder CLI 时会自动应用相同的约定。

本地配置

本地配置放在项目根目录的 <项目>/.qoder/settings.local.json，只对该项目、且只在当前机器上生效。它适合承载不希望提交、也不希望影响他人的私有设置：

本地服务地址、个人测试数据。
对项目配置的个人临时覆盖。

本地配置不应提交到版本库。通常应把 .qoder/settings.local.json 加入 .gitignore。

.qoder 目录结构

除了设置文件，项目根目录下的 .qoder/ 目录还承载了 Qoder CLI 运行时的多种本地数据和扩展。常见内容包括：

<项目>/.qoder/
├── settings.json          # 项目级配置（可提交）
├── settings.local.json    # 本地项目配置（不提交）
├── rules/                 # 项目级规则文件（*.md）
├── skills/                # 项目级 Skills
├── worktrees/             # --worktree 创建的隔离工作树
└── scheduled_tasks.json   # 定时任务定义

其中：

rules/ 下按主题拆分的规则文件，见记忆。
skills/ 下的项目级 Skills，见 Skills。
worktrees/ 下由 --worktree 创建的隔离检出，见使用 CLI 和并行处理多个任务。
scheduled_tasks.json 保存定时任务，见定时执行任务。

用户级的数据（例如 settings.json、认证状态、插件）放在用户配置目录下，默认是 ~/.qoder。

用户配置目录的位置可以通过 QODER_CONFIG_DIR 环境变量自定义。项目级的 .qoder 目录始终位于项目根目录下。

如何选择

放置配置时，可以按下面的顺序思考：

这是跨所有项目都想要的个人偏好吗？→ 放个人配置。
这是团队应当统一的项目约定吗？→ 放项目配置，并提交到仓库。
这是只在我这台机器上、且不希望影响他人的项目设置吗？→ 放本地配置，并加入 .gitignore。

当同一配置项在多个范围出现时，会按生效顺序合并和覆盖。详细规则见配置文件与生效顺序。