​

Plugin İç Yapıları

​

Açık yetenek modeli

​

Dış uyumluluk duruşu

• mevcut dış plugin’ler: hook tabanlı entegrasyonları çalışır durumda tutun; bunu uyumluluk tabanı olarak kabul edin
• yeni paketlenmiş/yerel plugin’ler: satıcıya özgü doğrudan erişimler veya yeni yalnızca-hook tasarımları yerine açık yetenek kaydını tercih edin
• yetenek kaydını benimseyen dış plugin’ler: buna izin verilir, ancak belgeler bir sözleşmeyi açıkça kararlı olarak işaretlemedikçe yeteneğe özgü yardımcı yüzeyleri gelişen yapılar olarak değerlendirin

• yetenek kayıt API’leri amaçlanan yöndür
• geçiş süresince dış plugin’ler için eski hook’lar en güvenli bozulmasız yol olmaya devam eder
• dışa aktarılan yardımcı alt yolların hepsi eşit değildir; tesadüfi yardımcı dışa aktarımları yerine belgelenmiş dar sözleşmeyi tercih edin

​

Plugin şekilleri

• plain-capability — tam olarak bir yetenek türü kaydeder (örneğin, mistral gibi yalnızca sağlayıcı plugin’i)
• hybrid-capability — birden çok yetenek türü kaydeder (örneğin, openai metin çıkarımı, konuşma, medya anlama ve görsel üretimine sahiptir)
• hook-only — yalnızca hook’lar (türlü veya özel) kaydeder; yetenek, araç, komut veya hizmet kaydetmez
• non-capability — araçlar, komutlar, hizmetler veya rotalar kaydeder ama yetenek kaydetmez

​

Eski hook’lar

• çalışır durumda tutun
• eski olarak belgelendirin
• model/sağlayıcı geçersiz kılma işleri için before_model_resolve tercih edin
• istem değişikliği işleri için before_prompt_build tercih edin
• yalnızca gerçek kullanım azaldığında ve fixture kapsamı geçiş güvenliğini kanıtladığında kaldırın

​

Uyumluluk sinyalleri

​

Mimariye genel bakış

1. Manifest + keşif OpenClaw, aday plugin’leri yapılandırılmış yollardan, çalışma alanı köklerinden, genel uzantı köklerinden ve paketlenmiş uzantılardan bulur. Keşif, önce yerel openclaw.plugin.json manifest dosyalarını ve desteklenen paket manifestlerini okur.
2. Etkinleştirme + doğrulama Çekirdek, keşfedilen bir plugin’in etkin, devre dışı, engellenmiş veya bellek gibi münhasır bir yuva için seçilmiş olup olmadığına karar verir.
3. Çalışma zamanı yükleme Yerel OpenClaw plugin’leri jiti aracılığıyla aynı süreç içinde yüklenir ve yetenekleri merkezi bir kayıt sistemine kaydeder. Uyumlu paketler ise çalışma zamanı kodu içe aktarılmadan kayıt kayıtlarına normalize edilir.
4. Yüzey tüketimi OpenClaw’un geri kalanı araçları, kanalları, sağlayıcı kurulumunu, hook’ları, HTTP rotalarını, CLI komutlarını ve hizmetleri açığa çıkarmak için kayıt sistemini okur.

• ayrıştırma zamanı meta verisi registerCli(..., { descriptors: [...] }) içinden gelir
• gerçek plugin CLI modülü tembel kalabilir ve ilk çağrıda kayıt olabilir

• keşif + yapılandırma doğrulaması, plugin kodu çalıştırılmadan manifest/şema meta verisinden çalışabilmelidir
• yerel çalışma zamanı davranışı, plugin modülünün register(api) yolundan gelir

​

Kanal plugin’leri ve paylaşılan mesaj aracı

• çekirdek, paylaşılan message araç ana bilgisayarına, istem kablolamasına, oturum/iş parçacığı muhasebesine ve yürütme dağıtımına sahiptir
• kanal plugin’leri kapsamlı eylem keşfi, yetenek keşfi ve kanala özgü tüm şema parçalarına sahiptir
• kanal plugin’leri, konuşma kimliklerinin iş parçacığı kimliklerini nasıl kodladığı veya üst konuşmalardan nasıl devraldığı gibi sağlayıcıya özgü oturum konuşma dil bilgisine sahiptir
• kanal plugin’leri son eylemi eylem bağdaştırıcıları üzerinden yürütür

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• güvenilir gelen requesterSenderId

• outbound.sendPoll, ortak anket modeline uyan kanallar için paylaşılan temel yoldur
• actions.handleAction("poll"), kanala özgü anket anlamları veya ek anket parametreleri için tercih edilen yoldur

​

Yetenek sahipliği modeli

• bir şirket plugin’i genellikle o şirkete ait tüm OpenClaw yüzeylerine sahip olmalıdır
• bir özellik plugin’i, genellikle tanıttığı tam özellik yüzeyine sahip olmalıdır
• kanallar, sağlayıcı davranışını geçici biçimde yeniden uygulamak yerine ortak çekirdek yeteneklerini tüketmelidir

