Refaktorierung des Nachrichtenlebenszyklus

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• Die Kernprimitive sollten Empfangen und Senden sein, nicht Antworten.
• Eine Antwort ist nur eine Relation auf einer ausgehenden Nachricht.
• Ein Turn ist eine praktische Vereinfachung für die Verarbeitung eingehender Nachrichten, nicht der Eigentümer der Zustellung.
• Senden muss kontextbasiert sein: begin, rendern, Preview oder Stream, final senden, committen, fehlschlagen.
• Empfangen muss ebenfalls kontextbasiert sein: normalisieren, deduplizieren, routen, aufzeichnen, dispatchen, Plattform-Ack, fehlschlagen.
• Das öffentliche Plugin-SDK sollte auf eine kleine Channel-Message-Oberfläche reduziert werden.

​

Probleme

• Einfache eingehende Adapter verwenden runtime.channel.turn.run.
• Umfassendere Adapter verwenden runtime.channel.turn.runPrepared.
• Legacy-Helfer verwenden dispatchInboundReplyWithBase, recordInboundSessionAndDispatchReply, Antwort-Payload-Helfer, Antwort-Chunking, Antwortreferenzen und ausgehende Runtime-Helfer.
• Preview-Streaming lebt in Channel-spezifischen Dispatchern.
• Dauerhaftigkeit für die finale Zustellung wird um vorhandene Antwort-Payload-Pfade herum ergänzt.

Telegram polling update acked
  -> assistant final text exists
  -> process restarts before sendMessage succeeds
  -> final response is lost

​

Ziele

• Ein Core-Lebenszyklus für alle Empfangs- und Sendepfade von Channel-Nachrichten.
• Dauerhafte finale Sends standardmäßig im neuen Nachrichten-Lebenszyklus, nachdem ein Adapter Replay-sicheres Verhalten deklariert.
• Gemeinsame Semantik für Preview, Bearbeitung, Stream, Finalisierung, Retry, Wiederherstellung und Belege.
• Eine kleine Plugin-SDK-Oberfläche, die Drittanbieter-Plugins lernen und pflegen können.
• Kompatibilität für vorhandene channel.turn-Aufrufer während der Migration.
• Klare Erweiterungspunkte für neue Channel-Fähigkeiten.
• Keine plattformspezifischen Branches im Core.
• Keine Token-Delta-Channel-Nachrichten. Channel-Streaming bleibt Nachrichten-Preview, Bearbeitung, Anhängen oder abgeschlossene Blockzustellung.
• Strukturierte Metadaten mit OpenClaw-Ursprung für operative/Systemausgaben, damit sichtbare Gateway-Fehler in gemeinsam genutzten bot-fähigen Räumen nicht erneut als neue Prompts eingehen.

​

Nicht-Ziele

• runtime.channel.turn.* in der ersten Phase nicht entfernen.
• Nicht jeden Channel in dasselbe native Transportverhalten zwingen.
• Dem Core keine Telegram-Themen, nativen Slack-Streams, Matrix-Redaktionen, Feishu-Karten, QQ-Voice oder Teams-Aktivitäten beibringen.
• Nicht alle internen Migrationshelfer als stabile SDK-API veröffentlichen.
• Retries sollen abgeschlossene nicht idempotente Plattformoperationen nicht erneut abspielen.

​

Referenzmodell

• Chat
• Thread
• Channel
• Message
• Adaptermethoden wie postMessage, editMessage, deleteMessage, stream, startTyping und History-Fetches
• einen State-Adapter für Deduplizierung, Locks, Queues und Persistenz

• Dauerhafte ausgehende Send-Absichten vor direkten Transportaufrufen.
• Explizite Sendekontexte mit Begin, Commit und Fail.
• Empfangskontexte, die die Plattform-Ack-Policy kennen.
• Belege, die einen Neustart überleben und Bearbeitungen, Löschungen, Wiederherstellung und Duplikatunterdrückung steuern können.
• Ein kleineres öffentliches SDK. Gebündelte Plugins können interne Runtime-Helfer verwenden, aber Drittanbieter-Plugins sollten eine kohärente Message-API sehen.
• Agent-spezifisches Verhalten: Sitzungen, Transkripte, Block-Streaming, Tool-Fortschritt, Genehmigungen, Mediendirektiven, stille Antworten und Verlauf von Gruppen-Erwähnungen.

​

Core-Modell

core.messages.receive(...)
core.messages.send(...)
core.messages.live(...)
core.messages.state(...)

​

Nachrichtenbegriffe

​

Nachricht

type ChannelMessage = {
  id: string;
  channel: string;
  accountId?: string;
  direction: "inbound" | "outbound";
  target: MessageTarget;
  sender?: MessageActor;
  body?: MessageBody;
  attachments?: MessageAttachment[];
  relation?: MessageRelation;
  origin?: MessageOrigin;
  timestamp?: number;
  raw?: unknown;
};

​

Ziel

