Resolución de problemas comunes: Qué hacer si no instala, no inicia sesión o no modifica archivos

📚 Navegación de la serie: El artículo anterior (36 Mejores prácticas) se centró en "cómo usarlo correctamente y de forma fluida", convirtiendo las buenas costumbres en memoria muscular. Este artículo es lo contrario: está diseñado para resolver cualquier contratiempo en el uso: fallos al instalar o al iniciar sesión, que se niegue a modificar tus archivos o que pierda rendimiento en conversaciones largas. Abordaremos los problemas más frecuentes uno a uno. El próximo artículo (38 Glosario) es el diccionario de cierre de toda la sección de Codex, al que podrás recurrir para consultar términos desconocidos.

"Oye, hermano, terminé el npm install, pero al escribir codex me dice command not found, ¿qué hago?"

"A mí no me carga el inicio de sesión y no se abre el navegador. ¿Necesito usar una VPN o proxy?"

"Puede leer mi código, pero cuando le pido que modifique un archivo me da un error diciendo que el sandbox no permite escribir. ¡Yo no he configurado nada de eso!"

Estas son las tres preguntas que más me han hecho en los grupos durante estos dos años; casi todos los días tropieza alguien con ellas. A decir verdad, el 90% de los problemas con Codex no son bugs, sino la falta de comprensión sobre algún comportamiento por defecto: o bien no te has autenticado, o los permisos están restringidos, o el contexto se ha saturado. En este artículo no voy a acumular teoría; iré resolviendo los problemas uno a uno según el "orden más probable en el que te los encuentres", detallando para cada caso "Síntoma → Causa → Solución" para que puedas solucionarlo tú mismo.

Al terminar este artículo, obtendrás:

• Una guía rápida de "Síntoma → Causa → Solución" para los diez fallos más comunes, ordenados por frecuencia real
• Soluciones específicas para los tres grandes obstáculos iniciales: problemas de instalación, de inicio de sesión y de conexión
• La verdad sobre los permisos detrás de "se niega a modificar archivos" y cómo habilitarlo con una sola línea de comandos
• El criterio para decidir si usar /compact o /new cuando el contexto se satura y el rendimiento decae
• Una lista de comprobación universal de "Comprobar estas tres cosas primero" para resolver por ti mismo problemas nuevos no contemplados

⚠️ Todo lo relacionado a continuación con comandos específicos, elementos de configuración y comportamientos por defecto se rige por la documentación oficial de Codex; los nombres de los modelos y números de versión, que varían con las actualizaciones, se regirán por lo que muestre tu terminal local con codex --version y el panel /model. Las soluciones de permisos que se describen corresponden a la documentación oficial de Autenticación y Permisos, aunque los perfiles de permisos (permission profiles) están marcados oficialmente como Beta y sujetos a cambios.

---

01 Método de diagnóstico: comprueba primero estas tres cosas antes de buscar explicaciones místicas

La conclusión primero: ante cualquier problema con Codex, no te apresures a reinstalar ni a cambiar de herramienta; primero confirma estas tres cosas en orden: versión, inicio de sesión y permisos. El 80% de los problemas se detiene en este filtro.

Analogía: El triaje médico. Si vas a urgencias, el enfermero no te mandará a hacer un TAC de inmediato; primero te tomará la temperatura, la presión arterial y te preguntará dónde te duele: tres indicadores básicos para descartar problemas mayores. El diagnóstico en Codex es igual; primero evalúa tres "constantes vitales" antes de profundizar:

# 1. ¿Es la versión correcta y está bien instalado?
codex --version

# 2. ¿Has iniciado sesión y qué método de autenticación usas?
codex login status

# 3. ¿Cómo están configurados los permisos de la sesión actual? (escríbelo en la interfaz interactiva)
/status

El primero te indica "si está instalado y si la versión es muy antigua"; el segundo te dice "si ha caducado la autenticación"; y el tercero te revela "en qué nivel están configurados el sandbox y la aprobación, y si puede modificar archivos".

Mi costumbre es la siguiente: siempre que alguien me pregunta por un error en Codex, lo primero que le digo es "pásame los resultados de estos tres comandos". En ocho de cada diez casos, el problema se hace evidente para la otra persona al intentar obtenerlos: o bien la versión es de hace seis meses, o login status muestra que nunca inició sesión.

