チャンネル送信 API

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

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

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

オプション	契約
`queue`	`ChannelIngressQueue`、またはアカウントスコープのキューを開く遅延ファクトリ。
`inspect(raw, context)`	安定した `eventId` とシリアル化された `laneKey` を返します。無視されるイベントの場合は `null` を返します。クレーム時の情報は、永続化された ID およびレーンと一致する必要があります。
`payload`	ペイロードのバージョンと、本文のシリアル化／逆シリアル化を提供します。標準の `{ version, rawEvent }` 文字列エンベロープには `storage: "raw-event"` を使用し、既存のチャネル固有形式にはカスタムのエンコード／デコードコールバックを指定します。`createClaimError` は、無効なバージョンまたは変更された ID を分類します。
`deliver(raw, lifecycle, claim)`	デコードされたイベントを 1 件ディスパッチし、完全な引き継ぎライフサイクルを受け取ります。`completed`、`deferred`、`failed-retryable`、または何も返さない場合があります。
`pollIntervalMs`	モニターの実行中に、復旧／ドレインのポーリングをスケジュールします。
`retention`	プルーニング間隔と、完了／失敗の TTL およびエントリ上限を提供します。

モニターは受け入れを直列化するため、追加時のバックオフによってレーンの順序が逆転することはありません。デフォルトの上限付き追加遅延は 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 つ定義します。

import {
  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" } を渡します。

import { sanitizeForPlainText } from "openclaw/plugin-sdk/channel-outbound";

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 アダプターがすでにある場合は、送信コードを重複させるのではなく、そこからメッセージアダプターを派生させます。

import { createChannelMessageAdapterFromOutbound } from "openclaw/plugin-sdk/channel-outbound";

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

永続的な送信

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

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

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

結果	意味
`sent`	表示可能なプラットフォームメッセージが少なくとも 1 件、プラットフォームの送信パスによって受理された
`suppressed`	プラットフォームメッセージが欠落したものとして扱われるべきではない
`partial_failed`	後続のペイロードまたは副作用が失敗する前に、少なくとも 1 件のプラットフォームメッセージが受理された
`failed`	プラットフォームの受領情報が生成されなかった

バッチ内に送信済み、抑制済み、失敗したペイロードが混在する場合は、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 を使用します。

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Contributing

チャンネル送信 API

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

アダプター

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

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

配信証拠

既存の送信アダプター

永続的な送信

遅延配信の受け入れ

互換性ディスパッチ

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

​アダプター

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

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

​配信証拠

​既存の送信アダプター

​永続的な送信

​遅延配信の受け入れ

​互換性ディスパッチ

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

アダプター

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

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

配信証拠

既存の送信アダプター

永続的な送信

遅延配信の受け入れ

互換性ディスパッチ