【凑个热闹】hermes本地模型配置说明(不烧token的也可以玩)

# Hermes 本地多模型服务配置通用指南

## 📋 概述

本指南介绍如何在 Hermes Agent 中配置多个本地模型服务（如 Ollama、MLX、vLLM 等），并解决切换不同服务时遇到的路由问题。

## ⚠️ 重要说明

**Hermes 当前版本不支持多 custom provider 自动路由**

主 `model` 配置中的 `base_url` 是全局默认的，**不会**根据 `custom_providers` 中的 `name` 自动切换到对应的服务地址。

因此，**每次切换不同服务时，必须手动更新主 model 配置中的 `base_url`**。

## 🔧 配置架构

### 1. custom_providers 配置（定义多个本地服务）

在配置文件中定义多个本地服务：

custom_providers:- name: omlx  base_url: http://127.0.0.1:8880/v1  api_key: "your-api-key"  api_mode: chat_completions  models:    "model-name-1":      context_length: 32768    "model-name-2":      context_length: 32768- name: ollama  base_url: http://127.0.0.1:11434/v1  api_key: ""  api_mode: chat_completions  models:    "ollama-model:tag":      context_length: 32768    "another-model:tag":      context_length: 32768

**关键字段说明**：

– `name`: 服务的唯一标识符，用于区分不同服务

– `base_url`: 服务的 API 端点地址（必须兼容 OpenAI `/v1` 接口）

– `api_key`: API 密钥（本地服务可留空）

– `api_mode`: API 兼容模式，通常为 `chat_completions`

– `models`: 可选，为特定模型配置专属参数（如上下文长度）

### 2. 主 model 配置（需要手动切换 base_url）

**使用服务 A 时**：

model:  default: model-name-1  provider: custom  base_url: http://127.0.0.1:8880/v1  # ⚠️ 服务 A 的端口  api_mode: chat_completions  context_length: 32768

**使用服务 B 时**：

model:  default: ollama-model:tag  provider: custom  base_url: http://127.0.0.1:11434/v1  # ⚠️ 服务 B 的端口  api_mode: chat_completions  context_length: 32768

### 3. Fallback 模型配置（可选）

当主模型不可用时，自动回退到备用模型：

fallback_model:  provider: custom  model: backup-model:tag  base_url: http://127.0.0.1:11434/v1  api_key_env: ''

## 🔄 如何切换服务

### 方法 1：使用 `hermes model` 命令（最可靠）

hermes model

然后按提示：

1. 选择 `Custom endpoint (self-hosted / VLLM / etc.)`

2. 输入目标服务的 URL

3. 输入模型名称

4. 配置会自动保存

### 方法 2：手动编辑配置文件

编辑配置文件（通常位于 `~/.hermes/config.yaml` 或 `$HERMES_HOME/config.yaml`），修改主 model 配置中的：

– `default`: 模型名称

– `base_url`: 服务地址

**重启 Hermes** 后生效。

### 方法 3：在同一个服务内切换模型

如果 `base_url` 已经指向某个服务，可以直接在会话中切换模型：

/model model-name-1/model model-name-2

**注意**：这种方式只能切换同一服务内的模型，不能跨服务切换。

### 1. 确保服务正在运行

# 检查服务是否可用curl http://127.0.0.1:<端口>/v1/models

### 2. 验证模型可用

# 查看服务提供的模型列表curl http://127.0.0.1:<端口>/v1/models# 或查看 Ollama 已安装模型ollama list

## ⚠️ 上下文长度设置

建议在 `custom_providers[].models[]` 中为每个模型设置 `context_length`，通常为 `32768` 或更高：

models:  "model-name":    context_length: 32768

这样可以：

– ✅ 支持更长的对话

– ✅ 支持工具调用（function calling）

– ✅ 支持复杂的多步骤任务

## 📁 配置文件位置

配置文件通常位于以下位置：

具体路径取决于你的安装方式和环境变量设置。

## 🔧 常见问题

### Q1: 启动 Hermes 时报错 “Connection refused”

**原因**：对应的本地服务未启动

**解决**：

# 启动你的本地服务your-service-command &

### Q2: 切换服务后仍然访问错误的端口

**原因**：主 model 配置中的 `base_url` 没有更新

**解决**：

1. 退出 Hermes

2. 编辑配置文件，更新 `model.base_url`

3. 重启 Hermes

### Q3: 使用 /model custom:name:model 切换失败

**原因**：Hermes 不会自动根据 custom_providers 的 name 路由到对应 base_url

**解决**：

使用 `hermes model` 命令交互式配置，或手动编辑配置文件更新 `base_url`。

### Q4: 模型响应很慢或失败

**原因**：模型未加载或内存不足

**解决**：

# 确认模型可用curl http://127.0.0.1:<端口>/v1/models

### Q5: 如何在两个服务间快速切换？

**创建快捷脚本**（可选）：

（ai写的，没试过，可以手工改配置文件）

#!/bin/bash# switch_service.sh - 快速切换本地模型服务CONFIG_FILE="${HERMES_CONFIG:-$HOME/.hermes/config.yaml}"if [ "$1" == "omlx" ]; then  sed -i '' 's|base_url:.*|base_url: http://127.0.0.1:8880/v1|' "$CONFIG_FILE"  echo "✅ 已切换到 omlx 服务"elif [ "$1" == "ollama" ]; then  sed -i '' 's|base_url:.*|base_url: http://127.0.0.1:11434/v1|' "$CONFIG_FILE"  echo "✅ 已切换到 ollama 服务"else  echo "用法: $0 {omlx|ollama}"  exit 1fi

使用方法：

chmod +x switch_service.sh./switch_service.sh omlx    # 切换到 omlx./switch_service.sh ollama  # 切换到 ollama

## 📚 相关资源

– [Hermes 官方文档](https://hermes-agent.nousresearch.com/docs/)

– [模型 Provider 配置](https://hermes-agent.nousresearch.com/docs/integrations/providers)

– [Ollama 官方文档](https://ollama.com/docs)

– [OpenAI 兼容 API 规范](https://platform.openai.com/docs/api-reference)

## 📝 版本信息

– 适用 Hermes 版本： 

– 最后更新：2026-04-11

– 本文档为通用配置指南，可根据实际环境调整路径和端口