建置通道 Plugin

Documentation Index

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

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

​

通道 Plugin 的運作方式

• 設定 - 帳號解析與設定精靈
• 安全性 - DM 政策與允許清單
• 配對 - DM 核准流程
• 工作階段語法 - 供應商特定對話 ID 如何對應到基礎聊天、執行緒 ID 與父層備援
• 對外傳送 - 將文字、媒體和投票傳送到平台
• 執行緒 - 回覆如何串接
• Heartbeat 輸入狀態 - 針對 Heartbeat 傳遞目標的選用輸入中/忙碌訊號

​

核准與通道能力

• 核心擁有同一聊天的 /approve、共用核准按鈕 payload，以及通用的後援傳遞。
• 當通道需要核准專屬行為時，偏好在通道 Plugin 上使用單一 approvalCapability 物件。
• ChannelPlugin.approvals 已移除。請將核准傳遞、原生、算繪、驗證事實放在 approvalCapability。
• plugin.auth 僅用於登入/登出；核心不再從該物件讀取核准驗證 hook。
• approvalCapability.authorizeActorAction 與 approvalCapability.getActionAvailabilityState 是標準的核准驗證接縫。
• 使用 approvalCapability.getActionAvailabilityState 處理同一聊天核准驗證可用性。
• 如果你的通道公開原生 exec 核准，當發起表面/原生用戶端狀態不同於同一聊天核准驗證時，請使用 approvalCapability.getExecInitiatingSurfaceState。核心會使用該 exec 專屬 hook 來區分 enabled 與 disabled、判斷發起通道是否支援原生 exec 核准，並將該通道納入原生用戶端後援指引。createApproverRestrictedNativeApprovalCapability(...) 會為常見情況填入這項內容。
• 使用 outbound.shouldSuppressLocalPayloadPrompt 或 outbound.beforeDeliverPayload 處理通道專屬的 payload 生命週期行為，例如隱藏重複的本機核准提示，或在傳遞前送出輸入中指示。
• 僅將 approvalCapability.delivery 用於原生核准路由或後援抑制。
• 使用 approvalCapability.nativeRuntime 放置通道擁有的原生核准事實。在熱門通道進入點上透過 createLazyChannelApprovalNativeRuntimeAdapter(...) 保持延遲載入；它可以視需要匯入你的 runtime 模組，同時仍讓核心組裝核准生命週期。
• 僅在通道確實需要自訂核准 payload，而非共用算繪器時，才使用 approvalCapability.render。
• 當通道希望 disabled 路徑回覆說明啟用原生 exec 核准所需的精確設定旋鈕時，使用 approvalCapability.describeExecApprovalSetup。該 hook 會收到 { channel, channelLabel, accountId }；具名帳號通道應算繪帳號範圍路徑，例如 channels.<channel>.accounts.<id>.execApprovals.*，而非頂層預設值。
• 如果通道可以從現有設定推斷穩定、類似擁有者的 DM 身分，請使用 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 } 目標使用共用通道路由比對器。只有在通道有供應商專屬等價規則時才傳入 targetsMatch，例如 Slack 時間戳前綴比對。
• 當通道需要在預設路由比對器或自訂 targetsMatch callback 執行前，先將供應商 id 標準化，同時保留原始目標以供傳遞時，請將 normalizeTargetForMatch 傳給 createChannelNativeOriginTargetResolver。只有在解析後的傳遞目標本身應被標準化時，才使用 normalizeTarget。
• availability - 帳號是否已設定，以及請求是否應被處理
• presentation - 將共用核准檢視模型對應到待處理/已解析/已到期的原生 payload 或最終動作
• transport - 準備目標並傳送/更新/刪除原生核准訊息
• interactions - 用於原生按鈕或反應的選用綁定/解除綁定/清除動作 hook
• observe - 選用的傳遞診斷 hook
• 如果通道需要 runtime 擁有的物件，例如用戶端、token、Bolt app 或 webhook receiver，請透過 openclaw/plugin-sdk/channel-runtime-context 註冊。通用 runtime-context 登錄可讓核心從通道啟動狀態啟動能力驅動的處理器，而不新增核准專屬 wrapper 黏合程式碼。
• 只有在能力驅動接縫尚不足以表達需求時，才使用較低層級的 createChannelApprovalHandler 或 createChannelNativeApprovalRuntime。
• 原生核准通道必須透過這些 helper 路由 accountId 與 approvalKind。accountId 會讓多帳號核准政策限定在正確的 bot 帳號範圍內，而 approvalKind 會讓通道可取得 exec 與 Plugin 核准行為，無須在核心中硬編碼分支。
• 核心現在也擁有核准重路由通知。通道 Plugin 不應從 createChannelNativeApprovalRuntime 傳送自己的「核准已送到 DM / 另一個通道」後續訊息；改為透過共用核准能力 helper 公開準確的來源與核准者 DM 路由，並讓核心在發起聊天中發出任何通知前彙總實際傳遞。
• 端對端保留已傳遞核准 id 種類。原生用戶端不應 從通道本機狀態猜測或重寫 exec 與 Plugin 核准路由。
• 不同核准種類可以刻意公開不同的原生表面。 目前的內建範例：
  • Slack 讓 exec 與 Plugin id 都可使用原生核准路由。
  • Matrix 為 exec 與 Plugin 核准保留相同的原生 DM/通道路由與反應 UX， 同時仍允許驗證依核准種類而異。
