Вход, сессии и профили CLI Telegram
Войдите в Telegram, управляйте профилями и сессиями и решайте проблемы авторизации на своём компьютере.
Подключите инструмент к своему аккаунту мессенджера, чтобы агент мог читать выбранные чаты и помогать с ответами. Здесь вы пройдёте вход, проверите подключение и узнаете, как управлять сессией или завершить её. Вход добавляет разрешённое устройство; всю историю чатов он не скачивает.
Прочтите эту страницу, когда вы подключаете tg к своему аккаунту Telegram в первый раз, когда вы добавляете второй аккаунт или когда tg сообщает, что вы не вошли в систему. В конце вы узнаете, как войти в систему, как проверить, под кем вы вошли в систему, как выйти из системы и где tg хранит все, что ему нужно, чтобы оставаться в системе.
Во-первых, слова, которые используются на этой странице:
- Сессия: логин
tgна этом компьютере. Telegram выдает его при входе в систему и указывает в приложении Telegram как еще одно устройство.tgсохраняет его в файле. Тот, у кого есть этот файл, может читать ваши чаты, поэтому относитесь к нему как к паролю. - Приложение (
api_idиapi_hash): два значения из my.telegram.org, которые идентифицируют программу в Telegram. Каждый пользователь регистрирует свое приложение один раз;tgможет сделать это за вас. - Связка ключей: хранилище паролей вашей операционной системы.
tgсохраняет там значения приложения. - Профиль: имя для одного входа на этом компьютере с собственной сессией, приложением и настройками. Его называет каждая команда, которой нужен аккаунт, поэтому вы выбираете одно имя при настройке (
tg personal setup) и дальше используете его (профили).
Не путайте tg personal session с tg personal account sessions. tg personal session — это логин самого tg; tg personal account sessions перечисляет все остальные устройства и приложения, на которых выполнен вход в ваш аккаунт.
Первый запуск
tg personal setup помогает при первом запуске приложения и сессии, проверяет пять чатов и предлагает навыки агента. Подождите около пяти минут; Загрузка истории — это отдельный шаг. Запустите его в терминале. Используйте tg personal setup --app browser для регистрации приложения вручную или --method phone для входа в систему по телефону. tg personal session start остается командой только для входа в систему, включая возобновление прерванного входа в систему. Программа установки проверяет существующую сессию и не выполняет повторный вход в автоматическом режиме, если он отклонен.
Приложение с my.telegram.org
Посмотреть экран входа my.telegram.org

Это вход на сайт для получения данных приложения Telegram. Код приходит сообщением в Telegram, не по SMS. После входа выберите API development tools. Подтверждение доступа CLI через QR-код будет следующим этапом. my.telegram.org
Каждый пользователь регистрирует своё приложение. Telegram выдаёт одно приложение на номер телефона, поэтому общий идентификатор не включён в tg. Данные нужны один раз для каждого профиля; tg personal session start запрашивает их только при отсутствии.
Есть два способа получить данные:
--app browserоткрывает my.telegram.org/apps. Войдите туда, создайте приложение, если у вас его нет (любое название и краткое имя, платформа Desktop), и вставьтеApp api_idиApp api_hash, когдаtgспросит. Хэш не отображается при вводе. Это значение по умолчанию дляtg personal session start.--app autoзаполняет сайт за вас. Он запрашивает ваш номер телефона, а my.telegram.org отправляет вам код сообщением в Telegram, затем читает ваше приложение или создает его, если у вас его нет. На сайте нет API, поэтомуtgсоответствует его веб-форме; изменение на стороне Telegram может сломать это. Тогда--app browserвсе еще работает. Это значение по умолчанию дляtg setup.
Данные приложения сохраняются только после успешного входа в Telegram.
Создание приложения вручную
Выполните эти шаги с --app browser или если --app auto не сработал. Это делается один раз для каждого аккаунта Telegram.
-
Войдите на my.telegram.org. Выберите страну, введите номер телефона и нажмите Next.

Telegram присылает код подтверждения сообщением в приложение Telegram, а не по SMS. Введите его на странице и нажмите Sign in. Никому не сообщайте этот код и никогда не вводите его в чат с агентом.

-
Откройте Development Tools и выберите Create new application.

Заполните форму. Название (title) — не меньше 5 символов. Краткое имя (short name) — только буквы и цифры, от 5 до 32 символов. Не используйте в них слово «Telegram». Выберите платформу, например Desktop. URL и описание необязательны. Затем нажмите Create application.

