Telegram-бот модератор

MVP-бот для автоматической модерации Telegram-групп. Бот проверяет текстовые сообщения по локальному списку запрещенных фраз и, если фраза не найдена, может отправить текст на проверку локальной модели Qwen через Ollama.

Требования

• Python 3.11+
• Telegram-бот, созданный через @BotFather
• Ollama для бесплатной локальной AI-модерации

Установка

python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Linux:

source .venv/bin/activate
pip install -r requirements.txt

Создайте .env на основе .env.example:

BOT_TOKEN=telegram_bot_token
OWNER_IDS=123456789,987654321
OPENAI_API_KEY=
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3:0.6b

OWNER_IDS содержит числовые Telegram ID владельцев через запятую, не username. Для Ollama OPENAI_API_KEY оставьте пустым.

Локальный AI через Ollama

Установите Ollama, затем загрузите модель:

ollama pull qwen3:0.6b

Запустите Ollama, если сервис не стартовал автоматически:

ollama serve

Ollama предоставляет API на http://localhost:11434. Значение с /v1 в .env также поддерживается ботом. Модель qwen3:0.6b занимает около 523 MB. При запуске бот пытается автоматически поднять локальный ollama serve, если Ollama установлена, но сервис выключен. Если Ollama не запущена или модель недоступна, бот продолжит работать только по локальным фразам.

Запуск

python main.py

SQLite-база moderation.db будет создана автоматически рядом с приложением.

Настройка Telegram-группы

1. Добавьте бота в группу или супергруппу.
2. Назначьте его администратором.
3. Выдайте права на удаление сообщений.
4. Выдайте права на блокировку пользователей, если нужен автобан.
5. Отключите Privacy Mode для бота через @BotFather, чтобы бот получал все сообщения группы.

Откройте личные сообщения с ботом и отправьте команду /panel. Выберите нужную группу из списка. Панель доступна владельцам из OWNER_IDS и администраторам выбранной группы. Для каждого чата отдельно можно менять список фраз, включать и выключать AI, включать автобан, смотреть статус и последние действия бота.

В разделе статуса нажмите Проверить AI, чтобы отправить контрольное спам-сообщение локальной модели. Бот покажет, отвечает ли Ollama и распознает ли модель тестовый спам.

По умолчанию AI включен, автобан выключен. Если Ollama временно недоступна, бот не останавливается и продолжает применять локальные правила. Бот проверяет новые и отредактированные текстовые сообщения, а также подписи к фото и видео.

Содержимое изображений без подписи бот не распознает: текущая компактная модель qwen3:0.6b работает только с текстом. Для анализа текста внутри изображений потребуется отдельно подключить OCR или vision-модель.

При временном таймауте Telegram API бот автоматически переподключается с увеличением задержки до 30 секунд. Перезапускать процесс вручную из-за краткого сетевого сбоя не нужно.

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

Если в терминале появляется ошибка not enough rights to restrict/unrestrict chat member, выдайте боту право блокировать пользователей в настройках администраторов группы либо выключите автобан в панели.