type MessageTarget = {
  kind: "direct" | "group" | "channel" | "thread";
  id: string;
  label?: string;
  spaceId?: string;
  parentId?: string;
  threadId?: string;
  nativeChannelId?: string;
};

​

Relation

type MessageRelation =
  | {
      kind: "reply";
      inboundMessageId?: string;
      replyToId?: string;
      threadId?: string;
      quote?: MessageQuote;
    }
  | {
      kind: "followup";
      sessionKey?: string;
      previousMessageId?: string;
    }
  | {
      kind: "broadcast";
      reason?: string;
    }
  | {
      kind: "system";
      reason:
        | "approval"
        | "task"
        | "hook"
        | "cron"
        | "subagent"
        | "message_tool"
        | "cli"
        | "control_ui"
        | "automation"
        | "error";
    };

​

Ursprung

type MessageOrigin =
  | {
      source: "openclaw";
      schemaVersion: 1;
      kind: "gateway_failure";
      code: "agent_failed_before_reply" | "missing_api_key" | "model_login_expired";
      echoPolicy: "drop_bot_room_echo";
    }
  | {
      source: "user" | "external_bot" | "platform" | "unknown";
    };

​

Beleg

type MessageReceipt = {
  primaryPlatformMessageId?: string;
  platformMessageIds: string[];
  parts: MessageReceiptPart[];
  threadId?: string;
  replyToId?: string;
  editToken?: string;
  deleteToken?: string;
  url?: string;
  sentAt: number;
  raw?: unknown;
};

type MessageReceiptPart = {
  platformMessageId: string;
  kind: "text" | "media" | "voice" | "card" | "preview" | "unknown";
  index: number;
  threadId?: string;
  replyToId?: string;
  editToken?: string;
  deleteToken?: string;
  url?: string;
  raw?: unknown;
};

​

Empfangskontext

type MessageReceiveContext = {
  id: string;
  channel: string;
  accountId?: string;
  input: ChannelMessage;
  ack: ReceiveAckController;
  route: MessageRouteController;
  session: MessageSessionController;
  log: MessageLifecycleLogger;

  dedupe(): Promise<ReceiveDedupeResult>;
  resolve(): Promise<ResolvedInboundMessage>;
  record(resolved: ResolvedInboundMessage): Promise<RecordResult>;
  dispatch(recorded: RecordResult): Promise<DispatchResult>;
  commit(result: DispatchResult): Promise<void>;
  fail(error: unknown): Promise<void>;
};

platform event
  -> begin receive context
  -> normalize
  -> classify
  -> dedupe and self-echo gate
  -> route and authorize
  -> record inbound session metadata
  -> dispatch agent run
  -> durable outbound sends happen through send context
  -> commit receive
  -> ack platform when policy allows

• Transport-Ack: teilt dem Plattform-Webhook oder Socket mit, dass OpenClaw den Event-Umschlag akzeptiert hat. Einige Plattformen erfordern dies vor dem Dispatch.
• Polling-Offset-Ack: bewegt einen Cursor weiter, damit dasselbe Event nicht erneut abgerufen wird. Dies darf nicht über Arbeit hinaus fortschreiten, die nicht wiederhergestellt werden kann.
• Eingehender Record-Ack: bestätigt, dass OpenClaw genügend eingehende Metadaten persistiert hat, um eine erneute Zustellung zu deduplizieren und zu routen.
• Benutzersichtbarer Beleg: optionales Lese-/Status-/Typing-Verhalten; niemals eine Dauerhaftigkeitsgrenze.

function shouldDropOpenClawEcho(params: {
  origin?: MessageOrigin;
  isBotAuthor: boolean;
  isRoomish: boolean;
}): boolean {
  return (
    params.isBotAuthor &&
    params.isRoomish &&
    params.origin?.source === "openclaw" &&
    params.origin.kind === "gateway_failure" &&
    params.origin.echoPolicy === "drop_bot_room_echo"
  );
}

type ReceiveAckPolicy =
  | { kind: "immediate"; reason: "webhook-timeout" | "platform-contract" }
  | { kind: "after-record" }
  | { kind: "after-durable-send" }
  | { kind: "manual" };

​

Sendekontext

type MessageSendContext = {
  id: string;
  channel: string;
  accountId?: string;
  message: ChannelMessage;
  intent: DurableSendIntent;
  attempt: number;
  signal: AbortSignal;
  previousReceipt?: MessageReceipt;
  preview?: LiveMessageState;
  log: MessageLifecycleLogger;

  render(): Promise<RenderedMessageBatch>;
  previewUpdate(rendered: RenderedMessageBatch): Promise<LiveMessageState>;
  send(rendered: RenderedMessageBatch): Promise<MessageReceipt>;
  edit(receipt: MessageReceipt, rendered: RenderedMessageBatch): Promise<MessageReceipt>;
  delete(receipt: MessageReceipt): Promise<void>;
  commit(receipt: MessageReceipt): Promise<void>;
  fail(error: unknown): Promise<void>;
};

