Skip to main content
OpenClaw는 광범위한 이전 버전 호환성 계층을 작고 목적이 명확한 import로 구성된 현대적인 Plugin 아키텍처로 교체했습니다. Plugin이 이 변경 전에 만들어졌다면 이 가이드를 따라 현재 계약으로 마이그레이션할 수 있습니다.

변경 사항

이전에는 제한이 거의 없는 두 import 표면을 통해 Plugin이 단일 진입점에서 거의 모든 항목에 접근할 수 있었습니다.
  • openclaw/plugin-sdk/compat - 새로운 아키텍처를 구축하는 동안 기존 훅 기반 Plugin이 계속 작동하도록 수십 개의 헬퍼를 다시 export했습니다.
  • openclaw/plugin-sdk/infra-runtime - 시스템 이벤트, Heartbeat 상태, 전송 큐, fetch/프록시 헬퍼, 파일 헬퍼, 승인 타입 및 서로 관련 없는 유틸리티를 혼합한 광범위한 배럴입니다.
  • openclaw/plugin-sdk/config-runtime - 마이그레이션 기간에 폐기 예정인 직접 로드/쓰기 헬퍼를 계속 포함했던 광범위한 구성 배럴입니다.
  • openclaw/extension-api - 내장 에이전트 실행기 같은 호스트 측 헬퍼에 Plugin이 직접 접근할 수 있게 한 브리지입니다.
  • api.registerEmbeddedExtensionFactory(...) - tool_result 같은 내장 실행기 이벤트를 관찰하던, 이제 제거된 내장 실행기 전용 훅입니다. 대신 에이전트 도구 결과 미들웨어를 사용하십시오(내장 도구 결과 확장을 미들웨어로 마이그레이션 참조).
이러한 표면은 폐기 예정입니다. 아직 작동하지만 새 Plugin은 이를 사용해서는 안 되며, 기존 Plugin은 다음 메이저 릴리스에서 제거되기 전에 마이그레이션해야 합니다. registerEmbeddedExtensionFactory는 이미 제거되었으며 레거시 등록은 더 이상 로드되지 않습니다.
이전 버전 호환성 계층은 향후 메이저 릴리스에서 제거됩니다. 이러한 표면에서 계속 import하는 Plugin은 제거 후 작동하지 않습니다.
OpenClaw는 대체 기능을 도입하는 동일한 변경에서 문서화된 Plugin 동작을 제거하거나 다르게 해석하지 않습니다. 계약을 깨는 변경에는 먼저 호환성 어댑터, 진단, 문서 및 폐기 유예 기간을 적용합니다. 이는 SDK import, 매니페스트 필드, 설정 API, 훅 및 런타임 등록 동작에 적용됩니다.

이유

  • 느린 시작 - 헬퍼 하나를 import하면 관련 없는 수십 개의 모듈까지 로드되었습니다.
  • 순환 종속성 - 광범위한 재export로 인해 import 순환이 쉽게 발생했습니다.
  • 불명확한 API 표면 - 안정적인 export와 내부 export를 구분할 방법이 없었습니다.
이제 각 openclaw/plugin-sdk/<subpath>는 문서화된 계약을 제공하는 작고 독립적인 모듈입니다. 번들 채널용 레거시 공급자 편의 연결부도 제거되었습니다. 채널 브랜드별 헬퍼 단축 기능은 비공개 모노리포 편의 기능이었으며 안정적인 Plugin 계약이 아니었습니다. 대신 범위가 좁은 범용 SDK 하위 경로를 사용하십시오. 번들 Plugin 워크스페이스 내에서는 공급자가 소유하는 헬퍼를 해당 Plugin의 api.ts 또는 runtime-api.ts에 유지하십시오.
  • Anthropic은 Claude 전용 스트림 헬퍼를 자체 api.ts / contract-api.ts 연결부에 유지합니다.
  • OpenAI는 공급자 빌더, 기본 모델 헬퍼 및 실시간 공급자 빌더를 자체 api.ts에 유지합니다.
  • OpenRouter는 공급자 빌더와 온보딩/구성 헬퍼를 자체 api.ts에 유지합니다.

호환성 정책

