Plugin compatibility

기준일: 2026-07-26
공식 기준: Plugin compatibility

Plugin compatibility 문서는 OpenClaw 공식 문서(plugins/compatibility)를 한국어로 정리한 가이드입니다. Plugin compatibility contracts, deprecation metadata, and migration expectations 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Plugin compatibility contracts, deprecation metadata, and migration expectations

한국어 가이드 범위: plugins/compatibility 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Compatibility registry
• Deprecation policy
• Current compatibility areas
• WhatsApp inbound callback flat aliases
• WhatsApp inbound admission fields
• Plugin inspector package
• Maintainer acceptance lane
• Release notes

상세 내용

본문

OpenClaw keeps older plugin contracts wired through named compatibility adapters before removing them. This protects existing bundled and external plugins while the SDK, manifest, setup, config, and agent runtime contracts evolve.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Compatibility registry

Plugin compatibility contracts are tracked in the core registry at src/plugins/compat/registry.ts. Each record has:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• a stable compatibility code
• status: active, deprecated, removal-pending, or removed
• owner: sdk, config, setup, channel, provider, plugin-execution,
• introduction and deprecation dates when applicable
• an exact removal date once the owning maintainer approves it; an omitted
• replacement guidance
• docs, diagnostics, and tests that cover the old and new behavior

Deprecation policy

OpenClaw should not remove a documented plugin contract in the same release that introduces its replacement. Migration sequence:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Current compatibility areas

The July 2026 sweep removed the expired root SDK, manifest, provider, runtime, registry-flag, and plugin-owned web-config aliases. Doctor migrations remain separately tracked so supported upgrade paths can still repair old config.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• the August and September SDK subpath windows listed in the migration guide
• api.on("deactivate", ...) and api.on("subagent_spawning", ...) hook aliases
• memory-specific embedding registration and the beta.5 session-store bridge
• WhatsApp inbound callback aliases described below
• explicit channel target parsing and openclaw/plugin-sdk/messaging-targets
• embedded Pi agent aliases
• the shipped agent-harness SDK aliases, whose removal is pending a new

WhatsApp inbound callback flat aliases

WhatsApp runtime callbacks deliver WebInboundMessage: the canonical nested event, payload, quote, group, and platform contexts plus deprecated flat aliases for the shipped callback fields. New callback code should read the nested contexts. Code that constructs clean nested callback messages can use WebInboundCallbackMessage; compatibility listeners that still inject old flat test or plugin messages should use LegacyFlatWebInboundMessage or WebInboundMessageInput.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• id, timestamp, and isBatched move under event.
• body, mediaPath, mediaType, mediaFileName, mediaUrl, location,
• to, chatId, sender/self fields, sendComposing, reply(...), and
• replyTo* fields move under quote; group subject/participant/mention

WhatsApp inbound admission fields

Accepted WhatsApp callback messages carry admission, a public-safe envelope for the access-control decision that admitted the message. New callback code should read admission facts from msg.admission instead of the older top-level admission fields.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• from and conversationId move to admission.conversation.id.
• accountId moves to admission.accountId.
• accessControlPassed is a derived compatibility view of
• chatType moves to admission.conversation.kind.

Plugin inspector package

The plugin inspector should live outside the core OpenClaw repo as a separate package/repository backed by the versioned compatibility and manifest contracts. The day-one CLI should be:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw-plugin-inspector ./my-plugin

Maintainer acceptance lane

Use Crabbox-backed Blacksmith Testbox for the installable-package acceptance lane when validating the external inspector against OpenClaw plugin packages. Run it from a clean OpenClaw checkout after the package is built:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "pnpm install && pnpm build && npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/telegram --json"
pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json"
pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- <clawhub-plugin-dir> --json"

Release notes

Release notes should include upcoming plugin deprecations with target dates and links to migration docs, before a compatibility path moves to removal-pending or removed.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/compatibility
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw-plugin-inspector ./my-plugin

pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "pnpm install && pnpm build && npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/telegram --json"
pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- ./extensions/discord --json"
pnpm crabbox:run -- --provider blacksmith-testbox --timing-json --shell -- "npm exec --yes @openclaw/plugin-inspector@0.1.0 -- <clawhub-plugin-dir> --json"

관련 링크

• 공식 원문: plugins/compatibility
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.