Manifest model fields

Manifest fields that describe the models a provider plugin exposes: which shorthand ids it claims, the catalog rows core can read before runtime loads, model-id cleanup, and hosted pricing policy. Part of the Plugin manifest reference; the top-level field reference lists every field.

modelSupport reference

Use modelSupport when OpenClaw should infer your provider plugin from shorthand model ids like gpt-5.6-sol or claude-sonnet-4.6 before plugin runtime loads.

{  "modelSupport": {    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],    "modelPatterns": ["^computer-use-preview"]  }}

OpenClaw applies this precedence:

• explicit provider/model refs use the owning providers manifest metadata
• modelPatterns beat modelPrefixes
• if one non-bundled plugin and one bundled plugin both match, the non-bundled plugin wins
• remaining ambiguity is ignored until the user or config specifies a provider

Fields:

modelPatterns entries are compiled through compileSafeRegex, which rejects patterns containing nested repetition (for example (a+)+$). Patterns that fail the safety check are silently skipped, the same as syntactically invalid regex. Keep patterns simple and avoid nested quantifiers.

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, publication-time metadata sources, provider aliases, suppression rules, and discovery mode. Runtime refresh still belongs in provider runtime code, but the manifest tells core when runtime is required.

{  "providers": ["openai"],  "modelCatalog": {    "modelsDev": {      "openai": "openai"    },    "providers": {      "openai": {        "baseUrl": "https://api.openai.com/v1",        "api": "openai-responses",        "models": [          {            "id": "gpt-5.4",            "name": "GPT-5.4",            "input": ["text", "image"],            "reasoning": true,            "contextWindow": 256000,            "maxTokens": 128000,            "cost": {              "input": 1.25,              "output": 10,              "cacheRead": 0.125            },            "status": "available",            "tags": ["default"]          }        ]      }    },    "aliases": {      "azure-openai-responses": {        "provider": "openai",        "api": "azure-openai-responses"      }    },    "suppressions": [      {        "provider": "azure-openai-responses",        "model": "gpt-5.3-codex-spark",        "reason": "not available on Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

Top-level fields:

modelsDev opts an owned provider into models.dev metadata hydration when the hosted catalog is published. Declare the upstream provider once per OpenClaw provider, not once per model. Omission means no models.dev hydration; there is no central provider fallback. Keys are normalized as OpenClaw provider ids and source ids are trimmed. Empty or non-string source ids and mappings for unowned providers are ignored; an alias alone does not grant ownership. A mapping does not create catalog provider rows or relax their validation.

Hydration adds eligible model ids and fills only undefined metadata. Explicit manifest values remain authoritative, including false; models.dev never supplies transport settings or prices. Prices still follow the provider-owned pricing policy. Opt in only when the provider defaults are appropriate for newly imported rows; providers that choose a transport per model should not opt in unless those defaults are safe. Hydration errors fail publication, leaving the last published artifact intact. The publisher hydrates opted-in metadata even without --pricing; that flag controls price enrichment only. A dry run performs the same metadata hydration without writing the artifact.

This field is publication-time authoring metadata, not a Gateway discovery hook. It does not add runtime network calls or hot reload; the existing hosted catalog update lifecycle is unchanged.

aliases participates in provider ownership lookup for model-catalog planning. Alias targets must be top-level providers owned by the same plugin. When a provider-filtered list uses an alias, OpenClaw can read the owning manifest and apply alias API/base URL overrides without loading provider runtime. Aliases do not expand unfiltered catalog listings; broad lists emit the owning canonical provider rows only.

suppressions replaces the old provider runtime suppressBuiltInModel hook. Suppression entries are honored only when the provider is owned by the plugin or declared as a modelCatalog.aliases key that targets an owned provider. Runtime suppression hooks are no longer called during model resolution.

Provider fields:

Model fields:

Suppression fields:

Declare retirement only from affirmative provider evidence, never from a failed or empty discovery request. Scope account-route retirements with when.baseUrlHosts; matching those rules requires a concrete selected endpoint and leaves sibling endpoints untouched. Unconditional retirement rules do not require credentials. Malformed or empty retirement scopes are ignored rather than becoming global rules. Runtime blocks that retired route, while openclaw doctor --fix owns persistent replacement or override removal. Ordinary suppression and a model row's deprecated listing status do not authorize retirement repair. Manifest changes take effect after Gateway restart or the owning metadata reload.

upstreamModel marks a row that serves the same upstream model as a row in another bundled catalog under a different name, for example a subscription endpoint next to the vendor's API endpoint. It is authoring metadata: normalization drops it, and a contract test uses it to keep capability flags such as compat.codeMode from drifting between catalogs that ship the same model. Most rows need no marker, because matching ignores a leading vendor namespace and casing: moonshotai/kimi-k3 and zai-org/GLM-5.2 already match the first-party kimi-k3 and glm-5.2 rows. Reach for upstreamModel only when the vendor's own names genuinely differ. See Code mode.

Do not put runtime-only data in modelCatalog. Use static only when manifest rows are complete enough for provider-filtered list and picker surfaces to skip registry/runtime discovery. Use refreshable when manifest rows are useful listable seeds or supplements but a refresh/cache can add more rows later; refreshable rows are not authoritative by themselves. Use runtime when OpenClaw must load provider runtime to know the list.

Capabilities belong to the declared API and base URL, not only the provider/model id. When model listing enriches a cached row, it uses manifest capabilities only for a matching route; a custom endpoint must supply its own limits and capabilities.

modelIdNormalization reference

Use modelIdNormalization for cheap provider-owned model-id cleanup that must happen before provider runtime loads. This keeps aliases such as short model names, provider-local legacy ids, and proxy prefix rules in the owning plugin manifest instead of in core model-selection tables.

{  "providers": ["anthropic", "openrouter"],  "modelIdNormalization": {    "providers": {      "anthropic": {        "aliases": {          "sonnet-4.6": "claude-sonnet-4-6"        }      },      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  }}

Provider fields:

modelPricing reference

Use modelPricing when the hosted catalog publisher needs provider-specific pricing-key behavior. The publisher reads this metadata without importing provider runtime code.

{  "providers": ["ollama", "openrouter"],  "modelPricing": {    "providers": {      "ollama": {        "external": false      },      "openrouter": {        "openRouter": {          "passthroughProviderModel": true        },        "liteLLM": false      }    }  }}

Provider fields:

Source fields:

A declared provider policy enables only its declared source mappings. Without a policy, publication tries OpenRouter, then LiteLLM. Each selected price is a complete schedule: base rates and context tiers are never combined across sources. OpenRouter's native prompt-length overrides are supported; time-based overrides are not represented as static context tiers.

For authoritative native source mappings, use:

{  "providers": ["opencode", "venice"],  "modelPricing": {    "providers": {      "opencode": { "openCode": { "provider": "opencode" } },      "venice": { "venice": { "provider": "venice" } }    }  }}

The publisher fetches a fixed public endpoint without credentials only when its source is declared, and publishes native prices only in explicitly mapped owner namespaces. Cerebras, Chutes, and DeepInfra use the same shape with their respective source and provider IDs. Lightweight plugin-owned pricing-api.ts artifacts share payload parsing with runtime discovery without importing provider runtimes.

DeepInfra's top-level array uses model_name identity. Its numeric discount and cached-input ratio apply to native cents-per-token prices. Pricing prose, nonempty tables, scheduled expiry, and undocumented generic cache-write rates are validated but omitted as unsupported schedules. Priority/flex and explicit cache-retention multipliers do not change standard costs. Its agent projection continues to own runtime metadata; the pricing feed does not discover chat models.

An opted-in native source owns the complete provider schedule, including missing prices: generic sources cannot fill its gaps. A successful feed with no price for a bundled model preserves that model's metadata, omits its cost, and emits a publication warning. Missing pricing is not evidence of model retirement or free usage. Explicit native zero prices remain known-free estimates. Fetch failure, malformed response bodies or declared prices, and feeds with no usable prices stop publication, leaving the previous hosted catalog intact. Explicit operator rates remain unchanged. This authoring metadata adds no operator setting and does not change the Gateway's existing refresh and restart lifecycle.

OpenClaw Provider Index

The compiled OpenClaw Provider Index is retired. Model metadata comes from plugin manifests, provider-owned discovery, and the hosted model catalog, with configured overrides applied by model resolution. See Model listing for catalog sources and refresh behavior.

Provider setup uses installed manifest metadata and the official external plugin catalog. The external catalog supplies install hints and auth-choice labels for plugins that are not installed; installed plugin owners take precedence. Install hints remain in package.json#openclaw.install, not in a separate compiled provider index.

openclaw doctor --fix migrates a small, closed set of legacy top-level manifest capability keys into contracts.*: speechProviders, mediaUnderstandingProviders, imageGenerationProviders, and tools. None of these (or any other capability list) are read as top-level manifest fields anymore; normal manifest loading only recognizes them under contracts.