OpenCode Desktop: установка и подключение Claude

Почему OpenCode Desktop в России не подключается к Claude напрямую

Барьер здесь не в самом приложении. OpenCode — это оболочка, а думает за него модель стороннего вендора, и платить надо вендору. Для разработчика из России это два препятствия сразу: доступ к API зарубежного провайдера и оплата зарубежной картой. Инсталлятор Desktop о регионе не спрашивает вовсе — он скачивается и запускается, проблема начинается на экране выбора модели.

Отсюда и обходной путь: само приложение остаётся оригинальным, меняется только адрес, по которому оно ходит за ответами. В конфиге описывается провайдер с OpenAI-совместимым эндпоинтом, и агент работает как обычно.

Важно понять одну деталь устройства, иначе дальнейшие шаги выглядят странно. Desktop — это не самостоятельный клиент: по документации проекта приложение поднимает в фоне локальный сервер OpenCode (sidecar opencode-cli), а окно с интерфейсом разговаривает с этим сервером. Настройки провайдеров читает именно сервер, из тех же файлов, что и терминальная версия. Поэтому правка конфига в текстовом редакторе — не костыль, а штатный способ настройки.

Если вы работаете в терминале, а не в окне, вся та же схема разобрана отдельно в статье про установку и настройку OpenCode в России — там путь через npm и TUI.

Как установить OpenCode Desktop

Сборки приложения лежат на странице загрузки проекта — opencode.ai/download. Доступны версии для macOS (отдельно для Apple Silicon и для Intel), Windows x64 и Linux в пакетах .deb и .rpm. Выбирать нужно вручную: страница не всегда угадывает платформу правильно, а для macOS важно не перепутать архитектуру процессора.

macOS: пакет или Homebrew

Простой путь — скачать образ со страницы загрузки и перенести приложение в «Программы». Если на машине уже есть Homebrew, приложение ставится одной командой:

brew install --cask opencode-desktop

Ключевое слово --cask здесь обязательно: без него Homebrew будет искать консольную утилиту, а не приложение с интерфейсом. Вариант с Homebrew удобнее тем, что обновления прилетают вместе с остальными пакетами, через brew upgrade.

Windows: инсталлятор и WebView2 Runtime

Для Windows на странице загрузки нужна сборка x64 — скачанный файл запускается как обычный установщик.

Отдельно о том, на чём спотыкается большинство. Приложение рисует интерфейс движком Microsoft Edge WebView2, и этот компонент должен быть в системе. Если после установки OpenCode Desktop открывается пустым белым окном или не стартует вообще, причина почти всегда в нём: по рекомендации документации нужно установить или обновить WebView2 Runtime и запустить приложение заново. На свежих сборках Windows компонент обычно уже присутствует, на урезанных и давно не обновлявшихся — нет.

Обратите внимание: в Windows ставится нативное приложение. Если раньше вы ставили терминальный OpenCode внутрь WSL, то это две независимые установки с разными домашними каталогами — конфиг и переменные окружения из WSL приложение не увидит.

Linux: пакеты .deb и .rpm, запуск под Wayland

Для Linux выбирается пакет под дистрибутив: .deb для Debian и Ubuntu, .rpm для Fedora и родственных систем. Устанавливается он стандартным пакетным менеджером системы.

Если вы сидите в сессии Wayland и приложение открывается пустым или падает на старте, документация предлагает запустить его с переменной окружения:

OC_ALLOW_WAYLAND=1 opencode-desktop

Такая запись задаёт переменную только для одного запуска — это и нужно, чтобы сначала проверить, в Wayland ли дело. Если помогло, переменную имеет смысл прописать в ярлык запуска, а не держать в голове.

Почему форма Custom Provider в OpenCode Desktop не работает

Теперь главное место, из-за которого подключение из России ломается. В приложении есть раздел настроек с провайдерами, и там же — форма для своего OpenAI-совместимого провайдера: поля под идентификатор, имя, базовый адрес, ключ, модель. Выглядит это как ровно то, что нужно.

Форма не работает. На момент публикации в issue-трекере проекта лежит серия обращений об одном и том же: при сохранении всплывает ошибка «Custom providers are unavailable on this server», и происходит это при любых введённых данных, с любым провайдером и на любом сервере, к которому подключён клиент. По описаниям в этих обращениях обработчик сохранения в форме реализован заглушкой и завершается ошибкой безусловно, то есть флоу не может сработать в принципе.

Текст ошибки при этом сбивает с толку дважды. Во-первых, он намекает, что проблема в сервере, — а сервер тут не виноват. Во-первых и главное, он читается как «ваш регион не поддерживается», и человек идёт искать VPN. Искать не нужно: ни VPN, ни смена страны аккаунта на эту ошибку не влияют.

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

Вывод практический: форму в интерфейсе игнорируем и идём в конфиг.

Как подключить Claude через opencode.json

OpenCode читает настройки из нескольких мест: глобальный файл ~/.config/opencode/opencode.json в домашнем каталоге пользователя и opencode.json в корне проекта. На Windows глобальный путь выглядит как %USERPROFILE%.config\opencode\opencode.json. Для Desktop разумнее глобальный файл: приложение вы открываете на разных папках, и провайдер должен быть доступен в любой из них.

Ключ в переменной окружения

Ключ в конфиг открытым текстом не вписывается — он читается из переменной окружения. Так файл можно спокойно хранить в репозитории: секрета в нём нет.

