चैनल Plugin बनाना

​

आपका plugin किन चीज़ों का स्वामी है

• कॉन्फ़िगरेशन - अकाउंट निर्धारण और सेटअप विज़ार्ड
• सुरक्षा - DM नीति और अनुमति-सूचियाँ
• पेयरिंग - DM अनुमोदन प्रवाह
• सेशन व्याकरण - प्रदाता-विशिष्ट वार्तालाप आईडी को आधार चैट, थ्रेड आईडी और पैरेंट फ़ॉलबैक से मैप करने का तरीका
• आउटबाउंड - प्लेटफ़ॉर्म पर टेक्स्ट, मीडिया और पोल भेजना
• थ्रेडिंग - उत्तरों को थ्रेड करने का तरीका
• Heartbeat टाइपिंग - Heartbeat डिलीवरी लक्ष्यों के लिए वैकल्पिक टाइपिंग/व्यस्तता संकेत

​

संदेश अडैप्टर

​

इनबाउंड प्रवेश (प्रयोगात्मक)

​

टिकाऊ प्रवेश और रीप्ले डीडुप्लीकेशन

​

ट्रांसपोर्ट वर्ग और प्रतिधारण

• अभिस्वीकृति-निर्भर Webhook या इवेंट डिलीवरी: केवल टिकाऊ संलग्नता के बाद अभिस्वीकृति दें या सफलता लौटाएँ। संलग्नता विफल होने पर डिलीवरी पुनः प्रयास के योग्य बनी रहनी चाहिए या प्राप्ति सीमा विफल होनी चाहिए। इस वर्ग में Slack, SMS, Zalo, Microsoft Teams, Google Chat, LINE और Synology Chat शामिल हैं।
• प्रतीक्षित पोलिंग या स्ट्रीम डिलीवरी: केवल संलग्नता के बाद रिमोट कर्सर आगे बढ़ाएँ या ट्रांसपोर्ट अभिस्वीकृति भेजें। जब कोई स्पष्ट कर्सर मौजूद न हो, तो प्राप्ति कॉलबैक को क्रमबद्ध और प्रतीक्षित रखें, ताकि संलग्नता विफल होने पर प्राप्ति लूप आगे न बढ़ सके। Telegram पोलिंग, Signal और Tlon इस वर्ग का उपयोग करते हैं; Telegram Webhook डिलीवरी ऊपर दिए अभिस्वीकृति-निर्भर नियम का पालन करती है।
• गैर-रीप्ले सॉकेट: IRC, Mattermost, Twitch और Zalo Personal प्लेटफ़ॉर्म से किसी स्वीकृत इवेंट को फिर से डिलीवर करने के लिए नहीं कह सकते। उनकी टिकाऊ कतार प्रक्रिया क्रैश अवधि की सुरक्षा करती है और स्थानीय पुनरारंभ पुनर्प्राप्ति का समर्थन करती है; पूर्णता टूम्बस्टोन प्लेटफ़ॉर्म रीप्ले के विरुद्ध लगभग निष्क्रिय हैं।

​

कम-से-कम-एक-बार साइड इफ़ेक्ट

​

अकाउंट-स्कोप वाला पुनरारंभ अनुबंध

​

टाइपिंग संकेतक

​

मीडिया स्रोत पैरामीटर

​

नेटिव payload का आकार निर्धारण

​

Session conversation grammar

​

Account-scoped conversation binding support

​

अनुमोदन और channel capabilities

​

अनुमोदन auth

