Настраиваем Qwen Code под проект: QWEN.md, правила, MCP, субагенты и песочница

—

от автора

После установки Qwen Code работает «как есть»: каждый раз заново изучает репозиторий, спрашивает одно и то же и тратит токены на то, что можно было сказать один раз. В прошлой статье разбирали, как подключить Qwen Code к своему ключу и OpenAI-совместимому провайдеру. Теперь — следующий шаг: настроить его под конкретный проект так, чтобы он меньше спрашивал, меньше тратил и не мог случайно навредить.

Что будем настраивать:

  1. QWEN.md — постоянные инструкции для проекта.

  2. Правила — инструкции, которые подгружаются только когда нужны.

  3. Режимы подтверждений и разрешения — что агент делает сам, а что только с вашего согласия.

  4. MCP-серверы — внешние инструменты.

  5. Субагенты — узкие помощники со своими инструкциями и ограниченными правами.

  6. Песочница — чтобы команды агента не выходили за пределы проекта.

Всё проверено по документации Qwen Code версии 0.28.0 (ноябрь 2026). Проект развивается быстро, поэтому если у вас другая версия, сверяйтесь с qwen --help и документацией в репозитории.

Где лежат настройки

Почти всё настраивается в двух местах:

Файл

Действует

~/.qwen/settings.json

Для вас во всех проектах

.qwen/settings.json в корне проекта

Только в этом проекте

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

1. QWEN.md: один раз объяснить проект

QWEN.md — обычный Markdown-файл, который Qwen Code читает в начале каждой сессии. Сюда стоит писать то, что иначе приходится повторять каждый раз: как собрать и протестировать проект, какие договорённости приняты в команде, чего делать нельзя.

Файлов может быть три, и загружаются все сразу:

Файл

Для кого

~/.qwen/QWEN.md

Для вас, во всех проектах

QWEN.md в корне проекта

Для всей команды, коммитится в git

.qwen/QWEN.local.md

Только для вас и только в этом проекте

Локальный файл загружается после общего, поэтому им можно дополнять или переопределять командные инструкции. Добавить его в .gitignore придётся вручную, сам Qwen Code этого не сделает.

Если в репозитории уже есть AGENTS.md для других ИИ-инструментов, Qwen Code прочитает и его. Дублировать не нужно.

Как быстро начать. Команда /init изучит код и создаст черновик QWEN.md с командами сборки и найденными соглашениями. Если файл уже есть, она предложит дополнения, а не перезапишет его.

Пример хорошего QWEN.md:

# Проект: API заказовОбзор проекта: @README.md## Команды- Установка зависимостей: `pnpm install` (не npm)- Тесты: `pnpm test`, один файл: `pnpm test path/to/file.test.ts`- Линтер перед коммитом: `pnpm lint --fix`## Договорённости- Контроллеры не обращаются к базе напрямую, только через репозитории в `src/repositories/`- Новые эндпоинты описываются в `openapi.yaml` до реализации- Миграции не редактируются после мержа, только новые## Нельзя- Трогать `src/legacy/` без явной просьбы- Коммитить и пушить без моего подтверждения

Через @путь/к/файлу можно подключать другие файлы, пути считаются от самого QWEN.md.

Главное правило — коротко и конкретно. Документация прямо предупреждает: чем длиннее файл, тем хуже модель ему следует. «Используй отступ в 2 пробела в TypeScript» работает, «пиши код аккуратно» — нет. Не пишите в QWEN.md то, что модель и так поймёт из кода.

И ещё одна причина держать его коротким: QWEN.md уходит в каждый запрос каждой сессии. Каждая лишняя строка — это токены, которые вы оплачиваете много раз.

Автопамять. Помимо QWEN.md, Qwen Code сам сохраняет заметки о ваших предпочтениях и проекте в ~/.qwen/projects/<проект>/memory/. Ей можно управлять вручную:

  • /remember всегда использовать snake_case в Python — запомнить сразу;

  • /forget старый обходной путь для бага логина — забыть;

  • /memory — посмотреть, какие файлы загружены, и включить или выключить автопамять.

