Создание плагинов каналов

​

За что отвечает ваш плагин

• Конфигурация — определение учётной записи и мастер настройки
• Безопасность — политика личных сообщений и списки разрешённых отправителей
• Сопряжение — процесс одобрения личных сообщений
• Грамматика сессий — сопоставление идентификаторов бесед, специфичных для провайдера, с базовыми чатами, идентификаторами веток и резервными родительскими контекстами
• Исходящие сообщения — отправка текста, медиафайлов и опросов на платформу
• Ветвление — распределение ответов по веткам
• Индикатор набора для Heartbeat — необязательные сигналы набора текста или занятости для целей доставки Heartbeat

​

Адаптер сообщений

​

Приём входящих сообщений (экспериментальная возможность)

​

Индикаторы набора текста

​

Параметры источников медиафайлов

​

Формирование нативной полезной нагрузки

​

Грамматика бесед сессии

​

Поддержка привязки бесед в рамках учётной записи

​

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

​

Авторизация одобрений

• approvalCapability.authorizeActorAction и approvalCapability.getActionAvailabilityState являются канонической точкой расширения для авторизации одобрений.
• Используйте getActionAvailabilityState для доступности авторизации одобрений в том же чате. Сохраняйте доступность настроенных одобряющих лиц для /approve, даже когда нативная доставка отключена; вместо этого используйте состояние нативной инициирующей поверхности для рекомендаций по доставке и настройке.
• Если канал предоставляет нативные одобрения выполнения, используйте approvalCapability.getExecInitiatingSurfaceState для состояния инициирующей поверхности или нативного клиента, если оно отличается от авторизации одобрений в том же чате. Ядро использует эту специфичную для выполнения точку расширения, чтобы различать enabled и disabled, определять, поддерживает ли инициирующий канал нативные одобрения выполнения, и включать канал в рекомендации по резервному использованию нативного клиента. createApproverRestrictedNativeApprovalCapability(...) заполняет это значение для типичного случая.
• Если канал может вывести стабильные идентичности личных сообщений, подобные владельцам, из существующей конфигурации, используйте createResolvedApproverActionAuthAdapter из openclaw/plugin-sdk/approval-runtime, чтобы ограничить /approve в том же чате, не добавляя в ядро специальную логику одобрений.
• Если пользовательская авторизация одобрений намеренно разрешает только резервный вариант в том же чате, верните markImplicitSameChatApprovalAuthorization({ authorized: true }) из openclaw/plugin-sdk/approval-auth-runtime; в противном случае ядро считает результат явной авторизацией одобряющего лица.
• Если принадлежащий каналу нативный обратный вызов разрешает одобрения напрямую, используйте isImplicitSameChatApprovalAuthorization(...) перед разрешением, чтобы неявный резервный вариант всё равно проходил через обычную авторизацию участников канала.

​

Жизненный цикл полезной нагрузки и рекомендации по настройке

• Используйте outbound.shouldSuppressLocalPayloadPrompt или outbound.beforeDeliverPayload для специфичного для канала поведения жизненного цикла полезной нагрузки, например скрытия дублирующихся локальных запросов одобрения или отправки индикаторов набора текста перед доставкой.
• Используйте approvalCapability.describeExecApprovalSetup, когда канал должен объяснить в ответе для отключённого пути, какие именно параметры конфигурации необходимы для включения нативных одобрений выполнения. Точка расширения получает { channel, channelLabel, accountId }; каналы с именованными учётными записями должны отображать пути в рамках учётной записи, например channels.<channel>.accounts.<id>.execApprovals.*, вместо значений верхнего уровня по умолчанию.
• Используйте approvalCapability.describePluginApprovalSetup, когда рекомендации при сбое одобрения плагина можно безопасно показывать при отсутствии маршрута и истечении времени ожидания одобрения плагина. createApproverRestrictedNativeApprovalCapability(...) не выводит это из describeExecApprovalSetup; передавайте тот же вспомогательный компонент явно, только если одобрения плагина и выполнения действительно используют одну и ту же нативную настройку.

​

Нативная доставка одобрений

• availability — настроена ли учётная запись и следует ли обрабатывать запрос
• presentation — преобразование общей модели представления подтверждения в ожидающие, разрешённые или просроченные нативные полезные нагрузки либо итоговые действия
• transport — подготовка целей, а также отправка, обновление и удаление нативных сообщений подтверждения
• interactions — необязательные хуки привязки, отвязки и очистки действий для нативных кнопок или реакций, а также необязательный хук cancelDelivered. Реализуйте cancelDelivered, когда deliverPending регистрирует внутрипроцессное или постоянное состояние (например, хранилище целей реакций), чтобы это состояние можно было освободить, если остановка обработчика отменяет доставку до выполнения bindPending или если bindPending не возвращает дескриптор
• observe — необязательные хуки диагностики доставки

