チャンネル送信 API

チャネル Plugin は、 openclaw/plugin-sdk/channel-outbound から送信メッセージの動作を公開します。受信／コンテキスト／ディスパッチの オーケストレーションには openclaw/plugin-sdk/channel-inbound を使用します。

コアは、キューイング、耐久性、永続的な イングレス監視とドレイン （createChannelIngressMonitor、createChannelIngressDrain、 openChannelIngressDrain）、汎用再試行ポリシー、ターン引き継ぎライフサイクル （turnAdoptionLifecycle / bindIngressLifecycleToReplyOptions）、フック、 受領情報、共有 message ツールを所有します。Plugin は、ネイティブの 送信／編集／削除呼び出し、ターゲットの正規化、プラットフォームのスレッド処理、選択された 引用、通知フラグ、アカウント状態、イングレス検査とペイロードの エンコード、レーンキー、再試行不可の述語、任意の置き換え 承認、プラットフォーム固有の副作用を所有します。

永続的なイングレスモニター

チャネルが受理したトランスポートイベントをディスパッチ前に永続化する必要がある場合は、createChannelIngressMonitor(...) を使用します。これは、チャネルのイングレスキューとドレインを、 共有の受け入れ、ポーリング、プルーニング、配信、シャットダウンのライフサイクルと 組み合わせます。トランスポートが実質的に異なる受け入れ契約またはポンプ契約を 所有する場合に限り、低レベルの createChannelIngressDrain(...) を使用します。

必須オプションは次のとおりです。

モニターは受け入れを直列化するため、追加時のバックオフによってレーンの順序が 逆転することはありません。デフォルトの上限付き追加遅延は 0、100、300 ms です。これを使い切ると、 永続化されなかったイベントをディスパッチする代わりに、トランスポートのコールバックを 拒否します。クレーム時には、バージョン付きペイロードをデコードし、inspect を再実行して、 配信前に ID またはレーンの不一致を拒否します。

deliver は、onAdopted、onDeferred、onAdoptionFinalizing、 onAbandoned、abortSignal を受け取ります。明示的に引き渡さずに戻ると、 ディスパッチされない終端イベントが引き継がれたものとしてマークされます。admission は常に exclusive です。 遅延された引き渡しではクレームが保持されますが、シャットダウンまたは中止の場合、引き継がれていない 作業は再試行可能なままです。引き継ぎによって、チャネルの配信 Promise が 戻る前に行がトゥームストーン化される場合があるため、モニターは配信をクレームの決着とは 独立して追跡します。

任意設定には、カスタムの追加遅延、高度なドレイン順序／並行処理／再試行ポリシー向けの drain オプションブロック、外部の abortSignal、 クロック、ポンプエラーの報告、停止エラーのファクトリ、受け入れポリシーが含まれます。 返されるモニターは、admit、start、pause、stop、waitForIdle、 isRunning、isStopped を公開します。stop は、まず受理済みの受け入れを決着させ、次に ドレインを中止して破棄し、ポンプとアクティブな配信を待機してから、 遅延作成の競合を解消するために再度破棄します。

トランスポート固有の秘匿化、未加工エンベロープの検証、再試行不可の 分類、永続化するペイロード形式は Plugin に保持します。Webhook トランスポートは、 admit が解決した後にのみ応答を返す必要があります。再生できないトランスポートは、 黙ってディスパッチするのではなく、永続的な追加の試行上限到達を表面化する必要があります。

アダプター

ほとんどの Plugin は、message アダプターを 1 つ定義します。

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

ネイティブトランスポートが実際に保持する機能だけを宣言してください。宣言した 各送信、受領情報、ライブプレビュー、受信確認の機能を、 このサブパスからエクスポートされる契約ヘルパーで網羅してください。

送信メッセージのエコー抑制

プラットフォームが Plugin 自身の送信メッセージを受信メッセージとして再配信する可能性がある場合は、チャネル、アカウント、会話、および安定したプラットフォームメッセージまたは送信元 ID を指定して recordOutboundMessageIdentity(...) を呼び出します。共有の受信ターンパスは、セッション記録またはエージェントへのディスパッチ前に、一致する ID を上限付きの 30 秒間ウィンドウで破棄します。配信の競合を解消するために、送信元 ID を送信前に予約したり、チャネルルートが削除されたときに更新したりできます。isRecentOutboundMessageIdentity(...) は、チャネル診断およびテスト向けに同じクエリを公開します。同じ安定した ID のために、並行するチャネルローカルの TTL キャッシュを維持しないでください。

