​

Manifest plugin (openclaw.plugin.json)

• Bundle Codex: .codex-plugin/plugin.json
• Bundle Claude: .claude-plugin/plugin.json atau layout komponen Claude default tanpa manifest
• Bundle Cursor: .cursor-plugin/plugin.json

​

Fungsi file ini

• identitas plugin
• validasi konfigurasi
• metadata auth dan onboarding yang harus tersedia tanpa menjalankan runtime plugin
• metadata alias dan auto-enable yang harus di-resolve sebelum runtime plugin dimuat
• metadata kepemilikan shorthand model-family yang harus mengaktifkan plugin secara otomatis sebelum runtime dimuat
• snapshot kepemilikan kapabilitas statis yang digunakan untuk wiring kompatibilitas bawaan dan cakupan kontrak
• metadata konfigurasi khusus channel yang harus digabungkan ke permukaan katalog dan validasi tanpa memuat runtime
• petunjuk UI konfigurasi

• mendaftarkan perilaku runtime
• mendeklarasikan entrypoint kode
• metadata instalasi npm

​

Contoh minimal

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

​

Contoh lengkap

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "Plugin penyedia OpenRouter",
  "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": "API key OpenRouter",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "API key OpenRouter",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

​

Referensi field tingkat atas

​

Referensi providerAuthChoices

​

Referensi uiHints

{
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "help": "Digunakan untuk permintaan OpenRouter",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}

​

Referensi contracts

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

​

Referensi channelConfigs

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

​

Referensi modelSupport

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

• ref provider/model eksplisit menggunakan metadata manifest providers yang memilikinya
• modelPatterns mengalahkan modelPrefixes
• jika satu plugin non-bawaan dan satu plugin bawaan sama-sama cocok, plugin non-bawaan menang
• ambiguitas yang tersisa diabaikan sampai pengguna atau konfigurasi menentukan penyedia

​

Manifest versus package.json

• jika OpenClaw harus mengetahuinya sebelum memuat kode plugin, letakkan di openclaw.plugin.json
• jika itu tentang packaging, file entry, atau perilaku instalasi npm, letakkan di package.json

​

Field package.json yang memengaruhi discovery

​

Persyaratan skema JSON

• Setiap plugin harus menyertakan Skema JSON, bahkan jika tidak menerima konfigurasi.
• Skema kosong dapat diterima (misalnya, { "type": "object", "additionalProperties": false }).
• Skema divalidasi saat baca/tulis konfigurasi, bukan saat runtime.

​

Perilaku validasi

• Key channels.* yang tidak dikenal adalah error, kecuali ID channel tersebut dideklarasikan oleh manifest plugin.
• plugins.entries.<id>, plugins.allow, plugins.deny, dan plugins.slots.* harus mereferensikan ID plugin yang dapat ditemukan. ID yang tidak dikenal adalah error.
• Jika plugin terinstal tetapi memiliki manifest atau skema yang rusak atau hilang, validasi gagal dan Doctor melaporkan error plugin tersebut.
• Jika konfigurasi plugin ada tetapi plugin nonaktif, konfigurasi tetap dipertahankan dan peringatan ditampilkan di Doctor + log.

​

Catatan

• Manifest wajib untuk plugin OpenClaw native, termasuk pemuatan dari filesystem lokal.
• Runtime tetap memuat modul plugin secara terpisah; manifest hanya untuk discovery + validasi.
• Manifest native diparse dengan JSON5, jadi komentar, trailing comma, dan key tanpa tanda kutip diterima selama nilai akhirnya tetap berupa object.
• Hanya field manifest yang didokumentasikan yang dibaca oleh pemuat manifest. Hindari menambahkan key tingkat atas kustom di sini.
• providerAuthEnvVars adalah jalur metadata murah untuk probe auth, validasi penanda env, dan permukaan auth penyedia serupa yang tidak seharusnya menjalankan runtime plugin hanya untuk memeriksa nama env.
• providerAuthChoices adalah jalur metadata murah untuk picker pilihan auth, resolusi --auth-choice, pemetaan preferred-provider, dan pendaftaran flag CLI onboarding sederhana sebelum runtime penyedia dimuat. Untuk metadata wizard runtime yang memerlukan kode penyedia, lihat Provider runtime hooks.
• Jenis plugin eksklusif dipilih melalui plugins.slots.*.
  • kind: "memory" dipilih oleh plugins.slots.memory.
  • kind: "context-engine" dipilih oleh plugins.slots.contextEngine (default: bawaan legacy).
• channels, providers, cliBackends, dan skills dapat dihilangkan saat plugin tidak memerlukannya.
• Jika plugin Anda bergantung pada modul native, dokumentasikan langkah build dan semua persyaratan allowlist package manager (misalnya, pnpm allow-build-scripts
  • pnpm rebuild <package>).

​

Terkait

• Building Plugins — memulai dengan plugin
• Plugin Architecture — arsitektur internal
• SDK Overview — referensi Plugin SDK