Hermes Agent 配置自定义 AI 模型

Hermes Agent 是 Nous Research 开源的自进化 AI 智能体框架，内置模型切换功能。你可以接入 API 中转站，获得更灵活的模型选择和成本控制。本文介绍两种接入方式的完整操作步骤。

一、准备工作

你需要从 API 中转站获取以下三个信息：

这三个信息通常在中转站的「令牌管理」和「模型广场」页面可以找到。

另外还需要确认一件事——你的中转站走哪种协议：

💡 不确定的话选 chat_completions，绝大多数中转站都是这个。Claude 模型如果走这个协议调不通，再换 anthropic_messages。

二、方式一：通过 CLI 向导配置（推荐新手）

Hermes 内置了模型选择向导，一步步选就行，最简单。

步骤 1：启动模型选择

在终端运行：

hermes model

步骤 2：选择服务商

你会看到一个列表，包含 Nous Portal、OpenRouter、OpenAI、Anthropic 等内置服务商。

如果要接入第三方中转站，选择 「Custom endpoint (self-hosted / VLLM / etc.)」（自定义端点）。

步骤 3：填写信息

向导会依次问你：

1. API base URL — 填你的中转站地址

- OpenAI 兼容格式：填 https://api.xxxx.com/v1（一般要加 /v1）
- Anthropic 格式：填 https://api.xxxx.com（一般不加 /v1）

1. API key — 填你的中转站令牌（sk-xxxx）

- 如果是本地 Ollama 之类的不需要 key 的服务，直接跳过

1. 模型名 — 填中转站支持的模型 ID

- 如果你的 Base URL 支持 /v1/models 接口，Hermes 会自动检测可用模型并让你选
- 否则需要手动输入，比如 glm-5.1、deepseek-chat

1. API mode — 选 chat_completions（OpenAI 兼容）还是 anthropic_messages（Anthropic 兼容）

1. Context length — 模型的上下文窗口大小，按实际填写，不确定就留空

1. Display name — 给这个配置起个名字，比如 my-api

步骤 4：验证

Hermes 会自动向你的 Base URL 发送验证请求，确认密钥和模型是否有效。验证通过后就可以使用了。

步骤 5：开始对话

hermes        # 经典 CLI
hermes --tui  # 现代 TUI 界面（推荐）

进入对话后，可以用 /model 命令切换模型。

三、方式二：手动编辑 config.yaml（推荐进阶）

如果你更习惯直接改配置文件，或者需要加多个中转站，手动编辑更高效。

配置文件位置

Hermes 的配置分两个文件：

⚠️ 改之前先备份！ 复制 config.yaml 为 config.yaml.bak，改坏了可以恢复。

添加自定义 Provider

打开 ~/.hermes/config.yaml，找到或添加 custom_providers 字段：

custom_providers:
  - name: myapi
    base_url: https://api.xxxx.com/v1
    key_env: MYAPI_API_KEY
    api_mode: chat_completions

然后在 ~/.hermes/.env 里添加对应的 API Key：

MYAPI_API_KEY=sk-xxxxxxxxxxxx

设置默认模型

在 config.yaml 的 model 字段里指定使用你的自定义 Provider：

model:
  provider: custom:myapi
  default: glm-5.1
  base_url: ''
  api_mode: chat_completions

💡 provider: custom:myapi 里的 custom: 前缀不能少，myapi 是你在 custom_providers 里定义的 name。

添加多个中转站

custom_providers:
  - name: myapi
    base_url: https://api.xxxx.com/v1
    key_env: MYAPI_API_KEY
    api_mode: chat_completions
  - name: myapi-claude
    base_url: https://api.xxxx.com
    key_env: MYAPI_CLAUDE_KEY
    api_mode: anthropic_messages

对应的 .env：

MYAPI_API_KEY=sk-xxxxxxxxxxxx
MYAPI_CLAUDE_KEY=sk-yyyyyyyyyyyy

切换模型：

/model custom:myapi:glm-5.1
/model custom:myapi-claude:claude-sonnet-4-20250514

