Plugin entry points

Every plugin exports a default entry object. The SDK provides three helpers for creating them.

For installed plugins,

should point runtime loading at built JavaScript when available:

json
Copy
{
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"],
    "setupEntry": "./src/setup-entry.ts",
    "runtimeSetupEntry": "./dist/setup-entry.js"
  }
}

and remain valid source entries for workspace and git checkout development. and are preferred when OpenClaw loads an installed package and let npm packages avoid runtime TypeScript compilation. If an installed package only declares a TypeScript source entry, OpenClaw will use a matching built peer when one exists, then fall back to the TypeScript source.

All entry paths must stay inside the plugin package directory. Runtime entries and inferred built JavaScript peers do not make an escaping

or source path valid.

text

Copy

definePluginEntry

Import:

For provider plugins, tool plugins, hook plugins, and anything that is not a messaging channel.

typescript
Copy
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
  },
});

• text

  Copy

  id
  must match your
  text

  Copy

  openclaw.plugin.json
  manifest.
• text

  Copy

  kind
  is for exclusive slots:
  text

  Copy

  "memory"
  or
  text

  Copy

  "context-engine"
  .
• text

  Copy

  configSchema
  can be a function for lazy evaluation.
• OpenClaw resolves and memoizes that schema on first access, so expensive schema builders only run once.

text

Copy

defineChannelPluginEntry

Import:

Wraps

with channel-specific wiring. Automatically calls , exposes an optional root-help CLI metadata seam, and gates on registration mode.

typescript
Copy
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});

• text

  Copy

  setRuntime
  is called during registration so you can store the runtime reference (typically via
  text

  Copy

  createPluginRuntimeStore
  ). It is skipped during CLI metadata capture.
• text

  Copy

  registerCliMetadata
  runs during
  text

  Copy

  api.registrationMode === "cli-metadata"
  ,
  text

  Copy

  api.registrationMode === "discovery"
  , and
  text

  Copy

  api.registrationMode === "full"
  . Use it as the canonical place for channel-owned CLI descriptors so root help stays non-activating, discovery snapshots include static command metadata, and normal CLI command registration remains compatible with full plugin loads.
• Discovery registration is non-activating, not import-free. OpenClaw may evaluate the trusted plugin entry and channel plugin module to build the snapshot, so keep top-level imports side-effect-free and put sockets, clients, workers, and services behind
  text

  Copy

  "full"
  -only paths.
• text

  Copy

  registerFull
  only runs when
  text

  Copy

  api.registrationMode === "full"
  . It is skipped during setup-only loading.
• Like
  text

  Copy

  definePluginEntry
  ,
  text

  Copy

  configSchema
  can be a lazy factory and OpenClaw memoizes the resolved schema on first access.
• For plugin-owned root CLI commands, prefer
  text

  Copy

  api.registerCli(..., { descriptors: [...] })
  when you want the command to stay lazy-loaded without disappearing from the root CLI parse tree. For channel plugins, prefer registering those descriptors from
  text

  Copy

  registerCliMetadata(...)
  and keep
  text

  Copy

  registerFull(...)
  focused on runtime-only work.
• If
  text

  Copy

  registerFull(...)
  also registers gateway RPC methods, keep them on a plugin-specific prefix. Reserved core admin namespaces (
  text

  Copy

  config.*
  ,
  text

  Copy

  exec.approvals.*
  ,
  text

  Copy

  wizard.*
  ,
  text

  Copy

  update.*
  ) are always coerced to
  text

  Copy

  operator.admin
  .

text

Copy

defineSetupPluginEntry

Import:

For the lightweight

file. Returns just with no runtime or CLI wiring.

typescript
Copy
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);

OpenClaw loads this instead of the full entry when a channel is disabled, unconfigured, or when deferred loading is enabled. See Setup and Config for when this matters.

In practice, pair

with the narrow setup helper families:

• text

  Copy

  openclaw/plugin-sdk/setup-runtime
  for runtime-safe setup helpers such as import-safe setup patch adapters, lookup-note output,
  text

  Copy

  promptResolvedAllowFrom
  ,
  text

  Copy

  splitSetupEntries
  , and delegated setup proxies
• text

  Copy

  openclaw/plugin-sdk/channel-setup
  for optional-install setup surfaces
• text

  Copy

  openclaw/plugin-sdk/setup-tools
  for setup/install CLI/archive/docs helpers

Keep heavy SDKs, CLI registration, and long-lived runtime services in the full entry.

Bundled workspace channels that split setup and runtime surfaces can use

from instead. That contract lets the setup entry keep setup-safe plugin/secrets exports while still exposing a runtime setter:

typescript
Copy
import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

export default defineBundledChannelSetupEntry({
  importMetaUrl: import.meta.url,
  plugin: {
    specifier: "./channel-plugin-api.js",
    exportName: "myChannelPlugin",
  },
  runtime: {
    specifier: "./runtime-api.js",
    exportName: "setMyChannelRuntime",
  },
});

Use that bundled contract only when setup flows truly need a lightweight runtime setter before the full channel entry loads.

Registration mode

tells your plugin how it was loaded:

handles this split automatically. If you use directly for a channel, check mode yourself:

typescript
Copy
register(api) {
  if (
    api.registrationMode === "cli-metadata" ||
    api.registrationMode === "discovery" ||
    api.registrationMode === "full"
  ) {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Heavy runtime-only registrations
  api.registerService(/* ... */);
}

Discovery mode builds a non-activating registry snapshot. It may still evaluate the plugin entry and the channel plugin object so OpenClaw can register channel capabilities and static CLI descriptors. Treat module evaluation in discovery as trusted but lightweight: no network clients, subprocesses, listeners, database connections, background workers, credential reads, or other live runtime side effects at top level.

Treat

as the window where setup-only startup surfaces must exist without re-entering the full bundled channel runtime. Good fits are channel registration, setup-safe HTTP routes, setup-safe gateway methods, and delegated setup helpers. Heavy background services, CLI registrars, and provider/client SDK bootstraps still belong in .

For CLI registrars specifically:

• use
  text

  Copy

  descriptors
  when the registrar owns one or more root commands and you want OpenClaw to lazy-load the real CLI module on first invocation
• make sure those descriptors cover every top-level command root exposed by the registrar
• keep descriptor command names to letters, numbers, hyphen, and underscore, starting with a letter or number; OpenClaw rejects descriptor names outside that shape and strips terminal control sequences from descriptions before rendering help
• use
  text

  Copy

  commands
  alone only for eager compatibility paths

Plugin shapes

OpenClaw classifies loaded plugins by their registration behavior:

Use

to see a plugin's shape.

Related

• SDK Overview — registration API and subpath reference
• Runtime Helpers —
  text

  Copy

  api.runtime
  and
  text

  Copy

  createPluginRuntimeStore
• Setup and Config — manifest, setup entry, deferred loading
• Channel Plugins — building the
  text

  Copy

  ChannelPlugin
  object
• Provider Plugins — provider registration and hooks