Plugin iç yapısı

Bu, OpenClaw plugin sistemi için ayrıntılı mimari başvuru kaynağıdır. Uygulamalı kılavuzlar için aşağıdaki odaklanmış sayfalardan biriyle başlayın.

Pluginleri yükleme ve kullanma

Plugin ekleme, etkinleştirme ve sorunlarını giderme konusunda son kullanıcı kılavuzu.

Plugin geliştirme

Çalışan en küçük manifesti içeren ilk Plugin öğreticisi.

Kanal pluginleri

Bir mesajlaşma kanalı Plugini geliştirin.

Sağlayıcı pluginleri

Bir model sağlayıcı Plugini geliştirin.

SDK'ye genel bakış

İçe aktarma eşlemesi ve kayıt API’si başvuru kaynağı.

Genel yetenek modeli

Yetenekler, OpenClaw içindeki genel yerel Plugin modelidir. Her yerel OpenClaw Plugini bir veya daha fazla yetenek türü için kaydolur:

Yetenek	Kayıt yöntemi	Örnek pluginler
Metin çıkarımı	`api.registerProvider(...)`	`anthropic`, `openai`
CLI çıkarım arka ucu	`api.registerCliBackend(...)`	`anthropic`, `openai`
Gömme	`api.registerEmbeddingProvider(...)`	Sağlayıcıya ait vektör pluginleri
Konuşma	`api.registerSpeechProvider(...)`	`elevenlabs`, `microsoft`
Gerçek zamanlı yazıya dökme	`api.registerRealtimeTranscriptionProvider(...)`	`openai`
Gerçek zamanlı ses	`api.registerRealtimeVoiceProvider(...)`	`google`, `openai`
Medya anlama	`api.registerMediaUnderstandingProvider(...)`	`google`, `openai`
Transkript kaynağı	`api.registerTranscriptSourceProvider(...)`	`discord`, `google-meet`, `teams-meetings`, `zoom-meetings`
Görüntü oluşturma	`api.registerImageGenerationProvider(...)`	`fal`, `google`, `openai`
Müzik oluşturma	`api.registerMusicGenerationProvider(...)`	`fal`, `google`, `minimax`
Video oluşturma	`api.registerVideoGenerationProvider(...)`	`fal`, `google`, `qwen`
Web’den getirme	`api.registerWebFetchProvider(...)`	`firecrawl`
Web’de arama	`api.registerWebSearchProvider(...)`	`brave`, `firecrawl`, `google`
Kanal / mesajlaşma	`api.registerChannel(...)`	`matrix`, `msteams`
Gateway keşfi	`api.registerGatewayDiscoveryService(...)`	`bonjour`

Sıfır yetenek kaydeden ancak kancalar, araçlar, keşif hizmetleri veya arka plan hizmetleri sağlayan bir Plugin, yalnızca eski kancaları kullanan bir Plugindir. Bu düzen hâlâ tam olarak desteklenmektedir.

Harici uyumluluk yaklaşımı

Yetenek modeli çekirdeğe eklenmiştir ve günümüzde paketle gelen/yerel pluginler tarafından kullanılmaktadır; ancak harici Plugin uyumluluğu için hâlâ “dışa aktarılmışsa dondurulmuştur” yaklaşımından daha sıkı bir ölçüt gerekir.

Plugin durumu	Yönlendirme
Mevcut harici pluginler	Kanca tabanlı entegrasyonların çalışmasını sürdürün; uyumluluğun temel çizgisi budur.
Paketle gelen/yeni yerel pluginler	Sağlayıcıya özgü doğrudan erişimler veya yalnızca kancaları kullanan yeni tasarımlar yerine açık yetenek kaydını tercih edin.
Yetenek kaydını benimseyen harici pluginler	İzin verilir; ancak belgeler kararlı olduğunu belirtmedikçe yeteneğe özgü yardımcı yüzeyleri gelişmekte kabul edin.

Amaçlanan yön yetenek kaydıdır. Geçiş sırasında eski kancalar, harici pluginler için bozulmaya yol açmayan en güvenli yol olmaya devam eder. Dışa aktarılan yardımcı alt yolların tümü eşit değildir; rastlantısal yardımcı dışa aktarımlar yerine dar kapsamlı, belgelenmiş sözleşmeleri tercih edin.

Plugin biçimleri

OpenClaw, yüklenen her Plugini yalnızca statik meta verilere göre değil, gerçek kayıt davranışına göre bir biçimde sınıflandırır:

yalın-yetenek

