Документация пользователя

Что такое Elys

Elys (Элис) — модульный юзербот для Telegram от команды ZavozDevs. Он работает от имени твоего аккаунта и выполняет команды, которые ты отправляешь в любой чат — например, .ping или .help. Вместо нового сообщения Elys обычно редактирует твоё, поэтому переписка остаётся чистой.

Elys написан на Python 3 поверх асинхронной MTProto-библиотеки elystl (форк Telethon) и вырос из проектов Hikka и Heroku.

Требования

• Python 3.10+ и git.
• API ID и API HASH — получи их на my.telegram.org/apps (раздел API development tools).
• Доступ в интернет до серверов Telegram (или прокси — см. флаги запуска).
• Для команд .ec, .ecpp, .ers, .eg, .enode — установленные компиляторы/рантаймы соответствующих языков. В Docker-образе уже есть Node.js и ffmpeg.

Установка

Выбери платформу. Все варианты клонируют репозиторий, ставят зависимости в виртуальное окружение и запускают python3 -m elys.

sudo apt update && sudo apt install git python3 python3-venv -y
git clone https://github.com/ZavozDevs/Elys && cd Elys
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python3 -m elys

sudo dnf update -y && sudo dnf install git python3 -y
git clone https://github.com/ZavozDevs/Elys && cd Elys
python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install -r requirements.txt
python3 -m elys

sudo pacman -Syu --noconfirm && sudo pacman -S git python --noconfirm --needed
git clone https://github.com/ZavozDevs/Elys && cd Elys
python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install -r requirements.txt
python3 -m elys

git clone https://github.com/ZavozDevs/Elys && cd Elys
docker compose up -d --build
docker attach elys_ub      # пройти авторизацию; выйти: Ctrl+P, Ctrl+Q
docker compose logs -f     # смотреть логи

Первый запуск

1. Введи API ID и API HASHElys попросит их при первом запуске. Их можно передать и через переменные окружения api_id и api_hash.
2. Войди в аккаунтпо номеру телефона (с кодом и 2FA-паролем, если он есть) или по QR-коду с флагом --qr-login.
3. Дождись создания инлайн-ботаElys сам создаст бота через @BotFather — он нужен для кнопок, форм и уведомлений. Своего бота можно задать позже: .ch_bot_token.
4. Проверь работуОтправь в любой чат .ping, затем .help.

Флаги запуска

Флаги передаются при старте: python3 -m elys --root --no-git.

python3 -m elys --proxy-host 127.0.0.1 --proxy-port 1080 --type-proxy socks5

Основы работы

Команда — это сообщение, начинающееся с префикса (по умолчанию точка). Аргументы пишутся через пробел; многие команды принимают ответ на сообщение вместо аргумента.

.help                 # список модулей и команд
.help Loader          # помощь по конкретному модулю
.ping                 # проверить, что бот жив
.info                 # карточка с информацией о юзерботе
.tr en Привет!        # перевести текст

Префикс

Сменить префикс: .setprefix ! — теперь команды пишутся как !help. Если забыл префикс, отправь .elys — бот покажет текущие настройки.

NoNick

NoNick позволяет запускать команды без отправки от твоего имени (бот отвечает отдельно, не редактируя сообщение). Включается для пользователя (.nonickuser), чата (.nonickchat) или команды (.nonickcmd ping).

Алиасы

Алиас — короткое имя для команды:

.addalias p ping      # теперь .p == .ping
.aliases              # все алиасы
.delalias p           # удалить алиас
.delalias --clear     # удалить все алиасы

Отключение команд и модулей

.togglecmd Tester ping выключает отдельную команду, .togglemod Translator — весь модуль. Повторный вызов включает обратно.

Модули

Функциональность Elys расширяется модулями — Python-файлами с командами. Совместимы модули Hikka, FTG, Heroku и MCUB.

Установка

.dlmod https://example.com/weather.py   # по ссылке (алиас .dlm)
.dlmod weather                          # по имени из подключённых репозиториев
.lm                                     # ответом на .py-файл (= .loadmod)
.dlmall                                 # все модули из выбранного репозитория

