Usare OpenClaw con Ollama: crea un data analyst locale

Perché eseguire OpenClaw con Ollama?

Eseguire OpenClaw con un modello Ollama locale trasforma il tuo sistema in un ambiente IA autosufficiente. Invece di inviare prompt e dati a API esterne, l'intero workflow, incluso ragionamento, accesso ai file e generazione di artefatti, gira sulla tua macchina.

Questa impostazione offre diversi vantaggi pratici:

• Privacy by design: tutti i dataset, i documenti e gli output intermedi restano on-device. Nulla viene trasmesso a servizi esterni.
• Piena trasparenza e controllo: ogni passaggio è ispezionabile, dallo slash command inviato a OpenClaw ai file generati e al trace di esecuzione.
• Operatività offline: una volta scaricato il modello tramite Ollama, il sistema funziona senza accesso a internet.
• Esecuzione in stile agent: una singola richiesta utente può avviare un workflow multi-step invece di una sola risposta testuale.

Questo tutorial si concentra sulla costruzione di un'architettura agent locale, dove OpenClaw funge da motore di esecuzione e Ollama fornisce il livello di ragionamento.

Tutorial OpenClaw + Ollama: crea un data analyst locale

mIn questa sezione costruiremo un'app Local Data Analyst che gira interamente sulla tua macchina usando OpenClaw e un modello locale di Ollama. A livello alto, il sistema svolge tre compiti principali:

• Accettare un dataset CSV dall'utente
• Facoltativamente ingerire documenti di contesto di supporto (PDF, TXT o Markdown)
• Eseguire un workflow di analisi multi-step per generare insight e visualizzazioni

Il sistema produce tre artefatti in output:

• trend_chart.png
• analysis_report.md
• tool_trace.json

Dietro le quinte, il workflow è coordinato da tre componenti:

• Interfaccia web(web_assistant.py): questo file Python gestisce gli upload, crea una cartella di esecuzione e invia uno slash command a OpenClaw.
• Agente OpenClaw: l'agente OpenClaw carica la skill dello spazio di lavoro, esegue comandi locali tramite tool e usa LLM locali ospitati tramite Ollama per ragionamento e sintesi.
• Motore di analisi (main.py): questo file legge il dataset, deduce le colonne rilevanti, genera grafici e insight e scrive tutti gli output su disco.

Una volta completato il workflow, l'interfaccia web mostra in anteprima gli artefatti generati, permettendo all'utente di visualizzare risultati e trace di esecuzione.

Passo 1: Installa OpenClaw

Prima di costruire il workflow Local Data Analyst, ci serve l'OpenClaw Gateway in esecuzione sulla tua macchina. Pensa a OpenClaw come al livello di esecuzione in questo progetto: riceve le richieste dalla web UI, carica la skill dello spazio di lavoro, esegue strumenti locali (come comandi shell e script Python) e coordina l'intero workflow end-to-end.

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

Questo comando installa la CLI di OpenClaw, esegue la procedura guidata di onboarding per configurare l'ambiente locale e imposta il demone del gateway così da poterlo avviare e arrestare facilmente. Anche se per questa demo eseguiremo il gateway in foreground, installare il demone garantisce un setup standard e facilita la risoluzione dei problemi.

Ora verifichiamo che tutto funzioni:

openclaw doctor
openclaw gateway status

Il OpenClaw doctor segnala che OpenClaw è installato correttamente. OpenClaw gateway status indica se il gateway è attualmente in esecuzione. A questo punto potrebbe dire "not running", ma va bene. L'importante è che il comando funzioni e l'installazione sia riconosciuta.

Se vuoi una guida dettagliata su ogni opzione di onboarding (canali, auth, skill, sicurezza del gateway), puoi consultare il tutorial OpenClaw per una configurazione completa passo passo.

Passo 2: Installa Ollama

Successivamente configureremo Ollama, che fungerà da backend LLM locale per questo progetto. OpenClaw continuerà a orchestrare il workflow, ma quando avrà bisogno dell'intelligenza del modello per sintesi o ragionamento, chiamerà gli LLM tramite Ollama. 

Esegui i seguenti comandi:

brew install ollama
ollama serve
ollama pull qwen3:8b

