Plugin SDK 마이그레이션

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJjb21tYW5kLWF1dGgg64-E7JuA66eQIOu5jOuNlCAt command-status"> 기존 (openclaw/plugin-sdk/command-auth): buildCommandsMessage, buildCommandsMessagePaginated, buildHelpMessage.

신규 (openclaw/plugin-sdk/command-status): 동일한 시그니처와 동일한 내보내기이며, 더 세분화된 하위 경로에서 가져오기만 하면 됩니다. command-auth는 이를 호환성 스텁으로 다시 내보냅니다.

// 이전import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // 이후import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLrqZjshZgg6rKM7J207YyFIO2XrO2NvCAt resolveInboundMentionDecision"> 기존: openclaw/plugin-sdk/channel-inbound 또는 openclaw/plugin-sdk/channel-mention-gating의 resolveMentionGating(params) 및 resolveMentionGatingWithBypass(params).

신규: resolveInboundMentionDecision({ facts, policy }) - 분리된 두 가지 호출 형태 대신 하나의 결정 객체를 사용합니다.

Discord, iMessage, Matrix, MS Teams, QQBot, Signal, Telegram, WhatsApp, Zalo 전반에 적용되었습니다. Slack의 자체 app_mention 이벤트 모델은 이 헬퍼를 사용하지 않습니다.

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLsm7kg6rKA7IOJIOygnOqzteyekCB0b29sKCkg7Zes7Y28IC0 Plugin의 createTool()"> 기존: openclaw/plugin-sdk/provider-web-search의 tool() 팩토리.

신규: 제공자 Plugin에 createTool(...)을 직접 구현하십시오. OpenClaw는 도구 래퍼 등록에 더 이상 SDK 헬퍼가 필요하지 않습니다.

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLsnbzrsJgg7YWN7Iqk7Yq4IOyxhOuEkCDsl5TrsozroZztlIQgLQ BodyForAgent"> 기존: 인바운드 채널 메시지에서 평면 일반 텍스트 프롬프트 엔벌로프를 만들기 위한 api.runtime.channel.reply.formatInboundEnvelope(...) 및 인바운드 메시지 객체의 channelEnvelope 필드.

신규: BodyForAgent와 구조화된 사용자 컨텍스트 블록을 사용합니다. 채널 Plugin은 라우팅 메타데이터(스레드, 주제, 회신 대상, 반응)를 프롬프트 문자열에 연결하는 대신 형식화된 필드로 첨부합니다. 합성된 어시스턴트 대상 엔벌로프에는 formatAgentEnvelope(...) 헬퍼가 계속 지원되지만, 인바운드 일반 텍스트 엔벌로프는 단계적으로 제거되고 있습니다.

영향받는 영역: inbound_claim, message_received, 그리고 기존 엔벌로프 텍스트를 후처리한 모든 사용자 지정 채널 Plugin.

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJkZWFjdGl2YXRlIO2bhSAt gateway_stop"> 기존: api.on("deactivate", handler).

신규: api.on("gateway_stop", handler). 종료 정리 계약은 동일하며 훅 이름만 변경됩니다.

// 이전api.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // 이후api.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

deactivate는 2026-08-16 이후 제거될 때까지 사용 중단된 호환성 별칭으로 계속 연결됩니다.

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJzdWJhZ2VudF9zcGF3bmluZyDtm4UgLQ 코어 스레드 바인딩"> 기존: threadBindingReady 또는 deliveryOrigin을 반환하는 api.on("subagent_spawning", handler).

신규: 코어가 채널 세션 바인딩 어댑터를 통해 thread: true 하위 에이전트 바인딩을 준비하도록 하십시오. 실행 후 관찰에만 api.on("subagent_spawned", handler)를 사용하십시오.

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

subagent_spawning, PluginHookSubagentSpawningEvent, PluginHookSubagentSpawningResult 및 SubagentLifecycleHookRunner.runSubagentSpawning(...)은 외부 플러그인이 마이그레이션하는 동안 사용 중단된 호환성 표면으로만 유지되며, 2026-08-30 이후 제거됩니다.

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLsgqzqs6Ag7KCV7LGFIO2bhSAt resolveThinkingProfile"> 이전 (ProviderThinkingPolicy의 세 가지 개별 훅): isBinaryThinking(ctx), supportsXHighThinking(ctx) 및 resolveDefaultThinkingLevel(ctx).

