Crear plugins de canal

​

Qué pertenece a tu Plugin

• Configuración - resolución de cuentas y asistente de configuración
• Seguridad - política de DM y listas de permitidos
• Emparejamiento - flujo de aprobación por DM
• Gramática de sesión - cómo los ids de conversación específicos del proveedor se asignan a chats base, ids de hilo y alternativas de padres
• Saliente - envío de texto, medios y encuestas a la plataforma
• Hilos - cómo se organizan las respuestas en hilos
• Escritura de Heartbeat - señales opcionales de escritura/ocupado para destinos de entrega de Heartbeat

​

Adaptador de mensajes

​

Ingreso entrante (experimental)

​

Indicadores de escritura

​

Parámetros de origen de medios

​

Modelado de payload nativo

​

Gramática de conversación de sesión

​

Aprobaciones y capacidades de canal

​

Autenticación de aprobación

• approvalCapability.authorizeActorAction y approvalCapability.getActionAvailabilityState son la vía canónica de autenticación de aprobación.
• Usa getActionAvailabilityState para la disponibilidad de autenticación de aprobación en el mismo chat. Mantén disponibles a los aprobadores configurados para /approve incluso cuando la entrega nativa esté deshabilitada; usa en cambio el estado de la superficie de inicio nativa para orientación de entrega/configuración.
• Si tu canal expone aprobaciones de exec nativas, usa approvalCapability.getExecInitiatingSurfaceState para el estado de superficie de inicio/cliente nativo cuando difiera de la autenticación de aprobación en el mismo chat. El núcleo usa ese hook específico de exec para distinguir enabled de disabled, decidir si el canal iniciador admite aprobaciones de exec nativas e incluir el canal en la orientación de alternativa del cliente nativo. createApproverRestrictedNativeApprovalCapability(...) completa esto para el caso común.
• Si un canal puede inferir identidades de DM estables similares a propietario a partir de la configuración existente, usa createResolvedApproverActionAuthAdapter desde openclaw/plugin-sdk/approval-runtime para restringir /approve en el mismo chat sin añadir lógica de núcleo específica de aprobación.
• Si la autenticación de aprobación personalizada permite intencionalmente solo la alternativa del mismo chat, devuelve markImplicitSameChatApprovalAuthorization({ authorized: true }) desde openclaw/plugin-sdk/approval-auth-runtime; de lo contrario, el núcleo trata el resultado como autorización explícita de aprobador.
• Si una devolución de llamada nativa propiedad del canal resuelve aprobaciones directamente, usa isImplicitSameChatApprovalAuthorization(...) antes de resolver para que la alternativa implícita siga pasando por la autorización normal de actor del canal.

​

Ciclo de vida del payload y orientación de configuración

• Usa outbound.shouldSuppressLocalPayloadPrompt o outbound.beforeDeliverPayload para comportamiento del ciclo de vida del payload específico del canal, como ocultar prompts locales de aprobación duplicados o enviar indicadores de escritura antes de la entrega.
• Usa approvalCapability.describeExecApprovalSetup cuando el canal quiera que la respuesta de ruta deshabilitada explique los controles exactos de configuración necesarios para habilitar aprobaciones de exec nativas. El hook recibe { channel, channelLabel, accountId }; los canales con cuentas con nombre deben renderizar rutas con alcance de cuenta como channels.<channel>.accounts.<id>.execApprovals.* en lugar de valores predeterminados de nivel superior.
• Usa approvalCapability.describePluginApprovalSetup cuando sea seguro mostrar la orientación de fallos de aprobación de Plugin para fallos sin ruta y de tiempo de espera de aprobación de Plugin. createApproverRestrictedNativeApprovalCapability(...) no infiere esto desde describeExecApprovalSetup; pasa el mismo helper explícitamente solo cuando las aprobaciones de Plugin y exec usen realmente la misma configuración nativa.

​

Entrega de aprobación nativa