💡 Resumen en una frase: El diagnóstico no es un misterio; evalúa primero la versión, el inicio de sesión y los permisos antes de realizar análisis más minuciosos.

---

02 No se instala o no se encuentra el comando

Esta es la primera prueba para los principiantes, y la que provoca que muchos desistan.

Síntoma: Escribes codex tras ejecutar npm install y la terminal te devuelve command not found: codex, o bien la instalación se interrumpe con una serie de errores en rojo.

Causa: Por lo general, no es un fallo de Codex, sino un problema de configuración de tu entorno. Las tres causas más comunes son: el directorio bin global de npm no está incluido en tu variable PATH, tu versión de Node es obsoleta, o careces de permisos suficientes para que npm instale en el directorio global.

Solución (intenta los pasos en orden de probabilidad):

• Confirma primero la versión de Node. Escribe node --version. Si es demasiado antigua (por ejemplo, una versión mayor de hace varios años), muchas herramientas actuales no podrán instalarse. Si es obsoleta, actualiza Node.
• command not found suele significar que tu variable PATH no incluye el bin global de npm. Escribe npm config get prefix para localizar el directorio global y confirma que su subdirectorio bin esté configurado en tu PATH.
• Si aparecen errores de permisos EACCES durante la instalación, significa que intentas escribir en directorios del sistema sin autorización. Evita forzarlo con sudo npm install -g; esto solo te acarreará problemas de permisos más adelante. Lo correcto es cambiar la ruta del directorio global de npm a una ubicación de la que seas propietario, o bien instalar Node mediante un gestor de versiones (como nvm).
• Si prefieres evitar complicaciones, no utilices npm. La documentación oficial de Codex ofrece métodos alternativos de instalación; consulta la guía de instalación correspondiente a tu plataforma. En mi caso, al configurar un nuevo Mac, npm no dejaba de dar errores de permisos; opté por la otra vía oficial sugerida y lo resolví en tres minutos.

Diferencias de plataforma: Los problemas de instalación para usuarios de Windows suelen deberse a otros motivos (ausencia de WSL, problemas de rutas, etc.). Esa categoría de inconvenientes se detalla de forma individual en 33 Puntos clave para Windows y no se abordará aquí.

💡 Resumen en una frase: command not found suele deberse a que PATH no incluye el bin global de npm; no utilices sudo para forzar los errores de permisos.

---

03 Error de inicio de sesión o credenciales caducadas

Una vez instalado, el segundo obstáculo es el inicio de sesión.

Síntoma: Escribes codex login y el navegador no se abre, o bien se abre pero la terminal se queda cargando indefinidamente; o bien, durante su uso, aparece repentinamente un mensaje de "no autenticado" o "sesión caducada" solicitándote iniciar sesión de nuevo.

Causa: El inicio de sesión de Codex utiliza por defecto una redirección al navegador: levanta un servidor temporal local en localhost:1455 esperando que el navegador le devuelva el token. Este proceso falla en tres situaciones: en máquinas remotas o sin interfaz gráfica (sin navegador), si la red local bloquea ese puerto de redirección, o si la caché de autenticación local se corrompe.

Solución:

• Si estás en local pero se queda cargando indefinidamente, confirma primero que el inicio de sesión en el navegador se haya completado correctamente y que el puerto localhost:1455 no esté ocupado ni bloqueado por un cortafuegos.
• Si no puedes iniciar sesión en entornos como servidores, Docker o conexiones SSH sin interfaz gráfica, el método oficial de preferencia es el inicio de sesión por código de dispositivo (device code, Beta):

codex login --device-auth

• Te proporcionará un enlace y un código de verificación de un solo uso. Abre el enlace en 任意一台有浏览器的机器 (cualquier dispositivo que tenga navegador), introduce el código y confirma; la terminal se autenticará automáticamente. Esta es la forma más sencilla de iniciar sesión de forma remota.
• Si el código de dispositivo tampoco funciona, existe un método manual: realiza el codex login en un equipo donde funcione correctamente y copia el archivo de caché ~/.codex/auth.json en la misma ruta de la máquina de destino. Atención: Este archivo contiene tu token de acceso, que equivale a tu contraseña; nunca lo subas a git, ni lo expongas en foros o chats.
• "Sesiones que caducan durante el uso": El inicio de sesión a través de ChatGPT en Codex renueva el token automáticamente antes de que caduque, por lo que no debería cerrarse con frecuencia. Si ocurre a menudo, comprueba el estado con codex login status, y si es necesario, cierra la sesión con codex logout e inicia sesión con codex login de nuevo. Los registros del inicio de sesión se guardan en codex-login.log; consúltalos para diagnosticar fallos de acceso.

