チャネル Plugin の構築

​

Plugin が担うもの

• 設定 - アカウントの解決とセットアップウィザード
• セキュリティ - DM ポリシーと許可リスト
• ペアリング - DM 承認フロー
• セッション文法 - プロバイダー固有の会話 ID をベースチャット、 スレッド ID、親フォールバックにマッピングする方法
• 送信 - プラットフォームへのテキスト、メディア、投票の送信
• スレッド化 - 返信をスレッド化する方法
• Heartbeat の入力中表示 - Heartbeat の配信先に対する任意の入力中／処理中シグナル

​

メッセージアダプター

​

受信イングレス（試験的）

​

永続的なイングレスとリプレイ重複排除

​

トランスポートクラスと保持

• 確認応答で制御される Webhook またはイベント配信： 永続的な追加の後にのみ確認応答または成功を返します。追加に失敗した場合は、配信を再試行可能な状態に維持するか、受信境界を失敗させる必要があります。このクラスには Slack、SMS、Zalo、Microsoft Teams、Google Chat、LINE、Synology Chat が含まれます。
• 待機されるポーリングまたはストリーム配信： 追加の後にのみリモートカーソルを進めるか、トランスポートの確認応答を送信します。明示的なカーソルがない場合は、受信コールバックを直列化して待機し、追加の失敗時に受信ループが先へ進めないようにします。Telegram のポーリング、Signal、Tlon はこのクラスを使用します。Telegram の Webhook 配信には、前述の確認応答で制御される規則が適用されます。
• リプレイ不可のソケット： IRC、Mattermost、Twitch、Zalo Personal は、受け入れ済みイベントの再配信をプラットフォームに要求できません。これらの永続キューはプロセスクラッシュの時間枠を保護し、ローカル再起動時の復旧を支援します。完了トゥームストーンは、プラットフォームのリプレイに対してほぼ効果を持ちません。

​

少なくとも 1 回の副作用

​

アカウント単位の再起動コントラクト

​

入力中インジケーター

​

メディアソースパラメーター

​

ネイティブペイロードの整形

​

セッション会話文法

​

アカウントスコープの会話バインディング対応

​

承認とチャンネルケイパビリティ

​

承認認証

• approvalCapability.authorizeActorAction と approvalCapability.getActionAvailabilityState が、正規の 承認認証シームです。
• 同一チャットの承認認証が利用可能かどうかには getActionAvailabilityState を使用します。 ネイティブ配信が無効な場合でも、設定済み承認者を /approve で利用可能に 保ってください。配信／設定ガイダンスには、代わりにネイティブの開始元サーフェス状態を 使用します。
• チャンネルがネイティブ exec 承認を公開し、その開始元サーフェス／ネイティブクライアントの 状態が同一チャットの承認認証と異なる場合は、 approvalCapability.getExecInitiatingSurfaceState を使用します。コアはこの exec 固有フックを使用して enabled と disabled を区別し、開始元チャンネルがネイティブ exec 承認に対応しているかどうかを判断し、そのチャンネルをネイティブクライアントの フォールバックガイダンスに含めます。一般的なケースでは createApproverRestrictedNativeApprovalCapability(...) がこれを補完します。
• チャンネルが既存の設定から安定した所有者相当の DM ID を推論できる場合は、 openclaw/plugin-sdk/approval-runtime の createResolvedApproverActionAuthAdapter を使用して、 承認固有のコアロジックを追加せずに同一チャットの /approve を制限します。
• カスタム承認認証で同一チャットのフォールバックのみを意図的に許可する場合は、 openclaw/plugin-sdk/approval-auth-runtime から markImplicitSameChatApprovalAuthorization({ authorized: true }) を返します。 それ以外の場合、コアはその結果を明示的な承認者の認可として扱います。
• チャンネル所有のネイティブコールバックが承認を直接解決する場合は、解決前に isImplicitSameChatApprovalAuthorization(...) を使用し、暗黙の フォールバックもチャンネルの通常のアクター認可を通るようにします。

​

ペイロードのライフサイクルと設定ガイダンス

