---
read_when:
    - Изменение доступа к файлам, распаковки архивов, хранилища рабочей области или вспомогательных функций файловой системы плагинов
summary: Как OpenClaw обеспечивает безопасный доступ к локальным файлам и почему необязательный вспомогательный модуль fs-safe на Python по умолчанию отключён
title: Безопасные операции с файлами
x-i18n:
    generated_at: "2026-07-13T19:50:39Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 24
    provider: openai
    source_hash: 5c8edf36ddbb8c8bc1edc52ecdf481affe5395d1779c679a40439167dfe70299
    source_path: gateway/security/secure-file-operations.md
    workflow: 16
---

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
# Поведение 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
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 от имени разных пользователей ОС или на разных хостах либо используйте песочницу.

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