Questi comandi installano il runtime di Ollama, avviano il server del modello locale con cui comunicherà OpenClaw e scaricano il modello qwen3:8b. Usiamo qwen3:8b perché offre un buon equilibrio tra prestazioni e qualità sulla maggior parte dei laptop, ma puoi scegliere un modello diverso in base alle risorse del tuo sistema. Puoi anche fare riferimento a questa guida di Ollama per il setup. 

Passo 3: Configura OpenClaw

Ora dobbiamo configurare OpenClaw per usare l'istanza locale di Ollama. In questo modo tutto il ragionamento, la sintesi e l'analisi avvengono interamente sulla tua macchina senza chiamate API esterne.

Crea una directory di configurazione locale:

mkdir -p .openclaw-local

Poi crea il file:

.openclaw-local/openclaw.json

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://127.0.0.1:11434/v1",
        "apiKey": "ollama-local",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3:8b",
            "name": "qwen3:8b",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 131072,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "ollama/qwen3:8b" }
    }
  },
  "tools": {
    "web": {
      "search": { "enabled": false },
      "fetch": { "enabled": true }
    }
  }
}

Questa configurazione definisce tre componenti chiave:

• baseUrl punta all'endpoint API locale esposto da ollama serve, mentre l'impostazione api: openai-completions abilita la comunicazione compatibile con OpenAI. La registrazione del modello qwen3:8b specifica le sue capacità, incluso un ampio contesto a 131K per gestire dataset di grandi dimensioni e un limite di token per risposte controllate. Poiché il modello gira in locale, tutti i valori di costo sono impostati a zero.
• La sezione agent defaults controlla quale modello usano gli agent di OpenClaw per il ragionamento. Impostando il modello primario su ollama/qwen3:8b, ogni task dell'agente, come interpretare i prompt, generare sintesi o ragionare sui dati, viene instradato automaticamente al modello locale di Ollama senza richiedere chiamate API esterne.
• La configurazione dei tool gestisce funzionalità esterne come la ricerca web, disabilitata per garantire la privacy ed evitare richieste in uscita. Il tool fetch resta abilitato per un recupero risorse limitato quando necessario. 

Insieme, queste impostazioni garantiscono che l'intero workflow giri privatamente sulla tua macchina, con OpenClaw a gestire l'orchestrazione e Ollama a fornire l'intelligenza locale.

Passo 4: Definisci la skill dello spazio di lavoro

In questo passaggio definiamo la skill dello spazio di lavoro che indica a OpenClaw come eseguire il nostro workflow. Invece di affidarsi al modello per pianificare l'uso dei tool, usiamo la modalità di dispatch dei comandi, che consente a uno slash command di attivare direttamente un comando di esecuzione locale, rendendo il workflow più veloce e totalmente locale.

Creiamo il seguente file SKILL.md nel tuo workspace:

---
name: local-data-analyst
description: Local Data Analyst: analyze private local data with Ollama, generate chart/report, and keep all data on-device.
user-invocable: true
command-dispatch: tool
command-tool: exec
command-arg-mode: raw
---
Invoke as /local-data-analyst <raw command>.
This skill bypasses model planning and dispatches raw command text directly to the exec tool.
Use this exact command template in this workspace:
python3 /……/main.py --docs-dir <context_dir> --data-file <data_file> --output-dir <output_dir> --prompt "<prompt>" --use-ollama --model qwen3:8b
Expected outputs under <output_dir>:
- trend_chart.png
- analysis_report.md
- tool_trace.json

Questa configurazione della skill controlla come OpenClaw esegue l'analisi:

