Plugin mimarisi iç yapıları

​

Yükleme hattı

1. aday Plugin köklerini keşfeder
2. yerel veya uyumlu paket manifestlerini ve paket meta verilerini okur
3. güvenli olmayan adayları reddeder
4. Plugin yapılandırmasını normalize eder (plugins.enabled, allow, deny, entries, slots, load.paths)
5. her aday için etkinleştirmeye karar verir
6. etkin yerel modülleri yükler: derlenmiş paketli modüller yerel yükleyici kullanır; üçüncü taraf yerel kaynak TypeScript acil durum Jiti fallback’ini kullanır
7. yerel register(api) hook’larını çağırır ve kayıtları Plugin kayıt defterinde toplar
8. kayıt defterini komutlara/runtime yüzeylerine açar

​

Manifest öncelikli davranış

• Plugin’i tanımlamak
• bildirilen kanalları/skills/yapılandırma şemasını veya paket yeteneklerini keşfetmek
• plugins.entries.<id>.config değerini doğrulamak
• Control UI etiketlerini/yer tutucularını zenginleştirmek
• kurulum/katalog meta verilerini göstermek
• Plugin runtime’ını yüklemeden ucuz etkinleştirme ve kurulum tanımlayıcılarını korumak

• CLI yüklemesi, istenen birincil komuta sahip Plugin’lere daraltılır
• kanal kurulumu/Plugin çözümlemesi, istenen kanal id’sine sahip Plugin’lere daraltılır
• açık sağlayıcı kurulumu/runtime çözümlemesi, istenen sağlayıcı id’sine sahip Plugin’lere daraltılır
• Gateway başlangıç planlaması, açık başlangıç içe aktarmaları ve başlangıçtan çıkışlar için activation.onStartup kullanır; başlangıç meta verisi olmayan Plugin’ler yalnızca daha dar etkinleştirme tetikleyicileriyle yüklenir

​

Plugin önbelleği sınırı

• PluginLoaderCacheState ve uyumlu etkin runtime kayıt defterleri
• aynı runtime yüzeyini tekrar tekrar içe aktarmayı önlemek için kullanılan jiti/modül önbellekleri ve genel yüzey yükleyici önbellekleri
• kurulu Plugin yapıtları için dosya sistemi önbellekleri
• yol normalizasyonu veya yinelenen çözümleme için kısa ömürlü çağrı başına haritalar

• keşif sonuçları
• doğrudan manifest kayıt defterleri
• kurulu Plugin dizininden yeniden oluşturulan manifest kayıt defterleri
• sağlayıcı sahibi araması, model bastırma, sağlayıcı politikası veya genel yapıt meta verileri
• değişen bir manifestin, kurulu dizinin veya yükleme yolunun bir sonraki meta veri okumasında görünür olması gereken manifestten türetilmiş diğer yanıtlar

​

Kayıt defteri modeli

• Plugin kayıtları (kimlik, kaynak, köken, durum, tanılamalar)
• araçlar
• eski hook’lar ve tipli hook’lar
• kanallar
• sağlayıcılar
• Gateway RPC işleyicileri
• HTTP rotaları
• CLI kaydedicileri
• arka plan servisleri
• Plugin’e ait komutlar

• Plugin modülü -> kayıt defteri kaydı
• çekirdek runtime -> kayıt defteri tüketimi

​

Konuşma bağlama geri çağrıları

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" veya "denied"
• decision: "allow-once", "allow-always" veya "deny"
• binding: onaylanmış istekler için çözümlenmiş bağlama
• request: özgün istek özeti, ayırma ipucu, gönderen id’si ve konuşma meta verileri

​

Sağlayıcı runtime hook’ları

• Ucuz runtime öncesi arama için manifest meta verileri: setup.providers[].envVars, kullanımdan kaldırılmış uyumluluk providerAuthEnvVars, providerAuthAliases, providerAuthChoices ve channelEnvVars.
• Yapılandırma zamanı hook’ları: catalog (eski discovery) ve applyConfigDefaults.
• Runtime hook’ları: kimlik doğrulama, model çözümleme, akış sarmalama, düşünme seviyeleri, yeniden oynatma politikası ve kullanım uç noktalarını kapsayan 40+ isteğe bağlı hook. Tam liste için bkz. Hook sırası ve kullanım.

