Hoja de referencia de comandos y configuración
📚 Navegación de la serie: El artículo anterior (34 Práctica integrada) te llevó a conectar todas las partes anteriores en un proyecto completo, lo cual fue la "unión". Este artículo hace lo contrario: extrae todos los comandos, banderas y claves de configuración dispersos en más de treinta capítulos y los comprime en una hoja de referencia que puedes pegar al lado de tu monitor. El siguiente artículo (36 Mejores prácticas) cerrará toda la sección de Codex centrándose en "cómo usarlo correctamente".
A decir verdad, es algo vergonzoso.
Durante los primeros dos meses usando Codex, tenía en mi computadora un archivo llamado codex-memo.txt donde anotaba de manera desordenada cosas como "exportar JSON es --json" o "escribir el último mensaje en un archivo es -o". El problema era que tomaba notas sin orden; cada vez que quería usar codex exec para guardar el resultado en un archivo, primero buscaba en este txt. Si no lo encontraba, buscaba en el historial del shell con history | grep codex, y si tampoco, abría el navegador para buscar en la documentación oficial. Algo que debía ser un solo comando me costaba cinco minutos.
Lo más tonto fue la configuración. Una vez quise desactivar temporalmente la red del sandbox para cierto proyecto. Recordaba que había una clave que empezaba con sandbox_workspace_write, pero olvidé por completo qué seguía después, ¿network? ¿net_access? Estuve adivinando en config.toml hasta que Codex arrojó un error al iniciar. Al final, tuve que revisar config-reference para enterarme de que era sandbox_workspace_write.network_access. En ese momento decidí: en lugar de buscarlo cada vez, es mejor extraer todos los comandos y configuraciones frecuentes en una tabla para poder consultarlos de un vistazo.
Este artículo es el resultado de esa tabla. No explica la teoría (que ya se cubrió anteriormente), solo hace una cosa: permitirte buscar rápido, copiar con precisión y no tener que abrir el navegador.
Al terminar este artículo, obtendrás:
- Una hoja de referencia que cubre la instalación, inicio de sesión, comandos y banderas de CLI, comandos de barra diagonal y elementos de configuración frecuentes en
config.toml. - Una tabla de correspondencias para los niveles de sandbox de permisos, modelos y esfuerzo de razonamiento, para configurarlo sin cometer errores.
- Una lista de "puntos de entrada clave" para capacidades avanzadas como MCP (Model Context Protocol), sub-agentes y Skills, para saber desde qué comando acceder a ellas.
- Un pequeño ejemplo funcional para validar y confirmar que los comandos que consultas realmente funcionan en tu entorno local.
⚠️ Los comandos, banderas y claves de configuración se basan en la documentación oficial y pueden cambiar con las versiones; los nombres de los modelos y los valores por defecto varían según la versión y tu cuenta, y siempre se regirán por el comportamiento real de tu
codex --helpyconfig.tomllocal; confirma la versión actual mediantecodex --version. Los elementos marcados como "experimental" a continuación tendrán una nota al inicio, ten cuidado al usarlos.
01 Instalación e inicio de sesión
Ya sea para la primera instalación, cambiar de máquina o iniciar de nuevo en un entorno de CI, estos son los comandos más utilizados. Analogía: Este es el "combo de encendido" de Codex: instalarlo, iniciar sesión y confirmar que se inició correctamente; si falta un paso, no funcionará.
Bajo ciertas restricciones de red locales, los scripts de instalación y el inicio de sesión mediante OAuth pueden requerir un proxy o VPN, de lo contrario es fácil quedarse atascado en el paso de descarga o de redirección.
| Propósito | Comando | Plataforma / Notas |
|---|---|---|
| Instalación estándar (script) | curl -fsSL https://chatgpt.com/codex/install.sh | sh | macOS / Linux |
| Instalación estándar (script) | powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" | Windows |
| Instalar con npm | npm install -g @openai/codex | Multiplataforma, requiere Node |
| Instalar con Homebrew | brew install --cask codex | macOS |
| Actualizar a la última versión | codex update | Disponible si la distribución soporta autoactualización |
| Iniciar sesión (OAuth del navegador) | codex login | Método predeterminado, abre el navegador para iniciar sesión en ChatGPT |
| Iniciar sesión (código de dispositivo) | codex login --device-auth | Úsalo cuando no puedas abrir un navegador (como en servidores remotos) |
| Iniciar sesión con API Key | printenv OPENAI_API_KEY | codex login --with-api-key | Lee la clave desde la entrada estándar (stdin) |
| Verificar estado de inicio de sesión | codex login status | El código de salida es 0 si ya inició sesión, ideal para scripts |
| Cerrar sesión | codex logout | Limpia las credenciales locales |
| Diagnóstico del sistema | codex doctor | Ejecútalo tras la instalación o ante problemas; autoevalúa la instalación, configuración, autenticación, Git, etc. |
💡 Resumen en una frase: Después de instalar, ejecuta primero
codex doctorpara un diagnóstico, luego usacodex login statuspara confirmar el estado de la sesión; esto te evitará la mitad de los desvíos comparado con empezar a ciegas.
02 Comandos y banderas frecuentes de la CLI de codex
Esta es la parte más central de todo el artículo. Analogía: codex es el programa principal, seguido del "subcomando" (a dónde ir) y luego el --xxx que es la "bandera" (cómo ir). Primero memoriza los subcomandos, luego las banderas, y al combinarlos obtendrás un comando completo.
Subcomandos comunes
| Subcomando | Qué hace | Madurez |
|---|---|---|
codex | Inicia la interfaz de usuario en terminal interactiva (TUI, Terminal User Interface), se ejecuta por defecto sin subcomandos | Estable |
codex exec | Ejecución única no interactiva, sale al terminar; abreviado como codex e | Estable |
codex resume | Continúa conversando desde la última sesión interactiva | Estable |
codex fork | "Bifurca" una sesión en un nuevo hilo, dejando intacto el registro original | Estable |
codex apply | Aplica en local los diffs generados por tareas en la nube; abreviado como codex a | Estable |
codex mcp | Administra servidores MCP (list / add / remove / login) | Experimental |
codex features | Enumera los interruptores de características y los habilita/deshabilita de forma persistente | Estable |
codex completion | Genera scripts de autocompletado para el shell | Estable |
Banderas globales de alta frecuencia (siguen a codex o a la mayoría de subcomandos)
| Bandera | Efecto | Valores / Notas |
|---|---|---|
--model / -m | Cambia temporalmente de modelo | P. ej., -m gpt-5.5 |
--image / -i | Adjunta imágenes a la primera instrucción | Separa múltiples imágenes con comas o repite -i |
--cd / -C | Especifica el directorio de trabajo antes de comenzar | Requiere una ruta |
--sandbox / -s | Selecciona el nivel del sandbox | read-only / workspace-write / danger-full-access |
--ask-for-approval / -a | Selecciona el momento de la aprobación | untrusted / on-request / never |
--search | Activa la búsqueda web en tiempo real | Cambia web_search a live (el valor predeterminado es cached) |
--add-dir | Otorga permisos de escritura adicionales a un directorio | Repetible, más seguro que otorgar acceso total al disco |
--profile / -p | Aplica un perfil (profile) de configuración | Se superpone a la configuración base |
--config / -c | Modifica temporalmente la configuración desde la línea de comandos | -c key=value, se analiza como TOML si es posible |
--yolo | Omite todas las aprobaciones y sandboxes | Peligroso, úsalo únicamente en entornos aislados |
Banderas exclusivas de alta frecuencia para codex exec (no interactivo)
Este es el conjunto más común para escribir scripts y ejecutar en CI. Analogía: El modo interactivo es como pedir comida en un restaurante, mientras que codex exec es como pedir a domicilio: haces el pedido y te vas, y el resultado se entrega en el lugar que especifiques.
| Bandera | Efecto |
|---|---|
PROMPT con - | Lee las instrucciones de la entrada estándar (stdin) (p. ej., cat prompt.txt | codex exec -) |
--json | Genera un flujo de eventos JSON por líneas (JSONL), útil para analizar con jq |
--output-last-message / -o | Escribe la respuesta final en un archivo (además de imprimirla en stdout) |
--output-schema | Proporciona un JSON Schema para forzar que la salida final cumpla con esa estructura |
--skip-git-repo-check | Permite la ejecución en directorios que no sean repositorios de Git |
--ephemeral | No guarda registros de sesión en el disco |
--full-auto | Bandera de compatibilidad obsoleta que genera una advertencia; los nuevos scripts deben cambiarse a --sandbox workspace-write |
codex exec resume --last | Continúa desde la sesión de exec más reciente |
💡 Resumen en una frase:
-mcambia de modelo,-sajusta el sandbox,-aregula la aprobación y-o/--jsonrecibe los resultados; memoriza estas cuatro acciones y tendrás cubierto el 80% de los casos de la línea de comandos.
03 Comandos de barra diagonal (introducidos en la TUI)
Los comandos de barra diagonal solo se usan en la interfaz interactiva. Una vez dentro de la interfaz a pantalla completa de codex, escribe / para abrir el menú. Analogía: Son "botones de acceso rápido" dentro de la sesión; no necesitas salir para ingresar comandos, solo escribe una barra diagonal para cambiar de configuración en el acto.
A continuación se muestran los que yo mismo uso con más frecuencia. La lista completa dependerá del menú que se despliegue con / en tu entorno local, ya que varía de una versión a otra.
| Comando de barra diagonal | Qué hace |
|---|---|
/model | Cambia el modelo actual (y ajusta el esfuerzo de razonamiento si está disponible) |
/status | Muestra el modelo actual, la política de aprobación, los directorios de escritura y el contexto restante |
/compact | Comprime las conversaciones largas en un resumen para liberar espacio en el contexto |
/diff | Muestra el diff de Git, incluyendo archivos nuevos no rastreados |
/permissions | Ajusta a mitad de camino las acciones que Codex puede realizar sin preguntar |
/review | Solicita a Codex que revise los cambios en tu espacio de trabajo actual |
/init | Genera una estructura inicial (scaffolding) de AGENTS.md en el directorio actual |
/mcp | Muestra las herramientas MCP disponibles en la sesión actual (añade verbose para ver detalles) |
/skills | Explora y selecciona skills locales |
/agent | Alterna entre los hilos de sub-agentes derivados |
/fast | Activa/desactiva la capa de servicio Fast del modelo actual (/fast on/off/status) |
/new | Inicia una conversación completamente nueva dentro de la misma sesión de CLI |
/clear | Limpia la pantalla e inicia una nueva conversación |
/quit o /exit | Sale de la CLI |
Un recordatorio: /fast está impulsado por el "catálogo de modelos". Si el modelo actual no proporciona una capa Fast, /fast no aparecerá en el menú en absoluto, no pienses que es un bug.
💡 Resumen en una frase: Los cuatro más comunes en una sesión son:
/modelpara cambiar de modelo,/statuspara ver el estado,/compactpara liberar espacio y/diffpara verificar resultados; practica estos cuatro hasta convertirlos en memoria muscular.
04 Configuración común en config.toml
El archivo de configuración se encuentra en ~/.codex/config.toml (formato TOML) y representa la "memoria a largo plazo" de Codex. Analogía: Las banderas de la línea de comandos son "cómo viajar esta vez", mientras que config.toml es "cómo viajar siempre por defecto". También puedes colocar un archivo .codex/config.toml en el proyecto para realizar una sobreescritura a nivel de proyecto (debes confiar primero en dicho proyecto).
A continuación solo se enumeran los elementos de alta frecuencia; para ver la lista completa, consulta la referencia oficial de configuración.
| Clave de configuración | Efecto | Ejemplo de valor |
|---|---|---|
model | Modelo predeterminado | "gpt-5.5" |
model_reasoning_effort | Esfuerzo de razonamiento | minimal / low / medium / high / xhigh |
model_reasoning_summary | Detalle del resumen de razonamiento | auto / concise / detailed / none |
service_tier | Nivel de servicio | flex / fast (relacionado con el rendimiento, usado con /fast) |
sandbox_mode | Nivel del sandbox | read-only / workspace-write / danger-full-access |
sandbox_workspace_write.network_access | Indica si se permite el acceso a la red en el modo de escritura del espacio de trabajo | true / false |
sandbox_workspace_write.writable_roots | Directorios con permisos de escritura adicionales | ["/path/a", "/path/b"] |
approval_policy | Política de aprobación | untrusted / on-request / never |
web_search | Modo de búsqueda en la web | disabled / cached / live (predeterminado cached) |
review_model | Modelo utilizado por /review | Si se deja vacío, se usa el modelo de la sesión actual |
model_instructions_file | Reemplaza las instrucciones integradas con un archivo determinado | Una ruta de archivo |
Un archivo config.toml mínimo y utilizable se ve así, puedes copiarlo y modificarlo según tus necesidades:
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
[sandbox_workspace_write]
network_access = false💡 Resumen en una frase: Definir las cuatro claves
model,model_reasoning_effort,sandbox_modeyapproval_policyenconfig.tomlequivale a darle a Codex una "personalidad predeterminada", y lo demás se puede anular con banderas temporales.
05 Permisos y niveles del sandbox
El sandbox determina hasta qué punto Codex puede alterar tu máquina, y la aprobación determina si te pregunta antes de actuar. Ambos trabajan en conjunto. Analogía: El sandbox es "en qué habitaciones puede entrar el becario", y la aprobación es "si debe llamarte antes de hacer algo".
Nivel del sandbox (--sandbox / sandbox_mode) | Qué puede hacer | Escenario recomendado |
|---|---|---|
read-only | Solo lectura, no puede modificar archivos | Para que analice primero y observe sin alterar el código |
workspace-write | Puede modificar archivos dentro del espacio de trabajo | El punto de equilibrio ideal para el desarrollo local diario |
danger-full-access | Lectura y escritura completas en todo el disco, red libre | Úsalo solo en contenedores aislados o ejecutores de CI |
Momento de la aprobación (--ask-for-approval / approval_policy) | Significado |
|---|---|
untrusted | Solo permite comandos que considera de confianza, pregunta por los demás |
on-request | El valor recomendado para ejecución interactiva, te consulta solo cuando es necesario |
never | Nunca pregunta, útil para ejecuciones no interactivas o en CI |
La combinación recomendada oficialmente para trabajar localmente con mínima fricción es la siguiente:
codex --sandbox workspace-write --ask-for-approval on-requestUn par de notas sobre errores que cometí en el pasado: si deseas darle a Codex un directorio de escritura adicional, no elijas la opción fácil de usar danger-full-access; en su lugar, utiliza --add-dir para otorgar acceso preciso solo a ese directorio. --full-auto es una sintaxis de compatibilidad antigua que ya está obsoleta; los nuevos scripts deben cambiarse a --sandbox workspace-write.
💡 Resumen en una frase: Usa por defecto en local
workspace-write+on-request, y en CIsandbox específico+never. Si necesitas dar más permisos, piensa primero si puedes usar--add-diren lugar de abrir el acceso total.
06 Correspondencia de modelos y esfuerzo de razonamiento
Elegir el modelo es decidir "a quién enviar", y ajustar el esfuerzo de razonamiento es "cuánto tiempo dejarle pensar antes de actuar". Son dos controles independientes. Analogía: El modelo es la persona que contratas y el esfuerzo de razonamiento es el tiempo que le das para pensar. No pongas a un experto a reflexionar sobre una tarea sencilla, ni dejes que un novato resuelva a la carrera un problema complejo.
| Modelo | Posicionamiento | Cuándo usarlo |
|---|---|---|
gpt-5.5 | Insignia, el más potente | Programación compleja, refactorización y tareas difíciles de investigación |
gpt-5.4-mini | Ligero, rápido y económico | Tareas secundarias, tareas por lotes y sub-agentes |
gpt-5.3-codex-spark | Vista previa de investigación instantánea (solo ChatGPT Pro) | Para iteraciones en tiempo real con respuestas casi instantáneas |
gpt-5.2 y gpt-5.3-codex están obsoletos, no los incluyas en tu configuración ni en --model.
El esfuerzo de razonamiento se controla mediante model_reasoning_effort, con ese nivel de cinco opciones:
| Valor | Nivel de reflexión | Escenario típico |
|---|---|---|
minimal | Casi nulo, el más rápido | Corrección de erratas (typos), renombrados o ejecutar un comando sencillo |
low | Reflexión ligera | Ajustes menores |
medium | Punto de equilibrio predeterminado | La gran mayoría de la programación diaria |
high | Profundo | Modificación de múltiples archivos o dilemas de diseño |
xhigh | Máximo (depende del modelo) | Problemas realmente difíciles en los que vale la pena esperar |
Mi configuración predeterminada es usar gpt-5.5 + medium, y solo subo manualmente a high cuando estoy seguro de que voy a resolver un problema difícil. En el artículo 30 mencioné la tontería que hacía: dejarlo fijo en xhigh a largo plazo y esperar un minuto solo para corregir un error tipográfico. El tiempo que te ahorras al evitar esa "ansiedad del máximo rendimiento" es mucho mayor de lo que crees.
💡 Resumen en una frase: En el día a día usa "modelo insignia +
medium", reduce aminimal/lowpara tareas mecánicas, y sube ahigh/xhighsolo para problemas difíciles. No toques ningún modelo obsoleto.
07 Puntos de entrada clave para MCP / Sub-agentes / Skills
Estas tres son capacidades avanzadas, y sus principios se explican en sus respectivos capítulos anteriores (capítulos 20, 21 y 22). Aquí solo te proporcionamos el acceso de "desde qué comando/configuración entrar", para que no tengas que volver a buscarlos. Analogía: Esta es la "ubicación del picaporte" de tres puertas; recuerda dónde está el picaporte y revisa el capítulo específico para los detalles al cruzar la puerta.
| Capacidad | Punto de entrada clave | Descripción |
|---|---|---|
| MCP (herramientas externas, como un puerto USB) | codex mcp list / codex mcp add <name> ... | Administra servidores desde la línea de comandos; usa /mcp en la sesión para ver herramientas disponibles (experimental) |
| MCP (inicio de sesión en servidor HTTP) | codex mcp login <name> | Servidor HTTP streamable que solo soporta OAuth |
| Configurar servidores MCP | [mcp_servers.<id>] en config.toml | Define un servidor utilizando claves como command, args, url, etc. |
| Sub-agentes (trabajo en paralelo) | [agents] / agents.<name>.* en config.toml | max_threads tiene un valor predeterminado de 6; alterna hilos usando /agent en la sesión |
| Skills (habilidades específicas para tareas) | /skills en la sesión | Explora y selecciona; utiliza [[skills.config]] (con path y enabled) en config.toml para sobreescribir la habilitación |
Ten en cuenta que el grupo de comandos codex mcp está marcado actualmente como "experimental", por lo que sus subcomandos y comportamiento podrían cambiar según la versión; consulta codex mcp --help antes de usarlos.
💡 Resumen en una frase: MCP se maneja con el comando
codex mcp, los sub-agentes con la configuración[agents]+ el cambio mediante/agent, y las Skills se seleccionan con/skills. Recordar estos tres puntos de entrada evitará que te sientas perdido sobre "por dónde empezar" con las capacidades avanzadas.
08 Práctica: Verifica que los comandos que buscas realmente funcionan
Por muy completa que sea una hoja de referencia, no hay nada como ejecutar un comando tú mismo para confirmar que funciona en tu entorno local. Aquí tienes un ejemplo mínimo de tres pasos que no depende de ningún proyecto existente.
Paso 1: Confirma el estado del inicio de sesión (consulta pura, sin modificar nada):
codex login statusSalida esperada: Si ya has iniciado sesión, se imprimirá el método de autenticación actual y el código de salida será 0; si no has iniciado sesión, se te pedirá que ejecutes codex login.
Paso 2: Ejecuta un comando no interactivo para guardar el resultado en un archivo, lo que te permitirá verificar tres cosas a la vez: codex exec, -o y el sandbox de solo lectura:
codex exec --sandbox read-only -o /tmp/codex-check.txt "用一句话说明当前目录是不是一个 Git 仓库"Resultado esperado: La terminal imprimirá esa frase y también se escribirá la misma frase en /tmp/codex-check.txt (reemplázalo por tu directorio temporal en Windows). Si puedes ver el contenido al abrir el archivo, significa que -o ha funcionado.
Paso 3: Confirma que no te has equivocado con el nombre de la bandera; pregúntale directamente a la propia CLI:
codex exec --helpResultado esperado: Se listarán todas las banderas soportadas por codex exec. Siempre que no estés seguro de si una bandera existe o cómo se llama, --help será siempre la fuente más actualizada y precisa, superando a esta tabla.
💡 Resumen en una frase:
login statuscomprueba el inicio de sesión,codex exec -ocomprueba que el comando realmente trabaja, y--helpvalida que el nombre de la bandera es correcto; si completas estos tres pasos, significa que la hoja de referencia está "viva" para tu entorno local.
Resumen
Este capítulo no introdujo nuevos conceptos, sino que condensó la "experiencia práctica" de los treinta capítulos anteriores en siete tablas:
- Combo de encendido: Instalación,
codex login, confirmación concodex login statusy, ante cualquier problema, ejecuta primerocodex doctor. - Comandos y banderas de CLI: Los subcomandos indican "a dónde ir" y las banderas "cómo ir"; el quinteto más común es
-m,-s,-a,-oy--json. - Comandos de barra: Convierte
/model,/status,/compacty/diffdentro de la sesión en memoria muscular. config.toml: Configuramodel,model_reasoning_effort,sandbox_modeyapproval_policypara establecer la personalidad predeterminada.- Sandbox de permisos: En local usa
workspace-write+on-request, en CI usasandbox específico+never; prioriza--add-dirpara otorgar accesos específicos. - Modelos y esfuerzo: Domina el trabajo con el modelo insignia
gpt-5.5+mediumy no uses ningún modelo obsoleto. - Puntos de entrada avanzados: MCP se gestiona con
codex mcp, los sub-agentes con[agents]y las Skills con/skills.
Ahora deberías ser capaz de: Desechar ese archivo de texto desordenado; cuando necesites un comando, clave de configuración o nivel de sandbox, solo dale un vistazo a esta página. Si tienes dudas, recurre a --help en lugar de abrir el navegador para buscar la documentación.
El próximo artículo (36 Mejores prácticas) es el cierre de toda la sección de Codex. La hoja de referencia resuelve el problema de "no recordar", mientras que las mejores prácticas resuelven el "cómo usarlo correctamente". Con el mismo comando codex exec, algunos logran crear un flujo de automatización perfecto, mientras que otros terminan desorganizando su repositorio de código. Una pequeña reflexión: De los comandos que tienes a mano, ¿cuáles usas a diario sin haberte planteado si existe una forma más estable de implementarlos? En el próximo capítulo desglosaremos uno a uno esos puntos que usamos diariamente pero que no hemos analizado a fondo.