Skip to content

README.vi.md

Latest commit

 

History

History
598 lines (480 loc) · 27.2 KB

README.vi.md

File metadata and controls

598 lines (480 loc) · 27.2 KB
Coding Agent Telegram

Coding Agent Telegram 🚀

English | Deutsch | Français | 日本語 | 한국어 | Nederlands | ไทย | Tiếng Việt | 简体中文 | 繁體中文（香港） | 繁體中文（台灣）

Nhẹ, nhiều bot, nhiều phiên, đa nhiệm, AI Coding Agent chạy 24/7

Điều khiển AI Coding Agent cục bộ của bạn từ bất kỳ đâu bằng Telegram.

Experimental MIT License Latest Release Python 3.9+

✨ Vì sao nên dùng

  • ✅ Nhẹ: không cần framework nặng, minh bạch hoàn toàn
  • ✅ Nhiều bot: nhiều cuộc chat, nhiều phiên
  • ✅ Dùng Telegram để điều khiển Codex / Copilot CLI
  • ✅ Dễ xem câu trả lời và các tệp đã thay đổi trong code block
  • ✅ Có thể xếp hàng câu hỏi tiếp theo khi agent đang làm việc
  • ✅ Chấp nhận tin nhắn ✏️ văn bản, 🌄 hình ảnh và 🎙️ thoại

🔁 Chuyển thiết bị/phiên liền mạch

Bắt đầu một phiên trên Telegram rồi tiếp tục đúng phiên Codex/Copilot CLI đó trên máy tính sau mà không cần thao tác rườm rà. Với /switch, bạn cũng có thể chuyển qua lại mượt mà giữa Telegram và command line.

  • Dùng /switch để tiếp tục một phiên cục bộ
  • Hỗ trợ cả các phiên lịch sử

🛠️ Luồng làm việc cục bộ điển hình

coding-agent-telegram # hoặc chạy ./startup.sh
Trong Telegram:
/project my-project
/new
Fix the failing API test in the current project

→ Cài đặt bằng một dòng lệnh:

curl -fsSL https://raw.githubusercontent.com/daocha/coding-agent-telegram/main/install.sh | bash

🔐 Bảo mật

  • Danh sách trắng cho chat riêng qua ALLOWED_CHAT_IDS

  • Chỉ cho phép một agent hoạt động trên mỗi project để giảm xung đột ghi

  • Ẩn diff của các tệp nhạy cảm

  • API keys, tokens, giá trị .env, certificates, SSH keys và các đầu ra mang tính bí mật sẽ được che trước khi gửi lại Telegram

  • Dữ liệu runtime của app nằm dưới ~/.coding-agent-telegram

  • Các thư mục có sẵn có thể yêu cầu xác nhận trust trước khi chạy Git operation có thay đổi

  • Máy chủ không thực hiện các lời gọi ra ngoài một cách ẩn. Bạn giữ toàn quyền kiểm soát.

  • Hoạt động tốt với Codex Sandbox mode, bạn không cần cấp danger-full-access

✅ Yêu cầu

Trước khi khởi động server, hãy chuẩn bị:

  • Python 3.9 trở lên
  • Telegram bot token tạo từ @BotFather
  • Telegram chat ID của bạn
  • Codex CLI và/hoặc Copilot CLI đã được cài cục bộ
  • Cài Codex CLI
  • Cài Copilot CLI
  • [Tùy chọn] Whisper, ffmpeg

🦞 Vì sao tôi cần cái này nếu đã có Openclaw?

Openclaw cung cấp bộ tính năng rất đầy đủ và đã có sẵn agent loop tích hợp tên là Pi-Agent. Nó khá toàn diện và phù hợp với nhiều use case đa dạng hơn. Tôi cũng là người thích Openclaw và từng code với Openclaw. Tuy vậy, riêng cho coding thì đây không phải lúc nào cũng là lựa chọn tốt nhất vì system prompt tích hợp khá lớn và context đi kèm nhiều hơn. Claude Code / Codex / Copilot vẫn thường hiệu quả hơn, chính xác hơn, ít bị phân tán hơn và trực tiếp hơn cho việc coding. Dự án này được giữ rất đơn giản, chỉ tích hợp Codex / Copilot CLI. Nghĩa là bạn giao việc trực tiếp cho Codex / Copilot.

