Plugin SDK 遷移

OpenClaw 已從廣泛的向後相容層，轉向採用聚焦且有文件記載匯入的現代 Plugin 架構。如果你的 Plugin 是在新架構之前建立，本指南可協助你遷移。

正在變更的內容

舊 Plugin 系統提供兩個完全開放的介面，讓 Plugin 可從單一進入點匯入任何所需項目：

openclaw/plugin-sdk/compat - 單一匯入，會重新匯出數十個輔助項目。它的引入是為了在新的 Plugin 架構建置期間，讓較舊的 hook 型 Plugin 繼續運作。
openclaw/plugin-sdk/infra-runtime - 廣泛的執行階段輔助 barrel，混合了系統事件、Heartbeat 狀態、傳遞佇列、fetch/proxy 輔助項目、檔案輔助項目、核准類型，以及無關的工具程式。
openclaw/plugin-sdk/config-runtime - 廣泛的設定相容性 barrel，在遷移期間仍保留已棄用的直接載入/寫入輔助項目。
openclaw/extension-api - 一個橋接層，讓 Plugin 能直接存取主機端輔助項目，例如嵌入式代理執行器。
api.registerEmbeddedExtensionFactory(...) - 已移除的 Pi 專用隨附 extension hook，可觀察嵌入式執行器事件，例如 tool_result。

這些廣泛匯入介面現在已棄用。它們在執行階段仍可運作，但新 Plugin 不得使用它們，現有 Plugin 也應在下一個主要版本移除它們之前完成遷移。Pi 專用的嵌入式 extension factory 註冊 API 已移除；請改用工具結果 middleware。 OpenClaw 不會在引入替代方案的同一項變更中，移除或重新解釋已記載的 Plugin 行為。破壞性合約變更必須先經過相容性 adapter、診斷、文件與棄用期間。這適用於 SDK 匯入、manifest 欄位、設定 API、hook，以及執行階段註冊行為。

向後相容層將在未來的主要版本中移除。仍從這些介面匯入的 Plugin 會在該情況發生時中斷。 Pi 專用的嵌入式 extension factory 註冊已不再載入。

為什麼變更

舊方法造成了一些問題：

啟動緩慢 - 匯入一個輔助項目會載入數十個無關模組
循環相依 - 廣泛的重新匯出讓建立匯入循環變得容易
API 介面不明確 - 無法判斷哪些匯出是穩定的，哪些是內部使用

現代 Plugin SDK 修正了這點：每個匯入路徑（openclaw/plugin-sdk/\<subpath\>）都是小型、自包含的模組，具備明確用途與已記載的合約。隨附通道的舊式提供者便利 seam 也已移除。通道品牌化的輔助 seam 是私有 mono-repo 捷徑，不是穩定的 Plugin 合約。請改用狹窄的通用 SDK 子路徑。在隨附的 Plugin 工作區內，將提供者擁有的輔助項目保留在該 Plugin 自己的 api.ts 或 runtime-api.ts 中。目前的隨附提供者範例：

Anthropic 將 Claude 專屬的串流輔助項目保留在自己的 api.ts / contract-api.ts seam 中
OpenAI 將提供者 builder、預設模型輔助項目，以及即時提供者 builder 保留在自己的 api.ts 中
OpenRouter 將提供者 builder 與 onboarding/設定輔助項目保留在自己的 api.ts 中

Talk 與即時語音遷移計畫

即時語音、電話、會議與瀏覽器 Talk 程式碼，正從介面本地的回合簿記，移至由 openclaw/plugin-sdk/realtime-voice 匯出的共用 Talk session controller。新的 controller 擁有通用 Talk 事件 envelope、作用中回合狀態、擷取狀態、輸出音訊狀態、近期事件歷史，以及過期回合拒絕。提供者 Plugin 應繼續擁有廠商專屬的即時 session；介面 Plugin 應繼續擁有擷取、播放、電話與會議的特殊處理。此 Talk 遷移刻意採用乾淨破壞式做法：

將共用 controller/執行階段 primitive 保留在 plugin-sdk/realtime-voice。
將隨附介面移至共用 controller：瀏覽器 relay、 managed-room handoff、voice-call 即時、voice-call 串流 STT、Google Meet 即時，以及原生 push-to-talk。
以最終的 talk.session.* 和 talk.client.* API 取代舊的 Talk RPC 家族。
在 Gateway hello-ok.features.events 中宣告單一即時 Talk 事件通道：talk.event。
刪除舊的即時 HTTP endpoint，以及任何請求時指令覆寫路徑。

除非是在實作低階 adapter 或測試 fixture，否則新程式碼不應直接呼叫 createTalkEventSequencer(...)。請優先使用共用 controller，讓回合範圍事件無法在沒有回合 id 的情況下發出，過期的 turnEnd / turnCancel 呼叫無法清除較新的作用中回合，並讓輸出音訊生命週期事件在電話、會議、瀏覽器 relay、managed-room handoff，以及原生 Talk 用戶端之間保持一致。目標公開 API 形狀如下：

// Gateway-owned Talk session 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 });

// Client-owned provider session 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 });

瀏覽器擁有的 WebRTC/provider-websocket session 使用 talk.client.create，因為瀏覽器擁有提供者 negotiation 與媒體傳輸，而 Gateway 擁有憑證、指令與工具政策。talk.session.* 是 gateway-relay 即時、gateway-relay 轉錄，以及 managed-room 原生 STT/TTS session 的通用 Gateway 管理介面。將即時選擇器放在 talk.provider / talk.providers 旁邊的舊式設定，應使用 openclaw doctor --fix 修復；執行階段 Talk 不會將語音/TTS 提供者設定重新解釋為即時提供者設定。支援的 talk.session.create 組合刻意保持精簡：

模式	傳輸	Brain	擁有者	備註
`realtime`	`gateway-relay`	`agent-consult`	Gateway	全雙工提供者音訊透過 Gateway 橋接；工具呼叫會透過 agent-consult 工具路由。
`transcription`	`gateway-relay`	`none`	Gateway	僅串流 STT；呼叫端傳送輸入音訊並接收 transcript 事件。
`stt-tts`	`managed-room`	`agent-consult`	原生/用戶端 room	Push-to-talk 與 walkie-talkie 風格 room，其中用戶端擁有擷取/播放，而 Gateway 擁有回合狀態。
`stt-tts`	`managed-room`	`direct-tools`	原生/用戶端 room	僅限管理員的 room 模式，供受信任的第一方介面直接執行 Gateway 工具動作。

