El día 1 se gana o se pierde en el proxy

Módulo 3 · Arquitectura de despliegue · Lección 3 de 5

Al terminar esta lección podrás configurar Claude Code para una red corporativa con proxy e inspección TLS, y entregar al equipo de red del cliente la lista exacta de dominios que te va a pedir.

Dónde se rompen las instalaciones

El primer ticket de soporte de toda activación empresarial es un ticket de red

El plan de activación lo llama “soporte de configuración: confirmar bloqueos antes del kickoff”. En la práctica significa una sola cosa: averiguar qué hay entre la terminal del desarrollador y el endpoint del modelo antes de que cuarenta personas instalen al mismo tiempo.

Pueden existir dos componentes distintos en ese camino, y resuelven problemas diferentes. Un proxy corporativo enruta el tráfico saliente a través del perímetro de red del cliente, para monitoreo y cumplimiento de políticas; configuras Claude Code para que lo atraviese. Un gateway LLM se sitúa delante del proveedor del modelo para gestionar autenticación, presupuestos y atribución de uso; eso corresponde a la lección 3.4. Se apilan: muchos clientes tienen ambos. Esta lección cubre la mitad de perímetro, y es trabajo puro de pre-kickoff, porque el modo de falla son cuarenta desarrolladores con terminales colgadas en la primera hora de la semana 1.

Componente	Función	Dónde se trata
Proxy corporativo	Saca el tráfico del edificio: proxy HTTP/HTTPS, inspección TLS y allowlists del firewall. Claude Code respeta las variables de entorno estándar de proxy. Lo administran los equipos de red y seguridad.	Esta lección
Gateway LLM	Controla lo que ocurre con el tráfico del modelo: autenticación centralizada, seguimiento de uso, presupuestos y auditoría. Es un servicio que el cliente despliega deliberadamente, no plomería de perímetro que ya tiene. Se configura mediante overrides de la base URL, no con variables de proxy.	Lección 3.4

flowchart LR
    T["Terminal del desarrollador (Claude Code)"] --> P["Proxy corporativo: sale del perímetro"]
    P --> G["Gateway LLM, si el cliente lo despliega (lección 3.4)"]
    G --> M["Endpoint del modelo"]

Las variables de proxy

Cuatro variables de entorno cubren la mayoría de las redes

Detalle de configuración a continuación, para desarrolladores y arquitectos. Si eres consultor de negocio, puedes saltar a la sección «La conversación sobre la allowlist».

# Enruta Claude Code a través del proxy corporativo
export HTTPS_PROXY=https://proxy.client.com:8080
# Alternativa HTTP si el proxy no tiene endpoint HTTPS
export HTTP_PROXY=http://proxy.client.com:8080
# Mantén los hosts internos fuera del proxy (separados por coma o espacio)
export NO_PROXY="localhost,.client.com,169.254.169.254"
# ¿El proxy requiere autenticación básica? Las credenciales van en la URL,
# obtenidas desde un gestor de secretos, nunca hardcodeadas en un script
export HTTPS_PROXY=http://user:[email protected]:8080

Las variables de proxy son a nivel de sistema operativo y no pueden configurarse desde los archivos de ajustes de Claude Code. Para desplegarlas en toda la organización, usa MDM: Jamf o Kandji en macOS, y la política del registro de Windows en Windows. Hay dos límites que conviene conocer antes de que lo pregunte el cliente:

• Descarta los proxies SOCKS: no son compatibles. Si el cliente usa SOCKS para otras herramientas de ingeniería, no es una ruta viable para Claude Code.
• Escala la autenticación NTLM o Kerberos al gateway: Claude Code no puede hablar directamente ninguno de esos dos protocolos. Un gateway LLM que gestione la autenticación empresarial es la respuesta, una razón más por la que importa la lección 3.4.

Inspección TLS y confianza

«Self-signed certificate in chain» significa que el proxy funciona como fue diseñado

Los proxies con inspección TLS, como Zscaler o Netskope, vuelven a firmar el tráfico con la CA raíz corporativa. Claude Code confía por defecto en el almacén de confianza del sistema operativo, así que en una flota bien administrada normalmente funciona sin más.

Cuando no funciona, el certificado raíz corporativo no está donde Node puede verlo. La solución es apuntar directamente a él, no desactivar la verificación. Cualquier sugerencia de desactivar las comprobaciones TLS no pasa la revisión de seguridad del propio cliente, y no debería pasarla.

