codex exec — как выполнять конкретные задачи Codex из терминала и скриптов

Практическое руководство по codex exec — неинтерактивному запуску Codex CLI для передачи одной задачи и получения финального сообщения в автоматизированном сценарии. Раздел о GitHub Actions сверён с официальным репозиторием OpenAI 12.09.2026; локальные параметры следует проверять в актуальной документации Codex CLI.

Что такое codex exec

Codex CLI умеет работать в двух режимах. Интерактивный режим открывает терминальный интерфейс, где вы ведёте диалог с агентом. Неинтерактивный запускается командой codex exec, получает конкретную задачу и завершается после финального ответа.

Такой запуск подходит для пайплайнов, регулярных заданий и сценариев, в которых результат нужно передать другой команде. При запуске прогресс обычно выводится в stderr, а финальный ответ можно направить в stdout или записать в отдельный файл.

Авторизация локального CLI

Официальный индекс документации отдельно выделяет разделы Codex CLI, Non-interactive mode, Authentication и Pricing. Порядок входа, хранение учётных данных и доступные лимиты зависят от версии CLI и конфигурации среды, поэтому перед автоматизацией сверяйте актуальные разделы. Для GitHub Actions действует отдельный контракт: официальный openai/codex-action принимает API-ключ выбранного провайдера через GitHub Secrets; его настройка описана ниже.

Основные возможности и базовое использование

Задача передаётся одним аргументом:

codex exec 'опиши структуру репозитория и назови 5 самых рискованных мест'

Результат можно сохранить или передать следующей команде:

codex exec 'собери release notes по последним 10 коммитам' | tee release-notes.md

Если сессионные файлы не нужны, добавьте --ephemeral:

codex exec --ephemeral 'проведи триаж репозитория и предложи следующие шаги'

Данные другой команды можно передать через стандартный ввод, включив инструкцию в тот же поток:

{
  echo 'Суммируй упавшие тесты и предложи минимальную правку.'
  npm test 2>&1
} | codex exec -

Если весь промпт находится в файле или формируется скриптом, используйте явный признак чтения из stdin:

cat prompt.txt | codex exec -

Права доступа и песочница

Для задач без изменения файлов используйте режим только чтения. Если агенту нужно редактировать рабочую копию, предоставьте это право явно.

Эта таблица относится к локальному CLI. В openai/codex-action действуют отдельные правила permission-profile и legacy-параметра sandbox, описанные ниже.

Флаг --full-auto сохранён для совместимости. В новых скриптах права лучше задавать явно через параметры песочницы или профиль разрешений, если используемый контур его поддерживает.

Команда обычно ожидает Git-репозиторий. Флаг --skip-git-repo-check снимает эту проверку, поэтому применять его стоит только в заранее подготовленном окружении.

Машиночитаемый вывод

Для автоматизации есть три уровня формализации результата.

Поток событий

Флаг --json превращает stdout в поток JSON Lines, где каждая строка содержит отдельное событие выполнения:

codex exec --json 'опиши структуру репозитория' | jq

Только финальное сообщение

Флаг -o <путь>, он же --output-last-message, записывает финальный ответ в файл:

codex exec 'подготовь краткий отчёт' -o ./report.md

Ответ по JSON Schema

Флаг --output-schema задаёт структуру финального ответа. Это удобно, когда результат должен без ручного разбора перейти в следующий шаг пайплайна.

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

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

Продолжение начатой задачи

Следующий запуск может продолжить предыдущую сессию:

codex exec 'проверь изменения на состояния гонки'
codex exec resume --last 'исправь найденные состояния гонки'

Для конкретной сессии укажите её идентификатор:

codex exec resume <SESSION_ID> 'продолжи проверку'

Полезные сценарии

Расписание без CI-сервера

Локальный планировщик подходит для регулярных отчётов, если машина включена, авторизация доступна процессу и вы контролируете окружение запуска.

0 9 * * * cd /path/to/repo && /usr/local/bin/codex exec 'собери сводку коммитов за последние 24 часа' -o "/path/to/reports/$(date +%F).md" >> /path/to/logs/codex-cron.log 2>&1

Такой запуск использует окружение и доступы системного пользователя планировщика. Перед автоматизацией проверьте права на репозиторий, путь к бинарному файлу и доступность нужных учётных данных.

Контент-конвейер со строгим форматом

codex exec можно использовать для черновиков, которые строятся по повторяемому шаблону: кратких новостей, описаний и сценариев. Источник передаётся через stdin, а --output-schema фиксирует контракт со следующим шагом.

Пример новости только по фактам из входного текста:

{
  echo 'Сделай короткую новость по источнику. Не добавляй отсутствующие факты, даты и цифры. Если данных недостаточно, верни SOURCE_UNCLEAR.'
  cat source-article.txt
} | codex exec - -o ./content/news-draft.md

Пример схемы для сценария ролика:

{
  "type": "object",
  "properties": {
    "title": { "type": "string" },
    "total_duration_sec": { "type": "number" },
    "scenes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "index": { "type": "number" },
          "duration_sec": { "type": "number" },
          "voiceover": { "type": "string" },
          "on_screen_text": { "type": "string" },
          "visual_prompt": { "type": "string" }
        },
        "required": ["index", "duration_sec", "voiceover", "on_screen_text", "visual_prompt"],
        "additionalProperties": false
      }
    }
  },
  "required": ["title", "total_duration_sec", "scenes"],
  "additionalProperties": false
}

{
  echo 'Собери сценарий вертикального ролика на 45 секунд: 5–7 сцен, разговорная озвучка, короткий текст на экране.'
  cat brief.md
} | codex exec - --output-schema ./video-scene.schema.json -o ./scenes.json

