Plugin manifestosu

Bu sayfa yalnızca yerel OpenClaw Plugin manifesti içindir.

Uyumlu paket düzenleri için bkz. Plugin paketleri.

Uyumlu paket biçimleri farklı manifest dosyaları kullanır:

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

OpenClaw bu paket düzenlerini de otomatik algılar, ancak bunlar burada açıklanan openclaw.plugin.json şemasına göre doğrulanmaz.

Uyumlu paketler için OpenClaw şu anda düzen OpenClaw çalışma zamanı beklentileriyle eşleştiğinde paket meta verilerini ve bildirilen beceri köklerini, Claude komut köklerini, Claude paketi settings.json varsayılanlarını, Claude paketi LSP varsayılanlarını ve desteklenen hook paketlerini okur.

Her yerel OpenClaw Plugin, Plugin kökünde bir openclaw.plugin.json dosyasıyla gelmelidir. OpenClaw bu manifesti, Plugin kodunu çalıştırmadan yapılandırmayı doğrulamak için kullanır. Eksik veya geçersiz manifestler Plugin hataları olarak ele alınır ve yapılandırma doğrulamasını engeller.

Tam Plugin sistemi kılavuzuna bakın: Plugins. Yerel yetenek modeli ve güncel dış uyumluluk kılavuzu için: Yetenek modeli.

Bu dosya ne yapar

openclaw.plugin.json, OpenClaw'ın Plugin kodunuzu yüklemeden önce okuduğu meta verilerdir. Aşağıdaki 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 UI 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ısaltılmış model ailesi sahipliği
• statik yetenek sahipliği anlık görüntüleri (contracts)
• paylaşılan openclaw qa ana makinesinin inceleyebileceği QA çalıştırıcısı meta verileri
• katalog ve doğrulama yüzeylerine birleştirilen kanala özgü yapılandırma meta verileri

Şunlar için kullanmayın: çalışma zamanı davranışını kaydetme, kod giriş noktalarını bildirme veya npm kurulum meta verileri. Bunlar Plugin kodunuza ve package.json dosyanıza aittir.

Minimal örnek

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

Zengin ö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"],  "providerAuthEnvVars": {    "openrouter": ["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

Üretim sağlayıcısı metadata başvurusu

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

Bu alanları yalnızca ucuz, bildirime dayalı olgular için kullanın. Taşıma, istek dönüşümleri, token yenileme, kimlik bilgisi doğrulama 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 metadata girdisi şunları destekler:

Her configSignals girdisi şunları destekler:

Her mode koruması şunları destekler:

Her authSignals girdisi şunları destekler:

Her providerBaseUrl koruması şunları destekler:

Araç metadata başvurusu

toolMetadata, araç adına göre anahtarlanmış olarak üretim sağlayıcısı metadata’sı ile aynı configSignals ve authSignals şekillerini 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 ucuz kullanılabilirlik kanıtı bildirir.

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

Bir araçta toolMetadata yoksa OpenClaw mevcut davranışı korur ve araç sözleşmesi ilkeyle eşleştiğinde sahibi olan Plugin’i yükler. Fabrikası kimlik doğrulama/yapılandırmaya bağlı olan sıcak yol araçları için Plugin yazarları, çekirdeğin sormak amacıyla çalışma zamanını içe aktarmasını sağlamak yerine toolMetadata bildirmelidir.

providerAuthChoices başvurusu

Her providerAuthChoices girdisi bir onboarding veya kimlik doğrulama seçimini açıklar. 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çimlerini, tanımlayıcıdan türetilmiş kurulum seçimlerini ve kurulum kataloğu metadata’sını kullanır.

commandAliases başvurusu

commandAliases öğesini, bir Plugin kullanıcıların yanlışlıkla plugins.allow içine koyabileceği veya kök CLI komutu olarak çalıştırmayı deneyebileceği bir çalışma zamanı komut adına sahip olduğunda kullanın. OpenClaw bu üst veriyi, Plugin çalışma zamanı kodunu içe aktarmadan tanılama için kullanır.

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