await core.messages.withSendContext(message, async (ctx) => {
  const rendered = await ctx.render();

  if (ctx.preview?.canFinalizeInPlace) {
    return await ctx.edit(ctx.preview.receipt, rendered);
  }

  return await ctx.send(rendered);
});

begin durable intent
  -> render
  -> optional preview/edit/stream work
  -> mark sending
  -> final platform send or final edit
  -> mark committing with raw receipt
  -> commit receipt
  -> ack durable intent
  -> fail durable intent on classified failure

type MessageDurabilityPolicy = "required" | "best_effort" | "disabled";

type RenderedMessageBatch = {
  units: RenderedMessageUnit[];
  atomicity: "all_or_retry_remaining" | "best_effort_parts";
  idempotencyKey: string;
};

type RenderedMessageUnit = {
  index: number;
  kind: "text" | "media" | "voice" | "card" | "preview" | "unknown";
  payload: unknown;
  required: boolean;
};

​

Live-Kontext

type MessageLiveAdapter = {
  begin?(ctx: MessageSendContext): Promise<LiveMessageState>;
  update?(
    ctx: MessageSendContext,
    state: LiveMessageState,
    update: LiveMessageUpdate,
  ): Promise<LiveMessageState>;
  finalize?(
    ctx: MessageSendContext,
    state: LiveMessageState,
    final: RenderedMessageBatch,
  ): Promise<MessageReceipt>;
  cancel?(
    ctx: MessageSendContext,
    state: LiveMessageState,
    reason: LiveCancelReason,
  ): Promise<void>;
};

type LiveMessageState = {
  mode: "partial" | "block" | "progress" | "native";
  receipt?: MessageReceipt;
  visibleSince?: number;
  canFinalizeInPlace: boolean;
  lastRenderedHash?: string;
  staleAfterMs?: number;
};

• Telegram-Senden plus Bearbeiten der Vorschau, mit frischem Finale nach veraltetem Vorschaualter.
• Discord-Senden plus Bearbeiten der Vorschau, Abbrechen bei Medien/Fehler/expliziter Antwort.
• Slack nativer Stream oder Entwurfsvorschau abhängig von der Thread-Form.
• Finalisierung von Mattermost-Entwurfsbeiträgen.
• Finalisierung von Matrix-Entwurfsereignissen oder Redaction bei Abweichung.
• Teams nativer Fortschrittsstream.
• QQ Bot-Stream oder angesammelter Fallback.

​

Adapter-Oberfläche

import { defineChannelMessageAdapter } from "openclaw/plugin-sdk/channel-message";

type ChannelMessageAdapter = {
  receive?: MessageReceiveAdapter;
  send: MessageSendAdapter;
  live?: MessageLiveAdapter;
  origin?: MessageOriginAdapter;
  render?: MessageRenderAdapter;
  capabilities: MessageCapabilities;
};

type MessageSendAdapter = {
  send(ctx: MessageSendContext, rendered: RenderedMessageBatch): Promise<MessageReceipt>;
  edit?(
    ctx: MessageSendContext,
    receipt: MessageReceipt,
    rendered: RenderedMessageBatch,
  ): Promise<MessageReceipt>;
  delete?(ctx: MessageSendContext, receipt: MessageReceipt): Promise<void>;
  classifyError?(ctx: MessageSendContext, error: unknown): DeliveryFailureKind;
  reconcileUnknownSend?(ctx: MessageSendContext): Promise<MessageReceipt | null>;
  afterSendSuccess?(ctx: MessageSendContext, receipt: MessageReceipt): Promise<void>;
  afterCommit?(ctx: MessageSendContext, receipt: MessageReceipt): Promise<void>;
};

type MessageReceiveAdapter<TRaw = unknown> = {
  normalize(raw: TRaw, ctx: MessageNormalizeContext): Promise<ChannelMessage>;
  classify?(message: ChannelMessage): Promise<MessageEventClass>;
  preflight?(message: ChannelMessage, event: MessageEventClass): Promise<MessagePreflightResult>;
  ackPolicy?(message: ChannelMessage, event: MessageEventClass): ReceiveAckPolicy;
};

type MessageOriginAdapter<TRaw = unknown, TNative = unknown> = {
  encode?(origin: MessageOrigin): TNative | undefined;
  decode?(raw: TRaw): MessageOrigin | undefined;
};

type MessageCapabilities = {
  text: { maxLength?: number; chunking?: boolean };
  attachments?: {
    upload: boolean;
    remoteUrl: boolean;
    voice?: boolean;
  };
  threads?: {
    reply: boolean;
    topic?: boolean;
    nativeThread?: boolean;
  };
  live?: {
    edit: boolean;
    delete: boolean;
    nativeStream?: boolean;
    progress?: boolean;
  };
  delivery?: {
    idempotencyKey?: boolean;
    retryAfter?: boolean;
    receiptRequired?: boolean;
  };
};

