Channels

Channel plugins integrate messaging platforms with OpenClaw. A channel plugin implements adapters for message handling, authentication, status checks, and more.

Channel Structure

A channel plugin implements the ChannelPlugin interface:

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

const myChannelPlugin: ChannelPlugin = {
  id: "my-channel",
  meta: {
    id: "my-channel",
    label: "My Channel",
    selectionLabel: "My Channel (plugin)",
    docsPath: "/channels/my-channel",
    docsLabel: "my-channel",
    blurb: "Custom messaging platform",
    order: 100
  },
  capabilities: {
    supportsDm: true,
    supportsGroup: true,
    supportsPolling: false
  },
  config: {
    /* Config adapter */
  },
  gateway: {
    /* Gateway adapter */
  },
  outbound: {
    /* Outbound adapter */
  },
  status: {
    /* Status adapter */
  }
};

Registering Channels

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

const plugin = {
  id: "my-channel",
  name: "My Channel",
  description: "Custom channel plugin",
  configSchema: emptyPluginConfigSchema(),
  register(api: OpenClawPluginApi) {
    api.registerChannel({ plugin: myChannelPlugin });
  }
};

export default plugin;

Core Adapters

Config Adapter

The config adapter manages channel configuration and accounts:

config: {
  resolveAccount: (config, accountId) => {
    // Return resolved account or null
    const section = config.channels?.myChannel;
    if (!section?.enabled) return null;
    
    return {
      accountId: accountId ?? "default",
      config,
      apiKey: section.apiKey,
      serverUrl: section.serverUrl
    };
  },
  
  listAccounts: (config) => {
    // Return list of account IDs
    const section = config.channels?.myChannel;
    return section?.enabled ? ["default"] : [];
  }
}

Gateway Adapter

The gateway adapter handles incoming messages:

gateway: {
  start: async ({ account, logger }) => {
    // Connect to messaging platform
    const client = new MyChannelClient(account.apiKey);
    
    client.on("message", async (message) => {
      // Process incoming message
      logger.info(`Received message: ${message.text}`);
      
      // Dispatch to agent
      await handleInboundMessage({
        channelId: "my-channel",
        from: message.senderId,
        to: message.recipientId,
        text: message.text,
        accountId: account.accountId
      });
    });
    
    await client.connect();
    
    return client;
  },
  
  stop: async (client) => {
    await client.disconnect();
  }
}

Outbound Adapter

The outbound adapter sends messages:

outbound: {
  send: async ({ account, to, payload }) => {
    const client = new MyChannelClient(account.apiKey);
    
    if (payload.kind === "text") {
      await client.sendMessage(to, payload.text);
      return { ok: true };
    }
    
    return { ok: false, error: "Unsupported payload kind" };
  }
}

Status Adapter

The status adapter provides connection status:

status: {
  describe: async ({ account }) => {
    const client = new MyChannelClient(account.apiKey);
    const isConnected = await client.ping();
    
    return {
      summary: isConnected ? "connected" : "disconnected",
      issues: isConnected ? [] : [
        { severity: "error", message: "Not connected" }
      ]
    };
  }
}

Advanced Adapters

Authentication Adapter

Handle login flows:

auth: {
  loginWithQr: {
    start: async ({ account }) => {
      // Generate QR code URL
      const { qrUrl, sessionId } = await generateQr();
      return { qrUrl, sessionId };
    },
    wait: async ({ sessionId }) => {
      // Poll for authentication
      const auth = await pollAuth(sessionId);
      return {
        ok: auth.success,
        creds: auth.credentials
      };
    }
  }
}

Pairing Adapter

Manage device pairing:

pairing: {
  idLabel: "userId",
  normalizeAllowEntry: (entry) => entry.toLowerCase(),
  
  list: async ({ account }) => {
    // Return pending pairing requests
    const requests = await fetchPairingRequests(account);
    return requests.map(r => ({
      id: r.id,
      sender: r.userId,
      timestamp: r.timestamp
    }));
  },
  
  approve: async ({ account, id }) => {
    await approvePairing(account, id);
    return { ok: true };
  },
  
  reject: async ({ account, id }) => {
    await rejectPairing(account, id);
    return { ok: true };
  }
}

