Manifes Plugin

Halaman ini membahas manifes plugin OpenClaw native, openclaw.plugin.json. Untuk tata letak bundel yang kompatibel (Codex, Claude, Cursor), lihat Bundel Plugin.

Format bundel yang kompatibel menggunakan file manifesnya sendiri sebagai gantinya:

• Bundel Codex: .codex-plugin/plugin.json
• Bundel Claude: .claude-plugin/plugin.json, atau tata letak komponen Claude bawaan tanpa manifes
• Bundel Cursor: .cursor-plugin/plugin.json

OpenClaw mendeteksi tata letak tersebut secara otomatis, tetapi tidak memvalidasinya terhadap skema openclaw.plugin.json di bawah ini. Untuk bundel yang kompatibel, OpenClaw membaca metadata bundel, root skill yang dideklarasikan, root perintah Claude, nilai bawaan settings.json Claude, nilai bawaan LSP Claude, dan paket hook yang didukung, jika tata letaknya sesuai dengan ekspektasi runtime OpenClaw.

Setiap plugin OpenClaw native harus menyertakan openclaw.plugin.json di root plugin. OpenClaw membacanya untuk memvalidasi konfigurasi tanpa mengeksekusi kode plugin. Manifes yang tidak ada atau tidak valid akan memblokir validasi konfigurasi dan diperlakukan sebagai kesalahan plugin.

Lihat Plugin untuk panduan lengkap sistem plugin, dan Model kapabilitas untuk model kapabilitas native serta panduan kompatibilitas eksternal saat ini.

Fungsi file ini

openclaw.plugin.json adalah metadata yang dibaca OpenClaw sebelum memuat kode plugin Anda. Semua yang ada di dalamnya harus cukup ringan untuk diperiksa tanpa menjalankan runtime plugin.

Gunakan untuk:

• identitas plugin, validasi konfigurasi, dan petunjuk UI konfigurasi
• metadata autentikasi, orientasi awal, dan penyiapan (alias, pengaktifan otomatis, variabel lingkungan penyedia, pilihan autentikasi)
• petunjuk aktivasi untuk antarmuka bidang kontrol
• kepemilikan singkat keluarga model
• rekam cuplikan statis kepemilikan kapabilitas (contracts)
• metadata runner QA yang dapat diperiksa oleh host bersama openclaw qa
• metadata konfigurasi khusus saluran yang digabungkan ke dalam katalog dan antarmuka validasi

Jangan gunakan untuk: mendaftarkan perilaku runtime, mendeklarasikan titik masuk kode, atau metadata instalasi npm. Hal-hal tersebut berada dalam kode plugin dan package.json Anda.

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-"]  },  "modelIdNormalization": {    "providers": {      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  },  "providerEndpoints": [    {      "endpointClass": "openrouter",      "hostSuffixes": ["openrouter.ai"]    }  ],  "providerRequest": {    "providers": {      "openrouter": {        "family": "openrouter"      }    }  },  "cliBackends": ["openrouter-cli"],  "syntheticAuthRefs": ["openrouter-cli"],  "setup": {    "providers": [      {        "id": "openrouter",        "envVars": ["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 kolom tingkat atas

referensi katalog

catalog menyediakan petunjuk tampilan opsional untuk penjelajah Plugin. Host dapat mengabaikan petunjuk ini. Petunjuk tersebut tidak pernah menginstal atau mengaktifkan Plugin, serta tidak mengubah perilaku runtime atau tingkat kepercayaannya.

{  "catalog": {    "featured": true,    "order": 10  }}

referensi metadata penyedia pembuatan

Bidang metadata penyedia pembuatan menjelaskan sinyal autentikasi statis untuk penyedia yang dideklarasikan dalam daftar contracts.*GenerationProviders yang sesuai. OpenClaw membaca bidang ini sebelum runtime penyedia dimuat agar alat inti dapat menentukan apakah penyedia pembuatan tersedia tanpa mengimpor setiap Plugin penyedia.

Gunakan bidang ini hanya untuk fakta deklaratif yang mudah diperiksa. Transportasi, transformasi permintaan, penyegaran token, validasi kredensial, dan perilaku pembuatan yang sebenarnya tetap berada dalam runtime Plugin.

{  "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"]          }        }      ]    }  }}

Setiap entri metadata mendukung:

Setiap entri configSignals mendukung:

Setiap pembatas mode mendukung:

Setiap entri authSignals mendukung:

Setiap pembatas providerBaseUrl mendukung:

referensi metadata alat

toolMetadata menggunakan bentuk configSignals dan authSignals yang sama seperti metadata penyedia pembuatan, dengan nama alat sebagai kunci. contracts.tools mendeklarasikan kepemilikan. toolMetadata mendeklarasikan bukti ketersediaan yang mudah diperiksa agar OpenClaw dapat menghindari pengimporan runtime Plugin hanya untuk mendapatkan nilai null dari factory alatnya.

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

Entri toolMetadata juga menerima optional (menandai alat sebagai tidak wajib untuk aktivasi Plugin) dan replaySafe (menandai eksekusi alat sebagai aman untuk diulang setelah giliran model yang tidak selesai), selain bidang bersama configSignals/authSignals di atas.

Jika suatu alat tidak memiliki toolMetadata, OpenClaw mempertahankan perilaku yang ada dan memuat Plugin pemilik ketika kontrak alat sesuai dengan kebijakan. Untuk alat pada jalur kritis yang factory-nya bergantung pada autentikasi/konfigurasi, pembuat Plugin harus mendeklarasikan toolMetadata, bukan membuat inti mengimpor runtime untuk menanyakannya.

referensi providerAuthChoices

Setiap entri providerAuthChoices menjelaskan satu pilihan orientasi awal atau autentikasi. OpenClaw membacanya sebelum runtime penyedia dimuat. Daftar penyiapan penyedia menggunakan pilihan manifes ini, pilihan penyiapan yang diturunkan dari deskriptor, dan metadata katalog instalasi tanpa memuat runtime penyedia.

Referensi commandAliases

Gunakan commandAliases ketika sebuah plugin memiliki nama perintah runtime yang mungkin secara keliru dimasukkan pengguna ke dalam plugins.allow atau dicoba dijalankan sebagai perintah CLI root. OpenClaw menggunakan metadata ini untuk diagnostik tanpa mengimpor kode runtime plugin.

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