​

Hook sırası ve kullanım

​

Sağlayıcı örneği

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

​

Yerleşik örnekler

​

Çalışma zamanı yardımcıları

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, dosya/sesli not yüzeyleri için normal çekirdek TTS çıktı yükünü döndürür.
• Çekirdek messages.tts yapılandırmasını ve sağlayıcı seçimini kullanır.
• PCM ses arabelleği + örnekleme hızını döndürür. Plugin’ler sağlayıcılar için yeniden örneklemeli/kodlamalıdır.
• listVoices sağlayıcı başına isteğe bağlıdır. Bunu satıcıya ait ses seçiciler veya kurulum akışları için kullanın.
• Ses listeleri, sağlayıcı farkındalıklı seçiciler için yerel ayar, cinsiyet ve kişilik etiketleri gibi daha zengin meta veriler içerebilir.
• OpenAI ve ElevenLabs bugün telefon desteğini destekler. Microsoft desteklemez.

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

• TTS ilkesini, geri dönüşü ve yanıt teslimini çekirdekte tutun.
• Konuşma sağlayıcılarını satıcıya ait sentez davranışı için kullanın.
• Eski Microsoft edge girdisi microsoft sağlayıcı kimliğine normalleştirilir.
• Tercih edilen sahiplik modeli şirket odaklıdır: OpenClaw bu yetenek sözleşmelerini ekledikçe tek bir satıcı Plugin’i metin, konuşma, görüntü ve gelecekteki medya sağlayıcılarının sahibi olabilir.

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

• Orkestrasyonu, geri dönüşü, yapılandırmayı ve kanal bağlantılarını çekirdekte tutun.
• Satıcı davranışını sağlayıcı Plugin’inde tutun.
• Eklemeli genişleme yazılmış kalmalıdır: yeni isteğe bağlı yöntemler, yeni isteğe bağlı sonuç alanları, yeni isteğe bağlı yetenekler.
• Video üretimi zaten aynı kalıbı izler:
  • çekirdek yetenek sözleşmesine ve çalışma zamanı yardımcısına sahiptir
  • satıcı Plugin’leri api.registerVideoGenerationProvider(...) kaydeder
  • özellik/kanal Plugin’leri api.runtime.videoGeneration.* tüketir

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.5",
  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.*, görüntü/ses/video anlama için tercih edilen paylaşılan yüzeydir.
• extractStructuredWithModel(...), sınırlı sağlayıcıya ait görüntü öncelikli çıkarım için Plugin’e dönük sınırdır. En az bir görüntü girdisi ekleyin; metin girdileri tamamlayıcı bağlamdır. Ürün Plugin’leri kendi rotalarına ve şemalarına sahip olurken OpenClaw sağlayıcı/çalışma zamanı sınırına sahiptir.
• Çekirdek medya anlama ses yapılandırmasını (tools.media.audio) ve sağlayıcı geri dönüş sırasını kullanır.
• Transkripsiyon çıktısı üretilmediğinde (örneğin atlanan/desteklenmeyen girdi) { text: undefined } döndürür.
• api.runtime.stt.transcribeAudioFile(...) uyumluluk alias’ı olarak kalır.

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 ve model, kalıcı oturum değişiklikleri değil, çalışma başına isteğe bağlı geçersiz kılmalardır.
• OpenClaw bu geçersiz kılma alanlarını yalnızca güvenilir çağıranlar için dikkate alır.
• Plugin’e ait geri dönüş çalıştırmaları için operatörler plugins.entries.<id>.subagent.allowModelOverride: true ile katılmalıdır.
• Güvenilir Plugin’leri belirli kanonik provider/model hedefleriyle sınırlamak için plugins.entries.<id>.subagent.allowedModels kullanın veya herhangi bir hedefe açıkça izin vermek için "*" kullanın.
• Güvenilmeyen Plugin alt ajan çalıştırmaları hâlâ çalışır, ancak geçersiz kılma istekleri sessizce geri dönmek yerine reddedilir.
• Plugin tarafından oluşturulan alt ajan oturumları, oluşturan Plugin kimliğiyle etiketlenir. Geri dönüş api.runtime.subagent.deleteSession(...) yalnızca bu sahip olunan oturumları silebilir; rastgele oturum silme hâlâ yönetici kapsamlı bir Gateway isteği gerektirir.

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

