OpenCode в России: установка и настройка без VPN

OpenCode в России ставится и запускается штатно — упирается всё не в сам агент, а в модель, к которой он ходит за ответами. Лечится это подменой провайдера: в opencode.json прописывается OpenAI-совместимый эндпоинт, и агент работает как обычно, без VPN и зарубежной карты. Готовый эндпоинт даёт AI для кода от PurpleSchool — ключ выдаётся сразу, оплата в рублях. Ниже — установка OpenCode на macOS, Linux и Windows, конфиг провайдера целиком, выбор модели и разбор ошибок подключения.

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

OpenCode — терминальный AI-агент: вы запускаете его в папке проекта, он читает файлы, правит код и выполняет команды. Сам инструмент ставится из npm и при установке ни о каком регионе не спрашивает.

Всё упирается в следующий шаг. Агент — это оболочка, думает за него модель стороннего вендора, и платить надо вендору. У разработчика из России тут два барьера сразу: доступ к API зарубежного провайдера и оплата зарубежной картой. Вторую половину этой истории мы разбирали отдельно — в статье про оплату OpenAI из России.

Отсюда и обходной путь. Сам OpenCode остаётся оригинальным, меняется только адрес, по которому он ходит за ответами: в конфиге агента провайдер описывается явно, и туда подставляется шлюз, совместимый с OpenAI API. Ни патчей, ни форков, ни туннелей — одна секция в JSON-файле.

Способ подключения: OpenCode через AI для кода от PurpleSchool

PurpleSchool держит OpenAI-совместимый прокси по адресу https://app.purpleschool.ru/api-v2/public/ai-proxy/openai/v1. Для OpenCode это обычный провайдер: вы получаете ключ в личном кабинете, платите за него рублями и прописываете адрес в конфиг агента.

Инструкция для OpenCode есть на самой странице AI для кода — в списке клиентов, рядом с Codex CLI, Claude Code и Pi. Дальше в статье разобраны те же шаги, но подробнее и с объяснением, что зачем.

Порядок такой: поставить OpenCode, положить ключ в переменную окружения, описать провайдера в opencode.json, запустить агент и выбрать модель. Четыре шага, каждый ниже отдельным разделом.

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

npx @purpleschool/ai-for-code

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

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

Ставится агент во всех системах одинаково — через npm, так что npm должен быть установлен.

npm install -g opencode-ai

macOS и Linux

Кроме npm, здесь работает официальный install-скрипт:

curl -fsSL https://opencode.ai/install | bash

Годятся оба варианта — выбирайте тот, что привычнее.

Windows

Для нативной Windows ставьте через npm, командой из начала раздела. Рекомендованный вариант — WSL: тогда OpenCode устанавливается внутри дистрибутива по инструкции для Linux, и дальше все шаги — ключ, конфиг, запуск — выполняются тоже внутри WSL. Смешивать не нужно: если агент живёт в WSL, а переменную окружения вы задали в PowerShell, агент её не увидит.

Как задать ключ PurpleSchool

Ключ не вписывается в конфиг открытым текстом — он читается из переменной окружения PURPLESCHOOL_API_KEY. Так конфиг можно спокойно коммитить в репозиторий: секрета в нём нет. Если переменные окружения — для вас новая тема, разберитесь с ней до конфига, дальше будет проще.

macOS и Linux

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

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

Команда export помечает переменную как экспортируемую, то есть видимую дочерним процессам — именно поэтому её увидит запущенный из этой оболочки OpenCode. Без export переменная останется внутри самой оболочки, и агент до неё не дотянется.

После правки откройте новый терминал или перечитайте конфиг оболочки. Проверить, что переменная на месте:

echo $PURPLESCHOOL_API_KEY

Windows

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

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

Первая строка кладёт ключ на постоянное хранение — он подхватится во всех новых окнах. Вторая нужна, чтобы не перезапускать текущее окно прямо сейчас. Если OpenCode работает у вас в WSL, эти команды не помогут: ключ надо задавать внутри WSL по инструкции для Linux.

Как настроить провайдера в opencode.json

