Membangun plugin kanal

​

Hal yang dimiliki Plugin Anda

• Konfigurasi - resolusi akun dan panduan penyiapan
• Keamanan - kebijakan DM dan daftar izin
• Pemasangan - alur persetujuan DM
• Tata bahasa sesi - cara id percakapan khusus penyedia dipetakan ke obrolan dasar, id utas, dan fallback induk
• Keluar - mengirim teks, media, dan jajak pendapat ke platform
• Penguntaian - cara balasan diuntaikan
• Indikator pengetikan Heartbeat - sinyal mengetik/sibuk opsional untuk target pengiriman Heartbeat

​

Adaptor pesan

​

Ingres masuk (eksperimental)

​

Ingres tahan lama dan deduplikasi pemutaran ulang

​

Kelas transport dan retensi

• Webhook atau pengiriman peristiwa yang dibatasi ack: kirim pengakuan atau kembalikan keberhasilan hanya setelah penambahan tahan lama. Kegagalan penambahan harus membiarkan pengiriman tetap memenuhi syarat untuk dicoba ulang atau menggagalkan batas penerimaan. Kelas ini mencakup Slack, SMS, Zalo, Microsoft Teams, Google Chat, LINE, dan Synology Chat.
• Polling atau pengiriman aliran yang ditunggu: majukan kursor jarak jauh atau kirim ack transport hanya setelah penambahan. Jika tidak ada kursor eksplisit, pertahankan callback penerimaan agar terserialisasi dan ditunggu sehingga kegagalan penambahan tidak dapat membuat perulangan penerimaan berjalan mendahului. Polling Telegram, Signal, dan Tlon menggunakan kelas ini; pengiriman Webhook Telegram mengikuti aturan yang dibatasi ack di atas.
• Soket tanpa pemutaran ulang: IRC, Mattermost, Twitch, dan Zalo Personal tidak dapat meminta platform untuk mengirimkan ulang peristiwa yang telah diterima. Antrean tahan lama mereka melindungi jendela kerusakan proses dan mendukung pemulihan mulai ulang lokal; tombstone penyelesaian hampir tidak berpengaruh terhadap pemutaran ulang platform.

​

Efek samping setidaknya satu kali

​

Kontrak mulai ulang bercakupan akun

​

Indikator pengetikan

​

Parameter sumber media

​

Pembentukan payload native

​

Tata bahasa percakapan sesi

​

Dukungan pengikatan percakapan dalam cakupan akun

​

Persetujuan dan kemampuan saluran

​

Autentikasi persetujuan

• approvalCapability.authorizeActorAction dan approvalCapability.getActionAvailabilityState merupakan seam autentikasi persetujuan kanonis.
• Gunakan getActionAvailabilityState untuk ketersediaan autentikasi persetujuan dalam chat yang sama. Pastikan pemberi persetujuan yang dikonfigurasi tetap tersedia untuk /approve meskipun pengiriman native dinonaktifkan; sebagai gantinya, gunakan status permukaan pemicu native untuk panduan pengiriman/penyiapan.
• Jika channel Anda mengekspos persetujuan eksekusi native, gunakan approvalCapability.getExecInitiatingSurfaceState untuk status permukaan pemicu/klien native ketika status tersebut berbeda dari autentikasi persetujuan dalam chat yang sama. Core menggunakan hook khusus eksekusi tersebut untuk membedakan enabled dengan disabled, menentukan apakah channel pemicu mendukung persetujuan eksekusi native, dan menyertakan channel tersebut dalam panduan fallback klien native. createApproverRestrictedNativeApprovalCapability(...) mengisi bagian ini untuk kasus umum.
• Jika suatu channel dapat menyimpulkan identitas DM stabil yang menyerupai pemilik dari konfigurasi yang ada, gunakan createResolvedApproverActionAuthAdapter dari openclaw/plugin-sdk/approval-runtime untuk membatasi /approve dalam chat yang sama tanpa menambahkan logika core khusus persetujuan.
• Jika autentikasi persetujuan khusus sengaja hanya mengizinkan fallback dalam chat yang sama, kembalikan markImplicitSameChatApprovalAuthorization({ authorized: true }) dari openclaw/plugin-sdk/approval-auth-runtime; jika tidak, core memperlakukan hasilnya sebagai otorisasi eksplisit pemberi persetujuan.
• Jika callback native milik channel menyelesaikan persetujuan secara langsung, gunakan isImplicitSameChatApprovalAuthorization(...) sebelum menyelesaikannya agar fallback implisit tetap melewati otorisasi aktor normal milik channel.

