Неинтерактивный режим

Неинтерактивный режим позволяет запускать Codex из скриптов (например, в заданиях непрерывной интеграции (CI)), не открывая интерактивный TUI. Для его запуска используйте codex exec.

Подробное описание флагов см. в разделе codex exec.

Когда использовать codex exec

Используйте codex exec, если требуется, чтобы Codex:

• Выполнялся как часть конвейера (CI, проверки перед слиянием, запланированные задания).
• Формировал вывод, который можно передать другим инструментам через канал (например, для создания примечаний к выпуску или сводок).
• Естественно вписывался в рабочие процессы CLI, где вывод команд передаётся в Codex, а вывод Codex — другим инструментам.
• Запускался с явно заданными заранее настройками песочницы и подтверждений.

Основы использования

Передайте описание задачи одним аргументом:

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

Во время выполнения codex exec Codex передаёт ход выполнения в stderr, а в stdout выводит только итоговое сообщение агента. Благодаря этому итоговый результат легко перенаправить или передать через канал:

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

Используйте --ephemeral, если не хотите сохранять файлы истории сеанса на диск:

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

Если данные передаются через stdin и одновременно указан аргумент с запросом, Codex воспринимает запрос как инструкцию, а переданные через канал данные — как дополнительный контекст.

Это позволяет легко сформировать входные данные одной командой и сразу передать их в Codex:

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

Более сложные схемы передачи данных через stdin описаны в разделе Расширенные способы передачи данных через stdin.

Разрешения и безопасность

По умолчанию codex exec выполняется в песочнице только для чтения. Для автоматизации задавайте минимальные разрешения, необходимые рабочему процессу:

• Разрешить изменения: codex exec --sandbox workspace-write "<task>"
• Разрешить более широкий доступ: codex exec --sandbox danger-full-access "<task>"

Используйте danger-full-access только в контролируемой среде (например, в изолированном исполнителе CI или контейнере).

Codex сохраняет codex exec --full-auto как устаревший флаг совместимости и выводит предупреждение. В новых скриптах используйте явный флаг --sandbox workspace-write.

Используйте --ignore-user-config, если требуется запуск без загрузки $CODEX_HOME/config.toml, и --ignore-rules, если в контролируемой среде автоматизации требуется пропустить пользовательские и проектные файлы execpolicy .rules.

Если настроен включённый сервер MCP с required = true и его инициализация завершается сбоем, codex exec завершает работу с ошибкой, а не продолжает её без этого сервера.

Подготовка машиночитаемого вывода

Чтобы обрабатывать вывод Codex в скриптах, используйте формат JSON Lines:

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

При включении --json поток stdout преобразуется в JSON Lines (JSONL), что позволяет сохранять каждое событие, создаваемое Codex во время выполнения. Среди типов событий: thread.started, turn.started, turn.completed, turn.failed, item.* и error.

К типам элементов относятся сообщения агента, рассуждения, выполнение команд, изменения файлов, вызовы инструментов MCP, поисковые запросы в интернете и обновления плана.

Пример потока JSON (каждая строка представляет собой объект 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}}

Если требуется только итоговое сообщение, запишите его в файл с помощью -o <path>/--output-last-message <path>. Итоговое сообщение будет записано в файл и по-прежнему выведено в stdout (подробнее см. в разделе codex exec).

Создание структурированного вывода по схеме

Если для последующих этапов требуются структурированные данные, используйте --output-schema, чтобы запросить итоговый ответ, соответствующий JSON Schema. Это удобно для автоматизированных процессов, которым необходимы стабильные поля (например, для сводок по заданиям, отчётов о рисках или метаданных выпусков).

schema.json

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

Запустите Codex со схемой и запишите итоговый ответ JSON на диск:

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

Пример итогового вывода (stdout):

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

Аутентификация при автоматизации

По умолчанию codex exec повторно использует сохранённые данные аутентификации CLI. В CI обычно учётные данные указывают явно:

Аутентификация с помощью API key

Для GitHub Actions используйте Codex GitHub Action вместо самостоятельной установки и аутентификации CLI. Это действие помогает уменьшить риск раскрытия API key: оно устанавливает Codex, запускает прокси Responses API и выполняет Codex с настраиваемой стратегией безопасности.

Не задавайте OPENAI_API_KEY или CODEX_API_KEY как переменную среды на уровне задания в рабочих процессах, которые извлекают или выполняют код, контролируемый репозиторием. Скрипты сборки, тесты, обработчики жизненного цикла зависимостей или скомпрометированное действие в том же задании могут прочитать эти переменные среды.

В других средах автоматизации задавайте CODEX_API_KEY только для отдельного вызова codex exec и убедитесь, что в той же среде процесса не выполняется недоверенный код.

Чтобы использовать другой API key для одного запуска, задайте CODEX_API_KEY непосредственно в команде:

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

CODEX_API_KEY поддерживается только в codex exec.

Возобновление неинтерактивного сеанса

Если требуется продолжить предыдущий запуск (например, в двухэтапном конвейере), используйте подкоманду resume:

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

Также можно указать конкретный идентификатор сеанса с помощью codex exec resume <SESSION_ID>.

Требование к репозиторию Git

Во избежание разрушительных изменений Codex требует, чтобы команды выполнялись внутри репозитория Git. Если вы уверены в безопасности среды, отключите эту проверку с помощью codex exec --skip-git-repo-check.

Распространённые схемы автоматизации

Пример: автоматическое исправление сбоев CI в GitHub Actions

В рабочих процессах GitHub Actions используйте openai/codex-action вместо установки Codex и передачи API key в шаг оболочки. Действие запускает защищённый прокси для API key OpenAI.

Codex можно использовать для автоматического предложения исправлений при сбое рабочего процесса CI. Схема выглядит следующим образом:

1. Запустите последующий рабочий процесс, когда основной рабочий процесс CI завершится с ошибкой.
2. Извлеките проблемный коммит, предоставив только разрешения на чтение репозитория.
3. Выполните команды настройки до запуска Codex, не предоставляя этим шагам доступ к API key OpenAI.
4. Запустите Codex GitHub Action.
5. Сохраните локальные изменения Codex как артефакт с патчем.
6. В отдельном задании примените патч и откройте pull request.

Приведённое ниже задание Codex имеет только contents: read. После выполнения Codex оно лишь сериализует различия в артефакт. Задание open_pr получает разрешения на запись в репозиторий, но не получает OPENAI_API_KEY.

Пример рассчитан на проект Node.js. Измените команды настройки и тестирования в соответствии со своим стеком.

Более подробный контрольный список по безопасности см. в рекомендациях по безопасности 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

Расширенные способы передачи данных через stdin

Когда другая команда формирует входные данные для Codex, выбирайте способ работы со stdin в зависимости от того, откуда должна поступать инструкция. Используйте запрос вместе со stdin, если инструкция уже известна, а передаваемый через канал вывод требуется добавить как контекст. Используйте codex exec -, если полным запросом должно стать содержимое stdin.

Использование запроса вместе со stdin

Запрос вместе со stdin удобен, когда другая команда уже формирует данные, которые должен проверить Codex. В этом режиме вы самостоятельно указываете инструкцию и передаёте вывод через канал как контекст. Поэтому этот способ естественно подходит для рабочих процессов CLI, построенных на выводе команд, журналах и сгенерированных данных.

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 -

Использование codex exec -, когда stdin содержит запрос

Если аргумент с запросом не указан, Codex считывает запрос из stdin. Используйте codex exec -, чтобы явно включить это поведение.

Маркер - удобен, когда другая команда или скрипт динамически формирует весь запрос. Этот способ хорошо подходит, если запросы хранятся в файлах, собираются скриптами оболочки или если перед передачей полного запроса в 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