Plugin setup and config

Reference for plugin packaging (package.json metadata), manifests (openclaw.plugin.json), setup entries, and config schemas.

On this page:

• Package metadata
• Plugin manifest
• Setup entry
• Config schema
• Setup wizards
• Publishing and installing

Package metadata

Your package.json needs an openclaw field that tells the plugin system what your plugin provides:

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

{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "dependencies": {    "typebox": "1.3.18"  },  "peerDependencies": {    "openclaw": ">=2026.3.24-beta.2"  },  "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"    }  }}

openclaw fields

openclaw.channel

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

Channel-owned setup fields

Channel plugins should define setup fields once in runtime code with defineChannelSetupContract(...) and publish the matching serializable projection under openclaw.channel.setup.fields. The runtime definition infers the plugin-local input type, parses both guided and non-interactive values, and keeps channel-specific keys out of core types. Package metadata lets openclaw channels add <channel-id> --help and openclaw channels add --channel <channel-id> --help discover only the selected channel's options without loading the plugin.

import { defineChannelSetupContract } from "openclaw/plugin-sdk/channel-setup"; export const setupContract = defineChannelSetupContract({  fields: {    endpoint: {      kind: "string",      cli: { flags: "--endpoint <url>", description: "Service endpoint" },    },    transport: {      kind: "choice",      choices: ["native", "container"],      cli: { flags: "--transport <kind>", description: "Transport owner" },    },  },  adapter: {    applyAccountConfig: ({ cfg, input }) => ({      ...cfg,      channels: { ...cfg.channels, example: input },    }),  },});

{  "openclaw": {    "channel": {      "id": "example",      "setup": {        "fields": [          {            "key": "endpoint",            "kind": "string",            "cli": { "flags": "--endpoint <url>", "description": "Service endpoint" }          },          {            "key": "transport",            "kind": "choice",            "choices": ["native", "container"],            "cli": { "flags": "--transport <kind>", "description": "Transport owner" }          }        ]      }    }  }}

Supported field kinds are string, boolean, integer, string-list, and choice. Use sensitive: true for credentials. Each field key must equal the camelCased attribute name of its long CLI flag, including any negated form, such as apiToken for --api-token. Boolean fields may add cli.negatedFlags when both positive and --no-* forms are needed. channel, account, and the account display name remain the shared control envelope.

For a boolean useEnv field, set envVars to the static environment variable names required by the plugin runtime. Non-interactive channel setup then rejects --use-env before writing config when any declared variable is empty. Set envVarMode: "any" when one variable from the list is sufficient, such as an inline credential or file-path alternative. Omitting envVars preserves the plugin's existing validation behavior.

The released setup/ChannelSetupInput adapter stays available for existing external plugins. New plugins should expose setupContract. OpenClaw always prefers it when both are present.

Use afterAccountConfigWritten (or a wizard's afterConfigWritten) for connection checks and other work that requires saved configuration. OpenClaw runs these callbacks after the write succeeds and passes a runtime cfg reread from the exact committed file, with environment references and plugin defaults resolved. The saved file can retain ${VAR} references. Missing or invalid saved configuration prevents callback execution. Callback failures are reported as post-setup warnings without undoing the saved configuration.

Example:

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

exposure supports:

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

openclaw.install

openclaw.install is package metadata, not manifest metadata.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/[email protected]",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

Setup-time gateway methods

If your setup/full entry registers gateway RPC methods, keep them on a plugin-specific prefix. Reserved core admin namespaces (config.*, exec.approvals.*, wizard.*, update.*) stay core-owned and always normalize to operator.admin.

Plugin manifest

Every native plugin must ship an openclaw.plugin.json in the package root. OpenClaw uses this to validate config without executing plugin code.

{  "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 channels (and provider plugins add providers):

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

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

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

See Plugin manifest for the full schema reference.

Setup entry

setup-entry.ts is a lightweight alternative to index.ts that OpenClaw loads when it only needs setup surfaces (onboarding, config repair, disabled channel inspection):

// setup-entry.tsimport { 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 defineBundledChannelSetupEntry(...) from openclaw/plugin-sdk/channel-entry-contract instead of defineSetupPluginEntry(...). That bundled contract also supports an optional 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 plugin-sdk/setup umbrella when you only need part of the setup surface:

Use the broader plugin-sdk/setup seam when you want the full shared setup toolbox, including config-patch helpers such as moveSingleAccountChannelSectionToDefaultAccount(...).

Use createSetupTranslator(...) for fixed setup wizard copy. It uses the first nonblank value from OPENCLAW_LOCALE, LC_ALL, LC_MESSAGES, and LANG, in that order, then falls back to English. Set OPENCLAW_LOCALE=en for an explicit English override. Keep plugin-specific setup text in plugin-owned code and use shared catalog keys only for common setup labels, status text, and official bundled plugin setup copy.

The setup patch adapters do no eager work when a plugin imports them. Their bundled single-account promotion contract-surface lookup is lazy, so importing plugin-sdk/setup-runtime does not eagerly load bundled contract-surface discovery before the adapter is actually used.

Channel-owned setup input fields

ChannelSetupInput is a generic envelope shared by setup callers and channel plugins. Its permanently typed fields are name, token, tokenFile, useEnv, allowFrom, and defaultTo. Additional plugin-owned keys can still be present on the runtime input object, but the shared type does not declare an index signature. Each plugin must declare and narrow its own setup fields or validate them with a plugin-owned schema at the adapter boundary:

import type { ChannelSetupAdapter, ChannelSetupInput } from "openclaw/plugin-sdk/channel-setup"; type AcmeSetupInput = ChannelSetupInput & {  workspaceId?: string;  webhookUrl?: string;}; export const acmeSetupAdapter: ChannelSetupAdapter = {  applyAccountConfig: ({ cfg, input }) => {    const setupInput = input as AcmeSetupInput;    return {      ...cfg,      channels: {        ...cfg.channels,        acme: {          token: setupInput.token,          workspaceId: setupInput.workspaceId,          webhookUrl: setupInput.webhookUrl,        },      },    };  },};

Channel-specific fields that were previously declared directly on ChannelSetupInput remain temporarily typed for external source compatibility. They are deprecated. A 2026-07-22 registry sweep of 426 published out-of-tree channel plugins removed 21 fields with no readers and retained 22 with known readers. Each retained field is deleted as soon as no published plugin reads it. No version boundary is required. New and bundled plugins must not rely on this tier. Declare the fields they own locally.

Channel-owned single-account promotion

When a channel upgrades from a single-account top-level config to channels.<id>.accounts.*, the default shared behavior moves promoted account-scoped values into accounts.default.

Every channel plugin can extend or narrow that promotion through its setup adapter:

• configPromotion: "preserve-root": keep all root values in place, including common name, policy, and delivery fields. The plugin owns its account layout
• singleAccountKeysToMove: extra top-level keys that should move into the promoted account
• namedAccountPromotionKeys: when named accounts already exist, only these keys move into the promoted account. Shared policy/delivery keys stay at the channel root
• resolveSingleAccountPromotionTarget(...): choose which existing account receives promoted values

The presence of singleAccountKeysToMove marks the promotion contract complete. Declare the field even when it is an empty array to opt out of legacy key promotion. An empty array does not suppress common fields. Adapters that omit the field retain a reader-backed pre-declaration promotion tier for already-published plugins. The 2026-07-22 registry sweep removed 23 keys with no published dependents and retained six common keys plus the setup-only rooms key. Each retained key is deleted as soon as its published readers migrate to declarations. No version boundary is required.

Declare openclaw.setupFeatures.configPromotion: true in the plugin package manifest when doctor must load these declarations from the lightweight setup entry. Doctor discovers that entry through the plugin manifest for both bundled and installed plugins, including disabled plugins. The setup-only plugin surface and the full channel plugin must expose the same declarations.

For a plugin-owned root layout, also declare openclaw.setupFeatures.configPromotion: "preserve-root" in package.json. Doctor reads this static declaration for installed and bundled plugins, including disabled plugins, without executing their runtime. Omitting the declaration or using false does not opt out of promotion. The runtime declaration belongs on the adapter passed to defineChannelSetupContract, and covers shared CLI, declarative wizard, and policy-writer promotion. It does not change helpers that explicitly migrate a base name. Use a selected-account writer when the root remains an implicit identity. Buzz is an example of this layout.

When calling moveSingleAccountChannelSectionToDefaultAccount(...) with an already resolved plugin, pass its setup adapter as setupSurface. Caller-supplied setup surfaces take precedence over loaded and bundled lookup, which keeps scoped or setup-only plugins independent of global registration.

Config schema

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

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

Your plugin receives this config as api.pluginConfig during registration.

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

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

Building channel config schemas

Use buildChannelConfigSchema to convert a Zod schema into the ChannelConfigSchema wrapper used by plugin-owned config artifacts:

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

If you already author the contract as JSON Schema or TypeBox, use the direct helper so OpenClaw can skip Zod-to-JSON-Schema conversion on metadata paths:

import { Type } from "typebox";import { buildJsonChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema"; const configSchema = buildJsonChannelConfigSchema(  Type.Object({    token: Type.Optional(Type.String()),    allowFrom: Type.Optional(Type.Array(Type.String())),  }),);

For third-party plugins, the cold-path contract is still the plugin manifest: mirror the generated JSON Schema into openclaw.plugin.json#channelConfigs so config schema, setup, and UI surfaces can inspect channels.<id> without loading runtime code.

Setup wizards

Channel plugins can provide interactive setup wizards for openclaw onboard. The wizard is a ChannelSetupWizard object on the ChannelPlugin:

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),        };      },    },  ],};

ChannelSetupWizard also supports textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize, and more. See the Discord plugin's src/setup-core.ts for a full bundled example.

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; const setupSurface = createOptionalChannelSetupSurface({  channel: "my-channel",  label: "My Channel",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Returns { setupAdapter, setupWizard }

Publishing and installing

External plugins: publish to ClawHub, then install:

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

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

Bundled package metadata is explicit, not inferred from built JavaScript at gateway startup. Runtime dependencies belong in the plugin package that owns them. Packaged OpenClaw startup never repairs or mirrors plugin dependencies.

ClawHub publishing

Skills and plugin packages use separate ClawHub publish commands. For plugin packages, use the package-specific command:

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

Related

• Building plugins — step-by-step getting started guide
• Plugin manifest — full manifest schema reference
• SDK entry points — definePluginEntry and defineChannelPluginEntry
• Plugin SDK overview — import map and registration API reference
• Plugin SDK subpaths — the public entry point catalog
• Plugin architecture internals — load pipeline and registry model