跳到主要内容

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 更严格的函数声明格式；旧版本构建或自定义端点可能不具备此功能。