| |

6 razões pelas quais o Claude Code utiliza o modo compatível com OpenAI em vez de /v1/messages (Guia completo de solução de problemas da versão NPM)

ByAPIYI - Stable and affordable AI API

Nota do autor: A instalação do Claude Code via NPM deveria utilizar o endpoint nativo /v1/messages, mas as requisições estão indo para /v1/chat/completions? Analisamos aqui 6 causas prováveis com base no mecanismo oficial, apresentamos um plano de diagnóstico rápido de 5 etapas e um exemplo de configuração correta para integração com a APIYI.

De acordo com a documentação oficial, o @anthropic-ai/claude-code instalado via NPM deve sempre enviar requisições para o endpoint /v1/messages em ambientes de linha de comando — este é o protocolo nativo da Messages API da Anthropic, que inclui o cabeçalho anthropic-version e o formato nativo de messages.

No entanto, se o seu cliente capturar pacotes e visualizar /v1/chat/completions (formato OpenAI Chat Completions), isso indica que houve uma conversão de protocolo ou confusão de pacotes em algum ponto. Isso não é um bug do próprio Claude Code, mas sim um dos 6 tipos de problemas comuns de configuração ou ambiente.

Valor central: Este artigo analisa exaustivamente essas 6 causas (incluindo instalação incorreta de pacotes de terceiros, ANTHROPIC_BASE_URL apontando para um gateway de compatibilidade, interceptação pelo claude-code-router, etc.), fornece um plano de diagnóstico rápido de 5 etapas e apresenta a configuração correta para garantir o uso do /v1/messages nativo ao integrar com a APIYI (apiyi.com).

claude-code-openai-compatible-mode-instead-of-v1-messages-pt-pt 图示

I. O Claude Code deve usar o /v1/messages por padrão: Entendendo o mecanismo central

Antes de começar a investigar, vamos esclarecer o comportamento esperado do Claude Code oficial para identificar onde está o problema.

1.1 O design de protocolo do @anthropic-ai/claude-code oficial

O pacote NPM @anthropic-ai/claude-code, mantido oficialmente pela Anthropic, utiliza apenas o protocolo nativo Messages API da Anthropic em todas as suas versões, com as seguintes características:

Dimensão Comportamento do Claude Code oficial
Endpoint de requisição POST {ANTHROPIC_BASE_URL}/v1/messages
Cabeçalhos x-api-key, anthropic-version: 2023-06-01, anthropic-beta
Formato do corpo { "model": "...", "messages": [...], "system": "...", "max_tokens": ... }
Formato da resposta { "content": [...], "stop_reason": "...", "usage": {...} }
Resposta em streaming Fluxo de eventos SSE, tipos como message_start, content_block_delta

Se o seu cliente capturar pacotes e visualizar /v1/chat/completions, Authorization: Bearer ... ou um corpo de requisição contendo um array choices, estas são características do protocolo OpenAI. Isso indica que a requisição não está seguindo o caminho esperado do Claude Code oficial.

1.2 A semântica correta das variáveis de ambiente chave

O Claude Code oficial reconhece apenas as seguintes variáveis de ambiente para ajustar o comportamento da API:

# Obrigatório: Chave API da Anthropic ou chave de serviço compatível
ANTHROPIC_AUTH_TOKEN=sk-your-key
# Ou variável sinônima:
ANTHROPIC_API_KEY=sk-your-key

# Opcional: URL do gateway de API personalizado (não inclua o sufixo /v1)
ANTHROPIC_BASE_URL=https://api.anthropic.com

# Opcional: ID do modelo personalizado
ANTHROPIC_MODEL=claude-sonnet-4-5
ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-5

Atenção: O Claude Code oficial não utiliza variáveis como OPENAI_BASE_URL ou CLAUDE_CODE_USE_OPENAI. Se esses nomes de variáveis aparecerem no seu ambiente, significa que um wrapper de terceiros está sendo utilizado.

💡 Dica de verificação rápida: Execute which claude no terminal para verificar o caminho de instalação do Claude Code e, em seguida, execute cat $(which claude) | head -20. Se você vir o termo @anthropic-ai/claude-code, significa que a versão oficial está instalada. Se vir palavras-chave como openclaude, claudex ou cli-agent-openai-adapter, você encontrou a causa raiz.

二、6 possíveis motivos para o Claude Code usar o modo de compatibilidade com OpenAI