flowchart TD
    A["Error: self-signed certificate in certificate chain"] --> B{"¿La CA raíz corporativa está en el almacén de confianza del sistema?"}
    B -->|"Sí"| C["Claude Code funciona sin cambios"]
    B -->|"No"| D["Definir NODE_EXTRA_CA_CERTS con el certificado raíz corporativo"]
    D --> C

# Confía directamente en la CA raíz corporativa
export NODE_EXTRA_CA_CERTS=/etc/ssl/corp-root-ca.pem
# Controla qué almacenes de confianza se usan (por defecto: system)
export CLAUDE_CODE_CERT_STORE=system
# Entornos con certificado de cliente (mTLS)
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem

La conversación sobre la allowlist

«¿Qué dominios necesita esta herramienta?» merece una respuesta preparada

El equipo de red lo preguntará. Entregarles la lista en la primera reunión, con la justificación de cada dominio, es la diferencia entre una aprobación en la misma semana y una solicitud de cambio de tres semanas.

Categoría	Dominio	Qué cubre
Modelo y API	api.anthropic.com	Solicitudes de la API de Claude en la ruta directa, y la verificación de seguridad de dominio de WebFetch en todas las rutas. Si lo bloqueas en un despliegue de Bedrock, WebFetch falla aunque el tráfico del modelo fluya bien, a menos que la configuración desactive la verificación previa (preflight).
Autenticación	claude.ai · platform.claude.com	Autenticación de cuentas de claude.ai y de Console, respectivamente. En Bedrock, Vertex y Foundry, la autenticación va al proveedor de nube, así que estos dominios importan sobre todo en la ruta directa.
Distribución	downloads.claude.ai	Instalador nativo, actualizador automático y descarga de ejecutables de plugins. Los clientes que distribuyen Claude Code desde su propio registro de artefactos a menudo pueden omitirlo para los usuarios finales.
Rutas de nube	Endpoints del proveedor, en su lugar	En Bedrock, Vertex o Foundry, el tráfico del modelo y de autenticación va a los endpoints del proveedor, que normalmente ya son alcanzables. La telemetría opcional hacia Anthropic viene desactivada por defecto, como se indicó en la lección 3.2. Verifica la postura final con /status dentro de Claude Code.

Una vez aprobada la allowlist, la siguiente pregunta de TI suele ser: “¿Cómo nos aseguramos de que cada desarrollador use la configuración correcta?”. Para eso existen las managed settings.

Qué son las managed settings

La capa de políticas a nivel de organización

managed-settings.json se sitúa en la parte superior de la jerarquía de ajustes de Claude Code, por encima de los ajustes de usuario y de proyecto. Las reglas definidas ahí no pueden ser sobrescritas por desarrolladores individuales. Úsalas para bloquear permisos, imponer los servidores MCP permitidos, exigir inicio de sesión por SSO y fijar versiones mínimas en toda la organización.

flowchart TD
    M["managed-settings.json (política de la organización)"] -->|"por encima de, no sobrescribible"| U["Ajustes de usuario"]
    M -->|"por encima de, no sobrescribible"| P["Ajustes de proyecto"]

Cómo llega a las máquinas de los desarrolladores

Hay tres vías de entrega:

• Administrada en el servidor mediante la consola de administración de Anthropic. Solo para Enterprise.
• MDM o a nivel de sistema operativo: plist en macOS o registro en Windows; despliégala con Jamf, Kandji o herramientas similares.
• Basada en archivo: escribe managed-settings.json en el directorio del sistema del sistema operativo.

Las tres requieren derechos de administrador, que es precisamente el punto.

flowchart LR
    A["Consola de administración de Anthropic (solo Enterprise)"] --> D["Máquina del desarrollador"]
    B["MDM: plist en macOS o registro en Windows"] --> D
    C["Archivo managed-settings.json en el directorio del sistema"] --> D

Comprueba tu comprensión

Escenario: Halvern Bank, cuarenta terminales colgadas

Semana 1, día 1. El kickoff salió bien, la sesión de instalación es ahora y nada conecta. Cuatro decisiones, ocho puntos. Las elecciones tienen consecuencias: la mejor opción suma 2 puntos, una opción parcial suma 1 y una opción incorrecta suma 0.

Decisión 1 de 4 · Todo se cuelga

Cada primer prompt de cada desarrollador gira sin fin. Cuarenta personas, una hora reservada, cero instalaciones funcionando. ¿Cuál es tu primer movimiento?

