Claude Code

Claude Code Channels で Telegram から Claude とやり取りしよう！ステップバイステップ設定ガイド

2026-03-23
43分で読了
更新: 2026-07-28
한국어 | Deutsch | English
hf_20260322_211039_b35c7222-94da-4dae-8c53-57b7f2f8473d.webp

目次

ターミナルの前にいなくても、スマホから Claude Code にメッセージを送れたら便利だと思いませんか？僕もそういった環境を目指すべく、自分で Discord と連携する環境を作ってはみたものの、あまり納得のいくものにはなっていませんでした。しかし、2026年3月にリサーチプレビューとして公開された Claude Code Channels を使えば、それが簡単に実現できます！

この記事では、チャットアプリ Telegram を使って Claude Code Channels を設定する手順を、ゼロからわかりやすく解説していきます。

2026年7月25日追記: 公開後に仕様がいくつか変わっていたため、公式ドキュメントと照らし合わせて全体を見直しました。主な変更点は、API キー認証への対応、iMessage チャネルの追加、そして権限プロンプトをスマホから承認できる「権限リレー」の追加です。変更箇所は本文中に反映しています。

2026年7月28日追記: 数か月運用してわかった注意点をまとめた「運用してわかったこと」の章を追加しました。1つの Bot につながるセッションは1つだけであること、プラグインを user スコープで有効にすると --channels を付けていないセッションでもポーリングのプロセスが起動すること、その対策としてのチャンネル専用ディレクトリ構成を解説しています。

Claude Code Channels とは

Claude Code Channels は、外部からの通知やメッセージを、動作中の Claude Code セッションにリアルタイムで届ける仕組みです。技術的には MCP（Model Context Protocol）サーバーとして動作し、Claude Code のサブプロセスとして起動します。

たとえば、こんな使い方ができます。

  • チャット連携: Telegram や Discord からメッセージを送ると、ローカルで動いている Claude Code がそれを受け取って作業してくれる
  • Webhook 連携: CI/CD の結果やモニタリングのアラートを Claude Code に直接流し込んで、自動で対応させる

一方通行（通知を送るだけ）にも、双方向（Claude が返信もする）にも対応しています。チャットアプリとの連携では、スマホでメッセージを送って、Claude が作業した結果をそのチャットに返してくれるという双方向のやり取りが可能です。

ひとつ押さえておきたいのは、イベントが届くのは セッションが開いている間だけ という点です。常時受け付けたい場合は、Claude Code をバックグラウンドプロセスや常駐させたターミナルで動かしておく必要があります。

なぜ Telegram を選んだのか

リサーチプレビューでサポートされているチャネルは、Telegram・Discord・iMessage の3つです。加えて、ローカルで動くデモ用の fakechat も用意されています（後述します）。今回は Telegram を選びました。その理由をいくつか挙げてみます。

1. Bot の作成がとにかく簡単

Telegram では「BotFather」という公式 Bot にメッセージを送るだけで、ものの数分で新しい Bot を作れます。開発者ポータルにログインしてアプリケーションを作成して…といった手順が不要なので、気軽に試せるのが魅力です。

2. スマホからの操作と相性が抜群

Telegram はモバイルアプリの動作が軽快で、どこからでもサクッとメッセージを送れます。出先でふと「あのファイルの内容を確認したい」「テストを走らせておきたい」と思ったとき、ポケットのスマホから Claude Code に指示を飛ばせるのは大きなメリットです。

3. セットアップ手順がシンプル

Discord の場合は、Developer Portal でアプリケーションを作成して、Message Content Intent を有効にして、権限を細かく設定して、サーバーに招待して…とステップが多くなりがちです。Telegram なら BotFather でトークンを取得するだけで準備完了なので、Channels の動作を素早く体験できます。

なお、iMessage チャネルは Bot トークン自体が不要で、macOS の Messages データベースを直接読む仕組みです。macOS を使っていて Apple ID で完結させたい方は、そちらも選択肢になります。ただしフルディスクアクセスの許可が必要です。

