Live Nov 18 · Cohort 3Nov 18, 19:00 MSK — free hands-on AI agents live workshop · Live Cohort 3 starts Nov 23Join Nov 18 Live →Cohort 3 (Nov 23)
ReleaseCode / SDK · ActionableHabr AI→ original

Configuring Qwen Code: QWEN.md, Subagents, and a Sandbox Cut Wasted Tokens

After installation, Qwen Code re-explores your repository every session and re-asks things you could say once, and you pay for it in tokens. For example, it doesn't know that the project installs packages with pnpm, not npm, so it asks every time. You record such commands and prohibitions in a QWEN.md file, which the agent reads at the start of each session. This guide for version 0.28.0 covers six settings that mean fewer questions and lower costs.

AI-processed from Habr AI; edited by Hamidun News
Configuring Qwen Code: QWEN.md, Subagents, and a Sandbox Cut Wasted Tokens
Source: Habr AI. Collage: Hamidun News.
Listen to article
Article Fact Sheet & Key Figures
ParameterDetails
Primary sourceHabr AI ↗
Editor-in-Chief
Key metric #1QWEN.md goes into every request, so each extra line is paid for many times over
Key metric #2Auto mode checks every command with a model: set a cheap one via /model --fast
Key metric #3A reviewer subagent without write_file and edit physically cannot modify code

Qwen Code works "as is" after installation: it re-explores the repository every session, re-asks the same questions, and spends tokens on things you could have said once. Imagine your project installs packages with pnpm, not npm, and runs tests with a special command. The agent doesn't know this, so every session it either asks or guesses.

You write this information down once in a QWEN.md file, a permanent project memo that the agent reads at the start of every session. This guide was checked against the Qwen Code documentation for version 0.