Tam olarak bir yetenek türü kaydeder (örneğin arcee veya chutes gibi yalnızca sağlayıcı görevi gören bir Plugin).

hibrit-yetenek

Birden fazla yetenek türü kaydeder (örneğin openai; metin çıkarımı, konuşma, medya anlama ve görüntü oluşturmanın sahibidir).

yalnızca-kanca

Yalnızca kancaları (türlü veya özel) kaydeder; yetenek, araç, komut veya hizmet kaydetmez.

yetenek-dışı

Araçları, komutları, hizmetleri veya rotaları kaydeder ancak yetenek kaydetmez.

Bir Pluginin biçimini ve yetenek dökümünü görmek için openclaw plugins inspect <id> kullanın. Ayrıntılar için CLI başvuru kaynağına bakın.

Uyumluluk sinyalleri

openclaw doctor, openclaw plugins inspect <id>, openclaw status --all ve openclaw plugins doctor şu uyumluluk bildirimlerini gösterir:

Sinyal	Anlamı
yapılandırma geçerli	Yapılandırma sorunsuz ayrıştırılır ve pluginler çözümlenir
yalnızca-kanca (bilgi)	Plugin yalnızca kancaları kaydeder; bu desteklenen bir yoldur ancak henüz yetenek kaydına geçirilmemiştir
kullanımdan kaldırılmış bellek gömme API’si (uyarı)	Paketle gelmeyen Plugin, `registerEmbeddingProvider` yerine belleğe özgü eski gömme sağlayıcısı API’sini kullanır
kesin hata	Yapılandırma geçersizdir veya Plugin yüklenememiştir

Bilgilendirme/uyarı sinyallerinin hiçbiri bugün Plugininizi bozmaz. Bu sinyaller openclaw status --all ve openclaw plugins doctor içinde de görünür.

Mimariye genel bakış

OpenClaw’ın Plugin sistemi dört katmandan oluşur:

Manifest + keşif

OpenClaw; yapılandırılmış yollarda, çalışma alanı köklerinde, genel Plugin köklerinde ve paketle gelen pluginlerde aday pluginleri bulur. Keşif önce yerel openclaw.plugin.json manifestlerini ve desteklenen paket manifestlerini okur.

Etkinleştirme + doğrulama

Çekirdek, keşfedilen bir Pluginin etkinleştirildiğine, devre dışı bırakıldığına, engellendiğine veya bellek gibi özel bir yuva için seçildiğine karar verir.

Çalışma zamanı yüklemesi

Yerel OpenClaw pluginleri işlem içinde yüklenir ve yetenekleri merkezi bir kayıt defterine kaydeder. Paketlenmiş JavaScript, yerel require üzerinden yüklenir; üçüncü taraf yerel kaynak TypeScript için acil durum alternatifi Jiti’dir. Uyumlu paketler, çalışma zamanı kodu içe aktarılmadan kayıt defteri girdilerine dönüştürülür.

Yüzey kullanımı

OpenClaw’ın geri kalanı araçları, kanalları, sağlayıcı kurulumunu, kancaları, HTTP rotalarını, CLI komutlarını ve hizmetleri sunmak için kayıt defterini okur.

Özellikle Plugin CLI’sinde kök komut keşfi iki aşamaya ayrılır:

ayrıştırma zamanı meta verileri registerCli(..., { descriptors: [...] }) kaynağından gelir
gerçek Plugin CLI modülü tembel kalabilir ve ilk çağrıda kaydolabilir

Böylece OpenClaw, ayrıştırmadan önce kök komut adlarını ayırabilirken Plugine ait CLI kodu Plugin içinde kalır. Önemli tasarım sınırı:

manifest/yapılandırma doğrulaması, Plugin kodu çalıştırılmadan manifest/şema meta verilerinden yapılabilmelidir
yerel yetenek keşfi, etkinleştirme yapmayan bir kayıt defteri anlık görüntüsü oluşturmak için güvenilir Plugin giriş kodunu yükleyebilir
yerel çalışma zamanı davranışı, Plugin modülünün register(api) yolundan ve api.registrationMode === "full" ile gelir

Bu ayrım, tam çalışma zamanı etkinleşmeden önce OpenClaw’ın yapılandırmayı doğrulamasına, eksik/devre dışı pluginleri açıklamasına ve kullanıcı arayüzü/şema ipuçları oluşturmasına olanak tanır.

Plugin meta verisi anlık görüntüsü ve arama tablosu

