​

Plugin İç Yapısı

​

Genel yetenek modeli

​

Dış uyumluluk duruşu

• mevcut dış plugin’ler: kanca tabanlı entegrasyonları çalışır durumda tutun; bunu uyumluluk temeli olarak değerlendirin
• yeni paketlenmiş/yerel plugin’ler: satıcıya özgü iç erişimler veya yeni yalnızca kanca tasarımları yerine açık yetenek kaydını tercih edin
• yetenek kaydını benimseyen dış plugin’ler: izin verilir, ancak belgelerde açıkça kararlı bir sözleşme olarak işaretlenmedikçe yeteneğe özgü yardımcı yüzeyleri gelişmekte olan yüzeyler olarak değerlendirin

• yetenek kayıt API’leri amaçlanan yöndür
• geçiş sırasında eski kancalar dış plugin’ler için en güvenli, kırılmasız yol olmaya devam eder
• dışa aktarılan yardımcı alt yolların hepsi eşdeğer değildir; rastlantısal yardımcı aktarımlarını değil, belgelenmiş dar sözleşmeyi tercih edin

​

Plugin biçimleri

• plain-capability — tam olarak bir yetenek türü kaydeder (örneğin mistral gibi yalnızca sağlayıcı olan bir plugin)
• hybrid-capability — birden fazla yetenek türü kaydeder (örneğin openai, metin çıkarımı, konuşma, medya anlama ve görsel oluşturma sahipliğine sahiptir)
• hook-only — yalnızca kanca kaydeder (yazımlı veya özel), yetenek, araç, komut veya hizmet kaydetmez
• non-capability — yetenek olmadan araç, komut, hizmet veya rota kaydeder

​

Eski kancalar

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

​

Uyumluluk sinyalleri

​

Mimariye genel bakış

1. Manifest + keşif OpenClaw, yapılandırılmış yollardan, çalışma alanı köklerinden, genel uzantı köklerinden ve paketlenmiş uzantılardan aday plugin’leri bulur. Keşif önce yerel openclaw.plugin.json manifestlerini ve desteklenen paket manifestlerini okur.
2. Etkinleştirme + doğrulama Çekirdek, keşfedilen bir plugin’in etkin, devre dışı, engellenmiş veya bellek gibi özel 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 işlem içi yüklenir ve yetenekleri merkezi bir kayıt sistemine kaydeder. Uyumlu paketler, ç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, kancaları, 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 kaydolabilir

• keşif + yapılandırma doğrulaması, plugin kodu yürütülmeden 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 message aracı

• çekirdek, paylaşılan message aracı ana makinesine, istem bağlamasına, oturum/iş parçacığı muhasebesine ve yürütme sevkine sahiptir
• kanal plugin’leri kapsamlı eylem keşfine, yetenek keşfine ve kanala özgü şema parçalarına sahiptir
• kanal plugin’leri, konuşma kimliklerinin iş parçacığı kimliklerini nasıl kodladığı veya üst konuşmalardan nasıl miras aldığı gibi, sağlayıcıya özgü oturum konuşma dil bilgisine sahiptir
• kanal plugin’leri son eylemi kendi 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 şirketin OpenClaw’a dönük tüm yüzeylerine sahip olmalıdır
• bir özellik plugin’i genellikle tanıttığı özelliğin tam yüzeyine sahip olmalıdır
• kanallar, sağlayıcı davranışını geçici olarak yeniden uygulamak yerine paylaşılan çekirdek yetenekleri 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 oluşturma 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 artı Google medya anlama + görsel oluşturma + 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
• voice-call plugin’i bir özellik plugin’idir: çağrı aktarımı, araçlar, CLI, rotalar ve Twilio medya akışı köprülemesine sahiptir, 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

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

• plugin = sahiplik sınırı
• capability = birden çok plugin’in uygulayabileceği veya tüketebileceği çekirdek sözleşme

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

​

Yetenek katmanları