-
Скопируйте
api_idиapi_hashиз раздела Credentials. Храните хеш в тайне: любой, у кого он есть, может расходовать квоту вашего приложения.
-
Передайте оба значения
tg, когда он запроситApp api_idиApp api_hash. Хеш не отображается при вводе.
Номер телефона и данные приложения на этих снимках экрана — примеры.
Вход в систему
tg personal session start # a QR code in the terminal
tg personal session start phone # a phone number, the code Telegram sends, and your 2FA password
tg personal session start phone --sms # the same, asking Telegram for the code by SMSQR: отсканируйте код в приложении Telegram, как описано в следующем разделе. Код обновляется, пока вы ждёте.
Телефон: введите номер в международном формате, а затем код для входа. Если у аккаунта есть облачный пароль (2FA), tg запрашивает его, не показывая, что вы вводите. При использовании --app auto номер телефона запрашивается только один раз. Код обычно приходит в приложение Telegram; --sms вместо этого запрашивает SMS, но Telegram выбирает, а tg сообщает, каким способом оно было отправлено. Когда в Telegram нет СМС для аккаунта, tg говорит об этом и запрашивает код из приложения.
После этого Telegram добавляет новое устройство в список сессий приложения.
Logged in as <your name> (@<username>, id <id>) — profile personal.
Session: ~/.local/share/tg-cli/sessions/personal.session
App keys: in the keyring
Next: tg personal chats list · tg personal server install to keep the archive currentЕсли вход запускает агент
Ваш ИИ-агент может запустить для вас вход в систему. Без терминала tg печатает QR-код обычным текстом, и агент вставляет его в чат, чтобы вы его отсканировали:
tg personal session start qrАгент запускает команду в фоне: она ждёт сканирования, а инструмент оболочки ничего не показывает, пока команда не завершится. Агент читает вывод и вставляет блок с QR-кодом в чат блоком кода, точно как напечатано. Когда Telegram обновляет код, печатается новый блок: агент вставляет его и говорит, что старый истёк. С --json каждый код также печатается одной строкой в stderr, {"event":"qr","qr":{"text":…,"expires_at":…,"scan":…}}. Когда код отсканирован, tg пишет scan accepted, finishing sign-in, а с --json — {"event":"progress","step":"scanned","message":…}: Telegram может завершать вход десять секунд и дольше.
Код нарисован для тёмной темы терминала. Без терминала это работает только в том случае, если в профиле уже есть приложение, а у аккаунта нет пароля 2FA: все остальное вам придется вводить самостоятельно.
Программа, которая показывает вопросы в своём окне, например WireCat Desktop, запускает
tg personal session start phone --json --answer-stdin: каждый вопрос приходит строкой needs в stderr,
а ответ — одной строкой в stdin.
tg personal setup работает так же. Вход не предлагается как инструмент MCP: агент, у которого есть только MCP, просит вас запустить команду или запускает её через свою оболочку.
Подключение устройства по QR-коду
В Telegram это называется подключением настольного устройства. tg показывает QR-код в терминале, а вы сканируете его приложением Telegram на телефоне. Используйте сканер самого Telegram, а не приложение камеры.
Android
- Откройте Telegram и перейдите в Настройки, затем в Устройства.
- Нажмите Подключить устройство (Add Device) и разрешите доступ к камере, если Telegram спросит.
- Наведите камеру на QR-код в терминале.

iPhone и iPad
- Откройте Telegram и перейдите в Настройки, затем в Устройства.
- Нажмите Подключить устройство (Link Desktop Device) и разрешите доступ к камере, если Telegram спросит.
- Наведите камеру на QR-код в терминале.
Если у аккаунта есть пароль двухэтапной проверки (2FA), tg запросит его после сканирования. Терминал не показывает, что вы вводите.
Незавершённые попытки входа. Если вы отсканировали код, но не ввели пароль 2FA, попытка появится в Устройствах в разделе незавершённых попыток входа (Incomplete login attempts). У неё нет доступа к вашим сообщениям. Завершите вход в tg или завершите эту попытку в том же списке.

