Plugin manifest

Plugin manifest 문서는 OpenClaw 공식 문서(plugins/manifest)를 한국어로 정리한 가이드입니다. Plugin manifest + JSON schema requirements (strict config validation) 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Plugin manifest + JSON schema requirements (strict config validation)

한국어 가이드 범위: plugins/manifest 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

What this file does
Minimal example
Rich example
Top-level field reference
MCP server reference
dashboard reference
catalog reference
Generation provider metadata reference
Tool metadata reference
providerAuthChoices reference
commandAliases reference
activation reference
qaRunners reference
setup reference
setup.providers reference
setup fields
uiHints reference
contracts reference
configContracts reference
mediaUnderstandingProviderMetadata reference
channelConfigs reference
Replacing another channel plugin
modelSupport reference
modelCatalog reference
modelIdNormalization reference
providerEndpoints reference
providerRequest reference
secretProviderIntegrations reference
modelPricing reference
Manifest versus package.json

상세 내용

본문

This page covers the native OpenClaw plugin manifest, openclaw.plugin.json. For compatible bundle layouts (Codex, Claude, Cursor), see Plugin bundles.

주요 항목:

Codex bundle: .codex-plugin/plugin.json
Claude bundle: .claude-plugin/plugin.json, or the default Claude component layout with no manifest
Cursor bundle: .cursor-plugin/plugin.json

What this file does

openclaw.plugin.json is metadata OpenClaw reads before loading your plugin code. Everything in it must be cheap enough to inspect without booting plugin runtime.

주요 항목:

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

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

Field	Required	Type	What it means
`id`	Yes	`string`	Canonical plugin id. This is the id used in `plugins.entries.<id>`.
`configSchema`	Yes	`object`	Inline JSON Schema for this plugin's config.
`requiresPlugins`	No	`string[]`	Plugin ids that must also be installed for this plugin to have an effect. Discovery keeps the plugin loadable but warns when any required plugin is missing.
`enabledByDefault`	No	`true`	Marks a bundled plugin as enabled by default. Omit it, or set any non-`true` value, to leave the plugin disabled by default.
`enabledByDefaultOnPlatforms`	No	`string[]`	Marks a bundled plugin as enabled by default only on the listed Node.js platforms, for example `["darwin"]`. Explicit config still wins.
`legacyPluginIds`	No	`string[]`	Legacy ids that normalize to this canonical plugin id.
`autoEnableWhenConfiguredProviders`	No	`string[]`	Provider ids that should auto-enable this plugin when auth, config, or model refs mention them.
`kind`	No	`PluginKind \| PluginKind[]`	Declares one or more exclusive plugin kinds (`"memory"`, `"context-engine"`) used by `plugins.slots.*`. A plugin that owns both slots declares both kinds in one array.
`channels`	No	`string[]`	Channel ids owned by this plugin. Used for discovery and config validation.
`providers`	No	`string[]`	Provider ids owned by this plugin.
`providerCatalogEntry`	No	`string`	Lightweight provider-catalog 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.
`modelPricing`	No	`object`	Provider-owned external pricing lookup policy. Use it to opt local/self-hosted providers out of remote pricing catalogs or map provider refs to OpenRouter/LiteLLM catalog ids without hardcoding provider ids in core.
`modelIdNormalization`	No	`object`	Provider-owned model-id alias/prefix cleanup that must run before provider runtime loads.
`providerEndpoints`	No	`object[]`	Manifest-owned endpoint host/baseUrl metadata for provider routes that core must classify before provider runtime loads.
`providerRequest`	No	`object`	Cheap provider-family and request-compatibility metadata used by generic request policy before provider runtime loads.
`secretProviderIntegrations`	No	`Record<string, object>`	Declarative SecretRef exec provider presets that setup or install surfaces can offer without hardcoding provider-specific integrations in core.
`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.
`nonSecretAuthMarkers`	No	`string[]`	Bundled-plugin-owned placeholder API key values that represent non-secret local, OAuth, or ambient credential state.
`commandAliases`	No	`object[]`	Command names owned by this plugin that should produce plugin-aware config and CLI diagnostics before runtime loads.
`providerUsageAuthEnvVars`	No	`Record<string, string[]>`	Usage/billing-only provider credentials. OpenClaw uses these names for usage discovery and secret scrubbing but never for inference auth.
`providerAuthAliases`	No	`Record<string, string>`	Provider ids that should reuse another provider id for auth lookup, for example a coding provider that shares the base provider API key and auth profiles.
`providerAuthChoices`	No	`object[]`	Cheap auth-choice metadata for onboarding pickers, preferred-provider resolution, and simple CLI flag wiring.
`activation`	No	`object`	Cheap activation planner metadata for startup, provider, command, channel, route, and capability-triggered loading. Metadata only; plugin runtime still owns actual behavior.
`setup`	No	`object`	Cheap setup/onboarding descriptors that discovery and setup surfaces can inspect without loading plugin runtime.
`qaRunners`	No	`object[]`	Cheap QA runner descriptors used by the shared `openclaw qa` host before plugin runtime loads.
`dashboard`	No	`object`	Dashboard widget data bindings and action verbs. Each entry is validated against a Gateway method registered by this plugin with the required read or write scope. See dashboard reference.
`mcpServers`	No	`Record<string, object>`	Static MCP server definitions contributed while this plugin is enabled. Relative command arguments and working directories resolve from the plugin root. Operator `mcp.servers` entries override or disable definitions with the same name. See MCP server reference.
`contracts`	No	`object`	Static capability ownership snapshot for external auth hooks, embeddings, speech, realtime transcription, realtime voice, media-understanding, image/video/music generation, web fetch, web search, worker providers, document/web-content extraction, and tool ownership.
`configContracts`	No	`object`	Manifest-owned config behavior consumed by generic core helpers: dangerous-flag detection, SecretRef migration targets, and legacy config-path narrowing. See configContracts reference.
`mediaUnderstandingProviderMetadata`	No	`Record<string, object>`	Cheap media-understanding defaults for provider ids declared in `contracts.mediaUnderstandingProviders`.
`imageGenerationProviderMetadata`	No	`Record<string, object>`	Cheap image-generation auth metadata for provider ids declared in `contracts.imageGenerationProviders`, including provider-owned auth aliases and base-url guards.
`videoGenerationProviderMetadata`	No	`Record<string, object>`	Cheap video-generation auth metadata for provider ids declared in `contracts.videoGenerationProviders`, including provider-owned auth aliases and base-url guards.
`musicGenerationProviderMetadata`	No	`Record<string, object>`	Cheap music-generation auth metadata for provider ids declared in `contracts.musicGenerationProviders`, including provider-owned auth aliases and base-url guards.
`toolMetadata`	No	`Record<string, object>`	Cheap availability metadata for plugin-owned tools declared in `contracts.tools`. Use it when a tool should not load runtime unless config, env, or auth evidence exists.
`channelConfigs`	No	`Record<string, object>`	Manifest-owned channel config metadata merged into discovery and validation surfaces before runtime loads.
`skills`	No	`string[]`	Skill directories to load, relative to the plugin root.
`name`	No	`string`	Human-readable plugin name.
`description`	No	`string`	Short summary shown in plugin surfaces.
`catalog`	No	`object`	Optional presentation hints for plugin catalog surfaces. This metadata does not install, enable, or grant trust to a plugin.
`icon`	No	`string`	HTTPS image URL for marketplace/catalog cards. ClawHub accepts any valid `https://` URL and falls back to the default plugin icon when this is omitted or invalid.
`version`	No	`string`	Informational plugin version.
`uiHints`	No	`Record<string, object>`	UI labels, placeholders, and sensitivity hints for config fields.

MCP server reference

mcpServers lets a native plugin ship an MCP server, including an MCP App, without requiring operators to duplicate its static process definition in openclaw.json:

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

dashboard reference

dashboard lets an enabled plugin expose existing Gateway RPCs to granted dashboard widgets without adding plugin policy to core. Data bindings must name a method the same plugin registers with operator.read; action verbs must name a method it registers with operator.write. A mismatch rejects the plugin 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" }
          }
        }
      }
    ]
  }
}

catalog reference

catalog provides optional display hints to plugin browsers. Hosts may ignore these hints. They never install or enable the plugin, and they do not change its runtime behavior or trust level.

Field	Type	What it means
`featured`	`boolean`	Whether catalog surfaces should feature this plugin.
`order`	`number`	Ascending display hint among curated plugins; lower values appear earlier.