Tu entorno	Método recomendado
Local con navegador	Ejecuta codex login directamente y completa el flujo
Remoto / Servidor / Sin interfaz gráfica	Código de dispositivo con codex login --device-auth
El código de dispositivo falla	Inicia sesión en local y copia ~/.codex/auth.json
Proxy TLS corporativo / CA privada	Define CODEX_CA_CERTIFICATE apuntando al certificado PEM antes de iniciar sesión

El año pasado estaba configurando Codex en un servidor headless para CI e intenté ejecutar codex login esperando a que se abriera el navegador; tardé cinco minutos en darme cuenta de que el sistema no tenía interfaz de escritorio. Cambié a codex login --device-auth, escaneé el código con el móvil y lo resolví en veinte segundos. En máquinas remotas, usa siempre el código de dispositivo y no intentes abrir el navegador.

💡 Resumen en una frase: En equipos remotos no esperes al navegador; el código de dispositivo con codex login --device-auth es la opción preferida.

---

04 La conexión se queda cargando: ¿es necesario un proxy o VPN?

Síntoma: El inicio de sesión, las conversaciones o las tareas se quedan cargando durante mucho tiempo y finalmente devuelven un error de tiempo de espera (timeout) o de conexión fallida.

Causa: Los modelos de Codex se ejecutan en los servidores de OpenAI, lo que dificulta la conexión directa en redes con ciertas restricciones geográficas. Además, los proxies TLS corporativos y los certificados CA privados pueden bloquear la conexión.

Solución:

• Muchos usuarios en redes restringidas necesitarán un proxy o VPN. Es un requisito indispensable: Codex debe conectarse a los servicios de OpenAI, y si la red está bloqueada, no funcionará nada. Asegúrate de que tu proxy esté configurado de forma global o afecte a los dominios correspondientes; si solo habilitas una extensión en el navegador pero la terminal no pasa por el proxy, la conexión seguirá fallando.
• Confirma que la terminal esté utilizando el proxy. Muchas personas ven que el navegador funciona y asumen que todo está bien, pero el proceso de Codex en la terminal no hereda esa configuración. Configura las variables de entorno HTTP_PROXY y HTTPS_PROXY necesarias, o utiliza una herramienta de proxy en modo global.
• Si la red corporativa emplea un proxy TLS de la empresa o una CA raíz privada, la conexión directa fallará por error de validación del certificado. El mecanismo oficial para solucionarlo es definir una variable de entorno apuntando al paquete de certificados PEM de tu empresa:

export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login

• Si no se define CODEX_CA_CERTIFICATE, el sistema recurrirá a SSL_CERT_FILE. Esta configuración de CA personalizada es válida para el inicio de sesión, peticiones HTTPS comunes y conexiones WebSocket cifradas.

Durante un tiempo estuve trabajando en una red interna corporativa donde el navegador abría ChatGPT perfectamente, pero Codex era incapaz de conectarse. Tras investigar, descubrí que el proxy TLS intermediario de la empresa reemplazaba los certificados. Configuré CODEX_CA_CERTIFICATE apuntando al certificado raíz facilitado por el equipo de TI y funcionó de inmediato. Grábate esto: "que el navegador tenga acceso a internet no significa que Codex lo tenga".

💡 Resumen en una frase: En entornos restringidos se requiere un proxy y configurar la terminal; para CAs corporativas privadas, utiliza CODEX_CA_CERTIFICATE para solucionar el problema.

---

05 No se encuentra o no se puede seleccionar un modelo determinado

Síntoma: No ves en tu panel /model algún modelo del que otros hablan, o bien defines un nombre de modelo específico y al iniciar obtienes un error que indica "el modelo no existe o no está disponible".

Causa: La lista de modelos disponibles varía según tu método de inicio de sesión (suscripción a ChatGPT frente a clave de API) y tu plan; además, algunos modelos están en fase de vista previa de investigación y limitados a planes específicos, mientras que otros modelos antiguos han sido retirados oficialmente.

Solución:

