Plugin manifestosu

Bu sayfa yerel OpenClaw Plugin manifesti olan openclaw.plugin.json dosyasını ele alır. Uyumlu paket düzenleri (Codex, Claude, Cursor) için Plugin paketleri bölümüne bakın.

Uyumlu paket biçimleri bunun yerine kendi manifest dosyalarını kullanır:

• Codex paketi: .codex-plugin/plugin.json
• Claude paketi: .claude-plugin/plugin.json veya manifestsiz varsayılan Claude bileşen düzeni
• Cursor paketi: .cursor-plugin/plugin.json

OpenClaw bu düzenleri otomatik olarak algılar ancak aşağıdaki openclaw.plugin.json şemasına göre doğrulamaz. Uyumlu bir paketin düzeni OpenClaw'ın çalışma zamanı beklentileriyle eşleştiğinde OpenClaw; paket meta verilerini, bildirilmiş beceri köklerini, Claude komut köklerini, Claude settings.json varsayılanlarını, Claude LSP varsayılanlarını ve desteklenen kanca paketlerini okur.

Her yerel OpenClaw Plugin'i, Plugin kökünde openclaw.plugin.json dosyasını mutlaka sunmalıdır. OpenClaw, Plugin kodunu çalıştırmadan yapılandırmayı doğrulamak için bu dosyayı okur. Eksik veya geçersiz bir manifest, yapılandırma doğrulamasını engeller ve Plugin hatası olarak değerlendirilir.

Plugin sisteminin tam kılavuzu için Pluginler, yerel yetenek modeli ve mevcut harici uyumluluk yönergeleri için Yetenek modeli bölümüne bakın.

Bu dosyanın işlevi

openclaw.plugin.json, OpenClaw'ın Plugin kodunuzu yüklemeden önce okuduğu meta verilerdir. İçindeki her şey, Plugin çalışma zamanını başlatmadan incelenebilecek kadar düşük maliyetli olmalıdır.

Şunlar için kullanın:

• Plugin kimliği, yapılandırma doğrulaması ve yapılandırma kullanıcı arayüzü ipuçları
• kimlik doğrulama, ilk kullanım ve kurulum meta verileri (takma ad, otomatik etkinleştirme, sağlayıcı ortam değişkenleri, kimlik doğrulama seçenekleri)
• kontrol düzlemi yüzeyleri için etkinleştirme ipuçları
• kısa model ailesi sahipliği
• statik yetenek sahipliği anlık görüntüleri (contracts)
• paylaşılan openclaw qa sunucusunun inceleyebileceği kalite güvencesi çalıştırıcısı meta verileri
• katalog ve doğrulama yüzeyleriyle birleştirilen kanala özgü yapılandırma meta verileri

Şunlar için kullanmayın: çalışma zamanı davranışını kaydetmek, kod giriş noktalarını bildirmek veya npm kurulum meta verilerini tanımlamak. Bunlar Plugin kodunuzda ve package.json dosyasında yer almalıdır.

En küçük örnek