4. Claude Code 専用として切り分けられる

僕はそれまで Telegram をインストールすらしていなかったので、逆にそれが好都合でした。他の用途で通知が来ることがなく、Telegram を開けば Claude Code の通知だけ、という完全な専用チャンネルとして使えます。

それでは、実際にセットアップしていきましょう！

前提条件

セットアップを始める前に、以下の準備が整っていることを確認してください。

  • Claude Code v2.1.80 以降（--channels が入ったバージョン）。ただし、後述する権限リレーは v2.1.81、Console の API キー認証での利用は v2.1.128、権限リレーの表示を安全に扱う修正は v2.1.211 で入っています。できるだけ新しいバージョンを使うのが確実です
  • claude.ai アカウント、または Claude Console の API キー で認証されていること
  • Bun がインストールされていること（公式チャネルプラグインの実行に必要です）
  • Telegram アカウント を持っていること
  • Team / Enterprise プランの場合は、組織の Owner が Channels を有効にしていること

認証まわりは公開当初から変わった部分です。当初は claude.ai アカウントのみでしたが、v2.1.128 以降は Console の API キー認証でも利用できます。一方で、Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry 経由では利用できません。

組織で使う場合の扱いは、認証方法によって既定値が異なります。

  • claude.ai の Team / Enterprise: 既定ではブロックされており、Owner が Admin settings の Claude Code から有効にするか、マネージド設定で channelsEnabled を true にする必要があります
  • Console の API キー認証: 既定で許可されています。マネージド設定を配布している組織の場合のみ、channelsEnabled の設定が必要です
  • 組織に属していない Pro / Max ユーザー: このチェック自体が不要です

管理者はさらに allowedChannelPlugins で、どのプラグインをチャネルとして登録できるかを制限できます。

Bun がまだの方は、以下のコマンドで簡単にインストールできます。

curl -fsSL https://bun.sh/install | bash

インストール完了後、そのまま bun --version を実行すると command not found になることがあります。これはインストーラーが ~/.zshrc にパスを追加してくれるものの、現在のシェルにはまだ反映されていないためです。以下のどちらかを実行すれば使えるようになります。

# 方法1: 現在のシェルを再起動する（インストーラーの案内にも表示されます）
exec /bin/zsh

# 方法2: .zshrc を手動で再読み込みする
source ~/.zshrc

パスが通ったら、バージョンを確認しておきましょう。

bun --version

Step 1: Telegram Bot を作成する

まずは Telegram 側で Bot を用意します。

  1. Telegram アプリを開きます。初めて使う場合は、電話番号の認証などの初期セットアップを済ませてください。
  2. 画面下部の検索バー（虫めがねアイコン）をタップして、「BotFather」と入力します。検索結果に青いチェックマーク付きの「BotFather」が表示されるので、それをタップしてチャット画面を開きます。もし検索で見つからない場合は、ブラウザで BotFather のチャットページ にアクセスすると、直接 BotFather のチャットを開けます。
  3. BotFather とのチャットを開いたら、Start ボタンをクリックして /newbot とメッセージを送信します。
  4. Bot の「表示名」を聞かれるので、好きな名前を入力します（例: My Claude Bot）。
  5. 次に「ユーザー名」を聞かれます。これは bot で終わる必要があります（例: my_claude_code_bot）。
  6. 作成が完了すると、Bot トークンが表示されます。110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw のような長い文字列です。これを控えておいてください。

注意: Bot トークンは秘密情報です。他人に共有したり、公開リポジトリにコミットしたりしないでください。

Step 2: Telegram プラグインをインストールする

次に、Claude Code のセッション内で Telegram のチャネルプラグインをインストールします。

Claude Code を起動して、以下のコマンドを実行してください。

/plugin install telegram@claude-plugins-official

Marketplace "claude-plugins-official" not found というエラーが出た場合は、先にマーケットプレイスを登録します。

