Гайды

Как настроить субагента в Qwen Code

13 октября 2026 · 20 минут чтения

Проверка фактов

Юлия Найпак

Методист по автоматизации. Сверяет паспорт инструмента с документацией вендора.

Автор Р

Редакция

Коллектив авторов, редакторов и иллюстраторов статей на сайте блога онлайн-университета «Зерокодер». Пишем…

Черновик готовит редакция с помощью ИИ. За стандарт издания отвечает главный редактор — Валерий Курземнек.

Материал редакции Зерокодера. Счёт по выдаче снят собственным прогоном 13 октября 2026 года; цитаты источников приведены дословно. Обновлено: октябрь 2026.

Настроить субагента в Qwen Code можно через markdown-файл с YAML-заголовком: в документации проекта субагенты описаны как специализированные ИИ-ассистенты, которые решают отдельные типы задач внутри Qwen Code. Файл кладут в .qwen/agents/ на уровне проекта или в ~/.qwen/agents/ на уровне пользователя, после чего агент обнаруживается командой /agents manage и вызывается на конкретной задаче.

Что такое субагент и где проходят границы продукта

В документации QwenLM субагенты определены как специализированные ИИ-ассистенты, которые берут на себя отдельные типы задач внутри Qwen Code. Это определение задаёт границу: субагент живёт внутри клиента Qwen Code и работает в его сессии. Он не является отдельным сервисом, не запускается автономно и не подключается к сторонним API сам по себе.

Границы стоит держать в голове перед настройкой. Субагент — это конфигурация поведения. Роль задаётся системным промптом в теле файла, набор инструментов — полями tools и disallowedTools, модель — полем model. Всё это работает в рамках той сессии Qwen Code, из которой вы его вызвали.

Отдельно документация описывает механику Fork subagent — ответвление текущего контекста для параллельной работы. Это смежный инструмент, и о нём ниже есть отдельный раздел. Именованный субагент и форк — разные вещи: первый задаётся файлом и вызываетcя по имени, второй создаётся как ответвление сессии.

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

Что стоит проверить перед началом:

• Qwen Code установлен и запускается — порядок установки описан в быстром старте Qwen Code.
• Вы понимаете, в какой директории открыт проект: от неё зависит, куда ляжет файл агента.
• Сессия не в plan mode, если агенту предстоит править файлы.
• Есть небольшая задача для проверки — например, ревью одного файла.

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

Формат хранения описан в документации QwenLM: субагенты настраиваются через markdown-файлы с YAML-заголовком. Это значит, что файл читается человеком, лежит в репозитории и версионируется вместе с кодом. Такая схема удобна для команд: определение агента можно положить в проект и передать коллегам вместе с кодом.

Условия доступа и источник актуальных требований

Источник актуальных требований — официальная документация проекта на qwenlm.github.io. Там описаны формат файла, места хранения, поля заголовка и команды управления. Другие страницы того же домена дополняют картину: раздел про инструмент agent описывает делегирование задач, раздел быстрого старта — установку и запуск.

Доступ к самому Qwen Code из России в прочитанных материалах не описан. Эта тема разобрана в отдельной статье про работу Qwen без ВПН — там собраны практические наблюдения. Для настройки субагента важно другое: клиент должен быть установлен и аутентифицирован, иначе команды агента просто некуда вводить.

Числа по выдаче стоит привести отдельно. Мы скачали подборку результатов веб-поиска по запросу «Как настроить субагента в Qwen Code»: текст отдали 8 из 10 страниц. Медиана объёма читаемого текста топа — 4401 слово. Метку 2026 года несут 7 из 8 прочитанных страниц.

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

Актуальность требований проверяют так:

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

Ещё одна точка контроля — режимы одобрения. В заголовке агента поле approvalMode может принимать значения default, plan, auto-edit, yolo, bubble. Значение определяет, сколько подтверждений потребует агент при работе с файлами. Для учебной задачи разумно оставить default, а yolo включать осознанно: этот режим снижает число подтверждений.

Документированный порядок создания своего агента

Создание агента в Qwen Code идёт по документированному маршруту. В документации QwenLM указана команда /agents create — она открывает создание нового определения. Команда /agents manage служит для управления уже существующими агентами. Через неё же удобно проверять, что файл подхватился.

