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：选择默认模型

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

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

💡 切换模型：hermes model 命令

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

hermes model

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

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

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

步骤 1：打开配置文件

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

hermes config edit

也可以手动编辑：

vim ~/.hermes/config.yaml

步骤 2：配置模型节

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

model:
  provider: openai
  base_url: https://your-proxy-endpoint.com/v1
  name: your-model-name

💡 关键提示：base_url 必须以 /v1 结尾，这是 OpenAI 兼容 API 的标准路径。

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

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

echo 'OPENAI_API_KEY=sk-your-api-key-here' >> ~/.hermes/.env

四、主流模型接入速查表

📌 本地 Ollama

前置条件：确保 Ollama 已安装并运行 ollama serve，且已拉取模型（如 ollama pull qwen2.5:7b）。

配置步骤：

1. 运行 hermes setup，在 provider 列表中选择 More providers… → Custom endpoint
2. 设置 API base URL 为 http://127.0.0.1:11434/v1
3. 留空 API key（本地 Ollama 不需要）
4. Hermes 会自动检测已下载的模型，确认选择即可

配置文件方式：

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

📌 小米 MiMo-V2 系列（限免中）

小米 MiMo-V2 系列模型已通过 Nous Portal 官方集成到 Hermes Agent 中，限免周期为 4 月 8 日至 4 月 22 日。

步骤 1：更新 Hermes Agent 至最新版本

hermes update

步骤 2：进行 Nous Portal 授权登录

hermes auth

依次选择 Add a credential → 输入 nous → 选择 Login with browser，完成 OAuth 登录。

步骤 3：选择小米模型

hermes model

在列表中选择 Nous Portal，即可看到三款小米模型：

• xiaomi/mimo-v2-pro — 旗舰基座，适合重度 Agent 任务和复杂编程
• xiaomi/mimo-v2-omni — 全模态，支持视觉、音频融合理解
• xiaomi/mimo-v2-flash — 极速推理，适合快速响应场景

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

.env 文件：

ALIBABA_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

config.yaml 配置：

model:
  provider: alibaba
  default: qwen-max

📌 Anthropic Claude（直连）

.env 文件：

ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

config.yaml 配置：

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

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

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

OPENAI_API_KEY=your-api-key

config.yaml 配置：

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

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

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

配置多个 provider

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

providers:
  openrouter:
    api_key: '你的_OPENROUTER_KEY'
  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 地址不可达或网络问题。

解决方案：先用 c​url 测试端点连通性：

c​url -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 框架的能力，与 RPA 流程编排、跨系统数据同步和企业内部自动化工作流深度集成，可以了解一下「实在Agent」。它能把大模型调用、业务流程和数据流转串成一条线，让你的 AI 助手从“会聊天”升级为“能干活”的生产力中枢。