​

Siklus hidup payload dan panduan penyiapan

• Gunakan outbound.shouldSuppressLocalPayloadPrompt atau outbound.beforeDeliverPayload untuk perilaku siklus hidup payload khusus channel, seperti menyembunyikan prompt persetujuan lokal duplikat atau mengirim indikator pengetikan sebelum pengiriman.
• Gunakan approvalCapability.describeExecApprovalSetup ketika channel menginginkan balasan jalur yang dinonaktifkan untuk menjelaskan pengaturan konfigurasi persis yang diperlukan guna mengaktifkan persetujuan eksekusi native. Hook menerima { channel, channelLabel, accountId }; channel dengan akun bernama harus merender jalur dalam cakupan akun seperti channels.<channel>.accounts.<id>.execApprovals.*, bukan default tingkat teratas.
• Gunakan approvalCapability.describePluginApprovalSetup ketika panduan kegagalan persetujuan plugin aman ditampilkan untuk kegagalan persetujuan plugin akibat tidak adanya rute dan batas waktu. createApproverRestrictedNativeApprovalCapability(...) tidak menyimpulkan hal ini dari describeExecApprovalSetup; teruskan helper yang sama secara eksplisit hanya ketika persetujuan plugin dan eksekusi benar-benar menggunakan penyiapan native yang sama.

​

Pengiriman persetujuan native

• availability - apakah akun dikonfigurasi dan apakah suatu permintaan harus ditangani
• presentation - memetakan model tampilan persetujuan bersama menjadi payload native tertunda/terselesaikan/kedaluwarsa atau tindakan akhir
• transport - menyiapkan target serta mengirim/memperbarui/menghapus pesan persetujuan native
• interactions - hook opsional untuk mengikat/melepas ikatan/menghapus tindakan bagi tombol atau reaksi native, ditambah hook cancelDelivered opsional. Implementasikan cancelDelivered ketika deliverPending mendaftarkan status dalam proses atau persisten (seperti penyimpanan target reaksi) agar status tersebut dapat dilepaskan jika penghentian handler membatalkan pengiriman sebelum bindPending dijalankan, atau ketika bindPending tidak mengembalikan handle
• observe - hook diagnostik pengiriman opsional

