<!-- Generated by scripts/generate-site-content.py — do not edit by hand -->


# openclaw-manifest-valid

Native OpenClaw manifests must declare valid identity, configSchema, and themes

| | |
|---|---|
| **Severity** | error (disabled) |
| **Autofix** | - |
| **Since** | v0.21.0 |
| **Repo Types** | openclaw-plugin |
| **Category** | [OpenClaw](openclaw.md) |

## Why

OpenClaw reads `openclaw.plugin.json` before executing a native plugin. Missing
or invalid JSON5, an empty/non-string `id`, the reserved `node-mcp` identity,
a manifest exceeding 262,144 bytes,
or a missing/non-object `configSchema` prevents the native manifest from loading.
An empty schema object is valid. Optional unknown fields remain forward compatible.

OpenClaw v2026.9.7 also rejects the whole plugin when its optional `themes`
declaration is invalid. This rule checks theme and artwork declarations against
that released manifest contract.

## Activation

Opt-in: enable `openclaw-manifest-valid` in configuration or with `--rule`.
Discovery and shared content/security inspection do not require this rule.
Native packaging checks are opt-in while ecosystem coverage expands.

## How to fix

Ship a native manifest in the package root, with a non-empty string `id` and
an object `configSchema`. Keep the file inside the package; escaping symlinks
are reported without reading their target. This rule makes no autofixes.

When declaring themes:

- Use an array of at most 32 objects. Each theme needs a unique lowercase `id`
  (1–64 letters, digits, underscores, or hyphens, starting with a letter or digit),
  a non-empty `name` of at most 80 characters, a non-empty `description` of at
  most 320 characters, and a relative `.json` `source`. Names and descriptions
  cannot contain control characters. OpenClaw measures text limits in UTF-16
  code units; most emoji use two units.
- Use a portable plugin ID outside the reserved `user` namespace. Scoped IDs
  such as `@scope/theme-pack` and multi-entry IDs such as `pack/one` are valid.
- Optional `hats` and `critters` maps each allow at most eight unique lowercase
  artwork IDs of 1–32 characters. Avoid IDs from the corresponding built-in
  catalog. Hats map to relative `.svg` paths; critters map to objects with a
  `.svg` `source`, optional printable `title` of at most 60 characters, and
  optional integer `crossMs` from 5000 through 90000.
- Keep source paths inside the plugin: absolute paths, traversal, backslashes,
  URLs, and empty path segments are invalid. A leading `./` is accepted.
  Duplicate artwork keys are errors even in JSON5 or when a key uses escapes.

Theme JSON contents and SVG files are outside this manifest check. Missing or
invalid asset files cause OpenClaw to omit the theme with a warning; other plugin
capabilities remain available. This rule does not require those files to exist.

## Upstream source

Pinned to OpenClaw revision
[`912b21b98581c0be3baad87fe3686b64d69fffeb`](https://github.com/openclaw/openclaw/tree/912b21b98581c0be3baad87fe3686b64d69fffeb),
for the native loader contract:

- [`manifest.ts`](https://github.com/openclaw/openclaw/blob/912b21b98581c0be3baad87fe3686b64d69fffeb/src/plugins/manifest.ts): JSON5 parsing, required fields, reserved identity.
- [`package-manifest.ts`](https://github.com/openclaw/openclaw/blob/912b21b98581c0be3baad87fe3686b64d69fffeb/src/plugins/package-manifest.ts): extension entry types and defaults.
- [`plugin-skills.ts`](https://github.com/openclaw/openclaw/blob/912b21b98581c0be3baad87fe3686b64d69fffeb/src/skills/loading/plugin-skills.ts): explicit skill roots and containment.
- [`manifest-capability-normalizers.ts`](https://github.com/openclaw/openclaw/blob/912b21b98581c0be3baad87fe3686b64d69fffeb/src/plugins/manifest-capability-normalizers.ts): static MCP normalization.

Theme declarations follow the released
[`v2026.9.7` loader](https://github.com/openclaw/openclaw/blob/v2026.9.7/src/plugins/manifest-themes.ts),
with limits and catalog IDs from
[`theme.ts`](https://github.com/openclaw/openclaw/blob/v2026.9.7/packages/gateway-protocol/src/theme.ts)
and [`theme-ids.ts`](https://github.com/openclaw/openclaw/blob/v2026.9.7/packages/gateway-protocol/src/theme-ids.ts).
The [upstream manifest reference](https://github.com/openclaw/openclaw/blob/v2026.9.7/docs/plugins/manifest/surfaces.md#themes)
describes theme packaging and the separate asset warning behavior.

The rule validates the stable native loading core and theme declarations. Other runtime capability
metadata, schema compilation, export/manifest identity agreement, gateway
settings, install-time dependency resolution, ClawHub and marketplace feeds are
outside its scope. Compatible portable bundles use their existing validators.

## Configuration

```yaml
rules:
  openclaw-manifest-valid:
    enabled: false  # true | false | auto
    severity: error
```


*Run `skillsaw explain openclaw-manifest-valid` to see this documentation and the rule's effective configuration in your terminal.*