外掛 SDK 概覽

外掛 SDK 是外掛與核心之間的具型別契約。本頁提供應匯入哪些項目以及可註冊哪些項目的參考資訊。

匯入慣例

一律從特定子路徑匯入：

每個子路徑都是精簡且自足的模組。這能加快啟動速度，並防止循環相依問題。對於頻道專用的進入點／建置輔助工具，請優先使用 openclaw/plugin-sdk/channel-core；openclaw/plugin-sdk/core 則保留給範圍更廣的統整介面，以及 buildChannelConfigSchema 等共用輔助工具。

對於頻道設定，請透過 openclaw.plugin.json#channelConfigs 發布該頻道所擁有的 JSON Schema。plugin-sdk/channel-config-schema 子路徑供共用結構描述基本元素與通用建置器使用。OpenClaw 的內建外掛使用 plugin-sdk/bundled-channel-config-schema 來處理保留的內建頻道結構描述。已棄用的相容性匯出仍保留於 plugin-sdk/channel-config-schema-legacy；這兩個內建結構描述子路徑都不是新外掛應遵循的模式。

子路徑參考

外掛 SDK 會以一組按領域分類的精簡子路徑公開（外掛進入點、頻道、提供者、驗證、執行階段、能力、記憶，以及保留的內建外掛輔助工具）。如需依類別整理並附有連結的完整目錄，請參閱外掛 SDK 子路徑。

編譯器進入點清單位於 scripts/lib/plugin-sdk-entrypoints.json；從公開子集扣除 scripts/lib/plugin-sdk-private-local-only-subpaths.json 中所列的儲存庫本機測試／內部子路徑後，便會產生套件匯出。執行 pnpm plugin-sdk:surface 可稽核公開匯出數量。年代足夠久且未由內建擴充功能正式環境程式碼使用的已棄用公開子路徑，記錄於 scripts/lib/plugin-sdk-deprecated-public-subpaths.json；範圍廣泛的已棄用重新匯出彙整模組則記錄於 scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json。

註冊 API

register(api) 回呼會收到具有下列方法的 OpenClawPluginApi 物件：

能力註冊

工作節點提供者也必須在 contracts.workerProviders 中宣告其 ID。核心會先保存持久意圖，再呼叫 provision(profile, operationId)。提供者必須在配置外部資源前驗證設定，並針對永久性的設定檔拒絕拋出 WorkerProviderError。當作業 ID 重複時，provision 必須採用相同的租約。 核心會將已驗證的設定檔設定與租約一併保存，並將該快照提供給必須具備冪等性的 destroy({ leaseId, profile })，以及回傳 active、destroyed 或 unknown 的 inspect({ leaseId, profile })。如此一來，提供者便能在閘道重新啟動或具名設定檔遭移除後，繼續路由生命週期呼叫。SSH 端點的 keyRef 使用 SecretRef，絕不內嵌金鑰內容；此外，端點還須包含來自受信任配置輸出的 hostKey，其格式必須恰為 algorithm base64，不得包含主機名稱或註解。核心會固定 hostKey，絕不信任首次連線提供的金鑰。若提供者會產生動態 keyRef，則可實作 resolveSshIdentity({ leaseId, profile, keyRef })；若有此解析器，便以其結果為準；未實作此解析器的提供者則使用已設定的通用機密解析器。 具有可續期租約的提供者也可實作 renew(leaseId)。 發生暫時性或無法判定的失敗時，inspect 必須拋出錯誤；只有在具權威性的確認不存在時才回傳 unknown。核心會將仍處於啟用狀態的本機記錄標記為孤立記錄；若先前已保存銷毀要求，則將不存在視為拆除完成。

透過 api.registerEmbeddingProvider(...) 註冊的嵌入提供者也必須列於外掛資訊清單的 contracts.embeddingProviders。這是用於產生可重複使用向量的通用嵌入介面。記憶搜尋可取用此通用提供者介面。較舊的 api.registerMemoryEmbeddingProvider(...) 與 contracts.memoryEmbeddingProviders 介面屬於已棄用的相容性機制，供現有的記憶專用提供者遷移期間使用。

