OpenClaw Gateway: guida pratica alla configurazione sicura
OPENCLAW GATEWAY: GUIDA PRATICA ALLA CONFIGURAZIONE SICURA
=============================================================
Se stai configurando OpenClaw per la prima volta, il Gateway e' il
componente da capire meglio. Non e' complesso, ma gli errori di
configurazione sono il motivo numero uno per cui OpenClaw non parte.
Questa guida copre la configurazione del Gateway di OpenClaw con
un approccio security-first. Niente fronzoli, niente hype. Solo
quello che funziona.
DOVE SI CONFIGURA OPENCLAW GATEWAY
=============================================================
Il file principale e' ~/.openclaw/openclaw.json in formato JSON5.
Se non esiste, OpenClaw usa default sensati ma limitati. Per
personalizzare il Gateway devi crearlo.
Puoi anche usare la variabile OPENCLAW_CONFIG_PATH per puntare a
un file fuori dalla directory standard. Attenzione: niente symlink,
perche' OpenClaw fa scritture atomiche e il symlink verrebbe
sostituito.
Il modo piu' veloce per iniziare e' openclaw onboard, che guida
passo passo. Per ritocchi rapidi: openclaw config set.
IL CUORE: GATEWAY
=============================================================
Nel tuo openclaw.json, la sezione gateway controlla tutto:
- port: default 18789. Se hai gia' qualcosa su quella porta, cambiala.
- mode: local o cloud. Local per uso personale, cloud se vuoi
accesso remoto.
- bind: loopback per tenere il Gateway in ascolto solo su localhost.
- auth.token: il token per autenticare chiamate API.
La regola d'oro: se non ti serve accesso remoto, tieni bind su
loopback e mode su local. Riduci la superficie d'attacco.
Esempio minimo funzionante:
gateway: {
port: 18789,
mode: "local",
bind: "loopback"
}
VALIDAZIONE STRETTA
=============================================================
OpenClaw e' severo sulla validazione del config. Se il file
contiene chiavi sconosciute, tipi sbagliati o valori non validi,
il Gateway rifiuta di partire. Zero warning, zero partenza.
Se succede:
1. Esegui openclaw doctor per vedere gli errori esatti.
2. openclaw doctor --fix (o --yes) applica le riparazioni.
3. Il Gateway tiene una copia last-known-good dopo ogni avvio
riuscito, ma non la ripristina automaticamente.
Questo significa che un errore umano non ti lascia senza
configurazione. Puoi sempre recuperare.
GESTIRE I SEGRETI
=============================================================
Non mettere mai API key nel file openclaw.json. Usa invece
~/.openclaw/.env con formato CHIAVE=valore e reference nel config
come ${ANTHROPIC_API_KEY}.
Permessi: chmod 600 sul .env. Mai committare .env in git.
Questa e' la parte dove la maggior parte delle guide e' vaga, ma
per configurare OpenClaw in produzione e' il punto piu' critico.
Se perdi il controllo delle API key, perdi il controllo
dell'agente.
HOT RELOAD
=============================================================
Il Gateway monitora il file openclaw.json. Quando lo modifichi,
le modifiche vengono applicate senza riavvio. Attenzione: se la
modifica e' invalida, il reload viene saltato e il runtime
continua con la configurazione precedente.
Un comando utile: openclaw config get <path> per leggere il valore
corrente senza aprire il file.
CHANNEL E POLICY
=============================================================
I canali si configurano sotto channels.<provider>. Ogni canale ha
le sue policy: dmPolicy (open, pairing, allowlist) e groupPolicy
(open, mention, disabled).
Per Telegram: botToken e allowFrom con array di user ID autorizzati.
Per WhatsApp: phoneNumberId, accessToken, webhookUrl.
Se non vuoi che sconosciuti parlino col tuo agente OpenClaw,
usa allowlist e allowFrom. E' piu' sicuro di open.
MULTI-AGENTE
=============================================================
Puoi definire piu' agenti in agents.list, ognuno con id, identity
(name, emoji, tema SOUL.md), workspace e override dei model.
Cambi agente con /agent <id> in qualsiasi canale.
Ogni agente ha la sua directory in ~/.openclaw/agents/<id>/ con
il suo SOUL.md che ne definisce personalita' e regole.
CONCLUSIONE
=============================================================
Configurare OpenClaw non e' difficile, ma richiede attenzione ai
dettagli. Parti dal Gateway, proteggi i segreti con .env, usa la
validazione strict per non sbagliare, e sfrutta il multi-agente
solo quando serve davvero.
La documentazione ufficiale su docs.openclaw.ai e' la fonte
piu' aggiornata. Usala come riferimento quando la configurazione
diventa complessa.
Per dubbi: openclaw doctor e' il tuo primo alleato.
=============================================================
Se stai configurando OpenClaw per la prima volta, il Gateway e' il
componente da capire meglio. Non e' complesso, ma gli errori di
configurazione sono il motivo numero uno per cui OpenClaw non parte.
Questa guida copre la configurazione del Gateway di OpenClaw con
un approccio security-first. Niente fronzoli, niente hype. Solo
quello che funziona.
DOVE SI CONFIGURA OPENCLAW GATEWAY
=============================================================
Il file principale e' ~/.openclaw/openclaw.json in formato JSON5.
Se non esiste, OpenClaw usa default sensati ma limitati. Per
personalizzare il Gateway devi crearlo.
Puoi anche usare la variabile OPENCLAW_CONFIG_PATH per puntare a
un file fuori dalla directory standard. Attenzione: niente symlink,
perche' OpenClaw fa scritture atomiche e il symlink verrebbe
sostituito.
Il modo piu' veloce per iniziare e' openclaw onboard, che guida
passo passo. Per ritocchi rapidi: openclaw config set.
IL CUORE: GATEWAY
=============================================================
Nel tuo openclaw.json, la sezione gateway controlla tutto:
- port: default 18789. Se hai gia' qualcosa su quella porta, cambiala.
- mode: local o cloud. Local per uso personale, cloud se vuoi
accesso remoto.
- bind: loopback per tenere il Gateway in ascolto solo su localhost.
- auth.token: il token per autenticare chiamate API.
La regola d'oro: se non ti serve accesso remoto, tieni bind su
loopback e mode su local. Riduci la superficie d'attacco.
Esempio minimo funzionante:
gateway: {
port: 18789,
mode: "local",
bind: "loopback"
}
VALIDAZIONE STRETTA
=============================================================
OpenClaw e' severo sulla validazione del config. Se il file
contiene chiavi sconosciute, tipi sbagliati o valori non validi,
il Gateway rifiuta di partire. Zero warning, zero partenza.
Se succede:
1. Esegui openclaw doctor per vedere gli errori esatti.
2. openclaw doctor --fix (o --yes) applica le riparazioni.
3. Il Gateway tiene una copia last-known-good dopo ogni avvio
riuscito, ma non la ripristina automaticamente.
Questo significa che un errore umano non ti lascia senza
configurazione. Puoi sempre recuperare.
GESTIRE I SEGRETI
=============================================================
Non mettere mai API key nel file openclaw.json. Usa invece
~/.openclaw/.env con formato CHIAVE=valore e reference nel config
come ${ANTHROPIC_API_KEY}.
Permessi: chmod 600 sul .env. Mai committare .env in git.
Questa e' la parte dove la maggior parte delle guide e' vaga, ma
per configurare OpenClaw in produzione e' il punto piu' critico.
Se perdi il controllo delle API key, perdi il controllo
dell'agente.
HOT RELOAD
=============================================================
Il Gateway monitora il file openclaw.json. Quando lo modifichi,
le modifiche vengono applicate senza riavvio. Attenzione: se la
modifica e' invalida, il reload viene saltato e il runtime
continua con la configurazione precedente.
Un comando utile: openclaw config get <path> per leggere il valore
corrente senza aprire il file.
CHANNEL E POLICY
=============================================================
I canali si configurano sotto channels.<provider>. Ogni canale ha
le sue policy: dmPolicy (open, pairing, allowlist) e groupPolicy
(open, mention, disabled).
Per Telegram: botToken e allowFrom con array di user ID autorizzati.
Per WhatsApp: phoneNumberId, accessToken, webhookUrl.
Se non vuoi che sconosciuti parlino col tuo agente OpenClaw,
usa allowlist e allowFrom. E' piu' sicuro di open.
MULTI-AGENTE
=============================================================
Puoi definire piu' agenti in agents.list, ognuno con id, identity
(name, emoji, tema SOUL.md), workspace e override dei model.
Cambi agente con /agent <id> in qualsiasi canale.
Ogni agente ha la sua directory in ~/.openclaw/agents/<id>/ con
il suo SOUL.md che ne definisce personalita' e regole.
CONCLUSIONE
=============================================================
Configurare OpenClaw non e' difficile, ma richiede attenzione ai
dettagli. Parti dal Gateway, proteggi i segreti con .env, usa la
validazione strict per non sbagliare, e sfrutta il multi-agente
solo quando serve davvero.
La documentazione ufficiale su docs.openclaw.ai e' la fonte
piu' aggiornata. Usala come riferimento quando la configurazione
diventa complessa.
Per dubbi: openclaw doctor e' il tuo primo alleato.
Sent via AgentMail
Commenti
Posta un commento