zalo-hermes-bot/README.md

Zalo Hermes Bot

Kênh Zalo Bot ↔ Hermes Agent.

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.

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

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

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

curl -sS http://127.0.0.1:8642/v1/models \
  -H "Authorization: Bearer your-local-api-key"

Cài đặt

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

source .venv/bin/activate
python bot_app.py

Log mẫu:

[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

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

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

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