排障顺序与官方参考

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

本页目录