---
read_when:
    - Зміна доступу до файлів, розпакування архівів, сховища робочої області або допоміжних засобів файлової системи Plugin
summary: Як OpenClaw безпечно обробляє доступ до локальних файлів і чому необов’язковий допоміжний Python-скрипт fs-safe вимкнений за замовчуванням
title: Безпечні операції з файлами
x-i18n:
    generated_at: "2026-05-06T01:35:56Z"
    model: gpt-5.5
    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.

Чому:

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

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

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

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