Referensi activation

Gunakan activation ketika plugin dapat dengan mudah mendeklarasikan peristiwa bidang kendali yang harus menyertakannya dalam rencana aktivasi/pemuatan.

Blok ini adalah metadata perencana, bukan API siklus hidup. Blok ini tidak mendaftarkan perilaku runtime, tidak menggantikan register(...), dan tidak menjanjikan bahwa kode plugin telah dijalankan. Perencana aktivasi menggunakan bidang-bidang ini untuk mempersempit kandidat plugin sebelum kembali menggunakan metadata kepemilikan manifes yang ada, seperti providers, channels, commandAliases, setup.providers, contracts.tools, dan hook.

Utamakan metadata tersempit yang sudah menjelaskan kepemilikan. Gunakan providers, channels, commandAliases, deskriptor penyiapan, atau contracts ketika bidang-bidang tersebut menyatakan hubungannya. Gunakan activation untuk petunjuk perencana tambahan yang tidak dapat direpresentasikan oleh bidang kepemilikan tersebut. Gunakan cliBackends tingkat atas untuk alias runtime CLI seperti claude-cli, my-cli, atau google-gemini-cli; activation.onAgentHarnesses hanya untuk ID harness agen tertanam yang belum memiliki bidang kepemilikan.

Setiap plugin harus mengatur activation.onStartup secara sengaja. Atur ke true hanya ketika plugin harus berjalan selama proses awal Gateway. Atur ke false ketika plugin tidak aktif saat proses awal dan hanya boleh dimuat dari pemicu yang lebih spesifik. Menghilangkan onStartup tidak lagi secara implisit memuat plugin saat proses awal; gunakan metadata aktivasi eksplisit untuk pemicu aktivasi proses awal, saluran, konfigurasi, harness agen, memori, atau pemicu lain yang lebih spesifik.

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

Konsumen aktif saat ini:

• Perencanaan proses awal Gateway menggunakan activation.onStartup untuk impor proses awal secara eksplisit.
• Perencanaan CLI yang dipicu perintah kembali menggunakan commandAliases[].cliCommand atau commandAliases[].name lama.
• Perencanaan proses awal runtime agen menggunakan activation.onAgentHarnesses untuk harness tertanam dan cliBackends[] tingkat atas untuk alias runtime CLI.
• Perencanaan penyiapan/saluran yang dipicu saluran kembali menggunakan kepemilikan channels[] lama ketika metadata aktivasi saluran eksplisit tidak tersedia.
• Perencanaan plugin proses awal menggunakan activation.onConfigPaths untuk permukaan konfigurasi root non-saluran, seperti blok browser milik plugin peramban bawaan.
• Perencanaan penyiapan/runtime yang dipicu penyedia kembali menggunakan kepemilikan providers[] lama dan cliBackends[] tingkat atas ketika metadata aktivasi penyedia eksplisit tidak tersedia.

Diagnostik perencana dapat membedakan petunjuk aktivasi eksplisit dari penggunaan cadangan kepemilikan manifes. Misalnya, activation-command-hint berarti activation.onCommands cocok, sedangkan manifest-command-alias berarti perencana menggunakan kepemilikan commandAliases. Label alasan ini ditujukan untuk diagnostik host dan pengujian; penulis plugin harus tetap mendeklarasikan metadata yang paling tepat menjelaskan kepemilikan.

Referensi qaRunners

Gunakan qaRunners ketika plugin menyediakan satu atau beberapa runner transportasi di bawah root bersama openclaw qa. Jaga agar metadata ini ringan dan statis; runtime plugin tetap memiliki pendaftaran CLI yang sebenarnya melalui permukaan ringan runtime-api.ts yang mengekspor qaRunnerCliRegistrations yang cocok. Sebuah adapterFactory opsional mengekspos transportasi ke skenario QA bersama tanpa mengubah runner perintah yang terdaftar.

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

ID adapterFactory harus cocok dengan commandName. Jangan mengekspor pendaftaran untuk perintah yang tidak ada dalam manifes.

referensi setup

Gunakan setup ketika antarmuka penyiapan dan orientasi memerlukan metadata murah milik plugin sebelum runtime dimuat.