Listados por ordem de probabilidade, recomendamos que você verifique nesta sequência.

2.1 Motivo 1: Instalação acidental de pacotes "OpenAI Wrapper" de terceiros (aprox. 35% dos casos)

Existem vários pacotes no NPM com nomes semelhantes, mas com funções completamente diferentes do "Claude Code", criados especificamente para conversão de compatibilidade com OpenAI. O usuário pode ter instalado um deles por engano:

Nome do Pacote Função Real Protocolo Padrão
@anthropic-ai/claude-code ✅ Pacote Oficial /v1/messages
@gitlawb/openclaude Shim da OpenAI /v1/chat/completions
@aryanjsx/openclaude Shim da OpenAI /v1/chat/completions
cli-agent-openai-adapter Conversor de protocolo /v1/chat/completions
claude-code-openai-wrapper Wrapper de protocolo duplo Suporta ambos
claudex Proxy OpenAI escrito em Go /v1/chat/completions

Como verificar:

# 1. Verifique o caminho de instalação real
which claude
# Exemplo de saída: /usr/local/bin/claude

# 2. Verifique o nome no package.json do pacote
cat $(npm root -g)/@anthropic-ai/claude-code/package.json 2>/dev/null | grep '"name"'

# 3. Liste todos os pacotes relacionados ao claude instalados globalmente
npm list -g --depth=0 | grep -i claude

Se o npm list não mostrar @anthropic-ai/claude-code, mas exibir outros pacotes com nomes similares, você instalou o pacote errado.

2.2 Motivo 2: Uso de ferramentas de roteamento como claude-code-router (aprox. 25% dos casos)

