Tutorial PicoClaw: un framework di agenti iper-minimalista per spazio su disco limitato

Se le notizie recenti ci azzeccano, l’AI sta consumando tutta la RAM e la CPU del pianeta, rendendo PicoClaw uno strumento quanto mai tempestivo. Non sorprende che al lancio abbia fatto molto rumore, raccogliendo migliaia di stelle nei primi giorni. L’intero agente AI sta sotto i 10MB e si avvia in meno di un secondo su un processore da 600MHz. 

Quando l’ho scoperto, ho dovuto provarlo di persona per vedere se l’hype fosse meritato. In questo articolo ti accompagno alla scoperta di PicoClaw, mettendo in evidenza tutto ciò che ho trovato. 

Se ti interessa approfondire l’agentic AI, ti consiglio di iniziare con lo skill track AI Agent Fundamentals. 

Che cos’è PicoClaw?

PicoClaw è un assistente AI personale leggero ispirato a Nanobot. È scritto in Go dal team Sipeed e gira su dispositivi edge come Raspberry Pi, schede embedded RISC-V e router basati su MIPS. Questo significa che puoi eseguire PicoClaw con un budget hardware di 10$. 

Funzionalità e capacità chiave di PicoClaw

PicoClaw viene distribuito come singolo binario. Questo lo rende estremamente rapido da configurare perché non ci sono ambienti virtuali Python da impostare o pip da installare. 

Essendo un file binario, puoi eseguirlo su varie architetture. La pagina delle release offre download per diversi sistemi operativi, tra cui Linux, macOS e Windows. 

Per quanto riguarda l’AI, PicoClaw è agnostico rispetto al provider. Supporta OpenAI, Anthropic, DeepSeek e persino Ollama per i modelli locali. È un grande vantaggio per chi vuole passare da un modello all’altro o usare modelli locali per motivi di privacy. 

Puoi imparare a configurare Ollama per i modelli locali nella guida Usare OpenClaw con Ollama. 

PicoClaw ha strumenti integrati che possono: 

• Leggere e scrivere file 
• Eseguire comandi shell sul sistema host 
• Cercare sul web con Brave Search o DuckDuckGo 
• Pianificare job ricorrenti con cron 

Come Nanobot, supporta i soliti noti: WhatsApp, Telegram, Discord, QQ e DingTalk. Più avanti ti mostrerò come configurarlo con Telegram. 

Scopri Nanobot, la alternativa a OpenClaw leggera. Crea un agente AI in Python sicuro e verificabile in meno di 10 minuti con questa guida completa a Nanobot.

Pro e contro di PicoClaw

Immagino ti stia chiedendo quali siano i contro di PicoClaw, visto quanto è veloce e semplice da configurare. Ci arriviamo, ma prima vediamo i pro. 

Primo, il fatto che sia un file binario lo rende facile da impostare praticamente su qualsiasi dispositivo. Sono riuscito a configurarlo sul mio telefono Google Pixel in pochi minuti. 

Secondo, PicoClaw può essere usato con le piattaforme di messaggistica che già utilizzi, rendendo l’interazione semplice senza cambiare app. 

Sul fronte dei contro, PicoClaw è ancora pre-1.0. Essendo uno strumento molto nuovo, potrebbero esserci bug imprevisti o persino modifiche breaking. Facendo ricerca, ho trovato anche numerose truffe crypto che prendono di mira PicoClaw. La documentazione ufficiale afferma che non gestiscono alcuna coin, quindi fai attenzione là fuori. 

Come configurare PicoClaw

Puoi configurare PicoClaw in pochi passaggi. Vediamo come:

Installazione (download del singolo binario)

Per configurare PicoClaw, puoi compilarlo direttamente dal sorgente:

git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
make deps
# Build, no need to install
make build
# Build for multiple platforms
make build-all
# Build for Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
make build-pi-zero
# Build And Install
make install

Tuttavia, preferisco usare Docker perché è molto più veloce: 

# 1. Clone this repo
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
# 2. First run — auto-generates docker/data/config.json then exits
docker compose -f docker/docker-compose.yml --profile gateway up
# The container prints "First-run setup complete." and stops.
# 3. Set your API keys
nano docker/data/config.json   # Set provider API keys, bot tokens, etc.
# 4. Start
docker compose -f docker/docker-compose.yml --profile gateway up -d

