跳轉到主要內容
外掛可擴充 OpenClaw，而無需變更核心。外掛可以新增訊息 通道、模型供應商、本機命令列介面後端、代理工具、hook、媒體供應商， 或另一個由外掛擁有的能力。 你不需要將外部外掛加入 OpenClaw 儲存庫。請將 套件發布到 ClawHub，使用者可透過以下方式安裝： 
openclaw plugins install clawhub:<package-name>
裸套件規格在啟動切換期間仍會從 npm 安裝。當你想要使用 ClawHub 解析時，請使用 clawhub: 前綴。

​
需求

  • 節點 22.19+、節點 23.11+，或節點 24+，以及 npm 或 pnpm。
  • TypeScript ESM 模組。
  • 若要進行儲存庫內建外掛工作，請複製儲存庫並執行 pnpm install。 原始碼 checkout 的外掛開發僅支援 pnpm，因為 OpenClaw 會從 extensions/* 工作區套件探索內建外掛。

​
選擇外掛形態

通道外掛

將 OpenClaw 連接到訊息平台。

供應商外掛

新增模型、媒體、搜尋、擷取、語音或即時供應商。

命令列介面後端外掛

透過 OpenClaw 模型後備執行本機 AI 命令列介面。

工具外掛

註冊代理工具。

​
快速開始

透過註冊一個必要代理工具來建置最小工具外掛。這是 最短且實用的外掛形態，涵蓋套件、manifest、進入點與 本機驗證。
1

建立套件中繼資料

{
  "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"
    }
  }
}

{
  "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
  }
}
已發布的外部外掛應將 runtime 進入點指向建置後的 JavaScript 檔案。完整進入點契約請參閱 SDK 進入點。每個外掛都需要 manifest，即使沒有設定也一樣。Runtime 工具必須 出現在 contracts.tools 中，讓 OpenClaw 不必急切載入每個外掛 runtime 就能探索擁有權。請有意識地設定 activation.onStartup； 此範例會在閘道啟動時載入。主機信任的外掛介面也由 manifest 閘控，且已安裝的外掛需要明確 宣告：api.registerAgentToolResultMiddleware(...) 需要將每個目標 runtime 列在 contracts.agentToolResultMiddleware 中， 而 api.registerTrustedToolPolicy(...) 需要將每個 policy id 列在 contracts.trustedToolPolicies 中。這些宣告可讓安裝時檢查 與 runtime 註冊保持一致。每個 manifest 欄位請參閱 外掛 manifest。
2

註冊工具

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。
3

測試 runtime

對已安裝或外部外掛，檢查已載入的 runtime：
openclaw plugins inspect my-plugin --runtime --json
如果外掛註冊了命令列介面命令，也請執行該命令並確認 輸出，例如 openclaw demo-plugin ping。對此儲存庫中的內建外掛，OpenClaw 會從 extensions/* 工作區 探索原始碼 checkout 的外掛套件。執行最接近的目標 測試：
pnpm test extensions/my-plugin/
pnpm check
4

測試套件安裝

發布可封裝外掛前，請測試使用者將取得的相同安裝形態。 先新增建置步驟，將 openclaw.extensions 等 runtime 進入點 指向像 ./dist/index.js 這樣的建置後 JavaScript，並確保 npm pack 包含該 dist/ 輸出。TypeScript 原始碼進入點 僅適用於原始碼 checkout 與本機開發路徑。然後封裝外掛，並使用 npm-pack: 安裝 tarball：
npm pack --pack-destination /tmp
openclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --force
openclaw plugins inspect my-plugin --runtime --json
npm-pack: 使用 OpenClaw 管理的個別外掛 npm 專案，因此可以抓出 原始碼 checkout 測試可能隱藏的 runtime 相依性錯誤。它證明的是 套件與相依性形態，而不是與 catalog 連結的官方信任。 Runtime 匯入必須位於 dependencies 或 optionalDependencies； 僅留在 devDependencies 中的相依性不會安裝到 受管理的 runtime 專案。不要將原始封存/路徑安裝作為官方或 特權外掛行為的最終驗證。原始碼對本機除錯很有用，但 它們無法證明與 npm 或 ClawHub 安裝相同的相依性路徑。如果 你的外掛依賴受信任官方外掛狀態，請加入第二項驗證， 透過以 catalog 為基礎的官方安裝，或透過記錄官方信任的 已發布套件路徑。安裝根與相依性擁有權細節請參閱 外掛相依性解析。
5

發布

發布前驗證套件：
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
標準 ClawHub 套件片段位於 docs/snippets/plugin-publish/。
6

安裝

透過 ClawHub 安裝已發布套件：
openclaw plugins install clawhub:your-org/your-plugin

​
註冊工具

工具可以是必要或選用。當外掛啟用時，必要工具一律可用。 選用工具需要使用者明確選擇加入，OpenClaw 才會載入 擁有該工具的外掛 runtime。 
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(...) 註冊的工具，也必須在 外掛 manifest 中宣告： 
{
  "contracts": {
    "tools": ["workflow_tool"]
  },
  "toolMetadata": {
    "workflow_tool": {
      "optional": true
    }
  }
}
使用者透過 tools.allow 選擇加入： 
{
  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool from one plugin
}
選用工具控制工具是否暴露給模型。當工具 或 hook 應在模型選擇後、動作執行前要求核准時，請使用 外掛權限請求。 對副作用、不常見的二進位檔，或不應預設暴露的能力使用選用工具。 工具名稱不得與核心工具名稱衝突；衝突會被略過並在外掛診斷中回報。 格式錯誤的註冊也會以相同方式略過並回報：缺少非空白 name、非函式 execute，或沒有 parameters 物件的工具描述子。 工具 factory 會接收 runtime 提供的 context 物件。當工具需要記錄、 顯示，或依目前回合的作用中模型調整時，請使用 ctx.activeModel； 它可以包含 provider、modelId 和 modelRef。請將其視為 資訊性的 runtime 中繼資料，而不是用來防範本機 操作者、已安裝外掛程式碼或經修改 OpenClaw runtime 的安全邊界。 敏感的本機工具仍應要求明確的外掛或操作者選擇加入，並在 作用中模型中繼資料缺失或不適合時封閉失敗。 Manifest 宣告擁有權與探索；執行仍會呼叫即時註冊的工具實作。 請讓 toolMetadata.<tool>.optional: true 與 api.registerTool(..., { optional: true }) 保持一致，讓 OpenClaw 可以避免 在工具被明確 allowlist 前載入該外掛 runtime。

​
匯入慣例

從聚焦的 SDK 子路徑匯入： 
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
不要從已棄用的根 barrel 匯入： 
import { definePluginEntry } from "openclaw/plugin-sdk";
在你的外掛套件內，請使用 api.ts 和 runtime-api.ts 等本機 barrel 檔案進行內部匯入。不要透過 SDK 路徑匯入你自己的外掛。供應商專用 helper 應留在供應商套件中， 除非該接縫確實是通用的。 自訂閘道 RPC 方法是進階進入點。請將它們保留在 外掛專用前綴上；核心管理命名空間，例如 config.*、 exec.approvals.*、operator.admin.*、wizard.* 和 update.* 仍為保留， 並解析為 operator.admin。 openclaw/plugin-sdk/gateway-method-runtime bridge 保留給宣告 contracts.gatewayMethodDispatch: ["authenticated-request"] 的外掛 HTTP 路由使用。 完整匯入對照請參閱 外掛 SDK 總覽。

​
提交前檢查清單

package.json 具有正確的 openclaw 中繼資料
openclaw.plugin.json manifest 存在且有效
進入點使用 defineChannelPluginEntry 或 definePluginEntry
所有匯入都使用聚焦的 plugin-sdk/<subpath> 路徑
內部匯入使用本機模組，而不是 SDK 自我匯入
測試通過（pnpm test <bundled-plugin-root>/my-plugin/）
pnpm check 通過（儲存庫內外掛）

​
針對 beta 發行版本測試

  1. 觀看 openclaw/openclaw 發行版（Watch > Releases）。Beta 標籤看起來像 v2026.3.N-beta.1。你也可以在 X 上追蹤 @openclaw 以取得發行公告。
  2. Beta 標籤一出現，就立即用它測試你的外掛。穩定版發布前的時間通常只有幾個小時。
  3. 測試後，在 plugin-forum Discord 頻道（discord.gg/clawd）中你的外掛討論串發文，內容可以是 all good 或說明哪裡壞了。如果你還沒有討論串，請建立一個。
  4. 如果有東西壞了，請開啟或更新標題為 Beta blocker: <plugin-name> - <summary> 的議題，並套用 beta-blocker 標籤。在你的討論串中連結該議題。
  5. 開啟一個到 main 的 PR，標題為 fix(<plugin-id>): beta blocker - <summary>，並在 PR 和你的 Discord 討論串中連結該議題。貢獻者無法為 PR 加上標籤，因此標題是給維護者和自動化系統的 PR 端訊號。有 PR 的阻擋問題會被合併；沒有 PR 的阻擋問題仍可能照常發布。
  6. 沉默表示綠燈。錯過這個時段通常表示你的修正會進入下一個週期。

​
下一步

Channel Plugins

建立訊息通道外掛

Provider Plugins

建立模型提供者外掛

CLI Backend Plugins

註冊本機 AI 命令列介面後端

SDK Overview

匯入對應與註冊 API 參考

Runtime Helpers

透過 api.runtime 使用 TTS、搜尋、子代理

Testing

測試工具與模式

Plugin Manifest

完整 manifest 結構描述參考

​
相關