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 nối - luồng phê duyệt DM
• Ngữ pháp phiên - cách id cuộc trò chuyện riêng theo nhà cung cấp ánh xạ tới cuộc trò chuyện gốc, id luồng và phương án dự phòng cha
• 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
• Gõ Heartbeat - tín hiệu đang gõ/bận tùy chọn cho các đích gửi Heartbeat

​

Phê duyệt và khả năng của kênh

• Phần lõi sở hữu /approve trong cùng cuộc trò chuyện, payload nút phê duyệt dùng chung và cơ chế gử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ị xóa. Đặt các dữ kiện gửi/native/render/auth của phê duyệt trên approvalCapability.
• plugin.auth chỉ dành cho đăng nhập/đăng xuất; phần lõi không còn đọc cá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 sẵn có của auth phê duyệt trong cùng cuộc trò chuyện.
• Nếu kênh của bạn phơi bày các phê duyệt exec native, dùng approvalCapability.getExecInitiatingSurfaceState cho trạng thái bề mặt khởi tạo/native-client khi nó khác với auth phê duyệt trong cùng cuộc trò chuyện. Phần lõi dùng hook riêng cho exec đó để phân biệt enabled với disabled, quyết định liệu 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 native-client. 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 như ẩn các lời nhắc phê duyệt cục bộ trùng lặp hoặc gửi chỉ báo đang nhập trước khi gử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 dữ kiện phê duyệt native do kênh sở hữu. Giữ nó lazy trên các entrypoint kênh nóng bằng createLazyChannelApprovalNativeRuntimeAdapter(...), có thể import module runtime của bạn theo nhu cầu trong khi vẫn cho phép phần 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 phản hồ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 theo 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ì các mặc định cấp cao nhất.
• Nếu một kênh có thể suy luận các danh tính DM ổn định giống chủ sở hữu 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 phần lõi riêng cho phê duyệt.
• Nếu một kênh cần gử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 các dữ kiện transport/presentation. Dùng createChannelExecApprovalProfile, createChannelNativeOriginTargetResolver, createChannelApproverDmTargetResolver, và createApproverRestrictedNativeApprovalCapability từ openclaw/plugin-sdk/approval-runtime. Đặt các dữ kiện riêng của kênh phía sau approvalCapability.nativeRuntime, tốt nhất thông qua createChannelApprovalNativeRuntimeAdapter(...) hoặc createLazyChannelApprovalNativeRuntimeAdapter(...), để phần lõi có thể lắp ráp handler và sở hữu việc lọc yêu cầu, định tuyến, khử 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 tách thành vài seam nhỏ hơn:
• createChannelNativeOriginTargetResolver dùng trình khớp tuyến kênh dùng chung theo mặc định cho các đích { to, accountId, threadId }. Chỉ truyền targetsMatch khi một kênh có quy tắc tương đương riêng theo provider, chẳng hạn như khớp tiền tố timestamp của Slack.
• Truyền normalizeTargetForMatch cho createChannelNativeOriginTargetResolver khi kênh cần chuẩn hóa id provider trước khi trình khớp tuyến mặc định hoặc callback targetsMatch tùy chỉnh chạy, trong khi vẫn giữ nguyên đích gốc để gửi. Chỉ dùng normalizeTarget khi chính đích gửi đã được phân giải cần được chuẩn hóa.
• availability - liệu tài khoản đã được cấu hình hay chưa và liệu một 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ờ/đã giải quyết/hết hạn hoặc hành động cuối cùng
• transport - chuẩn bị đích cộng với gửi/cập nhật/xóa thông báo 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 gử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, đăng ký chúng thông qua openclaw/plugin-sdk/channel-runtime-context. Registry runtime-context chung cho phép phần lõi bootstrap các handler điều khiển bằng capability từ trạng thái khởi động kênh mà không thêm lớp keo wrapper riêng cho phê duyệt.
• Chỉ dùng các API cấp thấp hơn createChannelApprovalHandler hoặc createChannelNativeApprovalRuntime khi seam điều khiển bằng 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 trong đúng phạm vi tài khoản bot, và approvalKind giữ hành vi phê duyệt exec so với plugin sẵn có cho kênh mà không có nhánh hardcode trong phần lõi.
• Phần lõi hiện cũng sở hữu các thông báo định tuyến lại phê duyệt. Plugin kênh không nên gửi thông báo theo sau riêng kiểu “phê duyệt đã đến DM / kênh khác” từ createChannelNativeApprovalRuntime; thay vào đó, hãy phơi bày định tuyến origin + approver-DM chính xác thông qua các helper capability phê duyệt dùng chung và để phần lõi tổng hợp các lần gử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.
• Bảo toàn loại id phê duyệt đã gửi xuyên suốt từ đầu đến cuối. Native client không nên đoán hoặc ghi 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ể cố ý phơi bày các bề mặt native khác nhau. Các ví dụ tích hợp 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 các phê duyệt exec và plugin, trong khi 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à phơi bày 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 setup an toàn cho runtime: adapter patch setup 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-runtime bao gồm seam adapter nhận biết env cho createEnvPatchedAccountSetupAdapter
• openclaw/plugin-sdk/channel-setup bao phủ các builder setup cài đặt tùy chọn cộng với một vài primitive an toàn cho setup: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

• chỉ dùng seam rộng hơn openclaw/plugin-sdk/setup khi bạn cũng cần các helper setup/config 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 đa tài khoản và dự phòng 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-nhận-và-dispatch
• openclaw/plugin-sdk/messaging-targets cho phân tích/khớp đích
• openclaw/plugin-sdk/outbound-media và openclaw/plugin-sdk/outbound-runtime cho tải media cộng với 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 tuyến outbound nê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. Các plugin provider có thể ghi đè độ ưu tiên, hành vi hậu tố và chuẩn hóa id thread khi nền tảng của chúng có ngữ nghĩa gửi thread native.
• openclaw/plugin-sdk/thread-bindings-runtime cho vòng đời thread-binding và đăng ký adapter
• openclaw/plugin-sdk/agent-media-payload chỉ khi layout trường payload agent/media legacy vẫn còn bắt buộc
• openclaw/plugin-sdk/telegram-command-config cho chuẩn hóa lệnh tùy chỉnh Telegram, validation trùng lặp/xung đột và hợp đồng cấu hình lệnh ổn định khi dự phòng

​

Chính sách đề cập 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 trả lời bot
• phát hiện trích dẫn bot
• kiểm tra sự tham gia trong thread
• loại trừ tin nhắn dịch vụ/hệ thống
• cache native của nền tảng cần thiết để chứng minh bot đã tham gia

• requireMention
• kết quả nhắc đến tường minh
• danh sách cho phép nhắc đến ngầm định
• bỏ qua bằng lệnh
• quyết định bỏ qua cuối cùng

1. Tính các dữ kiện nhắc đến cục bộ.
2. Truyền các dữ kiện đó 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

• Provider Plugins - nếu Plugin của bạn cũng cung cấp mô hình
• SDK Overview - tham chiếu import subpath đầy đủ
• SDK Testing - tiện ích kiểm thử và kiểm thử hợp đồng
• Plugin Manifest - schema manifest đầy đủ

​

Liên quan

• Plugin SDK setup
• Building plugins
• Agent harness plugins