外掛相容性

​

相容性註冊表

• 穩定的相容性代碼
• 狀態：active、deprecated、removal-pending 或 removed
• 擁有者：sdk、config、setup、channel、provider、plugin-execution、 agent-runtime 或 core
• 適用時的引入與棄用日期
• 替代方案指引
• 涵蓋舊行為與新行為的文件、診斷與測試

​

棄用政策

1. 新增新合約。
2. 透過具名相容性轉接器保留舊行為接線。
3. 在外掛作者可以採取行動時發出診斷或警告。
4. 記載替代方案與時程。
5. 測試舊路徑與新路徑。
6. 等待已公告的遷移窗口期結束。
7. 只有在明確核准破壞性發行時才移除。

​

目前的相容性區域

• 舊版廣泛 SDK 匯入，例如 openclaw/plugin-sdk/compat
• 舊版僅 hook 外掛形狀與 before_agent_start
• 舊版 api.on("deactivate", ...) 清理 hook 名稱，供外掛遷移到 gateway_stop
• 舊版 activate(api) 外掛進入點，供外掛遷移到 register(api)
• 舊版 SDK 別名，例如 openclaw/extension-api、 openclaw/plugin-sdk/channel-runtime、openclaw/plugin-sdk/command-auth 狀態建構器、openclaw/plugin-sdk/test-utils（由聚焦的 openclaw/plugin-sdk/* 測試子路徑取代），以及 ClawdbotConfig / OpenClawSchemaType 型別別名
• 內建外掛允許清單與啟用行為
• 舊版提供者/通道環境變數 manifest 中繼資料
• 舊版提供者外掛 hook 與型別別名，供提供者移至明確的目錄、驗證、思考、重播與傳輸 hook
• 舊版執行階段別名，例如 api.runtime.taskFlow、 api.runtime.subagent.getSession、api.runtime.stt，以及已棄用的 api.runtime.config.loadConfig() / api.runtime.config.writeConfigFile(...)
• WhatsApp WebInboundMessage 扁平回呼欄位（見下方）
• WhatsApp WebInboundMessage 頂層准入欄位（見下方）
• 舊版記憶體外掛分離註冊，供記憶體外掛移至 registerMemoryCapability
• 舊版記憶體專用 embedding 提供者註冊，供 embedding 提供者移至 api.registerEmbeddingProvider(...) 和 contracts.embeddingProviders
• 舊版通道 SDK 輔助工具，用於原生訊息 schema、提及門控、傳入 envelope 格式化，以及核准能力巢狀結構
• 舊版通道路由鍵與可比較目標輔助別名，供外掛移至 openclaw/plugin-sdk/channel-route
• 由 manifest 貢獻所有權取代的啟用提示
• setup-api 執行階段後援，供設定描述子移至冷路徑 setup.requiresRuntime: false 中繼資料
• 提供者 discovery hook，供提供者目錄 hook 移至 catalog.run(...)
• 通道 showConfigured / showInSetup 中繼資料，供通道套件移至 openclaw.channel.exposure
• 舊版 runtime-policy 設定鍵，doctor 會將操作者遷移到 agentRuntime
• 產生的內建通道設定中繼資料後援，直到 registry-first channelConfigs 中繼資料落地
• 持久化外掛註冊表停用與安裝遷移環境旗標，修復流程會將操作者遷移到 openclaw plugins registry --refresh 和 openclaw doctor --fix
• 舊版外掛所擁有的網頁搜尋、網頁擷取與 x_search 設定路徑，doctor 會將它們遷移到 plugins.entries.<plugin>.config
• 舊版 plugins.installs 作者設定與內建外掛載入路徑別名，安裝中繼資料會移入狀態管理的外掛帳本

​

WhatsApp 傳入回呼扁平別名

• id、timestamp 和 isBatched 移到 event 之下。
• body、mediaPath、mediaType、mediaFileName、mediaUrl、location 和 untrustedStructuredContext 移到 payload 之下。
• to、chatId、寄件者/自身欄位、sendComposing、reply(...) 和 sendMedia(...) 移到 platform 之下。
• replyTo* 欄位移到 quote 之下；群組主旨/參與者/提及欄位移到 group 之下。

​

WhatsApp 傳入准入欄位

• from 和 conversationId 移到 admission.conversation.id。
• accountId 移到 admission.accountId。
• accessControlPassed 是 admission.ingress.decision === "allow" 的衍生相容性檢視；在已攜帶 admission 的訊息上，寫入舊版布林值不會重寫 ingress graph。
• chatType 移到 admission.conversation.kind。

​

外掛檢查器套件

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"

​

發行說明