OpenClaw Plugin Manifest and JSON Schema Requirements

This page describes the native OpenClaw plugin manifest, openclaw.plugin.json. For details on compatible bundle layouts (Agent Plugins, Codex, Claude, Cursor), refer to Plugin bundles.

Those compatible bundle formats rely on their own manifest files instead:

• Agent Plugins bundle: plugin.json located at the package root, following the public Agent Plugins standard
• Codex bundle: .codex-plugin/plugin.json
• Claude bundle: .claude-plugin/plugin.json, or the default Claude component layout without any manifest
• Cursor bundle: .cursor-plugin/plugin.json

OpenClaw recognizes these layouts automatically but does not check them against the openclaw.plugin.json schema shown below. When a compatible bundle matches OpenClaw's runtime expectations, the system reads bundle metadata, declared skill roots, Claude command roots, Claude settings.json defaults, Claude LSP defaults, and supported hook packs.

A native OpenClaw plugin must include openclaw.plugin.json in the plugin root. OpenClaw uses it to validate configuration without running plugin code. If the manifest is missing or invalid, config validation fails and OpenClaw reports a plugin error.

The complete plugin system guide lives in Plugins, while Capability model covers the native capability model and current external-compatibility guidance.

What this file does

openclaw.plugin.json holds metadata that OpenClaw reads before your plugin code loads. Every piece of it must be inspectable cheaply, with no need to start plugin runtime.

Suitable for:

• plugin identity, config validation, and config UI hints
• auth, onboarding, and setup metadata (alias, auto-enable, provider env vars, auth choices)
• activation hints for control-plane surfaces
• root CLI command names, descriptions, and subcommand markers (cliCommands)
• shorthand model-family ownership
• static capability-ownership snapshots (contracts)
• dashboard widget data bindings and action verbs
• static MCP servers that should exist while the plugin is enabled
• QA runner metadata the shared openclaw qa host can inspect
• channel-specific config metadata merged into catalog and validation surfaces

Not suitable for: registering native runtime hooks, declaring plugin code entrypoints, or npm install metadata. Those belong in your plugin code and package.json.

Minimal example

{
  "id": "voice-call",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

Rich example

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "modelIdNormalization": {
    "providers": {
      "openrouter": {
        "prefixWhenBare": "openrouter"
      }
    }
  },
  "providerEndpoints": [
    {
      "endpointClass": "openrouter",
      "hostSuffixes": ["openrouter.ai"]
    }
  ],
  "providerRequest": {
    "providers": {
      "openrouter": {
        "family": "openrouter"
      }
    }
  },
  "cliBackends": ["openrouter-cli"],
  "syntheticAuthRefs": ["openrouter-cli"],
  "setup": {
    "providers": [
      {
        "id": "openrouter",
        "envVars": ["OPENROUTER_API_KEY"]
      }
    ]
  },
  "providerAuthAliases": {
    "openrouter-coding": "openrouter"
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "OpenRouter API key",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "OpenRouter API key",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

Top-level field reference

For static doctor ownership, prefer top-level sessionRouteStateOwners. External plugins can still rely on the older doctorContract.sessionRouteStateOwners: true declaration paired with a sessionRouteStateOwners export from doctor-contract-api, though that approach is deprecated. When the manifest field exists, OpenClaw uses it directly and skips loading the doctor-contract module. The fallback to that module is slated for removal in OpenClaw 2027.1, following the external-plugin migration period.

Set doctorContract.configRepair: true when the doctor-contract module exports non-empty legacyConfigRules, a normalizeCompatibilityConfig function, or both. A single declaration covers the entire config-repair artifact.

MCP server reference

With mcpServers, a native plugin can bundle an MCP server, including an MCP App, so operators don't have to repeat its static process definition in openclaw.json:

{
  "mcpServers": {
    "example": {
      "transport": "stdio",
      "command": "node",
      "args": ["./mcp-server.js"]
    }
  }
}

These servers are included by OpenClaw only while the owning plugin is active. Relative command, args, cwd, and workingDirectory paths are resolved from the plugin root. User configuration takes precedence: mcp.servers.<name> can override a plugin default, or enabled: false can be set to exclude it. MCP App rendering and server-tool calls still depend on the standard MCP Apps setting and effective tool policy; declaring a server bypasses neither boundary.

dashboard reference

dashboard allows an enabled plugin to surface existing Gateway RPCs to granted dashboard widgets without introducing plugin policy into core. Data bindings must reference a method the same plugin registers with operator.read; action verbs must reference one it registers with operator.write. Any mismatch causes the plugin to be rejected during registration.

{
  "dashboard": {
    "dataBindings": [
      {
        "id": "items.list",
        "method": "example.items.list",
        "description": "List example items."
      }
    ],
    "actionVerbs": [
      {
        "id": "refresh",
        "method": "example.items.refresh",
        "description": "Refresh example items.",
        "paramShape": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "force": { "type": "boolean" }
          }
        }
      }
    ]
  }
}

Manifest ids are scoped to the plugin. Widget grants use <plugin-id>.<id>, for instance example.items.list and example.refresh. To keep the persisted grant namespace unambiguous, OpenClaw escapes % and . in the plugin-id segment as %25 and %2E; ordinary plugin ids retain their natural form. paramShape is an optional JSON Schema applied to the action params object before OpenClaw invokes the plugin RPC.

