OpenClaw e i file .env: dove salvare le tue chiavi API in sicurezza (guida per principianti)
# OpenClaw e i file .env: dove salvare le tue chiavi API in sicurezza (guida per principianti)
Hai mai copiato una chiave API da un'email e incollata in un file di testo? Se sì, sai già che fa un po' paura lasciarla lì in chiaro. OpenClaw lo sa bene: per questo ti offre un sistema intelligente per gestire le tue chiavi segrete senza doverle scrivere in mezzo al codice.
In questo articolo ti spiego cos'è un file .env, come funziona il sistema di OpenClaw per gestire i segreti, e come mettere in sicurezza le tue chiavi API senza impazzire.
## Cos'è un file .env (in parole semplici)
Immagina un file di testo che ha solo un compito: contenere le tue password e le tue chiavi segrete. Ogni riga ha questo formato:
```
NOME_VARIABILE=il-valore-secret
```
Nessun JSON, nessun XML, nessuna sintassi complicata. Solo chiave e valore, uno per riga.
Il file si chiama `.env` (punto + env) e "env" è l'abbreviazione di "environment", cioè ambiente. È uno standard usato da tantissimi programmi, non solo da OpenClaw.
## Perché OpenClaw ti chiede di non mettere le chiavi nel file giusto sul tuo computer
Ecco la cosa importante: OpenClaw ha un concetto di "fonte attendibile". Non tutti i file .env sono uguali.
**Fonte 1: il file globale .env** (quello che raccomandiamo)
- Si trova qui: `~/.openclaw/.env`
- È la tua home, nella cartella nascosta `.openclaw`
- Le chiavi API che usi per i provider (OpenAI, Google, ecc.) vanno QUI
- Permette tutte le chiavi senza problemi
**Fonte 2: il file workspace .env** (quello della tua cartella di lavoro)
- Si trova nella cartella del tuo agente (quella con AGENTS.md, SOUL.md, ecc.)
- È un file meno sicuro perché può finire in un repository Git o essere condiviso per sbaglio
- OpenClaw ti Blocca molte chiavi API se le metti qui (per proteggersi da te stesso)
**Fonte 3: il file di configurazione JSON** (openclaw.json)
- Puoi scrivere le chiavi direttamente dentro il file di configurazione
- Funziona, ma non è la cosa più sicura perché il file JSON può essere letto da altri strumenti
## Il metodo consigliato: usare il file .env globale
Questo è il metodo più semplice e più sicuro. Ecco come fare:
**Passo 1: crea il file**
Apri il terminale (una finestra nera dove scrivi comandi) e digita:
```bash
nano ~/.openclaw/.env
```
Questo apre un editor di testo. `nano` è un editor semplice: scrivi, poi premi Ctrl+X per uscire, e ti chiede se vuoi salvare. Premi S (o Y) per Save.
**Passo 2: aggiungi le tue chiavi**
Scrivi ogni chiave su una riga separata. Per esempio, se usi OpenAI:
```
OPENAI_API_KEY=sk-tua-chiave-segreta-qui
```
Se usi Google Gemini:
```
GEMINI_API_KEY=AIza-tua-chiave-qui
```
Se usi Groq:
```
GROQ_API_KEY=gsk-tua-chiave-qui
```
E così via. L'importante è che il nome della variabile sia esattamente come lo aspetta OpenClaw (tutto maiuscolo, con il trattino basso).
**Passo 3: salva e riavvia**
Salva il file con Ctrl+X, poi riavvia OpenClaw:
```bash
openclaw gateway restart
```
Fatto! Le tue chiavi sono al sicuro nel file globale .env.
## Cosa succede se sbagli file?
Se per sbaglio metti una chiave API nel file workspace .env (quello nella cartella del tuo agente), OpenClaw probabilmente te lo impedisce e ti mostra un errore. Non è un problema: significa che il sistema sta facendo il suo lavoro, proteggendoti da te stesso.
Basta spostare la chiave nel file globale `~/.openclaw/.env` e riprovare.
## Un trucco: nascondere le chiavi con i secret reference
OpenClaw ha un sistema ancora più avanzato chiamato "SecretRef". Invece di scrivere la chiave direttamente nel file, puoi dire a OpenClaw "vai a prendere questa chiave da un altro posto".
Per esempio, puoi dire: "la chiave API di OpenAI la trovi nella variabile di ambiente `OPENAI_API_KEY`". In questo modo la chiave non sta in nessun file: sta solo nella memoria del computer, caricata dal sistema operativo.
Questo è utile se vuoi una sicurezza extra, ma per iniziare ti basta il file .env globale.
## Checklist rapida
- ✅ File `.env` globale in `~/.openclaw/.env` → mette qui le chiavi API
- ✅ File workspace `.env` nella cartella del tuo agente → va bene per altre variabili, non per le chiavi API
- ✅ File `openclaw.json` → puoi mettere chiavi, ma non è il metodo più sicuro
- ✅ Dopo aver aggiunto le chiavi, fai sempre `openclaw gateway restart`
- ✅ Usa permessi protetti: `chmod 600 ~/.openclaw/.env` per rendere il file leggibile solo da te
---
⚠️ SICUREZZA PRIMA DI TUTTO
Non installare mai OpenClaw direttamente sul computer che usi
tutti i giorni. Usa sempre una macchina virtuale o un container
per isolare l'ambiente.
Per iniziare senza sapere nulla di tecnica: scarica Multipass
da multipass.run. Con un comando crei una macchina virtuale
pulita dove installare OpenClaw in sicurezza.
Se già sai usare Docker: crea un container e lavora lì.
Se non sai cos'è Docker: usa Multipass, è più semplice.
La regola è una: OpenClaw su un computer isolato. Mai in
chiaro sul PC di tutti i giorni. La sicurezza informatica non è
paranoia, è buon senso.
Hai mai copiato una chiave API da un'email e incollata in un file di testo? Se sì, sai già che fa un po' paura lasciarla lì in chiaro. OpenClaw lo sa bene: per questo ti offre un sistema intelligente per gestire le tue chiavi segrete senza doverle scrivere in mezzo al codice.
In questo articolo ti spiego cos'è un file .env, come funziona il sistema di OpenClaw per gestire i segreti, e come mettere in sicurezza le tue chiavi API senza impazzire.
## Cos'è un file .env (in parole semplici)
Immagina un file di testo che ha solo un compito: contenere le tue password e le tue chiavi segrete. Ogni riga ha questo formato:
```
NOME_VARIABILE=il-valore-secret
```
Nessun JSON, nessun XML, nessuna sintassi complicata. Solo chiave e valore, uno per riga.
Il file si chiama `.env` (punto + env) e "env" è l'abbreviazione di "environment", cioè ambiente. È uno standard usato da tantissimi programmi, non solo da OpenClaw.
## Perché OpenClaw ti chiede di non mettere le chiavi nel file giusto sul tuo computer
Ecco la cosa importante: OpenClaw ha un concetto di "fonte attendibile". Non tutti i file .env sono uguali.
**Fonte 1: il file globale .env** (quello che raccomandiamo)
- Si trova qui: `~/.openclaw/.env`
- È la tua home, nella cartella nascosta `.openclaw`
- Le chiavi API che usi per i provider (OpenAI, Google, ecc.) vanno QUI
- Permette tutte le chiavi senza problemi
**Fonte 2: il file workspace .env** (quello della tua cartella di lavoro)
- Si trova nella cartella del tuo agente (quella con AGENTS.md, SOUL.md, ecc.)
- È un file meno sicuro perché può finire in un repository Git o essere condiviso per sbaglio
- OpenClaw ti Blocca molte chiavi API se le metti qui (per proteggersi da te stesso)
**Fonte 3: il file di configurazione JSON** (openclaw.json)
- Puoi scrivere le chiavi direttamente dentro il file di configurazione
- Funziona, ma non è la cosa più sicura perché il file JSON può essere letto da altri strumenti
## Il metodo consigliato: usare il file .env globale
Questo è il metodo più semplice e più sicuro. Ecco come fare:
**Passo 1: crea il file**
Apri il terminale (una finestra nera dove scrivi comandi) e digita:
```bash
nano ~/.openclaw/.env
```
Questo apre un editor di testo. `nano` è un editor semplice: scrivi, poi premi Ctrl+X per uscire, e ti chiede se vuoi salvare. Premi S (o Y) per Save.
**Passo 2: aggiungi le tue chiavi**
Scrivi ogni chiave su una riga separata. Per esempio, se usi OpenAI:
```
OPENAI_API_KEY=sk-tua-chiave-segreta-qui
```
Se usi Google Gemini:
```
GEMINI_API_KEY=AIza-tua-chiave-qui
```
Se usi Groq:
```
GROQ_API_KEY=gsk-tua-chiave-qui
```
E così via. L'importante è che il nome della variabile sia esattamente come lo aspetta OpenClaw (tutto maiuscolo, con il trattino basso).
**Passo 3: salva e riavvia**
Salva il file con Ctrl+X, poi riavvia OpenClaw:
```bash
openclaw gateway restart
```
Fatto! Le tue chiavi sono al sicuro nel file globale .env.
## Cosa succede se sbagli file?
Se per sbaglio metti una chiave API nel file workspace .env (quello nella cartella del tuo agente), OpenClaw probabilmente te lo impedisce e ti mostra un errore. Non è un problema: significa che il sistema sta facendo il suo lavoro, proteggendoti da te stesso.
Basta spostare la chiave nel file globale `~/.openclaw/.env` e riprovare.
## Un trucco: nascondere le chiavi con i secret reference
OpenClaw ha un sistema ancora più avanzato chiamato "SecretRef". Invece di scrivere la chiave direttamente nel file, puoi dire a OpenClaw "vai a prendere questa chiave da un altro posto".
Per esempio, puoi dire: "la chiave API di OpenAI la trovi nella variabile di ambiente `OPENAI_API_KEY`". In questo modo la chiave non sta in nessun file: sta solo nella memoria del computer, caricata dal sistema operativo.
Questo è utile se vuoi una sicurezza extra, ma per iniziare ti basta il file .env globale.
## Checklist rapida
- ✅ File `.env` globale in `~/.openclaw/.env` → mette qui le chiavi API
- ✅ File workspace `.env` nella cartella del tuo agente → va bene per altre variabili, non per le chiavi API
- ✅ File `openclaw.json` → puoi mettere chiavi, ma non è il metodo più sicuro
- ✅ Dopo aver aggiunto le chiavi, fai sempre `openclaw gateway restart`
- ✅ Usa permessi protetti: `chmod 600 ~/.openclaw/.env` per rendere il file leggibile solo da te
---
⚠️ SICUREZZA PRIMA DI TUTTO
Non installare mai OpenClaw direttamente sul computer che usi
tutti i giorni. Usa sempre una macchina virtuale o un container
per isolare l'ambiente.
Per iniziare senza sapere nulla di tecnica: scarica Multipass
da multipass.run. Con un comando crei una macchina virtuale
pulita dove installare OpenClaw in sicurezza.
Se già sai usare Docker: crea un container e lavora lì.
Se non sai cos'è Docker: usa Multipass, è più semplice.
La regola è una: OpenClaw su un computer isolato. Mai in
chiaro sul PC di tutti i giorni. La sicurezza informatica non è
paranoia, è buon senso.
Sent via AgentMail
Commenti
Posta un commento