config.toml: где лежит и что в нём

Все локальные клиенты Codex — CLI, расширение для IDE и режим Codex в ChatGPT desktop — читают один и тот же формат настроек: TOML-файл config.toml. Разберёмся, сколько таких файлов может быть, кто из них главнее и как понять, откуда взялось значение, которое вы видите в /status.

Где лежат файлы

Личная конфигурация — ~/.codex/config.toml. Точнее, $CODEX_HOME/config.toml: переменная CODEX_HOME по умолчанию указывает на ~/.codex, и в этом же каталоге Codex хранит учётные данные (auth.json, если не используется системное хранилище ключей), историю, логи и кэши.

Проектная конфигурация — .codex/config.toml в репозитории. Их может быть несколько: Codex идёт от корня проекта до текущего каталога и загружает каждый найденный файл. Корень по умолчанию — каталог с .git; изменить это можно ключом project_root_markers.

Есть и системный уровень — /etc/codex/config.toml на Unix, — а в Business и Enterprise администратор может доставлять облачные настройки по умолчанию и жёсткие ограничения через requirements.toml. Ограничения не задают значения, а запрещают их: например, approval_policy = "never" или danger-full-access.

Порядок слоёв

От высшего приоритета к низшему:

Из таблицы следует неочевидное: проектный конфиг сильнее профиля. Если в репозитории записано model = "...", профиль эту модель не перебьёт — только флаг -m. Профили разберём в следующем уроке.

Доверие к проекту

Проектный .codex/ — это код, пришедший к вам из чужого репозитория. Поэтому Codex загружает проектные слои (конфиг, хуки, rules) только для доверенных проектов. Когда вы впервые открываете каталог и подтверждаете доверие, Codex сам дописывает в личный конфиг запись:

[projects."/Users/me/work/site"]
trust_level = "trusted"

Значение "untrusted" отключает проектные слои; личные и системные настройки при этом продолжают действовать.

Даже в доверенном проекте часть ключей игнорируется, а Codex предупреждает об этом при старте: openai_base_url, chatgpt_base_url, model_provider, model_providers, notify, profile, profiles, otel и ещё несколько. Причина — защита от подмены: иначе репозиторий мог бы перенаправить ваши запросы с учётными данными на чужой сервер или запускать команды через уведомления. Провайдеров, уведомления и телеметрию задавайте только в личном конфиге.

Что обычно лежит в личном конфиге

Минимальный рабочий вариант для разработчика агентства:

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

model = "gpt-6.1-sol"              # на октябрь 2026; см. урок про модели
model_reasoning_effort = "medium"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

web_search = "cached"              # по умолчанию; 5, 6, 7
file_opener = "vscode"             # куда открывать ссылки на файлы: cursor, windsurf, none

[shell_environment_policy]
inherit = "core"
ignore_default_excludes = false    # убирать из окружения команд *KEY*, *SECRET*, *TOKEN*

[shell_environment_policy.filters]
"AWS_*" = "exclude"

[tui]
notifications = true

Строка #:schema в начале даёт автодополнение и подсветку ошибок в VS Code и Cursor с расширением Even Better TOML.

Обратите внимание на shell_environment_policy. По умолчанию ignore_default_excludes = true, то есть переменные с KEY, SECRET и TOKEN в имени не вычищаются автоматически из окружения команд, которые запускает агент. Если в вашей оболочке экспортированы токены GitLab или ключи API, имеет смысл включить фильтр явно.

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

Что класть в проектный конфиг

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

review_model = "gpt-6.1-sol"

[sandbox_workspace_write]
network_access = false

Относительные пути внутри проектного конфига (например, model_instructions_file) считаются от каталога .codex/, в котором лежит файл.

Разовые переопределения

Для одного запуска не нужно править файлы. Если для ключа есть отдельный флаг, используйте его (--model, --sandbox), для остального — -c:

codex -c model_reasoning_effort='"high"'
codex -c sandbox_workspace_write.network_access=true
codex -c 'shell_environment_policy.include_only=["PATH","HOME"]'
codex -c mcp_servers.context7.enabled=false

Значение после = разбирается как TOML, вложенные ключи пишутся через точку. Если значение не разобралось как TOML, Codex берёт его как строку, поэтому строки надёжнее брать в кавычки и защищать от оболочки одинарными. Флаги --enable имя и --disable имя — короткая запись для -c features.имя=true/false.

Как понять, что применилось

• /status в TUI — активная модель, политика одобрений, каталоги на запись, расход токенов.
• /debug-config — все слои конфигурации по порядку и источники ограничений. Это первое, что стоит открыть, когда значение «не то».
• codex --strict-config — завершиться с ошибкой, если в файле есть ключи, неизвестные этой версии. Помогает поймать опечатку или ключ, который переименовали.
• codex features list — экспериментальные и стабильные функции с их текущим состоянием; codex features enable имя записывает флаг в ~/.codex/config.toml.
• codex -c log_dir=./.codex-log — включить текстовый лог codex-tui.log в указанном каталоге.

Если вы читали старые инструкции

• approval_policy = "untrusted" больше не поддерживается и может помешать клиенту запуститься; on-failure устарел. Остались on-request, never и гранулярная политика. Строгий режим «спрашивать всё» теперь получают через trust_level = "untrusted" у проекта.
• Таблицы [profiles.имя] внутри config.toml с версии 0.134.0 не читаются — профили переехали в отдельные файлы.
• Ключ experimental_instructions_file переименован в model_instructions_file.