Gemini CLI 中轉站怎麼設定 Gemini API 金鑰

發佈於 2026-05-30

從安裝 Gemini CLI、首次設定 API 金鑰，到配置中轉站 Base URL、建立終端機別名與檢查常見錯誤，整理成繁體中文實作教學。

這篇教學在解決什麼問題

Gemini CLI 是 Google 推出的命令列 AI 工具，可以直接在終端機裡呼叫 Gemini 做問答、程式碼解釋、檔案分析和開發輔助。

如果你只用官方帳號，照著登入流程走通常就能開始用。真正容易卡住的是另一種情況：你拿到的是中轉站提供的 API 金鑰和 Base URL，不確定 Gemini CLI 要選哪個登入方式，也不確定環境變數該怎麼設定。

先記住一件事：很多「支援 Gemini」的中轉站，其實只是提供 Gemini 模型的 API 聚合服務，不一定完整相容 Gemini CLI。這篇教學會先用最小設定跑通，再教你怎麼驗證它是不是真的可用。

安裝 Gemini CLI 前的先決條件

先確認你的電腦有 Node.js，而且版本不要太舊。建議使用 Node.js 20 以上：

node --version

如果沒有安裝 Node.js，可以先用 nvm、fnm 或官方安裝包處理好，再回來裝 Gemini CLI。

官方 npm 安裝方式如下：

npm install -g @google/gemini-cli
gemini --version

如果只是臨時試用，不想全域安裝，也可以直接執行：

npx @google/gemini-cli

裝好後先啟動一次：

gemini

第一次啟動要選哪個登入方式

Gemini CLI 首次啟動時，通常會看到不同認證方式。對中轉站使用者來說，重點是這兩個：

Login with Google：用 Google 帳號登入，適合先體驗官方 Gemini CLI。
Gemini API Key (AI Studio)：讓 CLI 讀取 GEMINI_API_KEY，多數中轉站教學會走這條路。

如果你要接中轉站，通常選 Gemini API Key (AI Studio)，再把中轉站給你的 Key 寫進環境變數。

之後如果想重新切換認證方式，可以在 Gemini CLI 裡輸入：

/auth

再選回需要的路徑：

○ Login with Google
● Gemini API Key (AI Studio)

設定 API 金鑰與中轉站位址

只使用官方 AI Studio API Key 時，最小設定是：

export GEMINI_API_KEY="你的 Gemini API 金鑰"
gemini

如果你使用的是中轉站，服務商通常會再提供一個中轉站位址，也就是 Base URL。常見設定方式如下：

export GEMINI_API_KEY="你的中轉站 API 金鑰"
export GOOGLE_GEMINI_BASE_URL="https://你的中轉站位址"
gemini

這裡不要直接照抄別篇文章的網址。GOOGLE_GEMINI_BASE_URL 能不能用、網址尾端要不要帶 /v1，都要以你使用的服務商說明文件為準。

如果測試成功，再寫進 shell 設定檔。Zsh 通常是 ~/.zshrc：

nano ~/.zshrc

加入：

export GEMINI_API_KEY="你的中轉站 API 金鑰"
export GOOGLE_GEMINI_BASE_URL="https://你的中轉站位址"

儲存後重新載入設定：

source ~/.zshrc

Bash 使用者通常改 ~/.bashrc：

nano ~/.bashrc
source ~/.bashrc

Windows CMD 可以先用臨時設定：

set GEMINI_API_KEY=你的中轉站 API 金鑰
set GOOGLE_GEMINI_BASE_URL=https://你的中轉站位址

PowerShell 可以用：

$env:GEMINI_API_KEY="你的中轉站 API 金鑰"
$env:GOOGLE_GEMINI_BASE_URL="https://你的中轉站位址"

裝完後怎麼更方便地用

每次輸入 gemini 有點長，可以在終端機設定一個短別名。建議用 gm，不要用 g，因為 g 很容易和 git、目錄跳轉工具或其他指令撞名。