O claude-code-router (CCR) é uma ferramenta popular da comunidade, feita para interceptar requisições do Claude Code e encaminhá-las para diferentes modelos (como OpenAI, DeepSeek, Zhipu). Seu funcionamento:

  1. Inicia um servidor proxy local (padrão http://localhost:3456)
  2. O usuário aponta ANTHROPIC_BASE_URL para esse proxy local
  3. O CCR recebe a requisição /v1/messages e a traduz para /v1/chat/completions antes de encaminhar ao modelo alvo
  4. Ao capturar o tráfego, o que se vê é o protocolo da OpenAI

Como verificar:

# Verifique as variáveis de ambiente
env | grep -i ANTHROPIC

# Se vir algo como ANTHROPIC_BASE_URL=http://localhost:3456 ou http://127.0.0.1:xxx
# É muito provável que seja o CCR / claude-code-router ou proxy local similar

2.3 Motivo 3: ANTHROPIC_BASE_URL apontando para um gateway compatível com OpenAI (aprox. 20% dos casos)

Alguns gateways de LLM (como LiteLLM Proxy, OneAPI, Bifrost), embora permitam configurar modelos Anthropic, exibem apenas a interface /v1/chat/completions. Se o usuário apontar a ANTHROPIC_BASE_URL para um desses gateways:

  • O Claude Code continua enviando requisições como /v1/messages
  • O gateway retorna 404 ou reescreve o caminho automaticamente
  • O gateway converte internamente para o formato OpenAI para chamar o upstream
  • Se a ferramenta de captura de pacotes estiver implantada após o gateway, você verá o protocolo da OpenAI

Como verificar: Verifique se a ANTHROPIC_BASE_URL é um endereço de gateway compatível com OpenAI conhecido e se a requisição é bem-sucedida (200 ou 404).

2.4 Motivo 4: Variáveis de ambiente de wrappers de terceiros configuradas (aprox. 10% dos casos)

Alguns pacotes wrapper alternam o modo de protocolo via variáveis de ambiente, por exemplo:

# Variável de alternância do openclaude
CLAUDE_CODE_USE_OPENAI=1
OPENAI_API_KEY=sk-xxx
OPENAI_MODEL=gpt-4o
OPENAI_BASE_URL=https://api.openai.com/v1

Mesmo que você tenha instalado o pacote oficial via npm, se houver um script wrapper no seu PATH (ex: /usr/local/bin/claude sendo um wrapper), essas variáveis entrarão em vigor.

Como verificar:

# Liste todos os executáveis chamados claude no PATH
type -a claude

# Verifique se existem variáveis de ambiente relacionadas
env | grep -E 'CLAUDE_CODE|OPENAI_BASE_URL|OPENAI_MODEL'

2.5 Motivo 5: Alias do Shell ou script wrapper interceptando (aprox. 7% dos casos)

O usuário pode ter configurado um alias no ~/.bashrc ou ~/.zshrc:

# Esse tipo de alias substitui o comando original claude
alias claude='openclaude'
alias claude='claude-code-router run'

# Ou definiu uma função com o mesmo nome
claude() {
  CCR_PROXY=http://localhost:3456 command claude "$@"
}

Como verificar:

# Verifique aliases
alias | grep claude

# Verifique funções
type claude

# Verifique os arquivos de inicialização do shell
grep -nE 'claude' ~/.bashrc ~/.zshrc ~/.profile 2>/dev/null

2.6 Motivo 6: Julgamento incorreto pela perspectiva da captura de pacotes (aprox. 3% dos casos)

Em poucos casos, a ferramenta de captura está implantada no local errado, e as requisições vistas não são as que o Claude Code realmente enviou. Exemplo:

  • Claude Code → Proxy transparente local (ex: mitmproxy) → Gateway remoto da OpenAI
  • A ferramenta de captura está após o gateway, vendo a requisição reescrita pelo gateway
  • Na verdade, o Claude Code enviou /v1/messages

Como verificar: Use o mitmproxy localmente na máquina do usuário para interceptar diretamente o processo do Claude Code e confirmar qual protocolo a primeira requisição utiliza.

Três: Diagnóstico rápido em 5 passos para anomalias de protocolo no Claude Code

claude-code-openai-compatible-mode-instead-of-v1-messages-pt-pt 图示

Siga esta ordem e a maioria das anomalias de protocolo será resolvida nos 3 primeiros passos.

3.1 Passo 1: Confirme se o pacote NPM oficial está instalado

# Desinstale todos os possíveis wrappers
npm uninstall -g @gitlawb/openclaude @aryanjsx/openclaude cli-agent-openai-adapter claudex claude-code-router 2>/dev/null

# Desinstale e reinstale o pacote oficial
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

# Verifique a origem da versão
claude --version
npm list -g @anthropic-ai/claude-code

Critério de aprovação: A saída do npm list -g contém @anthropic-ai/[email protected].

3.2 Passo 2: Limpe o PATH e os aliases do Shell

# Encontre todos os executáveis chamados claude no PATH
type -a claude
which -a claude

# Remova aliases / funções com o mesmo nome
unalias claude 2>/dev/null
unset -f claude 2>/dev/null

# Verifique e limpe configurações relacionadas ao claude nos scripts de inicialização do shell
grep -n 'claude' ~/.bashrc ~/.zshrc ~/.profile 2>/dev/null

Critério de aprovação: type -a claude retorna apenas um caminho, apontando para o pacote oficial no diretório global do npm.

3.3 Passo 3: Limpe variáveis de ambiente conflitantes

# Veja todas as variáveis relacionadas a claude / openai
env | grep -iE 'claude|openai|anthropic'

# Limpe variáveis que podem causar conflito
unset CLAUDE_CODE_USE_OPENAI
unset OPENAI_BASE_URL
unset OPENAI_MODEL
unset CCR_PROXY

# Mantenha apenas as variáveis necessárias para o pacote oficial
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="sk-sua-chave-apiyi"

🎯 Lembrete importante: A ANTHROPIC_BASE_URL deve ser preenchida com a raiz do domínio (sem o sufixo /v1), pois o Claude Code adiciona automaticamente /v1/messages. Se você colocar https://vip.apiyi.com/v1, ele tentará acessar https://vip.apiyi.com/v1/v1/messages, resultando em 404.

3.4 Passo 4: Teste se a base_url suporta nativamente /v1/messages

Use o curl para simular a requisição do Claude Code e verificar se o gateway realmente suporta o protocolo nativo da Anthropic:

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Critério de aprovação: Retorna 200, e o corpo da resposta contém "type": "message" e "content": [...].

Se retornar 404 ou se o corpo da resposta estiver no formato OpenAI (contendo choices), significa que o gateway apontado pela ANTHROPIC_BASE_URL não suporta o protocolo nativo da Anthropic. Nesse caso, mudar para a APIYI (apiiyi.com) resolverá o problema imediatamente — ela suporta nativamente /v1/messages e é compatível com /v1/chat/completions, funcionando com ambos os protocolos.

3.5 Passo 5: Verificação final via captura de pacotes local

Se os 4 passos anteriores foram concluídos e o problema persiste, use o mitmproxy para capturar o tráfego localmente:

# Inicie o mitmproxy (porta padrão 8080)
mitmproxy --listen-port 8080

# Faça o Claude Code passar pelo proxy local
export HTTPS_PROXY=http://localhost:8080
export HTTP_PROXY=http://localhost:8080

# Inicie o Claude Code
claude

Critério de aprovação: A primeira requisição capturada pelo mitmproxy é POST /v1/messages e o cabeçalho da requisição contém anthropic-version.

Quatro. Configuração completa para conectar o Claude Code ao APIYI via protocolo nativo /v1/messages

O APIYI (apiyi.com) é um dos poucos serviços proxy de API que suporta nativamente o protocolo Anthropic Messages API, garantindo que o Claude Code utilize o endpoint /v1/messages em vez do /v1/chat/completions.

4.1 Configuração de variáveis de ambiente (método mais simples)

# macOS / Linux
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-apiyi-key"
# Opcional: especificar o modelo padrão
export ANTHROPIC_MODEL="claude-sonnet-4-5"
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4-5"

# Windows PowerShell
$env:ANTHROPIC_BASE_URL = "https://vip.apiyi.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-your-apiyi-key"

# Iniciar o Claude Code
claude

4.2 Configuração persistente no arquivo de inicialização do Shell

# Adicionar ao ~/.zshrc ou ~/.bashrc
cat >> ~/.zshrc <<'EOF'

# Configuração do proxy APIYI para o Claude Code
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-apiyi-key"
export ANTHROPIC_MODEL="claude-sonnet-4-5"
EOF

# Recarregar as configurações
source ~/.zshrc

4.3 Via comando de configuração interno do Claude Code (recomendado)

O próprio Claude Code oferece um CLI de configuração para evitar o vazamento de variáveis de ambiente:

# Método 1: Interativo
claude /login
# Selecione "Custom Endpoint", insira https://vip.apiyi.com e sua chave API

# Método 2: Modificar diretamente o arquivo de configuração
cat > ~/.claude/settings.json <<'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://vip.apiyi.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-apiyi-key"
  }
}
EOF

4.4 Verificar o caminho da requisição após a configuração

Após iniciar o Claude Code, abra um novo terminal e use um dos comandos abaixo para validar:

# Método 1: Captura de pacotes com mitmproxy (mais preciso)
mitmproxy --listen-port 8080
# Ao iniciar o Claude Code em outro terminal, defina HTTPS_PROXY=http://localhost:8080

# Método 2: Ativar logs de depuração do Claude Code
ANTHROPIC_LOG=debug claude
# O log exibirá a URL completa da requisição e o método utilizado

Resultado esperado: Todas as URLs de requisição devem ser https://vip.apiyi.com/v1/messages, com método POST e o cabeçalho anthropic-version: 2023-06-01.

4.5 Principais vantagens do APIYI

Vantagem Descrição
Suporte nativo a /v1/messages Protocolo padrão do Claude Code, sem perda de conversão
Suporte simultâneo a /v1/chat/completions Uma chave para dois protocolos, adaptação flexível
Preservação total do cabeçalho anthropic-beta Suporta recursos avançados como prompt caching e uso de ferramentas
Sem limite de concorrência Sem estrangulamento em sessões longas do Claude Code
Bônus de 10% em recargas de 100 USD Equivalente a 15% de desconto em relação ao site oficial
Recarga em Reais (BRL) Pagamento direto via Pix/QR Code

Cinco. Comparação de protocolos: Nativo /v1/messages vs OpenAI /v1/chat/completions

claude-code-openai-compatible-mode-instead-of-v1-messages-pt-pt 图示

Entender as diferenças fundamentais entre os dois protocolos é essencial para compreender por que o Claude Code precisa do protocolo nativo para liberar todo o seu potencial.

Dimensão Anthropic /v1/messages OpenAI /v1/chat/completions
Cabeçalho de autenticação x-api-key: sk-... Authorization: Bearer sk-...
Cabeçalho de versão anthropic-version: 2023-06-01 Nenhum (usa versão na URL)
Cabeçalho de recursos anthropic-beta: prompt-caching-... Sem padrão unificado
Campo system Campo independente no nível superior Como system role em messages[0]
Formato de resposta { "content": [...], "stop_reason": "..." } { "choices": [{ "message": {...} }] }
Eventos de streaming Eventos estruturados (message_start, content_block_delta, etc.) data: {...} (SSE genérico)
Chamada de ferramentas tool_use incorporado em blocos de conteúdo choices[0].message.tool_calls
Contagem de tokens usage.input_tokens / usage.output_tokens usage.prompt_tokens / usage.completion_tokens

