Hermes Agent 配置教程
Hermes Agent 的模型、供应商和自定义 endpoint 都保存在 ~/.hermes/config.yaml;API Key 等敏感信息保存在 ~/.hermes/.env。ai2save 使用 OpenAI Compatible 接口,Base URL 是 https://ai2save.com/v1。
1. 创建 API Key
- 打开 https://ai2save.com/keys。
- 创建密钥并选择包含目标模型的分组。
- 复制完整
sk-...Key。 - 记录控制台显示的真实模型 ID,例如
gpt-5.5。
2. 推荐使用内置向导
在终端执行:
hermes model
按提示选择:
Custom endpoint (self-hosted / vLLM / etc.)
依次输入:
API base URL: https://ai2save.com/v1
API key: sk-你的密钥
Model name: gpt-5.5
向导会把这些值写入 ~/.hermes/config.yaml。不要把 Base URL 写到 .env;Hermes 官方约定模型 endpoint 配置来自 config.yaml。
3. 手工编辑配置文件
编辑 ~/.hermes/config.yaml:
model:
provider: custom
default: gpt-5.5
base_url: https://ai2save.com/v1
key_env: AI2SAVE_API_KEY
字段说明:
provider: custom:使用任意 OpenAI Compatible endpoint。default:默认模型 ID,必须与控制台开放的模型 ID 完全一致。base_url:必须带/v1,Hermes 会在此基础上请求/chat/completions。key_env:指向保存密钥的环境变量名。
编辑 ~/.hermes/.env:
AI2SAVE_API_KEY=sk-你的密钥
.env 保存敏感信息,config.yaml 保存非敏感模型配置。不要把 .env 提交到 Git。
4. 使用配置命令写入
也可以使用 Hermes 自带命令,避免 YAML 缩进错误:
hermes config set model.provider custom
hermes config set model.default gpt-5.5
hermes config set model.base_url https://ai2save.com/v1
hermes config set model.key_env AI2SAVE_API_KEY
hermes config set AI2SAVE_API_KEY sk-你的密钥
hermes config check
AI2SAVE_API_KEY 是大写环境变量名,Hermes 会自动写入 ~/.hermes/.env。
5. 重启并验证
- 完全退出当前 Hermes 会话或 Gateway。
- 重新启动 Hermes。
- 新建会话并发送一句短问题。
- 在会话中输入
/model,确认当前模型是custom/gpt-5.5或gpt-5.5。
临时使用指定模型:
hermes chat --provider custom --model gpt-5.5
第一次验证建议关闭并行任务和复杂工具,只发送短文本。鉴权和模型连通后,再逐步开启 terminal、web、file 等工具。
6. 常见报错
- 401 / invalid_api_key:
AI2SAVE_API_KEY不存在或值不完整。执行hermes config get model.key_env检查引用。 - 404 / model not found:
model.default不是控制台开放的真实模型 ID。 - 连接失败:
base_url应为https://ai2save.com/v1;不要写成https://ai2save.com。 - 配置未生效:旧
OPENAI_BASE_URL只影响openai-apiprovider,不会自动作用于custom;检查config.yaml中model.base_url。 - YAML 解析失败:不要出现重复的
model:块,把所有字段合并在同一个块里。 - 工具调用异常:先确认模型支持 tool calling,并用短文本请求建立基线,再开启工具集。