telegram-tools

telegram-tools

コーディングエージェント向けの非公式 Telegram ツール：チャット、メッセージ、受信ファイル、送信、操作に対応します。

ハーネス	配布方法	固定方法
OpenCode V2	ネイティブプラグイン（npm パッケージ、スキル付き）	パッケージ内のバージョン
OpenCode V1	ネイティブプラグイン（npm パッケージ、スキルなし）	パッケージ内のバージョン
Claude Code	プラグイン：MCP サーバーとスキル	ref としてリリースタグ
Codex	プラグイン：MCP サーバーとスキル	ref としてリリースタグ
Grok Build	プラグイン：MCP サーバーとスキル	@ref としてリリースタグ
Antigravity	プラグイン：MCP サーバーとスキル	リリースタグのツリー URL
Hermes Agent	ネイティブプラグイン（Python、コマンドラインを呼び出す）	SHA としてリリースコミット
その他の MCP ホスト	npm からの MCP サーバー	パッケージ内のバージョン

ツールには Node.js 24 以降が必要です。 docs/conventions.md では、ツールの命名方法と動作について説明しています。

インストール

デフォルトブランチではなく、必ずリリースからインストールしてください。リリースとは、ビルド済みの dist/ を含むコミットに付けられたタグです。デフォルトブランチには dist/ がありません。以下のコマンドで、<version> はリリースのバージョン（1.2.3）、<sha> はそのタグが指すコミットです。

gh api repos/craft-agent/telegram-tools/commits/v<version> --jq .sha

OpenCode

OpenCode V2 では、パッケージとそのオプションを opencode.json に指定します。

{
  "plugins": [{ "package": "@craftsamo/telegram-tools@<version>", "options": { "read_only": false } }],
  "permissions": [{ "action": "telegram_*", "resource": "*", "effect": "ask" }]
}

OpenCode V1 では、パッケージを文字列として指定するか、オプションと組み合わせて指定します。

{
  "plugin": [["@craftsamo/telegram-tools@<version>", { "read_only": false }]],
  "permission": { "telegram_*": "ask" }
}

OpenCode では、ルール名のないあらゆるアクションが許可されるため、ルールで ask が指定されていない限り、プラグインのリクエストは通知なしで許可されます。読み取りツールでは確認を求めないため、telegram_* の glob は安全です。

