failed to start codex app-server: solución según el error exacto

Si la app de escritorio de Codex o la extensión de ChatGPT para Chrome no arranca en Windows, copia el mensaje exacto y búscalo en la tabla: cada uno apunta a una pieza local distinta y tiene un arreglo distinto. Reinstalar, reiniciar o ejecutar como administrador no resuelve ninguno de los cuatro según los usuarios que lo han probado, y borrar la carpeta .codex puede costarte el historial de conversaciones.

Desde el 9 de julio de 2026, Codex forma parte de la app de escritorio de ChatGPT en Windows, así que el diálogo suele decir «ChatGPT failed to start» aunque lo que falla es el app-server de Codex. El paquete instalado sigue llamándose OpenAI.Codex (Microsoft Store 9PLM9XGG6VKS); ChatGPT Classic es otro paquete y no lleva app-server, por lo que reinstalar desde un enlace genérico de ChatGPT puede dejarte con la app equivocada (#32706).

A 9 de octubre de 2026 OpenAI no ha publicado causa raíz ni versión corregida para ninguno de los cuatro, y el registro de cambios no los menciona. Los arreglos de abajo los han comprobado usuarios en GitHub y en el foro de OpenAI; en cada uno se indica si lo confirma una persona o varias.

Antes de tocar archivos: cierra desde la bandeja y copia .codex

Cerrar la ventana no cierra la app: se queda en la bandeja del sistema y deja codex.exe y una decena de procesos con las bases de datos abiertas (#39015). Sal desde el icono de la bandeja (Quit) y comprueba que no queda nada:

Get-Process ChatGPT, codex, node_repl -ErrorAction SilentlyContinue

Si la lista no sale vacía, termínalos con Stop-Process -Force antes de seguir. Después copia la carpeta de datos de Codex:

$stamp = Get-Date -Format yyyyMMdd-HHmmss
Copy-Item "$env:USERPROFILE\.codex" "$env:USERPROFILE\Desktop\codex-copia-$stamp" -Recurse

En %USERPROFILE%\.codex están state_5.sqlite (el índice de conversaciones), sessions\ (el historial local), config.toml, auth.json, las memorias y el estado de los plugins. Reinstalar la app no toca esta carpeta porque vive fuera del paquete MSIX, así que ni la borra ni la repara. Un usuario perdió su historial al borrarla mientras probaba arreglos (#49265), y el soporte de OpenAI en el foro recomienda no borrar .codex sin copia porque guarda configuración, credenciales y sesiones.

Si el historial ocupa decenas de gigas, haz la copia en otro disco. Todo lo que sigue mueve archivos a una carpeta aparte en lugar de borrarlos, para que puedas deshacerlo.

failed to start codex app-server (os error 3): rutas caducadas

El error aparece cuando usas Browser Use, el navegador integrado o el plugin de Chrome: las pestañas se listan, pero tab.goto(), las capturas y el árbol DOM fallan. Lo lanza node_repl, que intenta arrancar codex app-server --listen stdio:// desde una ruta que ya no existe (#20048). «os error 3» es el código de Windows para «no se encuentra la ruta».

La app copia sus ejecutables auxiliares a carpetas por usuario con nombre de hash: %LOCALAPPDATA%\OpenAI\Codex\bin\<hash>\ y %LOCALAPPDATA%\OpenAI\Codex\runtimes\cua_node\<hash>\bin\. Cuando una actualización automática borra la carpeta antigua, las rutas que quedaron anotadas en otros archivos se rompen (#26011). El issue de referencia, #19187, está abierto desde el 23 de abril de 2026 y sigue recibiendo comentarios de «sigue pasando» en septiembre.

Con la app cerrada del todo, localiza primero las carpetas que existen ahora:

Get-ChildItem "$env:LOCALAPPDATA\OpenAI\Codex\bin", "$env:LOCALAPPDATA\OpenAI\Codex\runtimes\cua_node" `
  -Recurse -Include codex.exe, node_repl.exe, node.exe -ErrorAction SilentlyContinue |
  Select-Object FullName, LastWriteTime

Luego mira qué rutas tiene anotadas tu configuración:

Select-String -Path "$env:USERPROFILE\.codex\config.toml" -Pattern 'node_repl|CODEX_CLI_PATH|NODE_REPL_NODE'
[Environment]::GetEnvironmentVariable('CODEX_CLI_PATH', 'User')

Hay que corregir las que apunten a una carpeta que no aparece en la primera lista:

1. Copia config.toml y edita en [mcp_servers.node_repl] la clave command, y en [mcp_servers.node_repl.env] las claves CODEX_CLI_PATH, NODE_REPL_NODE_PATH y NODE_REPL_NODE_MODULE_DIRS si existen. Pon la ruta de la carpeta que contiene de verdad node_repl.exe o codex.exe. Varios usuarios lo resolvieron así (#26011, #28474, #20206).
2. Escribe las rutas entre comillas simples ('C:\Users\...'). Con comillas dobles, las barras invertidas de Windows son secuencias de escape no válidas en TOML y la app puede quedarse colgada al leer el archivo (#37616).
3. Si la variable de usuario CODEX_CLI_PATH apunta a un codex.exe que ya no existe, corrígela o elimínala con [Environment]::SetEnvironmentVariable('CODEX_CLI_PATH', $null, 'User').
4. El archivo chrome-native-hosts-v2.json también guarda una ruta codexCliPath; si está caducada, Browser Use puede mostrar el fallo como un bloqueo de «enterprise network policy» aunque la causa sea el ejecutable que falta (#28474). Se repara igual que en la sección de nodePath.

Sal de la app desde la bandeja y vuelve a abrirla. Funcionó si desaparece el aviso MCP client for node_repl failed to start y Browser Use puede navegar y hacer capturas.

Repararla desde Configuración de Windows, reinstalar, reiniciar, ejecutar como administrador o instalar la CLI por npm no lo arregló a varios usuarios (resumen en #19187). Ninguno de esos pasos reescribe las rutas anotadas.

Si no existe la carpeta %LOCALAPPDATA%\OpenAI\Codex\bin

En las compilaciones de abril y mayo de 2026 los auxiliares a veces solo estaban en la caché virtualizada del paquete. Varios usuarios crearon un enlace de unión hacia ella (#19562):

New-Item -ItemType Junction -Path "$env:LOCALAPPDATA\OpenAI\Codex\bin" `
  -Target "$env:LOCALAPPDATA\Packages\OpenAI.Codex_2p2nqsd0c76g0\LocalCache\Local\OpenAI\Codex\bin"

Hazlo solo si la carpeta no existe. En una máquina virtual limpia el error pasó a ser CreateProcessAsUserW failed: 5 del sandbox (#20661), y un usuario de la versión 26.506 indica que la carpeta ya se crea sola, así que en compilaciones recientes lo normal es la causa anterior.

missing required path nodePath o resourcesPath en la extensión

El panel lateral de la extensión de ChatGPT (Chrome, Edge o Brave) muestra Unable to start ChatGPT y Codex app-server manifest entry is missing required path nodePath, o lo mismo con resourcesPath o codexCliPath. «Missing» no significa que falte el campo, sino que la ruta anotada ya no existe (#35705).

La cadena es esta: la extensión habla con el host nativo com.openai.codexextension, que arranca extension-host.exe desde la caché de plugins de .codex, y ese host lee chrome-native-hosts-v2.json (hay una copia en %LOCALAPPDATA%\OpenAI\Codex\ y otra en %USERPROFILE%\.codex\). Cuando una actualización elimina el runtime cua_node\<hash> antiguo o la carpeta del paquete anterior, el JSON sigue apuntando allí. Volvió a pasar tras las actualizaciones del 3 y el 8 de octubre de 2026 (#32706, #40357), así que puede que tengas que repetir el arreglo después de cada actualización.

Prueba en este orden, de menos a más invasivo:

1. Abre primero la app de escritorio y espera 30–60 s antes de usar la extensión. La extensión solo funciona mientras la app está en marcha; uno o dos usuarios lo confirman (#35705).
2. Haz las comprobaciones de la guía oficial de la extensión: actualiza la app de escritorio (si tienes más de una, como ChatGPT y ChatGPT Beta, actualiza cada una o quita las que no uses), reinicia el navegador, confirma que en Settings > Computer Use tu navegador muestra Manage y no Install, usa el perfil del navegador donde está instalada la extensión, abre un chat nuevo y reinicia la app. Esa guía no menciona el error de nodePath, pero descarta lo sencillo.
3. Pide a Codex en la app de escritorio que se conecte a Chrome («connect to Chrome»). A un usuario le regeneró el estado (#32706).
4. Repara el JSON a mano, que es lo que ha funcionado a más usuarios (#35705). Con la app y el navegador cerrados, haz una copia y mira qué rutas tiene anotadas:

$f = "$env:LOCALAPPDATA\OpenAI\Codex\chrome-native-hosts-v2.json"
Copy-Item $f "$f.copia"
(Get-Content $f -Raw | ConvertFrom-Json).entries.paths |
  Format-List nodePath, nodeModuleDirs, nodeReplPath, resourcesPath, codexCliPath

Y saca las rutas válidas de hoy:

$rt = Get-ChildItem "$env:LOCALAPPDATA\OpenAI\Codex\runtimes\cua_node" -Directory |
  Sort-Object LastWriteTime -Descending | Select-Object -First 1
Join-Path $rt.FullName 'bin\node.exe'          # nodePath
Join-Path $rt.FullName 'bin\node_modules'      # nodeModuleDirs
Join-Path $rt.FullName 'bin\node_repl.exe'     # nodeReplPath
(Get-AppxPackage -Name OpenAI.Codex).InstallLocation + '\app\resources'   # resourcesPath

Sustituye en el JSON cada ruta que no exista (en JSON las barras invertidas van dobles: C:\\Users\\...). Después arranca primero la app de escritorio y luego el navegador. Funcionó si el panel lateral carga sin el mensaje.

Si prefieres no editarlo a mano, el script Repair-CodexChromeManifest.ps1 de CherryDT hace exactamente esos cambios: busca el paquete OpenAI.Codex y el runtime más reciente, guarda una copia con fecha, reescribe las cuatro rutas y comprueba que existen. Admite -WhatIf para ver qué cambiaría sin escribir nada. Es de un tercero, no de OpenAI, y un usuario confirma que le funcionó; léelo antes de ejecutarlo.

Si el JSON ni siquiera existe o el enlace latest de la caché de plugins apunta a una versión borrada, varios usuarios de la 26.930.2377.0 reconstruyeron la caché completa desde app\resources\plugins (#42520). Es un procedimiento avanzado; sigue el hilo tal cual y con copia previa.

initialize handshake timed out: el app-server no responde en 30 s

El app-server es el proceso que da servicio a los clientes de Codex: la app de escritorio lo arranca, le habla por stdio y le envía primero una petición initialize (documentación del app-server). En Windows, la app espera 30 segundos a que conteste; los logs de #39015 muestran durationMs=30012 y cause=initialize_handshake_timeout. Ese plazo no figura en la documentación. Si pasa de ahí, ves «ChatGPT failed to start» con Codex app-server initialize handshake timed out.

No es el mismo error que timed out waiting for cloud config bundle after 15s, que tiene que ver con la configuración administrada del workspace; para ese está la guía Codex no cargó el cloud config bundle en 15 segundos: cómo aislarlo.

Ve de lo que no toca datos a lo que sí:

1. Procesos colgados. Con la app cerrada, termina los procesos que queden y vuelve a abrirla. A un usuario de Windows Server 2025 le pasó más de diez veces y siempre se resolvió así (#32160):

Get-Process *codex*, *chatgpt*, *node_repl* -ErrorAction SilentlyContinue | Stop-Process -Force

1. Mira el log por si el agente corre en WSL. El log de la app está en %LOCALAPPDATA%\Packages\OpenAI.Codex_2p2nqsd0c76g0\LocalCache\Local\Codex\Logs\<año>\<mes>\<día>\codex-desktop-*.log (Qiita). Si ves que lanza el backend con wsl.exe, rutas /mnt/c/... y el aviso state db backfill is running ... waiting up to 30s, el arranque se está comiendo el plazo copiando datos entre sistemas de archivos. En config.toml, sección [desktop], pon runCodexInWindowsSubsystemForLinux = false (#38345; dos usuarios en este hilo de Reddit dicen que esa era su causa). El precio: los chats que dependían de WSL dejan de estar accesibles mientras lo tengas desactivado (#39169). Otra opción, confirmada por un solo usuario, es dejar que el proceso termine (unos 40 s más) y volver a abrir.
2. Aparta la base de logs. logs_2.sqlite solo guarda registros de diagnóstico, no conversaciones ni ajustes (#39015). Si crece o se corrompe, el arranque no llega a tiempo: hay casos con 6,7 GB (#27741) y uno con 2,27 GB corruptos en el que, tras apartarla, el handshake bajó a 1,7 s. Mueve los tres archivos juntos y cierra antes las extensiones de Codex del IDE:

$codex = "$env:USERPROFILE\.codex"
$hold = "$codex\logs-apartados-$(Get-Date -Format yyyyMMdd-HHmmss)"
New-Item -ItemType Directory -Path $hold | Out-Null
Move-Item "$codex\logs_2.sqlite*" $hold

La app crea una base nueva al arrancar. No muevas state_5.sqlite en este paso: es el índice de conversaciones. Un empleado de OpenAI explicó en #23917 que las compilaciones nuevas detectan la corrupción y que están trabajando en que la base se repare sola, pero no hay versión anunciada.

1. Historial de sesiones muy grande. Si nada de lo anterior funciona, mide el historial:

Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -File | Measure-Object Length -Sum

Un usuario tenía 64 archivos de sesión con 22,24 GB en total; apartar logs_2.sqlite no le sirvió, y lo que funcionó fue mover (no borrar) sessions, archived_sessions y state_5.sqlite* a una carpeta en otro disco, con la app cerrada y una copia completa hecha antes (Reddit). Mientras esos archivos estén fuera, la app no verá esas conversaciones; están en la carpeta de espera y puedes devolverlos.

Un usuario más resolvió el handshake cambiando de nodo en su proxy (#29040); si usas uno, pruébalo antes del paso 4.

0xC000001D (code=3221225501): Astrill o una instrucción de CPU

3221225501 es 0xC000001D, STATUS_ILLEGAL_INSTRUCTION: el proceso codex.exe ejecutó una instrucción que el procesador no acepta y Windows lo cerró. En pantalla aparece como ChatGPT failed to start. (code=3221225501, signal=null). Most recent error: Codex app-server websocket closed (code=3221225501) o, al iniciar sesión, como Codex app-server process is not available (#24408, #42029). Ninguno de esos issues tiene respuesta de OpenAI.

Lo primero es saber quién provoca la instrucción. Abre el Visor de eventos, ve a Registros de Windows > Aplicación y busca el evento «Application Error» de la hora del fallo. Fíjate en el nombre del módulo con errores (Faulting module name).

Si el módulo es ASProxy64.dll, la culpable es Astrill VPN: instala un proveedor Winsock (LSP) que se inyecta en codex.exe. Es la causa con más pruebas, en equipos con procesadores modernos como Core Ultra, Ryzen Zen 5 o i7-14700KF (#30884). Varios usuarios lo resolvieron con una de estas vías:

• En Astrill, mantén pulsado Ctrl mientras abres el menú, ve a Help > LSP Uninstall y reinicia.
• O, en un terminal como administrador, comprueba con netsh winsock show catalog | findstr ASProxy que está, ejecuta netsh winsock reset y reinicia. Ten en cuenta que este comando restablece todos los proveedores Winsock, no solo el de Astrill.
• O desinstala Astrill. Con los protocolos OpenWeb o WireGuard no se instala el LSP.

Funcionó si tasklist /m ASProxy64.dll responde que no hay tareas y la app arranca. Un usuario que estaba atrapado en un bucle de «hit a snag» al iniciar sesión lo resolvió también quitando Astrill (#45597). Si usas otra VPN o software que inyecta DLL, no hay casos documentados, pero el Visor de eventos te dirá si el módulo es suyo.

Si el módulo es el propio codex.exe y tu procesador es antiguo, el problema está en la compilación. La CLI de npm 0.135.0 fallaba así en un Xeon Haswell y OpenAI dijo que se arreglaría en la siguiente versión (#25367), pero eso era solo para la CLI. En la extensión de VS Code, #17410 sigue abierto con HW capability requested: 0x200000 en Zen 3 y Raptor Lake, y quienes lo sufren usan la versión Linux dentro de WSL2. OpenAI no ha publicado qué instrucción exige la app de escritorio actual. En este caso no hay arreglo local: reúne los datos de la última sección y repórtalo.

Para la app de escritorio con 0xC000001D, a varios usuarios no les sirvió reinstalar, volver a registrar el paquete, instalar los redistribuibles de Visual C++, borrar las bases SQLite ni empezar con un .codex vacío (#30339, #30884).

Hay dos códigos cercanos que sí tienen arreglo local. 3221225781 (0xC0000135) es una DLL que no se encuentra: a un usuario le faltaba vcruntime140_1.dll y lo resolvió instalando el último Visual C++ Redistributable (foro). Si el error dice HW capability requested: 0x20000000, revisa si tienes una variable de entorno global OPENSSL_ia32cap; quitarla o ajustarla lo resolvió a varios usuarios (#12962), aunque afecta a todos los programas que usan OpenSSL.

Errores vecinos: program not found, hit a snag, 0xC0000022 y más

Estos mensajes no son ninguno de los cuatro anteriores, aunque es fácil confundirlos con ellos. Si el tuyo está aquí, empieza por la columna de la derecha:

Si la app arranca y lo que falla es la conexión durante una sesión, eso es otro problema: Codex se queda en Reconnecting: cómo recuperar la tarea sin borrar sesiones. Si el bloqueo es un certificado del proxy corporativo, consulta Solucionar self signed certificate in certificate chain en Codex.

Qué no hacer: borrar .codex, Restablecer o ejecutar como administrador

• Borrar %USERPROFILE%\.codex. Pierdes el historial local y la configuración, y en los casos de 0xC000001D no arregló nada (#30884). Si una guía te lo pide, mueve la carpeta en lugar de borrarla.
• Restablecer la app desde Configuración de Windows. A un usuario le borró las tareas locales de Codex y cierra la sesión (foro). Reparar es la variante menos agresiva, aunque tampoco corrige las rutas caducadas.
• Ejecutar como administrador para ver si así arranca. La documentación de Windows indica que el agente de Codex hereda ese nivel de permisos, así que todos sus comandos se ejecutarían elevados. Y para estos errores no sirve.
• Descargar parches de los issues. En los hilos circulan un .zip con un supuesto parche que otro usuario identificó como ransomware, un parche que hace pasar el control de sitios permitidos del navegador y herramientas de «recuperación» no oficiales. Ninguno es de OpenAI. El soporte de OpenAI también pide no desactivar las protecciones de seguridad de Windows como apaño (foro).

Si nada funciona: qué enviar a OpenAI y en qué issue

Cuando ninguna rama encaja, o eres del caso de CPU, reúne esto antes de escribir:

• Versión de la app: (Get-AppxPackage -Name OpenAI.Codex).Version.
• Versión de Windows (winver).
• El evento «Application Error» del Visor de eventos con el módulo que falla.
• El log del día en %LOCALAPPDATA%\Packages\OpenAI.Codex_2p2nqsd0c76g0\LocalCache\Local\Codex\Logs\; en compilaciones antiguas, %LOCALAPPDATA%\Codex\Logs. El soporte de OpenAI advierte que los logs pueden contener datos personales (foro): revísalos antes de pegarlos en un issue público.

Si la app llega a abrir, ejecuta /feedback en un chat y guarda el ID del chat, como indica la guía de la extensión. Para no abrir un duplicado, añade tus datos al issue que corresponde: #19187 para os error 3, #35705 para nodePath/resourcesPath, #39015 o #27741 para el handshake y #24408 para 0xC000001D.

Preguntas frecuentes sobre el app-server de Codex en Windows

¿Reinstalar la app de Codex borra mis conversaciones?

No. Las conversaciones y la configuración están en %USERPROFILE%\.codex, fuera del paquete, y desinstalar no las toca (#39015). Por eso mismo reinstalar tampoco corrige rutas caducadas en config.toml ni una base de logs dañada. Lo que sí puede perderse es lo que guarda el propio paquete: Restablecer borró tareas locales a un usuario.

¿Ya hay una versión de Codex que arregle failed to start codex app-server?

A 9 de octubre de 2026, no. Ninguno de los issues de os error 3, nodePath/resourcesPath, handshake timed out o 0xC000001D tiene versión corregida anunciada, y el error de nodePath reapareció tras las actualizaciones del 3 y el 8 de octubre. Actualizar sigue valiendo la pena por otros fallos de arranque, como el del logo infinito.

¿El error de la extensión de Chrome se arregla reinstalando la extensión?

Normalmente no, porque la ruta rota está en chrome-native-hosts-v2.json, que pertenece a la app de escritorio. Abre primero la app, espera a que termine de cargar y, si el panel sigue mostrando missing required path nodePath, repara el JSON como se explica arriba.