如何把外部 OpenAI 兼容端点添加为 Hermes WebUI 自定义 provider 并验证连接【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui如果你在一台机器上跑着一个 OpenAI 兼容的模型服务LM Studio、Ollama、vLLM、LiteLLM 代理或任何暴露/v1/models的端点想让它直接作为 Hermes WebUI 的聊天 provider 使用就需要把它添加为自定义 provider。Hermes WebUI 默认在进程内运行 Hermes Agent、直接读取HERMES_HOME配置聊天不会自动经过外部 OpenAI 兼容 API 服务器要把外部端点接入需要显式地在 WebUI 的 provider 设置里登记它的 Base URL 和凭证再通过内置的连接测试确认端点可达、模型列表能拉取成功。完成后的结果是模型下拉框出现该端点的模型选中的模型请求会路由到你配置的 Base URL。准备工作在开始之前确认以下条件Hermes WebUI 已经启动python3 bootstrap.py、./start.sh或 Docker 部署均可能在浏览器打开界面。你要接入的 OpenAI 兼容端点正在运行并且从 WebUI 所在的环境宿主机或容器网络可达。如果端点需要鉴权准备好 bearer tokenAPI key。多数本地服务器可以免密钥运行——按文档说明大多数 LM Studio、Ollama、vLLM、llama-server、TabbyAPI 安装都是 keyless 的这种情况 API key 字段留空即可。主路径在 Settings → Providers 中登记自定义 provider按 README.md 的说明把外部端点作为聊天 provider 使用的方式是在Settings → Providers中把它添加为自定义 OpenAI-compatible provider填入base_url和你的 bearer token。Settings 入口位于侧边栏底部的 Hermes Control Center控制中枢。对于本地自托管端点Ollama / LM Studio 这类本地 OpenAI 兼容模型服务器provider 卡片上会给出完整的一组字段实现见 static/panels.jsBase URL必填指向端点的 OpenAI 兼容 API 根路径带/v1后缀。Test connection点击后向该 URL 发起探测拉取模型列表。API key (optional)端点要求鉴权时填写否则留空。Model填写模型 id可配合探测结果自动填充的候选列表选择。SaveBase URL 和 Model 都非空后才可点击保存后写入该 provider 的配置供 Agent 的 provider 客户端使用。这个流程在保存前会用你填的 Base URL 做一次认证过的探测请求直接获取模型列表。首次运行时的替代入口onboarding 向导如果你的 WebUI 刚装好还没走完初始化同一件事可以在 onboarding 向导里完成。向导把 provider 按需要填写的信息量分组其中Open / self-hosted一组就包含 Ollama、LM Studio、custom OpenAI-compatible 和 AIML API需要输入 Base URL、模型API key 可选docs/onboarding.md。文档给出的一个完整远端示例AIML API 走的就是自定义 OpenAI 兼容接入路径它不是 Hermes 内置的一等 provider idBase URL 填https://api.aimlapi.com/v1然后要么用自定义 provider 的 API key 字段填密钥要么在配置里指向AIMLAPI_API_KEY环境变量让 provider 从环境读取。模型发现来自该端点的实时/v1/models响应而不是 WebUI 维护的静态模型表——这个模式对所有自定义 OpenAI 兼容端点都适用。Base URL 填写规则Base URL 必须指向 OpenAI 兼容 API 的根路径。docs/onboarding.md 给出的常见取值服务器位置典型 Base URL与 WebUI 同宿主机非 Docker的 LM Studiohttp://127.0.0.1:1234/v1与 WebUI 同宿主机非 Docker的 Ollamahttp://127.0.0.1:11434/v1Docker Desktop 里访问宿主机上的 LM Studiohttp://host.docker.internal:1234/v1Docker Desktop 里访问宿主机上的 Ollamahttp://host.docker.internal:11434/v1Linux Docker Engine 里访问宿主机服务http://api.local:port/v1配合 Compose 的extra_hosts加api.local:host-gateway局域网另一台机器http://lan-ip:port/v1其中port、lan-ip是你端点的实际端口和 IP按实际情况替换。Docker 部署下最容易踩的坑容器内的localhost指的是容器自身不是你的 Mac、Windows 宿主机、Linux 宿主机或局域网上的机器。端点在宿主机http://localhost:port上工作、但配到容器里的 WebUI 就失败是文档明确列出的典型故障形态docs/docker.md。解决办法按平台选择Docker Desktop 用host.docker.internalLinux Docker 加主机别名services: hermes-webui: extra_hosts: - api.local:host-gateway然后把 Base URL 写成http://api.local:port/v1。这个别名避免了在 WebUI 配置里写localhost而实际解析到容器回环地址的问题。README 中把 Hermes Agent 自己的外部端点接入 WebUI 的例子是base_url http://127.0.0.1:8642/v1加 bearer token可作为格式参照。验证连接验证动作就是Test connection。按 docs/onboarding.md 的说明向导/探测在保存前会请求base-url/models探测成功模型下拉框被端点返回的模型列表填充——这同时证明端点可达、鉴权通过、响应形状是 WebUI 能解析的模型目录。探测失败保存步骤会被阻断界面显示内联错误。探测错误分为固定几类DNS 失败dns、连接被拒connect_refused、超时timeout、HTTP 4xx / 5xx、响应解析失败parse、URL 非法invalid_url与不可达unreachable另有http_4xx、http_5xx等编码见 CHANGELOG.md 中POST /api/onboarding/probe的说明5 秒超时、256 KB 响应体上限。看到对应错误码即可定位方向connect_refused说明地址对但服务没监听端口或容器内localhost问题dns说明主机名解析不了timeout说明网络路径不通或端点过载http_4xx通常指向鉴权或路径错误比如 Base URL 少了或多了/v1parse说明端点通了但返回的不是预期的模型目录形状。Docker 环境下可以进容器直接探测端点这也是 onboarding 文档给出的排查命令形式docker exec hermes-webui sh -c curl -sS -w \nHTTP %{http_code}\n http://host.docker.internal:1234/v1/models | head -50命令里的hermes-webui是容器名host.docker.internal:1234按你的实际端点替换。容器内能拿到 HTTP 200 和模型 JSON而 WebUI 界面里 Test connection 失败时问题就在 WebUI 配置的 URL 与实际可达地址不一致。保存之后模型选择器里应能看到该自定义 provider 分组的模型custom_providers配置项的模型也会始终进入下拉框即使/v1/models端点当时不可达。可选在 config.yaml 中用 custom_providers 管理除了界面流程也可以在 Hermes 的config.yaml里用custom_providers[]声明端点条目包含name、base_url、api_key以及model或models。两点行为需要注意如果你在某个custom_providers条目里声明了models:白名单比如聚合网关只放开少数模型WebUI 会尊重这份白名单不再拉取实时/v1/models目录探测失败也不会显示为用户可见的诊断。用hermes modelCLI 创建的custom_providers条目在 Settings → Providers 中以只读的 config-managed 卡片展示显示已配置模型和密钥状态修改要回到 CLI。api_key支持直接写字面值、${ENV_VAR}形式的环境变量插值或通过key_env指定环境名。边界与限制免密钥的本地服务器不要硬填假 key字段留空是文档明确支持的路径。用户配置的custom_providers[].base_url主机名会被信任通过 SSRF 检查llama.cpp、vLLM、TabbyAPI 这类本地推理服务器不会被拦截但不要把端点配置成指向你无法控制的外部地址。端点本身可用不代表聊天可用provider 探测成功只证明/models可达实际对话请求还要走同一 Base URL 的 completions 路径出现异常时先用上面的错误分类和容器内curl探测缩小范围。本文覆盖的是把外部端点接为聊天 provider 的路径。把 WebUI 的聊天整体改道到一个 Hermes Gateway API 服务器HERMES_WEBUI_CHAT_BACKENDgateway是另一条独立路径见 docs/advanced-chat-setup.md与自定义 provider 接入互不替代。【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考