Internes de l’architecture des Plugin

​

Pipeline de chargement

1. découvre les racines de plugin candidates
2. lit les manifestes de bundle natifs ou compatibles et les métadonnées de package
3. rejette les candidats non sûrs
4. normalise la configuration des plugin (plugins.enabled, allow, deny, entries, slots, load.paths)
5. décide de l’activation de chaque candidat
6. charge les modules natifs activés : les modules intégrés compilés utilisent un chargeur natif ; les plugins natifs non compilés utilisent jiti
7. appelle les hooks natifs register(api) et collecte les enregistrements dans le registre des plugin
8. expose le registre aux commandes/surfaces d’exécution

​

Comportement basé d’abord sur le manifeste

• identifier le plugin
• découvrir les canaux/Skills/schémas de configuration déclarés ou les capacités du bundle
• valider plugins.entries.<id>.config
• enrichir les libellés/placeholders de l’interface Control
• afficher les métadonnées d’installation/catalogue
• préserver des descripteurs d’activation et de configuration légers sans charger l’exécution du plugin

• le chargement CLI se limite aux plugins qui possèdent la commande principale demandée
• la résolution de configuration/de plugin de canal se limite aux plugins qui possèdent l’id de canal demandé
• la résolution explicite de configuration/d’exécution de fournisseur se limite aux plugins qui possèdent l’id de fournisseur demandé

​

Ce que le chargeur met en cache

• les résultats de découverte
• les données du registre de manifestes
• les registres de plugin chargés

• Définissez OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1 ou OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1 pour désactiver ces caches.
• Ajustez les fenêtres de cache avec OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS et OPENCLAW_PLUGIN_MANIFEST_CACHE_MS.

​

Modèle de registre

• les enregistrements de plugin (identité, source, origine, statut, diagnostics)
• les outils
• les hooks historiques et les hooks typés
• les canaux
• les fournisseurs
• les gestionnaires RPC du gateway
• les routes HTTP
• les enregistreurs CLI
• les services en arrière-plan
• les commandes possédées par les plugin

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

​

Callbacks de liaison de conversation

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // Une liaison existe maintenant pour ce plugin + cette conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // La demande a été refusée ; effacez tout état local en attente.
      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’indice de détachement, l’id de l’expéditeur et les métadonnées de conversation

​

Hooks d’exécution du fournisseur

• Métadonnées du manifeste pour une recherche légère avant le runtime : providerAuthEnvVars, providerAuthAliases, providerAuthChoices et channelEnvVars.
• Hooks au moment de la configuration : catalog (anciennement discovery) plus 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 réflexion, la politique de relecture et les points d’accès d’usage. Voir la liste complète sous Ordre et usage des hooks.

​

Ordre et usage 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

​

