Qwen Code: o agente de código no terminal com Ollama

#O que é o Qwen Code e por que executá-lo localmente

O Qwen Code é um fork do Gemini CLI, o agente de terminal de código aberto do Google, que a equipe Qwen adaptou aos modelos Qwen3-Coder. O projeto é publicado sob a licença Apache 2.0 no GitHub (QwenLM/qwen-code), é instalado via npm e usado com o comando qwen. Ele retoma a mecânica dos agentes de código modernos: um modelo recebe sua solicitação, dispõe de ferramentas (leitura e escrita de arquivos, pesquisa no repositório, execução de shell, consultas web, servidores MCP) e repete o ciclo dessas ferramentas até produzir um resultado verificável.

Por padrão, o Qwen Code direciona para uma conexão « Qwen OAuth »: você se autentica com uma conta Qwen e as requisições vão para os servidores da Alibaba Cloud. Há uma oferta gratuita nesse caminho, mas suas cotas podem mudar e dependem da região. Portanto, não informamos nenhum número aqui: a página de autenticação da documentação oficial é a única fonte atualizada. O que não muda é o outro modo, chamado « OpenAI-compatible »: o Qwen Code aceita qualquer servidor que exponha a API OpenAI, incluindo Ollama e LM Studio na sua máquina.

Privacidade

No modo local, o código-fonte, os comandos executados e suas saídas nunca saem do computador. Esse é o argumento decisivo para código de clientes ou protegido por acordo de confidencialidade.

Custo

Nenhuma cota, nenhuma cobrança por token. O único custo é a eletricidade e o hardware já comprado.

Disponibilidade

Sem interrupção do serviço, sem fila nos horários de pico. O agente responde enquanto a GPU estiver funcionando.

Desvantagem

Um modelo de 7 a 30 bilhões de parâmetros em quantização Q4 não está no mesmo nível de um modelo na nuvem com várias centenas de bilhões. É preciso dividir as tarefas em partes menores e revisar mais.

#Pré-requisitos

Node.js 20 ou mais recente

O Qwen Code é um pacote npm. Verifique com node --version. No Linux e no macOS, nvm ou fnm evitam problemas de permissão durante a instalação global.

Ollama instalado e funcionando

O daemon escuta em http://localhost:11434. Um ollama list deve responder sem erro. Caso contrário, comece pelo guia de instalação do Ollama.

Um modelo que lida com chamadas de ferramentas

Isso é inegociável: um agente de código encadeia chamadas estruturadas de ferramentas. Os modelos das famílias Qwen3-Coder e Qwen2.5-Coder, assim como o Devstral, oferecem suporte a elas no Ollama. Um modelo sem suporte a tools produzirá texto em vez de ações, e o agente ficará bloqueado.

Memória da GPU

Referências em Q4_K_M: um 7B ocupa cerca de 5 GB de VRAM, um 14B cerca de 9 GB e um 32B cerca de 19 GB, sem contar o contexto. O contexto longo exigido por um agente acrescenta vários gigabytes: reserve uma margem.

Um repositório Git

Não é obrigatório, mas é altamente recomendado. O agente modifica arquivos; git diff e git checkout são sua rede de segurança.

#1. Instale o Qwen Code

A instalação recomendada pelo repositório é feita globalmente via npm. No macOS, também é publicado um pacote Homebrew. O binário se chama qwen.

npm install -g @qwen-code/qwen-code@latest
qwen --version

brew install qwen-code
qwen --version

Na primeira inicialização do qwen sem configuração, a ferramenta oferece a opção de escolher um método de autenticação. Não escolha o Qwen OAuth se o seu objetivo for usar localmente: selecione a opção OpenAI ou, melhor ainda, saia e prepare primeiro a configuração descrita na próxima etapa. Você sempre poderá mudar de método mais tarde com o comando /auth em uma sessão.

#2. Conecte o Qwen Code ao Ollama

O Ollama expõe uma API compatível com OpenAI no caminho /v1 da porta 11434. O Qwen Code lê três variáveis de ambiente para esse modo: a URL base, uma chave de API e o nome do modelo. O Ollama não exige uma chave, mas o Qwen Code rejeita um valor vazio, então usamos qualquer string.

