# 從 Gemini CLI 遷移至 Antigravity CLI：指南

> 安裝 agy、遷移設定、外掛程式與環境變數；檢查方式、常見錯誤與區域限制。

Source: https://ailoot.ai/blog/zh-hant-tw/gemini-cli-to-antigravity-cli-migration/
Canonical: https://ailoot.ai/blog/zh-hant-tw/gemini-cli-to-antigravity-cli-migration/
Language: zh-Hant-TW
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-097
Revision: sha256-dd43517fb6cba087a076e850c5a86504f7329ff31655d2254258a986b98002bd


2026 年 5 月 19 日，Google 宣布將於 6 月 18 日停止舊版 Gemini CLI 在 Free、Pro 和 Ultra 所有方案上的服務。本指南發布兩週後，`gemini` 命令將停止處理請求。若要繼續使用 Google 工具，唯一方法是使用 `agy` 命令從 Gemini CLI 遷移至 Antigravity CLI。`agy` 以 Go 開發，啟動速度快了數十倍。

如果你有任何程式正在使用 Gemini CLI，例如 CI 指令碼、每晚執行的 cron 工作或 Gemini Code Assist IDE 擴充功能，本指南將說明如何在一個晚上完成遷移，而且不會破壞任何東西。

<div class="aside" data-semantic="ailoot-docs-link" role="note" aria-label="Ailoot 文件">