Автопамять работает «по возможности». То, что должно соблюдаться всегда, пишите в QWEN.md.

2. Правила: инструкции по требованию

Если QWEN.md разрастается, часть инструкций стоит вынести в правила. Правило — это Markdown-файл в .qwen/rules/. Главное его отличие — поле paths:. Правило с ним попадает в контекст только тогда, когда агент читает или правит файл, подходящий под шаблон.

---description: Как мы пишем React-компонентыpaths:  - 'src/**/*.tsx'  - 'src/**/*.jsx'---Только функциональные компоненты. Тест лежит рядом с компонентом.Не выносить в глобальный стор состояние, которое нужно одному экрану.

Пока агент правит Makefile, инструкции про React его контекст не занимают. Как только он открывает .tsx, правило подгружается и действует до конца сессии.

Правило без paths: работает так же, как QWEN.md: загружается всегда.

Где лежат правила:

  • ~/.qwen/rules/ — ваши личные, загружаются всегда;

  • .qwen/rules/ в проекте — загружаются, только если вы доверяете этой папке (trusted folder).

Простой ориентир: в QWEN.md — то, что верно всегда, в правила с paths: — то, что касается отдельной части кода.

3. Режимы подтверждений и разрешения

Пять режимов

Режим

Правка файлов

Команды в терминале

Когда подходит

Plan

Нет, только чтение

Нет

Разобраться в коде, спланировать изменения

Ask Permissions (default)

С подтверждением

С подтверждением

Незнакомый код, критичные системы

Auto-Edit

Сам

С подтверждением

Повседневная разработка

Auto

Решает классификатор

Решает классификатор

Длинные автономные задачи

YOLO

Сам

Сам

Только в изолированном окружении

Переключаются они клавишами Shift+Tab (в Windows — Tab) или командой /approval-mode. Для Plan есть отдельный короткий путь: /plan включает его, /plan exit возвращает предыдущий режим. Чтобы закрепить режим, добавьте флаг: /approval-mode plan --project для проекта или --user для всех проектов.

Важная деталь: в свежих версиях режим по умолчанию — Auto. Это значит, что каждую команду в терминале, обращение к сети или вызов MCP-инструмента оценивает отдельная модель-классификатор. Это удобно, но:

  • классификатор — это дополнительные запросы к API, то есть дополнительные расходы;

  • он использует «быструю» модель, а если она не задана, то основную, и тогда каждая проверка стоит как полноценный запрос.

Поэтому, если вы работаете в Auto, задайте дешёвую быструю модель командой /model --fast или в настройках ("fastModel"). Если хочется предсказуемости, переключитесь в Auto-Edit: файлы правятся без вопросов, а команды требуют вашего «да».

Точечные разрешения

Режимы можно дополнить конкретными правилами в settings.json:

{  "permissions": {    "allow": ["Bash(git status)", "Bash(git diff *)", "Bash(pnpm test *)"],    "ask": ["Bash(git push *)"],    "deny": ["Bash(rm -rf *)", "Read(.env)"]  }}
  • allow — выполняется без вопросов;

  • ask — всегда спрашивать, даже в разрешительных режимах;

  • deny — запрещено полностью.

То же самое можно настроить интерактивно командой /permissions.

.qwenignore

Файл .qwenignore в корне проекта работает как .gitignore: перечисленные в нём файлы и папки исключаются из работы инструментов, которые его учитывают. Также поддерживаются .agentignore и .aiignore.

# Сгенерированное и тяжёлое/dist//coverage/*.min.js# Секреты.env.env.*

Это экономит контекст: агенту не нужно читать сборки и минифицированные файлы. Но это не защита секретов: учитывают его не все инструменты. Для .env добавьте ещё и правило deny, а лучше — песочницу (о ней ниже).

4. MCP: подключаем внешние инструменты

MCP (Model Context Protocol) — открытый стандарт, через который агент получает доступ к внешним инструментам: базам данных, трекерам задач, внутренним API, документации.

