<!-- source: https://deepwiki.com/openclaw/openclaw/5.3-plugin-examples -->

# Plugin Examples

- apps/ios/Sources/Design/TalkProTab.swift
- docs/install/migrating-hermes.md
- extensions/bonjour/manifest.test.ts
- extensions/codex/src/migration/auth.ts
- extensions/matrix/src/matrix/monitor/inbound-dedupe.test.ts
- extensions/migrate-hermes/auth-config.ts
- extensions/migrate-hermes/auth.ts
- extensions/migrate-hermes/items.ts
- extensions/migrate-hermes/secrets.test.ts
- extensions/migrate-hermes/secrets.ts
- extensions/migrate-hermes/source.ts
- extensions/openai/auth-choice-copy.ts
- extensions/openai/openclaw.plugin.json
- extensions/openai/openclaw.plugin.test.ts
- extensions/openai/provider-contract-api.ts
- extensions/openai/realtime-provider-shared.ts
- extensions/openai/realtime-voice-provider.test.ts
- extensions/openai/realtime-voice-provider.ts
- extensions/openai/setup-api.test.ts
- extensions/openai/setup-api.ts
- extensions/openrouter/music-generation-provider.test.ts
- extensions/openrouter/music-generation-provider.ts
- extensions/telegram/src/bot-handlers.runtime.ts
- extensions/telegram/src/bot.test.ts
- extensions/telegram/src/channel.message-adapter.test.ts
- extensions/telegram/src/message-cache.test.ts
- extensions/telegram/src/message-cache.ts
- extensions/telegram/src/model-buttons.test.ts
- extensions/telegram/src/model-buttons.ts
- extensions/telegram/src/outbound-message-context.ts
- extensions/telegram/src/outbound-params.test.ts
- extensions/telegram/src/outbound-params.ts
- extensions/whatsapp/src/inbound.media.test.ts
- src/plugin-sdk/provider-auth.test.ts
- src/plugin-sdk/provider-auth.ts
- src/plugin-sdk/test-helpers/provider-runtime-contract.ts
- src/plugins/activation-planner.test.ts
- src/plugins/plugin-registry.test.ts
- src/plugins/web-provider-resolution-candidates.test.ts
- src/talk/provider-types.ts

This page demonstrates how to implement OpenClaw plugins through concrete examples from the codebase. It walks through provider registration, authentication flows (including OAuth and API keys), and specialized implementations like Realtime Voice and Music Generation.

For broader architectural context and the plugin registration API, see **5.1 Plugin Architecture**. For skills and `SKILL.md` format, see **5.2 Skills System**.

## Plugin Structure Overview

