Флаг Codex CLI —profile (-p): как выбрать профиль настроек

Флаг Codex CLI --profile применяется для выбора заранее настроенного профиля запуска. Его короткий аналог — -p. Профиль позволяет одним параметром переключить набор параметров: модель, режим подтверждения действий, уровень доступа к файловой системе и другие настройки, которые хранятся в конфигурации Codex CLI.

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

Если вы регулярно работаете в разных сценариях — например, в безопасном режиме чтения, в проекте с разрешённой записью файлов или в экспериментальной среде, — профили избавляют от ручного редактирования команд. Вместо десятка флагов достаточно указать --profile имя-профиля. При этом сам профиль обычно описывается в файле конфигурации Codex CLI, например в ~/.codex/config.toml.

Как использовать

Флаг --profile указывается при запуске Codex CLI и принимает имя профиля. Сначала профиль нужно создать в конфигурации, а затем передать его имя в командной строке.

Имя после --profile должно точно совпадать с именем секции профиля в конфигурации: Codex не угадывает опечатки и не подбирает похожие варианты.

Простейшая команда выглядит так:

codex --profile work

Короткая форма делает то же самое:

codex -p work

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

ОС	Типичное расположение	Что учитывать
Linux	~/.codex/config.toml	Каталог .codex находится в домашней директории пользователя
macOS	~/.codex/config.toml	Путь обычно совпадает с Linux
Windows	Путь в домашнем каталоге пользователя	Точное расположение может зависеть от способа установки и окружения

Пример конфигурации с несколькими профилями:

[profiles.readonly]
model = "gpt-5"
approval_policy = "on-request"
sandbox_mode = "read-only"

[profiles.work]
model = "gpt-5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.experiment]
model = "gpt-5"
approval_policy = "never"
sandbox_mode = "danger-full-access"

Названия параметров и доступные значения зависят от версии Codex CLI. Поэтому перед переносом конфигурации между машинами полезно свериться с документацией установленной версии и проверить, какие ключи она поддерживает.

Элемент	Пример	Назначение
Секция профиля	[profiles.work]	Создаёт профиль с именем work
Выбор профиля	--profile work	Подключает настройки профиля
Короткая форма	-p work	Сокращённая запись того же параметра
Параметр профиля	sandbox_mode = "workspace-write"	Задаёт режим доступа к рабочим файлам

Порядок применения настроек можно представить так:

1. Codex CLI загружает базовую конфигурацию.
2. Находит профиль, указанный после --profile или -p.
3. Применяет параметры выбранного профиля.
4. Учитывает отдельные параметры командной строки, если они переданы.

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

Когда применять

Профили особенно полезны там, где один и тот же инструмент используется в разных режимах безопасности, для разных проектов или с разными требованиями к скорости и качеству ответа. Они превращают набор настроек в понятные пресеты: readonly, work, review, ci.

Хороший профиль должен отвечать на вопрос: «В каком режиме сейчас работает Codex и какие ограничения у него есть?»

Например, профиль для анализа кода может запрещать изменение файлов, а рабочий профиль — разрешать запись только в текущем проекте. Это лучше, чем каждый раз вручную вспоминать, какой режим песочницы и какая политика подтверждений нужны.

Сценарий	Рекомендуемый профиль	Почему это удобно
Чтение и анализ проекта	readonly	Снижает риск случайных изменений
Обычная разработка	work	Сочетает доступ к рабочей директории и подтверждения действий
Проверка патча	review	Помогает сосредоточиться на анализе, а не на редактировании
Эксперименты	experiment	Отделяет рискованные настройки от повседневной работы
Автоматизация	ci	Фиксирует предсказуемый режим для скриптов и пайплайнов

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

Есть и ситуации, когда --profile не нужен:

• если вы запускаете Codex CLI один раз с настройками по умолчанию;
• если различается только один параметр и его проще явно указать отдельным флагом;
• если профиль ещё не создан и команда не должна молча работать с другим режимом;
• если настройки должны быть полностью видны прямо в CI-команде.

