Как установить OpenCode и подключить к нему модели

Что такое OpenCode и чем он отличается от Claude Code и Cursor

OpenCode это открытый ИИ-агент для программирования, который работает в терминале, отдельным приложением или в браузере. Репозиторий на ноябрь 2026 собрал больше 226 тысяч звёзд, код открыт под лицензией MIT, а релизы выходят почти каждую неделю: 13 ноября вышел 2.3.0.

Терминал остаётся основным сценарием, хотя есть и десктопное приложение, и веб-версия. Агент читает файлы, правит код, запускает команды и держит сессию с историей, а модели берёт из каталога models.dev или из любого OpenAI-совместимого API.

Разница с Cursor в том, где живёт агент. Cursor объединяет редактор и агента в одном окне. OpenCode запускается отдельно от редактора, в терминале, и правит тот же проект, что открыт в IDE. Разница с Claude Code в выборе модели: у Claude Code выбор ограничен моделями Anthropic, а доступ идёт по подписке или через API, у OpenCode подключается любой провайдер, включая локальные модели через Ollama.

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

Установка OpenCode на Linux, macOS и Windows

Быстрее всего поставить через скрипт. Команда сразу скачивает установщик и запускает его, поэтому выполнять её стоит только с официального домена:

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

Пакетные менеджеры тоже поддерживаются. На macOS через Homebrew:

brew install anomalyco/tap/opencode-v2

Через npm ставится пакет @opencode/cli:

npm install -g @opencode/cli

У пакета есть postinstall-скрипт, который выбирает нативный бинарник под платформу. Поэтому в bun и pnpm установку запускают с явным разрешением скриптов: bun install -g --trust @opencode/cli или pnpm add -g --allow-build=@opencode/cli @opencode/cli. Есть варианты для AUR и mise, последний требует версию 2026.10.9 или новее.

Для Windows официально менеджеры пакетов не поддерживаются. Нужен отдельный бинарник со страницы загрузок либо установка в WSL. Десктопное приложение выходит сборками для macOS, Windows и Linux в форматах deb, rpm и AppImage, а в Docker OpenCode запускается образом ghcr.io/anomalyco/opencode с версионными тегами, например 2.0.0.

Проверить установку можно за секунду: opencode --version печатает версию, а запуск opencode в каталоге проекта открывает полноэкранный интерфейс.

Веб-версия открывается командой opencode pair. Она печатает одноразовую ссылку, которая живёт пять минут и ведёт на локальный адрес с портом вида 127.0.0.1:49374.

Первый запуск и подключение модели

Первым делом подключите модель командой /connect: интерфейс спросит провайдера и ключ. После подключения /models показывает каталог, а выбор действует на текущую сессию и конфиг не меняет.

Часть моделей доступна без ключа: это модели провайдера opencode с нулевой ценой на вход, и для первых проб их хватает. Скрыть их можно переменной OPENCODE_DISABLE_FREE_MODELS=1 в окружении сервера, а для общей фоновой службы командой opencode service set env OPENCODE_DISABLE_FREE_MODELS 1.

Кроме провайдеров напрямую есть два платных варианта от команды проекта. OpenCode Go стоит 10 долларов в месяц и открывает доступ к отобранным моделям. OpenCode Console работает по схеме оплаты за использование и выдаёт API-ключ.

Как подключить OpenRouter к OpenCode

OpenRouter подключается как обычный провайдер, потому что он уже есть в каталоге models.dev. Способов два. В первом вы выполняете /connect, выбираете OpenRouter и вставляете ключ. Во втором задаёте переменную OPENROUTER_API_KEY на сервере OpenCode, и такой путь удобнее для скриптов и CI.

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

{
  "$schema": "https://opencode.ai/config.json",
  "model": "openrouter/deepseek/deepseek-v4.1-flash",
}

На один запуск модель выбирается флагом: opencode run --model openrouter/anthropic/claude-sonnet-5.5 "Объясни этот репозиторий". Идентификатор после openrouter/ совпадает с тем, что показывает каталог OpenRouter, включая префикс ~ у моделей-алиасов. Написание у прямого провайдера и у OpenRouter различается: напрямую Anthropic отдаёт claude-sonnet-5-5, а через OpenRouter та же модель называется claude-sonnet-5.5. Строку проще копировать из /models, чем собирать вручную.

Если OpenRouter идёт через свой шлюз, адрес меняется в providers.openrouter.settings.baseURL, а пакет провайдера остаётся родной. С чужим пакетом теряется обработка reasoning, которую OpenRouter отдаёт по-своему.

Из каталога для кода удобны deepseek/deepseek-v4.1-flash и qwen/qwen3-coder, для сложных правок anthropic/claude-sonnet-5.5. Как получить ключ, поставить лимит и не платить посредникам, разобрано в статье про OpenRouter.

Модели, варианты и локальные модели

Модель задаётся строкой провайдер/модель. Через решётку добавляется вариант, чаще всего уровень reasoning: anthropic/claude-sonnet-5-5#high. Вариант выбирают для запуска, сессии, агента или команды, в корневом model он не сохраняется.

Переключить модель можно тремя способами: /models внутри сессии, флаг --model для одного запуска, поле model в конфиге как значение по умолчанию. Если настроенная модель недоступна, OpenCode берёт самую свежую из поддерживаемых, а при явном выборе отвечает ошибкой Model unavailable с полным идентификатором.

