Настройка OpenCode как Claude Code: LSP, Serena, модели, Docker

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

При переходе с Claude Code возникает типичное ощущение: агент делает то же самое, но работает заметно «глупее». Причина не в самом OpenCode, а в том, что половина слоёв, формирующих «ум» агента, по умолчанию выключена.

«Ум» Claude Code — это сумма из пяти слоёв. OpenCode умеет всё то же самое; ниже — разбор каждого слоя по убыванию вклада и готовые конфигурации, которые закрывают разрыв.

Из чего складывается «ум» агента

1. Модель

Самый большой вклад в поведение агента даёт сама модель. Claude Code построен вокруг конкретного семейства моделей и настроен под него. На слабой или локальной модели OpenCode не будет вести себя как топовый агент при любой конфигурации — это отправная точка.

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

2. LSP — понимание кода

Это главное, чего не хватает «голому» OpenCode. Language Server Protocol даёт агенту то же, что среда разработки даёт человеку: типы, переходы к определениям, поиск ссылок, диагностику компилятора. Без LSP агент читает код как простой текст и правит его вслепую. С LSP — видит структуру и ошибки заранее.

В OpenCode LSP по умолчанию выключен. Его нужно включить явно и указать серверы под используемые языки. Для типового набора Python + TypeScript это pyright и typescript-language-server.

3. Семантический поиск по коду

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

Решение — подключить внешний MCP-сервер для работы с кодом. Наиболее заметный эффект даёт Serena: она предоставляет LSP-точные операции над символами (найти определение, все использования, переименовать, отредактировать конкретный символ). Фактически она строит для модели «карту» кода, которую та сама построить не может. Это самый ощутимый скачок «интеллекта» на больших кодовых базах.

4. AGENTS.md — правила проекта

Прямой аналог файла инструкций из Claude Code. При старте OpenCode ищет файлы правил, поднимаясь вверх по дереву каталогов: AGENTS.md и CLAUDE.md. Если есть оба, берётся только AGENTS.md. Содержимое подмешивается в контекст модели и настраивает её поведение под конкретный проект.

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

Важный нюанс: чем слабее модель, тем подробнее и жёстче должны быть правила. Флагманская модель домысливает недостающий контекст сама, слабая — нет. Явно прописанные пути, команды и запреты сокращают разрыв между моделями сильнее всего.

5. Агенты, подагенты и режим плана

Claude Code имеет встроенную дисциплину: сначала планирование, потом исполнение, плюс делегирование подзадач. В OpenCode это настраивается.

Есть два основных агента — Build (полный доступ к инструментам) и Plan (ограниченный, преимущественно чтение), между которыми переключаются клавишей Tab. Есть встроенные подагенты — General, Explore, Scout, — которые основной агент вызывает под конкретные задачи.

Рабочий приём, особенно на не-флагманской модели: не давать агенту сразу писать код. Сначала Plan строит план, план проверяется глазами, и только потом идёт переключение в Build. Это отсекает бо́льшую часть глупых ошибок до того, как они попадут в файлы.

Сравнение моделей

Главное преимущество OpenCode перед закрытым агентом — свобода выбора модели. Но выбор не сводится к «взять верхнюю строчку рейтинга». В 2026 году ни одна модель не выигрывает по всем осям сразу, и правильный подход — маршрутизация: сильная модель на сложные задачи, дешёвая на рутину.

Ниже — ориентир по актуальному раскладу (данные на июль 2026, метрика SWE-bench Verified, цены за 1 млн токенов ввода/вывода). Цифры устаревают быстро — сверяйтесь с актуальными таблицами перед выбором.

Модель	SWE-bench Verified	Цена (ввод/вывод)	Открытые веса	Ниша
Claude Opus 4.8	~88.6%	$5 / $25	нет	Длинные автономные прогоны, сложный многофайловый рефакторинг
GPT-5.5	~88.7%	$5 / $30	нет	Терминальные агенты, командная строка
GPT-5.3-Codex	~высокая	ниже GPT-5.5	нет	Codex-подобные потоки, дешевле за задачу
Gemini 3.1 Pro	~80.6%	$2 / $12	нет	Архитектура, большой контекст, экономия
DeepSeek V4 Pro	~75.9–80%	$1.74 / $3.48	да (MIT)	Экономичные агент-циклы, самостоятельный хостинг
Claude Sonnet 4.6	~79.6%	$3 / $15	нет	Повседневная разработка, контекст 1 млн
DeepSeek V4 Flash	ниже	$0.14 / $0.28	да	Дешёвая рутина, «последние 10%» задач
Qwen 3 Coder	ниже	~$0.30 / $1.50	да (Apache 2.0)	Стандарт для локального хостинга
Devstral 2	ниже	локально	да	Агентный код без утечки данных наружу