仍公開執行階段 batchEmbed(...) 的記憶專用提供者，會繼續使用現有的逐檔批次契約，除非其執行階段明確設定 sourceWideBatchEmbed: true。選擇啟用此設定後，記憶主機即可在主機批次限制內，將來自多個已變更記憶檔案及已啟用來源的區塊，透過單次 batchEmbed(...) 呼叫提交。上傳 JSONL 要求檔案的批次配接器，除了要求數量上限外，也必須在達到上傳大小上限前分割提供者工作。提供者必須依照與 batch.chunks 相同的順序，為每個輸入區塊回傳一個嵌入；若提供者預期逐檔批次，或無法在較大型、涵蓋整個來源的工作中維持輸入順序，請省略此旗標。

工具與命令

對於工具名稱固定且僅包含工具的簡單外掛，請使用 defineToolPlugin。對於混合型外掛或完全動態的工具註冊，請直接使用 api.registerTool(...)。

當代理需要簡短且由命令本身擁有的路由提示時，外掛命令可設定 agentPromptGuidance。該文字應僅描述命令本身；請勿將提供者或外掛專用政策加入核心提示詞建置器。

指引項目可以是套用於所有提示詞介面的舊式字串，也可以是結構化項目：

agentPromptGuidance: [  "Global command hint.",  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },];

結構化的 surfaces 可包含 openclaw_main、codex_app_server、cli_backend、acp_backend 或 subagent。pi_main 仍是 openclaw_main 的已棄用別名。若有意讓指引套用於所有介面，請省略 surfaces。請勿傳入空的 surfaces 陣列；系統會拒絕此設定，避免意外遺失範圍限制後，文字反而成為全域提示詞。

原生 Codex 應用程式伺服器的開發者指示比其他提示詞介面更嚴格：只有明確限定於 codex_app_server 的指引，才會提升至該較高優先順序的通道。為維持相容性，舊式字串指引與未限定範圍的結構化指引仍可供非 Codex 提示詞介面使用。

節點主機命令會在已連線的節點主機上執行，而不是在閘道程序內執行。如果存在 agentTool，節點會在成功連線至閘道後發布描述元；只有在該節點保持連線，且描述元的 command 位於節點核准的命令介面中時，閘道才會將其提供給代理執行。設定 agentTool.defaultPlatforms，可將非危險命令納入預設節點命令允許清單；否則必須明確設定 gateway.nodes.allowCommands 或節點叫用原則。agentTool.name 必須符合提供者的安全要求：以字母開頭、僅使用字母、數字、底線或連字號，且不超過 64 個字元。以 MCP 為後端的節點工具可以設定 agentTool.mcp 中繼資料，讓目錄與工具搜尋介面顯示遠端 MCP 伺服器／工具身分，但執行仍會透過所公告的節點命令進行。

基礎架構

記憶提示詞補充建構器會收到選用的 agentId、agentSessionKey 與 sandboxed 上下文。記憶語料庫補充的 search 與 get 呼叫會收到選用的 agentId 與 sandboxed 上下文。具有代理自有儲存空間的外掛，應在每次呼叫時解析該儲存空間，而不是在註冊期間擷取單一全域路徑。若多代理作業需要代理 ID 但未提供，應採取封閉式失敗，而不是任意選擇一個代理。

Telegram 互動處理常式可以傳回 { submitText }，在處理常式成功後，透過 Telegram 的一般傳入代理路徑路由文字。當傳入原則略過文字或處理失敗時，OpenClaw 會保留回呼按鈕，讓使用者能在阻擋條件改變後重試。此結果欄位為 Telegram 專用；其他頻道維持各自的互動結果契約。

工作流程外掛的主機鉤子

主機鉤子是提供給需要參與主機生命週期，而非僅新增提供者、頻道或工具之外掛的 SDK 接合介面。它們是通用契約；計畫模式可以使用它們，核准工作流程、工作區原則閘門、背景監視器、設定精靈與使用者介面輔助外掛也同樣可以使用。

