> ## 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 配置文件格式的完整参考

Devin CLI 使用 JSON 文件 (支持注释) 进行配置。本页介绍所有可用选项。

***

<div id="file-locations">
  ## 文件位置
</div>

| 文件                            | 目的                   |
| ----------------------------- | -------------------- |
| `~/.config/devin/config.json` | 用户级设置                |
| `.devin/config.json`          | 项目设置 (已提交)           |
| `.devin/config.local.json`    | 项目本地覆盖设置 (已被 Git 忽略) |

<Note>
  在 Windows 上，用户配置文件路径为 `%APPDATA%\devin\config.json` (例如 `C:\Users\<you>\AppData\Roaming\devin\config.json`) ，而不是 `~\.config\devin\config.json`。
</Note>

***

<div id="full-config-reference">
  ## 完整配置参考
</div>

<Tabs>
  <Tab title="用户配置">
    ```json theme={null}
    // ~/.config/devin/config.json
    {
      // Agent 行为
      "agent": {
        "model": "swe-1-6-fast",           // 默认模型
        "show_history_on_continue": true  // 恢复时显示消息记录
      },

      // 主题
      "theme_mode": null,            // "light"、"dark"、"terminal-dark"、"terminal-light"、"nocolor" 或 null（自动）

      // 权限
      "permissions": {
        "allow": [],
        "deny": [],
        "ask": []
      },

      // MCP 服务器
      "mcpServers": {},

      // 显示
      "show_path": false,             // 在输入框边框中显示 CWD
      "unicode_mode": "auto",         // "auto"、"unicode" 或 "ascii"
      "show_hints": true,             // 在各轮对话之间显示提示

      // 文件补全
      "include_gitignored_files": false, // 在 @ 补全中包含已加入 gitignore 的文件

      // 文件访问
      "respect_gitignore": false,        // 阻止工具访问已加入 gitignore 的路径

      // 提交与 PR 署名
      "attribution": true,            // 向提交和 PR 添加“Generated with Devin”/ Co-Authored-By

      // 更新
      "auto_update": true,            // 在后台安装新版本

      // 通知
      "notify": "smart",              // "never" | "smart" | "always" — 终端通知

      // CLI HTTP 流量的代理设置
      "proxy": {
        "mode": "system",           // "system" | "manual" | "off"
        "url": null,                // 代理 URL（手动模式下必填）
        "no_proxy": null            // 以逗号分隔的不走代理列表
      },

      // 沙盒网络过滤
      "sandbox": {
        "allowed_domains": [],       // 域名允许列表（空 = 不过滤）
        "denied_domains": [],        // 域名拒绝列表（优先）
        "network_mode": "full"       // "full" 或 "limited"（仅限 GET/HEAD/OPTIONS）
      },

      // 从其他工具导入设置
      "read_config_from": {
        "cursor": true,
        "windsurf": true,
        "claude": true
      }
    }
    ```
  </Tab>

  <Tab title="项目配置">
    ```json theme={null}
    // .devin/config.json
    {
      // 权限
      "permissions": {
        "allow": [],
        "deny": [],
        "ask": []
      },

      // MCP 服务器
      "mcpServers": {},

      // 从其他工具导入设置
      "read_config_from": {
        "cursor": true,
        "windsurf": true,
        "claude": true
      }
    }
    ```
  </Tab>
</Tabs>

***

<div id="options-reference">
  ## 选项参考
</div>

<Note>
  标记为 **仅限用户** 的选项只能在用户配置中设置 (`~/.config/devin/config.json`；Windows 上为 `%APPDATA%\devin\config.json`) 。项目配置中只有 `permissions`、`mcpServers`、`read_config_from` 和 `hooks` 可用。
</Note>

### Agent <span style={{fontSize: '0.7em', color: 'gray'}}>(仅限用户)</span>

| 选项                         | 类型      | 默认值              | 描述             |
| -------------------------- | ------- | ---------------- | -------------- |
| `model`                    | string  | `"swe-1-6-fast"` | 默认 AI 模型       |
| `show_history_on_continue` | boolean | `true`           | 恢复会话时显示之前的消息记录 |

### theme\_mode <span style={{fontSize: '0.7em', color: 'gray'}}>(仅限用户)</span>

