Mode non interactif

Le mode non interactif vous permet d’exécuter Codex depuis des scripts (par exemple, des tâches d’intégration continue (CI)) sans ouvrir la TUI interactive. Vous l’invoquez avec codex exec.

Pour plus de détails sur les options, consultez codex exec.

Quand utiliser codex exec

Utilisez codex exec lorsque vous souhaitez que Codex :

• s’exécute dans le cadre d’un pipeline (CI, vérifications avant fusion, tâches planifiées) ;
• produise une sortie que vous pouvez transmettre à d’autres outils (par exemple, pour générer des notes de version ou des résumés) ;
• s’intègre naturellement aux workflows CLI qui transmettent la sortie d’une commande à Codex, puis la sortie de Codex à d’autres outils ;
• s’exécute avec des paramètres de bac à sable et d’approbation explicites et prédéfinis.

Utilisation de base

Transmettez une consigne de tâche sous la forme d’un argument unique :

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

Pendant l’exécution de codex exec, Codex diffuse la progression vers stderr et affiche uniquement le message final de l’agent dans stdout. Vous pouvez ainsi facilement rediriger ou transmettre le résultat final :

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

Utilisez --ephemeral si vous ne souhaitez pas enregistrer les fichiers de déroulement de session sur le disque :

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

Si stdin est transmis et que vous fournissez également un argument de consigne, Codex traite la consigne comme l’instruction et le contenu transmis comme du contexte supplémentaire.

Vous pouvez ainsi facilement générer une entrée avec une commande et la transmettre directement à Codex :

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

Pour découvrir des modèles plus avancés de transmission via stdin, consultez Transmission avancée via stdin.

Autorisations et sécurité

Par défaut, codex exec s’exécute dans un bac à sable en lecture seule. Pour l’automatisation, accordez uniquement les autorisations nécessaires au workflow :

• Autoriser les modifications : codex exec --sandbox workspace-write "<task>"
• Autoriser un accès plus étendu : codex exec --sandbox danger-full-access "<task>"

Utilisez danger-full-access uniquement dans un environnement contrôlé (par exemple, un exécuteur CI isolé ou un conteneur).

Codex conserve codex exec --full-auto comme option de compatibilité obsolète et affiche un avertissement. Dans les nouveaux scripts, privilégiez l’option explicite --sandbox workspace-write.

Utilisez --ignore-user-config lorsque vous avez besoin d’une exécution qui ne charge pas $CODEX_HOME/config.toml, et --ignore-rules lorsque vous devez ignorer les fichiers execpolicy .rules de l’utilisateur et du projet dans un environnement d’automatisation contrôlé.

Si vous configurez un serveur MCP activé avec required = true et que son initialisation échoue, codex exec s’arrête avec une erreur au lieu de poursuivre sans ce serveur.

Rendre la sortie exploitable par une machine

Pour exploiter la sortie de Codex dans des scripts, utilisez le format JSON Lines :

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

Lorsque vous activez --json, stdout devient un flux JSON Lines (JSONL) qui vous permet de capturer chaque événement émis par Codex pendant son exécution. Les types d’événements incluent thread.started, turn.started, turn.completed, turn.failed, item.* et error.

Les types d’éléments comprennent les messages d’agent, le raisonnement, les exécutions de commandes, les modifications de fichiers, les appels d’outils MCP, les recherches sur le Web et les mises à jour du plan.

