​

Створення плагінів каналів

​

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

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

​

Підтвердження та можливості каналів

• Ядру належать /approve у тому самому чаті, спільні payload кнопок підтвердження та загальна резервна доставка.
• Надавайте перевагу одному об’єкту approvalCapability у плагіні каналу, коли каналу потрібна поведінка, специфічна для підтверджень.
• ChannelPlugin.approvals видалено. Розміщуйте факти доставки/нативного відтворення/автентифікації підтверджень у approvalCapability.
• plugin.auth — лише login/logout; ядро більше не читає з цього об’єкта хуки автентифікації підтверджень.
• approvalCapability.authorizeActorAction і approvalCapability.getActionAvailabilityState — канонічний шов автентифікації підтверджень.
• Використовуйте approvalCapability.getActionAvailabilityState для доступності автентифікації підтверджень у тому самому чаті.
• Якщо ваш канал надає нативні підтвердження exec, використовуйте approvalCapability.getExecInitiatingSurfaceState для стану поверхні ініціювання/нативного клієнта, коли він відрізняється від автентифікації підтверджень у тому самому чаті. Ядро використовує цей хук, специфічний для exec, щоб розрізняти enabled і disabled, вирішувати, чи підтримує канал ініціювання нативні підтвердження exec, і включати канал до підказок щодо резервного варіанту для нативного клієнта. createApproverRestrictedNativeApprovalCapability(...) заповнює це для типового випадку.
• Використовуйте outbound.shouldSuppressLocalPayloadPrompt або outbound.beforeDeliverPayload для специфічної для каналу поведінки життєвого циклу payload, наприклад приховування дубльованих локальних підказок підтвердження або надсилання індикаторів набору перед доставкою.
• Використовуйте approvalCapability.delivery лише для маршрутизації нативних підтверджень або придушення резервної доставки.
• Використовуйте approvalCapability.nativeRuntime для фактів нативних підтверджень, що належать каналу. Зберігайте його лінивим у гарячих точках входу каналу за допомогою createLazyChannelApprovalNativeRuntimeAdapter(...), який може імпортувати ваш runtime-модуль на вимогу, водночас дозволяючи ядру збирати життєвий цикл підтверджень.
• Використовуйте approvalCapability.render лише тоді, коли каналу справді потрібні власні payload підтверджень замість спільного рендерера.
• Використовуйте approvalCapability.describeExecApprovalSetup, коли канал хоче, щоб відповідь для вимкненого шляху пояснювала точні параметри конфігурації, потрібні для ввімкнення нативних підтверджень exec. Хук отримує { channel, channelLabel, accountId }; канали з іменованими обліковими записами повинні відтворювати шляхи з областю облікового запису, як-от channels.<channel>.accounts.<id>.execApprovals.*, а не значення верхнього рівня за замовчуванням.
• Якщо канал може виводити стабільні DM-ідентичності, схожі на власника, з наявної конфігурації, використовуйте createResolvedApproverActionAuthAdapter з openclaw/plugin-sdk/approval-runtime, щоб обмежити /approve у тому самому чаті без додавання специфічної для підтверджень логіки ядра.
• Якщо каналу потрібна доставка нативних підтверджень, зосередьте код каналу на нормалізації цілі та фактах транспорту/подання. Використовуйте createChannelExecApprovalProfile, createChannelNativeOriginTargetResolver, createChannelApproverDmTargetResolver і createApproverRestrictedNativeApprovalCapability з openclaw/plugin-sdk/approval-runtime. Розміщуйте специфічні для каналу факти за approvalCapability.nativeRuntime, ідеально через createChannelApprovalNativeRuntimeAdapter(...) або createLazyChannelApprovalNativeRuntimeAdapter(...), щоб ядро могло збирати обробник і володіти фільтрацією запитів, маршрутизацією, дедуплікацією, строком дії, підпискою gateway і сповіщеннями про маршрутизацію в інше місце. nativeRuntime поділено на кілька менших швів:
• availability — чи налаштований обліковий запис і чи слід обробляти запит
• presentation — зіставлення спільної view model підтвердження з нативними payload у станах pending/resolved/expired або фінальними діями
• transport — підготовка цілей і надсилання/оновлення/видалення нативних повідомлень підтвердження
• interactions — необов’язкові хуки bind/unbind/clear-action для нативних кнопок або реакцій
• observe — необов’язкові хуки діагностики доставки
• Якщо каналу потрібні об’єкти, що належать runtime, наприклад клієнт, токен, застосунок Bolt або отримувач webhook, реєструйте їх через openclaw/plugin-sdk/channel-runtime-context. Загальний реєстр runtime-контексту дозволяє ядру завантажувати обробники, керовані можливостями, зі стану запуску каналу без додавання обгорткового glue-коду, специфічного для підтверджень.
• Звертайтеся до нижчорівневих createChannelApprovalHandler або createChannelNativeApprovalRuntime лише тоді, коли шов, керований можливостями, ще недостатньо виразний.
• Канали з нативними підтвердженнями повинні маршрутизувати через ці helper-и і accountId, і approvalKind. accountId зберігає політику підтверджень для кількох облікових записів у правильній області бот-облікового запису, а approvalKind зберігає для каналу доступну поведінку підтверджень exec або плагіна без жорстко закодованих гілок у ядрі.
• Тепер ядру також належать сповіщення про перемаршрутизацію підтверджень. Плагіни каналів не повинні надсилати власні додаткові повідомлення на кшталт “підтвердження перейшло в DM / інший канал” із createChannelNativeApprovalRuntime; натомість надавайте точну маршрутизацію origin + approver-DM через спільні helper-и можливостей підтверджень і дозвольте ядру агрегувати фактичні доставки перед публікацією будь-якого сповіщення назад у чат ініціювання.
• Зберігайте наскрізно тип delivered approval id. Нативні клієнти не повинні вгадувати або переписувати маршрутизацію підтверджень exec чи plugin зі стану, локального для каналу.
• Різні типи підтверджень можуть навмисно відкривати різні нативні поверхні. Поточні вбудовані приклади:
  • Slack зберігає доступною нативну маршрутизацію підтверджень як для exec, так і для plugin id.
  • Matrix зберігає ту саму нативну маршрутизацію DM/каналу та UX реакцій для підтверджень exec і plugin, водночас дозволяючи автентифікації відрізнятися за типом підтвердження.