Gateway başlangıcı, geçerli yapılandırma anlık görüntüsü için bir PluginMetadataSnapshot oluşturur. Anlık görüntü yalnızca meta verilerden oluşur: yüklü Plugin dizinini, manifest kayıt defterini, manifest tanılamalarını, sahip eşlemelerini, Plugin kimliği normalleştiricisini ve manifest kayıtlarını depolar. Yüklenmiş Plugin modüllerini, sağlayıcı SDK’lerini, paket içeriklerini veya çalışma zamanı dışa aktarımlarını içermez. Pluginleri dikkate alan yapılandırma doğrulaması, başlangıçta otomatik etkinleştirme ve Gateway Plugin önyüklemesi; manifest/dizin meta verilerini birbirinden bağımsız olarak yeniden oluşturmak yerine bu anlık görüntüyü kullanır. PluginLookUpTable aynı anlık görüntüden türetilir ve geçerli çalışma zamanı yapılandırması için başlangıç Plugin planını ekler. Gateway, başlangıçtan sonra geçerli meta veri anlık görüntüsünü değiştirilebilir bir çalışma zamanı ürünü olarak tutar. Yinelenen çalışma zamanı sağlayıcı keşfi, her sağlayıcı kataloğu geçişinde yüklü dizini ve manifest kayıt defterini yeniden oluşturmak yerine bu anlık görüntüyü ödünç alabilir. Gateway kapatıldığında, yapılandırma/Plugin envanteri değiştiğinde ve yüklü dizine yazıldığında anlık görüntü temizlenir veya değiştirilir; uyumlu ve geçerli bir anlık görüntü bulunmadığında çağıranlar soğuk manifest/dizin yoluna geri döner. Uyumluluk denetimleri, plugins.load.paths ve varsayılan ajan çalışma alanı gibi Plugin keşif köklerini içermelidir; çünkü çalışma alanı pluginleri meta veri kapsamının parçasıdır. Anlık görüntü ve arama tablosu, yinelenen başlangıç kararlarını hızlı yolda tutar:

kanal sahipliği
ertelenmiş kanal başlangıcı
başlangıç Plugin kimlikleri
sağlayıcı ve CLI arka uç sahipliği
kurulum sağlayıcısı, komut diğer adı, model kataloğu sağlayıcısı ve manifest sözleşmesi sahipliği
Plugin yapılandırma şeması ve kanal yapılandırma şeması doğrulaması
başlangıçta otomatik etkinleştirme kararları

Güvenlik sınırı mutasyon değil, anlık görüntünün değiştirilmesidir. Yapılandırma, Plugin envanteri, yükleme kayıtları veya kalıcı dizin ilkesi değiştiğinde anlık görüntüyü yeniden oluşturun. Bunu geniş kapsamlı, değiştirilebilir bir genel kayıt defteri olarak kullanmayın ve sınırsız sayıda geçmiş anlık görüntüyü tutmayın. Eski çalışma zamanı durumunun bir meta veri önbelleğinin arkasına gizlenememesi için çalışma zamanı Plugin yüklemesi, meta veri anlık görüntülerinden ayrı kalır. Önbellek kuralı Plugin mimarisi iç işleyişi bölümünde belgelenmiştir: çağıran geçerli akış için açık bir anlık görüntü, arama tablosu veya manifest kayıt defteri tutmadığı sürece manifest ve keşif meta verileri günceldir. Gizli meta veri önbellekleri ve duvar saati TTL’leri Plugin yüklemesinin parçası değildir. Kod veya yüklü yapılar gerçekten yüklendikten sonra yalnızca çalışma zamanı yükleyicisi, modül ve bağımlılık yapısı önbellekleri kalıcı olabilir. Bazı soğuk yol çağıranları, bir Gateway PluginLookUpTable almak yerine manifest kayıtlarını kalıcı yüklenmiş plugin dizininden doğrudan yeniden oluşturmaya devam ediyor. Bu yol artık kaydı istek üzerine yeniden oluşturuyor; çağıranda zaten mevcutsa çalışma zamanı akışları üzerinden geçerli arama tablosunu veya açık bir manifest kaydını aktarmayı tercih edin.

Etkinleştirme planlaması

Etkinleştirme planlaması, kontrol düzleminin bir parçasıdır. Çağıranlar, daha geniş çalışma zamanı kayıtlarını yüklemeden önce somut bir komut, sağlayıcı, kanal, rota, aracı koşum takımı veya yetenek için hangi pluginlerin ilgili olduğunu sorgulayabilir. Planlayıcı, mevcut manifest davranışının uyumluluğunu korur:

