AI AI Click
Hermes Agent Custom Model / 自定义模型接入

Hermes Agent 接入自定义大模型

以 AI Click 中转接口为案例，分别整理 OpenAI Chat Completions 与 Anthropic Messages 两种协议的 Hermes 配置、命令行验证、Gateway 重启和常见问题排查。

OpenAI 协议 Anthropic 协议 验证排障

开始前准备

Hermes 的模型配置主要分两层：非敏感配置写进 config.yaml，API Key 写进 .env。修改后 CLI 重新打开，Gateway 需要重启。

1

确认配置路径

先让 Hermes 打印实际路径，避免改错 profile。

Terminal
hermes config path
hermes config env-path
2

备份配置

修改前保留一份可回滚版本。

Terminal
cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak.$(date +%F-%H%M%S)
cp ~/.hermes/.env ~/.hermes/.env.bak.$(date +%F-%H%M%S)
3

准备模型参数

OpenAI 与 Anthropic 协议不要混用地址和模型名。

OpenAIgpt-5.5 / gpt-5.4
Anthropicclaude-sonnet-4-6 / claude-opus-4-8

OpenAI Chat Completions 协议

适合走 /v1/chat/completions 的 AI Click 中转模型。推荐默认使用 gpt-5.5，备用 gpt-5.4。

A

先测试接口

确认 Key、Base URL 和模型 ID 都可用。

Terminal
curl https://ai.aiclick.cc/v1/chat/completions \
  -H "Authorization: Bearer 你的_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {"role": "user", "content": "你好，测试 Hermes OpenAI 协议"}
    ]
  }'
B

写入 .env

Key 放到 secrets 文件，不建议硬编码进配置。

~/.hermes/.env
OPENAI_API_KEY=你的_API_KEY
如果你已经有其他 OpenAI Key，建议先备份再替换，或者使用 profile 单独隔离。
C

配置 Hermes 默认模型

通过命令写入更稳；如果字段名未来变化，也可以用 hermes config edit 手动确认。

Terminal
hermes config set model.provider openai
hermes config set model.default gpt-5.5
hermes config set model.base_url https://ai.aiclick.cc/v1
hermes config set model.api_key '${OPENAI_API_KEY}'
如果你的 Hermes 版本不支持 model.api_key 引用环境变量，就保留 .env 里的 OPENAI_API_KEY，只设置 provider、default、base_url。
YAML

config.yaml 参考结构

适合你想手动编辑时对照。

~/.hermes/config.yaml
model:
  provider: openai
  default: gpt-5.5
  base_url: https://ai.aiclick.cc/v1
  api_key: ${OPENAI_API_KEY}

Anthropic Messages 协议

适合走 /v1/messages 的 Claude 兼容路由。日常推荐 claude-sonnet-4-6，复杂任务可切 claude-opus-4-8。

A

Anthropic 接口测试

使用 x-api-key 和 anthropic-version 请求头。

Terminal
curl https://ai.aiclick.cc/v1/messages \
  -H "x-api-key: 你的_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 512,
    "messages": [
      {"role": "user", "content": "你好，测试 Hermes Anthropic 协议"}
    ]
  }'
M

支持的 Claude 模型

按成本和能力分层选择。

Haikuclaude-haiku-4-5
Sonnetclaude-sonnet-4-5 / claude-sonnet-4-6
Opusclaude-opus-4-5 / claude-opus-4-6 / claude-opus-4-7 / claude-opus-4-8
Thinkingclaude-opus-4-6-thinking
C

配置 Hermes 使用 Anthropic

Key 仍然放到 .env，配置中只引用环境变量。

~/.hermes/.env
ANTHROPIC_API_KEY=你的_API_KEY
Terminal
hermes config set model.provider anthropic
hermes config set model.default claude-sonnet-4-6
hermes config set model.base_url https://ai.aiclick.cc
hermes config set model.api_key '${ANTHROPIC_API_KEY}'
YAML

config.yaml 参考结构

如果命令方式不符合你当前版本，就手动编辑为这个结构。

~/.hermes/config.yaml
model:
  provider: anthropic
  default: claude-sonnet-4-6
  base_url: https://ai.aiclick.cc
  api_key: ${ANTHROPIC_API_KEY}

CLI 与 Gateway 生效方式

Hermes CLI 重新打开即可读取新配置；如果你用微信、Telegram、API Server 等 Gateway，需要重启 Gateway。

CLI

命令行测试

直接指定模型可以绕过默认配置做临时测试。

Terminal
hermes chat -q "用一句话说明 Hermes 已接入自定义模型"
hermes chat -m openai/gpt-5.5 -q "测试 OpenAI 协议"
hermes chat -m anthropic/claude-sonnet-4-6 -q "测试 Anthropic 协议"
Gateway

重启消息网关

改完模型后，微信/Telegram 等入口需要重启服务。

Terminal
hermes gateway restart
hermes gateway status
如果是 systemd 用户服务，也可以检查 systemctl --user status hermes-gateway。

最终验证

按这个顺序验证，能快速确认是 Hermes 配置问题，还是中转接口问题。

OK

检查命令

先看配置，再看健康检查，最后发起真实对话。

Terminal
hermes config
hermes doctor
hermes status --all
hermes chat -q "测试一下：你现在使用的是哪个模型？"

常见问题排查

重点看协议是否匹配、Key 是否放对位置、Gateway 是否重启。

401

Key 错误

Key 无效、环境变量没加载，或协议鉴权头不匹配。

  • OpenAI 协议使用 Authorization: Bearer
  • Anthropic 协议使用 x-api-key
  • 确认 ~/.hermes/.env 没有多余引号或空格
404

地址错误

OpenAI 和 Anthropic 的 Base URL 不完全一样。

  • OpenAI 配 https://ai.aiclick.cc/v1
  • Anthropic 配 https://ai.aiclick.cc
  • curl 成功后再改 Hermes
MODEL

模型不存在

模型名必须和网关支持列表完全一致。

  • OpenAI：gpt-5.5 / gpt-5.4
  • Anthropic：claude-sonnet-4-6 等 Claude ID
  • 不要把展示名当成模型 ID