• 重複するローカル承認プロンプトを非表示にしたり、配信前に入力中インジケーターを 送信したりするなど、チャンネル固有のペイロードライフサイクル動作には、 outbound.shouldSuppressLocalPayloadPrompt または outbound.beforeDeliverPayload を使用します。
• 無効時の応答で、ネイティブ exec 承認を有効にするために必要な正確な設定項目を 説明する場合は、approvalCapability.describeExecApprovalSetup を使用します。 このフックは { channel, channelLabel, accountId } を受け取ります。 名前付きアカウントを持つチャンネルでは、トップレベルのデフォルトではなく channels.<channel>.accounts.<id>.execApprovals.* のようなアカウントスコープのパスを レンダリングする必要があります。
• Plugin 承認のルートなしエラーおよびタイムアウトエラーで、Plugin 承認の 失敗ガイダンスを安全に表示できる場合は、approvalCapability.describePluginApprovalSetup を使用します。 createApproverRestrictedNativeApprovalCapability(...) は describeExecApprovalSetup からこれを推論しません。Plugin 承認と exec 承認が本当に同じ ネイティブ設定を使用する場合に限り、同じヘルパーを明示的に渡します。

​

ネイティブ承認の配信

• availability - アカウントが設定済みか、およびリクエストを 処理すべきかどうか
• presentation - 共有承認ビューモデルを、 保留中／解決済み／期限切れのネイティブペイロードまたは最終アクションにマッピング
• transport - ターゲットを準備し、ネイティブ承認 メッセージを送信／更新／削除
• interactions - ネイティブボタンまたはリアクション向けの、任意のバインド／バインド解除／アクション消去フックと、 任意の cancelDelivered フック。deliverPending がプロセス内または永続的な 状態（リアクションターゲットストアなど）を登録する場合は、cancelDelivered を実装します。 これにより、ハンドラーの停止によって bindPending の実行前に配信がキャンセルされた場合、 または bindPending がハンドルを返さない場合に、その状態を解放できます。
• observe - 任意の配信診断フック

• チャンネルがセッション起点のネイティブ配信と明示的な承認転送ターゲットの両方に 対応する場合は、openclaw/plugin-sdk/approval-native-runtime の createNativeApprovalChannelRouteGates を使用します。このヘルパーは、 承認設定の選択、mode の処理、エージェント／セッションフィルター、 アカウントバインディング、セッションターゲットの照合、およびターゲットリストの照合を 一元化します。一方で呼び出し側は引き続き、チャンネル ID、デフォルト転送モード、 アカウント検索、トランスポート有効化チェック、ターゲット正規化、およびターンソースの ターゲット解決を担当します。コア所有のチャンネルポリシーのデフォルトを作成するために 使用しないでください。チャンネルで文書化されたデフォルトモードを明示的に渡します。
• createChannelNativeOriginTargetResolver は、{ to, accountId, threadId } ターゲットに対して、デフォルトで共有チャンネルルート マッチャーを使用します。Slack のタイムスタンプ接頭辞マッチングなど、チャンネルに プロバイダー固有の同値ルールがある場合に限り、targetsMatch を渡します。 配信用の元のターゲットを維持しながら、デフォルトのルートマッチャーまたはカスタムの targetsMatch コールバックが実行される前にプロバイダー ID を正規化する必要がある場合は、 normalizeTargetForMatch を渡します。解決された配信ターゲット自体を正規化する必要がある場合に限り、 normalizeTarget を使用します。
• チャンネルでクライアント、トークン、Bolt アプリ、Webhook レシーバーなどのランタイム所有オブジェクトが必要な場合は、 openclaw/plugin-sdk/channel-runtime-context を介して登録します。汎用ランタイムコンテキスト レジストリにより、承認固有のラッパーグルーを追加せずに、チャンネルの 起動状態からケイパビリティ駆動のハンドラーをコアがブートストラップできます。
• ケイパビリティ駆動のシームの表現力がまだ十分でない場合に限り、低レベルの createChannelApprovalHandler または createChannelNativeApprovalRuntime を使用します。
• ネイティブ承認チャンネルは、accountId と approvalKind の両方を これらのヘルパー経由でルーティングする必要があります。accountId は複数アカウントの承認ポリシーを 適切なボットアカウントに限定し、approvalKind はコアにハードコードされた分岐を 追加せずに、exec 承認と Plugin 承認の動作をチャンネルで利用可能に保ちます。
• 承認の再ルーティング通知もコアが担当します。チャンネル Plugin は、 createChannelNativeApprovalRuntime から独自の「承認は DM／別のチャンネルに送信されました」という フォローアップメッセージを送信しないでください。代わりに、共有承認ケイパビリティ ヘルパーを介して正確な起点＋承認者 DM ルーティングを公開し、コアが実際の配信を 集約した後、開始元チャットへの通知を投稿するようにします。
• 配信された承認 ID の種別をエンドツーエンドで維持します。ネイティブクライアントは、 チャンネルローカルの状態から exec 承認と Plugin 承認のルーティングを推測したり、 書き換えたりしてはなりません。
• その明示的な approvalKind を resolveApprovalOverGateway に渡します。これは、 正規の approval.resolve サービスを使用し、別のサーフェスが先に応答した場合は 記録済みの勝者を返します。古い明示的な resolveMethod 入力は、 コマンドベースのコントロール向けに残されています。新しいネイティブアクションでは、 これを使用したり、ID から種別を推論したりしてはなりません。
• 承認の種別ごとに、意図的に異なるネイティブサーフェスを公開できます。現在のバンドル例では、 Matrix は exec 承認と Plugin 承認で同じネイティブ DM／チャンネルルーティングと リアクション UX を維持しつつ、承認種別によって認証を変えられます。Slack は exec ID と Plugin ID の両方でネイティブ承認ルーティングを利用可能に保ちます。
• createApproverRestrictedNativeApprovalAdapter は互換ラッパーとして 引き続き存在しますが、新しいコードではケイパビリティビルダーを優先し、 Plugin 上で approvalCapability を公開する必要があります。

