Como usar o Qwen4 no Claude Code: configuração e erros de conexão
Configure o Qwen4-Max no Claude Code com a rota e a chave corretas. Investigue erros 401, 403 e a descoberta de modelos no CC Switch.
Para usar Qwen4-Max no Claude Code, configure a URL base compatível com Anthropic do QwenCloud, uma chave válida para essa rota e o mapeamento explícito para qwen4-max. Alterar apenas o nome exibido do modelo não muda o provedor. Uma consulta bem-sucedida à lista de modelos não é requisito para conversar com ele.
Este guia se baseia na documentação do QwenCloud verificada em 17 de novembro de 2026. Ele trata do modelo lançado, não de qwen4-max-preview. Se ainda precisar diferenciar as versões, comece pelo guia de API e migração do Qwen4. Aqui o objetivo é mais específico: direcionar o cliente de programação à rota desejada e identificar em qual camada ocorreu a falha.
A configuração de shell abaixo foi verificada localmente com um cliente simulado que registra nomes de configuração, sem usar um modelo real. Não fizemos chamadas pagas ao Qwen4 para este tutorial. A conversa final e a conferência de cobrança são etapas que você deve executar com sua própria conta autorizada.
Escolha a rota antes de inserir a chave
O QwenCloud documenta rotas separadas para Token Plan e pagamento por uso regional. Escolha uma primeiro; não combine uma chave de uma rota com a URL base de outra.
| Rota desejada | URL base do Claude Code | O que conferir |
|---|---|---|
| QwenCloud Token Plan | https://token-plan.maas.qwencloudapi.com/apps/anthropic | Chave do plano e acesso ao modelo escolhido |
| QwenCloud por uso, Singapura | https://ap-southeast-1.maas.qwencloudapi.com/apps/anthropic | Chave emitida para essa região e acesso ao modelo |
| Outra região QwenCloud | Use a URL compatível com Anthropic documentada para a região | Região, disponibilidade do serviço e escopo da chave |
Esses endereços são URLs base, não URLs completas de requisição de mensagem. Não acrescente /v1 à URL base do QwenCloud nesta configuração. O cliente usa o caminho de mensagens abaixo dela. O guia de Claude Code do QwenCloud e a documentação de regiões definem as regras dessas rotas.
Uma chave de API do Ofox não é uma chave do QwenCloud. Se optar por um modelo compatível com Ofox, siga a documentação de autenticação do Ofox e suas configurações de integração. Não cole uma chave do Ofox em nenhum dos endereços do QwenCloud. Este guia não comprova a disponibilidade do Qwen4 pelo Ofox; confira o diretório atual de modelos do Ofox separadamente.
Inicie uma sessão isolada com mapeamento explícito para Qwen4
No primeiro diagnóstico, use uma nova sessão de terminal e um pequeno projeto sintético. Faça backup da configuração habitual. O inicializador Bash abaixo limita as variáveis exportadas ao próprio processo e ao cliente filho. Ele não reescreve o arquivo global de configurações, não imprime a chave e não a armazena no script.
Salve como launch-qwen4.sh:
#!/usr/bin/env bash
set -euo pipefail
# Singapore pay-as-you-go. For Token Plan, replace only this route
# and enter the matching Token Plan key when prompted.
export ANTHROPIC_BASE_URL="https://ap-southeast-1.maas.qwencloudapi.com/apps/anthropic"
unset ANTHROPIC_API_KEY
read -r -s -p "QwenCloud key for this route: " ANTHROPIC_AUTH_TOKEN
printf '\n'
if [[ -z "$ANTHROPIC_AUTH_TOKEN" ]]; then
printf 'No key entered; no request sent.\n' >&2
exit 1
fi
export ANTHROPIC_AUTH_TOKEN
# Deliberately use one model while diagnosing routing.
export ANTHROPIC_MODEL="qwen4-max"
export ANTHROPIC_DEFAULT_OPUS_MODEL="qwen4-max"
export ANTHROPIC_DEFAULT_SONNET_MODEL="qwen4-max"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="qwen4-max"
export CLAUDE_CODE_SUBAGENT_MODEL="qwen4-max"
export CLAUDE_CODE_MAX_CONTEXT_TOKENS="983616"
exec claude "$@"
Execute bash launch-qwen4.sh no projeto de teste. Para testar Token Plan, substitua a URL base pelo valor correspondente na tabela e forneça a chave desse plano. Não use um ID arbitrário de modelo mais barato antes de confirmar sua disponibilidade na rota.
Mapear todos os aliases para Qwen4-Max é uma escolha de diagnóstico, não uma recomendação de custo. Isso elimina a dúvida sobre uma tarefa em segundo plano ou subagente ter escolhido outro modelo configurado. Depois de confirmar a rota, você pode mapear tarefas leves para outro modelo compatível e testar esse mapeamento separadamente.
O inicializador também não substitui todas as possíveis configurações gerenciadas, wrappers ou extensões de IDE. Se sua organização gerencia o cliente, siga essa política. Inicie a CLI diretamente neste teste para evitar que a IDE forneça outro ambiente sem que você perceba. No Windows, execute este exemplo Bash em WSL ou Git Bash compatível; o PowerShell nativo usa outra sintaxe para variáveis de ambiente. Não presuma que a CLI do Windows lê a mesma configuração de uma instalação no WSL.
Comprove o provedor e a tarefa separadamente
Na nova sessão do Claude Code, execute /status. Compare a URL do provedor e o modelo selecionado com os valores pretendidos. Não publique um despejo bruto de configurações nem capturas de tela com credenciais. Se a rota estiver vazia ou ainda apontar para outro serviço, examine a configuração carregada por aquele processo específico antes de mudar o modelo novamente.
Use uma tarefa pequena, sem conteúdo privado do repositório:
Create a Python function named normalize_code(value).
It must accept a string, trim surrounding spaces and preserve leading zeros.
Raise TypeError for non-string input.
Add tests for " 0017 ", "", and the integer 17.
Do not install dependencies or access the network.
Show which files you changed and how to run the tests.
Um registro útil de validação tem três partes separadas:
- Roteamento: a sessão informa o provedor e o mapeamento esperados; o registro do provedor, quando disponível, identifica o modelo pretendido. A descrição que o modelo faz de si mesmo não comprova a rota.
- Entrega: o arquivo existe,
" 0017 "vira"0017", a string vazia permanece vazia e uma entrada inteira geraTypeError. Execute os testes criados e inspecione o diff. - Cobrança: a chamada aparece na visualização de uso da conta ou do plano pretendido. Não deduza a origem da cobrança pelo nome do modelo exibido na ferramenta.
Se a resposta for boa, mas a conta errada for cobrada, a configuração não passou. Se a rota estiver correta, mas os testes falharem, registre uma falha da tarefa em vez de tratá-la como problema de conexão. Mantenha o primeiro experimento pequeno; só depois permita alterações maiores no repositório ou tarefas mais longas.
Relacione o sintoma à camada que falhou
A seção oficial de solução de problemas separa falhas que poderiam parecer um único problema de “Qwen não funciona”.
| Sintoma | Primeira verificação útil | Próximo passo direcionado |
|---|---|---|
401 invalid_api_key | Rota e região da chave; URL efetiva do provedor | Use a chave QwenCloud correspondente e reinicie o cliente; não exponha a chave nos logs |
| Claude Code ainda se conecta à Anthropic | /status e configuração carregada por esse processo | Corrija ambiente e configurações do provedor; examine wrappers ou autenticações conflitantes |
| CC Switch não encontra endpoint de lista de modelos | Se a verificação consulta descoberta de modelos em vez de mensagens | Defina o mapeamento manualmente e teste uma mensagem real na rota documentada |
403 AccessDenied após trocar o modelo | Direito de acesso e indicação de ciclo de vida na galeria do QwenCloud | Substitua mapeamentos indisponíveis ou descontinuados por um modelo atual acessível; guarde erro e ID da requisição |
| Trocar o modelo não altera uma rota antiga | Se a URL base contém claude-code-proxy | Migre para a interface documentada /apps/anthropic |
| Uma resposta longa para antes do fim | Limite de saída solicitado pelo cliente e motivo de parada | Confira o limite do modelo e reduza a tarefa ou ajuste o teto do cliente de forma deliberada |
Se a rota personalizada pretendida estiver configurada, mas a inicialização ainda tentar o login oficial da Anthropic, o FAQ do QwenCloud também orienta conferir hasCompletedOnboarding: true em ~/.claude.json, arquivo diferente de ~/.claude/settings.json. Faça backup desse JSON e mescle apenas o campo relevante; não substitua o arquivo nem altere configurações gerenciadas pela organização. Reinicie em um novo terminal. Se a configuração documentada continuar falhando, atualize o cliente pelo método oficial de instalação e confira novamente a configuração carregada.
O caso da lista de modelos merece atenção. O QwenCloud documenta que sua rota compatível com Anthropic oferece /v1/messages, mas não um endpoint de lista de modelos. Assim, o CC Switch pode indicar falha de descoberta mesmo quando a rota de conversa funciona. Isso não significa que todo 404 pode ser ignorado: URL de mensagem incorreta, segmento extra de caminho ou modelo incompatível ainda exigem correção. Confira qual requisição falhou.
Se uma requisição direta funciona, mas o cliente de programação continua falhando, consulte nosso guia de erros de conexão do Claude Code (em inglês). Para um identificador exato indisponível, veja como investigar “model not found” na OpenAI (em inglês), aplicando as verificações de provedor e endpoint. Falhas de certificado pertencem ao diagnóstico de TLS e certificados (em inglês), não ao mapeamento de modelos; não desative a verificação de certificado como atalho.
Defina limites de contexto e saída de forma consciente
O guia atual do QwenCloud orienta manter CLAUDE_CODE_MAX_CONTEXT_TOKENS em 983616 para Qwen4-Max. Essa configuração do cliente não representa a mesma medida do contexto anunciado de um milhão de tokens, nem comprova que uma tarefa longa será concluída.
A versão de 17 de novembro do guia recomenda CLAUDE_CODE_MAX_OUTPUT_TOKENS=131072 para saídas truncadas do Qwen4-Max. A observação sobre preview na mesma página usa 64000. Não misture a recomendação da prévia com a configuração do modelo lançado. Não é preciso definir o máximo no primeiro teste básico: uma saída permitida muito grande pode aumentar o tempo e o consumo. Inspecione o motivo de parada e escolha um limite adequado à tarefa.
Se seu agente repete um documento de referência grande, continue com o tutorial de cache explícito do Qwen4. Uma janela de contexto grande é uma configuração de capacidade; o cache segue um contrato de requisição separado. Nenhum dos dois comprova um acerto de cache sem os respectivos campos de uso.
Guarde uma configuração que permita voltar atrás
Após a aprovação do teste, registre versão do cliente, URL base do provedor, mapeamento de modelos, tipo de chave e região, resultado e horário. Guarde a chave em seu mecanismo habitual de gestão de segredos. Ao alterar configurações persistentes, mescle os campos necessários no arquivo existente em vez de substituir permissões e configurações sem relação com a mudança.
Em falhas futuras, altere uma variável por vez e mantenha ID de requisição sem dados sensíveis, status HTTP, código de erro e ID do modelo. Para reverter o inicializador, encerre a sessão iniciada e abra seu cliente habitual pelo terminal pai; o inicializador não modificou o ambiente desse terminal nem o arquivo de configurações. Se você alterou configurações persistentes separadamente, restaure também a versão salva.
A configuração está concluída quando a rota pretendida, os arquivos entregues e o registro de uso esperado concordam. Isso cria uma base estável para comparar modelos em tarefas reais de programação, sem precisar diagnosticar uma rota diferente a cada tentativa.
Perguntas frequentes
- O endpoint do Qwen precisa oferecer uma lista de modelos para o Claude Code?
- Não. Segundo a documentação do QwenCloud, o endpoint compatível com Anthropic oferece mensagens, mas não descoberta de modelos. Uma falha na consulta à lista do CC Switch é diferente de uma falha no envio de mensagem.
- Selecionar Opus significa que a requisição usa um modelo da Anthropic?
- Não necessariamente. Em um provedor personalizado, o alias Opus pode apontar para Qwen4-Max. Confira o provedor configurado, o mapeamento exato e os registros de requisições do provedor.


