外掛 SDK 遷移

OpenClaw 已將廣泛的向後相容層替換為現代化的外掛架構， 此架構由小型且聚焦的匯入項目組成。如果你的外掛早於該項 變更，本指南可協助它遷移至目前的合約。

變更內容

過去有數個過度開放的匯入介面，讓外掛能從單一進入點存取 幾乎所有內容：

• openclaw/plugin-sdk 和 openclaw/plugin-sdk/compat - 在建置聚焦的 SDK 期間，曾重新匯出數十個輔助工具。這兩個根路徑現已移除； 請改為匯入文件記載的子路徑。
• openclaw/plugin-sdk/infra-runtime - 混合了系統事件、心跳偵測狀態、 傳遞佇列、擷取／Proxy 輔助工具、檔案輔助工具、核准類型及 不相關公用程式的廣泛彙總匯出。
• openclaw/plugin-sdk/config-runtime - 廣泛的設定彙總匯出，僅為後續的 相容期間而保留；直接的執行階段載入／寫入輔助工具已移除。
• openclaw/extension-api - 已移除的橋接層，先前讓外掛可直接 存取主機端的輔助工具，例如內嵌代理程式執行器。
• api.registerEmbeddedExtensionFactory(...) - 已移除且僅供內嵌執行器使用的 掛鉤，先前用於觀察內嵌執行器事件，例如 tool_result。請改用代理程式 工具結果中介軟體（請參閱將內嵌工具結果擴充功能遷移至中介軟體）。

根 SDK、相容性彙總匯出、擴充功能橋接層及內嵌擴充功能工廠 均已移除。infra-runtime 和 config-runtime 僅為各自另行記錄的後續 期間而保留；新外掛應使用聚焦的子路徑。

OpenClaw 不會在引入替代方案的同一項變更中，移除或重新解讀文件記載的 外掛行為。破壞合約的變更會先經過相容性配接器、診斷、文件及 淘汰期間。這適用於 SDK 匯入、資訊清單欄位、設定 API、掛鉤及執行階段 註冊行為。

原因

• 啟動緩慢 - 匯入一個輔助工具會載入數十個不相關的模組。
• 循環相依性 - 廣泛的重新匯出使匯入循環很容易 產生。
• API 介面不明確 - 無法分辨穩定匯出項目與內部匯出項目。

每個 openclaw/plugin-sdk/<subpath> 現在都是小型、獨立且 具有文件化合約的模組。

綁定通道的舊版供應商便利介面也已移除 - 帶有通道品牌的輔助工具捷徑是私有單一儲存庫的便利功能，而非 穩定的外掛合約。請改用範圍狹窄的通用 SDK 子路徑。在 綁定的外掛工作區內，請將供應商擁有的輔助工具保留在該外掛自身的 api.ts 或 runtime-api.ts 中：

• Anthropic 將 Claude 專用的串流輔助工具保留在自己的 api.ts / contract-api.ts 介面中。
• OpenAI 將供應商建構器、預設模型輔助工具及即時供應商 建構器保留在自己的 api.ts 中。
• OpenRouter 將供應商建構器及新手引導／設定輔助工具保留在自己的 api.ts 中。

相容性政策

外部外掛的相容性工作依照以下順序進行：

1. 新增合約。
2. 透過相容性配接器維持舊有行為的連接。
3. 發出診斷或警告，指出舊路徑及其替代方案。
4. 在測試中涵蓋兩條路徑。
5. 記錄淘汰及遷移路徑。
6. 僅在公告的遷移期間結束後移除，通常會在主要 版本中進行。

如果資訊清單欄位仍被接受，請持續使用，直到文件及 診斷另有說明為止。新程式碼應優先使用文件記載的替代方案； 現有外掛不應在一般次要版本發布期間中斷。

已發布通道的設定相容性

透過 2026.7.1 發布的 Slack、Discord、Signal 和 Microsoft Teams 套件，會從 openclaw/plugin-sdk/bundled-channel-config-schema 匯入通道專用的設定結構描述。 已發布的 Slack 和 Discord 套件也會從 openclaw/plugin-sdk/setup-runtime 匯入 createLegacyCompatChannelDmPolicy 和 promptLegacyChannelAllowFromForAccount。

這些匯出項目仍以已淘汰的執行階段相容性配接器形式提供。 新外掛及重新發布的外掛應在本機擁有其設定結構描述及設定政策， 並使用 channel-config-schema 和 setup-runtime 的通用基礎功能。 只有在支援的最低已發布套件版本不再匯入這些項目後， 才能移除相容性匯出項目。

通道設定輸入欄位的相容性

ChannelSetupInput 現在只會永久保留跨通道設定封套的型別。 通道專用欄位仍在已淘汰的相容性層中保有型別，讓現有外部外掛 在外掛作者將這些欄位移入外掛本機設定輸入型別時仍可編譯。

