| `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. |

| `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. |

| `providerAuthChoices` | No | `object[]` | Cheap auth-choice metadata for onboarding pickers, preferred-provider resolution, and simple CLI flag wiring. |

| `activation` | No | `object` | Cheap activation hints for provider, command, channel, route, and capability-triggered loading. Metadata only; plugin runtime still owns actual behavior. |

| `activation` | No | `object` | Cheap activation planner metadata for provider, command, channel, route, and capability-triggered loading. Metadata only; plugin runtime still owns actual behavior. |

| `setup` | No | `object` | Cheap setup/onboarding descriptors that discovery and setup surfaces can inspect without loading plugin runtime. |

| `qaRunners` | No | `object[]` | Cheap QA runner descriptors used by the shared `openclaw qa` host before plugin runtime loads. |

| `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. |

## activation reference

Use `activation` when the plugin can cheaply declare which control-plane events

should activate it later.

should include it in an activation/load plan.

## qaRunners reference

This block is planner metadata, not a lifecycle API. It does not register

runtime behavior, does not replace `register(...)`, and does not promise that

plugin code has already executed. The activation planner uses these fields to

narrow candidate plugins before falling back to existing manifest ownership

metadata such as `providers`, `channels`, `commandAliases`, `setup.providers`,

`contracts.tools`, and hooks.

Use `qaRunners` when a plugin contributes one or more transport runners beneath

the shared `openclaw qa` root. Keep this metadata cheap and static; the plugin

runtime still owns actual CLI registration through a lightweight

`runtime-api.ts` surface that exports `qaRunnerCliRegistrations`.

```json

{

"qaRunners": [

{

"commandName": "matrix",

"description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"

}

]

}

```

| Field | Required | Type | What it means |

| ------------- | -------- | -------- | ------------------------------------------------------------------ |

| `commandName` | Yes | `string` | Subcommand mounted beneath `openclaw qa`, for example `matrix`. |

| `description` | No | `string` | Fallback help text used when the shared host needs a stub command. |

Prefer the narrowest metadata that already describes ownership. Use

`providers`, `channels`, `commandAliases`, setup descriptors, or `contracts`

when those fields express the relationship. Use `activation` for extra planner

hints that cannot be represented by those ownership fields.

This block is metadata only. It does not register runtime behavior, and it does

not replace `register(...)`, `setupEntry`, or other runtime/plugin entrypoints.

}

```

| Field | Required | Type | What it means |

| ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- |

| `onProviders` | No | `string[]` | Provider ids that should activate this plugin when requested. |

| `onCommands` | No | `string[]` | Command ids that should activate this plugin. |

| `onChannels` | No | `string[]` | Channel ids that should activate this plugin. |

| `onRoutes` | No | `string[]` | Route kinds that should activate this plugin. |

| `onCapabilities` | No | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Broad capability hints used by control-plane activation planning. |

| Field | Required | Type | What it means |

| ---------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |

| `onProviders` | No | `string[]` | Provider ids that should include this plugin in activation/load plans. |

| `onCommands` | No | `string[]` | Command ids that should include this plugin in activation/load plans. |

| `onChannels` | No | `string[]` | Channel ids that should include this plugin in activation/load plans. |

| `onRoutes` | No | `string[]` | Route kinds that should include this plugin in activation/load plans. |

| `onCapabilities` | No | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Broad capability hints used by control-plane activation planning. Prefer narrower fields when possible. |

Current live consumers:

`providers[]` and top-level `cliBackends[]` ownership when explicit provider

activation metadata is missing

Planner diagnostics can distinguish explicit activation hints from manifest

ownership fallback. For example, `activation-command-hint` means

`activation.onCommands` matched, while `manifest-command-alias` means the

planner used `commandAliases` ownership instead. These reason labels are for

host diagnostics and tests; plugin authors should keep declaring the metadata

that best describes ownership.

## qaRunners reference

Use `qaRunners` when a plugin contributes one or more transport runners beneath

the shared `openclaw qa` root. Keep this metadata cheap and static; the plugin

runtime still owns actual CLI registration through a lightweight

`runtime-api.ts` surface that exports `qaRunnerCliRegistrations`.

```json

{

"qaRunners": [

{

"commandName": "matrix",

"description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"

}

]

}

```

| Field | Required | Type | What it means |

| ------------- | -------- | -------- | ------------------------------------------------------------------ |

| `commandName` | Yes | `string` | Subcommand mounted beneath `openclaw qa`, for example `matrix`. |

| `description` | No | `string` | Fallback help text used when the shared host needs a stub command. |

## setup reference

Use `setup` when setup and onboarding surfaces need cheap plugin-owned metadata