Groups Adapter

Manage group chats:

groups: {
  leave: async ({ account, groupId }) => {
    await leaveGroup(account, groupId);
    return { ok: true };
  },
  
  listMembers: async ({ account, groupId }) => {
    const members = await fetchGroupMembers(account, groupId);
    return members.map(m => m.userId);
  }
}

Mentions Adapter

Handle @mentions in groups:

mentions: {
  buildMentionText: ({ botName, mentionMode }) => {
    if (mentionMode === "at") return `@${botName}`;
    return botName;
  },
  
  normalizeText: (text) => {
    // Strip mention markers
    return text.replace(/@[\w]+/g, "").trim();
  }
}

Directory Adapter

List users and groups:

directory: {
  listPeers: async ({ account }) => {
    const users = await fetchUsers(account);
    return users.map(u => ({
      kind: "peer" as const,
      id: u.id,
      name: u.displayName
    }));
  },
  
  listGroups: async ({ account }) => {
    const groups = await fetchGroups(account);
    return groups.map(g => ({
      kind: "group" as const,
      id: g.id,
      name: g.name
    }));
  }
}

Example: Matrix Channel Plugin

The Matrix channel plugin demonstrates a complete implementation:

import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
import { matrixPlugin } from "./src/channel.js";
import { setMatrixRuntime } from "./src/runtime.js";

const plugin = {
  id: "matrix",
  name: "Matrix",
  description: "Matrix channel plugin (matrix-js-sdk)",
  configSchema: emptyPluginConfigSchema(),
  register(api: OpenClawPluginApi) {
    setMatrixRuntime(api.runtime);
    api.registerChannel({ plugin: matrixPlugin });
  }
};

export default plugin;

See the full source for details.

Message Handling

Channel plugins handle inbound messages by dispatching to the routing system:

import { recordInboundSession } from "openclaw/plugin-sdk";

gateway: {
  start: async ({ account, config, logger }) => {
    client.on("message", async (msg) => {
      // Record session
      const sessionKey = recordInboundSession({
        config,
        channelId: "my-channel",
        accountId: account.accountId,
        from: msg.senderId,
        to: msg.recipientId
      });
      
      // Dispatch to agent
      await dispatchToAgent({
        sessionKey,
        text: msg.text,
        // ...
      });
    });
  }
}

Outbound Message Types

Handle different payload types:

outbound: {
  send: async ({ account, to, payload }) => {
    if (payload.kind === "text") {
      await sendText(account, to, payload.text);
      return { ok: true };
    }
    
    if (payload.kind === "image") {
      await sendImage(account, to, payload.imagePath, payload.caption);
      return { ok: true };
    }
    
    if (payload.kind === "file") {
      await sendFile(account, to, payload.filePath, payload.caption);
      return { ok: true };
    }
    
    return { ok: false, error: `Unsupported payload kind: ${payload.kind}` };
  }
}

Configuration Schema

Define configuration with Zod:

import { z } from "zod";
import { buildChannelConfigSchema } from "openclaw/plugin-sdk";

const MyChannelConfigSchema = z.object({
  enabled: z.boolean().default(false),
  apiKey: z.string(),
  serverUrl: z.string().url(),
  accounts: z.array(
    z.object({
      id: z.string(),
      apiKey: z.string()
    })
  ).optional()
});

const configSchema = buildChannelConfigSchema(MyChannelConfigSchema, {
  apiKey: { sensitive: true, label: "API Key" },
  serverUrl: { label: "Server URL", placeholder: "https://api.example.com" }
});

Runtime Services

Channel plugins can use runtime services:

import { setMyChannelRuntime } from "./runtime.js";

