RealRelay.ai
编码智能体

Hermes Agent 接入指南

把 RealRelay.ai 作为自定义端点接入 Nous Research 的 Hermes Agent：安装、通过 hermes model 或 config.yaml 添加 RealRelay.ai、设置上下文窗口、检查连接并切换模型。

创建 API 密钥浏览目录
协议
OpenAI Chat Completions
基础地址
https://www.realrelay.ai/v1
官方文档
github.com
已对照工具官方文档核对
2026-10

概览

Hermes Agent 是 Nous Research 推出的开源智能体，运行在你自己的机器上。你可以在终端、它的桌面应用或聊天应用中使用它，它会在会话之间保留记忆和技能。RealRelay.ai 不在它的内置提供商之列，所以需要把它添加为一个使用 OpenAI Chat Completions API（/v1/chat/completions）的自定义端点。

  • 一个从控制台的 API 密钥页面获取的 API 密钥。

  • 末尾带 /v1 的基础地址。Hermes 会在后面拼上 /chat/completions。

  • 一个与 GET /v1/models 列出的完全一致的模型 ID，例如 z-ai/glm-5.2。请选择支持工具调用的模型。

Hermes 需要至少 64,000 token 的上下文窗口，低于这个值就拒绝启动。它通常从端点的模型列表读取窗口大小，但 RealRelay.ai 的列表不包含这项信息，所以请按“配置”一节所示，为每个模型自行设置窗口。

安装

命令行版本请使用 Nous Research 的安装程序。它会自行配置所需的 Python 和工具，Windows 既可原生运行，也可通过 WSL2 运行。Hermes 官网还提供适用于 Apple Silicon Mac 和 Windows 的桌面应用。

macOS · Linux · WSL2
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashsource ~/.zshrc   # or: source ~/.bashrc
Windows PowerShell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

安装程序会把 Hermes 放到 %LOCALAPPDATA%\hermes，并添加到你的用户 PATH。运行 hermes 之前，请新开一个 PowerShell 窗口。

安装结束时可能会启动一个设置向导。你可以跳过其中的提供商步骤，按下面的“配置”一节操作。

配置

Hermes 把设置保存在 config.yaml 中，把密钥等机密保存在 .env 中，两者都位于 ~/.hermes/，原生 Windows 上则位于 %LOCALAPPDATA%\hermes\。可以使用向导，也可以直接编辑文件；两种方式最终都写入 config.yaml。

  1. 1

    启动向导

    在终端中运行它（不要在聊天会话里运行），然后选择 Custom endpoint。

  2. 2

    回答提示

    按提示输入下列值。不同版本的提示措辞可能有所不同。请填写模型目录页上的真实上下文窗口；这里显示的值是一个安全下限。

    Terminal
    hermes model
    hermes model → Custom endpoint
    1API base URL:    https://www.realrelay.ai/v12API key:         sk-***3Model name:      z-ai/glm-5.24API mode:        chat_completions5Context length:  200000
  1. 1

    保存密钥

    这会把密钥写入 Hermes 的 .env 文件，而不是 config.yaml。

    Terminal
    hermes config set REALRELAY_API_KEY sk-***
  2. 2

    把 RealRelay.ai 添加为提供商

    用 hermes config edit 打开文件，合并进下面这些配置块。如果已有 model: 块，请替换掉它。

    ~/.hermes/config.yaml
    1providers:2  realrelay:3    name: RealRelay.ai4    api: https://www.realrelay.ai/v15    key_env: REALRELAY_API_KEY6    transport: chat_completions7    models:8      "z-ai/glm-5.2":9        context_length: 2000001011model:12  default: "z-ai/glm-5.2"13  provider: custom:realrelay

  • api 是基础地址。key_env 指定保存密钥的变量名；Hermes 会在你的 shell 或它的 .env 文件中查找这个变量。

  • transport: chat_completions 是自定义端点的默认值。显式写出来，可以避免 Hermes 根据 URL 去猜。

  • models.<id>.context_length 是该模型的总窗口，包括输入和输出。Hermes 据此决定何时压缩对话。

  • provider: custom:realrelay 把默认模型指向 realrelay 条目。模型 ID 加了引号，因为其中包含斜杠和点号。

  • .env 中的 OPENAI_BASE_URL 对自定义端点不起作用。Hermes 只从 config.yaml 读取 URL。

验证

  1. 1

    直接调用端点

    用你的密钥运行这条命令。如果返回的 JSON 包含 choices 数组，说明地址、密钥和模型都没问题。

    Terminal
    1curl -sS "https://www.realrelay.ai/v1/chat/completions" \2  -H "Authorization: Bearer sk-***" \3  -H "content-type: application/json" \4  -d '{"model": "z-ai/glm-5.2", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with OK"}]}'
  2. 2

    检查 Hermes 的设置并发送一条消息

    hermes doctor 会报告配置问题。hermes config get model 应显示模型 ID 和 custom:realrelay 提供商。最后一条命令会发送一条消息后退出。

    Terminal
    hermes doctorhermes config get modelhermes chat -q "Reply with OK"
  3. 3

    启动会话

    运行 hermes。欢迎横幅会显示模型及其上下文窗口。第一条消息收到回复即说明整条链路畅通，该请求也会出现在控制台的用量日志中。

模型

在会话中，用 /model 加提供商名称和模型 ID，即可切换到另一个 RealRelay.ai 模型。Hermes 会保存这个选择，重启后依然生效。

Hermes session
/model custom:realrelay:z-ai/glm-5.2

为每个要切换的模型在 models 下单独建一个条目，写明它的上下文窗口，免得 Hermes 退回去猜测：

~/.hermes/config.yaml → providers.realrelay.models
1"z-ai/glm-5.2":2  context_length: 2000003"<another-model-id>":4  context_length: 200000

/model 只能在已配置好的提供商之间切换。要添加提供商，请退出会话并运行 hermes model。摘要、读图等辅助任务默认使用你的主模型，除非单独配置。适合编码智能体的模型列在选择模型中。

故障排查

  • Hermes 因上下文太小而拒绝启动。模型的窗口低于 64,000 token，或者 Hermes 没找到窗口大小而进行了猜测。为该模型设置 context_length，或换一个窗口更大的模型。

  • 401。Hermes 找不到密钥。检查 key_env 中的名称是否与你用 hermes config set 保存的变量一致，以及密钥中是否混入了空格。

  • 404。基础地址缺少 /v1。把它加上。

  • 找不到模型。模型 ID 与 GET /v1/models 不完全一致。请保留斜杠前面的前缀。

  • /model 中没有 RealRelay.ai。它还没有配置。退出会话并运行 hermes model，或检查 config.yaml 中的 providers 块。

  • 切换模型后上下文窗口不对。切换时，顶层的 model.context_length 会被丢弃。请改为写在 providers.realrelay.models 下，每个模型一个条目。

  • .env 中的设置似乎被忽略了。Hermes 只从 config.yaml 读取模型和 URL。.env 用于保存密钥。