Modo no interactivo

El modo no interactivo permite ejecutar Codex desde scripts (por ejemplo, trabajos de integración continua (CI)) sin abrir la TUI interactiva. Se invoca con codex exec.

Para obtener información detallada sobre las opciones, consulta codex exec.

Cuándo usar codex exec

Usa codex exec cuando quieras que Codex:

• Se ejecute como parte de una canalización (CI, comprobaciones previas a la fusión, trabajos programados).
• Genere una salida que puedas canalizar a otras herramientas (por ejemplo, para generar notas de la versión o resúmenes).
• Se integre de forma natural en flujos de trabajo de CLI que encadenan la salida de comandos como entrada de Codex y pasan la salida de Codex a otras herramientas.
• Se ejecute con una configuración explícita y predefinida del entorno aislado y las aprobaciones.

Uso básico

Pasa una instrucción de tarea como un único argumento:

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

Mientras se ejecuta codex exec, Codex transmite el progreso a stderr e imprime únicamente el mensaje final del agente en stdout. Esto facilita redirigir o canalizar el resultado final:

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

Usa --ephemeral cuando no quieras conservar en el disco los archivos de registro de la sesión:

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

Si se canaliza stdin y también proporcionas un argumento de instrucción, Codex trata la instrucción como tal y el contenido canalizado como contexto adicional.

Esto permite generar fácilmente una 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 patrones más avanzados de canalización de stdin, consulta Canalización avanzada de stdin.

Permisos y seguridad

De forma predeterminada, codex exec se ejecuta en un entorno aislado de solo lectura. En la automatización, configura los permisos mínimos necesarios para el flujo de trabajo:

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

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

Codex conserva codex exec --full-auto como una opción de compatibilidad obsoleta y muestra una advertencia. En los scripts nuevos, usa preferentemente la opción explícita --sandbox workspace-write.

Usa --ignore-user-config cuando necesites una ejecución que no cargue $CODEX_HOME/config.toml y --ignore-rules cuando necesites 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 este no puede inicializarse, codex exec finaliza con un error en lugar de continuar sin ese servidor.

Generar una salida legible por máquinas

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

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

Cuando habilitas --json, stdout se convierte en un flujo JSON Lines (JSONL), por lo que puedes capturar cada evento que emite Codex mientras se ejecuta. 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 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, escríbelo en un archivo con -o <path>/--output-last-message <path>. Esto escribe el mensaje final en el archivo y también lo imprime en stdout (consulta codex exec para obtener más información).

Crear salidas estructuradas con un esquema

Si necesitas datos estructurados para pasos posteriores, usa --output-schema para solicitar una respuesta final que se ajuste a un JSON Schema. Esto resulta útil para flujos de trabajo automatizados que necesitan campos estables (por ejemplo, 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 escribe la respuesta JSON final en el disco:

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 la automatización

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

Usar la autenticación mediante API key

Para GitHub Actions, usa Codex GitHub Action en lugar de instalar y autenticar la CLI por tu cuenta. La acción está diseñada para reducir la exposición de la API key mediante la instalación de Codex, el inicio de un proxy de Responses API y la ejecución de Codex con una estrategia de seguridad configurable.

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

Para otros entornos de automatización, configura CODEX_API_KEY únicamente para la invocación individual de codex exec y asegúrate de que no se ejecute código que no sea de confianza en el mismo entorno de proceso.

Para usar una API key diferente en una sola ejecución, configura CODEX_API_KEY en línea:

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

CODEX_API_KEY solo es compatible con codex exec.

Reanudar una sesión no interactiva

Si necesitas continuar una ejecución anterior (por ejemplo, una canalización 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 seleccionar un ID de sesión específico con codex exec resume <SESSION_ID>.

Repositorio Git obligatorio

Codex requiere que los comandos se ejecuten dentro de un repositorio Git para evitar cambios destructivos. Omite esta comprobación con codex exec --skip-git-repo-check si tienes la certeza de que el entorno es seguro.

Patrones habituales de automatización

Ejemplo: Corregir automáticamente errores de CI en GitHub Actions

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

Puedes usar Codex para proponer correcciones automáticamente cuando falle un flujo de trabajo de CI. El patrón es el siguiente:

1. Activa un flujo de trabajo de seguimiento cuando el flujo de trabajo principal de CI finalice con un error.
2. Extrae el commit con errores únicamente con permisos de lectura del repositorio.
3. Ejecuta los comandos de configuración antes de Codex, sin exponer tu OpenAI API key a esos pasos.
4. Ejecuta Codex GitHub Action.
5. Guarda los cambios locales de Codex como un artefacto de parche.
6. En un trabajo independiente, aplica el parche y abre una solicitud de incorporación de cambios.

El trabajo de Codex que aparece a continuación solo tiene contents: read. Después de ejecutar Codex, únicamente serializa el diff como un artefacto. El trabajo open_pr recibe permisos de escritura en el repositorio, pero no recibe OPENAI_API_KEY.

El ejemplo presupone un proyecto de Node.js. Adapta los comandos de configuración y prueba a tu pila tecnológica.

Para consultar una lista de comprobación de seguridad más detallada, consulta las directrices de seguridad de Codex GitHub Action.

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

Canalización avanzada de stdin

Cuando otro comando genere una entrada para Codex, elige el patrón de stdin según de dónde deba proceder la instrucción. Usa una instrucción junto con stdin cuando ya conozcas la instrucción y quieras pasar la salida canalizada como contexto. Usa codex exec - cuando stdin deba convertirse en la instrucción completa.

Usar una instrucción junto con stdin

Una instrucción junto con stdin resulta útil cuando otro comando ya genera los datos que quieres que Codex examine. En este modo, escribes la instrucción y canalizas la salida como contexto, lo que encaja de forma natural en los flujos de trabajo de CLI basados en la salida de comandos, los registros y los 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 sea la instrucción

Si omites el argumento de instrucción, Codex lee la instrucción desde stdin. Usa codex exec - cuando quieras forzar explícitamente ese comportamiento.

El centinela - resulta útil cuando otro comando o script genera dinámicamente toda la instrucción. Es una buena opción cuando almacenas instrucciones en archivos, las compones con scripts de shell o combinas la salida de comandos en directo con instrucciones antes de pasar la instrucción completa 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