1. Cos'è myclaw?

myclaw è un maggiordomo digitale per casa: un assistente AI che vive su un computer di famiglia, parla attraverso i canali che già usi (terminale, Telegram, in futuro WhatsApp o voce), esegue azioni reali (leggere file, lanciare comandi, consultare il web) ma chiede il permesso prima di fare qualcosa di serio.

L'analogia del maggiordomo è utile. Un buon maggiordomo:

• vive nella tua casa (local-first: gira sul tuo PC, non in cloud);
• ha le chiavi di certe stanze ma non di tutte (sandbox: può toccare il workspace, non /etc né ~/.ssh);
• esegue compiti di routine da solo (cron, notifiche);
• per decisioni importanti chiede conferma (approval gating);
• apre la porta solo a chi riconosce o a chi mostra un invito (DM pairing);
• tiene un registro di tutto ciò che fa (audit log).

Tecnicamente è un processo Python ≥ 3.11 che gira a /opt/myclaw/, composto da quattro strati (gateway, policy, sandbox, workspace/tool). Ogni servizio AI (LLM, STT, TTS, embedding, speaker-ID) viene consumato tramite un'interfaccia astratta — myclaw è provider-agnostic per costruzione. Nel caso specifico dell'ambiente dell'autore l'interfaccia è realizzata da suprastructure, un package sibling preesistente; in un altro ambiente potrebbe essere realizzata da qualunque adapter equivalente.

Obiettivi espliciti

2. Perché non bastano openclaw o zeroclaw

Entrambi sono progetti eccellenti e sono stati la fonte di ispirazione primaria. Entrambi però hanno tare che li rendono non-pronti per l'uso domestico qui sul mio PC:

La decisione: prendere i pattern migliori di entrambi (gateway-first di openclaw, autonomy+pairing+sandbox-a-strati di zeroclaw) e reimplementarli in Python, dove:

1. posso riusare l'implementazione di interfaccia LLM che ho già pronta in casa (nel mio caso suprastructure) invece di riscriverla;
2. myclaw è coerente con gli altri sibling agents dell'ambiente (un solo linguaggio, convenzioni condivise);
3. posso alzare i default di sicurezza per il contesto domestico senza combattere contro convenzioni cloud-native.

3. Idea chiave: i quattro strati

myclaw è un cipolla: l'esterno parla con il mondo, l'interno esegue. Ogni strato fidandosi solo dello strato più interno, e concedendo meno privilegi man mano che si va verso il centro.

Strato 1 — Gateway

Un singolo processo FastAPI che espone HTTP/WebSocket/SSE su 127.0.0.1:42618. Riceve messaggi dai canali, gestisce le sessioni, smista webhook, pianifica cron job. È l'unico punto di contatto con il mondo. Non esegue mai direttamente comandi sensibili.

Strato 2 — Policy

Il filtro di legalità. Dato un evento ("utente X chiede di fare Y"), risponde: permesso, negato o permesso solo dopo approvazione. Applica il livello di autonomia (vedi cap. 6), i rate-limit, i cost-cap (quanto spendere in LLM al giorno), le forbidden paths e lo stato del pairing (cap. 7).

Strato 3 — Sandbox

Quando la policy dice "sì", l'azione non viene comunque eseguita a mano libera. Per i tool che toccano filesystem o shell si entra in bubblewrap (o systemd-run con hardening) con un profilo scelto dal livello di autonomia. Niente subprocess.run diretto, mai. Docker è un'opzione futura per il modo più strict.

Strato 4 — Workspace & Tool

Dentro la sandbox, il tool fa il suo lavoro: leggere un file dal workspace (/opt/myclaw/workspace/), chiamare un LLM via registry.get(LLMProvider) di suprastructure, scrivere una riga nell'audit log. Il workspace è la "casa" dell'agente: ci vivono i suoi file markdown di personalità e memoria (cap. 8).

4. Il flusso di una richiesta

Seguiamo un esempio concreto. Sei in giardino, scrivi da Telegram: "dimmi cosa c'è nel log di stasera".

