picoclaw/docs/it/configuration.md

⚙️ Guida alla Configurazione

Torna al README

⚙️ Configurazione

File di configurazione: ~/.picoclaw/config.json

Variabili d'Ambiente

Puoi sovrascrivere i percorsi predefiniti usando variabili d'ambiente. Questo è utile per installazioni portatili, distribuzioni containerizzate, o per eseguire picoclaw come servizio di sistema. Queste variabili sono indipendenti e controllano percorsi diversi.

Variabile	Descrizione	Percorso Predefinito
PICOCLAW_CONFIG	Sovrascrive il percorso al file di configurazione. Indica direttamente a picoclaw quale config.json caricare, ignorando tutte le altre posizioni.	~/.picoclaw/config.json
PICOCLAW_HOME	Sovrascrive la directory radice per i dati di picoclaw. Modifica la posizione predefinita del workspace e delle altre directory dati.	~/.picoclaw

Esempi:

# Esegui picoclaw usando un file di configurazione specifico
# Il percorso del workspace verrà letto da quel file di configurazione
PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway

# Esegui picoclaw con tutti i dati salvati in /opt/picoclaw
# La configurazione verrà caricata dal percorso predefinito ~/.picoclaw/config.json
# Il workspace verrà creato in /opt/picoclaw/workspace
PICOCLAW_HOME=/opt/picoclaw picoclaw agent

# Usa entrambi per un setup completamente personalizzato
PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway

Struttura del Workspace

PicoClaw salva i dati nel workspace configurato (predefinito: ~/.picoclaw/workspace):

~/.picoclaw/workspace/
├── sessions/          # Sessioni di conversazione e cronologia
├── memory/           # Memoria a lungo termine (MEMORY.md)
├── state/            # Stato persistente (ultimo canale, ecc.)
├── cron/             # Database dei job pianificati
├── skills/           # Skill personalizzate
├── AGENT.md          # Guida al comportamento dell'agent
├── HEARTBEAT.md      # Prompt per task periodici (controllato ogni 30 min)
├── SOUL.md           # Anima dell'agent
└── USER.md           # Preferenze dell'utente

Nota: Le modifiche a AGENT.md, SOUL.md, USER.md e memory/MEMORY.md vengono rilevate automaticamente a runtime tramite il tracciamento della data di modifica (mtime). Non è necessario riavviare il gateway dopo aver modificato questi file — l'agent caricherà il nuovo contenuto alla prossima richiesta.

Sorgenti delle Skill

Per impostazione predefinita, le skill vengono caricate da:

1. ~/.picoclaw/workspace/skills (workspace)
2. ~/.picoclaw/skills (globale)
3. <current-working-directory>/skills (builtin)

Per configurazioni avanzate/di test, puoi sovrascrivere la directory radice delle skill builtin con:

export PICOCLAW_BUILTIN_SKILLS=/path/to/skills

Politica Unificata di Esecuzione dei Comandi

• I comandi slash generici vengono eseguiti tramite un unico percorso in pkg/agent/loop.go via commands.Executor.
• Gli adattatori dei canali non consumano più localmente i comandi generici; inoltrano il testo in entrata al percorso bus/agent. Telegram registra ancora automaticamente i comandi supportati all'avvio.
• Un comando slash sconosciuto (ad esempio /foo) viene passato all'elaborazione LLM come se fosse un messaggio dell'utente.
• Un comando registrato ma non supportato sul canale corrente (ad esempio /show su WhatsApp) restituisce un errore esplicito all'utente e interrompe l'elaborazione.

Allowlist dei Tool per Agent

La dichiarazione dei tool per-agent vive nel frontmatter di AGENT.md, non in config.json.

Se tools è omesso nel frontmatter, l'agent riceve il normale set globale dei tool abilitati. Se tools è presente, PicoClaw registra per quell'agent solo i tool runtime elencati.

---
name: Research Agent
description: Specialista per ricerca web e analisi approfondita.
tools: [read_file, write_file, web_search, web_fetch, message]
skills: [deep-research]
mcpServers: [web-index]
---

Sei l'agent di ricerca.

Note:

• È una allowlist reale, non un suggerimento per l'LLM.
• I nomi dei tool fanno match 1:1 con il nome runtime del tool.
• Se ti serve controllo preciso, usa i nomi runtime effettivi come web_search, web_fetch, spawn, subagent, send_file.
• available_tools nella Agent Discovery riflette il risultato runtime filtrato, mentre tools riflette l'identità dichiarata in AGENT.md.

Discovery Multi-Agent (Automatica)

Quando esiste più di un agent, PicoClaw inietta automaticamente nel system prompt di ogni agent un registry strutturato dei peer. Non serve una chiamata aggiuntiva a un tool list_agents.

Questa discovery serve soprattutto a rendere affidabile la delega tramite spawn con agent_id esplicito.

Ogni entry include:

Campo	Significato
id	ID stabile dell'agent
name	Nome identitario da AGENT.md frontmatter
description	Descrizione identitaria da AGENT.md frontmatter
tools	Tool dichiarati nel frontmatter di AGENT.md
skills	Skill dichiarate nel frontmatter di AGENT.md
mcpServers	Server MCP dichiarati nel frontmatter di AGENT.md
model	Modello dichiarato nel frontmatter di AGENT.md
available_tools	Tool attualmente visibili a quell'agent
channels	Canali instradati verso quell'agent

Dettagli importanti:

• La sezione include anche l'entry dell'agent corrente, quindi c'è self-awareness.
• available_tools è il campo più importante per delegare bene: l'LLM vede i tool reali del peer, non deve indovinarli dalla sola descrizione.
• I campi di identità (name, description, tools, skills, mcpServers, model) arrivano dal frontmatter di AGENT.md.
• config.json resta il layer infrastrutturale: workspace, agent di default, routing e permessi di subagent.
• channels derivano dal routing:
  • l'agent di default espone i canali abilitati
  • gli altri agent espongono i canali che hanno un binding esplicito verso di loro

Forma dell'oggetto iniettato:

{
  "current_agent_id": "main",
  "agents": [
    {
      "id": "main",
      "name": "Main Assistant",
      "description": "Agent generalista per richieste quotidiane.",
      "tools": ["read_file", "write_file", "exec", "spawn"],
      "skills": ["coordination"],
      "mcpServers": ["filesystem"],
      "model": "gpt-4o-mini",
      "available_tools": ["read_file", "write_file", "exec", "spawn"],
      "channels": ["telegram", "discord"]
    },
    {
      "id": "research",
      "name": "Research Agent",
      "description": "Specialista per investigazioni e lavoro web.",
      "tools": ["read_file", "web_search", "web_fetch", "message"],
      "skills": ["deep-research"],
      "mcpServers": ["web-index"],
      "model": "claude-sonnet-4.5",
      "available_tools": ["web_search", "web_fetch", "read_file"],
      "channels": ["telegram"]
    }
  ]
}

In pratica, un agent generalista può vedere che un peer ha ["web_search", "web_fetch"] mentre lui ha solo tool locali, e scegliere di delegare a quel peer in modo esplicito invece di andare a tentativi.

🔒 Sandbox di Sicurezza

PicoClaw esegue in un ambiente sandboxed per impostazione predefinita. L'agent può accedere solo ai file ed eseguire comandi all'interno del workspace configurato.

Configurazione Predefinita

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "restrict_to_workspace": true
    }
  }
}

Opzione	Predefinito	Descrizione
workspace	~/.picoclaw/workspace	Directory di lavoro dell'agent
restrict_to_workspace	true	Limita l'accesso a file/comandi al workspace

Strumenti Protetti

Quando restrict_to_workspace: true, i seguenti strumenti sono in sandbox:

Strumento	Funzione	Restrizione
read_file	Legge file	Solo file all'interno del workspace
write_file	Scrive file	Solo file all'interno del workspace
list_dir	Elenca directory	Solo directory all'interno del workspace
edit_file	Modifica file	Solo file all'interno del workspace
append_file	Aggiunge ai file	Solo file all'interno del workspace
exec	Esegue comandi	I percorsi dei comandi devono essere nel workspace

Protezione Exec Aggiuntiva

Anche con restrict_to_workspace: false, lo strumento exec blocca questi comandi pericolosi:

• rm -rf, del /f, rmdir /s — Cancellazione di massa
• format, mkfs, diskpart — Formattazione del disco
• dd if= — Imaging del disco
• Scrittura su /dev/sd[a-z] — Scritture dirette su disco
• shutdown, reboot, poweroff — Spegnimento del sistema
• Fork bomb :(){ :|:& };:

Controllo Accesso ai File

Chiave di configurazione	Tipo	Predefinito	Descrizione
tools.allow_read_paths	string[]	[]	Percorsi aggiuntivi consentiti per la lettura al di fuori del workspace
tools.allow_write_paths	string[]	[]	Percorsi aggiuntivi consentiti per la scrittura al di fuori del workspace

Sicurezza Exec

Chiave di configurazione	Tipo	Predefinito	Descrizione
tools.exec.allow_remote	bool	false	Consente lo strumento exec da canali remoti (Telegram/Discord ecc.)
tools.exec.enable_deny_patterns	bool	true	Abilita l'intercettazione dei comandi pericolosi
tools.exec.custom_deny_patterns	string[]	[]	Pattern regex personalizzati da bloccare
tools.exec.custom_allow_patterns	string[]	[]	Pattern regex personalizzati da consentire

Nota di sicurezza: La protezione dei symlink è abilitata per impostazione predefinita — tutti i percorsi file vengono risolti tramite filepath.EvalSymlinks prima del confronto con la whitelist, prevenendo attacchi di escape tramite symlink.

Limitazione Nota: Processi Figlio degli Strumenti di Build

Il controllo di sicurezza exec ispeziona solo la riga di comando avviata direttamente da PicoClaw. Non ispeziona ricorsivamente i processi figlio generati da strumenti di sviluppo consentiti come make, go run, cargo, npm run o script di build personalizzati.

Ciò significa che un comando di primo livello può comunque compilare o avviare altri binari dopo aver superato il controllo iniziale. In pratica, tratta gli script di build, i Makefile, gli script di pacchetti e i binari generati come codice eseguibile che richiede lo stesso livello di revisione di un comando shell diretto.

Per ambienti ad alto rischio:

• Esamina gli script di build prima dell'esecuzione.
• Preferisci l'approvazione/revisione manuale per i workflow di compilazione ed esecuzione.
• Esegui PicoClaw in un container o VM se hai bisogno di un isolamento più forte di quello fornito dal controllo integrato.

Esempi di Errore

[ERROR] tool: Tool execution failed
{tool=exec, error=Command blocked by safety guard (path outside working dir)}

[ERROR] tool: Tool execution failed
{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}

Disabilitare le Restrizioni (Rischio di Sicurezza)

Se hai bisogno che l'agent acceda a percorsi al di fuori del workspace:

Metodo 1: File di configurazione

{
  "agents": {
    "defaults": {
      "restrict_to_workspace": false
    }
  }
}

Metodo 2: Variabile d'ambiente

export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false

⚠️ Attenzione: Disabilitare questa restrizione consente all'agent di accedere a qualsiasi percorso sul tuo sistema. Usare con cautela solo in ambienti controllati.

Coerenza dei Confini di Sicurezza

L'impostazione restrict_to_workspace si applica in modo coerente a tutti i percorsi di esecuzione:

Percorso di esecuzione	Confine di sicurezza
Main Agent	restrict_to_workspace ✅
Subagent / Spawn	Eredita la stessa restrizione ✅
Heartbeat tasks	Eredita la stessa restrizione ✅

Tutti i percorsi condividono la stessa restrizione del workspace — non è possibile aggirare il confine di sicurezza tramite subagent o task pianificati.

Heartbeat (Task Periodici)

PicoClaw può eseguire task periodici automaticamente. Crea un file HEARTBEAT.md nel tuo workspace:

# Periodic Tasks

- Check my email for important messages
- Review my calendar for upcoming events
- Check the weather forecast

L'agent leggerà questo file ogni 30 minuti (configurabile) ed eseguirà tutti i task usando gli strumenti disponibili.

Task Asincroni con Spawn

Per task di lunga durata (ricerca web, chiamate API), usa lo strumento spawn per creare un subagent:

# Periodic Tasks