外掛進入點

每個外掛都會匯出一個預設進入點物件。SDK 為每種進入點形態提供一個輔助函式：defineToolPlugin、definePluginEntry、 defineChannelPluginEntry、defineSetupPluginEntry。

套件進入點

已安裝的外掛會將 package.json openclaw 欄位同時指向原始碼和 建置後的進入點：

{  "openclaw": {    "extensions": ["./src/index.ts"],    "runtimeExtensions": ["./dist/index.js"],    "setupEntry": "./src/setup-entry.ts",    "runtimeSetupEntry": "./dist/setup-entry.js"  }}

• extensions 和 setupEntry 是原始碼進入點，用於工作區和 git 簽出開發。
• runtimeExtensions 和 runtimeSetupEntry 是已安裝 套件的首選：它們讓 npm 套件能略過執行階段 TypeScript 編譯。
• runtimeExtensions 若存在，其陣列長度必須與 extensions 相同 （進入點依位置配對）。runtimeSetupEntry 需要 setupEntry。
• 如果宣告了 runtimeExtensions/runtimeSetupEntry 成品但 該成品不存在，安裝／探索會因封裝錯誤而失敗；OpenClaw 不會 靜默回退至原始碼。下述原始碼回退僅在完全未宣告 執行階段進入點時適用。
• 如果已安裝的套件僅宣告 TypeScript 原始碼進入點，OpenClaw 會尋找相符的建置後 dist/*.js（或 .mjs/.cjs）對應項目並使用它； 否則會回退至 TypeScript 原始碼。
• 所有進入點路徑都必須位於外掛套件目錄內。執行階段 進入點和推斷出的建置後 JS 對應項目，並不會讓逸出目錄的 extensions 或 setupEntry 原始碼路徑變成有效。

defineToolPlugin

匯入： openclaw/plugin-sdk/tool-plugin

適用於僅新增代理程式工具的外掛。它能保持原始碼精簡、從 TypeBox 結構描述推斷設定 和工具參數型別、將一般回傳值包裝成 OpenClaw 工具結果格式，並公開靜態中繼資料，供 openclaw plugins build 寫入外掛資訊清單（contracts.tools、 configSchema）。

  export default defineToolPlugin({  id: "stock-quotes",  name: "Stock Quotes",  description: "Fetch stock quotes.",  configSchema: Type.Object({    apiKey: Type.Optional(Type.String({ description: "API key." })),  }),  tools: (tool) => [    tool({      name: "quote",      label: "Quote",      description: "Fetch a quote.",      parameters: Type.Object({        symbol: Type.String({ description: "Ticker symbol." }),      }),      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),    }),  ],});

• configSchema 是選用項目；省略時會使用嚴格的空物件結構描述 （產生的資訊清單仍會包含 configSchema）。
• execute 會回傳一般字串或可序列化為 JSON 的值；輔助函式 會將其包裝為文字工具結果，並將 details 設為原始 （未字串化的）回傳值。
• 若要使用自訂工具結果，openclaw/plugin-sdk/tool-results 會匯出 textResult 和 jsonResult。
• 工具名稱是靜態的，因此 openclaw plugins build 會從已宣告的工具推導 contracts.tools，無須手動重複填寫名稱。
• 執行階段載入仍採嚴格模式：已安裝的外掛仍需要 openclaw.plugin.json 和 package.json openclaw.extensions。OpenClaw 絕不會執行外掛程式碼來推斷缺少的資訊清單資料。

definePluginEntry

匯入： openclaw/plugin-sdk/plugin-entry

適用於供應商外掛、進階工具外掛、鉤點外掛，以及任何 不是訊息頻道的項目。

 export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Short summary",  register(api) {    api.registerProvider({/* ... */});    api.registerTool({/* ... */});  },});

