Antigravity CLI（agy）安裝與設定：什麼情況才真的需要命令列
☰ 目錄 table-of-contents.md
大部分人用 Antigravity 是開著視窗、看著它在編輯器裡跑。但你遲早會遇到這幾種情況：想在遠端伺服器上跑、想把它接進自動化流程、想一次批次處理三十個檔案、或是機器上根本沒有圖形介面。
這時候你要的是命令列（CLI）模式。Antigravity CLI 是 Google Antigravity 2.0 的終端機版本，執行檔叫 agy。依 官方 GitHub 說明，推理、跨檔案修改、呼叫工具這些能力都搬進了終端機，SSH 連進伺服器也能用。這篇講清楚：它跟編輯器模式差在哪、什麼情況才值得用、怎麼安裝與更新、怎麼寫進腳本，以及最常卡住的幾個地方。
（本篇是我們 Google Antigravity 系列的一部分。還沒安裝的話先看 Google Antigravity 安裝與設定完整指南；想知道它跟 Claude Code、Codex 怎麼選，看 三大 AI Coding Agent 完整比較。）
CLI 模式跟編輯器模式差在哪？
同一套能力，兩種操作方式，差別在誰來決定下一步：
| 編輯器模式 | 命令列模式 | |
|---|---|---|
| 互動方式 | 你看著它跑，隨時介入 | 下一次指令，等它跑完 |
| 適合 | 探索型、需要判斷的任務 | 規則明確、可重複的任務 |
| 能不能自動化 | 不行，需要人在場 | 可以，能接進腳本與排程 |
| 需要圖形介面 | 要 | 不用，SSH 進去就能跑 |
| 看得到過程嗎 | 看得到，隨時能喊停 | 只看得到輸出，較難即時煞車 |
‼️ 最關鍵的一列是最後一列。CLI 的優點是不用盯著，缺點也是不用盯著，它跑錯了你不會馬上知道。所以 CLI 適合的是你已經確定做法、只是不想手動重複的任務，不是拿來探索。
什麼情況真的需要 CLI？
- 在遠端主機上工作：SSH 進伺服器，沒有桌面環境，這是最直接的理由。
- 批次處理：三十個檔案要套同一套規則，用迴圈跑一遍，比在編輯器裡點三十次快得多。
- 接進自動化流程：例如每次有人提交程式碼就自動跑一次檢查、或每週自動整理一份報告。
- 要留下可重現的紀錄：指令寫在腳本裡，下次任何人執行都是同一套流程，不會因為「這次我提示詞打得不一樣」而結果不同。
反過來說，如果你只是要改個功能、修個 bug，編輯器模式更好用，你看得到它在想什麼，錯了馬上喊停。
‼️ 資料來源：下面的指令、參數與授權流程取自 Google Antigravity 官方 CLI 文件與 Google 的 Antigravity CLI 實作教學，查證於 2026 年 10 月 18 日。這個產品更新很快，執行前請對照手上版本的官方文件，以實際輸出為準。
安裝：一行指令，裝的是 agy
官方安裝說明沒有要求先裝 Node.js 之類的環境，安裝腳本會直接把 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
裝完之後執行檔會放在這裡：
| 系統 | 安裝位置 |
|---|---|
| macOS / Linux | ~/.local/bin/agy |
| Windows | C:\Users\<使用者名稱>\AppData\Local\agy\bin |
裝好後先打 agy --version 確認版本，再打 agy 進入。第一次啟動會問三件事：配色、畫面模式，以及要不要信任目前的資料夾。
安裝腳本預設會幫你改 shell 設定檔（加別名、加 PATH）。如果你不想讓它動這些，有兩個參數可以擋：
--skip-aliases：不要更新 shell 的別名設定。--skip-path：不要修改 shell 的環境變數。
‼️ 但要注意：用了 --skip-path 之後，你就得自己處理路徑。而且就算沒跳過，也還有一個很容易踩的坑，互動式終端機裡打 agy 可以跑，寫進腳本或排程卻說找不到命令。原因是排程環境載入的設定檔跟你的登入 shell 不一樣，PATH 也就不同。解法是在腳本裡直接用完整路徑（例如 ~/.local/bin/agy），不要靠 PATH。
如果連互動式終端機都說找不到 agy，macOS／Linux 依 官方疑難排解，把執行檔所在的資料夾加進 ~/.zshrc 或 ~/.bashrc，再重新載入：
export PATH="$HOME/.local/bin:$PATH"
source ~/.zshrc
Windows 則是把上表的 bin 資料夾加進使用者的 Path 環境變數，再重開終端機。其他安裝錯誤可以對照我們整理的 Antigravity 安裝疑難排解。
agy 怎麼更新？預設會自己更新
很多人搜「agy update」，但官方文件寫的做法是：CLI 內建一個在背景執行的自動更新程式，有 15 分鐘的間隔限制，不會每次啟動都去檢查，平常不用手動處理。
真正要處理的是相反的情況：在 CI 或排程上，通常不希望版本自己變。今天能跑的腳本，明天可能因為新版改了輸出而壞掉。官方提供的關閉方式是設定環境變數：
export AGY_CLI_DISABLE_AUTO_UPDATE=true
鎖住之後要升級，就在確認新版沒問題時，手動重跑一次上面的安裝指令。部分第三方速查表列了 agy update 這個指令，但官方文件目前沒有寫，版本到底有沒有換，以 agy --version 的輸出為準。
登入授權：遠端主機也有解
支援的帳號：依 官方授權說明，個人 Google 帳號的免費、Pro、Ultra 方案都能登入，公司帳號則走 Gemini Enterprise。用量算在帳號的方案額度裡，進去之後打 /usage 可以看各模型還剩多少。
在本機：CLI 會先查系統的憑證管理（keyring）有沒有存過帳號，有就直接登入，沒有的話會自動開啟預設瀏覽器，登入就完成了。
透過 SSH 連遠端主機：這是最多人卡住的情況，伺服器上沒有瀏覽器。官方的處理方式是：CLI 偵測到 SSH 連線時會印出一段授權網址，你複製到自己電腦的瀏覽器打開、登入後拿到一組英數代碼，再貼回遠端的終端機。整個流程不需要伺服器連得到瀏覽器，也不需要你手動搬憑證檔。
Linux 伺服器還有一個常見的坑：沒有桌面環境，系統的 keyring 服務根本沒在跑，結果每次都要重新登入。官方建議在無介面環境先執行 export $(dbus-launch)，把 keyring 服務帶起來。
排程與 CI 不想靠瀏覽器登入：官方另外提供兩種方式。一是在設定裡把 modelProvider 設成 gemini，再匯出 GEMINI_API_KEY，改用 Gemini API 金鑰；二是在 Google Cloud 環境設定 AGY_ADC_AUTH=true，執行 gcloud auth application-default login，用應用程式預設憑證登入。
要登出的話用 /logout，它會中斷帳號連線，並把儲存的驗證資料從系統 keyring 移除。
進去之後：常用的斜線指令
進入 CLI 之後，操作是靠斜線指令。忘記有哪些的時候，打一個 ? 就會列出全部。常用的幾個：
| 指令 | 作用 |
|---|---|
/config、/settings | 開啟設定選單 |
/permissions | 管理工具權限 |
/rewind、/undo | 把對話倒回前面的狀態 |
/fork、/branch | 從目前的對話分岔出一條新的對話 |
/clear、/new | 開一個新的對話 |
/resume | 列出並接續之前的對話 |
/usage、/quota | 看各模型的額度用量 |
/goal | 給一個目標，讓它自己跑到驗證完成 |
/schedule | 設定延遲或定期執行的任務 |
/keybindings | 自訂快捷鍵 |
? | 顯示說明與所有斜線指令 |
另外，前面加 ! 就是直接執行終端機指令，不用跳出去。
兩個很實用的小細節：設定會存在 ~/.gemini/antigravity-cli/settings.json（想版控或在多台機器同步就直接處理這個檔）；還有關閉 CLI 的時候，它會印出接續這個對話所需要的完整指令，複製起來下次就能接回去。
如果覺得工具執行的輸出太吵，可以在設定裡把 verbosity 調成 low。
不開介面直接跑：用 agy -p 寫進腳本
批次處理、排程、CI 要的都是「下一個指令、拿到結果、結束」。這就是 -p（也可以寫 --print 或 --prompt）的用途：送出一個提示，把回答印到標準輸出，然後結束。依 官方的非互動模式說明，診斷訊息走標準錯誤，所以輸出可以直接接給下一個指令。
# 跑一次就結束
agy -p "列出這個專案裡沒有測試的檔案"
# 要給程式讀，改輸出 JSON，再用 jq 取出回答
agy -p "整理這次改動的重點" --output-format json | jq '.response'
# 指定模型與推理強度（可用的模型名稱用 agy models 查）
agy -p "檢查 README 的安裝步驟" --model gemini-3.8-flash-medium --effort high
寫進腳本前要先知道的幾個行為：
- 權限照設定檔走：需要核准的工具在沒人能按確認時會被「軟拒絕」，執行照樣結束、回傳 0，只在標準錯誤印出通知。所以回傳 0 不代表事情做完了，一定要檢查輸出。
- 預先放行特定工具：在
settings.json的permissions.allow加規則，例如只放行command(git)。 - 全部放行的參數是
--dangerously-skip-permissions，官方特別警告它會核准所有寫檔與執行指令。我們的建議是只在拋棄式的容器裡用，並搭配--sandbox開啟終端機沙盒限制，差異可以看 Antigravity 沙盒模式說明。 - 逾時與接續：預設最多等 5 分鐘，長任務用
--print-timeout調整；要接續上一次的對話用-c。
模型方面，官方額度頁公告 Gemini 4 Argon 已開放給 Google AI Pro 與 Ultra；實際能選哪些，以 agy models 列出來的為準。
還有一個坑：檔案權限
由不同身分產生的檔案，網站或服務可能讀不到。如果你是用 root 或自己的帳號跑 CLI，但網站是用另一個身分在跑，產出的檔案很可能直接讓網站噴 500。
寫入專案檔案後，比對一下鄰近既有檔案的擁有者，權限不對就補齊，最後實際打開網頁確認一次。這個坑我們踩過，而且它不會有任何錯誤訊息提醒你。
非互動環境的三個必備習慣
沒有人盯著的時候，這三句話請一定要寫進你的指令：
1. 限定範圍：只處理指定的目錄，其他地方不要動，結束後列出所有動過的檔案。
2. 要求驗證：每一項改動都要分開確認，把實際結果輸出出來。沒有真的驗證過的，直接說沒驗證，不要用「應該可以」帶過。
3. 失敗就停：任何一步失敗就中止，不要繼續往下跑。
第三點特別重要。互動模式下你會看到它卡住，CLI 模式下它可能帶著錯誤的狀態一路跑到底，最後你收到一個「完成」，然後花兩小時查為什麼結果不對。加上前面提到的軟拒絕，腳本裡最好再補一道檢查：輸出裡沒有出現預期的結果，就當成失敗處理。
另外：CLI、API、MCP 別搞混
這三個詞常常一起出現，但解決的是不同問題：CLI 是你操作工具的方式；API 是程式之間互相呼叫；MCP 是AI 代理人存取外部工具與資料的標準介面。詳細差異可以看 MCP、API、CLI 差在哪？一篇看懂三種系統介面。
結論
CLI 模式不是「進階版」，它是不同用途。需要判斷的任務用編輯器，需要重複的任務用 CLI。
而且用 CLI 的前提是你已經知道正確做法，它是拿來把已知流程自動化的，不是拿來探索未知的。順序搞反，你只會得到一批跑很快但是錯的結果。
我們自己也在做 AI 產品：Ocean Bot 業務助理、玄燈命理 DestineAI、PiMe AI 形象照，以及陪跑者 PACER 這個 AI 原生官網，都收在作品案例裡，可以看看落地之後實際長什麼樣。
如果你想把 AI 代理人接進團隊的實際開發流程（CI、排程、批次維運），但不確定權限、憑證、環境該怎麼配置，這正是我們 AI 自動化開發在做的事。跟我們聊聊你的情境。
常見問題
Antigravity CLI 跟編輯器模式差在哪？
agy 要怎麼更新到最新版？
CLI 安裝後打指令說「找不到命令」怎麼辦？
遠端伺服器沒有瀏覽器，要怎麼完成登入授權？
讓 AI 在沒人盯著的情況下跑，要注意什麼？
這個主題的完整脈絡、選型比較與導入建議，都整理在指南裡。
訂閱免費電子報
把 AI 自動化、企業系統設計與 WordPress / Laravel 開發的真實案例和可直接照做的技巧，整理成電子報寄給你。只寄精選內容、不灌垃圾信，一鍵就能退訂。