> ## 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 по умолчанию задает для POSIX-вспомогательного Python-процесса fs-safe значение **off**.

Почему:

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

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

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

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

См. также: [Безопасность](/ru/gateway/security), [Песочница](/ru/gateway/sandboxing), [Одобрения exec](/ru/tools/exec-approvals), [Секреты](/ru/gateway/secrets).