Hermes Agent

概述

OmniMux 网关统一使用 Base URL：https://api.omnimux.ai（OpenAI 兼容客户端通常填 https://api.omnimux.ai/v1）。控制台为 omnimux.ai/dashboard。文中的模型 ID 仅为示例，请以控制台或 GET /v1/models 为准。

Hermes Agent 是 Nous Research 推出的开源、终端原生的自主式 AI Agent（命令行工具）。它具备持久记忆、可自创建技能（skills）以及支持 21+ 平台（Telegram、Discord、Slack、WhatsApp、Signal、Matrix 等）的消息网关，可运行在本地、Docker、SSH、Modal 等多种后端环境。 Hermes Agent 支持多种大模型供应商，并且支持自定义 OpenAI 兼容接口。通过将 Hermes Agent 与 OmniMux API 进行配置集成，您可以在终端中直接使用 OmniMux 提供的 Claude、GPT、Gemini 等系列模型能力，实现统一 Key 的多模型接入。 注意区分： Hermes Agent 是一个开源的命令行应用（MIT 许可），与 Nous Research 的 Hermes 3 / Hermes 4 模型不是同一种工具。本指南介绍的是 Hermes Agent 这个工具。

使用前准备

在开始配置之前，请确保已完成以下准备工作：

1. 系统与模型要求

终端环境：Hermes Agent 在 macOS、Linux、Windows（原生或 WSL2）的命令行中运行。
模型上下文要求：Hermes Agent 建议使用上下文长度至少 64K（64,000）tokens 的模型。因为系统提示词和工具定义本身就会占用较多上下文，窗口过小可能被填满、不留对话空间，从而在启动时被拒绝。如遇到上下文相关错误，换用上下文更大的模型即可（OmniMux 的 Claude / Gemini 系列均满足该要求）。

2. 获取 OmniMux API Key

登录 OmniMux 控制台
在控制台中找到 API Keys，点击”创建新Key”按钮，然后复制生成的 Key
API Key 通常以 sk- 开头，请妥善保存

第一步：安装 Hermes Agent

提示： 如果不知道如何打开命令行终端，请查看常见问题 - 如何打开命令行终端在终端中执行一键安装脚本：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

安装完成后，重新加载终端配置使命令生效：

source ~/.zshrc   # 或 source ~/.bashrc

首次运行：选择安装方式（Quick 或 Full） 首次运行 hermes 会进入交互式安装向导，首先询问你希望以哪种方式设置 Hermes：

Quick Setup（Nous Portal） —— 通过免费的 Nous OAuth 登录，无需 API Key，自动配置模型与工具，最快上手。但它默认使用 Nous Portal 的模型，并非 OmniMux；想接入 OmniMux 需在安装完成后再执行 hermes model 单独配置（见第二步）。
Full setup —— 由你自己逐项配置供应商、工具与选项（使用自己的 Key）。想直接接入 OmniMux 的用户推荐这一项，可在安装过程中一步到位填入 OmniMux 的接口地址与 Key。

下面演示选择 Full setup 接入 OmniMux 的几个关键步骤：用方向键选中 Full setup — configure every provider, tool & option yourself（bring your own keys），按回车确认。在供应商列表中，向下找到并选择 custom endpoint（enter URL manually）。因为 OmniMux 提供的是 OpenAI 兼容接口，所以这里走「自定义端点」接入。向导会依次提示输入端点信息：

API base URL 填入：https://api.omnimux.ai/v1
API key 填入你的 OmniMux API Key（以 sk- 开头）

填写后向导会自动校验端点。若看到类似 Verified endpoint via https://api.omnimux.ai/v1/models (154 model(s) visible) 的提示，说明接口连通、Key 有效。随后按提示继续选择默认模型与工具即可。 预期结果： 完成向导后会显示 Installation Complete（安装完成） 页面，并列出配置文件位置与常用命令。 WSL2、以及 Android（Termux）环境同样使用上面的 install.sh 脚本安装。以管理员身份打开 PowerShell（标题栏会显示「管理员: Windows PowerShell」），执行一键安装命令：

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