​

Reduzierung des öffentlichen SDK

• reply-runtime
• reply-dispatch-runtime
• reply-reference
• reply-chunking
• reply-payload
• inbound-reply-dispatch
• channel-reply-pipeline
• die meisten öffentlichen Verwendungen von outbound-runtime
• Ad-hoc-Helper für den Lebenszyklus von Entwurfsstreams

​

Beziehung zu channel turn

channel.turn.run
  -> messages.receive context
  -> session dispatch
  -> messages.send context for visible output

channel-owned dispatcher
  -> messages.receive record/finalize bridge
  -> messages.live for preview/progress
  -> messages.send for final delivery

​

Kompatibilitätsleitplanken

• channel.turn.run und dispatchAssembledChannelTurn verwenden den Zustellungs-Callback des Kanals, es sei denn, dieser Kanal stellt explizit ein geprüftes dauerhaftes Richtlinien-/Optionsobjekt bereit.
• channel.turn.runPrepared bleibt kanaleigen, bis der vorbereitete Dispatcher explizit den Sendekontext aufruft.
• Öffentliche Kompatibilitäts-Helper wie recordInboundSessionAndDispatchReply, dispatchInboundReplyWithBase und Direct-DM-Helper injizieren niemals generische dauerhafte Zustellung vor dem vom Aufrufer bereitgestellten deliver- oder reply-Callback.

• Dauerhafte endgültige Zustellung gibt einen diskriminierten Status zurück. handled_visible und handled_no_send sind terminal; unsupported und not_applicable können auf kanaleigene Zustellung zurückfallen; failed propagiert den Sendefehler.
• Generische dauerhafte endgültige Zustellung wird durch Adapterfähigkeiten wie stille Zustellung, Erhaltung des Antwortziels, Erhaltung nativer Zitate und Hooks zum Senden von Nachrichten gesteuert. Fehlende Parität sollte kanaleigene Zustellung wählen, keinen generischen Sendepfad, der für Benutzer sichtbares Verhalten ändert.
• Queue-gestützte dauerhafte Sends stellen eine Referenz auf die Zustellungsabsicht bereit. Bestehende pendingFinalDelivery*-Sitzungsfelder können während der Umstellung die Intent-ID tragen; der Endzustand ist ein MessageSendIntent-Store anstelle von eingefrorenem Antworttext plus Ad-hoc-Kontextfeldern.

• Der generische Sendeadapter führt dasselbe Rendering- und Transportverhalten aus wie der alte direkte Pfad.
• Lokale Nebeneffekte nach dem Senden bleiben über den Sendekontext erhalten.
• Der Adapter gibt Belege oder Zustellergebnisse mit allen Plattform-Nachrichten-IDs zurück.
• Vorbereitete Dispatcher-Pfade rufen entweder den neuen Sendekontext auf oder bleiben als außerhalb der dauerhaften Garantie dokumentiert.
• Fallback-Zustellung verarbeitet jede projizierte Payload, nicht nur die erste.
• Dauerhafte Fallback-Zustellung zeichnet das gesamte projizierte Payload-Array als einen erneut abspielbaren Intent oder Batch-Plan auf.

• Die iMessage-Monitor-Zustellung zeichnet gesendete Nachrichten nach einem erfolgreichen Send in einem Echo-Cache auf. Dauerhafte endgültige Sends müssen diesen Cache weiterhin befüllen, andernfalls kann OpenClaw seine eigenen endgültigen Antworten erneut als eingehende Benutzernachrichten aufnehmen.
• Tlon hängt optional eine Modellsignatur an und zeichnet nach Gruppenantworten teilgenommene Threads auf. Generische dauerhafte Zustellung darf diese Effekte nicht umgehen; verschieben Sie sie entweder in Tlon-Render-/Sende-/Finalisierungsadapter oder lassen Sie Tlon auf dem kanaleigenen Pfad.
• Discord und andere vorbereitete Dispatcher besitzen bereits direkte Zustellung und Vorschauverhalten. Sie sind nicht von einer dauerhaften Garantie für zusammengestellte Turns abgedeckt, bis ihre vorbereiteten Dispatcher endgültige Nachrichten ausdrücklich durch den Sendekontext leiten.
• Die stille Telegram-Fallback-Zustellung muss das vollständige projizierte Payload-Array zustellen. Eine Ein-Payload-Abkürzung kann nach der Projektion zusätzliche Fallback-Payloads verwerfen.
• LINE, BlueBubbles, Zalo, Nostr und andere bestehende zusammengestellte/Helfer-Pfade können Reply-Token-Behandlung, Medien-Proxying, Caches für gesendete Nachrichten, Loading-/Status- Bereinigung oder reine Callback-Ziele haben. Sie bleiben auf kanaleigener Zustellung, bis diese Semantik vom Sendeadapter dargestellt und durch Tests verifiziert ist.
• Direct-DM-Helfer können einen Antwort-Callback haben, der das einzige korrekte Transportziel ist. Generischer ausgehender Versand darf nicht aus OriginatingTo oder To raten und diesen Callback überspringen.
• OpenClaw-Gateway-Fehlerausgabe muss für Menschen sichtbar bleiben, aber getaggte, botverfasste Raum-Echos müssen vor der allowBots-Autorisierung verworfen werden. Kanäle dürfen dies außer als kurzen Notfall-Stopgap nicht mit sichtbaren Textpräfix-Filtern implementieren; der dauerhafte Vertrag ist strukturierte Ursprungsmetadaten.