• createApproverRestrictedNativeApprovalAdapter 仍作為相容性 wrapper 存在，但新程式碼應偏好能力 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 涵蓋 runtime 安全的 setup helper： 匯入安全 setup patch adapter（createPatchedAccountSetupAdapter、 createEnvPatchedAccountSetupAdapter、 createSetupInputPresenceValidator）、查找備註輸出、 promptResolvedAllowFrom、splitSetupEntries，以及委派的 setup-proxy builder
• openclaw/plugin-sdk/setup-runtime 包含用於 createEnvPatchedAccountSetupAdapter 的環境感知 adapter 接縫
• openclaw/plugin-sdk/channel-setup 涵蓋選用安裝 setup builder 與幾個 setup 安全 primitive： createOptionalChannelSetupSurface、createOptionalChannelSetupAdapter、

• 只有在你也需要較重的共用 setup/設定 helper，例如 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，用於傳入路由/envelope 與 記錄並分派接線
• openclaw/plugin-sdk/messaging-targets，用於目標剖析/比對
• openclaw/plugin-sdk/outbound-media 與 openclaw/plugin-sdk/outbound-runtime，用於媒體載入以及傳出 身分/傳送委派與 payload 規劃
• 當傳出路由應保留明確的 replyToId/threadId，或在基礎 session key 仍相符後恢復目前的 :thread: session 時，使用 openclaw/plugin-sdk/channel-core 中的 buildThreadAwareOutboundSessionRoute(...)。供應商 Plugin 可在其平台具有原生 thread 傳遞語意時，覆寫優先順序、後綴行為與 thread id 正規化。
• openclaw/plugin-sdk/thread-bindings-runtime，用於 thread-binding 生命週期 與 adapter 註冊
• 只有在仍需要舊式 agent/media payload 欄位配置時，才使用 openclaw/plugin-sdk/agent-media-payload
• openclaw/plugin-sdk/telegram-command-config，用於 Telegram 自訂命令 正規化、重複/衝突驗證，以及後援穩定的命令 設定合約

​

傳入提及政策

• Plugin 擁有的證據收集
• 共用政策評估

• 回覆 bot 偵測
• 引用 bot 偵測
• thread 參與檢查
• 服務/系統訊息排除
• 需要用來證明 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 - 完整 Manifest 結構描述

​

相關

• Plugin SDK 設定
• 建置 Plugin
• 代理程式框架 Plugin