외부 Plugin의 호환성 작업은 다음 순서를 따릅니다.
  1. 새 계약을 추가합니다.
  2. 호환성 어댑터를 통해 기존 동작이 계속 연결되도록 유지합니다.
  3. 기존 경로와 대체 경로를 명시하는 진단 또는 경고를 표시합니다.
  4. 테스트에서 두 경로를 모두 다룹니다.
  5. 폐기 예정 사항과 마이그레이션 경로를 문서화합니다.
  6. 공지된 마이그레이션 기간이 지난 후에만 제거하며, 일반적으로 메이저 릴리스에서 제거합니다.
매니페스트 필드가 여전히 허용된다면 문서와 진단에서 달리 안내할 때까지 계속 사용하십시오. 새 코드는 문서화된 대체 기능을 우선해야 하며, 기존 Plugin은 일반적인 마이너 릴리스 중에 중단되어서는 안 됩니다. pnpm plugins:boundary-report로 현재 마이그레이션 대기열을 감사하십시오. pnpm plugins:boundary-report:ci는 세 가지 실패 플래그를 모두 사용해 실행됩니다. 각 호환성 레코드에는 모호한 “다음 메이저 릴리스”가 아닌 명시적인 removeAfter 날짜가 있습니다. 보고서는 해당 날짜별로 폐기 예정 레코드를 그룹화하고, 로컬 코드/문서 참조 수를 집계하며, 소유자 경계를 넘는 예약 SDK import를 표시하고, 비공개 메모리 호스트 SDK 브리지를 요약합니다. 예약 SDK 하위 경로에는 추적되는 소유자 사용 내역이 있어야 하며, 사용되지 않는 예약 export는 공개 SDK에서 제거해야 합니다.

마이그레이션 방법

1

런타임 구성 로드/쓰기 헬퍼 마이그레이션

번들 Plugin은 api.runtime.config.loadConfig()api.runtime.config.writeConfigFile(...)을 직접 호출하지 않아야 합니다. 활성 호출 경로에 이미 전달된 구성을 우선 사용하십시오. 현재 프로세스 스냅샷이 필요한 장기 실행 핸들러는 api.runtime.config.current()를 사용할 수 있습니다. 장기 실행 에이전트 도구는 execute 내부에서 ctx.getRuntimeConfig()를 읽어야 구성 쓰기 전에 생성된 도구도 새로 고친 구성을 볼 수 있습니다.구성 쓰기는 명시적인 쓰기 후 정책을 지정하여 트랜잭션 헬퍼를 통해 수행합니다.
변경에 완전한 Gateway 재시작이 필요하면 afterWrite: { mode: "restart", reason: "..." }를 사용하고, 호출자가 후속 작업을 소유하며 의도적으로 다시 로드 플래너를 억제할 때만 afterWrite: { mode: "none", reason: "..." }를 사용하십시오. 변형 결과에는 테스트 및 로깅을 위한 타입 지정 followUp 요약이 포함됩니다. 재시작을 적용하거나 예약하는 책임은 계속 Gateway에 있습니다.loadConfigwriteConfigFile은 외부 Plugin을 위한 폐기 예정 호환성 헬퍼로 유지되며 runtime-config-load-write 호환성 코드와 함께 한 번 경고합니다. 번들 Plugin과 저장소 런타임 코드는 pnpm check:deprecated-api-usagepnpm check:no-runtime-action-load-config로 보호됩니다. 새로운 프로덕션 Plugin 사용은 즉시 실패하고, 직접 구성 쓰기도 실패하며, Gateway 서버 메서드는 요청 런타임 스냅샷을 사용해야 하고, 런타임 채널 전송/작업/클라이언트 헬퍼는 해당 경계에서 구성을 전달받아야 하며, 장기 실행 런타임 모듈에서는 주변 loadConfig() 호출을 하나도 허용하지 않습니다.새 Plugin 코드는 광범위한 openclaw/plugin-sdk/config-runtime 배럴을 피해야 합니다. 작업에 맞는 범위가 좁은 하위 경로를 사용하십시오.번들 Plugin과 해당 테스트는 스캐너를 통해 광범위한 배럴 사용이 차단되므로 import와 모의 객체가 필요한 동작에만 국한됩니다. 이 배럴은 외부 호환성을 위해 계속 존재하지만 새 코드는 이에 의존해서는 안 됩니다.
2

