Configurazione

TL;DR

Scegli un flusso di configurazione in base alla frequenza con cui vuoi ricevere aggiornamenti e al fatto che tu voglia eseguire personalmente il Gateway:

• La personalizzazione vive fuori dal repo: mantieni la configurazione e il workspace in ~/.openclaw/openclaw.json e ~/.openclaw/workspace/ così gli aggiornamenti del repo non li toccano.
• Flusso stabile (consigliato per la maggior parte degli utenti): installa l’app macOS e lascia che esegua il Gateway incluso.
• Flusso bleeding edge (dev): esegui tu il Gateway tramite pnpm gateway:watch, poi lascia che l’app macOS si colleghi in modalità Local.

Prerequisiti (da sorgente)

• Node 24 consigliato (Node 22 LTS, attualmente 22.16+, ancora supportato)
• pnpm richiesto per i checkout da sorgente. OpenClaw carica i plugins inclusi dai pacchetti workspace pnpm extensions/* in modalità dev, quindi npm install nella root non prepara l’intero albero sorgente.
• Docker (opzionale; solo per configurazione/e2e containerizzati - vedi Docker)

Strategia di personalizzazione (per evitare problemi con gli aggiornamenti)

Se vuoi una configurazione "100% su misura per me" e aggiornamenti semplici, mantieni la tua personalizzazione in:

• Configurazione: ~/.openclaw/openclaw.json (JSON/JSON5-ish)
• Workspace: ~/.openclaw/workspace (skills, prompt, memorie; rendilo un repo git privato)

Esegui il bootstrap una volta:

openclaw setup

Da dentro questo repo, usa l’entrypoint CLI locale:

openclaw setup

Se non hai ancora un’installazione globale, eseguilo tramite pnpm openclaw setup.

Eseguire il Gateway da questo repo

Dopo pnpm build, puoi eseguire direttamente la CLI pacchettizzata:

node openclaw.mjs gateway --port 18789 --verbose

Flusso stabile (prima l’app macOS)

1. Installa e avvia OpenClaw.app (barra dei menu).
2. Completa la checklist di onboarding/permessi (prompt TCC).
3. Assicurati che il Gateway sia Local e in esecuzione (l’app lo gestisce).
4. Collega le superfici (esempio: WhatsApp):

openclaw channels login

5. Controllo di integrità:

openclaw health

Se l’onboarding non è disponibile nella tua build:

• Esegui openclaw setup, poi openclaw channels login, quindi avvia manualmente il Gateway (openclaw gateway).

Flusso bleeding edge (Gateway in un terminale)

Obiettivo: lavorare sul Gateway TypeScript, ottenere hot reload, mantenere collegata l’interfaccia dell’app macOS.

0) (Opzionale) Esegui anche l’app macOS da sorgente

Se vuoi anche l’app macOS sul bleeding edge:

./scripts/restart-mac.sh

1) Avvia il Gateway dev

pnpm install# Solo la prima esecuzione (o dopo aver reimpostato la configurazione/workspace locale di OpenClaw)pnpm openclaw setuppnpm gateway:watch

gateway:watch avvia o riavvia il processo di watch del Gateway in una sessione tmux con nome e si collega automaticamente dai terminali interattivi. Le shell non interattive restano staccate e stampano tmux attach -t openclaw-gateway-watch-main; usa OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch per mantenere staccata un’esecuzione interattiva, oppure pnpm gateway:watch:raw per la modalità watch in foreground. Il watcher ricarica in caso di modifiche rilevanti a sorgenti, configurazione e metadati dei plugin inclusi. Se il Gateway osservato esce durante l’avvio, gateway:watch esegue openclaw doctor --fix --non-interactive una volta e riprova; imposta OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 per disabilitare quel passaggio di riparazione solo-dev. pnpm openclaw setup è il passaggio una tantum di inizializzazione della configurazione/workspace locale per un checkout nuovo. pnpm gateway:watch non ricostruisce dist/control-ui, quindi riesegui pnpm ui:build dopo modifiche a ui/ oppure usa pnpm ui:dev mentre sviluppi la Control UI.

2) Punta l’app macOS al Gateway in esecuzione

In OpenClaw.app:

• Connection Mode: Local L’app si collegherà al gateway in esecuzione sulla porta configurata.

3) Verifica

• Lo stato del Gateway nell’app dovrebbe indicare "Using existing gateway …"
• Oppure tramite CLI:

openclaw health

Problemi comuni

• Porta sbagliata: il WS del Gateway usa come default ws://127.0.0.1:18789; mantieni app e CLI sulla stessa porta.
• Dove vive lo stato:
  • Stato canale/provider: ~/.openclaw/credentials/
  • Profili di autenticazione modello: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Sessioni: ~/.openclaw/agents/<agentId>/sessions/
  • Log: /tmp/openclaw/

Mappa dello storage delle credenziali

Usala quando esegui il debug dell’autenticazione o decidi cosa sottoporre a backup:

• WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Token bot Telegram: config/env o channels.telegram.tokenFile (solo file normale; symlink rifiutati)
• Token bot Discord: config/env o SecretRef (provider env/file/exec)
• Token Slack: config/env (channels.slack.*)
• Allowlist di pairing:
  • ~/.openclaw/credentials/<channel>-allowFrom.json (account predefinito)
  • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (account non predefiniti)
• Profili di autenticazione modello: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• Payload di segreti basato su file (opzionale): ~/.openclaw/secrets.json
• Importazione OAuth legacy: ~/.openclaw/credentials/oauth.json Maggiori dettagli: Sicurezza.

Aggiornamento (senza rovinare la configurazione)

• Mantieni ~/.openclaw/workspace e ~/.openclaw/ come "le tue cose"; non inserire prompt/config personali nel repo openclaw.
• Aggiornamento del sorgente: git pull + pnpm install + continua a usare pnpm gateway:watch.

Linux (servizio utente systemd)

Le installazioni Linux usano un servizio systemd utente. Per impostazione predefinita, systemd arresta i servizi utente al logout/in inattività, cosa che termina il Gateway. L’onboarding tenta di abilitare il lingering per te (potrebbe chiedere sudo). Se è ancora disattivato, esegui:

sudo loginctl enable-linger $USER

Per server always-on o multiutente, considera invece un servizio system anziché un servizio utente (lingering non necessario). Consulta il runbook del Gateway per le note su systemd.

Documenti correlati

• Runbook del Gateway (flag, supervisione, porte)
• Configurazione del Gateway (schema config + esempi)
• Discord e Telegram (tag di risposta + impostazioni replyToMode)
• Configurazione dell’assistente OpenClaw
• App macOS (ciclo di vita del gateway)