Cómo configurar HTTPS_PROXY para Cursor y Claude Code en una red corporativa

Si su empresa bloquea el tráfico saliente a través de un proxy corporativo, los asistentes de IA como Cursor y Claude Code simplemente dejan de responder: la autocompleción se congela, la CLI muestra ETIMEDOUT o SSL certificate problem. Vamos a ver cómo configurar correctamente las variables de entorno HTTPS_PROXY, configurar la autenticación y evitar errores comunes que hacen que los desarrolladores pasen horas depurando la configuración de red en lugar de código.

¿Por qué necesitan los asistentes de IA un proxy en la red corporativa?

Cursor y Claude Code no son modelos locales. Ellos constantemente acceden a APIs externas: Cursor se conecta a sus servidores de indexación de código y a las APIs de modelos (OpenAI, Anthropic, Google dependiendo del proveedor elegido), mientras que Claude Code — se conecta directamente a la API de Anthropic a través de HTTPS. En una red corporativa, el acceso directo a Internet está a menudo bloqueado por un firewall, y todo el tráfico saliente debe pasar a través de un servidor proxy (Squid, Zscaler, Blue Coat, Fortinet FortiProxy o un gateway corporativo interno). Sin las variables de entorno configuradas correctamente, la aplicación simplemente no sabe que el tráfico debe ser redirigido a través del proxy y trata de acceder a Internet directamente — obteniendo timeouts.

Una dificultad adicional es que Cursor está construido sobre Electron (que es esencialmente Chromium + Node.js), mientras que Claude Code es una aplicación CLI de Node.js. Cada uno tiene su propia lógica para leer la configuración del proxy: Electron hereda parcialmente la configuración del sistema operativo, mientras que los procesos de Node.js leen las variables de entorno HTTP_PROXY/HTTPS_PROXY directamente o a través de bibliotecas como undici y node-fetch. Esto genera confusión: la configuración está establecida, pero la herramienta "no la ve".

Variables HTTP_PROXY, HTTPS_PROXY y NO_PROXY: ¿cómo funciona?

La forma clásica de especificar un proxy para aplicaciones de consola en Node.js, Python y Go es a través de variables de entorno. La diferencia entre HTTP_PROXY y HTTPS_PROXY es fundamental: el primero se utiliza para solicitudes a través del protocolo HTTP, el segundo — para solicitudes HTTPS (y casi todo el tráfico de los asistentes de IA va precisamente por HTTPS). Se deben especificar ambos, incluso si el tráfico real es solo HTTPS — algunas bibliotecas hacen solicitudes HTTP de servicio al inicio.

export HTTP_PROXY="http://proxy.company.local:8080"
export HTTPS_PROXY="http://proxy.company.local:8080"
export NO_PROXY="localhost,127.0.0.1,.company.local"

Tenga en cuenta: incluso para el tráfico HTTPS, el esquema en la dirección del proxy se especifica como http://, y no https:// — esta es la dirección del servidor proxy en sí, no del recurso objetivo. La conexión al proxy a través de HTTP es normal, la encriptación hasta el servidor final sigue funcionando a través del mecanismo de tunelización CONNECT.

La variable NO_PROXY es necesaria para excluir las direcciones internas de la empresa de la proxy — de lo contrario, las solicitudes a repositorios git internos, Jira o servicios de desarrollo locales también pasarán a través del proxy externo y no se encontrarán o se ralentizarán. Un detalle importante: algunas bibliotecas son sensibles al caso de las variables. Para mayor seguridad, especifique ambas versiones — en mayúsculas y minúsculas:

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export no_proxy="$NO_PROXY"

Configuración del proxy para Cursor

Cursor utiliza parcialmente la configuración del proxy del sistema operativo (especialmente en macOS y Windows), pero para un funcionamiento estable en la red corporativa es mejor configurarlo explícitamente a través de variables de entorno y, si es necesario, a través del archivo de configuración de la aplicación.

En macOS y Linux es más fácil agregar la exportación de variables al archivo de perfil de la shell, para que se carguen en cada inicio de terminal desde el que se inicia Cursor:

# ~/.zshrc o ~/.bash_profile
export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"
export NO_PROXY="localhost,127.0.0.1,*.company.local"

Después de cambiar el archivo de perfil, ejecute source ~/.zshrc y reinicie completamente Cursor (no solo minimice la ventana — finalice el proceso a través del Monitor de Actividad o el administrador de tareas, ya que las aplicaciones Electron almacenan en caché el entorno al iniciar).

En Windows, es más conveniente establecer las variables a través de la configuración del sistema (Panel de control → Sistema → Configuración avanzada del sistema → Variables de entorno) o a través de PowerShell para guardarlas de forma permanente:

[System.Environment]::SetEnvironmentVariable('HTTPS_PROXY','http://user:[email protected]:8080','User')
[System.Environment]::SetEnvironmentVariable('HTTP_PROXY','http://user:[email protected]:8080','User')
[System.Environment]::SetEnvironmentVariable('NO_PROXY','localhost,127.0.0.1','User')

Si después de esto Cursor aún no se conecta a la API de modelos, verifique la configuración del proxy dentro de la propia aplicación: Configuración → Red (o General) — puede haber un campo Proxy URL separado que anula las variables del sistema. En algunas versiones de Cursor también es necesario habilitar explícitamente la opción "Usar la configuración de proxy del sistema".

Configuración del proxy para Claude Code

Claude Code es una herramienta CLI en Node.js, ejecutada a través de npm/npx, por lo que lee directamente las variables de entorno de la sesión de terminal en la que fue invocada. Esto simplifica la configuración: es suficiente con exportar las variables antes de ejecutar.

export HTTPS_PROXY="http://user:[email protected]:8080"
export HTTP_PROXY="http://user:[email protected]:8080"
claude

Si ejecuta Claude Code como parte de un pipeline CI o desde un script, pase las variables explícitamente en el comando de ejecución, para evitar depender del entorno global de la shell:

HTTPS_PROXY="http://proxy.company.local:8080" \
HTTP_PROXY="http://proxy.company.local:8080" \
claude --print "Verifica las pruebas en el proyecto"

Para una configuración permanente, es más conveniente fijar las variables en un archivo .env en la raíz del proyecto y cargarlo a través de direnv o el soporte incorporado de dotenv, si su shell lo admite. Esto es especialmente útil cuando diferentes proyectos requieren diferentes configuraciones de proxy (por ejemplo, un proyecto trabaja con una API interna, mientras que otro — con servicios externos).

Autenticación en el proxy corporativo

La mayoría de los proxies corporativos requieren autenticación — Basic Auth, Digest o NTLM. Para Basic Auth, el nombre de usuario y la contraseña se pueden incrustar directamente en la URL del proxy, como se mostró anteriormente: http://user:[email protected]:8080. Un detalle importante — si la contraseña contiene caracteres especiales (@, #, %), deben ser codificados en URL, de lo contrario, el analizador de la cadena del proxy fallará en la frontera entre el nombre de usuario y el host.

# Si la contraseña es P@ssw0rd#2024, codificamos los caracteres especiales:
# @ -> %40, # -> %23
export HTTPS_PROXY="http://user:P%40ssw0rd%[email protected]:8080"

Es más complicado con la autenticación NTLM (a menudo utilizada junto con Microsoft ISA Server, Forefront TMG o Fortinet) — Node.js y la mayoría de los clientes HTTP no soportan NTLM "out of the box". En tal caso, la solución estándar es levantar un proxy intermedio local que se encargue del apretón de manos NTLM, y luego entregue un "proxy HTTP limpio" para la aplicación. Para esto, a menudo se utilizan cntlm o px (proxy NTLM local en Python). El esquema es simple: Cursor/Claude Code → localhost:3128 (cntlm) → proxy NTLM corporativo → internet.

# Ejemplo de configuración de cntlm (/etc/cntlm.conf)
Username    your_login
Domain      COMPANY
Password    su_contraseña_o_hash
Proxy       proxy.company.local:8080
Listen      3128

# Después de iniciar cntlm, especificamos la dirección local:
export HTTPS_PROXY="http://127.0.0.1:3128"
export HTTP_PROXY="http://127.0.0.1:3128"

Certificados y MITM: problema de SSL en la red corporativa

Si en la empresa se ha desplegado un producto de clase Zscaler, Netskope o cualquier otro filtro web con inspección SSL, el tráfico se descifra en el proxy y se firma con el certificado Root CA corporativo. Node.js (y por lo tanto Claude Code, y la mayor parte de los módulos internos de Cursor) por defecto confía solo en su conjunto integrado de certificados raíz y lanzará un error UNABLE_TO_VERIFY_LEAF_SIGNATURE o self signed certificate in certificate chain.

La solución es exportar el certificado CA corporativo (generalmente se puede obtener del departamento de TI o extraerlo del almacén de certificados del navegador) y especificar a Node.js la ruta a él a través de la variable NODE_EXTRA_CA_CERTS:

export NODE_EXTRA_CA_CERTS="/etc/ssl/certs/company-root-ca.pem"

Se desaconseja encarecidamente desactivar globalmente la verificación de certificados a través de NODE_TLS_REJECT_UNAUTHORIZED=0 — esto elimina la protección contra ataques MITM en todo el proceso, incluidas las conexiones legítimas. Utilice esta bandera solo para diagnóstico temporal y asegúrese de restaurar la protección.

