Plugin SDK Reference

Complete reference for the OpenClaw Plugin SDK

The Plugin SDK provides APIs for registering channels, tools, hooks, services, and HTTP handlers. Import from openclaw/plugin-sdk:

import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";

Plugin API

The OpenClawPluginApi is passed to your plugin’s register and activate functions.

Properties

id · string

Plugin identifier (e.g., "matrix", "my-plugin")

name · string

Plugin display name

version · string

Plugin version from package.json

description · string

Plugin description

source · string

Absolute path to the plugin entry point

config · OpenClawConfig

OpenClaw configuration object. Access via api.config.channels, api.config.agents, etc.

pluginConfig · Record<string, unknown>

Plugin-specific configuration from config.json under plugins.entries[id].config

runtime · PluginRuntime

Runtime services for media, messaging, logging, and more. See Runtime Services.

logger · PluginLogger

Scoped logger for plugin messages:

api.logger.info("Plugin started");
api.logger.warn("Deprecation warning");
api.logger.error("Operation failed");
api.logger.debug?.("Verbose output");

Registration Methods

registerTool · (tool: AnyAgentTool | OpenClawPluginToolFactory, opts?: OpenClawPluginToolOptions) => void

Register an agent tool. Tools are exposed to the LLM and can be called during agent runs.

api.registerTool(createMyTool());
api.registerTool(createMyTool(), { optional: true });
api.registerTool(toolFactory, { names: ["tool1", "tool2"] });

Options:

• name?: string - Tool name override
• names?: string[] - Multiple tool names (for tool factories)
• optional?: boolean - Require explicit allowlisting in agent config

registerHook · (events: string | string[], handler: InternalHookHandler, opts?: OpenClawPluginHookOptions) => void

Register a lifecycle hook. Hooks intercept events at key points in the message lifecycle.

api.registerHook("llm_input", async (event, ctx) => {
  api.logger.info(`LLM call: ${event.provider}/${event.model}`);
});

api.registerHook(["message_received", "message_sent"], handler);

See Hooks for available events.

registerChannel · (registration: OpenClawPluginChannelRegistration | ChannelPlugin) => void

Register a channel plugin. Channel plugins integrate messaging platforms.

api.registerChannel({ plugin: myChannelPlugin });

See Channels for details.

registerService · (service: OpenClawPluginService) => void

Register a background service. Services run persistent background tasks.

api.registerService({
  id: "my-service",
  start: async (ctx) => {
    // Start background task
  },
  stop: async (ctx) => {
    // Clean up
  }
});

registerHttpRoute · (params: { path: string; handler: OpenClawPluginHttpRouteHandler }) => void

Register an HTTP route for webhooks or custom endpoints.

api.registerHttpRoute({
  path: "/webhook/my-plugin",
  handler: async (req, res) => {
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ ok: true }));
  }
});

Routes are automatically normalized to prevent conflicts.

registerHttpHandler · (handler: OpenClawPluginHttpHandler) => void

Register a global HTTP handler. Handlers are called for all requests.

api.registerHttpHandler((req, res) => {
  if (req.url?.startsWith("/my-prefix")) {
    // Handle request
    return true; // Handled
  }
  return false; // Pass to next handler
});

registerCli · (registrar: OpenClawPluginCliRegistrar, opts?: { commands?: string[] }) => void

Register CLI commands. Add custom commands to the openclaw CLI.

api.registerCli((ctx) => {
  ctx.program
    .command("my-command")
    .description("Custom command")
    .action(() => {
      ctx.logger.info("Command executed");
    });
});

registerCommand · (command: OpenClawPluginCommandDefinition) => void

Register a plugin command. Plugin commands bypass the LLM agent and are processed before built-in commands.

api.registerCommand({
  name: "status",
  description: "Check plugin status",
  acceptsArgs: false,
  requireAuth: true,
  handler: async (ctx) => {
    return { text: "Plugin is running" };
  }
});

registerProvider · (provider: ProviderPlugin) => void

Register an authentication provider. Providers integrate with openclaw login.

api.registerProvider({
  id: "my-provider",
  label: "My Provider",
  auth: [/* auth methods */]
});

registerGatewayMethod · (method: string, handler: GatewayRequestHandler) => void

Register a custom gateway method. Gateway methods are JSON-RPC endpoints exposed via the gateway.

api.registerGatewayMethod("my.method", async (params) => {
  return { result: "success" };
});

Utility Methods

resolvePath · (input: string) => string

Resolve paths relative to the plugin source directory.

const configPath = api.resolvePath("./config.json");
const srcPath = api.resolvePath("src/helper.ts");

on · <K extends PluginHookName>(hookName: K, handler: PluginHookHandlerMap[K], opts?: { priority?: number }) => void

Alternative API for registering lifecycle hooks with typed event handlers.

api.on("llm_input", async (event, ctx) => {
  api.logger.info(`Model: ${event.model}`);
});

Runtime Services

The api.runtime object provides access to OpenClaw’s core services.

Config

api.runtime.config.loadConfig();
api.runtime.config.writeConfigFile(config);

