Gemini 中文文档Agent 权限控制 (Agent Permissions)
Antigravity 采用一套强大且统一的权限引擎，在启用自主工作流的同时保护您的环境安全。Agent 执行的每个敏感操作均被表示为一个格式为 action(target) 的权限资源。
权限是在三个不同的访问列表中进行评估的：
- 拒绝 (Deny)：操作被立即拦截。
- 询问 (Ask)：Agent 会暂停并在继续操作前提示您明确批准。
- 允许 (Allow)：操作会被自动批准，无需提示。
[!WARNING] 优先级规则：冲突的规则会严格按照优先级顺序进行评估：Deny > Ask > Allow。例如，如果您在 Ask 列表中配置了
command(*)，在 Allow 列表中配置了command(git)，那么 Ask 规则将处于优先地位，在执行每个命令前都会提示您。
支持的操作与匹配规则 (Supported Actions & Matching Rules)
| 操作 (Action) | 目标格式 (Target Format) | 匹配行为 (Matching Behavior) | 默认回退 (Default Fallback) |
|---|---|---|---|
| read_file | read_file(/path)、read_file(dir) 或 read_file(*) | 匹配绝对路径或相对于项目工作区根目录的路径。授予对所包含的所有文件/文件夹的递归读取权限。使用 read_file(*) 匹配系统上的所有文件。 | 询问 Ask（在工作区内自动允许） |
| write_file | write_file(/path) 或 write_file(*) | 与 read_file 相同。隐式授予对完全相同的目标路径的 read_file 权限。 | 询问 Ask（在工作区内自动允许） |
| read_url | read_url(domain) 或 read_url(*) | 匹配主机名和子域名（例如，google.com 覆盖 mail.google.com）。忽略 URL 路径片段。使用 read_url(*) 匹配任何域名。 | 询问 Ask |
| execute_url | execute_url(domain) 或 execute_url(*) | 触发网页元素（如点击、输入）或在某个域名上驱动交互式的浏览器工作流。 | 询问 Ask |
| command | command(prefix)、command(regex) 或 command(*) | 按精确的单词/标记前缀匹配。每个由空格分隔的标记都作为锚定的正则表达式（^(?:pattern)$）进行评估。例如，command(npm run (build.*)) 匹配 npm run build 和 npm run build-prod。 | 询问 Ask |
| unsandboxed | unsandboxed(prefix)、unsandboxed(regex) 或 unsandboxed(*) | 按精确的单词/标记前缀匹配命令。匹配此授权的命令将在容器隔离之外执行（仅在启用终端沙箱时适用）。 | 询问 Ask |
| mcp | mcp(server/tool)、mcp(server/*) 或 mcp(*) | 匹配精确的 MCP 工具或指定服务器上的所有工具（同样适用于本地 MCP 服务器和远程连接）。使用 mcp(*) 匹配任何工具。 | 询问 Ask |
[!NOTE] 全局通配符语法：在所有受支持的操作类型（如
read_file()、command()、mcp()等）中，传入全局通配符*将匹配该整个操作命名空间下的所有目标。
深入理解平台中的 read_url 与 execute_url
read_url 权限控制着 Antigravity 三个不同区域的出站网络连接：
read_url工具：当 Agent 使用内部的read_url_content工具获取网页 Markdown 以进行研究时，它会检查您的read_url授权。- 浏览器子 Agent 与工具：当驱动 Chrome 会话时，
read_url授权加载和查看目标域名。然而，交互式 UI 操作（点击按钮、输入文本）则由execute_url独立控制。 - 终端沙箱：在沙箱模式下，任何在
read_url下被授权的域名都会被直接编译进容器的出站网络允许列表（AllowedDomains），允许curl或npm等命令连接到受信任的主机。
跨平台命令与路径匹配
无论您在 macOS、Linux 还是 Windows 上开发，Antigravity 都能确保您的权限规则完美运行。在 macOS 和 Linux 上，路径使用标准正斜杠 (/)。在 Windows 上，Antigravity 在规则评估前会自动归一化路径，去除盘符（如 C:）并将所有反斜杠 (\) 转换为正斜杠 (/)。
隐式权限规则
- 写蕴含读：在某个路径上允许
write_file会自动授予对该路径的read_file权限。 - 拒绝读蕴含拒绝写：拒绝在某个路径上的
read_file权限会立即拦截该路径上的write_file操作。
交互式权限提示
当 Agent 遇到需要批准的操作（询问 Ask 模式）时，您的编辑器中会弹出一个交互式卡片。在为文件、URL 或 MCP 权限点击“允许”之前，您可以在提示卡片中直接编辑目标字符串以扩大授予的范围（例如，将单个文件请求如 /project/file.txt 扩大至自动添加父目录 /project）。Antigravity 会验证您编辑的目标是否安全地涵盖了该操作，并在该交互轮次的剩余时间内应用扩大后的授权，从而避免针对相关操作的重复提示。（注：终端命令不支持范围编辑）。
终端沙箱 (预览版)
当启用沙箱（sandbox）时，权限授予也适用于终端命令：
- 在
read_file下授权的路径会动态填充到沙箱的只读文件系统允许列表中。 - 在
write_file下授权的路径会动态填充到沙箱的读写文件系统允许列表中。 - 在
read_url下授权的域名定义了出站网络访问策略。
[!NOTE] 沙箱可用性：终端沙箱目前在 macOS / Linux 上处于预览阶段，Windows 版本即将推出。
默认系统行为与安全护栏
当某个操作未在您的允许、拒绝或询问列表中显式列出时，Antigravity 会回退到安全的系统默认行为：
- 网页浏览默认为询问 (Ask)：
read_url和execute_url的操作默认回退为 Ask。在 Agent 导航到或操作任何网页前，除非配置了允许规则，否则它将暂停并提示您明确批准。 - 工作区被自动允许：在标准操作下，读取和写入您活动项目目录内的文件是被自动允许的。所有其他未配置的操作（如命令、MCP、网页交互、工作区外的文件）均默认回退为询问 (Ask)。
配置示例
允许列表 (Allow list) —— 无需提示直接运行的操作：
command(git) # 允许标准 git 命令
command(npm run (build|lint|test)) # 通过正则允许安全的 npm 脚本
unsandboxed(git push) # 允许在沙箱外进行 git push
read_file(/var/log/app) # 读取外部日志路径
write_file(src/) # 编辑相对路径下的 src/ 文件夹
read_url(google.com) # 获取 Google 子域名
mcp(linter/*) # 运行 linter MCP 工具拒绝列表 (Deny list) —— 永久拦截的操作：
command(rm -rf) # 拦截破坏性的删除操作
command(curl .*) # 拦截未审查的 curl 下载
command(sudo) # 拦截 sudo 提权
write_file(.git/) # 保护 Git 历史记录
write_file(/home/user/.ssh) # 保护 SSH 密钥询问列表 (Ask list) —— 暂停等待人工确认的操作：
command(*) # 提示所有终端命令
execute_url(aws.amazon.com) # 提示 AWS 控制台操作
mcp(sql/execute_mutation) # 提示修改 SQL 的查询