• Sağlayıcı seçimini, kimlik bilgisi çözümlemesini ve paylaşılan istek semantiğini çekirdekte tutun.
• Web arama sağlayıcılarını satıcıya özgü arama taşımaları için kullanın.
• api.runtime.webSearch.*, ajan aracı sarmalayıcısına bağımlı olmadan arama davranışına ihtiyaç duyan özellik/kanal Plugin’leri için tercih edilen paylaşılan yüzeydir.

​

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(...): yapılandırılmış görüntü üretimi sağlayıcı zincirini kullanarak bir görüntü üretir.
• listProviders(...): kullanılabilir görüntü üretimi sağlayıcılarını ve yeteneklerini listeler.

​

Gateway HTTP rotaları

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

• path: Gateway HTTP sunucusu altındaki rota yolu.
• auth: zorunlu. Normal Gateway kimlik doğrulaması gerektirmek için "gateway", Plugin tarafından yönetilen kimlik doğrulaması/webhook doğrulaması için "plugin" kullanın.
• match: isteğe bağlı. "exact" (varsayılan) veya "prefix".
• replaceExisting: isteğe bağlı. Aynı Plugin’in kendi mevcut rota kaydını değiştirmesine izin verir.
• handler: rota isteği işlediğinde true döndürün.

• api.registerHttpHandler(...) kaldırıldı ve Plugin yükleme hatasına neden olur. Bunun yerine api.registerHttpRoute(...) kullanın.
• Plugin rotaları auth değerini açıkça bildirmelidir.
• Tam path + match çakışmaları, replaceExisting: true olmadığı sürece reddedilir ve bir Plugin başka bir Plugin’in rotasını değiştiremez.
• Farklı auth düzeylerine sahip örtüşen rotalar reddedilir. exact/prefix düşüş zincirlerini yalnızca aynı auth düzeyinde tutun.
• auth: "plugin" rotaları operatör çalışma zamanı kapsamlarını otomatik olarak almaz. Bunlar ayrıcalıklı Gateway yardımcı çağrıları için değil, Plugin tarafından yönetilen webhook’lar/imza doğrulaması içindir.
• auth: "gateway" rotaları bir Gateway isteği çalışma zamanı kapsamı içinde çalışır, ancak bu kapsam kasıtlı olarak kısıtlayıcıdır:
  • paylaşılan gizli bearer auth (gateway.auth.mode = "token" / "password"), çağıran x-openclaw-scopes gönderse bile Plugin rota çalışma zamanı kapsamlarını operator.write değerine sabitler
  • güvenilir kimlik taşıyan HTTP modları (örneğin özel bir girişte trusted-proxy veya gateway.auth.mode = "none") yalnızca başlık açıkça bulunduğunda x-openclaw-scopes değerini kabul eder
  • bu kimlik taşıyan Plugin rota isteklerinde x-openclaw-scopes yoksa, çalışma zamanı kapsamı operator.write değerine geri döner
• Pratik kural: gateway-auth Plugin rotasının örtük bir yönetici yüzeyi olduğunu varsaymayın. Rotanız yalnızca yönetici davranışı gerektiriyorsa, kimlik taşıyan bir auth modu gerektirin ve açık x-openclaw-scopes başlık sözleşmesini belgeleyin.

​

Plugin SDK içe aktarma yolları

• index.js — paketlenmiş Plugin girişi
• api.js — yardımcı/tip barrel’i
• runtime-api.js — yalnızca çalışma zamanı barrel’i
• setup-entry.js — kurulum Plugin girişi

​

Mesaj aracı şemaları

• semantik sunum blokları (text, context, divider, buttons, select) için presentation
• sabitlenmiş teslim istekleri için delivery-pin

​

Kanal hedef çözümlemesi

