Fonctionnement interne de l’architecture des Plugins

Pour le modèle public de capacités, les structures de Plugin et les contrats de propriété et d’exécution, consultez Architecture des Plugins. Cette page couvre les mécanismes internes : pipeline de chargement, registre, hooks d’exécution, routes HTTP du Gateway, chemins d’importation et tables de schéma.

Pipeline de chargement

Au démarrage, OpenClaw effectue approximativement les opérations suivantes :

1. découvrir les racines de Plugins candidates
2. lire les manifestes de paquets natifs ou compatibles et les métadonnées des paquets
3. rejeter les candidats non sécurisés
4. normaliser la configuration des Plugins (plugins.enabled, allow, deny, entries, slots, load.paths)
5. déterminer l’activation de chaque candidat
6. charger les modules natifs activés : les modules intégrés compilés utilisent un chargeur natif ; le code source TypeScript local tiers utilise le mécanisme de secours Jiti d’urgence
7. appeler les hooks natifs register(api) et collecter les enregistrements dans le registre des Plugins
8. exposer le registre aux commandes et aux surfaces d’exécution

Les contrôles de sécurité s’exécutent avant l’exécution du code. La découverte bloque un candidat lorsque :

• son point d’entrée résolu sort de la racine du Plugin
• son chemin (ou son répertoire racine) est accessible en écriture par tous
• pour les Plugins non intégrés, le propriétaire du chemin ne correspond pas à l’uid actuel (ou à root)

Pour les répertoires intégrés accessibles en écriture par tous, une tentative de réparation chmod sur place est d’abord effectuée (les installations npm/globales peuvent fournir des répertoires de paquets avec les permissions 0777) avant une nouvelle vérification ; les contrôles de propriété sont entièrement ignorés pour les origines intégrées.

Les candidats bloqués conservent néanmoins leur identifiant de Plugin dans le diagnostic émis lorsqu’il est connu (y compris les identifiants résolus depuis un manifeste situé dans un répertoire par ailleurs rejeté). Ainsi, une configuration faisant référence à cet identifiant voit un Plugin bloqué associé à un avertissement de sécurité du chemin plutôt qu’une erreur sans rapport indiquant un « Plugin inconnu ».

Comportement privilégiant le manifeste

Le manifeste constitue la source de vérité du plan de contrôle. OpenClaw l’utilise pour :

• identifier le Plugin
• découvrir les canaux, Skills, schémas de configuration ou capacités du paquet déclarés
• valider plugins.entries.<id>.config
• enrichir les libellés et textes indicatifs de la Control UI
• afficher les métadonnées d’installation et de catalogue
• conserver des descripteurs légers d’activation et de configuration sans charger le code d’exécution du Plugin

Pour les Plugins natifs, le module d’exécution constitue la partie plan de données. Il enregistre les comportements réels, tels que les hooks, les outils, les commandes ou les flux de fournisseurs.

Les blocs facultatifs activation et setup du manifeste restent dans le plan de contrôle. Il s’agit uniquement de descripteurs de métadonnées destinés à la planification de l’activation et à la découverte de la configuration ; ils ne remplacent ni l’enregistrement à l’exécution, ni register(...), ni setupEntry. Les consommateurs d’activation en direct utilisent les indications du manifeste concernant les commandes, les canaux et les fournisseurs afin de restreindre le chargement des Plugins avant une matérialisation plus large du registre :

• le chargement par la CLI se limite aux Plugins qui possèdent la commande principale demandée
• la configuration des canaux et la résolution des Plugins se limitent aux Plugins qui possèdent l’identifiant de canal demandé
• la configuration explicite d’un fournisseur et sa résolution à l’exécution se limitent aux Plugins qui possèdent l’identifiant de fournisseur demandé
• la planification du démarrage du Gateway utilise activation.onStartup pour les importations explicites au démarrage ; les Plugins dépourvus de métadonnées de démarrage ne sont chargés que par des déclencheurs d’activation plus ciblés

Le planificateur d’activation expose à la fois une API limitée aux identifiants pour les appelants existants et une API de planification pour les diagnostics. Les entrées du plan indiquent pourquoi un Plugin a été sélectionné, en distinguant les indications explicites activation.* du mécanisme de secours fondé sur la propriété déclarée dans le manifeste :

Cette distinction des motifs constitue la limite de compatibilité : les métadonnées de Plugin existantes continuent de fonctionner, tandis que le nouveau code peut détecter les indications générales ou les comportements de secours sans modifier la sémantique de chargement à l’exécution.

Les préchargements à l’exécution effectués au moment d’une requête et demandant la portée générale all continuent de dériver un ensemble explicite d’identifiants de Plugins effectifs à partir de la configuration, de la planification du démarrage, des canaux configurés, des emplacements et des règles d’activation automatique (resolveEffectivePluginIds dans src/plugins/effective-plugin-ids.ts). Si cet ensemble dérivé est vide, OpenClaw conserve une portée vide au lieu de l’élargir à tous les Plugins découvrables.

La découverte de la configuration privilégie les identifiants possédés par les descripteurs, tels que setup.providers et setup.cliBackends, afin de restreindre les Plugins candidats avant de revenir à setup-api pour les Plugins qui nécessitent encore des hooks d’exécution pendant la configuration. Les listes de configuration des fournisseurs utilisent les éléments providerAuthChoices du manifeste, les choix de configuration dérivés des descripteurs et les métadonnées du catalogue d’installation sans charger le code d’exécution du fournisseur. La valeur explicite setup.requiresRuntime: false impose un fonctionnement limité aux descripteurs ; l’omission de requiresRuntime conserve le mécanisme de secours historique setup-api à des fins de compatibilité. Si plusieurs Plugins découverts revendiquent le même identifiant normalisé de fournisseur de configuration ou de backend de CLI, la recherche de configuration refuse ce propriétaire ambigu au lieu de s’appuyer sur l’ordre de découverte. Lorsque le code de configuration s’exécute, les diagnostics du registre signalent les divergences entre setup.providers / setup.cliBackends et les fournisseurs ou backends de CLI effectivement enregistrés par setup-api, sans bloquer les Plugins historiques.

Limite du cache des Plugins

OpenClaw ne met pas en cache les résultats de découverte des Plugins ni les données directes du registre des manifestes derrière des fenêtres temporelles. Les installations, les modifications des manifestes et les changements de chemins de chargement doivent devenir visibles lors de la prochaine lecture explicite des métadonnées ou reconstruction d’un instantané. L’analyseur de fichiers manifestes conserve un cache limité de signatures de fichiers, indexé par le chemin du manifeste ouvert ainsi que par le périphérique/inode, la taille et les valeurs mtime/ctime ; ce cache évite uniquement d’analyser de nouveau des octets inchangés et ne doit pas mettre en cache les réponses relatives à la découverte, au registre, au propriétaire ou aux règles.

