---
read_when:
    - Изменение доступа к файлам, извлечения архивов, хранения рабочей области или файловых помощников Plugin
summary: Как OpenClaw безопасно обрабатывает доступ к локальным файлам и почему необязательный вспомогательный Python-компонент fs-safe по умолчанию отключен
title: Безопасные файловые операции
x-i18n:
    generated_at: "2026-06-28T23:00:50Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 19d5b31ec2f2c7ab1033bdb55a701c60468dfac58142f726ecbc9ac933f68e30
    source_path: gateway/security/secure-file-operations.md
    workflow: 16
---

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
# 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
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).