{
  "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.

Field	Required	Type	What it means
`aliases`	No	`string[]`	Additional provider ids that should count as static auth aliases for the generation provider.
`authProviders`	No	`string[]`	Provider ids whose configured auth profiles should count as auth for this generation provider.
`configSignals`	No	`object[]`	Cheap config-only availability signals for local or self-hosted providers that can be configured without auth profiles or env vars.
`authSignals`	No	`object[]`	Explicit auth signals. When present, these replace the default signal set from the provider id, `aliases`, and `authProviders`.
`referenceAudioInputs`	No	`boolean`	Video-generation only. Set to `true` when the provider accepts reference audio assets; otherwise `video_generate` hides audio reference parameters.

Field	Required	Type	What it means
`rootPath`	Yes	`string`	Dot path to the plugin-owned config object to inspect, for example `plugins.entries.example.config`.
`overlayPath`	No	`string`	Dot path inside the root config whose object should overlay the root object before evaluating the signal. Use this for capability-specific config such as `image`, `video`, or `music`.
`overlayMapPath`	No	`string`	Dot path inside the root config whose object values should each overlay the root object. Use this for named account maps such as `accounts`, where any configured account should qualify.
`required`	No	`string[]`	Dot paths inside the effective config that must have configured values. Strings must be non-empty; objects and arrays must not be empty.
`requiredAny`	No	`string[]`	Dot paths inside the effective config where at least one must have a configured value.
`mode`	No	`object`	Optional string mode guard inside the effective config. Use this when config-only availability applies only to one mode.

Field	Required	Type	What it means
`path`	No	`string`	Dot path inside the effective config. Defaults to `mode`.
`default`	No	`string`	Mode value to use when the config omits the path.
`allowed`	No	`string[]`	If present, the signal passes only when the effective mode is one of these values.
`disallowed`	No	`string[]`	If present, the signal fails when the effective mode is one of these values.

{
  "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"]
          }
        }
      ]
    }
  }
}

Tool metadata reference

toolMetadata uses the same configSignals and authSignals shapes as generation provider metadata, keyed by tool name. contracts.tools declares ownership. toolMetadata declares cheap availability evidence so OpenClaw can avoid importing a plugin runtime just to have its tool factory return null.

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

providerAuthChoices reference

Each providerAuthChoices entry describes one onboarding or auth choice. OpenClaw reads this before provider runtime loads. Provider setup lists use these manifest choices, descriptor-derived setup choices, and install-catalog metadata without loading provider runtime.

Field	Required	Type	What it means
`provider`	Yes	`string`	Provider id this choice belongs to.
`method`	Yes	`string`	Auth method id to dispatch to.
`choiceId`	Yes	`string`	Stable auth-choice id used by onboarding and CLI flows.
`choiceLabel`	No	`string`	User-facing label. If omitted, OpenClaw falls back to `choiceId`.
`choiceHint`	No	`string`	Short helper text for the picker.
`icon`	No	HTTPS URL	Artwork shown beside this choice in supported onboarding clients.
`website`	No	HTTPS URL	Product, sign-in, or installation page shown by supported onboarding clients.
`assistantPriority`	No	`number`	Lower values sort earlier in assistant-driven interactive pickers.
`assistantVisibility`	No	`"visible"` \| `"manual-only"`	Hide the choice from assistant pickers while still allowing manual CLI selection.
`deprecatedChoiceIds`	No	`string[]`	Legacy choice ids that should redirect users to this replacement choice.
`groupId`	No	`string`	Optional group id for grouping related choices.
`groupLabel`	No	`string`	User-facing label for that group.
`groupHint`	No	`string`	Short helper text for the group.
`onboardingFeatured`	No	`boolean`	Surface this group in the featured tier of the interactive onboarding picker, before the "More..." entry.
`optionKey`	No	`string`	Internal option key for simple one-flag auth flows.
`cliFlag`	No	`string`	CLI flag name, such as `--openrouter-api-key`.
`cliOption`	No	`string`	Full CLI option shape, such as `--openrouter-api-key <key>`.
`cliDescription`	No	`string`	Description used in CLI help.
`appGuidedSecret`	No	`boolean`	One pasted secret plus provider defaults is sufficient for app-guided setup.
`appGuidedDiscovery`	No	`boolean`	The matching runtime auth method owns read-only local discovery through `appGuidedSetup`.
`appGuidedAuth`	No	`"oauth"` \| `"device-code"`	Provider-owned interactive login that native setup clients can render generically.
`onboardingScopes`	No	`Array<"text-inference" \| "image-generation" \| "music-generation">`	Which onboarding surfaces this choice should appear in. If omitted, it defaults to `["text-inference"]`.

commandAliases reference

Use commandAliases when a plugin owns a runtime command name that users may mistakenly put in plugins.allow or try to run as a root CLI command. OpenClaw uses this metadata for diagnostics without importing plugin runtime code.

Field	Required	Type	What it means
`name`	Yes	`string`	Command name that belongs to this plugin.
`kind`	No	`"runtime-slash"`	Marks the alias as a chat slash command rather than a root CLI command.
`cliCommand`	No	`string`	Related root CLI command to suggest for CLI operations, if one exists.

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

activation reference

Use activation when the plugin can cheaply declare which control-plane events should include it in an activation/load plan.

주요 항목:

Gateway startup planning uses activation.onStartup for explicit startup import.
Command-triggered CLI planning falls back to legacy commandAliases[].cliCommand or commandAliases[].name.
Agent-runtime startup planning uses activation.onAgentHarnesses for embedded harnesses and top-level cliBackends[] for CLI runtime aliases.
Channel-triggered setup/channel planning falls back to legacy channels[] ownership when explicit channel activation metadata is missing.
Startup plugin planning uses activation.onConfigPaths for non-channel root config surfaces such as the bundled browser plugin's browser block.
Provider-triggered setup/runtime planning falls back to legacy providers[] and top-level cliBackends[] ownership when explicit provider activation metadata is missing.

Field	Required	Type	What it means
`onStartup`	No	`boolean`	Explicit Gateway startup activation. Every plugin should set this. `true` imports the plugin during startup; `false` keeps it startup-lazy unless another matched trigger requires loading.
`onProviders`	No	`string[]`	Provider ids that should include this plugin in activation/load plans.
`onAgentHarnesses`	No	`string[]`	Embedded agent harness runtime ids that should include this plugin in activation/load plans. Use top-level `cliBackends` for CLI backend aliases.
`onCommands`	No	`string[]`	Command ids that should include this plugin in activation/load plans.
`onChannels`	No	`string[]`	Channel ids that should include this plugin in activation/load plans.
`onRoutes`	No	`string[]`	Route kinds that should include this plugin in activation/load plans.
`onConfigPaths`	No	`string[]`	Root-relative config paths that should include this plugin in startup/load plans when the path is present and not explicitly disabled.
`onCapabilities`	No	`Array<"provider" \| "channel" \| "tool" \| "hook">`	Broad capability hints used by control-plane activation planning. Prefer narrower fields when possible.

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

qaRunners reference

Use qaRunners when a plugin contributes one or more transport runners beneath the shared openclaw qa root. Keep this metadata cheap and static; the plugin runtime still owns actual CLI registration through a lightweight runtime-api.ts surface that exports matching qaRunnerCliRegistrations. An optional adapterFactory exposes the transport to shared QA scenarios without changing the registered command's runner.

Field	Required	Type	What it means
`commandName`	Yes	`string`	Subcommand mounted beneath `openclaw qa`, for example `matrix`.
`description`	No	`string`	Fallback help text used when the shared host needs a stub command.

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

setup reference

Use setup when setup and onboarding surfaces need cheap 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
  }
}

setup.providers reference

authEvidence is for provider-owned local credential markers that can be verified without loading runtime code. These checks must stay cheap and local: no network calls, no keychain or secret-manager reads, no shell commands, and no provider API probes.

Field	Required	Type	What it means
`id`	Yes	`string`	Provider id exposed during setup or onboarding. Keep normalized ids globally unique.
`authMethods`	No	`string[]`	Setup/auth method ids this provider supports without loading full runtime.
`envVars`	No	`string[]`	Env vars that generic setup/status surfaces can check before plugin runtime loads.
`authEvidence`	No	`object[]`	Cheap local auth evidence checks for providers that can authenticate through non-secret markers.