• çekirdek yetenek katmanı: paylaşılan orkestrasyon, politika, geri dönüş, yapılandırma birleştirme kuralları, teslimat anlamları ve yazımlı sözleşmeler
• satıcı plugin katmanı: satıcıya özgü API’ler, kimlik doğrulama, model katalogları, konuşma sentezi, görsel oluşturma, gelecekteki video arka uçları, kullanım uç noktaları
• kanal/özellik plugin katmanı: paylaşılan ç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 uygun olduğunda describeImage, transcribeAudio ve describeVideo kaydı yapar
3. kanal ve özellik plugin’leri satıcı koduna doğrudan bağlanmak yerine paylaşılan çekirdek davranışını tüketir

​

Sözleşmeler ve zorunlu uygulama

• plugin yazarları tek bir kararlı iç standart elde eder
• çekirdek, aynı sağlayıcı kimliğini kaydeden iki plugin gibi yinelenen sahipliği reddedebilir
• başlangıç, bozuk kayıtlar için uygulanabilir tanılamaları yüzeye çıkarabilir
• sözleşme testleri paketlenmiş plugin sahipliğini zorunlu kılabilir ve sessiz sürüklenmeyi önleyebilir

1. çalışma zamanı kayıt zorlaması 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ılamaları üretir.
2. sözleşme testleri Paketlenmiş plugin’ler, test çalıştırmaları sırasında sözleşme kayıt sistemlerinde 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ılır.

​

Bir sözleşmede ne bulunmalı

• yazımlıdır
• küçüktür
• yeteneğe özgüdür
• ç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 baypas eden tek seferlik plugin kaçış kapıları
• doğrudan satıcı uygulamasına erişen kanal kodu
• 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, kancalar ve hizmetler kaydedebilir
• yerel bir plugin hatası gateway’i çökertebilir veya dengesizleştirebilir
• kötü amaçlı bir yerel plugin, OpenClaw süreci içinde keyfi kod yürütmeye denktir

• 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/allowlist’e alındığında kasıtlı olarak paketlenmiş kopyayı gölgeler.
• Bu normaldir ve yerel geliştirme, yama testi ve hotfix’ler için kullanışlıdır.

​

Dışa aktarma sınırı

• paketlenmiş plugin’e özgü yardımcı alt yollar
• genel 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/katılım yardımcıları

​

Yükleme işlem 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)) kancalarını çağırır ve kayıtları plugin kayıt sisteminde toplar
8. kayıt sistemini komutlara/çalışma zamanı yüzeylerine açığa çıkarır

​

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 verisini göstermek

​

Yükleyicinin önbelleğe aldıkları

• keşif sonuçları
• manifest kayıt sistemi verisi
• yüklenmiş plugin kayıt sistemleri

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

• plugin kayıtları (kimlik, kaynak, köken, durum, tanılamalar)
• araçlar
• eski kancalar ve yazımlı kancalar
• kanallar
• sağlayıcılar
• gateway RPC işleyicileri
• HTTP rotaları
• CLI kayıtçıları
• arka plan hizmetleri
• plugin’e ait 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ğ
• request: özgün istek özeti, ayırma ipucu, gönderen kimliği ve konuşma meta verisi

​

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

• manifest meta verisi: çalışma zamanı yüklemesinden önce ucuz sağlayıcı ortam kimlik doğrulama araması için providerAuthEnvVars, kimlik doğrulamayı paylaşan sağlayıcı varyantları için providerAuthAliases, çalışma zamanı yüklemesinden önce ucuz kanal ortamı/kurulum araması için channelEnvVars, ayrıca çalışma zamanı yüklemesinden önce ucuz katılım/kimlik doğrulama seçimi etiketleri ve CLI bayrağı meta verisi için providerAuthChoices
• yapılandırma zamanı kancaları: catalog / eski discovery ile applyConfigDefaults
• çalışma zamanı kancaları: normalizeModelId, normalizeTransport, normalizeConfig, applyNativeStreamingUsageCompat, resolveConfigApiKey, resolveSyntheticAuth, resolveExternalAuthProfiles, 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

​

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

