Langsung ke konten utama

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 menggunakan @openclaw/fs-safe untuk operasi file lokal yang sensitif terhadap keamanan: baca/tulis yang dibatasi root, penggantian atomik, ekstraksi arsip, workspace sementara, status JSON, dan penanganan file rahasia. Tujuannya adalah pagar pembatas pustaka yang konsisten untuk kode OpenClaw tepercaya yang menerima nama jalur tidak tepercaya. Ini bukan sandbox. Izin filesystem host, pengguna OS, kontainer, dan kebijakan agen/alat tetap menentukan radius dampak yang sebenarnya.

​
Default: tanpa helper Python

OpenClaw menonaktifkan helper Python POSIX fs-safe secara default. Alasannya:
  • Gateway tidak boleh menjalankan sidecar Python persisten kecuali operator memilih untuk mengaktifkannya;
  • banyak instalasi tidak membutuhkan pengerasan tambahan untuk mutasi direktori induk;
  • menonaktifkan Python membuat perilaku paket/runtime lebih mudah diprediksi di lingkungan desktop, Docker, CI, dan aplikasi terbundel.
OpenClaw hanya mengubah default. Jika Anda menetapkan mode secara eksplisit, fs-safe akan menghormatinya: 
# 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
Nama fs-safe generik juga berfungsi: FS_SAFE_PYTHON_MODE dan FS_SAFE_PYTHON.

​
Yang tetap terlindungi tanpa Python

Dengan helper dinonaktifkan, OpenClaw tetap menggunakan jalur Node dari fs-safe untuk:
  • menolak escape jalur relatif seperti .., jalur absolut, dan pemisah jalur di tempat yang hanya mengizinkan nama;
  • menyelesaikan operasi melalui handle root tepercaya, bukan pemeriksaan ad hoc path.resolve(...).startsWith(...);
  • menolak pola symlink dan hardlink pada API yang mewajibkan kebijakan tersebut;
  • membuka file dengan pemeriksaan identitas ketika API mengembalikan atau memakai isi file;
  • penulisan atomik ke temp saudara untuk file status/konfigurasi;
  • batas byte untuk pembacaan dan ekstraksi arsip;
  • mode privat untuk file rahasia dan status saat API mewajibkannya.
Perlindungan ini mencakup model ancaman OpenClaw normal: kode Gateway tepercaya yang menangani input jalur model/Plugin/saluran tidak tepercaya di dalam satu batas operator tepercaya.

​
Yang ditambahkan Python

Pada POSIX, helper opsional fs-safe mempertahankan satu proses Python persisten dan menggunakan operasi filesystem relatif-fd untuk mutasi direktori induk seperti rename, remove, mkdir, stat/list, dan beberapa jalur tulis. Ini mempersempit jendela race dengan UID yang sama, ketika proses lain dapat menukar direktori induk di antara validasi dan mutasi. Ini adalah defense in depth untuk host tempat proses lokal tidak tepercaya dapat memodifikasi direktori yang sama dengan yang sedang dioperasikan OpenClaw. Jika deployment Anda memiliki risiko tersebut dan Python dijamin tersedia, gunakan: 
OPENCLAW_FS_SAFE_PYTHON_MODE=require
Gunakan require, bukan auto, ketika helper merupakan bagian dari postur keamanan Anda; auto sengaja kembali ke perilaku khusus Node jika helper tidak tersedia.

​
Panduan Plugin dan inti

  • Akses file yang berhadapan dengan Plugin harus melalui helper openclaw/plugin-sdk/*, bukan fs mentah, ketika jalur berasal dari pesan, output model, konfigurasi, atau input Plugin.
  • Kode inti harus menggunakan wrapper fs-safe lokal di bawah src/infra/* agar kebijakan proses OpenClaw diterapkan secara konsisten.
  • Ekstraksi arsip harus menggunakan helper arsip fs-safe dengan batas ukuran, jumlah entri, tautan, dan tujuan yang eksplisit.
  • Rahasia harus menggunakan helper rahasia OpenClaw atau helper rahasia/status-privat fs-safe; jangan membuat sendiri pemeriksaan mode di sekitar fs.writeFile.
  • Jika Anda membutuhkan isolasi pengguna lokal yang bermusuhan, jangan mengandalkan fs-safe saja. Jalankan Gateway terpisah di bawah pengguna/host OS yang terpisah atau gunakan sandboxing.
Terkait: Keamanan, Sandboxing, Persetujuan exec, Rahasia.