🚀 Bắt đầu nhanh

Cách A: Script bootstrap một dòng

curl -fsSL https://raw.githubusercontent.com/daocha/coding-agent-telegram/main/install.sh | bash

Cách B: Cài từ PyPI bằng pip

pip install coding-agent-telegram
coding-agent-telegram

Cách C: Chạy từ repository đã clone

git clone https://github.com/daocha/coding-agent-telegram
cd coding-agent-telegram
./startup.sh

🌐 Khởi động bot server

Ở lần chạy đầu, app sẽ tạo tệp env và cho bạn biết cần điền trường nào.
Sau khi cập nhật tệp env, hãy chạy lại:
# nếu bạn làm theo Tùy chọn A hoặc Tùy chọn B, hãy chạy
coding-agent-telegram

# nếu bạn làm theo Tùy chọn C, hãy chạy lại lệnh này
./startup.sh

🎙️ [Tùy chọn] Tính năng chuyển giọng nói thành văn bản: chuẩn bị các điều kiện cần cục bộ của OpenAI-Whisper

Phần này dùng để bật tùy chọn chuyển tin nhắn thoại Telegram thành văn bản bằng Whisper chạy cục bộ. Tệp âm thanh được giới hạn tối đa 20 MB.

# nếu bạn cài bằng pip
coding-agent-telegram-stt-install

# nếu bạn chạy từ repository đã clone
./install-stt.sh

Thiết lập env được khuyến nghị:

ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT=true
OPENAI_WHISPER_MODEL=base
OPENAI_WHISPER_TIMEOUT_SECONDS=120

Lưu ý:

  • Whisper sẽ tự động tải model đã chọn vào ~/.cache/whisper ở lần dùng đầu tiên.
  • Nếu bạn chọn OPENAI_WHISPER_MODEL=turbo, lần chuyển giọng nói đầu tiên có khả năng chạm timeout cao hơn khi large-v3-turbo.pt vẫn đang được tải.
  • Sau khi một tin nhắn thoại được chép lại, bot sẽ gửi lại bản transcript đã nhận dạng vào Telegram trước rồi mới chuyển cho tác nhân. Điều này giúp kiểm tra lỗi nhận dạng dễ hơn.

🔑 Thiết lập Telegram

Lấy Bot Token

  1. Mở Telegram và bắt đầu chat với @BotFather.
  2. Gửi /newbot.
  3. Làm theo hướng dẫn để chọn:
    • tên hiển thị
    • tên người dùng bot kết thúc bằng bot
  4. BotFather sẽ trả về một HTTP API token.
  5. Đặt token đó vào TELEGRAM_BOT_TOKENS trong ~/.coding-agent-telegram/.env_coding_agent_telegram.

Lấy Chat ID

Cách đáng tin cậy nhất là dùng API getUpdates của Telegram với chính bot token của bạn.

  1. Bắt đầu chat với bot của bạn và gửi một tin nhắn như /start.
  2. Mở URL này trong trình duyệt và thay <BOT_TOKEN>:
https://api.telegram.org/bot<BOT_TOKEN>/getUpdates
  1. Tìm object chat trong JSON trả về.
  2. Sao chép trường số id trong object đó.
  3. Đặt giá trị đó vào ALLOWED_CHAT_IDS trong ~/.coding-agent-telegram/.env_coding_agent_telegram.

Lưu ý:

  • Với chat riêng, chat ID thường là số nguyên dương.
  • Nếu getUpdates trả về rỗng, hãy gửi thêm một tin nhắn cho bot rồi thử lại.

📨 Loại tin nhắn được hỗ trợ

Hiện tại bot chấp nhận:

  • tin nhắn văn bản
  • ảnh
  • tin nhắn thoại và tệp âm thanh khi ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT=true và các điều kiện cần cục bộ của Whisper đã được cài đặt
  • hiện tại Codex và Copilot chỉ hỗ trợ văn bản và hình ảnh, chưa hỗ trợ video

🤖 Lệnh Telegram

