Разрешения

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

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

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

Локальные профили разрешений поддерживаются в macOS, Linux, WSL и нативной версии Windows. Особенности и ограничения для отдельных платформ описаны в разделе Область действия и применение.

Сетевые настройки Codex cloud описаны в разделе Доступ к интернету.

Определение и выбор профиля

Codex включает три встроенных профиля разрешений:

• :read-only разрешает локальным командам только чтение.
• :workspace разрешает запись в активных корнях рабочих областей и системных временных каталогах.
• :danger-full-access снимает ограничения локальной песочницы и должен использоваться только тогда, когда такой широкий доступ предоставляется намеренно.

Создайте именованный профиль в [permissions.<name>], затем присвойте ключу верхнего уровня default_permissions имя этого профиля или одного из перечисленных выше встроенных профилей. В этом примере project-edit — имя пользовательского профиля, а не встроенное значение.

Администраторы предприятия могут определять профили и ограничивать доступные пользователям профили с помощью управляемого requirements.toml. После появления allowed_permission_profiles все неуказанные профили запрещаются, включая неуказанные встроенные профили и профили, добавленные в будущих версиях Codex. Рекомендуемая управляемая конфигурация приведена в разделе Управление доступными профилями разрешений.

Пользовательские профили используют два взаимосвязанных понятия:

• [permissions.<name>.workspace_roots] добавляет конкретные каталоги, которые должны считаться корнями рабочих областей для этого профиля.
• [permissions.<name>.filesystem.":workspace_roots"] определяет правила файловой системы, которые Codex применяет внутри каждого фактического корня рабочей области: корней рабочих областей текущего сеанса и корней, заданных выше в профиле.

Профили также используют обычную модель слоёв конфигурации. Слои с более высоким приоритетом могут добавлять или заменять записи под тем же именем профиля, не повторяя весь профиль.

Например, конфигурация уровня организации и конфигурация уровня пользователя могут независимо расширять один и тот же профиль:

# /etc/codex/config.toml
[permissions.server.workspace_roots]
"~/code/server" = true

# ~/.codex/config.toml
[permissions.server.workspace_roots]
"~/code/mobile-app" = true

Когда активен server, оба корня рабочей области входят в фактический профиль.

default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"
"objects.githubusercontent.com" = "allow"
"*.github.com" = "allow"
"tracking.example.com" = "deny"

Этот профиль:

• Разрешает чтение минимального набора путей среды выполнения, необходимых распространённым инструментам разработчика.
• Применяет одинаковые правила корней рабочих областей к текущему сеансу и корням, заданным в профиле.
• Оставляет доступ только для чтения к связанным с IDE настройкам, таким как .devcontainer/, в каждом корне.
• Запрещает соответствующие файлы окружения с помощью правила glob.
• Разрешает доступ к сети только в рамках настроенной доменной политики.

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

Расширение профиля

Используйте extends, когда профиль в основном совпадает со встроенным или другим именованным профилем. Предпочтительно расширять встроенный профиль, а не создавать профиль с нуля, чтобы сохранить базовые меры защиты. Например, при расширении :workspace каталог .codex в корне рабочей области остаётся доступным только для чтения, если это явно не переопределено. Задайте родительский профиль один раз, а затем добавляйте или переопределяйте только отличающиеся правила.

default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit]
description = "Project editing with OpenAI API access."
extends = ":workspace"

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"

Этот профиль основан на :workspace, сохраняет запрет для соответствующих файлов .env и разрешает запросы к api.openai.com. Профиль может расширять :read-only, :workspace или другой именованный профиль. Он не может расширять :danger-full-access; Codex также отклоняет неизвестные родительские профили и циклы наследования.

Спецификация конфигурации

Разрешения файловой системы

Записи файловой системы используют read, write или deny:

Более конкретные записи имеют приоритет над более общими. Когда две записи относятся к одному пути, deny имеет приоритет над write, а write — над read.

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

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"

В этом примере корень рабочей области остаётся доступным для записи, .devcontainer/ остаётся доступным для чтения, но не для записи, а соответствующие файлы окружения остаются недоступными для команд в песочнице.

Более конкретный путь также может повторно открыть более узкое поддерево внутри более широкого запрета:

[permissions.project-edit.filesystem]
"~/Documents" = "deny"
"~/Documents/codex" = "write"

Поддерживаемые формы путей:

В нативной Windows пути относительно домашнего каталога также могут использовать обратную косую черту, например ~\work.

Используйте :root, только когда профилю намеренно требуется широкий доступ для чтения:

[permissions.audit.filesystem]
":root" = "read"

Используйте вложенные записи в :workspace_roots, чтобы ограничить доступ подпутями относительно корня рабочей области:

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"          # each workspace root
"docs" = "read"        # each workspace-root docs directory
"generated" = "deny"   # each workspace-root generated directory

Вложенные подпути должны оставаться внутри своего корня рабочей области. Переход к родительскому каталогу, например ../other-repo, отклоняется.

Запрет чтения с помощью точных путей или glob-шаблонов

Используйте deny для файлов или поддеревьев, которые Codex не должен читать, даже когда более широкое правило профиля разрешает доступ поблизости. Точные пути подходят для стабильных расположений, таких как ~/.ssh. Glob-шаблоны лучше подходят, когда профиль должен охватывать группу конфиденциальных файлов, точное расположение которых различается между репозиториями.

Если glob-шаблон находится в :workspace_roots, Codex интерпретирует его относительно каждого фактического корня рабочей области. Например:

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

Это правило запрещает чтение соответствующих файлов .env, найденных внутри каждого корня рабочей области, заданного средой выполнения или профилем. Используйте его, когда нужно сохранить обычную запись в рабочей области, но сделать файлы окружения, сгенерированные секреты и аналогичные файлы с учётными данными недоступными для чтения.

Glob-шаблоны deny поддерживаются как правила запрета чтения. Glob-шаблоны read или write менее переносимы в песочницах Linux, WSL и нативной Windows, поэтому по возможности предпочитайте точные пути или правила для поддеревьев, такие как "docs/**" = "read".

В Linux, WSL и нативной Windows для неограниченного запрещающего чтение шаблона ** может потребоваться ограниченное предварительное развёртывание перед запуском песочницы. Задайте glob_scan_max_depth, если используете неограниченный шаблон, такой как "**/*.env" = "deny":

[permissions.project-edit.filesystem]
glob_scan_max_depth = 3

[permissions.project-edit.filesystem.":workspace_roots"]
"**/*.env" = "deny"