OpenClaw 不發布主要版本。2026-07-22 的登錄檔掃描檢查了 426 個已發布的樹外通道外掛，並移除 21 個沒有讀取端的欄位。 保留的 22 個欄位各自都有已知的已發布讀取端。只要沒有已發布外掛 讀取某個欄位，就會立即刪除該欄位；隨著外掛作者遷移至外掛本機 設定輸入型別，保留集合會持續縮小。

同一次掃描也移除了 23 個沒有已發布相依項目的舊版未宣告配接器 提升索引鍵。目前保留六個常用索引鍵及僅供設定使用的 rooms 索引鍵。隨著已發布外掛宣告 singleAccountKeysToMove，該集合也會持續縮小。

共用型別沒有索引簽章。外掛擁有的索引鍵仍可存在於執行階段 輸入物件中；請在外掛本機的交集型別中宣告它們，或透過擁有該索引鍵的 外掛設定結構描述縮小其型別。

舊版未宣告配接器提升層採用相同的讀取端驅動 政策。請宣告 singleAccountKeysToMove；若外掛不需要額外的提升索引鍵， 也應包含空陣列，以便逐一淘汰共用備援中的索引鍵。

驗證讀取端

1. 使用每個 nextCursor 分頁瀏覽 https://clawhub.ai/api/v1/packages?family=code-plugin&limit=100，並保留其 categories 包含 channels 的套件。
2. 從 npm search --json --searchlimit=1000 "openclaw channel plugin" 新增 npm 候選項目。從 GitHub 中針對 openclaw/plugin-sdk/channel-setup、openclaw/plugin-sdk/setup 和 openclaw/plugin-sdk/core 的程式碼搜尋新增僅原始碼候選項目。
3. 解析每個候選項目的最新已發布版本。執行 npm pack <package>@<version> --json --pack-destination <temp-dir>、解壓縮套件，並檢查已出貨的 dist JavaScript 和宣告，尋找直接或解構式欄位讀取。如果套件沒有 npm 版本，請下載 ClawHub 成品。
4. 記錄套件、版本、欄位或提升索引鍵，以及相符的檔案。只有在沒有任何已發布外掛成品讀取該欄位或索引鍵時，才能刪除它。請讓保留欄位及索引鍵清單旁程式碼註解中的讀取端名稱與掃描結果保持同步。

這僅是原始碼／型別相容性記錄。它沒有執行階段配接器或 相容性登錄項目，因為執行階段設定輸入物件及設定 行為並未變更。

使用 pnpm plugins:boundary-report 稽核目前的遷移佇列：

pnpm plugins:boundary-report:ci 會啟用全部三個失敗旗標。已淘汰的 記錄通常具有明確的 removeAfter 日期，而非含糊的「下一個 主要版本」。擁有者尚未核准日期的記錄不會包含 removeAfter，會顯示為 no-date，且永遠不符合移除資格。 報告會依日期將已淘汰記錄分組、計算本機程式碼／文件參照、 顯示跨擁有者的保留 SDK 匯入，並摘要私有的 記憶體主機 SDK 橋接層。保留的 SDK 子路徑必須有追蹤記錄的擁有者使用情形； 未使用的保留匯出項目應從公開 SDK 中移除。

媒體舊版投影

media-legacy-projection 相容性記錄涵蓋舊有的平行 媒體欄位、酬載建構器、掛鉤中繼資料別名及媒體範本 名稱。其核准的 removeAfter 日期為 2026-10-01（以事實優先的替代方案 出貨後兩個發布週期）。屆時要移除它，還必須完成沒有問題的 已發布外掛成品掃描；請在該日期前完成遷移。

針對通道輸入，請將單數／複數的 MediaPath、MediaUrl、 MediaType、MediaPaths、MediaUrls、MediaTypes、 MediaTranscribedIndexes、MediaWorkspaceDir 和 MediaStaged 替換為有序 事實：

 const media = toInboundMediaFacts([  { path: saved.path, url: nativeUrl, contentType: saved.contentType, messageId },]); const ctx = finalizeInboundContext({ Body: caption, media });

在 inbound_claim 和 message_received 掛鉤中使用 event.media。如果遠端 媒體尚未在本機暫存，請使用 event.originalMedia 進行身分識別／診斷， 並等待 event.media；event.mediaStagingPending 可區分該 狀態。請勿從 event.metadata 讀取已淘汰的單數／複數屬性。

針對命令列介面的媒體模型，請將 {{MediaPath}}、{{MediaUrl}}、{{MediaType}} 和 {{MediaDir}} 替換為 {{AttachmentPath}}、{{AttachmentUrl}}、 {{AttachmentContentType}} 和 {{AttachmentDir}}。當附件位置很重要時， 請使用 {{AttachmentIndex}}。

