Este artigo narra uma experiência prática de integração de modelos de linguagem chineses (Qwen/DeepSeek) ao Claude Code, destacando como a compreensão do protocolo de comunicação se mostrou mais importante do que soluções intermediárias.
O Desafio Inicial
Ao utilizar ferramentas como Cursor e Augment, muitos desenvolvedores recorrem a práticas criativas para acessar recursos computacionais de IA. Contudo, com o aumento das restrições por parte dos provedores, manter essas abordagens tornou-se cada vez mais custoso e instável.
O Claude Code, lançado pela Anthropic em maio de 2025, rapidamente se destacou como uma ferramenta de codificação assistida por IA com excelente engenharia de contexto. Entretanto, apresenta uma limitação significativa: opera exclusivamente com a API proprietária da Anthropic, cujo acesso é restrito e sujeito a bloqueios frequentes de contas.
A raiz do problema reside na incompatibilidade entre protocolos:
- O Claude Code utiliza o protocolo Anthropic
- A maioria das plataformas nacionais e internacionais adota o padrão OpenAI
- Essas duas abordagens diferem em estrutura de parâmetros e caminhos de requisição
Ao descobrir que a ModelScope oferece acesso gratuito às APIs do Qwen e DeepSeek (com limite de 2000 chamadas diárias), surgiu a seguinte meta: conectar esses modelos ao Claude Code.
A Armadilha dos Adaptadores Universais
A primeira abordagem envolveu o projeto open-source CCR, que prometia servir como ponte universal entre diferentes formatos de API. O processo de configuração incluía:
- Instalação do CCR
- Configuração de rotas de encaminhamento
- Registro dos endpoints e chaves dos modelos nativos
- Direcionamento do Claude Code para o servidor CCR
Após período significativo de configuração e testes, a integração funcionou parcialmente. Contudo, atualizações subsequentes do CCR quebraram as configurações estabelecidas, gerando erros de conexão e mensagens de aviso no log de execução.
A busca por soluções em fóruns e repositórios revelou um padrão preocupante: correções baseadas em tentativa e erro, com taxa de sucesso imprevisível. Essa instabilidade demonstrou que ferramentas críticas para produtividade não podem depender de soluções frágeis.
Compreendendo o Real Obstáculo
Após múltiplas tentativas frustradas, uma análise mais cuidadosa revelou a verdadeira natureza do problema:
- O Claude Code reconhece apenas o protocolo nativo da Anthropic
- Plataformas como ModelScope oferecem compatibilidade com o padrão OpenAI
- Adaptadores como CCR funcionam como tradutores entre protocolos
Toda camada intermediária introduz complexidade adicional: versionamento, bugs, necessidade de manutenção e testes contínuos. A questão fundamental tornou-se: existe realmente necessidade de um tradutor, ou seria possível encontrar uma plataforma que já "fale" o idioma correto?
A Solução Nativa
A verificação da documentação da ModelScope revelou que determinados modelos já suportam nativamente o formato de comunicação da Anthropic. Da mesma forma, o DeepSeek também disponibilizou uma interface compatível com o Claude Code.
Essa descoberta eliminou completamente a necessidade de middleware. O processo resume-se em duas ações:
- Configurar o Claude Code para apontar para o endpoint compatível com Anthropic na ModelScope
- Especificar qual modelo deve ser utilizado
Guia de Configuração Prático
Etapa 1: Obtenção da Chave de API
Acesse a plataforma ModelScope, navegue até a seção de tokens de acesso e gere uma nova chave de API. Guarde-a com segurança para uso nas configurações locais.
Etapa 2: Validação com Variáveis Temporárias
Antes de alterar configurações permanentes, valide a integração utilizando variáveis de ambiente transitórias no terminal. No PowerShell do Windows:
$env:ANTHROPIC_BASE_URL = "https://api-inference.modelscope.cn"
$env:ANTHROPIC_AUTH_TOKEN = "sua-chave-api-modelscope"
$env:ANTHROPIC_MODEL = "Qwen/Qwen3-Coder-480B-A35B-Instruct"
Três parâmetros são essenciais:
- ANTHROPIC_BASE_URL: endpoint de inferência compatível com Anthropic
- ANTHROPIC_AUTH_TOKEN: chave de autenticação da ModelScope
- ANTHROPIC_MODEL: identificador completo do modelo desejado
Na mesma sessão do terminal, execute o Claude Code:
claude
Para verificar se a configuração está correta, solicite à ferramenta que identifique seu modelo. Se a resposta indicar o modelo configurado (por exemplo, Qwen), a integração está funcionando.
Etapa 3: Tornando a Configuração Permanente
As variáveis definidas via terminal são descartadas ao fechar a janela. Para persistência, configure-as como variáveis de ambiente do usuário no Windows:
- Abra as configurações de variáveis de ambiente (Win → digite "variáveis de ambiente")
- Clique em "Editar variáveis de ambiente do sistema"
- Na seção de variáveis do usuário, crie três novas entradas:
- ANTHROPIC_BASE_URL → https://api-inference.modelscope.cn
- ANTHROPIC_AUTH_TOKEN → sua-chave-api
- ANTHROPIC_MODEL → Qwen/Qwen3-Coder-480B-A35B-Instruct
- Confirme e reinicie todos os terminais abertos
Após essa configuração, basta executar claude em qualquer terminal para acessar os modelos configurados.
Etapa 4: Configuração por Projeto
Para cenários onde múltiplas máquinas são utilizadas ou deseja-se centralizar as configurações do Claude Code, crie o arquivo .claude/settings.json no diretório do usuário:
{
"env": {
"ANTHROPIC_BASE_URL": "https://api-inference.modelscope.cn",
"ANTHROPIC_AUTH_TOKEN": "chave-api-aqui",
"ANTHROPIC_MODEL": "Qwen/Qwen3-Coder-480B-A35B-Instruct"
}
}
Esse arquivo permite que o Claude Code leia as configurações mesmo quando variáveis de ambiente do sistema não estão disponíveis.
Lições Aprendidas
1. Evite intermediários desnecessários
Adaptadores universais como o CCR adicionam camadas de complexidade que consomem tempo de configuração e manutenção. Quando uma solução nativa existe, ela quase sempre será mais confiável.
2. O protocolo determina a arquitetura
A verdadeira chave para integrar modelos ao Claude Code não está em ferramentas intermediárias, mas na compatibilidade de protocolo. Quando a plataforma de destino suporta nativamente o formato Anthropic, a integração se simplifica drasticamente. Interfaces e ferramentas evoluem continuamente, mas a escolha correta do protocolo de comunicação garante independência em relação a camadas intermediárias.
3. Reavalie o problema antes de buscar soluções
Em momentos de dificuldade, é comum seguir cegamente sugestões encontradas em fóruns. O progresso real ocorreu quando houve uma pausa para redefinir claramente o objetivo: utilizar modelos específicos de forma estável, independentemente da ferramenta intermediária escolhida.
Recomendações Práticas
- Ao integrar modelos de terceiros ao Claude Code, verifique primeiro se a plataforma suporta nativamente o protocolo Anthropic
- Minimize o número de camadas intermediárias na arquitetura
- Diante de erros, investigue a compatibilidade de protocolos e a documentação oficial antes de recorrer a soluções comunitárias
- Fóruns e comunidades são úteis para diagnosticar problemas compartilhados, mas não devem ser a fonte primária de soluções