Error de certificado SSL en Claude Code

El string de error te dice qué capa está fallando, y cada uno mapea a un fix específico más abajo.

Una prueba resuelve la causa en diez segundos. Ejecuta Claude Code en una red sin inspección — un hotspot del móvil sirve — o pide a IT una regla de bypass para api.anthropic.com. Si conecta ahí y falla en la red corporativa, el proxy está re-firmando tu tráfico y necesitas un fix de CA, no una reinstalación.

Antes de tocar un archivo de config, decide qué problema tienes de verdad. Los fixes de certificado asumen que puedes conseguir la CA de tu empresa y poner una variable de entorno. No siempre es cierto, y forzarlo desperdicia una tarde.

La mayoría de redes corporativas usan un proxy de inspección TLS. Saber qué hace te dice por qué aparece el error y dónde está el fix.

Zscaler, Netskope, Cato, CrowdStrike Falcon o un VPN de túnel completo hacen lo mismo: leer el HTTPS saliente para prevención de pérdida de datos y escaneo de malware. Para leer un flujo cifrado, la caja tiene que sentarse en el medio. Termina tu conexión a api.anthropic.com, la descifra, luego hace su propia conexión hacia adelante y re-firma la respuesta con la autoridad certificadora privada de la empresa.

Tu navegador confía en ese cert re-firmado porque IT empujó la CA raíz corporativa al navegador y al OS trust store cuando configuraron el portátil. Claude Code es un runtime aparte con su propia idea de en qué confiar — y ahí es donde vive el desajuste.

Aquí está la parte que la mayoría de write-ups erran. El Claude Code moderno ya lee tu OS trust store. Por defecto confía tanto en su set de Mozilla embebido como en el almacén de certificados del sistema operativo. Leer el OS store necesita un runtime que exponga tls.getCACertificates: el instalador nativo siempre lo tiene, y los installs por npm necesitan Node 22.15 o superior. En Node antiguo solo aplican el set embebido y NODE_EXTRA_CA_CERTS. Así que cuando IT ha instalado la raíz corporativa en el OS store y estás en un build actual, proxies de inspección como Zscaler y CrowdStrike Falcon funcionan sin configuración extra. Los errores aparecen en los huecos: un install viejo por npm, una CA que nunca llegó al OS store, o un runtime lanzado de forma que se lo salta.

El string exacto acota la causa. Es la misma taxonomía que usan Node y OpenSSL, así que aplica tanto si Claude Code corre en el binario nativo como en un install por npm.

La distinción importa. Un error de verificación en cada llamada a la API es un problema de trust store que se arregla una vez con una CA. Un error de revocación al instalar es el firewall bloqueando una consulta, y lo rodeas para ese único comando de instalación en vez de cambiar tu configuración de confianza.

Ve de arriba a abajo. Los primeros son más limpios y menos arriesgados que los últimos.

node --version

export CLAUDE_CODE_CERT_STORE=bundled,system

export NODE_EXTRA_CA_CERTS=/ruta/a/corporate-ca.pem
claude

curl --cacert /ruta/a/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

export HTTPS_PROXY=https://proxy.ejemplo.com:8080
export HTTP_PROXY=http://proxy.ejemplo.com:8080
export NO_PROXY="localhost,127.0.0.1,.internal.ejemplo.com"

export HTTPS_PROXY=http://usuario:password@proxy.ejemplo.com:8080

export CLAUDE_CODE_CLIENT_CERT=/ruta/a/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/ruta/a/client-key.pem
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="tu-passphrase"

Los pasos abstractos son fáciles de errar, así que aquí está todo para el setup más común — un Mac detrás de Zscaler. Toma unos cinco minutos.

1. 1.Confirma que es de verdad el proxy. Conéctate al móvil y ejecuta claude. Si conecta ahí, la red corporativa está interceptando y continúas abajo.
2. 2.Exporta la raíz de Zscaler del Keychain. Abre Keychain Access, busca la raíz corporativa (suele llamarse Zscaler Root CA), selecciónala y usa Archivo luego Exportar para guardarla como zscaler-root.pem en tu carpeta de usuario. Si la exporta como .cer, conviértela:
3. 3.Apunta Claude Code a ella y hazlo persistente:

openssl x509 -inform der -in zscaler-root.cer -out zscaler-root.pem

echo 'export NODE_EXTRA_CA_CERTS="$HOME/zscaler-root.pem"' >> ~/.zshrc
source ~/.zshrc

Abre una terminal nueva para que el export se cargue, luego arranca claude. El error SSL ha desaparecido.

curl --cacert "$NODE_EXTRA_CA_CERTS" -svo /dev/null https://api.anthropic.com 2>&1 | grep -E "issuer|verify"