Порядок действий:

1. Откройте Qwen Code в директории проекта.
2. Введите /agents create, чтобы начать создание определения.
3. Заполните поля: name — имя агента, description — когда и как его применять.
4. Задайте model, если агенту нужна другая модель; значение inherit берёт модель основной сессии.
5. Перечислите tools — список разрешённых инструментов; можно вместо этого указать disallowedTools как блок-лист.
6. Напишите системный промпт в теле файла: роль, границы задачи, формат ответа.
7. Сохраните файл и проверьте его командой /agents manage.

Место хранения определяет приоритет. В документации QwenLM описаны три уровня: проектный .qwen/agents/ имеет наивысший приоритет, пользовательский ~/.qwen/agents/ используется как запасной вариант, а агенты уровня расширения поставляются установленными расширениями. Если имя агента совпадает на разных уровнях, проектное определение выигрывает.

Структура заголовка из документации выглядит так: name, description, опциональные model, approvalMode, tools, disallowedTools, а после разделителя --- идёт текст системного промпта. Значение model может быть inherit, fast, конкретным идентификатором модели или строкой вида authType:modelId.

Поле tools работает как список разрешённых инструментов. Если его опустить, субагент наследует все доступные инструменты родительской сессии — это указано в документации QwenLM. Такой вариант удобен для быстрого старта, но для узкой роли лучше ограничить набор явно: ревьюеру достаточно чтения, а правки пусть делает основная сессия.

Практический совет по именам: называйте агента по задаче. code-reviewer переживёт смену модели, qwen-reviewer устареет при первом же обновлении. Описание пишите как инструкцию для основной сессии — модель выбирает субагента по этому полю, поэтому фраза «используй для проверки диффа перед коммитом» работает лучше, чем «хороший агент для кода».

Проверка после создания занимает минуту. Введите /agents manage, найдите агента в списке, убедитесь, что описание совпадает с ожидаемым. Затем вызовите его на маленькой задаче — об этом следующий раздел. Если агент не появился в списке, проверьте путь: файл должен лежать в .qwen/agents/ внутри проекта или в ~/.qwen/agents/ в домашней директории.

Учебный пример: агент ревью и критерии проверки

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

Задача промпта — создать субагента-ревьюера для одного файла:

---
name: readme-reviewer
description: Проверяет README на ясность и структуру. Используй, когда нужно ревью документации перед коммитом.
model: inherit
approvalMode: default
tools:
  - read_file
---

Ты ревьюер документации. Прочитай указанный файл README и выдай замечания по структуре, ясности и полноте.

Формат ответа:
1. Список проблем с указанием раздела.
2. Предложение правки для каждой проблемы.
3. Итоговая оценка готовности к публикации.

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

Что менять под себя: значение name — на [имя вашего агента], description — на [вашу задачу и момент вызова], список tools — на [нужный набор инструментов], а в теле промпта — роль и формат ответа под [ваш предмет ревью].

Вызов на задаче ревью выглядит как обычный запрос к основной сессии с указанием агента. В документации QwenLM делегирование описано как работа через инструмент agent: основная сессия передаёт задачу выбранному субагенту и получает результат. Это удобно формулировать прямо: «проверь README агентом readme-reviewer».

Критерии самостоятельной проверки результата:

Учебный пример проверяет не качество модели, а качество настройки. Если агент вышел за границы и начал править файлы, проблема в промпте или в наборе инструментов. Если ответ пришёл без структуры, промпт недостаточно явно задаёт формат. Если агент не запустился, стоит проверить список через /agents manage и точность вызова.

Варианты того же задания, если основная задача освоена:

• Агент для проверки сообщений коммитов на соответствие шаблону.
• Агент для поиска неиспользуемых импортов в указанном файле.
• Агент для сверки описания API с примерами в документации.
• Агент для проверки ссылок в markdown-файле.

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

Смежные варианты: именованные агенты и fork

В документации QwenLM описаны два подхода к делегированию. Именованный субагент задаётся файлом и вызывается по имени. Форк создаётся как ответвление текущего контекста сессии и работает с ним.

Параметры форка в документации описаны отдельно. fork_turns управляет тем, сколько ходов контекста наследует форк. fork_tools ограничивает выполнение инструментов в форке. fork_profile позволяет переиспользовать ограничения между запусками. Эти поля относятся к механике форка и настраиваются в момент ответвления.

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

