Створення Plugin для каналів

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.

​

Як працюють канальні плагіни

• Конфігурацію - визначення облікового запису та майстер налаштування
• Безпеку - політику DM і списки дозволених
• Сполучення - потік схвалення через DM
• Граматику сеансу - те, як ідентифікатори розмов конкретного провайдера зіставляються з базовими чатами, ідентифікаторами потоків і батьківськими резервними варіантами
• Вихідні повідомлення - надсилання тексту, медіа та опитувань на платформу
• Потоки - те, як відповіді прив’язуються до потоків
• Індикатор набору для Heartbeat - необов’язкові сигнали набору/зайнятості для цілей доставки Heartbeat

​

Схвалення та можливості каналу

• Ядро володіє /approve у тому самому чаті, спільними payload-кнопок схвалення та універсальною резервною доставкою.
• Віддавайте перевагу одному об’єкту approvalCapability у channel plugin, коли каналу потрібна поведінка, специфічна для схвалень.
• ChannelPlugin.approvals видалено. Розміщуйте факти про доставку/нативність/render/auth схвалень у approvalCapability.
• plugin.auth призначений лише для login/logout; ядро більше не читає approval auth hooks із цього об’єкта.
• approvalCapability.authorizeActorAction і approvalCapability.getActionAvailabilityState є канонічним інтерфейсом approval-auth.
• Використовуйте approvalCapability.getActionAvailabilityState для доступності approval auth у тому самому чаті.
• Якщо ваш канал надає native exec approvals, використовуйте approvalCapability.getExecInitiatingSurfaceState для стану initiating-surface/native-client, коли він відрізняється від same-chat approval auth. Ядро використовує цей exec-specific hook, щоб розрізняти enabled і disabled, вирішувати, чи initiating channel підтримує native exec approvals, і включати канал до fallback guidance для native-client. createApproverRestrictedNativeApprovalCapability(...) заповнює це для типового випадку.
• Використовуйте outbound.shouldSuppressLocalPayloadPrompt або outbound.beforeDeliverPayload для channel-specific поведінки життєвого циклу payload, наприклад приховування дубльованих локальних approval prompts або надсилання typing indicators перед доставкою.
• Використовуйте approvalCapability.delivery лише для маршрутизації нативних схвалень або пригнічення fallback.
• Використовуйте approvalCapability.nativeRuntime для channel-owned фактів нативного схвалення. Залишайте його lazy на гарячих entrypoints каналу через createLazyChannelApprovalNativeRuntimeAdapter(...), який може імпортувати ваш runtime-модуль на вимогу, водночас дозволяючи ядру зібрати життєвий цикл схвалення.
• Використовуйте approvalCapability.render лише тоді, коли каналу справді потрібні кастомні payload-схвалення замість спільного renderer.
• Використовуйте approvalCapability.describeExecApprovalSetup, коли канал хоче, щоб відповідь disabled-path пояснювала точні config knobs, потрібні для ввімкнення native exec approvals. Hook отримує { channel, channelLabel, accountId }; канали з іменованими обліковими записами мають render шляхи з прив’язкою до account, як-от channels.<channel>.accounts.<id>.execApprovals.*, замість top-level defaults.
• Якщо канал може вивести стабільні owner-like DM identities з наявної конфігурації, використовуйте createResolvedApproverActionAuthAdapter з openclaw/plugin-sdk/approval-runtime, щоб обмежити same-chat /approve без додавання approval-specific логіки в ядро.
• Якщо каналу потрібна доставка нативних схвалень, тримайте код каналу зосередженим на нормалізації target і фактах transport/presentation. Використовуйте createChannelExecApprovalProfile, createChannelNativeOriginTargetResolver, createChannelApproverDmTargetResolver і createApproverRestrictedNativeApprovalCapability з openclaw/plugin-sdk/approval-runtime. Розміщуйте channel-specific факти за approvalCapability.nativeRuntime, бажано через createChannelApprovalNativeRuntimeAdapter(...) або createLazyChannelApprovalNativeRuntimeAdapter(...), щоб ядро могло зібрати handler і володіти фільтрацією запитів, маршрутизацією, dedupe, expiry, gateway subscription і сповіщеннями routed-elsewhere. nativeRuntime поділено на кілька менших інтерфейсів:
• createChannelNativeOriginTargetResolver типово використовує shared channel-route matcher для цілей { to, accountId, threadId }. Передавайте targetsMatch лише коли канал має provider-specific правила еквівалентності, як-от Slack timestamp prefix matching.
• Передавайте normalizeTargetForMatch до createChannelNativeOriginTargetResolver, коли каналу потрібно canonicalize provider ids перед запуском default route matcher або custom targetsMatch callback, зберігаючи original target для доставки. Використовуйте normalizeTarget лише коли сам resolved delivery target має бути canonicalized.
• availability - чи налаштовано account і чи потрібно обробляти request
• presentation - відобразити shared approval view model у pending/resolved/expired native payloads або final actions
• transport - підготувати targets і send/update/delete native approval messages
• interactions - необов’язкові bind/unbind/clear-action hooks для native buttons або reactions
• observe - необов’язкові hooks діагностики доставки
• Якщо каналу потрібні runtime-owned objects, як-от client, token, Bolt app або webhook receiver, реєструйте їх через openclaw/plugin-sdk/channel-runtime-context. Generic runtime-context registry дозволяє ядру bootstrap capability-driven handlers зі startup state каналу без додавання approval-specific wrapper glue.
• Звертайтеся до нижчорівневих createChannelApprovalHandler або createChannelNativeApprovalRuntime лише коли capability-driven інтерфейс ще недостатньо виразний.
• Канали нативних схвалень мають маршрутизувати і accountId, і approvalKind через ці helpers. accountId утримує multi-account approval policy у межах правильного bot account, а approvalKind залишає exec vs plugin approval behavior доступною для каналу без hardcoded branches у ядрі.
• Ядро тепер також володіє approval reroute notices. Channel plugins не повинні надсилати власні follow-up messages “approval went to DMs / another channel” з createChannelNativeApprovalRuntime; натомість надавайте точну origin + approver-DM routing через shared approval capability helpers і дайте ядру агрегувати actual deliveries перед публікацією будь-якого notice назад в initiating chat.
• Зберігайте kind доставленого approval id наскрізно. Native clients не повинні вгадувати або переписувати exec vs plugin approval routing зі стану, локального для каналу.
• Різні approval kinds можуть навмисно надавати різні native surfaces. Поточні bundled examples:
  • Slack зберігає native approval routing доступним і для exec, і для plugin ids.
  • Matrix зберігає ту саму native DM/channel routing і reaction UX для exec та plugin approvals, водночас дозволяючи auth відрізнятися за approval kind.
