Гайды

Как настроить конфигурацию OpenCode

18 октября 2026 · 11 минут чтения

Проверка фактов

Юлия Найпак

Методист по автоматизации. Сверяет паспорт инструмента с документацией вендора.

Автор Р

Редакция

Коллектив авторов, редакторов и иллюстраторов статей на сайте блога онлайн-университета «Зерокодер». Пишем…

Черновик готовит редакция с помощью ИИ. За стандарт издания отвечает главный редактор — Валерий Курземнек.

Материал редакции Зерокодера. Счёт по выдаче снят собственным прогоном 18 октября 2026 года; цитаты источников приведены дословно. Обновлено: октябрь 2026.

Настроить конфигурацию OpenCode можно через файл opencode.json в формате JSON или JSONC. В документации проекта указано, что OpenCode поддерживает оба формата, а конфигурация задаётся именно JSON-файлом. Файлы из разных мест объединяются, и более поздний источник переопределяет ранний только при конфликте ключей. Ниже — где лежат файлы, как они взаимодействуют и как проверить результат. Мы скачали подборку результатов веб-поиска по запросу «Как настроить конфигурацию OpenCode»: текст отдали 10 из 10.

Что такое конфигурация OpenCode и её границы

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

В документации проекта прямо сказано: «Вы можете настроить opencode, используя файл конфигурации JSON». Это ключевая граница — вся настройка идёт через JSON-файл. Формат поддерживает комментарии, что удобно для пояснений прямо в файле.

Основной файл содержит модель и автообновление. Ниже — минимальный пример; оформление задаётся отдельно в tui.json.

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true
}

Схема $schema даёт редактору подсказки по допустимым полям. Модель указывается в формате provider/model. Автообновление принимает true, false или "notify"; тему оформления задайте в отдельном tui.json.

Границы продукта определяются тем, что описано в документации. Настройки делятся на уровни: серверные, интерфейсные и проектные. Интерфейсные настройки вынесены в отдельный файл tui.json, о чём сказано в справочнике конфигурации на GitHub: терминальные настройки используют отдельный tui.json или tui.jsonc, а поля темы и привязок клавиш располагаются прямо в корневом объекте этого файла.

Для терминала нужен современный эмулятор, например WezTerm, Alacritty, Ghostty или Kitty, и ключи API для поставщиков LLM, которых вы хотите использовать. Это описано в разделе «Введение» документации проекта.

Условия доступа и где искать актуальные требования

Актуальные требования стоит сверять с официальной документацией проекта по адресу dev.opencode.ai. Именно там публикуется справочник по конфигурации, который обновляется вместе с продуктом.

Для работы в терминале нужны две вещи, названные в документации: современный эмулятор терминала и ключи API для поставщиков LLM. Установка выполняется несколькими способами. Самый простой — через сценарий установки:

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

Альтернативные способы включают пакетные менеджеры. Для Node.js доступна команда npm install -g opencode-ai, для Bun — bun install -g opencode-ai, для pnpm и Yarn — аналогичные команды. В macOS и Linux работает Homebrew: brew install anomalyco/tap/opencode. В документации отмечено, что tap opencode даёт самые последние версии, а официальная формула обновляется реже.

Для Windows документация рекомендует использовать подсистему Windows для Linux (WSL), поскольку она обеспечивает лучшую производительность и полную совместимость с функциями opencode. Также доступны Chocolatey (choco install opencode) и Scoop (scoop install opencode). В Arch Linux работают sudo pacman -S opencode и paru -S opencode-bin. Есть вариант через Docker: docker run -it --rm ghcr.io/anomalyco/opencode. Бинарный файл можно получить в разделе Releases.

С OpenCode можно использовать любого поставщика LLM, настроив его ключи API. Для новичков документация рекомендует OpenCode Zen — подобранный список моделей, протестированных и проверенных командой проекта. Подключение выполняется командой /connect в TUI с переходом на opencode.ai/auth.

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

Порядок действий: от установки до рабочего конфига

Документированный порядок начинается с установки и подключения провайдера, затем идёт создание конфигурационных файлов. Разберём пошагово.

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

