Tworzenie pluginów kanałów

​

Za co odpowiada plugin

• Konfigurację — rozpoznawanie konta i kreator konfiguracji
• Zabezpieczenia — zasady wiadomości prywatnych i listy dozwolonych
• Parowanie — przepływ zatwierdzania wiadomości prywatnych
• Gramatykę sesji — sposób mapowania identyfikatorów konwersacji specyficznych dla dostawcy na bazowe czaty, identyfikatory wątków i zastępcze konwersacje nadrzędne
• Wiadomości wychodzące — wysyłanie na platformę tekstu, multimediów i ankiet
• Obsługę wątków — sposób grupowania odpowiedzi w wątki
• Wskaźnik pisania Heartbeat — opcjonalne sygnały pisania/zajętości dla celów dostarczania Heartbeat

​

Adapter wiadomości

​

Obsługa ruchu przychodzącego (eksperymentalna)

​

Wskaźniki pisania

​

Parametry źródeł multimediów

​

Kształtowanie natywnego ładunku

​

Gramatyka konwersacji sesji

​

Obsługa powiązań konwersacji w zakresie konta

​

Zatwierdzenia i możliwości kanału

​

Autoryzacja zatwierdzeń

• approvalCapability.authorizeActorAction i approvalCapability.getActionAvailabilityState są kanonicznym punktem rozszerzenia autoryzacji zatwierdzeń.
• Używaj getActionAvailabilityState do określania dostępności autoryzacji zatwierdzeń w tym samym czacie. Zachowaj dostępność skonfigurowanych zatwierdzających dla /approve nawet wtedy, gdy natywne dostarczanie jest wyłączone; do dostarczania i wskazówek konfiguracyjnych używaj zamiast tego stanu natywnej powierzchni inicjującej.
• Jeśli kanał udostępnia natywne zatwierdzenia wykonania, używaj approvalCapability.getExecInitiatingSurfaceState do określania stanu powierzchni inicjującej/natywnego klienta, gdy różni się on od autoryzacji zatwierdzeń w tym samym czacie. Rdzeń używa tego punktu rozszerzenia specyficznego dla wykonania, aby rozróżnić enabled i disabled, określić, czy kanał inicjujący obsługuje natywne zatwierdzenia wykonania, oraz uwzględnić kanał we wskazówkach dotyczących natywnego klienta zastępczego. createApproverRestrictedNativeApprovalCapability(...) uzupełnia tę wartość w typowym przypadku.
• Jeśli kanał może na podstawie istniejącej konfiguracji wywnioskować stabilne tożsamości wiadomości prywatnych podobne do właściciela, użyj createResolvedApproverActionAuthAdapter z openclaw/plugin-sdk/approval-runtime, aby ograniczyć /approve w tym samym czacie bez dodawania do rdzenia logiki specyficznej dla zatwierdzeń.
• Jeśli niestandardowa autoryzacja zatwierdzeń celowo zezwala wyłącznie na mechanizm zastępczy w tym samym czacie, zwróć markImplicitSameChatApprovalAuthorization({ authorized: true }) z openclaw/plugin-sdk/approval-auth-runtime; w przeciwnym razie rdzeń traktuje wynik jako jawną autoryzację zatwierdzającego.
• Jeśli natywne wywołanie zwrotne należące do kanału bezpośrednio rozstrzyga zatwierdzenia, przed rozstrzygnięciem użyj isImplicitSameChatApprovalAuthorization(...), aby niejawny mechanizm zastępczy nadal przechodził przez zwykłą autoryzację aktora kanału.

​

Cykl życia ładunku i wskazówki konfiguracyjne

• Używaj outbound.shouldSuppressLocalPayloadPrompt lub outbound.beforeDeliverPayload do zachowań cyklu życia ładunku specyficznych dla kanału, takich jak ukrywanie zduplikowanych lokalnych monitów o zatwierdzenie lub wysyłanie wskaźników pisania przed dostarczeniem.
• Używaj approvalCapability.describeExecApprovalSetup, gdy kanał chce, aby odpowiedź dla wyłączonej ścieżki wyjaśniała dokładne opcje konfiguracji potrzebne do włączenia natywnych zatwierdzeń wykonania. Punkt rozszerzenia otrzymuje { channel, channelLabel, accountId }; kanały z nazwanymi kontami powinny renderować ścieżki w zakresie konta, takie jak channels.<channel>.accounts.<id>.execApprovals.*, zamiast domyślnych wartości najwyższego poziomu.
• Używaj approvalCapability.describePluginApprovalSetup, gdy wskazówki dotyczące niepowodzenia zatwierdzenia pluginu można bezpiecznie wyświetlać w przypadku braku trasy zatwierdzenia pluginu i przekroczenia limitu czasu. createApproverRestrictedNativeApprovalCapability(...) nie wyznacza tego na podstawie describeExecApprovalSetup; przekaż tę samą funkcję pomocniczą jawnie tylko wtedy, gdy zatwierdzenia pluginu i wykonania rzeczywiście korzystają z tej samej konfiguracji natywnej.

