---
title: 如何为 Hermes Agent 添加自定义提供商（2026）
description: >-
  将 Hermes Agent 连接到任何 OpenAI 兼容的提供商——MiniMax、DeepSeek、Gemini、Grok、OpenAI 或
  haimaker.ai。涵盖基础 URL、API 密钥配置和超时问题排查。
date: 2026-05-11T00:00:00.000Z
updatedDate: 2026-06-26T00:00:00.000Z
location: 美国加利福尼亚州旧金山 – 2026 年 5 月 11 日
image: /images/hermes-custom-provider-setup-hero.jpg
keywords: >-
  hermes agent 自定义提供商, hermes agent 提供商配置, hermes agent api 密钥, hermes agent
  minimax 提供商配置, hermes agent gemini api, hermes agent deepseek 配置, hermes agent
  grok api, hermes 自定义端点, hermes agent openai 兼容 api
faq:
  - question: 如何为 Hermes Agent 添加自定义提供商？
    answer: >-
      在终端中运行 `hermes model`，选择“Custom endpoint”（自定义端点），然后依次输入三项内容：提供商的基础 URL（以
      /v1 结尾）、你的 API 密钥和模型标识符。Hermes 会保存该配置并在后续每次运行中使用。任何支持 OpenAI 兼容
      /v1/chat/completions
      端点的提供商都可以接入——MiniMax、DeepSeek、Google、xAI、OpenAI、OpenRouter、本地 Ollama 实例或
      haimaker.ai。对于 haimaker.ai，只需运行 npx -y @haimaker/connect --hermes
      即可一条命令完成配置。
  - question: Hermes Agent 需要什么基础 URL？
    answer: >-
      Hermes 需要的是 OpenAI 兼容的根路径，而非完整的 chat-completions 路径。haimaker 使用
      https://api.haimaker.ai/v1，MiniMax，MiniMax，MiniMax，MiniMax 使用
      https://api.minimax.io/v1，DeepSeek，DeepSeek，DeepSeek，DeepSeek 使用
      https://api.deepseek.com/v1，Gemini，Gemini，Gemini，Gemini 的 OpenAI 兼容层使用
      https://generativelanguage.googleapis.com/v1beta/openai，xAI，xAI，xAI，xAI
      Grok 使用 https://api.x.ai/v1，OpenAI，OpenAI，OpenAI，OpenAI 使用
      https://api.openai.com/v1，Ollama，Ollama，Ollama，Ollama 使用
      http://localhost:11434/v1。Hermes。Hermes。Hermes。Hermes 会自行拼接
      /chat/completions。
  - question: 为什么我的 Hermes 自定义提供商会超时？
    answer: >-
      在较慢的提供商上执行较长的 Agent 步骤时，可能会超出 Hermes 默认的读取超时时间。在启动 Hermes 之前，将
      HERMES_STREAM_READ_TIMEOUT 环境变量（单位为秒）设置为更大的值，并确认你的基础 URL 以 /v1
      结尾且没有尾部斜杠。如果返回 401 而非超时，说明 API 密钥未生效——重新运行 `hermes model` 并重新输入密钥。
