Hermes Agent 接入 Google Gemini：谷歌 AI 模型集成指南

Hermes Agent 原生支持 Google Gemini 作为推理后端，采用 Google AI Studio / Gemini API 接入方式，而非 OpenAI 兼容端点。Hermes 会将内部基于 OpenAI 格式的消息和工具循环转换为 Gemini 原生的 generateContent API，同时完整保留 tool calling、流式输出、多模态输入以及 Gemini 特有的响应元数据。

Hermes 还提供了一个独立的 Google Gemini (OAuth) provider，使用与 Google Gemini CLI 相同的 Cloud Code Assist 后端。建议使用 API Key 方式（gemini provider）作为最稳妥的官方 API 接入路径。

前置条件

• Google AI Studio API Key — 在 aistudio.google.com/apikey 创建
• 已启用计费的 Google Cloud 项目 — 强烈建议用于 Agent 场景。Gemini 免费额度对长时间运行的 Agent 会话来说远远不够，因为 Hermes 每个用户轮次可能需要多次模型调用
• 已安装 Hermes — 原生 Gemini provider 无需安装额外的 Python 包

:::tip API Key 环境变量 设置 GOOGLE_API_KEY 或 GEMINI_API_KEY 均可，Hermes 会同时检查这两个变量名。 :::

快速开始

# 添加你的 Gemini API Key
echo "GOOGLE_API_KEY=..." >> ~/.hermes/.env

# 选择 Gemini 作为 provider
hermes model
# → 选择 "More providers..." → "Google AI Studio"
# → Hermes 会检测你的 Key 层级并显示可用模型
# → 选择一个模型

# 开始对话
hermes chat

如果你更倾向于直接编辑配置文件，使用原生 Gemini API base 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

推荐的端点地址为：

Hermes 检测到此端点后会自动创建原生 Gemini 适配器。内部仍然保持基于 OpenAI 格式的 Agent 循环，然后将每个请求转换为 Gemini 原生格式：

• messages[] → Gemini contents[]
• system prompts → Gemini systemInstruction
• tool schemas → Gemini functionDeclarations
• tool results → Gemini functionResponse parts
• streaming responses → OpenAI 格式的流式数据块，供 Hermes 循环使用

:::note Gemini 3 thought signatures 在 Gemini 3 的 tool use 场景中，Hermes 会保留附加在 function-call parts 上的 thoughtSignature 值，并在下一次 tool turn 中回传。这确保了多步 Agent 工作流中关键的验证路径正确运行。

Gemini 3 可能还会将 thought signatures 附加到其他响应部分。Hermes 的原生适配器目前针对 Agent 工具循环进行了优化，尚未对所有非 tool-call 的 signature 实现完整的 part 级别回放。 :::

优先使用原生端点

Google 也提供了一个 OpenAI 兼容端点：

对于 Hermes Agent 会话，建议优先使用上面提到的原生 Gemini 端点。Hermes 内置了原生 Gemini 适配器，可以将多轮 tool use、tool-call 结果、流式输出、多模态输入和 Gemini 响应元数据直接映射到 Gemini 的 generateContent API。OpenAI 兼容端点在你明确需要 OpenAI API 兼容性时才有用。

如果你之前将 GEMINI_BASE_URL 设置为 /openai 地址，请移除或修改它：

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

OAuth Provider

Hermes 还提供了 google-gemini-cli provider：

hermes model
# → 选择 "Google Gemini (OAuth)"

该方式使用浏览器 PKCE 登录和 Cloud Code Assist 后端。对于希望通过 Gemini CLI 风格 OAuth 登录的用户可能有帮助，但 Hermes 会显示明确的警告，因为 Google 可能将第三方软件使用 Gemini CLI OAuth 客户端视为违反政策。生产环境或最低风险场景下，请优先使用上述 API Key 方式。

可用模型

hermes model 选择器会显示 Hermes provider 注册表中维护的 Gemini 模型。常用选择包括：

