메시지 수명 주기 리팩터링

Documentation Index

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

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

• 핵심 프리미티브는 reply가 아니라 receive와 send여야 합니다.
• 응답은 아웃바운드 메시지의 관계일 뿐입니다.
• 턴은 인바운드 처리를 위한 편의 기능이지 전달의 소유자가 아닙니다.
• 전송은 컨텍스트 기반이어야 합니다: begin, 렌더링, 미리보기 또는 스트림, 최종 전송, 커밋, 실패.
• 수신도 컨텍스트 기반이어야 합니다: 정규화, 중복 제거, 라우팅, 기록, 디스패치, 플랫폼 ack, 실패.
• 공개 Plugin SDK는 하나의 작은 채널 메시지 표면으로 축소되어야 합니다.

​

문제

• 단순 인바운드 어댑터는 runtime.channel.turn.run을 사용합니다.
• 풍부한 기능의 어댑터는 runtime.channel.turn.runPrepared를 사용합니다.
• 레거시 헬퍼는 dispatchInboundReplyWithBase, recordInboundSessionAndDispatchReply, 응답 페이로드 헬퍼, 응답 청킹, 응답 참조, 아웃바운드 런타임 헬퍼를 사용합니다.
• 미리보기 스트리밍은 채널별 디스패처에 있습니다.
• 최종 전달 내구성은 기존 응답 페이로드 경로 위에 추가되고 있습니다.

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

​

목표

• 모든 채널 메시지 수신 및 전송 경로에 대해 하나의 코어 수명 주기.
• 어댑터가 재생 안전 동작을 선언한 뒤 새 메시지 수명 주기에서 기본적으로 내구성 있는 최종 전송.
• 공유 미리보기, 편집, 스트림, 최종화, 재시도, 복구, 수신증 의미.
• 서드파티 Plugin이 배우고 유지할 수 있는 작은 Plugin SDK 표면.
• 마이그레이션 중 기존 channel.turn 호출자와의 호환성.
• 새 채널 기능을 위한 명확한 확장 지점.
• 코어에 플랫폼별 분기 없음.
• 토큰 델타 채널 메시지 없음. 채널 스트리밍은 메시지 미리보기, 편집, 추가, 또는 완료된 블록 전달로 유지됩니다.
• 표시되는 Gateway 실패가 공유 봇 사용 방에서 새 프롬프트로 다시 들어가지 않도록 운영/시스템 출력을 위한 구조화된 OpenClaw 출처 메타데이터.

​

비목표

• 첫 단계에서 runtime.channel.turn.*를 제거하지 않습니다.
• 모든 채널에 동일한 네이티브 전송 동작을 강제하지 않습니다.
• 코어에 Telegram 토픽, Slack 네이티브 스트림, Matrix 삭제 표시, Feishu 카드, QQ 음성, Teams 활동을 가르치지 않습니다.
• 모든 내부 마이그레이션 헬퍼를 안정적인 SDK API로 공개하지 않습니다.
• 재시도가 완료된 비멱등 플랫폼 작업을 재생하게 만들지 않습니다.

​

참조 모델

• Chat
• Thread
• Channel
• Message
• postMessage, editMessage, deleteMessage, stream, startTyping, 기록 가져오기 같은 어댑터 메서드
• 중복 제거, 잠금, 큐, 영속성을 위한 상태 어댑터

• 직접 전송 호출 전에 내구성 있는 아웃바운드 전송 의도.
• begin, commit, fail이 있는 명시적 전송 컨텍스트.
• 플랫폼 ack 정책을 아는 수신 컨텍스트.
• 재시작 후에도 살아남아 편집, 삭제, 복구, 중복 억제를 구동할 수 있는 수신증.
• 더 작은 공개 SDK. 번들 Plugin은 내부 런타임 헬퍼를 사용할 수 있지만, 서드파티 Plugin에는 하나의 일관된 메시지 API가 보여야 합니다.
• 에이전트별 동작: 세션, 트랜스크립트, 블록 스트리밍, 도구 진행, 승인, 미디어 지시문, 무음 응답, 그룹 멘션 기록.

​

코어 모델

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

​

메시지 용어

​

메시지

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

​

대상

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

​

관계

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

​

출처

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

​

수신증

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

​

