OpenCode: open-source альтернатива Claude Code. Гайд

OpenCode - open-source агент для программирования под лицензией MIT. Он работает в терминале, как desktop-приложение или расширение IDE, читает проект, правит файлы и запускает команды. От Claude Code он отличается в первую очередь моделями: OpenCode подключается к 75+ провайдерам через AI SDK, включая локальные модели в Ollama, LM Studio и llama.cpp.

Независимость от вендора имеет цену. Конфиг для локальной модели приходится писать руками, права по умолчанию широкие, качество работы целиком зависит от выбранной модели. Кроме того, в ноябре 2026 года у проекта две параллельные версии, OpenCode 1 и OpenCode 2, с разными командами установки.

Статья о том, как поставить OpenCode, подключить облачную и локальную модель, настроить агентов, права и MCP и чем он отличается от Claude Code. В конце - тест локальных моделей через Ollama на OpenCode 1.15.11: что получилось и что сломалось. Остальное описано по документации на 6 ноября 2026 года.

Что такое OpenCode

Проект живёт на GitHub в репозитории anomalyco/opencode, лицензия MIT. Старый адрес github.com/sst/opencode отдаёт редирект 301 на новый. На 6 ноября 2026 года у репозитория около 225 тыс. звёзд и 30 тыс. форков.

Интерфейсов три: TUI в терминале, desktop-приложение (в README помечено как beta) и расширение IDE. Есть и неинтерактивный режим: opencode run "задача" выполняет одну задачу и выходит, так OpenCode встраивается в скрипты и CI. Ключи провайдеров, добавленные через /connect, хранятся в ~/.local/share/opencode/auth.json.

OpenCode 1 и OpenCode 2

Сейчас развиваются две линейки. По GitHub API последним релизом помечен v1.19.5 от 28 октября 2026 года, а линейка v2 выходит параллельно: v2.2.5 опубликован 30 октября. Обе версии ставят команду opencode, и под этим именем рядом не уживаются: установщик V2 заменяет бинарь V1.

По руководству по миграции у V2 три намеренных несовместимости: новый API плагинов, новые контракты серверного API и перенос настроек терминального клиента из tui.json в один глобальный cli.json. Старый конфиг V2 читает из тех же мест и приводит к новому формату в памяти, сам файл не переписывается. Нативный формат V2 опционален, ключи в нём переименованы: agent стал agents, permission стал массивом permissions, MCP-серверы переехали в mcp.servers.

Статья описывает OpenCode 1 и его формат конфига. По руководству по миграции этот формат работает и в V2. Одно поведенческое отличие V2 касается безопасности: по умолчанию V2 не спрашивает перед доступом к путям вне проекта.

Установка OpenCode

macOS и Linux

Команды для двух версий различаются. Для OpenCode 1 документация даёт такие варианты:

# OpenCode 1
curl -fsSL https://opencode.ai/install | bash
npm install -g opencode-ai
brew install anomalyco/tap/opencode

Для OpenCode 2 команды из README и docs v2:

# OpenCode 2
curl -fsSL https://opencode.ai/v2/install | bash
npm install -g @opencode/cli
brew install anomalyco/tap/opencode-v2

Формула из основного Homebrew, brew install opencode, в README названа официальной, но обновляемой реже. Документация V1 уточняет, что сейчас она ставит V2, поэтому для V1 нужен tap anomalyco/tap. На Arch пакет opencode из официального репозитория тоже ставит V2. Скрипт установки кладёт бинарь в $HOME/.opencode/bin, этот каталог нужно добавить в PATH.

С Homebrew в тестовом окружении всплыла ещё одна деталь: brew upgrade opencode отказался загружать формулу из стороннего tap с сообщением Refusing to load formula anomalyco/tap/opencode from untrusted tap и предложил пометить tap как доверенный. Это изменение настроек доверия Homebrew, его лучше делать осознанно.

Windows

Для OpenCode 1 документация рекомендует WSL. Нативно доступны Chocolatey (choco install opencode), Scoop (scoop install opencode), npm (npm install -g opencode-ai) и Docker (docker run -it --rm ghcr.io/anomalyco/opencode). Для OpenCode 2 менеджеры пакетов Windows не поддерживаются, в docs v2 есть ссылки на отдельные бинарники под x64 и ARM64.