/provider Chọn nhà cung cấp cho các phiên mới. Lựa chọn này được lưu theo từng bot và chat cho đến khi bạn thay đổi.
/project <project_folder> Đặt thư mục project hiện tại. Nếu thư mục chưa tồn tại, app sẽ tạo và đánh dấu là trusted. Nếu đã tồn tại nhưng vẫn untrusted, app sẽ yêu cầu xác nhận trust rõ ràng.
/branch <new_branch> Chuẩn bị hoặc chuyển branch cho project hiện tại. Nếu branch đã tồn tại, bot coi branch đó là source candidate. Nếu chưa có, bot dùng default branch của repository làm source candidate.
/branch <origin_branch> <new_branch> Chuẩn bị hoặc chuyển branch bằng cách dùng <origin_branch> làm source candidate. Với cả hai dạng, bot chỉ đưa ra các source choice thật sự tồn tại: local/<branch> và origin/<branch>. Nếu chỉ có một lựa chọn thì chỉ hiện lựa chọn đó. Nếu không có lựa chọn nào, bot sẽ báo thiếu branch source.
/current Hiển thị phiên hoạt động cho bot và chat hiện tại.
/new [session_name] Tạo phiên mới cho project hiện tại. Nếu bỏ qua tên, bot sẽ dùng mã định danh phiên thật. Nếu thiếu nhà cung cấp, project hoặc branch, bot sẽ hướng dẫn bước còn thiếu.
/switch Hiển thị các phiên mới nhất, mới nhất trước. Danh sách bao gồm cả phiên do bot quản lý và phiên CLI Codex/Copilot cục bộ của project hiện tại.
/switch page <number> Hiển thị trang khác của các phiên đã lưu.
/switch <session_id> Chuyển sang một phiên cụ thể bằng ID. Nếu bạn chọn phiên CLI cục bộ, bot sẽ import nó và tiếp tục từ đó.
/compact Tạo một phiên rút gọn mới từ phiên đang hoạt động rồi chuyển sang phiên đó.
/commit <git commands> Chạy các lệnh liên quan đến git commit đã được kiểm tra trong project của phiên hoạt động. Chỉ có khi ENABLE_COMMIT_COMMAND=true. Các lệnh Git có thay đổi yêu cầu project đã trusted.
/diff Hiển thị tên các tệp đã thay đổi trong project của phiên đang hoạt động, tách riêng tệp đã theo dõi và tệp chưa theo dõi. Các tệp đã theo dõi có nút inline để mở diff của từng tệp.
/pull Sau khi xác nhận, thực hiện pull từ origin cho branch của phiên đang hoạt động. Bot cũng làm mới branch mặc định khi cần.
/push Push origin <branch> cho phiên hoạt động hiện tại. Bot sẽ hỏi xác nhận trước khi push.
/abort Hủy lần chạy tác nhân hiện tại của project hiện tại. Nếu còn các câu hỏi trong hàng đợi chờ xử lý, bot sẽ hỏi có tiếp tục hay không.

⚙️ Biến môi trường

Đường dẫn tệp env chính:

CODING_AGENT_TELEGRAM_ENV_FILE Dùng khi bạn muốn app trỏ tới một tệp env cụ thể.
~/.coding-agent-telegram/.env_coding_agent_telegram Vị trí tệp env mặc định.
./.env_coding_agent_telegram Chỉ dùng khi tệp local này đã tồn tại.

Bắt buộc

WORKSPACE_ROOT Thư mục cha chứa các thư mục project của bạn.
TELEGRAM_BOT_TOKENS Các Telegram bot token, ngăn cách bằng dấu phẩy.
ALLOWED_CHAT_IDS Các Telegram private chat ID được phép dùng bot, ngăn cách bằng dấu phẩy.

Cài đặt thường dùng