surface: "tab" 描述元會在控制使用者介面中新增側邊欄分頁。已啟用外掛的分頁描述元會在閘道問候訊息（controlUiTabs）中公告給儀表板用戶端，因此該分頁只會在外掛啟用時顯示。隨附外掛可為其分頁提供第一級儀表板檢視；其他外掛可將 path 設為外掛 HTTP 路由（請參閱 api.registerHttpRoute(...)），由儀表板在沙箱框架中呈現。icon 是儀表板圖示名稱提示，group 選擇側邊欄區段（control 或 agent），order 決定外掛分頁之間的排序，而 requiredScopes 會對缺少這些操作者作用域的連線隱藏該分頁：

api.session.controls.registerControlUiDescriptor({  surface: "tab",  id: "logbook",  label: "Logbook",  description: "Your day as a timeline, built from screen snapshots.",  icon: "sun",  group: "control",  requiredScopes: ["operator.write"],});

新的外掛程式碼請使用分組命名空間：

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

對等的扁平方法仍可作為既有外掛的已棄用相容性別名使用。請勿新增直接呼叫 api.registerSessionExtension、api.enqueueNextTurnInjection、api.registerControlUiDescriptor、api.registerRuntimeLifecycle、api.registerAgentEventSubscription、api.emitAgentEvent、api.setRunContext、api.getRunContext、api.clearRunContext、api.registerSessionSchedulerJob、api.registerSessionAction、api.sendSessionAttachment、api.scheduleSessionTurn 或 api.unscheduleSessionTurnsByTag 的外掛程式碼。

scheduleSessionTurn(...) 是以閘道排程器為基礎、限定工作階段作用域的便利介面。排程負責掌控時間，並在回合執行時建立背景任務記錄；外掛 SDK 僅限制目標工作階段、外掛自有命名與清理。若排定回合中的工作本身需要持久的多步驟 Task Flow 狀態，請使用 api.runtime.tasks.managedFlows。

這些契約刻意劃分權限：

• 外部外掛可擁有工作階段擴充、使用者介面描述元、命令、工具中繼資料、下一回合注入及一般鉤子。
• 受信任工具原則會在一般 before_tool_call 鉤子之前執行，且受主機信任。隨附原則最先執行；已安裝外掛的原則需要明確啟用，並將其本機 ID 加入 contracts.trustedToolPolicies，之後再依外掛載入順序執行。原則 ID 的作用域限於註冊該原則的外掛。
• 保留命令的所有權僅限隨附外掛。外部外掛應使用自己的命令名稱或別名。
• allowPromptInjection=false 會停用修改提示詞的鉤子，包括 agent_turn_prepare、before_prompt_build、heartbeat_prompt_contribution、舊版 before_agent_start 的提示詞欄位，以及 enqueueNextTurnInjection。

非計畫模式使用者的範例：

閘道探索註冊

api.registerGatewayDiscoveryService(...) 讓外掛可透過 mDNS/Bonjour 等本機探索傳輸公告作用中的閘道。啟用本機探索時，OpenClaw 會在閘道啟動 期間呼叫此服務，傳入目前的閘道連接埠與非機密的 TXT 提示資料，並在閘道 關閉期間呼叫傳回的 stop 處理常式。

api.registerGatewayDiscoveryService({  id: "my-discovery",  async advertise(ctx) {    const handle = await startMyAdvertiser({      gatewayPort: ctx.gatewayPort,      tls: ctx.gatewayTlsEnabled,      displayName: ctx.machineDisplayName,    });    return { stop: () => handle.stop() };  },});

閘道探索外掛不得將公告的 TXT 值視為機密或驗證資訊。探索僅是路由提示； 信任仍由閘道驗證與 TLS 固定負責。

命令列介面註冊中繼資料

api.registerCli(registrar, opts?) 接受兩種命令中繼資料：

• commands：註冊器擁有的明確命令名稱
• descriptors：用於命令列介面說明、路由及延遲外掛命令列介面註冊的 剖析階段命令描述元
• parentPath：巢狀命令群組的選用父命令路徑，例如 ["nodes"]