Helpers 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 surfaces de fichier/note vocale.
• Utilise la configuration centrale messages.tts et la sélection du fournisseur.
• Renvoie un tampon audio PCM + une fréquence d’échantillonnage. Les plugins doivent rééchantillonner/encoder pour les fournisseurs.
• listVoices est facultatif selon le fournisseur. Utilisez-le pour les sélecteurs de voix ou les flux de configuration propres au fournisseur.
• Les listes de voix peuvent inclure des métadonnées plus riches comme la locale, le genre et des tags de personnalité pour des sélecteurs tenant compte du fournisseur.
• OpenAI et ElevenLabs prennent en charge la téléphonie aujourd’hui. Microsoft non.

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 livraison des réponses dans le cœur.
• Utilisez les fournisseurs de parole pour le comportement de synthèse propre au fournisseur.
• L’entrée historique Microsoft edge est normalisée vers l’id fournisseur microsoft.
• Le modèle de propriété préféré est orienté entreprise : un plugin fournisseur peut prendre en charge les fournisseurs de texte, parole, image et futurs médias à mesure qu’OpenClaw ajoute ces contrats de capacité.

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 des canaux dans le cœur.
• Conservez le comportement fournisseur dans le plugin fournisseur.
• L’extension additive doit rester typée : nouvelles méthodes facultatives, nouveaux champs de résultat facultatifs, nouvelles capacités facultatives.
• La génération vidéo suit déjà le même modèle :
  • le cœur possède le contrat de capacité et le helper d’exécution
  • les plugins fournisseurs enregistrent api.registerVideoGenerationProvider(...)
  • les plugins de fonctionnalité/de canal consomment 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 { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Facultatif lorsque le type MIME ne peut pas être déduit de manière fiable :
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* est la surface partagée préférée pour la compréhension image/audio/vidéo.
• Utilise la configuration audio centrale de compréhension des médias (tools.media.audio) et l’ordre de repli du fournisseur.
• Renvoie { text: undefined } lorsqu’aucune sortie de transcription n’est produite (par exemple en cas d’entrée ignorée/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 surcharges facultatives par exécution, pas des changements de session persistants.
• OpenClaw ne respecte ces champs de surcharge que pour les appelants de confiance.
• Pour les exécutions de repli possédées par un plugin, les opérateurs doivent activer explicitement plugins.entries.<id>.subagent.allowModelOverride: true.
• Utilisez plugins.entries.<id>.subagent.allowedModels pour limiter les plugins de confiance à des cibles canoniques provider/model spécifiques, ou "*" pour autoriser explicitement n’importe quelle cible.
• Les exécutions de sous-agent de plugins non fiables fonctionnent toujours, mais les demandes de surcharge sont rejetées au lieu de faire silencieusement un repli.

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 Web pour les transports de recherche spécifiques au fournisseur.
• api.runtime.webSearch.* est la surface partagée préférée pour les plugins de fonctionnalité/de canal qui ont besoin d’un comportement de recherche sans dépendre du wrapper de l’outil 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 route sous le serveur HTTP du Gateway.
• auth : obligatoire. Utilisez "gateway" pour exiger l’authentification normale du Gateway, ou "plugin" pour une authentification/une vérification de Webhook gérée par le plugin.
• match : facultatif. "exact" (par défaut) ou "prefix".
• replaceExisting : facultatif. Permet au même plugin de remplacer son propre enregistrement de route existant.
• handler : renvoie true lorsque la route a traité la requête.

• api.registerHttpHandler(...) a été supprimé et provoquera une erreur de chargement du plugin. Utilisez api.registerHttpRoute(...) à la place.
• Les routes de plugin doivent déclarer explicitement auth.
• Les conflits exacts 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. Gardez les chaînes de retombée exact/prefix au même niveau d’authentification uniquement.
• Les routes auth: "plugin" ne reçoivent pas automatiquement les portées d’exécution opérateur. Elles sont destinées aux Webhook/vérifications de signature gérés par le plugin, pas aux appels privilégiés aux helpers du Gateway.
• Les routes auth: "gateway" s’exécutent dans une portée d’exécution de requête Gateway, mais cette portée est volontairement conservatrice :
  • l’authentification bearer par secret partagé (gateway.auth.mode = "token" / "password") maintient les portées d’exécution des routes de plugin fixées à operator.write, même si l’appelant envoie x-openclaw-scopes
  • les modes HTTP de confiance portant une identité (par exemple trusted-proxy ou gateway.auth.mode = "none" sur une entrée privée) ne respectent x-openclaw-scopes que lorsque l’en-tête est explicitement présent
  • si x-openclaw-scopes est absent sur ces requêtes de route de plugin porteuses d’identité, la portée d’exécution retombe sur operator.write
• Règle pratique : ne supposez pas qu’une route de plugin authentifiée par gateway soit implicitement une surface d’administration. Si votre route a besoin d’un comportement réservé à l’administration, exigez un mode d’authentification portant une identité et documentez le contrat explicite de l’en-tête x-openclaw-scopes.

​

Chemins d’importation du SDK Plugin

• index.js — entrée du plugin intégré
• api.js — barrel de helpers/types
• runtime-api.js — barrel réservé au runtime
• setup-entry.js — entrée du plugin de configuration

​

Schémas d’outils de message

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

​

Résolution des cibles de canal

• messaging.inferTargetChatType({ to }) décide si une cible normalisée doit être traitée comme direct, group ou channel avant la recherche dans le répertoire.
• messaging.targetResolver.looksLikeId(raw, normalized) indique au cœur si une entrée doit passer directement à une résolution de type id au lieu d’une recherche dans le répertoire.
• messaging.targetResolver.resolveTarget(...) est le repli du plugin lorsque le cœur a besoin d’une résolution finale propre au fournisseur après normalisation ou après un échec de recherche dans le répertoire.
• messaging.resolveOutboundSessionRoute(...) prend en charge la construction spécifique au fournisseur de la route de session sortante une fois qu’une cible est résolue.

• Utilisez inferTargetChatType pour les décisions de catégorie qui doivent avoir lieu avant la recherche de pairs/groupes.
• Utilisez looksLikeId pour les vérifications « traiter ceci comme un id de cible explicite/natif ».
• Utilisez resolveTarget pour le repli de normalisation spécifique au fournisseur, pas pour une recherche large dans le répertoire.
• Conservez les ids natifs au fournisseur comme les chat ids, thread ids, JIDs, handles et room ids dans les valeurs target ou les paramètres spécifiques au fournisseur, pas dans des champs SDK génériques.

​

Répertoires adossés à la configuration

• pairs DM pilotés par liste d’autorisation
• maps de canaux/groupes configurées
• replis statiques de répertoire à portée de compte

• filtrage des requêtes
• application des limites
• helpers de déduplication/normalisation
• construction de ChannelDirectoryEntry[]

​

Catalogues de fournisseurs

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

• simple : fournisseurs simples pilotés par clé API ou variables d’environnement
• profile : fournisseurs qui apparaissent lorsque des profils d’authentification existent
• paired : fournisseurs qui synthétisent plusieurs entrées fournisseur liées
• late : dernier passage, après les autres fournisseurs implicites

• discovery fonctionne toujours comme alias historique
• si catalog et discovery sont tous deux enregistrés, OpenClaw utilise catalog

​

Inspection de canal en lecture seule

• resolveAccount(...) est le chemin d’exécution. Il peut supposer que les identifiants sont entièrement matérialisés et peut échouer rapidement si les secrets requis sont absents.
• Les chemins de commande en lecture seule comme openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, et les flux de réparation doctor/config ne doivent pas avoir besoin de matérialiser les identifiants d’exécution simplement pour décrire la configuration.

• Ne renvoyer qu’un état de compte descriptif.
• Préserver enabled et configured.
• Inclure des champs de source/statut d’identifiants lorsque cela est pertinent, tels que :
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Il n’est pas nécessaire de renvoyer les valeurs brutes de jeton simplement pour signaler une disponibilité en lecture seule. Renvoyer tokenStatus: "available" (et le champ source correspondant) suffit pour les commandes de type statut.
• Utilisez configured_unavailable lorsqu’un identifiant est configuré via SecretRef mais indisponible dans le chemin de commande actuel.

​

Packs de packages

{
  "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 ne commence à écouter
• toutes les méthodes gateway, tous les outils ou services qui doivent exister pendant cette même fenêtre

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

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

​

Métadonnées de catalogue de canal

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (auto-hébergé)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Chat auto-hébergé via des bots Webhook Nextcloud Talk.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel : libellé secondaire pour des surfaces de catalogue/de statut plus riches
• docsLabel : remplace le texte du lien vers la documentation
• preferOver : ids de plugin/canal de priorité inférieure que cette entrée de catalogue doit dépasser
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras : contrôles de texte pour la surface de sélection
• markdownCapable : marque le canal comme compatible Markdown pour les décisions de mise en forme sortante
• exposure.configured : masque le canal des surfaces de liste des canaux configurés lorsqu’il est défini à false
• exposure.setup : masque le canal des sélecteurs interactifs de configuration lorsqu’il est défini à false
• exposure.docs : marque le canal comme interne/privé pour les surfaces de navigation de documentation
• showConfigured / showInSetup : alias historiques toujours acceptés pour compatibilité ; préférez exposure
• quickstartAllowFrom : fait participer le canal au flux allowFrom standard de démarrage rapide
• forceAccountBinding : exige une liaison de compte explicite même lorsqu’un seul compte existe
• preferSessionLookupForAnnounceTarget : préfère 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";

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

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

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

​

Ajout d’une nouvelle capacité

1. définissez le contrat du cœur Décidez quel comportement partagé le cœur doit prendre en charge : politique, repli, fusion de configuration, cycle de vie, sémantique côté canal et forme du helper d’exécution.
2. ajoutez des surfaces typées d’enregistrement/de runtime pour les plugins Étendez OpenClawPluginApi et/ou api.runtime avec la plus petite surface de capacité typée utile.
3. câblez les consommateurs du cœur + des canaux/fonctionnalités Les canaux et les plugins de fonctionnalité doivent consommer la nouvelle capacité via le cœur, et non en important directement une implémentation fournisseur.
4. enregistrez les implémentations fournisseur Les plugins fournisseurs enregistrent ensuite leurs backends par rapport à la capacité.
5. ajoutez une couverture de contrat Ajoutez des tests afin que la propriété et la forme d’enregistrement restent explicites dans le temps.

​

Checklist de capacité

• types de contrat du cœur dans src/<capability>/types.ts
• exécuteur/helper d’exécution du cœur dans src/<capability>/runtime.ts
• surface d’enregistrement de l’API plugin dans src/plugins/types.ts
• câblage du registre de plugins dans src/plugins/registry.ts
• exposition du runtime des plugins dans src/plugins/runtime/* lorsque les plugins de fonctionnalité/de canal doivent la consommer
• helpers de capture/de test dans src/test-utils/plugin-registration.ts
• assertions de propriété/de contrat dans src/plugins/contracts/registry.ts
• documentation opérateur/plugin dans docs/

​

Modèle de capacité

// contrat du cœur
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

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

// helper d’exécution partagé pour les plugins de fonctionnalité/de canal
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• le cœur possède le contrat de capacité + l’orchestration
• les plugins fournisseurs possèdent les implémentations fournisseur
• les plugins de fonctionnalité/de canal consomment les helpers d’exécution
• les tests de contrat gardent la propriété explicite

​

Lié

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