Conclusão fundamental: O Claude Code utiliza extensivamente recursos exclusivos da Anthropic (prompt caching, incremento de streaming de tool_use, conteúdo de raciocínio, etc.). Se for forçado a converter para o protocolo OpenAI, perderá essas capacidades ou apresentará comportamentos inconsistentes. É por isso que garantir o uso do /v1/messages nativo é indispensável.

6. Lista de verificação para solução de problemas por cenário

6.1 Cenário 1: Uso local por desenvolvedores individuais

Causa mais comum: Alias no Shell ou um wrapper com o mesmo nome no PATH.

Lista de verificação:

  • npm list -g contém @anthropic-ai/claude-code?
  • type -a claude aponta apenas para o pacote oficial?
  • ~/.zshrc / ~/.bashrc possuem algum alias claude=...?
  • env | grep -i claude mostra alguma variável não padrão?
  • ANTHROPIC_BASE_URL foi preenchida com o sufixo /v1? (Não deve conter).

6.2 Cenário 2: Implantação em ambiente de equipe/empresa

Causa mais comum: O gateway de Modelo de Linguagem Grande interno suporta apenas o protocolo OpenAI.

Lista de verificação:

  • O gateway da empresa suporta nativamente o endpoint /v1/messages?
  • O gateway encaminha os cabeçalhos de requisição anthropic-version e anthropic-beta?
  • O gateway preserva o formato original dos eventos SSE?
  • Existe algum script wrapper unificado da equipe?

Se o gateway da empresa realmente suportar apenas o protocolo OpenAI, recomendamos alterar a ANTHROPIC_BASE_URL do cliente para apontar para o APIYI (apiyi.com). Isso permite o uso direto do protocolo nativo, evitando perdas na conversão.

6.3 Cenário 3: Invocação do Claude Code em ambiente CI/CD

Causa mais comum: Scripts de CI com wrappers de terceiros fixados.

Lista de verificação:

  • O arquivo de configuração do CI executa npm install -g de um pacote não oficial?
  • As variáveis de ambiente do CI contêm CLAUDE_CODE_USE_OPENAI=1 ou similar?
  • A imagem do runner de CI possui um wrapper pré-instalado?

6.4 Cenário 4: Execução dentro de um contêiner Docker

Causa mais comum: A imagem base possui um wrapper pré-instalado.

Lista de verificação:

  • O nome do pacote no RUN npm install -g do Dockerfile é o oficial?
  • Para onde aponta o which claude dentro do contêiner?
  • As variáveis de ambiente (ENV) do contêiner definiram alguma variável de troca de protocolo?

7. FAQ: Problemas comuns de protocolo no Claude Code

Q1: Instalei o pacote oficial @anthropic-ai/claude-code, por que ele ainda usa o protocolo OpenAI?

A causa mais provável é que a ANTHROPIC_BASE_URL esteja apontando para um gateway compatível com OpenAI. Alguns gateways, ao receberem uma requisição /v1/messages, convertem-na internamente para /v1/chat/completions antes de chamar o upstream. Se sua ferramenta de captura de pacotes estiver implantada após o gateway, você verá o protocolo convertido.

A solução é alterar a ANTHROPIC_BASE_URL para apontar para o APIYI (apiyi.com), que suporta nativamente o /v1/messages sem qualquer perda por conversão.

Q2: Como desinstalar completamente todos os possíveis wrappers do Claude?

# Listar todos os pacotes globais relacionados ao claude
npm list -g --depth=0 | grep -i claude

# Desinstalar de uma vez os wrappers conhecidos
npm uninstall -g \
  @gitlawb/openclaude \
  @aryanjsx/openclaude \
  cli-agent-openai-adapter \
  claudex \
  claude-code-router \
  ccr \
  2>/dev/null

# Reinstalar o pacote oficial
npm install -g @anthropic-ai/claude-code

# Verificar
which claude
claude --version

Q3: Até que nível de caminho devo preencher a ANTHROPIC_BASE_URL?

