08 · MCP、权限与 Sandbox 怎么管 · AI 编程教程中文版

Antigravity 的安全问题不是“能不能信任模型”，而是“你给了 agent 哪些工具、哪些路径、哪些 URL、哪些自动执行权限”。只要它能调用 terminal、browser、MCP 和文件系统，就必须把权限当成工程设计。

官方安全相关文档把控制点拆得很细：MCP 有 resources（上下文资源）和 tools（工具）；Browser 有 allowlist / denylist（允许 / 拒绝名单）；Strict Mode（严格模式）会强制多类动作 Request Review（请求人工审阅）；Sandboxing（沙箱）会限制 terminal 命令的文件系统和网络访问。真实项目要组合这些设置，而不是只开一个"安全开关"。

默认策略：先 Ask，再 Allow。先 workspace-only，再最小路径。先本地域名，再外部 URL。先只读 MCP，再写操作。

阅读目标：读完本章，你应该能为一个有 secrets 的真实项目配置 browser、terminal、file、MCP 四类边界。

1. 四个风险面

flowchart TD
    Agent["Antigravity Agent"] --> Terminal["Terminal commands"]
    Agent --> File["File access"]
    Agent --> Browser["Browser URLs / JavaScript"]
    Agent --> MCP["MCP tools"]
    Terminal --> Risk1["删除 / 上传 / 部署 / SSH"]
    File --> Risk2["密钥 / 私人文件 / 非项目目录"]
    Browser --> Risk3["prompt injection / 账号后台"]
    MCP --> Risk4["外部副作用 / 数据读取"]

任何一个风险面过宽，都会让 agent 变成不可控执行器。

2. Allow / Deny / Ask 的组合

模式	适合	风险
Ask by default	真实项目、初期使用、团队环境	速度慢，但边界清楚
Allow low-risk	重复低风险命令	需要定期清理
Deny dangerous	Always Proceed 的兜底	容易漏列危险动作

推荐组合：

默认 Ask
Allow: ls、git status、读取官方文档域名、读取本地 workspace
Deny: rm、ssh、git push、上传命令、凭据目录

这里的关键不是列出所有危险命令，而是先把默认状态设成 Ask。真实项目里，Allow 只适合低副作用、可重复、可解释的动作，例如 rg、git status、测试命令；部署、推送、删除、远程连接、数据库迁移都不应该自动执行。

2.5 Allow / Deny / Ask 的具体写法

上面的"自然语言"例子只是原则说明。在真实 Antigravity 设置里，每条规则必须写成官方的资源字符串格式：

action(target)

官方 Agent Permissions 文档列出 5 种 action：

Action	Target 格式	匹配方式
`command`	`command(prefix)` 或 `command(*)`	按命令前缀匹配。`command(git)` 同时匹配 `git add` / `git commit` 等
`read_file`	`read_file(/abs/path)`	匹配文件或目录下所有内容；必须绝对路径，不支持 `*.go` glob、不支持正则、不支持 `~`
`write_file`	`write_file(/abs/path)`	与 `read_file` 同；写权限隐式包含同路径的读权限
`read_url`	`read_url(domain)` 或 `read_url(*)`	匹配域名 + 所有子域，不匹配 URL 路径
`mcp`	`mcp(server/tool)` / `mcp(server/)` / `mcp()`	按 server 名精确匹配；`server/*` 放通该 server 全部工具

把上面的"自然语言"清单翻译成可写入的真实规则：

# Allow（自动放行）
command(git status)
command(git diff)
command(ls)
read_file(/Users/me/projects/myapp)
read_url(antigravity.google)

# Deny（永远拦截）
command(rm)
command(sudo)
command(ssh)
write_file(/Users/me/.ssh)
write_file(/Users/me/.aws)

# Ask（每次问）
command(*)
mcp(*)

三个高频踩坑：① read_file / write_file 不能写 ~/projects 或 *.env 这类 shell 风格——必须绝对路径；② command(git) 会匹配所有 git 子命令（包括 git push），如果要细，写 command(git status)、command(git diff)；③ write_file(/some/path) 会隐式给同路径开 read_file，不要为了"只读"反而把目录写成 write_file。

3. Strict Mode 的作用

官方 Strict Mode 文档说明，开启后会强制收紧这些行为：

