Configuración de red empresarial

Configure Claude Code para entornos empresariales con servidores proxy, Autoridades de Certificación (CA) personalizadas y autenticación mutua de Seguridad de la Capa de Transporte (mTLS).

Claude Code admite varias configuraciones de red y seguridad empresarial a través de variables de entorno. Esto incluye enrutar el tráfico a través de servidores proxy corporativos, confiar en Autoridades de Certificación (CA) personalizadas y autenticarse con certificados de Seguridad de la Capa de Transporte mutua (mTLS) para mayor seguridad.

Establezca estas variables de entorno antes de iniciar Claude Code. Las variables exportadas en su shell se leen una sola vez al inicio, por lo que una sesión en ejecución no recoge cambios posteriores en su entorno de shell.

Configuración de proxy

Variables de entorno

Claude Code respeta las variables de entorno de proxy estándar. En sesiones de Claude Desktop donde la aplicación gestiona la conexión del proveedor, Claude Code las lee solo desde la configuración gestionada y ~/.claude/settings.json; consulte autenticación mTLS para las reglas de alcance.

# Proxy HTTPS (recomendado)
export HTTPS_PROXY=https://proxy.example.com:8080

# Proxy HTTP (si HTTPS no está disponible)
export HTTP_PROXY=http://proxy.example.com:8080

# Omitir proxy para solicitudes específicas - formato separado por espacios
export NO_PROXY="localhost 192.168.1.1 example.com .example.com"
# Omitir proxy para solicitudes específicas - formato separado por comas
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"
# Omitir proxy para todas las solicitudes
export NO_PROXY="*"

Las variantes en minúsculas también funcionan, y Claude Code utiliza la primera que esté configurada en el orden https_proxy, HTTPS_PROXY, http_proxy, HTTP_PROXY.

Claude Code nunca envía sus conexiones WebSocket a localhost, ::1, o 127.0.0.0/8 a través del proxy, por lo que no necesita una entrada de loopback en NO_PROXY para ellas.

Autenticación básica

Si su proxy requiere autenticación básica, incluya las credenciales en la URL del proxy:

export HTTPS_PROXY=http://username:password@proxy.example.com:8080

Almacén de certificados CA

De forma predeterminada, Claude Code confía tanto en sus certificados CA de Mozilla incluidos como en el almacén de certificados de su sistema operativo. La lectura del almacén del sistema operativo requiere un tiempo de ejecución con tls.getCACertificates: el instalador nativo siempre lo tiene, y las instalaciones de npm necesitan Node 22.15 o posterior. En versiones anteriores de Node, solo se aplican el conjunto incluido y NODE_EXTRA_CA_CERTS. Los proxies de inspección TLS empresariales funcionan sin configuración adicional cuando su certificado raíz se instala en el almacén de confianza del sistema operativo y el tiempo de ejecución puede leerlo.

CLAUDE_CODE_CERT_STORE acepta una lista separada por comas de fuentes. Los valores reconocidos son bundled para el conjunto de CA de Mozilla incluido con Claude Code y system para el almacén de certificados del sistema operativo. El valor predeterminado es bundled,system.

Para confiar solo en el conjunto de CA de Mozilla incluido:

export CLAUDE_CODE_CERT_STORE=bundled

Para confiar solo en el almacén de certificados del sistema operativo:

export CLAUDE_CODE_CERT_STORE=system

Certificados CA personalizados

Si su entorno empresarial utiliza una CA personalizada, configure Claude Code para confiar en ella directamente:

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

Autenticación mTLS

Para entornos empresariales que requieren autenticación de certificado de cliente:

# Certificado de cliente para autenticación
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem

# Clave privada del cliente
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem

# Opcional: Frase de contraseña para clave privada cifrada
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"

Claude Code lee los archivos de certificado y clave al iniciar y los vuelve a leer cada vez que aplica configuración, como cuando su organización cambia el bloque env en configuración administrada a mitad de sesión.

Para rotar el certificado y la clave, reemplace los archivos en las mismas rutas. Claude Code recoge el reemplazo en una sesión en ejecución sin necesidad de reiniciar. Cuando una solicitud de API falla con un error a nivel de conexión, como un restablecimiento de conexión o un error de protocolo de enlace TLS, vuelve a leer ambos archivos e intenta nuevamente la solicitud con el nuevo par. Antes de v2.1.232, Claude Code no volvía a leer en errores de conexión, por lo que mantenía el par que ya había cargado hasta que aplicaba configuración nuevamente o usted reiniciaba.