catalog reference

catalog offers optional display hints for plugin browsers. Hosts can choose to ignore these hints. They never install or enable the plugin, nor do they alter its runtime behavior or trust level.

{
  "catalog": {
    "featured": true,
    "order": 10
  }
}

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:

Each mode guard supports:

Each authSignals entry supports:

Each providerBaseUrl guard supports:

Tool metadata reference

toolMetadata relies on the identical configSignals and authSignals structures found in generation provider metadata, with the tool name acting as the key. Ownership is established through contracts.tools. By declaring cheap availability evidence via toolMetadata, OpenClaw can skip loading a plugin runtime when its tool factory would only return null.

{
  "setup": {
    "providers": [
      {
        "id": "example",
        "envVars": ["EXAMPLE_API_KEY"]
      }
    ]
  },
  "contracts": {
    "tools": ["example_search"]
  },
  "toolMetadata": {
    "example_search": {
      "profiles": ["coding", "full"],
      "authSignals": [
        {
          "provider": "example"
        }
      ],
      "configSignals": [
        {
          "rootPath": "plugins.entries.example.config",
          "overlayPath": "search",
          "required": ["apiKey"]
        }
      ]
    }
  }
}

Additional accepted fields for toolMetadata entries are:

• profiles: predefined tool profiles that include the plugin tool by default. The valid options are minimal, coding, messaging, and full. These contributions are merged into the corresponding profile allowlist, while explicit operator allowlists and deny rules keep their authority.
• optional: indicates the tool is not essential for plugin activation.
• replaySafe: designates tool execution as safe for repetition following an incomplete model turn.
• sideEffecting: flags execution as potentially altering persistent or external state.

These extras complement the shared configSignals and authSignals fields mentioned earlier.

When a tool lacks a toolMetadata, OpenClaw retains its current behavior, loading the owning plugin if the tool contract matches policy. For hot-path tools whose factory depends on auth or config, plugin authors should opt for toolMetadata rather than forcing the core import runtime to make the request.

providerAuthChoices reference

Every providerAuthChoices entry covers a single onboarding or authentication option. OpenClaw reviews this before the provider runtime loads. Provider setup lists draw on these manifest choices, descriptor-derived setup options, and install-catalog metadata without ever loading the provider runtime.

When appGuidedDiscovery is true, the associated provider auth method must provide appGuidedSetup.detect and appGuidedSetup.prepare. Detection operates read-only, meaning no login, model pull, download, or config write occurs. Preparation revalidates the exact chosen model and yields a config proposal; OpenClaw tests that proposal in isolation and commits it only after success. A provider may also expose appGuidedSetup.detectAvailability to flag its setup choice as detected when the local service is reachable but no model fits automatic setup. The availability probe also stays read-only.

cliCommands reference

List every plugin-owned root command in cliCommands so root help and command-owner routing remain metadata-only:

{
  "cliCommands": [
    {
      "name": "example",
      "description": "Manage the example integration",
      "hasSubcommands": true
    }
  ]
}

The manifest row serves as the authoritative help text. At runtime, register the same command using api.registerCli(..., { descriptors: [...] }); runtime descriptors can also supply machineOutput. Commands nested like openclaw nodes <feature> are not root commands and should not appear in cliCommands.

commandAliases reference

When a plugin owns a runtime command name that users might place in plugins.allow or attempt to invoke as a root CLI command, use commandAliases. OpenClaw relies on this metadata for diagnostics without loading the plugin's runtime code.

{
  "commandAliases": [
    {
      "name": "dreaming",
      "kind": "runtime-slash",
      "cliCommand": "memory"
    }
  ]
}

activation reference

Employ activation when the plugin can inexpensively specify which control-plane events should place it in an activation or load plan.

This block is planner metadata, not a lifecycle API. It neither registers runtime behavior, nor replaces register(...), nor guarantees that plugin code has run. The activation planner consults these fields to reduce candidate plugins before relying on existing manifest ownership metadata, such as providers, channels, commandAliases, setup.providers, contracts.tools, and hooks.

Choose the most specific metadata that already captures ownership. Use providers, channels, commandAliases, setup descriptors, or contracts when those fields convey the relationship. For extra planner hints that those ownership fields cannot express, use activation. For CLI runtime aliases like claude-cli, my-cli, or google-gemini-cli, use top-level cliBackends; activation.onAgentHarnesses applies only to embedded agent harness ids lacking an ownership field.

Every plugin should set activation.onStartup deliberately. Assign true only when the plugin must run during Gateway startup. Assign false when the plugin is idle at startup and should load solely from narrower triggers. Omitting onStartup no longer causes implicit startup loading; instead, rely on explicit activation metadata for startup, channel, config, agent-harness, memory, or other narrower activation triggers.

{
  "activation": {
    "onStartup": false,
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onConfigPaths": ["browser"],
    "onCapabilities": ["provider", "tool"]
  }
}

Current live consumers:

• During gateway startup, activation.onStartup is referenced for explicit import handling.
• CLI planning invoked by commands relies on the older commandAliases[].cliCommand or commandAliases[].name mechanisms.
• For agent-runtime initialization, activation.onAgentHarnesses applies to embedded harnesses, while cliBackends[] covers top-level CLI runtime aliases.
• When explicit channel activation metadata is absent, channel-triggered setup and planning revert to legacy channels[] ownership.
• Non-channel root configuration surfaces, like the bundled browser plugin's browser section, use activation.onConfigPaths for startup plugin planning.
• Provider-triggered setup and runtime planning fall back to legacy providers[] and top-level cliBackends[] ownership when explicit provider activation metadata is unavailable.

Diagnostics from the planner can tell apart explicit activation signals from manifest ownership fallbacks. For instance, activation-command-hint signals that activation.onCommands was a match, whereas manifest-command-alias indicates the planner relied on commandAliases ownership instead. These reason tags serve host diagnostics and tests; plugin authors should continue declaring the metadata that best reflects ownership.

qaRunners reference

When a plugin provides one or more transport runners under the shared openclaw qa root, use qaRunners. Keep this metadata lightweight and static; actual CLI registration remains with the plugin runtime via a minimal qa-runner-api.ts surface that exports corresponding qaRunnerCliRegistrations. For plugins adopting the shipped runtime-api.ts contract, that legacy surface stays accepted until 2026-10-01 while migration proceeds. An optional adapterFactory makes the transport available for shared QA scenarios without altering the registered command's runner.

Module-backed flow scenarios represent an adapter-owned execution mode. Assign adapterFactory.supportsModuleFlows to true only when every adapter produced by that factory implements prepareFlow; QA planning omits module flows from implementations that do not declare support.

{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
    }
  ]
}

The adapterFactory id must align with commandName. Do not export registrations for commands that are missing from the manifest.

setup reference

Use setup when setup and onboarding surfaces need inexpensive plugin-owned metadata before runtime loads.

