排障順序與官方參考

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

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

1. 先定位問題層級

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 賬號當前可能有相容問題；地理位置須在官方支援國家/地區列表；如顯示年齡未驗證，需到 Google 賬號年齡驗證完成（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. 許可權和副作用

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

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

如果問題是“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。

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

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

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

7. 反饋前準備什麼

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

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

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

本章自檢

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

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

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

官方來源

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

接下來去哪

真實專案任務選擇

回到任務分級，判斷應該直接執行、拆分執行還是人工處理。

Strict、Sandbox 與 Allowlist

針對許可權和安全問題，回到安全組合章節。

排障順序與官方參考

真實專案任務選擇

Strict、Sandbox 與 Allowlist

本頁目錄