對於配對節點功能，請優先使用 api.registerNodeCliFeature(registrar, opts?)。這是 api.registerCli(..., { parentPath: ["nodes"] }) 的小型包裝器，可明確指出 openclaw nodes canvas 等命令是由外掛擁有的節點功能。

若要讓外掛命令在一般根命令列介面路徑中維持延遲載入，請提供 descriptors，涵蓋該註冊器公開的每個頂層命令根。

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "Manage Matrix accounts, verification, devices, and profile state",        hasSubcommands: true,      },    ],  },);

巢狀命令會以 program 接收解析後的父命令：

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "Capture or render canvas content from a paired node",        hasSubcommands: true,      },    ],  },);

只有在不需要延遲根命令列介面註冊時，才單獨使用 commands。這條立即載入的 相容性路徑仍受支援，但不會安裝由描述元支援、供剖析階段延遲載入使用的 預留位置。

命令列介面後端註冊

api.registerCliBackend(...) 讓外掛可擁有 claude-cli 或 my-cli 等本機 AI 命令列介面後端的預設設定。

• 後端 id 會成為 my-cli/gpt-5 等模型參照中的提供者前綴。
• 後端 config 使用與 agents.defaults.cliBackends.<id> 相同的結構。
• 使用者設定仍具有優先權。OpenClaw 會先將 agents.defaults.cliBackends.<id> 合併覆蓋於外掛預設值，再執行命令列介面。
• 當後端需要在合併後進行相容性改寫時（例如正規化舊旗標結構），請使用 normalizeConfig。
• 對於屬於命令列介面方言的請求範圍 argv 改寫，請使用 resolveExecutionArgs，例如將 OpenClaw 的思考層級對應至原生投入程度旗標。 此掛鉤會接收 ctx.executionMode；請使用 "side-question" 為暫時性的 /btw 呼叫加入後端原生隔離旗標。若這些旗標能可靠地停用原本總是啟用的 命令列介面原生工具，也請宣告 sideQuestionToolMode: "disabled"。
• 可在特定執行中停用所有原生工具的後端，可以宣告 nativeToolMode: "selectable"。受限制的呼叫會傳入空的 ctx.toolAvailability.native 元組，以及精確且由主機隔離的 MCP 允許清單； resolveExecutionArgs 必須在最終全新或續接的 argv 上強制執行兩者。 若後端無法做到，OpenClaw 會採取封閉式失敗。

如需端對端的編寫指南，請參閱 命令列介面後端外掛。

獨佔插槽

已棄用的記憶體嵌入配接器

• registerMemoryCapability 是建議使用的獨佔記憶體外掛 API。
• registerMemoryCapability 也可以公開 publicArtifacts.listArtifacts(...)， 讓配套外掛透過 openclaw/plugin-sdk/memory-host-core 使用匯出的記憶體成品， 而不需存取特定記憶體外掛的私有配置。
• registerMemoryPromptSection、registerMemoryFlushPlan 與 registerMemoryRuntime 是具舊版相容性的獨佔記憶體外掛 API。
• MemoryFlushPlan.model 可將清除輪次固定至確切的 provider/model 參照，例如 ollama/qwen3:8b，而不繼承作用中的後援鏈。
• registerMemoryEmbeddingProvider 已棄用。新的嵌入提供者應使用 api.registerEmbeddingProvider(...) 與 contracts.embeddingProviders。
• 現有的記憶體專用提供者在遷移期間仍可繼續運作，但對非隨附外掛而言， 外掛檢查會將此項報告為相容性債務。

事件與生命週期

如需範例、常見掛鉤名稱及防護語意，請參閱 外掛掛鉤。

掛鉤決策語意

before_install 是外掛執行階段生命週期掛鉤，而非操作員安裝政策介面。 當允許／封鎖決策必須涵蓋命令列介面與閘道支援的安裝或更新路徑時，請使用 security.installPolicy。

