Hermes Agent OpenAI 兼容 API

为什么有这个 API

Hermes 主要场景是“挂在 Telegram / Discord / 微信上的对话机器人”，但很多用户希望：

• 在 Cursor / Continue / VSCode Copilot 里用 Hermes 而不是 ChatGPT
• 自己的 Python / Node 代码里直接调 Hermes，不写新 SDK
• 把 Hermes 当作 ChatGPT 的 drop-in 替代，省掉 OpenAI 订阅费

:8642 端口正好满足这些。它说“OpenAI 协议”，但底下挂的是 Hermes 的全套能力。

启动 :8642 端口

Hermes 把 Web UI 和 OpenAI 兼容 API 都跑在 :8642 上。Docker 启动时映射端口：

docker run -d \
  -p 8642:8642 \
  -e OPENROUTER_API_KEY="sk-or-v1-..." \
  -e API_SERVER_KEY="${API_SERVER_KEY}" \
  ghcr.io/nousresearch/hermes-agent:latest

API_SERVER_KEY 是这个 API 的鉴权 token（自己生成一个长随机字符串就行）。客户端调用时通过 Authorization header 传：Authorization: Bearer <token>。

第一个调用：curl

curl http://localhost:8642/v1/chat/completions \
  -H "Authorization: Bearer ${API_SERVER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hermes-default",
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

返回的 JSON 完全是 OpenAI 格式：choices[0].message.content、usage.total_tokens 等。

用 OpenAI Python SDK 直接调

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8642/v1",
    api_key="${API_SERVER_KEY}"
)

resp = client.chat.completions.create(
    model="hermes-default",
    messages=[{"role": "user", "content": "解释下 RAG"}]
)
print(resp.choices[0].message.content)

一行不改，把 base_url 从 https://api.openai.com/v1 换成你的 Hermes 地址即可。流式响应、function calling、tool use 都支持。

Cursor / Continue 接入

在 Cursor 设置里：

• Models → OpenAI → API Base URL: https://你的-hermes-域名:8642/v1
• API Key: 你的 API_SERVER_KEY
• Model: hermes-default 或者其他你在 hermes.json 里配的别名

Continue (VSCode 插件) 配置类似，在 config.json 里把 provider 设为 openai，apiBase 指到 :8642。

Open WebUI / LibreChat 接入

这两个流行的 ChatGPT 替代 UI 都支持“OpenAI 兼容 endpoint”：

• Open WebUI：Settings → Connections → OpenAI API URL 填 :8642 地址
• LibreChat：librechat.yaml 里加一个 endpoint，baseURL 指到 Hermes

这样你就有一个完整的 Web 聊天界面 + Hermes 的能力栈，而且不依赖 OpenAI / Anthropic 订阅。

Session（持续对话）

OpenAI 协议本身是无状态的（每次调用都要传完整的 messages 数组）。Hermes 加了一个扩展字段 session_id 让你不用每次都传历史：

# 第一条消息
client.chat.completions.create(
    model="hermes-default",
    messages=[{"role": "user", "content": "我叫 Zack"}],
    extra_body={"session_id": "user-zack-session-1"}
)

# 第二条消息（不传历史，Hermes 从 session_id 找回上下文）
client.chat.completions.create(
    model="hermes-default",
    messages=[{"role": "user", "content": "我叫什么名字？"}],
    extra_body={"session_id": "user-zack-session-1"}
)
# 输出："你叫 Zack"

这是 Hermes 的扩展，普通 OpenAI SDK 通过 extra_body 传。客户端不支持 extra_body 的，可以直接构造 HTTP 请求加这个字段。

多 provider routing

:8642 不只是 OpenAI 协议的 wrapper。它接到的 model 名字会被 Hermes 路由到对应 provider：

• hermes-default：用 hermes.json 里 models.primary 配的模型
• openrouter/anthropic/claude-sonnet-4.6：直接走 OpenRouter（如果配了）
• openai/gpt-5：用 OpenAI BYOK key
• anthropic/claude-sonnet-4.6：用 Anthropic OAuth（如果配了）

详细配置看 BYOK 指南。

和 OpenAI 真实 API 的差异

• 不支持 Assistants API（/v1/assistants）—— Hermes 用自己的 Skills 协议代替
• 不支持 fine-tuning API（/v1/fine_tunes）
• 支持但有限：vision input（图片分析）—— 需要底层 provider 支持视觉的模型
• 支持：streaming、function calling、tool use、JSON mode、logit_bias

常见问题

401 Unauthorized

• API_SERVER_KEY 没传或填错了
• Authorization header 写成 Bearer<空格><token> 才对，少空格不认

:8642 端口连不上

• Docker 没映射端口：-p 8642:8642 漏了
• Caddy / Nginx 反向代理没配 :8642 路径
• Hermes 容器未启用 API（HERMES_API_ENABLED=false 等环境变量被覆盖）

能调通但响应是空字符串

• Provider 没配（OPENROUTER_API_KEY / ANTHROPIC_API_KEY 等没传）
• 额度耗尽 —— 看 Hermes 日志会有 quota exhausted 一类

托管版：OpenClaw Launch

托管版 Hermes 默认开 :8642，并通过 https://你的实例-domain.com/v1 暴露。token 在 Dashboard 里一键生成。直接当 ChatGPT API 用，连 Cursor / Continue / Open WebUI 都不用改 base_url 就能接。 OpenClaw Launch 首月 $3，之后 $6/月。

下一步

• Hermes Agent 中文介绍
• BYOK 多 provider 配置
• Skills 中文指南
• 替代 ChatGPT 订阅