Гайд

Telegram Multi-Thread Router

Управляй Claude Code прямо из Telegram. Каждый топик — отдельная сессия агента. Работай с AI с телефона, из кровати, из отпуска.

GitHub репозиторий →
Зачем это нужно

Claude Code — в кармане

Claude Code — мощный инструмент, но у него есть ограничение: работает только в терминале на компьютере. А что если нужно быстро дать задачу агенту, пока едешь в метро? Или проверить статус задачи с телефона?

Telegram Multi-Thread Router решает эту проблему. Это Telegram-бот, который подключается к Claude Code на вашем компьютере или сервере и позволяет управлять им прямо из мессенджера.

💬

Топик = сессия

Каждый топик в боте — отдельная сессия Claude Code. Можно вести несколько задач параллельно, не мешая друг другу.

📱

Работай с телефона

Отправляешь сообщение в Telegram — агент его получает и выполняет. Ответ приходит прямо в чат. Никакого терминала.

🔄

Сессии живут

Бот перезапустился? Сессии восстановятся автоматически. Контекст не теряется — агент помнит, над чем работал.

🎤

Голосовые сообщения

Отправляешь голосовое — бот распознает речь и передаст текст агенту. Можно буквально «разговаривать» с Claude Code.

📊

Статус в реальном времени

Редактируемое сообщение-статус показывает, что именно сейчас делает агент в каждой сессии. Видно прогресс без угадывания.

🌐

Мульти-сервер

Запускай сессии на разных машинах через TCP-воркеры. Бот — хаб, воркеры — исполнители. Масштабируйся горизонтально.

Архитектура

Как это работает

📱
Telegram
ты пишешь в топик
→
🤖
Router Bot
aiogram 3
→
🧠
Claude Code
Agent SDK
→
💻
Твой компьютер
файлы, git, терминал

Каждый топик — отдельный SessionRunner с изолированным контекстом

Бот использует топики прямо в чате с тобой. Когда ты пишешь в топик:

  • Router определяет, к какой сессии относится сообщение (по ID топика)
  • Если сессии нет — создаёт новую через Claude Agent SDK
  • Передаёт твоё сообщение агенту и стримит ответ обратно в тот же топик
  • Оркестратор (главный топик) может управлять всеми сессиями
💡
Оркестратор — специальный топик, который создаётся автоматически при первом сообщении. Через него можно создавать новые сессии, видеть список активных, останавливать ненужные. У оркестратора есть MCP-инструменты для управления.
Перед установкой

Что понадобится

💻
Компьютер

  • Mac или Linux — подойдёт ваш обычный компьютер (Windows — через WSL)
  • Python 3.11+ — для запуска бота
  • Claude Code CLI — установлен и авторизован (claude auth login)
  • Подписка Claude — Max или Pro (агент использует Claude Code под капотом)

🤖
Telegram-бот

  • Создать бота через @BotFather и получить токен
  • Включить Threaded Mode в настройках бота через @BotFather (Bot Settings → Threaded Mode → Enable)
  • Отправить /start своему боту — это создаст чат, который бот будет использовать для топиков
  • Узнать свой Telegram User ID — через @Get_myidrobot (отправьте /start, скопируйте числовой ID)
💡
Начните с личного компьютера.Для первого знакомства не нужен сервер — запустите бота прямо на своём Mac или ноутбуке. Бот будет работать, пока компьютер включён. Перенести на сервер можно позже, когда захотите доступ 24/7.
⚠️
Важно: бот будет принимать сообщения только от вас (по User ID). Никто другой не сможет управлять вашими агентами. Это безопасно.
Пошаговая установка

Установка и настройка

🤖
Пусть агент сделает это за вас. Вместо ручного выполнения шагов ниже, просто скопируйте ссылку на эту страницу и отправьте Claude Code с просьбой: «Установи и настрой Telegram Multi-Thread Router по этому гайду». Агент сам склонирует репозиторий, создаст окружение, установит зависимости и подскажет, какие данные от вас нужны. Ниже — ручные шаги для тех, кто хочет разобраться сам.

1. Клонируем репозиторий

Открываем терминал на компьютере и скачиваем проект:

# Клонируем репозиторий git clone https://github.com/MaxZarev/telegram-multi-thread-router.git # Переходим в папку проекта cd telegram-multi-thread-router

2. Создаём виртуальное окружение

Python-проекты лучше запускать в изолированном окружении, чтобы зависимости не конфликтовали:

# Создаём виртуальное окружение (нужен Python 3.11+) python3.11 -m venv .venv # Активируем его source .venv/bin/activate # Устанавливаем зависимости pip install -e ".[dev]"
✅
После source .venv/bin/activate в начале строки терминала появится (.venv) — значит окружение активировано.

3. Настраиваем переменные окружения

Копируем файл-пример и заполняем своими данными:

# Копируем пример cp .env.example .env # Открываем для редактирования nano .env

Заполните файл .env следующими значениями:

ПеременнаяЧто писатьПример
BOT_TOKENТокен бота от @BotFather123456789:AAHfiqks...
OWNER_USER_IDВаш Telegram User ID (число)123456789
AUTH_TOKENЛюбой секретный ключ (для IPC)my-secret-token-123
STREAM_INTERMEDIATE_MESSAGESСтримить текст агента в реальном времени (true) или показывать только финальный ответ (false)true
🔒
Файл .env содержит секреты. Никогда не публикуйте его и не добавляйте в git. Он уже в .gitignore.

4. Проверяем авторизацию Claude Code

Claude Code должен быть установлен и авторизован на вашем компьютере:

# Проверяем что Claude Code работает claude --version # Если не авторизован — логинимся claude auth login

5. Запускаем бота

# Запуск python -m src

Если всё настроено правильно, вы увидите в логах:

INFO: Starting bot (owner=123456789, chat=auto-detect)

Теперь откройте чат с ботом в Telegram и отправьте любое сообщение. Бот автоматически определит чат и создаст топик-оркестратор — главный топик для управления сессиями.

⚠️
Если бот не отвечает: убедитесь, что вы отправили /start боту до запуска скрипта. Бот ожидает активный чат с владельцем.

6. Запуск в фоне (опционально, для сервера)

Если запускаете на личном компьютере — этот шаг не нужен. Просто держите терминал открытым, пока работаете с ботом.

Если вы перенесли бота на сервер и хотите, чтобы он работал постоянно:

# Через systemd (для Linux-сервера) # Создаём сервис sudo nano /etc/systemd/system/tg-router.service

Содержимое файла сервиса:

[Unit] Description=Telegram Multi-Thread Router After=network.target [Service] Type=simple User=YOUR_USER WorkingDirectory=/path/to/telegram-multi-thread-router ExecStart=/path/to/telegram-multi-thread-router/.venv/bin/python -m src Restart=always RestartSec=5 [Install] WantedBy=multi-user.target
# Включаем и запускаем sudo systemctl enable tg-router sudo systemctl start tg-router # Проверяем статус sudo systemctl status tg-router # Смотрим логи sudo journalctl -u tg-router -f
💡
На Mac для фонового запуска можно использовать launchd или просто nohup python -m src &. Попросите Claude Code настроить это — он справится.
Использование

Как пользоваться

Команды бота

Все команды работают из любого топика:

  • /new название /путь/к/проекту — создать новую сессию в новом топике
  • /list — список всех активных сессий
  • /stop — прервать текущее выполнение (как Escape в терминале)
  • /close — убить сессию и удалить топик
  • /restart — перезапустить бота (все сессии восстановятся)
  • Любая другая /команда — пересылается агенту (/model, /clear, /compact, /reset и т.д.)

Оркестратор

Первое сообщение боту создаёт оркестратор — главный топик. Через него можно управлять всем естественным языком:

Примеры:

  • «Создай сессию для проекта my-app в папке /home/user/my-app»
  • «Создай сессию на воркере personal в /root/agent»
  • «Покажи все активные сессии»
  • «Включи auto-mode для сессии my-app»
  • «Останови сессию my-app»

Отправка файлов

Можно отправлять боту файлы (фото, документы) — он скачает их в рабочую директорию сессии и передаст путь агенту. Удобно для:

  • Скриншотов с ошибками — агент «увидит» и поможет
  • Файлов конфигурации — закинуть на сервер через Telegram
  • Макетов и изображений — агент может использовать в проекте