Preencha até a raiz do domínio, sem o sufixo /v1. O Claude Code concatenará automaticamente o /v1/messages internamente.

# ✅ Correto
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"

# ❌ Errado (resultaria em /v1/v1/messages)
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1"

# ❌ Errado (com o caminho do endpoint incluído)
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1/messages"

Q4: Por que alguns tutoriais pedem para instalar o claude-code-router?

O claude-code-router é uma ferramenta da comunidade cujo objetivo principal é permitir que o Claude Code invoque modelos que não são da Anthropic (como DeepSeek, Zhipu, Ollama local, etc.). Isso é feito através da conversão de protocolos.

Se você deseja apenas usar os modelos Claude originais da Anthropic (como Claude Sonnet 4.5, Opus 4.7), não precisa do CCR. Basta conectar-se ao APIYI (apiyi.com) usando o /v1/messages nativo para ter uma experiência melhor e sem perdas de conversão.

Q5: O APIYI (apiyi.com) suporta simultaneamente /v1/messages e /v1/chat/completions?

Sim, o APIYI é totalmente compatível com ambos os protocolos:

  • https://vip.apiyi.com/v1/messages — Formato nativo da Anthropic (padrão do Claude Code)
  • https://vip.apiyi.com/v1/chat/completions — Formato compatível com OpenAI

Uma única chave API pode usar ambos os protocolos, adaptando-se automaticamente de acordo com a ferramenta cliente.

Q6: Se a URL capturada for https://vip.apiyi.com/v1/messages, isso significa que está em modo nativo?

Não necessariamente. É preciso verificar também:

  1. Se o cabeçalho da requisição contém anthropic-version: 2023-06-01.
  2. Se o corpo da requisição possui um array messages no nível superior e um campo system independente (não dentro do array de mensagens).
  3. Se o corpo da resposta contém "type": "message" e content: [...] (em vez de choices: [...]).

Se a URL for /v1/messages, mas o corpo da requisição estiver no formato OpenAI (com o system role dentro das mensagens), isso indica que o cliente possui sua própria camada de conversão.

Q7: Qual é a variável de ambiente para ativar os logs de depuração do Claude Code?

# Exibir logs detalhados de requisição/resposta HTTP
ANTHROPIC_LOG=debug claude

# Ou usar o modo verbose
claude --verbose

# Verificar as informações de diagnóstico do próprio Claude Code
claude /doctor

Os logs de depuração mostrarão a URL completa, cabeçalhos e corpo da requisição (campos sensíveis serão mascarados), sendo a forma mais direta de localizar problemas de protocolo.

Q8: Meu Claude Code funcionava normalmente e, de repente, passou a usar o protocolo OpenAI. O que pode ter acontecido?

As causas mais comuns para essa mudança repentina são:

  • Atualização do Claude Code, mas com instalação acidental de um pacote de terceiros com o mesmo nome via npm install -g.
  • A equipe implantou recentemente um gateway de Modelo de Linguagem Grande e definiu uma nova ANTHROPIC_BASE_URL.
  • Algum alias foi reativado após uma atualização do macOS.
  • A empresa ativou um proxy transparente para auditoria de conversão de protocolo.

Ao investigar, verifique as mudanças recentes no ambiente (histórico de instalação do npm, alterações na configuração do shell, avisos de mudança no gateway).

VIII. Principais pontos (Key Takeaways)

  • ✅ O oficial @anthropic-ai/claude-code usa sempre /v1/messages, não existe um modo de compatibilidade oficial com OpenAI.
  • ✅ 6 causas prováveis (por probabilidade): instalação incorreta de pacotes de terceiros / interceptação pelo claude-code-router / base_url apontando para um gateway da OpenAI / variáveis de ambiente de terceiros / alias de Shell / erro de interpretação na captura de pacotes.
  • ✅ 5 passos para diagnóstico rápido: confirmar nome do pacote → limpar PATH/alias → limpar variáveis de ambiente → teste curl na base_url → validar com captura de pacotes local.
  • ✅ Não inclua o sufixo /v1 na ANTHROPIC_BASE_URL, o Claude Code fará a concatenação automaticamente.
  • ✅ O APIYI (apiyi.com) oferece suporte nativo a /v1/messages e também é compatível com /v1/chat/completions; uma única chave para dois protocolos.
  • ✅ Vantagens de usar o protocolo nativo: suporte completo a prompt caching, tool_use, reasoning content e outros recursos exclusivos da Anthropic.
  • ✅ Método de verificação rápida: use ANTHROPIC_LOG=debug claude para visualizar a URL e o método da requisição real.

