Base URL de Claude Code: cómo configurar ANTHROPIC_BASE_URL correctamente

Wokey Team · 2026-09-24

Respuesta corta: la base URL de Claude Code se configura con la variable de entorno ANTHROPIC_BASE_URL. Usa solo el origen del gateway, sin /v1. Para Wokey es https://api.wokey.ai; Claude Code agrega /v1/messages por su cuenta. Pon tu clave en ANTHROPIC_AUTH_TOKEN, que se envía como Authorization: Bearer. Si configuras la base URL pero no la clave, Claude Code sigue usando tu sesión guardada de claude.ai.

Configuración mínima

export ANTHROPIC_BASE_URL="https://api.wokey.ai"
export ANTHROPIC_AUTH_TOKEN="your Wokey API key"
claude

Dentro de Claude Code, ejecuta /status. Las solicitudes pasan por Wokey cuando la pestaña Status muestra:

• Anthropic base URL con el valor https://api.wokey.ai
• una línea Auth token que menciona ANTHROPIC_AUTH_TOKEN

Si falta la línea Anthropic base URL, la variable nunca llegó a la sesión.

Por qué /v1 lo rompe

Claude Code trata ANTHROPIC_BASE_URL como un prefijo y solicita $ANTHROPIC_BASE_URL/v1/messages. Si la configuras como https://api.wokey.ai/v1, la solicitud va a /v1/v1/messages, y Wokey responde con:

{"message":"Route POST:/v1/v1/messages not found","error":"Not Found","statusCode":404}

Los clientes compatibles con OpenAI, como Cursor o Cherry Studio, por convención usan .../v1. Claude Code sigue en cambio la convención de Anthropic, y las dos no se mezclan. Tampoco agregues /v1/messages ni una barra final.

AUTH_TOKEN o API_KEY

Wokey acepta cualquiera de los dos encabezados. La diferencia está del lado de Claude Code:

• ANTHROPIC_AUTH_TOKEN surte efecto de inmediato.
• ANTHROPIC_API_KEY pide una aprobación única en modo interactivo antes de tomar el control. Una clave que rechazaste antes se ignora en silencio.

No configures ambas con valores distintos. Cuando los dos encabezados llevan claves diferentes, Wokey rechaza la solicitud:

{"error":{"code":"conflicting_api_key_headers","message":"conflicting_api_key_headers","type":"invalid_request_error"}}

La misma clave en ambos encabezados no es problema.

Qué pasa si solo configuras la base URL

Una base URL no es una credencial. Con solo ANTHROPIC_BASE_URL configurada y sin AUTH_TOKEN ni API_KEY, Claude Code sigue enviando las solicitudes con tu sesión guardada de claude.ai. Wokey no la reconoce como una clave de Wokey y devuelve 401.

Una vez configurada una credencial del gateway, tu sesión de claude.ai sigue guardada pero sin usarse; elimina la variable para volver a ella.

Puede que veas una advertencia al iniciar que termina en auth may not work as expected. Las versiones anteriores muestran en su lugar Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set. Cualquiera de las dos significa que hay a la vez una credencial del gateway y una sesión guardada. Para usar solo el gateway, ejecuta /logout dentro de Claude Code para borrar la sesión guardada.

Hazlo permanente en settings.json

Un export solo dura en la terminal actual, y los editores abiertos desde el Dock o el menú Inicio no lo ven. Para el uso diario, pon los valores en el bloque env de ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.wokey.ai",
    "ANTHROPIC_AUTH_TOKEN": "your Wokey API key"
  }
}

• Cuando la shell y un archivo de configuración definen la misma variable, gana el archivo de configuración. Si una variable de la shell que cambiaste parece no tener efecto, revisa aquí primero.
• Para un solo proyecto, usa el .claude/settings.local.json de ese proyecto y asegúrate de que esté en el gitignore.
• Nunca pongas la clave en el .claude/settings.json de un proyecto. Ese archivo se sube al repositorio.

Elegir modelos

Wokey usa los mismos ID de modelo de Claude que Anthropic, como claude-opus-5, claude-sonnet-5 y claude-haiku-4-5. Cambia de modelo durante una sesión con /model. Para fijar qué modelo usa cada nivel Opus, Sonnet y Haiku de Claude Code, agrega a env:

{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

ANTHROPIC_DEFAULT_HAIKU_MODEL también define el modelo de las tareas en segundo plano, como los títulos de sesión.

Extensión de VS Code y app de escritorio

La extensión de VS Code no usa las variables de la shell para su comprobación de inicio de sesión. Configúralas en la propia configuración de usuario de VS Code: ejecuta Preferences: Open User Settings (JSON) desde la paleta de comandos y agrega:

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.wokey.ai" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "your Wokey API key" }
  ]
}

Los valores de ~/.claude/settings.json llegan al proceso que inicia la extensión, pero no a la comprobación de inicio de sesión de la propia extensión. Si la extensión te sigue pidiendo iniciar sesión, usa la configuración de arriba.

La app de escritorio de Claude no lee ni ANTHROPIC_BASE_URL ni settings.json. Para configurar un gateway:

1. Abre Help → Troubleshooting → Enable Developer Mode.
2. Abre Developer → Configure Third-Party Inference e ingresa la dirección del gateway.

Consulta la guía de configuración de Claude Desktop para ver los pasos completos.

Comprueba primero con curl

Desde la misma terminal, prueba sin Claude Code de por medio:

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

Lo que te dice la respuesta:

• Empieza con {"id":"msg_: la URL y la clave están bien; el problema está en tu configuración de Claude Code.
• 401 con el código invalid_api_key: la clave falta, está mal escrita o se eliminó.
• 404 que menciona /v1/v1/messages: la base URL tiene un /v1 de más.
• curl funciona pero Claude Code sigue pidiendo iniciar sesión: Claude Code no tiene credencial propia. Comprueba que las variables se configuraron en la misma terminal desde la que iniciaste claude, o muévelas a ~/.claude/settings.json.