Hermes agent怎么配置大模型？云端API及本地Ollama的全路径接入实操

Hermes Agent 是由 Nous Research 开发的一款开源 AI 智能体框架，能将大模型推理、工具调用、终端执行、文件操作、浏览器自动化、长期记忆、定时任务等能力整合到一个统一的智能体运行环境中。配置大模型的核心价值在于：Hermes 本身不内置任何模型权重，而是一个‘模型无关’的调度框架——只要服务暴露 OpenAI 风格的 API，就能无缝接入，让你在云端 API、本地 Ollama、自建推理集群之间自由切换，完全不被单一供应商锁定。

本文大纲

👉 一、配置前的准备：认识三个核心文件
👉 二、方法一：通过交互式命令配置（最推荐新手）
👉 三、方法二：编辑 config.yaml 配置文件（灵活定制）
👉 四、主流模型接入速查表
👉 五、多模型共存与切换技巧
👉 六、常见问题与排障指南
👉 总结

一、配置前的准备：认识三个核心文件

在开始配置之前，先搞清楚 Hermes Agent 的三个核心配置文件的位置和作用，这是后续所有配置操作的基础：

文件路径	作用
~/.hermes/config.yaml	主配置文件，存放模型选择、provider、base_url、终端后端、工具集等核心设置
~/.hermes/.env	环境变量文件，存放各类 API 密钥（权限自动设为 0600，仅所有者可读写）
~/.hermes/state.db	SQLite 数据库，存放跨会话的记忆和用户档案

Hermes 读取配置的优先级是：.env 文件中的环境变量 > config.yaml 中的配置项 > 内置默认值。密钥一律放在 .env 中，不要直接写在 config.yaml 里，以防文件被意外分享或上传到公开仓库。

二、方法一：通过交互式命令配置（最推荐新手）

Hermes Agent 提供了完整的交互式配置流程，无需手动编辑文件，特别适合首次配置或快速切换模型。

步骤 1：启动配置向导

在终端中运行：

hermes setup

向导会依次引导你完成以下步骤：

• 选择 LLM provider（模型提供商）
• 输入 API Key
• 选择默认模型
• 配置终端后端（local / docker / ssh）
• 配置消息平台网关（可选）

步骤 2：选择 Provider

使用方向键在以下 provider 中选择一个：

Provider	说明
Nous Portal	官方订阅服务，OAuth 登录
OpenRouter	聚合 100+ 模型，一个密钥通吃
Anthropic	Claude 系列模型直连
OpenAI	GPT 系列模型直连
Custom endpoint	任意 OpenAI 兼容的自定义端点

对于国内用户，最推荐选择 OpenRouter（聚合服务，模型选择多）或 Custom endpoint（接入国内模型聚合平台）。

步骤 3：输入 API Key

选择 provider 后，向导会提示输入 API 密钥。输入时屏幕不会显示任何字符，直接粘贴后按回车即可。密钥会被保存到 ~/.hermes/.env 中。

步骤 4：选择默认模型

输入密钥后，向导会列出 death provider 下可用的模型列表，使用方向键选择默认模型即可。

配置完成后，直接运行 hermes 即可进入交互式对话界面。

💡 切换模型：hermes model 命令

如果只是想快速切换已有配置中的模型，可以使用更简洁的命令：

hermes model

在交互菜单中选择已有的 provider 和模型，即可完成切换，无需重新运行完整 setup。

三、方法二：编辑 config.yaml 配置文件（灵活定制）

如果需要更精细的控制（比如配置自定义中转服务、同时配置多个模型），直接编辑配置文件是更灵活的选择。

步骤 1：打开配置文件

使用以下命令在默认编辑器中打开配置文件：

hermes config edit

也可以手动编辑：

vim ~/.hermes/config.yaml

步骤 2：配置模型节

在文件中找到或添加 model 节点，按以下格式填写：

model:
  default: 'anthropic/claude-opus-4.6'   # 默认模型
  provider: 'openrouter'                  # provider 类型
  base_url: 'https://openrouter.ai/api/v1'   # API 端点地址

步骤 3：设置 API 密钥（放在 .env 中）

密钥 务必 放在 ~/.hermes/.env 文件中，不要直接写入 config.yaml：

# 编辑 .env 文件
vim ~/.hermes/.env

添加对应的密钥：

OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
# 或
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
# 或
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

💡 关键提示：base_url 必须以 /v1 结尾，这是 OpenAI 兼容 API 的标准路径。例如 https://api.modelverse.cn/v1 或 http://localhost:11434/v1。

四、主流模型接入速查表

以下是常见模型服务的配置速查，直接对照填写即可。

📌 本地 Ollama

前置条件：确保 Ollama 已安装并运行 ollama serve。

.env 文件无需设置密钥。

config.yaml 配置：