Система разрешений

Когда агент хочет выполнить потенциально опасное действие (записать файл, выполнить команду), бот спрашивает разрешение через inline-кнопки в Telegram:

  • Allow — разрешить одно действие
  • Allow All — разрешить все подобные действия в этой сессии
  • Deny — запретить

Безопасные действия (чтение файлов, поиск) одобряются автоматически.

💡
Auto Mode: для доверенных сессий можно включить автоматическое одобрение всех действий. Попросите оркестратор: «Включи auto-mode для сессии X». Или используйте inline-кнопку Allow All при первом запросе.

Режим стриминга

Бот поддерживает два режима вывода текста агента. Настраивается через переменную STREAM_INTERMEDIATE_MESSAGES в .env:

  • true — текст агента стримится в реальном времени. Видно, как Claude «думает» — удобно для наблюдения за процессом
  • false — Telegram тише: показываются статусы и прогресс, но основной текст появляется ближе к концу. Меньше уведомлений

Статусы, запросы разрешений и ошибки показываются в любом режиме.

Мульти-сервер

Можно запускать сессии на разных машинах, подключая воркеры по TCP:

# На удалённой машине — запуск воркера pip install -e ".[dev]" python -m src.worker --host <ip-бота> --port 9800 --token $AUTH_TOKEN --worker-id my-worker # Создание сессии на воркере (через оркестратор) # «Создай сессию на воркере my-worker в /root/agent»

Бот выступает хабом — обрабатывает Telegram и диспатчит задачи на локальные или удалённые бэкенды. Воркеры обмениваются сообщениями, файлами и запросами разрешений через бинарный TCP-протокол (msgspec).

Безопасность

Насколько это безопасно

Когда даёшь AI-агенту доступ к серверу через Telegram, логичный вопрос — «А не сломает ли он мне всё?». Короткий ответ: при правильной настройке — нет. Вот почему:

🔐

Только ваш User ID

Бот принимает сообщения только от владельца (OWNER_USER_ID). Никто другой не сможет отправить боту команды.

✋

Система разрешений

На каждое опасное действие (запись файлов, выполнение команд) бот спрашивает разрешение через inline-кнопки. Вы контролируете каждый шаг.

🏠

Изоляция сессий

Каждая сессия работает в своей рабочей директории. Агент из одного топика не видит файлы агента в другом — если вы сами не укажете один путь.

🔑

Секреты в .env

Все токены и ключи хранятся в файле .env, который не попадает в git. Доступ к серверу — только по SSH-ключу.

Рекомендации по безопасности

  • Не давайте боту root-доступ. Запускайте от обычного пользователя. Если агент попытается выполнить sudo rm -rf / — у него просто не будет прав
  • Используйте отдельного пользователя на сервере для бота. Создайте пользователя с ограниченными правами — только на нужные директории
  • Не включайте Auto Mode сразу. Начните с ручного подтверждения каждого действия. Когда привыкнете — можно включить автоматический режим для доверенных сессий
  • Используйте Git. Если агент что-то сломает в коде — всегда можно откатить через git checkout или git reset
  • Не храните пароли в открытых файлах в рабочих директориях. Агент может прочитать всё, к чему у пользователя есть доступ
💡
Про сервер vs домашний компьютер:если запускаете бота на арендованном сервере (VPS) — безопаснее всего. Даже в худшем случае — переустанавливаете сервер за 2 минуты. На домашнем компьютере будьте аккуратнее: не давайте агенту доступ к папкам с личными данными.
Важный нюанс

Компьютер не должен засыпать

Если вы запускаете бота на домашнем компьютере (а не на сервере) — есть критический момент: когда компьютер уходит в сон, бот перестаёт работать. Telegram-сообщения просто не будут доходить, пока машина спит.

Нужно настроить систему так, чтобы компьютер не засыпал, даже если вы закрыли крышку ноутбука, ушли из дома или не трогаете его часами.

🍎
macOS

Вариант 1: Системные настройки (GUI)

  • Откройте System Settings (Системные настройки)
  • Перейдите в Energy (Аккумулятор / Энергия)
  • Поставьте «Turn display off after» на Never (Никогда) — или на большое значение
  • Включите «Prevent automatic sleeping when the display is off»