脚本会自动检查并准备 uv、Python、Git、Node.js、ripgrep、ffmpeg 等依赖，并将 Hermes Agent 安装到 C:\Users\<用户名>\AppData\Local\hermes\ 目录。 如果出错： 如提示执行策略限制，请确认以管理员身份打开 PowerShell，或先执行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 后重试。安装完成后，按提示重启终端（关闭并重新打开 PowerShell）使 hermes 命令的 PATH 变更生效。 首次运行：选择安装方式（Quick / Full / Blank Slate） 首次运行 hermes 会进入交互式安装向导，首先询问你希望以哪种方式设置 Hermes。Windows 向导通过输入序号 + 回车进行选择：

Quick Setup（Nous Portal） —— 通过免费的 Nous OAuth 登录，无需 API Key，自动配置模型与工具，最快上手。但它默认使用 Nous Portal 的模型，并非 OmniMux；想接入 OmniMux 需在安装完成后再执行 hermes model 单独配置（见第二步）。
Full setup —— 由你自己逐项配置供应商、工具与选项（使用自己的 Key）。想直接接入 OmniMux 的用户推荐这一项，可在安装过程中一步到位填入 OmniMux 的接口地址与 Key。
Blank Slate —— 仅保留最小功能，其余能力按需逐项开启，适合进阶用户。

下面演示输入 2 选择 Full setup 接入 OmniMux 的几个关键步骤：在 How would you like to set up Hermes? 处输入 2（即 Full setup — configure every provider, tool & option yourself），按回车确认。在供应商列表中向下找到 custom endpoint（enter URL manually），输入它对应的序号（如示例中的 31）并回车。因为 OmniMux 提供的是 OpenAI 兼容接口，所以这里走「自定义端点」接入。向导会依次提示输入端点信息：

API base URL 填入：https://api.omnimux.ai/v1
API key 填入你的 OmniMux API Key（以 sk- 开头，输入时以 * 掩码显示）
API compatibility mode 选择 Chat Completions 或保持 Auto-detect [current]（直接回车即可）

填写后向导会自动校验端点。若看到类似 Verified endpoint via https://api.omnimux.ai/v1/models (169 model(s) visible) 的提示，说明接口连通、Key 有效。在模型列表底部的 Select model [1-N] or type name: 处，直接键入要作为默认模型的模型名（如 claude-opus-5）并回车。Context length 与 Display name 可直接回车使用默认值。 预期结果： 完成向导后会显示 Installation Complete（安装完成） 页面，列出 Windows 下的配置文件位置（C:\Users\<用户名>\AppData\Local\hermes\ 下的 config.yaml、.env 等）与常用命令，并提示 Restart your terminal for PATH changes to take effect（重启终端使 PATH 生效）。本指南 Windows 下的配置文件位于 C:\Users\<用户名>\AppData\Local\hermes\（而非 macOS / Linux 的 ~/.hermes/）。本指南后文出现的 ~/.hermes/.env、~/.hermes/config.yaml 在 Windows 上对应该目录下的 .env 与 config.yaml。 macOS 与 Windows 用户也可以从 Hermes 官网下载 Hermes Desktop 桌面安装包，双击安装。

检验安装

执行诊断命令检查安装状态：

hermes doctor

成功标志： 显示环境检查结果，未报告安装相关的致命错误。如需更新到最新版本，可执行 hermes update。

第二步：配置 OmniMux API（Quick 用户或重新配置）

如果你已经在第一步通过 Full setup 完成了 OmniMux 接入并通过端点校验，可以直接跳到第三步。本步骤主要面向选择了 Quick Setup 的用户，或需要重新配置 / 切换模型的场景。 Hermes Agent 通过 ~/.hermes/ 目录下的配置文件进行配置，其中：

~/.hermes/.env —— 存放 API Key 等密钥
~/.hermes/config.yaml —— 存放模型、供应商等非密钥配置

由于 OmniMux 提供 OpenAI 兼容接口，我们将 Hermes 的供应商设置为 custom（自定义端点），接口地址指向 https://api.omnimux.ai/v1。 Hermes 提供交互式配置向导，适合新用户（尤其是选择了 Quick Setup 的用户）。在终端执行：

hermes model