• approvalCapability.authorizeActorAction और approvalCapability.getActionAvailabilityState canonical approval-auth seam हैं।
• same-chat approval auth availability के लिए getActionAvailabilityState का उपयोग करें। native delivery disabled होने पर भी configured approvers को /approve के लिए उपलब्ध रखें; इसके बजाय delivery/setup guidance के लिए native initiating-surface state का उपयोग करें।
• यदि आपका channel native exec approvals प्रदर्शित करता है, तो initiating-surface/native-client state के लिए approvalCapability.getExecInitiatingSurfaceState का उपयोग करें, जब वह same-chat approval auth से अलग हो। core उस exec-specific hook का उपयोग enabled और disabled में अंतर करने, initiating channel द्वारा native exec approvals के support का निर्णय लेने और channel को native-client fallback guidance में शामिल करने के लिए करता है। सामान्य स्थिति में createApproverRestrictedNativeApprovalCapability(...) इसे भरता है।
• यदि कोई channel मौजूदा config से stable owner-like DM identities का अनुमान लगा सकता है, तो approval-specific core logic जोड़े बिना same-chat /approve को सीमित करने के लिए openclaw/plugin-sdk/approval-runtime से createResolvedApproverActionAuthAdapter का उपयोग करें।
• यदि custom approval auth जानबूझकर केवल same-chat fallback की अनुमति देता है, तो openclaw/plugin-sdk/approval-auth-runtime से markImplicitSameChatApprovalAuthorization({ authorized: true }) लौटाएँ; अन्यथा core परिणाम को स्पष्ट approver authorization मानता है।
• यदि channel-owned native callback approvals को सीधे resolve करता है, तो resolve करने से पहले isImplicitSameChatApprovalAuthorization(...) का उपयोग करें, ताकि implicit fallback फिर भी channel के सामान्य actor authorization से होकर जाए।

​

Payload lifecycle और setup guidance

• channel-specific payload lifecycle behavior के लिए outbound.shouldSuppressLocalPayloadPrompt या outbound.beforeDeliverPayload का उपयोग करें, जैसे duplicate local approval prompts छिपाना या delivery से पहले typing indicators भेजना।
• जब channel चाहता है कि disabled-path reply native exec approvals enable करने के लिए आवश्यक सटीक config knobs समझाए, तो approvalCapability.describeExecApprovalSetup का उपयोग करें। hook को { channel, channelLabel, accountId } मिलता है; named-account channels को top-level defaults के बजाय channels.<channel>.accounts.<id>.execApprovals.* जैसे account-scoped paths render करने चाहिए।
• जब plugin approval failure guidance को plugin approval no-route और timeout failures के लिए दिखाना सुरक्षित हो, तो approvalCapability.describePluginApprovalSetup का उपयोग करें। createApproverRestrictedNativeApprovalCapability(...), describeExecApprovalSetup से इसका अनुमान नहीं लगाता; उसी helper को स्पष्ट रूप से केवल तभी पास करें, जब plugin और exec approvals वास्तव में समान native setup का उपयोग करते हों।

​

नेटिव अनुमोदन delivery

• availability - account configured है या नहीं और request को handle किया जाना चाहिए या नहीं
• presentation - shared approval view model को pending/resolved/expired native payloads या final actions में map करें
• transport - targets तैयार करें तथा native approval messages send/update/delete करें
• interactions - native buttons या reactions के लिए वैकल्पिक bind/unbind/clear-action hooks, साथ ही वैकल्पिक cancelDelivered hook। जब deliverPending in-process या persistent state (जैसे reaction target store) register करता है, तो cancelDelivered implement करें, ताकि handler stop द्वारा bindPending चलने से पहले delivery cancel करने पर, या bindPending द्वारा कोई handle न लौटाए जाने पर, उस state को release किया जा सके
• observe - वैकल्पिक delivery diagnostics hooks