macOS / Linux 的 Zsh 可以這樣加：

echo 'alias gm="gemini"' >> ~/.zshrc
source ~/.zshrc

Bash 則通常寫到 ~/.bashrc 或 ~/.bash_profile：

echo 'alias gm="gemini"' >> ~/.bashrc
source ~/.bashrc

之後就能用：

gm

Windows PowerShell 可以先開啟設定檔：

notepad $PROFILE

加入：

Set-Alias gm gemini

這個別名只是在你的終端機裡把 gm 展開成 gemini，方便啟動 CLI。它不是 Gemini CLI 內部的快捷指令。

裝完後怎麼驗證是否可用

不要一開始就把設定寫死在全域檔案裡。建議先開一個新的終端機，用臨時變數測試：

unset GEMINI_API_KEY GOOGLE_API_KEY
export GEMINI_API_KEY="服務商或官方提供的測試 Key"

如果服務商要求自訂 Base URL，再補上：

export GOOGLE_GEMINI_BASE_URL="https://你的中轉站位址"
gemini "用一句話說明你目前連到哪個模型"

基本問答能回覆後，再測這幾件事：

gemini -p "解釋這個程式碼庫的架構" 能不能正常返回。
gemini -m gemini-2.5-flash "hello" 能不能指定模型。
在專案目錄啟動 gemini，請它讀取一個小檔案，確認檔案上下文可用。
做一次低風險的程式碼解釋或生成任務，觀察串流輸出和工具呼叫是否正常。

只會聊天不代表完整可用。中轉站如果只相容一般 API 呼叫，可能能回答問題，卻在讀檔、工具呼叫或串流輸出時出錯。

接中轉站時要看哪些細節

我會先看服務商文件有沒有明確寫出三件事：

要設定的變數是不是 GEMINI_API_KEY。
中轉站位址是不是走 GOOGLE_GEMINI_BASE_URL。
首次啟動或 /auth 裡是否要選 Gemini API Key (AI Studio)。

如果文件只寫「支援 Gemini」或「相容 OpenAI 格式」，先不要直接當成 Gemini CLI 可用。那通常只代表它能用 OpenAI 相容介面呼叫 Gemini 模型，不等於 Gemini CLI 的檔案讀取、工具呼叫和串流能力都能正常跑。

常見錯誤與排查方向

401 / unauthorized：API 金鑰類型不對，或服務商不接受 Gemini CLI 送出的認證方式。
403 / permission denied：Key 能通過認證，但帳號、專案或模型權限不足。
404 / not found：Base URL 路徑不對，常見原因是 /v1 是否需要帶上。
model not found：模型別名和服務商公開的模型名稱不一致。
429 / too many requests：額度不足、觸發限流，或 CLI 在短時間內重複重試。
network error / timeout：本機網路、代理、中轉節點或上游服務逾時。
能聊天但不能改程式碼：多半只是一般補全介面相容，沒有完整支援 Gemini CLI 需要的工具呼叫或串流能力。

遇到 401 或 429 時，先不要急著換服務商。頁面底部有相關錯誤排查，可以先按 Key、Base URL、模型名、餘額和限流規則逐項確認。

可以用哪些工具提升便利性

如果你只接一個中轉站，手動寫 ~/.zshrc 就夠了。工具的價值主要出現在你經常切換 provider、Base URL、API 金鑰和模型名稱的時候。

例如 CC Switch 這類配置管理工具，可以把 Claude Code、Codex、Gemini CLI、OpenCode 的 provider 設定集中管理。

但順序要反過來想：先手動跑通最小設定，再交給工具管理。沒有驗證過的設定，不值得先放進工具裡整理。

下一步

真正值得看的 Gemini CLI 中轉站，不只是模型列表裡有 Gemini。它至少要把 API 金鑰類型、Base URL、支援模型、價格、付款方式和 Gemini CLI 設定方式寫清楚。模型名稱只是起點，能不能穩定跑 CLI 才是重點。

Gemini CLI Gemini API Base URL