Domande frequenti

OpenClaw è un assistente IA personale che esegui sui tuoi dispositivi. Risponde sulle superfici di messaggistica che usi già (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat e Plugin di canale inclusi come QQ Bot) e può anche gestire voce + un Canvas live sulle piattaforme supportate. Il Gateway è il piano di controllo sempre attivo; l'assistente è il prodotto.

OpenClaw non è "solo un wrapper per Claude." È un piano di controllo local-first che ti permette di eseguire un assistente capace sul tuo hardware, raggiungibile dalle app di chat che usi già, con sessioni stateful, memoria e strumenti, senza cedere il controllo dei tuoi workflow a un SaaS ospitato.

Punti salienti:

• I tuoi dispositivi, i tuoi dati: esegui il Gateway dove vuoi (Mac, Linux, VPS) e mantieni workspace + cronologia delle sessioni in locale.
• Canali reali, non una sandbox web: WhatsApp/Telegram/Slack/Discord/Signal/iMessage/ecc., più voce mobile e Canvas sulle piattaforme supportate.
• Agnostico rispetto ai modelli: usa Anthropic, OpenAI, MiniMax, OpenRouter, ecc., con instradamento e failover per agente.
• Opzione solo locale: esegui modelli locali così tutti i dati possono restare sul tuo dispositivo se vuoi.
• Instradamento multi-agente: agenti separati per canale, account o attività, ciascuno con il proprio workspace e i propri valori predefiniti.
• Open source e modificabile: ispeziona, estendi e fai self-hosting senza lock-in del fornitore.

Documentazione: Gateway, Canali, Multi-agente, Memoria.

Buoni primi progetti:

• Crea un sito web (WordPress, Shopify o un semplice sito statico).
• Prototipa un'app mobile (schema, schermate, piano API).
• Organizza file e cartelle (pulizia, denominazione, tagging).
• Collega Gmail e automatizza riepiloghi o follow-up.

Può gestire attività grandi, ma funziona meglio quando le dividi in fasi e usi sub-agenti per il lavoro in parallelo.

I vantaggi quotidiani di solito sono:

• Briefing personali: riepiloghi di inbox, calendario e notizie che ti interessano.
• Ricerca e stesura: ricerca rapida, riepiloghi e prime bozze per email o documenti.
• Promemoria e follow-up: solleciti ed elenchi di controllo guidati da Cron o Heartbeat.
• Automazione del browser: compilazione di moduli, raccolta di dati e ripetizione di attività web.
• Coordinamento tra dispositivi: invia un'attività dal telefono, lascia che il Gateway la esegua su un server e ricevi il risultato in chat.

Sì, per ricerca, qualificazione e stesura. Può scansionare siti, creare shortlist, riepilogare prospect e scrivere bozze di outreach o testi per annunci.

Per outreach o campagne pubblicitarie, mantieni un essere umano nel ciclo. Evita lo spam, rispetta le leggi locali e le policy delle piattaforme, e rivedi tutto prima dell'invio. Il modello più sicuro è lasciare che OpenClaw prepari la bozza e che tu approvi.

Documentazione: Sicurezza.

OpenClaw è un assistente personale e un livello di coordinamento, non un sostituto dell'IDE. Usa Claude Code o Codex per il loop di coding diretto più veloce dentro un repository. Usa OpenClaw quando vuoi memoria duratura, accesso tra dispositivi e orchestrazione degli strumenti.

Vantaggi:

• Memoria persistente + workspace tra sessioni
• Accesso multipiattaforma (WhatsApp, Telegram, TUI, WebChat)
• Orchestrazione degli strumenti (browser, file, pianificazione, hook)
• Gateway sempre attivo (esegui su un VPS, interagisci da ovunque)
• Nodes per browser/schermo/fotocamera/exec locali

Showcase: https://openclaw.ai/showcase

Usa override gestiti invece di modificare la copia del repository. Inserisci le modifiche in ~/.openclaw/skills/<name>/SKILL.md (oppure aggiungi una cartella tramite skills.load.extraDirs in ~/.openclaw/openclaw.json). La precedenza è <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → incluse → skills.load.extraDirs, quindi gli override gestiti hanno comunque priorità sulle skills incluse senza toccare git. Se ti serve che la skill sia installata globalmente ma visibile solo ad alcuni agenti, mantieni la copia condivisa in ~/.openclaw/skills e controlla la visibilità con agents.defaults.skills e agents.list[].skills. Solo le modifiche adatte all'upstream dovrebbero vivere nel repository e uscire come PR.

Sì. Aggiungi directory extra tramite skills.load.extraDirs in ~/.openclaw/openclaw.json (precedenza più bassa). La precedenza predefinita è <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → incluse → skills.load.extraDirs. clawhub installa in ./skills per impostazione predefinita, che OpenClaw tratta come <workspace>/skills nella sessione successiva. Se la skill deve essere visibile solo a certi agenti, abbinala a agents.defaults.skills o agents.list[].skills.

Oggi i modelli supportati sono:

• Job Cron: i job isolati possono impostare un override model per job.
• Sub-agenti: instrada le attività ad agenti separati con modelli predefiniti diversi.
• Cambio su richiesta: usa /model per cambiare il modello della sessione corrente in qualsiasi momento.

Vedi Job Cron, Instradamento multi-agente e Comandi slash.

Usa sub-agenti per attività lunghe o in parallelo. I sub-agenti vengono eseguiti nella propria sessione, restituiscono un riepilogo e mantengono reattiva la chat principale.

Chiedi al tuo bot di "creare un sub-agente per questa attività" oppure usa /subagents. Usa /status in chat per vedere cosa sta facendo il Gateway in questo momento (e se è occupato).

Suggerimento sui token: le attività lunghe e i sub-agenti consumano entrambi token. Se il costo è un problema, imposta un modello più economico per i sub-agenti tramite agents.defaults.subagents.model.

Documentazione: Sub-agenti, Attività in background.

Usa i binding dei thread. Puoi vincolare un thread Discord a un subagente o a una destinazione di sessione, così i messaggi successivi in quel thread restano su quella sessione vincolata.

Flusso di base:

• Crea con sessions_spawn usando thread: true (e opzionalmente mode: "session" per follow-up persistenti).
• Oppure vincola manualmente con /focus <target>.
• Usa /agents per ispezionare lo stato del binding.
• Usa /session idle <duration|off> e /session max-age <duration|off> per controllare l'auto-unfocus.
• Usa /unfocus per scollegare il thread.

Configurazione richiesta:

• Valori predefiniti globali: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
• Override Discord: channels.discord.threadBindings.enabled, channels.discord.threadBindings.idleHours, channels.discord.threadBindings.maxAgeHours.
• Auto-bind alla creazione: channels.discord.threadBindings.spawnSessions ha valore predefinito true; impostalo a false per disabilitare la creazione di sessioni vincolate ai thread.

Documentazione: Sub-agenti, Discord, Riferimento della configurazione, Comandi slash.

Controlla prima la route risolta del richiedente:

• La consegna dei subagenti in modalità completamento preferisce qualsiasi thread vincolato o route di conversazione quando esiste.
• Se l'origine del completamento contiene solo un canale, OpenClaw ripiega sulla route memorizzata della sessione richiedente (lastChannel / lastTo / lastAccountId) così la consegna diretta può comunque riuscire.
• Se non esiste né una route vincolata né una route memorizzata utilizzabile, la consegna diretta può fallire e il risultato ripiega sulla consegna in coda alla sessione invece di essere pubblicato subito in chat.
• Destinazioni non valide o obsolete possono comunque forzare il fallback in coda o il fallimento finale della consegna.
• Se l'ultima risposta visibile dell'assistente figlio è l'esatto token silenzioso NO_REPLY / no_reply, o esattamente ANNOUNCE_SKIP, OpenClaw sopprime intenzionalmente l'annuncio invece di pubblicare progressi precedenti obsoleti.
• Se il figlio è scaduto dopo sole chiamate a strumenti, l'annuncio può comprimerle in un breve riepilogo di avanzamento parziale invece di riprodurre l'output grezzo degli strumenti.

Debug:

openclaw tasks show <runId-or-sessionKey>

Documentazione: Sub-agenti, Attività in background, Strumenti di sessione.

Cron viene eseguito dentro il processo Gateway. Se il Gateway non è in esecuzione continuamente, i job pianificati non verranno eseguiti.

Checklist:

• Conferma che cron sia abilitato (cron.enabled) e che OPENCLAW_SKIP_CRON non sia impostato.
• Controlla che il Gateway sia in esecuzione 24/7 (niente sospensione/riavvii).
• Verifica le impostazioni del fuso orario per il job (--tz rispetto al fuso orario dell'host).

Debug:

openclaw cron run <jobId>openclaw cron runs --id <jobId> --limit 50

Documentazione: Job Cron, Automazione.

Controlla prima la modalità di consegna:

• --no-deliver / delivery.mode: "none" significa che non è previsto alcun invio fallback da parte del runner.
• Una destinazione di annuncio mancante o non valida (channel / to) significa che il runner ha saltato la consegna in uscita.
• Errori di autenticazione del canale (unauthorized, Forbidden) significano che il runner ha provato a consegnare, ma le credenziali lo hanno bloccato.
• Un risultato isolato silenzioso (solo NO_REPLY / no_reply) viene trattato come intenzionalmente non consegnabile, quindi il runner sopprime anche la consegna fallback in coda.

Per i job cron isolati, l'agente può comunque inviare direttamente con lo strumento message quando è disponibile una rotta chat. --announce controlla solo il percorso fallback del runner per il testo finale che l'agente non ha già inviato.

Debug:

openclaw cron runs --id <jobId> --limit 50openclaw tasks show <runId-or-sessionKey>

Documentazione: job Cron, attività in background.

Di solito si tratta del percorso di cambio modello live, non di una pianificazione duplicata.

Cron isolato può mantenere un passaggio del modello di runtime e riprovare quando l'esecuzione attiva genera LiveSessionModelSwitchError. Il nuovo tentativo mantiene il provider/modello selezionato dal cambio e, se il cambio includeva un nuovo override del profilo di autenticazione, Cron mantiene anche quello prima di riprovare.

Regole di selezione correlate:

• L'override del modello dell'hook Gmail ha la precedenza quando applicabile.
• Poi model per job.
• Poi qualsiasi override del modello memorizzato per la sessione Cron.
• Poi la normale selezione del modello dell'agente/predefinito.

Il ciclo di nuovi tentativi è limitato. Dopo il tentativo iniziale più 2 nuovi tentativi di cambio, Cron interrompe invece di restare in ciclo all'infinito.

Debug:

openclaw cron runs --id <jobId> --limit 50openclaw tasks show <runId-or-sessionKey>

Documentazione: job Cron, CLI Cron.

Usa i comandi nativi openclaw skills o inserisci le Skills nel tuo workspace. L'interfaccia utente Skills di macOS non è disponibile su Linux. Sfoglia le Skills su https://clawhub.ai.

openclaw skills search "calendar"openclaw skills search --limit 20openclaw skills install <skill-slug>openclaw skills install <skill-slug> --version <version>openclaw skills install <skill-slug> --forceopenclaw skills update --allopenclaw skills list --eligibleopenclaw skills check

openclaw skills install nativo scrive nella directory skills/ del workspace attivo. Installa la CLI clawhub separata solo se vuoi pubblicare o sincronizzare le tue Skills. Per installazioni condivise tra agenti, metti la Skill in ~/.openclaw/skills e usa agents.defaults.skills o agents.list[].skills se vuoi restringere quali agenti possono vederla.

Sì. Usa lo scheduler del Gateway:

• job Cron per attività pianificate o ricorrenti (persistono tra i riavvii).
• Heartbeat per controlli periodici della "sessione principale".
• Job isolati per agenti autonomi che pubblicano riepiloghi o consegnano alle chat.

Documentazione: job Cron, automazione, Heartbeat.

Non direttamente. Le Skills per macOS sono limitate da metadata.openclaw.os più i binari richiesti, e le Skills compaiono nel prompt di sistema solo quando sono idonee sull'host del Gateway. Su Linux, le Skills solo darwin (come apple-notes, apple-reminders, things-mac) non verranno caricate a meno che tu non esegua l'override del gating.

Hai tre schemi supportati:

Opzione A - esegui il Gateway su un Mac (la più semplice). Esegui il Gateway dove esistono i binari macOS, poi connettiti da Linux in modalità remota o tramite Tailscale. Le Skills vengono caricate normalmente perché l'host del Gateway è macOS.

Opzione B - usa un nodo macOS (senza SSH). Esegui il Gateway su Linux, associa un nodo macOS (app nella barra dei menu) e imposta Node Run Commands su "Always Ask" o "Always Allow" sul Mac. OpenClaw può considerare idonee le Skills solo macOS quando i binari richiesti esistono sul nodo. L'agente esegue quelle Skills tramite lo strumento nodes. Se scegli "Always Ask", approvare "Always Allow" nel prompt aggiunge quel comando all'allowlist.

Opzione C - proxy dei binari macOS tramite SSH (avanzato). Mantieni il Gateway su Linux, ma fai in modo che i binari CLI richiesti si risolvano in wrapper SSH che vengono eseguiti su un Mac. Poi esegui l'override della Skill per consentire Linux, così resta idonea.

1. Crea un wrapper SSH per il binario (esempio: memo per Apple Notes):

   #!/usr/bin/env bashset -euo pipefailexec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"

2. Metti il wrapper in PATH sull'host Linux (ad esempio ~/bin/memo).

3. Esegui l'override dei metadati della Skill (workspace o ~/.openclaw/skills) per consentire Linux:

   ---name: apple-notesdescription: Manage Apple Notes via the memo CLI on macOS.metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }---

4. Avvia una nuova sessione in modo che lo snapshot delle Skills venga aggiornato.

Al momento non integrata.

Opzioni:

• Skill / Plugin personalizzato: soluzione migliore per accesso API affidabile (Notion/HeyGen hanno entrambe API).
• Automazione del browser: funziona senza codice, ma è più lenta e più fragile.

Se vuoi mantenere il contesto per cliente (flussi di lavoro di agenzia), uno schema semplice è:

• Una pagina Notion per cliente (contesto + preferenze + lavoro attivo).
• Chiedi all'agente di recuperare quella pagina all'inizio di una sessione.

Se vuoi un'integrazione nativa, apri una richiesta di funzionalità o crea una Skill mirata a quelle API.

Installa le Skills:

openclaw skills install <skill-slug>openclaw skills update --all

Le installazioni native finiscono nella directory skills/ del workspace attivo. Per Skills condivise tra agenti, mettile in ~/.openclaw/skills/<name>/SKILL.md. Se solo alcuni agenti devono vedere un'installazione condivisa, configura agents.defaults.skills o agents.list[].skills. Alcune Skills si aspettano binari installati tramite Homebrew; su Linux questo significa Linuxbrew (vedi la voce FAQ di Homebrew Linux sopra). Vedi Skills, configurazione Skills e ClawHub.

Usa il profilo browser integrato user, che si collega tramite Chrome DevTools MCP:

openclaw browser --browser-profile user tabsopenclaw browser --browser-profile user snapshot

Se vuoi un nome personalizzato, crea un profilo MCP esplicito:

openclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser --browser-profile chrome-live tabs

Questo percorso può usare il browser host locale o un nodo browser connesso. Se il Gateway viene eseguito altrove, esegui un host nodo sulla macchina del browser oppure usa invece CDP remoto.

Limiti attuali su existing-session / user:

• le azioni sono basate su ref, non su selettori CSS
• i caricamenti richiedono ref / inputRef e attualmente supportano un file alla volta
• responsebody, esportazione PDF, intercettazione dei download e azioni batch richiedono ancora un browser gestito o un profilo CDP raw

Sì. Vedi isolamento in sandbox. Per la configurazione specifica di Docker (Gateway completo in Docker o immagini sandbox), vedi Docker.

L'immagine predefinita privilegia la sicurezza e viene eseguita come utente node, quindi non include pacchetti di sistema, Homebrew o browser inclusi. Per una configurazione più completa:

• Mantieni /home/node con OPENCLAW_HOME_VOLUME così le cache sopravvivono.
• Integra le dipendenze di sistema nell'immagine con OPENCLAW_DOCKER_APT_PACKAGES.
• Installa i browser Playwright tramite la CLI inclusa: node /app/node_modules/playwright-core/cli.js install chromium
• Imposta PLAYWRIGHT_BROWSERS_PATH e assicurati che il percorso sia mantenuto.

Documentazione: Docker, browser.

Sì, se il traffico privato è costituito da DM e il traffico pubblico da gruppi.

Usa agents.defaults.sandbox.mode: "non-main" così le sessioni di gruppo/canale (chiavi non principali) vengono eseguite nel backend sandbox configurato, mentre la sessione DM principale resta sull'host. Docker è il backend predefinito se non ne scegli uno. Poi limita quali strumenti sono disponibili nelle sessioni in sandbox tramite tools.sandbox.tools.

Guida alla configurazione + esempio di configurazione: Gruppi: DM personali + gruppi pubblici

Riferimento di configurazione principale: configurazione del Gateway

Imposta agents.defaults.sandbox.docker.binds su ["host:path:mode"] (ad esempio, "/home/user/src:/src:ro"). I bind globali e per agente vengono uniti; i bind per agente vengono ignorati quando scope: "shared". Usa :ro per tutto ciò che è sensibile e ricorda che i bind aggirano le pareti del filesystem della sandbox.