• createApproverRestrictedNativeApprovalAdapter усе ще існує як обгортка сумісності, але новий код має надавати перевагу побудовнику можливостей і експортувати approvalCapability у плагіні.

• 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 helper-и setup: безпечні для імпорту адаптери patch setup (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), вивід нотаток пошуку, promptResolvedAllowFrom, splitSetupEntries і делеговані побудовники setup-proxy
• openclaw/plugin-sdk/setup-adapter-runtime — це вузький env-aware шов адаптера для createEnvPatchedAccountSetupAdapter
• openclaw/plugin-sdk/channel-setup охоплює побудовники setup з необов’язковим встановленням, а також кілька примітивів, безпечних для setup: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

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

• openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution і openclaw/plugin-sdk/account-helpers для конфігурації кількох облікових записів і резервного варіанта з обліковим записом за замовчуванням
• openclaw/plugin-sdk/inbound-envelope і openclaw/plugin-sdk/inbound-reply-dispatch для маршруту/конверта вхідних повідомлень і зв’язування record-and-dispatch
• openclaw/plugin-sdk/messaging-targets для розбору/зіставлення цілей
• openclaw/plugin-sdk/outbound-media і openclaw/plugin-sdk/outbound-runtime для завантаження медіа та делегатів identity/send для вихідних повідомлень
• openclaw/plugin-sdk/thread-bindings-runtime для життєвого циклу прив’язок потоків і реєстрації адаптерів
• openclaw/plugin-sdk/agent-media-payload лише тоді, коли все ще потрібне застаріле компонування полів payload агента/медіа
• openclaw/plugin-sdk/telegram-command-config для нормалізації користувацьких команд Telegram, валідації дублікатів/конфліктів і стабільного для fallback контракту конфігурації команд

​

Політика вхідних згадок

• збирання доказів, що належить плагіну
• спільна оцінка політики

• виявлення відповіді боту
• виявлення цитати бота
• перевірки участі в потоці
• виключення службових/системних повідомлень
• специфічні для платформи нативні кеші, потрібні для підтвердження участі бота

• 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
├── openclaw.plugin.json      # маніфест зі схемою конфігурації
├── index.ts                  # defineChannelPluginEntry
├── setup-entry.ts            # defineSetupPluginEntry
├── api.ts                    # публічні експорти (необов’язково)
├── runtime-api.ts            # внутрішні runtime-експорти (необов’язково)
└── src/
    ├── channel.ts            # ChannelPlugin через createChatChannelPlugin
    ├── channel.test.ts       # тести
    ├── client.ts             # клієнт API платформи
    └── runtime.ts            # сховище runtime (за потреби)

​

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

​

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

• Плагіни провайдерів — якщо ваш плагін також надає моделі
• Огляд SDK — повний довідник з імпортів за підшляхами
• Тестування SDK — утиліти тестування та контрактні тести
• Маніфест плагіна — повна схема маніфесту