Конфиг opencode.json: провайдеры, модели и ключи по шагам

Справочник по opencode.json: расположение файлов, порядок слияния, основные поля и пошаговое подключение своего OpenAI-совместимого провайдера с ключом из переменной окружения.

7 мин · · opencode · подключение · инструменты

opencode.json — файл, в котором opencode хранит модель по умолчанию, провайдеров, агентов, MCP-серверы и разрешения. Глобальный конфиг лежит в ~/.config/opencode/opencode.json, проектный — в корне репозитория, и они сливаются: проектные значения перекрывают глобальные. Своего OpenAI-совместимого провайдера добавляют блоком provider с пакетом @ai-sdk/openai-compatible, адресом API с суффиксом /v1 и списком моделей. Ниже каждый шаг разобран на примере Zukko.

Если opencode вам пока незнаком, начните с обзора что это за агент. Здесь речь только о самом файле конфигурации.

Где лежит конфиг и как файлы сливаются

Файл называется opencode.json или opencode.jsonc. Во втором варианте допустимы комментарии и висячие запятые. При ручной правке это снимает часть синтаксических ошибок.

УровеньПуть
Глобальный~/.config/opencode/opencode.json
Проектныйopencode.json в корне проекта или .opencode/opencode.json
Системный, macOS/Library/Application Support/opencode
Системный, Linux/etc/opencode
Системный, Windows%ProgramData%\opencode

Конфиги не заменяют друг друга, а дополняют. Если в глобальном файле описан провайдер, а в проектном указана только модель, opencode учтёт оба значения. Когда одно и то же поле задано в обоих местах, побеждает проектная настройка.

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

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

bash
export OPENCODE_CONFIG=/path/to/my/custom-config.json

Расположение файлов и правила слияния описаны в документации по конфигу на 29.10.2026.

Поле $schema

Первой строкой в конфиге стоит ссылка на схему https://opencode.ai/config.json. Редактор с поддержкой JSON Schema подскажет имена полей и подсветит опечатку ещё до запуска opencode.

Основные поля opencode.json

Поля формата OpenCode 1:

ПолеНазначение
modelмодель по умолчанию в виде provider/model
small_modelлёгкая модель для служебных задач вроде генерации заголовков
providerпровайдеры: адрес API, ключ, список моделей
agent, default_agentописание агентов и агент по умолчанию
mcpподключение MCP-серверов
permissionчто агенту разрешено делать без подтверждения
plugin, instructionsплагины и файлы инструкций
enabled_providers, disabled_providersкакие провайдеры включены, а какие скрыты

Минимальный рабочий конфиг выглядит так:

bash
{
  "$schema": "https://opencode.ai/config.json",
  "model": "zukko/claude-sonnet-5-5",
  "small_model": "zukko/qwen3.8-flash"
}

Префикс zukko — это идентификатор провайдера из блока provider, о нём ниже. Роли, отдельные модели и инструменты для агентов разобраны в статье про настройку агентов opencode. Формат блока mcp лучше сверять с документацией той версии opencode, которая у вас установлена.

Разрешения

В OpenCode 1 разрешения задаются объектом:

bash
{
  "permission": { "edit": "ask", "bash": "ask" }
}

В OpenCode 2 это упорядоченный массив правил:

bash
{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" }
  ]
}

OpenCode 1 и OpenCode 2

В OpenCode 2 поля называются во множественном числе: providers, agents, plugins, permissions. Старые поля по-прежнему принимаются. V2 читает конфиги формата V1 из тех же мест и нормализует их в памяти, файл при этом не переписывается. Поэтому примеры в этой статье написаны в формате V1: они работают в обеих версиях. Подробности — в руководстве по миграции на 29.10.2026.

Как добавить OpenAI-совместимого провайдера

opencode берёт каталог моделей с models.dev и поддерживает 75+ провайдеров через AI SDK. Если нужного провайдера там нет или нужен свой адрес API, его описывают вручную.

Шаг 1. Положить ключ в переменную окружения

Ключ Zukko начинается с fetch_. Чтобы он не попал в репозиторий, задайте его в окружении:

bash
export ZUKKO_API_KEY="fetch_..."

Строку стоит добавить в профиль оболочки, иначе переменная пропадёт после закрытия терминала.

Шаг 2. Описать провайдера в блоке provider

bash
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "zukko": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Zukko",
      "options": {
        "baseURL": "https://api.zukko.pro/v1",
        "apiKey": "{env:ZUKKO_API_KEY}"
      },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" },
        "claude-opus-5-5": { "name": "Claude Opus 5.5" },
        "deepseek-v4-pro": { "name": "DeepSeek V4 Pro" },
        "qwen3.8-flash": { "name": "Qwen 3.8 Flash" }
      }
    }
  },
  "model": "zukko/claude-sonnet-5-5",
  "small_model": "zukko/qwen3.8-flash"
}

Что здесь важно:

  • zukko — идентификатор провайдера. Он же становится префиксом в model.
  • npm — пакет AI SDK. @ai-sdk/openai-compatible работает с /v1/chat/completions. Для моделей, которые обслуживаются через /v1/responses, документация opencode предлагает @ai-sdk/openai.
  • baseURL — адрес обязательно с /v1 на конце.
  • apiKey — подстановка {env:ZUKKO_API_KEY}. Если переменная не задана, подставится пустая строка. Есть и вариант {file:path/to/file}, который читает значение из файла.
  • models — ключи должны совпадать с идентификаторами из каталога символ в символ. Поле name влияет только на отображение.

