Собираем Telegram-бота в Cursor: от идеи до деплоя за один вечер

Telegram-бот — идеальный первый проект, чтобы попробовать «программирование с ИИ» на чём-то настоящем. Он маленький, приносит пользу сразу, а его логика понятна на пальцах: пришло сообщение — бот ответил. Но между «hello world на ноутбуке» и «бот, который живёт в облаке и отвечает всем» есть несколько шагов, где новички стабильно спотыкаются: асинхронный код, хранение токена и деплой.

Cursor — редактор кода с ИИ-агентом — как раз хорош тем, что ускоряет именно эти сложные места. Он не «пишет бота за вас магией», а помогает не утонуть в асинхронных паттернах, структуре обработчиков и настройке окружения. В этом гайде соберём рабочего бота от токена до деплоя и по дороге разберём одну ловушку Cursor, о которой молчат обычные туториалы: тот самый файл .env, который создают, чтобы НЕ хранить токен в коде, Cursor прочитает сам, если его не исключить.

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

Три вещи:

• Cursor — сам редактор ставится бесплатно; для первого бота хватает бесплатного тарифа Hobby. Если хотите понять, что это за инструмент в целом, у нас есть полный обзор возможностей Cursor.
• Python 3.10 или новее — современные библиотеки для ботов требуют именно его.
• Аккаунт Telegram — для общения с BotFather.

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

Шаг 1. BotFather и токен (и куда его НЕ класть)

Единственный официальный способ создать бота — через @BotFather в самом Telegram:

Opus 5 стоит как Opus 4.8, а работает вдвое дешевле Fable — Anthropic продаёт не мощность, а экономию токенов

Какую модель включать в Cursor под задачу: Composer, Grok, Claude и GPT

Файл .cursorrules и правила проекта: как настроить Cursor под свой стек

Agent Mode в Cursor на максимум: Plan Mode и приёмы профессионалов

Рабочий воркфлоу вайб-кодинга в Cursor, который доезжает до продакшена

1. Напишите /newbot.
2. Задайте отображаемое имя бота (например, «Мой первый бот»).
3. Задайте username — он обязательно заканчивается на bot (например, my_first_1234_bot).
4. BotFather пришлёт токен — длинную строку вида 8628738987:AAG....

Запомните главное: токен — это пароль от вашего бота. Кто угодно с этим токеном может управлять ботом. Поэтому его нельзя вставлять прямо в код и уж тем более коммитить в git. Правильное место — переменные окружения, о которых поговорим на шаге про секреты. Пока просто скопируйте токен в надёжное место.

Шаг 2. aiogram или python-telegram-bot

Для Python есть две основные библиотеки, и выбор зависит от задачи.

Для нашего первого бота возьмём aiogram — он современный, быстрый и хорошо ложится на асинхронную природу ботов. Именно здесь Cursor и выручает: асинхронный код с async/await — типичное место, где новичок путается, а агент напишет корректный каркас и объяснит каждую строку.

Шаг 3. Просите план, а не сразу код

Главная ошибка новичка в Cursor — сразу требовать «напиши мне бота целиком». Агент выдаст стену кода, в которой вы не разберётесь, а первая же ошибка загонит в тупик. Профессиональный подход — сначала план, потом код по шагам.

Включите Plan Mode (сочетание Shift+Tab в поле ввода агента) и сформулируйте задачу человеческим языком:

«Помоги собрать Telegram-бота на aiogram 3.x. Нужны команды /start и /help, ответ на текстовые сообщения эхом, токен из переменной окружения. Сначала предложи план по шагам, код не пиши.»

Агент задаст уточняющие вопросы и выдаст план: установка зависимостей, структура файлов, обработчики, запуск. Вы читаете план, при необходимости правите — и только потом просите реализовать по одному шагу. Так вы двигаетесь маленькими шагами и всё понимаете.

Шаг 4. Правила проекта: научите Cursor вашим требованиям

