Разрешения

Профили разрешений позволяют применять принцип минимальных привилегий к локальным командам, которые 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"

[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"

[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, отклоняется.

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

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

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

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

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

Шаблоны deny поддерживаются в правилах запрета чтения. Шаблоны 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, поддерживаются как абсолютные пути.

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

Задайте enabled = true, чтобы разрешить доступ к сети для выбранного профиля:

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

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

[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.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 включены, оставляйте прослушивающие адреса прокси привязанными к адресам обратной петли.

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

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

Рекомендуемые отправные точки:

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

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

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

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

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

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

Как работает принудительное применение

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

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

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

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

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

default_permissions = "readonly-net"

[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"

[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"

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