在供应商列表中向下找到并选择 custom endpoint（enter URL manually），以接入 OmniMux 的 OpenAI 兼容端点。依次填入端点信息，并在校验通过后选择 API 兼容模式：

API base URL 填入：https://api.omnimux.ai/v1
API key 填入你的 OmniMux API Key（以 sk- 开头）
API compatibility mode 选择 Chat Completions（standard OpenAI-compatible endpoints）

看到类似 Verified endpoint via https://api.omnimux.ai/v1/models (163 model(s) visible) 即表示接口连通、Key 有效。最后填入要作为默认模型的模型名（如 claude-opus-5），按回车确认。向导会自动把 API Key 写入 ~/.hermes/.env，把模型与端点配置写入 ~/.hermes/config.yaml，无需手动编辑文件。 hermes model 是 Quick 用户接入 OmniMux 最关键的一步。完成后即可直接进入下一步开始使用。如果你已经拿到了 OmniMux API Key，可以直接用命令行写入配置。

1. 设置 API Key（写入 .env）

hermes config set OPENAI_API_KEY 你的OmniMux_API_Key

2. 设置接口地址与模型（写入 config.yaml）

hermes config set OPENAI_BASE_URL https://api.omnimux.ai/v1
hermes config set model claude-opus-5

hermes config set 会自动把 API Key 类的密钥写入 .env，把其余配置写入 config.yaml，你不需要关心写到哪个文件。完成后可执行 hermes config 查看当前配置是否正确。 进阶用户： 以下方式直接编辑配置文件。大多数用户推荐使用上面的”配置向导”。

1. 编辑 ~/.hermes/.env

打开（或新建）~/.hermes/.env，写入 API Key 与接口地址：

OPENAI_API_KEY=你的OmniMux_API_Key
OPENAI_BASE_URL=https://api.omnimux.ai/v1

2. 编辑 ~/.hermes/config.yaml

打开（或新建）~/.hermes/config.yaml，配置主模型为自定义端点：

model:
provider: custom
default: claude-opus-5
base_url: https://api.omnimux.ai/v1
api_mode: chat_completions

⚠️ 重要提示：

将 你的OmniMux_API_Key 替换为实际的 API Key
base_url 必须为 https://api.omnimux.ai/v1（OmniMux 的 OpenAI 兼容接口地址）
不要用中文输入法输入标点符号（如中文冒号 ：）

配置项说明：

provider: custom：使用自定义 OpenAI 兼容端点（即 OmniMux）
base_url：OmniMux API 接口地址
api_mode: chat_completions：使用标准的 Chat Completions 接口
default：默认使用的模型名

第三步：开始使用并验证

1. 启动 Hermes Agent

hermes          # 经典命令行模式

或使用现代 TUI 界面（推荐）：

hermes --tui    # 现代终端界面

2. 验证配置

启动后，输入一个简单的提示进行验证，例如：

你是谁

成功标志：

看到 AI 的回复内容（几行文字）
没有出现 401、403、API key 无效，或 context length（上下文长度）等错误

如果看到错误：

401 Unauthorized：API Key 未设置或无效 → 检查 ~/.hermes/.env 中的 OPENAI_API_KEY
403 Forbidden：API Key 权限不足或已过期 → 检查 API Key
context length 相关错误：所选模型上下文不足 64K → 换用满足要求的模型
No API key / provider not found：未找到 Key → 重新执行 hermes config set OPENAI_API_KEY ...

3. 恢复历史会话

hermes --continue    # 恢复最近一次会话
hermes -c            # 简写形式

进阶配置（可选）

以下配置均编辑 ~/.hermes/config.yaml（Windows 请编辑对应文件夹下的 config.yaml 文件），按需使用。

备用模型（Fallback）

当主模型请求失败时，Hermes 可自动切换到备用模型，且不丢失当前会话。可配置一条都走 OmniMux 的备用链：

fallback_providers:
- provider: custom
model: claude-sonnet-4-6
base_url: https://api.omnimux.ai/v1
- provider: custom
model: claude-haiku-4-5-20251001
base_url: https://api.omnimux.ai/v1

辅助模型（Auxiliary）

