OpenClaw API skills : connecter une API
Connectez une API à OpenClaw avec le bon partage des rôles entre skill Markdown, tool de plugin TypeScript, secrets et validation des effets.
Introduction
Les openclaw api skills ne sont pas des classes Python qui encapsulent httpx. Dans le produit actuel, un skill Markdown explique à l’agent comment utiliser un tool, tandis qu’un plugin Node/TypeScript peut ajouter le client API, le schéma d’entrée et la gestion des secrets. Cette approche est utile pour une intégration métier durable et auditable. Si un plugin officiel ou communautaire fiable couvre déjà le service, évitez de recoder une capacité ; si un simple webhook déterministe suffit, OpenClaw peut aussi être inutile. Ce tutoriel vous aide à choisir la bonne couche, installer ou concevoir le tool, rédiger le SKILL.md et vérifier les lectures comme les écritures.
Résumé rapide
- Cherchez d’abord un plugin ou tool existant.
- Le plugin porte l’appel API ; le skill porte les instructions d’usage.
- Les secrets restent dans la configuration, jamais dans
SKILL.md. - Validez schéma, timeout, erreurs et idempotence côté runtime.
- Testez lecture, écriture, relecture et refus avant production.
Skill, tool et plugin : trois responsabilités
Un skill est du contexte procédural : il décrit quand appeler un tool, quels paramètres fournir, comment interpréter la réponse et quand s’arrêter. Un tool est la fonction structurée que le modèle peut invoquer. Un plugin OpenClaw est une extension runtime Node/TypeScript capable d’enregistrer ce tool, de charger une configuration et de parler au service externe.
Cette séparation évite trois erreurs : mettre une clé dans un prompt, laisser le modèle construire des requêtes arbitraires et confondre une documentation avec une frontière de permission. Pour une API critique, exposez des opérations métier étroites comme ticket_get ou ticket_create, plutôt qu’un tool HTTP universel. Le schéma du tool filtre les entrées ; la policy de l’agent décide s’il peut l’utiliser.
Le guide des skills OpenClaw couvre la couche Markdown. Ce tutoriel se concentre sur le contrat entre cette couche et un plugin réellement chargé par le Gateway.
Connecter une API sans inventer de SDK
1. Vérifier l’existant
Cherchez un plugin ou un skill dans ClawHub et inspectez sa provenance :
openclaw plugins search "calendar"
openclaw skills search "calendar"
Un skill seul suppose qu’un tool ou un binaire existe déjà. Un plugin peut ajouter la capacité runtime. Préférez une source officielle, une version épinglée et une surface étroite.
2. Installer et inspecter un plugin
openclaw plugins install clawhub:<package>
openclaw plugins enable <plugin-id>
openclaw gateway restart
openclaw plugins inspect <plugin-id> --runtime --json
L’inspection runtime, après redémarrage, prouve que le tool est enregistré dans le Gateway actif. Une simple présence dans la liste locale ne suffit pas.
3. Définir le contrat du tool
Pour une intégration personnalisée, le plugin TypeScript doit enregistrer des opérations aux entrées bornées. Définissez les champs requis, les formats, les limites de taille et les valeurs autorisées. Normalisez la sortie pour ne renvoyer au modèle que les données utiles. Séparez lecture et écriture afin de pouvoir autoriser l’une sans l’autre.
Le client runtime doit fixer un timeout, distinguer erreurs réseau, authentification, quota et validation, puis retourner des erreurs exploitables sans exposer les secrets. Les retries sont réservés aux pannes transitoires. Une création doit accepter une clé d’idempotence ou un identifiant métier pour éviter les doublons.
4. Gérer l’authentification
Configurez le secret sous plugins.entries.<id>.config avec le mécanisme prévu par le plugin, une variable d’environnement ou un SecretRef compatible. Ne placez jamais un token dans SKILL.md, AGENTS.md, MEMORY.md ou un exemple de commande. Utilisez un credential dédié, limité aux endpoints nécessaires et révocable indépendamment.
5. Écrire le skill compagnon
name: tickets-support
description: Consulte et crée des tickets support avec validation et relecture.
**Tickets support**
Utiliser ce skill pour consulter un ticket identifié ou préparer une création.
1. Valider l’identifiant ou les champs obligatoires.
2. Utiliser le tool de lecture avant toute modification.
3. Demander confirmation avant une création.
4. Appeler le tool d’écriture avec une clé d’idempotence.
5. Relire le ticket et comparer les champs demandés.
Ne jamais afficher de credential. En cas de refus d’authentification, arrêter sans retry.
Dans un vrai SKILL.md, ces deux métadonnées sont placées entre les délimiteurs YAML. Le fichier doit ensuite être validé par openclaw skills check.
6. Limiter la visibilité
Exposez le skill uniquement à l’agent concerné, puis limitez aussi le tool. Une allowlist de skill n’empêche pas l’appel direct d’un tool encore autorisé. Pour une API d’écriture, réservez la capacité aux expéditeurs de confiance, activez le sandbox si pertinent et conservez une approbation sur les actions sensibles.
7. Tester le GET métier
Utilisez un identifiant connu. Vérifiez la réponse structurée, les champs absents, le timeout et un cas not found. Le modèle ne doit recevoir ni headers internes ni payload brut inutile. Comparez la sortie du tool à la donnée source.
8. Tester le POST métier
Commencez sur un environnement de test. Envoyez une création avec une clé d’idempotence, relisez la ressource via le tool de lecture, puis rejouez la même demande. Le second passage ne doit pas créer un doublon. Testez aussi une entrée invalide et une authentification refusée ; aucun retry aveugle ne doit se produire.
9. Observer en production
Journalisez l’opération, le statut, la durée et un identifiant non sensible. Nettoyez les payloads et headers. Sur erreur, le rapport doit dire si l’effet a pu avoir lieu avant le timeout. Une ambiguïté exige une lecture de l’état distant avant tout retry.
Checklist finale
- plugin revu et épinglé ;
- tool runtime visible ;
- secret externe au skill ;
- schéma borné ;
- timeout et erreurs testés ;
- idempotence prouvée ;
- relecture après écriture ;
- logs sans données sensibles.
Repère opérationnel supplémentaire
Le Gateway doit rester le point de référence opérationnel. Il porte les sessions, les connexions aux canaux et le routage ; un redémarrage ou une panne affecte donc toutes les surfaces qui en dépendent. En production, supervisez le processus, conservez une procédure de redémarrage, puis vérifiez son état avec openclaw gateway status. Les automations exigent elles aussi un Gateway actif au moment prévu. Cette topologie est plus simple à exploiter qu'une collection de scripts dispersés, mais elle impose de traiter le Gateway comme un service durable et non comme une commande ponctuelle.
Exemple concret
Un service support possède une API pour lire et créer des tickets. Plutôt que d’exposer un tool HTTP générique, l’équipe installe un plugin qui fournit ticket_get et ticket_create. Le premier accepte uniquement un identifiant ; le second exige sujet, description, priorité et clé d’idempotence. Le secret vient de la configuration du plugin.
Un skill tickets-support demande de lire avant d’écrire, de faire confirmer la création et de relire le ticket créé. L’équipe vérifie openclaw skills check --agent support, redémarre le Gateway puis confirme le runtime avec openclaw plugins inspect <plugin-id> --runtime --json. Sur l’environnement de test, elle crée un ticket, relit son identifiant et rejoue la demande avec la même clé : aucun doublon ne doit apparaître. Elle teste enfin un token invalide et un timeout ambigu. Dans les deux cas, l’agent s’arrête et vérifie l’état avant toute nouvelle écriture. Ce scénario démontre un contrat API sûr, pas seulement un appel réussi.
Bonnes pratiques
Préférez les tools métier étroits aux requêtes HTTP arbitraires. Séparez lecture et écriture, validez les paramètres côté plugin et réduisez la réponse avant de la renvoyer au modèle. Utilisez des credentials dédiés, bornés et révocables ; nettoyez headers et payloads des logs.
Pour les effets de bord, exigez confirmation, idempotence et lecture après écriture. Ne réessayez pas automatiquement une erreur d’authentification ou une réponse ambiguë après timeout. Votre checklist de production doit couvrir le plugin runtime, le skill éligible, la policy de tool, le sandbox, les cas 4xx et 5xx, le quota, la latence et le rollback. Auditez toute extension communautaire comme du code exécuté dans le Gateway.
Questions fréquentes
Comment brancher une API sur OpenClaw ?
Cherchez d’abord un plugin qui expose le tool nécessaire. Installez-le, redémarrez le Gateway et vérifiez son enregistrement runtime. Écrivez ensuite un skill SKILL.md qui explique quand utiliser le tool, comment valider les entrées et comment contrôler le résultat.
Un skill API OpenClaw est-il écrit en Python ?
Non. Un skill OpenClaw actuel est un fichier Markdown. Une capacité API runtime personnalisée se construit généralement dans un plugin Node/TypeScript qui enregistre un tool. Les exemples BaseSkill, SkillOutput et httpx ne correspondent pas à l’architecture officielle actuelle.
Où stocker la clé d’une API connectée à OpenClaw ?
Stockez-la dans la configuration du plugin, une variable d’environnement ou un SecretRef pris en charge. Utilisez un credential dédié avec les permissions minimales. Ne mettez jamais la clé dans le skill, le workspace, la mémoire, un prompt ou un transcript de test.
Comment fiabiliser une écriture API par un agent ?
Exposez une opération métier bornée, validez son schéma et demandez confirmation. Ajoutez une clé d’idempotence, un timeout et des erreurs typées. Après l’écriture, relisez la ressource et comparez les champs. Si le timeout rend l’effet ambigu, vérifiez avant de réessayer.
Articles liés
Une intégration API OpenClaw fiable sépare le plugin qui agit, le tool structuré qui borne l’opération et le skill qui guide l’agent. Commencez par une lecture sans risque, puis n’ajoutez l’écriture qu’avec idempotence, relecture et restrictions explicites.
Restez informé sur les agents IA
Nouveaux tutoriels, comparatifs et guides pratiques directement dans votre boîte mail.