3. Requisitos previos y entorno de trabajo

Objetivo del tema

Preparar tu equipo para ejecutar Claude Code sin sobresaltos: conocer los requisitos mínimos reales, decidir el método de instalación que usarás, elegir una terminal adecuada, reunir las herramientas complementarias y las credenciales de acceso, y verificar que todo esté listo antes de instalar en el próximo tema.

3.1 Qué necesita Claude Code (y qué no)

Claude Code es una aplicación de línea de comandos sorprendentemente liviana. Como el agente corre en tu máquina pero la inferencia ocurre en la nube de Anthropic, tu equipo no necesita potencia de cálculo especial: solo una terminal moderna, conexión a internet estable y lo indispensable del ecosistema de tu proyecto.

Los requisitos mínimos son:

  • Sistema operativo: macOS 11 o superior, Ubuntu 20.04+/Debian 10+ o Windows 10/11 (nativo o mediante WSL).
  • Memoria RAM: 4 GB como mínimo; 8 GB o más dan margen cómodo para proyectos grandes.
  • Conexión a internet: permanente, porque cada respuesta del modelo viaja desde la API de Anthropic.
  • Una terminal moderna: con soporte de colores verdaderos y caracteres Unicode para que la interfaz interactiva se renderice correctamente.
  • Credenciales de acceso: una suscripción de Claude.ai (Pro, Max, Team o Enterprise) o una clave de Anthropic API con facturación activa.

Y lo que no necesitas, que también conviene aclarar: GPU ni hardware especial, servidores de indexación del código, contenedores obligatorios ni bases de datos auxiliares. Claude Code funciona directamente sobre tu árbol de archivos con las herramientas que ya tienes instaladas.

La mayor parte del "peso" de Claude Code está en el modelo, no en el cliente. Por eso un netbook viejo puede ejecutarlo sin problemas siempre que la conexión a internet sea buena: tu equipo solo lee archivos, edita y ejecuta comandos; el razonamiento ocurre del otro lado.

3.2 Sistemas operativos soportados

Claude Code tiene soporte nativo en las tres plataformas principales. La tabla siguiente resume el estado de cada una:

Soporte por plataforma
Plataforma Requisito Notas
macOS 11 (Big Sur) o superior Soporte completo, incluidos los Mac con Apple Silicon.
Linux Ubuntu 20.04+ / Debian 10+ (glibc moderna) Funciona también en otras distribuciones y en entornos remotos por SSH.
Windows 10/11 con Git for Windows instalado Nativo en PowerShell y CMD; WSL2 como alternativa recomendada para flujos POSIX.

Un caso frecuente y bien soportado es el desarrollo remoto: puedes ejecutar Claude Code en un servidor, una máquina virtual o un contenedor de desarrollo y conectarte desde cualquier equipo liviano. La documentación oficial incluso ofrece una plantilla de devcontainer para trabajar dentro de un entorno aislado de Docker, útil en empresas con políticas estrictas de seguridad.

3.3 Node.js: cuándo lo necesitas y cuándo no

Aquí hay una decisión importante que conviene tomar antes de instalar. Existen dos vías de instalación y solo una de ellas requiere Node.js:

  • Instalador nativo: descarga un binario autocontenido, sin dependencias externas. Si eliges esta vía (la recomendada hoy), no necesitas Node.js en absoluto.
  • Instalación vía npm: requiere Node.js 18 o superior y se integra bien si ya gestionas tu entorno con nvm, fnm o asdf.

Si decides usar la vía npm, verifica tu versión con anticipación:

node --version    # debe ser 18.0.0 o superior

Aunque instales el binario nativo, Node.js sigue siendo útil por otras razones: muchos servidores MCP están escritos en JavaScript y se ejecutan con npx, y buena parte del ecosistema de herramientas de desarrollo lo asume. Por eso la recomendación práctica es tenerlo, aunque no sea estrictamente obligatorio. Para servidores MCP escritos en Python, el gestor uv cumple un rol equivalente.