Field	Required	Type	What it means
`type`	Yes	`string`	Currently `local-file-with-env`.
`fileEnvVar`	No	`string`	Env var containing an explicit credential file path.
`fallbackPaths`	No	`string[]`	Local credential file paths checked when `fileEnvVar` is absent or empty. Supports `${HOME}` and `${APPDATA}`.
`requiresAnyEnv`	No	`string[]`	At least one listed env var must be non-empty before the evidence is valid.
`requiresAllEnv`	No	`string[]`	Every listed env var must be non-empty before the evidence is valid.
`credentialMarker`	Yes	`string`	Non-secret marker returned when the evidence is present.
`source`	No	`string`	User-facing source label for auth/status output.

setup fields

Field	Required	Type	What it means
`providers`	No	`object[]`	Provider setup descriptors exposed during setup and onboarding.
`cliBackends`	No	`string[]`	Setup-time backend ids used for descriptor-first setup lookup. Keep normalized ids globally unique.
`configMigrations`	No	`string[]`	Config migration ids owned by this plugin's setup surface.
`requiresRuntime`	No	`boolean`	Whether setup still needs `setup-api` execution after descriptor lookup.

uiHints reference

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

Field	Type	What it means
`label`	`string`	User-facing field label.
`help`	`string`	Short helper text.
`tags`	`string[]`	Optional UI tags.
`advanced`	`boolean`	Marks the field as advanced.
`sensitive`	`boolean`	Marks the field as secret or sensitive.
`placeholder`	`string`	Placeholder text for form inputs.
`presentation`	`"phone-number"`	Display-only localized phone formatting for parseable international (`+...`) values; raw values remain unchanged.

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

contracts reference

Use contracts only for static capability ownership metadata that OpenClaw can read without importing the plugin runtime.

Field	Type	What it means
`embeddedExtensionFactories`	`string[]`	Codex app-server extension factory ids, currently `codex-app-server`.
`agentToolResultMiddleware`	`string[]`	Runtime ids this plugin may register tool-result middleware for.
`trustedToolPolicies`	`string[]`	Plugin-local trusted pre-tool policy ids an installed plugin may register. Bundled plugins may register policies without this field.
`externalAuthProviders`	`string[]`	Provider ids whose external auth profile hook this plugin owns.
`embeddingProviders`	`string[]`	General embedding provider ids this plugin owns for reusable vector embedding use, including memory.
`speechProviders`	`string[]`	Speech provider ids this plugin owns.
`realtimeTranscriptionProviders`	`string[]`	Realtime-transcription provider ids this plugin owns.
`realtimeVoiceProviders`	`string[]`	Realtime-voice provider ids this plugin owns.
`memoryEmbeddingProviders`	`string[]`	Deprecated memory-specific embedding provider ids this plugin owns.
`mediaUnderstandingProviders`	`string[]`	Media-understanding provider ids this plugin owns.
`transcriptSourceProviders`	`string[]`	Transcript source provider ids this plugin owns.
`documentExtractors`	`string[]`	Document (for example PDF) extractor provider ids this plugin owns.
`imageGenerationProviders`	`string[]`	Image-generation provider ids this plugin owns.
`videoGenerationProviders`	`string[]`	Video-generation provider ids this plugin owns.
`musicGenerationProviders`	`string[]`	Music-generation provider ids this plugin owns.
`webContentExtractors`	`string[]`	Web-page content-extraction provider ids this plugin owns.
`webFetchProviders`	`string[]`	Web-fetch provider ids this plugin owns.
`webSearchProviders`	`string[]`	Web-search provider ids this plugin owns.
`workerProviders`	`string[]`	Cloud-worker provider ids this plugin owns for provisioning and profile-backed lease lifecycle.
`usageProviders`	`string[]`	Provider ids whose usage-auth and usage-snapshot hooks this plugin owns.
`migrationProviders`	`string[]`	Import provider ids this plugin owns for `openclaw migrate`.
`gatewayMethodDispatch`	`string[]`	Reserved entitlement for authenticated plugin HTTP routes that dispatch Gateway methods in-process.
`tools`	`string[]`	Agent tool names this plugin owns.

{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "codex"],
    "trustedToolPolicies": ["workflow-budget"],
    "externalAuthProviders": ["acme-ai"],
    "embeddingProviders": ["openai-compatible"],
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "memoryEmbeddingProviders": ["local"],
    "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"]
  }
}

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.

Field	Required	Type	What it means
`compatibilityMigrationPaths`	No	`string[]`	Root-relative config paths that indicate this plugin's setup-time compatibility migrations might apply. Lets generic runtime config reads skip every plugin setup surface when the config never references the plugin.
`compatibilityRuntimePaths`	No	`string[]`	Root-relative compatibility paths this plugin can service during runtime before plugin code fully activates. Use this for legacy surfaces that should narrow bundled candidate sets without importing every compatible plugin runtime.
`dangerousFlags`	No	`object[]`	Config literals that `openclaw doctor` should flag as insecure or dangerous when enabled. See below.
`secretInputs`	No	`object`	Config paths under `plugins.entries.<id>.config` for SecretRef migration, audit, startup materialization, and optional runtime owner isolation. See below.

Field	Required	Type	What it means
`path`	Yes	`string`	Dot-separated config path relative to `plugins.entries.<id>.config`. Supports `*` wildcards for map/array segments.
`equals`	Yes	`string \| number \| boolean \| null`	Exact literal that marks this config value as dangerous.

Field	Required	Type	What it means
`bundledDefaultEnabled`	No	`boolean`	Override bundled-plugin default enablement when deciding whether this SecretRef surface is active. Use this when the plugin is bundled but the surface should stay inactive until explicitly enabled in config.
`paths`	Yes	`object[]`	Secret-shaped config paths, each with `path` (dot-separated, relative to `plugins.entries.<id>.config`, supports `*` wildcards), optional `expected` (currently only `"string"`), and optional `ownerKind` (currently only `"route"`). A declared owner isolates only that exact matched path when resolution fails; its owner id is the full config path.

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

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.

Field	Type	What it means
`capabilities`	`("image" \| "audio" \| "video")[]`	Media capabilities exposed by this provider.
`defaultModels`	`Record<string, string>`	Capability-to-model defaults used when config does not specify a model.
`autoPriority`	`Record<string, number>`	Lower numbers sort earlier for automatic credential-based provider fallback.
`nativeDocumentInputs`	`"pdf"[]`	Native document inputs supported by the provider.
`documentModels`	`{ pdf?: { textExtraction?: string; image?: string \| false } }`	Per-document-type model overrides. Set `image: false` to disable image-based extraction for that document type.

{
  "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"
        }
      }
    }
  }
}

channelConfigs reference

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

주요 항목:

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

Field	Type	What it means
`schema`	`object`	JSON Schema for `channels.<id>`. Required for each declared channel config entry.
`uiHints`	`Record<string, object>`	Optional labels, placeholders, sensitivity, and display-only presentation hints for that channel config section.
`label`	`string`	Channel label merged into picker and inspect surfaces when runtime metadata is not ready.
`description`	`string`	Short channel description for inspect and catalog surfaces.
`commands`	`object`	Static native command and native skill auto-defaults for pre-runtime config checks.
`preferOver`	`string[]`	Legacy or lower-priority plugin ids this channel should outrank in selection surfaces.

{
  "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"]
    }
  }
}

Replacing another channel plugin

Use preferOver when your plugin is the preferred owner for a channel id that another plugin can also provide. Common cases are a renamed plugin id, a standalone plugin that supersedes a bundled plugin, or a maintained fork that keeps the same channel id for config compatibility.

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

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.

주요 항목:

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

Field	Type	What it means
`modelPrefixes`	`string[]`	Prefixes matched with `startsWith` against shorthand model ids.
`modelPatterns`	`string[]`	Regex sources matched against shorthand model ids after profile suffix removal.

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

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.

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.
`runtimeAugment`	`boolean`	Set to `true` only when the provider runtime must append catalog rows after manifest/config planning.

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.
`defaultUtilityModel`	`string`	Optional provider-recommended small model id for short internal utility tasks (titles, progress narration). Used when `agents.defaults.utilityModel` is unset and this provider serves the agent's primary model.
`models`	`object[]`	Required model rows. Rows without an `id` are ignored.

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. Other values are silently dropped.
`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.
`thinkingLevelMap`	`Record<string, string \| null>`	Optional per-thinking-level model-id or param overrides.
`cost`	`object`	Optional USD per million token pricing, including optional `tieredPricing`.
`compat`	`object`	Optional compatibility flags matching OpenClaw model config compatibility.
`mediaInput`	`object`	Optional per-modality input config, currently image-only.
`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.

