Configurazione dell'assistente personale

OpenClaw è un Gateway self-hosted che collega Discord, Google Chat, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo e altro agli agenti AI. Questa guida copre la configurazione da "assistente personale": un numero WhatsApp dedicato che si comporta come il tuo assistente AI sempre attivo.

⚠️ Prima la sicurezza

Stai mettendo un agente nella posizione di:

• eseguire comandi sulla tua macchina (a seconda della tua policy sugli strumenti)
• leggere/scrivere file nel tuo workspace
• inviare messaggi in uscita tramite WhatsApp/Telegram/Discord/Mattermost e altri canali inclusi

Inizia in modo prudente:

• Imposta sempre channels.whatsapp.allowFrom (non eseguire mai una configurazione aperta a tutti sul tuo Mac personale).
• Usa un numero WhatsApp dedicato per l'assistente.
• Gli Heartbeat ora hanno come impostazione predefinita ogni 30 minuti. Disattivali finché non ti fidi della configurazione impostando agents.defaults.heartbeat.every: "0m".

Prerequisiti

• OpenClaw installato e configurato tramite onboarding - vedi Primi passi se non l'hai ancora fatto
• Un secondo numero di telefono (SIM/eSIM/prepagato) per l'assistente

La configurazione con due telefoni (consigliata)

Vuoi questo:

flowchart TB
    A["<b>Your Phone (personal)<br></b><br>Your WhatsApp<br>+1-555-YOU"] -- message --> B["<b>Second Phone (assistant)<br></b><br>Assistant WA<br>+1-555-ASSIST"]
    B -- linked via QR --> C["<b>Your Mac (openclaw)<br></b><br>AI agent"]

Se colleghi il tuo WhatsApp personale a OpenClaw, ogni messaggio indirizzato a te diventa "input dell'agente". Raramente è ciò che vuoi.

Avvio rapido in 5 minuti

