Antigravity CLI（agy）安裝與設定完整教學：什麼時候該用命令列模式

大部分人用 Antigravity 是開著視窗、看著它在編輯器裡跑。但你遲早會遇到這幾種情況：想在遠端伺服器上跑、想把它接進自動化流程、想一次批次處理三十個檔案、或是機器上根本沒有圖形介面。

這時候你要的是命令列（CLI）模式。這篇講清楚：它跟編輯器模式差在哪、什麼情況才值得用、安裝設定要注意什麼、以及最常卡住的幾個地方。

（本篇是我們 Google Antigravity 系列的一部分。還沒安裝的話先看 Google Antigravity 安裝與設定完整指南；想知道它跟 Claude Code、Codex 怎麼選，看 三大 AI Coding Agent 完整比較。）

CLI 模式跟編輯器模式差在哪？

同一套能力，兩種操作方式，差別在誰來決定下一步：

‼️ 最關鍵的一列是最後一列。CLI 的優點是不用盯著，缺點也是不用盯著——它跑錯了你不會馬上知道。所以 CLI 適合的是你已經確定做法、只是不想手動重複的任務，不是拿來探索。

什麼情況真的需要 CLI？

• 在遠端主機上工作：SSH 進伺服器，沒有桌面環境，這是最直接的理由。
• 批次處理：三十個檔案要套同一套規則，用迴圈跑一遍，比在編輯器裡點三十次快得多。
• 接進自動化流程：例如每次有人提交程式碼就自動跑一次檢查、或每週自動整理一份報告。
• 要留下可重現的紀錄：指令寫在腳本裡，下次任何人執行都是同一套流程，不會因為「這次我提示詞打得不一樣」而結果不同。

反過來說，如果你只是要改個功能、修個 bug，編輯器模式更好用——你看得到它在想什麼，錯了馬上喊停。

‼️ 資料來源：下面的指令與參數取自 Google Antigravity 官方文件（查證於 2026 年 7 月）。這個產品更新很快，執行前請對照你手上版本的官方文件，以實際輸出為準。

安裝：一行指令，裝的是 agy

Antigravity CLI 的執行檔叫 agy。安裝方式依作業系統不同：

# 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

裝完之後執行檔會放在這裡：

安裝腳本預設會幫你改 shell 設定檔（加別名、加 PATH）。如果你不想讓它動這些，有兩個參數可以擋：

• --skip-aliases：不要更新 shell 的別名設定。
• --skip-path：不要修改 shell 的環境變數。

‼️ 但要注意：用了 --skip-path 之後，你就得自己處理路徑。而且就算沒跳過，也還有一個很容易踩的坑——互動式終端機裡打 agy 可以跑，寫進腳本或排程卻說找不到命令。原因是排程環境載入的設定檔跟你的登入 shell 不一樣，PATH 也就不同。解法是在腳本裡直接用完整路徑（例如 ~/.local/bin/agy），不要靠 PATH。

登入授權：遠端主機也有解

在本機：CLI 會先查系統的憑證管理（keyring）有沒有存過帳號，沒有的話會自動開啟你的預設瀏覽器，登入就完成了。

透過 SSH 連遠端主機：這是最多人卡住的情況——伺服器上沒有瀏覽器。官方的處理方式是：CLI 會印出一段授權網址，你複製到自己電腦的瀏覽器打開、登入後拿到一組英數代碼，再貼回遠端的終端機。整個流程不需要伺服器連得到瀏覽器，也不需要你手動搬憑證檔。

要登出的話用 /logout，它會中斷帳號連線並把儲存的驗證資料從系統 keyring 移除。

進去之後：常用的斜線指令

進入 CLI 之後，操作是靠斜線指令。忘記有哪些的時候，打一個 ? 就會列出全部。常用的幾個：

另外，前面加 ! 就是直接執行終端機指令，不用跳出去。

兩個很實用的小細節：設定會存在 ~/.gemini/antigravity-cli/settings.json（想版控或在多台機器同步就直接處理這個檔）；還有關閉 CLI 的時候，它會印出接續這個對話所需要的完整指令，複製起來下次就能接回去。

如果覺得工具執行的輸出太吵，可以在設定裡把 verbosity 調成 low。

還有一個坑：檔案權限

由不同身分產生的檔案，網站或服務可能讀不到。如果你是用 root 或自己的帳號跑 CLI，但網站是用另一個身分在跑，產出的檔案很可能直接讓網站噴 500。

寫入專案檔案後，比對一下鄰近既有檔案的擁有者，權限不對就補齊，最後實際打開網頁確認一次。這個坑我們踩過，而且它不會有任何錯誤訊息提醒你。

非互動環境的三個必備習慣

沒有人盯著的時候，這三句話請一定要寫進你的指令：

1. 限定範圍：只處理指定的目錄，其他地方不要動，結束後列出所有動過的檔案。

2. 要求驗證：每一項改動都要分開確認，把實際結果輸出出來。沒有真的驗證過的，直接說沒驗證，不要用「應該可以」帶過。

3. 失敗就停：任何一步失敗就中止，不要繼續往下跑。

第三點特別重要。互動模式下你會看到它卡住，CLI 模式下它可能帶著錯誤的狀態一路跑到底，最後你收到一個「完成」，然後花兩小時查為什麼結果不對。

另外：CLI、API、MCP 別搞混

這三個詞常常一起出現，但解決的是不同問題：CLI 是你操作工具的方式；API 是程式之間互相呼叫；MCP 是AI 代理人存取外部工具與資料的標準介面。詳細差異可以看 MCP、API、CLI 差在哪？一篇看懂三種系統介面。

結論

CLI 模式不是「進階版」，它是不同用途。需要判斷的任務用編輯器，需要重複的任務用 CLI。

而且用 CLI 的前提是你已經知道正確做法——它是拿來把已知流程自動化的，不是拿來探索未知的。順序搞反，你只會得到一批跑很快但是錯的結果。

如果你想把 AI 代理人接進團隊的實際開發流程（CI、排程、批次維運），但不確定權限、憑證、環境該怎麼配置，這正是我們 AI 自動化開發在做的事。跟我們聊聊你的情境。