/plugin marketplace add anthropics/claude-plugins-official

マーケットプレイスはあるのにプラグインが見つからないと言われた場合は、手元のマーケットプレイス情報が古くなっています。次のコマンドで更新してから、もう一度インストールを実行してください。

/plugin marketplace update claude-plugins-official

インストール時にスコープを聞かれたら、公式ドキュメントでは user スコープ が推奨されています。こうしておくと、どのプロジェクトで Claude Code を起動しても Telegram チャネルを使えます。

ただし、user スコープで有効にすると、--channels を付けていないセッションでも Telegram をポーリングするプロセスが起動する、という副作用があります。まず試す段階では user スコープで問題ありませんが、日常的に使い始めたら後述の「運用してわかったこと」の構成に移行するのがおすすめです。

インストールが完了したら /reload-plugins を実行します。これで /telegram:configure などのコマンドが有効になります。

僕が3月に試したときは /reload-plugins では /telegram:configure が現れず、/exit でセッションを入り直す必要がありました。現在は公式手順どおり /reload-plugins で認識されます。それでもコマンドが見つからない場合は、一度セッションを終了して入り直してみてください。

Step 3: Bot トークンを設定する

Step 1 で取得した Bot トークンを Claude Code に登録します。以下のコマンドで設定してください。<token> の部分を実際のトークンに置き換えます。

/telegram:configure <token>

トークンは ~/.claude/channels/telegram/.env に保存されます。Claude Code を起動する前に、シェルの環境変数 TELEGRAM_BOT_TOKEN として設定しておく方法でも構いません。

なお /telegram:configure は引数なしで実行すると、トークンの設定状況やアクセスポリシー、承認待ちのペアリングといった現在の状態を確認できます。設定が済んだあとの確認にも使えます。

トークンを反映するために再び /exit でセッションを終了します。

Step 4: Channels を有効にして Claude Code を再起動する

トークンの設定ができたら、一度 Claude Code を終了して、--channels フラグ付きで再起動します。このフラグは「このチャネルからのメッセージを、このセッションに取り込んでよい」という許可を与えるスイッチです。フラグを付けていないセッションには、Bot にメッセージを送っても届きません。

claude --channels plugin:telegram@claude-plugins-official

僕は --dangerously-skip-permissions を付けて使っていますが、それについてはご自身の判断でお願いします。

claude --dangerously-skip-permissions --channels plugin:telegram@claude-plugins-official

後述する権限リレーが追加されてからは、権限の確認をスマホ側で承認できるようになりました。このフラグを付けなくても外出先で作業を進められるので、まずはフラグなしで試してみるのが良いと思います。

起動すると、Telegram プラグインが自動的にサブプロセスとして立ち上がり、Bot へのメッセージをポーリング（定期的にチェック）し始めます。起動画面には、指定したチャネルからのメッセージがこのセッションに直接届くという注意書きが表示されます。プラグインが未インストールだったり許可リストに載っていなかったりする場合は、その下に理由を示す警告が出ます。

複数のチャネルを同時に使いたい場合は、--channels にスペース区切りで並べて渡せます。

なお --channels は、リサーチプレビューの間は claude --help の一覧に表示されません。表示されなくてもフラグは機能しますので、そのまま使って大丈夫です。

Step 5: アカウントをペアリングする

セキュリティのために、最初に自分の Telegram アカウントと Claude Code セッションを紐づけ（ペアリング）する作業が必要です。Telegram プラグインの初期状態は pairing ポリシーになっており、知らない送信者からの DM にはペアリングコードを返してメッセージ自体は破棄する、という動作をします。

  1. Telegram アプリで、Step 1 で作成した Bot を、BotFather の最後のメッセージに書いてあるリンクから開き、OK をタップします。
  2. Bot に何かメッセージを送ります（「hello」など何でも OK です）
  3. Bot がペアリングコードを返信してきます

