# Como usar o Qwen Code: guia passo a passo

URL: https://agentvera.dev/pt/blog/how-to-use-qwen-code/ · Publicado: 2026-10-29

Como usar o Qwen Code: instale a CLI qwen, entre com /auth ou uma API key, escolha um modelo e configure o QWEN.md, servidores MCP e o modo headless.

**Resumo:**

- Instale o Qwen Code com o script oficial, npm (Node.js 22+) ou Homebrew, rode qwen em um projeto e escolha um provedor com /auth. O plano gratuito do Qwen OAuth acabou em 15 de abril de 2026.
- Qualquer chave compatível com OpenAI funciona: defina OPENAI_API_KEY, OPENAI_BASE_URL e OPENAI_MODEL, ou declare provedores em ~/.qwen/settings.json. Modelos locais via Ollama funcionam do mesmo jeito.
- As regras do projeto ficam no QWEN.md (o AGENTS.md também é lido), servidores MCP entram com qwen mcp add e qwen -p roda uma única tarefa sem interface para scripts e CI.

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

| Plataforma | Comando |
| --- | --- |
| macOS, Linux | `curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh \| bash` |
| Windows (PowerShell) | `irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 \| iex` |
| Qualquer plataforma com Node.js 22+ | `npm install -g @qwen-code/qwen-code@latest` |
| macOS, Linux (Homebrew) | `brew install 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:

```bash
cd my-project
qwen
```

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

| Opção | O que é |
| --- | --- |
| QwenCloud | A API Qwen da Alibaba: uma assinatura Token Plan com cota mensal de créditos ou uma chave padrão paga por uso. Também ativa a ferramenta de busca na web integrada do Qwen Code. |
| Alibaba ModelStudio | Alibaba Cloud Model Studio: o Coding Plan para desenvolvedores individuais (cota mensal fixa com limite semanal), um Token Plan para equipes ou uma API key padrão |
| Third-party Providers | Entradas prontas para DeepSeek, Grok, MiniMax, Z.AI, Kimi, ModelScope, OpenRouter, Requesty e outros |
| Custom Provider | Qualquer endpoint compatível com OpenAI, Anthropic ou Gemini: um proxy, um gateway ou um servidor local |

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](/pt/blog/best-free-ai-coding-tools/ "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:

```bash
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:

```json
{
  "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:

```json
{
  "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](/pt/blog/local-llm-coding-agent/ "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.

| Comando | O que faz |
| --- | --- |
| `/auth` | Escolher ou trocar o provedor |
| `/model` | Trocar o modelo |
| `/init` | Criar um `QWEN.md` inicial para o projeto |
| `/memory` | Abrir o gerenciador de memória |
| `/mcp` | Listar os servidores MCP e suas ferramentas |
| `/approval-mode` | Mudar o modo de aprovação desta sessão |
| `/compress` | Trocar o histórico por um resumo para liberar contexto |
| `/clear` | Limpar a conversa |
| `/resume` | Reabrir uma sessão anterior |
| `/restore` | Voltar os arquivos ao checkpoint anterior a uma chamada de ferramenta |
| `/stats` | Uso de tokens e custo estimado |
| `/doctor` | Verificações de instalação e autenticação |
| `/quit` | Sair |

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:

| Modo | Edição de arquivos | Comandos de shell | Melhor para |
| --- | --- | --- | --- |
| Plan | Não, só leitura | Não | Explorar o código e planejar uma mudança |
| Ask Permissions (`default`) | Pergunta sempre | Pergunta sempre | Código desconhecido ou crítico |
| Auto-Edit (`auto-edit`) | Automática | Pergunta | Trabalho diário com muitas edições |
| Auto (`auto`) | Verificada por um classificador | Verificados por um classificador | Sessões longas com rede de segurança |
| YOLO (`yolo`) | Automática | Automáticos | Automação confiável em ambientes isolados |

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:

| Arquivo | Vale para |
| --- | --- |
| `~/.qwen/QWEN.md` | Você, em todos os projetos |
| `QWEN.md` na raiz do projeto | A equipe toda (versione no repositório) |
| `.qwen/QWEN.local.md` | Só você, só neste projeto (adicione você mesmo ao `.gitignore`) |

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.

```markdown
# 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](/pt/blog/claude-md-agents-md/ "CLAUDE.md e AGENTS.md"), e vale igualmente para o `QWEN.md`.

## Passo 7: servidores MCP

[Servidores MCP](/pt/blog/what-is-mcp-server/ "O que é um servidor 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`:

```bash
# 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:

```bash
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:

```bash
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](/pt/agents/qwen-code/ "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](/pt/features/workspace/ "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](/pt/features/flows/ "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](/pt/download/ "Baixar 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.

## Perguntas frequentes

**O Qwen Code é gratuito?** A CLI é gratuita e open source sob a licença Apache-2.0, mas o plano gratuito do Qwen OAuth foi encerrado em 15 de abril de 2026. Agora você paga pelo modelo: um plano do QwenCloud ou do Alibaba Cloud Model Studio, uma API key paga por uso ou um provedor externo. Um modelo local via Ollama não custa nada além do seu hardware.

**O Qwen Code pode usar modelos que não são do Qwen?** Sim. Ele fala os formatos de API da OpenAI, da Anthropic e do Gemini, oferece no /auth provedores externos como DeepSeek, Kimi, Z.AI, MiniMax e OpenRouter e aceita qualquer endpoint próprio compatível com OpenAI, incluindo servidores locais como Ollama, vLLM e LM Studio.

**O Qwen Code lê o AGENTS.md?** Sim. O Qwen Code carrega ~/.qwen/QWEN.md, o QWEN.md do projeto e .qwen/QWEN.local.md, e se o repositório já tem um AGENTS.md para outras ferramentas, ele também o lê. Você não precisa copiar as mesmas regras em dois arquivos.

**O que aconteceu com o comando qwen auth?** Ele foi removido. Abra o qwen e rode /auth dentro da sessão para escolher ou trocar de provedor, e /doctor para ver qual autenticação está ativa. Em scripts, defina as variáveis de ambiente do provedor ou declare o provedor em ~/.qwen/settings.json.

**Como rodo o Qwen Code em CI?** Use o modo headless: qwen -p "seu prompt" com --output-format json para ter uma saída legível por máquina. Adicione um modo de aprovação como --approval-mode auto-edit, ou --yolo só em um runner isolado, porque --yolo não ativa nenhum sandbox. Limites como --max-wall-time interrompem uma execução travada.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/