Configuración segura de Claude Code y mejores prácticas de API relay

Claude Code y las integraciones personalizadas con API envían más que prompts: emiten metadatos del entorno, decisiones de enrutamiento y comportamiento de reintentos que los sistemas upstream pueden correlacionar con el estado de la cuenta. Esta guía se centra en la seguridad operativa: configuración coherente del shell, elección del gateway y conmutación por error ordenada cuando se endurecen las cuotas. El objetivo son flujos de ingeniería confiables, no eludir las políticas de Anthropic.

Parta de una línea base limpia: limpieza del entorno y configuración de IP y selección de VPN y proxy antes de ajustar las variables del CLI. Si opera relays o enrutadores multi-modelo, consulte también alternativas locales y de código abierto para rutas de degradación.

1. Configuraciones de seguridad de Claude Code

Claude Code lee las variables de entorno del shell al iniciar. Zona horaria, proxy o URL base desalineados pueden producir errores confusos o hacer que el cliente se comporte distinto a la sesión del navegador. Trate la terminal como un entorno de primera clase, no como un detalle posterior.

Variables de entorno principales

# ~/.zshrc or ~/.bashrc — load in every interactive shell

# 1. Declare custom Anthropic-compatible endpoints explicitly
export ANTHROPIC_BASE_URL="https://your-gateway.example.com"
export ANTHROPIC_API_KEY="sk-your-key"

# 2. When using a trusted first-party-shaped gateway, reduce client mismatch warnings
export _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL=1

# 3. Align terminal timezone with your documented operating region
export TZ=Asia/Tokyo   # or America/Los_Angeles — match proxy geo

# 4. Route CLI HTTPS through the same clean proxy as your browser (if required)
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1,.internal"

Lista de verificación de configuración

1. Única fuente de verdad: guarde las variables en ~/.zshrc (macOS) o en un archivo dedicado ~/.claude/env cargado por el shell; evite exportarlas al vuelo en una sola pestaña de terminal.
2. Verificar antes del arranque: ejecute env | grep -E 'ANTHROPIC|TZ|PROXY' en la misma ventana desde la que inicia Claude Code.
3. Alinear la geografía del navegador y del CLI: si el perfil del navegador usa la zona horaria de Tokio mediante herramientas anti-detect, el CLI no debería reportar Asia/Shanghai.
4. Documentar cambios de URL base: al pasar de Anthropic directo a un relay, actualice ANTHROPIC_BASE_URL y los runbooks internos para que el equipo no mezcle endpoints.
5. Higiene de secretos: no suba API keys al repositorio; use chmod 600 en archivos de entorno y rote las claves del relay cada trimestre.

Qué hace y qué no hace _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL

Este indicador indica a Claude Code tratar un ANTHROPIC_BASE_URL no predeterminado como si fuera el endpoint estándar de Anthropic en ciertas comprobaciones del lado del cliente. Reduce fricción cuando la organización ejecuta un gateway interno aprobado. No cambia la política del servidor, la facturación ni la elegibilidad. Para cómo aún pueden evaluarse los metadatos del cliente, vea esteganografía de Claude y modelo de riesgo.

Fallos habituales por mala configuración

• Proxy dividido: el navegador usa VPN y el CLI no; las solicitudes salen de distintos ASN. Síntoma: el chat web funciona y el CLI devuelve 403.
• NO_PROXY obsoleto: un gateway local en 127.0.0.1 debe omitir el proxy corporativo o los bucles fallan con connection reset.
• Alcance incorrecto de la API key: las claves de organización y de proyecto se comportan distinto bajo rate limits; confirme el tipo de clave en la consola de Anthropic.
• Shell interactivo frente a no interactivo: los jobs de CI que invocan Claude Code deben cargar el mismo archivo de entorno; en portátiles, los login shells suelen ocultar exports faltantes.

2. Selección de gateways relay para API

Cuando el acceso directo a api.anthropic.com está limitado por enrutamiento o adquisiciones, los relays pueden mejorar la disponibilidad si conservan la fidelidad del protocolo. Un gateway deficiente elimina encabezados en silencio, reescribe prompts o añade picos de latencia que parecen regresión de calidad del modelo.

Matriz de evaluación de gateways

Preservación de Prompt Cache (impacto en costo)

El prompt caching de Anthropic puede reducir hasta un 90% el costo de entradas repetidas. Los relays que descartan encabezados de caché cobran tokens de entrada a precio completo en cada turno, a menudo con sorpresas de 4×–10× en system prompts largos. Valide con una prueba de dos solicitudes:

# Request 1: create cache
curl -s "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: prompt-caching-2024-07-15" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":64,
       "system":[{"type":"text","text":"'$(python3 -c "print('x'*5000)")'",
         "cache_control":{"type":"ephemeral"}}],
       "messages":[{"role":"user","content":"ping"}]}'

# Request 2: expect cache_read_input_tokens > 0 in usage

Los patrones de optimización avanzada están en optimización avanzada de API.

Debida diligencia operativa antes de producción

