grinev/opencode-telegram-bot

OpenCode Telegram Bot – その概要

OpenCode Telegram Bot は、Telegram チャットから OpenCode AIコーディングアシスタント（ローカルCLIツール）を制御できる Node.js アプリケーションです。OpenCode サーバーと同じマシン上で動作し、Telegram の Bot API と通信するため、インターネットにポートを開放する必要はありません。

主な機能

• リモートプロンプト – テキスト、音声、ファイルをボットに送信すると、OpenCode がコードを生成し、Telegram ファイルとして返します。
• セッション管理 – チャットコマンドから直接、OpenCode セッションの作成、切り替え、中断、切り離しが可能。
• ライブ追跡 – 実行中の OpenCode セッションを追跡し、進捗状況、サブエージェントの活動、モデルの使用状況をリアルタイムで表示します。
• モデルとエージェントの切り替え – お気に入りのモデルを選択したり、Plan モードと Build モードをその場で切り替えたりできます。
• ファイルブラウザ – /ls を使用してプロジェクトのディレクトリツリーを探索し、ファイルをダウンロードしたり、次のプロンプトに添付したりできます。
• スケジュールタスク – 後で実行したり、定期的に実行するプロンプトを事前に定義できます。
• 音声入力 – オプションの Whisper 互換の音声認識機能。
• セキュリティ – 指定した Telegram ユーザー ID のみがボットと対話できます。
• ローカリゼーション – UI は12言語に対応。
• Docker サポート – OpenCode サーバーをホストに置いたまま、コンテナ内で実行できます。

導入方法

1. Telegram ボットを作成 @BotFather でトークンを取得します。
2. OpenCode をインストール（AIコーディング CLI）してサーバーを起動します（opencode serve）。
3. ボットをインストール npm（npx @grinev/opencode-telegram-bot@latest またはグローバルインストール）でインストールし、対話式ウィザードを実行します。ウィザードでは、ボットトークン、Telegram ユーザー ID、OpenCode のバージョン（V1 または V2）、API URL、資格情報を尋ねられます。
4. ボットとチャット – ブロッキング操作（メニューなど）がアクティブでない限り、プレーンテキストメッセージはすべてプロンプトになります。

主な Telegram コマンド（抜粋）

コマンド	機能
/status	ボットのバージョン、サーバーの健全性、現在のプロジェクト、セッション、モデルを表示
/new	新しい OpenCode セッションを開始
/abort	現在のタスクをキャンセル
/sessions	最近のセッションを閲覧・切り替え
/ls	対話式ファイルブラウザ
/settings	実行時設定を調整
/task / /tasklist	スケジュール済みプロンプトの作成と管理
/opencode_start / /opencode_stop	Telegram からローカルの OpenCode サーバーを制御

設定

• 環境変数または .env ファイル（OS固有のアプリデータフォルダに保存）で、ボットトークン、許可ユーザー ID、プロキシ設定、OpenCode サーバー URL、バージョン、オプションの制限（例：TASK_LIMIT）を指定できます。
• <appHome>/local-commands/ に配置したローカル JSON コマンドファイルは、ホスト上で任意のシェルコマンドを実行するカスタム /command ショートカットになります。

対象ユーザー

すでに OpenCode を AI 支援コーディングに使用しており、サーバーがローカルで実行されている間に、スマートフォンから便利かつ安全に操作したい開発者向けです。これはスタンドアロンの AI モデルではなく、既存の OpenCode サービスにコマンドを転送するシンクライアントです。

---

上記の詳細はすべて、リポジトリの README から直接取得しています。