Claude Code vuelve a leer los archivos en respuesta a solicitudes fallidas, no observando cambios en ellos:

• Tiempo: Claude Code no hace nada en el momento en que reemplaza los archivos. Presenta el nuevo par en el reintento después de una falla calificada, o en la siguiente solicitud después de que aplica configuración, lo que ocurra primero.
• Rechazos de puerta de enlace: Claude Code vuelve a leer cuando su puerta de enlace restablece la conexión o rechaza el protocolo de enlace TLS después de que deja de aceptar el par anterior. No vuelve a leer cuando la puerta de enlace completa el protocolo de enlace y responde con un error HTTP. En ese caso, Claude Code carga el nuevo par cuando aplica configuración nuevamente o cuando lo reinicia.
• Rotaciones parcialmente escritas: cuando Claude Code vuelve a leer mientras su rotación está a mitad de escritura, como leer un certificado y clave que no coinciden entre sí, mantiene el par anterior y vuelve a leer en la siguiente falla.
• Exportadores de telemetría OTLP: Claude Code mantiene el certificado que los exportadores cargaron en el primer uso, por lo que reinicie Claude Code para que un certificado rotado llegue a su recopilador de telemetría.
• Desactivar la recarga: establezca CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION=1 para desactivar la recarga de error de conexión. Claude Code recoge archivos rotados solo cuando aplica configuración nuevamente o en el siguiente inicio.

Para confirmar que Claude Code recogió una rotación, inicie la sesión con registro de depuración y busque Stale connection — reloaded rotated mTLS client material en el registro. Claude Code no registra esta línea cuando recoge la rotación mientras aplica configuración en su lugar, por lo que una línea faltante por sí sola no significa que la rotación haya fallado.

Reemplace los archivos antes de que expire el par actual para que Claude Code no cargue un par ya expirado en el siguiente inicio.

En sesiones en la nube, el entorno de alojamiento administra la conexión a la API, por lo que Claude Code ignora las siguientes variables cuando provienen de un bloque env de archivo de configuración:

• CLAUDE_CODE_CLIENT_CERT
• CLAUDE_CODE_CLIENT_KEY
• CLAUDE_CODE_CLIENT_KEY_PASSPHRASE
• NODE_EXTRA_CA_CERTS
• NODE_TLS_REJECT_UNAUTHORIZED
• CLAUDE_CODE_OAUTH_SCOPES

Claude Code anota cada clave ignorada en el registro de depuración de la sesión.

En sesiones de Claude Desktop donde la aplicación administra la conexión del proveedor, como la pestaña Code en un proveedor de terceros y sesiones de Cowork, Claude Code lee estas variables y las variables proxy HTTP_PROXY, HTTPS_PROXY y NO_PROXY solo desde configuración administrada y ~/.claude/settings.json: las ignora en los archivos de configuración propios de un repositorio, por lo que un repositorio extraído no puede redirigir la ruta TLS o proxy de una sesión cuyas credenciales provienen de la aplicación. En una sesión de pestaña Code local, SSH o WSL con sesión iniciada a través de claude.ai, la aplicación no administra la conexión, y Claude Code lee estas variables desde cada ámbito de configuración, como cualquier sesión de terminal; las sesiones en la nube siguen las reglas de sesión en la nube anteriores dondequiera que las inicie. Antes de v2.1.217, Claude Code ignoraba estas variables en cada archivo de configuración cuando la aplicación administraba la conexión.

Verificar su configuración

Generalmente se entera de una dirección de proxy incorrecta o una ruta de certificado incorrecta a partir de un error de conexión o certificado en una solicitud posterior, ya que Claude Code no valida la mayoría de estas configuraciones cuando las lee. La única configuración que verifica al iniciar es la URL del proxy: cuando no puede analizar el valor, como uno que carece del esquema http://, Claude Code detiene el lanzamiento con un error que nombra la variable a corregir.

Para confirmar que su configuración se cargó antes de enviar una solicitud, inicie Claude Code con registro de depuración:

claude --debug

La salida de depuración va a ~/.claude/debug/<session-id>.txt en lugar de la terminal, o a una ruta que establezca con --debug-file <path>. En el registro, busque las líneas que confirmen que cada archivo se cargó:

CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS (/etc/ssl/certs/corp-ca.pem)
mTLS: Loaded client certificate from CLAUDE_CODE_CLIENT_CERT
mTLS: Loaded client key from CLAUDE_CODE_CLIENT_KEY

Si Claude Code no puede leer uno de estos archivos, el registro muestra una línea Failed to read o Failed to load con la razón en su lugar.

También puede ejecutar /status en una sesión interactiva y verificar estas filas:

• Proxy: muestra la URL del proxy activo y marca un valor que no puede analizar como inválido e ignorado.
• mTLS client cert y mTLS client key: aparecen solo cuando los archivos se cargaron, por lo que una fila faltante significa que la carga falló y el registro de depuración tiene la razón.
• Additional CA cert(s): muestra la ruta NODE_EXTRA_CA_CERTS sin verificar que el archivo se cargó, así que confirme este en el registro de depuración.

Aplicar configuración de red a agentes en segundo plano

Los agentes en segundo plano no se ejecutan dentro de la terminal que los envió. Un proceso supervisor por usuario se inicia bajo demanda, sobrevive a su shell y aloja cada sesión de claude agents, --bg y /background. Consulte Cómo se alojan las sesiones en segundo plano. Esto cambia cómo la configuración en esta página llega a esas sesiones.

Establecer variables de red en la configuración, no en el shell

El supervisor es un proceso compartido por cada terminal. Hereda el entorno del shell que lo inicia primero, y un supervisor instalado por el sistema operativo no recibe ningún entorno de shell. Si exporta un proxy, ruta de CA o variable de mTLS solo en su shell, llega a los agentes en segundo plano cuando ese shell sucedió a iniciar en frío el supervisor, y silenciosamente no llega cuando un shell diferente lo hizo.

Coloque las mismas variables en el bloque env de ~/.claude/settings.json o configuración administrada en su lugar. Cada variable en esta página se puede establecer allí, y la configuración es la única que llega a cada sesión en segundo plano en cada máquina.

Configurar un iniciador corporativo como una configuración

Algunas organizaciones requieren que cada proceso de Claude Code se inicie a través de un iniciador corporativo que aplique sandboxing, controles de red o inyección de credenciales. El supervisor y sus trabajadores inician Claude Code desde una ruta fija en lugar de buscar claude en PATH, por lo que cada agente en segundo plano omite un contenedor que coloca anteriormente en PATH.

Establezca la configuración processWrapper para prefijar el supervisor, sus trabajadores y los otros procesos en segundo plano enumerados en Qué cubre el iniciador con su iniciador. La variable de entorno equivalente CLAUDE_CODE_PROCESS_WRAPPER tiene prioridad cuando ambas se establecen, y está sujeta a la misma regla: entréguela a través de la configuración administrada o ~/.claude/settings.json, no una exportación de shell. Ejecutar Claude Code detrás de un iniciador corporativo cubre el contrato que el iniciador debe satisfacer, qué alcanza y qué no alcanza, y cómo implementarlo.

Perros guardianes de inactividad en streaming

Claude Code ejecuta cuatro temporizadores independientes que abortan una respuesta de modelo en streaming cuando se queda en silencio, de modo que una conexión muerta falla y se reintenta en lugar de quedarse colgada. El plazo de primer byte cubre la espera de encabezados de respuesta, antes de que haya llegado ninguna parte de la respuesta. Cada uno de los otros tres supervisa una respuesta activa para una señal diferente.

Configure los temporizadores con estas variables, cada una detallada en la referencia de variables de entorno:

• CLAUDE_ENABLE_STREAM_WATCHDOG y CLAUDE_ENABLE_BYTE_WATCHDOG fuerzan el perro guardián correspondiente activado con 1 o desactivado con 0, dentro de los tipos de conexión que la tabla enumera; ninguna variable extiende un perro guardián a un tipo de conexión que no cubre. CLAUDE_ENABLE_BYTE_WATCHDOG establecido en 0 también desactiva el plazo de primer byte.
• CLAUDE_STREAM_IDLE_TIMEOUT_MS establece el tiempo de espera de ambos perros guardianes. Claude Code eleva los valores por debajo de 5 minutos a 5 minutos, y limita el valor a 30 minutos para el perro guardián a nivel de byte.
• CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS establece el tiempo de espera del perro guardián a nivel de byte sin cambiar el del perro guardián a nivel de evento, limitado entre 10 segundos y 30 minutos, y tiene prioridad sobre CLAUDE_STREAM_IDLE_TIMEOUT_MS para ese perro guardián.
• CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS establece el plazo de primer byte directamente. Déjelo sin establecer y Claude Code usa el tiempo de espera del perro guardián a nivel de byte, de modo que CLAUDE_STREAM_IDLE_TIMEOUT_MS y CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS también cambian el plazo. Para los límites, la asignación de carga, el límite de API_TIMEOUT_MS y cuánto tiempo espera el reintento después de un aborto sin respuesta, consulte Sin respuesta de la API.
• API_FORCE_IDLE_TIMEOUT establecido en 0 desactiva el tiempo de espera de inactividad del cuerpo, y establecido en 1 lo activa para cada proveedor. Los perros guardianes se ejecutan independientemente de él, por lo que para permitir que un stream se pause más tiempo que sus umbrales, también aumente o desactive los perros guardianes.

Cuando un perro guardián aborta un stream estancado, Claude Code trata el aborto como una falla a mitad de stream, y lo que ve depende de cuán lejos haya llegado la respuesta. Claude Code reintenta la solicitud o termina el turno con un error, mantiene la salida completada y muestra un aviso de respuesta incompleta, o termina el turno normalmente. Reintentos automáticos dice dónde se aplica cada resultado.

En una sesión no interactiva, y para la respuesta de un subagente en cualquier sesión, Claude Code puede primero solicitar a Claude que continúe la respuesta cortada; la entrada de ese aviso dice cuándo lo hace y cuándo aún ve el aviso.

Cuando se activa el plazo de primer byte, no ha comenzado ninguna respuesta, por lo que no hay salida parcial para mantener. Para saber cómo Claude Code reenvía la solicitud y cuándo termina el turno en su lugar, consulte Sin respuesta de la API.

Requisitos de acceso a la red

Claude Code requiere acceso a las siguientes URLs. Agregue estas a la lista de permitidos en su configuración de proxy y reglas de firewall, especialmente en entornos de red en contenedores o restringidos. La verificación de conectividad de configuración de primera ejecución apunta aquí cuando no puede alcanzar api.anthropic.com o platform.claude.com; consulte No se puede conectar a los servicios de Anthropic para los mensajes de la verificación y los pasos de recuperación.

Si instala Claude Code a través de npm o administra su propia distribución binaria, los usuarios finales no necesitan los usos del instalador nativo y actualizador automático de downloads.claude.ai, pero las instalaciones de npm y bun necesitan su registro de paquetes, registry.npmjs.org, a menos que su organización lo refleje. Los otros usos en la tabla se aplican independientemente del método de instalación.

Los dos hosts de ingesta de Datadog llevan solo telemetría operativa opcional, y establecer CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC deshabilita ambos. Las sesiones en proveedores de terceros nunca envían a estos hosts, incluso cuando una plataforma establece CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST y las métricas de telemetría están habilitadas de forma predeterminada. Consulte Servicios de telemetría para todo lo que Claude Code envía y cómo deshabilitarlo antes de finalizar su lista de permitidos.

Cuando se usa Amazon Bedrock, Agent Platform de Google Cloud, Microsoft Foundry o una sesión de puerta de enlace de aplicaciones Claude con sesión iniciada, el tráfico del modelo y la autenticación van a su proveedor o puerta de enlace en lugar de api.anthropic.com, claude.ai o platform.claude.com. La herramienta WebFetch aún llama a api.anthropic.com para su verificación de seguridad de dominio a menos que establezca skipWebFetchPreflight: true en configuración.

Cuando se enruta a través de una puerta de enlace LLM con ANTHROPIC_BASE_URL, la verificación de disponibilidad de modo rápido aún llama a api.anthropic.com en lugar de la URL base de la puerta de enlace. La verificación respeta un proxy HTTP configurado, por lo que donde un bloqueo de red es la causa, una entrada de lista de permitidos para api.anthropic.com en el proxy es la solución. Un bloqueo de red falla la verificación solo donde el host es inaccesible incluso a través del proxy, y el modo rápido luego reporta un error de conectividad. El mismo error de conectividad aparece cuando la verificación presenta una credencial emitida por la puerta de enlace que Anthropic rechaza; la lista de permitidos no ayuda allí, ya que nada está bloqueado. Consulte usar modo rápido detrás de proxies y puertas de enlace LLM para las variables que lo restauran.

