Rompo un po' le balle con charlotte, che mi ha intrippato bene. Testata con Kimi-code e Claude Opus 4. Prima c'è da installare la skill charlotte con npx (e vedere che sia installato e a posto anche il binary di charlotte), installare mcporter con npm (incazzarsi perché il file di configurazione mcporter.json non è nel posto giusto per l'installazione standard e creare un symlink tra il json di configurazione di mcporter per openclaw e il posto standard), installare la skill mcporter per OpenClaw, configurare mcporter per usare charlotte, configurare systemd (o quel che volete) per avviare e monitorare un daemon con mcporter che attende di farvi parlare con charlotte, creare una skill per insegnare a OpenClaw a usare charlotte.
Questa la configuarzione di mcporter per usare charlotte:
{
"mcpServers": {
"charlotte": {
"command": "node",
"args": ["/home/openclaw/.npm-global/lib/node_modules/@ticktockbent/charlotte/dist/index.js"],
"lifecycle": "keep-alive"
}
}
}
/home/openclaw/ lo si cambia con la home del proprio utente openclaw. keep-alive altrimenti ripartiamo da zero ogni volta.
Questo è per systemd, Direttamente il comando da eseguire con il proprio utente openclaw per configurare il daemon su Abbraccianigga OS (io uso 24.04 lts):
cat > ~/.config/systemd/user/mcporter-daemon.service << 'EOF'
[Unit]
Description=mcporter MCP daemon
After=network.target
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/home/openclaw/.npm-global/bin/mcporter daemon start
ExecStop=/home/openclaw/.npm-global/bin/mcporter daemon stop
ExecReload=/home/openclaw/.npm-global/bin/mcporter daemon restart
Environment=MCPORTER_CONFIG=/home/openclaw/.mcporter/mcporter.json
[Install]
WantedBy=default.target
EOF
/home/openclaw/ lo si cambia con la home del proprio utente openclaw.
Per la cronaca il symlink che dicevo prima è proprio /home/openclaw/.mcporter/mcporter.json
Questo lo SKILL.md per usare charlotte con OpenClaw. Occhio che ho scritto qui tel.egram per il noto wordfilter.
---
name: charlotte-browser
description: "Browse and interact with web pages via Charlotte MCP server (headless Chromium) using mcporter. Use this skill when the user asks to read, scrape, or analyze web page content, fill forms, click links or buttons, navigate multi-page workflows, take screenshots, or interact with any website. Also use when you need to fetch structured web content that simple HTTP requests cannot handle (JavaScript-rendered pages, SPAs, pages behind cookie consent). Triggers: 'open this page', 'read this website', 'fill this form', 'click', 'screenshot', 'browse', 'scrape', 'web page', 'navigate to'."
metadata: {"openclaw":{"os":["linux"],"requires":{"bins":["mcporter"]},"emoji":"🕸️"}}
---
# Charlotte Browser Skill
Charlotte is an MCP server providing headless Chromium browser automation via mcporter.
It returns structured page representations (accessibility tree, interactive elements, content)
instead of raw HTML.
## Calling Convention — READ THIS FIRST
Charlotte tools are called via mcporter. The server name is `charlotte`.
Each tool name has a `charlotte:` prefix. The full call pattern is:
```
mcporter call charlotte.charlotte:<toolname> key=value key2=value2
```
The `charlotte.charlotte:` prefix is mandatory: the first part is the mcporter server name,
the second is the MCP tool namespace. Example:
```bash
mcporter call charlotte.charlotte:navigate url=https://www.ansa.it
mcporter call charlotte.charlotte:observe detail=full
mcporter call charlotte.charlotte:find type=link text=About
mcporter call charlotte.charlotte:click element_id=lnk-d4b9
```
### Syntax Rules
**ALWAYS use `key=value` syntax for ALL parameters.**
For values with spaces, use quotes:
```bash
mcporter call charlotte.charlotte:find text="breaking news"
mcporter call charlotte.charlotte:type element_id=inp-c7e2 text="hello world"
```
For parameters requiring objects or arrays (cookies, headers), use `--args` with valid JSON:
```bash
mcporter call charlotte.charlotte:set_cookies --args '{"cookies":[{"name":"session","value":"abc","domain":"example.com"}]}'
```
### NEVER DO THIS
```bash
# WRONG: JSON as positional argument — causes "Tool not found"
mcporter call charlotte navigate '{"url": "https://example.com"}'
# WRONG: Missing charlotte: namespace — causes "Tool navigate not found"
mcporter call charlotte.navigate url=https://example.com
# WRONG: Double-dash flags — mcporter misinterprets them as its own flags
mcporter call charlotte.charlotte:navigate --url "https://example.com"
mcporter call charlotte.charlotte:navigate --wait_for load
# WRONG: JSON without --args flag
mcporter call charlotte.charlotte:navigate '{"url": "https://example.com"}'
```
## Core Workflow
The standard workflow is always: **navigate → observe → (interact → observe)***.
1. **Navigate** to the URL (returns minimal page structure)
2. **Observe** to get page content at desired detail level
3. **Find** specific elements if you need to interact
4. **Interact** (click, type, select, submit)
5. **Observe** again to see updated content
**Always observe before any interaction. Always observe after any interaction.**
## Tools Reference
### Navigation
**charlotte:navigate** — Load a URL. Returns page structure at minimal detail.
```bash
mcporter call charlotte.charlotte:navigate url=https://www.ansa.it
```
Parameters: `url` (required), `wait_for` (load|domcontentloaded|networkidle, default: load), `timeout` (ms, default: 30000).
After navigate, always call **charlotte:observe** to get actual page content.
**charlotte:back** / **charlotte:forward** — Browser history.
```bash
mcporter call charlotte.charlotte:back
mcporter call charlotte.charlotte:forward
```
**charlotte:reload** — Reload page.
```bash
mcporter call charlotte.charlotte:reload
mcporter call charlotte.charlotte:reload hard=true
```
### Observation
**charlotte:observe** — Get page content. This is the primary tool for reading pages.
- `minimal`: landmarks + interactive element counts. Quick orientation.
- `summary` (default): content summaries + full element list. Best for most tasks.
- `full`: all visible text content. Use when you need the actual text.
```bash
mcporter call charlotte.charlotte:observe
mcporter call charlotte.charlotte:observe detail=full
mcporter call charlotte.charlotte:observe detail=minimal
```
Optional: `selector` (CSS selector to scope observation, e.g. `selector=#main-content`), `include_styles` (true|false).
**charlotte:find** — Search for interactive elements.
```bash
mcporter call charlotte.charlotte:find type=link text=About
mcporter call charlotte.charlotte:find type=button text=Submit
mcporter call charlotte.charlotte:find type=text_input
mcporter call charlotte.charlotte:find text="search"
```
Parameters (all optional, use at least one): `text` (case-insensitive substring), `role` (ARIA role), `type` (button|link|text_input|select|checkbox|etc.), `near` (element ID, ~200px radius), `within` (element ID).
**charlotte:screenshot** — Visual screenshot.
```bash
mcporter call charlotte.charlotte:screenshot
mcporter call charlotte.charlotte:screenshot save=true
mcporter call charlotte.charlotte:screenshot selector="#chart" format=jpeg quality=80
```
**charlotte:screenshots** — List saved screenshots.
```bash
mcporter call charlotte.charlotte:screenshots
```
**charlotte:screenshot_get** — Retrieve a saved screenshot.
```bash
mcporter call charlotte.charlotte:screenshot_get id=ss-20260224103000-a1b2c3
```
**charlotte:diff** — Compare current page to previous snapshot.
```bash
mcporter call charlotte.charlotte:diff
mcporter call charlotte.charlotte:diff scope=content
```
Parameters: `snapshot_id` (specific snapshot), `scope` (all|structure|interactive|content).
### Interaction
**charlotte:click** — Click an element.
```bash
mcporter call charlotte.charlotte:click element_id=btn-a3f1
mcporter call charlotte.charlotte:click element_id=lnk-d4b9
```
Parameters: `element_id` (required), `click_type` (left|right|double, default: left).
**charlotte:type** — Type into an input field.
```bash
mcporter call charlotte.charlotte:type element_id=inp-c7e2 text="hello@example.com"
mcporter call charlotte.charlotte:type element_id=inp-c7e2 text="search query" press_enter=true
```
Parameters: `element_id` (required), `text` (required), `clear_first` (true|false, default: true), `press_enter` (true|false, default: false). Use `press_enter=true` for search fields.
**charlotte:select** — Choose from a dropdown.
```bash
mcporter call charlotte.charlotte:select element_id=sel-e8a3 value=Italy
```
**charlotte:toggle** — Toggle a checkbox or switch.
```bash
mcporter call charlotte.charlotte:toggle element_id=chk-f1a2
```
**charlotte:submit** — Submit a form by form ID.
```bash
mcporter call charlotte.charlotte:submit form_id=frm-b1d4
```
**charlotte:scroll** — Scroll the page.
```bash
mcporter call charlotte.charlotte:scroll direction=down
mcporter call charlotte.charlotte:scroll direction=down amount=half
mcporter call charlotte.charlotte:scroll direction=up amount=200
```
Parameters: `direction` (required: up|down|left|right), `amount` (page|half|pixel value, default: page), `element_id` (scroll within container).
**charlotte:hover** — Hover over an element (for tooltips, menus).
```bash
mcporter call charlotte.charlotte:hover element_id=btn-a3f1
```
**charlotte:key** — Press a keyboard key.
```bash
mcporter call charlotte.charlotte:key key=Enter
mcporter call charlotte.charlotte:key key=Escape
```
Parameters: `key` (required: Escape, Tab, Enter, ArrowDown, ArrowUp, Backspace, Delete, Home, End, PageUp, PageDown, or single character). For modifier combos use --args: `--args '{"key":"a","modifiers":["ctrl"]}'`
**charlotte:wait_for** — Wait for a condition.
```bash
mcporter call charlotte.charlotte:wait_for text="Results loaded"
mcporter call charlotte.charlotte:wait_for selector="#results"
mcporter call charlotte.charlotte:wait_for element_id=btn-a3f1 state=visible
```
Parameters (all optional, use at least one): `element_id`+`state` (visible|hidden|enabled|disabled|exists|removed), `text`, `selector`, `js` (JS expression), `timeout` (ms, default: 10000).
**charlotte:dialog** — Handle JavaScript dialogs (alert, confirm, prompt).
```bash
mcporter call charlotte.charlotte:dialog accept=true
mcporter call charlotte.charlotte:dialog accept=false
```
### Tab Management
```bash
mcporter call charlotte.charlotte:tabs
mcporter call charlotte.charlotte:tab_open url=https://example.com
mcporter call charlotte.charlotte:tab_switch tab_id=1
mcporter call charlotte.charlotte:tab_close tab_id=2
```
### Viewport, Cookies, Headers, Network
```bash
mcporter call charlotte.charlotte:viewport device=mobile
mcporter call charlotte.charlotte:get_cookies
mcporter call charlotte.charlotte:clear_cookies
mcporter call charlotte.charlotte:set_cookies --args '{"cookies":[{"name":"s","value":"v","domain":"example.com"}]}'
mcporter call charlotte.charlotte:set_headers --args '{"headers":{"Authorization":"Bearer tok"}}'
mcporter call charlotte.charlotte:network throttle=3g
mcporter call charlotte.charlotte:network --args '{"block":["*.ads.com"]}'
```
### Configuration
```bash
mcporter call charlotte.charlotte:configure dialog_auto_dismiss=accept_alerts
mcporter call charlotte.charlotte:configure screenshot_dir=/tmp/screenshots
```
## Element IDs
Charlotte assigns stable hash-based IDs to interactive elements. The prefix indicates the type:
| Prefix | Type | Example |
|--------|------------|------------|
| `btn-` | Button | `btn-a3f1` |
| `lnk-` | Link | `lnk-d4b9` |
| `inp-` | Text input | `inp-c7e2` |
| `sel-` | Select | `sel-e8a3` |
| `chk-` | Checkbox | `chk-f1a2` |
| `frm-` | Form | `frm-b1d4` |
Always get element IDs from `charlotte:observe` or `charlotte:find` output. Never guess IDs.
## Tested Workflows
### Read a page (tested, working)
```bash
mcporter call charlotte.charlotte:navigate url=https://www.ansa.it
mcporter call charlotte.charlotte:observe detail=full
```
### Find and click a link (tested, working)
```bash
mcporter call charlotte.charlotte:navigate url=https://www.ansa.it
mcporter call charlotte.charlotte:observe detail=summary
mcporter call charlotte.charlotte:find type=link text="Politica"
mcporter call charlotte.charlotte:click element_id=lnk-xxxx
mcporter call charlotte.charlotte:observe detail=full
```
### Search via form (tested pattern)
```bash
mcporter call charlotte.charlotte:navigate url=https://www.ansa.it
mcporter call charlotte.charlotte:observe detail=summary
mcporter call charlotte.charlotte:find type=text_input
mcporter call charlotte.charlotte:type element_id=inp-xxxx text="search query" press_enter=true
mcporter call charlotte.charlotte:wait_for text="results"
mcporter call charlotte.charlotte:observe detail=summary
```
### Handle cookie consent
```bash
mcporter call charlotte.charlotte:navigate url=https://example.com
mcporter call charlotte.charlotte:observe detail=summary
mcporter call charlotte.charlotte:find type=button text=Accept
mcporter call charlotte.charlotte:click element_id=btn-xxxx
mcporter call charlotte.charlotte:observe detail=summary
```
## Limitations
- Headless browser: no visual display.
- CAPTCHA and aggressive anti-bot protections will block Charlotte.
- Cookie consent banners must be dismissed via click.
- Browser state persists while daemon runs, resets on daemon restart.
- Some sites may require `wait_for=networkidle` on navigate for full content loading.
Questo il corso di istruzione:
# Navigare il web con l'agente: prompting per charlotte in OpenClaw
Corso in tre parti per utilizzare efficacemente la skill Charlotte Browser nell'interazione quotidiana con il tuo agente OpenClaw e nei cron job automatizzati.
**Ambiente di riferimento:** OpenClaw 2026.2 su Ub.untu OS 24.04 LTS headless, con skill mcporter e skill charlotte installate, daemon mcporter attivo con charlotte in modalità keep-alive.
---
## Parte 1 — Come funziona la catena: skills, mcporter, charlotte
### Come OpenClaw usa le skills
Quando avvii una sessione con il tuo agente OpenClaw, succede qualcosa che è importante capire per scrivere prompt efficaci. Il sistema non carica il testo completo di ogni skill installata nel prompt di sistema. Sarebbe troppo costoso in termini di token. Invece, OpenClaw inietta nel system prompt una lista compatta delle skill disponibili: solo il nome, la descrizione e il path del file SKILL.md.
Quando l'agente riceve il tuo messaggio, legge questa lista e decide se qualcuna delle skill è rilevante per quello che gli stai chiedendo. Se lo è, carica il contenuto del SKILL.md on demand — lo legge in quel momento, come faresti tu aprendo un manuale.
Questo ha una conseguenza pratica diretta sul prompting: **la descrizione della skill è il trigger**. Se il tuo prompt contiene parole o concetti che corrispondono alla descrizione della skill, l'agente la attiva. Se il tuo prompt è troppo vago o non tocca i trigger giusti, l'agente potrebbe non pensare di usare Charlotte anche quando sarebbe utile.
La descrizione della nostra skill charlotte-browser contiene trigger come: "read this website", "fill this form", "click", "screenshot", "browse", "scrape", "web page", "navigate to". Questo significa che un prompt come "vai su example.com e dimmi cosa c'è" dovrebbe attivare Charlotte, mentre "cerca informazioni su X" potrebbe NON FARLO, perché l'agente potrebbe preferire una ricerca web standard.
Un altro dettaglio importante: le skill vengono "fotografate" all'inizio della sessione. Se modifichi un file SKILL.md mentre una sessione è attiva, le modifiche non avranno effetto fino alla sessione successiva (a meno che il watch automatico di OpenClaw non rilevi il cambiamento e forzi un refresh — ma è meglio non contarci).
### Come mcporter fa da ponte
OpenClaw non sa parlare direttamente con i server MCP. Non ha un client MCP integrato nel suo runtime (è una feature richiesta da molti utenti ma non ancora implementata nella versione 2026.2). L'unico modo che l'agente ha per raggiungere un server MCP è attraverso mcporter, un CLI che fa da ponte.
Quando l'agente decide di usare Charlotte, quello che fa concretamente è eseguire un comando bash tramite il tool exec di OpenClaw. Il comando è qualcosa come:
```
mcporter call charlotte.navigate url=https://example.com
```
mcporter riceve il comando, lo traduce nel protocollo MCP (JSON-RPC via stdio), lo invia al processo Charlotte (che il daemon mcporter tiene vivo in background), riceve la risposta, e la restituisce all'agente come output testuale.
L'agente non sa nulla del protocollo MCP, dello stdio, del JSON-RPC. Vede solo un comando bash e il suo output. Tutto il "sapere come usare Charlotte" viene dalla SKILL.md che abbiamo scritto — è lì che l'agente impara che deve chiamare `mcporter call charlotte.observe detail=summary` e non `curl https://example.com`.
Nella nostra configurazione, Charlotte gira con `lifecycle: keep-alive`, il che significa che il daemon mcporter mantiene il processo Charlotte (e il suo Chromium headless) sempre attivo. Questo è importante perché Charlotte è stateful: mantiene lo stato del browser tra una chiamata e l'altra (cookie, sessione, tab aperti). Se fosse ephemeral, ogni chiamata avvierebbe un nuovo Chromium da zero — lento e senza memoria.
### Come Charlotte vede le pagine web
Charlotte non restituisce HTML grezzo all'agente. Sarebbe inutile: un LLM non naviga il DOM. Invece, Charlotte usa l'accessibility tree del browser (lo stesso che usano gli screen reader per le persone non vedenti) per costruire una rappresentazione strutturata della pagina: landmark, heading, link, bottoni, form, input, con le loro posizioni e proprietà.
Ogni elemento interattivo riceve un ID stabile basato su un hash dei suoi metadati. Gli ID hanno un prefisso che indica il tipo: `btn-` per i bottoni, `lnk-` per i link, `inp-` per gli input, `sel-` per i select, `chk-` per i checkbox, `frm-` per i form. Questo permette all'agente di riferirsi a un elemento specifico quando deve cliccarci sopra o digitarci dentro.
Ci sono tre livelli di dettaglio nella rappresentazione:
Il livello **minimal** restituisce solo i landmark e gli elementi interattivi — poche centinaia di token, utile per un'occhiata veloce alla struttura. Il livello **summary** aggiunge i riassunti dei contenuti, i form, gli errori — il miglior compromesso tra informazione e consumo di token, e il livello che l'agente dovrebbe usare per default. Il livello **full** include tutto il testo visibile della pagina — da usare solo quando serve il contenuto effettivo, perché può essere molto lungo.
---
## Parte 2 — Prompting per la navigazione web con Charlotte
### Il principio fondamentale: sii esplicito sul "cosa" e lascia il "come" alla skill
Il tuo agente ha già le istruzioni tecniche nel SKILL.md. Non devi dirgli di usare `mcporter call charlotte.navigate`. Devi dirgli cosa vuoi ottenere, usando parole che attivano la skill.
Confrontiamo due approcci.
**Prompt debole:**
> Cerca informazioni sul nuovo regolamento UE sulla fatturazione elettronica.
Questo prompt è ambiguo. L'agente potrebbe fare una ricerca web standard, consultare la sua knowledge base, o usare Charlotte. Non c'è nulla che lo spinga verso il browser.
**Prompt efficace:**
> Apri il sito https://eur-lex.europa.eu, cerca "e-invoicing regulation 2025" nel campo di ricerca, e riportami il titolo e la data di pubblicazione del primo risultato.
Qui l'agente sa esattamente cosa fare: aprire un sito specifico, interagire con un form di ricerca, estrarre dati specifici. Le parole "apri il sito" e "cerca nel campo di ricerca" attivano Charlotte.
### Pattern 1: Leggere una pagina
Il caso più semplice. Vuoi che l'agente vada su una pagina e ti dica cosa c'è.
> Apri la pagina https://www.agenziae...mativa-e-prassie fammi un riassunto dei documenti pubblicati questa settimana.
L'agente navigherà alla pagina, farà un observe (probabilmente a livello summary per orientarsi, poi full per leggere i contenuti), e ti restituirà un riassunto.
Se la pagina è lunga e paginata, puoi essere più specifico:
> Vai su https://example.com/news, leggi i titoli e le date dei primi 10 articoli. Se c'è una seconda pagina, clicca "Next" e leggi anche quelli.
Questo prompt dice all'agente che deve gestire la paginazione — cliccando un link — il che implica un workflow multi-step: navigate → observe → extract → find "Next" → click → wait → observe → extract.
### Pattern 2: Compilare un form
Questo è uno dei casi dove Charlotte brilla rispetto a un semplice fetch HTTP: le pagine con form JavaScript non funzionano senza un browser vero.
> Vai su https://telematici.a...icaCF/Scegli.do, inserisci il codice fiscale RSSMRA85M01F205X nel campo appropriato, clicca il pulsante di verifica e dimmi il risultato.
L'agente dovrà: navigare → observe per trovare il form → find per localizzare il campo input → type per inserire il CF → find per localizzare il bottone → click → wait per il risultato → observe per leggerlo.
Quando il form è complesso (più campi, dropdown, checkbox), conviene elencare i dati da inserire in modo strutturato:
> Apri il sito https://example.com/registratione compila il form con questi dati:
> - Nome: Mario
> - Cognome: Rossi
> - Email: mario.rossi@example.com
> - Paese: Italia (seleziona dal dropdown)
> - Accetta i termini di servizio (spunta il checkbox)
> Poi invia il form e dimmi se la registrazione è andata a buon fine.
### Pattern 3: Navigazione multi-step
Quando il workflow richiede più passaggi, struttura il prompt come una sequenza ordinata:
> Sul sito https://example.com:
> 1. Vai alla pagina di login
> 2. Inserisci username "user@example.com" e password "MyP4ssword"
> 3. Dopo il login, vai alla sezione "Reports"
> 4. Scarica il report più recente
> 5. Dimmi il titolo e la data del report
L'agente seguirà i passi nell'ordine. Se uno dei passi fallisce (ad esempio, credenziali errate), l'agente dovrebbe osservare la pagina risultante e informarti dell'errore.
**Nota sulla sicurezza:** evita di mettere credenziali reali direttamente nel prompt. Se l'agente ha accesso a un file di configurazione o a variabili d'ambiente, fai riferimento a quelli. L'ipotesi qui è che OpenClaw mantenga i log delle sessioni, e le credenziali in chiaro nei log sono un rischio.
### Pattern 4: Estrarre dati strutturati
Quando hai bisogno di dati in formato tabellare o strutturato, dillo esplicitamente:
> Apri https://www.borsaita...istino-a-z.htmle estraimi una tabella con: nome del titolo, ultimo prezzo, variazione percentuale. Limitati ai primi 20 titoli.
> Naviga su https://example.com/products, leggi tutte le schede prodotto nella prima pagina e restituiscimi i dati in formato JSON con campi: nome, prezzo, disponibilità.
La richiesta esplicita del formato di output guida l'agente nella strutturazione della risposta.
### Pattern 5: Screenshot e verifica visiva
Charlotte può catturare screenshot. Utile per verifiche che richiedono un controllo visivo:
> Apri https://miosito.example.come fai uno screenshot. Voglio verificare che il banner promozionale sia visibile correttamente.
L'agente userà `charlotte.screenshot` e ti restituirà l'immagine (l'ipotesi è che OpenClaw supporti la restituzione di immagini dalla shell; se non lo fa, lo screenshot potrebbe essere salvato come file e l'agente ti indicherà il path).
### Quando NON usare Charlotte
Charlotte non è sempre la scelta giusta. Ecco quando il semplice `curl` o il fetch HTTP nativo sono preferibili:
Pagine statiche con contenuto in HTML semplice: un `curl` è più veloce e consuma meno risorse. API REST con endpoint documentati: meglio chiamare l'API direttamente con `curl` o uno script. Ricerche web generiche: l'agente ha strumenti di ricerca web integrati che sono più efficienti per questo scopo.
Charlotte è la scelta giusta quando serve un browser reale: pagine JavaScript-rendered, SPA, form interattivi, pagine dietro cookie consent, contenuti che appaiono solo dopo scroll o click.
### Gestione degli errori nei prompt
I siti web falliscono. È buona pratica anticipare i problemi nel prompt:
> Apri https://example.com/dashboard. Se la pagina mostra un messaggio di errore o di manutenzione, riportamelo senza procedere oltre. Se la pagina si carica correttamente, estrai i dati del widget "Revenue Q1".
> Naviga su https://example.come accetta il banner dei cookie se presente, poi vai alla sezione "Pricing".
Il secondo esempio anticipa un ostacolo comune: i banner di cookie consent che bloccano l'interazione con la pagina sottostante.
---
## Parte 3 — Charlotte nei cron job e nella routine quotidiana
### Come funzionano i cron job in OpenClaw
Prima di vedere come usare Charlotte nei cron job, vale la pena capire come funziona il sistema di scheduling di OpenClaw.
I cron job sono gestiti dal Gateway (non dal modello LLM). Puoi crearli dalla CLI con `openclaw cron add` oppure chiedendo all'agente di farlo per te in chat. I job vengono salvati su disco in `~/.openclaw/cron/` e sopravvivono ai riavvii.
Ogni cron job ha due modalità di esecuzione. La modalità **main** inietta un system event nella sessione principale — utile per promemoria e per task che hanno bisogno del contesto della conversazione in corso. La modalità **isolated** crea una sessione dedicata con contesto pulito — ideale per task automatici che non devono inquinare la chat principale.
Per i job con Charlotte, la scelta quasi obbligata è **isolated**: il browsing di un sito è un task autonomo che non ha bisogno del tuo storico conversazionale e che potrebbe produrre output lungo.
### Anatomia di un cron job con Charlotte
Ecco un esempio completo. Ipotizziamo di voler monitorare ogni mattina alle 8:00 i nuovi documenti di prassi dell'Agenzia delle Entrate:
```bash
openclaw cron add \
--name "Monitor AdE prassi" \
--cron "0 8 * * *" \
--tz "Europe/Rome" \
--session isolated \
--message "Apri la pagina https://www.agenziae...ssi/risoluzionie leggi i documenti con data di oggi o di ieri. Se ce ne sono di nuovi, riportami titolo, numero e data di ciascuno. Se non ce ne sono, rispondi semplicemente 'Nessun nuovo documento.'" \
--announce \
--channel tel.egram \
--to "chat:123456789"
```
Analizziamo le scelte:
Il `--session isolated` garantisce che il job abbia il suo contesto pulito. L'`--announce` con `--channel il whatsapp dei froci` fa sì che il risultato arrivi su il whatsapp dei froci. Il prompt nel `--message` è autocontenuto: contiene l'URL esatto, le istruzioni specifiche, e una clausola per il caso in cui non ci siano novità. Questo è cruciale nei cron job: il prompt deve funzionare senza alcun contesto precedente.
### Regola d'oro per i cron job: prompt autocontenuti
Nella chat interattiva puoi permetterti di essere vago — puoi sempre chiarire nel turno successivo. Nei cron job no. Il prompt è tutto quello che l'agente ha. Deve contenere:
L'URL esatto da visitare. L'azione precisa da compiere sulla pagina. I dati specifici da estrarre. Il formato desiderato per l'output. Una clausola per il caso negativo (nessun dato trovato, errore, sito in manutenzione). Eventuali ostacoli prevedibili (banner cookie, paginazione).
**Prompt cron debole:**
> Controlla le novità sul sito dell'Agenzia delle Entrate.
L'agente non sa quale pagina aprire, cosa cercare, come filtrare per data, cosa fare se non trova nulla.
**Prompt cron efficace:**
> Usa Charlotte per aprire https://www.agenziae...rassi/circolari. Accetta il banner cookie se presente. Leggi la lista dei documenti visibili in prima pagina. Filtra mentalmente quelli con data di oggi (usa la data del sistema per determinare "oggi"). Restituisci per ciascuno: numero, titolo, data. Se nessun documento ha la data di oggi, rispondi: "Nessuna nuova circolare oggi." Se il sito non è raggiungibile, rispondi: "Sito AdE non disponibile."
### Use case 1: Monitoraggio prezzi
```bash
openclaw cron add \
--name "Monitor whisky prices" \
--cron "0 9 * * 1" \
--tz "Europe/Rome" \
--session isolated \
--message "Apri https://www.thewhisk...?q=lagavulin 16con Charlotte. Leggi il prezzo del Lagavulin 16 Year Old. Poi apri https://www.finedram...old-whisky.html e leggi il prezzo lì. Confronta i due prezzi e riportami: prodotto, prezzo su TWE, prezzo su FineDrams, differenza. Se uno dei due siti non è raggiungibile, segnalalo." \
--announce \
--channel tel.egram \
--to "chat:123456789"
```
Ogni lunedì mattina alle 9, l'agente naviga su due siti, estrae i prezzi e li confronta. Il prompt specifica esattamente cosa fare su ciascun sito.
### Use case 2: Verifica stato di un servizio web
```bash
openclaw cron add \
--name "Healthcheck portale clienti" \
--cron "*/30 * * * *" \
--tz "Europe/Rome" \
--session isolated \
--message "Apri https://portale.example.com/logincon Charlotte. Verifica che la pagina si carichi e che il form di login sia visibile (deve esserci un campo email, un campo password e un bottone di login). Rispondi con 'OK: portale funzionante' oppure 'ERRORE: [descrizione del problema]'. Sii conciso, massimo una riga." \
--announce \
--channel tel.egram \
--to "chat:123456789"
```
Ogni 30 minuti, l'agente verifica che un portale sia raggiungibile e che il form di login sia renderizzato correttamente. Il prompt chiede una risposta breve e binaria — fondamentale per job ad alta frequenza che non devono generare rumore.
**Attenzione ai costi:** un cron job ogni 30 minuti che invoca un LLM consuma token. Per healthcheck semplici, uno script bash con `curl` sarebbe più economico. Charlotte ha senso per healthcheck che richiedono un browser reale (pagine SPA, verifica di elementi JavaScript-rendered).
### Use case 3: Aggregazione contenuti da più fonti
```bash
openclaw cron add \
--name "Rassegna stampa fiscale" \
--cron "0 7 * * 1-5" \
--tz "Europe/Rome" \
--session isolated \
--message "Prepara una rassegna stampa fiscale del giorno. Per ciascuno dei seguenti siti, apri la homepage con Charlotte, identifica gli articoli pubblicati oggi (o ieri sera), e riportami titolo e link:
1. https://www.fiscooggi.it- sezione 'Normativa e prassi'
2. https://www.eutekne.info- ultimi articoli in homepage
3. https://www.ilsole24...norme-e-tributi- ultimi articoli
Per ciascun sito: se il banner cookie blocca la pagina, accettalo. Se il sito non è raggiungibile, segnalalo e prosegui con il successivo. Alla fine, presenta i risultati raggruppati per fonte. Se nessun sito ha novità rilevanti, scrivi 'Nessuna novità rilevante oggi.'" \
--announce \
--channel tel.egram \
--to "chat:123456789"
```
Questo è un job complesso. L'agente deve visitare tre siti in sequenza, gestire possibili errori su ciascuno indipendentemente, filtrare per data e aggregare i risultati. Il prompt è lungo ma necessariamente esplicito.
**Ipotesi:** questo job funziona nella misura in cui Charlotte riesce a navigare ciascun sito. Siti con paywall, CAPTCHA o protezioni anti-bot pesanti potrebbero fallire. È consigliabile testare manualmente ogni URL con `mcporter call charlotte.navigate url=... && mcporter call charlotte.observe detail=summary` prima di metterlo in un cron job.
### Use case 4: Compilazione automatica di un form ricorrente
Ipotizziamo un form che va compilato settimanalmente con dati aggiornati:
```bash
openclaw cron add \
--name "Report settimanale presenze" \
--cron "0 17 * * 5" \
--tz "Europe/Rome" \
--session isolated \
--message "Apri https://hr.example.com/timesheetcon Charlotte. Esegui il login con le credenziali nel file /home/openclaw/.config/hr-credentials.env (leggi il file per ottenere username e password). Compila il timesheet della settimana corrente con 8 ore per ogni giorno da lunedì a venerdì. Invia il form. Conferma se l'invio è andato a buon fine o riporta l'errore." \
--announce \
--channel tel.egram \
--to "chat:123456789"
```
**Nota importante sulla sicurezza:** le credenziali sono in un file separato, non nel prompt. L'agente legge il file al momento dell'esecuzione. Questo è un pattern migliore rispetto a metterle nel cron job direttamente, dove finirebbero nei log e nel file `jobs.json`.
### Consigli per il prompting quotidiano in chat
Nella chat interattiva il contesto è più ricco e puoi essere più conversazionale. Ecco alcuni pattern che funzionano bene nel quotidiano.
**Il redirect esplicito a Charlotte:**
Quando il fetch HTTP standard fallisce (perché la pagina è una SPA o ha contenuto JavaScript-rendered), puoi forzare Charlotte:
> Il fetch di quella pagina non ha funzionato, è probabilmente una SPA. Usa Charlotte per aprire la pagina nel browser e leggere il contenuto.
**La richiesta iterativa:**
> Apri https://example.com/search. Cerca "fringe benefit 2025". Fammi un riassunto dei primi 3 risultati. Se qualcuno sembra particolarmente rilevante, apri il link e leggimi il testo completo.
Qui stai dando all'agente autonomia parziale: deve decidere quali risultati sono "particolarmente rilevanti". Questo funziona bene in chat dove puoi correggere il tiro, meno bene nei cron job dove non ci sei.
**Il confronto tra pagine:**
> Apri queste due pagine e confronta i contenuti:
> - https://example.com/pricing(versione corrente)
> - https://example.com/pricing-new(versione proposta)
> Dimmi cosa è cambiato nei piani tariffari.
Charlotte può gestire più tab e fare diff tra stati della pagina, ma il modo più affidabile è navigare su una pagina, raccogliere i dati, poi navigare sull'altra e confrontare.
### Limiti da tenere presenti
Charlotte opera un Chromium headless. Questo significa alcune cose che non puoi fare o che funzionano male.
I siti con CAPTCHA (reCAPTCHA, hCaptcha, Cloudflare Turnstile) bloccheranno Charlotte nella maggior parte dei casi. I siti con protezione anti-bot aggressiva (fingerprinting del browser, rate limiting per IP) possono bloccare o rallentare l'accesso. Il download di file funziona in modo limitato — Charlotte interagisce con la pagina, ma il salvataggio di file scaricati dipende dalla configurazione del browser headless. Le pagine che richiedono autenticazione a due fattori non sono gestibili automaticamente.
Il daemon mcporter con keep-alive mantiene lo stato del browser tra le chiamate, ma non tra i riavvii del daemon. Se il daemon viene riavviato (ad esempio al reboot della VM), la sessione browser riparte da zero: cookie persi, login da rifare.
---
## Riepilogo delle best practice
**In chat interattiva:** sii specifico sull'URL e sull'obiettivo, ma lascia flessibilità sull'esecuzione. Usa parole trigger come "apri", "naviga", "leggi la pagina", "compila il form" per attivare Charlotte. Anticipa gli ostacoli prevedibili (cookie banner, pagine lente).
**Nei cron job:** il prompt deve essere completamente autocontenuto. Specifica URL esatti, azioni precise, formato di output atteso, gestione degli errori e del caso negativo. Testa ogni URL manualmente prima di automatizzarlo. Usa `--session isolated` per non inquinare la sessione principale.
**In generale:** Charlotte è uno strumento potente ma costoso (in token e in tempo di esecuzione). Usala quando un browser reale è necessario, non come sostituto di `curl` o di una ricerca web standard.
