DeepSeek V4: Guia de Configuração do Claude Code

Essa não é uma configuração oficialmente suportada pela Anthropic ou pela DeepSeek. A DeepSeek documenta a integração; a Anthropic tolera. Se quebrar, o time de suporte de nenhuma das duas empresas é sua primeira ligação.

Por que devs estão rodando DeepSeek V4 no Claude Code

O aumento repentino nas pesquisas por "DeepSeek Claude Code" (maio de 2026, consulta em ascensão de +170%)

A combinação faz sentido no papel: Claude Code é um agente de terminal maduro com CLAUDE.md, /ultrareview, task budgets e suporte a MCP. DeepSeek V4 é um modelo frontier competitivo a uma fração do custo por token da Anthropic. O endpoint da API da DeepSeek compatível com Anthropic (/anthropic) foi criado exatamente pra esse caso de uso — e quando a DeepSeek confirmou a integração no guia oficial de integração com Claude Code, os devs perceberam.

O pico de buscas veio depois do endosso formal da DeepSeek à configuração no guia de integração com coding agents. Não é um hack. É um caminho documentado que está funcionalmente disponível desde que a DeepSeek expôs o endpoint /anthropic.

O que você realmente ganha vs. o DeepSeek-TUI nativo

Rodar DeepSeek V4 pelo Claude Code é diferente de rodar o DeepSeek-TUI diretamente. As diferenças principais:

Se você já investiu no workflow do Claude Code — CLAUDE.md, servidores MCP existentes, Routines — essa configuração preserva esse investimento enquanto troca o backend do modelo. Se você quer RLM parallel sub-agents ou uma TUI Rust-native, o DeepSeek-TUI é a melhor escolha.

Quando essa configuração faz sentido e quando não faz

Faz sentido: você está pagando pela API da Anthropic nas tarifas cheias do Claude e quer reduzir custos em trabalho de alto volume ou experimental. Você quer testar a capacidade do DeepSeek V4 no seu workflow existente do Claude Code antes de se comprometer com outra ferramenta. Você tem arquivos CLAUDE.md e servidores MCP que não quer migrar.

Não faz sentido: você usa uma assinatura do Claude Code (Pro/Max) em vez de billing por API key — a assinatura não é roteada por essa configuração de variável de ambiente. Você precisa de /ultrareview, task budgets ou qualquer feature nativa da Anthropic. Você está trabalhando com código sensível ou proprietário (leia a seção de segurança abaixo).

Antes de começar: requisitos e o que isso não consegue fazer

Versão do Claude Code e suporte por OS

Essa configuração requer o CLI do Claude Code — superfícies de terminal e VS Code apenas. O Claude Desktop não suporta essa configuração: o Desktop usa OAuth, não API keys, e não lê ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_BASE_URL. Configure isso no terminal ou via extensão do VS Code.

Instale ou verifique o Claude Code:

# Instale via installer nativo (recomendado — npm install está deprecated):
# macOS / Linux:
curl -fsSL https://claude.ai/install.sh | sh
# Ou: brew install claude-code

# Verifique:
claude --version

Node.js 18+ é necessário se você usar o caminho npm. O installer nativo não tem dependência de Node.js.

API key da DeepSeek em platform.deepseek.com

Cadastre-se em platform.deepseek.com e crie uma API key. A DeepSeek tem oferecido créditos pra novos usuários no cadastro — verifique a disponibilidade atual de créditos na plataforma; isso muda. Sua key vai parecer com sk-xxxxxxxxxxxxxxxx.

O que ainda funciona nas features nativas do Claude Code, o que não funciona

Ainda funciona: CLAUDE.md, AGENTS.md, servidores MCP (stdio transport), slash commands do claude que não requerem o backend da Anthropic, o sistema de approval gate, histórico de sessão e /resume, Routines (o mecanismo de agendamento), e a maior parte da superfície CLI do Claude Code.

Não funciona: /ultrareview (requer backend da Anthropic), task budgets (o beta header task-budgets-2026-03-13 é específico da Anthropic), xhigh reasoning effort (feature da Anthropic), skills assinadas pela Anthropic do ecossistema de Skills do Claude Code, e qualquer feature que faça uma chamada diretamente à infraestrutura da Anthropic.

