Агенты в OpenCode: как создать своего агента

Агент в OpenCode — это именованный профиль работы: своя модель, свой системный промпт и свой список разрешённых инструментов. Чтобы создать своего агента, нужно описать его отдельным markdown-файлом в папке .opencode/agent/ внутри проекта (или в ~/.config/opencode/agent/, если агент нужен во всех проектах) либо объявить его в блоке agent файла opencode.json. После этого агент появляется в списке доступных, и его можно вызвать прямо в сессии.

Дальше — чем агент отличается от обычного режима, какие у него поля, как подключить к агенту модель Claude, работающую из России, и как собрать агента-ревьюера, который не имеет права править код.

Одна оговорка перед началом: OpenCode развивается быстро, и набор полей у агента со временем пополняется. Конкретные поля сверяйте с документацией той версии, которая стоит у вас — особенно если какое-то из них не подхватилось.

Что такое агент в OpenCode

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

У агента есть два режима работы, и разница между ними принципиальная:

• primary — агент ведёт диалог. Вы выбираете его в начале или переключаетесь на него во время сессии, и дальше он отвечает на ваши сообщения.
• subagent — агент не ведёт диалог, а вызывается на отдельную подзадачу. Основной агент передаёт ему задание, тот работает в своём контексте и возвращает результат.

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

Не путайте агентов с файлом AGENTS.md. AGENTS.md — это инструкции по проекту, общие для всех агентов: как собирать, как запускать тесты, какие соглашения в коде. Агент — это профиль исполнителя. Про сам файл инструкций мы писали отдельно: AGENTS.md: как написать инструкции для Codex и OpenCode.

Встроенные агенты: build, plan и general

Из коробки в OpenCode есть несколько агентов, и до создания своих полезно понять, что уже закрыто:

• build — основной рабочий агент. Полный доступ: читает, пишет файлы, запускает команды. Режим по умолчанию для обычной разработки.
• plan — агент для обсуждения без последствий. Ему запрещено менять файлы, поэтому его удобно использовать, когда нужно разобраться в незнакомом коде или обсудить подход, не рискуя, что модель начнёт переписывать проект по ходу разговора.
• general — subagent общего назначения для исследовательских подзадач: найти что-то в репозитории, собрать информацию по нескольким файлам.

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

Как создать своего агента

Самый короткий путь — markdown-файл. YAML-фронтматтер описывает параметры агента, тело файла становится его системным промптом.

Положите файл .opencode/agent/reviewer.md в корень проекта:

---
description: Ревьюит изменения в текущей ветке и никогда не правит код
mode: subagent
model: purpleschool-anthropic/claude-sonnet-5
temperature: 0.1
tools:
  write: false
  edit: false
---

Ты ревьюер кода. Твоя задача — находить проблемы в изменениях, а не исправлять их.

Порядок работы:

1. Получи список изменений командой `git diff`.
2. Разбери изменения по файлам.
3. Для каждой найденной проблемы укажи файл, строку и причину.

Правила: не предлагай готовых патчей, не меняй файлы. Если в diff нет проблем — скажи
об этом прямо, не придумывай замечания ради объёма.

Что здесь происходит по полям:

• description — для чего агент. Для subagent-а это поле делает двойную работу: по нему основной агент решает, стоит ли передавать ему задачу. Описание вида «ревью кода» работает хуже, чем описание с явной границей ответственности.
• mode — subagent, то есть агент не ведёт диалог сам, а вызывается на подзадачу.
• model — модель в формате провайдер/модель. Здесь это провайдер purpleschool-anthropic, который мы настроим в следующем разделе.
• temperature — низкое значение для задач, где нужна предсказуемость, а не вариативность формулировок.
• tools — карта инструментов. Отключив write и edit, вы получаете агента, который физически не может изменить файлы, — это надёжнее, чем просьба «ничего не меняй» в промпте.

Тело файла после фронтматтера — системный промпт агента. Это обычный markdown, и писать его стоит как инструкцию сотруднику: что делать, в каком порядке, чего не делать.

То же самое можно объявить в opencode.json, если не хочется разводить отдельные файлы:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "reviewer": {
      "description": "Ревьюит изменения в текущей ветке и никогда не правит код",
      "mode": "subagent",
      "model": "purpleschool-anthropic/claude-sonnet-5",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Разница только в удобстве: markdown-файл лучше, когда промпт длинный, JSON — когда агент описывается тремя строками. Файлы в .opencode/agent/ коммитятся вместе с проектом, так что агент приезжает всей команде вместе с репозиторием.

Какую модель Claude подключить к агенту

Поле model ссылается на провайдера, а провайдера нужно объявить. Напрямую из России API Anthropic не отвечает, поэтому модель подключается через шлюз. У PurpleSchool для этого есть сервис AI для кода: он даёт ключ и адрес, совместимый с Anthropic API, с оплатой в рублях.

Сначала положите ключ в переменную окружения — так он не попадёт в конфиг и не уедет в репозиторий:

export PURPLESCHOOL_API_KEY="ваш ключ"

Строку стоит добавить в ~/.zshrc или ~/.bashrc, иначе переменная исчезнет вместе с текущей сессией терминала. Если механика переменных окружения в шелле для вас не очевидна, у нас есть разбор: переменные окружения в Bash и команда export.

Теперь провайдер в opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "purpleschool-anthropic": {
      "npm": "@ai-sdk/anthropic",
      "name": "PurpleSchool Anthropic Proxy",
      "options": {
        "baseURL": "https://app.purpleschool.ru/api-v2/public/ai-proxy/anthropic/v1",
        "apiKey": "{env:PURPLESCHOOL_API_KEY}"
      },
      "models": {
        "claude-sonnet-5": { "name": "Claude Sonnet 5" },
        "claude-haiku-5-5": { "name": "Claude Haiku 5.5" },
        "claude-opus-5": { "name": "Claude Opus 5" }
      }
    }
  }
}

