Hermes + Open-WebUI 配置与使用

概述

Hermes 内置 OpenAI 兼容的 HTTP API 服务（API Server 适配器），Open-WebUI 可以直接连接作为后端 LLM 提供商。你通过 Open-WebUI 的 Web 界面与 Hermes 交互，获得完整的 AI 助理能力。

兼容前端：Open-WebUI、LobeChat、LibreChat、AnythingLLM、NextChat、ChatBox 等

架构


┌──────────────────────┐
│   Open-WebUI (Web)   │
│  (任意浏览器访问)     │
└─────────┬────────────┘
          │ OpenAI API (Bearer Key)
          ▼
┌──────────────────────┐
│   nginx (443)        │  ← 单一对外出入口
│   /hermes-api/ →     │
└─────────┬────────────┘
          │ http://hermes:8642
          ▼
┌──────────────────────┐
│   Hermes API Server   │
│   POST /v1/chat/      │
│   completions         │
└──────────────────────┘

端点清单：

  • POST /v1/chat/completions — Chat Completions（无状态）
  • POST /v1/responses — 有状态对话
  • GET /v1/models — 模型列表
  • GET /health — 健康检查

配置步骤

1. 启用 Hermes API Server

在 .env 中添加：

API_SERVER_ENABLED=true
API_SERVER_KEY=kc12345678
API_SERVER_HOST=0.0.0.0

可选参数：

  • API_SERVER_PORT=8642 — 默认 8642
  • API_SERVER_CORS_ORIGINS=https://your-openwebui-domain.com — CORS 白名单
  • API_SERVER_MODEL_NAME=hermes-agent — /v1/models 返回的模型名

配置后需重启 Hermes Gateway 使其生效。

2. Nginx 转发（现有架构）

在 /www/nginx/conf.d/ 下已有配置中增加：

location /hermes-api/ {
    proxy_pass http://hermes:8642/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_read_timeout 120s;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

然后 nginx -t && nginx -s reload。

3. Open-WebUI 后台设置

  1. 登录 Open-WebUI → 管理面板 → 设置 → 外部连接
  2. OpenAI API Base URL：https://arm.atibm.com/hermes-api/v1
  3. API Key：kc12345678
  4. 保存 → 模型列表应出现 hermes-agent

注意

  • API Server 是 Hermes Gateway 的一个平台适配器，与 Telegram/Discord 等并行运行，不是独立的服务进程
  • Open-WebUI 发起的每个请求对应 Hermes 一次独立的会话交互
  • Header X-Hermes-Session-Id 可让无状态端点延续上下文
  • Header X-Hermes-Session-Key 可实现长期记忆隔离
  • API Server 需要 aiohttp（Hermes 自带）
  • 认证方式：Authorization: Bearer kc12345678