• Il front matter (un blocco di metadati strutturati all'inizio del file) definisce una skill invocabile dall'utente chiamata local-data-analyst, disponibile come slash command /local-data-analyst.
• Uno slash command è il modo di OpenClaw per attivare azioni strutturate dalla chat o dalla UI.
• L'impostazione command-dispatch: tool abilita la modalità di dispatch, in cui OpenClaw inoltra direttamente il comando a un tool invece di chiedere al modello cosa fare.
• Con command-arg-mode: raw, l'intera stringa di comando viene passata inalterata al tool exec, garantendo un'esecuzione prevedibile.
• Il comando esegue lo script locale main.py, che:
• Carica il dataset e gli eventuali documenti di contesto
• Usa Ollama (qwen3:8b) per ragionamento e sintesi
• Genera tre artefatti, tra cui un grafico, un report markdown e un trace di esecuzione degli strumenti

Così, OpenClaw gestisce orchestrazione ed esecuzione, mentre Ollama fornisce il ragionamento locale. Nel prossimo passo collegheremo questa skill a un'interfaccia web in modo che gli utenti possano caricare i dati e avviare l'analisi con una sola azione.

Passo 5: Crea un'interfaccia web

A questo punto abbiamo già due componenti fondamentali: una skill OpenClaw nello spazio di lavoro e un backend di modello locale (Ollama) che fornisce il ragionamento. Ora ci serve un'interfaccia leggera che ti permetta di caricare file e avviare le esecuzioni senza toccare il terminale ogni volta.

Il file web_assistant.py funge da sottile server frontend che:

• Accetta gli upload dei file,
• Crea una cartella di esecuzione isolata per ogni run,
• Costruisce uno slash command OpenClaw che punta ai file su disco,
• Chiama l'agente OpenClaw in locale,
• Attende gli output,
• Ritorna artefatti pronti per l'anteprima nel browser.

La scelta progettuale chiave è che il server web non esegue mai direttamente la logica di analisi. Delega tutto a OpenClaw, così la UI resta semplice. 

Passo 5.1: Costruire lo slash command

L'obiettivo qui è produrre una singola stringa che OpenClaw possa ricevere come messaggio in chat, tipo: /local-data-analyst python3 ... --data-file ... --output-dir …

def build_slash_command(
    data_path: Path,
    docs_dir: Path,
    output_dir: Path,
    prompt: str,
    model: str,
    x_col: str,
    y_col: str,
) -> str:
    args = [
        "python3",
        str(BASE_DIR / "src" / "main.py"),
        "--docs-dir", str(docs_dir),
        "--data-file", str(data_path),
        "--output-dir", str(output_dir),
        "--prompt", prompt,
        "--use-ollama",
        "--model", model,
    ]
    if x_col:
        args.extend(["--x-column", x_col])
    if y_col:
        args.extend(["--y-column", y_col])
    raw = " ".join(shlex.quote(a) for a in args)
    return f"/local-data-analyst {raw}"

La funzione build_slash_command() prepara l'istruzione esatta che verrà inviata a OpenClaw. Invece di eseguire direttamente l'analisi, l'app web costruisce uno slash command strutturato che OpenClaw può instradare alla skill corretta del workspace. Questa funzione svolge quattro compiti chiave:

• La lista args definisce la chiamata CLI a src/main.py. È lo stesso comando che potresti eseguire manualmente dal terminale.
• Le opzioni --x-column e --y-column vengono aggiunte solo se fornite. Se mancano, lo script di analisi può dedurre automaticamente le colonne dal dataset.
• La chiamata shlex.quote() esegue l'escape di tutti gli argomenti, incluso il prompt dell'utente. È fondamentale per gestire spazi e caratteri speciali e previene rischi di command injection quando si passa input utente a un comando shell.

La funzione restituisce una stringa che inizia con: /local-data-analyst. Questo prefisso corrisponde al nome della skill definita in SKILL.md. Quando OpenClaw riceve questo slash command, instrada immediatamente la richiesta alla skill local-data-analyst, che poi esegue il comando tramite il tool exec.

Passo 5.2: Esecuzione OpenClaw 

Ora che abbiamo lo slash command, lo inviamo a OpenClaw usando il runner dell'agente CLI. Qui è dove l'app web consegna l'esecuzione.

slash_message = build_slash_command(
    data_path=data_path,
    docs_dir=docs_dir,
    output_dir=output_dir,
    prompt=prompt,
    model=model,
    x_col=x_col,
    y_col=y_col,
)
agent_cmd = [
    "openclaw", "agent",
    "--local",
    "--session-id", f"stealth-web-{run_id}",
    "--message", slash_message,
    "--timeout", "120",
]
proc = subprocess.run(agent_cmd, capture_output=True, 
                     text=True, env=openclaw_env())

L'invocazione dell'agente OpenClaw è il punto di handoff in cui l'app web smette di lavorare e chiede invece a OpenClaw di eseguire il workflow end-to-end. 

• L'uso di --local assicura che l'esecuzione resti sulla tua macchina e che l'agente elabori la richiesta tramite il tuo gateway locale e il modello basato su Ollama, anziché un servizio ospitato.
• Il flag --session-id stealth-web-{run_id} assegna a ogni run un proprio namespace di sessione isolato, evitando contaminazioni di stato tra run e semplificando il debug di una specifica esecuzione. 
• L'argomento --message passa lo slash command esattamente come se un utente lo avesse digitato in chat; OpenClaw lo riceve, lo instrada alla skill /local-data-analyst ed esegue il comando sottostante tramite il tool exec. 
• Infine, --timeout 120 funge da valvola di sicurezza per evitare che la UI resti bloccata se l'analisi si ferma, e env=openclaw_env() forza il subprocess a usare la configurazione locale del progetto e la directory di stato di OpenClaw, così da puntare in modo coerente al setup di Ollama previsto.

Nel prossimo passo caricheremo gli artefatti generati, inclusi un grafico, un report e il tool trace, e renderemo anteprime leggere nel browser.

Passo 5.3: Configurazione del server

Infine, web_assistant.py esegue un piccolo server HTTP locale per interagire via browser.

 def main() -> int:
    host = "127.0.0.1"
    port = 8765
    server = ThreadingHTTPServer((host, port), Handler)
    print(f"Local Data Analyst web UI: http://{host}:{port}")
    print("Press Ctrl+C to stop.")
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        pass
    return 0

Questo mantiene la distribuzione semplice:

• ThreadingHTTPServer consente più richieste senza bloccare l'intera app.
• Tutto il "lavoro vero" avviene nel Handler della richiesta, che riceve gli upload, crea le cartelle di esecuzione, attiva OpenClaw e restituisce le anteprime.

Nota: l'implementazione completa di web_assistant.py è disponibile nella repo GitHub del progetto.

Passo 6: Costruisci il motore di analisi locale

A questo punto, OpenClaw può già eseguire il workflow tramite la skill del workspace e la web UI può avviare le esecuzioni tramite uno slash command. Il pezzo rimanente è il motore di analisi che prende i file caricati, esegue i passaggi del workflow e produce gli artefatti.

Il file main.py in questa repo si concentra su due funzioni che definiscono il cuore della pipeline, cioè il caricamento dei dati tabulari e la chiamata a Ollama per il ragionamento locale. 

Passo 6.1: Caricare dati tabulari 

Questo helper supporta più formati di input mantenendo coerente il workflow.

def load_tabular_data(data_path: Path, events: List[SkillEvent]) -> pd.DataFrame:
    ext = data_path.suffix.lower()
    if ext == ".csv":
        df = pd.read_csv(data_path)
    elif ext in {".tsv", ".tab"}:
        df = pd.read_csv(data_path, sep="\t")
    elif ext in {".json", ".jsonl"}:
        try:
            df = pd.read_json(data_path)
        except ValueError:
            df = pd.read_json(data_path, lines=True)
    elif ext in {".xlsx", ".xls"}:
        df = pd.read_excel(data_path)
    else:
        raise ValueError(f"Unsupported data file...")
    log_event(events, "fs", "read", f"Loaded data file: {data_path.name}")
    return df

La funzione load_tabular_data() rileva il tipo di file usando data_path.suffix e lo indirizza al loader pandas corretto. I file CSV e TSV sono gestiti con read_csv(), dove i file TSV/tab impostano semplicemente il delimitatore su \t. Gli input JSON sono gestiti con read_json() e, se pandas solleva un ValueError, si ripiega su lines=True per i JSONL. Il supporto per Excel è aggiunto tramite read_excel() così gli utenti possono caricare file .xlsx senza preprocessing.

Infine, la chiamata a log_event() registra una voce di trace strutturata che la pipeline potrà poi serializzare in tool_trace.json. 

Passo 6.2: Integrazione con Ollama 

Dato che questa demo non si affida a un SDK, chiama direttamente l'API HTTP locale di Ollama.

def ollama_generate(model: str, prompt: str) -> str:
    url = "http://localhost:11434/api/generate"
    payload = json.dumps({
        "model": model, 
        "prompt": prompt, 
        "stream": False
    }).encode("utf-8")
    req = request.Request(url, data=payload, 
                         headers={"Content-Type": "application/json"})    
    with request.urlopen(req, timeout=45) as resp:
        body = json.loads(resp.read().decode("utf-8"))
    return str(body.get("response", "")).strip()

La funzione ollama_generate() invia un payload JSON all'endpoint /api/generate di Ollama su localhost. Il payload specifica il nome del modello (ad esempio, qwen3:8b), il prompt finale e disabilita lo streaming in modo che la funzione ritorni una singola risposta completa.

Usare urllib.request mantiene questo wrapper leggero e portabile, e il guardrail timeout=45 evita che il workflow resti appeso all'infinito se il modello è lento o il server non risponde. Infine, la funzione estrae l'output del modello dal campo response e restituisce testo pulito, che verrà poi usato per scrivere il file analysis_report.md.

Passo 7: Crea il server web

Ecco un piccolo script di lancio per avviare la web UI locale che accetta upload e avvia run di OpenClaw dietro le quinte.

set -euo pipefail
ROOT="$(cd "$(dirname "$0")" && pwd)"
cd "$ROOT/.."
python3 ../web_assistant.py

Questo script fa tre cose:

• set -euo pipefail fa fallire lo script in modo rapido: si ferma in caso di errori, tratta le variabili non impostate come errori ed evita failure silenziosi nelle pipeline.
• ROOT=... risolve la directory in cui vive lo script, così funziona anche se lo esegui da altrove.
• cd "$ROOT/.." entra nella root del progetto attesa e poi avvia web_assistant.py, che ospita la UI e gestisce l'intera pipeline.

Una volta in esecuzione, la UI del browser diventa la porta d'ingresso della demo.

Passo 8: Avvia il sistema

Per l'ultimo passaggio, eseguiamo il sistema con una configurazione a due processi. Il gateway OpenClaw gestisce tutta l'esecuzione dei task, mentre l'interfaccia web funge da livello utente per inviare richieste e visualizzare gli output generati.

Terminale 1:  Gateway

Prima di avviare l'interfaccia, avviamo il gateway OpenClaw. Questo processo funge da livello di esecuzione del sistema, gestendo le richieste dell'agente, caricando la skill del workspace, invocando strumenti locali e indirizzando le chiamate di ragionamento al modello Ollama.

export OPENCLAW_CONFIG_PATH="$PWD/.openclaw-local/openclaw.json"
openclaw gateway --force

In questo terminale, OPENCLAW_CONFIG_PATH indirizza OpenClaw alla config locale del progetto, dove abbiamo fissato il modello predefinito su ollama/qwen3:8b e disabilitato la ricerca web per privacy.  Poi, openclaw gateway --force avvia il gateway anche se OpenClaw pensa che qualcosa sia già in esecuzione o parzialmente configurato. 

Quando il gateway è operativo, è pronto ad accettare messaggi agent locali (incluso il nostro slash command /local-data-analyst).

Terminale 2: Web UI

Una volta che il gateway è in esecuzione, avviamo l'interfaccia web, che raccoglie gli input dell'utente, invia ogni richiesta all'agente OpenClaw locale e mostra i grafici, i report e i trace di esecuzione generati.

./local_data_analyst/run_web.sh

Poi apri:

http://127.0.0.1:8765

Il server web gira su 127.0.0.1, quindi è accessibile solo dalla tua macchina. Quando clicchi Run Analysis, la UI scrive una cartella di esecuzione, costruisce lo slash command, invoca openclaw agent --local e poi interroga il disco per i file di output così da mostrare in anteprima:

• trend_chart.png
• analysis_report.md
• tool_trace.json

L'output finale apparirà più o meno così. Puoi testare questa demo usando alcuni file di esempio.

Conclusione

In questo tutorial abbiamo creato un'app IA local-first in cui una semplice interfaccia web avvia un intero workflow agent alimentato da OpenClaw e da un modello Ollama locale. Invece di chiamare API esterne, il sistema mantiene l'intero ciclo sulla tua macchina.

OpenClaw gestisce orchestrazione ed esecuzione degli strumenti, mentre Ollama fornisce il livello di intelligenza locale. Il risultato è un workflow in stile agent in cui una singola richiesta produce artefatti strutturati come visualizzazioni, report e audit trail.

Da qui, puoi estendere il progetto in varie direzioni. Puoi aggiungere nuove skill di workspace per workflow diversi, integrare ulteriori strumenti locali (ad esempio query a database o ricerca documenti) o collegare OpenClaw a canali di messaggistica come Slack o WhatsApp per un accesso remoto sicuro. 

Puoi anche sperimentare modelli Ollama diversi per bilanciare prestazioni e qualità in base all'hardware.

Per approfondire l'uso dell'IA nei tuoi workflow, ti consiglio di dare un'occhiata al corso AI-Assisted Coding for Developers. Ti suggerisco anche di consultare la nostra guida a Moltbook.