Настраиваем Qwen Code под проект: QWEN.md, правила, MCP, субагенты и песочница. llm.. llm. mcp.. llm. mcp. Open source.. llm. mcp. Open source. qwen.. llm. mcp. Open source. qwen. qwen code.. llm. mcp. Open source. qwen. qwen code. ии-агенты.. llm. mcp. Open source. qwen. qwen code. ии-агенты. искусственный интеллект.. llm. mcp. Open source. qwen. qwen code. ии-агенты. искусственный интеллект. песочница.. llm. mcp. Open source. qwen. qwen code. ии-агенты. искусственный интеллект. песочница. Программирование.. llm. mcp. Open source. qwen. qwen code. ии-агенты. искусственный интеллект. песочница. Программирование. субагенты.

После установки 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, документации.

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

# Удалённый сервер по 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 минут:

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

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

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

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

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

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

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

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

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

Автор: zorkot

Источник