Errores comunes y sus soluciones

Error	Causa	Solución
ETIMEDOUT / ECONNREFUSED	Las variables del proxy no están exportadas en la sesión donde se ejecuta la aplicación	Verifique echo $HTTPS_PROXY en la misma terminal, reinicie la aplicación completamente
407 Proxy Authentication Required	El nombre de usuario/contraseña no están especificados o están desactualizados	Actualice las credenciales en la cadena del proxy, codifique en URL los caracteres especiales de la contraseña
self signed certificate in certificate chain	El proxy corporativo MITM sustituye el certificado	Especifique NODE_EXTRA_CA_CERTS con el Root CA corporativo
El proxy funciona en la terminal, pero no en Cursor	Cursor se ejecuta no desde la terminal correcta o a través de un acceso directo sin entorno	Ejecute Cursor con el comando desde la terminal con las variables exportadas, o especifique las variables globalmente en el sistema
NTLM authentication failed	El cliente no soporta el apretón de manos NTLM	Levante un proxy intermedio cntlm o px entre la aplicación y el proxy corporativo

Verificación de la conexión a través de curl

Antes de investigar por qué Cursor o Claude Code no funcionan, asegúrese de que el proxy en sí sea accesible y esté proxyando correctamente el tráfico HTTPS. Para esto, use curl — lee las mismas variables de entorno y permite localizar rápidamente el problema sin iniciar aplicaciones pesadas.

# Verificación de la disponibilidad del proxy y autenticación
curl -v -x "http://user:[email protected]:8080" https://api.anthropic.com

# Verificación teniendo en cuenta el certificado corporativo
curl -v --cacert /etc/ssl/certs/company-root-ca.pem \
  -x "http://user:[email protected]:8080" \
  https://api.anthropic.com

Si curl recibe una respuesta con éxito (incluso 401 o 403 — esto es normal, significa que el apretón de manos TLS ha pasado), y Claude Code aún no se conecta — el problema no está en la red, sino en que el proceso no ve las variables de entorno. Si curl también falla con un error de certificado o timeout — el problema está a nivel de red o proxy, y las herramientas no tienen nada que ver.

Cuándo se necesita un proxy externo en lugar del corporativo

A veces, la tarea no se limita al acceso desde la red corporativa hacia afuera. Los desarrolladores que prueban integraciones con APIs geoespecíficas, verifican el comportamiento del servicio desde diferentes países o depuran políticas de limitación de tasa de los proveedores de modelos, se encuentran con que el proxy corporativo emite la misma IP corporativa para todas las solicitudes. En tales escenarios, es conveniente enviar tráfico de prueba a través de un proxy externo en paralelo con el entorno de trabajo principal.

Para sesiones de prueba estables y de larga duración con un riesgo mínimo de bloqueo por IP, son adecuadas proxies residenciales — utilizan direcciones IP reales de proveedores domésticos y parecen tráfico de usuario normal, lo que es importante al verificar respuestas API geoespecíficas. Si necesita reproducir el comportamiento de un cliente móvil o probar escenarios sensibles al tipo de red, considere proxies móviles. Y para pruebas masivas y paralelas de solicitudes a APIs públicas, donde la velocidad y el costo del tráfico son más importantes que disfrazarse como un usuario normal, generalmente son suficientes proxies de centros de datos.

Importante: dicho proxy externo se configura de la misma manera a través de las variables HTTPS_PROXY/HTTP_PROXY, pero para el entorno de prueba o un perfil de terminal separado, para no mezclarlo con el tráfico de trabajo principal a través del gateway corporativo. Si la política corporativa requiere que todo el tráfico de la empresa pase solo por el proxy interno, el uso de un externo debe ser aprobado por IT/Security — muchas empresas prohíben explícitamente eludir el gateway corporativo sin permiso.

Lista de verificación de configuración

Conclusión

La mayoría de los problemas con Cursor y Claude Code detrás de un proxy corporativo se reducen a tres cosas: las variables de entorno no llegan al proceso, la autenticación está configurada incorrectamente, o el certificado MITM corporativo no se ha añadido a los de confianza. Al verificar estos tres puntos en orden — a través de curl, y no directamente a través de la aplicación — ahorrará horas en depuración y localizará rápidamente la causa.

Si la tarea va más allá de la red corporativa y necesita probar el comportamiento de la API desde diferentes regiones o con diferentes tipos de IP, le recomendamos probar proxies residenciales — ofrecen un tráfico más estable y menos sospechoso para los servicios externos en comparación con las direcciones de centros de datos normales.