{  "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  }}

cliBackends tingkat teratas tetap valid dan terus mendeskripsikan backend inferensi CLI. setup.cliBackends adalah antarmuka deskriptor khusus penyiapan untuk alur bidang kontrol/penyiapan yang harus tetap hanya berupa metadata.

Jika tersedia, setup.providers dan setup.cliBackends merupakan antarmuka pencarian berbasis deskriptor yang diutamakan untuk penemuan penyiapan. Jika deskriptor hanya mempersempit plugin kandidat dan penyiapan masih memerlukan hook runtime waktu penyiapan yang lebih lengkap, tetapkan requiresRuntime: true dan pertahankan setup-api sebagai jalur eksekusi cadangan.

OpenClaw juga menyertakan setup.providers[].envVars dalam pencarian autentikasi penyedia dan variabel lingkungan generik. providerAuthEnvVars tetap didukung melalui adaptor kompatibilitas selama periode penghentian, tetapi plugin yang tidak dibundel dan masih menggunakannya akan menerima diagnostik manifes. Plugin baru harus menempatkan metadata lingkungan penyiapan/status di setup.providers[].envVars.

Gunakan providerUsageAuthEnvVars ketika kredensial tingkat penagihan atau organisasi harus mengaktifkan resolveUsageAuth tanpa menjadi kredensial inferensi. Nama-nama ini disertakan dalam pemblokiran dotenv ruang kerja, penghapusan dari proses anak ACP, pemfilteran rahasia sandbox, dan pembersihan rahasia secara luas. Runtime penyedia tetap membaca dan mengklasifikasikan nilai tersebut di dalam resolveUsageAuth.

OpenClaw juga dapat memperoleh pilihan penyiapan sederhana dari setup.providers[].authMethods ketika tidak ada entri penyiapan, atau ketika setup.requiresRuntime: false menyatakan bahwa runtime penyiapan tidak diperlukan. Entri providerAuthChoices eksplisit tetap diutamakan untuk label khusus, flag CLI, cakupan orientasi, dan metadata asisten.

Tetapkan requiresRuntime: false hanya ketika deskriptor tersebut memadai untuk antarmuka penyiapan. OpenClaw memperlakukan false eksplisit sebagai kontrak khusus deskriptor dan tidak akan mengeksekusi setup-api atau openclaw.setupEntry untuk pencarian penyiapan. Jika plugin khusus deskriptor masih menyertakan salah satu entri runtime penyiapan tersebut, OpenClaw melaporkan diagnostik tambahan dan terus mengabaikannya. Tidak mencantumkan requiresRuntime mempertahankan perilaku cadangan lama agar plugin yang sudah ada dan menambahkan deskriptor tanpa flag tersebut tidak rusak.

Karena pencarian penyiapan dapat mengeksekusi kode setup-api milik plugin, nilai setup.providers[].id dan setup.cliBackends[] yang telah dinormalisasi harus tetap unik di seluruh plugin yang ditemukan. Kepemilikan yang ambigu akan ditolak secara aman alih-alih memilih pemenang berdasarkan urutan penemuan.

Ketika runtime penyiapan dijalankan, diagnostik registri penyiapan melaporkan penyimpangan deskriptor jika setup-api mendaftarkan penyedia atau backend CLI yang tidak dideklarasikan oleh deskriptor manifes, atau jika deskriptor tidak memiliki pendaftaran runtime yang cocok. Diagnostik ini bersifat tambahan dan tidak menolak plugin lama.

referensi setup.providers

authEvidence ditujukan untuk penanda kredensial lokal milik penyedia yang dapat diverifikasi tanpa memuat kode runtime. Pemeriksaan ini harus tetap murah dan lokal: tanpa panggilan jaringan, tanpa pembacaan rantai kunci atau pengelola rahasia, tanpa perintah shell, dan tanpa pemeriksaan API penyedia.

Entri bukti yang didukung:

bidang setup

referensi uiHints

uiHints adalah pemetaan dari nama bidang konfigurasi ke petunjuk perenderan ringkas. Kunci dapat menggunakan titik untuk bidang konfigurasi bersarang, tetapi tidak ada segmen jalur yang boleh berupa __proto__, constructor, atau prototype; penyiapan menolak nama-nama tersebut.

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

Setiap petunjuk bidang dapat mencakup:

referensi contracts

Gunakan contracts hanya untuk metadata kepemilikan kemampuan statis yang dapat dibaca OpenClaw tanpa mengimpor runtime plugin.

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"],    "trustedToolPolicies": ["workflow-budget"],    "externalAuthProviders": ["acme-ai"],    "embeddingProviders": ["openai-compatible"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "musicGenerationProviders": ["stability-audio"],    "documentExtractors": ["example-docs"],    "webContentExtractors": ["firecrawl"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "workerProviders": ["example-worker"],    "usageProviders": ["acme-ai"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

Setiap daftar bersifat opsional:

contracts.embeddedExtensionFactories dipertahankan untuk pabrik ekstensi khusus app-server Codex bawaan. Transformasi hasil alat bawaan sebaiknya mendeklarasikan contracts.agentToolResultMiddleware dan sebagai gantinya mendaftar dengan api.registerAgentToolResultMiddleware(...). Plugin terinstal dapat menggunakan celah middleware yang sama hanya ketika diaktifkan secara eksplisit dan hanya untuk runtime yang dideklarasikan dalam contracts.agentToolResultMiddleware.

Plugin terinstal yang memerlukan tingkat kebijakan pra-alat tepercaya host harus mendeklarasikan setiap ID lokal yang didaftarkan dalam contracts.trustedToolPolicies dan diaktifkan secara eksplisit. Plugin bawaan mempertahankan jalur kebijakan tepercaya yang ada, tetapi plugin terinstal dengan ID kebijakan yang tidak dideklarasikan akan ditolak sebelum pendaftaran. ID kebijakan dibatasi cakupannya pada plugin yang mendaftar, sehingga dua plugin dapat sama-sama mendeklarasikan dan mendaftarkan workflow-budget; satu plugin tidak boleh mendaftarkan ID lokal yang sama dua kali.

Pendaftaran api.registerTool(...) saat runtime harus cocok dengan contracts.tools. Penemuan alat menggunakan daftar ini untuk hanya memuat runtime plugin yang dapat memiliki alat yang diminta.

Plugin penyedia yang mengimplementasikan resolveExternalAuthProfiles sebaiknya mendeklarasikan contracts.externalAuthProviders; hook autentikasi eksternal yang tidak dideklarasikan akan diabaikan.

Plugin penyedia yang mengimplementasikan resolveUsageAuth dan fetchUsageSnapshot sebaiknya mendeklarasikan setiap ID penyedia yang ditemukan secara otomatis dalam contracts.usageProviders. Penemuan penggunaan membaca kontrak ini sebelum memuat kode runtime, lalu memverifikasi kedua hook setelah hanya memuat pemilik yang dideklarasikan.

Penyedia embedding umum sebaiknya mendeklarasikan contracts.embeddingProviders untuk setiap adaptor yang didaftarkan dengan api.registerEmbeddingProvider(...). Gunakan kontrak umum untuk pembuatan vektor yang dapat digunakan kembali, termasuk penyedia yang digunakan oleh pencarian memori. contracts.memoryEmbeddingProviders adalah kompatibilitas khusus memori yang sudah tidak digunakan dan hanya dipertahankan selama penyedia yang ada bermigrasi ke celah penyedia embedding generik.

Penyedia pekerja harus mendeklarasikan setiap ID api.registerWorkerProvider(...) dalam contracts.workerProviders. Core menyimpan maksud yang persisten sebelum memanggil provision; penyedia memvalidasi pengaturannya sebelum alokasi eksternal, dan pemanggilan berulang dengan ID operasi yang sama harus menggunakan sewa yang sama. Core juga menyimpan snapshot pengaturan tervalidasi tersebut dan meneruskannya bersama leaseId ke inspect({ leaseId, profile }) dan destroy({ leaseId, profile }), termasuk setelah profil bernama diubah atau dihapus. Penghancuran bersifat idempoten, pemeriksaan mengembalikan union status tertutup active / destroyed / unknown, dan materi kunci privat SSH hanya direferensikan melalui SecretRef. Endpoint SSH yang disediakan juga harus menyertakan hostKey publik dari keluaran penyediaan tepercaya dalam format persis algorithm base64, tanpa nama host atau komentar, agar core dapat menyematkan host sebelum terhubung. Penyedia yang membuat referensi identitas dinamis dapat mengimplementasikan resolveSshIdentity({ leaseId, profile, keyRef }) yang otoritatif; penyedia tanpa implementasi tersebut menggunakan resolver rahasia generik milik core. Status unknown yang otoritatif menjadikan rekaman lokal aktif sebagai yatim; setelah permintaan penghancuran disimpan, status tersebut mengonfirmasi pembongkaran.

contracts.gatewayMethodDispatch saat ini menerima "authenticated-request". Ini adalah gerbang kebersihan API untuk rute HTTP plugin native yang sengaja mengeksekusi metode bidang kontrol Gateway dalam proses, bukan sandbox terhadap plugin native berbahaya. Gunakan hanya untuk permukaan bawaan/operator yang ditinjau secara ketat dan sudah memerlukan autentikasi HTTP Gateway. Rute yang memiliki hak akses tetap dapat dijangkau saat penerimaan pekerjaan root Gateway ditutup hanya jika rute tersebut juga mendeklarasikan auth: "gateway" dan gatewayRuntimeScopeSurface: "trusted-operator" khusus rute; rute saudara biasa dari plugin yang sama tetap berada di balik batas penerimaan. Hal ini menjaga status penangguhan dan fungsi melanjutkan tetap dapat dijangkau tanpa memberikan bypass penerimaan kepada seluruh plugin. Jaga agar penguraian dan pembentukan respons tetap terbatas di luar eksekusi; pekerjaan substantif atau yang mengubah harus melalui eksekusi metode Gateway, yang memiliki penerapan penerimaan dan cakupan.

Referensi configContracts

Gunakan configContracts untuk perilaku konfigurasi milik manifes yang diperlukan helper core generik tanpa mengimpor runtime plugin: deteksi flag berbahaya, target migrasi SecretRef, dan penyempitan jalur konfigurasi lama.

{  "configContracts": {    "compatibilityMigrationPaths": ["legacyProvider"],    "compatibilityRuntimePaths": ["legacyProvider.webhook"],    "dangerousFlags": [      {        "path": "accounts.*.allowUnverifiedSenders",        "equals": true      }    ],    "secretInputs": {      "bundledDefaultEnabled": false,      "paths": [        {          "path": "apiKey",          "expected": "string"        }      ]    }  }}

Setiap entri dangerousFlags mendukung:

secretInputs mendukung:

Referensi mediaUnderstandingProviderMetadata

Gunakan mediaUnderstandingProviderMetadata jika penyedia pemahaman media memiliki model default, prioritas fallback autentikasi otomatis, atau dukungan dokumen native yang diperlukan pembantu inti generik sebelum runtime dimuat. Kunci juga harus dideklarasikan dalam contracts.mediaUnderstandingProviders.

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

Setiap entri penyedia dapat mencakup:

Referensi channelConfigs

Gunakan channelConfigs jika Plugin saluran memerlukan metadata konfigurasi ringan sebelum runtime dimuat. Penemuan penyiapan/status saluran hanya-baca dapat langsung menggunakan metadata ini untuk saluran eksternal yang telah dikonfigurasi ketika tidak tersedia entri penyiapan, atau ketika setup.requiresRuntime: false menyatakan runtime penyiapan tidak diperlukan.

channelConfigs adalah metadata manifes Plugin, bukan bagian konfigurasi pengguna tingkat atas yang baru. Pengguna tetap mengonfigurasi instans saluran di bawah channels.<channel-id>. OpenClaw membaca metadata manifes untuk menentukan Plugin yang memiliki saluran terkonfigurasi tersebut sebelum kode runtime Plugin dijalankan.

Untuk Plugin saluran, configSchema dan channelConfigs menjelaskan jalur yang berbeda:

• configSchema memvalidasi plugins.entries.<plugin-id>.config
• channelConfigs.<channel-id>.schema memvalidasi channels.<channel-id>

Plugin yang tidak dibundel dan mendeklarasikan channels[] juga harus mendeklarasikan entri channelConfigs yang sesuai. Tanpanya, OpenClaw tetap dapat memuat Plugin, tetapi skema konfigurasi jalur dingin, penyiapan, dan permukaan UI Kontrol tidak dapat mengetahui bentuk opsi milik saluran hingga runtime Plugin dijalankan.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled dan nativeSkillsAutoEnabled dapat mendeklarasikan default auto statis untuk pemeriksaan konfigurasi perintah yang berjalan sebelum runtime saluran dimuat. Saluran bawaan juga dapat menerbitkan default yang sama melalui package.json#openclaw.channel.commands bersama metadata katalog saluran lainnya yang dimiliki paket.

{  "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"]    }  }}

