Takopi: как подключить Claude Code к Telegram — полная инструкция

Takopi — это открытый проект от banteg, который соединяет Telegram с Claude Code. После настройки вы пишете сообщения в обычный Telegram-чат, а Claude Code на вашем сервере их получает, обрабатывает и отвечает — как настоящий агент. Голосовые, картинки, файлы — всё работает.

Что такое Takopi?

Takopi — это мост (bridge) между Telegram и Claude Code. Проект создал banteg — разработчик из экосистемы DeFi, известный по проектам yearn.finance и curve.fi. Идея простая: запустить Claude Code на сервере, подключить к нему Telegram-бота, и получить полноценного ИИ-агента в кармане.

Схема работы выглядит так: вы пишете сообщение в Telegram → takopi перехватывает его через Telegram Bot API → передаёт в Claude Code через CLI → получает ответ → отправляет обратно вам в чат. При этом Claude Code работает в полноценном режиме: может выполнять bash-команды, читать и писать файлы, ходить в интернет, запускать скрипты.

Проект полностью открытый: github.com/banteg/takopi. Хранится на GitHub, активно развивается, собрал несколько сотен звёзд от разработчиков, которые используют Claude Code для автоматизации своих задач.

Ключевые возможности Takopi:

• Полный доступ к Claude Code из Telegram — пишешь как в обычный чат
• Голосовые сообщения транскрибируются через Whisper (Groq или OpenAI)
• Передача изображений и файлов агенту
• Поддержка нескольких режимов работы (chat, auto и др.)
• Работает на любом VPS или локальной машине с Python
• Конфигурация через один простой TOML-файл

Зачем это нужно

Claude Code — мощный инструмент, но он привязан к терминалу. Если хочешь что-то сделать с телефона — нужно открывать SSH, вводить команды. Takopi решает эту проблему: достаточно написать в Telegram, и агент сделает всё сам.

Реальные сценарии использования:

• Задачи на сервере без ноутбука. Едешь в метро — надо срочно поправить баг на проде. Открываешь Telegram, пишешь агенту, он правит файл и перезапускает сервис.
• Агент работает 24/7. Запустил takopi на VPS как systemd сервис — агент всегда онлайн, принимает задачи в любое время суток.
• Голосовые задачи. Не хочешь печатать — надиктовал голосом, Whisper распознал, Claude Code выполнил. Удобно когда руки заняты.
• Автоматизация рутины. Анализ данных, генерация отчётов, мониторинг — всё через чат в Telegram.
• Файловая работа. Прислал фотографию документа или скриншот — агент проанализировал, извлёк текст, обработал.

Требования

Перед установкой убедитесь, что у вас есть всё необходимое:

• Python 3.10+ — takopi использует современный синтаксис async/await
• Claude Code — установлен и авторизован (claude доступен в PATH)
• Telegram Bot Token — получить у @BotFather
• Anthropic API ключ — если Claude Code работает через API
• VPS или локальный сервер — для постоянной работы нужна машина, которая не выключается
• Опционально: Groq API ключ — для транскрипции голосовых через Whisper

Для тестирования подойдёт любая машина с Ubuntu 20.04+ или macOS. Для продакшена рекомендуется VPS с минимум 1 GB RAM.

Установка шаг за шагом

Создать бота в Telegram

Откройте Telegram и найдите бота @BotFather — официальный инструмент Telegram для создания ботов. Отправьте команду /newbot и следуйте инструкциям:

1. Введите имя бота (отображается в чате), например: My Claude Agent
2. Введите username бота (уникальный, должен заканчиваться на bot), например: my_claude_agent_bot
3. BotFather выдаст токен вида 1234567890:AAEхxxx... — сохраните его

Дополнительно рекомендуется отключить privacy mode, чтобы бот получал все сообщения в группах (если планируете использовать в группе): /setprivacy → выбрать бота → Disable.

Установить Takopi

Способ 1 — через pip (рекомендуется для большинства пользователей):

pip install takopi

Способ 2 — из исходников (для разработчиков или последней версии):

git clone https://github.com/banteg/takopi
cd takopi
pip install -e .

Проверьте установку:

takopi --version

Настройка конфига takopi.toml

Создайте файл takopi.toml в рабочей директории. Ниже — пример с объяснением каждого поля:

[telegram]
# Токен бота от @BotFather
token = "1234567890:AAExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Ваш Telegram user ID (можно узнать у @userinfobot)
# Только этот пользователь сможет писать боту
allowed_users = [123456789]

[claude]
# Команда для запуска Claude Code (обычно просто "claude")
command = "claude"

# Режим работы: "auto" — агент сам решает когда ответить
# "chat" — отвечает на каждое сообщение
mode = "auto"

# Рабочая директория для агента
# workdir = "/home/user/projects"

[whisper]
# Провайдер транскрипции голосовых: "groq" или "openai"
provider = "groq"

# API ключ для выбранного провайдера
api_key = "gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Модель Whisper
model = "whisper-large-v3"

Запуск

Простой запуск в терминале:

takopi run

После запуска откройте Telegram, найдите своего бота по username и напишите ему любое сообщение. Claude Code должен ответить. Если всё работает — переходим к настройке автозапуска.

