Hermes Agent配置

Hermes Agent 是 Nous Research 推出的开源终端 AI 编程工具，支持以 Anthropic、OpenAI 等协议接入 TokenSwitch 平台。

1. 安装 Hermes Agent

各平台安装方式如下，完整的安装选项、前置条件与故障排查请参见官方安装指南。

Linux / macOS / WSL2

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

Windows（原生 PowerShell）

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

Android / Termux

在 Termux 中执行与 Linux 相同的安装命令，安装脚本会自动检测 Termux 并切换到适配 Android 的安装流程（通过 pkg 安装系统依赖）：

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

说明：

• 安装脚本会自动安装 Python 3.11、Node.js、ripgrep、ffmpeg 等依赖，并在 ~/.hermes/hermes-agent 创建受管理的隔离环境，这是官方唯一受支持的安装方式，请勿使用 pip install hermes-agent。

• 如需同时安装命令行与桌面应用，可从官网下载 Hermes Desktop 安装器。

安装完成后，重新加载终端环境并验证，输出版本号即表示安装成功：

source ~/.bashrc    # 如果使用 zsh，改为 source ~/.zshrc
hermes --version

2. 配置接入凭证

先在平台创建 API Key，模型 ID 可在「门户 / 模型广场」中复制。接入参数说明：

配置项	说明
model.provider	必须设置为 custom（Hermes 默认使用 OpenRouter）。
model.base_url	。Anthropic 协议客户端会自行拼接 /v1/messages，末尾不要加 /v1（参见 Cline配置中「关于 Base URL 中的 /v1」）。
model.api_mode	设置为 anthropic_messages。
model.api_key	平台 API Key。
model.default	默认模型 ID，建议使用 Claude 系列模型。

以下三种配置方式任选其一。将 YOUR_API_KEY 替换为真实的 API Key。

方式一：hermes config set 命令（推荐）

hermes config set model.provider custom
hermes config set model.base_url {{apiUrl}}
hermes config set model.api_mode anthropic_messages
hermes config set model.api_key YOUR_API_KEY
hermes config set model.default claude-sonnet-4.5

Hermes 会自动将值写入正确的文件：密钥类写入 ~/.hermes/.env，非密钥配置写入 ~/.hermes/config.yaml。

方式二：hermes model 交互式配置

hermes model

按交互提示选择 Custom endpoint (enter URL manually)，依次填入 Base URL、API Key，选择 API 兼容模式，最后填入模型 ID。适合不想记参数名的场景。具体交互流程见下图（以 OpenAI 兼容协议为例）：

注意 Base URL 与 API 兼容模式（步骤 ④）需要匹配：选 Auto-detect 或 Chat Completions（OpenAI 兼容）时，Base URL 填 （如图所示）；选 Anthropic Messages 时，Base URL 填 ，不带 /v1（与上表一致）。

方式三：直接编辑配置文件

编辑 ~/.hermes/config.yaml，写入：

model:
  default: claude-sonnet-4.5
  provider: custom
  base_url: {{apiUrl}}
  api_mode: anthropic_messages
  api_key: YOUR_API_KEY

出于安全考虑，密钥更推荐通过方式一写入（会自动存入 ~/.hermes/.env，与普通配置分开存放），避免明文保存在 config.yaml 中。

注意：Hermes Agent 要求模型最低支持 64K token 上下文，请选择满足要求的模型。

3. 验证配置

配置完成后，发送一条测试消息：

hermes chat -q "你好"

如果返回正常回复，则配置成功。日常使用可选择两种界面：

hermes            # 经典 CLI
hermes --tui      # 现代 TUI（推荐）

如需切换模型，通过 -m 参数指定：

hermes chat -m claude-opus-4.5

4. 常见问题

配置过程中遇到报错，可根据 HTTP 状态码和响应体中的 code、message 字段，对照用户错误码指南排查。

配置后仍连接到 OpenRouter

Hermes Agent 默认使用 OpenRouter 作为推理提供商。接入平台时 model.provider 必须设置为 custom，请执行以下命令确认：

hermes config set model.provider custom

报错 401 认证失败

API Key 填写错误或已失效，请登录 https://neolink.com/ ，在「API Key」菜单页确认或重新创建。详见 HTTP 401 — 认证失败。

报错 404 Invalid URL

通常是 model.base_url 末尾多加了 /v1。Anthropic 协议下应填 ，详见 HTTP 404 — 未找到。

5. 官方文档

更多功能说明请参考：

https://hermes-agent.nousresearch.com/docs/getting-started/quickstart