Tái cấu trúc vòng đời tin nhắn

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.

• Các primitive cốt lõi nên là nhận và gửi, không phải phản hồi.
• Một phản hồi chỉ là một quan hệ trên một thông điệp đi.
• Một lượt là tiện ích xử lý đầu vào, không phải chủ sở hữu của việc phân phối.
• Việc gửi phải dựa trên ngữ cảnh: begin, render, xem trước hoặc phát trực tuyến, gửi cuối cùng, commit, fail.
• Việc nhận cũng phải dựa trên ngữ cảnh: chuẩn hóa, khử trùng lặp, định tuyến, ghi nhận, điều phối, ack nền tảng, fail.
• SDK Plugin công khai nên thu gọn thành một bề mặt thông điệp kênh nhỏ duy nhất.

​

Vấn đề

• Adapter đầu vào đơn giản dùng runtime.channel.turn.run.
• Adapter phong phú dùng runtime.channel.turn.runPrepared.
• Helper cũ dùng dispatchInboundReplyWithBase, recordInboundSessionAndDispatchReply, helper payload phản hồi, chia đoạn phản hồi, tham chiếu phản hồi, và helper runtime đầu ra.
• Phát trực tuyến bản xem trước nằm trong các bộ điều phối riêng theo kênh.
• Độ bền của phân phối cuối cùng đang được bổ sung quanh các đường dẫn payload phản hồi hiện có.

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

​

Mục tiêu

• Một vòng đời core duy nhất cho mọi đường dẫn nhận và gửi thông điệp kênh.
• Gửi cuối bền vững theo mặc định trong vòng đời thông điệp mới sau khi một adapter khai báo hành vi an toàn để phát lại.
• Ngữ nghĩa xem trước, chỉnh sửa, phát trực tuyến, hoàn tất, thử lại, khôi phục và biên nhận được chia sẻ.
• Một bề mặt SDK Plugin nhỏ mà Plugin bên thứ ba có thể học và duy trì.
• Tương thích cho các caller channel.turn hiện có trong quá trình di chuyển.
• Điểm mở rộng rõ ràng cho năng lực kênh mới.
• Không có nhánh riêng theo nền tảng trong core.
• Không có thông điệp kênh delta token. Phát trực tuyến kênh vẫn là xem trước thông điệp, chỉnh sửa, nối thêm, hoặc phân phối khối đã hoàn tất.
• Metadata có cấu trúc có nguồn gốc từ OpenClaw cho đầu ra vận hành/hệ thống để các lỗi Gateway hiển thị không nhập lại các phòng dùng bot chung như prompt mới.

​

Không phải mục tiêu

• Không xóa runtime.channel.turn.* trong giai đoạn đầu.
• Không ép mọi kênh vào cùng một hành vi vận chuyển gốc.
• Không dạy core về chủ đề Telegram, luồng gốc Slack, redaction Matrix, thẻ Feishu, giọng nói QQ, hoặc hoạt động Teams.
• Không xuất bản mọi helper di chuyển nội bộ như API SDK ổn định.
• Không để retry phát lại các thao tác nền tảng không idempotent đã hoàn tất.

​

Mô hình tham chiếu

• Chat
• Thread
• Channel
• Message
• các phương thức adapter như postMessage, editMessage, deleteMessage, stream, startTyping, và truy xuất lịch sử
• một adapter trạng thái cho khử trùng lặp, khóa, hàng đợi và lưu bền vững

• Ý định gửi đi bền vững trước các lệnh gọi vận chuyển trực tiếp.
• Ngữ cảnh gửi rõ ràng với begin, commit và fail.
• Ngữ cảnh nhận biết chính sách ack của nền tảng.
• Biên nhận tồn tại qua khởi động lại và có thể thúc đẩy chỉnh sửa, xóa, khôi phục và triệt tiêu trùng lặp.
• SDK công khai nhỏ hơn. Plugin được đóng gói có thể dùng helper runtime nội bộ, nhưng Plugin bên thứ ba nên thấy một API thông điệp nhất quán duy nhất.
• Hành vi riêng theo agent: phiên, bản ghi hội thoại, phát trực tuyến khối, tiến trình công cụ, phê duyệt, chỉ thị media, phản hồi im lặng và lịch sử nhắc đến nhóm.

