Конфиг 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 есть переменная окружения:
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 | какие провайдеры включены, а какие скрыты |
Минимальный рабочий конфиг выглядит так:
{
"$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 разрешения задаются объектом:
{
"permission": { "edit": "ask", "bash": "ask" }
}В OpenCode 2 это упорядоченный массив правил:
{
"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_. Чтобы он не попал в репозиторий, задайте его в окружении:
export ZUKKO_API_KEY="fetch_..."Строку стоит добавить в профиль оболочки, иначе переменная пропадёт после закрытия терминала.
Шаг 2. Описать провайдера в блоке provider
{
"$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-запрос:
curl https://api.zukko.pro/v1/modelsКопируйте идентификаторы из ответа, а не набирайте по памяти: claude-sonnet-5-5 и claude-sonnet-5-standard — разные модели с разной ценой.
Вариант из документации Zukko
В инструкции Zukko для opencode используется другой путь: переопределяется встроенный провайдер anthropic.
{
"$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 на Windows, macOS и Linux: пошаговоОфициальные способы установить opencode на macOS, Linux и Windows, выбор между OpenCode 1 и 2, первый запуск и настройка Zukko с ключом в переменной окружения.
- Opencode бесплатно: какие модели доступны и где их ограниченияСам opencode бесплатный, а встроенный провайдер даёт набор бесплатных моделей, включая Big Pickle. Разбираем, какие это модели, что они делают с данными и сколько стоит работа агента, когда бесплатного перестаёт хватать.
- Настроить OpenClaw с Zukko — выбор провайдера и конфигOpenClaw подключается к Zukko как собственный провайдер. Разбираем два варианта API, готовые конфиги openclaw.json и типичные ошибки.
- OpenCode Go и Zen: подписка, цены, лимиты и альтернатива со своим ключомOpenCode Go — подписка с долларовыми лимитами по моделям, Zen — оплата по факту из предоплаченных кредитов. Разбираем цены, лимиты и оплату по документации на 29.10.2026 и считаем, когда выгоднее свой ключ.
- Claude Code, opencode, Aider, Cline: чем harness отличаются друг от другаВсе они читают проект и правят код. Различия — в том, сколько спрашивают, сколько тратят и куда встроены.
- opencode: подключение к API-шлюзу за пять минутopencode — терминальный агент с открытым исходным кодом. Он умеет работать с любым совместимым API: нужно указать адрес и ключ.