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

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

• Không trỏ nhầm sang KB :8766 — đó là zalo-bot-chat.
• Dùng token Zalo Bot riêng nếu chạy song song với bot KB.
• 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.
• Không commit .env.
• Webhook platform Hermes (hermes webhook …) vẫn dùng được cho GitHub/CI → Telegram/Discord; bridge này là đường Zalo ↔ agent riêng.