config.toml и профили Codex: 6 слоёв приоритета и запретные ключи проекта

Вы поставили Codex, поработали неделю и заметили, что каждый запуск начинается одинаково: переключить модель, поднять уровень рассуждений, разрешить запись в папку, а на чужом репозитории — наоборот, всё запретить. Это не тот случай, когда нужно объяснять агенту словами. Это настройки среды, и они живут в одном файле — config.toml.

Коротко (TL;DR)

config.toml — файл настроек Codex в формате TOML: какую модель брать, как глубоко думать, что агенту позволено трогать, через какого провайдера идти. Проверено по официальной документации Codex 11 августа 2026.

• Файлов не один, а несколько. Пользовательский ~/.codex/config.toml, проектный .codex/config.toml внутри репозитория и системный /etc/codex/config.toml. Профиль — тоже отдельный файл.
• Слоёв приоритета шесть. Сверху флаги командной строки, внизу встроенные дефолты. Проектный конфиг стоит ВЫШЕ профиля — и почти все гайды в выдаче говорят обратное.
• Профиль — это файл ~/.codex/<имя>.config.toml, включается флагом --profile <имя>. Старые таблицы [profiles.имя] внутри общего конфига сняты в версии 0.134.0 от 26 мая 2026.
• Строка profile = "имя", оставшаяся с прошлых версий, не даёт CLI запуститься вообще — это самая дорогая ошибка в теме, и в гайдах о ней не написано.
• Проектный конфиг урезан намеренно. Десять ключей он не переопределяет никогда: провайдер, базовые URL, уведомления, телеметрия, выбор профиля. Иначе склонированный чужой репозиторий молча уводил бы ваши запросы и API-ключ на чужой эндпоинт.
• Доступ задаётся двумя несовместимыми способами — новыми профилями разрешений или старой парой sandbox_mode/sandbox_workspace_write. Документация запрещает смешивать их в одном файле.

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

Где лежит config.toml и какие три файла Codex читает

Начнём с вопроса «где файл», потому что путаница начинается уже здесь: файл не один.

BYBIT EARNЗаставь крипту работатьПроценты на USDT и BTC без блокировки — деньги остаются под рукой.Разместить

• Пользовательский — ~/.codex/config.toml. Ваши личные настройки для всех проектов. Каталог появляется после установки Codex CLI; на Windows это %USERPROFILE%\.codex\. Каталог целиком переносится переменной окружения CODEX_HOME — удобно, когда конфиг лежит в дотфайлах.
• Проектный — .codex/config.toml внутри репозитория. Командные договорённости, которые едут вместе с кодом. Codex идёт от корня проекта вниз к вашей текущей папке и подбирает каждый найденный файл; ближайший к папке главнее. Важная оговорка: этот слой читается только у доверенного проекта, о доверии — отдельный раздел ниже.
• Системный — /etc/codex/config.toml на Unix-машинах, если он там есть. Это уровень администратора, а не разработчика.
• Файл профиля — ~/.codex/<имя>.config.toml, рядом с основным конфигом. Он не заменяет пользовательский конфиг, а накладывается на него.

Два практических нюанса, на которых спотыкаются даже опытные:

Окружение облачных задач Codex: setup-скрипт, кэш и доступ в интернет

MCP-серверы в Codex: config.toml, транспорты и отладка молчащего сервера

Сессия Codex CLI на час работы: команды, расход контекста и откат через git

Codex CLI против Codex Cloud: десять критериев выбора под задачу

DeepSeek Harness вышел под MIT: открытый каркас ИИ-агентов, где всё плагин

Порядок строк в TOML значим. Ключи верхнего уровня (model, approval_policy, sandbox_mode) обязаны стоять ДО первой таблицы в квадратных скобках. Если вы дописали model = "..." в конец файла после блока [model_providers.proxy], TOML прочитает эту строку как ключ внутри таблицы провайдера, а не как настройку модели. Ошибка выглядит как «конфиг не применился».

Редактор умеет подсказывать ключи. Добавьте первой строкой файла ссылку на официальную JSON-схему конфига — и VS Code или Cursor начнут дополнять имена ключей и подсвечивать опечатки:

#:schema https://developers.openai.com/codex/config-schema.json

model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

Схема живая: на 11 августа 2026 она отдаётся по этому адресу в формате JSON Schema draft-07 и содержит определения вроде ConfigProfile, AskForApproval и HooksToml. Ни один разбор из первой десятки выдачи про эту строку не упоминает, хотя она экономит больше времени, чем любой готовый шаблон.