Le chemin rapide et sûr pour les métadonnées repose sur la propriété explicite des objets, et non sur un cache caché. Les chemins critiques au démarrage du Gateway doivent transmettre le PluginMetadataSnapshot actuel, la PluginLookUpTable dérivée ou un registre de manifestes explicite tout au long de la chaîne d’appels. La validation de la configuration, l’activation automatique au démarrage, l’amorçage des Plugins et la sélection des fournisseurs peuvent réutiliser ces objets tant qu’ils représentent la configuration et l’inventaire de Plugins actuels. La recherche de configuration reconstruit toujours les métadonnées des manifestes à la demande, sauf si le chemin de configuration concerné reçoit un registre de manifestes explicite ; conservez ce mécanisme comme solution de secours pour les chemins non critiques plutôt que d’ajouter des caches de recherche cachés. Lorsque les données d’entrée changent, reconstruisez et remplacez l’instantané au lieu de le modifier ou de conserver des copies historiques. Les vues du registre actif des Plugins et les assistants d’amorçage des canaux intégrés doivent être recalculés à partir du registre ou de la racine actuels. Des tables de correspondance de courte durée sont acceptables au sein d’un même appel pour dédupliquer le travail ou empêcher une réentrée ; elles ne doivent pas devenir des caches de métadonnées à l’échelle du processus.

Pour le chargement des Plugins, la couche de cache persistante concerne le chargement à l’exécution. Elle peut réutiliser l’état du chargeur lorsque le code ou les artefacts installés sont effectivement chargés, notamment :

• PluginLoaderCacheState et les registres actifs compatibles à l’exécution
• les caches jiti/de modules et les caches de chargeur des surfaces publiques utilisés pour éviter d’importer plusieurs fois la même surface d’exécution
• les caches du système de fichiers pour les artefacts de Plugins installés
• les tables de correspondance de courte durée propres à un appel pour la normalisation des chemins ou la résolution des doublons

Ces caches sont des détails d’implémentation du plan de données. Ils ne doivent pas répondre à des questions du plan de contrôle telles que « quel Plugin possède ce fournisseur ? », sauf si l’appelant a délibérément demandé un chargement à l’exécution.

N’ajoutez pas de caches persistants ou temporels pour :

• les résultats de découverte
• les registres directs des manifestes
• les registres de manifestes reconstruits à partir de l’index des Plugins installés
• la recherche du propriétaire d’un fournisseur, la suppression de modèles, les règles des fournisseurs ou les métadonnées des artefacts publics
• toute autre réponse dérivée d’un manifeste pour laquelle un manifeste, un index installé ou un chemin de chargement modifié doit être visible lors de la prochaine lecture des métadonnées

Les appelants qui reconstruisent les métadonnées des manifestes à partir de l’index persistant des Plugins installés reconstruisent ce registre à la demande. L’index installé constitue un état durable du plan source ; il ne s’agit pas d’un cache caché de métadonnées en mémoire du processus.

Modèle de registre

Les Plugins chargés ne modifient pas directement des variables globales arbitraires du cœur. Ils s’enregistrent dans un registre central de Plugins (PluginRegistry dans src/plugins/registry-types.ts), qui suit les enregistrements des Plugins (identité, source, origine, état, diagnostics), ainsi que des tableaux pour chaque capacité : outils, hooks historiques et hooks typés, canaux, fournisseurs, gestionnaires RPC du Gateway, routes HTTP, registraires de CLI, services en arrière-plan, commandes possédées par les Plugins et des dizaines d’autres familles typées de fournisseurs (parole, embeddings, génération d’images, de vidéos et de musique, récupération et recherche web, environnements d’agents, actions de session, etc.).

Les fonctionnalités du cœur lisent ensuite ce registre au lieu de communiquer directement avec les modules de Plugins. Le chargement reste ainsi unidirectionnel :

• module de Plugin -> enregistrement dans le registre
• exécution du cœur -> consommation du registre

Cette séparation est importante pour la maintenabilité. Elle signifie que la plupart des surfaces du cœur ne nécessitent qu’un seul point d’intégration : « lire le registre », plutôt que « traiter chaque module de Plugin comme un cas particulier ».

Rappels de liaison de conversation

Les Plugins qui lient une conversation peuvent réagir lorsqu’une approbation est résolue.

Utilisez api.onConversationBindingResolved(...) pour recevoir un rappel après l’approbation ou le refus d’une demande de liaison :