• Используйте createNativeApprovalChannelRouteGates из openclaw/plugin-sdk/approval-native-runtime, когда канал поддерживает как нативную доставку из исходного сеанса, так и явные цели пересылки подтверждений. Это вспомогательное средство централизует выбор конфигурации подтверждений, обработку mode, фильтры агентов и сеансов, привязку учётных записей, сопоставление целей сеанса и сопоставление списков целей, при этом вызывающий код по-прежнему отвечает за идентификатор канала, режим пересылки по умолчанию, поиск учётной записи, проверку включения транспорта, нормализацию целей и разрешение цели из источника хода. Не используйте его для создания принадлежащих ядру настроек политики канала по умолчанию; явно передавайте документированный режим канала по умолчанию.
• createChannelNativeOriginTargetResolver по умолчанию использует общий механизм сопоставления маршрутов каналов для целей { to, accountId, threadId }. Передавайте targetsMatch только тогда, когда канал имеет специфичные для провайдера правила эквивалентности, например сопоставление префиксов временных меток Slack. Передавайте normalizeTargetForMatch, когда каналу требуется привести идентификаторы провайдера к каноническому виду до запуска стандартного механизма сопоставления маршрутов или пользовательского обратного вызова targetsMatch, сохраняя при этом исходную цель для доставки. Используйте normalizeTarget только тогда, когда к каноническому виду следует привести саму разрешённую цель доставки.
• Если каналу нужны принадлежащие среде выполнения объекты, например клиент, токен, приложение Bolt или приёмник Webhook, зарегистрируйте их через openclaw/plugin-sdk/channel-runtime-context. Универсальный реестр контекста среды выполнения позволяет ядру запускать обработчики на основе возможностей из состояния запуска канала без добавления специализированных для подтверждений обёрток.
• Используйте низкоуровневые createChannelApprovalHandler или createChannelNativeApprovalRuntime только тогда, когда интерфейс на основе возможностей пока недостаточно выразителен.
• Каналы нативных подтверждений должны направлять и accountId, и approvalKind через эти вспомогательные средства. accountId ограничивает политику подтверждений для нескольких учётных записей нужной учётной записью бота, а approvalKind делает поведение подтверждений выполнения и плагинов доступным каналу без жёстко заданных ветвей в ядре.
• Уведомления о перенаправлении подтверждений также принадлежат ядру. Плагины каналов не должны отправлять собственные последующие сообщения «подтверждение отправлено в личные сообщения / другой канал» из createChannelNativeApprovalRuntime; вместо этого предоставляйте точную маршрутизацию от источника к личным сообщениям подтверждающего через общие вспомогательные средства возможностей подтверждения и позволяйте ядру агрегировать фактические доставки перед публикацией уведомления обратно в чат-инициатор.
• Сохраняйте тип идентификатора доставленного подтверждения на всём пути. Нативные клиенты не должны угадывать или переписывать маршрутизацию подтверждений выполнения и плагинов на основе локального состояния канала.
• Передавайте этот явный approvalKind в resolveApprovalOverGateway. При этом используется каноническая служба approval.resolve и возвращается зарегистрированный победитель, если другая поверхность отвечает первой. Старый явный вход resolveMethod сохраняется для элементов управления на основе команд; новые нативные действия не должны использовать его или выводить тип из идентификатора.
• Разные типы подтверждений могут намеренно предоставлять разные нативные поверхности. Текущие встроенные примеры: Matrix сохраняет одинаковую нативную маршрутизацию в личные сообщения и каналы и интерфейс реакций для подтверждений выполнения и плагинов, при этом позволяя аутентификации различаться в зависимости от типа подтверждения; Slack сохраняет нативную маршрутизацию подтверждений доступной как для идентификаторов выполнения, так и для идентификаторов плагинов.
• 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-reference-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 охватывает безопасные для среды выполнения вспомогательные средства настройки: createSetupTranslator, безопасные для импорта адаптеры исправлений настройки (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), вывод примечаний поиска, promptResolvedAllowFrom, splitSetupEntries и делегированные конструкторы прокси настройки.
• openclaw/plugin-sdk/channel-setup охватывает конструкторы настройки необязательной установки и несколько безопасных для настройки примитивов: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled и splitSetupEntries.
• Используйте более широкий интерфейс openclaw/plugin-sdk/setup только тогда, когда вам также нужны более тяжёлые общие вспомогательные средства настройки и конфигурации, такие как 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: после того, как базовый ключ сеанса всё ещё совпал. Плагины провайдеров могут переопределять приоритет, поведение суффиксов и нормализацию идентификатора ветки, когда их платформа имеет нативную семантику доставки в ветки.
• openclaw/plugin-sdk/thread-bindings-runtime для жизненного цикла привязки веток и регистрации адаптеров
• openclaw/plugin-sdk/agent-media-payload только тогда, когда всё ещё требуется устаревшая структура полей полезной нагрузки агента или медиа
• openclaw/plugin-sdk/telegram-command-config (устарело: ни один встроенный плагин не использует это в рабочей среде) для нормализации пользовательских команд Telegram, проверки дубликатов и конфликтов и контракта конфигурации команд со стабильным откатом; для нового кода плагинов предпочитайте локальную обработку конфигурации команд в плагине