Setup passo a passo

Passo 1 — Instale ou atualize o Claude Code

# macOS/Linux nativo:
curl -fsSL https://claude.ai/install.sh | sh

# Verifique a instalação:
claude --version

Se você está em um npm install antigo e tendo problemas, a documentação da Anthropic agora chama a instalação via npm de deprecated. Migre pra o installer nativo.

Passo 2 — Gere uma API key da DeepSeek

1. Acesse platform.deepseek.com
2. Navegue até API Keys → Create new key
3. Copie a key — ela é mostrada apenas uma vez
4. Adicione crédito de billing se necessário (créditos de novo usuário podem cobrir os testes iniciais)

Passo 3 — Configure as variáveis de ambiente

Linux / macOS (shell):

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=<sua API Key da DeepSeek>
export ANTHROPIC_API_KEY=<sua API Key da DeepSeek>   # algumas versões do Claude Code verificam as duas
export ANTHROPIC_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-v4-pro[1m]
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-v4-flash
export CLAUDE_CODE_SUBAGENT_MODEL=deepseek-v4-flash
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export CLAUDE_CODE_EFFORT_LEVEL=max

Windows (PowerShell):

$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN="<sua API Key da DeepSeek>"
$env:ANTHROPIC_API_KEY="<sua API Key da DeepSeek>"
$env:ANTHROPIC_MODEL="deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-pro[1m]"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"
$env:CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash"
$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"
$env:CLAUDE_CODE_EFFORT_LEVEL="max"

Via settings.json (arquivo de configuração do Claude Code, persistente):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "<sua API Key da DeepSeek>",
    "ANTHROPIC_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4-flash",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_EFFORT_LEVEL": "max"
  }
}

O caminho do settings.json é ~/.claude/settings.json (global) ou .claude/settings.json no diretório do seu projeto. A configuração de referência completa também está em deepseek-ai/awesome-deepseek-agent.

Passo 4 — Escolha um modelo: deepseek-v4-pro vs deepseek-v4-flash

deepseek-v4-pro[1m] — o flagship. 1,6T parâmetros totais, 49B ativos, janela de contexto de 1M. Use pra tarefas complexas de agente, refactors multi-arquivo, trabalho que exige muito raciocínio. Mais caro por token.

deepseek-v4-flash — o tier eficiente. 284B parâmetros totais, 13B ativos, janela de contexto de 1M. Use pra funções de subagente, edições simples, trabalho exploratório. Significativamente mais barato por token.

O sufixo [1m] no ID do modelo solicita explicitamente a janela de contexto de 1M. Sem ele, o contexto padrão pode ser menor.

Passo 5 — Verifique a conexão com uma tarefa pequena

claude

Dentro da sessão, rode:

/status

Isso mostra a base URL atual e o modelo. Se você ver api.deepseek.com/anthropic no campo da base URL, as variáveis de ambiente foram carregadas. Rode uma tarefa pequena de só leitura pra confirmar que as respostas do modelo estão chegando:

Summarize the purpose of this file: README.md

Se você receber uma resposta, a integração está funcionando.

Configurando contexto de 1M e modos de thinking

Quando o contexto de 1M realmente vale a pena

A janela de contexto de 1M é real — e também é o custo por token de preenchê-la. Com 1M tokens de input, você está pagando por 1M tokens. Carregar um codebase grande inteiro em um único contexto é arquiteturalmente possível, mas pode custar mais por sessão do que sua estimativa de baseline.

Use a janela de 1M pra tarefas onde ela realmente ajuda: refactors multi-arquivo que precisam ler muitos arquivos em uma única passagem, sessões longas de test-fix onde o histórico acumulado de tool calls importa, ou análise de codebase que requer entender relações entre muitos arquivos. Pra tarefas curtas e focadas, não pré-carregue contexto que você não precisa.

Reasoning effort: max, high, off

