Kanal pluginleri oluşturma

​

Plugininizin sorumlulukları

• Yapılandırma - hesap çözümleme ve kurulum sihirbazı
• Güvenlik - DM politikası ve izin listeleri
• Eşleştirme - DM onay akışı
• Oturum dil bilgisi - sağlayıcıya özgü konuşma kimliklerinin temel sohbetlere, dizi kimliklerine ve üst öğe geri dönüşlerine nasıl eşlendiği
• Giden - platforma metin, medya ve anket gönderme
• Dizileme - yanıtların nasıl dizilendiği
• Heartbeat yazıyor göstergesi - Heartbeat teslimat hedefleri için isteğe bağlı yazıyor/meşgul sinyalleri

​

Mesaj adaptörü

​

Gelen giriş (deneysel)

​

Kalıcı giriş ve yeniden oynatma tekilleştirmesi

​

Aktarım sınıfları ve saklama

• Onay kapılı Webhook veya olay teslimatı: yalnızca kalıcı eklemeden sonra onay verin veya başarı döndürün. Ekleme hatası, teslimatı yeniden denemeye uygun bırakmalı veya alma sınırının başarısız olmasına neden olmalıdır. Bu sınıf Slack, SMS, Zalo, Microsoft Teams, Google Chat, LINE ve Synology Chat’i içerir.
• Beklenen yoklama veya akış teslimatı: uzak imleci ilerletin veya aktarım onayını yalnızca eklemeden sonra gönderin. Açık bir imleç yoksa bir ekleme hatasının alma döngüsünün öne geçmesine izin vermemesi için alma geri çağrısını serileştirilmiş ve beklenen durumda tutun. Telegram yoklaması, Signal ve Tlon bu sınıfı kullanır; Telegram Webhook teslimatı yukarıdaki onay kapılı kurala uyar.
• Yeniden oynatılamayan soketler: IRC, Mattermost, Twitch ve Zalo Personal, platformdan kabul edilen bir olayı yeniden teslim etmesini isteyemez. Kalıcı kuyrukları, süreç çökmesi zaman aralığına karşı koruma sağlar ve yerel yeniden başlatma kurtarmasını destekler; tamamlama mezar taşları platform yeniden oynatmasına karşı neredeyse etkisizdir.

​

En az bir kez yan etkiler

​

Hesap kapsamlı yeniden başlatma sözleşmesi

​

Yazıyor göstergeleri

​

Medya kaynağı parametreleri

​

Yerel yük biçimlendirme

​

Oturum konuşması dil bilgisi

​

Hesap kapsamlı konuşma bağlama desteği

​

Onaylar ve kanal yetenekleri

​

Onay yetkilendirmesi

• approvalCapability.authorizeActorAction ve approvalCapability.getActionAvailabilityState standart onay yetkilendirme bağlantı noktasıdır.
• Aynı sohbet onay yetkilendirmesi kullanılabilirliği için getActionAvailabilityState kullanın. Yerel teslimat devre dışı olsa bile yapılandırılmış onaylayıcıları /approve için kullanılabilir tutun; teslimat/kurulum rehberliği için bunun yerine yerel başlatma yüzeyi durumunu kullanın.
• Kanalınız yerel yürütme onayları sunuyorsa, aynı sohbet onay yetkilendirmesinden farklı olduğunda başlatma yüzeyi/yerel istemci durumu için approvalCapability.getExecInitiatingSurfaceState kullanın. Çekirdek, enabled ile disabled arasında ayrım yapmak, başlatan kanalın yerel yürütme onaylarını destekleyip desteklemediğine karar vermek ve kanalı yerel istemci geri dönüş rehberliğine dâhil etmek için yürütmeye özgü bu kancayı kullanır. createApproverRestrictedNativeApprovalCapability(...), yaygın durum için bunu doldurur.
• Bir kanal mevcut yapılandırmadan kararlı, sahip benzeri DM kimlikleri çıkarabiliyorsa, onaya özgü çekirdek mantığı eklemeden aynı sohbet /approve değerini kısıtlamak için openclaw/plugin-sdk/approval-runtime üzerinden createResolvedApproverActionAuthAdapter kullanın.
• Özel onay yetkilendirmesi kasıtlı olarak yalnızca aynı sohbet geri dönüşüne izin veriyorsa openclaw/plugin-sdk/approval-auth-runtime üzerinden markImplicitSameChatApprovalAuthorization({ authorized: true }) döndürün; aksi takdirde çekirdek sonucu açık onaylayıcı yetkilendirmesi olarak değerlendirir.
• Kanala ait yerel bir geri çağırma onayları doğrudan çözümlüyorsa, örtük geri dönüşün yine de kanalın normal aktör yetkilendirmesinden geçmesi için çözümlemeden önce isImplicitSameChatApprovalAuthorization(...) kullanın.