И сразу разграничение, без которого дальше будет каша. В проекте рядом лежит второй файл — AGENTS.md. Он про что агенту знать о вашем проекте: какой командой гонять тесты, куда не лезть, в каком стиле писать код. config.toml — про как запускать самого агента: модель, глубина рассуждений, права, провайдер. Инструкции — в AGENTS.md, среда — в config.toml. Ключ project_doc_max_bytes (по умолчанию 32 768 байт, то есть 32 KiB) — единственное место, где эти два файла соприкасаются: он ограничивает, сколько текста инструкций Codex вчитывает.

Шесть слоёв приоритета: какой конфиг Codex перебивает какой

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

В корпоративной установке сверху добавляется ещё один уровень — административные требования в requirements.toml, которые пользовательские слои перебить не могут. На личной машине его обычно нет.

BYBIT EARNЗаставь крипту работатьПроценты на USDT и BTC без блокировки — деньги остаются под рукой.Разместить

Теперь самое неприятное. Строки 2 и 3 в популярных гайдах переставлены местами, причём в обе стороны: один известный разбор ставит профиль выше проектного конфига, другой — ниже («между пользовательским и проектным»), третий вообще утверждает, что проектные настройки побеждают всегда, и не упоминает флаги CLI. Официальный справочник ставит проектный конфиг выше профиля, и в спорной ситуации я опираюсь на него, а не на пересказ. Практический вывод из этого расхождения важнее самого порядка: проверяйте результат на своей машине, а не полагайтесь на цепочку из статьи — как именно, разберём в разделе про проверку.

Разовое переопределение делается флагом -c (он же --config), принимает пару в синтаксисе TOML и повторяется сколько нужно:

codex -c model_reasoning_effort="high" -c sandbox_mode="read-only" "проверь миграции"

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

Ключи config.toml, которые реально меняют поведение агента

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

Что стоит держать в голове по трём самым ходовым ключам.

model и model_reasoning_effort — пара, а не два независимых переключателя. Дешёвая модель с xhigh и дорогая с low дают разный результат при похожем счёте. Какую модель брать под какую задачу, разобрано отдельно в материале про выбор модели Codex; здесь важно, что оба ключа можно закрепить за сценарием через профиль и не трогать руками.

sandbox_mode и approval_policy — два разных регулятора. Первый задаёт, что агенту вообще доступно; второй — когда он спросит разрешение. Смысл каждого значения и безопасные комбинации подробно разобраны в материале про режимы одобрения и песочницу Codex — в этом уроке я показываю только, как их записать в файл.

model_provider упирается в аутентификацию. Блок провайдера объявляется так:

model = "your-model-id"
model_provider = "custom_provider"

[model_providers.custom_provider]
name = "Custom Provider"
base_url = "https://api.example.com/v1"
env_key = "CUSTOM_API_KEY"
wire_api = "responses"

Ключ env_key — имя переменной окружения, из которой берётся API-ключ; сам ключ в файл не пишем никогда. Как Codex вообще получает доступ — через вход в ChatGPT или через API-ключ — разобрано в материале про аутентификацию Codex. Встроенных провайдеров три: openai, ollama и lmstudio, последние два — для локальных моделей.

Отдельно про MCP: подключение внешних инструментов и сервисов тоже объявляется в этом файле, блоками [mcp_servers.<имя>] с транспортом stdio или streamable HTTP. Тема большая и заслуживает своего разбора — разбираем отдельно в уроке про MCP в Codex, здесь достаточно знать, что механизм живёт в том же config.toml и подчиняется тем же шести слоям приоритета.

Именованные профили Codex: отдельный файл на каждый сценарий

Профиль — это именованный набор настроек под сценарий работы. Механика на 11 августа 2026 такая:

1. Создайте файл ~/.codex/<имя>.config.toml рядом с основным конфигом. Имя допускает буквы, цифры, дефис и подчёркивание: deep-review, ci, quick.
2. Пишите в него ключи верхнего уровня — ровно так же, как в основном конфиге. Никаких [profiles.deep-review]: официальная документация прямо просит не вкладывать ключи под такую таблицу.
3. Перечислите только то, что отличается. Остальное профиль наследует из ~/.codex/config.toml.
4. Включайте флагом codex --profile deep-review (короткая форма -p). Работает и с неинтерактивным запуском: codex exec --profile ci "прогони тесты".

Файл профиля выглядит буднично — и это правильно:

model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"

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

Что важно знать про активацию: она всегда явная. Автоматического «профиля по умолчанию» через строку в конфиге больше нет — об этом подробно в разделе про поломки. Часть сторонних гайдов упоминает переменную окружения CODEX_PROFILE; в официальном справочнике ключей и в описании профилей её нет, поэтому в CI я закладываю флаг --profile, а не переменную.

Три готовых профиля: быстрые правки, рефакторинг, ревью без записи

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

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

model_reasoning_effort = "low"
model_verbosity = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
personality = "pragmatic"

Почему так: low на рассуждениях и подробности — потому что задача механическая, и высокий уровень здесь только увеличивает счёт и время. on-request оставляет агента самостоятельным внутри песочницы, но останавливает перед выходом за её пределы. cached держит поиск на индексе OpenAI без выхода в интернет — для правки опечатки живой поиск не нужен.

Профиль 2 — тяжёлый рефакторинг. Много файлов, неочевидные связи, цена ошибки высокая.

model_reasoning_effort = "xhigh"
model_verbosity = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
writable_roots = []
network_access = false

Почему так: xhigh — единственное место, где максимальное усилие оправдано счётом. model_verbosity = "low" при этом оставляет вывод коротким: думать глубоко и пересказывать многословно — разные вещи. network_access = false явно фиксирует, что рефакторинг не ходит в сеть (в режиме workspace-write сеть и так выключена по умолчанию, но в профиле, который поедет в команду, лучше написать это явно). writable_roots — список дополнительных путей, куда разрешена запись помимо рабочей папки; пустой список означает «только рабочая папка».

Профиль 3 — ревью без записи. Агент читает код и пишет заключение, но не меняет ни байта.

model_reasoning_effort = "high"
approval_policy = "never"
sandbox_mode = "read-only"
web_search = "cached"

Почему так: read-only физически запрещает запись, поэтому approval_policy = "never" здесь безопасен — спрашивать не о чем, испортить нечего, а работа идёт без остановок. Это единственная комбинация из трёх, где never уместен: с правом записи он означал бы «делай что хочешь, не спрашивая». Пара значений та же, что в разборе режимов у сценария неинтерактивного запуска в CI, — и это не совпадение: сценарии разные (там смысл режимов, здесь оформление их в профиль), а безопасная комбинация для работы без вопросов и без записи одна.

Запуск, соответственно: codex -p quick, codex -p deep, codex -p review. Одно замечание: во всех трёх профилях доступ задан через sandbox_mode. Если вы перешли на профили разрешений, эти строки в них писать нельзя — почему, ниже.

Почему проектный .codex/config.toml не сменит вам провайдера

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

Первый — доверие. Проектные слои .codex/ (а вместе с конфигом это ещё хуки и правила) читаются только у проекта, который вы отметили как доверенный; решение хранится в вашем пользовательском конфиге как trust_level в блоке [projects]. В версии 0.147.0 от 7 августа 2026 требование явного доверия для незнакомых локальных проектов дополнительно усилили. Практический смысл: «доверяю» для чужого репозитория — это не формальность, а решение о безопасности, и принимать его стоит после чтения того, что в .codex/ лежит.

Второй — список запретных ключей. Даже у доверенного проекта десять ключей игнорируются. Документация формулирует это прямо: Codex игнорирует перечисленные ключи в проектном .codex/config.toml и печатает предупреждение при старте, когда их видит.

Логика запрета читается с одного взгляда на таблицу. Если бы репозиторий мог задать model_provider и base_url, то достаточно было бы склонировать чужой проект — и ваши запросы вместе с ключом из env_key ушли бы на чужой эндпоинт, а вы бы этого не заметили: агент работает, ответы приходят. Если бы он мог задать notify, то получил бы право запускать произвольную команду на вашей машине по событию. Именно поэтому граница проведена не по «удобно/неудобно», а по «кто платит и кто владеет секретами». Это не ограничение ради ограничения, а единственное место в файле, где решение принято за вас — и правильно принято.

Одна оговорка про поверхности: проектные разрешения на разных клиентах Codex ведут себя не одинаково. В трекере есть открытая заявка о том, что настольное приложение Codex не применяет проектный default_permissions из .codex/config.toml. Вывод рабочий: если настройка критична для безопасности, не полагайтесь на то, что все клиенты прочитают её одинаково, — проверяйте на той поверхности, где работаете.

Доступ в config.toml задают двумя способами, и смешивать нельзя

В файле сосуществуют две системы прав, и это главная ловушка при копировании чужих примеров.

Старая пара — sandbox_mode плюс уточняющий блок [sandbox_workspace_write] (writable_roots, network_access, исключения для /tmp и $TMPDIR). Именно её вы видели в трёх профилях выше.