내장 도구 결과 확장을 미들웨어로 마이그레이션

번들 Plugin은 내장 실행기 전용 api.registerEmbeddedExtensionFactory(...) 도구 결과 핸들러를 런타임 중립적인 미들웨어로 교체해야 합니다.
동시에 Plugin 매니페스트를 업데이트하십시오.
설치된 Plugin도 명시적으로 활성화되고 대상 런타임이 모두 contracts.agentToolResultMiddleware에 선언된 경우 도구 결과 미들웨어를 등록할 수 있습니다. 선언되지 않은 설치형 미들웨어 등록은 거부됩니다.
3

승인 네이티브 핸들러를 기능 정보로 마이그레이션

승인 기능을 지원하는 채널 Plugin은 approvalCapability.nativeRuntime과 공유 런타임 컨텍스트 레지스트리를 통해 네이티브 승인 동작을 노출합니다.
  • approvalCapability.handler.loadRuntime(...)approvalCapability.nativeRuntime으로 교체합니다.
  • 승인 전용 인증/전송을 레거시 plugin.auth / plugin.approvals 연결에서 approvalCapability로 이동합니다.
  • ChannelPlugin.approvals는 공개 채널 Plugin 계약에서 제거되었습니다. 전송/네이티브/렌더링 필드를 approvalCapability로 이동합니다.
  • plugin.auth는 채널 로그인/로그아웃 흐름에만 유지됩니다. 코어는 더 이상 여기서 승인 인증 훅을 읽지 않습니다.
  • 채널이 소유하는 런타임 객체(클라이언트, 토큰, Bolt 앱)는 openclaw/plugin-sdk/channel-runtime-context를 통해 등록합니다.
  • 네이티브 승인 핸들러에서 Plugin 소유의 재라우팅 알림을 보내지 마십시오. 실제 전송 결과에 따른 다른 위치로의 라우팅 알림은 코어가 소유합니다.
  • channelRuntimecreateChannelManager(...)에 전달할 때는 실제 createPluginRuntime().channel 표면을 제공하십시오. 부분 스텁은 거부됩니다.
현재 승인 기능 구조는 채널 Plugin을 참조하십시오.
4

Windows 래퍼 대체 동작 감사

Plugin에서 openclaw/plugin-sdk/windows-spawn을 사용하는 경우, 확인되지 않은 Windows .cmd/.bat 래퍼는 allowShellFallback: true를 명시적으로 전달하지 않으면 이제 실패 시 닫힙니다.
호출자가 셸 대체 동작에 의도적으로 의존하지 않는다면 allowShellFallback을 설정하지 말고 대신 발생한 오류를 처리하십시오.
5

폐기 예정 import 찾기

6

목적별 import로 교체

기존 표면의 각 export는 특정 현대식 import 경로에 매핑됩니다.
호스트 측 헬퍼의 경우 직접 가져오는 대신 주입된 Plugin 런타임을 사용하십시오.
다른 레거시 브리지 헬퍼에도 동일한 패턴을 적용합니다.
7

광범위한 infra-runtime 가져오기 교체

외부 호환성을 위해 openclaw/plugin-sdk/infra-runtime은 여전히 존재하지만, 새 코드에서는 실제로 필요한 세분화된 표면을 가져와야 합니다.번들 Plugin은 스캐너를 통해 infra-runtime 사용이 방지되므로 저장소 코드가 광범위한 배럴로 회귀할 수 없습니다.
8

채널 경로 헬퍼 마이그레이션