수신 컨텍스트

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

• 전송 ack: 플랫폼 Webhook 또는 소켓에 OpenClaw가 이벤트 봉투를 수락했음을 알립니다. 일부 플랫폼은 디스패치 전에 이를 요구합니다.
• 폴링 오프셋 ack: 동일한 이벤트를 다시 가져오지 않도록 커서를 전진시킵니다. 복구할 수 없는 작업을 지나 전진해서는 안 됩니다.
• 인바운드 기록 ack: OpenClaw가 재전달을 중복 제거하고 라우팅하기에 충분한 인바운드 메타데이터를 영속화했음을 확인합니다.
• 사용자 표시 수신증: 선택적 읽음/상태/입력 중 동작이며, 절대 내구성 경계가 아닙니다.

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

​

전송 컨텍스트

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 context

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 전송 및 편집 preview, 오래된 preview age 이후 새 최종본.
• Discord 전송 및 편집 preview, 미디어/오류/명시적 reply 시 취소.
• 스레드 형태에 따른 Slack 네이티브 stream 또는 draft preview.
• Mattermost draft post 최종화.
• Matrix draft event 최종화 또는 불일치 시 redaction.
• Teams 네이티브 진행률 stream.
• QQ Bot stream 또는 누적 fallback.

​

Adapter surface

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

​

Public SDK reduction

• reply-runtime
• reply-dispatch-runtime
• reply-reference
• reply-chunking
• reply-payload
• inbound-reply-dispatch
• channel-reply-pipeline
• outbound-runtime의 대부분 공개 사용
• ad hoc draft stream lifecycle helper

​

Relationship to 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

​

Compatibility guardrails

• channel.turn.run과 dispatchAssembledChannelTurn은 해당 채널이 감사된 지속성 policy/options object를 명시적으로 제공하지 않는 한 채널의 delivery callback을 사용합니다.
• channel.turn.runPrepared는 prepared dispatcher가 명시적으로 전송 context를 호출할 때까지 채널 소유로 남습니다.
• recordInboundSessionAndDispatchReply, dispatchInboundReplyWithBase, direct-DM helper 같은 공개 호환성 helper는 caller가 제공한 deliver 또는 reply callback보다 먼저 일반 지속성 delivery를 주입하지 않습니다.

• 지속성 최종 전달은 판별 가능한 상태를 반환합니다. handled_visible 및 handled_no_send는 종료 상태이며, unsupported 및 not_applicable은 채널 소유 전달로 폴백할 수 있고, failed는 전송 실패를 전파합니다.
• 범용 지속성 최종 전달은 무음 전달, 답장 대상 보존, 네이티브 인용 보존, 메시지 전송 훅과 같은 어댑터 기능에 의해 제한됩니다. 동등성이 누락된 경우, 사용자에게 보이는 동작을 바꾸는 범용 전송이 아니라 채널 소유 전달을 선택해야 합니다.
• 큐 기반 지속성 전송은 전달 의도 참조를 노출합니다. 기존 pendingFinalDelivery* 세션 필드는 전환 중에 의도 ID를 전달할 수 있으며, 최종 상태는 고정된 답장 텍스트와 임시 컨텍스트 필드가 아니라 MessageSendIntent 저장소입니다.

• 범용 전송 어댑터가 기존 직접 경로와 동일한 렌더링 및 전송 동작을 실행합니다.
• 로컬 전송 후 부수 효과가 전송 컨텍스트를 통해 보존됩니다.
• 어댑터가 모든 플랫폼 메시지 ID가 포함된 수신 확인 또는 전달 결과를 반환합니다.
• 준비된 디스패처 경로가 새 전송 컨텍스트를 호출하거나, 지속성 보장 범위 밖에 있음을 문서화한 상태로 유지됩니다.
• 폴백 전달이 첫 번째 페이로드뿐만 아니라 모든 예상 페이로드를 처리합니다.
• 지속성 폴백 전달이 전체 예상 페이로드 배열을 하나의 재생 가능한 의도 또는 배치 계획으로 기록합니다.