Потребность	Профиль подходит?	Обоснование
Переключать несколько настроек одновременно	Да	Профиль избавляет от длинной команды
Передать один временный параметр	Не всегда	Иногда проще использовать отдельный флаг
Сделать режим понятным коллегам	Да	Имя профиля описывает назначение запуска
Спрятать секреты	Нет	Профиль не является хранилищем секретов

Примеры использования

В этом разделе собраны типовые сценарии — от самого простого запуска до сочетания профиля с другими параметрами. В примерах используются условные имена профилей; при необходимости замените их на названия из собственной конфигурации.

Запуск с рабочим профилем

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

codex --profile work

Такая команда запускает Codex с настройками, собранными в секции [profiles.work].

Запуск с коротким флагом

Короткий вариант удобен в интерактивной работе, когда команда запускается часто и длинная форма начинает занимать лишнее место.

codex -p work

Флаги -p и --profile функционально равнозначны. Лучше выбрать один стиль и придерживаться его в документации команды.

Безопасный анализ без записи

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

codex --profile readonly

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

Проверка pull request

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

codex -p review

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

Переход в каталог проекта перед запуском

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

cd ~/projects/catalog
codex --profile work

Это уменьшает риск запуска в домашней директории или в соседнем проекте.

Выбор профиля и модели

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

codex --profile work --model gpt-5

Используйте этот вариант только в том случае, если установленная версия Codex CLI поддерживает параметр --model и выбранная модель доступна вашей учётной записи.

Одноразовое изменение режима подтверждений

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

codex --profile work --ask-for-approval on-request

Названия значений и самого параметра зависят от версии CLI. Проверяйте актуальную справку командой codex --help.

Использование профиля в shell-скрипте

Если запуск повторяется, имя профиля можно вынести в переменную. Это удобно для локальных скриптов, но важно не скрывать от пользователя смысл режима.

CODEX_PROFILE="review"
codex --profile "$CODEX_PROFILE"

В скриптах лучше проверять, что переменная не пуста: иначе команда может завершиться ошибкой или повести себя не так, как ожидается.

Профиль в CI-пайплайне

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

codex --profile ci

Не следует автоматически переносить в CI профиль с расширенными правами. В автоматизации ошибка особенно неприятна: человек не сидит рядом и не остановит действие в нужный момент.

Проверка доступных параметров

Перед настройкой профилей полезно посмотреть справку конкретной версии Codex CLI.

codex --help

В справке можно проверить наличие --profile, его короткого аналога -p, а также связанных параметров.

Диагностика после выбора профиля

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

codex -p work

codex --help

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

Задача	Команда	Ожидаемый результат
Полная форма	codex --profile work	Запуск с профилем work
Короткая форма	codex -p work	Тот же профиль
Работа из проекта	cd project && codex -p work	Запуск в выбранном каталоге
Профиль для ревью	codex -p review	Использование настроек ревью

Чем отличается от других команд и флагов

--profile часто путают с параметрами, которые тоже меняют поведение Codex CLI. Главное различие в том, что профиль выбирает набор настроек, а остальные флаги обычно меняют один конкретный аспект текущего запуска.

--model

Флаг --model выбирает модель, но не задаёт остальные параметры среды. Он не заменяет профиль, если вместе с моделью нужно изменить режим песочницы, подтверждения или другие настройки.

codex --model gpt-5

Сравнение:

Флаг	Что меняет	Когда выбирать
--profile	Набор связанных настроек	Когда нужен готовый режим работы
--model	Выбранную модель	Когда нужно изменить только модель

--config

Флаг --config обычно предназначен для передачи или переопределения отдельных конфигурационных значений из командной строки. Это более точечный механизм, тогда как --profile выбирает заранее названную конфигурацию.

codex --profile work --config model="gpt-5"

Синтаксис передачи конфигурации может различаться между версиями, поэтому уточняйте его через codex --help.

--sandbox

