Подробное объяснение конфигурации OpenCode Agent

Агенты — это специализированные ИИ-ассистенты в OpenCode. Каждый агент можно настроить с собственным системным промптом, моделью, разрешениями на доступ к инструментам и поведенческими ограничениями для выполнения определенных типов задач и рабочих процессов. Вы можете переключать агентов в любой момент во время сессии или@ProxyNameнапрямую вызвав конкретного агента.

Типы агентов

Агенты в OpenCode делятся на два типа, у каждого свои способы вызова и обязанности:

Type	Описание	Способ переключения
Основной агент	Основной ассистент, с которым вы взаимодействуете напрямую и который ведет основной диалог. Разрешения на доступ к инструментам задаются через`permission`configuration	нажмите`Tab`переключение клавиш по циклу или используйте настроенную`agent_cycle`горячую клавишу
Субагент	Ассистент, вызываемый основным агентом для выполнения специализированных задач, работающий в независимой дочерней сессии и не влияющий на контекст основной сессии	Автоматически вызывается основным агентом или вызывается вручную в сообщении с помощью`@ProxyName`вызвать вручную

Встроенные агенты

OpenCode включает 4 готовых к использованию агента, а также 3 автоматически запускаемых системных агента:

1. Build (основной агент)

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

2. Plan (основной агент)

