Solucionar errores de certificados TLS y SSL de SWG en herramientas CLI y de IA en Mac
Resuelve errores CERTIFICATE_VERIFY_FAILED y de certificado de emisor local en git, npm, Python, Claude Code y Cursor detrás de una SWG en macOS.
SWG bar · Actualizado
Cuando un Mac corporativo se conecta detrás de una pasarela web segura (SWG) que aplica inspección HTTPS/SSL (break-and-inspect), Safari y Chrome suelen cargar sitios web sin advertencias mientras que las herramientas de Terminal y los agentes de programación con IA fallan con errores de handshake TLS como SSL: CERTIFICATE_VERIFY_FAILED, UNABLE_TO_GET_ISSUER_CERT_LOCALLY o SSL certificate problem: unable to get local issuer certificate.
Esta diferencia se produce porque los navegadores consultan el Llavero de macOS —donde MDM puede instalar la CA raíz de inspección de tu organización—, mientras que muchos entornos de línea de comandos (git, curl, Node.js/npm, Python/pip) y herramientas de IA (Claude Code, Cursor, servidores MCP) validan los certificados frente a sus propios almacenes de CA públicas incluidos.
1. Confirma qué nombre de host está sometido a inspección HTTPS
Antes de modificar variables de entorno o ajustes de red, comprueba si la cadena de certificados del endpoint que falla realmente está siendo sustituida en tu Mac:
- Instala y abre SWG bar en macOS 14 o posterior (chip de Apple).
- Ejecuta una vez el comando que falla y revisa SWG bar → Dominios, o bien comprueba el endpoint exacto directamente desde Terminal con la CLI incluida:
/Applications/SWGBar.app/Contents/MacOS/swgbar probe registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar domains detail registry.npmjs.org
- Revisa la clasificación y la CA raíz. Recuerda que las interfaces web, los servidores de autenticación, los registros de paquetes y los endpoints de API de modelos LLM suelen utilizar nombres de host distintos: un subdominio puede pasar sin cambios mientras otro se descifra.
Si utilizas un asistente compatible con MCP, también puedes conectar el servidor MCP integrado de SWG bar para que tu cliente de IA consulte directamente los dominios y cadenas de certificados observados.
2. Elige la solución adecuada para tu entorno
Una vez confirmado que una CA raíz de inspección firma el certificado del nombre de host de destino, elige uno de estos tres enfoques según la política de red y tu autorización:
| Enfoque | Cómo funciona | Recomendado cuando |
|---|---|---|
| Configurar la confianza de CA en la herramienta | Apunta el entorno de ejecución (por ejemplo, NODE_EXTRA_CA_CERTS, SSL_CERT_FILE o REQUESTS_CA_BUNDLE) a un archivo PEM exportado que incluya la CA raíz corporativa. |
La política corporativa exige enrutamiento inspeccionado por SWG y confías en esa CA para esa herramienta concreta. |
| Solicitar una excepción de inspección TLS al administrador | El equipo de TI excluye el nombre de host de la API o del registro del descifrado HTTPS en la pasarela manteniendo el paso por ella. | Las herramientas con certificate pinning o los endpoints de desarrollo de todo el equipo fallan con break-and-inspect. |
| Activar la evasión de SWG por dominio en SWG bar | Enruta el nombre de host seleccionado en macOS sin descifrado HTTPS de la pasarela mediante la barra de menús, CLI o MCP. | Administras la red o tienes autorización para probar una ruta sin inspección para dominios específicos en tu Mac. |
Consulta Bypass de SWG frente a excepción de inspección TLS para ver una comparación arquitectónica detallada entre excepciones en la pasarela y cambios de ruta.
3. Evita un dominio inspeccionado en macOS cuando estés autorizado
Si la evasión por dominio es adecuada para tu red, puedes activarla para el nombre de host exacto de la API o del registro desde la barra de menús (SWG bar → Dominios → Evitar SWG → Activar evasión para este dominio) o desde Terminal:
/Applications/SWGBar.app/Contents/MacOS/swgbar bypass enable registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar bypass status
Cuando el estado muestre Evasión activa, reinicia el comando CLI, el proceso en segundo plano o el host de extensiones del IDE para que las conexiones existentes se cierren y vuelvan a conectarse aplicando la nueva regla. Sigue Cómo evitar una SWG en Mac para ver la autorización inicial de la extensión de red de macOS, el comportamiento tras reiniciar y cómo desactivar la evasión al terminar.
Ten en cuenta los límites de la plataforma y de la red
- Alcance por nombre de host: Evitar
example.comno incluye automáticamenteapi.example.comniauth.example.com. Comprueba cada nombre de host al que se conecte tu herramienta. - Requisitos de red: SWG bar 2.4.12 requiere macOS 14+ en ordenadores con chip de Apple y una ruta IPv4 disponible a través de una interfaz de red física. Si un cortafuegos bloquea las conexiones directas salientes o la herramienta fuerza su propio proxy explícito, desactiva la regla de evasión y utiliza en su lugar una excepción TLS del administrador o una configuración de paquete de CA.
- Verifica con pruebas recientes: Realiza una comprobación nueva siguiendo la guía de inspección HTTPS y SSL después de cualquier cambio en lugar de confiar en resultados almacenados en caché.