Mode non interactif

Le mode non interactif permet d’exécuter Codex depuis des scripts, par exemple dans des tâches d’intégration continue (CI), sans ouvrir l’interface interactive du terminal. Pour lancer Codex dans ce mode, utilisez codex exec.

Pour connaître le détail des options, consultez la référence de codex exec.

Quand utiliser codex exec

Utilisez codex exec lorsque vous souhaitez que Codex puisse :

• S’exécuter dans un pipeline (CI, vérifications avant fusion, tâches planifiées).
• Produire une sortie que vous pouvez transmettre à d’autres outils via un pipe, par exemple pour générer des notes de version ou des résumés.
• S’intégrer à des workflows en ligne de commande où Codex reçoit la sortie d’une commande et transmet à son tour le résultat à d’autres outils.
• S’exécuter avec des paramètres de bac à sable et d’approbation définis explicitement à l’avance.

Utilisation de base

Passez le prompt décrivant la tâche en un seul argument :

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

Pendant l’exécution de codex exec, Codex indique sa progression sur stderr et écrit uniquement le message final de l’agent sur stdout. Vous pouvez ainsi rediriger le résultat final ou le transmettre via un pipe :

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

Utilisez --ephemeral si vous ne souhaitez pas conserver sur disque les fichiers qui retracent le déroulement de la session :

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

Si le répertoire personnel de vos machines d’exécution est monté sur un système de fichiers réseau, découvrez comment stocker l’état de chaque tâche en local et conserver la trace du déroulement de la session.

Si vous alimentez l’entrée standard via un pipe et fournissez aussi un prompt en argument, Codex utilise le prompt comme instruction et le contenu de l’entrée standard comme contexte supplémentaire.

Vous pouvez ainsi générer des données avec une commande et les 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’autres façons d’utiliser les pipes, consultez la section Utilisation avancée de l’entrée standard.

Permissions et sécurité

Par défaut, codex exec s’exécute dans un bac à sable en lecture seule. Pour automatiser un workflow, accordez-lui uniquement les permissions nécessaires :

• Pour autoriser les modifications : codex exec --sandbox workspace-write "<task>"
• Pour autoriser un accès plus large : codex exec --sandbox danger-full-access "<task>"

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

L’option --full-auto n’est plus prise en charge. Modifiez vos scripts pour utiliser --sandbox workspace-write, ou utilisez --approve-for-me pour soumettre les demandes d’approbation à une révision automatique avec le bac à sable workspace-write.

Utilisez --ignore-user-config pour lancer une exécution sans charger $CODEX_HOME/config.toml. Dans un environnement d’automatisation contrôlé, utilisez --ignore-rules pour ignorer les fichiers .rules qui définissent les règles d’exécution de l’utilisateur et du projet.

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.

Obtenir une sortie exploitable par un script

Pour traiter 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 fournit un flux JSON Lines (JSONL) qui permet de capturer chaque événement émis par Codex pendant l’exécution. Les types d’événements comprennent thread.started, turn.started, turn.completed, turn.failed, item.* et error.

Les éléments peuvent correspondre à des messages de l’agent, à son raisonnement, à des exécutions de commandes, à des modifications de fichiers, à des appels d’outils MCP, à des recherches web ou à des mises à jour du plan.

Exemple de flux JSON où chaque ligne contient 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, enregistrez-le dans un fichier avec -o <path> ou --output-last-message <path>. Codex écrit alors le message final dans le fichier et continue de l’afficher sur stdout (consultez la référence de codex exec pour en savoir plus).

Créer des sorties structurées à l’aide d’un schéma

Si les étapes suivantes nécessitent des données structurées, utilisez --output-schema pour demander une réponse finale conforme à un schéma JSON. Cette option convient aux workflows automatisés qui ont besoin de champs stables, par exemple pour produire des résumés de tâches, des rapports sur les 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 ce schéma et enregistrez la réponse JSON finale sur 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"]
}

Authentification dans les workflows automatisés

Par défaut, codex exec réutilise les informations d’authentification enregistrées par la CLI. En CI, il est courant de fournir explicitement les identifiants.

Authentification par clé API