신규: 표준 id, 선택적 label, 순위가 지정된 수준 목록을 포함하는 ProviderThinkingProfile을 반환하는 단일 resolveThinkingProfile(ctx)입니다. OpenClaw는 저장된 오래된 값을 프로필 순위에 따라 자동으로 하향 조정합니다.

컨텍스트에는 provider, modelId, 선택적으로 병합된 reasoning, 선택적으로 병합된 모델 compat 정보가 포함됩니다. Provider 플러그인은 구성된 요청 계약이 지원하는 경우에만 이러한 카탈로그 정보를 사용하여 모델별 프로필을 노출할 수 있습니다.

세 개 대신 하나의 훅을 구현하십시오. 레거시 훅은 사용 중단 기간에도 계속 작동하지만 프로필 결과와 결합되지는 않습니다.

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLsmbjrtoAg7J247KadIFByb3ZpZGVyIC0 contracts.externalAuthProviders"> 이전: 플러그인 매니페스트에 Provider를 선언하지 않고 외부 인증 훅을 구현했습니다.

신규: 플러그인 매니페스트에 contracts.externalAuthProviders를 선언하고 동시에 resolveExternalAuthProfiles(...)를 구현하십시오.

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

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJQcm92aWRlciDtmZjqsr0g67OA7IiYIOyhsO2ajCAt setup.providers[].envVars"> 이전 매니페스트 필드: providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }.

신규: 동일한 환경 변수 조회를 매니페스트의 setup.providers[].envVars에도 반영하십시오. 이렇게 하면 설정/상태 환경 메타데이터가 한곳으로 통합되고, 환경 변수 조회에 응답하기 위해 플러그인 런타임을 부팅할 필요가 없어집니다.

providerAuthEnvVars는 사용 중단 기간이 끝날 때까지 호환성 어댑터를 통해 계속 지원됩니다.

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLrqZTrqqjrpqwg7ZSM65-s6re47J24IOuTseuhnSAt registerMemoryCapability"> 이전: 세 번의 개별 호출 - api.registerMemoryPromptSection(...), api.registerMemoryFlushPlan(...), api.registerMemoryRuntime(...).

신규: 메모리 상태 API에서 한 번 호출 - registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime }).

동일한 슬롯을 한 번의 등록 호출로 처리합니다. 추가 프롬프트 및 코퍼스 도우미(registerMemoryPromptSupplement, registerMemoryCorpusSupplement)는 영향을 받지 않습니다.

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJydW50aW1lLnRhc2tzLmZsb3cgLQ runtime.tasks.managedFlows"> 이전: runtime.tasks.flow(단수)는 라이브 작업 흐름 접근자를 반환했습니다.

신규: runtime.tasks.managedFlows는 흐름에서 하위 작업을 생성, 업데이트, 취소 또는 실행하는 Plugin을 위해 관리형 TaskFlow 변경 런타임을 유지합니다. Plugin에 DTO 기반 읽기만 필요한 경우 runtime.tasks.flows를 사용하십시오.

// 이전const flow = api.runtime.tasks.flow.fromToolContext(ctx);// 이후const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

2026-07-26 이후 제거되었습니다.

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLrgrTsnqUg7ZmV7J6lIO2Mqe2GoOumrCAt 에이전트 도구 결과 미들웨어"> 위의 마이그레이션 방법에서 다룹니다. 완전성을 위해 여기에 포함합니다. 제거된 내장 실행기 전용 api.registerEmbeddedExtensionFactory(...) 경로는 contracts.agentToolResultMiddleware의 명시적 런타임 목록과 함께 api.registerAgentToolResultMiddleware(...)로 대체됩니다.

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJPcGVuQ2xhd1NjaGVtYVR5cGUg67OE7LmtIC0 OpenClawConfig"> openclaw/plugin-sdk에서 다시 내보낸 OpenClawSchemaType은 이제 OpenClawConfig의 한 줄짜리 별칭입니다. 정식 이름을 우선 사용하십시오.

// 이전import type { OpenClawSchemaType } from "openclaw/plugin-sdk";// 이후import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";