Pluginler

Plugin'ler OpenClaw'ı kanallar, model sağlayıcıları, ajan harness'ları, araçlar, Skills, konuşma, gerçek zamanlı transkripsiyon, ses, medya anlama, üretim, web getirme, web arama ve diğer çalışma zamanı yetenekleriyle genişletir.

Bir Plugin kurmak, Gateway'i yeniden başlatmak, çalışma zamanının onu yüklediğini doğrulamak ve yaygın kurulum hatalarını yönlendirmek istediğinizde bu sayfayı kullanın. Yalnızca komut örnekleri için bkz. Plugin'leri yönet. Paketlenmiş, resmi harici ve yalnızca kaynak Plugin'lerin tam oluşturulmuş envanteri için bkz. Plugin envanteri.

Gereksinimler

Bir Plugin kurmadan önce şunlara sahip olduğunuzdan emin olun:

• openclaw CLI kullanılabilir olan bir OpenClaw checkout'ı veya kurulumu
• ClawHub, npm veya bir git host'u gibi seçilen kaynağa ağ erişimi
• ilgili Plugin'in kurulum belgelerinde belirtilen Plugin'e özgü 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"

# From ClawHub.openclaw plugins install clawhub:<package> # From npm.openclaw plugins install npm:<package> # From git.openclaw plugins install git:github.com/<owner>/<repo>@<ref> # From a local development checkout.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 kurulum kaynağı seçin

Yalın paket belirtimlerinin özel uyumluluk davranışı vardır. Yalın ad paketlenmiş bir Plugin id'siyle eşleşirse OpenClaw o paketlenmiş kaynağı kullanır. Resmi harici bir Plugin id'siyle eşleşirse OpenClaw resmi paket kataloğunu kullanır. Diğer sıradan yalın paket belirtimleri lansman geçişi sırasında npm üzerinden kurulur. Paketlenmiş Plugin'lerle eşleşen ham @openclaw/* paket belirtimleri de npm fallback'inden önce paketlenmiş kopyaya çözümlenir. Görüntüye ait paketlenmiş kopya yerine özellikle harici npm paketini istediğinizde npm:@openclaw/<plugin>@<version> kullanın. Deterministik kaynak seçimine ihtiyacınız olduğunda clawhub:, npm:, git: veya npm-pack: kullanın. Tam komut sözleşmesi için bkz. openclaw plugins.

npm kurulumlarında, sabitlenmemiş paket belirtimleri ve @latest, bu OpenClaw derlemesiyle uyumluluk duyuran en yeni kararlı paketi seçer. npm'in mevcut en son sürümü daha yeni bir openclaw.compat.pluginApi veya openclaw.install.minHostVersion bildirirse OpenClaw daha eski kararlı paket sürümlerini tarar ve uyan en yeni sürümü kurar. Tam sürümler ve @beta gibi açık kanal tag'leri seçilen pakete sabit kalır ve uyumsuz olduğunda başarısız olur.

Operatör kurulum politikası

Plugin kurulumu veya güncellemesi ilerlemeden önce güvenilir bir yerel politika komutu çalıştırmak için security.installPolicy yapılandırın. Politika, metadata ile aşamalanmış kaynak yolunu alır ve kuruluma izin verebilir veya engelleyebilir. CLI ve Gateway destekli Plugin kurulum/güncelleme yollarını kapsar. Plugin before_install hook'ları daha sonra yalnızca Plugin hook'larının yüklendiği OpenClaw süreçlerinde çalışır; bu nedenle operatöre ait kurulum kararları için security.installPolicy kullanın. Kullanımdan kaldırılan --dangerously-force-unsafe-install bayrağı uyumluluk için kabul edilir ancak kurulum politikasını veya OpenClaw'ın yerleşik Plugin bağımlılığı denylist'ini atlatmaz.

Hem Skills hem de Plugin'ler tarafından kullanılan paylaşılan security.installPolicy exec şeması için bkz. Skills yapılandırması.

Plugin politikasını yapılandırın

Yaygın Plugin yapılandırma şekli şudur:

{  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 politika kuralları:

• plugins.enabled: false, tüm Plugin'leri devre dışı bırakır ve Plugin keşif/yükleme çalışmasını atlar. Bu etkinken eski Plugin başvuruları etkisizdir; eski id'lerin kaldırılmasını istediğinizde doctor temizliğini çalıştırmadan önce Plugin'leri yeniden etkinleştirin.
• plugins.deny, allow ve Plugin başına etkinleştirmeye üstün gelir.
• plugins.allow özel bir allowlist'tir. Plugin'e ait araçlar, tools.allow "*" içerse bile allowlist dışında kullanılamaz.
• plugins.entries.<id>.enabled: false, yapılandırmasını koruyarak tek bir Plugin'i 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.
• Workspace kökenli Plugin'ler varsayılan olarak devre dışıdır; yerel workspace kodunu kullanmadan önce açıkça etkinleştirin veya allowlist'e alın.
• Paketlenmiş Plugin'ler, yapılandırma açıkça geçersiz kılmadıkça yerleşik default-on/default-off metadata'sını izler.
• plugins.slots.<slot>, bellek ve bağlam motorları gibi özel kategoriler için bir Plugin seçer. Slot seçimi, açık etkinleştirme sayılarak seçilen Plugin'i o slot için zorla etkinleştirir; aksi halde opt-in olacak olsa bile yüklenebilir. plugins.deny ve plugins.entries.<id>.enabled: false yine de engeller.
• Paketlenmiş opt-in Plugin'ler, yapılandırma sağlayıcı/model ref'i, kanal yapılandırması, CLI backend'i veya ajan harness çalışma zamanı gibi sahip oldukları yüzeylerden birini adlandırdığında otomatik etkinleşebilir.
• OpenAI ailesi Codex yönlendirmesi sağlayıcı ve çalışma zamanı Plugin sınırlarını ayrı tutar: legacy Codex model ref'leri doctor tarafından onarılan legacy yapılandırmadır; paketlenmiş codex Plugin'i ise canonical openai/* ajan ref'leri, açık agentRuntime.id: "codex" ve legacy codex/* ref'leri için Codex app-server çalışma zamanına sahiptir.

plugins.allow ayarlanmamışsa ve paketlenmemiş Plugin'ler workspace veya global Plugin köklerinden otomatik keşfediliyorsa başlangıç günlükleri plugins.allow is empty; discovered non-bundled plugins may auto-load: ... gösterir. Uyarı keşfedilen Plugin id'lerini ve kısa listeler için minimal bir plugins.allow snippet'ini içerir. Güvenilir Plugin'leri openclaw.json içine kopyalamadan önce listelenen Plugin id'siyle openclaw plugins list --enabled --verbose veya openclaw plugins inspect <id> çalıştırın. Aynı güven sabitleme yönlendirmesi, tanılama bir Plugin'in without install/load-path provenance yüklendiğini söylediğinde de geçerlidir: o Plugin id'sini inceleyin, ardından güvenilir id'yi plugins.allow içinde sabitleyin veya OpenClaw'ın kurulum provenance'ını kaydetmesi için güvenilir bir kaynaktan yeniden kurun.

Yapılandırma doğrulaması eski Plugin id'leri, allowlist/araç uyuşmazlıkları veya legacy paketlenmiş Plugin yolları bildirdiğinde openclaw doctor veya 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. Bundle uyumluluk sınırı için bkz. Plugin bundle'ları, native Plugin yazımı için bkz. Plugin geliştirme.

Plugin hook'ları

Plugin'ler çalışma zamanında hook kaydedebilir, ancak farklı görevlere sahip iki farklı API vardır.

• Çalışma zamanı lifecycle hook'ları için api.on(...) üzerinden typed hook'ları kullanın. Middleware, politika, mesaj yeniden yazma, prompt şekillendirme ve araç kontrolü için tercih edilen yüzey budur.
• Yalnızca Hook'lar içinde açıklanan dahili hook sistemine katılmak istediğinizde api.registerHook(...) kullanın. Bu ağırlıklı olarak kaba komut/lifecycle yan etkileri ve mevcut HOOK tarzı otomasyonla uyumluluk içindir.

Hızlı kural:

• Handler öncelik, merge semantiği veya engelleme/iptal davranışı gerektiriyorsa typed Plugin hook'larını kullanın.
• Handler yalnızca command:new, command:reset, message:sent veya benzer kaba olaylara tepki veriyorsa api.registerHook(...) uygundur.

Plugin tarafından yönetilen dahili hook'lar openclaw hooks list içinde plugin:<id> ile görünür. Bunları openclaw hooks üzerinden etkinleştiremez veya devre dışı bırakamazsınız; bunun yerine Plugin'i etkinleştirin veya devre dışı bırakın.

Etkin Gateway'i doğrulayın

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

Bir Plugin kurulu görünürken 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 kurma, güncelleme ve kaldırma değişikliklerinden sonra otomatik olarak yeniden başlar. VPS veya container kurulumlarında, elle yapılan yeniden başlatmanın kanallarınıza hizmet veren gerçek openclaw gateway run alt sürecini hedeflediğinden emin olun; yalnızca bir sarmalayıcıyı veya supervisor'ı değil.

Sorun giderme

Eski Plugin config'i hâlâ artık keşfedilemeyen bir kanal Plugin'ini adlandırıyorsa, Gateway başlangıcı, diğer tüm kanalları engellemek yerine o Plugin destekli kanalı atlar. Eski Plugin ve kanal girdilerini kaldırmak için openclaw doctor --fix çalıştırın. Eski Plugin kanıtı olmayan bilinmeyen kanal anahtarları yine de doğrulamada başarısız olur, böylece yazım hataları görünür kalır.

Amaçlı kanal değiştirme için, tercih edilen Plugin channelConfigs.<channel-id>.preferOver alanında eski veya daha düşük öncelikli Plugin id'sini bildirmelidir. Her iki Plugin de açıkça etkinleştirilmişse OpenClaw bu isteği korur ve bir sahibi sessizce seçmek yerine yinelenen kanal veya araç tanıları bildirir.

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

Engellenmiş Plugin yolu sahipliği

Plugin tanıları blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) diyor ve config doğrulaması plugin present but blocked ile devam ediyorsa, OpenClaw Plugin dosyalarının, onları yükleyen süreçten farklı bir Unix kullanıcısına ait olduğunu bulmuştur. Plugin config'ini yerinde tutun; dosya sistemi sahipliğini düzeltin veya OpenClaw'ı state dizininin sahibi olan aynı kullanıcı olarak çalıştırın.

Docker kurulumlarında resmi image node (uid 1000) olarak çalışır; bu yüzden host bind-mounted OpenClaw config ve çalışma alanı dizinleri normalde uid 1000 tarafından sahiplenilmelidir:

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

OpenClaw'ı bilinçli olarak root olarak çalıştırıyorsanız, bunun yerine yönetilen Plugin kökünü root sahipliğine onarın:

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 araç kurulumu

Agent turn'leri araçları hazırlarken takılmış gibi görünüyorsa, trace günlük kaydını 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, toplam fabrika süresini ve en yavaş Plugin araç fabrikalarını listeler; Plugin id'si, bildirilen araç adları, sonuç şekli ve aracın optional olup olmadığı dahil. Tek bir fabrika en az 1 sn sürdüğünde veya toplam Plugin araç fabrikası hazırlığı en az 5 sn sürdüğünde yavaş satırlar uyarıya yükseltilir.

OpenClaw, aynı etkin istek bağlamıyla tekrarlanan çözümlemeler için başarılı Plugin araç fabrikası sonuçlarını önbelleğe alır. Önbellek anahtarı etkin çalışma zamanı config'ini, çalışma alanını, agent/session id'lerini, sandbox ilkesini, tarayıcı ayarlarını, teslim bağlamını, istekte bulunan kimliğini ve sahiplik durumunu içerir; bu nedenle bu güvenilir alanlara bağlı fabrikalar bağlam değiştiğinde yeniden çalıştırılır. Zamanlamalar yüksek kalıyorsa, Plugin araç tanımlarını döndürmeden önce pahalı işler yapıyor olabilir.

Zamanlamaya bir Plugin baskın geliyorsa, çalışma zamanı kayıtlarını inceleyin:

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

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

Bağımlılık kökleri, paket metadata doğrulaması, kayıt defteri kayıtları, başlangıçta yeniden yükleme davranışı ve legacy temizliği için bkz. Plugin bağımlılık çözümlemesi.

İlgili

• Plugin'leri yönet - listeleme, kurma, güncelleme, kaldırma ve yayımlama için komut örnekleri
• openclaw plugins - tam CLI referansı
• Plugin envanteri - oluşturulan bundled ve external Plugin listesi
• Plugin referansı - oluşturulan Plugin başına referans sayfaları
• Community Plugin'leri - ClawHub keşfi ve dokümantasyon PR ilkesi
• Plugin bağımlılık çözümlemesi - kurulum kökleri, kayıt defteri kayıtları ve çalışma zamanı sınırları
• Plugin oluşturma - native Plugin yazma kılavuzu
• Plugin SDK genel bakışı - çalışma zamanı kaydı, hook'lar ve API alanları
• Plugin manifest'i - manifest ve paket metadata'sı