建置通道 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.

​

channel Plugin 的運作方式

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

​

核准與頻道能力

• 核心負責同一聊天中的 /approve、共用核准按鈕 payload，以及通用後援傳遞。
• 當頻道需要核准特定行為時，請優先在 channel Plugin 上使用一個 approvalCapability 物件。
• ChannelPlugin.approvals 已移除。請將核准傳遞/native/render/auth 事實放在 approvalCapability 上。
• plugin.auth 只用於登入/登出；核心不再從該物件讀取核准 auth hook。
• approvalCapability.authorizeActorAction 與 approvalCapability.getActionAvailabilityState 是標準核准 auth 介面。
• 使用 approvalCapability.getActionAvailabilityState 取得同一聊天核准 auth 可用性。
• 如果你的頻道公開 native exec 核准，當啟動介面/native-client 狀態與同一聊天核准 auth 不同時，請使用 approvalCapability.getExecInitiatingSurfaceState。核心會使用該 exec 專用 hook 來區分 enabled 與 disabled、判斷啟動頻道是否支援 native exec 核准，並在 native-client 後援指引中包含該頻道。createApproverRestrictedNativeApprovalCapability(...) 會為常見情境填入此項。
• 使用 outbound.shouldSuppressLocalPayloadPrompt 或 outbound.beforeDeliverPayload 處理頻道特定 payload 生命週期行為，例如隱藏重複的本機核准提示，或在傳遞前傳送輸入指示器。
• 只有在 native 核准路由或後援抑制時，才使用 approvalCapability.delivery。
• 使用 approvalCapability.nativeRuntime 放置頻道擁有的 native 核准事實。請透過 createLazyChannelApprovalNativeRuntimeAdapter(...) 讓它在熱 channel entrypoint 上保持延遲載入；這能在需要時匯入你的 runtime 模組，同時仍讓核心組裝核准生命週期。
• 只有當頻道確實需要自訂核准 payload、而不是使用共用 renderer 時，才使用 approvalCapability.render。
• 當頻道希望停用路徑回覆說明啟用 native exec 核准所需的確切設定旋鈕時，請使用 approvalCapability.describeExecApprovalSetup。此 hook 會收到 { channel, channelLabel, accountId }；具名帳號頻道應呈現帳號範圍路徑，例如 channels.<channel>.accounts.<id>.execApprovals.*，而不是頂層預設值。
• 如果頻道可以從既有設定推論穩定的類擁有者 DM 身分，請使用 openclaw/plugin-sdk/approval-runtime 中的 createResolvedApproverActionAuthAdapter 來限制同一聊天中的 /approve，而不加入核准特定核心邏輯。
• 如果頻道需要 native 核准傳遞，請讓頻道程式碼專注在目標正規化與傳輸/呈現事實。請使用 openclaw/plugin-sdk/approval-runtime 中的 createChannelExecApprovalProfile、createChannelNativeOriginTargetResolver、createChannelApproverDmTargetResolver 與 createApproverRestrictedNativeApprovalCapability。將頻道特定事實放在 approvalCapability.nativeRuntime 後方，理想情況是透過 createChannelApprovalNativeRuntimeAdapter(...) 或 createLazyChannelApprovalNativeRuntimeAdapter(...)，讓核心可以組裝 handler 並負責請求過濾、路由、去重、過期、Gateway 訂閱，以及已路由到其他位置的通知。nativeRuntime 被拆成幾個較小的介面：
• createChannelNativeOriginTargetResolver 預設會對 { to, accountId, threadId } 目標使用共用 channel-route matcher。只有當頻道具備供應商特定等價規則時，才傳入 targetsMatch，例如 Slack 時間戳前綴比對。
• 當頻道需要在預設 route matcher 或自訂 targetsMatch callback 執行前，先將供應商 ID 標準化，同時保留原始目標用於傳遞時，請將 normalizeTargetForMatch 傳給 createChannelNativeOriginTargetResolver。只有當已解析傳遞目標本身應被標準化時，才使用 normalizeTarget。
• availability — 帳號是否已設定，以及請求是否應被處理
• presentation — 將共用核准 view model 對應到 pending/resolved/expired native payload 或最終動作
• transport — 準備目標並傳送/更新/刪除 native 核准訊息
• interactions — native 按鈕或反應的選用 bind/unbind/clear-action hook
• observe — 選用傳遞診斷 hook
• 如果頻道需要 runtime 擁有的物件，例如 client、token、Bolt app 或 webhook receiver，請透過 openclaw/plugin-sdk/channel-runtime-context 註冊它們。通用 runtime-context registry 讓核心能從頻道啟動狀態啟動由能力驅動的 handler，而不需要加入核准特定 wrapper glue。
• 只有當能力驅動介面尚不足以表達需求時，才使用較低階的 createChannelApprovalHandler 或 createChannelNativeApprovalRuntime。
• Native 核准頻道必須透過那些 helper 路由 accountId 與 approvalKind。accountId 會讓多帳號核准政策限定在正確的 bot 帳號範圍內，而 approvalKind 會讓 exec 與 Plugin 核准行為可供頻道使用，而不需在核心中硬編碼分支。
• 核心現在也負責核准重新路由通知。channel Plugin 不應從 createChannelNativeApprovalRuntime 傳送自己的「核准已送到 DM / 另一個頻道」後續訊息；請改為透過共用核准能力 helper 公開準確的 origin 與 approver-DM 路由，並讓核心彙整實際傳遞後，再將任何通知張貼回啟動聊天。
• 端到端保留已傳遞核准 ID 的種類。Native client 不應 從頻道本機狀態猜測或重寫 exec 與 Plugin 核准路由。
• 不同核准種類可以刻意公開不同的 native 介面。 目前的內建範例：
  • Slack 讓 native 核准路由同時可用於 exec 與 Plugin ID。
  • Matrix 讓 exec 與 Plugin 核准保留相同的 native DM/頻道路由與反應 UX， 同時仍允許 auth 依核准種類而異。