Media

const media = await api.runtime.media.loadWebMedia(url);
const mime = api.runtime.media.detectMime(buffer);
const metadata = await api.runtime.media.getImageMetadata(buffer);
const jpeg = await api.runtime.media.resizeToJpeg(buffer, { maxWidth: 1024 });

Text Processing

const chunks = api.runtime.channel.text.chunkMarkdownText(text, limit);
const mode = api.runtime.channel.text.resolveChunkMode(config);
const hasCommand = api.runtime.channel.text.hasControlCommand(text);

Reply Dispatching

await api.runtime.channel.reply.dispatchReplyFromConfig({
  config,
  channelId: "telegram",
  to: "123456789",
  text: "Hello"
});

Logging

const childLogger = api.runtime.logging.getChildLogger(
  { component: "my-plugin" },
  { level: "info" }
);

if (api.runtime.logging.shouldLogVerbose()) {
  childLogger.debug("Verbose log message");
}

State Directory

const stateDir = api.runtime.state.resolveStateDir(config);

Channel-Specific Services

The runtime provides channel-specific helpers:

// Discord
api.runtime.channel.discord.sendMessageDiscord(...);
api.runtime.channel.discord.probeDiscord(...);

// Slack
api.runtime.channel.slack.sendMessageSlack(...);
api.runtime.channel.slack.probeSlack(...);

// Telegram
api.runtime.channel.telegram.sendMessageTelegram(...);
api.runtime.channel.telegram.probeTelegram(...);

// WhatsApp
api.runtime.channel.whatsapp.sendMessageWhatsApp(...);
api.runtime.channel.whatsapp.loginWeb(...);

// Signal
api.runtime.channel.signal.sendMessageSignal(...);

// iMessage
api.runtime.channel.imessage.sendMessageIMessage(...);

// LINE
api.runtime.channel.line.sendMessageLine(...);

See the runtime types for the complete API.

Plugin SDK Exports

The openclaw/plugin-sdk package exports types and utilities:

Types

import type {
  OpenClawPluginApi,
  OpenClawPluginDefinition,
  OpenClawPluginService,
  PluginRuntime,
  RuntimeLogger,
  AnyAgentTool,
  ChannelPlugin,
  ChannelConfigSchema,
  HookEntry,
  OpenClawConfig,
  ProviderAuthContext,
  ProviderAuthResult
} from "openclaw/plugin-sdk";

Helper Functions

import {
  emptyPluginConfigSchema,
  normalizePluginHttpPath,
  registerPluginHttpRoute,
  normalizeWebhookPath,
  resolveWebhookPath,
  registerWebhookTarget,
  buildAgentMediaPayload,
  buildBaseChannelStatusSummary,
  buildOauthProviderAuthResult,
  acquireFileLock,
  withFileLock
} from "openclaw/plugin-sdk";

Channel Helpers

import {
  createAccountListHelpers,
  buildChannelConfigSchema,
  resolveChannelAccountConfigBasePath,
  recordInboundSession,
  createReplyPrefixContext,
  createTypingCallbacks,
  extractToolSend,
  formatDocsLink
} from "openclaw/plugin-sdk";

Config Schemas (Zod)

import {
  DiscordConfigSchema,
  GoogleChatConfigSchema,
  IMessageConfigSchema,
  MSTeamsConfigSchema,
  SignalConfigSchema,
  SlackConfigSchema,
  TelegramConfigSchema,
  WhatsAppConfigSchema,
  DmConfigSchema,
  GroupPolicySchema,
  MarkdownConfigSchema,
  ToolPolicySchema
} from "openclaw/plugin-sdk";

Example: Complete Plugin

import type { OpenClawPluginApi, AnyAgentTool } from "openclaw/plugin-sdk";
import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
import { Type } from "@sinclair/typebox";

function createExampleTool(api: OpenClawPluginApi): AnyAgentTool {
  return {
    name: "example",
    description: "Example tool",
    input: Type.Object({
      message: Type.String()
    }),
    execute: async (args) => {
      api.logger.info(`Tool called: ${args.message}`);
      return { result: "success", details: { message: args.message } };
    }
  };
}

const plugin = {
  id: "example",
  name: "Example Plugin",
  description: "Demonstrates plugin SDK features",
  configSchema: emptyPluginConfigSchema(),
  
  register(api: OpenClawPluginApi) {
    // Register tool
    api.registerTool(createExampleTool(api));

    // Register hook
    api.registerHook("llm_input", async (event, ctx) => {
      api.logger.info(`LLM call: ${event.provider}/${event.model}`);
    });

    // Register HTTP route
    api.registerHttpRoute({
      path: "/webhook/example",
      handler: async (req, res) => {
        res.writeHead(200);
        res.end("OK");
      }
    });

    api.logger.info("Plugin registered");
  },

  activate(api: OpenClawPluginApi) {
    api.logger.info("Plugin activated");
  }
};

export default plugin;

Next Steps

• Hooks - Implement lifecycle hooks
• Tools - Build custom agent tools
• Channels - Create channel integrations
• Examples - Real-world plugin examples