• iMessage 모니터 전달은 성공적인 전송 후 에코 캐시에 전송된 메시지를 기록합니다. 지속성 최종 전송도 해당 캐시를 채워야 합니다. 그렇지 않으면 OpenClaw가 자체 최종 답장을 인바운드 사용자 메시지로 다시 수집할 수 있습니다.
• Tlon은 선택적 모델 서명을 추가하고 그룹 답장 후 참여한 스레드를 기록합니다. 범용 지속성 전달은 이러한 효과를 우회해서는 안 됩니다. 이를 Tlon 렌더링/전송/최종화 어댑터로 옮기거나 Tlon을 채널 소유 경로에 유지하세요.
• Discord 및 기타 준비된 디스패처는 이미 직접 전달과 미리보기 동작을 소유합니다. 준비된 디스패처가 최종 응답을 전송 컨텍스트를 통해 명시적으로 라우팅할 때까지, 이들은 조립된 턴 지속성 보장의 적용을 받지 않습니다.
• Telegram 무음 폴백 전달은 전체 예상 페이로드 배열을 전달해야 합니다. 단일 페이로드 단축 경로는 예상 처리 후 추가 폴백 페이로드를 누락할 수 있습니다.
• LINE, Zalo, Nostr 및 기타 기존 조립/헬퍼 경로에는 답장 토큰 처리, 미디어 프록시, 전송 메시지 캐시, 로딩/상태 정리 또는 콜백 전용 대상이 있을 수 있습니다. 이러한 의미가 전송 어댑터로 표현되고 테스트로 검증될 때까지 이들은 채널 소유 전달에 유지됩니다.
• 직접 DM 헬퍼에는 유일하게 올바른 전송 대상인 답장 콜백이 있을 수 있습니다. 범용 아웃바운드는 OriginatingTo 또는 To에서 추측하여 해당 콜백을 건너뛰어서는 안 됩니다.
• OpenClaw Gateway 실패 출력은 사람이 볼 수 있어야 하지만, 태그가 지정된 봇 작성 방 에코는 allowBots 권한 부여 전에 삭제되어야 합니다. 채널은 짧은 긴급 임시 조치를 제외하고 이를 보이는 텍스트 접두사 필터로 구현해서는 안 됩니다. 지속성 계약은 구조화된 원본 메타데이터입니다.

​

내부 저장소

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

​

실패 클래스

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

• transient 및 rate_limit은 재시도합니다.
• 렌더링 폴백이 없는 한 invalid_payload는 재시도하지 않습니다.
• 구성이 변경될 때까지 auth 또는 permission은 재시도하지 않습니다.
• not_found의 경우, 채널이 안전하다고 선언하면 실시간 최종화가 편집에서 새 전송으로 폴백하도록 합니다.
• conflict의 경우, 수신 확인/멱등성 규칙을 사용하여 메시지가 이미 존재하는지 판단합니다.
• 어댑터가 플랫폼 I/O를 완료했을 수 있으나 수신 확인 커밋 전에 발생한 오류는 어댑터가 플랫폼 작업이 발생하지 않았음을 증명할 수 없는 한 unknown_after_send가 됩니다.

​

채널 매핑

​

마이그레이션 계획

​

1단계: 내부 메시지 도메인

