Kanal pluginleri oluşturma

​

Kanal Plugin’leri nasıl çalışır

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

​

Onaylar ve kanal yetenekleri

• Çekirdek, aynı sohbet /approve, paylaşılan onay düğmesi yükleri ve genel geri dönüş teslimini sahiplenir.
• Kanal onaya özgü davranışa ihtiyaç duyduğunda kanal Plugin’inde tek bir approvalCapability nesnesini tercih edin.
• ChannelPlugin.approvals kaldırıldı. Onay teslimi/yerel/render/auth olgularını approvalCapability üzerine koyun.
• plugin.auth yalnızca login/logout içindir; çekirdek artık onay auth hook’larını bu nesneden okumaz.
• approvalCapability.authorizeActorAction ve approvalCapability.getActionAvailabilityState kanonik onay-auth yüzeyidir.
• Aynı sohbet onay auth kullanılabilirliği için approvalCapability.getActionAvailabilityState kullanın. Yerel teslim devre dışı olsa bile yapılandırılmış onaylayıcıları /approve için kullanılabilir tutun; bunun yerine teslim/kurulum yönlendirmesi için yerel başlatma-yüzeyi durumunu kullanın.
• Kanalınız yerel exec onaylarını açığa çıkarıyorsa, aynı sohbet onay auth durumundan farklı olduğunda başlatma-yüzeyi/yerel-istemci durumu için approvalCapability.getExecInitiatingSurfaceState kullanın. Çekirdek, bu exec’e özgü hook’u enabled ile disabled ayrımını yapmak, başlatan kanalın yerel exec onaylarını destekleyip desteklemediğine karar vermek ve kanalı yerel-istemci geri dönüş yönlendirmesine dahil etmek için kullanır. createApproverRestrictedNativeApprovalCapability(...) yaygın durum için bunu doldurur.
• Yinelenen yerel onay istemlerini gizlemek veya teslimden önce yazıyor göstergeleri göndermek gibi kanala özgü yük 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 geri dönüş bastırma için kullanın.
• Kanalın sahip olduğu yerel onay olguları için approvalCapability.nativeRuntime kullanın. Bunu sıcak kanal giriş noktalarında createLazyChannelApprovalNativeRuntimeAdapter(...) ile tembel tutun; bu, çekirdeğin onay yaşam döngüsünü bir araya getirmesine hâlâ izin verirken runtime modülünüzü isteğe bağlı içe aktarabilir.
• approvalCapability.render yalnızca bir kanal paylaşılan renderer yerine gerçekten özel onay yüklerine ihtiyaç duyduğunda kullanın.
• Kanal, devre dışı yol yanıtının yerel exec onaylarını etkinleştirmek için gereken kesin yapılandırma düğmelerini açıklamasını istediğinde 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 render etmelidir.
• Plugin onay hatası yönlendirmesinin Plugin onayı rota-yok ve zaman aşımı hataları için gösterilmesi güvenli olduğunda approvalCapability.describePluginApprovalSetup kullanın. createApproverRestrictedNativeApprovalCapability(...) bunu describeExecApprovalSetup üzerinden çıkarımsamaz; aynı yardımcıyı yalnızca Plugin ve exec onayları gerçekten aynı yerel kurulumu kullanıyorsa açıkça geçirin.
• Bir kanal mevcut yapılandırmadan kararlı sahip-benzeri DM kimlikleri çıkarabiliyorsa, onaya özgü çekirdek mantığı eklemeden aynı sohbet /approve komutunu kısıtlamak için openclaw/plugin-sdk/approval-runtime içinden createResolvedApproverActionAuthAdapter kullanın.
• Özel onay auth bilerek yalnızca aynı sohbet geri dönüşüne izin veriyorsa, openclaw/plugin-sdk/approval-auth-runtime içinden markImplicitSameChatApprovalAuthorization({ authorized: true }) döndürün; aksi takdirde çekirdek sonucu açık onaylayıcı yetkilendirmesi olarak ele alır.
• Kanalın sahip olduğu yerel bir callback onayları doğrudan çözümlüyorsa, örtük geri dönüşün hâlâ kanalın normal aktör yetkilendirmesinden geçmesi için çözümlemeden önce isImplicitSameChatApprovalAuthorization(...) kullanın.
• Bir kanal yerel onay teslimine ihtiyaç duyuyorsa, kanal kodunu hedef normalizasyonu artı taşıma/sunum olgularına odaklı tutun. openclaw/plugin-sdk/approval-runtime içinden createChannelExecApprovalProfile, createChannelNativeOriginTargetResolver, createChannelApproverDmTargetResolver ve createApproverRestrictedNativeApprovalCapability kullanın. Kanala özgü olguları, ideal olarak createChannelApprovalNativeRuntimeAdapter(...) veya createLazyChannelApprovalNativeRuntimeAdapter(...) üzerinden approvalCapability.nativeRuntime arkasına koyun; böylece çekirdek handler’ı bir araya getirip istek filtreleme, yönlendirme, tekilleştirme, süre sonu, Gateway aboneliği ve başka-yere-yönlendirildi bildirimlerini sahiplenebilir. nativeRuntime birkaç daha küçük yüzeye ayrılır:
• Bir kanal hem oturum-kökenli yerel teslimi hem de açık onay iletme hedeflerini desteklediğinde openclaw/plugin-sdk/approval-native-runtime içinden createNativeApprovalChannelRouteGates kullanın. Yardımcı, onay yapılandırması seçimini, mode işlemeyi, ajan/oturum filtrelerini, hesap bağlamayı, oturum-hedef eşleştirmeyi ve hedef-listesi eşleştirmeyi merkezileştirirken çağıranlar hâlâ kanal kimliğini, varsayılan iletme modunu, hesap aramayı, taşıma-etkin kontrolünü, hedef normalizasyonunu ve dönüş-kaynağı hedef çözümlemesini sahiplenir. Bunu çekirdek-sahipli kanal ilke varsayılanları oluşturmak için kullanmayın; kanalın belgelenmiş varsayılan modunu açıkça geçirin.
• createChannelNativeOriginTargetResolver, varsayılan olarak { to, accountId, threadId } hedefleri için paylaşılan kanal-rota eşleştiricisini kullanır. Yalnızca bir kanal Slack zaman damgası öneki eşleştirme gibi sağlayıcıya özgü eşdeğerlik kurallarına sahipse targetsMatch geçirin.
• Kanalın, özgün hedefi teslim için korurken varsayılan rota eşleştiricisi veya özel bir targetsMatch callback’i çalışmadan önce sağlayıcı kimliklerini kanonikleştirmesi gerektiğinde createChannelNativeOriginTargetResolver öğesine normalizeTargetForMatch geçirin. normalizeTarget yalnızca çözümlenen teslim hedefinin kendisinin kanonikleştirilmesi gerektiğinde kullanın.
• availability - hesabın yapılandırılıp yapılandırılmadığı 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şleyin
• transport - hedefleri hazırlayın ve yerel onay mesajlarını gönderin/güncelleyin/silin
• interactions - yerel düğmeler veya tepkiler için isteğe bağlı bind/unbind/clear-action hook’ları ve isteğe bağlı bir cancelDelivered hook’u. deliverPending işlem içi veya kalıcı durum kaydettiğinde (örneğin bir tepki hedef deposu) cancelDelivered uygulayın; böylece bir handler durdurması bindPending çalışmadan önce teslimi iptal ederse veya bindPending hiçbir handle döndürmezse bu durum serbest bırakılabilir
• observe - isteğe bağlı teslim tanılama hook’ları
• Kanal istemci, token, Bolt uygulaması veya webhook alıcısı gibi runtime-sahipli nesnelere ihtiyaç duyuyorsa, bunları openclaw/plugin-sdk/channel-runtime-context üzerinden kaydedin. Genel runtime-context kayıt defteri, çekirdeğin onaya özgü wrapper yapıştırıcısı eklemeden kanal başlangıç durumundan yetenek odaklı handler’ları bootstrap etmesini sağlar.
• Daha düşük seviyeli createChannelApprovalHandler veya createChannelNativeApprovalRuntime öğesine yalnızca yetenek odaklı yüzey 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ı kapsamında tutar; approvalKind ise exec ve Plugin onayı davranışını çekirdekte sabit kodlu dallar olmadan kanal için kullanılabilir tutar.
• Çekirdek artık onay yeniden yönlendirme bildirimlerini de sahiplenir. Kanal Plugin’leri createChannelNativeApprovalRuntime içinden kendi “onay DM’lere / başka kanala gitti” takip mesajlarını göndermemelidir; bunun yerine paylaşılan onay yeteneği yardımcıları üzerinden doğru köken + onaylayıcı-DM yönlendirmesini açığa çıkarın ve çekirdeğin başlatan sohbete herhangi bir bildirim göndermeden önce gerçek teslimleri toplamasına izin verin.
• Teslim edilen onay kimliği türünü uçtan uca koruyun. Yerel istemciler exec ve Plugin onayı yönlendirmesini kanal-yerel durumdan tahmin etmemeli veya yeniden yazmamalıdır.
• Farklı onay türleri bilerek farklı yerel yüzeyler açığa çıkarabilir. Mevcut paketli örnekler:
  • Slack, yerel onay yönlendirmesini hem exec hem de Plugin kimlikleri için kullanılabilir tutar.
  • Matrix, auth’un onay türüne göre farklılaşmasına hâlâ izin verirken exec ve Plugin onayları için aynı yerel DM/kanal yönlendirmesini ve tepki UX’ini korur.
