การสร้าง Plugin สำหรับช่องทาง

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.

​

Plugin ช่องทางทำงานอย่างไร

• การกำหนดค่า - การระบุบัญชีและตัวช่วยตั้งค่า
• ความปลอดภัย - นโยบาย DM และรายการอนุญาต
• การจับคู่ - โฟลว์อนุมัติผ่าน DM
• ไวยากรณ์เซสชัน - วิธีที่รหัสการสนทนาเฉพาะผู้ให้บริการแมปไปยังแชตฐาน, รหัสเธรด และทางเลือกสำรองของผู้ปกครอง
• ขาออก - การส่งข้อความ, สื่อ และโพลไปยังแพลตฟอร์ม
• การจัดเธรด - วิธีจัดเธรดการตอบกลับ
• การพิมพ์ Heartbeat - สัญญาณกำลังพิมพ์/ไม่ว่างแบบไม่บังคับสำหรับเป้าหมายการส่ง Heartbeat

​

การอนุมัติและความสามารถของช่องทาง

• core เป็นเจ้าของ /approve ในแชทเดียวกัน, payload ของปุ่มอนุมัติที่ใช้ร่วมกัน, และการส่ง fallback ทั่วไป
• แนะนำให้มีออบเจ็กต์ approvalCapability เดียวบน Plugin ช่องทาง เมื่อช่องทางต้องการพฤติกรรมเฉพาะสำหรับการอนุมัติ
• ChannelPlugin.approvals ถูกลบออกแล้ว ให้วางข้อเท็จจริงด้านการส่ง/เนทีฟ/การเรนเดอร์/การยืนยันสิทธิ์ของการอนุมัติไว้บน approvalCapability
• plugin.auth ใช้เฉพาะเข้าสู่ระบบ/ออกจากระบบเท่านั้น; core จะไม่อ่าน hook การยืนยันสิทธิ์ของการอนุมัติจากออบเจ็กต์นั้นอีกต่อไป
• approvalCapability.authorizeActorAction และ approvalCapability.getActionAvailabilityState เป็น seam มาตรฐานสำหรับการยืนยันสิทธิ์การอนุมัติ
• ใช้ approvalCapability.getActionAvailabilityState สำหรับความพร้อมของการยืนยันสิทธิ์การอนุมัติในแชทเดียวกัน
• หากช่องทางของคุณเปิดเผยการอนุมัติ exec แบบเนทีฟ ให้ใช้ approvalCapability.getExecInitiatingSurfaceState สำหรับสถานะพื้นผิวเริ่มต้น/ไคลเอนต์เนทีฟเมื่อแตกต่างจากการยืนยันสิทธิ์การอนุมัติในแชทเดียวกัน core ใช้ hook เฉพาะ exec นี้เพื่อแยก enabled กับ disabled, ตัดสินว่าช่องทางที่เริ่มต้นรองรับการอนุมัติ exec แบบเนทีฟหรือไม่, และรวมช่องทางนั้นไว้ในคำแนะนำ fallback ของไคลเอนต์เนทีฟ createApproverRestrictedNativeApprovalCapability(...) จะเติมส่วนนี้ให้สำหรับกรณีทั่วไป
• ใช้ outbound.shouldSuppressLocalPayloadPrompt หรือ outbound.beforeDeliverPayload สำหรับพฤติกรรมวงจรชีวิตของ payload เฉพาะช่องทาง เช่น การซ่อน prompt การอนุมัติภายในที่ซ้ำกัน หรือการส่งตัวบ่งชี้ว่ากำลังพิมพ์ก่อนส่ง
• ใช้ approvalCapability.delivery เฉพาะสำหรับการกำหนดเส้นทางการอนุมัติแบบเนทีฟหรือการระงับ fallback
• ใช้ approvalCapability.nativeRuntime สำหรับข้อเท็จจริงการอนุมัติแบบเนทีฟที่ช่องทางเป็นเจ้าของ ให้คงความ lazy ไว้บน entrypoint ของช่องทางที่เป็น hot path ด้วย createLazyChannelApprovalNativeRuntimeAdapter(...) ซึ่งสามารถนำเข้าโมดูล runtime ของคุณตามต้องการได้ โดยยังให้ core ประกอบวงจรชีวิตการอนุมัติได้
• ใช้ approvalCapability.render เฉพาะเมื่อช่องทางต้องการ payload การอนุมัติแบบกำหนดเองจริง ๆ แทน renderer ที่ใช้ร่วมกัน
• ใช้ approvalCapability.describeExecApprovalSetup เมื่อช่องทางต้องการให้คำตอบในเส้นทาง disabled อธิบาย knob การตั้งค่าที่แน่นอนซึ่งจำเป็นต่อการเปิดใช้การอนุมัติ exec แบบเนทีฟ hook จะได้รับ { channel, channelLabel, accountId }; ช่องทางแบบบัญชีที่มีชื่อควรเรนเดอร์ path ที่ผูกกับขอบเขตบัญชี เช่น channels.<channel>.accounts.<id>.execApprovals.* แทนค่าเริ่มต้นระดับบนสุด
• หากช่องทางสามารถอนุมานตัวตน DM ที่เสถียรคล้ายเจ้าของได้จาก config ที่มีอยู่ ให้ใช้ createResolvedApproverActionAuthAdapter จาก openclaw/plugin-sdk/approval-runtime เพื่อจำกัด /approve ในแชทเดียวกันโดยไม่เพิ่มตรรกะ core เฉพาะการอนุมัติ
• หากช่องทางต้องการการส่งการอนุมัติแบบเนทีฟ ให้โค้ดช่องทางเน้นที่การทำ target normalization รวมถึงข้อเท็จจริงด้านการขนส่ง/การนำเสนอ ใช้ createChannelExecApprovalProfile, createChannelNativeOriginTargetResolver, createChannelApproverDmTargetResolver, และ createApproverRestrictedNativeApprovalCapability จาก openclaw/plugin-sdk/approval-runtime วางข้อเท็จจริงเฉพาะช่องทางไว้หลัง approvalCapability.nativeRuntime โดยเหมาะที่สุดผ่าน createChannelApprovalNativeRuntimeAdapter(...) หรือ createLazyChannelApprovalNativeRuntimeAdapter(...) เพื่อให้ core ประกอบ handler และเป็นเจ้าของการกรองคำขอ, การกำหนดเส้นทาง, การลบรายการซ้ำ, การหมดอายุ, การสมัคร Gateway, และการแจ้งว่าถูกกำหนดเส้นทางไปที่อื่น nativeRuntime ถูกแยกเป็น seam ที่เล็กลงสองสามส่วน:
• createChannelNativeOriginTargetResolver ใช้ตัวจับคู่ route ของช่องทางที่ใช้ร่วมกันโดยค่าเริ่มต้นสำหรับ target { to, accountId, threadId } ส่ง targetsMatch เฉพาะเมื่อช่องทางมีกฎความเทียบเท่าเฉพาะ provider เช่น การจับคู่ prefix timestamp ของ Slack
• ส่ง normalizeTargetForMatch ให้ createChannelNativeOriginTargetResolver เมื่อช่องทางต้อง canonicalize id ของ provider ก่อนที่ตัวจับคู่ route เริ่มต้นหรือ callback targetsMatch แบบกำหนดเองจะทำงาน ขณะยังรักษา target เดิมไว้สำหรับการส่ง ใช้ normalizeTarget เฉพาะเมื่อ target การส่งที่ resolve แล้วควรถูก canonicalize เอง
• availability - บัญชีถูกกำหนดค่าไว้หรือไม่ และควรจัดการคำขอหรือไม่
• presentation - แมป view model การอนุมัติที่ใช้ร่วมกันเป็น payload เนทีฟ pending/resolved/expired หรือ action สุดท้าย
• transport - เตรียม target รวมถึงส่ง/อัปเดต/ลบข้อความการอนุมัติแบบเนทีฟ
• interactions - hook เสริมสำหรับ bind/unbind/clear-action สำหรับปุ่มหรือ reaction แบบเนทีฟ
• observe - hook เสริมสำหรับ diagnostics การส่ง
• หากช่องทางต้องการออบเจ็กต์ที่ runtime เป็นเจ้าของ เช่น client, token, Bolt app, หรือ webhook receiver ให้ลงทะเบียนผ่าน openclaw/plugin-sdk/channel-runtime-context registry ของ runtime context ทั่วไปทำให้ core bootstrap handler ที่ขับเคลื่อนด้วย capability จากสถานะเริ่มต้นของช่องทางได้โดยไม่เพิ่ม glue wrapper เฉพาะการอนุมัติ
• ใช้ createChannelApprovalHandler หรือ createChannelNativeApprovalRuntime ระดับล่างเฉพาะเมื่อ seam ที่ขับเคลื่อนด้วย capability ยังแสดงออกได้ไม่พอ
• ช่องทางการอนุมัติแบบเนทีฟต้องส่งทั้ง accountId และ approvalKind ผ่าน helper เหล่านั้น accountId ทำให้นโยบายการอนุมัติหลายบัญชีถูกจำกัดขอบเขตไปยังบัญชีบอทที่ถูกต้อง และ approvalKind ทำให้พฤติกรรมการอนุมัติ exec กับ Plugin พร้อมใช้งานต่อช่องทางโดยไม่ต้องมี branch แบบ hardcode ใน core
• ตอนนี้ core เป็นเจ้าของการแจ้ง reroute การอนุมัติด้วย Plugin ช่องทางไม่ควรส่งข้อความ follow-up ของตัวเองว่า “การอนุมัติถูกส่งไปยัง DM / ช่องทางอื่น” จาก createChannelNativeApprovalRuntime; ให้เปิดเผยการกำหนดเส้นทาง origin + DM ของผู้อนุมัติที่ถูกต้องผ่าน helper capability การอนุมัติที่ใช้ร่วมกัน และให้ core รวมการส่งจริงก่อนโพสต์การแจ้งใด ๆ กลับไปยังแชทที่เริ่มต้น
• รักษา kind ของ id การอนุมัติที่ส่งแล้วแบบครบวงจร ไคลเอนต์เนทีฟไม่ควร เดาหรือเขียนการกำหนดเส้นทางการอนุมัติ exec กับ Plugin ใหม่จากสถานะภายในช่องทาง
• kind การอนุมัติที่ต่างกันสามารถเปิดเผยพื้นผิวเนทีฟที่ต่างกันโดยตั้งใจได้ ตัวอย่างที่ bundled ปัจจุบัน:
  • Slack คงการกำหนดเส้นทางการอนุมัติแบบเนทีฟไว้สำหรับทั้ง id ของ exec และ Plugin
  • Matrix คงการกำหนดเส้นทาง DM/ช่องทางแบบเนทีฟและ UX ของ reaction เดิมไว้สำหรับการอนุมัติ exec และ Plugin ขณะยังยอมให้การยืนยันสิทธิ์แตกต่างกันตาม kind การอนุมัติ
