チャネル Plugin の構築

​

Plugin が所有するもの

• 設定 - アカウント解決とセットアップウィザード
• セキュリティ - DM ポリシーと許可リスト
• ペアリング - DM 承認フロー
• セッション文法 - プロバイダー固有の会話 ID をベースチャット、スレッド ID、親フォールバックにマッピングする方法
• アウトバウンド - テキスト、メディア、投票をプラットフォームへ送信すること
• スレッド化 - 返信をスレッド化する方法
• Heartbeat タイピング - Heartbeat 配信ターゲット向けの任意のタイピング/ビジー信号

​

メッセージアダプター

​

インバウンド入口（実験的）

​

タイピングインジケーター

​

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

​

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

​

セッション会話文法

​

承認とチャネル機能

​

承認 auth

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

​

ペイロードライフサイクルとセットアップガイダンス

• 重複するローカル承認プロンプトを隠す、配信前にタイピングインジケーターを送る、といったチャネル固有のペイロードライフサイクル挙動には、outbound.shouldSuppressLocalPayloadPrompt または outbound.beforeDeliverPayload を使用します。
• チャネルが無効パスの返信でネイティブ exec 承認を有効化するために必要な正確な設定ノブを説明したい場合は、approvalCapability.describeExecApprovalSetup を使用します。このフックは { channel, channelLabel, accountId } を受け取ります。名前付きアカウントチャネルは、トップレベルのデフォルトではなく、 channels.<channel>.accounts.<id>.execApprovals.* のようなアカウントスコープのパスをレンダリングする必要があります。
• Plugin 承認失敗ガイダンスを Plugin 承認の no-route および timeout 失敗で表示しても安全な場合は、approvalCapability.describePluginApprovalSetup を使用します。createApproverRestrictedNativeApprovalCapability(...) は、これを describeExecApprovalSetup から推測しません。Plugin 承認と exec 承認が本当に同じネイティブセットアップを使う場合のみ、同じヘルパーを明示的に渡してください。

​

ネイティブ承認配信

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

