Перейти до основного вмісту

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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