| |

6 razones por las que Claude Code utiliza el modo compatible con OpenAI en lugar de /v1/messages (Guía completa de solución de problemas para la versión NPM)

PorAPIYI - Stable and affordable AI API

一、Claude Code 默认应该走 /v1/messages：核心机制解读

En primer lugar, antes de empezar a diagnosticar, debemos tener claro cuál es el comportamiento esperado de Claude Code para identificar dónde está el fallo.

1.1 Diseño del protocolo de @anthropic-ai/claude-code

El paquete NPM oficial @anthropic-ai/claude-code mantenido por Anthropic utiliza exclusivamente el protocolo nativo Messages API de Anthropic. Sus características son:

Dimensión Comportamiento oficial de Claude Code
Endpoint de solicitud POST {ANTHROPIC_BASE_URL}/v1/messages
Cabeceras x-api-key, anthropic-version: 2023-06-01, anthropic-beta
Formato del cuerpo { "model": "...", "messages": [...], "system": "...", "max_tokens": ... }
Formato de respuesta { "content": [...], "stop_reason": "...", "usage": {...} }
Respuesta en streaming Flujo de eventos SSE, con tipos como message_start, content_block_delta

Si al capturar el tráfico ves /v1/chat/completions, Authorization: Bearer ... o un cuerpo de solicitud que contiene un array choices, estás ante características del protocolo de OpenAI. Esto indica que la solicitud no está siguiendo la ruta que debería tomar el Claude Code oficial.

1.2 Semántica correcta de las variables de entorno clave

El Claude Code oficial solo reconoce las siguientes variables de entorno para ajustar el comportamiento de la API:

# Obligatorio: Clave API de Anthropic o clave de un servicio compatible
ANTHROPIC_AUTH_TOKEN=sk-tu-clave
# O la variable equivalente:
ANTHROPIC_API_KEY=sk-tu-clave

# Opcional: URL personalizada del servicio proxy de API (no incluir el sufijo /v1)
ANTHROPIC_BASE_URL=https://api.anthropic.com

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

Nota: El Claude Code oficial no utiliza variables como OPENAI_BASE_URL o CLAUDE_CODE_USE_OPENAI. Si estas variables aparecen en tu entorno, significa que estás utilizando un envoltorio (wrapper) de terceros.

💡 Consejo de verificación rápida: Ejecuta which claude en tu terminal para ver la ruta de instalación de Claude Code y luego ejecuta cat $(which claude) | head -20. Si ves la cadena @anthropic-ai/claude-code, significa que tienes instalada la versión oficial. Si ves palabras clave como openclaude, claudex o cli-agent-openai-adapter, ahí es donde reside la causa raíz.

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

二、6 posibles razones por las que Claude Code utiliza el modo compatible con OpenAI

Ordenadas de mayor a menor probabilidad, te recomendamos revisarlas en este orden.

2.1 Razón 1: Instalación accidental de paquetes "OpenAI Wrapper" de terceros (aprox. 35% de los casos)

En NPM existen varios paquetes con nombres similares a "Claude Code" pero con funciones totalmente distintas, diseñados específicamente para la compatibilidad con OpenAI. Es posible que hayas instalado uno de ellos por error:

Nombre del paquete Función real Protocolo predeterminado
@anthropic-ai/claude-code ✅ Paquete oficial /v1/messages
@gitlawb/openclaude Shim de OpenAI /v1/chat/completions
@aryanjsx/openclaude Shim de OpenAI /v1/chat/completions
cli-agent-openai-adapter Conversor de protocolo /v1/chat/completions
claude-code-openai-wrapper Wrapper de doble protocolo Soporta ambos
claudex Proxy de OpenAI en Go /v1/chat/completions

Método de diagnóstico:

# 1. Verificar la ruta de instalación real
which claude
# Ejemplo de salida: /usr/local/bin/claude

# 2. Verificar el "name" en el package.json del paquete
cat $(npm root -g)/@anthropic-ai/claude-code/package.json 2>/dev/null | grep '"name"'

