Pluginler

Pluginler; kanallar, model sağlayıcıları, ajan yürütme çerçeveleri, araçlar, Skills, konuşma, gerçek zamanlı yazıya dökme, ses, medya anlama, üretim, web'den getirme, web araması ve diğer çalışma zamanı yetenekleriyle OpenClaw'u genişletir.

Bir Plugin yüklemek, Gateway'i yeniden başlatmak, çalışma zamanının onu yüklediğini doğrulamak ve yaygın kurulum hatalarını yönlendirmek için bu sayfayı kullanın. Yalnızca komut örnekleri için Pluginleri yönetme sayfasına bakın. Birlikte sunulan, resmî haricî ve yalnızca kaynak biçimindeki Pluginlerin oluşturulan envanteri için Plugin envanteri sayfasına bakın.

Gereksinimler

• openclaw CLI'nin kullanılabildiği bir OpenClaw kaynak kodu kopyası veya kurulumu
• seçilen kaynağa (ClawHub, npm veya bir git barındırıcısı) ağ erişimi
• ilgili Pluginin kurulum belgelerinde belirtilen, Plugine özgü tüm kimlik bilgileri, yapılandırma anahtarları veya işletim sistemi araçları
• kanallarınıza hizmet veren Gateway'in yeniden yüklenmesi veya yeniden başlatılması için izin

Hızlı başlangıç

openclaw plugins search "calendar"

# ClawHub'dan.openclaw plugins install clawhub:<package> # npm'den.openclaw plugins install npm:<package> # git'ten.openclaw plugins install git:github.com/<owner>/<repo>@<ref> # Yerel bir geliştirme kaynak kodu kopyasından.openclaw plugins install ./my-pluginopenclaw plugins install --link ./my-plugin

openclaw plugins enable <plugin-id>

openclaw gateway restart

openclaw plugins inspect <plugin-id> --runtime --json

Yapılandırma

Bir yükleme kaynağı seçin