Hermes 会用”辅助模型”处理一些次要任务（如上下文压缩、会话标题、网页摘要等）。默认使用主模型，你可以把它们路由到更便宜/更快的模型以节省成本：

auxiliary:
title_generation:
provider: custom
model: claude-haiku-4-5-20251001
base_url: https://api.omnimux.ai/v1
api_key: 你的OmniMux_API_Key
compression:
provider: custom
model: claude-haiku-4-5-20251001
base_url: https://api.omnimux.ai/v1
api_key: 你的OmniMux_API_Key

这样主模型专注于复杂推理，轻量任务交给更便宜的模型处理。

常见问题

1. Hermes Agent 是什么？主要用来做什么？

Hermes Agent 是 Nous Research 推出的开源、终端原生的自主式 AI Agent。它具备持久记忆和自创建技能能力，可在命令行中完成代码辅助、任务自动化、问答对话等工作，并支持通过消息网关接入多种聊天平台。

2. Hermes Agent 和 Hermes 3 / Hermes 4 模型是一回事吗？

不是。Hermes Agent 是一个开源命令行工具；Hermes 3 / Hermes 4 是 Nous Research 的大语言模型系列。本指南介绍的是 Hermes Agent 这个工具，它可以接入包括 OmniMux 在内的多种模型供应商。

3. 为什么要使用 `provider: custom` 接入 OmniMux？

因为 OmniMux 提供标准的 OpenAI 兼容接口。Hermes 支持多种供应商，其中 custom（自定义 OpenAI 兼容端点）正是用于接入这类兼容接口的方式。因此在 Hermes 中以 provider: custom 接入 OmniMux，接口地址填写为 https://api.omnimux.ai/v1 即可。

4. 启动时提示上下文长度（context length）不足怎么办？

Hermes Agent 建议使用至少具备 64K tokens 上下文的模型。因为系统提示词和工具定义会占用较多上下文，窗口过小可能被填满、不留对话空间，从而在启动时被拒绝。请换用上下文更大的模型（如 OmniMux 的 Claude 系列）。

5. 出现 401 / 403 错误一般是什么原因？

401 错误：OPENAI_API_KEY 未设置或 API Key 无效
403 错误：API Key 权限不足或已过期
请检查 ~/.hermes/.env 中的 Key，以及 base_url 是否为 https://api.omnimux.ai/v1

6. 修改了配置后为什么没有生效？

确认配置写入了正确的文件：API Key 在 ~/.hermes/.env，模型/端点在 ~/.hermes/config.yaml
可执行 hermes config 查看当前实际生效的配置
检查 config.yaml 的缩进与语法是否正确（YAML 对缩进敏感）
重新启动 Hermes

7. 如何切换模型？

交互式：执行 hermes model 重新选择
命令行：执行 hermes config set model 模型名
直接编辑 ~/.hermes/config.yaml 中 model.default 的值

8. OmniMux 支持哪些常用模型？

OmniMux 支持以下 Claude 模型（同时也支持 GPT、Gemini 等系列，可在控制台查看）：

模型名称	说明
`claude-haiku-4-5-20251001`	快速响应
`claude-sonnet-4-5-20250929`	平衡性能
`claude-opus-4-5-20251101`	高级版本
`claude-sonnet-4-6`	最新版本
`claude-sonnet-5`	最新版本
`claude-opus-5`	最新版本
`claude-opus-4-8`	最新版本
`claude-opus-4-7`	最新版本

9. 如何查看用量？

10. 配置文件和密钥文件分别在哪里？

密钥（API Key）：~/.hermes/.env
模型与供应商配置：~/.hermes/config.yaml
可执行 hermes config edit 直接打开配置文件编辑。

11. 如何打开命令行终端？

方法一：按 Win + R 键，输入 powershell，按回车
方法二：在开始菜单搜索”PowerShell”
方法三：在文件夹中按住 Shift 键，右键点击空白处，选择”在此处打开 PowerShell 窗口”
方法一：按 Command + 空格 打开 Spotlight，输入 Terminal，按回车
方法二：在”应用程序” → “实用工具” → “终端”
方法一：按 Ctrl + Alt + T 快捷键
方法二：在应用程序菜单中搜索”终端”或”Terminal”