已移除的方法對照表：

舊	新
`talk.realtime.session`	`talk.client.create`
`talk.realtime.toolCall`	`talk.client.toolCall`
`talk.realtime.relayAudio`	`talk.session.appendAudio`
`talk.realtime.relayCancel`	`talk.session.cancelOutput` 或 `talk.session.cancelTurn`
`talk.realtime.relayToolResult`	`talk.session.submitToolResult`
`talk.realtime.relayStop`	`talk.session.close`
`talk.transcription.session`	`talk.session.create({ mode: "transcription" })`
`talk.transcription.relayAudio`	`talk.session.appendAudio`
`talk.transcription.relayCancel`	`talk.session.cancelTurn`
`talk.transcription.relayStop`	`talk.session.close`
`talk.handoff.create`	`talk.session.create({ transport: "managed-room" })`
`talk.handoff.join`	`talk.session.join`
`talk.handoff.revoke`	`talk.session.close`

統一控制詞彙也刻意保持狹窄：

方法	適用於	合約
`talk.session.appendAudio`	`realtime/gateway-relay`, `transcription/gateway-relay`	將 base64 PCM 音訊 chunk 附加到同一 Gateway 連線擁有的提供者 session。
`talk.session.startTurn`	`stt-tts/managed-room`	啟動 managed-room 使用者回合。
`talk.session.endTurn`	`stt-tts/managed-room`	在過期回合驗證後結束作用中回合。
`talk.session.cancelTurn`	所有 Gateway 擁有的 session	取消某個回合的作用中擷取/提供者/代理/TTS 工作。
`talk.session.cancelOutput`	`realtime/gateway-relay`	停止助理音訊輸出，不一定會結束使用者回合。
`talk.session.submitToolResult`	`realtime/gateway-relay`	完成 relay 發出的提供者工具呼叫；傳入 `options.willContinue` 以產生暫時輸出，或傳入 `options.suppressResponse` 以在不產生另一個助理回應的情況下滿足該呼叫。
`talk.session.close`	所有統一 session	停止 relay session 或撤銷 managed-room 狀態，然後忘記統一 session id。

不要在核心中引入提供者或平台特殊案例來讓這項功能運作。核心負責 Talk 會話語意。提供者 Plugin 負責供應商會話設定。語音通話和 Google Meet 負責電話語音／會議配接器。瀏覽器和原生應用程式負責裝置擷取／播放使用者體驗。

相容性政策

對於外部 Plugin，相容性工作依照以下順序進行：

加入新合約
透過相容性配接器保留舊行為的連接
發出診斷或警告，指出舊路徑和替代項目
在測試中涵蓋兩條路徑
記錄棄用和遷移路徑
只在已公告的遷移窗口期之後移除，通常是在主要版本中

維護者可以使用 pnpm plugins:boundary-report 稽核目前的遷移佇列。使用 pnpm plugins:boundary-report:summary 取得精簡計數，使用 --owner <id> 檢視單一 Plugin 或相容性擁有者，並在 CI 閘道應於到期相容性記錄、跨擁有者保留 SDK 匯入，或未使用的保留 SDK 子路徑上失敗時，使用 pnpm plugins:boundary-report:ci。此報告會依移除日期分組已棄用的相容性記錄、計算本機程式碼／文件參照、顯示跨擁有者保留 SDK 匯入，並彙總私有記憶體主機 SDK 橋接，讓相容性清理保持明確，而不是仰賴臨時搜尋。保留 SDK 子路徑必須有追蹤的擁有者使用狀況；未使用的保留輔助程式匯出應從公開 SDK 移除。如果某個清單欄位仍被接受，Plugin 作者可以繼續使用，直到文件和診斷另有說明。新程式碼應偏好已記錄的替代項目，但既有 Plugin 不應在一般次要版本期間中斷。

如何遷移

遷移執行階段設定載入／寫入輔助程式

內建 Plugin 應停止直接呼叫 api.runtime.config.loadConfig() 和 api.runtime.config.writeConfigFile(...)。偏好使用已經傳入作用中呼叫路徑的設定。需要目前處理程序快照的長生命週期處理常式可以使用 api.runtime.config.current()。長生命週期代理工具應在 execute 內使用工具情境的 ctx.getRuntimeConfig()，讓在設定寫入前建立的工具仍能看到重新整理後的執行階段設定。設定寫入必須透過交易式輔助程式，並選擇寫入後政策：

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

當呼叫端知道變更需要乾淨地重新啟動 Gateway 時，使用 afterWrite: { mode: "restart", reason: "..." }；只有在呼叫端擁有後續處理，且刻意想抑制重新載入規劃器時，才使用 afterWrite: { mode: "none", reason: "..." }。變更結果包含型別化的 followUp 摘要，可供測試和記錄使用； Gateway 仍負責套用或排程重新啟動。 loadConfig 和 writeConfigFile 在遷移窗口期內仍作為外部 Plugin 的已棄用相容性輔助程式，並會以 runtime-config-load-write 相容性代碼警告一次。內建 Plugin 和儲存庫執行階段程式碼受到 pnpm check:deprecated-api-usage 和 pnpm check:no-runtime-action-load-config 中的掃描器護欄保護：新的生產 Plugin 使用會直接失敗、直接設定寫入會失敗、Gateway 伺服器方法必須使用請求執行階段快照、執行階段通道傳送／動作／用戶端輔助程式必須從其邊界接收設定，而長生命週期執行階段模組允許的環境 loadConfig() 呼叫數為零。新 Plugin 程式碼也應避免匯入廣泛的 openclaw/plugin-sdk/config-runtime 相容性桶。請使用符合工作需求的窄版 SDK 子路徑：

需求	匯入
設定型別，例如 `OpenClawConfig`	`openclaw/plugin-sdk/config-contracts`
已載入設定斷言和 Plugin 進入點設定查詢	`openclaw/plugin-sdk/plugin-config-runtime`
目前執行階段快照讀取	`openclaw/plugin-sdk/runtime-config-snapshot`
設定寫入	`openclaw/plugin-sdk/config-mutation`
會話儲存輔助程式	`openclaw/plugin-sdk/session-store-runtime`
Markdown 表格設定	`openclaw/plugin-sdk/markdown-table-runtime`
群組政策執行階段輔助程式	`openclaw/plugin-sdk/runtime-group-policy`
秘密輸入解析	`openclaw/plugin-sdk/secret-input-runtime`
模型／會話覆寫	`openclaw/plugin-sdk/model-session-runtime`

