МессенджерыTelegram

Диагностика команд CLI Telegram

Проверьте окружение, настройки и подключение CLI для Telegram и подготовьте диагностический отчёт.

Используйте эту страницу, когда команда завершается неудачно, зависает или выполняется слишком долго, и вы хотите понять, почему. Вы сможете наблюдать за выполнением командных запросов, вести учет выполнения, проверять установку и отправлять отчет о проблеме, не содержащий текста сообщения.

Несколько слов, которые используются на этой странице:

  • Запуск — это один вызов tg от начала до выхода.
  • Запись о запуске — это папка, в которой хранится то, что сделал один запуск: его командная строка, результат и одна строка на каждый запрос к Telegram. Эти строки никогда не содержат текст сообщения, имена или заголовки. Что сохраняется из введённой командной строки, описано в разделе Что вы ввели.
  • tg personal doctor проверяет установку: версию, логин, настройки и локальный архив.
  • Отчет о проблеме – это один файл JSON, созданный на основе tg personal doctor, и неудачный запуск. Вы прикрепляете его к проблеме.

Что можно сделать

ЗадачаКомандаСохраняет что-нибудь?
Просматривайте каждый запрос в реальном времениtg personal --trace …нет, печатает только в stderr
Найти запуск позжеtg personal runs listкаждый запуск сохраняется сам по себе
Не сохранять один запускtg personal --no-record …ничего
Сохранять только неудачные запускиtg personal config set record falseнеудачные запуски
Проверьте установкуtg personal doctor, tg personal doctor --onlineнет
Сообщить о проблемеtg personal doctor reports createда, один файл вы отправите

Показать операции: --trace

tg personal --trace messages list "Book club" --limit 5

--trace выводит операции в stderr по мере выполнения: → — запрос, ← — ответ. Указываются идентификаторы, количество объектов, длительность и код ошибки, если она возникла.

→ messages.list    chat -1001234567890
← messages.list    chat -1001234567890  118ms  5 messages

Он также передает строки журнала библиотеки Telegram внизу. stdout не меняется, поэтому канал по-прежнему получает только данные.

Сохранить запуск: --record

Каждый запуск сохраняется сам по себе. --record нужен только командам, которые работают, пока вы их не остановите (watch, serve, mcp serve), и командам, которые WireCat Desktop запускает для себя: удачный запуск они сохраняют только с --record.

tg personal runs list        # recorded runs, newest first
tg personal runs show <run-id>  # one run: its outcome, and one line per request
tg personal runs path <run-id>  # the folder that holds it

runs show перечисляет каждый запрос к Telegram: его метод (messages.getHistory или sendMessage в Bot API), сколько он занял и чем закончился. Когда Telegram просит подождать (FLOOD_WAIT или 429 в Bot API), а tg ждёт и пробует снова, за отклонённым запросом идёт повтор как попытка 2 с временем ожидания. Запуск хранит не больше 2000 таких строк или 1 МБ, а остальные только считает.

Запись запуска — это папка под runs/<day>/ в папке состояния (~/.local/share/tg-cli/runs/ в Linux). Её имя — время и команда. Она содержит два файла:

  • run.json — команда, профиль, версии tg, Node и системы, время начала и завершения, количество запросов, результат и код ошибки;
  • events.jsonl — операции, которые показывает --trace, и каждый запрос под ними, по одной на строку.

Удачный запуск без запросов не оставляет папки: это одна строка в индексе дня, и runs show всё равно его находит.

Неудачные запуски сохраняются автоматически

Если команда завершается ошибкой, её запуск сохраняется, даже если record установлен в false; тогда в run.json есть "kept_because_failed": true. Это справедливо для каждой команды и каждой ошибки: плохой параметр, неизвестная команда, проверка перед любой работой и команды, которые никогда не подключаются (models, server, upgrade). Сбой до запуска команды, например файл конфигурации, который не загружается, сохраняется как запуск с именем tg. Что запись хранит из командной строки, описано в разделе Что вы ввели; в запуске, настройки которого не загрузились, скрыто каждое введённое значение, которое может быть текстом.

