Como usar o Qwen Code: instalação, escolha de conta e modelo e configuração da API

O Qwen Code é um agente de programação de IA de código aberto (Apache-2.0), publicado pela equipe Alibaba Qwen. O uso tem quatro etapas: “instalar → executar qwen no projeto → configurar o destino da conexão com /auth → solicitar o trabalho”. Porém, o nível gratuito do Qwen OAuth terminou em 15 de abril de 2026; portanto, fazer login seguindo instruções anteriores não funcionará mais gratuitamente. E um ponto importante para usuários coreanos: o Qwen Code não tem UI em coreano. Esta página explica, em sequência, como começar pelo menu /auth atual, configurar respostas em coreano, fazer uma configuração personalizada para usar Claude e GPT e usar os comandos mais comuns. A versão mais recente é a v0.24.7, publicada no npm em 29 de setembro de 2026; como há lançamentos pelo menos uma vez por semana, confirme a versão instalada com qwen --version.

Instalação

Estes são os comandos do README oficial. Com o script de instalação independente, não é necessário preparar o Node.js diretamente; ele só é necessário na versão 22 ou superior quando a instalação é feita com npm.

# 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

# npm (Node.js 22 이상 필요)
npm install -g @qwen-code/qwen-code@latest

# Homebrew (macOS / Linux)
brew install qwen-code

Reabra o terminal para que as variáveis de ambiente tenham efeito após a instalação. O Qwen Code foi originalmente baseado no Google Gemini CLI v0.8.2, mas desde a v0.1 é desenvolvido de forma independente, sem sincronização com o original. As configurações e a cota gratuita do Gemini CLI não se aplicam automaticamente.

Primeira execução e respostas em coreano

cd /path/to/your-project
qwen

# 세션 안에서:
/language output Korean   # 모델 답변을 한국어로 (UI는 한국어 미지원)
/auth                     # 공급자와 API 키 설정

Os únicos idiomas de UI integrados são chinês simplificado, inglês, russo, alemão, japonês, português brasileiro, francês e catalão; os arquivos de tradução da UI no repositório também não incluem coreano (verificado em 1º de outubro de 2026). Portanto, os menus aparecem em inglês, e esta página cita exatamente os textos em inglês exibidos na tela. O idioma das respostas do modelo é separado da UI e pode ser fixado em coreano com /language output Korean.

Além do terminal, há um aplicativo para desktop, uma UI web aberta no navegador (qwen serve --open, recurso experimental), integrações com VS Code, Zed e JetBrains e execução headless para scripts e CI (qwen -p "..."). Tudo está no mesmo repositório gratuito, mas os custos de inferência são cobrados separadamente.

Escolher o destino da conexão com /auth

Ao abrir /auth(alias /login), aparece a tela “Select authentication method:”, com três opções de nível superior. Se você tentar escolher Qwen OAuth, verá a mensagem “Discontinued — switch to Coding Plan or API Key”.

As três opções do ModelStudio não são três formas de pagar a mesma fatura. A documentação define um endpoint e uma chave separados para cada uma; se o tipo de chave e baseUrl não corresponderem, não funcionará. Em 1º de outubro de 2026, o Coding Plan aparecia como “quantidade limitada, por ordem de chegada; reposição diariamente à meia-noite (UTC+8)”, portanto talvez não seja possível assinar em determinados dias. No Coding Plan, uma tarefa é calculada com várias chamadas de modelo; a Alibaba explica que normalmente são 5–10 chamadas para tarefas simples e 10–30 ou mais para tarefas complexas. A comparação de preços é detalhada na página em inglês Qwen Code pricing.

Usar Claude ou GPT: Custom Provider em settings.json

A documentação de autenticação do Qwen Code recomenda ~/.qwen/settings.json e modelProviders para conexões de terceiros como OpenAI, Anthropic, Google, OpenRouter e endpoints próprios. Para a Kunavo, fica assim.

{
  "modelProviders": {
    "openai": [
      {
        "id": "claude-sonnet-5",
        "name": "Claude Sonnet 5 (Kunavo)",
        "baseUrl": "https://api.kunavo.com/v1",
        "description": "Kunavo, OpenAI 호환",
        "envKey": "KUNAVO_API_KEY"
      }
    ]
  },
  "security": {
    "auth": {
      "selectedType": "openai"
    }
  },
  "model": {
    "name": "claude-sonnet-5"
  }
}

