​

Kanal Eklentileri Oluşturma

​

Kanal eklentileri nasıl çalışır

• Config — hesap çözümleme ve kurulum sihirbazı
• Security — DM politikası ve allowlist’ler
• Pairing — DM onay akışı
• Session grammar — sağlayıcıya özgü konuşma kimliklerinin temel sohbetlere, iş parçacığı kimliklerine ve üst fallback’lerine nasıl eşlendiği
• Outbound — platforma metin, medya ve anket gönderme
• Threading — yanıtların nasıl iş parçacığına bağlandığı

​

Onaylar ve kanal yetenekleri

• Çekirdek aynı sohbette /approve, ortak onay düğmesi payload’ları ve genel fallback teslimini yönetir.
• Kanal onaya özgü davranış gerektiriyorsa, kanal eklentisinde tek bir approvalCapability nesnesi tercih edin.
• ChannelPlugin.approvals kaldırıldı. Onay teslimi/yerel işleme/auth bilgilerini approvalCapability içine koyun.
• plugin.auth yalnızca login/logout içindir; çekirdek artık bu nesneden onay auth hook’larını okumaz.
• approvalCapability.authorizeActorAction ve approvalCapability.getActionAvailabilityState, kanonik onay-auth bağlantı yüzeyidir.
• Aynı sohbette onay auth kullanılabilirliği için approvalCapability.getActionAvailabilityState kullanın.
• Kanalınız yerel exec onayları sunuyorsa, başlatan yüzey/yerel istemci durumu aynı sohbet onay auth’undan farklı olduğunda approvalCapability.getExecInitiatingSurfaceState kullanın. Çekirdek bu exec’e özgü hook’u enabled ile disabled durumunu ayırt etmek, başlatan kanalın yerel exec onaylarını destekleyip desteklemediğine karar vermek ve kanalı yerel istemci fallback rehberliğine dahil etmek için kullanır. createApproverRestrictedNativeApprovalCapability(...) bunu yaygın durum için doldurur.
• Yinelenen yerel onay istemlerini gizlemek veya teslimattan önce yazıyor göstergeleri göndermek gibi kanala özgü payload yaşam döngüsü davranışları için outbound.shouldSuppressLocalPayloadPrompt veya outbound.beforeDeliverPayload kullanın.
• approvalCapability.delivery yalnızca yerel onay yönlendirmesi veya fallback bastırma için kullanılmalıdır.
• approvalCapability.nativeRuntime değerini kanala ait yerel onay bilgileri için kullanın. Çekirdek onay yaşam döngüsünü oluşturabilsin diye bunu sıcak kanal giriş noktalarında createLazyChannelApprovalNativeRuntimeAdapter(...) ile tembel tutun; bu, çalışma zamanı modülünüzü gerektiğinde içe aktarabilir.
• approvalCapability.render yalnızca bir kanal ortak işleyici yerine gerçekten özel onay payload’larına ihtiyaç duyuyorsa kullanılmalıdır.
• Kanal, devre dışı bırakılmış yoldaki yanıtta yerel exec onaylarını etkinleştirmek için gereken tam yapılandırma düğmelerini açıklamak istiyorsa approvalCapability.describeExecApprovalSetup kullanın. Hook { channel, channelLabel, accountId } alır; adlandırılmış hesap kanalları üst düzey varsayılanlar yerine channels.<channel>.accounts.<id>.execApprovals.* gibi hesap kapsamlı yollar göstermelidir.
• Bir kanal mevcut yapılandırmadan kararlı owner benzeri DM kimliklerini çıkarabiliyorsa, onaya özgü çekirdek mantığı eklemeden aynı sohbette /approve erişimini kısıtlamak için openclaw/plugin-sdk/approval-runtime içinden createResolvedApproverActionAuthAdapter kullanın.
• Kanal yerel onay teslimine ihtiyaç duyuyorsa, kanal kodunu hedef normalizasyonu ile taşıma/sunum bilgilerine odaklı tutun. openclaw/plugin-sdk/approval-runtime içinden createChannelExecApprovalProfile, createChannelNativeOriginTargetResolver, createChannelApproverDmTargetResolver ve createApproverRestrictedNativeApprovalCapability kullanın. Kanala özgü bilgileri approvalCapability.nativeRuntime arkasına, ideal olarak createChannelApprovalNativeRuntimeAdapter(...) veya createLazyChannelApprovalNativeRuntimeAdapter(...) üzerinden koyun; böylece çekirdek işleyiciyi birleştirebilir ve istek filtreleme, yönlendirme, tekilleştirme, süre sonu, gateway aboneliği ve başka yere yönlendirildi bildirimlerine sahip olabilir. nativeRuntime birkaç küçük bağlantı yüzeyine ayrılmıştır:
• availability — hesabın yapılandırılmış olup olmadığı ve bir isteğin işlenip işlenmemesi gerektiği
• presentation — ortak onay görünüm modelini bekleyen/çözümlenen/süresi dolan yerel payload’lara veya son eylemlere eşleme
• transport — hedefleri hazırlama ve yerel onay mesajlarını gönderme/güncelleme/silme
• interactions — yerel düğmeler veya tepkiler için isteğe bağlı bind/unbind/clear-action hook’ları
• observe — isteğe bağlı teslim tanılama hook’ları
• Kanalın istemci, token, Bolt uygulaması veya webhook alıcısı gibi çalışma zamanı sahipli nesnelere ihtiyacı varsa, bunları openclaw/plugin-sdk/channel-runtime-context üzerinden kaydedin. Genel runtime-context kayıt defteri, çekirdeğin onaya özgü sarmalayıcı glue eklemeden kanal başlangıç durumundan yetenek odaklı işleyicileri bootstrap etmesini sağlar.
• Yalnızca yetenek odaklı bağlantı yüzeyi henüz yeterince ifade edici değilse daha alt düzey createChannelApprovalHandler veya createChannelNativeApprovalRuntime kullanımına başvurun.
• Yerel onay kanalları, hem accountId hem de approvalKind değerini bu yardımcılar üzerinden yönlendirmelidir. accountId, çok hesaplı onay politikasını doğru bot hesabına kapsamlı tutar; approvalKind ise exec ile eklenti onayı davranışını çekirdekte sabit dallanmalar olmadan kanal için kullanılabilir kılar.
• Çekirdek artık onay yeniden yönlendirme bildirimlerinin de sahibidir. Kanal eklentileri, createChannelNativeApprovalRuntime içinden kendi “onay DM’lere / başka bir kanala gitti” takip mesajlarını göndermemelidir; bunun yerine ortak onay yetenek yardımcıları üzerinden doğru origin + approver-DM yönlendirmesini sunmalı ve çekirdeğin başlatan sohbete herhangi bir bildirim göndermeden önce gerçek teslimleri toplamasına izin vermelidir.
• Teslim edilen onay kimliği türünü uçtan uca koruyun. Yerel istemciler, exec ile eklenti onay yönlendirmesini kanal yerel durumundan tahmin etmemeli veya yeniden yazmamalıdır.
• Farklı onay türleri kasıtlı olarak farklı yerel yüzeyler sunabilir. Mevcut paketlenmiş örnekler:
  • Slack, hem exec hem de eklenti kimlikleri için yerel onay yönlendirmesini kullanılabilir tutar.
  • Matrix, aynı yerel DM/kanal yönlendirmesini ve reaction UX’ini exec ve eklenti onayları için korurken auth’un onay türüne göre farklılaşmasına yine de izin verir.
