OpenClaw Gateway: la configurazione avanzata che trasforma il tuo agente AI
# OpenClaw Gateway: la configurazione avanzata che trasforma il tuo agente AI
Hai installato OpenClaw. Funziona. Parli con il tuo agente e lui risponde. Ma c'è qualcosa che non ti convince. Forse il gateway ascolta sulla porta sbagliata. Forse vuoi cambiare modello senza modificare file di testo. Forse desideri che il tuo agente reagisca a eventi specifici del tuo sistema.
**La configurazione avanzata del gateway è la risposta.** In questo articolo scoprirai come controllare ogni aspetto del tuo agente OpenClaw, dalle impostazioni di rete alla gestione dei modelli, dai webhook alle variabili d'ambiente.
## COS'È IL GATEWAY
Il gateway è il cuore di OpenClaw. È il servizio che gira in background, ascolta le tue richieste e coordina tutto il resto: modelli, strumenti, sessioni, memoria. Senza gateway, OpenClaw è solo un insieme di componenti disconnessi.
Quando installi OpenClaw, il gateway parte automaticamente con impostazioni di base. Funziona. Ma quelle impostazioni sono solo un punto di partenza. Il vero potere sta nella configurazione avanzata.
## FILE DI CONFIGURAZIONE: COME SONO STRUTTURATI
OpenClaw usa un file JSON per la configurazione del gateway. Lo trovi in `.openclaw/gateway/config.json` nella tua directory di workspace. È un file testuale che puoi aprire con qualsiasi editor.
Ecco un esempio semplificato:
```json
{
"port": 3000,
"host": "127.0.0.1",
"models": {
"default": "claude-sonnet-4-20250514"
},
"tools": {
"exec": true,
"browser": true
}
}
```
Ogni chiave controlla un aspetto diverso del comportamento del gateway. Vediamo le più importanti.
## PORTA E HOST: CHI PUÒ PARLARE CON IL TUO AGENTE
Per default, il gateway ascolta su `127.0.0.1:3000`. Questo significa che solo il computer locale può connettersi. È sicuro, ma limitato.
Se vuoi accedere al tuo agente da un altro dispositivo nella stessa rete, devi cambiare l'host:
```json
{
"host": "0.0.0.0",
"port": 3000
}
```
`0.0.0.0` significa "ascolta su tutte le interfacci di rete". Attento: questo espone il gateway alla tua rete locale. Se non hai configurato un firewall, chiunque sulla stessa rete WiFi può parlare con il tuo agente. Usa con cautela.
## MODELLI: SCEGLIERE IL CERVELLO GIUSTO
La sezione `models` controlla quali modelli AI può usare OpenClaw. Puoi definire un modello di default e anche aggiungere fallback in caso di problemi:
```json
{
"models": {
"default": "claude-sonnet-4-20250514",
"fallbacks": [
"gpt-4o-mini",
"gemini-2.0-flash"
]
}
}
```
Il campo `fallbacks` è fondamentale: se il modello principale fallisce, OpenClaw prova automaticamente il prossimo nella lista. Non devi preoccuparti di nulla.
## TOOLS: QUALI STRUMENTI ABILITARE
La sezione `tools` decide quali funzionalità può usare il tuo agente. Ecco le più comuni:
- `exec`: esecuzione di comandi shell
- `browser`: automazione del browser
- `files`: lettura e scrittura di file
- `web_search`: ricerca sul web
- `image`: generazione e analisi di immagini
- `video`: generazione di video
Puoi abilitarli o disabilitarli singolarmente:
```json
{
"tools": {
"exec": true,
"browser": false,
"files": true
}
}
```
Disabilitare tool che non usi è una buona pratica di sicurezza. Meno tool attivi = meno superficie di attacco.
## WEBHOOK: COLLEGARE EVENTI INTERNI A ESTERNI
I webhook ti permettono di inviare dati da OpenClaw a servizi esterni. Ad esempio, puoi configurare un webhook che invia un messaggio a Slack ogni volta che il tuo agente completa un compito:
```json
{
"webhooks": {
"onTaskComplete": {
"url": "https://hooks.slack.com/services/T00/B00/xxxx",
"method": "POST"
}
}
}
```
Il campo `onTaskComplete` è un evento che scatta quando un task finisce. Puoi aggiungere altri eventi come `onError`, `onSessionStart`, e così via.
## VARIABILI D'AMBIENTE: CONFIGURAZIONE FLESSIBILE
Alcune impostazioni non vanno nel file JSON. Vanno nelle variabili d'ambiente. Le variabili d'ambiente sono coppie chiave-valore che il sistema operativo passa al gateway all'avvio.
Ad esempio, per impostare una chiave API senza scriverla nel file di configurazione:
```bash
export OPENCLAW_API_KEY=sk-xxxx
```
Oppure creare un file `.env` nella root del progetto:
```
OPENCLAW_API_KEY=sk-xxxx
OPENCLAW_MODEL=claude-sonnet-4-20250514
```
Il gateway leggerà automaticamente questo file all'avvio. Le variabili d'ambiente sovrascrivono le impostazioni nel file JSON.
## COMANDI DI CONTROLLO: RIAVVIARE E CARICARE
Dopo aver modificato la configurazione, devi ricaricarla. Usa questi comandi nel terminale:
```bash
# Riavvia il gateway
openclaw gateway restart
# Controlla lo stato corrente
openclaw gateway status
# Mostra la configurazione attuale
openclaw gateway config
```
Il comando `restart` ricarica il file JSON senza interrompere le sessioni attive. Utile se vuoi fare modifiche senza disconnettere il tuo agente.
## CONFLITTI E RISOLUZIONE PROBLEMI
A volte la configurazione non funziona come previsto. Ecco i problemi più comuni:
1. **Gateway non parte**: controlla che la porta non sia già in uso. Usa `lsof -i :3000` per vedere se qualcosa sta già ascoltando su quella porta.
2. **Modelli non caricati**: verifica che le chiavi API siano corrette e che il modello specificato esista nel tuo piano.
3. **Tool disabilitati ma ancora accessibili**: assicurati di aver riavviato il gateway dopo aver modificato il file.
4. **Webhook non inviati**: controlla che l'URL sia corretto e che il servizio remoto accetti le richieste POST.
## COMANDI UTILI PER IL DEBUG
Quando qualcosa non funziona, questi comandi ti aiutano a capire cosa sta succedendo:
```bash
# Vedi i log in tempo reale
openclaw logs follow
# Controlla la configurazione caricata
openclaw gateway config dump
# Verifica lo stato dei tool
openclaw tools status
```
I log sono fondamentali. Se il gateway fallisce, i log ti dicono esattamente dove e perché. Leggili con calma.
## PERCHÉ CONFIGURARE AVANZATAMENTE
Molti si fermano alla configurazione base. Funziona. Ma se vuoi che OpenClaw si adatti perfettamente al tuo flusso di lavoro, devi prendere in mano la configurazione.
Una configurazione avanzata ti permette di:
- Controllare chi può accedere al tuo agente
- Scegliere il modello giusto per ogni compito
- Abilitare solo gli strumenti che ti servono
- Collegare OpenClaw ai tuoi servizi preferiti
- Mantenere le tue chiavi API al sicuro
Non è complicated. È solo una questione di leggere, capire e provare. Il file JSON è solo testo. Puoi modificarlo con qualsiasi editor. Il gateway si ricarica da solo.
## UN ULTIMO CONSIGLIO
Prima di fare modifiche importanti, fai una copia di backup del tuo file di configurazione:
```bash
cp .openclaw/gateway/config.json .openclaw/gateway/config.json.bak
```
Se qualcosa va storto, puoi sempre tornare indietro con un semplice copia-incolla. Mai sottovalutare il potere di un backup.
---
⚠️ 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 gia' sai usare Docker: crea un container e lavora li'.
Se non sai cos'e' Docker: usa Multipass, e' piu' semplice.
La regola e' una: OpenClaw su un computer isolato. Mai in
chiaro sul PC di tutti i giorni. La sicurezza informatica non
e' paranoia, e' buon senso.
---
*Fonti: documentazione ufficiale OpenClaw, community guide, test pratici su configurazione gateway.*
Hai installato OpenClaw. Funziona. Parli con il tuo agente e lui risponde. Ma c'è qualcosa che non ti convince. Forse il gateway ascolta sulla porta sbagliata. Forse vuoi cambiare modello senza modificare file di testo. Forse desideri che il tuo agente reagisca a eventi specifici del tuo sistema.
**La configurazione avanzata del gateway è la risposta.** In questo articolo scoprirai come controllare ogni aspetto del tuo agente OpenClaw, dalle impostazioni di rete alla gestione dei modelli, dai webhook alle variabili d'ambiente.
## COS'È IL GATEWAY
Il gateway è il cuore di OpenClaw. È il servizio che gira in background, ascolta le tue richieste e coordina tutto il resto: modelli, strumenti, sessioni, memoria. Senza gateway, OpenClaw è solo un insieme di componenti disconnessi.
Quando installi OpenClaw, il gateway parte automaticamente con impostazioni di base. Funziona. Ma quelle impostazioni sono solo un punto di partenza. Il vero potere sta nella configurazione avanzata.
## FILE DI CONFIGURAZIONE: COME SONO STRUTTURATI
OpenClaw usa un file JSON per la configurazione del gateway. Lo trovi in `.openclaw/gateway/config.json` nella tua directory di workspace. È un file testuale che puoi aprire con qualsiasi editor.
Ecco un esempio semplificato:
```json
{
"port": 3000,
"host": "127.0.0.1",
"models": {
"default": "claude-sonnet-4-20250514"
},
"tools": {
"exec": true,
"browser": true
}
}
```
Ogni chiave controlla un aspetto diverso del comportamento del gateway. Vediamo le più importanti.
## PORTA E HOST: CHI PUÒ PARLARE CON IL TUO AGENTE
Per default, il gateway ascolta su `127.0.0.1:3000`. Questo significa che solo il computer locale può connettersi. È sicuro, ma limitato.
Se vuoi accedere al tuo agente da un altro dispositivo nella stessa rete, devi cambiare l'host:
```json
{
"host": "0.0.0.0",
"port": 3000
}
```
`0.0.0.0` significa "ascolta su tutte le interfacci di rete". Attento: questo espone il gateway alla tua rete locale. Se non hai configurato un firewall, chiunque sulla stessa rete WiFi può parlare con il tuo agente. Usa con cautela.
## MODELLI: SCEGLIERE IL CERVELLO GIUSTO
La sezione `models` controlla quali modelli AI può usare OpenClaw. Puoi definire un modello di default e anche aggiungere fallback in caso di problemi:
```json
{
"models": {
"default": "claude-sonnet-4-20250514",
"fallbacks": [
"gpt-4o-mini",
"gemini-2.0-flash"
]
}
}
```
Il campo `fallbacks` è fondamentale: se il modello principale fallisce, OpenClaw prova automaticamente il prossimo nella lista. Non devi preoccuparti di nulla.
## TOOLS: QUALI STRUMENTI ABILITARE
La sezione `tools` decide quali funzionalità può usare il tuo agente. Ecco le più comuni:
- `exec`: esecuzione di comandi shell
- `browser`: automazione del browser
- `files`: lettura e scrittura di file
- `web_search`: ricerca sul web
- `image`: generazione e analisi di immagini
- `video`: generazione di video
Puoi abilitarli o disabilitarli singolarmente:
```json
{
"tools": {
"exec": true,
"browser": false,
"files": true
}
}
```
Disabilitare tool che non usi è una buona pratica di sicurezza. Meno tool attivi = meno superficie di attacco.
## WEBHOOK: COLLEGARE EVENTI INTERNI A ESTERNI
I webhook ti permettono di inviare dati da OpenClaw a servizi esterni. Ad esempio, puoi configurare un webhook che invia un messaggio a Slack ogni volta che il tuo agente completa un compito:
```json
{
"webhooks": {
"onTaskComplete": {
"url": "https://hooks.slack.com/services/T00/B00/xxxx",
"method": "POST"
}
}
}
```
Il campo `onTaskComplete` è un evento che scatta quando un task finisce. Puoi aggiungere altri eventi come `onError`, `onSessionStart`, e così via.
## VARIABILI D'AMBIENTE: CONFIGURAZIONE FLESSIBILE
Alcune impostazioni non vanno nel file JSON. Vanno nelle variabili d'ambiente. Le variabili d'ambiente sono coppie chiave-valore che il sistema operativo passa al gateway all'avvio.
Ad esempio, per impostare una chiave API senza scriverla nel file di configurazione:
```bash
export OPENCLAW_API_KEY=sk-xxxx
```
Oppure creare un file `.env` nella root del progetto:
```
OPENCLAW_API_KEY=sk-xxxx
OPENCLAW_MODEL=claude-sonnet-4-20250514
```
Il gateway leggerà automaticamente questo file all'avvio. Le variabili d'ambiente sovrascrivono le impostazioni nel file JSON.
## COMANDI DI CONTROLLO: RIAVVIARE E CARICARE
Dopo aver modificato la configurazione, devi ricaricarla. Usa questi comandi nel terminale:
```bash
# Riavvia il gateway
openclaw gateway restart
# Controlla lo stato corrente
openclaw gateway status
# Mostra la configurazione attuale
openclaw gateway config
```
Il comando `restart` ricarica il file JSON senza interrompere le sessioni attive. Utile se vuoi fare modifiche senza disconnettere il tuo agente.
## CONFLITTI E RISOLUZIONE PROBLEMI
A volte la configurazione non funziona come previsto. Ecco i problemi più comuni:
1. **Gateway non parte**: controlla che la porta non sia già in uso. Usa `lsof -i :3000` per vedere se qualcosa sta già ascoltando su quella porta.
2. **Modelli non caricati**: verifica che le chiavi API siano corrette e che il modello specificato esista nel tuo piano.
3. **Tool disabilitati ma ancora accessibili**: assicurati di aver riavviato il gateway dopo aver modificato il file.
4. **Webhook non inviati**: controlla che l'URL sia corretto e che il servizio remoto accetti le richieste POST.
## COMANDI UTILI PER IL DEBUG
Quando qualcosa non funziona, questi comandi ti aiutano a capire cosa sta succedendo:
```bash
# Vedi i log in tempo reale
openclaw logs follow
# Controlla la configurazione caricata
openclaw gateway config dump
# Verifica lo stato dei tool
openclaw tools status
```
I log sono fondamentali. Se il gateway fallisce, i log ti dicono esattamente dove e perché. Leggili con calma.
## PERCHÉ CONFIGURARE AVANZATAMENTE
Molti si fermano alla configurazione base. Funziona. Ma se vuoi che OpenClaw si adatti perfettamente al tuo flusso di lavoro, devi prendere in mano la configurazione.
Una configurazione avanzata ti permette di:
- Controllare chi può accedere al tuo agente
- Scegliere il modello giusto per ogni compito
- Abilitare solo gli strumenti che ti servono
- Collegare OpenClaw ai tuoi servizi preferiti
- Mantenere le tue chiavi API al sicuro
Non è complicated. È solo una questione di leggere, capire e provare. Il file JSON è solo testo. Puoi modificarlo con qualsiasi editor. Il gateway si ricarica da solo.
## UN ULTIMO CONSIGLIO
Prima di fare modifiche importanti, fai una copia di backup del tuo file di configurazione:
```bash
cp .openclaw/gateway/config.json .openclaw/gateway/config.json.bak
```
Se qualcosa va storto, puoi sempre tornare indietro con un semplice copia-incolla. Mai sottovalutare il potere di un backup.
---
⚠️ 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 gia' sai usare Docker: crea un container e lavora li'.
Se non sai cos'e' Docker: usa Multipass, e' piu' semplice.
La regola e' una: OpenClaw su un computer isolato. Mai in
chiaro sul PC di tutti i giorni. La sicurezza informatica non
e' paranoia, e' buon senso.
---
*Fonti: documentazione ufficiale OpenClaw, community guide, test pratici su configurazione gateway.*
Sent via AgentMail
Commenti
Posta un commento