activation başvurusu

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

Bu blok bir planlayıcı üst verisidir, yaşam döngüsü API'si değildir. Çalışma zamanı davranışı kaydetmez, register(...) yerine geçmez ve Plugin kodunun zaten çalıştırılmış olduğunu vaat etmez. Etkinleştirme planlayıcısı, mevcut manifest sahiplik üst verilerine, örneğin providers, channels, commandAliases, setup.providers, contracts.tools ve hook'lara geri dönmeden önce aday Plugin'leri daraltmak için bu alanları kullanır.

Sahipliği zaten açıklayan en dar üst veriyi tercih edin. İlişkiyi bu alanlar ifade ediyorsa providers, channels, commandAliases, setup 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, codex-cli veya google-gemini-cli gibi CLI çalışma zamanı alias'ları için üst düzey cliBackends kullanın; activation.onAgentHarnesses yalnızca zaten bir sahiplik alanı bulunmayan gömülü ajan harness kimlikleri içindir.

Bu blok yalnızca üst veridir. Çalışma zamanı davranışı kaydetmez ve register(...), setupEntry ya da diğer çalışma zamanı/Plugin giriş noktalarının yerine geçmez. Geçerli tüketiciler bunu daha geniş Plugin yüklemesinden önce daraltıcı bir ipucu olarak kullanır; bu nedenle startup dışı etkinleştirme üst verisinin eksik olması genellikle yalnızca performansa mal olur; manifest sahiplik fallback'leri hâlâ mevcutken doğruluğu değiştirmemelidir.

Her Plugin activation.onStartup değerini bilinçli olarak ayarlamalıdır. Yalnızca Plugin'in Gateway startup sırasında çalışması gerekiyorsa true olarak ayarlayın. Plugin startup sırasında etkisizse ve yalnızca daha dar tetikleyicilerden yüklenmesi gerekiyorsa false olarak ayarlayın. onStartup öğesinin atlanması artık Plugin'i startup sırasında örtük olarak yüklemez; startup, kanal, yapılandırma, ajan harness, bellek veya diğer daha dar etkinleştirme tetikleyicileri için açık etkinleştirme üst verisi kullanın.

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

Geçerli canlı tüketiciler:

• Gateway startup planlaması, açık startup içe aktarması için activation.onStartup kullanır
• komutla tetiklenen CLI planlaması, eski commandAliases[].cliCommand veya commandAliases[].name değerlerine geri döner
• ajan çalışma zamanı startup planlaması, gömülü harness'ler için activation.onAgentHarnesses ve CLI çalışma zamanı alias'ları için üst düzey cliBackends[] kullanır
• kanalla tetiklenen setup/kanal planlaması, açık kanal etkinleştirme üst verisi eksik olduğunda eski channels[] sahipliğine geri döner
• startup Plugin planlaması, paketli 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 setup/çalışma zamanı planlaması, açık sağlayıcı etkinleştirme üst verisi 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ı manifest sahiplik fallback'inden ayırt edebilir. Örneğin, activation-command-hint, activation.onCommands 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 testleri içindir; Plugin yazarları sahipliği en iyi açıklayan üst veriyi bildirmeye devam etmelidir.

qaRunners başvurusu

Bir Plugin paylaşılan openclaw qa kökü altında bir veya daha fazla taşıma çalıştırıcısı sağladığında qaRunners kullanın. Bu üst veriyi düşük maliyetli ve statik tutun; gerçek CLI kaydının sahibi hâlâ qaRunnerCliRegistrations dışa aktaran hafif bir runtime-api.ts yüzeyi üzerinden Plugin çalışma zamanıdır.

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

setup başvurusu

Setup ve onboarding yüzeyleri çalışma zamanı yüklenmeden önce düşük maliyetli, Plugin'in sahibi olduğu üst veriye 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çerli kalır ve CLI çıkarım backend'lerini açıklamaya devam eder. setup.cliBackends, yalnızca üst veri olarak kalması gereken denetim düzlemi/setup akışları için setup'a özgü tanımlayıcı yüzeyidir.