IX. Conclusão

O Claude Code instalado via NPM deve sempre utilizar o protocolo nativo /v1/messages no ambiente de linha de comando — este é um comportamento codificado no pacote oficial @anthropic-ai/claude-code, e não há chaves oficiais para alternar para o modo de compatibilidade da OpenAI. Se, ao capturar os pacotes, o cliente observar o uso de /v1/chat/completions, o problema certamente está em algum ponto do ambiente do cliente: ou um wrapper de terceiros foi instalado por engano, ou a ANTHROPIC_BASE_URL está apontando para um gateway que suporta apenas o protocolo da OpenAI, ou um alias de Shell/variável de ambiente está realizando uma conversão de interceptação.

Seguindo o fluxo de diagnóstico de 5 passos descrito no terceiro capítulo deste artigo, a grande maioria dos problemas pode ser localizada em menos de 10 minutos. A solução mais comum é: desinstalar todos os pacotes não oficiais → reinstalar o @anthropic-ai/claude-code → apontar a ANTHROPIC_BASE_URL para um serviço proxy de API que suporte nativamente o /v1/messages.

O APIYI (apiyi.com) foi projetado para este cenário — oferece suporte nativo à API de Mensagens da Anthropic (incluindo a passagem completa dos cabeçalhos anthropic-version e anthropic-beta), ao mesmo tempo em que é compatível com o Chat Completions da OpenAI (protocolo duplo com uma única chave), sem limite de concorrência (evitando restrições em sessões longas do Claude Code), com bônus de 10% em recargas a partir de 100 dólares (equivalente a 15% de desconto em relação ao site oficial) e pagamento em moeda local (via WeChat/Alipay). Para configurar, basta definir a ANTHROPIC_BASE_URL como https://vip.apiyi.com, sem necessidade de qualquer alteração no código.

🎯 Sugestão de próximo passo: peça ao cliente para seguir a ordem de verificação 3.1 → 3.2 → 3.3 deste artigo, altere a ANTHROPIC_BASE_URL para https://vip.apiyi.com e, após reiniciar o Claude Code, utilize ANTHROPIC_LOG=debug claude para verificar se a URL da requisição retornou para /v1/messages.

Referências

  1. Documentação oficial do Claude Code: Instruções de configuração do LLM Gateway

    • Link: code.claude.com/docs/en/llm-gateway
    • Descrição: A documentação oficial especifica claramente que o Claude Code utiliza o formato da API Messages da Anthropic.

  2. Pacote NPM @anthropic-ai/claude-code: Página oficial do pacote NPM

    • Link: npmjs.com/package/@anthropic-ai/claude-code
    • Descrição: Verifique se você instalou o pacote oficial.

  3. Documentação oficial da API Messages da Anthropic: Especificação do protocolo nativo

    • Link: docs.anthropic.com/en/api/messages
    • Descrição: Campos completos, cabeçalhos de solicitação e formato de resposta do endpoint /v1/messages.

  4. Site oficial da APIYI: Serviço proxy de API com protocolo nativo da Anthropic

    • Link: apiyi.com
    • Descrição: Suporte nativo para /v1/messages + compatibilidade com /v1/chat/completions, sem limite de concorrência e 10% de bônus em recargas de 100 dólares.

Autor: Equipe Técnica
Última atualização: 02/05/2026
Sobre a APIYI: A APIYI (apiyi.com) é um provedor profissional de serviço proxy de API para o Claude, com suporte nativo à API Messages da Anthropic (/v1/messages, incluindo passagem completa de anthropic-version e anthropic-beta), sendo também compatível com OpenAI Chat Completions (/v1/chat/completions). Oferecemos acesso estável a toda a linha Claude Sonnet 4.5, Claude Opus 4.7 e Claude Haiku 4.5, com 10% de bônus em recargas de 100 dólares (equivalente a 15% de desconto em relação ao site oficial), sem limite de concorrência e com suporte técnico ágil.

Try AI Large Model https://api.apiyi.com for free
Stable and reliable AI LM API aggregation service, Get 300 Millions Tokens for Free~

Similar Posts