Bot が反応しない場合は、Claude Code が --channels 付きで起動しているか確認してください。Channel が有効なセッションが動いていないと、Bot は応答できません。

  1. Claude Code のターミナルに戻り、以下のコマンドでペアリングを完了させます。<code> の部分は Bot から受け取ったコードに置き換えてください。
/telegram:access pair <code>
  1. 最後に、アクセスポリシーを設定して、自分以外のユーザーからのメッセージをブロックします。
/telegram:access policy allowlist

これで、自分の Telegram アカウントだけが Claude Code にメッセージを送れる状態になりました。pairing はあくまで、まだ知らないユーザー ID を捕まえるための一時的な状態です。必要な人を登録し終えたら allowlist に切り替えておきましょう。

アクセス設定は ~/.claude/channels/telegram/access.json に保存されます。サーバーはメッセージを受け取るたびにこのファイルを読み直すので、設定を変えても再起動は必要ありません。

よく使うコマンドをまとめておきます。

コマンド内容
/telegram:access現在のポリシー、許可リスト、承認待ちのペアリング、有効なグループを表示
/telegram:access pair <code>ペアリングコードを承認して許可リストに追加
/telegram:access deny <code>承認待ちのコードを破棄（送信者には通知されません）
/telegram:access allow 412587349ユーザー ID を直接追加
/telegram:access remove 412587349許可リストから削除
/telegram:access policy allowlistDM ポリシーを変更（pairing / allowlist / disabled）

Telegram はユーザー名ではなく数値のユーザー ID で人を識別します。ユーザー名は変更できてしまうためです。ペアリングを使えば ID は自動で取得されますが、手動で調べたい場合は @userinfobot にメッセージを送ると教えてくれます。

使ってみよう！

セットアップが完了したので、早速使ってみましょう。Telegram アプリを開いて、Bot にメッセージを送ります。

今のワーキングディレクトリにあるファイルを教えて

これで現在のセッションのワーキングディレクトリのパスを Telegram に答えてくれるハズです。

メッセージが Claude Code セッションに届くと、Claude はそれに基づいてファイルを読んだり、コマンドを実行したりします。処理結果は Telegram のチャットに返信として届きます。

ターミナル側では、受信したメッセージと、返信のためのツール呼び出し（「sent」という確認）が表示されます。実際の返信テキストは Telegram 側に表示される仕組みです。

権限プロンプトをスマホから承認する（権限リレー）

この記事を最初に書いた時点では、Claude Code が権限を必要とする操作をしようとすると、ターミナルの確認プロンプトでセッションが止まってしまい、外出先ではどうにもできませんでした。その後 v2.1.81 で権限リレーという仕組みが追加され、この問題が解決しています。

権限リレーに対応したチャネルでは、ターミナルに出るのと同じ確認プロンプトが、チャットアプリ側にも同時に届きます。Telegram プラグインは対応済みなので、追加の設定なしで使えます。

最初に届くのは 🔐 Permission: <ツール名> という1行だけで、See more・Allow・Deny の3つのボタンが付いています。操作の説明と実際の引数のプレビューは、See more をタップして初めて展開されます。

ここは気をつけたいところです。通知から反射的に Allow を押すと、実行されるコマンドの中身を一度も見ないまま承認できてしまいます。Bash の実行など、内容を確かめてから判断したい場面では See more を開いてください。

ターミナル側の確認ダイアログも開いたままになっていて、先に答えたほうが採用される仕組みです。手元に戻ってターミナルで承認すれば、スマホ側の保留は破棄されます。

なお、公式ドキュメントのチャネル実装ガイドには、yes <ID> / no <ID> とテキストで返信して承認する方式が出てきます。Telegram プラグインにもこの形式を解釈するコードは入っているのですが、この ID（5文字の英小文字）はボタンの内部データにしか埋め込まれておらず、チャット上には表示されません。そのため実際には ID を知る手段がなく、ボタンで操作することになります。自分でチャネルを実装する場合は、プロンプト本文に ID を含めておく必要があります。

