跳到主要内容

Hermes Agent

把 OPL 数据空间作为 Nous Research 自主式 AI agent 的聊天前端。

Hermes Agent 是 Nous Research 提供的自主式 AI agent，内置终端访问、文件操作、网页搜索、记忆与可扩展技能。它暴露了一个 OpenAI 兼容 API 服务，因此可以很自然地接入 OPL 数据空间。

当你从 OPL 数据空间发送消息时，Hermes Agent 会接收请求，决定是否使用工具、执行相关操作，并把最终结果流式返回。你还能在界面中看到简短的中间进度提示，例如 💻 ls -la、🔍 searching...。

你需要准备
  • 已安装 Hermes Agent（参考其 quickstart）
  • 正在运行的 OPL 数据空间
  • 大约 10 分钟

第 1 步：安装 Hermes Agent​

如果尚未安装，请先按官方 quickstart 完成安装，并确认命令可用：

hermes --version

第 2 步：启用 API 服务​

在 Hermes Agent 的环境文件中加入：

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key

请把 your-secret-key 换成一串足够强的随机字符串，这就是稍后要填进 OPL 数据空间的 API Key。

可选配置

你还可以调整端口和监听地址：

变量默认值说明
API_SERVER_PORT8642API 服务监听端口
API_SERVER_HOST127.0.0.1默认只监听本机

第 3 步：启动网关​

hermes gateway

如果成功，你会看到类似输出：

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

只要 OPL 数据空间要和 Hermes Agent 通讯，这个 gateway 进程就必须保持运行。可以考虑放进 tmux、screen，或配置成系统服务。

第 4 步：在 OPL 数据空间中添加连接​

  1. 打开 OPL 数据空间。
  2. 前往 ⚙️ 管理设置 → 连接 → OpenAI。
  3. 点击 ➕ 添加连接。
  4. 填入：
设置项值
URLhttp://localhost:8642/v1
API Key第 2 步设置的 API_SERVER_KEY
  1. 点击 ✅ 验证，再点击 保存。
OPL 数据空间 在 Docker 中运行？

请把 localhost 换成：

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

第 5 步：开始聊天​

hermes-agent 模型现在应该会出现在模型下拉里。选中它后即可开始聊天。该 agent 会直接使用自己的工具集，包括终端、文件操作、网页搜索、记忆和技能系统。

流式输出默认启用，工具执行期间你会先看到简短的中间状态，再收到最终回复。

Docker Compose 方式​

如果你想做更稳定的部署，可以直接让 OPL 数据空间在启动时预置 Hermes Agent 连接：

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 并创建管理员账号即可。

备注

这些环境变量只会在 OPL 数据空间首次启动 时生效。之后连接配置会持久化到内部数据库。若要重新初始化，可以删除 Docker 卷后重启。

故障排查​

下拉中没有模型​

  • 确认 URL 带 /v1
  • 检查 gateway 是否在运行：curl http://localhost:8642/health
  • 检查模型列表：curl http://localhost:8642/v1/models

连接验证通过，但模型没有加载​

通常是 URL 少了 /v1。基础连通性和模型发现不是同一回事。

“Invalid API key”​

确保 OPL 数据空间里填的 API Key 与 ~/.hermes/.env 中的 API_SERVER_KEY 完全一致。

响应较慢​

Hermes Agent 可能在回复前执行了多次工具调用，这是正常现象。

Linux Docker 下 host.docker.internal 不可用​

docker run --add-host=host.docker.internal:host-gateway ...

或者：

docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1 ...

进一步阅读​