​

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

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

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

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

1. Вычислите локальные факты об упоминании.
2. Передайте эти факты в resolveInboundMentionDecision({ facts, policy }).
3. Используйте decision.effectiveWasMentioned, decision.shouldBypassMention и decision.shouldSkip во входном фильтре.

import {
  implicitMentionKindWhen,
  matchesMentionWithExplicit,
  resolveInboundMentionDecision,
} from "openclaw/plugin-sdk/channel-inbound";

const wasMentioned = matchesMentionWithExplicit({
  text,
  mentionRegexes,
  explicit: {
    hasAnyMention,
    isExplicitlyMentioned,
    canResolveExplicit,
  },
});

const facts = {
  canDetectMention: true,
  wasMentioned,
  hasAnyMention,
  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;

​

Пошаговое руководство

{
  "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": "Подключить OpenClaw к Acme Chat."
    }
  }
}

{
  "id": "acme-chat",
  "channels": ["acme-chat"],
  "name": "Acme Chat",
  "description": "Плагин канала Acme Chat",
  "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": "Токен бота",
          "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"; // клиент API вашей платформы

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: требуется токен");
  return {
    accountId: accountId ?? null,
    token,
    allowFrom: section?.allowFrom ?? [],
    dmPolicy: section?.dmSecurity,
  };
}

export const acmeChatPlugin = createChatChannelPlugin<ResolvedAccount>({
  base: createChannelPluginBase({
    id: "acme-chat",
    // Разрешение и проверка учётной записи относятся к `config`, а не к `setup`.
    // `setup` отвечает за запись при первоначальной настройке (applyAccountConfig, validateInput).
    config: {
      listAccountIds: () => ["default"],
      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",
        };
      },
    },
    setup: {
      applyAccountConfig: ({ cfg, input }) => ({
        ...cfg,
        channels: {
          ...cfg.channels,
          "acme-chat": { ...(cfg.channels as any)?.["acme-chat"], ...input },
        },
      }),
    },
  }),

  // Безопасность личных сообщений: кто может отправлять сообщения боту
  security: {
    dm: {
      channelKey: "acme-chat",
      resolvePolicy: (account) => account.dmPolicy,
      resolveAllowFrom: (account) => account.allowFrom,
      defaultPolicy: "allowlist",
    },
  },

  // Сопряжение: процесс подтверждения новых контактов в личных сообщениях
  pairing: {
    text: {
      idLabel: "Имя пользователя Acme Chat",
      message: "Отправьте этот код для подтверждения своей личности:",
      notify: async ({ target, code }) => {
        await acmeChatApi.sendDm(target, `Код сопряжения: ${code}`);
      },
    },
  },

  // Ветки обсуждения: способ доставки ответов
  threading: { topLevelReplyToMode: "reply" },

  // Исходящие сообщения: отправка сообщений на платформу
  outbound: {
    attachedResults: {
      channel: "acme-chat",
      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",
  plugin: acmeChatPlugin,
  registerCliMetadata(api) {
    api.registerCli(
      ({ program }) => {
        program
          .command("acme-chat")
          .description("Управление Acme Chat");
      },
      {
        descriptors: [
          {
            name: "acme-chat",
            description: "Управление Acme Chat",
            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", // аутентификация под управлением плагина (проверяйте подписи самостоятельно)
    handler: async (req, res) => {
      const event = parseWebhookPayload(req);

      // Ваш обработчик входящих сообщений передаёт сообщение в OpenClaw.
      // Точное подключение зависит от SDK вашей платформы —
      // реальный пример см. в пакете встроенного плагина Microsoft Teams или Google Chat.
      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", () => {
  it("определяет учётную запись из конфигурации", () => {
    const cfg = {
      channels: {
        "acme-chat": { token: "test-token", allowFrom: ["user1"] },
      },
    } as any;
    const account = acmeChatPlugin.config.resolveAccount(cfg, undefined);
    expect(account.token).toBe("test-token");
  });

  it("проверяет учётную запись без материализации секретов", () => {
    const cfg = {
      channels: { "acme-chat": { token: "test-token" } },
    } as any;
    const result = acmeChatPlugin.config.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(true);
    expect(result.tokenStatus).toBe("available");
  });

  it("сообщает об отсутствующей конфигурации", () => {
    const cfg = { channels: {} } as any;
    const result = acmeChatPlugin.config.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            # внутренние экспорты среды выполнения (необязательно)
└── src/
    ├── channel.ts            # ChannelPlugin через createChatChannelPlugin
    ├── channel.test.ts       # тесты
    ├── client.ts             # клиент API платформы
    └── runtime.ts            # хранилище среды выполнения (при необходимости)

​

Расширенные темы

​

Дальнейшие шаги

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

​

Связанные материалы

• Настройка Plugin SDK
• Создание плагинов
• Плагины среды выполнения агентов