Правила

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

Создание файла правил

1. Создайте файл .rules в папке rules/ рядом с активным слоем конфигурации (например, ~/.codex/rules/default.rules).
2. Добавьте правило. В этом примере перед запуском gh pr view за пределами песочницы запрашивается подтверждение.

   # Prompt before running commands with the prefix `gh pr view` outside the sandbox.
   prefix_rule(
       # The prefix to match.
       pattern = ["gh", "pr", "view"],

       # The action to take when Codex requests to run a matching command.
       decision = "prompt",

       # Optional rationale for why this rule exists.
       justification = "Viewing PRs is allowed with approval",

       # `match` and `not_match` are optional "inline unit tests" where you can
       # provide examples of commands that should (or should not) match this rule.
       match = [
           "gh pr view 7888",
           "gh pr view --repo openai/codex",
           "gh pr view 7888 --json title,body,comments",
       ],
       not_match = [
           # Does not match because the `pattern` must be an exact prefix.
           "gh pr --repo openai/codex view 7888",
       ],
   )

3. Перезапустите Codex.

При запуске Codex сканирует rules/ во всех активных слоях конфигурации, включая расположения конфигурации команды и пользовательский слой в ~/.codex/rules/. Локальные правила проекта в <repo>/.codex/rules/ загружаются только в том случае, если слой проекта .codex/ является доверенным.

Когда вы добавляете команду в список разрешённых в TUI, Codex записывает её в пользовательский слой в ~/.codex/rules/default.rules, чтобы при последующих запусках не запрашивать подтверждение.

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

Администраторы также могут принудительно применять ограничительные записи prefix_rule из requirements.toml.

Поля правил

prefix_rule() поддерживает следующие поля:

• pattern (обязательное): непустой список, определяющий префикс команды для сопоставления. Каждый элемент представляет собой:
  • Строковый литерал (например, "pr").
  • Объединение литералов (например, ["view", "list"]) для сопоставления с альтернативными значениями в этой позиции аргумента.
• decision (по умолчанию — "allow"): действие при совпадении с правилом. Если совпадает несколько правил, Codex применяет наиболее ограничительное решение (forbidden > prompt > allow).
  • allow: выполнить команду за пределами песочницы без запроса подтверждения.
  • prompt: запрашивать подтверждение перед каждым соответствующим вызовом.
  • forbidden: заблокировать запрос без подтверждения.
• justification (необязательное): непустое и понятное человеку обоснование правила. Codex может показывать его в запросах подтверждения или сообщениях об отклонении. При использовании forbidden по возможности указывайте в обосновании рекомендуемую альтернативу (например, "Use \rg` instead of `grep`."`).
• match и not_match (по умолчанию — []): примеры, которые Codex проверяет при загрузке правил. Используйте их, чтобы выявлять ошибки до вступления правила в силу.

Рассматривая команду для запуска, Codex сравнивает список её аргументов с pattern. Внутри Codex представляет команду как список аргументов (подобный тому, который получает execvp(3)).

Оболочки командной строки и составные команды

Некоторые инструменты объединяют несколько команд оболочки в один вызов, например:

["bash", "-lc", "git add . && rm -rf /"]

Поскольку такие команды могут скрывать несколько действий внутри одной строки, Codex особым образом обрабатывает bash -lc, bash -c и их аналоги zsh / sh.

Когда Codex может безопасно разделить скрипт

Если скрипт оболочки представляет собой линейную цепочку команд, состоящую только из:

• простых слов (без подстановки переменных, VAR=..., $FOO, * и т. д.)
• соединённых безопасными операторами (&&, ||, ; или |)

то Codex анализирует его (с помощью tree-sitter) и разделяет на отдельные команды перед применением правил.

Приведённый выше скрипт обрабатывается как две отдельные команды:

• ["git", "add", "."]
• ["rm", "-rf", "/"]

Затем Codex проверяет каждую команду по вашим правилам и выбирает наиболее ограничительный результат.

Даже если вы разрешите pattern=["git", "add"], Codex не разрешит git add . && rm -rf / автоматически, поскольку часть rm -rf / оценивается отдельно и не позволяет автоматически разрешить весь вызов.

Это предотвращает скрытый запуск опасных команд вместе с безопасными.

Когда Codex не разделяет скрипт

Если скрипт использует более сложные возможности оболочки, такие как:

• перенаправление (>, >>, <)
• подстановки ($(...), ...)
• переменные окружения (FOO=bar)
• шаблоны с подстановочными знаками (*, ?)
• управляющие конструкции (if, for, && с присваиваниями и т. д.)

то Codex не пытается интерпретировать или разделять его.

В таких случаях весь вызов обрабатывается как:

["bash", "-lc", "<full script>"]

и ваши правила применяются к этому единственному вызову.

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

Проверка файла правил

Используйте codex execpolicy check, чтобы проверить, как ваши правила применяются к команде:

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- gh pr view 7888 --json title,body,comments

Команда выводит JSON с наиболее строгим решением и всеми совпавшими правилами, включая значения justification из этих правил. Используйте несколько флагов --rules, чтобы объединить файлы, и добавьте --pretty для форматирования вывода.

Язык правил

Формат файла .rules использует Starlark (см. спецификацию языка). Его синтаксис похож на Python, но разработан с учётом безопасного выполнения: обработчик правил может запускать его без побочных эффектов (например, без обращения к файловой системе).