새 채널 경로 코드는 openclaw/plugin-sdk/channel-route를 사용합니다. 이전 경로 키 및 비교 가능한 대상 이름은 호환성 별칭으로 유지됩니다.현대적인 경로 헬퍼는 네이티브 승인, 응답 억제, 인바운드 중복 제거, Cron 전송 및 세션 라우팅 전반에서 { channel, to, accountId, threadId }를 일관되게 정규화합니다.ChannelMessagingAdapter.parseExplicitTarget, 파서 기반의 로드된 경로 헬퍼(parseExplicitTargetForLoadedChannel, resolveRouteTargetForLoadedChannel) 또는 plugin-sdk/channel-routeresolveChannelRouteTargetWithParser(...)를 새로 사용하지 마십시오. 이러한 항목은 사용 중단되었으며 이전 Plugin만을 위해 유지됩니다. 새 채널 Plugin은 대상 ID 정규화 및 디렉터리 조회 실패 시 대체 처리를 위해 messaging.targetResolver.resolveTarget(...)을 사용하고, 코어에서 피어 종류를 조기에 확인해야 할 때 messaging.inferTargetChatType(...)을 사용하며, 제공자 네이티브 세션 및 스레드 ID에는 messaging.resolveOutboundSessionRoute(...)를 사용해야 합니다.
9

빌드 및 테스트

가져오기 경로 참조

이 표는 전체 SDK 표면이 아니라 공통 마이그레이션 하위 집합입니다. 컴파일러 진입점 목록은 scripts/lib/plugin-sdk-entrypoints.json에 있으며, 패키지 내보내기는 공개 하위 집합에서 생성됩니다. 명시적으로 문서화된 호환성 퍼사드를 제외하고, 번들 Plugin용으로 예약된 헬퍼 연결 지점은 공개 SDK 내보내기 맵에서 제거되었습니다. 예를 들어 게시된 @openclaw/discord 패키지를 여전히 직접 가져오는 외부 Plugin을 위해 유지되는, 더 이상 사용되지 않는 plugin-sdk/discord 심이 있습니다. 소유자별 헬퍼는 해당 소유 Plugin 패키지 내부에 있으며, 공유 호스트 동작은 plugin-sdk/gateway-runtime, plugin-sdk/security-runtime, plugin-sdk/plugin-config-runtime 같은 일반 SDK 계약을 통해 이동합니다. 작업에 맞는 가장 좁은 가져오기를 사용하십시오. 내보내기를 찾을 수 없다면 src/plugin-sdk/의 소스를 확인하거나 어떤 일반 계약이 이를 소유해야 하는지 유지관리자에게 문의하십시오.

현재 사용 중단 예정 항목

