Kanal Plugin'leri oluşturma

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.

​

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, ileti dizisi kimliklerine ve üst öğe geri dönüşlerine nasıl eşlendiği
• Dışa giden - platforma metin, medya ve anket gönderme
• Dizilim - yanıtların nasıl dizilendiği
• 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 payload’ları ve genel geri dönüş teslimatını sahiplenir.
• Kanal onaya özgü davranışa ihtiyaç duyduğunda, kanal Plugin’i üzerinde tek bir approvalCapability nesnesini tercih edin.
• ChannelPlugin.approvals kaldırıldı. Onay teslimatı/native/render/auth bilgilerini approvalCapability üzerine koyun.
• plugin.auth yalnızca oturum açma/oturum kapatmadır; çekirdek artık onay auth hook’larını bu nesneden okumaz.
• approvalCapability.authorizeActorAction ve approvalCapability.getActionAvailabilityState, kanonik onay-auth arayüzüdür.
• Aynı sohbet onay auth kullanılabilirliği için approvalCapability.getActionAvailabilityState kullanın.
• Kanalınız native exec onaylarını açığa çıkarıyorsa, başlatan yüzey/native istemci durumu aynı sohbet onay auth’tan farklı olduğunda approvalCapability.getExecInitiatingSurfaceState kullanın. Çekirdek bu exec’e özgü hook’u enabled ile disabled durumlarını ayırt etmek, başlatan kanalın native exec onaylarını destekleyip desteklemediğine karar vermek ve kanalı native istemci geri dönüş rehberliğine dahil etmek için kullanır. createApproverRestrictedNativeApprovalCapability(...) yaygın durum için bunu doldurur.
• Yinelenen yerel onay istemlerini gizleme veya teslimattan önce yazıyor göstergeleri gönderme gibi kanala özgü payload yaşam döngüsü davranışları için outbound.shouldSuppressLocalPayloadPrompt veya outbound.beforeDeliverPayload kullanın.
• approvalCapability.delivery yalnızca native onay yönlendirmesi veya geri dönüş bastırma için kullanın.
• Kanalın sahip olduğu native onay bilgileri 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 yine de izin verirken runtime modülünüzü gerektiğinde import edebilir.
• approvalCapability.render yalnızca bir kanal paylaşılan renderer yerine gerçekten özel onay payload’larına ihtiyaç duyduğunda kullanın.
• Kanal, devre dışı yol yanıtının native exec onaylarını etkinleştirmek için gereken tam config 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.
• Bir kanal mevcut config’ten kararlı sahip benzeri DM kimlikleri çıkarabiliyorsa, onaya özgü çekirdek mantığı eklemeden aynı sohbet /approve kısıtlaması için openclaw/plugin-sdk/approval-runtime içinden createResolvedApproverActionAuthAdapter kullanın.
• Bir kanal native onay teslimatına 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, ideal olarak createChannelApprovalNativeRuntimeAdapter(...) veya createLazyChannelApprovalNativeRuntimeAdapter(...) aracılığıyla approvalCapability.nativeRuntime arkasına koyun; böylece çekirdek handler’ı bir araya getirip istek filtreleme, yönlendirme, dedupe, süre dolumu, Gateway aboneliği ve başka yere yönlendirildi bildirimlerini sahiplenebilir. nativeRuntime birkaç daha küçük arayüze bölünmüştür:
• createChannelNativeOriginTargetResolver, { to, accountId, threadId } hedefleri için varsayılan olarak paylaşılan kanal-route eşleştiricisini kullanır. targetsMatch parametresini yalnızca kanalın Slack timestamp öneki eşleştirme gibi sağlayıcıya özgü eşdeğerlik kuralları olduğunda geçirin.
• Kanal, teslimat için özgün hedefi korurken varsayılan route eşleştiricisi veya özel bir targetsMatch callback’i çalışmadan önce sağlayıcı id’lerini kanonik hale getirmeye ihtiyaç duyduğunda createChannelNativeOriginTargetResolver öğesine normalizeTargetForMatch geçirin. normalizeTarget öğesini yalnızca çözümlenen teslimat hedefinin kendisi kanonik hale getirilmeliyse kullanın.
• availability - hesabın yapılandırılıp yapılandırılmadığı ve bir isteğin işlenip işlenmemesi gerektiği
• presentation - paylaşılan onay view model’ini bekleyen/çözümlenen/süresi dolan native payload’lara veya son eylemlere eşler
• transport - hedefleri hazırlar ve native onay mesajlarını gönderir/günceller/siler
• interactions - native düğmeler veya tepkiler için isteğe bağlı bind/unbind/clear-action hook’ları
• observe - isteğe bağlı teslimat tanılama hook’ları
• Kanal client, token, Bolt app veya Webhook alıcısı gibi runtime’ın sahip olduğu nesnelere ihtiyaç duyuyorsa, bunları openclaw/plugin-sdk/channel-runtime-context üzerinden kaydedin. Genel runtime-context registry, çekirdeğin onaya özgü wrapper glue eklemeden kanal başlatma durumundan capability odaklı handler’ları bootstrap etmesine olanak tanır.
• Daha düşük seviyeli createChannelApprovalHandler veya createChannelNativeApprovalRuntime öğelerine yalnızca capability odaklı arayüz henüz yeterince ifade gücüne sahip olmadığında başvurun.
• Native onay kanalları hem accountId hem de approvalKind değerlerini bu yardımcılar üzerinden yönlendirmelidir. accountId, çok hesaplı onay politikasını doğru bot hesabına kapsamlı tutar; approvalKind ise çekirdekte sabit kodlu dallar olmadan exec ve Plugin onay davranışını 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 bir kanala gitti” takip mesajlarını göndermemelidir; bunun yerine paylaşılan onay capability yardımcıları üzerinden doğru origin + approver-DM yönlendirmesini açığa çıkarın ve başlatan sohbete herhangi bir bildirim göndermeden önce çekirdeğin gerçek teslimatları toplamasına izin verin.
• Teslim edilen onay id türünü uçtan uca koruyun. Native istemciler kanal-yerel durumdan exec ile Plugin onay yönlendirmesini tahmin etmemeli veya yeniden yazmamalıdır.
• Farklı onay türleri kasıtlı olarak farklı native yüzeyler açığa çıkarabilir. Güncel paketlenmiş örnekler:
  • Slack, native onay yönlendirmesini hem exec hem de Plugin id’leri için kullanılabilir tutar.
  • Matrix, auth’un onay türüne göre farklılaşmasına yine de izin verirken exec ve Plugin onayları için aynı native DM/kanal yönlendirmesini ve tepki UX’ini tutar.