Pour GitHub Actions, utilisez la GitHub Action de Codex plutôt que d’installer la CLI et de configurer vous-même son authentification. L’action limite l’exposition de la clé API en installant Codex, en démarrant un proxy pour l’API Responses et en exécutant Codex avec une stratégie de sécurité configurable.

Ne définissez pas OPENAI_API_KEY ou CODEX_API_KEY comme variable d’environnement au niveau d’un job si le workflow récupère ou exécute 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 le même job peuvent lire ces variables d’environnement.

Dans les autres environnements d’automatisation, définissez CODEX_API_KEY uniquement pour l’appel à Codex qui en a besoin et assurez-vous qu’aucun code non fiable ne s’exécute dans le même environnement de processus.

Pour utiliser une autre clé API le temps d’une exécution, définissez CODEX_API_KEY sur la même ligne que la commande :

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

Vous pouvez utiliser CODEX_API_KEY avec codex exec, codex review, le SDK TypeScript et codex exec-server --remote.

Reprendre une session non interactive

Pour 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 aussi reprendre une session précise en indiquant son identifiant avec codex exec resume <SESSION_ID>.

Dépôt Git obligatoire

Pour éviter les modifications destructrices, Codex exige que les commandes s’exécutent dans un dépôt Git. Si vous avez la certitude que l’environnement est sûr, désactivez cette vérification avec codex exec --skip-git-repo-check.

Exemples courants d’automatisation

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

Dans vos workflows GitHub Actions, utilisez openai/codex-action plutôt que d’installer Codex et de transmettre la clé API à une étape shell. L’action démarre un proxy sécurisé pour la clé API OpenAI.

Vous pouvez utiliser Codex pour proposer automatiquement des correctifs en cas d’échec d’un workflow de CI. Procédez comme suit :

1. Déclenchez un second workflow lorsque votre workflow de CI principal se termine par une erreur.
2. Récupérez le commit pour lequel la CI a échoué, avec un accès au dépôt en lecture seule.
3. Exécutez les commandes de préparation avant Codex, sans exposer votre clé API OpenAI à ces étapes.
4. Exécutez la GitHub Action de Codex.
5. Enregistrez les modifications locales de Codex dans un fichier patch et conservez-le comme artefact.
6. Dans un job distinct, appliquez le patch et ouvrez une pull request.

Dans l’exemple ci-dessous, le job Codex dispose uniquement de la permission contents: read. Après l’exécution de Codex, il se limite à enregistrer le diff sous forme d’artefact. Le job open_pr reçoit les permissions d’écriture sur le dépôt, mais n’a pas accès à OPENAI_API_KEY.

L’exemple suppose que vous travaillez sur un projet Node.js. Adaptez les commandes de préparation et de test aux technologies de votre projet.

Pour une liste plus détaillée des points de sécurité à vérifier, consultez les consignes de sécurité 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

Utilisation avancée de l’entrée standard

Lorsqu’une autre commande produit les données d’entrée de Codex, choisissez comment utiliser l’entrée standard selon l’origine de l’instruction. Si vous connaissez déjà l’instruction, passez-la en argument et transmettez la sortie de la commande via un pipe pour fournir le contexte. Utilisez codex exec - si l’entrée standard doit fournir le prompt complet.

Combiner un prompt et l’entrée standard

Cette méthode convient lorsqu’une autre commande produit déjà les données que Codex doit examiner. Vous rédigez vous-même l’instruction et transmettez la sortie de la commande via un pipe pour fournir le contexte. Cette approche s’intègre bien aux workflows en ligne de commande qui traitent des sorties de commandes, des journaux ou des 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 l’entrée standard fournit le prompt

Si vous omettez le prompt en argument, Codex le lit depuis l’entrée standard. Utilisez codex exec - pour imposer explicitement ce comportement.

L’argument spécial - est utile lorsqu’une autre commande ou un script génère dynamiquement l’intégralité du prompt. Cette méthode convient si vous stockez vos prompts dans des fichiers, si vous les composez à l’aide de scripts shell ou si vous combinez la sortie d’une commande en cours d’exécution avec des instructions avant de transmettre le prompt complet à 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