Plugin mimarisi iç işleyişi

​

Yükleme işlem hattı

1. aday plugin köklerini keşfeder
2. yerel veya uyumlu paket bildirimlerini ve paket meta verilerini okur
3. güvenli olmayan adayları reddeder
4. plugin yapılandırmasını normalleştirir (plugins.enabled, allow, deny, entries, slots, load.paths)
5. her aday için etkinleştirme durumuna karar verir
6. etkin yerel modülleri yükler: derlenmiş paket içi modüller yerel bir yükleyici kullanır; üçüncü taraf yerel kaynak TypeScript, acil durum Jiti yedek mekanizmasını kullanır
7. yerel register(api) kancalarını çağırır ve kayıtları plugin kayıt defterinde toplar
8. kayıt defterini komutlara/çalışma zamanı yüzeylerine sunar

• çözümlenen giriş noktası plugin kökünün dışına çıkıyorsa
• yolu (veya kök dizini) herkes tarafından yazılabiliyorsa
• paket içi olmayan pluginlerde yol sahipliği mevcut uid (veya root) ile eşleşmiyorsa

​

Bildirim öncelikli davranış

• plugini 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 çalışma zamanını yüklemeden düşük maliyetli etkinleştirme ve kurulum tanımlayıcılarını korumak

• CLI yüklemesi, istenen birincil komutun sahibi olan pluginlerle sınırlandırılır
• kanal kurulumu/plugin çözümlemesi, istenen kanal kimliğinin sahibi olan pluginlerle sınırlandırılır
• açık sağlayıcı kurulumu/çalışma zamanı çözümlemesi, istenen sağlayıcı kimliğinin sahibi olan pluginlerle sınırlandırılır
• Gateway başlangıç planlaması açık başlangıç içe aktarmaları için activation.onStartup kullanır; başlangıç meta verisi olmayan pluginler yalnızca daha dar etkinleştirme tetikleyicileri üzerinden yüklenir

​

Plugin önbellek sınırı

• PluginLoaderCacheState ve uyumlu etkin çalışma zamanı kayıt defterleri
• aynı çalışma zamanı yüzeyini tekrar tekrar içe aktarmaktan kaçınmak için kullanılan jiti/modül önbellekleri ve genel yüzey yükleyici önbellekleri
• kurulu plugin yapıları için dosya sistemi önbellekleri
• yol normalleştirme veya yinelenen çözümleme için kısa ömürlü çağrı başına eşlemeler

• keşif sonuçları
• doğrudan bildirim kayıt defterleri
• kurulu plugin dizininden yeniden oluşturulan bildirim kayıt defterleri
• sağlayıcı sahibi araması, model engelleme, sağlayıcı ilkesi veya genel yapı meta verileri
• değişen bir bildirimin, kurulu dizinin veya yükleme yolunun bir sonraki meta veri okumasında görünmesi gereken, bildirimden türetilmiş diğer tüm yanıtlar

​

Kayıt defteri modeli

• plugin modülü -> kayıt defteri kaydı
• çekirdek çalışma zamanı -> 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") {
        // Artık bu plugin + konuşma için bir bağlama mevcut.
        console.log(event.binding?.conversationId);
        return;
      }

      // İstek reddedildi; bekleyen tüm yerel durumları temizleyin.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" veya "denied"
• decision: "allow-once", "allow-always" veya "deny"
• binding: onaylanan istekler için çözümlenen bağlama
• request: özgün istek özeti, ayırma ipucu, gönderen kimliği ve konuşma meta verileri

​

Sağlayıcı çalışma zamanı kancaları

• Çalışma zamanı öncesi düşük maliyetli arama için bildirim meta verileri: setup.providers[].envVars, providerAuthAliases, providerAuthChoices ve channelConfigs.
• Yapılandırma zamanı kancaları: catalog ile applyConfigDefaults.
• Çalışma zamanı kancaları: kimlik doğrulama, model çözümleme, akış sarmalama, düşünme düzeyleri, yeniden oynatma ilkesi ve kullanım uç noktalarını kapsayan 40’tan fazla isteğe bağlı kanca. Bkz. Kanca sırası ve kullanımı.

