小纸条消息 lifecycle refactor：先把底下那条暗线看见

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：This page is the target design for replacing scattered 消息通道 turn, reply dispatch, preview 一边说一边送ing, and outbound deliv…。

This page is the target design for replacing scattered channel turn, reply dispatch, preview streaming, and outbound delivery helpers with one durable message lifecycle.

The short version:

commit, fail.

dispatch, platform ack, fail.

• The core primitives should be **receive** and **send**, not **reply**.
• A reply is only a relation on an outbound message.
• A turn is an inbound-processing convenience, not the owner of delivery.
• Sending must be context based: begin, render, preview or stream, final send,
• Receiving must be context based too: normalize, dedupe, route, record,
• The public plugin SDK should collapse to one small channel-message surface.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The current 消息通道 stack grew from several valid local needs: recordInboundSessionAndDispatchReply, reply payload helpers…。

The current channel stack grew from several valid local needs:

recordInboundSessionAndDispatchReply, reply payload helpers, reply chunking, reply references, and outbound runtime helpers.

• Simple inbound adapters use runtime.channel.turn.run.
• Rich adapters use runtime.channel.turn.runPrepared.
• Legacy helpers use dispatchInboundReplyWithBase,
• Preview streaming lives in channel-specific dispatchers.
• Final delivery durability is being added around existing reply payload paths.

That shape fixes local bugs, but it leaves OpenClaw with too many public concepts and too many places where delivery semantics can drift.

The reliability issue that exposed this is:

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

The target invariant is broader than Telegram: once core decides a visible outbound message should exist, the intent must be durable before the platform send is attempted, and the platform receipt must be committed after success. That gives OpenClaw at-least-once recovery. Exactly-once behavior exists only for adapters that can prove native idempotency or reconcile an unknown-after-send attempt against platform state before replay.

That is the end state for this refactor, not a description of every current path. During migration, existing outbound helpers can still fall through to a direct send when best-effort queue writes fail. The refactor is complete only when durable final sends fail closed or explicitly opt out with a documented non-durable policy.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：declares replay-safe behavior. semantics. edit, append, or completed block delivery. 门口的小门卫 failures do not re-enter sh…。

declares replay-safe behavior.

semantics.

edit, append, or completed block delivery.

gateway failures do not re-enter shared bot-enabled rooms as fresh prompts.

• One core lifecycle for all channel message receive and send paths.
• Durable final sends by default in the new message lifecycle after an adapter
• Shared preview, edit, stream, finalization, retry, recovery, and receipt
• A small plugin SDK surface that third-party plugins can learn and maintain.
• Compatibility for existing channel.turn callers during migration.
• Clear extension points for new channel capabilities.
• No platform-specific branches in core.
• No token-delta channel messages. Channel streaming remains message preview,
• Structured OpenClaw-origin metadata for operational/system output so visible

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Feishu cards, QQ voice, or Teams activities.

Feishu cards, QQ voice, or Teams activities.

• Do not remove runtime.channel.turn.* in the first phase.
• Do not force every channel into the same native transport behavior.
• Do not teach core Telegram topics, Slack native streams, Matrix redactions,
• Do not publish all internal migration helpers as stable SDK API.
• Do not make retries replay completed non-idempotent platform operations.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Vercel Chat has a good public mental 聪明脑袋模型: 一边说一边送, startTyping, and history fetches OpenClaw should borrow the vocabu…。

Vercel Chat has a good public mental model:

stream, startTyping, and history fetches

• Chat
• Thread
• Channel
• Message
• adapter methods such as postMessage, editMessage, deleteMessage,
• a state adapter for dedupe, locks, queues, and persistence

OpenClaw should borrow the vocabulary, not copy the surface.

What OpenClaw needs beyond that model:

duplicate suppression.

third-party plugins should see one coherent message API.

progress, approvals, media directives, silent replies, and group mention history.

• Durable outbound send intents before direct transport calls.
• Explicit send contexts with begin, commit, and fail.
• Receive contexts that know platform ack policy.
• Receipts that survive restart and can drive edits, deletes, recovery, and
• A smaller public SDK. Bundled plugins can use internal runtime helpers, but
• Agent-specific behavior: sessions, transcripts, block streaming, tool