內建 Plugin 及其測試受到掃描器保護，避免使用廣泛桶，因此匯入和模擬會保持在所需行為的本機範圍內。廣泛桶仍為外部相容性存在，但新程式碼不應依賴它。

將 Pi 工具結果擴充遷移到中介軟體

內建 Plugin 必須以執行階段中立的中介軟體取代僅限 Pi 的 api.registerEmbeddedExtensionFactory(...) 工具結果處理常式。

// Pi and Codex runtime dynamic tools
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["pi", "codex"],
});

同時更新 Plugin 清單：

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

外部 Plugin 不能註冊工具結果中介軟體，因為它可以在模型看到高信任工具輸出前重寫該輸出。

將核准原生處理常式遷移到能力事實

具備核准能力的通道 Plugin 現在透過 approvalCapability.nativeRuntime 加上共享執行階段情境登錄檔公開原生核准行為。主要變更：

將 approvalCapability.handler.loadRuntime(...) 取代為 approvalCapability.nativeRuntime
將核准專用驗證／交付從舊版 plugin.auth / plugin.approvals 連接移至 approvalCapability
ChannelPlugin.approvals 已從公開通道 Plugin 合約移除；請將交付／原生／算繪欄位移至 approvalCapability
plugin.auth 僅保留給通道登入／登出流程；核心不再讀取其中的核准驗證鉤子
透過 openclaw/plugin-sdk/channel-runtime-context 註冊通道擁有的執行階段物件，例如用戶端、權杖或 Bolt 應用程式
不要從原生核准處理常式傳送 Plugin 擁有的重新路由通知；核心現在根據實際交付結果負責路由至其他位置的通知
將 channelRuntime 傳入 createChannelManager(...) 時，請提供真正的 createPluginRuntime().channel 表面。部分存根會被拒絕。

請參閱 /plugins/sdk-channel-plugins 了解目前的核准能力配置。

稽核 Windows 包裝器後援行為

如果你的 Plugin 使用 openclaw/plugin-sdk/windows-spawn，未解析的 Windows .cmd/.bat 包裝器現在會封閉失敗，除非你明確傳入 allowShellFallback: true。

// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });

// After
const program = applyWindowsSpawnProgramPolicy({
  candidate,
  // Only set this for trusted compatibility callers that intentionally
  // accept shell-mediated fallback.
  allowShellFallback: true,
});

如果你的呼叫端並非刻意依賴 Shell 後援，請不要設定 allowShellFallback，而是處理拋出的錯誤。

尋找已棄用的匯入

在你的 Plugin 中搜尋來自任一已棄用表面的匯入：

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/

替換為聚焦匯入

舊表面的每個匯出都對應至特定的現代匯入路徑：

// Before (deprecated backwards-compatibility layer)
import {
  createChannelReplyPipeline,
  createPluginRuntimeStore,
  resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";

// After (modern focused imports)
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";

對於主機端輔助程式，請使用注入的 Plugin 執行階段，而不是直接匯入：

// Before (deprecated extension-api bridge)
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });

// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });

相同模式也適用於其他舊版橋接輔助程式：

舊匯入	現代對應項
`resolveAgentDir`	`api.runtime.agent.resolveAgentDir`
`resolveAgentWorkspaceDir`	`api.runtime.agent.resolveAgentWorkspaceDir`
`resolveAgentIdentity`	`api.runtime.agent.resolveAgentIdentity`
`resolveThinkingDefault`	`api.runtime.agent.resolveThinkingDefault`
`resolveAgentTimeoutMs`	`api.runtime.agent.resolveAgentTimeoutMs`
`ensureAgentWorkspace`	`api.runtime.agent.ensureAgentWorkspace`
會話儲存輔助程式	`api.runtime.agent.session.*`

替換廣泛 infra-runtime 匯入

openclaw/plugin-sdk/infra-runtime 仍為外部相容性存在，但新程式碼應匯入它實際需要的聚焦輔助程式表面：

需求	匯入
系統事件佇列輔助程式	`openclaw/plugin-sdk/system-event-runtime`
Heartbeat 喚醒、事件和可見性輔助程式	`openclaw/plugin-sdk/heartbeat-runtime`
擱置交付佇列排空	`openclaw/plugin-sdk/delivery-queue-runtime`
通道活動遙測	`openclaw/plugin-sdk/channel-activity-runtime`
記憶體內去重快取	`openclaw/plugin-sdk/dedupe-runtime`
安全本機檔案／媒體路徑輔助程式	`openclaw/plugin-sdk/file-access-runtime`
可感知分派器的 fetch	`openclaw/plugin-sdk/runtime-fetch`
Proxy 和受防護的 fetch 輔助程式	`openclaw/plugin-sdk/fetch-runtime`
SSRF 分派器政策型別	`openclaw/plugin-sdk/ssrf-dispatcher`
核准請求／解析型別	`openclaw/plugin-sdk/approval-runtime`
核准回覆酬載和命令輔助程式	`openclaw/plugin-sdk/approval-reply-runtime`
錯誤格式化輔助程式	`openclaw/plugin-sdk/error-runtime`
傳輸就緒等待	`openclaw/plugin-sdk/transport-ready-runtime`
安全權杖輔助程式	`openclaw/plugin-sdk/secure-random-runtime`
有界非同步工作並行	`openclaw/plugin-sdk/concurrency-runtime`
數值強制轉換	`openclaw/plugin-sdk/number-runtime`
處理程序本機非同步鎖	`openclaw/plugin-sdk/async-lock-runtime`
檔案鎖	`openclaw/plugin-sdk/file-lock`

內建 Plugin 受到掃描器保護，避免使用 infra-runtime，因此儲存庫程式碼不能退回到廣泛桶。

遷移通道路由輔助程式

新的通道路由程式碼應使用 openclaw/plugin-sdk/channel-route。較舊的路由鍵和可比較目標名稱在遷移窗口期內仍作為相容性別名保留，但新 Plugin 應使用直接描述行為的路由名稱：

舊版輔助函式	現代輔助函式
`channelRouteIdentityKey(...)`	`channelRouteDedupeKey(...)`
`channelRouteKey(...)`	`channelRouteCompactKey(...)`
`ComparableChannelTarget`	`ChannelRouteParsedTarget`
`resolveComparableTargetForChannel(...)`	`resolveRouteTargetForChannel(...)`
`resolveComparableTargetForLoadedChannel(...)`	`resolveRouteTargetForLoadedChannel(...)`
`comparableChannelTargetsMatch(...)`	`channelRouteTargetsMatchExact(...)`
`comparableChannelTargetsShareRoute(...)`	`channelRouteTargetsShareConversation(...)`

