跳到主要內容

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 Previewgemini-3.1-pro-preview可用時功能最強大的預覽模型
Gemini 3 Pro Previewgemini-3-pro-preview強大的推理和編碼模型
Gemini 3 Flash Previewgemini-3-flash-preview推薦的速度與能力平衡默認選項
Gemini 3.1 Flash Lite Previewgemini-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 ITgemma-4-31b-it較大的 Gemma 模型；適用於兼容性和質量評估
Gemma 4 26B A4B ITgemma-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 更嚴格的函數聲明格式；舊版本構建或自定義端點可能不具備此功能。