Vai al contenuto principale

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 usa @openclaw/fs-safe per operazioni sui file locali sensibili alla sicurezza: letture/scritture delimitate alla radice, sostituzione atomica, estrazione di archivi, workspace temporanei, stato JSON e gestione dei file segreti. L’obiettivo è una barriera di protezione della libreria coerente per codice OpenClaw attendibile che riceve nomi di percorso non attendibili. Non è una sandbox. Le autorizzazioni del filesystem host, gli utenti del sistema operativo, i container e la policy di agenti/strumenti definiscono comunque il reale raggio d’impatto.

​
Predefinito: nessun helper Python

OpenClaw imposta per impostazione predefinita l’helper Python POSIX di fs-safe su off. Perché:
  • il gateway non dovrebbe avviare un sidecar Python persistente a meno che un operatore non abbia scelto di abilitarlo;
  • molte installazioni non hanno bisogno dell’irrobustimento aggiuntivo contro le mutazioni delle directory padre;
  • disabilitare Python mantiene il comportamento di package/runtime più prevedibile tra ambienti desktop, Docker, CI e app in bundle.
OpenClaw modifica solo il valore predefinito. Se imposti esplicitamente una modalità, fs-safe la rispetta: 
# 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
Funzionano anche i nomi generici di fs-safe: FS_SAFE_PYTHON_MODE e FS_SAFE_PYTHON.

​
Cosa resta protetto senza Python

Con l’helper disattivato, OpenClaw usa comunque i percorsi Node di fs-safe per:
  • rifiutare escape da percorsi relativi come .., percorsi assoluti e separatori di percorso dove sono consentiti solo nomi;
  • risolvere le operazioni tramite un handle radice attendibile invece di controlli ad hoc path.resolve(...).startsWith(...);
  • rifiutare pattern di symlink e hardlink sulle API che richiedono tale policy;
  • aprire file con controlli di identità quando l’API restituisce o consuma contenuti di file;
  • scritture atomiche con file temporanei sibling per file di stato/configurazione;
  • limiti di byte per letture ed estrazione di archivi;
  • modalità private per segreti e file di stato dove l’API le richiede.
Queste protezioni coprono il normale modello di minaccia di OpenClaw: codice gateway attendibile che gestisce input di percorso non attendibili da modello/plugin/canale all’interno del perimetro di un singolo operatore attendibile.

​
Cosa aggiunge Python

Su POSIX, l’helper opzionale di fs-safe mantiene un processo Python persistente e usa operazioni filesystem relative a fd per mutazioni delle directory padre come rename, remove, mkdir, stat/list e alcuni percorsi di scrittura. Questo riduce le finestre di race della stessa UID in cui un altro processo può scambiare una directory padre tra validazione e mutazione. È difesa in profondità per host in cui processi locali non attendibili possono modificare le stesse directory su cui OpenClaw sta operando. Se il tuo deployment ha questo rischio e Python è garantito, usa: 
OPENCLAW_FS_SAFE_PYTHON_MODE=require
Usa require invece di auto quando l’helper fa parte della tua postura di sicurezza; auto ripiega intenzionalmente sul comportamento solo Node se l’helper non è disponibile.

​
Indicazioni per Plugin e core

  • L’accesso ai file rivolto ai Plugin dovrebbe passare dagli helper openclaw/plugin-sdk/*, non da fs grezzo, quando un percorso proviene da un messaggio, output del modello, configurazione o input del Plugin.
  • Il codice core dovrebbe usare i wrapper fs-safe locali in src/infra/* in modo che la policy di processo di OpenClaw sia applicata coerentemente.
  • L’estrazione di archivi dovrebbe usare gli helper di archivio fs-safe con limiti espliciti di dimensione, numero di voci, link e destinazione.
  • I segreti dovrebbero usare gli helper per segreti di OpenClaw o gli helper fs-safe per segreti/stato privato; non implementare manualmente controlli di modalità attorno a fs.writeFile.
  • Se ti serve isolamento da utenti locali ostili, non fare affidamento solo su fs-safe. Esegui gateway separati sotto utenti/host del sistema operativo separati o usa sandboxing.
Correlati: Sicurezza, Sandboxing, Approvazioni exec, Segreti.