@openclaw/fs-safe для чувствительных к безопасности локальных файловых операций: чтения/записи в пределах корня, атомарной замены, извлечения архивов, временных рабочих областей, JSON-состояния и работы с файлами секретов.
Цель — единый защитный барьер библиотеки для доверенного кода OpenClaw, который получает недоверенные имена путей. Это не песочница. Права файловой системы хоста, пользователи ОС, контейнеры и политика агента/инструментов по-прежнему определяют реальный радиус поражения.
По умолчанию: без вспомогательного Python-процесса
OpenClaw по умолчанию задает для POSIX-вспомогательного Python-процесса fs-safe значение off. Почему:- Gateway не должен запускать постоянный Python-сайдкар, если оператор не включил его явно;
- многим установкам не нужно дополнительное усиление против мутаций родительских каталогов;
- отключение Python делает поведение пакета/среды выполнения более предсказуемым в окружениях настольного приложения, Docker, CI и bundled app.
FS_SAFE_PYTHON_MODE и FS_SAFE_PYTHON.
Что остается защищенным без Python
Когда вспомогательный процесс отключен, OpenClaw по-прежнему использует Node-пути fs-safe для:- отклонения выходов за пределы относительного пути, таких как
.., абсолютных путей и разделителей пути там, где разрешены только имена; - выполнения операций через доверенный корневой дескриптор вместо разовых проверок
path.resolve(...).startsWith(...); - отказа от шаблонов символических и жестких ссылок в API, где требуется такая политика;
- открытия файлов с проверками идентичности там, где API возвращает или потребляет содержимое файлов;
- атомарных записей через временный соседний файл для файлов состояния/конфигурации;
- лимитов байтов для чтения и извлечения архивов;
- приватных режимов для секретов и файлов состояния там, где API их требует.
Что добавляет Python
В POSIX опциональный вспомогательный процесс fs-safe поддерживает один постоянный процесс Python и использует файловые операции относительно fd для мутаций родительских каталогов, таких как переименование, удаление, создание каталогов, stat/list и некоторые пути записи. Это сужает окна гонок для того же UID, когда другой процесс может подменить родительский каталог между проверкой и мутацией. Это эшелонированная защита для хостов, где недоверенные локальные процессы могут изменять те же каталоги, в которых работает OpenClaw. Если в вашем развертывании есть такой риск и наличие Python гарантировано, используйте: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 под разными пользователями/хостами ОС или используйте песочницу.