| 值                  | 行为                                |
| ------------------ | --------------------------------- |
| `null`             | 自动检测 (首次运行时会询问)                   |
| `"light"`          | 浅色主题                              |
| `"dark"`           | 深色主题                              |
| `"terminal-dark"`  | 采用 16 色 ANSI 颜色量化的深色主题 (遵循终端配色方案) |
| `"terminal-light"` | 采用 16 色 ANSI 颜色量化的浅色主题 (遵循终端配色方案) |
| `"nocolor"`        | 无颜色输出 (单色，适用于 VT100 终端)           |

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

完整文档请参阅[权限](/zh/cli/reference/permissions)。

```json theme={null}
{
  "permissions": {
    "allow": ["Read(**)", "Exec(git)"],
    "deny": ["Exec(sudo)"],
    "ask": ["Write(**/.env*)"]
  }
}
```

<div id="mcpservers">
  ### mcpServers
</div>

服务器名称到服务器配置的映射。支持本地命令 (stdio) 和远程 HTTP 服务器。请参阅 [MCP Configuration](/zh/cli/extensibility/mcp/configuration)。

```json theme={null}
{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": { "KEY": "value" }
    },
    "remote-server": {
      "url": "https://mcp.example.com/mcp",
      "transport": "http"
    }
  }
}
```

### show\_path <span style={{fontSize: '0.7em', color: 'gray'}}>(仅限用户)</span>

在输入框边框中显示当前工作目录路径。启用后，输入框上边框会显示美化后的 CWD (例如 `~/projects/my-app`) 。

| 值       | 行为               |
| ------- | ---------------- |
| `false` | 隐藏 (默认)          |
| `true`  | 在输入框边框中显示 CWD 路径 |

### unicode\_mode <span style={{fontSize: '0.7em', color: 'gray'}}>(仅限用户)</span>

控制终端 UI 使用 Unicode 符号，还是使用兼容 ASCII 的替代字符。如果你的终端或字体无法正确渲染 Unicode 字形 (例如 ⏺ 符号显示为方框) ，请将其设为 `"ascii"`。

| 值           | 行为                      |
| ----------- | ----------------------- |
| `"auto"`    | 从环境中检测是否支持 Unicode (默认) |
| `"unicode"` | 始终使用 Unicode 符号         |
| `"ascii"`   | 始终使用兼容 ASCII 的字符        |

### show\_hints <span style={{fontSize: '0.7em', color: 'gray'}}>(仅限用户)</span>

在对话轮次之间偶尔显示提示 (例如“你知道吗：使用 `/model` 可在可用模型之间切换”) 。有助于你了解 CLI 功能；熟悉后可将其设为 `false` 以关闭这些提示。

| 值       | 行为          |
| ------- | ----------- |
| `true`  | 偶尔显示提示 (默认) |
| `false` | 从不显示提示      |

### include\_gitignored\_files <span style={{fontSize: '0.7em', color: 'gray'}}>(仅限用户)</span>

在 `@` 选项卡补全结果中包含被 Git 忽略的文件。启用后，匹配 `.gitignore` 规则的文件会出现在 `@` 提及补全中。如果你将文档或其他文件存放在被 Git 忽略的目录中，并希望引用它们，此选项会很有用。

| 值       | 行为                     |
| ------- | ---------------------- |
| `false` | 从补全中排除被 Git 忽略的文件 (默认) |
| `true`  | 在 `@` 补全中包含被 Git 忽略的文件 |

### respect\_gitignore <span style={{fontSize: '0.7em', color: 'gray'}}>(仅限用户)</span>

控制 Agent 在通过工具读取或写入文件时是否遵守 `.gitignore`。启用后，访问被 `.gitignore` 忽略路径的工具调用会被阻止。这与 `include_gitignored_files` 不同，后者仅影响 `@` 选项卡补全。

| 值       | 行为                                      |
| ------- | --------------------------------------- |
| `false` | 无论 `.gitignore` 如何，Agent 都可以访问所有文件 (默认) |
| `true`  | 阻止工具访问被 `.gitignore` 忽略的路径              |

### attribution <span style={{fontSize: '0.7em', color: 'gray'}}>(仅限用户)</span>