1. Associa WhatsApp Web (mostra il QR; scansionalo con il telefono dell'assistente):

openclaw channels login

2. Avvia il Gateway (lascialo in esecuzione):

openclaw gateway --port 18789

3. Inserisci una configurazione minima in ~/.openclaw/openclaw.json:

{  gateway: { mode: "local" },  channels: { whatsapp: { allowFrom: ["+15555550123"] } },}

Ora invia un messaggio al numero dell'assistente dal telefono nella allowlist.

Quando l'onboarding termina, OpenClaw apre automaticamente la dashboard e stampa un link pulito (senza token). Se la dashboard richiede l'autenticazione, incolla il segreto condiviso configurato nelle impostazioni di Control UI. L'onboarding usa un token per impostazione predefinita (gateway.auth.token), ma l'autenticazione con password funziona anche se hai cambiato gateway.auth.mode in password. Per riaprirla in seguito: openclaw dashboard.

Dai all'agente un workspace (AGENTS)

OpenClaw legge le istruzioni operative e la "memoria" dalla directory del suo workspace.

Per impostazione predefinita, OpenClaw usa ~/.openclaw/workspace come workspace dell'agente e lo creerà (insieme ai file iniziali AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md) automaticamente durante la configurazione o la prima esecuzione dell'agente. BOOTSTRAP.md viene creato solo quando il workspace è completamente nuovo (non dovrebbe ricomparire dopo che lo elimini). MEMORY.md è opzionale (non viene creato automaticamente); quando è presente, viene caricato per le sessioni normali. Le sessioni dei subagenti inseriscono solo AGENTS.md e TOOLS.md.

openclaw setup

Layout completo del workspace + guida al backup: Workspace dell'agente Flusso di lavoro della memoria: Memoria

Opzionale: scegli un workspace diverso con agents.defaults.workspace (supporta ~).

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

Se distribuisci già i tuoi file di workspace da un repository, puoi disabilitare completamente la creazione dei file di bootstrap:

{  agents: {    defaults: {      skipBootstrap: true,    },  },}

La configurazione che lo trasforma in "un assistente"

OpenClaw usa già una buona configurazione predefinita da assistente, ma di solito vorrai regolare:

• persona/istruzioni in SOUL.md
• impostazioni predefinite di ragionamento (se desiderato)
• Heartbeat (quando ti fidi della configurazione)

Esempio:

{  logging: { level: "info" },  agents: {    defaults: {      model: { primary: "anthropic/claude-opus-4-6" },      workspace: "~/.openclaw/workspace",      thinkingDefault: "high",      timeoutSeconds: 1800,      // Start with 0; enable later.      heartbeat: { every: "0m" },    },    list: [      {        id: "main",        default: true,        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      allowFrom: ["+15555550123"],      groups: {        "*": { requireMention: true },      },    },  },  session: {    scope: "per-sender",    resetTriggers: ["/new", "/reset"],    reset: {      mode: "daily",      atHour: 4,      idleMinutes: 10080,    },  },}

Sessioni e memoria

• File di sessione: ~/.openclaw/agents/<agentId>/sessions/{{SessionId}}.jsonl
• Metadati di sessione (uso dei token, ultima route, ecc.): ~/.openclaw/agents/<agentId>/sessions/sessions.json (legacy: ~/.openclaw/sessions/sessions.json)
• /new o /reset avvia una nuova sessione per quella chat (configurabile tramite resetTriggers). Se inviato da solo, OpenClaw conferma il reset senza invocare il modello.
• /compact [instructions] compatta il contesto della sessione e riporta il budget di contesto restante.

Heartbeat (modalità proattiva)

Per impostazione predefinita, OpenClaw esegue un Heartbeat ogni 30 minuti con il prompt: Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK. Imposta agents.defaults.heartbeat.every: "0m" per disabilitarlo.

• Se HEARTBEAT.md esiste ma è di fatto vuoto (solo righe vuote, commenti Markdown/HTML, intestazioni Markdown come # Heading, marcatori di fence o stub di checklist vuoti), 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.
• Se l'agente risponde con HEARTBEAT_OK (facoltativamente con un breve padding; vedi agents.defaults.heartbeat.ackMaxChars), OpenClaw sopprime la consegna in uscita per quell'Heartbeat.
• Per impostazione predefinita, la consegna degli Heartbeat a target in stile DM user:<id> è consentita. Imposta agents.defaults.heartbeat.directPolicy: "block" per sopprimere la consegna a target diretti mantenendo attive le esecuzioni degli Heartbeat.
• Gli Heartbeat eseguono turni completi dell'agente - intervalli più brevi consumano più token.

{  agents: {    defaults: {      heartbeat: { every: "30m" },    },  },}

Media in ingresso e in uscita

Gli allegati in ingresso (immagini/audio/documenti) possono essere esposti al tuo comando tramite template:

• {{MediaPath}} (percorso del file temporaneo locale)
• {{MediaUrl}} (pseudo-URL)
• {{Transcript}} (se la trascrizione audio è abilitata)

Gli allegati in uscita dall'agente usano campi multimediali strutturati nello strumento di messaggistica o nel payload di risposta, come media, mediaUrl, mediaUrls, path o filePath. Esempio di argomenti dello strumento di messaggistica:

{  "message": "Here's the screenshot.",  "mediaUrl": "https://example.com/screenshot.png"}

OpenClaw invia i media strutturati insieme al testo. Le risposte finali legacy dell'assistente possono ancora essere normalizzate per compatibilità, ma l'output degli strumenti, l'output del browser, i blocchi in streaming e le azioni dei messaggi non interpretano il testo come comandi per allegati.

Il comportamento dei percorsi locali segue lo stesso modello di fiducia per la lettura dei file dell'agente:

• Se tools.fs.workspaceOnly è true, i percorsi dei media locali in uscita restano limitati alla root temporanea di OpenClaw, alla cache dei media, ai percorsi del workspace dell'agente e ai file generati dalla sandbox.
• Se tools.fs.workspaceOnly è false, i media locali in uscita possono usare file locali dell'host che l'agente è già autorizzato a leggere.
• I percorsi locali possono essere assoluti, relativi al workspace o relativi alla home con ~/.
• Gli invii locali dell'host consentono comunque solo media e tipi di documenti sicuri (immagini, audio, video, PDF, documenti Office e documenti di testo convalidati come Markdown/MD, TXT, JSON, YAML e YML). Questa è un'estensione del confine di fiducia esistente per la lettura dall'host, non uno scanner di segreti: se l'agente può leggere un file locale dell'host secret.txt o config.json, può allegare quel file quando l'estensione e la validazione del contenuto corrispondono.

Questo significa che immagini/file generati fuori dal workspace possono ora essere inviati quando la tua policy fs consente già quelle letture, mentre estensioni di testo arbitrarie locali dell'host restano bloccate. Tieni i file sensibili fuori dal filesystem leggibile dall'agente, oppure mantieni tools.fs.workspaceOnly=true per invii di percorsi locali più rigorosi.

Checklist operativa

openclaw status          # local status (creds, sessions, queued events)openclaw status --all    # full diagnosis (read-only, pasteable)openclaw status --deep   # asks the gateway for a live health probe with channel probes when supportedopenclaw health --json   # gateway health snapshot (WS; default can return a fresh cached snapshot)

I log si trovano sotto /tmp/openclaw/ (predefinito: openclaw-YYYY-MM-DD.log).

Passaggi successivi

• WebChat: WebChat
• Operazioni Gateway: Runbook Gateway
• Cron + risvegli: Job Cron
• Companion per la barra dei menu macOS: app macOS OpenClaw
• App Node iOS: app iOS
• App Node Android: app Android
• Hub Windows: Windows
• Stato Linux: app Linux
• Sicurezza: Sicurezza

Correlati

• Primi passi
• Configurazione
• Panoramica dei canali