Новая система — профили разрешений: ключ default_permissions называет активный профиль, а сами профили объявляются таблицами [permissions.<имя>] с разделами filesystem и network. Встроенных профилей три: :read-only (локальные команды только читают), :workspace (запись внутри рабочих корней и системного временного каталога) и :danger-full-access (локальная песочница снимается). Свой профиль удобно наращивать от встроенного через extends:

default_permissions = "workspace-net"

[permissions.workspace-net]
extends = ":workspace"

[permissions.workspace-net.network.domains]
"api.openai.com" = "allow"

Наследоваться от :danger-full-access Codex не даёт, неизвестных родителей и циклы в наследовании тоже отвергает — то есть «расширить полный доступ» через профиль не получится.

А теперь правило, которого нет ни в одном разборе из выдачи. Документация Codex говорит буквально: профили разрешений не совмещаются со старыми настройками песочницы, настраивайте либо default_permissions и [permissions], либо sandbox_mode и sandbox_workspace_write, но не оба. Это значит, что типовой «сборный» конфиг из чужого гайда, где рядом стоят default_permissions = ":workspace" и sandbox_mode = "workspace-write", — не «настройка с запасом», а файл с неопределённым поведением. Выбирайте одну систему на весь конфиг и все его профили.

Как проверить, какие настройки Codex применил на самом деле

Шесть слоёв — это шесть мест, где ваша настройка могла потеряться. Порядок проверки, от дешёвого к дорогому:

1. Прочитайте предупреждения при старте. Запретный ключ в проектном конфиге, сломанный TOML, снятый синтаксис — Codex сообщает об этом в первых строках вывода. Их привычно проматывают.
2. Спросите сессию. Slash-команда /status показывает конфигурацию текущей сессии; это самый быстрый способ увидеть, какая модель и какие права реально активны. Она и остальные команды управления сессией разобраны в материале про рабочий цикл Codex CLI.
3. Проверьте гипотезу флагом. Запустите то же задание с -c ключ="значение". Поведение изменилось — значит, ключ верный, а ваш файл перебивается слоем выше или лежит не там. Не изменилось — дело не в этом ключе.
4. Убедитесь, что профиль вообще подхватился. Имя в --profile должно совпадать с именем файла: --profile deep читает ~/.codex/deep.config.toml. Опечатка в имени — самая частая причина «профиль не работает».
5. Проверьте, что смотрите в тот файл. Если задана переменная CODEX_HOME, ваш конфиг лежит не в ~/.codex/, а там, куда она указывает.

Риски config.toml: снятый синтаксис профилей и тихие отказы

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

Строка profile = "имя" не даёт CLI запуститься. С релиза 0.134.0 от 26 мая 2026 флаг --profile стал единственным способом выбрать профиль: таблицы [profiles.имя] внутри общего конфига и селектор profile = "имя" больше не поддерживаются. Отказ жёсткий — не предупреждение, а ошибка загрузки конфигурации, после которой Codex не стартует. Текст ошибки прямо называет и проблему, и лечение: legacy profile = "openai-chatgpt" config is no longer supported; use --profile openai-chatgpt with openai-chatgpt.config.toml instead. Заявка #24858 в трекере Codex на 11 августа 2026 всё ещё открыта, и главная претензия в ней справедлива: обновление ломает инструмент, которым только и можно было бы починить конфиг.

Миграция занимает минуту:

1. Удалите строку profile = "имя" из ~/.codex/config.toml.
2. Перенесите содержимое таблицы [profiles.имя] в новый файл ~/.codex/имя.config.toml — ключами верхнего уровня, без обёртки.
3. Удалите саму таблицу [profiles.имя] из основного конфига и запускайте с --profile имя.

Примеры из первой десятки выдачи учат снятому синтаксису. Я разобрал шесть материалов из первой десятки по ключевым фразам темы, включая самые заметные, и на 11 августа 2026 все шесть показывают профили как таблицы [profiles.имя] внутри config.toml — отдельного файла профиля не показывает ни один из этой шестёрки. Исключение есть, и оно показательное: независимый разбор от 19 июля 2026 уже обновился — он рекомендует именно отдельные файлы вида ~/.codex/review.config.toml и прямо предупреждает не копировать [profiles.review] из старых примеров. То есть отставание гайдов не всеобщее, но в верхних результатах преобладает. Копирование устаревшего примера даёт не «немного устаревший», а неработающий конфиг — а если в примере есть ещё и строка profile =, то и неработающий Codex. Это и есть цена релиза 0.134.0, про который в гайдах не написано.

