diff --git a/CHANGELOG.md b/CHANGELOG.md index 574322d7c3c..88066de979c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ Docs: https://docs.openclaw.ai - Plugins/models: wire manifest `modelCatalog.aliases` and `modelCatalog.suppressions` into model-catalog planning and built-in model suppression, with stale Spark and Qwen Coding Plan suppressions now declared in plugin manifests instead of runtime fallback hooks. Thanks @shakkernerd. - Channels/Yuanbao: register the Tencent Yuanbao external channel plugin (`openclaw-plugin-yuanbao`) in the official channel catalog, contract suites, and community plugin docs, with a new `docs/channels/yuanbao.md` quick-start guide for WebSocket bot DMs and group chats. (#72756) Thanks @loongfay. - Channels/QQBot: add full group chat support (history tracking, @-mention gating, activation modes, per-group config, FIFO message queue with deliver debounce), C2C `stream_messages` streaming with a `StreamingController` lifecycle manager, unified `sendMedia` with chunked upload for large files, and refactor the engine into pipeline stages, focused outbound submodules, builtin slash-command modules, and explicit DI ports via `createEngineAdapters()`. (#70624) Thanks @cxyhhhhh. +- Plugins/startup: add explicit `activation.onStartup` metadata so plugins can declare Gateway startup import behavior while the deprecated implicit sidecar fallback remains for legacy plugins. Thanks @shakkernerd. - Gateway/startup: reuse lookup-table plugin manifests when loading startup plugins so Gateway boot avoids rebuilding plugin discovery and manifest metadata. Thanks @shakkernerd. - Gateway/runtime: reuse the current plugin metadata snapshot for provider discovery so repeated model-provider discovery avoids rebuilding plugin manifest metadata. Thanks @shakkernerd. - Gateway/startup: pass the plugin metadata snapshot from config validation into plugin bootstrap so startup reuses one manifest product instead of rebuilding plugin metadata. Thanks @shakkernerd. diff --git a/docs/plugins/architecture-internals.md b/docs/plugins/architecture-internals.md index 1f351fd6b64..f637d836e2f 100644 --- a/docs/plugins/architecture-internals.md +++ b/docs/plugins/architecture-internals.md @@ -60,6 +60,11 @@ to narrow plugin loading before broader registry materialization: channel id - explicit provider setup/runtime resolution narrows to plugins that own the requested provider id +- Gateway startup planning uses `activation.onStartup` for explicit startup + imports and startup opt-outs; every plugin should declare it as OpenClaw + moves away from implicit startup imports, while plugins without static + capability metadata and without `activation.onStartup` still use the + deprecated implicit startup sidecar fallback for compatibility The activation planner exposes both an ids-only API for existing callers and a plan API for new diagnostics. Plan entries report why a plugin was selected, diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md index e5440d6288a..f2456aafbbe 100644 --- a/docs/plugins/manifest.md +++ b/docs/plugins/manifest.md @@ -170,7 +170,7 @@ or npm install metadata. Those belong in your plugin code and `package.json`. | `providerAuthAliases` | No | `Record` | 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` | 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. | @@ -258,9 +258,18 @@ Current consumers use it as a narrowing hint before broader plugin loading, so 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"], @@ -271,18 +280,21 @@ change correctness while legacy manifest ownership fallbacks still exist. } ``` -| 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