{
  "setup": {
    "providers": [
      {
        "id": "openai",
        "authMethods": ["api-key"],
        "envVars": ["OPENAI_API_KEY"],
        "authEvidence": [
          {
            "type": "local-file-with-env",
            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",
            "requiresAllEnv": ["OPENAI_PROJECT"],
            "credentialMarker": "openai-local-credentials",
            "source": "openai local credentials"
          }
        ]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}

Top-level cliBackends remains valid and continues to describe CLI inference backends. setup.cliBackends serves as the setup-specific descriptor surface for control-plane/setup flows that should stay metadata-only.

When present, setup.providers and setup.cliBackends become the preferred descriptor-first lookup surface for setup discovery. If the descriptor only narrows the candidate plugin and setup still requires richer setup-time runtime hooks, set requiresRuntime: true and retain setup-api as the fallback execution path.

OpenClaw includes setup.providers[].envVars in generic provider auth and env-var lookups. Place setup and status env metadata there.

Use providerUsageAuthEnvVars when a billing or organization-level credential must activate resolveUsageAuth without becoming an inference credential. These names join workspace dotenv blocking, ACP child-process stripping, sandbox secret filtering, and broad secret scrubbing. The provider runtime still reads and classifies the value inside resolveUsageAuth.

OpenClaw can also derive simple setup choices from setup.providers[].authMethods when no setup entry is available, or when setup.requiresRuntime: false declares setup runtime unnecessary. Explicit providerAuthChoices entries remain preferred for custom labels, CLI flags, onboarding scope, and assistant metadata.

Set requiresRuntime: false only when those descriptors are sufficient for the setup surface. OpenClaw treats explicit false as a descriptor-only contract and will not execute setup-api or openclaw.setupEntry for setup lookup. If a descriptor-only plugin still ships one of those setup runtime entries, OpenClaw reports an additive diagnostic and continues ignoring it. Omitted requiresRuntime keeps legacy fallback behavior so existing plugins that added descriptors without the flag do not break.

Because setup lookup can execute plugin-owned setup-api code, normalized setup.providers[].id and setup.cliBackends[] values must stay unique across discovered plugins. Ambiguous ownership fails closed instead of picking a winner from discovery order.

When setup runtime executes, setup registry diagnostics report providers or CLI backends that setup-api registers without matching manifest declarations. CLI backend descriptors also report a missing runtime registration because setup lookup needs the registered backend configuration. Provider descriptors may remain metadata-only even when the same setup module contributes migrations, CLI backends, probes, or selected provider runtimes.

setup.providers reference

authEvidence handles provider-specific local credential markers that can be verified without loading runtime code. These checks must remain inexpensive and local: no network requests, no keychain or secret-manager access, no shell commands, and no provider API calls.

Supported evidence entries:

setup fields

uiHints reference

uiHints maps config field names to small rendering hints. Keys may use dots for nested config fields, but no path segment can be __proto__, constructor, or prototype; setup rejects those names.

{
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "help": "Used for OpenRouter requests",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}

Each field hint can include:

Channel configuration sections pick up help for the leaf settings that every channel has in common (enabled, allowFrom, dmPolicy, groupPolicy, streaming, and the like), both at the channel root and beneath accounts.<id>. If a channel defines its own help for any of those keys, that definition takes precedence, so supply an override whenever the default wording doesn't fit your provider. Credentials, hosts, webhooks, and other provider-specific keys continue to require their own hints.

contracts reference

Reserve contracts strictly for static capability ownership metadata that OpenClaw can access without loading the plugin runtime.

{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "codex"],
    "trustedToolPolicies": ["workflow-budget"],
    "externalAuthProviders": ["acme-ai"],
    "embeddingProviders": ["openai-compatible"],
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "musicGenerationProviders": ["stability-audio"],
    "documentExtractors": ["example-docs"],
    "webContentExtractors": ["firecrawl"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "workerProviders": ["example-worker"],
    "usageProviders": ["acme-ai"],
    "migrationProviders": ["hermes"],
    "gatewayMethodDispatch": ["authenticated-request"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

Every list is optional. For speechProviders and realtimeVoiceProviders, put the canonical provider ID first, then any aliases tied to that capability:

contracts.embeddedExtensionFactories remains in place for bundled Codex app-server-only extension factories. Tool-result transforms that ship bundled should instead declare contracts.agentToolResultMiddleware and register through api.registerAgentToolResultMiddleware(...). Installed plugins can tap the same middleware seam only when explicitly enabled and solely for runtimes they list in contracts.agentToolResultMiddleware.

For installed plugins requiring the host-trusted pre-tool policy tier, each registered local id must be declared in contracts.trustedToolPolicies and explicitly enabled. Bundled plugins continue using the existing trusted-policy path, yet installed plugins with undeclared policy ids face rejection prior to registration. Policy ids are scoped to the registering plugin, so two plugins can both declare and register workflow-budget; a single plugin cannot register the same local id twice.

Runtime api.registerTool(...) registrations have to align with contracts.tools. Tool discovery consults this list to load only the plugin runtimes capable of owning the requested tools.

Provider plugins implementing resolveExternalAuthProfiles should declare contracts.externalAuthProviders; external-auth hooks left undeclared are ignored.

Provider plugins implementing both resolveUsageAuth and fetchUsageSnapshot should declare each auto-discovered provider id in contracts.usageProviders. Usage discovery reads this contract before runtime code loads, then checks both hooks after loading only the declared owners.

Embedding providers must declare contracts.embeddingProviders for each adapter registered with api.registerEmbeddingProvider(...). The same generic contract serves reusable vector generation and memory search. The retired contracts.memoryEmbeddingProviders key is no longer accepted.

Worker providers must declare each api.registerWorkerProvider(...) id in contracts.workerProviders. Core persists durable intent before calling provision; providers validate their settings and any optional per-dispatch machineClass before external allocation, and repeated calls with the same operation id must adopt the same lease. Providers may implement asynchronous listMachineOptions(profile) to expose process-stable picker metadata; omit it when machine selection is not meaningful. Machine options contain only id, label, optional positive-integer cpu and memoryGb, and optional default. Providers used for session placement must declare exactly one supportedExecutionModes value: worker-turn providers return node leases and remote-exec providers return SSH leases. Omission advertises no session-placement modes while leaving direct lifecycle operations available. Providers whose bounded provisioning exceeds core's five-minute default may implement resolveProvisionTimeoutMs(profile) and include acquisition, provider-owned setup, and cleanup in the returned positive millisecond budget. Core also persists that validated settings snapshot and passes it with leaseId to inspect({ leaseId, profile }) and destroy({ leaseId, profile }), including after the named profile is changed or removed. Destruction is idempotent, inspection returns the closed active / destroyed / unknown status union, and SSH private-key material is referenced only through SecretRef. Provisioned SSH endpoints must also include a public hostKey from trusted provisioning output as exactly algorithm base64, without a hostname or comment, so core can pin the host before connecting. They may include up to 10 ordered, unique fallbackPorts, excluding the primary port; core persists those candidates and rotates among them only for idempotent probes, content-addressed transfers, receipt/lock-guarded artifact installation, convergent managed-worktree mirroring, and tunnel reconnects. Ambiguous unguarded stateful commands fail closed and are not replayed across candidates. A lease may set sharedHost: true when the SSH account also owns unrelated processes; core then avoids host-wide process freezing during workspace reconciliation. Omitted or false means a dedicated worker host. Active inspection repeats this fact so core can reconcile provider-owned isolation for leases persisted before the field existed; tunnel startup waits for that first authoritative inspection. Optional desktop metadata may advertise up to eight unique closed apps: browser with an absolute executablePath and a CDP port from 1 through 65535, or terminal with an absolute executablePath. Core rejects unknown app ids and fields and persists the validated metadata with the existing desktop record. Providers that mint dynamic identity refs may implement authoritative resolveSshIdentity({ leaseId, profile, keyRef }); providers without it use core's generic secret resolver. An authoritative unknown orphans an active local record; after a persisted destroy request it confirms teardown.

contracts.gatewayMethodDispatch currently accepts "authenticated-request". It is an API hygiene gate for native plugin HTTP routes that intentionally dispatch Gateway control-plane methods in-process, not a sandbox against malicious native plugins. Use it only for tightly reviewed bundled/operator surfaces that already require Gateway HTTP auth. An entitled route remains reachable while Gateway root-work admission is closed only when it also declares auth: "gateway" and the route-specific gatewayRuntimeScopeSurface: "trusted-operator"; ordinary sibling routes from the same plugin remain behind the admission boundary. This keeps suspension status and resume reachable without granting the whole plugin an admission bypass. Keep parsing and response shaping bounded outside dispatch; substantive or mutating work must go through Gateway method dispatch, which owns admission and scope enforcement.

configContracts reference

Use configContracts for manifest-owned config behavior that generic core helpers need without importing plugin runtime: dangerous-flag detection, SecretRef migration targets, and legacy config-path narrowing.

{
  "configContracts": {
    "compatibilityMigrationPaths": ["legacyProvider"],
    "compatibilityRuntimePaths": ["legacyProvider.webhook"],
    "dangerousFlags": [
      {
        "path": "accounts.*.allowUnverifiedSenders",
        "equals": true
      }
    ],
    "secretInputs": {
      "bundledDefaultEnabled": false,
      "paths": [
        {
          "path": "routes.*.secret",
          "expected": "string",
          "ownerKind": "route"
        }
      ]
    }
  }
}

Each dangerousFlags entry supports:

secretInputs supports:

mediaUnderstandingProviderMetadata reference

Employ 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:

channelConfigs reference

Apply channelConfigs when a channel plugin needs cheap config metadata before runtime loads. Read-only channel setup/status discovery can use this metadata directly for configured external channels when no setup entry is available, or when setup.requiresRuntime: false declares setup runtime unnecessary.

channelConfigs is plugin manifest metadata, not a new top-level user config section. Users still configure channel instances under channels.<channel-id>. OpenClaw reads manifest metadata to decide which plugin owns that configured channel before plugin runtime code executes.

For a channel plugin, configSchema and channelConfigs describe different paths:

• configSchema validates plugins.entries.<plugin-id>.config
• channelConfigs.<channel-id>.schema validates channels.<channel-id>

Non-bundled plugins that declare channels[] should also declare matching channelConfigs entries. Without them, OpenClaw can still load the plugin, but cold-path config schema, setup, and Control UI surfaces cannot know the channel-owned option shape or display-only UI hints until plugin runtime executes.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled and nativeSkillsAutoEnabled are able to set static auto defaults for command configuration validation that occurs prior to channel runtime initialization. Channels that ship with the package can also expose these same defaults via package.json#openclaw.channel.commands alongside their other channel catalog metadata owned by the package.

{
  "channelConfigs": {
    "matrix": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "homeserverUrl": { "type": "string" }
        }
      },
      "uiHints": {
        "homeserverUrl": {
          "label": "Homeserver URL",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Matrix homeserver connection",
      "commands": {
        "nativeCommandsAutoEnabled": true,
        "nativeSkillsAutoEnabled": true
      },
      "preferOver": ["matrix-legacy"]
    }
  }
}

Each channel entry has the following optional fields:

Replacing another channel plugin

Reach for preferOver when your plugin should be the designated owner for a channel id that another plugin is also capable of supplying. Typical scenarios include a renamed plugin id, a standalone plugin replacing a bundled one, or a maintained fork that preserves the same channel id for configuration compatibility.

{
  "id": "acme-chat",
  "channels": ["chat"],
  "channelConfigs": {
    "chat": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "webhookUrl": { "type": "string" }
        }
      },
      "preferOver": ["chat"]
    }
  }
}

When channels.chat is set, OpenClaw evaluates both the channel id and the preferred plugin id. If the lower-priority plugin was chosen only due to being bundled or enabled by default, OpenClaw removes it from the effective runtime config, leaving a single plugin in charge of the channel and its tools. Explicit user selection takes precedence: when the user deliberately enables both plugins (through plugins.allow or a concrete plugins.entries config), OpenClaw keeps that selection intact and flags duplicate channel/tool diagnostics instead of quietly altering the requested plugin set.

Restrict preferOver to plugin ids that genuinely offer the same channel. It is not a catch-all priority field, nor does it rename user configuration keys.

modelSupport reference

Employ modelSupport when OpenClaw should deduce your provider plugin from shorthand model identifiers such as gpt-5.6-sol or claude-sonnet-4.6 before the plugin runtime loads.

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

OpenClaw applies the following order of precedence:

• explicit provider/model refs rely on the owning providers manifest metadata
• modelPatterns take priority over modelPrefixes
• when one non-bundled plugin and one bundled plugin both match, the non-bundled plugin is chosen
• any remaining ambiguity is left unresolved until the user or config designates a provider

Fields:

modelPatterns entries are processed through compileSafeRegex, which rejects patterns with nested repetition, such as (a+)+$. Patterns failing this safety check are silently omitted, just like regex that is syntactically invalid. Keep patterns straightforward and steer clear of nested quantifiers.

modelCatalog reference

Use modelCatalog when OpenClaw needs provider model metadata ahead of plugin runtime loading. This serves as the manifest-owned source for fixed catalog rows, provider aliases, suppression rules, and discovery mode. Runtime refresh still lives in provider runtime code, but the manifest signals to core when runtime becomes necessary.

{
  "providers": ["openai"],
  "modelCatalog": {
    "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:

aliases takes part 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 takes the place of the earlier provider runtime suppressBuiltInModel hook. Suppression entries take effect only when the plugin owns the provider, or when the provider is set as a modelCatalog.aliases key pointing to an owned one. Model resolution no longer triggers runtime suppression hooks.

Provider fields:

Model fields:

Fields for suppression:

upstreamModel designates a row that points to the same upstream model as a differently named row in another bundled catalog, such as a subscription endpoint alongside the vendor's API endpoint. This is authoring metadata: normalization discards it, and a contract test relies on it to prevent capability flags like compat.codeMode from diverging across catalogs that share the model. Most rows don't need a marker, since matching ignores a leading vendor namespace and casing: moonshotai/kimi-k3 and zai-org/GLM-5.2 already align with the first-party kimi-k3 and glm-5.2 rows. Only when the vendor's names are truly distinct should you turn to upstreamModel. Check Code mode.

Avoid placing runtime-only data in modelCatalog. Use static only when manifest rows are sufficiently complete for provider-filtered list and picker surfaces to bypass registry/runtime discovery. Use refreshable when manifest rows serve as useful listable seeds or supplements, but a refresh/cache can later add more rows; refreshable rows are not authoritative on their own. Use runtime when OpenClaw must load provider runtime to determine the list.

modelIdNormalization reference

Use modelIdNormalization for inexpensive provider-owned model-id cleanup that must run before provider runtime loads. This keeps aliases like short model names, provider-local legacy ids, and proxy prefix rules in the owning plugin manifest rather than in core model-selection tables.

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

Provider fields:

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.

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:

secretProviderIntegrations reference

Use secretProviderIntegrations when a plugin can publish a reusable SecretRef exec provider preset. OpenClaw reads this metadata before plugin runtime loads, stores plugin ownership in secrets.providers.<alias>.pluginIntegration, and leaves actual secret resolution to the SecretRef runtime. Presets are exposed only for bundled plugins and installed plugins discovered from the managed plugin install roots, such as git and ClawHub installs.

{
  "secretProviderIntegrations": {
    "secret-store": {
      "providerAlias": "team-secrets",
      "displayName": "Team secrets",
      "source": "exec",
      "command": "${node}",
      "args": ["./bin/resolve-secrets.mjs"]
    }
  }
}

The integration id serves as the map key. When providerAlias is not provided, OpenClaw treats the integration id as the SecretRef provider alias. Provider aliases need to conform to the standard SecretRef provider alias format, such as team-secrets or onepassword-work.

Upon preset selection by an operator, OpenClaw generates a provider reference in this form:

{
  "secrets": {
    "providers": {
      "team-secrets": {
        "source": "exec",
        "pluginIntegration": {
          "pluginId": "acme-secrets",
          "integrationId": "secret-store"
        }
      }
    }
  }
}

During startup or reload, OpenClaw resolves that provider by pulling the latest plugin manifest metadata, verifying the owning plugin is both installed and active, and building the exec command from the manifest contents. If the plugin gets disabled or removed, the provider is revoked for any active SecretRefs. For standalone exec setups, operators can still create manual command/args providers on their own.

At this time, only source: "exec" presets are supported. command has to be ${node}, while args[0] needs to be a ./ resolver script that is relative to the plugin root. OpenClaw resolves it at startup or reload to the current Node executable along with the absolute in-plugin script path. Node options like --require, --import, --loader, --env-file, --eval, and --print fall outside the manifest preset contract. Operators requiring non-Node commands can set up standalone manual exec providers directly.

For manifest presets, OpenClaw computes trustedDirs from the plugin root, and for ${node} presets, from the current Node executable directory. Any trustedDirs authored in the manifest are disregarded. Additional exec provider options, including timeoutMs, noOutputTimeoutMs, maxOutputBytes, jsonOnly, env, and passEnv, are forwarded to the standard SecretRef exec provider configuration.

modelPricing reference

When the hosted catalog publisher needs provider-specific pricing-key behavior, modelPricing is the tool to use. The publisher accesses this metadata without importing any provider runtime code.

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

Provider fields:

Source fields:

OpenClaw Provider Index

The OpenClaw Provider Index is preview metadata owned by OpenClaw for providers whose plugins might not be installed yet. It does not belong to any plugin manifest. Plugin manifests continue to be the authority for installed plugins. The Provider Index acts as the internal fallback contract that upcoming installable-provider and pre-install model picker surfaces will rely on when a provider plugin is absent.

Catalog authority order:

1. User config.
2. Installed plugin manifest modelCatalog.
3. Model catalog cache from explicit refresh.
4. OpenClaw Provider Index preview rows.

The Provider Index must avoid storing secrets, enabled state, runtime hooks, or live account-specific model data. Its preview catalogs adopt the same modelCatalog provider row shape as plugin manifests, yet should stick to stable display metadata unless runtime adapter fields such as api, baseUrl, pricing, or compatibility flags are deliberately kept in sync with the installed plugin manifest. Providers that rely on live /models discovery should push refreshed rows through the explicit model catalog cache path rather than having normal listing or onboarding call provider APIs.

Provider Index entries can also include installable-plugin metadata for providers whose plugin has left core or is otherwise not yet installed. This metadata follows the channel catalog pattern: package name, npm install spec, expected integrity, and basic auth-choice labels suffice to present an installable setup option. Once the plugin is installed, its manifest takes precedence and the Provider Index entry is disregarded for that provider.

openclaw doctor --fix handles the migration of a limited set of legacy top-level manifest capability keys into contracts.*: speechProviders, mediaUnderstandingProviders, imageGenerationProviders, and tools. These keys, along with any other capability lists, are no longer read as top-level manifest fields; standard manifest loading only recognizes them within contracts.

Manifest versus package.json

Each of the two files has a distinct purpose:

When uncertain about where a piece of metadata belongs, apply this guideline:

• if OpenClaw needs it before plugin code is loaded, place it in openclaw.plugin.json
• if it concerns packaging, entry files, or npm install behavior, place it in package.json

package.json fields that affect discovery

Certain pre-runtime plugin metadata is intentionally stored in package.json under the openclaw block rather than in openclaw.plugin.json. openclaw.bundle and openclaw.bundle.json are not part of OpenClaw's plugin contracts; native plugins must rely on openclaw.plugin.json along with the supported package.json#openclaw fields listed below.

Key examples:

Before runtime loads, manifest metadata determines which provider, channel, and setup options appear during onboarding. package.json#openclaw.install instructs onboarding on how to fetch or enable a plugin when the user selects one of those options. Install hints must not be moved into openclaw.plugin.json.

Configured startup plugins register HTTP routes from their full runtime only after the Gateway begins listening. Until startup sidecars are ready, an otherwise-unclaimed HTTP request returns 503 with Retry-After: 1; core routes stay available throughout the startup process.

For openclaw.channel.cliAddOptions, use Commander's long-option syntax, such as --initial-sync-limit <n>. Configure valueType: "int" to handle a non-negative integer, or use valueType: "list" to break comma-, semicolon-, or newline-separated input into strings before the plugin setup adapter receives it. Leave out valueType to forward the parsed Commander value without modification.

During install and manifest registry loading for non-bundled plugin sources, openclaw.install.minHostVersion is enforced. Invalid values get rejected; newer-but-valid values cause external plugins to be skipped on older hosts. Bundled source plugins are treated as co-versioned with the host checkout.

For npm packages that expose required native binaries through optional, platform-specific aliases, use openclaw.install.requiredPlatformPackages. Provide the bare npm package name for each supported platform alias. During npm install, OpenClaw checks only the declared alias whose lockfile constraints match the current host. If npm reports success but that alias is absent, OpenClaw retries once with a fresh cache and rolls back the install if the alias remains missing.

openclaw.compat.pluginApi is enforced during package install for non-bundled plugin sources. Apply it for the minimum OpenClaw plugin SDK/runtime API version the package was built against. It may be stricter than minHostVersion when a plugin package requires a newer API while still maintaining a lower install hint for other flows. Official OpenClaw release sync bumps existing official plugin API floors to the OpenClaw release version by default, but plugin-only releases can keep a lower floor when the package deliberately supports older hosts. Do not rely on the package version alone as the compatibility contract. peerDependencies.openclaw remains npm package metadata; OpenClaw uses the openclaw.compat.pluginApi contract for install compatibility decisions.

For official install-on-demand metadata, use clawhubSpec when the plugin is published on ClawHub; onboarding treats that as the preferred remote source and records ClawHub artifact facts after install. npmSpec remains the compatibility fallback for packages that have not yet moved to ClawHub.

Exact npm version pinning already resides in npmSpec, for example "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Official external catalog entries should pair exact specs with expectedIntegrity so update flows fail closed if the fetched npm artifact no longer matches the pinned release. Interactive onboarding still offers trusted registry npm specs, including bare package names and dist-tags, for compatibility. Catalog diagnostics can distinguish exact, floating, integrity-pinned, missing-integrity, package-name mismatch, and invalid default-choice sources. They also warn when expectedIntegrity is present but there is no valid npm source it can pin. When expectedIntegrity is present, install/update flows enforce it; when omitted, the registry resolution is recorded without an integrity pin.

Channel plugins should provide openclaw.setupEntry when status, channel list, or SecretRef scans need to identify configured accounts without loading the full runtime. The setup entry should expose channel metadata plus setup-safe config, status, and secrets adapters; keep network clients, gateway listeners, and transport runtimes in the main extension entrypoint.

Runtime entrypoint fields do not override package-boundary checks for source entrypoint fields. For example, openclaw.runtimeExtensions cannot make an escaping openclaw.extensions path loadable.

openclaw.install.allowInvalidConfigRecovery is deliberately narrow. It does not make arbitrary broken configs installable. Today it only allows install flows to recover from specific stale bundled-plugin upgrade failures, such as a missing bundled plugin path or a stale channels.<id> entry for that same bundled plugin. Unrelated config errors still block install and send operators to openclaw doctor --fix.

openclaw.channel.persistedAuthState is package metadata for a tiny checker module:

{
  "openclaw": {
    "channel": {
      "id": "whatsapp",
      "persistedAuthState": {
        "specifier": "./auth-presence",
        "exportName": "hasAnyWhatsAppAuth"
      }
    }
  }
}

Use it when setup, doctor, status, or read-only presence flows need a cheap yes/no auth probe before the full channel plugin loads. Persisted auth state is not configured channel state: do not use this metadata to auto-enable plugins, repair runtime dependencies, or decide whether a channel runtime should load. The target export should be a small function that reads persisted state only; do not route it through the full channel runtime barrel.

openclaw.channel.configuredState supports cheap configured checks. Prefer declarative env metadata when environment variables are sufficient:

{
  "openclaw": {
    "channel": {
      "id": "telegram",
      "configuredState": {
        "env": {
          "allOf": ["TELEGRAM_BOT_TOKEN"]
        }
      }
    }
  }
}

Use env.allOf when every listed variable is required and env.anyOf when any one non-empty variable is enough. If a tiny non-runtime check needs more than environment metadata, use specifier plus exportName as shown for persistedAuthState; when env is present, OpenClaw uses it without loading that module. If the check needs full config resolution or the real channel runtime, keep that logic in the plugin config.hasConfiguredState hook instead.

Discovery precedence (duplicate plugin ids)

OpenClaw discovers plugins from three roots, checked in this order: bundled plugins shipped with OpenClaw, the global install root (~/.openclaw/extensions), and the current workspace root (<workspace>/.openclaw/extensions), plus any explicit plugins.load.paths entries.

If two discoveries share the same id, only the highest-precedence manifest is kept; lower-precedence duplicates are dropped instead of loading beside it. Precedence, highest to lowest:

1. Config-selected, a path explicitly pinned in plugins.entries.<id>
2. Global install matching a tracked install record, a plugin installed via openclaw plugin install/openclaw plugin update that OpenClaw's install tracking recognizes for that same id, even when the id also belongs to a bundled plugin
3. Bundled, plugins shipped with OpenClaw
4. Workspace, plugins discovered relative to the current workspace
5. Any other discovered candidate

Implications:

• A forked or stale copy of a bundled plugin sitting untracked in the workspace or global root will not shadow the bundled build.
• To override a bundled plugin, either run openclaw plugin install for that id so the tracked global install outranks the bundled copy, or pin a specific path via plugins.entries.<id> so it wins by config-selected precedence.
• Duplicate drops are logged so Doctor and startup diagnostics can point at the discarded copy.
• Config-selected duplicate overrides are worded as explicit overrides in diagnostics, but still warn so stale forks and accidental shadows stay visible.

JSON Schema requirements

• Every plugin must ship a JSON Schema, even if it accepts no config.
• An empty schema is acceptable (for example, { "type": "object", "additionalProperties": false }).
• Schemas are validated at config read/write time, not at runtime.
• When extending or forking a bundled plugin with new config keys, update that plugin's openclaw.plugin.json configSchema at the same time. Bundled plugin schemas are strict, so adding plugins.entries.<id>.config.myNewKey in user config without adding myNewKey to configSchema.properties will be rejected before the plugin runtime loads.

Example schema extension:

{
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "myNewKey": {
        "type": "string"
      }
    }
  }
}

Validation behavior

• Encountering an channels.* key that isn't recognized counts as an error, unless a plugin manifest declares the channel id. When that same id shows up in plugins.allow, plugins.entries, or plugins.installs (a plugin that is referenced but not currently discoverable), OpenClaw reduces this to a warning.
• References in plugins.entries.<id>, plugins.allow, and plugins.deny to plugin ids that don't exist are treated as warnings ("stale config entry ignored") rather than errors, so gateway startup isn't blocked by upgrades or plugins that have been removed or renamed.
• An plugins.slots.memory that points to an unknown plugin id results in an error, with the exception of the known memory-lancedb official external plugin, which produces a warning.
• When a plugin is installed but its manifest or schema is missing or corrupted, validation fails and Doctor reports the plugin error.
• If plugin config exists but the plugin is disabled, the config is retained and a warning appears in Doctor and the logs.

Check the Configuration reference for the complete plugins.* schema.

Notes

• Native OpenClaw plugins, including those loaded from the local filesystem, must have a manifest. The runtime still loads the plugin module separately; the manifest serves only discovery and validation purposes.
• Native manifests are parsed using JSON5, meaning comments, trailing commas, and unquoted keys are fine as long as the final value remains an object.
• The manifest loader reads only documented manifest fields. Avoid adding custom top-level keys.
• When a plugin doesn't require them, channels, providers, cliBackends, and skills can all be left out.
• providerCatalogEntry should remain lightweight and avoid importing broad runtime code; reserve it for static provider catalog metadata or narrow discovery descriptors, not request-time execution.
• Exclusive plugin kinds are chosen via plugins.slots.*: kind: "memory" through plugins.slots.memory (defaulting to memory-core), and kind: "context-engine" through plugins.slots.contextEngine (defaulting to legacy).
• Declare the exclusive plugin kind in this manifest. The runtime-entry OpenClawPluginDefinition.kind is deprecated and remains only as a compatibility fallback for older plugins.
• Env-var metadata in setup.providers[].envVars is purely declarative. Status, audit, cron delivery validation, and other read-only surfaces still apply plugin trust and effective activation policy before treating an env var as configured.
• For runtime wizard metadata that needs provider code, refer to Provider runtime hooks.
• If your plugin depends on native modules, document the build steps and any package-manager allowlist requirements (for example, pnpm allow-build-scripts + pnpm rebuild <package>).

Related

• Building plugins, A starting point for working with plugins.

• Plugin architecture, The internal architecture and capability model.

• SDK overview, Plugin SDK reference and subpath imports.