ES ▾

InicioGuía

Configuración del proxy de Claude Code con una API compatible con OpenAI

Esta configuración de proxy de claude code tiene cinco pasos: obtener una clave, escribir una configuración de LiteLLM, iniciar el proxy, configurar dos variables de entorno y ejecutar una prueba. Toma unos diez minutos.

Cinco piedras de paso luminosas que van desde un terminal hasta un servidor, mostrando una configuración de proxy paso a paso

Puntos clave

  1. Ejecuta un proxy LiteLLM local que reenvía a https://api.claudecodeproxyapi.com/v1
  2. Configura Claude Code para usar el proxy con ANTHROPIC_BASE_URL y ANTHROPIC_AUTH_TOKEN
  3. Mapea el nombre de modelo que envía Claude Code al modelo upstream uncensored
  4. Prueba el proxy con curl antes de iniciar la CLI

Lo que necesitas

  • Una clave de API de la página de claves. Regístrate con Google o correo electrónico y contraseña, luego reclama el crédito de prueba de $0.50 con un solo clic.
  • Python 3.9 o superior, para instalar el proxy.
  • Claude Code instalado y funcionando en tu máquina.

¿Por qué un proxy en absoluto? Claude Code usa el formato de mensajes de Anthropic, y nuestra API usa el formato de Chat Completions de OpenAI con el ID de modelo uncensored. El proxy traduce entre ambos. Si prefieres primero el contexto, lee la guía de solución de problemas del proxy. El modelo es un modelo de pesos abiertos, no Claude, así que espera un comportamiento diferente en tareas complejas de varios pasos.

Paso 1: instalar el proxy

Usa un entorno virtual para que las dependencias del proxy se mantengan separadas de tus proyectos:

python3 -m venv ~/litellm-env
source ~/litellm-env/bin/activate
pip install 'litellm[proxy]'

LiteLLM es software de código abierto de terceros. Los comandos y las claves de configuración que se indican a continuación coinciden con su documentación pública en el momento de la redacción, pero consulta su documentación actual si alguna bandera ha cambiado.

Paso 2: escribir la configuración

Crea config.yaml. El model_name es el nombre que envía el cliente. El bloque litellm_params indica dónde reenviarlo. El prefijo openai/ le dice a LiteLLM que hable con un servidor compatible con OpenAI.

cat > config.yaml <<'EOF'
model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: openai/uncensored
      api_base: https://api.claudecodeproxyapi.com/v1
      api_key: os.environ/UPSTREAM_KEY
EOF

El alias claude-sonnet es un ejemplo, no un requisito. Claude Code puede enviar varios nombres de modelo diferentes, por ejemplo, un modelo principal y uno más pequeño para tareas en segundo plano. Añade una entrada model_list por cada nombre que veas en el registro del proxy, apuntando todas al mismo servicio de origen. Apuntar todos los alias a uncensored está bien, porque solo hay un modelo.

La clave se lee de una variable de entorno, por lo que nunca llega a un archivo que podrías subir a un repositorio.

Paso 3: iniciar el proxy

export UPSTREAM_KEY="YOUR_KEY"
litellm --config config.yaml --port 4000

Deja esta terminal abierta. Deberías ver el servidor escuchando en el puerto 4000. Ahora verifica la ruta upstream desde el lado del proxy con una petición de prueba en formato Anthropic, que es lo que enviará Claude Code:

curl http://localhost:4000/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: sk-local-anything" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet",
    "max_tokens": 200,
    "messages": [{"role": "user", "content": "Reply with the word ready."}]
  }'

Una respuesta JSON cuyo contenido incluye la palabra "ready" significa que la traducción funciona de extremo a extremo: formato Anthropic de entrada, formato OpenAI a https://api.claudecodeproxyapi.com/v1, y de vuelta. Si configuras una clave maestra en la configuración de LiteLLM, úsala en lugar de sk-local-anything.

Paso 4: señalar Claude Code al proxy

Claude Code lee su dirección de API y token de variables de entorno. Configúralos en el shell donde inicias la CLI:

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-local-anything"
export ANTHROPIC_MODEL="claude-sonnet"
claude

Usa la dirección del proxy sin el sufijo /v1 aquí, porque la CLI añade su propia ruta. El token solo tiene que satisfacer al proxy, ya que la clave real de origen es la que exportaste como UPSTREAM_KEY. Si usas el archivo de configuración de la CLI para los valores de entorno en lugar del shell, pon los mismos tres nombres allí. Los nombres de las variables de entorno para Claude Code pueden cambiar entre versiones, así que verifícalos contra la documentación actual de Claude Code si algo se ignora.

Paso 5: ejecutar una primera tarea y observar el registro

Empieza pequeño. Pídele a la CLI que explique un archivo o que añada un comentario a una función. En la terminal del proxy deberías ver una petición por paso. Anota cada nombre de modelo que aparezca; si uno no está en tu model_list, el proxy responde con un error, así que añádelo y reinicia.

Las llamadas a funciones son importantes aquí, ya que la CLI lee archivos y edita código a través de herramientas. La API admite tools, tool_choice y tool_calls en streaming, y el proxy los convierte. Un cumplimiento menor de un esquema de herramientas se manifiesta como una edición fallida o un paso repetido. Cuando eso ocurra, acorta la tarea y vuelve a intentarlo antes de decidir que la configuración está rota.

