Флаг Codex CLI --config применяется для временного изменения настроек запуска без ручного редактирования файла конфигурации. Его короткий аналог — -c. С его помощью можно указать модель, режим подтверждения действий, уровень изоляции среды, профиль или другой параметр, поддерживаемый конкретной версией Codex CLI.
--configменяет настройки только для текущего запуска, если вы не записываете эти параметры отдельно в постоянный конфигурационный файл.
Это особенно удобно, когда один и тот же инструмент приходится запускать в разных режимах: например, безопасно анализировать код только для чтения, разрешать изменения в рабочем каталоге, тестировать новую модель или быстро проверять экспериментальную настройку. Важно помнить: после флага обычно указывается пара ключ=значение, а сам параметр можно передавать несколько раз.
- Как использовать
- Когда применять
- Примеры использования
- Выбор модели на один запуск
- Использование короткого аналога -c
- Запуск с политикой подтверждений
- Ограничение среды режимом только для чтения
- Разрешение изменений в рабочем каталоге
- Одновременная настройка модели и песочницы
- Отключение проверки обновлений на один запуск
- Использование профиля
- Передача параметров подкоманде exec
- Проверка синтаксиса перед рабочим запуском
- Запуск с параметрами из shell-сценария
- Сравнение двух конфигураций
- Чем отличается от…
- Отличие от -c
- Отличие от файла config.toml
- Отличие от переменных окружения
- Отличие от аргументов запроса
- Типичные ошибки
- Ошибка: забыто значение после ключа
- Ошибка: значение взято в неправильные кавычки
- Ошибка: используется неподдерживаемый ключ
- Ошибка: ожидание постоянного изменения
- Ошибка: чрезмерно широкие права
- Ошибка: секреты попадают в историю команд
- Краткая памятка
Как использовать
В этом разделе разберём базовый синтаксис флага, расположение параметров в команде и правила записи значений. Понимание этих основ избавляет от большинства ошибок ещё до первого запуска.
Вызов
--config— это не отдельная команда, а способ передать Codex CLI точечное переопределение настройки непосредственно при запуске.
Общий вид команды выглядит так:
codex --config ключ=значение
Короткая форма полностью эквивалентна длинной:
codex -c ключ=значение
Если нужно изменить несколько параметров, флаг указывают несколько раз. Например, одна настройка может отвечать за модель, а другая — за режим подтверждения действий:
codex --config model="gpt-5-codex" --config approval_policy="on-request"
Для подкоманд вроде exec или resume точное положение глобальных параметров зависит от версии Codex CLI. На практике сначала стоит проверить справку:
codex --help codex exec --help
| Форма записи | Что означает | Когда использовать |
|---|---|---|
--config key=value |
Полная форма параметра | В документации, скриптах и командах, где важна читаемость |
-c key=value |
Короткий псевдоним | В интерактивной работе и коротких командах |
--config key="text" |
Строковое значение в формате TOML | Для названий моделей, профилей и текстовых параметров |
Несколько --config |
Набор временных переопределений | Когда нужно изменить две и более настройки |
Значение после знака равенства интерпретируется как значение конфигурации, а не просто как произвольный текст. Поэтому строки обычно заключают в кавычки, логические значения пишут как true или false, а списки и вложенные структуры должны соответствовать синтаксису TOML.
| Тип значения | Пример | Замечание |
|---|---|---|
| Строка | model="gpt-5-codex" |
Кавычки помогают избежать неоднозначности |
| Логическое значение | check_for_update_on_startup=false |
Используются true и false |
| Число | timeout=30 |
Поддержка зависит от конкретного ключа |
| Вложенный ключ | shell_environment_policy.inherit="all" |
Синтаксис зависит от схемы настройки |
Если оболочка интерпретирует специальные символы, всю пару лучше заключить в одинарные кавычки. Это особенно актуально для значений, содержащих пробелы, скобки, символы $ или кавычки.
Когда применять
Флаг полезен не только для экономии времени. Он помогает разделить постоянные настройки и ситуативные решения: базовый конфигурационный файл остаётся стабильным, а конкретный запуск получает нужные отклонения.
Хорошее правило: постоянные предпочтения храните в конфигурации, разовые эксперименты передавайте через
--config.
Наиболее очевидный случай — проверка гипотезы. Например, вы хотите сравнить поведение двух моделей или временно отключить автоматическую проверку обновлений, не меняя настройки для всей команды. После завершения эксперимента не остаётся «забытых» параметров, которые неожиданно повлияют на следующую сессию.
| Ситуация | Почему подходит --config |
Результат |
|---|---|---|
| Разовый запуск другой модели | Не требуется менять основной файл | Тест проходит в изолированном контексте |
| Работа в режиме только чтения | Безопасность можно включить на один запуск | Снижается риск случайной модификации файлов |
| Автоматизация в CI | Настройки видны прямо в скрипте | Поведение задания проще воспроизвести |
| Отладка конфигурации | Можно менять по одному параметру | Легче найти конфликтующую настройку |
Второй важный сценарий — безопасность. Для анализа незнакомого репозитория разумно начать с ограничительного режима, а не сразу разрешать агенту записывать файлы или выполнять потенциально опасные действия. Комбинация конфигурации песочницы и политики подтверждений позволяет подобрать баланс между автономностью и контролем.
Третий сценарий — работа в разных проектах. В одном репозитории может быть удобно разрешить изменения в рабочем каталоге, а в другом — только просматривать файлы. Временный флаг позволяет не превращать глобальные настройки в компромисс, который неудобен везде.
| Режим работы | Предпочтительная идея | Что проверить заранее |
|---|---|---|
| Анализ чужого проекта | Ограничить запись и запросить подтверждения | Какие каталоги доступны агенту |
| Локальная разработка | Разрешить изменения в рабочей области | Есть ли резервная копия и чистый Git-status |
| CI-проверка | Задать параметры явно в сценарии | Не попадают ли секреты в логи |
| Сравнение моделей | Менять только ключ model |
Одинаковы ли остальные настройки |
Наконец, --config удобен для диагностики. Если Codex CLI ведёт себя не так, как ожидается, можно временно изменить одну настройку и сравнить результат. Такой подход лучше, чем сразу переписывать весь конфигурационный файл: иначе будет сложно понять, какой именно параметр повлиял на поведение.
Примеры использования
Ниже приведены практические сценарии — от самых простых до более составных. Названия доступных ключей и поддерживаемые значения могут отличаться между версиями Codex CLI, поэтому перед применением конкретного параметра полезно свериться с codex --help и актуальной документацией.
Выбор модели на один запуск
Если нужно проверить работу конкретной модели, можно передать её имя непосредственно в командной строке. Основная конфигурация при этом не изменится.
codex --config model="gpt-5-codex"
| Элемент | Значение | Практический смысл |
|---|---|---|
model |
Ключ конфигурации | Определяет модель для текущего запуска |
"gpt-5-codex" |
Строковое значение | Указывает выбранный идентификатор модели |
| Отсутствие записи в файле | Временное изменение | Постоянные настройки не переписываются |
Использование короткого аналога -c
Короткая форма удобна, когда команда запускается часто вручную и не хочется каждый раз писать длинный флаг.
codex -c model="gpt-5-codex"
Запуск с политикой подтверждений
Политика подтверждений определяет, в каких случаях Codex CLI должен спрашивать разрешение перед выполнением действий. Конкретные допустимые значения зависят от версии, но часто используется режим on-request.
codex --config approval_policy="on-request"
Ограничение среды режимом только для чтения
Для первичного ознакомления с незнакомым репозиторием полезно запретить изменения. Это не заменяет полноценную проверку безопасности, но уменьшает вероятность случайной записи в проект.
codex --config sandbox_mode="read-only"
| Задача | Подходящий параметр | Ожидаемый эффект |
|---|---|---|
| Только просмотр проекта | sandbox_mode="read-only" |
Агент работает в ограниченном режиме |
| Изменения в рабочей папке | sandbox_mode="workspace-write" |
Разрешается работа в пределах workspace |
| Максимально широкие права | sandbox_mode="danger-full-access" |
Требует особенно осторожного применения |
Разрешение изменений в рабочем каталоге
В локальной разработке может понадобиться, чтобы Codex CLI редактировал файлы проекта. Перед этим убедитесь, что понимаете границы рабочей области и готовы проверить изменения через git diff.
codex --config sandbox_mode="workspace-write"
Одновременная настройка модели и песочницы
Несколько флагов --config позволяют собрать нужный режим из отдельных параметров. Это лучше, чем пытаться передать несколько настроек одной строкой, если формат конкретной версии этого не поддерживает.
codex --config model="gpt-5-codex" --config sandbox_mode="workspace-write"
Отключение проверки обновлений на один запуск
В автоматизированной среде иногда важно, чтобы запуск не зависел от сетевой проверки обновлений. Такой параметр стоит применять осознанно: отключение уведомлений не означает, что обновления больше не нужны.
codex --config check_for_update_on_startup=false
Использование профиля
Если версия Codex CLI поддерживает профили, можно выбрать нужный профиль при запуске. Профиль обычно объединяет несколько связанных настроек и помогает не повторять длинный набор флагов.
codex --config profile="review"
| Подход | Плюсы | Минусы |
|---|---|---|
Несколько параметров через -c |
Все настройки видны прямо в команде | Команда становится длиннее |
| Профиль | Короткий и повторяемый запуск | Нужно заранее настроить профиль |
| Постоянный файл | Удобно для ежедневной работы | Легко забыть о глобальном эффекте |
Передача параметров подкоманде exec
Для неинтерактивного выполнения обычно используют подкоманду exec. В зависимости от версии глобальный флаг может располагаться до подкоманды или поддерживаться самой подкомандой, поэтому сначала проверьте её справку.
codex exec --config model="gpt-5-codex" "Проверь структуру тестов в проекте"
Проверка синтаксиса перед рабочим запуском
Если вы не уверены, поддерживает ли установленная версия определённый ключ, начните со справки. Это особенно важно для автоматизации: ошибка в параметре может остановить задание ещё до анализа проекта.
codex --help codex exec --help
Запуск с параметрами из shell-сценария
В скрипте параметры можно собирать из переменных, но следует осторожно обращаться с внешним вводом. Не подставляйте непроверенные значения в команду без экранирования.
MODEL="gpt-5-codex" codex --config model="$MODEL"
Сравнение двух конфигураций
Для корректного сравнения меняйте одну настройку за раз. Например, сначала запустите анализ с одной моделью, затем повторите его с другой, сохранив остальные параметры неизменными.
codex --config model="gpt-5-codex" --config sandbox_mode="read-only" codex --config model="gpt-4.1" --config sandbox_mode="read-only"
Чем отличается от…
Флаг --config часто путают с другими параметрами командной строки. Ниже разберём близкие по смыслу варианты и границы между ними.
Отличие от -c
-c — не другой механизм настройки, а короткий псевдоним --config. Поведение, область действия и требования к формату значения у них одинаковые.
codex --config model="gpt-5-codex" codex -c model="gpt-5-codex"
| Критерий | --config |
-c |
|---|---|---|
| Назначение | Переопределение настройки | То же самое |
| Читаемость | Выше | Ниже, зато команда короче |
| Совместимость | Предпочтительна в документации | Удобна для ручного ввода |
Отличие от файла config.toml
Файл конфигурации предназначен для постоянных или часто используемых настроек. --config обычно применяется как временное переопределение поверх уже загруженной конфигурации.
codex --config model="gpt-5-codex"
В результате модель для этого запуска может отличаться от модели, указанной в config.toml. Сам файл при этом не редактируется.
Отличие от переменных окружения
Переменные окружения — ещё один способ передавать параметры процессу, но их имена и поддержка зависят от реализации. --config обычно яснее показывает, какую именно настройку вы меняете.
MODEL="gpt-5-codex" codex --config model="$MODEL"
| Способ | Область действия | Удобство аудита |
|---|---|---|
--config |
Один запуск | Высокое: параметр виден в команде |
config.toml |
Несколько запусков | Зависит от доступности файла |
| Переменная окружения | Процесс и его дочерние процессы | Может быть менее очевидной |
Отличие от аргументов запроса
Текст вроде «проанализируй тесты» — это инструкция агенту, а --config — параметр самого CLI. Инструкция не должна использоваться для замены технических настроек безопасности, модели или песочницы.
codex --config sandbox_mode="read-only" "Проанализируй тесты и перечисли потенциальные проблемы"
Типичные ошибки
Ошибки при работе с --config чаще всего связаны не со сложностью самого флага, а с форматом значений, расположением параметра и неверными ожиданиями от области действия настройки.
Ошибка: забыто значение после ключа
Запись только имени параметра недостаточна: Codex CLI ожидает выражение в формате ключ=значение. Пробелы вокруг знака равенства лучше не использовать.
Неправильно: codex --config model Правильно: codex --config model="gpt-5-codex"
Ошибка: значение взято в неправильные кавычки
Строковые значения должны соответствовать формату, который ожидает конфигурация. Кроме того, кавычки обрабатывает и оболочка, поэтому сложные значения требуют аккуратного экранирования.
Рискованный вариант: codex --config model=gpt-5-codex Надёжнее: codex --config model="gpt-5-codex"
Ошибка: используется неподдерживаемый ключ
Набор параметров меняется между версиями Codex CLI. Настройка, найденная в статье для другой версии, может быть переименована, удалена или не относиться к командной строке.
codex --help codex exec --help
| Признак проблемы | Вероятная причина | Что сделать |
|---|---|---|
| Неизвестный аргумент | Флаг не поддерживается в этой версии | Проверить локальную справку и обновить документацию |
| Неверное значение | Использован неправильный вариант enum | Сверить допустимые значения |
| Параметр игнорируется | Он передан не той подкоманде | Проверить синтаксис exec --help |
| Команда не запускается | Ошибка TOML или shell-экранирования | Упростить значение и проверить кавычки |
Ошибка: ожидание постоянного изменения
После запуска с --config пользователь иногда открывает новый сеанс и удивляется, что настройка исчезла. Это нормальное поведение временного переопределения.
codex --config model="gpt-5-codex"
# Следующий запуск без флага использует обычную конфигурацию
codex
Ошибка: чрезмерно широкие права
Режим вроде danger-full-access может быть оправдан в контролируемой среде, но не должен становиться бездумным значением по умолчанию. Чем больше прав получает агент, тем важнее проверка проекта, команд и результата.
Опасный без необходимости вариант: codex --config sandbox_mode="danger-full-access" Более осторожный вариант для анализа: codex --config sandbox_mode="read-only"
Ошибка: секреты попадают в историю команд
Командная строка может сохраняться в истории shell, логах CI или системах мониторинга. Не передавайте через --config токены, пароли и другие секреты, если это не предусмотрено безопасным механизмом хранения.
Не следует: codex --config api_key="секретное-значение" Предпочтительно: # Используйте штатное безопасное хранилище или переменную, # которая не выводится в журнал задания.
Краткая памятка
Флаг --config нужен для точечного изменения конфигурации Codex CLI во время запуска. Он особенно полезен для разовых экспериментов, безопасного анализа, автоматизации и сравнения разных режимов работы.
| Вопрос | Короткий ответ |
|---|---|
| Какой общий синтаксис? | codex --config ключ=значение |
| Есть ли короткая форма? | Да, -c ключ=значение |
| Можно ли указать несколько параметров? | Да, повторяя флаг несколько раз |
| Изменяется ли файл конфигурации? | Обычно нет, изменение действует на текущий запуск |
| Нужно ли заключать строки в кавычки? | Желательно, особенно для сложных значений |
| Где проверить поддерживаемые ключи? | В локальной справке codex --help и справке подкоманды |
Перед запуском полезно пройти короткий чек-лист:
- Проверить, поддерживает ли установленная версия нужный ключ.
- Записать настройку в формате
ключ=значение. - Взять строковые значения в кавычки.
- Убедиться, что режим песочницы соответствует задаче.
- Не передавать секреты прямо в командной строке.
- Если параметров несколько, указать
--configдля каждого из них. - После выполнения проверить результат и убедиться, что временная настройка не была ошибочно принята за постоянную.
Безопасный шаблон для разового анализа:
codex --config model="gpt-5-codex" --config sandbox_mode="read-only" "Проанализируй структуру проекта"
Главная практическая идея проста: --config позволяет менять поведение Codex CLI точечно, прозрачно и без лишнего редактирования файлов. Используйте его для параметров конкретного запуска, проверяйте доступные значения в своей версии и особенно внимательно относитесь к настройкам, влияющим на запись файлов, выполнение команд и доступ к окружению.