現代路由輔助函式會在原生核准、回覆抑制、入站去重、 Cron 傳遞和工作階段路由中，一致地正規化 { channel, to, accountId, threadId }。如果你的 Plugin 擁有自訂目標文法，請使用 resolveChannelRouteTargetWithParser(...) 將該解析器調整為相同的路由目標合約。

建置與測試

pnpm build
pnpm test -- my-plugin/

匯入路徑參考

Common import path table

匯入路徑	用途	主要匯出
`plugin-sdk/plugin-entry`	標準 Plugin 進入點輔助函式	`definePluginEntry`
`plugin-sdk/core`	舊版通道進入點定義/建構器的總括重新匯出	`defineChannelPluginEntry`, `createChatChannelPlugin`
`plugin-sdk/config-schema`	根設定架構匯出	`OpenClawSchema`
`plugin-sdk/provider-entry`	單一提供者進入點輔助函式	`defineSingleProviderPluginEntry`
`plugin-sdk/channel-core`	聚焦的通道進入點定義與建構器	`defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`
`plugin-sdk/setup`	共用設定精靈輔助函式	允許清單提示、設定狀態建構器
`plugin-sdk/setup-runtime`	設定期間的執行階段輔助函式	可安全匯入的設定修補轉接器、查閱備註輔助函式、`promptResolvedAllowFrom`、`splitSetupEntries`、委派式設定代理
`plugin-sdk/setup-adapter-runtime`	已棄用的設定轉接器別名	使用 `plugin-sdk/setup-runtime`
`plugin-sdk/setup-tools`	設定工具輔助函式	`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`
`plugin-sdk/account-core`	多帳號輔助函式	帳號清單/設定/動作閘門輔助函式
`plugin-sdk/account-id`	account-id 輔助函式	`DEFAULT_ACCOUNT_ID`、account-id 正規化
`plugin-sdk/account-resolution`	帳號查閱輔助函式	帳號查閱 + 預設後援輔助函式
`plugin-sdk/account-helpers`	範圍較窄的帳號輔助函式	帳號清單/帳號動作輔助函式
`plugin-sdk/channel-setup`	設定精靈轉接器	`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries`
`plugin-sdk/channel-pairing`	DM 配對原語	`createChannelPairingController`
`plugin-sdk/channel-reply-pipeline`	回覆前綴、輸入中狀態與來源交付接線	`createChannelReplyPipeline`, `resolveChannelSourceReplyDeliveryMode`
`plugin-sdk/channel-config-helpers`	設定轉接器工廠與 DM 存取輔助函式	`createHybridChannelConfigAdapter`, `resolveChannelDmAccess`, `resolveChannelDmAllowFrom`, `resolveChannelDmPolicy`, `normalizeChannelDmPolicy`, `normalizeLegacyDmAliases`
`plugin-sdk/channel-config-schema`	設定架構建構器	僅限共用通道設定架構原語與泛型建構器
`plugin-sdk/bundled-channel-config-schema`	內建設定架構	僅限 OpenClaw 維護的內建 plugins；新的 plugins 必須定義 Plugin 本機架構
`plugin-sdk/channel-config-schema-legacy`	已棄用的內建設定架構	僅作為相容性別名；對維護中的內建 plugins 使用 `plugin-sdk/bundled-channel-config-schema`
`plugin-sdk/telegram-command-config`	Telegram 命令設定輔助函式	命令名稱正規化、描述修剪、重複/衝突驗證
`plugin-sdk/channel-policy`	群組/DM 政策解析	`resolveChannelGroupRequireMention`
`plugin-sdk/channel-lifecycle`	帳號狀態與草稿串流生命週期輔助函式	`createAccountStatusSink`、草稿預覽最終化輔助函式
`plugin-sdk/inbound-envelope`	入站信封輔助函式	共用路由 + 信封建構器輔助函式
`plugin-sdk/inbound-reply-dispatch`	入站回覆輔助函式	共用記錄並分派輔助函式
`plugin-sdk/messaging-targets`	訊息目標剖析	目標剖析/比對輔助函式
`plugin-sdk/outbound-media`	出站媒體輔助函式	共用出站媒體載入
`plugin-sdk/outbound-send-deps`	出站傳送相依性輔助函式	不匯入完整出站執行階段的輕量 `resolveOutboundSendDep` 查閱
`plugin-sdk/outbound-runtime`	出站執行階段輔助函式	出站交付、身分/傳送委派、工作階段、格式化與酬載規劃輔助函式
`plugin-sdk/thread-bindings-runtime`	執行緒繫結輔助函式	執行緒繫結生命週期與轉接器輔助函式
`plugin-sdk/agent-media-payload`	舊版媒體酬載輔助函式	舊版欄位版面配置的代理媒體酬載建構器
`plugin-sdk/channel-runtime`	已棄用的相容性墊片	僅限舊版通道執行階段公用程式
`plugin-sdk/channel-send-result`	傳送結果型別	回覆結果型別
`plugin-sdk/runtime-store`	持久化 Plugin 儲存空間	`createPluginRuntimeStore`
`plugin-sdk/runtime`	廣泛執行階段輔助函式	執行階段/記錄/備份/Plugin 安裝輔助函式
`plugin-sdk/runtime-env`	範圍較窄的執行階段環境輔助函式	記錄器/執行階段環境、逾時、重試與退避輔助函式
`plugin-sdk/plugin-runtime`	共用 Plugin 執行階段輔助函式	Plugin 命令/hooks/http/互動式輔助函式
`plugin-sdk/hook-runtime`	Hook 管線輔助函式	共用 Webhook/內部 hook 管線輔助函式
`plugin-sdk/lazy-runtime`	延遲執行階段輔助函式	`createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface`
`plugin-sdk/process-runtime`	程序輔助函式	共用 exec 輔助函式
`plugin-sdk/cli-runtime`	CLI 執行階段輔助函式	命令格式化、等待、版本輔助函式
`plugin-sdk/gateway-runtime`	Gateway 輔助函式	Gateway 用戶端、事件迴圈就緒啟動輔助函式，以及通道狀態修補輔助函式
`plugin-sdk/config-runtime`	已棄用的設定相容性墊片	偏好使用 `config-contracts`, `plugin-config-runtime`, `runtime-config-snapshot` 與 `config-mutation`
`plugin-sdk/telegram-command-config`	Telegram 命令輔助函式	內建 Telegram 合約介面無法使用時，後援穩定的 Telegram 命令驗證輔助函式
`plugin-sdk/approval-runtime`	核准提示輔助函式	Exec/Plugin 核准酬載、核准能力/設定檔輔助函式、原生核准路由/執行階段輔助函式，以及結構化核准顯示路徑格式化
`plugin-sdk/approval-auth-runtime`	核准驗證輔助函式	核准者解析、同聊天室動作驗證
`plugin-sdk/approval-client-runtime`	核准用戶端輔助函式	原生 exec 核准設定檔/篩選器輔助函式
`plugin-sdk/approval-delivery-runtime`	核准交付輔助函式	原生核准能力/交付轉接器
`plugin-sdk/approval-gateway-runtime`	核准 Gateway 輔助函式	共用核准 Gateway 解析輔助函式
`plugin-sdk/approval-handler-adapter-runtime`	核准轉接器輔助函式	用於熱門通道進入點的輕量原生核准轉接器載入輔助函式
`plugin-sdk/approval-handler-runtime`	核准處理器輔助函式	較廣泛的核准處理器執行階段輔助函式；足夠時偏好較窄的轉接器/Gateway 接縫
`plugin-sdk/approval-native-runtime`	核准目標輔助函式	原生核准目標/帳號繫結輔助函式
`plugin-sdk/approval-reply-runtime`	核准回覆輔助函式	Exec/Plugin 核准回覆酬載輔助函式
`plugin-sdk/channel-runtime-context`	通道執行階段內容輔助函式	泛型通道執行階段內容註冊/取得/監看輔助函式
`plugin-sdk/security-runtime`	安全性輔助函式	共用信任、DM 閘控、根目錄有界檔案/路徑輔助函式、外部內容與密鑰收集輔助函式
`plugin-sdk/ssrf-policy`	SSRF 政策輔助函式	主機允許清單與私有網路政策輔助函式
`plugin-sdk/ssrf-runtime`	SSRF 執行階段輔助函式	固定的分派器、受保護的 fetch、SSRF 政策輔助函式
`plugin-sdk/system-event-runtime`	系統事件輔助函式	`enqueueSystemEvent`, `peekSystemEventEntries`
`plugin-sdk/heartbeat-runtime`	Heartbeat 輔助函式	Heartbeat 喚醒、事件與可見性輔助函式
`plugin-sdk/delivery-queue-runtime`	交付佇列輔助函式	`drainPendingDeliveries`
`plugin-sdk/channel-activity-runtime`	通道活動輔助函式	`recordChannelActivity`
`plugin-sdk/dedupe-runtime`	去重輔助函式	記憶體內去重快取
`plugin-sdk/file-access-runtime`	檔案存取輔助函式	安全本機檔案/媒體路徑輔助函式
`plugin-sdk/transport-ready-runtime`	傳輸就緒輔助函式	`waitForTransportReady`
`plugin-sdk/collection-runtime`	有界快取輔助函式	`pruneMapToMaxSize`
`plugin-sdk/diagnostic-runtime`	診斷閘控輔助函式	`isDiagnosticFlagEnabled`, `isDiagnosticsEnabled`
`plugin-sdk/error-runtime`	錯誤格式化輔助函式	`formatUncaughtError`, `isApprovalNotFoundError`、錯誤圖形輔助函式
`plugin-sdk/fetch-runtime`	包裝 fetch/代理輔助函式	`resolveFetch`、代理輔助函式、EnvHttpProxyAgent 選項輔助函式
`plugin-sdk/host-runtime`	主機正規化輔助函式	`normalizeHostname`, `normalizeScpRemoteHost`
`plugin-sdk/retry-runtime`	重試輔助函式	`RetryConfig`, `retryAsync`、政策執行器
`plugin-sdk/allow-from`	允許清單格式化	`formatAllowFromLowercase`
`plugin-sdk/allowlist-resolution`	允許清單輸入對應	`mapAllowlistResolutionInputs`
`plugin-sdk/command-auth`	命令閘控與命令介面輔助函式	`resolveControlCommandGate`、傳送者授權輔助函式、命令登錄輔助函式，包含動態引數選單格式化
`plugin-sdk/command-status`	命令狀態/說明呈現器	`buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage`
`plugin-sdk/secret-input`	密鑰輸入剖析	密鑰輸入輔助函式
`plugin-sdk/webhook-ingress`	Webhook 請求輔助函式	Webhook 目標公用程式
`plugin-sdk/webhook-request-guards`	Webhook 主體保護輔助函式	請求主體讀取/限制輔助函式
`plugin-sdk/reply-runtime`	共用回覆執行階段	入站分派、Heartbeat、回覆規劃器、分塊
`plugin-sdk/reply-dispatch-runtime`	範圍較窄的回覆分派輔助函式	最終化、提供者分派與對話標籤輔助函式
`plugin-sdk/reply-history`	回覆歷史記錄輔助函式	`buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled`
`plugin-sdk/reply-reference`	回覆參照規劃	`createReplyReferencePlanner`
`plugin-sdk/reply-chunking`	回覆分塊輔助函式	文字/markdown 分塊輔助函式
`plugin-sdk/session-store-runtime`	工作階段儲存區輔助函式	儲存區路徑 + updated-at 輔助函式
`plugin-sdk/state-paths`	狀態路徑輔助函式	狀態與 OAuth 目錄輔助函式
`plugin-sdk/routing`	路由/工作階段鍵輔助函式	`resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`、工作階段鍵正規化輔助函式
`plugin-sdk/status-helpers`	通道狀態輔助函式	通道/帳號狀態摘要建構器、執行階段狀態預設值、議題中繼資料輔助函式
`plugin-sdk/target-resolver-runtime`	目標解析器輔助函式	共用目標解析器輔助函式
`plugin-sdk/string-normalization-runtime`	字串正規化輔助函式	slug/字串正規化輔助函式
`plugin-sdk/request-url`	請求 URL 輔助函式	從類似請求的輸入中擷取字串 URL
`plugin-sdk/run-command`	計時命令輔助函式	具備正規化 stdout/stderr 的計時命令執行器
`plugin-sdk/param-readers`	參數讀取器	常用工具/CLI 參數讀取器
`plugin-sdk/tool-payload`	工具承載資料擷取	從工具結果物件擷取正規化承載資料
`plugin-sdk/tool-send`	工具傳送擷取	從工具引數擷取標準傳送目標欄位
`plugin-sdk/temp-path`	暫存路徑輔助工具	共用暫存下載路徑輔助工具
`plugin-sdk/logging-core`	記錄輔助工具	子系統記錄器與遮蔽輔助工具
`plugin-sdk/markdown-table-runtime`	Markdown 表格輔助工具	Markdown 表格模式輔助工具
`plugin-sdk/reply-payload`	訊息回覆型別	回覆承載資料型別
`plugin-sdk/provider-setup`	精選本機/自架提供者設定輔助工具	自架提供者探索/設定輔助工具
`plugin-sdk/self-hosted-provider-setup`	聚焦於 OpenAI 相容自架提供者的設定輔助工具	相同的自架提供者探索/設定輔助工具
`plugin-sdk/provider-auth-runtime`	提供者執行階段驗證輔助工具	執行階段 API 金鑰解析輔助工具
`plugin-sdk/provider-auth-api-key`	提供者 API 金鑰設定輔助工具	API 金鑰初始設定/設定檔寫入輔助工具
`plugin-sdk/provider-auth-result`	提供者驗證結果輔助工具	標準 OAuth 驗證結果建構器
`plugin-sdk/provider-selection-runtime`	提供者選取輔助工具	已設定或自動提供者選取，以及原始提供者設定合併
`plugin-sdk/provider-env-vars`	提供者環境變數輔助工具	提供者驗證環境變數查詢輔助工具
`plugin-sdk/provider-model-shared`	共用提供者模型/重播輔助工具	`ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共用重播政策建構器、提供者端點輔助工具，以及模型 ID 正規化輔助工具
`plugin-sdk/provider-catalog-shared`	共用提供者目錄輔助工具	`findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `buildManifestModelProviderConfig`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat`
`plugin-sdk/provider-onboard`	提供者初始設定修補	初始設定設定輔助工具
`plugin-sdk/provider-http`	提供者 HTTP 輔助工具	通用提供者 HTTP/端點能力輔助工具，包括音訊轉錄 multipart 表單輔助工具
`plugin-sdk/provider-web-fetch`	提供者 Web 擷取輔助工具	Web 擷取提供者註冊/快取輔助工具
`plugin-sdk/provider-web-search-config-contract`	提供者 Web 搜尋設定輔助工具	供不需要 Plugin 啟用接線的提供者使用的窄範圍 Web 搜尋設定/憑證輔助工具
`plugin-sdk/provider-web-search-contract`	提供者 Web 搜尋合約輔助工具	窄範圍 Web 搜尋設定/憑證合約輔助工具，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及具範圍的憑證設定器/取得器
`plugin-sdk/provider-web-search`	提供者 Web 搜尋輔助工具	Web 搜尋提供者註冊/快取/執行階段輔助工具
`plugin-sdk/provider-tools`	提供者工具/結構描述相容性輔助工具	`ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`，以及 Gemini 結構描述清理與診斷
`plugin-sdk/provider-usage`	提供者使用量輔助工具	`fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`，以及其他提供者使用量輔助工具
`plugin-sdk/provider-stream`	提供者串流包裝器輔助工具	`ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、串流包裝器型別，以及共用 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包裝器輔助工具
`plugin-sdk/provider-transport-runtime`	提供者傳輸輔助工具	原生提供者傳輸輔助工具，例如受防護的擷取、傳輸訊息轉換，以及可寫入的傳輸事件串流
`plugin-sdk/keyed-async-queue`	有序非同步佇列	`KeyedAsyncQueue`
`plugin-sdk/media-runtime`	共用媒體輔助工具	媒體擷取/轉換/儲存輔助工具、由 ffprobe 支援的影片尺寸探測，以及媒體承載資料建構器
`plugin-sdk/media-generation-runtime`	共用媒體生成輔助工具	圖像/影片/音樂生成的共用容錯移轉輔助工具、候選項選取，以及缺少模型訊息
`plugin-sdk/media-understanding`	媒體理解輔助工具	媒體理解提供者型別，以及面向提供者的圖像/音訊輔助匯出
`plugin-sdk/text-runtime`	已棄用的寬範圍文字相容性匯出	使用 `string-coerce-runtime`, `text-chunking`, `text-utility-runtime`，以及 `logging-core`
`plugin-sdk/text-chunking`	文字分塊輔助工具	對外文字分塊輔助工具
`plugin-sdk/speech`	語音輔助工具	語音提供者型別，以及面向提供者的指令、登錄、驗證輔助工具與 OpenAI 相容 TTS 建構器
`plugin-sdk/speech-core`	共用語音核心	語音提供者型別、登錄、指令、正規化
`plugin-sdk/realtime-transcription`	即時轉錄輔助工具	提供者型別、登錄輔助工具，以及共用 WebSocket 工作階段輔助工具
`plugin-sdk/realtime-voice`	即時語音輔助工具	提供者型別、登錄/解析輔助工具、橋接工作階段輔助工具、共用代理程式回話佇列、文字稿/事件健康狀態、回音抑制，以及快速情境諮詢輔助工具
`plugin-sdk/image-generation`	圖像生成輔助工具	圖像生成提供者型別，以及圖像資產/資料 URL 輔助工具與 OpenAI 相容圖像提供者建構器
`plugin-sdk/image-generation-core`	共用圖像生成核心	圖像生成型別、容錯移轉、驗證，以及登錄輔助工具
`plugin-sdk/music-generation`	音樂生成輔助工具	音樂生成提供者/請求/結果型別
`plugin-sdk/music-generation-core`	共用音樂生成核心	音樂生成型別、容錯移轉輔助工具、提供者查詢，以及模型參照解析
`plugin-sdk/video-generation`	影片生成輔助工具	影片生成提供者/請求/結果型別
`plugin-sdk/video-generation-core`	共用影片生成核心	影片生成型別、容錯移轉輔助工具、提供者查詢，以及模型參照解析
`plugin-sdk/interactive-runtime`	互動式回覆輔助工具	互動式回覆承載資料正規化/縮減
`plugin-sdk/channel-config-primitives`	頻道設定基元	窄範圍頻道設定結構描述基元
`plugin-sdk/channel-config-writes`	頻道設定寫入輔助工具	頻道設定寫入授權輔助工具
`plugin-sdk/channel-plugin-common`	共用頻道前置匯出	共用頻道 Plugin 前置匯出
`plugin-sdk/channel-status`	頻道狀態輔助工具	共用頻道狀態快照/摘要輔助工具
`plugin-sdk/allowlist-config-edit`	允許清單設定輔助工具	允許清單設定編輯/讀取輔助工具
`plugin-sdk/group-access`	群組存取輔助工具	共用群組存取決策輔助工具
`plugin-sdk/direct-dm`	直接 DM 輔助工具	共用直接 DM 驗證/防護輔助工具
`plugin-sdk/extension-shared`	共用擴充功能輔助工具	被動頻道/狀態與環境代理輔助基元
`plugin-sdk/webhook-targets`	Webhook 目標輔助工具	Webhook 目標登錄與路由安裝輔助工具
`plugin-sdk/webhook-path`	已棄用的 Webhook 路徑別名	使用 `plugin-sdk/webhook-ingress`
`plugin-sdk/web-media`	共用 Web 媒體輔助工具	遠端/本機媒體載入輔助工具
`plugin-sdk/zod`	已棄用的 Zod 相容性重新匯出	直接從 `zod` 匯入 `zod`
`plugin-sdk/memory-core`	捆綁的 memory-core 輔助工具	記憶體管理器/設定/檔案/CLI 輔助介面
`plugin-sdk/memory-core-engine-runtime`	記憶體引擎執行階段 Facade	記憶體索引/搜尋執行階段 Facade
`plugin-sdk/memory-core-host-engine-foundation`	記憶體主機基礎引擎	記憶體主機基礎引擎匯出
`plugin-sdk/memory-core-host-engine-embeddings`	記憶體主機嵌入引擎	記憶體嵌入合約、登錄存取、本機提供者，以及通用批次/遠端輔助工具；具體遠端提供者位於其所屬 Plugin 中
`plugin-sdk/memory-core-host-engine-qmd`	記憶體主機 QMD 引擎	記憶體主機 QMD 引擎匯出
`plugin-sdk/memory-core-host-engine-storage`	記憶體主機儲存引擎	記憶體主機儲存引擎匯出
`plugin-sdk/memory-core-host-multimodal`	記憶體主機多模態輔助工具	記憶體主機多模態輔助工具
`plugin-sdk/memory-core-host-query`	記憶體主機查詢輔助工具	記憶體主機查詢輔助工具
`plugin-sdk/memory-core-host-secret`	記憶體主機密鑰輔助工具	記憶體主機密鑰輔助工具
`plugin-sdk/memory-core-host-events`	已棄用的記憶體事件別名	使用 `plugin-sdk/memory-host-events`
`plugin-sdk/memory-core-host-status`	記憶體主機狀態輔助工具	記憶體主機狀態輔助工具
`plugin-sdk/memory-core-host-runtime-cli`	記憶體主機 CLI 執行階段	記憶體主機 CLI 執行階段輔助工具
`plugin-sdk/memory-core-host-runtime-core`	記憶體主機核心執行階段	記憶體主機核心執行階段輔助工具
`plugin-sdk/memory-core-host-runtime-files`	記憶體主機檔案/執行階段輔助工具	記憶體主機檔案/執行階段輔助工具
`plugin-sdk/memory-host-core`	記憶體主機核心執行階段別名	供應商中立的記憶體主機核心執行階段輔助工具別名
`plugin-sdk/memory-host-events`	記憶體主機事件日誌別名	供應商中立的記憶體主機事件日誌輔助工具別名
`plugin-sdk/memory-host-files`	已棄用的記憶體檔案/執行階段別名	使用 `plugin-sdk/memory-core-host-runtime-files`
`plugin-sdk/memory-host-markdown`	受管理 Markdown 輔助工具	供記憶體相鄰 Plugin 使用的共用受管理 Markdown 輔助工具
`plugin-sdk/memory-host-search`	Active Memory 搜尋 Facade	延遲載入的 Active Memory 搜尋管理器執行階段 Facade
`plugin-sdk/memory-host-status`	已棄用的記憶體主機狀態別名	使用 `plugin-sdk/memory-core-host-status`
`plugin-sdk/testing`	測試工具	儲存庫本機已棄用的相容性 barrel；請使用聚焦的儲存庫本機測試子路徑，例如 `plugin-sdk/plugin-test-runtime`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/channel-target-testing`, `plugin-sdk/test-env`，以及 `plugin-sdk/test-fixtures`

這張表刻意只列出常見遷移子集，而不是完整的 SDK 介面範圍。編譯器進入點清單位於 scripts/lib/plugin-sdk-entrypoints.json；套件匯出會從公開子集產生。保留給內建 Plugin 的輔助接縫已從公開 SDK 匯出對應表中移除，除了明確文件化的相容性外觀，例如保留給已發布 @openclaw/discord@2026.3.13 套件的已棄用 plugin-sdk/discord shim。擁有者專屬的輔助工具位於所屬的 Plugin 套件內；共用的主機行為應透過通用 SDK 合約移動，例如 plugin-sdk/gateway-runtime、plugin-sdk/security-runtime 和 plugin-sdk/plugin-config-runtime。使用符合工作需求的最窄匯入。如果找不到匯出，請檢查 src/plugin-sdk/ 的原始碼，或詢問維護者應該由哪個通用合約擁有它。

作用中的棄用項目

適用於整個 Plugin SDK、供應商合約、執行階段介面範圍和 manifest 的較窄棄用項目。每一項目前仍可運作，但會在未來的主要版本中移除。每個項目下方的條目會將舊 API 對應到其標準替代項目。

command-auth 說明建構器 → command-status

舊版（openclaw/plugin-sdk/command-auth）：buildCommandsMessage、 buildCommandsMessagePaginated、buildHelpMessage。新版（openclaw/plugin-sdk/command-status）：相同簽章、相同匯出，只是從更窄的子路徑匯入。command-auth 會將它們重新匯出為相容性 stub。

// Before
import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth";

// After
import { buildHelpMessage } from "openclaw/plugin-sdk/command-status";

提及閘控輔助工具 → resolveInboundMentionDecision

舊版：來自 openclaw/plugin-sdk/channel-inbound 或 openclaw/plugin-sdk/channel-mention-gating 的 resolveInboundMentionRequirement({ facts, policy }) 和 shouldDropInboundForMention(...)。新版：resolveInboundMentionDecision({ facts, policy }) - 會傳回單一決策物件，而不是兩個分開的呼叫。下游頻道 Plugin（Slack、Discord、Matrix、MS Teams）都已經切換完成。

頻道執行階段 shim 和頻道動作輔助工具

openclaw/plugin-sdk/channel-runtime 是給較舊頻道 Plugin 使用的相容性 shim。新程式碼不要匯入它；請使用 openclaw/plugin-sdk/channel-runtime-context 來註冊執行階段物件。openclaw/plugin-sdk/channel-actions 中的 channelActions* 輔助工具會和原始「actions」頻道匯出一併棄用。請改為透過語意化的 presentation 介面範圍公開能力，也就是頻道 Plugin 宣告它們會呈現什麼（卡片、按鈕、選取器），而不是它們接受哪些原始動作名稱。

網頁搜尋供應商 tool() 輔助工具 → Plugin 上的 createTool()

舊版：來自 openclaw/plugin-sdk/provider-web-search 的 tool() 工廠。新版：直接在供應商 Plugin 上實作 createTool(...)。 OpenClaw 不再需要 SDK 輔助工具來註冊工具包裝器。

純文字頻道信封 → BodyForAgent

舊版：formatInboundEnvelope(...)（以及 ChannelMessageForAgent.channelEnvelope），用來從傳入頻道訊息建構扁平的純文字 prompt 信封。新版：BodyForAgent 加上結構化使用者情境區塊。頻道 Plugin 會將路由中繼資料（對話串、主題、回覆對象、回應）附加為型別化欄位，而不是把它們串接到 prompt 字串中。 formatAgentEnvelope(...) 輔助工具仍支援合成的面向助理信封，但傳入純文字信封正逐步淘汰。受影響區域：inbound_claim、message_received，以及任何後處理 channelEnvelope 文字的自訂頻道 Plugin。

供應商探索型別 → 供應商目錄型別

四個探索型別別名現在只是目錄時代型別的薄包裝：

舊別名	新型別
`ProviderDiscoveryOrder`	`ProviderCatalogOrder`
`ProviderDiscoveryContext`	`ProviderCatalogContext`
`ProviderDiscoveryResult`	`ProviderCatalogResult`
`ProviderPluginDiscovery`	`ProviderPluginCatalog`

另有舊版 ProviderCapabilities 靜態集合，供應商 Plugin 應使用明確的供應商 hook，例如 buildReplayPolicy、 normalizeToolSchemas 和 wrapStreamFn，而不是靜態物件。

思考政策 hook → resolveThinkingProfile

舊版（ProviderThinkingPolicy 上的三個獨立 hook）： isBinaryThinking(ctx)、supportsXHighThinking(ctx) 和 resolveDefaultThinkingLevel(ctx)。新版：單一 resolveThinkingProfile(ctx)，會傳回 ProviderThinkingProfile，內含標準 id、選用 label 和排序等級清單。OpenClaw 會依 profile 排名自動降級過時的已儲存值。實作一個 hook，而不是三個。舊版 hook 會在棄用窗口期間繼續運作，但不會與 profile 結果組合。

外部 OAuth 供應商備援 → contracts.externalAuthProviders

舊版：實作 resolveExternalOAuthProfiles(...)，但未在 Plugin manifest 中宣告供應商。新版：在 Plugin manifest 中宣告 contracts.externalAuthProviders 並且實作 resolveExternalAuthProfiles(...)。舊的「auth fallback」路徑會在執行階段發出警告，並將被移除。

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

供應商環境變數查找 → setup.providers[].envVars

舊版 manifest 欄位：providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }。新版：將相同的環境變數查找鏡像到 manifest 上的 setup.providers[].envVars。這會把設定/狀態環境中繼資料整合到同一處，並避免只是為了回答環境變數查找就啟動 Plugin 執行階段。providerAuthEnvVars 會透過相容性轉接器維持支援，直到棄用窗口關閉為止。

記憶 Plugin 註冊 → registerMemoryCapability

舊版：三個獨立呼叫： api.registerMemoryPromptSection(...)、 api.registerMemoryFlushPlan(...)、 api.registerMemoryRuntime(...)。新版：在記憶狀態 API 上的一個呼叫： registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })。相同 slot，單一註冊呼叫。加法式記憶輔助工具（registerMemoryPromptSupplement、registerMemoryCorpusSupplement、 registerMemoryEmbeddingProvider）不受影響。

子代理工作階段訊息型別已重新命名

兩個仍從 src/plugins/runtime/types.ts 匯出的舊版型別別名：

舊版	新版
`SubagentReadSessionParams`	`SubagentGetSessionMessagesParams`
`SubagentReadSessionResult`	`SubagentGetSessionMessagesResult`

執行階段方法 readSession 已棄用，請改用 getSessionMessages。相同簽章；舊方法會呼叫到新方法。

runtime.tasks.flow → runtime.tasks.managedFlows

舊版：runtime.tasks.flow（單數）會傳回即時 task-flow 存取器。新版：runtime.tasks.managedFlows 會為從流程建立、更新、取消或執行子工作的 Plugin 保留受管理的 TaskFlow 變更執行階段。當 Plugin 只需要基於 DTO 的讀取時，請使用 runtime.tasks.flows。

// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);

內嵌擴充工廠 → 代理工具結果 middleware

上方「如何遷移 → 將 Pi 工具結果擴充遷移到 middleware」已有說明。為求完整，也列在此處：已移除的 Pi 專用 api.registerEmbeddedExtensionFactory(...) 路徑，會由 api.registerAgentToolResultMiddleware(...) 取代，並在 contracts.agentToolResultMiddleware 中提供明確的執行階段清單。

OpenClawSchemaType 別名 → OpenClawConfig

從 openclaw/plugin-sdk 重新匯出的 OpenClawSchemaType 現在是 OpenClawConfig 的一行別名。請偏好使用標準名稱。

// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";

擴充層級的棄用項目（位於 extensions/ 底下的內建頻道/供應商 Plugin 內）會在各自的 api.ts 和 runtime-api.ts barrel 中追蹤。它們不影響第三方 Plugin 合約，因此未列於此處。如果你直接使用內建 Plugin 的本機 barrel，升級前請先閱讀該 barrel 中的棄用註解。

移除時程

時間	會發生什麼
現在	已棄用的介面範圍會發出執行階段警告
下一個主要版本	已棄用的介面範圍將被移除；仍使用它們的 Plugin 會失敗

所有核心 Plugin 都已完成遷移。外部 Plugin 應在下一個主要版本前完成遷移。

暫時抑制警告

在進行遷移時設定這些環境變數：

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run

這是暫時的逃生口，不是永久解法。

Documentation Index

​正在變更的內容

​為什麼變更

​Talk 與即時語音遷移計畫

​相容性政策

​如何遷移

​匯入路徑參考

​作用中的棄用項目

​移除時程

​暫時抑制警告

​相關

正在變更的內容

為什麼變更

Talk 與即時語音遷移計畫

相容性政策

如何遷移

匯入路徑參考

作用中的棄用項目

移除時程

暫時抑制警告

相關