Plugin SDK 마이그레이션

OpenClaw는 광범위한 하위 호환성 계층에서, 초점이 명확하고 문서화된 import를 사용하는 현대적인 Plugin 아키텍처로 이동했습니다. Plugin이 새 아키텍처 이전에 만들어졌다면 이 가이드가 마이그레이션에 도움을 줍니다.

변경되는 사항

이전 Plugin 시스템은 Plugin이 단일 진입점에서 필요한 모든 것을 가져올 수 있게 하는 두 개의 매우 개방적인 표면을 제공했습니다.

• openclaw/plugin-sdk/compat - 수십 개의 헬퍼를 다시 내보내는 단일 import입니다. 새 Plugin 아키텍처가 구축되는 동안 이전 훅 기반 Plugin이 계속 동작하도록 도입되었습니다.
• openclaw/plugin-sdk/infra-runtime - 시스템 이벤트, Heartbeat 상태, 전달 큐, fetch/proxy 헬퍼, 파일 헬퍼, 승인 타입, 관련 없는 유틸리티를 섞어 둔 광범위한 런타임 헬퍼 배럴입니다.
• openclaw/plugin-sdk/config-runtime - 마이그레이션 기간 동안 더 이상 권장되지 않는 직접 load/write 헬퍼를 계속 포함하는 광범위한 구성 호환성 배럴입니다.
• openclaw/extension-api - 내장 에이전트 러너 같은 호스트 측 헬퍼에 Plugin이 직접 접근할 수 있게 한 브리지입니다.
• api.registerEmbeddedExtensionFactory(...) - tool_result 같은 embedded-runner 이벤트를 관찰할 수 있었던, 제거된 embedded-runner 전용 번들 확장 훅입니다.

광범위한 import 표면은 이제 지원 중단되었습니다. 런타임에서는 여전히 동작하지만, 새 Plugin은 이를 사용하면 안 되며, 기존 Plugin은 다음 메이저 릴리스에서 제거되기 전에 마이그레이션해야 합니다. embedded-runner 전용 확장 팩터리 등록 API는 제거되었습니다. 대신 도구 결과 미들웨어를 사용하세요.

OpenClaw는 대체 기능을 도입하는 동일한 변경에서 문서화된 Plugin 동작을 제거하거나 다르게 해석하지 않습니다. 계약을 깨는 변경은 먼저 호환성 어댑터, 진단, 문서, 지원 중단 기간을 거쳐야 합니다. 이는 SDK import, 매니페스트 필드, 설정 API, 훅, 런타임 등록 동작에 적용됩니다.

변경 이유

이전 접근 방식은 문제를 일으켰습니다.

• 느린 시작 - 하나의 헬퍼를 import하면 관련 없는 수십 개의 모듈이 로드되었습니다.
• 순환 의존성 - 광범위한 재내보내기가 import 사이클을 만들기 쉽게 했습니다.
• 불명확한 API 표면 - 어떤 export가 안정적인지 내부용인지 구분할 방법이 없었습니다.

현대적인 Plugin SDK는 이를 해결합니다. 각 import 경로(openclaw/plugin-sdk/\<subpath\>)는 명확한 목적과 문서화된 계약을 가진 작고 독립적인 모듈입니다.

번들 채널을 위한 레거시 제공자 편의 경계도 제거되었습니다. 채널 브랜드가 붙은 헬퍼 경계는 비공개 모노레포 단축 경로였으며 안정적인 Plugin 계약이 아니었습니다. 대신 좁고 일반적인 SDK 하위 경로를 사용하세요. 번들 Plugin 워크스페이스 내부에서는 제공자 소유 헬퍼를 해당 Plugin의 자체 api.ts 또는 runtime-api.ts에 유지하세요.

현재 번들 제공자 예시:

• Anthropic은 Claude 전용 스트림 헬퍼를 자체 api.ts / contract-api.ts 경계에 유지합니다.
• OpenAI는 제공자 빌더, 기본 모델 헬퍼, realtime 제공자 빌더를 자체 api.ts에 유지합니다.
• OpenRouter는 제공자 빌더와 온보딩/구성 헬퍼를 자체 api.ts에 유지합니다.

Talk 및 realtime 음성 마이그레이션 계획

Realtime 음성, 전화, 회의, 브라우저 Talk 코드는 표면별 턴 기록 관리에서 openclaw/plugin-sdk/realtime-voice가 export하는 공유 Talk 세션 컨트롤러로 이동하고 있습니다. 새 컨트롤러는 공통 Talk 이벤트 엔벌로프, 활성 턴 상태, 캡처 상태, 출력 오디오 상태, 최근 이벤트 기록, 오래된 턴 거부를 소유합니다. 제공자 Plugin은 벤더별 realtime 세션을 계속 소유해야 하며, 표면 Plugin은 캡처, 재생, 전화, 회의 특수성을 계속 소유해야 합니다.