Проверка установки

opencode --version

Если команда не найдена после установки скриптом, проверьте, что $HOME/.opencode/bin есть в PATH, и откройте новый терминал.

Первый запуск

OpenCode запускается в каталоге проекта:

cd ~/projects/my-app
opencode

Первым делом подключите провайдера командой /connect (подробнее в следующем разделе). Затем /init: OpenCode проанализирует проект и создаст AGENTS.md в корне. Документация советует коммитить этот файл, в нём агент держит описание структуры и соглашений проекта. Как устроен этот формат и как он сочетается с CLAUDE.md, разобрано в гайде по AGENTS.md.

Несколько вещей, которые пригодятся сразу:

• @ в промпте открывает нечёткий поиск по файлам проекта, выбранный файл попадает в контекст.
• Tab переключает основной агент между Build и Plan. Plan не правит код и подходит для обсуждения плана.
• /undo откатывает последние изменения и возвращает исходное сообщение, его можно повторять несколько раз. /redo возвращает откаченное.
• /models показывает модели подключённых провайдеров.

Подключение моделей

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

Облачные провайдеры

Для облака конфиг почти не нужен: команда /connect в TUI показывает список провайдеров, спрашивает ключ и сохраняет его. В списке провайдеров Anthropic, OpenAI, Amazon Bedrock, Google Vertex AI, Azure OpenAI, OpenRouter, GitHub Copilot, Groq, DeepSeek, xAI, Together AI, Ollama Cloud и десятки других. Как устроен OpenRouter и чем он отличается от прямого ключа провайдера, разобрано в гайде по OpenRouter.

Подписки поддерживаются у части провайдеров. По документации OpenCode без дополнительной настройки работают ChatGPT Plus/Pro (вход через браузер), GitHub Copilot и GitLab Duo. Сама команда OpenCode продаёт доступ к моделям через провайдеры OpenCode Models и OpenCode Go (по docs v2 это подписка за $10 в месяц), оба опциональны.

С моделями Claude ситуация другая. Документация OpenCode прямо пишет, что существуют плагины для работы с подпиской Claude Pro/Max, что Anthropic это явно запрещает и что с версии 1.3.0 OpenCode их больше не поставляет. Документация Claude Code со своей стороны называет OAuth-вход подписки предназначенным для Claude Code и других собственных приложений Anthropic. Для Claude в OpenCode остаётся API-ключ из Claude Console:

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

Локальные модели через Ollama

Ollama подключается как OpenAI-совместимый провайдер. Проектный opencode.json, на котором проводился тест из этой статьи:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/qwen3:8b",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": {
        "qwen3:8b": { "name": "Qwen3 8B" },
        "gemma4:e4b": { "name": "Gemma 4 E4B" }
      }
    }
  }
}

Ключ в models должен совпадать с именем модели в Ollama. Проверить, что конфиг подхватился, можно командой opencode models ollama: она выводит модели провайдера в формате ollama/<модель>.

Главный параметр здесь - контекст. Документация Ollama пишет, что OpenCode нужен контекст от 64k токенов. По умолчанию Ollama выбирает его по объёму видеопамяти: 4k при VRAM меньше 24 GiB, 32k при 24-48 GiB и 256k при 48 GiB и больше (context length). На тестовой машине с 36 GiB по ollama ps получилось 32 768. Документация OpenCode при неработающих tool calls советует поднять num_ctx до 16-32k, это меньше рекомендации Ollama.

Контекст задаётся при старте сервера, а реальное значение видно в колонке CONTEXT:

OLLAMA_CONTEXT_LENGTH=64000 ollama serve
ollama ps

Больше контекста упирается в память и в потолок самой модели. У qwen3:8b он 40 960 токенов, и 64k для неё недостижимы. Подробно про выбор моделей, квантизацию и память - в гайде по Ollama.

Есть и короткий путь: ollama launch opencode. По документации Ollama он запускает OpenCode с inline-конфигом для выбранной модели и не перезаписывает ~/.config/opencode/opencode.json, а ollama launch opencode --config только настраивает интеграцию без запуска сессии. Модели, описанные только в opencode.json, в выборе ollama launch не появятся. В тесте этот путь не проверялся.

