跳轉到主要內容
OpenClaw 已將廣泛的向後兼容層,替換為由小型、聚焦匯入所建構的現代外掛架構。如果你的外掛早於該變更,本指南會協助它遷移到目前的合約。

變更內容

過去有兩個開放範圍很廣的匯入介面,讓外掛能從單一進入點存取幾乎所有內容:
  • openclaw/plugin-sdk/compat - 重新匯出數十個輔助工具,以便在新架構建置期間維持較舊的 hook 型外掛可運作。
  • openclaw/plugin-sdk/infra-runtime - 一個廣泛的 barrel,混合了系統事件、心跳偵測狀態、傳遞佇列、fetch/proxy 輔助工具、檔案輔助工具、核准類型,以及不相關的工具。
  • openclaw/plugin-sdk/config-runtime - 一個廣泛的設定 barrel,在遷移期間仍攜帶已棄用的直接載入/寫入輔助工具。
  • openclaw/extension-api - 一個橋接層,讓外掛可直接存取主機端輔助工具,例如內嵌代理執行器。
  • api.registerEmbeddedExtensionFactory(...) - 已移除、僅供內嵌執行器使用的 hook,過去會觀察內嵌執行器事件,例如 tool_result。請改用代理工具結果 middleware(請參閱將內嵌工具結果擴充功能遷移至 middleware)。
這些介面已棄用:它們仍可運作,但新外掛不得使用,既有外掛也應在下一個主要版本移除它們之前完成遷移。registerEmbeddedExtensionFactory 已經移除;舊式註冊不再載入。
向後兼容層將在未來的主要版本中移除。仍從這些介面匯入的外掛屆時會中斷。
OpenClaw 不會在引入替代方案的同一個變更中,移除或重新詮釋已文件化的外掛行為。破壞性合約變更會先經過兼容性轉接器、診斷、文件,以及棄用期間。這適用於 SDK 匯入、manifest 欄位、設定 API、hook,以及 runtime 註冊行為。

原因

  • 啟動緩慢 - 匯入一個輔助工具會載入數十個不相關的模組。
  • 循環依賴 - 廣泛的重新匯出讓匯入循環很容易產生。
  • API 介面不清楚 - 無法分辨穩定匯出與內部匯出。
每個 openclaw/plugin-sdk/<subpath> 現在都是小型、自包含,且具備文件化合約的模組。 舊式的 bundled channels provider 便利介面也已移除 - channel 品牌化的輔助捷徑是私有 mono-repo 便利功能,不是穩定的外掛合約。請改用狹窄的通用 SDK 子路徑。在 bundled plugin workspace 內,將 provider 擁有的輔助工具保留在該外掛自己的 api.tsruntime-api.ts
  • Anthropic 將 Claude 專用的串流輔助工具保留在自己的 api.ts / contract-api.ts 介面中。
  • OpenAI 將 provider builder、預設模型輔助工具,以及 realtime provider builder 保留在自己的 api.ts 中。
  • OpenRouter 將 provider builder 與 onboarding/config 輔助工具保留在自己的 api.ts 中。

兼容性政策

外部外掛兼容性工作依此順序進行:
  1. 新增新合約。
  2. 透過兼容性轉接器保留舊行為的接線。
  3. 發出診斷或警告,命名舊路徑與替代方案。
  4. 在測試中涵蓋兩條路徑。
  5. 文件化棄用與遷移路徑。
  6. 僅在已公告的遷移期間結束後移除,通常是在主要版本中。
