Gemini CLI → Antigravity CLI 迁移

Google 于 2026 年 5 月 19 日 宣布 Gemini CLI 将过渡为 Antigravity CLI。对于付费企业客户，一切保持不变。而对于所有使用 Google AI Pro、Ultra 或免费 Gemini Code Assist 个人账户的用户，Gemini CLI 将于 2026 年 6 月 18 日停止服务。这是一份可以在一个晚上完成的迁移计划，并包含在关键工作流中断时的回滚方案。

1. 公告内容

两家 Google 渠道在同一天发布了这一过渡消息。 Google Developers Blog 制定了时间表。 X 上的 @geminicli 账号 承诺为个人层级用户提供 30 天的迁移窗口期，并明确企业客户无需进行任何操作。

Google DeepMind 通过另一个官方账号阐述了更宏观的愿景 —

官方 迁移文档 位于 antigravity.google/docs/gcli-migration 是文件逐一映射的权威指南。以下步骤将按顺序进行说明，并指出文档中未明确提及的注意事项。

2. 核心摘要 (TL;DR)

• 截止日期： 2026 年 6 月 18 日（个人层级）
• 受影响范围： Google AI Pro, Google AI Ultra, 免费版 Gemini Code Assist
• 不受影响： Code Assist Standard / Enterprise，付费 Gemini API 密钥
• 替代方案： Antigravity CLI (二进制文件： agy)
• 一键迁移： agy plugin import gemini
• 需要手动移动： .gemini/skills/ → .agents/skills/，MCP 配置移动至 mcp_config.json
• 字段重命名： 远程 MCP url → serverUrl
• 上下文文件： GEMINI.md 和 AGENTS.md 保持运行且不作更改
• 并行安装： 安全 — gemini 和 agy 共存
• 本指南阅读时间： 14 分钟；实际操作时间：约 45 分钟

3. 时间线

4. 受影响人群

在继续阅读前，请先进行快速自查：

• 您使用个人 Google 账号登录 Gemini CLI。 您将受到影响 — 这是免费/个人用户流程。
• 您付费订阅了 Google AI Pro 或 Google AI Ultra。 您将受到影响。Antigravity CLI 使用相同的订阅。
• 您使用的是个人版 Gemini Code Assist（免费层级）。 您将受到影响。Gemini CLI 和 Code Assist IDE 扩展都将于 6 月 18 日停止服务。
• 您使用付费的 Gemini API 密钥对 Gemini CLI 进行身份验证。 您 不 受影响。Gemini CLI 将继续为付费 API 密钥用户提供服务。
• 您的组织拥有 Gemini Code Assist Standard 或 Enterprise 许可证。 您 不 受影响。企业级 CLI 访问权限保持不变。

5. 企业例外情况

根据 Google Developers Blog： “如果您的组织通过 Gemini Code Assist Standard 或 Enterprise 许可使用 Gemini CLI 或我们的 IDE 扩展，或者如果您的组织通过 Google Cloud 使用 Gemini Code Assist for GitHub，您的访问权限将保持不变。我们将继续支持 Gemini CLI 和 Gemini Code Assist，并提供对最新 Gemini 模型及其他更新的访问。”

具体而言，企业保留三个选项：

• 保留 Standard / Enterprise 许可下的 Gemini CLI — 无需迁移。
• 保留付费 API 密钥下的 Gemini CLI — 无需迁移。
• 同时采用 Antigravity CLI，并使用 GCP 项目凭据。有关 GCP 项目关联的详细信息，请参阅官方企业页面。

如果您是代表他人阅读此内容的企业管理员，对您而言核心要点是 规划试点，不要在组织内进行恐慌性迁移。 截止日期仅约束个人用户层级（consumer tier）。

6. 迁移前检查清单

在开始迁移之前，请确认：

• 您的机器可以安装 Go 分发的二进制文件（agy）— 您拥有 curl、irm 或管理员 shell 访问权限。
• 您知道当前 Gemini CLI 使用的是哪个 Google 账号（迁移将沿用该账号）。
• 您可以列出已安装的 Gemini CLI 扩展（gemini extension list）。
• 您的 ~/.gemini/ 目录完好无损（其中包含您的全局规则和技能）。
• 包含自定义 .gemini/ 文件夹的工作区项目已被识别 — 每个文件夹都需要手动移动以用于工作区范围的技能。
• 如果你通过 CI 或 cron 编写 Gemini CLI 调用脚本，你需要制定一个切换二进制文件名称的计划（gemini → agy）以及身份验证流程。

7. 步骤 1：安装 Antigravity CLI

每个平台对应一个安装命令，详见官方 README：

# macOS / Linux
curl -fsSL https://antigravity.google/cli/install.sh | bash

# Windows PowerShell
irm https://antigravity.google/cli/install.ps1 | iex

# Windows CMD
curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd

安装完成后，进行验证：

agy --version
# expected: a version string is printed

二进制文件命名为 agy，而非 antigravity。如果你编写了 CLI 调用脚本，这就是你需要重命名的地方。Gemini CLI 的 gemini二进制文件保持不变；两者共存。

8. 步骤 2：身份验证

首次运行将开启身份验证流程。有两种变体：

• 本地终端。 运行 agy。您的默认浏览器将打开。请使用与 Gemini CLI 相同的 Google 账号登录。Token 将存储在您的系统密钥环中。
• 远程 / SSH。 运行 agy。CLI 会检测到 SSH 会话并打印授权 URL。在本地机器上打开该链接，完成 OAuth 流程，SSH 会话即可获取 Token。这曾是早期 Gemini CLI 的一个显著痛点 — 现在已得到原生支持。
• 企业版。 在配置过程中，您可以连接 GCP 项目。随后的调用将计入该项目的账单。官方企业文档涵盖了具体细节。