• createApproverRestrictedNativeApprovalAdapter досі існує як compatibility wrapper, але новий код має віддавати перевагу capability builder і надавати approvalCapability у 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 охоплює runtime-safe setup helpers: import-safe setup patch adapters (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), lookup-note output, promptResolvedAllowFrom, splitSetupEntries і delegated setup-proxy builders
• openclaw/plugin-sdk/setup-runtime включає env-aware adapter seam для createEnvPatchedAccountSetupAdapter
• openclaw/plugin-sdk/channel-setup охоплює optional-install setup builders плюс кілька setup-safe primitives: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

• використовуйте ширший інтерфейс openclaw/plugin-sdk/setup лише коли вам також потрібні важчі shared setup/config helpers, такі як moveSingleAccountChannelSectionToDefaultAccount(...)

• openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution і openclaw/plugin-sdk/account-helpers для multi-account config і default-account fallback
• openclaw/plugin-sdk/inbound-envelope і openclaw/plugin-sdk/inbound-reply-dispatch для inbound route/envelope і record-and-dispatch wiring
• openclaw/plugin-sdk/messaging-targets для target parsing/matching
• openclaw/plugin-sdk/outbound-media і openclaw/plugin-sdk/outbound-runtime для media loading плюс outbound identity/send delegates і payload planning
• buildThreadAwareOutboundSessionRoute(...) з openclaw/plugin-sdk/channel-core, коли outbound route має зберігати explicit replyToId/threadId або відновлювати current :thread: session після того, як base session key усе ще збігається. Provider plugins можуть override precedence, suffix behavior і thread id normalization, коли їхня platform має native thread delivery semantics.
• openclaw/plugin-sdk/thread-bindings-runtime для thread-binding lifecycle і adapter registration
• openclaw/plugin-sdk/agent-media-payload лише коли legacy agent/media payload field layout досі потрібен
• openclaw/plugin-sdk/telegram-command-config для Telegram custom-command normalization, duplicate/conflict validation і fallback-stable command config contract

​

Політика inbound mentions

• plugin-owned evidence gathering
• shared policy evaluation

• reply-to-bot detection
• quoted-bot detection
• thread-participation checks
• service/system-message exclusions
• platform-native caches, потрібні для доведення bot participation

• requireMention
• результат явної згадки
• список дозволених неявних згадок
• обхід командою
• остаточне рішення про пропуск

1. Обчисліть локальні факти згадки.
2. Передайте ці факти в resolveInboundMentionDecision({ facts, policy }).
3. Використовуйте decision.effectiveWasMentioned, decision.shouldBypassMention і decision.shouldSkip у вашому вхідному шлюзі.

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

​

Покроковий огляд

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

​

Структура файлів

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

​

Розширені теми

​

Наступні кроки

• Provider Plugins - якщо ваш Plugin також надає моделі
• Огляд SDK - повна довідка імпортів підшляхів
• Тестування SDK - утиліти тестування та контрактні тести
• Маніфест Plugin - повна схема маніфесту

​

Пов’язано

• Налаштування SDK Plugin
• Створення Plugin
• Plugin агентського каркаса