Поэтому к отчёту о проблеме всегда можно приложить неудачный запуск. Не сохранить неудачный запуск можно только с --no-record.

Успешные поисковые и статистические запросы сохраняют свою собственную историю, помимо записей о запусках. У неё свои настройки: см. сохраненные поисковые запросы и историю.

Как сохранять только неудачные запуски

tg personal config set record false         # profile "personal": failed runs only
tg personal --no-record chats list          # this run: nothing at all

Удачный запуск хранит идентификаторы чатов, которые вы читали, а при включённом record_input — то, что вы ввели (отправленное сообщение, чат, названный по заголовку). Он хранится только на этом компьютере, доступен для чтения только вам и живёт 7 дней. Установите record в false, если не хотите хранить его вовсе.

Срок хранения

Удачный запуск хранится 7 дней (keep_successful_runs_for_days), неудачный — 30 дней (keep_runs_for_days). Папка запусков также остаётся меньше 200 МБ (runs_size_limit_mb): сверх этого первыми удаляются самые старые удачные запуски. Старые записи удаляются только при сохранении новой, проверка идёт раз в день, целыми днями, по имени папки, без чтения файлов.

Что не попадает в записи

События запуска и --trace содержат имя операции, идентификаторы, количество, продолжительность и коды ошибок. Они никогда не несут:

  • текст сообщения или подпись;
  • название чата, имя человека или имя пользователя;
  • номер телефона, код входа, пароль 2FA, сессию или хеш приложения.

Что вы ввели

run.json также хранит командную строку. Что именно сохраняется, зависит от вашей версии tg:

  • Версия, у которой record_input есть в выводе tg personal config show, хранит командную строку так, как вы её ввели, — название чата, поисковый запрос, текст сообщения, — чтобы можно было посмотреть, что вы запускали. Секрет всегда заменяется на [redacted]: значение параметра, названного по токену, паролю, парольной фразе, секрету, учётным данным, cookie, авторизации или ключу API; значение, которое tg помечает как секрет, например bot api --body; пароль внутри URL; длинная строка, похожая на токен. Чтобы снова скрывать каждое введённое значение, которое может быть текстом:

    tg personal config set record_input false     # everywhere
    tg personal config set record_input failed    # kept only in a run that failed
  • Более старая версия хранит слова команды и имена параметров, например messages list --limit. Каждое значение, которое может быть текстом, например введённое вместо <chat>, заменяется на [redacted].

Отчёт о проблеме, составленный по записи запуска, скрывает эти введённые значения в любой версии.

Проверить установку: tg personal doctor

tg personal doctor     # connects to nothing
tg personal doctor --online  # also connects once and reads the account; sends nothing to Telegram

