OpenCode: настройка, агенты, навыки и MCP

Установка

Процесс установки OpenCode максимально упрощен. Всё, что вам нужно сделать, это выполнить одну команду в терминале.

Откройте терминал и введите:

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

После завершения установки проверьте, что всё работает, запустив команду:

opencode --version

Запуск проекта

Рекомендуется запускать OpenCode непосредственно в папке вашего проекта. Это позволяет агенту видеть структуру файлов и правильно взаимодействовать с ними.

1. Перейдите в папку проекта:

cd /путь/к/вашему/проекту

2. Запустите OpenCode:

 opencode 

Если вы используете VS Code или Cursor, вы можете запустить OpenCode во встроенном терминале. Это удобно, так как вы сразу видите все файлы, которые создает или изменяет агент.

Главная сила OpenCode — поддержка множества провайдеров и моделей. Вы можете использовать как бесплатные модели (для тестирования), так и платные (для серьезной работы).

1. Бесплатные модели через OpenCode Zen

OpenCode имеет собственный шлюз Zen, который предоставляет доступ к бесплатным моделям (например, Big Pickle, HY3, Minimax 2.5).

Для подключения выполните в консоли OpenCode:

/connect

В открывшемся меню найдите и выберите OpenCode Zen. Система попросит вас ввести API-ключ. Перейдите по ссылке, сгенерируйте ключ и вставьте его в терминал.

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

2. Подписки и API-ключи (Платные модели)

Для серьезных проектов стоит подключить более мощные модели, такие как GPT-5.2 или Claude Sonnet.

Чтобы использовать существующую подписку (например, ChatGPT Pro/Plus) вместо токенов API:

1. Снова введите /connect.
2. Выберите провайдера, например, OpenAI.
3. Выберите способ аутентификации: ChatGPT Pro/Plus (используйте логин через браузер, если у вас есть подписка).
4. Следуйте инструкциям для входа.

Совет: Использование API-ключей напрямую обходится дорого. Рекомендуем использовать существующие подписки, если это поддерживается провайдером.

Для смены модели используйте команду:

/models

Выберите нужную модель (например, gpt-5.2-high для сложных задач).

Файл .agents/agents.md (или просто agents.md в корне проекта) — это системный промпт для агента. Вы можете задать здесь строгие правила, которые агент обязан соблюдать.

Если вы хотите, чтобы OpenCode просканировал ваш проект и автоматически создал этот файл, используйте команду:

/init

Однако для максимального контроля рекомендуется настроить его вручную.

Пример файла agents.md

# Инструкции для агента

- Отвечай кратко и по существу.
- В режиме планирования задавай уточняющие вопросы. Никогда не предполагай дизайн или стек технологий.
- Используй субагентов для реализации задач, чтобы защитить основное контекстное окно.
- Всегда запускай `npm run lint` и `npm run build` после завершения разработки.
- При создании UI строго следуй системе дизайна из файла `design.md`.

Почему это важно?

Агенты имеют ограниченное контекстное окно (контекст). Если вы не делегируете задачи субагентам, главный агент быстро «засоряет» контекст, что ведет к ухудшению качества ответов (так называемая «зона глупости»). Используя файл памяти и субагентов, вы сохраняете контекст чистым, а агента — умным.

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

Лучший репозиторий для поиска навыков — (откроется в новой вкладке)skills.sh (более 100 000 навыков).

Базовые навыки для веб-разработки

1. Frontend Design — для создания красивых пользовательских интерфейсов.
2. Next.js (от Vercel Labs) — для корректной работы с фреймворком.
3. AI SDK (от Vercel) — для интеграции AI-функций в ваше приложение.

Установка навыков

Скопируйте команду с сайта skills.sh и выполните её в терминале (в папке проекта):

# Пример установки навыка Frontend Design
npx skills install frontend-design

Навыки устанавливаются в папку .agents/skills/. Чтобы проверить, что навыки подключились, выполните в OpenCode:

/skills

Вы увидите список всех доступных навыков. Если навыков нет, перезапустите OpenCode.

OpenCode использует иерархию агентов для эффективной работы.

1. Главный агент (Main): Координирует работу, планирует задачи и общается с пользователем.
2. Планировщик (Plan): Собирает требования, задает уточняющие вопросы и создает детальный план.
3. Суб-агенты (Sub-agents): Выполняют конкретные задачи (исследование, кодинг, тестирование) параллельно и возвращают краткий отчет главному агенту.

