Решение проблем с CLI Telegram
Решите типичные проблемы установки, входа, подключения и выполнения команд CLI для Telegram.
Найдите свою ошибку или симптом и выполните шаги восстановления. Цель — вернуть инструмент в рабочее состояние и проверить результат; сохраните текст ошибки, если потребуется помощь с отчётом о проблеме.
Используйте эту страницу, когда tg показывает ошибку или не делает то, что вы ожидали. Найдите сообщение, которое вы видите, или его код выхода, и страница расскажет вам, что оно означает и что делать дальше. Большинство решений требует одной команды.
Несколько слов, которые используются на этой странице:
- Код выхода — это число, которое команда возвращает по завершении:
0означает завершение команды; у пакетного чтения проверьте полноту, любое другое число обозначает тип сбоя. Его читают скрипты и ИИ-агенты; В таблице ниже каждый из них сопоставлен с его разделом. tg personal doctorпроверяет установку без подключения к Telegram. Сначала запустите его.--traceпоказывает каждый запрос к Telegram в том виде, в каком он происходит, без текста сообщения (диагностика).
В выводе --json ошибка, завершающая команду, представляет собой одну строку в stderr, {"error":{"code":"…","message":"…"}}, и код выхода говорит то же самое, что и code. Каждый код также находится в справке по кодам выхода.
По коду завершения
| Код | Название | Что обычно означает | Где |
|---|---|---|---|
1 | internal_error | сбой самого tg | сообщить |
2 | validation_error | опечатка в команде или опции, значение или сочетание параметров, которое tg не принимает; имя, совпадающее с несколькими чатами | неизвестная команда, значения, несколько чатов |
3 | configuration_error | ошибка config.json, прокси отказал или недоступен, либо база новее tg | настройки, прокси, база |
4 | authentication_error | нет входа, сессия завершена или хранилище ключей недоступно | нет сессии |
5 | permission_error | отказ permissions профиля или Telegram | разрешения, Telegram, PEER_FLOOD |
6 | not_found | чат, сообщение или человек не найден; база пустая | чат, база |
7 | confirmation_required | чат отсутствует в получателях или некому подтвердить действие | получатели, подтверждение |
8 | rate_limited | часовой лимит или ожидание Telegram | лимит, FLOOD_WAIT |
9 | timeout | Telegram не ответил или сработал --timeout | зависание |
10 | network_error | Telegram недоступен | сеть |
11 | provider_error | Telegram отклонил запрос | отказ |
12 | provider_unavailable | сбой на стороне Telegram | сбой |
13 | invalid_response | tg не может прочитать ответ; пока только my.telegram.org | приложение |
14 | outcome_unknown | соединение оборвалось после записи; действие могло выполниться | неизвестный результат |
130 | cancelled | Ctrl-C или отказ от подтверждения | Ctrl-C |
Сначала: tg personal doctor
tg personal doctorБез подключения показывает зависимости команд: версию, среду выполнения, конфигурацию, сессию, данные приложения, переменные TG_*_DIR, базу, журнал отправок и записи запусков. Работает даже при неисправности остальных команд. Отсутствие сессии отображается в результате, а не как ошибка: код остаётся 0. Сессия и хеш не выводятся, только наличие.
tg personal doctor --online--online тоже один раз подключается и читает аккаунт. Он ничего не отправляет и ничего не отмечает как прочитанное. Без него логин отображается как not checked: только --online говорит вам, что Telegram по-прежнему принимает сессию. --online также сообщает о неправильных часах на этом компьютере и о том, заморозил ли Telegram или закрыл аккаунт (что показывает tg personal doctor).
Установка
tg не найден после установки
Каталог команд npm отсутствует в PATH.
- Linux и macOS. Каталог —
$(npm prefix -g)/bin. Добавьте его вPATHчерез~/.zshrcили~/.bashrc:export PATH="$(npm prefix -g)/bin:$PATH". - Windows. Каталог показывает
npm prefix -g, обычно%APPDATA%\npm. Проверьте наличие в$env:Path. Терминал, открытый до установки Node, не видит обновлённыйPATH: откройте новый. - PowerShell сообщает «running scripts is disabled on this system». npm устанавливает
tg.ps1рядом сtg.cmd, а PowerShell по умолчанию запрещает скрипты. Используйтеtg.cmdили разрешите скрипты своему пользователю:Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. - Другая
tgнаходится первой. Другая программа тоже может называтьсяtg.which -a tg(илиGet-Command tg -Allв PowerShell) показывает все; вызовите нашу по полному пути или поставьте её папку первой.
Без установки доступна команда npx @wirecat/tg-cli personal doctor.
npx @wirecat/tg-cli использует старую версию
npx сохраняет скачанное. Запросите новую версию: npx @wirecat/tg-cli@latest.
Вход и профили
"укажите профиль: tg <profile> … — профили на этом компьютере: …"
Код выхода 2. Команда работает с аккаунтом, но профиль ничем не указан: нет первого слова, нет TG_PROFILE. tg никогда не выбирает профиль сам, даже если он всего один. Сообщение перечисляет профили на этом компьютере; поставьте один из них перед командой:
tg personal chats list # the profile named in the message
export TG_PROFILE=personal # or for the whole shell sessionНа компьютере, где ещё нет ни одного профиля, сообщение предлагает выполнить tg personal setup; вместо personal подойдёт любое имя.
"нет сессии для профиля "personal" — запустите tg personal setup в локальном терминале"
Код выхода 4. Этот профиль ещё не входил в систему на этом компьютере или вышел из системы. Проверьте, какой профиль вы имели в виду: первое слово команды или TG_PROFILE (profiles).
tg personal setup # guided first run
tg work chats list # or name the profile you logged in toЕсли вход выполнен, проверьте различия TG_CONFIG_DIR, TG_STATE_DIR, TG_CACHE_DIR между входом и запуском, например в разных терминалах. Они меняют место хранения входа. tg config show показывает заданные переменные; env | grep TG_ — все.
При первом запуске без ключей приложения ошибка предлагает tg personal setup (или tg work setup для рабочего профиля). Варианты входа описаны в tg setup --help. Агент может прочитать tg skill show до входа. Прерванная или истёкшая сессия требует tg personal session start, затем повторной проверки настройкой.
«Учетные данные приложения Telegram не найдены… хотя вход в систему был выполнен на этом компьютере»
Код 4. Файл сессии есть, но хранилище ключей недоступно. Это бывает в cron, ssh, службах и MCP-клиентах с сокращённым окружением tg.
Не входите повторно: это добавит устройство и не исправит окружение. В Linux задайте XDG_RUNTIME_DIR (обычно /run/user/ и номер из id -u):
XDG_RUNTIME_DIR=/run/user/$(id -u) tg personal chats listПодробнее о cron см. работа по расписанию. Системное хранилище ключей также может быть заблокировано до тех пор, пока вы не войдёте в систему на компьютере. Тогда serve и запуск tg personal schedule вместо этого завершаются с кодом 12 (provider_unavailable): служба пробует снова каждые 30 с, а ежедневное или разовое расписание ждёт входа и повторяет попытки до 12 часов.
"не авторизован или сессия завершена — запустите tg session start"
Код 4. Telegram больше не принимает сессию: её завершили с другого устройства (Настройки → Устройства) или через tg personal session end. Войдите через tg personal session start.
"tg session start задаёт вопросы — запустите его в терминале"
Код выхода 2. Вход по телефону или первый вход, при котором нужно зарегистрировать приложение, требует, чтобы человек ввёл ответы. Запустите его в терминале. Вход по QR без терминала вместо этого печатает код текстом
(когда агент выполняет вход в систему).
"ширина терминала 40 столбцов, а QR-коду нужно 49"
Код не рисуется, потому что перенесённый по строкам код невозможно отсканировать. Расширьте терминал: следующий код, который пришлёт Telegram, будет нарисован.
"my.telegram.org сообщает, что приложение было создано, но на его странице ничего не отображается"
Код выхода 13, во время tg personal session start --app auto. На сайте нет API, поэтому tg следует за веб-формой, а форма изменилась или неожиданно ответила. Другие ошибки с сайта — это код выхода 11, как указано на сайте. Вместо этого используйте способ по умолчанию: tg personal session start открывает сайт в вашем браузере, и вы вставляете идентификатор и хэш приложения (приложение из my.telegram.org).
Ответ пришел не из того профиля
tg config show показывает профиль и источник выбора. TG_PROFILE выбирает профиль, TG_PROFILE_LOCK запрещает другие. Опечатка в команде может быть прочитана как профиль (ниже).
"неизвестная команда '…'"
Код 2. В терминале это одна строка с ✗; при выводе в конвейер — validation_error в JSON в stderr. Первое слово, не являющееся командой, считается профилем, поэтому опечатка в команде может стать именем профиля:
tg chat list
✗ unknown command 'list' "chat" is not a command, so it was read as a profile name — which left "list" to be one.Здесь chat считается профилем, а list не является командой. Правильно — chats, во множественном числе. Список: tg commands. Опечатка в команде после профиля подсказывает правильную:
✗ unknown command 'lst' (Did you mean list?). Неизвестная опция — та же ошибка, код 2.
Настройки и значения опций
«… не является настройкой tg»
Код выхода 3. В config.json есть настройка, которую tg не знает, значение неправильного типа, или файл не является
корректным JSON. Ошибка называет первую проблему и, если JSON не сломан, команду config unset, которая её
убирает; выполните эту команду как есть. Это намеренный отказ: молчаливо пропущенная настройка стоит полдня.
tg personal doctor перечисляет все проблемы в файле (опечатка — ошибка).
"--limit принимает целое число от 1 и выше"
Код 2. --page тоже требует целое положительное число. Иначе неверное значение могло бы молча вернуть пустой список.
"id< принимает идентификатор сообщения"
Код 2. id< и id> в запросе messages list принимают идентификатор сообщения ('id<4242'); messages comments говорит то же про идентификатор комментария. Время указывают в date> или date<: ISO 8601 в кавычках ('date>"2026-09-20T09:00:00+02:00"') или период назад (30m, 2h, 1d).
"--at-time принимает время, например 2026-09-25T09:00, или задержку, например 30 м, 2 часа, 1 д"
Код 2. --at-time принимает локальное время или задержку в минутах, часах, днях, не секундах. Минимум минута от текущего момента, максимум год.
"--timeout принимает время с единицей измерения — 500 мс, 30 с, 2 м, 4 ч или 1 д"
Код 2. --timeout и TG_TIMEOUT требуют число с единицей ms, s, m, h, d; число без единицы запрещено.
"--all и --page запрашивают разные вещи; используйте одно или другое"
Код 2. --all запрашивает все строки, --page — одну страницу. Команда отклоняет сочетание, а не выбирает молча один параметр.
Поиск чата
"… соответствует 3 чатам — назовите один по его идентификатору"
Код 2. Название подходит нескольким чатам. Ошибка перечисляет их идентификаторы, JSON — candidates. Повторите с идентификатором. tg не угадывает получателя.
"нет совпадений в чате..."
Код 6. Ни одно название не содержит введённый текст. Попробуйте tg personal chats list 'title:*<part of it>*' --offline, идентификатор, @username или me для «Избранного». Личный чат называется именем собеседника в вашем Telegram.
«Telegram этого не знает (…)»
Код 6. Чат, пользователь, имя или сообщение недоступны аккаунту: PEER_ID_INVALID, USERNAME_NOT_OCCUPIED, MSG_ID_INVALID и подобные ошибки. Сообщение могло быть удалено, идентификатор — относиться к другому чату. contacts lookup не находит человека, скрывающего номер или не имеющего аккаунта.
Ограничения и разрешения
"Telegram просит подождать N секунд до следующего запроса"
Код 8. Ограничение Telegram (FLOOD_WAIT). Подождите указанный срок; JSON содержит retry_after_ms. Обычно возникает после серии запросов, например chats list --all или долгого messages sync. Для messages sync и messages download --all увеличьте --pause.
Команда сама выжидает запрос до 10 секунд, не больше двух раз, и сообщает об этом в stderr: «Telegram asks to wait 3 s before … — waiting, then going on». serve и watch ждут до 2 минут. Более долгое ожидание завершает отдельный запрос этой ошибкой; пакетное чтение истории возвращает частичный результат с issue и действиями для восстановления. tg также запоминает ожидание: пока оно не закончится, та же команда сразу завершается ошибкой, не обращаясь к Telegram снова, а tg personal doctor и tg personal server status показывают его в flood.
Как сочетаются темп, ожидания и параллельные команды: ограничения и ожидания.
«Telegram ограничил сообщения этого аккаунта как спам (PEER_FLOOD)»
Код 5. Telegram ограничивает аккаунт, который написал слишком многим людям не из своих контактов. Читать он по-прежнему может. Напишите @SpamBot в приложении Telegram: он скажет, до какого срока. Новые отправки только ухудшают положение, поэтому tg задерживает все отправки на час и сообщает об этом; каждый новый отказ начинает час заново. tg personal doctor показывает задержку в flood.send_block. Когда @SpamBot скажет, что ограничение снято, tg personal flood clear снимет задержку вместе с любым ожиданием, которое запомнил tg. Отказ замороженного аккаунта задерживает отправки так же — до даты, названной Telegram; tg personal doctor --online устанавливает и снимает эту задержку.
"профиль... отправил N сообщений за час..."
Код 8. Лимит профиля — sends_per_hour, по умолчанию 30. Ошибка показывает время следующей отправки. Увеличивайте лимит только намеренно: tg personal config set sends_per_hour <n>.
«чат… нет в списке получателей профиля…»
Код 7. Список получателей включён, чат отсутствует. Добавьте его сами при необходимости: tg personal recipients add <chat>. Агент должен остановиться и спросить вас.
"профиль... не дает... писать" или "профиль... запрещает..."
Код выхода 5, прежде чем что-либо будет отправлено в Telegram. permissions профиля отказался: deny тоже прекращает чтение, readonly останавливает изменение. В ошибке указано, какой ключ, где он был установлен, и команда, которая это позволяет (что может делать профиль). Агент должен остановиться и спросить вас, а не менять настройку.
«…спрашивает, прежде чем действовать»
Код 7. Уровень команды — ask, но ответить некому: нет терминала или указан --json, --jsonl. Ошибка укажет подтверждающий параметр: --allow-dangerous для удаления, --yes для остальных изменений. Добавляйте его только осознанно. Агент должен спросить вас.
Запомнил ожидание
Когда Telegram сообщает, сколько времени ждать, tg запоминает это время для операции и чата. Повторная попытка до ее завершения сразу же завершается неудачно с кодом выхода 8 без другого запроса. Отказ из-за того, что аккаунт заморожен или ограничен из-за спама, также может приостановить отправку.
tg personal flood clear забывает об этих ожиданиях и удержаниях на этом компьютере. В Telegram это ничего не меняет, поэтому запускайте его только после снятия ограничения. У него нет инструмента MCP: агент не должен снимать блокировку только для того, чтобы попытаться еще раз. Только tg personal doctor --online проверяет логин, состояние аккаунта и часы; tg personal doctor без него не доказывает, что вход работает.
Telegram и сеть
«Телеграм отказался:…»
Код 5, если аккаунту запрещено действие, 11 — остальные отказы. Имя причины приходит от Telegram и содержится в JSON как provider_error; введённые аргументы не повторяются. Некоторые причины объясняются отдельно:
- Telegram распознаёт речь только для Premium — код
5. Используйте локальную модель:tg personal models download parakeet-v3, затемtg personal messages transcribe <chat> <id> --local. - Сообщение не является голосовым или видеозаметкой — код
2: указан другой тип сообщения. - Telegram не смог распознать речь — код
11; попробуйте--local.
«Ошибка Telegram: …»
Код 12. Ошибка на стороне Telegram. tg ничего не изменил; повторите через минуту. Если отправляли сообщение, сначала проверьте чат.
«невозможно связаться с Telegram (…)»
Код выхода 10. Соединение не удалось установить или оно оборвалось: нет сети, брандмауэра, прокси-сервера или DNS. Код в скобках говорит какой (ECONNREFUSED, ENOTFOUND, ETIMEDOUT). Команды, отвечающие из архива, работают без сети: tg personal --offline chats list. Там, где Telegram заблокирован, установите прокси (настройка прокси).
«прокси… недоступен» или «… отказано»
Код 3. Проблема в прокси, а не в Telegram: до Telegram ничего не дошло, поэтому даже отправка не ушла. tg останавливается на первом неудачном подключении, а не ждёт истечения срока.
- недоступен (
ECONNREFUSED,ENOTFOUND,ETIMEDOUT) — прокси не работает или указаны неверные адрес или порт. - refused: … auth … или refused the tunnel (HTTP 407) — неверные имя пользователя или пароль. Задайте их снова:
tg personal config set proxy -. - refused the tunnel (HTTP 403 или 502) — прокси не хочет или не может подключиться к Telegram.
tg personal doctor показывает используемый прокси, откуда он взят (TG_PROXY или настройки) и идёт ли через него Bot API. Чтобы попробовать без прокси: tg personal config unset proxy. MTProxy с неверным секретом обычно выглядит как зависание, а не как отказ: ограничьте время через --timeout 30s.
Команда зависает
Одноразовые команды закрывают соединение и выходят. Без ответа Telegram команда завершается с кодом 9 и timeout. Чтобы ограничить время и увидеть место остановки:
tg personal --timeout 30s --trace chats list--timeout охватывает всю команду, включая вход в систему, и завершает ее кодом выхода 9 после закрытия соединения. В --trace строка → без ← после нее - это запрос, который ушел и больше не вернулся: сеть или Telegram, а не tg (чтение трассировки).
Если результат выведен, но команда не выходит, это сбой. Через пять секунд tg перечисляет открытые ресурсы (tg: finished, but … stayed open) и выходит. Приложите эту строку к обращению. watch, serve, mcp serve должны работать до остановки.
После отправки
outcome_unknown после отправки
Код 14. Соединение оборвалось после отправки, и сообщение могло уйти. Не отправляйте его повторно без изменений. Используйте --operation-id из ошибки: Telegram исключит дубликат.
tg personal messages send <chat> "<the same text>" --operation-id <id from the error>После --at-time проверьте tg personal messages scheduled <chat>: отложенная отправка никогда не повторяется.
Закрепление, открепление, реакция, отметка о прочтении, удаление, голос, закрытие опроса, изменения папок и контактов завершаются так же, когда Telegram не отвечает. Сообщение говорит, безопасно ли повторять. Создание папки повторять небезопасно: сначала посмотрите tg personal chats folders list, иначе появится вторая папка.
Ctrl-C
Код 130. Команда остановлена и соединение закрыто. При остановке отправки сначала проверьте чат (tg personal messages list <chat> --limit 3): сообщение могло уйти. Фоновый messages sync продолжит работу; остановите через tg personal store jobs cancel <job>.
Ответ кроме y на запрос подтверждения даёт тот же код; действие не выполнено.
Локальный архив и поиск
"хранилище сообщений написано более новой версией..."
Код выхода 3. Другой CLI или более новый tg обновил локальное хранилище таким образом, что эта версия не может его прочитать. Запустите tg upgrade. Ничего в архиве не пропадает (архив и другие версии).
"две разные копии хранилища: … — ничего не перемещено и не изменено"
Код выхода 3, при первом запуске после обновления. Хранилище один раз переносится в папку WireCat, а в старой папке и в папке WireCat лежат файлы wirecat.db с разным содержимым — обычно потому, что более старый tg, max или memo после переноса создал новое хранилище на старом месте. Ничего не изменено. Оставьте нужное хранилище, перенесите другое в сторону и запустите команду снова. Обновляйте вместе все CLI, которые пользуются общим хранилищем.
"для профиля пока ничего не записано — запустите команду один раз без --offline"
Код 6. --offline, store status, store export читают только локальную базу, а профиль ещё ничего не сохранил. Сначала выполните онлайн-команду, например tg personal chats list.
search messages ничего не находит
Поиск в архиве (--backend archive, --offline или --discover) читает только то, что сохранила эта машина. Без этих параметров обычный поиск по словам может также обращаться к Telegram. Пустой результат в неполной истории не доказывает, что сообщение никогда не отправляли. Прочитайте чат (tg personal messages list <chat>) или получите его историю с помощью tg personal messages sync, затем повторите поиск (поиск в архиве). tg personal store check показывает, какие чаты требуют обновления.
Чат читается как полученный полностью, но старые сообщения отсутствуют
Снова выполните tg personal messages sync <chat>. Команда читает сообщения старше самого старого в базе, независимо от того, считался ли чат полным, и доходит до первого сообщения чата; для длинного чата увеличьте --limit. Держите --page-size не больше 100: Telegram возвращает до 100 сообщений за запрос.
Фоновый сервер
"tg serve уже запущен для профиля..."
Код 2. Разрешён один serve на профиль. tg personal server status показывает процесс и время запуска; tg personal server stop останавливает запущенный через server start или службу.
serve остановился сам по себе
Причина находится в tg personal server logs. Если Telegram завершил вход, пока работал serve, он примерно в течение 15 минут выходит с кодом 4 и не перезапускается: выполните tg personal session start, затем tg personal server start. Если обновления Telegram перестали приходить по другой причине, он выходит с кодом 12, и systemd запускает его снова.
Фоновый сервер не запускается
tg personal server status --json включает stopped и unit.exitCode, когда последний нормальный выход был таким, при котором служба не перезапускается. Для выхода 4 возобновите сессию с помощью tg personal session start, затем tg personal server start. tg personal server logs говорит, почему. В службе обычной причиной является связка ключей: служба запускается до открытия связки ключей или без XDG_RUNTIME_DIR. После перемещения Node или tg запустите tg personal server install еще раз: служба использует пути, с которыми её установили (запускается как служба).
Сообщить о проблеме
tg personal doctor reports show # what a report holds, and what it never holds; writes nothing
tg personal doctor reports create # write it to a file, and say where to send it
tg personal doctor reports create --run <id> # about another run; ids from tg personal runs listcreate записывает tg-report-<time>.json в текущую папку (или --output), доступную для чтения только вам. Он содержит версию, среду выполнения и операционную систему, ответ tg personal doctor, последний неудачный запуск — операцию каждого запроса, продолжительность и код ошибки — и только последние 20 попыток отправки, результат и длину. Каждый идентификатор чата, сообщения и аккаунта заменяется меткой, которая ничего не значит за пределами файла. Он не содержит текста сообщения, заголовков чатов, имен, номеров телефонов, учетных данных сессии или приложения. Неудачный запуск сохраняется отдельно, даже если record установлен в false (неудачные запуски).
Создайте обращение на GitHub: опишите действия и результат, приложите файл. Обращение и файл публичные: сначала прочитайте его.
⚠ Не прикладывайте каталог состояния, файл сессии или ~/.local/share/WireCat/: они содержат доступ к аккаунту и ваши сообщения.
Частичный результат и действия при ошибке
Каждый неудавшийся элемент частичного результата содержит actions: что проверить, какую настройку
изменить, сколько подождать или какой элемент пропустить. retryable не разрешает автоматически повторять запись: при
outcome_unknown сначала проверьте, произошло ли действие. Ограничения API нельзя увеличить
локальной настройкой; для них уменьшите или разделите входные данные.
У пакетной загрузки или чтения истории отдельный отказ возвращает частичный результат с кодом
выхода 0, complete: false и batch или issue. Файлы и предыдущие страницы остаются сохранены.
После долгой паузы сервера messages sync одного чата содержит issue.retry_after_ms и границу
resume; запрос всех чатов возвращает отдельные issue, а загрузка использует checkpoint. До
окончания паузы не повторяйте запросы. Частичное фоновое задание имеет состояние partial и
повторяется через tg personal store jobs retry. Проверяйте полноту ответа, а не только код выхода.