Fonctionnement interne de l’architecture des Plugins

​

Pipeline de chargement

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

• 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)

​

Comportement privilégiant le manifeste

• 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

• 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

​

Limite du cache des Plugins

• 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

• 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

​

Modèle de registre

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

​

Rappels de liaison de conversation

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);
    });
  },
};

• 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

​

Hooks d’exécution des fournisseurs

• 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.

​

Ordre et utilisation des hooks

​

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

​

Assistants d’exécution

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,
});

• 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.

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,
    };
  },
});

• 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.

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

• 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.*

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,
});

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",
});

• 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é.

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,
});

• 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.

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,
  },
});

• 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

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

• 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.

• 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

• 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

​

Schémas de l’outil 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

​

Résolution des cibles de canal

• 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.

• 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 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

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

​

Catalogues des fournisseurs

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

• 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

• 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

• 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.

• 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.

​

Paquets groupés

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

• 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

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

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

​

Métadonnées du catalogue de canaux

{
  "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"
    }
  }
}

• 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/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

Plugins de moteur de contexte

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
import { resolveSessionAgentId } from "openclaw/plugin-sdk/memory-host-core";

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 };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";
import { resolveSessionAgentId } from "openclaw/plugin-sdk/memory-host-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é

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.

​

Liste de contrôle d’une capacité

• 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/

​

Modèle de capacité

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

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

• 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