# 3. Listar todos los paquetes relacionados con claude instalados globalmente
npm list -g --depth=0 | grep -i claude

Si npm list no muestra @anthropic-ai/claude-code pero sí otros paquetes con nombres similares, esa es la causa.

2.2 Razón 2: Uso de herramientas de enrutamiento como claude-code-router (aprox. 25% de los casos)

claude-code-router (CCR) es una herramienta comunitaria popular que intercepta las peticiones de Claude Code y las redirige a diferentes modelos (como OpenAI, DeepSeek o Zhipu). Su funcionamiento es:

  1. Inicia un servidor proxy local (por defecto http://localhost:3456).
  2. El usuario apunta ANTHROPIC_BASE_URL a este proxy local.
  3. CCR recibe la petición /v1/messages y la traduce a /v1/chat/completions para reenviarla al modelo objetivo.
  4. Al capturar el tráfico, verás el protocolo de OpenAI.

Método de diagnóstico:

# Comprobar variables de entorno
env | grep -i ANTHROPIC

# Si ves algo como ANTHROPIC_BASE_URL=http://localhost:3456 o http://127.0.0.1:xxx
# Es muy probable que sea un proxy local como CCR / claude-code-router

2.3 Razón 3: ANTHROPIC_BASE_URL apunta a una pasarela compatible con OpenAI (aprox. 20% de los casos)

Algunas pasarelas de LLM (como LiteLLM Proxy, OneAPI o Bifrost), aunque permiten configurar modelos de Anthropic, solo exponen la interfaz /v1/chat/completions. Si apuntas ANTHROPIC_BASE_URL a estas pasarelas:

  • Claude Code sigue enviando peticiones a /v1/messages.
  • La pasarela devuelve un 404 o reescribe la ruta automáticamente.
  • La pasarela convierte internamente la petición al formato de OpenAI.
  • Si capturas el tráfico después de la pasarela, verás el protocolo de OpenAI.

Método de diagnóstico: Comprueba si ANTHROPIC_BASE_URL es una pasarela conocida compatible con OpenAI y si la petición tiene éxito (200) o falla (404).

2.4 Razón 4: Variables de entorno de wrappers de terceros (aprox. 10% de los casos)

Algunos paquetes wrapper cambian el protocolo mediante variables de entorno, por ejemplo:

# Variables de cambio para openclaude
CLAUDE_CODE_USE_OPENAI=1
OPENAI_API_KEY=sk-xxx
OPENAI_MODEL=gpt-4o
OPENAI_BASE_URL=https://api.openai.com/v1

Incluso si instalaste el paquete oficial, si hay un script wrapper en tu PATH (por ejemplo, si /usr/local/bin/claude es en realidad un wrapper), estas variables surtirán efecto.

Método de diagnóstico:

# Listar todos los ejecutables llamados claude en el PATH
type -a claude

# Comprobar si existen variables de entorno relacionadas
env | grep -E 'CLAUDE_CODE|OPENAI_BASE_URL|OPENAI_MODEL'

2.5 Razón 5: Intercepción por alias de Shell o scripts wrapper (aprox. 7% de los casos)

Es posible que hayas configurado un alias en tu ~/.bashrc o ~/.zshrc:

# Este tipo de alias reemplaza el comando claude original
alias claude='openclaude'
alias claude='claude-code-router run'

# O una función definida con el mismo nombre
claude() {
  CCR_PROXY=http://localhost:3456 command claude "$@"
}

Método de diagnóstico:

# Ver alias
alias | grep claude

# Ver funciones
type claude

# Revisar archivos de inicio de shell
grep -nE 'claude' ~/.bashrc ~/.zshrc ~/.profile 2>/dev/null

2.6 Razón 6: Error de juicio en la captura de tráfico (aprox. 3% de los casos)

En casos aislados, la herramienta de captura está mal configurada y no muestra la petición real que envía Claude Code. Por ejemplo:

  • Claude Code → Proxy transparente local (ej. mitmproxy) → Pasarela remota de OpenAI.
  • Si capturas después de la pasarela, verás la petición reescrita.
  • En realidad, Claude Code envió /v1/messages.

Método de diagnóstico: Usa mitmproxy localmente para interceptar directamente el proceso de Claude Code y confirmar qué protocolo utiliza en el primer salto.

三、5 pasos para diagnosticar rápidamente anomalías en el protocolo de Claude Code

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

Sigue este orden y podrás localizar la mayoría de las anomalías en los primeros 3 pasos.

3.1 Paso 1: Confirmar la instalación del paquete NPM oficial

# Desinstalar todos los posibles wrappers
npm uninstall -g @gitlawb/openclaude @aryanjsx/openclaude cli-agent-openai-adapter claudex claude-code-router 2>/dev/null

# Desinstalar y reinstalar el paquete oficial
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

# Verificar la versión y origen
claude --version
npm list -g @anthropic-ai/claude-code

Condición de éxito: La salida de npm list -g incluye @anthropic-ai/[email protected].

3.2 Paso 2: Limpiar PATH y alias de Shell

# Encontrar todos los ejecutables llamados claude en el PATH
type -a claude
which -a claude

# Eliminar alias / funciones con el mismo nombre
unalias claude 2>/dev/null
unset -f claude 2>/dev/null

# Revisar y limpiar configuraciones relacionadas con claude en los scripts de inicio
grep -n 'claude' ~/.bashrc ~/.zshrc ~/.profile 2>/dev/null

Condición de éxito: type -a claude solo muestra una ruta, apuntando al paquete oficial en el directorio global de npm.

3.3 Paso 3: Limpiar variables de entorno conflictivas

# Ver todas las variables relacionadas con claude / openai
env | grep -iE 'claude|openai|anthropic'

# Limpiar variables que puedan causar conflictos
unset CLAUDE_CODE_USE_OPENAI
unset OPENAI_BASE_URL
unset OPENAI_MODEL
unset CCR_PROXY

# Mantener solo las variables necesarias para el paquete oficial
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="sk-tu-clave-apiyi"

🎯 Recordatorio clave: ANTHROPIC_BASE_URL debe apuntar a la raíz del dominio (sin el sufijo /v1), ya que Claude Code añadirá automáticamente /v1/messages. Si pones https://vip.apiyi.com/v1, se formará https://vip.apiyi.com/v1/v1/messages, lo que causará un error 404.

3.4 Paso 4: Probar si la base_url soporta nativamente /v1/messages

Usa curl para simular la petición de Claude Code y verificar si la pasarela realmente soporta el protocolo nativo de 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"}]
  }'