• チャネルがセッション起点のネイティブ配信と明示的な承認転送ターゲットの両方をサポートする場合は、 openclaw/plugin-sdk/approval-native-runtime の createNativeApprovalChannelRouteGates を使用する。このヘルパーは、承認設定の選択、mode の処理、 エージェント/セッションフィルター、アカウントバインディング、セッションターゲット照合、ターゲットリスト照合を 集約する。一方で、呼び出し側は引き続きチャネル id、デフォルト転送モード、アカウント検索、 トランスポート有効化チェック、ターゲット正規化、ターンソースターゲット解決を所有する。 core 所有のチャネルポリシーデフォルトを作成するために使用してはならない。チャネルの 文書化されたデフォルトモードを明示的に渡す。
• createChannelNativeOriginTargetResolver は、デフォルトで { to, accountId, threadId } ターゲット向けの共有チャネルルートマッチャーを使用する。Slack タイムスタンプ接頭辞照合のような、 プロバイダー固有の等価ルールをチャネルが持つ場合にのみ、targetsMatch を渡す。 デフォルトのルートマッチャーまたはカスタム targetsMatch コールバックが実行される前に、 配信用の元のターゲットを保持しながらプロバイダー id を正規化する必要がある場合は、 normalizeTargetForMatch を渡す。解決済みの配信ターゲット自体を正規化すべき場合にのみ normalizeTarget を使用する。
• チャネルがクライアント、トークン、Bolt app、webhook レシーバーなどのランタイム所有オブジェクトを必要とする場合は、 openclaw/plugin-sdk/channel-runtime-context を通じて登録する。汎用 runtime-context レジストリにより、core は承認固有のラッパー接着剤を追加せずに、チャネル起動状態から capability 駆動ハンドラーをブートストラップできる。
• 低レベルの createChannelApprovalHandler または createChannelNativeApprovalRuntime は、capability 駆動の継ぎ目がまだ十分に表現力を持たない場合にのみ使用する。
• ネイティブ承認チャネルは、accountId と approvalKind の両方をこれらのヘルパー経由で ルーティングする必要がある。accountId はマルチアカウント承認ポリシーを正しいボットアカウントにスコープし、 approvalKind は core にハードコードされた分岐を置かずに、exec と Plugin の承認動作を チャネルで利用できるようにする。
• core は承認の再ルーティング通知も所有する。チャネル Plugin は createChannelNativeApprovalRuntime から独自の「承認は DM / 別チャネルに送信されました」フォローアップメッセージを 送信してはならない。代わりに、共有承認 capability ヘルパーを通じて正確な起点 + 承認者 DM ルーティングを公開し、開始元チャットに通知を投稿する前に、core に実際の配信を集約させる。
• 配信された承認 id の種類をエンドツーエンドで保持する。ネイティブクライアントは、チャネルローカル状態から exec と Plugin の承認ルーティングを推測したり書き換えたりしてはならない。
• 異なる承認種別が、意図的に異なるネイティブサーフェスを公開することがある。現在のバンドル例: Matrix は exec と Plugin の承認で同じネイティブ DM/チャネルルーティングとリアクション UX を維持しつつ、 承認種別ごとに auth を変えられる。Slack は exec と Plugin の id の両方で ネイティブ承認ルーティングを利用可能にしている。
• createApproverRestrictedNativeApprovalAdapter は互換ラッパーとしてまだ存在するが、 新しいコードでは capability ビルダーを優先し、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 は、ランタイムセーフなセットアップヘルパーを対象とする: createSetupTranslator、インポートセーフなセットアップパッチアダプター (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator)、lookup-note 出力、 promptResolvedAllowFrom、splitSetupEntries、および委譲された setup-proxy ビルダー。
• 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
• インバウンドルート/エンベロープと record-and-dispatch 配線には、 openclaw/plugin-sdk/inbound-envelope および openclaw/plugin-sdk/channel-inbound
• ターゲット解析ヘルパーには openclaw/plugin-sdk/channel-targets
• メディア読み込みには openclaw/plugin-sdk/outbound-media、アウトバウンド identity/send デリゲートと ペイロード計画には openclaw/plugin-sdk/channel-outbound
• アウトバウンドルートが明示的な replyToId/threadId を保持するべき場合、またはベースセッションキーがまだ一致した後に 現在の :thread: セッションを復元するべき場合は、 openclaw/plugin-sdk/channel-core の buildThreadAwareOutboundSessionRoute(...)。 プロバイダー Plugin は、プラットフォームにネイティブスレッド配信セマンティクスがある場合、 precedence、suffix 動作、thread id 正規化をオーバーライドできる。
• thread-binding ライフサイクルとアダプター登録には openclaw/plugin-sdk/thread-bindings-runtime
• レガシーのエージェント/メディアペイロードフィールドレイアウトがまだ必要な場合にのみ openclaw/plugin-sdk/agent-media-payload
• Telegram カスタムコマンドの正規化、重複/競合検証、フォールバック安定なコマンド設定コントラクトには openclaw/plugin-sdk/telegram-command-config（非推奨: 本番環境で使用するバンドル Plugin はない）。 新しい Plugin コードでは Plugin ローカルのコマンド設定処理を優先する

​

インバウンドメンションポリシー

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

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

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

1. ローカルメンション事実を計算する。
2. それらの事実を resolveInboundMentionDecision({ facts, policy }) に渡す。
3. インバウンドゲートで decision.effectiveWasMentioned、decision.shouldBypassMention、および decision.shouldSkip を使用する。

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

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 decision = resolveInboundMentionDecision({
  facts,
  policy: {
    isGroup,
    requireMention,
    allowedImplicitMentionKinds: requireExplicitMention ? [] : ["reply_to_bot", "quoted_bot"],
    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": "Connect OpenClaw to Acme Chat."
    }
  }
}

{
  "id": "acme-chat",
  "channels": ["acme-chat"],
  "name": "Acme Chat",
  "description": "Acme Chat channel 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 token",
          "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-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.config.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.config.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.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 metadata
├── openclaw.plugin.json      # Manifest with config schema
├── index.ts                  # defineChannelPluginEntry
├── setup-entry.ts            # defineSetupPluginEntry
├── api.ts                    # Public exports (optional)
├── runtime-api.ts            # Internal runtime exports (optional)
└── src/
    ├── channel.ts            # ChannelPlugin via createChatChannelPlugin
    ├── channel.test.ts       # Tests
    ├── client.ts             # Platform API client
    └── runtime.ts            # Runtime store (if needed)

​

高度なトピック

​

次のステップ

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

​

関連

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