Plugin SDK 遷移

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

# 有哪些變更

舊的 Plugin 系統提供了兩個開放範圍很大的介面，讓 Plugin 能從單一入口點匯入 任何需要的內容：

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

這些廣泛的匯入介面現在已棄用。它們在執行階段仍可運作， 但新的 Plugin 不得使用它們，既有 Plugin 也應在下一個主要版本移除它們之前 完成遷移。Pi-only embedded extension factory 註冊 API 已移除；請改用 tool-result middleware。

OpenClaw 不會在導入替代方案的同一項變更中，移除或重新解讀已記載於文件的 Plugin 行為。 破壞性合約變更必須先經過相容性配接器、診斷、文件，以及棄用期間。 這適用於 SDK 匯入、manifest 欄位、設定 API、hook，以及執行階段 註冊行為。

# 為什麼要做這項變更

舊方法造成了問題：

• 啟動緩慢 - 匯入一個輔助工具會載入數十個不相關的模組
• 循環依賴 - 廣泛的重新匯出很容易建立匯入循環
• API 介面不清楚 - 無法判斷哪些匯出是穩定的，哪些屬於內部使用

現代 Plugin SDK 解決了這個問題：每個匯入路徑（openclaw/plugin-sdk/\<subpath\>） 都是小型、自包含的模組，具備明確用途與文件化合約。

Bundled channels 的舊版 provider 便利 seam 也已移除。 Channel-branded 輔助 seam 是私有 mono-repo 捷徑，而不是穩定的 Plugin 合約。請改用範圍狹窄的通用 SDK 子路徑。在 bundled Plugin 工作區內，將 provider-owned 輔助工具保留在該 Plugin 自己的 api.ts 或 runtime-api.ts 中。

目前的 bundled provider 範例：

• Anthropic 將 Claude-specific 串流輔助工具保留在自己的 api.ts / contract-api.ts seam 中
• OpenAI 將 provider 建構器、預設模型輔助工具，以及 realtime provider 建構器保留在自己的 api.ts 中
• OpenRouter 將 provider 建構器與 onboarding/config 輔助工具保留在自己的 api.ts 中

# Talk 和即時語音遷移計畫

即時語音、電話、會議，以及瀏覽器 Talk 程式碼正在從 各介面本地的 turn bookkeeping，移轉到由 openclaw/plugin-sdk/realtime-voice 匯出的共享 Talk 工作階段控制器。新的控制器負責共同的 Talk 事件信封、active turn 狀態、擷取狀態、輸出音訊狀態、近期 事件歷史，以及 stale-turn 拒絕。Provider Plugin 應繼續負責 vendor-specific 即時工作階段；介面 Plugin 應繼續負責擷取、 播放、電話與會議的特殊處理。

此 Talk 遷移刻意採取乾淨破壞式變更：

1. 將共享控制器/執行階段基本元件保留在 plugin-sdk/realtime-voice。
2. 將 bundled surfaces 移到共享控制器上：browser relay、 managed-room handoff、voice-call realtime、voice-call streaming STT、Google Meet realtime，以及 native push-to-talk。
3. 以最終的 talk.session.* 和 talk.client.* API 取代舊的 Talk RPC 系列。
4. 在 Gateway hello-ok.features.events 中公告一個即時 Talk 事件通道：talk.event。
5. 刪除舊的即時 HTTP endpoint，以及任何 request-time instruction override 路徑。

新程式碼不應直接呼叫 createTalkEventSequencer(...)，除非它是在 實作低階 adapter 或測試 fixture。請優先使用共享控制器， 如此一來，turn-scoped 事件就無法在沒有 turn id 的情況下發出、過期的 turnEnd / turnCancel 呼叫無法清除較新的 active turn，且 output-audio lifecycle 事件在電話、會議、browser relay、managed-room handoff，以及 native Talk client 之間都能保持一致。

目標公開 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 });
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 });

Browser-owned WebRTC/provider-websocket 工作階段使用 talk.client.create， 因為瀏覽器負責 provider negotiation 和媒體傳輸，而 Gateway 負責憑證、指令與工具政策。talk.session.* 是 Gateway-managed 的共用介面，適用於 gateway-relay realtime、gateway-relay transcription，以及 managed-room native STT/TTS 工作階段。

將即時選擇器放在 talk.provider / talk.providers 旁邊的舊版設定，應使用 openclaw doctor --fix 修復；執行階段 Talk 不會將 speech/TTS provider config 重新解讀為 realtime provider config。

支援的 talk.session.create 組合刻意維持很小：

已移除的方法對照表：

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

不要在 core 中引入 provider 或 platform 特例來讓這項工作運作。 Core 負責 Talk 工作階段語意。Provider Plugin 負責 vendor 工作階段設定。 Voice-call 和 Google Meet 負責電話/會議 adapter。瀏覽器與 native app 負責裝置擷取/播放 UX。

# 相容性政策

對於外部 Plugin，相容性工作遵循以下順序：

1. 新增新合約
2. 透過相容性配接器保留舊行為的接線
3. 發出診斷或警告，指出舊路徑與替代項目
4. 在測試中涵蓋兩條路徑
5. 記錄棄用與遷移路徑
6. 僅在公告的遷移期間結束後移除，通常是在主要版本中

維護者可以使用 pnpm plugins:boundary-report 稽核目前的遷移佇列。使用 pnpm plugins:boundary-report:summary 取得 精簡計數，使用 --owner <id> 查看單一 Plugin 或相容性擁有者，並在 CI gate 應因到期的 相容性記錄、跨擁有者的保留 SDK 匯入，或未使用的保留 SDK 子路徑而失敗時使用 pnpm plugins:boundary-report:ci。報告會依移除日期分組已棄用的 相容性記錄、計算本機程式碼/文件參照、浮現跨擁有者的保留 SDK 匯入，並摘要私有 memory-host SDK 橋接，讓相容性清理保持明確，而不是依賴臨時搜尋。保留的 SDK 子路徑必須有追蹤的擁有者使用情況； 未使用的保留 helper 匯出應從公開 SDK 中移除。

如果 manifest 欄位仍被接受，Plugin 作者可以繼續使用，直到 文件與診斷另有說明。新程式碼應優先使用已文件化的 替代方案，但現有 Plugin 不應在一般 minor 版本期間中斷。

# 如何遷移

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

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

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

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

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";

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

pnpm build
pnpm test -- my-plugin/

# 匯入路徑參考

此表刻意只列出常見的遷移子集，而不是完整的 SDK 介面。200 多個進入點的完整清單位於 scripts/lib/plugin-sdk-entrypoints.json。

保留的內建 Plugin 輔助 seam 已從公開 SDK 匯出對照表中淘汰，只有明確記錄的相容性 facade 例外，例如為已發布的 @openclaw/[email protected] 套件保留的已棄用 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 對應到其標準替代項目。

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

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

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

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

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

# 移除時程

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

# 暫時抑制警告

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

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

這是暫時的逃生出口，不是永久解決方案。

# 相關

• 開始使用 - 建立你的第一個 Plugin
• SDK 概觀 - 完整子路徑匯入參考
• 頻道 Plugin - 建構頻道 Plugin
• 提供者 Plugin - 建構提供者 Plugin
• Plugin 內部架構 - 架構深入解析
• Plugin Manifest - manifest schema 參考