Таблица выбора:

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

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

Типичные проблемы и проверяемые способы диагностики

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

Агент не появился в списке. Проверьте путь: проектный уровень — .qwen/agents/, пользовательский — ~/.qwen/agents/. Убедитесь, что файл имеет расширение .md и YAML-заголовок отделён разделителем ---. Затем повторите /agents manage.

Агент создан, но не вызывается. Смотрите на поле description: основная сессия выбирает субагента по нему. Формулировка «когда использовать» помогает модели принять решение. Точное имя в запросе тоже работает: назовите агента прямо.

Инструменты не сработали. Если поле tools задано, набор ограничен перечисленным. Если tools опущено, субагент наследует все инструменты родительской сессии. Проверьте также блок-лист disallowedTools: он может отсекать нужный инструмент.

Правки не применяются. В документации QwenLM указано, что plan mode родительской сессии удерживает субагента в plan mode, а сессия только для анализа не может менять файлы через делегированного агента. Проверьте режим сессии и поле approvalMode.

Отдельная категория — общие сбои клиента, не связанные с агентами. Если Qwen Code не отвечает, команды не выполняются или сессия падает, это не про настройку субагента. Разбор таких случаев собран в статье Qwen Code не работает — там перечислены причины и решения.

Порядок диагностики стоит держать фиксированным: путь файла, формат заголовка, список через /agents manage, формулировка вызова, режим сессии, ограничения инструментов. Такой порядок отсекает большинство ошибок за несколько минут. Меняйте по одной вещи за раз, иначе причина сбоя потеряется.

Практикум: проверить субагента на небольшом проекте

Ниже — предлагаемый редакцией учебный процесс. Он помогает оценить созданного агента на собственном проекте. Редакция этот набор заданий не запускала; образцы запросов показывают форму задания, а ответы и изменения читатель проверяет самостоятельно. Начните с копии небольшого проекта, где вам понятны назначение файлов и ожидаемое поведение программы. Для первого упражнения достаточно существующего приложения с простым пользовательским действием: отправкой формы, поиском в списке или чтением записи. Выберите действие, для которого сможете объяснить правильный результат без помощи модели.

Перед запуском запишите назначение вашего субагента обычным предложением. Например: он читает обработчик формы и ищет причины, по которым пользователь может отправить неполные данные. Такое предложение задаёт проверяемый результат. Вы сможете открыть названный обработчик, сверить условия и воспроизвести обнаруженный случай. Если назначение расплывчатое, результат будет сложно оценить: общий совет улучшить качество программы не показывает, какую проблему агент нашёл и на чём основан вывод.

Подготовьте для себя короткую карточку ожидаемого поведения. Укажите, какие поля обязательны, какой ответ получает пользователь при ошибке, где хранится результат и какое действие запускает обработчик. Карточка служит ориентиром для проверки. Если в существующем приложении требования нигде не записаны, обозначьте свою карточку как предложенный вариант требований. Агент должен различать фактический код и ваше ожидание. Это полезная привычка для любой работы с помощником: неизвестные условия остаются неизвестными до уточнения.

Упражнение: разбор формы без изменения файлов

Сформулируйте запрос, который можно выполнить чтением проекта. Используйте реальное имя созданного субагента в своём привычном способе вызова. Текст задания можно взять за основу:

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

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

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

Упражнение: превратить находку в план исправления

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

Для подтверждённого случая предложи минимальный план исправления. Укажи, какие условия нужно проверить, где должно появиться понятное сообщение пользователю и какое существующее поведение требуется сохранить. Пока не меняй файлы. Перечисли вопросы, которые нужно уточнить у автора требований. Если есть несколько разумных вариантов, объясни последствия каждого для пользователя формы.

Прочитайте план как владелец приложения. Убедитесь, что предлагаемые проверки соответствуют требованиям. Например, пустая строка, строка из пробелов и отсутствующее поле могут попадать в разные ветки обработчика. Спросите, как план учитывает каждую из этих ситуаций. Для числового поля уточните, где производится преобразование и какое сообщение появится при неверном формате. Используйте реальные правила вашего приложения; демонстрационный проект не определяет универсальную политику проверки данных.

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