1. 01
   Baixe um modelo de código compatível com tools

   Exemplo com Qwen3-Coder 30B-A3B, um modelo de mistura de especialistas (MoE) com 30 bilhões de parâmetros, dos quais 3 bilhões ficam ativos a cada token, o que o torna rápido para seu tamanho. Ele pesa cerca de 19 GB em Q4: são necessários 24 GB de VRAM, ou uma máquina Apple Silicon com pelo menos 32 GB unificados, para mantê-lo inteiramente na GPU. Em uma placa de 12 GB, prefira qwen2.5-coder:7b ou um modelo de 14B.
2. 02
   Verifique se a API OpenAI de Ollama responde

   Uma requisição para /v1/models deve listar seus modelos. Se falhar, o Ollama não está iniciado ou está escutando em outro endereço.
3. 03
   Crie o arquivo .env na raiz do projeto

   Qwen Code carrega automaticamente um arquivo .env presente na pasta atual, em uma subpasta .qwen do projeto ou em ~/.qwen para uma configuração global. O arquivo mais próximo da pasta de trabalho prevalece.
4. 04
   Inicie o qwen no projeto

   A parte inferior da janela exibe o modelo ativo. Se você vir o nome do seu modelo Ollama, a conexão foi estabelecida. Digite uma primeira solicitação simples, por exemplo, resumir a estrutura do repositório, para verificar se as ferramentas de leitura estão funcionando.

ollama pull qwen3-coder:30b
curl http://localhost:11434/v1/models

OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3-coder:30b

cd mon-projet
qwen

Os mesmos parâmetros podem ser passados como opções de linha de comando para uma sessão pontual, sem mexer no arquivo .env. Isso é útil para testar um segundo modelo sem quebrar a configuração que funciona.

qwen --openai-api-key ollama \
  --openai-base-url http://localhost:11434/v1 \
  --model qwen2.5-coder:14b

#3. Variante: LM Studio como servidor

Se você preferir o LM Studio, o princípio é o mesmo. Carregue um modelo de código no aplicativo, abra a aba Developer e inicie o servidor local: ele escuta por padrão na porta 1234 e expõe a mesma API compatível com OpenAI. Lembre-se de ativar o suporte a chamadas de ferramentas nas opções do servidor, caso ainda não esteja marcado, e ajustar o tamanho do contexto do modelo na interface (consulte a próxima etapa).

OPENAI_API_KEY=lm-studio
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen2.5-coder-14b-instruct

O nome do modelo a ser informado é o identificador exibido pelo LM Studio na lista de modelos carregados ou retornado por uma consulta a http://localhost:1234/v1/models. Ele é diferente dos nomes Ollama.

#4. Ajuste a janela de contexto: a etapa que todo mundo pula

Essa é a principal causa das falhas do Qwen Code localmente. Um agente de código envia a cada rodada um prompt de sistema longo (descrição das ferramentas, regras de comportamento, conteúdo do arquivo QWEN.md), depois o histórico da sessão e, por fim, os arquivos lidos. Já nas primeiras interações, ultrapassamos 10.000 tokens. Porém, o Ollama abre por padrão uma janela curta (4.096 tokens nas versões recentes): tudo que excede esse limite é truncado silenciosamente, o modelo “esquece” as instruções das ferramentas e começa a responder em prosa em vez de agir, ou entra em loop na mesma ação.

Portanto, é preciso impor um contexto de pelo menos 32.000 tokens. Há dois métodos no Ollama: uma variável de ambiente global no daemon ou um Modelfile que define num_ctx para um modelo específico.

sudo systemctl edit ollama
# Ajouter dans le bloc [Service] :
# Environment="OLLAMA_CONTEXT_LENGTH=32768"
sudo systemctl restart ollama

launchctl setenv OLLAMA_CONTEXT_LENGTH 32768
# puis relancer l'application Ollama

cat > Modelfile.qwen-code <<'EOF'
FROM qwen3-coder:30b
PARAMETER num_ctx 32768
EOF
ollama create qwen3-coder-32k -f Modelfile.qwen-code
# puis OPENAI_MODEL=qwen3-coder-32k dans le .env

O segundo método é mais organizado: ele não afeta os outros modelos, e o nome do modelo derivado lembra sua configuração. O custo é de memória: o cache chave-valor cresce com o contexto. Para um modelo 7B em Q4, 32.000 tokens de contexto acrescentam aproximadamente de 2 a 4 GB, dependendo da arquitetura e da quantização do cache. Se o modelo não couber mais na GPU, o Ollama descarrega parte das camadas para a CPU e a velocidade despenca: monitore a coluna PROCESSOR de ollama ps, que deve exibir 100% GPU.