Condición de éxito: Recibir un código 200 y que el cuerpo de la respuesta contenga "type": "message" y "content": [...].

Si recibes un 404 o el formato de respuesta es de OpenAI (contiene choices), significa que la pasarela no soporta el protocolo nativo. En este caso, cambiar a APIYI (apiyi.com) resolverá el problema inmediatamente, ya que soporta nativamente /v1/messages y es compatible con /v1/chat/completions.

3.5 Paso 5: Verificación mediante captura de tráfico local

Si los pasos anteriores no han funcionado, utiliza mitmproxy para capturar el tráfico localmente:

# Iniciar mitmproxy (puerto 8080 por defecto)
mitmproxy --listen-port 8080

# Configurar Claude Code para usar el proxy local
export HTTPS_PROXY=http://localhost:8080
export HTTP_PROXY=http://localhost:8080

# Iniciar Claude Code
claude

Condición de éxito: La primera petición capturada por mitmproxy debe ser POST /v1/messages e incluir la cabecera anthropic-version.

IV. Configuración completa para conectar Claude Code a APIYI mediante el protocolo nativo /v1/messages

APIYI (apiyi.com) es uno de los pocos servicios proxy de API que soporta de forma nativa el protocolo Anthropic Messages API, lo que garantiza que Claude Code utilice /v1/messages en lugar de /v1/chat/completions.