이 Talk 마이그레이션은 의도적으로 깔끔한 breaking 변경입니다.

1. 공유 컨트롤러/런타임 프리미티브를 plugin-sdk/realtime-voice에 유지합니다.
2. 번들 표면을 공유 컨트롤러로 이동합니다: 브라우저 릴레이, managed-room handoff, 음성 통화 realtime, 음성 통화 스트리밍 STT, Google Meet realtime, 네이티브 push-to-talk.
3. 이전 Talk RPC 패밀리를 최종 talk.session.* 및 talk.client.* API로 교체합니다.
4. Gateway hello-ok.features.events에 하나의 라이브 Talk 이벤트 채널을 광고합니다: talk.event.
5. 이전 realtime HTTP 엔드포인트와 요청 시점 명령 override 경로를 삭제합니다.

저수준 어댑터나 테스트 픽스처를 구현하는 경우가 아니라면 새 코드는 createTalkEventSequencer(...)를 직접 호출하면 안 됩니다. 턴 범위 이벤트가 턴 id 없이 방출될 수 없고, 오래된 turnEnd / turnCancel 호출이 더 새로운 활성 턴을 지울 수 없으며, 출력 오디오 수명 주기 이벤트가 전화, 회의, 브라우저 릴레이, managed-room handoff, 네이티브 Talk 클라이언트 전반에서 일관되게 유지되도록 공유 컨트롤러를 선호하세요.

목표 공개 API 형태는 다음과 같습니다.

// Gateway-owned Talk session API.await gateway.request("talk.session.create", {  mode: "realtime",  transport: "gateway-relay",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.session.appendAudio", { sessionId, audioBase64 });await gateway.request("talk.session.cancelOutput", { sessionId, reason: "barge-in" });await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "working" },  options: { willContinue: true },});await gateway.request("talk.session.submitToolResult", {  sessionId,  callId,  result: { status: "already_delivered" },  options: { suppressResponse: true },});await gateway.request("talk.session.submitToolResult", { sessionId, callId, result });await gateway.request("talk.session.close", { sessionId }); // Client-owned provider session API.await gateway.request("talk.client.create", {  mode: "realtime",  transport: "webrtc",  brain: "agent-consult",  sessionKey: "main",});await gateway.request("talk.client.toolCall", { sessionKey, callId, name, args });await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

브라우저 소유 WebRTC/제공자 websocket 세션은 talk.client.create를 사용합니다. 브라우저가 제공자 협상과 미디어 전송을 소유하고, Gateway가 자격 증명, 명령, 도구 정책을 소유하기 때문입니다. talk.session.*는 gateway-relay realtime, gateway-relay transcription, managed-room 네이티브 STT/TTS 세션을 위한 공통 Gateway 관리 표면입니다.

talk.provider / talk.providers 옆에 realtime 선택자를 배치한 레거시 구성은 openclaw doctor --fix로 복구해야 합니다. 런타임 Talk는 speech/TTS 제공자 구성을 realtime 제공자 구성으로 다시 해석하지 않습니다.

지원되는 talk.session.create 조합은 의도적으로 작습니다.

제거된 메서드 매핑:

통합 제어 어휘도 의도적으로 좁습니다.

이를 작동시키기 위해 코어에 제공자 또는 플랫폼 특수 사례를 도입하지 마세요. 코어는 Talk 세션 의미 체계를 소유합니다. 제공자 Plugin은 벤더 세션 설정을 소유합니다. 음성 통화와 Google Meet는 전화/회의 어댑터를 소유합니다. 브라우저와 네이티브 앱은 기기 캡처/재생 UX를 소유합니다.

호환성 정책

외부 Plugin의 경우 호환성 작업은 다음 순서를 따릅니다.

1. 새 계약 추가
2. 호환성 어댑터를 통해 이전 동작 유지
3. 이전 경로와 대체 경로를 명명하는 진단 또는 경고 출력
4. 테스트에서 두 경로 모두 커버
5. 지원 중단 및 마이그레이션 경로 문서화
6. 공지된 마이그레이션 기간 이후에만 제거, 일반적으로 메이저 릴리스에서 제거

유지관리자는 현재 마이그레이션 대기열을 pnpm plugins:boundary-report로 감사할 수 있습니다. 간결한 수치에는 pnpm plugins:boundary-report:summary를 사용하고, 하나의 Plugin 또는 호환성 소유자에는 --owner <id>를 사용하며, 만료된 호환성 레코드, 소유자 간 예약 SDK 가져오기, 또는 사용되지 않는 예약 SDK 하위 경로에서 CI 게이트가 실패해야 할 때는 pnpm plugins:boundary-report:ci를 사용하세요. 이 보고서는 지원 중단된 호환성 레코드를 제거 날짜별로 그룹화하고, 로컬 코드/문서 참조 수를 세며, 소유자 간 예약 SDK 가져오기를 표시하고, 비공개 memory-host SDK 브리지를 요약하여 호환성 정리가 임시 검색에 의존하지 않고 명시적으로 유지되도록 합니다. 예약 SDK 하위 경로에는 추적된 소유자 사용이 있어야 합니다. 사용되지 않는 예약 헬퍼 내보내기는 공개 SDK에서 제거해야 합니다.

