sidebar_position: 16 title: “Google Gemini” description: “Use Hermes Agent with Google Gemini — native AI Studio API, API-key setup, tool calling, streaming, and quota guidance”

Google Gemini

Hermes Agent 支持将 Google Gemini 作为原生提供商使用，它通过 Google AI Studio / Gemini API 进行连接——而非兼容 OpenAI 的接口。这样一来，Hermes 能够将其内部的基于 OpenAI 的消息处理与工具调用机制转换为 Gemini 原生的 generateContent API，同时保留工具调用、流式处理、多模态输入以及 Gemini 特有的响应元数据功能。

先决条件

Google AI Studio API 密钥——请在 aistudio.google.com/apikey 处创建密钥。
已开启计费的 Google Cloud 项目——推荐用于运行 Agent。由于 Hermes 在每次用户交互中可能会多次调用模型，Gemini 的免费套餐容量有限，无法支持长时间运行的 Agent 会话。
已安装 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 基础地址：

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

配置

运行 hermes model 后，您的 ~/.hermes/config.yaml 文件中将包含以下内容：

model:
  default: gemini-3.7-flash
  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格式流式数据块

诸如"type": ["number", "null"]这样的工具参数类型数组会被转换为Gemini的标量类型加上nullable属性形式。对于多类型联合类型，所有可选类型都会通过anyOf被保留下来，包括嵌套属性和数组元素。这一转换过程是自动完成的，无需修改MCP服务器或提供者的配置。: ::注意 Gemini 3的思维签名在使用Gemini 3的工具时，Hermes会保留函数调用部分附带的thoughtSignature值，并在后续工具调用时重新使用这些值。这有助于确保多步骤智能体工作流的验证流程正常运行。
Gemini 3也可以为其他响应部分添加思维签名。由于Hermes的专用适配器目前主要是为智能体工具循环优化的，因此它还无法以完整的字段级精度重新呈现所有非函数调用部分的思维签名。: ::

建议使用原生端点

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

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

对于 Hermes Agent 会话，建议优先使用上述原生 Gemini 接口。Hermes 内置了专用的 Gemini 适配器，能够将多轮对话中的工具使用、工具调用结果、流式数据、多模态输入以及 Gemini 的响应元数据直接映射到 Gemini 的 generateContent API 中。而当您确实需要 OpenAI API 兼容性时，兼容 OpenAI 的接口依然十分有用。

如果您之前将 GEMINI_BASE_URL 设置为 /openai 格式的地址，请将其删除或进行修改：

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

可用模型

hermes model 选择器会显示存储在 Hermes 提供商注册表中的 Gemini 模型。常见的可选模型包括：

模型	ID	备注
Gemini 3.8 Flash	`gemini-3.8-flash`	具备最强能力的 Flash 模型，适用于需要长时序处理的任务及编程工作
Gemini 3.7 Flash	`gemini-3.7-flash`	在速度、能力与多模态理解能力之间达到最佳平衡的推荐默认选项
Gemini 3.1 Pro Preview	`gemini-3.1-pro-preview`	推理、数学运算及编程能力最强的模型
Gemini 3.5 Flash Lite	`gemini-3.5-flash-lite`	适用于轻量级任务的最快且成本最低的选项
Gemini 2.5 Flash	`gemini-2.5-flash`	具备思考能力的上一代快速模型
Gemini 2.5 Pro	`gemini-2.5-pro`	用于复杂推理任务的上一代模型

可用模型列表会随时间发生变化。如果某个模型不再可用或未针对您的密钥启用，可再次运行 hermes model，从当前列表中选择其他模型。: ::info 模型 ID 当使用 provider: gemini 时，请使用 Gemini 的原生模型 ID，如 gemini-3.7-flash，而非 OpenRouter 风格的 ID，例如 google/gemini-3.7-flash。; ::

别名	当前追踪的模型	备注
`gemini-pro-latest`	最新的 Gemini Pro 模型	适用于需要使用谷歌当前默认的 Pro 版模型时
`gemini-flash-latest`	最新的 Gemini Flash 模型	适用于需要使用谷歌当前默认的 Flash 版模型时

通过 Gemini API 使用 Gemma 模型

Google 还通过 Gemini API 提供 Gemma 模型。Hermes 会将这些模型识别为 Google 的模型，但会隐藏那些吞吐量极低的 Gemma 模型选项，避免新用户在不经意间为长时间运行的智能体会话选择评估版模型。

常用的评估模型编号如下：

模型	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.7-flash
/model gemini-flash-latest
/model gemini-3.1-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

医生会检查以下内容：

是否存在 GOOGLE_API_KEY 或 GEMINI_API_KEY
配置的提供者凭证是否能够被成功解析

网关（消息平台）

Gemini 支持所有 Hermes 网关平台（Telegram、Discord、Slack、WhatsApp、LINE、飞书等）。只需将 Gemini 配置为你的提供者，即可正常启动网关：

hermes gateway setup
hermes gateway start

网关会读取 config.yaml 文件，并使用相同的 Gemini 提供商配置。

故障排除

“Gemini 原生客户端需要 API 密钥”

Hermes 未找到可用的 API 密钥。请在 ~/.hermes/.env 文件中添加以下任意一个密钥：

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

接着再次运行 hermes model 命令。

“此 Google API 密钥处于免费套餐层级”

Hermes 在初始化时会检测 Gemini API 密钥的属性。由于工具调用、重试操作、数据压缩以及各类辅助任务都可能需要多次模型调用，因此仅仅几次智能体交互后就可能会用完免费套餐的调用限额。

请在关联该密钥的 Google Cloud 项目中开启计费功能，必要时重新生成密钥，之后再运行相应命令：

hermes model

“404：未找到模型”

您当前使用的账户、地区或密钥无法访问所选模型。请再次运行 hermes model 命令，从现有列表中选择其他 Gemini 模型。

在 `hermes model` 中看不到 Gemma 模型

Hermes 默认会隐藏那些吞吐量较低的 Gemma 模型，以免出现在选择列表中。如果您确实想要测试这类模型，可直接在 ~/.hermes/config.yaml 文件中指定该模型的 ID。

使用 Gemma 时出现“429：配额已用尽”的错误

通过 Gemini API 提供的 Gemma 模型虽适合用于测试，但其免费套餐的调用限额较低。建议将其用于兼容性测试，若需维持长时间的智能体会话，则应切换到付费的 Gemini 模型或其他服务提供商的模型。

已配置 OpenAI 兼容的端点

请检查 ~/.hermes/.env 文件中的相关设置：

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

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

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

工具调用因架构错误而失败

请升级 Hermes 并重新运行 hermes model 命令。内置的 Gemini 适配器会按照 Gemini 更严格的函数声明格式对工具架构进行优化处理；而旧版本或自定义端点可能无法做到这一点。

Hermes Agent Docs i18n