• createApproverRestrictedNativeApprovalAdapter hâlâ uyumluluk wrapper’ı olarak vardır, ancak yeni kod capability builder’ı 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 açısından güvenli setup yardımcılarını kapsar: import açısından güvenli setup patch adapter’ları (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), lookup-note çıktısı, promptResolvedAllowFrom, splitSetupEntries ve devredilmiş setup-proxy builder’ları
• openclaw/plugin-sdk/setup-runtime, createEnvPatchedAccountSetupAdapter için env-aware adapter arayüzünü içerir
• openclaw/plugin-sdk/channel-setup, optional-install setup builder’larını ve birkaç setup açısından güvenli primitive’i kapsar: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

• daha geniş openclaw/plugin-sdk/setup arayüzünü yalnızca moveSingleAccountChannelSectionToDefaultAccount(...) gibi daha ağır paylaşılan setup/config yardımcılarına da ihtiyaç duyduğunuzda kullanın

• çok hesaplı config 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
• inbound route/envelope ve record-and-dispatch bağlantıları 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 outbound kimlik/send delegate’leri ve payload planlama için openclaw/plugin-sdk/outbound-media ve openclaw/plugin-sdk/outbound-runtime
• outbound route açık bir replyToId/threadId değerini korumalıysa veya temel session key hâlâ eşleştiğinde mevcut :thread: session’ını geri kazanmalıysa openclaw/plugin-sdk/channel-core içinden buildThreadAwareOutboundSessionRoute(...). Sağlayıcı Plugin’leri, platformlarında native thread teslim semantikleri olduğunda önceliği, sonek davranışını ve thread id normalizasyonunu geçersiz kılabilir.
• thread-binding yaşam döngüsü ve adapter kaydı için openclaw/plugin-sdk/thread-bindings-runtime
• yalnızca eski agent/media payload alan yerleşimi hâlâ gerekliyse openclaw/plugin-sdk/agent-media-payload
• Telegram özel komut normalizasyonu, yinelenen/çakışan doğrulama ve geri dönüşte kararlı komut config sözleşmesi için openclaw/plugin-sdk/telegram-command-config

​

Inbound mention policy

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

• reply-to-bot algılama
• quoted-bot algılama
• thread-participation kontrolleri
• service/system-message hariç tutmaları
• bot katılımını kanıtlamak için gereken platform-native cache’ler

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

1. Yerel mention bilgilerini hesaplayın.
2. Bu bilgileri 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

​

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

• Sağlayıcı Plugin’leri - Plugin’iniz modeller de sağlıyorsa
• SDK Genel Bakış - tam alt yol içe aktarma referansı
• SDK Test Etme - test yardımcı programları ve sözleşme testleri
• Plugin Manifesti - tam manifest şeması

​

İlgili

• Plugin SDK kurulumu
• Plugin oluşturma
• Aracı harness Plugin’leri