Plugin entry points

​

Package entries

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

• extensions and setupEntry are source entries, used for workspace and git checkout development.
• runtimeExtensions and runtimeSetupEntry are preferred for installed packages: they let npm packages skip runtime TypeScript compilation.
• runtimeExtensions, when present, must match extensions in array length (entries pair positionally). runtimeSetupEntry requires setupEntry.
• If a runtimeExtensions/runtimeSetupEntry artifact is declared but missing, install/discovery fails with a packaging error; OpenClaw does not silently fall back to source. Source fallback (below) only applies when no runtime entry is declared at all.
• If an installed package declares only a TypeScript source entry, OpenClaw looks for a matching built dist/*.js (or .mjs/.cjs) peer and uses it; otherwise it falls back to the TypeScript source.
• All entry paths must stay inside the plugin package directory. Runtime entries and inferred built-JS peers do not make an escaping extensions or setupEntry source path valid.

​

defineToolPlugin

import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

export default defineToolPlugin({
  id: "stock-quotes",
  name: "Stock Quotes",
  description: "Fetch stock quotes.",
  configSchema: Type.Object({
    apiKey: Type.Optional(Type.String({ description: "API key." })),
  }),
  tools: (tool) => [
    tool({
      name: "quote",
      label: "Quote",
      description: "Fetch a quote.",
      parameters: Type.Object({
        symbol: Type.String({ description: "Ticker symbol." }),
      }),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

• configSchema is optional; omitting it uses a strict empty object schema (the generated manifest still includes configSchema).
• execute returns a plain string or JSON-serializable value; the helper wraps it as a text tool result with details set to the original (unstringified) return value.
• For custom tool results, openclaw/plugin-sdk/tool-results exports textResult and jsonResult.
• Tool names are static, so openclaw plugins build derives contracts.tools from the declared tools without hand-duplicated names.
• Runtime loading stays strict: installed plugins still need openclaw.plugin.json and package.json openclaw.extensions. OpenClaw never executes plugin code to infer missing manifest data.

​

definePluginEntry

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({
      /* ... */
    });
  },
});

• id must match your openclaw.plugin.json manifest.
• kind is deprecated: declare an exclusive slot ("memory" or "context-engine") in the openclaw.plugin.json manifest kind field instead. Runtime-entry kind remains only as a compatibility fallback for older plugins.
• configSchema can be a function for lazy evaluation. OpenClaw resolves and memoizes the schema on first access, so expensive schema builders only run once.

​

defineChannelPluginEntry

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(/* ... */);
  },
});

• setRuntime runs in every mode except "cli-metadata" and "tool-discovery". Store the runtime reference here, typically via createPluginRuntimeStore.
• registerCliMetadata runs for "cli-metadata", "discovery", and "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 registration stays compatible with full plugin loads.
• registerFull runs only for "full" and "tool-discovery". For "tool-discovery" it runs instead of channel registration: OpenClaw skips registerChannel/setRuntime entirely and calls only registerFull, so any provider/tool registration your channel needs for standalone tool discovery or execution must live there, not behind normal channel setup.
• Discovery registration is non-activating, not import-free: OpenClaw may evaluate the trusted plugin entry and channel plugin module to build the snapshot. Keep top-level imports side-effect-free and put sockets, clients, workers, and services behind "full"-only paths.
• Like definePluginEntry, configSchema can be a lazy factory; OpenClaw memoizes the resolved schema on first access.

• Use api.registerCli(..., { descriptors: [...] }) for plugin-owned root CLI commands you want lazy-loaded without disappearing from the root CLI parse tree. Descriptor names must match letters, numbers, hyphen, and underscore, starting with a letter or number; OpenClaw rejects other shapes and strips terminal control sequences from descriptions before rendering help. Cover every top-level command root the registrar exposes. commands alone stays on the eager compatibility path.
• Use api.registerNodeCliFeature(...) for paired-node feature commands so they land under openclaw nodes (equivalent to registerCli(registrar, { parentPath: ["nodes"], ... })).
• For other nested plugin commands, add parentPath and register commands on the program object passed to the registrar; OpenClaw resolves it to the parent command before calling the plugin.
• For channel plugins, register CLI descriptors from registerCliMetadata and keep registerFull focused on runtime-only work.
• If registerFull also registers gateway RPC methods, keep them on a plugin-specific prefix. Reserved core admin namespaces (config.*, exec.approvals.*, wizard.*, update.*) always coerce to operator.admin.

​

defineSetupPluginEntry

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

export default defineSetupPluginEntry(myChannelPlugin);

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",
  },
  registerSetupRuntime(api) {
    api.registerHttpRoute({
      path: "/my-channel/events",
      auth: "plugin",
      handler: async (req, res) => {
        /* setup-safe route */
      },
    });
  },
});

​

Registration mode

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

  if (api.registrationMode === "tool-discovery") {
    // Register capability-only surfaces (providers/tools), no channel.
    return;
  }

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

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

​

Plugin shapes

​

Related

• SDK Overview - registration API and subpath reference
• Runtime Helpers - api.runtime and createPluginRuntimeStore
• Setup and Config - manifest, setup entry, deferred loading
• Channel Plugins - building the ChannelPlugin object
• Provider Plugins - provider registration and hooks