activation.* alanları açık planlayıcı ipuçlarıdır
providers, channels, commandAliases, setup.providers, contracts.tools ve hook’lar manifest sahipliği geri dönüşü olmaya devam eder
yalnızca kimliklerden oluşan planlayıcı API’si mevcut çağıranlar için kullanılabilir kalır
plan API’si neden etiketlerini bildirir; böylece tanılama, açık ipuçlarını sahiplik geri dönüşünden ayırt edebilir

activation öğesini bir yaşam döngüsü hook’u veya register(...) yerine geçen bir unsur olarak değerlendirmeyin. Bu, yüklemeyi daraltmak için kullanılan metaveridir. İlişkiyi zaten tanımlıyorlarsa sahiplik alanlarını tercih edin; activation öğesini yalnızca ek planlayıcı ipuçları için kullanın.

Kanal pluginleri ve paylaşılan mesaj aracı

Kanal pluginlerinin normal sohbet eylemleri için ayrı bir gönderme/düzenleme/tepki verme aracı kaydetmesi gerekmez. OpenClaw, çekirdekte tek bir paylaşılan message aracı tutar ve kanal pluginleri bunun arkasındaki kanala özgü keşif ile yürütmenin sahipliğini üstlenir. Geçerli sınır şöyledir:

çekirdek; paylaşılan message araç barındırıcısının, istem bağlantılarının, oturum/ileti dizisi kaydının ve yürütme yönlendirmenin sahibidir
kanal pluginleri; kapsamlı eylem keşfinin, yetenek keşfinin ve kanala özgü tüm şema parçalarının sahibidir
kanal pluginleri; konuşma kimliklerinin ileti dizisi kimliklerini nasıl kodladığı veya üst konuşmalardan nasıl devralındığı gibi, sağlayıcıya özgü oturum konuşması dilbilgisinin sahibidir
kanal pluginleri son eylemi kendi eylem bağdaştırıcıları üzerinden yürütür

Kanal pluginleri için SDK yüzeyi ChannelMessageActionAdapter.describeMessageTool(...) şeklindedir. Bu birleşik keşif çağrısı, söz konusu parçaların birbirinden sapmaması için bir pluginin görünür eylemlerini, yeteneklerini ve şema katkılarını birlikte döndürmesine olanak tanır. Mesaj eylemi adları, her aktarımın her eylemi işleyebilmesi için kasıtlı olarak kapalı ve çekirdeğin sahip olduğu bir söz dağarcığını kullanır. Pluginler eylem adlarını bir çekirdek PR’ı aracılığıyla ekler; çalışma zamanında kayıt kasıtlı olarak desteklenmez. Kanala özgü bir mesaj aracı parametresi, yerel yol veya uzak medya URL’si gibi bir medya kaynağı taşıdığında plugin ayrıca describeMessageTool(...) içinden mediaSourceParams döndürmelidir. Çekirdek, pluginin sahip olduğu parametre adlarını sabit kodlamadan korumalı alan yol normalleştirmesi ve giden medya erişimi ipuçlarını uygulamak için bu açık listeyi kullanır. Profil kapsamlı bir medya parametresinin send gibi ilgisiz eylemlerde normalleştirilmemesi için burada kanal genelinde tek bir düz liste yerine eylem kapsamlı eşlemeleri tercih edin. Çekirdek, çalışma zamanı kapsamını bu keşif adımına aktarır. Önemli alanlar şunlardır:

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