28.0 (November 2026) and covers six settings: QWEN.md, rules, approval modes, MCP servers (external tools), subagents (narrow helpers with reduced permissions), and the sandbox (isolation for the agent's commands).

The goal is simple: the agent should ask less, spend less, and be unable to cause accidental harm. The project changes quickly, so if you run a different version, check qwen --help.

Memory and rules: say it once

Settings live in two places: ~/.qwen/settings.json applies to you across all projects, while .qwen/settings.json in the repository root applies only to that project, and you can commit it so the whole team has it. Don't put API keys there: use environment variables or user-level settings for those.

QWEN.md is a plain Markdown file. There can be three of them, and all are loaded at once: ~/.qwen/QWEN.md for you across all projects, QWEN.md in the root for the whole team, and .qwen/QWEN.local.md for you only, in this project. The local file loads after the shared one, so you can use it to extend or override team instructions. You will have to add it to .gitignore manually. If the repository already has an AGENTS.md for other AI tools, Qwen Code reads that too.

The fastest way to start is the /init command: it studies the code and creates a draft with build commands and the conventions it finds. The main rule is to be short and specific. The documentation warns that the longer the file, the worse the model follows it. The phrase "use 2-space indentation in TypeScript" works; "write clean code" does not. On top of that, QWEN.md goes into every request of every session, so each extra line is tokens you pay for many times over.

Besides the file, there is auto-memory: Qwen Code saves notes on its own to ~/.qwen/projects/<project>/memory/. The /remember command saves something immediately, /forget deletes it, and /memory shows the loaded files. But auto-memory works on a best-effort basis, so put anything mandatory in QWEN.md.

If the file keeps growing, move some instructions into rules: Markdown files in .qwen/rules/. A rule has a paths: field, for example 'src/*/.tsx'. The React instructions then enter the context only when the agent opens a matching file. While it edits a Makefile, they take up no space. A rule without paths works like QWEN.md. Project rules load only if you trust the folder (trusted folder).

Approvals, MCP, and subagents

There are five approval modes: Plan (read-only), Ask Permissions (asks about both edits and commands), Auto-Edit (edits files on its own, runs commands with your consent), Auto (a classifier decides), and YOLO (does everything itself, only in an isolated environment). You switch with Shift+Tab (Tab on Windows) or /approval-mode. Recent versions default to Auto: a separate classifier model evaluates every command, network access, or MCP tool call. These are additional API requests. If no fast model is set, the main model is used, and each check costs as much as a full request. So set a cheap one with /model --fast or via "fastModel" in the settings, or switch to Auto-Edit.

Granular permissions are set in the permissions block: allow runs without asking (for example, git status and pnpm test), ask always asks (git push), and deny forbids outright (rm -rf and reading .env). The .qwenignore file, like .agentignore or .aiignore, works like .gitignore and saves context, but it does not protect secrets: not all tools honor it.

MCP (Model Context Protocol) is an open standard for connecting databases, trackers, and documentation. You add a server with qwen mcp add; the --scope project flag saves it in the project settings. The recommended transport is http for remote services and stdio for local programs and Docker; sse is deprecated. Tool descriptions also take up context, so connect only what you need and limit the set via includeTools or excludeTools.

A subagent is a separate helper with its own instructions, tools, and context. It can read a hundred files, and the main agent receives only the result. The files live in .qwen/agents/ (project ones take priority) or ~/.qwen/agents/. A reviewer with model: fast and the tools read_file, grep_search, glob, and run_shell_command cannot modify code, because it has no write_file or edit. The reliable restriction is the tools list, not approvalMode: if the main session runs in YOLO, a subagent set to plan will still end up in YOLO.

The sandbox: what the agent can do even without asking

Modes decide whether the agent asks; the sandbox decides what it can do even if it didn't ask. If you ever work in Auto or YOLO, even occasionally, you need it. Recent Linux versions added a mode in which Qwen Code itself runs as usual, while the agent's commands and file operations execute in isolation via bwrap (Bubblewrap).

Start with /init, shorten QWEN.md, move narrow instructions into rules, set /model --fast, split commands between allow and deny, create a read-only reviewer, and enable the sandbox.

Story

Key Questions Answered

What are the key details on Memory and rules: say it once?

Settings live in two places: ~/.qwen/settings.json applies to you across all projects, while .qwen/settings.json in the repository root applies only to that project, and you can commit it so the whole team has it. Don't put API keys there: use environment variables or user-level settings for those. QWEN.md is a plain Markdown file.

What are the key details on Approvals, MCP, and subagents?

There are five approval modes: Plan (read-only), Ask Permissions (asks about both edits and commands), Auto-Edit (edits files on its own, runs commands with your consent), Auto (a classifier decides), and YOLO (does everything itself, only in an isolated environment). You switch with Shift+Tab (Tab on Windows) or /approval-mode. Recent versions default to Auto: a separate classifier model evaluates every command, network access, or MCP tool call. These are additional API requests.

What are the key details on The sandbox: what the agent can do even without asking?

Modes decide whether the agent asks; the sandbox decides what it can do even if it didn't ask. If you ever work in Auto or YOLO, even occasionally, you need it. Recent Linux versions added a mode in which Qwen Code itself runs as usual, while the agent's commands and file operations execute in isolation via bwrap (Bubblewrap). Start with /init, shorten QWEN.md, move narrow instructions into rules, set /model --fast, split commands between allow and deny, create a read-only reviewer, and enable the sandbox.

ZK
Zhemal Khamidun — CPO at Alpina Digital, product manager of AlpinaGPT. Building AI products since 2019. Hamidun News is a pet project that grew into a production aggregator with 6,000+ readers.
✦ Unified AI Workspace · Nomad

Test Frontier LLMs & Autonomous Agents in One Workspace

Run Claude Opus 5.5, GPT-6, Gemini 3.1, and DeepSeek side-by-side in Nomad AI (nomadnet.ai) — unified model routing, deep research, and multimodal workflows under one subscription.

Try Nomad AI →Launch Nomad Agent
What do you think?
Loading comments…