Создание Plugin для каналов

​

Как работают канальные Plugins

• Конфигурация - разрешение аккаунта и мастер настройки
• Безопасность - политика личных сообщений и списки разрешений
• Сопряжение - поток подтверждения в личных сообщениях
• Грамматика сессий - как идентификаторы бесед, специфичные для провайдера, сопоставляются с базовыми чатами, идентификаторами цепочек и родительскими fallback-вариантами
• Исходящие сообщения - отправка текста, медиа и опросов на платформу
• Цепочки - как ответы объединяются в цепочки
• Heartbeat typing - необязательные индикаторы набора/занятости для целей доставки Heartbeat

​

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

• Ядро владеет /approve в том же чате, общими payload утверждений для кнопок и универсальной fallback-доставкой.
• Предпочитайте один объект approvalCapability в канальном Plugin, когда каналу требуется поведение, специфичное для утверждений.
• ChannelPlugin.approvals удален. Размещайте факты доставки/нативного отображения/render/auth для утверждений в approvalCapability.
• plugin.auth предназначен только для входа/выхода; ядро больше не читает auth-хуки утверждений из этого объекта.
• approvalCapability.authorizeActorAction и approvalCapability.getActionAvailabilityState являются каноничным seam для auth утверждений.
• Используйте approvalCapability.getActionAvailabilityState для доступности auth утверждений в том же чате.
• Если ваш канал предоставляет нативные утверждения exec, используйте approvalCapability.getExecInitiatingSurfaceState для состояния инициирующей поверхности/нативного клиента, когда оно отличается от auth утверждений в том же чате. Ядро использует этот exec-специфичный хук, чтобы различать enabled и disabled, решать, поддерживает ли инициирующий канал нативные утверждения exec, и включать канал в подсказки fallback для нативного клиента. createApproverRestrictedNativeApprovalCapability(...) заполняет это для обычного случая.
• Используйте outbound.shouldSuppressLocalPayloadPrompt или outbound.beforeDeliverPayload для поведения жизненного цикла payload, специфичного для канала, например скрытия дублирующихся локальных запросов утверждения или отправки индикаторов набора перед доставкой.
• Используйте approvalCapability.delivery только для нативной маршрутизации утверждений или подавления fallback.
• Используйте approvalCapability.nativeRuntime для принадлежащих каналу нативных фактов утверждений. Оставляйте его ленивым на горячих entrypoint канала с помощью createLazyChannelApprovalNativeRuntimeAdapter(...), который может импортировать ваш runtime-модуль по требованию, при этом позволяя ядру собирать жизненный цикл утверждения.
• Используйте approvalCapability.render только когда каналу действительно нужны пользовательские payload утверждений вместо общего renderer.
• Используйте approvalCapability.describeExecApprovalSetup, когда канал хочет, чтобы ответ для отключенного пути объяснял точные параметры конфигурации, необходимые для включения нативных утверждений exec. Хук получает { channel, channelLabel, accountId }; каналы с именованными аккаунтами должны отображать пути в области аккаунта, например channels.<channel>.accounts.<id>.execApprovals.*, вместо верхнеуровневых значений по умолчанию.
• Если канал может вывести стабильные DM-идентичности, похожие на владельцев, из существующей конфигурации, используйте createResolvedApproverActionAuthAdapter из openclaw/plugin-sdk/approval-runtime, чтобы ограничить /approve в том же чате без добавления логики ядра, специфичной для утверждений.
• Если пользовательский auth утверждений намеренно разрешает только same-chat fallback, возвращайте markImplicitSameChatApprovalAuthorization({ authorized: true }) из openclaw/plugin-sdk/approval-auth-runtime; иначе ядро трактует результат как явную авторизацию утверждающего.
• Если принадлежащий каналу нативный callback напрямую разрешает утверждения, используйте isImplicitSameChatApprovalAuthorization(...) перед разрешением, чтобы неявный fallback все равно проходил через обычную авторизацию actor канала.
• Если каналу нужна нативная доставка утверждений, держите код канала сфокусированным на нормализации target и фактах транспорта/представления. Используйте createChannelExecApprovalProfile, createChannelNativeOriginTargetResolver, createChannelApproverDmTargetResolver и createApproverRestrictedNativeApprovalCapability из openclaw/plugin-sdk/approval-runtime. Помещайте факты, специфичные для канала, за approvalCapability.nativeRuntime, в идеале через createChannelApprovalNativeRuntimeAdapter(...) или createLazyChannelApprovalNativeRuntimeAdapter(...), чтобы ядро могло собрать handler и владеть фильтрацией запросов, маршрутизацией, дедупликацией, истечением срока, подпиской Gateway и уведомлениями о маршрутизации в другое место. nativeRuntime разделен на несколько меньших seams:
• Используйте createNativeApprovalChannelRouteGates из openclaw/plugin-sdk/approval-native-runtime, когда канал поддерживает и нативную доставку из session-origin, и явные цели пересылки утверждений. Helper централизует выбор конфигурации утверждений, обработку mode, фильтры agent/session, привязку аккаунта, сопоставление session-target и сопоставление списка targets, при этом вызывающие стороны по-прежнему владеют id канала, режимом пересылки по умолчанию, lookup аккаунта, проверкой включенного транспорта, нормализацией target и разрешением turn-source target. Не используйте его для создания принадлежащих ядру политик канала по умолчанию; передавайте документированный режим по умолчанию канала явно.
• createChannelNativeOriginTargetResolver по умолчанию использует общий matcher маршрутов канала для targets { to, accountId, threadId }. Передавайте targetsMatch только когда у канала есть правила эквивалентности, специфичные для provider, например сопоставление префикса timestamp в Slack.
• Передавайте normalizeTargetForMatch в createChannelNativeOriginTargetResolver, когда каналу нужно канонизировать provider ids перед запуском стандартного matcher маршрутов или пользовательского callback targetsMatch, сохраняя исходный target для доставки. Используйте normalizeTarget только когда сам разрешенный target доставки должен быть канонизирован.
• availability - настроен ли аккаунт и должен ли запрос обрабатываться
• presentation - отображение общей view model утверждения в ожидающие/разрешенные/истекшие нативные payload или финальные действия
• transport - подготовка targets и отправка/обновление/удаление нативных сообщений утверждения
• interactions - необязательные хуки bind/unbind/clear-action для нативных кнопок или реакций, плюс необязательный хук cancelDelivered. Реализуйте cancelDelivered, когда deliverPending регистрирует внутрипроцессное или постоянное состояние (например, хранилище target реакций), чтобы это состояние можно было освободить, если остановка handler отменяет доставку до запуска bindPending или когда bindPending не возвращает handle
• observe - необязательные хуки диагностики доставки
• Если каналу нужны runtime-объекты, такие как client, token, Bolt app или webhook receiver, регистрируйте их через openclaw/plugin-sdk/channel-runtime-context. Универсальный registry runtime-context позволяет ядру bootstrap-ить handlers на основе capabilities из startup-состояния канала без добавления wrapper-glue, специфичного для утверждений.
• Обращайтесь к более низкоуровневым createChannelApprovalHandler или createChannelNativeApprovalRuntime только когда seam на основе capability пока недостаточно выразителен.
• Нативные каналы утверждений должны маршрутизировать и accountId, и approvalKind через эти helpers. accountId удерживает политику утверждений для нескольких аккаунтов в области правильного bot account, а approvalKind сохраняет доступность поведения утверждений exec и Plugin для канала без захардкоженных ветвлений в ядре.
• Теперь ядро также владеет уведомлениями о перемаршрутизации утверждений. Канальные Plugins не должны отправлять собственные follow-up сообщения “утверждение ушло в DM / другой канал” из createChannelNativeApprovalRuntime; вместо этого раскрывайте точную маршрутизацию origin + approver-DM через общие helpers capability утверждений и позволяйте ядру агрегировать фактические доставки перед публикацией любого уведомления обратно в инициирующий чат.
• Сохраняйте kind доставленного approval id сквозным образом. Нативные клиенты не должны угадывать или переписывать маршрутизацию утверждений exec и Plugin из локального состояния канала.
• Разные kinds утверждений могут намеренно предоставлять разные нативные поверхности. Текущие встроенные примеры:
  • Slack сохраняет нативную маршрутизацию утверждений доступной и для exec, и для Plugin ids.
  • Matrix сохраняет одинаковую нативную маршрутизацию DM/канала и UX реакций для утверждений exec и Plugin, при этом все еще позволяя auth отличаться по kind утверждения.