​

Kanca 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: "OpenClaw'dan merhaba",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "OpenClaw'dan merhaba",
  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 tts yapılandırmasını ve sağlayıcı seçimini kullanır.
• PCM ses arabelleği + örnekleme hızı 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. Satıcıya ait ses seçiciler veya kurulum akışları için kullanın.
• Çekirdek, sağlayıcı listVoices kancalarına çözümlenmiş bir istek son tarihi iletir; sağlayıcıya özgü zaman aşımı ayarları bunu geçersiz kılabilir.
• Ses listeleri, sağlayıcıya duyarlı seçiciler için yerel ayar, cinsiyet ve kişilik etiketleri gibi daha zengin meta veriler içerebilir.
• OpenAI ve ElevenLabs şu anda telefonu 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 politikasını, geri dönüşü ve yanıt teslimini çekirdekte tutun.
• Satıcıya ait sentez davranışı için konuşma sağlayıcılarını 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ına sahip 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şletme türlü 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ı örüntüyü 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.6-sol",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "Doğruluk kaynağı olarak basılı alanları kullanın." },
  ],
  instructions: "Varlıkları ve aranabilir etiketleri döndürün.",
  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,
  // MIME güvenilir biçimde çıkarılamadığında isteğe bağlıdır:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.*, görüntü/ses/video anlama için tercih edilen paylaşılan yüzeydir.
• extractStructuredWithModel(...), sınırlı ve sağlayıcıya ait, öncelikle görüntü tabanlı çıkarım için Plugin’e dönük bağlantı noktasıdı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 sahipken 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.
• Hiçbir transkripsiyon çıktısı üretilmediğinde (örneğin atlanan/desteklenmeyen girdi) { text: undefined } döndürür.

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Bu sorguyu odaklanmış takip aramalarına genişletin.",
  toolsAlsoAllow: ["my_plugin_progress"],
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider ve model, kalıcı oturum değişiklikleri değil, çalıştırma başına isteğe bağlı geçersiz kılmalardır.
• toolsAlsoAllow, çağıran Plugin tarafından kaydedilmiş tam ve benzersiz sahipli araç adlarını kabul eder. Çekirdek ve belirsiz adlar reddedilir. Normal profile eklemelidir ancak operatör izin listeleri ve retleri yetkili olmaya devam eder.
• 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örlerin plugins.entries.<id>.subagent.allowModelOverride: true ile katılım sağlaması gerekir.
• Güvenilir Plugin’leri belirli standart provider/model hedefleriyle sınırlamak için plugins.entries.<id>.subagent.allowedModels, herhangi bir hedefe açıkça izin vermek için ise "*" kullanın.
• Güvenilmeyen Plugin alt aracı çalıştırmaları yine çalışır ancak geçersiz kılma istekleri sessizce geri dönmek yerine reddedilir.
• Plugin tarafından oluşturulan alt aracı oturumları, oluşturan Plugin kimliğiyle etiketlenir. Geri dönüş api.runtime.subagent.deleteSession(...) yalnızca sahip olunan bu oturumları silebilir; rastgele oturum silme işlemi yine de 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 çalışma zamanı yardımcıları",
    count: 5,
  },
});