3.4 Credenciales: suscripción o clave de API

Claude Code admite dos formas de acceso, que se detallarán en el tema 5. Para este tema basta con decidir cuál usarás:

  • Suscripción de Claude.ai (Pro o Max): pagas un monto fijo mensual con cupos amplios de uso. Es la opción más sencilla para empezar: al primer arranque, el navegador se abre para iniciar sesión y listo.
  • Clave de Anthropic API (Console): pago por tokens consumidos, con control granular del gasto. Requiere crear la clave en console.anthropic.com con facturación activa. Ideal para automatizaciones, CI/CD y entornos corporativos.
  • Empresas con nube propia: también es posible operar sobre Amazon Bedrock o Google Vertex AI mediante variables de entorno, sin exponer claves de Anthropic.

Regla de seguridad desde ya: las claves de API viven en variables de entorno o en el gestor de credenciales del sistema, jamás en archivos del repositorio ni en scripts versionados. Antes de instalar, decide dónde vas a guardar la tuya.

3.5 Elección de terminal: comparativa rápida

La interfaz interactiva de Claude Code renderiza colores verdaderos, caracteres Unicode y actualizaciones en vivo, así que una terminal moderna marca la diferencia. La buena noticia: casi cualquier terminal actual funciona; solo evita emuladores muy antiguos o minimalistas.

Emuladores de terminal recomendados para Claude Code
Terminal Plataformas Destacado
Terminal.app / iTerm2 macOS Terminal.app funciona bien; iTerm2 agrega paneles, búsqueda y perfiles.
Warp, Ghostty, Kitty, WezTerm macOS, Linux (algunas también en Windows) Terminales modernas de alto rendimiento, ideales para sesiones largas.
GNOME Terminal, Konsole, Alacritty Linux Opciones estándar y livianas con soporte completo de colores.
Windows Terminal + PowerShell Windows La opción nativa recomendada; soporte completo de la interfaz interactiva.
Terminal dentro de VS Code / JetBrains Todas Muy cómoda para trabajar con el agente junto al código (tema 12).

Si la interfaz se ve con caracteres rotos, colores planos o el texto se superpone, el problema casi siempre es el emulador de terminal, no Claude Code. Prueba con Windows Terminal, iTerm2, Ghostty o WezTerm antes de buscar otros culpables.

3.6 Git y GitHub CLI: los compañeros imprescindibles

Técnicamente Claude Code funciona en cualquier carpeta, pero su potencial se libera sobre repositorios versionados:

  • Git (imprescindible en la práctica): permite revisar los diffs que propone el agente, retroceder con /rewind o git checkout, y crear commits atómicos por cada tarea. Instálalo desde git-scm.com y configura tu identidad global:
git config --global user.name "Tu Nombre"
git config --global user.email "tu@correo.com"
  • GitHub CLI (gh, recomendado): con la CLI de GitHub autenticada, el agente puede abrir pull requests, leer issues y atender revisiones desde la conversación; será protagonista del tema 13.
  • ripgrep: no hace falta instalarlo; Claude Code incluye su propia versión para las búsquedas de contenido.
  • Runtimes de tus proyectos: Node, Python, Go, Rust o los que usen tus repositorios. El agente ejecutará tests, builds y scripts con las versiones que tú tengas instaladas.

3.7 Red y entornos corporativos

Si trabajas detrás de un firewall corporativo o un proxy, planifícalo antes de instalar. Claude Code necesita acceso saliente a estos dominios:

api.anthropic.com        # API de modelos (imprescindible)
statsig.anthropic.com    # telemetría y pruebas de funciones
sentry.io                # reporte de errores del cliente

Para proxies corporativos, las variables de entorno HTTPS_PROXY y HTTP_PROXY están soportadas de forma nativa, y NO_PROXY permite excluir hosts internos. En organizaciones que no permiten enviar código a servicios de terceros, la alternativa es operar sobre Bedrock o Vertex AI, donde la inferencia corre dentro de tu propia cuenta de nube. Claude Code no admite ejecución sin conexión: el modelo siempre está en la nube.