​

より限定的な承認ランタイムサブパス

• openclaw/plugin-sdk/approval-auth-runtime
• openclaw/plugin-sdk/approval-client-runtime
• openclaw/plugin-sdk/approval-delivery-runtime
• openclaw/plugin-sdk/approval-gateway-runtime
• openclaw/plugin-sdk/approval-reference-runtime
• openclaw/plugin-sdk/approval-handler-adapter-runtime
• openclaw/plugin-sdk/approval-handler-runtime
• openclaw/plugin-sdk/approval-native-runtime
• openclaw/plugin-sdk/approval-reply-runtime
• openclaw/plugin-sdk/channel-runtime-context

​

セットアップのサブパス

• openclaw/plugin-sdk/setup-runtimeは、ランタイムで安全なセットアップヘルパーを対象とします。 createSetupTranslator、インポートしても安全なセットアップパッチアダプター （createPatchedAccountSetupAdapter、createEnvPatchedAccountSetupAdapter、 createSetupInputPresenceValidator）、検索メモの出力、 promptResolvedAllowFrom、splitSetupEntries、および委譲された セットアッププロキシビルダーです。
• openclaw/plugin-sdk/channel-setupは、オプションインストール用セットアップ ビルダーと、セットアップで安全ないくつかのプリミティブを対象とします。createOptionalChannelSetupSurface、 createOptionalChannelSetupAdapter、createOptionalChannelSetupWizard、 DEFAULT_ACCOUNT_ID、createTopLevelChannelDmPolicy、 setSetupChannelEnabled、およびsplitSetupEntriesです。
• moveSingleAccountChannelSectionToDefaultAccount(...)のような、より重量のある共有セットアップ／設定ヘルパーも 必要な場合にのみ、より広範なopenclaw/plugin-sdk/setupシームを使用してください。

​

その他の狭いチャンネルサブパス

• 複数アカウントの設定とデフォルトアカウントへの フォールバックには、openclaw/plugin-sdk/account-core、openclaw/plugin-sdk/account-id、 openclaw/plugin-sdk/account-resolution、および openclaw/plugin-sdk/account-helpers
• 受信ルート／エンベロープ、および記録してディスパッチする 結線には、openclaw/plugin-sdk/inbound-envelopeと openclaw/plugin-sdk/channel-inbound
• 対象解析ヘルパーには、openclaw/plugin-sdk/channel-targets
• 送信ID／送信デリゲートと型付きペイロード計画には、 openclaw/plugin-sdk/channel-outbound
• 送信ルートが明示的なreplyToId/threadIdを保持する必要がある場合、または ベースセッションキーが引き続き一致した後に現在の:thread:セッションを復元する必要がある場合は、 openclaw/plugin-sdk/channel-coreのbuildThreadAwareOutboundSessionRoute(...)。 プラットフォームにネイティブのスレッド配信セマンティクスがある場合、 プロバイダーPluginは優先順位、サフィックスの動作、スレッドIDの正規化を オーバーライドできます。
• スレッドバインディングのライフサイクルと アダプター登録には、openclaw/plugin-sdk/thread-bindings-runtime

