Содержание
Как настроить агента в OpenCode
Черновик готовит редакция с помощью ИИ. За стандарт издания отвечает главный редактор — Валерий Курземнек.
Материал редакции Зерокодера. Счёт по выдаче снят собственным прогоном 18 октября 2026 года; цитаты источников приведены дословно. Обновлено: октябрь 2026.
Как настроить агента в OpenCode: выберите один из способов — описать его в JSON-конфиге opencode.json в секции agent либо положить markdown-файл в каталог agents/. Агент получает режим (primary, subagent или all), модель, системный промпт, лимит шагов и набор разрешений на инструменты. Ниже — порядок действий, учебный пример и проверка результата.
Собственный прогон редакции по этому запросу: скачали подборку результатов веб-поиска по запросу «Как настроить агента в OpenCode»: текст отдали 10 из 10. Медиана объёма читаемого текста топа — 2615 слов. Метку 2026 года несут 10 из 10 прочитанных страниц.
Прямой ответ и границы продукта
Агент в OpenCode — это именованная конфигурация поведения модели внутри одного инструмента. В документации проекта различают два типа: первичные агенты, с которыми пользователь общается напрямую, и субагенты, которых вызывает основной агент через инструмент задач. Переключение между первичными агентами идёт по клавише Tab или по настроенной привязке switch_agent.
Границы стоит держать в голове до начала настройки. OpenCode — это оболочка: она управляет тем, какая модель вызвана, какие инструменты ей доступны и что требует подтверждения. Сама модель приходит от провайдера, а её идентификатор записывается в формате provider/model-id. В документации проекта приведён пример: для OpenCode Zen идентификатор модели GPT 5.1 Codex записывается как opencode/gpt-5.1-codex.
Что именно настраивается у агента:
mode— как агент используется:primary,subagentилиall;model— какая модель обслуживает этого агента;prompt— файл системных инструкций;temperature— степень вариативности ответов;steps— максимальное количество шагов;toolsиpermission— доступ к инструментам и правила подтверждения;disable— отключение агента;hidden— скрытие субагента из списка.
Если модель у агента не указана, первичные агенты берут глобально настроенную модель, а субагенты наследуют модель вызвавшего их агента. Это описано в документации проекта и объясняет, почему один и тот же субагент ведёт себя по-разному в зависимости от того, кто его позвал.
Отдельная сущность — default_agent. Она задаёт агента, который используется, когда явного выбора не сделано. Пример из документации: "default_agent": "plan" делает агентом по умолчанию планировщик.
Практический вывод для старта: сначала определите задачу (ревью кода, документация, аудит безопасности), затем выберите режим, и только после этого подбирайте модель и разрешения. Обратный порядок приводит к конфигу, который технически валиден, но бесполезен в работе.
Условия доступа и источник актуальных требований
Актуальные требования живут в двух местах: справочник по агентам и справочник по конфигурации на сайте проекта. Первый описывает параметры агента, второй — расположение файлов, порядок приоритета и общую схему. Раздел о разрешениях дополняет их правилами доступа к инструментам.
OpenCode поддерживает форматы JSON и JSONC — второй допускает комментарии. Схема подключается строкой "$schema": "https://opencode.ai/config.json", что даёт автодополнение в редакторах, понимающих JSON Schema.
Конфигурация размещается в нескольких местах, и они объединяются. В документации проекта порядок такой: удалённая конфигурация из .well-known/opencode, глобальная ~/.config/opencode/opencode.json, пользовательская через переменную окружения OPENCODE_CONFIG, проектная opencode.json, каталоги .opencode, встроенная через OPENCODE_CONFIG_CONTENT. Более поздние источники переопределяют более ранние при конфликте ключей, а неконфликтующие настройки сохраняются из всех слоёв.
| Слой | Расположение | Назначение |
|---|---|---|
| Удалённая | .well-known/opencode |
Настройки организации по умолчанию |
| Глобальная | ~/.config/opencode/opencode.json |
Пользовательские настройки |
| Пользовательская | переменная OPENCODE_CONFIG |
Переопределения |
| Проектная | opencode.json в проекте |
Настройки конкретного проекта |
| Каталоги | .opencode |
Агенты, команды, плагины |
| Встроенная | переменная OPENCODE_CONFIG_CONTENT |
Переопределение времени выполнения |
Для агентов важны два каталога: глобальный ~/.config/opencode/agents/ и проектный .opencode/agents/. В документации проекта отмечено, что в каталогах .opencode и ~/.config/opencode для подкаталогов используются множественные имена — agents/, commands/, modes/, plugins/, skills/, tools/, themes/. Единственные имена вроде agent/ поддерживаются для обратной совместимости.
Практическое следствие: агент, нужный во всех проектах, кладите в глобальный каталог; агент под конкретный репозиторий — в проектный. Проектный слой переопределит глобальный при совпадении имён.
Видимость проверяйте с учётом режима: первичные агенты переключаются через Tab, а субагенты вызываются через @. Параметр hidden: true скрывает субагента из автодополнения. Затем проверьте каталог, синтаксис и поле disable; схема помогает проверить JSON-конфигурацию.
Порядок действий по выбранной задаче
Разберём настройку субагента для ревью кода. Это документированный сценарий: в справочнике по агентам приведён готовый пример code-reviewer.
Шаг 1. Выберите способ описания. JSON-конфиг удобен, когда агентов несколько и они живут рядом с другими настройками. Markdown-файл удобен, когда у агента длинный системный промпт: тело файла становится этим промптом, а метаданные — параметрами.
Шаг 2. Задайте режим. Для ревьюера подходит subagent: его вызывает основной агент через Task, а пользователь может вызвать его вручную через упоминание @. Документация указывает режимы primary, subagent и all; значение по умолчанию — all.
Шаг 3. Опишите назначение. Поле description — то, по чему основной агент понимает, когда звать субагента. Формулировка «Reviews code for best practices and potential issues» из документации проекта задаёт границы: качество и потенциальные проблемы.
Шаг 4. Выберите модель. Ревью требует аккуратности, поэтому в примере документации стоит anthropic/claude-sonnet-4-20250514. Для дешёвых операций есть отдельная опция small_model: она настраивает модель для облегчённых задач вроде генерации заголовков, и по умолчанию OpenCode пытается взять более дешёвую модель у провайдера.
Шаг 5. Напишите промпт. В документации проекта сказано: файл подсказки должен содержать инструкции, специфичные для целей агента. Подключается он через prompt со ссылкой вида {file:./prompts/code-review.txt}.
Шаг 6. Закройте лишние инструменты. Ревьюеру не нужны запись и правка. В примере документации для него выставлены write: false, edit: false, bash: false.
Шаг 7. Ограничьте разрешения. Если оставляете bash, задайте правила: "*": "ask", а конкретные безопасные команды — allow. В документации проекта приведён пример, где git diff, git log* и grep * разрешены, а webfetch запрещён.
Шаг 8. Проверьте. Позовите субагента на небольшом diff и посмотрите, какие инструменты он запрашивает. Если запросов больше ожидаемого — сузьте правила.
Порядок важен: режим и назначение определяют, кто и когда зовёт агента; модель и промпт определяют качество; разрешения определяют риск. Меняя всё сразу, вы не поймёте, что именно повлияло на результат.
Учебный пример и критерии проверки
Создайте .opencode/agents/docs-writer.md. Основа ниже следует документированному примеру агента документации; тело — учебная инструкция редакции.
---
description: Writes and maintains project documentation
mode: subagent
tools:
bash: false
---
Ты технический писатель проекта.
Сначала прочитай существующую документацию и связанные файлы кода.
Предложи план обновления документации и дождись подтверждения.
Описывай назначение функций, входы, выходы и примеры вызовов.
Отмечай сведения, которые невозможно установить по исходникам.
Меняй только согласованные файлы документации.
Имя markdown-файла становится именем агента. Вызовите @docs-writer на небольшом разделе документации. Перед запуском запишите ожидаемые файлы и результат; после ответа сравните их с планом.
Критерии проверки: файл находится в проектном каталоге agents; frontmatter отделён строками ---; агент вызывается по имени файла; использует режим subagent; предлагает план перед правками; bash отключён; правки относятся к согласованной документации. Это предложенная читателю учебная проверка своей установки.
Смежные варианты и что выбирать по задаче
Справочник по агентам перечисляет встроенные агенты OpenCode. Их стоит знать, чтобы не плодить дубли.
| Агент | Режим | Для чего |
|---|---|---|
| build | primary | Основная работа, все инструменты включены |
| plan | primary | Планирование, инструменты ограничены |
| general | subagent | Общие задачи |
| explore | subagent | Исследование кодовой базы |
| scout | subagent | Разведка по проекту |
| compaction | скрытый | Сжатие контекста |
| title | скрытый | Генерация заголовков |
| summary | скрытый | Сводки |
Разница между build и plan описана в документации проекта через разрешения: при сборке все инструменты включены, при планировании ограничены. Отсюда практическое правило: планируйте в plan, реализуйте в build.
Выбор по задаче выглядит так. Для ревью и аудита — субагент с закрытыми write и edit. Для исследования незнакомого репозитория — explore или собственный субагент с разрешёнными read, glob, grep. Для оркестрации нескольких субагентов — первичный агент с настройкой permission.task: в документации проекта показан пример, где "*": "deny", "orchestrator-*": "allow", а конкретный субагент — "ask".
Для сложных рассуждений есть параметры reasoningEffort и textVerbosity. В документации проекта приведён пример агента deep-thinker с моделью openai/gpt-5, reasoningEffort: "high" и textVerbosity: "low".
Для управления расходом выберите модель под задачу и ограничьте число итераций через steps; в документации есть пример steps: 5. Параметр small_model относится к облегчённым служебным задачам. Температура управляет вариативностью ответа: документация приводит низкое значение для анализа и высокое для генерации идей. Расход своей задачи оценивайте по фактическому использованию.
Скрытые агенты (title, summary, compaction) работают в фоне. Их настройка полезна, когда нужно поменять модель для служебных операций, не трогая основную.
Типичные проблемы и способы диагностики
Агент не появился в списке. Проверьте каталог: глобальный ~/.config/opencode/agents/, проектный .opencode/agents/. Проверьте имя подкаталога — в документации проекта указаны множественные имена. Проверьте метаданные markdown-файла: они отделяются строками ---.
Агент вызывается, но ведёт себя как основной. Проверьте mode. Значение all делает агента доступным и как первичный, и как субагент. Для чистого субагента ставьте subagent.
Субагент использует не ту модель. Вспомните правило наследования: без явной модели субагент берёт модель вызвавшего агента. Укажите model явно.
Агент просит подтверждение на каждое действие. Так работает ask. Посмотрите правила: в документации проекта описано, что правила оцениваются по шаблону и выигрывает последнее совпадающее. Универсальное "*" ставят первым, конкретные правила — после него.
Агент трогает файлы за пределами проекта. Для этого есть external_directory. В документации проекта отмечено, что расширение ~ влияет только на запись шаблона и не делает внешний путь частью рабочего пространства. Добавьте явные правила, например запрет на edit для внешнего каталога при сохранённом чтении.
Правила конфликтуют между слоями. Конфигурации объединяются. Сопоставьте модель и разрешения в глобальном и проектном файлах: при конфликте ключа действует источник с большим приоритетом. Оформление TUI проверяйте в отдельном tui.json.
Старая настройка tools не действует как ожидалось. В документации проекта указано, что начиная с v1.1.1 логическая конфигурация tools объединена с permission, а старая форма поддерживается для обратной совместимости. Переносите правила в permission.
Агент делает лишние шаги. Ограничьте steps. Это документированный параметр, применимый к субагентам.
Диагностика строится на сужении: сначала проверьте расположение файла, затем режим, затем модель, затем разрешения. Каждый шаг проверяется отдельным запуском на маленькой задаче.
Для самостоятельной проверки начните с задачи, в которой легко увидеть нарушение роли. Попросите агента изучить небольшой файл и подготовить предложение изменений. До запуска запишите, какие инструменты ему разрешены и какого результата вы ожидаете. После ответа сравните поведение с этими ожиданиями: агент должен оставаться в заданной роли, учитывать ограничения и объяснять необходимость действий, для которых требуется разрешение. Отдельно проверьте, понятны ли условия остановки и передачи работы человеку. Если результат не совпал с ожиданием, меняйте только соответствующее поле конфигурации и повторяйте ту же задачу. Этот порядок — учебное упражнение редакции; фактическое поведение своей версии OpenCode проверьте самостоятельно.
Дополнительное упражнение: проверить границы роли
Для проверки роли подготовьте небольшой учебный файл с понятным назначением. Попросите агента объяснить его устройство и предложить изменение в ответе. Заранее определите, разрешены ли изменения файлов в этом сценарии и в какой момент требуется подтверждение пользователя. Сопоставьте действия агента с собственным заданием и выбранными разрешениями. Если поведение расходится с ожиданием, сохраните исходный текст запроса и описание расхождения, затем перепроверьте относящиеся к задаче настройки.
Следующий сценарий посвятите передаче работы. Опишите в запросе, какой результат должен подготовить основной агент и какое поручение предполагается передать помощнику. Проверьте, какой агент действительно отвечает, какие данные получает и как возвращает результат. Условия такого упражнения определяет читатель; редакция не утверждает, что запускала его на конкретной версии приложения.
Для повторяемости сохраните название агента, расположение файла его настройки, выбранную модель, текст поручения и итоговый ответ. Такой журнал помогает сравнить поведение после изменения конфигурации. Меняйте только относящиеся к обнаруженной проблеме условия, сохраняя само поручение. В результате будет проще понять, объясняется ли различие настройками роли, изменением задачи или возможностями выбранной модели.
Частые вопросы
Как создать агента в OpenCode?
Два пути: добавить запись в секцию agent файла opencode.json либо положить markdown-файл в каталог agents/. В обоих случаях задаются режим, модель, промпт и разрешения. Для markdown-файла параметры идут в метаданных, а тело становится системным промптом.
Что такое субагенты OpenCode?
Это агенты, которых вызывает основной агент через инструмент задач. Пользователь общается с ними косвенно. Управлять тем, каких субагентов агент может звать, позволяет permission.task с шаблонами glob.
Как настроить агента в OpenCode для экономии токенов?
Выбирайте модель под задачу через поле model и ограничивайте число шагов параметром steps. Для облегчённых служебных задач предусмотрен small_model. Температура регулирует вариативность ответа; фактический расход сравнивают на одинаковых задачах.
Какой AI-агент использовать для OpenCode?
Начните со встроенных: build для реализации, plan для планирования, explore для исследования кода. Собственный агент нужен, когда задача повторяется и требует своего промпта и своего набора инструментов. Модель выбирается под задачу через provider/model-id.
Как работает оркестрация агентов на OpenCode?
Первичный агент получает правила permission.task и по ним решает, каких субагентов звать. В документации проекта показан пример с запретом всех по умолчанию, разрешением группы orchestrator-* и подтверждением для конкретного ревьюера. Такой конфиг удерживает вызовы внутри заданного набора.