메인 콘텐츠로 건너뛰기

Plugin SDK Migration

OpenClaw는 넓은 범위의 하위 호환성 계층에서 집중적이고 문서화된 import를 사용하는 최신 plugin 아키텍처로 이동했습니다. 새 아키텍처 이전에 plugin을 만들었다면 이 가이드를 통해 마이그레이션할 수 있습니다.

무엇이 바뀌고 있나요

이전 plugin 시스템은 plugin이 단일 진입점에서 필요한 모든 것을 import할 수 있도록 하는 두 개의 매우 넓은 표면을 제공했습니다.
  • openclaw/plugin-sdk/compat — 수십 개의 helper를 재export하는 단일 import. 새 plugin 아키텍처가 구축되는 동안 이전 hook 기반 plugins가 계속 동작하게 하기 위해 도입되었습니다.
  • openclaw/extension-api — plugin이 임베디드 agent runner 같은 호스트 측 helper에 직접 접근할 수 있게 해 주는 브리지.
이 두 표면은 이제 모두 deprecated되었습니다. 런타임에서는 여전히 동작하지만, 새 plugins는 이를 사용해서는 안 되며, 기존 plugins는 다음 major release에서 제거되기 전에 마이그레이션해야 합니다.
하위 호환성 계층은 향후 major release에서 제거될 예정입니다. 이 표면에서 여전히 import하는 plugins는 그 시점에 동작이 깨집니다.

왜 이렇게 바뀌었나요

기존 접근 방식은 여러 문제를 일으켰습니다:
  • 느린 시작 속도 — helper 하나를 import하면 관련 없는 수십 개의 모듈이 로드됨
  • 순환 의존성 — 광범위한 재export 때문에 import cycle을 쉽게 만들 수 있었음
  • 불분명한 API 표면 — 어떤 export가 안정적인지, 어떤 것이 내부용인지 구분할 수 없었음
최신 plugin SDK는 이를 해결합니다: 각 import 경로(openclaw/plugin-sdk/\<subpath\>)는 명확한 목적과 문서화된 계약을 가진 작고 독립적인 모듈입니다. 번들 채널용 레거시 provider 편의 seam도 제거되었습니다. openclaw/plugin-sdk/slack, openclaw/plugin-sdk/discord, openclaw/plugin-sdk/signal, openclaw/plugin-sdk/whatsapp, 채널 브랜드 helper seams, openclaw/plugin-sdk/telegram-core 같은 import는 안정적인 plugin 계약이 아니라 private mono-repo 단축 경로였습니다. 대신 좁고 일반적인 SDK subpath를 사용하세요. 번들 plugin workspace 내부에서는 provider가 소유하는 helper를 해당 plugin의 자체 api.ts 또는 runtime-api.ts에 두세요. 현재 번들 provider 예시:
  • Anthropic은 Claude 전용 stream helper를 자체 api.ts / contract-api.ts seam에 유지
  • OpenAI는 provider builder, default-model helper, realtime provider builder를 자체 api.ts에 유지
  • OpenRouter는 provider builder와 onboarding/config helper를 자체 api.ts에 유지

마이그레이션 방법

1

Windows wrapper fallback 동작 감사

plugin이 openclaw/plugin-sdk/windows-spawn을 사용한다면, 확인되지 않은 Windows .cmd/.bat wrapper는 이제 명시적으로 allowShellFallback: true를 전달하지 않는 한 fail closed 처리됩니다.
// 이전
const program = applyWindowsSpawnProgramPolicy({ candidate });

// 이후
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // 셸을 통한 fallback을 의도적으로 허용하는 신뢰된
  // 호환성 호출자에서만 이것을 설정하세요.
  allowShellFallback: true,
});
호출자가 의도적으로 shell fallback에 의존하지 않는다면 allowShellFallback을 설정하지 말고 대신 발생한 오류를 처리하세요.
2

deprecated import 찾기

plugin에서 deprecated된 두 표면 중 하나를 import하는 부분을 검색하세요:
grep -r "plugin-sdk/compat" my-plugin/
grep -r "openclaw/extension-api" my-plugin/
3

집중된 import로 교체

이전 표면의 각 export는 특정 최신 import 경로에 매핑됩니다:
// 이전 (deprecated 하위 호환성 계층)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";

// 이후 (최신 집중 import)
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
호스트 측 helper의 경우 직접 import하지 말고 주입된 plugin runtime을 사용하세요:
// 이전 (deprecated extension-api bridge)
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });

// 이후 (주입된 runtime)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
같은 패턴이 다른 레거시 bridge helper에도 적용됩니다:
이전 import최신 대응
resolveAgentDirapi.runtime.agent.resolveAgentDir
resolveAgentWorkspaceDirapi.runtime.agent.resolveAgentWorkspaceDir
resolveAgentIdentityapi.runtime.agent.resolveAgentIdentity
resolveThinkingDefaultapi.runtime.agent.resolveThinkingDefault
resolveAgentTimeoutMsapi.runtime.agent.resolveAgentTimeoutMs
ensureAgentWorkspaceapi.runtime.agent.ensureAgentWorkspace
session store helpersapi.runtime.agent.session.*
4

빌드 및 테스트

pnpm build
pnpm test -- my-plugin/

Import 경로 참조

Import 경로목적주요 exports
plugin-sdk/plugin-entry표준 plugin entry helperdefinePluginEntry
plugin-sdk/core채널 entry 정의/빌더를 위한 레거시 umbrella 재exportdefineChannelPluginEntry, createChatChannelPlugin
plugin-sdk/config-schema루트 config schema exportOpenClawSchema
plugin-sdk/provider-entry단일 provider entry helperdefineSingleProviderPluginEntry
plugin-sdk/channel-core집중된 채널 entry 정의 및 빌더defineChannelPluginEntry, defineSetupPluginEntry, createChatChannelPlugin, createChannelPluginBase
plugin-sdk/setup공유 setup wizard helperAllowlist prompts, setup status builders
plugin-sdk/setup-runtimesetup 시점 runtime helperImport-safe setup patch adapters, lookup-note helpers, promptResolvedAllowFrom, splitSetupEntries, delegated setup proxies
plugin-sdk/setup-adapter-runtimesetup adapter helpercreateEnvPatchedAccountSetupAdapter
plugin-sdk/setup-toolssetup 도구 helperformatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR
plugin-sdk/account-core다중 account helperAccount list/config/action-gate helpers
plugin-sdk/account-idaccount-id helperDEFAULT_ACCOUNT_ID, account-id normalization
plugin-sdk/account-resolutionaccount lookup helperAccount lookup + default-fallback helpers
plugin-sdk/account-helpers좁은 범위 account helperAccount list/account-action helpers
plugin-sdk/channel-setupsetup wizard adaptercreateOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, plus DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled, splitSetupEntries
plugin-sdk/channel-pairingDM pairing 기본 요소createChannelPairingController
plugin-sdk/channel-reply-pipeline응답 접두사 + typing 연결createChannelReplyPipeline
plugin-sdk/channel-config-helpersConfig adapter factorycreateHybridChannelConfigAdapter
plugin-sdk/channel-config-schemaConfig schema builderChannel config schema types
plugin-sdk/telegram-command-configTelegram 명령 config helperCommand-name normalization, description trimming, duplicate/conflict validation
plugin-sdk/channel-policy그룹/DM 정책 확인resolveChannelGroupRequireMention
plugin-sdk/channel-lifecycleaccount 상태 추적createAccountStatusSink
plugin-sdk/inbound-envelope수신 envelope helperShared route + envelope builder helpers
plugin-sdk/inbound-reply-dispatch수신 응답 helperShared record-and-dispatch helpers
plugin-sdk/messaging-targets메시징 대상 파싱Target parsing/matching helpers
plugin-sdk/outbound-media발신 미디어 helperShared outbound media loading
plugin-sdk/outbound-runtime발신 runtime helperOutbound identity/send delegate helpers
plugin-sdk/thread-bindings-runtimethread-binding helperThread-binding lifecycle and adapter helpers
plugin-sdk/agent-media-payload레거시 미디어 payload helperLegacy field layout용 agent media payload builder
plugin-sdk/channel-runtimedeprecated 호환성 shim레거시 channel runtime utilities 전용
plugin-sdk/channel-send-resultsend 결과 타입Reply result types
plugin-sdk/runtime-store영구 plugin 저장소createPluginRuntimeStore
plugin-sdk/runtime광범위한 runtime helperRuntime/logging/backup/plugin-install helpers
plugin-sdk/runtime-env좁은 범위 runtime env helperLogger/runtime env, timeout, retry, and backoff helpers
plugin-sdk/plugin-runtime공유 plugin runtime helperPlugin commands/hooks/http/interactive helpers
plugin-sdk/hook-runtimehook pipeline helperShared webhook/internal hook pipeline helpers
plugin-sdk/lazy-runtimelazy runtime helpercreateLazyRuntimeModule, createLazyRuntimeMethod, createLazyRuntimeMethodBinder, createLazyRuntimeNamedExport, createLazyRuntimeSurface
plugin-sdk/process-runtime프로세스 helperShared exec helpers
plugin-sdk/cli-runtimeCLI runtime helperCommand formatting, waits, version helpers
plugin-sdk/gateway-runtimeGateway helperGateway client and channel-status patch helpers
plugin-sdk/config-runtimeConfig helperConfig load/write helpers
plugin-sdk/telegram-command-configTelegram 명령 helper번들 Telegram 계약 표면을 사용할 수 없을 때의 fallback-stable Telegram command validation helpers
plugin-sdk/approval-runtime승인 프롬프트 helperExec/plugin approval payload, approval capability/profile helpers, native approval routing/runtime helpers
plugin-sdk/approval-auth-runtime승인 인증 helperApprover resolution, same-chat action auth
plugin-sdk/approval-client-runtime승인 클라이언트 helperNative exec approval profile/filter helpers
plugin-sdk/approval-delivery-runtime승인 전달 helperNative approval capability/delivery adapters
plugin-sdk/approval-native-runtime승인 대상 helperNative approval target/account binding helpers
plugin-sdk/approval-reply-runtime승인 응답 helperExec/plugin approval reply payload helpers
plugin-sdk/security-runtime보안 helperShared trust, DM gating, external-content, and secret-collection helpers
plugin-sdk/ssrf-policySSRF 정책 helperHost allowlist and private-network policy helpers
plugin-sdk/ssrf-runtimeSSRF runtime helperPinned-dispatcher, guarded fetch, SSRF policy helpers
plugin-sdk/collection-runtime제한된 캐시 helperpruneMapToMaxSize
plugin-sdk/diagnostic-runtime진단 게이팅 helperisDiagnosticFlagEnabled, isDiagnosticsEnabled
plugin-sdk/error-runtime오류 형식화 helperformatUncaughtError, isApprovalNotFoundError, error graph helpers
plugin-sdk/fetch-runtime래핑된 fetch/proxy helperresolveFetch, proxy helpers
plugin-sdk/host-runtime호스트 normalization helpernormalizeHostname, normalizeScpRemoteHost
plugin-sdk/retry-runtimeretry helperRetryConfig, retryAsync, policy runners
plugin-sdk/allow-fromAllowlist 형식화formatAllowFromLowercase
plugin-sdk/allowlist-resolutionAllowlist 입력 매핑mapAllowlistResolutionInputs
plugin-sdk/command-auth명령 게이팅 및 command-surface helperresolveControlCommandGate, sender-authorization helpers, command registry helpers
plugin-sdk/secret-inputsecret 입력 파싱Secret input helpers
plugin-sdk/webhook-ingresswebhook 요청 helperWebhook target utilities
plugin-sdk/webhook-request-guardswebhook 본문 가드 helperRequest body read/limit helpers
plugin-sdk/reply-runtime공유 reply runtimeInbound dispatch, heartbeat, reply planner, chunking
plugin-sdk/reply-dispatch-runtime좁은 범위 reply dispatch helperFinalize + provider dispatch helpers
plugin-sdk/reply-historyreply-history helperbuildHistoryContext, buildPendingHistoryContextFromMap, recordPendingHistoryEntry, clearHistoryEntriesIfEnabled
plugin-sdk/reply-referencereply reference 계획createReplyReferencePlanner
plugin-sdk/reply-chunkingreply chunk helperText/markdown chunking helpers
plugin-sdk/session-store-runtimesession store helperStore path + updated-at helpers
plugin-sdk/state-paths상태 경로 helperState and OAuth dir helpers
plugin-sdk/routing라우팅/session-key helperresolveAgentRoute, buildAgentSessionKey, resolveDefaultAgentBoundAccountId, session-key normalization helpers
plugin-sdk/status-helpers채널 상태 helperChannel/account status summary builders, runtime-state defaults, issue metadata helpers
plugin-sdk/target-resolver-runtimetarget resolver helperShared target resolver helpers
plugin-sdk/string-normalization-runtime문자열 normalization helperSlug/string normalization helpers
plugin-sdk/request-url요청 URL helperrequest-like 입력에서 문자열 URL 추출
plugin-sdk/run-command시간 제한 명령 helperTimed command runner with normalized stdout/stderr
plugin-sdk/param-readers매개변수 readerCommon tool/CLI param readers
plugin-sdk/tool-send도구 send 추출도구 args에서 표준 send target field 추출
plugin-sdk/temp-path임시 경로 helperShared temp-download path helpers
plugin-sdk/logging-core로깅 helperSubsystem logger and redaction helpers
plugin-sdk/markdown-table-runtimemarkdown-table helperMarkdown table mode helpers
plugin-sdk/reply-payload메시지 reply 타입Reply payload types
plugin-sdk/provider-setup선별된 로컬/self-hosted provider setup helperSelf-hosted provider discovery/config helpers
plugin-sdk/self-hosted-provider-setup집중된 OpenAI-compatible self-hosted provider setup helperSame self-hosted provider discovery/config helpers
plugin-sdk/provider-auth-runtimeprovider runtime auth helperRuntime API-key resolution helpers
plugin-sdk/provider-auth-api-keyprovider API-key setup helperAPI-key onboarding/profile-write helpers
plugin-sdk/provider-auth-resultprovider auth-result helperStandard OAuth auth-result builder
plugin-sdk/provider-auth-loginprovider 대화형 login helperShared interactive login helpers
plugin-sdk/provider-env-varsprovider env-var helperProvider auth env-var lookup helpers
plugin-sdk/provider-model-shared공유 provider model/replay helperProviderReplayFamily, buildProviderReplayFamilyHooks, normalizeModelCompat, shared replay-policy builders, provider-endpoint helpers, and model-id normalization helpers
plugin-sdk/provider-catalog-shared공유 provider catalog helperfindCatalogTemplate, buildSingleProviderApiKeyCatalog, supportsNativeStreamingUsageCompat, applyProviderNativeStreamingUsageCompat
plugin-sdk/provider-onboardprovider onboarding patchOnboarding config helpers
plugin-sdk/provider-httpprovider HTTP helperGeneric provider HTTP/endpoint capability helpers
plugin-sdk/provider-web-fetchprovider web-fetch helperWeb-fetch provider registration/cache helpers
plugin-sdk/provider-web-searchprovider web-search helperWeb-search provider registration/cache/config helpers
plugin-sdk/provider-toolsprovider tool/schema compat helperProviderToolCompatFamily, buildProviderToolCompatFamilyHooks, Gemini schema cleanup + diagnostics, and xAI compat helpers such as resolveXaiModelCompatPatch / applyXaiModelCompat
plugin-sdk/provider-usageprovider 사용량 helperfetchClaudeUsage, fetchGeminiUsage, fetchGithubCopilotUsage, and other provider usage helpers
plugin-sdk/provider-streamprovider stream wrapper helperProviderStreamFamily, buildProviderStreamFamilyHooks, composeProviderStreamWrappers, stream wrapper types, and shared Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot wrapper helpers
plugin-sdk/keyed-async-queue순서가 보장된 async 큐KeyedAsyncQueue
plugin-sdk/media-runtime공유 미디어 helperMedia fetch/transform/store helpers plus media payload builders
plugin-sdk/media-understandingmedia-understanding helperMedia understanding provider types plus provider-facing image/audio helper exports
plugin-sdk/text-runtime공유 텍스트 helperAssistant-visible-text stripping, markdown render/chunking/table helpers, redaction helpers, directive-tag helpers, safe-text utilities, and related text/logging helpers
plugin-sdk/text-chunking텍스트 chunking helperOutbound text chunking helper
plugin-sdk/speech음성 helperSpeech provider types plus provider-facing directive, registry, and validation helpers
plugin-sdk/speech-core공유 speech coreSpeech provider types, registry, directives, normalization
plugin-sdk/realtime-transcriptionrealtime transcription helperProvider types and registry helpers
plugin-sdk/realtime-voicerealtime voice helperProvider types and registry helpers
plugin-sdk/image-generation-core공유 이미지 생성 coreImage-generation types, failover, auth, and registry helpers
plugin-sdk/video-generation비디오 생성 helperVideo-generation provider/request/result types
plugin-sdk/video-generation-core공유 비디오 생성 coreVideo-generation types, failover helpers, provider lookup, and model-ref parsing
plugin-sdk/interactive-runtime인터랙티브 reply helperInteractive reply payload normalization/reduction
plugin-sdk/channel-config-primitiveschannel config 기본 요소Narrow channel config-schema primitives
plugin-sdk/channel-config-writeschannel config-write helperChannel config-write authorization helpers
plugin-sdk/channel-plugin-common공유 channel preludeShared channel plugin prelude exports
plugin-sdk/channel-statuschannel 상태 helperShared channel status snapshot/summary helpers
plugin-sdk/allowlist-config-editallowlist config helperAllowlist config edit/read helpers
plugin-sdk/group-access그룹 접근 helperShared group-access decision helpers
plugin-sdk/direct-dmdirect-DM helperShared direct-DM auth/guard helpers
plugin-sdk/extension-shared공유 extension helperPassive-channel/status helper primitives
plugin-sdk/webhook-targetswebhook target helperWebhook target registry and route-install helpers
plugin-sdk/webhook-pathwebhook 경로 helperWebhook path normalization helpers
plugin-sdk/web-media공유 웹 미디어 helperRemote/local media loading helpers
plugin-sdk/zodZod 재exportplugin SDK 소비자를 위한 재export된 zod
plugin-sdk/memory-core번들 memory-core helperMemory manager/config/file/CLI helper surface
plugin-sdk/memory-core-engine-runtimememory engine runtime facadeMemory index/search runtime facade
plugin-sdk/memory-core-host-engine-foundationmemory host foundation engineMemory host foundation engine exports
plugin-sdk/memory-core-host-engine-embeddingsmemory host embedding engineMemory host embedding engine exports
plugin-sdk/memory-core-host-engine-qmdmemory host QMD engineMemory host QMD engine exports
plugin-sdk/memory-core-host-engine-storagememory host storage engineMemory host storage engine exports
plugin-sdk/memory-core-host-multimodalmemory host multimodal helperMemory host multimodal helpers
plugin-sdk/memory-core-host-querymemory host query helperMemory host query helpers
plugin-sdk/memory-core-host-secretmemory host secret helperMemory host secret helpers
plugin-sdk/memory-core-host-statusmemory host status helperMemory host status helpers
plugin-sdk/memory-core-host-runtime-climemory host CLI runtimeMemory host CLI runtime helpers
plugin-sdk/memory-core-host-runtime-corememory host core runtimeMemory host core runtime helpers
plugin-sdk/memory-core-host-runtime-filesmemory host file/runtime helperMemory host file/runtime helpers
plugin-sdk/memory-lancedb번들 memory-lancedb helperMemory-lancedb helper surface
plugin-sdk/testing테스트 유틸리티Test helpers and mocks
이 표는 전체 SDK 표면이 아니라 의도적으로 일반적인 마이그레이션 하위 집합만 담고 있습니다. 200개가 넘는 전체 entrypoint 목록은 scripts/lib/plugin-sdk-entrypoints.json에 있습니다. 그 목록에는 여전히 plugin-sdk/feishu, plugin-sdk/feishu-setup, plugin-sdk/zalo, plugin-sdk/zalo-setup, plugin-sdk/matrix* 같은 일부 번들 plugin helper seam도 포함됩니다. 이들은 번들 plugin 유지보수와 호환성을 위해 계속 export되지만, 의도적으로 일반 마이그레이션 표에서는 제외되어 있으며 새 plugin 코드의 권장 대상은 아닙니다. 같은 규칙은 다른 번들 helper 계열에도 적용됩니다:
  • browser 지원 helper: plugin-sdk/browser-config-support, plugin-sdk/browser-support
  • Matrix: plugin-sdk/matrix*
  • LINE: plugin-sdk/line*
  • IRC: plugin-sdk/irc*
  • 번들 helper/plugin 표면: plugin-sdk/googlechat, plugin-sdk/zalouser, plugin-sdk/bluebubbles*, plugin-sdk/mattermost*, plugin-sdk/msteams, plugin-sdk/nextcloud-talk, plugin-sdk/nostr, plugin-sdk/tlon, plugin-sdk/twitch, plugin-sdk/github-copilot-login, plugin-sdk/github-copilot-token, plugin-sdk/diagnostics-otel, plugin-sdk/diffs, plugin-sdk/llm-task, plugin-sdk/thread-ownership, plugin-sdk/voice-call
plugin-sdk/github-copilot-token은 현재 좁은 범위의 token-helper 표면인 DEFAULT_COPILOT_API_BASE_URL, deriveCopilotApiBaseUrlFromToken, resolveCopilotApiToken을 노출합니다. 작업에 맞는 가장 좁은 import를 사용하세요. export를 찾을 수 없다면 src/plugin-sdk/의 소스를 확인하거나 Discord에서 물어보세요.

제거 일정

시점발생하는 일
지금deprecated 표면이 런타임 경고를 출력함
다음 major releasedeprecated 표면이 제거되며, 여전히 사용 중인 plugins는 실패함
모든 core plugins는 이미 마이그레이션되었습니다. 외부 plugins는 다음 major release 전에 마이그레이션해야 합니다.

경고를 일시적으로 숨기기

마이그레이션 작업 중에는 다음 환경 변수를 설정하세요:
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
이것은 영구적인 해결책이 아니라 임시 탈출구입니다.

관련 문서