Setiap entri saluran dapat mencakup:

Menggantikan Plugin saluran lain

Gunakan preferOver jika Plugin Anda merupakan pemilik yang diutamakan untuk ID saluran yang juga dapat disediakan oleh Plugin lain. Kasus yang umum adalah ID Plugin yang diubah namanya, Plugin mandiri yang menggantikan Plugin bawaan, atau fork terpelihara yang mempertahankan ID saluran yang sama demi kompatibilitas konfigurasi.

{  "id": "acme-chat",  "channels": ["chat"],  "channelConfigs": {    "chat": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "webhookUrl": { "type": "string" }        }      },      "preferOver": ["chat"]    }  }}

Ketika channels.chat dikonfigurasi, OpenClaw mempertimbangkan ID saluran dan ID Plugin yang diutamakan. Jika Plugin berprioritas lebih rendah hanya dipilih karena dibundel atau diaktifkan secara default, OpenClaw menonaktifkannya dalam konfigurasi runtime efektif agar satu Plugin memiliki saluran beserta alatnya. Pemilihan eksplisit pengguna tetap diutamakan: jika pengguna secara eksplisit mengaktifkan kedua Plugin (melalui plugins.allow atau konfigurasi plugins.entries yang nyata), OpenClaw mempertahankan pilihan tersebut dan melaporkan diagnostik duplikasi saluran/alat, alih-alih diam-diam mengubah kumpulan Plugin yang diminta.

Batasi cakupan preferOver pada ID Plugin yang benar-benar dapat menyediakan saluran yang sama. Ini bukan bidang prioritas umum dan tidak mengubah nama kunci konfigurasi pengguna.

Referensi modelSupport

Gunakan modelSupport jika OpenClaw harus menyimpulkan Plugin penyedia Anda dari ID model singkat seperti gpt-5.6-sol atau claude-sonnet-4.6 sebelum runtime Plugin dimuat.

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

OpenClaw menerapkan urutan prioritas berikut:

• referensi provider/model eksplisit menggunakan metadata manifes providers milik penyedia
• modelPatterns mengalahkan modelPrefixes
• jika satu Plugin yang tidak dibundel dan satu Plugin bawaan sama-sama cocok, Plugin yang tidak dibundel menang
• ambiguitas yang tersisa diabaikan hingga pengguna atau konfigurasi menentukan penyedia

Bidang:

Entri modelPatterns dikompilasi melalui compileSafeRegex, yang menolak pola berisi pengulangan bersarang (misalnya (a+)+$). Pola yang gagal dalam pemeriksaan keamanan dilewati tanpa pemberitahuan, sama seperti regex yang secara sintaksis tidak valid. Buat pola tetap sederhana dan hindari kuantifier bersarang.

Referensi modelCatalog

Gunakan modelCatalog jika OpenClaw harus mengetahui metadata model penyedia sebelum memuat runtime Plugin. Ini adalah sumber milik manifes untuk baris katalog tetap, alias penyedia, aturan penyembunyian, dan mode penemuan. Penyegaran runtime tetap menjadi tanggung jawab kode runtime penyedia, tetapi manifes memberi tahu inti kapan runtime diperlukan.

{  "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"    }  }}

Bidang tingkat atas:

aliases berperan dalam pencarian kepemilikan penyedia untuk perencanaan katalog model. Target alias harus berupa penyedia tingkat atas yang dimiliki oleh Plugin yang sama. Ketika daftar yang difilter berdasarkan penyedia menggunakan alias, OpenClaw dapat membaca manifes pemilik dan menerapkan penggantian API/URL dasar alias tanpa memuat runtime penyedia. Alias tidak memperluas daftar katalog tanpa filter; daftar luas hanya menghasilkan baris penyedia kanonis milik pemilik.

suppressions menggantikan hook runtime penyedia suppressBuiltInModel yang lama. Entri penyembunyian hanya diterapkan jika penyedia dimiliki oleh Plugin atau dideklarasikan sebagai kunci modelCatalog.aliases yang menargetkan penyedia milik Plugin. Hook penyembunyian runtime tidak lagi dipanggil selama resolusi model.

Bidang penyedia:

Bidang model:

Bidang penyembunyian:

Jangan masukkan data khusus runtime ke dalam modelCatalog. Gunakan static hanya jika baris manifes cukup lengkap agar daftar yang difilter berdasarkan penyedia dan permukaan pemilih dapat melewati penemuan registri/runtime. Gunakan refreshable jika baris manifes berguna sebagai benih yang dapat dicantumkan atau sebagai pelengkap, tetapi penyegaran/cache dapat menambahkan lebih banyak baris nanti; baris yang dapat disegarkan tidak bersifat otoritatif dengan sendirinya. Gunakan runtime jika OpenClaw harus memuat runtime penyedia untuk mengetahui daftar tersebut.

Referensi modelIdNormalization

Gunakan modelIdNormalization untuk pembersihan id model milik penyedia yang ringan dan harus terjadi sebelum runtime penyedia dimuat. Hal ini mempertahankan alias seperti nama model singkat, id lama lokal penyedia, dan aturan prefiks proksi dalam manifes Plugin pemilik, bukan dalam tabel pemilihan model inti.

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

Bidang penyedia:

Referensi providerEndpoints

Gunakan providerEndpoints untuk klasifikasi titik akhir yang harus diketahui oleh kebijakan permintaan generik sebelum runtime penyedia dimuat. Inti tetap menentukan arti setiap endpointClass; manifes Plugin menentukan metadata host dan URL dasar.

Plugin penyedia yang secara resmi dieksternalisasi dikecualikan dari distribusi inti, sehingga manifesnya tidak terlihat hingga diinstal. providerEndpoints miliknya juga harus dicerminkan dalam scripts/lib/official-external-provider-catalog.json agar klasifikasi titik akhir tetap berfungsi tanpa Plugin tersebut; pengujian kontrak memastikan pencerminan ini.

Bidang titik akhir:

Referensi providerRequest

Gunakan providerRequest untuk metadata kompatibilitas permintaan yang ringan dan diperlukan oleh kebijakan permintaan generik tanpa memuat runtime penyedia. Pertahankan penulisan ulang muatan yang spesifik terhadap perilaku di hook runtime penyedia atau pembantu bersama keluarga penyedia.

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

Bidang penyedia:

Referensi secretProviderIntegrations

Gunakan secretProviderIntegrations ketika sebuah plugin dapat menerbitkan preset penyedia eksekusi SecretRef yang dapat digunakan kembali. OpenClaw membaca metadata ini sebelum runtime plugin dimuat, menyimpan kepemilikan plugin di secrets.providers.<alias>.pluginIntegration, dan menyerahkan resolusi rahasia aktual kepada runtime SecretRef. Preset hanya diekspos untuk plugin bawaan dan plugin terinstal yang ditemukan dari akar instalasi plugin terkelola, seperti instalasi git dan ClawHub.

{  "secretProviderIntegrations": {    "secret-store": {      "providerAlias": "team-secrets",      "displayName": "Team secrets",      "source": "exec",      "command": "${node}",      "args": ["./bin/resolve-secrets.mjs"]    }  }}

Kunci peta adalah id integrasi. Jika providerAlias dihilangkan, OpenClaw menggunakan id integrasi sebagai alias penyedia SecretRef. Alias penyedia harus cocok dengan pola alias penyedia SecretRef yang normal, misalnya team-secrets atau onepassword-work.

Ketika operator memilih preset, OpenClaw menulis referensi penyedia seperti:

{  "secrets": {    "providers": {      "team-secrets": {        "source": "exec",        "pluginIntegration": {          "pluginId": "acme-secrets",          "integrationId": "secret-store"        }      }    }  }}

Saat mulai/muat ulang, OpenClaw menyelesaikan penyedia tersebut dengan memuat metadata manifes plugin saat ini, memeriksa bahwa plugin pemilik terinstal dan aktif, serta mewujudkan perintah eksekusi dari manifes. Menonaktifkan atau menghapus plugin mencabut penyedia untuk SecretRef yang aktif. Operator yang menginginkan konfigurasi eksekusi mandiri tetap dapat menulis penyedia command/args manual secara langsung.

Saat ini hanya preset source: "exec" yang didukung. command harus berupa ${node}, dan args[0] harus berupa skrip penyelesai relatif terhadap akar plugin yang diawali ./. OpenClaw mewujudkannya saat mulai/muat ulang menjadi executable Node saat ini dan jalur absolut skrip di dalam plugin. Opsi Node seperti --require, --import, --loader, --env-file, --eval, dan --print bukan bagian dari kontrak preset manifes. Operator yang memerlukan perintah non-Node dapat mengonfigurasi penyedia eksekusi manual mandiri secara langsung.

OpenClaw menurunkan trustedDirs untuk preset manifes dari akar plugin dan, untuk preset ${node}, direktori executable Node saat ini. trustedDirs yang ditulis dalam manifes diabaikan. Opsi penyedia eksekusi lainnya seperti timeoutMs, noOutputTimeoutMs, maxOutputBytes, jsonOnly, env, passEnv, dan allowInsecurePath diteruskan ke konfigurasi penyedia eksekusi SecretRef normal.

Referensi modelPricing

Gunakan modelPricing ketika penyedia memerlukan perilaku penetapan harga bidang kontrol sebelum runtime dimuat. Cache penetapan harga Gateway membaca metadata ini tanpa mengimpor kode runtime penyedia.

{  "providers": ["ollama", "openrouter"],  "modelPricing": {    "providers": {      "ollama": {        "external": false      },      "openrouter": {        "openRouter": {          "passthroughProviderModel": true        },        "liteLLM": false      }    }  }}

Bidang penyedia:

Bidang sumber:

Indeks Penyedia OpenClaw

Indeks Penyedia OpenClaw adalah metadata pratinjau milik OpenClaw untuk penyedia yang pluginnya mungkin belum terinstal. Ini bukan bagian dari manifes plugin. Manifes plugin tetap menjadi otoritas untuk plugin terinstal. Indeks Penyedia adalah kontrak fallback internal yang akan digunakan oleh antarmuka penyedia yang dapat diinstal dan pemilih model pra-instalasi di masa mendatang ketika plugin penyedia belum terinstal.

Urutan otoritas katalog:

1. Konfigurasi pengguna.
2. modelCatalog manifes plugin terinstal.
3. Cache katalog model dari penyegaran eksplisit.
4. Baris pratinjau Indeks Penyedia OpenClaw.

Indeks Penyedia tidak boleh memuat rahasia, status aktif, hook runtime, atau data model langsung yang spesifik untuk akun. Katalog pratinjaunya menggunakan bentuk baris penyedia modelCatalog yang sama seperti manifes plugin, tetapi harus dibatasi pada metadata tampilan yang stabil kecuali bidang adaptor runtime seperti api, baseUrl, harga, atau flag kompatibilitas sengaja dijaga tetap selaras dengan manifes plugin terinstal. Penyedia dengan penemuan /models langsung harus menulis baris yang disegarkan melalui jalur cache katalog model eksplisit alih-alih membuat pencantuman normal atau orientasi awal memanggil API penyedia.

Entri Indeks Penyedia juga dapat membawa metadata plugin yang dapat diinstal untuk penyedia yang pluginnya telah dipindahkan keluar dari inti atau belum terinstal karena alasan lain. Metadata ini mencerminkan pola katalog saluran: nama paket, spesifikasi instalasi npm, integritas yang diharapkan, dan label pilihan autentikasi ringan sudah cukup untuk menampilkan opsi penyiapan yang dapat diinstal. Setelah plugin terinstal, manifesnya menjadi acuan dan entri Indeks Penyedia diabaikan untuk penyedia tersebut.

openclaw doctor --fix memigrasikan sekumpulan kecil dan tertutup kunci kemampuan manifes tingkat atas lama ke dalam contracts.*: speechProviders, mediaUnderstandingProviders, imageGenerationProviders, dan tools. Tidak satu pun dari kunci ini (atau daftar kemampuan lainnya) yang dibaca sebagai bidang manifes tingkat atas lagi; pemuatan manifes normal hanya mengenalinya di bawah contracts.

Manifes dibandingkan dengan package.json

Kedua berkas tersebut memiliki fungsi berbeda:

Jika Anda tidak yakin di mana suatu metadata seharusnya ditempatkan, gunakan aturan ini:

• jika OpenClaw harus mengetahuinya sebelum memuat kode plugin, letakkan di openclaw.plugin.json
• jika berkaitan dengan pengemasan, berkas entri, atau perilaku instalasi npm, letakkan di package.json

Bidang package.json yang memengaruhi penemuan

Sebagian metadata plugin pra-runtime sengaja berada di package.json di bawah blok openclaw, bukan di openclaw.plugin.json. openclaw.bundle dan openclaw.bundle.json bukan kontrak plugin OpenClaw; plugin native harus menggunakan openclaw.plugin.json beserta bidang package.json#openclaw yang didukung di bawah ini.

Contoh penting:

Metadata manifes menentukan pilihan penyedia/kanal/penyiapan yang muncul dalam orientasi awal sebelum runtime dimuat. package.json#openclaw.install memberi tahu orientasi awal cara mengambil atau mengaktifkan plugin tersebut ketika pengguna memilih salah satu pilihan itu. Jangan pindahkan petunjuk instalasi ke openclaw.plugin.json.