4.1 Configuración de variables de entorno (la forma más sencilla)

# macOS / Linux
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-apiyi-key"
# Opcional: especificar el modelo por defecto
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 Claude Code
claude

4.2 Configuración persistente en el archivo de inicio del Shell

# Añadir a ~/.zshrc o ~/.bashrc
cat >> ~/.zshrc <<'EOF'

# Configuración del proxy de APIYI para 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

# Recargar configuración
source ~/.zshrc

4.3 Mediante el comando de configuración integrado de Claude Code (recomendado)

Claude Code ofrece su propia CLI de configuración para evitar la exposición de variables de entorno:

# Opción 1: Interactiva
claude /login
# Selecciona "Custom Endpoint", introduce https://vip.apiyi.com y tu clave API

# Opción 2: Modificar directamente el archivo de configuración
cat > ~/.claude/settings.json <<'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://vip.apiyi.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-apiyi-key"
  }
}
EOF

4.4 Verificar la ruta de solicitud tras la configuración

Después de iniciar Claude Code, abre una nueva terminal y utiliza uno de los siguientes comandos para verificar:

# Opción 1: Captura de paquetes con mitmproxy (la más precisa)
mitmproxy --listen-port 8080
# Al iniciar Claude Code en otra terminal, configura HTTPS_PROXY=http://localhost:8080

# Opción 2: Activar los registros de depuración de Claude Code
ANTHROPIC_LOG=debug claude
# Los registros mostrarán la URL de solicitud completa y el método

Resultado esperado: Todas las URLs de solicitud deben ser https://vip.apiyi.com/v1/messages, con método POST y la cabecera anthropic-version: 2023-06-01.

4.5 Ventajas clave de conectar con APIYI

Ventaja Descripción
Soporte nativo /v1/messages Protocolo predeterminado de Claude Code, sin pérdida de conversión
Soporte simultáneo /v1/chat/completions Una clave para ambos protocolos, adaptabilidad flexible
Preservación total de cabeceras anthropic-beta Soporta características avanzadas como prompt caching y uso de herramientas
Sin límite de concurrencia Sin estrangulamiento en sesiones largas de Claude Code
Recarga de 100 USD con 10% extra Equivalente a un 15% de descuento respecto a la web oficial
Pagos en moneda local (RMB) Pago directo mediante WeChat/Alipay

V. Comparativa de protocolos: Nativo /v1/messages vs OpenAI /v1/chat/completions

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

Entender las diferencias fundamentales entre ambos protocolos es crucial para comprender por qué Claude Code debe utilizar el protocolo nativo para desplegar todo su potencial.

Dimensión Anthropic /v1/messages OpenAI /v1/chat/completions
Cabecera de autenticación x-api-key: sk-... Authorization: Bearer sk-...
Cabecera de versión anthropic-version: 2023-06-01 Ninguna (usa versión en la URL)
Cabecera de características anthropic-beta: prompt-caching-... Sin estándar unificado
Campo system Campo independiente de nivel superior Como rol system en messages[0]
Formato de respuesta { "content": [...], "stop_reason": "..." } { "choices": [{ "message": {...} }] }
Eventos de streaming Eventos estructurados (message_start, content_block_delta, etc.) SSE genérico data: {...}
Invocación de herramientas tool_use incrustado en bloques de contenido choices[0].message.tool_calls
Conteo de tokens usage.input_tokens / usage.output_tokens usage.prompt_tokens / usage.completion_tokens

Conclusión clave: Claude Code utiliza intensivamente características exclusivas de Anthropic (prompt caching, incrementos de streaming de tool_use, contenido de razonamiento, etc.). Si se fuerza una conversión al protocolo de OpenAI, se perderán estas capacidades o el comportamiento será inconsistente. Por eso es indispensable asegurar que utilice el /v1/messages nativo.

VI. Lista de verificación para solución de problemas por escenario

6.1 Escenario 1: Uso local para desarrolladores individuales

Causa más común: Un wrapper con el mismo nombre en el alias de Shell o en el PATH.

