跳到主要内容

Hermes Agent

将 Open WebUI 用作 Nous Research 的自主 AI 智能体（Agent）的聊天前端。

由 Nous Research 提供的 Hermes Agent 是一个内置诸多工具的自主 AI 智能体：终端访问、文件操作、网页搜索、记忆和可扩展的技能。它暴露了一个兼容 OpenAI 的 API 服务器，因此将其连接到 Open WebUI 仅需几分钟。

当您通过 Open WebUI 发送消息时，Hermes Agent 会接收该消息，决定使用哪些工具（如果有），执行它们并流式传输最终响应。您将实时看到内联的进度指示器（例如 💻 ls -la，🔍 正在搜索...）。

前提条件
  • 您的机器上已安装了 Hermes Agent (快速入门指南)
  • Open WebUI 正在运行（通过 Docker、pip 或桌面应用）
  • 大约需要 10 分钟 来完成此设置

步骤 1：安装 Hermes Agent​

如果您还没有安装 Hermes Agent，请遵循官方快速入门指南。安装后，验证其是否正常工作：

hermes --version

步骤 2：启用 API 服务器​

将以下内容添加到您的 Hermes Agent 环境文件中：

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key

将 your-secret-key 替换为任何强随机字符串。这将成为您在 Open WebUI 中要填写的 API Key。

可选配置

您还可以自定义端口和主机：

变量名默认值描述
API_SERVER_PORT8642API 服务器监听的端口
API_SERVER_HOST127.0.0.1绑定地址（默认仅本地 localhost）

步骤 3：启动网关​

hermes gateway

您应该会看到确认 API 服务器正在运行的输出：

[API Server] API server listening on http://127.0.0.1:8642
保持其运行

网关必须保持运行，Open WebUI 才能与您的智能体进行通信。对于持久化部署，可以考虑在终端复用器（如 tmux, screen）或作为系统服务中运行它。

步骤 4：在 Open WebUI 中添加连接​

  1. 在浏览器中打开 Open WebUI。
  2. 转到 ⚙️ 管理员设置 → 外部连接 → OpenAI。
  3. 点击 ➕ 添加连接。
  4. 输入以下内容：
设置项值
URLhttp://localhost:8642/v1
API Key您在步骤 2 中设置的 API_SERVER_KEY
  1. 点击 ✅ 勾选以进行验证，然后点击 保存。
在 Docker 中运行 Open WebUI？

将 localhost 替换为 host.docker.internal：

http://host.docker.internal:8642/v1

步骤 5：开始对话！​

hermes-agent 模型现在应该会出现在模型下拉菜单中。选择它并开始对话。您的智能体将能够直接通过 Open WebUI 的界面完全访问其工具集（终端、文件操作、网页搜索、记忆、技能）。

默认启用了流式传输。在智能体的最终响应出现之前，您会看到工具执行的简短内联进度指示。

Docker Compose 配置​

对于更永久的部署，可以运行预先配置好连接 Hermes Agent 的 Open WebUI：

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1
      - OPENAI_API_KEY=your-secret-key
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: always

volumes:
  open-webui:
docker compose up -d

然后打开 http://localhost:3000 并创建您的管理员账户。

备注

环境变量仅在 Open WebUI 的首次启动时生效。此后，连接设置将被存储在其内部数据库中。如需在以后更改它们，请使用管理员 UI，或删除 Docker 卷重新开始。

故障排除​

下拉菜单中未出现模型​

  • 验证 URL 中是否包含 /v1：http://localhost:8642/v1（而不仅仅是 :8642）
  • 检查网关是否正在运行：curl http://localhost:8642/health → 应返回 {"status": "ok"}
  • 检查模型列表：curl http://localhost:8642/v1/models → 应该列出 hermes-agent

连接测试通过但未加载模型​

这几乎总是由于缺少 /v1 后缀引起的。Open WebUI 的连接测试仅检查基本网络连通性，而不会检测模型发现。

“Invalid API key” 错误​

确保 Open WebUI 中的 API Key 与 ~/.hermes/.env 中的 API_SERVER_KEY 完全一致。

响应时间过长​

Hermes Agent 在做出响应前可能会执行多次工具调用。这对于复杂的查询是正常的，因为智能体实际上是在为您工作。

Linux Docker（无 Docker Desktop）​

在没有 Docker Desktop 的 Linux 系统上，默认情况下无法解析 host.docker.internal：

# 选项 1：添加主机映射
docker run --add-host=host.docker.internal:host-gateway ...

# 选项 2：使用宿主机网络模式
docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1 ...

# 选项 3：使用 Docker 网桥 IP
docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1 ...

了解更多​

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.