14. Solución de problemas comunes

Objetivo del tema

Resolver incidentes habituales al usar Codex CLI: conflictos de permisos, fallas de conexión o rate limit, reinicio de sesiones y procesos de reinstalación.

14.1 Panorama de incidentes frecuentes

La versión reciente del CLI mejora la diagnóstica automática, pero algunos problemas siguen requiriendo intervención manual. Agrupamos los casos más comunes:

Permisos / sandbox

La acción solicitada requiere escalada (acceso fuera del workspace, red, archivos protegidos).

Conexión / rate limit

El CLI no puede comunicarse con los servidores de OpenAI o se alcanzó la cuota disponible.

Sesiones y entorno

Conversaciones que no responden, archivos temporales corruptos o instalaciones desactualizadas.

14.2 Fallas de permisos y sandbox

Cuando Codex necesita permisos adicionales, verás un mensaje en la TUI o en codex exec indicando que la acción fue bloqueada.

Diagnóstico de permisos
Síntoma Posible causa Solución
“Permission denied” al editar archivos Archivo fuera del workspace o modo lectora activado Verificar /status, ajustar con /approvals o iniciar con --sandbox workspace-write
“Network blocked by sandbox” Sesiones por defecto bloquean red en workspace-write En perfiles de confianza activa [sandbox_workspace_write].network_access = true en config.toml
“Escalation required” reiterado Proceso intenta salir del directorio o ejecutar comandos sensibles Confirma la acción con aprobaciones o ajusta el plan para evitar esa ruta

Si ejecutas Codex en modo no interactivo y necesitas permisos extendidos, agrega --sandbox danger-full-access con precaución o ejecuta la tarea manualmente.

14.3 Errores de conexión o rate limit

Los mensajes típicos incluyen “Failed to reach Codex service”, “usage limit reached” o errores HTTP (401, 429, 503).

  • 401/403: revisa la autenticación. Inicia sesión nuevamente con codex y selecciona “Sign in with ChatGPT” o configura correctamente CODEX_API_KEY.
  • 429 (rate limit): espera a que se restablezca la cuota (ver tema13) o usa un modelo alternativo con --model.
  • 503 / timeouts: verifica el estatus de status.openai.com y reintenta.
  • Sessión bloqueada: usa codex resume --last para retomar; si falla, inicia con codex --reset para limpiar la sesión activa.
Diagnóstico: ejecuta codex exec --json --output-last-message report.json "ping codex" para obtener un log JSON del intento fallido. El archivo resultante puede compartirse con soporte.

14.4 Reiniciar una sesión y verificar estado

Codex ofrece comandos dedicados para restablecer hilos sin perder historial.

# Ver las sesiones activas
codex resume

# Retomar la última sesión
codex resume --last

# Reiniciar completamente la sesión actual
codex --reset

# Comprobar sandbox, aprobaciones y rutas
codex --status  # equivalente al comando /status dentro de la TUI

Si la interfaz se queda congelada, cierra el proceso (Ctrl+C) y vuelve a abrirlo con el mismo comando. Codex recuperará el hilo desde el punto guardado.

14.5 Reinstalación o limpieza del entorno

En casos donde la instalación se corrompe o quieras empezar desde cero:

Procedimiento sugerido

  1. Desinstala la versión actual:
    npm uninstall -g @openai/codex  # si lo instalaste con npm
    brew uninstall codex             # si usaste Homebrew
  2. Borra la carpeta de configuración si necesitas un reset total (opcional):
    rm -rf ~/.codex

    Antes de hacerlo, respalda AGENTS.md, prompts o perfiles de config.toml.

  3. Reinstala la versión más reciente:
    npm install -g @openai/codex
    # o
    brew install codex
  4. Abre Codex nuevamente y configura el inicio de sesión.

Para instalaciones manuales desde binarios, descarga la versión actual en GitHub Releases y reemplaza el ejecutable.

14.6 Consejos adicionales

  • Guarda logs de errores en archivos de texto para compartir con soporte o tu equipo.
  • Revisa los permisos del sistema (antivirus, firewall, WSL) si el CLI no puede leer/escribir archivos.
  • En Windows, considera usar WSL2 cuando encuentres incompatibilidades de sandbox.
  • Consulta el foro o issues del repositorio openai/codex para ver reportes similares.

14.7 Conclusión

Anticipar y resolver problemas con Codex CLI requiere conocer las herramientas de diagnóstico del propio agente y mantener una instalación limpia. Con estos procedimientos puedes restablecer sesiones, ajustar permisos y reenfocar tu trabajo rápidamente.