Hermes Agent · 当前配置 · 实测边界

Hermes Agent 接入 OpenAI 兼容 API

Hermes 自带 OpenAI 兼容 API 的 Custom Endpoint 配置流程。稳妥的顺序并不复杂：先在 Hermes 外验证接口，再运行 provider 向导，检查实际保存的配置，最后开一个新会话验收。本文以当前官方文档为准，不沿用旧版 custom_providers 示例。

Hermes 支持什么格式？

Hermes 官方文档说明，只要服务实现 /v1/chat/completions，就可以通过 OpenAI Compatible Custom Endpoint 接入。新增端点时，推荐运行 hermes model，选择 “Custom endpoint (self-hosted / VLLM / etc.)”。向导会询问 Base URL、API Key、模型名和 transport，并把结果写入 ~/.hermes/config.yaml。

OpenAI 兼容只说明请求协议能对接，不代表每个模型都适合 Agent。工具调用、流式输出和长上下文仍取决于模型与上游实现。

改 Hermes 配置前先测 API

测试时要使用准备交给 Hermes 的同一组 Base URL 与 Key。2026-08-02 现场验证中，下方生产路由在无 Key 时返回结构化 HTTP 401 JSON。这能确认路由可达并执行认证，但不能替代有效 Key 的模型测试。

curl https://monkeytheme.com/v1/models \
  -H "Authorization: Bearer ***"

结果	下一步
返回模型列表	从响应中复制完整模型 ID
401 JSON	检查 Bearer 请求头与 Key 状态
HTML 或 404	检查 Base URL 是否只带一次 `/v1`

使用当前 Custom Endpoint 向导

hermes model
# 选择：Custom endpoint (self-hosted / VLLM / etc.)
# Base URL: https://monkeytheme.com/v1
# API key: 自己后台生成的 Key
# Model: /v1/models 返回的完整 ID
# Transport: chat_completions

请在终端中、活动聊天之外运行这条命令。hermes model 可以新增凭据和端点；聊天内的 /model 只能切换已经配置好的 provider 与模型。

需要手工维护 YAML 时怎么写？

当前格式使用顶层 providers: 字典。密钥放进环境变量，配置里只通过 key_env 引用变量名。

# ~/.hermes/config.yaml
providers:
  monkeyai:
    api: https://monkeytheme.com/v1
    key_env: MONKEYAI_API_KEY
    transport: chat_completions
    default_model: YOUR_EXACT_MODEL_ID

# ~/.hermes/.env
MONKEYAI_API_KEY=***

旧教程可能还在使用顶层 custom_providers: 列表。Hermes 目前仍可读取，但官方已将它标为旧格式，并说明升级时会迁移到 providers:。不要为了套用旧示例去改一份本来能用的配置。

检查 Hermes 实际加载了什么

hermes config check
hermes config get model --json
hermes status

配置完成后开一个新的 Hermes 会话，用选定模型发送一条短请求。已经打开的聊天会继续使用启动时的模型，除非在会话内主动切换。如果直接请求 /v1/models 成功，而 Hermes 仍失败，应逐项核对实际保存的 Base URL、provider、transport 和完整模型 ID。

本轮没有使用私有生产 Key，也没有发起计费模型请求。已验证范围包括公开认证响应、当前 Hermes CLI 与配置文档，以及本机命令可用性。

官方资料

常见问题

Hermes Agent 能接入 OpenAI 兼容 API 吗？

可以。Hermes 官方提供 Custom Endpoint 流程，用于接入实现 /v1/chat/completions 的服务。

MonkeyAI 的 Base URL 填什么？

OpenAI 兼容端点填写 https://monkeytheme.com/v1。

应该用 hermes model 还是 /model？

新增端点和凭据时，在终端运行 hermes model；聊天内的 /model 只用于切换已经配置好的 provider。

还需要照抄旧版 custom_providers 示例吗？

不需要。当前格式是顶层 providers 字典。Hermes 仍能读取旧列表，并可以迁移。

/v1/models 路由可达就代表全部配置成功吗？

不代表。401 只能证明路由和认证边界可达；还要用有效 Key 获取模型列表，并在新会话中完成一次真实请求。