매니페스트 필드가 아직 허용되는 경우, Plugin 작성자는 문서와 진단이 달리 말할 때까지 계속 사용할 수 있습니다. 새 코드는 문서화된 대체 항목을 선호해야 하지만, 기존 Plugin은 일반적인 마이너 릴리스 중에 깨지면 안 됩니다.

마이그레이션 방법

await api.runtime.config.mutateConfigFile({  afterWrite: { mode: "auto" },  mutate(draft) {    draft.plugins ??= {};  },});

// OpenClaw and Codex runtime dynamic toolsapi.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"]  }}

// Beforeconst program = applyWindowsSpawnProgramPolicy({ candidate }); // Afterconst program = applyWindowsSpawnProgramPolicy({  candidate,  // Only set this for trusted compatibility callers that intentionally  // accept shell-mediated fallback.  allowShellFallback: true,});

grep -r "plugin-sdk/compat" my-plugin/grep -r "plugin-sdk/infra-runtime" my-plugin/grep -r "plugin-sdk/config-runtime" my-plugin/grep -r "openclaw/extension-api" my-plugin/

// Before (deprecated backwards-compatibility layer)import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // After (modern focused imports)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";

// Before (deprecated extension-api bridge)import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // After (injected runtime)const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test -- my-plugin/

Import 경로 참조

이 표는 전체 SDK 표면이 아니라 의도적으로 공통 마이그레이션 하위 집합만 다룹니다. 컴파일러 엔트리포인트 인벤토리는 scripts/lib/plugin-sdk-entrypoints.json에 있으며, 패키지 exports는 공개 하위 집합에서 생성됩니다.

예약된 번들 Plugin 헬퍼 이음새는 폐기된 plugin-sdk/discord shim처럼 게시된 @openclaw/discord@2026.3.13 패키지를 위해 유지되는 명시적으로 문서화된 호환성 facade를 제외하고 공개 SDK export map에서 은퇴되었습니다. 소유자별 헬퍼는 해당 소유 Plugin 패키지 안에 있습니다. 공유 호스트 동작은 plugin-sdk/gateway-runtime, plugin-sdk/security-runtime, plugin-sdk/plugin-config-runtime 같은 일반 SDK 계약을 통해 이동해야 합니다.

작업에 맞는 가장 좁은 import를 사용하세요. export를 찾을 수 없다면 src/plugin-sdk/의 소스를 확인하거나 어떤 일반 계약이 그것을 소유해야 하는지 메인테이너에게 문의하세요.

활성 지원 중단 항목

Plugin SDK, 공급자 계약, 런타임 표면, 매니페스트 전반에 적용되는 더 좁은 지원 중단 항목입니다. 각 항목은 오늘도 여전히 동작하지만 향후 메이저 릴리스에서 제거됩니다. 각 항목 아래의 엔트리는 이전 API를 표준 대체 항목에 매핑합니다.

// Beforeimport { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // Afterimport { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// Beforeapi.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // Afterapi.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

// Beforeapi.on("subagent_spawning", async () => ({  status: "ok",  threadBindingReady: true,  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },})); // Afterapi.on("subagent_spawned", async (event) => {  await observeSubagentLaunch(event);});

{  "contracts": {    "externalAuthProviders": ["anthropic", "openai"]  }}

// Beforeconst flow = api.runtime.tasks.flow.fromToolContext(ctx);// Afterconst flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Beforeimport type { OpenClawSchemaType } from "openclaw/plugin-sdk";// Afterimport type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

제거 일정

모든 핵심 Plugin은 이미 마이그레이션되었습니다. 외부 Plugin은 다음 메이저 릴리스 전에 마이그레이션해야 합니다.

경고를 일시적으로 숨기기

마이그레이션 작업 중에는 다음 환경 변수를 설정하세요.

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

이는 영구적인 해결책이 아니라 임시 우회 수단입니다.

관련 항목

• 시작하기 - 첫 Plugin 빌드하기
• SDK 개요 - 전체 하위 경로 가져오기 참조
• 채널 Plugin - 채널 Plugin 빌드하기
• Provider Plugin - Provider Plugin 빌드하기
• Plugin 내부 - 아키텍처 심층 분석
• Plugin 매니페스트 - 매니페스트 스키마 참조