hermes-agent/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/google-gemini.md

sidebar_position	title	description
16	Google Gemini	将 Hermes Agent 与 Google Gemini 配合使用——原生 AI Studio API、API 密钥配置、OAuth 选项、工具调用、流式传输及配额说明

Google Gemini

Hermes Agent 通过 Google AI Studio / Gemini API 原生支持 Google Gemini——而非 OpenAI 兼容端点。这使 Hermes 能够将其内部 OpenAI 格式的消息和工具循环转换为 Gemini 原生的 generateContent API，同时保留工具调用、流式传输、多模态输入以及 Gemini 特有的响应元数据。

Hermes 还支持独立的 Google Gemini（OAuth） provider，使用与 Google Gemini CLI 相同的 Cloud Code Assist 后端。如需最低风险的官方 API 路径，请使用 API 密钥 provider（gemini）。

前提条件

• Google AI Studio API 密钥 — 在 aistudio.google.com/apikey 创建
• 已启用计费的 Google Cloud 项目 — 推荐用于 Agent 场景。Gemini 免费层级对长时间运行的 Agent 会话而言配额过小，因为 Hermes 每次用户交互可能发起多次模型调用。
• 已安装 Hermes — 原生 Gemini provider 无需额外安装 Python 包。

:::tip API 密钥路径 设置 GOOGLE_API_KEY 或 GEMINI_API_KEY。Hermes 对 gemini provider 会同时检查这两个名称。 :::

快速开始

# 添加 Gemini API 密钥
echo "GOOGLE_API_KEY=..." >> ~/.hermes/.env

# 选择 Gemini 作为 provider
hermes model
# → 选择 "More providers..." → "Google AI Studio"
# → Hermes 检查密钥层级并显示 Gemini 模型列表
# → 选择一个模型

# 开始对话
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 仍以 OpenAI 格式维护 Agent 循环，然后将每个请求转换为 Gemini 原生 schema：

• messages[] → Gemini contents[]
• 系统提示（system prompt）→ Gemini systemInstruction
• 工具 schema → Gemini functionDeclarations
• 工具结果 → Gemini functionResponse 部分
• 流式响应 → 供 Hermes 循环使用的 OpenAI 格式流式数据块

:::note 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 兼容端点在你明确需要 OpenAI API 兼容性时仍然有用。

如果你之前将 GEMINI_BASE_URL 设置为 /openai URL，请将其删除或修改：

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 密钥 provider。

可用模型

hermes model 选择器显示 Hermes provider 注册表中维护的 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 并从当前列表中选择。

:::info 模型 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 条目，以防新用户在长时间运行的 Agent 会话中意外选择评估层级的模型。

常用评估 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 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 密钥。

诊断

hermes doctor

doctor 命令检查：

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

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

/gquota

/gquota 适用于 google-gemini-cli OAuth provider，不适用于 AI Studio API 密钥 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 密钥。请将以下任一项添加到 ~/.hermes/.env：

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

然后重新运行 hermes model。

"This Google API key is on the free tier"

Hermes 在设置期间会探测 Gemini API 密钥。由于工具调用、重试、压缩和辅助任务可能需要多次模型调用，免费层级配额在少数几轮 Agent 交互后即可耗尽。

请为与密钥关联的 Google Cloud 项目启用计费，必要时重新生成密钥，然后运行：

hermes model

"404 model not found"

所选模型对你的账号、地区或密钥不可用。重新运行 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 密钥路径不同。如需官方 API 密钥集成，请使用 provider: gemini 配合 GOOGLE_API_KEY。

工具调用因 schema 错误而失败

升级 Hermes 并重新运行 hermes model。原生 Gemini 适配器会针对 Gemini 更严格的函数声明格式对工具 schema 进行清理；旧版本或自定义端点可能不支持此功能。

相关链接

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