針對本機媒體讀取政策，請從 openclaw/plugin-sdk/media-local-roots 匯入 getAgentScopedMediaLocalRoots(...) 或 getAgentScopedMediaLocalRootsForSources(...)。 openclaw/plugin-sdk/agent-media-payload 外觀介面及其 buildAgentMediaPayload(...) 投影均已淘汰。

如何遷移

await api.runtime.config.mutateConfigFile({  afterWrite: { mode: "auto" },  mutate(draft) {    draft.plugins ??= {};  },});

// OpenClaw 執行階段工具與 Codex 執行階段動態工具（結果可能會被// 轉換）。Codex 原生工具結果也會被轉送以供觀察，// 但其轉換後的輸出絕不會傳達給模型：Codex// PostToolUse 鉤子合約無法取代原生工具回應。api.registerAgentToolResultMiddleware(async (event) => {  return compactToolResult(event);}, {  runtimes: ["openclaw", "codex"],});

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"]  }}

// 之前const program = applyWindowsSpawnProgramPolicy({ candidate }); // 之後const program = applyWindowsSpawnProgramPolicy({  candidate,  // 僅為刻意接受由 shell 媒介後援的受信任相容性呼叫端  // 設定此項目。  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/

// 之前（已淘汰的向後相容層）import {  createChannelReplyPipeline,  createPluginRuntimeStore,  resolveControlCommandGate,} from "openclaw/plugin-sdk/compat"; // 之後（現代的聚焦匯入）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";

// 之前（已淘汰的 extension-api 橋接）import { runEmbeddedAgent } from "openclaw/extension-api";const result = await runEmbeddedAgent({ sessionId, prompt }); // 之後（注入的執行階段）const result = await api.runtime.agent.runEmbeddedAgent({ sessionId, prompt });

pnpm buildpnpm test my-plugin/

匯入路徑參考

公開套件匯出對應表是可匯入 SDK 子路徑的唯一事實來源。請使用 SDK 概覽 所連結的主題式 SDK 指南，並優先採用範圍最窄且有文件記載的公開子路徑。 scripts/lib/plugin-sdk-entrypoints.json 中的編譯器清單也包含用於 建置內建外掛的私有本機項目；它們出現在該處並不表示其為公開套件匯出。

此表是常見的遷移子集，而非完整的 SDK 介面。編譯器進入點清單位於 scripts/lib/plugin-sdk-entrypoints.json；套件匯出則由公開子集產生。

為內建外掛保留的輔助接縫已從公開 SDK 匯出對應表中淘汰，但明確記載的相容性 facade 除外，例如保留給仍 直接匯入已發布 @openclaw/discord 套件之外部外掛的 已淘汰 plugin-sdk/discord 相容層。擁有者專用 輔助函式位於所屬外掛套件內；共用主機行為則透過 plugin-sdk/gateway-runtime、 plugin-sdk/security-runtime 與注入的外掛 API 等通用 SDK 合約傳遞。

請使用符合工作需求且範圍最窄的匯入。如果找不到匯出， 請檢查 src/plugin-sdk/ 的原始碼，或詢問維護者應由哪個通用 合約負責。

已移除的相容性介面

2026 年 7 月的清理移除了根 SDK 與 compat 桶狀匯出、擴充功能 API 橋接、已到期的 SDK 子路徑別名、未使用的 SDK 子路徑，以及僅供內建使用之 SDK 模組的公開 匯出。僅供內建使用的模組仍可由其儲存庫擁有者透過私有本機 建置對應使用；但無法從已發布的套件匯入。

程序全域 API 提供者發布

registerApiProvider(...) 和 unregisterApiProviders(...) 已從 openclaw/plugin-sdk/llm 移除。它們會將 API 傳輸發布至程序全域 狀態，導致由生命週期擁有的模型執行階段之後必須將其複製到每個準備完成的 登錄檔中。

提供者外掛應透過 api.registerProvider(...) 註冊文字推論提供者。 建立 ApiRegistry 的主機擁有程式碼與測試，應直接在該登錄檔上 註冊，使提供者擁有權與拆卸作業都維持在準備完成之執行階段的範圍內。

私有測試桶狀匯出

openclaw/plugin-sdk/testing 僅供儲存庫本機使用，且不包含在發布的套件 成品中，因此已在其 2026-07-28 removeAfter 日期前移除。儲存庫 測試會使用 plugin-sdk/plugin-test-runtime、 plugin-sdk/channel-test-helpers、plugin-sdk/channel-target-testing、 plugin-sdk/test-env 和 plugin-sdk/test-fixtures 等聚焦子路徑。

遷移參考

這些對應關係涵蓋已於 2026 年 7 月移除的介面，以及較晚時程中仍在進行的 淘汰項目。對應關係是遷移指引，不代表舊 介面仍然可用；請查閱相容性登錄檔與移除 時程表以瞭解目前狀態。

