跳转到主要内容

​
一、产品简介

Hermes Agent 是 Nous Research 开源的自托管 AI Agent，支持终端交互、持久记忆、技能与消息平台接入。通过配置 GravitexAI 自定义服务商，可以在 Hermes 中使用账户可用的 GPT、Claude、DeepSeek 等模型。

持久记忆

跨会话保留偏好与工作上下文

技能复用

将任务经验整理为可复用的 Skill

多渠道使用

通过 CLI 或消息网关使用同一个 Agent

多协议接入

按模型选择 Responses、Anthropic Messages 或 Chat Completions
本文按 2026 年 10 月 19 日查阅的官方配置文档更新，介绍 Hermes Agent 命令行与配置文件的接入方式。桌面界面操作请参考 Hermes Agent Desktop App。

​
二、环境要求

  • Linux、macOS、Windows 原生环境或 WSL2，具体支持范围以官方安装说明为准。
  • 使用 POSIX 安装脚本时，准备 Git、curl、tar 和 SHA-256 工具；运行依赖由官方安装器管理。
  • Android / Termux 使用官方独立安装指南，不要套用桌面或服务器的安装脚本。

​
三、前置条件

Hermes 要求模型上下文窗口至少为 64,000 tokens。请以实际模型和渠道的上下文限制为准，不要通过虚填配置绕过限制。

​
四、安装 Hermes Agent

安装完成后重新打开终端，或按所用 Shell 执行 source ~/.zshrc / source ~/.bashrc。
已有安装可先运行 hermes update，再按下面的步骤配置。

​
五、配置 GravitexAI

​
第一步：确认配置文件位置

Hermes 将普通设置与密钥分开保存： Linux / macOS 默认数据目录为 ~/.hermes/；Windows 原生脚本安装默认使用 %LOCALAPPDATA%\hermes\。设置了 HERMES_HOME 或使用其他安装方式时，以实际数据目录为准。可以通过 hermes config edit 打开当前配置。

​
第二步：保存 GravitexAI API Key

运行下面的命令，将占位符替换为实际密钥：
该设置会保存到当前 Hermes 数据目录的 .env。下文通过 key_env: GRAVITEX_API_KEY 引用它，无需将密钥重复写进 YAML。

​
第三步：添加自定义服务商

运行：
在 config.yaml 中添加或合并下面的配置。已有 providers 或 model 块时，请修改原块，不要重复创建同名顶层键。
模型 ID 均为示例，请替换为账户实际可用的模型。不需要的服务商可以删除；若删除默认服务商，请同时调整 model.provider 与 model.default。
协议与模型必须匹配。 Claude 原生协议的地址不带 /v1，也不需要额外添加 /anthropic；不要将 Claude 放到 Responses 服务商中。Hermes 中 Responses 对应的配置值为 codex_responses。
新版使用 providers 字典；旧版 custom_providers 列表仍兼容，官方更新器会迁移到新格式。其中，服务商条目的 base_url 可改用 api，model 改为 default_model，api_mode 改为 transport。主模型块仍使用 model.default。

​
第四步：显式选择默认服务商

添加 providers 只是登记服务商，还需要将主模型切换到它。若原配置仍保留 model.provider: auto，执行：
如需默认使用 Claude，则改为：
同时检查原有 model 块，清理指向其他服务商的旧 base_url、api_mode 与 api_key 等覆盖设置；密钥使用上文服务商条目的 key_env 引用。保存后开启新会话。

​
也可以使用交互式配置

在终端运行 hermes model，选择 Custom endpoint，按上表填写服务地址、密钥、模型与 API mode。上下文长度可先留空自动识别；手动指定时，必须填写渠道真实支持的窗口大小。 hermes model 用于新增或配置服务商；会话内的 /model 用于切换已配置的模型。协议配置详见官方 AI Providers 文档。

​
六、启动与验证

保存配置后运行：
先发送一条简单消息，确认没有认证、模型或协议错误，再尝试工具任务。 在会话中切换已配置的服务商与模型：
验证标准： 会话选中了预期模型、消息正常返回，并能完成一次简单的工具调用。hermes doctor 用于诊断配置与依赖，不能替代实际 API 调用验证。

​
七、辅助模型（可选）

上下文压缩、视觉分析和标题生成等任务可以单独指定模型。默认的 auto 会优先使用主模型，通常可以先保留默认设置。 如需指定其他已配置的服务商，可在 config.yaml 中添加：
辅助模型也必须支持相应任务；例如图片分析需选择支持视觉输入的模型。更多设置见官方模型配置指南。

​
八、接入消息平台（可选）

终端验证成功后，再配置 Telegram、Discord、Slack 等消息平台：
run 在前台运行，适用于先验证平台接入，以及 WSL2 等环境。Linux / macOS 如需安装后台服务，可使用：
平台 Token 与权限通过向导配置，具体要求见官方消息平台文档。

​
九、常用命令

技能、MCP 与执行后端等扩展设置，请参考官方配置文档；终端后端使用 terminal.backend 配置。

​
十、常见问题

检查当前 Hermes 数据目录的 .env 中是否存在有效的 GRAVITEX_API_KEY，并确认服务商的 key_env 拼写一致。再检查 GravitexAI 账户的密钥状态与模型权限。
核对所选服务商的 transport 与地址：GPT 用 codex_responses + https://api.gravitex.ai/v1；Claude 用 anthropic_messages + https://api.gravitex.ai；Chat Completions 用 chat_completions + https://api.gravitex.ai/v1。不要在地址后重复填写完整请求路径。
从 GravitexAI 模型广场复制准确的模型 ID，并确认它与服务商协议匹配。跨协议切换时，同时切换服务商与模型，不能只改模型名称。
确认模型实际支持至少 64,000 tokens。自动识别有误时，可按渠道真实窗口设置 model.context_length 或 providers.<名称>.models.<模型 ID>.context_length。该字段表示上下文窗口，不是单次回复的输出上限。
仅保存密钥或添加 providers 条目不会自动选中服务商。检查 model.provider 是否仍为 auto，按第五节第四步显式设置为 custom:gravitex-gpt 或 custom:gravitex-claude，同时设置对应的 model.default，再开启新会话。
通过 hermes config edit 确认编辑的是当前配置，检查 HERMES_HOME 与所用 profile 是否一致。清理旧的 model.base_url、model.api_mode 等与新服务商冲突的设置，重新运行 hermes model 选择服务商，并开启新会话；已运行的消息网关可执行 hermes gateway restart。

​
十一、相关资源