OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Building plugins

建置外掛

外掛可擴充 OpenClaw，而無須變更核心。外掛可新增訊息 頻道、模型提供者、本機命令列介面後端、代理程式工具、掛鉤、媒體提供者， 或其他由外掛擁有的功能。

你不需要將外部外掛新增至 OpenClaw 儲存庫。將 套件發布至 ClawHub，使用者即可使用以下指令安裝：

bash
openclaw plugins install clawhub:<package-name>

在推出切換期間，裸套件規格仍會從 npm 安裝。當你要使用 ClawHub 解析時，請使用 clawhub: 前綴。

需求

  • Node 22.22.3+、Node 24.15+ 或 Node 25.9+，以及 npm 或 pnpm。
  • TypeScript ESM 模組。
  • 若要在儲存庫內開發隨附外掛，請複製儲存庫並執行 pnpm install。 來源簽出中的外掛開發僅支援 pnpm，因為 OpenClaw 會從 extensions/* 工作區套件探索隨附外掛。

選擇外掛形式

頻道外掛

將 OpenClaw 連接至訊息平台。
提供者外掛

新增模型、媒體、搜尋、擷取、語音或即時提供者。
命令列介面後端外掛

透過 OpenClaw 模型備援執行本機 AI 命令列介面。
工具外掛

註冊代理程式工具。

快速入門

註冊一個必要的代理程式工具，以建置最小化的工具外掛。這是 最精簡且實用的外掛形式，涵蓋套件、中繼資料清單、進入點和 本機驗證。

  • 建立套件中繼資料

    package.json
    {"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","dependencies": {"typebox": "1.1.39"},"peerDependencies": {"openclaw": ">=2026.3.24-beta.2"},"openclaw": {"extensions": ["./index.ts"],"compat": {"pluginApi": ">=2026.3.24-beta.2","minGatewayVersion": "2026.3.24-beta.2"},"build": {"openclawVersion": "2026.3.24-beta.2","pluginSdkVersion": "2026.3.24-beta.2"}}}
    openclaw.plugin.json
    {"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {"tools": ["my_tool"]},"activation": {"onStartup": true},"configSchema": {"type": "object","additionalProperties": false}}

    已發布的外部外掛應讓執行階段進入點指向已建置的 JavaScript 檔案。完整的進入點契約請參閱 SDK 進入點。

    每個外掛都需要中繼資料清單，即使沒有設定也一樣。執行階段工具必須 出現在 contracts.tools 中，讓 OpenClaw 無須 預先載入每個外掛執行階段，即可探索擁有權。請刻意設定 activation.onStartup； 此範例會在閘道啟動時載入。

    主機信任的外掛介面也受中繼資料清單控管，且已安裝的外掛必須 明確宣告：api.registerAgentToolResultMiddleware(...) 要求在 contracts.agentToolResultMiddleware 中列出每個目標執行階段， 而 api.registerTrustedToolPolicy(...) 則要求在 contracts.trustedToolPolicies 中列出每個原則 ID。這些宣告可使安裝時的 檢查與執行階段註冊保持一致。

    如需所有中繼資料清單欄位的資訊，請參閱外掛中繼資料清單。

  • 註冊工具

    index.ts
    import { Type } from "typebox";import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Adds a custom tool to OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Echo one input value",      parameters: Type.Object({ input: Type.String() }),      async execute(_id, params) {        return {          content: [{ type: "text", text: `Got: ${params.input}` }],        };      },    });  },});

    非頻道外掛請使用 definePluginEntry。頻道外掛則改用 openclaw/plugin-sdk/core 中的 defineChannelPluginEntry。

  • 測試執行階段

    對於已安裝或外部外掛，請檢查已載入的執行階段：

    bash
    openclaw plugins inspect my-plugin --runtime --json

    如果外掛註冊了命令列介面指令，也請執行該指令並確認 輸出，例如 openclaw demo-plugin ping。

    對於此儲存庫中的隨附外掛，OpenClaw 會從 extensions/* 工作區探索來源簽出的外掛套件。請執行最接近的針對性 測試：

    bash
    pnpm test extensions/my-plugin/pnpm check

  • 測試套件安裝

    發布準備就緒的套件外掛之前，請測試使用者將取得的相同安裝形式。 請先新增建置步驟，讓 openclaw.extensions 等執行階段進入點 指向 ./dist/index.js 等已建置的 JavaScript，並確保 npm pack 包含該 dist/ 輸出。TypeScript 原始碼進入點 僅適用於來源簽出和本機開發路徑。

    接著封裝外掛，並使用 npm-pack: 安裝 tarball：

    bash
    npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

    npm-pack: 使用 OpenClaw 管理的個別外掛 npm 專案，因此能找出 來源簽出測試可能隱藏的執行階段相依性錯誤。它可驗證 套件及相依性形式，但無法驗證連結目錄的官方信任狀態。 執行階段匯入項目必須位於 dependencies 或 optionalDependencies； 僅留在 devDependencies 中的相依性不會安裝至 受管理的執行階段專案。

    請勿使用原始封存檔／路徑安裝，作為官方或 特權外掛行為的最終驗證。原始來源適合用於本機偵錯，但 無法驗證與 npm 或 ClawHub 安裝相同的相依性路徑。如果 你的外掛依賴受信任的官方外掛狀態，請透過目錄支援的官方安裝， 或會記錄官方信任狀態的已發布套件路徑，新增第二項驗證。關於 安裝根目錄和相依性擁有權的詳細資訊，請參閱 外掛相依性解析。

  • 發布

    發布前請驗證套件：

    bash
    clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

    標準 ClawHub 套件片段位於 docs/snippets/plugin-publish/。

  • 安裝

    透過 ClawHub 安裝已發布的套件：

    bash
    openclaw plugins install clawhub:your-org/your-plugin

    • 註冊工具

    工具可以是必要或選用。外掛啟用時，必要工具一律可用。選用工具 需要使用者明確選擇加入，OpenClaw 才會載入擁有該工具的外掛執行階段。

    工具工廠會接收受信任的執行階段情境，包括 deliveryContext、 可用時目前平台對話的 nativeChannelId，以及 requesterSenderId。

    typescript
    register(api) {  api.registerTool(    {      name: "workflow_tool",      description: "Run a workflow",      parameters: Type.Object({ pipeline: Type.String() }),      async execute(_id, params) {        return { content: [{ type: "text", text: params.pipeline }] };      },    },    { optional: true },  );}

    每個使用 api.registerTool(...) 註冊的工具，也必須在 外掛中繼資料清單中宣告：

    json
    {  "contracts": {    "tools": ["workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

    使用者可透過 tools.allow 選擇加入：

    json5
    {  tools: { allow: ["workflow_tool"] }, // 或使用 ["my-plugin"] 允許單一外掛中的所有工具}

    選用工具會控制工具是否向模型公開。若工具 或掛鉤應在模型選取後、動作執行前要求核准，請使用 外掛權限要求。

    對於具有副作用、使用罕見二進位檔，或預設不應公開的功能， 請使用選用工具。工具名稱不得與核心工具名稱衝突；衝突項目會被略過， 並在外掛診斷中回報。格式錯誤的註冊也會以相同方式略過並回報： 缺少非空的 name、execute 不是函式， 或工具描述元缺少 parameters 物件。

    工具工廠會接收由執行階段提供的情境物件。如果工具需要針對目前回合的 作用中模型進行記錄、顯示或調整，請使用 ctx.activeModel； 其中可包含 provider、modelId 和 modelRef。請將其視為 資訊性執行階段中繼資料，而不是用來防範本機操作者、已安裝外掛程式碼， 或經修改 OpenClaw 執行階段的安全界線。敏感的本機工具仍應要求 外掛或操作者明確選擇加入，且當作用中模型中繼資料遺失或不適用時， 必須採取封閉式失敗。

    中繼資料清單宣告擁有權和探索資訊；執行時仍會呼叫即時 註冊的工具實作。請保持 toolMetadata.<tool>.optional: true 與 api.registerTool(..., { optional: true }) 一致，讓 OpenClaw 能避免 載入該外掛執行階段，直到工具明確加入允許清單為止。

    匯入慣例

    從特定用途的 SDK 子路徑匯入：

    typescript

    請勿從已棄用的根 barrel 匯入：

    typescript

    在你的外掛套件中，內部匯入請使用 api.ts 和 runtime-api.ts 等本機 barrel 檔案。請勿透過 SDK 路徑匯入你自己的 外掛。提供者專用的輔助程式應留在提供者套件中，除非 該介面確實具備通用性。

    自訂閘道 RPC 方法是進階進入點。請使用 外掛專用前綴；config.*、 exec.approvals.*、operator.admin.*、wizard.* 和 update.* 等核心管理命名空間仍為保留， 並解析為 operator.admin。 openclaw/plugin-sdk/gateway-method-runtime 橋接器保留給宣告 contracts.gatewayMethodDispatch: ["authenticated-request"] 的外掛 HTTP 路由。

    完整的匯入對應表請參閱外掛 SDK 概觀。

    提交前檢查清單

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json 具有正確的 openclaw 中繼資料 OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json 中繼資料清單存在且有效 OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s 進入點使用 defineChannelPluginEntry 或 definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s 所有匯入均使用特定用途的 plugin-sdk/<subpath> 路徑 OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page