# Open WebUI 和 Hermes 打通历史记录整理

整理时间：2026-07-22

本文整理本机 Hermes 历史会话中关于 Open WebUI 与 Hermes API Server 打通的记录、相关配置文件、长期保存位置和后续维护命令。

---

## 1. 原始历史消息还在不在？

还在。

Hermes 当前 default profile 的原始会话历史保存在 SQLite 数据库：

```bash
/home/xingpeng/.hermes/state.db
```

这是 Hermes 的 canonical session store，历史消息不是单独 markdown 文件，而是在这个 SQLite 里。

可用命令：

```bash
hermes sessions browse
hermes sessions export /tmp/hermes_sessions.jsonl
```

相关历史 session 包括：

| Session ID | 标题/主题 | 说明 |
|---|---|---|
| `20260713_134521_301d6b` | 打通 OpenWebUI 和 Hermes | root@www.xingpeng.online 上 Open WebUI 接 Hermes |
| `20260713_174653_6f0901` | Docker内Hermes配置 | 10.10.10.6 的 doc_hermers 容器内 Open WebUI 接 Hermes |
| `20260713_143849_b29822` | 查询 Hermes API key | 本机/远程 Open WebUI 使用 Hermes API 的讨论 |
| `20260713_154304_88045b` | OpenWebUI公网访问方案 | Open WebUI 公网访问、反代、隧道方案 |

---

## 2. 长期整理记录保存在哪些文件？

主要整理在这个 skill 中：

```bash
/home/xingpeng/.hermes/skills/software-development/openai-compatible-frontend-integration/
```

主文件：

```bash
/home/xingpeng/.hermes/skills/software-development/openai-compatible-frontend-integration/SKILL.md
```

参考文档：

```bash
/home/xingpeng/.hermes/skills/software-development/openai-compatible-frontend-integration/references/hermes-openwebui-wsl.md
/home/xingpeng/.hermes/skills/software-development/openai-compatible-frontend-integration/references/hermes-openwebui-remote-systemd.md
/home/xingpeng/.hermes/skills/software-development/openai-compatible-frontend-integration/references/hermes-openwebui-docker-bridge.md
```

用途对应关系：

| 文件 | 场景 |
|---|---|
| `hermes-openwebui-wsl.md` | 本机 WSL 内 Open WebUI 连接本机 Hermes API Server |
| `hermes-openwebui-remote-systemd.md` | 远程 Linux 主机 systemd 方式运行 Hermes Gateway + Open WebUI |
| `hermes-openwebui-docker-bridge.md` | Docker bridge 容器内运行 Hermes + Open WebUI |

---

## 3. 本机 WSL Open WebUI + Hermes 配置记录

### 3.1 已知可用形态

Hermes API Server：

```text
API_SERVER_ENABLED=true
API_SERVER_HOST=127.0.0.1
API_SERVER_PORT=8642
API_SERVER_MODEL_NAME=Hermes Agent
API_SERVER_KEY=<strong local token>
```

Open WebUI server-side connection：

```text
OPENAI_API_BASE_URL=http://127.0.0.1:8642/v1
OPENAI_API_KEY=<same token>
OPENAI_API_BASE_URLS=http://127.0.0.1:8642/v1
OPENAI_API_KEYS=<same token>
ENABLE_OLLAMA_API=false
```

离线/弱网启动建议：

```text
ENABLE_BASE_MODELS_CACHE=false
RAG_EMBEDDING_MODEL=
RAG_EMBEDDING_MODEL_AUTO_UPDATE=false
ENABLE_PIP_INSTALL_FRONTMATTER_REQUIREMENTS=false
OFFLINE_MODE=true
```

### 3.2 本机 Open WebUI env 文件

找到的本机环境变量文件：

```bash
/home/xingpeng/openwebui-hermes.env
```

内容摘要：

```bash
OPENAI_API_BASE_URL=http://127.0.0.1:8642/v1
OPENAI_API_BASE_URLS=http://127.0.0.1:8642/v1
ENABLE_OLLAMA_API=false
ENABLE_BASE_MODELS_CACHE=false
RAG_EMBEDDING_MODEL=
RAG_EMBEDDING_MODEL_AUTO_UPDATE=false
ENABLE_PIP_INSTALL_FRONTMATTER_REQUIREMENTS=false
OFFLINE_MODE=true
```