​

Natywne dostarczanie zatwierdzeń

• availability — czy konto jest skonfigurowane i czy żądanie powinno zostać obsłużone
• presentation — mapowanie współdzielonego modelu widoku zatwierdzenia na natywne ładunki oczekujące/rozstrzygnięte/wygasłe lub działania końcowe
• transport — przygotowanie celów oraz wysyłanie/aktualizowanie/usuwanie natywnych komunikatów zatwierdzenia
• interactions — opcjonalne haki powiązania/usunięcia powiązania/czyszczenia działania dla natywnych przycisków lub reakcji oraz opcjonalny hak cancelDelivered. Należy zaimplementować cancelDelivered, gdy deliverPending rejestruje stan w procesie lub stan trwały (na przykład magazyn celów reakcji), aby można było zwolnić ten stan, jeśli zatrzymanie procedury obsługi anuluje dostarczenie przed uruchomieniem bindPending, albo gdy bindPending nie zwróci uchwytu
• observe — opcjonalne haki diagnostyki dostarczania

• Należy używać createNativeApprovalChannelRouteGates z openclaw/plugin-sdk/approval-native-runtime, gdy kanał obsługuje zarówno natywne dostarczanie pochodzące z sesji, jak i jawne cele przekazywania zatwierdzeń. Ta funkcja pomocnicza centralizuje wybór konfiguracji zatwierdzeń, obsługę mode, filtry agenta/sesji, powiązanie konta, dopasowanie celu sesji i dopasowanie listy celów, natomiast kod wywołujący nadal odpowiada za identyfikator kanału, domyślny tryb przekazywania, wyszukiwanie konta, sprawdzenie włączenia transportu, normalizację celu i ustalanie celu na podstawie źródła tury. Nie należy używać jej do tworzenia należących do rdzenia domyślnych zasad kanału; należy jawnie przekazać udokumentowany domyślny tryb kanału.
• createChannelNativeOriginTargetResolver domyślnie używa współdzielonego mechanizmu dopasowywania tras kanału dla celów { to, accountId, threadId }. Parametr targetsMatch należy przekazywać tylko wtedy, gdy kanał ma reguły równoważności specyficzne dla dostawcy, takie jak dopasowywanie prefiksu znacznika czasu w Slack. Parametr normalizeTargetForMatch należy przekazać, gdy kanał musi kanonizować identyfikatory dostawcy przed uruchomieniem domyślnego mechanizmu dopasowywania tras lub niestandardowego wywołania zwrotnego targetsMatch, zachowując jednocześnie pierwotny cel do dostarczenia. normalizeTarget należy używać tylko wtedy, gdy kanonizacji powinien podlegać sam ustalony cel dostarczenia.
• Jeśli kanał potrzebuje obiektów należących do środowiska uruchomieniowego, takich jak klient, token, aplikacja Bolt lub odbiornik webhooka, należy je zarejestrować przez openclaw/plugin-sdk/channel-runtime-context. Ogólny rejestr kontekstu środowiska uruchomieniowego pozwala rdzeniowi inicjować procedury obsługi sterowane możliwościami na podstawie stanu uruchomienia kanału bez dodawania kodu opakowującego specyficznego dla zatwierdzeń.
• Po funkcje niższego poziomu createChannelApprovalHandler lub createChannelNativeApprovalRuntime należy sięgać tylko wtedy, gdy punkt integracji sterowany możliwościami nie jest jeszcze wystarczająco ekspresyjny.
• Kanały natywnych zatwierdzeń muszą kierować zarówno accountId, jak i approvalKind przez te funkcje pomocnicze. accountId ogranicza zasady zatwierdzania dla wielu kont do właściwego konta bota, a approvalKind udostępnia kanałowi różne zachowanie zatwierdzeń exec i Plugin bez zakodowanych na stałe rozgałęzień w rdzeniu.
• Rdzeń odpowiada również za powiadomienia o przekierowaniu zatwierdzeń. Pluginy kanałów nie powinny wysyłać własnych komunikatów uzupełniających „zatwierdzenie trafiło do wiadomości prywatnych / innego kanału” z createChannelNativeApprovalRuntime; zamiast tego należy udostępnić dokładne trasowanie źródło + wiadomość prywatna zatwierdzającego za pomocą współdzielonych funkcji pomocniczych możliwości zatwierdzania i pozwolić rdzeniowi agregować rzeczywiste dostarczenia przed opublikowaniem jakiegokolwiek powiadomienia z powrotem na czacie inicjującym.
• Należy zachować rodzaj identyfikatora dostarczonego zatwierdzenia w całym przepływie. Klienci natywni nie powinni odgadywać ani przepisywać trasowania zatwierdzeń exec i Plugin na podstawie lokalnego stanu kanału.
• Ten jawny approvalKind należy przekazać do resolveApprovalOverGateway. Powoduje to użycie kanonicznej usługi approval.resolve i zwrócenie zarejestrowanego zwycięzcy, gdy inna powierzchnia odpowie jako pierwsza. Starsze jawne wejście resolveMethod pozostaje dostępne dla elementów sterujących opartych na poleceniach; nowe działania natywne nie mogą go używać ani wywnioskowywać rodzaju z identyfikatora.
• Różne rodzaje zatwierdzeń mogą celowo udostępniać różne powierzchnie natywne. Obecne dołączone przykłady: Matrix zachowuje takie samo natywne trasowanie wiadomości prywatnych/kanału i środowisko reakcji dla zatwierdzeń exec i Plugin, jednocześnie nadal pozwalając różnicować uwierzytelnianie według rodzaju zatwierdzenia; Slack zachowuje natywne trasowanie zatwierdzeń dla identyfikatorów exec i Plugin.
• createApproverRestrictedNativeApprovalAdapter nadal istnieje jako opakowanie zgodności, ale nowy kod powinien preferować konstruktor możliwości i udostępniać approvalCapability w pluginie.