• Rígete por lo que muestre tu panel /model local y evita memorizar nombres. En la arquitectura actual, el modelo insignia por defecto es gpt-5.5, y el modelo ligero orientado a sub-agentes es gpt-5.4-mini. La gran mayoría de las cuentas tienen acceso a ambos.
• Es normal si no ves gpt-5.3-codex-spark; se trata de una vista previa de investigación instantánea limitada actualmente a suscripciones de ChatGPT Pro. Que no aparezca no significa que haya un error de instalación.
• Si configuras un modelo y te indica que no está disponible, revisa tu ~/.codex/config.toml y el parámetro codex exec --model para verificar si estás usando nombres obsoletos (como gpt-5.2 o gpt-5.3-codex). Estos modelos ya no se admiten en el inicio de sesión mediante ChatGPT; cámbialos por las versiones más recientes.
• Si deseas confirmar qué modelo estás utilizando exactamente, escribe /status en la sesión para comprobarlo en lugar de suponerlo.

Los nombres de los modelos y su disponibilidad cambian con las versiones y planes; este apartado expone la metodología de comprobación. Los modelos utilizables dependerán en última instancia de lo que muestre tu panel /model local.

💡 Resumen en una frase: La disponibilidad de los modelos depende de tu método de acceso y plan; rígete siempre por el panel /model y no intentes memorizar la lista.

---

06 Restricciones de permisos: el sandbox bloquea la escritura de archivos

Este es el origen principal de los problemas de "lectura permitida, escritura denegada", y el aspecto que más desconcierta a los principiantes.

Síntoma: Codex puede leer tu código y redactar análisis sin problemas, pero cuando le pides que modifique un archivo o ejecute comandos de escritura, devuelve un error indicando que el sandbox lo prohíbe, o bien se detiene a pedirte autorización para cada paso.

Causa: No es un bug, sino una medida de seguridad por defecto. Codex no modificará los archivos de tu sistema sin control; ejecuta sus comandos en un entorno de sandbox donde los permisos de escritura están restringidos por defecto. Si intenta realizar cambios fuera de su espacio de trabajo o conectarse a internet, se detendrá para solicitar tu aprobación. Esa sensación de bloqueo es en realidad el sistema protegiéndosete bajo el principio de mínimos privilegios.

Analogía: Una vivienda de alquiler. El arrendador (la configuración predeterminada de Codex) solo te otorga inicialmente permisos para "visitar la vivienda"; no te permite derribar tabiques ni sustituir el mobiliario. Si deseas realizar reformas, debes acordar y firmar con él primero el "alcance de las modificaciones" permitidas. No busca complicarte la vida, sino que evita actuar sin tu consentimiento explícito.

Solución (dos vías alternativas):

• Para flexibilizar el acceso de forma temporal, utiliza parámetros de la línea de comandos. Usa --sandbox (abreviado -s) para el sandbox, y --ask-for-approval (abreviado -a) para la aprobación. Si quieres que trabaje libremente en el proyecto actual y solo te consulte al salir de él, emplea la combinación recomendada de "escritura en espacio de trabajo + aprobación bajo petición":

codex --sandbox workspace-write --ask-for-approval on-request

• Las diferentes opciones y combinaciones se detallan en 15 Permisos, sandbox y aprobación, por lo que no se repetirán aquí.
• Para establecerlo de forma permanente, regístralo en ~/.codex/config.toml. Los nuevos perfiles de permisos (permission profiles, Beta) ofrecen tres niveles integrados:

Perfil de permisos integrado	Qué puede hacer	Escenario recomendado
:read-only	Solo lectura, ningún comando ejecutado tiene permitido escribir	Para analizar o revisar código sin alterar archivos
:workspace	Escritura en el espacio de trabajo y directorios temporales, lectura para lo demás	Desarrollo diario para modificar el proyecto actual
:danger-full-access	Elimina las restricciones locales de sandbox	Úsalo exclusivamente en contenedores aislados, no en tu máquina

Solo debes asignar a default_permissions el nombre del perfil que desees. Ten en cuenta una incompatibilidad documentada oficialmente: los perfiles de permisos y la antigua directiva sandbox_mode no pueden mezclarse. Si tu configuración incluye sandbox_mode o pasas el parámetro --sandbox, Codex recurrirá a la arquitectura anterior e ignorará el perfil de permisos. Elige una de las dos vías y evita configurarlas simultáneamente.