thread.post() style promises are not enough for OpenClaw. They hide the transaction boundary that decides whether a send is recoverable.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The new domain should live under an internal core namespace such as src/消息通道s/小纸条消息/*. It has four concepts: receive ow…。

The new domain should live under an internal core namespace such as src/channels/message/*.

It has four concepts:

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

receive owns inbound lifecycle.

send owns outbound lifecycle.

live owns preview, edit, progress, and stream state.

state owns durable intent storage, receipts, idempotency, recovery, locks, and dedupe.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：A normalized 小纸条消息 is platform-neutral:。

A normalized message is platform-neutral:

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;
};

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The target describes where the 小纸条消息 lives:。

The target describes where the message lives:

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

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Reply is a relation, not an 对话接口 root: This lets the same send path handle normal replies, cron notifications, approval…。

Reply is a relation, not an API root:

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";
    };

This lets the same send path handle normal replies, cron notifications, approval prompts, task completions, message-tool sends, CLI or Control UI sends, subagent results, and automation sends.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Origin describes who produced a 小纸条消息 and how OpenClaw should treat echoes of that 小纸条消息. It is separate from relation:…。

Origin describes who produced a message and how OpenClaw should treat echoes of that message. It is separate from relation: a message can be a reply to a user and still be OpenClaw-originated operational output.

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";
    };

Core owns the meaning of OpenClaw-originated output. Channels own how that origin is encoded into their transport.

The first required use is gateway failure output. Humans should still see messages such as "Agent failed before reply" or "Missing API key", but tagged OpenClaw operational output must not be accepted as bot-authored input in shared rooms when allowBots is enabled.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Receipts are first-class: Receipts are the bridge from durable intent to future edit, delete, preview finalization, dup…。

Receipts are first-class:

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;
};

Receipts are the bridge from durable intent to future edit, delete, preview finalization, duplicate suppression, and recovery.

A receipt can describe one platform message or a multi-part delivery. Chunked text, media plus text, voice plus text, and card fallbacks must preserve all platform ids while still exposing a primary id for threading and later edits.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Receiving should not be a bare helper call. The core needs a context that knows dedupe, routing, session recording, and…。

Receiving should not be a bare helper call. The core needs a context that knows dedupe, routing, session recording, and platform ack policy.

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>;
};

Receive flow:

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

Ack is not one thing. The receive contract must keep these signals separate:

the event envelope. Some platforms require this before dispatch.

again. This must not advance past work that cannot be recovered.

dedupe and route a redelivery.

durability boundary.

• **Transport ack:** tells the platform webhook or socket that OpenClaw accepted
• **Polling offset ack:** advances a cursor so the same event is not fetched
• **Inbound record ack:** confirms OpenClaw persisted enough inbound metadata to
• **User-visible receipt:** optional read/status/typing behavior; never a

ReceiveAckPolicy controls transport or polling acknowledgement only. It must not be reused for read receipts or status reactions.

Before bot authorization, receive must apply the shared OpenClaw echo policy when the channel can decode message origin metadata:

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"
  );
}

This drop is tag-based, not text-based. A bot-authored room message with the same visible gateway-failure text but without OpenClaw origin metadata still goes through normal allowBots authorization.

Ack policy is explicit:

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

Telegram polling now uses the receive-context ack policy for its persisted restart watermark. The tracker still observes grammY updates as they enter the middleware chain, but OpenClaw persists only the safe completed update id after successful dispatch, leaving failed or lower pending updates replayable after a restart. Telegram's upstream getUpdates fetch offset is still controlled by the polling library, so the remaining deeper cut is a fully durable polling source if we need platform-level redelivery beyond OpenClaw's restart watermark. Webhook platforms may need immediate HTTP ack, but they still need inbound dedupe and durable outbound send intents because webhooks can redeliver.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Sending is also context based: Preferred orchestration: The helper expands to: The intent must exist before transport I…。

Sending is also context based:

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>;
};

Preferred orchestration:

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

The helper expands to:

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

The intent must exist before transport I/O. A restart after begin but before commit is recoverable.

The dangerous boundary is after platform success and before receipt commit. If a process dies there, OpenClaw cannot know whether the platform message exists unless the adapter provides native idempotency or a receipt reconciliation path. Those attempts must resume in unknown_after_send, not blindly replay. Channels without reconciliation may choose at-least-once replay only if duplicate visible messages are an acceptable, documented tradeoff for that channel and relation. The current SDK reconciliation bridge requires the adapter to declare reconcileUnknownSend, then asks durableFinal.reconcileUnknownSend to classify an unknown entry as sent, not_sent, or unresolved; only not_sent permits replay, and unresolved entries stay terminal or retry only the reconciliation check.

Durability policy must be explicit:

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

required means core must fail closed when it cannot write the durable intent. best_effort can fall through when persistence is unavailable. disabled keeps the old direct send behavior. During migration, legacy wrappers and public compatibility helpers default to disabled; they must not infer required from the fact that a channel has a generic outbound adapter.

Send contexts also own channel-local post-send effects. A migration is not safe if durable delivery bypasses local behavior that was previously attached to the channel's direct send path. Examples include self-echo suppression caches, thread participation markers, native edit anchors, model-signature rendering, and platform-specific duplicate guards. Those effects must either move into the send adapter, the render adapter, or a named send-context hook before that channel can enable durable generic final delivery.

Send helpers must return receipts all the way back to their caller. Durable wrappers cannot swallow message ids or replace a channel delivery result with undefined; buffered dispatchers use those ids for thread anchors, later edits, preview finalization, and duplicate suppression.

Fallback sends operate on batches, not single payloads. Silent-reply rewrites, media fallback, card fallback, and chunk projection can all produce more than one deliverable message, so a send context must either deliver the whole projected batch or explicitly document why only one payload is valid.

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;
};

When such a fallback is durable, the whole projected batch must be represented by one durable send intent or another atomic batch plan. Recording each payload one-by-one is not enough: a crash between payloads can leave a partial visible fallback with no durable record for the remaining payloads. Recovery must know which units already have receipts and either replay only missing units or mark the batch unknown_after_send until the adapter reconciles it.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Preview, edit, progress, and 一边说一边送 behavior should be one opt-in lifecycle. Live state is durable enough to recover or…。

Preview, edit, progress, and stream behavior should be one opt-in lifecycle.

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>;
};

Live state is durable enough to recover or suppress duplicates:

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

This should cover current behavior:

• Telegram send plus edit preview, with fresh final after stale preview age.
• Discord send plus edit preview, cancel on media/error/explicit reply.
• Slack native stream or draft preview depending on thread shape.
• Mattermost draft post finalization.
• Matrix draft event finalization or redaction on mismatch.
• Teams native progress stream.
• QQ Bot stream or accumulated fallback.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The public SDK target should be one subpath: Target shape: Send adapter: Receive adapter: Before preflight authorizatio…。

The public SDK target should be one subpath:

Target shape:

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

Send adapter:

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
;
  afterSendSuccess?(ctx: MessageSendContext, receipt: MessageReceipt): Promise<void>;
  afterCommit?(ctx: MessageSendContext, receipt: MessageReceipt): Promise<void>;
};

Receive adapter:

type MessageReceiveAdapter
TRaw
 = {
  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;
};

Before preflight authorization, core must run the shared OpenClaw echo predicate whenever origin.decode returns OpenClaw-origin metadata. The receive adapter supplies platform facts such as bot author and room shape; core owns the drop decision and ordering so channels do not reimplement text filters.

Origin adapter:

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

Core sets MessageOrigin. Channels only translate it to and from native transport metadata. Slack maps this to chat.postMessage({ metadata }) and inbound message.metadata; Matrix can map it to extra event content; channels without native metadata can use a receipt/outbound registry when that is the best available approximation.

Capabilities:

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;
  };
};

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The new public surface should absorb or deprecate these conceptual areas: Compatibility subpaths can remain as wrappers…。

The new public surface should absorb or deprecate these conceptual areas:

• reply-runtime
• reply-dispatch-runtime
• reply-reference
• reply-chunking
• reply-payload
• inbound-reply-dispatch
• channel-reply-pipeline
• most public uses of outbound-runtime
• ad hoc draft stream lifecycle helpers

Compatibility subpaths can remain as wrappers, but new third-party plugins should not need them.

Bundled plugins may keep internal helper imports through reserved runtime subpaths while migrating. Public docs should steer plugin authors to plugin-sdk/channel-message once it exists.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：runtime.消息通道.turn.* should stay during migration. It should become a compatibility adapter: 消息通道.turn.runPrepared shoul…。

runtime.channel.turn.* should stay during migration.

It should become a compatibility adapter:

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

channel.turn.runPrepared should also remain initially:

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

After all bundled plugins and known third-party compatibility paths are bridged, channel.turn can be deprecated. It should not be removed until there is a published SDK migration path and contract tests proving old plugins still work or fail with a clear version error.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：During migration, generic durable delivery is opt-in for any 消息通道 whose existing delivery callback has side effects bey…。

During migration, generic durable delivery is opt-in for any channel whose existing delivery callback has side effects beyond "send this payload".

Legacy entry points are non-durable by default:

delivery callback unless that channel explicitly supplies an audited durable policy/options object.

explicitly calls the send context.

dispatchInboundReplyWithBase, and direct-DM helpers never inject generic durable delivery before the caller-provided deliver or reply callback.

• channel.turn.run and dispatchAssembledChannelTurn use the channel's
• channel.turn.runPrepared stays channel-owned until the prepared dispatcher
• Public compatibility helpers such as recordInboundSessionAndDispatchReply,

For migration bridge types, durable: undefined means "not durable". The durable path is enabled only by an explicit policy/options value. durable: false can remain as a compatibility spelling, but implementation should not require every unmigrated channel to add it.

Current bridge code must keep the durability decision explicit:

handled_no_send are terminal; unsupported and not_applicable may fall back to channel-owned delivery; failed propagates the send failure.

silent delivery, reply target preservation, native quote preservation, and message-sending hooks. Missing parity should choose channel-owned delivery, not a generic send that changes user-visible behavior.

pendingFinalDelivery* session fields can carry the intent id during the transition; the end state is a MessageSendIntent store instead of frozen reply text plus ad hoc context fields.

• Durable final delivery returns a discriminated status. handled_visible and
• Generic durable final delivery is gated by adapter capabilities such as
• Queue-backed durable sends expose a delivery intent reference. Existing

Do not enable the generic durable path for a channel until all of these are true:

the old direct path.

ids.

as outside the durable guarantee.

replayable intent or batch plan.

• The generic send adapter executes the same rendering and transport behavior as
• Local post-send side effects are preserved through the send context.
• The adapter returns receipts or delivery results with all platform message
• Prepared dispatcher paths either call the new send context or stay documented
• Fallback delivery handles every projected payload, not only the first one.
• Durable fallback delivery records the whole projected payload array as one

Concrete migration hazards to preserve:

successful send. Durable final sends must still populate that cache, otherwise OpenClaw can re-ingest its own final replies as inbound user messages.

after group replies. Generic durable delivery must not bypass those effects; either move them into Tlon render/send/finalize adapters or keep Tlon on the channel-owned path.

behavior. They are not covered by an assembled-turn durable guarantee until their prepared dispatchers explicitly route finals through the send context.

array. A single-payload shortcut can drop additional fallback payloads after projection.

have reply-token handling, media proxying, sent-message caches, loading/status cleanup, or callback-only targets. They stay on channel-owned delivery until those semantics are represented by the send adapter and verified by tests.

target. Generic outbound must not guess from OriginatingTo or To and skip that callback.

bot-authored room echoes must be dropped before allowBots authorization. Channels must not implement this with visible-text prefix filters except as a short emergency stopgap; the durable contract is structured origin metadata.

• iMessage monitor delivery records sent messages in an echo cache after a
• Tlon appends an optional model signature and records participated threads
• Discord and other prepared dispatchers already own direct delivery and preview
• Telegram silent fallback delivery must deliver the full projected payload
• LINE, Zalo, Nostr, and other existing assembled/helper paths may
• Direct-DM helpers can have a reply callback that is the only correct transport
• OpenClaw gateway failure output must stay visible to humans, but tagged

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：The durable queue should store 小纸条消息 send intents, not reply payloads. Recovery loop: The queue should keep enough iden…。

The durable queue should store message send intents, not reply payloads.

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;
};

Recovery loop:

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

The queue should keep enough identity to replay through the same account, thread, target, formatting policy, and media rules after restart.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：消息通道 adapters classify transport failures into closed categories: Core policy: the 消息通道 declares that safe. already exi…。

Channel adapters classify transport failures into closed categories:

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

Core policy:

the channel declares that safe.

already exists.

commit becomes unknown_after_send unless the adapter can prove the platform operation did not happen.

• Retry transient and rate_limit.
• Do not retry invalid_payload unless a render fallback exists.
• Do not retry auth or permission until configuration changes.
• For not_found, let live finalization fall back from edit to fresh send when
• For conflict, use receipt/idempotency rules to decide whether the message
• Any error after the adapter may have completed platform I/O but before receipt

这一小段像旁白，在提醒我们镜头已经切到下一站。

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：origins, receipts, capabilities, durable intents, receive context, send context, live context, and failure classes. cur…。

origins, receipts, capabilities, durable intents, receive context, send context, live context, and failure classes.

current reply delivery, then move that field to ChannelMessage and rendered message types as the refactor replaces reply payloads.

• Add src/channels/message/* types for messages, targets, relations,
• Add origin?: MessageOrigin to the migration bridge payload type used by
• Keep this internal until adapters and tests prove the shape.
• Add pure unit tests for state transitions and serialization.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：小纸条消息 send intents. only one reply payload. cannot be written in the new 小纸条消息 lifecycle, after the adapter declares re…。

message send intents.

only one reply payload.

cannot be written in the new message lifecycle, after the adapter declares replay safety. Existing channel-turn and SDK compatibility paths remain direct-send by default during this phase.

of treating durable send as a terminal side effect.

chunked sends preserve OpenClaw operational provenance.

• Move the existing outbound queue from reply-payload durability to durable
• Let a durable send intent carry a projected payload array or batch plan, not
• Preserve the current queue recovery behavior through compatibility conversion.
• Make deliverOutboundPayloads call messages.send.
• Make final-send durability the default and fail closed when the durable intent
• Record receipts consistently.
• Return receipts and delivery results to the original dispatcher caller instead
• Persist message origin through durable send intents so recovery, replay, and

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：小纸条消息s.receive and 小纸条消息s.send. only when its adapter explicitly opts in with a replay-safe durability policy. native e…。

messages.receive and messages.send.

only when its adapter explicitly opts in with a replay-safe durability policy.

native edits and cannot replay safely yet, but do not rely on false markers to protect unmigrated channels.

the channel mapping proves the generic send path preserves the old channel delivery semantics.

• Reimplement channel.turn.run and dispatchAssembledChannelTurn on top of
• Keep current fact types stable.
• Keep legacy behavior by default. An assembled-turn channel becomes durable
• Keep durable: false as a compatibility escape hatch for paths that finalize
• Default assembled-turn durability only in the new message lifecycle, after

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：they already have durable-final work or simpler send paths. the send context. Documentation and changelog entries must…。

they already have durable-final work or simpler send paths.

the send context. Documentation and changelog entries must say "assembled channel turns" or name the migrated channel paths rather than claiming all automatic final replies.

public compatibility helpers behavior-preserving. They may expose an explicit send-context opt-in later, but must not automatically attempt generic durable delivery before the caller-owned delivery callback.

• Replace deliverDurableInboundReplyPayload with a send-context bridge.
• Keep the old helper as a wrapper.
• Port Telegram, WhatsApp, Slack, Signal, iMessage, and Discord first because
• Treat every prepared dispatcher as uncovered until it explicitly opts in to
• Keep recordInboundSessionAndDispatchReply, direct-DM helpers, and similar

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：parity tests.

parity tests.

• Build messages.live with two proof adapters:
• Telegram for send plus edit plus stale final send.
• Matrix for draft finalization plus redaction fallback.
• Then migrate Discord, Slack, Mattermost, Teams, QQ Bot, and Feishu.
• Delete duplicated preview finalization code only after each channel has

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：新本领插件 SDK docs. shouldDropOpenClawEcho predicate in the 消息通道-小纸条消息 SDK surface. migrated.

plugin SDK docs.

shouldDropOpenClawEcho predicate in the channel-message SDK surface.

migrated.

• Add openclaw/plugin-sdk/channel-message.
• Document it as the preferred channel plugin API.
• Update package exports, entrypoint inventory, generated API baselines, and
• Include MessageOrigin, origin encode/decode hooks, and the shared
• Keep compatibility wrappers for old subpaths.
• Mark reply-named SDK helpers as deprecated in docs after bundled plugins are

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Move all non-reply outbound producers onto 小纸条消息s.send: This is where the 聪明脑袋模型 stops being "机器人朋友 replies" and become…。

Move all non-reply outbound producers onto messages.send:

• cron and heartbeat notifications
• task completions
• hook results
• approval prompts and approval results
• message tool sends
• subagent completion announcements
• explicit CLI or Control UI sends
• automation/broadcast paths

This is where the model stops being "agent replies" and becomes "OpenClaw sends messages".

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：and third-party contracts have a stable replacement.

and third-party contracts have a stable replacement.

• Keep channel.turn as a wrapper for at least one compatibility window.
• Publish migration notes.
• Run plugin SDK compatibility tests against old imports.
• Remove or hide old internal helpers only after no bundled plugin needs them

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Unit tests: supports reconciliation. serialization, and recovery. Integration tests: explicitly opts in. and do not gen…。

Unit tests:

supports reconciliation.

serialization, and recovery.

• Durable send intent serialization and recovery.
• Idempotency key reuse and duplicate suppression.
• Receipt commit and replay skip.
• unknown_after_send recovery that reconciles before replay when an adapter
• Failure classification policy.
• Receive ack policy sequencing.
• Relation mapping for reply, followup, system, and broadcast sends.
• Gateway-failure origin factory and shouldDropOpenClawEcho predicate.
• Origin preservation through payload normalization, chunking, durable queue

Integration tests:

explicitly opts in.

and do not generic-send before those callbacks.

restart and cannot leave the later payloads unrecorded after an early crash.

dispatcher.

is disabled or unavailable.

requires normal delivery.

• channel.turn.run simple adapter still records and sends.
• Legacy assembled-event delivery does not become durable unless the channel
• channel.turn.runPrepared bridge still records and finalizes.
• Public compatibility helpers call caller-owned delivery callbacks by default
• Durable fallback delivery replays the whole projected payload array after
• Durable assembled-event delivery returns platform message ids to the buffered
• Custom delivery hooks still return platform message ids when durable delivery
• Final reply survives restart between assistant completion and platform send.
• Preview draft finalizes in place when allowed.
• Preview draft is cancelled or redacted when media/error/reply-target mismatch
• Block streaming and preview streaming do not both deliver the same text.
• Media streamed early is not duplicated in final delivery.

Channel tests:

completed watermark.

the persisted safe-completed offset model.

atomically, not one single-payload durable intent per loop iteration.

or changelog claim Discord final-reply durability.

generic durable send until their adapter parity tests exist.

migrated to a complete message target and replay-safe send adapter.

bot-room echoes drop before allowBots, and untagged bot messages with the same visible text still follow normal bot authorization.

accounts drop before allowBots handling.

allowBots modes before claiming generic protection there.

thread tracking.

Synology Chat, Tlon, Twitch, Zalo, and Zalo Personal simple durable final sends.

• Telegram topic reply with polling ack delayed until the receive context's safe
• Telegram polling recovery for accepted-but-not-delivered updates covered by
• Telegram stale preview sends fresh final and cleans up preview.
• Telegram silent fallback sends every projected fallback payload.
• Telegram silent fallback durability records the full projected fallback array
• Discord preview cancel on media/error/explicit reply.
• Discord prepared dispatcher finals route through the send context before docs
• iMessage durable final sends populate the monitor sent-message echo cache.
• LINE, Zalo, and Nostr legacy delivery paths are not bypassed by
• Direct-DM/Nostr callback delivery remains authoritative unless explicitly
• Slack tagged OpenClaw gateway failure messages stay visible outbound, tagged
• Slack native stream fallback to draft preview in top-level DMs.
• Matrix preview finalization and redaction fallback.
• Matrix tagged OpenClaw gateway-failure room echoes from configured bot
• Discord and Google Chat shared-room gateway-failure cascade audits cover
• Mattermost draft finalization and fresh-send fallback.
• Teams native progress finalization.
• Feishu duplicate final suppression.
• QQ Bot accumulator timeout fallback.
• Tlon durable final sends preserve model-signature rendering and participated
• WhatsApp, Signal, iMessage, Google Chat, LINE, IRC, Nostr, Nextcloud Talk,

Validation:

public SDK/export changes.

simple send-only channel before removing compatibility wrappers.

• Targeted Vitest files during development.
• pnpm check:changed in Testbox for the full changed surface.
• Broader pnpm check in Testbox before landing the complete refactor or after
• Live or qa-channel smoke for at least one edit-capable channel and one

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：fully durable polling source that can control platform-level redelivery, not only OpenClaw's persisted restart watermar…。

fully durable polling source that can control platform-level redelivery, not only OpenClaw's persisted restart watermark.

as the final send intent or in a sibling live-state store.

plugin-sdk/channel-message ships.

provide normalize/send/live hooks through defineChannelMessageAdapter.

state.

should be modeled as send-context hooks, adapter-owned finalize steps, or receipt subscribers.

registries, and which cannot offer reliable cross-bot echo suppression.

• Whether Telegram should eventually replace the grammY runner source with a
• Whether durable live preview state should be stored in the same queue record
• How long compatibility wrappers stay documented after
• Whether third-party plugins should implement receive adapters directly or only
• Which receipt fields are safe to expose in public SDK versus internal runtime
• Whether side effects such as self-echo caches and participated-thread markers
• Which channels have native origin metadata, which need persisted outbound

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：小纸条消息s.send. documented compatibility wrapper. finalization. the final response or duplicating already committed sends;…。

messages.send.

documented compatibility wrapper.

finalization.

the final response or duplicating already committed sends; sends whose platform outcome is unknown are reconciled before replay or documented as at-least-once for that adapter.

unless a caller explicitly selected a documented non-durable mode.

channel-owned delivery; generic durable send is explicit opt-in only.

primary id for threading/edit convenience.

delivery callbacks.

path explicitly uses the send context.

intent or batch plan.

bot-authored room echoes are dropped before bot authorization on channels that declare support for the origin contract.

policy, migration, and test coverage.

• Every bundled message channel sends final visible output through
• Every inbound message channel enters through messages.receive or a
• Every preview/edit/stream channel uses messages.live for draft state and
• channel.turn is only a wrapper.
• Reply-named SDK helpers are compatibility exports, not the recommended path.
• Durable recovery can replay pending final sends after restart without losing
• Durable final sends fail closed when the durable intent cannot be written,
• Legacy channel-turn and SDK compatibility helpers default to direct
• Receipts preserve all platform message ids for multi-part deliveries and a
• Durable wrappers preserve channel-local side effects before replacing direct
• Prepared dispatchers are not counted as durable until their final delivery
• Fallback delivery handles every projected payload.
• Durable fallback delivery records every projected payload in one replayable
• OpenClaw-originated gateway failure output is visible to humans but tagged
• The docs explain send, receive, live, state, receipts, relations, failure

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：---。

• Messages
• Streaming and chunking
• Progress drafts
• Retry policy
• Channel turn kernel

---