Для модели можно указать limit.context и limit.output — размер контекста и ответа. Значения берите из описания модели, а не наугад. Схема блока описана в документации по провайдерам на 29.10.2026.

Шаг 3. Сверить имена моделей

Актуальный список моделей Zukko с ценами отдаёт GET-запрос:

bash
curl https://api.zukko.pro/v1/models

Копируйте идентификаторы из ответа, а не набирайте по памяти: claude-sonnet-5-5 и claude-sonnet-5-standard — разные модели с разной ценой.

Вариант из документации Zukko

В инструкции Zukko для opencode используется другой путь: переопределяется встроенный провайдер anthropic.

bash
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.zukko.pro/v1",
        "apiKey": "{env:ZUKKO_API_KEY}"
      },
      "models": {
        "claude-opus-5-5": {},
        "claude-sonnet-5": {}
      }
    }
  }
}

Это вариант, который описан и проверен в документации Zukko, но только для моделей Claude. Провайдер zukko из шага 2 собран по шаблону из документации opencode: начните с короткого запроса, и если какая-то модель ведёт себя в нём нестабильно, вернитесь к варианту с anthropic.

Суффикс /v1 нужен и здесь, хотя провайдер называется Anthropic. Это частая путаница: в Claude Code переменная ANTHROPIC_BASE_URL задаётся без /v1, а в opencode — с ним. Короткая версия подключения без справочной части есть в статье opencode: подключение к API-шлюзу за пять минут.

Где хранятся ключи

Ключ можно передать тремя способами: полем options.apiKey в конфиге, командой /connect с пунктом Other или командой opencode auth login.

Два последних способа сохраняют ключ вне opencode.json. В OpenCode 1 это файл ~/.local/share/opencode/auth.json, в OpenCode 2 — SQLite-база ~/.local/share/opencode/opencode.db.

Проектный opencode.json часто попадает в git. Поэтому ключ в нём лучше не писать открытым текстом, а использовать {env:...} или {file:...}. Дополнительная страховка на стороне Zukko — дневной и месячный лимит расхода в долларах на ключ.

Как выбрать модель

Команда /models переключает модель для текущей сессии и не меняет конфиг. Модель по умолчанию задаётся полем "model": "provider/model", как в примерах выше.

Разумно разделить роли: основная модель для работы с кодом и дешёвая small_model для служебных задач. Несколько вариантов из каталога Zukko:

МодельЦена, вход/выход
claude-opus-5-5$0.8/$4 за 1M
claude-sonnet-5-5$0.4/$2 за 1M
deepseek-v4-pro$0.07/$0.21 за 1M
qwen3.8-flash$0.03/$0.07 за 1M

Для сравнения, 10 млн входных токенов: на claude-sonnet-5-5 это 10 × $0.4 = $4, на qwen3.8-flash — 10 × $0.03 = $0.3. Другие способы сократить расход собраны в чек-листе по экономии токенов.

Типичные ошибки конфига

Неверный JSON. Лишняя или пропущенная запятая, незакрытая скобка — и opencode не прочитает файл. Помогает $schema в редакторе или переход на opencode.jsonc.

Нет /v1 в baseURL. Симптом — 404 на каждый запрос. Проверьте, что адрес заканчивается на /v1.

Модель не из каталога. Ошибка 404 model_not_found означает, что имени нет в списке https://api.zukko.pro/v1/models. Сверьте написание, включая точки и дефисы.

Моделей нет в /models. Обычно файл лежит не там, где его ищет opencode, или в нём синтаксическая ошибка. Проверьте путь, исправьте запятые и перезапустите opencode.

Пустой ключ. {env:ZUKKO_API_KEY} превращается в пустую строку, если переменная не задана в той оболочке, из которой запущен opencode.

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

Частые вопросы

Чем opencode.json отличается от opencode.jsonc?

Содержимое одно и то же. В .jsonc дополнительно разрешены комментарии и висячие запятые, поэтому его удобнее править вручную.

Можно ли хранить ключ прямо в opencode.json?

Можно, через options.apiKey. Но если файл лежит в репозитории, ключ окажется в истории git. Надёжнее {env:ZUKKO_API_KEY} или /connect.

Почему для opencode нужен /v1, а для Claude Code — нет?

Claude Code сам добавляет путь к адресу из ANTHROPIC_BASE_URL. opencode ожидает полный адрес API, поэтому https://api.zukko.pro/v1 указывается с суффиксом.

Меняет ли команда /models конфиг?

Нет. Она действует только на текущую сессию. Постоянный выбор задаётся полем model.

Как оплачивается работа через Zukko?

Баланс в долларах, списываются только использованные токены, абонентской платы нет, пополнение от $1. Сравнение со встроенным вариантом opencode — в статье OpenCode Zen или свой провайдер.

zukko

Платите в 25×
меньше

за Claude Code & ChatGPT

Один ключ fetch_* и base URL api.zukko.pro — в Cursor, Claude Code, Codex и любом SDK.

opencode json: провайдеры и конфиг opencode по шагам · Zukko