Custom endpoint · CLI / Gateway

Hermes Agent 接入

Hermes 当前把 config.yaml 作为模型、provider 和 Base URL 的事实源。Handsfree Club 使用命名 Custom endpoint，走 OpenAI Chat Completions 兼容入口。

协议OpenAI Chat Completions

Base URLhttps://api.handsfreeclub.com/v1

推荐模型gpt-5.6-terra

30 秒摘要

先确保终端中已有 OPENAI_API_KEY，再把下面的 custom_providers 段合并到 ~/.hermes/config.yaml，运行 hermes doctor 后启动 Hermes。

准备 Key，确认 openai-default 权限

可先运行本站一键脚本，它会安全写入 OPENAI_API_KEY 与 OPENAI_BASE_URL。脚本不会替你改 Hermes 的 provider，避免覆盖已有模型配置。

macOS / Linux

bash <(curl -fsSL https://handsfreeclub.com/install.sh) --only=codex

已经装好 Hermes 的用户：不要再次运行 hermes setup 覆盖现有工具、Gateway 或记忆设置；只补下面的 provider 即可。

添加 Handsfree 命名 provider

编辑 ~/.hermes/config.yaml，保留你的其他配置，将下面两段合并进去。Key 通过环境变量读取，不写进 YAML。

~/.hermes/config.yaml

custom_providers:
  - name: handsfree
    base_url: https://api.handsfreeclub.com/v1
    key_env: OPENAI_API_KEY
    api_mode: chat_completions

model:
  provider: custom:handsfree
  default: gpt-5.6-terra

也可以运行 hermes model，选择 Custom endpoint，依次填写 Base URL、Key 与精确模型名；交互式向导最终同样写入 config.yaml。

验证并切换模型

terminal / Hermes chat

hermes doctor
hermes

# 在 Hermes 会话内切换
/model custom:handsfree:gpt-5.6-terra

gpt-5.6-sol高难度推理、架构与复杂调试

gpt-5.6-terra默认推荐，日常开发平衡档

gpt-5.6-luna快速、低成本、批量任务

注意：终端外的 hermes model 用来新增 provider；会话内的 /model 只能在已经配置好的 provider 之间切换。裸 gpt-5.6 不可用。

常见问题

401：新终端没有读到 OPENAI_API_KEY，重新打开终端或重新 source Handsfree 环境文件。
403：该 Key 不属于 openai-default，或尚未开放 GPT-5.6。
404：Base URL 少了 /v1，或 api_mode 不是 chat_completions。
Unknown provider：确认 provider 为 custom:handsfree，并运行 hermes doctor。

配置依据：Hermes 官方文档确认 Custom endpoint 由 hermes model 或 config.yaml 管理，命名 provider 使用 key_env 与 api_mode。查看官方 provider 文档。