​

受信メンションポリシー

• Plugin所有の根拠収集
• 共有ポリシー評価

• Botへの返信の検出
• 引用されたBotの検出
• スレッド参加の確認
• サービス／システムメッセージの除外
• Botの参加を立証するために必要なプラットフォームネイティブのキャッシュ

• requireMention
• 明示的メンションの結果
• 暗黙的メンションの許可リスト
• コマンドのバイパス
• 最終的なスキップ判定

1. ローカルのメンション情報を計算します。
2. その情報をresolveInboundMentionDecision({ facts, policy })に渡します。
3. 受信ゲートでdecision.effectiveWasMentioned、decision.shouldBypassMention、および decision.shouldSkipを使用します。

import {
  implicitMentionKindWhen,
  matchesMentionWithExplicit,
  resolveInboundMentionDecision,
} from "openclaw/plugin-sdk/channel-inbound";
import { resolveChannelImplicitMentions } from "openclaw/plugin-sdk/channel-ingress-runtime";

const wasMentioned = matchesMentionWithExplicit({
  text,
  mentionRegexes,
  explicit: {
    hasAnyMention,
    isExplicitlyMentioned,
    canResolveExplicit,
  },
});

const facts = {
  canDetectMention: true,
  wasMentioned,
  hasAnyMention,
  implicitMentionKinds: [
    ...implicitMentionKindWhen("reply_to_bot", isReplyToBot),
    ...implicitMentionKindWhen("quoted_bot", isQuoteOfBot),
  ],
};

const implicitMentions = resolveChannelImplicitMentions({
  cfg,
  channel: channelId,
  accountId,
});

const decision = resolveInboundMentionDecision({
  facts,
  policy: {
    isGroup,
    requireMention,
    implicitMentions,
    allowTextCommands,
    hasControlCommand,
    commandAuthorized,
  },
});

if (decision.shouldSkip) return;

​

手順

{
  "name": "@myorg/openclaw-acme-chat",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "channel": {
      "id": "acme-chat",
      "label": "Acme Chat",
      "blurb": "OpenClawをAcme Chatに接続します。"
    }
  }
}

{
  "id": "acme-chat",
  "channels": ["acme-chat"],
  "name": "Acme Chat",
  "description": "Acme ChatチャンネルPlugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  },
  "channelConfigs": {
    "acme-chat": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "token": { "type": "string" },
          "allowFrom": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      },
      "uiHints": {
        "token": {
          "label": "Botトークン",
          "sensitive": true
        }
      }
    }
  }
}

import {
  createChatChannelPlugin,
  createChannelPluginBase,
} from "openclaw/plugin-sdk/channel-core";
import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
import { acmeChatApi } from "./client.js"; // your platform API client

type ResolvedAccount = {
  accountId: string | null;
  token: string;
  allowFrom: string[];
  dmPolicy: string | undefined;
};

function resolveAccount(
  cfg: OpenClawConfig,
  accountId?: string | null,
): ResolvedAccount {
  const section = (cfg.channels as Record<string, any>)?.["acme-chat"];
  const token = section?.token;
  if (!token) throw new Error("acme-chat: token is required");
  return {
    accountId: accountId ?? null,
    token,
    allowFrom: section?.allowFrom ?? [],
    dmPolicy: section?.dmSecurity,
  };
}