OpenClaw convalida le sorgenti dei bind sia rispetto al percorso normalizzato sia rispetto al percorso canonico risolto tramite l'antenato esistente più profondo. Questo significa che le fughe tramite genitori symlink continuano a fallire in modo chiuso anche quando l'ultimo segmento del percorso non esiste ancora, e i controlli sulle radici consentite continuano ad applicarsi dopo la risoluzione dei symlink.

Vedi isolamento in sandbox e Sandbox vs criterio degli strumenti vs privilegi elevati per esempi e note di sicurezza.

La memoria di OpenClaw è composta semplicemente da file Markdown nel workspace dell'agente:

• Note giornaliere in memory/YYYY-MM-DD.md
• Note curate a lungo termine in MEMORY.md (solo sessioni principali/private)

OpenClaw esegue anche un flush di memoria silenzioso pre-Compaction per ricordare al modello di scrivere note durevoli prima della Compaction automatica. Questo viene eseguito solo quando il workspace è scrivibile (le sandbox in sola lettura lo saltano). Vedi memoria.

Chiedi al bot di scrivere il fatto in memoria. Le note a lungo termine vanno in MEMORY.md, il contesto a breve termine va in memory/YYYY-MM-DD.md.

Questa è ancora un'area che stiamo migliorando. Aiuta ricordare al modello di memorizzare i ricordi; saprà cosa fare. Se continua a dimenticare, verifica che il Gateway stia usando lo stesso workspace a ogni esecuzione.

Documentazione: memoria, workspace dell'agente.

I file di memoria vivono su disco e persistono finché non li elimini. Il limite è il tuo spazio di archiviazione, non il modello. Il contesto di sessione è comunque limitato dalla finestra di contesto del modello, quindi le conversazioni lunghe possono essere compattate o troncate. Ecco perché esiste la ricerca in memoria: riporta nel contesto solo le parti rilevanti.

Documentazione: memoria, contesto.

Solo se usi gli embedding OpenAI. Codex OAuth copre chat/completions e non concede accesso agli embedding, quindi accedere con Codex (OAuth o il login della CLI Codex) non aiuta per la ricerca semantica nella memoria. Gli embedding OpenAI richiedono comunque una vera chiave API (OPENAI_API_KEY o models.providers.openai.apiKey).

