Wiki cho dev, bot và người vận hành.

Tổng quan

AHV CLI Bot là gói cài đặt bot Telegram cho Codex CLI và Claude Code. Gói public nằm tại:

https://bot.ahvclaw.com/downloads/telegram-cli-bot-setup

Cài đặt nhanh

Linux

bash <(curl -fsSL https://bot.ahvclaw.com/downloads/telegram-cli-bot-setup/install.sh)

Windows PowerShell

irm https://bot.ahvclaw.com/downloads/telegram-cli-bot-setup/install.ps1 | iex

macOS

bash <(curl -fsSL https://bot.ahvclaw.com/downloads/telegram-cli-bot-setup/install-mac.sh)

Nếu cài trên server sản xuất, hãy giữ lại file .env hiện có. Script cập nhật được thiết kế để bảo toàn cấu hình token/model/chat id.

Cập nhật thủ công

Dùng khi muốn chủ động kéo bản mới nhất thay vì chờ timer.

Linux có systemd timer

sudo systemctl start telegram-cli-bot-package-update.service
sudo journalctl -u telegram-cli-bot-package-update.service -n 100 --no-pager

Kiểm tra phiên bản sau update

cat /opt/bot/tg-claude-bot/VERSION
cat /opt/bot/tg-codex-bot/VERSION
systemctl is-active tg-claude-bot tg-codex-bot

Windows/macOS

Chạy lại trình cài đặt tương ứng. Đây là đường cập nhật/sửa lỗi chuẩn cho môi trường không dùng systemd.

Thêm bot token mới

Khi cần làm việc đồng thời, hãy tạo thêm một bot instance riêng thay vì dùng chung một token. Mỗi instance có service, app dir và project dir riêng; updater vẫn cập nhật tất cả service đang active.

Thêm Codex Bot instance

curl -fsSL https://bot.ahvclaw.com/downloads/telegram-cli-bot-setup/add-bot-instance.sh | sudo bash -s -- codex main PASTE_CODEX_BOT_TOKEN 6348110855

Thêm Claude Bot instance

curl -fsSL https://bot.ahvclaw.com/downloads/telegram-cli-bot-setup/add-bot-instance.sh | sudo bash -s -- claude support PASTE_CLAUDE_BOT_TOKEN 6348110855

Kiểm tra

systemctl status tg-codex-bot-main --no-pager
journalctl -u tg-codex-bot-main -n 80 --no-pager

Không dùng cùng một Telegram bot token cho hai service. Nếu muốn hai session song song, hãy tạo hai bot token khác nhau trong BotFather.

Login Codex và Claude CLI

Bot Telegram chỉ là lớp điều khiển. Codex CLI và Claude Code CLI vẫn cần đăng nhập trên server bằng đúng Linux user chạy service. Mỗi CLI login một lần, token/session sẽ nằm trong home của user tương ứng.

Login Codex Bot

sudo -u codexproxy -H codex login --device-auth
sudo systemctl restart tg-codex-bot
sudo journalctl -u tg-codex-bot -n 80 --no-pager

Login Claude Bot

sudo -u claudeproxy -H claude login
sudo systemctl restart tg-claude-bot
sudo journalctl -u tg-claude-bot -n 80 --no-pager

Kiểm tra nhanh

sudo -u codexproxy -H codex --version
sudo -u claudeproxy -H claude --version
systemctl is-active tg-codex-bot tg-claude-bot

Nếu login mở link hoặc mã xác thực, hãy hoàn tất ngay trên terminal đó. Không chạy cùng một Telegram bot token cho cả Codex và Claude vì hai service sẽ xung đột polling.

Thêm Telegram ID được phép dùng bot

Người dùng nhắn /whoami cho bot để lấy Telegram user id. Từ v0.0.29, Codex Bot và Claude Bot tự đọc lại ALLOWED_USER_ID, ALLOWED_CHAT_ID, ALLOWED_TOPIC_ID khi file .env đổi, nên thêm ID xong nhận ngay không cần restart.

Thêm ID cho cả Codex và Claude

curl -fsSL https://bot.ahvclaw.com/downloads/telegram-cli-bot-setup/allow-telegram-id.sh | sudo bash -s -- both 638048624

Chỉ thêm cho một bot

curl -fsSL https://bot.ahvclaw.com/downloads/telegram-cli-bot-setup/allow-telegram-id.sh | sudo bash -s -- codex 638048624
curl -fsSL https://bot.ahvclaw.com/downloads/telegram-cli-bot-setup/allow-telegram-id.sh | sudo bash -s -- claude 638048624

Restart thủ công khi cần

sudo systemctl restart tg-codex-bot tg-claude-bot

Lệnh sửa lỗi khi bot lỗi

Sửa lỗi nghĩa là cài lại bộ cập nhật/gói mới nhất, kiểm tra manifest, khởi động lại service và giữ cấu hình hiện tại. Trên Linux, lệnh dưới đây chạy như người dùng thật: tải script repair public, cài lại updater, chạy update ngay, restart bot đang tồn tại và in trạng thái cuối.

Linux sửa toàn bộ bộ cập nhật + bot

curl -fsSL https://bot.ahvclaw.com/downloads/telegram-cli-bot-setup/repair.sh | sudo BOT_PACKAGE_BASE_URL=https://bot.ahvclaw.com/downloads/telegram-cli-bot-setup AUTO_UPDATE_NOTIFY_CHAT_ID=638048624 bash

Windows sửa/cập nhật

irm https://bot.ahvclaw.com/downloads/telegram-cli-bot-setup/install.ps1 | iex

macOS sửa/cập nhật

bash <(curl -fsSL https://bot.ahvclaw.com/downloads/telegram-cli-bot-setup/install-mac.sh)

Xử lý lỗi thường gặp

Phát triển tiếp

Repository gốc trên máy build:

C:\Users\Administrator\telegram-cli-bot-setup

Các file chính:

• claude-bot/bot.py: wrapper Telegram cho Claude Code.
• codex-bot/bot.py: wrapper Telegram cho Codex CLI.
• install-package-update-linux.sh: cài timer updater cho Linux.
• manifest.json và VERSION: metadata public package.
• landing/bot-ahvclaw/: landing page và wiki public.

Checklist khi sửa code

python test_package_update_assets.py
python -m unittest discover claude-bot
python -m unittest discover codex-bot
python -m py_compile claude-bot\bot.py codex-bot\bot.py

Mọi fix bot phải sửa ở package gốc, bump version, rebuild zip, upload public và ép updater trên server cần cập nhật. Không được chỉ vá nóng live server rồi bỏ quên package.

Quy trình release

1. Sửa code/tài liệu trong package gốc.
2. Tăng phiên bản trong VERSION và manifest.json.
3. Đóng gói lại zip bằng script POSIX zip của workspace.
4. Cập nhật SHA256 thật vào manifest.
5. Chạy kiểm tra đầy đủ.
6. Upload lên ahvclaw:/srv/telegram-cli-bot-setup.
7. Kiểm tra HTTPS ở bot.ahvclaw.com và đường dẫn tương thích cũ.
8. Ép bộ cập nhật trên server cần nhận bản mới.