领域	Strict Mode 行为
Browser URL	外部 markdown 图片和 Read URL tool 受 allowlist / denylist 控制
Terminal Auto Execution	强制 Request Review，忽略 terminal allowlist
Browser JavaScript Execution	强制 Request Review
Artifact Review	强制 Request Review
File System Access	respect `.gitignore`，禁用 workspace 外文件访问

这对真实项目很有价值，因为它会覆盖之前过宽的自动执行设置。尤其是 terminal allowlist 被忽略这一点，可以防止你以为进入安全模式，实际上旧 allowlist 还在放行命令。

建议起点：

Strict Mode: on
Artifact Review: Request Review
Terminal Auto Execution: Request Review
Browser JavaScript Execution: Request Review
Non-Workspace File Access: off

4. Terminal sandbox

Sandbox 是运行限制，不是授权策略。即使启用 sandbox，也不能随便允许：

删除命令
部署命令
上传命令
连接远端
修改系统配置
写 workspace 外目录

Permission 解决“能不能做”，sandbox 解决“做的时候被限制在哪”。两者都要有。

官方 Sandboxing 文档说明，terminal sandbox 为 Agent 执行的命令提供 kernel-level isolation。macOS 使用 Seatbelt，也就是 sandbox-exec；Linux 使用 nsjail。启用后可以限制命令写 workspace 外文件，也可以单独控制网络访问。

Sandbox 当前默认关闭（官方原话："Sandboxing is currently disabled by default, but this may change in future releases."）。也就是说，如果你只是开了 Antigravity 没动设置，agent 跑命令是没有 kernel 层隔离的。商业项目第一件事就是去 Antigravity User Settings 打开 "Enable Terminal Sandboxing"，并按需开/关 "Sandbox Allow Network"。

反过来，开启 Strict Mode 时官方会自动激活 sandbox 并默认禁用网络——这是 Strict Mode 的副作用之一，不需要单独再开。

如果命令被 sandbox 拦住，不要第一反应永久关闭 sandbox。先判断它是否真的需要：

情况	推荐处理
测试脚本写 workspace 外缓存	优先改测试或临时目录
构建需要联网下载	单次允许网络，检查 lockfile
部署命令被拦	不自动部署，改成人工执行
读取 home 目录配置	改成复制必要文件到 workspace
确认只是一次性例外	Request Review 下单命令 bypass

5. File access

默认 workspace-only 是正确的。非 workspace 文件访问只适合非常明确的临时任务，例如读取一个指定日志文件。不要授权：

路径	原因
用户家目录	范围过大
凭据目录	token 和密钥风险
云同步根目录	私人数据和历史文件
系统配置目录	破坏环境
其他项目根目录	任务边界混乱

Strict Mode 会 respect .gitignore，这点很重要。.gitignore 经常包含 .env、构建产物、缓存、凭据、私有输出目录。不要为了“让 agent 看更多上下文”就让它读这些文件。

6. Browser allowlist

浏览器能力必须按域名限制。常用策略：

本地验证只 allow localhost。
查官方资料只 allow 官方域名。
社区网页临时 allow。
登录后台不默认 allow 自动点击。
任务完成后清理临时域名。

官方 Allowlist / Denylist 文档说明，Browser 有两层 URL 控制：server-side denylist（云端拒绝名单，由 Google Superroots BadUrlsChecker 服务维护）和本地 allowlist（一份你可以手动编辑的本地文本文件）。denylist 优先，denylist 服务不可用时默认拒绝访问；allowlist 初始只有 localhost。

实际触发时有三种处理路径：

触发场景	你能做什么
agent 想访问非 allowlist URL	弹窗给 Always allow 按钮——点了就把这条 URL 加进 allowlist
想批量预先放行	直接编辑 allowlist 本地文本文件（新增 / 删除 URL）
URL 在 denylist 里	即使 allowlist 添了也无效——denylist 永远优先

实操 prompt 可以写：

Browser 只允许访问：
1. http://localhost:3000
2. https://antigravity.google/docs

如果遇到登录、支付、广告后台、云控制台或外部跳转，立刻停止并报告。
不要点击 always allow，除非我明确批准。

7. MCP 最小开放