Практически модели делятся на три яруса. Флагманы (Opus 4.8, GPT-5.5) — для сложных 20% задач, где качество важнее цены. Оптимальные (Sonnet 4.6, Gemini 3.1 Pro, DeepSeek V4 Pro) — для ежедневной работы: почти всё качество за долю стоимости. Дешёвые и быстрые (DeepSeek V4 Flash, Qwen 3 Coder) — для рутины и автодополнения.

Почему обвязка важнее модели

Это ключевой вывод, переворачивающий логику выбора. Независимые замеры 2026 года показали: при прогоне через разную обвязку одна и та же модель набирает от ~52% до ~69% на одном бенчмарке. Разрыв в 17 пунктов создаётся только инструментами и сценарием, а не сменой модели.

Маршрутизация моделей в OpenCode

OpenCode позволяет назначать разные модели разным агентам. Типовая схема: сильная модель на основного агента build, дешёвая — на служебные задачи (small_model: заголовки сессий, сжатие контекста) и на агента-планировщика.

Три яруса на базе DeepSeek

DeepSeek удобен для маршрутизации: весь набор укладывается в две модели плюс переключатель усилия рассуждений (reasoning effort), а цены на порядок ниже флагманов. Раскладка по трём ярусам:

• Сильная — deepseek-v4-pro с высоким усилием рассуждений. Модель на 1.6 трлн параметров (49 млрд активных), контекст 1 млн токенов, ~$1.74 / $3.48 за 1 млн. Ставится на основного агента build: сложный многофайловый рефакторинг, анализ всей кодовой базы, длинные автономные прогоны. Её поведение при вызове инструментов ближе к Claude Code, чем у прежней линейки V3.
• Средняя — deepseek-v4-flash с включённым рассуждением. Та же архитектура, но 284 млрд параметров (13 млрд активных), заметно дешевле при приличном качестве рассуждений. Ставится на агента-планировщика plan: построить план, разобраться в задаче — здесь не нужна вся мощь Pro.
• Дешёвая — deepseek-v4-flash в быстром режиме, ~$0.14 / $0.28 за 1 млн. Идёт на служебные задачи (small_model) и рутину: заголовки сессий, сжатие контекста, простые правки.

Конфигурация с прямым API DeepSeek:

{
  "model": "deepseek/deepseek-v4-pro",
  "small_model": "deepseek/deepseek-v4-flash",
  "agent": {
    "plan": {
      "model": "deepseek/deepseek-v4-flash"
    }
  }
}

При работе через OpenRouter добавляется префикс провайдера:

{
  "model": "openrouter/deepseek/deepseek-v4-pro",
  "small_model": "openrouter/deepseek/deepseek-v4-flash",
  "agent": {
    "plan": {
      "model": "openrouter/deepseek/deepseek-v4-flash"
    }
  }
}

Так более сильная модель оплачивается только там, где она реально нужна — на сложных правках кода, — а планирование и служебные операции идут на дешёвом Flash.

Имена моделей и цены DeepSeek периодически меняются (старые deepseek-chat и deepseek-reasoner уже выведены из обращения) — сверяйтесь с актуальной документацией провайдера.

Установка всех компонентов

Прежде чем конфигурация заработает, в системе должны быть установлены сам OpenCode и все внешние программы, на которые он ссылается: языковые серверы, форматтеры и менеджер пакетов для запуска Serena. Ниже — полный набор команд для Linux (Debian/Ubuntu) и macOS.

1. OpenCode

Официальный установочный скрипт (Linux и macOS):

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

Альтернативно — через npm (если Node.js уже стоит) или Homebrew на macOS:

npm i -g opencode-ai
# либо
brew install sst/tap/opencode

Проверка:

opencode --version

2. Node.js — основа для языковых серверов

Пакеты pyright, typescript-language-server и prettier ставятся через npm, поэтому Node.js нужен обязательно. Проверка наличия:

node --version

Если команды нет — установить. На Debian/Ubuntu актуальную версию удобнее ставить через официальный репозиторий NodeSource:

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

На macOS через Homebrew:

brew install node

3. Языковые серверы и форматтер (npm)

Одной командой устанавливаются сервер Python, сервер TypeScript (вместе с самим пакетом typescript, который ему нужен для работы) и форматтер prettier:

npm i -g pyright typescript typescript-language-server prettier

После этого становятся доступны исполняемые файлы pyright-langserver, typescript-language-server и prettier.

4. Python-инструменты: uv и ruff

uv — быстрый менеджер пакетов Python; через его команду uvx запускается Serena. Он же ставит форматтер ruff.

Установка uv (Linux и macOS):

curl -LsSf https://astral.sh/uv/install.sh | sh

Установщик дописывает PATH в ~/.bashrc, но в уже открытой сессии это не действует. Подхватить uv в текущей сессии без перезапуска терминала:

source $HOME/.local/bin/env
uv --version

Затем устанавливается ruff как отдельный инструмент:

uv tool install ruff

Serena отдельно ставить не нужно — она подтягивается автоматически при первом запуске командой uvx из конфигурации. Требуется лишь установленный uv и наличие в системе Python 3.11 или новее.

5. Проверка PATH

Все программы должны находиться системой. Каждая команда должна вернуть путь, а не пустую строку:

which opencode
which pyright-langserver
which typescript-language-server
which prettier
which ruff
which uvx

Если команда ничего не вернула — каталог с программой не входит в PATH. Чаще всего это касается глобальных пакетов npm и инструментов, установленных через uv. Узнать каталог глобальных пакетов npm:

npm config get prefix

Допустим, вернулось /home/user/.npm-global. Тогда в PATH добавляется его каталог bin, а также каталог инструментов uv. Строка вписывается в конец ~/.bashrc (или ~/.zshrc при использовании zsh):

echo 'export PATH="$HOME/.npm-global/bin:$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Когда все команды из проверки возвращают пути — система готова, и OpenCode подхватит инструменты из конфигурации автоматически. Запомните вывод which uvx (обычно /root/.local/bin/uvx или $HOME/.local/bin/uvx) — этот абсолютный путь понадобится в разделе про запуск в фоне.

Готовый глобальный конфиг

Файл ~/.config/opencode/opencode.json. Провайдер и модель здесь не зашиты — они подставляются через opencode auth или переменную окружения, поэтому конфигурация подходит под любую модель.

{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1"
  },
  "default_agent": "build",
  "autoupdate": "notify",
  "lsp": {
    "python": {
      "command": ["pyright-langserver", "--stdio"],
      "extensions": [".py", ".pyi"]
    },
    "typescript": {
      "command": ["typescript-language-server", "--stdio"],
      "extensions": [".ts", ".tsx", ".js", ".jsx"]
    }
  },
  "formatter": {
    "ruff": {
      "command": ["ruff", "format", "$FILE"],
      "extensions": [".py"]
    },
    "prettier": {
      "command": ["prettier", "--write", "$FILE"],
      "extensions": [".ts", ".tsx", ".js", ".jsx", ".json", ".css"]
    }
  },
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    },
    "serena": {
      "type": "local",
      "command": [
        "/root/.local/bin/uvx", "--from", "git+https://github.com/oraios/serena",
        "serena", "start-mcp-server",
        "--context", "claude-code",
        "--project", "/path/to/your/project",
        "--transport", "stdio"
      ],
      "enabled": true
    }
  },
  "instructions": ["AGENTS.md", ".cursor/rules/*.md"],
  "permission": {
    "edit": "allow",
    "bash": {
      "rm *": "ask",
      "git push *": "ask",
      "docker *": "ask",
      "*": "allow"
    }
  },
  "compaction": {
    "auto": true
  }
}

Пояснения к конфигурации:

• server.hostname = 127.0.0.1 означает, что OpenCode Server слушает только локальную петлю. Если сервер стоит на VPS за обратным прокси (nginx, Nginx Proxy Manager) — это правильный выбор: наружу порт не торчит, весь внешний трафик идёт через прокси с TLS. Значение 0.0.0.0 открывает порт на всех интерфейсах и нужно только внутри Docker-контейнера (см. ниже).
• lsp включает языковые серверы. pyright-langserver и typescript-language-server должны быть доступны в PATH запускающего процесса.
• formatter прогоняет ruff и prettier после правок, чтобы код оставался в едином стиле.
• mcp.context7 — публичный удалённый сервер актуальной документации по библиотекам. Это просто URL, OpenCode ему ничего не запускает.
• mcp.serena — локальный сервер семантического поиска и точных правок символов. Три момента здесь критичны, и все три вынесены в раздел про типичные проблемы: абсолютный путь к uvx, актуальное имя контекста claude-code (старое ide-assistant устарело) и явный --project с путём к вашему репозиторию.
• permission.bash переводит потенциально опасные команды (удаление файлов, push, работа с контейнерами) в режим подтверждения, оставляя остальное автоматическим.
• compaction.auto включает автоматическое сжатие контекста при приближении к пределу окна модели, чтобы длинные сессии не обрывались.

