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 Đại lý Hermes, 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

`mermaid flowchart LR A["Open WebUI
browser UI
port 3000"] B["Hermes-agent
gateway API server
port 8642"] A -->|POST /v1/chat/completions| B B -->|SSE streaming response| A

` ``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. Hermes 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.

Runtime location

Máy chủ API là thời gian chạy tác nhân Hermes, không phải proxy LLM thuần túy. Đối với mỗi yêu cầu, Hermes tạo AIAgent phía máy chủ trên máy chủ máy chủ API. Cuộc gọi công cụ chạy ở nơi máy chủ API đó đang chạy.

Ví dụ: nếu máy tính xách tay trỏ Open WebUI hoặc một ứng dụng khách tương thích OpenAI khác tại máy chủ API Hermes trên máy từ xa, `pwd

, công cụ tệp, công cụ trình duyệt, công cụ MCP cục bộ và các công cụ không gian làm việc khác chạy trên máy chủ máy chủ API từ xa chứ không phải trên máy tính xách tay.

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

Thiết lập nhanh

Khởi động cục bộ một lệnh (macOS/Linux, không có Docker)

Nếu bạn muốn Hermes + Open WebUI được kết nối cục bộ với trình khởi chạy có thể tái sử dụng, hãy chạy:

cd ~/.Hermes/Hermes-agent
bash scripts/setup_open_webui.sh

`
``Kịch bản làm gì:
- đảm bảo 

~/.Hermes/.env
` chứa 
`API_SERVER_ENABLED

, 
`API_SERVER_HOST

, 
`API_SERVER_KEY

, 
`API_SERVER_PORT
` và 
`API_SERVER_MODEL_NAME

`
- khởi động lại cổng Hermes để máy chủ API xuất hiện
- cài đặt Open WebUI vào 

~/.local/open-webui-venv

- viết trình khởi chạy tại 

~/.local/bin/start-open-webui-Hermes.sh

- trên macOS, cài đặt dịch vụ người dùng 
`launchd

; trên Linux với 
`systemd --user

, cài đặt dịch vụ người dùng ở đó

Mặc định:
- API Hermes: 
`http://127.0.0.1:8642/v1

- Mở WebUI: 
`http://127.0.0.1:8080

- tên model được quảng cáo cho Open WebUI: 
`Hermes Agent
``Ghi đè hữu ích:

``` bash
OPEN_WEBUI_NAME='My Hermes UI' \
OPEN_WEBUI_ENABLE_SIGNUP=true \
Hermes_API_MODEL_NAME='My Hermes Agent' \
bash scripts/setup_open_webui.sh

`
``Trên Linux, thiết lập dịch vụ nền tự động yêu cầu phiên 
`systemd --user
` hoạt động. Nếu bạn đang sử dụng hộp SSH không đầu và muốn bỏ qua cài đặt dịch vụ, hãy chạy:

`bash
OPEN_WEBUI_ENABLE_SERVICE=false bash scripts/setup_open_webui.sh

`

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

`bash
Hermes config set API_SERVER_ENABLED true
Hermes config set API_SERVER_KEY your-secret-key

`
```Hermes config set
` tự động định tuyến cờ tới 
`config.yaml
` và bí mật tới 

~/.Hermes/.env

. Nếu cổng đang chạy, hãy khởi động lại nó để thay đổi có hiệu lực:

`bash
Hermes gateway stop && Hermes gateway

`

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

`bash
Hermes gateway

`
``Bạn nên xem:

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

`

### 3. Xác minh máy chủ API có thể truy cập được

`bash
curl -s http://127.0.0.1:8642/health

# \{"status": "ok", ...}

curl -s -H "Authorization: Bearer your-secret-key" http://127.0.0.1:8642/v1/models
# \{"object":"list","data":[\{"id":"Hermes-agent", ...}]}

`
``Nếu 

/health
` không thành công thì cổng không nhận được 
`API_SERVER_ENABLED=true
` — hãy khởi động lại nó. Nếu 

/v1/models
` trả về 
`401

, tiêu đề 
`Authorization
` của bạn không khớp với 
`API_SERVER_KEY

.

### 4. Bắt đầu Mở WebUI

``` bash
Docker run -d -p 3000:8080 \

  -e OpenAI_API_BASE_URL=http://host.Docker.internal:8642/v1 \
  -e OpenAI_API_KEY=your-secret-key \
  -e ENABLE_OLlama_API=false \
  --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

`
```ENABLE_OLlama_API=false
` chặn phần phụ trợ mặc định của OLlama, nếu không sẽ hiển thị trống và làm lộn xộn bộ chọn mô hình. Hãy bỏ qua nó nếu bạn thực sự có OLlama chạy cùng.

Lần khởi chạy đầu tiên mất 15–30 giây: WebUI mở tải xuống các mô hình nhúng biến đổi câu (~150MB) trong lần khởi động đầu tiên. Đợi 
`Docker logs open-webui
` ổn định trước khi mở UI.

### 5. 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 nhân viên hỗ trợ của mình trong danh sách mô hình thả xuống (được đặt tên theo hồ sơ của bạn hoặc **Hermes-agent** cho hồ sơ mặc định). 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

