Hermes Agent 是 Nous Research 开源的自进化 AI 智能体框架，内置模型切换功能。支持接入 API 中转站，拿到更灵活的模型选择和成本控制。这篇讲两种接入方式的完整步骤。

一、准备工作

先从 API 中转站获取以下三个信息：

信息说明示例

| API Key | 中转站的令牌，通常以 sk- 开头 | sk-xxxxxxxxxxxx

| Base URL | 中转站的 API 地址 | https://api.xxxx.com

| 模型 ID | 你要使用的模型名称 | glm-5.1、deepseek-chat

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

另外还得确认一下——你的中转站走哪种协议：

中转站类型协议说明

| 绝大多数中转站（New API、One API 等） | chat_completions | OpenAI 兼容格式，最常见

| 支持 Anthropic 原生接口的中转站 | anthropic_messages | 较少见，需要中转站明确支持

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

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

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

步骤 1：启动模型选择

在终端运行：

hermes model

步骤 2：选择服务商

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

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

步骤 3：填写信息

向导会挨个问你：

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

• OpenAI 兼容格式：填 https://api.xxxx.com/v1（一般要加 /v1）
• Anthropic 格式：填 https://api.xxxx.com（一般不加 /v1）
• API key — 填你的中转站令牌（sk-xxxx）

• 如果是本地 Ollama 之类的不需要 key 的服务，直接跳过
• 模型名 — 填中转站支持的模型 ID

• 如果你的 Base URL 支持 /v1/models 接口，Hermes 会自动检测能用的模型让你挑
• 不然就手动输，比如 glm-5.1、deepseek-chat
• API mode — 选 chat_completions（OpenAI 兼容）还是 anthropic_messages（Anthropic 兼容）
• Context length — 模型的上下文窗口大小，按实际填写，不确定就留空
• Display name — 给这个配置起个名字，比如 my-api

步骤 4：验证

Hermes 会自动往你的 Base URL 发个验证请求，看看密钥和模型能不能用。验证过了就能直接用。

步骤 5：开始对话

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

进去之后，用 /model 命令切换模型。

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

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

配置文件位置

Hermes 的配置分两个文件：

文件存什么

| ~/.hermes/config.yaml | 非敏感配置（模型、服务商、辅助任务等）

| ~/.hermes/.env | 敏感信息（API Key、Token 等）

⚠️ 改之前先备份！ 复制 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 一样的规则：

协议类型Base URL说明

| chat_completions（OpenAI 兼容） | https://api.xxxx.com/v1 | 一般要加 /v1

| anthropic_messages（Anthropic 兼容） | https://api.xxxx.com | 一般不加 /v1

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

十、常见问题排查

hermes model 选了 Custom endpoint 但连接失败

按这个顺序查：

• Base URL 是否正确：确认加了或没加 /v1
• API Key 是否有效：去中转站看看令牌状态、余额
• 模型 ID 是否正确：中转站显示的名字和实际 API 调用 ID 可能不一样
• api_mode 是否选对：大多数选 chat_completions，只有明确支持 Anthropic 原生的才选这个 anthropic_messages

config.yaml 改了但不生效

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

Claude 模型连不上

最常见的三个原因：

• api_mode 写成了 chat_completions → 改成 anthropic_messages
• Base URL 的 /v1 加没加对 → Anthropic 格式一般不加
• 中转站本身不支持 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 会把这些字段合到每个请求里。

十一、用 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

十三、总结

CLI 向导手动编辑 config.yaml

| 配置难度 | 最简单 | 中等

| 适合场景 | 第一次配置、只接一个中转站 | 接多个中转站、需要精细控制

| 支持的功能 | 基础模型配置 | 别名、辅助任务、Fallback、extra_body

最关键的四个要点：

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