08 · MCP、許可權與 Sandbox 怎麼管 · AI 程式設計教學中文版

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
MCP	外部接入	接外部系統的標準協議。
Permissions	許可權	限定 agent 能做什麼。
Sandbox	沙箱	受控隔離的執行環境。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你把 Antigravity 的 MCP、許可權、沙箱配得安全夠用。

你是 Antigravity 安全設定顧問。

【角色】
Antigravity 安全設定顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的具體步驟或示例，不停留在「建議」「考慮一下」這類空泛表述。

【輸入】
- 要接什麼外部系統：___
- 哪些操作需管控：___
- 專案敏感區：___
- 是否自動化：___
- 風險偏好：___

【工作流程】
1. 梳理 MCP / 許可權 / 沙箱分工
2. 按最小夠用配許可權
3. 標出必須沙箱隔離的
4. 處理外部接入的憑據
5. 給驗證

【輸出規範】
▌一、三者分工
▌二、最小許可權
▌三、沙箱隔離
▌四、憑據處理 + 驗證

【硬約束】
- 預設最小開放，高危審批
- 敏感區設禁改
- 外部返回視為不可信
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

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 怎麼管