Если нужна локальная модель именно в Claude Code, это тоже возможно через Anthropic-совместимый API Ollama, пример есть в статье про Claude Code в России.

Кастомный OpenAI-совместимый провайдер

Любой сервис с OpenAI-совместимым API добавляется тем же способом. В /connect выберите Other, задайте ID провайдера и ключ, а затем опишите его в opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My provider",
      "options": {
        "baseURL": "https://api.myprovider.com/v1",
        "apiKey": "{env:MYPROVIDER_API_KEY}"
      },
      "models": { "my-model": { "name": "My model" } }
    }
  }
}

Пакет @ai-sdk/openai-compatible работает с /v1/chat/completions. Если провайдер использует /v1/responses, docs советуют @ai-sdk/openai. В options.headers можно передать дополнительные заголовки.

Режимы и агенты

Build и Plan

В OpenCode два основных агента, между ними переключает Tab. Build - агент по умолчанию со всеми инструментами. Plan предназначен для анализа и планирования, но запрещает он меньше, чем обещает название:

• правки, запись и патчи файлов запрещены, кроме markdown-планов в .opencode/plans/ и в каталоге данных OpenCode;
• bash не ограничен, команды подчиняются общему конфигу permission;
• правила Plan применяются до вашего конфига, и побеждает последнее совпавшее правило. Глобальное "edit": "allow" распространяется и на Plan.

Чтобы Plan гарантированно ничего не менял и спрашивал перед командами, его права задаются явно:

{
  "agent": {
    "plan": {
      "permission": { "edit": "deny", "bash": "ask" }
    }
  }
}

Субагенты

Встроенных субагентов два. General выполняет многошаговые задачи, у него все инструменты, кроме todowrite, и он может менять файлы; несколько таких задач идут параллельно. Explore работает только на чтение и ищет по коду. Основной агент вызывает субагентов сам по их описанию, а вручную их зовут упоминанием: @general найди, где обрабатывается авторизация. Ещё три системных агента (compaction, title, summary) скрыты и запускаются автоматически.

Свои агенты

Своего агента можно описать в ключе agent конфига или отдельным markdown-файлом в ~/.config/opencode/agents/ (глобально) либо .opencode/agents/ (в проекте). Имя файла становится именем агента:

---
description: Reviews code for quality and security without editing files
mode: subagent
temperature: 0.1
permission:
  edit: deny
  bash: deny
---
You are a code reviewer. Focus on bugs, edge cases,
security and missing tests. Do not change files.

Обязательно только поле description. Остальные поля: mode (primary, subagent или all), model, prompt, temperature, steps (лимит итераций, после которого агент обязан ответить текстом), permission, hidden, disable. Создать агента интерактивно можно командой opencode agent create, посмотреть загруженных - opencode agent list. Аналогичный механизм в Claude Code разобран в статье про субагентов.

Права: ключ permission

У каждого инструмента три режима: allow, ask и deny. По документации стартовые значения разрешительные: большинство прав - allow, ask стоит только у doom_loop (один и тот же вызов три раза подряд) и external_directory (обращение к путям вне проекта). Чтение .env-файлов по умолчанию требует подтверждения.

Правила задаются шаблонами. Пример, где git-команды разрешены, push запрещён, а всё остальное требует подтверждения:

{
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git push *": "deny"
    }
  }
}

На запрос ask интерфейс предлагает три варианта: разрешить один раз, разрешить похожие запросы до конца сессии или отклонить.

Конфигурация OpenCode

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

1. Удалённый конфиг организации из .well-known/opencode.
2. Глобальный ~/.config/opencode/opencode.json.
3. Файл из переменной OPENCODE_CONFIG.
4. Проектный opencode.json. OpenCode ищет его в текущем каталоге и выше, до ближайшего git-каталога.
5. Каталоги .opencode (агенты, команды, плагины).
6. Inline-конфиг из переменной OPENCODE_CONFIG_CONTENT.
7. Managed-файлы администратора: /Library/Application Support/opencode/ на macOS, /etc/opencode/ на Linux.
8. Профили macOS MDM, их пользователь переопределить не может.

