---
title: "排障順序與官方參考"
description: "整理 Antigravity 安裝、workspace、許可權、browser、MCP、模型額度和反饋提交的排障順序。"
verifiedAt: "2026-05-06"
---

Antigravity 出問題時，不要第一反應重灌或換模型。它是 Editor、Agent Manager、Terminal、Browser、Artifacts、MCP 和許可權策略的組合系統，排障要先定位層級。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能按層級判斷 Antigravity 問題來自安裝、workspace、許可權、browser、MCP、模型額度還是專案本身。

## 1. 先定位問題層級

```mermaid
flowchart TD
  Symptom["出現問題"] --> Layer{"先定位層級"}
  Layer --> Install["安裝 / 更新 / Chrome"]
  Layer --> Workspace["Workspace / file access"]
  Layer --> Permission["Strict / sandbox / review policy"]
  Layer --> Browser["Browser profile / allowlist"]
  Layer --> MCP["MCP server / auth / tools"]
  Layer --> Model["Model / quota / plan"]
  Layer --> Project["專案依賴 / 測試命令"]
  Project --> Evidence["保留日誌、diff、artifacts"]
```

先回答“哪一層壞了”，再動手。

## 2. 常見症狀和優先檢查

| 症狀 | 優先檢查 |
| --- | --- |
| 應用無法啟動 | 平臺要求、安裝來源、更新提示、Chrome 是否存在 |
| 登入失敗 / 驗證不透過 | 優先用 `@gmail.com` 個人賬號；Workspace 賬號當前可能有相容問題；地理位置須在 [官方支援國家/地區列表](https://antigravity.google/docs/faq#geo)；如顯示年齡未驗證，需到 [Google 賬號年齡驗證](https://myaccount.google.com/age-verification) 完成（18 歲以下當前不可用） |
| 第三方 agent 用 Antigravity 賬號失敗 | **不能**用 Claude Code / OpenClaw / OpenCode 等第三方工具登入 Antigravity（違反服務條款），需要的話改用 Vertex 或 AI Studio API key |
| Agent 看不到檔案 | 是否開啟正確 workspace，file access 是否被限制 |
| Agent 不跑 terminal 命令 | Terminal Auto Execution、Strict Mode、Sandbox、Request Review |
| 命令因為 sandbox 失敗 | 是否需要 workspace 外寫入或網路，是否單次 Bypass Sandbox |
| Browser 打不開外部 URL | Allowlist / Denylist，strict mode，是否只允許 localhost |
| Browser 沒有登入態 | 官方 separate Chrome profile 設計，預設不繼承日常 Chrome |
| 沒有 screenshot / recording | 是否觸發 Browser Subagent，prompt 是否要求視覺證據 |
| MCP tool 不可用 | server 是否 disabled，tool 是否在 disabledTools，認證是否完成 |
| 模型不可用或中斷 | plan / quota / weekly limit / AI credits overage |
| Agent 改動範圍太大 | prompt 邊界、Planning plan、Artifact Review 是否 Request Review |
| 長任務期間電腦休眠 | Agent 執行時 Antigravity 會**主動阻止電腦休眠**，無需額外配置 |
| 想用 git worktree | **當前不支援 worktrees**（官方 FAQ 明確寫 "Not at the moment"），按單 workspace 工作 |

## 3. 安裝和基礎環境

安裝相關先查：

| 項 | 官方依據 |
| --- | --- |
| 下載來源 | `https://antigravity.google/download` |
| 平臺要求 | Getting Started 文件 |
| 更新提示 | Getting Started 文件說明應用有更新會提示 |
| Chrome 檢測 | Browser 文件說明 Antigravity 使用現有 Chrome application |
| Chrome binary path | Browser 設定裡可指定 |

不要從第三方安裝包、網盤包或所謂漢化包開始排障。

## 4. 許可權和副作用

許可權相關按這個順序看：

1. 是否開啟 Strict Mode。
2. Artifact Review 是否被強制 Request Review。
3. Terminal Auto Execution 是否 Request Review。
4. Sandbox 是否開啟，network 是否允許。
5. Non-Workspace File Access 是否關閉。
6. `.gitignore` 是否被 respect。

> [!IMPORTANT]
> 如果問題是“agent 被卡住”，不要馬上放開所有許可權。先看它請求的具體動作是否合理。

## 5. Browser 排障

Browser 相關重點：

| 問題 | 判斷 |
| --- | --- |
| 打不開頁面 | 是否在 allowlist，是否被 denylist 攔截 |
| 外部 URL 被拒 | allowlist 初始只有 localhost，需要顯式允許 |
| 無法和頁面同時操作 | browser subagent 控制時會顯示 overlay，此時使用者不能互動 |
| 沒登入 | separate browser profile，預設不繼承普通 Chrome 登入態 |
| Chrome 找不到 | 設定 Chrome binary path |

如果任務是前端 UI 驗收，第一輪只允許 `localhost`，不要一開始就開啟真實後臺。

## 6. MCP 排障

MCP 相關重點：

- `~/.gemini/antigravity/mcp_config.json` 是否格式正確。
- `command` 或 `serverUrl` 是否二選一正確配置。
- server 是否被 `disabled: true` 停用。
- 需要的 tool 是否在 `disabledTools` 裡。
- OAuth 是否完成認證。
- token 是否過期或被移除。
- Google ADC 是否已執行 `gcloud auth application-default login`。

<details>
<summary>深讀：為什麼 MCP 排障要先看許可權而不是先看模型</summary>

MCP 把 agent 接到本地工具、資料庫和外部服務。一個 MCP 問題可能來自配置路徑、認證、transport、server 狀態、tool 停用、許可權策略或遠端服務，而不一定是模型能力不夠。

如果 agent 說“不能訪問某工具”，先查 server 是否可用、認證是否完成、tool 是否暴露給模型，再看 prompt 是否表達清楚任務。
</details>

## 7. 反饋前準備什麼

如果需要向產品反饋，先準備這些資訊：

1. Antigravity 版本、系統、平臺。
2. 任務描述和 workspace 型別。
3. 當前模式：Planning / Fast。
4. Strict Mode、Sandbox、Browser allowlist 狀態。
5. MCP server 和 tool 是否相關。
6. 錯誤截圖、terminal output、artifact、recording。
7. 已脫敏的復現步驟。

不要提交金鑰、token、私人路徑、客戶資料或生產後臺截圖。

## 本章自檢

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

1. Browser 打不開外部網頁時，應該先查哪些設定？
2. Terminal 命令被 sandbox 阻止時，為什麼不應該直接永久關閉 sandbox？
3. MCP tool 不可用時，至少要檢查哪些配置和認證項？

透過標準：你能把一個 Antigravity 故障歸類到具體層級，並收集足夠證據再決定是否放權、重試或反饋。

## 官方來源

- [Google Antigravity Getting Started](https://antigravity.google/docs/get-started) —— 官方安裝、平臺要求、更新和基礎導航。
- [Google Antigravity Browser](https://antigravity.google/docs/browser) —— 官方 Chrome、separate profile、browser tools 和 Chrome path 說明。
- [Google Antigravity Allowlist / Denylist](https://antigravity.google/docs/allowlist-denylist) —— 官方 URL 訪問控制說明。
- [Google Antigravity MCP Integration](https://antigravity.google/docs/mcp) —— 官方 MCP 配置、認證和 token 儲存說明。
- [Google Antigravity Plans](https://antigravity.google/docs/plans) —— 官方 quota、AI credits 和當前不支援項說明。
- [Google Antigravity FAQ](https://antigravity.google/docs/faq) —— 官方 FAQ，覆蓋賬號 / 年齡 / 地理可用性 / 第三方 agent 接入 / worktree 等高頻排障問答。
- [Getting Started with Google Antigravity](https://codelabs.developers.google.com/getting-started-google-antigravity) —— 官方 Codelab，用於核對入門流程、功能演示和反饋入口。

## 接下來去哪

<Cards>
  <Card title="真實專案任務選擇" description="回到任務分級，判斷應該直接執行、拆分執行還是人工處理。" href="/zh-Hant/docs/antigravity/official/07-use-cases-reference/00-real-project-selection" />
  <Card title="Strict、Sandbox 與 Allowlist" description="針對許可權和安全問題，回到安全組合章節。" href="/zh-Hant/docs/antigravity/official/05-mcp-permissions-security/01-strict-sandbox-allowlist" />
</Cards>
