​

チャネル Plugin の構築

​

チャネル Plugin の仕組み

• 設定 — アカウント解決とセットアップウィザード
• セキュリティ — DM ポリシーと許可リスト
• ペアリング — DM 承認フロー
• セッショングラマー — プロバイダー固有の会話 ID を、どのようにベースチャット、スレッド ID、親フォールバックへ対応付けるか
• 送信 — テキスト、メディア、投票をプラットフォームへ送信する処理
• スレッド化 — 返信をどのようにスレッド化するか

​

承認とチャネル機能

• コアは、同一チャット内の /approve、共有承認ボタンのペイロード、汎用フォールバック配信を担います。
• チャネルで承認固有の挙動が必要な場合は、チャネル Plugin 上に1つの approvalCapability オブジェクトを置くのが望ましいです。
• ChannelPlugin.approvals は削除されました。承認の配信/ネイティブ/レンダリング/認証に関する情報は approvalCapability に置いてください。
• plugin.auth は login/logout 専用です。コアはそのオブジェクトから承認認証フックをもう読みません。
• approvalCapability.authorizeActorAction と approvalCapability.getActionAvailabilityState が、承認認証の正規の公開インターフェースです。
• 同一チャット内の承認認証の可用性には approvalCapability.getActionAvailabilityState を使用してください。
• チャネルがネイティブ exec 承認を公開する場合は、開始サーフェス/ネイティブクライアントの状態が同一チャット承認認証と異なるときに approvalCapability.getExecInitiatingSurfaceState を使用してください。コアはこの exec 専用フックを使用して、enabled と disabled を区別し、開始チャネルがネイティブ exec 承認をサポートするかどうかを判断し、ネイティブクライアントのフォールバック案内にそのチャネルを含めます。createApproverRestrictedNativeApprovalCapability(...) は、この一般的なケースを埋めます。
• 重複したローカル承認プロンプトを隠す、配信前に typing indicator を送る、といったチャネル固有のペイロードライフサイクル挙動には、outbound.shouldSuppressLocalPayloadPrompt または outbound.beforeDeliverPayload を使用してください。
• approvalCapability.delivery は、ネイティブ承認のルーティングまたはフォールバック抑制にのみ使用してください。
• approvalCapability.nativeRuntime は、チャネル所有のネイティブ承認情報に使用してください。ホットなチャネルエントリーポイントでは createLazyChannelApprovalNativeRuntimeAdapter(...) を使って遅延化し、必要時にランタイムモジュールを import できるようにしつつ、コアが承認ライフサイクルを組み立てられるようにしてください。
• approvalCapability.render は、チャネルが共有レンダラーではなく本当にカスタム承認ペイロードを必要とする場合にのみ使用してください。
• チャネルが、ネイティブ exec 承認を有効にするために必要な正確な設定項目を disabled 経路の返信で説明したい場合は、approvalCapability.describeExecApprovalSetup を使用してください。このフックは { channel, channelLabel, accountId } を受け取ります。名前付きアカウントチャネルは、トップレベルのデフォルトではなく、channels.<channel>.accounts.<id>.execApprovals.* のようなアカウントスコープのパスをレンダリングしてください。
• チャネルが既存設定から安定した owner 類似の DM ID を推測できる場合は、承認固有のコアロジックを追加せずに、同一チャット内の /approve を制限するために openclaw/plugin-sdk/approval-runtime の createResolvedApproverActionAuthAdapter を使用してください。
• チャネルがネイティブ承認配信を必要とする場合は、チャネルコードをターゲット正規化とトランスポート/表示情報に集中させてください。openclaw/plugin-sdk/approval-runtime の createChannelExecApprovalProfile、createChannelNativeOriginTargetResolver、createChannelApproverDmTargetResolver、createApproverRestrictedNativeApprovalCapability を使用してください。チャネル固有の情報は approvalCapability.nativeRuntime の背後に置き、理想的には createChannelApprovalNativeRuntimeAdapter(...) または createLazyChannelApprovalNativeRuntimeAdapter(...) を介してください。そうすることで、コアがハンドラーを組み立て、リクエストのフィルタリング、ルーティング、重複排除、有効期限、Gateway 購読、別経路ルーティング通知を担えます。nativeRuntime は、いくつかの小さな公開インターフェースに分かれています。
• availability — アカウントが設定済みかどうか、およびリクエストを処理すべきかどうか
• presentation — 共有承認ビュー・モデルを pending/resolved/expired のネイティブペイロードや最終アクションへ変換
• transport — ターゲットを準備し、ネイティブ承認メッセージを送信/更新/削除
• interactions — ネイティブボタンやリアクション向けの任意の bind/unbind/clear-action フック
• observe — 任意の配信診断フック
• チャネルが client、token、Bolt app、Webhook レシーバーのようなランタイム所有オブジェクトを必要とする場合は、openclaw/plugin-sdk/channel-runtime-context を通じて登録してください。汎用 runtime-context レジストリにより、コアは承認固有のラッパー glue を追加せずに、チャネル起動状態から capability 駆動ハンドラーをブートストラップできます。
• capability 駆動の公開インターフェースではまだ表現力が足りない場合にのみ、より低レベルの createChannelApprovalHandler または createChannelNativeApprovalRuntime を使ってください。
• ネイティブ承認チャネルでは、accountId と approvalKind の両方をそれらのヘルパー経由でルーティングする必要があります。accountId は複数アカウントの承認ポリシーを正しい bot アカウントにスコープし、approvalKind は exec と Plugin 承認の挙動を、コアにハードコードされた分岐なしでチャネル側で扱えるようにします。
• コアは現在、承認の再ルーティング通知も担います。チャネル Plugin は createChannelNativeApprovalRuntime から独自の「承認は DM / 別チャネルへ送られました」というフォローアップメッセージを送るべきではありません。代わりに、共有承認 capability ヘルパーを通じて正確な送信元 + approver-DM ルーティングを公開し、実際の配信を集約したうえで、必要な通知を開始チャットへ投稿するかどうかはコアに任せてください。
• 配信された承認 ID の種類は、最初から最後まで保持してください。ネイティブクライアントは、チャネルローカルの状態から exec と Plugin 承認のルーティングを推測したり書き換えたりしてはいけません。
• 異なる承認種別は、意図的に異なるネイティブサーフェスを公開してよい場合があります。 現在の同梱例:
  • Slack は exec と Plugin の両方の ID について、ネイティブ承認ルーティングを利用可能なままにしています。
  • Matrix は exec と Plugin 承認の両方で同じネイティブ DM/チャネルルーティングと reaction UX を維持しつつ、承認種別ごとに auth だけは異なるようにできます。
