From d39e89e6b05e6e6da3d72a358319322975d2c3a1 Mon Sep 17 00:00:00 2001 From: Shakker Date: Sat, 25 Apr 2026 02:16:28 +0100 Subject: [PATCH] docs: document model catalog manifest metadata --- docs/plugins/manifest.md | 100 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) diff --git a/docs/plugins/manifest.md b/docs/plugins/manifest.md index 4759be5cc77..781a7a3e89d 100644 --- a/docs/plugins/manifest.md +++ b/docs/plugins/manifest.md @@ -143,6 +143,7 @@ or npm install metadata. Those belong in your plugin code and `package.json`. | `providers` | No | `string[]` | Provider ids owned by this plugin. | | `providerDiscoveryEntry` | No | `string` | Lightweight provider-discovery module path, relative to the plugin root, for manifest-scoped provider catalog metadata that can be loaded without activating the full plugin runtime. | | `modelSupport` | No | `object` | Manifest-owned shorthand model-family metadata used to auto-load the plugin before runtime. | +| `modelCatalog` | No | `object` | Declarative model catalog metadata for providers owned by this plugin. This is the control-plane contract for future read-only listing, onboarding, model pickers, aliases, and suppression without loading plugin runtime. | | `providerEndpoints` | No | `object[]` | Manifest-owned endpoint host/baseUrl metadata for provider routes that core must classify before provider runtime loads. | | `cliBackends` | No | `string[]` | CLI inference backend ids owned by this plugin. Used for startup auto-activation from explicit config refs. | | `syntheticAuthRefs` | No | `string[]` | Provider or CLI backend refs whose plugin-owned synthetic auth hook should be probed during cold model discovery before runtime loads. | @@ -583,6 +584,105 @@ Fields: | `modelPrefixes` | `string[]` | Prefixes matched with `startsWith` against shorthand model ids. | | `modelPatterns` | `string[]` | Regex sources matched against shorthand model ids after profile suffix removal. | +## modelCatalog reference + +Use `modelCatalog` when OpenClaw should know provider model metadata before +loading plugin runtime. This is the manifest-owned source for fixed catalog +rows, provider aliases, suppression rules, and discovery mode. Runtime refresh +still belongs in provider runtime code, but the manifest tells core when runtime +is required. + +```json +{ + "providers": ["moonshot"], + "modelCatalog": { + "providers": { + "moonshot": { + "baseUrl": "https://api.moonshot.ai/v1", + "api": "openai-responses", + "models": [ + { + "id": "kimi-k2.6", + "name": "Kimi K2.6", + "input": ["text", "image"], + "reasoning": true, + "contextWindow": 256000, + "maxTokens": 128000, + "cost": { + "input": 0.6, + "output": 2.5, + "cacheRead": 0.15 + }, + "status": "available", + "tags": ["default"] + } + ] + } + }, + "aliases": { + "azure-openai-responses": { + "provider": "openai", + "api": "azure-openai-responses" + } + }, + "suppressions": [ + { + "provider": "openai", + "model": "gpt-5.3-codex-spark", + "reason": "not available on Azure OpenAI Responses" + } + ], + "discovery": { + "moonshot": "static" + } + } +} +``` + +Top-level fields: + +| Field | Type | What it means | +| -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| `providers` | `Record` | Catalog rows for provider ids owned by this plugin. Keys should also appear in top-level `providers`. | +| `aliases` | `Record` | Provider aliases that should resolve to an owned provider for catalog or suppression planning. | +| `suppressions` | `object[]` | Model rows from another source that this plugin suppresses for a provider-specific reason. | +| `discovery` | `Record` | Whether the provider catalog can be read from manifest metadata, refreshed into cache, or requires runtime. | + +Provider fields: + +| Field | Type | What it means | +| --------- | ------------------------ | ----------------------------------------------------------------- | +| `baseUrl` | `string` | Optional default base URL for models in this provider catalog. | +| `api` | `ModelApi` | Optional default API adapter for models in this provider catalog. | +| `headers` | `Record` | Optional static headers that apply to this provider catalog. | +| `models` | `object[]` | Required model rows. Rows without an `id` are ignored. | + +Model fields: + +| Field | Type | What it means | +| --------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------- | +| `id` | `string` | Provider-local model id, without the `provider/` prefix. | +| `name` | `string` | Optional display name. | +| `api` | `ModelApi` | Optional per-model API override. | +| `baseUrl` | `string` | Optional per-model base URL override. | +| `headers` | `Record` | Optional per-model static headers. | +| `input` | `Array<"text" \| "image" \| "document">` | Modalities the model accepts. | +| `reasoning` | `boolean` | Whether the model exposes reasoning behavior. | +| `contextWindow` | `number` | Native provider context window. | +| `contextTokens` | `number` | Optional effective runtime context cap when different from `contextWindow`. | +| `maxTokens` | `number` | Maximum output tokens when known. | +| `cost` | `object` | Optional USD per million token pricing, including optional `tieredPricing`. | +| `compat` | `object` | Optional compatibility flags matching OpenClaw model config compatibility. | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Listing status. Suppress only when the row must not appear at all. | +| `statusReason` | `string` | Optional reason shown with non-available status. | +| `replaces` | `string[]` | Older provider-local model ids this model supersedes. | +| `replacedBy` | `string` | Replacement provider-local model id for deprecated rows. | +| `tags` | `string[]` | Stable tags used by pickers and filters. | + +Do not put runtime-only data in `modelCatalog`. If a provider needs account +state, an API request, or local process discovery to know the complete model +set, declare that provider as `refreshable` or `runtime` in `discovery`. + Legacy top-level capability keys are deprecated. Use `openclaw doctor --fix` to move `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`,