Добавить сервер проще всего командой:

# Удалённый сервер по HTTPqwen mcp add --transport http my-docs https://mcp.example.com/mcp \  --header "Authorization: Bearer your-token"# Локальный процессqwen mcp add my-tools --timeout 15000 python -m my_mcp_server

По умолчанию сервер записывается в пользовательские настройки. Флаг --scope project сохранит его в .qwen/settings.json проекта. Удалить сервер можно командой qwen mcp remove имя.

То же самое в settings.json:

{  "mcpServers": {    "my-docs": {      "httpUrl": "https://mcp.example.com/mcp",      "headers": { "Authorization": "Bearer your-token" },      "timeout": 5000    },    "my-tools": {      "command": "python",      "args": ["-m", "my_mcp_server"],      "includeTools": ["search", "get_page"]    }  }}

После добавления перезапустите Qwen Code и проверьте подключение командой /mcp.

Какой транспорт выбрать:

  • http — для удалённых сервисов, это рекомендуемый вариант;

  • stdio — для локальных программ и Docker-контейнеров;

  • sse — устаревший, только если сервер не умеет http.

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

5. Субагенты: узкие помощники

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

  • Контекст основной сессии не засоряется. Субагент может прочитать сто файлов, а основной агент получит только итог.

  • Права можно урезать. Ревьюер, который не может ничего править, физически не сломает код.

Создать субагента можно мастером /agents create, а посмотреть существующих — командой /agents manage. Но удобнее положить файл руками:

  • .qwen/agents/ — агенты проекта (имеют приоритет);

  • ~/.qwen/agents/ — ваши личные агенты для всех проектов.

Пример ревьюера, который только читает и работает на дешёвой модели:

---name: reviewerdescription: Проверяет изменения перед коммитом. Использовать после любой правки кода.model: fasttools:  - read_file  - grep_search  - glob  - run_shell_command---Ты ревьюер кода. Посмотри изменения через `git diff` и найди:ошибки логики, необработанные ошибки, проблемы безопасности,нарушения договорённостей из QWEN.md.Ничего не исправляй. Верни список замечаний по убыванию важности,у каждого — файл, строка и почему это проблема.

У ревьюера нет write_file и edit, поэтому править файлы он не может. Терминал ему нужен для git diff, а эта команда уже есть в permissions.allow из раздела 3, так что лишних вопросов не будет. Режим plan здесь не подходит: в нём агент вообще не выполняет команды.

И тестировщик, который может писать файлы:

---name: test-writerdescription: Пишет и запускает юнит-тесты для указанного модуля.approvalMode: auto-edittools:  - read_file  - write_file  - edit  - grep_search  - glob  - run_shell_command---Ты пишешь тесты. Сначала изучи модуль и существующие тесты рядом,повтори их стиль. Покрой основной сценарий, граничные случаи и ошибки.После написания запусти тесты и исправь то, что не проходит.Код самого модуля не меняй: если нашёл баг, опиши его в ответе.

Что важно знать о полях:

  • model: inherit (по умолчанию) — та же модель, что в основной сессии; fast — быстрая модель из настроек; можно указать конкретный идентификатор модели. Так дорогую модель можно оставить основной, а рутину отдать дешёвой.

  • tools — белый список. Если его нет, субагент получает все инструменты, включая MCP.

  • disallowedTools — чёрный список, например mcp__slack, чтобы закрыть целый MCP-сервер.

  • approvalMode — разрешительный режим основной сессии важнее. Если вы работаете в YOLO, субагент с approvalMode: plan всё равно будет в YOLO. Поэтому надёжное ограничение — это список tools, а не режим.

Вызывать субагентов можно явно («пусть reviewer посмотрит изменения»), а можно положиться на основного агента: он сам решает, кому передать задачу, по полю description. Чтобы он делал это охотнее, пишите в описании, когда агента нужно использовать.

