Песочница Codex: профили разрешений и доступ к npm
Сохраните ограничения рабочей области Codex и разрешите доступ к реестру пакетов. Настройте профиль разрешений и сетевой прокси, проверьте разрешённые и запрещённые операции. Узнайте, какие файлы остаются доступными для чтения, как работают ограничения ОС и корпоративные требования к профилям.
Содержание

Если Codex правит файлы репозитория, но не может скачать пакеты npm, сначала проверьте профиль разрешений песочницы, а не настройки API. Встроенный профиль :workspace запрещает командам доступ к сети, поэтому с этим сталкиваются разработчики, устанавливающие зависимости в локальных сессиях Codex. Создайте профиль на основе :workspace, включите сетевой прокси и разрешите домен реестра вместо перехода к полному доступу.
По состоянию на 2026-11-19 OpenAI помечает профили разрешений как бета-функцию. Ниже описана настройка локального запуска команд с примерами для Bash в macOS, Linux и WSL2.
Что разрешает стандартный профиль рабочей области?
Если корнем рабочей области служит Git-репозиторий, :workspace разрешает командам в песочнице менять исходники, но защищает отдельные каталоги. Под каждым корнем рабочей области .git, .codex, .agents и .aws доступны только для чтения. Поэтому команды не могут напрямую менять конфигурацию репозитория, например .codex/config.toml, или хуки Git в .git/hooks. Эти правила защищают пути под корнями рабочей области, а не все одноимённые каталоги на компьютере.
Права на чтение шире прав на запись. Команды могут читать файлы за пределами репозитория, если это допускают ваши права в ОС. В описании стандартных ограничений песочницы OpenAI объясняет: компиляторам и другим инструментам нужны SDK, библиотеки и настройки за пределами репозитория. При этом такие файлы не скрыты от команд Codex.
По умолчанию сеть отключена: возможность прочитать данные не должна автоматически давать возможность отправить их наружу. По той же причине для скачивания зависимостей требуется дополнительное разрешение. OpenAI также указывает, что дочерние процессы наследуют ограничения песочницы родительского процесса. Ограничения действуют даже для потомков, которые продолжают работать после завершения исходной команды.
Для разовой загрузки рассмотрите запрос на сетевой доступ, не меняя профиль по умолчанию. Codex может направить запрос вам или на автоматическую проверку, как описано в разделе о сетевом прокси. Если зависимости скачиваются регулярно, используйте профиль с доступом к конкретному реестру. Для задач, которым сеть не нужна, оставьте её выключенной.
Как настроить профиль dev для реестра npm
Установленный Codex CLI должен поддерживать команду codex sandbox --permission-profile. Для проверок также понадобятся npm, curl и Bash. Проверяйте правила из корня временной рабочей копии Git-репозитория.
Измените свой файл ~/.codex/config.toml. Добавьте параметры в соответствующие таблицы TOML, не создавая повторных определений таблиц. Настройка ниже выбирает dev как профиль разрешений по умолчанию.
Не смешивайте этот вариант с прежними параметрами sandbox_mode или [sandbox_workspace_write]. В документации по профилям разрешений требуется выбрать один из двух способов настройки, а не использовать оба.
default_permissions = "dev"
[features]
network_proxy = true
[permissions.dev]
description = "Workspace editing with npm registry access."
extends = ":workspace"
[permissions.dev.filesystem.":workspace_roots"]
".devcontainer" = "read"
".vscode" = "read"
".env" = "deny"
".env.local" = "deny"
"secrets" = "deny"
[permissions.dev.network]
enabled = true
[permissions.dev.network.domains]
"registry.npmjs.org" = "allow"
"example.com" = "deny"
extends = ":workspace" сохраняет встроенную защиту, включая режим «только чтение» для .git и .codex. Дополнительные правила запрещают запись в настройки редактора и контейнера разработки. Доступ к перечисленным файлам переменных окружения и каталогу secrets со всем содержимым запрещён под каждым корнем рабочей области. В описании разрешений файловой системы OpenAI определяет значения так: read разрешает только чтение, write — чтение и запись, deny запрещает доступ.
За сетевой доступ отвечают два отдельных параметра. permissions.dev.network.enabled = true разрешает сеть, а network_proxy = true включает применение доменных правил. Как объясняет документация по сетевым разрешениям, включённая сеть без работающего прокси даёт прямой сетевой доступ. Доменные правила в этом случае не применяются. Не пропускайте настройку прокси.
В руководстве OpenAI по безопасности для компаний registry.npmjs.org указан в примере доступа к зависимостям. Здесь example.com явно запрещён: он нужен для проверки ограничения. Согласно правилам обработки доменов, явный запрет имеет приоритет над совпавшим разрешением. Запросы к другим адресам требуют одобрения или блокируются.
Такая конфигурация не открывает неограниченный доступ ко всем узлам, к которым может обратиться установщик пакетов. Добавляйте домен только после того, как выясните, зачем он нужен проекту.
Как проверить доступ и ограничения
Используйте codex sandbox, чтобы запускать проверочные команды непосредственно с нужным профилем. Добавьте --include-managed-config, чтобы при загрузке профиля учитывались требования администратора. Это важно, если корпоративная политика ограничивает доступные профили.
Сначала проверьте связь с реестром из Bash:
codex sandbox --permission-profile dev --include-managed-config -- \
npm ping --registry=https://registry.npmjs.org \
--cache="$PWD/.npm-cache"
При успешном npm ping в выводе будет PONG. В этом примере параметр cache размещает кэш npm внутри рабочей области. Поэтому отдельное разрешение на запись кэша за её пределами не требуется. Это подтверждает связь с реестром, но не гарантирует успешную установку каждой зависимости или выполнение каждого установочного скрипта.
Затем проверьте запись в рабочую область, защиту метаданных Git и запрет доступа к домену. Выполняйте команды по отдельности. Для проверки Git нужен существующий каталог .git, а не файл-указатель на настоящий каталог репозитория.
# Expect success: create and remove a temporary workspace file.
codex sandbox --permission-profile dev --include-managed-config -- \
bash -c 'p=$(mktemp ./codex-write-check.XXXXXX) && rm "$p"'
# Expect a filesystem permission denial.
codex sandbox --permission-profile dev --include-managed-config -- \
bash -c 'p=$(mktemp .git/codex-write-check.XXXXXX) && rm "$p"'
# Expect a proxy policy rejection.
codex sandbox --permission-profile dev --include-managed-config -- \
curl --fail --head --max-time 15 https://example.com
Ожидаемый результат: запись в рабочую область проходит, запись в .git запрещена, сетевой запрос отклонён. Ошибка конфигурации, отсутствие каталога или посторонний сетевой сбой не доказывают, что сработало нужное ограничение. Если хотя бы одна запрещённая операция прошла, остановитесь и разберитесь с действующей конфигурацией, прежде чем использовать профиль для обычной работы. Здесь приведены ожидаемые результаты, а не результаты уже проведённых тестов.
После успешных проверок запустите новую сессию Codex из корня репозитория. Введите /permissions и проверьте запись dev и её описание, как показано в примере настройки профиля OpenAI. Убедившись, что профиль активен, повторите исходную задачу установки зависимостей. Храните кэш внутри рабочей области либо дайте разрешение write только конкретному внешнему каталогу кэша.
Что проверить, если пакеты по-прежнему не загружаются
Если профиль не применяется, сначала проверьте загруженную конфигурацию на наличие прежних настроек песочницы. Затем сверьтесь с порядком приоритета настроек: параметры командной строки или конфигурация доверенного проекта могут переопределить ваши настройки по умолчанию. Не расширяйте разрешения профиля, который сессия не использует.
Если npm ping проходит, а установка нет, отдельно проверьте адрес неудачного запроса и путь, где возникла ошибка файловой системы. Для другого домена нужно отдельное решение о сетевом доступе. Для записи кэша за пределами рабочей области требуется подходящее правило файловой системы. Разрешения файловой системы и сети независимы: доступ к сети не даёт права записывать файлы.
Если запрос к разрешённому адресу всё равно не проходит, проверьте, учитывает ли программа настройки прокси. В описании реализации сетевого прокси OpenAI предупреждает, что некоторые программы игнорируют переменные окружения для прокси. Разберитесь с программой или её настройками, а не снимайте ограничения песочницы.
Ошибка подключения самого Codex к поставщику модели отличается от блокировки команды пакетного менеджера в песочнице. Для настройки аутентификации, Base URL и протокола используйте отдельное руководство по подключению API к Codex.
Может ли Codex прочитать ключи API?
Да, они могут оставаться доступными для чтения. Режим «только чтение» запрещает изменения, но не чтение. В статье об устройстве песочницы Codex OpenAI прямо описывает этот компромисс (перевод):
При таком подходе конфиденциальные файлы в других каталогах компьютера тоже могут оставаться доступными для чтения, например файлы конфигурации с ключами API.
Поэтому стандартный профиль не гарантирует, что секреты за пределами репозитория скрыты.
Пример запрещает доступ только к указанным путям .env и .env.local относительно корня, а также к каталогу secrets и его содержимому. Он не охватывает все возможные имена и расположения файлов с учётными данными. Добавьте подходящие правила deny для конфиденциальных путей в вашей среде, в том числе за пределами рабочей области, когда это необходимо. Проверяйте запреты на безвредных тестовых файлах, не выводите реальные ключи.
Доступные для записи файлы тоже создают риск. OpenAI описывает, как изменение установленного пакета, например node_modules/prettier, может затронуть форматтер, который редактор позже запустит вне песочницы. Поскольку node_modules часто игнорируется Git, такое изменение может не появиться в git status. Проверяйте доступные для записи инструменты и содержимое каталогов зависимостей, а не только изменения отслеживаемого кода.
Если команда использует несколько агентов для программирования, также проверьте разрешения Claude Code для секретов и Git. Настраивайте каждый инструмент по его собственным правилам, не копируйте параметры разрешений Codex в другой клиент.
Почему Codex использует песочницу ОС, а не Docker?
Песочница на уровне ОС позволяет Codex использовать привычные инструменты разработки и ограничивает команды, которые он запускает. В описании устройства песочницы OpenAI объясняет этот выбор как альтернативу переносу всей среды разработки в контейнер.
Практический пример — разработка приложения для iOS на Mac. В описанном OpenAI сценарии контейнер Docker не может запускать нативные инструменты сборки для Mac или симулятор iPhone. Если передать сборку и работу с симулятором хосту Mac, эти операции выйдут за пределы песочницы контейнера. Для них потребуются отдельные ограничения.
В macOS Codex использует Seatbelt. Для Linux и WSL2 инструкция OpenAI по настройке песочницы рекомендует установить bubblewrap через пакетный менеджер дистрибутива. Ошибку запуска песочницы разбирайте отдельно от запрета запроса к реестру.
Запуск непосредственно в Windows требует отдельной проверки. Документация по песочнице Windows рекомендует MXC на совместимых устройствах. Она также предупреждает, что устаревший вариант unelevated не поддерживает запрет чтения отдельных путей. Успешные проверки в Bash под WSL2 не заменяют проверку ограничений при запуске непосредственно в Windows.
Контейнер можно использовать, когда вся работа выполняется внутри него. Если нужны инструменты хоста, определите и ограничьте операции на хосте. Не считайте, что ограничения контейнера автоматически распространяются и на операции, переданные хосту.
Может ли компания запретить профиль dev?
Да. Через управляемый файл requirements.toml администраторы могут ограничить выбор профилей. Локальное определение профиля не отменяет эти требования. В примере требований администратора от OpenAI приведена такая политика:
default_permissions = ":read-only"
[allowed_permission_profiles]
":read-only" = true
":danger-full-access" = false
При наличии allowed_permission_profiles итоговая объединённая таблица задаёт полный список разрешённых профилей. Профили, которых в ней нет, запрещены, как и профили со значением false. Если показанный пример — итоговый список после объединения требований, пользовательский профиль dev недоступен, поскольку его нет в списке. Попросите администратора согласовать подходящий профиль для сборки вместо попыток обойти политику.
В документации по управляемой конфигурации указана важная граница версий: списки разрешённых профилей требуют Codex 0.138.0 или новее. Codex 0.137.0 и более ранние версии игнорируют allowed_permission_profiles и управляемый параметр default_permissions. Прежде чем рассчитывать на эти ограничения, проверьте версию каждого управляемого клиента.
Перед развёртыванием проверьте разрешённую сборку и заведомо запрещённое действие на каждой поддерживаемой ОС. Разрешайте только нужные домены реестров, проверяйте активный профиль и повторяйте проверки запретов после обновления клиентов.