​

Mô hình core

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

​

Thuật ngữ thông điệp

​

Thông điệp

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

​

Đích

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

​

Quan hệ

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

​

Nguồn gốc

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

​

Biên nhận

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

​

Ngữ cảnh nhận

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 vận chuyển: báo cho webhook hoặc socket nền tảng rằng OpenClaw đã chấp nhận envelope sự kiện. Một số nền tảng yêu cầu điều này trước khi điều phối.
• Ack offset polling: tiến con trỏ để cùng một sự kiện không được lấy lại. Việc này không được vượt qua công việc không thể khôi phục.
• Ack bản ghi đầu vào: xác nhận OpenClaw đã lưu bền vững đủ metadata đầu vào để khử trùng lặp và định tuyến một lần phân phối lại.
• Biên nhận hiển thị cho người dùng: hành vi đọc/trạng thái/đang nhập tùy chọn; không bao giờ là ranh giới độ bền.

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

​

Ngữ cảnh gửi

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

​

Ngữ cảnh trực tiếp

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 gửi kèm edit preview, với final mới sau khi preview quá tuổi stale.
• Discord gửi kèm edit preview, cancel khi có media/error/explicit reply.
• Slack native stream hoặc draft preview tùy theo hình dạng thread.
• Mattermost draft post finalization.
• Matrix draft event finalization hoặc redaction khi không khớp.
• Teams native progress stream.
• QQ Bot stream hoặc fallback tích lũy.

​

Bề mặt adapter

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

​

Thu gọn SDK công khai

• reply-runtime
• reply-dispatch-runtime
• reply-reference
• reply-chunking
• reply-payload
• inbound-reply-dispatch
• channel-reply-pipeline
• hầu hết các cách dùng công khai của outbound-runtime
• các helper lifecycle draft stream ad hoc

​

Quan hệ với 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

​

Lan can tương thích

• channel.turn.run và dispatchAssembledChannelTurn dùng delivery callback của channel trừ khi channel đó cung cấp tường minh một đối tượng durable policy/options đã audit.
• channel.turn.runPrepared vẫn do channel sở hữu cho đến khi prepared dispatcher gọi send context một cách tường minh.
• Các helper tương thích công khai như recordInboundSessionAndDispatchReply, dispatchInboundReplyWithBase, và direct-DM helper không bao giờ chèn generic durable delivery trước callback deliver hoặc reply do caller cung cấp.

• Việc phân phối kết quả cuối bền vững trả về một trạng thái phân biệt. handled_visible và handled_no_send là trạng thái kết thúc; unsupported và not_applicable có thể quay về cơ chế phân phối do kênh sở hữu; failed truyền tiếp lỗi gửi.
• Việc phân phối kết quả cuối bền vững dạng chung được kiểm soát bằng các năng lực adapter như phân phối im lặng, bảo toàn đích trả lời, bảo toàn trích dẫn gốc, và hook gửi tin nhắn. Khi thiếu tương đương hành vi, nên chọn phân phối do kênh sở hữu, không phải một lần gửi chung làm thay đổi hành vi người dùng nhìn thấy.
• Các lần gửi bền vững dựa trên hàng đợi để lộ một tham chiếu ý định phân phối. Các trường phiên pendingFinalDelivery* hiện có có thể mang id ý định trong giai đoạn chuyển đổi; trạng thái cuối là một kho MessageSendIntent thay vì văn bản trả lời bị đóng băng cộng với các trường ngữ cảnh tùy biến.

