Gemini CLI

Gemini CLI 是 Google 推出的開源終端機代理程式，可以在終端機中理解專案、分析檔案並在獲得授權後使用命令和工具。透過設定 Gemini API 地址、API Key 和模型 ID，可以讓 Gemini CLI 使用 AGTCloud 的 Gemini Generate Content 相容入口。

本教學只介紹 Gemini CLI 的基本連線與安全驗證流程。檔案修改、Shell 命令、函式呼叫和其他代理程式能力取決於目標模型，以及對應模型對 Gemini Parts、Function Call 等協議結構的實際支援情況。

先驗證基本對話，再測試工具能力

成功傳回一般文字只表示基本生成流程已經接通，不代表檔案編輯、命令執行和所有內建工具均可用。首次測試請保持人工確認，不要啟用自動核准。

準備工作

開始前，請確認你已經：

安裝 Node.js 20 或更高版本；
準備 Bash、Zsh 或 PowerShell 終端機；
在 API Keys 頁面建立 AGTCloud API Key；
從模型廣場複製目前 Key 可見、且支援 Gemini Generate Content 的模型 ID；
準備一個不包含敏感程式碼和正式環境憑證的測試目錄。

MODEL_ID 是需要替換的預留位置，不是實際模型名稱。請使用目前 API Key 可見且支援 Gemini Generate Content 的模型 ID。

安裝 Gemini CLI

推薦安裝目前穩定版本。不同安裝方式得到的是同一個 gemini 命令。

使用 npm 全域安裝：

npm install -g @google/gemini-cli

適用於已經安裝 Node.js 20+ 的 macOS、Linux、WSL 和 Windows 環境。

安裝完成後檢查版本：

gemini --version

如果提示找不到命令，請重新開啟終端機，並確認 npm 全域命令目錄已經加入 PATH。

設定 AGTCloud

Gemini CLI 需要四個環境變數：API Key、模型 ID、自訂 Gemini API 地址和 Bearer 身分驗證方式。

在目前終端機臨時設定：

export GEMINI_API_KEY="your-api-key"
export GEMINI_MODEL="MODEL_ID"
export GOOGLE_GEMINI_BASE_URL="https://api.agtcloud.cn"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"

這些變數只對目前終端機工作階段生效，關閉終端機後需要重新設定。

設定項目說明

環境變數	用途
`GEMINI_API_KEY`	在 API Keys 頁面建立的 AGTCloud API Key
`GEMINI_MODEL`	目前 Key 可見且支援 Gemini Generate Content 的模型 ID
`GOOGLE_GEMINI_BASE_URL`	Gemini API 地址，使用 `https://api.agtcloud.cn`
`GEMINI_API_KEY_AUTH_MECHANISM`	設定為 `bearer`，透過 Authorization Header 傳送 AGTCloud API Key

Base URL 不要追加 /v1

GOOGLE_GEMINI_BASE_URL 只填寫 https://api.agtcloud.cn。Gemini SDK 會繼續串接 /v1beta/models/{model}:generateContent；如果填寫 https://api.agtcloud.cn/v1，最終路徑可能變成錯誤的 /v1/v1beta/...。

本教學不設定 GOOGLE_GENAI_API_VERSION，讓 Gemini CLI 使用 Gemini API 預設的 v1beta。也不要把完整的 generateContent 請求路徑寫入 Base URL。

儲存使用者層級設定

確認臨時設定能夠工作後，可以將變數寫入 Gemini CLI 的使用者層級 .env 檔案。該檔案可能包含真實 API Key，請不要提交到程式碼倉庫。

使用者層級檔案路徑：

~/.gemini/.env

檔案內容：

GEMINI_API_KEY=your-api-key
GEMINI_MODEL=MODEL_ID
GOOGLE_GEMINI_BASE_URL=https://api.agtcloud.cn
GEMINI_API_KEY_AUTH_MECHANISM=bearer

Gemini CLI 會按目前工作目錄和父目錄查找環境檔案。專案中更近的 .env 或 .gemini/.env 可能優先於使用者層級設定；發現設定沒有生效時，應先排查這些檔案。

固定 API Key 驗證方式

Gemini CLI 支援多種 Google 驗證方式。透過 AGTCloud 使用時，應選擇 Gemini API Key，而不是 Google 登入或 Vertex AI。

