Hermes Agent

官方主页：hermes-agent.nousresearch.com
安装文档：hermes-agent.nousresearch.com/docs/getting-started/installation
网关配置（AI Providers）：hermes-agent.nousresearch.com/docs/integrations/providers
协议类型：OpenAI Chat Completions（自定义 endpoint 走 wire/api_mode = chat_completions）

安装

Hermes 是 Python 应用，官方安装器会自动处理全部依赖（Python、Node.js、ripgrep、ffmpeg），并完成仓库克隆、虚拟环境、全局 hermes 命令配置。其余写法以官方安装文档为准。

桌面安装器（macOS / Windows，官方推荐）

到官方下载页下载 Hermes Desktop 安装器并运行，会同时安装命令行与桌面应用。

命令行安装（Linux / macOS / WSL2 / Android Termux）

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

命令行安装（Windows 原生，PowerShell）

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

安装完成后重载 shell（source ~/.bashrc 或 source ~/.zshrc），然后用以下命令确认版本：

hermes version

对接 TokenBay

Hermes 可对接任何 OpenAI 兼容的 /v1/chat/completions 端点，因此通过「自定义 provider」即可指向 TokenBay。全部配置集中在 ~/.hermes/ 目录：

~/.hermes/config.yaml：非密钥设置（模型、provider、base URL 等），是模型与端点配置的唯一权威来源。
~/.hermes/.env：密钥（API Key、Token、密码），机密只能放这里。

凭证不写进 config.yaml 明文，而是用 key_env 指定存放 API Key 的环境变量名，运行时从 .env 读取。

Base URL 注意：Hermes 在 chat_completions 协议下只会在 base_url 后追加 /chat/completions。因此 TokenBay 的 base_url 必须写成 https://api.tokenbay.com/v1（带 /v1），而不是裸的 https://api.tokenbay.com，否则会 404。

1. 获取 API Key

控制台创建 API Key

2. 配置 API Key（写入 .env）

Hermes 通过 key_env 指定的变量名读取凭证，下面统一用 TOKENBAY_API_KEY。把它写进 ~/.hermes/.env：

变量	值
`TOKENBAY_API_KEY`	你的 TokenBay API Key（`sk-...`）

可直接用 hermes config set 写入（API Key 会被自动路由到 .env）：

hermes config set TOKENBAY_API_KEY sk-XXXXXXX

或手动编辑 ~/.hermes/.env：

# ~/.hermes/.env
TOKENBAY_API_KEY=sk-XXXXXXX

3. 配置 provider（交互式，推荐）

退出任何会话后，在终端运行配置向导：

hermes model

在菜单中选择 Custom endpoint (self-hosted / VLLM / etc.)，按提示依次填写：

提示项	填写值
API base URL	`https://api.tokenbay.com/v1`
API key	你的 TokenBay API Key（`sk-...`）
Model name	`claude-sonnet-4.6`（或任意下方推荐模型 ID）
API mode	`chat_completions`

向导会把结果持久化到 ~/.hermes/config.yaml。

4. 备选：手动写入 config.yaml

若不想用向导，可直接编辑 ~/.hermes/config.yaml，以「命名自定义 provider」的方式注册 TokenBay：

# ~/.hermes/config.yaml
custom_providers:
  - name: tokenbay
    base_url: https://api.tokenbay.com/v1
    key_env: TOKENBAY_API_KEY
    api_mode: chat_completions
 
model:
  default: claude-sonnet-4.6
  provider: custom:tokenbay

字段说明：

字段	含义
`name`	provider 名称，引用时写作 `custom:tokenbay`
`base_url`	TokenBay 的 OpenAI 兼容端点根（含 `/v1`）
`key_env`	存放 API Key 的环境变量名（对应 `.env` 中的 `TOKENBAY_API_KEY`）
`api_mode`	协议类型，TokenBay 用 `chat_completions`
`model.default`	默认模型 ID
`model.provider`	激活的 provider，须与上面的 `name` 对应（`custom:<name>`）

配置层级：config.yaml 是模型/端点配置的唯一权威来源。命令行参数（如 hermes chat --model ...）优先级最高，仅对单次调用生效；其次是 config.yaml；机密回退到 .env。

5. 推荐模型

Hermes 是长程自主代理，建议使用工具调用与长上下文表现强的模型：

用途	模型 ID
自主代理 / 长任务（推荐默认）	`claude-sonnet-4.6`
最强推理 / 重度编码	`claude-opus-4.8`
高性价比 / 轻量子代理	`claude-haiku-4.5`

模型 ID 直接透传上游，无前缀。完整可用列表见模型清单，或以控制台 Models 页面为准；接入前请核对并确认所属分组已授权该模型。

模型名格式：TokenBay 的模型名称中版本号仅接受小数点形式（如 claude-sonnet-4.6），不要写成连字符形式（claude-sonnet-4-6）。

6. 进阶配置：长任务超时

自主代理常跑长任务。Hermes 的请求超时默认已较宽松（HERMES_API_TIMEOUT 默认 1800 秒 / 30 分钟），一般无需调整；若需显式覆盖，可在 .env 中设置 legacy 环境变量（单位秒）：

# ~/.hermes/.env
TOKENBAY_API_KEY=sk-XXXXXXX
HERMES_API_TIMEOUT=1800
HERMES_API_CALL_STALE_TIMEOUT=300

变量	含义	官方默认值
`HERMES_API_TIMEOUT`	单次请求（socket 读取）超时上限	`1800`（秒）
`HERMES_API_CALL_STALE_TIMEOUT`	非流式调用「无响应」判定上限	`300`（秒）

推荐用 config.yaml 的 provider 粒度设置：官方现支持 providers.<id>.request_timeout_seconds（或 timeout_seconds）与 providers.<id>.stale_timeout_seconds，优先级高于上述 legacy 环境变量，也可在 models.<model> 下做单模型覆盖。具体写法以官方 Configuration 文档为准。