export const acmeChatPlugin = createChatChannelPlugin<ResolvedAccount>({
  base: createChannelPluginBase({
    id: "acme-chat",
    // Account resolution/inspection belongs on `config`, not `setup`.
    // `setup` covers onboarding writes (applyAccountConfig, validateInput).
    config: {
      listAccountIds: () => ["default"],
      resolveAccount,
      inspectAccount(cfg, accountId) {
        const section =
          (cfg.channels as Record<string, any>)?.["acme-chat"];
        return {
          enabled: Boolean(section?.token),
          configured: Boolean(section?.token),
          tokenStatus: section?.token ? "available" : "missing",
        };
      },
    },
    setup: {
      applyAccountConfig: ({ cfg, input }) => ({
        ...cfg,
        channels: {
          ...cfg.channels,
          "acme-chat": { ...(cfg.channels as any)?.["acme-chat"], ...input },
        },
      }),
    },
  }),

  // DM security: who can message the bot
  security: {
    dm: {
      channelKey: "acme-chat",
      resolvePolicy: (account) => account.dmPolicy,
      resolveAllowFrom: (account) => account.allowFrom,
      defaultPolicy: "allowlist",
    },
  },

  // Pairing: approval flow for new DM contacts
  pairing: {
    text: {
      idLabel: "Acme Chat username",
      message: "Send this code to verify your identity:",
      notify: async ({ target, code }) => {
        await acmeChatApi.sendDm(target, `Pairing code: ${code}`);
      },
    },
  },

  // Threading: how replies are delivered
  threading: { topLevelReplyToMode: "reply" },

  // Outbound: send messages to the platform
  outbound: {
    attachedResults: {
      channel: "acme-chat",
      sendText: async (params) => {
        const result = await acmeChatApi.sendMessage(
          params.to,
          params.text,
        );
        return { messageId: result.id };
      },
    },
    base: {
      sendMedia: async (params) => {
        await acmeChatApi.sendFile(params.to, params.filePath);
      },
    },
  },
});

import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { acmeChatPlugin } from "./src/channel.js";

export default defineChannelPluginEntry({
  id: "acme-chat",
  name: "Acme Chat",
  description: "Acme Chat channel plugin",
  plugin: acmeChatPlugin,
  registerCliMetadata(api) {
    api.registerCli(
      ({ program }) => {
        program
          .command("acme-chat")
          .description("Acme Chat management");
      },
      {
        descriptors: [
          {
            name: "acme-chat",
            description: "Acme Chat management",
            hasSubcommands: false,
          },
        ],
      },
    );
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { acmeChatPlugin } from "./src/channel.js";

export default defineSetupPluginEntry(acmeChatPlugin);

registerFull(api) {
  api.registerHttpRoute({
    path: "/acme-chat/webhook",
    auth: "plugin", // Plugin が管理する認証（署名は自身で検証）
    handler: async (req, res) => {
      const event = parseWebhookPayload(req);

      // 受信ハンドラーがメッセージを OpenClaw にディスパッチします。
      // 正確な接続方法はプラットフォーム SDK によって異なります。
      // バンドル済みの Microsoft Teams または Google Chat Plugin パッケージにある実例を参照してください。
      await handleAcmeChatInbound(api, event);

      res.statusCode = 200;
      res.end("ok");
      return true;
    },
  });
}

import { describe, it, expect } from "vitest";
import { acmeChatPlugin } from "./channel.js";

describe("acme-chat Plugin", () => {
  it("設定からアカウントを解決する", () => {
    const cfg = {
      channels: {
        "acme-chat": { token: "test-token", allowFrom: ["user1"] },
      },
    } as any;
    const account = acmeChatPlugin.config.resolveAccount(cfg, undefined);
    expect(account.token).toBe("test-token");
  });

  it("シークレットを実体化せずにアカウントを検査する", () => {
    const cfg = {
      channels: { "acme-chat": { token: "test-token" } },
    } as any;
    const result = acmeChatPlugin.config.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(true);
    expect(result.tokenStatus).toBe("available");
  });

  it("設定がないことを報告する", () => {
    const cfg = { channels: {} } as any;
    const result = acmeChatPlugin.config.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(false);
  });
});

pnpm test <bundled-plugin-root>/acme-chat/

​

ファイル構成

<bundled-plugin-root>/acme-chat/
├── package.json              # openclaw.channel メタデータ
├── openclaw.plugin.json      # 設定スキーマを含むマニフェスト
├── index.ts                  # defineChannelPluginEntry
├── setup-entry.ts            # defineSetupPluginEntry
├── api.ts                    # 公開エクスポート（任意）
├── runtime-api.ts            # 内部ランタイムエクスポート（任意）
└── src/
    ├── channel.ts            # createChatChannelPlugin による ChannelPlugin
    ├── channel.test.ts       # テスト
    ├── client.ts             # プラットフォーム API クライアント
    └── runtime.ts            # ランタイムストア（必要な場合）

​

高度なトピック

​

次のステップ

• プロバイダー Plugin - Plugin でモデルも提供する場合
• SDK の概要 - サブパスインポートの完全なリファレンス
• SDK のテスト - テストユーティリティとコントラクトテスト
• Plugin マニフェスト - 完全なマニフェストスキーマ

​

関連項目

• Plugin SDK のセットアップ
• Plugin の構築
• エージェントハーネス Plugin