1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Conectar Claude Code a una puerta de enlace LLM
6
7> Apunte Claude Code a la puerta de enlace LLM de su organización. Compruebe si su administrador ya la configuró, o establezca la URL base y las credenciales usted mismo para la CLI, VS Code, GitHub Actions y el Agent SDK, luego verifique la conexión y corrija los errores de la puerta de enlace.
8
9Una [puerta de enlace LLM](/es/llm-gateway) es un proxy que su organización ejecuta entre Claude Code y el proveedor del modelo. Cuando su organización usa una, Claude Code se autentica en la puerta de enlace con una credencial que su organización emite en lugar de su inicio de sesión personal en claude.ai.
10
11Esta página es para desarrolladores que ejecutan Claude Code a través de una puerta de enlace que opera su organización. Cubre dos caminos: [comprobar si su administrador ya la configuró para usted](#check-for-an-existing-configuration), y [configurarla usted mismo](#configure-claude-code-yourself) cuando no lo haya hecho.
12
13<Note>
14 * Para implementar una puerta de enlace para su organización, consulte [Implementar una puerta de enlace LLM](/es/llm-gateway-rollout)
15 * Para ver qué envía Claude Code a una puerta de enlace, consulte la [referencia del protocolo de puerta de enlace](/es/llm-gateway-protocol)
16</Note>
17
18<h2 id="check-for-an-existing-configuration">
19 Comprobar una configuración existente
20</h2>
21
22Los administradores pueden distribuir la dirección de la puerta de enlace y la credencial a través de [configuración administrada](/es/settings#settings-files), administración de dispositivos, o un [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper), para que Claude Code las recoja al iniciar sin que tenga que configurar nada. Para comprobar si su organización ya lo hizo:
23
24<Steps>
25 <Step title="Iniciar Claude Code">
26 Ejecute `claude`. Si se abre en la pantalla de inicio de sesión en lugar de una sesión, no se distribuyó ninguna credencial de puerta de enlace; [configúrela usted mismo](#configure-claude-code-yourself) a continuación.
27 </Step>
28
29 <Step title="Comprobar la pestaña Estado">
30 Si Claude Code inició una sesión sin mostrar la pantalla de inicio de sesión, ejecute `/status`, abra la pestaña **Estado**, y compruebe dos líneas:
31
32 * `Anthropic base URL`: esta línea solo aparece cuando se establece una dirección de puerta de enlace. Si no está ahí, Claude Code no está apuntando a la puerta de enlace; [configúrela usted mismo](#configure-claude-code-yourself) a continuación.
33 * `Auth token` o `API key`: una línea que nombre `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_API_KEY`, o un `apiKeyHelper` confirma que una credencial de puerta de enlace está activa. Una línea `Login method` que nombre una cuenta de claude.ai en su lugar significa que la credencial no se distribuyó; [establézcala usted mismo](#set-the-credential-variable).
34 </Step>
35
36 <Step title="Enviar un mensaje de prueba">
37 Cierre el menú `/status` y envíe cualquier solicitud en Claude Code. Una respuesta normal de Claude, sin error, confirma que la conexión de la puerta de enlace funciona.
38 </Step>
39</Steps>
40
41Si ambas líneas en el menú `/status` se ven bien pero el mensaje a Claude falla, consulte la [tabla de solución de problemas](#troubleshoot-gateway-errors).
42
43<h2 id="configure-claude-code-yourself">
44 Configurar Claude Code usted mismo
45</h2>
46
47Para configurar Claude Code para la puerta de enlace usted mismo, necesita de su equipo de puerta de enlace:
48
49* La URL base de la puerta de enlace
50* Una credencial: una cadena de clave o token, o un comando que obtenga una
51 * Si su equipo de puerta de enlace no dijo qué tipo de credencial es, la sección [variable de credencial](#set-the-credential-variable) a continuación cubre qué intentar
52
53Las secciones a continuación cubren la configuración en orden:
54
55* [Establecer la variable de credencial](#set-the-credential-variable) y [establecer la URL base](#set-the-base-url-and-credential): las dos variables que toda conexión de puerta de enlace necesita
56* [Verificar la conexión](#verify-the-connection): confirmar que funciona antes de persistir nada
57* [Configurar cada superficie](#configure-each-surface): si está usando una superficie además de la CLI de Claude Code, como VS Code, vea cómo configurarla con sus credenciales de puerta de enlace
58* [Configuración adicional](#additional-configuration): variables que algunas puertas de enlace necesitan más allá de la URL base y la credencial, como un encabezado personalizado, un asistente de credencial, descubrimiento de modelos, o una URL base en formato de proveedor. Establezca estos solo si su administrador los nombró
59
60<h3 id="set-the-credential-variable">
61 Establecer la variable de credencial
62</h3>
63
64Para autenticar Claude Code en la puerta de enlace, establezca su credencial en una variable de entorno. Qué variable depende de lo que su equipo de puerta de enlace le dijo:
65
66| Establecer la credencial en | Usar cuando |
67| :------------------------------------------------------ | :------------------------------------------------------------------------- |
68| `ANTHROPIC_AUTH_TOKEN` | Su equipo de puerta de enlace dijo "bearer token" o "Authorization header" |
69| `ANTHROPIC_API_KEY` | Su equipo de puerta de enlace dijo "API key" o "x-api-key" |
70| [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper) | La credencial rota o viene de un almacén |
71
72Si no le dijeron cuál, use `ANTHROPIC_AUTH_TOKEN`; la [solicitud de verificación](#verify-the-connection) a continuación muestra cómo saber si necesita cambiar.
73
74<h3 id="set-the-base-url-and-credential">
75 Establecer la URL base y la credencial
76</h3>
77
78Establezca la URL base de la puerta de enlace y la variable de credencial que eligió arriba como variables de entorno. Los ejemplos usan `ANTHROPIC_AUTH_TOKEN`; cámbielo por `ANTHROPIC_API_KEY` si esa es [la variable que eligió](#set-the-credential-variable). Puede establecerlos [en su shell](#set-as-shell-environment-variables), que dura una sesión de terminal, o [en un archivo de configuración de Claude Code](#set-in-a-settings-file), que persiste en todas partes donde se ejecuta Claude Code.
79
80Para su primera conexión, comience con exportaciones de shell y ejecute la [solicitud de verificación](#verify-the-connection) antes de mover los valores a un archivo de configuración.
81
82<h4 id="set-as-shell-environment-variables">
83 Establecer como variables de entorno de shell
84</h4>
85
86Reemplace los valores con los que su equipo de puerta de enlace le dio:
87
88<Tabs>
89 <Tab title="Bash o Zsh">
90 ```bash theme={null}
91 export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
92 export ANTHROPIC_AUTH_TOKEN=sk-gateway-key
93 ```
94 </Tab>
95
96 <Tab title="PowerShell">
97 ```powershell theme={null}
98 $env:ANTHROPIC_BASE_URL = "https://llm-gateway.example.com"
99 $env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"
100 ```
101 </Tab>
102</Tabs>
103
104Las exportaciones de shell se aplican solo a esa sesión de terminal y a los programas iniciados desde ella; un editor lanzado desde el dock o el menú Inicio no las verá. Para que persistan en nuevas terminales, agregue las mismas líneas a su perfil de shell, como `~/.zshrc`, `~/.bashrc`, o su `$PROFILE` de PowerShell, o use un archivo de configuración en su lugar.
105
106<h4 id="set-in-a-settings-file">
107 Establecer en un archivo de configuración
108</h4>
109
110Para que la configuración se aplique en todas partes donde se ejecuta Claude Code sin depender de su shell, establezca las variables en el bloque `env` de un [archivo de configuración](/es/settings). Los archivos de configuración tienen diferentes alcances:
111
112* `~/.claude/settings.json` se aplica a todos sus proyectos. En Windows la ruta es `%USERPROFILE%\.claude\settings.json`
113* `.claude/settings.local.json` se aplica a un proyecto. Claude Code lo agrega a su gitignore cuando crea el archivo; si lo crea usted mismo, agréguelo a su gitignore manualmente primero para que no cometa accidentalmente su credencial
114
115<Warning>
116 No ponga la credencial en el `.claude/settings.json` de un proyecto. Ese archivo se confirma y se comparte con todos los que clonan el repositorio.
117</Warning>
118
119El bloque `env` se ve igual en cualquiera de los archivos:
120
121```json theme={null}
122{
123 "env": {
124 "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
125 "ANTHROPIC_AUTH_TOKEN": "sk-gateway-key"
126 }
127}
128```
129
130Cuando tanto una exportación de shell como un bloque `env` de archivo de configuración establecen la misma variable, se aplica el valor del archivo de configuración. Ejecute `/status` para ver qué URL base y fuente de credencial está usando Claude Code.
131
132<h3 id="verify-the-connection">
133 Verificar la conexión
134</h3>
135
136Con las variables exportadas en su shell, envíe una solicitud de un token a la puerta de enlace directamente. Esto confirma que la URL y la credencial funcionan antes de abrir Claude Code, por lo que una falla apunta a la puerta de enlace en lugar de su configuración. Los comandos a continuación leen las variables de shell, por lo que necesitan las [exportaciones de shell](#set-as-shell-environment-variables) incluso si también pone los valores en un archivo de configuración.
137
138<Tabs>
139 <Tab title="Bash o Zsh">
140 ```bash theme={null}
141 curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
142 -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
143 -H "anthropic-version: 2023-06-01" \
144 -H "content-type: application/json" \
145 -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
146 ```
147 </Tab>
148
149 <Tab title="PowerShell">
150 ```powershell theme={null}
151 Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
152 -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
153 -ContentType "application/json" `
154 -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
155 ```
156 </Tab>
157</Tabs>
158
159Si su puerta de enlace espera claves en el encabezado `x-api-key`, reemplace el encabezado `Authorization` con `x-api-key: $ANTHROPIC_API_KEY` en el comando Bash, o la entrada de tabla hash `"Authorization"` con `"x-api-key" = "$env:ANTHROPIC_API_KEY"` en el comando PowerShell.
160
161Una respuesta JSON que comience con `{"id":"msg_` e incluya un campo `"content":[...]` significa que la puerta de enlace es alcanzable y la credencial funciona. Un error que nombre un modelo desconocido aún prueba que la URL y la credencial funcionan, ya que la puerta de enlace autenticó la solicitud antes de rechazar el nombre del modelo; no necesita encontrar un modelo que su puerta de enlace sirva para esta prueba. Un `401` significa que la credencial fue rechazada: si adivinó la variable, cambie a la otra y re-exporte.
162
163<h4 id="confirm-in-claude-code">
164 Confirmar en Claude Code
165</h4>
166
167Inicie `claude` desde el mismo shell para que herede las exportaciones, envíe un mensaje, y ejecute `/status`.
168
169En la pestaña **Estado**, la línea `Anthropic base URL` debe mostrar su dirección de puerta de enlace, lo que confirma que las solicitudes se enrutan allí; si la línea no está ahí, la variable no llegó a la sesión. Una línea `Auth token` o `API key` que nombre la variable que estableció confirma que la credencial de puerta de enlace está activa en lugar de un inicio de sesión de claude.ai guardado.
170
171Si el mensaje falla, o `/status` no muestra la URL de la puerta de enlace, consulte la [tabla de solución de problemas](#troubleshoot-gateway-errors) a continuación.
172
173<h3 id="how-the-credential-variable-maps-to-a-header">
174 Cómo la variable de credencial se asigna a un encabezado
175</h3>
176
177Cada variable envía la credencial en un encabezado HTTP diferente: `ANTHROPIC_AUTH_TOKEN` en `Authorization: Bearer`, `ANTHROPIC_API_KEY` en `x-api-key`, y `apiKeyHelper` en ambos. Una credencial en la variable incorrecta llega a la puerta de enlace en un encabezado que no lee, y la solicitud falla con `401`. Si la solicitud de verificación devolvió `401`, cambie a la otra variable e intente de nuevo.
178
179<h3 id="conflicts-with-an-existing-login">
180 Conflictos con un inicio de sesión existente
181</h3>
182
183Una variable de credencial de puerta de enlace tiene precedencia sobre un inicio de sesión de claude.ai guardado o una clave de Consola. Su inicio de sesión de claude.ai permanece guardado y sin usar mientras la variable está establecida; desestablezca la variable y Claude Code vuelve a ella. Con `ANTHROPIC_AUTH_TOKEN`, la variable tiene precedencia inmediatamente. Con `ANTHROPIC_API_KEY`, se le solicita una vez en modo interactivo para aprobar la clave antes de que tome el control.
184
185Ejecute `/status` para confirmar qué fuente de credencial está activa. Si el inicio muestra una advertencia de conflicto de autenticación que nombra dos fuentes, consulte la primera fila de la [tabla de solución de problemas](#troubleshoot-gateway-errors) para saber cuál descartar. Para borrar un inicio de sesión guardado para que solo permanezca la credencial de puerta de enlace, ejecute `/logout`.
186
187<h2 id="configure-each-surface">
188 Configurar cada superficie
189</h2>
190
191La CLI lee las variables de entorno y archivos de configuración anteriores. Las otras superficies son la extensión de VS Code, la aplicación de escritorio, GitHub Actions, el Agent SDK, y las superficies en la nube como Slack y la web; las secciones a continuación cubren si esa configuración llega a cada una.
192
193<h3 id="vs-code-extension">
194 Extensión de VS Code
195</h3>
196
197Establezca las variables de puerta de enlace para la [extensión de VS Code](/es/vs-code) en `claudeCode.environmentVariables`, en la configuración de usuario propia de VS Code abierta con el comando **Preferences: Open User Settings (JSON)**. La extensión comprueba las credenciales de esta configuración antes de lanzarse, por lo que es el lugar confiable para la credencial de puerta de enlace; los valores en `~/.claude/settings.json` llegan al proceso generado pero no a la comprobación de inicio de sesión propia de la extensión.
198
199```json theme={null}
200{
201 "claudeCode.environmentVariables": [
202 { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
203 { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-gateway-key" }
204 ]
205}
206```
207
208<h3 id="desktop-app">
209 Aplicación de escritorio
210</h3>
211
212La aplicación de escritorio lee el enrutamiento de puerta de enlace de una [configuración distribuida por administrador](https://claude.com/docs/cowork/3p/gateway), no de `ANTHROPIC_BASE_URL` o `settings.json`. Si su organización la ha distribuido, la aplicación de escritorio se enruta a través de la puerta de enlace sin configuración de su parte; si no, use la CLI de terminal o la extensión de VS Code para sesiones de puerta de enlace. Los administradores distribuyen la configuración como se describe en la [implementación de la organización](/es/llm-gateway-rollout#distribute-through-managed-settings).
213
214Si la aplicación de escritorio muestra `Gateway was unreachable`, la aplicación no pudo alcanzar la URL base configurada al iniciar; compruebe la URL y la ruta de red con la [prueba de curl anterior](#verify-the-connection).
215
216<h3 id="github-actions">
217 GitHub Actions
218</h3>
219
220[Claude Code GitHub Actions](/es/github-actions) lee `ANTHROPIC_BASE_URL` y `ANTHROPIC_CUSTOM_HEADERS` del bloque `env` del flujo de trabajo. Pase la credencial como la entrada `anthropic_api_key` de la acción; la acción la establece como `ANTHROPIC_API_KEY`, por lo que llega a la puerta de enlace en el encabezado `x-api-key`.
221
222Para una puerta de enlace `x-api-key`, establezca la URL base en `env` y pase la clave de puerta de enlace como entrada:
223
224```yaml theme={null}
225env:
226 ANTHROPIC_BASE_URL: https://llm-gateway.example.com
227
228steps:
229 - uses: anthropics/claude-code-action@v1
230 with:
231 anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}
232```
233
234Para una puerta de enlace de token portador, pase el mismo secreto como entrada `anthropic_api_key` y `ANTHROPIC_AUTH_TOKEN` en el bloque `env` del flujo de trabajo. La acción requiere `anthropic_api_key`, `CLAUDE_CODE_OAUTH_TOKEN`, o federación de identidad de carga de trabajo antes de lanzar Claude Code, y no lee `ANTHROPIC_AUTH_TOKEN`, por lo que la entrada satisface esa comprobación de lanzamiento mientras la variable de entorno pone la clave en el encabezado `Authorization` que la puerta de enlace lee. La copia en `x-api-key` se ignora:
235
236```yaml theme={null}
237env:
238 ANTHROPIC_BASE_URL: https://llm-gateway.example.com
239 ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}
240
241steps:
242 - uses: anthropics/claude-code-action@v1
243 with:
244 anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}
245```
246
247Para las otras opciones de autenticación de la acción, incluidas `CLAUDE_CODE_OAUTH_TOKEN` y federación de identidad de carga de trabajo, consulte [Claude Code GitHub Actions](/es/github-actions) y el [README](https://github.com/anthropics/claude-code-action#readme) de la acción.
248
249<h3 id="agent-sdk">
250 Agent SDK
251</h3>
252
253El [Agent SDK](/es/agent-sdk/overview) no tiene opciones específicas de puerta de enlace; pasa variables de entorno al proceso de Claude Code que genera. Cada SDK acepta una opción `env` que establece el entorno del proceso generado, y los SDK de TypeScript y Python lo tratan de manera diferente:
254
255* TypeScript: el proceso generado hereda el entorno principal de forma predeterminada, pero establecer `options.env` reemplaza el entorno completamente. Extienda `process.env` en él para mantener sus variables de puerta de enlace.
256* Python: `ClaudeAgentOptions(env=...)` se fusiona en el entorno heredado, por lo que las variables de puerta de enlace establecidas en el proceso principal se transmiten sin extender.
257
258<CodeGroup>
259 ```ts TypeScript theme={null}
260 const result = query({
261 prompt: "...",
262 options: {
263 env: {
264 ...process.env,
265 ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
266 ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
267 },
268 },
269 })
270 ```
271
272 ```python Python theme={null}
273 options = ClaudeAgentOptions(
274 env={
275 "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
276 "ANTHROPIC_AUTH_TOKEN": os.environ["GATEWAY_KEY"],
277 }
278 )
279 ```
280</CodeGroup>
281
282<h3 id="slack-web-and-remote-control">
283 Slack, web y Control Remoto
284</h3>
285
286[Claude Code en Slack](/es/slack) y [Claude Code en la web](/es/claude-code-on-the-web) son productos alojados por Anthropic que siempre usan la API de Anthropic; no son parte de una implementación de puerta de enlace. Las variables de puerta de enlace establecidas en la configuración de entorno de una sesión en la nube no se aplican. Si su tráfico debe permanecer en la puerta de enlace, no habilite estas superficies para esos usuarios.
287
288[Control Remoto](/es/remote-control) y [dictado de voz](/es/voice-dictation) ambos se basan en una identidad de claude.ai: Control Remoto para emparejar una sesión en vivo con su cuenta, y dictado de voz para alcanzar el punto final de transcripción de claude.ai. No están disponibles mientras `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, o un `apiKeyHelper` está activo. Para usar cualquiera de ellos, desestablezca la credencial de puerta de enlace e inicie sesión con claude.ai en su lugar; `/doctor` nombra la variable a desestablecer.
289
290<h2 id="additional-configuration">
291 Configuración adicional
292</h2>
293
294Estas configuraciones cubren casos más allá de la URL base y la credencial. Establézcalas solo si las instrucciones de su administrador o la [tabla de solución de problemas](#troubleshoot-gateway-errors) llaman a una.
295
296<h3 id="send-additional-headers">
297 Enviar encabezados adicionales
298</h3>
299
300Algunas puertas de enlace enrutan o etiquetan solicitudes usando un encabezado personalizado además de la credencial, por ejemplo un identificador de inquilino o una clave de enrutamiento. Para enviar uno, establezca [`ANTHROPIC_CUSTOM_HEADERS`](/es/env-vars) con un par `Name: Value` por línea. El ejemplo a continuación agrega un encabezado de enrutamiento llamado `X-Org-Route`:
301
302<Tabs>
303 <Tab title="Bash o Zsh">
304 ```bash theme={null}
305 export ANTHROPIC_CUSTOM_HEADERS="X-Org-Route: prod"
306 ```
307 </Tab>
308
309 <Tab title="PowerShell">
310 ```powershell theme={null}
311 $env:ANTHROPIC_CUSTOM_HEADERS = "X-Org-Route: prod"
312 ```
313 </Tab>
314</Tabs>
315
316También puede establecer `ANTHROPIC_CUSTOM_HEADERS` en el bloque `env` de un archivo de configuración. Use `\n` entre pares allí, ya que las cadenas JSON no pueden abarcar múltiples líneas:
317
318```json theme={null}
319{
320 "env": {
321 "ANTHROPIC_CUSTOM_HEADERS": "X-Org-Route: prod\nX-Tenant: acme"
322 }
323}
324```
325
326<h3 id="add-gateway-models-to-the-model-picker">
327 Agregar modelos de puerta de enlace al selector de modelos
328</h3>
329
330El descubrimiento de modelos consulta la puerta de enlace para su lista de modelos al iniciar y agrega esos nombres al selector `/model` junto con las entradas integradas.
331
332Habilítelo si su puerta de enlace sirve nombres de modelos que no están en la lista integrada de Claude Code y desea seleccionarlos del selector. Si los modelos integrados son los que usa, no necesita descubrimiento; su administrador también puede haberlo habilitado ya a través de configuración administrada.
333
334Para habilitarlo, establezca `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` en su shell o en el bloque `env` de `~/.claude/settings.json`. El descubrimiento requiere Claude Code v2.1.129 o posterior. {/* min-version: 2.1.129 */}
335
336Los modelos descubiertos aparecen como entradas `/model` adicionales etiquetadas como `From gateway`. Para confirmar que el descubrimiento se ejecutó, inicie `claude --debug` y busque las líneas `[gatewayDiscovery]`: un éxito registra cuántos modelos se almacenaron en caché, y un `404`, tiempo de espera, o redirección se registra allí también. Para cuándo se ejecuta el descubrimiento, qué filtra, y el formato de respuesta que las puertas de enlace sirven, consulte la [referencia de descubrimiento de modelos](/es/llm-gateway-protocol#model-discovery).
337
338<h3 id="rotate-credentials-with-apikeyhelper">
339 Rotar credenciales con apiKeyHelper
340</h3>
341
342Un `apiKeyHelper` es un comando que Claude Code ejecuta para obtener su credencial de puerta de enlace, en lugar de leerla de una variable de entorno estática.
343
344Use un asistente cuando la credencial expira en un cronograma, viene de un comando de almacén o SSO, o su administrador le dijo que configure uno. Si su credencial es una cadena fija que establece una vez, la [variable de credencial](#set-the-credential-variable) es todo lo que necesita y puede omitir esta sección.
345
346El asistente es cualquier comando de shell que imprime la credencial actual en stdout. Claude Code lo ejecuta a través de su shell del sistema, por lo que en Windows puede ser un ejecutable o una invocación de PowerShell. Escriba el script, hágalo ejecutable, y haga referencia a él desde `apiKeyHelper` en su [archivo de configuración](/es/settings):
347
348<Tabs>
349 <Tab title="Bash o Zsh">
350 Por ejemplo, un script que lee desde un almacén:
351
352 ```bash theme={null}
353 #!/bin/bash
354 vault kv get -field=api_key secret/llm-gateway/claude-code
355 ```
356
357 Haga referencia a su ruta en `~/.claude/settings.json`:
358
359 ```json theme={null}
360 {
361 "apiKeyHelper": "~/bin/get-gateway-key.sh"
362 }
363 ```
364 </Tab>
365
366 <Tab title="PowerShell">
367 Por ejemplo, un script que lee desde un almacén:
368
369 ```powershell theme={null}
370 vault kv get -field=api_key secret/llm-gateway/claude-code
371 ```
372
373 Haga referencia a la invocación de PowerShell en `%USERPROFILE%\.claude\settings.json`, escapando las barras invertidas en la cadena JSON:
374
375 ```json theme={null}
376 {
377 "apiKeyHelper": "powershell -NoProfile -File C:\\scripts\\get-gateway-key.ps1"
378 }
379 ```
380 </Tab>
381</Tabs>
382
383Claude Code almacena en caché la salida del asistente durante cinco minutos de forma predeterminada y lo re-ejecuta cuando una solicitud devuelve HTTP 401. Para cambiar la duración del caché, establezca `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` en milisegundos, por ejemplo `CLAUDE_CODE_API_KEY_HELPER_TTL_MS=900000` para 15 minutos.
384
385El valor del asistente se envía en los encabezados `Authorization` y `x-api-key`, por lo que funciona cualquiera que sea el encabezado que su puerta de enlace lea.
386
387<h3 id="route-to-a-cloud-provider-through-a-gateway">
388 Enrutar a un proveedor en la nube a través de una puerta de enlace
389</h3>
390
391Estas configuraciones apuntan Claude Code a una puerta de enlace a través de una variable de URL base específica del proveedor en lugar de `ANTHROPIC_BASE_URL`. Las puertas de enlace de Bedrock y Vertex aceptan los formatos de solicitud nativos de esos proveedores; las puertas de enlace de Foundry y Claude Platform en AWS aceptan el formato de Mensajes de Anthropic y difieren solo en qué variable de URL base las alcanza.
392
393Use una solo si su equipo de puerta de enlace nombró específicamente Bedrock, Vertex, Foundry, o Claude Platform en AWS. Si la [solicitud de verificación](#verify-the-connection) anterior devolvió JSON, puede omitir esta sección.
394
395Establezca el bloque para el proveedor que su equipo de puerta de enlace nombró. Las variables de omitir autenticación le dicen a Claude Code que no firme solicitudes con credenciales de proveedor, ya que la puerta de enlace tiene esas. Si la puerta de enlace necesita su propio token, agregue `ANTHROPIC_AUTH_TOKEN` después del bloque, excepto para Foundry, que usa `ANTHROPIC_FOUNDRY_API_KEY` como se muestra.
396
397<h4 id="amazon-bedrock">
398 Amazon Bedrock
399</h4>
400
401<Tabs>
402 <Tab title="Bash o Zsh">
403 ```bash theme={null}
404 export ANTHROPIC_BEDROCK_BASE_URL=https://llm-gateway.example.com/bedrock
405 export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
406 export CLAUDE_CODE_USE_BEDROCK=1
407 ```
408 </Tab>
409
410 <Tab title="PowerShell">
411 ```powershell theme={null}
412 $env:ANTHROPIC_BEDROCK_BASE_URL = "https://llm-gateway.example.com/bedrock"
413 $env:CLAUDE_CODE_SKIP_BEDROCK_AUTH = "1"
414 $env:CLAUDE_CODE_USE_BEDROCK = "1"
415 ```
416 </Tab>
417</Tabs>
418
419<h4 id="google-vertex-ai">
420 Google Vertex AI
421</h4>
422
423<Tabs>
424 <Tab title="Bash o Zsh">
425 ```bash theme={null}
426 export ANTHROPIC_VERTEX_BASE_URL=https://llm-gateway.example.com/vertex
427 export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
428 export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
429 export CLAUDE_CODE_USE_VERTEX=1
430 export CLOUD_ML_REGION=us-east5
431 ```
432 </Tab>
433
434 <Tab title="PowerShell">
435 ```powershell theme={null}
436 $env:ANTHROPIC_VERTEX_BASE_URL = "https://llm-gateway.example.com/vertex"
437 $env:ANTHROPIC_VERTEX_PROJECT_ID = "your-gcp-project-id"
438 $env:CLAUDE_CODE_SKIP_VERTEX_AUTH = "1"
439 $env:CLAUDE_CODE_USE_VERTEX = "1"
440 $env:CLOUD_ML_REGION = "us-east5"
441 ```
442 </Tab>
443</Tabs>
444
445<h4 id="microsoft-foundry">
446 Microsoft Foundry
447</h4>
448
449Ponga la credencial de la puerta de enlace en `ANTHROPIC_FOUNDRY_API_KEY`; se envía a la puerta de enlace como el encabezado `x-api-key`. `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` no se aplica aquí: sin una clave de API, el cliente de Foundry falla cada solicitud antes de que salga de la máquina.
450
451<Tabs>
452 <Tab title="Bash o Zsh">
453 ```bash theme={null}
454 export ANTHROPIC_FOUNDRY_BASE_URL=https://llm-gateway.example.com/foundry
455 export ANTHROPIC_FOUNDRY_API_KEY=sk-gateway-key
456 export CLAUDE_CODE_USE_FOUNDRY=1
457 ```
458 </Tab>
459
460 <Tab title="PowerShell">
461 ```powershell theme={null}
462 $env:ANTHROPIC_FOUNDRY_BASE_URL = "https://llm-gateway.example.com/foundry"
463 $env:ANTHROPIC_FOUNDRY_API_KEY = "sk-gateway-key"
464 $env:CLAUDE_CODE_USE_FOUNDRY = "1"
465 ```
466 </Tab>
467</Tabs>
468
469<h4 id="claude-platform-on-aws">
470 Claude Platform en AWS
471</h4>
472
473Consulte [Claude Platform en AWS](/es/claude-platform-on-aws) para el ID del espacio de trabajo.
474
475<Tabs>
476 <Tab title="Bash o Zsh">
477 ```bash theme={null}
478 export ANTHROPIC_AWS_BASE_URL=https://llm-gateway.example.com/anthropic-aws
479 export ANTHROPIC_AWS_WORKSPACE_ID=wrkspc_01ABCDEFGHIJKLMN
480 export CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH=1
481 export CLAUDE_CODE_USE_ANTHROPIC_AWS=1
482 ```
483 </Tab>
484
485 <Tab title="PowerShell">
486 ```powershell theme={null}
487 $env:ANTHROPIC_AWS_BASE_URL = "https://llm-gateway.example.com/anthropic-aws"
488 $env:ANTHROPIC_AWS_WORKSPACE_ID = "wrkspc_01ABCDEFGHIJKLMN"
489 $env:CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH = "1"
490 $env:CLAUDE_CODE_USE_ANTHROPIC_AWS = "1"
491 ```
492 </Tab>
493</Tabs>
494
495<h2 id="troubleshoot-gateway-errors">
496 Solucionar problemas de errores de puerta de enlace
497</h2>
498
499Estos son los errores más comunes al ejecutar Claude Code a través de una puerta de enlace, con la causa del lado de la puerta de enlace y la solución:
500
501| Error | Causa | Solución |
502| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
503| Una advertencia de inicio que nombra dos fuentes de credencial y termina en `auth may not work as expected`. Las versiones más antiguas muestran `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set` en su lugar. | Una credencial de puerta de enlace y un inicio de sesión guardado están ambos activos; la variable se usa para solicitudes, pero el inicio de sesión obsoleto puede causar comportamiento de autenticación inesperado | Desestablezca la variable para usar el inicio de sesión guardado, o ejecute `/logout` para usar la credencial de puerta de enlace |
504| Errores `401` que nombran un token inválido o no reconocido | La credencial no es una que la puerta de enlace emitió, o está en un encabezado que la puerta de enlace no lee | Confirme que la variable coincida con su tipo de credencial en la [tabla de credencial](#set-the-credential-variable), y regenere la clave en la puerta de enlace si fue revocada |
505| `Unable to connect to API (ConnectionRefused)`, o `(ECONNREFUSED)` de instalaciones de npm, a menudo después de una pausa silenciosa mientras Claude Code [reintenta con retroceso](/es/errors#automatic-retries) | Nada respondió en la URL base: la dirección es incorrecta, o una VPN o firewall bloquea la ruta a la puerta de enlace | Ejecute la [prueba de curl anterior](#verify-the-connection), que falla inmediatamente con la misma causa, y confirme la URL y la ruta de red con su equipo de puerta de enlace |
506| `API returned an empty or malformed response (HTTP 200)` | La puerta de enlace o un proxy intermedio devolvió una respuesta que no es de API, a menudo una página de error HTML o de inicio de sesión | Pruebe con la [solicitud de curl anterior](#verify-the-connection); corrija la ruta de puerta de enlace que devuelve JSON no válido |
507| Errores `400` que nombran `context_management`, `Extra inputs are not permitted`, u otros campos no reconocidos | La puerta de enlace reenvía solicitudes a un upstream que rechaza campos que Claude Code envía a puntos finales en formato de Anthropic | Establezca `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`, que suprime la mayoría de campos de pre-lanzamiento; consulte [paso de características](/es/llm-gateway-protocol#feature-pass-through). Algunos betas no están controlados por esta bandera; para esos, establezca la variable de proveedor `CLAUDE_CODE_USE_*` coincidente para que Claude Code envíe solo lo que ese proveedor acepta |
508| Errores `400` que nombran `thinking` o `adaptive`, como `Input tag 'adaptive' found` | La compilación del modelo upstream no acepta razonamiento adaptativo, que Claude Code solicita para modelos Claude 4.6 y posteriores | Actualice el upstream de la puerta de enlace. En Opus 4.6 y Sonnet 4.6, `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` funciona en su lugar. Las variables de capacidad de [configuración de modelo](/es/model-config) se aplican solo a las configuraciones de proveedor, como `CLAUDE_CODE_USE_BEDROCK` y `CLAUDE_CODE_USE_VERTEX`, no detrás de una puerta de enlace `ANTHROPIC_BASE_URL` |
509| Errores `400` que indican un contexto o límite de token en las propias palabras de la puerta de enlace, como `ContextWindowExceededError` o `prompt token count of N exceeds the limit of M` | La puerta de enlace aplica un contexto más pequeño que la ventana nativa del modelo y reescribe el error upstream, por lo que el compacto automático y reintento, que coincide con la redacción `prompt is too long` de Anthropic, no se dispara | Ejecute `/compact` para recuperar la sesión. Para prevenirlo, establezca `CLAUDE_CODE_AUTO_COMPACT_WINDOW` al límite de la puerta de enlace; el valor se fija a al menos 100,000 tokens y como máximo la ventana de contexto del modelo, por lo que un límite de puerta de enlace por debajo de 100,000 no puede coincidir y `/compact` permanece como la recuperación allí. También establezca `CLAUDE_CODE_MAX_OUTPUT_TOKENS` por debajo del límite de salida del modelo de puerta de enlace |
510| Modelos faltantes del selector `/model` | Los nombres de modelos de puerta de enlace no están en la lista integrada de Claude Code | Habilite [descubrimiento de modelos de puerta de enlace](#add-gateway-models-to-the-model-picker) o agregue nombres con las variables de [configuración de modelo](/es/model-config) |
511| Claude Code le pide que inicie sesión aunque la [prueba de curl](#verify-the-connection) tenga éxito | La CLI no tiene credencial propia: una URL base alcanzable no es una, y un bloque `env` en el `.claude/settings.json` o `.claude/settings.local.json` de un proyecto se aplica solo después del asistente de primera ejecución y la solicitud de confianza | Establezca `ANTHROPIC_AUTH_TOKEN` en algún lugar que Claude Code lea antes de la configuración de primera ejecución: una exportación de shell, el bloque `env` en `~/.claude/settings.json`, o configuración administrada |
512| `ANTHROPIC_API_KEY` está establecido pero ignorado, sin solicitud | La clave necesita una aprobación única en sesiones interactivas, y una clave previamente rechazada se ignora sin preguntar de nuevo | Habilítela bajo `/config` con la opción `Use custom API key` |
513| `This machine's managed settings require a first-party login` | La configuración administrada incluye `forceLoginMethod` o `forceLoginOrgUUID`, que en Claude Code v2.1.146 y posterior no pueden coexistir con `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, o `apiKeyHelper` | Su administrador debe eliminar `forceLoginMethod` y `forceLoginOrgUUID` de la configuración administrada para usar credenciales de puerta de enlace, o eliminar la credencial de puerta de enlace para usar inicio de sesión de primera parte. Los dos no pueden combinarse |
514| `403` con un cuerpo HTML como `403 Forbidden`, cuando los registros propios de la puerta de enlace no muestran ninguna solicitud recibida | Un firewall de aplicación web o proxy inverso frente a la puerta de enlace bloqueó el cuerpo de la solicitud antes de que llegara a la puerta de enlace. Los avisos de Claude Code incluyen etiquetas de estilo XML y código fuente que coinciden con reglas de cuerpo de secuencias de comandos entre sitios, por lo que una prueba de curl corta pasa mientras una sesión real no | Exima la ruta `/v1/messages` de la puerta de enlace de la inspección del cuerpo de la solicitud. En AWS WAF esta es la regla administrada `CrossSiteScripting_Body`; en nginx con ModSecurity es la regla de cuerpo OWASP CRS equivalente |
515| Errores de certificado o TLS como `SSL certificate verification failed` o `Self-signed certificate detected`, cuando la [prueba de curl](#verify-the-connection) tiene éxito | El tiempo de ejecución de Claude Code no está confiando en la misma autoridad de certificación que `curl` usa. Común detrás de proxies de inspección TLS corporativos | Establezca `NODE_EXTRA_CA_CERTS` a la ruta del paquete de CA; consulte [almacén de certificados de CA](/es/network-config#ca-certificate-store) |
516
517Si Claude Code le solicita que inicie sesión repetidamente después de eliminar la configuración de puerta de enlace, la causa es generalmente almacenamiento de credenciales en lugar de la puerta de enlace; consulte [errores de autenticación](/es/errors#authentication-errors).
518
519<h2 id="related-resources">
520 Recursos relacionados
521</h2>
522
523* [Descripción general de puertas de enlace LLM](/es/llm-gateway): qué es una puerta de enlace y cómo interactúa con las suscripciones de claude.ai
524* [Implementar una puerta de enlace LLM para su organización](/es/llm-gateway-rollout): la lista de verificación orientada al administrador para implementar y distribuir la configuración de puerta de enlace
525* [Referencia del protocolo de puerta de enlace](/es/llm-gateway-protocol): qué envía Claude Code a una puerta de enlace, incluidos los encabezados y campos que la puerta de enlace debe reenviar
526* [Configuración](/es/settings): dónde viven los archivos de configuración y cómo se lee el bloque `env`
527* [Autenticación](/es/authentication): cómo interactúan las variables de credencial, `apiKeyHelper`, e inicio de sesión OAuth