El invierno pasado, por simplificar las cosas, configuré la directiva de acceso total en el archivo config.toml global. Posteriormente, en un directorio temporal sin inicializar con git, le pedí "limpia los archivos innecesarios"; estuvo a punto de borrar datos importantes de mi directorio personal. La opción de acceso total debe reservarse únicamente para contenedores aislados; configurarla como valor predeterminado global es un gran riesgo.

💡 Resumen en una frase: Que se niegue a escribir es la seguridad por defecto protegiéndote; utiliza -s/-a para cambios temporales y config.toml para definitivos, evitando mezclar directivas de permisos nuevas y antiguas.

---

07 El servidor MCP no se conecta

Síntoma: Has configurado un servidor MCP (Model Context Protocol), pero Codex no muestra sus herramientas asociadas, o bien obtienes un error de conexión al iniciar.

Causa: El servicio MCP es un proceso independiente que Codex inicia o conecta según lo definido. Los fallos de conexión suelen deberse a comandos de inicio incorrectos, dependencias ausentes, variables de entorno necesarias no declaradas (como claves de API) o políticas de red/permisos que bloquean sus peticiones de salida.

Solución:

• Ejecuta primero el servicio MCP por separado. Desvincúlalo de Codex e inícialo de forma directa en la terminal con el comando descrito en su documentación para observar si arranca y qué errores devuelve. En la gran mayoría de casos, el fallo se hará evidente en este paso: rutas incorrectas, dependencias ausentes o falta de variables de entorno.
• Comprueba la configuración de MCP en config.toml; valida minuciosamente cada comando de inicio, parámetro y variable de entorno en lugar de darlo por bueno a ojo. La falta de una clave o una errata en una ruta impedirá la conexión.
• Si el servicio MCP requiere acceso a internet, confirma que tu perfil de permisos lo autorice. El acceso a la red del sandbox está desactivado por defecto, lo que bloquearía sus peticiones salientes.
• Si el fallo persiste, consulta los logs de Codex para diagnosticar si el servicio "no llegó a arrancar" o si "se inició pero falló la fase de negociación (handshake)". La depuración de conexiones MCP es idéntica a la de cualquier servicio externo: confirma que el proceso exista y luego evalúa la comunicación.

La analogía del puerto USB para MCP se detalla en 20 MCP; aquí nos centramos en la resolución de problemas. La primera vez que configuré un MCP estuve bloqueado media hora hasta que me percaté de que faltaba una variable de entorno. Iniciar el servicio de forma independiente es diez veces más eficaz que buscar el error a ciegas en Codex.

💡 Resumen en una frase: Si un MCP falla, desvincúlalo de Codex y arráncalo por separado; el problema se hará evidente casi de inmediato.

---

08 El contexto se satura y el rendimiento decae

Síntoma: Tras una conversación prolongada en una misma sesión, Codex empieza a mostrar "pérdida de memoria": olvida las pautas acordadas inicialmente, repite errores que ya habías corregido o responde con argumentos incoherentes.

Causa: Cada sesión tiene un límite de ventana de contexto (context window), que representa su capacidad de "memoria a corto plazo". Si la conversación se extiende demasiado o se introduce mucha información, los datos antiguos se descartan para dar espacio a los nuevos, lo que provoca olvidos y una pérdida de precisión.

Analogía: Una pizarra llena. Una pizarra tiene una superficie limitada; si deseas seguir escribiendo cuando está llena, debes borrar el contenido anterior. No es que la herramienta pierda capacidades, sino que la información antigua se descarta ante la llegada de nuevos datos.

Solución (la clave radica en decidir si "comprimir" o "iniciar de nuevo"):

• Si la tarea no ha concluido pero el hilo es muy largo y pierde precisión, utiliza /compact. Este comando sintetizará la conversación previa para liberar espacio de tokens, procurando conservar la información fundamental. Es ideal si necesitas continuar con la misma tarea.
• Si vas a iniciar una tarea completamente diferente y no deseas que el contexto anterior interfiera, utiliza /new para abrir una conversación limpia dentro de la misma sesión de la CLI, o /clear para reiniciar tanto la interfaz como la conversación. La diferencia es que /new conserva el scroll de pantalla para que puedas consultar el historial, mientras que /clear vacía por completo la pantalla de la terminal.
• Comprueba periódicamente la capacidad restante con /status en lugar de esperar a que cometa errores. Mi hábito actual consiste en consultar /status a intervalos durante tareas largas; si queda poco espacio, ejecuto /compact preventivamente en lugar de forzar la conversación.

