La instalación es un comando. Llegar hasta ahí es el trabajo.

Módulo 2 · Instalación y entornos · Lección 1 de 5

Antes de que cualquier desarrollador de un proyecto de cliente ejecute Claude Code, debes confirmar el entorno. Esta lección cubre la lista de verificación previa al kickoff que envías a TI, el recorrido de una instalación limpia y cómo diagnosticar lo que falla cuando algo sale mal.

Confirma el entorno antes del día de instalación, no durante ella

Los fallos de configuración durante el kickoff de un cliente casi siempre se pueden evitar. El Plan de Activación de 30 Días es explícito: confirma los bloqueos antes del kickoff, no en el kickoff. Esto significa una llamada corta o un intercambio de lista de verificación con el equipo de TI del cliente la semana anterior.

Tres cosas determinan si el día de instalación sale bien: si el sistema operativo objetivo está soportado, si la red del cliente puede alcanzar los endpoints de Anthropic y cómo se autenticará Claude Code para la cohorte de desarrolladores. Las tres se pueden responder por adelantado, así que ninguna requiere que haya un desarrollador presente. Es una conversación con TI.

Principio del proyecto: si el día de la instalación es la primera vez que verificas el entorno, ya vas tarde.

Soporte de plataforma: macOS, Linux y Windows están soportados de forma nativa. Windows tiene dos caminos.

La mayoría de las flotas de desarrolladores empresariales son una mezcla. Conoce las opciones de Windows antes del kickoff para poder asesorar al equipo de TI del cliente sobre cuál encaja con su entorno.

macOS

Claude Code se ejecuta de forma nativa en macOS. La instalación es la misma tanto en Apple Silicon (M1+) como en equipos Intel. No requiere configuración adicional más allá del comando de instalación con curl. Si el equipo usa un proxy corporativo o una autoridad de certificación (CA) personalizada, apunta NODE_EXTRA_CA_CERTS al archivo del certificado de la CA.

Linux

Claude Code se ejecuta de forma nativa en Linux. Las distribuciones habituales (Ubuntu 20.04+, Debian 10+, Alpine 3.19+) están soportadas. La instalación es el comando curl estándar. Igual que en macOS, el manejo de proxy y certificados funciona mediante variables de entorno estándar: HTTPS_PROXY (o HTTP_PROXY) y NODE_EXTRA_CA_CERTS.

Windows: ruta nativa

Claude Code se ejecuta de forma nativa en Windows, sin necesitar WSL ni ninguna capa de Linux. Los desarrolladores lo lanzan desde PowerShell o CMD. La ruta nativa es la más sencilla para la mayoría de los equipos y no requiere más aprovisionamiento de TI que el acceso a la red. Git para Windows es opcional pero recomendable; sin él, Claude Code usa PowerShell como shell en lugar de Git Bash. Confirma con TI antes del kickoff si esta contrapartida encaja con el flujo de trabajo del equipo.

Windows: ruta WSL

WSL (Windows Subsystem for Linux) es la opción adecuada cuando el equipo necesita toolchains de Linux o quiere sandboxing, no disponible en Windows nativo. WSL requiere habilitación por parte de TI en equipos gestionados. Si los desarrolladores eligen esta ruta, instalan Claude Code dentro del entorno WSL; a partir de ahí se comporta de forma idéntica a la instalación en Linux. Se recomienda WSL 2 por rendimiento y aislamiento.

Instalación: un comando. Lo que pasa después de ejecutarlo es lo que hay que preparar.

El script de instalación se encarga de la configuración del runtime. La autenticación es el primer punto de decisión tras completarse.

El comando de instalación varía según el sistema operativo. En macOS y Linux, usa el instalador con curl. En Windows, usa PowerShell (recomendado) o CMD.

macOS y Linux

curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell, recomendado)

irm https://claude.ai/install.ps1 | iex

Windows (CMD)

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Tras completar la instalación, Claude Code abre un prompt en la terminal que pregunta cómo quiere autenticarse el desarrollador. Hay dos caminos, y la elección define toda la configuración de la cohorte y si TI tiene que participar.

flowchart TD
  I["Instalar con el comando del sistema operativo"] --> A["Prompt de autenticación"]
  A --> B{"Método de autenticación"}
  B -- "Login por navegador (Team o Enterprise)" --> C["Inicio de sesión en el navegador; el token vuelve a la terminal"]
  B -- "Clave de API (CI, headless o automatización)" --> D["Introducir la clave de API en el prompt"]
  C --> V["claude --version"]
  D --> V
  V --> H["claude doctor (antes de incorporar la cohorte)"]

Login por navegador

El desarrollador pulsa Enter en el prompt de autenticación. Se abre una ventana del navegador con una página de inicio de sesión donde se autentica con su cuenta de Anthropic (suscripción Team o Enterprise). El navegador devuelve un token de sesión a la terminal y Claude Code queda listo para usarse. Es la ruta estándar para desarrolladores interactivos con un plan Team o Enterprise. No requiere la intervención de TI para la gestión de claves; la autenticación se mantiene a nivel individual.

Introducción de clave de API

El desarrollador introduce una clave de API directamente en el prompt. Es la ruta estándar para uso headless, pipelines de CI o flujos automatizados, en cualquier escenario en el que el desarrollador no inicie sesión a través de un navegador. La distribución de claves de API requiere coordinación con TI: la clave debe crearse en la consola de Anthropic, distribuirse de forma segura (variable de entorno, gestor de secretos o archivo seguro) y rotarse periódicamente. Para despliegues de cohortes empresariales en los que varios desarrolladores comparten una clave, confirma este enfoque con TI antes del kickoff, porque determina tu flujo de aprovisionamiento.

Bloqueos habituales: cuatro cosas que fallan durante la instalación en entornos empresariales

Cada uno de estos puntos puede fallar en silencio o producir errores engañosos. Confírmalos con el equipo de TI del cliente antes de que la cohorte de desarrolladores intente la configuración.

1. Acceso a la red. Claude Code necesita alcanzar los endpoints de la API de Anthropic. En redes corporativas con filtrado de salida, confirma que son accesibles antes del día de la instalación: api.anthropic.com (API de Claude), claude.ai y platform.claude.com (autenticación), downloads.claude.ai (instalador y actualizador automático) y raw.githubusercontent.com (changelog). Es el primer punto que debes plantear a TI, porque cambiar las reglas de firewall lleva días.

2. Manejo de proxy y certificados. Claude Code respeta las variables de entorno de proxy estándar. La mayoría de las configuraciones empresariales (Zscaler, CrowdStrike) funcionan sin configuración adicional si el certificado raíz está en el almacén de confianza del sistema operativo. Hay configuraciones de CA personalizada y mTLS si se necesitan. La configuración completa del proxy se cubre en el Curso 3, Lección 3.3. Confirma con TI si se usa un proxy y márcalo como elemento de configuración para esa etapa.

3. Arquitectura de autenticación. Confirma el método de autenticación antes del kickoff, porque determina toda la configuración de la cohorte. Para desarrolladores interactivos con plan Team o Enterprise, el login por suscripción en navegador es la ruta estándar. Las claves de API son adecuadas para uso en CI, headless o automatizado. Las cohortes mixtas pueden usar ambos. Confirma la participación y la aprobación de TI para la ruta elegida antes del día de la instalación.

4. Windows: nativo frente a WSL en equipos gestionados. Windows nativo funciona sin intervención de TI. Si el equipo opta por WSL para toolchains de Linux o sandboxing, las imágenes gestionadas por TI pueden no tenerlo habilitado por defecto, y activarlo puede requerir un ticket de TI. Establece la ruta de Windows pronto para saber si hace falta la intervención de TI.

Verificación: confirma que la instalación está limpia antes de continuar

Una instalación correcta que no se ha verificado no es una instalación correcta. Es una suposición.

Tras la instalación y la autenticación, empieza con una comprobación de versión para confirmar que Claude Code está disponible y responde. Después valida la configuración antes de que la cohorte de desarrolladores se incorpore.

Comprobación de versión

claude --version