Do lado do Qwen Code, também existe um limite de sessão. A configuração sessionTokenLimit no arquivo de configurações limita o número acumulado de tokens de uma conversa; quando esse limite é atingido, a ferramenta solicita que você compacte o histórico com /compress ou recomece do zero com /clear. Alinhe esse valor ao que seu modelo realmente suporta: um limite de 32 000 para um modelo servido com num_ctx 32768 evita truncamentos silenciosos do lado do Ollama.

#5. Arquivo de configurações e QWEN.md

O Qwen Code lê um arquivo settings.json em dois níveis: ~/.qwen/settings.json para o usuário e .qwen/settings.json no projeto, que prevalece. As chaves mais úteis para uso local são o limite da sessão, o modo de aprovação das ações e os servidores MCP. Os nomes exatos mudaram entre as versões; o exemplo abaixo segue a documentação pública e deve ser conferido na página Settings da sua versão.

{
  "sessionTokenLimit": 32000,
  "contextFileName": "QWEN.md",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/moi/mon-projet"]
    }
  }
}

O arquivo QWEN.md desempenha o mesmo papel que CLAUDE.md no Claude Code ou AGENTS.md em outros agentes: é o memorando permanente injetado em cada sessão. Descreva nele a stack, os comandos de build e teste, as convenções de nomenclatura e o que o agente nunca deve tocar. O comando /init gera uma primeira versão a partir do repositório; /memory show exibe o que o agente realmente carregou.

# Projet API Facturation

- Python 3.12, FastAPI, tests avec pytest (`make test`).
- Ne jamais modifier les migrations existantes dans alembic/versions/.
- Toute nouvelle route doit avoir un test dans tests/api/.
- Style : ruff, lignes de 100 caractères max.

O modo de aprovação controla o que o agente pode fazer sem pedir sua autorização. Por padrão, cada gravação de arquivo e cada comando shell aguardam sua validação. A opção --approval-mode auto-edit permite modificações em arquivos, mas não comandos; --yolo remove toda confirmação. Com um modelo local que erra com mais frequência que um modelo na nuvem, mantenha o modo padrão enquanto ainda não tiver confiança e reserve --yolo para um repositório limpo e com commit.

#6. Primeira sessão de trabalho

Uma sessão do Qwen Code é controlada em linguagem natural, com alguns atalhos. O prefixo @ insere um arquivo ou uma pasta na solicitação (@src/api/routes.py), o prefixo! executa um comando shell sem passar pelo modelo, e os comandos que começam com / controlam a própria ferramenta.

/help

Lista dos comandos disponíveis na sua versão.

/auth

Altera o método de autenticação, útil para alternar entre o local e a nuvem.

/model

Exibe ou altera o modelo atual da sessão.

/stats

Tokens consumidos e duração da sessão: o primeiro reflexo quando as respostas pioram.

/compress

Resuma o histórico para liberar contexto sem perder o fio.

/clear

Começa uma conversa vazia; o QWEN.md continua carregado.

/init et /memory

Gera e depois inspeciona o arquivo de contexto do projeto.

/mcp

Status dos servidores MCP configurados e das ferramentas que eles expõem.

/quit

Sai da sessão.

Um fluxo que funciona bem com um modelo local: primeiro peça uma leitura (« explique como a autenticação é gerenciada em @src/auth/ »), depois uma modificação delimitada (« adicione uma verificação de expiração do token em verify_token e um teste correspondente ») e, em seguida, a verificação (« execute make test e corrija o que quebrar »). Cada etapa cabe em alguns milhares de tokens, e o modelo mantém o contexto. Solicitações do tipo « refatore todo o módulo » excedem o que modelos de 7 a 30B conseguem manter de forma confiável.

Para automação, o modo não interativo aceita uma solicitação como argumento e devolve o controle quando termina. Ele se integra a um script ou hook do Git.

qwen -p "Relis le diff de git diff --cached et liste les problèmes potentiels, sans modifier de fichier"

#Limitações do Qwen Code localmente

O Qwen Code foi desenvolvido em torno dos modelos Qwen3-Coder oferecidos pela Alibaba Cloud, e isso fica evidente assim que ele é executado em um modelo local menor. Eis o que você precisa aceitar.

Prompt de sistema pesado

A ferramenta envia uma longa descrição das ferramentas a cada rodada. Em um modelo 7B, essa instrução sozinha ocupa uma parte do contexto e da atenção do modelo, que respeita menos o formato de chamada de ferramentas do que os modelos maiores. Os loops e as respostas em prosa em vez de ações são mais frequentes do que no OpenCode ou no Aider, que usam prompts mais compactos.