• जब कोई channel session-origin native delivery और explicit approval forwarding targets दोनों का समर्थन करता है, तो openclaw/plugin-sdk/approval-native-runtime से createNativeApprovalChannelRouteGates का उपयोग करें। helper approval config selection, mode handling, agent/session filters, account binding, session-target matching और target-list matching को centralize करता है, जबकि callers अभी भी channel id, default forwarding mode, account lookup, transport-enabled check, target normalization और turn-source target resolution के स्वामी रहते हैं। core-owned channel policy defaults बनाने के लिए इसका उपयोग न करें; channel के documented default mode को स्पष्ट रूप से पास करें।
• createChannelNativeOriginTargetResolver, { to, accountId, threadId } targets के लिए default रूप से shared channel-route matcher का उपयोग करता है। targetsMatch केवल तब पास करें, जब किसी channel के पास provider-specific equivalence rules हों, जैसे Slack timestamp prefix matching। जब default route matcher या custom targetsMatch callback चलने से पहले channel को provider ids canonicalize करने की आवश्यकता हो, तब original target को delivery के लिए संरक्षित रखते हुए normalizeTargetForMatch पास करें। normalizeTarget का उपयोग केवल तब करें, जब resolved delivery target को ही canonicalize किया जाना चाहिए।
• यदि channel को client, token, Bolt app या webhook receiver जैसे runtime-owned objects चाहिए, तो उन्हें openclaw/plugin-sdk/channel-runtime-context के माध्यम से register करें। generic runtime-context registry core को approval-specific wrapper glue जोड़े बिना channel startup state से capability-driven handlers bootstrap करने देता है।
• lower-level createChannelApprovalHandler या createChannelNativeApprovalRuntime का उपयोग केवल तब करें, जब capability-driven seam अभी पर्याप्त रूप से expressive न हो।
• native approval channels को accountId और approvalKind दोनों को उन helpers के माध्यम से route करना आवश्यक है। accountId multi-account approval policy को सही bot account तक scoped रखता है, और approvalKind exec बनाम plugin approval behavior को core में hardcoded branches के बिना channel के लिए उपलब्ध रखता है।
• core approval reroute notices का भी स्वामी है। channel plugins को createChannelNativeApprovalRuntime से अपने “approval DMs / किसी अन्य channel पर गया” follow-up messages नहीं भेजने चाहिए; इसके बजाय shared approval capability helpers के माध्यम से accurate origin + approver-DM routing प्रदर्शित करें और initiating chat पर कोई notice वापस post करने से पहले core को actual deliveries aggregate करने दें।
• delivered approval id kind को शुरू से अंत तक संरक्षित रखें। native clients को channel-local state से exec बनाम plugin approval routing का अनुमान नहीं लगाना या उसे rewrite नहीं करना चाहिए।
• उस explicit approvalKind को resolveApprovalOverGateway में पास करें। यह canonical approval.resolve service का उपयोग करता है और किसी अन्य surface द्वारा पहले उत्तर दिए जाने पर recorded winner लौटाता है। पुराना explicit resolveMethod input command-backed controls के लिए बना हुआ है; नए native actions को इसका उपयोग नहीं करना चाहिए या ID से kind का अनुमान नहीं लगाना चाहिए।
• अलग-अलग approval kinds जानबूझकर अलग native surfaces प्रदर्शित कर सकते हैं। वर्तमान bundled examples: Matrix exec और plugin approvals के लिए समान native DM/channel routing और reaction UX बनाए रखता है, जबकि auth को approval kind के अनुसार अलग होने देता है; Slack exec और plugin ids दोनों के लिए native approval routing उपलब्ध रखता है।
• createApproverRestrictedNativeApprovalAdapter अब भी compatibility wrapper के रूप में मौजूद है, लेकिन नए code को capability builder को प्राथमिकता देनी चाहिए और plugin पर approvalCapability प्रदर्शित करना चाहिए।

​

अधिक सीमित approval runtime subpaths

• openclaw/plugin-sdk/approval-auth-runtime
• openclaw/plugin-sdk/approval-client-runtime
• openclaw/plugin-sdk/approval-delivery-runtime
• openclaw/plugin-sdk/approval-gateway-runtime
• openclaw/plugin-sdk/approval-reference-runtime
• openclaw/plugin-sdk/approval-handler-adapter-runtime
• openclaw/plugin-sdk/approval-handler-runtime
• openclaw/plugin-sdk/approval-native-runtime
• openclaw/plugin-sdk/approval-reply-runtime
• openclaw/plugin-sdk/channel-runtime-context

​

सेटअप उपपथ