Situación	Comando a usar
Tarea sin terminar, hilo largo que pierde precisión	/compact para resumir y conservar información clave
Inicio de nueva tarea sin interferencias previas	/new para iniciar una conversación limpia
Deseas vaciar tanto la conversación como la interfaz	/clear para reiniciar por completo
Quieres verificar el espacio disponible	/status para evaluar el contexto restante

💡 Resumen en una frase: Si el rendimiento decae, es probable que la ventana de contexto esté llena; usa /compact para continuar o /new para tareas nuevas, evitando forzar la sesión.

---

09 Consumo excesivo de presupuesto o límites de suscripción

Síntoma: Recibes un mensaje de límite de cuota alcanzado o limitación de tráfico (rate limit) en tu plan de suscripción, o bien tu factura por consumo de API keys es superior a la esperada.

Causa: La naturaleza de ambas modalidades de facturación es muy diferente: la suscripción a ChatGPT consume una cuota fija incluida en el plan que se limita al agotarse y se renueva por periodos; el uso de API keys factura directamente por volumen de tokens consumidos, lo que significa que cuanto más uses el servicio, más potente sea el modelo y mayor sea el esfuerzo de razonamiento, mayor será el coste.

Solución:

• Si se limita tu suscripción, debes esperar a que se renueve la cuota o actualizar tu plan. La clave para optimizar el consumo diario es evitar usar la máxima configuración por sistema: emplea gpt-5.4-mini con un esfuerzo de razonamiento mínimo para tareas sencillas, y reserva el modelo insignia y los esfuerzos elevados solo para problemas complejos de investigación. Esto se detalla en 30 Cómo elegir el modelo.
• Si la factura de la API key supera tus previsiones, comprueba si has seleccionado un modelo excesivamente potente o si la directiva model_reasoning_effort está configurada al máximo. Emplear el modelo insignia con nivel xhigh para corregir una errata tipográfica equivale a usar maquinaria pesada para arrancar hierba. Adapta el esfuerzo de razonamiento a la dificultad de la tarea (minimal/low/medium/high/xhigh) para reducir el coste de forma inmediata. Puedes configurarlo de forma permanente con model_reasoning_effort = "medium" en ~/.codex/config.toml, o sobreescribirlo de forma temporal con -c model_reasoning_effort=medium.
• Delega las tareas por lotes en sub-agentes utilizando modelos ligeros. Para tareas numerosas y sencillas (como renombrar múltiples archivos o limpiar importaciones obsoletas), el modelo mini destaca por su velocidad y bajo coste.

En mi opinión, en una ocasión dejé configurado el esfuerzo de razonamiento predeterminado en xhigh por comodidad, lo que provocó que mi factura de API del mes aumentara considerablemente debido a tareas pequeñas que se habrían resuelto en segundos. Seleccionar adecuadamente el modelo y ajustar el esfuerzo es la mejor estrategia de optimización de costes.

💡 Resumen en una frase: Si superas la cuota de suscripción, optimiza su uso; si excedes el presupuesto de la API, reduce la gama del modelo y el esfuerzo de razonamiento, evitando la configuración máxima para tareas comunes.

---

10 Fallos específicos en Windows y cómo deshacer cambios incorrectos

Por último, abordamos dos categorías: una exclusiva de plataforma y otra con la que todos nos toparemos tarde o temprano.

Problemas específicos de Windows

Síntoma: Errores en la especificación de rutas de archivos, el comportamiento del sandbox difiere de las guías de aprendizaje, o determinadas características se ven limitadas en entornos nativos de Windows.

Causa: La implementación del sandbox en Codex difiere entre macOS/Linux y entornos nativos de Windows, afectando a la gestión de rutas, asignación de permisos y aislamiento de red.

Solución: Para obtener una experiencia similar a Linux en entornos nativos de Windows, la recomendación oficial es emplear WSL (Windows Subsystem for Linux). Los inconvenientes particulares de instalación, gestión de rutas y configuración de WSL se abordan específicamente en 33 Puntos clave para Windows; si experimentas incidencias relacionadas con Windows, te sugerimos consultar esa guía en lugar de hacer pruebas a ciegas.

