Use this file to discover all available pages before exploring further.

Plugin setup and config

Reference for plugin packaging (

text

package.json

metadata), manifests (

text

openclaw.plugin.json

), setup entries, and config schemas.

tip

**Looking for a walkthrough?** The how-to guides cover packaging in context: [Channel plugins](/plugins/sdk-channel-plugins#step-1-package-and-manifest) and [Provider plugins](/plugins/sdk-provider-plugins#step-1-package-and-manifest).

Package metadata

Your

text

package.json

needs an

text

openclaw

field that tells the plugin system what your plugin provides:

```json} { "name": "@myorg/openclaw-my-channel", "version": "1.0.0", "type": "module", "openclaw": { "extensions": ["./index.ts"], "setupEntry": "./setup-entry.ts", "channel": { "id": "my-channel", "label": "My Channel", "blurb": "Short description of the channel." } } } ``` ```json openclaw-clawhub-package.json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "name": "@myorg/openclaw-my-plugin", "version": "1.0.0", "type": "module", "openclaw": { "extensions": ["./index.ts"], "compat": { "pluginApi": ">=2026.3.24-beta.2", "minGatewayVersion": "2026.3.24-beta.2" }, "build": { "openclawVersion": "2026.3.24-beta.2", "pluginSdkVersion": "2026.3.24-beta.2" } } } ```

note

If you publish the plugin externally on ClawHub, those `compat` and `build` fields are required. The canonical publish snippets live in `docs/snippets/plugin-publish/`.

text
`openclaw`
fields

Entry point files (relative to package root). Lightweight setup-only entry (optional). Channel catalog metadata for setup, picker, quickstart, and status surfaces. Provider ids registered by this plugin. Install hints: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `expectedIntegrity`, `allowInvalidConfigRecovery`. Startup behavior flags.

text
`openclaw.channel`

text

openclaw.channel

is cheap package metadata for channel discovery and setup surfaces before runtime loads.

Field	Type	What it means
text `id`	text `string`	Canonical channel id.
text `label`	text `string`	Primary channel label.
text `selectionLabel`	text `string`	Picker/setup label when it should differ from text `label` .
text `detailLabel`	text `string`	Secondary detail label for richer channel catalogs and status surfaces.
text `docsPath`	text `string`	Docs path for setup and selection links.
text `docsLabel`	text `string`	Override label used for docs links when it should differ from the channel id.
text `blurb`	text `string`	Short onboarding/catalog description.
text `order`	text `number`	Sort order in channel catalogs.
text `aliases`	text `string[]`	Extra lookup aliases for channel selection.
text `preferOver`	text `string[]`	Lower-priority plugin/channel ids this channel should outrank.
text `systemImage`	text `string`	Optional icon/system-image name for channel UI catalogs.
text `selectionDocsPrefix`	text `string`	Prefix text before docs links in selection surfaces.
text `selectionDocsOmitLabel`	text `boolean`	Show the docs path directly instead of a labeled docs link in selection copy.
text `selectionExtras`	text `string[]`	Extra short strings appended in selection copy.
text `markdownCapable`	text `boolean`	Marks the channel as markdown-capable for outbound formatting decisions.
text `exposure`	text `object`	Channel visibility controls for setup, configured lists, and docs surfaces.
text `quickstartAllowFrom`	text `boolean`	Opt this channel into the standard quickstart text `allowFrom` setup flow.
text `forceAccountBinding`	text `boolean`	Require explicit account binding even when only one account exists.
text `preferSessionLookupForAnnounceTarget`	text `boolean`	Prefer session lookup when resolving announce targets for this channel.

Example:


json
{
  "openclaw": {
    "channel": {
      "id": "my-channel",
      "label": "My Channel",
      "selectionLabel": "My Channel (self-hosted)",
      "detailLabel": "My Channel Bot",
      "docsPath": "/channels/my-channel",
      "docsLabel": "my-channel",
      "blurb": "Webhook-based self-hosted chat integration.",
      "order": 80,
      "aliases": ["mc"],
      "preferOver": ["my-channel-legacy"],
      "selectionDocsPrefix": "Guide:",
      "selectionExtras": ["Markdown"],
      "markdownCapable": true,
      "exposure": {
        "configured": true,
        "setup": true,
        "docs": true
      },
      "quickstartAllowFrom": true
    }
  }
}

text

exposure

supports:

text
configured
: include the channel in configured/status-style listing surfaces
text
setup
: include the channel in interactive setup/configure pickers
text
docs
: mark the channel as public-facing in docs/navigation surfaces

note

`showConfigured` and `showInSetup` remain supported as legacy aliases. Prefer `exposure`.

text
`openclaw.install`

text

openclaw.install

is package metadata, not manifest metadata.

Field	Type	What it means
text `npmSpec`	text `string`	Canonical npm spec for install/update flows.
text `localPath`	text `string`	Local development or bundled install path.
text `defaultChoice`	text `"npm"` \| text `"local"`	Preferred install source when both are available.
text `minHostVersion`	text `string`	Minimum supported OpenClaw version in the form text `>=x.y.z` .
text `expectedIntegrity`	text `string`	Expected npm dist integrity string, usually text `sha512-...` , for pinned installs.
text `allowInvalidConfigRecovery`	text `boolean`	Lets bundled-plugin reinstall flows recover from specific stale-config failures.

Deferred full load

Channel plugins can opt into deferred loading with:


json
{
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

When enabled, OpenClaw loads only

text

setupEntry

during the pre-listen startup phase, even for already-configured channels. The full entry loads after the gateway starts listening.

warning

Only enable deferred loading when your `setupEntry` registers everything the gateway needs before it starts listening (channel registration, HTTP routes, gateway methods). If the full entry owns required startup capabilities, keep the default behavior.

If your setup/full entry registers gateway RPC methods, keep them on a plugin-specific prefix. Reserved core admin namespaces (

text

config.*

text

exec.approvals.*

text

wizard.*

text

update.*

) stay core-owned and always resolve to

text

operator.admin

Plugin manifest

Every native plugin must ship an

text

openclaw.plugin.json

in the package root. OpenClaw uses this to validate config without executing plugin code.


json
{
  "id": "my-plugin",
  "name": "My Plugin",
  "description": "Adds My Plugin capabilities to OpenClaw",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "webhookSecret": {
        "type": "string",
        "description": "Webhook verification secret"
      }
    }
  }
}