Проверка и выход
tg personal account show # who this profile is logged in as
tg account list # every profile on this computer, and the account each is logged in as
tg personal account sessions list # every device and app logged in to the account; ends nothing
tg personal session end # log out on Telegram's side, and delete the session file heretg personal session end завершает сессию и на стороне Telegram: устройство исчезает из списка в приложении. Идентификатор и хеш приложения остаются в хранилище ключей, локальная база не меняется.
Чтобы полностью забыть профиль, используйте tg personal account remove --keep-data или --delete-data. Команда так же завершает сессию, а затем удаляет идентификатор и хеш приложения профиля, пароль его прокси, сессии его ботов для чтения истории и то, что cli-core хранит для профиля. С --keep-data его сообщения остаются в хранилище и находятся поиском. С --delete-data они удаляются. Токен бота с профилем того же имени остаётся, потому что бот является отдельным аккаунтом.
Срок действия сессии
Сессия действует, пока её не завершат: tg personal session end, из списка устройств в приложении Telegram или самим Telegram, если сессия не используется дольше, чем лимит аккаунта для неактивных сессий (authorization_ttl_days в Telegram API), который приложения позволяют вам установить в списке устройств. Профиль, который запускается каждый день, никогда не достигает его. Когда сессия завершена, каждая команда отвечает «не вошел в систему или сессия завершена» с кодом выхода 4; войдите снова с помощью tg personal session start (что делать, когда сессия завершилась).
Профили
Профиль — именованное подключение аккаунта Telegram в CLI. Обычно отдельный профиль создают для каждого номера: например, personal для личного аккаунта и work для рабочего. У каждого подключения свои сессия входа, данные приложения, настройки, разрешённые получатели и записи запусков.
Имя work — выбранная вами метка, а не номер телефона. Чтобы подключить рабочий аккаунт, выполните:
tg work session start --app browserПри регистрации приложения укажите рабочий номер; при QR-входе переключите Telegram на телефоне на рабочий аккаунт. После входа проверьте, какой аккаунт связан с меткой:
tg work account showОдин и тот же аккаунт тоже можно подключить в нескольких профилях; профиль сам по себе не создаёт новый аккаунт Telegram. Имя профиля указывается первым словом после tg, перед командой:
tg personal chats list # profile "personal"
tg work chats list # profile "work"
export TG_PROFILE=work # the same for the whole shell sessionПервое слово считается профилем, если это не команда. Поэтому профиль нельзя назвать chats, messages или другим словом команды; tg personal session start отклоняет такое имя. Разрешены буквы, цифры, точки, дефисы и подчёркивания; первый символ — буква или цифра.
Приоритет: сначала первое слово команды, затем TG_PROFILE. Если нет ни того, ни другого, команда, которой нужен аккаунт, останавливается с кодом выхода 2 и перечисляет профили на этом компьютере; если профилей ещё нет, она предлагает запустить tg personal setup. tg никогда не выбирает профиль сам, даже единственный. Команды, которым аккаунт не нужен, работают без профиля: --help, --version, commands, skill show, account list и config show.
Слово, которое не является командой и за которым нет команды, вызывает поясняющую ошибку:
"nonsense" is not a command, so it was read as a profile name — and no command followed it.TG_PROFILE_LOCK фиксирует процесс на одном профиле. Задайте его в окружении агента: другой профиль первым словом или через TG_PROFILE будет отклонён с кодом 5. Без этой переменной агент может выбрать профиль с меньшими ограничениями.
Для чего нужен каждый профиль и как профиль работает с ботом: профили и боты.
Где хранятся данные входа
| Данные | Место хранения |
|---|---|
| сессия | sessions/<profile>.session в каталоге состояния |
| идентификатор и хеш приложения | системное хранилище ключей, сервис tg-cli, запись <profile>:api |
| идентификатор и хеш без хранилища ключей | credentials.json в каталоге настроек |
| идентификатор и хеш для CI | TG_API_ID и TG_API_HASH; приоритет над хранилищем ключей |
Каталоги перечислены в куда идут файлы.
Если хранилища ключей нет (часто в контейнерах), данные приложения сохраняются в credentials.json рядом с настройками. tg один раз сообщает об этом в stderr.
⚠
TG_CONFIG_DIR,TG_STATE_DIRиTG_CACHE_DIRтакже меняют запись хранилища ключей. При любой из этих переменных имя сервиса включает каталог настроек. Сессия, созданная без переменных, не видна с ними, и наоборот. Задавайте их всегда или не задавайте вовсе.
⚠ В Linux доступ к связке ключей осуществляется через
XDG_RUNTIME_DIR. cron, ssh и некоторые клиенты MCP запускаютtgбез него, и каждая команда затем говорит, что учетные данные приложения не найдены, «хотя вход выполнен в систему на этом компьютере». Не входите повторно: это добавляет еще одно устройство и не исправляет среду. УстановитеXDG_RUNTIME_DIR> (учетные данные приложения не найдены после входа в систему).