| `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 planner metadata 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 startup, 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. |

missing activation metadata usually only costs performance; it should not

change correctness while legacy manifest ownership fallbacks still exist.

Every plugin should set `activation.onStartup` intentionally as OpenClaw moves

away from implicit startup imports. Set it to `true` only when the plugin must

run during Gateway startup. Set it to `false` when the plugin is inert at

startup and should load only from narrower triggers. Omitting `onStartup` keeps

the deprecated legacy implicit startup sidecar fallback for plugins with no

static capability metadata; future versions may stop startup-loading those

plugins unless they declare `activation.onStartup: true`.

```json

{

"activation": {

"onStartup": false,

"onProviders": ["openai"],

"onCommands": ["models"],

"onChannels": ["web"],

}

```

| Field | Required | Type | What it means |

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

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

| `onAgentHarnesses` | No | `string[]` | Embedded agent harness runtime ids that should include this plugin in activation/load plans. Use top-level `cliBackends` for CLI backend aliases. |

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

| `onConfigPaths` | No | `string[]` | Root-relative config paths that should include this plugin in startup/load plans when the path is present and not explicitly disabled. |

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

| Field | Required | Type | What it means |

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

| `onStartup` | No | `boolean` | Explicit Gateway startup activation. Every plugin should set this. `true` imports the plugin during startup; `false` opts out of the deprecated implicit sidecar startup fallback unless another matched trigger requires loading. |

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

| `onAgentHarnesses` | No | `string[]` | Embedded agent harness runtime ids that should include this plugin in activation/load plans. Use top-level `cliBackends` for CLI backend aliases. |

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

| `onConfigPaths` | No | `string[]` | Root-relative config paths that should include this plugin in startup/load plans when the path is present and not explicitly disabled. |

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

Current live consumers:

- Gateway startup planning uses `activation.onStartup` for explicit startup

import and opt-out of deprecated implicit sidecar startup fallback

- command-triggered CLI planning falls back to legacy

`commandAliases[].cliCommand` or `commandAliases[].name`

- agent-runtime startup planning uses `activation.onAgentHarnesses` for