После установки 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-сервера, которыми действительно пользуетесь.
-
Заведите субагента-ревьюера с правами только на чтение.
-
Включите песочницу.
Большая часть этих настроек делается один раз, а экономит время и деньги на каждой сессии.
Автор: zorkot