• Sağlayıcı seçimini, kimlik bilgisi çözümlemesini ve paylaşılan istek semantiğini çekirdekte tutun.
• Satıcıya özgü arama aktarımları için web araması sağlayıcılarını kullanın.
• api.runtime.webSearch.*, aracı araç 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: "Dost canlısı bir ıstakoz maskotu", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...): yapılandırılmış görüntü oluşturma sağlayıcı zincirini kullanarak bir görüntü oluşturur.
• listProviders(...): kullanılabilir görüntü oluşturma sağlayıcılarını ve bunların 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: zorunludur; "gateway" veya "plugin". Normal Gateway kimlik doğrulamasını zorunlu kılmak için "gateway", Plugin tarafından yönetilen kimlik doğrulama/Webhook doğrulaması için "plugin" kullanın.
• match: isteğe bağlıdır. "exact" (varsayılan) veya "prefix".
• handleUpgrade: aynı rotadaki WebSocket yükseltme istekleri için isteğe bağlı işleyici.
• replaceExisting: isteğe bağlıdır. 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ılmıştır 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 zincirlerini yalnızca aynı kimlik doğrulama 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. Varsayılan yüzey (gatewayRuntimeScopeSurface: "write-default") kasıtlı olarak ihtiyatlıdır:
  • paylaşılan gizli anahtar taşıyıcı kimlik doğrulaması (gateway.auth.mode = "token" / "password") ve güvenilir proxy dışındaki tüm kimlik doğrulama yöntemleri, çağıran x-openclaw-scopes gönderse bile tek bir operator.write kapsamı alır
  • açık bir x-openclaw-scopes üstbilgisi olmayan trusted-proxy çağıranları da eski, yalnızca operator.write yüzeyini korur
  • x-openclaw-scopes gönderen trusted-proxy çağıranları bunun yerine bildirilen kapsamları alır
  • bir rota, kimlik taşıyan kimlik doğrulama modlarında x-openclaw-scopes değerini her zaman dikkate almak için gatewayRuntimeScopeSurface: "trusted-operator" seçeneğini etkinleştirebilir (üstbilgi yoksa tam CLI varsayılan kapsam kümesine geri döner)
• auth: "gateway" rotaları tarafından desteklenen korumalı alan içindeki harici Control UI sekmeleri, yalnızca kimliği doğrulanmış başlangıç işlemi tarafından oluşturulan kısa ömürlü, imzalı bir çerez izni kullanır; Plugin kimlik doğrulamalı sekmeler doğrudan iframe yollarını korur. Üst öğe, bağlamadan önce aynı opak korumalı alan içinde rotanın sahip olduğu bir yoklama çalıştırır ve tarayıcı gizlilik politikası çerezi engellediğinde güvenli biçimde başarısız olur. İzin, sahip olan Plugin’e, eşleşen rota köküne ve geçerli kimlik doğrulama nesline bağlıdır; süreç için rastgele oluşturulan çerez adı, aynı ana bilgisayardaki güvenilir Gateway’lerin birbirlerinin üzerine yazmasını önler ancak çerezler TCP bağlantı noktalarını hiçbir zaman birbirinden yalıtmaz. Bu nedenle Gateway ana bilgisayar adı tek bir kimlik bilgisi sınırıdır: diğer bağlantı noktaları dâhil olmak üzere karşılıklı olarak güvenilmeyen hizmetleri bu ana bilgisayar adında birlikte barındırmayın. Rota gönderimi, başka bir Plugin’e ait iç içe geçmiş bir rotada yeniden kullanımı reddeder. Korumalı alan alt öğeleri çerez amaçları bakımından siteler arası olduğundan izin, yalnızca operator.read ile GET ve HEAD kabul eder; değişiklikler ve WebSocket yükseltmeleri açıkça Gateway kimlik doğrulamalı yüzeylerde kalır. Çerez kasıtlı olarak CHIPS kullanamaz: güncel tarayıcılar bölüm anahtarına bir siteler arası üst öğe biti eklediğinden, iç içe opak korumalı alan çerçeveleri aynı rotadaki varlıklara erişimi kaybeder. Çerez güvenli bir bağlam ve siteler arası çerezler için tarayıcı izni gerektirir; bu nedenle Gateway kimlik doğrulamalı harici sekmeler düz HTTP kullanan LAN kaynaklarında veya üçüncü taraf çerezlerin tamamen engellendiği durumlarda kullanılamaz; HTTPS/Tailscale Serve veya uyumlu bir çerez politikasıyla tarayıcının güvendiği geri döngüyü kullanın.
• İzin, Gateway taşıyıcı belirtecinin açığa çıkmasını ve rotanın/kapsamın yanlışlıkla yeniden kullanılmasını önler; yerel Plugin’ler arasında bir güvenlik sınırı oluşturmaz. Yerel Plugin kodu ve sunduğu UI içeriği, aynı güvenilir işlem içi Plugin sınırının parçası olmaya devam eder.
• Pratik kural: Gateway kimlik doğrulamalı bir Plugin rotasının örtük bir yönetici yüzeyi olduğunu varsaymayın. Rotanız yalnızca yöneticiye özel davranış gerektiriyorsa trusted-operator kapsam yüzeyini etkinleştirin, kimlik taşıyan bir kimlik doğrulama modunu zorunlu kılın ve açık x-openclaw-scopes üstbilgi sözleşmesini belgeleyin.
• Rota eşleştirmesi ve kimlik doğrulamasından sonra sıradan işleyiciler Gateway kök iş kabulüne katılır. Hazırlanmakta veya yeniden başlatılmakta olan bir Gateway, işleyiciyi çağırmadan önce 503 döndürür. Dar kapsamlı istisna, rota özelindeki trusted-operator yüzeyini de etkinleştiren ve manifest tarafından yetkilendirilmiş bir auth: "gateway" rotasıdır; askıya alma denetimi gönderiminin erişilemez hâle gelmemesi için rota erişilebilir kalırken aynı Plugin’in sıradan kardeş rotaları kabul sınırının arkasında kalır. WebSocket handleUpgrade sahipliği aynı atomik kabul sınırını kullanır; işleyici bir soketi kabul ettikten sonra soketin sonraki yaşam döngüsünün sahibi Plugin olur ve bu sınır tarafından izlenmez.

