---
title: "Strict Mode、Sandbox 與 URL Allowlist"
description: "基於官方文件解釋 Antigravity Strict Mode、Sandbox、URL Allowlist 和檔案訪問邊界。"
verifiedAt: "2026-05-07"
---

Antigravity 的安全控制不是一個開關，而是一組組合：Strict Mode（嚴格模式）、browser allowlist / denylist（瀏覽器白名單 / 黑名單）、terminal sandbox（終端沙箱）、artifact review（產物稽核）、browser JavaScript review（瀏覽器 JS 稽核）、workspace file access（工作區檔案訪問）。真實專案要把這些組合起來，而不是隻開啟某一個設定。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能為真實專案建立“預設不越界、需要副作用就請求確認”的安全配置。

## 1. URL 訪問有 denylist 和 allowlist 兩層

官方 Allowlist / Denylist 文件說明，Browser 使用兩層安全系統控制 URL：

| 層 | 官方說明 | 關鍵點 |
| --- | --- | --- |
| Denylist | 使用 Google Superroots BadUrlsChecker 服務維護和強制執行 | denylist 優先，server 不可用時預設拒絕 |
| Allowlist | 本地可編輯文本檔案，用來顯式信任 URL | 初始只有 localhost，可手動增刪 |

當 browser 嘗試訪問不在 allowlist 的 URL 時，會彈出提示；點選 `always allow` 會把該 URL 加入 allowlist。即使 allowlist 裡有某 URL，只要它在 denylist 中，仍然不能訪問。

> [!IMPORTANT]
> 官方預設 allowlist 只有 localhost，這很合理。前端開發第一階段就應該從 `localhost` 驗證開始。

## 2. Strict Mode 會強制收緊多個設定

官方 Strict Mode 文件說明，開啟 strict mode 後會執行增強安全控制。

| 領域 | Strict Mode 行為 |
| --- | --- |
| Browser URL | external markdown images 和 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 外檔案訪問 |

Strict Mode 的價值是把多個容易漏掉的設定一次性收緊。它適合：

- 真實業務專案。
- 有 secrets 的儲存庫。
- 會訪問外部網頁或瀏覽器的任務。
- 會執行 terminal 命令的任務。
- 多 agent 或長任務場景。

## 3. Sandboxing 限制 terminal 命令執行環境

官方 Sandboxing 文件說明，terminal sandbox 為 Agent 執行的 terminal 命令提供 kernel-level isolation。當前預設停用，但未來可能變化。macOS 使用 Seatbelt，也就是 `sandbox-exec`；Linux 使用 `nsjail`。

開啟後有兩個核心限制：

| 限制 | 官方說明 |
| --- | --- |
| File System | 命令只能寫 workspace 和必要系統位置，避免誤刪或修改專案外檔案 |
| Network Access | 可以單獨用 `Sandbox Allow Network` 控制是否允許聯網 |

如果命令因 sandbox 限制失敗，官方給出兩條處理路徑：

- 在 User Settings 裡永久關閉 sandbox。
- 在 Request Review 模式下，對單個命令選擇 `Bypass Sandbox`。

> [!WARNING]
> Sandbox 失敗不要第一反應永久關閉。先判斷命令是不是真的需要 workspace 外檔案或網路；如果只是一次性需要，優先單命令 bypass。

## 4. Strict Mode 與 Sandbox 的關係

官方 Sandboxing 文件說明，Strict Mode 開啟時，sandbox 會自動啟用，並且網路訪問被拒絕。

```mermaid
flowchart TD
  Task["Agent task"] --> Strict{"Strict Mode"}
  Strict -->|on| Request["Terminal / Browser JS / Artifact Review = Request Review"]
  Strict -->|on| Files["Respect .gitignore + workspace isolation"]
  Strict -->|on| Sandbox["Sandbox on + network denied"]
  Strict -->|off| Custom["按使用者自定義設定執行"]
  Request --> Human["等待人工確認"]
  Sandbox --> Limited["限制檔案系統和網路"]
```

