Como usar o Qwen Code: guia passo a passo

Para usar o Qwen Code, instale a CLI qwen com o script oficial, npm ou Homebrew, rode qwen na pasta de um projeto, escolha um provedor de modelos com /auth e descreva o que você quer. O Qwen Code lê seu código, edita arquivos e executa comandos, pedindo permissão de acordo com o modo de aprovação escolhido. Como o plano gratuito do Qwen OAuth acabou em 15 de abril de 2026, você precisa de uma API key ou de um plano de algum provedor, ou de um modelo local.

Esse é o ciclo básico. Este guia cobre o resto: as opções de login e o que substituiu o plano gratuito, chaves compatíveis com OpenAI e modelos locais, a escolha do modelo, os modos de aprovação, o QWEN.md, os servidores MCP, o modo headless para scripts e como usar o Qwen Code ao lado de outros agentes. Tudo segue o repositório e a documentação oficiais do Qwen Code em outubro de 2026.

O que é o Qwen Code

O Qwen Code é um agente de programação para o terminal criado pela equipe Qwen da Alibaba e publicado sob a licença Apache-2.0. Ele nasceu de um fork do Gemini CLI, então a estrutura vai parecer familiar se você já usou o agente do Google, embora há tempos siga seu próprio caminho. É ajustado para os modelos de código do Qwen, mas não depende deles: fala os formatos de API da OpenAI, da Anthropic e do Gemini e funciona com modelos locais.

Além do terminal, o projeto oferece um app desktop, integrações para VS Code, Zed e JetBrains e SDKs para TypeScript, Python e Java. Este guia foca na CLI.

Passo 1: instale o Qwen Code

Depois de instalar pelo script, reinicie o terminal para que o comando qwen esteja no seu PATH. O pacote npm exige Node.js 22 ou mais recente. Para atualizar, rode de novo o mesmo comando do npm ou do Homebrew.

Passo 2: entre com /auth

Entre em um projeto e abra o Qwen Code:

cd my-project
qwen

Na primeira execução, e quando quiser depois com /auth, o Qwen Code mostra quatro formas de conectar um modelo:

Rode /doctor dentro de uma sessão para ver qual autenticação está ativa. O antigo comando de shell qwen auth foi removido; para trocar de provedor, use /auth.

O que aconteceu com o plano gratuito do Qwen OAuth

Durante muito tempo, o caminho mais fácil era entrar com uma conta qwen.ai via Qwen OAuth e receber uma cota diária gratuita. A documentação agora diz que o plano gratuito do Qwen OAuth foi encerrado em 15 de abril de 2026. Ele não aparece mais no /auth, e novas requisições por esse caminho são recusadas mesmo que ainda exista um token antigo em cache. Se você seguiu um tutorial antigo e o agente parou de responder de repente, o motivo é esse. Escolha uma das opções acima. Nossa seleção das melhores ferramentas de IA gratuitas para programar mostra o que continua de graça em 2026.

Use qualquer API key compatível com OpenAI

A configuração mais rápida para scripts e servidores são três variáveis de ambiente:

export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_MODEL="your-model-id"
qwen

Essas são as variáveis do protocolo compatível com OpenAI, que cobre a maioria dos provedores. Os formatos da Anthropic e do Gemini têm as suas (ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, ANTHROPIC_MODEL e GEMINI_API_KEY, GEMINI_MODEL).

Em vez de exportar as chaves em cada shell, você pode colocá-las em um arquivo .env. O Qwen Code procura .qwen/.env e .env no projeto e nas pastas acima, depois ~/.qwen/.env e ~/.env, e carrega só o primeiro que encontrar. As flags da linha de comando têm prioridade sobre as variáveis do shell, estas sobre o .env, e o .env sobre o bloco env do settings.json.

Para uma configuração permanente, declare o provedor em ~/.qwen/settings.json. O envKey indica a variável que guarda a chave:

{
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3-coder-plus",
        "name": "qwen3-coder-plus",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "description": "Qwen3-Coder via Dashscope",
        "envKey": "DASHSCOPE_API_KEY"
      }
    ]
  },
  "security": { "auth": { "selectedType": "openai" } },
  "model": { "name": "qwen3-coder-plus" }
}

O arquivo também aceita um bloco env com a própria chave, mas assim ela fica salva em texto puro. A documentação recomenda .qwen/.env para os segredos do projeto, fora do Git.

Modelos locais com Ollama

Ollama, vLLM e LM Studio expõem uma API compatível com OpenAI, então um modelo local é só mais um provedor openai com uma baseUrl local. O Ollama não precisa de uma chave real; qualquer valor serve:

{
  "env": { "OLLAMA_API_KEY": "ollama" },
  "modelProviders": {
    "openai": [
      {
        "id": "qwen2.5-7b",
        "name": "Qwen2.5 7B (Ollama)",
        "envKey": "OLLAMA_API_KEY",
        "baseUrl": "http://localhost:11434/v1",
        "generationConfig": { "contextWindowSize": 32768 }
      }
    ]
  }
}

