بناء Plugins القنوات

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

كيف تعمل Plugins القنوات

• الإعدادات - حل الحساب ومعالج الإعداد
• الأمان - سياسة الرسائل المباشرة وقوائم السماح
• الإقران - تدفق الموافقة عبر الرسائل المباشرة
• قواعد الجلسة - كيفية ربط معرفات المحادثات الخاصة بالمزود بالمحادثات الأساسية ومعرفات السلاسل والبدائل الأصلية
• الصادر - إرسال النص والوسائط والاستطلاعات إلى المنصة
• تسلسل المحادثات - كيفية ربط الردود بالسلاسل
• مؤشرات الكتابة في Heartbeat - إشارات كتابة/انشغال اختيارية لأهداف تسليم Heartbeat

​

الموافقات وقدرات القناة

• تمتلك النواة /approve في نفس الدردشة، وحمولات أزرار الموافقة المشتركة، والتسليم الاحتياطي العام.
• فضّل كائن approvalCapability واحدًا على Plugin القناة عندما تحتاج القناة إلى سلوك خاص بالموافقات.
• تمت إزالة ChannelPlugin.approvals. ضع حقائق تسليم/أصلية/عرض/مصادقة الموافقة على approvalCapability.
• plugin.auth مخصص لتسجيل الدخول/الخروج فقط؛ لم تعد النواة تقرأ خطافات مصادقة الموافقات من ذلك الكائن.
• approvalCapability.authorizeActorAction وapprovalCapability.getActionAvailabilityState هما خط تماس مصادقة الموافقات القياسي.
• استخدم approvalCapability.getActionAvailabilityState لتوفر مصادقة الموافقة في نفس الدردشة.
• إذا كانت قناتك تعرض موافقات exec أصلية، فاستخدم approvalCapability.getExecInitiatingSurfaceState لحالة سطح البدء/العميل الأصلي عندما تختلف عن مصادقة الموافقة في نفس الدردشة. تستخدم النواة ذلك الخطاف الخاص بـ exec للتمييز بين enabled وdisabled، وتحديد ما إذا كانت القناة البادئة تدعم موافقات exec الأصلية، وتضمين القناة في إرشادات الرجوع الاحتياطي للعميل الأصلي. يملأ createApproverRestrictedNativeApprovalCapability(...) هذا للحالة الشائعة.
• استخدم outbound.shouldSuppressLocalPayloadPrompt أو outbound.beforeDeliverPayload لسلوك دورة حياة الحمولة الخاص بالقناة، مثل إخفاء مطالبات الموافقة المحلية المكررة أو إرسال مؤشرات الكتابة قبل التسليم.
• استخدم approvalCapability.delivery فقط لتوجيه الموافقة الأصلية أو كبت الرجوع الاحتياطي.
• استخدم approvalCapability.nativeRuntime لحقائق الموافقة الأصلية المملوكة للقناة. أبقه كسولًا في نقاط دخول القناة كثيرة الاستخدام باستخدام createLazyChannelApprovalNativeRuntimeAdapter(...)، والذي يمكنه استيراد وحدة وقت التشغيل عند الطلب مع السماح للنواة بتجميع دورة حياة الموافقة.
• استخدم approvalCapability.render فقط عندما تحتاج القناة فعلًا إلى حمولات موافقة مخصصة بدلًا من العارض المشترك.
• استخدم approvalCapability.describeExecApprovalSetup عندما تريد القناة أن يشرح رد مسار التعطيل مفاتيح الإعدادات الدقيقة اللازمة لتمكين موافقات exec الأصلية. يتلقى الخطاف { channel, channelLabel, accountId }؛ يجب أن تعرض قنوات الحسابات المسماة مسارات محددة النطاق للحساب مثل channels.<channel>.accounts.<id>.execApprovals.* بدلًا من القيم الافتراضية على المستوى الأعلى.
• إذا كان بإمكان قناة استنتاج هويات DM مستقرة شبيهة بالمالك من الإعدادات الحالية، فاستخدم createResolvedApproverActionAuthAdapter من openclaw/plugin-sdk/approval-runtime لتقييد /approve في نفس الدردشة دون إضافة منطق خاص بالموافقة إلى النواة.
• إذا احتاجت قناة إلى تسليم موافقة أصلي، فاجعل كود القناة مركزًا على تطبيع الهدف وحقائق النقل/العرض. استخدم createChannelExecApprovalProfile وcreateChannelNativeOriginTargetResolver وcreateChannelApproverDmTargetResolver وcreateApproverRestrictedNativeApprovalCapability من openclaw/plugin-sdk/approval-runtime. ضع الحقائق الخاصة بالقناة خلف approvalCapability.nativeRuntime، ويفضل عبر createChannelApprovalNativeRuntimeAdapter(...) أو createLazyChannelApprovalNativeRuntimeAdapter(...)، حتى تتمكن النواة من تجميع المعالج وامتلاك ترشيح الطلبات، والتوجيه، وإزالة التكرار، وانتهاء الصلاحية، واشتراك Gateway، وإشعارات التوجيه إلى مكان آخر. ينقسم nativeRuntime إلى بضعة خطوط تماس أصغر:
• يستخدم createChannelNativeOriginTargetResolver مطابق مسارات القنوات المشترك افتراضيًا لأهداف { to, accountId, threadId }. مرّر targetsMatch فقط عندما تمتلك قناة قواعد تكافؤ خاصة بالمزوّد، مثل مطابقة بادئة الطابع الزمني في Slack.
• مرّر normalizeTargetForMatch إلى createChannelNativeOriginTargetResolver عندما تحتاج القناة إلى جعل معرّفات المزوّد قياسية قبل تشغيل مطابق المسارات الافتراضي أو رد نداء targetsMatch مخصص، مع الحفاظ على الهدف الأصلي للتسليم. استخدم normalizeTarget فقط عندما يجب جعل هدف التسليم المحلول نفسه قياسيًا.
• availability - ما إذا كان الحساب مضبوطًا وما إذا كان يجب التعامل مع الطلب
• presentation - تعيين نموذج عرض الموافقة المشترك إلى حمولات أصلية معلقة/محلولة/منتهية أو إجراءات نهائية
• transport - تحضير الأهداف وإرسال/تحديث/حذف رسائل الموافقة الأصلية
• interactions - خطافات ربط/إلغاء ربط/مسح إجراء اختيارية للأزرار أو التفاعلات الأصلية
• observe - خطافات تشخيص التسليم الاختيارية
• إذا احتاجت القناة إلى كائنات مملوكة لوقت التشغيل مثل عميل، أو رمز، أو تطبيق Bolt، أو مستقبل Webhook، فسجلها عبر openclaw/plugin-sdk/channel-runtime-context. يتيح سجل سياق وقت التشغيل العام للنواة تمهيد المعالجات المدفوعة بالقدرات من حالة بدء تشغيل القناة دون إضافة غراء تغليف خاص بالموافقة.
• استخدم createChannelApprovalHandler أو createChannelNativeApprovalRuntime ذوي المستوى الأدنى فقط عندما لا يكون خط التماس المدفوع بالقدرات معبرًا بما يكفي بعد.
• يجب أن تمرر قنوات الموافقة الأصلية كلًا من accountId وapprovalKind عبر تلك المساعدات. يُبقي accountId سياسة موافقة الحسابات المتعددة محصورة في حساب البوت الصحيح، ويُبقي approvalKind سلوك موافقات exec مقابل Plugin متاحًا للقناة دون فروع ثابتة في النواة.
• تمتلك النواة الآن إشعارات إعادة توجيه الموافقة أيضًا. يجب ألا ترسل Plugins القنوات رسائل متابعة خاصة بها من نوع “ذهبت الموافقة إلى DMs / قناة أخرى” من createChannelNativeApprovalRuntime؛ بدلًا من ذلك، اعرض توجيهًا دقيقًا للمنشأ + DM الموافق عبر مساعدات قدرة الموافقة المشتركة، ودع النواة تجمع عمليات التسليم الفعلية قبل نشر أي إشعار عائد إلى الدردشة البادئة.
• حافظ على نوع معرّف الموافقة المسلّم من البداية إلى النهاية. يجب ألا تخمن العملاء الأصلية أو تعيد كتابة توجيه موافقة exec مقابل Plugin من حالة محلية للقناة.
• يمكن لأنواع الموافقات المختلفة أن تعرض أسطحًا أصلية مختلفة عمدًا. الأمثلة المضمّنة الحالية:
  • يحافظ Slack على توفر توجيه الموافقة الأصلي لكل من معرّفات exec وPlugin.
  • يحافظ Matrix على نفس توجيه DM/القناة الأصلي وتجربة تفاعلات الموافقة لكل من موافقات exec وPlugin، مع السماح في الوقت نفسه للمصادقة بالاختلاف حسب نوع الموافقة.
