從 Gemini CLI 遷移至 Antigravity CLI：指南

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 擴充功能，本指南將說明如何在一個晚上完成遷移，而且不會破壞任何東西。

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

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

Google Developers Blog 官方公告：

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

Google 為什麼要關閉 Gemini CLI？#

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

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

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

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

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

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

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

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

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

macOS 和 Linux

使用 curl 的單行指令：

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

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

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

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

which agy
agy --version

Windows（PowerShell）

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

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

Windows（CMD）

如果公司政策封鎖了 PowerShell：

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

驗證安裝

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

agy doctor

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

驗證

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

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

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

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

逐步操作如下：

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 工具的通用設定，就不必修改它。Antigravity CLI 會和 Claude Code 或 Codex 一樣，從同一個資料夾讀取 AGENTS.md。

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

完整的替換對照表：

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

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

# 搜尋整個專案中的提及
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 檢查：

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”

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

初期問題檢查清單：

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（獨立的 VS Code 分支版本），或在其他 AI 編輯器中使用 AGENTS.md。

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

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

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

Antigravity 2.0 可作為備用選項，以因應主要工具（Claude Code 或 Codex）不適用的情況。如需了解它的優缺點，請參閱 Google Antigravity 2.0 指南。

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

15 分鐘遷移檢查清單#

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" 時就會收到驗證錯誤。