Anatomia di una configurazione Openclaw perfetta

Una guida completa ai file del workspace, alle skill, ai canali, alle autorizzazioni e a come configurarli correttamente.

La maggior parte degli utenti di OpenClaw lo installa, collega un canale e non apre mai la cartella del workspace.

Questo è un errore.

Il tuo workspace è il centro di controllo per il comportamento del tuo assistente AI. Contiene la tua identità, le skill personalizzate, le connessioni ai canali e la memoria. Una volta che capisci cosa si trova dove, puoi configurare OpenClaw esattamente come ti serve.

Questa guida analizza l'anatomia di una configurazione perfetta.

PS: Openclaw è solo l'inizio.

All'interno della nostra community Build With AI, ti insegneremo come costruire agenti, app e automazioni personalizzate che potrai usare tu stesso o vendere ai clienti. In arrivo a breve.

Iscriviti alla lista d'attesa qui: https://return-my-time.kit.com/1bd2720397

-----------------------------------------

Due livelli di configurazione, non uno

Prima di addentrarci, una cosa da sapere subito: OpenClaw utilizza due livelli di configurazione.

Il primo è la cartella del tuo workspace (di solito ~/clawd/ o dove hai inizializzato). Questa contiene la tua configurazione personale, le skill, la memoria e i segreti.

Il secondo è l'installazione globale in opt/homebrew/lib/node_modules/clawdbot/ (o l'equivalente sul tuo sistema). Questa contiene i documenti principali, le skill integrate e i comportamenti predefiniti.

Il tuo workspace è dove personalizzi. L'installazione globale è quella che aggiorni.

AGENTS.md: Le tue istruzioni operative

Questo è il file più importante dell'intera configurazione. Quando OpenClaw avvia una sessione, la prima cosa che legge è AGENTS.md. Lo carica direttamente nel prompt di sistema e lo tiene a mente per l'intera conversazione.

In parole povere: qualunque cosa tu scriva in AGENTS.md, il tuo agente la seguirà.

Se gli dici di controllare sempre il tuo calendario prima di suggerire orari per le riunioni, lo farà. Se dici "non inviare mai email senza la mia esplicita approvazione", lo rispetterà ogni volta.

Cosa dovrebbe davvero stare in AGENTS.md:

Scrivi:

• La tua direttiva operativa principale (qual è il compito dell'agente?)
• Gli strumenti chiave e come usarli (CLI email, flussi di lavoro per la gestione delle attività)
• Regole ferree che non devono mai essere infrante
• Link a risorse importanti (documentazione API, percorsi delle skill)
• Trigger dei flussi di lavoro (cosa dovrebbe accadere automaticamente)

Non scrivere:

• Documentazione completa a cui puoi invece linkare
• Lunghi paragrafi che spiegano la teoria
• Informazioni che cambiano frequentemente

Mantieni AGENTS.md sotto le 300 righe. File più lunghi iniziano a consumare troppo contesto e l'aderenza alle istruzioni diminuisce effettivamente.

Ecco un esempio minimo ma efficace:

1# AGENTS.md - Workspace Clawdbot
2
3## Direttiva Operativa Principale
4Il mio assistente opera come un aiuto proattivo per la mia attività.
5
6**Il Mandato:**
7- Togliere più lavoro possibile dalle mie mani
8- Essere proattivo - non aspettare che gli venga chiesto
9
10## Strumenti Chiave
11- **Email:** Controlla la posta in arrivo ogni giorno, segnala gli elementi urgenti
12- **Calendario:** Verifica che non ci siano conflitti prima di pianificare
13- **Task Manager:** Sincronizza il lavoro completato nel dashboard
14
15## Regole Ferree
16- NON riavviare mai i servizi senza permesso esplicito
17- Verifica sempre le date con il comando `date` prima di pianificare
18- Registra tutto il lavoro completato nel sistema di tracciamento

Sono circa 20 righe di direttive principali. Dà al tuo agente tutto ciò di cui ha bisogno per lavorare in modo produttivo senza continue richieste di chiarimenti.

SOUL.md: Personalità e confini

SOUL.md definisce chi è il tuo agente e come dovrebbe comunicare. È qui che vive la personalità.

1# SOUL.md - Personalità e Confini
2
3- Mantieni le risposte concise e dirette.
4- Fai domande di chiarimento quando necessario.
5- Non inviare mai risposte parziali/in streaming a superfici di messaggistica esterne.

Se AGENTS.md è il manuale di istruzioni, SOUL.md è il profilo di personalità. Alcuni utenti scrivono qui personalità estese. Altri lo mantengono minimale. Entrambi funzionano, dipende da quanta personalizzazione della personalità desideri.

IDENTITY.md e USER.md: Chi è chi

Questi due file stabiliscono la relazione tra il tuo agente e te.

IDENTITY.md definisce il tuo agente:

1# IDENTITY.md - Identità dell'Agente
2
3- Nome: [Nome del tuo Agente]
4- Creatura: [Opzionale: descrizione divertente]
5- Stile: Intelligente, utile, affidabile, risolutore di problemi tenace
6- Emoji: [La tua emoji scelta]

USER.md definisce te:

1# USER.md - Profilo Utente
2
3- Nome: [Il tuo nome]
4- Appellativo preferito: [Soprannome]
5- Fuso orario: [Il tuo fuso orario]
6- Telefono: [Il tuo numero]
7- Calendario: [Piattaforma calendario ed email]

Perché file separati? Perché servono a scopi diversi. IDENTITY.md raramente cambia una volta impostato. USER.md si aggiorna man mano che le tue preferenze evolvono. Tenerli separati rende la manutenzione più facile.

HEARTBEAT.md: Check-in programmati

Questo file controlla cosa fa il tuo agente durante i poll del heartbeat (battito cardiaco), ovvero i momenti programmati in cui il sistema verifica se c'è qualcosa che necessita attenzione.

1# HEARTBEAT.md
2
3**Se il messaggio contiene "⚠️ ESECUZIONE CRON":**
4- Questo NON è un controllo heartbeat - è lavoro da fare
5- Leggi le istruzioni complete nel messaggio
6- Esegui tutti i passaggi richiesti
7- Non restituire mai HEARTBEAT_OK
8
9**Altrimenti:**
10- Se non c'è nulla che richiede attenzione, restituisci HEARTBEAT_OK
11- Mantienilo minimale

Gli heartbeat sono potenti per creare agenti proattivi. Il tuo agente può controllare il tuo calendario, scansionare la tua posta in arrivo o eseguire qualsiasi flusso di lavoro automatizzato secondo una pianificazione, il tutto attivato dai poll heartbeat.

TOOLS.md: Documentazione degli strumenti esterni

Questo file contiene le tue note sugli strumenti esterni e le convenzioni. Non definisce quali strumenti esistono (OpenClaw gestisce questo internamente), ma è qui che documenti COME li usi TU.

1# TOOLS.md - Note sugli Strumenti Utente
2
3## CLI Email
4- Account: [email protected]
5- Comune: `cli email search`, `cli calendar create`
6
7## API Gestione Attività
8- Posizione token: ~/.secrets/task-api-token.txt
9- Usa sempre `limit=100` per evitare problemi di paginazione
10- Conversione stato: [documenta il tuo flusso di lavoro specifico]
11
12## Strumento di web scraping (quando i siti bloccano le richieste normali)
13- Posizione: ~/clawd/.venv/scraper
14- Usa la modalità stealth per i siti protetti

Questa diventa la tua guida di riferimento personale. Quando il tuo agente ha bisogno di usare uno strumento, controlla TOOLS.md per le tue convenzioni specifiche.

La cartella skills/: Flussi di lavoro riutilizzabili

Le skill sono dove OpenClaw diventa potente. Ogni skill è un flusso di lavoro indipendente che il tuo agente può invocare quando l'attività corrisponde alla descrizione della skill.

Ogni skill vive nella propria sottocartella con un file SKILL.md:

1skills/
2├── meeting-prep/
3│   └── SKILL.md
4├── social-post-writer/
5│   ├── SKILL.md
6│   └── references/
7│       └── templates.md
8└── podcast-show-notes/
9    └── SKILL.md

Un file SKILL.md utilizza il frontmatter YAML per descrivere quando usarlo:

1---
2name: meeting-prep
3description: Ricerca e briefing automatizzati pre-chiamata. Usa quando l'utente chiede di controllare le prossime riunioni o di eseguire il briefing per una riunione.
4---
5
6# Skill Meeting Prep
7
8## Quando attivarla:
9- L'utente chiede di controllare le prossime riunioni
10- Programmata per essere eseguita ogni 10 minuti tramite cron
11- Prepara il briefing solo per PRIME CHIAMATE
12
13## Procedura:
141. Controlla il calendario per le riunioni nei prossimi 15-45 minuti
152. Ricerca i partecipanti (LinkedIn, sito aziendale)
163. Crea un documento di briefing
174. Allega il link all'evento del calendario

La differenza fondamentale rispetto alle istruzioni statiche: le skill possono raggruppare file di supporto insieme a loro. Il file references/templates.md può contenere output di esempio, formati comprovati o contesto aggiuntivo che viene caricato solo quando la skill è attiva.

La cartella memory/: Contesto persistente

Questa è la memoria a lungo termine del tuo agente. Trascrizioni delle sessioni, preferenze apprese e registri giornalieri vivono tutti qui.

1memory/
2├── 2026-03-22.md
3├── 2026-03-21.md
4├── email-style.md
5├── business-context-2026-02.md
6└── workflow-playbook.md

Buone pratiche:

• Mantieni i registri giornalieri in memory/YYYY-MM-DD.md
• All'avvio della sessione, il tuo agente legge oggi + ieri se presenti
• Cattura fatti duraturi, preferenze e decisioni
• Evita di memorizzare segreti

I file di memoria sono ciò che dà al tuo agente contesto tra le sessioni. Senza di essi, ogni conversazione ricomincia da zero.

La cartella .secrets/: Credenziali

Token API, password e configurazioni sensibili vivono qui. Questa cartella dovrebbe essere in gitignore e mai committata.

1.secrets/
2├── task-api-token.txt
3├── openai-api-key.txt
4├── anthropic-api-key.txt
5└── service-credentials.txt

I tuoi AGENTS.md o TOOLS.md possono fare riferimento a questi percorsi senza esporre i valori effettivi.

Configurazione del canale: Dove parli con il tuo agente

OpenClaw supporta più canali di messaggistica: Discord, Telegram, Signal, WhatsApp e altri. La configurazione del canale risiede nella configurazione del tuo gateway (gestita tramite i comandi del gateway clawdbot).

Concetti chiave:

• Ogni canale ha il proprio comportamento di sessione
• Puoi avere più canali attivi simultaneamente
• Le regole specifiche del canale (come "non rispondere a meno che non venga @menzionato su Discord") vanno in AGENTS.md

Il quadro completo

Ecco come tutto si unisce:

1~/clawd/
2├── AGENTS.md           # Istruzioni operative (uso quotidiano)
3├── SOUL.md             # Personalità e confini
4├── IDENTITY.md         # Identità dell'agente
5├── USER.md             # Il tuo profilo
6├── HEARTBEAT.md        # Comportamento dei check-in programmati
7├── TOOLS.md            # Documentazione degli strumenti esterni
8├── BOOTSTRAP.md        # Rituale di primo avvio (elimina dopo)
9│
10├── skills/             # Flussi di lavoro personalizzati
11│   ├── meeting-prep/
12│   ├── podcast-show-notes/
13│   └── social-post-writer/
14│
15├── memory/             # Contesto persistente
16│   ├── 2026-03-22.md
17│   └── key-context.md
18│
19├── .secrets/           # Chiavi API e credenziali (gitignorate)
20│   ├── task-api-token.txt
21│   └── anthropic-api-key.txt
22│
23└── output/             # File generati ed esportazioni

Una configurazione pratica per iniziare

Se stai partendo da zero, ecco una progressione che funziona bene.

Passo 1. Esegui openclaw onboard e completa la configurazione iniziale. Scegli il tuo provider di modelli e connetti almeno un canale.

Passo 2. Crea la cartella del tuo workspace e aggiungi AGENTS.md con le tue direttive principali. Inizia con 10-20 righe che coprono i tuoi casi d'uso principali.

Passo 3. Aggiungi IDENTITY.md, USER.md e SOUL.md. Questi stabiliscono la relazione e la personalità.

Passo 4. Crea la tua prima skill per un flusso di lavoro che esegui ripetutamente. La preparazione delle riunioni, le bozze delle email o la creazione di contenuti sono buoni punti di partenza.

Passo 5. Configura memory/ con un modello di registro giornaliero. Il tuo agente inizierà a costruire contesto nel tempo.

Passo 6. Aggiungi TOOLS.md man mano che scopri pattern specifici degli strumenti che vale la pena documentare.

Questo è davvero tutto ciò di cui hai bisogno per il 95% dei casi d'uso. Funzionalità avanzate come i cron job, le configurazioni multi-agente e i plugin per canali personalizzati entrano in gioco quando hai flussi di lavoro specifici che vale la pena automatizzare.

Il punto chiave

Il tuo workspace OpenClaw è in realtà un protocollo per dire al tuo assistente AI chi sei, cosa deve fare e quali regole deve seguire. Più chiaramente lo definisci, meno tempo passi a correggere il tuo agente e più tempo passa a fare lavoro utile.

AGENTS.md è il tuo file a più alta leva. Imposta quello per primo. Tutto il resto è ottimizzazione.

Inizia in piccolo, perfeziona man mano, e trattalo come qualsiasi altra infrastruttura nel tuo flusso di lavoro: qualcosa che dà i suoi frutti ogni giorno una volta impostato correttamente.

PS: Openclaw è solo l'inizio.

All'interno della nostra community Build With AI, ti insegnerò come costruire agenti, app e automazioni personalizzate che potrai usare tu stesso o vendere ai clienti. In arrivo a breve.

Iscriviti alla lista d'attesa qui:

https://return-my-time.kit.com/1bd2720397