:

``` yaml
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
      - ENABLE_OLlama_API=false
    extra_hosts:
      - "host.Docker.internal:host-gateway"
    restart: always`volumes:
  open-webui:

`
``Sau đó:

``` bash
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**: có cùng giá trị với 
`API_SERVER_KEY
` trong Hermes
7. Nhấp vào **dấu kiểm** để xác minh kết nối
8. **Lưu**

Mô hình nhân viên hỗ trợ của bạn bây giờ sẽ xuất hiện trong danh sách mô hình thả xuống (được đặt tên theo hồ sơ của bạn hoặc **Hermes-agent** cho hồ sơ mặc định).:::warning
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ạng | Khi nào nên sử dụng |
|------|--------|-------------|
| **Hoàn thành cuộc trò chuyện** (mặc định) |

/v1/chat/completions
` | Khuyế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à Đại lý Hermes 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ưu

Vớ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à Đại lý Hermes 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

. Khi 
`stream: true

, Hermes cũng truyền phát các mục 
`function_call
` và 
`function_call_output
` đặc biệt, cho phép giao diện người dùng lệnh gọi công cụ có cấu trúc tùy chỉnh trong các máy khách hiển thị các sự kiện Phản hồi.

:::note
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

. Ưu điểm chính của chế độ Phản hồi ngày nay là luồng sự kiện có cấu trúc: các mục delta văn bản, 
`function_call
` và 
`function_call_output
` xuất hiện dưới dạng các sự kiện SSE Phản hồi OpenAI thay vì các khối Hoàn thành trò chuyệ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. Đại lý Hermes tạo phiên bản 
`AIAgent
` phía máy chủ bằng cách sử dụng hồ sơ, cấu hình mô hình/nhà cung cấp, bộ nhớ, kỹ năng và bộ công cụ máy chủ API được định cấu hình của máy chủ API
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.) trên máy chủ máy chủ API
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 đến 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
` 

`
, 

` 

🔍 Python 3.12 Release
` 

`
)
5. Phản hồi văn bản cuối cùng của tổng đài viên sẽ quay trở lại Open WebUI
6. Open WebUI hiển thị phản hồi trong giao diện trò chuyện của nó

Nhân viên hỗ trợ của bạn có quyền truy cập vào các công cụ và khả năng tương tự như phiên bản Hermes máy chủ API đó. Nếu máy chủ API ở xa thì các công cụ đó cũng ở xa.

Nếu bạn cần các công cụ để chạy trên không gian làm việc **cục bộ** của mình ngay hôm nay, hãy chạy Hermes cục bộ và trỏ nó đến một nhà cung cấp LLM thuần túy hoặc proxy mô hình thuần túy tương thích với OpenAI (ví dụ: vLLM, LiteLLM, OLlama, Llama.cpp, OpenAI, OpenRouter, v.v.). Chế độ thời gian chạy phân chia trong tương lai dành cho "bộ não từ xa, bàn tay cục bộ" đang được theo dõi trong [#18715](https://GitHub.com/NousResearch/Hermes-agent/issues/18715); đó không phải là hành vi của máy chủ API hiện tại.

:::tip[Tool Progress]
Khi bật tính năng phát trực tuyến (mặc định), bạn sẽ thấy các chỉ báo nội tuyến ngắn gọn khi các công cụ chạy — biểu tượng cảm xúc của công cụ và đối số chính của nó. Những thông tin này xuất hiện trong luồng phản hồi trước câu trả lời cuối cùng của tổng đài viên, giúp bạn hiểu rõ những gì đang diễn ra ở hậu trường.
:::

## Tham khảo cấu hình

### Đại lý Hermes (máy chủ API)

| Biến | Mặc định | Mô tả |
|----------|----------|-------------|
| 
`API_SERVER_ENABLED
` | 
`false
` | Kích hoạt máy chủ API |
| 
`API_SERVER_PORT
` | 
`8642
` | Cổng máy chủ HTTP |
| 
`API_SERVER_HOST
` | 
`127.0.0.1
` | Địa chỉ ràng buộc |
| 
`API_SERVER_KEY
` | _(bắt buộc)_ | Mã thông báo mang cho auth. Phù hợp với 
`OpenAI_API_KEY

. |

### Mở WebUI

| Biến | Mô tả |
|----------|-------------|
| 
`OpenAI_API_BASE_URL
` | URL API của Đại lý Hermes (bao gồm 

/v1

) |
| 
`OpenAI_API_KEY
` | Phải không trống. Phù hợp với 
`API_SERVER_KEY
` của bạn. |

## Khắc phục sự cố

### Không có mô hình nào xuất hiện trong danh sách thả xuống- **Kiểm tra URL có hậu tố 

/v1

**: 
`http://host.Docker.internal:8642/v1
` (không chỉ 

:8642

)
- **Xác minh cổng đang chạy**: 
`curl http://localhost:8642/health
` sẽ trả về 

\&#123;"status": "ok"&#125;