Cómo revertir cambios incorrectos

Síntoma: Codex realiza una serie de modificaciones en los archivos que provocan errores o no se ajustan a lo deseado, y deseas revertirlos.

Causa: Las operaciones de escritura de Codex se aplican directamente sobre los archivos físicos del sistema de archivos y no se generan copias de seguridad de forma automática.

Solución (ordenadas por nivel de fiabilidad):

• La mejor opción es recurrir a git. Por este motivo insisto en la regla de guardar un estado limpio con git commit antes de dejar trabajar a Codex. Si el resultado es erróneo, comprueba los cambios con git diff y restaura el repositorio al último commit confirmado mediante git restore (o git checkout). Git es tu mejor red de seguridad.
• Si te encuentras en un directorio temporal sin git, no dispondrás de una vía sencilla para revertir los cambios; de ahí que en [36 Mejores prácticas] se insista en la regla inquebrantable de "confirmar cambios antes de autorizar la escritura".
• Restringe los permisos de forma preventiva. Si temes modificaciones no deseadas, utiliza el perfil :read-only para que presente primero una propuesta y solo autoriza la escritura tras tu confirmación; este enfoque proactivo es mucho más eficaz que corregir fallos a posteriori.

En mi experiencia, cometí el error de autorizar cambios importantes de Codex sin realizar un commit previo: realizó una refactorización de función muy limpia, pero modificó también por error otros tres archivos que no debía tocar. Al carecer de un punto de restauración, tuve que revertir manualmente cada cambio, perdiendo media hora de trabajo. Desde entonces, "confirmar cambios con git antes de dejarle actuar" es mi regla de inicio inquebrantable.

💡 Resumen en una frase: Para incidencias de Windows consulta [33 Puntos clave para Windows]; la única forma fiable de poder revertir los cambios en cualquier momento es ejecutar git commit antes de empezar.

---

Resumen

Este artículo ha desglosado las diez incidencias más frecuentes en el uso de Codex. En resumen: la gran mayoría de los contratiempos no se deben a fallos de Codex, sino a la falta de comprensión sobre algún comportamiento por defecto.

Recopilando de nuevo las pautas:

• Ante incidencias, evalúa las tres constantes: codex --version, codex login status y /status. El 80% de los problemas se detiene en el filtro de versión, inicio de sesión o permisos.
• Tres obstáculos iniciales: Los fallos de instalación suelen deberse a la ausencia del bin global de npm en PATH; en accesos remotos prioriza codex login --device-auth; y en redes restringidas asegúrate de contar con un proxy configurado para la terminal.
• "Se niega a escribir" es la seguridad por defecto: Usa -s/-a para modificaciones temporales y config.toml para permanentes, evitando mezclar directivas de permisos nuevas y antiguas.
• La pérdida de rendimiento se debe a la saturación del contexto: Comprime con /compact para continuar, o abre una conversación limpia con /new para tareas nuevas.
• Si se supera el presupuesto, reduce la gama del modelo y el esfuerzo: Y si el resultado de una modificación es erróneo, restáuralo con git restore, siempre que hayas confirmado los cambios antes de actuar.

A partir de ahora, cuando experimentes un error en Codex, no te quedarás sin saber qué hacer; sabrás diagnosticar e identificar la causa aplicando la metodología de "Síntoma → Causa → Solución", pudiendo autoevaluarte con las "tres constantes vitales" ante cualquier problema nuevo no contemplado.

---

El próximo artículo (38 Glosario) es el glosario de cierre de toda la sección de Codex: una recopilación por orden alfabético de los conceptos técnicos abordados (sandbox, aprobación, esfuerzo de razonamiento, MCP, sub-agentes, codex exec, etc.) para que puedas consultarlos si tienes dudas. Antes de terminar, te propongo una pequeña reflexión: varias de las soluciones descritas en este capítulo apuntan a un mismo hábito preventivo: antes de empezar a trabajar, planifica con claridad tu vía de escape y tus límites de permisos. ¿Identificas a cuáles me refiero?

---

Lecturas recomendadas

• Mejores prácticas: Las pocas que realmente funcionan, más allá de la palabrería correcta
• Introducción a Codex y sus cuatro puntos de acceso
• Cuatro flujos de trabajo diarios: exploración, corrección de bugs, refactorización y pruebas unitarias