Plugin SDK, 제공자 계약, 런타임 표면, 매니페스트 전반에 걸친 더 세분화된 사용 중단 예정 항목입니다. 각 항목은 현재도 작동하지만 향후 메이저 릴리스에서 제거됩니다. 모든 항목은 기존 API를 정식 대체 항목에 매핑합니다.
기존 (openclaw/plugin-sdk/command-auth): buildCommandsMessage, buildCommandsMessagePaginated, buildHelpMessage.신규 (openclaw/plugin-sdk/command-status): 동일한 시그니처와 동일한 내보내기이며, 더 세분화된 하위 경로에서 가져오기만 하면 됩니다. command-auth는 이를 호환성 스텁으로 다시 내보냅니다.
기존: openclaw/plugin-sdk/channel-inbound 또는 openclaw/plugin-sdk/channel-mention-gatingresolveMentionGating(params)resolveMentionGatingWithBypass(params).신규: resolveInboundMentionDecision({ facts, policy }) - 분리된 두 가지 호출 형태 대신 하나의 결정 객체를 사용합니다.Discord, iMessage, Matrix, MS Teams, QQBot, Signal, Telegram, WhatsApp, Zalo 전반에 적용되었습니다. Slack의 자체 app_mention 이벤트 모델은 이 헬퍼를 사용하지 않습니다.
openclaw/plugin-sdk/channel-runtime은 이전 채널 Plugin을 위한 호환성 심입니다. 새 코드에서는 이를 가져오지 말고, 런타임 객체 등록에 openclaw/plugin-sdk/channel-runtime-context를 사용하십시오.openclaw/plugin-sdk/channel-actionschannelActions* 헬퍼는 원시 “actions” 채널 내보내기와 함께 사용 중단 예정입니다. 대신 의미론적 presentation 표면을 통해 기능을 노출하십시오. 채널 Plugin은 허용하는 원시 작업 이름이 아니라 렌더링하는 항목(카드, 버튼, 선택 항목)을 선언합니다.
기존: openclaw/plugin-sdk/provider-web-searchtool() 팩토리.신규: 제공자 Plugin에 createTool(...)을 직접 구현하십시오. OpenClaw는 도구 래퍼 등록에 더 이상 SDK 헬퍼가 필요하지 않습니다.
기존: 인바운드 채널 메시지에서 평면 일반 텍스트 프롬프트 엔벌로프를 만들기 위한 api.runtime.channel.reply.formatInboundEnvelope(...) 및 인바운드 메시지 객체의 channelEnvelope 필드.신규: BodyForAgent와 구조화된 사용자 컨텍스트 블록을 사용합니다. 채널 Plugin은 라우팅 메타데이터(스레드, 주제, 회신 대상, 반응)를 프롬프트 문자열에 연결하는 대신 형식화된 필드로 첨부합니다. 합성된 어시스턴트 대상 엔벌로프에는 formatAgentEnvelope(...) 헬퍼가 계속 지원되지만, 인바운드 일반 텍스트 엔벌로프는 단계적으로 제거되고 있습니다.영향받는 영역: inbound_claim, message_received, 그리고 기존 엔벌로프 텍스트를 후처리한 모든 사용자 지정 채널 Plugin.
기존: api.on("deactivate", handler).신규: api.on("gateway_stop", handler). 종료 정리 계약은 동일하며 훅 이름만 변경됩니다.
deactivate는 2026-08-16 이후 제거될 때까지 사용 중단된 호환성 별칭으로 계속 연결됩니다.
기존: threadBindingReady 또는 deliveryOrigin을 반환하는 api.on("subagent_spawning", handler).신규: 코어가 채널 세션 바인딩 어댑터를 통해 thread: true 하위 에이전트 바인딩을 준비하도록 하십시오. 실행 후 관찰에만 api.on("subagent_spawned", handler)를 사용하십시오.
subagent_spawning, PluginHookSubagentSpawningEvent, PluginHookSubagentSpawningResultSubagentLifecycleHookRunner.runSubagentSpawning(...)은 외부 플러그인이 마이그레이션하는 동안 사용 중단된 호환성 표면으로만 유지되며, 2026-08-30 이후 제거됩니다.
이제 네 가지 검색 타입 별칭은 카탈로그 시대 타입을 감싸는 얇은 래퍼입니다.또한 레거시 ProviderCapabilities 정적 모음이 있습니다. Provider 플러그인은 정적 객체 대신 buildReplayPolicy, normalizeToolSchemas, wrapStreamFn과 같은 명시적 Provider 훅을 사용해야 합니다.
이전 (ProviderThinkingPolicy의 세 가지 개별 훅): isBinaryThinking(ctx), supportsXHighThinking(ctx)resolveDefaultThinkingLevel(ctx).신규: 표준 id, 선택적 label, 순위가 지정된 수준 목록을 포함하는 ProviderThinkingProfile을 반환하는 단일 resolveThinkingProfile(ctx)입니다. OpenClaw는 저장된 오래된 값을 프로필 순위에 따라 자동으로 하향 조정합니다.컨텍스트에는 provider, modelId, 선택적으로 병합된 reasoning, 선택적으로 병합된 모델 compat 정보가 포함됩니다. Provider 플러그인은 구성된 요청 계약이 지원하는 경우에만 이러한 카탈로그 정보를 사용하여 모델별 프로필을 노출할 수 있습니다.세 개 대신 하나의 훅을 구현하십시오. 레거시 훅은 사용 중단 기간에도 계속 작동하지만 프로필 결과와 결합되지는 않습니다.
이전: 플러그인 매니페스트에 Provider를 선언하지 않고 외부 인증 훅을 구현했습니다.신규: 플러그인 매니페스트에 contracts.externalAuthProviders를 선언하고 동시에 resolveExternalAuthProfiles(...)를 구현하십시오.
이전 매니페스트 필드: providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }.신규: 동일한 환경 변수 조회를 매니페스트의 setup.providers[].envVars에도 반영하십시오. 이렇게 하면 설정/상태 환경 메타데이터가 한곳으로 통합되고, 환경 변수 조회에 응답하기 위해 플러그인 런타임을 부팅할 필요가 없어집니다.providerAuthEnvVars는 사용 중단 기간이 끝날 때까지 호환성 어댑터를 통해 계속 지원됩니다.
이전: 세 번의 개별 호출 - api.registerMemoryPromptSection(...), api.registerMemoryFlushPlan(...), api.registerMemoryRuntime(...).신규: 메모리 상태 API에서 한 번 호출 - registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime }).동일한 슬롯을 한 번의 등록 호출로 처리합니다. 추가 프롬프트 및 코퍼스 도우미(registerMemoryPromptSupplement, registerMemoryCorpusSupplement)는 영향을 받지 않습니다.
이전: api.registerMemoryEmbeddingProvider(...)contracts.memoryEmbeddingProviders.신규: api.registerEmbeddingProvider(...)contracts.embeddingProviders.일반 임베딩 Provider 계약은 메모리 외부에서도 재사용할 수 있으며 새로운 Provider에서 지원되는 경로입니다. 기존 Provider가 마이그레이션하는 동안 메모리 전용 등록 API는 사용 중단된 호환성을 위해 계속 연결된 상태로 유지됩니다. 플러그인 검사는 번들되지 않은 사용을 호환성 부채로 보고합니다.
src/plugins/runtime/types.ts에서 여전히 내보내는 두 가지 레거시 타입 별칭:런타임 메서드 readSessiongetSessionMessages를 위해 사용 중단되었습니다. 시그니처는 동일하며 이전 메서드는 새 메서드를 호출합니다.
SQLite 세션/트랜스크립트 전환으로 인해 활성 sessions.json 저장소, JSONL 트랜스크립트 경로 또는 세션 파일 목록을 노출하던 플러그인 대상 API가 제거되거나 사용 중단됩니다. 런타임 플러그인은 활성 파일을 확인하거나 변경하는 대신 세션 ID와 SDK 런타임 도우미를 사용해야 합니다.레거시 JSONL 트랜스크립트 파일은 가져오기, 보관, 내보내기 및 지원 아티팩트로 계속 유효합니다. 하지만 더 이상 활성 세션의 정상 상태 런타임 계약이 아닙니다.v2026.7.1-beta.5와 함께 출시된 공식 Plugin은 위의 더 이상 사용되지 않는 헬퍼 4개를 가져왔습니다. openclaw/plugin-sdk/session-store-runtime은 2026-10-12까지 해당 브리지를 그대로 유지합니다. 새 Plugin은 대체 항목을 사용해야 합니다. resolveStorePath(...)는 계속 지원되는 SDK 헬퍼이며 이 사용 중단에 포함되지 않습니다.openclaw plugins inspect --all --runtime은 로드 오류 또는 진단에서 제거된 파일 API를 여전히 참조하는 번들 외부 Plugin을 보고합니다. 외부 패키지 검사에서도 전체 저장소 세션 헬퍼, 세션 파일 경로 헬퍼, 레거시 트랜스크립트 파일 대상 및 저수준 트랜스크립트 헬퍼를 출시 전에 표시하도록 @openclaw/plugin-inspector 권고 검사는 버전 0.3.17 이상을 사용해야 합니다.
이전: runtime.tasks.flow(단수)는 라이브 작업 흐름 접근자를 반환했습니다.신규: runtime.tasks.managedFlows는 흐름에서 하위 작업을 생성, 업데이트, 취소 또는 실행하는 Plugin을 위해 관리형 TaskFlow 변경 런타임을 유지합니다. Plugin에 DTO 기반 읽기만 필요한 경우 runtime.tasks.flows를 사용하십시오.
2026-07-26 이후 제거되었습니다.
위의 마이그레이션 방법에서 다룹니다. 완전성을 위해 여기에 포함합니다. 제거된 내장 실행기 전용 api.registerEmbeddedExtensionFactory(...) 경로는 contracts.agentToolResultMiddleware의 명시적 런타임 목록과 함께 api.registerAgentToolResultMiddleware(...)로 대체됩니다.
openclaw/plugin-sdk에서 다시 내보낸 OpenClawSchemaType은 이제 OpenClawConfig의 한 줄짜리 별칭입니다. 정식 이름을 우선 사용하십시오.
확장 수준의 사용 중단 항목(extensions/ 아래의 번들 채널/공급자 Plugin 내부)은 각각의 api.tsruntime-api.ts 배럴에서 추적됩니다. 이 항목들은 서드 파티 Plugin 계약에 영향을 주지 않으며 여기에 나열되지 않습니다. 번들 Plugin의 로컬 배럴을 직접 사용하는 경우 업그레이드하기 전에 해당 배럴의 사용 중단 주석을 읽으십시오.