也可以把 API Key 直接写在 config.yaml 里

如果你不在意安全（比如本地开发），可以用 api_key 代替 key_env：

custom_providers:
  - name: myapi
    base_url: https://api.xxxx.com/v1
    api_key: sk-xxxxxxxxxxxx
    api_mode: chat_completions

但推荐还是走 .env 文件，密钥不要明文写在配置里。

四、模型别名：给常用模型起短名

如果你经常在几个模型之间切换，可以定义别名，不用每次输那么长。

在 config.yaml 里添加：

model_aliases:
  glm:
    model: glm-5.1
    provider: custom:myapi
  ds:
    model: deepseek-chat
    provider: custom:myapi
  claude:
    model: claude-sonnet-4-20250514
    provider: custom:myapi-claude

然后用短名切换：

/model glm
/model ds
/model claude

也可以用 CLI 命令直接设置：

hermes config set model.aliases.glm "custom:myapi/glm-5.1"
hermes config set model.aliases.ds "custom:myapi/deepseek-chat"

💡 model_aliases 比 model.aliases 优先级更高，且支持自定义 base_url。简单场景用哪个都行。

五、辅助任务模型分配

Hermes 除了主聊天模型，还有一些辅助任务（视觉分析、压缩、标题生成等），可以给它们指定不同的模型来省钱。

auxiliary:
  # 图片分析 — 用便宜的视觉模型
  vision:
    provider: custom:myapi
    model: gpt-4o-mini
    base_url: ''
    api_key: ''
    timeout: 120
    download_timeout: 30
  # 上下文压缩 — 用快速模型
  compression:
    provider: custom:myapi
    model: deepseek-chat
    base_url: ''
    api_key: ''
  # 标题生成 — 用最便宜的模型就行
  title_gen:
    provider: custom:myapi
    model: glm-4-flash
    base_url: ''
    api_key: ''
  # 网页内容提取
  web_extract:
    provider: custom:myapi
    model: deepseek-chat
    base_url: ''
    api_key: ''
    timeout: 360

如果 provider 和 model 留空（或设为 auto），Hermes 会用主模型来跑这些辅助任务。

六、Fallback：主模型挂了自动切备用

你可以配置一个备用模型，当主模型出错（限流、宕机等）时自动切换：

通过 CLI：

hermes fallback

或手动在 config.yaml 里添加：

fallback_model:
  provider: custom:myapi
  model: deepseek-chat

七、改完怎么生效

• CLI 模式：下次 hermes chat 或 hermes --tui 启动时自动读取新配置
• 网关模式（Telegram/Discord 等）：执行 hermes gateway restart
• 对话中切换：直接用 /model 命令，立即生效，不需要重启

八、怎么确认配置成功了

方法一：看启动信息

启动 hermes 后，顶部状态栏会显示当前模型名，确认是不是你配置的。

方法二：对话中查看

在对话里输入 /model，会显示当前使用的模型和 Provider。

方法三：发一条测试消息

发送：

请只回复：配置成功

能正常回复就说明没问题。

方法四：运行诊断

hermes doctor

这个命令会检查配置是否有问题，包括模型连接是否正常。

九、Base URL 要不要加 /v1

跟 Trae 和 OpenClaw 一样的规则：

⚠️ 调不通就把 /v1 加上或去掉试试。有些中转站两种都能用，有些只认一种。

十、常见问题排查

hermes model 选了 Custom endpoint 但连接失败

按这个顺序检查：

1. Base URL 是否正确：确认加了或没加 /v1
2. API Key 是否有效：在中转站确认令牌状态正常、有余额
3. 模型 ID 是否正确：中转站显示的名称和实际 API 调用 ID 可能不同
4. api_mode 是否选对：大多数选 chat_completions，只有明确支持 Anthropic 原生的才选 anthropic_messages

config.yaml 改了但不生效

• 格式错误：YAML 对缩进非常敏感，必须用空格缩进，不能用 Tab。检查缩进是否对齐
• 没保存：确认文件已保存
• 需要重启：CLI 模式重新进一下，网关模式执行 hermes gateway restart