• createApproverRestrictedNativeApprovalAdapter ยังคงมีอยู่ในฐานะ wrapper เพื่อความเข้ากันได้ แต่โค้ดใหม่ควรเลือกใช้ตัวสร้าง capability และเปิดเผย 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 ครอบคลุม helper สำหรับ setup ที่ปลอดภัยต่อ runtime: adapter patch setup ที่ปลอดภัยต่อการ import (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), เอาต์พุต lookup-note, promptResolvedAllowFrom, splitSetupEntries, และตัวสร้าง setup-proxy แบบ delegated
• openclaw/plugin-sdk/setup-runtime รวม seam adapter ที่รับรู้ env สำหรับ createEnvPatchedAccountSetupAdapter
• openclaw/plugin-sdk/channel-setup ครอบคลุมตัวสร้าง setup สำหรับ optional-install พร้อม primitive ที่ปลอดภัยต่อ setup อีกสองสามตัว: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

• ใช้ seam openclaw/plugin-sdk/setup ที่กว้างกว่าเฉพาะเมื่อคุณยังต้องการ helper setup/config ที่ใช้ร่วมกันและหนักกว่า เช่น moveSingleAccountChannelSectionToDefaultAccount(...)

• openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution, และ openclaw/plugin-sdk/account-helpers สำหรับ config หลายบัญชีและ fallback ของบัญชีเริ่มต้น
• openclaw/plugin-sdk/inbound-envelope และ openclaw/plugin-sdk/inbound-reply-dispatch สำหรับ route/envelope ขาเข้าและ wiring สำหรับบันทึกแล้ว dispatch
• openclaw/plugin-sdk/messaging-targets สำหรับการ parse/จับคู่ target
• openclaw/plugin-sdk/outbound-media และ openclaw/plugin-sdk/outbound-runtime สำหรับการโหลดสื่อ รวมถึง delegate identity/send ขาออกและการวางแผน payload
• buildThreadAwareOutboundSessionRoute(...) จาก openclaw/plugin-sdk/channel-core เมื่อ route ขาออกควรรักษา replyToId/threadId ที่ระบุชัดเจน หรือกู้คืน session :thread: ปัจจุบัน หลังจาก base session key ยังตรงกัน Plugin provider สามารถ override ลำดับความสำคัญ, พฤติกรรม suffix, และการทำ normalization ของ thread id เมื่อแพลตฟอร์มของตน มี semantics การส่ง thread แบบเนทีฟ
• openclaw/plugin-sdk/thread-bindings-runtime สำหรับวงจรชีวิต thread-binding และการลงทะเบียน adapter
• openclaw/plugin-sdk/agent-media-payload เฉพาะเมื่อยังต้องใช้ layout ของ field payload agent/media แบบ legacy
• openclaw/plugin-sdk/telegram-command-config สำหรับการทำ normalization ของคำสั่งกำหนดเองของ Telegram, การตรวจสอบ duplicate/conflict, และสัญญา config คำสั่งที่ stable ต่อ fallback

​

นโยบาย mention ขาเข้า

• การรวบรวมหลักฐานที่ Plugin เป็นเจ้าของ
• การประเมินนโยบายที่ใช้ร่วมกัน

• การตรวจจับ reply-to-bot
• การตรวจจับ quoted-bot
• การตรวจสอบการเข้าร่วม thread
• การยกเว้นข้อความบริการ/ระบบ
• cache เนทีฟของแพลตฟอร์มที่จำเป็นเพื่อพิสูจน์การเข้าร่วมของบอท

• 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)

​

หัวข้อขั้นสูง

​

ขั้นตอนถัดไป

• Provider Plugins - หาก Plugin ของคุณยังให้บริการโมเดลด้วย
• ภาพรวม SDK - อ้างอิงการนำเข้า subpath ทั้งหมด
• การทดสอบ SDK - ยูทิลิตีทดสอบและการทดสอบ contract
• Manifest ของ Plugin - สคีมา manifest ทั้งหมด

​

ที่เกี่ยวข้อง

• การตั้งค่า SDK ของ Plugin
• การสร้าง Plugin
• Plugin agent harness