На macOS и Linux строка добавляется в конфигурационный файл активной оболочки — ~/.zshrc для zsh, ~/.bashrc для bash:

export PURPLESCHOOL_API_KEY="ваш ключ"

Команда export помечает переменную как экспортируемую, то есть видимую дочерним процессам. Если тема переменных окружения для вас новая, разберитесь с ней до конфига — дальше будет понятнее.

С графическим приложением есть нюанс, которого нет у терминальной версии. Оболочка читает ~/.zshrc при запуске терминала, а приложение, запущенное двойным щелчком из «Программ» или из меню, через оболочку не проходит и переменную может не увидеть. Надёжная проверка: запустить приложение из терминала, в котором echo $PURPLESCHOOL_API_KEY уже печатает ключ. Если так провайдер подхватывается, а щелчком по иконке — нет, дело именно в этом.

В Windows ключ сохраняется в пользовательские переменные окружения:

[Environment]::SetEnvironmentVariable("PURPLESCHOOL_API_KEY", "ваш ключ", "User")

После этого приложение нужно закрыть и открыть заново: запущенные процессы новые переменные окружения не перечитывают.

Блок провайдера в конфиге

Теперь сам конфиг. Если файла нет, создайте его; если есть — добавьте секцию provider, не выбрасывая остальные настройки:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "purpleschool": {
      "npm": "@ai-sdk/openai",
      "name": "PurpleSchool OpenAI Proxy",
      "options": {
        "baseURL": "https://app.purpleschool.ru/api-v2/public/ai-proxy/openai/v1",
        "apiKey": "{env:PURPLESCHOOL_API_KEY}"
      },
      "models": {
        "<MODEL_NAME>": {
          "name": "<MODEL_NAME>"
        }
      }
    }
  }
}

Разберём по полям:

• $schema — ссылка на схему конфига. Редактор с поддержкой JSON Schema будет подсказывать поля и подсвечивать опечатки; на работу приложения поле не влияет.
• provider.purpleschool — идентификатор провайдера внутри конфига. Оставьте как есть: на него завязана остальная часть секции.
• name — подпись провайдера в интерфейсе. Именно эту строку вы увидите в списке при выборе модели.
• npm — пакет адаптера, через который OpenCode разговаривает с API.
• options.baseURL — адрес прокси, он подставляется вместо адреса по умолчанию.
• options.apiKey — запись {env:...} означает «взять значение из переменной окружения», а не «вот такая строка-ключ».
• models — модели, которые появятся в выборе. Подставьте имя модели из списка доступных в личном кабинете вместо <MODEL_NAME>; на странице подключения доступны семейства Claude, GPT и Qwen, а актуальный набор отображается в самом подключённом инструменте.

Если править JSON руками не хочется, на странице подключения есть CLI, который пропишет окружение сам:

npx @purpleschool/ai-for-code

Ручной путь всё равно стоит пройти хотя бы раз: когда что-то не заведётся, чинить придётся именно эти файлы.

Сколько стоит ключ и где его взять

Ключ выдаётся в личном кабинете AI для кода сразу после оплаты. Тарифы — подписка с ежемесячным обновлением лимита токенов:

Оплата — российской картой или через СБП, зарубежная карта и VPN не нужны. Один ключ работает на модели Claude, GPT и Qwen с общим балансом токенов.

Если вы ещё выбираете между своим ключом и встроенным шлюзом OpenCode, сравнение с ценами за токены и расчётом на одинаковых объёмах есть в статье OpenCode Zen или свой API-ключ — здесь я её не повторяю.

Частые ошибки при первом запуске

Пустое белое окно или приложение не стартует на Windows. Почти всегда WebView2 Runtime: установите или обновите компонент и запустите заново.

Пустое окно или падение на Linux. Проверьте, Wayland ли это: запустите с OC_ALLOW_WAYLAND=1.

«Custom providers are unavailable on this server». Вы пытаетесь добавить провайдера через форму в настройках. Она не работает — провайдер прописывается в opencode.json, как выше.

Провайдер в конфиге есть, но моделей в выборе нет. Сначала проверьте простое: тот ли это файл, который читает приложение, и подхватило ли оно переменную с ключом. Если файл лежит в нестандартном месте, путь к нему можно задать явно переменной окружения OPENCODE_CONFIG. Учтите и описанную выше проблему с диалогом выбора модели: на момент публикации есть обращения, что модели своего провайдера туда попадают не всегда. Если в окне не получается, а задача срочная — тот же ключ и тот же конфиг работают в терминальной версии, она ставится рядом и ничему не мешает.

Настроили в WSL, запускаете в Windows. Это разные установки с разными домашними каталогами. Конфиг и переменная окружения нужны в той системе, где реально запущено приложение.

Ошибки авторизации при первом запросе. Проверьте, что в baseURL адрес заканчивается на /v1, и что в apiKey стоит подстановка {env:PURPLESCHOOL_API_KEY}, а не имя переменной само по себе.

Заключение

OpenCode Desktop ставится в России без ухищрений: скачать сборку под свою платформу, добить WebView2 на Windows или Wayland-флаг на Linux. Единственное место, где всё ломается, — форма своего провайдера в настройках: она не работает ни у кого, и ошибка про «этот сервер» к региону отношения не имеет. Провайдер описывается в opencode.json, ключ лежит в переменной окружения, и дальше приложение работает штатно. Ключ с рублёвой оплатой и моделями Claude — на странице AI для кода.