{  "id": "voice-call",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

Kapsamlı örnek

{  "id": "openrouter",  "name": "OpenRouter",  "description": "OpenRouter provider plugin",  "version": "1.0.0",  "providers": ["openrouter"],  "modelSupport": {    "modelPrefixes": ["router-"]  },  "modelIdNormalization": {    "providers": {      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  },  "providerEndpoints": [    {      "endpointClass": "openrouter",      "hostSuffixes": ["openrouter.ai"]    }  ],  "providerRequest": {    "providers": {      "openrouter": {        "family": "openrouter"      }    }  },  "cliBackends": ["openrouter-cli"],  "syntheticAuthRefs": ["openrouter-cli"],  "setup": {    "providers": [      {        "id": "openrouter",        "envVars": ["OPENROUTER_API_KEY"]      }    ]  },  "providerAuthAliases": {    "openrouter-coding": "openrouter"  },  "channelEnvVars": {    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "OpenRouter API key",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "OpenRouter API key",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "API key",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

Üst düzey alan başvurusu

katalog referansı

catalog, plugin tarayıcılarına isteğe bağlı görüntüleme ipuçları sağlar. Ana sistemler bu ipuçlarını yok sayabilir. Bunlar hiçbir zaman plugini kurmaz veya etkinleştirmez ve pluginin çalışma zamanı davranışını ya da güven düzeyini değiştirmez.

{  "catalog": {    "featured": true,    "order": 10  }}

Üretim sağlayıcısı meta verileri referansı

Üretim sağlayıcısı meta veri alanları, eşleşen contracts.*GenerationProviders listesinde bildirilen sağlayıcılar için statik kimlik doğrulama sinyallerini tanımlar. OpenClaw, sağlayıcı çalışma zamanı yüklenmeden önce bu alanları okur; böylece çekirdek araçlar, her sağlayıcı pluginini içe aktarmadan bir üretim sağlayıcısının kullanılabilir olup olmadığına karar verebilir.

Bu alanları yalnızca düşük maliyetli, bildirimsel bilgiler için kullanın. Aktarım, istek dönüşümleri, belirteç yenileme, kimlik bilgisi doğrulaması ve gerçek üretim davranışı plugin çalışma zamanında kalır.

{  "contracts": {    "imageGenerationProviders": ["example-image"]  },  "imageGenerationProviderMetadata": {    "example-image": {      "aliases": ["example-image-oauth"],      "authProviders": ["example-image"],      "configSignals": [        {          "rootPath": "plugins.entries.example-image.config",          "overlayPath": "image",          "mode": {            "path": "mode",            "default": "local",            "allowed": ["local"]          },          "requiredAny": ["workflow", "workflowPath"],          "required": ["promptNodeId"]        }      ],      "authSignals": [        {          "provider": "example-image"        },        {          "provider": "example-image-oauth",          "providerBaseUrl": {            "provider": "example-image",            "defaultBaseUrl": "https://api.example.com/v1",            "allowedBaseUrls": ["https://api.example.com/v1"]          }        }      ]    }  }}

Her meta veri girdisi şunları destekler:

Her configSignals girdisi şunları destekler:

Her mode koruması şunları destekler:

Her authSignals girdisi şunları destekler:

Her providerBaseUrl koruması şunları destekler:

Araç meta verileri referansı

toolMetadata, araç adına göre anahtarlanmış olarak üretim sağlayıcısı meta verileriyle aynı configSignals ve authSignals biçimlerini kullanır. contracts.tools sahipliği bildirir. toolMetadata, OpenClaw'ın yalnızca araç fabrikasının null döndürmesini sağlamak için bir plugin çalışma zamanını içe aktarmaktan kaçınabilmesi amacıyla düşük maliyetli kullanılabilirlik kanıtı bildirir.

{  "setup": {    "providers": [      {        "id": "example",        "envVars": ["EXAMPLE_API_KEY"]      }    ]  },  "contracts": {    "tools": ["example_search"]  },  "toolMetadata": {    "example_search": {      "authSignals": [        {          "provider": "example"        }      ],      "configSignals": [        {          "rootPath": "plugins.entries.example.config",          "overlayPath": "search",          "required": ["apiKey"]        }      ]    }  }}

toolMetadata girdileri, yukarıdaki ortak configSignals/authSignals alanlarına ek olarak optional (aracı plugin etkinleştirmesi için zorunlu değil olarak işaretler) ve replaySafe (tamamlanmamış bir model turundan sonra araç yürütmesinin güvenle yinelenebileceğini belirtir) alanlarını da kabul eder.

Bir aracın toolMetadata değeri yoksa OpenClaw mevcut davranışı korur ve araç sözleşmesi politikayla eşleştiğinde sahibi olan plugini yükler. Fabrikası kimlik doğrulamasına/yapılandırmaya bağlı olan kritik yol araçları için plugin yazarları, çekirdeğin sorgulamak amacıyla çalışma zamanını içe aktarmasını sağlamak yerine toolMetadata bildirmelidir.

providerAuthChoices referansı

Her providerAuthChoices girdisi bir ilk kurulum veya kimlik doğrulama seçeneğini tanımlar. OpenClaw bunu sağlayıcı çalışma zamanı yüklenmeden önce okur. Sağlayıcı kurulum listeleri; sağlayıcı çalışma zamanını yüklemeden bu manifest seçeneklerini, tanımlayıcıdan türetilen kurulum seçeneklerini ve kurulum kataloğu meta verilerini kullanır.

commandAliases başvurusu

Kullanıcıların yanlışlıkla plugins.allow içine ekleyebileceği veya kök CLI komutu olarak çalıştırmayı deneyebileceği bir çalışma zamanı komut adı Plugin'e ait olduğunda commandAliases kullanın. OpenClaw, Plugin çalışma zamanı kodunu içe aktarmadan tanılama yapmak için bu meta verileri kullanır.

{  "commandAliases": [    {      "name": "dreaming",      "kind": "runtime-slash",      "cliCommand": "memory"    }  ]}

activation başvurusu

Plugin, hangi kontrol düzlemi olaylarının kendisini bir etkinleştirme/yükleme planına dahil etmesi gerektiğini düşük maliyetle bildirebiliyorsa activation kullanın.

Bu blok bir yaşam döngüsü API'si değil, planlayıcı meta verisidir. Çalışma zamanı davranışını kaydetmez, register(...) işlevinin yerini almaz ve Plugin kodunun zaten yürütülmüş olduğunu garanti etmez. Etkinleştirme planlayıcısı; providers, channels, commandAliases, setup.providers, contracts.tools ve kancalar gibi mevcut bildirim sahipliği meta verilerine geri dönmeden önce aday Plugin'leri daraltmak için bu alanları kullanır.

Sahipliği zaten açıklayan en dar meta veriyi tercih edin. İlişkiyi bu alanlar ifade ediyorsa providers, channels, commandAliases, kurulum tanımlayıcıları veya contracts kullanın. Bu sahiplik alanlarıyla temsil edilemeyen ek planlayıcı ipuçları için activation kullanın. claude-cli, my-cli veya google-gemini-cli gibi CLI çalışma zamanı takma adları için üst düzey cliBackends alanını kullanın; activation.onAgentHarnesses yalnızca zaten bir sahiplik alanı bulunmayan gömülü aracı altyapısı kimlikleri içindir.

Her Plugin, activation.onStartup değerini bilinçli olarak ayarlamalıdır. Plugin'in Gateway başlatılırken çalışması gerekiyorsa bunu yalnızca true olarak ayarlayın. Plugin başlangıçta etkin değilse ve yalnızca daha dar tetikleyicilerden yüklenmesi gerekiyorsa false olarak ayarlayın. onStartup alanının belirtilmemesi artık Plugin'in başlangıçta örtük olarak yüklenmesine neden olmaz; başlangıç, kanal, yapılandırma, aracı altyapısı, bellek veya daha dar diğer etkinleştirme tetikleyicileri için açık etkinleştirme meta verileri kullanın.

{  "activation": {    "onStartup": false,    "onProviders": ["openai"],    "onCommands": ["models"],    "onChannels": ["web"],    "onRoutes": ["gateway-webhook"],    "onConfigPaths": ["browser"],    "onCapabilities": ["provider", "tool"]  }}

Mevcut canlı tüketiciler:

• Gateway başlangıç planlaması, açık başlangıç içe aktarımı için activation.onStartup kullanır.
• Komutla tetiklenen CLI planlaması, eski commandAliases[].cliCommand veya commandAliases[].name alanlarına geri döner.
• Aracı çalışma zamanı başlangıç planlaması, gömülü altyapılar için activation.onAgentHarnesses, CLI çalışma zamanı takma adları içinse üst düzey cliBackends[] kullanır.
• Kanalla tetiklenen kurulum/kanal planlaması, açık kanal etkinleştirme meta verileri eksik olduğunda eski channels[] sahipliğine geri döner.
• Başlangıç Plugin planlaması, paketle birlikte gelen tarayıcı Plugin'inin browser bloğu gibi kanal dışı kök yapılandırma yüzeyleri için activation.onConfigPaths kullanır.
• Sağlayıcıyla tetiklenen kurulum/çalışma zamanı planlaması, açık sağlayıcı etkinleştirme meta verileri eksik olduğunda eski providers[] ve üst düzey cliBackends[] sahipliğine geri döner.

Planlayıcı tanılamaları, açık etkinleştirme ipuçlarını bildirim sahipliği geri dönüşlerinden ayırt edebilir. Örneğin activation-command-hint, activation.onCommands alanının eşleştiği anlamına gelirken manifest-command-alias, planlayıcının bunun yerine commandAliases sahipliğini kullandığı anlamına gelir. Bu neden etiketleri ana makine tanılamaları ve testler içindir; Plugin yazarları, sahipliği en iyi açıklayan meta verileri bildirmeye devam etmelidir.

qaRunners başvurusu

Bir Plugin, paylaşılan openclaw qa kökü altında bir veya daha fazla aktarım çalıştırıcısı sağladığında qaRunners kullanın. Bu meta verileri hafif ve statik tutun; Plugin çalışma zamanı, eşleşen qaRunnerCliRegistrations dışa aktarımını sunan hafif bir runtime-api.ts yüzeyi aracılığıyla gerçek CLI kaydının sahibi olmaya devam eder. İsteğe bağlı adapterFactory, kayıtlı komutun çalıştırıcısını değiştirmeden aktarımı paylaşılan QA senaryolarına sunar.

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"    }  ]}

adapterFactory kimliği commandName ile eşleşmelidir. Manifestte bulunmayan komutlar için kayıtları dışa aktarmayın.

setup referansı

Kurulum ve ilk kullanım yüzeyleri, çalışma zamanı yüklenmeden önce Plugin'e ait düşük maliyetli meta verilere ihtiyaç duyduğunda setup kullanın.

{  "setup": {    "providers": [      {        "id": "openai",        "authMethods": ["api-key"],        "envVars": ["OPENAI_API_KEY"],        "authEvidence": [          {            "type": "local-file-with-env",            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",            "requiresAllEnv": ["OPENAI_PROJECT"],            "credentialMarker": "openai-local-credentials",            "source": "openai local credentials"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

Üst düzey cliBackends geçerliliğini korur ve CLI çıkarım arka uçlarını açıklamaya devam eder. setup.cliBackends, yalnızca meta veri olarak kalması gereken kontrol düzlemi/kurulum akışlarına yönelik kuruluma özgü tanımlayıcı yüzeyidir.

Mevcut olduklarında setup.providers ve setup.cliBackends, kurulum keşfi için tercih edilen, önce tanımlayıcıya dayalı arama yüzeyidir. Tanımlayıcı yalnızca aday Plugin'i daraltıyorsa ve kurulum hâlâ kurulum zamanında daha kapsamlı çalışma zamanı kancalarına ihtiyaç duyuyorsa requiresRuntime: true ayarlayın ve yedek yürütme yolu olarak setup-api öğesini yerinde tutun.

OpenClaw ayrıca genel sağlayıcı kimlik doğrulama ve ortam değişkeni aramalarına setup.providers[].envVars öğesini dahil eder. providerAuthEnvVars, kullanımdan kaldırma dönemi boyunca bir uyumluluk bağdaştırıcısı aracılığıyla desteklenmeye devam eder; ancak bunu hâlâ kullanan paketle birlikte gelmeyen Plugin'ler bir manifest tanılama bildirimi alır. Yeni Plugin'ler, kurulum/durum ortam meta verilerini setup.providers[].envVars içine yerleştirmelidir.

Bir faturalandırma veya kuruluş düzeyindeki kimlik bilgisi, çıkarım kimlik bilgisine dönüşmeden resolveUsageAuth öğesini etkinleştirmesi gerektiğinde providerUsageAuthEnvVars kullanın. Bu adlar çalışma alanı dotenv engellemesine, ACP alt süreçlerinden kaldırmaya, korumalı alan sır filtrelemesine ve kapsamlı sır temizlemeye dahil edilir. Sağlayıcı çalışma zamanı, değeri yine resolveUsageAuth içinde okur ve sınıflandırır.

OpenClaw, kurulum girdisi bulunmadığında veya setup.requiresRuntime: false kurulum çalışma zamanının gereksiz olduğunu bildirdiğinde basit kurulum seçeneklerini setup.providers[].authMethods öğesinden de türetebilir. Özel etiketler, CLI bayrakları, ilk kullanım kapsamı ve asistan meta verileri için açık providerAuthChoices girdileri tercih edilmeye devam eder.

requiresRuntime: false ayarını yalnızca bu tanımlayıcılar kurulum yüzeyi için yeterli olduğunda kullanın. OpenClaw, açık false değerini yalnızca tanımlayıcıya dayalı bir sözleşme olarak değerlendirir ve kurulum araması için setup-api veya openclaw.setupEntry öğesini yürütmez. Yalnızca tanımlayıcı kullanan bir Plugin yine de bu kurulum çalışma zamanı girdilerinden birini sunuyorsa OpenClaw ek bir tanılama bildirimi raporlar ve girdiyi yok saymaya devam eder. requiresRuntime öğesinin belirtilmemesi, bayrağı kullanmadan tanımlayıcı ekleyen mevcut Plugin'lerin bozulmaması için eski yedek davranışı korur.

Kurulum araması Plugin'e ait setup-api kodunu yürütebildiğinden, normalleştirilmiş setup.providers[].id ve setup.cliBackends[] değerleri keşfedilen Plugin'ler genelinde benzersiz kalmalıdır. Belirsiz sahiplikte, keşif sırasına göre bir kazanan seçmek yerine güvenli biçimde hata oluşur.

Kurulum çalışma zamanı yürütüldüğünde, setup-api manifest tanımlayıcılarında bildirilmeyen bir sağlayıcı veya CLI arka ucu kaydederse ya da bir tanımlayıcının eşleşen çalışma zamanı kaydı yoksa kurulum kayıt defteri tanılamaları tanımlayıcı sapmasını raporlar. Bu tanılamalar ek niteliktedir ve eski Plugin'leri reddetmez.

setup.providers referansı

authEvidence, çalışma zamanı kodu yüklenmeden doğrulanabilen, sağlayıcıya ait yerel kimlik bilgisi işaretleyicileri içindir. Bu denetimler düşük maliyetli ve yerel kalmalıdır: ağ çağrısı, anahtarlık veya sır yöneticisi okuması, kabuk komutu ve sağlayıcı API yoklaması yapılamaz.

Desteklenen kanıt girdileri:

setup alanları

uiHints referansı

uiHints, yapılandırma alanı adlarından küçük işleme ipuçlarına eşlenen bir haritadır. Anahtarlar iç içe yapılandırma alanları için nokta kullanabilir; ancak hiçbir yol parçası __proto__, constructor veya prototype olamaz. Kurulum bu adları reddeder.

{  "uiHints": {    "apiKey": {      "label": "API key",      "help": "Used for OpenRouter requests",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

Her alan ipucu şunları içerebilir:

contracts referansı

contracts öğesini yalnızca OpenClaw'ın Plugin çalışma zamanını içe aktarmadan okuyabileceği statik yetenek sahipliği meta verileri için kullanın.

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"],    "trustedToolPolicies": ["workflow-budget"],    "externalAuthProviders": ["acme-ai"],    "embeddingProviders": ["openai-compatible"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "musicGenerationProviders": ["stability-audio"],    "documentExtractors": ["example-docs"],    "webContentExtractors": ["firecrawl"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "workerProviders": ["example-worker"],    "usageProviders": ["acme-ai"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

Her liste isteğe bağlıdır:

contracts.embeddedExtensionFactories, yalnızca birlikte gelen Codex app-server uzantı fabrikaları için korunur. Birlikte gelen araç sonucu dönüşümleri bunun yerine contracts.agentToolResultMiddleware bildirmeli ve api.registerAgentToolResultMiddleware(...) ile kaydolmalıdır. Yüklü Plugin'ler aynı ara yazılım bağlantı noktasını yalnızca açıkça etkinleştirildiklerinde ve yalnızca contracts.agentToolResultMiddleware içinde bildirdikleri çalışma zamanları için kullanabilir.

Ana makinenin güvendiği araç öncesi politika katmanına ihtiyaç duyan yüklü Plugin'ler, kaydedilen her yerel kimliği contracts.trustedToolPolicies içinde bildirmeli ve açıkça etkinleştirilmelidir. Birlikte gelen Plugin'ler mevcut güvenilir politika yolunu korur; ancak bildirilmemiş politika kimliklerine sahip yüklü Plugin'ler kayıt öncesinde reddedilir. Politika kimlikleri kaydeden Plugin kapsamında olduğundan iki Plugin de workflow-budget kimliğini bildirip kaydedebilir; tek bir Plugin aynı yerel kimliği iki kez kaydedemez.

Çalışma zamanı api.registerTool(...) kayıtları contracts.tools ile eşleşmelidir. Araç keşfi, yalnızca istenen araçların sahibi olabilecek Plugin çalışma zamanlarını yüklemek için bu listeyi kullanır.

resolveExternalAuthProfiles uygulayan sağlayıcı Plugin'leri contracts.externalAuthProviders bildirmelidir; bildirilmemiş harici kimlik doğrulama kancaları yok sayılır.

Hem resolveUsageAuth hem de fetchUsageSnapshot uygulayan sağlayıcı Plugin'leri, otomatik keşfedilen her sağlayıcı kimliğini contracts.usageProviders içinde bildirmelidir. Kullanım keşfi, çalışma zamanı kodunu yüklemeden önce bu sözleşmeyi okur ve yalnızca bildirilen sahipleri yükledikten sonra her iki kancayı da doğrular.

Genel gömme sağlayıcıları, api.registerEmbeddingProvider(...) ile kaydedilen her bağdaştırıcı için contracts.embeddingProviders bildirmelidir. Bellek araması tarafından kullanılan sağlayıcılar dâhil, yeniden kullanılabilir vektör üretimi için genel sözleşmeyi kullanın. contracts.memoryEmbeddingProviders, kullanımdan kaldırılmış belleğe özgü uyumluluktur ve yalnızca mevcut sağlayıcılar genel gömme sağlayıcısı bağlantı noktasına taşınırken korunur.

İşçi sağlayıcıları, her api.registerWorkerProvider(...) kimliğini contracts.workerProviders içinde bildirmelidir. Çekirdek, provision çağrısından önce kalıcı niyeti saklar; sağlayıcılar harici tahsisten önce ayarlarını doğrular ve aynı işlem kimliğiyle yinelenen çağrılar aynı kirayı benimsemelidir. Çekirdek ayrıca doğrulanmış bu ayar anlık görüntüsünü saklar ve adlandırılmış profil değiştirilmiş veya kaldırılmış olsa bile leaseId ile birlikte inspect({ leaseId, profile }) ve destroy({ leaseId, profile }) çağrılarına iletir. Yok etme eşgüçlüdür, inceleme kapalı active / destroyed / unknown durum birleşimini döndürür ve SSH özel anahtar malzemesine yalnızca SecretRef üzerinden başvurulur. Sağlanan SSH uç noktaları, çekirdeğin bağlanmadan önce ana makineyi sabitleyebilmesi için güvenilir kaynak sağlama çıktısından, ana makine adı veya yorum olmadan tam olarak algorithm base64 biçiminde genel bir hostKey de içermelidir. Dinamik kimlik başvuruları oluşturan sağlayıcılar, yetkili resolveSshIdentity({ leaseId, profile, keyRef }) yöntemini uygulayabilir; bunu uygulamayan sağlayıcılar çekirdeğin genel gizli değer çözümleyicisini kullanır. Yetkili bir unknown, etkin bir yerel kaydı sahipsiz bırakır; saklanan bir yok etme isteğinden sonra ise kapatmayı doğrular.

contracts.gatewayMethodDispatch şu anda "authenticated-request" değerini kabul eder. Bu, Gateway kontrol düzlemi yöntemlerini kasıtlı olarak süreç içinde yönlendiren yerel Plugin HTTP rotaları için bir API düzeni kapısıdır; kötü amaçlı yerel Plugin'lere karşı bir korumalı alan değildir. Bunu yalnızca zaten Gateway HTTP kimlik doğrulaması gerektiren ve sıkı biçimde incelenmiş, birlikte gelen/operatör yüzeyleri için kullanın. Yetkilendirilmiş bir rota, Gateway kök iş kabulü kapalıyken yalnızca ayrıca auth: "gateway" ve rotaya özgü gatewayRuntimeScopeSurface: "trusted-operator" bildirdiğinde erişilebilir kalır; aynı Plugin'in sıradan kardeş rotaları kabul sınırının arkasında kalır. Böylece tüm Plugin'e kabul atlama yetkisi verilmeden askıya alma durumu ve sürdürme işlemi erişilebilir tutulur. Ayrıştırma ve yanıt biçimlendirmeyi yönlendirme dışında sınırlı tutun; esaslı veya değişiklik yapan işler, kabul ve kapsam uygulamasının sahibi olan Gateway yöntem yönlendirmesi üzerinden gerçekleştirilmelidir.

configContracts başvurusu

Plugin bildirimine ait olup genel çekirdek yardımcılarının Plugin çalışma zamanını içe aktarmadan ihtiyaç duyduğu yapılandırma davranışları için configContracts kullanın: tehlikeli bayrak algılama, SecretRef taşıma hedefleri ve eski yapılandırma yolu daraltma.

{  "configContracts": {    "compatibilityMigrationPaths": ["legacyProvider"],    "compatibilityRuntimePaths": ["legacyProvider.webhook"],    "dangerousFlags": [      {        "path": "accounts.*.allowUnverifiedSenders",        "equals": true      }    ],    "secretInputs": {      "bundledDefaultEnabled": false,      "paths": [        {          "path": "apiKey",          "expected": "string"        }      ]    }  }}

Her dangerousFlags girdisi şunları destekler:

secretInputs şunları destekler:

mediaUnderstandingProviderMetadata referansı

Bir medya anlama sağlayıcısının varsayılan modelleri, otomatik kimlik doğrulama yedek önceliği veya genel çekirdek yardımcılarının çalışma zamanı yüklenmeden önce gereksinim duyduğu yerel belge desteği varsa mediaUnderstandingProviderMetadata kullanın. Anahtarlar ayrıca contracts.mediaUnderstandingProviders içinde bildirilmelidir.

{  "contracts": {    "mediaUnderstandingProviders": ["example"]  },  "mediaUnderstandingProviderMetadata": {    "example": {      "capabilities": ["image", "audio"],      "defaultModels": {        "image": "example-vision-latest",        "audio": "example-transcribe-latest"      },      "autoPriority": {        "image": 40      },      "nativeDocumentInputs": ["pdf"],      "documentModels": {        "pdf": {          "textExtraction": "example-doc-text-latest",          "image": "example-doc-vision-latest"        }      }    }  }}

Her sağlayıcı girdisi şunları içerebilir:

channelConfigs referansı

Bir kanal Plugin'inin çalışma zamanı yüklenmeden önce düşük maliyetli yapılandırma meta verilerine gereksinimi olduğunda channelConfigs kullanın. Salt okunur kanal kurulum/durum keşfi, kullanılabilir bir kurulum girdisi olmadığında veya setup.requiresRuntime: false kurulum çalışma zamanının gereksiz olduğunu bildirdiğinde, yapılandırılmış harici kanallar için bu meta verileri doğrudan kullanabilir.

channelConfigs, yeni bir üst düzey kullanıcı yapılandırma bölümü değil, Plugin manifest meta verisidir. Kullanıcılar kanal örneklerini yine channels.<channel-id> altında yapılandırır. OpenClaw, Plugin çalışma zamanı kodu yürütülmeden önce yapılandırılmış kanalın hangi Plugin'e ait olduğuna karar vermek için manifest meta verilerini okur.

Bir kanal Plugin'i için configSchema ve channelConfigs farklı yolları tanımlar:

• configSchema, plugins.entries.<plugin-id>.config yolunu doğrular
• channelConfigs.<channel-id>.schema, channels.<channel-id> yolunu doğrular

channels[] bildiren ve paketle gelmeyen Plugin'ler, eşleşen channelConfigs girdilerini de bildirmelidir. Bunlar olmadan OpenClaw yine de Plugin'i yükleyebilir; ancak soğuk yol yapılandırma şeması, kurulum ve Control UI yüzeyleri, Plugin çalışma zamanı yürütülene kadar kanala ait seçeneklerin biçimini bilemez.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled ve nativeSkillsAutoEnabled, kanal çalışma zamanı yüklenmeden önce çalışan komut yapılandırması denetimleri için statik auto varsayılanlarını bildirebilir. Paketle gelen kanallar, paketlerine ait diğer kanal kataloğu meta verilerinin yanında aynı varsayılanları package.json#openclaw.channel.commands aracılığıyla da yayımlayabilir.

{  "channelConfigs": {    "matrix": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "homeserverUrl": { "type": "string" }        }      },      "uiHints": {        "homeserverUrl": {          "label": "Homeserver URL",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "Matrix homeserver connection",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

Her kanal girdisi şunları içerebilir:

Başka bir kanal Plugin'inin yerini alma

Plugin'iniz, başka bir Plugin'in de sağlayabildiği bir kanal kimliği için tercih edilen sahip olduğunda preferOver kullanın. Yaygın durumlar; yeniden adlandırılmış bir Plugin kimliği, paketle gelen bir Plugin'in yerini alan bağımsız bir Plugin veya yapılandırma uyumluluğu için aynı kanal kimliğini koruyan, bakımı sürdürülen bir çatallamadır.

{  "id": "acme-chat",  "channels": ["chat"],  "channelConfigs": {    "chat": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "webhookUrl": { "type": "string" }        }      },      "preferOver": ["chat"]    }  }}

channels.chat yapılandırıldığında OpenClaw hem kanal kimliğini hem de tercih edilen Plugin kimliğini dikkate alır. Daha düşük öncelikli Plugin yalnızca paketle geldiği veya varsayılan olarak etkin olduğu için seçildiyse OpenClaw, kanalın ve araçlarının tek bir Plugin'e ait olması için bu Plugin'i etkin çalışma zamanı yapılandırmasında devre dışı bırakır. Açık kullanıcı seçimi yine önceliklidir: kullanıcı her iki Plugin'i de açıkça etkinleştirirse (plugins.allow veya önemli bir plugins.entries yapılandırması aracılığıyla), OpenClaw istenen Plugin kümesini sessizce değiştirmek yerine bu seçimi korur ve yinelenen kanal/araç tanılamalarını bildirir.

preferOver kapsamını gerçekten aynı kanalı sağlayabilen Plugin kimlikleriyle sınırlı tutun. Bu, genel bir öncelik alanı değildir ve kullanıcı yapılandırma anahtarlarını yeniden adlandırmaz.

modelSupport referansı

OpenClaw'ın Plugin çalışma zamanı yüklenmeden önce gpt-5.6-sol veya claude-sonnet-4.6 gibi kısa model kimliklerinden sağlayıcı Plugin'inizi çıkarsaması gerektiğinde modelSupport kullanın.

{  "modelSupport": {    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],    "modelPatterns": ["^computer-use-preview"]  }}

OpenClaw şu öncelik sırasını uygular:

• açık provider/model referansları, sahip olan providers manifest meta verilerini kullanır
• modelPatterns, modelPrefixes değerlerinden önceliklidir
• paketle gelmeyen bir Plugin ile paketle gelen bir Plugin'in ikisi de eşleşirse paketle gelmeyen Plugin kazanır
• kalan belirsizlik, kullanıcı veya yapılandırma bir sağlayıcı belirtene kadar yok sayılır

Alanlar:

modelPatterns girdileri, iç içe yineleme içeren kalıpları (örneğin (a+)+$) reddeden compileSafeRegex aracılığıyla derlenir. Güvenlik denetiminde başarısız olan kalıplar, sözdizimsel olarak geçersiz düzenli ifadeler gibi sessizce atlanır. Kalıpları basit tutun ve iç içe niceleyicilerden kaçının.

modelCatalog referansı

OpenClaw'ın Plugin çalışma zamanını yüklemeden önce sağlayıcı model meta verilerini bilmesi gerektiğinde modelCatalog kullanın. Bu, sabit katalog satırları, sağlayıcı takma adları, bastırma kuralları ve keşif modu için manifeste ait kaynaktır. Çalışma zamanı yenilemesi yine sağlayıcı çalışma zamanı koduna aittir; ancak manifest, çalışma zamanının ne zaman gerekli olduğunu çekirdeğe bildirir.

{  "providers": ["openai"],  "modelCatalog": {    "providers": {      "openai": {        "baseUrl": "https://api.openai.com/v1",        "api": "openai-responses",        "models": [          {            "id": "gpt-5.4",            "name": "GPT-5.4",            "input": ["text", "image"],            "reasoning": true,            "contextWindow": 256000,            "maxTokens": 128000,            "cost": {              "input": 1.25,              "output": 10,              "cacheRead": 0.125            },            "status": "available",            "tags": ["default"]          }        ]      }    },    "aliases": {      "azure-openai-responses": {        "provider": "openai",        "api": "azure-openai-responses"      }    },    "suppressions": [      {        "provider": "azure-openai-responses",        "model": "gpt-5.3-codex-spark",        "reason": "not available on Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

Üst düzey alanlar:

aliases, model kataloğu planlamasında sağlayıcı sahipliği aramasına katılır. Takma ad hedefleri, aynı pluginin sahip olduğu üst düzey sağlayıcılar olmalıdır. Sağlayıcıya göre filtrelenmiş bir liste bir takma ad kullandığında OpenClaw, sağlayıcı çalışma zamanını yüklemeden sahip olan manifesti okuyabilir ve takma ada ait API/temel URL geçersiz kılmalarını uygulayabilir. Takma adlar, filtrelenmemiş katalog listelerini genişletmez; geniş kapsamlı listeler yalnızca sahip olan standart sağlayıcının satırlarını verir.

suppressions, eski sağlayıcı çalışma zamanı suppressBuiltInModel kancasının yerini alır. Engelleme girdileri yalnızca sağlayıcı plugine ait olduğunda veya sahip olunan bir sağlayıcıyı hedefleyen bir modelCatalog.aliases anahtarı olarak bildirildiğinde dikkate alınır. Model çözümleme sırasında çalışma zamanı engelleme kancaları artık çağrılmaz.

Sağlayıcı alanları:

Model alanları:

Engelleme alanları:

Yalnızca çalışma zamanına ait verileri modelCatalog içine koymayın. static değerini yalnızca manifest satırları, sağlayıcıya göre filtrelenmiş liste ve seçici yüzeylerinin kayıt defteri/çalışma zamanı keşfini atlayabilmesine yetecek kadar eksiksiz olduğunda kullanın. Manifest satırları listelenebilir yararlı başlangıç verileri veya eklemeler olduğunda ancak yenileme/önbellek daha sonra yeni satırlar ekleyebildiğinde refreshable kullanın; yenilenebilir satırlar tek başlarına yetkili değildir. OpenClaw'ın listeyi bilmek için sağlayıcı çalışma zamanını yüklemesi gerektiğinde runtime kullanın.

modelIdNormalization referansı

Sağlayıcı çalışma zamanı yüklenmeden önce gerçekleşmesi gereken, maliyeti düşük ve sağlayıcıya ait model kimliği temizliği için modelIdNormalization kullanın. Böylece kısa model adları, sağlayıcıya özgü eski kimlikler ve vekil önek kuralları gibi takma adlar, çekirdek model seçimi tabloları yerine sahip olan plugin manifestinde tutulur.

{  "providers": ["anthropic", "openrouter"],  "modelIdNormalization": {    "providers": {      "anthropic": {        "aliases": {          "sonnet-4.6": "claude-sonnet-4-6"        }      },      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  }}

Sağlayıcı alanları:

providerEndpoints referansı

Genel istek politikasının sağlayıcı çalışma zamanı yüklenmeden önce bilmesi gereken uç nokta sınıflandırması için providerEndpoints kullanın. Her bir endpointClass değerinin anlamı hâlâ çekirdeğe aittir; ana bilgisayar ve temel URL meta verileri plugin manifestlerine aittir.

Resmî olarak haricileştirilmiş sağlayıcı pluginleri çekirdek dağıtımının dışında bırakılır; bu nedenle manifestleri kurulana kadar görünmez. Uç nokta sınıflandırmasının plugin olmadan da çalışmaya devam etmesi için bunların providerEndpoints verileri scripts/lib/official-external-provider-catalog.json dosyasına da yansıtılmalıdır; bir sözleşme testi bu yansıtmayı zorunlu kılar.

Uç nokta alanları:

providerRequest referansı

Genel istek politikasının sağlayıcı çalışma zamanını yüklemeden ihtiyaç duyduğu düşük maliyetli istek uyumluluğu meta verileri için providerRequest kullanın. Davranışa özgü yük yeniden yazma işlemlerini sağlayıcı çalışma zamanı kancalarında veya paylaşılan sağlayıcı ailesi yardımcılarında tutun.

{  "providerRequest": {    "providers": {      "vllm": {        "family": "vllm",        "openAICompletions": {          "supportsStreamingUsage": true        }      }    }  }}

Sağlayıcı alanları:

secretProviderIntegrations referansı

Bir plugin yeniden kullanılabilir bir SecretRef çalıştırma sağlayıcısı ön ayarı yayımlayabildiğinde secretProviderIntegrations kullanın. OpenClaw bu meta verileri plugin çalışma zamanı yüklenmeden önce okur, plugin sahipliğini secrets.providers.<alias>.pluginIntegration içinde saklar ve gerçek gizli değer çözümlemesini SecretRef çalışma zamanına bırakır. Ön ayarlar yalnızca paketle gelen pluginler ve git ile ClawHub kurulumları gibi yönetilen plugin kurulum köklerinden keşfedilen kurulu pluginler için sunulur.

{  "secretProviderIntegrations": {    "secret-store": {      "providerAlias": "team-secrets",      "displayName": "Team secrets",      "source": "exec",      "command": "${node}",      "args": ["./bin/resolve-secrets.mjs"]    }  }}

Eşleme anahtarı entegrasyon kimliğidir. providerAlias belirtilmezse OpenClaw, entegrasyon kimliğini SecretRef sağlayıcı diğer adı olarak kullanır. Sağlayıcı diğer adları normal SecretRef sağlayıcı diğer adı kalıbıyla eşleşmelidir; örneğin team-secrets veya onepassword-work.

Bir operatör ön ayarı seçtiğinde OpenClaw şuna benzer bir sağlayıcı referansı yazar:

{  "secrets": {    "providers": {      "team-secrets": {        "source": "exec",        "pluginIntegration": {          "pluginId": "acme-secrets",          "integrationId": "secret-store"        }      }    }  }}

Başlatma/yeniden yükleme sırasında OpenClaw, güncel plugin manifesti meta verilerini yükleyerek, sahibi olan pluginin kurulu ve etkin olduğunu denetleyerek ve çalıştırma komutunu manifestten oluşturarak bu sağlayıcıyı çözümler. Pluginin devre dışı bırakılması veya kaldırılması, etkin SecretRef'ler için sağlayıcıyı geçersiz kılar. Bağımsız çalıştırma yapılandırması isteyen operatörler doğrudan elle command/args sağlayıcıları yazmaya devam edebilir.

Şu anda yalnızca source: "exec" ön ayarları desteklenmektedir. command, ${node} olmalı ve args[0], plugin köküne göreli bir ./ çözümleyici betiği olmalıdır. OpenClaw bunu başlatma/yeniden yükleme sırasında güncel Node yürütülebilir dosyasına ve plugin içindeki betiğin mutlak yoluna dönüştürür. --require, --import, --loader, --env-file, --eval ve --print gibi Node seçenekleri manifest ön ayarı sözleşmesinin parçası değildir. Node dışı komutlara ihtiyaç duyan operatörler bağımsız elle çalıştırma sağlayıcılarını doğrudan yapılandırabilir.

OpenClaw, manifest ön ayarları için trustedDirs değerini plugin kökünden ve ${node} ön ayarlarında güncel Node yürütülebilir dosyasının dizininden türetir. Manifestte tanımlanan trustedDirs yok sayılır. timeoutMs, noOutputTimeoutMs, maxOutputBytes, jsonOnly, env, passEnv ve allowInsecurePath gibi diğer çalıştırma sağlayıcısı seçenekleri normal SecretRef çalıştırma sağlayıcısı yapılandırmasına aktarılır.

modelPricing referansı

Bir sağlayıcının çalışma zamanı yüklenmeden önce kontrol düzlemi fiyatlandırma davranışını belirlemesi gerektiğinde modelPricing kullanın. Gateway fiyatlandırma önbelleği, sağlayıcı çalışma zamanı kodunu içe aktarmadan bu meta verileri okur.

{  "providers": ["ollama", "openrouter"],  "modelPricing": {    "providers": {      "ollama": {        "external": false      },      "openrouter": {        "openRouter": {          "passthroughProviderModel": true        },        "liteLLM": false      }    }  }}

Sağlayıcı alanları:

Kaynak alanları:

OpenClaw Sağlayıcı Dizini

OpenClaw Sağlayıcı Dizini, pluginleri henüz kurulmamış olabilecek sağlayıcılar için OpenClaw'a ait önizleme meta verileridir. Bir plugin manifestinin parçası değildir. Plugin manifestleri, kurulu pluginler için yetkili kaynak olmaya devam eder. Sağlayıcı Dizini, gelecekteki kurulabilir sağlayıcı ve kurulum öncesi model seçici yüzeylerinin bir sağlayıcı plugini kurulu olmadığında kullanacağı dahili geri dönüş sözleşmesidir.

Katalog yetki sırası:

1. Kullanıcı yapılandırması.
2. Kurulu plugin manifestindeki modelCatalog.
3. Açık yenileme sonucunda oluşturulan model kataloğu önbelleği.
4. OpenClaw Sağlayıcı Dizini önizleme satırları.

Sağlayıcı Dizini gizli değerler, etkinleştirilmiş durum, çalışma zamanı kancaları veya canlı hesaba özgü model verileri içermemelidir. Önizleme katalogları, plugin manifestleriyle aynı modelCatalog sağlayıcı satırı biçimini kullanır; ancak api, baseUrl, fiyatlandırma veya uyumluluk bayrakları gibi çalışma zamanı bağdaştırıcısı alanları kasıtlı olarak kurulu plugin manifestiyle uyumlu tutulmadıkça yalnızca kararlı görüntüleme meta verileriyle sınırlı kalmalıdır. Canlı /models keşfine sahip sağlayıcılar, normal listeleme veya ilk katılım sırasında sağlayıcı API'lerini çağırmak yerine yenilenmiş satırları açık model kataloğu önbelleği yolu üzerinden yazmalıdır.

Sağlayıcı Dizini girdileri, plugini çekirdekten taşınmış veya başka bir nedenle henüz kurulmamış sağlayıcılar için kurulabilir plugin meta verilerini de taşıyabilir. Bu meta veriler kanal kataloğu kalıbını yansıtır: paket adı, npm kurulum belirtimi, beklenen bütünlük ve düşük maliyetli kimlik doğrulama seçeneği etiketleri, kurulabilir bir ayarlama seçeneğini göstermek için yeterlidir. Plugin kurulduktan sonra kendi manifesti öncelik kazanır ve o sağlayıcının Sağlayıcı Dizini girdisi yok sayılır.

openclaw doctor --fix, eski üst düzey manifest yetenek anahtarlarının küçük ve kapalı bir kümesini contracts.* içine taşır: speechProviders, mediaUnderstandingProviders, imageGenerationProviders ve tools. Bunların hiçbiri (veya başka herhangi bir yetenek listesi) artık üst düzey manifest alanları olarak okunmaz; normal manifest yükleme bunları yalnızca contracts altında tanır.

Manifest ile package.json karşılaştırması

İki dosya farklı amaçlara hizmet eder:

Bir meta veri parçasının nereye ait olduğundan emin değilseniz şu kuralı kullanın:

• OpenClaw'ın plugin kodunu yüklemeden önce bunu bilmesi gerekiyorsa openclaw.plugin.json içine koyun
• paketleme, giriş dosyaları veya npm kurulum davranışıyla ilgiliyse package.json içine koyun

Keşfi etkileyen package.json alanları

Bazı çalışma zamanı öncesi plugin meta verileri kasıtlı olarak openclaw.plugin.json yerine package.json içindeki openclaw bloğunda bulunur. openclaw.bundle ve openclaw.bundle.json, OpenClaw plugin sözleşmeleri değildir; yerel pluginler openclaw.plugin.json dosyasını ve aşağıdaki desteklenen package.json#openclaw alanlarını kullanmalıdır.

Önemli örnekler:

Manifest meta verileri, çalışma zamanı yüklenmeden önce ilk katılımda hangi sağlayıcı/kanal/kurulum seçeneklerinin görüneceğini belirler. package.json#openclaw.install, kullanıcı bu seçeneklerden birini belirlediğinde ilk katılıma ilgili plugini nasıl getireceğini veya etkinleştireceğini bildirir. Yükleme ipuçlarını openclaw.plugin.json içine taşımayın.

openclaw.install.minHostVersion, birlikte sunulmayan Plugin kaynakları için yükleme ve manifest kayıt defteri yüklemesi sırasında uygulanır. Geçersiz değerler reddedilir; daha yeni ancak geçerli değerler, eski ana makinelerde harici pluginlerin atlanmasına neden olur. Birlikte sunulan kaynak pluginlerin ana makine kaynak koduyla aynı sürüme sahip olduğu varsayılır.

openclaw.install.requiredPlatformPackages, gerekli yerel ikili dosyaları isteğe bağlı, platforma özgü takma adlar üzerinden sunan npm paketleri içindir. Desteklenen her platform takma adı için yalın npm paket adını listeleyin. npm yüklemesi sırasında OpenClaw, yalnızca kilit dosyası kısıtlamaları mevcut ana makineyle eşleşen bildirilmiş takma adı doğrular. npm başarı bildirdiği hâlde bu takma adı dahil etmezse OpenClaw yeni bir önbellekle bir kez daha dener ve takma ad hâlâ yoksa yüklemeyi geri alır.

openclaw.compat.pluginApi, birlikte sunulmayan Plugin kaynaklarının paket yüklemesi sırasında uygulanır. Bunu, paketin temel alınarak derlendiği OpenClaw Plugin SDK/çalışma zamanı API alt sınırı için kullanın. Bir Plugin paketi daha yeni bir API gerektirirken diğer akışlar için daha düşük bir yükleme ipucunu koruduğunda, bu değer minHostVersion değerinden daha katı olabilir. Resmî OpenClaw sürüm eşitlemesi, mevcut resmî Plugin API alt sınırlarını varsayılan olarak OpenClaw sürümüne yükseltir; ancak yalnızca Plugine yönelik sürümler, paket eski ana makineleri bilinçli olarak destekliyorsa daha düşük bir alt sınırı koruyabilir. Uyumluluk sözleşmesi olarak yalnızca paket sürümünü kullanmayın. peerDependencies.openclaw, npm paket meta verisi olarak kalır; OpenClaw, yükleme uyumluluğu kararları için openclaw.compat.pluginApi sözleşmesini kullanır.

İsteğe bağlı resmî yükleme meta verileri, Plugin ClawHub'da yayımlanmışsa clawhubSpec kullanmalıdır; ilk katılım bunu tercih edilen uzak kaynak olarak değerlendirir ve yükleme sonrasında ClawHub yapıt bilgilerini kaydeder. npmSpec, henüz ClawHub'a taşınmamış paketler için uyumluluk yedeği olarak kalır.

Tam npm sürümü sabitlemesi zaten npmSpec içinde bulunur; örneğin "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Resmî harici katalog girdileri, tam belirtimleri expectedIntegrity ile eşleştirmelidir; böylece getirilen npm yapıtı artık sabitlenmiş sürümle eşleşmiyorsa güncelleme akışları güvenli biçimde başarısız olur. Etkileşimli ilk katılım, uyumluluk için yalın paket adları ve dağıtım etiketleri dahil olmak üzere güvenilir kayıt defteri npm belirtimlerini sunmaya devam eder. Katalog tanılamaları; tam, değişken, bütünlük sabitlenmiş, bütünlüğü eksik, paket adı uyuşmazlığı bulunan ve geçersiz varsayılan seçim kaynaklarını birbirinden ayırabilir. Ayrıca expectedIntegrity mevcut olduğu hâlde sabitleyebileceği geçerli bir npm kaynağı yoksa uyarı verir. expectedIntegrity mevcut olduğunda yükleme/güncelleme akışları bunu zorunlu kılar; belirtilmediğinde kayıt defteri çözümlemesi bir bütünlük sabitlemesi olmadan kaydedilir.

Kanal pluginleri; durum, kanal listesi veya SecretRef taramalarının tam çalışma zamanını yüklemeden yapılandırılmış hesapları tanımlaması gerektiğinde openclaw.setupEntry sağlamalıdır. Kurulum girdisi, kanal meta verilerinin yanı sıra kurulum açısından güvenli yapılandırma, durum ve gizli bilgi bağdaştırıcılarını sunmalıdır; ağ istemcilerini, Gateway dinleyicilerini ve aktarım çalışma zamanlarını ana uzantı giriş noktasında tutun.

Çalışma zamanı giriş noktası alanları, kaynak giriş noktası alanlarına yönelik paket sınırı denetimlerini geçersiz kılmaz. Örneğin openclaw.runtimeExtensions, paket dışına çıkan bir openclaw.extensions yolunu yüklenebilir hâle getiremez.

openclaw.install.allowInvalidConfigRecovery bilinçli olarak dar kapsamlıdır. Keyfî bozuk yapılandırmaları yüklenebilir hâle getirmez. Şu anda yalnızca eksik bir birlikte sunulan Plugin yolu veya aynı birlikte sunulan Plugin için eskimiş bir channels.<id> girdisi gibi, birlikte sunulan Pluginlerin belirli eskimiş yükseltme hatalarından yükleme akışlarının kurtulmasına izin verir. İlgisiz yapılandırma hataları yüklemeyi engellemeye devam eder ve operatörleri openclaw doctor --fix komutuna yönlendirir.

openclaw.channel.persistedAuthState, küçük bir denetleyici modülü için paket meta verisidir:

{  "openclaw": {    "channel": {      "id": "whatsapp",      "persistedAuthState": {        "specifier": "./auth-presence",        "exportName": "hasAnyWhatsAppAuth"      }    }  }}

Kurulum, doctor, durum veya salt okunur mevcudiyet akışları tam kanal Plugini yüklenmeden önce düşük maliyetli bir evet/hayır kimlik doğrulama yoklamasına ihtiyaç duyduğunda bunu kullanın. Kalıcı kimlik doğrulama durumu, yapılandırılmış kanal durumu değildir: Pluginleri otomatik olarak etkinleştirmek, çalışma zamanı bağımlılıklarını onarmak veya bir kanal çalışma zamanının yüklenip yüklenmeyeceğine karar vermek için bu meta verileri kullanmayın. Hedef dışa aktarım, yalnızca kalıcı durumu okuyan küçük bir işlev olmalıdır; bunu tam kanal çalışma zamanı barrel dosyası üzerinden yönlendirmeyin.

openclaw.channel.configuredState, düşük maliyetli ve yalnızca ortam değişkenlerine dayalı yapılandırılmışlık denetimleri için aynı yapıyı izler:

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "specifier": "./configured-state",        "exportName": "hasTelegramConfiguredState"      }    }  }}

Bir kanal, yapılandırılmış durumu ortam değişkenlerinden veya diğer küçük, çalışma zamanı dışı girdilerden belirleyebiliyorsa bunu kullanın. Denetim tam yapılandırma çözümlemesini veya gerçek kanal çalışma zamanını gerektiriyorsa bu mantığı Pluginin config.hasConfiguredState kancasında tutun.

Keşif önceliği (yinelenen Plugin kimlikleri)

OpenClaw pluginleri şu sırayla denetlenen üç kökten keşfeder: OpenClaw ile birlikte sunulan pluginler, genel yükleme kökü (~/.openclaw/extensions) ve mevcut çalışma alanı kökü (<workspace>/.openclaw/extensions); bunlara ek olarak açıkça belirtilen plugins.load.paths girdileri de denetlenir.

İki keşif aynı id değerini paylaşıyorsa yalnızca en yüksek öncelikli manifest tutulur; daha düşük öncelikli yinelenenler yan yana yüklenmek yerine elenir. En yüksekten en düşüğe öncelik sırası:

1. Yapılandırmayla seçilen — plugins.entries.<id> içinde açıkça sabitlenmiş bir yol
2. İzlenen bir yükleme kaydıyla eşleşen genel yükleme — kimlik birlikte sunulan bir Plugine de ait olsa bile, openclaw plugin install/openclaw plugin update aracılığıyla yüklenmiş ve OpenClaw'ın yükleme izlemesinin aynı kimlik için tanıdığı bir Plugin
3. Birlikte sunulan — OpenClaw ile birlikte sunulan pluginler
4. Çalışma alanı — mevcut çalışma alanına göre keşfedilen pluginler
5. Keşfedilen diğer tüm adaylar

Sonuçlar:

• Birlikte sunulan bir Pluginin çalışma alanında veya genel kökte izlenmeden duran çatallanmış ya da eskimiş bir kopyası, birlikte sunulan derlemeyi gölgelemez.
• Birlikte sunulan bir Plugini geçersiz kılmak için ya ilgili kimlik adına openclaw plugin install komutunu çalıştırarak izlenen genel yüklemenin birlikte sunulan kopyadan daha yüksek öncelik kazanmasını sağlayın ya da plugins.entries.<id> üzerinden belirli bir yolu sabitleyerek yapılandırmayla seçilen öncelik sayesinde kazanmasını sağlayın.
• Yinelenenlerin elenmesi günlüğe kaydedilir; böylece Doctor ve başlangıç tanılamaları elenen kopyayı gösterebilir.
• Yapılandırmayla seçilen yinelenen geçersiz kılmalar, tanılamalarda açık geçersiz kılmalar olarak ifade edilir; ancak eskimiş çatalların ve kazara oluşan gölgelemelerin görünür kalması için yine de uyarı verilir.

JSON Schema gereksinimleri

• Her plugin bir JSON Schema ile birlikte sunulmalıdır; hiçbir yapılandırma kabul etmese bile.
• Boş bir şema kabul edilebilir (örneğin, { "type": "object", "additionalProperties": false }).
• Şemalar çalışma zamanında değil, yapılandırma okunurken/yazılırken doğrulanır.
• Paketle birlikte gelen bir plugin'i yeni yapılandırma anahtarlarıyla genişletirken veya çatallarken, aynı anda ilgili plugin'in openclaw.plugin.json dosyasındaki configSchema alanını da güncelleyin. Paketle birlikte gelen plugin şemaları katıdır; bu nedenle configSchema.properties alanına myNewKey eklemeden kullanıcı yapılandırmasına plugins.entries.<id>.config.myNewKey eklemek, plugin çalışma zamanı yüklenmeden önce reddedilir.

Örnek şema genişletmesi:

{  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "myNewKey": {        "type": "string"      }    }  }}

Doğrulama davranışı

• Bilinmeyen channels.* anahtarları, kanal kimliği bir plugin bildirimi tarafından tanımlanmadığı sürece hatadır. Aynı kimlik plugins.allow, plugins.entries veya plugins.installs içinde de yer alıyorsa (başvurulan ancak şu anda keşfedilemeyen bir plugin), OpenClaw bunu bunun yerine uyarı düzeyine indirir.
• Bilinmeyen plugin kimliklerine başvuran plugins.entries.<id>, plugins.allow ve plugins.deny girdileri hata değil, uyarıdır ("eski yapılandırma girdisi yok sayıldı"); böylece yükseltmeler ve kaldırılan/yeniden adlandırılan plugin'ler Gateway'in başlatılmasını engellemez.
• Bilinmeyen bir plugin kimliğine başvuran plugins.slots.memory bir hatadır; ancak bilinen resmî harici memory-lancedb plugin'i için bunun yerine uyarı verilir.
• Bir plugin yüklenmiş ancak bildirimi veya şeması bozuk ya da eksikse doğrulama başarısız olur ve Doctor plugin hatasını bildirir.
• Plugin yapılandırması mevcut ancak plugin devre dışıysa, yapılandırma korunur ve Doctor ile günlüklerde bir uyarı gösterilir.

Eksiksiz plugins.* şeması için Yapılandırma başvurusu bölümüne bakın.

Notlar

• Bildirim, yerel dosya sistemi yüklemeleri dâhil olmak üzere yerel OpenClaw plugin'leri için zorunludur. Çalışma zamanı plugin modülünü yine ayrı olarak yükler; bildirim yalnızca keşif ve doğrulama içindir.
• Yerel bildirimler JSON5 ile ayrıştırılır; bu nedenle nihai değer bir nesne olduğu sürece yorumlar, sondaki virgüller ve tırnaksız anahtarlar kabul edilir.
• Bildirim yükleyicisi yalnızca belgelenmiş bildirim alanlarını okur. Özel üst düzey anahtarlardan kaçının.
• Bir plugin bunlara ihtiyaç duymadığında channels, providers, cliBackends ve skills alanlarının tümü atlanabilir.
• providerCatalogEntry hafif kalmalı ve kapsamlı çalışma zamanı kodunu içe aktarmamalıdır; bunu istek zamanında yürütme için değil, statik sağlayıcı kataloğu meta verileri veya dar kapsamlı keşif tanımlayıcıları için kullanın.
• Özel plugin türleri plugins.slots.* aracılığıyla seçilir: plugins.slots.memory üzerinden kind: "memory" (varsayılan memory-core), plugins.slots.contextEngine üzerinden kind: "context-engine" (varsayılan legacy).
• Özel plugin türünü bu bildirimde tanımlayın. Çalışma zamanı girişindeki OpenClawPluginDefinition.kind kullanımdan kaldırılmıştır ve yalnızca eski plugin'ler için uyumluluk geri dönüşü olarak kalmıştır.
• Ortam değişkeni meta verileri (setup.providers[].envVars, kullanımdan kaldırılmış providerAuthEnvVars ve channelEnvVars) yalnızca bildirimseldir. Durum, denetim, cron teslimatı doğrulaması ve diğer salt okunur yüzeyler, bir ortam değişkenini yapılandırılmış olarak kabul etmeden önce plugin güvenini ve etkinleştirme politikasını uygulamaya devam eder.
• Sağlayıcı kodu gerektiren çalışma zamanı sihirbazı meta verileri için Sağlayıcı çalışma zamanı kancaları bölümüne bakın.
• Plugin'iniz yerel modüllere bağımlıysa derleme adımlarını ve paket yöneticisi izin listesi gereksinimlerini belgeleyin (örneğin, pnpm allow-build-scripts + pnpm rebuild <package>).

İlgili