Ao vivo 18/11 · Turma 318 nov às 19:00 MSK — aula prática gratuita de agentes de IA · Turma 3 ao vivo começa 23/11Aula 18/11 →Turma 3 (23/11)
LançamentoCódigo / SDK · Pronto p/ usoHabr AI→ original

Configuração do Qwen Code: QWEN.md, subagentes e sandbox cortam o gasto desnecessário de tokens

Depois de instalado, o Qwen Code reexamina o repositório a cada sessão e repete perguntas que poderiam ser respondidas uma única vez, e você paga por isso em tokens. Por exemplo, ele não sabe que o projeto instala pacotes com pnpm, e não com npm, e pergunta toda vez. Esses comandos e proibições vão para o arquivo QWEN.md, que o agente lê no início da sessão. O guia, feito para a versão 0.28.0, apresenta seis ajustes que reduzem perguntas e custos.

Processado por IA de Habr AI; editado por Hamidun News
Configuração do Qwen Code: QWEN.md, subagentes e sandbox cortam o gasto desnecessário de tokens
Fonte: Habr AI. Colagem: Hamidun News.
Ouvir artigo
Ficha técnica e números-chave
ParâmetroDados
Fonte originalHabr AI ↗
Editor-chefe
Dado-chave #1O QWEN.md vai em cada requisição, então cada linha a mais é paga várias vezes
Dado-chave #2O modo Auto verifica cada comando com um modelo: defina um mais barato com /model --fast
Dado-chave #3Um subagente revisor sem write_file e edit fisicamente não consegue alterar o código

Logo após a instalação, o Qwen Code funciona no modo «como está»: reexamina o repositório a cada sessão, repete as mesmas perguntas e gasta tokens com informações que poderiam ser passadas uma só vez. Imagine que, no seu projeto, os pacotes são instalados com pnpm, e não com npm, e que os testes rodam com um comando específico. O agente não sabe disso e, a cada sessão, ou pergunta ou tenta adivinhar.

Esses dados são registrados uma única vez no arquivo QWEN.md, ou seja, numa espécie de nota permanente do projeto que o agente lê no início de cada sessão. Este guia foi conferido com a documentação do Qwen Code versão 0.

28.0 (novembro de 2026) e cobre seis ajustes: QWEN.md, regras, modos de confirmação, servidores MCP (ferramentas externas), subagentes (assistentes especializados com permissões reduzidas) e sandbox (isolamento dos comandos do agente).

O objetivo é simples: fazer o agente perguntar menos, gastar menos e não conseguir causar danos por acidente. O projeto muda rápido, então, se estiver em outra versão, confira com qwen --help.

Memória e regras: diga uma vez só

As configurações ficam em dois lugares: ~/.qwen/settings.json vale para você em todos os projetos, e .qwen/settings.json, na raiz do repositório, vale apenas para aquele projeto e pode ser commitado para que toda a equipe o use. Não é preciso colocar chaves de API ali: para elas existem variáveis de ambiente ou configurações de usuário.

O QWEN.md é um arquivo Markdown comum. Pode haver três, e todos são carregados ao mesmo tempo: ~/.qwen/QWEN.md para você em todos os projetos, QWEN.md na raiz para toda a equipe e .qwen/QWEN.local.md só para você naquele projeto. O arquivo local é carregado depois do compartilhado, então serve para complementar ou sobrescrever as instruções da equipe. Será preciso adicioná-lo ao .gitignore manualmente. Se o repositório já tiver um AGENTS.md para outras ferramentas de IA, o Qwen Code também o lê.

O jeito mais rápido de começar é o comando /init: ele analisa o código e cria um rascunho com os comandos de build e as convenções encontradas. A regra principal é ser curto e específico. A documentação alerta: quanto mais longo o arquivo, pior o modelo o segue. A frase «use indentação de 2 espaços em TypeScript» funciona; «escreva código com capricho» não. Além disso, o QWEN.md vai em cada requisição de cada sessão, de modo que cada linha a mais são tokens que você paga várias vezes.

Além do arquivo, há a memória automática: o próprio Qwen Code salva anotações em ~/.qwen/projects/<projeto>/memory/. O comando /remember memoriza na hora, /forget apaga e /memory mostra os arquivos carregados. Mas a memória automática funciona «na medida do possível», então o que é obrigatório deve ir no QWEN.md.

Se o arquivo crescer demais, parte das instruções pode ir para as regras, que são arquivos Markdown em .qwen/rules/. A regra tem um campo paths: por exemplo, 'src/*/.tsx'. Assim, as instruções sobre React entram no contexto só quando o agente abre um arquivo correspondente. Enquanto ele edita o Makefile, elas não ocupam espaço. Uma regra sem paths funciona como o QWEN.md. As regras do projeto só são carregadas se você confiar na pasta (trusted folder).