​

Interner Speicher

type DurableSendIntent = {
  id: string;
  idempotencyKey: string;
  channel: string;
  accountId?: string;
  message: ChannelMessage;
  batch?: RenderedMessageBatch;
  liveState?: LiveMessageState;
  status:
    | "pending"
    | "sending"
    | "committing"
    | "unknown_after_send"
    | "sent"
    | "failed"
    | "cancelled";
  attempt: number;
  nextAttemptAt?: number;
  receipt?: MessageReceipt;
  partialReceipt?: MessageReceipt;
  failure?: DeliveryFailure;
  createdAt: number;
  updatedAt: number;
};

load pending or sending intents
  -> acquire idempotency lock
  -> skip if receipt already committed
  -> reconstruct send context
  -> render if needed
  -> reconcile unknown_after_send if needed
  -> call adapter send/edit/finalize
  -> commit receipt, mark unknown_after_send, or schedule retry

​

Fehlerklassen

type DeliveryFailureKind =
  | "transient"
  | "rate_limit"
  | "auth"
  | "permission"
  | "not_found"
  | "invalid_payload"
  | "conflict"
  | "cancelled"
  | "unknown";

• transient und rate_limit erneut versuchen.
• invalid_payload nicht erneut versuchen, außer es gibt einen Rendering-Fallback.
• auth oder permission nicht erneut versuchen, bis sich die Konfiguration ändert.
• Bei not_found die Live-Finalisierung von Bearbeiten auf frisches Senden zurückfallen lassen, wenn der Kanal dies als sicher deklariert.
• Bei conflict Beleg-/Idempotenzregeln verwenden, um zu entscheiden, ob die Nachricht bereits existiert.
• Jeder Fehler, nachdem der Adapter möglicherweise Plattform-I/O abgeschlossen hat, aber vor dem Beleg- Commit, wird zu unknown_after_send, außer der Adapter kann beweisen, dass die Plattform- Operation nicht stattgefunden hat.

​

Kanalzuordnung

​

Migrationsplan

​

Phase 1: Interne Nachrichten-Domain