Если модуль требует pip-пакеты (строка # requires: в начале файла), Elys установит их автоматически.

Управление

.ulm Weather          # выгрузить модуль (= .unloadmod)
.ml Weather           # получить модуль файлом
.helphide Weather     # спрятать из .help
.clearmodule Weather  # стереть данные модуля в базе
.clearmodules         # выгрузить ВСЕ сторонние модули

Репозитории

Добавь репозиторий, чтобы ставить модули из него по имени: .addrepo <ссылка>, удалить — .delrepo <ссылка>.

Конфигурация

У большинства модулей есть настройки. Самый удобный путь — интерактивный конфигуратор с кнопками, поиском и пагинацией:

.config                          # выбрать модуль из списка
.config Tester                   # открыть настройки модуля
.config Tester ping_emoji        # открыть конкретную опцию
.config Tester ping_emoji 🚀     # сразу установить значение
.config ElysInfo banner_url https://… && ping_emoji ⚡   # несколько опций через &&

Значение можно взять из сообщения: ответь на него командой .config <модуль> <опция>. У .config есть короткий вариант — .cfg (алиас .fcfg).

Инлайн-настройки

.settings — панель с основными переключателями юзербота. .watchers — список активных «смотрителей» (обработчиков всех сообщений), .watcherbl <модуль> отключает смотрителя в текущем чате.

Безопасность и доступ

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

Владельцы

.owneradd @friend       # дать полный доступ (owner)
.owneradd -n @friend    # …без NoNick
.ownerlist              # список владельцев
.ownerrm @friend        # забрать доступ

Группы безопасности

Создай группу, добавь в неё людей и разреши ей конкретные команды через .security:

.newsgroup helpers           # создать группу
.sgroupadd helpers @friend   # добавить участника
.security ping               # инлайн-настройка: кто может запускать .ping
.sgroups                     # все группы

Таргетированные правила

.tsec выдаёт доступ к команде или модулю конкретному пользователю, чату или группе — опционально на время:

.tsec user @friend ping 1h   # другу — .ping на час
.tsec chat Translator        # всем в этом чате — модуль Translator
.tsecrm user ping            # удалить правило
.tsecclr chat                # очистить все правила для чатов

Чёрные списки

.blacklist — отключить бота в текущем чате, .blacklistuser — запретить пользователю выполнять команды. Отмена: .unblacklist / .unblacklistuser.

API Firewall

Защита от слишком частых запросов к Telegram API, которые могут привести к ограничениям аккаунта. Переключение — .api_fw_protection; временно приостановить — .suspend_api_protect 60.

Резервные копии

Elys умеет сохранять базу и модули прямо в Telegram — в отдельный чат-хранилище.

Для восстановления ответь соответствующей командой на файл бэкапа. Бэкапы из Hikka и Heroku тоже подходят.

Обновления

.update          # скачать и установить обновления
.changelog       # что нового
.rollback        # откатить последнее обновление
.autoupdate      # автообновления вкл/выкл
.branch beta     # сменить ветку: master, beta или dev
.restart         # перезапуск
.ubstop          # остановить юзербота (с подтверждением; -f — без)

Языки интерфейса

Смена языка: .setlang ru. Встроенные паки:

Внешний языковой пак ставится по ссылке: .dllangpack <ссылка>.

Несколько аккаунтов

.addacc запускает вход ещё одного аккаунта через инлайн-форму — без перезапуска и консоли. .switchacc переносит юзербота на другой аккаунт. При запуске из консоли несколько аккаунтов можно указать флагом -p несколько раз.

Eval и терминал

Для продвинутых пользователей: выполнение кода и shell-команд прямо из Telegram.

.e 2 ** 64                       # Python (алиас .eval)
.e await client.get_me()         # доступ к клиенту Telegram
.enode console.log([1,2,3].map(x => x * 2))
.terminal uptime                 # shell (алиас .exec)
.terminate                       # ответом — убить процесс (-f — принудительно)

Также доступны .ec (C), .ecpp (C++), .ers (Rust) и .eg (Go) — при наличии компиляторов в системе.

Справочник команд

Все команды встроенных модулей. Нажми на команду, чтобы скопировать её. Актуальный список с описаниями на выбранном языке — в .help.

Решение проблем