Типичные проблемы: Serena не подключается

Самая частая проблема при первой настройке: в панели MCP сервер serena виден, но переключатель не встаёт (откатывается назад), вверху висит «1 MCP» вместо «2», либо вкладка вовсе показывает «MCP не настроены».

Ключ к пониманию — разница между двумя типами серверов. context7 удалённый: это просто URL, OpenCode ничего не запускает, поэтому его переключатель встаёт всегда. serena локальная: OpenCode должен сам запустить процесс командой uvx. Если этот запуск падает, переключатель откатывается. Значит проблема почти никогда не в самой Serena, а в окружении процесса, который её запускает.

Диагностика по шагам

Сначала проверьте, что конфиг валиден — битый JSON OpenCode игнорирует молча, без ошибок в интерфейсе:

python3 -m json.tool ~/.config/opencode/opencode.json > /dev/null && echo OK || echo BROKEN

Затем запустите команду Serena вручную — ровно ту, что стоит в конфиге:

/root/.local/bin/uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context claude-code \
  --project /path/to/your/project --transport stdio

Если в выводе появляется MCP server lifetime setup complete и список из ~23 инструментов (find_symbol, find_referencing_symbols и т.д.) — сама Serena полностью рабочая, выйдите по Ctrl+C. Значит дело исключительно в том, как её запускает сервер. Если же вылезает command not found — uvx не виден процессу.

Три причины и их устранение

Причина №2 — устаревшее имя контекста. В свежих версиях Serena контекст ide-assistant переименован в claude-code. Пока старое имя даёт лишь предупреждение в логе, но в новых сборках может стать ошибкой запуска. Используйте --context claude-code.

Причина №3 — зависание на активации проекта. При первом запуске Serena проводит onboarding и активирует проект. Без явного пути она иногда зависает на этом шаге, и OpenCode считает запуск неудачным. Добавьте --project с абсолютным путём к репозиторию.

Обязательный перезапуск сервера

MCP-серверы и PATH подхватываются только при старте, поэтому после любой правки конфига нужно перезапустить именно сам серверный процесс (не сессию в приложении). Как — зависит от способа запуска.

Если сервер работает через systemd:

systemctl restart opencode
systemctl status opencode --no-pager
journalctl -u opencode -n 40 --no-pager | grep -iE "serena|mcp|error"

Если запущен вручную в tmux или screen — убить процесс и запустить заново из оболочки, где uvx виден в PATH:

pkill -f "opencode serve"
opencode serve --hostname 127.0.0.1 --port 4096

После перезапуска закройте и снова откройте проект в приложении OpenCode, чтобы оно перечитало список MCP с сервера. Переключатель serena должен встать и остаться — вверху появится «2 MCP». При первом запуске Serena несколько секунд тянется через uvx и индексирует проект, так что появляется не мгновенно.

Как установить OpenCode в Docker

Если OpenCode Server работает в контейнере, действует важное ограничение среды.

Минимальный Dockerfile, собирающий полный набор:

FROM node:22-slim

