​

Plugin manifesti (openclaw.plugin.json)

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

​

Bu dosya ne yapar

• plugin kimliği
• yapılandırma doğrulaması
• plugin çalışma zamanını başlatmadan kullanılabilir olması gereken kimlik doğrulama ve onboarding meta verileri
• denetim düzlemi yüzeylerinin çalışma zamanı yüklenmeden önce inceleyebileceği düşük maliyetli etkinleştirme ipuçları
• kurulum/onboarding yüzeylerinin çalışma zamanı yüklenmeden önce inceleyebileceği düşük maliyetli kurulum tanımlayıcıları
• plugin çalışma zamanı yüklenmeden önce çözümlenmesi gereken takma ad ve otomatik etkinleştirme meta verileri
• plugin’i çalışma zamanı yüklenmeden önce otomatik etkinleştirmesi gereken kısa model ailesi sahipliği meta verileri
• paketlenmiş uyumluluk bağlama ve sözleşme kapsamı için kullanılan statik yetenek sahipliği anlık görüntüleri
• paylaşılan openclaw qa ana makinesinin plugin çalışma zamanı yüklenmeden önce inceleyebileceği düşük maliyetli QA çalıştırıcısı meta verileri
• çalışma zamanı yüklemeden katalog ve doğrulama yüzeyleriyle birleştirilmesi gereken kanala özgü yapılandırma meta verileri
• yapılandırma arayüzü ipuçları

• çalışma zamanı davranışını kaydetmek
• kod giriş noktalarını bildirmek
• npm kurulum meta verileri

​

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-"]
  },
  "providerEndpoints": [
    {
      "endpointClass": "xai-native",
      "hosts": ["api.x.ai"]
    }
  ],
  "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

​

providerAuthChoices başvurusu

​

commandAliases başvurusu

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

​

activation başvurusu

​

qaRunners başvurusu

{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "Kullan-at bir homeserver'a karşı Docker destekli Matrix canlı QA hattını çalıştır"
    }
  ]
}

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

• komut tetiklemeli CLI planlaması, eski commandAliases[].cliCommand veya commandAliases[].name alanlarına geri döner
• kanal tetiklemeli kurulum/kanal planlaması, açık kanal etkinleştirme meta verisi eksik olduğunda eski channels[] sahipliğine geri döner
• provider tetiklemeli kurulum/çalışma zamanı planlaması, açık provider etkinleştirme meta verisi eksik olduğunda eski providers[] ve üst düzey cliBackends[] sahipliğine geri döner

​

setup başvurusu