• Gunakan createNativeApprovalChannelRouteGates dari openclaw/plugin-sdk/approval-native-runtime ketika suatu channel mendukung pengiriman native asal sesi dan target penerusan persetujuan eksplisit. Helper ini memusatkan pemilihan konfigurasi persetujuan, penanganan mode, filter agen/sesi, pengikatan akun, pencocokan target sesi, dan pencocokan daftar target, sementara pemanggil tetap menangani id channel, mode penerusan default, pencarian akun, pemeriksaan bahwa transportasi diaktifkan, normalisasi target, dan resolusi target sumber giliran. Jangan menggunakannya untuk membuat default kebijakan channel milik core; teruskan mode default terdokumentasi milik channel secara eksplisit.
• createChannelNativeOriginTargetResolver menggunakan pencocok rute channel bersama secara default untuk target { to, accountId, threadId }. Teruskan targetsMatch hanya ketika suatu channel memiliki aturan ekuivalensi khusus penyedia, seperti pencocokan awalan stempel waktu Slack. Teruskan normalizeTargetForMatch ketika channel perlu mengkanoniskan id penyedia sebelum pencocok rute default atau callback targetsMatch khusus dijalankan, sambil mempertahankan target asli untuk pengiriman. Gunakan normalizeTarget hanya ketika target pengiriman yang telah diresolusi itu sendiri harus dikanoniskan.
• Jika channel memerlukan objek milik runtime seperti klien, token, aplikasi Bolt, atau penerima Webhook, daftarkan objek tersebut melalui openclaw/plugin-sdk/channel-runtime-context. Registri konteks runtime generik memungkinkan core melakukan bootstrap handler berbasis kapabilitas dari status startup channel tanpa menambahkan kode perekat pembungkus khusus persetujuan.
• Gunakan createChannelApprovalHandler atau createChannelNativeApprovalRuntime tingkat rendah hanya ketika seam berbasis kapabilitas belum cukup ekspresif.
• Channel persetujuan native harus merutekan accountId dan approvalKind melalui helper tersebut. accountId menjaga kebijakan persetujuan multiakun tetap berada dalam cakupan akun bot yang tepat, dan approvalKind menjaga perilaku persetujuan eksekusi dibandingkan plugin tetap tersedia bagi channel tanpa cabang yang di-hardcode dalam core.
• Core juga menangani pemberitahuan perutean ulang persetujuan. Plugin channel tidak boleh mengirim pesan tindak lanjutnya sendiri yang menyatakan “persetujuan dialihkan ke DM / channel lain” dari createChannelNativeApprovalRuntime; sebagai gantinya, ekspos perutean asal + DM pemberi persetujuan secara akurat melalui helper kapabilitas persetujuan bersama dan biarkan core mengagregasi pengiriman aktual sebelum memposting pemberitahuan apa pun kembali ke chat pemicu.
• Pertahankan jenis id persetujuan yang dikirimkan secara menyeluruh. Klien native tidak boleh menebak atau menulis ulang perutean persetujuan eksekusi dibandingkan plugin dari status lokal channel.
• Teruskan approvalKind eksplisit tersebut ke resolveApprovalOverGateway. Ini menggunakan layanan approval.resolve kanonis dan mengembalikan pemenang yang tercatat ketika permukaan lain menjawab lebih dahulu. Input eksplisit resolveMethod yang lebih lama tetap tersedia untuk kontrol berbasis perintah; tindakan native baru tidak boleh menggunakannya atau menyimpulkan jenis dari ID.
• Jenis persetujuan yang berbeda dapat secara sengaja mengekspos permukaan native yang berbeda. Contoh bawaan saat ini: Matrix mempertahankan perutean DM/channel native dan UX reaksi yang sama untuk persetujuan eksekusi dan plugin, sambil tetap memungkinkan autentikasi berbeda menurut jenis persetujuan; Slack mempertahankan perutean persetujuan native tersedia untuk id eksekusi maupun plugin.
• createApproverRestrictedNativeApprovalAdapter masih tersedia sebagai pembungkus kompatibilitas, tetapi kode baru sebaiknya mengutamakan builder kapabilitas dan mengekspos approvalCapability pada plugin.

​

Subjalur runtime persetujuan yang lebih sempit

• 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

​

Subjalur penyiapan

• openclaw/plugin-sdk/setup-runtime mencakup pembantu penyiapan yang aman untuk runtime: createSetupTranslator, adaptor patch penyiapan yang aman untuk impor (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), keluaran catatan pencarian, promptResolvedAllowFrom, splitSetupEntries, dan pembuat proksi penyiapan yang didelegasikan.
• openclaw/plugin-sdk/channel-setup mencakup pembuat penyiapan untuk instalasi opsional beserta beberapa primitif yang aman untuk penyiapan: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled, dan splitSetupEntries.
• Gunakan sambungan openclaw/plugin-sdk/setup yang lebih luas hanya jika Anda juga memerlukan pembantu penyiapan/konfigurasi bersama yang lebih berat, seperti moveSingleAccountChannelSectionToDefaultAccount(...).

​

Subjalur channel sempit lainnya

• openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution, dan openclaw/plugin-sdk/account-helpers untuk konfigurasi multiakun dan fallback akun default
• openclaw/plugin-sdk/inbound-envelope dan openclaw/plugin-sdk/channel-inbound untuk rute/envelope masuk serta pengkabelan pencatatan-dan-pengiriman
• openclaw/plugin-sdk/channel-targets untuk pembantu penguraian target
• openclaw/plugin-sdk/channel-outbound untuk delegasi identitas/pengiriman keluar dan perencanaan payload bertipe
• buildThreadAwareOutboundSessionRoute(...) dari openclaw/plugin-sdk/channel-core saat rute keluar harus mempertahankan replyToId/threadId eksplisit atau memulihkan sesi :thread: saat ini setelah kunci sesi dasar masih cocok. Plugin penyedia dapat menimpa prioritas, perilaku sufiks, dan normalisasi id utas saat platformnya memiliki semantik pengiriman utas native.
• openclaw/plugin-sdk/thread-bindings-runtime untuk siklus hidup pengikatan utas dan pendaftaran adaptor

​

Kebijakan penyebutan masuk

• pengumpulan bukti milik plugin
• evaluasi kebijakan bersama

• deteksi balasan kepada bot
• deteksi bot yang dikutip
• pemeriksaan partisipasi utas
• pengecualian pesan layanan/sistem
• cache native platform yang diperlukan untuk membuktikan partisipasi bot

