Claude Code en Windows: configuración para desarrolladores

Configuración profesional de Claude Code en Windows: Consejos clave para profesionales de TI

La configuración de Claude Code en Windows requiere tener en cuenta las particularidades del sistema operativo e integración con herramientas de desarrollo. Este artículo comparte configuraciones probadas para trabajar con AWS, PowerShell y Git Bash sin errores.

Preparación del entorno

Para que Claude Code funcione correctamente, configura adecuadamente los componentes básicos. Comienza instalando Git Bash, un componente crítico, ya que el instalador de Claude Code lo usa para ejecutar comandos:

winget install Git.Git

Durante la instalación de Git, mantén todas las configuraciones predeterminadas, incluida la integración con Explorer y la adición a PATH. Presta especial atención a PowerShell: Windows tiene por defecto una versión desactualizada 5.1 en .NET Framework. Los proyectos modernos requieren PowerShell 7+:

winget install Microsoft.PowerShell

Después de la instalación, inicia pwsh, no powershell.exe. Verifica la versión:

pwsh --version

Importante: Todos los comandos posteriores deben ejecutarse en PowerShell 7+. Por comodidad, usa Windows Terminal, que permite trabajar en paralelo con diferentes shells.

Instalación y autenticación

Características clave de la instalación:

• Usa el script oficial:

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

• La alternativa de WinGet requiere actualizaciones manuales:

winget install Anthropic.ClaudeCode

• Para una versión específica:

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.105

Después de la instalación, verifica que funcione:

claude --version
claude doctor

Si obtienes un error de command not found, agrega la ruta manualmente:

$userPath = [Environment]::GetEnvironmentVariable("PATH", "User")
[Environment]::SetEnvironmentVariable("PATH", 
  "$userPath;$env:USERPROFILE\.local\bin", 
  "User")

Para la autenticación:

• Para la mayoría de los usuarios, solo ejecuta claude e inicia sesión vía navegador
• Para facturación de API, establece la clave:

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-api03-...", "User")

Configuración específica de Windows

Solucionando problemas de PowerShell

Por defecto, Claude Code usa Git Bash, lo que causa conflictos con la sintaxis de PowerShell. Para un funcionamiento adecuado, agrega a %USERPROFILE%\.claude\settings.json:

{
  "env": {
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1",
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  },
  "defaultShell": "powershell"
}

Esto activa:

• Detección automática de pwsh.exe
• Redirección de comandos interactivos a través de PowerShell
• Mantenimiento de Git Bash para operaciones internas

Trabajo con rutas y sistema de archivos

NTFS tiene diferencias fundamentales con los sistemas de archivos de Linux:

• Insensibilidad a mayúsculas/minúsculas para nombres de archivos
• Requisitos de permisos para enlaces simbólicos
• Peculiaridades en el manejo de finales de línea (CRLF vs LF)

Configuraciones críticas:

• Siempre usa rutas de Windows con barras invertidas
• Para scripts, agrega conversión de finales de línea:

(Get-Content script.sh) -replace "`r`n", "`n" | Set-Content -NoNewline script.sh

• En las instrucciones globales (%USERPROFILE%\.claude\CLAUDE.md), especifica:

# File paths
- Use Windows paths: C:\\Users\\<user>\\projects\\...
- Do NOT use Unix paths

Integración con servicios en la nube

AWS y PowerShell

Para trabajar con AWS vía PowerShell:

• Instala AWS Tools for PowerShell
• Configura perfiles en %USERPROFILE%\.aws\credentials
• En CLAUDE.md, agrega:

# Available tools
- Use aws-powershell for AWS operations
- Use SSM documents with PowerShell

Solucionando problemas del servidor MCP

MCP usa sockets de dominio Unix, no disponibles en Windows. Solución alternativa:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:/Projects"]
    }
  }
}

Importante:

• Usa barras diagonales en rutas de JSON
• Evita rutas Unix hardcodeadas en el código del servidor
• Para archivos temporales, especifica rutas específicas de Windows

Puntos clave

• PowerShell 7+ es obligatorio — la versión 5.1 no soporta escenarios modernos
• Git Bash es crítico — incluso con PowerShell, se necesita para operaciones internas
• Rutas al estilo Windows — Claude Code no reconoce rutas Unix ni accesos directos con ~
• Problemas de MCP — requieren configuración manual vía cmd /c en Windows
• Finales de línea — la conversión automática CRLF→LF es esencial para scripts

Consejos para desarrolladores rusos

A partir de 2026, el acceso oficial a Claude Code en Rusia estará restringido. Soluciones recomendadas:

• Cuentas corporativas vía proveedores en la nube (AWS Bedrock)
• Servidores proxy con autenticación
• Facturación de API con prepago
• Servidores MCP alternativos con rutas localizadas

Importante: Con una clave API, asegúrate de que esté activa y vinculada a una cuenta funcional. Verifica el estado vía claude /status.

Conclusión

La configuración de Claude Code en Windows depende de tres aspectos clave: configuración adecuada de PowerShell, adaptaciones a NTFS y correcciones del servidor MCP. Para desarrolladores de AWS, especificar correctamente las rutas en archivos de configuración y manejar los finales de línea es crucial. Sigue estos consejos y alcanzarás un rendimiento equivalente al de Linux.

— Editorial Team