Talk 및 실시간 음성 마이그레이션

실시간 음성, 전화 통신, 회의 및 브라우저 Talk 코드는 openclaw/plugin-sdk/realtime-voice에서 내보내는 하나의 Talk 세션 컨트롤러를 공유합니다. 이 컨트롤러는 공통 Talk 이벤트 봉투, 활성 턴 상태, 캡처 상태, 출력 오디오 상태, 최근 이벤트 기록 및 오래된 턴 거부를 소유합니다. 공급자 Plugin은 공급업체별 실시간 세션을 소유하며, 표면 Plugin은 캡처, 재생, 전화 통신 및 회의 관련 특수 동작을 소유합니다. 모든 번들 표면은 공유 컨트롤러에서 실행됩니다. 브라우저 릴레이, 관리형 룸 핸드오프, 음성 통화 실시간 처리, 음성 통화 스트리밍 STT, Google Meet 실시간 처리 및 네이티브 푸시투토크가 이에 포함됩니다. Gateway는 hello-ok.features.events에서 하나의 라이브 Talk 이벤트 채널인 talk.event를 알립니다. 저수준 어댑터 또는 테스트 픽스처를 구현하는 경우가 아니라면 새 코드에서 createTalkEventSequencer(...)를 직접 호출하지 마십시오. 공유 컨트롤러를 사용하면 턴 범위 이벤트가 턴 ID 없이 방출되지 않고, 오래된 turnEnd / turnCancel 호출이 더 새로운 활성 턴을 지우지 않으며, 출력 오디오 수명 주기 이벤트가 전화 통신, 회의, 브라우저 릴레이, 관리형 룸 핸드오프 및 네이티브 Talk 클라이언트 전반에서 일관되게 유지됩니다. 공개 API 형태는 다음과 같습니다.
브라우저 소유 WebRTC/공급자 WebSocket 세션은 talk.client.create를 사용합니다. 브라우저가 공급자 협상과 미디어 전송을 소유하고 Gateway가 자격 증명, 지침 및 도구 정책을 소유하기 때문입니다. talk.session.*는 Gateway 릴레이 실시간 처리, Gateway 릴레이 전사 및 관리형 룸 네이티브 STT/TTS 세션을 위한 공통 Gateway 관리 표면입니다. talk.provider / talk.providers 옆에 실시간 선택기를 배치하는 레거시 구성은 openclaw doctor --fix로 복구해야 합니다. 런타임 Talk는 음성/TTS 공급자 구성을 실시간 공급자 구성으로 재해석하지 않습니다. 지원되는 talk.session.create 조합은 의도적으로 제한되어 있습니다. 기존 talk.realtime.* / talk.transcription.* / talk.handoff.* 패밀리(모두 제거됨)에서 마이그레이션하는 사용자를 위한 메서드 매핑은 다음과 같습니다. 통합된 제어 어휘 역시 의도적으로 제한되어 있습니다. 이 기능을 작동시키기 위해 코어에 제공자 또는 플랫폼별 특수 사례를 도입하지 마십시오. 코어는 Talk 세션 의미 체계를 소유합니다. 제공자 Plugin은 벤더 세션 설정을 소유합니다. 음성 통화와 Google Meet은 전화/회의 어댑터를 소유합니다. 브라우저와 네이티브 앱은 기기 캡처/재생 UX를 소유합니다.

제거 일정

모든 코어 Plugin은 이미 마이그레이션되었습니다. 외부 Plugin은 다음 메이저 릴리스 전에 마이그레이션해야 합니다. Plugin에서 사용하는 표면 중 호환성 레코드의 만료가 가장 임박한 항목을 확인하려면 pnpm plugins:boundary-report를 실행하십시오.

일시적으로 경고 억제하기

이는 일시적인 우회 수단이며 영구적인 해결책이 아닙니다.

관련 문서