{
  "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"
    }
  }
}

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.

Field	Type	What it means
`aliases`	`Record<string,string>`	Case-insensitive exact model-id aliases. Values are returned as written.
`stripPrefixes`	`string[]`	Prefixes to remove before alias lookup, useful for legacy provider/model duplication.
`prefixWhenBare`	`string`	Prefix to add when the normalized model id does not already contain `/`.
`prefixWhenBareAfterAliasStartsWith`	`object[]`	Conditional bare-id prefix rules after alias lookup, keyed by `modelPrefix` and `prefix`.

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

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.

Field	Type	What it means
`endpointClass`	`string`	Known core endpoint class, such as `openrouter`, `moonshot-native`, or `google-vertex`.
`hosts`	`string[]`	Exact hostnames that map to the endpoint class.
`hostSuffixes`	`string[]`	Host suffixes that map to the endpoint class. Prefix with `.` for domain suffix-only matching.
`baseUrls`	`string[]`	Exact normalized HTTP(S) base URLs that map to the endpoint class.
`googleVertexRegion`	`string`	Static Google Vertex region for exact global hosts.
`googleVertexRegionHostSuffix`	`string`	Suffix to strip from matching hosts to expose the Google Vertex region prefix.

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.

Field	Type	What it means
`family`	`string`	Provider family label used by generic request compatibility decisions and diagnostics.
`compatibilityFamily`	`"moonshot"`	Optional provider-family compatibility bucket for shared request helpers.
`openAICompletions`	`object`	OpenAI-compatible completions request flags, currently `supportsStreamingUsage`.

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

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..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"]
    }
  }
}

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

modelPricing reference

Use modelPricing when a provider needs control-plane pricing behavior before runtime loads. The Gateway pricing cache reads this metadata without importing provider runtime code.

Field	Type	What it means
`external`	`boolean`	Set `false` for local/self-hosted providers that should never fetch OpenRouter or LiteLLM pricing.
`openRouter`	`false \| object`	OpenRouter pricing lookup mapping. `false` disables OpenRouter lookup for this provider.
`liteLLM`	`false \| object`	LiteLLM pricing lookup mapping. `false` disables LiteLLM lookup for this provider.

Field	Type	What it means
`provider`	`string`	External catalog provider id when it differs from the OpenClaw provider id, for example `z-ai` for a `zai` provider.
`passthroughProviderModel`	`boolean`	Treat slash-containing model ids as nested provider/model refs, useful for proxy providers such as OpenRouter.
`modelIdTransforms`	`"version-dots"[]`	Extra external catalog model-id variants. `version-dots` tries dotted version ids like `claude-opus-4.6`.

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

OpenClaw Provider Index

The OpenClaw Provider Index is OpenClaw-owned preview metadata for providers whose plugins may not be installed yet. It is not part of a plugin manifest. Plugin manifests remain the installed-plugin authority. The Provider Index is the internal fallback contract that future installable-provider and pre-install model picker surfaces will consume when a provider plugin is not installed.

Manifest versus package.json

If you are unsure where a piece of metadata belongs, use this rule:

주요 항목:

if OpenClaw must know it before loading plugin code, put it in openclaw.plugin.json
if it is about packaging, entry files, or npm install behavior, put it in package.json

File	Use it for
`openclaw.plugin.json`	Discovery, config validation, auth-choice metadata, and UI hints that must exist before plugin code runs
`package.json`	npm metadata, dependency installation, and the `openclaw` block used for entrypoints, install gating, setup, or catalog metadata

package.json fields that affect discovery

Some pre-runtime plugin metadata intentionally lives in package.json under the openclaw block instead of openclaw.plugin.json. openclaw.bundle and openclaw.bundle.json are not OpenClaw plugin contracts; native plugins must use openclaw.plugin.json plus the supported package.json#openclaw fields below.

Field	What it means
`openclaw.extensions`	Declares native plugin entrypoints. Must stay inside the plugin package directory.
`openclaw.runtimeExtensions`	Declares built JavaScript runtime entrypoints for installed packages. Must stay inside the plugin package directory.
`openclaw.setupEntry`	Lightweight setup-only entrypoint used during onboarding, deferred channel startup, and read-only channel status/SecretRef discovery. Must stay inside the plugin package directory.
`openclaw.runtimeSetupEntry`	Declares the built JavaScript setup entrypoint for installed packages. Requires `setupEntry`, must exist, and must stay inside the plugin package directory.
`openclaw.channel`	Cheap channel catalog metadata like labels, docs paths, aliases, and selection copy.
`openclaw.channel.approvalFlags`	Closed approval behavior flags available before runtime load. `native` means the channel owns native approval UI and same-turn resolution.
`openclaw.channel.commands`	Static native command and native skill auto-default metadata used by config, audit, and command-list surfaces before channel runtime loads.
`openclaw.channel.cliAddOptions`	Plugin-owned `openclaw channels add` options. Each entry declares `flags`, `description`, optional `defaultValue`, and optional `valueType` (`int` or `list`) for generic input coercion.
`openclaw.channel.configuredState`	Lightweight configured-state checker metadata that can answer "does env-only setup already exist?" without loading the full channel runtime.
`openclaw.channel.persistedAuthState`	Lightweight persisted-auth checker metadata that can answer "is anything already signed in?" without loading the full channel runtime.
`openclaw.install.clawhubSpec` / `openclaw.install.npmSpec` / `openclaw.install.localPath`	Install/update hints for bundled and externally published plugins.
`openclaw.install.defaultChoice`	Preferred install path when multiple install sources are available.
`openclaw.install.minHostVersion`	Minimum supported OpenClaw host version, using a semver floor like `>=2026.3.22` or `>=2026.5.1-beta.1`.
`openclaw.compat.pluginApi`	Minimum OpenClaw plugin API range required by this package, using a semver floor like `>=2026.5.27`.
`openclaw.install.expectedIntegrity`	Expected npm dist integrity string such as `sha512-...`; install and update flows verify the fetched artifact against it.
`openclaw.install.allowInvalidConfigRecovery`	Allows a narrow bundled-plugin reinstall recovery path when config is invalid.
`openclaw.install.requiredPlatformPackages`	npm package aliases that must materialize when their lockfile platform constraints match the current host.
`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`	Lets setup-runtime channel surfaces load before listen, then defers the full configured channel plugin until post-listen activation.

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

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

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 (/.openclaw/extensions), plus any explicit plugins.load.paths entries.

주요 항목:

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 plugins 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 (예를 들어, { "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.

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

Validation behavior

See Configuration reference for the full plugins.* schema.

주요 항목:

Unknown channels.* keys are errors, unless the channel id is declared by a plugin manifest. If the same id also appears in plugins.allow, plugins.entries, or plugins.installs (a plugin that is referenced but not currently discoverable), OpenClaw downgrades this to a warning instead.
plugins.entries.<id>, plugins.allow, and plugins.deny referencing unknown plugin ids are warnings ("stale config entry ignored"), not errors, so upgrades and removed/renamed plugins do not block gateway startup.
plugins.slots.memory referencing an unknown plugin id is an error, except for the known memory-lancedb official external plugin, which warns instead.
If a plugin is installed but has a broken or missing manifest or schema, validation fails and Doctor reports the plugin error.
If plugin config exists but the plugin is disabled, the config is kept and a warning is surfaced in Doctor + logs.

참고

주요 항목:

The manifest is required for native OpenClaw plugins, including local filesystem loads. Runtime still loads the plugin module separately; the manifest is only for discovery + validation.
Native manifests are parsed with JSON5, so comments, trailing commas, and unquoted keys are accepted as long as the final value is still an object.
Only documented manifest fields are read by the manifest loader. Avoid custom top-level keys.
channels, providers, cliBackends, and skills can all be omitted when a plugin does not need them.
providerCatalogEntry must stay lightweight and should not import broad runtime code; use it for static provider catalog metadata or narrow discovery descriptors, not request-time execution.
Exclusive plugin kinds are selected through plugins.slots.*: kind: "memory" via plugins.slots.memory (default memory-core), kind: "context-engine" via plugins.slots.contextEngine (default legacy).
Declare exclusive plugin kind in this manifest. Runtime-entry OpenClawPluginDefinition.kind is deprecated and remains only as a compatibility fallback for older plugins.
Env-var metadata in setup.providers[].envVars is declarative only. 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 requires provider code, see Provider runtime hooks.
If your plugin depends on native modules, document the build steps and any package-manager allowlist requirements (예를 들어, pnpm allow-build-scripts + pnpm rebuild <package>).

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/manifest
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

{
  "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"
      }
    }
  }
}

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

