---
read_when:
    - Зміна доступу до файлів, розпакування архівів, сховища робочого простору або допоміжних засобів файлової системи плагінів
summary: Як OpenClaw безпечно обробляє доступ до локальних файлів і чому необов’язковий допоміжний засіб fs-safe на Python типово вимкнено
title: Безпечні операції з файлами
x-i18n:
    generated_at: "2026-07-12T13:15:34Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    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 типово **вимикає** допоміжний засіб POSIX Python у 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, який обробляє недовірені вхідні шляхи від моделі, Plugin або каналу в межах єдиної довіреної області відповідальності оператора.

## Що додає Python

У POSIX необов’язковий допоміжний засіб підтримує один постійний процес Python і використовує файлові операції відносно файлового дескриптора для змін батьківських каталогів: перейменування, видалення, створення каталогів, отримання стану й переліку, а також деяких шляхів запису.

Це звужує вікна стану перегонів для процесів із тим самим UID, коли інший процес замінює батьківський каталог між перевіркою та зміною, — додатковий рівень захисту на хостах, де недовірені локальні процеси можуть змінювати ті самі каталоги, у яких працює OpenClaw.

Якщо у вашому розгортанні існує такий ризик і наявність Python гарантована, установіть:

```bash
OPENCLAW_FS_SAFE_PYTHON_MODE=require
```

## Рекомендації для Plugin і ядра

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

Пов’язані матеріали: [Безпека](/uk/gateway/security), [Ізоляція в пісочниці](/uk/gateway/sandboxing), [Схвалення виконання](/uk/tools/exec-approvals), [Секрети](/uk/gateway/secrets).