Tutorial
Claude Code で Telegram 連携 完全ガイド
ゼロから始める AI アシスタント構築 — ハマりポイントと解決策をすべて収録
2026-05-05 · 点点滴滴喵児貴
0. はじめに：なぜ Claude Code + Telegram なのか
想像してみてください：通勤電車の中でスマホを取り出し、Telegram を開いて Claude に直接話しかける。コードを書いてもらったり、ドキュメントを分析したり、スケジュールを立てたり、調べものをしてもらったり。パソコンを開く必要もブラウザも不要 —— AI アシスタントが、いつも使っているメッセージアプリの中にいるのです。
Claude Code はそれ自体が強力な CLI ツールですが、Telegram プラグインを使えば「パソコンの前でしか使えない」から「いつでもどこでも使える」に変わります。このガイドでは、ゼロから連携を完了するまでを、自分が実際にハマったポイントも含めてすべて解説します。
連携が完了すると、以下のことができるようになります：
- スマホからいつでも Claude と会話（テキスト＋音声）
- グループで @bot してディスカッションに参加させる
- ファイルを送って分析してもらう
- 24 時間 365 日稼働のプライベート AI アシスタントとして使う
1. 事前準備
始める前に、以下のものを用意してください：
サーバー 1 台
Linux または Mac（クラウド VM でも可）。Telegram メッセージを常時受信するため、24 時間稼働が必要です。
Claude アカウント（2 択）
方法 1：サブスクリプションでログイン — claude.ai の有料プランで直接ログイン。月額固定、一般利用向け。
方法 2：API Key —
console.anthropic.com で取得。従量課金、ヘビーユースや自動化向け。
Telegram アカウント
Bot を作成できる必要があります。Telegram アカウントがあれば OK です。
基本的なターミナル操作
SSH 接続、コマンド実行、設定ファイルの編集ができること。
Tip：おすすめのサーバー選び
24 時間稼働のサーバーがない場合は、安価な VPS（例えば Linode の最安プラン $5/月）や、自宅に置いた Mac mini / Raspberry Pi がおすすめです。大事なのは常時稼働できることです。
2. ステップ 1：Bun のインストール
Bun は高速な JavaScript ランタイムで、Claude Code の Telegram プラグインはこれに依存して動作します。Telegram プラグインを使うには、先に Bun をインストールする必要があります。
インストールコマンド（Mac / Linux 共通）
curl -fsSL https://bun.sh/install | bash
インストール完了後、シェルの設定を再読み込みします：
source ~/.zshrc
source ~/.bashrc
インストール確認
bun --version
落とし穴：Bun は事前にインストールが必須
Claude Code の Telegram プラグインは起動時に Bun を呼び出してスクリプトを実行します。システムに Bun がインストールされていない場合、プラグインはサイレントに失敗します —— エラーも出ず、ただ動かないだけ。「Bot が反応しない」原因で最も多いのがこれです。
落とし穴（Mac）：root でインストールしない
Mac では絶対に sudo でインストールコマンドを実行しないでください。Bun のインストールスクリプトはバイナリを ~/.bun/bin/ に配置しますが、root で実行すると root の home ディレクトリに入ってしまい、通常ユーザーから bun が見つからなくなります。
落とし穴（Mac）：システム権限の確認ダイアログ
インストール中に macOS がセキュリティ権限のダイアログ（例:「ターミナルがダウンロードフォルダにアクセスすることを許可」）を表示することがあります。必ず「許可」をクリックしてください。拒否するとインストールが失敗しますが、明確なエラーメッセージは表示されません。
Tip：PATH の設定を確認する
インストール後に bun --version で command not found と表示される場合は、シェル設定ファイル（~/.zshrc または ~/.bashrc）に以下の行があるか確認してください：
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
3. ステップ 2：Claude Code のインストール
Claude Code CLI のインストール
npm install -g @anthropic-ai/claude-code
落とし穴（Mac）：sudo でインストールしない
Bun と同様、sudo npm install -g は使わないでください。権限エラーが出る場合の正しい対処法は、npm のグローバルインストール先を変更することです：
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$HOME/.npm-global/bin:$PATH"
source ~/.zshrc
npm install -g @anthropic-ai/claude-code
認証の設定（2 択）
方法 1：サブスクリプションでログイン（初心者おすすめ）
Claude Pro / Team / Max サブスクリプションをお持ちの場合、アカウントで直接ログインでき、API Key は不要です：
claude
サブスクリプション vs API Key、どちらを選ぶ？
サブスクリプション：月額固定（Pro $20/月）、一般利用向け、使用量を気にしなくて良い。
API Key：従量課金、ヘビーな自動化、コストを精密に管理したい、エンタープライズ向け。
おすすめ：まずサブスクリプションで始めて、使用量が安定してから API に切り替えるか検討しましょう。
方法 2：API Key を使う
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxx"
起動のたびに有効にするため、シェル設定ファイルに書き込みます：
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-あなたのkey"' >> ~/.zshrc
source ~/.zshrc
セキュリティに関する注意
API Key はクレジットカードと同じです。公開リポジトリに入れたり、他人に共有したりしないでください。クラウドサーバーを使う場合は、~/.zshrc のファイル権限が 600（自分だけ読み取り可）であることを確認しましょう。
インストール確認
claude --version
claude -p "hello と言って"
4. ステップ 3：Telegram Bot の作成
Telegram で Bot を作成し、Bot Token を取得します。
4.1 Bot の作成
- Telegram で @BotFather を検索する
- 会話を開いて
/newbot と入力する
- BotFather が Bot の表示名を聞いてきます（日本語 OK、例：「マイ AI アシスタント」）
- 次に username を聞かれます（英数字で末尾が
_bot、例：my_ai_assistant_bot）
- 完了すると、BotFather から Bot Token が送られます。形式はこんな感じ：
7123456789:AAF1x2y3z4a5b6c7d8e9f0-AbCdEfGhIjKlM
Tip：Bot Token は大切に保管
Bot Token は Bot のパスワードのようなものです。Token を手に入れた人は Bot を操作できてしまいます。安全に保管し、公開しないでください。
4.2 Group Privacy の設定（重要！）
見落としがちな設定です。デフォルトでは、Bot はグループ内で以下のメッセージしか受け取れません：
/ で始まるコマンド- Bot を @メンションしたメッセージ
- Bot の以前のメッセージへの返信
Bot にグループ内のすべてのメッセージを受信させたい場合（毎回 @メンションしなくて済むように）、Group Privacy を無効にする必要があります：
- @BotFather と会話する
/setprivacy と入力する- 作成した Bot を選択する
- Disable を選択する
あなた：/setprivacy
BotFather：Choose a bot to change group messages settings.
あなた：@your_bot_username
BotFather：'Disable' - your bot will receive all messages in groups.
'Enable' - your bot will only receive messages that...
あなた：Disable
BotFather：Success! The new status is: DISABLED.
落とし穴：Group Privacy はグループに追加する「前に」設定する
Bot がすでにグループに参加している場合、Privacy 設定を変更した後に Bot を一度グループから削除して再追加する必要があります。新しい設定はそうしないと反映されません。これは Telegram Bot API の既知の仕様です。
4.3 Chat ID の取得
Claude Code の Telegram プラグインは、どの chat_id との対話を許可するかを設定する必要があります（セキュリティ対策：知らない人が Bot を使って API クレジットを消費するのを防ぐため）。
個人の Chat ID を取得する方法：
curl -s "https://api.telegram.org/botあなたのTOKEN/getUpdates" | python3 -m json.tool
Tip：グループの Chat ID
グループの chat_id は負の数です（例：-1001234567890）。同じ getUpdates の方法で、Bot をグループに追加後にメッセージを送れば確認できます。
5. ステップ 4：Claude Code Telegram Plugin の設定
5.1 Bot Token の設定
Claude Code の CLI で、設定コマンドを使って Telegram プラグインを構成します：
claude
/telegram:configure
プロンプトに従って Bot Token を貼り付けてください。
5.2 許可する Chat ID の設定
セキュリティのため、Bot と対話できる chat_id を設定する必要があります：
/telegram:access
設定が完了すると、許可リストに含まれる chat_id からのメッセージにだけ Bot が応答するようになります。
5.3 Claude Code をデーモンモードで起動
Bot を常時稼働させるには、Claude Code をデーモンモードで起動します：
claude --daemon
nohup claude --daemon &> ~/claude-daemon.log &
tail -f ~/claude-daemon.log
5.4 動作確認
Telegram で Bot にメッセージを送ってみましょう（例：「こんにちは」）。すべて正しく設定されていれば、数秒以内に Bot が返信するはずです。
成功の目安
Bot がメッセージに返信すれば成功です。おめでとうございます！基本的な連携は完了です。次は応用設定に進みましょう。
Bot が反応しない場合
よくある原因（確認する順番）：
1. Bun がインストールされていない → bun --version で確認
2. Bot Token が間違っている → 再確認
3. Chat ID が許可リストにない → access 設定を確認
4. Claude Code がデーモンモードで動いていない → プロセスを確認
6. ステップ 5：応用設定
6.1 音声メッセージの自動文字起こし（Whisper）
音声で Bot と会話したい場合は、音声認識を設定する必要があります。Claude Code の Telegram プラグインは音声メッセージを受信し、Whisper モデルで自動的にテキスト変換してから処理できます。
pip install faster-whisper
export OPENAI_API_KEY="sk-..."
Tip：ローカル Whisper vs. API
GPU 搭載サーバーがあるなら、ローカル Whisper がコスパ良く高速です。GPU がない場合は OpenAI Whisper API の方が現実的で、1 分の音声で約 $0.006 です。
6.2 グループ対応
グループで Bot を使うには：
- Group Privacy が無効になっていることを確認（ステップ 3 で解説済み）
- Bot をグループに追加する
- グループの chat_id（負の数）を許可リストに追加する
-1001234567890
/telegram:access
6.3 自動起動（systemd / pm2）
再起動のたびに手動で Bot を起動するのは面倒です。以下は一般的な自動起動の方法 2 つです：
プラン A：systemd（Linux おすすめ）
sudo nano /etc/systemd/system/claude-telegram.service
[Unit]
Description=Claude Code Telegram Bot
After=network.target
[Service]
Type=simple
User=あなたのユーザー名
Environment=ANTHROPIC_API_KEY=sk-ant-api03-あなたのkey
Environment=HOME=/home/あなたのユーザー名
ExecStart=/home/あなたのユーザー名/.npm-global/bin/claude --daemon
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable claude-telegram
sudo systemctl start claude-telegram
sudo systemctl status claude-telegram
journalctl -u claude-telegram -f
プラン B：pm2（Mac / Linux 両対応）
npm install -g pm2
pm2 start "claude --daemon" --name claude-telegram
pm2 startup
pm2 save
pm2 status
pm2 logs claude-telegram
pm2 restart claude-telegram
6.4 CLAUDE.md でカスタム指示
プロジェクトディレクトリまたはホームディレクトリに CLAUDE.md（または ~/.claude/CLAUDE.md）を作成して、Claude の動作をカスタマイズできます：
# マイ設定
- 日本語で返答してください
- 回答は簡潔に、要点をまとめて
- コードにはコメントを付けてください
- 質問が曖昧な場合は、推測せず確認してください
Tip：CLAUDE.md の優先順位
Claude Code は次の順序で読み込みます：プロジェクトディレクトリの CLAUDE.md > ~/.claude/CLAUDE.md。プロジェクトレベルの設定がグローバル設定を上書きします。Telegram の会話ではデフォルトでグローバルの ~/.claude/CLAUDE.md が使われます。
7. よくあるトラブルシューティング
Bot が反応しない
bun --version
ps aux | grep claude
curl -s "https://api.telegram.org/botあなたのTOKEN/getMe"
権限エラー（Mac）
EACCES / Permission denied
Mac で最も多い権限の問題は sudo でインストールしたことが原因です。対処法：
1. root でインストールしたものを削除：sudo rm -rf /usr/local/lib/node_modules/@anthropic-ai
2. npm のグローバルパスをホームディレクトリに変更（ステップ 2 で解説済み）
3. 通常ユーザーで再インストール
Bun not found
ls ~/.bun/bin/bun
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"
API Rate Limit
音声メッセージが認識されない
pip show faster-whisper
ffmpeg -version
brew install ffmpeg
sudo apt install ffmpeg
8. おわりに
おめでとうございます！Claude Code + Telegram の連携が完了しました。これで 24 時間 365 日稼働のプライベート AI アシスタントを手に入れ、いつでも Telegram からやり取りできるようになりました。
やったことの振り返り：
Bun インストール → Claude Code インストール → Telegram Bot 作成 → Plugin 設定 → 応用設定。全体で約 30〜60 分（ハマった時間を除く）。
いくつかの運用アドバイス：
- 定期的に API 使用量を確認 —— 特にグループを追加した後は、複数人の利用でクレジットの消費が早くなります
- CLAUDE.md を活用 —— よく使う設定を書いておけば Bot が覚えてくれます
- デーモンの状態を監視 —— たまにログを確認して異常がないかチェックしましょう
- アップデートを忘れずに —— Claude Code は頻繁に更新されており、新バージョンでは多くのバグが修正されています
npm update -g @anthropic-ai/claude-code
このガイドが参考になったら、同じく連携を試してみたい友人にシェアしてください。質問があれば Telegram でお気軽にどうぞ。
Happy hacking!