​

Yük yaşam döngüsü ve kurulum rehberliği

• Yinelenen yerel onay istemlerini gizleme veya teslimattan önce yazıyor göstergeleri gönderme gibi kanala özgü yük yaşam döngüsü davranışları için outbound.shouldSuppressLocalPayloadPrompt ya da outbound.beforeDeliverPayload kullanın.
• Kanal, devre dışı bırakılmış yol yanıtının yerel yürütme onaylarını etkinleştirmek için gereken tam yapılandırma ayarlarını açıklamasını istediğinde approvalCapability.describeExecApprovalSetup kullanın. Kanca { 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ı işlemelidir.
• Plugin onay hatası rehberliğinin, Plugin onayının rota bulunamaması ve zaman aşımı hataları için gösterilmesi güvenli olduğunda approvalCapability.describePluginApprovalSetup kullanın. createApproverRestrictedNativeApprovalCapability(...) bunu describeExecApprovalSetup üzerinden çıkarmaz; aynı yardımcıyı yalnızca Plugin ve yürütme onayları gerçekten aynı yerel kurulumu kullandığında açıkça iletin.

​

Yerel onay teslimatı

• availability - hesabın yapılandırılmış olup olmadığı ve bir isteğin işlenip işlenmeyeceği
• presentation - paylaşılan onay görünüm modelini bekleyen/çözümlenen/süresi dolan yerel yüklere veya son eylemlere eşleme
• transport - hedefleri hazırlama ve yerel onay iletilerini gönderme/güncelleme/silme
• interactions - yerel düğmeler veya tepkiler için isteğe bağlı bağlama/bağ kaldırma/eylem temizleme kancaları ve isteğe bağlı bir cancelDelivered kancası. deliverPending işlem içi veya kalıcı durum (tepki hedefi deposu gibi) kaydediyorsa cancelDelivered uygulayın; böylece bir işleyicinin durdurulması teslimatı bindPending çalışmadan önce iptal ederse ya da bindPending hiçbir tanıtıcı döndürmezse bu durum serbest bırakılabilir
• observe - isteğe bağlı teslimat tanılama kancaları

• Bir kanal hem oturum kaynağından yerel teslimatı hem de açık onay iletme hedeflerini desteklediğinde openclaw/plugin-sdk/approval-native-runtime üzerinden createNativeApprovalChannelRouteGates kullanın. Yardımcı; onay yapılandırması seçimini, mode işlemeyi, aracı/oturum filtrelerini, hesap bağlamayı, oturum-hedef eşleştirmeyi ve hedef listesi eşleştirmeyi merkezîleştirirken çağıranlar kanal kimliği, varsayılan iletme modu, hesap araması, aktarımın etkin olup olmadığı denetimi, hedef normalleştirme ve tur kaynağı hedef çözümlemesinin sahibi olmaya devam eder. Bunu çekirdeğe ait kanal ilkesi varsayılanları oluşturmak için kullanmayın; kanalın belgelenmiş varsayılan modunu açıkça iletin.
• createChannelNativeOriginTargetResolver, { to, accountId, threadId } hedefleri için varsayılan olarak paylaşılan kanal rotası eşleştiricisini kullanır. targetsMatch değerini yalnızca bir kanalın Slack zaman damgası öneki eşleştirmesi gibi sağlayıcıya özgü eşdeğerlik kuralları olduğunda iletin. Kanalın, özgün hedefi teslimat için korurken varsayılan rota eşleştiricisi veya özel bir targetsMatch geri çağırması çalışmadan önce sağlayıcı kimliklerini standartlaştırması gerektiğinde normalizeTargetForMatch iletin. normalizeTarget değerini yalnızca çözümlenen teslimat hedefinin kendisi standartlaştırılacaksa kullanın.
• Kanal istemci, belirteç, Bolt uygulaması veya Webhook alıcısı gibi çalışma zamanına ait nesnelere ihtiyaç duyuyorsa bunları openclaw/plugin-sdk/channel-runtime-context üzerinden kaydedin. Genel çalışma zamanı bağlamı kayıt defteri, çekirdeğin onaya özgü sarmalayıcı bağlantı kodu eklemeden kanal başlangıç durumundan yetenek odaklı işleyicileri önyüklemesini sağlar.
• Daha düşük düzeyli createChannelApprovalHandler veya createChannelNativeApprovalRuntime değerlerine yalnızca yetenek odaklı bağlantı noktası henüz yeterince ifade gücüne sahip olmadığında başvurun.
• Yerel onay kanalları hem accountId hem de approvalKind değerlerini bu yardımcılar üzerinden yönlendirmelidir. accountId, çok hesaplı onay ilkesini doğru bot hesabıyla kapsamlı tutar; approvalKind ise çekirdekte sabit kodlanmış dallar olmadan yürütme ve Plugin onayı davranışını kanal için kullanılabilir tutar.
• Onay yeniden yönlendirme bildirimlerinin sahibi de çekirdektir. Kanal Plugin’leri createChannelNativeApprovalRuntime içinden kendi “onay DM’lere / başka bir kanala gitti” takip iletilerini göndermemelidir; bunun yerine paylaşılan onay yeteneği yardımcıları üzerinden doğru kaynak + onaylayıcı DM yönlendirmesini sunmalı ve başlatan sohbete herhangi bir bildirim göndermeden önce çekirdeğin gerçek teslimatları toplamasına izin vermelidir.
• Teslim edilen onay kimliği türünü uçtan uca koruyun. Yerel istemciler, yürütme ve Plugin onayı yönlendirmesini kanalın yerel durumundan tahmin etmemeli veya yeniden yazmamalıdır.
• Bu açık approvalKind değerini resolveApprovalOverGateway öğesine iletin. Bu, standart approval.resolve hizmetini kullanır ve başka bir yüzey önce yanıt verdiğinde kaydedilen kazananı döndürür. Eski açık resolveMethod girdisi komut destekli denetimler için korunur; yeni yerel eylemler bunu kullanmamalı veya türü bir kimlikten çıkarmamalıdır.
• Farklı onay türleri kasıtlı olarak farklı yerel yüzeyler sunabilir. Geçerli paketlenmiş örnekler: Matrix, yetkilendirmenin onay türüne göre farklılaşmasına yine de izin verirken yürütme ve Plugin onayları için aynı yerel DM/kanal yönlendirmesini ve tepki kullanıcı deneyimini korur; Slack ise yerel onay yönlendirmesini hem yürütme hem de Plugin kimlikleri için kullanılabilir tutar.
• createApproverRestrictedNativeApprovalAdapter hâlâ bir uyumluluk sarmalayıcısı olarak bulunur; ancak yeni kod yetenek oluşturucuyu tercih etmeli ve Plugin üzerinde approvalCapability sunmalıdır.

​

Daha dar onay çalışma zamanı alt yolları

• 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

​

Kurulum alt yolları

• openclaw/plugin-sdk/setup-runtime, çalışma zamanı açısından güvenli kurulum yardımcılarını kapsar: createSetupTranslator, içe aktarımı güvenli kurulum yaması adaptörleri (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), arama notu çıktısı, promptResolvedAllowFrom, splitSetupEntries ve devredilen kurulum proxy’si oluşturucuları.
• openclaw/plugin-sdk/channel-setup, isteğe bağlı yükleme kurulumu oluşturucularının yanı sıra kurulum açısından güvenli birkaç temel öğeyi kapsar: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled ve splitSetupEntries.
• Daha geniş openclaw/plugin-sdk/setup bağlantı noktasını yalnızca moveSingleAccountChannelSectionToDefaultAccount(...) gibi daha ağır paylaşılan kurulum/yapılandırma yardımcılarına da ihtiyacınız olduğunda kullanın.

​

Diğer dar kanal alt yolları

• Çoklu hesap yapılandırması ve varsayılan hesap geri dönüşü 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 kaydetme-dağıtma bağlantıları için openclaw/plugin-sdk/inbound-envelope ve openclaw/plugin-sdk/channel-inbound
• Hedef ayrıştırma yardımcıları için openclaw/plugin-sdk/channel-targets
• Giden kimlik/gönderme temsilcileri ve türü belirlenmiş yük planlaması için openclaw/plugin-sdk/channel-outbound
• Giden bir rotanın açık bir replyToId/threadId değerini koruması veya temel oturum anahtarı hâlâ eşleşirken mevcut :thread: oturumunu kurtarması gerektiğinde openclaw/plugin-sdk/channel-core içindeki buildThreadAwareOutboundSessionRoute(...). Sağlayıcı plugin’leri, platformlarında yerel ileti dizisi teslimi semantiği bulunduğunda önceliği, sonek davranışını ve ileti dizisi kimliği normalleştirmesini geçersiz kılabilir.
• İleti dizisi bağlama yaşam döngüsü ve adaptör kaydı için openclaw/plugin-sdk/thread-bindings-runtime

​

Gelen bahsetme politikası

• plugin’e ait kanıt toplama
• paylaşılan politika değerlendirmesi

• bota yanıt algılama
• alıntılanan botu algılama
• ileti dizisine katılım denetimleri
• hizmet/sistem mesajı hariç tutmaları
• bot katılımını kanıtlamak için gereken platforma özgü önbellekler

• requireMention
• açık bahsetme sonucu
• örtük bahsetme izin listesi
• komut atlaması
• nihai atlama kararı

1. Yerel bahsetme olgularını hesaplayın.
2. Bu olguları resolveInboundMentionDecision({ facts, policy }) içine aktarın.
3. Gelen geçidinizde decision.effectiveWasMentioned, decision.shouldBypassMention ve decision.shouldSkip kullanın.

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;

​

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": "OpenClaw'u Acme Chat'e bağlayın."
    }
  }
}