​

Plugin SDK içe aktarma yolları

• index.js — paketle gelen Plugin girişi
• api.js — yardımcı/tür barrel’ı
• runtime-api.js — yalnızca çalışma zamanı barrel’ı
• setup-entry.js — kurulum Plugin girişi

​

İleti aracı şemaları

• anlamsal sunum blokları için presentation (text, context, divider, chart, table, buttons, select)
• sabitlenmiş teslimat istekleri için delivery-pin

​

Kanal hedefi çözümleme

• messaging.inferTargetChatType({ to }), normalleştirilmiş bir hedefin dizin aramasından önce direct, group veya channel olarak değerlendirilip değerlendirilmeyeceğine karar verir.
• messaging.targetResolver.looksLikeId(raw, normalized), bir girdinin dizin araması yerine doğrudan kimlik benzeri çözümlemeye geçip geçmemesi gerektiğini çekirdeğe bildirir.
• messaging.targetResolver.reservedLiterals, söz konusu sağlayıcı için kanal/oturum başvurusu olan yalın sözcükleri listeler. Çözümleme, ayrılmış sabit değerleri reddetmeden önce yapılandırılmış dizin girdilerini korur, ardından bir dizin eşleşmesi bulunamazsa güvenli biçimde başarısız olur.
• messaging.targetResolver.resolveTarget(...), normalleştirmeden veya bir dizin eşleşmesi bulunamadıktan sonra çekirdeğin sağlayıcının sahip olduğu son bir çözümlemeye ihtiyacı olduğunda Plugin geri dönüşüdür.
• messaging.resolveOutboundSessionRoute(...), bir hedef çözümlendikten sonra sağlayıcıya özel oturum rotası oluşturmanın sahibidir.

• Eşleri/grupları aramadan önce gerçekleşmesi gereken kategori kararları için inferTargetChatType kullanın.
• “Bunu açık/yerel bir hedef kimliği olarak değerlendir” kontrolleri için looksLikeId kullanın.
• Geniş dizin araması için değil, sağlayıcıya özel normalleştirme geri dönüşü için resolveTarget kullanın.
• Sohbet kimlikleri, ileti dizisi kimlikleri, JID’ler, tanıtıcılar ve oda kimlikleri gibi sağlayıcıya özgü kimlikleri genel SDK alanlarında değil, target değerlerinde veya sağlayıcıya özel parametrelerde tutun.

​

Yapılandırma destekli dizinler

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

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

​

Sağlayıcı katalogları

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

• simple: düz API anahtarlı veya ortam tarafından yönlendirilen sağlayıcılar
• profile: kimlik doğrulama profilleri mevcut olduğunda görünen sağlayıcılar
• paired: birbiriyle ilişkili birden çok sağlayıcı girdisi sentezleyen sağlayıcılar
• late: diğer örtük sağlayıcılardan sonraki son geçiş

