跳轉到主要內容
每個外掛都會匯出一個預設進入點物件。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 checkout 開發。
  • 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）。 
import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

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 用於提供者外掛、進階工具外掛、鉤子外掛，以及任何不是訊息頻道的項目。 
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
  },
});
欄位類型必填預設值
idstring是-
namestring是-
descriptionstring是-
kindstring（已淘汰，見下方）否-
configSchemaOpenClawPluginConfigSchema | () => OpenClawPluginConfigSchema否空物件結構描述
reloadOpenClawPluginReloadRegistration否-
nodeHostCommandsOpenClawPluginNodeHostCommand[]否-
securityAuditCollectorsOpenClawPluginSecurityAuditCollector[]否-
register(api: OpenClawPluginApi) => void是-
  • id 必須符合你的 openclaw.plugin.json 資訊清單。
  • kind 已淘汰：請改在 openclaw.plugin.json 資訊清單的 kind 欄位中宣告專屬槽位（"memory" 或 "context-engine"）。執行階段進入點的 kind 只會作為舊版外掛的相容性退回。
  • configSchema 可以是函式，以便延遲求值。OpenClaw 會在首次存取時解析並記憶結構描述，因此昂貴的結構描述建構器只會執行一次。

​
defineChannelPluginEntry

匯入： openclaw/plugin-sdk/channel-core 以頻道專屬接線包裝 definePluginEntry：它會自動呼叫 api.registerChannel({ plugin })，公開選用的根說明命令列介面中繼資料接縫，並依註冊模式控管 registerFull。 
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});
欄位類型必填預設值
idstring是-
namestring是-
descriptionstring是-
pluginChannelPlugin是-
configSchemaOpenClawPluginConfigSchema | () => OpenClawPluginConfigSchema否空物件結構描述
setRuntime(runtime: PluginRuntime) => void否-
registerCliMetadata(api: OpenClawPluginApi) => void否-
registerFull(api: OpenClawPluginApi) => void否-
回呼會依註冊模式執行（完整表格見註冊模式）：
  • setRuntime 會在除了 "cli-metadata" 和 "tool-discovery" 之外的每種模式中執行。通常透過 createPluginRuntimeStore 在這裡儲存執行階段參照。
  • registerCliMetadata 會在 "cli-metadata"、"discovery" 和 "full" 中執行。請將它作為頻道擁有的命令列介面描述元的標準位置，讓根說明保持不啟用、探索快照包含靜態命令中繼資料，且一般命令列介面註冊與完整外掛載入保持相容。
  • registerFull 只會在 "full" 和 "tool-discovery" 中執行。對於 "tool-discovery"，它會取代頻道註冊而執行：OpenClaw 會完全略過 registerChannel/setRuntime，只呼叫 registerFull，因此你的頻道若需要任何提供者/工具註冊來進行獨立工具探索或執行，必須放在這裡，而不是藏在一般頻道設定後面。
  • 探索註冊是不啟用的，但不是免匯入：OpenClaw 可能會評估受信任的外掛進入點和頻道外掛模組來建立快照。請讓頂層匯入沒有副作用，並將 sockets、clients、workers 和 services 放在只有 "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 }，沒有執行階段或命令列介面接線。 
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);
當頻道停用、未設定，或啟用延遲載入時，OpenClaw 會載入此項目而非完整進入點。請參閱設定與組態了解何時重要。 將 defineSetupPluginEntry(...) 與狹義的設定輔助函式系列搭配使用：
匯入用途
openclaw/plugin-sdk/setup-runtime執行階段安全的設定輔助工具：createSetupTranslator、匯入安全的設定修補配接器、查找附註輸出、promptResolvedAllowFrom、splitSetupEntries、委派的設定代理
openclaw/plugin-sdk/channel-setup選用安裝設定介面
openclaw/plugin-sdk/setup-tools設定/安裝命令列介面、封存與文件輔助工具
請將大型 SDK、命令列介面註冊，以及長期執行的執行階段服務保留在 完整進入點中。 拆分設定與執行階段介面的 bundled 工作區通道，則可以改用 openclaw/plugin-sdk/channel-entry-contract 中的 defineBundledChannelSetupEntry(...)。它讓設定進入點保留設定安全的 外掛/secret 匯出，同時仍公開執行階段 setter： 
import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

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) => {
        /* setup-safe route */
      },
    });
  },
});
只有在設定流程確實需要輕量執行階段 setter，或在完整通道進入點載入前 需要設定安全的閘道介面時，才使用此方式。 registerSetupRuntime 只會在 "setup-runtime" 載入時執行；請將它 限制在僅設定用路由，或必須在延後的完整啟用之前存在的方法。

​
註冊模式

api.registrationMode 會告訴你的外掛它是如何被載入的：
模式時機要註冊的內容
"full"一般閘道啟動所有內容
"discovery"唯讀能力探索通道註冊加上靜態命令列介面描述元；進入點程式碼可以載入，但略過 socket、worker、client 與服務
"tool-discovery"用於列出或執行特定外掛工具的範圍載入僅註冊能力/工具；不啟用通道
"setup-only"停用/未設定的通道僅通道註冊
"setup-runtime"具有可用執行階段的設定流程通道註冊加上完整進入點載入前所需的輕量執行階段
"cli-metadata"根說明 / 命令列介面中繼資料擷取僅命令列介面描述元
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") {
    // Register capability-only surfaces (providers/tools), no channel.
    return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Heavy runtime-only registrations
  api.registerService(/* ... */);
}
探索模式會建立不啟用的 registry 快照。它仍可能評估外掛進入點和通道外掛物件， 讓 OpenClaw 可以註冊通道能力與靜態命令列介面描述元。請將探索期間的模組評估 視為受信任但輕量：頂層不得有網路 client、子行程、listener、資料庫連線、 背景 worker、憑證讀取，或其他即時執行階段副作用。 請將 "setup-runtime" 視為設定專用啟動介面必須存在、但不重新進入完整 bundled 通道執行階段的時段。適合的內容包括通道註冊、設定安全的 HTTP 路由、設定安全的 閘道方法，以及委派的設定輔助工具。大型背景服務、命令列介面 registrar，以及 provider/client SDK 啟動程序仍屬於 "full"。

​
外掛形態

OpenClaw 會依照載入外掛的註冊行為分類：
形態說明
plain-capability一種能力類型（例如僅 provider）
hybrid-capability多種能力類型（例如 provider + speech）
hook-only只有 hook，沒有能力
non-capability工具/指令/服務，但沒有能力
使用 openclaw plugins inspect <id> 查看外掛的形態。

​
相關