Manifest host surface fields

Manifest fields that contribute a concrete host surface: an icon, a command, a server, a panel, a widget, a runner, a channel, or a backup resource. Part of the Plugin manifest reference; the top-level field reference lists every field.

Plugin icon

Place the portable plugin icon at assets/icon.png, relative to the plugin root. No manifest field is required. Use a square PNG that remains recognizable at 16 px; 512×512 is recommended. Missing, unreadable, or invalid icons are ignored and do not invalidate the plugin.

This is the plugin's identity artwork for catalogs, settings, channel setup, and installation cards. Compact tool calls use separate inline activity icons, so improving a chat glyph does not change the plugin's branding elsewhere.

OpenClaw adopts this fixed package path as its icon convention, matching the path proposed in Agent Plugins spec proposal agent-plugins-spec#66. OpenClaw itself implements Agent Plugins 1.0.0. Other Agent Plugins consumers may not discover it unless that proposal is adopted. The fixed path keeps packages portable and inspectable, avoids manifest path indirection and precedence rules, and lets OpenClaw render the icon without a runtime network request. Top-level plugin-branding icon URLs are not loaded; provider-auth artwork remains server-owned catalog metadata.

Prefer top-level sessionRouteStateOwners for static doctor ownership. The older doctorContract.sessionRouteStateOwners: true declaration plus a sessionRouteStateOwners export from doctor-contract-api remains supported for external plugins, but is deprecated. When the manifest field is present, OpenClaw uses it without loading the doctor-contract module. Removal plan: remove the module fallback in OpenClaw 2027.1 after the external-plugin migration window.

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

The config-repair module can export historicalWebhookListener to describe a retired default endpoint. The existing compatibility normalizer reports eligible accounts; the host owns the one-shot pin and completion write. See webhook migration contracts.

When Doctor renames saved credentials, it updates exact authProfileId and defaultAuthProfileId references inside plugin config and channel config. This preserves the shipped authProfileId migration and also covers defaults such as LLM Task's defaultAuthProfileId, including older installed plugins. Reference lookup trims surrounding whitespace, as the credential reader does. Unmapped values and literal strings elsewhere remain unchanged. Plugins do not need to implement the host's credential rename in their compatibility callbacks.

Bundled plugins declare each state migration in execution order so Doctor can plan its owner and receipt without loading plugin code:

{
  "doctorContract": {
    "stateMigrations": [
      { "id": "legacy-cache-to-state" },
      { "id": "session-owner-repair", "doctorOnly": true, "phase": "after-session-repair" }
    ]
  }
}

The array must match the migration IDs, order, doctorOnly flags, and phases exported by the doctor-contract module. The older value true still declares the dynamic module. During an in-process package update, Doctor loads the replacement package's callbacks in its new inventory; earlier inventories retain their original callbacks. A changed action list between package versions is allowed, but each version's manifest and module must agree.

Installed external plugin manifests remain outside the copied-state and candidate content identity, including when they use the descriptor array. Candidate validation must bind those artifacts separately. Until then, Doctor records an explicit planning refusal instead of treating an installed manifest as write authority.

A state migration returns changes and warnings, with optional notices. Warnings refuse later Doctor repairs by default. A migration may return warningDisposition: "recoverable" only when every warning is advisory and required state remains safe for later repairs. Doctor preserves those warnings in its receipts and continues. Detection errors, thrown failures, and unclassified warnings from another migration still refuse the combined step.

For definePluginDoctorMigrationFromPlans, a plugin-state-import plan may set cleanupWarningDisposition: "recoverable" when its retired source is an unused, rebuildable artifact. This applies only to cleanup failures after import succeeds. Read, import, and verification failures still refuse the migration. Every plan consuming a shared source must opt in before its cleanup failures become advisory.

The Codex plugin sets doctorHealthChecks: true when its public API exports health-check registration. Doctor checks the selected plugin's trust before loading this surface. Older installed versions without the declaration skip Codex health registration without preventing other checks; a declared but missing or broken API remains an error. This does not grant plugin capabilities or replace upgrade consent.

Channel plugins maintained in the OpenClaw source tree also expose these config exports through a pure config-doctor-api.ts entrypoint. The core package retains that entrypoint alongside its channel schemas when the plugin runtime is distributed separately. This lets doctor --fix migrate older configuration before plugin installation or capability consent. An installed plugin's doctor contract remains authoritative; retained entrypoints do not expose state migrations, install plugins, or grant capabilities.

