> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

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

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

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# Поведение 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 гарантировано, задайте:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 от имени разных пользователей ОС или на разных хостах либо используйте песочницу.

См. также: [Безопасность](https://docs2.openclaw.ai/ru/gateway/security.md), [Изоляция в песочнице](https://docs2.openclaw.ai/ru/gateway/sandboxing.md), [Подтверждения выполнения](https://docs2.openclaw.ai/ru/tools/exec-approvals.md), [Секреты](https://docs2.openclaw.ai/ru/gateway/secrets.md).