⚙️ 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.

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

Configurazione Streaming

Lo streaming del provider usa un double opt-in ed è disattivato per impostazione predefinita. L'agent prova lo streaming solo quando il canale corrente ha settings.streaming.enabled: true, l'entry del modello attivo ha streaming.enabled: true, e sia il provider sia il canale supportano lo streaming. Se manca una qualsiasi condizione, PicoClaw usa il normale percorso di richiesta non streaming.

Pico WebUI è il primo canale completamente collegato. Pico crea il primo messaggio assistant con il wire message esistente message.create, poi aggiorna lo stesso messaggio con message.update; non viene introdotto alcun nuovo tipo di wire message Pico.

Lascia streaming assente quando non vuoi usare lo streaming. Un blocco streaming omesso significa disattivato; non è necessario scrivere "streaming": {"enabled": false}.

Esempio di attivazione:

{
  "model_list": [
    {
      "model_name": "gpt-5.4",
      "provider": "openai",
      "model": "gpt-5.4",
      "api_keys": ["sk-your-openai-key"],
      "streaming": {
        "enabled": true
      }
    }
  ],
  "channel_list": {
    "pico": {
      "enabled": true,
      "type": "pico",
      "settings": {
        "token": "YOUR_PICO_TOKEN",
        "streaming": {
          "enabled": true
        }
      }
    }
  }
}

Le variabili d'ambiente legacy di Telegram restano compatibili: PICOCLAW_CHANNELS_TELEGRAM_STREAMING_ENABLED, PICOCLAW_CHANNELS_TELEGRAM_STREAMING_THROTTLE_SECONDS e PICOCLAW_CHANNELS_TELEGRAM_STREAMING_MIN_GROWTH_CHARS. Si applicano solo alle settings Telegram e non attivano né modificano settings.streaming di Pico.

Il comportamento in caso di errore è intenzionalmente conservativo: se lo streaming fallisce prima che venga inviato un chunk visibile, PicoClaw riprova una volta tramite il normale percorso Chat(). Se un chunk è già stato mostrato all'utente, PicoClaw non invia una seconda risposta non streaming, evitando output duplicato.

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.
• Le dichiarazioni dei tool in AGENT.md sono usate dal runtime e dai tool, ma non vengono iniettate nel prompt di discovery.

Discovery Multi-Agent (Automatica)

Quando un agent ha peer spawnabili, PicoClaw inietta automaticamente nel suo system prompt 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:

Dettagli importanti:

• La sezione include solo i peer che l'agent corrente può spawnare tramite subagents.allow_agents.
• L'agent corrente e i peer non spawnabili vengono omessi, così il modello non pianifica contro agent non disponibili.
• La discovery è volutamente leggera. Fornisce al modello solo l'identità necessaria per scegliere un peer: id, name, description.
• config.json resta il layer infrastrutturale: workspace, agent di default, routing e permessi di subagent. Questi permessi controllano anche la visibilità nella discovery.
• AGENT.md resta il layer di identità. Il codice runtime e i tool possono comunque usare tools, skills, mcpServers e model quando avviene la delega.

Forma dell'oggetto iniettato:

{
  "agents": [
    {
      "id": "research",
      "name": "Research Agent",
      "description": "Specialista per investigazioni e lavoro web."
    }
  ]
}

In pratica, un agent generalista sceglie un peer in base alla descrizione del suo ruolo, poi chiama spawn con l'agent_id del peer. Il runtime risolve il resto.

🔒 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
    }
  }
}

Strumenti Protetti

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

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

Sicurezza Exec

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:

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