Definir CLAUDE_CODE_EFFORT_LEVEL=max diz ao Claude Code pra solicitar profundidade máxima de raciocínio do modelo. Pelo endpoint /anthropic da DeepSeek, isso mapeia pro modo de thinking do DeepSeek V4. O impacto: output mais completo em tarefas complexas, e maior consumo de tokens no output (tokens de thinking são cobrados).

Pra tarefas onde a profundidade de raciocínio importa menos — edições rápidas, lookups simples, formatação — considere reduzir pra high ou omitir o effort level pra reduzir o consumo de thinking tokens.

Implicações de custo por token

Os custos dependem dos preços atuais da DeepSeek (verifique platform.deepseek.com/api-docs/pricing no momento do uso — as tarifas mudaram e podem mudar novamente). Dois fatores que impulsionam o custo nessa configuração:

Tamanho do contexto: contexto mais longo = mais tokens de input por request

Modo de thinking: esforço máximo gera traces de raciocínio extendido cobrados como tokens de output

O context caching funciona pelo endpoint /anthropic da DeepSeek — conteúdo estável repetido (system prompt, arquivos sem alteração) é cacheado no lado da DeepSeek e cobrado à tarifa de cached input (~10% da tarifa completa de input).

Erros comuns e correções

"API streaming failed" ou erros de conexão

API Error: streaming failed

Verificação 1: confirme que ANTHROPIC_BASE_URL está definida como exatamente https://api.deepseek.com/anthropic — sem barra no final, sem /v1.

Verificação 2: conectividade de rede com api.deepseek.com. Se você está atrás de um proxy corporativo, defina HTTPS_PROXY antes das variáveis de ambiente.

Verificação 3: adicione CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 — isso evita que o Claude Code faça fallback pra um caminho não-streaming que pode conflitar com o endpoint da DeepSeek.

Falhas de autenticação

API Error: 401 Unauthorized

Causa comum: definir ANTHROPIC_API_KEY mas não ANTHROPIC_AUTH_TOKEN. Algumas versões do Claude Code verificam um, algumas verificam os dois. Defina os dois com sua key da DeepSeek:

bash

export ANTHROPIC_AUTH_TOKEN=<sua key da DeepSeek>
export ANTHROPIC_API_KEY=<sua key da DeepSeek>

Também verifique se a key é válida: teste-a diretamente contra a API da DeepSeek com uma chamada curl.

Modelo não encontrado / ID de modelo errado

API Error: 404 — model not found

Causa comum: usar um ID de modelo legado. Os IDs corretos a partir do V4 são:

• deepseek-v4-pro[1m] — não deepseek-chat, não deepseek-v4-0424
• deepseek-v4-flash — não deepseek-reasoner

Os aliases legados deepseek-chat e deepseek-reasoner serão descontinuados após 24 de julho de 2026. Atualize os IDs de modelo agora.

Custo e trade-offs vs. Claude Code nativo da Anthropic

Comparação de preço por token

Em maio de 2026, o DeepSeek V4 Pro está rodando com desconto promocional por tempo limitado. Nas tarifas padrão, os tokens de input do V4 Pro custam uma fração do que custam os tokens de input do Claude Opus 4.7 — a proporção foi citada por várias fontes como sendo em torno de 10–15× mais barato por milhão de tokens de input. O V4 Flash é mais barato ainda.

Essas são as tarifas no momento desta escrita; verifique na página de preços da DeepSeek antes de confiar nelas pra planejamento de orçamento. A tarifa promocional expira em 31 de maio de 2026 às 15:59 UTC.

Gaps de capacidade a esperar

O que funciona bem: navegação de código multi-arquivo, tarefas de implementação, sessões de debug, a maior parte da mecânica do workflow do Claude Code.

O que é mais fraco vs. Claude Opus 4.7: raciocínio arquitetural complexo, consistência no seguimento de instruções em sessões longas, e casos de borda no comportamento do tool loop do Claude Code (algumas tool calls que o Claude lida graciosamente podem produzir erros ou outputs inesperados pelo endpoint proxy).

