外掛 SDK 遷移

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJjb21tYW5kLWF1dGgg6Kqq5piO5bu65qeL5ZmoIC0 command-status"> 舊版（openclaw/plugin-sdk/command-auth）：buildCommandsMessage、 buildCommandsMessagePaginated、buildHelpMessage。

新版（openclaw/plugin-sdk/command-status）：簽章相同、匯出相同， 只是改從範圍較窄的子路徑匯入。command-auth 會將它們重新匯出為相容性虛設介面。

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

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLmj5Dlj4rplpjploDovJTliqnlt6XlhbcgLQ resolveInboundMentionDecision"> 舊版：來自 openclaw/plugin-sdk/channel-inbound 或 openclaw/plugin-sdk/channel-mention-gating 的 resolveMentionGating(params) 與 resolveMentionGatingWithBypass(params)。

新版：resolveInboundMentionDecision({ facts, policy })——使用單一決策 物件取代兩種分離的呼叫形式。

Discord、iMessage、Matrix、MS Teams、QQ Bot、Signal、 Telegram、WhatsApp 與 Zalo 均已採用。Slack 自有的 app_mention 事件模型不使用 此輔助工具。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLntrLpoIHmkJzlsIvmj5DkvpvogIUgdG9vbCgpIOi8lOWKqeW3peWFtyAt 外掛上的 createTool()"> 舊版：來自 openclaw/plugin-sdk/provider-web-search 的 tool() 工廠函式。

新版：直接在提供者外掛上實作 createTool(...)。 OpenClaw 不再需要使用 SDK 輔助工具註冊工具包裝函式。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLntJTmloflrZfpoLvpgZPlsIHoo50gLQ BodyForAgent"> 舊版：使用 api.runtime.channel.reply.formatInboundEnvelope(...)（以及傳入訊息物件上的 channelEnvelope 欄位），從傳入的頻道訊息建構扁平的 純文字提示封裝。

新版：BodyForAgent 加上結構化使用者情境區塊。頻道 外掛會將路由中繼資料（討論串、主題、回覆對象、回應）附加為 具型別欄位，而不是將其串接至提示字串中。 formatAgentEnvelope(...) 輔助工具仍支援合成的 助理端封裝，但傳入的純文字封裝正逐步淘汰。

受影響範圍：inbound_claim、message_received，以及任何曾對 舊封裝文字進行後處理的自訂頻道外掛。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJkZWFjdGl2YXRlIOmJpOm7niAt gateway_stop"> 舊版：api.on("deactivate", handler)。

新版：api.on("gateway_stop", handler)。關閉清理 合約相同；只有鉤點名稱改變。

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

deactivate 仍會以已棄用的相容性別名形式連接，直到 2026-08-16 之後移除。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJzdWJhZ2VudF9zcGF3bmluZyDpiaTpu54gLQ 核心討論串繫結"> 舊版：api.on("subagent_spawning", handler)，會傳回 threadBindingReady 或 deliveryOrigin。

新版：讓核心透過頻道工作階段繫結配接器準備 thread: true 子代理程式繫結。 僅將 api.on("subagent_spawned", handler) 用於啟動後觀察。

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

subagent_spawning、PluginHookSubagentSpawningEvent、 PluginHookSubagentSpawningResult 與 SubagentLifecycleHookRunner.runSubagentSpawning(...) 僅會在外部外掛遷移期間保留為 已棄用的相容性介面，並於 2026-08-30 之後移除。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLmgJ3ogIPljp_liYfpiaTpu54gLQ resolveThinkingProfile"> 舊版（ProviderThinkingPolicy 上三個獨立鉤點）： isBinaryThinking(ctx)、supportsXHighThinking(ctx) 與 resolveDefaultThinkingLevel(ctx)。

新版：單一 resolveThinkingProfile(ctx)，會傳回 ProviderThinkingProfile，其中包含標準的 id、選用的 label，以及 已排序的層級清單。OpenClaw 會依設定檔排名自動 降級過時的已儲存值。

情境包含 provider、modelId、選用的已合併 reasoning， 以及選用的已合併模型 compat 資訊。提供者外掛只有在已設定的 要求合約支援時，才能使用這些目錄資訊公開模型專屬的設定檔。

請實作一個鉤點，而不是三個。舊版鉤點在棄用期間仍可運作， 但不會與設定檔結果組合。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLlpJbpg6jpqZforYnmj5DkvpvogIUgLQ contracts.externalAuthProviders"> 舊版：實作外部驗證鉤點，但未在外掛資訊清單中宣告提供者。

新版：在外掛資訊清單中宣告 contracts.externalAuthProviders 並且實作 resolveExternalAuthProfiles(...)。

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

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLmj5DkvpvogIXnkrDlooPorormlbjmn6XoqaIgLQ setup.providers[].envVars"> 舊版資訊清單欄位：providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }。

新版：將相同的環境變數查詢鏡像至資訊清單上的 setup.providers[].envVars。 這會將設定／狀態環境中繼資料整合至單一位置， 並避免只為回應環境變數查詢而啟動外掛執行階段。

在棄用期結束前，providerAuthEnvVars 仍會透過相容性配接器獲得支援。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLoqJjmhrbpq5TlpJbmjpvoqLvlhoogLQ registerMemoryCapability"> 舊版：三個獨立呼叫——api.registerMemoryPromptSection(...)、 api.registerMemoryFlushPlan(...)、api.registerMemoryRuntime(...)。

新版：記憶體狀態 API 上的一個呼叫—— registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })。

欄位相同，只需一次註冊呼叫。累加式提示與語料庫輔助工具 （registerMemoryPromptSupplement、registerMemoryCorpusSupplement） 不受影響。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLljp_lp4vpoLvpgZPlgrPpgIHntZDmnpwgLQ OutboundDeliveryResult"> 舊版：透過 ChannelSendRawResult 傳回 { ok, messageId, error }， 並使用 createRawChannelSendResultAdapter(...) 將其正規化。

新版：傳回 OutboundDeliveryResult 欄位，並使用 createAttachedChannelResultAdapter(...) 附加頻道。傳送失敗時應擲回例外， 而不是傳回錯誤字串。原始結果型別會保留至下一個外掛 SDK 主要版本。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJydW50aW1lLnRhc2tzLmZsb3cgLQ runtime.tasks.managedFlows"> 舊版：runtime.tasks.flow（單數）會傳回即時的工作流程 存取器。

新版：runtime.tasks.managedFlows 保留受管理的 TaskFlow 變更 執行階段，供會從流程建立、更新、取消或執行子任務的外掛使用。 當外掛只需要以 DTO 為基礎的讀取時，請使用 runtime.tasks.flows。

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

於 2026-07-26 後移除。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSLlhafltYzmk7TlhYXlpZfku7blt6Xlu6AgLQ 代理工具結果中介軟體"> 上方的如何遷移已涵蓋此項。為求完整，仍列於此處： 已移除且僅供內嵌執行器使用的 api.registerEmbeddedExtensionFactory(...) 路徑，已由 api.registerAgentToolResultMiddleware(...) 取代，並在 contracts.agentToolResultMiddleware 中明確列出執行階段清單。

OPENCLAW_DOCS_MARKER:accordionOpen:IHRpdGxlPSJPcGVuQ2xhd1NjaGVtYVR5cGUg5Yil5ZCNIC0 OpenClawConfig"> 從 openclaw/plugin-sdk 重新匯出的 OpenClawSchemaType，現在是 OpenClawConfig 的單行別名。請優先使用標準名稱。

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