# 키는 settings.json에 직접 쓰지 말고 .qwen/.env 나 환경 변수로
echo 'KUNAVO_API_KEY=sk-kn-...' >> ~/.qwen/.env

Quatro pontos que poupam tempo de depuração:

• baseUrl vai somente até /v1. A documentação de referência do provedor do modelo determina: “especifique a raiz /v1 da API, não o caminho completo /v1/chat/completions, pois o SDK acrescenta o caminho da solicitação”. Se você incluir o caminho, receberá 404, não um erro de autenticação.
• Onde colocar a chave. O Qwen Code lê a chave da variável de ambiente cujo nome está em envKey. A prioridade é shell export, arquivo .env(.qwen/.env recomendado; somente o primeiro arquivo encontrado), settings.json com env; a última opção armazena a chave em texto simples e não é recomendada.
• O arquivo de configuração vence as flags da CLI. A ordem de decisão é valor de entrada de /auth → item modelProviders selecionado → argumento da CLI → variável de ambiente → settings.json. É por isso que --openai-base-url parece ser ignorado. security.auth.apiKey e security.auth.baseUrl, mencionados em explicações antigas, estão previstos para descontinuação.
• Comece com Chat Completions. Se você omitir wireApi, será usado o formato Chat Completions. Se alterar para "responses", não haverá detecção automática do endpoint nem fallback automático em caso de falha. Alterações em modelProviders também são aplicadas imediatamente à sessão em execução (elas aparecem ao reabrir /model).

O catálogo da Kunavo não tem modelos de texto Qwen. Isso não é uma forma barata de usar Qwen, mas uma forma de usar Claude e GPT dentro do Qwen Code com um único saldo pré-pago. Além disso, a Kunavo não verificou o Qwen Code executando de fato em seu próprio endpoint. A configuração foi escrita consultando a documentação oficial, assim como a página em inglês Configuração do Qwen Code. Faça testes mantendo disponível a rota que você usa atualmente.

Primeira tarefa e comandos frequentes

A primeira solicitação sugerida pelo README é algo como “explique este repositório e diga por onde começar”. Ela confirma de uma vez a leitura de arquivos e as chamadas de ferramentas. Apenas cumprimentar o agente não permite encontrar problemas de conexão.

Modos de aprovação automática como yolo vêm com o aviso explícito de que devem ser usados apenas em ambientes confiáveis, em sandbox ou descartáveis. O custo estimado de /stats model é um cálculo do Qwen Code, não o valor cobrado. Confira o valor real no histórico de uso do provedor conectado.

Limitações importantes

• O web_search integrado é ativado ou desativado conforme o destino da conexão. Como usa a busca no lado do servidor do DashScope, ele é ativado com uma ModelStudio Standard API Key, um Token Plan e itens que apontem para um host DashScope reconhecido; é desativado no Coding Plan (não verificado nesse endpoint) e também em endpoints personalizados de terceiros ou de outros hosts (documentação do web_search). Se necessário, conecte um servidor de busca MCP.
• A rota da Kunavo é apenas para chat. A Kunavo não oferece modelos de embeddings, síntese de voz ou reconhecimento de voz. O Live Voice do Qwen Code exige um endpoint DashScope e, portanto, usa a chave separada mesmo que o modelo de chat seja direcionado para outro lugar.

Pagamentos ao testar com a Kunavo

A Kunavo usa recargas pré-pagas, sem mensalidade, e desconta do saldo por token. A recarga mínima é de $10; no checkout do Stripe, é possível usar cartões (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay, Google Pay e Link. Se o checkout for exibido em won, também será possível escolher KakaoPay, Naver Pay, PAYCO, Samsung Pay e cartões domésticos que não aceitam pagamentos internacionais (a conversão para won inclui uma taxa de câmbio do Stripe de 2–4%; pagar em dólares evita essa taxa). Toss Pay não está disponível. Consulte as informações de pagamento, crie uma conta e emita sua chave. Após a primeira solicitação, a forma mais segura de confirmar o valor real é consultar o histórico de uso.

Perguntas frequentes

Verificado em 1º de outubro de 2026: README do Qwen Code; documentação de autenticação, provedores de modelo, comandos e web_search (branch main); lista de arquivos de tradução da UI do repositório; @qwen-code/qwen-code 0.24.7 no npm; páginas do Coding Plan e do Token Plan da Alibaba Cloud. A Kunavo não executou o Qwen Code em seu próprio endpoint.