Ограниченный агент, предназначенный специально для анализа кода и планирования. По умолчанию следующие операции вызывают запрос на подтверждение (установлено вask）：

правки файлов: все операции write, patch и edit
bash: все команды bash

Когда вы хотите, чтобы LLM проанализировала код, дала предложения или создала план выполнения, но не хотите, чтобы она вносила какие-либо фактические изменения в кодовую базу, переключитесь на агента Plan.

3. General (субагент)

Субагент общего назначения с полным доступом к инструментам (кроме инструмента todo) и возможностью изменять файлы. Подходит для исследования сложных проблем и выполнения многошаговых задач, а также может параллельно запускать несколько независимых рабочих единиц.

4. Explore (субагент)

Субагент только для чтения, который не может изменять файлы. Подходит для быстрого поиска файлов, поиска ключевых слов в коде или ответов на вопросы о структуре кодовой базы. Он быстрый и не имеет побочных эффектов.

5. Системные агенты (скрытые)

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

Имя агента	Ответственность	Момент срабатывания
Compaction	Сжимает слишком длинный контекст в краткое резюме, чтобы не превысить лимит контекста модели	Автоматически запускается, когда длина контекста достигает порогового значения
Title	Генерирует короткое название для сессии	Автоматически запускается после начала новой сессии
Итог	Создаёт резюме для сессии	Автоматически запускается, когда требуется резюме сессии

Как использовать агентов

1. Переключение основных агентов

Во время сеанса нажмитеTabклавишу, чтобы переключаться между всеми основными агентами, нажмитеShift+Tabчтобы переключиться в обратном порядке. Также можно использовать<Leader>aчтобы открыть список агентов и выбрать напрямую.

2. Вызов субагентов

Существует два способа вызвать субагентов:

Автоматический вызов: Когда основной агент определяет, что на основе характера задачи нужен определённый субагент, он автоматически вызывает субагента и делегирует ему задачу
Ручной вызов @: Используйте в сообщении@ProxyNameчтобы напрямую указать, какой субагент должен это обработать

@general help me search for this function across the codebase

3. Навигация между родительскими и дочерними сессиями

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

Сочетание клавиш	Действие
`<Leader>+→`（`session_child_cycle`）	Цикл вперёд: Родительская сессия → Дочерняя сессия 1 → Дочерняя сессия 2 → … → Родительская сессия
`<Leader>+←`（`session_child_cycle_reverse`）	Цикл назад: Родительская сессия ← Дочерняя сессия 1 ← Дочерняя сессия 2 ← … ← Родительская сессия
`<Leader>+↑`（`session_parent`）	Вернуться напрямую к родительской сессии

Два способа настройки

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

Способ 1: Настройка в opencode.json

Пример

{
"$schema": "https://opencode.ai/config.json",
"agent": {
"build": { // Переопределить конфигурацию встроенного агента build
"mode": "primary",
"model": "anthropic/claude-sonnet-4-20250514",
"prompt": "{file:./prompts/build.txt}", // Загрузить системный промпт из файла
"tools": {
"write": true,
"edit": true,
"bash": true
}
},
"code-reviewer": { // Пользовательский субагент
"description": "Анализирует код на предмет лучших практик и потенциальных проблем",
"mode": "subagent",
"model": "anthropic/claude-sonnet-4-20250514",
"prompt": "Вы — код-ревьюер. Сосредоточьтесь на безопасности, производительности и сопровождаемости.",
"tools": {
"write": false,
"edit": false
}
}
}
}

Способ 2: Markdown-файл

Создать.mdфайл по следующему пути,Имя файла — это имя агента(e.g.,review.mdсоответствует имени агентаreview）：

Глобально:~/.config/opencode/agents/(Действует для всех проектов)
Уровень проекта:.opencode/agents/(Действует только для текущего проекта)

Пример

# Путь к файлу: ~/.config/opencode/agents/review.md
---
description: Проверяет код на качество и соответствие лучшим практикам
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
write: false
edit: false
bash: false
---

Вы находитесь в режиме проверки кода. Сосредоточьтесь на:

- Качество кода и лучшие практики
- Потенциальные ошибки и граничные случаи
- Влияние на производительность
- Вопросы безопасности

Предоставляйте конструктивную обратную связь, не внося прямых изменений.

Объяснение параметров конфигурации

description (Описание)

Описание функциональности агента, отображаемое в списке агентов и@меню автодополнения. Оно помогает пользователям и основному агенту решать, когда вызывать этого агента. Для пользовательских агентов это поле являетсяобязательным：

Пример

{
"agent": {
"review": {
"description": "Анализирует код на предмет лучших практик и потенциальных проблем"
}
}
}

mode (Режим)

Определяет, как используется агент. Его можно установить в одно из следующих трех значений:

Значение	Описание
`"primary"`	Основной агент, появляется в списке переключения вкладок, используется для основного диалога
`"subagent"`	Субагент, отсутствует в списке переключения вкладок, вызывается основным агентом или вручную через @
`"all"`	Используется и как основной агент, и как субагент (значение по умолчанию, когда режим не указан)

Пример

{
"agent": {
"review": {
"mode": "subagent" // Используется только как субагент, не отображается в списке переключения основных агентов
}
}
}

model (Модель)

Указывает конкретную модель для агента, переопределяя модель по умолчанию в глобальной конфигурации. Формат:provider/model-id. Подходит для использования разных моделей для разных задач, например, более быстрой небольшой модели для задач планирования и более мощной большой модели для генерации кода:

Пример

{
"agent": {
"plan": {
"model": "anthropic/claude-haiku-4-20250514" // Использовать более быструю модель Haiku для задач планирования
},
"build": {
"model": "anthropic/claude-sonnet-4-20250514" // Использовать более мощную модель Sonnet для задач разработки
}
}
}

Если не указаноmodel, основной агент будет использовать модель по умолчанию из глобальной конфигурации, а субагенты унаследуют модель, используемую основным агентом, который их вызвал. Запускopencode modelsВы можете просмотреть список всех доступных моделей.

prompt (системный промпт)

Укажите пользовательский системный промпт для агента. Можно написать строку напрямую или использовать{file:./路径}синтаксис для загрузки из внешнего файла. Путь указывается относительно расположения файла конфигурации:

Пример

{
"agent": {
"review": {
"prompt": "{file:./prompts/code-review.txt}"
// Читать промпт из prompts/code-review.txt в том же каталоге, что и opencode.json
// Подходит для длинных промптов; храните их отдельно в текстовом файле
}
}
}

temperature

Управляет случайностью вывода модели. Более низкие значения дают более детерминированный вывод, подходящий для задач, требующих точных результатов; более высокие значения дают более разнообразный вывод, подходящий для творческих задач:

Диапазон температуры	Характеристики вывода	Применимые сценарии
0.0 – 0.2	Высокая сфокусированность, высокая детерминированность	Анализ кода, планирование, отладка, ревью
0.3 – 0.5	Сбалансированный, сочетающий точность и гибкость	Общие задачи разработки, написание документации
0.6 – 1.0	Более творческий и разнообразный	Мозговой штурм, поиск решений, творческое письмо

Пример

{
"agent": {
"analyze": {
"temperature": 0.1, // Задачи анализа: высокая детерминированность
"prompt": "{file:./prompts/analysis.txt}"
},
"build": {
"temperature": 0.3 // Задачи разработки: сбалансировано
},
"brainstorm": {
"temperature": 0.7, // Мозговой штурм: более креативно
"prompt": "{file:./prompts/creative.txt}"
}
}
}

Если не указаноtemperature, OpenCode использует значение по умолчанию модели — большинство моделей по умолчанию принимают значение0, тогда как модели серии Qwen по умолчанию принимают значение0.55。

steps (Максимальное число шагов)

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

Пример

{
"agent": {
"quick-thinker": {
"description": "Быстрые рассуждения с ограниченным числом итераций",
"prompt": "Ты — быстрый мыслитель. Решай задачи с минимальным числом шагов.",
"steps": 5 // Выполнить не более 5 итераций; после этого агент выведет сводку текущего прогресса и оставшихся предлагаемых задач
}
}
}

Если не заданоsteps, агент будет продолжать итерации, пока модель не остановится сама или пользователь не прервёт вручную.

УстаревшееmaxStepsполе не рекомендуется к использованию, используйтеsteps。

tools (Доступ к инструментам)

Управляет тем, какие инструменты может использовать этот агент. Установите имя инструмента вtrueилиfalse. Конфигурация уровня агентапереопределит глобальную конфигурацию：

Пример

{
"$schema": "https://opencode.ai/config.json",
"tools": {
"write": true, // Глобально: разрешить запись файлов
"bash": true // Глобально: разрешить команды bash
},
"agent": {
"plan": {
"tools": {
"write": false, // plan agent: переопределить глобальные настройки, отключить запись файлов
"bash": false // plan agent: переопределить глобальные настройки, отключить bash
}
}
}
}

Вы также можете использовать подстановочные знаки для массового управления инструментами, например, отключить все инструменты с определенного сервера MCP:

Пример

{
"agent": {
"readonly": {
"tools": {
"mymcp_*": false, // Отключить все инструменты с сервера mymcp (сопоставление по Glob)
"write": false,
"edit": false
}
}
}
}

permission (Разрешения)

Настройте более детальный контроль разрешений для агента. Вы можете установить для каждой операции"allow"(allow),"ask"(ask), или"deny"(deny):

Пример

{
"$schema": "https://opencode.ai/config.json",
"permission": {
"edit": "deny" // Глобально: запретить редактирование всех файлов по умолчанию
},
"agent": {
"build": {
"permission": {
"edit": "ask" // build agent: переопределить глобальные настройки, требовать одобрения перед редактированием
}
}
}
}

Дляbashинструментов, можно дополнительно уточнить до конкретных команд, с поддержкой подстановочных знаков Glob, ипоследнее совпавшее правило имеет приоритет(Рекомендуется размещать*правила с подстановочными знаками сначала, а конкретные правила позже):

Пример

{
"agent": {
"build": {
"permission": {
"bash": {
"*": "ask", // Резервный вариант: все команды bash по умолчанию требуют одобрения
"git status *": "allow",// команды, связанные с git status, разрешаются напрямую (более конкретное правило имеет приоритет)
"grep *": "allow" // команды поиска grep разрешаются напрямую
}
}
}
}
}

В Markdown-файле агента можно также настроить разрешения в frontmatter:

Пример

# Путь к файлу: ~/.config/opencode/agents/review.md
---
description: Проверка кода без правок
mode: subagent
permission:
edit: deny # Запретить любое редактирование файлов
bash:
"*": ask # команды bash по умолчанию требуют одобрения
"git diff": allow # Разрешить git diff
"git log*": allow # Разрешить git log и его варианты
"grep *": allow # Разрешить поиск grep
webfetch: deny # Запретить доступ к внешним URL
---

Только анализировать код и предлагать изменения.

permission.task (Разрешения Task)

Управляет тем, каких субагентов этот агент может вызывать через инструмент Task. Поддерживает сопоставление Glob. Установите в"deny", субагент будет полностью удалён из описания инструмента Task, и модель не будет пытаться его вызвать:

Пример

{
"agent": {
"orchestrator": {
"mode": "primary",
"permission": {
"task": {
"*": "deny", // Запасной вариант: по умолчанию запретить вызов всех субагентов
"orchestrator-*": "allow", // Разрешить вызов субагентов, имена которых начинаются с orchestrator-
"code-reviewer": "ask" // Вызов code-reviewer требует подтверждения пользователя
// Последнее совпадающее правило имеет приоритет: orchestrator-planner соответствует и *, и orchestrator-*,
// Поскольку orchestrator-* идёт позже, результат — allow
}
}
}
}
}

hidden (Скрытый)

Скрывает субагента из@меню автодополнения и позволяет вызывать его только программно через инструмент Task. Подходит для инструментальных субагентов, которые должны вызываться только изнутри другими агентами:

Пример

{
"agent": {
"internal-helper": {
"mode": "subagent", // hidden работает только для субагентов
"hidden": true // После скрытия этот агент не будет отображаться в меню автодополнения @ пользователя,
// но когда разрешения позволяют, модель всё ещё может вызвать его через инструмент Task
}
}
}

color

Настраивает цвет отображения агента в интерфейсе. Поддерживает шестнадцатеричные значения цвета или ключевые слова цветов темы (primary、secondary、accent、success、warning、error、info）：

Пример

{
"agent": {
"creative": {
"color": "#ff6b6b" // Использовать шестнадцатеричный цвет
},
"code-reviewer": {
"color": "accent" // Использовать ключевое слово цвета темы
}
}
}

top_p (Разнообразие сэмплирования)

top_pДаtemperatureЕщё один параметр для управления разнообразием вывода, диапазон значений 0.0 – 1.0. Более низкие значения дают более сфокусированный вывод, более высокие — более разнообразный вывод:

Пример

{
"agent": {
"brainstorm": {
"top_p": 0.9 // Более высокое top_p увеличивает разнообразие вывода
}
}
}

disable (Отключить)

Переводит агента в отключённое состояние. После отключения агент не будет отображаться в списке выбора:

Пример

{
"agent": {
"review": {
"disable": true // Отключить этого агента, не влияя на других агентов
}
}
}

Другие параметры модели

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

Пример

{
"agent": {
"deep-thinker": {
"description": "Агент, использующий высокие усилия рассуждения для сложных задач",
"model": "openai/gpt-5",
"reasoningEffort": "high", // Параметр усилия рассуждения OpenAI, передаваемый напрямую в OpenAI API
"textVerbosity": "low" // Параметр подробности ответа OpenAI
}
}
}

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

Быстрое создание агентов

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

opencode agent create

Эта команда проведёт вас через следующие шаги по порядку:

Выберите, где сохранить агента (глобально~/.config/opencode/agents/или на уровне проекта).opencode/agents/）
Опишите обязанности и цели агента
Автоматически сгенерировать подходящий системный промпт и идентификатор агента
Выберите, к каким инструментам агент может получить доступ
Сгенерируйте Markdown-файл с полной конфигурацией в выбранном расположении

Примеры агентов

Агент для написания документации

Пример

# Путь к файлу: ~/.config/opencode/agents/docs-writer.md
---
description: Пишет и поддерживает документацию проекта
mode: subagent
tools:
bash: false # Отключить bash; для написания документации не нужно выполнять команды
---

Вы технический писатель. Создавайте чёткую, всеобъемлющую документацию.

Сосредоточьтесь на:
- Чёткие объяснения
- Правильная структура
- Примеры кода
- Язык, понятный пользователю

Агент аудита безопасности

Пример

# Путь к файлу: ~/.config/opencode/agents/security-auditor.md
---
description: Проводит аудит безопасности и выявляет уязвимости
mode: subagent
tools:
write: false # Только для чтения: не записывать файлы
edit: false # Только для чтения: не редактировать файлы
---

Вы эксперт по безопасности. Сосредоточьтесь на выявлении потенциальных проблем безопасности.

Ищите:
- Уязвимости проверки входных данных
- Недостатки аутентификации и авторизации
- Риски раскрытия данных
- Уязвимости зависимостей
- Проблемы безопасности конфигурации

Типичные случаи использования

Сценарий	Рекомендуемая конфигурация агента
Повседневная разработка, требуются полные разрешения для инструментов	Используйте встроенныйBuildагент
Анализируйте код и создавайте планы без изменения файлов	Переключитесь на встроенныйPlanагент
Запрос только для чтения по структуре кодовой базы или ключевым словам	Через`@explore`вызовите встроенногоExploreсубагента
Выполняйте несколько независимых задач параллельно	Через`@general`вызвать несколькоGeneralсубагентов для параллельной обработки
Выполнить проверку безопасности или качества кода	Пользовательский субагент только для чтения (отключить write/edit), установить низкую температуру (0.1)
Контролировать расходы, ограничивать количество шагов выполнения ИИ	Настройте`steps`параметр для ограничения максимального количества итераций

Другие расширения