• requireMention
• hasil penyebutan eksplisit
• daftar izin penyebutan implisit
• pengabaian untuk perintah
• keputusan akhir untuk melewati

1. Hitung fakta penyebutan lokal.
2. Teruskan fakta tersebut ke resolveInboundMentionDecision({ facts, policy }).
3. Gunakan decision.effectiveWasMentioned, decision.shouldBypassMention, dan decision.shouldSkip dalam gerbang masuk Anda.

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;

​

Panduan langkah demi langkah

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

{
  "id": "acme-chat",
  "channels": ["acme-chat"],
  "name": "Acme Chat",
  "description": "Plugin channel Acme Chat",
  "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": "Token bot",
          "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"; // klien API platform Anda

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 wajib diisi");
  return {
    accountId: accountId ?? null,
    token,
    allowFrom: section?.allowFrom ?? [],
    dmPolicy: section?.dmSecurity,
  };
}

export const acmeChatPlugin = createChatChannelPlugin<ResolvedAccount>({
  base: createChannelPluginBase({
    id: "acme-chat",
    // Resolusi/inspeksi akun berada di `config`, bukan `setup`.
    // `setup` mencakup penulisan orientasi awal (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 },
        },
      }),
    },
  }),

  // Keamanan DM: siapa yang dapat mengirim pesan kepada bot
  security: {
    dm: {
      channelKey: "acme-chat",
      resolvePolicy: (account) => account.dmPolicy,
      resolveAllowFrom: (account) => account.allowFrom,
      defaultPolicy: "allowlist",
    },
  },

  // Pemasangan: alur persetujuan untuk kontak DM baru
  pairing: {
    text: {
      idLabel: "Nama pengguna Acme Chat",
      message: "Kirim kode ini untuk memverifikasi identitas Anda:",
      notify: async ({ target, code }) => {
        await acmeChatApi.sendDm(target, `Kode pemasangan: ${code}`);
      },
    },
  },

  // Pengutasan: cara balasan dikirimkan
  threading: { topLevelReplyToMode: "reply" },

  // Keluar: kirim pesan ke 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: "Plugin channel Acme Chat",
  plugin: acmeChatPlugin,
  registerCliMetadata(api) {
    api.registerCli(
      ({ program }) => {
        program
          .command("acme-chat")
          .description("Pengelolaan Acme Chat");
      },
      {
        descriptors: [
          {
            name: "acme-chat",
            description: "Pengelolaan Acme Chat",
            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", // autentikasi yang dikelola plugin (verifikasi tanda tangan sendiri)
    handler: async (req, res) => {
      const event = parseWebhookPayload(req);

      // Handler masuk Anda meneruskan pesan ke OpenClaw.
      // Penghubungan persisnya bergantung pada SDK platform Anda -
      // lihat contoh nyata dalam paket plugin bawaan Microsoft Teams atau Google Chat.
      await handleAcmeChatInbound(api, event);

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

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

describe("plugin acme-chat", () => {
  it("menyelesaikan akun dari konfigurasi", () => {
    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("memeriksa akun tanpa mewujudkan rahasia", () => {
    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("melaporkan konfigurasi yang tidak ada", () => {
    const cfg = { channels: {} } as any;
    const result = acmeChatPlugin.config.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(false);
  });
});

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

​

Struktur file

<bundled-plugin-root>/acme-chat/
├── package.json              # metadata openclaw.channel
├── openclaw.plugin.json      # Manifes dengan skema konfigurasi
├── index.ts                  # defineChannelPluginEntry
├── setup-entry.ts            # defineSetupPluginEntry
├── api.ts                    # Ekspor publik (opsional)
├── runtime-api.ts            # Ekspor runtime internal (opsional)
└── src/
    ├── channel.ts            # ChannelPlugin melalui createChatChannelPlugin
    ├── channel.test.ts       # Pengujian
    ├── client.ts             # Klien API platform
    └── runtime.ts            # Penyimpanan runtime (jika diperlukan)

​

Topik lanjutan

​

Langkah berikutnya

• Plugin Penyedia - jika plugin Anda juga menyediakan model
• Ikhtisar SDK - referensi impor subpath lengkap
• Pengujian SDK - utilitas pengujian dan pengujian kontrak
• Manifes Plugin - skema manifes lengkap

​

Terkait

• Penyiapan SDK Plugin
• Membangun plugin
• Plugin harness agen