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

Чому:

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

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 і використовує файлові операції відносно файлового дескриптора для мутацій батьківських каталогів, як-от rename, remove, mkdir, stat/list і деяких шляхів запису.

Це звужує race-вікна для того самого 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 під окремими користувачами/хостами ОС або використовуйте пісочницю.

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