Costruire un assistente personale con OpenClaw

OpenClaw è un gateway WhatsApp + Telegram + Discord + iMessage per agenti Pi. I plugin aggiungono Mattermost. Questa guida riguarda il setup come “assistente personale”: un numero WhatsApp dedicato che si comporta come il tuo agente sempre attivo.

⚠️ Prima la sicurezza

Stai mettendo un agente nella posizione di:

  • eseguire comandi sulla tua macchina (a seconda del tuo setup dei tool Pi)
  • leggere/scrivere file nel tuo workspace
  • inviare messaggi tramite WhatsApp/Telegram/Discord/Mattermost (plugin)

Parti in modo conservativo:

  • Imposta sempre channels.whatsapp.allowFrom (non eseguire mai un’istanza aperta a tutti sul tuo Mac personale).
  • Usa un numero WhatsApp dedicato per l’assistente.
  • Gli heartbeat ora hanno un intervallo predefinito di 30 minuti. Disabilitali finché non ti fidi del setup impostando agents.defaults.heartbeat.every: "0m".

Prerequisiti

  • OpenClaw installato e con onboarding completato — consulta Per iniziare se non l’hai ancora fatto
  • Un secondo numero di telefono (SIM/eSIM/prepagata) per l’assistente

Il setup a due telefoni (consigliato)

Ecco quello che vuoi ottenere:

flowchart TB
    A["<b>Il tuo telefono (personale)<br></b><br>Il tuo WhatsApp<br>+1-555-YOU"] -- message --> B["<b>Secondo telefono (assistente)<br></b><br>WA assistente<br>+1-555-ASSIST"]
    B -- linked via QR --> C["<b>Il tuo Mac (openclaw)<br></b><br>Agente Pi"]

Se colleghi il tuo WhatsApp personale a OpenClaw, ogni messaggio che ricevi diventa “input per l’agente”. Raramente è ciò che vuoi.

Quick start in 5 minuti

  1. Abbina WhatsApp Web (mostra il QR; scansiona con il telefono dell’assistente):
openclaw channels login
  1. Avvia il Gateway (lascialo in esecuzione):
openclaw gateway --port 18789
  1. Inserisci una configurazione minimale in ~/.openclaw/openclaw.json:
{
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

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

Quando l’onboarding termina, si apre automaticamente la dashboard e viene stampato un link pulito (non tokenizzato). Se richiede l’autenticazione, incolla il token da gateway.auth.token nelle impostazioni della Control UI. Per riaprire in seguito: openclaw dashboard.

Dare all’agente un workspace (AGENTS)

OpenClaw legge le istruzioni operative e la “memoria” dalla directory del workspace.

Per impostazione predefinita, OpenClaw usa ~/.openclaw/workspace come workspace dell’agente e lo crea automaticamente (con i file iniziali AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md) durante il setup o la prima esecuzione. BOOTSTRAP.md viene creato solo quando il workspace è completamente nuovo (non dovrebbe ricomparire dopo averlo eliminato). MEMORY.md è opzionale (non viene creato automaticamente); quando presente, viene caricato per le sessioni normali. Le sessioni dei sub-agenti iniettano solo AGENTS.md e TOOLS.md.

Suggerimento: tratta questa cartella come la “memoria” di OpenClaw e rendila un repository git (idealmente privato) così i tuoi file AGENTS.md e di memoria sono al sicuro. Se git è installato, i workspace nuovi vengono inizializzati automaticamente.

openclaw setup

Layout completo del workspace e guida al backup: Workspace dell’agente Workflow della memoria: Memoria

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

{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

Se gestisci già i tuoi file del workspace tramite un repository, puoi disabilitare completamente la creazione dei file di bootstrap:

{
  agent: {
    skipBootstrap: true,
  },
}

La configurazione che lo trasforma in “un assistente”

OpenClaw ha già impostazioni predefinite adatte a un uso come assistente, ma in genere vorrai personalizzare:

  • persona/istruzioni in SOUL.md
  • valori predefiniti del thinking (se desiderato)
  • heartbeat (una volta che ti fidi del setup)

Esempio:

{
  logging: { level: "info" },
  agent: {
    model: "anthropic/claude-opus-4-6",
    workspace: "~/.openclaw/workspace",
    thinkingDefault: "high",
    timeoutSeconds: 1800,
    // Parti con 0; abilita in seguito.
    heartbeat: { every: "0m" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  routing: {
    groupChat: {
      mentionPatterns: ["@openclaw", "openclaw"],
    },
  },
  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 (utilizzo 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, l’agente risponde con un breve saluto per confermare il reset.
  • /compact [istruzioni] compatta il contesto della sessione e riporta il budget di contesto rimanente.

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 è effettivamente vuoto (solo righe vuote e intestazioni markdown come # Heading), OpenClaw salta l’esecuzione dell’heartbeat per risparmiare chiamate API.
  • Se il file è assente, l’heartbeat viene comunque eseguito e il modello decide cosa fare.
  • Se l’agente risponde con HEARTBEAT_OK (opzionalmente con breve padding; vedi agents.defaults.heartbeat.ackMaxChars), OpenClaw sopprime la consegna in uscita per quell’heartbeat.
  • Per impostazione predefinita, la consegna dell’heartbeat a target DM di tipo user:<id> è consentita. Imposta agents.defaults.heartbeat.directPolicy: "block" per sopprimere la consegna diretta mantenendo attive le esecuzioni dell’heartbeat.
  • Gli heartbeat eseguono turni completi dell’agente — intervalli più brevi consumano più token.
{
  agent: {
    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)

Allegati in uscita dall’agente: includi MEDIA:<percorso-o-url> su una riga a sé (senza spazi). Esempio:

Here's the screenshot.
MEDIA:https://example.com/screenshot.png

OpenClaw estrae questi riferimenti e li invia come media insieme al testo.

Checklist operativa

openclaw status          # stato locale (credenziali, sessioni, eventi in coda)
openclaw status --all    # diagnosi completa (sola lettura, incollabile)
openclaw status --deep   # aggiunge probe di health del gateway (Telegram + Discord)
openclaw health --json   # snapshot dello stato del gateway (WS)

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

Passi successivi

arrow_back
Precedente
Onboarding
Successivo
Wizard CLI Reference
arrow_forward