Plugin maintainer reference

Compatibilité des Plugins

OpenClaw maintient les anciens contrats de Plugin via des adaptateurs de compatibilité nommés avant de les supprimer. Cela protège les plugins intégrés et externes existants pendant que les contrats du SDK, du manifeste, de la configuration initiale, de la configuration et de l’environnement d’exécution des agents évoluent.

Registre de compatibilité

Les contrats de compatibilité des plugins sont suivis dans le registre du cœur à l’emplacement src/plugins/compat/registry.ts. Chaque entrée comporte :

un code de compatibilité stable
un état : active, deprecated, removal-pending ou removed
un propriétaire : sdk, config, setup, channel, provider, plugin-execution, agent-runtime ou core
les dates d’introduction et d’obsolescence, le cas échéant
des recommandations de remplacement
la documentation, les diagnostics et les tests couvrant l’ancien et le nouveau comportement

Le registre constitue la source de référence pour la planification des responsables de maintenance et les futures vérifications de l’inspecteur de plugins. Si un comportement exposé aux plugins change, ajoutez ou mettez à jour l’entrée de compatibilité dans la même modification que celle qui ajoute l’adaptateur.

La compatibilité des réparations et migrations de Doctor est suivie séparément dans src/commands/doctor/shared/deprecation-compat.ts. Ces entrées couvrent les anciennes structures de configuration, les structures du registre d’installation et les couches d’adaptation de réparation susceptibles de devoir rester disponibles après la suppression du chemin de compatibilité de l’environnement d’exécution.

Les vérifications de publication doivent contrôler les deux registres. Ne supprimez pas une migration de Doctor simplement parce que l’entrée de compatibilité correspondante de l’environnement d’exécution ou de la configuration a expiré ; vérifiez d’abord qu’aucun chemin de mise à niveau pris en charge n’a encore besoin de cette réparation. Revalidez également chaque annotation de remplacement lors de la planification des publications, car la responsabilité des plugins et l’empreinte de configuration peuvent évoluer à mesure que les fournisseurs et les canaux quittent le cœur.

Politique d’obsolescence

OpenClaw ne doit pas supprimer un contrat de Plugin documenté dans la même version que celle qui introduit son remplacement. Séquence de migration :

Ajoutez le nouveau contrat.
Maintenez l’ancien comportement via un adaptateur de compatibilité nommé.
Émettez des diagnostics ou des avertissements lorsque les auteurs de plugins peuvent intervenir.
Documentez le remplacement et le calendrier.
Testez les anciens et les nouveaux chemins.
Attendez la fin de la période de migration annoncée.
Ne procédez à la suppression qu’avec une approbation explicite pour une version comportant des changements incompatibles.

Les entrées obsolètes doivent inclure une date de début des avertissements, un remplacement, un lien vers la documentation et une date de suppression définitive au plus tard trois mois après le début des avertissements. N’ajoutez pas de chemin de compatibilité obsolète avec une période de suppression sans échéance, sauf si les responsables de maintenance décident explicitement qu’il s’agit d’une compatibilité permanente et le marquent plutôt comme active.

Zones de compatibilité actuelles

Le registre suit actuellement environ 70 codes de compatibilité dans les zones suivantes. Le nouveau code de Plugin doit utiliser le remplacement indiqué dans chaque zone et dans le guide de migration correspondant ; les plugins existants peuvent continuer à utiliser un chemin de compatibilité jusqu’à ce que la documentation, les diagnostics et les notes de publication annoncent une période de suppression.

