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

| `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<string, object>` | Catalog rows for provider ids owned by this plugin. Keys should also appear in top-level `providers`. |

| `aliases` | `Record<string, object>` | 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<string, "static" \| "refreshable" \| "runtime">` | 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<string, string>` | 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<string, string>` | 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`,