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

# 配置优先级

> 全局、项目和本地设置之间如何相互影响

Devin CLI 会从多个来源加载配置，并将其合并。了解配置的优先级顺序，有助于你为团队和个人偏好设置合适的配置。

***

<div id="configuration-layers">
  ## 配置层
</div>

按优先级从高到低：

| 优先级    | 来源                                                                           | 说明                   |
| ------ | ---------------------------------------------------------------------------- | -------------------- |
| 1 (最高) | 组织 / 团队设置                                                                    | 不可覆盖                 |
| 2      | 会话 (交互式审批)                                                                   | 仅存储在内存中              |
| 3      | 项目本地 (`.devin/config.local.json`)                                            | 个人配置，会被 gitignore 忽略 |
| 4      | 项目 (`.devin/config.json`)                                                    | 与团队共享                |
| 5 (最低) | 用户 (`~/.config/devin/config.json`; Windows 上为 `%APPDATA%\devin\config.json`) | 你的默认设置               |

当同一设置在多个层级中定义时，以优先级更高的来源为准。

***

<div id="when-to-use-each-level">
  ## 何时使用各个层级
</div>

<AccordionGroup>
  <Accordion title="用户配置" icon="user" defaultOpen>
    **路径：** `~/.config/devin/config.json` (Windows 上为 `%APPDATA%\devin\config.json`)

    用于适用于所有场景的个人偏好设置：

    * 默认模型偏好
    * 主题偏好
    * 个人 MCP 服务器 (例如，你自己的 API key)
    * 全局权限授权

    ```json theme={null}
    {
      "agent": { "model": "opus" },
      "permissions": {
        "allow": ["Read(**)", "Exec(git)"]
      }
    }
    ```
  </Accordion>

  <Accordion title="项目配置" icon="folder">
    **路径：** `.devin/config.json`

    用于提交到代码仓库中的团队标准配置。此层级仅支持 `permissions`、`mcpServers`、`read_config_from` 和 `hooks`：

    * 共享 MCP 服务器 (使用非敏感配置)
    * 团队权限策略
    * 导入设置
    * 生命周期钩子

    ```json theme={null}
    {
      "permissions": {
        "allow": ["Exec(npm run)", "Read(src/**)"],
        "deny": ["Exec(sudo)"]
      },
      "mcpServers": {
        "github": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="项目本地配置" icon="lock">
    **路径：** `.devin/config.local.json`

    用于不应提交的个人覆盖配置：

    * API key 和 secrets
    * 此项目的个人工具偏好
    * 权限覆盖

    ```json theme={null}
    {
      "mcpServers": {
        "github": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"],
          "env": {
            "GITHUB_TOKEN": "ghp_my_personal_token"
          }
        }
      }
    }
    ```

    <Tip>
      本地配置文件会通过 `.git/info/exclude` 自动从 git 中排除。
    </Tip>
  </Accordion>

  <Accordion title="组织设置" icon="building">
    由你的 Enterprise Admin 通过团队设置仪表板进行管理。这些设置不能被单个用户覆盖，并会在整个组织范围内强制执行策略，例如模型限制和 MCP 服务器允许列表。
  </Accordion>
</AccordionGroup>

***

<div id="whats-available-at-each-level">
  ## 各层级可用的设置
</div>

项目配置 (`.devin/config.json` 和 `.devin/config.local.json`) 仅支持部分设置。下表显示了每个层级可用的设置：

| 设置                         | 用户配置 | 项目配置 |
| -------------------------- | :--: | :--: |
| `permissions`              |   ✓  |   ✓  |
| `mcpServers`               |   ✓  |   ✓  |
| `read_config_from`         |   ✓  |   ✓  |
| `hooks`                    |   ✓  |   ✓  |
| `agent` (模型)               |   ✓  |   ✗  |
| `theme_mode`               |   ✓  |   ✗  |
| `unicode_mode`             |   ✓  |   ✗  |
| `show_path`                |   ✓  |   ✗  |
| `show_hints`               |   ✓  |   ✗  |
| `include_gitignored_files` |   ✓  |   ✗  |
| `sandbox`                  |   ✓  |   ✗  |

标记为仅限用户配置的设置只能在用户配置中设置 (`~/.config/devin/config.json`；Windows 上为 `%APPDATA%\devin\config.json`) ，且不参与上述优先级。

***

<div id="how-merging-works">
  ## 合并机制
</div>

上面的优先级表仅适用于支持多个层级的配置项 (`permissions`、`mcpServers`、`read_config_from`、`hooks`) 。

<div id="permissions">
  ### 权限
</div>

权限列表会在各个级别之间**合并** (叠加) 。较高级别的拒绝不能被较低级别的允许覆盖。

例如，如果你的组织拒绝 `Exec(sudo)`，那么即使你在用户允许列表中添加 `Exec(sudo)`，也不会生效——组织级拒绝始终优先。不过，项目级别的其他权限 (如 `Read(**)`) 仍会正常生效。

<div id="mcp-servers">
  ### MCP 服务器
</div>

MCP 服务器配置会**按名称合并**。在更高层级定义的服务器会覆盖更低层级中同名的服务器。

例如，如果你的用户配置和项目配置都定义了一个 "github" 服务器，由于项目配置的优先级高于用户配置，因此会以项目配置版本为准。

<div id="hooks">
  ### 钩子
</div>

系统会**汇总**来自所有来源的钩子，并全部运行。用户配置中定义的钩子会与项目配置中定义的钩子一同运行——两者不会相互覆盖。

***

<div id="project-root-detection">
  ## 项目根目录检测
</div>

Devin CLI 会从你当前的工作目录开始逐级向上查找，通过寻找 `.git` 或 `.jj` 目录来确定项目根目录。项目配置 (`.devin/`) 会从项目根目录加载。

<Note>
  如果你有嵌套的 `.devin/` 目录 (例如在 monorepo 中) ，子目录中的配置会优先于上级目录中的配置。
</Note>

***

<div id="file-discovery-summary">
  ## 文件发现摘要
</div>

| 文件                                  | 发现来源        | 共享？                 |
| ----------------------------------- | ----------- | ------------------- |
| `~/.config/devin/config.json`       | XDG 路径      | 否                   |
| `.devin/config.json`                | 从当前工作目录向上查找 | 是 (已提交)             |
| `.devin/config.local.json`          | 从当前工作目录向上查找 | 否 (已被 gitignore 忽略) |
| `.devin/skills/*/SKILL.md`          | 项目根目录       | 是 (已提交)             |
| `~/.config/devin/skills/*/SKILL.md` | XDG 路径      | 否                   |
| `AGENTS.md`                         | 项目根目录       | 是 (已提交)             |
| `~/.config/devin/AGENTS.md`         | XDG 路径      | 否                   |

<Note>
  **Windows：** 显示为 `~/.config/devin/` 的路径采用的是 Linux/macOS 的 XDG 约定。在 Windows 上，这些路径会解析为 `%APPDATA%\devin\` (通常是 `C:\Users\<YourUser>\AppData\Roaming\devin\`) 。
</Note>