• discovery eski bir diğer ad olarak çalışmaya devam eder ancak kullanımdan kaldırma uyarısı verir
• hem catalog hem de discovery kaydedilirse OpenClaw, catalog kullanır ve bir uyarı verir
• 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 oluşturulduğunu varsayabilir ve gerekli gizli bilgiler eksik olduğunda hemen başarısız olabilir.
• openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve gibi salt okunur komut yollarının ve doctor/yapılandırma onarım akışlarının yalnızca yapılandırmayı açıklamak için çalışma zamanı kimlik bilgilerini oluşturması gerekmemelidir.

• Yalnızca açıklayıcı hesap durumunu döndürün.
• enabled ve configured değerlerini koruyun.
• Uygun olduğunda aşağıdakiler gibi kimlik bilgisi kaynağı/durum alanlarını ekleyin:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Yalnızca salt okunur kullanılabilirliği bildirmek için ham token değerlerini döndürmeniz gerekmez. Durum tarzı komutlar için tokenStatus: "available" (ve eşleşen kaynak alanını) döndürmek yeterlidir.
• Bir kimlik bilgisi SecretRef aracılığıyla yapılandırılmış ancak geçerli 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ı zaman aralığında mevcut 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 kataloğu meta verileri

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (kendi sunucunuzda barındırılan)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Nextcloud Talk Webhook botları aracılığıyla kendi sunucunuzda barındırılan 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üman bağlantısının bağlantı metnini geçersiz kılma
• preferOver: bu katalog girdisinin geride bırakması gereken daha düşük öncelikli Plugin/kanal kimlikleri
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: seçim yüzeyi metin denetimleri
• markdownCapable: giden biçimlendirme kararları için kanalı Markdown özellikli olarak işaretler
• exposure.configured: false olarak ayarlandığında kanalı yapılandırılmış kanal listeleme yüzeylerinden gizler
• exposure.setup: false olarak ayarlandığında kanalı etkileşimli kurulum/yapılandırma seçicilerinden gizler
• exposure.docs: doküman gezinme yüzeyleri için kanalı dahili/özel olarak işaretler
• quickstartAllowFrom: kanalı standart hızlı başlangıç allowFrom akışına dahil eder
• forceAccountBinding: yalnızca bir hesap mevcut olsa bile açık hesap bağlaması gerektirir
• preferSessionLookupForAnnounceTarget: duyuru hedeflerini çözümlerken oturum aramasını tercih eder

• ~/.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, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentSessionKey: sessionKey,
        }),
      };
    },
    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, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Yeni bir yetenek ekleme

1. Çekirdek sözleşmesini tanımlayın. Çekirdeğin hangi paylaşılan davranışa sahip olması gerektiğine karar verin: ilke, geri dönüş, yapılandırma birleştirme, yaşam döngüsü, kanal odaklı anlamlar ve çalışma zamanı yardımcısının şekli.
2. Türü belirlenmiş Plugin kayıt/çalışma zamanı yüzeylerini ekleyin. En küçük kullanışlı türü belirlenmiş yetenek yüzeyiyle OpenClawPluginApi ve/veya api.runtime öğesini genişletin.
3. Çekirdek ile kanal/özellik tüketicilerini bağlayın. Kanallar ve özellik Pluginleri, bir sağlayıcı uygulamasını doğrudan içe aktarmak yerine yeni yeteneği çekirdek üzerinden tüketmelidir.
4. Sağlayıcı uygulamalarını kaydedin. Ardından sağlayıcı Pluginleri kendi arka uçlarını yeteneğe 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 türleri
• src/<capability>/runtime.ts içindeki çekirdek yürütücüsü/ç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ıları
• özellik/kanal Pluginlerinin bunu tüketmesi gerektiğinde src/plugins/runtime/* içindeki Plugin çalışma zamanı sunumu
• 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 belgeleri

​

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

// 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"]);

• çekirdek, yetenek sözleşmesinin ve orkestrasyonun sahibidir
• sağlayıcı Pluginleri, sağlayıcı uygulamalarının sahibidir
• özellik/kanal Pluginleri çalışma zamanı yardımcılarını tüketir
• sözleşme testleri sahipliği açık tutar

​

İlgili

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