• id 必須與你的 openclaw.plugin.json 資訊清單相符。
• 外部工作階段目錄使用 openclaw/plugin-sdk/session-catalog 和 api.registerSessionCatalog({ id, label, list, read, continueSession?, archive? })。 核心擁有 sessions.catalog.* 閘道方法；供應商會回傳主機、 工作階段和正規化的逐字稿投影，而不註冊 RPC。
• kind 已棄用：請改在 openclaw.plugin.json 資訊清單的 kind 欄位中 宣告專用插槽（"memory" 或 "context-engine"）。執行階段進入點的 kind 僅保留作為 舊版外掛的相容性回退。
• configSchema 可以是函式，以進行延遲求值。OpenClaw 會在 首次存取時解析並記憶該結構描述，因此高成本的結構描述建構器只會執行 一次。
• nodeHostCommands 描述項可以定義 isAvailable({ config, env })。 回傳 false 會從無頭節點的閘道宣告中省略該命令及其功能。 OpenClaw 會根據節點本機的啟動設定評估它；命令處理常式在 叫用時仍應驗證可用性。

defineChannelPluginEntry

匯入： openclaw/plugin-sdk/channel-core

使用頻道專屬接線包裝 definePluginEntry：它會自動 呼叫 api.registerChannel({ plugin })、公開選用的根說明命令列介面 中繼資料接縫，並根據註冊模式限制 registerFull。

 export default defineChannelPluginEntry({  id: "my-channel",  name: "My Channel",  description: "Short summary",  plugin: myChannelPlugin,  setRuntime: setMyRuntime,  registerCliMetadata(api) {    api.registerCli(/* ... */);  },  registerFull(api) {    api.registerGatewayMethod(/* ... */);  },});

回呼會依註冊模式執行（完整表格請見 註冊模式）：

• setRuntime 會在除 "cli-metadata" 和 "tool-discovery" 以外的每種模式中執行。請在此儲存執行階段參照，通常透過 createPluginRuntimeStore。
• registerCliMetadata 會針對 "cli-metadata"、"discovery" 和 "full" 執行。請將其作為頻道所擁有之命令列介面描述項的標準位置， 讓根說明維持非啟用狀態、探索快照包含靜態 命令中繼資料，且一般命令列介面註冊仍與完整 外掛載入相容。
• registerFull 僅針對 "full" 和 "tool-discovery" 執行。對於 "tool-discovery"，它會_取代_頻道註冊而執行：OpenClaw 會完全略過 registerChannel/setRuntime，且只呼叫 registerFull，因此你的頻道為獨立工具探索或執行所需的任何供應商／工具註冊 都必須放在該處，而不能置於一般 頻道設定之後。
• 探索註冊是不啟用功能，而不是不匯入：OpenClaw 可能會 評估受信任的外掛進入點和頻道外掛模組，以建構 快照。請讓頂層匯入不產生副作用，並將通訊端、 用戶端、工作程式和服務置於僅限 "full" 的路徑之後。
• 與 definePluginEntry 相同，configSchema 可以是延遲工廠；OpenClaw 會在首次存取時記憶解析後的結構描述。

命令列介面註冊：

• 對於希望延遲載入且不會從根命令列介面 剖析樹中消失的外掛自有根命令列介面命令，請使用 api.registerCli(..., { descriptors: [...] })。 描述項名稱必須由字母、數字、連字號和底線組成，並以字母或數字開頭； OpenClaw 會拒絕其他格式，並在呈現說明前 從描述中移除終端機控制序列。請涵蓋註冊器公開的 每個頂層命令根節點。 僅使用 commands 時，仍會走積極載入的相容性路徑。
• 對於配對節點功能命令，請使用 api.registerNodeCliFeature(...)，使其 位於 openclaw nodes 之下（等同於 registerCli(registrar, { parentPath: ["nodes"], ... })）。
• 對於其他巢狀外掛命令，請新增 parentPath，並在傳給註冊器的 program 物件上註冊命令；OpenClaw 會在呼叫外掛前 將其解析為父命令。
• 對於頻道外掛，請從 registerCliMetadata 註冊命令列介面描述項， 並讓 registerFull 專注於僅限執行階段的工作。
• 如果 registerFull 也註冊閘道 RPC 方法，請將它們置於 外掛專屬前綴下。保留的核心管理命名空間（config.*、 exec.approvals.*、wizard.*、update.*）一律強制轉換為 operator.admin。

defineSetupPluginEntry

匯入： openclaw/plugin-sdk/channel-core

適用於輕量的 setup-entry.ts 檔案。僅回傳 { plugin }，不含 執行階段或命令列介面接線。

 export default defineSetupPluginEntry(myChannelPlugin);