Bu, bağlama duyarlı pluginler için önemlidir. Bir kanal; çekirdek message aracında kanala özgü dalları sabit kodlamadan, etkin hesaba, geçerli odaya/ileti dizisine/mesaja veya güvenilir istekte bulunanın kimliğine göre mesaj eylemlerini gizleyebilir ya da gösterebilir. Gömülü çalıştırıcı yönlendirme değişikliklerinin hâlâ plugin işi olmasının nedeni budur: çalıştırıcı, geçerli sohbet/oturum kimliğini plugin keşif sınırına iletmekten sorumludur; böylece paylaşılan message aracı geçerli tur için kanalın sahip olduğu doğru yüzeyi sunar. Kanalın sahip olduğu yürütme yardımcıları için kanal pluginleri, yürütme çalışma zamanını kendi plugin modülleri içinde tutmalıdır. Çekirdek artık src/agents/tools altında Discord, Slack, Telegram veya WhatsApp mesaj eylemi çalışma zamanlarının sahibi değildir. Ayrı plugin-sdk/*-action-runtime alt yolları yayımlamıyoruz ve bu pluginler kendi yerel çalışma zamanı kodlarını doğrudan pluginin sahip olduğu modüllerden içe aktarmalıdır. Aynı sınır genel olarak sağlayıcı adını taşıyan SDK bağlantı noktaları için de geçerlidir: çekirdek Discord, Signal, Slack, WhatsApp veya benzer pluginler için kanala özgü kolaylık barrel’larını içe aktarmamalıdır. Çekirdeğin bir davranışa ihtiyacı varsa ya paketlenmiş pluginin kendi api.ts / runtime-api.ts barrel’ını kullanmalı ya da ihtiyacı paylaşılan SDK’da dar kapsamlı, genel bir yeteneğe yükseltmelidir. Paketlenmiş pluginler de aynı kuralı izler. Paketlenmiş bir pluginin runtime-api.ts öğesi, kendi markalı openclaw/plugin-sdk/<plugin-id> cephesini yeniden dışa aktarmamalıdır. Bu markalı cepheler haricî pluginler ve eski tüketiciler için uyumluluk shim’leri olarak kalır; ancak paketlenmiş pluginler yerel dışa aktarımları ve openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/runtime-store veya openclaw/plugin-sdk/webhook-ingress gibi dar kapsamlı genel SDK alt yollarını kullanmalıdır. Yeni kod, mevcut bir haricî ekosistemin uyumluluk sınırı gerektirmediği sürece plugin kimliğine özgü SDK cepheleri eklememelidir. Özellikle anketler için iki yürütme yolu vardır:

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

Çekirdek artık paylaşılan anket ayrıştırmasını, plugin anket yönlendirmesi eylemi reddedene kadar erteler; böylece pluginin sahip olduğu anket işleyicileri önce genel anket ayrıştırıcısı tarafından engellenmeden kanala özgü anket alanlarını kabul edebilir. Başlatma sırasının tamamı için Plugin mimarisi iç ayrıntıları bölümüne bakın.

Yetenek sahipliği modeli

OpenClaw, yerel bir plugini ilgisiz entegrasyonların toplandığı bir paket olarak değil, bir şirketin veya özelliğin sahiplik sınırı olarak değerlendirir. Bunun anlamı şudur:

bir şirket plugini genellikle o şirketin OpenClaw’a dönük tüm yüzeylerinin sahibi olmalıdır
bir özellik plugini genellikle sunduğu özellik yüzeyinin tamamının sahibi olmalıdır
kanallar, sağlayıcı davranışını geçici biçimde yeniden uygulamak yerine paylaşılan çekirdek yeteneklerini kullanmalıdır

Çok yetenekli tedarikçi

google; metin çıkarımı, CLI arka ucu, gömmeler, konuşma, gerçek zamanlı ses, medya anlama, görüntü/müzik/video üretimi ve web aramasının sahibidir. openai; metin çıkarımı, gömmeler, konuşma, gerçek zamanlı transkripsiyon, gerçek zamanlı ses, medya anlama ve görüntü/video üretiminin sahibidir. minimax; metin çıkarımının yanı sıra medya anlama, konuşma, görüntü/müzik/video üretimi ve web aramasının sahibidir.

Tek yetenekli tedarikçi

arcee ve chutes yalnızca metin çıkarımının; microsoft ise yalnızca konuşmanın sahibidir. Bir tedarikçi plugini, o tedarikçinin daha geniş yüzeyini kapsaması gerekene kadar bu kadar dar kalabilir.

Özellik plugini

voice-call; çağrı aktarımı, araçlar, CLI, rotalar ve Twilio medya akışı köprülemesinin sahibidir; ancak tedarikçi pluginlerini doğrudan içe aktarmak yerine paylaşılan konuşma, gerçek zamanlı transkripsiyon ve gerçek zamanlı ses yeteneklerini kullanır.

Amaçlanan son durum şöyledir:

bir tedarikçinin OpenClaw’a dönük yüzeyi, metin modelleri, konuşma, görüntüler ve videoyu kapsasa bile tek bir pluginde bulunur
diğer tedarikçiler de kendi yüzey alanları için aynısını yapabilir
kanallar, sağlayıcının hangi tedarikçi pluginine ait olduğunu önemsemez; çekirdeğin sunduğu paylaşılan yetenek sözleşmesini kullanırlar

Temel ayrım şudur:

plugin = sahiplik sınırı
yetenek = birden fazla pluginin uygulayabildiği veya kullanabildiği çekirdek sözleşmesi

Dolayısıyla OpenClaw video gibi yeni bir alan eklerse ilk soru “hangi sağlayıcı video işlemeyi sabit kodlamalı?” değildir. İlk soru “temel video yeteneği sözleşmesi nedir?” olmalıdır. Bu sözleşme oluşturulduktan sonra tedarikçi pluginleri buna göre kaydolabilir ve kanal/özellik pluginleri bunu kullanabilir. Yetenek henüz mevcut değilse doğru yaklaşım genellikle şöyledir:

Yeteneği tanımlayın

Eksik yeteneği çekirdekte tanımlayın.

SDK üzerinden sunun

Plugin API’si/çalışma zamanı üzerinden tür güvenli biçimde sunun.

Tüketicileri bağlayın

Kanalları/özellikleri bu yeteneğe bağlayın.

Tedarikçi uygulamaları

Tedarikçi pluginlerinin uygulamaları kaydetmesine olanak tanıyın.

Bu, tek bir tedarikçiye veya tek seferlik plugine özgü bir kod yoluna bağımlı çekirdek davranışından kaçınırken sahipliği açık tutar.

Yetenek katmanlandırması

Kodun nereye ait olduğuna karar verirken şu zihinsel modeli kullanın:

Çekirdek yetenek katmanı
Tedarikçi plugin katmanı
Kanal/özellik plugin katmanı

Paylaşılan orkestrasyon, politika, geri dönüş, yapılandırma birleştirme kuralları, teslim semantiği ve tür güvenli sözleşmeler.

Örneğin TTS şu yapıyı izler:

çekirdek; yanıt zamanı TTS politikasının, geri dönüş sırasının, tercihlerin ve kanal tesliminin sahibidir
elevenlabs, google, microsoft ve openai sentez uygulamalarının sahibidir
voice-call telefon TTS çalışma zamanı yardımcısını kullanır

Gelecekteki yetenekler için de aynı kalıp tercih edilmelidir.

Çok yetenekli şirket plugini örneği

Bir şirket plugini dışarıdan bakıldığında bütünlüklü hissettirmelidir. OpenClaw’ın modeller, konuşma, gerçek zamanlı transkripsiyon, gerçek zamanlı ses, medya anlama, görüntü üretimi, video üretimi, web getirme ve web araması için paylaşılan sözleşmeleri varsa bir tedarikçi tüm yüzeylerine tek bir yerde sahip olabilir:

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { exampleAiMedia } from "./exampleai-media.js";

export default definePluginEntry({
  id: "exampleai",
  name: "ExampleAI",
  description: "ExampleAI modelleri ve medya yetenekleri.",
  register(api) {
    api.registerProvider({
      id: "exampleai",
      // kimlik doğrulama/model kataloğu/çalışma zamanı hook'ları
    });

    api.registerSpeechProvider({
      id: "exampleai",
      // tedarikçi konuşma yapılandırması — SpeechProviderPlugin arayüzünü doğrudan uygulayın
    });

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

    api.registerWebSearchProvider({
      id: "exampleai-search",
      createTool() {
        // Tedarikçinin sahip olduğu web arama aracını döndürün.
      },
    });
  },
});

Önemli olan yardımcıların tam adları değildir. Önemli olan yapıdır:

tek bir plugin tedarikçi yüzeyinin sahibidir
yetenek sözleşmelerinin sahibi hâlâ çekirdektir
sağlayıcı isteği dönüştürme ve HTTP yardımcıları tedarikçi plugininde kalır
kanallar ve özellik pluginleri tedarikçi kodunu değil, api.runtime.* yardımcılarını kullanır
sözleşme testleri, pluginin sahip olduğunu belirttiği yetenekleri kaydettiğini doğrulayabilir

Yetenek örneği: video anlama

OpenClaw görüntü/ses/video anlamayı zaten tek bir paylaşılan yetenek olarak değerlendirir. Aynı sahiplik modeli burada da geçerlidir:

Core sözleşmeyi tanımlar

Core, medya anlama sözleşmesini tanımlar.

Sağlayıcı pluginleri kaydolur

Sağlayıcı pluginleri, uygun olduğunda describeImage, transcribeAudio ve describeVideo öğelerini kaydeder.

Tüketiciler ortak davranışı kullanır

Kanallar ve özellik pluginleri, doğrudan sağlayıcı koduna bağlanmak yerine ortak core davranışını kullanır.

Bu, tek bir sağlayıcının video varsayımlarının core içine gömülmesini önler. Sağlayıcı yüzeyinin sahibi plugindir; yetenek sözleşmesinin ve geri dönüş davranışının sahibi ise core’dur. Video oluşturma zaten aynı sıralamayı kullanır: Türü belirlenmiş yetenek sözleşmesinin ve çalışma zamanı yardımcısının sahibi core’dur; sağlayıcı pluginleri ise api.registerVideoGenerationProvider(...) uygulamalarını buna göre kaydeder. Somut bir kullanıma sunma kontrol listesine mi ihtiyacınız var? Yetenek Tarifleri sayfasına bakın.

Sözleşmeler ve uygulama

Plugin API yüzeyi, OpenClawPluginApi içinde kasıtlı olarak türü belirlenmiş ve merkezileştirilmiştir. Bu sözleşme, desteklenen kayıt noktalarını ve bir pluginin güvenebileceği çalışma zamanı yardımcılarını tanımlar. Bunun önemi:

plugin yazarları tek bir kararlı dahili standarda sahip olur
core, aynı sağlayıcı kimliğini kaydeden iki plugin gibi yinelenen sahiplikleri reddedebilir
başlangıç, hatalı biçimlendirilmiş kayıtlar için eyleme dönüştürülebilir tanılamalar gösterebilir
sözleşme testleri, paketlenmiş plugin sahipliğini uygulayabilir ve sessiz sapmaları önleyebilir

İki uygulama katmanı vardır:

Çalışma zamanı kayıt uygulaması

Plugin kayıt defteri, pluginler yüklenirken kayıtları doğrular. Örneğin yinelenen sağlayıcı kimlikleri, yinelenen konuşma sağlayıcısı kimlikleri ve hatalı biçimlendirilmiş kayıtlar, tanımsız davranış yerine plugin tanılamaları üretir.

Sözleşme testleri

OpenClaw’un sahipliği açıkça doğrulayabilmesi için paketlenmiş pluginler, test çalıştırmaları sırasında sözleşme kayıt defterlerinde yakalanır. Günümüzde 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.

Bunun pratik etkisi, OpenClaw’un hangi yüzeyin hangi plugine ait olduğunu en baştan bilmesidir. Sahiplik örtük olmak yerine bildirilmiş, türü belirlenmiş ve test edilebilir olduğundan core ile kanallar sorunsuz biçimde birleştirilebilir.

Bir sözleşmede neler bulunmalı

İyi sözleşmeler
Kötü sözleşmeler

türü belirlenmiş
küçük
yeteneğe özgü
core’a ait
birden fazla plugin tarafından yeniden kullanılabilir
sağlayıcı bilgisi gerektirmeden kanallar/özellikler tarafından kullanılabilir

core içinde gizlenen sağlayıcıya özgü politika
kayıt defterini atlayan tek kullanımlık plugin kaçış yolları
doğrudan bir sağlayıcı uygulamasına erişen kanal kodu
OpenClawPluginApi veya api.runtime kapsamında olmayan geçici çalışma zamanı nesneleri

Şüpheye düştüğünüzde soyutlama düzeyini yükseltin: önce yeteneği tanımlayın, ardından pluginlerin buna bağlanmasını sağlayın.

Yürütme modeli

Yerel OpenClaw pluginleri, Gateway ile aynı işlem içinde çalışır. Korumalı alanda çalıştırılmazlar. Yüklenen bir yerel plugin, core koduyla aynı işlem düzeyindeki güven sınırına sahiptir.

Yerel pluginlerin etkileri: Bir plugin araçları, ağ işleyicilerini, kancaları ve hizmetleri kaydedebilir; bir plugin hatası Gateway’in çökmesine veya kararsızlaşmasına yol açabilir; kötü amaçlı bir yerel plugin ise OpenClaw işlemi içinde rastgele kod yürütülmesine eşdeğerdir.

OpenClaw şu anda uyumlu paketleri meta veri/içerik paketleri olarak ele aldığından, bunlar varsayılan olarak daha güvenlidir. Mevcut sürümlerde bu çoğunlukla paketlenmiş Skills anlamına gelir. Paketlenmemiş pluginler için izin listeleri ve açık kurulum/yükleme yolları kullanın. Çalışma alanı pluginlerini üretim varsayılanları olarak değil, geliştirme zamanı kodu olarak değerlendirin. Paketlenmiş çalışma alanı paket adlarında plugin kimliğini npm adına bağlı tutun: varsayılan olarak @openclaw/<id>; paket kasıtlı olarak daha dar bir plugin rolü sunuyorsa -provider, -plugin, -speech, -sandbox veya -media-understanding gibi onaylanmış, türü belirlenmiş bir sonek kullanın.

Güven notu: plugins.allow, kaynak menşeine değil plugin kimliklerine güvenir. Paketlenmiş bir pluginle aynı kimliğe sahip çalışma alanı plugini etkinleştirildiğinde/izin listesine eklendiğinde, kasıtlı olarak paketlenmiş kopyanın yerine geçer. Bu normaldir ve yerel geliştirme, yama testi ve acil düzeltmeler için kullanışlıdır. Paketlenmiş plugin güveni, kurulum meta verilerinden değil kaynak anlık görüntüsünden — yükleme anında diskte bulunan manifest ve koddan — belirlenir. Bozulmuş veya değiştirilmiş bir kurulum kaydı, paketlenmiş bir pluginin güven yüzeyini gerçek kaynağın beyan ettiğinin ötesine sessizce genişletemez.

Dışa aktarma sınırı

OpenClaw, uygulama kolaylıklarını değil yetenekleri dışa aktarır. Yetenek kaydını herkese açık tutun. Sözleşme dışı yardımcı dışa aktarımları azaltın:

paketlenmiş plugine özgü yardımcı alt yollar
genel API olarak tasarlanmamış çalışma zamanı tesisatı alt yolları
sağlayıcıya özgü kolaylık yardımcıları
uygulama ayrıntısı olan kurulum/ilk katılım yardımcıları

Ayrılmış paketlenmiş plugin yardımcı alt yolları, oluşturulan SDK dışa aktarma haritasından kaldırılmıştır. Sahibe özgü yardımcıları sahip plugin paketinin içinde tutun; yalnızca yeniden kullanılabilir ana makine davranışını plugin-sdk/gateway-runtime, plugin-sdk/security-runtime ve enjekte edilen plugin API yetenekleri gibi genel SDK sözleşmelerine yükseltin.

Dahili işleyiş ve başvuru

Yükleme işlem hattı, kayıt defteri modeli, sağlayıcı çalışma zamanı kancaları, Gateway HTTP rotaları, mesaj aracı şemaları, kanal hedefi çözümleme, sağlayıcı katalogları, bağlam motoru pluginleri ve yeni bir yetenek ekleme kılavuzu için Plugin mimarisi dahili işleyişi sayfasına bakın.

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Contributing

Plugin iç yapısı

Pluginleri yükleme ve kullanma

Plugin geliştirme

Kanal pluginleri

Sağlayıcı pluginleri

SDK'ye genel bakış

Genel yetenek modeli

Harici uyumluluk yaklaşımı

Plugin biçimleri

Uyumluluk sinyalleri

Mimariye genel bakış

Plugin meta verisi anlık görüntüsü ve arama tablosu

Etkinleştirme planlaması

Kanal pluginleri ve paylaşılan mesaj aracı

Yetenek sahipliği modeli

Yetenek katmanlandırması

Çok yetenekli şirket plugini örneği

Yetenek örneği: video anlama

Sözleşmeler ve uygulama

Bir sözleşmede neler bulunmalı

Yürütme modeli

Dışa aktarma sınırı

Dahili işleyiş ve başvuru

İlgili

Pluginleri yükleme ve kullanma

Plugin geliştirme

Kanal pluginleri

Sağlayıcı pluginleri

SDK'ye genel bakış

​Genel yetenek modeli

​Harici uyumluluk yaklaşımı

​Plugin biçimleri

​Uyumluluk sinyalleri

​Mimariye genel bakış

​Plugin meta verisi anlık görüntüsü ve arama tablosu

​Etkinleştirme planlaması

​Kanal pluginleri ve paylaşılan mesaj aracı

​Yetenek sahipliği modeli

​Yetenek katmanlandırması

​Çok yetenekli şirket plugini örneği

​Yetenek örneği: video anlama

​Sözleşmeler ve uygulama

​Bir sözleşmede neler bulunmalı

​Yürütme modeli

​Dışa aktarma sınırı

​Dahili işleyiş ve başvuru

​İlgili

Genel yetenek modeli

Harici uyumluluk yaklaşımı

Plugin biçimleri

Uyumluluk sinyalleri

Mimariye genel bakış

Plugin meta verisi anlık görüntüsü ve arama tablosu

Etkinleştirme planlaması

Kanal pluginleri ve paylaşılan mesaj aracı

Yetenek sahipliği modeli

Yetenek katmanlandırması

Çok yetenekli şirket plugini örneği

Yetenek örneği: video anlama

Sözleşmeler ve uygulama

Bir sözleşmede neler bulunmalı

Yürütme modeli

Dışa aktarma sınırı

Dahili işleyiş ve başvuru

İlgili