{
  "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" }
          }
        }
      }
    ]
  }
}

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

{
  "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"]
          }
        }
      ]
    }
  }
}

Plugin manifest

핵심 요약

Plugin manifest + JSON schema requirements (strict config validation)

한국어 가이드 범위: plugins/manifest 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

What this file does
Minimal example
Rich example
Top-level field reference
MCP server reference
dashboard reference
catalog reference
Generation provider metadata reference
Tool metadata reference
providerAuthChoices reference
commandAliases reference
activation reference
qaRunners reference
setup reference
setup.providers reference
setup fields
uiHints reference
contracts reference
configContracts reference
mediaUnderstandingProviderMetadata reference
channelConfigs reference
Replacing another channel plugin
modelSupport reference
modelCatalog reference
modelIdNormalization reference
providerEndpoints reference
providerRequest reference
secretProviderIntegrations reference
modelPricing reference
Manifest versus package.json

상세 내용

본문

This page covers the native OpenClaw plugin manifest, openclaw.plugin.json. For compatible bundle layouts (Codex, Claude, Cursor), see Plugin bundles.

주요 항목:

Codex bundle: .codex-plugin/plugin.json
Claude bundle: .claude-plugin/plugin.json, or the default Claude component layout with no manifest
Cursor bundle: .cursor-plugin/plugin.json

What this file does

openclaw.plugin.json is metadata OpenClaw reads before loading your plugin code. Everything in it must be cheap enough to inspect without booting plugin runtime.

주요 항목:

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

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

Field	Required	Type	What it means
`id`	Yes	`string`	Canonical plugin id. This is the id used in `plugins.entries.<id>`.
`configSchema`	Yes	`object`	Inline JSON Schema for this plugin's config.
`requiresPlugins`	No	`string[]`	Plugin ids that must also be installed for this plugin to have an effect. Discovery keeps the plugin loadable but warns when any required plugin is missing.
`enabledByDefault`	No	`true`	Marks a bundled plugin as enabled by default. Omit it, or set any non-`true` value, to leave the plugin disabled by default.
`enabledByDefaultOnPlatforms`	No	`string[]`	Marks a bundled plugin as enabled by default only on the listed Node.js platforms, for example `["darwin"]`. Explicit config still wins.
`legacyPluginIds`	No	`string[]`	Legacy ids that normalize to this canonical plugin id.
`autoEnableWhenConfiguredProviders`	No	`string[]`	Provider ids that should auto-enable this plugin when auth, config, or model refs mention them.
`kind`	No	`PluginKind \| PluginKind[]`	Declares one or more exclusive plugin kinds (`"memory"`, `"context-engine"`) used by `plugins.slots.*`. A plugin that owns both slots declares both kinds in one array.
`channels`	No	`string[]`	Channel ids owned by this plugin. Used for discovery and config validation.
`providers`	No	`string[]`	Provider ids owned by this plugin.
`providerCatalogEntry`	No	`string`	Lightweight provider-catalog 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.
`modelPricing`	No	`object`	Provider-owned external pricing lookup policy. Use it to opt local/self-hosted providers out of remote pricing catalogs or map provider refs to OpenRouter/LiteLLM catalog ids without hardcoding provider ids in core.
`modelIdNormalization`	No	`object`	Provider-owned model-id alias/prefix cleanup that must run before provider runtime loads.
`providerEndpoints`	No	`object[]`	Manifest-owned endpoint host/baseUrl metadata for provider routes that core must classify before provider runtime loads.
`providerRequest`	No	`object`	Cheap provider-family and request-compatibility metadata used by generic request policy before provider runtime loads.
`secretProviderIntegrations`	No	`Record<string, object>`	Declarative SecretRef exec provider presets that setup or install surfaces can offer without hardcoding provider-specific integrations in core.
`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.
`nonSecretAuthMarkers`	No	`string[]`	Bundled-plugin-owned placeholder API key values that represent non-secret local, OAuth, or ambient credential state.
`commandAliases`	No	`object[]`	Command names owned by this plugin that should produce plugin-aware config and CLI diagnostics before runtime loads.
`providerUsageAuthEnvVars`	No	`Record<string, string[]>`	Usage/billing-only provider credentials. OpenClaw uses these names for usage discovery and secret scrubbing but never for inference auth.
`providerAuthAliases`	No	`Record<string, string>`	Provider ids that should reuse another provider id for auth lookup, for example a coding provider that shares the base provider API key and auth profiles.
`providerAuthChoices`	No	`object[]`	Cheap auth-choice metadata for onboarding pickers, preferred-provider resolution, and simple CLI flag wiring.
`activation`	No	`object`	Cheap activation planner metadata for startup, provider, command, channel, route, and capability-triggered loading. Metadata only; plugin runtime still owns actual behavior.
`setup`	No	`object`	Cheap setup/onboarding descriptors that discovery and setup surfaces can inspect without loading plugin runtime.
`qaRunners`	No	`object[]`	Cheap QA runner descriptors used by the shared `openclaw qa` host before plugin runtime loads.
`dashboard`	No	`object`	Dashboard widget data bindings and action verbs. Each entry is validated against a Gateway method registered by this plugin with the required read or write scope. See dashboard reference.
`mcpServers`	No	`Record<string, object>`	Static MCP server definitions contributed while this plugin is enabled. Relative command arguments and working directories resolve from the plugin root. Operator `mcp.servers` entries override or disable definitions with the same name. See MCP server reference.
`contracts`	No	`object`	Static capability ownership snapshot for external auth hooks, embeddings, speech, realtime transcription, realtime voice, media-understanding, image/video/music generation, web fetch, web search, worker providers, document/web-content extraction, and tool ownership.
`configContracts`	No	`object`	Manifest-owned config behavior consumed by generic core helpers: dangerous-flag detection, SecretRef migration targets, and legacy config-path narrowing. See configContracts reference.
`mediaUnderstandingProviderMetadata`	No	`Record<string, object>`	Cheap media-understanding defaults for provider ids declared in `contracts.mediaUnderstandingProviders`.
`imageGenerationProviderMetadata`	No	`Record<string, object>`	Cheap image-generation auth metadata for provider ids declared in `contracts.imageGenerationProviders`, including provider-owned auth aliases and base-url guards.
`videoGenerationProviderMetadata`	No	`Record<string, object>`	Cheap video-generation auth metadata for provider ids declared in `contracts.videoGenerationProviders`, including provider-owned auth aliases and base-url guards.
`musicGenerationProviderMetadata`	No	`Record<string, object>`	Cheap music-generation auth metadata for provider ids declared in `contracts.musicGenerationProviders`, including provider-owned auth aliases and base-url guards.
`toolMetadata`	No	`Record<string, object>`	Cheap availability metadata for plugin-owned tools declared in `contracts.tools`. Use it when a tool should not load runtime unless config, env, or auth evidence exists.
`channelConfigs`	No	`Record<string, object>`	Manifest-owned channel config metadata merged into discovery and validation surfaces before runtime loads.
`skills`	No	`string[]`	Skill directories to load, relative to the plugin root.
`name`	No	`string`	Human-readable plugin name.
`description`	No	`string`	Short summary shown in plugin surfaces.
`catalog`	No	`object`	Optional presentation hints for plugin catalog surfaces. This metadata does not install, enable, or grant trust to a plugin.
`icon`	No	`string`	HTTPS image URL for marketplace/catalog cards. ClawHub accepts any valid `https://` URL and falls back to the default plugin icon when this is omitted or invalid.
`version`	No	`string`	Informational plugin version.
`uiHints`	No	`Record<string, object>`	UI labels, placeholders, and sensitivity hints for config fields.

MCP server reference

mcpServers lets a native plugin ship an MCP server, including an MCP App, without requiring operators to duplicate its static process definition in openclaw.json:

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

dashboard reference

{
  "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" }
          }
        }
      }
    ]
  }
}

catalog reference

catalog provides optional display hints to plugin browsers. Hosts may ignore these hints. They never install or enable the plugin, and they do not change its runtime behavior or trust level.

Field	Type	What it means
`featured`	`boolean`	Whether catalog surfaces should feature this plugin.
`order`	`number`	Ascending display hint among curated plugins; lower values appear earlier.

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

