Manifest provider fields

Manifest fields that tell core what a provider can do, and how to reach it, without importing the provider runtime. Part of the Plugin manifest reference; the top-level field reference lists every field.

Generation provider metadata reference

The generation provider metadata fields describe static auth signals for providers declared in the matching contracts.*GenerationProviders list. OpenClaw reads these fields before provider runtime loads so core tools can decide whether a generation provider is available without importing every provider plugin.

Use these fields only for cheap, declarative facts. Transport, request transforms, token refresh, credential validation, and actual generation behavior stay in the plugin runtime.

{
  "contracts": {
    "imageGenerationProviders": ["example-image"]
  },
  "imageGenerationProviderMetadata": {
    "example-image": {
      "aliases": ["example-image-oauth"],
      "authProviders": ["example-image"],
      "configSignals": [
        {
          "rootPath": "plugins.entries.example-image.config",
          "overlayPath": "image",
          "mode": {
            "path": "mode",
            "default": "local",
            "allowed": ["local"]
          },
          "requiredAny": ["workflow", "workflowPath"],
          "required": ["promptNodeId"]
        }
      ],
      "authSignals": [
        {
          "provider": "example-image"
        },
        {
          "provider": "example-image-oauth",
          "providerBaseUrl": {
            "provider": "example-image",
            "defaultBaseUrl": "https://api.example.com/v1",
            "allowedBaseUrls": ["https://api.example.com/v1"]
          }
        }
      ]
    }
  }
}

Each metadata entry supports:

Each configSignals entry supports:

Config signals inspect canonical SecretRefs for provider and environment availability. Other nonempty objects are configured metadata; an object containing only source and id is not interpreted as a SecretRef. Doctor repairs legacy refs on declared credential paths without rewriting opaque plugin data.

Each mode guard supports:

Each authSignals entry supports:

Each providerBaseUrl guard supports:

mediaUnderstandingProviderMetadata reference

Use mediaUnderstandingProviderMetadata when a media-understanding provider has default models, auto-auth fallback priority, or native document support that generic core helpers need before runtime loads. Keys must also be declared in contracts.mediaUnderstandingProviders.

{
  "contracts": {
    "mediaUnderstandingProviders": ["example"]
  },
  "mediaUnderstandingProviderMetadata": {
    "example": {
      "capabilities": ["image", "audio"],
      "defaultModels": {
        "image": "example-vision-latest",
        "audio": "example-transcribe-latest"
      },
      "autoPriority": {
        "image": 40
      },
      "nativeDocumentInputs": ["pdf"],
      "documentModels": {
        "pdf": {
          "textExtraction": "example-doc-text-latest",
          "image": "example-doc-vision-latest"
        }
      }
    }
  }
}

Each provider entry can include:

providerEndpoints reference

Use providerEndpoints for endpoint classification that generic request policy must know before provider runtime loads. Core still owns the meaning of each endpointClass; plugin manifests own the host and base URL metadata.

The same endpoint metadata controls implicit model catalog eligibility when an operator sets models.providers.<id>.baseUrl. Catalog, alias, and native model base URLs also count as declared endpoints. A nonmatching provider-level URL excludes manifest, discovered, static, and generated catalog rows; explicitly authored models remain in the inventory. Plugins without native endpoint declarations keep their existing discovery behavior. Host and suffix matching retain their request-classification rules, so catalog eligibility does not establish exact-origin trust or prove a request can succeed.

Officially externalized provider plugins are excluded from the core dist, so their manifests are invisible until installed. Their providerEndpoints must also be mirrored in scripts/lib/official-external-provider-catalog.json so endpoint classification keeps working without the plugin; a contract test enforces the mirror.

Endpoint fields:

providerRequest reference

Use providerRequest for cheap request-compatibility metadata that generic request policy needs without loading provider runtime. Keep behavior-specific payload rewriting in provider runtime hooks or shared provider-family helpers.

{
  "providerRequest": {
    "providers": {
      "vllm": {
        "family": "vllm",
        "openAICompletions": {
          "supportsStreamingUsage": true
        }
      }
    }
  }
}

Provider fields: