Pautas de uso en Windows: entorno nativo frente a WSL, cómo ejecutarlo de forma sencilla

📚 Navegación de la serie: El artículo anterior 〔32 Migrar desde Claude Code〕 detalló la equivalencia de conceptos, comandos y configuraciones para migrar flujos de trabajo. Esta sección está dirigida a usuarios de Windows: dado que las guías generales asumen un entorno basado en Unix (Mac o Linux), analizaremos las particularidades de Windows relativas a rutas de archivos, codificación de saltos de línea y las políticas de seguridad del sandbox. El siguiente artículo 〔34 Proyecto integrado de práctica〕 consolidará las habilidades aprendidas en un ejercicio práctico completo.

Les contaré una tontería que hice yo mismo.

En marzo de 2026, al instalar por primera vez Codex en mi portátil de desarrollo con Windows 11, opté por omitir la instalación de WSL para ejecutarlo directamente en PowerShell nativo. Si bien el proceso de instalación concluyó con éxito, el sistema arrojaba errores al intentar modificar archivos. Al analizar los registros, identifiqué que el repositorio clonado desde Mac utilizaba saltos de línea en formato LF, mientras que Git en Windows los convertía automáticamente a CRLF al descargarlos. Cuando Codex modificaba y guardaba un archivo, las diferencias en Git (diff) reportaban caracteres ^M en cada línea, interpretando el cambio como si todo el archivo hubiera sido modificado. Asumí erróneamente que se trataba de un fallo en Codex, hasta que comprendí que la demora se debía a la gestión de saltos de línea en Windows.

En la actualidad, Codex se ejecuta de forma nativa en Windows con una experiencia fluida, pero su comportamiento difiere del de Mac/Linux. Las políticas del sandbox son específicas para Windows, las rutas de archivos utilizan barras invertidas y la codificación de saltos de línea requiere atención para evitar errores de consistencia en el código.

Este artículo detalla la configuración de Codex en Windows: proceso de instalación, elección del entorno nativo frente a WSL, resolución de errores comunes de codificación y la estructura del sandbox en este sistema operativo.

Al terminar de leer este artículo, obtendrás:

• La recomendación del flujo de ejecución óptimo en Windows.
• El procedimiento de instalación del CLI mediante scripts de PowerShell y sus dependencias de sistema asociadas.
• Pautas de elección: PowerShell nativo frente a WSL2 según su flujo de desarrollo.
• Solución a los tres problemas recurrentes en Windows: rutas de archivos, codificación CRLF y advertencias de permisos de directorios (Everyone).
• La diferencia de comportamiento entre las políticas de sandbox elevated y unelevated en Windows y cómo depurar el error 1385.
• Un ejercicio práctico paso a paso para ejecutar una tarea en PowerShell nativo.

⚠️ Los comandos, propiedades de configuración y comportamientos se contrastan con la documentación oficial de Codex. Los modelos y versiones son ilustrativos y pueden variar con el tiempo. Las pautas detallan en qué consola ejecutar cada paso (PowerShell o WSL), prestando atención para evitar confusiones de entorno.

---

01 El flujo de ejecución óptimo en Windows

Para simplificar su entorno de desarrollo:

Se recomienda priorizar la ejecución en el entorno nativo de Windows configurando el sandbox en modo elevated como la opción estándar; esto garantiza un rendimiento óptimo de lectura/escritura y mantiene los estándares de seguridad de la herramienta. Use WSL2 únicamente si su flujo de trabajo de desarrollo actual ya opera dentro de ese entorno o si las directivas de seguridad de su sistema impiden el arranque del sandbox nativo.

Aunque algunas guías recomiendan forzar el uso de unelevated o implementar WSL por defecto en Windows, la documentación oficial señala que el sandbox nativo en modo elevated ofrece el mayor rendimiento del sistema de archivos y mantiene los niveles de seguridad equivalentes a otros sistemas operativos, relegando el modo unelevated como una alternativa secundaria de compatibilidad.

