​

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 auth ve onboarding meta verileri
• plugin çalışma zamanı yüklenmeden çözülmesi gereken takma ad ve otomatik etkinleştirme meta verileri
• çalışma zamanı yüklenmeden önce plugin’i otomatik etkinleştirmesi gereken kısa model ailesi sahipliği meta verileri
• paketlenmiş uyumluluk bağlantıları ve sözleşme kapsamı için kullanılan statik yetenek sahipliği anlık görüntüleri
• çalışma zamanı yüklenmeden katalog ve doğrulama yüzeylerine birleştirilmesi gereken kanala özgü yapılandırma meta verileri
• yapılandırma UI ipuçları

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

​

Asgari örnek

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

​

Zengin örnek

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter sağlayıcı plugin'i",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "cliBackends": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["OPENROUTER_API_KEY"]
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "OpenRouter API anahtarı",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "OpenRouter API anahtarı",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API anahtarı",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

​

Üst düzey alan başvurusu

​

providerAuthChoices başvurusu

​

uiHints başvurusu

{
  "uiHints": {
    "apiKey": {
      "label": "API anahtarı",
      "help": "OpenRouter istekleri için kullanılır",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}

​

contracts başvurusu

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

​

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ı sahip providers manifest meta verilerini kullanır
• modelPatterns, modelPrefixes üzerinde önceliklidir
• paketlenmemiş bir plugin ile paketlenmiş bir plugin birlikte eşleşirse, paketlenmemiş plugin kazanır
• kalan belirsizlik, kullanıcı veya yapılandırma bir sağlayıcı belirtinceye kadar yok sayılır

​

Manifest ve 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ışı ile ilgiliyse, package.json içine koyun

​

Keşfi etkileyen package.json alanları

​

JSON Şeması gereksinimleri

• Her plugin bir JSON Şeması göndermelidir, hiç 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şvurmak zorundadır. Bilinmeyen kimlikler hatadır.
• Bir plugin kuruluysa ancak bozuk veya eksik bir manifest ya da şemaya sahipse, 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â 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, env adlarını incelemek için plugin çalışma zamanını başlatmaması gereken auth yoklamaları, env-işaretleyici doğrulaması ve benzeri sağlayıcı-auth yüzeyleri için düşük maliyetli meta veri yoludur.
• providerAuthChoices, auth-seçimi seçicileri, --auth-choice çözümleme, tercih edilen sağlayıcı eşleme ve sağlayıcı çalışma zamanı yüklenmeden önce basit onboarding CLI bayrağı kaydı için düşük maliyetli meta veri yoludur. Sağlayıcı kodu gerektiren çalışma zamanı sihirbazı meta verileri için bkz. Provider runtime hooks.
• Dışlayıcı plugin türleri plugins.slots.* üzerinden seçilir.
  • kind: "memory", plugins.slots.memory tarafından seçilir.
  • kind: "context-engine", plugins.slots.contextEngine tarafından seçilir (varsayılan: yerleşik legacy).
• channels, providers, cliBackends ve skills, bir plugin bunlara ihtiyaç duymadığında atlanabilir.
• Plugin’iniz yerel modüllere bağlıysa, derleme adımlarını ve olası paket yöneticisi izin listesi gereksinimlerini belgeleyin (örneğin pnpm allow-build-scripts
  • pnpm rebuild <package>).

​

İlgili

• Building Plugins — plugin’lere başlangıç
• Plugin Architecture — iç mimari
• SDK Overview — Plugin SDK başvurusu