{
  "id": "acme-chat",
  "channels": ["acme-chat"],
  "name": "Acme Chat",
  "description": "Acme Chat kanal plugin'i",
  "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": "Bot belirteci",
          "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"; // 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",
    // Account resolution/inspection belongs on `config`, not `setup`.
    // `setup` covers onboarding writes (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 },
        },
      }),
    },
  }),

  // 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: {
      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: "Acme Chat kanal plugin'i",
  plugin: acmeChatPlugin,
  registerCliMetadata(api) {
    api.registerCli(
      ({ program }) => {
        program
          .command("acme-chat")
          .description("Acme Chat yönetimi");
      },
      {
        descriptors: [
          {
            name: "acme-chat",
            description: "Acme Chat yönetimi",
            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 tarafından yönetilen kimlik doğrulama (imzaları kendiniz doğrulayın)
    handler: async (req, res) => {
      const event = parseWebhookPayload(req);

      // Gelen ileti işleyiciniz mesajı OpenClaw'a yönlendirir.
      // Tam bağlantı düzeni platform SDK'nıza bağlıdır -
      // gerçek bir örnek için paketlenmiş Microsoft Teams veya Google Chat Plugin paketine bakın.
      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.config.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.config.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.config.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 meta verileri
├── openclaw.plugin.json      # Yapılandırma şemasını içeren bildirim
├── index.ts                  # defineChannelPluginEntry
├── setup-entry.ts            # defineSetupPluginEntry
├── api.ts                    # Genel dışa aktarımlar (isteğe bağlı)
├── runtime-api.ts            # Dahili çalışma ortamı dışa aktarımları (isteğe bağlı)
└── src/
    ├── channel.ts            # createChatChannelPlugin aracılığıyla ChannelPlugin
    ├── channel.test.ts       # Testler
    ├── client.ts             # Platform API istemcisi
    └── runtime.ts            # Çalışma ortamı deposu (gerekirse)

​

İleri düzey konular

​

Sonraki adımlar

• Sağlayıcı Plugin’leri - Plugin’iniz modeller de sağlıyorsa
• SDK’ye genel bakış - alt yol içe aktarımlarının tam başvurusu
• SDK testi - test yardımcı programları ve sözleşme testleri
• Plugin manifesti - tam manifest şeması

​

İlgili

• Plugin SDK kurulumu
• Plugin oluşturma
• Ajan çalıştırma çerçevesi Plugin’leri