Hermes Agent

​

概述

​

使用前准备

​

1. 系统与模型要求

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

​

2. 获取 EvoLink API Key

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

​

第一步：安装 Hermes Agent

• macOS / Linux
• Windows

在终端中执行一键安装脚本：

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 的模型，并非 EvoLink；想接入 EvoLink 需在安装完成后再执行 hermes model 单独配置（见第二步）。
• Full setup —— 由你自己逐项配置供应商、工具与选项（使用自己的 Key）。想直接接入 EvoLink 的用户推荐这一项，可在安装过程中一步到位填入 EvoLink 的接口地址与 Key。

下面演示选择 Full setup 接入 EvoLink 的几个关键步骤：

1

选择 Full setup

用方向键选中 Full setup — configure every provider, tool & option yourself（bring your own keys），按回车确认。

2

选择供应商：Custom endpoint

在供应商列表中，向下找到并选择 custom endpoint（enter URL manually）。因为 EvoLink 提供的是 OpenAI 兼容接口，所以这里走「自定义端点」接入。

3

填写 EvoLink 接口地址与 API Key

向导会依次提示输入端点信息：

• API base URL 填入：https://direct.evolink.ai/v1
• API key 填入你的 EvoLink API Key（以 sk- 开头）

填写后向导会自动校验端点。若看到类似 Verified endpoint via https://direct.evolink.ai/v1/models (154 model(s) visible) 的提示，说明接口连通、Key 有效。随后按提示继续选择默认模型与工具即可。

预期结果： 完成向导后会显示 Installation Complete（安装完成） 页面，并列出配置文件位置与常用命令。

WSL2、以及 Android（Termux）环境同样使用上面的 install.sh 脚本安装。

在 PowerShell 中执行一键安装命令：

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

预期结果： 会看到下载和安装信息，最后显示安装成功提示。如果出错： 如提示执行策略限制，请以管理员身份打开 PowerShell，或先执行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 后重试。安装后首次运行 hermes 同样会进入 Quick / Full 安装向导，接入 EvoLink 的步骤与 macOS / Linux 标签页一致（推荐选择 Full setup，在向导中填入 EvoLink 接口地址与 Key）。

macOS 与 Windows 用户也可以从 Hermes 官网 下载 Hermes Desktop 桌面安装包，双击安装。

​

检验安装

hermes doctor

​

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

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

• 配置向导（推荐）
• 命令行配置
• 手动编辑配置文件

Hermes 提供交互式配置向导，适合新用户（尤其是选择了 Quick Setup 的用户）。在终端执行：

hermes model

1

选择供应商：Custom endpoint

在供应商列表中向下找到并选择 custom endpoint（enter URL manually），以接入 EvoLink 的 OpenAI 兼容端点。

2

填写接口地址、Key 并选择兼容模式

依次填入端点信息，并在校验通过后选择 API 兼容模式：

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

看到类似 Verified endpoint via https://direct.evolink.ai/v1/models (163 model(s) visible) 即表示接口连通、Key 有效。

3

选择默认模型

最后填入要作为默认模型的模型名（如 claude-sonnet-4-6、claude-opus-4-8 等），按回车确认。

向导会自动把 API Key 写入 ~/.hermes/.env，把模型与端点配置写入 ~/.hermes/config.yaml，无需手动编辑文件。

hermes model 是 Quick 用户接入 EvoLink 最关键的一步。完成后即可直接进入下一步开始使用。

如果你已经拿到了 EvoLink API Key，可以直接用命令行写入配置。

​

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

hermes config set OPENAI_API_KEY 你的EvoLink_API_Key

​

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

hermes config set OPENAI_BASE_URL https://direct.evolink.ai/v1
hermes config set model claude-sonnet-4-6

hermes config set 会自动把 API Key 类的密钥写入 .env，把其余配置写入 config.yaml，你不需要关心写到哪个文件。

完成后可执行 hermes config 查看当前配置是否正确。

进阶用户： 以下方式直接编辑配置文件。大多数用户推荐使用上面的”配置向导”。

​

1. 编辑 ~/.hermes/.env

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

OPENAI_API_KEY=你的EvoLink_API_Key
OPENAI_BASE_URL=https://direct.evolink.ai/v1

​

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

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

model:
  provider: custom
  default: claude-sonnet-4-6
  base_url: https://direct.evolink.ai/v1
  api_mode: chat_completions

⚠️ 重要提示：

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

配置项说明：

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

​

第三步：开始使用并验证

​

1. 启动 Hermes Agent

hermes          # 经典命令行模式

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            # 简写形式

​

进阶配置（可选）

​

备用模型（Fallback）

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

​

辅助模型（Auxiliary）

auxiliary:
  title_generation:
    provider: custom
    model: claude-haiku-4-5-20251001
    base_url: https://direct.evolink.ai/v1
    api_key: 你的EvoLink_API_Key
  compression:
    provider: custom
    model: claude-haiku-4-5-20251001
    base_url: https://direct.evolink.ai/v1
    api_key: 你的EvoLink_API_Key

​

常见问题

​

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

​

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

​

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

​

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

​

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

• 401 错误：OPENAI_API_KEY 未设置或 API Key 无效
• 403 错误：API Key 权限不足或已过期
• 请检查 ~/.hermes/.env 中的 Key，以及 base_url 是否为 https://direct.evolink.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. EvoLink 支持哪些常用模型？

​

9. 如何查看用量？

​

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

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

​

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

​

注意