les anciens imports généraux du SDK, tels que openclaw/plugin-sdk/compat
les anciennes structures de plugins composées uniquement de hooks et before_agent_start
les anciens noms de hooks de nettoyage api.on("deactivate", ...) pendant la migration des plugins vers gateway_stop
les anciens points d’entrée de Plugin activate(api) pendant la migration des plugins vers register(api)
les anciens alias du SDK tels que openclaw/extension-api, openclaw/plugin-sdk/channel-runtime, les générateurs d’état de openclaw/plugin-sdk/command-auth, openclaw/plugin-sdk/test-utils (remplacé par des sous-chemins de test ciblés openclaw/plugin-sdk/*), ainsi que les alias de types ClawdbotConfig / OpenClawSchemaType
le comportement de liste d’autorisation et d’activation des plugins intégrés
les anciennes métadonnées de manifeste pour les variables d’environnement des fournisseurs et des canaux
les anciens hooks et alias de types des plugins de fournisseur pendant la migration des fournisseurs vers des hooks explicites de catalogue, d’authentification, de raisonnement, de relecture et de transport
les anciens alias d’environnement d’exécution tels que api.runtime.taskFlow, api.runtime.subagent.getSession, api.runtime.stt et les méthodes obsolètes api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...)
les champs plats de rappel WebInboundMessage de WhatsApp (voir ci-dessous)
les champs d’admission de premier niveau de WebInboundMessage de WhatsApp (voir ci-dessous)
l’ancien enregistrement fractionné des plugins de mémoire pendant leur migration vers registerMemoryCapability
l’ancien enregistrement de fournisseurs d’incorporation propre à la mémoire pendant leur migration vers api.registerEmbeddingProvider(...) et contracts.embeddingProviders
les anciens assistants du SDK de canal pour les schémas de messages natifs, le filtrage des mentions, la mise en forme des enveloppes entrantes et l’imbrication des capacités d’approbation
les anciens alias de clé de route de canal et d’assistants de comparaison de cibles pendant la migration des plugins vers openclaw/plugin-sdk/channel-route
les indications d’activation remplacées par la responsabilité des contributions du manifeste
le repli vers l’environnement d’exécution de setup-api pendant la migration des descripteurs de configuration initiale vers les métadonnées à froid setup.requiresRuntime: false
les hooks discovery des fournisseurs pendant la migration des hooks de catalogue de fournisseurs vers catalog.run(...)
les métadonnées de canal showConfigured / showInSetup pendant la migration des paquets de canaux vers openclaw.channel.exposure
les anciennes clés de configuration de politique d’environnement d’exécution pendant que Doctor migre les opérateurs vers agentRuntime
le repli vers les métadonnées de configuration générées des canaux intégrés pendant le déploiement des métadonnées channelConfigs donnant la priorité au registre
les indicateurs d’environnement persistants de désactivation du registre de plugins et de migration d’installation pendant que les flux de réparation migrent les opérateurs vers openclaw plugins registry --refresh et openclaw doctor --fix
les anciens chemins de configuration de recherche Web, de récupération Web et de x_search appartenant aux plugins pendant que Doctor les migre vers plugins.entries.<plugin>.config
l’ancienne configuration rédigée plugins.installs et les alias de chemins de chargement des plugins intégrés pendant la migration des métadonnées d’installation vers le registre de plugins géré par l’état

Alias plats des rappels entrants de WhatsApp

Les rappels de l’environnement d’exécution de WhatsApp transmettent WebInboundMessage : les contextes imbriqués canoniques event, payload, quote, group et platform, ainsi que les alias plats obsolètes des champs de rappel publiés. Le nouveau code de rappel doit lire les contextes imbriqués. Le code qui construit des messages de rappel imbriqués propres peut utiliser WebInboundCallbackMessage ; les écouteurs de compatibilité qui injectent encore d’anciens messages plats de test ou de Plugin doivent utiliser LegacyFlatWebInboundMessage ou WebInboundMessageInput.

Les alias plats restent disponibles jusqu’au 2026-08-30 ; cette période s’applique uniquement à l’accès aux alias plats, et non à la structure imbriquée, qui constitue le contrat canonique de l’environnement d’exécution. L’annotation TypeScript @deprecated de chaque alias plat indique son remplacement imbriqué exact. Exemples courants :

id, timestamp et isBatched sont déplacés sous event.
body, mediaPath, mediaType, mediaFileName, mediaUrl, location et untrustedStructuredContext sont déplacés sous payload.
to, chatId, les champs d’expéditeur et d’identité propre, sendComposing, reply(...) et sendMedia(...) sont déplacés sous platform.
Les champs replyTo* sont déplacés sous quote ; les champs d’objet, de participants et de mentions de groupe sont déplacés sous group.

payload.untrustedStructuredContext est extrait des charges utiles entrantes des fournisseurs. Les plugins doivent examiner label, source et type avant de considérer son payload comme faisant autorité.

Champs d’admission entrants de WhatsApp

Les messages de rappel WhatsApp acceptés comportent admission, une enveloppe pouvant être exposée publiquement pour la décision de contrôle d’accès ayant autorisé le message. Le nouveau code de rappel doit lire les informations d’admission depuis msg.admission plutôt que depuis les anciens champs d’admission de premier niveau.

Les champs de premier niveau restent disponibles jusqu’au 2026-08-30. L’annotation TypeScript @deprecated de chaque champ indique son remplacement :

from et conversationId sont déplacés vers admission.conversation.id.
accountId est déplacé vers admission.accountId.
accessControlPassed est une vue de compatibilité dérivée de admission.ingress.decision === "allow" ; sur les messages qui comportent déjà admission, l’écriture de l’ancien booléen ne réécrit pas le graphe d’entrée.
chatType est déplacé vers admission.conversation.kind.

Paquet de l’inspecteur de plugins

L’inspecteur de plugins doit résider hors du dépôt principal d’OpenClaw sous la forme d’un paquet ou dépôt distinct fondé sur les contrats versionnés de compatibilité et de manifeste. La CLI initiale doit être :

openclaw-plugin-inspector ./my-plugin

Elle doit produire la validation du manifeste et du schéma, la version de compatibilité du contrat vérifiée, les contrôles des métadonnées d’installation et de source, les contrôles d’importation des chemins à froid, ainsi que les avertissements d’obsolescence et de compatibilité. Utilisez --json pour obtenir une sortie stable et lisible par machine dans les annotations de CI. Le cœur d’OpenClaw doit exposer les contrats et les données de test que l’inspecteur peut consommer, mais ne doit pas publier le binaire de l’inspecteur depuis le paquet principal openclaw.

Voie d’acceptation des responsables de maintenance

Utilisez Blacksmith Testbox adossé à Crabbox pour la voie d’acceptation des paquets installables lors de la validation de l’inspecteur externe par rapport aux paquets de Plugin OpenClaw. Exécutez-la depuis une copie de travail OpenClaw propre une fois le paquet compilé :

pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "pnpm install && pnpm build && npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/telegram --json"pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json"pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- <clawhub-plugin-dir> --json"

Gardez cette voie facultative pour les responsables de maintenance, car elle installe un paquet npm externe et peut inspecter des paquets de plugins clonés hors du dépôt. Les garde-fous du dépôt local couvrent la table d’exportation du SDK, les métadonnées du registre de compatibilité, la réduction progressive des imports obsolètes du SDK et les limites d’importation des extensions intégrées ; la preuve de l’inspecteur dans Testbox couvre le paquet tel que les auteurs de plugins externes l’utilisent.

Notes de publication

Les notes de publication doivent inclure les prochaines obsolescences de plugins avec leurs dates cibles et des liens vers la documentation de migration, avant qu’un chemin de compatibilité ne passe à removal-pending ou removed.

Was this useful?