​

Węższe podścieżki środowiska uruchomieniowego zatwierdzeń

• 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

​

Podścieżki konfiguracji

• openclaw/plugin-sdk/setup-runtime obejmuje bezpieczne dla środowiska uruchomieniowego funkcje pomocnicze konfiguracji: createSetupTranslator, bezpieczne przy imporcie adaptery poprawek konfiguracji (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), dane wyjściowe uwag wyszukiwania, promptResolvedAllowFrom, splitSetupEntries oraz delegowane konstruktory proxy konfiguracji.
• openclaw/plugin-sdk/channel-setup obejmuje konstruktory konfiguracji opcjonalnej instalacji oraz kilka bezpiecznych dla konfiguracji elementów podstawowych: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled i splitSetupEntries.
• Szerszego punktu integracji openclaw/plugin-sdk/setup należy używać tylko wtedy, gdy potrzebne są również bardziej rozbudowane współdzielone funkcje pomocnicze konfiguracji, takie jak moveSingleAccountChannelSectionToDefaultAccount(...).

​

Inne wąskie podścieżki kanału

• openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution i openclaw/plugin-sdk/account-helpers do konfiguracji wielu kont i powrotu do konta domyślnego
• openclaw/plugin-sdk/inbound-envelope i openclaw/plugin-sdk/channel-inbound do okablowania trasy/koperty przychodzącej oraz rejestrowania i wysyłania
• openclaw/plugin-sdk/channel-targets do funkcji pomocniczych analizowania celu
• openclaw/plugin-sdk/outbound-media do ładowania multimediów oraz openclaw/plugin-sdk/channel-outbound do delegatów tożsamości/wysyłania wychodzącego i planowania ładunku
• buildThreadAwareOutboundSessionRoute(...) z openclaw/plugin-sdk/channel-core, gdy trasa wychodząca powinna zachować jawny replyToId/threadId lub odzyskać bieżącą sesję :thread: po tym, jak bazowy klucz sesji nadal jest zgodny. Pluginy dostawców mogą nadpisywać pierwszeństwo, zachowanie sufiksów i normalizację identyfikatora wątku, gdy ich platforma ma natywną semantykę dostarczania do wątków.
• openclaw/plugin-sdk/thread-bindings-runtime do cyklu życia powiązań wątków i rejestracji adapterów
• openclaw/plugin-sdk/agent-media-payload tylko wtedy, gdy starszy układ pól ładunku agenta/multimediów jest nadal wymagany
• openclaw/plugin-sdk/telegram-command-config (przestarzałe: żaden dołączony plugin nie używa go w środowisku produkcyjnym) do normalizacji niestandardowych poleceń Telegram, walidacji duplikatów/konfliktów i stabilnego mimo mechanizmu zapasowego kontraktu konfiguracji poleceń; w nowym kodzie pluginu należy preferować lokalną obsługę konfiguracji poleceń

​

Zasady obsługi wzmianek przychodzących

• gromadzenie dowodów należące do pluginu
• ocena współdzielonych zasad

• wykrywanie odpowiedzi do bota
• wykrywanie cytowania bota
• sprawdzanie udziału w wątku
• wykluczanie wiadomości usługi/systemowych
• natywne pamięci podręczne platformy potrzebne do potwierdzenia udziału bota

