🔧 Configuration des Outils

Retour au README

La configuration des outils de PicoClaw se trouve dans le champ tools de config.json.

Structure du répertoire

{
  "tools": {
    "web": {
      ...
    },
    "mcp": {
      ...
    },
    "exec": {
      ...
    },
    "cron": {
      ...
    },
    "skills": {
      ...
    }
  }
}

Outils Web

Les outils web sont utilisés pour la recherche et la récupération de pages web.

Web Fetcher

Paramètres généraux pour la récupération et le traitement du contenu des pages web.

DuckDuckGo

Baidu Search

{
  "tools": {
    "web": {
      "baidu_search": {
        "enabled": true,
        "api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
        "max_results": 10
      }
    }
  }
}

Perplexity

Brave

Tavily

SearXNG

GLM Search

Outil Exec

L'outil exec est utilisé pour exécuter des commandes shell.

Désactivation de l'Outil Exec

Pour désactiver complètement l'outil exec, définissez enabled à false :

Via le fichier de configuration :

{
  "tools": {
    "exec": {
      "enabled": false
    }
  }
}

Via la variable d'environnement :

PICOCLAW_TOOLS_EXEC_ENABLED=false

Note : Lorsqu'il est désactivé, l'agent ne pourra pas exécuter de commandes shell. Cela affecte également la capacité de l'outil Cron à exécuter des commandes shell planifiées.

Fonctionnalité

• enable_deny_patterns : Définir à false pour désactiver complètement les modèles de blocage par défaut des commandes dangereuses
• custom_deny_patterns : Ajouter des modèles regex de refus personnalisés ; les commandes correspondantes seront bloquées

Modèles de commandes bloquées par défaut

Par défaut, PicoClaw bloque les commandes dangereuses suivantes :

• Commandes de suppression : rm -rf, del /f/q, rmdir /s
• Opérations disque : format, mkfs, diskpart, dd if=, écriture vers /dev/sd*
• Opérations système : shutdown, reboot, poweroff
• Substitution de commandes : $(), ${}, backticks
• Pipe vers shell : | sh, | bash
• Élévation de privilèges : sudo, chmod, chown
• Contrôle de processus : pkill, killall, kill -9
• Opérations distantes : curl | sh, wget | sh, ssh
• Gestion de paquets : apt, yum, dnf, npm install -g, pip install --user
• Conteneurs : docker run, docker exec
• Git : git push, git force
• Autres : eval, source *.sh

Limitation architecturale connue

Le garde exec ne valide que la commande de niveau supérieur envoyée à PicoClaw. Il n'inspecte pas récursivement les processus enfants générés par les outils de build ou les scripts après le démarrage de cette commande.

Exemples de workflows pouvant contourner le garde de commande directe une fois la commande initiale autorisée :

• make run
• go run ./cmd/...
• cargo run
• npm run build

Cela signifie que le garde est utile pour bloquer les commandes directes manifestement dangereuses, mais ce n'est pas un bac à sable complet pour les pipelines de build non vérifiés. Si votre modèle de menace inclut du code non fiable dans l'espace de travail, utilisez une isolation plus forte comme des conteneurs, des VM ou un flux d'approbation autour des commandes de build et d'exécution.

Exemple de configuration

{
  "tools": {
    "exec": {
      "enable_deny_patterns": true,
      "custom_deny_patterns": [
        "\\brm\\s+-r\\b",
        "\\bkillall\\s+python"
      ]
    }
  }
}

Outil Cron

L'outil cron est utilisé pour planifier des tâches périodiques.

<a id="mcp-tool"></a>

Outil MCP

L'outil MCP permet l'intégration avec des serveurs Model Context Protocol externes.

Découverte d'outils (chargement paresseux)

Lors de la connexion à plusieurs serveurs MCP, exposer simultanément des centaines d'outils peut épuiser la fenêtre de contexte du LLM et augmenter les coûts API. La fonctionnalité Discovery résout ce problème en gardant les outils MCP masqués par défaut.

Au lieu de charger tous les outils, le LLM reçoit un outil de recherche léger (utilisant la correspondance par mots-clés BM25 ou les expressions régulières). Lorsque le LLM a besoin d'une capacité spécifique, il recherche dans la bibliothèque masquée. Les outils correspondants sont alors temporairement « déverrouillés » et injectés dans le contexte pour un nombre configuré de tours (ttl).

Configuration globale

Configuration Discovery (discovery)

Note : Si discovery.enabled est true, vous devez activer au moins un moteur de recherche (use_bm25 ou use_regex), sinon l'application ne démarrera pas.

Configuration par serveur

Comportement du transport

• Si type est omis, le transport est détecté automatiquement :
  • url est défini → sse
  • command est défini → stdio
• http et sse utilisent tous deux url + headers optionnels.
• env et env_file ne sont appliqués qu'aux serveurs stdio.

Exemples de configuration

1) Serveur MCP Stdio

{
  "tools": {
    "mcp": {
      "enabled": true,
      "servers": {
        "filesystem": {
          "enabled": true,
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-filesystem",
            "/tmp"
          ]
        }
      }
    }
  }
}

2) Serveur MCP distant SSE/HTTP

{
  "tools": {
    "mcp": {
      "enabled": true,
      "servers": {
        "remote-mcp": {
          "enabled": true,
          "type": "sse",
          "url": "https://example.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN"
          }
        }
      }
    }
  }
}

3) Configuration MCP massive avec découverte d'outils activée

Dans cet exemple, le LLM ne verra que tool_search_tool_bm25. Il recherchera et déverrouillera dynamiquement les outils Github ou Postgres uniquement lorsque l'utilisateur le demande.

{
  "tools": {
    "mcp": {
      "enabled": true,
      "discovery": {
        "enabled": true,
        "ttl": 5,
        "max_search_results": 5,
        "use_bm25": true,
        "use_regex": false
      },
      "servers": {
        "github": {
          "enabled": true,
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-github"
          ],
          "env": {
            "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
          }
        },
        "postgres": {
          "enabled": true,
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-postgres",
            "postgresql://user:password@localhost/dbname"
          ]
        },
        "slack": {
          "enabled": true,
          "type": "slack",
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-slack"
          ],
          "env": {
            "SLACK_BOT_TOKEN": "YOUR_SLACK_BOT_TOKEN",
            "SLACK_TEAM_ID": "YOUR_SLACK_TEAM_ID"
          }
        }
      }
    }
  }
}

<a id="skills-tool"></a>

Outil Skills

L'outil skills configure la découverte et l'installation de compétences via des registres comme ClawHub.

Registres

Exemple de configuration

{
  "tools": {
    "skills": {
      "registries": {
        "clawhub": {
          "enabled": true,
          "base_url": "https://clawhub.ai",
          "auth_token": "",
          "search_path": "/api/v1/search",
          "skills_path": "/api/v1/skills",
          "download_path": "/api/v1/download"
        }
      }
    }
  }
}

Variables d'environnement

Toutes les options de configuration peuvent être remplacées via des variables d'environnement au format PICOCLAW_TOOLS_<SECTION>_<KEY> :

Par exemple :

• PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true
• PICOCLAW_TOOLS_EXEC_ENABLED=false
• PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false
• PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10
• PICOCLAW_TOOLS_MCP_ENABLED=true

Note : La configuration de type map imbriquée (par exemple tools.mcp.servers.<name>.*) est configurée dans config.json plutôt que via des variables d'environnement.