模型可用性会随时间变化。如果某个模型消失或你的 Key 未启用，请重新运行 hermes model 并从当前列表中选择。

:::info 模型 ID 使用 provider: gemini 时，请使用 Gemini 原生模型 ID（如 gemini-3-flash-preview），而非 OpenRouter 风格的 ID（如 google/gemini-3-flash-preview）。 :::

最新模型别名

Google 为 Pro 和 Flash Gemini 系列发布了动态别名。gemini-pro-latest 和 gemini-flash-latest 在你希望 Google 自动升级模型而不修改 Hermes 配置时非常有用。

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 条目，避免新用户误选评估级模型用于长时间运行的 Agent 会话。

常用的评估 ID 包括：

这些模型最好仅作为 Gemini API Key 上的评估选项。Google 的 Gemma API 定价仅为免费层，使用上限远低于生产级 Gemini 模型。持续的 Hermes Agent 使用应转向付费 Gemini 模型、自托管部署或其他具有适当配额的 provider。

要使用被选择器隐藏的 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 仅在已配置的 provider 和模型之间切换，不会收集新的 API Key。

诊断

hermes doctor

诊断检查项包括：

• GOOGLE_API_KEY 或 GEMINI_API_KEY 是否可用
• google-gemini-cli 是否存在 Gemini OAuth 凭据
• 已配置的 provider 凭据是否能被正确解析

查看 OAuth 配额使用情况，在 Hermes 会话中运行：

/gquota 适用于 google-gemini-cli OAuth provider，不适用于 AI Studio API Key provider。

Gateway（消息平台）

Gemini 可与所有 Hermes Gateway 平台（Telegram、Discord、Slack、WhatsApp、LINE、飞书等）配合使用。配置 Gemini 为你的 provider 后，正常启动 Gateway 即可：

hermes gateway setup
hermes gateway start

Gateway 会读取 config.yaml，使用相同的 Gemini provider 配置。

故障排除

"Gemini native client requires an API key"

Hermes 找不到可用的 API Key。请在 ~/.hermes/.env 中添加以下之一：

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

然后重新运行 hermes model。

"This Google API key is on the free tier"

Hermes 在设置时会探测 Gemini API Key 的层级。免费层配额在少数几个 Agent 轮次后就可能耗尽，因为 tool use、重试、压缩和辅助任务可能需要多次模型调用。

请在与你的 Key 关联的 Google Cloud 项目上启用计费，必要时重新生成 Key，然后运行：

hermes model

"404 model not found"

所选模型在你的账户、区域或 Key 下不可用。重新运行 hermes model，从当前列表中选择其他 Gemini 模型。

Gemma 模型未在 hermes model 中显示

Hermes 默认可能隐藏低吞吐量的 Gemma 模型。如果你确实需要评估某个模型，请在 ~/.hermes/config.yaml 中直接设置模型 ID。

Gemma 模型出现 "429 quota exceeded"

通过 Gemini API 提供的 Gemma 模型适合评估使用，但其 Gemini API 免费层上限很低。请用于兼容性测试，然后切换到付费 Gemini 模型或其他 provider 用于持续的 Agent 会话。

配置了 OpenAI 兼容端点

检查 ~/.hermes/.env 中是否存在：

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

将其更改为原生端点或移除该覆盖设置：

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

OAuth 登录警告

google-gemini-cli provider 使用 Gemini CLI / Cloud Code Assist OAuth 流程。Hermes 在启动前会发出警告，因为此方式与官方 AI Studio API Key 路径不同。请使用 provider: gemini 配合 GOOGLE_API_KEY 进行官方 API Key 集成。

Tool Calling 出现 Schema 错误

升级 Hermes 并重新运行 hermes model。原生 Gemini 适配器会为 Gemini 更严格的 function-declaration 格式清理 tool schema；旧版本或自定义端点可能不会。

相关资源

• AI Providers
• Configuration
• Fallback Providers
• AWS Bedrock — 使用 AWS 凭证的原生云 provider 集成