Channel Integration Patterns 🟡

OpenClaw supports 20+ messaging platforms. Each platform has a different API, but they all follow the same integration pattern. This chapter uses the Telegram channel plugin as an example.

I. Channel Plugin Structure

Channel plugins implement the ChannelPlugin interface with required and optional adapters:

type ChannelPlugin = {
  id: ChannelId;                        // required
  messaging: ChannelMessagingAdapter;   // required
  outbound?: ChannelOutboundAdapter;    // recommended
  lifecycle?: ChannelLifecycleAdapter;  // recommended
  auth?: ChannelAuthAdapter;            // recommended
  setup?: ChannelSetupAdapter;          // for onboarding
  status?: ChannelStatusAdapter;        // for health checks
  // ... 10+ more optional adapters
};

II. Webhook vs Long Polling

Webhook (recommended): Platform pushes messages to OpenClaw.

// Register webhook route in setup()
api.gateway.registerHttpRoute({
  path: '/webhook/my-channel/:accountId',
  auth: 'none',
  handler: async (req, res, params) => {
    const update = JSON.parse(req.body);
    await handleUpdate(params.accountId, update);
    res.status(200).json({ ok: true });
  },
});

Long Polling: OpenClaw actively polls the platform API (for platforms that don't support webhooks).

Auto-Restart Policy

ChannelManager in server-channels.ts automatically restarts crashed channels with exponential backoff:

const RESTART_POLICY = {
  initialMs: 5_000,   // 5 second initial wait
  maxMs: 300_000,     // max 5 minutes
  factor: 2,          // exponential
  jitter: 0.1,        // 10% random jitter
};

III. Channel Capability Differences

Channel plugins declare capabilities via the capabilities field:

type ChannelCapabilities = {
  streaming?: boolean;
  images?: boolean;
  markdown?: boolean;
  voiceMessages?: boolean;
};

IV. Multi-Account Support

One channel plugin can manage multiple bot accounts:

channels:
  telegram:
    accounts:
      main-bot:
        token: "${env:TELEGRAM_BOT_1_TOKEN}"
      work-bot:
        token: "${env:TELEGRAM_BOT_2_TOKEN}"

V. Health Monitoring

channel-health-monitor.ts periodically validates Bot Tokens:

• Calls ChannelAuthAdapter.checkToken() at configured intervals
• Updates ChannelAccountSnapshot.status
• Alerts via configured alert channel if token becomes invalid

Key Source Files

Summary

1. Minimum viable channel: messaging adapter + openclaw.plugin.json.
2. Webhook over polling: less overhead, faster response times.
3. Auto-restart: exponential backoff with jitter on crashes.
4. Multi-account via accountId: same plugin handles multiple bot accounts.

← Auth System | → Memory & MCP