​

Manifest Plugin (openclaw.plugin.json)

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

​

Apa fungsi file ini

• identitas plugin
• validasi config
• metadata autentikasi dan onboarding yang harus tersedia tanpa mem-boot runtime plugin
• petunjuk aktivasi ringan yang dapat diperiksa oleh permukaan control-plane sebelum runtime dimuat
• deskriptor setup ringan yang dapat diperiksa oleh permukaan setup/onboarding sebelum runtime dimuat
• metadata alias dan auto-enable yang harus diselesaikan sebelum runtime plugin dimuat
• metadata kepemilikan keluarga model singkat yang harus mengaktifkan plugin secara otomatis sebelum runtime dimuat
• snapshot kepemilikan kapabilitas statis yang digunakan untuk wiring kompatibilitas bundle dan cakupan kontrak
• metadata QA runner ringan yang dapat diperiksa host bersama openclaw qa sebelum runtime plugin dimuat
• metadata config khusus channel yang harus digabungkan ke permukaan katalog dan validasi tanpa memuat runtime
• petunjuk UI config

• 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": "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"
      }
    }
  }
}

​

Referensi field tingkat atas

​

Referensi providerAuthChoices

​

Referensi commandAliases

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

​

Referensi activation

​

Referensi qaRunners

{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "Jalankan lane QA live Matrix berbasis Docker terhadap homeserver disposable"
    }
  ]
}

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

• perencanaan CLI yang dipicu perintah melakukan fallback ke commandAliases[].cliCommand atau commandAliases[].name lama
• perencanaan setup/channel yang dipicu channel melakukan fallback ke kepemilikan channels[] lama saat metadata aktivasi channel eksplisit tidak ada
• perencanaan setup/runtime yang dipicu provider melakukan fallback ke kepemilikan providers[] lama dan cliBackends[] tingkat atas saat metadata aktivasi provider eksplisit tidak ada

​

Referensi setup

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

​

Referensi setup.providers

​

Field setup

​

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": "Homeserver URL",
          "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"]
  }
}

• referensi provider/model eksplisit menggunakan metadata manifest providers yang memilikinya
• modelPatterns mengalahkan modelPrefixes
• jika satu Plugin non-bundle dan satu Plugin bundle sama-sama cocok, Plugin non-bundle yang menang
• ambiguitas yang tersisa diabaikan sampai pengguna atau config menentukan provider

​

Manifest versus package.json

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

​

Field package.json yang memengaruhi discovery

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

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

​

Persyaratan JSON Schema

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

​

Perilaku validasi

• Kunci 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 sebuah Plugin terinstal tetapi memiliki manifest atau skema yang rusak atau hilang, validasi gagal dan Doctor melaporkan error Plugin tersebut.
• Jika config Plugin ada tetapi Plugin tersebut dinonaktifkan, config tetap disimpan dan peringatan akan ditampilkan di Doctor + log.

​

Catatan

• Manifest ini wajib untuk Plugin OpenClaw native, termasuk pemuatan dari filesystem lokal.
• Runtime tetap memuat modul plugin secara terpisah; manifest hanya digunakan untuk discovery + validasi.
• Manifest native di-parse dengan JSON5, jadi komentar, trailing comma, dan key tanpa tanda kutip diterima selama nilai akhirnya tetap berupa object.
• Hanya field manifest yang terdokumentasi yang dibaca oleh manifest loader. Hindari menambahkan key tingkat atas kustom di sini.
• providerAuthEnvVars adalah jalur metadata ringan untuk probe auth, validasi penanda env, dan permukaan auth provider serupa yang tidak seharusnya mem-boot runtime plugin hanya untuk memeriksa nama env.
• providerAuthAliases memungkinkan varian provider menggunakan ulang env var auth provider lain, profil auth, auth berbasis config, dan pilihan onboarding API key tanpa melakukan hardcode hubungan tersebut di core.
• providerEndpoints memungkinkan Plugin provider memiliki metadata pencocokan host/baseUrl endpoint sederhana. Gunakan hanya untuk kelas endpoint yang sudah didukung core; plugin tetap memiliki perilaku runtime.
• syntheticAuthRefs adalah jalur metadata ringan untuk hook auth sintetis milik provider yang harus terlihat oleh discovery model cold path sebelum registry runtime ada. Cantumkan hanya referensi yang runtime provider atau backend CLI-nya benar-benar mengimplementasikan resolveSyntheticAuth.
• nonSecretAuthMarkers adalah jalur metadata ringan untuk placeholder API key milik Plugin bundle seperti penanda kredensial lokal, OAuth, atau ambient. Core memperlakukan ini sebagai non-secret untuk tampilan auth dan audit secret tanpa melakukan hardcode pada provider pemiliknya.
• channelEnvVars adalah jalur metadata ringan untuk fallback shell-env, prompt setup, dan permukaan channel serupa yang tidak seharusnya mem-boot runtime plugin hanya untuk memeriksa nama env.
• providerAuthChoices adalah jalur metadata ringan untuk picker pilihan auth, resolusi --auth-choice, pemetaan provider pilihan, dan registrasi flag CLI onboarding sederhana sebelum runtime provider dimuat. Untuk metadata wizard runtime yang memerlukan kode provider, lihat Hook runtime provider.
• Jenis Plugin eksklusif dipilih melalui plugins.slots.*.
  • kind: "memory" dipilih oleh plugins.slots.memory.
  • kind: "context-engine" dipilih oleh plugins.slots.contextEngine (default: legacy bawaan).
• channels, providers, cliBackends, dan skills dapat dihilangkan saat sebuah Plugin tidak memerlukannya.
• Jika Plugin Anda bergantung pada modul native, dokumentasikan langkah build dan setiap persyaratan allowlist package manager (misalnya, pnpm allow-build-scripts
  • pnpm rebuild <package>).

​

Terkait

• Membangun Plugin — memulai dengan plugin
• Arsitektur Plugin — arsitektur internal
• Ikhtisar SDK — referensi SDK Plugin