Plugin SDK 마이그레이션

OpenClaw는 광범위한 하위 호환성 계층에서 초점이 분명하고 문서화된 import를 사용하는 최신 Plugin 아키텍처로 이동했습니다. 새 아키텍처 이전에 Plugin을 만들었다면 이 가이드가 마이그레이션에 도움이 됩니다.

# 변경 사항

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

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

광범위한 import 표면은 이제 사용 중단 예정입니다. 런타임에서는 아직 작동하지만, 새 Plugin은 이를 사용하면 안 되며, 기존 Plugin은 다음 major release에서 제거되기 전에 마이그레이션해야 합니다. Pi 전용 embedded extension factory 등록 API는 제거되었습니다. 대신 tool-result middleware를 사용하세요.

OpenClaw는 대체 항목을 도입하는 동일한 변경에서 문서화된 Plugin 동작을 제거하거나 재해석하지 않습니다. 계약을 깨는 변경은 먼저 호환성 adapter, diagnostics, docs, deprecation window를 거쳐야 합니다. 이는 SDK import, manifest field, setup API, hook, 런타임 등록 동작에 적용됩니다.

# 변경 이유

기존 접근 방식은 문제를 일으켰습니다.

• 느린 시작 - 하나의 헬퍼를 import하면 관련 없는 수십 개의 module이 load되었습니다.
• 순환 의존성 - 광범위한 re-export로 import cycle을 만들기 쉬웠습니다.
• 불명확한 API 표면 - 어떤 export가 안정적인지 내부용인지 구분할 방법이 없었습니다.

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

bundled channel을 위한 legacy provider 편의 seam도 제거되었습니다. Channel 브랜드가 붙은 헬퍼 seam은 안정적인 Plugin 계약이 아니라 private mono-repo shortcut이었습니다. 대신 좁은 generic SDK subpath를 사용하세요. bundled Plugin workspace 안에서는 provider 소유 헬퍼를 해당 Plugin 자체의 api.ts 또는 runtime-api.ts에 유지하세요.

현재 bundled provider 예시:

• Anthropic은 Claude 전용 stream 헬퍼를 자체 api.ts / contract-api.ts seam에 유지합니다.
• OpenAI는 provider builder, default-model 헬퍼, realtime provider builder를 자체 api.ts에 유지합니다.
• OpenRouter는 provider builder와 onboarding/config 헬퍼를 자체 api.ts에 유지합니다.

# Talk 및 realtime voice 마이그레이션 계획

Realtime voice, telephony, meeting, browser Talk 코드는 surface별 turn bookkeeping에서 openclaw/plugin-sdk/realtime-voice가 export하는 공유 Talk session controller로 이동하고 있습니다. 새 controller는 공통 Talk event envelope, active turn 상태, capture 상태, output-audio 상태, 최근 event history, stale-turn 거부를 소유합니다. Provider Plugin은 vendor별 realtime session을 계속 소유해야 하며, surface Plugin은 capture, playback, telephony, meeting 관련 특수 처리를 계속 소유해야 합니다.

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

1. 공유 controller/runtime primitive를 plugin-sdk/realtime-voice에 유지합니다.
2. bundled surface를 공유 controller로 이동합니다: browser relay, managed-room handoff, voice-call realtime, voice-call streaming STT, Google Meet realtime, native push-to-talk.
3. 기존 Talk RPC family를 최종 talk.session.* 및 talk.client.* API로 교체합니다.
4. Gateway hello-ok.features.events에서 하나의 live Talk event channel을 알립니다: talk.event.
5. 기존 realtime HTTP endpoint와 request-time instruction override path를 삭제합니다.

새 코드는 low-level adapter 또는 test fixture를 구현하는 경우가 아니라면 createTalkEventSequencer(...)를 직접 호출하지 않아야 합니다. 공유 controller를 선호하세요. 그러면 turn id 없이 turn 범위 event가 emit될 수 없고, 오래된 turnEnd / turnCancel 호출이 더 새로운 active turn을 지울 수 없으며, output-audio lifecycle event가 telephony, meeting, browser relay, managed-room handoff, native Talk client 전반에서 일관되게 유지됩니다.

목표 public 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 });
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 });

Browser 소유 WebRTC/provider-websocket session은 talk.client.create를 사용합니다. browser가 provider negotiation과 media transport를 소유하고, Gateway가 credentials, instructions, tool policy를 소유하기 때문입니다. talk.session.*는 gateway-relay realtime, gateway-relay transcription, managed-room native STT/TTS session을 위한 공통 Gateway 관리 surface입니다.

tallk.provider / talk.providers 옆에 realtime selector를 배치한 legacy config는 openclaw doctor --fix로 복구해야 합니다. 런타임 Talk는 speech/TTS provider config를 realtime provider config로 재해석하지 않습니다.

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

제거된 method map:

통합 control vocabulary도 의도적으로 좁습니다.

이를 동작하게 하려고 core에 provider 또는 platform 특수 사례를 도입하지 마세요. Core는 Talk session semantics를 소유합니다. Provider Plugin은 vendor session setup을 소유합니다. Voice-call과 Google Meet은 telephony/meeting adapter를 소유합니다. Browser와 native app은 device capture/playback UX를 소유합니다.

# 호환성 정책

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

1. 새 계약을 추가합니다.
2. 기존 동작을 compatibility adapter를 통해 계속 연결합니다.
3. 기존 path와 replacement를 이름으로 알려 주는 diagnostic 또는 warning을 emit합니다.
4. 두 path를 모두 test에서 다룹니다.
5. deprecation 및 migration path를 문서화합니다.
6. 공지된 migration window 이후에만 제거합니다. 일반적으로 major release에서 제거합니다.

관리자는 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 ??= {};
  },
});

// Pi and Codex runtime dynamic tools
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["pi", "codex"],
});

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

// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });

// After
const 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 { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });

// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

pnpm build
pnpm test -- my-plugin/

# 가져오기 경로 참조

이 표는 의도적으로 전체 SDK 표면이 아니라 공통 마이그레이션 하위 집합만 다룹니다. 200개 이상의 진입점 전체 목록은 scripts/lib/plugin-sdk-entrypoints.json에 있습니다.

예약된 번들 Plugin 헬퍼 이음매는 명시적으로 문서화된 호환성 파사드(예: 게시된 @openclaw/[email protected] 패키지를 위해 유지되는 사용 중단된 plugin-sdk/discord shim)를 제외하고 public 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, provider 계약, runtime 표면, manifest 전반에 적용되는 더 좁은 범위의 사용 중단입니다. 각각은 현재도 동작하지만 향후 major release에서 제거됩니다. 각 항목 아래의 항목은 이전 API를 정식 대체 항목에 매핑합니다.

// Before
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

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

// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

# 제거 일정

모든 core Plugin은 이미 마이그레이션되었습니다. 외부 Plugin은 다음 major release 전에 마이그레이션해야 합니다.

# 경고 일시적으로 억제하기

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

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

이는 임시 escape hatch이지 영구적인 해결책이 아닙니다.

# 관련 항목

• 시작하기 - 첫 Plugin 빌드하기
• SDK 개요 - 전체 subpath import reference
• Channel Plugin - channel Plugin 빌드하기
• Provider Plugin - provider Plugin 빌드하기
• Plugin 내부 구조 - architecture 심층 분석
• Plugin Manifest - manifest schema reference