跳到主要内容

Hermes Agent

把 Open WebUI 作为 Nous Research 自主 AI Agent 的聊天前端。

Hermes Agent 是 Nous Research 开发的自主 AI Agent，内置终端访问、文件操作、网页搜索、记忆和可扩展技能。它会暴露一个兼容 OpenAI 的 API 服务，因此接入 Open WebUI 只需几分钟。

当你通过 Open WebUI 发送消息时，Hermes Agent 会接收消息，决定是否调用工具，执行相关操作，并将最终回复流式返回。你还会实时看到内联进度提示（例如 💻 ls -la、🔍 searching...）。

你需要准备
  • 本机已安装 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 密钥。

可选配置

你也可以自定义端口和监听地址：

变量默认值说明
API_SERVER_PORT8642API 服务监听端口
API_SERVER_HOST127.0.0.1绑定地址（默认仅本机可访问）

第 3 步：启动 Gateway​

hermes gateway

你应该看到类似如下输出，表示 API 服务已启动：

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

Open WebUI 需要依赖该 gateway 与你的 Agent 通信。对于长期部署，建议把它放进 tmux、screen 或配置成系统服务。

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

  1. 在浏览器中打开 Open WebUI。
  2. 进入 ⚙️ 管理面板 → 连接 → OpenAI。
  3. 点击 ➕ 添加连接。
  4. 填写以下内容：
设置项值
URLhttp://localhost:8642/v1
API 密钥第 2 步中设置的 API_SERVER_KEY
  1. 点击 ✅ 勾选按钮进行验证，然后点击 保存。
如果 Open WebUI 运行在 Docker 中？
http://host.docker.internal:8642/v1

第 5 步：开始聊天！​

现在，hermes-agent 模型应该已经出现在模型下拉框中。选中它即可开始聊天。你的 Agent 将通过 Open WebUI 界面直接获得其完整工具集（终端、文件操作、网页搜索、记忆、技能）的能力。

流式输出默认开启。工具执行时你会看到简短的内联提示，随后再出现 Agent 的最终回复。

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 首次启动时生效。之后，连接设置会存储在其内部数据库中。若之后要修改，请使用管理界面，或删除 Docker 卷后重新开始。

故障排查​

下拉框中没有模型​

  • 确认 URL 包含 /v1：http://localhost:8642/v1（而不只是 :8642）
  • 检查 gateway 是否在运行：curl http://localhost:8642/health → {"status": "ok"}
  • 检查模型列表：curl http://localhost:8642/v1/models → 应返回 hermes-agent

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

几乎总是因为缺少 /v1 后缀。Open WebUI 的连接测试只检查基础连通性，不会验证模型发现是否正常。

出现 “无效的 API 密钥” 错误​

请确认 Open WebUI 中填写的 API 密钥 与 ~/.hermes/.env 中的 API_SERVER_KEY 完全一致。

响应耗时较长​

Hermes Agent 可能在回复前执行了多个工具调用。对于复杂查询，这很正常——因为 Agent 的确在代表你完成真实工作。

Linux Docker（无 Docker Desktop）​

在不带 Docker Desktop 的 Linux 上，host.docker.internal 默认不会解析：

# 方案 1：添加 host 映射
docker run --add-host=host.docker.internal:host-gateway ...

# 方案 2：使用 host 网络
docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1 ...

# 方案 3：使用 Docker bridge IP
docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1 ...

了解更多​

本内容仅供参考，不构成任何保证、担保或合同承诺。Open WebUI 按“现状”提供。请参阅您的许可协议 以了解适用条款。