模型連線與 API 使用方式，請參閱 [Ailoot 文件](https://ailoot.ai/docs/)。

</div>

## 2026 年 6 月 18 日究竟有哪些服務會停止運作？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重要要點">

重要要點

2026 年 6 月 18 日，Gemini CLI 和 VS Code 的 Gemini Code Assist 擴充功能將停止為三類使用者處理請求：Free 方案、Google AI Pro 和 Google AI Ultra。GitHub 上將無法再安裝新的 Gemini Code Assist；現有安裝則會「在接下來幾週內」停用。透過 Gemini Enterprise Agent Platform 的付費 API 存取，以及 Code Assist Standard/Enterprise 授權，將維持原狀並繼續運作。

</div>

這不是「專案全面關閉」，而是停止三種最受歡迎方案的服務。受影響的方案如下：

| 方案 | 提供內容 | 2026 年 6 月 18 日將發生的情況 |
|----|----|----|
| Free tier | 限額使用 Gemini Code Assist 和 CLI | 完全停用 |
| Google AI Pro（每月約 \$19.99） | 提高 CLI 和 Code Assist 的使用限額 | 完全停用 |
| Google AI Ultra（I/O 2026 後，每月 \$100 起） | 最高使用限額 | 完全停用 |
| Gemini Code Assist for GitHub | Google 在你的儲存庫中自動審查 PR | 無法新安裝；現有安裝將在接下來幾週內停用 |
| Gemini Code Assist Standard / Enterprise（企業授權） | 透過企業 Google Workspace 帳戶使用 | 維持原狀並繼續運作 |
| 透過 Google Cloud 使用付費 API（付費 Gemini API 金鑰） | 請求費用由專案支付 | 維持原狀並繼續運作 |

Google Developers Blog 官方公告：

<figure>
<blockquote>
<p>2026 年 6 月 18 日，Gemini CLI 和 Gemini Code Assist IDE 擴充功能將停止為 Google AI Pro、Ultra 和 Free tier 使用者處理請求。</p>
</blockquote>
<figcaption>— Google Developers Blog, https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/</figcaption>
</figure>

如果你和大多數個人開發者一樣使用 Free 方案，並且心想「可是我有付費帳戶」，請確認你的 API 金鑰究竟如何計費。AI Pro 並非 Cloud 計費，而是個人 Google AI 訂閱服務，這項服務將被停用。使用付費專案的 Cloud 計費則不會被停用。

## Google 為什麼要關閉 Gemini CLI？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重要要點">

重要要點

Gemini CLI 是 Google GitHub 儲存庫中一項獨立的 TypeScript/Node.js 實驗專案。Google 決定將所有代理工具整合到單一平台 Google Antigravity 之下，並提供四種介面：Antigravity 2.0（桌面應用程式）、Antigravity CLI（終端機）、Antigravity SDK（Python 封裝程式）和 Antigravity IDE（VS Code 分支版本）。Antigravity CLI 已從 Node.js 改寫為 Go：啟動時間從數百毫秒縮短至數毫秒，記憶體用量則從數百 MB 降至數十 MB。

</div>

舊版 `gemini` 因為 Node.js 需要暖機，啟動時間是「數百毫秒」。新版 `agy` 是單一靜態 Go 二進位檔，啟動時間只需「數毫秒」。對於每次執行都會呼叫 CLI 數百次的 CI 和指令碼來說，這項差異相當顯著。

Google 對速度與原因的說明如下：

<figure>
<blockquote>
<p>Antigravity CLI 以 Go 開發，執行速度更快，並支援非同步背景工作流程。</p>
</blockquote>
<figcaption>— Google Developers Blog, https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/</figcaption>
</figure>

Gemini CLI 的所有主要功能都已移轉：

- **Agent Skills** — `.gemini/skills/` 資料夾現在位於 `.agents/skills/`。
- **Hooks** — 事件相同（`PreToolUse`、`PostToolUse` 等），語法幾乎沒有改變。
- **Subagents** — 運作方式與之前相同，設定也會自動遷移。
- **Extensions** — 改名為 Antigravity 外掛程式，並可透過一個命令匯入。

未能順利遷移的項目包括 MCP 伺服器，以及會直接存取 `.gemini/config.json` 的舊指令碼。根據 GitHub 討論串，有些使用者回報 MCP 設定會出問題，必須手動改寫。下文另有專節說明。

Google 並未關閉 Gemini CLI 開源專案：

<figure>
<blockquote>
<p>儲存庫將繼續以 Apache 2.0 授權條款保留在 GitHub 上，我們也會繼續以開源專案的形式投入開發。</p>
</blockquote>
<figcaption>— Google Developers Blog (Discussion #27274)</figcaption>
</figure>

這表示你可以建立分支，並使用自己的 Gemini API 金鑰繼續使用。不過，這種方式需要透過 Cloud 計費付費；免費的 Code Assist 使用方式已經結束。

## 如何安裝 Antigravity CLI：macOS、Linux 和 Windows 指令

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重要要點">

重要要點

Google 安裝程式會自動偵測作業系統和架構、下載二進位檔，並將其放入 `~/.local/bin`（Linux/macOS）或 `C:\Users\[your_name]\AppData\Local\agy\bin`（Windows）。三種作業系統使用的指令不同：macOS 和 Linux 使用一行 `curl` 指令；Windows 則可使用 PowerShell 的 `irm` 或 CMD 方式。安裝完成後，如果安裝程式沒有自行處理，請將路徑加入 `PATH`，開啟新的終端機並執行 `agy doctor`。此命令會檢查是否找到二進位檔，以及是否能連線至 Google。

</div>

開始之前，先快速確認你使用的是哪種方案。如果你有付費 Cloud 專案，而且沒有 6 月 18 日的期限，遷移雖然有幫助，但不急著完成。如果你使用 Free/Pro/Ultra，而且有程式正在使用 CLI，請趁這些方案仍有效時立即切換，才能在同一個工作上比較行為差異。

### macOS 和 Linux

使用 `curl` 的單行指令：

```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

指令碼會偵測平台、下載 `agy` 二進位檔、驗證其檢查碼，並將其放入 `~/.local/bin`。如果此資料夾不在 `PATH` 中，請將它加入：

```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

檢查是否找得到二進位檔：

```bash
which agy
agy --version
```

### Windows（PowerShell）

```powershell
irm https://antigravity.google/cli/install.ps1 | iex
```

二進位檔會安裝至 `C:\Users\[your_name]\AppData\Local\agy\bin`。安裝程式會自動更新 PATH，但請開啟新的 PowerShell 視窗，讓變數重新載入。

### Windows（CMD）

如果公司政策封鎖了 PowerShell：

```cmd
curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd
```

### 驗證安裝

在任何作業系統上安裝完成後，執行：

```bash
agy doctor
```

此命令會檢查二進位檔版本、是否存在設定檔、驗證狀態，以及網路是否能存取 `antigravity.google`。如果無法連線至 Google，問題可能出在所在區域或代理伺服器。

### 驗證

第一次不帶引數執行 `agy` 時，會啟動設定精靈：

1. 選擇介面主題。
2. 選擇驗證方式：Google OAuth（個人帳戶適用）或 API 金鑰。
3. 可選擇立即匯入 `.gemini/` 中的設定。

如果選擇 OAuth，瀏覽器會開啟並重新導向至 `accounts.google.com`；你需要同意資料分享。完成後即可使用 CLI。

## 如何將設定與外掛程式從 .gemini 遷移至 .agents

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重要要點">

重要要點

Antigravity CLI 會在專案旁的 `.agents/` 和全域的 `~/.agents/` 中尋找設定，與 Gemini CLI 尋找 `.gemini/` 的方式相同。只要執行一個命令 `agy plugin import gemini` 即可遷移：它會檢查 `.gemini/extensions/`，將外掛程式遷移為 Antigravity 外掛程式，並更新設定格式。請手動移動 skills 資料夾：`mv .gemini/skills/ .agents/skills/`。之後，`agy doctor` 和 `agy inspect` 會顯示已載入、未載入的項目，以及重複項目所在位置。

</div>

逐步操作如下：

1.  ### agy plugin import gemini

    可在任何資料夾執行此命令。它會將全域外掛程式從 `~/.gemini/` 遷移至 `~/.agents/`。若要遷移工作區外掛程式（位於專案旁），請在專案資料夾內執行此命令。

2.  ### mv .gemini/skills/ .agents/skills/

    手動重新命名資料夾以移動 skills。資料夾內的檔案格式相同，不需要改寫 Markdown。

3.  ### agy inspect

    顯示目前啟用的外掛程式、skills、hooks 和 subagents。請與你在 Gemini CLI 中使用的清單比較，確認沒有遺漏。

4.  ### agy config --edit

    使用預設編輯器（`$EDITOR`）開啟設定。如果有項目未自動載入，請手動編輯。

5.  ### agy doctor

    最後檢查二進位檔、驗證、外掛程式和網路。如果四項都顯示綠燈，設定遷移就完成了。

建議將舊的 `.gemini/` 資料夾保留一個月作為備份，以防遺漏項目。使用 Antigravity 一週並確認所有內容都已就位後，就可以刪除它。

如果你使用 [AGENTS.md 作為所有 AI 工具的通用設定](https://ailoot.ai/blog/zh-hant-tw/agents-md-guide-template/)，就不必修改它。Antigravity CLI 會和 Claude Code 或 Codex 一樣，從同一個資料夾讀取 `AGENTS.md`。

## 哪些環境變數需要修改？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重要要點">

重要要點

如果你的 CI/CD 指令碼、GitHub Actions、`.env` 本機檔案或 dotfiles 會傳入 `GEMINI_API_KEY` 或其他變數，就需要重新命名。前綴 `GEMINI_` 已改為 `AV_`（Antigravity 的縮寫）。Antigravity CLI 不會讀取舊變數。

</div>

完整的替換對照表：

| 舊變數（Gemini CLI） | 新變數（Antigravity CLI） | 預設值 |
|----|----|----|
| `GEMINI_API_KEY` | `AV_API_KEY` | \- |
| `GEMINI_PROJECT_ID` | `AV_PROJECT_ID` | \- |
| `GEMINI_REGION` | `AV_REGION` | `us-central1` |
| `GEMINI_MODEL` | `AV_MODEL` | `gemini-3.5-flash` |
| `GEMINI_API_BASE` | `AV_API_BASE` | Google 官方端點 |

如果 GitHub Actions 會傳入 secrets，請開啟 `Settings -> Secrets -> Actions` 並重新命名金鑰。金鑰值本身不變（遷移期間 Google API 金鑰並未更動）。

檢查所有可能含有 `GEMINI_` 的位置：

```bash
# 搜尋整個專案中的提及
grep -rn "GEMINI_" . --include="*.yml" --include="*.yaml" --include="*.sh" --include=".env*" 2>/dev/null

# 搜尋 dotfiles
grep -nE "GEMINI_" ~/.zshrc ~/.bashrc ~/.bash_profile ~/.config/fish/config.fish 2>/dev/null
```

替換後重新啟動終端機，只檢查是否存在，不要輸出機密。勿開啟 shell tracing，也不要把金鑰值複製到日誌。變數存在不代表授權成功；請另用 `agy doctor` 檢查：

```bash
if [ -n "${AV_API_KEY:-}" ]; then
    printf 'AV_API_KEY is set\n'
else
    printf 'AV_API_KEY is missing or empty\n'
fi
agy doctor        # should show “authorized”
```

## 遷移期間最常出現的問題及解決方法

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重要要點">

重要要點

根據 GitHub 討論串，最常見的問題是定義於 `~/.gemini/config.json` 的 MCP 伺服器不會自動載入，必須改寫為 Antigravity 格式。使用舊環境變數的自訂 hooks 會無聲失敗，導致測試失敗但沒有明確錯誤。直接存取 `.gemini/`（而非透過 CLI）的指令碼需要改為使用 `.agents/`。Antigravity CLI 初期版本的 `@[file]` 載入檔案至上下文功能曾有錯誤；近期版本已修正，但如果你使用舊版，請更新。

</div>

初期問題檢查清單：

1. **MCP 伺服器。** 如果你在 `.gemini/config.json` 中使用 `mcp_servers`，執行 `agy plugin import gemini` 後可能不會載入。使用 `agy inspect` 檢查，裡面會有 `mcp` 區段。如果該區段是空的或出現錯誤，請透過 `agy config --edit` 手動改寫。格式說明請參閱 Antigravity 官方文件中的 MCP 專節。

2. **自訂 hooks。** 如果你在 `.gemini/hooks/` 中有讀取 `$GEMINI_API_KEY` 的 bash 指令碼，它就會失效。找出這類位置：bash

    ```
    grep -rn "GEMINI_" .agents/hooks/ 2>/dev/null
    ```

    替換變數。

3. **CI/CD。** 在 GitHub Actions 或 GitLab CI 中，將使用 `gemini` 命令的步驟改為 `agy`。安裝程式中的二進位檔名稱可能不同，因此請使用 `$CLI_CMD` 變數建立抽象層。

4. **IDE 擴充功能。** VS Code 的 Gemini Code Assist 擴充功能會和 CLI 一起停用。替代方案是 [Antigravity IDE](https://antigravity.google)（獨立的 VS Code 分支版本），或在其他 AI 編輯器中使用 AGENTS.md。

5. **`@[file]` 載入功能。** Antigravity CLI 初期版本的 `@src/file.ts` 命令在載入檔案至上下文時曾有錯誤。請執行 `agy update` 更新至最新版本。

如果發生重大問題，且一小時內無法修復，Free 方案使用者可暫時繼續使用 Gemini CLI，直到 6 月 18 日，同時在另一個儲存庫分支上準備遷移。期限：14 天。

## 6 月 18 日之後，繼續使用 Google 工具值得嗎？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重要要點">

重要要點

Antigravity CLI 啟動速度更快，可搭配 Gemini 3.5 Flash 使用，並透過 `agy --background` 支援平行代理和非同步背景工作。不過有兩個潛在問題：區域存取限制，以及尚未成熟的生態系（外掛程式和 MCP 伺服器都比 Claude Code 少）。我不建議將 Antigravity 作為主要工具。我會把它當成執行平行背景工作的備用管道，同時繼續使用 Claude Code 處理主要開發工作。如果你使用 Gemini CLI 的原因是 Free 方案，6 月 18 日正好是重新考慮整套工具的時機。

</div>

Antigravity 2.0 可作為備用選項，以因應主要工具（Claude Code 或 Codex）不適用的情況。如需了解它的優缺點，請參閱 [Google Antigravity 2.0 指南](https://ailoot.ai/blog/zh-hant-tw/google-antigravity/)。

以下簡要列出不同情況的建議做法：

| 如果你…… | 6 月 18 日前該怎麼做 |
|----|----|
| 使用 Free Gemini CLI 進行實驗 | 使用可存取服務的帳戶遷移至 Antigravity CLI，或依預算改用 Claude/Codex |
| 在 IDE 中使用 Gemini Code Assist | 改用 Antigravity IDE，或回到 VS Code + Claude Code |
| 透過 Free 方案的 Gemini API 執行每晚的 cron 工作 | 儘快改用不會被停用的付費 Cloud API，或遷移至 Claude API |
| 透過企業 Cloud（Standard/Enterprise）工作 | 無需處理；此次停用不會影響你 |
| 只是因為「免費」才考慮試用 Gemini CLI | 不要開始使用，直接改用 [Claude Code](https://ailoot.ai/blog/zh-hant-tw/claude-code/) 或 [Codex](https://ailoot.ai/blog/zh-hant-tw/codex-vs-claude-code-choice/) |



## 15 分鐘遷移檢查清單

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="重要要點">

重要要點

如果你想以最快方式完成遷移，不想閱讀整篇指南，請依序執行以下步驟。在沒有任何 Gemini 指令碼正在執行的新終端機中，整個遷移需要 10–20 分鐘。

</div>

1. ### 安裝 Antigravity CLI

    `curl -fsSL https://antigravity.google/cli/install.sh | bash`（macOS/Linux），或 `irm https://antigravity.google/cli/install.ps1 | iex`（Windows PowerShell）。

2. ### 啟動 agy 並完成驗證

    不帶引數執行：`agy`。選擇 OAuth 或 API 金鑰。

3. ### 從 .gemini 匯入外掛程式

    `agy plugin import gemini`——此命令會全域遷移擴充功能。若要遷移工作區外掛程式，請在專案資料夾內再次執行。

4. ### 移動 skills

    `mv .gemini/skills/ .agents/skills/`。檔案內容保持不變。

5. ### 替換環境變數

    在 `~/.zshrc`/`~/.bashrc` 和 `.env` 檔案中，將 `GEMINI_API_KEY → AV_API_KEY`、`GEMINI_PROJECT_ID → AV_PROJECT_ID`、`GEMINI_REGION → AV_REGION`。重新啟動終端機。

6. ### 驗證安裝

    執行 `agy doctor`——四個項目（二進位檔、驗證、外掛程式、網路）都應顯示綠燈。

7. ### 執行測試工作

    執行 `agy "write a README for the project in the current folder"`，並檢查結果是否與 Gemini CLI 的輸出相似。

8. ### 更新 GitHub Actions / GitLab CI

    將命令名稱和 secrets 從 `GEMINI_*` 改為 `AV_*`。

9. ### 保留 .gemini/ 作為備份

    確認一切正常後 1–2 週即可刪除。

最後提醒：6 月 18 日不代表「你的所有專案都會停擺」，而是免費使用管道將被停用。付費 Cloud API 存取權會保留，Gemini CLI 儲存庫也會保留，而且仍可建立分支。如果你使用 Free 方案，必須在 6 月 18 日之前做出決定；否則，下次執行 `gemini "something"` 時就會收到驗證錯誤。

<div class="section" role="doc-bibliography" aria-label="來源">

### 來源

- [Google Developers Blog - 重要更新：從 Gemini CLI 遷移至 Antigravity CLI](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/)
- [Antigravity CLI - 入門指南](https://antigravity.google/docs/cli-getting-started)
- [Antigravity CLI - GitHub 儲存庫](https://github.com/google-antigravity/antigravity-cli)
- [Google Blog - Google I/O 2026 開發者亮點](https://blog.google/innovation-and-ai/technology/developers-tools/google-io-2026-developer-highlights/)

</div>





<div class="aside" data-semantic="ailoot-link" role="note" aria-label="Ailoot">

繼續在 [Ailoot](https://ailoot.ai/) 上使用 AI 工作。

</div>

## 常見問題：從 Gemini CLI 遷移至 Antigravity CLI：指南

### 如何確認更名後的 API 金鑰變數，而不洩漏內容？

檢查 `${AV_API_KEY:-}` 是否非空，只印出已設定或缺少訊息。不要 echo 金鑰值，也不要在開啟 shell tracing 時測試；另外用 `agy doctor` 查看驗證狀態。

### 設定匯入成功，就代表遷移全部完成嗎？

不能。請對照舊設定檢查使用中的 plugins、skills、hooks 與 subagents，查看 MCP 設定，再跑一項小任務。預期流程與結果尚未驗證前，保留原本 `.gemini/` 設定。


## Ailoot · 公司及其專案組合

Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。

公司及其專案組合：數百萬客戶，每月銷售額達數十億。

Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。