Exemple de flux JSON (chaque ligne est un objet 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 vous avez uniquement besoin du message final, écrivez-le dans un fichier avec -o <path>/--output-last-message <path>. Cette opération écrit le message final dans le fichier tout en l’affichant dans stdout (consultez codex exec pour plus de détails).

Créer des sorties structurées avec un schéma

Si vous avez besoin de données structurées pour les étapes suivantes, utilisez --output-schema afin de demander une réponse finale conforme à un schéma JSON. Cette fonctionnalité est utile pour les workflows automatisés qui nécessitent des champs stables (par exemple, des résumés de tâches, des rapports de risques ou des métadonnées de version).

schema.json

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

Exécutez Codex avec le schéma et écrivez la réponse JSON finale sur le disque :

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

Exemple de sortie finale (stdout) :

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

S’authentifier dans un environnement automatisé

codex exec réutilise par défaut l’authentification CLI enregistrée. Dans un environnement CI, il est courant de fournir explicitement les identifiants :

Utiliser l’authentification par API key

Pour GitHub Actions, utilisez Codex GitHub Action au lieu d’installer et d’authentifier vous-même la CLI. L’action est conçue pour limiter l’exposition de l’API key en installant Codex, en démarrant un proxy Responses API et en exécutant Codex avec une stratégie de sécurité configurable.

Ne définissez pas OPENAI_API_KEY ni CODEX_API_KEY comme variable d’environnement au niveau de la tâche dans les workflows qui extraient ou exécutent du code contrôlé par le dépôt. Les scripts de build, les tests, les hooks du cycle de vie des dépendances ou une action compromise dans la même tâche peuvent lire ces variables d’environnement.

Pour les autres environnements d’automatisation, définissez CODEX_API_KEY uniquement pour l’invocation codex exec concernée et assurez-vous qu’aucun code non fiable ne s’exécute dans le même environnement de processus.

Pour utiliser une autre API key lors d’une seule exécution, définissez CODEX_API_KEY en ligne :

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

CODEX_API_KEY est uniquement pris en charge dans codex exec.

Reprendre une session non interactive

Si vous devez poursuivre une exécution précédente (par exemple, dans un pipeline en deux étapes), utilisez la sous-commande resume :

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

Vous pouvez également cibler un ID de session précis avec codex exec resume <SESSION_ID>.

Dépôt Git requis

Codex exige que les commandes soient exécutées dans un dépôt Git afin d’éviter les modifications destructrices. Si vous êtes certain que l’environnement est sûr, contournez cette vérification avec codex exec --skip-git-repo-check.

Modèles d’automatisation courants

Exemple : corriger automatiquement les échecs de CI dans GitHub Actions

Pour les workflows GitHub Actions, utilisez openai/codex-action au lieu d’installer Codex et de transmettre l’API key à une étape de shell. L’action démarre un proxy sécurisé pour l’API key OpenAI.

Vous pouvez utiliser Codex pour proposer automatiquement des correctifs lorsqu’un workflow CI échoue. Procédez comme suit :

1. Déclenchez un workflow de suivi lorsque votre workflow CI principal se termine par une erreur.
2. Extrayez le commit en échec avec uniquement des autorisations de lecture sur le dépôt.
3. Exécutez les commandes de configuration avant Codex, sans exposer votre API key OpenAI à ces étapes.
4. Exécutez Codex GitHub Action.
5. Enregistrez les modifications locales de Codex sous forme d’artefact de correctif.
6. Dans une tâche distincte, appliquez le correctif et ouvrez une pull request.

La tâche Codex ci-dessous dispose uniquement de contents: read. Après l’exécution de Codex, elle se contente de sérialiser le diff sous forme d’artefact. La tâche open_pr reçoit des autorisations d’écriture sur le dépôt, mais ne reçoit pas OPENAI_API_KEY.

L’exemple suppose qu’il s’agit d’un projet Node.js. Adaptez les commandes de configuration et de test à votre pile technologique.

Pour une liste de contrôle de sécurité plus approfondie, consultez les recommandations de sécurité 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

Transmission avancée via stdin

Lorsqu’une autre commande produit une entrée pour Codex, choisissez le modèle stdin en fonction de la provenance souhaitée de l’instruction. Utilisez une consigne avec stdin lorsque vous connaissez déjà l’instruction et souhaitez transmettre la sortie reçue comme contexte. Utilisez codex exec - lorsque stdin doit devenir la consigne complète.

Utiliser une consigne avec stdin

Une consigne avec stdin est utile lorsqu’une autre commande produit déjà les données que vous souhaitez faire examiner par Codex. Dans ce mode, vous rédigez vous-même l’instruction et transmettez la sortie comme contexte, ce qui convient naturellement aux workflows CLI fondés sur les sorties de commandes, les journaux et les données générées.

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 -

Utiliser codex exec - lorsque stdin contient la consigne

Si vous omettez l’argument de consigne, Codex lit la consigne depuis stdin. Utilisez codex exec - pour imposer explicitement ce comportement.

Le marqueur - est utile lorsqu’une autre commande ou un autre script génère dynamiquement l’intégralité de la consigne. Cette approche convient lorsque vous stockez des consignes dans des fichiers, assemblez des consignes avec des scripts shell ou combinez la sortie de commandes exécutées en direct avec des instructions avant de transmettre l’intégralité de la consigne à 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