Шаг 2. Подключение провайдера. Запустите команду /connect в TUI, выберите opencode и перейдите по адресу opencode.ai/auth. Войдите в систему, добавьте платёжные данные и скопируйте ключ API. Вставьте ключ в появившееся поле. Альтернативно можно выбрать другого поставщика.

Шаг 3. Создание глобального конфига. Поместите модель, провайдеров и автообновление в ~/.config/opencode/opencode.json. Для общих настроек интерфейса используйте отдельный ~/.config/opencode/tui.json, как указано в справочнике.

Шаг 4. Создание проектного конфига. Добавьте opencode.json в корень проекта. Документация подчёркивает: конфигурация проекта имеет наивысший приоритет среди стандартных файлов и переопределяет как глобальные, так и удалённые конфигурации. Этот файл безопасно регистрировать в Git, он использует ту же схему, что и глобальный.

Шаг 5. Инициализация проекта. Выполните /init в TUI: документация описывает анализ проекта и создание AGENTS.md в его корне. Этот файл даёт агенту контекст о вашем коде.

Шаг 6. Настройка TUI. Для интерфейсных настроек используйте ~/.config/opencode/tui.json глобально или tui.json рядом с проектным конфигом. В справочнике на GitHub приведён пример с темой, привязками клавиш, скоростью прокрутки и стилем курсора.

После этих шагов конфигурация готова. Проверка описана в следующем разделе.

Учебный пример и критерии самостоятельной проверки

Предлагаем упражнение, которое показывает, как работает слияние конфигов. Это наша учебная конструкция.

Задача. Задать глобальное автообновление в opencode.json, тему в отдельном tui.json, а модель — в проектном opencode.json. Проверить применение всех трёх настроек.

Глобальный файл ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": true
}

Глобальное оформление ~/.config/opencode/tui.json:

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode"
}

Проектный файл opencode.json в корне проекта:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5"
}

В этом учебном примере глобальный и проектный opencode.json объединяют настройки автообновления и модели. Оформление читается отдельно из tui.json. Принцип слияния относится к соответствующим конфигурациям: при конфликте побеждает источник с большим приоритетом.

Критерии проверки. После запуска opencode:

1. Интерфейс использует тему opencode — это видно визуально.
2. Модель anthropic/claude-sonnet-4-5 активна — проверьте через команду или в интерфейсе.
3. Автообновление включено — при наличии новой версии поведение соответствует значению true.

Если хотя бы один пункт не выполняется, проверьте путь к файлу и синтаксис JSON. Комментарии допустимы только в формате JSONC.

Упражнение с приоритетом. Задайте другую тему в проектном tui.json и сравните с глобальным оформлением. Для модели отдельно сравните глобальный и проектный opencode.json. Так вы проверите приоритет внутри каждой схемы.

Упражнение с MCP. Добавьте в проектный конфиг сервер MCP и проверьте, что он доступен агенту. Пример структуры приведён в документации проекта:

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Поле enabled управляет активностью сервера. Документация описывает сценарий, когда организация предоставляет серверы MCP, отключённые по умолчанию, а пользователь включает нужные в локальной конфигурации.

Смежные варианты: глобальный, проектный и пользовательский конфиг

OpenCode поддерживает несколько мест для конфигурации с разным приоритетом. Понимание этой иерархии определяет, какой файл редактировать.

Документация проекта перечисляет источники в порядке загрузки, где более поздние переопределяют более ранние. Справочник на GitHub приводит тот же порядок с нумерацией от низкого приоритета к высокому.

Удалённая конфигурация загружается первой и служит базовым слоем. Она извлекается автоматически при аутентификации у провайдера, который её поддерживает. Глобальная конфигурация переопределяет настройки удалённой организации. Проектная конфигурация переопределяет и глобальную, и удалённую.

Пользовательская конфигурация задаётся через переменную среды OPENCODE_CONFIG и загружается между глобальной и проектной. Пример из документации:

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