• لا يزال createApproverRestrictedNativeApprovalAdapter موجودًا كغلاف توافق، لكن يجب أن يفضل الكود الجديد باني القدرة ويعرض approvalCapability على Plugin.

• 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-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 مساعدات الإعداد الآمنة لوقت التشغيل: محولات تصحيح الإعداد الآمنة للاستيراد (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator)، ومخرجات ملاحظات البحث، وpromptResolvedAllowFrom، وsplitSetupEntries، وبناة وكيل الإعداد المفوض
• يتضمن openclaw/plugin-sdk/setup-runtime خط تماس المحول المدرك للبيئة لـ createEnvPatchedAccountSetupAdapter
• يغطي openclaw/plugin-sdk/channel-setup بناة إعداد التثبيت الاختياري بالإضافة إلى بضعة بدائيات آمنة للإعداد: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

• استخدم خط تماس 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/inbound-reply-dispatch لمسار/غلاف الوارد وتوصيل التسجيل والإرسال
• openclaw/plugin-sdk/messaging-targets لتحليل/مطابقة الأهداف
• openclaw/plugin-sdk/outbound-media و openclaw/plugin-sdk/outbound-runtime لتحميل الوسائط بالإضافة إلى مفوضات الهوية/الإرسال الصادرة وتخطيط الحمولة
• buildThreadAwareOutboundSessionRoute(...) من openclaw/plugin-sdk/channel-core عندما يجب أن يحافظ مسار صادر على replyToId/threadId صريح أو يستعيد جلسة :thread: الحالية بعد أن يظل مفتاح الجلسة الأساسي مطابقًا. يمكن لـ Plugins المزوّدين تجاوز الأولوية، وسلوك اللاحقة، وتطبيع معرّف السلسلة عندما تمتلك منصتهم دلالات تسليم سلاسل أصلية.
• openclaw/plugin-sdk/thread-bindings-runtime لدورة حياة ربط السلاسل وتسجيل المحولات
• openclaw/plugin-sdk/agent-media-payload فقط عندما يظل تخطيط حقل حمولة الوكيل/الوسائط القديم مطلوبًا
• openclaw/plugin-sdk/telegram-command-config لتطبيع أوامر Telegram المخصصة، والتحقق من التكرار/التعارض، وعقد إعداد أوامر مستقر عند الرجوع الاحتياطي