Impara le basi della containerizzazione con la nostra guida Docker per Principianti. 

Configurare il tuo provider LLM

Dopo l’installazione, devi configurare il provider LLM che preferisci. Puoi farlo modificando il file docker/data/config.json:

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "gpt4",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "model_list": [
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "your-api-key",
      "request_timeout": 300
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4.6",
      "api_key": "your-anthropic-key"
    }
  ],
  "tools": {
    "web": {
      "brave": {
        "enabled": false,
        "api_key": "YOUR_BRAVE_API_KEY",
        "max_results": 5
      },
      "tavily": {
        "enabled": false,
        "api_key": "YOUR_TAVILY_API_KEY",
        "max_results": 5
      },
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      },
      "perplexity": {
        "enabled": false,
        "api_key": "YOUR_PERPLEXITY_API_KEY",
        "max_results": 5
      },
      "searxng": {
        "enabled": false,
        "base_url": "http://your-searxng-instance:8888",
        "max_results": 5
      }
    }
  }
}

Eseguire il tuo primo agente

Collegare PicoClaw a Telegram richiede solo pochi passaggi.

Ecco come ho impostato tutto per Telegram:

• Apri Telegram e cerca @BotFather 
• Digita /newbot e segui le istruzioni 
• Copia il token che riceverai da BotFather 
• Poi ottieni il tuo ID utente per fare in modo che il bot accetti comandi solo da te. Cerca @userinfobot su Telegram e fai clic su start. Copia l’ID utente.

Quindi aggiorna il file docker/data/config.json per includere il token del bot e il tuo user ID di Telegram. 

Ora vai sul tuo bot Telegram e inizia a interagire con Picoclaw. 

Proviamo qualche prompt. 

Per prima cosa, userò PicoClaw per cercare sul web e restituire il prezzo corrente delle azioni Apple. Come si vede dallo screenshot, ha usato lo strumento di web search DuckDuckGo e ha recuperato il prezzo. 

Ecco un altro prompt in cui chiedo a PicoClaw di abbozzare un post sul blog, salvarlo su disco e leggerlo: 

Ero curioso della sua capacità di eseguire task pianificati, quindi gli ho chiesto di ricordarmi di pubblicare il post tra cinque minuti, e il promemoria è effettivamente arrivato dopo 5 minuti. 

Problemi comuni di PicoClaw e troubleshooting

Durante la configurazione di PicoClaw ho incontrato alcuni problemi. Li cito brevemente nel caso capitino anche a te. 

Nessuna risposta su Telegram

Se non ricevi alcuna risposta su Telegram, il problema potrebbe essere: 

• Il token di Telegram non è corretto. Apri il file di configurazione e ricontrolla 
• L’ID utente from non è impostato, oppure stai accedendo all’agente da un altro account 
• Modello e API key non sono impostati. Apri il file di configurazione e impostali

Controllando i log vedrai qual è il problema esatto: 

docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway

Modello non impostato 

L’errore seguente significa che non hai impostato il modello di default: 

Error: error creating provider: model "" not found in model_list: model "" not found in model_list or providers

Apri il file di configurazione JSON e imposta il nome del modello che vuoi usare, assicurandoti che la relativa API key sia inclusa nel file.

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "gpt4", ---> make sure this is here 
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  }

API key fornita non corretta

Questo è semplice. L’API key indicata per il provider del modello scelto è vuota o errata. Apri il file di configurazione JSON e verifica la chiave.

Le capacità distintive di PicoClaw

Vediamo ora alcune capacità che rendono PicoClaw diverso e al tempo stesso simile ad altri assistenti AI personali. 

Il sistema Heartbeat

PicoClaw ha un file markdown di heartbeat nella sua directory di lavoro, che l’agente legge ogni 30 minuti e su cui agisce seguendo le istruzioni presenti. Picoclaw può anche avviare subagent per gestire il lavoro in parallelo. 

Memoria persistente

PicoClaw ha un file di memoria che salva le informazioni importanti da mantenere tra le sessioni. Memorizza le tue preferenze e le skill abilitate, così quando serve quel contesto può essere recuperato. È fondamentale per non dover ripartire ogni volta da zero in ogni interazione. 

Modalità air-gapped/offline

PicoClaw può anche girare senza accesso a Internet. È importante se vuoi elaborare dati sensibili, soprattutto in settori regolamentati come banking e sanità. Per farlo, dovrai configurare un modello locale tramite Ollama. 