Упражнение: составить проверку результата

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

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

Хороший сценарий помогает воспроизвести поведение. Читатель должен понимать, что ввести, какое действие выполнить и что наблюдать на странице или в результате обработки. Формулировка «проверить корректность формы» слишком общая для такого упражнения. Попросите заменить её на конкретное действие и ожидаемое сообщение. Проверьте также успешный путь: исправление обработки неверного ввода должно сохранять возможность отправить правильные данные. Набор сценариев вы выбираете по требованиям своего проекта.

Во время самостоятельной проверки записывайте фактический результат рядом с ожиданием. Если поведение расходится, сначала сохраните наблюдение: состояние формы, входные данные и сообщение. Затем можно передать агенту этот контекст для нового разбора. Уточняйте, что вы действительно наблюдали, а что предполагаете. Это делает обратную связь полезной и помогает избежать цепочки объяснений, построенных на неподтверждённом исходном случае.

Упражнение: сравнить назначение роли с полученным ответом

Вернитесь к карточке назначения субагента. Посмотрите, какие части работы он выполнил: нашёл соответствующий файл, объяснил условие, отметил неизвестные требования, предложил воспроизводимую проверку. Если ответ оказался полезным только после длинного уточнения, запишите, какой информации не хватало исходному заданию. Это основание улучшить описание роли и инструкцию. Изменяйте формулировку целиком и проверяйте её на понятном примере; одновременно менять задачу, проект и описание роли неудобно для сравнения результатов.

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

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

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

Как оформить заметку для повторного запуска

После практикума составьте компактную запись, по которой можно повторить разбор. Начните с задачи пользователя приложения: какое действие он выполняет и что должно произойти. Затем назовите выбранный обработчик и объясните, почему он относится к этому действию. Рядом сохраните исходный запрос субагенту. Читатель такой заметки должен понимать связь между задачей, переданным контекстом и ожидаемой формой ответа. Если вы передавали требования отдельным сообщением, сохраните их вместе с запросом.

Следующая часть записи — подтверждённые выводы. Для каждого вывода укажите основание, которое удалось открыть в проекте, и действие вашей проверки. Например, вы нашли условие проверки строки, проследили вызов обработчика и самостоятельно наблюдали сообщение при пустом поле. Описывайте только выполненные действия. Если сообщение предположено по коду, прямо обозначьте, что это вывод из чтения. Если программа не запускалась, запись не должна выглядеть как отчёт о работающем исправлении.

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

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

Перед повторным запуском перечитайте входные материалы глазами будущего пользователя роли. Замените общие слова на известные имена файлов и объясните назначение неизвестных сокращений. Укажите, где находятся требования, и отдельно отметьте предложенные ожидания. Такая подготовка уменьшает неоднозначность задания и облегчает проверку ответа. После запуска сохраните исходный запрос рядом с фактическими наблюдениями, чтобы следующий участник команды мог восстановить ход разбора.

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

Как настроить субагента в Qwen Code с нуля?
Создайте markdown-файл с YAML-заголовком и положите его в .qwen/agents/ внутри проекта или в ~/.qwen/agents/ в домашней директории. В заголовке укажите имя, описание и при необходимости модель и инструменты, в теле — системный промпт. Затем проверьте агента командой /agents manage.

Какие поля обязательны в файле агента?
В документации QwenLM в структуре заголовка указаны name и description. Поля model, approvalMode, tools и disallowedTools помечены как опциональные. Тело файла после разделителя содержит системный промпт, который задаёт роль агента.

Что делает команда /agents create?
Эта команда начинает создание нового определения агента. Через неё удобно задать имя, описание и роль, не собирая файл вручную. Управление уже созданными агентами идёт через /agents manage.

Чем субагент отличается от fork?
Именованный субагент задаётся файлом, хранится в проекте или у пользователя и переиспользуется между сессиями. Форк создаётся как ответвление текущего контекста и настраивается через fork_turns, fork_tools и fork_profile. Первый подходит для повторяющихся ролей, второй — для параллельной работы внутри задачи.

Почему субагент не может изменить файлы?
В документации QwenLM указано, что plan mode родительской сессии удерживает субагента в plan mode, а сессия только для анализа не может менять файлы через делегированного агента. Проверьте режим сессии и значение approvalMode в заголовке агента.