Хотите запустить OpenCode через собственный API Key? Создайте аккаунт BetterToken и API Key, затем откройте инструкцию для OpenCode и выберите настройку через /connect или opencode.json. Укажите Base URL https://www.bettertoken.ai/v1 и текущий Model ID, выполните короткий запрос и сверьте модель, статус и расход Token в Dashboard.

Что нужно для запуска OpenCode в России

OpenCode — coding-агент для терминала. Он читает файлы проекта, работает с выбранной моделью и может выполнять действия в репозитории. Для первого запуска понадобятся:

macOS, Linux или Windows с доступом к одному из официальных способов установки;
собственный API Key BetterToken;
актуальный Model ID из BetterToken model plaza;
тестовый каталог, где можно безопасно проверить ответ агента.

BetterToken в этой схеме отвечает за внешний API-запрос. Он не гарантирует доступность сайта OpenCode, установочного файла, GitHub или обновлений. Из России к BetterToken API Endpoint можно подключаться без VPN, но это утверждение не распространяется на сторонние сайты и загрузки.

Как установить OpenCode из официального источника

Выберите один способ. Node.js нужен только для установки через npm.

macOS и Linux: официальный installer

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

npm

npm install -g opencode-ai

Homebrew

brew install anomalyco/tap/opencode

OpenCode рекомендует собственный tap, потому что формула brew install opencode, которую сопровождает команда Homebrew, может обновляться позднее.

Windows

Официальная документация предлагает Chocolatey или Scoop:

choco install opencode

scoop install opencode

После установки проверьте, что команда доступна:

opencode --version

Версия должна напечататься без command not found. Конкретный номер в статье не фиксируется: он меняется вместе с релизами.

Как работают `/connect` и `opencode.json`

У OpenCode credential и настройки provider хранятся раздельно.

/connect сохраняет API Key в ~/.local/share/opencode/auth.json.
Глобальный ~/.config/opencode/opencode.json задаёт providers и модели для пользователя.
opencode.json в корне проекта меняет настройки только для этого проекта.

Конфигурационные файлы объединяются. При конфликте более поздний источник переопределяет ранний. Для обычной локальной настройки важен такой порядок: global config → файл из OPENCODE_CONFIG → проектный opencode.json. Управляемые организацией настройки имеют отдельный высший приоритет.

1. Сохраните API Key через `/connect`

Запустите OpenCode в тестовом каталоге:

mkdir opencode-first-test
cd opencode-first-test
opencode

В TUI выполните:

/connect

Выберите Other, введите provider id bettertoken, затем вставьте свой API Key в поле credential. Не добавляйте реальный ключ в prompt, opencode.json, скриншот или Git.

После сохранения выйдите из OpenCode и убедитесь, что provider зарегистрирован:

opencode auth list

Команда должна показать provider без раскрытия самого ключа.

2. Добавьте BetterToken provider

Для настройки во всех проектах создайте или обновите:

~/.config/opencode/opencode.json

Если provider нужен только в одном репозитории, положите opencode.json в его корень. Минимальная конфигурация:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "bettertoken/YOUR_MODEL_ID",
  "provider": {
    "bettertoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "BetterToken",
      "options": {
        "baseURL": "https://www.bettertoken.ai/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "YOUR_MODEL_ID"
        }
      }
    }
  }
}

Замените YOUR_MODEL_ID точным идентификатором из текущего каталога BetterToken. Одно и то же значение должно стоять в model, ключе объекта models и его name. Не добавляйте к Base URL путь /chat/completions: OpenCode и пакет @ai-sdk/openai-compatible формируют запрос сами.

Подробные команды automatic setup и актуальные ограничения по группам моделей находятся в документации BetterToken для OpenCode. Статья оставляет Model ID плейсхолдером, потому что список доступных моделей меняется.

3. Проверьте, какой файл победил

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

~/.config/opencode/opencode.json;
значение OPENCODE_CONFIG, если переменная задана;
opencode.json в текущем проекте или ближайшем родительском каталоге до корня Git.

Не удаляйте файлы наугад. Сопоставьте поля model, provider.bettertoken.options.baseURL и provider.bettertoken.models во всех найденных конфигурациях.

Как выполнить и проверить первый запрос

Перезапустите OpenCode после изменения JSON:

opencode

Откройте выбор моделей командой:

/models

Выберите bettertoken/YOUR_MODEL_ID. Затем отправьте короткий запрос, результат которого легко проверить:

Верни только JSON: {"tool":"opencode","sum":4}. Не изменяй файлы.

Первый запрос считается подтверждённым, когда совпали четыре проверки:

OpenCode вернул валидный JSON и не изменил файлы;
в TUI выбрана модель bettertoken/YOUR_MODEL_ID;
в BetterToken Dashboard появился запрос с ожидаемыми моделью и статусом;
Dashboard показывает input, output и применимый cache Token, а также соответствующее списание.

Dashboard не нужно использовать как хранилище полного prompt или ответа: утверждение касается метаданных использования и расхода Token. Если запись не появилась, ответ мог прийти от другого provider из-за config override.

Как исправить частые ошибки

`opencode: command not found`

Закройте и снова откройте терминал. Если ставили через npm, проверьте, входит ли глобальный каталог npm в PATH. Не запускайте второй installer, пока не выяснили, куда установился первый бинарник.

`401` или ошибка credential

Выполните /connect ещё раз и выберите provider id bettertoken. Проверьте результат через opencode auth list. Не вставляйте ключ в командную строку или JSON ради быстрой проверки.

`404` или ошибка API

В provider.bettertoken.options.baseURL должен быть Base URL:

https://www.bettertoken.ai/v1

Не добавляйте /chat/completions. Если URL верен, перезапустите OpenCode и повторите короткий запрос.

`model not found`

Сверьте точный Model ID с текущей документацией и model plaza. Верхнее поле model должно иметь вид bettertoken/YOUR_MODEL_ID, а внутри provider.bettertoken.models должен существовать ключ с тем же YOUR_MODEL_ID.

OpenCode использует другую модель или endpoint

Это обычно означает config override. Сравните global, OPENCODE_CONFIG и проектный файл. Проектная настройка имеет более высокий приоритет среди стандартных файлов. После исправления полностью перезапустите OpenCode и снова проверьте /models и Dashboard.

FAQ

Нужно ли хранить API Key в `opencode.json`?

Нет. Для обычной настройки используйте /connect: OpenCode сохранит credential в ~/.local/share/opencode/auth.json. Файл конфигурации можно держать без реального ключа.

Какой Base URL нужен OpenCode?

Для OpenAI-compatible provider BetterToken используется https://www.bettertoken.ai/v1. Это Base URL, поэтому /chat/completions вручную не добавляется.

Глобальный или проектный `opencode.json` выбрать?

Глобальный файл удобен для общего provider и модели. Проектный файл подходит, когда репозиторию нужен другой Model ID или набор разрешений. При конфликте проектный файл переопределяет глобальный.

Нужен ли аккаунт OpenCode для BetterToken provider?

Custom provider использует credential выбранного API-сервиса. BetterToken выдаёт собственный API Key, но не заменяет сайт, аккаунт или другие сервисы OpenCode. Текущие требования самого инструмента проверяйте в официальной документации OpenCode.

OpenCode в России: установка, API и первый запрос