跳转到内容
简体中文
РусскийEnglish简体中文HindiEspañolPortuguês (BR)日本語FrançaisDeutsch한국어
免费注册
在 Coding Agent 接入

Hermes Agent 安装与 API 配置

安装 Hermes Agent，配置 BetterToken Base URL 和 API Key，选择模型并排查常见错误。

要在 Hermes Agent 中使用 BetterToken，请准备 API Key，填写下表中的 Base URL，并从模型广场选择当前可用的 Model ID。

重点信息

字段填写内容
API KeyBetterToken API Key
Base URLhttps://bettertoken.ai/v1
Model从模型广场复制的当前 Model ID

准备工作

工具特定要求

  • 从模型广场复制准确的 Model ID。
  • macOS、Linux、Windows 10/11 或 WSL2 环境
  • 用于 Hermes Agent 工具调用的模型至少具备 64K 上下文窗口

安装

安装 Hermes Agent

Desktop（macOS / Windows）

Hermes 官方推荐 macOS 和 Windows 用户使用 Desktop 安装器。前往 Hermes Desktop 下载页，下载并运行对应系统的安装程序。

Linux / macOS / WSL2

终端窗口
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

安装完成后，请打开新终端或重新加载 shell，再运行 hermes。

Windows PowerShell

Hermes Agent 原生支持 Windows 10 和 Windows 11。打开 PowerShell 或 Windows Terminal，然后运行：

终端窗口
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

安装不需要管理员权限。完成后请重新打开 PowerShell，让更新后的用户 PATH 生效。

验证安装：

终端窗口
hermes --version
hermes doctor

手动配置

优先使用 Hermes Agent 的交互式模型配置界面。只有在需要手动设置时，才直接编辑配置文件。

字段填写内容
API KeyBetterToken API Key
Base URLhttps://bettertoken.ai/v1
Model从模型广场复制的当前 Model ID

配置步骤

交互式配置

运行模型选择器

先退出正在运行的 Hermes 聊天，再执行：

终端窗口
hermes model

选择 Custom endpoint

在 provider 列表中选择 Custom endpoint (self-hosted / VLLM / etc.)。

填写 BetterToken 配置

按提示依次输入：

  • Base URL：https://bettertoken.ai/v1
  • API Key：你的 BetterToken API Key
  • Model：从模型广场复制的 模型 ID

如果 Hermes 询问 API mode，请选择 OpenAI-compatible Chat Completions 选项。如果需要填写 context length，请使用该模型公布的值，并确保至少为 64K。

启动 Hermes Agent

终端窗口
hermes --tui

你也可以运行 hermes 使用经典终端界面。

配置文件

交互式配置会自动验证并保存 endpoint，因此更加稳妥。如需手动配置，请将非敏感的模型设置写入 ~/.hermes/config.yaml：

model:
  default: YOUR_MODEL_ID
  provider: custom
  base_url: "https://bettertoken.ai/v1"

将 API Key 单独写入 ~/.hermes/.env：

OPENAI_API_KEY=YOUR_API_KEY

在原生 Windows 中，这两个文件位于 %LOCALAPPDATA%\hermes\，而不是 ~/.hermes/。替换 YOUR_MODEL_ID 和 YOUR_API_KEY 后，先运行 hermes doctor，再启动 Hermes。

验证连接

使用 hermes --tui 或 hermes 启动，然后发送以下短消息：

Reply with HERMES_OK only. Do not use tools.

如果 Hermes 返回 HERMES_OK，且没有认证、endpoint 或 Model ID 错误，就说明连接成功。接下来先完成一个小型只读任务，再启用 gateway、定时任务或其他工具。

切换模型

在聊天外运行 hermes model，可以新增或重新配置 provider。在聊天中使用 /model，可以切换已经配置好的 provider 和模型。请使用模型广场中的完整 Model ID。

常见错误

错误排查方式
401 或 Unauthorized检查 BetterToken API Key，并删除首尾空格。
404检查 Base URL，不要附加具体 endpoint 路径。
model not found从模型广场重新复制当前 Model ID。
hermes: command not found安装后打开新终端，再检查 PATH。
更新后配置错误运行 hermes config check；如果提示迁移，再运行 hermes config migrate。

排障提示

  • 无响应或请求失败时，先确认 Base URL 是否正好是 https://bettertoken.ai/v1。这里通常不要再拼接 /chat/completions。
  • 从模型广场复制准确的 Model ID。
  • 报鉴权失败时，确认 API Key 没有复制空格，确认 Key 未过期。
  • 仍在使用旧模型时，退出聊天，运行 hermes model 重新保存 custom endpoint，再开始新聊天。
  • 接入 BetterToken 时通常不需要额外设置 User-Agent 或其他 headers。只有当你还接了自定义网关、租户路由、审计或缓存服务时，再按对应上游服务的官方文档补充。

若网关要求额外的认证头，Hermes 支持在 config.yaml 的 providers.<provider-name> 下设置 extra_headers。按命名 provider 配置说明填写所需头名称，并妥善保管凭据值。

相关 FAQ

技术说明

协议、endpoint 与 provider 内部字段

本页配置使用 https://bettertoken.ai/v1。工具会自行拼接 OpenAI-compatible endpoint；除非具体字段明确要求，否则不要在 Base URL 后附加 /chat/completions 或 /responses。

功能速查

能力用途
Terminal UI在终端中直接和 Agent 交互
Skills为重复任务沉淀可复用流程
MCP连接本地或远程工具能力
Scheduled tasks配置定时任务和周期性工作流
Subagents将复杂任务拆给不同子 Agent
Message gateway把 Agent 接入更多消息入口

从 OpenClaw 迁移

如果你已经使用 OpenClaw，可以先在 Hermes Agent 当前版本中检查是否提供迁移命令。迁移前建议先做 dry run。

终端窗口
hermes claw migrate --dry-run

确认无误后再执行正式迁移：

终端窗口
hermes claw migrate

迁移后仍建议检查 Hermes Agent 中的 Base URL、API Key 和模型 ID，确保它们分别对应 https://bettertoken.ai/v1、你的 BetterToken API Key，以及准确的模型 ID。

Hermes 官方参考