# Системные зависимости и Python
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl ca-certificates git python3 python3-venv \
    && rm -rf /var/lib/apt/lists/*

# Языковые серверы и форматтер
RUN npm i -g opencode-ai pyright typescript typescript-language-server prettier

# uv и ruff
RUN curl -LsSf https://astral.sh/uv/install.sh | sh
ENV PATH="/root/.local/bin:${PATH}"
RUN uv tool install ruff

WORKDIR /workspace
EXPOSE 4096
CMD ["opencode", "serve", "--hostname", "0.0.0.0", "--port", "4096"]

Внутри контейнера --hostname 0.0.0.0 обязателен — иначе сервер будет недоступен через проброс порта. Но наружу порт 4096 публиковать не нужно: пробрасывайте его только во внутреннюю сеть Docker, а внешний доступ давайте через обратный прокси с TLS. При таком образе Serena так же подтянется через uvx при первом запуске, а все проверки which внутри контейнера пройдут успешно.

Заготовка AGENTS.md

Файл кладётся в корень проекта и дорабатывается под конкретный репозиторий. Пример для проекта на FastAPI + React:

# Правила проекта

## Стек
- Бэкенд: FastAPI + PostgreSQL, асинхронный (asyncpg / SQLAlchemy 2.0).
- Фронтенд: React + Vite + TypeScript + TailwindCSS.
- Всегда полный рабочий код, без заглушек «добавьте сюда».

## Команды
- Запуск бэкенда: `uvicorn app.main:app --reload`
- Тесты: `pytest -q`
- Линт и форматирование: `ruff check . && ruff format .`
- Сборка фронтенда: `npm run build`
- Перед завершением задачи прогонять `ruff` и `pytest`.

## Стиль
- Придерживаться существующей структуры каталогов и именования.
- Не трогать миграции базы данных без явного запроса.
- Секреты и файлы окружения не коммитить и не выводить в лог.
- Перед удалением файлов и деструктивными командами — спрашивать.

Чем конкретнее этот файл, тем меньше разрыв в качестве между сильной и слабой моделью.

Порядок внедрения

Включать всё сразу не стоит — эффект лучше проверять послойно:

1. Модель. Подключение лучшей доступной модели даёт основную часть разницы.
2. LSP. Агент перестаёт слепо редактировать и начинает видеть типы и ошибки.
3. Serena. Скачок качества на больших репозиториях, где раньше терялся контекст.
4. AGENTS.md и агенты. Тонкая настройка правил, прав и режима планирования.

Если после первых двух-трёх шагов ощущение «как в топовом агенте» уже появилось — остальное опционально.

Заключение

По «ощущению из коробки» настроенный таким образом OpenCode дотягивается до эталонного агента примерно на 85–90%. Оставшийся разрыв — это годами вылизанный системный промпт и внутренняя обвязка (harness) закрытого продукта, которые в OpenCode воспроизводятся через AGENTS.md, подагентов и режим плана, но не байт-в-байт.

Для практической ежедневной работы эта разница почти незаметна, а бесплатные слои — LSP, семантический поиск через Serena и правила в AGENTS.md — дают больший прирост качества, чем переход на модель классом выше. Взамен закрытого продукта пользователь получает свободу выбора модели и провайдера, отсутствие привязки к вендору и полный контроль над инструментами на собственной инфраструктуре.

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

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

OpenCode — открытый агент с поддержкой десятков провайдеров моделей, который можно запускать на собственной инфраструктуре. Claude Code — закрытый продукт, настроенный под одно семейство моделей. По базовой функциональности (правки файлов, оболочка, понимание проекта) они сопоставимы, но OpenCode требует ручной настройки слоёв, которые у Claude Code включены по умолчанию.

Нужен ли LSP для OpenCode?

Да, если требуется, чтобы агент понимал типы, ссылки и ошибки, а не правил код вслепую. По умолчанию LSP в OpenCode выключен — его нужно включить в opencode.json и указать языковые серверы под используемые языки, например pyright для Python и typescript-language-server для TypeScript.

Какая модель лучше для OpenCode?

Зависит от задачи и бюджета. Для максимального качества — флагманы уровня Claude Opus или GPT-5.5. Для баланса цены и качества — Gemini 3.1 Pro, Claude Sonnet или DeepSeek V4 Pro. Для рутины — DeepSeek V4 Flash. Оптимальная схема — маршрутизация: сильная модель на сложные правки, дешёвая на планирование и служебные задачи.

Что важнее — модель или её настройка?

Настройка. Замеры показывают, что одна и та же модель через разную обвязку набирает от ~52% до ~69% на одном бенчмарке. Разрыв в 17 пунктов создаётся инструментами и сценарием, а не сменой модели. Сначала стоит выжать максимум из LSP, семантического поиска и правил проекта, и только потом доплачивать за более сильную модель.

Почему Serena не подключается в OpenCode?

Чаще всего потому, что процесс OpenCode Server (под systemd или в Docker) не видит uvx в своём PATH, хотя из обычной оболочки команда работает. Решение — указать в конфиге абсолютный путь к uvx из which uvx, задать актуальное имя контекста claude-code вместо устаревшего ide-assistant, добавить --project и перезапустить сервер. Подробности — в разделе про типичные проблемы.

Что такое AGENTS.md в OpenCode?

Это файл с правилами проекта, который подмешивается в контекст модели и настраивает её поведение под конкретный репозиторий — прямой аналог инструкций из Claude Code. Создаётся командой /init или вручную; его стоит закоммитить в репозиторий.

Можно ли запустить OpenCode в Docker?

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