La ventana de contexto es de 100,000 tokens, prompt y respuesta juntos. Las sesiones largas que superen este límite fallarán, así que inicia una sesión nueva para una tarea nueva. Los costos son mínimos: $0.15 por 1M de tokens de entrada y $0.50 por 1M de tokens de salida: una petición con 20,000 tokens de entrada y 800 de salida cuesta $0.003 + $0.0004 = $0.0034. Consulta la página de precios para recargas, que en este sitio se pagan por cripto (USDT en TRC20, USDC en Base).

Solución de problemas

Lo que vesCausaSolución
Conexión rechazadaEl proxy no se está ejecutando o el puerto es diferenteInícialo y asegúrate de que el puerto coincida con ANTHROPIC_BASE_URL
Proxy 404 o "modelo no encontrado"El nombre de modelo que envió la CLI no está en la configuraciónAñade ese nombre a model_list
Upstream 401UPSTREAM_KEY incorrecta o vacíaRe-exporta la clave en el shell del proxy y reinicia
429 con concurrencyMás de 8 peticiones simultáneas (2 en prueba)Reduce los agentes paralelos
429 con rate_limitedMás de 300 peticiones por minuto (60 en prueba)Espera y reintenta
429 con Retry-After: 5Sobrecarga temporalReintenta después de cinco segundos
Transmisión estancadaUna petición en streaming mantiene su espacio hasta que termineCancélala en la CLI para liberar el espacio

Para cualquier cosa no cubierta aquí, incluye la cabecera de respuesta X-Request-Id cuando escribas a soporte. La documentación enumera cada parámetro admitido.

Hacerlo permanente

Escribir exports cada vez se vuelve tedioso. Pon el inicio del proxy en un script pequeño y las variables del cliente en un alias, para que un comando levante todo:

cat > ~/start-proxy.sh <<'EOF'
. ~/litellm-env/bin/activate
export UPSTREAM_KEY="YOUR_KEY"
exec litellm --config ~/config.yaml --port 4000
EOF
chmod +x ~/start-proxy.sh

alias claude-uncensored='ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_AUTH_TOKEN=sk-local-anything ANTHROPIC_MODEL=claude-sonnet claude'

Como las variables se configuran solo para ese comando, tu comando normal claude sigue funcionando con su configuración predeterminada. Añade el alias a tu perfil de shell. Protege el script con permisos de archivo como chmod 700, ya que contiene tu clave.

Volver atrás

Si exportaste las variables en el shell actual, ejecuta unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL e inicia la CLI nuevamente. No se ha cambiado nada en el lado de la API, así que no hay nada que deshacer.

Vigila tu saldo y gastos

Cada respuesta de la API incluye X-Balance-USD, el crédito restante en tu clave. LiteLLM puede pasar los encabezados upstream en algunas configuraciones, pero la forma más segura de ver tu saldo es llamar directamente al upstream de vez en cuando:

curl -i https://api.claudecodeproxyapi.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY" | grep -i x-balance-usd

Las sesiones de agente crecen silenciosamente. Cada paso reenvía el contexto de trabajo, por lo que una sesión larga cuesta más por petición que una corta. Iniciar una sesión nueva para cada tarea mantiene la entrada pequeña y la factura baja. A los precios publicados ($0.15 por 1M de entrada y $0.50 por 1M de salida), una petición con 50,000 tokens de entrada y 1,000 de salida cuesta 50,000 x $0.15 / 1M = $0.0075 más $0.0005, lo que es $0.008. Veinte de esas peticiones suman $0.16.

Las recargas van de $20 a $500 en cantidades enteras y se pagan con criptomonedas (USDT en TRC20 o USDC en Base) en este sitio. El crédito no caduca, por lo que una recarga mayor con el bono de +5%, +10% o +15% no pone un límite de tiempo a tu saldo.

Preguntas y respuestas

¿Qué variables de entorno necesita Claude Code para un proxy?

ANTHROPIC_BASE_URL para la dirección del proxy y ANTHROPIC_AUTH_TOKEN para un token que el proxy acepta. ANTHROPIC_MODEL puede nombrar el alias que definiste. Consulta la documentación actual de Claude Code para ver cambios.

¿Pongo /v1 en ANTHROPIC_BASE_URL?

No. Usa la dirección del proxy como http://localhost:4000, porque la CLI añade su propia ruta. El /v1 solo pertenece al api_base de origen en la configuración del proxy.

¿Puedo usar un proxy distinto a LiteLLM?

Sí. Cualquier proxy que convierta peticiones de Anthropic Messages a OpenAI Chat Completions funciona, por ejemplo claude-code-router. Apunta su upstream a https://api.claudecodeproxyapi.com/v1 con el modelo uncensored.

¿Es segura mi clave upstream en la configuración?

Mantén la clave en una variable de entorno en lugar del archivo, como se muestra en la configuración anterior. No hagas commit de la clave en un repositorio.

Tu clave está a un formulario de distancia

Crea una cuenta, copia la clave, cambia la URL base. Esa es toda la configuración.