Режимы работы

Вы можете переключаться между режимом Bold (исполнение) и Plan (планирование) с помощью горячих клавиш Shift + Tab.

# Режим Планирования
/plan Опишите идею приложения...

# Режим Исполнения
/bold Реализуйте план согласно файлу .agents/plans/plan.md

Когда вы используете режим Bold с правильными инструкциями в agents.md, главный агент автоматически делегирует задачи суб-агентам.

Создание своего суб-агента

Вы можете создать собственного агента для специфических задач (например, только для дизайна или только для тестов).

В терминале, вне OpenCode, выполните:

opencode agent create

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

Рассмотрим практический пример. Мы хотим создать приложение, которое генерирует техническое задание (ТЗ) по описанию идеи пользователя.

Этап 1: Планирование

1. Переключаемся в режим Plan (Shift + Tab).
2. Вводим промпт с описанием проекта. Важно указать, что мы используем Next.js, AI SDK (OpenRouter) и хотим визуализировать модель данных.
3. Агент задает уточняющие вопросы и создает детальный план.
4. Сохраняем план в папку .agents/plans/ (командой или вручную).

Этап 2: Реализация

1. Создаем новую сессию (/new).
2. Переключаемся в режим Bold (Shift + Tab).
3. Пишем: Реализуй план из папки .agents/plans/.
4. Агент разбивает задачи и запускает суб-агентов для параллельной работы.

Этап 3: Настройка .env

Файл .env хранит все конфиденциальные данные (API-ключи, токены) и обязательно должен быть добавлен в .gitignore, чтобы не попасть в репозиторий. OpenCode автоматически подхватывает переменные из этого файла при запуске, но после изменений требуется перезапустить сессию (/new) или весь OpenCode.

Основные переменные для настройки

Ключи провайдеров (OPENROUTER_API_KEY, OPENAI_API_KEY), модель по умолчанию (OPENROUTER_MODEL) и специфичные для приложения настройки. Для удобства создайте файл-шаблон .env.example с описанием всех необходимых переменных (без реальных значений) — это поможет другим разработчикам быстро настроить проект. При использовании нескольких провайдеров все ключи можно хранить в одном .env файле, а OpenCode будет автоматически выбирать нужный в зависимости от активной модели. Даже для бесплатных моделей OpenCode Zen потребуется API-ключ, который также следует разместить в .env для автоматической аутентификации.

Итак, для работы с AI необходимо создать файл .env и добавить ключи API:

OPENROUTER_API_KEY=sk-ваш_ключ
OPENROUTER_MODEL=anthropic/claude-3.5-sonnet

Самый мощный функционал OpenCode — это подключение MCP-серверов (Model Context Protocol). Это позволяет агенту взаимодействовать с внешними инструментами. В примере используется Playwright MCP для автоматического тестирования UI в браузере.

Настройка Playwright MCP

1. В корне проекта создайте файл opencode.json.

2. Добавьте в него конфигурацию для Playwright:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

3. Перезапустите OpenCode.

4. Проверьте подключение командой:

 /mcps 

Вы должны увидеть playwright в списке подключенных серверов.

Использование в работе

Теперь вы можете дать агенту задание:

/bold Используй навыки фронтенд-дизайна для улучшения UI. Затем с помощью Playwright MCP протестируй все функции приложения.

Агент откроет браузер, заполнит поля, нажмет кнопки и проверит, что все работает, автоматически внося исправления, если что-то пошло не так.

OpenCode — это мощный, гибкий и бесплатный инструмент для агентного программирования. Его ключевые преимущества:

1. Мульти-провайдерность: Возможность использовать любые модели, включая бесплатные.
2. Гибкость: Полный контроль через файлы agents.md и design.md.
3. Масштабируемость: Использование субагентов и MCP-серверов для сложных задач, таких как тестирование или взаимодействие с внешними API.

Попробуйте OpenCode в своем следующем проекте — и вы увидите, как разработка может быть не только быстрой, но и по-настоящему интеллектуальной. Если возникнут вопросы, обязательно пишите. На странице Контакты можно отправить сообщение, на которое мы обязательно ответим.