Xây dựng Plugin kênh

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.

​

Cách Plugin kênh hoạt động

• Cấu hình — phân giải tài khoản và trình hướng dẫn thiết lập
• Bảo mật — chính sách DM và danh sách cho phép
• Ghép đôi — luồng phê duyệt DM
• Ngữ pháp phiên — cách các id cuộc trò chuyện riêng của nhà cung cấp ánh xạ tới cuộc trò chuyện cơ sở, id luồng và các phương án cha dự phòng
• Gửi đi — gửi văn bản, phương tiện và bình chọn tới nền tảng
• Phân luồng — cách các trả lời được phân luồng
• Heartbeat đang nhập — tín hiệu đang nhập/bận tùy chọn cho các đích phân phối Heartbeat

​

Phê duyệt và năng lực kênh

• Lõi sở hữu /approve trong cùng cuộc trò chuyện, payload nút phê duyệt dùng chung và phân phối dự phòng chung.
• Ưu tiên một đối tượng approvalCapability trên Plugin kênh khi kênh cần hành vi riêng cho phê duyệt.
• ChannelPlugin.approvals đã bị loại bỏ. Đặt các thông tin phân phối/native/render/auth phê duyệt trên approvalCapability.
• plugin.auth chỉ dành cho đăng nhập/đăng xuất; lõi không còn đọc hook auth phê duyệt từ đối tượng đó.
• approvalCapability.authorizeActorAction và approvalCapability.getActionAvailabilityState là seam auth phê duyệt chuẩn.
• Dùng approvalCapability.getActionAvailabilityState cho khả năng auth phê duyệt trong cùng cuộc trò chuyện.
• Nếu kênh của bạn cung cấp phê duyệt exec native, dùng approvalCapability.getExecInitiatingSurfaceState cho trạng thái bề mặt khởi tạo/client native khi nó khác với auth phê duyệt trong cùng cuộc trò chuyện. Lõi dùng hook riêng cho exec đó để phân biệt enabled với disabled, quyết định kênh khởi tạo có hỗ trợ phê duyệt exec native hay không, và đưa kênh vào hướng dẫn dự phòng client native. createApproverRestrictedNativeApprovalCapability(...) điền phần này cho trường hợp phổ biến.
• Dùng outbound.shouldSuppressLocalPayloadPrompt hoặc outbound.beforeDeliverPayload cho hành vi vòng đời payload riêng theo kênh, chẳng hạn ẩn prompt phê duyệt cục bộ trùng lặp hoặc gửi chỉ báo đang nhập trước khi phân phối.
• Chỉ dùng approvalCapability.delivery cho định tuyến phê duyệt native hoặc chặn dự phòng.
• Dùng approvalCapability.nativeRuntime cho các thông tin phê duyệt native do kênh sở hữu. Giữ nó lazy trên các điểm vào kênh nóng bằng createLazyChannelApprovalNativeRuntimeAdapter(...), có thể import module runtime của bạn khi cần trong khi vẫn cho phép lõi lắp ráp vòng đời phê duyệt.
• Chỉ dùng approvalCapability.render khi kênh thật sự cần payload phê duyệt tùy chỉnh thay vì renderer dùng chung.
• Dùng approvalCapability.describeExecApprovalSetup khi kênh muốn trả lời ở nhánh disabled giải thích chính xác các núm cấu hình cần thiết để bật phê duyệt exec native. Hook nhận { channel, channelLabel, accountId }; các kênh có tài khoản được đặt tên nên render các đường dẫn theo phạm vi tài khoản như channels.<channel>.accounts.<id>.execApprovals.* thay vì mặc định cấp cao nhất.
• Nếu kênh có thể suy ra các danh tính DM giống chủ sở hữu ổn định từ cấu hình hiện có, dùng createResolvedApproverActionAuthAdapter từ openclaw/plugin-sdk/approval-runtime để giới hạn /approve trong cùng cuộc trò chuyện mà không thêm logic lõi riêng cho phê duyệt.
• Nếu kênh cần phân phối phê duyệt native, hãy giữ mã kênh tập trung vào chuẩn hóa đích cộng với thông tin transport/presentation. Dùng createChannelExecApprovalProfile, createChannelNativeOriginTargetResolver, createChannelApproverDmTargetResolver và createApproverRestrictedNativeApprovalCapability từ openclaw/plugin-sdk/approval-runtime. Đặt các thông tin riêng của kênh phía sau approvalCapability.nativeRuntime, lý tưởng là qua createChannelApprovalNativeRuntimeAdapter(...) hoặc createLazyChannelApprovalNativeRuntimeAdapter(...), để lõi có thể lắp ráp handler và sở hữu lọc yêu cầu, định tuyến, chống trùng lặp, hết hạn, đăng ký Gateway và thông báo đã định tuyến nơi khác. nativeRuntime được chia thành một vài seam nhỏ hơn:
• createChannelNativeOriginTargetResolver mặc định dùng bộ so khớp channel-route dùng chung cho các đích { to, accountId, threadId }. Chỉ truyền targetsMatch khi kênh có quy tắc tương đương riêng của nhà cung cấp, chẳng hạn so khớp tiền tố timestamp của Slack.
• Truyền normalizeTargetForMatch vào createChannelNativeOriginTargetResolver khi kênh cần chuẩn hóa id nhà cung cấp trước khi bộ so khớp tuyến mặc định hoặc callback targetsMatch tùy chỉnh chạy, trong khi vẫn giữ đích gốc để phân phối. Chỉ dùng normalizeTarget khi chính đích phân phối đã phân giải cần được chuẩn hóa.
• availability — tài khoản đã được cấu hình hay chưa và yêu cầu có nên được xử lý hay không
• presentation — ánh xạ view model phê duyệt dùng chung thành payload native đang chờ/đã phân giải/đã hết hạn hoặc hành động cuối
• transport — chuẩn bị đích cùng với gửi/cập nhật/xóa tin nhắn phê duyệt native
• interactions — các hook bind/unbind/clear-action tùy chọn cho nút hoặc phản ứng native
• observe — các hook chẩn đoán phân phối tùy chọn
• Nếu kênh cần các đối tượng do runtime sở hữu như client, token, ứng dụng Bolt hoặc webhook receiver, hãy đăng ký chúng qua openclaw/plugin-sdk/channel-runtime-context. Registry runtime-context chung cho phép lõi bootstrap các handler dựa trên capability từ trạng thái khởi động kênh mà không cần thêm lớp keo wrapper riêng cho phê duyệt.
• Chỉ dùng createChannelApprovalHandler hoặc createChannelNativeApprovalRuntime cấp thấp hơn khi seam dựa trên capability chưa đủ biểu đạt.
• Các kênh phê duyệt native phải định tuyến cả accountId và approvalKind qua các helper đó. accountId giữ chính sách phê duyệt đa tài khoản được giới hạn vào đúng tài khoản bot, còn approvalKind giữ cho hành vi phê duyệt exec so với Plugin khả dụng với kênh mà không cần nhánh hardcode trong lõi.
• Lõi hiện cũng sở hữu thông báo định tuyến lại phê duyệt. Plugin kênh không nên gửi tin nhắn tiếp nối riêng kiểu “phê duyệt đã chuyển tới DM / kênh khác” từ createChannelNativeApprovalRuntime; thay vào đó, cung cấp định tuyến origin + DM người phê duyệt chính xác qua các helper capability phê duyệt dùng chung và để lõi tổng hợp các lần phân phối thực tế trước khi đăng bất kỳ thông báo nào trở lại cuộc trò chuyện khởi tạo.
• Giữ nguyên loại id phê duyệt đã phân phối từ đầu đến cuối. Client native không nên đoán hoặc viết lại định tuyến phê duyệt exec so với Plugin từ trạng thái cục bộ của kênh.
• Các loại phê duyệt khác nhau có thể chủ đích cung cấp các bề mặt native khác nhau. Các ví dụ đi kèm hiện tại:
  • Slack giữ định tuyến phê duyệt native khả dụng cho cả id exec và Plugin.
  • Matrix giữ cùng định tuyến DM/kênh native và UX phản ứng cho phê duyệt exec và Plugin, đồng thời vẫn cho phép auth khác nhau theo loại phê duyệt.