• A. Traer al equipo de red a la llamada. Haz las dos preguntas que importan: ¿el tráfico saliente pasa por un proxy?, ¿la inspección TLS está activa? Todo lo que haga cada terminal después depende de esas respuestas.
• B. Que todos desinstalen y reinstalen. Cuarenta fallas idénticas sugieren una mala build. Una reinstalación limpia la descarta lo más rápido.
• C. Probar una laptop con el hotspot del celular. Si funciona fuera de la red corporativa, has aislado el problema en el perímetro en cinco minutos.

Ver respuesta

• Mejor opción (+2) · A. Traer al equipo de red a la llamada. La sala te oye hacer la pregunta correcta en los primeros cinco minutos. El equipo de red confirma un proxy más inspección TLS, y la solución pasa a ser una tarea de configuración en lugar de un misterio.
• Incorrecta (+0) · B. Que todos desinstalen y reinstalen. Cuarenta reinstalaciones después, las cuarenta terminales siguen colgadas, porque el binario nunca fue el problema. Quemaste media clínica y le enseñaste a la sala que tu primer instinto es adivinar.
• Parcial (+1) · C. Probar una laptop con el hotspot del celular. El test del hotspot aísla el perímetro rápido, y es un buen instinto. Pero aún necesitas al equipo de red para la respuesta real, y gastaste parte de la hora demostrando lo que el propio diagrama de arquitectura del cliente ya decía.

Decisión 2 de 4 · Proxy confirmado

El equipo de red confirma que todo el tráfico saliente pasa por proxy.halvern.net:8080. ¿Cómo distribuyes la corrección en cuarenta máquinas?

• A. Publicar los comandos export en el canal. Cada uno añade HTTPS_PROXY a su perfil de shell. Funciona en una hora para quien lo haga bien.
• B. Enviar HTTPS_PROXY y NO_PROXY por MDM. Las variables de proxy son a nivel de sistema operativo; despliégalas con Jamf o Kandji en macOS, o con la política del registro en Windows. Todas las máquinas existentes la recogen, y las nuevas la reciben al enrolarse.
• C. Pedir el endpoint SOCKS en su lugar. Halvern también ejecuta un proxy SOCKS5 para herramientas de ingeniería; apunta Claude Code a ese y omite por completo el proxy HTTP.

Ver respuesta

• Parcial (+1) · A. Publicar los comandos export en el canal. La sala queda funcionando antes de la hora de almuerzo, menos las seis personas que lo pegaron en el perfil equivocado. Y la ola dos golpea el mismo muro en tres semanas, porque la solución vive en el historial del chat y no en la configuración.
• Mejor opción (+2) · B. Enviar HTTPS_PROXY y NO_PROXY por MDM. Un solo archivo de configuración, en todas las máquinas, incluidas las doscientas instalaciones de la ola dos y cada laptop que se reinstale el próximo trimestre. Esa es la diferencia entre arreglar una sesión y arreglar el despliegue.
• Incorrecta (+0) · C. Pedir el endpoint SOCKS en su lugar. Claude Code no soporta proxies SOCKS. Acabas de hacer una recomendación técnica con seguridad que falla al primer contacto, frente al equipo de plataforma en el que más necesitas que confíen en ti.

Decisión 3 de 4 · El error de certificado

Proxy configurado, aparece un error nuevo: “self-signed certificate in certificate chain”. Un desarrollador sugiere una bandera que encontró en Stack Overflow: NODE_TLS_REJECT_UNAUTHORIZED=0.

• A. Usar la bandera como desbloqueo temporal. Pone a cuarenta personas a trabajar hoy. Reemplázala por la solución correcta cuando termine la clínica.
• B. Apuntar NODE_EXTRA_CA_CERTS a la CA raíz corporativa. El proxy con inspección TLS está volviendo a firmar el tráfico; confía explícitamente en su certificado raíz y distribúyelo en el mismo bloque de managed settings.
• C. Pedir una exención de inspección TLS para los dominios de la API. Pide al equipo de red que exente api.anthropic.com de la inspección. Es legítimo, pero es una solicitud de cambio de seguridad con su propio ciclo de aprobación.

Ver respuesta

