跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

這是給 OpenClaw 核心開發者的貢獻者指南。如果你正在 建置外部 Plugin，請改參閱建置 plugins。 如需深入的架構參考（能力模型、所有權、載入管線、執行階段輔助工具），請參閱 Plugin 內部架構。
當 OpenClaw 需要新的共享領域時使用此指南，例如影像生成、影片生成，或未來某個由供應商支援的功能領域。 規則：
  • plugin = 所有權邊界
  • capability = 共享核心契約
不要一開始就把供應商直接接到通道或工具中。先從定義能力開始。

​
何時建立 capability

當以下條件全部成立時，建立新的 capability：
  1. 可能有不只一個供應商可實作它。
  2. 通道、工具或功能 plugins 應該能使用它，而不需要在意供應商。
  3. 核心需要擁有 fallback、政策、設定或交付行為。
如果工作只屬於單一供應商，且尚未有共享契約，請停下來先定義契約。

​
標準順序

  1. 定義具型別的核心契約。
  2. 為該契約加入 plugin 註冊。
  3. 加入共享執行階段輔助工具。
  4. 接上一個真實供應商 plugin 作為證明。
  5. 將功能/通道消費端移到執行階段輔助工具上。
  6. 加入契約測試。
  7. 記錄面向操作員的設定與所有權模型。

​
內容放在哪裡

核心：
  • 請求/回應型別。
  • 提供者登錄 + 解析。
  • Fallback 行為。
  • 設定 schema，並在巢狀物件、萬用字元、陣列項目與組合節點上傳播 title / description 文件中繼資料。
  • 執行階段輔助工具介面。
供應商 plugin：
  • 供應商 API 呼叫。
  • 供應商驗證處理。
  • 供應商特定的請求正規化。
  • capability 實作的註冊。
功能/通道 plugin：
  • 呼叫 api.runtime.* 或相符的 plugin-sdk/*-runtime 輔助工具。
  • 絕不直接呼叫供應商實作。

​
提供者與 harness seam

當行為屬於模型提供者契約，而不是通用 agent 迴圈時，使用提供者 hooks。範例包括傳輸選擇後的提供者特定請求參數、驗證設定檔偏好、提示覆蓋，以及模型/設定檔 failover 後的後續 fallback 路由。 當行為屬於正在執行一個 turn 的執行階段時，使用 agent harness hooks。Harnesses 可以分類成功但不可用的嘗試結果，例如空白、僅推理或僅規劃的回應，讓外層模型 fallback 政策能做出重試決策。 讓兩種 seam 都保持狹窄：
  • 核心擁有重試/fallback 政策。
  • 提供者 plugins 擁有提供者特定的請求/驗證/路由提示。
  • Harness plugins 擁有執行階段特定的嘗試分類。
  • 第三方 plugins 回傳提示，而不是直接變更核心狀態。

​
檔案檢查清單

對於新的 capability，預期會碰到這些區域：
  • 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
  • 一個或多個 bundled plugin 套件。
  • 設定、文件、測試。

​
實作範例：影像生成

影像生成遵循標準形狀：
  1. 核心定義 ImageGenerationProvider。
  2. 核心公開 registerImageGenerationProvider(...)。
  3. 核心公開 runtime.imageGeneration.generate(...)。
  4. openai、google、fal 和 minimax plugins 註冊由供應商支援的實作。
  5. 未來的供應商註冊相同契約，而不需要變更通道/工具。
設定鍵刻意與視覺分析路由分開：
  • agents.defaults.imageModel 分析影像。
  • agents.defaults.imageGenerationModel 生成影像。
讓它們保持分離，這樣 fallback 與政策才能維持明確。

​
Review 檢查清單

在發布新的 capability 前，請確認：
  • 沒有通道/工具直接匯入供應商程式碼。
  • 執行階段輔助工具是共享路徑。
  • 至少有一個契約測試會斷言 bundled 所有權。
  • 設定文件命名新的模型/設定鍵。
  • Plugin 文件說明所有權邊界。
如果 PR 跳過 capability 層，並將供應商行為硬編碼到通道/工具中，請退回並先定義契約。

​
相關