​

채널 Plugin 구축

​

채널 plugin의 작동 방식

• 설정 — 계정 해석 및 설정 wizard
• 보안 — DM 정책 및 허용 목록
• 페어링 — DM 승인 흐름
• 세션 문법 — provider별 대화 id가 기본 채팅, 스레드 id, 부모 대체 경로에 어떻게 매핑되는지
• 아웃바운드 — 플랫폼으로 텍스트, 미디어, 투표를 보내기
• 스레딩 — 답장을 어떻게 스레드로 연결할지

​

승인 및 채널 기능

• 코어는 동일 채팅의 /approve, 공유 승인 버튼 페이로드, 일반적인 대체 전달을 담당합니다.
• 채널에 승인 전용 동작이 필요할 때는 채널 plugin에 하나의 approvalCapability 객체를 두는 방식을 선호하세요.
• ChannelPlugin.approvals는 제거되었습니다. 승인 전달/네이티브/렌더링/인증 관련 정보는 approvalCapability에 두세요.
• plugin.auth는 login/logout 전용입니다. 코어는 더 이상 그 객체에서 승인 인증 훅을 읽지 않습니다.
• approvalCapability.authorizeActorAction과 approvalCapability.getActionAvailabilityState가 정식 승인 인증 연결 지점입니다.
• 동일 채팅 승인 인증 가용성에는 approvalCapability.getActionAvailabilityState를 사용하세요.
• 채널이 네이티브 exec 승인을 노출한다면, 동일 채팅 승인 인증과 다를 때 시작 표면/네이티브 클라이언트 상태를 위해 approvalCapability.getExecInitiatingSurfaceState를 사용하세요. 코어는 이 exec 전용 훅으로 enabled와 disabled를 구분하고, 시작 채널이 네이티브 exec 승인을 지원하는지 판단하며, 네이티브 클라이언트 대체 안내에 해당 채널을 포함합니다. 일반적인 경우에는 createApproverRestrictedNativeApprovalCapability(...)가 이를 채워 줍니다.
• 중복된 로컬 승인 프롬프트 숨기기나 전달 전 타이핑 표시 보내기 같은 채널 전용 페이로드 수명 주기 동작에는 outbound.shouldSuppressLocalPayloadPrompt 또는 outbound.beforeDeliverPayload를 사용하세요.
• approvalCapability.delivery는 네이티브 승인 라우팅 또는 대체 억제에만 사용하세요.
• 채널 소유 네이티브 승인 관련 정보에는 approvalCapability.nativeRuntime를 사용하세요. 핫 채널 엔트리포인트에서는 createLazyChannelApprovalNativeRuntimeAdapter(...)로 이를 지연 로드 상태로 유지하세요. 그러면 코어가 승인 수명 주기를 조립할 수 있으면서도 필요 시 런타임 모듈을 가져올 수 있습니다.
• 채널이 공유 렌더러 대신 진짜로 커스텀 승인 페이로드가 필요할 때만 approvalCapability.render를 사용하세요.
• 채널이 비활성 경로 응답에서 네이티브 exec 승인을 활성화하는 데 필요한 정확한 설정 키를 설명하고 싶다면 approvalCapability.describeExecApprovalSetup을 사용하세요. 이 훅은 { 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은 몇 개의 더 작은 연결 지점으로 나뉩니다:
• availability — 계정이 설정되었는지, 요청을 처리해야 하는지 여부
• presentation — 공유 승인 뷰 모델을 보류/해결됨/만료된 네이티브 페이로드 또는 최종 작업으로 매핑
• transport — 대상을 준비하고 네이티브 승인 메시지를 전송/업데이트/삭제
• interactions — 네이티브 버튼 또는 반응을 위한 선택적 bind/unbind/clear-action 훅
• observe — 선택적 전달 진단 훅
• 채널에 클라이언트, 토큰, Bolt 앱, 웹훅 리시버 같은 런타임 소유 객체가 필요하다면 openclaw/plugin-sdk/channel-runtime-context를 통해 등록하세요. 일반적인 runtime-context 레지스트리를 사용하면 승인 전용 래퍼 접착 코드를 추가하지 않고도 코어가 채널 시작 상태에서 기능 기반 핸들러를 부트스트랩할 수 있습니다.
• 기능 기반 연결 지점으로 아직 충분히 표현할 수 없을 때만 더 낮은 수준의 createChannelApprovalHandler 또는 createChannelNativeApprovalRuntime을 사용하세요.
• 네이티브 승인 채널은 accountId와 approvalKind를 모두 해당 헬퍼들을 통해 라우팅해야 합니다. accountId는 다중 계정 승인 정책을 올바른 봇 계정 범위로 유지하고, approvalKind는 코어에 하드코딩된 분기 없이도 채널에서 exec 대 plugin 승인 동작을 사용할 수 있게 합니다.
• 이제 코어가 승인 재라우팅 알림도 담당합니다. 채널 plugin은 createChannelNativeApprovalRuntime에서 자체적인 “승인이 DM/다른 채널로 갔음” 후속 메시지를 보내지 말고, 공유 승인 기능 헬퍼를 통해 정확한 origin + approver-DM 라우팅을 노출한 뒤 코어가 시작 채팅에 알림을 게시하기 전에 실제 전달 결과를 집계하게 하세요.
• 전달된 승인 id 종류를 처음부터 끝까지 보존하세요. 네이티브 클라이언트는 채널 로컬 상태를 기준으로 exec 대 plugin 승인 라우팅을 추측하거나 다시 쓰면 안 됩니다.
• 서로 다른 승인 종류는 의도적으로 서로 다른 네이티브 표면을 노출할 수 있습니다. 현재 번들 예시는 다음과 같습니다:
  • Slack은 exec 및 plugin id 모두에 대해 네이티브 승인 라우팅을 계속 사용할 수 있게 유지합니다.
  • Matrix는 exec와 plugin 승인 모두에 대해 동일한 네이티브 DM/채널 라우팅과 반응 UX를 유지하면서도 승인 종류별로 인증이 다를 수 있게 합니다.
• createApproverRestrictedNativeApprovalAdapter는 여전히 호환성 래퍼로 존재하지만, 새 코드에서는 기능 빌더를 선호하고 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은 런타임 안전 setup 헬퍼를 다룹니다: import-safe setup 패치 adapter(createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), lookup-note 출력, promptResolvedAllowFrom, splitSetupEntries, 그리고 위임된 setup-proxy 빌더
• openclaw/plugin-sdk/setup-adapter-runtime은 createEnvPatchedAccountSetupAdapter를 위한 좁은 env 인식 adapter 연결 지점입니다
• openclaw/plugin-sdk/channel-setup은 선택적 설치 setup 빌더와 몇 가지 setup 안전 기본 요소를 다룹니다: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

• 더 무거운 공유 setup/config 헬퍼인 moveSingleAccountChannelSectionToDefaultAccount(...)도 필요할 때만 더 넓은 openclaw/plugin-sdk/setup 연결 지점을 사용하세요

• 다중 계정 config 및 기본 계정 대체를 위한 openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution, 그리고 openclaw/plugin-sdk/account-helpers
• 인바운드 경로/envelope 및 record-and-dispatch 연결을 위한 openclaw/plugin-sdk/inbound-envelope와 openclaw/plugin-sdk/inbound-reply-dispatch
• 대상 파싱/매칭을 위한 openclaw/plugin-sdk/messaging-targets
• 미디어 로딩 및 아웃바운드 정체성/send 위임을 위한 openclaw/plugin-sdk/outbound-media와 openclaw/plugin-sdk/outbound-runtime
• 스레드 바인딩 수명 주기 및 adapter 등록을 위한 openclaw/plugin-sdk/thread-bindings-runtime
• 레거시 agent/media 페이로드 필드 레이아웃이 여전히 필요할 때만 openclaw/plugin-sdk/agent-media-payload
• Telegram 커스텀 명령 정규화, 중복/충돌 검증, 그리고 대체 안정 명령 config 계약을 위한 openclaw/plugin-sdk/telegram-command-config

​

인바운드 멘션 정책

• plugin 소유 증거 수집
• 공유 정책 평가

• 봇에 대한 reply 감지
• 봇 인용 감지
• 스레드 참여 확인
• 서비스/시스템 메시지 제외
• 봇 참여를 입증하는 데 필요한 플랫폼 네이티브 캐시

• 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      # config schema가 포함된 Manifest
├── index.ts                  # defineChannelPluginEntry
├── setup-entry.ts            # defineSetupPluginEntry
├── api.ts                    # 공개 export(선택 사항)
├── runtime-api.ts            # 내부 런타임 export(선택 사항)
└── src/
    ├── channel.ts            # createChatChannelPlugin을 통한 ChannelPlugin
    ├── channel.test.ts       # 테스트
    ├── client.ts             # 플랫폼 API 클라이언트
    └── runtime.ts            # 런타임 저장소(필요한 경우)

​

고급 주제

​

다음 단계

• Provider Plugin — plugin이 모델도 제공하는 경우
• SDK 개요 — 전체 하위 경로 import 참조
• SDK 테스팅 — 테스트 유틸리티 및 계약 테스트
• Plugin Manifest — 전체 manifest 스키마