• createApproverRestrictedNativeApprovalAdapter vẫn tồn tại như một wrapper tương thích, nhưng mã mới nên ưu tiên builder capability và cung cấp approvalCapability trên 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 bao phủ các helper thiết lập an toàn cho runtime: adapter vá thiết lập an toàn khi import (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), đầu ra ghi chú tra cứu, promptResolvedAllowFrom, splitSetupEntries và các builder setup-proxy được ủy quyền
• openclaw/plugin-sdk/setup-adapter-runtime là seam adapter hẹp có nhận biết env cho createEnvPatchedAccountSetupAdapter
• openclaw/plugin-sdk/channel-setup bao phủ các builder thiết lập cài đặt tùy chọn cùng một vài primitive an toàn cho thiết lập: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

• chỉ dùng seam openclaw/plugin-sdk/setup rộng hơn khi bạn cũng cần các helper thiết lập/cấu hình dùng chung nặng hơn như moveSingleAccountChannelSectionToDefaultAccount(...)

• openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution, và openclaw/plugin-sdk/account-helpers cho cấu hình nhiều tài khoản và fallback tài khoản mặc định
• openclaw/plugin-sdk/inbound-envelope và openclaw/plugin-sdk/inbound-reply-dispatch cho route/envelope inbound và wiring ghi rồi dispatch
• openclaw/plugin-sdk/messaging-targets cho phân tích/matching mục tiêu
• openclaw/plugin-sdk/outbound-media và openclaw/plugin-sdk/outbound-runtime cho tải media cùng các delegate danh tính/gửi outbound và lập kế hoạch payload
• buildThreadAwareOutboundSessionRoute(...) từ openclaw/plugin-sdk/channel-core khi một route outbound cần giữ nguyên replyToId/threadId rõ ràng hoặc khôi phục session :thread: hiện tại sau khi khóa session cơ sở vẫn khớp. Provider plugin có thể ghi đè độ ưu tiên, hành vi hậu tố và chuẩn hóa thread id khi nền tảng của chúng có ngữ nghĩa phân phối thread gốc.
• openclaw/plugin-sdk/thread-bindings-runtime cho vòng đời thread-binding và đăng ký adapter
• openclaw/plugin-sdk/agent-media-payload chỉ khi vẫn cần layout trường payload agent/media legacy
• openclaw/plugin-sdk/telegram-command-config cho việc chuẩn hóa lệnh tùy chỉnh Telegram, validation trùng lặp/xung đột và contract cấu hình lệnh ổn định khi fallback

