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 default 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, default settings.json Claude, default 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 memblokir validasi konfigurasi dan diperlakukan sebagai kesalahan plugin.

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

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 memulai 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 permukaan bidang kontrol
• kepemilikan keluarga model dalam bentuk singkat
• snapshot kepemilikan kapabilitas statis (contracts)
• metadata runner QA yang dapat diperiksa oleh host openclaw qa bersama
• metadata konfigurasi khusus saluran yang digabungkan ke dalam permukaan katalog dan 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": "Plugin penyedia OpenRouter",  "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"  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "Kunci API OpenRouter",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "Kunci API OpenRouter",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "Kunci API",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

Referensi bidang tingkat atas

referensi katalog

catalog menyediakan petunjuk tampilan opsional untuk peramban plugin. Host dapat mengabaikan petunjuk ini. Petunjuk ini tidak pernah menginstal atau mengaktifkan plugin, dan 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 murah. Transportasi, transformasi permintaan, penyegaran token, validasi kredensial, dan perilaku pembuatan aktual tetap berada di 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 pengaman mode mendukung:

Setiap entri authSignals mendukung:

Setiap pengaman 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 murah agar OpenClaw dapat menghindari pengimporan runtime plugin hanya untuk membuat pabrik alatnya mengembalikan null.

{  "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 alat tidak memiliki toolMetadata, OpenClaw mempertahankan perilaku yang ada dan memuat plugin pemilik ketika kontrak alat cocok dengan kebijakan. Untuk alat jalur panas yang pabriknya bergantung pada autentikasi/konfigurasi, penulis plugin harus mendeklarasikan toolMetadata, alih-alih membuat inti mengimpor runtime untuk menanyakannya.

Referensi providerAuthChoices

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

Jika appGuidedDiscovery bernilai true, metode autentikasi penyedia yang cocok harus menyediakan appGuidedSetup.detect dan appGuidedSetup.prepare. Deteksi harus hanya-baca: tanpa login, penarikan model, unduhan, atau penulisan konfigurasi. Persiapan memeriksa ulang model persis yang dipilih dan mengembalikan usulan konfigurasi; OpenClaw menguji langsung usulan tersebut secara terisolasi dan menerapkannya hanya setelah berhasil.

Referensi commandAliases

Gunakan commandAliases ketika sebuah plugin memiliki nama perintah runtime yang mungkin keliru dimasukkan pengguna ke dalam plugins.allow atau coba 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 aktivasi

Gunakan activation ketika plugin dapat dengan mudah mendeklarasikan peristiwa bidang kontrol mana 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 plugin kandidat 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 menetapkan activation.onStartup secara sengaja. Tetapkan ke true hanya jika plugin harus berjalan selama startup Gateway. Tetapkan ke false jika plugin tidak aktif saat startup dan hanya boleh dimuat dari pemicu yang lebih sempit. Tidak mencantumkan onStartup tidak lagi memuat plugin secara implisit saat startup; gunakan metadata aktivasi eksplisit untuk pemicu aktivasi startup, saluran, konfigurasi, harness agen, memori, atau pemicu lain yang lebih sempit.

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

Konsumen aktif saat ini:

• Perencanaan startup Gateway menggunakan activation.onStartup untuk impor startup eksplisit.
• Perencanaan CLI yang dipicu perintah kembali menggunakan commandAliases[].cliCommand atau commandAliases[].name lama.
• Perencanaan startup runtime agen menggunakan activation.onAgentHarnesses untuk harness tersemat dan cliBackends[] tingkat atas untuk alias runtime CLI.
• Perencanaan penyiapan/channel yang dipicu channel kembali menggunakan kepemilikan channels[] lama ketika metadata aktivasi channel eksplisit tidak tersedia.
• Perencanaan Plugin startup menggunakan activation.onConfigPaths untuk permukaan konfigurasi root non-channel, seperti blok browser milik Plugin browser 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 fallback 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; pembuat Plugin harus tetap mendeklarasikan metadata yang paling tepat menggambarkan kepemilikan.

Referensi qaRunners

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

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Jalankan jalur QA langsung Matrix berbasis Docker terhadap homeserver sekali pakai"    }  ]}

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

Referensi setup

Gunakan setup ketika permukaan penyiapan dan orientasi memerlukan metadata ringan 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": "kredensial lokal openai"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

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

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

OpenClaw menyertakan setup.providers[].envVars dalam pencarian autentikasi penyedia dan variabel lingkungan generik. Tempatkan metadata lingkungan penyiapan dan status di sana.

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 di dalam resolveUsageAuth.

OpenClaw juga dapat memperoleh pilihan penyiapan sederhana dari setup.providers[].authMethods ketika entri penyiapan tidak tersedia, atau ketika setup.requiresRuntime: false menyatakan 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 permukaan penyiapan. OpenClaw memperlakukan false eksplisit sebagai kontrak khusus deskriptor dan tidak akan menjalankan 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 tetap mengabaikannya. requiresRuntime yang dihilangkan mempertahankan perilaku fallback 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 dinormalisasi harus tetap unik di antara Plugin yang ditemukan. Kepemilikan ambigu gagal secara tertutup 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 registrasi runtime yang sesuai. 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 ringan dan lokal: tanpa panggilan jaringan, tanpa pembacaan keychain 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 kecil. Kunci dapat menggunakan titik untuk bidang konfigurasi bertingkat, tetapi tidak ada segmen jalur yang boleh berupa __proto__, constructor, atau prototype; penyiapan menolak nama-nama tersebut.

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

Setiap petunjuk bidang dapat mencakup:

Referensi contracts

Gunakan contracts hanya untuk metadata kepemilikan kapabilitas 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 factory ekstensi bawaan khusus app-server Codex. Transformasi hasil alat bawaan sebaiknya mendeklarasikan contracts.agentToolResultMiddleware dan sebagai gantinya mendaftar dengan api.registerAgentToolResultMiddleware(...). Plugin terinstal hanya dapat menggunakan seam middleware yang sama jika 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 terdaftar dalam contracts.trustedToolPolicies dan diaktifkan secara eksplisit. Plugin bawaan tetap menggunakan jalur kebijakan tepercaya yang sudah ada, tetapi plugin terinstal dengan ID kebijakan yang tidak dideklarasikan akan ditolak sebelum pendaftaran. ID kebijakan dibatasi cakupannya pada plugin yang mendaftarkannya, sehingga dua plugin dapat sama-sama mendeklarasikan dan mendaftarkan workflow-budget; satu plugin tidak boleh mendaftarkan ID lokal yang sama dua kali.

Pendaftaran runtime api.registerTool(...) harus cocok dengan contracts.tools. Penemuan alat menggunakan daftar ini untuk memuat hanya 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 harus 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 tidak digunakan lagi dan hanya dipertahankan selama penyedia yang ada bermigrasi ke seam penyedia embedding generik.

Penyedia pekerja harus mendeklarasikan setiap ID api.registerWorkerProvider(...) dalam contracts.workerProviders. Core menyimpan intensi persisten sebelum memanggil provision; penyedia memvalidasi pengaturannya sebelum alokasi eksternal, dan panggilan berulang dengan ID operasi yang sama harus mengadopsi 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. Pemusnahan bersifat idempoten, inspeksi 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 sebagai tepat algorithm base64, tanpa nama host atau komentar, agar core dapat menyematkan host sebelum terhubung. Penyedia yang menerbitkan referensi identitas dinamis dapat mengimplementasikan resolveSshIdentity({ leaseId, profile, keyRef }) yang otoritatif; penyedia tanpa itu menggunakan resolver rahasia generik milik core. unknown yang otoritatif membuat rekaman lokal aktif menjadi yatim; setelah permintaan pemusnahan disimpan, hook tersebut mengonfirmasi pembongkaran.

contracts.gatewayMethodDispatch saat ini menerima "authenticated-request". Ini adalah gerbang kebersihan API untuk rute HTTP plugin native yang secara sengaja mengirimkan 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 tetap dapat dijangkau ketika 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 penguraian dan pembentukan respons tetap terbatas di luar dispatch; pekerjaan substantif atau yang mengubah keadaan harus melalui dispatch metode Gateway, yang memiliki penegakan 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": "routes.*.secret",          "expected": "string",          "ownerKind": "route"        }      ]    }  }}

Setiap entri dangerousFlags mendukung:

secretInputs mendukung:

Referensi mediaUnderstandingProviderMetadata

Gunakan mediaUnderstandingProviderMetadata ketika 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 ketika plugin saluran memerlukan metadata konfigurasi ringan sebelum runtime dimuat. Penemuan penyiapan/status saluran hanya-baca dapat menggunakan metadata ini secara langsung untuk saluran eksternal yang dikonfigurasi ketika entri penyiapan tidak tersedia, atau ketika setup.requiresRuntime: false menyatakan bahwa 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 nonbawaan yang mendeklarasikan channels[] juga harus mendeklarasikan entri channelConfigs yang sesuai. Tanpanya, OpenClaw masih dapat memuat plugin, tetapi skema konfigurasi jalur dingin, penyiapan, dan permukaan Control UI 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 memublikasikan default yang sama melalui package.json#openclaw.channel.commands bersama metadata katalog saluran milik paket lainnya.

{  "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",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

Setiap entri saluran dapat mencakup:

Menggantikan plugin saluran lain

Gunakan preferOver ketika plugin Anda adalah pemilik pilihan untuk id saluran yang juga dapat disediakan oleh plugin lain. Kasus umum adalah id plugin yang diubah namanya, plugin mandiri yang menggantikan plugin bawaan, atau fork yang dipelihara dan 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 pilihan. Jika plugin berprioritas lebih rendah dipilih hanya karena merupakan bawaan atau diaktifkan secara default, OpenClaw menonaktifkannya dalam konfigurasi runtime efektif sehingga satu plugin memiliki saluran dan alatnya. Pilihan eksplisit pengguna tetap berlaku: jika pengguna secara eksplisit mengaktifkan kedua plugin (melalui plugins.allow atau konfigurasi plugins.entries yang material), OpenClaw mempertahankan pilihan tersebut dan melaporkan diagnostik saluran/alat duplikat 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 mengganti nama kunci konfigurasi pengguna.

Referensi modelSupport

Gunakan modelSupport ketika 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 pemilik
• modelPatterns mengalahkan modelPrefixes
• jika satu plugin nonbawaan dan satu plugin bawaan sama-sama cocok, plugin nonbawaan menang
• ambiguitas yang tersisa diabaikan hingga pengguna atau konfigurasi menentukan penyedia

Bidang:

Entri modelPatterns dikompilasi melalui compileSafeRegex, yang menolak pola yang mengandung pengulangan bersarang (misalnya (a+)+$). Pola yang gagal dalam pemeriksaan keamanan dilewati secara diam-diam, sama seperti regex yang sintaksnya tidak valid. Pertahankan pola tetap sederhana dan hindari kuantifier bersarang.

Referensi modelCatalog

Gunakan modelCatalog ketika 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": "tidak tersedia di Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

Bidang tingkat atas:

aliases berpartisipasi dalam pencarian kepemilikan penyedia untuk perencanaan katalog model. Target alias harus berupa penyedia tingkat teratas 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 suppressBuiltInModel runtime penyedia lama. Entri supresi hanya dipatuhi ketika penyedia dimiliki oleh plugin atau dideklarasikan sebagai kunci modelCatalog.aliases yang menargetkan penyedia milik plugin. Hook supresi runtime tidak lagi dipanggil selama resolusi model.

Bidang penyedia:

Bidang model:

Bidang supresi:

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

Referensi modelIdNormalization

Gunakan modelIdNormalization untuk pembersihan id model milik penyedia yang ringan dan harus dilakukan sebelum runtime penyedia dimuat. Ini mempertahankan alias seperti nama model pendek, 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 endpoint yang harus diketahui oleh kebijakan permintaan generik sebelum runtime penyedia dimuat. Inti tetap memiliki makna setiap endpointClass; manifes plugin memiliki metadata host dan URL dasar.

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

Bidang endpoint:

Referensi providerRequest

Gunakan providerRequest untuk metadata kompatibilitas permintaan yang murah, yang diperlukan kebijakan permintaan generik tanpa memuat runtime penyedia. Pertahankan penulisan ulang payload khusus perilaku dalam hook runtime penyedia atau pembantu keluarga penyedia bersama.

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

Bidang penyedia:

Referensi secretProviderIntegrations

Gunakan secretProviderIntegrations ketika plugin dapat menerbitkan preset penyedia exec 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 sebenarnya kepada runtime SecretRef. Preset hanya diekspos untuk plugin bawaan dan plugin terpasang yang ditemukan dari akar pemasangan plugin terkelola, seperti pemasangan 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 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 telah terpasang dan aktif, serta mewujudkan perintah exec dari manifes. Menonaktifkan atau menghapus plugin mencabut penyedia untuk SecretRef aktif. Operator yang menginginkan konfigurasi exec mandiri tetap dapat menulis penyedia manual command/args secara langsung.

Saat ini hanya preset source: "exec" yang didukung. command harus berupa ${node}, dan args[0] harus berupa skrip penyelesai ./ yang relatif terhadap akar plugin. OpenClaw mewujudkannya saat mulai/muat ulang menjadi executable Node saat ini dan jalur skrip absolut 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 exec manual mandiri secara langsung.

OpenClaw memperoleh trustedDirs untuk preset manifes dari akar plugin dan, untuk preset ${node}, direktori executable Node saat ini. trustedDirs yang ditulis dalam manifes diabaikan. Opsi penyedia exec lainnya seperti timeoutMs, noOutputTimeoutMs, maxOutputBytes, jsonOnly, env, passEnv, dan allowInsecurePath diteruskan ke konfigurasi penyedia exec 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 terpasang. Ini bukan bagian dari manifes plugin. Manifes plugin tetap menjadi otoritas untuk plugin terpasang. Indeks Penyedia adalah kontrak fallback internal yang akan digunakan oleh permukaan pemilih model pra-pemasangan dan penyedia yang dapat dipasang di masa mendatang ketika plugin penyedia belum terpasang.

Urutan otoritas katalog:

1. Konfigurasi pengguna.
2. Manifes plugin terpasang modelCatalog.
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 khusus untuk akun. Katalog pratinjaunya menggunakan bentuk baris penyedia modelCatalog yang sama dengan manifes plugin, tetapi harus tetap terbatas pada metadata tampilan yang stabil, kecuali bidang adaptor runtime seperti api, baseUrl, harga, atau flag kompatibilitas sengaja dipertahankan agar selaras dengan manifes plugin terpasang. 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 dipasang untuk penyedia yang pluginnya telah dipindahkan dari inti atau belum terpasang karena alasan lain. Metadata ini mencerminkan pola katalog saluran: nama paket, spesifikasi pemasangan npm, integritas yang diharapkan, dan label pilihan autentikasi sederhana sudah cukup untuk menampilkan opsi penyiapan yang dapat dipasang. Setelah plugin terpasang, manifesnya akan diutamakan 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) dibaca sebagai bidang manifes tingkat atas lagi; pemuatan manifes normal hanya mengenalinya di bawah contracts.

Manifes dibandingkan dengan package.json

Kedua berkas tersebut menjalankan tugas yang berbeda:

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

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

Bidang package.json yang memengaruhi penemuan

Beberapa metadata plugin pra-runtime sengaja berada di package.json dalam 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/channel/penyiapan yang muncul dalam onboarding sebelum runtime dimuat. package.json#openclaw.install memberi tahu onboarding 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 mengekspos 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 tidak menyertakan alias tersebut, OpenClaw mencoba ulang satu kali dengan cache baru dan membatalkan instalasi jika alias masih tidak tersedia.

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 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 instalasi sesuai permintaan resmi harus menggunakan clawhubSpec ketika plugin dipublikasikan di ClawHub; onboarding memperlakukannya sebagai sumber jarak jauh yang diutamakan dan mencatat fakta artefak ClawHub setelah instalasi. npmSpec tetap menjadi fallback kompatibilitas untuk paket yang belum berpindah ke ClawHub.

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

Plugin channel harus menyediakan openclaw.setupEntry ketika pemindaian status, daftar channel, atau SecretRef perlu mengidentifikasi akun yang terkonfigurasi tanpa memuat runtime lengkap. Entri penyiapan harus mengekspos metadata channel beserta adaptor konfigurasi, status, dan rahasia yang aman untuk penyiapan; pertahankan klien jaringan, listener 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. Ini tidak membuat konfigurasi rusak apa pun menjadi dapat diinstal. Saat ini, ini hanya memungkinkan alur instalasi pulih dari kegagalan peningkatan plugin bawaan usang tertentu, seperti jalur plugin bawaan yang hilang 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 ini ketika alur penyiapan, doctor, status, atau pemeriksaan keberadaan hanya-baca memerlukan probe autentikasi ya/tidak yang ringan sebelum plugin channel lengkap dimuat. Status autentikasi tersimpan bukanlah status channel terkonfigurasi: jangan gunakan metadata ini untuk mengaktifkan plugin secara otomatis, memperbaiki dependensi runtime, atau memutuskan apakah runtime channel harus dimuat. Ekspor target harus berupa fungsi kecil yang hanya membaca status tersimpan; jangan arahkan melalui barrel runtime channel lengkap.

openclaw.channel.configuredState mendukung pemeriksaan terkonfigurasi yang ringan. Utamakan metadata lingkungan deklaratif ketika variabel lingkungan sudah memadai:

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "env": {          "allOf": ["TELEGRAM_BOT_TOKEN"]        }      }    }  }}

Gunakan env.allOf ketika setiap variabel yang tercantum diwajibkan dan env.anyOf ketika salah satu variabel yang tidak kosong sudah cukup. Jika pemeriksaan kecil non-runtime memerlukan lebih dari metadata lingkungan, gunakan specifier beserta exportName seperti ditunjukkan untuk persistedAuthState; ketika env tersedia, OpenClaw menggunakannya tanpa memuat modul tersebut. Jika pemeriksaan memerlukan resolusi konfigurasi lengkap atau runtime channel sebenarnya, pertahankan logika tersebut dalam hook config.hasConfiguredState plugin.

Prioritas penemuan (id plugin duplikat)

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

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

1. Dipilih oleh 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 dilacak di ruang kerja atau root global tidak akan membayangi build bawaan.
• Untuk mengganti Plugin bawaan, jalankan openclaw plugin install untuk id tersebut agar instalasi global yang dilacak memiliki prioritas lebih tinggi daripada salinan bawaan, atau sematkan jalur tertentu melalui plugins.entries.<id> agar jalur tersebut menang berdasarkan prioritas yang dipilih konfigurasi.
• Duplikat yang diabaikan dicatat ke log agar Doctor dan diagnostik startup dapat menunjukkan salinan yang dibuang.
• Penggantian duplikat yang dipilih konfigurasi dinyatakan sebagai penggantian eksplisit dalam diagnostik, tetapi tetap menghasilkan peringatan agar fork usang dan pembayangan yang tidak disengaja tetap terlihat.

Persyaratan JSON Schema

• Setiap Plugin harus menyertakan JSON Schema, meskipun tidak menerima konfigurasi apa pun.
• Skema kosong dapat diterima (misalnya, { "type": "object", "additionalProperties": false }).
• Skema divalidasi saat konfigurasi dibaca/ditulis, bukan saat runtime.
• Saat memperluas atau membuat fork dari Plugin bawaan dengan kunci konfigurasi baru, perbarui openclaw.plugin.json configSchema 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 adalah kesalahan, kecuali id saluran dideklarasikan oleh manifes Plugin. Jika id yang sama juga muncul dalam plugins.allow, plugins.entries, atau plugins.installs (Plugin yang direferensikan tetapi saat ini tidak dapat ditemukan), OpenClaw menurunkannya menjadi peringatan.
• plugins.entries.<id>, plugins.allow, dan plugins.deny yang mereferensikan id Plugin yang tidak dikenal adalah peringatan ("entri konfigurasi usang diabaikan"), bukan kesalahan, sehingga peningkatan versi dan Plugin yang dihapus/diganti namanya tidak memblokir startup Gateway.
• plugins.slots.memory yang mereferensikan id Plugin yang tidak dikenal adalah kesalahan, kecuali untuk Plugin eksternal resmi memory-lancedb yang telah dikenal, yang hanya menghasilkan peringatan.
• Jika Plugin telah diinstal tetapi memiliki manifes atau skema yang rusak atau hilang, validasi gagal dan Doctor melaporkan kesalahan Plugin tersebut.
• Jika konfigurasi Plugin tersedia tetapi Plugin dinonaktifkan, konfigurasi tetap dipertahankan dan peringatan ditampilkan di Doctor + log.

Lihat Referensi konfigurasi untuk skema plugins.* lengkap.

Catatan

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

Terkait