O id precisa ser igual ao nome do modelo no Ollama. Um modelo local pequeno sofre em sessões longas de agente; nosso guia sobre um agente de código com LLM local explica quais modelos e quanta memória tornam isso viável.

Passo 3: escolha um modelo

Dentro de uma sessão, /model abre um seletor com os modelos dos seus provedores e /model <model-id> troca direto. No shell, qwen --model qwen3-coder-plus (ou -m) fixa o modelo para uma execução. Em modelos com raciocínio, /effort ajusta o nível de raciocínio quando o provedor permite.

Os modelos disponíveis dependem do provedor. Em outubro de 2026, o Coding Plan da Alibaba inclui modelos Qwen como qwen3-coder-plus, qwen3-coder-next e qwen3.7-plus, além de modelos de terceiros como GLM, Kimi e MiniMax. Uma chave paga por uso dá acesso ao que a API daquele provedor oferece.

Passo 4: o básico de uma sessão

A tela do Qwen Code é um chat com o seu projeto. Algumas coisas que você vai usar o tempo todo:

• @caminho anexa um arquivo à mensagem, e @pasta/ lê os arquivos de texto de uma pasta.
• !comando executa um comando de shell, por exemplo !git status. Um ! sozinho alterna para o modo shell até você digitar ! de novo.
• Shift+Tab (Tab no Windows) percorre os modos de aprovação.

No shell, qwen --continue reabre a última sessão do projeto atual e qwen --resume <id> abre uma específica.

Passo 5: modos de aprovação

O Qwen Code tem cinco modos de aprovação que decidem o que ele pode fazer sem perguntar:

Por padrão, o Qwen Code começa no Auto: um classificador baseado em modelo aprova as ações seguras e bloqueia as arriscadas. Use /approval-mode plan ou Shift+Tab para trocar, ou comece com qwen --approval-mode plan. Um bom hábito para qualquer coisa não trivial: comece no Plan, combinem a abordagem e depois passe para Auto-Edit ou Auto para executar. Deixe o YOLO para contêineres ou máquinas descartáveis, onde um comando errado não cause estrago duradouro.

Passo 6: QWEN.md e o contexto do projeto

O QWEN.md é o briefing que o Qwen Code carrega no início de cada sessão: comandos de build e de teste, convenções, pastas que ele não deve tocar. Ele pode ficar em três lugares, e todos são carregados:

Rode /init e o Qwen Code analisa o projeto e escreve um QWEN.md inicial; se ele já existir, sugere acréscimos em vez de sobrescrever. Se o repositório já tem um AGENTS.md para outras ferramentas, o Qwen Code também o lê. Dentro do QWEN.md, @docs/git-workflow.md importa outro arquivo.

# Regras do projeto

- Gerenciador de pacotes: pnpm. Rode `pnpm test` antes de terminar uma tarefa.
- TypeScript em modo strict; nada de `any` em código novo.
- Nunca edite arquivos em src/generated/.
- Fluxo de Git: @docs/git-workflow.md

Mantenha o arquivo curto; a documentação avisa que um arquivo longo é seguido com menos confiabilidade. O Qwen Code também mantém uma memória automática própria em ~/.qwen/projects/<projeto>/memory/, arquivos Markdown que você pode editar ou desativar no /memory. Para regras que só valem para certos arquivos, .qwen/rules/ aceita arquivos Markdown com um campo paths:. O que colocar em um arquivo desses está em CLAUDE.md e AGENTS.md, e vale igualmente para o QWEN.md.

Passo 7: servidores MCP

Servidores MCP dão ao Qwen Code ferramentas novas, como um navegador, um gerenciador de issues ou busca na documentação. O jeito mais rápido de adicionar um é o comando qwen mcp:

# um servidor remoto via HTTP
qwen mcp add --transport http my-server http://localhost:3000/mcp

# um servidor local iniciado como processo (stdio é o transporte padrão)
qwen mcp add pythonTools -e DATABASE_URL=$DB_CONNECTION_STRING python -m my_mcp_server

# remover de novo
qwen mcp remove my-server

Os servidores ficam salvos no bloco mcpServers de ~/.qwen/settings.json (o escopo de usuário, padrão) ou, com --scope project, em .qwen/settings.json. Você também pode editar esse bloco à mão: command e args para um processo local, httpUrl para um servidor HTTP. --include-tools e --exclude-tools limitam quais ferramentas um servidor expõe. Se o Qwen Code já estava aberto, reinicie e digite /mcp para confirmar que o servidor conectou e ver as ferramentas dele.

Passo 8: modo headless para scripts e CI

-p (ou --prompt) executa uma única tarefa sem a interface interativa, e stdin também funciona:

qwen -p "Summarize what changed in src/ since the last tag"
cat error.log | qwen -p "Explain this stack trace"
qwen -p "List the TODOs in this repo" --output-format json > todos.json

--output-format aceita text, json ou stream-json. qwen --continue -p "..." continua a última sessão, então um script pode trabalhar em várias etapas. Para que uma execução headless possa editar arquivos, defina um modo de aprovação como --approval-mode auto-edit, ou --yolo em um runner isolado. A documentação é clara: --yolo não ativa nenhum sandbox, e os comandos de shell rodam com as permissões do seu usuário. Limites evitam que uma execução sem supervisão saia do controle:

qwen -p "Fix the failing unit tests" --yolo \
  --max-session-turns 30 --max-wall-time 10m --output-format json

Uma execução que passa de --max-wall-time ou --max-tool-calls termina com o código 55, e uma que passa de --max-session-turns, com o 53, então a CI consegue distinguir os casos. Para um isolamento de verdade, qwen -s roda as ferramentas em um sandbox (Seatbelt no macOS, Docker ou Podman nos outros sistemas).

Armadilhas comuns

• O agente parou de funcionar depois de abril de 2026. Você usava o plano gratuito do Qwen OAuth, que não existe mais. Rode /auth e escolha outro provedor.
• “qwen auth” mostra um aviso de que foi removido. O comando não existe mais; use /auth em uma sessão e /doctor para conferir.
• Uma chave em QWENCLOUD_API_KEY ou DASHSCOPE_API_KEY é ignorada. Variáveis específicas de um provedor só funcionam quando um provedor do settings.json as indica como envKey. Caso contrário, use OPENAI_API_KEY.
• Um servidor MCP novo não aparece. Ele foi adicionado com o Qwen Code aberto. Reinicie no mesmo projeto.
• Sessões longas ficam lentas e caras. Use /compress ou /clear, mantenha o QWEN.md curto e desative os servidores MCP que não estiver usando.

Rodar o Qwen Code ao lado de outras CLIs

O Qwen Code tem seus próprios subagentes e suporte a worktrees, mas eles ficam dentro do Qwen Code. Se você quer o Qwen Code em uma tarefa, o Claude Code em outra e o Gemini CLI em uma terceira, volta a fazer malabarismo com abas do terminal. O AgentVera é um app desktop que roda essas CLIs em paralelo em terminais reais, com suas próprias instalações e logins. O suporte ao Qwen Code funciona assim:

• Seu login. O Qwen Code mantém o próprio login, que o terminal do agente pede na primeira execução. Se o qwen não estiver instalado, o AgentVera instala com npm i -g @qwen-code/qwen-code.
• Uma sessão por agente. Cada agente começa com seu próprio identificador de sessão (--session-id), e uma sessão salva reabre com --resume.
• Papel e modelo. O papel do agente é adicionado ao prompt de sistema do Qwen Code com --append-system-prompt. Deixe o campo Model vazio para usar o modelo padrão do Qwen Code, ou escolha um e o AgentVera o passa com --model.
• MCP a cada início. Os servidores do gerenciador de MCP do AgentVera e o navegador do AgentVera são passados com --mcp-config, então o seu settings.json fica como está.
• Painéis, revisão e flows. Rode o Qwen Code ao lado do Claude Code na grade do Workspace, cada agente em seu próprio worktree do git, com revisão de código automática ao fim de cada turno. Agentes do Qwen Code também funcionam em transmissões, tarefas agendadas e Flows (Pro e Team), onde a resposta de um agente passa para o próximo.
• Várias contas. Em Settings → Accounts → Accounts of other agents, você pode adicionar contas extras do Qwen, que funcionam com API keys, e definir uma ordem de fallback (Pro e Team).

Para ser justo com as alternativas: se você só quer um modelo hospedado gratuito, o Qwen Code não oferece mais isso, e as ferramentas gratuitas da seleção citada acima são um ponto de partida melhor. Se procura um agente independente de provedor com outro fluxo de trabalho, o opencode é a alternativa mais próxima. A grade, os worktrees, a revisão de código e o gerenciador de MCP estão no plano gratuito. Baixe o AgentVera para experimentar.

Conclusão

Para usar o Qwen Code, instale, rode qwen em um projeto e escolha um provedor com /auth, já que o plano gratuito do Qwen OAuth acabou. Qualquer chave compatível com OpenAI funciona pelas variáveis OPENAI_* ou pelo settings.json, incluindo modelos locais. Comece trabalhos arriscados no modo Plan, coloque as regras do projeto no QWEN.md, adicione ferramentas com qwen mcp add e use qwen -p com limites quando um script ou job de CI precisar do agente. Daí em diante, a decisão principal é qual provedor e qual modelo cabem no seu orçamento, e o Qwen Code deixa você trocar os dois quando quiser.