AruHub 文档

主题

Hermes Agent 配置教程 ​

本教程依据 Hermes Agent 当前官方文档，介绍如何把主模型连接到 AruHub。不同版本的菜单名称可能略有不同，请以当前客户端界面为准。

1. 这是什么工具 ​

Hermes Agent 是 Nous Research 开发的自主 AI Agent。Agent 可以理解为能持续处理任务、调用工具并保留会话的 AI 助手。Hermes 提供命令行、桌面应用和 Web Dashboard 等使用方式。

本页只完成模型 API 配置与首次测试，不介绍消息平台、远程服务器或复杂工具网关部署。

2. 适合什么用户 ​

适合希望在终端或 Hermes Desktop 中使用 AI 助手，并愿意逐步确认工具权限的用户。当前官方平台支持包括：

  • macOS Apple Silicon；
  • Windows 10/11，包括原生安装和 WSL2；
  • Linux；
  • Android Termux 为尽力支持的平台，部分功能可能不可用。

官方当前不把 Intel Mac、Homebrew 安装和 PyPI 直接安装列为受支持方式。新手应优先使用官方安装器。

3. 开始前准备 ​

准备以下三个值：

配置项应填写的内容
Base URLhttps://api.aruhub.com/v1
API Key登录 AruHub 后，在“我的密钥”页面创建；示例只使用 sk-xxxxxxxx
模型 ID从 AruHub 模型价格页、Hermes 实际加载的模型列表或 AruHub /v1/models 返回结果确认

API Key 相当于账户密码，不要发给其他人，也不要上传到 GitHub、网盘、截图或公开聊天。

Base URL 通常只填写到 /v1。不要写成 https://api.aruhub.com/v1/v1，也不要把 /chat/completions 当成 Base URL，除非工具明确要求完整接口地址。

4. 安装或打开工具 ​

Windows 或 macOS 桌面版 ​

从 Hermes Agent 官方网站下载 Hermes Desktop 安装器并按界面完成安装。不要从不明镜像下载。安装完成后打开 Hermes Desktop。

Windows 原生命令行 ​

打开 PowerShell，运行官方安装命令：

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

安装结束后关闭 PowerShell，重新打开一个新窗口，再检查：

powershell
hermes --version

Linux、macOS、WSL2 ​

打开终端运行：

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

然后检查：

bash
hermes --version

首次启动配置可以运行：

bash
hermes setup

如果向导推荐 Nous Portal，可以返回并选择自定义模型方式；AruHub API Key 不是 Nous Portal 或 ChatGPT 的登录凭证。

5. 创建 AruHub API Key ​

  1. 在浏览器登录 AruHub。
  2. 打开“我的密钥”。
  3. 点击创建密钥并设置容易识别的名称。
  4. 复制 Key，保存到自己的密码管理器。
  5. 本页示例中的 sk-xxxxxxxx 只是占位符，实际配置时替换，但不要展示完整 Key。

6. 配置 Base URL ​

推荐使用 Hermes 的交互式模型向导。在 PowerShell 或 macOS/Linux 终端运行：

bash
hermes model

按当前官方向导操作：

  1. 选择 Custom endpoint (self-hosted / VLLM / etc.)。
  2. API mode 选择 OpenAI 兼容的 Chat Completions。
  3. API base URL 输入 https://api.aruhub.com/v1。
  4. 继续到 API Key 和模型步骤。

hermes model 是终端中的完整 Provider 配置向导；聊天里的 /model 只能切换已经配置好的模型，不能新增 Provider 或录入 Key。

7. 填写 API Key ​

在 hermes model 向导询问 API key 时，粘贴真实 AruHub Key，然后确认。输入过程中界面可能隐藏字符，这是正常的。

Hermes 当前把设置放在 ~/.hermes/：

text
~/.hermes/config.yaml    非秘密配置，例如模型、Provider、Base URL
~/.hermes/.env           API Key 等秘密环境变量

YAML 是一种缩进表示层级的配置格式。不要用 Tab 键混排缩进，也不要在公开截图中打开 .env。

8. 填写或选择模型 ​

向导询问 Model name 或 Model ID 时，从 AruHub 模型价格页、Hermes 加载结果或 /v1/models 返回结果复制准确 ID。不要使用展示名称猜测。

当前官方配置文件方式可以使用命名自定义 Provider。用文本编辑器打开 ~/.hermes/config.yaml，合并以下示例：

yaml
custom_providers:
  - name: aruhub
    base_url: https://api.aruhub.com/v1
    key_env: ARUHUB_API_KEY
    api_mode: chat_completions
    models:
      replace-with-model-id: {}

model:
  provider: custom:aruhub
  default: replace-with-model-id

再打开 ~/.hermes/.env，写入密钥占位示例：

dotenv
ARUHUB_API_KEY=sk-xxxxxxxx

实际使用时替换 sk-xxxxxxxx，同时把两处 replace-with-model-id 替换为相同的准确模型 ID。api_mode: chat_completions 表示使用 OpenAI 兼容 Chat Completions 接口。

也可以在 PowerShell 或终端运行以下命令保存 Key；命令会把 API Key 类变量写入 .env：

bash
hermes config set ARUHUB_API_KEY sk-xxxxxxxx