Это главный шаг. Создайте в корне проекта файл opencode.json или дополните существующий, не выбрасывая из него остальные настройки:

{
  "$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. Здесь @ai-sdk/openai: конфигурация использует OpenAI Responses API.
• options.baseURL — адрес прокси. Именно эта строка и заменяет обращение к зарубежному эндпоинту.
• options.apiKey — подстановка {env:PURPLESCHOOL_API_KEY} означает «взять значение из переменной окружения». Ключ в файл не попадает.
• models — список моделей провайдера. Вместо <MODEL_NAME> подставьте имя доступной вам модели: один раз ключом объекта, второй — в поле name. На странице подключения в качестве примера имени модели фигурирует gpt-5.6-sol; актуальный список смотрите в личном кабинете.

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

Как запустить OpenCode и выбрать модель

Перейдите в папку проекта и запустите агент:

opencode

Дальше нужно переключиться на свою модель — по умолчанию агент её не выберет. В интерфейсе выполните команду:

/models

Откроется список, в нём будет провайдер PurpleSchool OpenAI Proxy — то самое значение из поля name в конфиге — и под ним модель, которую вы прописали в models. Выбираете её, и агент начинает ходить через прокси.

Если провайдера в списке нет, дальше идти нет смысла: значит, OpenCode не прочитал ваш конфиг. Чаще всего это запуск не из той папки, где лежит opencode.json.

Что делать, если OpenCode пишет forbidden или не подключается

Точную причину OpenCode показывает в тексте ошибки — читайте его, а не гадайте. Дальше — что проверять по порядку, от самого частого к редкому.

Ошибка доступа или forbidden. Провайдер отклонил запрос. Проверьте по очереди: ключ действительно попал в переменную окружения (echo $PURPLESCHOOL_API_KEY в том же терминале, где запускаете агент); ключ не деактивирован в личном кабинете; на балансе остались токены; имя модели в models совпадает с доступным вам, а не осталось плейсхолдером <MODEL_NAME>.

Агент не видит ключ. Самый частый сюжет — переменную задали в одном окружении, а агент запустили в другом: правили ~/.zshrc, а работаете в bash; сохранили переменную в PowerShell, а OpenCode живёт в WSL. Проверяйте echo ровно в том терминале, из которого стартует агент.

Провайдера нет в /models. Конфиг не подхватился. Убедитесь, что файл называется именно opencode.json, лежит в корне текущего проекта и содержит валидный JSON — лишняя запятая ломает весь файл целиком. Запускайте opencode из корня проекта.

Запросы уходят не туда. Сверьте baseURL посимвольно, вместе с хвостом /v1. Обрезанный или лишний сегмент пути — причина ошибок, которые выглядят как что угодно, только не как опечатка в адресе.

Чем OpenCode отличается от Codex и Claude Code

Через один и тот же прокси PurpleSchool работают несколько агентов, и выбор между ними — вопрос привычки, а не доступности.

• OpenCode — агент с настраиваемым списком провайдеров. Провайдер описывается в JSON прямо в проекте, поэтому разные репозитории могут ходить к разным моделям. Это же и его минус: конфиг нужен в каждом проекте.
• Codex — агент OpenAI. Настраивается один раз глобально, через ~/.codex/config.toml, и умеет работать не только в терминале, но и расширением в VS Code и Cursor. Подробный разбор — в статье про Codex в России.
• Claude Code — агент Anthropic, подключается через Anthropic-эндпоинт того же прокси и настраивается переменными окружения. Отдельная инструкция — в статье про Claude Code в России.

Ключ и баланс токенов при этом общие. Попробовать все три и оставить тот, что удобнее, ничего дополнительно не стоит.

Сколько стоит подписка на OpenCode через PurpleSchool

Отдельной подписки «на OpenCode» нет — вы платите за токены, а каким агентом их тратить, решаете сами. На сентябрь 2026 года на странице AI для кода три тарифа с ежемесячным списанием:

Неизрасходованные токены переносятся на следующий месяц, а если лимита не хватает, сверх подписки можно докупать пакеты токенов. Расход виден в личном кабинете в реальном времени — там же ключи и деактивируются.

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