// 之前import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; // 之後import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

// 之前api.on("deactivate", async (event, ctx) => {  await stopPluginService(ctx);}); // 之後api.on("gateway_stop", async (event, ctx) => {  await stopPluginService(ctx);});

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

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

// 之前const flow = api.runtime.tasks.flow.fromToolContext(ctx);// 之後const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

// 之前import type { OpenClawSchemaType } from "openclaw/plugin-sdk";// 之後import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";

Talk 與即時語音遷移

即時語音、電話、會議及瀏覽器 Talk 程式碼共用一個由 openclaw/plugin-sdk/realtime-voice 匯出的 Talk 工作階段控制器。此 控制器擁有共用的 Talk 事件封裝、作用中輪次狀態、擷取 狀態、輸出音訊狀態、近期事件歷程及過期輪次拒絕機制。 供應商外掛擁有供應商專屬的即時工作階段。瀏覽器會議外掛 使用 openclaw/plugin-sdk/meeting-runtime 處理工作階段、瀏覽器、音訊、節點主機、 代理程式諮詢及語音通話機制，接著實作 MeetingPlatformAdapter 以處理 URL 規則、DOM 指令碼、手動動作對應、字幕、建立及撥入 方案。平台 REST API、OAuth、成品、選擇器及連線名稱仍保留在 外掛中。瀏覽器權限方案會收到所要求的會議 URL，讓各 平台僅授予其確切支援的來源。工作階段執行階段也必須在確認瀏覽器離開後， 正規化平台專屬的即時健康狀態； 歷史逐字稿欄位可以保留，但離開後字幕與音訊就緒狀態 不得繼續保持作用中。

所有內建介面都在共用控制器上執行：瀏覽器轉送、 受管理房間移交、語音通話即時處理、語音通話串流 STT、Google Meet 即時處理及原生按下通話。閘道會在 hello-ok.features.events 中公布一個即時 Talk 事件 頻道：talk.event。

除非正在實作低階介接器或測試固定資料，否則新程式碼不應直接呼叫 createTalkEventSequencer(...)。請使用共用控制器，確保 輪次範圍事件無法在沒有輪次 ID 的情況下發出、過期的 turnEnd / turnCancel 呼叫無法清除較新的作用中輪次，且輸出音訊 生命週期事件在電話、會議、瀏覽器轉送、 受管理房間移交及原生 Talk 用戶端之間保持一致。

公開 API 形式：

// 閘道擁有的 Talk 工作階段 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 }); // 用戶端擁有的供應商工作階段 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 });await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

由瀏覽器擁有的 WebRTC／供應商 WebSocket 工作階段使用 talk.client.create， 因為瀏覽器擁有供應商協商與媒體傳輸，而 閘道擁有認證資訊、指示及工具政策。talk.session.* 是 由閘道管理的共用介面，用於閘道轉送即時處理、閘道轉送 轉錄，以及受管理房間的原生 STT/TTS 工作階段。

將即時選擇器與 talk.provider / talk.providers 並列的舊版設定，應使用 openclaw doctor --fix 修復；Talk 執行階段 不會將語音／TTS 供應商設定重新解讀為即時供應商設定。

支援的 talk.session.create 組合刻意維持精簡：

供從較舊的 talk.realtime.* / talk.transcription.* / talk.handoff.* 系列（均已移除）遷移的讀者參考的方法對照表：

統一控制詞彙也刻意限制在精簡範圍內：

請勿為了讓此功能運作而在核心中加入供應商或平台特例。 核心擁有 Talk 工作階段語意。供應商外掛擁有供應商工作階段設定。 語音通話與 Google Meet 擁有電話／會議介接器。瀏覽器與原生 應用程式擁有裝置擷取／播放使用者體驗。

移除時程

下列其餘公開 SDK 子路徑具有由登錄檔支援的移除時程。 7 月 30 日的資料列已在維護者提前授權的清理後移除： 未使用的子路徑已刪除、較早的相容性別名已刪除，且 僅供隨附模組使用的模組已降級為私有本機建置對應。

所有核心外掛皆已完成遷移。外部外掛應在 下一個主要版本之前遷移。執行 pnpm plugins:boundary-report，即可查看你的外掛所使用介面中 哪些相容性記錄最接近到期。

暫時抑制警告

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway runOPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

這是暫時的緊急應變機制，並非永久解決方案。

相關內容

• 開始使用 - 建置你的第一個外掛
• SDK 概觀 - 完整的子路徑匯入參考
• 頻道外掛 - 建置頻道外掛
• 供應商外掛 - 建置供應商外掛
• 外掛內部機制 - 深入探討架構
• 外掛資訊清單 - 資訊清單結構描述參考