Plugin iç işleyişi

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

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:

Harici uyumluluk yaklaşımı

Yetenek modeli çekirdeğe eklenmiştir ve bugün paketle birlikte gelen/yerel pluginler tarafından kullanılmaktadır; ancak harici Plugin uyumluluğu için hâlâ "dışa aktarılıyorsa artık sabittir" anlayışından daha katı bir ölçüt gereklidir.

Amaçlanan yön yetenek kaydıdır. Geçiş sırasında harici pluginler için kırılmaya yol açmayan en güvenli yol eski kancalar olmaya devam eder. Dışa aktarılan yardımcı alt yolların tümü eşit değildir — tesadüfi 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:

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

Eski kancalar

before_agent_start kancası, yalnızca kanca kullanan pluginler için bir uyumluluk yolu olarak desteklenmeye devam etmektedir. Gerçek dünyada kullanılan eski pluginler hâlâ buna bağımlıdır.

Yön:

• çalışır durumda tutun
• eski olarak belgeleyin
• model/sağlayıcı geçersiz kılma çalışmaları için before_model_resolve kullanmayı tercih edin
• istem değişikliği çalışmaları için before_prompt_build kullanmayı tercih edin
• yalnızca gerçek kullanım azaldıktan ve düzenek kapsamı geçişin güvenli olduğunu kanıtladıktan sonra kaldırın

Uyumluluk sinyalleri

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

Bilgilendirme/uyarı sinyallerinin hiçbiri bugün Plugininizi bozmaz. Bu sinyaller openclaw status --all ve openclaw plugins doctor çıktılarında da görünür.

Mimariye genel bakış

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

Özellikle Plugin CLI'si için kök komut keşfi iki aşamaya ayrılır:

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

Bu, OpenClaw'ın ayrıştırmadan önce kök komut adlarını ayırabilmesini sağlarken Plugine ait CLI kodunu Pluginin içinde tutar.

Önemli tasarım sınırı:

• manifest/yapılandırma doğrulaması, Plugin kodunu çalıştırmadan manifest/şema meta verileri üzerinden çalışmalıdır
• yerel yetenek keşfi, etkinleştirmeyen bir kayıt defteri anlık görüntüsü oluşturmak için güvenilen Plugin giriş kodunu yükleyebilir
• yerel çalışma zamanı davranışı, api.registrationMode === "full" koşuluyla Plugin modülünün register(api) yolundan 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şlatılırken geçerli yapılandırma anlık görüntüsü için tek bir PluginMetadataSnapshot oluşturulur. 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, bir Plugin kimliği normalleştiricisini ve manifest kayıtlarını saklar. Yüklenmiş Plugin modüllerini, sağlayıcı SDK'larını, paket içeriklerini veya çalışma zamanı dışa aktarımlarını içermez.

Plugin farkındalıklı 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.

Başlangıçtan sonra Gateway, 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 güncel 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 aracı ç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ın hızlı yolda kalmasını sağlar:

• kanal sahipliği
• ertelenmiş kanal başlangıcı
• başlangıç Plugin kimlikleri
• sağlayıcı ve CLI arka ucu sahipliği
• kurulum sağlayıcısı, komut takma 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ı, anlık görüntünün değiştirilmesidir; değiştirilmesi değil. 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 değerlendirmeyin ve sınırsız sayıda geçmiş anlık görüntü tutmayın. Eski çalışma zamanı durumunun bir meta veri önbelleğinin ardına gizlenememesi için çalışma zamanı Plugin yüklemesi, meta veri anlık görüntülerinden ayrı kalır.

Önbellek kuralı Plugin mimarisinin 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. Yalnızca çalışma zamanı yükleyicisi, modül ve bağımlılık yapıtı önbellekleri; kod veya yüklü yapıtlar gerçekten yüklendikten sonra kalıcı olabilir.

