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

Почти все обращения сводятся к нескольким сюжетам: система ругается на установщик, приложение не видит старых данных, нужны логи, нужно перенести или сбросить базу, не поднимается MCP-сервер, gRPC-вызов падает с ошибкой TLS, не включается синхронизация. Ниже — что делать в каждом случае и что приложить, если проблема осталась.

Windows: предупреждение SmartScreen#

Установщик для Windows пока не подписан. SmartScreen показывает синее окно «Система Windows защитила ваш компьютер»: нажмите Подробнее, затем Выполнить в любом случае. Компонент WebView2, если его нет в системе, установщик поставит сам. Берите файл только по ссылкам с сайта — откуда именно, написано на странице Установка.

macOS: Gatekeeper и карантин#

Сборка для macOS подписана Developer ID и нотаризована Apple, поэтому обычный сценарий — открыть DMG, перетащить Tetiva в «Программы» и запустить без единого предупреждения.

Если система всё же говорит, что приложение повреждено или его нельзя проверить, дело почти всегда в файле, а не в подписи: недокачанный DMG, распаковка сторонним архиватором, корпоративный прокси, подменивший содержимое. Скачайте файл заново. Снимать атрибут карантина вручную (xattr -d com.apple.quarantine /Applications/Tetiva.app) стоит только если вы уверены в источнике файла — это отключает проверку, а не чинит её.

Как получить логи#

Tetiva пишет логи в стандартный вывод в формате JSON, файла логов нет. Значит, приложение нужно запустить из терминала и смотреть вывод там.

macOS:

/Applications/Tetiva.app/Contents/MacOS/client

Windows, PowerShell:

& "$env:LOCALAPPDATA\Programs\Tetiva\client.exe"

Это %LOCALAPPDATA%\Programs\Tetiva\client.exe. Копия, которую поставила версия 1.2.0 или более ранняя, лежит в C:\Program Files\Saveliy Yudin\Tetiva\client.exe.

Linux:

tetiva

Воспроизведите проблему при запущенном терминале и сохраните вывод — именно он больше всего помогает разобраться.

Приложение не видит прежних данных#

При первом запуске после переименования приложения каталог ~/.gophercourier переименовывается в ~/.tetiva. Есть один случай, когда этого не происходит: если ~/.tetiva уже создан. Тогда приложение работает с новым, пустым каталогом, а старый остаётся нетронутым рядом. Закройте Tetiva, переименуйте пустой ~/.tetiva, верните на его место старый каталог и запустите приложение снова.

Перенос и сброс данных#

Всё локальное лежит в одном каталоге: ~/.tetiva на macOS и Linux, %USERPROFILE%\.tetiva на Windows. Внутри — data.db и файлы WAL рядом с ним.

• Перенести на другую машину. Закройте приложение (иначе WAL не будет дописан в базу) и скопируйте каталог целиком.
• Сбросить до чистого состояния. Закройте приложение и удалите каталог. Локальные коллекции, история и куки пропадут навсегда; воркспейсы, которые были в Tetiva Cloud, вернутся после следующего входа в аккаунт.
• Хранить базу в другом месте. Задайте TETIVA_DATA_DIR перед запуском. Учтите: приложение, запущенное двойным кликом из Finder или меню «Пуск», переменных из профиля оболочки не видит — запускайте из терминала теми же командами, что выше.

Тема, размер шрифта и перенос строк в этом каталоге не хранятся и при переносе не поедут — их придётся выставить заново, см. Настройки.

MCP-сервер не поднимается#

Если переключатель «MCP-сервер» в настройках включён, а статус остался «Остановлен», чаще всего порт занят другой программой или вторым экземпляром Tetiva. В логе при старте будет строка MCP port unavailable — приложение продолжает работать, отключается только MCP. Смените порт в настройках и перезапустите приложение.

Другой сюжет — сервер работает, но агент получает 401. Значит, конфиг написан до появления токена доступа. Нажмите «Скопировать конфиг» в настройках, выберите своего клиента и замените этим старую запись. Подробности — на странице MCP-сервер.

gRPC: ошибка TLS или «too many colons in address»#

Если сервер работает через TLS, а адрес указан без схемы, или наоборот, ошибка подскажет, что поправить: The server may require TLS — use grpcs:// или The server may not use TLS — remove grpcs://. Исправьте адрес или щёлкните замок перед ним. Ошибка too many colons in address на другом устройстве значит, что там стоит Tetiva 1.2.1 или более ранняя версия, которая не понимает адрес со схемой: обновите её. Подробности — на странице gRPC.

Синхронизация не включается#

Жёлтая иконка облака с точкой означает, что почта не подтверждена. У облачного аккаунта подтверждение и повторная отправка письма живут на сайте: перейдите по ссылке из письма, а если письма нет — запросите его заново в кабинете. Кнопка Send again в приложении есть только на экране Check your email, который у облачных пользователей появляется редко. Красная иконка и надпись Session expired — sign in to resume sync означают, что сессия закончилась и нужно войти заново. Разбор всех состояний — на странице Синхронизация.

После обновления просит войти заново#

При первом запуске после обновления с версии 0.17.0 или старее приложение показывает уведомление Sign-in has changed with this update. Please sign in again. с кнопкой Sign in. Это не сбой: схема авторизации изменилась, и прежняя сессия не подходит. Войдите заново один раз — до этого синхронизация не стартует.

Обновлять стоит все устройства сразу: старая версия не примет схему авторизации, которой она не знает, и синхронизация на отставшем устройстве встанет с состоянием Sync stopped — update the app to read the newest changes.

Не открывается браузер при входе#

Вход в аккаунт через браузер и грант Authorization Code открывают браузер сами. Если он не открылся, в панели ожидания есть Open again и Copy link — ссылку можно открыть руками; в форме OAuth 2.0 те же две кнопки. Грант Device Code браузер не открывает: он показывает адрес страницы подтверждения, код с кнопкой копирования рядом и одну кнопку Open.

Отдельный случай — грант Authorization Code: ему нужен свободный порт на 127.0.0.1, и занятый порт приложение назовёт ошибкой прямо под полем Redirect Port. Впишите туда 0, и порт выберется сам. Подробности — на страницах Синхронизация и Авторизация.

Куда сообщать о проблеме#

Баги и предложения — в issues репозитория github.com/tetiva-app/client. Короткие вопросы и обратная связь — в Telegram.

Приложите: версию из секции About в настройках, операционную систему, шаги воспроизведения и вывод из терминала. Проверьте перед отправкой, что в выводе не осталось токенов и адресов ваших внутренних сервисов.