​

Chính sách mention inbound

• thu thập bằng chứng do plugin sở hữu
• đánh giá chính sách dùng chung

• phát hiện reply-to-bot
• phát hiện quoted-bot
• kiểm tra thread-participation
• loại trừ service/system-message
• cache native của nền tảng cần thiết để chứng minh bot participation

• requireMention
• kết quả mention rõ ràng
• allowlist mention ngầm định
• command bypass
• quyết định skip cuối cùng

1. Tính toán các fact mention cục bộ.
2. Truyền các fact đó vào resolveInboundMentionDecision({ facts, policy }).
3. Dùng decision.effectiveWasMentioned, decision.shouldBypassMention và decision.shouldSkip trong cổng inbound của bạn.

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

​

Hướng dẫn từng bước

{
  "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/

​

Cấu trúc tệp

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

​

Chủ đề nâng cao

​

Bước tiếp theo

• Plugin nhà cung cấp — nếu Plugin của bạn cũng cung cấp mô hình
• Tổng quan SDK — tham chiếu import đường dẫn con đầy đủ
• Kiểm thử SDK — tiện ích kiểm thử và kiểm thử hợp đồng
• Manifest Plugin — schema manifest đầy đủ

​

Liên quan

• Thiết lập Plugin SDK
• Xây dựng Plugin
• Plugin harness tác tử