Значение glob_scan_max_depth должно быть не меньше 1. Более высокие значения увеличивают глубину сканирования перед запуском песочницы, что может добавить работы при запуске в Linux, WSL и нативной Windows. Если вы не хотите использовать ограниченное развёртывание, перечислите явные уровни глубины, например *.env, */*.env и */*/*.env.

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

[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true

Когда этот профиль активен, Codex применяет правила :workspace_roots к корням рабочих областей текущего сеанса и каждому включённому корню рабочей области, заданному в профиле.

В нативной Windows поддерживаются абсолютные пути с буквами дисков, такие как D:\work, и UNC-пути, такие как \\server\share.

Сетевые разрешения

Доступ к сети и фильтрация сети настраиваются отдельно. Задайте permissions.<name>.network.enabled = true, чтобы разрешить командам доступ к сети, и включите features.network_proxy, чтобы обеспечить соблюдение доменных правил профиля:

[features]
network_proxy = true

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"example.com" = "allow"      # exact host
"*.example.com" = "allow"    # subdomains only
"**.example.com" = "allow"   # apex and subdomains
"ads.example.com" = "deny"   # deny wins over allow

Итоговое поведение зависит от обеих настроек:

• Сеть выключена: команды не могут обращаться к сети независимо от состояния функции прокси.
• Сеть включена, прокси выключен: команды получают прямой неограниченный доступ к сети. Доменные правила профиля разрешений не применяются.
• Сеть включена, прокси включён: команды используют прокси-сервер, который применяет доменные правила профиля. Если у активного прокси-сервера нет разрешённых доменов, он блокирует внешние адресаты.

Добавление [permissions.<name>.network.domains] или задание permissions.<name>.network.enabled = true не включает features.network_proxy. В качестве альтернативы администраторы могут включить прокси с помощью [experimental_network] в requirements.toml. См. раздел Управляемая конфигурация.

Когда сетевой прокси-сервер песочницы активен, по умолчанию он привязывается к локальным адресам прослушивания:

[permissions.project-edit.network]
enabled = true
proxy_url = "http://127.0.0.1:3128"
enable_socks5 = true
socks_url = "http://127.0.0.1:8081"
enable_socks5_udp = true

Оставьте стандартные значения этих настроек адресов прослушивания, если только вы не интегрируетесь с конкретной средой выполнения. Сетевые ключи dangerously_* — это обходные механизмы для специализированных сред; их не следует использовать для обычной локальной разработки.

Локальные и частные сети

Когда сетевой прокси-сервер активен, Codex по умолчанию применяет защиту локальной/частной сети от перепривязки DNS и случайного доступа к локальным службам. Чтобы намеренно разрешить локальный литеральный адрес, добавьте точное имя узла или литеральный IP-адрес в список разрешённых:

[permissions.project-edit.network.domains]
"localhost" = "allow"
"127.0.0.1" = "allow"

Задавайте allow_local_binding = true, только если профилю необходимо обращаться к добавленным в список разрешённых именам узлов, которые разрешаются в локальные или частные адреса:

[permissions.project-edit.network]
enabled = true
allow_local_binding = true

[permissions.project-edit.network.domains]
"localhost" = "allow"

Сокеты Unix

Проксирование сокетов Unix — локальный обходной механизм для таких инструментов, как Docker. Используйте его с осторожностью:

[permissions.project-edit.network.unix_sockets]
"/var/run/docker.sock" = "allow"
"/tmp/old.sock" = "deny"

Используйте deny, чтобы отклонить путь к сокету, включая унаследованную разрешающую запись. Запрещённые пути к сокетам исключаются из фактического списка разрешённых.

Когда сокеты Unix включены, оставляйте адреса прослушивания прокси привязанными к loopback-адресам.

Переход с прежних настроек песочницы

Профили разрешений заменяют прежнее сочетание sandbox_mode и sandbox_workspace_write, когда один повторно используемый профиль должен описывать и поведение файловой системы, и поведение сети. Используйте в одном сеансе только одну из этих систем.

Рекомендуемые исходные варианты:

• Для рабочего процесса только с чтением используйте встроенный профиль :read-only или определите пользовательский профиль с доступом для чтения только там, где он необходим.
• Для редактирования рабочей области используйте встроенный профиль :workspace или определите пользовательский профиль, который разрешает запись через :workspace_roots и добавляет только дополнительные временные пути или пути к кешу, необходимые рабочему процессу.
• Для неограниченного локального выполнения используйте :danger-full-access только тогда, когда намеренно выбираете модель с максимально широким локальным доступом.

Профили описывают стандартный локальный режим доступа для сеанса. Управляемые организацией требования по-прежнему могут добавлять ограничения, которые пользовательская конфигурация не должна ослаблять. Ограничения файловой системы и сети, применяемые администратором, описаны в разделе Управляемая конфигурация.

Область действия и применение

Профили разрешений определяют границы локального выполнения команд в песочнице. Используйте их вместе с политиками подтверждения и отдельными элементами управления для веб-поиска, коннекторов, серверов MCP, встроенного браузера, Computer Use и Codex cloud.

Что контролируют профили

• Локальное выполнение команд: профили разрешений управляют командами в песочнице, выполняемыми на вашем компьютере. Коннекторы, серверы MCP, интерфейсы браузера или Computer Use, настройки среды Codex cloud и подтверждённые повышения привилегий используют собственные элементы управления.
• Запись в файловую систему: профиль с возможностью записи может создавать постоянные изменения. Считайте запись в скрипты, этапы сборки, хуки менеджеров пакетов, файлы запуска оболочки и общие каталоги конфиденциальной операцией, поскольку впоследствии инструменты или пользователи могут выполнять эти файлы вне исходного контекста песочницы.
• Исходящие адресаты: доменные правила сети ограничивают адресаты трафика команд в песочнице только тогда, когда активен сетевой прокси-сервер. Они не определяют, заслуживает ли разрешённый адресат доверия, а правила с подстановочными знаками обеспечивают широкий доступ.
• Локальные службы: активный сетевой прокси-сервер по умолчанию блокирует адресаты в локальной и частной сети. Добавление в список разрешённых localhost, частных IP-адресов, сокетов Unix или задание allow_local_binding = true явно открывает доступ к локальным службам.

Что сетевой прокси-сервер не контролирует

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

• Веб-поиск: размещённый в облаке инструмент поиска использует собственные настройки доступа. Используйте web_search и, для управляемых клиентов, allowed_web_search_modes, чтобы управлять им. tools.web_search.allowed_domains фильтрует результаты поиска, а не сетевой доступ команд.
• Приложения и коннекторы: инструменты на основе коннекторов используют собственные подключения на стороне службы, разрешения рабочей области и настройки приложения или инструмента.
• Серверы MCP: локальные и удалённые серверы MCP используют собственный процесс или транспорт. Управляйте ими с помощью конфигурации mcp_servers и управляемых списков разрешённых серверов.
• Браузер и Computer Use: навигация в браузере и действия Computer Use используют собственные элементы управления функциями и подтверждениями.
• Служебный трафик Codex: запросы к модели, аутентификации и другим клиентским службам используют отдельные настройки HTTP и системного прокси клиента.
• Codex cloud: эти задачи используют собственные настройки доступа к интернету соответствующей среды.

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

Как обеспечивается соблюдение правил

• В macOS Codex использует профили песочницы Seatbelt. Если выбранную политику нельзя применить средствами песочницы платформы, Codex отказывается выполнять команду, а не запускает её без песочницы без уведомления.
• В Linux и WSL Codex использует bubblewrap и seccomp, а Landlock доступен для резервных путей совместимости. Наиболее строгий вариант применения зависит от пространств имён пользователей и поддержки ядра; ограниченные контейнерные среды могут вынудить использовать пути совместимости, а неподдерживаемые раздельные политики отклоняются.
• В нативной Windows песочница elevated обеспечивает наиболее строгую изоляцию, поскольку может использовать выделенных пользователей песочницы с пониженными привилегиями, границы разрешений файловой системы и правила брандмауэра. Песочница unelevated служит резервным вариантом с более слабой сетевой изоляцией и не может обеспечить соблюдение всех отдельных исключений для чтения и записи, поэтому неподдерживаемые политики отклоняются. Используйте WSL, если вам нужна модель песочницы Linux.

Практические рекомендации

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

Распространённые профили

Только чтение со списком разрешённых сетевых адресатов

default_permissions = "readonly-net"

[features]
network_proxy = true

[permissions.readonly-net.filesystem]
":minimal" = "read"

[permissions.readonly-net.filesystem.":workspace_roots"]
"." = "read"

[permissions.readonly-net.network]
enabled = true

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

Доступ к файлам только в рабочей области

Ниже приведён пример профиля разрешений, который позволит Codex записывать данные в папки вашей рабочей области, одновременно запретив чтение остальной файловой системы (за ограниченными исключениями, определяемыми :minimal).

default_permissions = "workspace-only"

[permissions.workspace-only]
# By extending the :workspace profile, you get Codex's safeguards to ensure
# subfolders such as .codex/ and .git/ within a workspace root are read-only
# while the rest of the folder is writable.
extends = ":workspace"

[permissions.workspace-only.filesystem]
# By default, deny read access to all files on disk.
":root" = "deny"

# Though in practice, a software agent needs to be able to read folders that
# contain common tools, such as `/usr/bin`, to get work done, so grant access
# to a "minimal" set of files and folders, as determined by Codex.
":minimal" = "read"

# By extending the :workspace profile, :tmpdir and :slash_tmp are "write" by
# default, though you can deny access to them altogether, if desired.
":tmpdir" = "deny"
":slash_tmp" = "deny"

Запись в рабочую область без сети

default_permissions = "project-edit"

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"

[permissions.project-edit.network]
enabled = false

Запись в рабочую область с доступом к общедоступному интернету

default_permissions = "workspace-net"

[features]
network_proxy = true

[permissions.workspace-net.filesystem]
":minimal" = "read"

[permissions.workspace-net.filesystem.":workspace_roots"]
"." = "write"

[permissions.workspace-net.network]
enabled = true

[permissions.workspace-net.network.domains]
"*" = "allow"

Используйте глобальное разрешающее правило "*", только если вы намерены разрешить доступ к общедоступной сети. Запрещающие правила могут сузить широкий список разрешённых.