运行前必须把占位符换成自己的 Key。不要把包含真实 Key 的命令截图或复制到聊天中。

9. 保存配置 ​

使用向导时，完成最后一步后让向导写入配置。手动编辑时：

  1. 保存 ~/.hermes/config.yaml 和 ~/.hermes/.env。
  2. 关闭仍在运行的旧 Hermes 会话。
  3. 在 PowerShell 或终端检查配置：
bash
hermes config check
hermes config get model --json
hermes status

配置输出应显示 provider 为 custom:aruhub、Base URL 为 https://api.aruhub.com/v1、模型为你填写的 ID。不要让命令输出完整 API Key。

10. 发起第一次测试 ​

在 PowerShell 或终端启动新会话：

bash
hermes chat

若当前版本直接使用 hermes 进入聊天，也可以按启动界面提示进入。输入一个低风险任务：

text
请只回复：Hermes 与 AruHub 连接测试成功。不要调用工具。

旧聊天进程不会自动读取新模型配置，因此必须新建会话。Gateway 场景需要刷新全部会话时，可以运行：

bash
hermes gateway restart

11. 如何确认配置成功 ​

同时检查：

  1. hermes config get model --json 显示 custom:aruhub 和准确模型 ID。
  2. 新会话收到模型回复，没有 401、404、429 或模型不可用错误。
  3. AruHub 用量记录出现相近时间和相同模型的请求。
  4. hermes status 没有显示仍在使用旧默认 Provider。

聊天中切换已配置模型可输入 /model；需要新增或重配 Provider 时先退出聊天，再在终端运行 hermes model。

12. 常见问题 ​

系统中已有旧的 OPENAI_BASE_URL ​

旧变量可能让某些版本或旧配置继续指向其他地址。PowerShell 只检查 Base URL：

powershell
$env:OPENAI_BASE_URL

macOS/Linux 终端运行：

bash
printenv OPENAI_BASE_URL

如果显示旧地址，先确认它来自当前终端、Shell 启动文件还是 Hermes 的 .env，再删除重复定义。最终 AruHub Base URL 应为 https://api.aruhub.com/v1。

系统中已有旧的 OPENAI_API_KEY ​

不要用会打印完整 Key 的命令。PowerShell 只检查是否存在：

powershell
if ($env:OPENAI_API_KEY) { "OPENAI_API_KEY 已设置" } else { "OPENAI_API_KEY 未设置" }

macOS/Linux 终端只检查是否存在：

bash
if [ -n "$OPENAI_API_KEY" ]; then echo "OPENAI_API_KEY 已设置"; else echo "OPENAI_API_KEY 未设置"; fi

若旧变量存在，不要把值贴给客服。优先使用本页命名的 ARUHUB_API_KEY，并检查当前 Provider 是否为 custom:aruhub。

配置文件和环境变量同时存在 ​

Hermes 当前解析顺序以命令行参数优先，其次是 ~/.hermes/config.yaml，然后是 ~/.hermes/.env 和内置默认值。非秘密设置优先放 config.yaml，Key 放 .env。避免在多个位置同时定义同一作用的 Base URL。

修改配置后旧终端仍使用旧环境变量 ​

关闭旧 Hermes 会话和终端，重新打开窗口。仅清除当前窗口变量时，PowerShell 使用：

powershell
Remove-Item Env:OPENAI_BASE_URL -ErrorAction SilentlyContinue
Remove-Item Env:OPENAI_API_KEY -ErrorAction SilentlyContinue

macOS/Linux 终端使用：

bash
unset OPENAI_BASE_URL OPENAI_API_KEY

这些命令只影响当前窗口；若新窗口仍出现旧值，还要检查 PowerShell 配置、.bashrc、.zshrc 或 ~/.hermes/.env。

同一个变量在多个文件中重复定义 ​

用文本编辑器分别检查 ~/.hermes/.env、Shell 启动文件和系统环境变量。保留一个明确来源，删除错误或重复的旧定义，然后打开新终端运行 hermes config get model --json。

401、404、429 或模型不可用 ​

401 先检查 Key；404 先检查 Base URL、模型 ID 和接口模式；429 降低频率并检查额度；模型不可用时重新核对模型 ID。不要无间隔反复重试。

13. 如何重置或修改配置 ​

  • 重新运行完整模型配置：退出聊天，在终端运行 hermes model。
  • 查看当前配置：运行 hermes config 或 hermes config get model --json。
  • 用编辑器修改：运行 hermes config edit，保存后新建会话。
  • 清理错误旧 Base URL：从 model.base_url 或对应 custom_providers 条目删除错误地址，确保只保留 https://api.aruhub.com/v1。
  • 删除单个用户设置可使用 hermes config unset KEY，但执行前先用 hermes config get KEY 确认键名。

14. 安全注意事项 ​

  • API Key 相当于账户密码，只保存在自己控制的设备。
  • 不要在文档、截图、GitHub、网盘或公开聊天中展示完整 Key。
  • 向客服提供问题时只说明请求时间、模型 ID、已遮盖的 Key 末几位和错误正文。
  • 第一次测试不要授权删除文件、部署、数据库或外部账号操作。
  • .env 是秘密文件，不要提交到代码仓库。

15. 相关文档 ​

AruHub · 统一 API 网关

Copyright © 2026 AruHub