Claude 模型连不上

最常见的三个原因：

1. api_mode 写成了 chat_completions → 改成 anthropic_messages
2. Base URL 的 /v1 加没加对 → Anthropic 格式一般不加
3. 中转站本身不支持 Anthropic 原生格式 → 试试 chat_completions，有些中转站的 Claude 也能走 OpenAI 兼容格式

自定义 Provider 不出现在列表里

• 确认 custom_providers 写在了 config.yaml 的顶层（不是嵌套在别的地方）
• 确认 name 字段没有特殊字符
• 运行 hermes doctor 看是否有配置错误提示

上下文窗口太小报错

Hermes 要求模型至少有 64K tokens 的上下文窗口。如果你用的模型上下文较小，会启动报错。如果用本地模型，确保启动时设置了足够大的上下文：

# Ollama 示例
ollama run --num_ctx 65536 模型名

响应很慢或超时

在 custom_providers 或辅助任务配置里加一个 timeout：

custom_providers:
  - name: myapi
    base_url: https://api.xxxx.com/v1
    key_env: MYAPI_API_KEY
    api_mode: chat_completions
    timeout: 300  # 秒

extra_body：某些中转站需要额外参数

如果你的中转站需要在请求体里加额外字段（比如推理开关），可以用 extra_body：

custom_providers:
  - name: myapi
    base_url: https://api.xxxx.com/v1
    key_env: MYAPI_API_KEY
    api_mode: chat_completions
    extra_body:
      enable_thinking: true
      reasoning_effort: high

Hermes 会把这些字段合并到每个 chat-completions 请求里。

十一、用 CLI 命令快捷设置

除了手动改文件，Hermes 还支持命令行一键设置：

# 设置默认模型
hermes config set model anthropic/claude-opus-4.7

# 设置 Provider
hermes config set model.provider custom:myapi

# 设置 API Key（自动写入 .env）
hermes config set MYAPI_API_KEY sk-xxxxxxxxxxxx

# 设置模型别名
hermes config set model.aliases.glm "custom:myapi/glm-5.1"

CLI 会自动把密钥写到 .env，非密钥写到 config.yaml，不会搞混。

十二、完整配置示例

以下是一个接入第三方中转站的完整 config.yaml 示例：

# 自定义 Provider
custom_providers:
  - name: myapi
    base_url: https://api.xxxx.com/v1
    key_env: MYAPI_API_KEY
    api_mode: chat_completions
  - name: myapi-anthropic
    base_url: https://api.xxxx.com
    key_env: MYAPI_ANTHROPIC_KEY
    api_mode: anthropic_messages

# 主模型
model:
  provider: custom:myapi
  default: glm-5.1
  base_url: ''
  api_mode: chat_completions

# 模型别名
model_aliases:
  glm:
    model: glm-5.1
    provider: custom:myapi
  ds:
    model: deepseek-chat
    provider: custom:myapi
  claude:
    model: claude-sonnet-4-20250514
    provider: custom:myapi-anthropic

# 辅助任务
auxiliary:
  vision:
    provider: custom:myapi
    model: gpt-4o-mini
  compression:
    provider: custom:myapi
    model: deepseek-chat
  title_gen:
    provider: custom:myapi
    model: glm-4-flash

# 备用模型
fallback_model:
  provider: custom:myapi
  model: deepseek-chat

对应的 .env：

MYAPI_API_KEY=sk-xxxxxxxxxxxx
MYAPI_ANTHROPIC_KEY=sk-yyyyyyyyyyyy

十三、总结

最关键的四个要点：

1. Provider 名称加 custom: 前缀 — provider: custom:myapi，不是 provider: myapi
2. API Key 放 .env 文件 — 不要明文写在 config.yaml 里
3. Base URL 注意 /v1 — chat_completions 一般加，anthropic_messages 一般不加
4. 模型 ID 必须和中转站一致 — 填实际 API 调用 ID，不是显示名称