如果 manifest 欄位仍被接受,請繼續使用,直到文件與診斷另有說明。新程式碼應優先使用已文件化的替代方案;既有外掛不應在一般次要版本中中斷。 使用 pnpm plugins:boundary-report 稽核目前的遷移佇列:
旗標效果
--summary(或 pnpm plugins:boundary-report:summary使用精簡計數,而不是完整詳細資訊。
--json機器可讀報告。
--owner <id>篩選到單一外掛或兼容性擁有者。
--fail-on-cross-owner在跨擁有者保留 SDK 匯入時以非零狀態結束。
--fail-on-eligible-compat當已棄用 compat 記錄的 removeAfter 日期已過時,以非零狀態結束。
--fail-on-unclassified-unused-reserved在未使用且未分類的保留 SDK shim 上以非零狀態結束。
pnpm plugins:boundary-report:ci 會啟用全部三個失敗旗標。每筆兼容性記錄都有明確的 removeAfter 日期(不是含糊的「下一個主要版本」)- 報告會依該日期分組已棄用記錄、計算本機程式碼/文件參照、揭露跨擁有者的保留 SDK 匯入,並摘要私有記憶體主機 SDK 橋接。保留 SDK 子路徑必須有追蹤的擁有者使用情形;未使用的保留匯出應從公開 SDK 移除。

如何遷移

1

遷移 runtime 設定載入/寫入輔助工具

Bundled 外掛應停止直接呼叫 api.runtime.config.loadConfig()api.runtime.config.writeConfigFile(...)。優先使用已傳入作用中呼叫路徑的設定。需要目前程序快照的長生命週期 handler 可以使用 api.runtime.config.current()。長生命週期的代理工具應在 execute 內讀取 ctx.getRuntimeConfig(),讓設定寫入前建立的工具仍能看到重新整理後的設定。設定寫入會透過具有明確寫入後政策的交易式輔助工具執行:
await api.runtime.config.mutateConfigFile({
  afterWrite: { mode: "auto" },
  mutate(draft) {
    draft.plugins ??= {};
  },
});
當變更需要乾淨的閘道重新啟動時,使用 afterWrite: { mode: "restart", reason: "..." };只有當呼叫端擁有後續動作並刻意抑制重新載入規劃器時,才使用 afterWrite: { mode: "none", reason: "..." }。Mutation 結果包含型別化的 followUp 摘要,可供測試與記錄使用;閘道仍負責套用或排程重新啟動。loadConfigwriteConfigFile 仍作為外部外掛的已棄用兼容性輔助工具保留,並以 runtime-config-load-write 兼容性代碼發出一次警告。Bundled 外掛與 repo runtime 程式碼由 pnpm check:deprecated-api-usagepnpm check:no-runtime-action-load-config 防護:新的 production 外掛使用會直接失敗,直接設定寫入會失敗,閘道 server 方法必須使用請求 runtime 快照,runtime channel send/action/client 輔助工具必須從其邊界接收設定,且長生命週期 runtime 模組允許零個環境式 loadConfig() 呼叫。新的外掛程式碼應避免廣泛的 openclaw/plugin-sdk/config-runtime barrel。請針對工作使用狹窄的子路徑:
需求匯入
設定類型,例如 OpenClawConfigopenclaw/plugin-sdk/config-contracts
已載入設定斷言與外掛進入點設定查詢openclaw/plugin-sdk/plugin-config-runtime
目前 runtime 快照讀取openclaw/plugin-sdk/runtime-config-snapshot
設定寫入openclaw/plugin-sdk/config-mutation
Session store 輔助工具openclaw/plugin-sdk/session-store-runtime
Markdown 表格設定openclaw/plugin-sdk/markdown-table-runtime
群組政策 runtime 輔助工具openclaw/plugin-sdk/runtime-group-policy
Secret input 解析openclaw/plugin-sdk/secret-input-runtime
Model/session 覆寫openclaw/plugin-sdk/model-session-runtime
Bundled 外掛與其測試受到掃描器防護,避免使用廣泛 barrel,讓匯入與 mock 都維持在所需行為的本機範圍內。該 barrel 仍為外部兼容性存在,但新程式碼不應依賴它。
2

將內嵌工具結果擴充功能遷移至 middleware

Bundled 外掛必須以 runtime 中立的 middleware,取代僅供內嵌執行器使用的 api.registerEmbeddedExtensionFactory(...) 工具結果 handler:
// OpenClaw and Codex runtime dynamic tools
api.registerAgentToolResultMiddleware(async (event) => {
  return compactToolResult(event);
}, {
  runtimes: ["openclaw", "codex"],
});
同時更新外掛 manifest:
{
  "contracts": {
    "agentToolResultMiddleware": ["openclaw", "codex"]
  }
}
已安裝的外掛也可以在明確啟用,且每個目標 runtime 都已在 contracts.agentToolResultMiddleware 宣告時,註冊工具結果 middleware。未宣告的已安裝 middleware 註冊會被拒絕。
3

將 approval-native handler 遷移到 capability facts

具備核准能力的 channel 外掛會透過 approvalCapability.nativeRuntime 加上共享 runtime-context registry,公開原生核准行為:
  • approvalCapability.handler.loadRuntime(...) 替換為 approvalCapability.nativeRuntime
  • 將核准專用 auth/delivery 從舊式 plugin.auth / plugin.approvals 接線移到 approvalCapability
  • ChannelPlugin.approvals 已從公開的 channel-plugin 合約中移除;請將 delivery/native/render 欄位移到 approvalCapability
  • plugin.auth 僅保留給 channel login/logout 流程;core 不再從那裡讀取核准 auth hook。
  • 透過 openclaw/plugin-sdk/channel-runtime-context 註冊 channel 擁有的 runtime 物件(clients、tokens、Bolt apps)。
  • 不要從原生核准 handler 傳送外掛擁有的 reroute 通知;core 擁有來自實際傳遞結果的 routed-elsewhere 通知。
  • channelRuntime 傳入 createChannelManager(...) 時,請提供真正的 createPluginRuntime().channel 介面 - partial stub 會被拒絕。
請參閱 Channel 外掛 以取得目前的核准能力版面配置。
4

稽核 Windows wrapper fallback 行為

如果你的外掛使用 openclaw/plugin-sdk/windows-spawn,未解析的 Windows .cmd/.bat wrapper 現在會封閉失敗,除非你明確傳入 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 fallback,請不要設定 allowShellFallback,並改為處理拋出的錯誤。
5

尋找已棄用的匯入

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/
6

替換為聚焦匯入

舊介面的每個匯出都會對應到特定的現代匯入路徑:
// 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 { runEmbeddedAgent } from "openclaw/extension-api";
const result = await runEmbeddedAgent({ sessionId, prompt });

// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedAgent({ 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.*
7

取代寬泛的 infra-runtime 匯入

openclaw/plugin-sdk/infra-runtime 仍會為外部相容性保留,但新程式碼應匯入它實際需要的聚焦介面:
需求匯入
系統事件佇列輔助工具openclaw/plugin-sdk/system-event-runtime
心跳偵測喚醒、事件與可見性輔助工具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
可感知分派器的 fetchopenclaw/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
內建外掛已受掃描器保護,禁止使用 infra-runtime,因此儲存庫程式碼無法退回寬泛 barrel。
8

遷移頻道路由輔助工具

新的頻道路由程式碼使用 openclaw/plugin-sdk/channel-route。較舊的 route-key 與 comparable-target 名稱會保留作為相容性別名:
舊輔助工具現代輔助工具
channelRouteIdentityKey(...)channelRouteDedupeKey(...)
channelRouteKey(...)channelRouteCompactKey(...)
ComparableChannelTargetChannelRouteParsedTarget
comparableChannelTargetsMatch(...)channelRouteTargetsMatchExact(...)
comparableChannelTargetsShareRoute(...)channelRouteTargetsShareConversation(...)
現代路由輔助工具會在原生核准、回覆抑制、入站去重、排程傳遞與工作階段路由之間,一致地正規化 { channel, to, accountId, threadId }不要新增對 ChannelMessagingAdapter.parseExplicitTarget、parser-backed loaded-route 輔助工具(parseExplicitTargetForLoadedChannelresolveRouteTargetForLoadedChannel),或來自 plugin-sdk/channel-routeresolveChannelRouteTargetWithParser(...) 的使用 - 這些已棄用,僅為較舊的外掛保留。新的頻道外掛應使用 messaging.targetResolver.resolveTarget(...) 進行 target-id 正規化與目錄未命中後援,當核心需要早期對等端種類時使用 messaging.inferTargetChatType(...),並使用 messaging.resolveOutboundSessionRoute(...) 處理提供者原生工作階段與對話串身分。
9

建置與測試

pnpm build
pnpm test my-plugin/

匯入路徑參考

匯入路徑用途主要匯出
plugin-sdk/plugin-entry標準外掛進入點輔助工具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設定期間執行階段輔助工具createSetupTranslator、匯入安全的設定修補配接器、查找備註輔助工具、promptResolvedAllowFromsplitSetupEntries、委派設定代理
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帳號 ID 輔助工具DEFAULT_ACCOUNT_ID、帳號 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-pairingDM 配對原語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 維護的內建外掛;新外掛必須定義外掛本機架構
plugin-sdk/channel-config-schema-legacy已淘汰的內建設定架構僅限相容性別名;對維護中的內建外掛使用 plugin-sdk/bundled-channel-config-schema
plugin-sdk/telegram-command-configTelegram 命令設定輔助工具命令名稱正規化、描述修剪、重複/衝突驗證
plugin-sdk/channel-policy群組/DM 政策解析resolveChannelGroupRequireMention
plugin-sdk/channel-lifecycle已淘汰的相容性門面使用 plugin-sdk/channel-outbound
plugin-sdk/inbound-envelope輸入信封輔助工具共用路由 + 信封建構器輔助工具
plugin-sdk/channel-inbound輸入接收輔助工具內容建構、格式化、根、執行器、已準備回覆分派,以及分派述詞
plugin-sdk/messaging-targets已淘汰的目標剖析匯入路徑對通用目標剖析輔助工具使用 plugin-sdk/channel-targets,對路由比較使用 plugin-sdk/channel-route,對提供者專屬目標解析使用外掛擁有的 messaging.targetResolver / messaging.resolveOutboundSessionRoute
plugin-sdk/outbound-media輸出媒體輔助工具共用輸出媒體載入
plugin-sdk/outbound-send-deps已淘汰的相容性門面使用 plugin-sdk/channel-outbound
plugin-sdk/channel-outbound輸出訊息生命週期輔助工具訊息配接器、回執、耐久發送輔助工具、即時預覽/串流輔助工具、回覆選項、生命週期輔助工具、輸出身分與酬載規劃
plugin-sdk/channel-streaming已淘汰的相容性門面使用 plugin-sdk/channel-outbound
plugin-sdk/outbound-runtime已淘汰的相容性門面使用 plugin-sdk/channel-outbound
plugin-sdk/thread-bindings-runtime執行緒繫結輔助工具執行緒繫結生命週期與配接器輔助工具
plugin-sdk/agent-media-payload舊版媒體酬載輔助工具舊版欄位版面配置的代理媒體酬載建構器
plugin-sdk/channel-runtime已淘汰的相容性 shim僅限舊版通道執行階段公用工具
plugin-sdk/channel-send-result發送結果型別回覆結果型別
plugin-sdk/runtime-store持久化外掛儲存createPluginRuntimeStore
plugin-sdk/runtime廣範圍執行階段輔助工具執行階段/記錄/備份/外掛安裝輔助工具
plugin-sdk/runtime-env窄範圍執行階段環境輔助工具記錄器/執行階段環境、逾時、重試與退避輔助工具
plugin-sdk/plugin-runtime共用外掛執行階段輔助工具外掛命令/鉤子/HTTP/互動式輔助工具
plugin-sdk/hook-runtime鉤子管線輔助工具共用網路鉤子/內部鉤子管線輔助工具
plugin-sdk/lazy-runtime延遲載入執行階段輔助工具createLazyRuntimeModule, createLazyRuntimeMethod, createLazyRuntimeMethodBinder, createLazyRuntimeNamedExport, createLazyRuntimeSurface
plugin-sdk/process-runtime程序輔助工具共用執行輔助工具
plugin-sdk/cli-runtime命令列介面執行階段輔助工具命令格式化、等待、版本輔助工具
plugin-sdk/gateway-runtime閘道輔助工具閘道用戶端、事件迴圈就緒啟動輔助工具、公告的 LAN 主機解析,以及通道狀態修補輔助工具
plugin-sdk/config-runtime已淘汰的設定相容性 shim優先使用 config-contracts, plugin-config-runtime, runtime-config-snapshotconfig-mutation
plugin-sdk/telegram-command-configTelegram 命令輔助工具內建 Telegram 合約介面無法使用時,備援穩定的 Telegram 命令驗證輔助工具
plugin-sdk/approval-runtime核准提示輔助工具執行/外掛核准酬載、核准能力/設定檔輔助工具、原生核准路由/執行階段輔助工具,以及結構化核准顯示路徑格式化
plugin-sdk/approval-auth-runtime核准授權輔助工具核准者解析、同一聊天動作授權
plugin-sdk/approval-client-runtime核准用戶端輔助工具原生執行核准設定檔/篩選器輔助工具
plugin-sdk/approval-delivery-runtime核准傳遞輔助工具原生核准能力/傳遞配接器
plugin-sdk/approval-gateway-runtime核准閘道輔助工具共用核准閘道解析輔助工具
plugin-sdk/approval-handler-adapter-runtime核准配接器輔助工具熱通道進入點的輕量原生核准配接器載入輔助工具
plugin-sdk/approval-handler-runtime核准處理常式輔助工具較廣範圍的核准處理常式執行階段輔助工具;足夠時優先使用較窄的配接器/閘道接縫
plugin-sdk/approval-native-runtime核准目標輔助工具原生核准目標/帳號繫結輔助工具
plugin-sdk/approval-reply-runtime核准回覆輔助工具執行/外掛核准回覆酬載輔助工具
plugin-sdk/channel-runtime-context通道執行階段內容輔助工具通用通道執行階段內容註冊/取得/監看輔助工具
plugin-sdk/security-runtime安全性輔助工具共用信任、DM 閘控、根目錄範圍限制的檔案/路徑輔助工具、外部內容與密鑰收集輔助工具
plugin-sdk/ssrf-policySSRF 政策輔助工具主機允許清單與私有網路政策輔助工具
plugin-sdk/ssrf-runtimeSSRF 執行階段輔助工具固定調度器、受防護的擷取、SSRF 政策輔助工具
plugin-sdk/system-event-runtime系統事件輔助工具enqueueSystemEvent, peekSystemEventEntries
plugin-sdk/heartbeat-runtime心跳偵測輔助工具心跳偵測喚醒、事件與可見性輔助工具
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/exec-approvals-runtime執行核准政策輔助工具loadExecApprovals, resolveExecApprovalsFromFile, ExecApprovalsFile
plugin-sdk/collection-runtime有界快取輔助工具pruneMapToMaxSize
plugin-sdk/diagnostic-runtime診斷閘控輔助工具isDiagnosticFlagEnabled, isDiagnosticsEnabled
plugin-sdk/error-runtime錯誤格式化輔助工具formatUncaughtError, isApprovalNotFoundError、錯誤圖輔助工具
plugin-sdk/fetch-runtime包裝式擷取/代理輔助工具resolveFetch、代理輔助工具、EnvHttpProxyAgent 選項輔助工具
plugin-sdk/host-runtime主機正規化輔助工具normalizeHostname, normalizeScpRemoteHost
plugin-sdk/retry-runtime重試輔助工具RetryConfig, retryAsync、政策執行器
plugin-sdk/allow-from允許清單格式化與輸入對應formatAllowFromLowercase, mapAllowlistResolutionInputs
plugin-sdk/command-auth命令閘控與命令介面輔助工具resolveControlCommandGate、發送者授權輔助工具、命令登錄輔助工具,包含動態引數選單格式化
plugin-sdk/command-status命令狀態/說明轉譯器buildCommandsMessage, buildCommandsMessagePaginated, buildHelpMessage
plugin-sdk/secret-input密鑰輸入剖析密鑰輸入輔助工具
plugin-sdk/webhook-ingress網路鉤子請求輔助工具網路鉤子目標公用工具
plugin-sdk/webhook-request-guards網路鉤子主體防護輔助工具請求主體讀取/限制輔助工具
plugin-sdk/reply-runtime共用回覆執行階段輸入分派、心跳偵測、回覆規劃器、分塊
plugin-sdk/reply-dispatch-runtime窄範圍回覆分派輔助工具完成、提供者分派與對話標籤輔助工具
plugin-sdk/reply-history回覆歷史輔助工具createChannelHistoryWindow;已淘汰的對應表輔助工具相容性匯出,例如 buildPendingHistoryContextFromMap, recordPendingHistoryEntryclearHistoryEntriesIfEnabled
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路由/工作階段金鑰輔助工具resolveAgentRoutebuildAgentSessionKeyresolveDefaultAgentBoundAccountId、工作階段金鑰正規化輔助工具
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參數讀取器常用工具/命令列介面參數讀取器
plugin-sdk/tool-payload工具承載資料擷取從工具結果物件擷取正規化承載資料
plugin-sdk/tool-send工具傳送擷取從工具引數擷取標準傳送目標欄位
plugin-sdk/temp-path暫存路徑輔助工具共用暫存下載路徑輔助工具
plugin-sdk/logging-core記錄輔助工具子系統記錄器與遮蔽輔助工具
plugin-sdk/markdown-table-runtimeMarkdown 表格輔助工具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共用供應商模型/重播輔助工具ProviderReplayFamilybuildProviderReplayFamilyHooksnormalizeModelCompat、共用重播政策建構器、供應商端點輔助工具,以及模型 ID 正規化輔助工具
plugin-sdk/provider-catalog-shared共用供應商目錄輔助工具findCatalogTemplatebuildSingleProviderApiKeyCatalogbuildManifestModelProviderConfigsupportsNativeStreamingUsageCompatapplyProviderNativeStreamingUsageCompat
plugin-sdk/provider-onboard供應商導入修補導入設定輔助工具
plugin-sdk/provider-http供應商 HTTP 輔助工具通用供應商 HTTP/端點能力輔助工具,包含音訊轉錄 multipart 表單輔助工具
plugin-sdk/provider-web-fetch供應商網頁擷取輔助工具網頁擷取供應商註冊/快取輔助工具
plugin-sdk/provider-web-search-config-contract供應商網頁搜尋設定輔助工具適用於不需要外掛啟用接線之供應商的精簡網頁搜尋設定/憑證輔助工具
plugin-sdk/provider-web-search-contract供應商網頁搜尋合約輔助工具精簡網頁搜尋設定/憑證合約輔助工具,例如 createWebSearchProviderContractFieldsenablePluginInConfigresolveProviderWebSearchPluginConfig,以及具範圍的憑證設定器/取得器
plugin-sdk/provider-web-search供應商網頁搜尋輔助工具網頁搜尋供應商註冊/快取/執行階段輔助工具
plugin-sdk/provider-tools供應商工具/結構描述相容輔助工具ProviderToolCompatFamilybuildProviderToolCompatFamilyHooks,以及 DeepSeek/Gemini/OpenAI 結構描述清理與診斷
plugin-sdk/provider-usage供應商用量輔助工具fetchClaudeUsagefetchGeminiUsagefetchGithubCopilotUsage,以及其他供應商用量輔助工具
plugin-sdk/provider-stream供應商串流包裝器輔助工具ProviderStreamFamilybuildProviderStreamFamilyHookscomposeProviderStreamWrappers、串流包裝器型別,以及共用 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-runtimetext-chunkingtext-utility-runtimelogging-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-sdk/channel-status頻道狀態輔助工具共用頻道狀態快照/摘要輔助工具
plugin-sdk/allowlist-config-edit允許清單設定輔助工具允許清單設定編輯/讀取輔助工具
plugin-sdk/group-access群組存取輔助工具共用群組存取決策輔助工具
plugin-sdk/direct-dm, plugin-sdk/direct-dm-access已棄用的相容性門面使用 plugin-sdk/channel-inbound
plugin-sdk/direct-dm-guard-policy直接私訊防護輔助工具精簡加密前防護政策輔助工具
plugin-sdk/extension-shared共用擴充輔助工具被動頻道/狀態與環境代理輔助基礎元件
plugin-sdk/webhook-targets網路鉤子目標輔助工具網路鉤子目標登錄與路由安裝輔助工具
plugin-sdk/webhook-path已棄用的網路鉤子路徑別名使用 plugin-sdk/webhook-ingress
plugin-sdk/web-media共用網頁媒體輔助工具遠端/本機媒體載入輔助工具
plugin-sdk/zod已棄用的 Zod 相容性重新匯出直接從 zod 匯入 zod
plugin-sdk/memory-core內建記憶體核心輔助工具記憶體管理器/設定/檔案/命令列介面輔助工具介面
plugin-sdk/memory-core-engine-runtime記憶體引擎執行階段門面記憶體索引/搜尋執行階段門面
plugin-sdk/memory-core-host-embedding-registry記憶體嵌入登錄輕量記憶體嵌入供應商登錄輔助工具
plugin-sdk/memory-core-host-engine-foundation記憶體主機基礎引擎記憶體主機基礎引擎匯出
plugin-sdk/memory-core-host-engine-embeddings記憶體主機嵌入引擎記憶體嵌入合約、登錄存取、本機供應商,以及通用批次/遠端輔助工具;具體遠端供應商位於其所屬外掛中
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記憶體主機命令列介面執行階段記憶體主機命令列介面執行階段輔助工具
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 輔助工具供記憶體相鄰外掛使用的共用受管理 Markdown 輔助工具
plugin-sdk/memory-host-search主動記憶搜尋門面延遲載入的主動記憶搜尋管理器執行階段門面
plugin-sdk/memory-host-status已棄用的記憶體主機狀態別名使用 plugin-sdk/memory-core-host-status
plugin-sdk/testing測試公用工具儲存庫本機已棄用的相容性彙整匯出;使用聚焦的儲存庫本機測試子路徑,例如 plugin-sdk/plugin-test-runtimeplugin-sdk/channel-test-helpersplugin-sdk/channel-target-testingplugin-sdk/test-envplugin-sdk/test-fixtures
此表格是常見遷移子集,不是完整的 SDK 介面。編譯器進入點清單位於 scripts/lib/plugin-sdk-entrypoints.json;套件匯出會從公開子集產生。 保留的內建外掛輔助接縫已從公開 SDK 匯出映射中退役,但明確記錄的相容性 facade 除外,例如保留給仍直接匯入已發布 @openclaw/discord 套件之外部外掛的已棄用 plugin-sdk/discord shim。擁有者專屬輔助工具位於所屬外掛套件內;共用主機行為會透過泛用 SDK 合約移動,例如 plugin-sdk/gateway-runtimeplugin-sdk/security-runtimeplugin-sdk/plugin-config-runtime 使用符合工作的最窄匯入。如果找不到匯出,請檢查 src/plugin-sdk/ 的原始碼,或詢問維護者應由哪個泛用合約擁有它。

作用中的棄用項目

外掛 SDK、供應者合約、執行階段介面和 manifest 中更窄範圍的棄用項目。每個項目目前仍可運作,但會在未來的主要版本中移除。每個項目都會將舊 API 對應到其標準替代項。
舊 (openclaw/plugin-sdk/command-auth)buildCommandsMessagebuildCommandsMessagePaginatedbuildHelpMessage新 (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";
:來自 openclaw/plugin-sdk/channel-inboundopenclaw/plugin-sdk/channel-mention-gatingresolveMentionGating(params)resolveMentionGatingWithBypass(params)resolveInboundMentionDecision({ facts, policy }),使用一個決策物件,而不是兩種拆分的呼叫形狀。已在 Discord、iMessage、Matrix、MS Teams、QQ Bot、Signal、 Telegram、WhatsApp 和 Zalo 中採用。Slack 自身的 app_mention 事件模型不使用此輔助工具。
openclaw/plugin-sdk/channel-runtime 是舊版頻道外掛的相容性 shim。新程式碼不要匯入它;請使用 openclaw/plugin-sdk/channel-runtime-context 註冊執行階段物件。openclaw/plugin-sdk/channel-actions 中的 channelActions* 輔助工具,會與原始「actions」頻道匯出一起棄用。請改為透過語意化的 presentation 介面公開能力:頻道外掛宣告它們要呈現的內容(卡片、按鈕、選取器),而不是它們接受哪些原始動作名稱。
:來自 openclaw/plugin-sdk/provider-web-searchtool() 工廠。:直接在供應者外掛上實作 createTool(...)。OpenClaw 不再需要 SDK 輔助工具來註冊工具包裝器。
api.runtime.channel.reply.formatInboundEnvelope(...)(以及傳入訊息物件上的 channelEnvelope 欄位),用來從傳入頻道訊息建立扁平的純文字提示封套。BodyForAgent 加上結構化使用者情境區塊。頻道外掛會將路由中繼資料(討論串、主題、回覆對象、回應)附加為具型別欄位,而不是將它們串接進提示字串。formatAgentEnvelope(...) 輔助工具仍支援合成的面向助理封套,但傳入純文字封套正在淘汰中。受影響區域:inbound_claimmessage_received,以及任何曾對舊封套文字進行後處理的自訂頻道外掛。
api.on("deactivate", handler)api.on("gateway_stop", handler)。相同的關閉清理合約;只有 hook 名稱變更。
// Before
api.on("deactivate", async (event, ctx) => {
  await stopPluginService(ctx);
});

// After
api.on("gateway_stop", async (event, ctx) => {
  await stopPluginService(ctx);
});
deactivate 仍會作為已棄用的相容性別名接線,直到 2026-08-16 後移除。
api.on("subagent_spawning", handler),回傳 threadBindingReadydeliveryOrigin:讓核心透過頻道工作階段繫結轉接器準備 thread: true 子代理繫結。僅使用 api.on("subagent_spawned", handler) 進行啟動後觀察。
// Before
api.on("subagent_spawning", async () => ({
  status: "ok",
  threadBindingReady: true,
  deliveryOrigin: { channel: "discord", to: "channel:123", threadId: "456" },
}));

// After
api.on("subagent_spawned", async (event) => {
  await observeSubagentLaunch(event);
});
subagent_spawningPluginHookSubagentSpawningEventPluginHookSubagentSpawningResultSubagentLifecycleHookRunner.runSubagentSpawning(...) 只會在外部外掛遷移期間保留為已棄用的相容性介面,並於 2026-08-30 後移除。
四個探索型別別名現在是型錄時代型別的薄包裝:
舊別名新型別
ProviderDiscoveryOrderProviderCatalogOrder
ProviderDiscoveryContextProviderCatalogContext
ProviderDiscoveryResultProviderCatalogResult
ProviderPluginDiscoveryProviderPluginCatalog
以及舊版的 ProviderCapabilities 靜態集合:供應者外掛應使用明確的供應者 hook,例如 buildReplayPolicynormalizeToolSchemaswrapStreamFn,而不是靜態物件。
ProviderThinkingPolicy 上的三個獨立 hook): isBinaryThinking(ctx)supportsXHighThinking(ctx)resolveDefaultThinkingLevel(ctx):單一 resolveThinkingProfile(ctx),回傳包含標準 id、選用 label,以及已排序層級清單的 ProviderThinkingProfile。OpenClaw 會自動依 profile 排名降級過期的已儲存值。情境包含 providermodelId、選用的合併 reasoning,以及選用的合併模型 compat 事實。供應者外掛可以使用這些型錄事實,只有在已設定的請求合約支援時,才公開模型專屬 profile。請實作一個 hook,而不是三個。舊版 hook 在棄用期間會繼續運作,但不會與 profile 結果組合。
:實作外部驗證 hook,但未在外掛 manifest 中宣告供應者。:在外掛 manifest 中宣告 contracts.externalAuthProviders並且實作 resolveExternalAuthProfiles(...)
{
  "contracts": {
    "externalAuthProviders": ["anthropic", "openai"]
  }
}
manifest 欄位:providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }:將相同的環境變數查找鏡像到 manifest 上的 setup.providers[].envVars。這會將設定/狀態環境中繼資料集中到一個位置,並避免只為了回答環境變數查找而啟動外掛執行階段。providerAuthEnvVars 會透過相容性轉接器繼續支援,直到棄用期間結束。
:三個獨立呼叫:api.registerMemoryPromptSection(...)api.registerMemoryFlushPlan(...)api.registerMemoryRuntime(...):在記憶狀態 API 上的一個呼叫: registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })相同插槽,單一註冊呼叫。附加式提示和語料庫輔助工具(registerMemoryPromptSupplementregisterMemoryCorpusSupplement)不受影響。
api.registerMemoryEmbeddingProvider(...) 加上 contracts.memoryEmbeddingProvidersapi.registerEmbeddingProvider(...) 加上 contracts.embeddingProviders泛用嵌入供應者合約可在記憶之外重複使用,也是新供應者支援的路徑。記憶專屬註冊 API 會在現有供應者遷移期間,繼續作為已棄用相容性接線。外掛檢查會將非內建使用回報為相容性債務。
仍從 src/plugins/runtime/types.ts 匯出的兩個舊版型別別名:
SubagentReadSessionParamsSubagentGetSessionMessagesParams
SubagentReadSessionResultSubagentGetSessionMessagesResult
執行階段方法 readSession 已棄用,請改用 getSessionMessages。相同簽章;舊方法會轉呼叫新方法。
runtime.tasks.flow(單數)會回傳即時任務流程存取器。runtime.tasks.managedFlows 會保留受管理的 TaskFlow 變更執行階段,供從流程建立、更新、取消或執行子任務的外掛使用。當外掛只需要基於 DTO 的讀取時,請使用 runtime.tasks.flows
// Before
const flow = api.runtime.tasks.flow.fromToolContext(ctx);
// After
const flow = api.runtime.tasks.managedFlows.fromToolContext(ctx);
於 2026-07-26 後移除。
已在上方的如何遷移中涵蓋。為完整性列於此處:已移除的僅限嵌入式執行器 api.registerEmbeddedExtensionFactory(...) 路徑,會由 api.registerAgentToolResultMiddleware(...) 取代,並在 contracts.agentToolResultMiddleware 中明確列出執行階段清單。
openclaw/plugin-sdk 重新匯出的 OpenClawSchemaType 現在是 OpenClawConfig 的單行別名。請優先使用標準名稱。
// Before
import type { OpenClawSchemaType } from "openclaw/plugin-sdk";
// After
import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema";
外掛層級的淘汰項目(位於 extensions/ 下捆綁的頻道/提供者外掛內)會在各自的 api.tsruntime-api.ts barrel 中追蹤。它們不影響第三方外掛合約,也不會列在此處。如果你直接使用捆綁外掛的本機 barrel,升級前請先閱讀該 barrel 中的淘汰註解。

