新增功能（貢獻者指南）

當 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.imageGenerationModel 用於生成影像。

請保持兩者分離，使備援與原則維持明確。

嵌入提供者

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

較舊的記憶功能專用註冊 API 與 memoryEmbeddingProviders 契約已棄用。所有新的嵌入提供者都應使用 registerEmbeddingProvider 與 embeddingProviders。

審查檢查清單

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

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

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

相關內容

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