Tarification et configuration API de PicoClaw : modèles, protocoles et clés

Le logiciel PicoClaw est gratuit : le dépôt est sous licence MIT et la FAQ officielle de picoclaw.io indique « The software is free. You only pay for the LLM API usage » — ainsi, « tarification de PicoClaw » désigne votre facture d’API de modèle, à laquelle s’ajoute éventuellement le coût de l’appareil. Sipeed n’annonce ni abonnement PicoClaw ni niveau hébergé. La valeur à budgéter est le nombre de tokens par tour d’agent, et le paramètre le plus susceptible de surprendre est la limite d’itérations d’outils de PicoClaw : 50 lorsque le champ est absent, 20 dans le fichier de configuration fourni.

Commençons par deux mises au point, car la page de résultats les mélange. Le domaine officiel est picoclaw.io — c’est le champ homepage de github.com/sipeed/picoclaw. Le site ressemblant pico-claw.com précise dans son propre pied de page qu’il « is not officially affiliated with Sipeed or PicoClaw », et le prix mensuel qui y figure appartient à son propre module d’hébergement géré, pas à PicoClaw. Un deuxième site ressemblant, picoclaw.net, n’est pas non plus le domaine officiel. Il affiche en titre « 95% AI-Generated Code » et « 3 Supported Architectures » — x86_64, ARM64 et RISC-V — alors que la FAQ de picoclaw.io en recense six. Et PicoClaw n’est pas un fork d’OpenClaw ; c’est une implémentation Go indépendante qui se compare elle-même à OpenClaw et NanoBot.

Tarification de PicoClaw, ligne par ligne

Tout a été vérifié le 21 septembre 2026. Pour mémoire, la dernière version balisée est v0.3.1, publiée le 3 juillet 2026, tandis que le dépôt a reçu son dernier push le 17 septembre 2026 — le code de main est donc plus récent que la balise, et la propre liste d’actualités du README est encore plus obsolète, sa dernière entrée de version étant v0.2.9 du 28 mai 2026. Tous les comportements ci-dessous ont été lus sur main, et non dans le binaire v0.3.1 que vous téléchargeriez ; un lecteur utilisant la version balisée peut donc constater une différence. Une condition observée le jour de la vérification : le certificat TLS de picoclaw.io avait expiré (valide du 25 février au 10 septembre 2026), si bien qu’un navigateur affiche un avertissement de sécurité sur la page officielle de téléchargement. Cela peut être corrigé à tout moment et ne dit rien du projet ; les versions GitHub ne sont pas affectées.

Configuration de la clé API PicoClaw : model_list et .security.yml

picoclaw onboard crée ~/.picoclaw/config.json et l’espace de travail. Les modèles sont déclarés dans un tableau model_list et sélectionnés par leur nom depuis agents.defaults.model_name ; les deux doivent correspondre, ce qui constitue le seul cas traité par le document de dépannage de PicoClaw.

{
  "agents": {
    "defaults": {
      "model_name": "gateway-sonnet"
    }
  },
  "model_list": [
    {
      "model_name": "gateway-sonnet",
      "provider": "openai",
      "model": "claude-sonnet-4-6",
      "api_base": "https://api.kunavo.com/v1",
      "enabled": true
    }
  ]
}

Les clés résident dans un second fichier. La documentation de sécurité de PicoClaw appelle config.json « Main configuration (safe to share) » et .security.yml « Security data (never share) », et vous demande de le chmod 600. La structure YAML est une map indexée par model_name, et non le tableau utilisé dans config.json ; api_keys est au pluriel et constitue un tableau même pour une seule clé.

# The map key must equal the model_name in config.json.
# api_keys is plural and is an array even for one key.
model_list:
  gateway-sonnet:
    api_keys:
      - "sk-kn-..."

Quatre détails piègent souvent les utilisateurs. provider est facultatif : si vous le définissez, model est envoyé tel quel au fournisseur ; si vous l’omettez, PicoClaw considère comme fournisseur tout ce qui précède le premier / dans model, ce qui correspond à l’ancienne forme protocol/model. La configuration est versionnée par schéma et la version 3 est actuelle ; la migration crée une sauvegarde datée, et la documentation avertit qu’un fichier V3 ne peut pas être chargé de manière sûre par d’anciens binaires limités à V2. Lors de la migration de V1 vers V2, enabled est déduit automatiquement — les entrées sans clé API et qui ne portent pas le nom local-model sont par défaut désactivées — raison pour laquelle l’exemple ci-dessus définit explicitement enabled après le déplacement des clés vers .security.yml. Enfin, la diffusion est désactivée par défaut et soumise à deux conditions : streaming.enabled de l’entrée du modèle et settings.streaming.enabled du canal doivent tous deux être définis sur true.