Локальные модели OpenCode находит сам. Ollama на 127.0.0.1:11434, LM Studio на 1234 и vLLM на 8000 опрашиваются при старте, и их модели появляются в каталоге с идентификаторами вида ollama/gemma3:4b или vllm/Qwen/Qwen3-Coder-30B-A3B-Instruct. Другой адрес задаётся в providers.ollama.settings.baseURL, ключ берётся из переменной через {env:OLLAMA_API_KEY}.

Одно ограничение: агенту нужна модель с вызовом инструментов. Модели только для эмбеддингов в каталог не попадают. Слабые локальные модели хуже держат длинную цепочку правок. Подбор модели под железо разобран в гайде по Ollama.

Конфигурация opencode.jsonc

Файл конфигурации один по формату и несколько по расположению. Поддерживаются JSON и JSONC, второй разрешает комментарии и висячие запятые. Поле $schema включает проверку и автодополнение в редакторе.

Файл ищется в нескольких местах: /etc/opencode/opencode.json для всей машины (на macOS /Library/Application Support/opencode), ~/.config/opencode/opencode.json для пользователя, opencode.json в корне проекта и .opencode/opencode.json рядом с проектом. Проектные файлы ищутся от текущего каталога вверх, а .opencode перекрывает прямой файл в том же каталоге.

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

Полезные поля: model для модели по умолчанию, default_agent для агента при старте, permissions для правил доступа к инструментам, agents для своих агентов, mcp для серверов Model Context Protocol, plugins, instructions и update с режимами notify, auto и disable.

Начните с трёх строк: схема, модель и агент. Остальное добавляется по мере надобности, потому что конфиг читается при каждом запуске и ошибка в нём ломает старт.

Агенты и субагенты

У агента есть системный промпт, модель и права. Встроенных четыре: build для обычной работы, plan для исследования без правок, general и explore как субагенты. Скрытые служебные агенты compaction, title и summary обслуживают сессии, выбрать их нельзя.

Свой агент задаётся markdown-файлом в ~/.config/opencode/agents/ или .opencode/agents/ проекта. Во frontmatter идут description, mode, model и permissions, а тело файла становится системным промптом. Пример ревьюера, которому запрещены правки файлов и команды оболочки:

---
description: Проверяет изменения на регрессии
mode: subagent
model: anthropic/claude-sonnet-5-5#high
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
---

Проверь текущие изменения и перечисли находки по убыванию важности.

mode бывает трёх видов: primary для основного агента сессии, subagent только для дочерних сессий, all для обоих случаев. Субагенты запускаются в фоне, каждый в своей сессии со свежим контекстом, а родитель получает отчёт, когда дочерний агент закончил работу.

Права субагента задаются отдельно, и родитель может запретить запуск всех агентов, разрешив одного конкретного правилом с action: subagent.

Разрешения, MCP-серверы и полезные команды

Права описываются списком правил. В каждом правиле три поля: действие, ресурс и эффект allow, deny или ask. Ресурс указывается шаблоном вроде git push *, а действие берётся из набора инструментов: shell, edit, read, subagent.

{
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status", "effect": "allow" },
  ],
}

Правила применяются по порядку, поэтому узкое исключение ставьте после общего запрета. Глобальные правила срабатывают раньше правил агента, и агент дополняет их своим списком. Если настройку нельзя доверять проекту, её переносят в политики: их проектный конфиг не перекрывает.

Отдельно от прав стоят политики. Ими запрещают провайдера целиком, блокируют MCP-сервер, навык или плагин, и проектный конфиг такое решение отменить не может. В управляемом парке политики остаются единственным способом удержать настройки.

MCP-серверы подключаются в конфиге. Локальный сервер запускается командой:

{
  "mcp": {
    "servers": {
      "playwright": { "type": "local", "command": ["bunx", "@playwright/mcp"] },
    },
  },
}

Из команд пригодятся opencode run для скриптов и CI, opencode mini для упрощённого интерфейса, opencode pair для веб-версии, opencode service для управления фоновым сервером и opencode debug paths для поиска базы и каталогов. Полное удаление показывает opencode uninstall --dry-run. Что дают такие серверы, разобрано в статье про MCP.

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

OpenCode бесплатный

Да, код открыт под лицензией MIT и сам агент ничего не стоит. Платятся только модели: либо по счёту провайдера, либо подпиской OpenCode Go.

Работает ли OpenCode на Windows

Да, но менеджеры пакетов не поддерживаются. Нужен отдельный бинарник или установка в WSL, плюс есть десктопное приложение.

Можно ли работать без интернета

Да, если модель локальная. Ollama, LM Studio и vLLM находятся автоматически, но модель должна поддерживать вызов инструментов.

Где хранится конфигурация

Глобально в ~/.config/opencode/opencode.json, для проекта в opencode.json или .opencode/opencode.json. Системный файл лежит в /etc/opencode.

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

Открытым кодом и выбором провайдера. Claude Code привязан к моделям Anthropic, OpenCode работает с любым API, включая OpenRouter и локальные модели.

Нужен ли ключ OpenRouter

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

Итог

OpenCode закрывает терминальный сценарий целиком: установка одной командой, подключение любой модели через /connect или переменную окружения, конфиг в проекте и свои агенты под повторяющиеся задачи. Для домашней машины хватает локальной модели, для команды удобнее OpenRouter с одним ключом и общим счётом.

Дальше имеет смысл заняться правами и субагентами: именно они превращают агента из чата в инструмент, которому можно доверить правки в репозитории. Если проект только начинается, начните с агента build и правила ask на команды оболочки, а узкие разрешения добавляйте после того, как посмотрите на поведение агента.