APP_LOCALE Ngôn ngữ UI cho các thông điệp bot dùng chung và mô tả lệnh. Giá trị hỗ trợ: en, de, fr, ja, ko, nl, th, vi, zh-CN, zh-HK, zh-TW.
CODEX_BIN Lệnh dùng để chạy Codex CLI. Mặc định: codex.
COPILOT_BIN Lệnh dùng để chạy Copilot CLI. Mặc định: copilot.
CODEX_MODEL Ghi đè model Codex nếu cần. Để trống để dùng model mặc định của Codex CLI. Ví dụ: gpt-5.4 OpenAI Codex/OpenAI models
COPILOT_MODEL Ghi đè model Copilot nếu cần. Để trống để dùng model mặc định của Copilot CLI. Ví dụ: gpt-5.4, claude-sonnet-4.6 GitHub Copilot supported models
CODEX_APPROVAL_POLICY Chế độ approval truyền cho Codex. Mặc định: never.
CODEX_SANDBOX_MODE Chế độ sandbox truyền cho Codex. Mặc định: workspace-write.
CODEX_SKIP_GIT_REPO_CHECK Nếu bật, luôn bỏ qua trusted-repo check của Codex.
ENABLE_COMMIT_COMMAND Bật lệnh Telegram /commit. Mặc định: false.
AGENT_HARD_TIMEOUT_SECONDS Timeout cứng cho một lần lần chạy tác nhân. Mặc định: 0 (tắt).
SNAPSHOT_TEXT_FILE_MAX_BYTES Kích thước tệp tối đa mà bot sẽ đọc dưới dạng văn bản khi tạo ảnh chụp nhanh trước/sau cho diff của từng run. Mặc định: 200000.
MAX_TELEGRAM_MESSAGE_LENGTH Kích thước tin nhắn tối đa trước khi app tách phản hồi. Mặc định: 3000.
ENABLE_SENSITIVE_DIFF_FILTER Ẩn diff của các tệp nhạy cảm. Mặc định: true.
ENABLE_SECRET_SCRUB_FILTER Che tokens, keys, giá trị .env, certificates và các đầu ra giống bí mật trước khi gửi về Telegram. Mặc định: true (rất nên bật).
SNAPSHOT_INCLUDE_PATH_GLOBS Luôn đưa các path khớp điều kiện vào diff. Ví dụ: .github/*,.profile.test,.profile.prod
SNAPSHOT_EXCLUDE_PATH_GLOBS Thêm các rule loại trừ diff ngoài bộ mặc định của package. Ví dụ: .*,personal/*,sensitive*.txt Lưu ý: .* khớp cả path ẩn, gồm cả tệp trong thư mục ẩn.

Chuyển giọng nói thành văn bản

ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT Mặc định: false. Nếu bật true, hệ thống sẽ nhận dạng tin nhắn thoại và tệp âm thanh. Hệ thống sẽ kiểm tra các binary hoặc thư viện cần thiết và nhắc người dùng cài đặt nếu còn thiếu.
OPENAI_WHISPER_MODEL Mô hình dùng cho Whisper STT. Mặc định: base
Các mô hình khả dụng: tiny khoảng 72 MB, base khoảng 139 MB, large-v3-turbo khoảng 1.5 GB
Mô hình sẽ được tự động tải xuống khi bạn gửi tin nhắn thoại đầu tiên. Khuyến nghị: base cho nhu cầu chung. Nếu muốn độ chính xác và chất lượng tốt hơn, bạn có thể thử turbo.
OPENAI_WHISPER_TIMEOUT_SECONDS Mặc định: 120. Thời gian chờ cho tiến trình STT. Thông thường STT đủ nhanh, nhưng nếu bạn chọn turbo, lần gửi tin nhắn thoại đầu tiên có thể vượt quá thời gian chờ do phải tải mô hình, tùy theo tốc độ mạng.

Trạng thái và log

~/.coding-agent-telegram/state.json Tệp trạng thái phiên chính.
~/.coding-agent-telegram/state.json.bak Tệp sao lưu trạng thái.
~/.coding-agent-telegram/logs Thư mục log.

Ví dụ:

APP_LOCALE=en
WORKSPACE_ROOT=~/git
TELEGRAM_BOT_TOKENS=bot_token_one
ALLOWED_CHAT_IDS=123456789
DEFAULT_AGENT_PROVIDER=codex
CODEX_BIN=codex
COPILOT_BIN=copilot
CODEX_APPROVAL_POLICY=never
CODEX_SANDBOX_MODE=workspace-write
ENABLE_SENSITIVE_DIFF_FILTER=true
ENABLE_SECRET_SCRUB_FILTER=true

🧠 Quản lý phiên

Phiên được tách theo:

  • Telegram bot
  • Telegram chat

Vì vậy cùng một tài khoản Telegram có thể dùng nhiều bot mà không làm lẫn phiên.

Ví dụ:

  • Bot A + chat của bạn -> việc backend
  • Bot B + chat của bạn -> việc frontend
  • Bot C + chat của bạn -> việc infra

phiên hoạt động cũng gắn với:

  • thư mục dự án
  • nhà cung cấp
  • branch name nếu có
Mỗi phiên lưu:
  • tên phiên
  • thư mục dự án
  • branch name
  • nhà cung cấp
  • timestamps
  • phiên hoạt động được chọn cho phạm vi bot/chat đó

🔓 Khóa đồng thời workspace

Chỉ có thể có một lần chạy tác nhân hoạt động trên mỗi thư mục dự án tại một thời điểm, bất kể chat hay Telegram bot nào khởi chạy.

  • dự án đang bận: workspace đó đã có một lần chạy tác nhân đang chạy
  • tác nhân đang bận: chính run đó vẫn đang xử lý yêu cầu hiện tại

Bot cố ý áp dụng giới hạn này để hai agent không ghi vào cùng một workspace cùng lúc. Điều đó giúp tránh sửa đổi xung đột và giảm nguy cơ hỏng dữ liệu.

Nếu có tin nhắn đến khi cùng project đã có agent chạy, bot sẽ trả lời ngay:

⏳ Đã có agent đang chạy trên project này. Hãy đợi cho đến khi nó hoàn tất.

Lock được giữ trong bộ nhớ, không phải trên đĩa, nên sẽ tự giải phóng khi agent hoàn tất, lỗi hoặc khi server khởi động lại.

💬 Câu hỏi trong hàng đợi

Nếu project hiện tại đã có lần chạy tác nhân đang chạy, các tin nhắn văn bản gửi sau sẽ không bị từ chối mà được đưa vào queue.

  • câu hỏi mới được nối vào tệp queued-questions trên đĩa
  • agent hiện tại tiếp tục làm yêu cầu trước đó
  • khi run đó kết thúc bình thường, bot tự động bắt đầu xử lý các câu hỏi trong hàng đợi

Nếu run hiện tại bị abort và vẫn còn các câu hỏi trong hàng đợi, bot sẽ không tự tiếp tục. Bot sẽ hỏi có muốn tiếp tục xử lý phần còn lại theo dạng gộp hay từng câu một hay không.

⚠️ Diff (thay đổi tệp)

Trong mỗi lần chạy tác nhân, bot cũng tạo một ảnh chụp nhanh trước/sau nhẹ của project để có thể tóm tắt các tệp thay đổi và gửi diff về Telegram. Bản chụp nhanh này do chính bot app tạo ra, không phải bởi Codex hay Copilot.

Ghi chú về ảnh chụp nhanh:

  • app quét thư mục dự án trước và sau mỗi run
  • với tệp văn bản thông thường, app ưu tiên diff ảnh chụp nhanh theo từng run hơn là diff so với git head
  • các thư mục phụ thuộc, bộ đệm và runtime phổ biến cũng bị bỏ qua
  • tệp nhị phân và tệp lớn hơn SNAPSHOT_TEXT_FILE_MAX_BYTES sẽ không được đọc như văn bản
  • với project rất lớn, lần quét bổ sung này có thể làm tăng đáng kể I/O và bộ nhớ
  • nếu ảnh chụp nhanh không thể biểu diễn tệp dưới dạng văn bản, app sẽ fallback sang git diff khi có thể
  • với tệp lớn hoặc không phải văn bản, diff vẫn có thể bị bỏ qua và thay bằng thông báo ngắn

Các rule loại trừ ảnh chụp nhanh nằm trong tài nguyên gói:

  • src/coding_agent_telegram/resources/ảnh chụp nhanh_excluded_dir_names.txt
  • src/coding_agent_telegram/resources/ảnh chụp nhanh_excluded_dir_globs.txt
  • src/coding_agent_telegram/resources/ảnh chụp nhanh_excluded_file_globs.txt

Bạn có thể override các giá trị mặc định này trong file env mà không cần sửa package đã cài:

  • SNAPSHOT_INCLUDE_PATH_GLOBS Luôn đưa các path khớp vào diff. Ví dụ: .github/*,.profile.test,.profile.prod

  • SNAPSHOT_EXCLUDE_PATH_GLOBS Thêm các diff exclusion ngoài bộ mặc định của package. Ví dụ: .*,personal/*,sensitive*.txt Lưu ý: .* khớp cả đường dẫn ẩn, kể cả tệp trong thư mục ẩn.

Nếu include và exclude cùng khớp, include sẽ được ưu tiên.

🌿 Hành vi của Branch

Bot coi project và branch là một cặp đi cùng nhau.

  • việc chọn project sẽ không âm thầm chọn một branch không liên quan
  • nếu cần branch, bot sẽ yêu cầu bạn chọn
  • khi thông tin branch được hiển thị trong các thông báo liên quan đến phiên, project và branch sẽ được hiển thị cùng nhau

Khi bạn tạo hoặc đổi branch, bot sẽ hướng dẫn rõ source:

  • local/<branch> nghĩa là dùng local branch làm source
  • origin/<branch> nghĩa là cập nhật từ remote branch trước rồi mới chuyển

Nếu bot phát hiện branch lưu trong phiên không khớp với branch hiện tại của repository, bot sẽ không tiếp tục một cách mù quáng. Bot sẽ hỏi bạn muốn dùng branch nào:

  • giữ branch đã lưu trong phiên
  • giữ branch hiện tại của repository

Nếu source branch bạn muốn không còn, bot sẽ đưa ra các fallback source dựa trên default branch và current branch thay vì để bạn đối mặt với Git error thô.

🔐 Hành vi trust của Git

  • thư mục đã tồn tại sẽ tuân theo CODEX_SKIP_GIT_REPO_CHECK
  • thư mục được tạo qua /project <name> sẽ được app này đánh dấu là trusted
  • thư mục đã có sẵn được chọn qua /project <name> sẽ vẫn là untrusted cho đến khi bạn xác nhận trust trong Telegram
  • vì vậy các thư mục dự án mới tạo có thể dùng ngay
  • có thể tắt hoàn toàn /commit bằng ENABLE_COMMIT_COMMAND
  • các thao tác /commit có sửa đổi chỉ được phép trên trusted project

🪵 Nhật ký

Log được ghi cả ra stdout và vào file log quay vòng dưới:

  • ~/.coding-agent-telegram/logs (quay vòng ở 10 MB, giữ 3 bản sao)

Lưu ý: nếu bạn vừa xem terminal vừa tail file log, mỗi thông điệp sẽ xuất hiện hai lần. Đây là hành vi bình thường. Hãy chỉ xem một nơi tại một thời điểm.

Các sự kiện thường được ghi log
  • bot khởi động và bắt đầu polling
  • chọn project
  • tạo phiên
  • chuyển phiên
  • báo cáo phiên hoạt động
  • chạy bình thường (bao gồm audit log line với prompt đã được rút gọn)
  • thay phiên sau khi resume thất bại
  • warnings và runtime errors

🗂️ Cấu trúc dự án

  • src/coding_agent_telegram/ mã nguồn chính của ứng dụng

  • tests/ bộ kiểm thử

  • startup.sh entrypoint bootstrap và startup cục bộ

  • src/coding_agent_telegram/resources/.env.example mẫu environment chính được dùng cả khi chạy từ repo và khi cài dưới dạng package

  • pyproject.toml cấu hình đóng gói và dependencies

📦 Quy ước phiên bản release

Phiên bản package được suy ra từ Git tags.

  • TestPyPI/testing: v2026.3.26.dev1
  • PyPI prerelease: v2026.3.26rc1
  • PyPI stable: v2026.3.26

📌 Ghi chú

  • Dự án này dành cho người dùng chạy agent cục bộ trên chính máy của mình.
  • Telegram bot là lớp điều khiển, không phải môi trường thực thi.
  • Nếu bạn chạy nhiều bot, tất cả vẫn có thể được quản lý bởi một server process duy nhất.