Se non imposti esplicitamente un provider, OpenClaw seleziona automaticamente un provider quando riesce a risolvere una chiave API (profili di autenticazione, models.providers.*.apiKey o variabili d'ambiente). Preferisce OpenAI se risolve una chiave OpenAI, altrimenti Gemini se risolve una chiave Gemini, poi Voyage, poi Mistral. Se non è disponibile alcuna chiave remota, la ricerca nella memoria resta disabilitata finché non la configuri. Se hai un percorso di modello locale configurato e presente, OpenClaw preferisce local. Ollama è supportato quando imposti esplicitamente memorySearch.provider = "ollama".

Se preferisci restare in locale, imposta memorySearch.provider = "local" (e facoltativamente memorySearch.fallback = "none"). Se vuoi gli embedding Gemini, imposta memorySearch.provider = "gemini" e fornisci GEMINI_API_KEY (o memorySearch.remote.apiKey). Supportiamo modelli di embedding OpenAI, Gemini, Voyage, Mistral, Ollama o locali: vedi Memoria per i dettagli di configurazione.

No: lo stato di OpenClaw è locale, ma i servizi esterni vedono comunque ciò che invii loro.

• Locale per impostazione predefinita: sessioni, file di memoria, configurazione e workspace si trovano sull'host del Gateway (~/.openclaw + la directory del tuo workspace).
• Remoto per necessità: i messaggi che invii ai provider di modelli (Anthropic/OpenAI/ecc.) vanno alle loro API, e le piattaforme di chat (WhatsApp/Telegram/Slack/ecc.) archiviano i dati dei messaggi sui loro server.
• Controlli tu l'impronta: usare modelli locali mantiene i prompt sulla tua macchina, ma il traffico dei canali passa comunque attraverso i server del canale.

Correlati: Workspace dell'agente, Memoria.

Tutto si trova sotto $OPENCLAW_STATE_DIR (predefinito: ~/.openclaw):

Percorso legacy per agente singolo: ~/.openclaw/agent/* (migrato da openclaw doctor).

Il tuo workspace (AGENTS.md, file di memoria, Skills, ecc.) è separato e configurato tramite agents.defaults.workspace (predefinito: ~/.openclaw/workspace).

Questi file si trovano nel workspace dell'agente, non in ~/.openclaw.

• Workspace (per agente): AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md, memory/YYYY-MM-DD.md, HEARTBEAT.md facoltativo. La radice minuscola memory.md è solo input di riparazione legacy; openclaw doctor --fix può unirlo in MEMORY.md quando entrambi i file esistono.
• Directory di stato (~/.openclaw): configurazione, stato di canali/provider, profili di autenticazione, sessioni, log e Skills condivise (~/.openclaw/skills).

Il workspace predefinito è ~/.openclaw/workspace, configurabile tramite:

{  agents: { defaults: { workspace: "~/.openclaw/workspace" } },}

Se il bot "dimentica" dopo un riavvio, conferma che il Gateway stia usando lo stesso workspace a ogni avvio (e ricorda: la modalità remota usa il workspace dell'host gateway, non quello del tuo laptop locale).

Suggerimento: se vuoi un comportamento o una preferenza durevole, chiedi al bot di scriverlo in AGENTS.md o MEMORY.md invece di fare affidamento sulla cronologia della chat.

Vedi Workspace dell'agente e Memoria.

Metti il tuo workspace dell'agente in un repository git privato e fanne il backup in un luogo privato (per esempio GitHub privato). Questo acquisisce memoria + file AGENTS/SOUL/USER e ti permette di ripristinare in seguito la "mente" dell'assistente.

Non eseguire il commit di nulla sotto ~/.openclaw (credenziali, sessioni, token o payload di segreti cifrati). Se ti serve un ripristino completo, esegui il backup sia del workspace sia della directory di stato separatamente (vedi la domanda sulla migrazione sopra).

Documentazione: Workspace dell'agente.

Vedi la guida dedicata: Disinstallazione.

Sì. Il workspace è la cwd predefinita e l'ancora della memoria, non una sandbox rigida. I percorsi relativi vengono risolti dentro il workspace, ma i percorsi assoluti possono accedere ad altre posizioni dell'host a meno che il sandboxing non sia abilitato. Se ti serve isolamento, usa agents.defaults.sandbox o impostazioni sandbox per agente. Se vuoi che un repository sia la directory di lavoro predefinita, punta il workspace di quell'agente alla radice del repository. Il repository OpenClaw è solo codice sorgente; mantieni il workspace separato a meno che tu non voglia intenzionalmente che l'agente lavori al suo interno.

Esempio (repository come cwd predefinita):

{  agents: {    defaults: {      workspace: "~/Projects/my-repo",    },  },}

Lo stato delle sessioni è di proprietà dell'host gateway. Se sei in modalità remota, l'archivio delle sessioni che ti interessa è sulla macchina remota, non sul tuo laptop locale. Vedi Gestione delle sessioni.

OpenClaw legge una configurazione JSON5 facoltativa da $OPENCLAW_CONFIG_PATH (predefinito: ~/.openclaw/openclaw.json):

$OPENCLAW_CONFIG_PATH

Se il file manca, usa impostazioni predefinite ragionevolmente sicure (incluso un workspace predefinito di ~/.openclaw/workspace).

I bind non-loopback richiedono un percorso di autenticazione gateway valido. In pratica significa:

• autenticazione con segreto condiviso: token o password
• gateway.auth.mode: "trusted-proxy" dietro un reverse proxy identity-aware configurato correttamente

{  gateway: {    bind: "lan",    auth: {      mode: "token",      token: "replace-me",    },  },}

Note:

• gateway.remote.token / .password non abilitano da soli l'autenticazione del gateway locale.
• I percorsi di chiamata locali possono usare gateway.remote.* come fallback solo quando gateway.auth.* non è impostato.
• Per l'autenticazione con password, imposta invece gateway.auth.mode: "password" più gateway.auth.password (o OPENCLAW_GATEWAY_PASSWORD).
• Se gateway.auth.token / gateway.auth.password è configurato esplicitamente tramite SecretRef e non risolto, la risoluzione fallisce in modo chiuso (nessun mascheramento tramite fallback remoto).
• Le configurazioni Control UI con segreto condiviso si autenticano tramite connect.params.auth.token o connect.params.auth.password (archiviati nelle impostazioni dell'app/UI). Le modalità con identità, come Tailscale Serve o trusted-proxy, usano invece gli header della richiesta. Evita di inserire segreti condivisi negli URL.
• Con gateway.auth.mode: "trusted-proxy", i reverse proxy loopback sullo stesso host richiedono gateway.auth.trustedProxy.allowLoopback = true esplicito e una voce loopback in gateway.trustedProxies.

OpenClaw applica l'autenticazione gateway per impostazione predefinita, incluso il loopback. Nel percorso predefinito normale questo significa autenticazione tramite token: se non è configurato alcun percorso di autenticazione esplicito, l'avvio del gateway si risolve in modalità token e genera un token valido solo per quel runtime di avvio, quindi i client WS locali devono autenticarsi. Configura esplicitamente gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN o OPENCLAW_GATEWAY_PASSWORD quando i client hanno bisogno di un segreto stabile tra i riavvii. Questo impedisce ad altri processi locali di chiamare il Gateway.

Se preferisci un percorso di autenticazione diverso, puoi scegliere esplicitamente la modalità password (oppure, per reverse proxy identity-aware, trusted-proxy). Se vuoi davvero un loopback aperto, imposta esplicitamente gateway.auth.mode: "none" nella tua configurazione. Doctor può generare un token per te in qualsiasi momento: openclaw doctor --generate-gateway-token.

Il Gateway osserva la configurazione e supporta l'hot-reload:

• gateway.reload.mode: "hybrid" (predefinito): applica a caldo le modifiche sicure, riavvia per quelle critiche
• sono supportati anche hot, restart, off

Imposta cli.banner.taglineMode nella configurazione:

{  cli: {    banner: {      taglineMode: "off", // random | default | off    },  },}

• off: nasconde il testo dello slogan ma mantiene la riga titolo/versione del banner.
• default: usa All your chats, one OpenClaw. ogni volta.
• random: slogan divertenti/stagionali a rotazione (comportamento predefinito).
• Se non vuoi alcun banner, imposta la variabile d'ambiente OPENCLAW_HIDE_BANNER=1.

web_fetch funziona senza una chiave API. web_search dipende dal provider selezionato:

• I provider basati su API come Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity e Tavily richiedono la loro normale configurazione della chiave API.
• Ollama Web Search non richiede chiavi, ma usa il tuo host Ollama configurato e richiede ollama signin.
• DuckDuckGo non richiede chiavi, ma è un'integrazione non ufficiale basata su HTML.
• SearXNG non richiede chiavi/è self-hosted; configura SEARXNG_BASE_URL o plugins.entries.searxng.config.webSearch.baseUrl.

Consigliato: esegui openclaw configure --section web e scegli un provider. Alternative d'ambiente:

• Brave: BRAVE_API_KEY
• Exa: EXA_API_KEY
• Firecrawl: FIRECRAWL_API_KEY
• Gemini: GEMINI_API_KEY
• Grok: XAI_API_KEY
• Kimi: KIMI_API_KEY o MOONSHOT_API_KEY
• MiniMax Search: MINIMAX_CODE_PLAN_KEY, MINIMAX_CODING_API_KEY o MINIMAX_API_KEY
• Perplexity: PERPLEXITY_API_KEY o OPENROUTER_API_KEY
• SearXNG: SEARXNG_BASE_URL
• Tavily: TAVILY_API_KEY

{  plugins: {    entries: {      brave: {        config: {          webSearch: {            apiKey: "BRAVE_API_KEY_HERE",          },        },      },    },    },    tools: {      web: {        search: {          enabled: true,          provider: "brave",          maxResults: 5,        },        fetch: {          enabled: true,          provider: "firecrawl", // optional; omit for auto-detect        },      },    },}

La configurazione della ricerca web specifica del provider ora si trova in plugins.entries.<plugin>.config.webSearch.*. I percorsi provider legacy tools.web.search.* vengono ancora caricati temporaneamente per compatibilità, ma non devono essere usati per nuove configurazioni. La configurazione di fallback del recupero web Firecrawl si trova in plugins.entries.firecrawl.config.webFetch.*.

Note:

• Se usi allowlist, aggiungi web_search/web_fetch/x_search o group:web.
• web_fetch è abilitato per impostazione predefinita (a meno che non sia disabilitato esplicitamente).
• Se tools.web.fetch.provider viene omesso, OpenClaw rileva automaticamente il primo provider di fallback pronto per il recupero dalle credenziali disponibili. Oggi il provider in bundle è Firecrawl.
• I daemon leggono le variabili d'ambiente da ~/.openclaw/.env (o dall'ambiente del servizio).

Documentazione: Strumenti web.

config.apply sostituisce l'intera configurazione. Se invii un oggetto parziale, tutto il resto viene rimosso.

La versione attuale di OpenClaw protegge da molte sovrascritture accidentali:

• Le scritture di configurazione gestite da OpenClaw convalidano l'intera configurazione post-modifica prima di scrivere.
• Le scritture gestite da OpenClaw non valide o distruttive vengono rifiutate e salvate come openclaw.json.rejected.*.
• Se una modifica diretta interrompe l'avvio o il ricaricamento a caldo, il Gateway fallisce in modo chiuso o salta il ricaricamento; non riscrive openclaw.json.
• openclaw doctor --fix gestisce la riparazione e può ripristinare l'ultima configurazione valida nota salvando il file rifiutato come openclaw.json.clobbered.*.

Recupero:

• Controlla openclaw logs --follow per Invalid config at, Config write rejected: o config reload skipped (invalid config).
• Ispeziona il più recente openclaw.json.clobbered.* o openclaw.json.rejected.* accanto alla configurazione attiva.
• Esegui openclaw config validate e openclaw doctor --fix.
• Copia di nuovo solo le chiavi desiderate con openclaw config set o config.patch.
• Se non hai un'ultima configurazione valida nota o un payload rifiutato, ripristina da backup oppure riesegui openclaw doctor e riconfigura canali/modelli.
• Se è successo in modo inatteso, apri una segnalazione di bug e includi l'ultima configurazione nota o eventuali backup.
• Un agente di codifica locale spesso può ricostruire una configurazione funzionante da log o cronologia.

Per evitarlo:

• Usa openclaw config set per piccole modifiche.
• Usa openclaw configure per modifiche interattive.
• Usa prima config.schema.lookup quando non sei sicuro di un percorso esatto o della forma di un campo; restituisce un nodo di schema superficiale più riepiloghi immediati dei figli per l'approfondimento.
• Usa config.patch per modifiche RPC parziali; riserva config.apply solo alla sostituzione completa della configurazione.
• Se stai usando lo strumento solo per owner gateway da un'esecuzione agente, continuerà a rifiutare scritture su tools.exec.ask / tools.exec.security (inclusi gli alias legacy tools.bash.* che vengono normalizzati agli stessi percorsi exec protetti).

Documentazione: Configurazione, Configurare, Risoluzione problemi del Gateway, Doctor.

Il modello comune è un Gateway (ad esempio Raspberry Pi) più nodi e agenti:

• Gateway (centrale): gestisce canali (Signal/WhatsApp), routing e sessioni.
• Nodi (dispositivi): Mac/iOS/Android si connettono come periferiche ed espongono strumenti locali (system.run, canvas, camera).
• Agenti (worker): cervelli/workspace separati per ruoli speciali (ad esempio "Hetzner ops", "Dati personali").
• Sotto-agenti: avviano lavoro in background da un agente principale quando vuoi parallelismo.
• TUI: connettiti al Gateway e cambia agenti/sessioni.

Documentazione: Nodi, Accesso remoto, Routing multi-agente, Sotto-agenti, TUI.

Sì. È un'opzione di configurazione:

{  browser: { headless: true },  agents: {    defaults: {      sandbox: { browser: { headless: true } },    },  },}

Il valore predefinito è false (headful). La modalità headless ha più probabilità di attivare controlli anti-bot su alcuni siti. Consulta Browser.

La modalità headless usa lo stesso motore Chromium e funziona per la maggior parte dell'automazione (moduli, clic, scraping, login). Le differenze principali:

• Nessuna finestra del browser visibile (usa screenshot se ti servono elementi visivi).
• Alcuni siti sono più severi sull'automazione in modalità headless (CAPTCHA, anti-bot). Ad esempio, X/Twitter spesso blocca le sessioni headless.

Imposta browser.executablePath sul binario Brave (o su qualsiasi browser basato su Chromium) e riavvia il Gateway. Consulta gli esempi completi di configurazione in Browser.

I messaggi Telegram vengono gestiti dal gateway. Il gateway esegue l'agente e solo allora chiama i nodi tramite il Gateway WebSocket quando serve uno strumento di nodo:

Telegram → Gateway → Agente → node.* → Nodo → Gateway → Telegram

I nodi non vedono il traffico provider in ingresso; ricevono solo chiamate RPC di nodo.

Risposta breve: abbina il tuo computer come nodo. Il Gateway viene eseguito altrove, ma può chiamare gli strumenti node.* (schermo, fotocamera, sistema) sulla tua macchina locale tramite il Gateway WebSocket.

Configurazione tipica:

1. Esegui il Gateway sull'host sempre attivo (VPS/server domestico).

2. Metti l'host del Gateway e il tuo computer nella stessa tailnet.

3. Assicurati che il Gateway WS sia raggiungibile (bind tailnet o tunnel SSH).

4. Apri l'app macOS localmente e connettiti in modalità Remoto tramite SSH (o tailnet diretta) in modo che possa registrarsi come nodo.

5. Approva il nodo sul Gateway:

   openclaw devices listopenclaw devices approve <requestId>

Non è richiesto alcun bridge TCP separato; i nodi si connettono tramite il Gateway WebSocket.

Promemoria di sicurezza: abbinare un nodo macOS consente system.run su quella macchina. Abbina solo dispositivi di cui ti fidi e consulta Sicurezza.

Documentazione: Nodi, Protocollo Gateway, modalità remota macOS, Sicurezza.

Controlla le basi:

• Gateway in esecuzione: openclaw gateway status
• Stato del Gateway: openclaw status
• Stato dei canali: openclaw channels status

Poi verifica autenticazione e routing:

• Se usi Tailscale Serve, assicurati che gateway.auth.allowTailscale sia impostato correttamente.
• Se ti connetti tramite tunnel SSH, conferma che il tunnel locale sia attivo e punti alla porta corretta.
• Conferma che le tue allowlist (DM o gruppo) includano il tuo account.

Documentazione: Tailscale, Accesso remoto, Canali.

Sì. Non esiste un bridge "bot-to-bot" integrato, ma puoi collegarle in alcuni modi affidabili:

Il più semplice: usa un normale canale di chat a cui entrambi i bot possono accedere (Telegram/Slack/WhatsApp). Fai inviare un messaggio dal Bot A al Bot B, poi lascia che il Bot B risponda come al solito.

Bridge CLI (generico): esegui uno script che chiama l'altro Gateway con openclaw agent --message ... --deliver, indirizzandolo a una chat in cui l'altro bot è in ascolto. Se un bot è su un VPS remoto, punta la tua CLI a quel Gateway remoto tramite SSH/Tailscale (vedi Accesso remoto).

Schema di esempio (eseguito da una macchina che può raggiungere il Gateway di destinazione):

openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to <chat-id>

Suggerimento: aggiungi una protezione in modo che i due bot non entrino in un ciclo infinito (solo menzione, allowlist di canale o una regola "non rispondere ai messaggi dei bot").

Documentazione: Accesso remoto, CLI agente, Invio agente.

No. Un Gateway può ospitare più agenti, ciascuno con il proprio workspace, valori predefiniti di modello e routing. Questa è la configurazione normale ed è molto più economica e semplice che eseguire un VPS per agente.

Usa VPS separati solo quando ti serve isolamento forte (confini di sicurezza) o configurazioni molto diverse che non vuoi condividere. Altrimenti, mantieni un solo Gateway e usa più agenti o sotto-agenti.

Sì - i nodi sono il modo di prima classe per raggiungere il tuo laptop da un Gateway remoto e sbloccano più del semplice accesso shell. Il Gateway funziona su macOS/Linux (Windows tramite WSL2) ed è leggero (un piccolo VPS o un dispositivo di classe Raspberry Pi va bene; 4 GB di RAM sono più che sufficienti), quindi una configurazione comune è un host sempre attivo più il tuo laptop come nodo.

• Nessun SSH in ingresso richiesto. I nodi si connettono in uscita al Gateway WebSocket e usano l'abbinamento dei dispositivi.
• Controlli di esecuzione più sicuri. system.run è vincolato da allowlist/approvazioni del nodo su quel laptop.
• Più strumenti dispositivo. I nodi espongono canvas, camera e screen oltre a system.run.
• Automazione browser locale. Mantieni il Gateway su un VPS, ma esegui Chrome localmente tramite un host nodo sul laptop, oppure collegati al Chrome locale sull'host tramite Chrome MCP.

SSH va bene per accesso shell ad hoc, ma i nodi sono più semplici per flussi di lavoro agente continuativi e automazione dei dispositivi.

Documentazione: Nodi, CLI nodi, Browser.

No. Deve essere in esecuzione solo un gateway per host, a meno che tu non esegua intenzionalmente profili isolati (vedi Gateway multipli). I nodi sono periferiche che si connettono al gateway (nodi iOS/Android, o "modalità nodo" macOS nell'app della barra dei menu). Per host nodo headless e controllo CLI, consulta CLI host nodo.

È necessario un riavvio completo per modifiche a gateway, discovery e alla superficie Plugin ospitata.

Sì.

• config.schema.lookup: ispeziona un sottoalbero di configurazione con il relativo nodo di schema superficiale, il suggerimento UI corrispondente e i riepiloghi immediati dei figli prima di scrivere
• config.get: recupera lo snapshot corrente + hash
• config.patch: aggiornamento parziale sicuro (preferito per la maggior parte delle modifiche RPC); ricarica a caldo quando possibile e riavvia quando necessario
• config.apply: valida + sostituisce l'intera configurazione; ricarica a caldo quando possibile e riavvia quando necessario
• Lo strumento runtime gateway riservato al proprietario continua a rifiutare la riscrittura di tools.exec.ask / tools.exec.security; gli alias legacy tools.bash.* vengono normalizzati negli stessi percorsi exec protetti

{  agents: { defaults: { workspace: "~/.openclaw/workspace" } },  channels: { whatsapp: { allowFrom: ["+15555550123"] } },}

Questo imposta il tuo workspace e limita chi può attivare il bot.

Passaggi minimi:

1. Installa + accedi sulla VPS

   curl -fsSL https://tailscale.com/install.sh | shsudo tailscale up

2. Installa + accedi sul tuo Mac

   • Usa l'app Tailscale e accedi alla stessa tailnet.

3. Abilita MagicDNS (consigliato)

   • Nella console di amministrazione Tailscale, abilita MagicDNS così la VPS ha un nome stabile.

4. Usa il nome host della tailnet

   • SSH: ssh user@your-vps.tailnet-xxxx.ts.net
   • Gateway WS: ws://your-vps.tailnet-xxxx.ts.net:18789

Se vuoi la UI di controllo senza SSH, usa Tailscale Serve sulla VPS:

openclaw gateway --tailscale serve

Questo mantiene il Gateway associato a loopback ed espone HTTPS tramite Tailscale. Vedi Tailscale.

Serve espone la UI di controllo Gateway + WS. I Node si collegano tramite lo stesso endpoint Gateway WS.

Configurazione consigliata:

1. Assicurati che VPS + Mac siano sulla stessa tailnet.

2. Usa l'app macOS in modalità remota (la destinazione SSH può essere il nome host della tailnet). L'app creerà un tunnel per la porta del Gateway e si collegherà come Node.

3. Approva il Node sul Gateway:

   openclaw devices listopenclaw devices approve <requestId>

Documentazione: Protocollo Gateway, Discovery, modalità remota macOS.

Se ti servono solo strumenti locali (schermo/fotocamera/exec) sul secondo laptop, aggiungilo come Node. Questo mantiene un solo Gateway ed evita configurazioni duplicate. Gli strumenti dei Node locali sono attualmente disponibili solo su macOS, ma prevediamo di estenderli ad altri sistemi operativi.

Installa un secondo Gateway solo quando ti serve isolamento rigido o due bot completamente separati.

Documentazione: Node, CLI Node, Gateway multipli.

OpenClaw legge le variabili d'ambiente dal processo padre (shell, launchd/systemd, CI, ecc.) e carica inoltre:

• .env dalla directory di lavoro corrente
• un fallback globale .env da ~/.openclaw/.env (alias $OPENCLAW_STATE_DIR/.env)

Nessuno dei file .env sovrascrive variabili d'ambiente esistenti.

Puoi anche definire variabili d'ambiente inline nella configurazione (applicate solo se mancanti dall'ambiente del processo):

{  env: {    OPENROUTER_API_KEY: "sk-or-...",    vars: { GROQ_API_KEY: "gsk-..." },  },}

Vedi /environment per precedenza e fonti complete.

Due correzioni comuni:

1. Inserisci le chiavi mancanti in ~/.openclaw/.env così vengono rilevate anche quando il servizio non eredita l'ambiente della tua shell.
2. Abilita l'importazione dalla shell (comodità opzionale):

{  env: {    shellEnv: {      enabled: true,      timeoutMs: 15000,    },  },}

Questo esegue la tua shell di login e importa solo le chiavi attese mancanti (senza mai sovrascrivere). Variabili d'ambiente equivalenti: OPENCLAW_LOAD_SHELL_ENV=1, OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000.

openclaw models status segnala se l'importazione dell'ambiente shell è abilitata. "Shell env: off" non significa che le tue variabili d'ambiente manchino: significa solo che OpenClaw non caricherà automaticamente la tua shell di login.

Se il Gateway viene eseguito come servizio (launchd/systemd), non erediterà l'ambiente della tua shell. Risolvi in uno di questi modi:

1. Inserisci il token in ~/.openclaw/.env:

   COPILOT_GITHUB_TOKEN=...

2. Oppure abilita l'importazione dalla shell (env.shellEnv.enabled: true).

3. Oppure aggiungilo al blocco env della configurazione (si applica solo se manca).

Poi riavvia il Gateway e ricontrolla:

openclaw models status

I token Copilot vengono letti da COPILOT_GITHUB_TOKEN (anche GH_TOKEN / GITHUB_TOKEN). Vedi /concepts/model-providers e /environment.

Invia /new o /reset come messaggio autonomo. Vedi Gestione delle sessioni.

Le sessioni possono scadere dopo session.idleMinutes, ma questo è disabilitato per impostazione predefinita (predefinito 0). Impostalo su un valore positivo per abilitare la scadenza per inattività. Quando è abilitata, il messaggio successivo dopo il periodo di inattività avvia un nuovo ID sessione per quella chiave di chat. Questo non elimina le trascrizioni: avvia solo una nuova sessione.

{  session: {    idleMinutes: 240,  },}

Sì, tramite routing multi-agente e sotto-agenti. Puoi creare un agente coordinatore e diversi agenti worker con workspace e modelli propri.

Detto questo, è meglio considerarlo un esperimento divertente. Consuma molti token ed è spesso meno efficiente che usare un bot con sessioni separate. Il modello tipico che immaginiamo è un bot con cui parli, con sessioni diverse per lavoro parallelo. Quel bot può anche generare sotto-agenti quando necessario.

Documentazione: Routing multi-agente, Sotto-agenti, CLI agenti.

Il contesto della sessione è limitato dalla finestra del modello. Chat lunghe, output estesi degli strumenti o molti file possono attivare Compaction o troncamento.

Cosa aiuta:

• Chiedi al bot di riassumere lo stato corrente e scriverlo in un file.
• Usa /compact prima di attività lunghe e /new quando cambi argomento.
• Tieni il contesto importante nel workspace e chiedi al bot di rileggerlo.
• Usa sotto-agenti per lavoro lungo o parallelo così la chat principale resta più piccola.
• Scegli un modello con una finestra di contesto più ampia se succede spesso.

Usa il comando di reset:

openclaw reset

Reset completo non interattivo:

openclaw reset --scope full --yes --non-interactive

Poi riesegui la configurazione:

openclaw onboard --install-daemon

Note:

• L'onboarding offre anche Reset se rileva una configurazione esistente. Vedi Onboarding (CLI).
• Se hai usato profili (--profile / OPENCLAW_PROFILE), reimposta ogni directory di stato (i predefiniti sono ~/.openclaw-<profile>).
• Reset dev: openclaw gateway --dev --reset (solo dev; cancella configurazione dev + credenziali + sessioni + workspace).

Usa una di queste opzioni:

• Compatta (mantiene la conversazione ma riassume i turni più vecchi):

  /compact

  oppure /compact <instructions> per guidare il riassunto.

• Reimposta (nuovo ID sessione per la stessa chiave di chat):

  /new/reset

Se continua a succedere:

• Abilita o regola la potatura della sessione (agents.defaults.contextPruning) per ridurre i vecchi output degli strumenti.
• Usa un modello con una finestra di contesto più ampia.

Documentazione: Compaction, Potatura della sessione, Gestione delle sessioni.

Questo è un errore di validazione del provider: il modello ha emesso un blocco tool_use senza l'input richiesto. Di solito significa che la cronologia della sessione è obsoleta o corrotta (spesso dopo thread lunghi o una modifica di strumento/schema).

Correzione: avvia una nuova sessione con /new (messaggio autonomo).

Gli Heartbeat vengono eseguiti ogni 30m per impostazione predefinita (1h quando si usa l'autenticazione OAuth). Regolali o disabilitali:

{  agents: {    defaults: {      heartbeat: {        every: "2h", // or "0m" to disable      },    },  },}

Se HEARTBEAT.md esiste ma è di fatto vuoto (solo righe vuote e intestazioni markdown come # Heading), OpenClaw salta l'esecuzione dell'Heartbeat per risparmiare chiamate API. Se il file manca, l'Heartbeat viene comunque eseguito e il modello decide cosa fare.

Le sovrascritture per agente usano agents.list[].heartbeat. Documentazione: Heartbeat.

No. OpenClaw viene eseguito sul tuo account, quindi se sei nel gruppo OpenClaw può vederlo. Per impostazione predefinita, le risposte nei gruppi sono bloccate finché non autorizzi i mittenti (groupPolicy: "allowlist").

Se vuoi che solo tu possa attivare risposte nel gruppo:

{  channels: {    whatsapp: {      groupPolicy: "allowlist",      groupAllowFrom: ["+15551234567"],    },  },}

Opzione 1 (la più veloce): segui i log e invia un messaggio di test nel gruppo:

openclaw logs --follow --json

Cerca chatId (o from) che termina con @g.us, come: 1234567890-1234567890@g.us.

Opzione 2 (se già configurato/in allowlist): elenca i gruppi dalla configurazione:

openclaw directory groups list --channel whatsapp

Documentazione: WhatsApp, Directory, Log.

Due cause comuni:

• Il gating delle menzioni è attivo (predefinito). Devi @menzionare il bot (o corrispondere a mentionPatterns).
• Hai configurato channels.whatsapp.groups senza "*" e il gruppo non è in allowlist.

Vedi Gruppi e Messaggi di gruppo.

Le chat dirette vengono accorpate alla sessione principale per impostazione predefinita. Gruppi/canali hanno le proprie chiavi di sessione, e gli argomenti Telegram / i thread Discord sono sessioni separate. Vedi Gruppi e Messaggi di gruppo.

Nessun limite rigido. Decine (anche centinaia) vanno bene, ma tieni d'occhio:

• Crescita del disco: sessioni + trascrizioni si trovano in ~/.openclaw/agents/<agentId>/sessions/.
• Costo in token: più agenti significa più utilizzo concorrente del modello.
• Overhead operativo: profili di autenticazione, workspace e instradamento dei canali per ogni agente.

Suggerimenti:

• Mantieni un workspace attivo per agente (agents.defaults.workspace).
• Elimina le vecchie sessioni (cancella JSONL o voci archiviate) se il disco cresce.
• Usa openclaw doctor per individuare workspace residui e profili non corrispondenti.

Sì. Usa Instradamento Multi-Agent per eseguire più agenti isolati e instradare i messaggi in ingresso per canale/account/peer. Slack è supportato come canale e può essere associato ad agenti specifici.

L'accesso al browser è potente ma non permette di "fare qualunque cosa possa fare un umano": anti-bot, CAPTCHA e MFA possono comunque bloccare l'automazione. Per il controllo del browser più affidabile, usa Chrome MCP locale sull'host, oppure usa CDP sulla macchina che esegue effettivamente il browser.

Configurazione consigliata:

• Host Gateway sempre attivo (VPS/Mac mini).
• Un agente per ruolo (associazioni).
• Canali Slack associati a quegli agenti.
• Browser locale tramite Chrome MCP o un nodo quando necessario.

Documentazione: Instradamento Multi-Agent, Slack, Browser, Nodi.

gateway.port controlla la singola porta multiplexata per WebSocket + HTTP (Control UI, hook, ecc.).

Precedenza:

--port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789

Perché "running" è la vista del supervisor (launchd/systemd/schtasks). Il probe di connettività è la CLI che si connette effettivamente al WebSocket del gateway.

Usa openclaw gateway status e considera affidabili queste righe:

• Probe target: (l'URL effettivamente usato dal probe)
• Listening: (ciò che è effettivamente associato alla porta)
• Last gateway error: (causa radice comune quando il processo è attivo ma la porta non è in ascolto)

Stai modificando un file di configurazione mentre il servizio ne sta usando un altro (spesso una mancata corrispondenza --profile / OPENCLAW_STATE_DIR).

Correzione:

openclaw gateway install --force

Eseguilo dallo stesso --profile / ambiente che vuoi far usare al servizio.

OpenClaw applica un blocco di runtime associando immediatamente il listener WebSocket all'avvio (predefinito ws://127.0.0.1:18789). Se l'associazione fallisce con EADDRINUSE, genera GatewayLockError indicando che un'altra istanza è già in ascolto.

Correzione: arresta l'altra istanza, libera la porta oppure esegui con openclaw gateway --port <port>.

Imposta gateway.mode: "remote" e punta a un URL WebSocket remoto, facoltativamente con credenziali remote basate su segreto condiviso:

{  gateway: {    mode: "remote",    remote: {      url: "ws://gateway.tailnet:18789",      token: "your-token",      password: "your-password",    },  },}

Note:

• openclaw gateway si avvia solo quando gateway.mode è local (o se passi il flag di override).
• L'app macOS osserva il file di configurazione e cambia modalità live quando questi valori cambiano.
• gateway.remote.token / .password sono solo credenziali remote lato client; da sole non abilitano l'autenticazione del gateway locale.

Il percorso di autenticazione del gateway e il metodo di autenticazione della UI non corrispondono.

Fatti (dal codice):

• La Control UI mantiene il token in sessionStorage per la sessione della scheda corrente del browser e l'URL del gateway selezionato, quindi i refresh nella stessa scheda continuano a funzionare senza ripristinare la persistenza del token in localStorage a lungo termine.
• Su AUTH_TOKEN_MISMATCH, i client attendibili possono tentare un solo retry limitato con un token dispositivo memorizzato nella cache quando il gateway restituisce suggerimenti di retry (canRetryWithDeviceToken=true, recommendedNextStep=retry_with_device_token).
• Quel retry con token memorizzato nella cache ora riutilizza gli scope approvati in cache archiviati con il token dispositivo. I chiamanti con deviceToken esplicito / scopes espliciti mantengono comunque l'insieme di scope richiesto invece di ereditare gli scope in cache.
• Al di fuori di quel percorso di retry, la precedenza dell'autenticazione di connessione è prima token/password condivisi espliciti, poi deviceToken esplicito, poi token dispositivo archiviato, poi token bootstrap.
• I controlli degli scope del token bootstrap usano prefissi di ruolo. L'allowlist operatore bootstrap integrata soddisfa solo le richieste operatore; i nodi o altri ruoli non operatore hanno comunque bisogno di scope sotto il proprio prefisso di ruolo.

Correzione:

• Più rapido: openclaw dashboard (stampa + copia l'URL della dashboard, prova ad aprirlo; mostra un suggerimento SSH se headless).
• Se non hai ancora un token: openclaw doctor --generate-gateway-token.
• Se remoto, crea prima un tunnel: ssh -N -L 18789:127.0.0.1:18789 user@host poi apri http://127.0.0.1:18789/.
• Modalità segreto condiviso: imposta gateway.auth.token / OPENCLAW_GATEWAY_TOKEN oppure gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD, poi incolla il segreto corrispondente nelle impostazioni della Control UI.
• Modalità Tailscale Serve: assicurati che gateway.auth.allowTailscale sia abilitato e di aprire l'URL Serve, non un URL loopback/tailnet grezzo che aggira gli header di identità Tailscale.
• Modalità proxy attendibile: assicurati di passare attraverso il proxy identity-aware configurato, non un URL gateway grezzo. Anche i proxy loopback sullo stesso host richiedono gateway.auth.trustedProxy.allowLoopback = true.
• Se la mancata corrispondenza persiste dopo l'unico retry, ruota/riapprova il token dispositivo associato:
  • openclaw devices list
  • openclaw devices rotate --device <id> --role operator
• Se quella chiamata di rotazione dice che è stata negata, controlla due cose:
  • le sessioni dei dispositivi associati possono ruotare solo il proprio dispositivo, a meno che non abbiano anche operator.admin
  • i valori --scope espliciti non possono superare gli scope operatore correnti del chiamante
• Ancora bloccato? Esegui openclaw status --all e segui Risoluzione dei problemi. Vedi Dashboard per i dettagli sull'autenticazione.

L'associazione tailnet sceglie un IP Tailscale dalle interfacce di rete (100.64.0.0/10). Se la macchina non è su Tailscale (o l'interfaccia è inattiva), non c'è nulla a cui associarsi.

Correzione:

• Avvia Tailscale su quell'host (così avrà un indirizzo 100.x), oppure
• Passa a gateway.bind: "loopback" / "lan".

Nota: tailnet è esplicito. auto preferisce loopback; usa gateway.bind: "tailnet" quando vuoi un'associazione solo tailnet.

Di solito no: un Gateway può eseguire più canali di messaggistica e agenti. Usa più Gateway solo quando ti serve ridondanza (es.: bot di emergenza) o isolamento rigido.

Sì, ma devi isolare:

• OPENCLAW_CONFIG_PATH (configurazione per istanza)
• OPENCLAW_STATE_DIR (stato per istanza)
• agents.defaults.workspace (isolamento del workspace)
• gateway.port (porte univoche)

Configurazione rapida (consigliata):

• Usa openclaw --profile <name> ... per ogni istanza (crea automaticamente ~/.openclaw-<name>).
• Imposta un gateway.port univoco nella configurazione di ogni profilo (oppure passa --port per le esecuzioni manuali).
• Installa un servizio per profilo: openclaw --profile <name> gateway install.

I profili aggiungono anche un suffisso ai nomi dei servizi (ai.openclaw.<profile>; legacy com.openclaw.*, openclaw-gateway-<profile>.service, OpenClaw Gateway (<profile>)). Guida completa: Gateway multipli.

Il Gateway è un server WebSocket e si aspetta che il primissimo messaggio sia un frame connect. Se riceve qualunque altra cosa, chiude la connessione con codice 1008 (violazione della policy).

Cause comuni:

• Hai aperto l'URL HTTP in un browser (http://...) invece di un client WS.
• Hai usato la porta o il percorso sbagliato.
• Un proxy o tunnel ha rimosso gli header di autenticazione o inviato una richiesta non Gateway.

Correzioni rapide:

1. Usa l'URL WS: ws://<host>:18789 (o wss://... se HTTPS).
2. Non aprire la porta WS in una normale scheda del browser.
3. Se l'autenticazione è attiva, includi token/password nel frame connect.

Se usi la CLI o la TUI, l'URL dovrebbe apparire così:

openclaw tui --url ws://<host>:18789 --token <token>

Dettagli del protocollo: Protocollo Gateway.

Log su file (strutturati):

/tmp/openclaw/openclaw-YYYY-MM-DD.log

Puoi impostare un percorso stabile tramite logging.file. Il livello di log su file è controllato da logging.level. La verbosità della console è controllata da --verbose e logging.consoleLevel.

Tail dei log più rapido:

openclaw logs --follow

Log di servizio/supervisor (quando il gateway viene eseguito tramite launchd/systemd):

• macOS: $OPENCLAW_STATE_DIR/logs/gateway.log e gateway.err.log (predefinito: ~/.openclaw/logs/...; i profili usano ~/.openclaw-<profile>/logs/...)
• Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
• Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST

Vedi Risoluzione dei problemi per altro.

Usa gli helper del gateway:

openclaw gateway statusopenclaw gateway restart

Se esegui il gateway manualmente, openclaw gateway --force può recuperare la porta. Vedi Gateway.

Esistono due modalità di installazione Windows:

1) WSL2 (consigliata): il Gateway viene eseguito dentro Linux.

Apri PowerShell, entra in WSL, poi riavvia:

wslopenclaw gateway statusopenclaw gateway restart

Se non hai mai installato il servizio, avvialo in foreground:

openclaw gateway run

2) Windows nativo (non consigliato): il Gateway viene eseguito direttamente in Windows.

Apri PowerShell ed esegui:

openclaw gateway statusopenclaw gateway restart

Se lo esegui manualmente (senza servizio), usa:

openclaw gateway run

Documentazione: Windows (WSL2), Runbook del servizio Gateway.

Inizia con un rapido controllo dello stato:

openclaw statusopenclaw models statusopenclaw channels statusopenclaw logs --follow

Cause comuni:

• Autenticazione del modello non caricata sull'host del Gateway (controlla models status).
• Pairing del canale/lista consentiti che blocca le risposte (controlla configurazione del canale + log).
• WebChat/Dashboard è aperto senza il token corretto.

Se sei in remoto, conferma che la connessione tunnel/Tailscale sia attiva e che il WebSocket del Gateway sia raggiungibile.

Documentazione: Canali, Risoluzione dei problemi, Accesso remoto.

Di solito significa che la UI ha perso la connessione WebSocket. Controlla:

1. Il Gateway è in esecuzione? openclaw gateway status
2. Il Gateway è integro? openclaw status
3. La UI ha il token corretto? openclaw dashboard
4. Se sei in remoto, il collegamento tunnel/Tailscale è attivo?

Poi segui i log:

openclaw logs --follow

Documentazione: Dashboard, Accesso remoto, Risoluzione dei problemi.

Inizia con i log e lo stato del canale:

openclaw channels statusopenclaw channels logs --channel telegram

Poi confronta l'errore:

• BOT_COMMANDS_TOO_MUCH: il menu Telegram ha troppe voci. OpenClaw riduce già i comandi al limite di Telegram e riprova con meno comandi, ma alcune voci del menu devono comunque essere rimosse. Riduci i comandi di plugin/skill/personalizzati, oppure disabilita channels.telegram.commands.native se non ti serve il menu.
• TypeError: fetch failed, Network request for 'setMyCommands' failed! o errori di rete simili: se sei su un VPS o dietro un proxy, conferma che l'HTTPS in uscita sia consentito e che il DNS funzioni per api.telegram.org.

Se il Gateway è remoto, assicurati di guardare i log sull'host del Gateway.

Documentazione: Telegram, Risoluzione dei problemi dei canali.

Prima conferma che il Gateway sia raggiungibile e che l'agente possa essere eseguito:

openclaw statusopenclaw models statusopenclaw logs --follow

Nella TUI, usa /status per vedere lo stato attuale. Se ti aspetti risposte in un canale chat, assicurati che la consegna sia abilitata (/deliver on).

Documentazione: TUI, Comandi slash.

Se hai installato il servizio:

openclaw gateway stopopenclaw gateway start

Questo arresta/avvia il servizio supervisionato (launchd su macOS, systemd su Linux). Usalo quando il Gateway viene eseguito in background come daemon.

Se lo stai eseguendo in foreground, arrestalo con Ctrl-C, poi:

openclaw gateway run

Documentazione: Runbook del servizio Gateway.

• openclaw gateway restart: riavvia il servizio in background (launchd/systemd).
• openclaw gateway: esegue il gateway in foreground per questa sessione del terminale.

Se hai installato il servizio, usa i comandi gateway. Usa openclaw gateway quando vuoi un'esecuzione una tantum in foreground.

Avvia il Gateway con --verbose per ottenere più dettagli nella console. Poi ispeziona il file di log per autenticazione del canale, instradamento del modello ed errori RPC.

Gli allegati in uscita dall'agente devono includere una riga MEDIA:<path-or-url> (su una riga autonoma). Vedi Configurazione dell'assistente OpenClaw e Invio agente.

Invio da CLI:

openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png

Controlla anche:

• Il canale di destinazione supporta i media in uscita e non è bloccato da liste consentiti.
• Il file rientra nei limiti di dimensione del provider (le immagini vengono ridimensionate a un massimo di 2048 px).
• tools.fs.workspaceOnly=true limita gli invii da percorso locale a workspace, temp/media-store e file convalidati dalla sandbox.
• tools.fs.workspaceOnly=false consente a MEDIA: di inviare file locali dell'host che l'agente può già leggere, ma solo per media e tipi di documento sicuri (immagini, audio, video, PDF e documenti Office). I file di testo semplice e quelli simili a segreti restano bloccati.

Vedi Immagini.

Tratta i DM in ingresso come input non attendibile. I valori predefiniti sono progettati per ridurre il rischio:

• Il comportamento predefinito sui canali con DM è il pairing:
  • I mittenti sconosciuti ricevono un codice di pairing; il bot non elabora il loro messaggio.
  • Approva con: openclaw pairing approve --channel <channel> [--account <id>] <code>
  • Le richieste in sospeso sono limitate a 3 per canale; controlla openclaw pairing list --channel <channel> [--account <id>] se un codice non è arrivato.
• L'apertura pubblica dei DM richiede un opt-in esplicito (dmPolicy: "open" e lista consentiti "*").

Esegui openclaw doctor per evidenziare policy DM rischiose.

No. La prompt injection riguarda contenuti non attendibili, non solo chi può inviare DM al bot. Se il tuo assistente legge contenuti esterni (ricerca/fetch web, pagine del browser, email, documenti, allegati, log incollati), quei contenuti possono includere istruzioni che tentano di dirottare il modello. Questo può accadere anche se sei l'unico mittente.

Il rischio maggiore è quando gli strumenti sono abilitati: il modello può essere ingannato e indotto a esfiltrare contesto o a chiamare strumenti per tuo conto. Riduci il raggio d'impatto:

• usando un agente "reader" in sola lettura o senza strumenti per riassumere contenuti non attendibili
• mantenendo web_search / web_fetch / browser disattivati per agenti con strumenti abilitati
• trattando anche il testo decodificato da file/documenti come non attendibile: OpenResponses input_file e l'estrazione da allegati multimediali racchiudono entrambi il testo estratto in marcatori espliciti di confine per contenuti esterni invece di passare testo grezzo del file
• sandboxing e liste consentiti rigorose per gli strumenti

Dettagli: Sicurezza.

Sì, per la maggior parte delle configurazioni. Isolare il bot con account e numeri di telefono separati riduce il raggio d'impatto se qualcosa va storto. Questo rende anche più facile ruotare le credenziali o revocare l'accesso senza impattare i tuoi account personali.

Inizia in piccolo. Concedi accesso solo agli strumenti e agli account di cui hai davvero bisogno, ed espandi in seguito se necessario.

Documentazione: Sicurezza, Pairing.

Non consigliamo la piena autonomia sui tuoi messaggi personali. Il pattern più sicuro è:

• Mantieni i DM in modalità pairing o con una lista consentiti stretta.
• Usa un numero o account separato se vuoi che invii messaggi per tuo conto.
• Lascia che prepari una bozza, poi approva prima dell'invio.

Se vuoi sperimentare, fallo su un account dedicato e tienilo isolato. Vedi Sicurezza.

Sì, se l'agente è solo chat e l'input è attendibile. I livelli più piccoli sono più suscettibili al dirottamento delle istruzioni, quindi evitali per agenti con strumenti abilitati o quando leggono contenuti non attendibili. Se devi usare un modello più piccolo, blocca gli strumenti ed esegui all'interno di una sandbox. Vedi Sicurezza.

I codici di pairing vengono inviati solo quando un mittente sconosciuto invia un messaggio al bot e dmPolicy: "pairing" è abilitato. /start da solo non genera un codice.

Controlla le richieste in sospeso:

openclaw pairing list telegram

Se vuoi accesso immediato, aggiungi il tuo id mittente alla lista consentiti o imposta dmPolicy: "open" per quell'account.

No. La policy DM predefinita di WhatsApp è pairing. I mittenti sconosciuti ricevono solo un codice di pairing e il loro messaggio non viene elaborato. OpenClaw risponde solo alle chat che riceve o agli invii espliciti che attivi.

Approva il pairing con:

openclaw pairing approve whatsapp <code>

Elenca le richieste in sospeso:

openclaw pairing list whatsapp

Prompt del numero di telefono del wizard: viene usato per impostare la tua lista consentiti/proprietario in modo che i tuoi DM siano consentiti. Non viene usato per invii automatici. Se lo esegui sul tuo numero WhatsApp personale, usa quel numero e abilita channels.whatsapp.selfChatMode.

La maggior parte dei messaggi interni o degli strumenti appare solo quando verbose, trace o reasoning sono abilitati per quella sessione.

Correggi nella chat in cui lo vedi:

/verbose off/trace off/reasoning off

Se è ancora rumoroso, controlla le impostazioni della sessione nella UI di controllo e imposta verbose su inherit. Conferma anche di non usare un profilo bot con verboseDefault impostato su on nella configurazione.

Documentazione: Pensiero e verbose, Sicurezza.

Invia una di queste opzioni come messaggio autonomo (senza slash):

stopstop actionstop current actionstop runstop current runstop agentstop the agentstop openclawopenclaw stopstop don't do anythingstop do not do anythingstop doing anythingplease stopstop pleaseabortescwaitexitinterrupt

Questi sono trigger di interruzione (non comandi slash).

Per i processi in background (dallo strumento exec), puoi chiedere all'agente di eseguire:

process action:kill sessionId:XXX

Panoramica dei comandi slash: vedi Comandi slash.

La maggior parte dei comandi deve essere inviata come messaggio autonomo che inizia con /, ma alcune scorciatoie (come /status) funzionano anche inline per i mittenti nella lista consentiti.

OpenClaw blocca per impostazione predefinita la messaggistica cross-provider. Se una chiamata strumento è associata a Telegram, non invierà a Discord a meno che tu non lo consenta esplicitamente.

Abilita la messaggistica cross-provider per l'agente:

{  tools: {    message: {      crossContext: {        allowAcrossProviders: true,        marker: { enabled: true, prefix: "[from {channel}] " },      },    },  },}

Riavvia il gateway dopo aver modificato la configurazione.

La modalità coda controlla come i nuovi messaggi interagiscono con un'esecuzione in corso. Usa /queue per cambiare modalità:

• steer - accoda tutto lo steering in sospeso per il prossimo boundary del modello nell'esecuzione corrente
• queue - steering legacy uno alla volta
• followup - esegui i messaggi uno alla volta
• collect - raggruppa i messaggi e rispondi una volta
• steer-backlog - fai steering ora, poi elabora il backlog
• interrupt - interrompi l'esecuzione corrente e riparti da zero

La modalità predefinita è steer. Puoi aggiungere opzioni come debounce:0.5s cap:25 drop:summarize per le modalità di follow-up. Vedi Coda dei comandi e Coda di Steering.

In OpenClaw, credenziali e selezione del modello sono separate. Impostare ANTHROPIC_API_KEY (o archiviare una chiave API Anthropic nei profili di autenticazione) abilita l'autenticazione, ma il modello predefinito effettivo è quello che configuri in agents.defaults.model.primary (ad esempio, anthropic/claude-sonnet-4-6 o anthropic/claude-opus-4-6). Se vedi No credentials found for profile "anthropic:default", significa che il Gateway non è riuscito a trovare le credenziali Anthropic nel file auth-profiles.json previsto per l'agente in esecuzione.