5. L'interfaccia LLM, il pattern provider-agnostic

myclaw non parla mai direttamente con Claude, OpenAI, Ollama o qualunque altro fornitore di modelli linguistici. Parla con un'interfaccia astratta (tipicamente un typing.Protocol) che il registro risolve a runtime in un'implementazione concreta. Lo stesso vale per STT, TTS, embedding, speaker ID. È il pattern che rende myclaw provider-agnostic: chi scrive myclaw non deve sapere quale modello girerà davvero, e chi amministra l'ambiente può cambiarlo con una riga di configurazione.

Nel diagramma che segue, myclaw è un consumer tra i possibili altri: un assistente domotico per voce e controllo casa, ulteriori bot specializzati su domini ristretti. Tutti condividono la stessa astrazione. Nessuno riscrive il layer AI: lo usa.

Il vantaggio concreto: un nuovo modello (es. Claude 4.7 quando sarà disponibile) si configura una volta sola nell'implementazione dell'interfaccia e tutti i consumer lo ereditano simultaneamente — myclaw compreso. Nessun codice da rifare, nessun deploy da coordinare.

6. I tre livelli di autonomia

Concetto ripreso e adattato da zeroclaw. Ogni sessione gira a un livello di autonomia dichiarato. Il livello determina quanto myclaw può fare prima di dover chiedere conferma.

Il livello può essere alzato temporaneamente con un comando esplicito (myclaw session --level full --for 10m), loggato e a scadenza automatica.

7. Il DM pairing

Un canale come Telegram è inerentemente multi-utente: chiunque conosca l'handle del bot può scrivergli. Il pairing è il meccanismo che distingue un familiare da un estraneo.

8. Il workspace: file markdown invece di codice

La "personalità" di myclaw non è in un file Python. È nel workspace/, in cinque file markdown che Roberto può editare quando vuole senza restart. L'idea viene da openclaw/zeroclaw ed è azzeccata: la configurazione comportamentale è testo leggibile, non una struttura dati sepolta.

Questi file sono iniettati nel prompt di sistema a ogni chiamata LLM (con opportuno caching per non consumare token). Editarli è il modo primario di "riprogrammare" myclaw.

L'audit log vive in workspace/.audit/ come JSONL append-only: una riga per ogni tool call, con timestamp, sender, azione, esito, costo stimato.

9. Struttura del repository

10. Cosa NON è myclaw

• Non è un framework generalista. openclaw punta a essere piattaforma; myclaw è un agente per una casa. Se serve un altro agente con regole diverse, se ne fa un'altra istanza, non si astrae.
• Non è un hub di servizi AI. I servizi AI stanno dietro un'interfaccia astratta, fornita da un adapter esterno (nel mio caso suprastructure). Se manca un servizio, lo si aggiunge là, non qui.
• Non supporta 20+ canali al day one. Si parte con 2 (CLI + Telegram). Signal, WhatsApp, voce arrivano quando servono davvero.
• Non è un cloud agent. Gira a casa. Accesso remoto solo via tunnel esplicito (Tailscale/Cloudflare), opt-in.
• Non è un sostituto di un sistema di domotica. Per il controllo vocale e la domotica ci sarà un assistente domotico dedicato (tipicamente già presente: nel mio ambiente lo è). myclaw può chiedergli, non duplicarlo.
• Non è un framework agentico generico (langchain, llamaindex, crewai, ...). Quelle librerie possono essere usate dentro un Tool, mai come sostituto dell'architettura.
• Non è un IDE né un dev assistant. Non scrive codice in altri progetti per conto dell'utente: al massimo ne analizza con tool read-only. Per lavorare sul codice esiste già Claude Code.

11. Roadmap & approfondimenti

La roadmap è volutamente piccola. Passo uno alla volta, con il documento di microprogettazione che precede il codice.

Continua a leggere

myclaw — Architettura: Introduzione v1.0 — 2026-04-21
Ispirato a openclaw e zeroclaw, costruito sopra suprastructure.