Запуск в GitHub Actions

Официальный openai/codex-action устанавливает Codex CLI и подключает его к Responses API через защищённый прокси. Для запуска нужен API-ключ выбранного провайдера, сохранённый в GitHub Secrets.

Минимальный пример:

- uses: actions/checkout@v5
  with:
    persist-credentials: false

- name: Run Codex
  id: run_codex
  uses: openai/codex-action@v1
  with:
    openai-api-key: ${{ secrets.OPENAI_API_KEY }}
    permission-profile: ":workspace"
    prompt: Review the changes and report concrete problems.

Для новых сценариев GitHub Actions официальный репозиторий рекомендует профили разрешений:

• :workspace — если агенту нужно менять файлы checkout;
• :read-only — для анализа без изменений;
• именованный профиль из доверенного config.toml — когда нужна более узкая политика.

Профили разрешений имеют статус beta и требуют Codex CLI версии 0.138.0 или новее. Не закрепляйте более старую версию через codex-version, если используете permission-profile.

permission-profile нельзя сочетать с входом sandbox. Стратегия safety-strategy: read-only также включает устаревшую read-only-песочницу и несовместима с профилем разрешений. В защищённом запуске --full-auto нельзя сочетать с профилем разрешений или эффективной read-only-песочницей.

Если не указать ни профиль, ни sandbox, action ради обратной совместимости использует прежнюю песочницу workspace-write.

По умолчанию action применяет safety-strategy: drop-sudo. На Linux и macOS она лишает запускаемого пользователя sudo и снижает набор доступных привилегий. Изменения учётной записи и системных сокетов могут сохраниться на повторно используемом self-hosted runner, поэтому официальный репозиторий советует применять этот режим на одноразовых раннерах и ставить шаг Codex последним в job.

Доступные стратегии:

На GitHub-hosted Windows поддерживается только safety-strategy: unsafe, поскольку поддерживаемой песочницы там нет. На Linux режимы на основе Bubblewrap требуют работающих непривилегированных пользовательских пространств имён; для self-hosted runner это нужно настроить заранее, включая ограничения AppArmor или SELinux.

Финальное сообщение доступно как output final-message:

outputs:
  final_message: ${{ steps.run_codex.outputs.final-message }}

Передавайте его в отдельный job с минимально необходимыми правами, если результат нужно опубликовать в pull request. Не выдавайте самому шагу Codex право записи комментариев без необходимости.

Лимиты и когда нужен API-ключ

Точные лимиты и стоимость зависят от плана, модели и текущих правил. Проверяйте их по официальной странице Pricing и дашборду использования непосредственно перед тем, как ставить запуск в расписание.

Для GitHub Actions API-ключ передавайте через input openai-api-key из GitHub Secrets. Способ передачи ключа для локального CLI сверяйте с актуальным разделом Authentication выбранной версии Codex.

Ограничения и когда инструмент не подходит

• Не переносите локальные учётные данные на публичный или недоверенный раннер.
• Не используйте danger-full-access за пределами изолированного окружения.
• Отключение проверки Git-репозитория снимает одну из защитных границ.
• Внешние интеграции, включая MCP, добавляют отдельные точки отказа; проверьте их доступность и обработку ненулевого кода возврата.
• Проектные инструкции и конфигурационные файлы могут влиять на поведение агента. Проверяйте их перед запуском в чужом репозитории.
• Формат JSON или JSON Schema обеспечивает структуру данных, но не подтверждает фактическую точность ответа.

Проверка результата

Минимальный проверочный сценарий:

1. Перейдите в тестовый Git-репозиторий без секретов.
2. Выполните codex exec 'перечисли файлы верхнего уровня и назови стек проекта'.
3. Убедитесь, что команда завершилась и вернула финальный ответ.
4. Выполните codex exec --json 'перечисли файлы верхнего уровня' | jq и проверьте, что каждая строка разбирается как JSON.
5. Для задачи с записью используйте отдельную тестовую ветку, добавьте --sandbox workspace-write, затем проверьте git diff.
6. Для проверки расхода откройте актуальный дашборд использования и сопоставьте результат с выбранным контуром авторизации.

Прохождение этих шагов подтверждает работу базового запуска и формата вывода. Оно не заменяет проверку качества и безопасности изменений.

Чеклист «Что делать, если…»

• Ответ пришёл без правок — предоставьте право записи через подходящую песочницу или профиль разрешений.
• Команда не стартует вне репозитория — перейдите в репозиторий либо осознанно используйте --skip-git-repo-check.
• Скрипт не может разобрать вывод — используйте --json или --output-schema.
• Нужен только финальный текст — запишите его через -o <путь>.
• Авторизация не работает на сервере — сверяйтесь с актуальным разделом Authentication для вашей версии CLI и средой запуска.
• Нужно продолжить прошлую задачу — используйте codex exec resume --last '<следующий шаг>'.
• GitHub Action отклоняет параметры — проверьте, не заданы ли одновременно permission-profile, sandbox или несовместимая стратегия read-only.
• Профиль разрешений не запускается — проверьте, что версия Codex CLI не ниже 0.138.0.
• Песочница не стартует на self-hosted Linux — проверьте пользовательские пространства имён и ограничения AppArmor или SELinux.

Ссылки

• Официальная документация ChatGPT и Codex
• Дашборд использования Codex
• openai/codex-action — запуск Codex в GitHub Actions

Следующий шаг

Если нужна актуальная справка по разделам Codex CLI и неинтерактивному режиму, откройте официальную документацию ChatGPT и Codex.

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

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

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov