LLM/moltbot
1
0
Fork 0
mirror of https://github.com/moltbot/moltbot.git synced 2026-04-23 14:45:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(plugins): add manifest activation and setup descriptors (#64780)

Browse Source
This commit is contained in:
Vincent Koc
2026-04-11 12:35:59 +01:00
committed by GitHub
parent d7479dc61a
commit 79c3dbecd1
6 changed files with 311 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/plugins/architecture.md
View File

@@ -519,10 +519,15 @@ The manifest is the control-plane source of truth. OpenClaw uses it to:
- validate `plugins.entries.<id>.config`
- augment Control UI labels/placeholders
- show install/catalog metadata
- preserve cheap activation and setup descriptors without loading plugin runtime
For native plugins, the runtime module is the data-plane part. It registers
actual behavior such as hooks, tools, commands, or provider flows.
Optional manifest `activation` and `setup` blocks stay on the control plane.
They are metadata-only descriptors for activation planning and setup discovery;
they do not replace runtime registration, `register(...)`, or `setupEntry`.
### What the loader caches
OpenClaw keeps short in-process caches for:

77
docs/plugins/manifest.md
View File

@@ -47,6 +47,10 @@ Use it for:
- config validation
- auth and onboarding metadata that should be available without booting plugin
runtime
- cheap activation hints that control-plane surfaces can inspect before runtime
loads
- cheap setup descriptors that setup/onboarding surfaces can inspect before
runtime loads
- alias and auto-enable metadata that should resolve before plugin runtime loads
- shorthand model-family ownership metadata that should auto-activate the
plugin before runtime loads
@@ -152,6 +156,8 @@ Those belong in your plugin code and `package.json`.
| `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. |
| `setup` | No | `object` | Cheap setup/onboarding descriptors that discovery and setup surfaces can inspect without loading plugin runtime. |
| `contracts` | No | `object` | Static bundled capability snapshot for speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search, and tool ownership. |
| `channelConfigs` | No | `Record<string, object>` | Manifest-owned channel config metadata merged into discovery and validation surfaces before runtime loads. |
| `skills` | No | `string[]` | Skill directories to load, relative to the plugin root. |
@@ -208,6 +214,77 @@ uses this metadata for diagnostics without importing plugin runtime code.
| `kind` | No | `"runtime-slash"` | Marks the alias as a chat slash command rather than a root CLI command. |
| `cliCommand` | No | `string` | Related root CLI command to suggest for CLI operations, if one exists. |
## activation reference
Use `activation` when the plugin can cheaply declare which control-plane events
should activate it later.
This block is metadata only. It does not register runtime behavior, and it does
not replace `register(...)`, `setupEntry`, or other runtime/plugin entrypoints.
```json
{
"activation": {
"onProviders": ["openai"],
"onCommands": ["models"],
"onChannels": ["web"],
"onRoutes": ["gateway-webhook"],
"onCapabilities": ["provider", "tool"]
}
}
```
| 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. |
## setup reference
Use `setup` when setup and onboarding surfaces need cheap plugin-owned metadata
before runtime loads.
```json
{
"setup": {
"providers": [
{
"id": "openai",
"authMethods": ["api-key"],
"envVars": ["OPENAI_API_KEY"]
}
],
"cliBackends": ["openai-cli"],
"configMigrations": ["legacy-openai-auth"],
"requiresRuntime": false
}
}
```
Top-level `cliBackends` stays valid and continues to describe CLI inference
backends. `setup.cliBackends` is the setup-specific descriptor surface for
control-plane/setup flows that should stay metadata-only.
### setup.providers reference
| Field | Required | Type | What it means |
| ------------- | -------- | ---------- | ---------------------------------------------------------------------------------- |
| `id` | Yes | `string` | Provider id exposed during setup or onboarding. |
| `authMethods` | No | `string[]` | Setup/auth method ids this provider supports without loading full runtime. |
| `envVars` | No | `string[]` | Env vars that generic setup/status surfaces can check before plugin runtime loads. |
### setup fields
| Field | Required | Type | What it means |
| ------------------ | -------- | ---------- | --------------------------------------------------------------------------- |
| `providers` | No | `object[]` | Provider setup descriptors exposed during setup and onboarding. |
| `cliBackends` | No | `string[]` | Setup-time backend ids available without full runtime activation. |
| `configMigrations` | No | `string[]` | Config migration ids owned by this plugin's setup surface. |
| `requiresRuntime` | No | `boolean` | Whether setup still needs plugin runtime execution after descriptor lookup. |
## uiHints reference
`uiHints` is a map from config field names to small rendering hints.