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

Python ≥ 3.8 (khuyến nghị 3.11)
Token Zalo Bot (BOT_TOKEN)
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.

4.4 KiB Raw Blame History