Channel Pluginsの構築
このガイドでは、OpenClawをメッセージングプラットフォームに接続するchannel pluginの構築手順を説明します。最終的には、DMセキュリティ、ペアリング、応答スレッド化、送信メッセージングを備えた動作するchannelを作成できます。OpenClaw pluginをまだ一度も構築したことがない場合は、まず
はじめにを読んで、基本的なパッケージ
構造とマニフェスト設定を確認してください。
channel pluginsの仕組み
channel pluginsには独自のsend/edit/react toolsは不要です。OpenClawは 共有のmessage toolをcoreに1つだけ保持します。pluginが担当するのは次です:
- 設定 — アカウント解決とセットアップウィザード
- セキュリティ — DMポリシーとallowlist
- ペアリング — DM承認フロー
- セッショングラマー — プロバイダー固有の会話idを、ベースチャット、thread id、親フォールバックへどう対応付けるか
- 送信 — プラットフォームへのテキスト、メディア、polls送信
- スレッド化 — 応答をどうスレッド化するか
:thread:管理、およびディスパッチを担当します。
プラットフォームが会話id内に追加スコープを保存する場合、その解析は
plugin内でmessaging.resolveSessionConversation(...)に保持してください。これは
rawIdをベース会話id、任意のthread
id、明示的なbaseConversationId、および任意のparentConversationCandidatesへ対応付けるための
正規フックです。
parentConversationCandidatesを返す場合は、最も狭い親から最も広い/ベース会話へ向けて順序を保ってください。
bundled pluginsで、channel registryが起動する前に同じ解析が必要な場合は、
一致するresolveSessionConversation(...)エクスポートを持つトップレベルの
session-key-api.tsファイルを公開することもできます。coreは、ランタイムplugin registryがまだ利用できない場合にのみ、この起動時安全なサーフェスを使用します。
messaging.resolveParentConversationCandidates(...)は、pluginが汎用/raw idの上に
親フォールバックだけを必要とする場合の、古い互換フォールバックとして引き続き利用可能です。両方のフックが存在する場合、coreはまず
resolveSessionConversation(...).parentConversationCandidatesを使用し、正規フックが
それらを省略した場合にのみresolveParentConversationCandidates(...)へフォールバックします。
承認とchannel機能
ほとんどのchannel pluginsでは、承認専用コードは不要です。- coreは、同一チャット内の
/approve、共有承認ボタンのペイロード、および汎用フォールバック配信を担当します。 - channelが承認固有の動作を必要とする場合は、channel plugin上の1つの
approvalCapabilityオブジェクトを優先してください。 approvalCapability.authorizeActorActionとapprovalCapability.getActionAvailabilityStateが、正規の承認認可シームです。- 重複するローカル承認プロンプトの非表示や、配信前のtyping indicator送信など、channel固有のペイロードライフサイクル動作には
outbound.shouldSuppressLocalPayloadPromptまたはoutbound.beforeDeliverPayloadを使用してください。 - ネイティブ承認ルーティングまたはフォールバック抑制には
approvalCapability.deliveryのみを使用してください。 - 共有レンダラーではなく、本当にchannelにカスタム承認ペイロードが必要な場合にのみ
approvalCapability.renderを使用してください。 - 既存設定から安定したowner類似のDM identityを推測できるchannelでは、承認固有のcoreロジックを追加せずに、同一チャット内の
/approveを制限するためopenclaw/plugin-sdk/approval-runtimeのcreateResolvedApproverActionAuthAdapterを使用してください。 - channelにネイティブ承認配信が必要な場合、channelコードはターゲット正規化と転送フックに集中させてください。
openclaw/plugin-sdk/approval-runtimeのcreateChannelExecApprovalProfile、createChannelNativeOriginTargetResolver、createChannelApproverDmTargetResolver、createApproverRestrictedNativeApprovalCapability、createChannelNativeApprovalRuntimeを使用し、coreがリクエストフィルタリング、ルーティング、重複排除、有効期限、およびGatewayサブスクリプションを担当するようにしてください。 - ネイティブ承認channelでは、
accountIdとapprovalKindの両方をそれらのヘルパー経由でルーティングする必要があります。accountIdはマルチアカウント承認ポリシーを正しいbotアカウントに限定し、approvalKindはexecとplugin承認の動作をcore内のハードコード分岐なしでchannelに利用可能にします。 - 配信された承認idの種別はエンドツーエンドで保持してください。ネイティブクライアントは、channelローカル状態からexec対plugin承認ルーティングを推測または書き換えてはいけません。
- 異なる承認種別では、意図的に異なるネイティブサーフェスを公開できます。
現在のbundled examples:
- Slackは、exec idとplugin idの両方でネイティブ承認ルーティングを利用可能にしています。
- Matrixは、exec承認に対してのみネイティブDM/channelルーティングを維持し、
plugin承認は共有の同一チャット
/approveパスに残します。
createApproverRestrictedNativeApprovalAdapterは互換ラッパーとしてまだ存在しますが、新しいコードではcapability builderを優先し、plugin上でapprovalCapabilityを公開してください。
openclaw/plugin-sdk/approval-auth-runtimeopenclaw/plugin-sdk/approval-client-runtimeopenclaw/plugin-sdk/approval-delivery-runtimeopenclaw/plugin-sdk/approval-native-runtimeopenclaw/plugin-sdk/approval-reply-runtime
openclaw/plugin-sdk/setup-runtime、
openclaw/plugin-sdk/setup-adapter-runtime、
openclaw/plugin-sdk/reply-runtime、
openclaw/plugin-sdk/reply-dispatch-runtime、
openclaw/plugin-sdk/reply-reference、および
openclaw/plugin-sdk/reply-chunkingを優先してください。
セットアップ固有では:
openclaw/plugin-sdk/setup-runtimeは、ランタイム安全なセットアップヘルパーを扱います: import安全なセットアップパッチアダプター(createPatchedAccountSetupAdapter、createEnvPatchedAccountSetupAdapter、createSetupInputPresenceValidator)、lookup-note出力、promptResolvedAllowFrom、splitSetupEntries、および委譲された setup-proxy builderopenclaw/plugin-sdk/setup-adapter-runtimeは、createEnvPatchedAccountSetupAdapter向けの狭いenv対応アダプター シームですopenclaw/plugin-sdk/channel-setupは、任意インストールのセットアップ builderと、いくつかのセットアップ安全な基本要素を扱います:createOptionalChannelSetupSurface、createOptionalChannelSetupAdapter、createOptionalChannelSetupWizard、DEFAULT_ACCOUNT_ID、createTopLevelChannelDmPolicy、setSetupChannelEnabled、およびsplitSetupEntries- より重い共有セットアップ/設定ヘルパー、たとえば
moveSingleAccountChannelSectionToDefaultAccount(...)も必要な場合にのみ、 より広いopenclaw/plugin-sdk/setupシームを使用してください
createOptionalChannelSetupSurface(...)を優先してください。生成されるadapter/wizardは設定書き込みと最終化でフェイルクローズし、検証、最終化、ドキュメントリンク文言全体で同じインストール必須メッセージを再利用します。
その他のホットなchannelパスでも、広い古いsurfaceより狭いヘルパーを優先してください:
- マルチアカウント設定と
デフォルトアカウントフォールバックには
openclaw/plugin-sdk/account-core、openclaw/plugin-sdk/account-id、openclaw/plugin-sdk/account-resolution、およびopenclaw/plugin-sdk/account-helpers - 受信ルート/エンベロープと
record-and-dispatch配線には
openclaw/plugin-sdk/inbound-envelopeとopenclaw/plugin-sdk/inbound-reply-dispatch - ターゲット解析/マッチングには
openclaw/plugin-sdk/messaging-targets - メディア読み込みと送信
identity/send delegateには
openclaw/plugin-sdk/outbound-mediaとopenclaw/plugin-sdk/outbound-runtime - thread-bindingライフサイクル
とadapter登録には
openclaw/plugin-sdk/thread-bindings-runtime - 古いagent/media
ペイロードフィールドレイアウトがまだ必要な場合のみ
openclaw/plugin-sdk/agent-media-payload - Telegramカスタムコマンド
正規化、重複/競合検証、およびフォールバック安定なコマンド
設定契約には
openclaw/plugin-sdk/telegram-command-config
ウォークスルー
パッケージとマニフェスト
標準的なpluginファイルを作成します。
package.jsonのchannelフィールドが、
これをchannel pluginにします。完全なpackage-metadataサーフェスについては、
Plugin Setup and Configを参照してください:channel pluginオブジェクトを構築する
ChannelPluginインターフェースには多くの任意adapter surfaceがあります。まず
最小構成であるidとsetupから始め、必要に応じてadapterを追加してください。src/channel.tsを作成します:src/channel.ts
createChatChannelPluginが代わりに行ってくれること
createChatChannelPluginが代わりに行ってくれること
低レベルadapter interfaceを手動実装する代わりに、
宣言的オプションを渡すと、builderがそれらを合成します:
完全制御が必要な場合は、宣言的オプションの代わりに生のadapterオブジェクトを渡すこともできます。
| Option | 配線されるもの |
|---|---|
security.dm | 設定フィールドからのスコープ付きDM security resolver |
pairing.text | コード交換によるテキストベースDM pairingフロー |
threading | reply-to-mode resolver(固定、アカウントスコープ、またはカスタム) |
outbound.attachedResults | 結果メタデータ(message ID)を返すsend関数 |
エントリポイントを配線する
index.tsを作成します:index.ts
registerCliMetadata(...)に置いてください。これによりOpenClawは、完全なchannel runtimeを有効化せずに
root helpへそれらを表示でき、通常の完全ロードでも実際のコマンド登録のために同じdescriptorを取得できます。registerFull(...)はruntime専用作業のために保持してください。
registerFull(...)がgateway RPC methodを登録する場合は、
plugin固有プレフィックスを使用してください。core管理namespace(config.*、
exec.approvals.*、wizard.*、update.*)は予約されており、常に
operator.adminへ解決されます。
defineChannelPluginEntryは、登録モードの分割を自動処理します。すべての
オプションについてはEntry Pointsを参照してください。setup entryを追加する
オンボーディング中の軽量ロードのためにOpenClawは、channelが無効または未設定のとき、完全entryの代わりにこれをロードします。
これにより、セットアップフロー中に重いruntimeコードを引き込まずに済みます。
詳細はSetup and Configを参照してください。
setup-entry.tsを作成します:setup-entry.ts
受信メッセージを処理する
pluginは、プラットフォームからメッセージを受信し、それを
OpenClawへ転送する必要があります。典型的なパターンは、リクエストを検証し、
そのchannelのinbound handler経由でディスパッチするWebhookです:
inboundメッセージ処理はchannel固有です。各channel pluginは
独自のinboundパイプラインを所有します。実際のパターンについては、bundled channel plugins
(たとえばMicrosoft TeamsまたはGoogle Chat plugin package)を確認してください。
テスト
ファイル構造
高度なトピック
スレッド化オプション
固定、アカウントスコープ、またはカスタムのreply mode
Message tool統合
describeMessageToolとactionディスカバリー
ターゲット解決
inferTargetChatType、looksLikeId、resolveTarget
runtimeヘルパー
api.runtime経由のTTS、STT、media、subagent
一部のbundled helper seamは、bundled-pluginの保守と
互換性のために依然存在します。これらは新しいchannel pluginsに推奨されるパターンではありません。
そのbundled pluginファミリーを直接保守しているのでない限り、
共通SDKサーフェスの汎用的なchannel/setup/reply/runtime subpathを優先してください。
次のステップ
- Provider Plugins — pluginがモデルも提供する場合
- SDK Overview — 完全なsubpath importリファレンス
- SDK Testing — テストユーティリティと契約テスト
- Plugin Manifest — 完全なマニフェストスキーマ