Membangun plugin saluran

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.

​

Cara kerja Plugin saluran

• Konfigurasi - resolusi akun dan panduan penyiapan
• Keamanan - kebijakan DM dan daftar izin
• Pemasangan - alur persetujuan DM
• Tata bahasa sesi - bagaimana id percakapan khusus penyedia dipetakan ke chat dasar, id thread, dan fallback induk
• Keluar - mengirim teks, media, dan polling ke platform
• Threading - bagaimana balasan dibuat berurutan
• Pengetikan Heartbeat - sinyal mengetik/sibuk opsional untuk target pengiriman Heartbeat

​

Persetujuan dan kapabilitas saluran

• Inti memiliki /approve dalam chat yang sama, payload tombol persetujuan bersama, dan pengiriman cadangan generik.
• Lebih pilih satu objek approvalCapability pada Plugin kanal saat kanal membutuhkan perilaku khusus persetujuan.
• ChannelPlugin.approvals dihapus. Letakkan fakta pengiriman/asli/render/auth persetujuan pada approvalCapability.
• plugin.auth hanya untuk login/logout; inti tidak lagi membaca hook auth persetujuan dari objek itu.
• approvalCapability.authorizeActorAction dan approvalCapability.getActionAvailabilityState adalah seam auth persetujuan kanonis.
• Gunakan approvalCapability.getActionAvailabilityState untuk ketersediaan auth persetujuan dalam chat yang sama.
• Jika kanal Anda mengekspos persetujuan eksekusi asli, gunakan approvalCapability.getExecInitiatingSurfaceState untuk status permukaan pemicu/klien asli saat berbeda dari auth persetujuan dalam chat yang sama. Inti menggunakan hook khusus eksekusi itu untuk membedakan enabled vs disabled, menentukan apakah kanal pemicu mendukung persetujuan eksekusi asli, dan menyertakan kanal dalam panduan cadangan klien asli. createApproverRestrictedNativeApprovalCapability(...) mengisi ini untuk kasus umum.
• Gunakan outbound.shouldSuppressLocalPayloadPrompt atau outbound.beforeDeliverPayload untuk perilaku siklus hidup payload khusus kanal seperti menyembunyikan prompt persetujuan lokal duplikat atau mengirim indikator mengetik sebelum pengiriman.
• Gunakan approvalCapability.delivery hanya untuk perutean persetujuan asli atau penekanan cadangan.
• Gunakan approvalCapability.nativeRuntime untuk fakta persetujuan asli yang dimiliki kanal. Jaga agar tetap malas pada entrypoint kanal panas dengan createLazyChannelApprovalNativeRuntimeAdapter(...), yang dapat mengimpor modul runtime Anda sesuai kebutuhan sambil tetap memungkinkan inti menyusun siklus hidup persetujuan.
• Gunakan approvalCapability.render hanya saat kanal benar-benar membutuhkan payload persetujuan kustom alih-alih perender bersama.
• Gunakan approvalCapability.describeExecApprovalSetup saat kanal ingin balasan jalur nonaktif menjelaskan knob konfigurasi persis yang diperlukan untuk mengaktifkan persetujuan eksekusi asli. Hook menerima { channel, channelLabel, accountId }; kanal akun bernama harus merender path berlingkup akun seperti channels.<channel>.accounts.<id>.execApprovals.* alih-alih default tingkat atas.
• Jika kanal dapat menyimpulkan identitas DM yang stabil dan mirip pemilik dari konfigurasi yang ada, gunakan createResolvedApproverActionAuthAdapter dari openclaw/plugin-sdk/approval-runtime untuk membatasi /approve dalam chat yang sama tanpa menambahkan logika inti khusus persetujuan.
• Jika kanal membutuhkan pengiriman persetujuan asli, jaga kode kanal tetap berfokus pada normalisasi target serta fakta transport/presentasi. Gunakan createChannelExecApprovalProfile, createChannelNativeOriginTargetResolver, createChannelApproverDmTargetResolver, dan createApproverRestrictedNativeApprovalCapability dari openclaw/plugin-sdk/approval-runtime. Letakkan fakta khusus kanal di balik approvalCapability.nativeRuntime, idealnya melalui createChannelApprovalNativeRuntimeAdapter(...) atau createLazyChannelApprovalNativeRuntimeAdapter(...), agar inti dapat menyusun handler dan memiliki penyaringan permintaan, perutean, deduplikasi, kedaluwarsa, langganan Gateway, dan pemberitahuan dirutekan-ke-tempat-lain. nativeRuntime dipecah menjadi beberapa seam yang lebih kecil:
• createChannelNativeOriginTargetResolver menggunakan pencocok rute kanal bersama secara default untuk target { to, accountId, threadId }. Teruskan targetsMatch hanya saat kanal memiliki aturan ekuivalensi khusus penyedia, seperti pencocokan awalan timestamp Slack.
• Teruskan normalizeTargetForMatch ke createChannelNativeOriginTargetResolver saat kanal perlu mengkanoniskan id penyedia sebelum pencocok rute default atau callback targetsMatch kustom berjalan, sambil mempertahankan target asli untuk pengiriman. Gunakan normalizeTarget hanya saat target pengiriman yang terselesaikan itu sendiri harus dikanoniskan.
• availability - apakah akun dikonfigurasi dan apakah permintaan harus ditangani
• presentation - petakan model tampilan persetujuan bersama ke payload asli tertunda/terselesaikan/kedaluwarsa atau tindakan akhir
• transport - siapkan target serta kirim/perbarui/hapus pesan persetujuan asli
• interactions - hook bind/unbind/clear-action opsional untuk tombol atau reaksi asli
• observe - hook diagnostik pengiriman opsional
• Jika kanal membutuhkan objek milik runtime seperti klien, token, aplikasi Bolt, atau penerima webhook, daftarkan melalui openclaw/plugin-sdk/channel-runtime-context. Registry konteks runtime generik memungkinkan inti melakukan bootstrap handler berbasis kapabilitas dari status startup kanal tanpa menambahkan glue wrapper khusus persetujuan.
• Gunakan createChannelApprovalHandler atau createChannelNativeApprovalRuntime tingkat lebih rendah hanya saat seam berbasis kapabilitas belum cukup ekspresif.
• Kanal persetujuan asli harus merutekan accountId dan approvalKind melalui helper tersebut. accountId menjaga kebijakan persetujuan multi-akun tetap berlingkup ke akun bot yang tepat, dan approvalKind menjaga perilaku persetujuan eksekusi vs Plugin tersedia bagi kanal tanpa cabang hardcode di inti.
• Inti sekarang juga memiliki pemberitahuan perutean ulang persetujuan. Plugin kanal tidak boleh mengirim pesan tindak lanjut mereka sendiri “persetujuan masuk ke DM / kanal lain” dari createChannelNativeApprovalRuntime; sebaliknya, ekspos perutean asal + DM pemberi persetujuan yang akurat melalui helper kapabilitas persetujuan bersama dan biarkan inti mengagregasi pengiriman aktual sebelum memposting pemberitahuan apa pun kembali ke chat pemicu.
• Pertahankan jenis id persetujuan yang dikirim dari ujung ke ujung. Klien asli tidak boleh menebak atau menulis ulang perutean persetujuan eksekusi vs Plugin dari status lokal kanal.
• Jenis persetujuan yang berbeda dapat secara sengaja mengekspos permukaan asli yang berbeda. Contoh bawaan saat ini:
  • Slack menjaga perutean persetujuan asli tersedia untuk id eksekusi dan Plugin.
  • Matrix menjaga perutean DM/kanal asli dan UX reaksi yang sama untuk persetujuan eksekusi dan Plugin, sambil tetap memungkinkan auth berbeda menurut jenis persetujuan.