O que está completamente ausente: /ultrareview, task budgets, xhigh effort, assinatura nativa de Skills da Anthropic, e qualquer feature do Claude Code que depende da infraestrutura de backend da Anthropic em vez da API do modelo.

Segurança: o que acontece com seu código

Esta seção não é leitura opcional. Quando você usa essa configuração, seu código, prompts e outputs de tool calls transitam pela infraestrutura de API da DeepSeek — não pela da Anthropic.

Pra código open-source, pessoal ou de baixa sensibilidade: o perfil de risco é similar a usar qualquer API de modelo em nuvem. Termos de API padrão e políticas de tratamento de dados se aplicam.

Pra código empresarial ou proprietário: seu código passa pelos servidores da DeepSeek. A DeepSeek é uma empresa chinesa operando sob lei chinesa. Dependendo dos requisitos de tratamento de dados da sua organização, isso pode violar políticas de residência de dados, acordos de emprego ou obrigações de confidencialidade com clientes. Antes de usar essa configuração em um projeto profissional, verifique com seu time jurídico ou de compliance.

Pra qualquer código de produção contendo credenciais, chaves privadas ou PII: não use essa configuração. Incluir acidentalmente esses dados em um prompt ou em um arquivo que o agente lê os envia pra fora dos acordos de tratamento de dados da Anthropic.

Isso não é uma crítica à postura de segurança da DeepSeek — é um fato estrutural sobre o que acontece quando você roteia seu código pra qualquer endpoint fora da Anthropic.

FAQ

Essa é uma configuração oficialmente suportada?

Não. A DeepSeek documenta; a Anthropic tolera. Nenhuma das duas empresas oferece suporte pra problemas que surjam dessa configuração. Se atualizações do Claude Code quebrarem a integração, você fica aguardando a DeepSeek atualizar a camada de compatibilidade ou workarounds documentados pela comunidade.

Eu perco as skills do Claude Code / CLAUDE.md?

Você mantém CLAUDE.md e AGENTS.md — eles são lidos no início da sessão independentemente do backend do modelo. Você perde features específicas da Anthropic: assinatura de skills, /ultrareview, task budgets, e as features de Routines que fazem callback pra infraestrutura da Anthropic. Servidores MCP configurados nas suas configurações do Claude Code continuam funcionando.

Posso voltar pra modelos da Anthropic por sessão?

Sim. Remova as variáveis de ambiente ou inicie uma nova sessão sem as variáveis de ambiente da DeepSeek. Se você usou um arquivo settings.json, renomeie-o ou mova-o. O Claude Code vai voltar ao modelo padrão da Anthropic pra aquela sessão.

É seguro enviar código proprietário pra API da DeepSeek?

Depende da sua definição de "seguro" e dos requisitos da sua organização. Leia a seção de Segurança acima. Pra código pessoal ou open-source: geralmente tudo bem. Pra código empresarial confidencial: verifique com seu time de compliance antes de usar.

O context caching funciona por esse proxy?

Sim. O endpoint /anthropic da DeepSeek suporta prompt caching. Conteúdo repetido no início do seu contexto (system prompt, conteúdo de arquivo estável) é cacheado e cobrado à tarifa de cached input da DeepSeek — aproximadamente 10% da tarifa completa de token de input.

Conclusão

Comprometa-se com essa configuração quando: você está pagando tarifas de API pra uso de alto volume do Claude Code e quer reduzir custos em tarefas onde a qualidade do DeepSeek V4-Pro é suficiente, você tem infraestrutura de CLAUDE.md e MCP que não quer reconstruir, e você está trabalhando com código que é adequado rotear pela API da DeepSeek.

Fique com a Anthropic nativa quando: você precisa de /ultrareview, task budgets ou xhigh reasoning effort, você precisa das garantias de tratamento de dados da Anthropic pra seu código, ou você é um usuário de assinatura do Claude Code (Pro/Max) onde a integração não se aplica ao seu modelo de billing.

Use o DeepSeek-TUI diretamente quando: você quer RLM parallel sub-agents, tooling nativo do DeepSeek V4, ou a TUI Rust-native sem o overhead do Claude Code.