Inline activity icons

Place a monochrome SVG at assets/activity.svg for the compact icon beside the plugin's tool calls and collapsed tool results. No manifest field is required. Design it to remain clear at 16 px with a transparent background. The Control UI renders its shape in the activity row's text color, including dark mode; source colors do not become branding colors in the row.

Use assets/activity/<tool-name>.svg only when an individual tool needs a different shape. The filename must exactly match that tool's id from tools.effective, including case. For example, a tool with ID calendar_search can ship:

assets/
  icon.png
  activity.svg
  activity/
    calendar_search.svg

The tool ID must be at most 128 ASCII characters, start with a letter, digit, or underscore, and contain only letters, digits, underscores, hyphens, or periods. Keep the override directory to at most 128 entries; larger directories are ignored as a whole. The default activity icon covers other tool IDs, including integrations whose routing adds prefixes to tool names. These files supply presentation only; they do not register tools or change tool ownership.

Keep each SVG file within 32 KiB. Use simple SVG geometry: path, circle, ellipse, line, polygon, polyline, and rect, optionally inside g. The SVG can contain at most four elements including the root, 8 KiB of combined path and point data, and 1,024 path commands. Give the root a viewBox with positive width and height, or positive numeric width and height, each at most 4,096. Scripts, stylesheets, event handlers, external references, embedded images, and filters are not supported. For example:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
  <path d="M5 5h14v14H5zM8 2v6m8-6v6M5 10h14"/>
</svg>

OpenClaw validates the SVG and rasterizes it before using it as an activity mask; it never inserts package SVG markup into the chat DOM. Missing or invalid artwork falls back to the existing tool glyph, without showing the packaged brand image. The plugin remains usable.