Talk 與即時語音遷移

即時語音、電話、會議和瀏覽器 Talk 程式碼共用一個由 openclaw/plugin-sdk/realtime-voice 匯出的 Talk 工作階段控制器。該控制器負責共通的 Talk 事件封套、作用中的回合狀態、擷取狀態、輸出音訊狀態、近期事件歷史,以及過期回合拒絕。提供者外掛負責廠商特定的即時工作階段;介面外掛負責擷取、播放、電話和會議的特殊情境。 所有捆綁介面都在共用控制器上執行:瀏覽器轉送、受管理聊天室交接、語音通話即時、語音通話串流 STT、Google Meet 即時,以及原生按住說話。閘道會在 hello-ok.features.events 中公告一個即時 Talk 事件頻道:talk.event 新程式碼不應直接呼叫 createTalkEventSequencer(...),除非是在實作低階配接器或測試 fixture。請使用共用控制器,讓回合範圍事件無法在沒有回合 ID 的情況下送出,過期的 turnEnd / turnCancel 呼叫無法清除較新的作用中回合,且輸出音訊生命週期事件能在電話、會議、瀏覽器轉送、受管理聊天室交接,以及原生 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 });
await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });
瀏覽器擁有的 WebRTC/提供者 WebSocket 工作階段使用 talk.client.create,因為瀏覽器擁有提供者協商與媒體傳輸,而閘道擁有憑證、指示和工具政策。talk.session.* 是閘道管理的共通介面,適用於 gateway-relay 即時、gateway-relay 轉錄,以及 managed-room 原生 STT/TTS 工作階段。 將即時選擇器放在 talk.provider / talk.providers 旁的舊版設定,應透過 openclaw doctor --fix 修復;執行階段 Talk 不會把語音/TTS 提供者設定重新解讀為即時提供者設定。 支援的 talk.session.create 組合刻意保持精簡:
模式傳輸Brain擁有者註記
realtimegateway-relayagent-consult閘道透過閘道橋接全雙工提供者音訊;工具呼叫會經由 agent-consult 工具路由。
transcriptiongateway-relaynone閘道僅串流 STT;呼叫端傳送輸入音訊並接收逐字稿事件。
stt-ttsmanaged-roomagent-consult原生/用戶端聊天室按住說話與對講機風格聊天室,其中用戶端擁有擷取/播放,而閘道擁有回合狀態。
stt-ttsmanaged-roomdirect-tools原生/用戶端聊天室僅供管理員使用的聊天室模式,適用於受信任的第一方介面,可直接執行閘道工具動作。
供從較舊的 talk.realtime.* / talk.transcription.* / talk.handoff.* 家族(皆已移除)遷移的讀者使用的方法對照:
talk.realtime.sessiontalk.client.create
talk.realtime.toolCalltalk.client.toolCall
talk.realtime.relayAudiotalk.session.appendAudio
talk.realtime.relayCanceltalk.session.cancelOutputtalk.session.cancelTurn
talk.realtime.relayToolResulttalk.session.submitToolResult
talk.realtime.relayStoptalk.session.close
talk.transcription.sessiontalk.session.create({ mode: "transcription" })
talk.transcription.relayAudiotalk.session.appendAudio
talk.transcription.relayCanceltalk.session.cancelTurn
talk.transcription.relayStoptalk.session.close
talk.handoff.createtalk.session.create({ transport: "managed-room" })
talk.handoff.jointalk.session.join
talk.handoff.revoketalk.session.close
統一的控制詞彙也刻意保持狹窄:
方法適用於合約
talk.session.appendAudiorealtime/gateway-relay, transcription/gateway-relay將 base64 PCM 音訊區塊附加到同一個閘道連線擁有的提供者工作階段。
talk.session.startTurnstt-tts/managed-room開始受管理聊天室使用者回合。
talk.session.endTurnstt-tts/managed-room在過期回合驗證後結束作用中回合。
talk.session.cancelTurn所有閘道擁有的工作階段取消某個回合的作用中擷取/提供者/代理/TTS 工作。
talk.session.cancelOutputrealtime/gateway-relay停止助理音訊輸出,但不一定結束使用者回合。
talk.session.submitToolResultrealtime/gateway-relay完成由轉送發出的提供者工具呼叫;傳遞 options.willContinue 以產生暫時輸出,或傳遞 options.suppressResponse 以在不產生另一個助理回應的情況下滿足該呼叫。
talk.session.steer代理支援的 Talk 工作階段將語音 statussteercancelfollowup 控制傳送到從 Talk 工作階段解析出的作用中嵌入式執行。
talk.session.close所有統一工作階段停止轉送工作階段或撤銷受管理聊天室狀態,然後忘記統一工作階段 ID。
請勿為了讓這項功能運作而在核心中引入提供者或平台特殊案例。核心負責 Talk 工作階段語義。提供者外掛負責廠商工作階段設定。語音通話與 Google Meet 負責電話/會議配接器。瀏覽器與原生應用程式負責裝置擷取/播放使用者體驗。

移除時程

時間會發生什麼
現在已淘汰的介面會發出執行階段警告。
每筆相容記錄的 removeAfter 日期該特定介面符合移除資格;日期過後,pnpm plugins:boundary-report --fail-on-eligible-compat 會讓 CI 失敗。
下一個主要版本任何仍未遷移的介面都會被移除;仍使用它們的外掛將會失敗。
所有核心外掛都已完成遷移。外部外掛應在下一個主要版本前遷移。執行 pnpm plugins:boundary-report,查看你的外掛使用的介面中哪些相容記錄最早到期。

暫時抑制警告

OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
這是暫時的逃生口,不是永久解法。

相關