Lista de verificación:

  • ¿npm list -g incluye @anthropic-ai/claude-code?
  • ¿type -a claude apunta únicamente al paquete oficial?
  • ¿~/.zshrc / ~/.bashrc tiene algún alias claude=...?
  • ¿env | grep -i claude muestra variables no estándar?
  • ¿ANTHROPIC_BASE_URL incluye el sufijo /v1? (No debería llevarlo).

6.2 Escenario 2: Despliegue en entornos de equipo o empresa

Causa más común: La pasarela (gateway) de LLM interna solo admite el protocolo OpenAI.

Lista de verificación:

  • ¿La pasarela corporativa admite de forma nativa el endpoint /v1/messages?
  • ¿La pasarela reenvía las cabeceras anthropic-version y anthropic-beta?
  • ¿La pasarela conserva el formato original de los eventos SSE?
  • ¿Existe algún script de wrapper unificado para el equipo?

Si la pasarela de tu empresa solo admite el protocolo OpenAI, te recomendamos configurar ANTHROPIC_BASE_URL en el cliente para que apunte a APIYI (apiyi.com). Esto permite una conexión directa con el protocolo nativo, evitando pérdidas por conversión.

6.3 Escenario 3: Invocación de Claude Code en entornos CI/CD

Causa más común: El script de CI tiene un wrapper de terceros integrado.

Lista de verificación:

  • ¿El archivo de configuración de CI ejecuta npm install -g con un paquete no oficial?
  • ¿Las variables de entorno de CI incluyen CLAUDE_CODE_USE_OPENAI=1 o similares?
  • ¿La imagen del runner de CI tiene preinstalado algún wrapper?

6.4 Escenario 4: Ejecución dentro de contenedores Docker

Causa más común: La imagen base tiene preinstalado un wrapper.

Lista de verificación:

  • ¿El nombre del paquete en RUN npm install -g dentro del Dockerfile es el oficial?
  • ¿A dónde apunta which claude dentro del contenedor?
  • ¿Las variables de entorno (ENV) del contenedor tienen configurada alguna variable de cambio de protocolo?

VII. Preguntas frecuentes (FAQ) sobre anomalías en el protocolo de Claude Code

Q1: Tengo instalado el paquete oficial @anthropic-ai/claude-code, ¿por qué sigue usando el protocolo OpenAI?

La causa más probable es que ANTHROPIC_BASE_URL apunte a una pasarela compatible con OpenAI. Algunas pasarelas, al recibir una solicitud /v1/messages, la convierten internamente a /v1/chat/completions para llamar al modelo superior. Si tu herramienta de captura de tráfico está desplegada después de la pasarela, verás el protocolo convertido.

La solución es cambiar ANTHROPIC_BASE_URL para que apunte a APIYI (apiyi.com), que admite de forma nativa /v1/messages sin ninguna pérdida por conversión.

Q2: ¿Cómo desinstalar completamente cualquier posible wrapper de Claude?

# Listar todos los paquetes globales relacionados con claude
npm list -g --depth=0 | grep -i claude

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

# Reinstalar el paquete oficial
npm install -g @anthropic-ai/claude-code

# Verificar
which claude
claude --version

Q3: ¿A qué nivel de ruta debo configurar ANTHROPIC_BASE_URL?

Configúralo en la raíz del dominio, sin el sufijo /v1. Claude Code añadirá automáticamente /v1/messages de forma interna.

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

# ❌ Incorrecto (se convertiría en /v1/v1/messages)
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1"

# ❌ Incorrecto (incluye la ruta del endpoint)
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1/messages"

Q4: ¿Por qué algunos tutoriales me piden instalar claude-code-router?

claude-code-router es una herramienta de la comunidad cuyo propósito principal es permitir que Claude Code invoque modelos que no son de Anthropic (como DeepSeek, Zhipu, Ollama local, etc.) mediante la conversión de protocolos.

