API de salida del canal

Los plugins de canal exponen el comportamiento de los mensajes salientes desde openclaw/plugin-sdk/channel-outbound. Use openclaw/plugin-sdk/channel-inbound para la orquestación de recepción/contexto/despacho.

El núcleo se encarga de las colas, la durabilidad, la política genérica de reintentos, los hooks, los acuses y la herramienta message compartida. El plugin se encarga de las llamadas nativas para enviar/editar/eliminar, la normalización del destino, los hilos de la plataforma, las citas seleccionadas, los indicadores de notificación, el estado de la cuenta y los efectos secundarios específicos de la plataforma.

Adaptador

La mayoría de los plugins definen un adaptador de message:

   defineChannelMessageAdapter,  createMessageReceiptFromOutboundResults,} from "openclaw/plugin-sdk/channel-outbound"; export const demoMessageAdapter = defineChannelMessageAdapter({  id: "demo",  durableFinal: {    capabilities: {      text: true,      replyTo: true,      thread: true,      messageSendingHooks: true,    },  },  send: {    text: async ({ cfg, to, text, accountId, replyToId, threadId, signal }) => {      const sent = await sendDemoMessage({        cfg,        to,        text,        accountId: accountId ?? undefined,        replyToId: replyToId ?? undefined,        threadId: threadId == null ? undefined : String(threadId),        signal,      });       return {        receipt: createMessageReceiptFromOutboundResults({          results: [{ channel: "demo", messageId: sent.id, conversationId: to }],          kind: "text",          threadId: threadId == null ? undefined : String(threadId),          replyToId: replyToId ?? undefined,        }),      };    },  },});

Declare únicamente las capacidades que el transporte nativo conserve realmente. Cubra cada capacidad declarada de envío, acuse, vista previa en vivo y confirmación de recepción con los auxiliares de contrato exportados desde esta subruta.

Saneamiento de texto sin formato

Use sanitizeForPlainText(...) cuando un adaptador de salida necesite convertir las etiquetas de formato HTML compatibles en marcado de texto ligero. De forma predeterminada, conserva los marcadores existentes de negrita y tachado propios del chat. Pase { style: "markdown" } únicamente cuando el canal vuelva a interpretar el resultado como Markdown:

 const chatText = sanitizeForPlainText(text);const markdownText = sanitizeForPlainText(text, { style: "markdown" });

El estilo Markdown usa **bold** y ~~strikethrough~~; la cursiva y el código en línea conservan los marcadores _italic_ y de acento grave en ambos estilos. Seleccione el estilo en el límite del canal en lugar de reescribir el texto de los marcadores después del saneamiento.

Evidencia de entrega

Un MessageReceipt registra el resultado devuelto por un adaptador de canal. Los identificadores concretos de mensajes de la plataforma demuestran que la ruta de envío de la plataforma aceptó el mensaje; no demuestran que el dispositivo de un destinatario lo mostrara o leyera. Los acuses sin identificadores de mensajes de la plataforma son únicamente metadatos de acuse locales. Los canales con acuses de lectura o estado de entrega al dispositivo deben registrar esos datos mediante una ruta independiente y específica del canal.

Si un adaptador de canal puede demostrar que reintentar un fallo no puede duplicar un envío visible para el destinatario y que no se inició ninguna llamada capaz de finalizarlo, lance new PlatformMessageNotDispatchedError("...", { cause: error }) desde openclaw/plugin-sdk/error-runtime. El núcleo podrá entonces borrar la evidencia obsoleta del intento de envío y reintentar de forma segura la intención en cola. Solo el adaptador que controla el límite final de despacho puede realizar esta afirmación. Nunca use el marcador después de que comience una llamada de finalización/envío ni cuando esta devuelva un resultado ambiguo; un marcado incorrecto puede duplicar mensajes.

Adaptadores de salida existentes

Si el canal ya tiene un adaptador outbound compatible, derive el adaptador de mensajes en lugar de duplicar el código de envío:

 export const messageAdapter = createChannelMessageAdapterFromOutbound({  id: "demo",  outbound,  durableFinal: {    capabilities: {      text: true,      media: true,    },  },});

Envíos duraderos

Los auxiliares de envío en tiempo de ejecución también se encuentran en channel-outbound:

• sendDurableMessageBatch(...)
• withDurableMessageSendContext(...)
• deliverInboundReplyWithMessageSendContext(...)
• auxiliares de streaming/progreso de borradores, como resolveChannelDraftStreamingChunking(...)

sendDurableMessageBatch(...) devuelve un resultado explícito:

Use payloadOutcomes cuando un lote combine cargas útiles enviadas, suprimidas y fallidas. No deduzca la cancelación de un hook a partir de un resultado vacío de entrega directa heredada.

Admisión de entrega diferida

Use message.durableFinal.admitDeferredDelivery(...) cuando una cuenta resuelta no pueda aceptar de forma segura entregas salientes o diferidas gestionadas por el núcleo. El núcleo llama a este hook de forma síncrona antes del trabajo saliente en vivo, incluidas las rutas que omiten la persistencia en cola, y de nuevo antes de reproducir una intención recuperada. El contexto incluye cfg, channel, to, accountId y una phase de live o recovery.

Devuelva { status: "allowed" } para continuar. Devuelva { status: "permanent_rejection", reason } cuando la entrega no deba persistirse, enviarse directamente ni reproducirse. Un rechazo en vivo falla antes de crear la cola, ejecutar los hooks de mensajes o realizar trabajo en la plataforma. Un rechazo durante la recuperación marca el registro en cola como fallido y omite la reconciliación y la reproducción. Omitir el hook equivale a permitir la entrega.

El hook es una decisión de admisión síncrona, no una ruta de envío. Lea únicamente la configuración o el estado de ejecución ya cargados; no realice operaciones de red, del sistema de archivos ni otras operaciones de E/S asíncronas. Las pruebas de contrato deben cubrir ambas fases y ambas variantes de resultado mediante ChannelMessageDurableFinalAdapter de openclaw/plugin-sdk/channel-outbound.

Despacho de compatibilidad

Compile el despacho de respuestas entrantes mediante dispatchChannelInboundReply(...) de channel-inbound. Mantenga la entrega de la plataforma en el adaptador de entrega; use channel-outbound para los adaptadores de mensajes, los envíos duraderos, los acuses, la vista previa en vivo y las opciones de la canalización de respuestas.