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

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

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

Типово: без допоміжного засобу Python

OpenClaw типово вимикає допоміжний засіб POSIX Python у fs-safe:

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

OpenClaw змінює лише типове значення. Явне налаштування завжди має пріоритет:

# Типова поведінка 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 гарантована, установіть:

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

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