• 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, kimlik doğrulama onarım rehberliğine, kullanım uç noktası entegrasyonuna, istem önbelleği uygunluğuna, kimlik doğrulama farkındalıklı yapılandırma varsayılanlarına, Claude varsayılan/uyarlanabilir düşünme politikasına ve beta üstbilgileri, /fast / serviceTier ile context1m için Anthropic’e özgü akış şekillendirmesine sahiptir.
• Anthropic’in Claude’a özgü akış yardımcıları şimdilik paketlenmiş plugin’in kendi genel api.ts / contract-api.ts geçişinde kalır. Bu paket yüzeyi, genel SDK’yi tek bir sağlayıcının beta-header kuralları çevresinde genişletmek yerine wrapAnthropicProviderStream, resolveAnthropicBetas, resolveAnthropicFastMode, resolveAnthropicServiceTier ve daha alt düzey Anthropic sarmalayıcı oluşturucuları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ındalıklı kimlik doğrulama 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ı düzeyi, doğal Codex web arama, gerekçelendirme uyumluluğu yük şekillendirmesi ve Responses bağlam yönetimi için paylaşılan doğal OpenAI Responses sarmalayıcılarına sahiptir.
• OpenRouter; sağlayıcı bir geçiş sağlayıcısı olduğu ve OpenClaw’un durağan kataloğu güncellenmeden önce yeni model kimlikleri açığa çıkarabileceği için catalog ile birlikte resolveDynamicModel ve prepareDynamicModel kullanır; ayrıca sağlayıcıya özgü istek üstbilgilerini, yönlendirme meta verisini, gerekçelendirme yamalarını ve istem önbelleği politikasını çekirdekten uzak tutmak için capabilities, wrapStreamFn ve isCacheTtlEligible de kullanır. Yeniden oynatma politikası passthrough-gemini ailesinden gelirken, openrouter-thinking akış ailesi ise proxy gerekçelendirme ekleme ile desteklenmeyen model / auto atlamalarına sahiptir.
• GitHub Copilot; sağlayıcıya ait cihaz oturum açma, model geri dönüş davranışı, Claude transcript tuhaflıkları, GitHub belirteci -> Copilot belirteci değişimi ve sağlayıcıya ait kullanım uç noktası gerektiği için catalog, auth, resolveDynamicModel ve capabilities ile birlikte prepareRuntimeAuth ve fetchUsageSnapshot kullanır.
• OpenAI Codex; hâlâ çekirdek OpenAI aktarımları üzerinde çalışmasına rağmen kendi aktarım/temel URL normalizasyonuna, OAuth yenileme geri dönüş politikasına, varsayılan aktarım seçimine, sentetik Codex katalog satırlarına ve ChatGPT kullanım uç noktası entegrasyonuna sahip olduğu için catalog, resolveDynamicModel, normalizeResolvedModel, refreshOAuth ve augmentModelCatalog ile birlikte prepareExtraParams, resolveUsageAuth ve fetchUsageSnapshot kullanır; doğrudan OpenAI ile aynı openai-responses-defaults akış ailesini paylaşır.
• Google AI Studio ve Gemini CLI OAuth; google-gemini yeniden oynatma ailesi Gemini 3.1 ileri uyumluluk geri dönüşüne, doğal Gemini yeniden oynatma doğrulamasına, önyükleme yeniden oynatma temizliğine, etiketli gerekçelendirme-çıktı moduna ve modern model eşleştirmesine sahip olduğu için resolveDynamicModel, buildReplayPolicy, sanitizeReplayHistory, resolveReasoningOutputMode, wrapStreamFn ve isModernModelRef kullanır; google-thinking akış ailesi ise Gemini düşünme yükü normalizasyonuna sahiptir; Gemini CLI OAuth ayrıca belirteç biçimlendirme, belirteç ayrıştırma ve kota uç noktası bağlantısı için formatApiKey, resolveUsageAuth ve fetchUsageSnapshot kullanır.
• Anthropic Vertex, anthropic-by-model yeniden oynatma ailesi aracılığıyla buildReplayPolicy kullanır; böylece Claude’a özgü yeniden oynatma temizliği tüm anthropic-messages aktarımı yerine Claude kimlikleriyle sınırlı kalır.
• Amazon Bedrock; Anthropic-on-Bedrock trafiği için Bedrock’a özgü daraltma/hazır değil/bağlam taşması hata sınıflandırmasına sahip olduğu için buildReplayPolicy, matchesContextOverflowError, classifyFailoverReason ve resolveDefaultThinkingLevel kullanır; yeniden oynatma politikası ise yine aynı yalnızca-Claude anthropic-by-model korumasını paylaşır.
• OpenRouter, Kilocode, Opencode ve Opencode Go; Gemini modellerini OpenAI uyumlu aktarımlar üzerinden vekil sundukları ve doğal Gemini yeniden oynatma doğrulaması veya önyükleme yeniden yazımları olmadan Gemini düşünce-imzası temizliğine ihtiyaç duydukları için passthrough-gemini yeniden oynatma ailesi aracılığıyla buildReplayPolicy kullanır.
• MiniMax, hybrid-anthropic-openai yeniden oynatma ailesi aracılığıyla buildReplayPolicy kullanır çünkü tek bir sağlayıcı hem Anthropic-message hem de OpenAI uyumlu anlamlara sahiptir; Anthropic tarafında yalnızca Claude’a özgü düşünme bloğu düşürmeyi sürdürürken gerekçelendirme çıktı modunu tekrar doğala geçersiz kılar ve minimax-fast-mode akış ailesi paylaşılan akış yolunda hızlı mod model yeniden yazımlarına sahiptir.
• Moonshot; hâlâ paylaşılan OpenAI aktarımını kullandığı ancak sağlayıcıya ait düşünme yükü normalizasyonuna ihtiyaç duyduğu için catalog ile birlikte wrapStreamFn kullanır; moonshot-thinking akış ailesi ise yapılandırma ile /think durumunu kendi doğal ikili düşünme yüküne eşler.
• Kilocode; sağlayıcıya ait istek üstbilgilerine, gerekçelendirme yükü normalizasyonuna, Gemini transcript ipuçlarına ve Anthropic önbellek-TTL geçitlemesine ihtiyaç duyduğu için catalog, capabilities, wrapStreamFn ve isCacheTtlEligible kullanır; kilocode-thinking akış ailesi ise paylaşılan proxy akış yolunda Kilo düşünme eklemeyi tutarken kilo/auto ve açık gerekçelendirme yüklerini desteklemeyen diğer proxy model kimliklerini atlar.
• Z.AI; 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 kimlik doğrulaması hem de kota getirmeye sahip olduğu için resolveDynamicModel, prepareExtraParams, wrapStreamFn, isCacheTtlEligible, isBinaryThinking, isModernModelRef, resolveUsageAuth ve fetchUsageSnapshot kullanır; tool-stream-default-on akış ailesi ise varsayılan açık tool_stream sarmalayıcısını sağlayıcı başına elle yazılmış yapıştırma kodundan uzak tutar.
• xAI; doğal xAI Responses aktarımı normalizasyonuna, Grok hızlı mod takma ad yeniden yazımlarına, varsayılan tool_streame, katı araç / gerekçelendirme yükü temizliğine, plugin’e ait araçlar için geri dönüş kimlik doğrulaması yeniden kullanımına, ileri uyumluluk Grok model çözümlemesine ve xAI araç-şema profili, desteklenmeyen şema anahtar sözcükleri, doğal web_search ve HTML varlık araç çağrısı argüman çözümlemesi gibi sağlayıcıya ait uyumluluk yamalarına sahip olduğu için normalizeResolvedModel, normalizeTransport, contributeResolvedModelCompat, prepareExtraParams, wrapStreamFn, resolveSyntheticAuth, resolveDynamicModel ve isModernModelRef kullanır.
• Mistral, OpenCode Zen ve OpenCode Go; transcript/araç tuhaflıklarını çekirdekten uzak 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 kullanan paketlenmiş sağlayıcılar yalnızca catalog kullanır.
• Qwen, metin sağlayıcısı için catalog ile birlikte çok modlu yüzeyleri için paylaşılan medya-anlama ve video-oluşturma kayıtlarını kullanır.
• MiniMax ve Xiaomi, çıkarım hâlâ paylaşılan aktarımlardan geçse de /usage davranışları plugin’e ait olduğu için catalog ile birlikte kullanım kancaları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. Satıcıya ait ses seçiciler veya kurulum akışları için kullanın.
• Ses listeleri yerel ayar, cinsiyet ve kişilik etiketleri gibi daha zengin meta veriler içerebilir.
• OpenAI ve ElevenLabs bugün telefon desteği sunuyor. Microsoft sunmuyor.

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 teslimatını çekirdekte tutun.
• Satıcıya ait 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: tek bir satıcı plugin’i OpenClaw bu yetenek sözleşmelerini ekledikçe metin, konuşma, görsel 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ğlamasını çekirdekte tutun.
• Satıcı davranışını sağlayıcı plugin’inde tutun.
• Artımlı genişleme yazımlı kalmalıdır: yeni isteğe bağlı yöntemler, yeni isteğe bağlı sonuç alanları, yeni isteğe bağlı yetenekler.
• Video oluşturma 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.
• Hiçbir yazıya dökme çıktısı üretilmediğinde { text: undefined } döndürür (örneğin atlanan/desteklenmeyen girdi).
• api.runtime.stt.transcribeAudioFile(...) 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ış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 açıkça izin vermelidir.
• 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ı yine de çalışır, ancak geçersiz kılma istekleri sessizce geri dönmek 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 anlamlarını çekirdekte tutun.
• Satıcıya özgü arama aktarımları için web arama sağlayıcıları kullanın.
• api.runtime.webSearch.*, ajan 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: "A friendly lobster mascot", size: "1024x1024" },
});

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