• createApproverRestrictedNativeApprovalAdapter hâlâ bir uyumluluk sarmalayıcısı olarak vardır, ancak yeni kod capability oluşturucuyu tercih etmeli ve eklentide approvalCapability sunmalıdır.

• 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, runtime-safe kurulum yardımcılarını kapsar: import-safe kurulum yama bağdaştırıcıları (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), lookup-note çıktısı, promptResolvedAllowFrom, splitSetupEntries ve devredilen setup-proxy oluşturucular
• openclaw/plugin-sdk/setup-adapter-runtime, createEnvPatchedAccountSetupAdapter için dar, ortam farkında bağdaştırıcı bağlantı yüzeyidir
• openclaw/plugin-sdk/channel-setup, isteğe bağlı kurulum setup oluşturucularını ve setup-safe birkaç ilkel yapıyı kapsar: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

• yalnızca daha ağır ortak kurulum/config yardımcılarına da ihtiyacınız varsa daha geniş openclaw/plugin-sdk/setup bağlantı yüzeyini kullanın; örneğin moveSingleAccountChannelSectionToDefaultAccount(...)

• çok hesaplı config ve varsayılan hesap fallback’i için openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution ve openclaw/plugin-sdk/account-helpers
• gelen rota/zarf ve record-and-dispatch bağlantısı için openclaw/plugin-sdk/inbound-envelope ve openclaw/plugin-sdk/inbound-reply-dispatch
• hedef ayrıştırma/eşleştirme için openclaw/plugin-sdk/messaging-targets
• medya yükleme ile giden kimlik/gönderim delegeleri için openclaw/plugin-sdk/outbound-media ve openclaw/plugin-sdk/outbound-runtime
• iş parçacığı bağı yaşam döngüsü ve bağdaştırıcı kaydı için openclaw/plugin-sdk/thread-bindings-runtime
• yalnızca eski bir agent/media payload alan düzeni hâlâ gerekliyse openclaw/plugin-sdk/agent-media-payload
• Telegram özel komut normalizasyonu, yinelenen/çakışma doğrulaması ve fallback açısından kararlı komut config sözleşmesi için openclaw/plugin-sdk/telegram-command-config

​

Gelen mention politikası

• eklentiye ait kanıt toplama
• ortak politika değerlendirmesi

• bota yanıt algılama
• bottan alıntı algılama
• iş parçacığına katılım denetimleri
• hizmet/sistem mesajı hariç tutmaları
• bot katılımını kanıtlamak için gereken platform yerel önbellekler

• requireMention
• açık mention sonucu
• örtük mention allowlist’i
• komut bypass’ı
• son atlama kararı

1. Yerel mention bilgilerini hesaplayın.
2. Bu bilgileri resolveInboundMentionDecision({ facts, policy }) içine geçirin.
3. Gelen kapıda decision.effectiveWasMentioned, decision.shouldBypassMention ve decision.shouldSkip kullanı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

​

Adım adım açıklama

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

​

Dosya yapısı

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

​

Gelişmiş konular

​

Sonraki adımlar

• Provider Plugins — eklentiniz model de sağlıyorsa
• SDK Overview — tam alt yol içe aktarma başvurusu
• SDK Testing — test yardımcı programları ve sözleşme testleri
• Plugin Manifest — tam manifest şeması