在使用者層級 settings.json 中合併以下設定，不要覆蓋檔案中已有的主題、權限或其他設定：

{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

設定檔位置：

系統	路徑
macOS / Linux / WSL	`~/.gemini/settings.json`
Windows	`%USERPROFILE%\.gemini\settings.json`

儲存後完全退出 Gemini CLI，再重新啟動。selectedType 與 GEMINI_API_KEY_AUTH_MECHANISM=bearer 分別負責選擇 API Key 驗證流程和按 AGTCloud 要求生成 Bearer Header，二者不能相互替代。

選擇模型

預設模型由 GEMINI_MODEL 決定。需要為單次工作階段臨時指定模型時，可以執行：

gemini --model MODEL_ID

互動工作階段中的 /model 可以作為輔助入口，但其清單不一定自動包含目前 AGTCloud API Key 傳回的所有模型。遇到模型不存在或不可見時，請從模型廣場重新複製完整模型 ID，並優先透過 GEMINI_MODEL 或 --model 指定。

驗證連線

執行最小生成測試

在不包含敏感檔案的目錄中執行：

gemini -p "請只回覆：AGTCloud 連線成功。" --output-format json

能夠傳回包含回答內容的 JSON，說明 Base URL、API Key、Bearer 身分驗證和模型 ID 已經建立基本連線。

執行唯讀檔案測試

進入包含 README.md 的安全測試專案：

gemini -p "@README.md 請用三點概括專案用途，不要修改任何檔案。" --output-format json

正常讀取並概括檔案，且沒有發生檔案修改，說明基本檔案分析流程可用。

啟動互動工作階段

基本測試通過後執行：

gemini

首次使用保持預設人工審核。檢查 Gemini CLI 準備執行的每項檔案和命令操作，不要直接啟用自動核准模式。

常見問題

現象	優先檢查	處理方式
找不到 `gemini` 命令	Node.js 版本、安裝結果和 `PATH`	確認 Node.js 為 `20+`，重新開啟終端機並執行 `gemini --version`
仍要求 Google 登入	`security.auth.selectedType`	合併 `gemini-api-key` 設定，退出並重新啟動 Gemini CLI
環境變數未生效	目前目錄、父目錄和使用者目錄中的環境檔案	檢查是否存在優先級更高的 `.env` 或 `.gemini/.env`，不要列印完整 API Key
傳回 `401`	API Key 和 Bearer 變數	使用有效 API Key，並確認 `GEMINI_API_KEY_AUTH_MECHANISM=bearer`
傳回 `403`	Key 權限和模型可見範圍	確認目前 Key 能存取所填模型，並檢查帳戶狀態
傳回 `404`	Base URL、API 版本和模型 ID	Base URL 使用 `https://api.agtcloud.cn`，不要附加 `/v1`、`/v1beta` 或完整 Endpoint
請求進入 Vertex AI / Google	衝突的 Google 環境變數	清除或停用 `GOOGLE_GENAI_USE_VERTEXAI`、`GOOGLE_GENAI_USE_GCA`、`GOOGLE_API_KEY` 等不屬於本教學的設定
模型不可用	`GEMINI_MODEL` 或 `--model`	從模型廣場重新複製支援 Gemini Generate Content 的完整模型 ID
文字正常但工具失敗	模型能力和 Gemini Function Call 相容性	暫時限制為一般對話和唯讀分析，再根據實際錯誤核對工具呼叫能力
Bearer 設定不可用	Gemini CLI 版本	更新到目前穩定版本，不修改本機安裝原始碼，也不把 Key 手工寫進自訂 Header

遇到無法定位的問題時，請記錄請求時間、API Base URL、模型 ID、Gemini CLI 版本、HTTP 狀態和去識別化錯誤資訊，然後檢視錯誤與疑難排解。不要提交完整 API Key 或包含憑證的 .env 檔案。

安全建議

不要把真實 API Key 寫入倉庫、共享腳本、截圖、記錄或聊天記錄；
建議先使用臨時環境變數驗證，成功後再儲存使用者層級設定；
為 .env 檔案設定合適的本機存取權限，並避免同步到公開雲端硬碟；
首次使用工具能力時保持人工審核，並在非正式環境專案中驗證；
共享疑難排解資訊前，刪除完整 Key、使用者名、本機路徑和業務原始碼。