Analogía: La elección del tendido de red en su domicilio. La conexión de fibra óptica directa a su módem (modo elevated) representa la opción más estable y rápida. Si existen restricciones físicas en la infraestructura que impiden el tendido de fibra, puede optar por una red cableada estándar (modo unelevated) o, en caso extremo, desplazarse a otra instalación con conexión activa (WSL2). Para la mayoría de usuarios, la conexión directa es la opción óptima y no requiere configuraciones secundarias.

Criterios de elección del entorno de desarrollo:

• Desarrollo cotidiano en Windows usando herramientas nativas y editores como VS Code: ejecute Codex en el entorno nativo configurado en modo elevated.
• Equipos con políticas de seguridad estrictas (ordenadores corporativos con bloqueo de permisos de administrador): si no es posible inicializar el modo elevated, configure el sandbox en unelevated y notifique al departamento de soporte técnico de su empresa.
• Entorno de desarrollo actual alojado dentro de WSL (uso de scripts de shell y utilidades Linux): ejecute Codex directamente dentro de su distribución de WSL2.

💡 Resumen en una frase: Use la configuración nativa de Windows con el sandbox en elevated como opción predeterminada, limitando el uso de WSL2 únicamente si su flujo de trabajo requiere herramientas nativas de Linux.

---

02 Procedimiento de instalación y dependencias

La instalación del CLI de Codex en Windows se realiza mediante la ejecución del script oficial en la consola.

Abra una ventana de PowerShell o Windows Terminal y ejecute:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Como alternativa, si su sistema dispone de Node.js instalado, puede instalar el CLI a nivel global mediante npm:

npm install -g @openai/codex

Una vez completada la descarga, reinicie la consola de comandos para actualizar las variables de entorno de la sesión y verifique la instalación ejecutando:

codex --version

Resultado esperado: la consola devuelve el número de versión instalado en formato codex 0.x.x, confirmando el correcto registro de la herramienta en el sistema.

Si prefiere utilizar la interfaz gráfica, OpenAI distribuye la App de escritorio de Codex a través de Microsoft Store. Puede descargarla directamente de la tienda o instalarla desde la consola de comandos mediante winget: winget install Codex -s msstore.

Dependencias de sistema requeridas

Para prevenir fallos en la ejecución, asegúrese de contar con los siguientes elementos:

Dependencia	Función	Notas de configuración
Windows 11 (Recomendado)	Versión optimizada de compatibilidad	También compatible con Windows 10 (versión 1809 o superior)
Herramienta winget	Descarga de paquetes y dependencias	Se incluye por defecto en actualizaciones recientes de Windows
Permisos de administrador	Requerido para inicializar el sandbox elevated	Confirmar permisos UAC al arrancar
Visual C++ Build Tools	Compilación de extensiones locales en el IDE	Instalar mediante winget install --id Microsoft.VisualStudio.2022.BuildTools -e

Si implementa extensiones de IDE en VS Code y experimenta demoras en el arranque de Codex, instale las C++ Build Tools de Visual Studio ejecutando la línea de comando winget detallada en la tabla y reinicie el editor para asegurar la compilación de dependencias nativas.

💡 Resumen en una frase: Instale Codex CLI mediante el script de PowerShell nativo y configure las C++ Build Tools si utiliza las extensiones de IDE para evitar errores de compilación de dependencias.

---

03 WSL2 frente a PowerShell nativo: criterios de selección

La elección del entorno de ejecución debe responder a la ubicación de sus archivos de código y herramientas de compilación.

Analogía: Elegir la oficina de trabajo. El entorno nativo de Windows (PowerShell) representa su oficina principal, donde se ejecutan sus aplicaciones nativas y editores. WSL2 funciona como un contenedor Linux aislado dentro de la misma oficina. Si requiere ejecutar scripts bash o herramientas de compilación nativas de Linux, debe ingresar a ese espacio de trabajo de forma dedicada, evitando mover los archivos de un entorno a otro constantemente para prevenir demoras.

Comparativa de entornos de desarrollo:

Variable	PowerShell nativo	WSL2
Instalación	Script de instalación simple	Requiere habilitar WSL e instalar una distribución
Velocidad I/O	Rendimiento máximo nativo	Demoras en lectura/escritura si accede a discos de Windows (/mnt/c/)
Sandbox	Lógica nativa (elevated / unelevated)	Lógica de Linux mediante la utilidad bubblewrap
Compatibilidad	Herramientas Windows y ejecutables .exe	Herramientas Linux nativas y scripts bash
Perfil idóneo	Mayoría de desarrolladores Windows	Flujos de trabajo dependientes de Linux o Docker nativo

Si opta por la ejecución en WSL2, asegúrese de habilitar la característica desde una ventana de PowerShell con permisos de administrador:

wsl --install
wsl

Una vez dentro de la consola de WSL, debe instalar Codex CLI de forma independiente dentro del entorno Linux (la instalación nativa de Windows no se comparte con el contenedor):

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

IMPORTANT

No almacene los archivos de su proyecto en la partición de Windows si trabaja desde WSL. Acceder a rutas como /mnt/c/Users/... desde WSL ralentiza las operaciones de análisis de código de Git y Codex. Clone su repositorio directamente en el sistema de archivos nativo de Linux (ej. ~/code/) para garantizar una velocidad de ejecución óptima.

Puede acceder a los archivos de WSL desde el explorador de Windows utilizando la ruta de red \\wsl$\Ubuntu\home\<usuario>\ (sustituyendo <usuario> por su nombre de usuario en Linux). Tenga en cuenta que Codex requiere WSL2 en sus versiones actuales, habiendo finalizado el soporte para WSL1 debido a las dependencias del sandbox de seguridad.

💡 Resumen en una frase: Use PowerShell nativo si compila sus proyectos directamente en Windows; use WSL2 si sus herramientas y dependencias se ejecutan en Linux, asegurándose de almacenar los repositorios en el sistema de archivos nativo de la distribución.

---

04 Solución a problemas recurrentes en Windows

A continuación se detallan los tres problemas más comunes y cómo solucionarlos al ejecutar Codex en Windows:

1. Sintaxis de rutas de archivos

Windows utiliza barras invertidas (\) en sus rutas de archivos en lugar de la barra diagonal (/) de Unix. Codex gestiona esta conversión de forma automática, pero debe prestar atención en dos configuraciones:

• Al declarar rutas en su archivo global de preferencias ~/.codex/config.toml, use rutas absolutas formateadas con barras invertidas (ej. C:\Users\Usuario\Proyecto).
• Al autorizar directorios de lectura en el sandbox durante una sesión activa, declare la ruta exacta utilizando el comando interno de la sesión:

/sandbox-add-read-dir C:\Users\Usuario\Proyecto

Esta autorización tiene validez durante la conversación activa, debiendo reconfigurarse al abrir una nueva sesión.

2. Codificación de saltos de línea (CRLF)

Este comportamiento corresponde a la gestión de cambios de Git en Windows. Si clona un repositorio configurado con saltos de línea LF (estándar de Unix), Git en Windows puede convertirlos automáticamente a CRLF. Al modificar y guardar el archivo, Codex mantendrá la codificación local, provocando diferencias en Git que dificultan la auditoría de cambios.

Para solucionar esto, cree un archivo .gitattributes en la raíz de su repositorio para unificar el formato de los archivos del proyecto:

* text=auto eol=lf

Como alternativa, puede desactivar globalmente la conversión automática de saltos de línea en su PowerShell:

git config --global core.autocrlf false

Consulte con su equipo de desarrollo qué política de saltos de línea se encuentra activa en el proyecto antes de aplicar cambios globales en su consola.

3. Advertencias de permisos del sistema de archivos (Everyone)

Si Codex detecta que un directorio de su proyecto cuenta con permisos de acceso muy permisivos en Windows (como privilegios de escritura asignados al grupo Everyone), emitirá una advertencia de seguridad en la consola. Esta advertencia indica que el sandbox no puede garantizar el aislamiento de los archivos bajo esa configuración. Modifique las propiedades de seguridad de la carpeta en Windows removiendo los privilegios de escritura para usuarios no autenticados y reinicie el CLI.