ただし、すべてのプロンプトがリレーされるわけではありません。リレーの対象は Bash・Write・Edit といったツール実行の承認で、プロジェクトの信頼確認や MCP サーバーの利用同意といったダイアログはターミナルにしか表示されません。

注意: 権限リレーは、チャネル経由で返信できる人なら誰でもツールの実行を承認・拒否できることを意味します。許可リストには、その権限を任せて構わない相手だけを登録してください。

知っておくと便利な機能

セットアップが済んだあとに使える機能もいくつかあります。

画像の送信

Telegram で写真を送ると、プラグインがローカルに自動でダウンロードし、Claude がそのファイルを読めるようになります。エラー画面のスクリーンショットを撮って送り、そのまま調べてもらうといった使い方ができます。

リアクションとメッセージ編集

Claude はメッセージに絵文字リアクションを付けたり、送信済みのメッセージを編集したりできます。長い処理の途中経過を、メッセージを書き換える形で知らせることが可能です。

ただし、メッセージの編集ではプッシュ通知が鳴りません。途中経過は編集で更新しつつ、処理が終わったことを知らせるときは新しいメッセージとして送る、という使い分けになります。プラグイン側も Claude にそう指示しているので、通常はこの動きになります。

受信時に自動でリアクションを返す設定もあります。「受け取りました」の合図になるので、設定しておくと安心感があります。

/telegram:access set ackReaction 👀

リアクションに使える絵文字は Telegram 側で決められた一覧に限られており、それ以外を指定しても何も起きません。

グループチャットでの利用

DM だけでなく、グループチャットでも使えます。ただし既定では無効なので、グループごとに個別に許可します。

/telegram:access group add -1001654782309

グループ ID は -100 で始まる負の数値です。既定では Bot がメンションされたときか、Bot のメッセージへの返信のときだけ反応します。すべてのメッセージに反応させたい場合は --no-mention を付けますが、あわせて BotFather で /setprivacy を実行し、プライバシーモードを Disable にする必要があります。この設定をしないと、Telegram 側でメッセージがフィルタされて手元まで届きません。

グループ内で反応できるメンバーを絞りたい場合は --allow にユーザー ID を並べます。また mentionPatterns に正規表現を登録しておくと、@ 付きのメンションでなくてもトリガーにできます。

/telegram:access group add -1001654782309 --allow 412587349,628194073
/telegram:access set mentionPatterns '["^hey claude\\b"]'

制約

  • Bot は届いたメッセージしか見えません。過去のやり取りを遡って取得する手段はありません
  • 添付ファイルは1つあたり最大 50MB です
  • Telegram は 4096 文字を超えるメッセージを受け付けないため、長い返信は自動的に分割して送られます

セキュリティについて知っておきたいこと

Channels を使う上で、セキュリティ面でいくつか押さえておきたいポイントがあります。

送信者の許可リスト

Telegram チャネルプラグインは、ペアリング済みのアカウントからのメッセージだけを受け付けます。許可リストに載っていない送信者からのメッセージは無視されます。これにより、第三者が Bot 経由で Claude Code に不正な指示を送り込むこと（プロンプトインジェクション）を防いでいます。

セッション単位の有効化

.mcp.json にサーバーが登録されているだけでは、メッセージは届きません。--channels フラグで明示的に有効化したセッションでのみ、Claude Code Channels が機能します。

許可リストの範囲

送信者の許可リストは、メッセージの受け付けだけでなく、前述の権限リレーの入り口も兼ねています。チャネル経由で返信できる人は、そのセッションでのツール実行を承認できてしまいます。許可リストに追加するのは、そこまで任せられる相手だけにしてください。

権限プロンプトへの注意

Claude Code がファイルの編集やコマンドの実行など、権限が必要な操作を行おうとすると、ターミナルに確認プロンプトが表示されます。権限リレーがあるので外出先からでも承認できますが、それでもプロンプト自体はセッションを一時停止させます。