Los contenedores son donde este error reaparece tras creerlo resuelto, porque un contenedor nuevo no hereda el OS trust store de tu portátil. Tu host confía en la CA corporativa; la imagen Ubuntu base dentro de Docker, no.

Mete la CA en la imagen y regístrala tanto en el OS store como en la variable de Node:

COPY corporate-ca.pem /usr/local/share/ca-certificates/corporate-ca.crt
RUN update-ca-certificates
ENV NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/corporate-ca.crt

La misma lógica cubre runners de CI y máquinas de dev remoto: un runner de GitHub Actions o GitLab detrás del mismo proxy necesita la CA presente en el entorno del job, normalmente como archivo secreto escrito al inicio del job con NODE_EXTRA_CA_CERTS exportado antes de cualquier paso de claude. Los devcontainers necesitan la línea ENV de arriba en su Dockerfile. Si solo arreglaste tu shell profile, el contenedor nunca lo vio.

Cada variable de arriba puede vivir en el bloque env de ~/.claude/settings.json, que es la opción ordenada para una máquina que configuras una vez.

{
  "env": {
    "NODE_EXTRA_CA_CERTS": "/ruta/a/corporate-ca.pem",
    "HTTPS_PROXY": "https://proxy.ejemplo.com:8080"
  }
}

Hay una advertencia que conviene decir claro. Algunas versiones anteriores ignoraban NODE_EXTRA_CA_CERTS cuando solo se ponía en settings.json, y la app de escritorio no siempre lo reenviaba al subproceso del CLI que lanza. Ambos han salido como issues rastreados en GitHub. Si el valor de settings.json no hace nada, el fallback fiable es el export del shell en tu profile, que todo build honra porque Node lo lee antes de que arranque Claude Code.

Estos aparecen junto a los errores de certificado y se confunden con ellos.

Esa última fila es la silenciosa. Si claude va en tu terminal pero el panel de VS Code o JetBrains lanza el error SSL, el editor se arrancó desde el dock y nunca vio tu .zshrc. Pon las variables en el entorno propio del IDE, o arranca el editor desde un shell donde ya estén exportadas.

Si el proxy exige NTLM o Kerberos, o simplemente no puedes conseguir la CA, añadir certificados es un callejón sin salida. Pon un LLM gateway delante que hable ese esquema.

Un gateway termina su propio TLS y maneja la negociación sucia del proxy una vez, de modo que cada desarrollador apunta a un endpoint en vez de que cada uno pelee con su propio trust store. Apuntar Claude Code a un endpoint custom es un cambio de una línea — pon dos variables:

export ANTHROPIC_BASE_URL=https://tu-gateway.ejemplo/anthropic
export ANTHROPIC_API_KEY=sk-...

Sé honesto sobre qué resuelve esto y qué no. El proxy corporativo sigue re-firmando el tráfico hacia el host del gateway, así que puede que sigas necesitando la CA corporativa en tu trust store para él. Lo que te compra el gateway es un punto de salida para todo el equipo, una vista única de facturación y uso entre proveedores, y un sitio para poner failover cuando un upstream no responde.

El gateway es la vía de escape, no el valor por defecto. Cuando puedes conseguir la CA, Fix 1 o Fix 2 es más simple y te mantiene en el camino directo.

Los arreglos de arriba hacen que Claude Code hable a través de tu proxy. El resto es la parte por la que vale la pena actuar antes de que alguien mande el anti-fix.

Puedes leer este error de dos formas. La estrecha: un proxy re-firma tu tráfico, añade la CA y sigue. La útil: un control de seguridad que tu empresa puso es ahora lo que bloquea tus herramientas — y el workaround al que más gente recurre elimina silenciosamente la protección por completo.

Lo vemos en casi todo sistema de IA que auditamos. Un equipo pone NODE_TLS_REJECT_UNAUTHORIZED=0 en un script para que un error desaparezca, ese script se copia a CI, y un año después un atacante en la red lee cada API key que envía. El error de certificado es una cosa pequeña. El reflejo de desactivar la validación es la vulnerabilidad real.

Tres cosas hacen que un setup sobreviva a estos entornos:

Si el workaround de tu equipo para un error de certificado es desactivar las verificaciones de certificado, el error no era el problema — lo era el workaround.

Sobre FACTA

FACTA ayuda a startups y equipos en etapa de crecimiento a convertir IA en sistemas de producción que siguen funcionando — no demos que impresionan una vez.

Diseñamos la arquitectura en torno a lo que de verdad se rompe bajo uso real: abstracción de modelo, credenciales que te pertenecen, failover, controles de coste, observabilidad. La infraestructura aburrida que mantiene un sistema vivo después del lanzamiento.

Liderado por Matías Baglieri y Carolina Fogliato, nos centramos en una sola cosa:

Liderazgo de IA que construye. No solo asesora.