• openclaw/plugin-sdk/setup-runtime रनटाइम-सुरक्षित सेटअप सहायकों को समेटता है: createSetupTranslator, आयात-सुरक्षित सेटअप पैच अडैप्टर (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), लुकअप-नोट आउटपुट, promptResolvedAllowFrom, splitSetupEntries, और प्रत्यायोजित सेटअप-प्रॉक्सी बिल्डर।
• openclaw/plugin-sdk/channel-setup वैकल्पिक-इंस्टॉल सेटअप बिल्डरों के साथ कुछ सेटअप-सुरक्षित प्रिमिटिव को समेटता है: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled, और splitSetupEntries।
• व्यापक openclaw/plugin-sdk/setup सीम का उपयोग केवल तभी करें, जब आपको moveSingleAccountChannelSectionToDefaultAccount(...) जैसे अधिक भारी साझा सेटअप/कॉन्फ़िग सहायक भी चाहिए।

​

अन्य सीमित चैनल उपपथ

• बहु-खाता कॉन्फ़िग और डिफ़ॉल्ट-खाता फ़ॉलबैक के लिए openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution, और openclaw/plugin-sdk/account-helpers
• इनबाउंड रूट/एनवेलप और रिकॉर्ड-एंड-डिस्पैच वायरिंग के लिए openclaw/plugin-sdk/inbound-envelope और openclaw/plugin-sdk/channel-inbound
• लक्ष्य पार्सिंग सहायकों के लिए openclaw/plugin-sdk/channel-targets
• आउटबाउंड पहचान/प्रेषण डेलिगेट और टाइपयुक्त पेलोड योजना के लिए openclaw/plugin-sdk/channel-outbound
• जब किसी आउटबाउंड रूट को स्पष्ट replyToId/threadId संरक्षित करना चाहिए या आधार सेशन कुंजी के अब भी मेल खाने पर वर्तमान :thread: सेशन पुनर्प्राप्त करना चाहिए, तब openclaw/plugin-sdk/channel-core से buildThreadAwareOutboundSessionRoute(...)। जब उनके प्लेटफ़ॉर्म में नेटिव थ्रेड डिलीवरी अर्थविज्ञान हो, तो प्रदाता Plugin वरीयता, प्रत्यय व्यवहार और थ्रेड आईडी सामान्यीकरण को ओवरराइड कर सकते हैं।
• थ्रेड-बाइंडिंग जीवनचक्र और अडैप्टर पंजीकरण के लिए openclaw/plugin-sdk/thread-bindings-runtime

​

इनबाउंड उल्लेख नीति

• Plugin-स्वामित्व वाला साक्ष्य संग्रह
• साझा नीति मूल्यांकन

• बॉट को उत्तर देने की पहचान
• उद्धृत बॉट की पहचान
• थ्रेड सहभागिता जाँच
• सेवा/सिस्टम-संदेश अपवर्जन
• बॉट की सहभागिता सिद्ध करने के लिए आवश्यक प्लेटफ़ॉर्म-नेटिव कैश

• requireMention
• स्पष्ट उल्लेख परिणाम
• अंतर्निहित उल्लेख अनुमति-सूची
• कमांड बायपास
• अंतिम छोड़ने का निर्णय

1. स्थानीय उल्लेख तथ्य परिकलित करें।
2. उन तथ्यों को resolveInboundMentionDecision({ facts, policy }) में भेजें।
3. अपने इनबाउंड गेट में decision.effectiveWasMentioned, decision.shouldBypassMention, और decision.shouldSkip का उपयोग करें।

import {
  implicitMentionKindWhen,
  matchesMentionWithExplicit,
  resolveInboundMentionDecision,
} from "openclaw/plugin-sdk/channel-inbound";
import { resolveChannelImplicitMentions } from "openclaw/plugin-sdk/channel-ingress-runtime";

const wasMentioned = matchesMentionWithExplicit({
  text,
  mentionRegexes,
  explicit: {
    hasAnyMention,
    isExplicitlyMentioned,
    canResolveExplicit,
  },
});

const facts = {
  canDetectMention: true,
  wasMentioned,
  hasAnyMention,
  implicitMentionKinds: [
    ...implicitMentionKindWhen("reply_to_bot", isReplyToBot),
    ...implicitMentionKindWhen("quoted_bot", isQuoteOfBot),
  ],
};