• Incorrecta (+0) · A. Usar la bandera como desbloqueo temporal. Esa bandera desactiva la verificación de certificados para todo el tráfico, en un banco. Si el equipo de seguridad la encuentra en un perfil de shell, y audita justamente eso, el hallazgo cae sobre el engagement, no sobre el desarrollador que la sugirió.
• Mejor opción (+2) · B. Apuntar NODE_EXTRA_CA_CERTS a la CA raíz corporativa. La solución correcta, distribuida de la forma correcta. La CA raíz corporativa va a NODE_EXTRA_CA_CERTS en el mismo bloque de managed settings que el proxy, y el error desaparece para todos a la vez.
• Parcial (+1) · C. Pedir una exención de inspección TLS para los dominios de la API. Un patrón legítimo que algunos bancos prefieren. Pero es una solicitud de cambio en el firewall con su propio ciclo de aprobación, así que la clínica termina sin instalaciones funcionando y con un número de ticket. La solución de confianza en la CA habría funcionado hoy.

Decisión 4 de 4 · Seguridad pide la lista

La instalación funciona. El líder de seguridad de Halvern pide “la lista definitiva de cada dominio con el que habla esta herramienta”, por escrito, antes de la segunda ola.

• A. Enviar la allowlist con la justificación por dominio. Dominios de API, autenticación y descarga, cada uno con su propósito, más el matiz de la verificación previa de WebFetch y qué endpoints de telemetría son opcionales y cómo desactivarlos.
• B. Sugerir permitir *.anthropic.com y *.claude.ai. Los comodines cubren lo que el producto necesite ahora y después, y es una sola línea en la configuración del proxy.
• C. Decirles que todo es HTTPS estándar en el puerto 443. Viaja por los mismos carriles que cualquier herramienta SaaS; no necesita tratamiento especial en el firewall.

Ver respuesta

• Mejor opción (+2) · A. Enviar la allowlist con la justificación por dominio. Dominio, propósito, si es obligatorio u opcional, más el matiz de la verificación previa de WebFetch que nadie espera. Seguridad aprueba la ola dos la misma semana y archiva tu memo como documento de referencia para la próxima revisión de herramientas.
• Parcial (+1) · B. Sugerir permitir *.anthropic.com y *.claude.ai. Los comodines probablemente funcionen, pero el equipo de seguridad de un banco no aprueba “probablemente”, y las reglas demasiado amplias invitan justo al escrutinio que intentas evitar. Espera que te devuelvan la solicitud pidiendo la lista específica que podías haber enviado hoy.
• Incorrecta (+0) · C. Decirles que todo es HTTPS estándar en el puerto 443. “No hace falta nada especial” es la respuesta que termina citada en la revisión de seguridad cuando la verificación previa de WebFetch se bloquea y las búsquedas fallan en silencio. Tenías la lista; el momento la pidió; se quedó en tus notas.

Ver cierre del escenario

• 7–8 puntos · Listo para entregar. Diagnosticado en el perímetro, corregido en managed settings, con el certificado correcto de confianza, y le entregaste a Seguridad una lista que pudo aprobar en la primera lectura. Esto es la sección de postura de red de tu Decision Doc, ejecutada en vivo.
• 4–6 puntos · Sólido, pero con exposición. Las instalaciones funcionan, pero algo te costó: un diagnóstico lento, una solución que no sobrevivirá a la ola dos, o una conversación sobre la allowlist que fue rechazada. Cada punto perdido corresponde a un tema de esta lección; recógelos antes del siguiente cliente.
• 0–3 puntos · De vuelta a la terminal. La clínica terminó con terminales colgadas, un hallazgo de seguridad, o ambos. Vuelve a las secciones «Las variables de proxy», «Inspección TLS y confianza» y «La conversación sobre la allowlist», y vuelve a intentarlo. En un engagement real, el Día 1 es la única primera impresión que tiene la activación.

Ideas clave

• Un proxy corporativo saca el tráfico del edificio. Se configura con HTTPS_PROXY y NO_PROXY, y como estas variables son de sistema operativo, se despliegan por MDM y no desde los ajustes de Claude Code.
• SOCKS no es compatible. NTLM y Kerberos se escalan al gateway LLM.
• Ante «self-signed certificate», confía en la CA raíz corporativa con NODE_EXTRA_CA_CERTS. Nunca desactives la verificación TLS.
• La allowlist se entrega con la justificación de cada dominio. api.anthropic.com es necesario para la verificación de seguridad de WebFetch en todas las rutas.
• Las managed settings son la capa de políticas de la organización: no pueden ser sobrescritas por los desarrolladores y se distribuyen desde la consola (solo Enterprise), por MDM o por archivo.

Siguiente: Patrón LLM gateway