• messaging.inferTargetChatType({ to }), normalleştirilmiş bir hedefin dizin aramasından önce direct, group veya channel olarak ele alınıp alınmayacağına karar verir.
• messaging.targetResolver.looksLikeId(raw, normalized), bir girdinin dizin araması yerine doğrudan id benzeri çözümlemeye atlanıp atlanmayacağını çekirdeğe söyler.
• messaging.targetResolver.reservedLiterals, o sağlayıcı için kanal/oturum başvurusu olan yalın sözcükleri listeler. Çözümleme, ayrılmış sabitleri reddetmeden önce yapılandırılmış dizin girdilerini korur, ardından dizin eşleşmesi yoksa kapalı şekilde başarısız olur.
• messaging.targetResolver.resolveTarget(...), çekirdeğin normalleştirmeden sonra veya dizin eşleşmesi kaçırıldıktan sonra son sağlayıcıya ait çözümlemeye ihtiyaç duyması durumunda Plugin geri dönüşüdür.
• messaging.resolveOutboundSessionRoute(...), hedef çözümlendikten sonra sağlayıcıya özgü oturum rotası oluşturmayı sahiplenir.

• Eşleri/grupları aramadan önce gerçekleşmesi gereken kategori kararları için inferTargetChatType kullanın.
• “Bunu açık/yerel hedef id olarak ele al” kontrolleri için looksLikeId kullanın.
• Geniş dizin araması için değil, sağlayıcıya özgü normalleştirme geri dönüşü için resolveTarget kullanın.
• Sohbet id’leri, konu id’leri, JID’ler, handle’lar ve oda id’leri gibi sağlayıcıya özgü yerel id’leri genel SDK alanlarında değil, target değerleri veya sağlayıcıya özgü parametreler içinde tutun.

​

Yapılandırma destekli dizinler

• izin listesiyle yönetilen DM eşleri
• yapılandırılmış kanal/grup eşlemeleri
• hesap kapsamlı statik dizin geri dönüşleri

• sorgu filtreleme
• limit uygulama
• yinelenenleri kaldırma/normalleştirme yardımcıları
• ChannelDirectoryEntry[] oluşturma

​

Sağlayıcı katalogları

• tek sağlayıcı girdisi için { provider }
• birden çok sağlayıcı girdisi için { providers }

• simple: düz API anahtarı veya env odaklı sağlayıcılar
• profile: auth profilleri olduğunda görünen sağlayıcılar
• paired: birden çok ilişkili sağlayıcı girdisi sentezleyen sağlayıcılar
• late: diğer örtük sağlayıcılardan sonra son geçiş

• discovery eski bir diğer ad olarak hâlâ çalışır, ancak kullanımdan kaldırma uyarısı yayar
• hem catalog hem de discovery kayıtlıysa, OpenClaw catalog kullanır
• augmentModelCatalog kullanımdan kaldırılmıştır; paketlenmiş sağlayıcılar ek satırları registerModelCatalogProvider aracılığıyla yayımlamalıdır

​

Salt okunur kanal incelemesi

• resolveAccount(...) çalışma zamanı yoludur. Kimlik bilgilerinin tamamen somutlaştırıldığını varsaymasına izin verilir ve gerekli secret’lar eksik olduğunda hızlı şekilde başarısız olabilir.
• openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve gibi salt okunur komut yolları ve doctor/yapılandırma onarım akışları, yalnızca yapılandırmayı tanımlamak için çalışma zamanı kimlik bilgilerini somutlaştırmak zorunda kalmamalıdır.

• Yalnızca açıklayıcı hesap durumu döndürün.
• enabled ve configured değerlerini koruyun.
• İlgili olduğunda kimlik bilgisi kaynak/durum alanlarını ekleyin, örneğin:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Salt okunur kullanılabilirliği raporlamak için ham token değerleri döndürmeniz gerekmez. tokenStatus: "available" (ve eşleşen kaynak alanı) döndürmek durum tarzı komutlar için yeterlidir.
• Bir kimlik bilgisi SecretRef ile yapılandırılmış ancak mevcut komut yolunda kullanılamıyorsa configured_unavailable kullanın.

​

Paket paketleri

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

