English | Deutsch | Français | 日本語 | 한국어 | Nederlands | ไทย | Tiếng Việt | 简体中文 | 繁體中文（香港） | 繁體中文（台灣）
軽量・マルチBot・マルチセッション・マルチタスク対応の 24/7 AI Coding Agent
Telegram からどこでもローカルの AI Coding Agent を操作できます。
Telegram で始めたセッションを、あとで同じ Codex/Copilot CLI セッションとして PC 上でそのまま続けられます。
coding-agent-telegram # または ./startup.sh を実行 |
|
→ ワンライナーでセットアップ:
curl -fsSL https://raw.githubusercontent.com/daocha/coding-agent-telegram/main/install.sh | bash
|
サーバー起動前に次を用意してください:
|
Openclaw は非常に多機能で、Pi-Agent という統合 agent loop も備えています。用途の幅も広く、とても包括的です。私自身も Openclaw が好きで、以前は Openclaw で coding していました。ですが、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 または one-liner install.sh でインストールした場合
coding-agent-telegram-stt-install
# クローンしたリポジトリから使う場合
./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のダウンロード中に最初の音声文字起こしがタイムアウトしやすくなります。- 音声メッセージを文字起こしした後、ボットはまず認識したテキストを Telegram に返し、その後でエージェントへ渡します。これにより認識ミスを確認しやすくなります。
- Telegram を開いて
@BotFatherとのチャットを開始します。 /newbotを送信します。- 次の内容に従って設定します:
- 表示名
botで終わるユーザー名
- BotFather から HTTP API token が返されます。
- その token を
~/.coding-agent-telegram/.env_coding_agent_telegramのTELEGRAM_BOT_TOKENSに設定します。
最も確実なのは、自分の bot token で Telegram の getUpdates API を使う方法です。
- 自分の bot とのチャットを開き、
/startなどのメッセージを送ります。 <BOT_TOKEN>を置き換えて次の URL をブラウザで開きます:
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 にもう一度メッセージを送り、再試行してください。
このボットが現在受け付けるもの:
- テキストメッセージ
- 写真
ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT=trueが設定され、ローカル Whisper の前提条件がインストールされている場合の音声メッセージと音声ファイル- Codex と Copilot は現在、テキストと画像のみをサポートしており、動画はサポートしていません
/provider |
新しいセッション用のプロバイダーを選択します。選択は変更するまで bot と chat ごとに保存されます。 |
/project <project_folder> |
現在のプロジェクトフォルダを設定します。フォルダが存在しない場合は作成して trusted として扱います。既存で untrusted の場合は明示的に trust を確認します。 |
/branch <new_branch> |
現在のプロジェクトで branch を準備または切り替えます。branch が既に存在する場合はその branch を source candidate として扱います。存在しない場合は repository の default branch を source candidate に使います。 |
/branch <origin_branch> <new_branch> |
<origin_branch> を source candidate として branch を準備または切り替えます。どちらの形式でも bot は実在する source choice のみを提示します: local/<branch> と origin/<branch>。片方だけ存在する場合はその選択肢だけが表示され、どちらも無い場合は branch source が無いと通知します。 |
/current |
現在の bot と chat の アクティブなセッション を表示します。 |
/new [session_name] |
現在のプロジェクトに新しいセッションを作成します。名前を省略すると実際のセッション ID を使います。プロバイダー、プロジェクト、branch が不足している場合は bot が不足分を案内します。 |
/switch |
最新のセッションを新しい順で表示します。現在のプロジェクトに対する bot 管理セッションとローカルの Codex/Copilot CLI セッションの両方を含みます。 |
/switch page <number> |
保存済みセッションの別ページを表示します。 |
/switch <session_id> |
ID を指定して特定のセッションに切り替えます。ローカル CLI セッションを選ぶと bot がそれを取り込み、そこから続行します。 |
/compact |
アクティブなセッションから新しい compact 済みセッションを作成し、そこへ切り替えます。 |
/commit <git commands> |
アクティブなセッション の project 内で、検証済みの git commit 関連コマンドを実行します。ENABLE_COMMIT_COMMAND=true のときだけ利用できます。変更を伴う Git コマンドには trusted project が必要です。 |
/diff |
アクティブなセッションの project で変更されたファイル名を、追跡済みファイルと未追跡ファイルに分けて表示します。追跡済みファイルには各ファイルの diff を開く inline ボタンが付きます。 |
/pull |
確認後に、アクティブなセッションのブランチで origin から pull します。必要に応じてデフォルト ブランチも更新します。 |
/push |
現在の アクティブなセッション に対して origin <branch> を push します。push 前に bot が確認します。 |
/abort |
現在のプロジェクトで実行中の エージェント実行 を中断します。キューされた質問 がある場合は続行するか確認します。 |
CODING_AGENT_TELEGRAM_ENV_FILE |
アプリに特定の env ファイルを使わせたい場合に指定します。 |
~/.coding-agent-telegram/.env_coding_agent_telegram |
既定の env ファイルの場所です。 |
./.env_coding_agent_telegram |
このローカルファイルがすでに存在する場合にのみ使われます。 |
WORKSPACE_ROOT |
プロジェクトディレクトリを含む親フォルダです。 |
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 モデルの任意上書きです。空欄なら Codex CLI の既定モデルを使います。例: gpt-5.4 OpenAI Codex/OpenAI models |
COPILOT_MODEL |
Copilot モデルの任意上書きです。空欄なら Copilot CLI の既定モデルを使います。例: 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 check を常にスキップします。 |
ENABLE_COMMIT_COMMAND |
Telegram の /commit コマンドを有効にします。既定: false. |
AGENT_HARD_TIMEOUT_SECONDS |
単一の エージェント実行 に対するハードタイムアウト。既定: 0（無効）。 |
SNAPSHOT_TEXT_FILE_MAX_BYTES |
実行ごとの diff 用に 実行前後のスナップショット を作る際、bot がテキストとして読む最大ファイルサイズです。既定: 200000. |
MAX_TELEGRAM_MESSAGE_LENGTH |
応答を分割する前に使う最大メッセージサイズ。既定: 3000. |
ENABLE_SENSITIVE_DIFF_FILTER |
機密ファイルの diff を隠します。既定: true. |
ENABLE_SECRET_SCRUB_FILTER |
tokens、keys、.env 値、certificates などの秘密らしい出力を Telegram 送信前にマスクします。既定: true（強く推奨）。 |
SNAPSHOT_INCLUDE_PATH_GLOBS |
一致するパスを diff に強制的に含めます。例: .github/*,.profile.test,.profile.prod |
SNAPSHOT_EXCLUDE_PATH_GLOBS |
パッケージ既定値に加えて diff 除外を追加します。例: .*,personal/*,sensitive*.txt 注: .* は 隠しディレクトリ内のファイルも含む隠しパス に一致します。 |
ENABLE_OPENAI_WHISPER_SPEECH_TO_TEXT |
デフォルト: false。true の場合、音声メッセージと音声ファイルの認識を有効にします。必要なバイナリやライブラリを起動時に確認し、不足していればインストールを案内します。 |
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 スコープでの アクティブなセッション 選択
プロジェクトフォルダー ごとに同時に動ける エージェント実行 は 1 つだけです。どの chat や Telegram bot から起動したかは関係ありません。
- プロジェクトは使用中: その workspace ですでに エージェント実行 が動いている状態
- エージェントは使用中: その 1 つの run が現在の依頼をまだ処理中の状態
2 つの agent が同じ workspace に同時に書き込まないように、この制約を設けています。競合する編集やデータ破損の可能性を減らすためです。
同じ project で既に agent が動作中なら、bot はすぐに次のように返します:
⏳ この project ではすでに agent が実行中です。完了するまで待ってください。
lock はディスクではなくメモリ上に保持されるため、agent 完了・失敗・server 再起動時に自動で解放されます。
現在の project で既に エージェント実行 が動いている場合、後から送られたテキストメッセージは拒否されずに queue されます。
- 新しい質問はディスク上の queued-questions file に追記されます
- 現在の agent は先の依頼をそのまま処理し続けます
- run が正常終了すると、bot は queue 内の質問の処理を自動で開始します
現在の run が abort され、まだ キューされた質問 が残っている場合は自動継続しません。残りを続けるかどうか、まとめて処理するか 1 件ずつ処理するかを bot が確認します。
各 エージェント実行 のたびに、bot はプロジェクトの軽量な 実行前後のスナップショット も取得し、変更ファイルの要約と diff を Telegram に送ります。この スナップショット は Codex や Copilot ではなく、bot 自身が作成します。
Snapshot のポイント:
- app は run の前後で プロジェクトディレクトリ を走査します
- 通常のテキストファイルでは、git head diff よりも 実行ごとのスナップショット差分 を優先します
- 一般的な依存関係、キャッシュ、実行時ディレクトリ も除外されます
- binary ファイル と
SNAPSHOT_TEXT_FILE_MAX_BYTESを超える ファイル は text として読み込みません - 非常に大きな project では、この追加走査によって I/O と memory の負荷が増えることがあります
- スナップショット で text として表現できない ファイル は、可能なら
git diffに fallback します - 大きい ファイル や非 text ファイル では、diff を省略して短いメッセージに置き換えることがあります
Snapshot の除外ルールは パッケージ resource にあります:
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 を source に使うorigin/<branch>: remote branch から更新してから切り替える
保存済みセッションの branch と現在の repository branch が一致しない場合、bot はそのまま続行しません。どちらの branch を使うか確認します:
- 保存済みセッションの branch を使う
- 現在の repository branch を使う
希望する source branch が存在しない場合は、生の Git error にせず、default branch と current branch を元に fallback source を提案します。
- 既存 folder は
CODEX_SKIP_GIT_REPO_CHECKに従います /project <name>で作成した folder は、この app により trusted として扱われます- 既存 folder を
/project <name>で選択した場合は、Telegram prompt で trust を確認するまで untrusted のままです - そのため、新しく作成した プロジェクトフォルダー はすぐに使えます
/commitはENABLE_COMMIT_COMMANDで完全に無効化できます- 変更を伴う
/commit操作は trusted project でのみ許可されます
log は stdout とローテーションする ログファイル の両方に書き込まれます:
~/.coding-agent-telegram/logs（10 MB でローテーション、3 世代保持）
注意: terminal を見ながら同時に ログファイル を tail すると、各メッセージが 2 回表示されます。これは想定どおりです。どちらか一方だけを見てください。
よく記録されるイベント
- bot 起動と polling 開始
- project 選択
- セッション作成
- セッション切り替え
- アクティブなセッション の表示
- 通常の run 実行（切り詰められた prompt を含む audit log 行も含む）
- resume 失敗後のセッション置き換え
- warning と runtime error
-
src/coding_agent_telegram/アプリ本体コード -
tests/テストスイート -
startup.shローカル bootstrap / 起動エントリーポイント -
src/coding_agent_telegram/resources/.env.examplerepo 起動と package インストールの両方で使う canonical な environment template -
pyproject.tomlパッケージング と 依存関係 の設定
package version は Git tag から導出されます。
- TestPyPI/testing:
v2026.3.26.dev1 - PyPI prerelease:
v2026.3.26rc1 - PyPI stable:
v2026.3.26
- このプロジェクトは、自分のマシンで agent をローカル実行するユーザー向けです。
- Telegram bot は操作面であり、実行環境そのものではありません。
- 複数の bot を使っていても、1 つの server process でまとめて管理できます。