Ещё две переменные: OPENCODE_CONFIG_DIR задаёт свой каталог с агентами и командами, OPENCODE_TUI_CONFIG - путь к настройкам интерфейса. Схема конфига лежит по адресу https://opencode.ai/config.json, для TUI - https://opencode.ai/tui.json. Ссылка на схему в $schema включает автодополнение в редакторе.

В значениях работают подстановки. {env:VAR} берёт переменную окружения (если её нет, подставится пустая строка), {file:path} - содержимое файла. Так ключи остаются вне конфига, который лежит в git:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"],
  "provider": {
    "openai": { "options": { "apiKey": "{file:~/.secrets/openai-key}" } }
  }
}

Ключ instructions принимает пути и glob-шаблоны к дополнительным файлам инструкций. Чтобы ограничить набор провайдеров, есть enabled_providers (белый список) и disabled_providers, у второго приоритет выше.

MCP-серверы

MCP-серверы описываются в ключе mcp, по документации поддерживаются локальные и удалённые. Что такое MCP и как он устроен, разобрано в статье про MCP-серверы.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "enabled": true
    },
    "remote-api": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer {env:REMOTE_API_TOKEN}" }
    }
  }
}

Для удалённых серверов с OAuth OpenCode сам предложит авторизацию при первом обращении. Вручную поток запускается командой opencode mcp auth <server-name>, статус всех серверов показывает opencode mcp list, сохранённые данные удаляет opencode mcp logout <server-name>.

Документация отдельно предупреждает о контексте: каждый MCP-сервер добавляет в промпт описания своих инструментов, а некоторые, например GitHub MCP, добавляют так много токенов, что легко упереться в лимит. Для локальных моделей с контекстом 32-64k это критично. Если серверов много, их отключают глобально и включают только нужному агенту:

{
  "tools": { "my-mcp*": false },
  "agent": {
    "my-agent": { "tools": { "my-mcp*": true } }
  }
}

Инструменты MCP регистрируются с префиксом имени сервера, поэтому шаблон my-mcp* отключает все инструменты сервера my-mcp. В нативном формате V2 серверы лежат в mcp.servers, а enabled заменён на обратный disabled.

OpenCode vs Claude Code

Сравнение по документации обоих продуктов на 6 ноября 2026 года. Цены и лимиты тарифов в таблицу не включены.

Источники по OpenCode: providers, agents, permissions, skills, config. По Claude Code: overview, permission modes, sub-agents, settings, MCP.

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

С подписками есть разница. Подписка Claude даёт доступ к Claude Code, но не к OpenCode: для моделей Claude в OpenCode нужен API-ключ (см. раздел про облачных провайдеров). Зато ChatGPT Plus/Pro и GitHub Copilot OpenCode поддерживает официально. Подробнее про Claude Code - в полном гайде, сравнение с другим закрытым агентом - в статье Claude Code vs Codex, обзор рынка - в подборке AI-инструментов для программирования.

Тест: локальные модели в OpenCode 1.15.11

Окружение. macOS 27.2, Apple M4 Max, 36 GiB памяти. OpenCode 1.15.11 (актуальный на момент теста релиз 1.19.5 не устанавливался), Ollama 0.24.0, затем 0.40.14. Конфиг провайдера - тот, что приведён выше. Глобальный конфиг не использовался: HOME и XDG_* указывали на пустые временные каталоги.

Задача. Проект из calc.py с функциями add и subtract и двумя тестами на unittest. Промпт: добавить функцию multiply(a, b) в calc.py, тест к ней и запустить python3 -m unittest discover -s tests -t .. Запуск: opencode run -m ollama/<модель> "<задача>", на каждую конфигурацию одна попытка.

Выводы:

1. Тег tools в библиотеке Ollama не гарантирует рабочих вызовов инструментов в OpenCode. У qwen2.5-coder:7b он есть, но во всех прогонах из таблицы модель писала вызовы текстом, а OpenCode их не выполнял. Где именно ломается связка (формат модели, шаблон Ollama или версия OpenCode), тест не показывает.
2. На локальных 8B-моделях результат нестабилен. qwen3:8b из пяти прогонов один раз сделала задачу, не тронув существующий код, ещё раз довела тесты до зелёных ценой мусора в коде, остальные три прогона закончились ничем или порчей. gemma4:e4b с контекстом 64k отработала быстрее всех, но удалила функцию, которую её не просили трогать.
3. Зелёные тесты не означают корректную правку. В двух прогонах из трёх с зелёными тестами существующий код был испорчен или удалён, в третьем осталась лишняя строка.
4. По одной попытке на конфигурацию рейтинг моделей не построить. Таблица показывает разброс результатов, какая модель лучше, из неё не следует.