完全に無人で動かしたい場合は --dangerously-skip-permissions フラグがありますが、名前の通り危険を伴うオプションです。信頼できる環境でのみ使用してください。なお、このフラグを付けても、明示的な ask ルール、組織が ask に設定したコネクタツール、requiresUserInteraction が指定された MCP ツールは、それでも確認を求めてきます。

-p を使った非対話モードで Channels を動かす場合は、選択式の質問やプラン承認といった端末入力を必要とするツールが無効化されるため、入力待ちでセッションが固まることはありません。

運用してわかったこと（2026年7月28日追記）

ここからは、数か月使ってきて気づいた、セットアップガイドだけでは見えてこない挙動の話です。複数のセッションを開きながら使う方は、この章にも目を通しておくことをおすすめします。

1つの Bot につながるセッションは1つだけ

Telegram の Bot API では、メッセージを受信する getUpdates を同じトークンで同時に呼べるのは実質1プロセスだけで、2つ目からは 409 Conflict エラーが返ります。そして Channels の仕組み上、チャネルの MCP サーバーはセッションの子プロセスとして動きます。この2つを合わせると、1つの Bot とやり取りできるセッションは1つだけ、という結論になります。複数のセッションにメッセージを振り分けるような仕組みは、現時点の Claude Code にはありません。

では、すでに Bot とつながっているセッションがあるところへ、Telegram プラグインを読み込んだ別のセッションを起動するとどうなるか。Telegram プラグインは「後勝ち」で、新しいセッションが既存のポーリングプロセスを停止させて Bot を引き継ぎます。このとき、先に動いていたセッションのターミナルに目立った通知は出ません（少なくとも僕が体験した範囲では、気づけませんでした）。「さっきまで返事が来ていたのに急に無反応になった」というときは、まずこれを疑ってください。

なお Discord プラグインは逆の挙動で、先に接続したセッションが優先され、後から起動したセッションが受信できなくなるという報告が出ています（Issue #56109。重複としてクローズされていますが、症状の報告として参考になります）。こちらは僕自身では未検証です。

user スコープで有効にすると全セッションでプロセスが起動する

もうひとつは --channels フラグの意味の話です。このフラグが制御しているのは「チャネルからのメッセージをセッションに取り込むかどうか」だけで、ポーリングのプロセス自体は、プラグインが有効になっているセッションなら必ず起動します。つまり Step 2 で user スコープを選んでいると、--channels を付けていない普段のセッションを開くたびに、裏で Telegram をポーリングする bun のプロセスが立ち上がっているわけです。Issue #38098 で報告されている挙動で、手元の v2.1.220 でも同じことを確認しました。

セッションが増えるたびに Bot の「後勝ち」の奪い合いが起きるだけでなく、セッションを閉じたあともプロセスだけが残ることがあります。僕の環境では、起動元のセッションがとっくに消えているのに25日間動き続けていたプロセスが見つかりました。メモリを 130MB ほど抱えたままです。名誉のために補足すると、これは古い版のプラグインが動き続けていた個体だと思われます。現行のプラグインには終了処理や孤児検出が実装されているので、残留は起きにくくなっているはずですが、確認はしておいて損はありません。

ps -eo pid,ppid,etime,command | grep -E "[c]laude-plugins-official/telegram|[b]un server\.ts"

現役のポーラーは、~/.claude/channels/telegram/bot.pid に書かれた PID と一致する1つだけです。それ以外で PPID（2列目）が 1 になっているものは、起動元を失って残り続けているプロセスなので、止めてしまって問題ありません。僕が見つけた古い個体は通常の kill では終了しなかったので、その場合は kill -9 で止めます。

おすすめの構成は「チャンネル専用ディレクトリ」

ここまでの2つの問題は、プラグインの有効化をチャンネル専用のディレクトリに限定することでまとめて解決できます。僕は次の構成に落ち着きました。