• paketlenmiş openai plugin’i OpenAI model-sağlayıcı davranışına ve OpenAI konuşma + gerçek zamanlı ses + medya-anlama + görsel-üretim davranışına sahiptir
• paketlenmiş elevenlabs plugin’i ElevenLabs konuşma davranışına sahiptir
• paketlenmiş microsoft plugin’i Microsoft konuşma davranışına sahiptir
• paketlenmiş google plugin’i Google model-sağlayıcı davranışına ve ayrıca Google medya-anlama + görsel-üretim + web-arama davranışına sahiptir
• paketlenmiş firecrawl plugin’i Firecrawl web-getirme davranışına sahiptir
• paketlenmiş minimax, mistral, moonshot ve zai plugin’leri medya-anlama arka uçlarına sahiptir
• paketlenmiş qwen plugin’i Qwen metin-sağlayıcı davranışına ve ayrıca medya-anlama ile video-üretim davranışına sahiptir
• voice-call plugin’i bir özellik plugin’idir: çağrı taşımasını, araçları, CLI’yi, rotaları ve Twilio medya-akışı köprülemesini sahiplenir, ancak satıcı plugin’lerini doğrudan içe aktarmak yerine paylaşılan konuşma ile gerçek zamanlı yazıya dökme ve gerçek zamanlı ses yeteneklerini tüketir

• OpenAI, metin modelleri, konuşma, görseller ve gelecekte video kapsasa bile tek bir plugin’de yaşar
• başka bir satıcı da kendi yüzey alanı için aynı şeyi yapabilir
• kanallar hangi satıcı plugin’inin sağlayıcıya sahip olduğunu önemsemez; çekirdek tarafından açığa çıkarılan paylaşılan yetenek sözleşmesini tüketirler

• plugin = sahiplik sınırı
• capability = birden fazla plugin’in uygulayabildiği veya tüketebildiği çekirdek sözleşmesi

1. eksik yeteneği çekirdekte tanımlayın
2. bunu plugin API’si/çalışma zamanı üzerinden türlü şekilde açığa çıkarın
3. kanalları/özellikleri bu yeteneğe bağlayın
4. satıcı plugin’lerinin uygulamaları kaydetmesine izin verin

​

Yetenek katmanlaması

• çekirdek yetenek katmanı: paylaşılan orkestrasyon, politika, geri dönüş, yapılandırma birleştirme kuralları, teslim semantiği ve türlü sözleşmeler
• satıcı plugin katmanı: satıcıya özgü API’ler, kimlik doğrulama, model katalogları, konuşma sentezi, görsel üretimi, gelecekte video arka uçları, kullanım uç noktaları
• kanal/özellik plugin katmanı: çekirdek yetenekleri tüketen ve bunları bir yüzeyde sunan Slack/Discord/voice-call/vb. entegrasyonları

• çekirdek, yanıt zamanı TTS politikasına, geri dönüş sırasına, tercihlere ve kanal teslimatına sahiptir
• openai, elevenlabs ve microsoft sentez uygulamalarına sahiptir
• voice-call, telefon TTS çalışma zamanı yardımcısını tüketir

​

Çok yetenekli şirket plugin’i örneği

import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
import {
  describeImageWithModel,
  transcribeOpenAiCompatibleAudio,
} from "openclaw/plugin-sdk/media-understanding";