Generation provider metadata reference

Field	Required	Type	What it means
`aliases`	No	`string[]`	Additional provider ids that should count as static auth aliases for the generation provider.
`authProviders`	No	`string[]`	Provider ids whose configured auth profiles should count as auth for this generation provider.
`configSignals`	No	`object[]`	Cheap config-only availability signals for local or self-hosted providers that can be configured without auth profiles or env vars.
`authSignals`	No	`object[]`	Explicit auth signals. When present, these replace the default signal set from the provider id, `aliases`, and `authProviders`.
`referenceAudioInputs`	No	`boolean`	Video-generation only. Set to `true` when the provider accepts reference audio assets; otherwise `video_generate` hides audio reference parameters.

Field	Required	Type	What it means
`rootPath`	Yes	`string`	Dot path to the plugin-owned config object to inspect, for example `plugins.entries.example.config`.
`overlayPath`	No	`string`	Dot path inside the root config whose object should overlay the root object before evaluating the signal. Use this for capability-specific config such as `image`, `video`, or `music`.
`overlayMapPath`	No	`string`	Dot path inside the root config whose object values should each overlay the root object. Use this for named account maps such as `accounts`, where any configured account should qualify.
`required`	No	`string[]`	Dot paths inside the effective config that must have configured values. Strings must be non-empty; objects and arrays must not be empty.
`requiredAny`	No	`string[]`	Dot paths inside the effective config where at least one must have a configured value.
`mode`	No	`object`	Optional string mode guard inside the effective config. Use this when config-only availability applies only to one mode.

Field	Required	Type	What it means
`path`	No	`string`	Dot path inside the effective config. Defaults to `mode`.
`default`	No	`string`	Mode value to use when the config omits the path.
`allowed`	No	`string[]`	If present, the signal passes only when the effective mode is one of these values.
`disallowed`	No	`string[]`	If present, the signal fails when the effective mode is one of these values.

{
  "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"]
          }
        }
      ]
    }
  }
}

Tool metadata reference

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

providerAuthChoices reference

Field	Required	Type	What it means
`provider`	Yes	`string`	Provider id this choice belongs to.
`method`	Yes	`string`	Auth method id to dispatch to.
`choiceId`	Yes	`string`	Stable auth-choice id used by onboarding and CLI flows.
`choiceLabel`	No	`string`	User-facing label. If omitted, OpenClaw falls back to `choiceId`.
`choiceHint`	No	`string`	Short helper text for the picker.
`icon`	No	HTTPS URL	Artwork shown beside this choice in supported onboarding clients.
`website`	No	HTTPS URL	Product, sign-in, or installation page shown by supported onboarding clients.
`assistantPriority`	No	`number`	Lower values sort earlier in assistant-driven interactive pickers.
`assistantVisibility`	No	`"visible"` \| `"manual-only"`	Hide the choice from assistant pickers while still allowing manual CLI selection.
`deprecatedChoiceIds`	No	`string[]`	Legacy choice ids that should redirect users to this replacement choice.
`groupId`	No	`string`	Optional group id for grouping related choices.
`groupLabel`	No	`string`	User-facing label for that group.
`groupHint`	No	`string`	Short helper text for the group.
`onboardingFeatured`	No	`boolean`	Surface this group in the featured tier of the interactive onboarding picker, before the "More..." entry.
`optionKey`	No	`string`	Internal option key for simple one-flag auth flows.
`cliFlag`	No	`string`	CLI flag name, such as `--openrouter-api-key`.
`cliOption`	No	`string`	Full CLI option shape, such as `--openrouter-api-key <key>`.
`cliDescription`	No	`string`	Description used in CLI help.
`appGuidedSecret`	No	`boolean`	One pasted secret plus provider defaults is sufficient for app-guided setup.
`appGuidedDiscovery`	No	`boolean`	The matching runtime auth method owns read-only local discovery through `appGuidedSetup`.
`appGuidedAuth`	No	`"oauth"` \| `"device-code"`	Provider-owned interactive login that native setup clients can render generically.
`onboardingScopes`	No	`Array<"text-inference" \| "image-generation" \| "music-generation">`	Which onboarding surfaces this choice should appear in. If omitted, it defaults to `["text-inference"]`.

commandAliases reference

Field	Required	Type	What it means
`name`	Yes	`string`	Command name that belongs to this plugin.
`kind`	No	`"runtime-slash"`	Marks the alias as a chat slash command rather than a root CLI command.
`cliCommand`	No	`string`	Related root CLI command to suggest for CLI operations, if one exists.

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

activation reference

Use activation when the plugin can cheaply declare which control-plane events should include it in an activation/load plan.

주요 항목:

Gateway startup planning uses activation.onStartup for explicit startup import.
Command-triggered CLI planning falls back to legacy commandAliases[].cliCommand or commandAliases[].name.
Agent-runtime startup planning uses activation.onAgentHarnesses for embedded harnesses and top-level cliBackends[] for CLI runtime aliases.
Channel-triggered setup/channel planning falls back to legacy channels[] ownership when explicit channel activation metadata is missing.
Startup plugin planning uses activation.onConfigPaths for non-channel root config surfaces such as the bundled browser plugin's browser block.
Provider-triggered setup/runtime planning falls back to legacy providers[] and top-level cliBackends[] ownership when explicit provider activation metadata is missing.

Field	Required	Type	What it means
`onStartup`	No	`boolean`	Explicit Gateway startup activation. Every plugin should set this. `true` imports the plugin during startup; `false` keeps it startup-lazy unless another matched trigger requires loading.
`onProviders`	No	`string[]`	Provider ids that should include this plugin in activation/load plans.
`onAgentHarnesses`	No	`string[]`	Embedded agent harness runtime ids that should include this plugin in activation/load plans. Use top-level `cliBackends` for CLI backend aliases.
`onCommands`	No	`string[]`	Command ids that should include this plugin in activation/load plans.
`onChannels`	No	`string[]`	Channel ids that should include this plugin in activation/load plans.
`onRoutes`	No	`string[]`	Route kinds that should include this plugin in activation/load plans.
`onConfigPaths`	No	`string[]`	Root-relative config paths that should include this plugin in startup/load plans when the path is present and not explicitly disabled.
`onCapabilities`	No	`Array<"provider" \| "channel" \| "tool" \| "hook">`	Broad capability hints used by control-plane activation planning. Prefer narrower fields when possible.

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

qaRunners reference

Field	Required	Type	What it means
`commandName`	Yes	`string`	Subcommand mounted beneath `openclaw qa`, for example `matrix`.
`description`	No	`string`	Fallback help text used when the shared host needs a stub command.

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

setup reference

Use setup when setup and onboarding surfaces need cheap 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
  }
}

setup.providers reference

Field	Required	Type	What it means
`id`	Yes	`string`	Provider id exposed during setup or onboarding. Keep normalized ids globally unique.
`authMethods`	No	`string[]`	Setup/auth method ids this provider supports without loading full runtime.
`envVars`	No	`string[]`	Env vars that generic setup/status surfaces can check before plugin runtime loads.
`authEvidence`	No	`object[]`	Cheap local auth evidence checks for providers that can authenticate through non-secret markers.

Field	Required	Type	What it means
`type`	Yes	`string`	Currently `local-file-with-env`.
`fileEnvVar`	No	`string`	Env var containing an explicit credential file path.
`fallbackPaths`	No	`string[]`	Local credential file paths checked when `fileEnvVar` is absent or empty. Supports `${HOME}` and `${APPDATA}`.
`requiresAnyEnv`	No	`string[]`	At least one listed env var must be non-empty before the evidence is valid.
`requiresAllEnv`	No	`string[]`	Every listed env var must be non-empty before the evidence is valid.
`credentialMarker`	Yes	`string`	Non-secret marker returned when the evidence is present.
`source`	No	`string`	User-facing source label for auth/status output.

setup fields

Field	Required	Type	What it means
`providers`	No	`object[]`	Provider setup descriptors exposed during setup and onboarding.
`cliBackends`	No	`string[]`	Setup-time backend ids used for descriptor-first setup lookup. Keep normalized ids globally unique.
`configMigrations`	No	`string[]`	Config migration ids owned by this plugin's setup surface.
`requiresRuntime`	No	`boolean`	Whether setup still needs `setup-api` execution after descriptor lookup.

uiHints reference