Une limite mérite d’être précisée avant de créer vos entrées : le tableau des fournisseurs de PicoClaw décrit Groq comme « LLM + Voice transcription (Whisper) », et Kunavo ne fournit ni reconnaissance vocale, ni synthèse vocale, ni embeddings — une entrée de transcription ou d’embeddings doit pointer vers un autre fournisseur ; seules les entrées de chat peuvent utiliser une clé Kunavo.

Les noms des protocoles sont inversés, et c’est là tout le piège

Dans PicoClaw, anthropic désigne des modèles de type Claude utilisant le format filaire OpenAI, tandis que anthropic-messages désigne l’API native Messages d’Anthropic. La documentation le dit explicitement : « Le protocole anthropic utilise le format compatible OpenAI (/v1/chat/completions), tandis que anthropic-messages utilise le format natif d’Anthropic (/v1/messages). » Le code le confirme : factory_provider.go construit le fournisseur HTTP partagé compatible OpenAI pour anthropic et un fournisseur natif distinct pour anthropic-messages. Le propre tableau « All Supported Vendors » de PicoClaw contredit les deux en étiquetant la colonne de protocole de la ligne anthropic « Anthropic » ; un lecteur qui ne consulte que ce tableau configure le mauvais protocole.

Lu depuis openai_compat/provider.go, common/anthropic_common.go, anthropic_messages/provider.go et factory_provider.go sur main, le 21 septembre 2026 — déduit du code, et non observé sur le réseau. La conséquence est concrète : vous ne pouvez pas diriger anthropic ou anthropic-messages vers une passerelle dont le chemin ne doit pas se terminer par /v1, car PicoClaw l’ajoute systématiquement. Une passerelle située à https://gw.example.com/anthropic devient https://gw.example.com/anthropic/v1/messages. Pour un tel endpoint, le protocole openai, qui respecte le chemin tel quel, est le seul à pouvoir exprimer l’URL. Seuls ces trois protocoles ont été audités ; ne généralisez pas cette règle à gemini, azure ou aux autres.

Deux autres limites concernent le chemin natif, toutes deux lues dans le même fichier. anthropic-messages exige une clé API et provoque une erreur fatale en son absence ; la branche OAuth — que factory_provider.go relie à anthropic et openai, ainsi qu’aux ponts CLI et à antigravity — ne peut donc pas être atteinte par ce chemin. Et bien que cinq branches de factory_provider.go transmettent cfg.CustomHeaders, la branche anthropic-messages n’en fait pas partie : son constructeur n’accepte que la clé, l’URL de base, l’agent utilisateur et le délai d’attente. Ainsi, la solution de contournement documentée custom_headers pour une passerelle utilisant une authentification non standard semble atteindre les protocoles compatibles OpenAI, mais pas celui des Messages natifs. Il s’agit d’une lecture du code, pas d’un test à l’exécution. Ce que le chemin natif ne vous coûte pas, c’est l’appel d’outils : il construit des tools natifs avec input_schema et traite les blocs tool_use et tool_result.

Pour Kunavo, les deux URL de base documentées sont https://api.kunavo.com/v1 pour les chat completions et https://api.kunavo.com/v1/messages pour la route Messages ; le gestionnaire Messages de Kunavo lit également la clé depuis x-api-key ainsi que depuis Authorization: Bearer. Sur le papier, ces éléments correspondent à l’arithmétique des URL de PicoClaw dans les deux sens. Il s’agit d’une arithmétique fondée sur deux ensembles de documents — aucune requête PicoClaw n’a été envoyée à Kunavo ici, et cette page ne prétend pas qu’un protocole PicoClaw y a été testé. Consultez la documentation de l’URL de base Anthropic et la documentation de l’endpoint de chat pour les structures exactes, puis envoyez vous-même une requête limitée.

Exemple de calcul du coût d’une API PicoClaw

Il s’agit d’un calcul illustratif de tokens, et non de coûts de tâche mesurés ni d’un plafond de facturation. Supposons un tour d’agent qui se termine en 8 cycles d’outils, chaque cycle renvoyant un transcript de 12 000 tokens d’entrée en moyenne et produisant 700 tokens de sortie. Ces ratios sont des hypothèses illustratives. La deuxième colonne applique la même structure jusqu’à la valeur par défaut compilée max_tool_iterations de 50 dans pkg/config/defaults.go, utilisée lorsque le champ est absent — le fichier config/config.example.json fourni indique 20 ; consultez donc votre propre fichier avant de considérer 50 comme votre plafond. Les tarifs sont ceux du catalogue Kunavo en vigueur, par million de tokens.

Lisez les deux colonnes comme un seul fait. Passer de 8 cycles au plafond de 50 multiplie chaque ligne par le même facteur 6.25x, car la longueur de la boucle est indépendante du tarif : un tour Claude Sonnet 4.6 coûte $0.260 avec 8 cycles et $1.627 au plafond, tandis que Claude Haiku 4.5 coûte $0.542 à ce même plafond. Limitez donc max_tool_iterations à un nombre que vous avez réellement observé avant de rechercher un tarif moins cher — il se trouve sous agents.defaults et peut être remplacé par la variable d’environnement PICOCLAW_AGENTS_DEFAULTS_MAX_TOOL_ITERATIONS. Multipliez ensuite par le nombre de tours quotidiens.