這說明 Strict Mode 更像安全上限：一旦開啟，它會覆蓋一些更寬鬆的設定，強制把高副作用動作拉回人工審查。

## 5. 檔案訪問邊界

Strict Mode 會讓 Agent respect `.gitignore`，並關閉 workspace 外檔案訪問。這個行為對真實專案很重要，因為 `.gitignore` 常常包含：

- `.env`
- 構建產物。
- 本地快取。
- 憑據檔案。
- 私有輸出目錄。

如果你確實需要 agent 讀取 workspace 外檔案，優先做臨時複製或最小路徑授權，不要開放整個 home 目錄。

<details>
<summary>深讀：為什麼 terminal allowlist 在 Strict Mode 下會被忽略</summary>

官方 Strict Mode 文件說明，開啟 strict mode 後 Terminal Auto Execution 被設為 Request Review，並且 terminal allowlist 會被忽略。

這個設計避免了一個常見漏洞：你以為自己進入安全模式，但之前配置過的自動執行命令仍然悄悄執行。Strict Mode 的目標是重新收緊高副作用能力，所以它必須讓 terminal 命令重新回到人工確認。
</details>

## 6. 推薦預設安全組合

真實專案起點可以這樣設：

| 設定 | 推薦 | 為什麼 |
| --- | --- | --- |
| Strict Mode | 開啟 | 一次把多個高副作用動作拉回人工審查，避免設定遺漏 |
| Terminal Sandboxing | 開啟 | 命令預設只能寫 workspace，誤刪專案外檔案不會發生 |
| Sandbox Network Access | 預設關閉，需要時單次放開 | 聯網命令是供應鏈投毒的最大入口 |
| Artifact Review | Request Review | agent 改 artifact 前先停下，人看一眼 diff |
| Browser JavaScript Execution | Request Review | JS 能呼叫任意外部 API，強制審查避免賬號被濫用 |
| Browser URL Allowlist | 只放 `localhost` 和必要官方域名 | 預設 allowlist 只有 localhost，先用本地驗證再擴 |
| Non-Workspace File Access | 關閉 | 配合 Strict Mode 的 `.gitignore` respect，secrets 不會被讀 |
| MCP tools | 按任務啟用，寫操作預設 Ask | MCP 的 token 通常長期有效，寫許可權濫用代價高 |

## 本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

1. Denylist 和 allowlist 誰優先？server 不可用時會怎樣？
2. Strict Mode 會強制改變哪些 terminal、browser、artifact 和 file access 行為？
3. Sandbox 和 Request Review 的職責有什麼不同？

透過標準：你能為一個含 secrets 的真實專案配置 strict mode、安全 URL 範圍和 terminal sandbox，並解釋哪些動作需要人工確認。

## 官方來源

- [Google Antigravity Allowlist / Denylist](https://antigravity.google/docs/allowlist-denylist) —— 官方說明 browser URL denylist、allowlist、localhost 初始狀態和 denylist 優先順序。
- [Google Antigravity Strict Mode](https://antigravity.google/docs/strict-mode) —— 官方說明 strict mode 對 URL、terminal、browser JavaScript、artifact review 和 file access 的強制收緊。
- [Google Antigravity Sandboxing Terminal Commands](https://antigravity.google/docs/sandbox-mode) —— 官方說明 macOS / Linux sandbox、檔案系統限制、網路限制、bypass 和 strict mode 關係。

## 接下來去哪

<Cards>
  <Card title="MCP 整合與許可權邊界" description="回到 MCP server、resources、tools、OAuth 和 disabledTools 的配置審查。" href="/zh-Hant/docs/antigravity/official/05-mcp-permissions-security/00-mcp-integration" />
  <Card title="Browser Subagent 與視覺證據" description="把 URL allowlist 和瀏覽器截圖、錄屏驗收結合起來。" href="/zh-Hant/docs/antigravity/official/03-browser-artifacts/01-browser-subagent-evidence" />
</Cards>
