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 路徑，請使用 API 密鑰提供商（gemini）。

前提條件

• Google AI Studio API 密鑰 — 在 aistudio.google.com/apikey 創建一個
• 已啟用計費的 Google Cloud 項目 — 建議用於 Agent 使用。Gemini 的免費層級對於長時間運行的 Agent 會話來說太小了，因為 Hermes 可能在每個用戶回合中進行多次模型調用。
• 已安裝 Hermes — 原生 Gemini 提供商不需要額外的 Python 包。

API 密鑰路徑

設置 GOOGLE_API_KEY 或 GEMINI_API_KEY。Hermes 會檢查 gemini 提供商的這兩個名稱。

快速開始

# Add your Gemini API key
echo "GOOGLE_API_KEY=..." >> ~/.hermes/.env

# Select Gemini as your provider
hermes model
# → Choose "More providers..." → "Google AI Studio"
# → Hermes checks your key tier and shows Gemini models
# → Select a model

# Start chatting
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 仍然保持 Agent 循環使用 OpenAI 格式的消息，然後將每個請求轉換為 Gemini 的原生架構：

• messages[] → Gemini contents[]
• 系統提示詞 → Gemini systemInstruction
• 工具架構 → Gemini functionDeclarations
• 工具結果 → Gemini functionResponse 部分
• 流式響應 → 適用於 Hermes 循環的 OpenAI 格式流塊

Gemini 3 思維簽名

對於 Gemini 3 的工具使用，Hermes 會保留附加到函數調用部分的 thoughtSignature 值，並在下一個工具回合中重放它們。這涵蓋了多步 Agent 工作流中驗證關鍵路徑的需求。

Gemini 3 還可能將思維簽名附加到其他響應部分。Hermes 的原生適配器目前針對 Agent 工具循環進行了優化，因此尚未以完整的部分級保真度重放每個非工具調用的簽名。

優先使用原生端點

Google 還提供了一個 OpenAI 兼容端點：

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

對於 Hermes Agent 會話，請優先使用上述原生 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
# → Choose "Google Gemini (OAuth)"

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

可用模型

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

模型	ID	備註
Gemini 3.1 Pro Preview	gemini-3.1-pro-preview	可用時功能最強大的預覽模型
Gemini 3 Pro Preview	gemini-3-pro-preview	強大的推理和編碼模型
Gemini 3 Flash Preview	gemini-3-flash-preview	推薦的速度與能力平衡默認選項
Gemini 3.1 Flash Lite Preview	gemini-3.1-flash-lite-preview	可用時最快/最低成本選項

模型可用性會隨時間變化。如果模型消失或未為您的密鑰啟用，請再次運行 hermes model 並從當前列表中選擇一個。

模型 ID

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

最新別名

Google 為 Pro 和 Flash Gemini 系列發佈動態別名。當您希望 Google 自動升級模型而無需更改 Hermes 配置時，gemini-pro-latest 和 gemini-flash-latest 非常有用。

別名	當前跟蹤	備註
gemini-pro-latest	最新 Gemini Pro 模型	當您希望使用 Google 當前的 Pro 默認模型時的最佳選擇
gemini-flash-latest	最新 Gemini Flash 模型	當您希望使用 Google 當前的 Flash 默認模型時的最佳選擇

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 包括：

模型	ID	備註
Gemma 4 31B IT	gemma-4-31b-it	較大的 Gemma 模型；適用於兼容性和質量評估
Gemma 4 26B A4B IT	gemma-4-26b-a4b-it	可用時較小的激活參數變體

這些模型最好被視為 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、飛書等）。將 Gemini 配置為你的提供商，然後正常啟動網關：

hermes gateway setup
hermes gateway start

網關讀取 config.yaml 並使用相同的 Gemini 提供商配置。

故障排除

"Gemini native client requires an API key"（Gemini 原生客戶端需要 API 密鑰）

Hermes 找不到可用的 API 密鑰。將以下其中之一添加到 ~/.hermes/.env：

GOOGLE_API_KEY=...
# or
GEMINI_API_KEY=...

然後再次運行 hermes model。

"This Google API key is on the free tier"（此 Google API 密鑰處於免費層級）

Hermes 在設置過程中會探測 Gemini API 密鑰。由於工具使用、重試、壓縮和輔助任務可能需要多次模型調用，免費層級的配額可能在幾次代理交互後耗盡。

在與你的密鑰關聯的 Google Cloud 項目上啟用計費，必要時重新生成密鑰，然後運行：

hermes model

"404 model not found"（404 模型未找到）

所選模型對你的賬戶、區域或密鑰不可用。再次運行 hermes model 並從當前列表中選擇另一個 Gemini 模型。

Gemma 模型未顯示在 hermes model 中

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

Gemma 出現 "429 quota exceeded"（429 超出配額）

通過 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 密鑰路徑。對於官方 API 密鑰集成，請將 provider 設置為 gemini 並使用 GOOGLE_API_KEY。

工具調用因架構錯誤而失敗

升級 Hermes 並重新運行 hermes model。原生 Gemini 適配器會對工具架構進行清理，以符合 Gemini 更嚴格的函數聲明格式；舊版本構建或自定義端點可能不具備此功能。

相關資源

• AI 提供商
• 配置
• 回退提供商
• AWS Bedrock — 使用 AWS 憑據的原生雲提供商集成