Modo no interactivo

El modo no interactivo te permite ejecutar Codex desde scripts, por ejemplo, en trabajos de integración continua (CI), sin abrir la interfaz de terminal interactiva (TUI). Para usarlo, ejecuta codex exec.

Para conocer los detalles de cada opción, consulta codex exec.

Cuándo usar codex exec

Usa codex exec cuando quieras que Codex:

• se ejecute como parte de un pipeline (CI, verificaciones previas a la fusión de cambios o trabajos programados).
• genere una salida que puedas pasar a otras herramientas, por ejemplo, para elaborar notas de versión o resúmenes.
• se integre en flujos de trabajo de CLI que pasan la salida de un comando a Codex y envían la salida de Codex a otras herramientas.
• se ejecute con una configuración explícita de sandbox y aprobación definida de antemano.

Uso básico

Pasa el prompt de la tarea como un solo argumento:

codex exec "summarize the repository structure and list the top 5 risky areas"

Durante la ejecución de codex exec, Codex envía información de progreso a stderr y escribe únicamente el mensaje final del agente en stdout. Así puedes redirigir el resultado final o pasarlo a otro comando:

codex exec "generate release notes for the last 10 commits" | tee release-notes.md

Usa --ephemeral si quieres evitar que los archivos que registran la ejecución de la sesión se guarden en disco:

codex exec --ephemeral "triage this repository and suggest next steps"

Si los nodos que ejecutan los trabajos tienen directorios de inicio montados en red, consulta cómo mantener el estado de cada trabajo en el nodo local y conservar el registro de ejecución de la sesión.

Si envías datos por stdin mediante una tubería y también pasas un prompt como argumento, Codex toma el prompt como instrucción y los datos de la tubería como contexto adicional.

Así puedes generar la entrada con un comando y pasarla directamente a Codex:

curl -s https://jsonplaceholder.typicode.com/comments \
  | codex exec "format the top 20 items into a markdown table" \
  > table.md

Para conocer usos más avanzados de stdin con tuberías, consulta Uso avanzado de stdin con tuberías.

Permisos y seguridad

De forma predeterminada, codex exec se ejecuta en un sandbox de solo lectura. Al automatizar, concede solo los permisos que necesita el flujo de trabajo:

• Para permitir modificaciones: codex exec --sandbox workspace-write "<task>"
• Para permitir un acceso más amplio: codex exec --sandbox danger-full-access "<task>"

Usa danger-full-access únicamente en un entorno controlado, por ejemplo, en un runner de CI aislado o en un contenedor.

Codex ya no admite --full-auto. Actualiza los scripts para que usen --sandbox workspace-write o usa --approve-for-me para que las solicitudes de aprobación pasen por una revisión automática con el sandbox workspace-write.

Usa --ignore-user-config si necesitas ejecutar Codex sin cargar $CODEX_HOME/config.toml y --ignore-rules si necesitas omitir los archivos .rules de execpolicy del usuario y del proyecto en un entorno de automatización controlado.

Si configuras un servidor MCP habilitado con required = true y el servidor no se inicializa, codex exec termina con un error en lugar de continuar sin ese servidor.

Generar una salida legible por máquina

Para procesar la salida de Codex en scripts, usa el formato JSON Lines:

codex exec --json "summarize the repo structure" | jq

Al activar --json, stdout pasa a ser un flujo de datos en formato JSON Lines (JSONL). Así puedes capturar cada evento que emite Codex durante la ejecución. Los tipos de eventos incluyen thread.started, turn.started, turn.completed, turn.failed, item.* y error.

Los tipos de elementos incluyen mensajes del agente, razonamiento, ejecuciones de comandos, cambios en archivos, llamadas a herramientas MCP, búsquedas web y actualizaciones del plan.

Ejemplo de un flujo JSON (cada línea es un objeto JSON):

{"type":"thread.started","thread_id":"0199a213-81c0-7800-8aa1-bbab2a035a53"}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","command":"bash -lc ls","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"Repo contains docs, sdk, and examples directories."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122,"reasoning_output_tokens":0}}

Si solo necesitas el mensaje final, guárdalo en un archivo con -o <path> o --output-last-message <path>. Codex escribe el mensaje final en el archivo y también lo envía a stdout (consulta codex exec para obtener más detalles).