OpenClaw plugins are discovered by scanning for entry points that utilize `register(api)`. Every native OpenClaw plugin must ship an `openclaw.plugin.json` manifest file in its root directory [extensions/openai/openclaw.plugin.json1-5](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openai/openclaw.plugin.json#L1-L5) This manifest allows the Gateway to validate configuration and discover capabilities without executing plugin code.

### Core Plugin Registration

The system uses a `PluginRegistry` to manage the lifecycle of providers, tools, and hooks once they are activated in the runtime.

**Diagram: Plugin Discovery and Provider Registration**

```

```

Sources: `src/plugins/loader.ts` (referenced in architectural context), [extensions/openai/openclaw.plugin.json1-10](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openai/openclaw.plugin.json#L1-L10) [src/plugin-sdk/provider-auth.ts1-10](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugin-sdk/provider-auth.ts#L1-L10)

## Authentication & Provider Registration

OpenClaw uses a normalized `provider-auth` SDK to handle various credential types, including API keys and OAuth tokens.

### OpenAI Provider Example

The OpenAI plugin demonstrates a multi-modal provider that supports standard chat completions, realtime voice, and account setup via a wizard [extensions/openai/openclaw.plugin.test.ts66-79](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openai/openclaw.plugin.test.ts#L66-L79)

- API Key Resolution : The SDK provides resolveProviderAuthProfileApiKey to look up credentials in the auth-profiles.json store src/plugin-sdk/provider-auth.ts 11-19
- Wizard Integration : Authentication methods can define a wizard object in their registration to provide metadata for the Control UI's onboarding forms extensions/openai/openclaw.plugin.test.ts 81-92
- External CLI Discovery : Some providers (like OpenAI or Anthropic) can opt-in to discovering credentials from local CLI tools (e.g., gh or claude CLI) src/plugin-sdk/provider-auth.ts 11-12

**Diagram: Provider Authentication Resolution**

```

```

Sources: [src/plugin-sdk/provider-auth.ts11-19](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugin-sdk/provider-auth.ts#L11-L19) [src/plugin-sdk/provider-auth.ts61-69](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugin-sdk/provider-auth.ts#L61-L69) [extensions/openai/openclaw.plugin.test.ts164-172](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openai/openclaw.plugin.test.ts#L164-L172)

## Specialized Provider Implementations

### Realtime Voice: OpenAI

The OpenAI plugin implements a `RealtimeVoiceProviderPlugin` which manages low-latency WebSocket connections for audio streaming [extensions/openai/realtime-voice-provider.ts20-24](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openai/realtime-voice-provider.ts#L20-L24)

- WebSocket Management : It uses the ws library to connect to endpoints like wss://api.openai.com/v1/realtime extensions/openai/realtime-voice-provider.ts 33-34
- Barge-in Handling : The implementation includes logic to detect and handle user interruptions via interruptResponseOnInputAudio extensions/openai/realtime-voice-provider.ts 218-222
- Audio Formats : It supports multiple formats such as PCM16 (24kHz) and G711_ULAW (8kHz) extensions/openai/realtime-voice-provider.ts 194-201

Sources: [extensions/openai/realtime-voice-provider.ts87-94](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openai/realtime-voice-provider.ts#L87-L94) [extensions/openai/realtime-voice-provider.ts153-176](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openai/realtime-voice-provider.ts#L153-L176) [extensions/openai/realtime-voice-provider.test.ts229-234](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openai/realtime-voice-provider.test.ts#L229-L234)

### Music Generation: OpenRouter

The OpenRouter plugin demonstrates a `MusicGenerationProvider` that handles Server-Sent Events (SSE) to stream generated audio [extensions/openrouter/music-generation-provider.ts1-5](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openrouter/music-generation-provider.ts#L1-L5)

- Multimodal Inputs : The provider can accept inputImages as reference content for the music generation prompt extensions/openrouter/music-generation-provider.ts 80-85
- SSE Processing : The processOpenRouterSseLine function parses data: [DONE] and audio chunks from the stream extensions/openrouter/music-generation-provider.ts 113-135
- Buffer Recomposition : It independently decodes base64 chunks and concatenates them into a final audio buffer extensions/openrouter/music-generation-provider.ts 178-185

Sources: [extensions/openrouter/music-generation-provider.ts59-72](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openrouter/music-generation-provider.ts#L59-L72) [extensions/openrouter/music-generation-provider.ts169-185](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openrouter/music-generation-provider.ts#L169-L185) [extensions/openrouter/music-generation-provider.test.ts89-129](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openrouter/music-generation-provider.test.ts#L89-L129)

## Channel Implementation: Telegram

The Telegram plugin illustrates how a messaging channel integrates with the agent runtime, handling message caching and interactive UI elements.

- Message Cache : Telegram uses a persistent cache to reconstruct reply chains and provide context to the agent extensions/telegram/src/message-cache.ts 30-57
- Interactive Menus : It implements dynamic keyboards for model selection and provider switching extensions/telegram/src/model-buttons.ts 136-144
- Inbound Debouncing : To prevent message flooding, the plugin utilizes createInboundDebouncer to group rapid-fire messages into a single agent turn extensions/telegram/src/bot-handlers.runtime.ts 11-14

**Diagram: Telegram Inbound Message Flow**

```

```

Sources: [extensions/telegram/src/bot-handlers.runtime.ts148-167](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/telegram/src/bot-handlers.runtime.ts#L148-L167) [extensions/telegram/src/message-cache.ts7-15](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/telegram/src/message-cache.ts#L7-L15) [extensions/telegram/src/message-cache.test.ts73-106](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/telegram/src/message-cache.test.ts#L73-L106)

## Summary: Implementation Checklist

Sources: [extensions/openai/openclaw.plugin.json1-11](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openai/openclaw.plugin.json#L1-L11) [src/plugin-sdk/provider-auth.ts82-90](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugin-sdk/provider-auth.ts#L82-L90) [extensions/openai/realtime-voice-provider.ts217-228](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openai/realtime-voice-provider.ts#L217-L228) [extensions/telegram/src/bot-handlers.runtime.ts34-41](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/telegram/src/bot-handlers.runtime.ts#L34-L41)