const implicitMentions = resolveChannelImplicitMentions({
  cfg,
  channel: channelId,
  accountId,
});

const decision = resolveInboundMentionDecision({
  facts,
  policy: {
    isGroup,
    requireMention,
    implicitMentions,
    allowTextCommands,
    hasControlCommand,
    commandAuthorized,
  },
});

if (decision.shouldSkip) return;

​

चरण-दर-चरण मार्गदर्शिका

{
  "name": "@myorg/openclaw-acme-chat",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "channel": {
      "id": "acme-chat",
      "label": "Acme Chat",
      "blurb": "OpenClaw को Acme Chat से कनेक्ट करें।"
    }
  }
}

{
  "id": "acme-chat",
  "channels": ["acme-chat"],
  "name": "Acme Chat",
  "description": "Acme Chat चैनल Plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  },
  "channelConfigs": {
    "acme-chat": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "token": { "type": "string" },
          "allowFrom": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      },
      "uiHints": {
        "token": {
          "label": "बॉट टोकन",
          "sensitive": true
        }
      }
    }
  }
}

import {
  createChatChannelPlugin,
  createChannelPluginBase,
} from "openclaw/plugin-sdk/channel-core";
import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
import { acmeChatApi } from "./client.js"; // your platform API client

type ResolvedAccount = {
  accountId: string | null;
  token: string;
  allowFrom: string[];
  dmPolicy: string | undefined;
};

function resolveAccount(
  cfg: OpenClawConfig,
  accountId?: string | null,
): ResolvedAccount {
  const section = (cfg.channels as Record<string, any>)?.["acme-chat"];
  const token = section?.token;
  if (!token) throw new Error("acme-chat: token is required");
  return {
    accountId: accountId ?? null,
    token,
    allowFrom: section?.allowFrom ?? [],
    dmPolicy: section?.dmSecurity,
  };
}

export const acmeChatPlugin = createChatChannelPlugin<ResolvedAccount>({
  base: createChannelPluginBase({
    id: "acme-chat",
    // Account resolution/inspection belongs on `config`, not `setup`.
    // `setup` covers onboarding writes (applyAccountConfig, validateInput).
    config: {
      listAccountIds: () => ["default"],
      resolveAccount,
      inspectAccount(cfg, accountId) {
        const section =
          (cfg.channels as Record<string, any>)?.["acme-chat"];
        return {
          enabled: Boolean(section?.token),
          configured: Boolean(section?.token),
          tokenStatus: section?.token ? "available" : "missing",
        };
      },
    },
    setup: {
      applyAccountConfig: ({ cfg, input }) => ({
        ...cfg,
        channels: {
          ...cfg.channels,
          "acme-chat": { ...(cfg.channels as any)?.["acme-chat"], ...input },
        },
      }),
    },
  }),

  // DM security: who can message the bot
  security: {
    dm: {
      channelKey: "acme-chat",
      resolvePolicy: (account) => account.dmPolicy,
      resolveAllowFrom: (account) => account.allowFrom,
      defaultPolicy: "allowlist",
    },
  },

  // Pairing: approval flow for new DM contacts
  pairing: {
    text: {
      idLabel: "Acme Chat username",
      message: "Send this code to verify your identity:",
      notify: async ({ target, code }) => {
        await acmeChatApi.sendDm(target, `Pairing code: ${code}`);
      },
    },
  },

  // Threading: how replies are delivered
  threading: { topLevelReplyToMode: "reply" },

  // Outbound: send messages to the platform
  outbound: {
    attachedResults: {
      channel: "acme-chat",
      sendText: async (params) => {
        const result = await acmeChatApi.sendMessage(
          params.to,
          params.text,
        );
        return { messageId: result.id };
      },
    },
    base: {
      sendMedia: async (params) => {
        await acmeChatApi.sendFile(params.to, params.filePath);
      },
    },
  },
});

import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { acmeChatPlugin } from "./src/channel.js";

