Plugin SDK 마이그레이션

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.

​

변경되는 사항

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

​

변경 이유

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

• 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에 유지합니다

​

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

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를 삭제합니다.

// 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 });

​

호환성 정책

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

​

마이그레이션 방법

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/

​

가져오기 경로 참조

​

활성 deprecation

// 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";

​

제거 일정

​

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

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

​

관련 항목

• 시작하기 - 첫 Plugin 빌드
• SDK 개요 - 전체 subpath import 참조
• 채널 Plugins - 채널 plugins 빌드
• 제공자 Plugins - 제공자 plugins 빌드
• Plugin 내부 구조 - 아키텍처 심층 설명
• Plugin Manifest - manifest schema 참조