• kanal kaydının kendisi
• gateway dinlemeye başlamadan önce kullanılabilir olması gereken tüm HTTP rotaları
• aynı pencere sırasında var olması gereken tüm gateway yöntemleri, araçları veya hizmetleri

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

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

​

Kanal katalog metaverileri

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (kendi barındırmalı)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Nextcloud Talk webhook botları üzerinden kendi barındırmalı sohbet.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: daha zengin katalog/durum yüzeyleri için ikincil etiket
• docsLabel: dokümantasyon bağlantısı için bağlantı metnini geçersiz kıl
• preferOver: bu katalog girdisinin önüne geçmesi gereken daha düşük öncelikli plugin/kanal kimlikleri
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: seçim yüzeyi metin denetimleri
• markdownCapable: kanalı giden biçimlendirme kararları için markdown yetenekli olarak işaretler
• exposure.configured: false olarak ayarlandığında kanalı yapılandırılmış kanal listeleme yüzeylerinden gizle
• exposure.setup: false olarak ayarlandığında kanalı etkileşimli kurulum/yapılandırma seçicilerinden gizle
• exposure.docs: kanalı dokümantasyon gezinti yüzeyleri için dahili/özel olarak işaretle
• showConfigured / showInSetup: uyumluluk için hâlâ kabul edilen eski takma adlar; exposure tercih edin
• quickstartAllowFrom: kanalı standart hızlı başlangıç allowFrom akışına dahil et
• forceAccountBinding: yalnızca bir hesap var olsa bile açık hesap bağlamayı zorunlu kıl
• preferSessionLookupForAnnounceTarget: duyuru hedeflerini çözerken oturum aramasını tercih et

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

​

Bağlam motoru plugin’leri

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/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, 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", (ctx) => ({
    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);
    },
  }));
}

​

Yeni bir yetenek ekleme

1. çekirdek sözleşmeyi tanımlayın Çekirdeğin hangi ortak davranışa sahip olması gerektiğine karar verin: politika, fallback, yapılandırma birleştirme, yaşam döngüsü, kanala dönük semantik ve çalışma zamanı yardımcı şekli.
2. tipli plugin kayıt/çalışma zamanı yüzeyleri ekleyin OpenClawPluginApi ve/veya api.runtime yüzeyini en küçük yararlı tipli yetenek yüzeyiyle genişletin.
3. çekirdeği + kanal/özellik tüketicilerini bağlayın Kanallar ve özellik plugin’leri, yeni yeteneği bir vendor uygulamasını doğrudan içe aktararak değil, çekirdek üzerinden tüketmelidir.
4. vendor uygulamalarını kaydedin Vendor plugin’leri ardından backend’lerini yeteneğe karşı kaydeder.
5. sözleşme kapsamı ekleyin Sahiplik ve kayıt şeklinin zaman içinde açık kalması için testler ekleyin.

​

Yetenek kontrol listesi

• src/<capability>/types.ts içindeki çekirdek sözleşme tipleri
• src/<capability>/runtime.ts içindeki çekirdek çalıştırıcı/çalışma zamanı yardımcısı
• src/plugins/types.ts içindeki plugin API kayıt yüzeyi
• src/plugins/registry.ts içindeki plugin kayıt defteri bağlantısı
• özellik/kanal plugin’lerinin tüketmesi gerektiğinde src/plugins/runtime/* içindeki plugin çalışma zamanı açığa çıkarımı
• src/test-utils/plugin-registration.ts içindeki yakalama/test yardımcıları
• src/plugins/contracts/registry.ts içindeki sahiplik/sözleşme doğrulamaları
• docs/ içindeki operatör/plugin dokümantasyonu

​

Yetenek şablonu

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

// feature/channel plugin'leri için paylaşılan runtime yardımcısı
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

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

• core, yetenek sözleşmesine + orkestrasyona sahip olur
• satıcı plugin’leri satıcı uygulamalarına sahip olur
• feature/channel plugin’leri runtime yardımcılarını tüketir
• contract testleri sahipliği açık tutar

​

İlgili

• Plugin mimarisi — genel yetenek modeli ve şekilleri
• Plugin SDK alt yolları
• Plugin SDK kurulumu
• Plugin oluşturma