const plugin = {
  register(api: OpenClawPluginApi) {
    // Store runtime for use in channel adapter
    setMyChannelRuntime(api.runtime);
    
    api.registerChannel({ plugin: myChannelPlugin });
  }
};

Then use in channel code:

import { getMyChannelRuntime } from "./runtime.js";

const runtime = getMyChannelRuntime();
const media = await runtime.media.loadWebMedia(url);
const logger = runtime.logging.getChildLogger({ channel: "my-channel" });

Best Practices

1. Error Handling

Handle connection errors gracefully:

gateway: {
  start: async ({ account, logger }) => {
    try {
      const client = await connect(account);
      return client;
    } catch (err) {
      logger.error(`Connection failed: ${err}`);
      throw err;
    }
  }
}

2. Reconnection Logic

Implement automatic reconnection:

gateway: {
  start: async ({ account, logger }) => {
    const client = new Client();
    
    client.on("disconnect", async () => {
      logger.warn("Disconnected, reconnecting...");
      await client.reconnect();
    });
    
    await client.connect();
    return client;
  }
}

3. Rate Limiting

Respect platform rate limits:

import { sleep } from "openclaw/plugin-sdk";

outbound: {
  send: async ({ account, to, payload }) => {
    await rateLimiter.acquire();
    await sendMessage(to, payload.text);
    await sleep(100); // Throttle
    return { ok: true };
  }
}

4. Status Checks

Provide detailed status information:

status: {
  describe: async ({ account }) => {
    const issues = [];
    
    if (!account.apiKey) {
      issues.push({ severity: "error", message: "Missing API key" });
    }
    
    const connected = await checkConnection(account);
    if (!connected) {
      issues.push({ severity: "error", message: "Not connected" });
    }
    
    return {
      summary: issues.length === 0 ? "connected" : "error",
      issues
    };
  }
}

Example Channels

Explore these built-in channel plugins:

Matrix - extensions/matrix - Matrix protocol integration
Microsoft Teams - extensions/msteams - Bot Framework integration
IRC - extensions/irc - IRC protocol
Mattermost - extensions/mattermost - Mattermost API
Nextcloud Talk - extensions/nextcloud-talk - Nextcloud integration

See the extensions directory for complete implementations.

Next Steps

Examples - Complete channel plugin examples
Publishing - Publish your plugin to npm
Built-in Extensions - Explore existing plugins

Overview

SDK Reference

Extensions

Channel Structure

Registering Channels

Core Adapters

Config Adapter

Gateway Adapter

Outbound Adapter

Status Adapter

Advanced Adapters

Authentication Adapter

Pairing Adapter

Groups Adapter

Mentions Adapter

Directory Adapter

Example: Matrix Channel Plugin

Message Handling

Outbound Message Types

Configuration Schema

Runtime Services

Best Practices

1. Error Handling

2. Reconnection Logic

3. Rate Limiting

4. Status Checks

Example Channels

Next Steps

Overview

SDK Reference

Extensions

Documentation Index

​Channel Structure

​Registering Channels

​Core Adapters

​Config Adapter

​Gateway Adapter

​Outbound Adapter

​Status Adapter

​Advanced Adapters

​Authentication Adapter

​Pairing Adapter

​Groups Adapter

​Mentions Adapter

​Directory Adapter

​Example: Matrix Channel Plugin

​Message Handling

​Outbound Message Types

​Configuration Schema

​Runtime Services

​Best Practices

​1. Error Handling

​2. Reconnection Logic

​3. Rate Limiting

​4. Status Checks

​Example Channels

​Next Steps

Channel Structure

Registering Channels

Core Adapters

Config Adapter

Gateway Adapter

Outbound Adapter

Status Adapter

Advanced Adapters

Authentication Adapter

Pairing Adapter

Groups Adapter

Mentions Adapter

Directory Adapter

Example: Matrix Channel Plugin

Message Handling

Outbound Message Types

Configuration Schema

Runtime Services

Best Practices

1. Error Handling

2. Reconnection Logic

3. Rate Limiting

4. Status Checks

Example Channels

Next Steps