locale: zh-cn
translationKey: hermes-custom-provider-setup
---
Hermes Agent 虽然内置的提供商数量不多，但它真正的灵活之处来自 **Custom endpoint** 选项：任何支持 OpenAI chat-completions 格式的服务，只需一个基础 URL、一个密钥和一个模型名称即可接入。覆盖范围包括 MiniMax、DeepSeek、Google Gemini、xAI Grok、OpenAI、OpenRouter、私有 vLLM 服务器、本地 Ollama 实例，以及 [haimaker.ai](https://haimaker.ai)——通过它可以一站式接入上述所有模型。

下面先介绍通用配置方法，再给出大家最常问的各提供商的具体参数值。

## 通用方法

Hermes 中每个自定义提供商都遵循相同的三步配置流程：

```bash
hermes model
```

1. 从菜单中选择 **Custom endpoint**。
2. 输入**基础 URL**——即 OpenAI 兼容的根路径，以 `/v1` 结尾（Hermes 会自行拼接 `/chat/completions`）。
3. 输入该提供商的 **API 密钥**。
4. 输入提供商要求的**模型标识符**。

Hermes 会保存该配置并在后续每次运行中使用。如需更换提供商，再次运行 `hermes model` 即可。流程就这么简单——本文其余部分只是帮你把各项参数填对。

模型要在 Hermes 中表现良好，需要能正确遵循工具调用 Schema，并且有足够的上下文窗口来支撑 Agent 的多轮循环——建议至少约 64K 可用上下文。关于具体该选哪个模型，请参阅 [Hermes Agent 最佳模型推荐](/blog/best-models-for-hermes/)。

## haimaker.ai——一个密钥接入所有模型

无需为每个提供商分别管理账户、密钥和基础 URL，只需将 Hermes 指向 haimaker.ai 一次，之后改一个字符串就能切换模型。最快的配置方式是一条命令：

```bash
export HAIMAKER_API_KEY=your-haimaker-key
npx -y @haimaker/connect --hermes
```

[`@haimaker/connect`](/connect) 会写入 Hermes 的自定义端点配置并验证密钥，然后退出。添加 `--model` 可固定某个模型，添加 `--pick-model` 可交互式选择模型，运行 `npx @haimaker/connect --uninstall --hermes` 可撤销配置。请先在 [app.haimaker.ai](https://app.haimaker.ai/sign-up) 获取密钥；新账户附带免费额度。

如果你更习惯使用内置的 `hermes model` 流程，可以在提示时输入以下值：

- **基础 URL：** `https://api.haimaker.ai/v1`
- **API 密钥：** 你的 haimaker.ai 密钥
- **模型：** 任何受支持的模型，例如 `anthropic/claude-sonnet-4-6`、`openai/gpt-5-4-codex`、`google/gemini-3-1-pro`、`minimax/minimax-m2-5`、`deepseek/deepseek-v3-2`、`xai/grok-4-1-fast`、`zai/glm-4-7`、`moonshot/kimi-k2-5`

模型价格比市场价低约 5%，且只需管理一个计费账户。

## 在 Hermes 中使用 MiniMax

MiniMax M2.5 是 Hermes 中广受欢迎的高性价比之选——价格足够低，可以长时间运行；能力也足以应对工具循环。

- **基础 URL：** `https://api.minimax.io/v1`
- **API 密钥：** 从 MiniMax 平台控制台获取
- **模型：** `MiniMax-M2.5`（请使用 MiniMax 控制台中显示的精确 ID——注意大小写）

或者通过 haimaker.ai 使用模型 `minimax/minimax-m2-5` 来接入 MiniMax，无需单独注册账户。

## 在 Hermes 中使用 Google Gemini

Gemini 提供了 OpenAI 兼容层，因此可以直接作为 Hermes 的自定义端点使用。

- **基础 URL：** `https://generativelanguage.googleapis.com/v1beta/openai`
- **API 密钥：** 你的 Google AI Studio 密钥
- **模型：** `gemini-3-flash` 适合低成本、快速的任务；`gemini-3.1-pro` 适合长上下文研究

是的，Hermes Agent 确实可以通过这种方式接入 Google Gemini——无需启用单独的 Gemini 集成，它就是一个自定义端点。或者通过 haimaker.ai 使用 `google/gemini-3-1-pro`。

## 在 Hermes 中使用 DeepSeek

- **基础 URL：** `https://api.deepseek.com/v1`
- **API 密钥：** 从 DeepSeek 平台获取
- **模型：** `deepseek-chat`（指向当前 V3.2 系列）或 `deepseek-reasoner`

通过 haimaker.ai：`deepseek/deepseek-v3-2`。

## 在 Hermes 中使用 xAI Grok

- **基础 URL：** `https://api.x.ai/v1`
- **API 密钥：** 从 xAI 控制台获取
- **模型：** `grok-4.1-fast` 适合低成本大上下文任务，`grok-code-fast` 适合代码相关任务

通过 haimaker.ai：`xai/grok-4-1-fast`。

## 在 Hermes 中使用 OpenAI / Codex 模型

如果你想在 Hermes 中使用 OpenAI 自家的模型（包括 Codex 系列）：

- **基础 URL：** `https://api.openai.com/v1`
- **API 密钥：** OpenAI 的 **API** 密钥（ChatGPT Plus 订阅不包含 API 使用权限——你需要一个单独启用了计费的 API 密钥）
- **模型：** `gpt-5.4-codex` 适合编程，`gpt-5.4` 适合通用任务

通过 haimaker.ai：`openai/gpt-5-4-codex`。

## 通过 Ollama 使用本地模型

- **基础 URL：** `http://localhost:11434/v1`
- **API 密钥：** 任意非空字符串（Ollama 会忽略它，但 Hermes 要求填写一个值）
- **模型：** `gemma4:latest`、`qwen3.5:latest`，或你已拉取的任何模型

```bash
ollama pull gemma4
hermes model   # Custom endpoint → base URL above → model gemma4:latest
```

## 常见问题

- **长步骤超时。** 较慢的提供商在执行较长的 Agent 任务时可能超出 Hermes 默认的流式读取超时时间。在启动 Hermes 之前将 `HERMES_STREAM_READ_TIMEOUT`（秒）设置为更大的值。
- **401/认证错误。** 密钥未生效，或者你粘贴的是控制台/会话令牌而非 API 密钥。重新运行 `hermes model` 并重新输入。
- **请求返回 404。** 你的基础 URL 可能已经包含了 `/chat/completions`，或者末尾有斜杠。Hermes 会自行拼接路径——URL 应以 `/v1` 结尾。
- **工具调用反复失败。** 这通常是模型的问题，而非配置问题。小模型在处理工具调用 Schema 时容易出现偏差；建议升级到更强的模型。

## 获取你的 haimaker.ai 密钥

新账户可获得免费额度用于测试。在 [haimaker.ai](https://haimaker.ai) 浏览所有受支持的模型及其实时定价和基准测试结果，然后运行 `npx -y @haimaker/connect --hermes` 将 Hermes 指向它。

<a href="https://app.haimaker.ai/sign-up?utm_source=hermes_blog&utm_medium=cta&utm_campaign=hermes_custom_provider" class="cta-button">在 HAIMAKER 领取 $10 免费额度</a>

---

*相关阅读：[Hermes Agent 最佳模型推荐](/blog/best-models-for-hermes/) · [Hermes Agent 定价](/blog/hermes-api-costs-pricing/) · [Hermes Agent 与 Codex CLI 对比](/blog/hermes-vs-codex/)*