Безпечні операції з файлами

OpenClaw використовує @openclaw/fs-safe для чутливих до безпеки локальних файлових операцій: читання/запису в межах кореня, атомарної заміни, розпакування архівів, тимчасових робочих просторів, стану JSON та обробки файлів із секретами.

Мета — узгоджений бібліотечний запобіжник для довіреного коду OpenClaw, який отримує недовірені імена шляхів. Це не пісочниця. Дозволи файлової системи хоста, користувачі ОС, контейнери та політика агентів/інструментів усе ще визначають реальний радіус впливу.

# Типово: без допоміжного Python-процесу

OpenClaw типово вимикає POSIX-допоміжний Python-процес fs-safe.

Чому:

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

OpenClaw змінює лише типове значення. Якщо явно задати режим, fs-safe дотримується його:

# 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 гарантована, використовуйте:

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

Пов’язано: Безпека, Пісочниця, Схвалення виконання команд, Секрети.