<!-- Source: https://hermesbible.com/docs/guides/google-gemini -->

Hermes Agent 支援 Google Gemini 作為原生供應商，使用 Google AI Studio / Gemini API — 而非 OpenAI 相容端點。這讓 Hermes 將其內部 OpenAI 格式的訊息和工具迴圈翻譯為 Gemini 原生的 generateContent API，同時保留工具呼叫、串流、多模態輸入和 Gemini 特定的回應中繼資料。

Hermes 還支援一個獨立的 Google Gemini (OAuth) 供應商，使用與 Google 的 Gemini CLI 相同的 Cloud Code Assist 後端。使用 API 金鑰供應商（gemini）以獲得風險最低的官方 API 路徑。

前置需求

• Google AI Studio API 金鑰 — 在 aistudio.google.com/apikey 建立
• 啟用計費的 Google Cloud 專案 — 建議用於代理程式使用。Gemini 的免費層對於長時間運行的代理工作階段太小，因為 Hermes 每個使用者回合可能進行多次模型呼叫。
• Hermes 已安裝 — 原生 Gemini 供應商不需要額外的 Python 套件。

提示 — API 金鑰路徑

設定 GOOGLE_API_KEY 或 GEMINI_API_KEY。Hermes 為 gemini 供應商檢查兩個名稱。

快速開始

# 新增你的 Gemini API 金鑰
echo "GOOGLE_API_KEY=..." >> ~/.hermes/.env

# 選擇 Gemini 作為你的供應商
hermes model
# → 選擇 "More providers..." → "Google AI Studio"
# → Hermes 檢查你的金鑰層級並顯示 Gemini 模型
# → 選擇一個模型

# 開始聊天
hermes chat

如果你偏好直接編輯設定，使用原生 Gemini API 基礎 URL：

model:
  default: gemini-3-flash-preview
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

設定

執行 hermes model 後，你的 ~/.hermes/config.yaml 將包含：

model:
  default: gemini-3-flash-preview
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

以及在 ~/.hermes/.env 中：

GOOGLE_API_KEY=...

原生 Gemini API

建議的端點是：

https://generativelanguage.googleapis.com/v1beta

Hermes 偵測此端點並建立其原生 Gemini 適配器。在內部，Hermes 仍將代理迴圈保持在 OpenAI 格式的訊息中，然後將每個請求翻譯為 Gemini 的原生架構：

• messages[] → Gemini contents[]
• 系統提示詞 → Gemini systemInstruction
• 工具架構 → Gemini functionDeclarations
• 工具結果 → Gemini functionResponse 部分
• 串流回應 → 供 Hermes 迴圈使用的 OpenAI 格式串流區塊

注意 — Gemini 3 思考簽章

對於 Gemini 3 工具使用，Hermes 保留附加到函式呼叫部分的 thoughtSignature 值，並在下一個工具回合中重播它們。這涵蓋了多步驟代理工作流程的驗證關鍵路徑。

Gemini 3 可能也會將思考簽章附加到其他回應部分。Hermes 的原生適配器針對代理工具迴圈進行了最佳化，因此目前還無法以完整的部分級保真度重播每個非工具呼叫簽章。

優先使用原生端點

Google 也公開一個 OpenAI 相容端點：

https://generativelanguage.googleapis.com/v1beta/openai/

對於 Hermes 代理工作階段，優先使用上方的原生 Gemini 端點。Hermes 包含原生 Gemini 適配器，因此可以直接將多回合工具使用、工具呼叫結果、串流、多模態輸入和 Gemini 回應中繼資料對應到 Gemini 的 generateContent API。當你特別需要 OpenAI API 相容性時，OpenAI 相容端點仍然有用。

如果你先前將 GEMINI_BASE_URL 設定為 /openai URL，請移除它或更改為：

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta

OAuth 供應商

Hermes 還有一個 google-gemini-cli 供應商：

hermes model
# → 選擇 "Google Gemini (OAuth)"

這使用瀏覽器 PKCE 登入和 Cloud Code Assist 後端。對於想要 Gemini CLI 風格 OAuth 的使用者可能有用，但 Hermes 會顯示明確警告，因為 Google 可能將第三方軟體使用 Gemini CLI OAuth 客戶端視為違反政策。對於生產環境或最低風險的使用，優先使用上方的 API 金鑰供應商。

可用模型

hermes model 選擇器顯示維護在 Hermes 供應商註冊表中的 Gemini 模型。常見選擇包括：

模型可用性會隨時間變化。如果模型消失或未為你的金鑰啟用，再次執行 hermes model 並從當前清單中選擇一個。

資訊 — 模型 ID

使用 Gemini 的原生模型 ID 如 gemini-3-flash-preview，而非 OpenRouter 風格的 ID 如 google/gemini-3-flash-preview，當 provider: gemini 時。

