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 ves | Causa | Solución |
|---|---|---|
| Conexión rechazada | El proxy no se está ejecutando o el puerto es diferente | Iní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ón | Añade ese nombre a model_list |
| Upstream 401 | UPSTREAM_KEY incorrecta o vacía | Re-exporta la clave en el shell del proxy y reinicia |
429 con concurrency | Más de 8 peticiones simultáneas (2 en prueba) | Reduce los agentes paralelos |
429 con rate_limited | Más de 300 peticiones por minuto (60 en prueba) | Espera y reintenta |
429 con Retry-After: 5 | Sobrecarga temporal | Reintenta después de cinco segundos |
| Transmisión estancada | Una petición en streaming mantiene su espacio hasta que termine | Cancé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.
