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() }),      outputSchema: Type.Object(        { input: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        const details = { input: params.input };        return {          content: [{ type: "text", text: `Got: ${params.input}` }],          details,        };      },    });  },});

    非頻道外掛請使用 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() }),      outputSchema: Type.Object(        { pipeline: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        return {          content: [{ type: "text", text: params.pipeline }],          details: { pipeline: params.pipeline },        };      },    },    { optional: true },  );}

    outputSchema 為選用。它描述 Code Mode 與 工具搜尋所使用的結構化 details 值。目錄 呼叫會在執行前拒絕無效的結構描述，並在工具掛鉤後驗證最終值。 對於沒有穩定 JSON 結果的工具，請省略此項。完整合約請參閱 工具外掛。

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

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

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

    json5
    {  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool from one plugin}

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

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

    工具工廠會收到執行階段提供的內容物件。當工具需要記錄、顯示目前 回合的作用中模型，或根據該模型調整行為時，請使用 ctx.activeModel； 其中可能包含 provider、modelId 和 modelRef。請將其視為 資訊性執行階段中繼資料，而不是防範本機操作者、已安裝外掛程式碼或 修改版 OpenClaw 執行階段的安全邊界。敏感的本機工具仍應要求明確的 外掛或操作者選擇加入，且在作用中模型中繼資料缺失或不適用時， 應採取拒絕執行的安全預設。

    資訊清單負責宣告擁有權與探索；執行時仍會呼叫即時註冊的工具實作。 請讓 toolMetadata.<tool>.optional: true 與 api.registerTool(..., { optional: true }) 保持一致， 讓 OpenClaw 在該工具明確列入允許清單前，無須載入 該外掛執行階段。

    匯入慣例

    從聚焦的 SDK 子路徑匯入：

    typescript

    在你的外掛套件中，內部匯入請使用 api.ts 和 runtime-api.ts 等本機彙整檔。請勿透過 SDK 路徑匯入自己的外掛。 除非介面確實通用，否則供應商特定的輔助函式應留在供應商套件中。

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

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

    OpenClaw SDK 相容性欄位帶有 TypeScript @deprecated 註解， 編輯器會將其顯示為遷移警告。若要在建置時強制執行，請啟用具備型別感知能力的規則，例如 @typescript-eslint/no-deprecated。 Oxlint 不具備型別感知能力，因此無法強制執行這些註解。

    提交前檢查清單

    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