Практический вывод: с локальной моделью OpenCode может сделать задачу, но работать стоит только в git-репозитории, смотреть git diff после каждого шага и проверять результат тестами и глазами. Поведение на OpenCode 1.19.5 и V2 не проверялось.

Ограничения и подводные камни

Две версии. Команды установки V1 и V2 различаются, а brew install opencode из основного Homebrew уже ставит V2. Перед установкой решите, какую версию берёте, и сверяйте документацию с ней: в V2 другой формат плагинов и серверного API.

В V2 нет вопроса про пути вне проекта. Руководство по миграции предупреждает: V1 спрашивает перед доступом к путям вне проекта, а V2 по умолчанию это разрешает. Чтобы вернуть поведение V1, в V2 нужно правило { "action": "external_directory", "resource": "*", "effect": "ask" } в массиве permissions.

Широкие права по умолчанию. Даже в V1 большинство инструментов, включая bash и правку файлов, работают без подтверждения. Для незнакомого репозитория или слабой модели задайте "bash": {"*": "ask"} и посмотрите, что агент собирается выполнять.

Размер промпта и навыки из других агентов. По документации OpenCode ищет навыки в своих каталогах, а также в ~/.claude/skills/ и ~/.agents/skills/ (в проекте - в .claude/skills/ и .agents/skills/). Имена и описания всех найденных навыков он перечисляет в описании инструмента skill. В тестовых прогонах с реальным домашним каталогом лог Ollama показал truncating input prompt limit=32768 prompt=52988: промпт в 52 988 токенов обрезался до 32 768. В логе OpenCode при этом были предупреждения service=skill с путями этих каталогов. Связь между навыками и размером промпта прямо не доказана, но в прогонах с пустым HOME запросы были около 8k токенов. По docs, навыки скрываются правилом "permission": {"skill": {"*": "deny"}}, а "tools": {"skill": false} у агента убирает весь блок <available_skills>. В тесте эти настройки не проверялись.

Признак того же эффекта: локальная модель ведёт себя странно, а в логе Ollama есть строка truncating input prompt. Обрезанный системный промпт может терять описания инструментов, и тогда модель не знает, как их вызывать.

Контекст локальной модели. Рекомендация Ollama - от 64k, но по умолчанию сервер выделяет 4k или 32k в зависимости от VRAM, а у части моделей потолок ниже 64k. Проверяйте фактическое значение в ollama ps, а не в конфиге.

Plan не read-only. Правки файлов в Plan запрещены, но bash подчиняется общему конфигу. Если глобально стоит "bash": "allow", Plan может запустить любую команду.

MCP съедает контекст. Каждый сервер добавляет описания инструментов в промпт. С локальной моделью лучше подключать MCP точечно, к конкретному агенту.

Не проверено в рамках статьи: OpenCode 1.19.5 и V2, ollama launch opencode, Plan-режим, MCP, облачные провайдеры. Эти разделы описаны по документации.

С чего начать

1. Выберите версию и поставьте её: для V1 curl -fsSL https://opencode.ai/install | bash или tap anomalyco/tap/opencode, для V2 команды из README. Проверьте opencode --version.
2. Запустите opencode в проекте под git, подключите облачного провайдера через /connect и выполните /init.
3. Сразу ограничьте права: "bash": {"*": "ask"} в opencode.json, явные permission для агента Plan.
4. Для локальной модели поднимите контекст Ollama (OLLAMA_CONTEXT_LENGTH), проверьте его в ollama ps и опишите провайдера в opencode.json.
5. Дайте модели маленькую задачу с тестами, посмотрите git diff и только потом переходите к реальной работе.
6. Если промпт раздувается (в логе Ollama truncating input prompt), уберите лишние навыки и MCP-серверы или включайте их только нужным агентам.