• generate(...): yapılandırılmış görsel oluşturma sağlayıcı zincirini kullanarak görsel oluşturur.
• listProviders(...): kullanılabilir görsel oluşturma 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: gerekli. Normal gateway kimlik doğrulaması gerektirmek için "gateway", plugin tarafından yönetilen kimlik doğrulama/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ürmelidir.

• 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 çakışan rotalar reddedilir. exact/prefix ardışık geçiş zincirlerini yalnızca aynı kimlik doğrulama 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’lar/imza doğrulaması içindir.
• auth: "gateway" rotaları bir Gateway istek çalışma zamanı kapsamında çalışır, ancak bu kapsam bilerek muhafazakârdır:
  • paylaşılan gizli bearer kimlik doğrulaması (gateway.auth.mode = "token" / "password") kullanıldığında, çağıran x-openclaw-scopes gönderse bile plugin-rotası çalışma zamanı kapsamları operator.write olarak sabitlenir
  • güvenilir kimlik taşıyan HTTP modları (örneğin trusted-proxy veya özel girişte gateway.auth.mode = "none") x-openclaw-scopes değerini 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üşer
• Pratik kural: gateway kimlik doğrulamalı bir plugin rotasının örtük bir yönetici yüzeyi olduğunu varsaymayın. Rotanız yöneticiye özel davranış gerektiriyorsa, kimlik taşıyan bir kimlik doğrulama modu isteyin 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’e dönük 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/kimlik doğrulama/yanıt/webhook bağlaması içindir. channel-inbound; debounce, mention eşleştirme, gelen mention-policy yardımcıları, zarf biçimlendirme ve gelen zarf bağlam yardımcıları için paylaşılan yuvadır. channel-setup, dar isteğe bağlı kurulum geçişidir. 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ı dahil çalışma zamanı güvenli kurulum yüzeyidir. setup-adapter-runtime, ortama duyarlı hesap-kurulum bağdaştırıcısı geçişidir. setup-tools, küçük CLI/arşiv/belge yardımcı geçişidir (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-gateway-runtime, openclaw/plugin-sdk/approval-handler-adapter-runtime, openclaw/plugin-sdk/approval-handler-runtime, 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 genel geçiştir ve paketlenmiş Telegram sözleşme yüzeyi geçici olarak kullanılamasa bile kullanılabilir kalır. text-runtime, yardımcıya görünür metin çıkarma, markdown render/parçalama yardımcıları, sansürleme yardımcıları, yönerge etiketi yardımcıları ve güvenli metin yardımcıları dahil paylaşılan metin/markdown/günlükleme geçişidir.
• Onaya özgü kanal geçişleri, plugin üzerinde tek bir approvalCapability sözleşmesini tercih etmelidir. Çekirdek daha sonra onay kimlik doğrulaması, teslimat, render, doğal yönlendirme ve tembel doğal işleyici davranışını alakasız plugin alanlarına karıştırmak yerine bu tek yetenek üzerinden okur.
• openclaw/plugin-sdk/channel-runtime kullanımdan kaldırılmıştır ve yalnızca eski plugin’ler için uyumluluk geçişi olarak kalır. Yeni kod bunun yerine daha dar genel ilkelleri içe aktarmalıdır ve repo kodu bu geçiş için yeni içe aktarmalar eklememelidir.
• Paketlenmiş uzantı iç yapıları özel kalır. Dış plugin’ler yalnızca openclaw/plugin-sdk/* alt yollarını kullanmalıdır. OpenClaw çekirdeği/test kodu, index.js, api.js, runtime-api.js, setup-entry.js ve login-qr-api.js gibi dar kapsamlı dosyalar gibi bir plugin paket kökü altındaki repo genel giriş noktalarını kullanabilir. Çekirdekten veya başka bir uzantıdan asla bir plugin paketinin src/* yolunu içe aktarmayın.
• Repo giriş noktası ayrımı: <plugin-package-root>/api.js yardımcı/türler varilidir, <plugin-package-root>/runtime-api.js yalnızca çalışma zamanı varilidir, <plugin-package-root>/index.js paketlenmiş plugin girişidir, ve <plugin-package-root>/setup-entry.js kurulum plugin girişidir.
• Güncel 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ı oluşturucuları, varsayılan model yardımcıları ve gerçek zamanlı sağlayıcı oluşturucuları için api.js kullanır.
  • OpenRouter, kendi sağlayıcı oluşturucusu ve katılım/yapılandırma yardımcıları için api.js kullanırken register.runtime.js, repo içi kullanım için genel plugin-sdk/provider-stream yardımcılarını yeniden dışa aktarabilir.
• Yüklenen yüzler üzerinden gelen genel giriş noktaları, mevcutsa 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 diskteki çözülmüş yapılandırma dosyasına geri döner.
• Genel paylaşılan ilkeller tercih edilen genel SDK sözleşmesi olmaya devam eder. Kanal markalı küçük, ayrılmış bir uyumluluk kümesi hâlâ mevcuttur. Bunları yeni üçüncü taraf içe aktarma hedefleri olarak değil, paket bakımı/uyumluluk geçişleri olarak değerlendirin; yeni çapraz kanal sözleşmeleri yine genel plugin-sdk/* alt yollarında veya plugin’in yerel api.js / runtime-api.js varillerinde yer almalıdır.

• Yeni kod için kök openclaw/plugin-sdk varilinden kaçının.
• Önce dar kararlı ilkelleri tercih edin. Daha yeni setup/pairing/reply/ feedback/contract/inbound/threading/command/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 eylemi geçitleri ve tepki mesaj kimliği yardımcıları openclaw/plugin-sdk/channel-actions üzerinde olmalıdır.
• Paketlenmiş uzantıya özgü yardımcı varilleri varsayılan olarak kararlı değildir. Eğer 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 geçişi arkasında tutun.
• Yeni paylaşılan yardımcı geçişleri kanal markalı değil, genel olmalıdır. Paylaşılan hedef ayrıştırma openclaw/plugin-sdk/channel-targets üzerinde olmalıdır; kanala özgü iç yapılar ise sahip plugin’in yerel api.js veya runtime-api.js geçişi 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 vadede sabitlenmiş bir dış sözleşme olduğu anlamına gelmez.

​

Message aracı ş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 ele alınıp alınmayacağına karar verir.
• messaging.targetResolver.looksLikeId(raw, normalized), bir girdinin dizin araması yerine doğrudan kimlik benzeri çözümlemeye atlayıp atlamayacağını çekirdeğe söyler.
• messaging.targetResolver.resolveTarget(...), çekirdeğin normalizasyondan veya dizin kaçırmasından sonra son sağlayıcıya ait çözümlemeye ihtiyaç duyduğunda plugin geri dönüş yoludur.
• messaging.resolveOutboundSessionRoute(...), hedef çözüldükten sonra sağlayıcıya özgü oturum rota kurulumuna sahiptir.

• eşler/gruplar aranmadan önce gerçekleşmesi gereken kategori kararları için inferTargetChatType kullanın.
• “bunu açık/doğal hedef kimliği olarak işle” 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, tanıtıcılar ve oda kimlikleri gibi sağlayıcıya özgü doğal kimlikleri genel SDK alanlarında değil target değerlerinde veya sağlayıcıya özgü parametrelerde tutun.

​

Yapılandırma destekli dizinler

• allowlist güdümlü DM eşleri
• yapılandırılmış kanal/grup haritaları
• hesap kapsamlı durağan dizin geri dönüşleri

• sorgu filtreleme
• limit uygulama
• tekilleştirme/normalizasyon yardımcıları
• ChannelDirectoryEntry[] oluşturma

​

Sağlayıcı katalogları

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

• simple: düz API anahtarı veya ortam güdümlü sağlayıcılar
• profile: kimlik doğrulama 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 takma ad olarak hâlâ çalışır
• hem catalog hem discovery kayıtlıysa OpenClaw catalog kullanır

​

Salt okunur kanal inceleme

• resolveAccount(...) çalışma zamanı yoludur. Kimlik bilgilerinin tamamen somutlaştığını varsayabilir ve gerekli sırlar eksik olduğunda hızlıca hata verebilir.
• openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve ve doctor/config onarım akışları gibi salt okunur komut yollarının, yapılandırmayı açıklamak için çalışma zamanı kimlik bilgilerini somutlaştırması gerekmez.

• Yalnızca açıklayıcı hesap durumu döndürün.
• enabled ve configured değerlerini koruyun.
• Gerektiğinde şu gibi kimlik bilgisi kaynağı/durum alanları ekleyin:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Salt okunur kullanılabilirliği bildirmek için ham belirteç değerlerini döndürmeniz gerekmez. Durum tarzı komutlar için tokenStatus: "available" (ve eşleşen kaynak alanı) döndürmek yeterlidir.
• Bir kimlik bilgisi SecretRef üzerinden 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 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"
    }
  }
}

• daha zengin katalog/durum yüzeyleri için detailLabel: ikincil etiket
• belge bağlantısı metnini geçersiz kılmak için docsLabel
• bu katalog girdisinin geride bırakması gereken daha düşük öncelikli plugin/kanal kimlikleri için preferOver
• seçim yüzeyi metin denetimleri için selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras
• giden biçimlendirme kararları için kanalın markdown yeteneğine sahip olduğunu işaretleyen markdownCapable
• false olarak ayarlandığında kanalı yapılandırılmış kanal listeleme yüzeylerinden gizleyen exposure.configured
• false olarak ayarlandığında kanalı etkileşimli kurulum/yapılandırma seçicilerinden gizleyen exposure.setup
• belge gezinme yüzeyleri için kanalı dahili/özel olarak işaretleyen exposure.docs
• uyumluluk için eski takma adlar hâlâ kabul edilir: showConfigured / showInSetup; tercih edilen alan exposuredur
• kanalı standart hızlı başlangıç allowFrom akışına dâhil eden quickstartAllowFrom
• yalnızca tek hesap olsa bile açık hesap bağlamasını zorunlu kılan forceAccountBinding
• duyuru hedeflerini çözerken oturum aramasını tercih eden preferSessionLookupForAnnounceTarget

• ~/.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", () => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

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

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

​

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: politika, geri dönüş, yapılandırma birleştirme, yaşam döngüsü, kanala dönük anlamlar ve çalışma zamanı yardımcı biçimi.
2. yazımlı plugin kayıt/çalışma zamanı yüzeyleri ekleyin En küçük yararlı yazımlı yetenek yüzeyiyle OpenClawPluginApi ve/veya api.runtime öğesini genişletin.
3. çekirdek + kanal/özellik tüketicilerini bağlayın Kanal ve özellik plugin’leri yeni yeteneği bir satıcı uygulamasını doğrudan içe aktararak değil, çekirdek üzerinden tüketmelidir.
4. satıcı uygulamalarını kaydedin Satıcı plugin’leri ardından arka uçlarını bu yeteneğe kaydeder.
5. sözleşme kapsamı ekleyin Sahiplik ve kayıt biçimi zaman içinde açık kalsın diye 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 bağlaması
• özellik/kanal plugin’lerinin bunu 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 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