export default {  id: "my-plugin",  register(api) {    api.onConversationBindingResolved(async (event) => {      if (event.status === "approved") {        // A binding now exists for this plugin + conversation.        console.log(event.binding?.conversationId);        return;      }       // The request was denied; clear any local pending state.      console.log(event.request.conversation.conversationId);    });  },};

Champs de la charge utile du rappel :

• status : "approved" ou "denied"
• decision : "allow-once", "allow-always" ou "deny"
• binding : la liaison résolue pour les demandes approuvées
• request : le résumé de la demande d’origine, l’indication de dissociation, l’identifiant de l’expéditeur et les métadonnées de la conversation

Ce rappel sert uniquement de notification. Il ne modifie pas les personnes autorisées à lier une conversation et s’exécute une fois le traitement de l’approbation par le cœur terminé.

Hooks d’exécution des fournisseurs

Les Plugins de fournisseurs comportent trois couches :

• Métadonnées du manifeste pour une recherche légère avant l’exécution : setup.providers[].envVars, l’élément de compatibilité obsolète providerAuthEnvVars, providerAuthAliases, providerAuthChoices et channelEnvVars.
• Hooks lors de la configuration : catalog (anciennement discovery) ainsi que applyConfigDefaults.
• Hooks d’exécution : plus de 40 hooks facultatifs couvrant l’authentification, la résolution des modèles, l’encapsulation des flux, les niveaux de raisonnement, les règles de relecture et les points de terminaison d’utilisation. Consultez Ordre et utilisation des hooks.

OpenClaw reste responsable de la boucle d’agent générique, du basculement, du traitement des transcriptions et des règles relatives aux outils. Ces hooks constituent la surface d’extension destinée aux comportements propres aux fournisseurs, sans nécessiter un transport d’inférence entièrement personnalisé.

Utilisez setup.providers[].envVars dans le manifeste lorsque le fournisseur dispose d’identifiants basés sur des variables d’environnement que les parcours génériques d’authentification, d’état et de sélection de modèle doivent pouvoir consulter sans charger l’exécution du Plugin. Le champ obsolète providerAuthEnvVars reste lu par l’adaptateur de compatibilité pendant la période d’abandon progressif, et les plugins non intégrés qui l’utilisent reçoivent un diagnostic de manifeste. Utilisez providerAuthAliases dans le manifeste lorsqu’un identifiant de fournisseur doit réutiliser les variables d’environnement, les profils d’authentification, l’authentification issue de la configuration et le choix d’intégration par clé d’API d’un autre identifiant de fournisseur. Utilisez providerAuthChoices dans le manifeste lorsque les interfaces CLI d’intégration et de choix d’authentification doivent connaître l’identifiant du choix du fournisseur, les libellés de groupe et la configuration simple de l’authentification par un seul indicateur, sans charger l’exécution du fournisseur. Conservez les envVars de l’exécution du fournisseur pour les indications destinées aux opérateurs, telles que les libellés d’intégration ou les variables de configuration de l’identifiant et du secret client OAuth.

Utilisez channelEnvVars dans le manifeste lorsqu’un canal dispose d’une authentification ou d’une configuration pilotée par des variables d’environnement que la solution de repli générique vers l’environnement de l’interpréteur de commandes, les vérifications de configuration ou d’état, ou les invites de configuration doivent pouvoir consulter sans charger l’exécution du canal.

Ordre et utilisation des hooks

Pour les plugins de modèle ou de fournisseur, OpenClaw appelle les hooks approximativement dans cet ordre. La colonne « Quand l’utiliser » constitue le guide de décision rapide. Les champs de fournisseur réservés à la compatibilité qu’OpenClaw n’appelle plus, tels que ProviderPlugin.capabilities et suppressBuiltInModel, ne sont volontairement pas répertoriés ici.

normalizeModelId, normalizeTransport et normalizeConfig vérifient d’abord le Plugin de fournisseur correspondant, puis parcourent les autres Plugins de fournisseur prenant en charge les hooks jusqu’à ce que l’un d’eux modifie réellement l’identifiant du modèle, le transport ou la configuration. Cela permet aux adaptateurs de fournisseur d’alias ou de compatibilité de continuer à fonctionner sans que l’appelant ait besoin de savoir quel Plugin intégré est responsable de la réécriture. Si aucun hook de fournisseur ne réécrit une entrée de configuration prise en charge de la famille Google, le normalisateur de configuration Google intégré applique tout de même ce nettoyage de compatibilité.

Si le fournisseur nécessite un protocole filaire entièrement personnalisé ou un exécuteur de requêtes personnalisé, il s’agit d’une autre catégorie d’extension. Ces hooks sont destinés au comportement des fournisseurs qui s’exécute toujours dans la boucle d’inférence normale d’OpenClaw.

resolveUsageAuth détermine si OpenClaw doit appeler fetchUsageSnapshot ou revenir à la résolution générique des identifiants pour les interfaces d’utilisation et d’état. Renvoyez { token, accountId?, subscriptionType?, rateLimitTier? } lorsque le fournisseur dispose d’un identifiant d’utilisation (les métadonnées facultatives du forfait sont transmises à fetchUsageSnapshot), renvoyez { handled: true } lorsque l’authentification d’utilisation gérée par le fournisseur a traité la requête et doit empêcher le repli générique vers une clé d’API ou OAuth, et renvoyez null ou undefined lorsque le fournisseur n’a pas traité l’authentification d’utilisation.

Déclarez les identifiants d’organisation ou de facturation dans providerUsageAuthEnvVars du manifeste. Cela permet aux mécanismes génériques de détection et de nettoyage des secrets de les reconnaître sans en faire des candidats à l’authentification d’inférence.

Exemple de fournisseur

api.registerProvider({  id: "example-proxy",  label: "Example Proxy",  auth: [],  catalog: {    order: "simple",    run: async (ctx) => {      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;      if (!apiKey) {        return null;      }      return {        provider: {          baseUrl: "https://proxy.example.com/v1",          apiKey,          api: "openai-completions",          models: [{ id: "auto", name: "Auto" }],        },      };    },  },  resolveDynamicModel: (ctx) => ({    id: ctx.modelId,    name: ctx.modelId,    provider: "example-proxy",    api: "openai-completions",    baseUrl: "https://proxy.example.com/v1",    reasoning: false,    input: ["text"],    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },    contextWindow: 128000,    maxTokens: 8192,  }),  prepareRuntimeAuth: async (ctx) => {    const exchanged = await exchangeToken(ctx.apiKey);    return {      apiKey: exchanged.token,      baseUrl: exchanged.baseUrl,      expiresAt: exchanged.expiresAt,    };  },  resolveUsageAuth: async (ctx) => {    const auth = await ctx.resolveOAuthToken();    return auth ? { token: auth.token } : null;  },  fetchUsageSnapshot: async (ctx) => {    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);  },});

Exemples intégrés

Les Plugins de fournisseur intégrés combinent les hooks ci-dessus pour répondre aux besoins de chaque fournisseur en matière de catalogue, d’authentification, de raisonnement, de relecture et d’utilisation. L’ensemble de hooks faisant autorité réside avec chaque Plugin sous extensions/ ; cette page illustre leurs structures plutôt que de reproduire la liste.

Assistants d’exécution

Les Plugins peuvent accéder à certains assistants du cœur via api.runtime. Pour la synthèse vocale :

const clip = await api.runtime.tts.textToSpeech({  text: "Hello from OpenClaw",  cfg: api.config,}); const result = await api.runtime.tts.textToSpeechTelephony({  text: "Hello from OpenClaw",  cfg: api.config,}); const voices = await api.runtime.tts.listVoices({  provider: "elevenlabs",  cfg: api.config,});

Remarques :

• textToSpeech renvoie la charge utile de sortie TTS normale du cœur pour les interfaces de fichiers et de notes vocales.
• Utilise la configuration centrale messages.tts et la sélection du fournisseur.
• Renvoie un tampon audio PCM et une fréquence d’échantillonnage. Les Plugins doivent rééchantillonner et encoder les données pour les fournisseurs.
• listVoices est facultatif pour chaque fournisseur. Utilisez-le pour les sélecteurs de voix ou les parcours de configuration propres au fournisseur.
• Le cœur transmet une échéance de requête résolue aux hooks listVoices des fournisseurs ; les paramètres de délai d’expiration propres au fournisseur peuvent la remplacer.
• Les listes de voix peuvent inclure des métadonnées plus riches, telles que la langue, le genre et des étiquettes de personnalité, pour les sélecteurs tenant compte du fournisseur.
• OpenAI et ElevenLabs prennent actuellement en charge la téléphonie. Microsoft ne la prend pas en charge.

Les Plugins peuvent également enregistrer des fournisseurs vocaux via api.registerSpeechProvider(...).

api.registerSpeechProvider({  id: "acme-speech",  label: "Acme Speech",  isConfigured: ({ config }) => Boolean(config.messages?.tts),  synthesize: async (req) => {    return {      audioBuffer: Buffer.from([]),      outputFormat: "mp3",      fileExtension: ".mp3",      voiceCompatible: false,    };  },});

Remarques :

• Conservez la politique TTS, le repli et la remise des réponses dans le cœur.
• Utilisez les fournisseurs vocaux pour le comportement de synthèse propre au fournisseur.
• L’entrée Microsoft héritée edge est normalisée vers l’identifiant de fournisseur microsoft.
• Le modèle de responsabilité privilégié est organisé par entreprise : un seul Plugin de fournisseur peut gérer les fournisseurs de texte, de parole, d’image et de futurs médias à mesure qu’OpenClaw ajoute ces contrats de capacités.

Pour la compréhension des images, de l’audio et de la vidéo, les Plugins enregistrent un fournisseur typé de compréhension multimédia plutôt qu’un ensemble générique de paires clé-valeur :

api.registerMediaUnderstandingProvider({  id: "google",  capabilities: ["image", "audio", "video"],  describeImage: async (req) => ({ text: "..." }),  transcribeAudio: async (req) => ({ text: "..." }),  describeVideo: async (req) => ({ text: "..." }),});

Remarques :

• Conservez l’orchestration, le repli, la configuration et le raccordement aux canaux dans le cœur.
• Conservez le comportement propre au fournisseur dans le Plugin de fournisseur.
• Les extensions additives doivent rester typées : nouvelles méthodes facultatives, nouveaux champs de résultat facultatifs et nouvelles capacités facultatives.
• La génération vidéo suit déjà le même modèle :
  • le cœur gère le contrat de capacité et l’assistant d’exécution
  • les Plugins de fournisseur enregistrent api.registerVideoGenerationProvider(...)
  • les Plugins de fonctionnalité ou de canal utilisent api.runtime.videoGeneration.*

Pour les assistants d’exécution de compréhension multimédia, les Plugins peuvent appeler :

const image = await api.runtime.mediaUnderstanding.describeImageFile({  filePath: "/tmp/inbound-photo.jpg",  cfg: api.config,  agentDir: "/tmp/agent",}); const video = await api.runtime.mediaUnderstanding.describeVideoFile({  filePath: "/tmp/inbound-video.mp4",  cfg: api.config,}); const extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({  provider: "codex",  model: "gpt-5.6-sol",  input: [    {      type: "image",      buffer: receiptImageBuffer,      fileName: "receipt.png",      mime: "image/png",    },    { type: "text", text: "Use the printed fields as the source of truth." },  ],  instructions: "Return entities and searchable tags.",  schemaName: "example.evidence",  jsonSchema: {    type: "object",    properties: {      entities: { type: "array", items: { type: "string" } },      tags: { type: "array", items: { type: "string" } },    },  },  cfg: api.config,});

Pour la transcription audio, les Plugins peuvent utiliser soit l’environnement d’exécution de compréhension multimédia, soit l’ancien alias STT :

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({  filePath: "/tmp/inbound-audio.ogg",  cfg: api.config,  // Optional when MIME cannot be inferred reliably:  mime: "audio/ogg",});

Remarques :

• api.runtime.mediaUnderstanding.* est l’interface partagée privilégiée pour la compréhension des images, de l’audio et de la vidéo.
• extractStructuredWithModel(...) est l’interface destinée aux Plugins pour une extraction bornée, axée sur les images et gérée par le fournisseur. Incluez au moins une entrée d’image ; les entrées textuelles fournissent un contexte complémentaire. Les Plugins produit gèrent leurs routes et leurs schémas, tandis qu’OpenClaw gère la frontière entre le fournisseur et l’environnement d’exécution.
• Utilise la configuration audio centrale de compréhension multimédia (tools.media.audio) et l’ordre de repli des fournisseurs.
• Renvoie { text: undefined } lorsqu’aucune transcription n’est produite, par exemple pour une entrée ignorée ou non prise en charge.
• api.runtime.stt.transcribeAudioFile(...) reste disponible comme alias de compatibilité.

Les Plugins peuvent également lancer des exécutions de sous-agents en arrière-plan via api.runtime.subagent :

const result = await api.runtime.subagent.run({  sessionKey: "agent:main:subagent:search-helper",  message: "Expand this query into focused follow-up searches.",  provider: "openai",  model: "gpt-4.1-mini",  deliver: false,});

Remarques :

• provider et model sont des substitutions facultatives propres à chaque exécution, et non des modifications persistantes de la session.
• OpenClaw n’honore ces champs de substitution que pour les appelants de confiance.
• Pour les exécutions de repli gérées par un Plugin, les opérateurs doivent les autoriser avec plugins.entries.<id>.subagent.allowModelOverride: true.
• Utilisez plugins.entries.<id>.subagent.allowedModels pour limiter les Plugins de confiance à des cibles canoniques provider/model précises, ou "*" pour autoriser explicitement n’importe quelle cible.
• Les exécutions de sous-agents provenant de Plugins non fiables continuent de fonctionner, mais les demandes de substitution sont rejetées au lieu d’utiliser silencieusement un repli.
• Les sessions de sous-agents créées par un Plugin sont étiquetées avec l’identifiant du Plugin créateur. La méthode de repli api.runtime.subagent.deleteSession(...) ne peut supprimer que ces sessions détenues ; la suppression de sessions arbitraires nécessite toujours une requête Gateway avec une portée d’administration.

Pour la recherche sur le Web, les Plugins peuvent utiliser l’assistant d’exécution partagé au lieu d’accéder directement au raccordement des outils de l’agent :

const providers = api.runtime.webSearch.listProviders({  config: api.config,}); const result = await api.runtime.webSearch.search({  config: api.config,  args: {    query: "OpenClaw plugin runtime helpers",    count: 5,  },});

Les Plugins peuvent également enregistrer des fournisseurs de recherche sur le Web via api.registerWebSearchProvider(...).

Remarques :

• Conservez la sélection du fournisseur, la résolution des identifiants et la sémantique partagée des requêtes dans le cœur.
• Utilisez les fournisseurs de recherche sur le Web pour les transports de recherche propres au fournisseur.
• api.runtime.webSearch.* est l’interface partagée privilégiée pour les Plugins de fonctionnalité ou de canal qui nécessitent une fonction de recherche sans dépendre de l’adaptateur d’outil de l’agent.

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({  config: api.config,  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },}); const providers = api.runtime.imageGeneration.listProviders({  config: api.config,});

• generate(...) : génère une image à l’aide de la chaîne de fournisseurs de génération d’images configurée.
• listProviders(...) : répertorie les fournisseurs de génération d’images disponibles et leurs capacités.

Routes HTTP du Gateway

Les Plugins peuvent exposer des points de terminaison HTTP avec api.registerHttpRoute(...).

api.registerHttpRoute({  path: "/acme/webhook",  auth: "plugin",  match: "exact",  handler: async (_req, res) => {    res.statusCode = 200;    res.end("ok");    return true;  },});

Champs de la route :

• path : chemin de la route sur le serveur HTTP du Gateway.
• auth : obligatoire, "gateway" ou "plugin". Utilisez "gateway" pour exiger l’authentification normale du Gateway, ou "plugin" pour une authentification ou une vérification de Webhook gérée par le plugin.
• match : facultatif. "exact" (par défaut) ou "prefix".
• handleUpgrade : gestionnaire facultatif pour les requêtes de mise à niveau WebSocket sur la même route.
• replaceExisting : facultatif. Autorise le même plugin à remplacer son propre enregistrement de route existant.
• handler : renvoyez true lorsque la route a traité la requête.

Remarques :

• api.registerHttpHandler(...) a été supprimé et provoquera une erreur de chargement du plugin. Utilisez plutôt api.registerHttpRoute(...).
• Les routes des plugins doivent déclarer explicitement auth.
• Les conflits portant sur une même combinaison path + match sont rejetés sauf avec replaceExisting: true, et un plugin ne peut pas remplacer la route d’un autre plugin.
• Les routes qui se chevauchent avec des niveaux auth différents sont rejetées. Les chaînes de repli exact/prefix doivent uniquement utiliser le même niveau d’authentification.
• Les routes avec auth: "plugin" ne reçoivent pas automatiquement les portées d’exécution de l’opérateur. Elles sont destinées aux Webhooks et à la vérification des signatures gérés par les plugins, et non aux appels privilégiés aux fonctions auxiliaires du Gateway.
• Les routes avec auth: "gateway" s’exécutent dans une portée d’exécution de requête du Gateway. La surface par défaut (gatewayRuntimeScopeSurface: "write-default") est volontairement restrictive :
  • l’authentification par secret partagé de type bearer (gateway.auth.mode = "token" / "password") et toute méthode d’authentification autre que par proxy de confiance obtiennent une unique portée operator.write, même si l’appelant envoie x-openclaw-scopes
  • les appelants trusted-proxy sans en-tête x-openclaw-scopes explicite conservent également l’ancienne surface limitée à operator.write
  • les appelants trusted-proxy qui envoient x-openclaw-scopes obtiennent à la place les portées déclarées
  • une route peut choisir gatewayRuntimeScopeSurface: "trusted-operator" afin de toujours respecter x-openclaw-scopes pour les modes d’authentification associés à une identité (avec repli sur l’ensemble complet des portées par défaut de la CLI lorsque l’en-tête est absent)
• Règle pratique : ne supposez pas qu’une route de plugin authentifiée par le Gateway constitue implicitement une surface d’administration. Si votre route nécessite un comportement réservé aux administrateurs, choisissez la surface de portée trusted-operator, exigez un mode d’authentification associé à une identité et documentez le contrat explicite de l’en-tête x-openclaw-scopes.
• Après la correspondance de la route et l’authentification, les gestionnaires ordinaires participent au contrôle d’admission du travail racine du Gateway. Un Gateway préparé ou en cours de redémarrage renvoie 503 avant d’appeler le gestionnaire. La seule exception restreinte est une route avec auth: "gateway", autorisée par le manifeste, qui choisit également la surface trusted-operator propre à la route ; elle reste accessible afin que la distribution des commandes de suspension ne soit pas bloquée, tandis que les routes sœurs ordinaires du même plugin restent derrière la limite d’admission. La propriété WebSocket de handleUpgrade utilise la même limite d’admission atomique ; dès que le gestionnaire accepte un socket, la durée de vie ultérieure de celui-ci relève du plugin et n’est pas suivie par cette limite.

Chemins d’importation du SDK des plugins

Utilisez les sous-chemins ciblés du SDK plutôt que le barrel racine monolithique openclaw/plugin-sdk lors de la création de nouveaux plugins. Sous-chemins principaux :

Les plugins de canaux choisissent parmi une famille d’interfaces ciblées — channel-setup, setup-runtime, setup-tools, channel-pairing, channel-contract, channel-feedback, channel-inbound, channel-outbound, command-auth, secret-input, webhook-ingress, channel-targets et channel-actions. Le comportement d’approbation doit être regroupé dans un seul contrat approvalCapability, au lieu d’être réparti entre des champs de plugin sans rapport. Consultez Plugins de canaux.

Les fonctions auxiliaires d’exécution et de configuration se trouvent sous les sous-chemins ciblés *-runtime correspondants (approval-runtime, agent-runtime, lazy-runtime, directory-runtime, text-runtime, runtime-store, system-event-runtime, heartbeat-runtime, channel-activity-runtime, etc.). Préférez config-contracts, plugin-config-runtime, runtime-config-snapshot et config-mutation au barrel de compatibilité général config-runtime.

Points d’entrée internes au dépôt (à la racine du paquet de chaque plugin intégré) :

• index.js — point d’entrée du plugin intégré
• api.js — barrel des fonctions auxiliaires et des types
• runtime-api.js — barrel réservé à l’exécution
• setup-entry.js — point d’entrée de configuration du plugin

Les plugins externes doivent uniquement importer les sous-chemins openclaw/plugin-sdk/*. N’importez jamais le chemin src/* du paquet d’un autre plugin depuis le cœur ou un autre plugin. Les points d’entrée chargés par une façade privilégient l’instantané actif de la configuration d’exécution lorsqu’il existe, puis se rabattent sur le fichier de configuration résolu sur le disque.

Les sous-chemins propres à une capacité, tels que image-generation, media-understanding et speech, existent parce que les plugins intégrés les utilisent actuellement. Ils ne constituent pas automatiquement des contrats externes figés à long terme — consultez la page de référence du SDK concernée avant de vous appuyer sur eux.

Schémas de l’outil de messagerie

Les plugins doivent prendre en charge les contributions de schéma describeMessageTool(...) propres aux canaux pour les primitives autres que les messages, telles que les réactions, les lectures et les sondages. La présentation partagée des envois doit utiliser le contrat générique MessagePresentation au lieu de champs de boutons, composants, blocs ou cartes propres aux fournisseurs. Consultez Présentation des messages pour le contrat, les règles de repli, la correspondance avec les fournisseurs et la liste de contrôle destinée aux auteurs de plugins.

Les plugins capables d’envoyer des messages déclarent ce qu’ils peuvent afficher au moyen des capacités de messagerie :

• presentation pour les blocs de présentation sémantiques (text, context, divider, chart, table, buttons, select)
• delivery-pin pour les demandes de livraison épinglée

Le cœur décide s’il doit afficher la présentation de manière native ou la dégrader en texte. N’exposez pas de mécanismes d’échappement d’interface utilisateur propres aux fournisseurs depuis l’outil de messagerie générique. Les fonctions auxiliaires obsolètes du SDK pour les anciens schémas natifs restent exportées pour les plugins tiers existants, mais les nouveaux plugins ne doivent pas les utiliser.

Résolution des cibles de canal

Les plugins de canaux doivent prendre en charge la sémantique des cibles propre à chaque canal. Gardez l’hôte sortant partagé générique et utilisez la surface de l’adaptateur de messagerie pour les règles du fournisseur :

• messaging.inferTargetChatType({ to }) détermine si une cible normalisée doit être traitée comme direct, group ou channel avant la recherche dans l’annuaire.
• messaging.targetResolver.looksLikeId(raw, normalized) indique au cœur si une entrée doit passer directement à une résolution de type identifiant plutôt qu’à une recherche dans l’annuaire.
• messaging.targetResolver.reservedLiterals répertorie les mots nus qui constituent des références à un canal ou à une session pour ce fournisseur. La résolution conserve les entrées d’annuaire configurées avant de rejeter les littéraux réservés, puis échoue de manière fermée si la recherche dans l’annuaire n’aboutit pas.
• messaging.targetResolver.resolveTarget(...) constitue le mécanisme de repli du plugin lorsque le cœur a besoin d’une résolution finale appartenant au fournisseur après la normalisation ou après l’échec d’une recherche dans l’annuaire.
• messaging.resolveOutboundSessionRoute(...) prend en charge la construction de la route de session propre au fournisseur une fois la cible résolue.

Répartition recommandée :

• Utilisez inferTargetChatType pour les décisions de catégorie qui doivent intervenir avant la recherche de correspondants ou de groupes.
• Utilisez looksLikeId pour les vérifications du type « traiter ceci comme un identifiant de cible explicite ou natif ».
• Utilisez resolveTarget comme mécanisme de repli de normalisation propre au fournisseur, et non pour une recherche générale dans l’annuaire.
• Conservez les identifiants natifs du fournisseur, tels que les identifiants de discussion, de fil de discussion, les JID, les pseudonymes et les identifiants de salon, dans les valeurs target ou les paramètres propres au fournisseur, et non dans les champs génériques du SDK.

Annuaires fondés sur la configuration

Les plugins qui dérivent des entrées d’annuaire de la configuration doivent conserver cette logique dans le plugin et réutiliser les fonctions auxiliaires partagées de openclaw/plugin-sdk/directory-runtime.

Utilisez cette approche lorsqu’un canal nécessite des correspondants ou groupes issus de la configuration, tels que :

• les correspondants de messages privés déterminés par une liste d’autorisation
• les mappages configurés de canaux ou de groupes
• les mécanismes de repli d’annuaire statiques limités à un compte

Les fonctions auxiliaires partagées de directory-runtime prennent uniquement en charge les opérations génériques :

• filtrage des requêtes
• application des limites
• fonctions auxiliaires de déduplication et de normalisation
• création de ChannelDirectoryEntry[]

L’inspection des comptes et la normalisation des identifiants propres à chaque canal doivent rester dans l’implémentation du plugin.

Catalogues des fournisseurs

Les plugins de fournisseurs peuvent définir des catalogues de modèles pour l’inférence avec registerProvider({ catalog: { run(...) { ... } } }).

catalog.run(...) renvoie la même structure que celle écrite par OpenClaw dans models.providers :

• { provider } pour une entrée de fournisseur
• { providers } pour plusieurs entrées de fournisseurs

Utilisez catalog lorsque le plugin prend en charge les identifiants de modèles propres au fournisseur, les valeurs par défaut de l’URL de base ou les métadonnées de modèles soumises à une authentification.

catalog.order détermine le moment où le catalogue d’un plugin est fusionné par rapport aux fournisseurs implicites intégrés d’OpenClaw :

• simple : fournisseurs utilisant une simple clé d’API ou pilotés par l’environnement
• profile : fournisseurs qui apparaissent lorsque des profils d’authentification existent
• paired : fournisseurs qui synthétisent plusieurs entrées de fournisseurs liées
• late : dernière passe, après les autres fournisseurs implicites

Les fournisseurs les plus tardifs l’emportent en cas de collision de clés ; les plugins peuvent donc remplacer volontairement une entrée de fournisseur intégrée possédant le même identifiant de fournisseur.

Les plugins peuvent également publier des lignes de modèles en lecture seule au moyen de api.registerModelCatalogProvider({ provider, kinds, staticCatalog, liveCatalog }). Il s’agit de la voie à privilégier pour les surfaces de liste, d’aide et de sélection ; elle prend en charge les lignes text, voice, image_generation, video_generation et music_generation. Les plugins de fournisseurs restent responsables des appels aux points de terminaison en direct, de l’échange des jetons et de la correspondance des réponses du fournisseur ; le cœur prend en charge la structure commune des lignes, les libellés de source et la mise en forme de l’aide des outils multimédias. Les enregistrements de fournisseurs de génération multimédia synthétisent automatiquement des lignes de catalogue statiques à partir de defaultModel, models et capabilities.

Compatibilité :

• discovery fonctionne encore comme ancien alias, mais émet un avertissement d’obsolescence
• si catalog et discovery sont tous deux enregistrés, OpenClaw utilise catalog et émet un avertissement
• augmentModelCatalog est obsolète ; les fournisseurs intégrés doivent publier les lignes supplémentaires au moyen de registerModelCatalogProvider

Inspection des canaux en lecture seule

Si votre plugin enregistre un canal, implémentez de préférence plugin.config.inspectAccount(cfg, accountId) parallèlement à resolveAccount(...).

Pourquoi :

• resolveAccount(...) correspond au chemin d’exécution. Il peut supposer que les identifiants sont entièrement matérialisés et échouer immédiatement lorsque les secrets requis sont absents.
• Les chemins de commandes en lecture seule, tels que openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, ainsi que les flux de réparation de doctor ou de la configuration, ne doivent pas avoir à matérialiser les identifiants d’exécution uniquement pour décrire la configuration.

Comportement recommandé de inspectAccount(...) :

• Renvoyez uniquement un état descriptif du compte.
• Préservez enabled et configured.
• Incluez les champs de source/d’état des identifiants lorsque cela est pertinent, tels que :
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Vous n’avez pas besoin de renvoyer les valeurs brutes des jetons uniquement pour signaler leur disponibilité en lecture seule. Renvoyer tokenStatus: "available" (ainsi que le champ de source correspondant) suffit pour les commandes de type état.
• Utilisez configured_unavailable lorsqu’un identifiant est configuré via SecretRef, mais indisponible dans le chemin d’exécution de la commande actuelle.

Cela permet aux commandes en lecture seule d’indiquer « configuré, mais indisponible dans ce chemin d’exécution de commande » au lieu de planter ou de signaler à tort que le compte n’est pas configuré.

Paquets groupés

Un répertoire de Plugin peut inclure un fichier package.json avec openclaw.extensions :

{  "name": "my-pack",  "openclaw": {    "extensions": ["./src/safety.ts", "./src/tools.ts"],    "setupEntry": "./src/setup-entry.ts"  }}

Chaque entrée devient un Plugin. Si le paquet répertorie plusieurs extensions, l’identifiant du Plugin devient <manifestOrPackageName>/<fileBase> (l’identifiant du manifeste prévaut lorsqu’il est présent ; sinon, le nom non délimité par une portée du fichier package.json est utilisé).

Si votre Plugin importe des dépendances npm, installez-les dans ce répertoire afin que node_modules soit disponible (npm install / pnpm install).

Mesure de sécurité : chaque entrée openclaw.extensions doit rester dans le répertoire du Plugin après la résolution des liens symboliques. Les entrées qui sortent du répertoire du paquet sont rejetées.

Remarque de sécurité : openclaw plugins install installe les dépendances du Plugin avec une commande npm install --omit=dev --ignore-scripts locale au projet (aucun script de cycle de vie et aucune dépendance de développement à l’exécution), en ignorant les paramètres d’installation npm globaux hérités. Veillez à ce que les arborescences de dépendances des Plugins soient « exclusivement en JS/TS » et évitez les paquets qui nécessitent des compilations postinstall.

Facultatif : openclaw.setupEntry peut pointer vers un module léger réservé à la configuration. Lorsqu’OpenClaw a besoin des surfaces de configuration d’un Plugin de canal désactivé, ou lorsqu’un Plugin de canal est activé mais pas encore configuré, il charge setupEntry au lieu de l’entrée complète du Plugin. Cela allège le démarrage et la configuration lorsque l’entrée principale de votre Plugin raccorde également des outils, des hooks ou d’autres éléments de code réservés à l’exécution.

Facultatif : openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen peut permettre à un Plugin de canal d’utiliser le même chemin setupEntry pendant la phase de démarrage du Gateway précédant la mise en écoute, même lorsque le canal est déjà configuré.

Utilisez cette option uniquement lorsque setupEntry couvre entièrement la surface de démarrage qui doit exister avant que le Gateway commence à écouter. En pratique, cela signifie que l’entrée de configuration doit enregistrer chaque capacité appartenant au canal dont dépend le démarrage, telle que :

• l’enregistrement du canal lui-même
• toutes les routes HTTP qui doivent être disponibles avant que le Gateway commence à écouter
• toutes les méthodes, tous les outils ou tous les services du Gateway qui doivent exister pendant cette même période

Si votre entrée complète possède encore une capacité requise au démarrage, n’activez pas cette option. Conservez le comportement par défaut du Plugin et laissez OpenClaw charger l’entrée complète pendant le démarrage.

Les canaux intégrés peuvent également publier des fonctions d’assistance de surface contractuelle réservées à la configuration, que le cœur peut consulter avant le chargement de l’environnement d’exécution complet du canal. La surface de promotion de configuration actuelle est :

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

Le cœur utilise cette surface lorsqu’il doit promouvoir une configuration de canal historique à compte unique vers channels.<id>.accounts.* sans charger l’entrée complète du Plugin. Matrix constitue l’exemple intégré actuel : il déplace uniquement les clés d’authentification et d’amorçage vers un compte nommé promu lorsque des comptes nommés existent déjà, et peut préserver une clé configurée de compte par défaut non canonique au lieu de toujours créer accounts.default.

Ces adaptateurs de correctifs de configuration maintiennent différée la découverte des surfaces contractuelles intégrées. Le temps d’importation reste faible ; la surface de promotion n’est chargée qu’à sa première utilisation, au lieu de réexécuter le démarrage du canal intégré lors de l’importation du module.

Lorsque ces surfaces de démarrage comprennent des méthodes RPC du Gateway, conservez-les sous un préfixe propre au Plugin. Les espaces de noms d’administration du cœur (config.*, exec.approvals.*, wizard.*, update.*) restent réservés et correspondent toujours à operator.admin, même si un Plugin demande une portée plus restreinte.

Exemple :

{  "name": "@scope/my-channel",  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "startup": {      "deferConfiguredChannelFullLoadUntilAfterListen": true    }  }}

Métadonnées du catalogue de canaux

Les Plugins de canal peuvent publier des métadonnées de configuration et de découverte via openclaw.channel, ainsi que des indications d’installation via openclaw.install. Cela évite de stocker les données du catalogue dans le cœur.

Exemple :

{  "name": "@openclaw/nextcloud-talk",  "openclaw": {    "extensions": ["./index.ts"],    "channel": {      "id": "nextcloud-talk",      "label": "Nextcloud Talk",      "selectionLabel": "Nextcloud Talk (self-hosted)",      "docsPath": "/channels/nextcloud-talk",      "docsLabel": "nextcloud-talk",      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",      "order": 65,      "aliases": ["nc-talk", "nc"]    },    "install": {      "npmSpec": "@openclaw/nextcloud-talk",      "localPath": "<bundled-plugin-local-path>",      "defaultChoice": "npm"    }  }}

Champs openclaw.channel utiles au-delà de l’exemple minimal :

• detailLabel : libellé secondaire pour les surfaces enrichies de catalogue et d’état
• docsLabel : remplace le texte du lien vers la documentation
• preferOver : identifiants de Plugins ou de canaux de moindre priorité que cette entrée de catalogue doit devancer
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras : réglages du texte de la surface de sélection
• markdownCapable : indique que le canal prend en charge Markdown pour les décisions de mise en forme des messages sortants
• exposure.configured : masque le canal dans les surfaces répertoriant les canaux configurés lorsque la valeur est false
• exposure.setup : masque le canal dans les sélecteurs interactifs de configuration lorsqu’elle est définie sur false
• exposure.docs : marque le canal comme interne ou privé pour les surfaces de navigation de la documentation
• showConfigured / showInSetup : anciens alias encore acceptés à des fins de compatibilité ; préférez exposure
• quickstartAllowFrom : permet au canal d’utiliser le flux allowFrom standard de démarrage rapide
• forceAccountBinding : exige une association explicite du compte même lorsqu’il n’existe qu’un seul compte
• preferSessionLookupForAnnounceTarget : privilégie la recherche de session lors de la résolution des cibles d’annonce

OpenClaw peut également fusionner des catalogues de canaux externes (par exemple, une exportation de registre MPM). Déposez un fichier JSON à l’un des emplacements suivants :

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

Ou faites pointer OPENCLAW_PLUGIN_CATALOG_PATHS (ou OPENCLAW_MPM_CATALOG_PATHS) vers un ou plusieurs fichiers JSON (séparés par des virgules, des points-virgules ou selon PATH). Chaque fichier doit contenir { "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }. L’analyseur accepte également "packages" ou "plugins" comme anciens alias de la clé "entries".

Les entrées générées du catalogue de canaux et les entrées du catalogue d’installation des fournisseurs exposent des informations normalisées sur la source d’installation à côté du bloc brut openclaw.install. Ces informations normalisées indiquent si la spécification npm est une version exacte ou un sélecteur flottant, si les métadonnées d’intégrité attendues sont présentes et si un chemin de source local est également disponible. Lorsque l’identité du catalogue ou du paquet est connue, les informations normalisées émettent un avertissement si le nom du paquet npm analysé diverge de cette identité. Elles émettent également un avertissement lorsque defaultChoice est invalide ou pointe vers une source indisponible, ainsi que lorsque des métadonnées d’intégrité npm sont présentes sans source npm valide. Les consommateurs doivent considérer installSource comme un champ facultatif additif afin que les entrées créées manuellement et les adaptateurs de catalogue n’aient pas à le synthétiser. Cela permet aux procédures d’intégration et aux diagnostics d’expliquer l’état du plan des sources sans importer l’environnement d’exécution du Plugin.

Les entrées npm externes officielles doivent privilégier une valeur npmSpec exacte accompagnée de expectedIntegrity. Les noms de paquets seuls et les balises de distribution continuent de fonctionner à des fins de compatibilité, mais ils génèrent des avertissements sur le plan des sources afin que le catalogue puisse évoluer vers des installations verrouillées et vérifiées par contrôle d’intégrité sans casser les Plugins existants. Lorsque la procédure d’intégration installe depuis un chemin de catalogue local, elle enregistre une entrée gérée dans l’index des Plugins avec source: "path" et, lorsque cela est possible, un sourcePath relatif à l’espace de travail. Le chemin de chargement opérationnel absolu reste dans plugins.load.paths ; l’enregistrement d’installation évite de dupliquer les chemins du poste de travail local dans la configuration à long terme. Cela permet aux installations de développement locales de rester visibles dans les diagnostics du plan des sources sans ajouter une seconde surface de divulgation de chemins bruts du système de fichiers. La table SQLite persistante installed_plugin_index constitue la source de vérité des installations et peut être actualisée sans charger les modules d’exécution des Plugins. Sa map installRecords est persistante même lorsqu’un manifeste de Plugin est manquant ou invalide ; sa charge utile plugins est une vue reconstruisible des manifestes.

Plugins de moteur de contexte

Les Plugins de moteur de contexte prennent en charge l’orchestration du contexte de session pour l’ingestion, l’assemblage et la Compaction. Enregistrez-les depuis votre Plugin avec api.registerContextEngine(id, factory), puis sélectionnez le moteur actif avec plugins.slots.contextEngine.

Utilisez cette fonctionnalité lorsque votre Plugin doit remplacer ou étendre le pipeline de contexte par défaut, plutôt que simplement ajouter une recherche en mémoire ou des hooks.

  export default function (api) {  api.registerContextEngine("lossless-claw", (ctx) => ({    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },    async ingest() {      return { ingested: true };    },    async assemble({ messages, sessionKey, availableTools, citationsMode }) {      return {        messages,        estimatedTokens: 0,        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),          agentSessionKey: sessionKey,        }),      };    },    async compact() {      return { ok: true, compacted: false };    },  }));}

La fabrique ctx expose des valeurs facultatives config, agentDir et workspaceDir pour l’initialisation au moment de la construction.

assemble() peut renvoyer contextProjection lorsque le harnais actif dispose d’un fil d’exécution persistant côté backend. Omettez-le pour la projection historique à chaque tour. Renvoyez { mode: "thread_bootstrap", epoch } lorsque le contexte assemblé doit être injecté une seule fois dans un fil d’exécution du backend et réutilisé jusqu’à ce que l’époque change. Modifiez l’époque après un changement sémantique du contexte du moteur, par exemple après une passe de Compaction gérée par le moteur. Les hôtes peuvent préserver les métadonnées des appels d’outils, la forme des entrées et les résultats d’outils expurgés dans une projection d’amorçage de fil afin que les nouveaux fils d’exécution du backend conservent la continuité des outils sans copier de charges utiles brutes contenant des secrets.

Si votre moteur ne prend pas en charge l’algorithme de Compaction, conservez l’implémentation de compact() et déléguez-la explicitement :

   buildMemorySystemPromptAddition,  delegateCompactionToRuntime,} from "openclaw/plugin-sdk/core"; export default function (api) {  api.registerContextEngine("my-memory-engine", (ctx) => ({    info: {      id: "my-memory-engine",      name: "My Memory Engine",      ownsCompaction: false,    },    async ingest() {      return { ingested: true };    },    async assemble({ messages, sessionKey, availableTools, citationsMode }) {      return {        messages,        estimatedTokens: 0,        systemPromptAddition: buildMemorySystemPromptAddition({          availableTools: availableTools ?? new Set(),          citationsMode,          agentId: resolveSessionAgentId({ config: ctx.config, sessionKey }),          agentSessionKey: sessionKey,        }),      };    },    async compact(params) {      return await delegateCompactionToRuntime(params);    },  }));}

Ajout d'une nouvelle capacité

Lorsqu'un plugin nécessite un comportement qui ne correspond pas à l'API actuelle, ne contournez pas le système de plugins en accédant directement à des éléments internes privés. Ajoutez la capacité manquante.

Séquence recommandée :

1. Définissez le contrat du cœur. Déterminez quels comportements partagés doivent relever du cœur : stratégie, solution de repli, fusion de la configuration, cycle de vie, sémantique destinée aux canaux et forme des fonctions d'assistance à l'exécution.
2. Ajoutez des surfaces typées d'enregistrement et d'exécution des plugins. Étendez OpenClawPluginApi et/ou api.runtime avec la plus petite surface typée utile pour cette capacité.
3. Reliez le cœur aux consommateurs de canaux et de fonctionnalités. Les canaux et les plugins de fonctionnalités doivent utiliser la nouvelle capacité par l'intermédiaire du cœur, sans importer directement l'implémentation d'un fournisseur.
4. Enregistrez les implémentations des fournisseurs. Les plugins des fournisseurs enregistrent ensuite leurs moteurs auprès de la capacité.
5. Ajoutez une couverture du contrat. Ajoutez des tests afin que la propriété et la forme de l'enregistrement restent explicites au fil du temps.

C'est ainsi qu'OpenClaw conserve des choix affirmés sans figer la vision du monde d'un fournisseur particulier. Consultez le guide pratique des capacités pour obtenir une liste de contrôle concrète des fichiers et un exemple détaillé.

Liste de contrôle d'une capacité

Lorsque vous ajoutez une nouvelle capacité, l'implémentation doit généralement modifier ensemble les surfaces suivantes :

• les types de contrat du cœur dans src/<capability>/types.ts
• la fonction d'assistance du cœur pour l'exécution dans src/<capability>/runtime.ts
• la surface d'enregistrement de l'API des plugins dans src/plugins/types.ts
• le raccordement au registre des plugins dans src/plugins/registry.ts
• l'exposition à l'exécution des plugins dans src/plugins/runtime/* lorsque les plugins de fonctionnalités ou de canaux doivent l'utiliser
• les fonctions d'assistance de capture et de test dans src/test-utils/plugin-registration.ts
• les assertions de propriété et de contrat dans src/plugins/contracts/registry.ts
• la documentation destinée aux opérateurs et aux plugins dans docs/

Si l'une de ces surfaces est absente, cela indique généralement que la capacité n'est pas encore entièrement intégrée.

Modèle de capacité

Structure minimale :

// core contractexport type VideoGenerationProviderPlugin = {  id: string;  label: string;  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;}; // plugin APIapi.registerVideoGenerationProvider({  id: "openai",  label: "OpenAI",  async generateVideo(req) {    return await generateOpenAiVideo(req);  },}); // shared runtime helper for feature/channel pluginsconst clip = await api.runtime.videoGeneration.generate({  prompt: "Show the robot walking through the lab.",  cfg,});

Structure du test de contrat (src/plugins/contracts/registry.ts expose des recherches de propriété telles que providerContractPluginIds ; les tests vérifient que la liste contracts.videoGenerationProviders d'un plugin correspond à ce qu'il enregistre réellement) :

expect(pluginManifest.contracts?.videoGenerationProviders).toEqual(["openai"]);

La règle reste ainsi simple :

• le cœur possède le contrat de la capacité et l'orchestration
• les plugins des fournisseurs possèdent leurs implémentations respectives
• les plugins de fonctionnalités et de canaux utilisent les fonctions d'assistance à l'exécution
• les tests de contrat maintiennent la propriété explicite

Ressources connexes

• Architecture des plugins — modèle public des capacités et structures
• Sous-chemins du SDK des plugins
• Configuration du SDK des plugins
• Création de plugins