Команда показывает версию, среду выполнения, профиль, файл конфигурации, наличие сессии и данных приложения (без значений), изменение записи хранилища ключей через TG_*_DIR, локальную базу (путь, версию, количество чатов и сообщений), отправки за последний час и сохранённые запуски.

  • config.issues перечисляет все проблемы файла настроек: некорректный JSON (со строкой и столбцом, где чтение остановилось), настройку или ключ разрешения, которых tg не знает, значение неправильного типа. Каждая проблема говорит, каким должно быть значение, но никогда не показывает само значение. Все, кроме некорректного JSON, приходят с командой config unset, которая их убирает (fix). doctor всё равно отвечает, с кодом выхода 0.
  • login — это not checked без --online. Наличие файла сессии на диске не означает, что Telegram все еще его принимает. При --online это ok или failed с подсказкой.
  • files и telegram.session.files называют каждый личный файл или папку, которые могут читать другие пользователи этого компьютера: файл настроек (ему нужен 0600) и его папка (0700), сессия, хранилище, их файлы SQLite -wal и -shm, журнал отправки и папка запусков. Каждая проблема — это { path, mode, want }, а в stderr печатается исправляющая её команда chmod: to make it private: chmod 600 '<path>'. Если профиль не назван или настройки отклонены, files проверяет только файл настроек и его папку. doctor сам никогда не меняет режим файла. В Windows Unix-права доступа не проверяются.
  • online.clock (с --online) сравнивает часы этого компьютера с часами Telegram. skew_ms положителен, когда этот компьютер впереди. Он предупреждает (ok: false) через 10 секунд. Telegram отклоняет запрос, который опережает собственные часы более чем на 30 секунд.
  • online.standing (с --online) — это active, frozen, banned, deactivated или revoked или unknown, когда ответ Telegram не может быть определен. Замороженный аккаунт может читать, но не писать. Там, где Telegram их предоставляет, указывается дата, когда аккаунт был заморожен, дата, когда Telegram его удалит, и ссылка на апелляцию. Повторный вход не восстанавливает аккаунт, закрытый Telegram.
  • flood перечисляет ожидания, которые Telegram попросил сохранить в этом профиле (deadlines) и задержать отправку (send_block). doctor только читает, за одним исключением: doctor --online записывает блокировку отправки для замороженного аккаунта. Когда он считывает аккаунт как замороженный, он удерживает отправку до даты Telegram. Когда он считает его активным, он снимает удержание. Он никогда не снимает ограничение на спам — tg personal flood clear делает это.

Отчёт об ошибке

tg personal doctor reports create          # about the newest failed run
tg personal doctor reports create --run <run-id>  # about this one

Он записывает файл JSON — то, что показывает tg personal doctor плюс запуск — и говорит, куда его отправить: новая задача на github.com/WireCatLabs/tg-cli/issues. Прочтите его, прежде чем отправить. Он не содержит текста сообщения, и каждый идентификатор отображается в виде метки, а не номера Telegram. Как сообщить о проблеме перечисляет все, что содержится в файле.

Если записи неудачного запуска нет, повторите проблемную команду: ошибка сохранится автоматически.

Анализ записей

Записи имеют формат JSON, поэтому их можно анализировать через jq. tg personal runs list --json возвращает { items, page: { limit, has_more }, meta }, где items — содержимое run.json для каждого запуска, от новых к старым:

tg personal runs list --limit 100 --json | jq '[.items[] | select(.status == "failed") | {command, error_code}]'
tg personal runs list --limit 100 --json | jq '[.items[] | .duration_ms] | add / length'  # average duration
tg personal runs list --limit 100 --json | jq '[.items[] | select(.requests > 10) | {command, requests}]'

tg personal runs show <run-id> выводит те же события таблицей без повторяющихся полей. Полный файл находится в каталоге, который показывает tg personal runs path <run-id>.

Дальше

Найти ошибку или частичный запуск

tg personal search runs error_code:rate_limited --json
tg personal search runs status:partial 'started_at>=2026-10-01' --json

search runs ищет буквальный текст в метаданных и безопасных диагностических событиях. Термы status:, error_code:, operation:, profile: и сравнения или диапазоны started_at:, а также параметры --limit и --page уточняют поиск. Одна страница — до 100 запусков; в запуске возвращается до 100 совпавших событий, events_truncated сообщает о сокращении. Ошибка отдельного файла или страницы истории создаёт частичную запись status: "partial" с неудачными ID, этапами и кодами. Текст сообщений и текст отказа сервера в неё не копируются. Запись сохраняется по умолчанию, если её явно не выключили. Поиск сам не создаёт новый запуск.

В MCP вызовите tg_read с command: "search runs"; поля arguments: query (включая условия по времени), limit, page. Он читает только записи активного профиля, не подключается к Telegram и не открывает сырые журналы фоновых заданий. Полный результат частичной команды содержит действия для восстановления; диагностическая запись сохраняет только безопасные идентификаторы и коды.