MCP 的风险在于 tool 的外部副作用。一个 MCP server 可能看起来只是“查资料”，实际也可能写文件、发请求、创建资源。

治理清单：

先列出 server 和 tool。
写操作默认 Ask。
只读工具也要限制域名或资源范围。
不把大型 MCP 全局常驻。
每个 workspace 单独决定 MCP。
团队项目把 MCP 配置纳入审查。

官方 MCP 文档把能力分成两类：

MCP 能力	价值	风险
Context Resources	读取数据库 schema、日志、文档、上下文	泄露业务数据、客户数据、内部日志
Custom Tools	创建 Linear issue、搜索 GitHub/Notion、调用外部服务	触发写操作、创建资源、改远端状态

Antigravity 安装 MCP server 有两种方式：① 通过内置 MCP Store（编辑器 agent panel 的 ... 下拉 → MCP Store → Browse & Install），覆盖 GitHub / Linear / Notion / Stripe / Supabase / Figma 等 30+ 官方接入；② 自己写自定义 server 配置。两者最终都落到同一份配置文件：

~/.gemini/antigravity/mcp_config.json

每个 server 条目支持的关键字段：

字段	作用
`command` 或 `serverUrl`	stdio 二选一传输；前者本地可执行文件，后者远程 HTTP server
`args` / `env` / `cwd`	启动命令参数、环境变量、工作目录（仅 stdio）
`headers`	远程 server 的自定义 HTTP 头（如 `Authorization: Bearer ...`）
`authProviderType`	认证提供方，`"google_credentials"` 走 Google ADC（`gcloud auth application-default login`）
`oauth.clientId` / `clientSecret`	不支持 OAuth 动态注册的 server 用这个手动配
`disabled`	临时停用整个 server，但保留配置
`disabledTools`	数组，指名禁用 server 上的某些 tools，其余可用

商业项目里，不要因为需要某个只读 resource 就放开整个 server 的所有 tools。能写 GitHub、Stripe、PayPal、数据库、云服务、CMS 的 tool 默认在 disabledTools 里列上，再用 Allow/Deny/Ask 配 mcp(server/tool) 资源字符串做第二层闸门。

8. 按任务放权

最稳的方式不是一次性设置完，而是按任务放权：

阶段	权限
只读分析	read workspace
单文件小改	write 指定目录或文件
本地验证	command(dev server) + read localhost
UI 录屏	browser allowlist
发布前	只生成 checklist，不自动部署

一个安全 prompt 可以这样写：

先只读分析，不要修改文件。
只允许读取当前 workspace，不允许读取 workspace 外文件。
如果需要 terminal、browser 或 MCP，请先说明目的、命令/URL/tool 名称和风险。
本轮禁止 git push、部署、删除文件、写外部系统。

9. 商业项目默认配置

控制项	默认建议
Strict Mode	开启
Terminal Sandboxing	开启
Sandbox Network	默认关闭，需要时单次批准
Terminal Auto Execution	Request Review
Artifact Review	Request Review
Browser JavaScript	Request Review
Browser Allowlist	`localhost` + 必要官方域名
Non-Workspace File Access	关闭
MCP	workspace 级配置，写操作默认禁用
Secrets	不读、不贴、不写入仓库

这套设置会慢一点，但可解释、可审计、可回退。商业级上线前，速度不是第一优先级，边界清楚才是。

本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

Strict Mode 会强制收紧哪些设置？
Sandbox 和 Request Review 分别解决什么问题？
disabledTools 为什么比“装不装某个 MCP server”更细？

通过标准：你能为一个真实项目写出 browser allowlist、terminal sandbox、MCP disabledTools 和 workspace-only 文件访问策略。

官方来源

Google Antigravity MCP Integration - 官方说明 MCP Store、自定义 server、resources、tools、OAuth、headers、disabled 和 disabledTools。
Google Antigravity Strict Mode - 官方说明 strict mode 对 terminal、browser、artifact review 和 file access 的强制收紧。
Google Antigravity Allowlist / Denylist - 官方说明 browser URL denylist、allowlist、localhost 初始状态和 denylist 优先级。
Google Antigravity Sandboxing Terminal Commands - 官方说明 terminal sandbox、文件系统限制、网络限制、单命令 bypass 和 strict mode 关系。

08 · MCP、权限与 Sandbox 怎么管