Si devuelve «command not found», el PATH no se actualizó. Cierra y vuelve a abrir la terminal, o carga tu perfil de shell con source.

Validación de configuración

claude doctor

Ejecútalo antes de que la cohorte de desarrolladores se incorpore. Valida la configuración y lista los ajustes no válidos con su archivo de origen y el nombre del campo: la forma más rápida de detectar una política o un proxy mal configurados antes de que se convierta en una llamada de soporte. Úsalo como comprobación previa al despliegue en una máquina representativa antes de desplegar en todo el equipo.

Una vez que Claude Code está en marcha, usa el comando de sesión /status para confirmar que la configuración de proxy y gateway se aplica correctamente. Es útil al configurar por primera vez un LLM gateway o un proxy corporativo.

Comprueba tu comprensión

Escenario: tu hoja de admisión del cliente acaba de llegar.

Tienes 30 minutos con el responsable de plataforma y el contacto de TI del cliente la próxima semana. Debes decidir qué bloqueos plantear primero, para no perder tiempo y no pasar por alto nada crítico.

Tu pregunta de apertura importa. El contacto de TI ha reservado 30 minutos. Puedes cubrir tres temas en profundidad o cinco superficialmente. Elige tu pregunta de apertura para ver qué se queda sin cubrir.

El responsable de TI dice: «¿Qué necesitamos saber?» Tienes su atención. ¿Qué preguntas primero?

• Acceso a la red: ¿a qué endpoints necesita llegar Claude Code?
• Número de desarrolladores: ¿cuántos necesitan acceso y en qué plazo?
• WSL: ¿usáis WSL en los equipos de los desarrolladores?

Ver respuesta

Cada opción, con su marca y su retroalimentación de la lección:

• Mejor. Acceso a la red. Es el bloqueo que condiciona todo. Si el firewall bloquea el instalador, nada más importa. Además es el más difícil de resolver con un calendario ajustado. Las reglas de firewall tardan días. Retroalimentación: buena decisión. El acceso a la red condiciona toda la instalación. Si el firewall bloquea el curl, nada más importa. Además es el bloqueo más difícil de resolver con un calendario ajustado. Las reglas de firewall tardan días en cambiar. Preguntarlo primero permite que TI empiece la solicitud de cambio mientras tú cubres el resto de bloqueos.
• Incorrecta. Número de desarrolladores. Esto condiciona la planificación del despliegue, lo que resulta útil como contexto. Pero no revela bloqueos. Encaja con cualquier ruta de despliegue, aunque no indica si la instalación realmente va a funcionar. Retroalimentación: prioridad perdida. La planificación por fases encaja con cualquier ruta de despliegue. Dedicas 20 minutos a la planificación del despliegue y nunca haces la pregunta que condiciona la instalación. El contacto de TI responde tu pregunta y luego tienes que reservar una segunda llamada.
• Parcial. WSL. Es útil si el cliente usa imágenes gestionadas de Windows. Pero solo importa si eligen la ruta WSL, y no lo sabrás hasta que entiendas su mezcla de plataformas y su postura de red. Retroalimentación: útil, pero secundaria. La pregunta sobre WSL solo importa si el cliente elige la ruta WSL. No lo sabrás hasta que entiendas su mezcla de plataformas y su postura de red. Has dedicado tiempo a un detalle condicional.

Escenario: un desarrollador en la llamada de instalación. El desarrollador ejecutó el comando de instalación, reinició la terminal y obtuvo un error. Ves el mensaje de error. ¿Cuál es tu diagnóstico?

Error #1. El desarrollador ejecutó el comando de instalación en su Mac y obtuvo: «curl: (7) Failed to connect to claude.ai port 443: Connection refused»

• La red bloquea la salida HTTPS hacia la URL del instalador.
• La conexión a internet del desarrollador está caída.
• El servidor del script de instalación está temporalmente caído.

Ver respuesta

Cada opción, con su marca y su retroalimentación de la lección:

• Mejor. La red bloquea la salida HTTPS hacia la URL del instalador. La red corporativa o el firewall impide que curl llegue a claude.ai. Es el bloqueo que debías haber confirmado con TI antes del kickoff. Escálalo al contacto de TI con el nombre de host bloqueado. Retroalimentación: acertaste con el diagnóstico. Es exactamente el bloqueo de red que debería haberse detectado en la lista de verificación previa al kickoff. Escala a TI con el nombre de host (claude.ai) y el mensaje de error. Ahora es su ticket, no el tuyo.
• Incorrecta. La conexión a internet del desarrollador está caída. Poco probable en un equipo compartido o en una red corporativa. Pídele que haga ping a un servidor DNS público para comprobarlo, pero rara vez es el problema cuando otros en la misma red no se ven afectados. Retroalimentación: posible pero de baja probabilidad. Un desarrollador en una red corporativa que pierde la conectividad a internet afectaría a más que este único curl. Empieza por la hipótesis del bloqueo de red cuando otros en la misma red tampoco pueden instalar.
• Parcial. El servidor del script de instalación está temporalmente caído. Posible pero raro. Si otro desarrollador de la misma red también tiene el problema, la red es el problema. Si se limita a una máquina, un reintento en unos minutos lo confirmará. Retroalimentación: demasiado raro para ser la respuesta. La infraestructura de instalación es muy fiable. Si un desarrollador lo sufre y los demás no, el problema está en el entorno de red de ese desarrollador, no en el servidor.

Error #2. Un desarrollador instaló Claude Code y se autenticó. Ahora ejecuta claude --version y obtiene: «command not found: claude»

• El PATH de la terminal no se actualizó tras la instalación.
• El paso de autenticación falló en silencio.
• No ejecutó la instalación desde su directorio personal.

Ver respuesta

Cada opción, con su marca y su retroalimentación de la lección:

• Mejor. El PATH de la terminal no se actualizó tras la instalación. El script de instalación añade claude al PATH, pero el shell no se recarga hasta que se reinicia la terminal. Pídele que cierre y abra una terminal nueva. Si está en la misma ventana, el cambio de PATH todavía no es visible. Retroalimentación: el bloqueo más común después de la instalación. El script actualiza el PATH, pero el shell no se recarga hasta que la terminal se reinicia. «Cerrar y abrir una terminal nueva» resuelve esto el 95 % de las veces. Rápido y predecible.
• Incorrecta. El paso de autenticación falló en silencio. Si la autenticación hubiera fallado, la instalación habría dado error. Si llegó a la terminal sin error de instalación, está autenticado. El problema casi siempre es el PATH. Retroalimentación: posible, pero ya lo sabrías. Si la autenticación hubiera fallado, la instalación en sí habría devuelto un error. Este desarrollador llegó a la terminal, lo que significa que la autenticación se superó.
• Parcial. No ejecutó la instalación desde su directorio personal. El script de instalación no depende del directorio de trabajo. Es una suposición plausible que te lleva a depurar en la dirección equivocada. Retroalimentación: irrelevante para este error. El script de instalación no depende del directorio de trabajo. Es una de esas suposiciones plausibles que te lleva a depurar en la dirección equivocada.

Ideas clave

Al terminar esta lección sabes qué bloqueos plantear primero, cómo guiar a un desarrollador por una instalación limpia y cómo diagnosticar los errores que aparecen con más frecuencia. La lista de verificación que produces es lo que envías a TI, y forma parte del Installation Configuration Pack que completarás a lo largo del curso.

• Confirma antes del día de instalación tres cosas: soporte del sistema operativo, acceso de red a los endpoints de Anthropic y método de autenticación de la cohorte.
• macOS, Linux y Windows (nativo o WSL) están soportados; WSL en equipos gestionados puede requerir un ticket de TI.
• El login por navegador es la ruta estándar para Team y Enterprise; las claves de API se usan para CI, headless o automatización.
• Verifica con claude --version y valida la configuración con claude doctor antes de incorporar la cohorte; usa /status para comprobar proxy y gateway.
• Un error «command not found» tras la instalación casi siempre es un problema de PATH, no de autenticación.

Siguiente: Integraciones con IDE: VS Code y JetBrains