プレーンテキストのサニタイズ

送信アダプターで、サポート対象の HTML 書式タグを軽量な テキストマークアップに変換する必要がある場合は、sanitizeForPlainText(...) を使用します。デフォルトでは、 既存のチャット形式の太字および取り消し線マーカーが維持されます。チャネルが結果を Markdown として 再解析する場合に限り、{ style: "markdown" } を渡します。

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

Markdown スタイルでは **bold** と ~~strikethrough~~ を使用します。斜体とインライン コードでは、どちらのスタイルでも _italic_ とバッククォートマーカーが維持されます。サニタイズ後に マーカーテキストを書き換えるのではなく、チャネル境界でスタイルを選択してください。

配信証拠

MessageReceipt は、チャネルアダプターが返した結果を記録します。具体的な プラットフォームメッセージ ID は、プラットフォームの送信パスが メッセージを受理したことを示しますが、受信者のデバイスに表示された、または既読になったことを 証明するものではありません。プラットフォームメッセージ ID のない受領情報は、 ローカルの受領メタデータにすぎません。既読通知またはデバイス配信状態を備えるチャネルは、 それらの情報をチャネル固有の別個のパスで追跡する必要があります。

失敗を再試行しても受信者に表示される送信が重複せず、 かつ確定処理が可能な呼び出しが開始されていないことをチャネルアダプターが証明できる場合は、 openclaw/plugin-sdk/error-runtime から new PlatformMessageNotDispatchedError("...", { cause: error }) をスローします。これによりコアは、古い送信試行の 証拠を消去し、キューに入ったインテントを安全に再試行できます。この表明を行えるのは、 最終ディスパッチ境界を所有するアダプターのみです。確定処理／送信呼び出しの開始後、または 曖昧な結果が返された後には、このマーカーを決して使用しないでください。誤ってマークすると、 メッセージが重複する可能性があります。

既存の送信アダプター

チャネルに互換性のある outbound アダプターがすでにある場合は、送信コードを 重複させるのではなく、そこからメッセージアダプターを派生させます。

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

永続的な送信

ランタイム送信ヘルパーも channel-outbound にあります。

• sendDurableMessageBatch(...)
• withDurableMessageSendContext(...)
• deliverInboundReplyWithMessageSendContext(...)
• resolveChannelDraftStreamingChunking(...) などのドラフトストリーミング／進捗ヘルパー

sendDurableMessageBatch(...) は、次の明示的な結果のいずれかを返します。

バッチ内に送信済み、抑制済み、失敗した ペイロードが混在する場合は、payloadOutcomes を使用します。空のレガシーな 直接配信結果からフックのキャンセルを推測しないでください。

遅延配信の受け入れ

解決済みのアカウントが、コア管理の送信または遅延配信を 安全に受け入れられない場合は、message.durableFinal.admitDeferredDelivery(...) を使用します。コアは、 キューへの永続化を省略するパスを含むライブ送信処理の前に、このフックを同期的に呼び出し、 復旧したインテントを再生する前にも再度呼び出します。コンテキストには、 cfg、channel、to、accountId、および live または recovery の phase が含まれます。

続行するには { status: "allowed" } を返します。配信を 永続化、直接送信、または再生してはならない場合は、 { status: "permanent_rejection", reason } を返します。ライブでの拒否は、キュー作成、 メッセージフック、プラットフォーム処理の前に失敗します。復旧時の拒否は、 キュー内のレコードを失敗としてマークし、調整と再生を省略します。フックを省略した場合は、 許可されたものとみなされます。

このフックは同期的な受け入れ判定であり、送信経路ではありません。すでに 読み込まれている設定またはランタイム状態のみを読み取り、ネットワーク、ファイルシステム、 その他の非同期 I/O を実行しないでください。契約テストでは、 openclaw/plugin-sdk/channel-outbound の ChannelMessageDurableFinalAdapter を通じて、両方のフェーズと 両方の結果バリアントを検証する必要があります。

互換性ディスパッチ

channel-inbound の dispatchChannelInboundReply(...) を通じて、 受信返信のディスパッチを構成します。プラットフォームへの配信は配信アダプター内に維持し、 メッセージアダプター、永続的な送信、受領確認、ライブプレビュー、 返信パイプラインのオプションには channel-outbound を使用します。