@openclaw/fs-safe для локальных файловых операций, критичных для безопасности: чтения и записи с ограничением корневым каталогом, атомарной замены, извлечения архивов, временных рабочих пространств, состояния в формате JSON и работы с файлами секретов.
Это защитный механизм библиотеки для доверенного кода OpenClaw, который получает недоверенные имена путей, а не песочница. Реальную область потенциального воздействия по-прежнему определяют разрешения файловой системы хоста, пользователи ОС, контейнеры и политика агента/инструментов.
По умолчанию: без вспомогательного процесса Python
OpenClaw по умолчанию отключает вспомогательный процесс Python для POSIX в fs-safe:- Gateway не должен запускать постоянный побочный процесс Python, если оператор явно не включил его;
- большинству установок не требуется дополнительная защита операций изменения родительских каталогов;
- отключение Python обеспечивает предсказуемое поведение среды выполнения в настольных приложениях, Docker, CI и пакетных приложениях.
FS_SAFE_PYTHON_MODE и FS_SAFE_PYTHON.
Используйте require (а не auto), если вспомогательный процесс является частью вашей стратегии безопасности; auto незаметно переходит к поведению только на Node, если вспомогательный процесс не удаётся запустить.
Что остаётся защищённым без Python
Когда вспомогательный процесс отключён, OpenClaw по-прежнему использует защитные механизмы fs-safe только на Node:- отклоняет выходы за пределы относительного пути (
..), абсолютные пути и разделители путей там, где разрешены только простые имена; - выполняет операции через доверенный дескриптор корневого каталога вместо ситуативных проверок
path.resolve(...).startsWith(...); - отклоняет шаблоны символических и жёстких ссылок в API, где этого требует политика;
- открывает файлы с проверкой идентичности, когда API возвращает или принимает содержимое файлов;
- записывает файлы состояния и конфигурации через атомарный временный файл в том же каталоге с последующим переименованием;
- применяет ограничения на количество байтов при чтении и извлечении архивов;
- устанавливает закрытые режимы доступа к файлам секретов и состояния там, где этого требует API.
Что добавляет Python
В POSIX необязательный вспомогательный процесс поддерживает один постоянный процесс Python и использует файловые операции относительно файлового дескриптора для изменений родительских каталогов: переименования, удаления, создания каталогов, получения метаданных и списков, а также некоторых путей записи. Это сокращает окна состояний гонки для процессов с тем же UID, когда другой процесс подменяет родительский каталог между проверкой и изменением, — дополнительный уровень защиты на хостах, где недоверенные локальные процессы могут изменять те же каталоги, с которыми работает OpenClaw. Если при развёртывании существует такой риск и наличие Python гарантировано, задайте:Рекомендации для плагинов и ядра
- Для доступа плагинов к файлам следует использовать вспомогательные функции
openclaw/plugin-sdk/*, а не необработанныйfs, если путь поступает из сообщения, вывода модели, конфигурации или входных данных плагина. - Код ядра должен использовать обёртки fs-safe из
src/infra/*, чтобы политика процесса OpenClaw применялась единообразно. - Для извлечения архивов следует использовать вспомогательные функции fs-safe для архивов с явными ограничениями размера, количества записей, ссылок и места назначения.
- Для секретов следует использовать вспомогательные функции OpenClaw для секретов или функции fs-safe для секретов и закрытого состояния; не реализуйте собственные проверки режимов доступа вокруг
fs.writeFile. - Для изоляции от враждебных локальных пользователей не полагайтесь только на fs-safe. Запускайте отдельные экземпляры Gateway от имени разных пользователей ОС или на разных хостах либо используйте песочницу.