• createApproverRestrictedNativeApprovalAdapter masih ada sebagai wrapper kompatibilitas, tetapi kode baru sebaiknya memilih pembangun kapabilitas dan mengekspos approvalCapability pada 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 mencakup helper setup yang aman untuk runtime: adapter patch setup yang aman diimpor (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), keluaran catatan lookup, promptResolvedAllowFrom, splitSetupEntries, dan pembangun setup-proxy terdelegasi
• openclaw/plugin-sdk/setup-runtime menyertakan seam adapter sadar-env untuk createEnvPatchedAccountSetupAdapter
• openclaw/plugin-sdk/channel-setup mencakup pembangun setup instalasi opsional ditambah beberapa primitif aman-setup: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

• gunakan seam openclaw/plugin-sdk/setup yang lebih luas hanya saat Anda juga membutuhkan helper setup/konfigurasi bersama yang lebih berat seperti moveSingleAccountChannelSectionToDefaultAccount(...)

• openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution, dan openclaw/plugin-sdk/account-helpers untuk konfigurasi multi-akun dan cadangan akun default
• openclaw/plugin-sdk/inbound-envelope dan openclaw/plugin-sdk/inbound-reply-dispatch untuk rute/envelope inbound dan wiring catat-dan-dispatch
• openclaw/plugin-sdk/messaging-targets untuk parsing/pencocokan target
• openclaw/plugin-sdk/outbound-media dan openclaw/plugin-sdk/outbound-runtime untuk pemuatan media plus delegasi identitas/kirim outbound dan perencanaan payload
• buildThreadAwareOutboundSessionRoute(...) dari openclaw/plugin-sdk/channel-core saat rute outbound harus mempertahankan replyToId/threadId eksplisit atau memulihkan sesi :thread: saat ini setelah kunci sesi dasar masih cocok. Plugin penyedia dapat menimpa presedensi, perilaku sufiks, dan normalisasi id thread saat platform mereka memiliki semantik pengiriman thread asli.
• openclaw/plugin-sdk/thread-bindings-runtime untuk siklus hidup thread-binding dan pendaftaran adapter
• openclaw/plugin-sdk/agent-media-payload hanya saat tata letak field payload agen/media lama masih diperlukan
• openclaw/plugin-sdk/telegram-command-config untuk normalisasi perintah kustom Telegram, validasi duplikat/konflik, dan kontrak konfigurasi perintah yang stabil untuk cadangan

​

Kebijakan mention inbound

• pengumpulan bukti milik Plugin
• evaluasi kebijakan bersama

• deteksi reply-to-bot
• deteksi quoted-bot
• pemeriksaan partisipasi thread
• pengecualian pesan layanan/sistem
• cache asli platform yang diperlukan untuk membuktikan partisipasi bot

• requireMention
• hasil mention eksplisit
• allowlist mention implisit
• bypass perintah
• keputusan skip akhir

1. Hitung fakta mention lokal.
2. Teruskan fakta tersebut ke resolveInboundMentionDecision({ facts, policy }).
3. Gunakan decision.effectiveWasMentioned, decision.shouldBypassMention, dan decision.shouldSkip di gate inbound Anda.

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

​

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

​

Struktur file

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

​

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
• Manifest Plugin - skema manifest lengkap

​

Terkait

• Penyiapan SDK Plugin
• Membangun plugin
• Plugin harness agen