@@ -152,7 +152,7 @@ or npm install metadata. Those belong in your plugin code and `package.json`.
152152| `providerAuthAliases` | No | `Record<string, string>` | Provider ids that should reuse another provider id for auth lookup, for example a coding provider that shares the base provider API key and auth profiles. |
153153| `channelEnvVars` | No | `Record<string, string[]>` | Cheap channel env metadata that OpenClaw can inspect without loading plugin code. Use this for env-driven channel setup or auth surfaces that generic startup/config helpers should see. |
154154| `providerAuthChoices` | No | `object[]` | Cheap auth-choice metadata for onboarding pickers, preferred-provider resolution, and simple CLI flag wiring. |
155-| `activation` | No | `object` | Cheap activation hints for provider, command, channel, route, and capability-triggered loading. Metadata only; plugin runtime still owns actual behavior. |
155+| `activation` | No | `object` | Cheap activation planner metadata for provider, command, channel, route, and capability-triggered loading. Metadata only; plugin runtime still owns actual behavior. |
156156| `setup` | No | `object` | Cheap setup/onboarding descriptors that discovery and setup surfaces can inspect without loading plugin runtime. |
157157| `qaRunners` | No | `object[]` | Cheap QA runner descriptors used by the shared `openclaw qa` host before plugin runtime loads. |
158158| `contracts` | No | `object` | Static bundled capability snapshot for external auth hooks, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search, and tool ownership. |
@@ -215,30 +215,19 @@ uses this metadata for diagnostics without importing plugin runtime code.
215215## activation reference
216216217217Use `activation` when the plugin can cheaply declare which control-plane events
218-should activate it later.
218+should include it in an activation/load plan.
219219220-## qaRunners reference
220+This block is planner metadata, not a lifecycle API. It does not register
221+runtime behavior, does not replace `register(...)`, and does not promise that
222+plugin code has already executed. The activation planner uses these fields to
223+narrow candidate plugins before falling back to existing manifest ownership
224+metadata such as `providers`, `channels`, `commandAliases`, `setup.providers`,
225+`contracts.tools`, and hooks.
221226222-Use `qaRunners` when a plugin contributes one or more transport runners beneath
223-the shared `openclaw qa` root. Keep this metadata cheap and static; the plugin
224-runtime still owns actual CLI registration through a lightweight
225-`runtime-api.ts` surface that exports `qaRunnerCliRegistrations`.
226-227-```json
228-{
229-"qaRunners": [
230- {
231-"commandName": "matrix",
232-"description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
233- }
234- ]
235-}
236-```
237-238-| Field | Required | Type | What it means |
239-| ------------- | -------- | -------- | ------------------------------------------------------------------ |
240-| `commandName` | Yes | `string` | Subcommand mounted beneath `openclaw qa`, for example `matrix`. |
241-| `description` | No | `string` | Fallback help text used when the shared host needs a stub command. |
227+Prefer the narrowest metadata that already describes ownership. Use
228+`providers`, `channels`, `commandAliases`, setup descriptors, or `contracts`
229+when those fields express the relationship. Use `activation` for extra planner
230+hints that cannot be represented by those ownership fields.
242231243232This block is metadata only. It does not register runtime behavior, and it does
244233not replace `register(...)`, `setupEntry`, or other runtime/plugin entrypoints.
@@ -258,13 +247,13 @@ change correctness while legacy manifest ownership fallbacks still exist.
258247}
259248```
260249261-| Field | Required | Type | What it means |
262-| ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
263-| `onProviders` | No | `string[]` | Provider ids that should activate this plugin when requested. |
264-| `onCommands` | No | `string[]` | Command ids that should activate this plugin. |
265-| `onChannels` | No | `string[]` | Channel ids that should activate this plugin. |
266-| `onRoutes` | No | `string[]` | Route kinds that should activate this plugin. |
267-| `onCapabilities` | No | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Broad capability hints used by control-plane activation planning. |
250+| Field | Required | Type | What it means |
251+| ---------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
252+| `onProviders` | No | `string[]` | Provider ids that should include this plugin in activation/load plans. |
253+| `onCommands` | No | `string[]` | Command ids that should include this plugin in activation/load plans. |
254+| `onChannels` | No | `string[]` | Channel ids that should include this plugin in activation/load plans. |
255+| `onRoutes` | No | `string[]` | Route kinds that should include this plugin in activation/load plans. |
256+| `onCapabilities` | No | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Broad capability hints used by control-plane activation planning. Prefer narrower fields when possible. |
268257269258Current live consumers:
270259@@ -276,6 +265,36 @@ Current live consumers:
276265`providers[]` and top-level `cliBackends[]` ownership when explicit provider
277266 activation metadata is missing
278267268+Planner diagnostics can distinguish explicit activation hints from manifest
269+ownership fallback. For example, `activation-command-hint` means
270+`activation.onCommands` matched, while `manifest-command-alias` means the
271+planner used `commandAliases` ownership instead. These reason labels are for
272+host diagnostics and tests; plugin authors should keep declaring the metadata
273+that best describes ownership.
274+275+## qaRunners reference
276+277+Use `qaRunners` when a plugin contributes one or more transport runners beneath
278+the shared `openclaw qa` root. Keep this metadata cheap and static; the plugin
279+runtime still owns actual CLI registration through a lightweight
280+`runtime-api.ts` surface that exports `qaRunnerCliRegistrations`.
281+282+```json
283+{
284+"qaRunners": [
285+ {
286+"commandName": "matrix",
287+"description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
288+ }
289+ ]
290+}
291+```
292+293+| Field | Required | Type | What it means |
294+| ------------- | -------- | -------- | ------------------------------------------------------------------ |
295+| `commandName` | Yes | `string` | Subcommand mounted beneath `openclaw qa`, for example `matrix`. |
296+| `description` | No | `string` | Fallback help text used when the shared host needs a stub command. |
297+279298## setup reference
280299281300Use `setup` when setup and onboarding surfaces need cheap plugin-owned metadata
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。