English | Deutsch | Français | 日本語 | 한국어 | Nederlands | ไทย | Tiếng Việt | 简体中文 | 繁體中文（香港） | 繁體中文（台灣）
輕量、多 Bot、多工作階段、多工、24/7 AI Coding Agent
透過 Telegram 隨時隨地控制你本機的 AI Coding Agent。
你可以先在 Telegram 開始一個工作階段，之後再在電腦上繼續同一個 Codex/Copilot CLI 工作階段，過程自然順暢。使用
coding-agent-telegram # 或執行 ./startup.sh |
|
→ 一行指令安裝：
curl -fsSL https://raw.githubusercontent.com/daocha/coding-agent-telegram/main/install.sh | bash
|
在啟動 server 之前，請先準備：
|
Openclaw 提供非常完整的能力，也內建了名為 Pi-Agent 的 agent loop，適合更多元的 use case。我自己也很喜歡 Openclaw，過去亦曾用它來寫 code。不過對純 coding 來說，它未必永遠是最佳選擇，因為內建的大型 system prompt 和額外 context 有時會令模型更容易分心。Claude Code / Codex / Copilot 在 coding 場景下通常仍然更有效率、更準確、更少被干擾，也更直接。這個 project 刻意保持簡單，只整合 Codex / Copilot CLI，所以你其實是在直接把工作交給 Codex / Copilot。
curl -fsSL https://raw.githubusercontent.com/daocha/coding-agent-telegram/main/install.sh | bashpip install coding-agent-telegram
coding-agent-telegramgit clone https://github.com/daocha/coding-agent-telegram
cd coding-agent-telegram
./startup.sh# 如果你使用方案 A 或方案 B，則執行
coding-agent-telegram
# 如果你使用方案 C，則再次執行此指令
./startup.sh這部分可選啟用 Telegram 語音訊息的本機 Whisper 語音轉文字功能。音訊檔案最大限制為 20 MB。
# 如果你是用 pip 安裝
coding-agent-telegram-stt-install
# 如果你是從 clone 的 repository 執行
./install-stt.sh建議的 env 設定：
ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT=true
OPENAI_WHISPER_MODEL=base
OPENAI_WHISPER_TIMEOUT_SECONDS=120
說明：
- Whisper 會在首次使用時自動把所選模型下載到
~/.cache/whisper。 - 如果你選擇
OPENAI_WHISPER_MODEL=turbo，第一次語音轉錄更容易在large-v3-turbo.pt尚在下載時觸發逾時。 - 語音訊息轉錄完成後，bot 會先把辨識出的文字回傳到 Telegram，再把它交給 agent。這樣更方便排查辨識錯誤。
- 開啟 Telegram，並與
@BotFather開始聊天。 - 傳送
/newbot。 - 按提示設定：
- 顯示名稱
- 以
bot結尾的 bot 使用者名稱
- BotFather 會回傳 HTTP API token。
- 把這個 token 填入
~/.coding-agent-telegram/.env_coding_agent_telegram內的TELEGRAM_BOT_TOKENS。
最可靠的方法是使用你自己的 bot token 呼叫 Telegram 的 getUpdates API。
- 與你的 bot 開始聊天，並傳送一條訊息，例如
/start。 - 在瀏覽器開啟以下 URL，並將
<BOT_TOKEN>替換掉：
https://api.telegram.org/bot<BOT_TOKEN>/getUpdates
- 在 JSON 回應中找出
chat物件。 - 複製其中數值型的
id欄位。 - 把該值填入
~/.coding-agent-telegram/.env_coding_agent_telegram內的ALLOWED_CHAT_IDS。
說明：
- 私人聊天的 chat ID 通常是正整數。
- 如果
getUpdates回傳空結果，請先再傳一條訊息給 bot，然後重試。
bot 目前接受：
- 文字訊息
- 圖片
- 當
ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT=true且已安裝本機 Whisper 依賴時的語音訊息與音訊檔案 - Codex 與 Copilot 目前只支援文字與圖片，不支援影片
/provider |
為新的工作階段選擇提供者。這個選擇會按 bot 與 chat 儲存，直到你手動修改。 |
/project <project_folder> |
設定目前的 project 資料夾。如果資料夾不存在，app 會建立並標記為 trusted；如果已存在但仍是 untrusted，app 會明確要求確認 trust。 |
/branch <new_branch> |
為目前的 project 準備或切換 branch。如果 branch 已存在，bot 會把它當作 source candidate；否則會使用 repository 的 default branch 作為 source candidate。 |
/branch <origin_branch> <new_branch> |
使用 <origin_branch> 作為 source candidate 來準備或切換 branch。無論哪種形式，bot 之後只會提供實際存在的 source choices：local/<branch> 和 origin/<branch>。若只存在其中一個，就只顯示那個；若兩個都不存在，bot 會提示缺少 branch source。 |
/current |
顯示目前 bot 與 chat 的作用中工作階段。 |
/new [session_name] |
為目前的專案建立新工作階段。如果省略名稱，bot 會使用真實工作階段 ID。若缺少提供者、專案或 branch，bot 會引導你完成缺少的步驟。 |
/switch |
顯示最新的工作階段，按由新到舊排序。列表同時包含 bot 管理的工作階段以及目前專案的本機 Codex/Copilot CLI 工作階段。 |
/switch page <number> |
顯示已儲存工作階段的其他頁面。 |
/switch <session_id> |
透過 ID 切換到指定工作階段。如果你選擇本機 CLI 工作階段，bot 會把它匯入狀態並從那裡繼續。 |
/compact |
從目前使用中的工作階段建立新的壓縮工作階段，並切換到該工作階段。 |
/commit <git commands> |
在作用中工作階段的專案內執行已驗證的 git commit 相關指令。只在 ENABLE_COMMIT_COMMAND=true 時可用。會修改內容的 Git 指令要求專案已 trusted。 |
/diff |
顯示作用中工作階段專案內已變更的檔案名稱，並分開列出已追蹤與未追蹤檔案。已追蹤檔案會附帶 inline 按鈕，可直接開啟單一檔案的 diff。 |
/pull |
確認後，從 origin 拉取作用中工作階段目前的分支。適用時，bot 也會一併重新整理預設分支。 |
/push |
為目前作用中工作階段執行 origin <branch> push。push 前 bot 會要求確認。 |
/abort |
中止目前 project 的 代理執行。如果還有 排隊問題 等候，bot 會詢問是否繼續處理。 |
CODING_AGENT_TELEGRAM_ENV_FILE |
如果你想讓 app 使用指定的 env 檔案，可設定此項。 |
~/.coding-agent-telegram/.env_coding_agent_telegram |
預設的 env 檔案位置。 |
./.env_coding_agent_telegram |
只有當這個本機檔案已經存在時才會使用。 |
WORKSPACE_ROOT |
包含你各個 project 目錄的父資料夾。 |
TELEGRAM_BOT_TOKENS |
以逗號分隔的 Telegram bot token。 |
ALLOWED_CHAT_IDS |
允許使用此 bot 的 Telegram 私人 chat ID，使用逗號分隔。 |
APP_LOCALE |
共用 bot 訊息與指令說明所使用的 UI 語言。支援值：en、de、fr、ja、ko、nl、th、vi、zh-CN、zh-HK、zh-TW。 |
CODEX_BIN |
用來啟動 Codex CLI 的指令。預設：codex。 |
COPILOT_BIN |
用來啟動 Copilot CLI 的指令。預設：copilot。 |
CODEX_MODEL |
可選的 Codex model override。留空則使用 Codex CLI 預設 model。例子：gpt-5.4 OpenAI Codex/OpenAI models |
COPILOT_MODEL |
可選的 Copilot model override。留空則使用 Copilot CLI 預設 model。例子：gpt-5.4、claude-sonnet-4.6 GitHub Copilot supported models |
CODEX_APPROVAL_POLICY |
傳遞給 Codex 的 approval mode。預設：never。 |
CODEX_SANDBOX_MODE |
傳遞給 Codex 的 sandbox mode。預設：workspace-write。 |
CODEX_SKIP_GIT_REPO_CHECK |
如果啟用，會一直略過 Codex 的 trusted-repo 檢查。 |
ENABLE_COMMIT_COMMAND |
啟用 Telegram 的 /commit 指令。預設：false。 |
AGENT_HARD_TIMEOUT_SECONDS |
單次 代理執行 的硬性 timeout。預設：0（停用）。 |
SNAPSHOT_TEXT_FILE_MAX_BYTES |
建立每次執行的前後 快照 diff 時，bot 會以文字讀取的最大檔案大小。預設：200000。 |
MAX_TELEGRAM_MESSAGE_LENGTH |
app 分割回覆前使用的最大訊息長度。預設：3000。 |
ENABLE_SENSITIVE_DIFF_FILTER |
隱藏敏感檔案的 diff。預設：true。 |
ENABLE_SECRET_SCRUB_FILTER |
在送往 Telegram 之前，對 tokens、keys、.env 值、certificates 及類似秘密輸出做遮罩。預設：true（強烈建議啟用）。 |
SNAPSHOT_INCLUDE_PATH_GLOBS |
強制把符合條件的 path 納入 diff。例子：.github/*,.profile.test,.profile.prod |
SNAPSHOT_EXCLUDE_PATH_GLOBS |
在套件預設值之外額外加入 diff 排除規則。例子：.*,personal/*,sensitive*.txt 說明：.* 會比對隱藏 path，包括隱藏資料夾內的檔案。 |
ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT |
預設：false。如果為 true，就會啟用語音訊息與音訊檔案識別。系統會檢查所需的 binary 或 library 依賴，缺少時會提示使用者安裝。 |
OPENAI_WHISPER_MODEL |
Whisper STT 使用的模型。預設：base可用模型： tiny 約 72 MB、base 約 139 MB、large-v3-turbo 約 1.5 GB模型會在你第一次傳送語音訊息時自動下載。建議一般使用選 base。如果你想要更好的準確率與品質，可以嘗試 turbo。 |
OPENAI_WHISPER_TIMEOUT_SECONDS |
預設：120。STT 進程的逾時時間。一般來說處理速度已足夠快，但如果你選擇 turbo，首次下載可能會視乎網速而超出逾時限制。 |
~/.coding-agent-telegram/state.json |
工作階段狀態主檔。 |
~/.coding-agent-telegram/state.json.bak |
狀態備份檔。 |
~/.coding-agent-telegram/logs |
日誌目錄。 |
範例：
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工作階段會按以下範圍分開：
- Telegram bot
- Telegram chat
這表示同一個 Telegram 帳號可以同時使用多個 bot，而不會把工作階段混在一起。
例子：
- Bot A + 你的 chat -> backend 工作
- Bot B + 你的 chat -> frontend 工作
- Bot C + 你的 chat -> infra 工作
目前作用中的工作階段亦會綁定到：
- 專案資料夾
- 提供者
- 如有的話，branch 名稱
每個工作階段會儲存：
- 工作階段名稱
- 專案資料夾
- branch 名稱
- 提供者
- timestamps
- 該 bot/chat 範圍下的作用中工作階段選擇
同一時間，每個專案資料夾只能有一個代理執行在運作，不論它是由哪個 chat 或 Telegram bot 觸發。
- 專案忙碌中：該工作區裡已經有一個代理執行在運作
- 代理忙碌中：該執行仍在處理目前的請求
bot 會強制這個限制，避免兩個 agent 同時寫入同一個 workspace，從而減少衝突修改和資料損壞風險。
如果同一個 project 已經有 agent 在運行，又收到新訊息，bot 會立即回覆：
⏳ 專案上已有代理正在執行。請等待其完成。
這個 lock 只保存在記憶體中，不會寫入磁碟，所以當 agent 完成、失敗或 server 重新啟動時會自動釋放。
如果目前的 project 已經有一個 代理執行 在執行，之後的文字訊息不會被拒絕，而是會進入佇列。
- 新問題會追加到磁碟上的 queued-questions file
- 目前的 agent 會繼續處理先前的請求
- 當該 run 正常結束後，bot 會自動開始處理佇列中的問題
如果目前的 run 被 abort，而仍有 排隊問題 在等待，bot 不會自動繼續。它會詢問你是否要繼續處理剩餘問題，以及要分批還是逐個處理。
在每次 代理執行 期間，bot 也會為 project 產生輕量的 前後快照，用來總結已變更檔案並把 diff 傳回 Telegram。這個 快照 是由 bot app 自己建立，不是由 Codex 或 Copilot 建立。
快照說明：
- app 會在 run 前後掃描 專案目錄
- 對一般文字檔，app 會優先使用本次 run 的 快照 diff，而不是 git head diff
- 常見的 依賴、快取 和 執行時目錄 也會被略過
- 二進位檔案 以及大於
SNAPSHOT_TEXT_FILE_MAX_BYTES的 檔案 不會以文字方式讀取 - 對非常大的 project，這次額外掃描可能增加明顯的 I/O 和記憶體負擔
- 如果 快照 無法把 檔案 表示為文字，app 會在可行時 fallback 到
git diff - 對大檔案或非文字檔，diff 仍可能被省略，並以簡短訊息代替
快照排除規則位於套件資源：
src/coding_agent_telegram/resources/snapshot_excluded_dir_names.txtsrc/coding_agent_telegram/resources/snapshot_excluded_dir_globs.txtsrc/coding_agent_telegram/resources/snapshot_excluded_file_globs.txt
你可以在 環境檔案 中覆蓋這些預設值，而不用修改已安裝的套件：
-
SNAPSHOT_INCLUDE_PATH_GLOBS強制把符合的 path 納入 diff。 例子：.github/*,.profile.test,.profile.prod -
SNAPSHOT_EXCLUDE_PATH_GLOBS在 套件 預設值之外加入額外的 diff 排除規則。 例子：.*,personal/*,sensitive*.txt說明：.*會比對 隱藏路徑，包括隱藏目錄內的檔案。
如果 include 和 exclude 同時命中，include 會優先。
bot 會把 project 和 branch 當成一組來處理。
- 選擇 project 時不會靜默切到無關 branch
- 如果需要 branch 輸入，bot 會要求你選擇
- 在工作階段相關訊息中顯示 branch 資訊時，專案和 branch 會一起顯示
當你建立或切換 branch 時，bot 會明確引導你選擇 source：
local/<branch>：使用本地 branch 作為 sourceorigin/<branch>：先從遠端 branch 更新，再切換
如果 bot 發現工作階段中儲存的 branch 與目前儲存庫 branch 不一致，它不會盲目繼續，而會詢問你想使用哪個 branch：
- 保留工作階段中儲存的 branch
- 保留目前 repository branch
如果你偏好的 source branch 已不存在，bot 會根據 default branch 和 current branch 提供 fallback source，而不是直接丟出原始 Git error。
- 已存在的 folder 會遵循
CODEX_SKIP_GIT_REPO_CHECK - 透過
/project <name>建立的 folder 會被這個 app 標記為 trusted - 透過
/project <name>選取的既有 folder，在你於 Telegram 確認 trust 前仍然保持 untrusted - 因此，新建立的專案資料夾可以立即使用
- 可以用
ENABLE_COMMIT_COMMAND完全停用/commit - 會修改內容的
/commit操作只允許在 trusted project 上執行
log 會同時寫入 stdout 和輪轉 日誌檔案，路徑如下：
~/.coding-agent-telegram/logs（10 MB 輪轉，保留 3 份備份）
**注意：**如果你同時看 terminal 又去 tail 日誌檔案，每條訊息都會出現兩次。這是正常行為。請只看其中一邊，不要同時看兩邊。
常見記錄事件
- bot 啟動與 polling 開始
- project 選擇
- 工作階段建立
- 工作階段切換
- 作用中工作階段報告
- 正常 run 執行（包含被截短的 prompt audit log 行）
- resume 失敗後的工作階段替換
- warnings 與 runtime errors
-
src/coding_agent_telegram/app 主程式碼 -
tests/測試套件 -
startup.sh本地啟動與執行入口 -
src/coding_agent_telegram/resources/.env.example標準環境範本，同時用於儲存庫啟動與套件安裝 -
pyproject.toml封裝 與 依賴 設定
套件版本由 Git tags 推導而來。
- TestPyPI/testing:
v2026.3.26.dev1 - PyPI prerelease:
v2026.3.26rc1 - PyPI stable:
v2026.3.26
- 本專案面向在自己機器上本地執行 agent 的使用者。
- Telegram bot 是控制介面，不是實際執行環境。
- 如果你運行多個 bot，也可以由同一個 server process 統一管理。