API key 文件：

```bash
/home/xingpeng/.hermes/openwebui_api_key
```

### 3.3 本机 Open WebUI 数据目录

Open WebUI 本机数据目录：

```bash
/home/xingpeng/miniforge3/envs/openwebui/lib/python3.11/site-packages/open_webui/data
```

SQLite DB：

```bash
/home/xingpeng/miniforge3/envs/openwebui/lib/python3.11/site-packages/open_webui/data/webui.db
```

uploads 目录：

```bash
/home/xingpeng/miniforge3/envs/openwebui/lib/python3.11/site-packages/open_webui/data/uploads
```

Open WebUI DB 里常见配置 key：

```text
openai.enable=true
openai.api_base_urls=["http://127.0.0.1:8642/v1"]
openai.api_keys=["<token>"]
openai.api_configs={}
ollama.enable=false
rag.embedding_model=""
rag.embedding_engine=""
rag.bypass_embedding_and_retrieval=true
models.base_models_cache=false
tool_server.connections=[]
```

### 3.4 本机验证命令

```bash
KEY=$(cat ~/.hermes/openwebui_api_key)

curl -sS http://127.0.0.1:8642/health

curl -sS \
  -H "Authorization: Bearer $KEY" \
  http://127.0.0.1:8642/v1/models

curl -sS \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  http://127.0.0.1:8642/v1/chat/completions \
  -d '{"model":"Hermes Agent","messages":[{"role":"user","content":"只回复 OK"}],"stream":false}'

curl -I http://127.0.0.1:8080/
```

Windows 侧访问 WSL：

```cmd
curl.exe -I --max-time 5 http://127.0.0.1:8080/
curl.exe -sS --max-time 5 http://127.0.0.1:8642/health
```

---

## 4. 远程 systemd 主机记录：root@www.xingpeng.online

历史里完成过：

- SSH 登录 `root@www.xingpeng.online`
- Hermes Gateway/API Server 作为 systemd 服务运行
- Open WebUI 作为 systemd 服务运行
- Open WebUI 接入 Hermes API Server

### 4.1 Hermes API Server 配置

远程配置文件：

```bash
/root/.hermes/.env
```

配置形态：

```text
API_SERVER_ENABLED=true
API_SERVER_HOST=127.0.0.1
API_SERVER_PORT=8642
API_SERVER_MODEL_NAME=Hermes Agent
API_SERVER_KEY=<strong token>
```

API token 文件：

```bash
/root/.hermes/openwebui_api_key
```

### 4.2 Open WebUI 连接 Hermes

Open WebUI 指向同机 Hermes：

```text
OPENAI_API_BASE_URL=http://127.0.0.1:8642/v1
OPENAI_API_KEY=<same token>
OPENAI_API_BASE_URLS=http://127.0.0.1:8642/v1
OPENAI_API_KEYS=<same token>
ENABLE_OLLAMA_API=false
```

### 4.3 systemd 服务模式

Hermes Gateway：

```bash
hermes gateway install --system --run-as-user root --start-now --force
systemctl status hermes-gateway.service
```

Open WebUI systemd 服务大致形态：

```ini
[Unit]
Description=Open WebUI
After=network-online.target hermes-gateway.service
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/xingpeng
Environment=PATH=/root/miniforge3/envs/openwebui/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
Environment=PORT=8080
Environment=OPENAI_API_BASE_URL=http://127.0.0.1:8642/v1
Environment=OPENAI_API_KEY=<same token>
Environment=OPENAI_API_BASE_URLS=http://127.0.0.1:8642/v1
Environment=OPENAI_API_KEYS=<same token>
Environment=ENABLE_OLLAMA_API=false
Environment=ENABLE_BASE_MODELS_CACHE=false
Environment=RAG_EMBEDDING_MODEL=
Environment=RAG_EMBEDDING_MODEL_AUTO_UPDATE=false
Environment=ENABLE_PIP_INSTALL_FRONTMATTER_REQUIREMENTS=false
Environment=OFFLINE_MODE=true
ExecStart=/root/miniforge3/envs/openwebui/bin/open-webui serve
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

启动/重启：

```bash
systemctl daemon-reload
systemctl enable openwebui.service
systemctl restart openwebui.service
```

### 4.4 远程验证命令

```bash
KEY=$(cat /root/.hermes/openwebui_api_key)

