Skip to main content

​
外掛程式 SDK 遷移

OpenClaw 已從寬泛的向後相容性層移動至具有聚焦、文件化匯入的現代外掛程式架構。若您的外掛程式是在新架構之前建立的，此指南可幫助您進行遷移。

​
正在變更的內容

舊外掛程式系統提供了兩個寬泛的表面，讓外掛程式可以從單一進入點匯入它們需要的任何內容：
  • openclaw/plugin-sdk/compat — 單一匯入，重新匯出幾十個幫手。它被引入以在建構新外掛程式架構時保持較舊掛鉤型外掛程式的執行。
  • openclaw/extension-api — 一個橋接器，給外掛程式直接存取主機側幫手（如內嵌代理程式執行器）的權限。
兩個表面現在都已棄用。它們在執行時仍有效，但新外掛程式不得使用它們，現有外掛程式應在下一個主要版本將其移除之前進行遷移。
向後相容性層將在未來主要版本中移除。仍然從這些表面匯入的外掛程式會在這種情況下中斷。

​
為什麼這改變了

舊方法造成了問題：
  • 啟動速度慢 — 匯入一個幫手會載入幾十個無關的模組
  • 循環相依性 — 寬泛的重新匯出使得易於建立匯入迴圈
  • 不清楚的 API 表面 — 無法判斷哪些匯出是穩定的 vs 內部的
現代外掛程式 SDK 修復了這個問題：每個匯入路徑（openclaw/plugin-sdk/<subpath>）是一個小的、自包含的模組，具有清楚的目的和文件化的約定。

​
如何遷移

1

找到已棄用的匯入

搜尋您的外掛程式以尋找來自任一已棄用表面的匯入：
grep -r "plugin-sdk/compat" my-plugin/
grep -r "openclaw/extension-api" my-plugin/
2

替換為聚焦的匯入

舊表面的每個匯出都對應到特定的現代匯入路徑：
// 之前（已棄用的向後相容性層）
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 { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });

// 之後（注入的執行時）
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
相同的模式適用於其他舊版橋接器幫手：
舊匯入現代等價物
resolveAgentDirapi.runtime.agent.resolveAgentDir
resolveAgentWorkspaceDirapi.runtime.agent.resolveAgentWorkspaceDir
resolveAgentIdentityapi.runtime.agent.resolveAgentIdentity
resolveThinkingDefaultapi.runtime.agent.resolveThinkingDefault
resolveAgentTimeoutMsapi.runtime.agent.resolveAgentTimeoutMs
ensureAgentWorkspaceapi.runtime.agent.ensureAgentWorkspace
工作階段存儲幫手api.runtime.agent.session.*
3

建置並測試

pnpm build
pnpm test -- my-plugin/

​
匯入路徑參考

匯入路徑目的主要匯出
plugin-sdk/plugin-entry規範外掛程式進入點幫手definePluginEntry
plugin-sdk/core頻道進入點定義、頻道構建器、基本型別defineChannelPluginEntry、createChatChannelPlugin
plugin-sdk/channel-setup設定精靈適配器createOptionalChannelSetupSurface
plugin-sdk/channel-pairingDM 配對基元createChannelPairingController
plugin-sdk/channel-reply-pipeline回應前綴 + 輸入連接createChannelReplyPipeline
plugin-sdk/channel-config-helpers設定適配器工廠createHybridChannelConfigAdapter
plugin-sdk/channel-config-schema設定結構描述構建器頻道設定結構描述型別
plugin-sdk/channel-policy群組/DM 政策解析resolveChannelGroupRequireMention
plugin-sdk/channel-lifecycle帳戶狀態追蹤createAccountStatusSink
plugin-sdk/channel-runtime執行時連接幫手頻道執行時工具
plugin-sdk/channel-send-result發送結果型別回應結果型別
plugin-sdk/runtime-store持久外掛程式儲存體createPluginRuntimeStore
plugin-sdk/allow-from允許清單格式化formatAllowFromLowercase
plugin-sdk/allowlist-resolution允許清單輸入對應mapAllowlistResolutionInputs
plugin-sdk/command-auth指令限制resolveControlCommandGate
plugin-sdk/secret-input祕密輸入解析祕密輸入幫手
plugin-sdk/webhook-ingressWebhook 要求幫手Webhook 目標工具
plugin-sdk/reply-payload訊息回應型別回應承載型別
plugin-sdk/provider-onboard提供商上線修補上線設定幫手
plugin-sdk/keyed-async-queue有序非同步佇列KeyedAsyncQueue
plugin-sdk/testing測試工具測試幫手和模擬
使用最窄的匯入來符合該工作。若您找不到匯出，檢查 src/plugin-sdk/ 的來源或在 Discord 中提問。

​
移除時間表

時機發生的情況
現在已棄用的表面發出執行時警告
下一個主要版本已棄用的表面將被移除；仍然使用它們的外掛程式將失敗
所有核心外掛程式都已遷移。外部外掛程式應在下一個主要版本前進行遷移。

​
暫時抑制警告

在遷移時設定這些環境變數： 
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
這是臨時避難所，不是永久解決方案。

​
相關主題