跳到主要内容

Hermes

Hermes Agent 是 Nous Research 推出的开源 AI 助手，支持终端操作、工具调用、记忆、技能和消息网关。Bita API 提供 OpenAI Chat Completions 兼容接口，可以作为 Hermes 的自定义模型服务商接入。

准备工作​

开始前，请准备：

  • 已安装的 Hermes Agent。
  • 一个处于启用状态、仍有可用额度的 Bita API 密钥。
  • 密钥所属分组可以使用的模型 ID。
  • 一个支持 OpenAI Chat Completions、工具调用且上下文窗口不小于 64,000 tokens 的模型。

如果尚未创建密钥或选择模型，请阅读创建 API 密钥和选择模型。

先确认模型能力

Hermes 会向模型发送工具定义，并依赖模型返回结构化工具调用。只支持普通文本对话、没有工具调用能力的模型，可能把调用内容作为文本输出，或者无法完成多步任务。

Hermes 还要求至少 64,000 tokens 的上下文窗口。不要把配置值填写得高于模型实际支持的上限。

安装 Hermes​

macOS、Linux 或 WSL2​

使用官方安装脚本：

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

安装完成后，重新加载当前 Shell：

source ~/.zshrc

使用 Bash 时改为：

source ~/.bashrc

Windows​

在 PowerShell 中运行：

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

也可以在 WSL2 中按照 macOS、Linux 的方式安装。

安装后检查版本和运行环境：

hermes version
hermes doctor

通过配置向导接入​

推荐使用 Hermes 的模型配置向导。它会保存服务商、模型和上下文长度，并把凭据写入 Hermes 的配置目录。

在普通终端中运行：

hermes model

按照提示填写：

配置项填写内容
Provider / 服务商Custom endpoint (self-hosted / VLLM / etc.)
API mode / 接口模式OpenAI Chat Completions 或 chat_completions
API base URLhttps://www.bita-api.com/v1
API key完整的 Bita API 密钥
Model name从模型广场复制的模型 ID
Context length模型实际支持的上下文长度，且不小于 64000

不同版本的选项名称可能略有差异。核心配置是：自定义端点、Chat Completions 模式、包含 /v1 的 API 地址，以及准确的模型 ID。

Base URL 必须包含 /v1

Hermes 会在 Base URL 后请求 /chat/completions 和 /models，因此这里必须填写：

https://www.bita-api.com/v1

不要只填写站点根地址，也不要填写完整的 /v1/chat/completions 路径。

启动并验证​

完成配置后启动 Hermes：

hermes

首次验证建议：

  1. 发送一条简单消息，确认模型可以正常回复。
  2. 要求 Hermes 执行一个无副作用的工具操作，例如查看当前目录。
  3. 检查启动信息中的模型名称和 Context limit 是否符合配置。
  4. 如果 Hermes 报告配置或依赖问题，退出会话后运行 hermes doctor。

也可以通过已配置的服务商，直接指定模型启动一次会话：

hermes chat --model YOUR_MODEL_ID

把 YOUR_MODEL_ID 替换为 Bita API 模型广场中的实际模型 ID。

手动配置​

配置向导不可用时，可以手动编辑 ~/.hermes/config.yaml，并使用单独的环境变量保存密钥。

将下面内容加入 ~/.hermes/config.yaml：

~/.hermes/config.yaml
custom_providers:
  - name: bita
    base_url: https://www.bita-api.com/v1
    key_env: BITA_API_KEY
    api_mode: chat_completions

model:
  provider: custom:bita
  default: YOUR_MODEL_ID
  context_length: 64000

然后在 ~/.hermes/.env 中保存密钥：

~/.hermes/.env
BITA_API_KEY=YOUR_BITA_API_KEY

替换以下内容：

  • YOUR_MODEL_ID：从模型广场复制的模型 ID。
  • YOUR_BITA_API_KEY：完整的 Bita API 密钥。
  • context_length：可以填写模型的实际上下文窗口；不确定时先使用 64000，确认模型确实支持后再提高。

保存后退出并重新启动 Hermes。不要把真实密钥直接提交到代码仓库或复制到公开日志中。

切换模型​

需要更改默认模型或重新配置服务商时，在终端中退出当前会话，再运行：

hermes model

在已经启动的 Hermes 会话中，/model 只能切换已配置的服务商和模型，不能添加新的 API 密钥或端点。使用上面的命名服务商配置后，可以在会话中切换到 Bita API 模型：

/model custom:bita:YOUR_MODEL_ID

模型 ID 必须属于当前 API 密钥的可用分组。切换模型不会改变密钥的分组权限。

常见问题​

现象建议检查
返回 401API 密钥是否完整；~/.hermes/.env 中的变量名是否与 key_env 一致；修改凭据后是否重新启动 Hermes
返回 403密钥是否启用、过期或超额；密钥分组是否支持当前模型
返回 404Base URL 是否为 https://www.bita-api.com/v1；不要遗漏 /v1，也不要填写完整接口路径
返回模型不存在模型 ID 是否与模型广场完全一致，密钥分组是否可以调用该模型
启动时提示上下文不足选择上下文窗口不小于 64,000 tokens 的模型，并把 context_length 设置为模型实际支持的值
工具调用显示成普通 JSON 文本当前模型可能不支持工具调用；换用支持工具调用的模型后重新测试
普通对话成功，但复杂任务中断检查模型的工具调用能力、上下文长度、输出上限和密钥额度
/model 中找不到 Bita API先退出会话并运行 hermes model 完成端点配置，再启动新会话
配置正确但请求失败查看 Bita API 使用日志中的接口、模型和错误信息，并运行 hermes doctor

Hermes 的配置项会随版本更新。安装和自定义服务商的最新说明请参考 Hermes 安装文档和 AI Providers 文档。

如果希望通过图形界面管理 Hermes 的服务商，也可以使用 CC Switch。