Extensions — Modular Plugin Ecosystem

Plugin SDK Hot Reload Manifest-Driven Sandboxed Imports

Architecture

Extensions sit between external services and OpenClaw’s core gateway. The Plugin SDK provides the contract boundary — extensions import only from openclaw/plugin-sdk/* subpaths, never from src/** internals.

flowchart LR
  subgraph External["External Services"]
    LLM["LLM APIs"]
    Chat["Chat Platforms"]
    Search["Search Engines"]
    Voice["Voice Services"]
  end
  subgraph Extensions["extensions/"]
    Providers["Provider Extensions"]
    Channels["Channel Extensions"]
    SearchExt["Search Extensions"]
    MediaExt["Media Extensions"]
    Utils["Utility Extensions"]
  end
  subgraph Core["OpenClaw Core"]
    SDK["Plugin SDK"]
    Gateway["Gateway"]
    Agent["Agent Engine"]
  end
  LLM --> Providers
  Chat --> Channels
  Search --> SearchExt
  Voice --> MediaExt
  Providers --> SDK
  Channels --> SDK
  SearchExt --> SDK
  MediaExt --> SDK
  Utils --> SDK
  SDK --> Gateway
  Gateway --> Agent

Extension Registration Flow

When OpenClaw boots, the plugin loader scans package.json manifests, resolves entry points, and calls each extension’s register(api) function. The registration API accumulates providers, channels, hooks, tools, and HTTP routes into the core registry.

sequenceDiagram
  participant Loader as Plugin Loader
  participant Manifest as package.json
  participant Entry as Extension Entry
  participant API as OpenClawPluginApi
  participant Registry as Core Registry
  Loader->>Manifest: Read openclaw.extensions[]
  Loader->>Entry: import default export
  Entry->>API: definePluginEntry({ id, register })
  API->>Entry: register(api) callback
  Entry->>API: api.registerProvider(...)
  Entry->>API: api.registerChannel(...)
  Entry->>API: api.registerHook(...)
  API->>Registry: Accumulate registrations
  Registry-->>Loader: Extension ready

Extension Categories

AI Providers

Provider extensions implement the ProviderPlugin interface, supplying model catalogs, auth methods, transport normalization, and streaming logic.

Messaging Channels

Channel extensions implement the ChannelPlugin interface with adapters for messaging, outbound delivery, threading, security, and gateway HTTP methods.

Search & Web

Media & Voice

Utilities

Shared Extension Contract

Every extension follows the same discovery and registration contract. The entry point exports a DefinedPluginEntry created by one of two helper functions depending on the extension type:

General Plugins — definePluginEntry()

// extensions/openai/index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { buildOpenAIProvider } from "./openai-provider.js";
import { buildOpenAISpeechProvider } from "./speech-provider.js";
import { buildOpenAIImageGenerationProvider } from "./image-generation-provider.js";

export default definePluginEntry({
  id: "openai",
  name: "OpenAI Provider",
  description: "Bundled OpenAI provider plugins",
  register(api) {
    api.registerProvider(buildOpenAIProvider());
    api.registerSpeechProvider(buildOpenAISpeechProvider());
    api.registerImageGenerationProvider(buildOpenAIImageGenerationProvider());
    api.registerCliBackend(buildOpenAICodexCliBackend());
  },
});

Channel Plugins — defineChannelPluginEntry()

// extensions/telegram/index.ts
import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
import { telegramPlugin } from "./src/channel.js";
import { setTelegramRuntime } from "./src/runtime.js";

export default defineChannelPluginEntry({
  id: "telegram",
  name: "Telegram",
  description: "Telegram channel plugin",
  plugin: telegramPlugin as ChannelPlugin,
  setRuntime: setTelegramRuntime,
});

Package Manifest

// extensions/openai/package.json (relevant fields)
{
  "name": "@openclaw/openai-provider",
  "version": "2026.4.1-beta.1",
  "private": true,
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"]
  }
}

Registration API

The OpenClawPluginApi object passed to register(api) exposes 20+ registration methods. Each method adds a capability to the core registry:

Configuration Reference

Deep-Dive Focus Pages

Directory Map

extensions/
├── shared/                        ← Common utilities (runtime, deferred, config helpers)
├── openai/                        ← OpenAI provider (chat, image, speech, media)
├── anthropic/                     ← Anthropic Claude provider
├── google/                        ← Google Gemini provider
├── ollama/                        ← Local Ollama server provider
├── mistral/                       ← Mistral AI provider
├── deepseek/                      ← DeepSeek reasoning provider
├── groq/                          ← Groq fast inference provider
├── xai/                           ← xAI Grok provider
├── together/                      ← Together AI provider
├── nvidia/                        ← NVIDIA NIM provider
├── amazon-bedrock/                ← AWS Bedrock multi-provider
├── telegram/                      ← Telegram channel plugin
├── discord/                       ← Discord channel plugin
├── slack/                         ← Slack channel plugin
├── whatsapp/                      ← WhatsApp channel plugin
├── signal/                        ← Signal channel plugin
├── matrix/                        ← Matrix channel plugin
├── brave/                         ← Brave Search integration
├── duckduckgo/                    ← DuckDuckGo search
├── elevenlabs/                    ← ElevenLabs TTS
├── deepgram/                      ← Deepgram STT
├── browser/                       ← Headless browser tool
├── memory-core/                   ← Memory abstraction layer
├── memory-lancedb/                ← LanceDB vector memory
├── diagnostics-otel/              ← OpenTelemetry instrumentation
├── speech-core/                   ← Speech provider abstraction
├── image-generation-core/         ← Image generation abstraction
├── media-understanding-core/      ← Media analysis abstraction
└── AGENTS.md                      ← Extension boundary rules & contracts