Confirmações, MCP e subagentes

São cinco modos de confirmação: Plan (somente leitura), Ask Permissions (pergunta tanto sobre edições quanto sobre comandos), Auto-Edit (edita arquivos sozinho, comandos só com a sua aprovação), Auto (um classificador decide) e YOLO (faz tudo sozinho, apenas em ambiente isolado). A troca é feita com Shift+Tab (Tab no Windows) ou /approval-mode. Nas versões recentes, o padrão é Auto: cada comando, acesso à rede ou chamada de ferramenta MCP é avaliado por um modelo classificador separado. Isso gera requisições extras à API. Se nenhum modelo rápido estiver definido, é usado o principal, e cada verificação custa como uma requisição completa. Por isso, defina um modelo barato com /model --fast ou por meio de "fastModel" nas configurações, ou mude para Auto-Edit.

Permissões pontuais são definidas no bloco permissions: allow executa sem perguntar (por exemplo, git status e pnpm test), ask sempre pergunta (git push) e deny proíbe totalmente (rm -rf e leitura do .env). O arquivo .qwenignore, assim como .agentignore ou .aiignore, funciona como o .gitignore e economiza contexto, mas não protege segredos: nem todas as ferramentas o respeitam.

O MCP (Model Context Protocol) é um padrão aberto para conectar bancos de dados, gerenciadores de tarefas e documentação. O servidor é adicionado com o comando qwen mcp add; a flag --scope project o salva nas configurações do projeto. Para serviços remotos, o transporte recomendado é http; para programas locais e Docker, stdio; sse está obsoleto. As descrições das ferramentas também ocupam contexto, então conecte só o necessário e limite o conjunto com includeTools ou excludeTools.

O subagente é um assistente separado, com instruções, ferramentas e contexto próprios. Ele pode ler cem arquivos, e o agente principal recebe só o resultado. Os arquivos ficam em .qwen/agents/ (os do projeto têm prioridade) ou em ~/.qwen/agents/. Um revisor com model: fast e as ferramentas read_file, grep_search, glob e run_shell_command não consegue alterar o código, porque não tem write_file nem edit. A restrição confiável é a lista tools, e não o approvalMode: se a sessão principal estiver em YOLO, um subagente com plan ainda assim acabará em YOLO.

Sandbox: o que o agente pode fazer mesmo sem perguntar

Os modos decidem se o agente pergunta; a sandbox define o que ele consegue fazer mesmo sem perguntar. Se você trabalha, ainda que de vez em quando, em Auto ou YOLO, ela é necessária. Nas versões mais recentes para Linux, surgiu um modo em que o Qwen Code roda normalmente, enquanto os comandos e as operações de arquivo do agente são executados de forma isolada via bwrap (Bubblewrap).

Comece com /init, reduza o QWEN.md, mova instruções específicas para as regras, defina /model --fast, distribua os comandos entre allow e deny, crie um revisor somente leitura e ative a sandbox.

História

Perguntas frequentes sobre a notícia

O que se sabe sobre Memória e regras: diga uma vez só?

As configurações ficam em dois lugares: ~/.qwen/settings.json vale para você em todos os projetos, e .qwen/settings.json, na raiz do repositório, vale apenas para aquele projeto e pode ser commitado para que toda a equipe o use. Não é preciso colocar chaves de API ali: para elas existem variáveis de ambiente ou configurações de usuário. O QWEN.md é um arquivo Markdown comum.

O que se sabe sobre Confirmações, MCP e subagentes?

São cinco modos de confirmação: Plan (somente leitura), Ask Permissions (pergunta tanto sobre edições quanto sobre comandos), Auto-Edit (edita arquivos sozinho, comandos só com a sua aprovação), Auto (um classificador decide) e YOLO (faz tudo sozinho, apenas em ambiente isolado). A troca é feita com Shift+Tab (Tab no Windows) ou /approval-mode. Nas versões recentes, o padrão é Auto: cada comando, acesso à rede ou chamada de ferramenta MCP é avaliado por um modelo classificador separado.

O que se sabe sobre Sandbox: o que o agente pode fazer mesmo sem perguntar?

Os modos decidem se o agente pergunta; a sandbox define o que ele consegue fazer mesmo sem perguntar. Se você trabalha, ainda que de vez em quando, em Auto ou YOLO, ela é necessária. Nas versões mais recentes para Linux, surgiu um modo em que o Qwen Code roda normalmente, enquanto os comandos e as operações de arquivo do agente são executados de forma isolada via bwrap (Bubblewrap).

ZK
Zhemal Khamidun — CPO da Alpina Digital, gerente de produto do AlpinaGPT. Cria produtos de IA desde 2019. O Hamidun News é um projeto pessoal que virou um agregador em produção com mais de 6.000 leitores.
✦ 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
O que você acha?
Carregando comentários…