• Adapter gửi dạng chung thực thi cùng hành vi kết xuất và vận chuyển như đường dẫn trực tiếp cũ.
• Các tác dụng phụ cục bộ sau khi gửi được bảo toàn thông qua ngữ cảnh gửi.
• Adapter trả về biên nhận hoặc kết quả phân phối với tất cả id tin nhắn của nền tảng.
• Các đường dẫn dispatcher đã chuẩn bị hoặc gọi ngữ cảnh gửi mới hoặc vẫn được ghi tài liệu là nằm ngoài bảo đảm bền vững.
• Phân phối dự phòng xử lý mọi payload đã chiếu, không chỉ payload đầu tiên.
• Phân phối dự phòng bền vững ghi lại toàn bộ mảng payload đã chiếu như một ý định có thể phát lại hoặc kế hoạch lô.

• Phân phối của bộ giám sát iMessage ghi lại tin nhắn đã gửi vào một bộ nhớ đệm echo sau một lần gửi thành công. Các lần gửi kết quả cuối bền vững vẫn phải điền bộ nhớ đệm đó, nếu không OpenClaw có thể nhập lại chính các trả lời cuối của nó như tin nhắn người dùng gửi vào.
• Tlon thêm chữ ký mô hình tùy chọn và ghi lại các luồng đã tham gia sau các trả lời nhóm. Phân phối bền vững dạng chung không được bỏ qua các hiệu ứng đó; hoặc chuyển chúng vào adapter kết xuất/gửi/hoàn tất của Tlon hoặc giữ Tlon trên đường dẫn do kênh sở hữu.
• Discord và các dispatcher đã chuẩn bị khác đã sở hữu hành vi phân phối trực tiếp và xem trước. Chúng không được bao phủ bởi bảo đảm bền vững của lượt đã lắp ráp cho đến khi các dispatcher đã chuẩn bị của chúng định tuyến rõ ràng kết quả cuối qua ngữ cảnh gửi.
• Phân phối dự phòng im lặng của Telegram phải phân phối toàn bộ mảng payload đã chiếu. Một lối tắt một payload có thể làm rơi các payload dự phòng bổ sung sau khi chiếu.
• LINE, Zalo, Nostr, và các đường dẫn đã lắp ráp/helper hiện có khác có thể có xử lý reply-token, proxy media, bộ nhớ đệm tin nhắn đã gửi, dọn dẹp loading/status, hoặc đích chỉ-callback. Chúng vẫn ở trên phân phối do kênh sở hữu cho đến khi các ngữ nghĩa đó được biểu diễn bởi adapter gửi và được kiểm chứng bằng kiểm thử.
• Các helper DM trực tiếp có thể có một callback trả lời là đích vận chuyển đúng duy nhất. Đầu ra dạng chung không được đoán từ OriginatingTo hoặc To rồi bỏ qua callback đó.
• Đầu ra lỗi của OpenClaw gateway phải vẫn hiển thị với con người, nhưng các echo trong phòng do bot tạo và đã gắn thẻ phải bị loại bỏ trước bước ủy quyền allowBots. Các kênh không được triển khai việc này bằng bộ lọc tiền tố văn bản hiển thị, ngoại trừ như một biện pháp chặn khẩn cấp ngắn hạn; hợp đồng bền vững là siêu dữ liệu nguồn gốc có cấu trúc.

​

Lưu trữ nội bộ

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

​

Lớp lỗi

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

• Thử lại transient và rate_limit.
• Không thử lại invalid_payload trừ khi có dự phòng kết xuất.
• Không thử lại auth hoặc permission cho đến khi cấu hình thay đổi.
• Với not_found, cho phép hoàn tất trực tiếp quay về từ chỉnh sửa sang gửi mới khi kênh khai báo rằng việc đó an toàn.
• Với conflict, dùng quy tắc biên nhận/idempotency để quyết định liệu tin nhắn đã tồn tại hay chưa.
• Bất kỳ lỗi nào sau khi adapter có thể đã hoàn tất I/O nền tảng nhưng trước khi commit biên nhận đều trở thành unknown_after_send trừ khi adapter có thể chứng minh thao tác nền tảng đã không xảy ra.