Bazı soğuk yol çağıranları, Gateway PluginLookUpTable almak yerine manifest kayıt defterlerini kalıcı yüklü Plugin dizininden doğrudan yeniden oluşturmayı sürdürür. Bu yol artık kayıt defterini gerektiğinde yeniden oluşturur; çağıranın elinde zaten bir tablo varsa çalışma zamanı akışları boyunca geçerli arama tablosunu veya açık bir manifest kayıt defterini geçirmeyi 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, ajan altyapısı veya yetenekle hangi Plugin'lerin ilgili olduğunu sorabilir.

Planlayıcı, mevcut manifest davranışıyla uyumluluğu korur:

• activation.* alanları açık planlayıcı ipuçlarıdır
• providers, channels, commandAliases, setup.providers, contracts.tools ve hook'lar, manifest sahipliği için yedek mekanizma olmaya devam eder
• yalnızca kimlikleri döndüren planlayıcı API'si mevcut çağıranlar için kullanılabilir kalır
• plan API'si, tanılamanın açık ipuçlarını sahiplik yedek mekanizmasından ayırt edebilmesi için neden etiketlerini bildirir

Kanal Plugin'leri ve paylaşılan mesaj aracı

Kanal Plugin'lerinin 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; kanala özgü keşif ve bunun arkasındaki yürütme kanal Plugin'lerine aittir.

Geçerli sınır şöyledir:

• paylaşılan message aracı sunucusu, istem bağlantıları, oturum/ileti dizisi takibi ve yürütme yönlendirmesi çekirdeğe aittir
• kapsamlı eylem keşfi, yetenek keşfi ve kanala özgü şema parçaları kanal Plugin'lerine aittir
• 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şma dil bilgisi kanal Plugin'lerine aittir
• kanal Plugin'leri son eylemi kendi eylem adaptörleri üzerinden yürütür

Kanal Plugin'leri için SDK yüzeyi ChannelMessageActionAdapter.describeMessageTool(...) şeklindedir. Bu birleşik keşif çağrısı, bir Plugin'in görünür eylemlerini, yeteneklerini ve şema katkılarını birlikte döndürmesini sağlayarak bu parçaların birbirinden sapmasını önler.

Kanala özgü bir mesaj aracı parametresi, yerel yol veya uzak medya URL'si gibi bir medya kaynağı taşıdığında Plugin, describeMessageTool(...) üzerinden ayrıca mediaSourceParams döndürmelidir. Çekirdek, Plugin'e ait parametre adlarını sabit kodlamadan korumalı alan yolu normalleştirmesi ve giden medya erişimi ipuçlarını uygulamak için bu açık listeyi kullanır. Profil ile sınırlı 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ı Plugin'ler için önemlidir. Bir kanal, çekirdekteki message aracına kanala özgü dallar sabit kodlamadan etkin hesaba, geçerli odaya/ileti dizisine/mesaja veya güvenilir istekte bulunan kimliğine göre mesaj eylemlerini gizleyebilir ya da gösterebilir.

Bu nedenle gömülü çalıştırıcı yönlendirme değişiklikleri hâlâ Plugin işidir: paylaşılan message aracının geçerli tur için doğru, kanala ait yüzeyi sunabilmesi amacıyla geçerli sohbet/oturum kimliğini Plugin keşif sınırına iletmekten çalıştırıcı sorumludur.

Kanala ait yürütme yardımcıları için paketlenmiş Plugin'ler, yürütme çalışma zamanını kendi Plugin modüllerinde 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 paketlenmiş Plugin'ler kendi yerel çalışma zamanı kodlarını doğrudan Plugin'e ait modüllerinden içe aktarmalıdır.

Aynı sınır, genel olarak sağlayıcı adını taşıyan SDK bağlantıları için de geçerlidir: çekirdek; Discord, Signal, Slack, WhatsApp veya benzer Plugin'lere özgü kolaylık barrel'larını içe aktarmamalıdır. Çekirdek bir davranışa ihtiyaç duyuyorsa ya paketlenmiş Plugin'in kendi api.ts / runtime-api.ts barrel'ını tüketmeli ya da ihtiyacı paylaşılan SDK'da dar kapsamlı, genel bir yeteneğe yükseltmelidir.