Le montant du catalogue Kunavo constitue un plancher de facturation, et non un plafond : lorsque le fournisseur amont communique son coût, la facture correspond au montant le plus élevé entre le coût du catalogue et le coût amont multiplié par la majoration applicable. Les lectures et écritures de cache sont facturées à leurs propres tarifs et ne sont modélisées dans aucun sens ici ; les appels à des outils externes sont également exclus de l’exemple. Le rechargement minimal est de 10 $ de crédit prépayé, un minimum de financement et non un frais de tâche ou un abonnement — consultez les détails de facturation et l’optimisation des coûts IA pour connaître la méthode de mesure.

Meilleure API pour PicoClaw : quelle route l’emporte selon le cas

Le nombre de fournisseurs n’est pas un axe de comparaison ici : les propres fichiers de PicoClaw se contredisent quant aux fournisseurs disponibles ; la formulation « 30+ LLM providers » de son README est donc la plus prudente à reprendre. Pour situer PicoClaw parmi les autres agents à binaire unique, l’annuaire des API d’agents IA présente sa surface de configuration à côté de la leur, et les alternatives à OpenRouter comparent les routes de passerelle selon les conditions de financement plutôt que selon la profondeur de l’intégration.

Première requête, premier cycle d’outils et erreur 404

Exécutez une tâche au périmètre délimité et examinez trois éléments dans l'ordre. Une erreur modèle introuvable dans model_list correspond au cas documenté et résulte d'une discordance de nom : agents.defaults.model_name doit correspondre exactement à une entrée de model_name, et un identifiant sans préfixe, sans provider défini, ne sélectionne pas le fournisseur que vous souhaitiez utiliser — il se rabat sur le protocole openai, ce qui correspond au cas documenté "model": "free" dans lequel OpenRouter reçoit l'identifiant littéral free et le rejette. Une erreur 404 dès la première requête est le signe documenté que vous avez choisi le mauvais protocole Anthropic — les propres recommandations de PicoClaw indiquent de passer à anthropic-messages lorsque « le protocole anthropic existant renvoie des erreurs 404 (ce qui indique que le point de terminaison ne prend pas en charge le format compatible avec OpenAI) ». Vérifiez l'URL assemblée en vous référant au tableau ci-dessus avant de modifier quoi que ce soit d'autre ; aucune rubrique officielle de dépannage ne traite de ce problème, ce diagnostic provient donc de la note sur les fournisseurs et du code source, et non d'une page d'assistance. Troisièmement, si le premier cycle d'appel d'outil échoue alors que la conversation simple fonctionnait, soupçonnez la rigueur des exigences relatives aux schémas plutôt que l'authentification : PicoClaw transmet par défaut les schémas des outils sans les modifier, et tool_schema_transform: "simple" permet de désactiver ce comportement pour chaque modèle lorsque les points de terminaison rejettent $ref, $defs, anyOf, oneOf, allOf ou pattern.

Kunavo ne publie aucune page de configuration PicoClaw et n’a effectué aucun test de compatibilité PicoClaw ; gardez une route fonctionnelle disponible pendant vos essais, puis consultez le montant réellement enregistré sur votre compte pour cette tâche plutôt que de l’estimer à partir de cette page. Créez un compte Kunavo lorsque vous serez prêt à financer une clé, et comparez les tarifs des modèles sur l’API Claude la moins chère si Claude est la famille que vous avez choisie.

Questions fréquentes

Vérifié le 21 septembre 2026 : le dépôt GitHub et l’API des versions, picoclaw.io (consulté avec la validation du certificat désactivée, car son certificat avait expiré), le README, docs/guides/providers.md, docs/security/security_configuration.md, docs/reference/config-versioning.md, docs/guides/configuration.md, docs/operations/troubleshooting.md, config/config.example.json, ainsi que sept fichiers sources de la branche main — factory_provider.go, openai_compat/provider.go, common/anthropic_common.go, anthropic_messages/provider.go, provider_metadata.go, pkg/config/defaults.go et pkg/config/config.go — plus les deux domaines ressemblants. N’ont pas été vérifiés : les quotas de tiers du propre tableau comparatif de PicoClaw, les prix de vente au détail du matériel et les notes de version de la version v0.3.1. Rien n’a été installé ni exécuté : aucune requête PicoClaw n’a été envoyée à un endpoint. Les tarifs des tokens Kunavo proviennent du catalogue en direct, et chaque exemple en dollars est un calcul illustratif de tokens, non le coût mesuré d’une tâche.