Visão exclusiva da nuvem

O suporte a imagens (capturas de tela, maquetes) depende de modelos de visão oferecidos online. Localmente, ele só funciona se o seu servidor expuser um modelo multimodal compatível, o que não acontece com a maioria dos modelos de código.

Sem gerenciamento nativo de modelos locais

Ao contrário do OpenCode, que lista os modelos Ollama em um menu, o Qwen Code exige que você informe o nome do modelo e a URL em um arquivo ou como opção. Trocar de modelo implica editar o .env ou executar novamente com --model.

Formato de configuração em mudança

O projeto é recente, e seu arquivo settings.json mudou de estrutura ao longo das versões. Um exemplo encontrado em um fórum pode não ser mais válido. A documentação oficial, na data da consulta, é a referência definitiva.

Edição por reescrita

Assim como o Gemini CLI, do qual deriva, o Qwen Code modifica os arquivos substituindo blocos. Já o Aider aplica diffs unificados e faz commit automático de cada alteração, o que torna o histórico mais legível. Se você quiser um commit por alteração, o Aider continua sendo mais adequado.

Em contrapartida, o Qwen Code oferece suporte completo a MCP, comandos maduros de gerenciamento de sessão herdados do Gemini CLI, um modo não interativo bem estruturado e uma integração que se estende aos IDEs por meio de extensão. Ele é pertinente se você já usa os modelos Qwen e quer uma única ferramenta para alternar entre a nuvem da Alibaba e sua GPU. Se o objetivo for apenas o uso local, o OpenCode ou o Aider exigem menos configurações para chegar ao mesmo resultado. Não publicamos uma comparação numérica: a qualidade depende primeiro do modelo escolhido, não do agente.

#Solução de problemas

O agente responde em texto em vez de executar ações

Ou o modelo não oferece suporte à chamada de ferramentas (consulte a ficha Ollama), ou o contexto é curto demais e a descrição das ferramentas foi truncada. Execute a etapa 4 e verifique com ollama ps se o modelo foi carregado com o num_ctx correto.

Erro 404 ou « model not found »

O nome em OPENAI_MODEL não corresponde exatamente a ollama list. Copie e cole o nome com a tag.

Erro de conexão em localhost:11434

O Ollama não está iniciado ou está escutando em outra interface (OLLAMA_HOST). Teste com curl http://localhost:11434/v1/models.

Respostas muito lentas depois de algumas interações

O contexto aumentou e o modelo excedeu a capacidade da GPU. ollama ps mostra uma parte na CPU. Reduza o num_ctx, use um modelo menor ou execute /compress mais cedo na sessão.

Qwen Code solicita novamente uma autenticação OAuth

As variáveis de ambiente não são lidas: o .env não está na pasta atual nem em ~/.qwen. Execute /auth na sessão e escolha a opção OpenAI ou passe os parâmetros na linha de comando para isolar o problema.

O modelo ignora o QWEN.md

Verifique com /memory show se o arquivo foi carregado. Se contextFileName tiver sido alterado em settings.json, o nome deverá corresponder.

Falha na instalação do npm com EACCES

Permissões insuficientes na pasta global do npm. Instale o Node via nvm ou fnm em vez de usar o pacote do sistema e depois execute a instalação novamente.

#Para se aprofundar

Qwen Code é apenas um dos agentes de terminal que aceitam um servidor local. Os guias a seguir abordam as alternativas e a escolha do modelo, algo que este artigo deixa deliberadamente de lado.

• OpenCode + Ollama: um agente de código no seu terminal
• Aider + Ollama: programar no terminal com um agente 100% local
• Goose (Block): o agente de IA local no seu terminal
• Melhor LLM local para codar: Devstral, Qwen3-Coder

Guia elaborado em 11 de outubro de 2026; as referências são o repositório do GitHub e a documentação do Qwen Code, além da documentação Ollama. Nenhuma medição de velocidade ou qualidade foi realizada para este artigo; as referências de memória são ordens de grandeza. Os comandos e nomes de chaves mudam com as versões: verifique-os nas páginas abaixo antes de copiá-los.

• Repositório GitHub QwenLM/qwen-code (README, instalação, licença)
• Documentação oficial do Qwen Code (autenticação, settings, comandos)
• Documentação Ollama (API compatível com OpenAI, variáveis de ambiente)