curl -sS http://127.0.0.1:8642/health
curl -sS -H "Authorization: Bearer $KEY" http://127.0.0.1:8642/v1/models
curl -sS \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  http://127.0.0.1:8642/v1/chat/completions \
  -d '{"model":"Hermes Agent","messages":[{"role":"user","content":"只回复 OK"}],"stream":false}'

curl -I http://127.0.0.1:8080/
systemctl is-active hermes-gateway.service openwebui.service
ss -ltnp | grep -E ':(8642|8080)'
```

预期：

```text
Hermes API: 127.0.0.1:8642
Open WebUI: 0.0.0.0:8080
/v1/models includes "Hermes Agent"
chat smoke test returns OK
```

### 4.5 当时浏览器访问地址

```text
http://www.xingpeng.online:8080
```

---

## 5. Docker 容器记录：10.10.10.6 / doc_hermers

历史里完成过：

- SSH 到 `xingpeng@10.10.10.6`
- 进入 Docker 容器 `doc_hermers`
- 容器内打通 Hermes API Server 和 Open WebUI
- 同步本地 skills 到容器内 Hermes
- 设置 PDF watcher 和 Open WebUI uploads importer

### 5.1 已知可用形态

容器内部：

```text
Hermes API Server: 127.0.0.1:8642
Open WebUI:        0.0.0.0:8080
Open WebUI base:   http://127.0.0.1:8642/v1
Model name:        Hermes Agent
```

Open WebUI SQLite config 已写入：

```text
openai.enable = true
openai.api_base_urls = ["http://127.0.0.1:8642/v1"]
openai.api_keys = <same token>
ollama.enable = false
rag.embedding_model = ""
```

### 5.2 容器内重启脚本

保留的一键重启脚本：

```bash
/home/xingpeng/restart_doc_services.sh
```

它会拉起：

- Hermes Gateway/API Server
- Open WebUI
- PDF watcher
- OpenWebUI PDF importer

执行方式：

```bash
docker exec -d doc_hermers /bin/bash -lc "/home/xingpeng/restart_doc_services.sh > /home/xingpeng/logs/restart_doc_services.log 2>&1"
```

### 5.3 Docker 非 systemd 场景启动建议

无 systemd 的长期容器中，不建议从交互 shell 里用普通后台任务启动服务。推荐从 Docker host 使用：

```bash
docker exec -d <container> ...
```

Hermes Gateway 示例形态：

```bash
docker exec -d <container> /bin/bash -lc '
  export PATH=/home/xingpeng/.local/bin:/usr/local/bin:/usr/bin:/bin
  export HOME=/home/xingpeng
  env API_SERVER_ENABLED=true \
      API_SERVER_HOST=127.0.0.1 \
      API_SERVER_PORT=8642 \
      API_SERVER_MODEL_NAME="Hermes Agent" \
      API_SERVER_KEY="$KEY" \
      hermes gateway run > /home/xingpeng/logs/hermes-gateway.log 2>&1
'
```

Open WebUI 示例形态：

```bash
docker exec -d <container> /bin/bash -lc '
  export PATH=/home/xingpeng/miniforge3/envs/pyopenwebui/bin:/usr/local/bin:/usr/bin:/bin
  export HOME=/home/xingpeng
  env PORT=8080 HOST=0.0.0.0 \
      OPENAI_API_BASE_URL=http://127.0.0.1:8642/v1 \
      OPENAI_API_KEY="$KEY" \
      OPENAI_API_BASE_URLS=http://127.0.0.1:8642/v1 \
      OPENAI_API_KEYS="$KEY" \
      ENABLE_OLLAMA_API=false \
      ENABLE_BASE_MODELS_CACHE=false \
      RAG_EMBEDDING_MODEL= \
      RAG_EMBEDDING_MODEL_AUTO_UPDATE=false \
      ENABLE_PIP_INSTALL_FRONTMATTER_REQUIREMENTS=false \
      OFFLINE_MODE=true \
      open-webui serve > /home/xingpeng/logs/open-webui.log 2>&1
'
```

### 5.4 容器内验证命令

```bash
docker exec doc_hermers ss -ltnp | grep -E ':(8080|8642)'
docker exec doc_hermers curl -sS http://127.0.0.1:8642/health
docker exec doc_hermers curl -sS -H "Authorization: Bearer $KEY" http://127.0.0.1:8642/v1/models