Multi-agente e fallback di modello

Con PicoClaw puoi definire ogni agente perché usi il suo provider LLM. Supporta anche il load balancing, distribuendo le richieste su più modelli. Una volta configurato, PicoClaw ruoterà tra i modelli in modalità round robin.

Integrazione hardware

PicoClaw include strumenti integrati per la comunicazione I2C e SPI. Questo aiuta l’agente a interagire con le periferiche hardware sulle schede supportate. Significa che può interfacciarsi con sensori, display, controller di motori e ogni tipo di dispositivo fisico. 

PicoClaw in azione: casi d’uso reali

Esploriamo ora alcuni casi d’uso di PicoClaw. 

Tra gli usi interessanti che ho trovato online durante la ricerca ci sono: 

• Domotica e monitoraggio con un Raspberry PI di prima generazione 
• Ricerche web automatizzate, ad esempio per inviarti riepiloghi su Telegram ogni mattina 
• Alert e monitoraggio da dispositivi embedded, ad esempio a partire da dati di sensori 

Limitazioni e avvertenze di PicoClaw

Prima di distribuire PicoClaw nella tua rete, ci sono alcune limitazioni importanti da tenere presenti.

Innanzitutto, PicoClaw è sicuro per impostazione predefinita. È limitato alla workspace da cui lavora. Non può quindi accedere a cartelle e file al di fuori di quella directory. 

Puoi modificare questa impostazione nel file di configurazione. 

Alcuni comandi, come rm, sono inoltre limitati per prevenire problemi come l’azzeramento del disco rigido. 

Per esempio, ho provato a chiedergli di eliminare la mia cartella home e le guardrail sono intervenute per impedirlo. 

Essendo software in fase iniziale di sviluppo, PicoClaw presenta problemi di sicurezza di rete non risolti, quindi si raccomanda di non distribuirlo in produzione prima del rilascio della v1.0. 

Se cerchi qualcosa di più maturo, OpenClaw è una buona scelta. Scopri se è adatto al tuo workflow nella nostra guida OpenClaw vs Claude Code. 

Prospettive future

La possibilità di eseguire large language model su dispositivi edge ha guadagnato molta trazione di recente, soprattutto con la creazione di modelli che possono girare su telefoni e dispositivi embedded. Penso che PicoClaw sarà molto utile in ambienti con risorse limitate e in applicazioni dove la sensibilità dei dati è assoluta. Dove la connettività è inaffidabile, non ci saranno alternative se non usare uno strumento come PicoClaw. 

Credo che PicoClaw possa diventare un vero concorrente di Nanobot e OpenClaw quando sarà pronto per la produzione. Scommetterei che sarà lo strumento che permetterà ai dispositivi Internet-of-Things di eseguire workflow agentici. Questo comporta anche rischi seri se i modelli alla base dell’agente allucinano o se una prompt injection li porta a fare cose malevole, come surriscaldare un microonde. 

PicoClaw punterà anche a costruire le funzionalità mancanti presenti in altri agenti, come OpenClaw, come indicato nella loro roadmap. Tra queste: 

• Automazione del browser
• Maggiore scoperta di skill 
• Supporto MCP 

Conclusione

Quando è stato lanciato OpenClaw, c’era parecchio hype sull’acquisto di Mac Mini per eseguirlo, anche se in realtà non era necessario. Un Mac Mini costa centinaia di dollari. 

PicoClaw è stato creato per smentire questa narrativa, permettendo il deployment di agenti potenti con un budget di 10$. A differenza di OpenClaw, PicoClaw adotta un approccio secure-first, limitando l’accesso dell’agente alla sola workspace e disabilitando i comandi che possono fare danni quando il modello sottostante allucina o viene iniettato un prompt malevolo. 

Per saperne di più sul lavoro con strumenti AI, ti consiglio di dare un’occhiata alla nostra guida ai migliori strumenti AI gratuiti. Per competenze di coding AI più ampie, prova il nostro corso AI-Assisted Coding for Developers per sviluppare le abilità che rendono gli assistenti AI partner più affidabili nel tuo workflow di sviluppo. 

Puoi anche scoprire come creare applicazioni AI-powered usando LLM, prompt, chain e agent in LangChain con il nostro corso Developing LLM Applications with LangChain.