• availability - si la cuenta está configurada y si una solicitud debe manejarse
• presentation - asigna el modelo de vista de aprobación compartido a cargas nativas pendientes/resueltas/caducadas o acciones finales
• transport - prepara destinos y envía/actualiza/elimina mensajes de aprobación nativos
• interactions - hooks opcionales bind/unbind/clear-action para botones o reacciones nativos, además de un hook opcional cancelDelivered. Implementa cancelDelivered cuando deliverPending registra estado en proceso o persistente (como un almacén de destinos de reacción) para que ese estado pueda liberarse si una detención del manejador cancela la entrega antes de que se ejecute bindPending, o cuando bindPending no devuelve ningún handle
• observe - hooks opcionales de diagnóstico de entrega

• Usa createNativeApprovalChannelRouteGates de openclaw/plugin-sdk/approval-native-runtime cuando un canal admite tanto entrega nativa con origen de sesión como destinos explícitos de reenvío de aprobación. El helper centraliza la selección de configuración de aprobación, el manejo de mode, los filtros de agente/sesión, la vinculación de cuentas, la coincidencia de destinos de sesión y la coincidencia de listas de destinos, mientras que los llamadores siguen siendo propietarios del id de canal, el modo predeterminado de reenvío, la búsqueda de cuenta, la comprobación de transporte habilitado, la normalización de destinos y la resolución de destinos de origen de turno. No lo uses para crear valores predeterminados de política de canal propiedad de core; pasa explícitamente el modo predeterminado documentado del canal.
• createChannelNativeOriginTargetResolver usa de forma predeterminada el matcher compartido de rutas de canal para destinos { to, accountId, threadId }. Pasa targetsMatch solo cuando un canal tiene reglas de equivalencia específicas del proveedor, como la coincidencia de prefijo de timestamp de Slack. Pasa normalizeTargetForMatch cuando el canal necesite canonicalizar ids de proveedor antes de que se ejecute el matcher de ruta predeterminado o un callback personalizado targetsMatch, preservando al mismo tiempo el destino original para la entrega. Usa normalizeTarget solo cuando el propio destino de entrega resuelto deba canonicalizarse.
• Si el canal necesita objetos propiedad del runtime como un cliente, token, aplicación Bolt o receptor de webhook, regístralos mediante openclaw/plugin-sdk/channel-runtime-context. El registro genérico de contexto de runtime permite que core arranque manejadores impulsados por capacidades desde el estado de inicio del canal sin agregar pegamento de wrappers específico de aprobación.
• Recurre a createChannelApprovalHandler o createChannelNativeApprovalRuntime de nivel más bajo solo cuando el punto de integración impulsado por capacidades todavía no sea suficientemente expresivo.
• Los canales de aprobación nativa deben enrutar tanto accountId como approvalKind mediante esos helpers. accountId mantiene la política de aprobación multi-cuenta acotada a la cuenta de bot correcta, y approvalKind mantiene el comportamiento de aprobación exec vs plugin disponible para el canal sin ramas hardcodeadas en core.
• Core también es propietario de los avisos de redireccionamiento de aprobación. Los plugins de canal no deben enviar sus propios mensajes de seguimiento “la aprobación fue a DMs / otro canal” desde createChannelNativeApprovalRuntime; en su lugar, expón un enrutamiento preciso de origen + DM del aprobador mediante los helpers compartidos de capacidad de aprobación y deja que core agregue las entregas reales antes de publicar cualquier aviso de vuelta al chat iniciador.
• Preserva el tipo de id de aprobación entregado de extremo a extremo. Los clientes nativos no deben adivinar ni reescribir el enrutamiento de aprobación exec vs plugin desde estado local del canal.
• Distintos tipos de aprobación pueden exponer intencionalmente superficies nativas diferentes. Ejemplos empaquetados actuales: Matrix mantiene el mismo enrutamiento nativo de DM/canal y la UX de reacciones para aprobaciones exec y plugin, a la vez que permite que la autenticación difiera por tipo de aprobación; Slack mantiene el enrutamiento de aprobación nativa disponible tanto para ids exec como plugin.
• createApproverRestrictedNativeApprovalAdapter todavía existe como wrapper de compatibilidad, pero el código nuevo debe preferir el constructor de capacidades y exponer approvalCapability en el plugin.