まず専用のディレクトリを作り、その中の .claude/settings.local.json にだけプラグインの有効化を書きます。

mkdir -p ~/Projects/claude-channel/.claude

{
  "enabledPlugins": {
    "telegram@claude-plugins-official": true
  }
}

この設定ファイルを作ってから、user スコープ（~/.claude/settings.json の enabledPlugins）の telegram の行を削除します。順序を逆にすると、一時的にどこからもプラグインを読み込めない状態になるので注意してください。これで普段のセッションはプラグインを読み込まなくなり、ポーリングのプロセスも起動しません。

起動には ~/.zshrc に用意したシェル関数を使います。

tgclaude() {
  ( cd ~/Projects/claude-channel &&
    claude "$@" --channels plugin:telegram@claude-plugins-official --add-dir ~/Projects/your-project )
}

ひとつ細かい話ですが、"$@" は claude の直後に置いています。--channels と --add-dir はどちらも値を複数取れるオプションなので、末尾に "$@" を置く形だと、tgclaude "テストを実行して" のように渡したプロンプトがディレクトリ名として解釈されてしまうためです。

--add-dir に実際の作業ディレクトリを渡しておけば、専用ディレクトリを起点にしつつ、いつものプロジェクトのファイルを読み書きできます。作業ディレクトリの CLAUDE.md も効かせたい場合は、専用ディレクトリ側の CLAUDE.md に @/Users/you/Projects/your-project/CLAUDE.md のように書いておくと取り込まれます。

この構成にすると、Bot とつながるのは tgclaude で起動したセッションだけになります。素の claude で開いたセッションは Bot を奪うことも、プロセスを残すこともありません。tgclaude を2つ同時に起動すればさすがに競合しますが、それは意図しないと起きない操作なので、事故はほぼ防げます。

それでも複数セッションで使いたい場合

プロジェクトごとにチャネルを持ちたいなど、複数のセッションで同時に使いたい場合は、BotFather で Bot をもう1つ作り、環境変数 TELEGRAM_STATE_DIR で状態ディレクトリを分けて起動します。プラグインの README に記載されている方法です。

TELEGRAM_STATE_DIR=~/.claude/channels/telegram-second \
  claude --channels plugin:telegram@claude-plugins-official

2つ目の Bot のトークンは、分けたディレクトリの .env に TELEGRAM_BOT_TOKEN=... として置きます。ここで注意したいのは、シェルの環境変数が .env より優先されることです。Step 3 の補足で触れた環境変数方式（シェルで TELEGRAM_BOT_TOKEN を export しておく方法）を使っている場合、その値がすべてのインスタンスに効いてしまい、ディレクトリを分けても同じ Bot につながります。複数 Bot 構成にするなら、シェル側の export は外して .env に統一してください。

ただし現時点では、/telegram:configure と /telegram:access が TELEGRAM_STATE_DIR を参照せず、既定のディレクトリに書き込んでしまうという問題があります。このためペアリングが成立せず、分けた側の access.json は手で用意することになります。同種の問題は Discord プラグインについて Issue #1448 として報告されています。

{
  "dmPolicy": "allowlist",
  "allowFrom": ["あなたの数値ユーザーID"],
  "groups": {}
}

自分のユーザー ID は、前述の @userinfobot で調べられます。

動かないときのチェックリスト

うまくいかない場合は、以下を確認してみてください。

  • Claude Code のバージョン: できるだけ新しいバージョンになっていますか？
  • 認証方式: claude.ai アカウント、または Console の API キーで認証されていますか？（Bedrock・Google Cloud の Agent Platform・Microsoft Foundry 経由では使えません）
  • Bun のインストール: bun --version でバージョンが表示されますか？
  • --channels フラグ: Claude Code を起動するときにフラグを付けましたか？
  • ペアリング: Bot にメッセージを送り、受け取ったコードで /telegram:access pair を実行しましたか？
  • 別のセッションに奪われていないか: Telegram プラグインが有効な別のセッションを後から起動すると、Bot はそちらに移ります。奪われた側は自動では復帰しないため、チャネルを使いたいセッションのほうを起動し直してください（詳しくは「運用してわかったこと」を参照）
  • 現在の状態: /telegram:configure を引数なしで実行して、トークンと許可リストの状態を確認しましたか？
  • 組織の設定: Team / Enterprise で「blocked by org policy」と表示される場合は、管理者に Channels の有効化を依頼してください

