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

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

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

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

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

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

OpenClaw изменяет только значение по умолчанию. Явная настройка всегда имеет приоритет:

# Поведение OpenClaw по умолчанию: только резервные механизмы fs-safe на Node.OPENCLAW_FS_SAFE_PYTHON_MODE=off # Использовать вспомогательный процесс, когда он доступен, с переходом к резервному варианту, если он недоступен.OPENCLAW_FS_SAFE_PYTHON_MODE=auto # Завершить работу с ошибкой, если вспомогательный процесс не удаётся запустить.OPENCLAW_FS_SAFE_PYTHON_MODE=require # Необязательный явный путь к интерпретатору.OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3

Также поддерживаются общие имена переменных окружения fs-safe: FS_SAFE_PYTHON_MODE и FS_SAFE_PYTHON.

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

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

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

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

Это соответствует обычной модели угроз OpenClaw: доверенный код Gateway обрабатывает недоверенные пути, поступающие от модели, плагина или канала, в пределах единой доверенной области оператора.

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

В POSIX необязательный вспомогательный процесс поддерживает один постоянный процесс Python и использует файловые операции относительно файлового дескриптора для изменений родительских каталогов: переименования, удаления, создания каталогов, получения метаданных и списков, а также некоторых путей записи.

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

Если при развёртывании существует такой риск и наличие Python гарантировано, задайте:

OPENCLAW_FS_SAFE_PYTHON_MODE=require

Рекомендации для плагинов и ядра

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

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