Si solo quieres usar los modelos originales de Claude de Anthropic (como Claude Sonnet 4.5 o Opus 4.7), no necesitas CCR en absoluto. Conéctate directamente a APIYI (apiyi.com) usando el protocolo nativo /v1/messages para obtener una mejor experiencia y sin pérdidas por conversión.

Q5: ¿APIYI (apiyi.com) admite tanto /v1/messages como /v1/chat/completions?

Sí, APIYI es totalmente compatible con ambos protocolos:

  • https://vip.apiyi.com/v1/messages —— Formato nativo de Anthropic (predeterminado en Claude Code).
  • https://vip.apiyi.com/v1/chat/completions —— Formato compatible con OpenAI.

Una misma clave API puede utilizar ambos protocolos, adaptándose automáticamente según la herramienta cliente.

Q6: Si la URL de solicitud capturada es https://vip.apiyi.com/v1/messages, ¿significa que es modo nativo?

No necesariamente. Debes verificar también lo siguiente:

  1. La cabecera de la solicitud contiene anthropic-version: 2023-06-01.
  2. El cuerpo de la solicitud tiene un array messages y un campo system independiente (no un rol system dentro de messages).
  3. El cuerpo de la respuesta contiene "type": "message" y content: [...] (no choices: [...]).

Si la URL es /v1/messages pero el cuerpo de la solicitud tiene formato OpenAI (con el rol system dentro de messages), significa que el cliente tiene su propia capa de conversión.

Q7: ¿Cuál es la variable de entorno para habilitar los registros de depuración (debug) en Claude Code?

# Mostrar registros detallados de solicitud/respuesta HTTP
ANTHROPIC_LOG=debug claude

# O usar el modo verbose
claude --verbose

# Ver la información de diagnóstico de Claude Code
claude /doctor

Los registros de depuración mostrarán la URL completa, las cabeceras y el cuerpo de la solicitud (los campos sensibles se enmascaran), siendo la forma más directa de localizar problemas de protocolo.

Q8: Mi Claude Code funcionaba bien y de repente cambió al protocolo OpenAI, ¿cuál podría ser la causa?

Las causas más comunes de este cambio repentino son:

  • Se actualizó Claude Code, pero se instaló por error un paquete de terceros con el mismo nombre mediante npm install -g.
  • El equipo desplegó recientemente una pasarela de LLM y configuró una nueva ANTHROPIC_BASE_URL.
  • Algunos alias volvieron a activarse tras una actualización de macOS.
  • La empresa habilitó un proxy transparente para auditar la conversión de protocolos.

Al investigar, prioriza revisar los cambios recientes en el entorno (historial de instalación de npm, cambios en la configuración de shell, notificaciones de cambios en la pasarela).

八、Key Takeaways Puntos clave

  • ✅ El paquete oficial @anthropic-ai/claude-code utiliza siempre /v1/messages; no existe un modo de compatibilidad oficial con OpenAI.
  • ✅ 6 causas probables (por probabilidad): instalación errónea de paquetes de terceros / interceptación por claude-code-router / base_url apuntando a una pasarela de OpenAI / variables de entorno de terceros / alias de Shell / malinterpretación al capturar paquetes.
  • ✅ 5 pasos para un diagnóstico rápido: verificar el nombre del paquete → limpiar PATH/alias → limpiar variables de entorno → prueba curl a base_url → verificar con captura de paquetes local.
  • ✅ No incluyas el sufijo /v1 en ANTHROPIC_BASE_URL, ya que Claude Code lo añade automáticamente.
  • ✅ APIYI (apiyi.com) admite de forma nativa /v1/messages y es compatible con /v1/chat/completions; una sola clave API para ambos protocolos.
  • ✅ Ventajas de usar el protocolo nativo: soporte completo para características exclusivas de Anthropic como prompt caching, tool_use y reasoning content.
  • ✅ Método de verificación rápida: ejecuta ANTHROPIC_LOG=debug claude para ver la URL y el método de la solicitud real.

九、Conclusión