Include both assets/activity.svg and assets/activity/*.svg in the published package's files list when used. OpenClaw's bundled metadata copier and plugin runtime package builder include these paths automatically. Asset discovery uses the Gateway's prepared plugin metadata; restart or explicitly reload the plugin after changing its artwork.

Themes

Declare portable themes in openclaw.plugin.json to make them available in Settings → Appearance and the agent's theme tool. The same catalog serves both surfaces. Theme discovery reads static JSON and does not execute plugin code or require the Custom plugin UI Labs setting.

{
  "id": "starship",
  "configSchema": { "type": "object", "additionalProperties": false },
  "themes": [
    {
      "id": "xenovessel",
      "name": "Xenovessel",
      "description": "Near-black indigo, acid lime, and alien cyan with monospace text.",
      "source": "themes/xenovessel.json",
      "icons": { "rocket": "assets/theme-art/rocket.svg" },
      "hats": { "beret": "assets/theme-art/beret.svg" },
      "critters": {
        "ferris": {
          "source": "assets/theme-art/ferris.svg",
          "title": "a crab, allegedly",
          "crossMs": 12000
        }
      }
    }
  ]
}

The catalog ID is starship/xenovessel. It preserves the plugin's canonical ID, including case, scoped IDs such as @scope/starship, and multi-entry IDs such as pack/one; their theme IDs are @scope/starship/xenovessel and pack/one/xenovessel. The complete catalog ID is limited to 256 characters. Each plugin can declare up to 32 themes. Local IDs must start with a lowercase letter or digit, contain only lowercase letters, digits, underscores, or hyphens, and be at most 64 characters. The user/ namespace belongs to personally imported themes.

source is a relative .json path inside the plugin root; include it in the published package's files list. Absolute paths, traversal, and symlinks escaping the root are rejected. Each source file can contain at most 16 KiB including formatting whitespace. Its normalized definition must fit in 4096 UTF-8 bytes.

Each theme may declare icons and hats, maps of artwork IDs to relative .svg paths, and critters, a map of artwork IDs to objects containing source and optional title and crossMs. Each map allows at most 8 entries. Artwork IDs must match ^[a-z0-9][a-z0-9_-]{0,31}$; duplicates and collisions with the corresponding built-in brand icon (claw, mark), hat, or critter catalog are manifest errors. title is untranslated hover text of at most 60 printable characters. crossMs is an integer from 5000 through 90000, defaulting to 12000 milliseconds.

Artwork paths follow the same containment rules as source. Each SVG must be self-contained and at most 32 KiB; scripts, event handlers, external references, and embedded resources are rejected. The Control UI rasterizes artwork to a 256 × 256 pixel canvas before rendering it as an image. It uses the activity-icon limits: at most 4 elements including the root, 8 KiB of combined path and point data, 1024 path commands, and positive source dimensions no larger than 4096. Use path, circle, ellipse, line, polygon, polyline, and rect, optionally inside g; the root is svg, and title and desc are also supported within the element limit. Stylesheets, filters, and embedded images are unsupported. Hats overlay the avatar's full square; place the hat near the top of the SVG viewBox and leave the lower area transparent.

Include the definition JSON and every declared SVG in the published package's files list. OpenClaw's bundled metadata copier and runtime package builder include these declared paths automatically. An unreadable or invalid SVG omits the whole theme from the catalog with a plugin warning diagnostic; other plugin capabilities remain available.

The JSON file contains name, description, and at least one of light or dark; its name and description must match the manifest. Names are limited to 80 characters and descriptions to 320. Each present mode supplies all semantic colors from the theme definition example, plus optional font-sans and font-mono font-family lists. Individual values are limited to 120 characters. Supported colors are hex, rgb(), rgba(), hsl(), hsla(), lab(), lch(), oklab(), oklch(), color(), black, white, and transparent. CSS declarations, URLs, and references to other CSS variables are not theme data. An invalid definition is omitted from the catalog with a plugin diagnostic; other plugin capabilities remain available.

The source JSON also accepts optional presentation fields. They belong in the definition referenced by themes[].source, alongside name, description, and the palettes:

• mascot: "claw" (the default) or "none"; "none" defaults to neutral branding and hides the resident lobster and visiting lobster strangers. Ordinary critters can still cross the composer ledge when Lobster visits is enabled, and the toggle stays unchanged.
• brandName: a trimmed display name of 1–80 printable characters; defaults to “OpenClaw.”
• brandIcon: "claw", "mark", or an ID from this theme's declared icons map. Omission follows mascot: claw for "claw", mark for "none". An ID declared only as a hat or critter is not a brand icon.
• workingIndicator: "claw", "dots", "brand" (the selected brand icon), or "none". Omission uses claw for the claw mascot and dots otherwise; it does not change long-wait phrases.
• lobsterdex and communityLinks: booleans controlling their respective navigation entries; each defaults to true independently of the mascot. These are presentation choices, not deletion or authorization controls.
• workingPhrases: up to 24 literal, untranslated long-wait status phrases. Each phrase is trimmed, must contain 1–24 characters, and cannot contain control characters or duplicate another trimmed phrase. Omit it to keep the default vocabulary; use [] to hide long-wait phrases.
• critters: up to 8 unique IDs from the built-in "penguin" and "fedora" catalog or this theme's declared critters map, adding occasional visitors to ordinary composer ledge traffic while Lobster visits is enabled. Omit it or use [] for no theme-supplied critters. Unknown IDs and duplicates are rejected.
• avatarHat: "fedora", "crown", "santa", "party", "pumpkin", or an ID from this theme's declared hats map adds an occasional decorative hat to agent avatars; omission adds no hat.

These fields count toward the same 4096-byte normalized definition limit and are returned with the catalog descriptor. The theme definition example shows these presentation fields. Definitions carry IDs only, never SVG markup or URLs. Personal themes imported through the agent's theme tool remain limited to built-in artwork IDs.

Only enabled plugins contribute themes. OpenClaw retains validated definitions and artwork bytes with the current plugin inventory. After editing a source, artwork file, or manifest, run openclaw plugins reload starship or choose Reload in the plugin's Lifecycle settings. Reload publishes the new palette and refreshes connected clients without restarting the Gateway. Artwork URLs include a content hash so changed images bypass the page's artwork cache. Serving artwork reads the captured generation, never changed files on disk. No filesystem polling is needed. Disabling or removing the plugin removes its themes from the catalog; the selected theme can then fall back as described in Plugin themes and hot reload.

Transcript sources reference

transcriptSources maps provider IDs to static setup descriptors. Each key must also appear in this plugin's contracts.transcriptSourceProviders; descriptors for undeclared IDs are ignored. Names and setup controls are available from the prepared manifest snapshot without importing provider runtime.

{
  "contracts": { "transcriptSourceProviders": ["captions"] },
  "transcriptSources": {
    "captions": {
      "name": "Captions",
      "autoStart": { "accountId": "optional", "meetingUrl": "required" }
    }
  }
}

name is an optional display name. autoStart advertises setup controls to Gateway clients through transcripts.status. Its only keys are accountId, guildId, channelId, and meetingUrl; each value must be "required" or "optional". An explicit empty object supports setup without locator controls. Omit autoStart for sources that only attach to an already-active meeting bot. Malformed objects, unknown locator keys, or invalid modes do not advertise partial setup. Title and custom session ID remain existing configuration fields, not locator descriptor keys.

Setup requires an enabled plugin. Runtime capabilities remain observed facts: an absent canStart does not hide the manifest descriptor, while an observed canStart: false prevents new setup. The descriptor does not change acceptance of existing transcripts.autoStart config or provider start semantics. Existing source edits preserve configured fields when metadata is unavailable.

backupResources reference

Use backupResources to declare plugin-owned durable data that backups must include, or generated data that OpenClaw can safely omit and regenerate after restore. The backup planner reads this metadata without loading plugin runtime or modifying plugin files. Only effectively activated, loadable plugins contribute resources; disabled or unloadable plugins cannot exclude data.

An include declaration also asks OpenClaw to manage SQLite backups for that resource. SQLite files at or below the declared path receive verified online snapshots and offline compaction, with their committed write-ahead log (WAL) content included and sidecars omitted. Creation refuses a declared database when its required SQLite capabilities are unavailable. Declare every hardlink alias within these resources so backup can identify its journal owner.

Other plugin SQLite files remain opaque byte copies, including their sidecars, unless they alias a canonical OpenClaw database. Backup reports each opaque SQLite file and sidecar in warnings; verification and restore preserve its bytes without applying SQLite validation or compaction. Merely placing a database under the state or agent directory does not opt it into managed snapshots. Undeclared SQLite symbolic links that exceed the link-resolution limit (ELOOP), including loops, are skipped with filename warnings. Declared database links still fail closed if they cannot be captured safely.

{
  "backupResources": [
    {
      "disposition": "include",
      "scope": "state",
      "relativePath": "example-plugin/durable-state"
    },
    {
      "disposition": "regenerable",
      "scope": "agent",
      "relativePath": "example-plugin/generated-cache"
    }
  ]
}

Each entry is a closed object with exactly these fields:

Plugin identity and its trusted root come from manifest discovery; resource entries cannot declare or override an owner. relativePath must not be empty or absolute and must not contain backslashes, NULs, empty path segments, ., .., Windows drive or UNC prefixes, URI-like values, or any path that escapes its selected anchor. Invalid entries are rejected rather than normalized.

The planner deduplicates resources deterministically. A narrower regenerable declaration wins over a broad configured state or agent root. Among plugin resource declarations, only an explicit nested include protects a descendant and keeps its excluded ancestors traversable. Explicit config, credentials, workspace, and nested agent paths also remain protected. Omit only data the plugin can recreate. openclaw backup create --only-config does not inspect plugin backup metadata.

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

OpenClaw includes these servers only while the owning plugin is enabled. Relative command, args, cwd, and workingDirectory paths resolve from the plugin root. User configuration remains authoritative: mcp.servers.<name> can replace a plugin default or set enabled: false to omit it. MCP App rendering and server-tool calls still require the normal MCP Apps setting and effective tool policy; declaring a server does not bypass either boundary.

UI capabilities

Declare uiCapabilities in openclaw.plugin.json to describe what the plugin adds to the OpenClaw interface. The plugin detail page shows these kinds in its Capabilities section before installation and while the plugin is disabled or enabled. Display reads static manifest or catalog metadata without executing plugin code.

{
  "uiCapabilities": ["page", "navigation", "accessory", "widget"]
}

The field is optional. Omission means unspecified; [] explicitly declares no UI contributions. OpenClaw ignores an invalid declaration (unknown values or a non-array value) and reports a plugin warning; the plugin still loads. Older OpenClaw versions ignored this field, so malformed display metadata does not break existing installs after an update. Duplicates are removed, and values use the order above. Declare kinds only, not instance counts or live availability. Conditional registrations may be absent in a particular session without invalidating the declaration.

This field is independent of controlUi.entry: a plugin using a host-rendered link reader can declare link-reader without shipping browser JavaScript. It does not activate a plugin, grant permissions, or prove that a capability is currently configured or healthy. Browser registration and known backend UI registrations emit a diagnostic when an observed kind is missing from an explicit declaration; omission skips that comparison. These diagnostics do not block activation.

For a catalog listing, publish the same metadata with the selected plugin version. If the catalog omits it, OpenClaw leaves the UI contribution kinds unspecified rather than loading the plugin to infer them. For native browser modules, explicit UI reload reads the updated declaration and creates a new revision even when browser code is unchanged.

controlUi reference

controlUi declares a trusted native browser entry and optional stylesheets for the Control UI. Paths are relative to the plugin root and must name compiled JavaScript and CSS. Assets follow the Gateway's authentication policy, are captured as immutable revisions, and refresh only through the explicit UI reload flow.

User-installed native UI requires Settings → Labs → Custom plugin UI (gateway.controlUi.experimental.customPlugins, default false). Native UI from enabled bundled plugins remains available. See Enable custom plugin UI for restart and browser reload requirements. This gate does not disable the plugin's backend APIs or the sandboxed dashboard bindings below.

{
  "controlUi": {
    "entry": "dist/control-ui/<content-hash>/index.js",
    "styles": ["dist/control-ui/<content-hash>/index.css"]
  }
}

Use package.json.openclaw.controlUi for the source entry and let openclaw plugins build generate this declaration. Native UI executes with the browser application's trust; it is distinct from the scoped dashboard widget bindings below. See Feature plugins for authoring, replacements, reload, and activation receipts.

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

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

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.

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

cliCommands reference

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

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

The manifest row is the canonical help text. Register the same command at runtime with api.registerCli(..., { descriptors: [...] }); runtime descriptors may additionally provide machineOutput. Nested commands such as openclaw nodes <feature> are not root commands and do not belong in cliCommands.

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.

If a plugin fails to load, invoking its declared runtime-slash command in chat returns the plugin name, a short failure reason, and recovery guidance (openclaw doctor and gateway logs). Unknown commands and commands belonging to intentionally disabled plugins keep their normal handling; manifest ownership alone does not make a command executable.

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

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 qa-runner-api.ts surface that exports matching qaRunnerCliRegistrations. The pre-July 2026 runtime-api.ts fallback is retired; move runner registrations to qa-runner-api.ts. An optional adapterFactory exposes the transport to shared QA scenarios without changing the registered command's runner.

Module-backed flow scenarios are an adapter-owned execution form. Set adapterFactory.supportsModuleFlows to true only when every adapter created by that factory implements prepareFlow; QA planning excludes module flows from implementations that do not declare support.

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

The adapterFactory id must match commandName. Do not export registrations for commands absent from the manifest.

channelAccountKeyPolicies reference

channelAccountKeyPolicies declares stored account-key selection rules for channels listed in the plugin's channels array. It is plugin metadata; operators keep their account config under channels.<id>.accounts.

{
  "channels": ["signal"],
  "channelAccountKeyPolicies": {
    "signal": { "canonicalAliasesRequireOwnField": "account" }
  }
}

canonicalAliasesRequireOwnField is the name of a string field in the account entry. An alias that matches only after account-id normalization is eligible when that entry has a nonempty value for this field. Root values do not satisfy it. Exact stored keys win; existing case-insensitive matches keep their behavior. Readers and writers use the same selected stored key.

For Signal, Work Phone resolves as work-phone when it has its own account number. Its settings then apply even if the channel root also has a number. Without its own number, the previously ignored entry stays ignored and the route keeps its inherited settings. Doctor preserves that key and reports the required manual change. Doctor also reports normalized-key collisions and preserves both entries; an exact work-phone key wins at runtime.

Rules for undeclared channels are ignored. Runtime reads use the selected plugin metadata snapshot; they do not load plugin code to find the rule. See account lookup arguments for the SDK contract.

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.

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

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

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

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

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled and nativeSkillsAutoEnabled can declare static auto defaults for command config checks that run before channel runtime loads. Bundled channels can also publish the same defaults through package.json#openclaw.channel.commands alongside their other package-owned channel catalog metadata.

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

Each channel entry can include:

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

When channels.chat is configured, OpenClaw considers both the channel id and the preferred plugin id. If the lower-priority plugin was only selected because it is bundled or enabled by default, OpenClaw disables it in the effective runtime config so one plugin owns the channel and its tools. Explicit user selection still wins: if the user explicitly enables both plugins (via plugins.allow or a material plugins.entries config), OpenClaw preserves that choice and reports duplicate channel/tool diagnostics instead of silently changing the requested plugin set.

Keep preferOver scoped to plugin ids that can really provide the same channel. It is not a general priority field and it does not rename user config keys.