注意

建议在专门的项目文件夹内启动 Hermes Agent，避免在敏感目录（如系统目录、包含密钥的目录）中运行。Hermes Agent 是自主式 Agent，会以当前工作目录为起点进行文件操作。更多用法与配置可参考 Hermes Agent 官方文档与 GitHub 仓库。

概览

Coding CLI

桌面与 IDE

OpenClaw

概述

使用前准备

1. 系统与模型要求

2. 获取 OmniMux API Key

第一步：安装 Hermes Agent

检验安装

第二步：配置 OmniMux API（Quick 用户或重新配置）

1. 设置 API Key（写入 .env）

2. 设置接口地址与模型（写入 config.yaml）

1. 编辑 ~/.hermes/.env

2. 编辑 ~/.hermes/config.yaml

第三步：开始使用并验证

1. 启动 Hermes Agent

2. 验证配置

3. 恢复历史会话

进阶配置（可选）

备用模型（Fallback）

辅助模型（Auxiliary）

常见问题

1. Hermes Agent 是什么？主要用来做什么？

2. Hermes Agent 和 Hermes 3 / Hermes 4 模型是一回事吗？

3. 为什么要使用 `provider: custom` 接入 OmniMux？

4. 启动时提示上下文长度（context length）不足怎么办？

5. 出现 401 / 403 错误一般是什么原因？

6. 修改了配置后为什么没有生效？

7. 如何切换模型？

8. OmniMux 支持哪些常用模型？

9. 如何查看用量？

10. 配置文件和密钥文件分别在哪里？

11. 如何打开命令行终端？

注意

​概述

​使用前准备

​1. 系统与模型要求

​2. 获取 OmniMux API Key

​第一步：安装 Hermes Agent

​检验安装

​第二步：配置 OmniMux API（Quick 用户或重新配置）

​1. 设置 API Key（写入 .env）

​2. 设置接口地址与模型（写入 config.yaml）

​1. 编辑 ~/.hermes/.env

​2. 编辑 ~/.hermes/config.yaml

​第三步：开始使用并验证

​1. 启动 Hermes Agent

​2. 验证配置

​3. 恢复历史会话

​进阶配置（可选）

​备用模型（Fallback）

​辅助模型（Auxiliary）

​常见问题

​1. Hermes Agent 是什么？主要用来做什么？

​2. Hermes Agent 和 Hermes 3 / Hermes 4 模型是一回事吗？

​3. 为什么要使用 provider: custom 接入 OmniMux？

​4. 启动时提示上下文长度（context length）不足怎么办？

​5. 出现 401 / 403 错误一般是什么原因？

​6. 修改了配置后为什么没有生效？

​7. 如何切换模型？

​8. OmniMux 支持哪些常用模型？

​9. 如何查看用量？

​10. 配置文件和密钥文件分别在哪里？

​11. 如何打开命令行终端？

​注意

概述

使用前准备

1. 系统与模型要求

2. 获取 OmniMux API Key

第一步：安装 Hermes Agent

检验安装

第二步：配置 OmniMux API（Quick 用户或重新配置）

1. 设置 API Key（写入 .env）

2. 设置接口地址与模型（写入 config.yaml）

1. 编辑 ~/.hermes/.env

2. 编辑 ~/.hermes/config.yaml

第三步：开始使用并验证

1. 启动 Hermes Agent

2. 验证配置

3. 恢复历史会话

进阶配置（可选）

备用模型（Fallback）

辅助模型（Auxiliary）

常见问题

1. Hermes Agent 是什么？主要用来做什么？

2. Hermes Agent 和 Hermes 3 / Hermes 4 模型是一回事吗？

3. 为什么要使用 `provider: custom` 接入 OmniMux？

4. 启动时提示上下文长度（context length）不足怎么办？

5. 出现 401 / 403 错误一般是什么原因？

6. 修改了配置后为什么没有生效？

7. 如何切换模型？

8. OmniMux 支持哪些常用模型？

9. 如何查看用量？

10. 配置文件和密钥文件分别在哪里？

11. 如何打开命令行终端？

注意