---
url: /antigravity/cli-permissions.md
description: 保护您的本地工作站、限制绝对文件路径、配置自定义的 允许/拒绝/询问 策略，并管理交互式审批。
---

# 权限管理 (Permissions)

保护您的本地工作站、限制绝对文件路径、配置自定义的 允许/拒绝/询问 策略，并管理交互式审批。

## 细粒度权限 (Fine-grained permissions)

为了在启用自主工作流的同时保护您的工作站，Antigravity CLI 集成了一个强大的**细粒度权限引擎 (Fine-Grained Permissions Engine)**。Agent 执行的每个敏感操作都表示为一个格式为 `action(target)` 的权限资源。

权限是通过您全局设置中配置的三个不同访问列表来评估的：

```text
~/.gemini/antigravity-cli/settings.json
deny：该操作将被立即拦截。
ask：Agent 会暂停并提示您进行明确批准，然后才能继续。
allow：该操作将被自动批准，无需提示。
```

> \[!WARNING]
> **优先级规则**：冲突的规则会严格按照优先级顺序进行评估：`Deny > Ask > Allow`。例如，如果您在 `ask` 列表中配置了 `command(*)`，并在 `allow` 列表中配置了 `command(git)`，则 `ask` 规则优先，在每个命令执行前都会提示。

## 支持的操作与匹配规则 (Supported actions & matching rules)

细粒度权限遵循标准的模式语法：

```text
action(target)
```

支持的操作、目标格式规范和匹配算法如下：

| 操作 (Action) | 目标格式 (Target Format) | 匹配行为 (Matching Behavior) | 默认回退 (Default Fallback) |
| :--- | :--- | :--- | :--- |
| **read\_file** | `read_file(/path)`、`read_file(dir)` 或 `read_file(*)` | 匹配绝对路径或相对于工作空间根目录的路径。递归授予对其中包含的所有文件/文件夹的读取权限。`read_file(*)` 匹配系统上的所有文件。 | 询问 (在工作空间内自动允许) |
| **write\_file** | `write_file(/path)` 或 `write_file(*)` | 与 `read_file` 相同。隐式授予对完全相同目标路径的 `read_file` 权限。 | 询问 (在工作空间内自动允许) |
| **read\_url** | `read_url(domain)` 或 `read_url(*)` | 匹配主机名和子域名（例如：`google.com` 覆盖 `mail.google.com`）。忽略 URL 路径片段。`read_url(*)` 匹配任何域名。 | 询问 |
| **execute\_url** | `execute_url(domain)` 或 `execute_url(*)` | 触发网页元素（点击、输入）或在一个域名上驱动交互式的浏览器工作流。 | 询问 |
| **command** | `command(prefix)`、`command(regex)` 或 `command(*)` | 通过精确的单词/Token 前缀匹配命令。每个由空格分隔的 Token 都会被评估为一个有锚定的正则表达式（`^(?:pattern)$`）。例如，`command(npm run (build\|lint\|test))` 会匹配 `npm run build` 和 `npm run test`。 | 询问 |
| **unsandboxed** | `unsandboxed(prefix)` 或 `unsandboxed(*)` | 通过精确的单词/Token 前缀匹配命令。匹配此授予的命令将在容器隔离之外执行（仅在启用终端沙箱时适用）。 | 询问 |
| **mcp** | `mcp(server/tool)` 或 `mcp(*)` | 匹配精确的 MCP 工具或指定服务端上的所有工具（适用于本地 MCP 服务端和远程连接）。`mcp(*)` 匹配任何工具。 | 询问 |

### 全局通配符语法

在所有支持的操作类型中，传入全局通配符 `*`（例如 `read_file(*)`、`command(*)`、`mcp(*)`）将匹配该操作命名空间下的所有目标。

### 隐式权限规则

* **写隐含读 (Write implies Read)**：允许对某个路径执行 `write_file` 会自动授予对该路径的 `read_file` 权限。
* **拒读隐含拒写 (Deny Read implies Deny Write)**：拒绝某个路径的 `read_file` 权限会立即拦截对该路径的 `write_file` 权限。

### 跨平台路径规范化 (Cross-platform path normalization)

无论您是在 macOS、Linux 还是 Windows 上进行开发，Jetski 都能确保您的权限规则无缝运行。在 macOS 和 Linux 上，路径使用标准正斜杠 (`/`)。在 Windows 上，Jetski 在规则评估之前会自动规范化路径，移除盘符（例如 `C:`）并将所有反斜杠 (`\`) 转换为正斜杠 (`/`)。

## 默认系统行为与安全护栏 (Default system behaviors & guardrails)

当某项操作未显式列在您的 `allow`、`deny` 或 `ask` 列表中时，系统将回退到安全系统默认设置：

* **工作空间自动允许**：在标准操作中，自动允许读取和写入您当前活跃项目目录中的文件。
* **网页浏览默认询问**：`read_url` 和 `execute_url` 的操作默认设为询问 (Ask)。在 Agent 导航到或在任何网页上操作之前，除非配置了 `allow` 规则，否则它会暂停并提示您进行审批。
* **未配置的操作默认询问**：所有其他未配置的操作（如 `command`、`mcp`、`execute_url`、非工作空间文件）默认设为询问 (Ask)。

## 交互式权限提示 (Interactive permission prompts)

当 Agent 遇到需要审批的操作时（询问模式），TUI 中会出现一个交互式提示卡片。

在确认允许文件、URL 或 MCP 权限之前，您可以直接在提示卡片中编辑目标字符串，以扩大授予的范围（例如，将对单个文件 `/project/file.txt` 的请求扩大为父目录 `/project`）。CLI 会验证您编辑后的目标是否能够安全覆盖该操作，并在该轮次的其余时间内应用扩大的授权，从而防止对相关操作进行重复提示。（注意：终端命令不支持范围编辑）。

## 配置示例 (Configuration examples)

将这些规则添加到您的 `~/.gemini/antigravity-cli/settings.json` 文件中：

```json
{
  "permissions": {
    "allow": [
      "command(git)",
      "command(npm run (build|lint|test))",
      "unsandboxed(git push)",
      "read_file(/var/log/app)",
      "write_file(src/)",
      "read_url(google.com)",
      "mcp(linter/*)"
    ],
    "deny": [
      "command(rm -rf)",
      "command(curl .*)",
      "command(sudo)",
      "write_file(.git/)",
      "write_file(/home/user/.ssh)"
    ],
    "ask": [
      "command(*)",
      "execute_url(aws.amazon.com)",
      "mcp(sql/execute_mutation)"
    ]
  }
}
```

## 参见 (See also)

* **沙箱自定义**：强制执行系统级的容器隔离边界。
* **插件与技能**：创建您自己的自定义技能和斜杠命令。
* **设置、渲染与键绑定**：自定义键盘快捷键和缓冲区。