Field	Type	What it means
`label`	`string`	User-facing field label.
`help`	`string`	Short helper text.
`tags`	`string[]`	Optional UI tags.
`advanced`	`boolean`	Marks the field as advanced.
`sensitive`	`boolean`	Marks the field as secret or sensitive.
`placeholder`	`string`	Placeholder text for form inputs.
`presentation`	`"phone-number"`	Display-only localized phone formatting for parseable international (`+...`) values; raw values remain unchanged.

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

contracts reference

Use contracts only for static capability ownership metadata that OpenClaw can read without importing the plugin runtime.

Field	Type	What it means
`embeddedExtensionFactories`	`string[]`	Codex app-server extension factory ids, currently `codex-app-server`.
`agentToolResultMiddleware`	`string[]`	Runtime ids this plugin may register tool-result middleware for.
`trustedToolPolicies`	`string[]`	Plugin-local trusted pre-tool policy ids an installed plugin may register. Bundled plugins may register policies without this field.
`externalAuthProviders`	`string[]`	Provider ids whose external auth profile hook this plugin owns.
`embeddingProviders`	`string[]`	General embedding provider ids this plugin owns for reusable vector embedding use, including memory.
`speechProviders`	`string[]`	Speech provider ids this plugin owns.
`realtimeTranscriptionProviders`	`string[]`	Realtime-transcription provider ids this plugin owns.
`realtimeVoiceProviders`	`string[]`	Realtime-voice provider ids this plugin owns.
`memoryEmbeddingProviders`	`string[]`	Deprecated memory-specific embedding provider ids this plugin owns.
`mediaUnderstandingProviders`	`string[]`	Media-understanding provider ids this plugin owns.
`transcriptSourceProviders`	`string[]`	Transcript source provider ids this plugin owns.
`documentExtractors`	`string[]`	Document (for example PDF) extractor provider ids this plugin owns.
`imageGenerationProviders`	`string[]`	Image-generation provider ids this plugin owns.
`videoGenerationProviders`	`string[]`	Video-generation provider ids this plugin owns.
`musicGenerationProviders`	`string[]`	Music-generation provider ids this plugin owns.
`webContentExtractors`	`string[]`	Web-page content-extraction provider ids this plugin owns.
`webFetchProviders`	`string[]`	Web-fetch provider ids this plugin owns.
`webSearchProviders`	`string[]`	Web-search provider ids this plugin owns.
`workerProviders`	`string[]`	Cloud-worker provider ids this plugin owns for provisioning and profile-backed lease lifecycle.
`usageProviders`	`string[]`	Provider ids whose usage-auth and usage-snapshot hooks this plugin owns.
`migrationProviders`	`string[]`	Import provider ids this plugin owns for `openclaw migrate`.
`gatewayMethodDispatch`	`string[]`	Reserved entitlement for authenticated plugin HTTP routes that dispatch Gateway methods in-process.
`tools`	`string[]`	Agent tool names this plugin owns.

{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "codex"],
    "trustedToolPolicies": ["workflow-budget"],
    "externalAuthProviders": ["acme-ai"],
    "embeddingProviders": ["openai-compatible"],
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "memoryEmbeddingProviders": ["local"],
    "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"]
  }
}

configContracts reference

Field	Required	Type	What it means
`compatibilityMigrationPaths`	No	`string[]`	Root-relative config paths that indicate this plugin's setup-time compatibility migrations might apply. Lets generic runtime config reads skip every plugin setup surface when the config never references the plugin.
`compatibilityRuntimePaths`	No	`string[]`	Root-relative compatibility paths this plugin can service during runtime before plugin code fully activates. Use this for legacy surfaces that should narrow bundled candidate sets without importing every compatible plugin runtime.
`dangerousFlags`	No	`object[]`	Config literals that `openclaw doctor` should flag as insecure or dangerous when enabled. See below.
`secretInputs`	No	`object`	Config paths under `plugins.entries.<id>.config` for SecretRef migration, audit, startup materialization, and optional runtime owner isolation. See below.

Field	Required	Type	What it means
`path`	Yes	`string`	Dot-separated config path relative to `plugins.entries.<id>.config`. Supports `*` wildcards for map/array segments.
`equals`	Yes	`string \| number \| boolean \| null`	Exact literal that marks this config value as dangerous.

Field	Required	Type	What it means
`bundledDefaultEnabled`	No	`boolean`	Override bundled-plugin default enablement when deciding whether this SecretRef surface is active. Use this when the plugin is bundled but the surface should stay inactive until explicitly enabled in config.
`paths`	Yes	`object[]`	Secret-shaped config paths, each with `path` (dot-separated, relative to `plugins.entries.<id>.config`, supports `*` wildcards), optional `expected` (currently only `"string"`), and optional `ownerKind` (currently only `"route"`). A declared owner isolates only that exact matched path when resolution fails; its owner id is the full config path.

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

mediaUnderstandingProviderMetadata reference

Field	Type	What it means
`capabilities`	`("image" \| "audio" \| "video")[]`	Media capabilities exposed by this provider.
`defaultModels`	`Record<string, string>`	Capability-to-model defaults used when config does not specify a model.
`autoPriority`	`Record<string, number>`	Lower numbers sort earlier for automatic credential-based provider fallback.
`nativeDocumentInputs`	`"pdf"[]`	Native document inputs supported by the provider.
`documentModels`	`{ pdf?: { textExtraction?: string; image?: string \| false } }`	Per-document-type model overrides. Set `image: false` to disable image-based extraction for that document type.

{
  "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"
        }
      }
    }
  }
}

channelConfigs reference

주요 항목:

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

Field	Type	What it means
`schema`	`object`	JSON Schema for `channels.<id>`. Required for each declared channel config entry.
`uiHints`	`Record<string, object>`	Optional labels, placeholders, sensitivity, and display-only presentation hints for that channel config section.
`label`	`string`	Channel label merged into picker and inspect surfaces when runtime metadata is not ready.
`description`	`string`	Short channel description for inspect and catalog surfaces.
`commands`	`object`	Static native command and native skill auto-defaults for pre-runtime config checks.
`preferOver`	`string[]`	Legacy or lower-priority plugin ids this channel should outrank in selection surfaces.

{
  "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"]
    }
  }
}

Replacing another channel plugin

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

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.

주요 항목:

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

Field	Type	What it means
`modelPrefixes`	`string[]`	Prefixes matched with `startsWith` against shorthand model ids.
`modelPatterns`	`string[]`	Regex sources matched against shorthand model ids after profile suffix removal.

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

modelCatalog reference

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.
`runtimeAugment`	`boolean`	Set to `true` only when the provider runtime must append catalog rows after manifest/config planning.

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.
`defaultUtilityModel`	`string`	Optional provider-recommended small model id for short internal utility tasks (titles, progress narration). Used when `agents.defaults.utilityModel` is unset and this provider serves the agent's primary model.
`models`	`object[]`	Required model rows. Rows without an `id` are ignored.

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. Other values are silently dropped.
`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.
`thinkingLevelMap`	`Record<string, string \| null>`	Optional per-thinking-level model-id or param overrides.
`cost`	`object`	Optional USD per million token pricing, including optional `tieredPricing`.
`compat`	`object`	Optional compatibility flags matching OpenClaw model config compatibility.
`mediaInput`	`object`	Optional per-modality input config, currently image-only.
`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.

{
  "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"
    }
  }
}

modelIdNormalization reference

Field	Type	What it means
`aliases`	`Record<string,string>`	Case-insensitive exact model-id aliases. Values are returned as written.
`stripPrefixes`	`string[]`	Prefixes to remove before alias lookup, useful for legacy provider/model duplication.
`prefixWhenBare`	`string`	Prefix to add when the normalized model id does not already contain `/`.
`prefixWhenBareAfterAliasStartsWith`	`object[]`	Conditional bare-id prefix rules after alias lookup, keyed by `modelPrefix` and `prefix`.

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

providerEndpoints reference

Field	Type	What it means
`endpointClass`	`string`	Known core endpoint class, such as `openrouter`, `moonshot-native`, or `google-vertex`.
`hosts`	`string[]`	Exact hostnames that map to the endpoint class.
`hostSuffixes`	`string[]`	Host suffixes that map to the endpoint class. Prefix with `.` for domain suffix-only matching.
`baseUrls`	`string[]`	Exact normalized HTTP(S) base URLs that map to the endpoint class.
`googleVertexRegion`	`string`	Static Google Vertex region for exact global hosts.
`googleVertexRegionHostSuffix`	`string`	Suffix to strip from matching hosts to expose the Google Vertex region prefix.

