> ## 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.

# 权限

> 通过细粒度的权限规则控制 Agent 可执行的操作

权限系统用于控制 Agent 在无需你批准的情况下可以执行哪些操作。你可以预先批准安全操作，阻止危险操作，并始终对敏感操作发出提示。

***

<div id="default-permission-behavior">
  ## 默认权限行为
</div>

Devin CLI 使用分层权限系统，在功能性与安全性之间取得平衡。默认行为取决于当前的[模式](/zh/cli/essential-commands#modes)：

每个单元格显示该工具在该模式下是自动运行 (**自动**，不提示) 还是等待你批准 (**提示**) ：

| 工具类型                     | 示例             | Normal | Accept Edits | Bypass | Autonomous (沙盒) |
| ------------------------ | -------------- | ------ | ------------ | ------ | --------------- |
| 只读                       | 文件读取、grep、glob | 自动     | 自动           | 自动     | 自动              |
| Fetch                    | HTTP 请求        | 提示     | 提示           | 自动     | 自动              |
| Bash 命令                  | Shell 执行       | 提示     | 提示           | 自动     | 自动              |
| 通过 `edit`/`write` 进行文件编辑 | 编辑/写入文件        | 提示     | 自动 (在 工作区 内) | 自动     | 提示              |

在 **Normal 模式** (默认模式) 下，只读操作会自动获批，而写入和 shell 命令则需要你明确批准。每次批准某个操作时，你都可以选择仅允许一次、在当前 会话 期间允许，或永久允许该项目执行。

在 **Accept Edits 模式**下，工作区 内的文件编辑会自动获批，但 shell 命令以及对 工作区 外的写入仍然会触发提示。

在 **Bypass 模式**下，所有工具调用都会自动获批，不再提示。

在 **Autonomous 模式**下，shell 命令和网络抓取会自动获批，因为操作系统级沙盒会限制它们可访问的范围。通过 `edit`/`write` 工具进行的直接文件编辑仍会触发提示，因为这些工具在沙盒之外运行。只有在[操作系统级沙盒](#autonomous-mode)处于启用状态时，才可使用 Autonomous。

<Warning>
  Bypass 和 Autonomous 模式**不会**覆盖组织级权限。通过 [团队设置](/zh/cli/enterprise/team-settings) 配置的、由 Admin 强制执行的拒绝和询问规则，无论用户使用哪种权限模式，都会继续生效。详情请参阅[优先级](#precedence)。
</Warning>

<div id="autonomous-mode">
  ### Autonomous 模式
</div>

Autonomous 是与 `--sandbox` 标志配套的权限模式。从概念上说，它大致相当于“接受当前工作区中的编辑”，再加上可运行任意 shell 命令，并且这两种行为都受到操作系统级沙箱的约束。当 sandbox 处于激活状态时：

* **这是唯一可用的权限模式。** 在 sandbox 会话中，Normal、Accept Edits 和 Bypass 都会被隐藏。Plan mode 仍然可用。
* **Shell 命令和抓取操作会自动获批**，而不是弹出提示，因为沙箱会限制它们可读取、写入的内容，以及可通过网络访问的范围。
* **通过 `edit` 和 `write` 工具直接编辑文件时仍会弹出提示。** 这些工具运行在 CLI 进程内，而不是沙箱内，因此无法受到沙箱约束。在提示中授予 `Write(...)` 作用域后，沙箱会动态扩展，使后续 shell 命令也能在该位置写入。
* **在会话中途授予的作用域会动态扩展沙箱**，以便后续命令使用。

```bash theme={null}
devin --sandbox --permission-mode autonomous
```

如果你希望在不进行操作系统级隔离的情况下不受限制地执行，请使用 Bypass；如果你希望在操作系统强制限制文件系统和网络访问的前提下进行无人值守执行，请使用 `--sandbox` (会选择 Autonomous) 。有关可写/可读根目录和域过滤的详细信息，请参阅[沙箱配置参考](/zh/cli/reference/configuration/config-file#sandbox)；有关企业级控制，请参阅[团队设置 → 沙箱强制执行](/zh/cli/enterprise/team-settings#sandbox-enforcement)。

***

<div id="how-permissions-work">
  ## 权限的工作方式
</div>

当 Agent 调用工具时，权限系统会按优先级顺序检查你的规则：

1. **拒绝规则** — 优先检查。如果匹配，操作会立即被阻止。
2. **询问规则** — 其次检查。如果匹配，系统总会提示你确认 (会覆盖任何允许规则) 。
3. **允许规则** — 最后检查。如果匹配，操作会直接继续，不会提示。
4. **默认** — 如果没有任何规则匹配，系统会提示你批准。

<Note>
  由于系统会先检查拒绝规则，再检查询问规则，最后检查允许规则，因此拒绝规则始终优先。如果同一作用域同时匹配拒绝规则和询问规则，则以拒绝规则为准。
</Note>

***

<div id="configuration">
  ## 配置
</div>

在配置文件的 `permissions` 部分中添加权限：

<Note>
  在 Windows 上，用户配置文件路径为 `%APPDATA%\devin\config.json` (通常是 `C:\Users\<you>\AppData\Roaming\devin\config.json`) ，而不是 `~/.config/devin/config.json`。详情请参阅[配置文件](/zh/cli/reference/configuration/config-file#file-locations)。
</Note>

<Tabs>
  <Tab title="项目配置">
    ```json theme={null}
    // .devin/config.json
    {
      "permissions": {
        "allow": [
          "Read(src/**)",
          "Exec(npm run)"
        ],
        "deny": [
          "Exec(rm)"
        ]
      }
    }
    ```
  </Tab>

  <Tab title="用户配置">
    ```json theme={null}
    // ~/.config/devin/config.json
    {
      "permissions": {
        "allow": [
          "Read(**)",
          "Exec(git)"
        ]
      }
    }
    ```
  </Tab>

  <Tab title="本地覆盖">
    ```json theme={null}
    // .devin/config.local.json
    {
      "permissions": {
        "allow": [
          "Exec(docker compose)"
        ]
      }
    }
    ```
  </Tab>
</Tabs>

***

<div id="permission-syntax">
  ## 权限语法
</div>

权限匹配器分为两种类型：**基于作用域的** (控制可访问的路径/命令/URL) 和 **基于工具的** (控制可使用哪些工具) 。

<div id="scope-based-permissions">
  ### 基于作用域的权限
</div>

<AccordionGroup>
  <Accordion title="Read(glob)" icon="eye" defaultOpen>
    控制文件读取权限。glob 模式用于匹配文件路径。

    ```json theme={null}
    "allow": [
      "Read(src/**)",           // src/ 下的所有文件
      "Read(~/.config/**)",     // 主目录中的配置文件
      "Read(/tmp/**)"           // 临时目录
    ]
    ```

    目录路径会自动匹配其中的所有文件。
  </Accordion>

  <Accordion title="Write(glob)" icon="pen">
    控制文件写入/编辑权限。

    ```json theme={null}
    "allow": [
      "Write(src/**)",          // 可写入 src/ 下的任意位置
      "Write(tests/**)"         // 可写入测试文件
    ],
    "deny": [
      "Write(*.lock)",          // 不能修改 lock 文件
      "Write(.env*)"            // 不能修改 env 文件
    ]
    ```
  </Accordion>

  <Accordion title="Exec(prefix)" icon="terminal">
    控制 shell 命令执行权限。匹配以给定前缀开头的命令。

    ```json theme={null}
    "allow": [
      "Exec(git)",              // git、git status、git commit...
      "Exec(npm run)",          // npm run test、npm run build...
      "Exec(python)"            // python、python script.py...
    ],
    "deny": [
      "Exec(rm)",               // 阻止 rm、rm -rf 等命令
      "Exec(sudo)"              // 阻止 sudo 命令
    ]
    ```

    <Note>
      `Exec(git)` 会匹配 "git"、"git status"、"git commit -m 'msg'"，但不会匹配 "gitk" 或 "github-cli"。该前缀必须作为完整单词匹配。
    </Note>
  </Accordion>

  <Accordion title="Fetch(pattern)" icon="globe">
    使用 URL 模式控制 HTTP fetch 权限。

    ```json theme={null}
    "allow": [
      "Fetch(https://api.github.com/*)",    // GitHub API
      "Fetch(https://*.example.com/*)",     // 所有 example.com 子域名
      "Fetch(domain:npmjs.org)"             // npmjs.org 上的任意 URL
    ]
    ```

    URL 模式遵循 [WHATWG URL Pattern](https://urlpattern.spec.whatwg.org/) 标准。`domain:` 简写会匹配该精确域名下的任意路径。
  </Accordion>
</AccordionGroup>

<div id="tool-based-permissions">
  ### 基于工具的权限
</div>

按工具名称匹配，以控制整个工具：

```json theme={null}
{
  "permissions": {
    "deny": [
      "edit",       // 阻止所有文件编辑
      "exec"        // 阻止所有命令执行
    ],
    "allow": [
      "read",       // 允许所有文件读取
      "grep",       // 允许所有搜索
      "glob"        // 允许所有文件查找
    ]
  }
}
```

**可用工具名称：** `read`, `edit`, `grep`, `glob`, `exec`

<div id="mcp-tool-permissions">
  ### MCP 工具权限
</div>

管理对 MCP 服务器工具的访问：

```json theme={null}
{
  "permissions": {
    "allow": [
      "mcp__github__list_issues",     // 特定服务器上的特定工具
      "mcp__github__*",               // GitHub 服务器上的所有工具
      "mcp__*"                        // 所有 MCP 工具
    ],
    "deny": [
      "mcp__github__delete_repo"      // 禁止特定危险工具
    ]
  }
}
```

| 模式                  | 匹配                    |
| ------------------- | --------------------- |
| `mcp__server__tool` | 某个特定工具                |
| `mcp__server__*`    | 某个 server 上的所有工具      |
| `mcp__*`            | 所有 server 上的全部 MCP 工具 |

***

<div id="path-patterns">
  ## 路径匹配模式
</div>

`Read()` 和 `Write()` 支持以下 Glob 模式：

| 模式   | 含义               |
| ---- | ---------------- |
| `*`  | 单个路径段中的任意字符      |
| `**` | 跨多个路径段的任意字符 (递归) |
| `~`  | 主目录展开            |

**示例：**

```json theme={null}
"allow": [
  "Read(**)",                    // 所有位置的所有文件
  "Read(src/**/*.ts)",           // src/ 下的所有 TypeScript 文件
  "Write(~/projects/myapp/**)"   // 写入指定项目
]
```

<Note>
  当你想匹配系统中的所有文件时，请使用绝对路径前缀 (例如 `Read(/**)`) 。不带前导 `/` 的 `Read(**)` 会相对于你当前的工作目录解析，因此它只会匹配该目录下的文件，而不会匹配通过其他位置的绝对路径访问的文件。
</Note>

***

<div id="persistence-options">
  ## 持久化选项
</div>

当 Agent 在会话期间请求权限时，你可以选择如何保存你的决定：

| 选项         | 保存位置                                                                     | 与团队共享？ |
| ---------- | ------------------------------------------------------------------------ | ------ |
| 允许一次       | 不保存                                                                      | 否      |
| 在当前会话中允许   | 仅保存在内存中                                                                  | 否      |
| 对项目允许      | `.devin/config.json`                                                     | 是      |
| 对项目允许 (本地) | `.devin/config.local.json`                                               | 否      |
| 全局允许       | `~/.config/devin/config.json` (Windows 上为 `%APPDATA%\devin\config.json`) | 否      |

<div id="mcp-server-level-grants">
  ### MCP 服务器级授权
</div>

当系统就某个特定 MCP 工具请求授权时 (例如 Figma 服务器上的 `list_issues`) ，权限提示还会提供范围更广的服务器级选项：

| 选项                  | 作用                       |
| ------------------- | ------------------------ |
| 允许此工具 (本次会话)        | 在当前会话中授予对此特定工具的访问权限      |
| 始终允许此工具             | 将对此特定工具的授权持久保存到配置中       |
| 允许此服务器上的所有工具 (本次会话) | 在本次会话中授予对此服务器上所有工具的访问权限  |
| 始终允许此服务器上的工具        | 将对此服务器上所有工具的访问权限持久保存到配置中 |

这样，你就可以快速向受信任的 MCP 服务器授予整体访问权限，而无需逐个批准每个工具。

***

<div id="precedence">
  ## 优先级
</div>

当多个权限来源定义了规则时，会按以下优先级进行合并 (从高到低) ：

1. 组织/团队设置 (若为 Enterprise)
2. 会话级授权 (交互式批准)
3. 项目本地配置 (`.devin/config.local.json`)
4. 项目配置 (`.devin/config.json`)
5. 用户配置 (`~/.config/devin/config.json`；Windows 上为 `%APPDATA%\devin\config.json`)

<Warning>
  组织级拒绝规则不能被项目配置或用户配置覆盖。这可确保企业策略得到强制执行。
</Warning>

***

<div id="examples">
  ## 示例
</div>

<div id="minimal-development-setup">
  ### 最小开发设置
</div>

允许常见的只读操作，其他一律提示：

```json theme={null}
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Exec(git status)",
      "Exec(git diff)",
      "Exec(git log)"
    ]
  }
}
```

<div id="full-trust-for-a-project">
  ### 项目完全信任
</div>

自动批准该项目中的大多数操作：

```json theme={null}
{
  "permissions": {
    "allow": [
      "Read(**)",
      "Write(src/**)",
      "Write(tests/**)",
      "Exec(npm)",
      "Exec(git)",
      "Exec(node)"
    ],
    "deny": [
      "Exec(rm -rf)",
      "Exec(sudo)",
      "Write(.env*)"
    ]
  }
}
```

<div id="locked-down-enterprise">
  ### 严格管控的企业版
</div>

仅限特定的安全操作，所有写入前一律提示：

```json theme={null}
{
  "permissions": {
    "allow": [
      "Read(src/**)",
      "Exec(git status)",
      "Exec(git diff)",
      "Exec(npm run lint)"
    ],
    "deny": [
      "Exec(rm)",
      "Exec(sudo)",
      "Write(.env*)"
    ],
    "ask": [
      "Write(**)",
      "exec"
    ]
  }
}
```

<Tip>
  在此示例中，对 `.env*` 的写入会被直接拒绝，所有其他写入都会提示用户，且只有少数只读命令会被自动批准。由于 deny 会先于 ask 进行检查，因此对 `.env*` 的拒绝优先于 `Write(**)` 的 ask 规则。
</Tip>