openclaw.install.minHostVersion diberlakukan selama instalasi dan pemuatan registri manifes untuk sumber plugin nonbawaan. Nilai yang tidak valid ditolak; nilai yang lebih baru tetapi valid menyebabkan plugin eksternal dilewati pada host yang lebih lama. Plugin sumber bawaan diasumsikan memiliki versi yang sama dengan checkout host.

openclaw.install.requiredPlatformPackages ditujukan untuk paket npm yang menyediakan biner native wajib melalui alias opsional khusus platform. Cantumkan nama paket npm tanpa tambahan untuk setiap alias platform yang didukung. Selama instalasi npm, OpenClaw hanya memverifikasi alias yang dideklarasikan dan batasan lockfile-nya cocok dengan host saat ini. Jika npm melaporkan keberhasilan tetapi menghilangkan alias tersebut, OpenClaw mencoba kembali satu kali dengan cache baru dan membatalkan instalasi jika alias tersebut masih tidak ada.

openclaw.compat.pluginApi diberlakukan selama instalasi paket untuk sumber plugin nonbawaan. Gunakan ini untuk batas bawah API SDK/runtime plugin OpenClaw yang menjadi dasar build paket. Nilainya dapat lebih ketat daripada minHostVersion ketika suatu paket plugin memerlukan API yang lebih baru, tetapi tetap mempertahankan petunjuk instalasi yang lebih rendah untuk alur lain. Sinkronisasi rilis resmi OpenClaw secara default menaikkan batas bawah API plugin resmi yang sudah ada ke versi rilis OpenClaw, tetapi rilis khusus plugin dapat mempertahankan batas bawah yang lebih rendah ketika paket tersebut sengaja mendukung host yang lebih lama. Jangan gunakan versi paket saja sebagai kontrak kompatibilitas. peerDependencies.openclaw tetap merupakan metadata paket npm; OpenClaw menggunakan kontrak openclaw.compat.pluginApi untuk keputusan kompatibilitas instalasi.

Metadata resmi instalasi sesuai permintaan harus menggunakan clawhubSpec ketika plugin dipublikasikan di ClawHub; orientasi awal memperlakukannya sebagai sumber jarak jauh pilihan dan mencatat fakta artefak ClawHub setelah instalasi. npmSpec tetap menjadi fallback kompatibilitas bagi paket yang belum dipindahkan ke ClawHub.

Penyematan versi npm yang tepat sudah berada dalam npmSpec, misalnya "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Entri katalog eksternal resmi harus memasangkan spesifikasi yang tepat dengan expectedIntegrity agar alur pembaruan gagal secara tertutup jika artefak npm yang diambil tidak lagi cocok dengan rilis yang disematkan. Orientasi awal interaktif tetap menawarkan spesifikasi npm dari registri tepercaya, termasuk nama paket tanpa tambahan dan dist-tag, demi kompatibilitas. Diagnostik katalog dapat membedakan sumber versi tepat, mengambang, disematkan-integritas, tanpa-integritas, ketidakcocokan nama paket, dan pilihan default yang tidak valid. Diagnostik tersebut juga memperingatkan ketika expectedIntegrity ada tetapi tidak terdapat sumber npm valid yang dapat disematkannya. Ketika expectedIntegrity ada, alur instalasi/pembaruan memberlakukannya; ketika tidak disertakan, resolusi registri dicatat tanpa penyematan integritas.

Plugin kanal harus menyediakan openclaw.setupEntry ketika pemindaian status, daftar kanal, atau SecretRef perlu mengidentifikasi akun yang terkonfigurasi tanpa memuat runtime secara lengkap. Titik masuk penyiapan harus mengekspos metadata kanal beserta adaptor konfigurasi, status, dan rahasia yang aman untuk penyiapan; pertahankan klien jaringan, pendengar Gateway, dan runtime transportasi di titik masuk ekstensi utama.

Bidang titik masuk runtime tidak mengesampingkan pemeriksaan batas paket untuk bidang titik masuk sumber. Misalnya, openclaw.runtimeExtensions tidak dapat membuat jalur openclaw.extensions yang keluar dari batas menjadi dapat dimuat.

openclaw.install.allowInvalidConfigRecovery sengaja dibatasi. Opsi ini tidak membuat konfigurasi rusak sembarang menjadi dapat diinstal. Saat ini, opsi tersebut hanya memungkinkan alur instalasi pulih dari kegagalan peningkatan plugin bawaan tertentu yang sudah usang, seperti jalur plugin bawaan yang tidak ada atau entri channels.<id> usang untuk plugin bawaan yang sama. Kesalahan konfigurasi yang tidak terkait tetap memblokir instalasi dan mengarahkan operator ke openclaw doctor --fix.

openclaw.channel.persistedAuthState adalah metadata paket untuk modul pemeriksa kecil:

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

Gunakan ketika alur penyiapan, doctor, status, atau pemeriksaan keberadaan hanya-baca memerlukan pemeriksaan autentikasi ya/tidak yang ringan sebelum plugin kanal dimuat secara lengkap. Status autentikasi tersimpan bukanlah status kanal terkonfigurasi: jangan gunakan metadata ini untuk mengaktifkan plugin secara otomatis, memperbaiki dependensi runtime, atau menentukan apakah runtime kanal harus dimuat. Ekspor target harus berupa fungsi kecil yang hanya membaca status tersimpan; jangan arahkan melalui barrel runtime kanal lengkap.

openclaw.channel.configuredState mengikuti bentuk yang sama untuk pemeriksaan ringan konfigurasi hanya melalui env:

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

Gunakan ketika kanal dapat menentukan status terkonfigurasi dari env atau masukan kecil non-runtime lainnya. Jika pemeriksaan memerlukan resolusi konfigurasi lengkap atau runtime kanal sebenarnya, pertahankan logika tersebut dalam hook config.hasConfiguredState plugin.

Prioritas penemuan (ID plugin duplikat)

OpenClaw menemukan plugin dari tiga akar, yang diperiksa dalam urutan berikut: plugin bawaan yang disertakan bersama OpenClaw, akar instalasi global (~/.openclaw/extensions), dan akar ruang kerja saat ini (<workspace>/.openclaw/extensions), ditambah setiap entri eksplisit plugins.load.paths.

