Песочница Codex задает техническую границу для локальных команд: какие файлы они могут изменять и доступна ли им сеть. approval_policy решает другой вопрос — когда Codex должен остановиться и попросить подтверждение для выхода за границу. Эти механизмы работают вместе, но не заменяют друг друга. По официальной документации Sandbox, те же ограничения наследуют запущенные агентом git, пакетные менеджеры, test runners и другие процессы.
Для обычной локальной разработки разумная отправная точка — workspace-write вместе с on-request: внутри рабочей области агент выполняет рутинные действия, а при реальном выходе за границу может запросить подтверждение. read-only подходит для анализа. danger-full-access снимает ограничения файловой системы и сети; это осознанное доверие хосту, а не стандартный способ исправить ошибку. Отдельно, approval_policy = "never" означает отсутствие запросов, но сам по себе не дает полный доступ.
После этого уже имеет смысл искать владельца настройки. Личные значения Codex находятся в ~/.codex/config.toml. Доверенный репозиторий может добавлять .codex/config.toml, а повторяемый режим лучше оформить отдельным profile-файлом. Такой порядок не превращает одну проблему прав в одновременную замену provider, модели, сети и MCP.
Перед изменением сохраните копию только того файла, который собираетесь редактировать. Удалять весь каталог ~/.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 и храните такие значения на пользовательском уровне.
Сначала выберите границу, затем уровень автономии
Рабочая база может состоять всего из двух строк:
tomlapproval_policy = "on-request" sandbox_mode = "workspace-write"
У этих значений разные обязанности:
| Контроль | Что он определяет | Чего он не гарантирует |
|---|---|---|
sandbox_mode | Доступ команд к файлам и сети | Появится ли запрос подтверждения |
approval_policy | Когда остановиться и спросить | Что действие технически разрешено |
approvals_reviewer | Кто рассматривает допустимый approval | Изменение границы песочницы |
Текущая документация перечисляет read-only, workspace-write и danger-full-access, а для approvals — untrusted, on-request и never. В CLI активный профиль можно выбирать через /permissions; в IDE и desktop app используется control под composer. Набор видимых пунктов зависит от версии и политики организации, поэтому проверяйте How permissions work, а не старый screenshot.
Если нужен только второй репозиторий, добавьте конкретный writable root вместо полного доступа:
tomlsandbox_mode = "workspace-write" approval_policy = "on-request" [sandbox_workspace_write] writable_roots = ["/absolute/path/to/second-repo"] network_access = false
Не используйте домашний каталог или корень диска как универсальную writable область. network_access относится к исходящей сети процессов внутри sandbox. Он не управляет web search, apps, MCP и remote browser. Поэтому работающий web search не доказывает, что npm install или приложение внутри теста имеет доступ в интернет.
ОС определяет, как именно создается песочница
Цель одна, но реализация платформенная. В актуальном разделе Getting started указано:
| Среда | Механизм | Что проверить первым |
|---|---|---|
| macOS | встроенный Seatbelt | Находится ли путь внутри разрешенной области |
| Native Windows | нативная Windows sandbox Codex | Setup sandbox и политика устройства |
| WSL2 | Linux-реализация | WSL2 и наличие bubblewrap |
| Linux | bubblewrap и системная изоляция | bwrap, user namespace, AppArmor |
Ubuntu/Debian:
bashsudo apt install bubblewrap
Fedora:
bashsudo dnf install bubblewrap
Если после установки остается предупреждение о user namespace или AppArmor, выполните шаги для своего дистрибутива из официальной документации. Не отключайте системное ограничение первым действием. В Docker внешний контейнер может блокировать namespace или seccomp, необходимые bwrap. Сначала докажите изоляцию контейнера, и только затем решайте, нужен ли внутри него более широкий режим Codex; на bare host это уже другое решение о риске.
Profiles больше не живут внутри основной таблицы
Режим для осторожного аудита можно вынести отдельно:
toml# ~/.codex/audit.config.toml model_reasoning_effort = "xhigh" approval_policy = "on-request" sandbox_mode = "read-only"
Запуск:
bashcodex --profile audit
Profile должен содержать только отличия. Формат profile меняется между версиями клиента, поэтому перед копированием старого примера с [profiles.name] сверяйтесь с актуальным 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 | Добавлять другие поля «для полноты» |
| Repo читается, но файл не меняется | Активный sandbox и точный workspace root | Сразу включать danger-full-access |
| Package manager или API test не выходит в сеть | Sandbox command network, proxy/DNS и approval | Считать web search доказательством сети процесса |
| Native Windows не создает sandbox | Native/WSL2 маршрут и policy устройства | Смешивать Windows Sandbox, VM и Codex sandbox |
| 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. Это политика, а не задача выбора более сильного локального слоя.
Хорошее изменение имеет один наблюдаемый результат. Сначала докажите чтение, затем одну запись внутри workspace и проектный test. Только после этого проверяйте действительно нужный внешний каталог или сеть. Так можно отделить непрочитанный config от корректного отказа sandbox, отсутствующего approval и неспособности ОС создать песочницу — и не менять одновременно model, provider, permissions и MCP.
Если вопрос уже не о настройке, а о выборе инструмента для разработки, используйте отдельное сравнение Claude Code и Codex. config.toml не решает продуктовую задачу.