Вариант 2: Через терминал (надёжнее)

# Запретить сон навсегда (до перезагрузки) caffeinate -s & # Или: запретить сон пока работает конкретный процесс caffeinate -s python -m src # Проверить, не уснёт ли Mac pmset -g assertions

Если используете MacBook с закрытой крышкой:

  • Mac должен быть подключён к зарядке — иначе уснёт при закрытии крышки
  • Подключите внешний монитор, клавиатуру или мышь — тогда Mac будет работать в «режиме крышки» (clamshell mode)
  • Или используйте утилиту KeepingYouAwake (бесплатная, open-source) — иконка в меню-баре для предотвращения сна
⚠️
caffeinate — встроенная утилита macOS. Флаг -s предотвращает системный сон. Если закроете терминал — caffeinate остановится. Лучше запускать через tmux или screen.

🪟
Windows

Вариант 1: Параметры электропитания (GUI)

  • Откройте Параметры → Система → Питание и спящий режим
  • Установите «Переводить в спящий режим через» на Никогда (и от сети, и от батареи)
  • Установите «Отключать экран через» на Никогда или большое значение

Вариант 2: Через PowerShell

# Отключить спящий режим (от сети) powercfg /change standby-timeout-ac 0 # Отключить спящий режим (от батареи) powercfg /change standby-timeout-dc 0 # Отключить гибернацию powercfg /hibernate off # Проверить текущие настройки powercfg /query

Если используете ноутбук с закрытой крышкой:

  • Откройте Панель управления → Электропитание → Действие при закрытии крышки
  • Установите «При закрытии крышки» → Действие не требуется (и от батареи, и от сети)
  • Нажмите Сохранить изменения
⚠️
Windows Update может перезагрузить компьютер автоматически. Отключите это: Параметры → Центр обновления Windows → Дополнительные параметры→ выключите «Перезапускать это устройство как можно скорее». Установите активные часы на весь день.

Сессия терминала не должна умирать

Даже если компьютер не спит — при закрытии терминала процесс бота остановится. Чтобы этого не произошло, используйте один из инструментов:

tmux (рекомендуется) — терминальный мультиплексор:

# Создать новую сессию tmux new -s router # Запустить бота внутри tmux cd telegram-multi-thread-router source .venv/bin/activate python -m src # Отсоединиться от сессии (бот продолжит работать) # Нажмите: Ctrl+B, затем D # Подключиться обратно к сессии tmux attach -t router

На Windows tmux нет, но можно использовать:

  • Windows Terminal — просто не закрывайте окно
  • WSL 2 + tmux — самый надёжный вариант для Windows
  • nssm — утилита для запуска скриптов как Windows-служб
💡
Лучшее решение — VPS-сервер.За $4–5/мес (Hetzner, DigitalOcean) получаете машину, которая работает 24/7, не засыпает и не перезагружается. Настроили один раз — и забыли. Это то, что мы рекомендуем на курсе.
Сценарии

Как это можно применять

🛠

Удалённая разработка

Даёшь задачу агенту с телефона: «Добавь кнопку выхода на страницу профиля». Агент пишет код, коммитит, деплоит. Ты проверяешь результат.

🐛

Дебаг на ходу

Пришло уведомление об ошибке? Скидываешь скриншот агенту в топик. Он анализирует логи, находит причину, предлагает фикс.

📊

Мониторинг

Спрашиваешь агента: «Какой uptime сервера?», «Сколько свободной памяти?», «Покажи последние логи nginx». Он выполняет команды и отвечает.

🚀

Параллельные проекты

Один топик = один проект. Веди пять проектов одновременно, переключайся между ними просто переходя между топиками.

Ресурсы

Полезные ссылки

📦
GitHub — Исходный код
Форк репозитория с доработками. Клонировать, смотреть issues, контрибьютить.
📖
Claude Code — Документация
Официальная документация Claude Code CLI от Anthropic.
🐍
Claude Agent SDK
Python SDK для программного управления Claude Code.
🤖
BotFather
Создание и настройка Telegram-ботов.