config.toml не должен становиться коллекцией случайных фрагментов из инструкций по прокси, Azure, локальным моделям и MCP. Файл может оставаться синтаксически корректным, но одновременно выбирать не тот provider, снимать защитные ограничения и запускать ненужный процесс. Поэтому надежная настройка Codex начинается не с шаблона, а с вопроса: кому принадлежит конкретное решение?
Личные значения Codex находятся в ~/.codex/config.toml. Доверенный репозиторий может добавлять .codex/config.toml, а повторяемый режим лучше оформить отдельным profile-файлом. CLI и IDE используют общие слои на одном хосте. Точные расположения и область действия описаны в официальном разделе Config basics.
Перед изменением сохраните копию только того файла, который собираетесь редактировать. Удалять весь каталог ~/.codex из-за одной ошибочной таблицы опасно: вместе с ней можно потерять исправные профили, правила и локальное состояние авторизации.
Конфигурация — это порядок ответственности
Обычные значения применяются сверху вниз:
- флаги CLI и
--config; .codex/config.tomlв доверенном проекте, причем ближайший к текущей директории файл выигрывает;- profile, выбранный через
--profile; - пользовательский
~/.codex/config.toml; - системный
/etc/codex/config.tomlна Unix, если он существует; - встроенные значения Codex.
Этот порядок закреплен в официальной схеме Configuration precedence. Если модель или sandbox «не меняются», сначала ищите более высокий слой, а не переписывайте пользовательский файл.
Практическое распределение выглядит так:
| Задача | Подходящий слой | Причина |
|---|---|---|
| Обычная модель, reasoning, личные MCP и уведомления | Пользовательский | Действует в разных проектах |
| Граница выполнения для одного репозитория | Доверенный проект | Политика следует за кодом |
| Повторяемый read-only или deep-review режим | Отдельный profile | Не дублирует базовый файл |
| Один эксперимент | CLI override | Не превращается в постоянную политику |
| Обязательное правило организации | Managed requirements | Пользователь не может его обойти |
Не все ключи разрешено переносить в проект. Machine-local настройки provider, авторизации, выбора profile, уведомлений и telemetry нельзя переопределить из проекта. В актуальном списке есть model_provider, model_providers, profile и otel. Проверяйте полный перечень в Configuration reference и храните такие значения на пользовательском уровне.
Минимальный файл легче доказать
Для личной работы достаточно небольшого основания:
tomlmodel = "gpt-5.6" model_reasoning_effort = "high" approval_policy = "on-request" sandbox_mode = "workspace-write" web_search = "cached"
Модель в примере — изменяемый идентификатор, а не обещание доступности. Убедитесь, что текущая версия клиента и ваш маршрут действительно ее предоставляют. Если стандартное значение вас устраивает, не закрепляйте его без необходимости.
approval_policy отвечает за момент запроса подтверждения, а sandbox_mode — за доступ команды к файловой системе и сети. Это разные барьеры. OpenAI приводит workspace-write вместе с on-request как более осторожный вариант локальной автоматизации. Комбинация danger-full-access и never убирает оба ограничения; она не подходит в качестве бытового значения «чтобы не спрашивал». Определения режимов находятся в Sandbox: Configure defaults.
Настройка интернета тоже независима. Верхнеуровневый web_search сейчас принимает cached, indexed, live и disabled. Старые feature flags для web search помечены как устаревшие. Актуальный набор нужно сверять с Config basics, а не с сохраненным чужим файлом.
Profiles больше не живут внутри основной таблицы
Режим для осторожного аудита можно вынести отдельно:
toml# ~/.codex/audit.config.toml model_reasoning_effort = "xhigh" approval_policy = "on-request" sandbox_mode = "read-only"
Запуск:
bashcodex --profile audit
Profile накладывается поверх пользовательского файла и должен содержать только отличия. Начиная с Codex 0.134.0, --profile больше не читает [profiles.audit] из основного config.toml, а верхнеуровневый селектор profile = "audit" не поддерживается. Текущий формат приведен в Advanced Config: Profiles.
Provider не исправляет доступ, а TOML не проверяет сеть
Маршрут provider следует рассматривать как отдельный контракт: значение model_provider должно указывать на существующую таблицу, credential должен быть виден процессу, endpoint — доступен, а модель — поддерживаться этим маршрутом. Ошибка региональной доступности, учетной записи или сети не превращается в синтаксическую проблему config.toml только потому, что появилась после редактирования.
Не храните секрет в репозитории и не вставляйте его в обращение за поддержкой. Если поле поддерживает ссылку на переменную окружения, используйте имя переменной и отдельно проверяйте, видит ли ее процесс CLI или IDE. Ситуация «CLI работает, IDE не работает» часто означает различие окружений, а не неверную TOML-таблицу.
Для Azure существует отдельный provider-контракт; универсальная статья не должна смешивать deployment name, Azure endpoint и общий локальный baseline. Сначала докажите общий слой, затем используйте документацию конкретного маршрута.
MCP проходит четыре проверки
Для STDIO server конфигурация может выглядеть так:
toml[mcp_servers.docs] command = "docs-server" args = ["--read-only"] env_vars = ["DOCS_TOKEN"] startup_timeout_sec = 20 tool_timeout_sec = 60 enabled = true
Для streamable HTTP:
toml[mcp_servers.tasks] url = "https://mcp.example.internal/mcp" bearer_token_env_var = "TASKS_MCP_TOKEN" enabled = true
Официальное руководство Model Context Protocol разделяет STDIO и streamable HTTP, описывает OAuth, environment headers, timeout и списки инструментов.
Проверяйте по порядку:
- Codex разобрал таблицу;
- команда запускается или URL доступен;
- credential/OAuth принят;
- конкретный tool отвечает корректно.
Начать можно с команд, которые показывает установленная версия:
bashcodex mcp list codex mcp --help
Для OAuth-сервера предусмотрен codex mcp login <server-name>. Наличие записи в mcp list не означает, что процесс стартовал или удаленная сторона приняла токен.
Диагностика начинается с первого недоказанного слоя
Новые версии CLI предлагают --strict-config и doctor. Их наличие нужно проверить локально:
bashcodex --version codex --help codex doctor --help
Если опции присутствуют, выполните read-only проверку:
bashcodex --strict-config doctor --summary
Strict mode помогает обнаружить неизвестные текущей версии поля. doctor диагностирует установку, config, auth и runtime. Но даже успешный отчет не заменяет запрос к provider или вызов MCP tool.
| Симптом | Что доказать первым | Что не стоит делать |
|---|---|---|
| Значение игнорируется только в одном repo | Trust и ближайший project config | Удалять user config |
| CLI видит ключ, IDE — нет | Окружение процесса IDE | Записывать secret прямо в TOML |
| Unknown field при запуске | Версию и текущий reference | Добавлять другие поля «для полноты» |
| MCP виден, но не отвечает | Процесс/URL, auth, timeout, tool | Считать список health check |
| Высокий доступ запрещен на рабочем устройстве | Managed requirements | Переносить тот же запретный ключ в другой файл |
| После provider-правки остается connection error | DNS, proxy, endpoint, credential | Менять синтаксис без сетевой проверки |
В управляемой среде requirements.toml может ограничивать approval, permission profiles, web search, разрешенные MCP, plugins и features. При конфликте клиент использует совместимое значение и сообщает об ограничении. Подробности есть в Admin-enforced requirements. Это политика, а не задача выбора более сильного локального слоя.
Хорошее изменение имеет один наблюдаемый результат. Выберите владельца, сохраните копию, отредактируйте один блок, проверьте parsing и приоритет, затем выполните безопасное действие, на котором новая настройка видна. Если оно не сработало, вернитесь к первому недоказанному уровню — так быстрее, чем одновременно менять model, provider, permissions и MCP.
Если вопрос уже не о настройке, а о выборе инструмента для разработки, используйте отдельное сравнение Claude Code и Codex. config.toml не решает продуктовую задачу.