• 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 安全的設定 helper： 匯入安全的設定 patch adapter（createPatchedAccountSetupAdapter、 createEnvPatchedAccountSetupAdapter、 createSetupInputPresenceValidator）、lookup-note 輸出、 promptResolvedAllowFrom、splitSetupEntries，以及委派的 setup-proxy builder
• openclaw/plugin-sdk/setup-adapter-runtime 是用於 createEnvPatchedAccountSetupAdapter 的狹窄 env-aware adapter 介面
• openclaw/plugin-sdk/channel-setup 涵蓋 optional-install 設定 builder 與一些設定安全 primitives： createOptionalChannelSetupSurface、createOptionalChannelSetupAdapter、

• 只有在你也需要較重的共用 setup/config helper，例如 moveSingleAccountChannelSectionToDefaultAccount(...) 時，才使用較廣的 openclaw/plugin-sdk/setup seam

• openclaw/plugin-sdk/account-core、 openclaw/plugin-sdk/account-id、 openclaw/plugin-sdk/account-resolution 和 openclaw/plugin-sdk/account-helpers，用於 multi-account config 和 default-account fallback
• openclaw/plugin-sdk/inbound-envelope 和 openclaw/plugin-sdk/inbound-reply-dispatch，用於 inbound route/envelope 和 record-and-dispatch wiring
• openclaw/plugin-sdk/messaging-targets，用於 target parsing/matching
• openclaw/plugin-sdk/outbound-media 和 openclaw/plugin-sdk/outbound-runtime，用於 media loading，以及 outbound identity/send delegate 和 payload planning
• 當 outbound route 應保留明確的 replyToId/threadId，或在 base session key 仍然相符後復原目前的 :thread: session 時，使用 openclaw/plugin-sdk/channel-core 中的 buildThreadAwareOutboundSessionRoute(...)。Provider plugins 可以在其平台具有原生 thread delivery 語意時，覆寫 precedence、suffix behavior 和 thread id normalization。
• openclaw/plugin-sdk/thread-bindings-runtime，用於 thread-binding lifecycle 和 adapter registration
• 只有在仍需要 legacy agent/media payload 欄位配置時，才使用 openclaw/plugin-sdk/agent-media-payload
• openclaw/plugin-sdk/telegram-command-config，用於 Telegram custom-command normalization、duplicate/conflict validation，以及 fallback-stable command config contract

​

Inbound 提及政策

• Plugin 擁有的 evidence gathering
• 共用的 policy evaluation

• reply-to-bot 偵測
• quoted-bot 偵測
• thread-participation 檢查
• service/system-message 排除
• 需要證明 bot participation 的 platform-native cache

• requireMention
• explicit mention result
• implicit mention allowlist
• command bypass
• final skip decision

1. 計算 local mention facts。
2. 將這些 facts 傳入 resolveInboundMentionDecision({ facts, policy })。
3. 在你的 inbound gate 中使用 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 Plugin — 如果你的 Plugin 也提供模型
• SDK 概覽 — 完整子路徑匯入參考
• SDK 測試 — 測試工具與合約測試
• Plugin Manifest — 完整 manifest schema

​

相關

• Plugin SDK 設定
• 建置 Plugin
• Agent harness Plugin