Problema	Síntoma en consola	Solución recomendada
Rutas de archivos	Directorios no encontrados o de solo lectura	Usar rutas absolutas nativas en configuraciones y comandos /sandbox-add-read-dir
Codificación CRLF	Diferencias en Git excesivas con caracteres ^M	Configurar eol=lf en .gitattributes o desactivar core.autocrlf en Git
Permisos de directorio	Advertencias sobre seguridad del grupo Everyone	Ajustar los permisos de acceso de la carpeta en las propiedades de seguridad de Windows

💡 Resumen en una frase: Evite errores en Windows usando rutas absolutas en las configuraciones, forzando la codificación de saltos de línea a LF en Git para mantener limpios los cambios, y restringiendo los permisos de escritura del grupo Everyone en las carpetas del proyecto.

---

05 Políticas del Sandbox en Windows

La infraestructura de aislamiento de Codex varía según el sistema operativo. En Mac se implementa sandbox-exec y en Linux bubblewrap, mientras que en Windows se han desarrollado dos perfiles de sandbox nativos específicos.

Puede definir el perfil del sandbox agregando la propiedad en su archivo de configuración global ~/.codex/config.toml:

[windows]
sandbox = "elevated" # Opciones: "elevated" o "unelevated"

Diferencias entre los perfiles de sandbox en Windows:

Perfil	Nivel de aislamiento	Mecanismo de control	Caso de uso recomendado
elevated (Predeterminado)	Alto	Cuenta de usuario local de bajos privilegios dedicada, reglas de firewall y políticas de grupo locales	Perfil estándar; recomendado por su rendimiento y nivel de seguridad
unelevated	Moderado	Token de seguridad restringido del usuario activo, reglas de ACL locales y aislamiento de red a nivel de proceso	Alternativa secundaria si las restricciones de sistema bloquean el modo elevated

El modo elevated se establece como la opción recomendada. Ambos perfiles aíslan la interfaz gráfica mediante la creación de un escritorio virtual privado; no desactive la propiedad windows.sandbox_private_desktop a menos que experimente fallos de compatibilidad con sesiones clásicas de Windows Station (Winsta0\Default).

Diagnóstico del error de inicio de sesión 1385

En sistemas corporativos administrados, la inicialización del sandbox en modo elevated puede fallar debido a políticas de seguridad del sistema operativo que restringen la creación de cuentas de usuario locales de bajos privilegios. Esto se reporta en la terminal con el código de error 1385 (inicio de sesión no autorizado para el usuario del sandbox).

Si experimenta el error 1385, aplique los siguientes pasos de diagnóstico:

1. Solicite al departamento de soporte técnico de su empresa validar si las políticas de grupo (GPO) permiten la inicialización de la cuenta de usuario local temporal creada por Codex.
2. Si no es posible modificar las políticas del sistema, configure temporalmente el sandbox en modo unelevated en su archivo config.toml para poder continuar trabajando.
3. El registro detallado de inicialización del sandbox se almacena en el archivo CODEX_HOME/.sandbox/sandbox.log; comparta este archivo con su administrador de sistemas para diagnosticar bloqueos de seguridad.

CAUTION

Al exportar registros de diagnóstico para soporte técnico, no comparta la carpeta CODEX_HOME/.sandbox-secrets/, ya que contiene las claves y tokens de cifrado de su sesión de Codex.

Si una instrucción de terminal falla por restricciones de lectura del sandbox, use /sandbox-add-read-dir para autorizar explícitamente el acceso al directorio correspondiente.

💡 Resumen en una frase: El sandbox nativo implementa los perfiles elevated (estándar y seguro) y unelevated (compatibilidad); si experimenta el error 1385 de permisos de inicio de sesión locales, cambie temporalmente al perfil unelevated en config.toml.

---

06 Ejercicio práctico: Ejecutar una tarea en PowerShell nativo

Realizaremos la configuración y prueba de una tarea de desarrollo básica utilizando la terminal de PowerShell en Windows, validando el comportamiento de las rutas y saltos de línea.

Requisitos: contar con Codex CLI instalado y ejecutar los pasos en un entorno nativo de Windows (PowerShell).

Paso 1: Inicializar el proyecto y archivo de código