OpenClaw 會在頻道停用、未設定，或啟用延遲載入時，載入此項目而非完整進入點。 如需瞭解這在何種情況下會有影響，請參閱 設定與組態。

將 defineSetupPluginEntry(...) 與範圍明確的設定輔助函式系列搭配使用：

將大型 SDK、命令列介面註冊，以及長期執行的執行階段服務保留在 完整進入點中。

將設定與執行階段介面分開的內建工作區頻道，可改用 來自 openclaw/plugin-sdk/channel-entry-contract 的 defineBundledChannelSetupEntry(...)。這可讓設定 進入點保留設定安全的外掛／密鑰匯出，同時仍公開執行階段 設定函式：

 export default defineBundledChannelSetupEntry({  importMetaUrl: import.meta.url,  plugin: {    specifier: "./channel-plugin-api.js",    exportName: "myChannelPlugin",  },  runtime: {    specifier: "./runtime-api.js",    exportName: "setMyChannelRuntime",  },  registerSetupRuntime(api) {    api.registerHttpRoute({      path: "/my-channel/events",      auth: "plugin",      handler: async (req, res) => {        /* 設定安全的路由 */      },    });  },});

僅在設定流程確實需要輕量執行階段設定函式，或需要在完整頻道進入點載入前提供 設定安全的閘道介面時，才使用此方式。 registerSetupRuntime 僅針對 "setup-runtime" 載入執行；請將其 限制於僅處理組態的路由，或必須在延遲的 完整啟用前存在的方法。

註冊模式

api.registrationMode 會告知外掛其載入方式：

defineChannelPluginEntry 會自動處理此分流。若你直接將 definePluginEntry 用於頻道，請自行檢查模式，並記住 "tool-discovery" 會略過頻道註冊：

register(api) {  if (    api.registrationMode === "cli-metadata" ||    api.registrationMode === "discovery" ||    api.registrationMode === "full"  ) {    api.registerCli(/* ... */);    if (api.registrationMode === "cli-metadata") return;  }   if (api.registrationMode === "tool-discovery") {    // 僅註冊能力介面（提供者／工具），不註冊頻道。    return;  }   api.registerChannel({ plugin: myPlugin });  if (api.registrationMode !== "full") return;   // 僅限大型執行階段的註冊  api.registerService(/* ... */);}

長期執行的服務可透過其服務情境發出小型失效或生命週期事件：

api.registerService({  id: "index-events",  start(ctx) {    ctx.gatewayEvents?.emit("changed", { revision: 1 }, { scope: "operator.read" });  },});

OpenClaw 會將其命名空間設為 plugin.<plugin-id>.changed。事件名稱為單一 小寫區段，承載資料必須是有大小上限的 JSON，而範圍必須是 operator.read、operator.write 或 operator.admin。發射器僅在 服務存續期間存在，並會在停止或啟動失敗後撤銷。應優先使用 版本或失效承載資料，而非完整記錄，讓獲得授權的用戶端透過外掛的範圍限定 閘道方法重新讀取標準狀態。

探索模式會建立不啟用的登錄快照。它仍可 評估外掛進入點與頻道外掛物件，讓 OpenClaw 能夠 註冊頻道能力與靜態命令列介面描述元。將探索期間的模組 評估視為受信任但輕量的操作：頂層不得有網路用戶端、 子程序、監聽器、資料庫連線、背景工作執行緒、 認證資訊讀取，或其他即時執行階段副作用。

將 "setup-runtime" 視為一個時間窗口；在此期間，僅限設定的啟動介面必須 存在，且不會重新進入完整的內建頻道執行階段。適合的項目包括 頻道註冊、設定安全的 HTTP 路由、設定安全的閘道方法， 以及委派的設定輔助函式。大型背景服務、命令列介面註冊器，以及 提供者／用戶端 SDK 啟動程序仍應放在 "full" 中。

外掛形式

OpenClaw 會依照已載入外掛的註冊行為進行分類：

使用 openclaw plugins inspect <id> 查看外掛的形式。

相關內容

• SDK 概觀 - 註冊 API 與子路徑參考
• 執行階段輔助函式 - api.runtime 與 createPluginRuntimeStore
• 設定與組態 - 資訊清單、設定進入點、延遲載入
• 頻道外掛 - 建立 ChannelPlugin 物件
• 提供者外掛 - 提供者註冊與掛鉤