新增功能（貢獻者指南）

當 OpenClaw 需要新的共享領域（例如嵌入、影像生成、影片生成，或未來由供應商支援的某個功能領域）時，請使用此模式。

規則：

• 外掛 = 所有權邊界
• 能力 = 共享核心合約

請勿將供應商直接接入頻道或工具。請先定義能力。

何時建立能力

只有在以下條件全部成立時，才能建立新能力：

1. 可能有多個供應商能合理地實作此能力。
2. 頻道、工具或功能外掛應能使用此能力，而不必在意供應商。
3. 核心需要擁有備援、政策、設定或交付行為。

如果這項工作僅限單一供應商，且尚無共享合約，請先定義合約。

標準順序

1. 定義具型別的核心合約。
2. 為該合約新增外掛註冊機制。
3. 新增共享的執行階段輔助函式。
4. 接入一個真正的供應商外掛作為驗證。
5. 將功能／頻道使用端移至執行階段輔助函式。
6. 新增合約測試。
7. 記錄面向操作者的設定與所有權模型。

各層的職責

提供者與執行框架接合點

當行為屬於模型提供者合約而非通用代理迴圈時，請使用提供者掛鉤。例如，在選定傳輸方式後加入提供者專屬的請求參數、驗證設定檔偏好、提示詞覆疊，以及模型／設定檔容錯移轉後的後續備援路由。

當行為屬於執行某一回合的執行階段時，請使用代理執行框架掛鉤。執行框架可分類明確的通訊協定結果，例如輸出為空、只有推理而沒有可見輸出，或具有結構化計畫但沒有最終答案，讓外層模型備援政策能決定是否重試。

讓這兩個接合點保持精簡：

• 核心擁有重試／備援政策。
• 提供者外掛擁有提供者專屬的請求／驗證／路由提示。
• 執行框架外掛擁有執行階段專屬的嘗試分類。
• 第三方外掛回傳提示，而非直接變更核心狀態。

檔案檢查清單

新增能力時，預期會觸及以下區域：

• src/<capability>/types.ts
• src/<capability>/...registry/runtime.ts
• src/plugins/types.ts
• src/plugins/registry.ts
• src/plugins/captured-registration.ts
• src/plugins/contracts/registry.ts
• src/plugins/runtime/types-core.ts
• src/plugins/runtime/index.ts
• src/plugin-sdk/<capability>.ts
• src/plugin-sdk/<capability>-runtime.ts
• 一個或多個內建外掛套件。
• 設定、文件、測試。

實作範例：影像生成

影像生成遵循標準模式：

1. 核心定義 ImageGenerationProvider。
2. 核心公開 registerImageGenerationProvider(...)。
3. 核心公開 api.runtime.imageGeneration.generate(...) 和 .listProviders(...)。
4. 供應商外掛（comfy、deepinfra、fal、google、litellm、microsoft-foundry、minimax、openai、openrouter、vydra、xai）註冊由供應商支援的實作。
5. 未來的供應商可註冊相同合約，而不必變更頻道／工具。

此設定鍵刻意與視覺分析路由分開：

• agents.defaults.imageModel 分析影像。
• agents.defaults.mediaModels.image 生成影像。

請將兩者分開，讓備援與政策維持明確。

嵌入提供者

可重複使用的向量嵌入提供者，請使用 registerEmbeddingProvider(...)／合約 embeddingProviders。 此合約刻意涵蓋比記憶體更廣泛的用途：工具、搜尋、檢索、匯入程式或未來的功能外掛， 都能使用嵌入，而不必依賴記憶體引擎。記憶體搜尋 也會使用通用的 embeddingProviders。

較舊的記憶體專屬註冊 API 與 memoryEmbeddingProviders 合約已棄用。所有新的嵌入提供者都請使用 registerEmbeddingProvider 和 embeddingProviders。

審查檢查清單

發布新能力之前，請確認：

• 沒有任何頻道／工具直接匯入供應商程式碼。
• 執行階段輔助函式是共用路徑。
• 至少有一項合約測試會驗證內建所有權。
• 設定文件會指出新的模型／設定鍵。
• 外掛文件會說明所有權邊界。

如果 PR 略過能力層，並將供應商行為硬編碼至頻道／工具中，請退回該 PR，並先定義合約。

相關內容

• 外掛內部架構 — 能力模型、所有權、載入流水線、執行階段輔助函式。
• 建置外掛 — 第一個外掛教學。
• SDK 概覽 — 匯入對應表與註冊 API 參考資料。
• 建立 Skills — 配套的貢獻者介面。