Кстати, если у вас установлены Claude Code или Codex, Qwen Code умеет передавать задачи и им как встроенным субагентам. Они работают на своих моделях и своих подписках.

6. Песочница: чтобы агент не вышел за пределы проекта

Режимы подтверждений решают, спросит ли агент. Песочница решает, что он сможет сделать, даже если не спросил. Если вы хоть иногда работаете в Auto или YOLO, песочница нужна.

Linux: песочница для инструментов

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

Установите bwrap (в Debian и Ubuntu — пакет bubblewrap) и добавьте в пользовательские настройки ~/.qwen/settings.json:

{  "tools": {    "executionSandbox": {      "backend": "auto",      "filesystem": "workspace-write",      "network": "closed"    }  }}
  • filesystem: workspace-write — писать можно только в папку проекта; read-only — нельзя писать вообще.

  • network: closed — команды агента не ходят в сеть; open — сеть общая с системой.

Настройку нельзя включить или ослабить из .qwen/settings.json проекта. Это сделано намеренно: чужой репозиторий не должен уметь отключить вам песочницу.

Проверьте, что всё работает:

qwen sandbox --verify

Ограничения, о которых стоит знать заранее:

  • Чтение не ограничено. Песочница не даёт писать за пределами проекта, но читать файлы системы команды всё ещё могут. Секреты в домашней папке она не прячет.

  • Многое отключается. В этом режиме не работают MCP-серверы, хуки, расширения и режим ACP, то есть его нельзя использовать, когда Qwen Code запущен как агент внутри другого приложения.

Docker и Podman: изолировать всё целиком

Второй вариант работает на любой ОС: Qwen Code целиком запускается в контейнере, куда монтируются папка проекта и ~/.qwen.

# Разовый запускqwen -s -p "запусти тесты и разберись, почему падают"# Для всей сессии терминалаexport QWEN_SANDBOX=dockerqwen

Или постоянно — в settings.json: {"tools": {"sandbox": true}}. Образ по умолчанию скачается сам, свой можно указать через tools.sandboxImage.

macOS: Seatbelt

На macOS есть встроенный лёгкий вариант без Docker: QWEN_SANDBOX=sandbox-exec. Профиль задаётся переменной SEATBELT_PROFILE. По умолчанию это permissive-open (запись только в проект, сеть разрешена). Документация советует начать с него, а потом попробовать restrictive-closed, если всё работает.

Собираем вместе

Так выглядит проект после настройки:

my-project/├── QWEN.md                  # Команды, договорённости, запреты├── .qwenignore              # Сборки, минифицированное, секреты└── .qwen/    ├── settings.json        # Режим, разрешения, MCP проекта    ├── QWEN.local.md        # Личные заметки (в .gitignore)    ├── rules/    │   └── react.md         # Правило с paths: для src/**/*.tsx    └── agents/        ├── reviewer.md      # Только чтение, быстрая модель        └── test-writer.md   # Пишет тесты

А в ~/.qwen/settings.json — ключи, быстрая модель и песочница.

Чек-лист на 15 минут:

  1. Запустите /init и сократите получившийся QWEN.md до самого важного.

  2. Вынесите инструкции для отдельных частей кода в .qwen/rules/ с paths:.

  3. Создайте .qwenignore для сборок и тяжёлых файлов.

  4. Задайте быструю модель через /model --fast, если работаете в Auto.

  5. Добавьте в permissions безопасные команды в allow и опасные в deny.

  6. Подключите один-два MCP-сервера, которыми действительно пользуетесь.

  7. Заведите субагента-ревьюера с правами только на чтение.

  8. Включите песочницу.

Большая часть этих настроек делается один раз, а экономит время и деньги на каждой сессии.

А как настроено у вас? Какой режим подтверждений стоит по умолчанию, держите ли отдельных субагентов и включаете ли песочницу? И если пробовали Qwen Code рядом с Claude Code или Codex, где он заметно уступает, а где справляется не хуже? Делитесь в комментариях, интересно сравнить.

ссылка на оригинал статьи https://habr.com/ru/articles/1109386/