Диагностика команд 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 itruns 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' --jsonsearch 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 и не открывает сырые
журналы фоновых заданий. Полный результат частичной команды содержит действия для восстановления;
диагностическая запись сохраняет только безопасные идентификаторы и коды.