После установки Qwen Code работает «как есть»: каждый раз заново изучает репозиторий, спрашивает одно и то же и тратит токены на то, что можно было сказать один раз. В прошлой статье разбирали, как подключить Qwen Code к своему ключу и OpenAI-совместимому провайдеру. Теперь — следующий шаг: настроить его под конкретный проект так, чтобы он меньше спрашивал, меньше тратил и не мог случайно навредить.
Что будем настраивать:
QWEN.md — постоянные инструкции для проекта.
Правила — инструкции, которые подгружаются только когда нужны.
Режимы подтверждений и разрешения — что агент делает сам, а что только с вашего согласия.
MCP-серверы — внешние инструменты.
Субагенты — узкие помощники со своими инструкциями и ограниченными правами.
Песочница — чтобы команды агента не выходили за пределы проекта.
Всё проверено по документации Qwen Code версии 0.28.0 (ноябрь 2026). Проект развивается быстро, поэтому если у вас другая версия, сверяйтесь с qwen --help и документацией в репозитории.
Где лежат настройки
Почти всё настраивается в двух местах:
Файл |
Действует |
|---|---|
|
Для вас во всех проектах |
|
Только в этом проекте |
Настройки проекта можно коммитить, тогда они будут у всей команды. Ключи API туда класть не надо: для них есть переменные окружения или пользовательские настройки.
1. QWEN.md: один раз объяснить проект
QWEN.md — обычный Markdown-файл, который Qwen Code читает в начале каждой сессии. Сюда стоит писать то, что иначе приходится повторять каждый раз: как собрать и протестировать проект, какие договорённости приняты в команде, чего делать нельзя.
Файлов может быть три, и загружаются все сразу:
Файл |
Для кого |
|---|---|
|
Для вас, во всех проектах |
|
Для всей команды, коммитится в git |
|
Только для вас и только в этом проекте |
Локальный файл загружается после общего, поэтому им можно дополнять или переопределять командные инструкции. Добавить его в .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 ( |
С подтверждением |
С подтверждением |
Незнакомый код, критичные системы |
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, документации.
Добавить сервер проще всего командой:
# Удалённый сервер по HTTP qwen 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: reviewer description: Проверяет изменения перед коммитом. Использовать после любой правки кода. model: fast tools: - read_file - grep_search - glob - run_shell_command --- Ты ревьюер кода. Посмотри изменения через `git diff` и найди: ошибки логики, необработанные ошибки, проблемы безопасности, нарушения договорённостей из QWEN.md. Ничего не исправляй. Верни список замечаний по убыванию важности, у каждого — файл, строка и почему это проблема.
У ревьюера нет write_file и edit, поэтому править файлы он не может. Терминал ему нужен для git diff, а эта команда уже есть в permissions.allow из раздела 3, так что лишних вопросов не будет. Режим plan здесь не подходит: в нём агент вообще не выполняет команды.
И тестировщик, который может писать файлы:
--- name: test-writer description: Пишет и запускает юнит-тесты для указанного модуля. approvalMode: auto-edit tools: - 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=docker qwen
Или постоянно — в 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 минут:
Запустите
/initи сократите получившийся QWEN.md до самого важного.Вынесите инструкции для отдельных частей кода в
.qwen/rules/сpaths:.Создайте
.qwenignoreдля сборок и тяжёлых файлов.Задайте быструю модель через
/model --fast, если работаете в Auto.Добавьте в
permissionsбезопасные команды вallowи опасные вdeny.Подключите один-два MCP-сервера, которыми действительно пользуетесь.
Заведите субагента-ревьюера с правами только на чтение.
Включите песочницу.
Большая часть этих настроек делается один раз, а экономит время и деньги на каждой сессии.
А как настроено у вас? Какой режим подтверждений стоит по умолчанию, держите ли отдельных субагентов и включаете ли песочницу? И если пробовали Qwen Code рядом с Claude Code или Codex, где он заметно уступает, а где справляется не хуже? Делитесь в комментариях, интересно сравнить.