Jika dua hasil penemuan memiliki id yang sama, hanya manifes dengan prioritas tertinggi yang dipertahankan; duplikat dengan prioritas lebih rendah dibuang alih-alih dimuat berdampingan. Urutan prioritas, dari tertinggi hingga terendah:

1. Dipilih konfigurasi — jalur yang disematkan secara eksplisit dalam plugins.entries.<id>
2. Instalasi global yang cocok dengan catatan instalasi terlacak — plugin yang diinstal melalui openclaw plugin install/openclaw plugin update dan dikenali oleh pelacakan instalasi OpenClaw untuk ID yang sama, bahkan ketika ID tersebut juga dimiliki plugin bawaan
3. Bawaan — plugin yang disertakan bersama OpenClaw
4. Ruang kerja — plugin yang ditemukan relatif terhadap ruang kerja saat ini
5. Kandidat lain yang ditemukan

Implikasi:

• Salinan bercabang atau usang dari plugin bawaan yang berada tanpa pelacakan di ruang kerja atau akar global tidak akan membayangi build bawaan.
• Untuk menggantikan plugin bawaan, jalankan openclaw plugin install untuk ID tersebut agar instalasi global terlacak mengungguli salinan bawaan, atau sematkan jalur tertentu melalui plugins.entries.<id> agar jalur tersebut menang berdasarkan prioritas pilihan konfigurasi.
• Pembuangan duplikat dicatat dalam log agar Doctor dan diagnostik startup dapat menunjuk ke salinan yang dibuang.
• Penggantian duplikat pilihan konfigurasi disebut sebagai penggantian eksplisit dalam diagnostik, tetapi tetap menghasilkan peringatan agar fork usang dan pembayangan tidak disengaja tetap terlihat.

Persyaratan JSON Schema

• Setiap plugin harus menyertakan JSON Schema, meskipun tidak menerima konfigurasi.
• Skema kosong dapat diterima (misalnya, { "type": "object", "additionalProperties": false }).
• Skema divalidasi saat konfigurasi dibaca/ditulis, bukan saat runtime.
• Saat memperluas atau melakukan fork pada plugin bawaan dengan kunci konfigurasi baru, perbarui configSchema dalam openclaw.plugin.json milik plugin tersebut secara bersamaan. Skema plugin bawaan bersifat ketat, sehingga menambahkan plugins.entries.<id>.config.myNewKey dalam konfigurasi pengguna tanpa menambahkan myNewKey ke configSchema.properties akan ditolak sebelum runtime plugin dimuat.

Contoh perluasan skema:

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

Perilaku validasi

• Kunci channels.* yang tidak dikenal merupakan kesalahan, kecuali ID channel dideklarasikan oleh manifes plugin. Jika ID yang sama juga muncul dalam plugins.allow, plugins.entries, atau plugins.installs (plugin yang dirujuk tetapi saat ini tidak dapat ditemukan), OpenClaw menurunkan tingkat masalah ini menjadi peringatan.
• plugins.entries.<id>, plugins.allow, dan plugins.deny yang merujuk ke ID plugin yang tidak dikenal merupakan peringatan ("entri konfigurasi usang diabaikan"), bukan kesalahan, sehingga peningkatan versi dan plugin yang dihapus/diubah namanya tidak menghalangi Gateway untuk dimulai.
• plugins.slots.memory yang merujuk ke ID plugin yang tidak dikenal merupakan kesalahan, kecuali untuk plugin eksternal resmi memory-lancedb yang telah dikenal, yang hanya menghasilkan peringatan.
• Jika plugin telah terpasang tetapi manifes atau skemanya rusak atau tidak ada, validasi gagal dan Doctor melaporkan kesalahan plugin tersebut.
• Jika konfigurasi plugin tersedia tetapi plugin dinonaktifkan, konfigurasi tersebut dipertahankan dan peringatan ditampilkan di Doctor serta log.

Lihat Referensi konfigurasi untuk skema plugins.* selengkapnya.

Catatan

• Manifes diwajibkan untuk plugin asli OpenClaw, termasuk pemuatan dari sistem berkas lokal. Runtime tetap memuat modul plugin secara terpisah; manifes hanya digunakan untuk penemuan dan validasi.
• Manifes asli diuraikan dengan JSON5, sehingga komentar, koma di akhir, dan kunci tanpa tanda kutip dapat diterima selama nilai akhirnya tetap berupa objek.
• Hanya kolom manifes yang terdokumentasi yang dibaca oleh pemuat manifes. Hindari kunci tingkat atas khusus.
• channels, providers, cliBackends, dan skills semuanya dapat dihilangkan jika plugin tidak memerlukannya.
• providerCatalogEntry harus tetap ringan dan tidak boleh mengimpor kode runtime yang luas; gunakan untuk metadata katalog penyedia statis atau deskriptor penemuan terbatas, bukan untuk eksekusi pada saat permintaan.
• Jenis plugin eksklusif dipilih melalui plugins.slots.*: kind: "memory" melalui plugins.slots.memory (default memory-core), dan kind: "context-engine" melalui plugins.slots.contextEngine (default legacy).
• Deklarasikan jenis plugin eksklusif dalam manifes ini. OpenClawPluginDefinition.kind pada entri runtime sudah tidak dianjurkan dan tetap tersedia hanya sebagai mekanisme kompatibilitas cadangan untuk plugin lama.
• Metadata variabel lingkungan (setup.providers[].envVars, providerAuthEnvVars yang sudah tidak dianjurkan, dan channelEnvVars) hanya bersifat deklaratif. Status, audit, validasi pengiriman Cron, dan permukaan baca-saja lainnya tetap menerapkan kebijakan kepercayaan plugin dan aktivasi efektif sebelum menganggap suatu variabel lingkungan telah dikonfigurasi.
• Untuk metadata wisaya runtime yang memerlukan kode penyedia, lihat Hook runtime penyedia.
• Jika plugin Anda bergantung pada modul native, dokumentasikan langkah-langkah build dan semua persyaratan daftar izin pengelola paket (misalnya, allow-build-scripts pnpm + pnpm rebuild <package>).

Terkait