Параметр --sandbox отвечает за режим ограничения доступа к окружению. Профиль может содержать такой параметр, но сам профиль шире: он способен объединять режим песочницы с моделью и политикой подтверждений.

codex --sandbox read-only

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

--ask-for-approval

Этот параметр определяет, когда Codex должен запрашивать подтверждение действий. Он регулирует согласования, но не обязательно меняет доступ к файловой системе или выбранную модель.

codex --ask-for-approval on-request

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

Параметр	Область влияния	Пример вопроса
--profile	Комбинация настроек	«Какой режим работы мне нужен?»
--model	Модель	«Какую модель использовать?»
--config	Конкретное значение конфигурации	«Как переопределить один параметр?»
--sandbox	Ограничения окружения	«Можно ли записывать файлы?»
--ask-for-approval	Запросы подтверждения	«Когда спрашивать разрешение?»

Типичные ошибки

Ошибки при работе с --profile обычно связаны не с самим флагом, а с несоответствием между именем, конфигурацией и ожиданиями пользователя. Ниже — наиболее распространённые случаи.

Профиль не найден

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

codex --profile produkt

А в файле существует только секция:

[profiles.product]

В этом случае нужно исправить опечатку в команде или переименовать секцию. Имена produkt и product — разные строки.

Профиль создан не в той секции

Иногда вместо правильной секции пишут произвольный заголовок:

[work]
model = "gpt-5"

Если версия Codex CLI ожидает профиль в формате [profiles.work], такая запись не будет распознана как профиль work.

Правильный вариант:

[profiles.work]
model = "gpt-5"

Всегда сверяйте формат с документацией своей версии.

Ожидание, что имя профиля само задаёт права

Название safe, readonly или production не является встроенной политикой безопасности. Это всего лишь имя. Реальные ограничения определяются параметрами внутри профиля.

[profiles.readonly]
sandbox_mode = "workspace-write"

Такой профиль выглядит безопасным, но фактически разрешает запись в рабочую область. Имя не должно заменять проверку содержимого.

Смешивание профилей и ручных переопределений

Пользователь выбирает профиль readonly, а затем добавляет флаг, который меняет режим доступа:

codex --profile readonly --sandbox workspace-write

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

Использование устаревшего имени параметра

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

codex --profile legacy

Если запуск завершается ошибкой, проверьте версию Codex CLI, справку и синтаксис файла конфигурации.

Ошибка	Причина	Что сделать
Профиль не найден	Опечатка или отсутствующая секция	Сверить имя с [profiles.name]
Настройки игнорируются	Неверный формат секции	Проверить структуру TOML
Небезопасное поведение	Имя профиля не соответствует его содержимому	Проверить реальные параметры
Неизвестный параметр	Старая или неподдерживаемая конфигурация	Свериться со справкой текущей версии

Краткая памятка

Флаг --profile нужен для выбора именованного набора настроек Codex CLI. Его короткая форма — -p. Сам флаг не создаёт профиль и не определяет его содержимое: он только указывает, какой профиль следует применить.

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

Действие	Команда или запись
Запустить профиль	codex --profile work
Использовать короткую форму	codex -p work
Создать секцию профиля	[profiles.work]
Посмотреть справку	codex --help
Запустить из нужного проекта	cd project && codex -p work

Перед использованием профилей полезно пройти короткий чек-лист:

• проверить, что установленная версия Codex CLI поддерживает --profile и -p;
• убедиться, что профиль находится в правильном файле конфигурации;
• сверить точное имя профиля;
• проверить режим песочницы и политику подтверждений;
• не хранить в конфигурации открытые секреты;
• не использовать расширенные права в автоматизации без необходимости;
• при спорном поведении временно запустить Codex с минимальным профилем и проверить настройки по одной.

Итоговая схема проста: профиль описывается в конфигурации, выбирается через codex --profile имя или codex -p имя, а отдельные параметры командной строки при необходимости уточняют поведение текущего запуска. Такой подход делает команды короче, режимы работы понятнее, а переключение между безопасным анализом, разработкой, ревью и автоматизацией — заметно предсказуемее.