⚙️ Guide de Configuration

Retour au README

⚙️ Configuration

Fichier de configuration : ~/.picoclaw/config.json

Variables d'Environnement

Vous pouvez remplacer les chemins par défaut à l'aide de variables d'environnement. Ceci est utile pour les installations portables, les déploiements conteneurisés ou l'exécution de PicoClaw en tant que service système. Ces variables sont indépendantes et contrôlent des chemins différents.

Exemples :

# Run picoclaw using a specific config file
# The workspace path will be read from within that config file
PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway

# Run picoclaw with all its data stored in /opt/picoclaw
# Config will be loaded from the default ~/.picoclaw/config.json
# Workspace will be created at /opt/picoclaw/workspace
PICOCLAW_HOME=/opt/picoclaw picoclaw agent

# Use both for a fully customized setup
PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway

Niveau de Log du Gateway

gateway.log_level contrôle la verbosité des logs du Gateway, configurable dans config.json :

{
  "gateway": {
    "log_level": "warn"
  }
}

La valeur par défaut est warn. Valeurs supportées : debug, info, warn, error, fatal.

Peut également être surchargé via la variable d'environnement : PICOCLAW_LOG_LEVEL=info

Structure du Workspace

PicoClaw stocke les données dans votre workspace configuré (par défaut : ~/.picoclaw/workspace) :

~/.picoclaw/workspace/
├── sessions/          # Sessions de conversation et historique
├── memory/           # Mémoire à long terme (MEMORY.md)
├── state/            # État persistant (dernier canal, etc.)
├── cron/             # Base de données des tâches planifiées
├── skills/           # Compétences personnalisées
├── AGENT.md          # Guide de comportement de l'agent
├── HEARTBEAT.md      # Invites de tâches périodiques (vérifiées toutes les 30 min)
├── SOUL.md           # Âme de l'agent
└── USER.md           # Préférences utilisateur

Remarque : Les modifications apportées à AGENT.md, SOUL.md, USER.md et memory/MEMORY.md sont détectées automatiquement au moment de l'exécution via le suivi de la date de modification (mtime). Il n'est pas nécessaire de redémarrer le gateway après avoir modifié ces fichiers — l'agent charge le nouveau contenu à la prochaine requête.

Politique de contexte de requête

turn_profile est une politique facultative sous agents.defaults.turn_profile pour contrôler le contexte chargé par chaque nouveau tour : historique, prompt système, prompts de skills et outils autorisés. Sans cette configuration, ou avec "enabled": false, PicoClaw garde son comportement normal. Avec "enabled": true, la politique ci-dessous s'applique à chaque nouveau tour.

Tous les blocs utilisent les mêmes valeurs de mode :

Blocs disponibles :

Quand system_prompt.mode vaut off, que des outils restent visibles et qu'aucun prompt système externe n'est fourni, PicoClaw réutilise sa règle existante d'utilisation des outils comme prompt minimal de secours. Si tools.mode vaut off, ce prompt de secours n'est pas ajouté.

Exemple de contexte propre avec outils web :

{
  "agents": {
    "defaults": {
      "turn_profile": {
        "enabled": true,
        "history": { "mode": "off" },
        "system_prompt": { "mode": "off" },
        "skills": { "mode": "off" },
        "tools": {
          "mode": "custom",
          "allow": ["web_search", "web_fetch"]
        }
      }
    }
  }
}

Sources de Compétences

Par défaut, les compétences sont chargées depuis :

1. ~/.picoclaw/workspace/skills (workspace)
2. ~/.picoclaw/skills (global)
3. <chemin-intégré-à-la-compilation>/skills (intégré)

Pour les configurations avancées/de test, vous pouvez remplacer la racine des compétences builtin avec :

export PICOCLAW_BUILTIN_SKILLS=/path/to/skills

Utiliser les Commandes Depuis les Canaux de Chat

Une fois les compétences installées, vous pouvez aussi les inspecter et les activer directement depuis un canal de chat :

• /list skills affiche les noms des compétences installées visibles pour l'agent courant.
• /use <skill> <message> force une compétence pour une seule requête.
• /use <skill> prépare cette compétence pour votre prochain message dans la meme conversation.
• /use clear annule une surcharge de compétence en attente creee via /use <skill>.
• /btw <question> pose une question annexe immediate sans modifier l'historique courant de la session. /btw est traite comme une requete directe sans outils et n'entre pas dans le flux normal d'execution des outils.

