跳到主要内容

Hermes Agent 使用指南

Hermes Agent 是 Nous Research 开源的终端自主 AI Agent，可在终端中独立完成编码、文件操作、任务编排等复杂工作。它支持接入任意 OpenAI 兼容 API 端点，官方 Provider 文档已将 Custom Endpoint 作为正式选项，因此可无缝接入 OPE.AI。

安装 Hermes Agent​

macOS / Linux / WSL2 / Termux​

使用官方安装脚本：

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

安装完成后加载 shell 配置：

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

Windows​

Hermes Agent 官方现已原生支持 Windows，在 PowerShell 中运行：

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

安装程序会自动处理 uv、Python 3.11、Node.js 等依赖，并内置便携版 Git Bash（无需管理员权限）。如果你更倾向于使用 WSL2，也可以在 WSL2 终端中执行上方 Linux/macOS 安装命令。

原生 Windows 安装目录为 %LOCALAPPDATA%\hermes；WSL2 安装目录为 ~/.hermes。

验证安装​

hermes --version

如果正确输出版本号，说明安装成功。

获取 API Key​

登录 OPE.AI 控制台，创建您的专属 API Key（以 sk- 开头）。

配置 OPE.AI​

OPE.AI 提供 OpenAI 兼容协议，API 地址为 https://api.ope.ai/v1。接入 Hermes Agent 只需配置 API base URL、API Key、Model name 三项。

方式一：交互式配置（推荐）​

运行模型配置命令：

hermes model

在菜单中选择 Custom endpoint (self-hosted / VLLM / etc.)，然后依次输入：

配置项值
API base URLhttps://api.ope.ai/v1
API Key您的 OPE.AI API Key
Model name如 claude-sonnet-5

配置上下文窗口时可留空，Hermes 会自动从端点探测；配置完成后会自动保存到 ~/.hermes/config.yaml。

方式二：手动编辑 ~/.hermes/config.yaml​

~/.hermes/config.yaml
model:
  default: claude-sonnet-5
  provider: custom
  base_url: https://api.ope.ai/v1
  api_key: sk-xxxx
注意

LLM_MODEL 旧环境变量已被 Hermes 移除，OPENAI_BASE_URL 也仅对 openai-api provider 生效。对于自定义端点（custom endpoint），~/.hermes/config.yaml 是模型与端点配置的唯一来源，请通过 hermes model 命令或直接编辑 config.yaml 中的 model.base_url 进行配置。

验证配置​

启动交互式对话：

hermes "你好，请介绍一下你自己"

如果 Hermes 使用配置的模型正常回复，说明接入成功。

推荐模型​

信息

Hermes Agent 启动时要求模型上下文至少 64K（系统提示词、工具 schema 与工作会话状态需要足够的空间），上下文低于 64K 的模型会在启动时被拒绝。以下模型均满足要求。

应用场景推荐模型上下文窗口特性说明
日常编程与写作claude-sonnet-51M综合能力均衡，擅长编程、写作与工具调用
复杂推理任务claude-opus-51M强推理与 Agent 能力，适合复杂工程和专业任务
全能旗舰gpt-5.6-sol1M综合能力强，适合编程、研究及复杂知识工作
高性价比deepseek-v4-flash-07311M极低成本，高频调用首选
多模态任务glm-5.3-flash1M原生多模态，支持长上下文，兼顾速度与 Agent 能力

完整模型列表和价格请查看 模型价格说明。

开始使用​

交互式对话​

hermes

启动终端 UI，直接在输入框中对话。

命令行直接提问​

hermes chat --provider custom --model claude-sonnet-5 "用 Python 写一个快速排序"

会话内切换模型​

hermes model vs /model

hermes model（在终端中、会话外运行）是完整的 Provider 配置向导，用于添加新 Provider、输入 API Key、配置自定义端点。

/model（在会话中输入）只能在已配置好的 Provider 和模型之间切换，无法新增 Provider 或输入 API Key。如需新增配置，请退出会话（Ctrl+C 或 /quit）后运行 hermes model。

Hermes 支持在会话中直接切换模型，无需重启：

/model custom:gpt-5.4              # 切换到 custom provider 上的 gpt-5.4
/model custom:DeepSeek-V3.2        # 切换到 DeepSeek
/model custom                     # 自动探测端点上的模型
提示

/model custom（不带模型名）会查询端点 /models 接口并自动选择模型，适合模型名记忆不确定时使用。

常见问题排查​

提示找不到 API Key 或 Provider​

  • 检查 ~/.hermes/config.yaml 中 provider: custom 与 api_key 是否正确
  • 确认 base_url 与模型配置均已写入 config.yaml
  • 重新运行 hermes model 走一遍交互式配置

401 / 403 认证失败​

  • 确认 API Key 格式正确（以 sk- 开头）
  • 登录 OPE.AI 控制台 确认 Key 有效
  • 确认 API 地址正确：https://api.ope.ai/v1

提示模型不存在或无响应​

  • 确认模型 ID 拼写正确（如 claude-sonnet-5）
  • 确认 ~/.hermes/config.yaml 中的 base_url 与模型名一致
  • 参考上方推荐模型表格使用正确的模型 ID

启动时报上下文错误​

  • 换用上下文窗口 ≥ 64K 的模型（参考上方推荐模型表格）
  • 重新运行 hermes model，设置正确的上下文窗口（或留空自动探测）

辅助任务说明（vision、会话标题等）​

vision（图像分析）、会话标题生成、上下文压缩等辅助任务，默认（auxiliary.*.provider: "auto"）使用主聊天模型，无需额外配置即可正常使用，也不会增加额外成本。若希望辅助任务走更便宜/更快的模型，可在 hermes model 菜单中选择 Configure auxiliary models 交互式配置，或参考 Auxiliary Models 文档手动设置。

相关链接​