9. 步骤 3：导入插件

On first launch, Antigravity CLI prompts to migrate Gemini CLI extensions to Antigravity plugins. If you skip the prompt or are installing on a fresh machine, run the import explicitly:

agy plugin import gemini

官方迁移文档中的示例输出，演示了多组件扩展的迁移过程：

[ok]    conductor
          - skills      : skipped (not found)
          - agents      : skipped (not found)
          ✔ commands    : 6 processed (converted to skills)
          - mcpServers  : skipped (not found)
          - hooks       : skipped (not found)
[ok]    google-workspace
          ✔ skills      : 6 processed
          - agents      : skipped (not found)
          ✔ commands    : 4 processed (converted to skills)
          ✔ mcpServers  : 1 processed
          - hooks       : skipped (not found)

10. 步骤 4：迁移 MCP 配置

Gemini CLI 将 MCP 服务器配置内联存储在 settings.json。Antigravity CLI 使用独立的文件。请迁移它们：

并且在 JSON 本身中有一个字段重命名：

// Gemini CLI (settings.json)
{
  "mcpServers": {
    "my-remote-mcp": {
      "url": "https://example.com/mcp"   // or the deprecated "httpUrl"
    }
  }
}

// Antigravity CLI (mcp_config.json)
{
  "my-remote-mcp": {
    "serverUrl": "https://example.com/mcp"
  }
}

如果你直接复制 url 而不进行重命名，远程 MCP 服务器将静默失败。包含 command + args 的本地 MCP 服务器条目不需要重命名。有关 MCP 配置的背景信息，请参阅我们的 MCP 教程。

11. 第 5 步：移动工作区技能

位于 ~/.gemini/skills/ 下的全局技能会自动加载 — 无需任何操作。位于 .gemini/skills/ 下的工作区技能必须移动到 .agents/skills/：

# Per project, from the workspace root:
mkdir -p .agents
git mv .gemini/skills .agents/skills
# Or, if not in git:
mv .gemini/skills .agents/skills

如果工作区已经有一个 .agents/skills/ 文件夹（Gemini CLI 文档允许的双位置情况），请保留该文件夹并删除 .gemini/skills/ 副本。有关编写模式，请参阅我们的 Antigravity 技能设置指南.

12. 第 6 步：验证 Hooks 和 Context

在确认迁移完成之前，需要确认以下两点：

• Context 文件正常加载。 GEMINI.md 以及 AGENTS.md （位于工作区中），加上 ~/.gemini/GEMINI.md （全局），所有这些都应保持原样正常工作。开启一个会话并让 Agent 背诵你文件中的一条已知规则。
• JSON hooks 正常触发。 如果你针对 Antigravity 2.0 或 Gemini CLI 编写了 JSON hooks，它们在 Antigravity CLI 的相同生命周期时刻依然适用。修改一个文件或运行一个示例工具调用，以确认你已知的 hook 确实触发了。

关于规则模式，请参阅我们的 规则示例 和 GEMINI.md 系统提示词指南。

13. 第 7 步：真实任务验证

这是绝对不能跳过的一步。挑选一个你昨天在 Gemini CLI 中完成的任务 — 例如重构、研究会话或多文件编辑 — 并在同一个仓库中通过 Antigravity CLI 运行它。对比一下：

• Agent 是否在相同的步骤中调用了相同的工具？
• 你的 skills slash-command 是否在正确的位置触发？
• MCP-server 调用是否触发？（注意这里的静默 serverUrl 失败情况。）
• 上下文文件（GEMINI.md, AGENTS.md）是否以相同的方式引导行为？
• hooks 是否在预期的生命周期时刻被调用？

在代表性任务上花费 20 到 30 分钟，就能获得 90% 所需的反馈信号。如果一切都能复现，你就大功告成了。如果某处出现问题，请提交反馈，并在修复前该工作流回退到使用 Gemini CLI。

14. 回滚计划

Antigravity CLI 和 Gemini CLI 在同一台机器上共存。它们是独立的二进制文件（agy vs gemini），拥有独立的配置树（~/.gemini/antigravity-cli/ 与之并列 ~/.gemini/），以及独立的身份验证流程。在 2026 年 6 月 18 日之前，针对任何特定工作流的回滚操作非常简单： 继续运行 gemini 来处理该任务。

6 月 18 日之后，回滚选项将缩小为：

• 升级到企业版许可证（Gemini Code Assist Standard / Enterprise）。
• 切换到付费的 Gemini API 密钥。
• 针对受影响的工作流，使用 Antigravity 2.0（GUI 版本）而非 CLI。
• 完全切换到其他代理 CLI。请参阅我们的 替代方案综述 以了解当前行业现状。

15. 变更一览

16. 常见问题 (FAQ)

17. 结论

如果你今天只打算做一件事：请在你最常使用 Gemini CLI 的机器上安装 Antigravity CLI。完成这一步后，后续的其他操作都会轻松得多。

来源

• Google Developers Blog — 重要更新：将 Gemini CLI 迁移至 Antigravity CLI
• X 上的 @geminicli — 迁移公告
• Antigravity CLI — 从 Gemini CLI 迁移（官方文档）
• Google Antigravity CLI 介绍 — antigravity.google
• Google Antigravity 2.0 介绍 — antigravity.google
• Antigravity CLI 概览 — 官方文档
• google-antigravity/antigravity-cli — GitHub 仓库