Запретные ключи игнорируются тихо. Предупреждение при старте есть, но настройка в файле остаётся видимой и выглядит применённой. Читая проектный .codex/config.toml, помните: model_provider в нём — мёртвая строка.

Две системы прав в одном файле дают неопределённый доступ. Разобрано выше: либо профили разрешений, либо sandbox_mode.

Доверие проекту включает больше, чем конфиг. Вместе с ним поднимаются проектные хуки и правила. Отмечая чужой репозиторий доверенным, вы соглашаетесь на всё содержимое .codex/, а не только на модель и права.

Флаги живут недолго. В версии 0.147.0 от 7 августа 2026 удалён устаревший флаг --full-auto — вместо него --sandbox workspace-write. Значение approval_policy = "on-failure" тоже помечено устаревшим. Конфиг, зашитый в CI по прошлогоднему гайду, ломается ровно на таком обновлении.

Что в конфиге Codex устареет первым: имена ключей и флаги

Codex меняется быстро, и по релизам это видно: 0.134.0 (26 мая 2026) снёс профили старого формата, 0.147.0 (7 августа 2026) убрал флаг --full-auto и усилил требование доверия; на 11 августа 2026 в ленте уже лежит альфа 0.148.0.

Что стареет первым:

• Имена и состав моделей в ключе model — быстрее всего остального.
• Имена флагов и значений (--full-auto, on-failure) — снимаются между версиями.
• Дефолты песочницы и одобрений. Здесь источники расходятся уже сейчас: официальный образец конфига содержит sandbox_mode = "read-only" и approval_policy = "on-request", независимые разборы называют дефолтом workspace-write, а справочник ключей фиксированного дефолта не печатает вовсе. Это не повод угадывать: посмотрите /status на своей версии.
• Состав [features] — флаги появляются и включаются по умолчанию.

Что устаревает медленно и на что можно опираться: расположение файлов, шестислойная модель приоритета, разделение «инструкции в AGENTS.md, среда в config.toml» и список ключей, запретных для проектного слоя. Сверяться стоит не с гайдами, а со справочником ключей и лентой релизов — и перечитывать их при мажорном обновлении, а не после того, как CLI перестал запускаться.

FAQ

Где лежит config.toml, если после установки Codex файла нет? Codex не создаёт файл сам — пустой конфиг равнозначен встроенным дефолтам. Создайте ~/.codex/config.toml руками (на Windows — %USERPROFILE%\.codex\config.toml). Каталог ~/.codex появляется при первом запуске и хранит ещё и историю сессий, и логи. Если задана переменная CODEX_HOME, файл нужно положить в указанный ею каталог.

Можно ли держать разные модели и разный уровень рассуждений для разных проектов? Да, двумя способами. Первый — проектный .codex/config.toml в репозитории: ключи model и model_reasoning_effort он переопределять вправе, и это поедет вместе с кодом всей команде. Второй — именованный профиль под тип задачи и запуск codex --profile deep. Первый привязан к папке, второй — к сценарию работы.

Почему Codex перестал запускаться после обновления и пишет про legacy profile? В вашем ~/.codex/config.toml осталась строка profile = "имя". С версии 0.134.0 она не поддерживается, и Codex не стартует. Удалите её, перенесите содержимое таблицы [profiles.имя] в отдельный файл ~/.codex/имя.config.toml ключами верхнего уровня и запускайте с флагом --profile имя.

Профиль и проектный конфиг задают один и тот же ключ — кто победит? По официальному справочнику конфигурации проектный .codex/config.toml стоит выше файла профиля, то есть победит он. Учтите, что распространённые гайды утверждают обратное и противоречат друг другу, поэтому в спорном случае не спорьте с документацией, а посмотрите /status в сессии, запущенной ровно так, как вы её запускаете в работе.

Нужен ли config.toml, если в проекте уже есть AGENTS.md? Нужен, это разные вещи. AGENTS.md объясняет агенту проект: команды, границы, соглашения. config.toml настраивает среду запуска: модель, глубину рассуждений, права на диск и сеть, провайдера. Инструкции без настроек работают, но каждый запуск придётся доводить руками — а именно это и убирает профиль.

Может ли чужой репозиторий через .codex/config.toml увести мой API-ключ? Нет, и это сделано намеренно. Проектный слой читается только у доверенного проекта и вообще не принимает ключи model_provider, model_providers, openai_base_url и chatgpt_base_url — подменить эндпоинт из репозитория нельзя. Но доверие поднимает ещё проектные хуки и правила, поэтому содержимое .codex/ в чужом репозитории стоит прочитать до того, как нажать «доверяю».