Конструкция {env:PURPLESCHOOL_API_KEY} — это подстановка переменной окружения: сам ключ в файле не хранится. Ключ models перечисляет модели, которые будут видны в OpenCode; актуальный список id есть в инструкции на странице сервиса, там же лежат модели семейств Sonnet, Haiku, Opus и Fable разных версий.

После этого purpleschool-anthropic/claude-sonnet-5 в поле model агента становится валидной ссылкой. Проверить, что провайдер подхватился, можно командой /models в запущенном OpenCode — модели появятся в списке под именем провайдера.

Если OpenCode у вас ещё не установлен, начните с базовой настройки — она описана отдельно: OpenCode в России: установка и настройка без VPN. Сам OpenCode ставится через npm:

npm install -g opencode-ai

Как вызвать агента в диалоге

Способ вызова зависит от режима агента.

primary-агент выбирается как режим сессии: вы переключаетесь на него, и дальше он отвечает на все ваши сообщения. Переключение доступно внутри запущенного OpenCode, так что менять агента можно по ходу разговора — например, разобраться в коде на plan, а потом переключиться на build и внести правки.

subagent вызывается упоминанием по имени — @reviewer в тексте сообщения. Агент получает задачу, выполняет её в своём контексте и возвращает результат в основной диалог.

Второй путь для subagent-а — автоматический. Основной агент сам решает делегировать часть работы, опираясь на поле description. Поэтому описание агента стоит писать не для себя, а для модели: что агент делает и, главное, в каких случаях его нужно звать.

Пример: агент-ревьюер кода

Соберём агента из предыдущих разделов целиком и посмотрим, что получится на практике. Файл .opencode/agent/reviewer.md уже описан выше: mode: subagent, write и edit отключены, промпт требует указывать файл и строку.

Вызов выглядит так:

@reviewer посмотри изменения в текущей ветке перед пушем

Что происходит дальше: агент запускает git diff, читает изменённые файлы, возвращает список замечаний. Поправить он ничего не может — write и edit выключены на уровне конфигурации, и промпт тут вторичен. Это важное свойство: ревьюер, которому технически запрещено писать в файлы, не «починит» заодно пару мест по своему усмотрению.

Обратите внимание на bash в наборе инструментов. Ревьюеру он нужен, чтобы получить diff, но вместе с ним агент получает возможность запускать произвольные команды. Если это не устраивает, можно не давать агенту shell вовсе, а передавать diff в тексте задачи — агент разберёт то, что ему дали, и ничего не запустит.

Тот же приём работает для других узких задач: агент, который только пишет тесты; агент, который только переводит строки интерфейса; агент, который читает логи и ничего больше. Общий принцип — чем уже права и конкретнее промпт, тем предсказуемее результат.

Как настроить агента, чтобы экономить токены

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

• Модель под задачу. Переименовать переменные, собрать коммит-месседж, причесать markdown — это работа для быстрой и дешёвой модели. Тяжёлую модель оставьте основному агенту, который разбирается в архитектуре. Поле model задаётся у каждого агента отдельно, так что одна сессия может пользоваться обеими.
• Вынос подзадач в subagent. Шумная работа вроде поиска по репозиторию проходит в контексте агента, а в основную сессию попадает только результат. Основной диалог остаётся короче, а каждый следующий запрос в нём дешевле.
• Короткий набор инструментов. Описания доступных инструментов занимают место в каждом запросе. Агенту, которому не нужен веб-поиск и правка файлов, их лучше отключить.
• Промпт вместо повторяющихся объяснений. Требования, которые вы раз за разом дописываете в чат руками, надёжнее положить в тело файла агента — один раз в конфиг вместо каждого сообщения.

Частые ошибки при настройке агента

Агент не появился в списке. Проверьте расположение файла: проектные агенты лежат в .opencode/agent/ относительно корня проекта, и OpenCode должен быть запущен именно из этого корня. Запуск из подпапки — самая частая причина. Глобальные агенты живут в ~/.config/opencode/agent/.

Агент есть, но не вызывается по @. Убедитесь, что у него mode: subagent. primary-агент по упоминанию не вызывается — он выбирается как режим сессии.

Модель недоступна или ответ приходит с ошибкой доступа. Строка в model должна точно совпадать с парой «id провайдера / id модели» из блока provider. Если провайдер задан верно, проверьте, что переменная PURPLESCHOOL_API_KEY действительно видна процессу: echo $PURPLESCHOOL_API_KEY в том же терминале, из которого запускаете OpenCode. Переменная, добавленная в ~/.zshrc, не появится в уже открытых сессиях — их нужно перезапустить.

Агент всё равно правит файлы. Значит, ограничение задано только в промпте. Текстовая просьба — это не запрет; отключайте write и edit в tools.

Невалидный YAML во фронтматтере. Поле tools — это вложенная карта, отступы в ней значимы. Если агент не читается, а путь верный, начните с проверки отступов и двоеточий.

Что дальше

Агенты закрывают одну часть настройки OpenCode, инструменты — другую: агенту можно выдать доступ к внешним системам через MCP-серверы, и тогда он будет работать не только с файлами проекта. Про это у нас есть отдельный разбор: MCP в Codex CLI и OpenCode: как подключить сервер.

Если нужно решить, на чём держать ключ и что выгоднее по деньгам, посмотрите сравнение вариантов: OpenCode Zen или свой API-ключ: что выгоднее в России. А ключ для моделей Claude с оплатой в рублях — в сервисе AI для кода.