> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Operazioni sicure sui file

OpenClaw usa [`@openclaw/fs-safe`](https://github.com/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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/it/gateway/security), [Sandboxing](/it/gateway/sandboxing), [Approvazioni exec](/it/tools/exec-approvals), [Segreti](/it/gateway/secrets).