3.8 Consideraciones para Windows

Windows tiene dos caminos válidos, y conviene elegir uno conscientemente:

  • Nativo (PowerShell o CMD): soporte completo desde 2025. Requiere tener Git for Windows instalado, porque el agente lo utiliza para ejecutar comandos de estilo Unix. Es la opción más directa para quien ya trabaja en PowerShell.
  • WSL2 (Windows Subsystem for Linux): un entorno Ubuntu real dentro de Windows, con permisos POSIX, shell bash y compatibilidad total con las herramientas de tu proyecto:
wsl --install          # instala WSL2 con Ubuntu por defecto

Si trabajas dentro de WSL, clona tus repositorios dentro del sistema de archivos de WSL (por ejemplo ~/proyectos/) y no en /mnt/c/...: el acceso a disco sobre la partición de Windows es mucho más lento y penaliza a cualquier agente que lea miles de archivos.

En ambos caminos, revisa la configuración de fin de línea de Git para evitar diffs ruidosos entre plataformas: git config --global core.autocrlf true en Windows nativo, o input dentro de WSL.

3.9 Verificaciones iniciales y checklist

Con las piezas anteriores en su lugar, comprueba tu entorno:

git --version          # imprescindible
node --version         # opcional (npm/MCP), 18+
gh --version           # opcional (GitHub CLI)
claude --version       # fallará aún: instalaremos en el tema 4

Como todavía no instalamos Claude Code, el último comando debería fallar con un "comando no encontrado"; es lo esperado. Tras instalar, conocerás además claude doctor, el diagnóstico integrado que verifica versión, instalación y conectividad en un solo paso.

La tabla siguiente resume el estado ideal antes de pasar al tema 4:

Checklist previo a la instalación
Paso Acción Resultado esperado
1. Elegir terminal Windows Terminal, iTerm2, Ghostty, WezTerm o equivalente. La interfaz interactiva renderiza colores y símbolos sin errores.
2. Instalar Git Verificar con git --version y configurar identidad global. Diffs y commits generados por el agente quedarán correctamente firmados.
3. Decidir vía de instalación Nativo (sin Node) o npm con Node 18+. Instalación previsible y fácil de actualizar después.
4. Conseguir credenciales Suscripción Pro/Max activa o clave de API con facturación. Autenticación sin fricciones en el primer arranque.
5. Validar red Acceso a api.anthropic.com desde tu red (o proxy configurado). Sin errores de conexión al usar el agente.
6. Preparar repositorio de prueba git init o git clone de un proyecto pequeño. Espacio seguro para experimentar en los próximos temas.

3.10 Buenas prácticas continuas

  • Mantén Git, tu terminal y los runtimes de tus proyectos actualizados: Claude Code evoluciona rápido y se integra con versiones recientes de las herramientas.
  • Guarda las claves de API en variables de entorno o en el almacén de credenciales del sistema; nunca las subas a repositorios ni las pegues en scripts compartidos.
  • Usa un repositorio de prueba dedicado para aprender: permite equivocarse sin riesgo antes de tocar proyectos reales.
  • En equipos, acuerden versión mínima de Claude Code, terminal soportada y configuración común de Git para reducir diferencias de comportamiento entre compañeros.
  • Si tu organización exige aislamiento, evalúa el devcontainer oficial o un entorno remoto dedicado antes de instalar en tu máquina principal.

Conclusión: los requisitos reales de Claude Code son modestos: una terminal moderna, Git, conexión a internet y credenciales de acceso; el resto (Node.js, gh CLI, WSL) son complementos que amplían capacidades. Con el checklist completo, en el próximo tema instalaremos Claude Code usando el método que mejor se ajuste a tu sistema operativo.

Retornar