Yalın paket belirtimleri özel uyumluluk davranışına sahiptir: birlikte sunulan bir Plugin kimliğiyle eşleşen yalın ad, birlikte sunulan bu kaynağı kullanır; resmî haricî bir Plugin kimliğiyle eşleşen yalın ad, resmî paket kataloğunu kullanır; diğer tüm yalın belirtimler geçiş sürecinde npm üzerinden yüklenir. Birlikte sunulan Pluginlerle eşleşen ham @openclaw/* belirtimleri de npm geri dönüşünden önce birlikte sunulan kopyaya çözümlenir. Birlikte sunulan kopya yerine haricî npm paketini bilinçli olarak yüklemek için npm:@openclaw/<plugin>@<version> kullanın. Belirlenimci kaynak seçimi için clawhub:, npm:, git: veya npm-pack: kullanın. Komut sözleşmesinin tamamı için openclaw plugins sayfasına bakın.

npm yüklemelerinde sabitlenmemiş belirtimler ve @latest, bu OpenClaw derlemesiyle uyumluluğunu bildiren en yeni kararlı paketi seçer. npm'nin mevcut en son sürümü, bu derlemenin desteklediğinden daha yeni bir openclaw.compat.pluginApi veya openclaw.install.minHostVersion bildirirse OpenClaw eski kararlı sürümleri tarar ve uygun olanların en yenisini yükler. Tam sürümler ve @beta gibi açık kanal etiketleri seçilen pakete sabitlenmiş olarak kalır ve uyumsuz olduklarında başarısız olur.

Operatör yükleme ilkesi

Bir Plugin yüklemesi veya güncellemesi devam etmeden önce güvenilen bir yerel ilke komutunu çalıştırmak için security.installPolicy yapılandırmasını yapın. İlke, meta verileri ve hazırlanmış kaynak yolunu alır; yüklemeye izin verebilir veya yüklemeyi engelleyebilir. Hem CLI hem de Gateway destekli yükleme/güncelleme yollarını kapsar. Plugin before_install kancaları daha sonra ve yalnızca Plugin kancalarının yüklendiği OpenClaw süreçlerinde çalışır; bu nedenle operatörün sahip olduğu yükleme kararları için bunun yerine security.installPolicy kullanın. Kullanımdan kaldırılmış --dangerously-force-unsafe-install bayrağı uyumluluk için kabul edilir ancak hiçbir işlem yapmaz: yükleme ilkesini veya OpenClaw'un yerleşik Plugin bağımlılığı engelleme listesini atlamaz.

Hem Skills hem de Pluginler tarafından kullanılan ortak security.installPolicy çalıştırma şeması için Skills yapılandırması sayfasına bakın.

Plugin ilkesini yapılandırın

Ortak Plugin yapılandırma biçimi şöyledir:

{  plugins: {    enabled: true,    allow: ["voice-call"],    deny: ["untrusted-plugin"],    load: { paths: ["~/Projects/oss/voice-call-plugin"] },    slots: { memory: "memory-core" },    entries: {      "voice-call": { enabled: true, config: { provider: "twilio" } },    },  },}

Temel ilke kuralları:

• plugins.enabled: false, tüm Pluginleri devre dışı bırakır ve keşif/yükleme çalışmasını atlar. Eski Plugin başvuruları bu etkinken eylemsiz kalır; eski kimliklerin kaldırılmasını istiyorsanız doctor temizliğini çalıştırmadan önce Pluginleri yeniden etkinleştirin.
• plugins.deny, izin verme ve Plugin başına etkinleştirme ayarlarından önceliklidir.
• plugins.allow, özel bir izin verme listesidir. İzin verme listesinin dışındaki, Pluginin sahip olduğu araçlar tools.allow içinde "*" bulunsa bile kullanılamaz.
• plugins.entries.<id>.enabled: false, yapılandırmasını korurken tek bir Plugini devre dışı bırakır.
• plugins.load.paths, açık yerel Plugin dosyaları veya dizinleri ekler. Yönetilen plugins install yerel yolları Plugin dizinleri veya arşivleri olmalıdır; bağımsız Plugin dosyaları için plugins.load.paths kullanın.
• Çalışma alanı kaynaklı Pluginler varsayılan olarak devre dışıdır; yerel çalışma alanı kodunu kullanmadan önce bunları açıkça etkinleştirin veya izin verme listesine ekleyin.
• Birlikte sunulan Pluginler, yapılandırma açıkça geçersiz kılmadığı sürece yerleşik varsayılan açık/varsayılan kapalı meta verilerini izler.
• plugins.slots.<slot> (memory veya contextEngine), özel bir kategori için bir Plugin seçer. Yuva seçimi açık etkinleştirme sayılır ve normalde isteğe bağlı olsa bile seçilen Plugini bu yuva için zorla etkinleştirir. plugins.deny ve plugins.entries.<id>.enabled: false yine de onu engeller.
• Birlikte sunulan isteğe bağlı Pluginler; yapılandırma bir sağlayıcı/model başvurusu, kanal yapılandırması, CLI arka ucu veya ajan yürütme çerçevesi çalışma zamanı gibi sahip oldukları yüzeylerden birini adlandırdığında otomatik olarak etkinleştirilebilir.
• OpenAI ailesi Codex yönlendirmesi, sağlayıcı ve çalışma zamanı Plugin sınırlarını ayrı tutar: eski Codex model başvuruları doctor'ın onardığı eski yapılandırmadır; birlikte sunulan codex Plugini ise kurallı openai/* ajan başvuruları, açık agentRuntime.id: "codex" ve eski codex/* başvuruları için Codex uygulama sunucusu çalışma zamanının sahibidir.

plugins.allow ayarlanmamışsa ve birlikte sunulmayan Pluginler çalışma alanından veya genel Plugin köklerinden otomatik olarak keşfediliyorsa başlangıç günlükleri, keşfedilen Plugin kimlikleriyle ve kısa listeler için asgari bir plugins.allow parçacığıyla birlikte plugins.allow is empty; discovered non-bundled plugins may auto-load: ... iletisini kaydeder. Güvenilen Pluginleri openclaw.json dosyasına kopyalamadan önce listelenen Plugin kimliği üzerinde openclaw plugins list --enabled --verbose veya openclaw plugins inspect <id> komutunu çalıştırın. Tanılamalar bir Pluginin without install/load-path provenance ile yüklendiğini söylediğinde de aynı güven sabitlemesi geçerlidir: bu Plugin kimliğini inceleyin, ardından onu plugins.allow içine sabitleyin veya OpenClaw'un yükleme kökenini kaydetmesi için güvenilen bir kaynaktan yeniden yükleyin.

Yapılandırma doğrulaması eski Plugin kimlikleri, izin verme listesi/araç uyuşmazlıkları veya eski birlikte sunulan Plugin yolları bildirdiğinde openclaw doctor ya da openclaw doctor --fix çalıştırın.

Plugin biçimlerini anlayın

OpenClaw iki Plugin biçimini tanır:

Her iki biçim de openclaw plugins list, openclaw plugins inspect, openclaw plugins enable ve openclaw plugins disable içinde görünür. Paket uyumluluğu sınırı için Plugin paketleri, yerel Plugin geliştirme için Plugin geliştirme sayfasına bakın.

Plugin kancaları

Pluginler, çalışma zamanında iki farklı API üzerinden kanca kaydedebilir:

• Çalışma zamanı yaşam döngüsü olayları için api.on(...) tür güvenli kancaları. Bu; ara katman, ilke, ileti yeniden yazma, istem biçimlendirme ve araç denetimi için tercih edilen yüzeydir.
• Kancalar bölümünde açıklanan iç kanca sistemi için api.registerHook(...). Bu, çoğunlukla kaba komut/yaşam döngüsü yan etkileri ve mevcut HOOK tarzı otomasyonla uyumluluk içindir.

Kısa kural: işleyici öncelik, birleştirme semantiği veya engelleme/iptal davranışı gerektiriyorsa tür güvenli kancaları kullanın. Yalnızca command:new, command:reset, message:sent veya benzer kaba olaylara tepki veriyorsa api.registerHook uygundur.

Plugin tarafından yönetilen iç kancalar openclaw hooks list içinde plugin:<id> olarak görünür. Bunları openclaw hooks üzerinden etkinleştiremez veya devre dışı bırakamazsınız; bunun yerine Plugini etkinleştirin ya da devre dışı bırakın.

Etkin Gateway'i doğrulayın

openclaw plugins list ve düz openclaw plugins inspect, soğuk yapılandırma, bildirim ve kayıt defteri durumunu okur. Bunlar, zaten çalışan bir Gateway'in aynı Plugin kodunu içe aktardığını kanıtlamaz.

Bir Plugin yüklü göründüğü hâlde canlı sohbet trafiği onu kullanmıyorsa:

openclaw gateway status --deep --require-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

Yönetilen Gateway'ler, Plugin kaynağını değiştiren Plugin yükleme, güncelleme ve kaldırma işlemlerinden sonra otomatik olarak yeniden başlatılır. VPS veya konteyner kurulumlarında, elle yeniden başlatma işleminin yalnızca bir sarmalayıcıyı ya da gözetmeni değil, kanallarınıza hizmet veren gerçek openclaw gateway run alt sürecini hedeflediğinden emin olun.

Sorun giderme

Eski Plugin yapılandırması artık keşfedilemeyen bir kanal Plugin'ini hâlâ adlandırıyorsa yapılandırma doğrulaması, bu kanal anahtarını kesin hata yerine uyarı düzeyine indirir; böylece Gateway başlangıcı diğer tüm kanallara hizmet vermeye devam edebilir. Eski Plugin ve kanal girdilerini kaldırmak için openclaw doctor --fix komutunu çalıştırın. Eski Plugin kanıtı bulunmayan bilinmeyen kanal anahtarları, yazım hatalarının görünür kalması için doğrulamayı yine başarısız kılar.

Kasıtlı kanal değiştirme için tercih edilen Plugin, channelConfigs.<channel-id>.preferOver alanını eski veya daha düşük öncelikli Plugin kimliğiyle bildirmelidir. Her iki Plugin de açıkça etkinleştirilmişse OpenClaw bu isteği korur ve sessizce tek bir sahip seçmek yerine yinelenen kanal/araç tanılamalarını bildirir.

Yüklü bir paket requires compiled runtime output for TypeScript entry ... bildiriyorsa paket, OpenClaw'ın çalışma zamanında ihtiyaç duyduğu JavaScript dosyaları olmadan yayımlanmıştır. Yayımcı derlenmiş JavaScript'i sunduktan sonra güncelleyin veya yeniden yükleyin ya da o zamana kadar Plugin'i devre dışı bırakın/kaldırın.

Engellenen Plugin yolu sahipliği

Tanılamalar blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) diyorsa ve doğrulama bunu plugin present but blocked ile izliyorsa OpenClaw, Plugin dosyalarının bunları yükleyen süreçten farklı bir Unix kullanıcısına ait olduğunu saptamıştır. Plugin yapılandırmasını yerinde tutun; dosya sistemi sahipliğini düzeltin veya OpenClaw'ı durum dizininin sahibi olan kullanıcıyla çalıştırın.

Docker kurulumlarında resmî imaj node (uid 1000) olarak çalışır; bu nedenle ana makineden bağlama yoluyla bağlanan OpenClaw yapılandırma ve çalışma alanı dizinleri normalde uid 1000 kullanıcısına ait olmalıdır:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

OpenClaw'ı kasıtlı olarak root kullanıcısıyla çalıştırıyorsanız bunun yerine yönetilen Plugin kökünün sahipliğini root olarak düzeltin:

sudo chown -R root:root /path/to/openclaw-config/npm

Sahipliği düzelttikten sonra kalıcı Plugin kayıt defterinin onarılan dosyalarla eşleşmesi için openclaw doctor --fix veya openclaw plugins registry --refresh komutunu yeniden çalıştırın.

Yavaş Plugin aracı kurulumu

Araçlar hazırlanırken agent turları takılı kalıyor gibi görünüyorsa izleme günlüklemesini etkinleştirin ve Plugin araç fabrikası zamanlama satırlarını kontrol edin:

openclaw config set logging.level traceopenclaw logs --follow

Şunu arayın:

[trace:plugin-tools] factory timings ...

Özet; Plugin kimliği, bildirilen araç adları, sonuç şekli ve aracın isteğe bağlı olup olmadığı bilgileriyle birlikte toplam fabrika süresini ve en yavaş Plugin araç fabrikalarını listeler. Tek bir fabrika en az 1 saniye sürerse veya toplam Plugin araç fabrikası hazırlığı en az 5 saniye sürerse yavaş satırlar uyarı düzeyine yükseltilir.

OpenClaw, aynı etkin istek bağlamıyla yinelenen çözümlemeler için başarılı Plugin araç fabrikası sonuçlarını önbelleğe alır. Önbellek anahtarı; etkin çalışma zamanı yapılandırmasını, çalışma alanını ve agent kimliğini, sandbox politikasını, tarayıcı ayarlarını, teslim bağlamını, istekte bulunanın kimliğini ve sahiplik durumunu içerir. Böylece bu güvenilir alanlara bağımlı fabrikalar bağlam değiştiğinde yeniden çalışır. Zamanlamalar yüksek kalıyorsa Plugin, araç tanımlarını döndürmeden önce maliyetli işlemler yapıyor olabilir.

Zamanlamaya tek bir Plugin hâkimse çalışma zamanı kayıtlarını inceleyin:

openclaw plugins inspect <plugin-id> --runtime --json

Ardından bu Plugin'i güncelleyin, yeniden yükleyin veya devre dışı bırakın. Plugin yazarları, maliyetli bağımlılık yükleme işlemini araç fabrikası içinde yapmak yerine araç yürütme yolunun arkasına taşımalıdır.

Bağımlılık kökleri, paket üst veri doğrulaması, kayıt defteri kayıtları, başlangıçta yeniden yükleme davranışı ve eski öğelerin temizlenmesi hakkında bilgi için Plugin bağımlılık çözümlemesine bakın.

İlgili

• Plugin'leri yönetin - listeleme, yükleme, güncelleme, kaldırma ve yayımlama için komut örnekleri
• openclaw plugins - eksiksiz CLI başvurusu
• Plugin envanteri - oluşturulan, paketle birlikte gelen ve harici Plugin listesi
• Plugin başvurusu - Plugin başına oluşturulan başvuru sayfaları
• Topluluk Plugin'leri - ClawHub keşfi ve dokümantasyon PR politikası
• Plugin bağımlılık çözümlemesi - yükleme kökleri, kayıt defteri kayıtları ve çalışma zamanı sınırları
• Plugin oluşturma - yerel Plugin yazma kılavuzu
• Plugin SDK'ya genel bakış - çalışma zamanı kaydı, kancalar ve API alanları
• Plugin manifesti - manifest ve paket üst verileri