• createApproverRestrictedNativeApprovalAdapter は互換ラッパーとしてまだ存在しますが、新しいコードでは capability builder を優先し、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-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 は、ランタイム安全なセットアップヘルパーをカバーします: import-safe なセットアップ patch アダプター（createPatchedAccountSetupAdapter、createEnvPatchedAccountSetupAdapter、createSetupInputPresenceValidator）、lookup-note 出力、promptResolvedAllowFrom、splitSetupEntries、および委譲セットアッププロキシ builder
• openclaw/plugin-sdk/setup-adapter-runtime は、createEnvPatchedAccountSetupAdapter のための、より狭い env 対応アダプター公開インターフェースです
• openclaw/plugin-sdk/channel-setup は、任意インストールのセットアップ builder と、いくつかのセットアップ安全な基本要素をカバーします: createOptionalChannelSetupSurface、createOptionalChannelSetupAdapter、

• 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/inbound-reply-dispatch は、受信ルート/エンベロープおよび record-and-dispatch 配線向け
• openclaw/plugin-sdk/messaging-targets は、ターゲットの解析/マッチング向け
• openclaw/plugin-sdk/outbound-media と openclaw/plugin-sdk/outbound-runtime は、メディア読み込みと送信 identity/send delegate 向け
• openclaw/plugin-sdk/thread-bindings-runtime は、スレッドバインディングのライフサイクルと adapter 登録向け
• openclaw/plugin-sdk/agent-media-payload は、レガシー agent/media ペイロードのフィールドレイアウトがまだ必要な場合のみ
• openclaw/plugin-sdk/telegram-command-config は、Telegram カスタムコマンドの正規化、重複/競合検証、およびフォールバック安定なコマンド設定契約向け

​

受信メンションポリシー

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

• bot への返信検出
• bot の引用検出
• スレッド参加チェック
• service/system メッセージの除外
• bot 参加を証明するために必要なプラットフォームネイティブのキャッシュ

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

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

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

const mentionMatch = matchesMentionWithExplicit(text, {
  mentionRegexes,
  mentionPatterns,
});

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

const decision = resolveInboundMentionDecision({
  facts,
  policy: {
    isGroup,
    requireMention,
    allowedImplicitMentionKinds: requireExplicitMention ? [] : ["reply_to_bot", "quoted_bot"],
    allowTextCommands,
    hasControlCommand,
    commandAuthorized,
  },
});

if (decision.shouldSkip) return;

• buildMentionRegexes
• matchesMentionPatterns
• matchesMentionWithExplicit
• implicitMentionKindWhen
• resolveInboundMentionDecision

​

ウォークスルー

{
  "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": "Connect OpenClaw to Acme Chat."
    }
  }
}

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",
    setup: {
      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",
        };
      },
    },
  }),

  // 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: {
      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-managed auth (verify signatures yourself)
    handler: async (req, res) => {
      const event = parseWebhookPayload(req);

      // Your inbound handler dispatches the message to OpenClaw.
      // The exact wiring depends on your platform SDK —
      // see a real example in the bundled Microsoft Teams or Google Chat plugin package.
      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("resolves account from config", () => {
    const cfg = {
      channels: {
        "acme-chat": { token: "test-token", allowFrom: ["user1"] },
      },
    } as any;
    const account = acmeChatPlugin.setup!.resolveAccount(cfg, undefined);
    expect(account.token).toBe("test-token");
  });

  it("inspects account without materializing secrets", () => {
    const cfg = {
      channels: { "acme-chat": { token: "test-token" } },
    } as any;
    const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(true);
    expect(result.tokenStatus).toBe("available");
  });

  it("reports missing config", () => {
    const cfg = { channels: {} } as any;
    const result = acmeChatPlugin.setup!.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            # ランタイムストア（必要な場合）

​

高度なトピック

​

次のステップ

• Provider Plugins — Plugin がモデルも提供する場合
• SDK Overview — 完全な subpath import リファレンス
• SDK Testing — テストユーティリティとコントラクトテスト
• Plugin Manifest — 完全なマニフェストスキーマ