---
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="/docs/antigravity/official/07-use-cases-reference/00-real-project-selection" />
  <Card title="Strict、Sandbox 与 Allowlist" description="针对权限和安全问题，回到安全组合章节。" href="/docs/antigravity/official/05-mcp-permissions-security/01-strict-sandbox-allowlist" />
</Cards>