​

Subrutas más acotadas del runtime de aprobación

• 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

​

Subrutas de configuración

• openclaw/plugin-sdk/setup-runtime cubre los helpers de configuración seguros para runtime: createSetupTranslator, adaptadores de parches de configuración seguros para importación (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), salida de notas de búsqueda, promptResolvedAllowFrom, splitSetupEntries y los constructores delegados setup-proxy.
• openclaw/plugin-sdk/channel-setup cubre los constructores de configuración de instalación opcional además de algunas primitivas seguras para configuración: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled y splitSetupEntries.
• Usa el punto de integración más amplio openclaw/plugin-sdk/setup solo cuando también necesites los helpers compartidos más pesados de configuración/configuración, como moveSingleAccountChannelSectionToDefaultAccount(...).

​

Otras subrutas acotadas de canal

• openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution y openclaw/plugin-sdk/account-helpers para configuración multi-cuenta y fallback de cuenta predeterminada
• openclaw/plugin-sdk/inbound-envelope y openclaw/plugin-sdk/channel-inbound para rutas/sobres entrantes y cableado de registro y despacho
• openclaw/plugin-sdk/channel-targets para helpers de análisis de destinos
• openclaw/plugin-sdk/outbound-media para carga de medios y openclaw/plugin-sdk/channel-outbound para delegados de identidad/envío salientes y planificación de payloads
• buildThreadAwareOutboundSessionRoute(...) de openclaw/plugin-sdk/channel-core cuando una ruta saliente debe preservar un replyToId/threadId explícito o recuperar la sesión :thread: actual después de que la clave de sesión base todavía coincida. Los plugins de proveedor pueden sobrescribir la precedencia, el comportamiento de sufijo y la normalización de id de hilo cuando su plataforma tenga semántica nativa de entrega en hilos.
• openclaw/plugin-sdk/thread-bindings-runtime para el ciclo de vida de vinculaciones de hilos y el registro de adaptadores
• openclaw/plugin-sdk/agent-media-payload solo cuando todavía se requiera un diseño heredado de campos de payload de agente/medio
• openclaw/plugin-sdk/telegram-command-config (obsoleto: ningún plugin empaquetado lo usa en producción) para la normalización de comandos personalizados de Telegram, validación de duplicados/conflictos y un contrato de configuración de comandos estable ante fallback; prefiere el manejo de configuración de comandos local al plugin para código de plugin nuevo

​

Política de menciones entrantes

• recopilación de evidencia propiedad del plugin
• evaluación de política compartida

• detección de respuesta al bot
• detección de bot citado
• comprobaciones de participación en hilos
• exclusiones de mensajes de servicio/sistema
• cachés nativas de plataforma necesarias para demostrar participación del bot

• requireMention
• resultado de mención explícita
• lista de permisos de mención implícita
• omisión por comando
• decisión final de omisión

1. Calcula los datos locales de mención.
2. Pasa esos datos a resolveInboundMentionDecision({ facts, policy }).
3. Usa decision.effectiveWasMentioned, decision.shouldBypassMention y decision.shouldSkip en tu puerta de entrada.

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;

​

Tutorial

{
  "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."
    }
  }
}

{
  "id": "acme-chat",
  "channels": ["acme-chat"],
  "name": "Acme Chat",
  "description": "Acme Chat channel plugin",
  "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": "Bot token",
          "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"; // 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",
    // Account resolution/inspection belongs on `config`, not `setup`.
    // `setup` covers onboarding writes (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 },
        },
      }),
    },
  }),

  // 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: {
      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 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.config.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.config.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.config.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(false);
  });
});

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

​

Estructura de archivos

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

​

Temas avanzados

​

Siguientes pasos

• Plugins de proveedor - si tu Plugin también proporciona modelos
• Información general del SDK - referencia completa de importación por subrutas
• Pruebas del SDK - utilidades de prueba y pruebas de contrato
• Manifiesto de Plugin - esquema completo del manifiesto

​

Relacionado

• Configuración del SDK de Plugin
• Creación de Plugins
• Plugins de arnés de agente