export default defineChannelPluginEntry({
  id: "acme-chat",
  name: "Acme Chat",
  description: "Acme Chat channel plugin",
  plugin: acmeChatPlugin,
  registerCliMetadata(api) {
    api.registerCli(
      ({ program }) => {
        program
          .command("acme-chat")
          .description("Acme Chat management");
      },
      {
        descriptors: [
          {
            name: "acme-chat",
            description: "Acme Chat management",
            hasSubcommands: false,
          },
        ],
      },
    );
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { acmeChatPlugin } from "./src/channel.js";

export default defineSetupPluginEntry(acmeChatPlugin);

registerFull(api) {
  api.registerHttpRoute({
    path: "/acme-chat/webhook",
    auth: "plugin", // Plugin द्वारा प्रबंधित प्रमाणीकरण (हस्ताक्षर स्वयं सत्यापित करें)
    handler: async (req, res) => {
      const event = parseWebhookPayload(req);

      // आपका इनबाउंड हैंडलर संदेश को OpenClaw में डिस्पैच करता है।
      // सटीक वायरिंग आपके प्लेटफ़ॉर्म SDK पर निर्भर करती है -
      // बंडल किए गए Microsoft Teams या Google Chat Plugin पैकेज में वास्तविक उदाहरण देखें।
      await handleAcmeChatInbound(api, event);

      res.statusCode = 200;
      res.end("ok");
      return true;
    },
  });
}

import { describe, it, expect } from "vitest";
import { acmeChatPlugin } from "./channel.js";

describe("acme-chat Plugin", () => {
  it("कॉन्फ़िगरेशन से खाता निर्धारित करता है", () => {
    const cfg = {
      channels: {
        "acme-chat": { token: "test-token", allowFrom: ["user1"] },
      },
    } as any;
    const account = acmeChatPlugin.config.resolveAccount(cfg, undefined);
    expect(account.token).toBe("test-token");
  });

  it("सीक्रेट्स को वास्तविक रूप दिए बिना खाते का निरीक्षण करता है", () => {
    const cfg = {
      channels: { "acme-chat": { token: "test-token" } },
    } as any;
    const result = acmeChatPlugin.config.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(true);
    expect(result.tokenStatus).toBe("available");
  });

  it("अनुपस्थित कॉन्फ़िगरेशन की रिपोर्ट करता है", () => {
    const cfg = { channels: {} } as any;
    const result = acmeChatPlugin.config.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(false);
  });
});

pnpm test <bundled-plugin-root>/acme-chat/

​

फ़ाइल संरचना

<bundled-plugin-root>/acme-chat/
├── package.json              # openclaw.channel मेटाडेटा
├── openclaw.plugin.json      # कॉन्फ़िगरेशन स्कीमा सहित मैनिफ़ेस्ट
├── index.ts                  # defineChannelPluginEntry
├── setup-entry.ts            # defineSetupPluginEntry
├── api.ts                    # सार्वजनिक एक्सपोर्ट (वैकल्पिक)
├── runtime-api.ts            # आंतरिक रनटाइम एक्सपोर्ट (वैकल्पिक)
└── src/
    ├── channel.ts            # createChatChannelPlugin के माध्यम से ChannelPlugin
    ├── channel.test.ts       # परीक्षण
    ├── client.ts             # प्लेटफ़ॉर्म API क्लाइंट
    └── runtime.ts            # रनटाइम स्टोर (यदि आवश्यक हो)

​

उन्नत विषय

​

अगले चरण

• प्रदाता Plugin - यदि आपका Plugin मॉडल भी प्रदान करता है
• SDK अवलोकन - संपूर्ण उपपथ आयात संदर्भ
• SDK परीक्षण - परीक्षण उपयोगिताएँ और अनुबंध परीक्षण
• Plugin मैनिफ़ेस्ट - संपूर्ण मैनिफ़ेस्ट स्कीमा

​

संबंधित

• Plugin SDK सेटअप
• Plugin बनाना
• एजेंट हार्नेस Plugin