Hermes Agent 自定义 API 教程：向导入口、协议选择与工具验证

本文对应 Nous Research 的 Hermes Agent。2026 年 9 月 30 日已核对官方配置文档；“流程已核验”只表示入口和参数有依据，不表示本文向任何模型服务发过请求。

图中连线用于说明配置关系，不是接口测试结果。

先选向导，别改正在运行的会话

在终端使用 hermes model，选择 Custom endpoint。它负责新增提供商、认证和默认模型；会话内的 /model 主要用于切换已配置模型。保存新默认值后，已有会话不会因此全部换模型。请在独立测试会话操作，不要直接覆盖承担日常任务的配置。

协议和地址要一起确认

当前向导会询问 API mode，并将选择保存为提供商的 transport。官方支持 chat_completions、anthropic_messages、codex_responses 等传输方式；它们不是同一个请求结构。先向实际服务方确认协议，再填地址，不能看到“兼容”两个字就随便选。

以下仅为向导填写示意，地址是占位，本站未提供可据此使用的真实接口、Key 创建或充值服务。实际接入参数须另行取得。

API mode：chat_completions
API base URL：https://80321.cn/v1
API key：YOUR_API_KEY
Model ID：YOUR_MODEL_ID

模型 ID 必须与服务方一致。上下文长度也要填写真实限制，不能把本地数值调大当成服务端扩容。

把文本回复和工具调用分开验收

取得正式参数后，先开新会话要求只返回一行文字，再在空白测试目录验证一个只读任务。文字正常并不证明工具调用可用：服务端还须正确处理工具定义和返回结果。官方要求带工具的 Agent 使用至少 64,000 token 的上下文窗口，小于这个窗口可能在启动阶段被拒绝。

记录模型 ID、协议、是否流式和脱敏错误信息，不记录密钥。若只读任务要求额外权限，先审查要做的操作，再决定是否授权。

没有模型列表时如何排查

模型发现失败和推理失败是两个问题。官方说明某些端点没有可访问的模型列表时，向导仍可保存指定模型并给出警告。优先核对实际 ID、请求路径、凭据归属和上下文限制；不要为了消除警告去改成另一个提供商。

出现未知提供商提示时，可参考官方 hermes doctor 诊断。若服务方无法说明所需传输协议，暂停接入，而不是轮流尝试各种模式。

密钥和辅助模型的边界

命名自定义提供商支持 key_env 引用凭据；用官方向导或受控凭据入口管理秘密，不把真实 Key 放进教程、仓库或截图。部分压缩、标题、视觉任务还有单独的辅助模型设置，核对其路由后再交付敏感文件，不能仅凭主模型地址判断全部数据流向。

保留人工审批，在不含生产凭据的目录做首次验证。本文没有读取或修改任何现有 Hermes 配置。