Hermes Agent

安装 Hermes Agent，并通过具名自定义 provider 调用 TokenHub 的 OpenAI 兼容接口。

Hermes Agent 支持任意实现 /v1/chat/completions 的 OpenAI-compatible 自定义端点。在 Hermes 中创建一个名为 tokenhub-custom 的独立 custom provider，并从本地环境读取 API Key 即可。

本教程使用的 TokenHub endpoint 是 https://us-api.tokenhub.com/v1/chat/completions。

适合场景

Hermes 适合需要终端 Agent、工具调用、长期记忆和自动化工作流的场景。第一次接入时，先用只读任务验证 Key、Base URL 和模型，再逐步开放文件修改、终端命令与外部工具。

安装 Hermes Agent

先阅读 Hermes Agent 官方 Integrations 文档和自定义与自托管 LLM 提供商文档。macOS、Linux、WSL2 或 Termux 可使用官方安装脚本：

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

Windows 可在 PowerShell 中运行：

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

安装后重新打开终端，并确认命令可用：

hermes --version

准备 TokenHub 凭证

在 TokenHub 工作台创建 API Key，并从模型列表选择支持 OpenAI Chat Completions 和工具调用的真实 Model ID。下面以 gpt-4.1 为例；如果工作区没有这个模型，请替换为可用 ID。

Hermes 可以通过 key_env 从 ~/.hermes/.env 读取密钥：

TOKENHUB_API_KEY=sk-...

不要把真实 Key 写进项目仓库或直接写入 config.yaml。

配置具名自定义 provider

Hermes 当前的 named custom provider schema 使用 custom_providers 列表，并支持 name、base_url、key_env 和 api_mode。在 ~/.hermes/config.yaml 中写入：

custom_providers:
  - name: tokenhub-custom
    base_url: '__API_BASE_URL__/v1'
    key_env: TOKENHUB_API_KEY
    api_mode: chat_completions

model:
  provider: 'custom:tokenhub-custom'
  default: 'gpt-4.1'

关键字段：

字段	作用
`custom_providers[].name`	本地自定义 provider 名称，与任何内置厂商 provider 无关。
`base_url`	TokenHub 的 OpenAI-compatible Base URL，必须保留 `/v1`。
`key_env`	从环境变量 `TOKENHUB_API_KEY` 读取密钥。
`api_mode`	`chat_completions` 对应 `/v1/chat/completions`。
`model.default`	TokenHub 模型列表中的真实 Model ID。
`model.provider`	使用 `custom:tokenhub-custom` 选择上面的具名自定义 provider。

不要把 model.provider 写成裸的 tokenhub。Hermes 将这个名称作为内置 provider 的别名处理；自定义端点必须使用 custom:tokenhub-custom 这种 custom:<名称> 形式。

也可以在 Hermes 会话外运行：

hermes model

选择 “Custom endpoint”，输入 https://us-api.tokenhub.com/v1、API Key、模型名，并将 API mode 设为 Chat Completions。向导最终仍会把配置写入 ~/.hermes/config.yaml。

启动和切换模型

配置完成后启动 Hermes：

hermes chat

在会话中切换具名自定义 provider 时，使用三段式引用：

/model custom:tokenhub-custom:gpt-4.1

hermes model 用于添加或调整 provider；会话内的 /model 只切换已经配置好的 provider 与模型。

验证连接

进入 Hermes 后先发送只读提示：

请阅读当前项目的 README，并用三句话总结项目用途。不要修改任何文件，也不要运行写入命令。

收到正常回复后，到 TokenHub 请求日志确认请求使用了预期 Model ID、/v1/chat/completions endpoint、token 用量和计费分组。确认无误后，再测试工具调用、文件编辑和自动化任务。

临时环境变量验证

如果只想确认当前终端是否读取到了 Key，可以临时导出：

export TOKENHUB_API_KEY="sk-..."
hermes chat

Base URL、API mode 和模型仍以 ~/.hermes/config.yaml 为准。验证成功后，把 Key 保存到 ~/.hermes/.env。

常见问题

现象	处理方式
401 或认证失败	确认 `~/.hermes/.env` 中的 `TOKENHUB_API_KEY` 有效，并重新启动 Hermes。
请求发往错误地址	检查 `custom_providers` 中 `tokenhub-custom` 的 `base_url` 是否为 `https://us-api.tokenhub.com/v1`。
请求协议错误	确认 `api_mode` 是 `chat_completions`，不要误用 `anthropic_messages`。
404 或模型不存在	使用 TokenHub 模型列表中的真实 Model ID，并检查 `model.default`。
`/model` 找不到 TokenHub	先退出会话运行 `hermes model`，或检查 `model.provider` 是否为 `custom:tokenhub-custom`。
工具调用失败	先换用支持 OpenAI tool calling 的模型，再用简单只读工具验证。

本页目录