For channel plugins, add

text

kind

and

text

channels


json
{
  "id": "my-channel",
  "kind": "channel",
  "channels": ["my-channel"],
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

Even plugins with no config must ship a schema. An empty schema is valid:


json
{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

See Plugin manifest for the full schema reference.

ClawHub publishing

For plugin packages, use the package-specific ClawHub command:


bash
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin

note

The legacy skill-only publish alias is for skills. Plugin packages should always use `clawhub package publish`.

Setup entry

The

text

setup-entry.ts

file is a lightweight alternative to

text

index.ts

that OpenClaw loads when it only needs setup surfaces (onboarding, config repair, disabled channel inspection).


typescript
// setup-entry.ts
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { myChannelPlugin } from "./src/channel.js";

export default defineSetupPluginEntry(myChannelPlugin);

This avoids loading heavy runtime code (crypto libraries, CLI registrations, background services) during setup flows.

Bundled workspace channels that keep setup-safe exports in sidecar modules can use

text

defineBundledChannelSetupEntry(...)

from

text

openclaw/plugin-sdk/channel-entry-contract

instead of

text

defineSetupPluginEntry(...)

. That bundled contract also supports an optional

text

runtime

export so setup-time runtime wiring can stay lightweight and explicit.

Narrow setup helper imports

For hot setup-only paths, prefer the narrow setup helper seams over the broader

text

plugin-sdk/setup

umbrella when you only need part of the setup surface:

Import path	Use it for	Key exports
text `plugin-sdk/setup-runtime`	setup-time runtime helpers that stay available in text `setupEntry` / deferred channel startup	text `createPatchedAccountSetupAdapter` , text `createEnvPatchedAccountSetupAdapter` , text `createSetupInputPresenceValidator` , text `noteChannelLookupFailure` , text `noteChannelLookupSummary` , text `promptResolvedAllowFrom` , text `splitSetupEntries` , text `createAllowlistSetupWizardProxy` , text `createDelegatedSetupWizardProxy`
text `plugin-sdk/setup-adapter-runtime`	environment-aware account setup adapters	text `createEnvPatchedAccountSetupAdapter`
text `plugin-sdk/setup-tools`	setup/install CLI/archive/docs helpers	text `formatCliCommand` , text `detectBinary` , text `extractArchive` , text `resolveBrewExecutable` , text `formatDocsLink` , text `CONFIG_DIR`

Use the broader

text

plugin-sdk/setup

seam when you want the full shared setup toolbox, including config-patch helpers such as

text

moveSingleAccountChannelSectionToDefaultAccount(...)

The setup patch adapters stay hot-path safe on import. Their bundled single-account promotion contract-surface lookup is lazy, so importing

text

plugin-sdk/setup-runtime

does not eagerly load bundled contract-surface discovery before the adapter is actually used.

Channel-owned single-account promotion

When a channel upgrades from a single-account top-level config to

text

channels.<id>.accounts.*

, the default shared behavior is to move promoted account-scoped values into

text

accounts.default

Bundled channels can narrow or override that promotion through their setup contract surface:

text
singleAccountKeysToMove
: extra top-level keys that should move into the promoted account
text
namedAccountPromotionKeys
: when named accounts already exist, only these keys move into the promoted account; shared policy/delivery keys stay at the channel root
text
resolveSingleAccountPromotionTarget(...)
: choose which existing account receives promoted values

note

Matrix is the current bundled example. If exactly one named Matrix account already exists, or if `defaultAccount` points at an existing non-canonical key such as `Ops`, promotion preserves that account instead of creating a new `accounts.default` entry.

Config schema

Plugin config is validated against the JSON Schema in your manifest. Users configure plugins via:


json5
{
  plugins: {
    entries: {
      "my-plugin": {
        config: {
          webhookSecret: "abc123",
        },
      },
    },
  },
}

Your plugin receives this config as

text

api.pluginConfig

during registration.

For channel-specific config, use the channel config section instead:


json5
{
  channels: {
    "my-channel": {
      token: "bot-token",
      allowFrom: ["user1", "user2"],
    },
  },
}

Building channel config schemas

Use

text

buildChannelConfigSchema

to convert a Zod schema into the

text

ChannelConfigSchema

wrapper used by plugin-owned config artifacts:


typescript
import { z } from "zod";
import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";

const accountSchema = z.object({
  token: z.string().optional(),
  allowFrom: z.array(z.string()).optional(),
  accounts: z.object({}).catchall(z.any()).optional(),
  defaultAccount: z.string().optional(),
});

const configSchema = buildChannelConfigSchema(accountSchema);

For third-party plugins, the cold-path contract is still the plugin manifest: mirror the generated JSON Schema into

text

openclaw.plugin.json#channelConfigs

so config schema, setup, and UI surfaces can inspect

text

channels.<id>

without loading runtime code.

Setup wizards

Channel plugins can provide interactive setup wizards for

text

openclaw onboard

. The wizard is a

text

ChannelSetupWizard

object on the

text

ChannelPlugin


typescript
import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";

const setupWizard: ChannelSetupWizard = {
  channel: "my-channel",
  status: {
    configuredLabel: "Connected",
    unconfiguredLabel: "Not configured",
    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),
  },
  credentials: [
    {
      inputKey: "token",
      providerHint: "my-channel",
      credentialLabel: "Bot token",
      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",
      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",
      keepPrompt: "Keep current token?",
      inputPrompt: "Enter your bot token:",
      inspect: ({ cfg, accountId }) => {
        const token = (cfg.channels as any)?.["my-channel"]?.token;
        return {
          accountConfigured: Boolean(token),
          hasConfiguredValue: Boolean(token),
        };
      },
    },
  ],
};

The

text

ChannelSetupWizard

type supports

text

credentials

text

textInputs

text

dmPolicy

text

allowFrom

text

groupAccess

text

prepare

text

finalize

, and more. See bundled plugin packages (for example the Discord plugin

text

src/channel.setup.ts

) for full examples.

Publishing and installing

External plugins: publish to ClawHub, then install:

```bash} openclaw plugins install @myorg/openclaw-my-plugin ```


text
OpenClaw tries ClawHub first and falls back to npm automatically.

```bash} openclaw plugins install clawhub:@myorg/openclaw-my-plugin ``` Use npm when a package has not moved to ClawHub yet, or when you need a direct npm install path during migration:


text
```bash}
openclaw plugins install npm:@myorg/openclaw-my-plugin
```

In-repo plugins: place under the bundled plugin workspace tree and they are automatically discovered during build.

Users can install:


bash
openclaw plugins install <package-name>

info

For npm-sourced installs, `openclaw plugins install` runs project-local `npm install --ignore-scripts` (no lifecycle scripts), ignoring inherited global npm install settings. Keep plugin dependency trees pure JS/TS and avoid packages that require `postinstall` builds.

note

Bundled OpenClaw-owned plugins are the only startup repair exception: when a packaged install sees one enabled by plugin config, legacy channel config, or its bundled default-enabled manifest, startup installs that plugin's missing runtime dependencies before import. Operators can inspect or repair that stage with `openclaw plugins deps`. Third-party plugins should not rely on startup installs; keep using the explicit plugin installer.

Bundled package-level runtime deps are explicit metadata, not inferred from built JavaScript at gateway startup. If a shared OpenClaw root dependency must be available inside the external bundled-plugin runtime mirror, declare it in

text

openclaw.bundle.mirroredRootRuntimeDependencies

in the root package manifest.

Building plugins — step-by-step getting started guide
Plugin manifest — full manifest schema reference
SDK entry points —
text
definePluginEntry
and
text
defineChannelPluginEntry

OpenClaw Docs

Plugin setup and config

tip

Package metadata

note

text
`openclaw`
fields

text
`openclaw.channel`

note

text
`openclaw.install`

Deferred full load

warning

Plugin manifest

ClawHub publishing

note

Setup entry

Narrow setup helper imports

Channel-owned single-account promotion

note

Config schema

Building channel config schemas

Setup wizards

Publishing and installing

info

note

Related

OpenClaw Docs

Plugin setup and config

tip

Package metadata

note

textCopyopenclaw fields

textCopyopenclaw.channel

note

textCopyopenclaw.install

Deferred full load

warning

Plugin manifest

ClawHub publishing

note

Setup entry

Narrow setup helper imports

Channel-owned single-account promotion

note

Config schema

Building channel config schemas

Setup wizards

Publishing and installing

info

note

Related

text
`openclaw`
fields

text
`openclaw.channel`

text
`openclaw.install`