grinev/opencode-telegram-bot

OpenCode mobile client via Telegram: run and monitor AI coding tasks from your phone while everything runs locally on your machine. Scheduled tasks support.

OpenCode Telegram Bot – 何であるか

Node.js による Telegram ボット で、スマートフォンから OpenCode AI コーディング CLI を制御できます。このボットは、ローカルの OpenCode サーバー（同じマシン上で実行中）と公式の Telegram Bot API のみと通信し、パブリックポートや公開 API を必要としません。実際には、Telegram チャットからコーディングセッションを開始し、モデルを切り替え、ファイルを送信し、リアルタイムの進捗を確認し、ジョブをスケジュールし、設定を管理できます。

コア機能（README に記載）

分野	Telegram から行える操作
リモートコーディング	任意のテキストプロンプト（または音声変換されたプロンプト）を OpenCode に送信し、生成されたコードをファイルとして受け取る。
セッション管理	新しいセッションを作成（`/new`）、既存のセッションを継続（`/sessions`）、名前を変更（`/rename`）、中断（`/abort`）、分離（`/detach`）。
リアルタイム追跡	実行中の OpenCode CLI セッションを追跡し、リアルタイムでエージェント出力、サブエージェントステップ、および他の TUI クライアントからの外部入力を表示。
モデル管理	OpenCode のお気に入りや最近使用したモデルから選択、またはプロバイダー別にすべてのモデルを直接チャット内で閲覧。
エージェントモード	Plan と Build モードをリアルタイムで切り替え、サブエージェントの活動を監視。
スキルとコマンド	OpenCode の「スキル」やカスタムコマンド（`/skills`、`/commands`）を閲覧し、オプション引数付きで実行。
ファイル操作	画像、PDF、テキストベースのファイルをアップロード。`/ls` でプロジェクトのファイルシステムを閲覧し、ファイルをダウンロード、または次のプロンプトにファイルを添付。
スケジュールタスク	1回限りまたは繰り返しのプロンプトを作成（`/task`、`/tasklist`）。繰り返しジョブは最低5分間隔で実行され、デフォルトで最大10件まで。
ステータスと通知	ピン留めされたメッセージでプロジェクト/ワークツリー、モデル、コンテキスト使用量、変更されたファイルを常に表示。バックグラウンドセッションの通知で分離されたセッションの状態を把握。
設定とローカライズ	`/settings` で実行時オプション（メッセージキュー、コンテキスト圧縮、STT など）をカスタマイズ。`BOT_LOCALE` で10言語に対応。
セキュリティ	ボットと通信できるのは、ホワイトリスト登録された Telegram ユーザーIDのみ。他のユーザーは無視される。
Docker とデーモンモード	OpenCode はホストに残したまま、コンテナ内でボットを実行する。または、組み込みデーモン（`opencode-telegram start --daemon`）を使用。

クイックスタート（導入フロー）

@BotFather で Telegram ボットを作成し、トークンをメモする。
@userinfobot で Telegram ユーザーIDを確認する。
同じマシン上で OpenCode サーバーを起動：opencode serve（デフォルトの API URL は http://localhost:4096）。
ボットを実行 – 最も簡単な方法はワンライナー：
```
npx @grinev/opencode-telegram-bot@latest
```
必要な環境変数が不足している場合、インタラクティブなウィザードがトークン、ユーザーID、API URL などを尋ね、プラットフォーム固有の設定ディレクトリに .env ファイルを生成する。
Telegram を開き、新しく作成したボットとチャットを開始し、プロンプトを送信し始める。

代替インストール – npm i -g @grinev/opencode-telegram-bot でグローバルインストール後、opencode-telegram start を実行。--daemon を指定して自己完結型のバックグラウンドプロセスを起動、またはドキュメントに記載の通り systemd/pm2/Docker に統合。

設定のハイライト

変数	意味	通常のデフォルト
`TELEGRAM_BOT_TOKEN`	BotFather から取得したトークン	必須
`TELEGRAM_ALLOWED_USER_ID`	あなたの数値型 Telegram ID	必須
`OPENCODE_API_URL`	ローカル OpenCode サーバーの URL	`http://localhost:4096`
`OPENCODE_MODEL_PROVIDER` / `OPENCODE_MODEL_ID`	モデルが選択されていない場合に使用するデフォルトモデル	`opencode` / `big-pickle`
`BOT_LOCALE`	UI 言語（`en`, `es`, `zh`, …）	`en`
`MESSAGE_QUEUE`（`/settings` で設定）	エージェントがビジー状態の間メッセージをキューにためる	デフォルトではオフ
`TASK_LIMIT`	同時実行可能なスケジュールタスクの最大数	`10`
`SCHEDULED_TASK_EXECUTION_TIMEOUT_MINUTES`	スケジュール実行が失敗と判断されるまでの待機時間	`120`

これらのすべては .env ファイルまたは実際の環境変数で指定可能。ウィザードは ~/Library/Application Support/opencode-telegram-bot/.env（macOS）、%APPDATA%\opencode-telegram-bot\.env（Windows）、~/.config/opencode-telegram-bot/.env（Linux）にファイルを書き込みます。

どんな人に向いているか？

すでにローカルで OpenCode を使っている開発者で、デスクトップから離れた状態でもコード作業を開始したい人。
迅速かつ安全なリモートインターフェースが必要なチームで、ポートを公開したり、完全な Web UI を構築したりしたくない人。
Telegram ボットのインタラクティブ性（インラインキーボード、ピン留めメッセージ、音声からテキスト変換など）を好むパワーユーザー。

制限事項 / README からの注意点

ボットは OpenCode サーバーが ボットと同じマシン上 で実行されている場合（または設定された OPENCODE_API_URL で到達可能な場合）にのみ動作します。
スケジュールタスクは常に build エージェントで実行されます。繰り返しジョブでは他のエージェントは現在サポートされていません。
npm パッケージは main ブランチに遅れをとる可能性があります。README に記載されている一部の機能は、最新リリース版には含まれていない場合があります。
ドキュメントアップロードの最大ファイルサイズは設定可能（CODE_FILE_MAX_SIZE_KB）ですが、この抜粋にはデフォルト値は記載されていません。

まとめ

OpenCode Telegram Bot は、OpenCode AI コーディングプラットフォームと Telegram の間の本格的で生産性の高いブリッジです。セキュアでポータブルな UI を提供し、リモートコード生成、セッション管理、自動化を可能にします。すべての処理はローカルで完結し、複数言語に対応し、Telegram のネイティブ機能（インラインキーボード、ピン留め、音声プロンプト、ファイルブラウズ）を活用できます。すでに OpenCode を AI ヘルプ付き開発に使っているなら、このボットでそのワークフローをスマートフォンに拡張でき、ネットワークポートを開くことなく実現できます。