const plugin: OpenClawPluginDefinition = {
  id: "exampleai",
  name: "ExampleAI",
  register(api) {
    api.registerProvider({
      id: "exampleai",
      // auth/model catalog/runtime hooks
    });

    api.registerSpeechProvider({
      id: "exampleai",
      // vendor speech config — implement the SpeechProviderPlugin interface directly
    });

    api.registerMediaUnderstandingProvider({
      id: "exampleai",
      capabilities: ["image", "audio", "video"],
      async describeImage(req) {
        return describeImageWithModel({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
      async transcribeAudio(req) {
        return transcribeOpenAiCompatibleAudio({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
    });

    api.registerWebSearchProvider(
      createPluginBackedWebSearchProvider({
        id: "exampleai-search",
        // credential + fetch logic
      }),
    );
  },
};

export default plugin;

• tek bir plugin satıcı yüzeyine sahiptir
• çekirdek yine de yetenek sözleşmelerine sahiptir
• kanallar ve özellik plugin’leri satıcı kodunu değil api.runtime.* yardımcılarını tüketir
• sözleşme testleri, plugin’in sahip olduğunu iddia ettiği yetenekleri kaydettiğini doğrulayabilir

​

Yetenek örneği: video anlama

1. çekirdek medya-anlama sözleşmesini tanımlar
2. satıcı plugin’leri duruma göre describeImage, transcribeAudio ve describeVideo kaydeder
3. kanallar ve özellik plugin’leri, doğrudan satıcı koduna bağlanmak yerine paylaşılan çekirdek davranışı tüketir

​

Sözleşmeler ve zorunlu kılma

• plugin yazarları tek ve kararlı bir iç standarda sahip olur
• çekirdek, aynı sağlayıcı kimliğini iki plugin’in kaydetmesi gibi yinelenen sahipliği reddedebilir
• başlangıç, bozuk kayıtlar için uygulanabilir tanılar gösterebilir
• sözleşme testleri, paketlenmiş plugin sahipliğini zorunlu kılabilir ve sessiz kaymayı önleyebilir

1. çalışma zamanı kayıt zorunluluğu Plugin kayıt sistemi, plugin’ler yüklenirken kayıtları doğrular. Örnekler: yinelenen sağlayıcı kimlikleri, yinelenen konuşma sağlayıcı kimlikleri ve bozuk kayıtlar, tanımsız davranış yerine plugin tanıları üretir.
2. sözleşme testleri Paketlenmiş plugin’ler, test çalışmaları sırasında sözleşme kayıtlarına yakalanır; böylece OpenClaw sahipliği açıkça doğrulayabilir. Bugün bu, model sağlayıcıları, konuşma sağlayıcıları, web arama sağlayıcıları ve paketlenmiş kayıt sahipliği için kullanılmaktadır.

​

Bir sözleşmeye neler aittir

• türlüdür
• küçüktür
• yeteneğe özeldir
• çekirdeğe aittir
• birden çok plugin tarafından yeniden kullanılabilir
• satıcı bilgisi olmadan kanallar/özellikler tarafından tüketilebilir

• çekirdekte gizlenmiş satıcıya özgü politika
• kayıt sistemini atlayan tek seferlik plugin kaçış delikleri
• kanal kodunun doğrudan bir satıcı uygulamasına ulaşması
• OpenClawPluginApi veya api.runtime parçası olmayan geçici çalışma zamanı nesneleri

​

Yürütme modeli

• yerel bir plugin araçlar, ağ işleyicileri, hook’lar ve hizmetler kaydedebilir
• yerel bir plugin hatası ağ geçidini çökertebilir veya kararsızlaştırabilir
• kötü niyetli bir yerel plugin, OpenClaw süreci içinde keyfi kod yürütmeye eşdeğerdir

• plugins.allow, kaynak kökenine değil plugin kimliklerine güvenir.
• Paketlenmiş bir plugin ile aynı kimliğe sahip bir çalışma alanı plugin’i, etkinleştirildiğinde/izin listesine eklendiğinde paketlenmiş kopyayı kasıtlı olarak gölgeler.
• Bu normaldir ve yerel geliştirme, yama testi ve düzeltmeler için faydalıdır.

​

Dışa aktarma sınırı

• paketlenmiş plugin’e özgü yardımcı alt yollar
• açık API olması amaçlanmayan çalışma zamanı tesisat alt yolları
• satıcıya özgü kolaylık yardımcıları
• uygulama ayrıntısı olan kurulum/başlangıç yardımcı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 jiti aracılığıyla yükler
7. yerel register(api) (veya eski bir takma ad olan activate(api)) hook’larını çağırır ve kayıtları plugin kayıt sisteminde toplar
8. kayıt sistemini komut/çalışma zamanı yüzeylerine açar

​

Önce manifest davranışı

• plugin’i tanımlamak
• beyan edilen kanalları/Skills/yapılandırma şemasını veya paket yeteneklerini keşfetmek
• plugins.entries.<id>.config doğrulamak
• Control UI etiketlerini/yer tutucularını zenginleştirmek
• yükleme/katalog meta verilerini göstermek

​

Yükleyicinin önbelleğe aldığı şeyler

• keşif sonuçları
• manifest kayıt verileri
• yüklenmiş plugin kayıtları

• Bu önbellekleri devre dışı bırakmak için OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1 veya OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1 ayarlayın.
• Önbellek pencerelerini OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS ve OPENCLAW_PLUGIN_MANIFEST_CACHE_MS ile ayarlayın.

​

Kayıt modeli

• plugin kayıtları (kimlik, kaynak, köken, durum, tanılar)
• araçlar
• eski hook’lar ve türlü hook’lar
• kanallar
• sağlayıcılar
• gateway RPC işleyicileri
• HTTP rotaları
• CLI kaydedicileri
• arka plan hizmetleri
• plugin’in sahip olduğu komutlar

• plugin modülü -> kayıt sistemi kaydı
• çekirdek çalışma zamanı -> kayıt sistemi 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: onaylanan istekler için çözülmüş bağlama
• request: özgün istek özeti, ayırma ipucu, gönderici kimliği ve konuşma meta verisi

​

Sağlayıcı çalışma zamanı hook’ları

• manifest meta verisi: çalışma zamanı yüklemeden önce düşük maliyetli ortam tabanlı kimlik doğrulama araması için providerAuthEnvVars; ayrıca çalışma zamanı yüklemeden önce düşük maliyetli onboarding/auth-choice etiketleri ve CLI bayrağı meta verisi için providerAuthChoices
• yapılandırma zamanı hook’ları: catalog / eski discovery ve applyConfigDefaults
• çalışma zamanı hook’ları: normalizeModelId, normalizeTransport, normalizeConfig, applyNativeStreamingUsageCompat, resolveConfigApiKey, resolveSyntheticAuth, shouldDeferSyntheticProfileAuth, resolveDynamicModel, prepareDynamicModel, normalizeResolvedModel, contributeResolvedModelCompat, capabilities, normalizeToolSchemas, inspectToolSchemas, resolveReasoningOutputMode, prepareExtraParams, createStreamFn, wrapStreamFn, resolveTransportTurnState, resolveWebSocketSessionPolicy, formatApiKey, refreshOAuth, buildAuthDoctorHint, matchesContextOverflowError, classifyFailoverReason, isCacheTtlEligible, buildMissingAuthMessage, suppressBuiltInModel, augmentModelCatalog, isBinaryThinking, supportsXHighThinking, resolveDefaultThinkingLevel, isModernModelRef, prepareRuntimeAuth, resolveUsageAuth, fetchUsageSnapshot, createEmbeddingProvider, buildReplayPolicy, sanitizeReplayHistory, validateReplayTurns, onModelSelected

​

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

• Anthropic, resolveDynamicModel, capabilities, buildAuthDoctorHint, resolveUsageAuth, fetchUsageSnapshot, isCacheTtlEligible, resolveDefaultThinkingLevel, applyConfigDefaults, isModernModelRef ve wrapStreamFn kullanır; çünkü Claude 4.6 ileri uyumluluğuna, sağlayıcı-ailesi ipuçlarına, auth onarım rehberliğine, kullanım uç noktası entegrasyonuna, istem önbelleği uygunluğuna, auth farkında yapılandırma varsayılanlarına, Claude varsayılan/uyarlamalı düşünme politikasına ve beta üstbilgileri, /fast / serviceTier ve context1m için Anthropic’e özgü akış şekillendirmesine sahiptir.
• Anthropic’in Claude’a özgü akış yardımcıları şimdilik paketlenmiş plugin’in kendi açık api.ts / contract-api.ts yüzeyinde kalır. Bu paket yüzeyi, genel SDK’yı tek bir sağlayıcının beta-header kuralları etrafında genişletmek yerine wrapAnthropicProviderStream, resolveAnthropicBetas, resolveAnthropicFastMode, resolveAnthropicServiceTier ve daha düşük seviyeli Anthropic sarmalayıcı kurucularını dışa aktarır.
• OpenAI, resolveDynamicModel, normalizeResolvedModel ve capabilities ile birlikte buildMissingAuthMessage, suppressBuiltInModel, augmentModelCatalog, supportsXHighThinking ve isModernModelRef kullanır; çünkü GPT-5.4 ileri uyumluluğuna, doğrudan OpenAI openai-completions -> openai-responses normalizasyonuna, Codex farkında auth ipuçlarına, Spark bastırmasına, sentetik OpenAI liste satırlarına ve GPT-5 düşünme / canlı-model politikasına sahiptir; openai-responses-defaults akış ailesi ise atıf üstbilgileri, /fast/serviceTier, metin ayrıntı seviyesi, yerel Codex web arama, reasoning-compat yük şekillendirme ve Responses bağlam yönetimi için paylaşılan yerel OpenAI Responses sarmalayıcılarına sahiptir.
• OpenRouter, geçişli olduğu ve yeni model kimliklerini OpenClaw’un statik kataloğu güncellenmeden önce açığa çıkarabildiği için catalog ile birlikte resolveDynamicModel ve prepareDynamicModel kullanır; ayrıca sağlayıcıya özgü istek üstbilgileri, yönlendirme meta verisi, akıl yürütme yamaları ve istem önbelleği politikasını çekirdek dışında tutmak için capabilities, wrapStreamFn ve isCacheTtlEligible de kullanır. Replay politikası passthrough-gemini ailesinden gelirken, openrouter-thinking akış ailesi proxy akıl yürütme enjeksiyonuna ve desteklenmeyen model / auto atlamalarına sahiptir.
• GitHub Copilot, catalog, auth, resolveDynamicModel ve capabilities ile birlikte prepareRuntimeAuth ve fetchUsageSnapshot kullanır; çünkü sağlayıcı sahipli cihaz oturum açma, model geri dönüş davranışı, Claude döküm farklılıkları, GitHub token -> Copilot token değişimi ve sağlayıcı sahipli kullanım uç noktası gerekir.
• OpenAI Codex, catalog, resolveDynamicModel, normalizeResolvedModel, refreshOAuth ve augmentModelCatalog ile birlikte prepareExtraParams, resolveUsageAuth ve fetchUsageSnapshot kullanır; çünkü hâlâ çekirdek OpenAI taşımaları üzerinde çalışsa da taşıma/base URL normalizasyonuna, OAuth yenileme geri dönüş politikasına, varsayılan taşıma seçimine, sentetik Codex katalog satırlarına ve ChatGPT kullanım uç noktası entegrasyonuna sahiptir; doğrudan OpenAI ile aynı openai-responses-defaults akış ailesini paylaşır.
• Google AI Studio ve Gemini CLI OAuth, resolveDynamicModel, buildReplayPolicy, sanitizeReplayHistory, resolveReasoningOutputMode, wrapStreamFn ve isModernModelRef kullanır; çünkü google-gemini replay ailesi Gemini 3.1 ileri uyumluluk geri dönüşüne, yerel Gemini replay doğrulamasına, bootstrap replay temizliğine, etiketli akıl yürütme çıktısı moduna ve modern-model eşleştirmesine sahiptir; google-thinking akış ailesi ise Gemini thinking yük normalizasyonuna sahiptir; Gemini CLI OAuth ayrıca formatApiKey, resolveUsageAuth ve fetchUsageSnapshot kullanarak token biçimlendirme, token ayrıştırma ve kota uç noktası kablolamasını yapar.
• Anthropic Vertex, buildReplayPolicy’yi anthropic-by-model replay ailesi üzerinden kullanır; böylece Claude’a özgü replay temizliği, her anthropic-messages taşıması yerine Claude kimlikleriyle sınırlı kalır.
• Amazon Bedrock, buildReplayPolicy, matchesContextOverflowError, classifyFailoverReason ve resolveDefaultThinkingLevel kullanır; çünkü Anthropic-on-Bedrock trafiği için Bedrock’a özgü throttle/not-ready/context-overflow hata sınıflandırmasına sahiptir; replay politikası ise aynı yalnızca-Claude anthropic-by-model korumasını paylaşır.
• OpenRouter, Kilocode, Opencode ve Opencode Go, buildReplayPolicy kullanır passthrough-gemini replay ailesi üzerinden; çünkü Gemini modellerini OpenAI uyumlu taşımalar üzerinden proxy eder ve yerel Gemini replay doğrulaması veya bootstrap yeniden yazımları olmadan Gemini düşünce-imzası temizliğine ihtiyaç duyarlar.
• MiniMax, buildReplayPolicy kullanır hybrid-anthropic-openai replay ailesi üzerinden; çünkü tek bir sağlayıcı hem Anthropic-message hem de OpenAI uyumlu anlambilime sahiptir; Anthropic tarafında Claude’a özgü düşünme bloğu düşürmeyi korurken akıl yürütme çıktı modunu tekrar yerel moda çevirir ve minimax-fast-mode akış ailesi ortak akış yolunda fast-mode model yeniden yazımlarına sahiptir.
• Moonshot, catalog ile birlikte wrapStreamFn kullanır; çünkü hâlâ ortak OpenAI taşımasını kullanır ama sağlayıcı sahipli düşünme yükü normalizasyonuna ihtiyaç duyar; moonshot-thinking akış ailesi yapılandırma ile /think durumunu kendi yerel ikili düşünme yüküne eşler.
• Kilocode, catalog, capabilities, wrapStreamFn ve isCacheTtlEligible kullanır; çünkü sağlayıcı sahipli istek üstbilgilerine, akıl yürütme yükü normalizasyonuna, Gemini döküm ipuçlarına ve Anthropic önbellek-TTL kapılamasına ihtiyaç duyar; kilocode-thinking akış ailesi ise kilo/auto ve açık akıl yürütme yüklerini desteklemeyen diğer proxy model kimliklerini atlayarak ortak proxy akış yolunda Kilo thinking enjeksiyonunu tutar.
• Z.AI, resolveDynamicModel, prepareExtraParams, wrapStreamFn, isCacheTtlEligible, isBinaryThinking, isModernModelRef, resolveUsageAuth ve fetchUsageSnapshot kullanır; çünkü GLM-5 geri dönüşüne, tool_stream varsayılanlarına, ikili düşünme UX’ine, modern-model eşleştirmesine ve hem kullanım auth’ına hem kota getirmeye sahiptir; tool-stream-default-on akış ailesi varsayılan açık tool_stream sarmalayıcısını sağlayıcı başına el yazımı yapıştırıcı dışında tutar.
• xAI, normalizeResolvedModel, normalizeTransport, contributeResolvedModelCompat, prepareExtraParams, wrapStreamFn, resolveSyntheticAuth, resolveDynamicModel ve isModernModelRef kullanır; çünkü yerel xAI Responses taşıma normalizasyonuna, Grok fast-mode takma ad yeniden yazımlarına, varsayılan tool_stream, strict-tool / reasoning-payload temizliğine, plugin sahipli araçlar için geri dönüş auth tekrar kullanımına, ileri uyumlu Grok model çözümlemesine ve xAI araç-şema profili, desteklenmeyen şema anahtar kelimeleri, yerel web_search ve HTML-entity araç çağrısı bağımsız değişken çözümleme gibi sağlayıcı sahipli uyumluluk yamalarına sahiptir.
• Mistral, OpenCode Zen ve OpenCode Go, döküm/araç farklılıklarını çekirdek dışında tutmak için yalnızca capabilities kullanır.
• byteplus, cloudflare-ai-gateway, huggingface, kimi-coding, nvidia, qianfan, synthetic, together, venice, vercel-ai-gateway ve volcengine gibi yalnızca katalog sağlayan paketlenmiş sağlayıcılar yalnızca catalog kullanır.
• Qwen, metin sağlayıcısı için catalog, ayrıca çok modlu yüzeyleri için ortak medya-anlama ve video-üretim kayıtlarını kullanır.
• MiniMax ve Xiaomi, çıkarım hâlâ ortak taşımalar üzerinden çalışsa da /usage davranışları plugin sahipli olduğu için catalog ile birlikte kullanım hook’larını kullanır.

​

Ç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ı döndürür. Plugin’ler sağlayıcılar için yeniden örnekleme/kodlama yapmalıdır.
• listVoices, sağlayıcı başına isteğe bağlıdır. Bunu satıcı sahipli ses seçicileri 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.
• Bugün telefon desteği OpenAI ve ElevenLabs tarafında vardır. Microsoft’ta yoktur.

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ı sahipli sentez davranışı için konuşma sağlayıcıları kullanın.
• Eski Microsoft edge girdisi microsoft sağlayıcı kimliğine normalize edilir.
• 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örsel ve gelecekte 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 kablolamasını çekirdekte tutun.
• Satıcı davranışını sağlayıcı plugin’inde tutun.
• Toplamsal genişleme 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ı deseni 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 { 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örsel/ses/video anlama için tercih edilen paylaşılan yüzeydir.
• Çekirdek medya-anlama ses yapılandırmasını (tools.media.audio) ve sağlayıcı geri dönüş sırasını kullanır.
• Yazıya dökme çıktısı üretilmediğinde { text: undefined } döndürür (örneğin atlanan/desteklenmeyen giriş).
• api.runtime.stt.transcribeAudioFile(...) bir uyumluluk takma adı 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ıştırma başına 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’in sahip olduğu geri dönüş çalıştırmaları için operatörlerin plugins.entries.<id>.subagent.allowModelOverride: true ile açıkça izin vermesi gerekir.
• Güvenilir plugin’leri belirli kanonik provider/model hedefleriyle sınırlamak için plugins.entries.<id>.subagent.allowedModels kullanın veya açıkça herhangi bir hedefe izin vermek için "*" kullanın.
• Güvenilmeyen plugin alt ajan çalıştırmaları yine çalışır, ancak geçersiz kılma istekleri sessizce geri düşmek yerine reddedilir.

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 anlambilimini çekirdekte tutun.
• Satıcıya özgü arama taşımaları için web arama sağlayıcılarını kullanın.
• api.runtime.webSearch.*, ajan araç sarmalayıcısına bağımlı olmadan arama davranışı gereken ö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örsel üretimi sağlayıcı zincirini kullanarak bir görsel üretir.
• listProviders(...): kullanılabilir görsel ü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 auth gerektirmek için "gateway", plugin tarafından yönetilen auth/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şlediyse 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 alanını açıkça beyan etmelidir.
• Tam path + match çakışmaları, replaceExisting: true olmadıkça 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 geçiş zincirlerini yalnızca aynı auth düzeyinde tutun.
• auth: "plugin" rotaları otomatik olarak operatör çalışma zamanı kapsamları almaz. Bunlar ayrıcalıklı Gateway yardımcı çağrıları için değil, plugin tarafından yönetilen webhook/imza doğrulaması içindir.
• auth: "gateway" rotaları bir Gateway istek çalışma zamanı kapsamı içinde çalışır, ancak bu kapsam kasıtlı olarak muhafazakârdır:
  • paylaşılan gizli bearer auth (gateway.auth.mode = "token" / "password") plugin-rotası çalışma zamanı kapsamlarını, çağıran x-openclaw-scopes gönderse bile operator.write düzeyinde tutar
  • güvenilir kimlik taşıyan HTTP modları (örneğin trusted-proxy veya özel bir girişte gateway.auth.mode = "none") x-openclaw-scopes üstbilgisini yalnızca üstbilgi açıkça mevcutsa dikkate alır
  • bu kimlik taşıyan plugin-rotası isteklerinde x-openclaw-scopes yoksa, çalışma zamanı kapsamı operator.write değerine geri döner
• Pratik kural: gateway auth’lı bir plugin rotasının örtük yönetici yüzeyi olduğunu varsaymayın. Rotanızın yalnızca yöneticiye açık davranışa ihtiyacı varsa, kimlik taşıyan bir auth modu gerektirin ve açık x-openclaw-scopes üstbilgisi sözleşmesini belgelendirin.

​

Plugin SDK içe aktarma yolları

• Plugin kayıt ilkelleri için openclaw/plugin-sdk/plugin-entry.
• Genel paylaşılan plugin odaklı sözleşme için openclaw/plugin-sdk/core.
• Kök openclaw.json Zod şema dışa aktarımı (OpenClawSchema) için openclaw/plugin-sdk/config-schema.
• openclaw/plugin-sdk/channel-setup, openclaw/plugin-sdk/setup-runtime, openclaw/plugin-sdk/setup-adapter-runtime, openclaw/plugin-sdk/setup-tools, openclaw/plugin-sdk/channel-pairing, openclaw/plugin-sdk/channel-contract, openclaw/plugin-sdk/channel-feedback, openclaw/plugin-sdk/channel-inbound, openclaw/plugin-sdk/channel-lifecycle, openclaw/plugin-sdk/channel-reply-pipeline, openclaw/plugin-sdk/command-auth, openclaw/plugin-sdk/secret-input ve openclaw/plugin-sdk/webhook-ingress gibi kararlı kanal ilkelleri; paylaşılan kurulum/auth/yanıt/webhook kablolaması içindir. channel-inbound; debounce, bahsetme eşleştirme, zarf biçimlendirme ve gelen zarf bağlam yardımcılarının ortak evidir. channel-setup, dar isteğe bağlı kurulum yüzeyidir. setup-runtime, setupEntry / ertelenmiş başlangıç tarafından kullanılan, içe aktarma açısından güvenli kurulum yama bağdaştırıcılarını da içeren çalışma zamanı güvenli kurulum yüzeyidir. setup-adapter-runtime, ortama duyarlı hesap-kurulum bağdaştırıcı yüzeyidir. setup-tools, küçük CLI/arşiv/belge yardımcı yüzeyidir (formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR).
• openclaw/plugin-sdk/channel-config-helpers, openclaw/plugin-sdk/allow-from, openclaw/plugin-sdk/channel-config-schema, openclaw/plugin-sdk/telegram-command-config, openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/approval-runtime, openclaw/plugin-sdk/config-runtime, openclaw/plugin-sdk/infra-runtime, openclaw/plugin-sdk/agent-runtime, openclaw/plugin-sdk/lazy-runtime, openclaw/plugin-sdk/reply-history, openclaw/plugin-sdk/routing, openclaw/plugin-sdk/status-helpers, openclaw/plugin-sdk/text-runtime, openclaw/plugin-sdk/runtime-store ve openclaw/plugin-sdk/directory-runtime gibi alan alt yolları; paylaşılan çalışma zamanı/yapılandırma yardımcıları içindir. telegram-command-config, Telegram özel komut normalizasyonu/doğrulaması için dar açık yüzeydir ve paketlenmiş Telegram sözleşme yüzeyi geçici olarak kullanılamaz olduğunda da erişilebilir kalır. text-runtime, asistan görünür metin temizleme, markdown işleme/parçalama yardımcıları, redaksiyon yardımcıları, directive-tag yardımcıları ve güvenli metin araçları dâhil paylaşılan metin/markdown/günlük yüzeyidir.
• Onaya özgü kanal yüzeyleri, plugin üzerindeki tek bir approvalCapability sözleşmesini tercih etmelidir. Çekirdek daha sonra onay auth, teslim, render ve yerel yönlendirme davranışını bu tek yetenek üzerinden okur; ilgisiz plugin alanlarına onay davranışı karıştırmaz.
• openclaw/plugin-sdk/channel-runtime artık önerilmez ve yalnızca eski plugin’ler için uyumluluk şimi olarak kalır. Yeni kod, bunun yerine daha dar genel ilkelleri içe aktarmalıdır ve depo kodu şim için yeni içe aktarımlar eklememelidir.
• Paketlenmiş uzantı iç yapıları özel kalır. Dış plugin’ler yalnızca openclaw/plugin-sdk/* alt yollarını kullanmalıdır. OpenClaw çekirdek/test kodu, index.js, api.js, runtime-api.js, setup-entry.js ve login-qr-api.js gibi dar kapsamlı dosyalar dâhil olmak üzere bir plugin paket kökü altındaki depo açık giriş noktalarını kullanabilir. Çekirdekten veya başka bir uzantıdan hiçbir zaman bir plugin paketinin src/* yolunu içe aktarmayın.
• Depo giriş noktası ayrımı: <plugin-package-root>/api.js yardımcı/tür barrel’ıdır, <plugin-package-root>/runtime-api.js yalnızca çalışma zamanı barrel’ıdır, <plugin-package-root>/index.js paketlenmiş plugin girişidir, ve <plugin-package-root>/setup-entry.js kurulum plugin girişidir.
• Geçerli paketlenmiş sağlayıcı örnekleri:
  • Anthropic, wrapAnthropicProviderStream, beta-header yardımcıları ve service_tier ayrıştırması gibi Claude akış yardımcıları için api.js / contract-api.js kullanır.
  • OpenAI, sağlayıcı kurucuları, varsayılan model yardımcıları ve gerçek zamanlı sağlayıcı kurucuları için api.js kullanır.
  • OpenRouter, sağlayıcı kurucusu ve onboarding/config yardımcıları için api.js kullanırken, register.runtime.js depo içi kullanım için genel plugin-sdk/provider-stream yardımcılarını yeniden dışa aktarabilir.
• Facade ile yüklenen açık giriş noktaları, varsa etkin çalışma zamanı yapılandırma anlık görüntüsünü tercih eder; OpenClaw henüz çalışma zamanı anlık görüntüsü sunmuyorsa disk üzerindeki çözülmüş yapılandırma dosyasına geri düşer.
• Genel paylaşılan ilkeller, tercih edilen açık SDK sözleşmesi olmaya devam eder. Paketlenmiş kanal markalı küçük bir ayrılmış yardımcı yüzey uyumluluk için hâlâ vardır. Bunları yeni üçüncü taraf içe aktarma hedefleri olarak değil, paketlenmiş bakım/uyumluluk yüzeyleri olarak değerlendirin; yeni kanal arası sözleşmeler yine genel plugin-sdk/* alt yollarına veya plugin yerel api.js / runtime-api.js barrel’larına yerleşmelidir.

• Yeni kod için kök openclaw/plugin-sdk barrel’ından kaçının.
• Önce dar kararlı ilkelleri tercih edin. Daha yeni kurulum/eşleme/yanıt/ geri bildirim/sözleşme/gelen/iş parçacığı/komut/secret-input/webhook/infra/ allowlist/status/message-tool alt yolları, yeni paketlenmiş ve dış plugin çalışmaları için amaçlanan sözleşmedir. Hedef ayrıştırma/eşleştirme openclaw/plugin-sdk/channel-targets üzerinde olmalıdır. Mesaj eylem kapıları ve tepki message-id yardımcıları ise openclaw/plugin-sdk/channel-actions üzerinde yer almalıdır.
• Paketlenmiş uzantıya özgü yardımcı barrel’lar varsayılan olarak kararlı değildir. Bir yardımcı yalnızca paketlenmiş bir uzantı tarafından gerekiyorsa, bunu openclaw/plugin-sdk/<extension> içine yükseltmek yerine uzantının yerel api.js veya runtime-api.js yüzeyinin arkasında tutun.
• Yeni paylaşılan yardımcı yüzeyler kanal markalı değil, genel olmalıdır. Paylaşılan hedef ayrıştırma openclaw/plugin-sdk/channel-targets üzerinde yer almalıdır; kanala özgü iç yapılar ise sahip plugin’in yerel api.js veya runtime-api.js yüzeyinin arkasında kalmalıdır.
• image-generation, media-understanding ve speech gibi yeteneğe özgü alt yollar bugün paketlenmiş/yerel plugin’ler bunları kullandığı için vardır. Bunların varlığı tek başına dışa aktarılan her yardımcının uzun vadeli donmuş bir dış sözleşme olduğu anlamına gelmez.

​

Mesaj araç şemaları

• düğme ızgarası tarzı yükler için createMessageToolButtonsSchema()
• yapılandırılmış kart yükleri için createMessageToolCardSchema()

​

Kanal hedef çözümleme

• messaging.inferTargetChatType({ to }), normalize edilmiş bir hedefin dizin aramasından önce direct, group veya channel olarak değerlendirilip değerlendirilmemesine karar verir.
• messaging.targetResolver.looksLikeId(raw, normalized), bir girdinin dizin araması yerine doğrudan kimlik benzeri çözümlemeye atlaması gerekip gerekmediğini çekirdeğe söyler.
• messaging.targetResolver.resolveTarget(...), çekirdeğin normalizasyondan veya dizin kaçırmasından sonra son sağlayıcı sahipli çözümlemeye ihtiyaç duyduğunda kullandığı plugin geri dönüşüdür.
• messaging.resolveOutboundSessionRoute(...), bir hedef çözüldükten sonra sağlayıcıya özgü oturum rota kurulumuna sahiptir.

• Eşler/gruplar aranmasından önce gerçekleşmesi gereken kategori kararları için inferTargetChatType kullanın.
• “Buna açık/yerel hedef kimliği gibi davran” denetimleri için looksLikeId kullanın.
• Geniş dizin araması için değil, sağlayıcıya özgü normalizasyon geri dönüşü için resolveTarget kullanın.
• Sohbet kimlikleri, iş parçacığı kimlikleri, JID’ler, handle’lar ve oda kimlikleri gibi sağlayıcıya özgü yerel kimlikleri 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 listesi tabanlı 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
• tekilleştirme/normalizasyon yardımcıları
• ChannelDirectoryEntry[] oluşturma

​

Sağlayıcı katalogları

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

• simple: düz API anahtarı veya ortam odaklı sağlayıcılar
• profile: auth profilleri olduğunda görünen sağlayıcılar
• paired: ilişkili birden çok 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 takma ad olarak hâlâ çalışır
• hem catalog hem discovery kaydedilmişse, OpenClaw catalog kullanır

​

Salt okunur kanal incelemesi

• resolveAccount(...) çalışma zamanı yoludur. Kimlik bilgilerinin tamamen somutlaştırıldığını varsayabilir ve gerekli gizli bilgiler eksik olduğunda hızlıca başarısız olabilir.
• openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve ve doctor/config onarım akışları gibi salt okunur komut yolları; yapılandırmayı açıklamak için çalışma zamanı kimlik bilgilerini somutlaştırmak zorunda kalmamalıdır.

• Yalnızca açıklayıcı hesap durumunu döndürün.
• enabled ve configured değerlerini koruyun.
• İlgili olduğunda kimlik bilgisi kaynağı/durum alanlarını ekleyin; örneğin:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Salt okunur kullanılabilirliği raporlamak için ham belirteç değerlerini döndürmeniz gerekmez. tokenStatus: "available" döndürmek (ve eşleşen kaynak alanıyla birlikte) durum tarzı komutlar için yeterlidir.
• SecretRef ile yapılandırılmış ama geçerli komut yolunda kullanılamayan bir kimlik bilgisi için 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ı pencerede var olması gereken tüm gateway yöntemleri, araçlar veya hizmetler

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

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

​

Kanal katalog meta verisi

{
  "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: daha zengin katalog/durum yüzeyleri için ikincil etiket
• docsLabel: belge bağlantısı için bağlantı metnini geçersiz kılar
• preferOver: bu katalog girdisinin geride bırakması gereken daha düşük öncelikli plugin/kanal kimlikleri
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: seçim yüzeyi kopya denetimleri
• markdownCapable: giden biçimlendirme kararları için kanalı markdown uyumlu olarak işaretler
• showConfigured: false olduğunda kanalı yapılandırılmış kanal listeleme yüzeylerinden gizler
• quickstartAllowFrom: kanalı standart hızlı başlangıç allowFrom akışına dahil eder
• forceAccountBinding: yalnızca bir hesap olsa bile açık hesap bağlamasını zorunlu kılar
• preferSessionLookupForAnnounceTarget: duyuru hedefi çözümlemede oturum aramasını tercih eder

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

​

Bağlam motoru plugin’leri

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 }) {
      return { messages, estimatedTokens: 0 };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import { 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 }) {
      return { messages, estimatedTokens: 0 };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Yeni bir yetenek ekleme

1. çekirdek sözleşmesini tanımlayın Çekirdeğin hangi ortak davranışa sahip olması gerektiğine karar verin: politika, geri dönüş, yapılandırma birleştirme, yaşam döngüsü, kanala dönük anlambilim ve çalışma zamanı yardımcı şekli.
2. türlü plugin kayıt/çalışma zamanı yüzeyleri ekleyin OpenClawPluginApi ve/veya api.runtime yüzeyini en küçük faydalı türlü yetenek yüzeyiyle genişletin.
3. çekirdek + kanal/özellik tüketicilerini bağlayın Kanal ve özellik plugin’leri yeni yeteneği doğrudan bir satıcı uygulamasını içe aktararak değil, çekirdek üzerinden tüketmelidir.
4. satıcı uygulamalarını kaydedin Ardından satıcı plugin’leri arka uçlarını bu yeteneğe karşı kaydeder.
5. sözleşme kapsamı ekleyin Sahipliğin 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 ç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 sistemi kablolaması
• özellik/kanal plugin’lerinin tüketmesi gerektiğinde src/plugins/runtime/* altındaki 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 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(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• çekirdek yetenek sözleşmesine + orkestrasyona sahiptir
• satıcı plugin’leri satıcı uygulamalarına sahiptir
• özellik/kanal plugin’leri çalışma zamanı yardımcılarını tüketir
• sözleşme testleri sahipliği açık tutar