Чтобы агент не выдумывал стиль и не забывал про безопасность, задайте ему правила. В Cursor это файлы .cursor/rules/*.mdc — постоянный контекст, который подкладывается в каждый запрос. Создайте .cursor/rules/telegram-bot.mdc:

---
description: Правила для Telegram-бота на aiogram
alwaysApply: true
---

- Библиотека — aiogram 3.x, только async/await.
- Токен и любые секреты — ТОЛЬКО из переменных окружения (os.getenv), никогда не в коде.
- Каждый хендлер — отдельная функция с понятным именем.
- Логирование через модуль logging, не print.

Теперь агент будет держать эти требования в голове на протяжении всей работы — и, что важно, сам не станет хардкодить токен.

Шаг 5. Секреты: .env, .gitignore и главная ловушка Cursor

Вот место, ради которого стоит читать именно этот гайд. Правильный способ хранить токен — в файле .env:

BOT_TOKEN=8628738987:AAG...ваш_токен

В коде токен читается из окружения:

import os
from dotenv import load_dotenv

load_dotenv()
TOKEN = os.getenv("BOT_TOKEN")

И обязательно добавьте .env в .gitignore, чтобы он не попал в git:

.env

А теперь ловушка, специфичная для Cursor. Файл .env вы создаёте именно для того, чтобы токен не лежал в коде. Но ИИ-агент Cursor читает файлы вашего проекта, чтобы понимать контекст, — и .env он тоже прочитает, если его не исключить. Токен-пароль уедет в контекст модели.

Решение — файл .cursorignore в корне проекта (работает как .gitignore, но для агента Cursor):

.env

Это стык двух миров безопасности, который не проговаривает ни один обычный Telegram-туториал: .gitignore прячет секрет от git, .cursorignore — от ИИ-агента. Нужны оба.

Шаг 6. Хендлеры и запуск

Теперь можно просить агента реализовать бота. Минимальный каркас на aiogram выглядит так:

import asyncio, os, logging
from aiogram import Bot, Dispatcher
from aiogram.filters import Command
from aiogram.types import Message
from dotenv import load_dotenv

load_dotenv()
logging.basicConfig(level=logging.INFO)
bot = Bot(os.getenv("BOT_TOKEN"))
dp = Dispatcher()

@dp.message(Command("start"))
async def start(msg: Message):
    await msg.answer("Привет! Я твой первый бот.")

@dp.message()
async def echo(msg: Message):
    await msg.answer(msg.text)

async def main():
    await dp.start_polling(bot)

if __name__ == "__main__":
    asyncio.run(main())

Когда агент что-то предлагает, читайте дифф и принимайте изменения осознанно, а не жмите «принять всё» вслепую. Не понимаете строку — спросите агента прямо в чате: «объясни, что делает dp.start_polling».

Шаг 6.5. Сделаем бота полезным: кнопки и меню

Эхо-бот — это учебный минимум. Настоящая польза начинается, когда у бота есть понятное меню и он что-то делает. Самый простой способ — кнопки под сообщением (inline-клавиатура). Попросите агента: «добавь к команде /start две кнопки — „О боте“ и „Помощь“ — и обработай их нажатия». Он выдаст примерно такое:

from aiogram.types import InlineKeyboardMarkup, InlineKeyboardButton
from aiogram.filters import Command
from aiogram import F

@dp.message(Command("start"))
async def start(msg: Message):
    kb = InlineKeyboardMarkup(inline_keyboard=[[
        InlineKeyboardButton(text="О боте", callback_data="about"),
        InlineKeyboardButton(text="Помощь", callback_data="help"),
    ]])
    await msg.answer("Привет! Выбери действие:", reply_markup=kb)

@dp.callback_query(F.data == "about")
async def about(cb):
    await cb.message.answer("Я собран в Cursor за один вечер.")
    await cb.answer()

Дальше по тому же принципу навешивается любая логика: запрос погоды, напоминания, приём заявок. Важный приём — двигаться по одной фиче за раз: добавили кнопки, проверили, закоммитили; потом следующую функцию. Это ровно тот подход «маленькими шагами», который отделяет рабочего бота от каши, которую потом невозможно чинить.

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

Шаг 7. Тест локально: polling

Здесь важно понять разницу двух способов, которыми бот получает сообщения:

• Polling — бот сам постоянно спрашивает Telegram «есть новые сообщения?». Просто, не требует сервера и домена — идеально для локальной разработки и теста.
• Webhook — Telegram сам присылает сообщения на ваш адрес. Требует HTTPS и публичного домена — это для продакшена.

Для теста запускаем polling (dp.start_polling в коде выше). Установите зависимости и запустите:

pip install aiogram python-dotenv
python bot.py

Откройте своего бота в Telegram, напишите /start — он должен ответить. Работает локально? Отлично, половина дела сделана.

Шаг 8. Деплой: куда поселить бота

Бот на ноутбуке живёт, пока открыт терминал. Чтобы он работал круглосуточно, нужен хостинг. Три популярных варианта:

Для первого бота Railway — самый мягкий вход. По шагам:

1. Залейте код в репозиторий на GitHub (об этом попросите агента, если не знаете git — он подскажет команды).
2. Убедитесь, что в репозитории есть requirements.txt со списком зависимостей (aiogram, python-dotenv) — агент сгенерирует его командой или руками.
3. В Railway создайте новый проект → Deploy from GitHub repo → выберите свой репозиторий.
4. В настройках проекта, в разделе Variables, добавьте переменную BOT_TOKEN со значением вашего токена. Именно здесь, а не в коде — так токен попадёт в окружение сервера, но не в git.
5. Railway сам соберёт проект и запустит бота.

По практике простой хобби-бот на polling тратит около 40 центов в неделю, так что бесплатного кредита Railway ($5) хватает на пару-тройку месяцев. Когда кредит закончится, тариф Hobby стоит недорого — для одного бота это копейки.

При переезде в продакшен на постоянный домен есть смысл переключиться с polling на webhook — это надёжнее под нагрузкой. Попросите агента переписать запуск под webhook: он знает шаблон и объяснит, что поменять.

Типовые ошибки и риски новичка

Чтобы не наступить на грабли, о которых узнают уже в бою:

• Токен утёк в git. Самая частая и болезненная ошибка. Проверьте, что .env в .gitignore ДО первого коммита. Если токен всё же попал в историю — немедленно перевыпустите его через BotFather (команда /token) и получите новый.
• Токен уехал в контекст Cursor. Тот самый .cursorignore — не забудьте про него, иначе секрет прочитает агент.
• Временный бан от Telegram. При частых перезапусках бота и повторных авторизациях Telegram может временно ограничить бота. Не дёргайте перезапуск в цикле — особенно если агент «чинит» бота итерациями.
• Агент что-то выдумал. ИИ-инструменты иногда «галлюцинируют» — предлагают несуществующие методы библиотеки. Если код не запускается со странной ошибкой, сверьтесь с официальной документацией aiogram, а не слепо доверяйте агенту.
• Спутали polling и webhook. Нельзя запускать оба одновременно — Telegram отдаёт сообщения либо туда, либо туда. На локали — polling, в проде — webhook, но не вместе.

Отладка: что делать, когда бот молчит

Бот не отвечает — самая частая ситуация у новичка. Пройдите по списку, прежде чем звать агента чинить наугад:

• Токен не подхватился. Проверьте, что .env лежит рядом с bot.py, переменная называется ровно BOT_TOKEN, а load_dotenv() вызван до чтения токена. Пустой токен — самая частая причина «тишины».
• Бот запущен, но в другом чате. Убедитесь, что пишете именно тому боту, чей username вам выдал BotFather, а не старому тестовому.
• Ошибка в логах. Мы не зря включили logging — при запуске смотрите в терминал. Питоновский traceback прямо укажет строку с проблемой; скопируйте её агенту в чат, и он объяснит причину.
• Конфликт polling/webhook. Если раньше ставили webhook, а теперь запускаете polling, Telegram может отдавать сообщения «в старую дверь». Попросите агента добавить await bot.delete_webhook(drop_pending_updates=True) перед стартом polling.
• Не те версии библиотек. Код под aiogram 2.x не заработает на aiogram 3.x — синтаксис изменился. Проверьте, что установлена версия 3.x, и явно скажите агенту, под какую версию писать.

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

Какого бота собрать первым

Чтобы не застрять на выборе идеи, начните с простого, но полезного лично вам. Хорошие первые проекты:

• Бот-напоминалка — принимает текст и время, присылает напоминание. Учит работать с состоянием и планировщиком.
• Бот-шпаргалка — по команде выдаёт заготовленные ответы (расписание, контакты, ссылки). Почти чистая логика на кнопках.
• Бот-агрегатор — по запросу подтягивает данные из открытого API (курс валют, погода, статус сервиса). Учит делать HTTP-запросы.
• Бот для заявок — собирает форму по шагам и отправляет вам в личку. Пригодится для маленького бизнеса.

Все они собираются на том же каркасе, что мы прошли: команды, кнопки, обработчики. Разница только в логике внутри, а её как раз удобно наращивать вместе с агентом по одной фиче за раз. Начните с того, чем сами будете пользоваться, — так проще довести проект до конца.

Коротко о главном

Собрать Telegram-бота в Cursor реально за один вечер, даже без опыта в Python: токен у BotFather, aiogram для логики, Plan Mode вместо «напиши всё сразу», секреты в .env — и обязательно в .cursorignore, чтобы токен не уехал к агенту. Локально тестируем на polling, в облако выкатываем на Railway. Главное — двигаться маленькими шагами и понимать каждую строку, а не принимать код вслепую.

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

Если вам понравился сам подход «строю продукт с ИИ», почитайте, что такое вайб-кодинг и где у него границы — бот здесь только начало. А дальше тот же путь ведёт к более серьёзным проектам: веб-приложениям, автоматизациям, собственным инструментам. Навык остаётся тем же — чётко ставить задачу, двигаться маленькими шагами и понимать код, который пишет агент.

Частые вопросы

Нужно ли знать Python, чтобы собрать бота в Cursor? Для первого простого бота — нет. Код пишет агент, а ваша задача — понимать логику и принимать решения. Но базовое понимание Python сильно ускорит дальнейшую работу.

Где взять токен для бота? Только у @BotFather в Telegram: команда /newbot, задаёте имя и username, в ответ получаете токен. Это единственный официальный способ.

Чем polling отличается от webhook? Polling — бот сам спрашивает Telegram о новых сообщениях, подходит для локального теста без сервера. Webhook — Telegram присылает сообщения на ваш HTTPS-адрес, нужен для продакшена. Одновременно использовать нельзя.

Как безопасно хранить токен в Cursor? В файле .env, читать через переменные окружения. Добавьте .env и в .gitignore (чтобы не попал в git), и в .cursorignore (чтобы его не прочитал ИИ-агент). Нужны оба файла.

Куда задеплоить бота бесплатно? На старте подойдёт Railway ($5 бесплатного кредита) или Render (free-тариф на 750 часов, но сервис «засыпает» без активности). Токен задавайте в переменных окружения хостинга, а не в коде.