Если OpenCode выдаёт ошибку, не удаляйте проект и данные. По полному сообщению отделите сбой приложения от ошибки модели, доступа или плагина. Выберите 1 проверку, внесите 1 правку и повторите задачу.
В Desktop скопируйте сведения с экрана ошибки. Видите только Connection Error или зависшее окно - откройте журнал. Ключи и конфиги пока не трогайте.
Что именно не работает: окно, модель, расширение или задача?
Откройте журнал: Windows - Win+R → %USERPROFILE%\.local\share\opencode\log; macOS - Finder → Cmd+Shift+G → ~/.local/share/opencode/log/; Linux - этот же путь в файловом менеджере. Найдите ошибку по времени в имени файла.
Для подробностей запустите из терминала и повторите действие:
opencode --log-level DEBUGЕсли OpenCode не запускается, получите сообщения в терминале:
opencode --print-logsСохраните текст ошибки и время, не весь журнал. Первую проверку выберите ниже по сообщению.
Для отдельной проверки модели откройте новую сессию с той же моделью: «Ответь одним словом: готов». Не давайте ей менять файлы проекта.
| Что видите | Первая проверка | Что дальше |
|---|---|---|
| Connection Error в Desktop | Сверьте URL сервера | Адрес верный - сохраните сообщение из журнала; неверный - исправьте адрес |
| Запрос модели отклонён | Дайте запрос «Ответь одним словом: готов» | Не прошёл - выберите проверку по сообщению ниже; прошёл - проверьте рабочую задачу |
| Сбой после изменения плагина | Сохраните состояние, временно отключите локальный плагин | Помогло - возвращайте по одному; нет - верните каталог |
| «Готов» есть, задача падает | Запишите последний успешный шаг и первый сбой | Повторите этот шаг; затем проверьте целый сценарий |
Ответ «готов» не проверяет работу с файлами и инструментами. Если расширение не показывает квоту, отдельно проверьте запрос к модели.
Если OpenCode ещё не запускался и дело в установке, начните с инструкции в отдельной статье.
Какая ошибка повторяется у вашего агента? Продолжим разговор в канале:
Что сохраняем, прежде чем что-то менять?
Сначала решите, как отменить правку. Не знаете, как вернуться к исходному состоянию, - соберите данные для помощи, ничего не меняя.
| Что меняете | Что сохранить | Как вернуться / когда не трогать |
|---|---|---|
| Рабочие файлы | Копию файлов, которые меняете, входные данные и состояние задачи | Отменяйте только свои изменения, не затирая чужую работу |
| Конфиг | Исходный файл и его расположение | После неудачи верните изменённое значение. Не заменяйте весь конфиг примером |
| Сеансы и авторизация | До вмешательства - копию и проверенный способ восстановления для вашей версии | При первой проверке каталог не трогайте. Копия не гарантирует восстановления входа |
| Кеш | Содержимое, если нужен возврат; сначала закройте Desktop | Пересборка кеша не восстановит историю |
| Состояние Desktop | Выбранный URL сервера | После неудачи верните адрес. Файлы состояния не удаляйте |
По инструкции OpenCode, в ~/.local/share/opencode/ лежат auth.json с данными доступа и данные сеансов с сообщениями. В Windows это %USERPROFILE%\.local\share\opencode. При удалении всего каталога удалятся и эти данные.
Кеш расположен отдельно: ~/.cache/opencode, в Windows - %USERPROFILE%\.cache\opencode. Файлы opencode.settings.dat, opencode.global.dat, opencode.workspace.*.dat хранят состояние Desktop. Их сброс в инструкции OpenCode оставлен последним средством.
Запрос модели падает: где проверить конфиг, доступ и лимит?
По сообщению выберите 1 проверку, не весь список:
- Connection Error в Desktop: сверьте URL сервера, как описано ниже. Ключ модели пока не трогайте.
- ProviderModelNotFoundError: выполните команду и сравните выбранную модель с полным ID
providerId/modelIdв списке:
opencode models- Ошибка авторизации: проверьте статус ключа в кабинете API-сервиса. Повторный вход -
/connectв терминальном интерфейсе OpenCode. Сначала убедитесь, что сможете войти. - Сообщение о лимите: проверьте расход, баланс и условия в кабинете ответившего сервиса.
- ProviderInitError, ошибка конфига: проверьте указанный файл или поле. Глобальный -
~/.config/opencode/opencode.json(c), проектный -opencode.json(c)или.opencode/opencode.json(c). Настройки объединяются; управляемые могут перекрыть правку. - AI_APICallError: ищите причину в пояснении. Её нет - заполните шаблон помощи, ничего не меняя.
Неизвестное поле найдите в текущей схеме. В старой версии не переименовывайте plugin/provider наугад: передайте версию, поле и ошибку для помощи.
Если ключ задан как {env:VARIABLE_NAME}, без переменной OpenCode получит пустую строку. В командах замените VARIABLE_NAME именем из конфига. Значение ключа не выводится.
macOS/Linux:
if [ -n "${VARIABLE_NAME:-}" ]; then printf 'Задана\n'; else printf 'Пусто или не задана\n'; fiWindows PowerShell:
if ($env:VARIABLE_NAME) { 'Задана' } else { 'Пусто или не задана' }Проверка относится к запуску из этого терминала. Запускаете Desktop значком - уточните настройку у того, кто её делал. Передавайте имя переменной, не ключ.
Не меняйте ключ из-за одного слова Forbidden: сохраните полное сообщение, ID модели и ответивший сервис. Адрес API сверяйте с документацией сервиса, не с URL Desktop.
Подробнее о файлах и переменных - в документации конфигурации.
Что меняем: сервер, локальный плагин или кеш?
Не выполняйте всё по списку. Выберите 1 проверку по своей ошибке.
Если не работает конкретный инструмент MCP, проверяйте его подключение отдельно от запроса модели. О первом подключении MCP в OpenCode - в отдельной статье.
Сервер Desktop. Нажмите имя сервера с точкой состояния, сверьте URL. Для пробы встроенного сервера запишите адрес и нажмите «Очистить» в разделе «Сервер по умолчанию». Не помогло - верните адрес.
Не знаете, где заданы server в opencode.json(c) или OPENCODE_PORT, - заполните шаблон помощи. Не удаляйте раздел из первого найденного конфига.
Локальный плагин. Закройте приложение, запишите путь и имя каталога, временно переименуйте его. Каталоги: ~/.config/opencode/plugins/ и .opencode/plugins/ в проекте.
Перезапустите приложение. Не помогло - закройте его и верните имя каталога. Помогло - возвращайте плагины по одному с проверкой. Плагины, подключённые другим способом, при такой проверке останутся подключёнными.
Кеш. При ошибке пакета провайдера откройте в инструкции OpenCode раздел «AI_APICallError и проблемы с пакетом провайдера»: закрыть Desktop, очистить кеш, перезапустить. Данные приложения не удаляйте. Нужен гарантированный возврат - передайте ошибку по шаблону помощи без очистки.
Как проверить: стало лучше или ошибка просто исчезла с экрана?
Допустим, сбой начался после изменения плагина. Проверим ту же задачу без него.
- Запишите задачу, входные данные, версию OpenCode, модель, настройки и место ошибки. Определите, какой результат нужен и как его проверите. Сохраните начальное состояние для повтора.
- Сформулируйте гипотезу: без выбранного локального плагина задача пройдёт шаг, на котором была ошибка. Запишите, как вернёте плагин.
- Внесите 1 правку. Не меняйте заодно модель, сервер и ключ.
- Сохраните результаты неудачного запуска отдельно. Повторите задачу на исходной копии файлов, с той же моделью и данными, изменив только плагин. Нет исходной копии - остановитесь. При проверке ID модели только он будет отличием.
- Проверьте результат и целый сценарий. Отдельно проверьте новое задание, которое не использовали при выборе исправления.
- Запишите, прошла ли задача и что доделали руками. Время и расходы не измеряли - отметьте «не измерял». Дополнительное задание тоже прошло - оставьте правку. Иначе верните плагин и запишите итог.
Кстати, я снял полный гайд про связку для первого агента Hermes Agent, обязательно посмотрите.
В нём показываю проверку на разных моделях, бортовой журнал и улучшение навыка с напарником. Посмотрите, как проверять работу агента в Hermes; ошибки OpenCode в этом видео не разбираю.
Заведите бортовой журнал всех запусков, включая неудачный:
Задача:
Исходное состояние, версия, модель и настройки:
Гипотеза:
Единственная правка и способ возврата:
Результат той же задачи:
Результат дополнительного задания:
Качество:
Время:
Деньги:
Ручные исправления:
Решение - оставить или вернуть:Если открылось только окно, исходную задачу всё равно нужно проверить.
Когда агент уже выдаёт код, проверьте сам код по отдельной инструкции.
Собираете свой проект с ИИ-агентами? Посмотрите программу практикума СмыслоКода.
Проверка не помогла: что передать разработчикам?
Сначала найдите похожее обращение в списке ошибок OpenCode. Сверьте версию, модель и сообщение.
В обращении о лимите участник проекта просит версию, ОС, модель и точное сообщение. Данные аккаунта публиковать запрещает. Добавьте результаты своих проверок:
Версия OpenCode:
ОС:
Интерфейс CLI/Desktop:
Время ошибки:
Провайдер и полный ID модели:
На каком шаге и что ожидали:
Точное сообщение без секретов:
Результат нейтральной проверки:
Исходная рабочая задача и результат повтора:
Единственное изменение:
Вернули ли изменение и что после возврата:
Дополнительное задание и результат:Опишите действие и входные данные без закрытой информации, чтобы ошибку можно было повторить.
Не прикладывайте ключи, auth.json, весь конфиг и полный DEBUG-журнал. Вручную перепишите нужное сообщение, уберите секреты, адрес почты и данные аккаунта.
Закрытие обращения как дубликата не подтверждает, что ошибку исправили.
На каком шаге у вас не работает OpenCode и что показал повтор той же задачи после правки? Напишите в комментариях в канале, без ключей и данных аккаунта.
Частые вопросы
Источники
- OpenCode: поиск неисправностей - журналы, каталоги данных и кеша, сервер Desktop, локальные плагины, доступ и ID модели.
- OpenCode: конфигурация - расположение и слияние настроек, схема и подстановка переменных окружения.
- OpenCode: обращение об исчерпанном лимите - запрашиваемые сведения, запрет публикации данных аккаунта, закрытие как дубликата.
Новые материалы - дайджестом, без спама
Гайды выходят регулярно. Подпишись, чтобы не пропускать: пришлю подборку в Telegram или на email. Раз в неделю или каждый день - выбираешь сам.