Listas de permitidos de IP de la organización y salida de proxy

Si su organización tiene lista de permitidos de IP habilitada para Claude, enrute bridge.claudeusercontent.com a través del mismo proxy de salida que claude.ai y api.anthropic.com, por ejemplo colocándolo en el mismo segmento de aplicación de Zscaler o política de dirección de Netskope. Si no puede enrutarlo de esa manera, agregue la dirección de salida que su proxy usa para ese host a la lista de permitidos de IP de su organización, pero solo cuando esa dirección está dedicada a su organización: un rango de salida de proxy compartido también admite a otros clientes del proveedor de proxy.

Anthropic verifica las conexiones a bridge.claudeusercontent.com contra la lista de permitidos de IP de su organización usando la dirección desde la que llegan. Si su proxy envía tráfico para ese host a través de una dirección que no está en esa lista de permitidos, Claude Code no puede conectarse a la extensión Claude en Chrome aunque el resto de Claude Code funcione.

Listas de permitidos de GitHub y firewalls

Claude Code en la web en entornos alojados por Anthropic y Code Review se conectan a sus repositorios desde infraestructura administrada por Anthropic; las sesiones en un entorno autohospedado se conectan desde dentro de su red, a menos que el ejecutor opte por el proxy git de Anthropic, que obtiene desde el lado de Anthropic.

Si su organización de GitHub Enterprise Cloud restringe el acceso por dirección IP, habilite herencia de lista de permitidos de IP para aplicaciones GitHub instaladas y también agregue una entrada de lista de permitidos para las direcciones IP salientes de Anthropic. La herencia cubre solo las solicitudes que realiza la aplicación GitHub de Claude como instalación, no las solicitudes que realiza en nombre de sus usuarios. Para otros firewalls, consulte las direcciones IP de la API de Anthropic.

Para instancias de GitHub Enterprise Server autohospedadas detrás de un firewall, agregue a la lista de permitidos las direcciones IP salientes de Anthropic para que la infraestructura de Anthropic pueda alcanzar su host GHES para clonar repositorios y publicar comentarios de revisión. Las sesiones en un entorno autohospedado alcanzan su host GHES desde dentro de su red en su lugar, por lo que esa exposición se aplica solo a sesiones alojadas por Anthropic, a flujos previos a la sesión alojados como el selector de repositorio, y a ejecutores autohospedados que opten por el proxy git de Anthropic, que obtiene desde el lado de Anthropic. Para un host GHES que solo es enrutable dentro de su red, el conector SCM lleva los flujos previos a la sesión alojados sobre una conexión saliente en su lugar, por lo que la lista de permitidos no es necesaria para ellos.

Escritorio y claude.ai

La tabla anterior cubre la CLI independiente. La aplicación Claude Desktop y claude.ai en un navegador cargan su código de aplicación y contenido del usuario desde hosts CDN adicionales de Anthropic, incluidos assets-proxy.anthropic.com y los otros orígenes *.claudeusercontent.com que sirven artefactos en esas aplicaciones. Permitir claude.ai mientras se bloquean esos hosts produce una página en blanco en lugar de un error. Consulte requisitos de acceso a la red en la página de Desktop.

Un artefacto que carga una fuente tipográfica desde Google Fonts también solicita fonts.googleapis.com y fonts.gstatic.com. Ambos hosts son opcionales. Si los bloquea, los artefactos se renderizan en fuentes tipográficas alternativas. Bloquee con un rechazo rápido en lugar de una caída silenciosa para que la solicitud de fuente falle inmediatamente en lugar de retrasar el primer renderizado de la página.

Los artefactos también pueden cargar bibliotecas de JavaScript, como React o un paquete de gráficos, desde cdnjs.cloudflare.com, cdn.jsdelivr.net, cdn.tailwindcss.com, code.jquery.com y unpkg.com, y desde ningún otro host externo. Si bloquea esos hosts, las partes de un artefacto que dependen de una biblioteca no funcionan, y a diferencia de una fuente bloqueada, una biblioteca bloqueada no tiene alternativa. Bloquee con un rechazo rápido aquí también, para que una solicitud de biblioteca bloqueada falle de inmediato en lugar de colgarse hasta que se agote el tiempo de espera.

Recursos adicionales

• Archivos de configuración y precedencia
• Referencia de variables de entorno
• Guía de solución de problemas