153 lines
5.4 KiB
Markdown
153 lines
5.4 KiB
Markdown
# Zalo Hermes Bot
|
|
|
|
Kênh **Zalo Bot ↔ Hermes Agent** (không phải bot KB/wiki `:8766`).
|
|
|
|
Người dùng chat Zalo → bot long-poll (`python-zalo-bot`) → **Hermes API Server** (`:8642`, agent đầy đủ tool/skill/memory) → format plain-text → trả lại Zalo.
|
|
|
|
Đây là hiện thực phương án **B** trong thực tế vận hành: event từ Zalo do bridge giữ `chat_id` và lấy câu trả lời agent rồi `send_message`. Webhook Hermes `:8644` không deliver native sang Zalo, nên bridge dùng **API Server** (cùng gateway Hermes) thay vì phụ thuộc deliver platform.
|
|
|
|
```
|
|
Zalo user
|
|
→ python-zalo-bot (get_update)
|
|
→ POST http://127.0.0.1:8642/v1/chat/completions (model: hermes-agent)
|
|
→ format_for_zalo()
|
|
→ send_message
|
|
```
|
|
|
|
Khác `zalo-bot-chat` (KB support giá/wiki). Có thể chạy song song với token bot khác.
|
|
|
|
## Yêu cầu
|
|
|
|
1. Python ≥ 3.8 (khuyến nghị 3.11)
|
|
2. Token Zalo Bot (`BOT_TOKEN`)
|
|
3. Hermes gateway đang chạy + **API Server bật** trên `:8642`
|
|
|
|
### Bật Hermes API Server (một lần)
|
|
|
|
Docs: [API Server](https://hermes-agent.nousresearch.com/docs/user-guide/features/api-server)
|
|
|
|
```bash
|
|
# Cách nhanh
|
|
bash scripts/enable-hermes-api-server.sh 'your-local-api-key'
|
|
systemctl --user restart hermes-gateway
|
|
|
|
# Hoặc tự thêm vào ~/.hermes/.env:
|
|
# API_SERVER_ENABLED=true
|
|
# API_SERVER_KEY=your-local-api-key
|
|
```
|
|
|
|
Smoke:
|
|
|
|
```bash
|
|
curl -sS http://127.0.0.1:8642/v1/models \
|
|
-H "Authorization: Bearer your-local-api-key"
|
|
```
|
|
|
|
## Cài đặt
|
|
|
|
```bash
|
|
cd ~/workspace/zalo-hermes-bot
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
cp .env.example .env
|
|
# sửa BOT_TOKEN + HERMES_API_KEY (= API_SERVER_KEY)
|
|
chmod 600 .env
|
|
```
|
|
|
|
## Chạy tay
|
|
|
|
```bash
|
|
source .venv/bin/activate
|
|
python bot_app.py
|
|
```
|
|
|
|
Log mẫu:
|
|
|
|
```text
|
|
[hermes] backend=api base=http://127.0.0.1:8642/v1 health={'ok': True, …}
|
|
[zalo] started as …; listening…
|
|
```
|
|
|
|
`Ctrl+C` → `[zalo] stopped (Ctrl+C)`.
|
|
|
|
## Systemd (user) — tự chạy khi boot
|
|
|
|
```bash
|
|
mkdir -p ~/.config/systemd/user
|
|
cp ~/workspace/zalo-hermes-bot/zalo-hermes-bot.service ~/.config/systemd/user/
|
|
systemctl --user daemon-reload
|
|
systemctl --user enable --now zalo-hermes-bot.service
|
|
sudo loginctl enable-linger "$USER" # nếu chưa
|
|
```
|
|
|
|
```bash
|
|
systemctl --user status zalo-hermes-bot.service
|
|
journalctl --user -u zalo-hermes-bot.service -f
|
|
systemctl --user restart zalo-hermes-bot.service
|
|
```
|
|
|
|
## Luồng tin nhắn
|
|
|
|
| Bước | Điều kiện | Hành động |
|
|
|------|-----------|-----------|
|
|
| 1 | `/reset` / `xóa lịch sử` | Xóa history Hermes theo `chat_id` |
|
|
| 2 | Còn lại | Gọi Hermes (nền, không chặn poll) → plain text → Zalo |
|
|
|
|
Mỗi `chat_id` giữ history ngắn (`HERMES_HISTORY_TURNS`). User đang chờ câu trước sẽ nhận thông báo bận thay vì chồng request.
|
|
|
|
## Biến môi trường
|
|
|
|
| Biến | Bắt buộc | Mặc định | Mô tả |
|
|
|------|----------|----------|--------|
|
|
| `BOT_TOKEN` | Có | — | Token Zalo Bot |
|
|
| `HERMES_API_BASE` | Không | `http://127.0.0.1:8642/v1` | OpenAI-compatible base |
|
|
| `HERMES_API_KEY` | Có* | — | = `API_SERVER_KEY` |
|
|
| `HERMES_MODEL` | Không | `hermes-agent` | Model name API Server |
|
|
| `HERMES_TIMEOUT` | Không | `180` | Timeout giây |
|
|
| `HERMES_HISTORY_TURNS` | Không | `12` | Số lượt user/assistant giữ |
|
|
| `HERMES_BACKEND` | Không | `api` | `api` hoặc `cli` (`hermes chat -q`) |
|
|
| `HERMES_WORKERS` | Không | `2` | Số job Hermes song song |
|
|
| `HERMES_SYSTEM_PROMPT` | Không | (xem `.env.example`) | System prompt |
|
|
|
|
\*Bắt buộc khi `HERMES_BACKEND=api`.
|
|
|
|
## Cấu trúc
|
|
|
|
```text
|
|
zalo-hermes-bot/
|
|
├── bot_app.py # long-poll + task nền
|
|
├── hermes_client.py # API Server / CLI client + history
|
|
├── format_zalo.py # plain-text Zalo
|
|
├── scripts/enable-hermes-api-server.sh
|
|
├── zalo-hermes-bot.service
|
|
├── requirements.txt
|
|
├── .env.example
|
|
└── README.md
|
|
```
|
|
|
|
## Lưu ý
|
|
|
|
- Câu trả lời agent có tool có thể lâu → bot đã `typing` + chạy nền; tăng `HERMES_TIMEOUT` nếu cần.
|
|
- Webhook platform Hermes (`hermes webhook …`) vẫn dùng được cho GitHub/CI → Telegram/Discord; bridge này là đường **Zalo ↔ agent** riêng.
|
|
|
|
## Source-Available License
|
|
|
|
Dự án được cung cấp nguyên trạng cho mục đích học tập và sử dụng cá nhân.
|
|
|
|
Copyright (c) 2026 Trần Thanh Tân / [TTAI Solutions Software](https://ttaisolutions.com/).
|
|
All rights reserved.
|
|
|
|
Được phép xem, tải xuống, cài đặt và sử dụng phần mềm này cho mục đích cá nhân, giáo dục và sử dụng nội bộ trong tổ chức.
|
|
|
|
Được phép sửa đổi cho mục đích cá nhân hoặc sử dụng nội bộ.
|
|
|
|
Nếu chưa có sự cho phép trước bằng văn bản của chủ sở hữu bản quyền, bạn không được:
|
|
|
|
1. Bán, bán lại, cấp phép lại hoặc phân phối thương mại phần mềm này hay bất kỳ phần đáng kể nào trong mã nguồn của nó.
|
|
2. Cung cấp phần mềm này, dù đã sửa đổi hay chưa, dưới dạng sản phẩm thương mại, dịch vụ lưu trữ hoặc dịch vụ SaaS trả phí.
|
|
3. Đóng gói phần mềm này cùng phần cứng hoặc sản phẩm khác để bán lại.
|
|
4. Xóa hoặc thay đổi thông báo bản quyền, hoặc nhận mình là tác giả của phần mềm gốc.
|
|
|
|
Mọi yêu cầu cấp phép thương mại vui lòng gửi tới: https://ttaisolutions.com
|