Отдельно есть переменная OPENCODE_CONFIG_DIR для пользовательского каталога конфигурации. В этом каталоге выполняется поиск агентов, команд, режимов и плагинов, и он должен иметь ту же структуру, что стандартный каталог .opencode.

Каталоги .opencode и ~/.config/opencode используют множественные имена для подкаталогов: agents/, commands/, modes/, plugins/, skills/, tools/ и themes/. Единственные имена вроде agent/ поддерживаются для обратной совместимости.

Управляемые настройки на macOS задаются через .mobileconfig и MDM. Они имеют наивысший приоритет и не переопределяются пользователем.

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

Типичные проблемы и способы диагностики

Проблемы с конфигурацией обычно связаны с путями, синтаксисом или приоритетом. Разберём частые случаи и проверяемые способы диагностики.

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

Файл не находится. OpenCode при запуске ищет файл конфигурации в текущем каталоге, затем поднимается до ближайшего каталога Git. Если вы запускаете opencode вне проекта, проектный конфиг не подхватится. Проверьте, что находитесь в нужной директории.

Ошибка синтаксиса. Формат JSON требует корректных кавычек и запятых. Комментарии допустимы в JSONC. Если файл не парсится, проверьте его валидатором или упростите до минимального набора полей.

TUI-настройки не работают. Тема и привязки клавиш располагаются в корне отдельного tui.json. Справочник на GitHub указывает именно эту структуру. Проверьте путь к файлу и его схему.

Провайдер не загружается. Проверьте список disabled_providers — провайдер из этого списка не загрузится даже с ключом API. Обратная настройка — enabled_providers: когда список задан, провайдеры вне его игнорируются.

MCP-сервер недоступен. Проверьте поле enabled в конфигурации сервера. Организационная конфигурация может отключать серверы по умолчанию, а локальная — включать их.

Диагностика через уровни логирования. В справочнике на GitHub описано поле logLevel с вариантами DEBUG, INFO, WARN, ERROR. Повышение детализации используйте для разбора ошибок загрузки конфигурации.

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

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

Где лежит конфиг OpenCode?

Глобальный конфиг расположен по пути ~/.config/opencode/opencode.json. Проектный файл opencode.json размещается в корне проекта. Для интерфейсных настроек используется отдельный tui.json в тех же каталогах. Пользовательский путь задаётся переменной OPENCODE_CONFIG, а каталог — переменной OPENCODE_CONFIG_DIR. Точные пути приведены в документации проекта.

Как настроить модели в OpenCode?

Модель задаётся ключом model в формате provider/model, например anthropic/claude-sonnet-4-5. Для простых задач есть ключ small_model — он используется для генерации заголовков и сводок. Список отключённых провайдеров задаётся через disabled_providers, список разрешённых — через enabled_providers. Модель можно задать как глобально, так и в проекте.

Как подключить MCP в OpenCode?

Сервер MCP описывается в секции mcp конфигурационного файла. Указываются тип, URL и поле enabled. Для удалённого сервера тип — remote. Организационная конфигурация может предоставлять серверы отключёнными по умолчанию, а локальная конфигурация включает нужные. Пример структуры приведён в документации проекта.

Как настроить OpenCode в Windows?

Документация рекомендует использовать подсистему Windows для Linux (WSL) — она обеспечивает лучшую производительность и полную совместимость с функциями opencode. Также доступны установка через Chocolatey командой choco install opencode и через Scoop командой scoop install opencode. В документации отмечено, что поддержка установки через Bun находится в разработке. Пути к конфигу в WSL совпадают с Linux.

Что делать, если настройки не применяются?

Проверьте приоритет источников: проектный конфиг переопределяет глобальный, а управляемые настройки переопределяют всё. Убедитесь, что файл находится в правильном каталоге и opencode запускается из нужной директории. Проверьте синтаксис JSON и отсутствие конфликтующих ключей. Для детальной диагностики повысьте уровень логирования через поле logLevel.

Если вы работаете с локальными моделями, пригодится материал о запуске Nemotron GGUF локально. Для сравнения агентных инструментов есть обзор аналогов Qwen Code. Подключение внешних инструментов через MCP разобрано в статье о подключении Blender к Claude через MCP.