notes.kodachan.dev
← 一覧に戻る

Claude Code Telegram連携セットアップガイド

#プログラミング#ClaudeCode#リファレンス

Claude Code v2.1.80以降で使える Channels機能 を使い、TelegramからClaude Codeを操作する方法。

前提条件

  • Claude Code v2.1.80以上
  • Bun ランタイム（Node.jsではダメ）
  • Telegramアカウント

構造図

flowchart TD
    A["Bun"]
    A --> B["cmd.exe 経由"]
    B --> C["`/newbot` を送信"]
    C --> D["Telegram に「Paired! Say hi to.."]
    D --> E["3. プラグインをインストール"]
    E --> F["Listening 表示されてても動かない場合"]
    style F fill:#c05746,color:#fff,stroke:none

手順

1. Bun をインストール

プラグインのサーバーは Bun で動く。Node.js では動作しない。

Mac:

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

Windows（PowerShell）:

powershell -c "irm bun.sh/install.ps1 | iex"

winget でもインストール可能だが、PATHに自動追加されない既知問題あり。公式インストーラー推奨。

重要: インストール後、ターミナルを完全に再起動すること。Claude Code は cmd.exe 経由でプラグインを spawn するため、Windows の PATH に bun が入っている必要がある。

2. Telegram Bot を作成

  1. Telegram で @BotFather を検索してチャットを開く
  2. /newbot を送信
  3. Bot の表示名を入力（例: KodaChan Claude）
  4. Bot のユーザー名を入力（_bot で終わる、例: kodachan_claude_bot）
  5. 表示される API Token をコピー

3. プラグインをインストール

claude plugin install telegram@claude-plugins-official

4. Bot トークンを設定

Claude Code 内で:

/telegram:configure <コピーしたトークン>

トークンは ~/.claude/channels/telegram/.env に保存される。

5. Channels 付きでセッション起動

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

起動時に以下が表示されればOK:

Listening for channel messages from: plugin:telegram@claude-plugins-official

6. ペアリング

  1. Telegram で Bot を検索して DM を送る（/start など）
  2. Bot がペアリングコードを返す（例: a39faa）
  3. Claude Code 内で承認:
/telegram:access pair <コード>
  1. Telegram に「Paired! Say hi to Claude.」が届く

7. アクセスをロックダウン

自分だけが使えるようにする:

/telegram:access policy allowlist

便利なエイリアス

毎回 --channels を指定するのが面倒なら:

# .bashrc に追加
alias ct="claude --channels plugin:telegram@claude-plugins-official"

Windows 特有のハマりポイント（2026-03-20 実体験）

Bun の PATH 問題

Claude Code はプラグインサーバーを cmd.exe 経由 で spawn する。Git Bash の PATH に bun があっても、Windows の System/User PATH に入っていなければ 'bun' is not recognized で失敗する。

確認方法:

# デバッグログで確認
grep "bun.*not recognized" ~/.claude/debug/*.txt

解決: winget ではなく公式インストーラーを使う（PowerShell で irm bun.sh/install.ps1 | iex）。公式インストーラーは %USERPROFILE%\.bun\bin を User PATH に自動追加する。

ターミナル再起動が必須

PATH を変更しても、同じターミナルウィンドウ内で /exit → 再起動しただけでは反映されない。ターミナルウィンドウ自体を閉じて新しく開くこと。

Listening 表示されてても動かない場合

「Listening for channel messages from:」が表示されても、実際にはサーバー起動に失敗している場合がある。--debug を付けて ~/.claude/debug/ のログを確認するのが確実。

トラブルシューティング

Bot が DM に反応しない

  1. Bun がインストールされているか確認

    bun --version

  2. cmd.exe から bun が見えるか確認（Windows の場合）

    cmd //c "where bun"

    見えない場合はターミナルを完全に再起動

  3. --channels 付きで起動しているか確認 「Listening for channel messages from:」が表示されていること

  4. bun プロセスが実際に動いているか確認

    tasklist | grep -i "bun.exe"

    表示されなければサーバーが起動に失敗している

  5. デバッグモードで起動

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

    ~/.claude/debug/ にログが出る。'bun' is not recognized が出ていたら PATH の問題

アクセス管理コマンド一覧

| コマンド | 説明 | |---|---| | /telegram:access | 現在のステータス表示 | | /telegram:access pair <code> | ペアリング承認 | | /telegram:access deny <code> | ペアリング拒否 | | /telegram:access allow <userId> | ユーザーを許可リストに追加 | | /telegram:access remove <userId> | ユーザーを許可リストから削除 | | /telegram:access policy allowlist | 許可リストのみに制限 | | /telegram:access policy pairing | ペアリングモードに戻す |

関連ノート

  • [[CLAUDE.md]]

参考