​

Ánh xạ kênh

​

Kế hoạch di chuyển

​

Giai đoạn 1: Miền tin nhắn nội bộ

• Thêm các kiểu src/channels/message/* cho tin nhắn, mục tiêu, quan hệ, nguồn, biên nhận, năng lực, ý định bền vững, ngữ cảnh nhận, ngữ cảnh gửi, ngữ cảnh trực tiếp, và lớp lỗi.
• Thêm origin?: MessageOrigin vào kiểu payload cầu nối di chuyển được dùng bởi phân phối trả lời hiện tại, rồi chuyển trường đó sang ChannelMessage và các kiểu tin nhắn đã hiển thị khi tái cấu trúc thay thế payload trả lời.
• Giữ phần này nội bộ cho đến khi các bộ chuyển tiếp và kiểm thử chứng minh được hình dạng.
• Thêm kiểm thử đơn vị thuần cho chuyển đổi trạng thái và tuần tự hóa.

​

Giai đoạn 2: Lõi gửi bền vững

• Chuyển hàng đợi gửi đi hiện có từ độ bền payload trả lời sang các ý định gửi tin nhắn bền vững.
• Cho phép một ý định gửi bền vững mang mảng payload đã chiếu hoặc kế hoạch lô, không chỉ một payload trả lời.
• Bảo toàn hành vi khôi phục hàng đợi hiện tại thông qua chuyển đổi tương thích.
• Làm cho deliverOutboundPayloads gọi messages.send.
• Đặt độ bền gửi cuối làm mặc định và đóng khi thất bại nếu không thể ghi ý định bền vững trong vòng đời tin nhắn mới, sau khi bộ chuyển tiếp khai báo an toàn phát lại. Các đường dẫn tương thích channel-turn và SDK hiện có vẫn mặc định gửi trực tiếp trong giai đoạn này.
• Ghi biên nhận một cách nhất quán.
• Trả biên nhận và kết quả phân phối về bên gọi dispatcher ban đầu thay vì coi gửi bền vững là một tác dụng phụ cuối cùng.
• Duy trì nguồn tin nhắn qua các ý định gửi bền vững để khôi phục, phát lại, và gửi theo khối vẫn bảo toàn nguồn gốc vận hành OpenClaw.

​

Giai đoạn 3: Cầu nối lượt kênh

• Triển khai lại channel.turn.run và dispatchAssembledChannelTurn trên nền messages.receive và messages.send.
• Giữ ổn định các kiểu fact hiện tại.
• Giữ hành vi cũ theo mặc định. Một kênh assembled-turn chỉ trở nên bền vững khi bộ chuyển tiếp của nó chọn tham gia rõ ràng với chính sách độ bền an toàn phát lại.
• Giữ durable: false làm lối thoát tương thích cho các đường dẫn hoàn tất chỉnh sửa gốc và chưa thể phát lại an toàn, nhưng không dựa vào các dấu false để bảo vệ các kênh chưa di chuyển.
• Chỉ mặc định độ bền assembled-turn trong vòng đời tin nhắn mới, sau khi ánh xạ kênh chứng minh đường dẫn gửi chung bảo toàn ngữ nghĩa phân phối kênh cũ.

​

Giai đoạn 4: Cầu nối dispatcher đã chuẩn bị

• Thay deliverDurableInboundReplyPayload bằng một cầu nối ngữ cảnh gửi.
• Giữ helper cũ dưới dạng wrapper.
• Chuyển Telegram, WhatsApp, Slack, Signal, iMessage và Discord trước vì chúng đã có công việc final bền vững hoặc đường gửi đơn giản hơn.
• Xem mọi dispatcher đã chuẩn bị là chưa được bao phủ cho đến khi nó chọn tham gia rõ ràng vào ngữ cảnh gửi. Tài liệu và mục changelog phải nói “lượt kênh đã được lắp ráp” hoặc nêu tên các đường dẫn kênh đã di chuyển thay vì tuyên bố tất cả phản hồi cuối tự động.
• Giữ recordInboundSessionAndDispatchReply, các helper direct-DM và những helper tương thích công khai tương tự bảo toàn hành vi. Chúng có thể phơi bày một tùy chọn tham gia ngữ cảnh gửi rõ ràng sau này, nhưng không được tự động thử giao phát bền vững chung trước callback giao phát do caller sở hữu.

​

Giai đoạn 5: Vòng đời live hợp nhất

• Xây dựng messages.live với hai adapter chứng minh:
  • Telegram cho gửi cộng chỉnh sửa cộng gửi final đã cũ.
  • Matrix cho hoàn tất bản nháp cộng fallback xóa.
• Sau đó di chuyển Discord, Slack, Mattermost, Teams, QQ Bot và Feishu.
• Chỉ xóa mã hoàn tất bản xem trước trùng lặp sau khi mỗi kênh có kiểm thử tương đương.

​

Giai đoạn 6: SDK công khai

• Thêm openclaw/plugin-sdk/channel-message.
• Tài liệu hóa nó là API Plugin kênh được ưu tiên.
• Cập nhật package exports, inventory entrypoint, baseline API đã sinh và tài liệu SDK Plugin.
• Bao gồm MessageOrigin, các hook mã hóa/giải mã origin và predicate chung shouldDropOpenClawEcho trong bề mặt SDK channel-message.
• Giữ các wrapper tương thích cho subpath cũ.
• Đánh dấu các helper SDK có tên reply là đã ngừng khuyến nghị trong tài liệu sau khi các Plugin đi kèm được di chuyển.

​

Giai đoạn 7: Tất cả bên gửi

• thông báo cron và heartbeat
• hoàn tất tác vụ
• kết quả hook
• lời nhắc phê duyệt và kết quả phê duyệt
• gửi bằng công cụ tin nhắn
• thông báo hoàn tất subagent
• gửi rõ ràng từ CLI hoặc Control UI
• đường tự động hóa/phát rộng

​

Giai đoạn 8: Ngừng khuyến nghị Turn

• Giữ channel.turn dưới dạng wrapper trong ít nhất một cửa sổ tương thích.
• Công bố ghi chú di chuyển.
• Chạy kiểm thử tương thích SDK Plugin với import cũ.
• Chỉ xóa hoặc ẩn các helper nội bộ cũ sau khi không Plugin đi kèm nào cần chúng và hợp đồng bên thứ ba đã có thay thế ổn định.

​

Kế hoạch kiểm thử

• Tuần tự hóa và khôi phục ý định gửi bền vững.
• Tái sử dụng khóa idempotency và triệt tiêu bản trùng lặp.
• Commit receipt và bỏ qua replay.
• Khôi phục unknown_after_send, có đối soát trước replay khi adapter hỗ trợ đối soát.
• Chính sách phân loại lỗi.
• Trình tự chính sách ack khi nhận.
• Ánh xạ quan hệ cho gửi reply, followup, system và broadcast.
• Factory origin lỗi Gateway và predicate shouldDropOpenClawEcho.
• Bảo toàn origin qua chuẩn hóa payload, chia chunk, tuần tự hóa hàng đợi bền vững và khôi phục.

• Adapter đơn giản channel.turn.run vẫn ghi lại và gửi.
• Giao phát assembled-turn kế thừa không trở thành bền vững trừ khi kênh chọn tham gia rõ ràng.
• Cầu nối channel.turn.runPrepared vẫn ghi lại và hoàn tất.
• Các helper tương thích công khai mặc định gọi callback giao phát do caller sở hữu và không generic-send trước các callback đó.
• Giao phát fallback bền vững replay toàn bộ mảng payload đã chiếu sau khi khởi động lại và không thể để các payload sau đó chưa được ghi lại sau một crash sớm.
• Giao phát assembled-turn bền vững trả về id tin nhắn nền tảng cho dispatcher được đệm.
• Hook giao phát tùy chỉnh vẫn trả về id tin nhắn nền tảng khi giao phát bền vững bị tắt hoặc không khả dụng.
• Reply cuối sống sót qua khởi động lại giữa lúc assistant hoàn tất và lúc gửi lên nền tảng.
• Bản nháp xem trước hoàn tất tại chỗ khi được cho phép.
• Bản nháp xem trước bị hủy hoặc bị xóa khi media/lỗi/không khớp reply-target yêu cầu giao phát bình thường.
• Streaming block và streaming xem trước không cùng giao phát một văn bản.
• Media được stream sớm không bị lặp trong giao phát cuối.

• Reply topic Telegram với ack polling bị trì hoãn cho đến watermark completed an toàn của ngữ cảnh nhận.
• Khôi phục polling Telegram cho các update đã chấp nhận nhưng chưa giao phát được bao phủ bởi mô hình offset safe-completed đã lưu.
• Bản xem trước Telegram đã cũ gửi final mới và dọn dẹp bản xem trước.
• Fallback im lặng Telegram gửi mọi payload fallback đã chiếu.
• Độ bền fallback im lặng Telegram ghi lại toàn bộ mảng fallback đã chiếu một cách nguyên tử, không phải một ý định bền vững single-payload cho mỗi vòng lặp.
• Discord hủy bản xem trước khi có media/lỗi/reply rõ ràng.
• Final của dispatcher đã chuẩn bị trong Discord định tuyến qua ngữ cảnh gửi trước khi tài liệu hoặc changelog tuyên bố độ bền final-reply của Discord.
• Gửi final bền vững của iMessage điền cache echo sent-message của monitor.
• Các đường giao phát kế thừa LINE, Zalo và Nostr không bị bỏ qua bởi gửi bền vững chung cho đến khi tồn tại kiểm thử tương đương adapter của chúng.
• Giao phát callback Direct-DM/Nostr vẫn có thẩm quyền trừ khi được di chuyển rõ ràng sang một message target hoàn chỉnh và adapter gửi an toàn khi replay.
• Tin nhắn lỗi Gateway OpenClaw được gắn thẻ của Slack vẫn hiển thị outbound, echo phòng bot được gắn thẻ bị loại trước allowBots, và tin nhắn bot không gắn thẻ có cùng văn bản hiển thị vẫn đi theo ủy quyền bot bình thường.
• Fallback stream native Slack sang bản xem trước nháp trong DM cấp cao nhất.
• Hoàn tất bản xem trước Matrix và fallback xóa.
• Echo phòng gateway-failure OpenClaw được gắn thẻ của Matrix từ tài khoản bot đã cấu hình bị loại trước xử lý allowBots.
• Kiểm toán cascade gateway-failure trong phòng chung của Discord và Google Chat bao phủ các chế độ allowBots trước khi tuyên bố bảo vệ chung ở đó.
• Hoàn tất bản nháp Mattermost và fallback gửi mới.
• Hoàn tất tiến trình native Teams.
• Triệt tiêu final trùng lặp Feishu.
• Fallback timeout accumulator QQ Bot.
• Gửi final bền vững Tlon bảo toàn render model-signature và theo dõi thread đã tham gia.
• Gửi final bền vững đơn giản cho WhatsApp, Signal, iMessage, Google Chat, LINE, IRC, Nostr, Nextcloud Talk, Synology Chat, Tlon, Twitch, Zalo và Zalo Personal.

• Các file Vitest được nhắm mục tiêu trong quá trình phát triển.
• pnpm check:changed trong Testbox cho toàn bộ bề mặt đã thay đổi.
• pnpm check rộng hơn trong Testbox trước khi landing toàn bộ refactor hoặc sau các thay đổi SDK/export công khai.
• Smoke live hoặc qa-channel cho ít nhất một kênh có khả năng chỉnh sửa và một kênh chỉ gửi đơn giản trước khi xóa wrapper tương thích.

​

Câu hỏi mở

• Liệu Telegram cuối cùng có nên thay runner source grammY bằng một nguồn polling hoàn toàn bền vững có thể kiểm soát giao phát lại ở cấp nền tảng, không chỉ watermark khởi động lại đã lưu của OpenClaw hay không.
• Liệu trạng thái live preview bền vững nên được lưu trong cùng bản ghi hàng đợi với ý định gửi cuối hay trong một kho live-state song song.
• Wrapper tương thích sẽ còn được tài liệu hóa bao lâu sau khi plugin-sdk/channel-message được phát hành.
• Liệu Plugin bên thứ ba nên triển khai receive adapter trực tiếp hay chỉ cung cấp hook normalize/send/live thông qua defineChannelMessageAdapter.
• Những trường receipt nào an toàn để phơi bày trong SDK công khai so với trạng thái runtime nội bộ.
• Liệu các hiệu ứng phụ như cache self-echo và marker participated-thread nên được mô hình hóa là hook send-context, bước finalize do adapter sở hữu, hay subscriber receipt.
• Kênh nào có metadata origin native, kênh nào cần registry outbound đã lưu, và kênh nào không thể cung cấp triệt tiêu echo cross-bot đáng tin cậy.

​

Tiêu chí chấp nhận

• Mọi kênh tin nhắn đi kèm gửi đầu ra hiển thị cuối cùng qua messages.send.
• Mọi kênh tin nhắn inbound đi vào qua messages.receive hoặc wrapper tương thích được tài liệu hóa.
• Mọi kênh preview/edit/stream dùng messages.live cho trạng thái bản nháp và hoàn tất.
• channel.turn chỉ là wrapper.
• Các helper SDK có tên reply là export tương thích, không phải đường được khuyến nghị.
• Khôi phục bền vững có thể replay các lượt gửi final đang chờ sau khi khởi động lại mà không làm mất phản hồi cuối hoặc nhân đôi các lượt gửi đã commit; các lượt gửi có kết quả nền tảng không xác định được đối soát trước khi replay hoặc được tài liệu hóa là at-least-once cho adapter đó.
• Gửi final bền vững fail closed khi không thể ghi ý định bền vững, trừ khi caller đã chọn rõ ràng một chế độ không bền vững được tài liệu hóa.
• Các helper tương thích channel-turn và SDK kế thừa mặc định giao phát trực tiếp do kênh sở hữu; gửi bền vững chung chỉ là tùy chọn tham gia rõ ràng.
• Receipt bảo toàn tất cả id tin nhắn nền tảng cho giao phát nhiều phần và một id chính để tiện threading/edit.
• Wrapper bền vững bảo toàn các hiệu ứng phụ cục bộ của kênh trước khi thay thế callback giao phát trực tiếp.
• Dispatcher đã chuẩn bị không được tính là bền vững cho đến khi đường giao phát cuối của chúng sử dụng rõ ràng ngữ cảnh gửi.
• Giao phát fallback xử lý mọi payload đã chiếu.
• Giao phát fallback bền vững ghi lại mọi payload đã chiếu trong một ý định hoặc kế hoạch batch có thể replay.
• Đầu ra lỗi Gateway bắt nguồn từ OpenClaw hiển thị với con người nhưng echo phòng do bot viết được gắn thẻ bị loại trước ủy quyền bot trên các kênh tuyên bố hỗ trợ hợp đồng origin.
• Tài liệu giải thích gửi, nhận, live, trạng thái, receipt, quan hệ, chính sách lỗi, di chuyển và phạm vi kiểm thử.

​

Liên quan

• Tin nhắn
• Streaming và chunking
• Bản nháp tiến trình
• Chính sách retry
• Kernel lượt kênh