providerRequest reference

Field	Type	What it means
`family`	`string`	Provider family label used by generic request compatibility decisions and diagnostics.
`compatibilityFamily`	`"moonshot"`	Optional provider-family compatibility bucket for shared request helpers.
`openAICompletions`	`object`	OpenAI-compatible completions request flags, currently `supportsStreamingUsage`.

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

secretProviderIntegrations reference

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

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

modelPricing reference

Use modelPricing when a provider needs control-plane pricing behavior before runtime loads. The Gateway pricing cache reads this metadata without importing provider runtime code.

Field	Type	What it means
`external`	`boolean`	Set `false` for local/self-hosted providers that should never fetch OpenRouter or LiteLLM pricing.
`openRouter`	`false \| object`	OpenRouter pricing lookup mapping. `false` disables OpenRouter lookup for this provider.
`liteLLM`	`false \| object`	LiteLLM pricing lookup mapping. `false` disables LiteLLM lookup for this provider.

Field	Type	What it means
`provider`	`string`	External catalog provider id when it differs from the OpenClaw provider id, for example `z-ai` for a `zai` provider.
`passthroughProviderModel`	`boolean`	Treat slash-containing model ids as nested provider/model refs, useful for proxy providers such as OpenRouter.
`modelIdTransforms`	`"version-dots"[]`	Extra external catalog model-id variants. `version-dots` tries dotted version ids like `claude-opus-4.6`.

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

OpenClaw Provider Index

Manifest versus package.json

If you are unsure where a piece of metadata belongs, use this rule:

주요 항목:

if OpenClaw must know it before loading plugin code, put it in openclaw.plugin.json
if it is about packaging, entry files, or npm install behavior, put it in package.json

File	Use it for
`openclaw.plugin.json`	Discovery, config validation, auth-choice metadata, and UI hints that must exist before plugin code runs
`package.json`	npm metadata, dependency installation, and the `openclaw` block used for entrypoints, install gating, setup, or catalog metadata

package.json fields that affect discovery

Field	What it means
`openclaw.extensions`	Declares native plugin entrypoints. Must stay inside the plugin package directory.
`openclaw.runtimeExtensions`	Declares built JavaScript runtime entrypoints for installed packages. Must stay inside the plugin package directory.
`openclaw.setupEntry`	Lightweight setup-only entrypoint used during onboarding, deferred channel startup, and read-only channel status/SecretRef discovery. Must stay inside the plugin package directory.
`openclaw.runtimeSetupEntry`	Declares the built JavaScript setup entrypoint for installed packages. Requires `setupEntry`, must exist, and must stay inside the plugin package directory.
`openclaw.channel`	Cheap channel catalog metadata like labels, docs paths, aliases, and selection copy.
`openclaw.channel.approvalFlags`	Closed approval behavior flags available before runtime load. `native` means the channel owns native approval UI and same-turn resolution.
`openclaw.channel.commands`	Static native command and native skill auto-default metadata used by config, audit, and command-list surfaces before channel runtime loads.
`openclaw.channel.cliAddOptions`	Plugin-owned `openclaw channels add` options. Each entry declares `flags`, `description`, optional `defaultValue`, and optional `valueType` (`int` or `list`) for generic input coercion.
`openclaw.channel.configuredState`	Lightweight configured-state checker metadata that can answer "does env-only setup already exist?" without loading the full channel runtime.
`openclaw.channel.persistedAuthState`	Lightweight persisted-auth checker metadata that can answer "is anything already signed in?" without loading the full channel runtime.
`openclaw.install.clawhubSpec` / `openclaw.install.npmSpec` / `openclaw.install.localPath`	Install/update hints for bundled and externally published plugins.
`openclaw.install.defaultChoice`	Preferred install path when multiple install sources are available.
`openclaw.install.minHostVersion`	Minimum supported OpenClaw host version, using a semver floor like `>=2026.3.22` or `>=2026.5.1-beta.1`.
`openclaw.compat.pluginApi`	Minimum OpenClaw plugin API range required by this package, using a semver floor like `>=2026.5.27`.
`openclaw.install.expectedIntegrity`	Expected npm dist integrity string such as `sha512-...`; install and update flows verify the fetched artifact against it.
`openclaw.install.allowInvalidConfigRecovery`	Allows a narrow bundled-plugin reinstall recovery path when config is invalid.
`openclaw.install.requiredPlatformPackages`	npm package aliases that must materialize when their lockfile platform constraints match the current host.
`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`	Lets setup-runtime channel surfaces load before listen, then defers the full configured channel plugin until post-listen activation.

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

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

Discovery precedence (duplicate plugin ids)

주요 항목:

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 plugins 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 (예를 들어, { "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.

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

Validation behavior

See Configuration reference for the full plugins.* schema.

주요 항목:

Unknown channels.* keys are errors, unless the channel id is declared by a plugin manifest. If the same id also appears in plugins.allow, plugins.entries, or plugins.installs (a plugin that is referenced but not currently discoverable), OpenClaw downgrades this to a warning instead.
plugins.entries.<id>, plugins.allow, and plugins.deny referencing unknown plugin ids are warnings ("stale config entry ignored"), not errors, so upgrades and removed/renamed plugins do not block gateway startup.
plugins.slots.memory referencing an unknown plugin id is an error, except for the known memory-lancedb official external plugin, which warns instead.
If a plugin is installed but has a broken or missing manifest or schema, validation fails and Doctor reports the plugin error.
If plugin config exists but the plugin is disabled, the config is kept and a warning is surfaced in Doctor + logs.

참고

주요 항목:

The manifest is required for native OpenClaw plugins, including local filesystem loads. Runtime still loads the plugin module separately; the manifest is only for discovery + validation.
Native manifests are parsed with JSON5, so comments, trailing commas, and unquoted keys are accepted as long as the final value is still an object.
Only documented manifest fields are read by the manifest loader. Avoid custom top-level keys.
channels, providers, cliBackends, and skills can all be omitted when a plugin does not need them.
providerCatalogEntry must stay lightweight and should not import broad runtime code; use it for static provider catalog metadata or narrow discovery descriptors, not request-time execution.
Exclusive plugin kinds are selected through plugins.slots.*: kind: "memory" via plugins.slots.memory (default memory-core), kind: "context-engine" via plugins.slots.contextEngine (default legacy).
Declare exclusive plugin kind in this manifest. Runtime-entry OpenClawPluginDefinition.kind is deprecated and remains only as a compatibility fallback for older plugins.
Env-var metadata in setup.providers[].envVars is declarative only. 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 requires provider code, see Provider runtime hooks.
If your plugin depends on native modules, document the build steps and any package-manager allowlist requirements (예를 들어, pnpm allow-build-scripts + pnpm rebuild <package>).

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/manifest
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

{
  "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"
      }
    }
  }
}

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

{
  "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" }
          }
        }
      }
    ]
  }
}

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

{
  "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"]
          }
        }
      ]
    }
  }
}

Plugin manifest

핵심 요약

문서 구성

상세 내용

본문

What this file does

Minimal example

Rich example

Top-level field reference

MCP server reference

dashboard reference

catalog reference

Generation provider metadata reference

Tool metadata reference

providerAuthChoices reference

commandAliases reference

activation reference

qaRunners reference

setup reference

setup.providers reference

setup fields

uiHints reference

contracts reference

configContracts reference

mediaUnderstandingProviderMetadata reference

channelConfigs reference

Replacing another channel plugin

modelSupport reference

modelCatalog reference

modelIdNormalization reference

providerEndpoints reference

providerRequest reference

secretProviderIntegrations reference

modelPricing reference

OpenClaw Provider Index

Manifest versus package.json

package.json fields that affect discovery

Discovery precedence (duplicate plugin ids)

JSON Schema requirements

Validation behavior

참고

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Plugin manifest

핵심 요약

문서 구성

상세 내용

본문

What this file does

Minimal example

Rich example

Top-level field reference

MCP server reference

dashboard reference

catalog reference

Generation provider metadata reference

Tool metadata reference

providerAuthChoices reference

commandAliases reference

activation reference

qaRunners reference

setup reference

setup.providers reference

setup fields

uiHints reference

contracts reference

configContracts reference

mediaUnderstandingProviderMetadata reference

channelConfigs reference

Replacing another channel plugin

modelSupport reference

modelCatalog reference

modelIdNormalization reference

providerEndpoints reference

providerRequest reference

secretProviderIntegrations reference

modelPricing reference