控制 Agent 是否在其创建的提交和拉取请求中添加 Devin 署名。启用后，提交信息和 PR 正文会包含一行 `Generated with [Devin]` 以及一个 `Co-Authored-By: Devin` 尾注。将其设为 `false` 可省略这两项，即不添加任何 Devin 署名。

| 值       | 行为                                                                |
| ------- | ----------------------------------------------------------------- |
| `true`  | 在提交和 PR 中添加 `Generated with [Devin]` 行以及 `Co-Authored-By` 尾注 (默认) |
| `false` | 不在提交和 PR 中添加任何 Devin 署名                                           |

### auto\_update <span style={{fontSize: '0.7em', color: 'gray'}}>(仅限用户)</span>

控制 macOS 和 Linux 上的后台自动更新。启用后，Devin CLI 运行期间会在后台下载并启用新版本，因此下次调用 `devin` 时会自动使用最新版本。当前正在运行的会话不受影响——`current` 符号链接的切换只会在下次启动时生效。

此更新机制可安全应对中断：文件系统的每个步骤都会先暂存到临时路径，再通过原子重命名切换到正式位置；同时，并发更新会通过文件锁按顺序执行。更新过程中即使退出，也不会导致安装损坏——下次启动时仍只会继续使用旧版本。

仅适用于自行管理的安装 (macOS/Linux 上通过 `curl | bash` 安装) 。与其他产品捆绑的安装 (例如 Windsurf) 会忽略此设置，并通过其宿主应用进行更新。

| 值       | 行为                       |
| ------- | ------------------------ |
| `true`  | 在后台下载并安装新版本 (默认)         |
| `false` | 仅检查新版本；通过 `/update` 手动安装 |

<div id="notify">
  ### notify
</div>

控制 Agent 完成任务或需要 user 输入时的终端通知。CLI 会写入一个 BEL 字符 (触发终端铃声/可视铃声) 、一个 OSC 9 转义序列 (在 iTerm2 和兼容终端中触发系统通知) ，以及一个 OSC 777 序列 (在 rxvt-unicode 和其他终端中触发桌面通知) 。无法识别这些序列的终端会安全地忽略它们。

| Value      | Behavior                                |
| ---------- | --------------------------------------- |
| `"never"`  | 不通知                                     |
| `"smart"`  | 仅在终端窗口未获得焦点时通知 (使用 OSC 焦点报告)  (default) |
| `"always"` | 无论是否获得焦点，只要发生符合条件的事件就通知                 |

<div id="read_config_from">
  ### read\_config\_from
</div>

控制是否从其他 AI 工具的配置中导入：

| 选项         | 类型           | 默认值    | 说明                      |
| ---------- | ------------ | ------ | ----------------------- |
| `cursor`   | boolean/null | `true` | 从 `.cursor/rules/` 导入   |
| `windsurf` | boolean/null | `true` | 从 `.windsurf/rules/` 导入 |
| `claude`   | boolean/null | `true` | 从 `.claude/` 导入         |

设为 `false` 可禁用某项导入。`null` 会被视为 `true`。

### proxy <span style={{fontSize: '0.7em', color: 'gray'}}>(仅限用户)</span>

配置 CLI 如何为自身发出的 HTTP/HTTPS 流量 (API 调用、更新、MCP 服务器等) 选择代理路由。这不会影响 sandbox 子进程的联网方式 (见下方的 `sandbox`) 。

`mode` 字段用于选择代理策略：

| Mode                 | Behavior                                                                                |
| -------------------- | --------------------------------------------------------------------------------------- |
| `"system"` (default) | 遵循环境变量 (`HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`) ，以及 macOS 和 Windows 上平台原生的 PAC (代理自动配置) |
| `"manual"`           | 通过明确指定的 `url` 转发所有 CLI 流量                                                               |
| `"off"`              | 直接连接——不使用代理                                                                             |

