チャネルPluginの構築

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

チャンネル Plugin の仕組み

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

​

承認とチャンネル機能

• コアは、同一チャットの /approve、共有承認ボタンペイロード、汎用フォールバック配信を所有します。
• チャネルに承認固有の挙動が必要な場合は、チャネル Plugin 上の単一の approvalCapability オブジェクトを優先してください。
• ChannelPlugin.approvals は削除されました。承認の配信、ネイティブ、レンダー、認証の情報は approvalCapability に置いてください。
• plugin.auth はログイン/ログアウト専用です。コアは、そのオブジェクトから承認認証フックを読み取らなくなりました。
• approvalCapability.authorizeActorAction と approvalCapability.getActionAvailabilityState は、正規の承認認証シームです。
• 同一チャット承認の認証可用性には approvalCapability.getActionAvailabilityState を使用してください。
• チャネルがネイティブ exec 承認を公開する場合、開始サーフェス/ネイティブクライアント状態が同一チャット承認認証と異なるときは、approvalCapability.getExecInitiatingSurfaceState を使用してください。コアはその exec 固有フックを使用して、enabled と disabled を区別し、開始チャネルがネイティブ exec 承認をサポートするかどうかを判断し、ネイティブクライアントのフォールバック案内にそのチャネルを含めます。createApproverRestrictedNativeApprovalCapability(...) は一般的なケースについてこれを補完します。
• 重複するローカル承認プロンプトを隠したり、配信前にタイピングインジケーターを送信したりするような、チャネル固有のペイロードライフサイクル挙動には、outbound.shouldSuppressLocalPayloadPrompt または outbound.beforeDeliverPayload を使用してください。
• approvalCapability.delivery は、ネイティブ承認ルーティングまたはフォールバック抑制にのみ使用してください。
• チャネル所有のネイティブ承認情報には approvalCapability.nativeRuntime を使用してください。ホットなチャネルエントリポイントでは createLazyChannelApprovalNativeRuntimeAdapter(...) で遅延化してください。これは、コアが承認ライフサイクルを組み立てられる状態を保ちながら、必要に応じてランタイムモジュールを import できます。
• approvalCapability.render は、共有レンダラーではなくカスタム承認ペイロードが本当に必要なチャネルでのみ使用してください。
• チャネルが、ネイティブ exec 承認を有効化するために必要な正確な設定ノブを disabled パスの返信で説明したい場合は、approvalCapability.describeExecApprovalSetup を使用してください。このフックは { channel, channelLabel, accountId } を受け取ります。名前付きアカウントのチャネルは、トップレベルのデフォルトではなく、channels.<channel>.accounts.<id>.execApprovals.* のようなアカウントスコープのパスをレンダーする必要があります。
• チャネルが既存設定から安定した所有者風の DM ID を推測できる場合は、openclaw/plugin-sdk/approval-runtime の createResolvedApproverActionAuthAdapter を使用して、承認固有のコアロジックを追加せずに同一チャットの /approve を制限してください。
• チャネルにネイティブ承認配信が必要な場合、チャネルコードはターゲット正規化とトランスポート/表示情報に集中させてください。openclaw/plugin-sdk/approval-runtime の createChannelExecApprovalProfile、createChannelNativeOriginTargetResolver、createChannelApproverDmTargetResolver、createApproverRestrictedNativeApprovalCapability を使用してください。チャネル固有の情報は approvalCapability.nativeRuntime の背後に置き、できれば createChannelApprovalNativeRuntimeAdapter(...) または createLazyChannelApprovalNativeRuntimeAdapter(...) 経由にしてください。そうすれば、コアがハンドラーを組み立て、リクエストフィルタリング、ルーティング、重複排除、期限切れ、Gateway サブスクリプション、別経路ルーティング通知を所有できます。nativeRuntime は、いくつかの小さなシームに分割されています。
• createChannelNativeOriginTargetResolver は、デフォルトで { to, accountId, threadId } ターゲット向けの共有チャネルルートマッチャーを使用します。Slack のタイムスタンププレフィックス照合のように、チャネルにプロバイダー固有の等価性ルールがある場合にのみ targetsMatch を渡してください。
• デフォルトのルートマッチャーまたはカスタム targetsMatch コールバックが実行される前に、チャネルがプロバイダー ID を正規化する必要があり、かつ配信用には元のターゲットを保持したい場合は、createChannelNativeOriginTargetResolver に normalizeTargetForMatch を渡してください。解決済みの配信ターゲット自体を正規化すべき場合にのみ normalizeTarget を使用してください。
• availability - アカウントが設定済みかどうか、およびリクエストを処理すべきかどうか
• presentation - 共有承認ビューモデルを、保留中/解決済み/期限切れのネイティブペイロードまたは最終アクションにマップします
• transport - ターゲットを準備し、ネイティブ承認メッセージを送信/更新/削除します
• interactions - ネイティブボタンまたはリアクション用の任意のバインド/バインド解除/アクション消去フック
• observe - 任意の配信診断フック
• チャネルにクライアント、トークン、Bolt アプリ、Webhook レシーバーなどのランタイム所有オブジェクトが必要な場合は、openclaw/plugin-sdk/channel-runtime-context 経由で登録してください。汎用ランタイムコンテキストレジストリにより、コアは承認固有のラッパー接着コードを追加せずに、チャネル起動状態から capability 駆動のハンドラーをブートストラップできます。
• 低レベルの createChannelApprovalHandler または createChannelNativeApprovalRuntime に手を伸ばすのは、capability 駆動のシームでまだ十分に表現できない場合だけにしてください。
• ネイティブ承認チャネルは、これらのヘルパーを通じて accountId と approvalKind の両方をルーティングする必要があります。accountId はマルチアカウント承認ポリシーを正しい bot アカウントにスコープし、approvalKind はコアにハードコードされた分岐を置かずに exec と Plugin 承認の挙動をチャネルで利用可能にします。
• コアは承認の再ルーティング通知も所有するようになりました。チャネル Plugin は、createChannelNativeApprovalRuntime から独自の「承認は DM / 別のチャネルに送られました」というフォローアップメッセージを送信しないでください。代わりに、共有承認 capability ヘルパーを通じて正確な発信元 + 承認者 DM ルーティングを公開し、開始チャットへ通知を投稿する前に、コアが実際の配信を集約できるようにしてください。
• 配信された承認 ID の種類をエンドツーエンドで保持してください。ネイティブクライアントは、チャネルローカル状態から exec と Plugin 承認ルーティングを推測したり書き換えたりしてはいけません。
• 異なる承認の種類は、意図的に異なるネイティブサーフェスを公開できます。 現在の同梱例:
  • Slack は exec と Plugin ID の両方でネイティブ承認ルーティングを利用可能にしています。
  • Matrix は exec と Plugin 承認で同じネイティブ DM/チャネルルーティングとリアクション UX を維持しつつ、承認の種類ごとに認証を変えられるようにしています。
