Chuyển tới nội dung chính

Mở tích hợp WebUI

Open WebUI (126k★) là giao diện trò chuyện tự lưu trữ phổ biến nhất dành cho AI. Với máy chủ API tích hợp của Hermes Agent, bạn có thể sử dụng Open WebUI làm giao diện người dùng web bóng bẩy cho đại lý của mình — hoàn thiện với tính năng quản lý cuộc trò chuyện, tài khoản người dùng và giao diện trò chuyện hiện đại.

Kiến trúc

Open WebUI kết nối với máy chủ API của Hermes Agent giống như kết nối với OpenAI. Tác nhân của bạn xử lý các yêu cầu bằng bộ công cụ đầy đủ — terminal, thao tác tệp, tìm kiếm trên web, bộ nhớ, kỹ năng — và trả về phản hồi cuối cùng.

Mở WebUI giao tiếp với máy chủ Hermes đến máy chủ nên bạn không cần API_SERVER_CORS_ORIGINS cho việc tích hợp này.

Thiết lập nhanh

1. Kích hoạt máy chủ API​

Thêm vào ~/.hermes/.env :

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key

2. Khởi động cổng Hermes Agent​

hermes gateway

Bạn nên xem:

[API Server] API server listening on http://127.0.0.1:8642

3. Bắt đầu mở WebUI​

docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
  -e OPENAI_API_KEY=your-secret-key \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

4. Mở giao diện người dùng​

Đi tới http://localhost:3000. Tạo tài khoản quản trị viên của bạn (người dùng đầu tiên trở thành quản trị viên). Bạn sẽ thấy hermes-agent trong danh sách mô hình thả xuống. Bắt đầu trò chuyện!

Thiết lập soạn thảo Docker

Để thiết lập lâu dài hơn, hãy tạo docker-compose.yml :

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:

Sau đó:

docker compose up -d

Định cấu hình qua Giao diện người dùng quản trị

Nếu bạn muốn định cấu hình kết nối thông qua giao diện người dùng thay vì các biến môi trường:

  1. Đăng nhập để mở WebUI tại http://localhost:3000
  2. Nhấp vào hình đại diện hồ sơ của bạn → Cài đặt quản trị
  3. Vào Kết nối
  4. Trong OpenAI API, hãy nhấp vào biểu tượng cờ lê (Quản lý)
  5. Nhấp vào *** Thêm kết nối mới**
  6. Nhập:
    • URL: http://host.docker.internal:8642/v1
    • Khóa API: khóa của bạn hoặc bất kỳ giá trị nào không trống (ví dụ: not-needed )
  7. Nhấp vào dấu kiểm để xác minh kết nối
  8. Lưu

Mô hình hermes-agent bây giờ sẽ xuất hiện trong danh sách mô hình thả xuống.

cảnh báo

Các biến môi trường chỉ có hiệu lực trong lần khởi chạy đầu tiên của Open WebUI. Sau đó, cài đặt kết nối được lưu trữ trong cơ sở dữ liệu nội bộ của nó. Để thay đổi chúng sau này, hãy sử dụng Giao diện người dùng quản trị viên hoặc xóa ổ đĩa Docker và bắt đầu làm mới.

Loại API: Hoàn thành trò chuyện và Phản hồi

Open WebUI hỗ trợ hai chế độ API khi kết nối với chương trình phụ trợ:

Chế độĐịnh dạngKhi nào nên sử dụng
Hoàn thành cuộc trò chuyện (mặc định)/v1/chat/completionsKhuyến khích. Hoạt động tốt.
Phản hồi (thử nghiệm)/v1/responsesĐối với trạng thái hội thoại phía máy chủ thông qua previous_response_id .

Sử dụng tính năng hoàn thành cuộc trò chuyện (được khuyến nghị)​

Đây là mặc định và không yêu cầu cấu hình bổ sung. Open WebUI gửi các yêu cầu định dạng OpenAI tiêu chuẩn và Hermes Agent sẽ phản hồi tương ứng. Mỗi yêu cầu bao gồm toàn bộ lịch sử hội thoại.