Claude Code instalado vía NPM debe utilizar siempre el protocolo nativo /v1/messages en el entorno de línea de comandos; este es un comportamiento codificado en el paquete oficial @anthropic-ai/claude-code y no existe ningún interruptor oficial para cambiar al modo de compatibilidad con OpenAI. Si al capturar los paquetes el cliente observa /v1/chat/completions, el problema reside sin duda en algún punto del entorno del cliente: ya sea que se haya instalado por error un envoltorio (wrapper) de terceros, que ANTHROPIC_BASE_URL apunte a una pasarela que solo admite el protocolo de OpenAI, o que un alias de Shell o una variable de entorno esté realizando una conversión interceptada.

Siguiendo el proceso de diagnóstico de 5 pasos descrito en el tercer capítulo de este artículo, la gran mayoría de los problemas pueden localizarse en menos de 10 minutos. La solución más común es: desinstalar todos los paquetes no oficiales → reinstalar @anthropic-ai/claude-code → configurar ANTHROPIC_BASE_URL hacia un servicio proxy de API que admita nativamente /v1/messages.

APIYI (apiyi.com) está diseñado para este tipo de escenarios: admite de forma nativa la API de mensajes de Anthropic (incluyendo la transmisión completa de las cabeceras anthropic-version y anthropic-beta), es compatible con OpenAI Chat Completions (protocolo dual con una sola clave), no tiene límites de concurrencia (evitando restricciones en sesiones largas de Claude Code), ofrece un bono del 10% en recargas de 100 USD (equivalente a un 15% de descuento respecto al sitio oficial) y permite pagos en RMB (vía WeChat/Alipay). Solo necesitas configurar ANTHROPIC_BASE_URL como https://vip.apiyi.com sin realizar ningún cambio en el código.

🎯 Siguiente paso recomendado: pide al cliente que siga el orden de los puntos 3.1 → 3.2 → 3.3 de este artículo, cambie ANTHROPIC_BASE_URL a https://vip.apiyi.com y, tras reiniciar Claude Code, utilice ANTHROPIC_LOG=debug claude para verificar si la URL de la solicitud ha vuelto a /v1/messages.

Referencias

  1. Documentación oficial de Claude Code: Instrucciones de configuración de LLM Gateway

    • Enlace: code.claude.com/docs/en/llm-gateway
    • Descripción: La documentación oficial especifica claramente que Claude Code utiliza el formato de la API de mensajes de Anthropic.

  2. Paquete NPM @anthropic-ai/claude-code: Página oficial del paquete NPM

    • Enlace: npmjs.com/package/@anthropic-ai/claude-code
    • Descripción: Verifica que tienes instalado el paquete oficial.

  3. Documentación oficial de la API de mensajes de Anthropic: Especificación del protocolo nativo

    • Enlace: docs.anthropic.com/en/api/messages
    • Descripción: Campos completos, encabezados de solicitud y formato de respuesta del endpoint /v1/messages.

  4. Sitio web oficial de APIYI: Servicio proxy de API con protocolo nativo de Anthropic

    • Enlace: apiyi.com
    • Descripción: Soporte nativo para /v1/messages + compatibilidad con /v1/chat/completions, concurrencia ilimitada y un 10% de regalo en recargas de 100 USD.

Autor: Equipo técnico
Última actualización: 02-05-2026
Sobre APIYI: APIYI (apiyi.com) es un proveedor profesional de servicios proxy de API para Claude. Ofrece soporte nativo para la API de mensajes de Anthropic (/v1/messages, incluyendo la transmisión completa de anthropic-version y anthropic-beta), a la vez que es compatible con OpenAI Chat Completions (/v1/chat/completions). Proporcionamos acceso estable a toda la serie Claude Sonnet 4.5, Claude Opus 4.7 y Claude Haiku 4.5. Con recargas de 100 USD obtienes un 10% adicional (equivalente a un 15% de descuento respecto al sitio oficial), sin límites de concurrencia y con un soporte técnico de respuesta rápida.

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

Publicaciones Similares