Crear resultados estructurados con un esquema

Si necesitas datos estructurados para los pasos posteriores, usa --output-schema para solicitar una respuesta final que se ajuste a un esquema definido con JSON Schema. Esto resulta útil en flujos de trabajo automatizados que requieren campos estables, por ejemplo, para resúmenes de trabajos, informes de riesgos o metadatos de versiones.

schema.json

{
  "type": "object",
  "properties": {
    "project_name": { "type": "string" },
    "programming_languages": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["project_name", "programming_languages"],
  "additionalProperties": false
}

Ejecuta Codex con el esquema y guarda en disco la respuesta JSON final:

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

Ejemplo de salida final (stdout):

{
  "project_name": "Codex CLI",
  "programming_languages": ["Rust", "TypeScript", "Shell"]
}

Autenticación en entornos de automatización

De forma predeterminada, codex exec reutiliza las credenciales de autenticación guardadas en la CLI. En CI, es habitual proporcionar las credenciales de forma explícita.

Usar la autenticación con clave de API

En GitHub Actions, usa la GitHub Action de Codex en lugar de instalar la CLI y autenticarte por tu cuenta. La acción está diseñada para reducir la exposición de la clave de API. Para ello, instala Codex, inicia un proxy para la API de Responses y ejecuta Codex con una estrategia de seguridad configurable.

No configures OPENAI_API_KEY ni CODEX_API_KEY como variables de entorno para todo el trabajo en flujos que descarguen o ejecuten código controlado por el repositorio. Los scripts de compilación, las pruebas, los hooks del ciclo de vida de las dependencias o una acción comprometida que se ejecute en el mismo trabajo pueden leer esas variables de entorno.

En otros entornos de automatización, configura CODEX_API_KEY solo para la ejecución de Codex que la necesite y asegúrate de que en el mismo entorno de proceso se ejecute únicamente código de confianza.

Para usar otra clave de API en una sola ejecución, define CODEX_API_KEY en la misma línea que el comando:

CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"

Puedes usar CODEX_API_KEY con codex exec, codex review, el SDK de TypeScript y codex exec-server --remote.

Reanudar una sesión no interactiva

Si necesitas continuar una ejecución anterior, por ejemplo, en un pipeline de dos etapas, usa el subcomando resume:

codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"

También puedes reanudar una sesión específica por su ID con codex exec resume <SESSION_ID>.

Requisito de repositorio Git

Codex exige que los comandos se ejecuten dentro de un repositorio Git para evitar cambios destructivos. Si tienes la certeza de que el entorno es seguro, puedes omitir esta verificación con codex exec --skip-git-repo-check.

Patrones comunes de automatización

Ejemplo: corregir automáticamente fallas de CI en GitHub Actions

En los flujos de trabajo de GitHub Actions, usa openai/codex-action en lugar de instalar Codex y pasar la clave de API a un paso de shell. La acción inicia un proxy seguro para la clave de API de OpenAI.

Puedes usar Codex para proponer correcciones automáticamente cuando falla un flujo de trabajo de CI. Sigue estos pasos:

1. Activa un flujo de trabajo de seguimiento cuando el flujo principal de CI termine con un error.
2. Descarga el código del commit que falló con permisos de solo lectura para el repositorio.
3. Ejecuta los comandos de preparación antes de ejecutar Codex, sin exponer tu clave de API de OpenAI en esos pasos.
4. Ejecuta la GitHub Action de Codex.
5. Guarda los cambios locales de Codex como un artefacto que contenga el parche.
6. En otro trabajo, aplica el parche y abre un pull request.

El trabajo de Codex que se muestra a continuación solo tiene el permiso contents: read. Después de ejecutar Codex, se limita a guardar las diferencias como artefacto. El trabajo open_pr recibe permisos de escritura para el repositorio, pero no recibe OPENAI_API_KEY.

El ejemplo supone que usas un proyecto de Node.js. Adapta los comandos de preparación y prueba a las tecnologías de tu proyecto.

Para consultar una lista más detallada de verificaciones de seguridad, lee la guía de seguridad de la GitHub Action de Codex.

name: Codex auto-fix on CI failure

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  generate_fix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      has_patch: ${{ steps.diff.outputs.has_patch }}
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          fetch-depth: 0
          persist-credentials: false

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: |
          if [ -f package-lock.json ]; then npm ci; fi

      - name: Run Codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            The CI workflow "${{ github.event.workflow_run.name }}" failed for commit
            ${{ github.event.workflow_run.head_sha }}.

            Run `npm test --silent` to reproduce the failure. Identify the minimal
            change needed to make the tests pass, implement only that change, and
            run `npm test --silent` again.

            Do not refactor unrelated files.

      - name: Create patch artifact
        id: diff
        run: |
          git add -N .
          git diff --binary HEAD > codex.patch
          if [ -s codex.patch ]; then
            echo "has_patch=true" >> "$GITHUB_OUTPUT"
          else
            echo "has_patch=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Upload patch artifact
        if: steps.diff.outputs.has_patch == 'true'
        uses: actions/upload-artifact@v4
        with:
          name: codex-fix-patch
          path: codex.patch
          if-no-files-found: error

  open_pr:
    runs-on: ubuntu-latest
    needs: generate_fix
    if: needs.generate_fix.outputs.has_patch == 'true'
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          fetch-depth: 0

      - uses: actions/download-artifact@v4
        with:
          name: codex-fix-patch

      - name: Apply Codex patch
        run: git apply --index codex.patch

      - name: Open pull request
        env:
          GH_TOKEN: ${{ github.token }}
          FAILED_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
          FAILED_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
          RUN_ID: ${{ github.event.workflow_run.run_id }}
        run: |
          branch="codex/auto-fix-$RUN_ID"

          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git switch -c "$branch"
          git commit -m "Auto-fix failing CI via Codex"
          git push origin "$branch"

          {
            echo "Codex generated this patch after CI failed for \`$FAILED_HEAD_SHA\`."
            echo
            echo "Review the changes before merging."
          } > pr-body.md

          gh pr create \
            --base "$FAILED_HEAD_BRANCH" \
            --head "$branch" \
            --title "Auto-fix failing CI via Codex" \
            --body-file pr-body.md

Uso avanzado de stdin con tuberías

Cuando otro comando genera la entrada para Codex, elige cómo usar stdin según el origen de la instrucción. Combina un prompt con stdin si ya sabes qué instrucción dar y quieres pasar la salida de otro comando como contexto. Usa codex exec - si quieres que stdin proporcione el prompt completo.

Combinar un prompt con stdin

Combinar un prompt con stdin es útil cuando otro comando ya genera los datos que quieres que Codex examine. En este modo, escribes la instrucción y pasas la salida del comando por una tubería para que sirva de contexto. Por eso, se adapta bien a los flujos de trabajo de CLI que procesan salidas de comandos, registros y datos generados.

npm test 2>&1 \
  | codex exec "summarize the failing tests and propose the smallest likely fix" \
  | tee test-summary.md

tail -n 200 app.log \
  | codex exec "identify the likely root cause, cite the most important errors, and suggest the next three debugging steps" \
  > log-triage.md

curl -vv https://api.example.com/health 2>&1 \
  | codex exec "explain the TLS or HTTP failure and suggest the most likely fix" \
  > tls-debug.md

gh run view 123456 --log \
  | codex exec "write a concise Slack-ready update on the CI failure, including the likely cause and next step" \
  | pbcopy

gh run view 123456 --log \
  | codex exec "summarize the failure in 5 bullets for the pull request thread" \
  | gh pr comment 789 --body-file -

Usar codex exec - cuando stdin contiene el prompt

Si omites el argumento del prompt, Codex lee el prompt desde stdin. Usa codex exec - si quieres indicar explícitamente que debe leerlo desde allí.

El marcador - resulta útil cuando otro comando o script genera dinámicamente el prompt completo. Puedes usarlo si guardas prompts en archivos, los construyes con scripts de shell o combinas la salida de un comando en tiempo real con instrucciones antes de pasarle el prompt completo a Codex.

cat prompt.txt | codex exec -

printf "Summarize this error log in 3 bullets:\n\n%s\n" "$(tail -n 200 app.log)" \
  | codex exec -

generate_prompt.sh | codex exec - --json > result.jsonl