Разрешения

Управляемая настройка 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 Cloud (Legacy) см. раздел Доступ к интернету.

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

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 сохраняется доступ только для чтения к путям .git, .agents, .codex и .aws в корне рабочего пространства, если вы явно не переопределите эти правила. Укажите родительский профиль один раз, затем добавляйте или переопределяйте только отличающиеся правила.

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, найденных внутри каждого корня рабочей области, заданного средой выполнения или профилем. Используйте его, когда нужно сохранить обычную запись в рабочей области, но сделать файлы окружения, сгенерированные секреты и аналогичные файлы с учётными данными недоступными для чтения.

В Linux, WSL и нативной Windows с MXC или elevated файлы, соответствующие glob-шаблонам запрета чтения, перечисляются при запуске каждого процесса в песочнице. Соответствующие файлы, созданные позже, не добавляются в список запретов этого процесса и остаются доступными для чтения, если другие его разрешения допускают доступ. Например, длительно работающая оболочка, скрипт, процесс наблюдения или сервер разработки может прочитать соответствующий шаблону файл .env, созданный после его запуска.

Этот снимок действует в течение всего времени работы процесса в песочнице, а не всего сеанса Codex. При запуске нового процесса в песочнице через Codex соответствующие файлы перечисляются заново; продолжение работы с уже запущенным процессом не обновляет его список запретов. Не полагайтесь на glob-шаблон для блокировки вновь созданных файлов в таком процессе. Ограничения для Windows описаны в разделе Совместимость с Windows MXC .

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 только тогда, когда намеренно выбираете модель с максимально широким локальным доступом.

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

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

Доступ к локальному компьютеру через Work Cloud и политика среды

Ознакомьтесь с политикой каждой среды, в которой используется доступ к локальному компьютеру через Work Cloud:

• Корпоративные требования: Для Work с локальным доступом и dots поддерживаемая политика Global регулирует работу общего облачного оркестратора, когда включена управляемая политика; применимые требования к локальному выполнению регулируют работу подключённого компьютера.
• Выполнение в облаке: Облачные контейнеры Work используют существующие политики Work Cloud.
• Порядок локальных политик: MDM и прежние требования к управляемым устройствам имеют более высокий приоритет, чем Agent Security. Системный файл требований устройства имеет более низкий приоритет, чем Agent Security.
• Приоритет политик: Политика с более высоким приоритетом имеет преимущество, даже если политика с более низким приоритетом более конкретна. В рамках одной политики переопределения среды для конкретной ОС имеют приоритет над переопределениями среды для всех ОС, за которыми следует Global.

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

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

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

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

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

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

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

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

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

• В macOS Codex использует профили песочницы Seatbelt. Если выбранную политику нельзя применить средствами песочницы платформы, Codex отказывается выполнять команду вместо того, чтобы незаметно запустить её вне песочницы.
• В Linux и WSL Codex использует bubblewrap и seccomp для применения ограничений файловой системы. Устаревший вариант с Landlock не может изолировать Unix-сокеты app-server и отклоняется для политик с ограничениями файловой системы. Отключите features.use_legacy_landlock при обновлении. На хостах, блокирующих необходимые операции bubblewrap, эти политики использовать нельзя.
• В Windows MXC использует изоляцию процессов для ограничения доступа к файловой системе и сети. Ознакомьтесь с совместимостью MXC перед включением. Устаревший резервный вариант 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
# paths such as .git/, .agents/, .codex/, and .aws/ 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"

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