docker exec doc_hermers curl -sS \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  http://127.0.0.1:8642/v1/chat/completions \
  -d '{"model":"Hermes Agent","messages":[{"role":"user","content":"只回复 OK"}],"stream":false}'

docker exec doc_hermers curl -I --max-time 5 http://127.0.0.1:8080/
```

历史验证结果：

```text
Hermes health OK
/v1/models 返回 Hermes Agent
/v1/chat/completions 返回 OK
Open WebUI HTTP 200 OK
```

### 5.5 Docker 端口暴露注意事项

当时记录：容器启动时没有发布端口。

现象：

```text
Docker inspect Ports = {}
```

所以：

```text
http://10.10.10.6:8080
```

不一定可访问，除非 Docker host 做了 `-p 8080:8080` 或反向代理/端口转发。

Docker host 可能能通过容器 bridge IP 访问：

```bash
IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' doc_hermers)
curl -I http://$IP:8080/
```

但 LAN 客户端通常不能直接访问 Docker bridge IP。

解决方式：

1. 重建容器时加：

```bash
-p 8080:8080
```

2. 或在 Docker host 上加反向代理/端口转发。

### 5.6 Docker 内 skills 路径

容器内安装位置：

```bash
/home/xingpeng/.hermes/skills/xingpeng_pdf2md
/home/xingpeng/.hermes/skills/xingpeng_compare/xingpeng_compare
/home/xingpeng/.hermes/skills/xingpeng_getq_pdf/xingpeng_getq_pdf
```

容器内文档路径：

```bash
/home/xingpeng/workspace/pdf
/home/xingpeng/workspace/md
/home/xingpeng/workspace/out
```

记忆中还记录：

```text
/home/xingpeng/workspace in container is backed by host /home/xingpeng/doc
```

---

## 6. Open WebUI 上传 PDF 自动导入记录

这部分记录在：

```bash
/home/xingpeng/.hermes/skills/xingpeng_pdf2md/SKILL.md
```

相关脚本：

```bash
/home/xingpeng/.hermes/skills/xingpeng_pdf2md/scripts/import_openwebui_uploads.py
/home/xingpeng/.hermes/skills/xingpeng_pdf2md/scripts/ensure_openwebui_importer.sh
/home/xingpeng/.hermes/skills/xingpeng_pdf2md/scripts/ensure_watcher.sh
```

### 6.1 本机 PDF 工作目录

PDF 输入：

```bash
/mnt/c/Users/xingpeng/Desktop/doc/pdf
```

Markdown 输出：

```bash
/mnt/c/Users/xingpeng/Desktop/doc/md
```

报告输出：

```bash
/mnt/c/Users/xingpeng/Desktop/doc/out
```

Windows 对应路径：

```text
C:\Users\xingpeng\Desktop\doc\pdf
C:\Users\xingpeng\Desktop\doc\md
C:\Users\xingpeng\Desktop\doc\out
```

### 6.2 Open WebUI 上传的特殊点

Open WebUI UI 上传 PDF 时，默认走 Open WebUI 自己的 RAG 上传流程：

```text
Open WebUI data/uploads + webui.db
```

它通常不会把原始 PDF 作为 base64 file part 转发给 Hermes，所以不会自动进入 Hermes document cache，也不会自动触发 `[The user sent a document...]` 这类附件模板。

解决方式是运行 importer：

```bash
/usr/bin/bash /home/xingpeng/.hermes/skills/xingpeng_pdf2md/scripts/ensure_openwebui_importer.sh
```

它会读取：

```bash
/home/xingpeng/miniforge3/envs/openwebui/lib/python3.11/site-packages/open_webui/data/webui.db
/home/xingpeng/miniforge3/envs/openwebui/lib/python3.11/site-packages/open_webui/data/uploads
```

把新 PDF 复制到：

```bash
/mnt/c/Users/xingpeng/Desktop/doc/pdf
```

然后 watcher 转成 Markdown。

### 6.3 本机启动 PDF watcher/importer

```bash
/usr/bin/bash /home/xingpeng/.hermes/skills/xingpeng_pdf2md/scripts/ensure_watcher.sh
/usr/bin/bash /home/xingpeng/.hermes/skills/xingpeng_pdf2md/scripts/ensure_openwebui_importer.sh
```

---

## 7. xingpeng_compare 在 Open WebUI 里使用工具的注意事项

记录文件：

```bash
/home/xingpeng/.hermes/skills/xingpeng_compare/xingpeng_compare/references/openwebui-api-server-tools.md
```

问题现象：Open WebUI 调 Hermes API Server 时，比较模块可能需要本地文件/工具访问。如果 approvals 阻塞工具调用，回答可能出现：

```text
当前 execute_code 被环境拦截为“需要一次性命令审批”...
```

本机私有 WSL/Open WebUI 场景的处理方式：

```bash
hermes config set approvals.mode off
```

然后从外部 shell 重启 gateway：

```bash
hermes gateway restart
# 或
systemctl --user restart hermes-gateway
```

恢复手动审批：

```bash
hermes config set approvals.mode manual
```

---

## 8. 常见坑总结

1. **Open WebUI 的 localhost 是 server-side 视角**

   如果 Open WebUI 在远程服务器或 Docker 容器里：

   ```text
   http://127.0.0.1:8642/v1
   ```

   指的是 Open WebUI 所在环境自己的 localhost，不是你的 Windows/WSL 本机。

2. **Base URL 要带 `/v1`**

   正确：

   ```text
   http://127.0.0.1:8642/v1
   ```

3. **Open WebUI env 和 DB 都可能要改**

   只改环境变量不一定生效，因为 Open WebUI 会把连接设置持久化到 SQLite config 表。

4. **Hermes API key 不能太弱**

   新版 Hermes API Server 会拒绝 placeholder 或太短的 key。

   生成强 key：

   ```bash
   openssl rand -hex 32
   ```

5. **Open WebUI 首页 200 不代表 Hermes 后端连接成功**

   需要同时验证：

   ```bash
   /health
   /v1/models
   /v1/chat/completions
   ```

6. **Docker 未发布端口时，宿主机/LAN 访问不到容器 8080**

   容器内 `0.0.0.0:8080` 不等于宿主机 `10.10.10.6:8080` 已开放。

7. **Docker 容器内重启 Hermes Gateway 时要 kill 所有 `hermes gateway` 子命令**

   不只 kill `hermes gateway run`，因为残留的 `hermes gateway restart` 也可能占用端口。

8. **Open WebUI PDF 上传不会天然进入 Hermes 文档缓存**

   需要 `import_openwebui_uploads.py` 读取 Open WebUI 的 uploads 和 webui.db。

---

## 9. 快速路径索引

### Hermes 历史消息

```bash
/home/xingpeng/.hermes/state.db
```

### Open WebUI/Hermes 集成 skill

```bash
/home/xingpeng/.hermes/skills/software-development/openai-compatible-frontend-integration/SKILL.md
```

### WSL 记录

```bash
/home/xingpeng/.hermes/skills/software-development/openai-compatible-frontend-integration/references/hermes-openwebui-wsl.md
```

### 远程 systemd 记录

```bash
/home/xingpeng/.hermes/skills/software-development/openai-compatible-frontend-integration/references/hermes-openwebui-remote-systemd.md
```

### Docker bridge 记录

```bash
/home/xingpeng/.hermes/skills/software-development/openai-compatible-frontend-integration/references/hermes-openwebui-docker-bridge.md
```

### 本机 Open WebUI env

```bash
/home/xingpeng/openwebui-hermes.env
```

### 本机 API key 文件

```bash
/home/xingpeng/.hermes/openwebui_api_key
```

### 本机 Open WebUI DB

```bash
/home/xingpeng/miniforge3/envs/openwebui/lib/python3.11/site-packages/open_webui/data/webui.db
```

### 本机 Open WebUI uploads

```bash
/home/xingpeng/miniforge3/envs/openwebui/lib/python3.11/site-packages/open_webui/data/uploads
```

### PDF importer/watcher

```bash
/home/xingpeng/.hermes/skills/xingpeng_pdf2md/scripts/import_openwebui_uploads.py
/home/xingpeng/.hermes/skills/xingpeng_pdf2md/scripts/ensure_openwebui_importer.sh
/home/xingpeng/.hermes/skills/xingpeng_pdf2md/scripts/ensure_watcher.sh
```

### xingpeng_compare Open WebUI 工具调用说明

```bash
/home/xingpeng/.hermes/skills/xingpeng_compare/xingpeng_compare/references/openwebui-api-server-tools.md
```