Paketlenmiş Plugin'ler de aynı kurala uyar. Paketlenmiş bir Plugin'in runtime-api.ts dosyası, kendi markalı openclaw/plugin-sdk/<plugin-id> facade'ını yeniden dışa aktarmamalıdır. Bu markalı facade'lar, harici Plugin'ler ve eski tüketiciler için uyumluluk shim'leri olarak kalır; ancak paketlenmiş Plugin'ler 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 harici ekosistemin uyumluluk sınırı gerektirmedikçe Plugin kimliğine özgü SDK facade'ları eklememelidir.

Anketler için özellikle iki yürütme yolu vardır:

• outbound.sendPoll, ortak anket modeline uyan kanallar için paylaşılan temel davranıştır
• actions.handleAction("poll"), kanala özgü anket anlamları 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 Plugin'e ait anket işleyicileri önce genel anket ayrıştırıcısı tarafından engellenmeden kanala özgü anket alanlarını kabul edebilir.

Tam başlatma sırası için Plugin mimarisi iç işleyişi bölümüne bakın.

Yetenek sahipliği modeli

OpenClaw, yerel bir Plugin'i ilgisiz entegrasyonların bir araya toplandığı bir yapı olarak değil, bir şirketin veya özelliğin sahiplik sınırı olarak değerlendirir.

Bunun anlamı şudur:

• 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 sunduğu özellik yüzeyinin tamamına sahip olmalıdır
• kanallar, sağlayıcı davranışını duruma özel biçimde yeniden uygulamak yerine paylaşılan çekirdek yeteneklerini tüketmelidir

Hedeflenen 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 Plugin'de bulunur
• diğer tedarikçiler kendi yüzey alanları için aynısını yapabilir
• kanallar, sağlayıcının hangi tedarikçi Plugin'ine ait olduğunu önemsemez; çekirdek tarafından sunulan paylaşılan yetenek sözleşmesini tüketirler

Temel ayrım şudur:

• Plugin = sahiplik sınırı
• yetenek = birden fazla Plugin'in uygulayabileceği veya tüketebileceğ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 "çekirdek video yeteneği sözleşmesi nedir?" olmalıdır. Bu sözleşme oluşturulduktan sonra tedarikçi Plugin'leri buna kaydolabilir ve kanal/özellik Plugin'leri bunu tüketebilir.

Yetenek henüz mevcut değilse doğru yaklaşım genellikle şöyledir:

Bu yaklaşım, tek bir tedarikçiye veya tek seferlik, Plugin'e özgü bir kod yoluna bağlı çekirdek davranışından kaçınırken sahipliği açık tutar.

Yetenek katmanları

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

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

• yanıt sırasındaki TTS politikası, yedek mekanizma sırası, tercihler ve kanal teslimi çekirdeğe aittir
• sentez uygulamaları elevenlabs, google, microsoft ve openai öğelerine aittir
• voice-call, telefon TTS çalışma zamanı yardımcısını tüketir

Gelecekteki yetenekler için de aynı model tercih edilmelidir.

Çok yetenekli şirket Plugin'i örneği