最新別名

Google 為 Pro 和 Flash Gemini 系列發佈移動別名。當你希望 Google 在不更改 Hermes 設定的情況下自動推進模型時，gemini-pro-latest 和 gemini-flash-latest 很有用。

model:
  default: gemini-pro-latest
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

如果你需要嚴格的可重現性，優先使用明確的模型 ID 如 gemini-3.1-pro-preview 或 gemini-3-flash-preview。

透過 Gemini API 使用 Gemma

Google 也透過 Gemini API 公開 Gemma 模型。Hermes 將這些識別為 Google 模型，但從預設模型選擇器中隱藏非常低吞吐量的 Gemma 條目，以免新使用者意外為長時間運行的代理工作階段選擇評估級模型。

有用的評估 ID 包括：

這些模型最好作為 Gemini API 金鑰上的評估選項。Google 的 Gemma API 定價僅限免費層，使用上限與生產 Gemini 模型相比較低，因此持續的 Hermes 代理使用通常應轉向付費 Gemini 模型、自託管部署或其他具有適當配額的供應商。

要使用選擇器中隱藏的 Gemma 模型，直接設定：

model:
  default: gemma-4-31b-it
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

在工作階段中途切換模型

在對話期間使用 /model 指令：

/model gemini-3-flash-preview
/model gemini-flash-latest
/model gemini-3-pro-preview
/model gemini-pro-latest
/model gemma-4-31b-it
/model gemini-3.1-flash-lite-preview

如果你尚未設定 Gemini，請先退出工作階段並執行 hermes model。/model 在已設定的供應商和模型之間切換；它不會收集新的 API 金鑰。

診斷

hermes doctor

doctor 檢查：

• GOOGLE_API_KEY 或 GEMINI_API_KEY 是否可用
• google-gemini-cli 是否存在 Gemini OAuth 憑證
• 已設定的供應商憑證是否可解析

要查看 OAuth 配額使用情況，在 Hermes 工作階段內執行：

/gquota

/gquota 適用於 google-gemini-cli OAuth 供應商，而非 AI Studio API 金鑰供應商。

閘道（訊息平台）

Gemini 與所有 Hermes 閘道平台（Telegram、Discord、Slack、WhatsApp、LINE、Feishu 等）配合使用。將 Gemini 設定為你的供應商，然後正常啟動閘道：

hermes gateway setup
hermes gateway start

閘道讀取 config.yaml 並使用相同的 Gemini 供應商設定。

疑難排解

「Gemini native client requires an API key」

Hermes 找不到可用的 API 金鑰。在 ~/.hermes/.env 中新增以下其中一個：

GOOGLE_API_KEY=...
# 或
GEMINI_API_KEY=...

然後再次執行 hermes model。

「This Google API key is on the free tier」

Hermes 在設定期間探測 Gemini API 金鑰。免費層配額在幾個代理回合後可能耗盡，因為工具使用、重試、壓縮和輔助任務可能需要多次模型呼叫。

在附加到你金鑰的 Google Cloud 專案上啟用計費，必要時重新產生金鑰，然後執行：

hermes model

「404 model not found」

所選模型對你的帳戶、區域或金鑰不可用。再次執行 hermes model 並從當前清單中選擇另一個 Gemini 模型。

Gemma 模型未在 hermes model 中顯示

Hermes 可能會預設隱藏低吞吐量的 Gemma 模型。如果你有意要評估其中一個，請在 ~/.hermes/config.yaml 中直接設定模型 ID。

Gemma 上出現「429 quota exceeded」

透過 Gemini API 公開的 Gemma 模型適用於評估，但它們的 Gemini API 免費層上限較低。將它們用於相容性測試，然後切換到付費 Gemini 模型或其他供應商以進行持續的代理工作階段。

設定了 OpenAI 相容端點

檢查 ~/.hermes/.env 中是否有：

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/

將其更改為原生端點或移除覆寫：

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta

OAuth 登入警告

google-gemini-cli 供應商使用 Gemini CLI / Cloud Code Assist OAuth 流程。Hermes 在啟動前發出警告，因為這與官方 AI Studio API 金鑰路徑不同。使用 provider: gemini 搭配 GOOGLE_API_KEY 進行官方 API 金鑰整合。

工具呼叫因架構錯誤失敗

升級 Hermes 並重新執行 hermes model。原生 Gemini 適配器為 Gemini 更嚴格的函式宣告格式清理工具架構；較舊的建置或自訂端點可能無法做到。

相關

• AI 供應商
• 設定
• 備用供應商
• AWS Bedrock — 使用 AWS 憑證的原生雲端供應商整合

---

---

使用 Ollama 在本機執行 Hermes — 零 API 成本