{
  "setup": {
    "providers": [
      {
        "id": "openai",
        "authMethods": ["api-key"],
        "envVars": ["OPENAI_API_KEY"]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}

​

setup.providers başvurusu

​

setup alanları

​

uiHints başvurusu

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

​

contracts başvurusu

{
  "contracts": {
    "embeddedExtensionFactories": ["pi"],
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

​

mediaUnderstandingProviderMetadata başvurusu

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

​

channelConfigs başvurusu

{
  "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 bağlantısı",
      "preferOver": ["matrix-legacy"]
    }
  }
}

​

modelSupport başvurusu

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

• açık provider/model başvuruları, sahibi olan providers manifest meta verilerini kullanır
• modelPatterns, modelPrefixes değerlerini geçersiz kılar
• hem paketlenmemiş bir plugin hem de paketlenmiş bir plugin eşleşirse paketlenmemiş plugin kazanır
• kalan belirsizlik, kullanıcı veya yapılandırma bir provider belirtinceye kadar yok sayılır

​

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

• OpenClaw bunu plugin kodunu yüklemeden önce bilmek zorundaysa 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ı

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

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

​

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

1. Yapılandırmada seçilen — plugins.entries.<id> içinde açıkça sabitlenmiş bir yol
2. Paketlenmiş — OpenClaw ile birlikte gelen plugin’ler
3. Global kurulum — global OpenClaw plugin köküne kurulmuş plugin’ler
4. Çalışma alanı — geçerli çalışma alanına göre keşfedilen plugin’ler

• Çalışma alanında duran, çatallanmış veya eski bir paketlenmiş plugin kopyası, paketlenmiş derlemenin önüne geçmez.
• Paketlenmiş bir plugin’i yerel olanla gerçekten geçersiz kılmak için, çalışma alanı keşfine güvenmek yerine öncelik sırasıyla kazanması amacıyla onu plugins.entries.<id> üzerinden sabitleyin.
• Atılan yinelenenler günlüğe kaydedilir; böylece Doctor ve başlangıç tanılamaları elenen kopyayı gösterebilir.

​

JSON Schema gereksinimleri

• Her plugin mutlaka bir JSON Schema yayımlamalıdır, 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 okuma/yazma sırasında doğrulanır.

​

Doğrulama davranışı

• Bilinmeyen channels.* anahtarları, kanal kimliği bir plugin manifesti tarafından bildirilmedikçe hatadır.
• plugins.entries.<id>, plugins.allow, plugins.deny ve plugins.slots.*, keşfedilebilir plugin kimliklerine başvurmalıdır. Bilinmeyen kimlikler hatadır.
• Bir plugin kuruluysa ancak bozuk veya eksik manifesti ya da şeması varsa doğrulama başarısız olur ve Doctor plugin hatasını bildirir.
• Plugin yapılandırması varsa ancak plugin devre dışıysa, yapılandırma korunur ve Doctor + günlüklerde bir uyarı gösterilir.

​

Notlar

• Manifest, yerel dosya sistemi yüklemeleri dahil yerel OpenClaw plugin’leri için zorunludur.
• Çalışma zamanı yine de 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, sondaki virgüller ve tırnaksız anahtarlar kabul edilir.
• Manifest yükleyicisi yalnızca belgelenmiş manifest alanlarını okur. Buraya özel üst düzey anahtarlar eklemekten kaçının.
• providerAuthEnvVars, kimlik doğrulama yoklamaları, env işaretleyici doğrulaması ve env adlarını incelemek için plugin çalışma zamanını başlatmaması gereken benzer provider kimlik doğrulama yüzeyleri için düşük maliyetli meta veri yoludur.
• providerAuthAliases, provider varyantlarının başka bir provider’ın kimlik doğrulama env değişkenlerini, kimlik doğrulama profillerini, yapılandırma tabanlı kimlik doğrulamayı ve API anahtarı onboarding seçeneğini, bu ilişkiyi çekirdekte sabit kodlamadan yeniden kullanmasına izin verir.
• providerEndpoints, provider plugin’lerinin basit endpoint host/baseUrl eşleştirme meta verilerinin sahibi olmasına izin verir. Bunu yalnızca çekirdeğin zaten desteklediği endpoint sınıfları için kullanın; çalışma zamanı davranışının sahibi hâlâ plugin’dir.
• syntheticAuthRefs, çalışma zamanı kayıt defteri mevcut olmadan önce soğuk model keşfine görünür olması gereken provider’a ait sentetik kimlik doğrulama hook’ları için düşük maliyetli meta veri yoludur. Yalnızca çalışma zamanı provider’ı veya CLI backend’i gerçekten resolveSyntheticAuth uygulayan başvuruları listeleyin.
• nonSecretAuthMarkers, yerel, OAuth veya ortamdan gelen kimlik bilgisi işaretleyicileri gibi paketlenmiş plugin’e ait yer tutucu API anahtarları için düşük maliyetli meta veri yoludur. Çekirdek, sahibi olan provider’ı sabit kodlamadan bunları kimlik doğrulama gösterimi ve gizli bilgi denetimleri için gizli olmayan değerler olarak ele alır.
• channelEnvVars, env adlarını incelemek için plugin çalışma zamanını başlatmaması gereken kabuk env geri dönüşü, setup istemleri ve benzer kanal yüzeyleri için düşük maliyetli meta veri yoludur. Env adları meta veridir, tek başlarına etkinleştirme değildir: durum, denetim, Cron teslim doğrulaması ve diğer salt okunur yüzeyler, bir env değişkenini yapılandırılmış kanal olarak kabul etmeden önce hâlâ plugin güvenini ve etkili etkinleştirme ilkesini uygular.
• providerAuthChoices, provider çalışma zamanı yüklenmeden önce kimlik doğrulama seçici arayüzleri, --auth-choice çözümlemesi, tercih edilen provider eşlemesi ve basit onboarding CLI bayrağı kaydı için düşük maliyetli meta veri yoludur. Provider kodu gerektiren çalışma zamanı sihirbazı meta verileri için bkz. Provider çalışma zamanı hook’ları.
• Yalnızca birine özel plugin türleri plugins.slots.* üzerinden seçilir.
  • kind: "memory" şu alan tarafından seçilir: plugins.slots.memory.
  • kind: "context-engine" şu alan tarafından seçilir: plugins.slots.contextEngine (varsayılan: yerleşik legacy).
• channels, providers, cliBackends ve skills, bir plugin bunlara ihtiyaç duymuyorsa atlanabilir.
• Plugin’iniz yerel modüllere bağlıysa derleme adımlarını ve paket yöneticisi izin listesi gereksinimlerini belgeleyin (örneğin, pnpm allow-build-scripts
  • pnpm rebuild <package>).

​

İlgili

• Plugin’ler Oluşturma — plugin’lerle çalışmaya başlama
• Plugin Mimarisi — iç mimari
• SDK Genel Bakış — Plugin SDK başvurusu