Bir şirket Plugin'i dışarıdan tutarlı görünmelidir. 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:

    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({          ...req,          provider: "exampleai",        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          ...req,          provider: "exampleai",        });      },    });     api.registerWebSearchProvider(      createPluginBackedWebSearchProvider({        id: "exampleai-search",        // credential + fetch logic      }),    );  },}; export default plugin;

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

• tedarikçi yüzeyinin sahibi tek bir Plugin'dir
• yetenek sözleşmelerinin sahibi yine çekirdektir
• kanallar ve özellik Plugin'leri tedarikçi kodunu değil, api.runtime.* yardımcılarını tüketir
• sözleşme testleri, Plugin'in sahibi olduğunu iddia ettiğ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:

Bu, tek bir sağlayıcının video varsayımlarının çekirdeğe yerleştirilmesini önler. Tedarikçi yüzeyi Plugin'e; yetenek sözleşmesi ve yedek davranışı ise çekirdeğe aittir.

Video üretimi de aynı sırayı zaten kullanır: tür güvenli yetenek sözleşmesi ve çalışma zamanı yardımcısı çekirdeğe aittir; tedarikçi Plugin'leri ise buna yönelik api.registerVideoGenerationProvider(...) uygulamalarını kaydeder.

Somut bir kullanıma sunma kontrol listesine mi ihtiyacınız var? Yetenek Tarifleri bölümüne bakın.

Sözleşmeler ve uygulama zorunluluğu

Plugin API yüzeyi, OpenClawPluginApi içinde bilinçli olarak türlendirilmiş ve merkezileştirilmiştir. Bu sözleşme, desteklenen kayıt noktalarını ve bir Plugin'in güvenebileceği çalışma zamanı yardımcılarını tanımlar.

Bunun önemi:

• Plugin yazarları tek ve kararlı bir dahili standarda sahip olur
• çekirdek, aynı sağlayıcı kimliğini kaydeden iki Plugin gibi yinelenen sahiplik durumlarını reddedebilir
• başlatma sırasında hatalı biçimlendirilmiş kayıtlar için uygulanabilir tanılama bilgileri gösterilebilir
• sözleşme testleri, paketle birlikte gelen Plugin'lerin sahipliğini zorunlu kılabilir ve sessiz sapmaları önleyebilir

İki uygulama katmanı vardır:

Bunun pratik sonucu, OpenClaw'un hangi yüzeyin hangi Plugin'e ait olduğunu en baştan bilmesidir. Böylece sahiplik örtük olmak yerine bildirilmiş, türlendirilmiş ve test edilebilir olduğundan çekirdek ile kanallar sorunsuz biçimde birlikte çalışabilir.

Bir sözleşmede neler bulunmalıdır?

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

Yürütme modeli

Yerel OpenClaw Plugin'leri Gateway ile aynı işlem içinde çalışır. Korumalı alanda çalıştırılmazlar. Yüklenmiş bir yerel Plugin, çekirdek kodla aynı işlem düzeyindeki güven sınırına sahiptir.

Uyumlu paketler varsayılan olarak daha güvenlidir çünkü OpenClaw şu anda bunları meta veri/içerik paketleri olarak değerlendirir. Güncel sürümlerde bu çoğunlukla paketle birlikte gelen Skills anlamına gelir.

Paketle birlikte gelmeyen Plugin'ler için izin listeleri ve açık kurulum/yükleme yolları kullanın. Çalışma alanı Plugin'lerini üretim varsayılanları olarak değil, geliştirme zamanı kodu olarak değerlendirin.

Paketle birlikte gelen çalışma alanı paket adlarında Plugin kimliğini npm adına bağlı tutun: varsayılan olarak @openclaw/<id> veya paket bilinçli olarak daha dar bir Plugin rolü sunuyorsa -provider, -plugin, -speech, -sandbox ya da -media-understanding gibi onaylanmış, türlendirilmiş bir sonek kullanın.

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 kapsamı dışındaki yardımcı dışa aktarımları kaldırın:

• paketle birlikte gelen Plugin'lere özgü yardımcı alt yollar
• herkese açık API olarak tasarlanmamış çalışma zamanı altyapısı alt yolları
• satıcıya özgü kolaylık sağlayan yardımcılar
• uygulama ayrıntısı niteliğindeki kurulum/ilk yapılandırma yardımcıları

Paketle birlikte gelen Plugin'lere ayrılmış yardımcı alt yollar, oluşturulan SDK dışa aktarma eşlemesinden kaldırılmıştır. Sahibe özgü yardımcıları ilgili Plugin paketinin içinde tutun; yalnızca yeniden kullanılabilir ana makine davranışını plugin-sdk/gateway-runtime, plugin-sdk/security-runtime ve plugin-sdk/plugin-config-runtime gibi genel SDK sözleşmelerine yükseltin.

Dahili yapılar 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 Plugin'leri ve yeni bir yetenek ekleme kılavuzu için Plugin mimarisinin dahili yapıları bölümüne bakın.

İlgili

• Plugin oluşturma
• Plugin manifesti
• Plugin SDK kurulumu