Abra su ventana de PowerShell y cree un directorio de pruebas:

mkdir codex-win-test
cd codex-win-test
git init
"console.log('hi')" | Out-File -Encoding utf8 app.js

Si utiliza PowerShell v5.1, la codificación utf8 incluye caracteres BOM. En PowerShell v7 o superior, se recomienda usar Set-Content -Encoding utf8NoBOM para escribir archivos planos sin metadatos de codificación.

Paso 2: Configurar la política de saltos de línea

Cree el archivo .gitattributes en la raíz del directorio para fijar el formato de codificación del proyecto:

* text=auto eol=lf

Este paso asegura que los saltos de línea se gestionen en formato LF de forma homogénea.

Paso 3: Iniciar Codex

Ejecute la utilidad en la terminal:

codex

Durante el arranque en modo elevated, se mostrará la ventana de confirmación de control de cuentas de usuario (UAC) de Windows. Confirme la solicitud; si el entorno está restringido por directivas del sistema, el CLI reportará la redirección automática al modo unelevated para continuar con la sesión.

Paso 4: Enviar una tarea de edición

En la terminal de chat de Codex, envíe la siguiente instrucción:

Modifica el archivo app.js para cambiar el texto 'hi' por 'hello, codex on windows'

Resultado esperado: Codex lee el archivo app.js, despliega el bloque de diferencias (diff) y le solicita confirmación. Tras aprobar los cambios, la respuesta se escribe en el archivo y finaliza el proceso de edición. Compruebe el contenido modificado:

Get-Content app.js

Debería mostrar la línea de código actualizada:

console.log('hello, codex on windows')

Paso 5: Validar el diff de Git

Es una buena práctica comprobar las diferencias del repositorio después de que Codex realice cambios de archivos en Windows para confirmar que no se han introducido metadatos de formato o saltos de línea incorrectos:

git diff

Resultado esperado: las diferencias de Git deben reportar únicamente el cambio de la cadena de texto de la línea modificada, libre de advertencias de cambio de codificación o saltos de línea del tipo ^M. Si se reporta la conversión de todo el archivo, valide la configuración de su .gitattributes.

Completar esta prueba le ayuda a configurar correctamente su terminal para el desarrollo de proyectos en Windows.

💡 Resumen en una frase: La prueba práctica en Windows requiere: crear un directorio local en PowerShell → fijar la codificación a LF con .gitattributes → abrir Codex aceptando permisos → solicitar la edición de un archivo plano → verificar mediante git diff que no se hayan introducido caracteres ^M en los saltos de línea.

---

Resumen

En este artículo hemos detallado las particularidades del uso de Codex en entornos de desarrollo bajo el sistema operativo Windows:

• Ejecución recomendada: use la configuración nativa de Windows con el sandbox en modo elevated por rendimiento; limitando el uso de WSL2 a flujos que requieran dependencias nativas de Linux.
• Instalación y dependencias: implemente la instalación mediante el script oficial de PowerShell y asegure las C++ Build Tools de Visual Studio para las extensiones de IDE.
• Saltos de línea (CRLF): configure el archivo .gitattributes con eol=lf en sus proyectos para evitar diferencias de Git con caracteres de formato ^M al editar archivos en Windows.
• Políticas de Sandbox: Windows implementa los modos elevated y unelevated de forma específica; si surgen restricciones de inicio de sesión locales (error 1385), cambie temporalmente al perfil unelevated en config.toml.

Gestionar de forma adecuada las particularidades del sistema de archivos y las políticas del sandbox le permite desarrollar sus proyectos en Windows de forma ágil y segura.

---

El siguiente artículo 34 · Proyecto integrado de práctica: implementaremos un ejercicio práctico completo para consolidar las habilidades adquiridas a lo largo de la serie, abarcando desde la inicialización de configuraciones hasta la resolución de requerimientos de desarrollo en un proyecto real.

---

Lecturas recomendadas

• Uso de modelos y APIs alternativas en Codex
• Estructurar tareas en flujos de desarrollo cotidianos
• Configuración de extensiones en entornos de IDE locales