Mevcut olduğunda setup.providers ve setup.cliBackends, setup keşfi için tercih edilen tanımlayıcı öncelikli arama yüzeyidir. Tanımlayıcı yalnızca aday Plugin'i daraltıyorsa ve setup hâlâ daha zengin setup zamanı çalışma zamanı hook'larına ihtiyaç duyuyorsa requiresRuntime: true ayarlayın ve fallback yürütme yolu olarak setup-api öğesini yerinde tutun.

OpenClaw ayrıca genel sağlayıcı kimlik doğrulaması ve env-var aramalarına setup.providers[].envVars öğesini dahil eder. providerAuthEnvVars, kullanımdan kaldırma penceresi sırasında uyumluluk adaptörü üzerinden desteklenmeye devam eder, ancak bunu hâlâ kullanan paketli olmayan Plugin'ler bir manifest tanılaması alır. Yeni Plugin'ler setup/durum env üst verisini setup.providers[].envVars üzerine koymalıdır.

OpenClaw, setup girişi bulunmadığında veya setup.requiresRuntime: false setup çalışma zamanının gereksiz olduğunu bildirdiğinde setup.providers[].authMethods üzerinden basit setup seçenekleri de türetebilir. Açık providerAuthChoices girdileri özel etiketler, CLI flag'leri, onboarding kapsamı ve asistan üst verisi için tercih edilmeye devam eder.

requiresRuntime: false değerini yalnızca bu tanımlayıcılar setup yüzeyi için yeterliyse ayarlayın. OpenClaw açık false değerini yalnızca tanımlayıcı sözleşmesi olarak ele alır ve setup araması için setup-api veya openclaw.setupEntry çalıştırmaz. Yalnızca tanımlayıcı kullanan bir Plugin hâlâ bu setup çalışma zamanı girişlerinden birini gönderiyorsa OpenClaw eklemeli bir tanılama raporlar ve onu yok saymaya devam eder. requiresRuntime öğesinin atlanması eski fallback davranışını korur, böylece flag olmadan tanımlayıcı ekleyen mevcut Plugin'ler bozulmaz.

Setup araması Plugin'in sahibi olduğu setup-api kodunu çalıştırabildiğinden, normalize edilmiş setup.providers[].id ve setup.cliBackends[] değerleri keşfedilen Plugin'ler genelinde benzersiz kalmalıdır. Belirsiz sahiplik, keşif sırasından bir kazanan seçmek yerine kapalı olarak başarısız olur.

Setup çalışma zamanı çalıştığında, setup kayıt defteri tanılamaları setup-api manifest tanımlayıcılarının bildirmediği bir sağlayıcı veya CLI backend kaydederse ya da bir tanımlayıcının eşleşen çalışma zamanı kaydı yoksa tanımlayıcı sapması raporlar. Bu tanılamalar eklemelidir ve eski Plugin'leri reddetmez.

setup.providers başvurusu

authEvidence, çalışma zamanı kodu yüklenmeden doğrulanabilen, sağlayıcıya ait yerel kimlik bilgisi işaretçileri içindir. Bu kontroller ucuz ve yerel kalmalıdır: ağ çağrısı yok, anahtar zinciri veya gizli dizi yöneticisi okuması yok, kabuk komutu yok ve sağlayıcı API yoklaması yok.

Desteklenen kanıt girdileri:

setup alanları

uiHints başvurusu

uiHints, yapılandırma alan adlarından küçük işleme ipuçlarına uzanan bir haritadır.

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

Her alan ipucu şunları içerebilir:

contracts başvurusu

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": ["pi", "codex"],    "externalAuthProviders": ["acme-ai"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai", "openai-codex"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "migrationProviders": ["hermes"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

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

contracts.embeddedExtensionFactories, paketli ve yalnızca Codex app-server için olan extension factory'ler için tutulur. Paketli araç sonucu dönüşümleri bunun yerine contracts.agentToolResultMiddleware bildirmeli ve api.registerAgentToolResultMiddleware(...) ile kaydolmalıdır. Dış plugin'ler araç sonucu middleware'i kaydedemez, çünkü bu seam, model görmeden önce yüksek güvenli araç çıktısını yeniden yazabilir.

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

resolveExternalAuthProfiles uygulayan sağlayıcı plugin'leri contracts.externalAuthProviders bildirmelidir. Bildirimi olmayan plugin'ler hâlâ kullanımdan kaldırılmış bir uyumluluk fallback'i üzerinden çalışır, ancak bu fallback daha yavaştır ve geçiş penceresinden sonra kaldırılacaktır.

Paketli bellek gömme sağlayıcıları, local gibi yerleşik adapter'lar dahil olmak üzere sundukları her adapter kimliği için contracts.memoryEmbeddingProviders bildirmelidir. Bağımsız CLI yolları, sağlayıcılar tam Gateway çalışma zamanı tarafından kaydedilmeden önce yalnızca sahip plugin'i yüklemek için bu manifest sözleşmesini kullanır.

mediaUnderstandingProviderMetadata başvurusu

Bir medya anlama sağlayıcısının varsayılan modelleri, otomatik kimlik doğrulama fallback önceliği veya genel çekirdek yardımcıların çalışma zamanı yüklenmeden önce ihtiyaç duyduğu yerel belge desteği olduğunda 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"]    }  }}

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

channelConfigs başvurusu

Bir kanal plugin'inin çalışma zamanı yüklenmeden önce ucuz yapılandırma meta verilerine ihtiyaç duyduğu durumlarda channelConfigs kullanın. Salt okunur kanal kurulum/durum keşfi, kurulum girdisi yoksa veya setup.requiresRuntime: false kurulum çalışma zamanının gereksiz olduğunu bildiriyorsa, yapılandırılmış dış kanallar için bu meta verileri doğrudan kullanabilir.

channelConfigs, plugin manifest meta verisidir; yeni bir üst düzey kullanıcı yapılandırması bölümü değildir. Kullanıcılar kanal örneklerini hâlâ channels.<channel-id> altında yapılandırır. OpenClaw, plugin çalışma zamanı kodu yürütülmeden önce yapılandırılmış kanala hangi plugin'in sahip olduğunu belirlemek 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 değerini doğrular
• channelConfigs.<channel-id>.schema, channels.<channel-id> değerini doğrular

channels[] bildiren paketli olmayan plugin'ler, eşleşen channelConfigs girdilerini de bildirmelidir. Bunlar olmadan OpenClaw plugin'i yine de 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 kanalın sahip olduğu seçenek şeklini bilemez.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled ve nativeSkillsAutoEnabled, kanal çalışma zamanı yüklenmeden önce çalışan komut yapılandırması kontrolleri için statik auto varsayılanları bildirebilir. Paketli kanallar, diğer pakete ait kanal katalog meta verilerinin yanında aynı varsayılanları package.json#openclaw.channel.commands üzerinden de 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'ini değiştirme

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, paketlenmiş bir Plugin'in yerine geçen bağımsız bir Plugin veya yapılandırma uyumluluğu için aynı kanal kimliğini koruyan bakımı yapılan bir fork'tur.

{  "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 paketlenmiş olduğu veya varsayılan olarak etkinleştirildiği için seçildiyse, OpenClaw etkili çalışma zamanı yapılandırmasında onu devre dışı bırakır; böylece kanalın ve araçlarının sahibi tek bir Plugin olur. Açık kullanıcı seçimi yine önceliklidir: kullanıcı her iki Plugin'i de açıkça etkinleştirirse OpenClaw bu seçimi korur ve istenen Plugin kümesini sessizce değiştirmek yerine yinelenen kanal/araç tanılamaları 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 başvurusu

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

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

OpenClaw şu önceliği uygular:

• açık provider/model başvuruları sahip olan providers manifest meta verilerini kullanır
• modelPatterns, modelPrefixes karşısında üstün gelir
• paketlenmemiş bir Plugin ve paketlenmiş bir Plugin eşleşirse paketlenmemiş Plugin kazanır
• kalan belirsizlik, kullanıcı veya yapılandırma bir sağlayıcı belirtene kadar yok sayılır

Alanlar:

modelCatalog başvurusu

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 manifest'e ait kaynaktır. Çalışma zamanı yenilemesi yine sağlayıcı çalışma zamanı koduna aittir, ancak manifest çekirdeğe çalışma zamanının ne zaman gerektiğini 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ı için sağlayıcı sahipliği aramasına katılır. Takma ad hedefleri, aynı Plugin'in sahip olduğu üst düzey sağlayıcılar olmalıdır. Sağlayıcıyla filtrelenmiş bir liste bir takma ad kullandığında OpenClaw sahip olan manifest'i okuyabilir ve sağlayıcı çalışma zamanını yüklemeden takma ad API/base URL geçersiz kılmalarını uygulayabilir. Takma adlar filtrelenmemiş katalog listelerini genişletmez; geniş listeler yalnızca sahip olan kanonik sağlayıcı satırlarını yayar.

suppressions eski sağlayıcı çalışma zamanı suppressBuiltInModel hook'unun yerini alır. Bastırma girdileri yalnızca sağlayıcı Plugin'e 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ı bastırma hook'ları artık çağrılmaz.

Sağlayıcı alanları:

Model alanları:

Bastırma 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 atlaması için yeterince eksiksiz olduğunda kullanın. Manifest satırları yararlı listelenebilir başlangıç verileri veya tamamlayıcılar olduğunda, ancak yenileme/önbellek daha sonra daha fazla satır ekleyebildiğinde refreshable kullanın; refreshable satırlar tek başlarına yetkili değildir. OpenClaw listeyi bilmek için sağlayıcı çalışma zamanını yüklemek zorunda olduğunda runtime kullanın.

modelIdNormalization başvurusu

Sağlayıcı çalışma zamanı yüklenmeden önce gerçekleşmesi gereken ucuz, sağlayıcıya ait model kimliği temizliği için modelIdNormalization kullanın. Bu, kısa model adları, sağlayıcıya yerel eski kimlikler ve proxy önek kuralları gibi takma adları, çekirdek model seçimi tabloları yerine sahibi olan Plugin manifestinde tutar.

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

Sağlayıcı alanları:

providerEndpoints başvurusu

Sağlayıcı çalışma zamanı yüklenmeden önce genel istek ilkesinin bilmesi gereken uç nokta sınıflandırması için providerEndpoints kullanın. Çekirdek hâlâ her endpointClass değerinin anlamına sahiptir; Plugin manifestleri ana makine ve temel URL meta verilerine sahiptir.

Uç nokta alanları:

providerRequest başvurusu

Sağlayıcı çalışma zamanını yüklemeden genel istek ilkesinin ihtiyaç duyduğu ucuz istek uyumluluğu meta verileri için providerRequest kullanın. Davranışa özel yük yeniden yazmayı sağlayıcı çalışma zamanı hook’larında veya paylaşılan sağlayıcı ailesi yardımcılarında tutun.

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

Sağlayıcı alanları:

modelPricing başvurusu

Bir sağlayıcı çalışma zamanı yüklenmeden önce denetim düzlemi fiyatlandırma davranışı üzerinde denetime ihtiyaç duyduğunda modelPricing kullanın. Gateway fiyatlandırma önbelleği bu meta verileri sağlayıcı çalışma zamanı kodunu içe aktarmadan 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 kurulu olmayabilecek sağlayıcılar için OpenClaw’a ait önizleme meta verileridir. Bir Plugin manifestinin parçası değildir. Plugin manifestleri, kurulu Plugin yetkisi olmaya devam eder. Sağlayıcı Dizini, gelecekteki kurulabilir sağlayıcı ve kurulum öncesi model seçici yüzeylerinin, bir sağlayıcı Plugin’i kurulu olmadığında kullanacağı dahili yedek sözleşmedir.

Katalog yetkisi sırası:

1. Kullanıcı yapılandırması.
2. Kurulu Plugin manifesti modelCatalog.
3. Açık yenilemeden gelen model kataloğu önbelleği.
4. OpenClaw Sağlayıcı Dizini önizleme satırları.

Sağlayıcı Dizini; sırlar, etkin durum, çalışma zamanı hook’ları veya canlı hesaba özel model verileri içermemelidir. Önizleme katalogları, Plugin manifestleriyle aynı modelCatalog sağlayıcı satırı şeklini kullanır, ancak api, baseUrl, fiyatlandırma veya uyumluluk bayrakları gibi çalışma zamanı adaptörü alanları bilerek kurulu Plugin manifestiyle hizalı tutulmadıkça 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 onboarding işleminin sağlayıcı API’lerini çağırmasını sağlamak yerine açık model kataloğu önbellek yolu üzerinden yenilenmiş satırlar yazmalıdır.

Sağlayıcı Dizini girdileri, Plugin’i çekirdekten çıkarılmış veya başka bir şekilde henüz kurulmamış sağlayıcılar için kurulabilir Plugin meta verileri de taşıyabilir. Bu meta veriler kanal kataloğu desenini yansıtır: paket adı, npm kurulum belirtimi, beklenen bütünlük ve ucuz kimlik doğrulama seçimi etiketleri, kurulabilir bir kurulum seçeneği göstermek için yeterlidir. Plugin kurulduktan sonra, onun manifesti kazanır ve Sağlayıcı Dizini girdisi o sağlayıcı için yok sayılır.

Eski üst düzey yetenek anahtarları kullanımdan kaldırılmıştır. speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders ve webSearchProviders değerlerini contracts altına taşımak için openclaw doctor --fix kullanın; normal manifest yükleme artık bu üst düzey alanları yetenek sahipliği olarak ele almaz.

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

İki dosya farklı işler görür:

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

• OpenClaw’ın bunu Plugin kodunu yüklemeden önce 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, bilerek openclaw.plugin.json yerine package.json içindeki openclaw bloğunda yaşar. openclaw.bundle ve openclaw.bundle.json OpenClaw Plugin sözleşmeleri değildir; yerel Pluginler openclaw.plugin.json artı aşağıdaki desteklenen package.json#openclaw alanlarını kullanmalıdır.

Önemli örnekler:

Manifest meta verileri, runtime yüklenmeden önce onboarding içinde hangi sağlayıcı/kanal/kurulum seçeneklerinin görüneceğine karar verir. package.json#openclaw.install, kullanıcı bu seçeneklerden birini seçtiğinde onboarding'e o Plugin'i nasıl alacağını veya etkinleştireceğini söyler. Yükleme ipuçlarını openclaw.plugin.json içine taşımayın.

openclaw.install.minHostVersion, paketlenmemiş Plugin kaynakları için yükleme ve manifest registry yükleme sırasında uygulanır. Geçersiz değerler reddedilir; daha yeni ama geçerli değerler, eski host'larda harici Plugin'leri atlar. Paketlenmiş kaynak Plugin'lerinin host checkout ile aynı sürümde olduğu varsayılır.

Resmi isteğe bağlı yükleme meta verileri, Plugin ClawHub üzerinde yayımlanıyorsa clawhubSpec kullanmalıdır; onboarding bunu tercih edilen uzak kaynak olarak ele alır ve yükleme sonrasında ClawHub artifact bilgilerini kaydeder. npmSpec, henüz ClawHub'a taşınmamış paketler için uyumluluk fallback'i olarak kalır.

Kesin npm sürüm sabitlemesi zaten npmSpec içinde yer alır; örneğin "npmSpec": "@wecom/[email protected]". Resmi harici katalog girdileri, alınan npm artifact'i artık sabitlenmiş sürümle eşleşmiyorsa güncelleme akışlarının kapalı şekilde başarısız olması için kesin spec'leri expectedIntegrity ile eşleştirmelidir. Etkileşimli onboarding, uyumluluk için çıplak paket adları ve dist-tag'ler dahil olmak üzere güvenilir registry npm spec'lerini sunmaya devam eder. Katalog tanılamaları kesin, kayan, bütünlükle sabitlenmiş, eksik bütünlüklü, paket adı uyuşmazlığı olan ve geçersiz varsayılan seçim kaynaklarını ayırt edebilir. Ayrıca expectedIntegrity mevcutken sabitleyebileceği geçerli bir npm kaynağı yoksa uyarır. expectedIntegrity mevcut olduğunda yükleme/güncelleme akışları bunu uygular; atlandığında registry çözümlemesi bütünlük sabitlemesi olmadan kaydedilir.

Kanal Plugin'leri, durum, kanal listesi veya SecretRef taramaları tam runtime yüklenmeden yapılandırılmış hesapları tanımlamak zorunda olduğunda openclaw.setupEntry sağlamalıdır. Kurulum girişi kanal meta verilerini ve kurulum açısından güvenli config, durum ve secrets adapter'larını açığa çıkarmalıdır; ağ istemcilerini, Gateway dinleyicilerini ve transport runtime'larını ana extension giriş noktasında tutun.

Runtime giriş noktası alanları, kaynak giriş noktası alanları için paket sınırı denetimlerini geçersiz kılmaz. Örneğin, openclaw.runtimeExtensions dışarı kaçan bir openclaw.extensions yolunu yüklenebilir hale getiremez.

openclaw.install.allowInvalidConfigRecovery bilinçli olarak dar kapsamlıdır. Rastgele bozuk config'leri yüklenebilir hale getirmez. Bugün yalnızca eksik paketlenmiş Plugin yolu veya aynı paketlenmiş Plugin için eski bir channels.<id> girdisi gibi belirli eski paketlenmiş-Plugin yükseltme hatalarından yükleme akışlarının kurtulmasına izin verir. İlgisiz config hataları yüklemeyi yine engeller 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 varlık akışları tam kanal Plugin'i yüklenmeden önce ucuz 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: Bu meta veriyi Plugin'leri otomatik etkinleştirmek, runtime bağımlılıklarını onarmak veya bir kanal runtime'ının yüklenip yüklenmeyeceğine karar vermek için kullanmayın. Hedef export yalnızca kalıcı durumu okuyan küçük bir işlev olmalıdır; bunu tam kanal runtime barrel'ı üzerinden yönlendirmeyin.

openclaw.channel.configuredState, ucuz yalnızca env configured denetimleri için aynı şekli izler:

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

Bir kanal configured-state'i env veya diğer küçük runtime dışı girdilerden yanıtlayabiliyorsa bunu kullanın. Denetim tam config çözümlemesi veya gerçek kanal runtime'ı gerektiriyorsa bu mantığı Plugin config.hasConfiguredState hook'unda tutun.

Keşif önceliği (yinelenen Plugin id'leri)

OpenClaw, Plugin'leri birkaç kökten keşfeder (paketlenmiş, global yükleme, workspace, explicit config-selected yollar). İki keşif aynı id değerini paylaşıyorsa yalnızca en yüksek öncelikli manifest tutulur; daha düşük öncelikli yinelenenler yanına yüklenmek yerine düşürülür.

Öncelik, en yüksekten en düşüğe:

1. Config-selected — plugins.entries.<id> içinde açıkça sabitlenmiş bir yol
2. Paketlenmiş — OpenClaw ile birlikte gelen Plugin'ler
3. Global yükleme — global OpenClaw Plugin köküne yüklenen Plugin'ler
4. Workspace — geçerli workspace'e göre keşfedilen Plugin'ler

Sonuçlar:

• Workspace içinde duran paketlenmiş bir Plugin'in fork'lanmış veya eski bir kopyası, paketlenmiş build'i gölgelemez.
• Paketlenmiş bir Plugin'i yerel bir Plugin ile gerçekten geçersiz kılmak için workspace keşfine güvenmek yerine onu plugins.entries.<id> aracılığıyla sabitleyin; böylece öncelik sayesinde kazanır.
• Yinelenen düşürmeler loglanır, böylece Doctor ve başlatma tanılamaları atılan kopyayı gösterebilir.
• Config-selected yinelenen geçersiz kılmaları, tanılamalarda açık geçersiz kılmalar olarak ifade edilir, ancak eski fork'lar ve yanlışlıkla oluşan gölgeler görünür kalsın diye yine de uyarır.

JSON Schema gereksinimleri

• Her Plugin bir JSON Schema ile gelmelidir, config kabul etmese bile.
• Boş bir schema kabul edilebilir (örneğin, { "type": "object", "additionalProperties": false }).
• Schema'lar runtime'da değil, config okuma/yazma zamanında doğrulanır.
• Paketlenmiş bir Plugin'i yeni config anahtarlarıyla genişletirken veya fork'larken aynı anda o Plugin'in openclaw.plugin.json configSchema değerini güncelleyin. Paketlenmiş Plugin schema'ları strict'tir, bu yüzden kullanıcı config'ine configSchema.properties içine myNewKey eklemeden plugins.entries.<id>.config.myNewKey eklemek, Plugin runtime yüklenmeden önce reddedilir.

Örnek schema extension:

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

Doğrulama davranışı

• Kanal id'si bir Plugin manifest tarafından bildirilmemişse bilinmeyen channels.* anahtarları hatadır.
• plugins.entries.<id>, plugins.allow, plugins.deny ve plugins.slots.* keşfedilebilir Plugin id'lerine başvurmalıdır. Bilinmeyen id'ler hatadır.
• Bir Plugin yüklüyse ancak bozuk veya eksik manifest ya da schema içeriyorsa doğrulama başarısız olur ve Doctor Plugin hatasını raporlar.
• Plugin config'i mevcut ama Plugin devre dışı ise config korunur ve Doctor + log'larda bir uyarı gösterilir.

Tam plugins.* schema'sı için Yapılandırma referansı bölümüne bakın.

Notlar

• Manifest, yerel dosya sistemi yüklemeleri dahil yerel OpenClaw Plugin'leri için zorunludur. Runtime yine Plugin modülünü ayrı olarak yükler; manifest yalnızca keşif + doğrulama içindir.
• Yerel manifestler JSON5 ile ayrıştırılır; bu nedenle son değer hâlâ bir nesne olduğu sürece yorumlar, sonda kalan virgüller ve tırnaksız anahtarlar kabul edilir.
• Manifest yükleyici yalnızca belgelenmiş manifest 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 geniş runtime kodunu içe aktarmamalıdır; bunu istek zamanı yürütmesi için değil, statik sağlayıcı katalog metadatası veya dar keşif tanımlayıcıları için kullanın. providerDiscoveryEntry eski yazımdır ve mevcut Plugin'ler için hâlâ çalışır.
• Ayrıcalıklı Plugin türleri plugins.slots.* üzerinden seçilir: plugins.slots.memory ile kind: "memory", plugins.slots.contextEngine ile kind: "context-engine" (varsayılan legacy).
• Ayrıcalıklı Plugin türünü bu manifestte bildirin. Runtime girişi OpenClawPluginDefinition.kind kullanımdan kaldırılmıştır ve yalnızca eski Plugin'ler için uyumluluk yedeği olarak kalır.
• Ortam değişkeni metadatası (setup.providers[].envVars, kullanımdan kaldırılmış providerAuthEnvVars ve channelEnvVars) yalnızca bildirimseldir. Durum, denetim, cron teslim doğrulaması ve diğer salt okunur yüzeyler, bir ortam değişkenini yapılandırılmış olarak değerlendirmeden önce hâlâ Plugin güveni ve etkinleştirme politikasını uygular.
• Sağlayıcı kodu gerektiren runtime sihirbazı metadatası için bkz. Sağlayıcı runtime hook'ları.
• Plugin'iniz yerel modüllere bağlıysa derleme adımlarını ve tüm paket yöneticisi izin listesi gereksinimlerini belgeleyin (örneğin, pnpm allow-build-scripts + pnpm rebuild <package>).

İlgili