​

سياسة الإشارة الواردة

• جمع الأدلة المملوك لـ Plugin
• تقييم السياسة المشتركة

• اكتشاف الرد على البوت
• اكتشاف الاقتباس من البوت
• فحوصات مشاركة السلسلة
• استثناءات رسائل الخدمة/النظام
• ذاكرات التخزين المؤقت الأصلية للمنصة اللازمة لإثبات مشاركة البوت

• requireMention
• نتيجة الإشارة الصريحة
• قائمة السماح للإشارة الضمنية
• تجاوز الأمر
• قرار التخطي النهائي

1. احسب حقائق الإشارة المحلية.
2. مرر تلك الحقائق إلى resolveInboundMentionDecision({ facts, policy }).
3. استخدم decision.effectiveWasMentioned وdecision.shouldBypassMention وdecision.shouldSkip في بوابة الوارد لديك.

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

const mentionMatch = matchesMentionWithExplicit(text, {
  mentionRegexes,
  mentionPatterns,
});

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

const decision = resolveInboundMentionDecision({
  facts,
  policy: {
    isGroup,
    requireMention,
    allowedImplicitMentionKinds: requireExplicitMention ? [] : ["reply_to_bot", "quoted_bot"],
    allowTextCommands,
    hasControlCommand,
    commandAuthorized,
  },
});

if (decision.shouldSkip) return;

• buildMentionRegexes
• matchesMentionPatterns
• matchesMentionWithExplicit
• implicitMentionKindWhen
• resolveInboundMentionDecision

​

شرح تفصيلي

{
  "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": "Connect OpenClaw to Acme Chat."
    }
  }
}

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",
    setup: {
      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",
        };
      },
    },
  }),

  // 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: {
      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-managed auth (verify signatures yourself)
    handler: async (req, res) => {
      const event = parseWebhookPayload(req);

      // Your inbound handler dispatches the message to OpenClaw.
      // The exact wiring depends on your platform SDK -
      // see a real example in the bundled Microsoft Teams or Google Chat plugin package.
      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("resolves account from config", () => {
    const cfg = {
      channels: {
        "acme-chat": { token: "test-token", allowFrom: ["user1"] },
      },
    } as any;
    const account = acmeChatPlugin.setup!.resolveAccount(cfg, undefined);
    expect(account.token).toBe("test-token");
  });

  it("inspects account without materializing secrets", () => {
    const cfg = {
      channels: { "acme-chat": { token: "test-token" } },
    } as any;
    const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(true);
    expect(result.tokenStatus).toBe("available");
  });

  it("reports missing config", () => {
    const cfg = { channels: {} } as any;
    const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(false);
  });
});

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

​

بنية الملفات

<bundled-plugin-root>/acme-chat/
├── package.json              # openclaw.channel metadata
├── openclaw.plugin.json      # Manifest with config schema
├── index.ts                  # defineChannelPluginEntry
├── setup-entry.ts            # defineSetupPluginEntry
├── api.ts                    # Public exports (optional)
├── runtime-api.ts            # Internal runtime exports (optional)
└── src/
    ├── channel.ts            # ChannelPlugin via createChatChannelPlugin
    ├── channel.test.ts       # Tests
    ├── client.ts             # Platform API client
    └── runtime.ts            # Runtime store (if needed)

​

موضوعات متقدمة

​

الخطوات التالية

• Plugins المزوّدين - إذا كان Plugin الخاص بك يوفّر نماذج أيضًا
• نظرة عامة على SDK - مرجع كامل لاستيرادات المسارات الفرعية
• اختبار SDK - أدوات الاختبار واختبارات العقد
• بيان Plugin - مخطط البيان الكامل

​

ذو صلة

• إعداد Plugin SDK
• بناء Plugins
• Plugins حاضنة الوكيل