model:
  provider: ollama
  base_url: http://localhost:11434
  default: qwen2.5:7b

📌 OpenRouter（聚合 200+ 模型）

.env 文件：

OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

config.yaml 配置：

model:
  provider: openrouter
  base_url: https://openrouter.ai/api/v1
  default: openrouter/auto   # 或指定具体模型

📌 Anthropic Claude（直连）

.env 文件：

ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

config.yaml 配置：

model:
  provider: anthropic
  default: anthropic/claude-opus-4.6

📌 Kimi / Moonshot AI

.env 文件：

KIMI_API_KEY=sk-kimi-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

config.yaml 配置：

model:
  provider: kimi-coding
  default: kimi-3.5

💡 提示：密钥前缀为 sk-kimi- 时会自动使用 Kimi Code API，端点地址也自动对应。

📌 智谱 GLM

.env 文件：

ZAI_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxx

config.yaml 配置：

model:
  provider: zai
  default: glm-5

📌 自建 vLLM / FastChat / 任意 OpenAI 兼容端点

.env 文件（可选，如果服务需要认证）：

OPENAI_API_KEY=your-api-key   # 无认证时填 'EMPTY'

config.yaml 配置：

model:
  provider: openai
  base_url: http://192.168.1.100:8000/v1
  default: Qwen2.5-7B-Instruct

📌 DeepSeek

.env 文件：

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

config.yaml 配置：

model:
  provider: custom
  base_url: https://api.deepseek.com/v1
  default: deepseek-chat

📌 阿里云百炼（通义千问）

.env 文件：

ALIBABA_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

config.yaml 配置：

model:
  provider: alibaba
  default: qwen-max

五、多模型共存与切换技巧

Hermes Agent 支持同时配置多个模型，并在运行时灵活切换。

配置多个 provider

在 ~/.hermes/config.yaml 中配置多个 provider：

providers:
  openrouter:
    api_key: '你的_OPENROUTER_KEY'
  deepseek:
    api_key: '你的_DEEPSEEK_KEY'
    base_url: 'https://api.deepseek.com/v1'
  ollama:
    base_url: 'http://localhost:11434'

model:
  default: 'openrouter/auto'   # 默认启动的模型
  provider: 'openrouter'

运行时切换模型

有以下几种方式：

方式一：hermes model 命令。在终端中运行，交互式选择目标模型。

方式二：对话中切换。在 Hermes 对话界面中输入 /model 命令：

/model openrouter:google/gemini-2.5-pro
/model qwen2.5:7b

方式三：直接指定：

hermes config set model anthropic/claude-opus-4.6

六、常见问题与排障指南

🔧 Q1：配置完成后模型不回复，日志显示连接超时？

可能原因：base_url 地址不可达或网络问题。

解决方案：先用 curl 测试端点连通性：

curl -X POST https://your-endpoint.com/v1/chat/completions \
  -H 'Authorization: Bearer sk-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{"model": "your-model", "messages": [{"role": "user", "content": "hi"}]}'

若该命令返回正常 JSON，说明服务本身正常，问题出在 Hermes 配置上。

🔧 Q2：回复乱码或格式异常？

可能原因：服务未启用 OpenAI 兼容模式。

解决方案：检查中转服务文档，确认已开启 OpenAI API 兼容。对于自建 vLLM 服务，启动时需加上 --entrypoint openai.api_server 参数。

🔧 Q3：API Key 报错？

可能原因：密钥未正确加载或格式错误。

解决方案：

1. 检查 .env 文件位置是否正确（~/.hermes/.env）
2. 检查密钥前后有无多余空格
3. 运行 hermes config env-path 确认当前加载的 .env 文件路径

🔧 Q4：模型未被识别，模型名称显示为空？

在对话中输入 /model 命令手动指定模型，看到模型名称正确显示即代表设置成功。

🔧 Q5：base_url 配置后请求返回 404？

可能原因：缺少 /v1 后缀。

解决方案：确保 base_url 以 /v1 结尾，例如 https://api.example.com/v1，而不是 https://api.example.com。

总结

Hermes Agent 配置大模型有三条核心路径：交互式配置（hermes setup / hermes model） 最便捷、适合新手快速上手；编辑配置文件（config.yaml + .env） 最灵活、适合精细定制和长期固定配置；多模型共存配置 则让你在云端 API、本地 Ollama 和自建推理服务之间自由切换。核心记住三点：密钥放 .env，base_url 以 /v1 结尾，服务须提供 OpenAI 兼容端点。

如果你想把 Hermes Agent 这类开源 Agent 的能力集成到更复杂的企业级自动化场景中——比如跨系统数据同步、智能审批、多 Agent 协同编排——可以了解一下「实在Agent」。它能把大模型调用、RPA 流程编排和数据流转串成一条线，让你的 AI 助手从“会聊天”升级为“能干活”的生产力中枢。