• createApproverRestrictedNativeApprovalAdapter все еще существует как wrapper совместимости, но новый код должен предпочитать builder capability и раскрывать 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 helpers setup: createSetupTranslator, import-safe setup patch adapters (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), вывод lookup-note, promptResolvedAllowFrom, splitSetupEntries и делегированные builders setup-proxy
• openclaw/plugin-sdk/setup-runtime включает env-aware adapter seam для createEnvPatchedAccountSetupAdapter
• openclaw/plugin-sdk/channel-setup покрывает builders setup для optional-install плюс несколько setup-safe primitives: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

• используйте более широкий seam openclaw/plugin-sdk/setup только когда вам также нужны более тяжелые общие helpers 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/channel-inbound для входящего маршрута/конверта и связки записи и диспетчеризации
• openclaw/plugin-sdk/channel-targets для вспомогательных функций разбора целей
• openclaw/plugin-sdk/outbound-media для загрузки медиа и openclaw/plugin-sdk/channel-outbound для делегатов исходящей идентификации/отправки и планирования полезной нагрузки
• buildThreadAwareOutboundSessionRoute(...) из openclaw/plugin-sdk/channel-core, когда исходящий маршрут должен сохранить явный replyToId/threadId или восстановить текущую сессию :thread: после того, как базовый ключ сессии все еще совпадает. Provider plugins могут переопределять приоритет, поведение суффиксов и нормализацию идентификатора треда, когда у их платформы есть нативная семантика доставки в треды.
• openclaw/plugin-sdk/thread-bindings-runtime для жизненного цикла привязок тредов и регистрации адаптера
• openclaw/plugin-sdk/agent-media-payload только когда все еще требуется устаревшая структура полей полезной нагрузки агент/медиа
• openclaw/plugin-sdk/telegram-command-config для нормализации пользовательских команд Telegram, проверки дубликатов/конфликтов и контракта конфигурации команд со стабильным откатом

​

Политика входящих упоминаний

• сбор доказательств, принадлежащий Plugin
• оценка общей политики

• обнаружение ответа боту
• обнаружение цитирования бота
• проверки участия в треде
• исключения служебных/системных сообщений
• платформенно-нативные кэши, нужные для подтверждения участия бота

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

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
• Создание Plugins
• Plugins harness агента