Sử dụng API phản hồi​

Để sử dụng chế độ API phản hồi:

  1. Đi tới Cài đặt quản trị → Kết nối → OpenAI → Quản lý
  2. Chỉnh sửa kết nối Hermes-agent của bạn
  3. Thay đổi Loại API từ "Hoàn thành trò chuyện" thành "Phản hồi (Thử nghiệm)"
  4. LưuVới API phản hồi, Open WebUI gửi yêu cầu ở định dạng Phản hồi ( mảng input + instructions ) và Hermes Agent có thể lưu giữ toàn bộ lịch sử cuộc gọi công cụ qua các lượt thông qua previous_response_id .
ghi chú

Open WebUI hiện quản lý lịch sử hội thoại phía máy khách ngay cả trong chế độ Phản hồi — nó gửi toàn bộ lịch sử tin nhắn trong mỗi yêu cầu thay vì sử dụng previous_response_id . Chế độ API phản hồi chủ yếu hữu ích cho khả năng tương thích trong tương lai khi giao diện người dùng phát triển.

Nó hoạt động như thế nào

Khi bạn gửi tin nhắn trong Open WebUI:

  1. WebUI mở sẽ gửi yêu cầu POST /v1/chat/completions kèm theo lịch sử tin nhắn và cuộc trò chuyện của bạn
  2. Hermes Agent tạo một phiên bản AIAgent với bộ công cụ đầy đủ
  3. Tác nhân xử lý yêu cầu của bạn — nó có thể gọi các công cụ (terminal, thao tác tệp, tìm kiếm trên web, v.v.)
  4. Khi các công cụ thực thi, thông báo tiến trình nội tuyến sẽ truyền tới giao diện người dùng để bạn có thể biết tác nhân đang làm gì (ví dụ: 💻 ls -la , 🔍 Bản phát hành Python 3.12 )
  5. The agent's final text response streams back to Open WebUI
  6. Open WebUI displays the response in its chat interface

Your agent has access to all the same tools and capabilities as when using the CLI or Telegram — the only difference is the frontend.

Tool Progress

With streaming enabled (the default), you'll see brief inline indicators as tools run — the tool emoji and its key argument. These appear in the response stream before the agent's final answer, giving you visibility into what's happening behind the scenes.

Configuration Reference

Hermes Agent (API server)​

VariableDefaultDescription
API_SERVER_ENABLEDfalseEnable the API server
API_SERVER_PORT8642HTTP server port
API_SERVER_HOST127.0.0.1Bind address
API_SERVER_KEY(required)Bearer token for auth. Match OPENAI_API_KEY.

Open WebUI​

VariableDescription
OPENAI_API_BASE_URLHermes Agent's API URL (include /v1)
OPENAI_API_KEYMust be non-empty. Match your API_SERVER_KEY.

Troubleshooting

No models appear in the dropdown​

  • Check the URL has /v1 suffix: http://host.docker.internal:8642/v1 (not just :8642)
  • Verify the gateway is running: cuộn tròn http://localhost:8642/health should return {"status": "ok"}
  • Check model listing: cuộn tròn http://localhost:8642/v1/models should return a list with hermes-agent
  • Docker networking: From inside Docker, localhost means the container, not your host. Use Host.docker.internal or --network=host.

Connection test passes but no models load​

This is almost always the missing /v1 suffix. Open WebUI's connection test is a basic connectivity check — it doesn't verify model listing works.

Response takes a long time​

Hermes Agent may be executing multiple tool calls (reading files, running commands, searching the web) before producing its final response. This is normal for complex queries. The response appears all at once when the agent finishes.

"Invalid API key" errors​

Make sure your OPENAI_API_KEY in Open WebUI matches the API_SERVER_KEY in Hermes Agent.

Linux Docker (no Docker Desktop)

On Linux without Docker Desktop, Host.docker.internal không giải quyết được bằng mặc định. Tùy chọn:

# Option 1: Add host mapping
docker run --add-host=host.docker.internal:host-gateway ...

# Option 2: Use host networking
docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1 ...

# Option 3: Use Docker bridge IP
docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1 ...