• before_tool_call：回傳 { block: true } 會終止處理。一旦任何處理常式設定此值，就會略過優先順序較低的處理常式。
• before_tool_call：回傳 { block: false } 會視為未做決定（等同省略 block），而非覆寫先前的決定。
• before_install：回傳 { block: true } 會終止處理。一旦任何處理常式設定此值，就會略過優先順序較低的處理常式。
• before_install：回傳 { block: false } 會視為未做決定（等同省略 block），而非覆寫先前的決定。
• reply_dispatch：回傳 { handled: true, ... } 會終止處理。一旦任何處理常式接管分派，就會略過優先順序較低的處理常式與預設模型分派路徑。
• message_sending：回傳 { cancel: true } 會終止處理。一旦任何處理常式設定此值，就會略過優先順序較低的處理常式。
• message_sending：回傳 { cancel: false } 會視為未做決定（等同省略 cancel），而非覆寫先前的決定。
• message_received：需要路由傳入的討論串／主題時，請使用具型別的 threadId 欄位。metadata 應保留給頻道特有的額外資料。
• message_sending：優先使用具型別的 replyToId／threadId 路由欄位，再退回使用頻道特有的 metadata。
• gateway_start：請使用 ctx.config、ctx.workspaceDir 與 ctx.getCron?.() 取得閘道擁有的啟動狀態，而不要依賴內部 gateway:startup 鉤子。此時排程可能仍在載入。
• cron_reconciled：在啟動或排程器重新載入後，重建完整的外部排程投影。它包含 reason 與實際生效的 enabled 狀態（包括 enabled: false），而 ctx.getCron?.() 會回傳完成協調後的確切排程器。請將 ctx.abortSignal 傳入持久化投影作業；當該排程器快照被取代或閘道關閉時，它會中止作業。
• cron_changed：觀察閘道擁有的排程生命週期變更。scheduled 與 removed 事件是提交後的協調提示，而非有序的差異記錄。若工作沒有下一次喚醒時間，排程事件的 event.nextRunAtMs 將不存在；移除事件仍會攜帶已刪除工作的快照。

外部喚醒排程器應對 cron_changed 事件進行防抖或合併， 然後從 cron_reconciled 最後擷取的排程器重新讀取完整的持久化檢視。 請勿採用 cron_changed 上下文中的排程器：來自較舊排程器的分離提示， 可能會與後續重新載入重疊。

對於在閘道啟動或排程器替換時載入的持久化狀態，請使用 cron_reconciled 作為完整快照觸發條件。僅重新載入外掛時不會重播此事件。 觀察處理常式會平行執行，而即發即棄的分派可能彼此重疊，因此消費端不得 依賴事件完成順序。到期檢查與執行應以 OpenClaw 為唯一真實來源。

如需具備持久化替換、重試／退避與乾淨關閉功能的單次執行轉接器， 請參閱安全的外部排程投影。

API 物件欄位

內部模組慣例

在外掛內部，請使用本機彙總檔案進行內部匯入：

my-plugin/  api.ts            # 提供給外部使用者的公開匯出  runtime-api.ts    # 僅供內部使用的執行階段匯出  index.ts          # 外掛進入點  setup-entry.ts    # 僅供設定使用的輕量進入點（選填）

透過外觀載入的內建外掛公開介面（api.ts、runtime-api.ts、 index.ts、setup-entry.ts 及類似的公開進入檔案）會在 OpenClaw 已執行時，優先使用作用中的執行階段設定快照。若執行階段快照尚不存在， 則會退回使用磁碟上已解析的設定檔。封裝後的內建外掛外觀應透過 OpenClaw 的外掛外觀載入器載入；直接從 dist/extensions/... 匯入會略過封裝安裝 用於外掛自有程式碼的資訊清單與執行階段附屬檔案檢查。

當輔助工具刻意僅供特定供應商使用，且尚不適合置於通用 SDK 子路徑時， 供應商外掛可以公開範圍狹窄的外掛本機契約彙總介面。內建範例：

• Anthropic：公開的 api.ts／contract-api.ts 接合介面，用於 Claude 測試版標頭與 service_tier 串流輔助工具。
• @openclaw/openai-provider：api.ts 匯出供應商建構器、 預設模型輔助工具與即時供應商建構器。
• @openclaw/openrouter-provider：api.ts 匯出供應商建構器， 以及初始設定／組態輔助工具。

相關內容