> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置的使用范围

<div id="overview">
  # 概述
</div>

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

三个范围对应三个不同的文件：

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

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

<div id="personal">
  # 个人配置
</div>

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

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

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

<div id="project">
  # 项目配置
</div>

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

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

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

<div id="local">
  # 本地配置
</div>

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

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

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

<div id="directory-structure">
  # .qoder 目录结构
</div>

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

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

其中：

* `rules/` 下按主题拆分的规则文件，见 [记忆](/zh/cli/04-扩展QoderCLI/memory)。
* `skills/` 下的项目级 Skills，见 [Skills](/zh/cli/04-扩展QoderCLI/Skills)。
* `worktrees/` 下由 `--worktree` 创建的隔离检出，见 [使用 CLI](/zh/cli/03-使用QoderCLI/01-开始一个任务/using-cli) 和 [并行处理多个任务](/zh/cli/03-使用QoderCLI/03-多任务与协作/parallel)。
* `scheduled_tasks.json` 保存定时任务，见 [定时执行任务](/zh/cli/03-使用QoderCLI/02-任务自动化/scheduled)。

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

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

<div id="choose">
  # 如何选择
</div>

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

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

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