• Ejecute sondeos sintéticos de 24 horas (un mensaje cada 15 minutos) midiendo latencia p95 y tasa de error.
• Registre una muestra de request ID; confirme que la aplicación puede correlacionar logs del gateway con IDs upstream en incidentes.
• Revise el acuerdo de tratamiento de datos: algunos relays registran prompts para detección de abuso, lo cual no es aceptable para cargas reguladas.
• Prefiera gateways bajo control de la organización (LiteLLM autohospedado, One-API en VPC) frente a revendedores públicos opacos cuando se maneja código fuente.

La estabilidad a nivel de cuenta sigue dependiendo de la higiene del registro; consulte registro de cuenta y pago anti-ban si la adopción del relay coincide con la creación de una organización nueva.

3. Límites de tasa (429) y conmutación por error ordenada

Los rate limits de Anthropic aplican a nivel de organización y nivel de modelo, no solo por API key aislada. Agentes en ráfaga, jobs de CI en paralelo y bucles de reintento sin límite pueden agotar la cuota compartida y bloquear servicios no relacionados en la misma organización.

Clases de límite (simplificado)

Patrón de reintento y conmutación por error

// TypeScript — retry 429/529, failover on sustained pressure
async function callClaudeWithFallback(prompt: string, opts: CallOpts) {
  const maxRetries = 4;
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await callClaudeAPI(prompt, opts);
    } catch (error: any) {
      const status = error?.status;
      if (status === 429 || status === 529) {
        const delay = Math.min(30_000, 500 * 2 ** attempt + Math.random() * 250);
        await sleep(delay);
        continue;
      }
      if (status === 403) throw error; // surface auth issues
      throw error;
    }
  }
  console.warn('Claude quota saturated; failing over to backup upstream');
  return await callFallbackAPI(prompt, opts); // DeepSeek / GLM / local — see alternatives guide
}

Controles de concurrencia

• Token bucket en CI: limite los jobs de agente en paralelo (p. ej., máximo 3 concurrentes) por organización.
• Fusión de solicitudes: agrupe correcciones de lint pequeñas en lugar de una llamada API por archivo cuando sea posible.
• Circuit breaker: tras N 429 consecutivos, abra el circuito 60 s y enrute al fallback automáticamente; evita tormentas de reintentos.
• Observabilidad: exporte métricas: claude_requests_total{status}, fallback_invocations_total, latencia p95. Alerte si la tasa de fallback supera el 15% durante 10 minutos.

403 frente a 429: no tratarlos igual

Un 429 es presión temporal: retroceder y reanudar. Un 403 suele indicar revocación de credenciales, restricción geográfica o cambio de estado de la cuenta. Reintentar 403 con claves alternas sin diagnóstico puede acelerar la aplicación de políticas. Use la guía de solución de problemas para clasificar errores antes de rotar infraestructura.

Preguntas frecuentes

¿Debería definir TZ si la zona horaria del sistema ya es correcta?

Si la zona horaria del SO, la geografía de salida del proxy y el perfil del navegador ya coinciden, un TZ explícito puede ser redundante, pero los contenedores de CI suelen usar UTC por defecto. La exportación explícita hace el comportamiento determinista entre portátiles y servidores.

¿Es «seguro» un revendedor público de API para código fuente de la empresa?

Trátelo como cualquier subprocesador de terceros: revise registro, retención y lista de subprocesadores. Para código propietario, los relays autohospedados en su VPC son estrictamente más seguros que revendedores anónimos.

¿Por qué desaparecen los ahorros de caché al cambiar de gateway?

Lo más habitual es que el relay elimine encabezados anthropic-beta o reordene bloques system, invalidando las claves de caché. Repita la prueba de caché de dos solicitudes tras cualquier cambio de gateway.

¿Puedo usar proxies distintos para el navegador y Claude Code?

Técnicamente sí, pero aumenta el riesgo de divergencia. Prefiera una ruta de salida documentada para todo el tráfico Claude, salvo que aísle cuentas experimentales en perfiles separados.

¿Qué modelo de respaldo debería usar Claude Code ante un 429?

Claude Code no tiene conmutación multi-modelo integrada; implémentela en el gateway (One-API/LiteLLM) o desactive Claude Code temporalmente y use plugins del IDE apuntando a APIs de respaldo. Vea alternativas locales y de código abierto para tablas de enrutamiento.

¿Cómo depurar «funciona en curl pero falla en Claude Code»?

1. Compare encabezados: capture curl frente al CLI con mitmproxy o logs de acceso del gateway.
2. Confirme el entorno en el shell de lanzamiento: las terminales integradas del IDE a veces omiten archivos rc de login.
3. Revise los agentes proxy de Node/fetch; algunas versiones ignoran HTTPS_PROXY salvo que se defina GLOBAL_AGENT_HTTP_PROXY.
4. Verifique interceptación TLS en redes corporativas.

¿Asumir URL base de first party afecta la facturación de Anthropic?

No. La facturación sigue la API key y la organización ligadas al upstream que realmente atiende la solicitud. Si el gateway reenvía a Anthropic, paga Anthropic; si cambia de modelo, paga el proveedor que invoque el gateway.