Безопасные файловые операции

OpenClaw использует @openclaw/fs-safe для чувствительных к безопасности локальных файловых операций: чтения/записи в пределах корня, атомарной замены, извлечения архивов, временных рабочих областей, JSON-состояния и работы с файлами секретов.

Цель — единый защитный барьер библиотеки для доверенного кода OpenClaw, который получает недоверенные имена путей. Это не песочница. Права файловой системы хоста, пользователи ОС, контейнеры и политика агента/инструментов по-прежнему определяют реальный радиус поражения.

По умолчанию: без вспомогательного Python-процесса

OpenClaw по умолчанию задает для POSIX-вспомогательного Python-процесса fs-safe значение off.

Почему:

• Gateway не должен запускать постоянный Python-сайдкар, если оператор не включил его явно;
• многим установкам не нужно дополнительное усиление против мутаций родительских каталогов;
• отключение Python делает поведение пакета/среды выполнения более предсказуемым в окружениях настольного приложения, Docker, CI и bundled app.

OpenClaw меняет только значение по умолчанию. Если вы явно зададите режим, fs-safe его соблюдает:

# Default OpenClaw behavior: Node-only fs-safe fallbacks.OPENCLAW_FS_SAFE_PYTHON_MODE=off # Opt into the helper when available, falling back if unavailable.OPENCLAW_FS_SAFE_PYTHON_MODE=auto # Fail closed if the helper cannot start.OPENCLAW_FS_SAFE_PYTHON_MODE=require # Optional explicit interpreter.OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3

Также работают общие имена fs-safe: FS_SAFE_PYTHON_MODE и FS_SAFE_PYTHON.

Что остается защищенным без Python

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

• отклонения выходов за пределы относительного пути, таких как .., абсолютных путей и разделителей пути там, где разрешены только имена;
• выполнения операций через доверенный корневой дескриптор вместо разовых проверок path.resolve(...).startsWith(...);
• отказа от шаблонов символических и жестких ссылок в API, где требуется такая политика;
• открытия файлов с проверками идентичности там, где API возвращает или потребляет содержимое файлов;
• атомарных записей через временный соседний файл для файлов состояния/конфигурации;
• лимитов байтов для чтения и извлечения архивов;
• приватных режимов для секретов и файлов состояния там, где API их требует.

Эти меры защиты покрывают обычную модель угроз OpenClaw: доверенный код Gateway обрабатывает недоверенный ввод путей от модели/Plugin/канала внутри одной доверенной границы оператора.

Что добавляет Python

В POSIX опциональный вспомогательный процесс fs-safe поддерживает один постоянный процесс Python и использует файловые операции относительно fd для мутаций родительских каталогов, таких как переименование, удаление, создание каталогов, stat/list и некоторые пути записи.

Это сужает окна гонок для того же UID, когда другой процесс может подменить родительский каталог между проверкой и мутацией. Это эшелонированная защита для хостов, где недоверенные локальные процессы могут изменять те же каталоги, в которых работает OpenClaw.

Если в вашем развертывании есть такой риск и наличие Python гарантировано, используйте:

OPENCLAW_FS_SAFE_PYTHON_MODE=require

Используйте require, а не auto, когда вспомогательный процесс является частью вашей позиции безопасности; auto намеренно откатывается к поведению только на Node, если вспомогательный процесс недоступен.

Рекомендации для Plugin и ядра

• Доступ к файлам со стороны Plugin должен проходить через вспомогательные средства openclaw/plugin-sdk/*, а не напрямую через fs, когда путь приходит из сообщения, вывода модели, конфигурации или ввода Plugin.
• Код ядра должен использовать локальные обертки fs-safe в src/infra/*, чтобы политика процесса OpenClaw применялась единообразно.
• Извлечение архивов должно использовать архивные вспомогательные средства fs-safe с явными лимитами размера, количества записей, ссылок и назначения.
• Для секретов следует использовать вспомогательные средства секретов OpenClaw или вспомогательные средства секретов/приватного состояния fs-safe; не пишите собственные проверки режима вокруг fs.writeFile.
• Если вам нужна изоляция от враждебного локального пользователя, не полагайтесь только на fs-safe. Запускайте отдельные Gateway под разными пользователями/хостами ОС или используйте песочницу.

См. также: Безопасность, Песочница, Одобрения exec, Секреты.