• requireMention
• wynik jawnej wzmianki
• lista dozwolonych niejawnych wzmianek
• pomijanie dla poleceń
• końcowa decyzja o pominięciu

1. Obliczyć lokalne fakty dotyczące wzmianek.
2. Przekazać te fakty do resolveInboundMentionDecision({ facts, policy }).
3. Użyć decision.effectiveWasMentioned, decision.shouldBypassMention i decision.shouldSkip w bramie danych przychodzących.

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;

​

Przewodnik

{
  "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": "Połącz OpenClaw z Acme Chat."
    }
  }
}

{
  "id": "acme-chat",
  "channels": ["acme-chat"],
  "name": "Acme Chat",
  "description": "Plugin kanału 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": "Token bota",
          "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"; // klient API platformy

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 jest wymagany");
  return {
    accountId: accountId ?? null,
    token,
    allowFrom: section?.allowFrom ?? [],
    dmPolicy: section?.dmSecurity,
  };
}

export const acmeChatPlugin = createChatChannelPlugin<ResolvedAccount>({
  base: createChannelPluginBase({
    id: "acme-chat",
    // Rozwiązywanie i sprawdzanie kont należy do `config`, a nie do `setup`.
    // `setup` obsługuje zapisy podczas wdrażania (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 },
        },
      }),
    },
  }),

  // Zabezpieczenia wiadomości prywatnych: kto może wysyłać wiadomości do bota
  security: {
    dm: {
      channelKey: "acme-chat",
      resolvePolicy: (account) => account.dmPolicy,
      resolveAllowFrom: (account) => account.allowFrom,
      defaultPolicy: "allowlist",
    },
  },

  // Parowanie: przepływ zatwierdzania nowych kontaktów w wiadomościach prywatnych
  pairing: {
    text: {
      idLabel: "Nazwa użytkownika Acme Chat",
      message: "Wyślij ten kod, aby zweryfikować swoją tożsamość:",
      notify: async ({ target, code }) => {
        await acmeChatApi.sendDm(target, `Kod parowania: ${code}`);
      },
    },
  },

  // Wątki: sposób dostarczania odpowiedzi
  threading: { topLevelReplyToMode: "reply" },

  // Wiadomości wychodzące: wysyłanie wiadomości na platformę
  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: "Plugin kanału Acme Chat",
  plugin: acmeChatPlugin,
  registerCliMetadata(api) {
    api.registerCli(
      ({ program }) => {
        program
          .command("acme-chat")
          .description("Zarządzanie Acme Chat");
      },
      {
        descriptors: [
          {
            name: "acme-chat",
            description: "Zarządzanie 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", // uwierzytelnianie zarządzane przez plugin (podpisy należy weryfikować samodzielnie)
    handler: async (req, res) => {
      const event = parseWebhookPayload(req);

      // Procedura obsługi wiadomości przychodzących przekazuje wiadomość do OpenClaw.
      // Dokładny sposób podłączenia zależy od SDK platformy —
      // rzeczywisty przykład znajduje się w dołączonym pakiecie pluginu Microsoft Teams lub 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("plugin acme-chat", () => {
  it("rozpoznaje konto z konfiguracji", () => {
    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("sprawdza konto bez materializowania sekretów", () => {
    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("zgłasza brak konfiguracji", () => {
    const cfg = { channels: {} } as any;
    const result = acmeChatPlugin.config.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(false);
  });
});

pnpm test <bundled-plugin-root>/acme-chat/

​

Struktura plików

<bundled-plugin-root>/acme-chat/
├── package.json              # metadane openclaw.channel
├── openclaw.plugin.json      # manifest ze schematem konfiguracji
├── index.ts                  # defineChannelPluginEntry
├── setup-entry.ts            # defineSetupPluginEntry
├── api.ts                    # eksporty publiczne (opcjonalne)
├── runtime-api.ts            # wewnętrzne eksporty środowiska uruchomieniowego (opcjonalne)
└── src/
    ├── channel.ts            # ChannelPlugin za pośrednictwem createChatChannelPlugin
    ├── channel.test.ts       # testy
    ├── client.ts             # klient API platformy
    └── runtime.ts            # magazyn środowiska uruchomieniowego (w razie potrzeby)

​

Tematy zaawansowane

​

Następne kroki

• Pluginy dostawców — jeśli plugin udostępnia również modele
• Omówienie SDK — pełna dokumentacja importów z podścieżek
• Testowanie SDK — narzędzia testowe i testy kontraktowe
• Manifest pluginu — pełny schemat manifestu

​

Powiązane

• Konfiguracja Plugin SDK
• Tworzenie pluginów
• Pluginy infrastruktury agentów