- **Kiểm tra danh sách mô hình**: 
`curl -H "Authorization: Bearer your-secret-key" http://localhost:8642/v1/models
` sẽ trả về danh sách có 
`Hermes-agent

- **Mạng Docker**: Từ bên trong Docker, 
`localhost
` có nghĩa là vùng chứa chứ không phải máy chủ của bạn. Sử dụng 
`host.Docker.internal
` hoặc 

--network=host

.
- **Phần phụ trợ OLlama trống đang che khuất bộ chọn**: Nếu bạn bỏ qua 
`ENABLE_OLlama_API=false

, Open WebUI sẽ hiển thị phần OLlama trống phía trên các mẫu Hermes của bạn. Khởi động lại vùng chứa bằng 

-e ENABLE_OLlama_API=false
` hoặc tắt OLlama trong **Cài đặt quản trị viên → Kết nối**.

### Kiểm tra kết nối thành công nhưng không tải mô hình

Đây hầu như luôn là hậu tố 

/v1
` bị thiếu. Kiểm tra kết nối của Open WebUI là kiểm tra kết nối cơ bản — nó không xác minh hoạt động của danh sách mô hình.`###Phản hồi mất nhiều thời gian

Đại lý Hermes có thể đang thực hiện nhiều lệnh gọi công cụ (đọc tệp, chạy lệnh, tìm kiếm trên web) trước khi đưa ra phản hồi cuối cùng. Điều này là bình thường đối với các truy vấn phức tạp. Phản hồi xuất hiện cùng một lúc khi tác nhân kết thúc.

### Lỗi "Khóa API không hợp lệ"

Đảm bảo 
`OpenAI_API_KEY
` của bạn trong Open WebUI khớp với 
`API_SERVER_KEY
` trong Đại lý Hermes.

:::warning
Open WebUI duy trì các cài đặt kết nối tương thích với OpenAI trong cơ sở dữ liệu của chính nó sau lần khởi chạy đầu tiên. Nếu bạn vô tình lưu sai khóa trong Giao diện người dùng quản trị thì chỉ sửa các biến môi trường là chưa đủ — cập nhật hoặc xóa kết nối đã lưu trong **Cài đặt quản trị → Kết nối** hoặc đặt lại thư mục/cơ sở dữ liệu Open WebUI.
:::

## Thiết lập nhiều người dùng với hồ sơ

Để chạy các phiên bản Hermes riêng biệt cho mỗi người dùng — mỗi phiên bản có cấu hình, bộ nhớ và kỹ năng riêng — hãy sử dụng [profiles](/docs/user-guide/profiles). Mỗi cấu hình chạy máy chủ API riêng trên một cổng khác nhau và tự động quảng cáo tên cấu hình làm mô hình trong Open WebUI.

### 1. Tạo hồ sơ và cấu hình máy chủ API``API_SERVER_*
` là các biến env, không phải khóa cấu hình YAML, vì vậy hãy ghi chúng vào 

.env
` của mỗi cấu hình. Chọn các cổng nằm ngoài phạm vi nền tảng mặc định (
`8644
` là bộ điều hợp webhook, 
`8645
` là WeCom-callback, 
`8646
` là msgraph-webhook), ví dụ: 
`8650+

:

``` bash
Hermes profile create alice
cat >> ~/.Hermes/profiles/alice/.env &lt;&lt;EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8650
API_SERVER_KEY=alice-secret
EOF

Hermes profile create bob
cat > ~/.Hermes/profiles/bob/.env &lt;&lt;EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8651
API_SERVER_KEY=bob-secret
EOF

`

### 2. Khởi động từng cổng

`bash
Hermes -p alice gateway &
Hermes -p bob gateway &

`

### 3. Thêm kết nối trong Open WebUI

Trong **Cài đặt quản trị** → **Kết nối** → **OpenAI API** → **Quản lý**, thêm một kết nối cho mỗi hồ sơ:

| Kết nối | URL | Khóa API |
|----------||------|----------|
| Alice |

http://host.Docker.internal:8650/v1
` | 
`alice-secret
` |
| Bob |

http://host.Docker.internal:8651/v1
` | 
`bob-secret
` |

Danh sách mô hình thả xuống sẽ hiển thị 
`alice
` và 
`bob
` dưới dạng các mô hình riêng biệt. Bạn có thể chỉ định mô hình cho người dùng Open WebUI thông qua bảng quản trị, cung cấp cho mỗi người dùng tác nhân Hermes riêng biệt của họ.

:::tip[Custom Model Names]
Tên model mặc định là tên hồ sơ. Để ghi đè nó, hãy đặt 
`API_SERVER_MODEL_NAME
` trong 

.env
` của cấu hình:

`
`bash
Hermes -p alice config set API_SERVER_MODEL_NAME "Alice's Agent"

`

`
:::

## Linux Docker (không có Docker Desktop)

Trên Linux không có Docker Desktop, 
`host.Docker.internal
` không giải quyết theo mặc định. Tùy chọn:

``` bash

# 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 ...

`
`

Kiến trúc​

Thiết lập nhanh​

Khởi động cục bộ một lệnh (macOS/Linux, không có Docker)​

Kiến trúc

Thiết lập nhanh

Khởi động cục bộ một lệnh (macOS/Linux, không có Docker)