La configuración de Claude Code API empieza por elegir la ruta activa, no por pegar una clave. Decide si la sesión debe usar inicio de sesión de suscripción, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN con ANTHROPIC_BASE_URL, apiKeyHelper, Bedrock, Vertex o Foundry.
El orden seguro es ruta, alcance, modelo y verificación. Antes de confiar en la sesión, comprueba /status, /config y /model.
| Objetivo | Dónde configurarlo | Primera verificación |
|---|---|---|
| Uso interactivo normal | Inicio de sesión y settings de usuario/proyecto | /status |
| API key directa | shell local con ANTHROPIC_API_KEY | env y ruta activa |
| Gateway compatible | ANTHROPIC_AUTH_TOKEN y ANTHROPIC_BASE_URL | host, modelo y confianza |
| Bedrock, Vertex, Foundry | credenciales del proveedor y variables de ruta | proveedor, región y modelo |
Elige la ruta antes de configurar
Claude Code puede usar contratos distintos aunque el comando sea el mismo. El inicio de sesión de suscripción sirve para trabajo interactivo. La API key directa sirve para CI, SDK, agentes, tareas sin login humano o uso auditado en Console. El gateway requiere una frontera de confianza clara. Los proveedores cloud trasladan credenciales, región, modelo y cuota a su propia plataforma.
Para instalación base, abre Claude Code install. Para saber quién paga cuando hay API key, usa API key vs subscription billing.
Prioridad de credenciales
En la revisión oficial del 21 de abril de 2026, el orden era credenciales cloud, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper, OAuth token y después /login. Una variable antigua puede ganar a un cambio nuevo en settings.
bashtest -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY is set" test -n "$ANTHROPIC_AUTH_TOKEN" && echo "ANTHROPIC_AUTH_TOKEN is set" printenv ANTHROPIC_BASE_URL
Alcance de settings.json
~/.claude/settings.json es para valores personales. .claude/settings.json es para reglas compartidas del proyecto. .claude/settings.local.json es para ajustes locales. Las claves y tokens no deben vivir en settings compartido.
| Alcance | Uso correcto | Evita |
|---|---|---|
| usuario | preferencias personales | política del equipo |
| proyecto compartido | permisos y defaults no secretos | API keys |
| proyecto local | override de una máquina | valores para commit |
| shell / CI | credenciales y flags | defaults invisibles para el equipo |
API key y gateway
Para la ruta directa de Anthropic usa ANTHROPIC_API_KEY:
bashexport ANTHROPIC_API_KEY="$YOUR_ANTHROPIC_API_KEY" claude /status
Para gateway, token y base URL van juntos:
bashexport ANTHROPIC_AUTH_TOKEN="$YOUR_GATEWAY_TOKEN" export ANTHROPIC_BASE_URL="https://gateway.example.com" claude /status
Un gateway no es el mismo contrato que la API directa de Anthropic. Revisa API shape, headers, nombres de modelo, logs y límite de datos. La selección de proveedor va en Claude gateway.
Modelo y proveedores
La prioridad del modelo es /model, --model, ANTHROPIC_MODEL y después model en settings. Bedrock usa CLAUDE_CODE_USE_BEDROCK=1 y AWS_REGION; Vertex usa CLAUDE_CODE_USE_VERTEX=1 y credenciales de Google Cloud.
Verificación
Dentro de Claude Code ejecuta:
text/status /config /model
En shell, comprueba existencia sin imprimir secretos. Si la ruta no coincide, limpia variables de mayor prioridad y abre una nueva sesión.
Seguridad y decisiones vecinas
No hagas commit de claves reales, bearer tokens, URLs privadas ni credenciales cloud. Antes de enviar cambios, revisa git diff -- .claude/settings.json .claude/settings.local.json.
Decisiones relacionadas: instalación, API key y facturación, Claude API key free tier, usage limits.
Preguntas frecuentes
¿Necesito API key para Claude Code?
No siempre. Para uso interactivo normal, el inicio de sesión de suscripción puede ser suficiente. La API key es para ruta API, CI y automatización.
¿Para qué sirve ANTHROPIC_AUTH_TOKEN?
Es un bearer token. Suele usarse con ANTHROPIC_BASE_URL para una ruta de gateway compatible.
¿Cómo verifico la configuración?
Ejecuta /status, /config, /model y comprueba variables sin imprimir secretos.