• createApproverRestrictedNativeApprovalAdapter bir uyumluluk wrapper’ı olarak hâlâ vardır, ancak yeni kod yetenek oluşturucuyu tercih etmeli ve Plugin üzerinde approvalCapability açığa çıkarmalı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-güvenli kurulum yardımcılarını kapsar: createSetupTranslator, içe-aktarma-güvenli kurulum yama adaptörleri (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), arama-notu çıktısı, promptResolvedAllowFrom, splitSetupEntries ve yetkilendirilmiş setup-proxy oluşturucular
• openclaw/plugin-sdk/setup-runtime, createEnvPatchedAccountSetupAdapter için env-duyarlı adaptör yüzeyini içerir
• openclaw/plugin-sdk/channel-setup, isteğe bağlı-kurulum kurulumu oluşturucularını ve birkaç kurulum-güvenli primitifi kapsar: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

• daha geniş openclaw/plugin-sdk/setup yüzeyini yalnızca moveSingleAccountChannelSectionToDefaultAccount(...) gibi daha ağır paylaşılan kurulum/yapılandırma yardımcılarına da ihtiyaç duyduğunuzda kullanın

• openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution ve çok hesaplı yapılandırma ve varsayılan hesap geri dönüşü için openclaw/plugin-sdk/account-helpers
• gelen rota/zarf ve kaydetme ve gönderme bağlantısı 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
• medya yükleme için openclaw/plugin-sdk/outbound-media ve giden kimlik/gönderme temsilcileri ve yük planlaması için openclaw/plugin-sdk/channel-outbound
• Bir giden rota açık bir replyToId/threadId değerini korumalıysa veya temel oturum anahtarı hâlâ eşleştikten sonra geçerli :thread: oturumunu kurtarmalıysa openclaw/plugin-sdk/channel-core içinden buildThreadAwareOutboundSessionRoute(...). Sağlayıcı Plugin’leri, platformlarında yerel iş parçacığı teslim semantiği olduğunda önceliği, sonek davranışını ve iş parçacığı kimliği normalleştirmesini geçersiz kılabilir.
• iş parçacığı bağlama yaşam döngüsü ve bağdaştırıcı kaydı için openclaw/plugin-sdk/thread-bindings-runtime
• yalnızca eski bir aracı/medya yük alanı düzeni hâlâ gerekli olduğunda openclaw/plugin-sdk/agent-media-payload
• Telegram özel komut normalleştirmesi, yinelenen/çakışan doğrulaması ve geri dönüşü kararlı bir komut yapılandırması sözleşmesi için openclaw/plugin-sdk/telegram-command-config

​

Gelen bahsetme ilkesi

• Plugin’in sahip olduğu kanıt toplama
• paylaşılan ilke değerlendirmesi

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

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

1. Yerel bahsetme olgularını hesaplayın.
2. Bu olguları resolveInboundMentionDecision({ facts, policy }) içine geçirin.
3. Gelen kapınızda 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

​

İzlenecek yol

{
  "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."
    }
  }
}

{
  "id": "acme-chat",
  "kind": "channel",
  "channels": ["acme-chat"],
  "name": "Acme Chat",
  "description": "Acme Chat channel plugin",
  "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 token",
          "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",
    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 - Plugin’iniz modeller de sağlıyorsa
• SDK Overview - tam alt yol içe aktarma referansı
• SDK Testing - test yardımcıları ve sözleşme testleri
• Plugin Manifest - tam manifest şeması

​

İlgili

• Plugin SDK setup
• Building plugins
• Agent harness plugins