Для работы в фоне (без systemd) можно использовать nohup или screen:

# через nohup
nohup takopi run > /var/log/takopi.log 2>&1 &

# или через screen
screen -S takopi
takopi run
# Ctrl+A, затем D — отсоединиться от сессии

Запуск как systemd сервис (для VPS)

Для постоянной работы на сервере лучше использовать systemd. Создайте файл сервиса:

sudo nano /etc/systemd/system/takopi.service

Содержимое unit-файла:

[Unit]
Description=Takopi — Telegram bridge for Claude Code
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/root
ExecStart=/usr/local/bin/takopi run
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal
Environment=HOME=/root

[Install]
WantedBy=multi-user.target

Активируйте и запустите сервис:

# Перечитать конфиги systemd
sudo systemctl daemon-reload

# Включить автозапуск при старте системы
sudo systemctl enable takopi

# Запустить сервис
sudo systemctl start takopi

# Проверить статус
sudo systemctl status takopi

# Смотреть логи в реальном времени
sudo journalctl -u takopi -f

После этого takopi будет автоматически запускаться при перезагрузке сервера и перезапускаться при ошибках.

Takopi + Whisper голосовые

Одна из самых удобных возможностей Takopi — транскрипция голосовых сообщений. Отправляете голосовое в Telegram, Takopi передаёт аудио в Whisper, получает текст, и уже этот текст уходит в Claude Code как обычное сообщение.

Настройка через Groq (рекомендуется)

Groq предоставляет бесплатный API для Whisper с очень высокой скоростью транскрипции — обычно меньше секунды даже для длинных сообщений. Модель whisper-large-v3 хорошо работает с русским языком.

1. Зарегистрируйтесь на console.groq.com
2. Создайте API ключ в разделе API Keys
3. Добавьте в takopi.toml:

[whisper]
provider = "groq"
api_key = "gsk_ваш_ключ_здесь"
model = "whisper-large-v3"

Настройка через OpenAI Whisper

Если у вас уже есть OpenAI API ключ:

[whisper]
provider = "openai"
api_key = "sk-ваш_ключ_здесь"
model = "whisper-1"

Как эффективно использовать голосовые

Голосовые особенно удобны для длинных задач, где печатать было бы долго. Несколько советов для качества распознавания:

• Говорите чётко и не слишком быстро — Whisper справляется с нормальным темпом речи
• Технические термины (названия функций, переменных) лучше проговаривать по буквам или дублировать в тексте
• Whisper хорошо понимает смешанную русско-английскую речь — можно говорить как привыкли
• Для точных команд (git commit message, SQL запросы) надёжнее писать текстом

Поддерживаемые режимы

Режим auto

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

Режим chat

Отвечает на каждое сообщение сразу, без долгого "обдумывания". Похож на обычный диалог с ChatGPT — хорошо для простых вопросов и коротких задач.

Работа с изображениями

Отправьте фото или скриншот в Telegram — takopi передаст изображение в Claude Code. Агент может описать содержимое, извлечь текст, проанализировать данные с графика или скриншота кода.

Работа с файлами

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

Советы и трюки

Как правильно ставить задачи агенту

Claude Code работает лучше, когда задача конкретная. Вместо "разберись с этим файлом" лучше написать "прочитай /var/log/nginx/error.log, найди все 500 ошибки за последний час и напиши краткий отчёт". Чем точнее контекст — тем лучше результат.

Контекст между сессиями

По умолчанию каждое сообщение — новая сессия Claude Code. Если вам нужен контекст между разговорами, настройте систему памяти: создайте файл с постоянными инструкциями и укажите агенту его читать. Например, создайте CLAUDE.md в рабочей директории — Claude Code автоматически учитывает его содержимое.

Несколько рабочих директорий

Если у вас несколько проектов, можно запустить несколько экземпляров takopi с разными конфигами и разными ботами — каждый со своей рабочей директорией. Удобно разделять рабочее и личное.

Безопасность: закрыть бота от посторонних

Всегда заполняйте поле allowed_users в конфиге. Если поле пустое или настроено неверно — любой пользователь Telegram может управлять вашим агентом и иметь доступ к файловой системе сервера.

Лимиты и ограничения

• Telegram ограничивает размер файлов: до 20 MB для ботов через Bot API
• Длинные ответы агент дробит на несколько сообщений автоматически
• Лимиты Anthropic API применяются как обычно — rate limits зависят от вашего плана
• Голосовые сообщения: Groq Whisper принимает файлы до 25 MB, OpenAI — до 25 MB

Логи для отладки

Если что-то идёт не так, смотрите логи:

# Если запущен через systemd
journalctl -u takopi -n 100

# Если запущен через nohup
tail -f /var/log/takopi.log

# Запустить с подробными логами
takopi run --verbose

---

FAQ

---

Где скачать и попробовать

Официальный репозиторий Takopi: github.com/banteg/takopi

Если хотите попробовать Takopi быстро, без ручной настройки — получите готовый скилл через бота @claudeskillsmarketbot. Напишите боту команду /start takopifree — получите бесплатный скилл с подробной инструкцией по установке и готовыми конфигами.