Exemples :

/list skills
/use git explique comment squash les 3 derniers commits
/btw rappelle-moi ce qu'on a deja decide pour le plan de deploiement
/use italiapersonalfinance
dammi le ultime news

Politique Unifiée d'Exécution des Commandes

• Les commandes slash génériques sont exécutées via un chemin unique dans pkg/agent/loop.go via commands.Executor.
• Les adaptateurs de canaux ne consomment plus les commandes génériques localement ; ils transmettent le texte entrant au chemin bus/agent. Telegram enregistre toujours automatiquement au démarrage les commandes prises en charge, comme /start, /help, /show, /list, /use et /btw.
• Une commande slash inconnue (par exemple /foo) passe au traitement LLM normal.
• Une commande enregistrée mais non prise en charge sur le canal actuel (par exemple /show sur WhatsApp) renvoie une erreur explicite à l'utilisateur et arrête le traitement ultérieur.

🔒 Sandbox de Sécurité

PicoClaw s'exécute dans un environnement sandboxé par défaut. L'agent ne peut accéder aux fichiers et exécuter des commandes que dans le workspace configuré.

Configuration par Défaut

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

Outils Protégés

Lorsque restrict_to_workspace: true, les outils suivants sont sandboxés :

Protection Exec Supplémentaire

Même avec restrict_to_workspace: false, l'outil exec bloque ces commandes dangereuses :

• rm -rf, del /f, rmdir /s — Suppression en masse
• format, mkfs, diskpart — Formatage de disque
• dd if= — Imagerie de disque
• Écriture vers /dev/sd[a-z] — Écritures directes sur disque
• shutdown, reboot, poweroff — Arrêt du système
• Fork bomb :(){ :|:& };:

Contrôle d'Accès aux Fichiers

Sécurité Exec

Note de sécurité : La protection Symlink est activée par défaut — tous les chemins de fichiers sont résolus via filepath.EvalSymlinks avant la correspondance avec la liste blanche, empêchant les attaques d'évasion par symlink.

Limitation Connue : Processus Enfants des Outils de Build

Le garde de sécurité exec n'inspecte que la ligne de commande lancée directement par PicoClaw. Il n'inspecte pas récursivement les processus enfants générés par les outils de développement autorisés tels que make, go run, cargo, npm run ou les scripts de build personnalisés.

Cela signifie qu'une commande de niveau supérieur peut toujours compiler ou lancer d'autres binaires après avoir passé la vérification initiale du garde. En pratique, traitez les scripts de build, les Makefiles, les scripts de packages et les binaires générés comme du code exécutable nécessitant le même niveau de revue qu'une commande shell directe.

Pour les environnements à haut risque :

• Examinez les scripts de build avant l'exécution.
• Préférez l'approbation/revue manuelle pour les workflows de compilation et d'exécution.
• Exécutez PicoClaw dans un conteneur ou une VM si vous avez besoin d'une isolation plus forte que celle fournie par le garde intégré.

Exemples d'Erreurs

[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)}

Désactiver les Restrictions (Risque de Sécurité)

Si vous avez besoin que l'agent accède à des chemins en dehors du workspace :

Méthode 1 : Fichier de configuration

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

Méthode 2 : Variable d'environnement

export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false

⚠️ Avertissement : Désactiver cette restriction permet à l'agent d'accéder à n'importe quel chemin sur votre système. À utiliser avec précaution dans des environnements contrôlés uniquement.

Cohérence des Limites de Sécurité

Le paramètre restrict_to_workspace s'applique de manière cohérente à tous les chemins d'exécution :

Tous les chemins partagent la même restriction de workspace — il n'y a aucun moyen de contourner la limite de sécurité via les subagents ou les tâches planifiées.

Heartbeat (Tâches Périodiques)

PicoClaw peut effectuer des tâches périodiques automatiquement. Créez un fichier HEARTBEAT.md dans votre workspace :

# Periodic Tasks

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

L'agent lira ce fichier toutes les 30 minutes (configurable) et exécutera toutes les tâches en utilisant les outils disponibles.

Tâches Asynchrones avec Spawn

Pour les tâches longues (recherche web, appels API), utilisez l'outil spawn pour créer un subagent :

# Tâches Périodiques

## Tâches Rapides (répondre directement)

- Indiquer l'heure actuelle

## Tâches Longues (utiliser spawn pour l'asynchrone)

- Rechercher les actualités IA sur le web et résumer
- Vérifier les e-mails et signaler les messages importants

Comportements clés :

Flux de Communication du Subagent

Heartbeat déclenché
    ↓
Agent lit HEARTBEAT.md
    ↓
Tâche longue : spawn subagent
    ↓                           ↓
Continue tâche suivante    Subagent travaille indépendamment
    ↓                           ↓
Toutes tâches terminées    Subagent utilise "message" tool
    ↓                           ↓
Répond HEARTBEAT_OK        Utilisateur reçoit le résultat

Configuration :

{
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}

Variables d'environnement :

• PICOCLAW_HEARTBEAT_ENABLED=false pour désactiver
• PICOCLAW_HEARTBEAT_INTERVAL=60 pour changer l'intervalle

Providers

[!NOTE] Groq fournit une transcription vocale gratuite via Whisper. Si configuré, les messages audio de n'importe quel canal seront automatiquement transcrits au niveau de l'agent.

Configuration des Modèles (model_list)

Nouveauté : PicoClaw utilise désormais une approche centrée sur le modèle. Spécifiez simplement le format vendor/model (ex. zhipu/glm-4.7) pour ajouter de nouveaux providers — aucune modification de code requise !

Tous les Vendors Supportés

Équilibrage de Charge

Configurez plusieurs endpoints pour le même nom de modèle — PicoClaw effectuera automatiquement un round-robin :

{
  "model_list": [
    { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_keys": ["sk-key1"] },
    { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_keys": ["sk-key2"] }
  ]
}

Migration depuis l'ancienne config providers

L'ancienne configuration providers est dépréciée et a été supprimée dans V2. Les configs V0/V1 existantes sont auto-migrées. Voir docs/migration/model-list-migration.md.

Configuration du Streaming

Le streaming provider utilise un double opt-in et est désactivé par défaut. L'agent ne tente le streaming que lorsque le channel courant a settings.streaming.enabled: true, que l'entrée de modèle active a streaming.enabled: true, et que le provider comme le channel prennent en charge le streaming. Si une condition manque, PicoClaw utilise le chemin de requête non-streaming normal.

Pico WebUI est le premier channel entièrement câblé. Pico crée le premier message assistant avec le message wire existant message.create, puis met à jour ce même message avec message.update; aucun nouveau type de message Pico n'est introduit.

Laissez streaming absent si vous ne voulez pas de streaming. Un bloc streaming omis signifie désactivé; il n'est pas nécessaire d'écrire "streaming": {"enabled": false}.

Exemple d'activation :

{
  "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
        }
      }
    }
  }
}

Les anciennes variables d'environnement Telegram restent compatibles : PICOCLAW_CHANNELS_TELEGRAM_STREAMING_ENABLED, PICOCLAW_CHANNELS_TELEGRAM_STREAMING_THROTTLE_SECONDS et PICOCLAW_CHANNELS_TELEGRAM_STREAMING_MIN_GROWTH_CHARS. Elles s'appliquent uniquement aux settings Telegram et n'activent ni ne modifient settings.streaming de Pico.

Le comportement d'échec est volontairement conservateur : si le streaming échoue avant l'envoi d'un chunk visible, PicoClaw réessaie une fois via le chemin Chat() normal. Si un chunk a déjà été affiché à l'utilisateur, PicoClaw n'envoie pas une deuxième réponse non-streaming, afin d'éviter une sortie dupliquée.

Architecture des Providers

PicoClaw route les providers par famille de protocole :

• Compatible OpenAI : OpenRouter, Groq, Zhipu, endpoints vLLM et la plupart des autres.
• Gemini natif : Google Gemini via les endpoints natifs models/*:generateContent et models/*:streamGenerateContent.
• Anthropic : Comportement natif de l'API Claude.
• Codex/OAuth : Route d'authentification OAuth/token OpenAI.

Cela maintient le runtime léger tout en faisant des nouveaux backends compatibles OpenAI principalement une opération de configuration (api_base + api_keys).

Tâches Planifiées / Rappels

PicoClaw supporte les tâches planifiées via l'outil cron. L'agent peut définir, lister et annuler des rappels ou tâches récurrentes.

{
  "tools": {
    "cron": {
      "enabled": true,
      "exec_timeout_minutes": 5
    }
  }
}

Les tâches planifiées persistent après redémarrage dans ~/.picoclaw/workspace/cron/.

Sujets Avancés