• 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 は、ランタイムセーフなセットアップヘルパーをカバーします: import セーフなセットアップパッチアダプター (createPatchedAccountSetupAdapter、 createEnvPatchedAccountSetupAdapter、 createSetupInputPresenceValidator)、lookup-note 出力、 promptResolvedAllowFrom、splitSetupEntries、および委譲された setup-proxy ビルダー
• openclaw/plugin-sdk/setup-runtime には、 createEnvPatchedAccountSetupAdapter 向けの env 対応アダプターシームが含まれます
• openclaw/plugin-sdk/channel-setup は、optional-install セットアップ ビルダーに加え、いくつかのセットアップセーフなプリミティブをカバーします: 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
• ターゲット解析/照合には openclaw/plugin-sdk/messaging-targets
• メディア読み込みに加え、アウトバウンド ID/送信 delegate とペイロード計画には openclaw/plugin-sdk/outbound-media と openclaw/plugin-sdk/outbound-runtime
• ベースセッションキーがまだ一致した後に、アウトバウンドルートが明示的な replyToId/threadId を保持する、または現在の :thread: セッションを復元する必要がある場合は、 openclaw/plugin-sdk/channel-core の buildThreadAwareOutboundSessionRoute(...)。 Provider Plugin は、プラットフォームにネイティブスレッド配信セマンティクスがある場合、優先順位、サフィックス挙動、スレッド ID 正規化を上書きできます。
• スレッドバインディングのライフサイクルとアダプター登録には openclaw/plugin-sdk/thread-bindings-runtime
• レガシー agent/media ペイロードフィールドレイアウトがまだ必要な場合にのみ openclaw/plugin-sdk/agent-media-payload
• Telegram カスタムコマンドの正規化、重複/競合検証、およびフォールバック安定なコマンド設定契約には openclaw/plugin-sdk/telegram-command-config

​

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

• 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";

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 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)

​

高度なトピック

​

次のステップ

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

​

関連

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