• Fügen Sie src/channels/message/*-Typen für Nachrichten, Ziele, Beziehungen, Ursprünge, Empfangsbestätigungen, Fähigkeiten, persistente Intents, Empfangskontext, Sendekontext, Live-Kontext und Fehlerklassen hinzu.
• Fügen Sie origin?: MessageOrigin zum Payload-Typ der Migrationsbridge hinzu, der von der aktuellen Antwortzustellung verwendet wird, und verschieben Sie dieses Feld dann nach ChannelMessage und in gerenderte Nachrichtentypen, während das Refactoring Antwort-Payloads ersetzt.
• Halten Sie dies intern, bis Adapter und Tests die Form belegen.
• Fügen Sie reine Unit-Tests für Zustandsübergänge und Serialisierung hinzu.

​

Phase 2: Persistenter Sendekern

• Verschieben Sie die bestehende ausgehende Queue von Antwort-Payload-Persistenz zu persistenten Nachrichtensende-Intents.
• Lassen Sie einen persistenten Sende-Intent ein projiziertes Payload-Array oder einen Batch-Plan tragen, nicht nur einen einzelnen Antwort-Payload.
• Bewahren Sie das aktuelle Queue-Wiederherstellungsverhalten durch Kompatibilitätskonvertierung.
• Lassen Sie deliverOutboundPayloads messages.send aufrufen.
• Machen Sie persistente finale Sendungen zum Standard und schlagen Sie geschlossen fehl, wenn der persistente Intent im neuen Nachrichtenlebenszyklus nicht geschrieben werden kann, nachdem der Adapter Replay-Sicherheit deklariert hat. Bestehende Kanal-Turn- und SDK-Kompatibilitätspfade bleiben während dieser Phase standardmäßig Direktversand.
• Zeichnen Sie Empfangsbestätigungen konsistent auf.
• Geben Sie Empfangsbestätigungen und Zustellungsergebnisse an den ursprünglichen Dispatcher-Aufrufer zurück, statt persistentes Senden als terminalen Seiteneffekt zu behandeln.
• Persistieren Sie den Nachrichtenursprung durch persistente Sende-Intents, damit Wiederherstellung, Replay und segmentierte Sendungen die operative OpenClaw-Provenienz bewahren.

​

Phase 3: Kanal-Turn-Bridge

• Implementieren Sie channel.turn.run und dispatchAssembledChannelTurn auf Basis von messages.receive und messages.send neu.
• Halten Sie aktuelle Faktentypen stabil.
• Behalten Sie standardmäßig Legacy-Verhalten bei. Ein Assembled-Turn-Kanal wird nur dann persistent, wenn sein Adapter ausdrücklich mit einer replay-sicheren Persistenzrichtlinie zustimmt.
• Behalten Sie durable: false als Kompatibilitäts-Ausweichmöglichkeit für Pfade bei, die native Bearbeitungen finalisieren und noch nicht sicher replayfähig sind, verlassen Sie sich jedoch nicht auf false-Marker, um nicht migrierte Kanäle zu schützen.
• Aktivieren Sie Assembled-Turn-Persistenz standardmäßig nur im neuen Nachrichtenlebenszyklus, nachdem die Kanalzuordnung belegt, dass der generische Sendepfad die alte Kanal- Zustellungssemantik bewahrt.

​

Phase 4: Vorbereitete Dispatcher-Bridge

• Ersetzen Sie deliverDurableInboundReplyPayload durch eine Sendekontext-Bridge.
• Behalten Sie den alten Helper als Wrapper bei.
• Portieren Sie Telegram, WhatsApp, Slack, Signal, iMessage und Discord zuerst, weil sie bereits Arbeit an dauerhaften abschließenden Antworten oder einfachere Sendepfade haben.
• Behandeln Sie jeden vorbereiteten Dispatcher als nicht abgedeckt, bis er sich explizit für den Sendekontext entscheidet. Dokumentation und Changelog-Einträge müssen „zusammengesetzte Kanal-Turns“ sagen oder die migrierten Kanalpfade nennen, statt alle automatischen abschließenden Antworten zu beanspruchen.
• Halten Sie recordInboundSessionAndDispatchReply, Direct-DM-Helper und ähnliche öffentliche Kompatibilitäts-Helper verhaltenserhaltend. Sie können später ein explizites Sendekontext-Opt-in bereitstellen, dürfen aber nicht automatisch generische dauerhafte Zustellung vor dem vom Aufrufer verantworteten Zustellungs-Callback versuchen.

​

Phase 5: Vereinheitlichter Live-Lebenszyklus

• Erstellen Sie messages.live mit zwei Proof-Adaptern:
  • Telegram für Senden plus Bearbeiten plus veralteten abschließenden Versand.
  • Matrix für Entwurfsfinalisierung plus Redaktions-Fallback.
• Migrieren Sie danach Discord, Slack, Mattermost, Teams, QQ Bot und Feishu.
• Löschen Sie duplizierten Code zur Preview-Finalisierung erst, nachdem jeder Kanal Paritätstests hat.

​

Phase 6: Öffentliches SDK

• Fügen Sie openclaw/plugin-sdk/channel-message hinzu.
• Dokumentieren Sie es als bevorzugte API für Kanal-Plugins.
• Aktualisieren Sie Paket-Exports, Entrypoint-Inventar, generierte API-Baselines und Plugin-SDK-Dokumentation.
• Nehmen Sie MessageOrigin, Origin-Encode/Decode-Hooks und das gemeinsame Prädikat shouldDropOpenClawEcho in die SDK-Oberfläche für Kanalnachrichten auf.
• Behalten Sie Kompatibilitäts-Wrapper für alte Subpfade bei.
• Markieren Sie antwortbenannte SDK-Helper in der Dokumentation als veraltet, nachdem gebündelte Plugins migriert sind.

​

Phase 7: Alle Sender

• Cron- und Heartbeat-Benachrichtigungen
• Aufgabenabschlüsse
• Hook-Ergebnisse
• Genehmigungsaufforderungen und Genehmigungsergebnisse
• Sendevorgänge des Message-Tools
• Abschlussankündigungen von Subagents
• explizite CLI- oder Control-UI-Sendevorgänge
• Automatisierungs-/Broadcast-Pfade

​

Phase 8: Turn als veraltet markieren

• Behalten Sie channel.turn für mindestens ein Kompatibilitätsfenster als Wrapper bei.
• Veröffentlichen Sie Migrationshinweise.
• Führen Sie Plugin-SDK-Kompatibilitätstests gegen alte Importe aus.
• Entfernen oder verstecken Sie alte interne Helper erst, nachdem kein gebündeltes Plugin sie mehr benötigt und Drittanbieter-Verträge einen stabilen Ersatz haben.

​

Testplan

• Serialisierung und Wiederherstellung dauerhafter Sendeabsichten.
• Wiederverwendung von Idempotency-Schlüsseln und Unterdrückung von Duplikaten.
• Receipt-Commit und Überspringen bei Replay.
• unknown_after_send-Wiederherstellung, die vor dem Replay abgleicht, wenn ein Adapter Abgleich unterstützt.
• Richtlinie zur Fehlerklassifizierung.
• Sequenzierung der Receive-Ack-Richtlinie.
• Relationszuordnung für Antwort-, Follow-up-, System- und Broadcast-Sendevorgänge.
• Origin-Factory für Gateway-Fehler und Prädikat shouldDropOpenClawEcho.
• Origin-Erhalt durch Payload-Normalisierung, Chunking, Serialisierung der dauerhaften Queue und Wiederherstellung.

• Einfacher channel.turn.run-Adapter zeichnet weiterhin auf und sendet.
• Legacy-Zustellung zusammengesetzter Turns wird nicht dauerhaft, es sei denn, der Kanal entscheidet sich explizit dafür.
• channel.turn.runPrepared-Bridge zeichnet weiterhin auf und finalisiert.
• Öffentliche Kompatibilitäts-Helper rufen standardmäßig vom Aufrufer verantwortete Zustellungs-Callbacks auf und führen keinen generischen Versand vor diesen Callbacks aus.
• Dauerhafte Fallback-Zustellung spielt nach einem Neustart das gesamte projizierte Payload-Array erneut ab und kann spätere Payloads nach einem frühen Absturz nicht unaufgezeichnet lassen.
• Dauerhafte Zustellung zusammengesetzter Turns gibt Plattformnachrichten-IDs an den gepufferten Dispatcher zurück.
• Benutzerdefinierte Zustellungs-Hooks geben weiterhin Plattformnachrichten-IDs zurück, wenn dauerhafte Zustellung deaktiviert oder nicht verfügbar ist.
• Abschließende Antwort überlebt einen Neustart zwischen Assistentenabschluss und Plattformversand.
• Preview-Entwurf wird vor Ort finalisiert, wenn erlaubt.
• Preview-Entwurf wird abgebrochen oder redigiert, wenn Medien-/Fehler-/Antwortziel-Abweichung normale Zustellung erfordert.
• Block-Streaming und Preview-Streaming liefern nicht beide denselben Text.
• Früh gestreamte Medien werden in der abschließenden Zustellung nicht dupliziert.

• Telegram-Themenantwort mit Polling-Ack verzögert bis zum sicheren Completed-Wasserzeichen des Receive-Kontexts.
• Telegram-Polling-Wiederherstellung für akzeptierte, aber nicht zugestellte Updates, abgedeckt durch das persistierte Modell des Safe-Completed-Offsets.
• Veraltete Telegram-Preview sendet frische abschließende Antwort und räumt Preview auf.
• Telegram-Silent-Fallback sendet jeden projizierten Fallback-Payload.
• Dauerhaftigkeit des Telegram-Silent-Fallbacks zeichnet das vollständige projizierte Fallback-Array atomar auf, nicht eine einzelne Single-Payload-Dauerabsicht pro Schleifendurchlauf.
• Discord-Preview-Abbruch bei Medien/Fehler/expliziter Antwort.
• Abschlüsse vorbereiteter Discord-Dispatcher laufen durch den Sendekontext, bevor Dokumentation oder Changelog Dauerhaftigkeit abschließender Discord-Antworten beanspruchen.
• Dauerhafte abschließende iMessage-Sendevorgänge befüllen den Echo-Cache gesendeter Nachrichten des Monitors.
• Legacy-Zustellungspfade von LINE, BlueBubbles, Zalo und Nostr werden nicht durch generischen dauerhaften Versand umgangen, bis ihre Adapter-Paritätstests existieren.
• Direct-DM-/Nostr-Callback-Zustellung bleibt maßgeblich, sofern sie nicht explizit zu einem vollständigen Nachrichtenziel und replay-sicheren Sendeadapter migriert wurde.
• Getaggte Slack-OpenClaw-Gateway-Fehlermeldungen bleiben ausgehend sichtbar, getaggte Bot-Raum-Echos werden vor allowBots verworfen, und ungetaggte Bot-Nachrichten mit demselben sichtbaren Text folgen weiterhin der normalen Bot-Autorisierung.
• Slack-nativer Stream-Fallback auf Entwurfs-Preview in Top-Level-DMs.
• Matrix-Preview-Finalisierung und Redaktions-Fallback.
• Getaggte Matrix-Raum-Echos von OpenClaw-Gateway-Fehlern aus konfigurierten Bot- Konten werden vor der allowBots-Behandlung verworfen.
• Cascade-Audits für Gateway-Fehler in gemeinsam genutzten Räumen von Discord und Google Chat decken allowBots-Modi ab, bevor dort generischer Schutz beansprucht wird.
• Mattermost-Entwurfsfinalisierung und Fresh-Send-Fallback.
• Teams-native Fortschrittsfinalisierung.
• Feishu-Unterdrückung doppelter Abschlüsse.
• QQ-Bot-Accumulator-Timeout-Fallback.
• Dauerhafte abschließende Tlon-Sendevorgänge erhalten Model-Signature-Rendering und Tracking beteiligter Threads.
• Einfache dauerhafte abschließende Sendevorgänge für WhatsApp, Signal, iMessage, Google Chat, LINE, IRC, Nostr, Nextcloud Talk, Synology Chat, Tlon, Twitch, Zalo und Zalo Personal.

• Zielgerichtete Vitest-Dateien während der Entwicklung.
• pnpm check:changed in Testbox für die gesamte geänderte Oberfläche.
• Breiteres pnpm check in Testbox vor dem Landen des vollständigen Refactorings oder nach öffentlichen SDK-/Export-Änderungen.
• Live- oder qa-channel-Smoke für mindestens einen bearbeitungsfähigen Kanal und einen einfachen Nur-Senden-Kanal, bevor Kompatibilitäts-Wrapper entfernt werden.

​

Offene Fragen

• Ob Telegram die grammY-Runner-Quelle irgendwann durch eine vollständig dauerhafte Polling-Quelle ersetzen sollte, die Plattform-Redelivery steuern kann, nicht nur das persistierte OpenClaw-Neustart-Wasserzeichen.
• Ob dauerhafter Live-Preview-Status im selben Queue-Record wie die abschließende Sendeabsicht oder in einem benachbarten Live-State-Store gespeichert werden sollte.
• Wie lange Kompatibilitäts-Wrapper dokumentiert bleiben, nachdem plugin-sdk/channel-message ausgeliefert wurde.
• Ob Drittanbieter-Plugins Receive-Adapter direkt implementieren oder nur Normalize-/Send-/Live-Hooks über defineChannelMessageAdapter bereitstellen sollten.
• Welche Receipt-Felder sicher im öffentlichen SDK statt im internen Runtime- Status offengelegt werden können.
• Ob Seiteneffekte wie Self-Echo-Caches und Markierungen beteiligter Threads als Sendekontext-Hooks, adaptereigene Finalisierungsschritte oder Receipt-Abonnenten modelliert werden sollten.
• Welche Kanäle native Origin-Metadaten haben, welche persistierte ausgehende Registries benötigen und welche keine zuverlässige kanalübergreifende Echo-Unterdrückung bieten können.

​

Akzeptanzkriterien

• Jeder gebündelte Nachrichtenkanal sendet abschließende sichtbare Ausgabe über messages.send.
• Jeder eingehende Nachrichtenkanal tritt über messages.receive oder einen dokumentierten Kompatibilitäts-Wrapper ein.
• Jeder Preview-/Bearbeitungs-/Stream-Kanal verwendet messages.live für Entwurfsstatus und Finalisierung.
• channel.turn ist nur ein Wrapper.
• Antwortbenannte SDK-Helper sind Kompatibilitäts-Exports, nicht der empfohlene Pfad.
• Dauerhafte Wiederherstellung kann ausstehende abschließende Sendevorgänge nach einem Neustart erneut abspielen, ohne die abschließende Antwort zu verlieren oder bereits committete Sendevorgänge zu duplizieren; Sendevorgänge, deren Plattformergebnis unbekannt ist, werden vor dem Replay abgeglichen oder für diesen Adapter als mindestens-einmal dokumentiert.
• Dauerhafte abschließende Sendevorgänge schlagen geschlossen fehl, wenn die dauerhafte Absicht nicht geschrieben werden kann, sofern ein Aufrufer nicht explizit einen dokumentierten nicht-dauerhaften Modus ausgewählt hat.
• Legacy-Kanal-Turn- und SDK-Kompatibilitäts-Helper verwenden standardmäßig direkte kanalverantwortete Zustellung; generischer dauerhafter Versand ist nur explizites Opt-in.
• Receipts bewahren alle Plattformnachrichten-IDs für mehrteilige Zustellungen und eine primäre ID für Threading-/Bearbeitungskomfort.
• Dauerhafte Wrapper erhalten kanallokale Seiteneffekte, bevor direkte Zustellungs-Callbacks ersetzt werden.
• Vorbereitete Dispatcher zählen nicht als dauerhaft, bis ihr abschließender Zustellungspfad explizit den Sendekontext verwendet.
• Fallback-Zustellung verarbeitet jeden projizierten Payload.
• Dauerhafte Fallback-Zustellung zeichnet jeden projizierten Payload in einer replay-fähigen Absicht oder einem Batch-Plan auf.
• Von OpenClaw stammende Gateway-Fehlerausgabe ist für Menschen sichtbar, aber getaggte botverfasste Raum-Echos werden vor der Bot-Autorisierung auf Kanälen verworfen, die Unterstützung für den Origin-Vertrag deklarieren.
• Die Dokumentation erklärt Send, Receive, Live, State, Receipts, Relations, Fehler- richtlinie, Migration und Testabdeckung.

​

Verwandt

• Messages
• Streaming und Chunking
• Fortschrittsentwürfe
• Retry-Richtlinie
• Channel-Turn-Kernel