外部サービスの設定で手間取りそうなときは、先にデモ用の fakechat チャネルで動作を確かめておくと切り分けが楽になります。ブラウザ上のチャット UI とやり取りするだけなので、認証も外部サービスの設定も不要です。

/plugin install fakechat@claude-plugins-official

claude --channels plugin:fakechat@claude-plugins-official

起動したら http://localhost:8787 を開いてメッセージを送ると、そのままセッションに届きます。

うまくいかなかったらまずは Claude Code に聞いてみましょう。

まとめ

Claude Code Channels と Telegram を組み合わせることで、ターミナルから離れていても Claude Code に指示を送れる環境が手に入ります。設定手順をおさらいしておきましょう。

  1. BotFather で Telegram Bot を作成してトークンを取得
  2. Claude Code で Telegram プラグインをインストールして /reload-plugins
  3. /telegram:configure で トークンを設定
  4. --channels フラグ付きで Claude Code を再起動
  5. Bot にメッセージを送って ペアリングを完了し、allowlist に切り替え

たったこれだけのステップで、スマホから Claude Code を操作できるようになります。公開当初と比べると、権限リレーによってターミナルに戻らなくても作業を進められるようになった点が特に大きな進歩だと感じています。

Channels はまだリサーチプレビューの段階なので、今後フラグの仕様やプロトコルが変わる可能性があります。実際、この記事も公開から数か月で複数の点を書き直すことになりました。最新の情報は公式ドキュメントを確認してくださいね。

フィードバックや不具合の報告は Claude Code の GitHub リポジトリ で受け付けているとのことです。気になった方はぜひ試してみてください！

参考リンク

更新履歴

  • 2026年7月28日: 数か月の運用で判明した注意点を「運用してわかったこと」の章としてまとめました。1つの Bot につながるセッションは1つだけであること、user スコープで有効化すると --channels なしのセッションでもポーリングのプロセスが起動すること（環境によっては残留すること）、対策としてのチャンネル専用ディレクトリ構成、複数セッションで使うための TELEGRAM_STATE_DIR と現時点の制約を追記しています。あわせて Step 2 のスコープ選択に注意書きを加え、Step 4 の --channels フラグの説明をより正確な表現に改めました
  • 2026年7月25日: 公式ドキュメントと Telegram プラグインの実装を確認し、以下を更新しました。
    • 認証要件を修正（Console の API キー認証にも対応。Bedrock・Google Cloud の Agent Platform・Microsoft Foundry は非対応）
    • サポートされるチャネルに iMessage とデモ用の fakechat を追加
    • プラグインのインストール手順を現行のものに更新（user スコープの選択、/plugin marketplace update、/reload-plugins で認識されるようになった点）
    • 権限リレーの解説を追加
    • 画像送信、リアクション、メッセージ編集、グループチャット対応などの機能を追記
    • アクセス管理コマンドの一覧と、組織向け設定（channelsEnabled / allowedChannelPlugins）を追記
    • その後、Telegram プラグインの実装を読み直して以下を修正しました。権限プロンプトは最初にツール名しか届かず、詳細は See more を開いて初めて表示されること。yes <ID> によるテキスト返信は、ID がチャット上に表示されないため実際には使えないこと。メッセージ編集ではプッシュ通知が鳴らないこと。あわせて各機能が入ったバージョンを明記しました
  • 2026年3月23日: 公開

この記事をシェア

関連記事