Gemini 在 October 27 推出了名為 gemini-api 的命令列用戶端。這則公告的重點不在於「又一個 SDK」,而是一種不同的存取介面:一個無狀態、零相依性的執行檔,有 shell 存取權限的代理可以呼叫,指令碼或 CI 工作也能以相同方式呼叫。文字與媒體生成、檔案分析,以及受管理的代理,都成了透過 Interactions API 執行的一般 shell 命令。
這個定位很重要,因為大多數整合決策其實都取決於程式碼在哪裡執行。如果答案是「在我的應用程式內」,這個 CLI 就不是適合的工具。如果答案是「在終端機、子程序或管線中」,它就是減少一項相依性,而不是增加一項。從第一句起就要記住的一個注意事項是:這仍是測試版,次要版本之間可能出現破壞性變更,自動化環境應固定使用特定發行版本。
以下內容皆依據官方版本資訊與 CLI 指南,並已於 2026-10-30 查核。命令均照錄自已發布的範例,其中代理識別碼以預留位置表示。
這次推出了什麼
版本說明將 gemini-api 描述為無狀態、零相依性的命令列用戶端,供 AI 程式開發代理、指令碼和 CI 管線使用。它透過 Interactions API 運作,並列出三項功能:產生文字與媒體、分析檔案,以及執行 Gemini 代管代理。
這裡的「無狀態」有實質意義。這個命令不會在不同次執行之間保留對話;每次呼叫都各自獨立。這正是 shell 工具該有的設計,因為呼叫 shell 工具的通常是已經自行管理狀態的程式或流程:指令碼、管線中的步驟,或是決定下一步要執行什麼的代理。
它能取代什麼,不能取代什麼
這份指南提供了明確的選用表,值得照著表中的建議選擇,而不是把 CLI 當成適用所有情境的升級方案。
當代理或指令碼需要直接從 shell 呼叫 Gemini,又不想在專案中加入 SDK 程式碼時,就使用 CLI。這包括產生媒體、分析檔案,或從管線執行背景研究代理,而且不必為專案新增任何相依套件。
當你要將 Gemini 整合進應用程式、後端服務或即時 Live API 工作階段時,就使用 Google GenAI SDKs。這些程式碼會匯入用戶端程式庫,這類整合也應留在程式碼中。
當程式開發代理正在撰寫會匯入 GenAI SDK 的應用程式碼,需要即時搜尋文件並查閱最新的 SDK 規則時,就使用 Gemini Docs MCP 和技能。
指南也明確劃分了一條界線,避免常見的混淆:gemini-api 是無狀態的 API 用戶端,不是像另一個獨立專案 Gemini CLI 那樣的互動式程式開發代理。你是在程式開發代理中執行 gemini-api;它本身並不是代理。
誰可以不換工具就直接使用
支援清單刻意涵蓋廣泛:Antigravity、Claude Code、Codex、Cursor、OpenClaw、Hermes,或任何 shell 環境。實際上,這代表已統一使用某個程式開發代理的團隊,可以新增 Gemini 作為可用模型,而不必改用新的編輯器或工作流程。這就是「多一個模型,工具照舊」的主張,也是這次公告中最具體的好處。
只要你的代理能執行子程序,就能執行這個工具。接下來的設定問題就在於憑證與版本鎖定,而不是整合架構。至於 Codex 端的相關設定,包括專案層級與使用者層級的設定如何解析,都在 Codex 設定情境指南中說明。
安裝與驗證
官方公布的 macOS 和 Linux 安裝指令會將 curl 的輸出透過管線傳給 bash:
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash接著透過環境變數提供金鑰:
export GEMINI_API_KEY="YOUR_API_KEY"這兩段指令旁應該附上兩點提醒。在受管理的環境中,curl | bash 安裝方式可能會被政策封鎖,因此在放進管線之前,先在可正常運作的機器上試跑。另外,金鑰應透過環境變數注入或機密管理工具提供,而不是直接寫進指令碼;這也是 API 金鑰安全管理指南 對其他任何憑證採用的相同原則。
公布的三個範例,以及關鍵旗標
指南列出三個指令,各自對應一項功能。
媒體生成會將結果寫入檔案:
gemini-api image "Minimalist isometric icon of a cloud database" --out ./assets/db-icon.jpg檔案分析接受輸入路徑與提示詞:
gemini-api analyze -i ./docs/quarterly-report.pdf "Summarize the key findings in three bullets."代管代理程式會在背景執行,並關閉串流輸出:
gemini-api agent run "Compare WebRTC SFU architectures and cite sources" \
--agent <agent-name> \
--background \
--stream=false<agent-name> 佔位符代表你要執行的代管代理程式識別碼;指南本身的範例使用了特定的預覽版代理程式。旗標的拼法請與公布的指令完全一致,因為 --stream=false 是文件記載的形式。
為什麼串流輸出在這裡很重要?背景工作或 CI 步驟不是要將 token 顯示給人看;它需要的是最終結果與結束代碼。關閉串流輸出正好符合這種結果取用方式。同樣的取捨,也就是等待結果而非觀看輸出過程,讓 Batch API 適合用於大量作業,不過這兩種機制解決的是不同問題。
設計時必須納入考量的 beta 限制
指南的註記說得很明確:gemini-api 是開源的 beta 版本,會隨著 Interactions API 一起演進,而次要版本之間也可能出現不相容的變更。接著,指南給出了實務操作指示:在自動化代理環境與 CI 管線中,固定使用特定的發布版本。
這表示 CI 工作不應該在每次執行時都安裝「當下的最新版本」。把版本寫進用來建置執行環境的映像檔、指令碼或鎖定檔,並將升級視為需要驗證的變更,而不是悄悄進行的更新。程式開發代理的 CI 指南 涵蓋了相關的可重現性實務;至於驗證步驟,則與任何提示詞或模型變更在正式採用前所需的驗證相同。
還有一個值得明說的間接影響:由於 CLI 會跟隨 Interactions API 更新,不相容的變更可能來自其中任一層。固定 CLI 版本並不會固定 API 的行為,因此升級檢查清單也應納入版本說明的檢閱。
為什麼這裡預設採用無狀態才合理
Gemini 最近變更了儲存的預設行為:新的付費層級專案現在會儲存 Generate Content 請求,除非主動選擇停用,詳見儲存預設行為分析。這項變更涉及 API 的伺服器端資料保留,很容易與 CLI 的行為混為一談。
CLI 本身不保留工作階段。每次執行都是全新的呼叫,因此很適合不需要重播的工作:一次性分析、CI 步驟,或處理完檔案就結束的指令碼。如果你需要伺服器端狀態,應透過 Interactions API 的 store 語意來處理,而不是命令列。清楚知道狀態存在哪一層,就能在設計工作流程時避免混淆不同層次的概念。
可觀測性也適用同樣的區分。使用無狀態命令時,你必須自行記錄執行了什麼、使用哪些輸入,以及回傳了什麼,而且要採用固定的欄位集合,不能只依賴終端機剛好印出的內容。命令失敗時,從結束代碼搭配請求中繼資料來診斷,通常比重新閱讀指令碼更容易找出問題。
它與 MCP、Batch 和快取的關係
這三個面向很容易混淆,明確的區分方式是:CLI 是呼叫介面,Batch 是傳遞管道,而快取則是同步路徑上降低成本的手段。
它們可以搭配使用,而不是互相競爭。CI 作業可以透過 CLI 觸發工作,大量資料回填可以透過 Batch 處理,遵循其專屬的時間窗口與限制,而互動式路徑則可以利用提示快取,重複使用相同的前綴。如果你要將代理程式串接到外部工具,而不是模型,MCP 伺服器指南 說明的就是這個不同的層次。
導入檢查清單
- 判斷需求是透過 shell 呼叫,還是在應用程式內整合;CLI 只適用於前者。
- 將安裝或金鑰匯出步驟加入自動化流程前,先在可正常運作的機器上執行這兩個步驟。
- 使用已發布範例中的一個實際指令進行驗證,而不是自行拼湊的 echo 指令。
- 在 CI 和映像檔中固定發行版本;不要每次執行都安裝持續變動的最新開發版本。
- 從環境變數或機密管理工具注入
GEMINI_API_KEY,並避免讓它出現在日誌中。 - 執行背景工作時,確認已設定
--stream=false,並為工作明確設定逾時上限。 - 比較供應商時,分別記錄模型與呼叫介面,以免將其中一項的變更誤認為另一項的變更。
- 將每次升級都視為一次變更:閱讀版本說明、重新執行驗證指令,再推進升級,並記錄指令、模型與結果。
這則公告不大,帶來的影響也很平常:代理程式多了一種存取模型的方式,而且不必在儲存庫中新增相依套件。真正該慎重看待的是 beta 標籤,因為固定版本的成本微不足道,但未固定版本而讓管線遭遇破壞性變更的成本可不低。
上述所有指令、功能與限制,皆以 2026-10-30 查核的官方頁面為依據;實際採用前,請先對照目前的文件確認。