| Option     | Type        | Default    | Description                                                                                       |
| ---------- | ----------- | ---------- | ------------------------------------------------------------------------------------------------- |
| `mode`     | string      | `"system"` | 代理策略：`"system"`、`"manual"` 或 `"off"`                                                              |
| `url`      | string/null | `null`     | 代理 URL。当 `mode` 为 `"manual"` 时为必填。支持 `http://`、`https://` 和 `socks5://` 协议                        |
| `no_proxy` | string/null | `null`     | 不走代理的主机/域名逗号分隔列表。使用与 `NO_PROXY` 环境变量相同的语法 (例如 `"localhost,127.0.0.1,.corp.example.com"`) 。适用于任何模式 |

**示例——企业代理：**

```json theme={null}
{
  "proxy": {
    "mode": "manual",
    "url": "http://proxy.corp.example.com:8080",
    "no_proxy": "localhost,127.0.0.1,.internal.corp"
  }
}
```

**示例——禁用代理：**

```json theme={null}
{
  "proxy": {
    "mode": "off"
  }
}
```

<div id="sandbox" />

### 沙盒 <span style={{fontSize: '0.7em', color: 'gray'}}>(仅限用户)</span>

<Warning>
  Sandbox 网络过滤目前还不稳定。如果你需要此功能，请联系你的账户代表，了解其稳定性时间表。
</Warning>

为 沙盒 配置域级网络过滤。启用 `--sandbox` 且已配置域过滤时，系统会在回环地址上启动一个受管网络代理，沙盒 会强制所有子进程的网络流量都经由该代理转发。

<Note>
  如需全面了解 沙盒 的工作方式——包括企业级强制执行机制，以及企业设置与用户设置如何交互——请参阅 [沙盒 文档](/zh/cli/sandbox)。
</Note>

`--sandbox` 标志会在操作系统层面强制执行当前生效的 Read 和 Write 权限作用域。可写根目录根据已授予的 `Write(...)` 作用域以及工作区目录派生而来；可读根目录则来自 `Read(...)` 作用域 (平台默认路径始终可读) 。在会话中途授予的作用域会动态扩展 沙盒，使其对后续命令生效。

<Note>
  如果传入了 `--sandbox`，但 沙盒 初始化失败 (例如当前平台上没有可用的沙箱工具) ，CLI 会拒绝启动，而不是在无 沙盒 的情况下运行。这种“故障默认关闭”的行为可确保 `--sandbox` 的安全意图绝不会被悄然绕过。
</Note>

| 选项                | 类型        | 默认值      | 描述                                                     |
| ----------------- | --------- | -------- | ------------------------------------------------------ |
| `allowed_domains` | string\[] | `[]`     | 允许通过代理的域名模式。非空时，仅允许匹配的域名通过 (允许列表模式)                    |
| `denied_domains`  | string\[] | `[]`     | 始终阻止的域名模式。拒绝规则优先于允许规则                                  |
| `network_mode`    | string    | `"full"` | `"full"` 允许所有 HTTP 方法；`"limited"` 仅允许 GET/HEAD/OPTIONS |

**域名模式语法：**

| 模式               | 匹配项            |
| ---------------- | -------------- |
| `example.com`    | 仅精确匹配          |
| `*.example.com`  | 任意子域名 (不包括根域名) |
| `**.example.com` | 根域名及其任意子域名     |

**示例：**

```json theme={null}
{
  "sandbox": {
    "allowed_domains": [
      "github.com",
      "**.npmjs.org",
      "**.crates.io",
      "**.pypi.org"
    ],
    "denied_domains": ["evil.example.com"],
    "network_mode": "full"
  }
}
```

<Note>
  仅在sandbox启用时 (`--sandbox`) ，域过滤才会生效。不使用 `--sandbox` 时，会忽略沙盒相关部分。
</Note>

<Note>
  对于企业团队，管理员可以通过 [团队设置](/zh/cli/enterprise/team-settings#sandbox-enforcement) 覆盖域名列表。企业允许列表以其配置为准 (会替换你本地的 `allowed_domains`) ，而企业拒绝列表则为叠加模式 (会与你本地的 `denied_domains` 合并) 。
</Note>

***

<div id="json-with-comments">
  ## 带注释的 JSON
</div>

配置文件支持 JavaScript 风格的注释：

```json theme={null}
{
  // 行注释
  "agent": {
    "model": "sonnet"  // 内联注释
  },
  /* 块注释
     */
  "permissions": {}
}
```