Integração com modelos de terceiros / nacionais
Use DeepSeek e outros modelos nacionais / de terceiros para impulsionar o Claude Code e cortar seus custos
📚 Navegação da série: O artigo anterior 04 · Configuração de API explicou como usar a API Key oficial para conectar ao Claude Code. Este artigo traz uma abordagem diferente — substituir totalmente o "cérebro", usando um modelo nacional como o DeepSeek para economizar dinheiro.
⚠️ Um aviso antes de começar: Usar modelos de terceiros para rodar o Claude Code é considerado uma abordagem "experimental". A documentação oficial cobre formalmente apenas "gateways LLM" e Bedrock / Vertex para hospedagem do Claude, não oferecendo suporte oficial a nenhum modelo que não seja da Anthropic. Tudo neste artigo que a equipe oficial menciona claramente (significados das variáveis de ambiente, comportamento padrão) está marcado com a fonte; a parte do DeepSeek baseia-se em soluções e testes da comunidade, e o endereço da interface e nomes dos modelos podem mudar a qualquer momento, portanto verifique a documentação oficial do DeepSeek.
Amigos, vou dizer algo que pode ser polêmico: A maioria das pessoas simplesmente não precisa lidar com modelos de terceiros.
Muitos tutoriais na internet glorificam a conexão "Claude Code + DeepSeek" como uma ferramenta mágica de economia, fazendo parecer que você está perdendo dinheiro se não usá-la. Mas, falando sério — se você já comprou a assinatura do Claude (Pro / Max), ou sua despesa de API custa apenas alguns dólares por mês, o dinheiro que você vai economizar com muito esforço não será suficiente para pagar pelo tempo gasto corrigindo problemas nas variáveis de ambiente.
Então, por que escrevo este artigo? Porque existem dois tipos de pessoas que realmente vão precisar dele: Uma é o usuário intensivo que sofre com a fatura da API, gastando dezenas de milhões de tokens diariamente. Trocar para um modelo dez vezes mais barato pode economizar centenas de dólares por mês; A outra é o usuário na China que não consegue se conectar à API oficial e não quer lidar com VPN. Uma API de conexão direta, como a do DeepSeek, acaba sendo a mais conveniente.
Se você se encaixa em uma dessas opções — continue lendo. Se não, basta entender o princípio e não se apressar em fazer a troca.
Ao terminar de ler este artigo, você obterá:
- Uma tabela comparativa de "API Oficial vs Modelos de Terceiros", para decidir se deve ou não fazer a troca.
- Um conjunto de configurações do DeepSeek prontas para copiar e colar (para Mac / Windows).
- Entendimento claro sobre o que 4 variáveis de ambiente cruciais realmente fazem e como elas servem para substituir qualquer modelo de terceiros.
- Algumas armadilhas comuns: variáveis obsoletas, validação via
/statuse quando não usar.
01 Entenda primeiro: O que a troca de modelos realmente muda
Indo direto ao ponto: O Claude Code é a "casca", o modelo é o "cérebro". A integração com terceiros apenas substitui o cérebro por um de outra empresa.
O Claude Code que você instalou é essencialmente um cliente rodando no terminal — responsável por ler seu código, chamar ferramentas, gerenciar o contexto e executar o ciclo de agente "pensar → agir → observar". Mas ele não pensa sozinho. A cada etapa, ele precisa enviar a solicitação a um modelo e esperar a resposta. Por padrão, esse modelo é o Claude da Anthropic.
Analogia: Trocar o motor de um carro. O Claude Code é o chassi — o volante, o assento e o painel continuam os mesmos, sem a necessidade de mudar seus hábitos. O modelo é o motor. O motor original de fábrica (Claude) é o mais potente, mas o combustível é caro; se quiser economizar, você pode removê-lo e colocar um motor nacional (DeepSeek). O carro ainda é o mesmo e a experiência de condução é semelhante, o que muda é a potência e o consumo.
E como se faz essa "troca de motor"? Não se altera o código, e sim algumas variáveis de ambiente. A mais central é ANTHROPIC_BASE_URL — ela determina para qual endereço o Claude Code envia a solicitação.
Aqui há um ponto que a documentação oficial salienta, mas que a maioria dos tutoriais falha em explicar:
O
ANTHROPIC_BASE_URLmuda para onde as solicitações são enviadas, e não o modelo responsável por respondê-las. (Texto original da documentação oficial "Model Configuration")
O que isso significa? ANTHROPIC_BASE_URL apenas muda "para onde enviar a carta", mas não determina "quem vai responder". Ao mudar o endereço para a interface do DeepSeek, se o DeepSeek vai aceitar e qual modelo vai responder é algo definido pelo endereço da interface + nome do modelo. Mudar apenas a URL não é suficiente; o nome do modelo também deve ser configurado — essa é uma das armadilhas mais comuns.
Então, por que o DeepSeek funciona diretamente? Porque o DeepSeek fornece uma interface "compatível com o protocolo da Anthropic" — cujo endereço é https://api.deepseek.com/anthropic. Em outras palavras, o DeepSeek se disfarça como se fosse a Anthropic, fazendo o Claude Code acreditar que está falando com o servidor oficial, enquanto o cálculo é feito pelo DeepSeek. Você não precisa alterar nenhuma linha de código do Claude Code.
💡 Resumo em uma frase: Trocar o modelo = mudar algumas variáveis de ambiente para substituir o "motor", com a carroceria do carro (Claude Code) intacta;
ANTHROPIC_BASE_URLlida com "para onde enviar", e o nome do modelo define "quem vai responder", e ambos precisam ser configurados juntos.
02 Você deve mudar? Analise a tabela primeiro
Antes de agir, acalme-se por 5 minutos. Os modelos de terceiros não são perfeitos; eles economizam dinheiro, mas você perde outras coisas.
Eu fiz uma comparação real em um projeto durante duas semanas: na primeira semana usei o Sonnet oficial e na segunda mudei para o DeepSeek. A tabela abaixo mostra as impressões reais baseadas nesse uso, não uma cópia das tabelas de especificações.
| Dimensão | Claude Oficial (Anthropic API) | Modelos de Terceiros / Nacionais (ex: DeepSeek) |
|---|---|---|
| Preço | Caro, Opus queima muito dinheiro | ✅ Barato, frequentemente uma ordem de magnitude menor |
| Conexão Direta (China) | A maioria requer VPN | ✅ DeepSeek oferece conexão direta sem barreiras |
| Capacidade de Código | ✅ Atual nível de ponta, estável em refatorações complexas | Suficiente, mas pode falhar em tarefas muito complexas |
| Chamada de Ferramentas / Habilidade de Agente | ✅ O mais estável nativamente, bom em tarefas de várias etapas | ⚠️ Varia com o modelo, interfaces compatíveis podem ter comportamentos marginais |
| Custo de Configuração | Apenas preencher uma Key | Requer configurar variáveis de ambiente, fácil de cometer erros |
| Suporte Oficial | ✅ Cidadão de primeira classe | ❌ Experimental, sem garantia oficial se algo der errado |
Você entendeu? O preço baixo e a conexão direta são as maiores vantagens de usar modelos de terceiros; O custo é pago no limite de qualidade de código, estabilidade do agente e "falta de suporte garantido".
Minha conclusão após duas semanas de uso real: Para CRUD diário, testes, documentação e explicação de código, o DeepSeek é perfeitamente adequado e quase indistinguível do Sonnet, mas com um custo irrisório. Porém, quando se trata de refatoração pesada ou "entender o relacionamento entre cinco ou seis arquivos em diferentes módulos", o DeepSeek omitiu dependências essenciais duas vezes, enquanto o Claude acertou de primeira com o mesmo prompt.
A melhor maneira de usar é misturá-los: deixe as tarefas simples para os modelos baratos e as pesadas para o Claude — a seção 05 mostra como configurar isso.
Um julgamento simples se você deve trocar:
- ✅ Deve trocar: Usuários pesados com contas de API mensais muito altas; Usuários chineses que têm dificuldade em conectar e não querem usar VPN; Pessoas que apenas querem praticar e não se importam com a pequena diferença na capacidade dos modelos.
- ❌ Não se incomode: Se você já comprou a assinatura do Claude (é um custo fixo, usar a API seria um custo extra, a próxima seção 06 explica mais); Se a sua tarefa principal envolve refatorações arquitetônicas complexas e debugging avançado (não vale a pena sacrificar a qualidade do resultado por um pouco de economia).
Ainda está hesitando? Deixe sua rede falar por você.
Na lista de "devo ou não devo", "se é difícil se conectar à API oficial na China" é o item mais difícil de julgar sozinho — você acha que sua VPN é estável, mas ao usar o Claude Code, você recebe repentinamente um 502 ou 400. É um problema da API ou do bloqueio de rede? Não tente adivinhar, faça um teste de rede:
ipcheck é uma ferramenta de diagnóstico que testa seu IP / DNS / Proxy e risco de bloqueio em um só comando, dizendo se você pode se conectar limpa e diretamente à API oficial.
- Se o teste der muito vermelho / amarelo (Poluição DNS, proxy detectado, bloqueio) → não hesite, use modelos de terceiros e economize em investigações inúteis depois.
- Se o teste der todo verde → seja honesto e use o serviço oficial, não complique configurando variáveis apenas para economizar alguns trocados.
💡 Resumo em uma frase: Modelos de terceiros trocam "qualidade e garantia" por "economia e conexão direta"; Usuários intensivos e usuários na China que buscam conexão direta devem trocar, assinantes e desenvolvedores hard-core não.
03 Mão na massa: Conectando o DeepSeek ao Claude Code
Bem, supondo que você decidiu trocar, esta seção fornece as configurações prontas para uso.
Abaixo usaremos o DeepSeek como exemplo (o mais fácil para uso na China). Integrar outros modelos de terceiros (Kimi, Zhipu, outros agregadores...) segue exatamente o mesmo procedimento, apenas substitua o
ANTHROPIC_BASE_URLe o nome do modelo pelos da respectiva plataforma — consulte as documentações oficiais deles.
Pré-requisito: Obter uma API Key do DeepSeek
O pré-requisito é que o Claude Code já esteja instalado (se não, veja o 02 · Instalação e Uso). Então:
- Abra a plataforma de desenvolvedor do DeepSeek, registre-se / faça login.
- Crie uma API Key e copie-a e guarde-a com segurança (é algo como
sk-xxxxxxxx).
🔑 A API Key é como a chave da sua carteira. Não a submeta a repositórios Git, não a envie em grupos e não a escreva no código-fonte. Abaixo usaremos variáveis de ambiente para gerenciá-la, o que naturalmente evita que ela vá para o código.
Passo 1: Configurar variáveis de ambiente
Variáveis de ambiente são "um conjunto de chaves e endereços que o sistema lê". O Claude Code as lerá na inicialização para decidir para onde enviar e qual modelo usar.
Analogia: Preencher um formulário de envio. O ANTHROPIC_BASE_URL é o endereço de entrega, o ANTHROPIC_AUTH_TOKEN é sua identificação, e as variáveis ANTHROPIC_*_MODEL dizem "qual mensageiro deve entregar". Se você preencher corretamente, sua solicitação será enviada para o lugar certo e tratada pela pessoa certa.
Mac / Linux
Abra o terminal e execute linha por linha (substitua <Sua API Key do DeepSeek> pela sua chave real):
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=<Sua API Key do DeepSeek>
export ANTHROPIC_MODEL=deepseek-chat
export ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-chat
export ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-chat
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-chatWindows (PowerShell)
$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN="<Sua API Key do DeepSeek>"
$env:ANTHROPIC_MODEL="deepseek-chat"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-chat"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-chat"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-chat"⚠️ Sobre os nomes de modelo: O
deepseek-chatacima é um exemplo. Os nomes específicos dos modelos do DeepSeek (e seus níveis de capacidade) são definidos na documentação oficial do DeepSeek. O nome pode mudar quando a plataforma for atualizada. O nome do modelo é "a ID do mensageiro no formulário", se você preencher errado, o sistema não o reconhecerá e ocorrerá um erro na inicialização.
Este diagrama expressa todo o processo: Seu comando → O Claude Code empacota em uma solicitação → O BASE_URL altera o destino para o DeepSeek → O AUTH_TOKEN verifica sua identidade → O modelo DeepSeek processa → O resultado retorna ao terminal. No meio, o Claude Code (como uma "casca") não muda nada.
Passo 2: Tornar as configurações permanentes (opcional, mas altamente recomendado)
Os comandos export / $env: acima são válidos apenas na janela atual do terminal. Ao fechar a janela, eles somem — esse é o primeiro erro que os novatos cometem: "Eu configurei, por que não está funcionando quando abro um novo terminal?"
Para que as alterações sejam permanentes:
- Mac (zsh, padrão): Adicione os comandos
exportao final do arquivo~/.zshrce executesource ~/.zshrc. - Linux (bash): Adicione ao final do arquivo
~/.bashrce executesource ~/.bashrc. - Windows: Adicione nas Variáveis de Ambiente do Sistema (para o usuário) ou insira no
$PROFILEdo PowerShell.
💡 Resumo em uma frase: Integrar o DeepSeek = Obter a Key + Configurar variáveis de ambiente (Endereço + Identidade + Modelo); Exportar temporariamente expira ao fechar a janela, adicione ao
~/.zshrcpara uso a longo prazo.
04 Validação: Consegui conectar?
Depois de configurar, não comece a usar logo de cara, valide primeiro. Se você não verificar, pode passar um tempo e descobrir que suas solicitações ainda estavam sendo processadas pela API oficial, desperdiçando tempo.
Você só precisa de um comando. Entre em qualquer diretório de projeto, inicie o Claude Code e digite /status:
cd /path/to/your-project
claudeNa janela de chat, digite:
/statusSe a integração funcionou, você verá linhas parecidas com estas (preste atenção em Base URL e Model):
Base URL: https://api.deepseek.com/anthropic
Model: deepseek-chatSe o Base URL for o endereço do DeepSeek, significa que o "motor" foi substituído com sucesso. O comando /status também mostra informações da sua conta e o modelo atual, sendo a maneira mais rápida de resolver problemas — a documentação oficial especificamente recomenda seu uso para "validar se sua configuração de proxy e gateway foi aplicada corretamente".
Se ainda exibir o endereço oficial ou se mostrar um erro, verifique estas causas mais comuns:
| Sintoma | Causa Mais Provável | Como Consertar |
|---|---|---|
| Base URL ainda é oficial | Variáveis de ambiente não foram aplicadas (talvez você abriu um novo terminal) | Execute o source novamente ou confirme que foram salvas no arquivo de configuração |
| Erro de modelo inexistente na inicialização | Nome do modelo incorreto / a plataforma o renomeou | Verifique a documentação oficial do DeepSeek para os nomes mais recentes |
| 401 / Falha de Autenticação | A API Key está incorreta ou expirou | Gere uma nova Key, verifique se copiou espaços extras |
| Solicitações de login no claude.ai | O cliente ainda tenta autenticar oficialmente | Veja as notas abaixo |
Sobre o último item: Em alguns casos de uso com terceiros, o Claude Code ainda tenta forçar o prompt de login oficial. Um método comum para corrigir isso é editar o arquivo ~/.claude.json e adicionar "hasCompletedOnboarding": true para pular o guia. Isso é considerado uma solução experimental e não uma prática padrão documentada oficialmente, portanto o comportamento em novas versões pode mudar — se não precisar, não altere; apenas se ficar preso.
💡 Resumo em uma frase: Olhar o
/statusrevela se o Base URL mudou, indicando se conectou com sucesso; se não conseguir conectar, verifique a tabela de erros passo a passo, não fique adivinhando.
05 Avançado: Uso em camadas de modelos, economizando sem perder estabilidade
Esta seção traz a técnica mais valiosa e a execução concreta da "abordagem mista" falada na seção 02.
Lembra-se daquelas variáveis ANTHROPIC_*_MODEL na seção 01? Elas não estão repetidas à toa — O Claude Code internamente divide as tarefas em 3 níveis, e você pode designar um modelo para cada nível.
| Variável | Significado Oficial | Tarefa Adequada |
|---|---|---|
ANTHROPIC_DEFAULT_OPUS_MODEL | O modelo resolvido pelo alias opus | Tarefas complexas: arquitetura, debug complexo |
ANTHROPIC_DEFAULT_SONNET_MODEL | O modelo resolvido pelo alias sonnet | Tarefas rotineiras: funcionalidades, correções simples |
ANTHROPIC_DEFAULT_HAIKU_MODEL | Alias haiku / para funcionalidades de background (ex: títulos) | Tarefas leves: perguntas rápidas, rotinas ocultas |
CLAUDE_CODE_SUBAGENT_MODEL | Modelo usado por todos os subagentes / times de agentes | Sub-tarefas, use o mais barato e rápido |
Essas descrições são retiradas da documentação oficial "Model Configuration". Este não é um mecanismo do DeepSeek, mas algo nativo do Claude Code — ao se conectar a terceiros, você apenas aponta esses aliases para os modelos de terceiros.
Analogia: O turno do restaurante. O chef principal (modelo mais forte) ganha um alto salário e é reservado para cozinhar apenas os pratos de destaque; as refeições diárias são feitas por cozinheiros intermediários (modelo médio); e serviços de rotina como limpar mesas e organizar coisas (tarefas em segundo plano, subtarefas) são delegadas a aprendizes (modelos baratos e rápidos). Se todos os pratos forem feitos pelo chef principal, a comida será excelente, mas o custo o levará à falência.
Portanto, o truque para economizar não é "preencher a mesma variável em tudo", e sim dividir as tarefas — supondo que a plataforma tem um "modelo de raciocínio forte" e um "modelo rápido e barato":
# Tarefas complexas com o modelo forte
export ANTHROPIC_DEFAULT_OPUS_MODEL=<Modelo de Raciocínio Forte>
export ANTHROPIC_DEFAULT_SONNET_MODEL=<Modelo de Raciocínio Forte>
# Tarefas leves e chamadas de subagente usando os baratos
export ANTHROPIC_DEFAULT_HAIKU_MODEL=<Modelo Rápido e Barato>
export CLAUDE_CODE_SUBAGENT_MODEL=<Modelo Rápido e Barato>A grande vantagem dessa divisão: No Claude Code, quando você precisa do modelo forte, você usa /model opus. Por padrão ele roda com a rotina barata e os subagentes que lidam com muitas consultas em segundo plano usam o modelo mais barato — a fatura da sua API vai despencar.
Há também uma variável para controlar "a profundidade de pensamento", CLAUDE_CODE_EFFORT_LEVEL, o suporte oficial lista low / medium / high / xhigh / max / auto (onde auto volta ao default do modelo). Se você quer que o modelo gaste mais tempo pensando para produzir resultados mais consistentes, você pode aumentar. Se quiser respostas mais rápidas e queimar menos tokens, diminua.
Uma excelente configuração prática: O modelo default sendo um mais barato + nível de esforço
mediumpara o dia a dia. Se achar que o problema é complexo, você mesmo usa o comando/modelpara mudar ao modelo pesado e, temporariamente, usa o esforço emhigh. Com essa estratégia as contas tendem a reduzir a menos de um terço da fatura sem comprometer a eficiência na prática.
💡 Resumo em uma frase: Não coloque o mesmo modelo em todos os níveis — Atribua as tarefas difíceis para modelos fortes, e rotinas de fundo e subagentes para os modelos rápidos e baratos. Dividir garante custo menor com ótima qualidade.
06 Duas armadilhas que todos os novatos caem
Por fim, gostaria de mencionar dois erros muito comuns que os iniciantes encontram.
Erro 1: Copiar o nome de variáveis obsoletas oficialmente.
É comum ver tutoriais antigos na internet usarem uma variável como ANTHROPIC_SMALL_FAST_MODEL, projetada para modelos menores.
Essa variável está oficialmente documentada como obsoleta ("deprecated"), e a variável que a substitui é ANTHROPIC_DEFAULT_HAIKU_MODEL. Muitas vezes os novatos copiam tutoriais antigos e, apesar de ainda rodar de vez em quando, a documentação "Environment Variables" explica que não se deve usá-la.
Conclusão: Nas novas configurações use sempre ANTHROPIC_DEFAULT_HAIKU_MODEL, caso veja um tutorial com o ANTHROPIC_SMALL_FAST_MODEL, ignore e substitua.
Erro 2: Não conseguir distinguir AUTH_TOKEN de API_KEY
Qual variável deve ser usada para autenticar os serviços de terceiros? Essas duas parecem semelhantes, mas agem de formas totalmente distintas — veja a documentação:
| Variável | Comportamento Oficial | Qual usar para modelos de terceiros |
|---|---|---|
ANTHROPIC_AUTH_TOKEN | Usada no header Authorization e adiciona o prefixo Bearer | ✅ Use isto para conectar com DeepSeek e terceiros |
ANTHROPIC_API_KEY | Usada no header X-Api-Key; e o força o uso deste quando não interativo (-p) | Usado ao conectar com a API da Anthropic Oficial |
Por que as empresas de terceiros recomendam ANTHROPIC_AUTH_TOKEN? Porque as APIs compatíveis como as do DeepSeek utilizam o padrão HTTP no formato Authorization: Bearer <key>, combinando exatamente com isso. Este é o porquê de soluções da comunidade indicarem a variável AUTH_TOKEN.
Também há algo na documentação que diz que, quando você altera o ANTHROPIC_BASE_URL para hosts de terceiros, a funcionalidade de buscar em ferramentas MCP é desativada por padrão. Isso apenas indica que integrações de terceiros podem limitar algumas funcionalidades avançadas de integração com as ferramentas MCP. Se você for um usuário intenso de MCP, tenha isso em mente.
💡 Resumo em uma frase: A autenticação para modelos de terceiros é com o
ANTHROPIC_AUTH_TOKENe modelos rápidos ficam noANTHROPIC_DEFAULT_HAIKU_MODEL; Evite variáveis obsoletas antigas e saiba que usar terceiros pode desativar recursos avançados do MCP.
07 Resumo
Este artigo explicou algo bem simples: Como trocar o 'cérebro' do Claude Code da versão oficial para modelos de terceiros ou nacionais.
Lista com pontos chave:
| Etapa | Ação Essencial |
|---|---|
| Planejar | Usuários pesados / Usuários chineses que precisam de conexão direta devem trocar; Assinantes não devem. |
| Conectar | Defina o ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN + Nomes dos Modelos |
| Testar | Com /status valide se a Base URL mudou |
| Economizar | Divida por camadas! O pesado para tarefas difíceis, o mais barato para subagentes |
| Evitar Erros | Descarte variáveis obsoletas (ANTHROPIC_SMALL_FAST_MODEL); A autenticação de terceiros usa AUTH_TOKEN. |
Você agora deve ser capaz de: Conectar o DeepSeek (ou qualquer modelo de terceiros compatível com Anthropic) ao Claude Code, verificar a conexão e configurar camadas de tarefas para reduzir suas contas.
Repito mais uma vez: Isso é uma estratégia de economia, não um curso obrigatório. Se vale a pena, depende de quão cara está a sua conta de API. Para usuários leves, a API oficial já é excelente.
No próximo artigo: 06 · Coding Plan: Planos de assinatura e faturamento — Como este artigo sempre fala sobre "economizar", vamos levar isso até o fim: O que compensa mais, os planos de assinatura (Pro / Max) do Claude ou a API com pagamento por uso? Deixo uma pergunta para pensar: Se você usa muito o Claude Code todos os dias, deveria comprar a assinatura ou a API de terceiros é mais econômica? A resposta virá no próximo artigo.