• 메시지, 대상, 관계, 원본, 수신 확인, 기능, 지속성 있는 인텐트, 수신 컨텍스트, 전송 컨텍스트, 라이브 컨텍스트, 실패 클래스에 대한 src/channels/message/* 타입을 추가합니다.
• 현재 답장 전달에서 사용하는 마이그레이션 브리지 페이로드 타입에 origin?: MessageOrigin을 추가한 다음, 리팩터링이 답장 페이로드를 대체하면서 해당 필드를 ChannelMessage와 렌더링된 메시지 타입으로 옮깁니다.
• 어댑터와 테스트가 형태를 입증할 때까지 이를 내부로 유지합니다.
• 상태 전이와 직렬화에 대한 순수 단위 테스트를 추가합니다.

​

2단계: 지속성 있는 전송 코어

• 기존 아웃바운드 큐를 답장-페이로드 지속성에서 지속성 있는 메시지 전송 인텐트로 이동합니다.
• 지속성 있는 전송 인텐트가 하나의 답장 페이로드뿐 아니라 투영된 페이로드 배열이나 배치 계획을 담을 수 있게 합니다.
• 호환성 변환을 통해 현재 큐 복구 동작을 보존합니다.
• deliverOutboundPayloads가 messages.send를 호출하게 합니다.
• 어댑터가 replay 안전성을 선언한 뒤, 새 메시지 수명 주기에서 지속성 있는 인텐트를 쓸 수 없을 때 최종 전송 지속성을 기본값으로 삼고 fail closed합니다. 이 단계 동안 기존 채널 턴과 SDK 호환성 경로는 기본적으로 직접 전송으로 유지됩니다.
• 수신 확인을 일관되게 기록합니다.
• 지속성 있는 전송을 종단 부수 효과로 취급하는 대신, 수신 확인과 전달 결과를 원래 디스패처 호출자에게 반환합니다.
• 복구, replay, 청크 전송이 OpenClaw 운영 출처를 보존하도록 지속성 있는 전송 인텐트를 통해 메시지 원본을 유지합니다.

​

3단계: 채널 턴 브리지

• channel.turn.run과 dispatchAssembledChannelTurn을 messages.receive와 messages.send 위에서 다시 구현합니다.
• 현재 fact 타입을 안정적으로 유지합니다.
• 기본적으로 레거시 동작을 유지합니다. 조립된 턴 채널은 어댑터가 replay-safe 지속성 정책으로 명시적으로 옵트인할 때만 지속성을 갖습니다.
• 네이티브 편집을 최종화하고 아직 안전하게 replay할 수 없는 경로를 위한 호환성 탈출구로 durable: false를 유지하되, 마이그레이션되지 않은 채널을 보호하기 위해 false 마커에 의존하지는 않습니다.
• 채널 매핑이 범용 전송 경로가 기존 채널 전달 의미론을 보존한다는 점을 입증한 뒤, 새 메시지 수명 주기에서만 조립된 턴 지속성을 기본값으로 설정합니다.

​

4단계: 준비된 디스패처 브리지

• deliverDurableInboundReplyPayload를 전송 컨텍스트 브리지로 대체합니다.
• 기존 helper는 wrapper로 유지합니다.
• Telegram, WhatsApp, Slack, Signal, iMessage, Discord를 먼저 포팅합니다. 이들은 이미 내구성 있는 최종 처리 작업이 있거나 전송 경로가 더 단순하기 때문입니다.
• 모든 준비된 dispatcher는 전송 컨텍스트를 명시적으로 옵트인하기 전까지 커버되지 않은 것으로 취급합니다. 문서와 changelog 항목은 모든 자동 최종 답장을 주장하기보다 “조립된 채널 턴”이라고 말하거나 마이그레이션된 채널 경로의 이름을 명시해야 합니다.
• recordInboundSessionAndDispatchReply, direct-DM helper 및 유사한 공개 호환성 helper는 동작을 보존해야 합니다. 나중에 명시적인 전송 컨텍스트 옵트인을 노출할 수 있지만, 호출자가 소유한 전달 callback보다 먼저 generic 내구성 전달을 자동으로 시도해서는 안 됩니다.

​

5단계: 통합 Live 수명 주기

• 두 개의 증명 adapter로 messages.live를 빌드합니다.
  • Telegram: 전송, 수정, 오래된 최종 전송.
  • Matrix: draft 최종화와 redaction fallback.
• 그런 다음 Discord, Slack, Mattermost, Teams, QQ Bot, Feishu를 마이그레이션합니다.
• 각 채널에 동등성 테스트가 생긴 뒤에만 중복된 preview 최종화 코드를 삭제합니다.

​

6단계: 공개 SDK

• openclaw/plugin-sdk/channel-message를 추가합니다.
• 이를 권장 채널 Plugin API로 문서화합니다.
• package exports, entrypoint inventory, 생성된 API baseline, Plugin SDK 문서를 업데이트합니다.
• MessageOrigin, origin encode/decode hook, 공유 shouldDropOpenClawEcho predicate를 channel-message SDK 표면에 포함합니다.
• 이전 subpath에 대한 호환성 wrapper를 유지합니다.
• bundled Plugin이 마이그레이션된 뒤 docs에서 reply 이름이 붙은 SDK helper를 deprecated로 표시합니다.

​

7단계: 모든 Sender

• cron 및 heartbeat 알림
• task 완료
• hook 결과
• approval prompt 및 approval 결과
• message tool 전송
• subagent 완료 공지
• 명시적 CLI 또는 Control UI 전송
• automation/broadcast 경로

​

8단계: Turn 사용 중단

• channel.turn을 최소 한 번의 호환성 기간 동안 wrapper로 유지합니다.
• 마이그레이션 노트를 게시합니다.
• 이전 import에 대해 Plugin SDK 호환성 테스트를 실행합니다.
• bundled Plugin이 더 이상 필요로 하지 않고 third-party contract에 안정적인 대체물이 생긴 뒤에만 이전 internal helper를 제거하거나 숨깁니다.

​

테스트 계획

• 내구성 있는 전송 intent 직렬화 및 복구.
• idempotency key 재사용 및 중복 억제.
• receipt commit 및 replay skip.
• adapter가 reconciliation을 지원할 때 replay 전에 reconcile하는 unknown_after_send 복구.
• 실패 분류 정책.
• receive ack policy sequencing.
• reply, followup, system, broadcast 전송에 대한 relation mapping.
• Gateway 실패 origin factory 및 shouldDropOpenClawEcho predicate.
• payload normalization, chunking, durable queue serialization, recovery를 통한 origin 보존.

• channel.turn.run 단순 adapter가 여전히 기록하고 전송합니다.
• legacy 조립된-turn 전달은 채널이 명시적으로 옵트인하지 않는 한 durable이 되지 않습니다.
• channel.turn.runPrepared bridge가 여전히 기록하고 최종화합니다.
• 공개 호환성 helper는 기본적으로 호출자가 소유한 delivery callback을 호출하며 해당 callback보다 먼저 generic-send하지 않습니다.
• Durable fallback delivery는 restart 후 전체 projected payload array를 replay하며, 이른 crash 후에도 이후 payload가 기록되지 않은 상태로 남을 수 없습니다.
• Durable assembled-turn delivery는 platform message id를 buffered dispatcher에 반환합니다.
• custom delivery hook은 durable delivery가 비활성화되었거나 사용할 수 없을 때도 platform message id를 반환합니다.
• 최종 reply는 assistant completion과 platform send 사이의 restart에서도 살아남습니다.
• 허용되는 경우 preview draft가 제자리에서 최종화됩니다.
• media/error/reply-target mismatch로 normal delivery가 필요할 때 preview draft는 취소되거나 redacted됩니다.
• block streaming과 preview streaming이 같은 텍스트를 둘 다 전달하지 않습니다.
• 일찍 stream된 media가 final delivery에서 중복되지 않습니다.

• Telegram topic reply에서 polling ack는 receive context의 safe completed watermark까지 지연됩니다.
• accepted-but-not-delivered update에 대한 Telegram polling recovery는 persisted safe-completed offset model로 커버됩니다.
• Telegram stale preview는 fresh final을 전송하고 preview를 정리합니다.
• Telegram silent fallback은 모든 projected fallback payload를 전송합니다.
• Telegram silent fallback durability는 루프 iteration마다 single-payload durable intent 하나가 아니라 전체 projected fallback array를 atomically 기록합니다.
• Discord preview cancel on media/error/explicit reply.
• Discord prepared dispatcher final은 docs나 changelog가 Discord final-reply durability를 주장하기 전에 send context를 통해 route됩니다.
• iMessage durable final send는 monitor sent-message echo cache를 채웁니다.
• LINE, Zalo, Nostr legacy delivery path는 adapter parity test가 생길 때까지 generic durable send로 우회되지 않습니다.
• Direct-DM/Nostr callback delivery는 complete message target과 replay-safe send adapter로 명시적으로 마이그레이션되지 않는 한 authoritative로 유지됩니다.
• Slack tagged OpenClaw gateway failure message는 outbound에서 visible 상태로 유지되고, tagged bot-room echo는 allowBots 전에 drop되며, 같은 visible text를 가진 untagged bot message는 여전히 normal bot authorization을 따릅니다.
• Slack native stream fallback to draft preview in top-level DMs.
• Matrix preview finalization 및 redaction fallback.
• Matrix tagged OpenClaw gateway-failure room echo는 configured bot account에서 온 경우 allowBots handling 전에 drop됩니다.
• Discord 및 Google Chat shared-room gateway-failure cascade audit는 generic protection을 주장하기 전에 allowBots mode를 커버합니다.
• Mattermost draft finalization 및 fresh-send fallback.
• Teams native progress finalization.
• Feishu duplicate final suppression.
• QQ Bot accumulator timeout fallback.
• Tlon durable final send는 model-signature rendering 및 participated thread tracking을 보존합니다.
• WhatsApp, Signal, iMessage, Google Chat, LINE, IRC, Nostr, Nextcloud Talk, Synology Chat, Tlon, Twitch, Zalo, Zalo Personal simple durable final send.

• 개발 중 targeted Vitest file.
• 전체 changed surface에 대해 Testbox에서 pnpm check:changed.
• complete refactor를 land하기 전 또는 public SDK/export 변경 후 Testbox에서 더 넓은 pnpm check.
• compatibility wrapper를 제거하기 전에 edit-capable 채널 하나와 simple send-only 채널 하나 이상에 대한 live 또는 qa-channel smoke.

​

열린 질문

• Telegram이 결국 grammY runner source를 platform-level redelivery를 제어할 수 있는 완전히 durable한 polling source로 대체해야 하는지 여부. OpenClaw의 persisted restart watermark만 제어하는 것이 아닙니다.
• durable live preview state를 final send intent와 같은 queue record에 저장해야 하는지, 아니면 sibling live-state store에 저장해야 하는지 여부.
• plugin-sdk/channel-message가 출시된 뒤 compatibility wrapper를 얼마나 오래 문서화할지.
• third-party Plugin이 receive adapter를 직접 구현해야 하는지, 아니면 defineChannelMessageAdapter를 통해 normalize/send/live hook만 제공해야 하는지.
• 어떤 receipt field를 public SDK에 노출해도 안전하고, 어떤 것이 internal runtime state인지.
• self-echo cache 및 participated-thread marker 같은 side effect를 send-context hook, adapter-owned finalize step 또는 receipt subscriber로 모델링해야 하는지 여부.
• 어떤 채널에 native origin metadata가 있고, 어떤 채널에 persisted outbound registry가 필요하며, 어떤 채널이 reliable cross-bot echo suppression을 제공할 수 없는지.

​

승인 기준

• 모든 bundled message channel은 최종 visible output을 messages.send를 통해 전송합니다.
• 모든 inbound message channel은 messages.receive 또는 문서화된 compatibility wrapper를 통해 진입합니다.
• 모든 preview/edit/stream 채널은 draft state 및 finalization에 messages.live를 사용합니다.
• channel.turn은 wrapper일 뿐입니다.
• reply 이름이 붙은 SDK helper는 compatibility export이지 권장 경로가 아닙니다.
• Durable recovery는 restart 후 pending final send를 replay할 수 있으며, final response를 잃거나 이미 committed send를 중복하지 않습니다. platform outcome이 unknown인 send는 replay 전에 reconciled되거나 해당 adapter에 대해 at-least-once로 문서화됩니다.
• Durable final send는 durable intent를 쓸 수 없을 때 fail closed됩니다. 단, 호출자가 문서화된 non-durable mode를 명시적으로 선택한 경우는 예외입니다.
• Legacy channel-turn 및 SDK compatibility helper는 기본적으로 직접 channel-owned delivery를 사용합니다. generic durable send는 명시적 opt-in일 때만 가능합니다.
• receipt는 multi-part delivery의 모든 platform message id와 threading/edit convenience를 위한 primary id를 보존합니다.
• Durable wrapper는 direct delivery callback을 대체하기 전에 channel-local side effect를 보존합니다.
• prepared dispatcher는 final delivery path가 send context를 명시적으로 사용할 때까지 durable로 간주되지 않습니다.
• fallback delivery는 모든 projected payload를 처리합니다.
• Durable fallback delivery는 모든 projected payload를 replay 가능한 하나의 intent 또는 batch plan에 기록합니다.
• OpenClaw-originated gateway failure output은 사람에게 visible하지만, origin contract 지원을 선언한 채널에서는 tagged bot-authored room echo가 bot authorization 전에 drop됩니다.
• docs는 send, receive, live, state, receipts, relations, failure policy, migration, test coverage를 설명합니다.

​

관련 항목

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