Ajout de fonctionnalités (guide du contributeur)

Utilisez ce guide lorsqu’OpenClaw a besoin d’un nouveau domaine partagé, tel que les plongements, la génération d’images, la génération de vidéos ou un futur domaine fonctionnel reposant sur des fournisseurs.

La règle :

• plugin = frontière de responsabilité
• capacité = contrat partagé du cœur

Ne reliez pas directement un fournisseur à un canal ou à un outil. Définissez d’abord la capacité.

Quand créer une capacité

Créez une capacité uniquement lorsque toutes les conditions suivantes sont remplies :

1. Plusieurs fournisseurs pourraient vraisemblablement l’implémenter.
2. Les canaux, outils ou plugins fonctionnels doivent pouvoir l’utiliser sans se soucier du fournisseur.
3. Le cœur doit gérer le mécanisme de repli, la politique, la configuration ou le comportement de livraison.

Si le travail concerne uniquement un fournisseur et qu’aucun contrat partagé n’existe encore, définissez d’abord le contrat.

Séquence standard

1. Définissez le contrat typé du cœur.
2. Ajoutez l’enregistrement du plugin pour ce contrat.
3. Ajoutez un utilitaire d’exécution partagé.
4. Intégrez un véritable plugin fournisseur à titre de preuve.
5. Faites migrer les consommateurs fonctionnels et les canaux vers l’utilitaire d’exécution.
6. Ajoutez des tests de contrat.
7. Documentez la configuration destinée aux opérateurs et le modèle de responsabilités.

Répartition des responsabilités

Points d’extension des fournisseurs et des environnements d’exécution

Utilisez les hooks de fournisseur lorsque le comportement relève du contrat du fournisseur de modèles plutôt que de la boucle générique de l’agent. Il peut notamment s’agir des paramètres de requête propres au fournisseur après la sélection du transport, de la préférence de profil d’authentification, des surcharges de prompt et du routage de repli après une bascule de modèle ou de profil.

Utilisez les hooks d’environnement d’exécution de l’agent lorsque le comportement relève de l’environnement qui exécute un tour. Ces environnements peuvent classer des résultats de protocole explicites, tels qu’une sortie vide, un raisonnement sans sortie visible ou un plan structuré sans réponse finale, afin que la politique externe de repli du modèle puisse décider d’une nouvelle tentative.

Maintenez ces deux points d’extension ciblés :

• Le cœur gère la politique de nouvelle tentative et de repli.
• Les plugins fournisseurs gèrent les paramètres de requête, l’authentification et les indications de routage propres au fournisseur.
• Les plugins d’environnement d’exécution gèrent la classification des tentatives propre à l’environnement.
• Les plugins tiers renvoient des indications, sans modifier directement l’état du cœur.

Liste de contrôle des fichiers

Pour une nouvelle capacité, prévoyez de modifier les zones suivantes :

• src/<capability>/types.ts
• src/<capability>/...registry/runtime.ts
• src/plugins/types.ts
• src/plugins/registry.ts
• src/plugins/captured-registration.ts
• src/plugins/contracts/registry.ts
• src/plugins/runtime/types-core.ts
• src/plugins/runtime/index.ts
• src/plugin-sdk/<capability>.ts
• src/plugin-sdk/<capability>-runtime.ts
• Un ou plusieurs paquets de plugins intégrés.
• La configuration, la documentation et les tests.

Exemple détaillé : génération d’images

La génération d’images suit la structure standard :

1. Le cœur définit ImageGenerationProvider.
2. Le cœur expose registerImageGenerationProvider(...).
3. Le cœur expose api.runtime.imageGeneration.generate(...) et .listProviders(...).
4. Les plugins fournisseurs (comfy, deepinfra, fal, google, litellm, microsoft-foundry, minimax, openai, openrouter, vydra, xai) enregistrent des implémentations reposant sur ces fournisseurs.
5. Les futurs fournisseurs enregistrent le même contrat sans modifier les canaux ni les outils.

La clé de configuration est intentionnellement distincte du routage de l’analyse visuelle :

• agents.defaults.imageModel analyse les images.
• agents.defaults.imageGenerationModel génère des images.

Conservez cette séparation afin que le mécanisme de repli et la politique restent explicites.

Fournisseurs de plongements

Utilisez registerEmbeddingProvider(...) et le contrat embeddingProviders pour les fournisseurs réutilisables de plongements vectoriels. Ce contrat est volontairement plus large que la mémoire : les outils, la recherche, la récupération, les importateurs ou les futurs plugins fonctionnels peuvent utiliser des plongements sans dépendre du moteur de mémoire. La recherche en mémoire utilise également les fournisseurs génériques embeddingProviders.

L’ancienne API d’enregistrement propre à la mémoire et le contrat memoryEmbeddingProviders sont obsolètes. Utilisez registerEmbeddingProvider et embeddingProviders pour tous les nouveaux fournisseurs de plongements.

Liste de contrôle de la revue

Avant de publier une nouvelle capacité, vérifiez les points suivants :

• Aucun canal ni outil n’importe directement le code d’un fournisseur.
• L’utilitaire d’exécution constitue le chemin partagé.
• Au moins un test de contrat vérifie la responsabilité intégrée.
• La documentation de configuration indique le nouveau modèle ou la nouvelle clé de configuration.
• La documentation des plugins explique la frontière de responsabilité.

Si une PR omet la couche de capacité et code en dur le comportement d’un fournisseur dans un canal ou un outil, renvoyez-la et définissez d’abord le contrat.

Ressources connexes

• Architecture interne des plugins — modèle de capacités, responsabilités, pipeline de chargement et utilitaires d’exécution.
• Développer des plugins — tutoriel de création d’un premier plugin.
• Présentation du SDK — référence des correspondances d’importation et de l’API d’enregistrement.
• Créer des skills — interface complémentaire destinée aux contributeurs.