V1 はスキルを登録しません。パッケージを展開し、skills/* フォルダーを ~/.config/opencode/skills/ にコピーしてください。

npm pack @craftsamo/telegram-tools@<version>
tar -xzf craftsamo-telegram-tools-<version>.tgz
mkdir -p ~/.config/opencode/skills
cp -r package/skills/* ~/.config/opencode/skills/
rm -rf package craftsamo-telegram-tools-<version>.tgz

Claude Code

claude plugin marketplace add craft-agent/telegram-tools#v<version>
claude plugin install telegram-tools@craft-agent

Codex

codex plugin marketplace add craft-agent/telegram-tools --ref v<version>
codex plugin add telegram-tools@craft-agent

Codex はサーバー名の - を _ に変換するため、ツールは mcp__telegram_tools__telegram_* として表示されます。MCP サーバーはプラグインのインストールディレクトリで起動されます。このディレクトリが呼び出し元の作業ツリーになることはありません。

Grok Build

grok plugin install craft-agent/telegram-tools@v<version> --trust

Grok はセッションの作業ディレクトリで MCP サーバーを起動します。

Antigravity

デフォルトブランチではなく、リリースタグのツリーからインストールしてください。デフォルトブランチにはビルド済みの dist/ がありません。Antigravity はタグを ~/.gemini/config/plugins/telegram-tools にクローンします。

agy plugin install https://github.com/craft-agent/telegram-tools/tree/v<version>

Hermes Agent

Hermes がインストールするのはタグではなくコミットで、プラグインは無効の状態でインストールされます。

hermes plugins install craft-agent/telegram-tools --ref <sha>
hermes plugins enable telegram-tools

Hermes ゲートウェイがすでに実行中の場合は、再起動してプラグインを読み込んでください（hermes gateway restart）。

プラグインは Hermes の起動時に見つかった Node を実行します。Hermes の実行中にバージョンマネージャーがそのバージョンを削除すると、呼び出し時に Node を再検索します。Node が見つからない場合は、node を実行できるシェルから Hermes を再起動してください。

その他の MCP ホスト

ホストの MCP 設定にサーバーを追加してください。フラグは args に指定します。

{
  "mcpServers": {
    "telegram-tools": {
      "command": "npx",
      "args": ["-y", "@craftsamo/telegram-tools@<version>", "--read-only"]
    }
  }
}

ツールとスキル

各ツールセットには、エージェントにツールの使い方を伝えるスキルが付属しています。スキルは、フロントマターの metadata でツールセットを指定します（ブロックとして記述する場合は metadata: { toolset: sends }）。OpenCode V2 と Hermes では、設定でそのツールセットのツールが少なくとも1つ登録されている場合に限り、スキルが登録されます。そのため、ツールセットを無効にしたプロファイルや、すべてのツールを削除したプロファイルでは、そのスキルは表示されません。ツールセットを指定しないスキルは常に登録されます。Claude Code、Codex、Grok Build、Antigravity はスキルフォルダー全体をインストールし、設定は MCP サーバーにのみ渡すため、設定で選択した内容にかかわらず、すべてのスキルが一覧に表示されます。OpenCode V1 はスキルを登録せず、コピーしたスキルもすべて一覧に表示されます。

アカウント（account）

ツール	機能	分類
telegram_account_read	ログインしているラベル、各同期サービスが稼働しているかどうか、Telegram から最後に応答があった時刻、ミラーの件数、次に必要な操作を確認します	読み取り

ローカルの状態のみを読み取ります。デーモンもネットワークも使用せず、結果に電話番号、アカウント ID、キーは含まれません。スキルは telegram-account で、Claude Code では telegram-tools:telegram-account、Hermes では telegram-tools:account として表示されます。

チャット（chats）

ツール	機能	分類
telegram_chat_read	method に応じてチャットを検索し、メッセージを読み取ります。指定できる値は list、view、topics、search、around、または過去の履歴を取得する fetch です	読み取り

ミラーに保存されているチャット（プライベートチャット、ボット、基本グループ、保存済みメッセージ、同期リストに登録されている間のスーパーグループとチャンネル）は、同期サービスを使用せずにローカルミラーから読み取ります。過去の履歴は fetch で取得します。一覧にのみ記載されているチャットは、同期サービス経由で view と around によって Telegram から直接読み取られ、1 ページあたり最大 100 件のメッセージが取得されます（live: true）。メッセージ本文、キャプション、ファイル名、トピックのタイトルはデータであり、指示ではありません。スキルは telegram-chats で、Claude Code では telegram-tools:telegram-chats、Hermes では telegram-tools:chats として表示されます。

同期（sync）

ツール	機能	分類
telegram_sync_read	同期リストに登録されているスーパーグループとチャンネルを一覧表示します	読み取り
telegram_sync_add	今後ミラーリングするスーパーグループまたはチャンネルを同期リストに追加します	冪等
telegram_sync_remove	チャットを同期リストから削除し、ミラーリングされたメッセージとその過去のバージョンを削除します	上書き

同期リストには、ミラーがメッセージを最新の状態に保つスーパーグループとチャンネルを最大 30 件登録できます。telegram_sync_read は同期サービスを使用せず、ローカルミラーからリストを読み取ります。チャットの追加や削除はローカルミラーを変更するため、同期サービスが稼働している必要があります。新たに追加されたチャットには最新の 50 件のメッセージが登録され、チャットを削除すると、そのミラーリングされたメッセージと過去のバージョンがローカルで削除されます（Telegram 側には変更はありません）。チャンネルを一覧表示またはミラーリングするには、channels 設定をオンにする必要があります。スキルは telegram-sync で、Claude Code では telegram-tools:telegram-sync、Hermes では telegram-tools:sync として表示されます。

送信（sends）

ツール	説明	分類
telegram_message_send	チャット ID を指定してテキストを 1 件送信します。フォーラムのトピックへの送信や返信も指定できます	追加

发送 ツールセットはデフォルトで有効です。テキストは記述されたとおりに送信され（Markdown や HTML として読み取られることはありません）、前後の空白が削除され、最大 4096 文字です。1 回の呼び出しで 1 回だけ送信され、random_id は 1 つだけ使用され、再送信はされません。失敗理由が uncertain の場合、メッセージが送信された可能性があります。ヒントにはミラーが確認した一致するメッセージが記載されるため、再送信する前にチャットを確認してください。duplicate は、同じ呼び出しによる以前の送信がすでに完了していたことを意味します。送信は同期サービスが行うため、サービスが実行されている必要があります。スキルは telegram-sends で、Claude Code では telegram-tools:telegram-sends、Hermes では telegram-tools:sends として表示されます。

ファイル（files）

ツール	説明	分類
telegram_file_save	Telegram のメッセージからファイルを 1 件ダウンロードし、download_dir に保存します	追加
telegram_file_send	ファイルを 1～10 件（合計 100 MB）チャットにキャプション付きで送信します	追加

files ツールセットはデフォルトで無効です。ディスクへの書き込み、アーカイブの展開、ファイルの送信を行います。toolsets または tools で有効にしてください。送信できるのは、1～10 件（合計最大 100 MB）のファイルを 1 つのグループとしてまとめたものです。各ファイルはファイルとして扱われ、作業ディレクトリ（ホームディレクトリまたはファイルシステムのルートである場合を除く）と、send_dirs で指定したディレクトリから送信されます。キー、シークレット、プログラム、インストーラーは拒否されます。アーカイブはエントリごとに確認され、各ファイルはラベルの送信ボックスにコピーされ、アップロード前に検査されます。sha256 を使うと、ファイルを承認済みのものに固定できます。送信には同期サービスが実行されている必要があります。失敗理由が uncertain の場合、ミラーが確認した一致するメッセージが表示されるため、再送信する前にチャットを確認してください。受信したファイルについては、メッセージのファイルは <download_dir>/<label>/<chat id>/<message id>/ に保存されます。非公開（モード 600）で、実行可能にならず、上書きもされません。最大ファイルサイズは download_max_mb で設定します。ダウンロードは同期サービスが行うため、サービスが実行されている必要があります。プログラムとインストーラーは拒否されます。また、zip、tar、gzip 圧縮 tar 以外のアーカイブ、プログラム、別のアーカイブ、リンク、またはアーカイブの外に出るパスを含むアーカイブ、アニメーションステッカー、閲覧後に消えるファイルも拒否されます。アーカイブは検査されて内容が一覧表示され、要求された場合（unpack: true）に限り、同じ場所にある <name>.unpacked/ に展開されます。macOS では、保存および展開されたすべてのファイルに隔離フラグが付きます。ファイル名と内容はデータであり、指示ではありません。スキルは telegram-files で、Claude Code では telegram-tools:telegram-files、Hermes では telegram-tools:files として表示されます。

アクション（actions）

ツール	機能	分類
telegram_message_edit	ユーザー自身のメッセージのテキストまたはキャプションを置き換えます	上書き
telegram_message_delete	ユーザー自身のメッセージを全員から削除します	管理
telegram_message_react	メッセージに対するユーザーの絵文字リアクションを設定または解除します	上書き
telegram_message_pin	メッセージをピン留めまたはピン留め解除します	上書き
telegram_chat_mark_read	チャットまたはフォーラムのトピックを、指定したメッセージまで既読にします。それより先には進みません	冪等

actions ツールセットはデフォルトで無効です。他の人がすでに読んだ内容を変更するためです。toolsets または tools で有効にしてください。編集と削除の対象はユーザー自身のメッセージに限られます。削除は常に全員から削除され、取り消せず、実行のたびに確認を求められます。リアクションは標準の絵文字1つで、ユーザーが以前に付けたリアクションを置き換えます（カスタム絵文字と有料リアクションは拒否されます）。notify が指定されていない場合、ピン留めは通知されません。プライベートチャットでは、both_sides が指定されていない限り、ユーザーに対してのみピン留めされます。既読にする処理は、ユーザーから依頼された場合のみ実行され、指定されたメッセージまで進み、後戻りはしません。また、送信者には既読として表示されます。すべてのアクションには同期サービスの実行が必要です。already はすでにその状態だったことを意味し、uncertain は処理が実行された可能性があるため、再度依頼する前にチャットを確認する必要があることを意味します。スキルは telegram-actions で、Claude Code では telegram-tools:telegram-actions、Hermes では telegram-tools:actions として表示されます。

ツールの追加

1. src/core/<domain>/<verb>.ts に defineTool を使って仕様を記述します。ID <prefix>_<domain>_<verb>、タイトルと説明、Zod の引数および出力スキーマ、ツールセットと書き込みクラス、execute(args, context) を指定します。書き込みツールには targets(args, context) も指定します。これは、その呼び出しが何に書き込むかを示すもので、権限ルールではその対象を指定する必要があります。
2. 仕様と同じ場所にテスト（<verb>.test.ts）を作成し、エントリーポイントと同様に invoke を通じて呼び出します。プログラムを実行するツールは、PATH 上に置いたそのプログラムのフェイクを使ってテストします。実際のサービスに接続するテストはありません。
3. src/tools.ts にツールを登録します。新しいツールセットは src/project.ts の toolsets に追加します（デフォルトで有効にする場合は defaultToolsets にも追加します）。また、設定以外にツールが読み取る変数があれば、toolVariables に追加します。
4. ツールセットのスキル skills/<prefix>-<toolset>/SKILL.md を追加または更新します。そのフロントマターでは、metadata の下にツールセットを指定します。
5. pnpm run build && pnpm run manifests を実行し、ツールを plugin.yaml に、変数を Codex のマニフェストに登録してから、「ツールとスキル」の下に説明を追加します。

各手順で従うルールについては、docs/conventions.md を参照してください。

読み取りと書き込み

すべての読み取りツールの名前は <prefix>_<domain>_read です。読み取りは確認なしで実行できます。書き込みはハーネスで確認されます。

ハーネス	確認なしで実行できる読み取り
OpenCode	常に実行できます。プラグインが確認するのは書き込みの前だけです。
Claude Code	~/.claude/settings.json の permissions.allow にある mcp__plugin_telegram-tools_telegram-tools__*_read ルール
Codex	常に実行できます。Codex は読み取りツールと同様に readOnlyHint を宣言しているツールを確認なしで実行します。
Grok Build	grok --allow 'MCPTool(telegram-tools__*_read)' --allow 'MCPTool(telegram_*_read)'（両方のルールが必要です。下記を参照してください）
Antigravity	読み取りツールごとに permissions.allow に設定する mcp(telegram-tools_telegram-tools/<tool id>) ルール
Hermes	常に実行できます。プラグインが確認するのは書き込みの前だけです。

書き込みの確認が求められる場合と、求められない場合は次のとおりです。

• OpenCode はルール名がなければどのアクションも許可するため、ルールで確認を求めない限り、書き込みは確認なしで実行されます。OpenCode の下に示されている telegram_* ルールを追加してください。
• Codex は codex exec の実行時に、また Grok Build は grok -p の実行時に、確認を求められない書き込みを拒否します。事前に許可されている場合を除きます。
• Grok Build は use_tool ツールを通じてプラグインのツールを呼び出しますが、エージェントはサーバー名を付けずにツール名を指定することがよくあります。Grok は指定された名前に対してルールを確認するため、最初の呼び出しではサーバー名を含むルールだけでは一致しません。2つ目のルールは短い名前に一致します。書き込みはいずれのルールにも一致しません。
• Antigravity は、ルールで許可されていないすべての MCP ツールについて、読み取りも含めて確認を求めます。また、プラグインのサーバー名を telegram-tools_telegram-tools（プラグイン名、続いてサーバー名）として指定します。agy -p は、確認を求められないツールを拒否します。
• Hermes の hermes chat -q は、確認を求められない書き込みを拒否します。hermes -z と --yolo は承認を省略するため、書き込みは確認なしで実行されます。

設定

すべてのエントリーポイントで同じ設定を使用します。フラグは環境変数より優先され、オプションまたは設定も変数より優先されます。

設定	フラグ	変数	意味
toolsets	--toolsets	TELEGRAM_TOOLS_TOOLSETS	有効にするツールセット、または all。デフォルトは src/project.ts の名前
read_only	--read-only	TELEGRAM_TOOLS_READ_ONLY	書き込みを行うツールを登録しません。他のすべての設定より優先されます
tools	--tools	TELEGRAM_TOOLS_TOOLS	ツールセットにかかわらず、ID を指定して追加する個別のツール
exclude_tools	--exclude-tools	TELEGRAM_TOOLS_EXCLUDE_TOOLS	ID を指定して除外する個別のツール。tools と toolsets より優先されます
confirm	--confirm	TELEGRAM_TOOLS_CONFIRM	MCP サーバーのみ：慣例に従い、harness（デフォルト）または elicitation
language	--language	TELEGRAM_TOOLS_LANGUAGE	ネイティブプラグインのみ：承認プロンプトの言語。例：ja
emoji	—	—	Hermes のみ：ツールセット名ごとに表示する、各ツールセットの横の絵文字（なしの場合は ""）
state_dir	--state-dir	TELEGRAM_TOOLS_STATE_DIR	各ラベルの状態を保存する場所。デフォルトは $XDG_STATE_HOME/telegram-tools
download_dir	--download-dir	TELEGRAM_TOOLS_DOWNLOAD_DIR	telegram_file_save が受信ファイルを保存する場所。メッセージごとにフォルダーを作成します。デフォルトは ~/Downloads/telegram-tools。ツールが読み取るため、サービスの再起動は不要です
download_max_mb	--download-max-mb <n>	TELEGRAM_TOOLS_DOWNLOAD_MAX_MB	ダウンロードできるファイルの最大サイズ（MB）。整数で 1～2000、デフォルトは 100。ツールが読み取るため、サービスの再起動は不要です
send_dirs	--send-dirs	TELEGRAM_TOOLS_SEND_DIRS	作業ディレクトリに加えて、ファイルの送信元として許可するディレクトリ。絶対パスで指定します。デフォルトはなし。ツールが読み取るため、サービスの再起動は不要です
keep_disappearing	--keep-disappearing	TELEGRAM_TOOLS_KEEP_DISAPPEARING	ユーザー向けに、消えるメッセージと一度だけ表示できるメッセージを保持します。デフォルトではオフです。sync と service install が読み取ります。変更後は service install を再実行してください
channels	--channels	TELEGRAM_TOOLS_CHANNELS	チャンネルの一覧表示、読み取り、ミラーリング、送信を行います。デフォルトではオフです。以下を参照してください。sync と service install が読み取ります。変更後は service install を再実行してください

フラグまたは変数でリストを指定する場合は、カンマ区切りにします。各ハーネスがリストを読み取るタイミング：

• OpenCode では、前述のプラグイン options を受け取り、リストは配列、read_only はブール値、state_dir と download_dir はパス、download_max_mb は数値、send_dirs はパスの配列として扱い、これらの値がない場合は環境変数にフォールバックします。V2 はプラグインをバックグラウンドサービス内で実行し、サービスの起動時の環境を保持します。opencode run の起動時に設定した環境変数は、その環境でサービスを再起動するまで反映されません（opencode service restart）。V1 はプラグインを独自のプロセスで実行します。

• Hermes では、config.yaml の plugins.entries.telegram-tools.settings を使用します。

  plugins:
    entries:
      telegram-tools:
        settings:
          read_only: false
          exclude_tools: []
  

  language の設定がない場合、承認カードは Hermes 自身の display.language（または HERMES_LANGUAGE）に従います。承認ボタンの言語にも従い、それ以外の場合は英語のままです。プラグインは、実行するコマンドラインに独自の環境を渡すため、環境変数も使用できます。実行中のゲートウェイは起動時の環境を保持するため、環境変数を変更した後は再起動してください（hermes gateway restart）。

• Claude Code、Grok Build、Antigravity はフラグなしでプラグインのサーバーを起動し、クライアントの環境を渡します。そのため、ハーネスの実行環境に環境変数を設定してください。

• Codex がプラグインの MCP サーバーに渡すのは、PATH や HOME などの基本的な環境変数と、プラグインのマニフェストに記載された環境変数（上記の環境変数）のみです。そのため、Codex の実行環境に設定してください。設定以外にツールが読み取る環境変数は、src/project.ts の toolVariables に追加します。pnpm run manifests を実行すると、設定用の環境変数の後にマニフェストへ追加されます。フラグを渡す場合や、パッケージに記載されていない環境変数をサーバーに渡す場合は、プラグインを使わず、Codex の config.toml で [mcp_servers] の下にサーバーを追加してください。フラグは args に指定し、env_vars には Codex の環境から転送する環境変数名を指定します。env には固定値を設定します。

  [mcp_servers.telegram-tools]
  command = "npx"
  args = ["-y", "@craftsamo/telegram-tools@<version>", "--read-only"]
  env_vars = ["TELEGRAM_TOOLS_TOOLSETS"]
  

アカウントと同期サービス

ツールは、mtcute を通じてユーザー自身のアカウントのデバイスとしてログインします。ログインには、my.telegram.org で登録した api_id と api_hash を使用します。他のクライアントのデータを読み取ることはありません。

• ログイン済みの各セッションにはラベルが付きます。 ラベルは小文字、数字、_ で構成し、長さは 1～24 文字です（ログイン時に名前を指定しない場合は default）。ツールの account 引数でラベルを選択します。ログイン済みのセッションが 1 つだけの場合は省略できます。
• 各ラベルの状態は 1 つのディレクトリに保存されます。 <state_dir>/<label>/（モード 700）には、セッションとアプリの認証情報、mtcute のストレージ、ミラー、サービスのソケット、転送中のファイルの一時コピーを格納する incoming/ があります。state_dir の既定値は $XDG_STATE_HOME/telegram-tools、または ~/.local/state/telegram-tools です。共有バックアップには含めないでください。セッションはあなたになり代わって読み書きします。
• 同期サービスは各ラベルの唯一の接続を保持し、ミラーを管理します。 ミラーに保持されているチャットはミラーから読み取ります。リストにのみ記載されているチャットは、サービスを通じてリアルタイムに読み取ります。履歴の取得は、サービスがチャットの追跡を開始した時点から始まります。fetch を使うと、それより古い履歴を追加できます。
• 新しいログインは他のデバイスに表示されます。 また、Telegram はアカウント設定で指定された期間使用されていないセッションを終了します。

ログインと同期サービスの実行

開始する前に、my.telegram.org（API 開発ツール）でアプリを登録し、api_id と api_hash を取得してください。ツールの実行には Node.js 24 以降が必要です。macOS と Linux に対応しています。

# Log in: on your phone, open Telegram > Settings > Devices > Link Desktop Device,
# and scan the QR code this prints.
telegram-tools-cli login --account work

# Start receiving at logon, and restart after a failure.
telegram-tools-cli service install --account work
telegram-tools-cli service status --account work

ラベルが 1 つだけの場合は --account を省略できます（login で新しいラベルを作成すると、名前は default になります）。すべてのコマンドで、ツールと同様に --state-dir を指定できます。

コマンド	動作
login [--account <label>] [--phone | --telethon]	QR コード（デフォルト）、電話番号とコード（--phone）、または Telethon v1 の文字列セッション（--telethon）でログインします
sync [--account <label>] [--keep-disappearing] [--channels]	同期サービスをフォアグラウンドで実行し、停止されるまで標準エラーにログを出力します
service install | uninstall | status [--account <label>]	同期サービスを launchd エージェント（macOS）または systemd ユーザーユニット（Linux）として登録するか、削除するか、状態を報告します
logout [--account <label>]	Telegram のセッションを終了してミラーを保持し、ローカルのセッションストレージを削除します
remove --account <label> [--yes]	--yes を指定するかラベルを再入力すると、サービスをアンインストールし、ラベルのディレクトリを完全に削除します

• ログイン：デフォルトでは、login は QR コードを表示します。スマートフォンの Telegram で「設定 → デバイス → デスクトップデバイスをリンク」に進み、QR コードをスキャンしてください。--phone を指定すると、電話番号とログインコードでログインします。--telethon を指定すると、Telethon v1 の文字列セッションをインポートします。ターミナルでは入力内容を表示せずに読み取り、または標準入力から読み取ります。アカウントで 2 段階認証パスワードを使用している場合、login は入力内容を表示せずにパスワードを求めます。環境変数に TELEGRAM_TOOLS_API_ID と TELEGRAM_TOOLS_API_HASH が設定されている場合はそれらを使用します。設定されていない場合、login はそれらの入力を求め（ハッシュは入力内容を表示しません）、<state_dir>/<label>/app.json に保存します（モード 0600）。
• サービスの動作：初回起動時、サービスはチャットリストを取得し、過去 30 日間にアクティブだったチャットの最新 50 件のメッセージを、フラッド制限を避けるよう間隔を空けながら少しずつ取得して初期データとして保存します。その後、更新が届くたびにミラーへ保存し、30 分ごとにチャットリストを更新し、メッセージ履歴の欠落を補います。スーパーグループとチャンネルがミラーリングされるのは同期リストにある間のみで（最大 30 件）、チャンネルの場合は channels 設定も有効にする必要があります。
• ログの保存先：macOS では、サービスのログは service install が表示する ~/Library/Logs/io.github.craft-agent.telegram-tools/<label>.log に書き込まれます。Linux では、systemd のユーザージャーナルに記録されます（service status に表示されるとおり、journalctl --user -u <unit> で確認できます）。ログアウト後もサービスを実行し続けるには、loginctl enable-linger を実行してください。
• macOS では、ログイン項目にサービスが telegram-tools-sync-<label> として表示されます：エージェントはそのランチャースクリプト経由で起動します。このスクリプトは service install によって ~/Library/Application Support/io.github.craft-agent.telegram-tools/ に書き込まれ、service uninstall によって削除されます。そこで項目をオフにすると同期が停止します。
• サービスの更新と再起動：service install はこのパッケージと Node の実行ファイルのパスを記録します。そのため、どちらかを更新した場合や、keep_disappearing または channels を変更した場合は、再度 service install を実行してください。バージョンマネージャーの配下など、Node のパスにバージョン番号が含まれる場合、service install は同じ Node を起動する、バージョン番号を含まない PATH 上の node を記録し、該当するものがない場合は警告します。その node は、バージョンマネージャーが現在のものとして選択する Node を実行します。このバージョンでサービスをインストールした後は、記録されたプログラムがなくなった場合に service status と telegram_account_read がその旨を通知します。サービスは障害発生から 1 分後に再起動しますが、Telegram によってセッションが終了された場合は停止したままになります。
• ラベルごとに 1 つの接続：Telegram は、同時に 2 か所から接続した認証キーを無効にすることがあります。サービス実行中は login、logout、remove を実行できません。先にサービスを停止してください（service uninstall を実行するか、フォアグラウンドの sync を停止します）。
• ログアウトと削除：logout は Telegram 上のセッションを終了し、ミラーは残してセッションストレージのみを削除します。remove はサービスをアンインストールし、ラベルのディレクトリを完全に削除します。macOS ではサービスのログも削除されます（service uninstall ではログは残ります）。Linux では、ジャーナルにサービスのログが残ります。Telegram に接続できない場合、セッションはローカルで削除されます。その場合は Telegram の「設定 → デバイス」からセッションを終了してください。
• デバイスのセッション：新しいログインは、ほかのデバイスに表示されます。Telegram は、「設定 → プライバシーとセキュリティ → 『不在の場合』」で設定した期間使われていないセッションを終了します。その場合は再度ログインしてください。telegram_account_read を使うと、各ラベルに必要な手順をエージェントに知らせることができます。

非公式であること、およびTelegramの規約について

このパッケージはTelegramによって作成も承認もされていません。独自のアプリを登録し （API規約 §2.1）、パッケージと、サービスへの ログイン時に使用されるデバイス名によって、非公式であることが識別されます（§2.2、§2.3）。

• Telegramの規約では、プラットフォームのデータをAIに使用することが禁じられています。 §1.5では、プラットフォームのデータをAIの トレーニングやデプロイに使用することを禁じています。広く解釈すれば、エージェントが 自分のチャットを読むことも対象になります。非公式クライアントは監視されており、悪用すると アカウントが一時凍結または永久凍結されることがあります。
• keep_disappearing と channels はデフォルトで無効です。 消えるメッセージを 保持することは§1.4に違反します。有効にすると、同期サービスは消えるメッセージ、 1回限り表示されるメッセージ、自動消去メッセージのファイルも、届いた時点で保持します （各最大100 MB。プログラムやアーカイブは対象外）。そのため、Telegramから削除された後でも telegram_file_save で保存できます。無効にすると、サービスの次回起動時にそれらのファイルが 削除されます。チャンネルについては、API規約§3.3により、チャンネルのコンテンツを表示する アプリはスポンサー付きメッセージを表示するよう求められています。スポンサー付きメッセージは 取得も表示もされません（信頼できないプロンプトがモデルに届くのを防ぐためです）。 channels を有効にしたユーザーは、§3.3に伴うリスクを受け入れることになります。 channels が無効の場合、チャンネルは一覧表示、閲覧、ミラーリング、同期リストへの登録が されず、同期サービスは次回起動時に、ミラーからすべてのチャンネルとミラーリング済みの メッセージを削除します。

構成

• src/project.ts — パッケージ名、ツールIDのプレフィックス、設定のプレフィックス、 ツールセット、およびツールが読み取るその他の変数。
• src/core/ — ハーネスやプロジェクト名に依存しない、ツールのコントラクトとツール群。
• src/tools.ts — すべてのツールの一覧。各エントリーポイントがここにある各ツールを登録します。
• src/words.ts — ツールの文言を言語ごとに翻訳したもの。ネイティブプラグインが承認プロンプトで使用します。
• src/mcp/ — MCP サーバー。dist/mcp.js にビルドされ、telegram-tools で実行されます。
• src/opencode/ — OpenCode プラグイン。dist/opencode.js にビルドされます。
• src/cli/ — Hermes プラグインが呼び出すコマンドライン。dist/cli.js にビルドされ、 telegram-tools-cli で実行されます。
• src/hermes/、plugin.yaml、__init__.py — Hermes プラグイン。
• skills/ — ツールセットごとに1つのスキルがあり、skills/<name>/SKILL.md に格納されています。 スキルに対応するすべてのハーネスは、パッケージまたはプラグインのルートから読み込みます。 ネイティブプラグインが読み込むのは、有効になっているツールセットのスキルだけです。
• .claude-plugin/、.codex-plugin/、.agents/plugins/、.mcp.json、 .antigravity-plugin/、mcp_config.json — その他のハーネス用プラグインマニフェストです。 Codexは.codex-plugin/plugin.jsonを読み込みます。ルートにplugin.jsonがあると、 プラグインがAgent Pluginとして読み込まれ、ツールの上限により、一定のサイズを超えたツールが 表示されなくなります。ルートの.mcp.jsonはGrok Buildが読み込む設定です （${CLAUDE_PLUGIN_ROOT}はGrok BuildとClaude Codeの両方が展開する変数です）。 Claude Codeでこのリポジトリを作業する際は、そのファイルから提示されるプロジェクトのMCP サーバーを 使用しないでください。

リリースの手順についてはRELEASING.mdを参照してください。

ライセンス

AGPL-3.0 with Commons Clause