---
read_when:
    - 您想建立新的 OpenClaw Plugin
    - 您需要一份 Plugin 開發快速入門指南
    - 你正在為 OpenClaw 新增通道、提供者、工具或其他功能
sidebarTitle: Getting Started
summary: 在幾分鐘內建立你的第一個 OpenClaw Plugin
title: 建構 Plugin
x-i18n:
    generated_at: "2026-05-02T20:51:43Z"
    model: gpt-5.5
    provider: openai
    source_hash: b42170b40094f89a63b1497c08ec31e397931dd536bd6faeeb8bc3c123ae45d1
    source_path: plugins/building-plugins.md
    workflow: 16
---

Plugin 以新功能擴充 OpenClaw：頻道、模型提供者、語音、即時轉錄、即時語音、媒體理解、圖像生成、影片生成、網頁擷取、網頁搜尋、代理工具，或任意組合。

你不需要將你的 Plugin 加入 OpenClaw 儲存庫。發布到
[ClawHub](/zh-TW/tools/clawhub)，使用者即可透過
`openclaw plugins install clawhub:<package-name>` 安裝。裸套件規格在啟動切換期間仍會從 npm 安裝。

## 先決條件

- Node >= 22 和套件管理器（npm 或 pnpm）
- 熟悉 TypeScript（ESM）
- 對於儲存庫內 Plugin：已複製儲存庫並完成 `pnpm install`。原始碼
  checkout 的 Plugin 開發僅支援 pnpm，因為 OpenClaw 會從 `extensions/*` 工作區套件載入內建
  Plugin。

## 哪一種 Plugin？

<CardGroup cols={3}>
  <Card title="Channel plugin" icon="messages-square" href="/zh-TW/plugins/sdk-channel-plugins">
    將 OpenClaw 連接到訊息平台（Discord、IRC 等）
  </Card>
  <Card title="Provider plugin" icon="cpu" href="/zh-TW/plugins/sdk-provider-plugins">
    新增模型提供者（LLM、代理或自訂端點）
  </Card>
  <Card title="Tool / hook plugin" icon="wrench" href="/zh-TW/plugins/hooks">
    註冊代理工具、事件 hook 或服務 — 請繼續閱讀下方內容
  </Card>
</CardGroup>

對於無法保證在 onboarding/setup 執行時已安裝的頻道 Plugin，請使用
`openclaw/plugin-sdk/channel-setup` 中的 `createOptionalChannelSetupSurface(...)`。
它會產生一組設定配接器與精靈，宣告安裝需求，並在 Plugin 尚未安裝前，對實際設定寫入採取失敗關閉策略。

## 快速開始：工具 Plugin

本逐步說明會建立一個最小 Plugin，用來註冊代理工具。頻道與提供者
Plugin 有上方連結的專屬指南。

<Steps>
  <Step title="Create the package and manifest">
    <CodeGroup>
    ```json package.json
    {
      "name": "@myorg/openclaw-my-plugin",
      "version": "1.0.0",
      "type": "module",
      "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"
        }
      }
    }
    ```

    ```json 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
      }
    }
    ```
    </CodeGroup>

    每個 Plugin 都需要 manifest，即使沒有設定也一樣。執行階段註冊的工具
    必須列在 `contracts.tools` 中，讓 OpenClaw 不必載入每個 Plugin 執行階段也能發現擁有它的
    Plugin。Plugin 也應有意識地宣告
    `activation.onStartup`。這個範例將它設為 `true`。完整 schema 請參閱
    [Manifest](/zh-TW/plugins/manifest)。標準 ClawHub
    發布片段位於 `docs/snippets/plugin-publish/`。

  </Step>

  <Step title="Write the entry point">

    ```typescript
    // index.ts
    import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
    import { Type } from "@sinclair/typebox";

    export default definePluginEntry({
      id: "my-plugin",
      name: "My Plugin",
      description: "Adds a custom tool to OpenClaw",
      register(api) {
        api.registerTool({
          name: "my_tool",
          description: "Do a thing",
          parameters: Type.Object({ input: Type.String() }),
          async execute(_id, params) {
            return { content: [{ type: "text", text: `Got: ${params.input}` }] };
          },
        });
      },
    });
    ```

    `definePluginEntry` 適用於非頻道 Plugin。對於頻道，請使用
    `defineChannelPluginEntry` — 請參閱 [Channel Plugins](/zh-TW/plugins/sdk-channel-plugins)。
    完整進入點選項請參閱 [Entry Points](/zh-TW/plugins/sdk-entrypoints)。

  </Step>

  <Step title="Test and publish">

    **外部 Plugin：** 使用 ClawHub 驗證並發布，然後安裝：

    ```bash
    clawhub package publish your-org/your-plugin --dry-run
    clawhub package publish your-org/your-plugin
    openclaw plugins install clawhub:@myorg/openclaw-my-plugin
    ```

    像 `@myorg/openclaw-my-plugin` 這樣的裸套件規格會在啟動切換期間從 npm 安裝。
    想使用 ClawHub 解析時，請使用 `clawhub:`。

    **儲存庫內 Plugin：** 放在內建 Plugin 工作區樹狀結構下 — 會自動被發現。

    ```bash
    pnpm test -- <bundled-plugin-root>/my-plugin/
    ```

  </Step>
</Steps>

## Plugin 功能

單一 Plugin 可以透過 `api` 物件註冊任意數量的功能：

| 功能                   | 註冊方法                                         | 詳細指南                                                                        |
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |
| 文字推論（LLM）        | `api.registerProvider(...)`                      | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins)                               |
| CLI 推論後端           | `api.registerCliBackend(...)`                    | [CLI Backends](/zh-TW/gateway/cli-backends)                                           |
| 頻道 / 訊息            | `api.registerChannel(...)`                       | [Channel Plugins](/zh-TW/plugins/sdk-channel-plugins)                                 |
| 語音（TTS/STT）        | `api.registerSpeechProvider(...)`                | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 即時轉錄               | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 即時語音               | `api.registerRealtimeVoiceProvider(...)`         | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 媒體理解               | `api.registerMediaUnderstandingProvider(...)`    | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 圖像生成               | `api.registerImageGenerationProvider(...)`       | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 音樂生成               | `api.registerMusicGenerationProvider(...)`       | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 影片生成               | `api.registerVideoGenerationProvider(...)`       | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 網頁擷取               | `api.registerWebFetchProvider(...)`              | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 網頁搜尋               | `api.registerWebSearchProvider(...)`             | [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| 工具結果 middleware    | `api.registerAgentToolResultMiddleware(...)`     | [SDK Overview](/zh-TW/plugins/sdk-overview#registration-api)                          |
| 代理工具               | `api.registerTool(...)`                          | 下方                                                                            |
| 自訂命令               | `api.registerCommand(...)`                       | [Entry Points](/zh-TW/plugins/sdk-entrypoints)                                        |
| Plugin hook            | `api.on(...)`                                    | [Plugin hooks](/zh-TW/plugins/hooks)                                                  |
| 內部事件 hook          | `api.registerHook(...)`                          | [Entry Points](/zh-TW/plugins/sdk-entrypoints)                                        |
| HTTP 路由              | `api.registerHttpRoute(...)`                     | [Internals](/zh-TW/plugins/architecture-internals#gateway-http-routes)                |
| CLI 子命令             | `api.registerCli(...)`                           | [Entry Points](/zh-TW/plugins/sdk-entrypoints)                                        |

完整註冊 API 請參閱 [SDK Overview](/zh-TW/plugins/sdk-overview#registration-api)。

內建 Plugin 在需要於模型看到輸出前進行非同步工具結果重寫時，可以使用 `api.registerAgentToolResultMiddleware(...)`。
請在 `contracts.agentToolResultMiddleware` 中宣告目標執行階段，例如
`["pi", "codex"]`。這是受信任的內建 Plugin seam；外部
Plugin 應優先使用一般 OpenClaw Plugin hook，除非 OpenClaw 為此功能增加明確的信任政策。

如果你的 Plugin 註冊自訂 Gateway RPC 方法，請將它們保留在
Plugin 專屬前綴下。核心管理命名空間（`config.*`、
`exec.approvals.*`、`wizard.*`、`update.*`）會保持保留，且一律解析為
`operator.admin`，即使 Plugin 要求較窄的 scope 也是如此。

需要記住的 hook guard 語意：

- `before_tool_call`：`{ block: true }` 是終止性決策，並會停止較低優先級的處理常式。
- `before_tool_call`：`{ block: false }` 會被視為沒有決策。
- `before_tool_call`：`{ requireApproval: true }` 會暫停代理執行，並透過 exec 核准覆蓋層、Telegram 按鈕、Discord 互動，或任何頻道上的 `/approve` 命令提示使用者核准。
- `before_install`：`{ block: true }` 是終止性決策，並會停止較低優先級的處理常式。
- `before_install`：`{ block: false }` 會被視為沒有決策。
- `message_sending`：`{ cancel: true }` 是終止性決策，並會停止較低優先級的處理常式。
- `message_sending`：`{ cancel: false }` 會被視為沒有決策。
- `message_received`：需要傳入 thread/topic 路由時，請優先使用型別化的 `threadId` 欄位。將 `metadata` 保留給頻道專屬的額外資訊。
- `message_sending`：請優先使用型別化的 `replyToId` / `threadId` 路由欄位，而不是頻道專屬的 metadata key。

`/approve` 命令會以有界 fallback 處理 exec 與 Plugin 核准：找不到 exec 核准 id 時，OpenClaw 會以相同 id 重試 Plugin 核准。Plugin 核准轉送可透過設定中的 `approvals.plugin` 獨立設定。

如果自訂核准接線需要偵測相同的有界 fallback 情況，
請優先使用 `openclaw/plugin-sdk/error-runtime` 中的 `isApprovalNotFoundError`，
而不是手動比對核准到期字串。

範例與 hook 參考請參閱 [Plugin hooks](/zh-TW/plugins/hooks)。

## 註冊代理工具

工具是 LLM 可以呼叫的型別化函式。它們可以是必要的（永遠
可用）或選用的（使用者選擇加入）：

```typescript
register(api) {
  // Required tool — always available
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({ input: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

  // Optional tool — user must add to allowlist
  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(...)` 註冊的工具，也必須在
Plugin manifest 中宣告：

```json
{
  "contracts": {
    "tools": ["my_tool", "workflow_tool"]
  }
}
```

OpenClaw 會擷取並快取已註冊工具的已驗證描述子，
因此 Plugin 不需要在 manifest 中重複 `description` 或 schema 資料。
manifest contract 只宣告擁有權與發現；執行仍會呼叫
即時註冊的工具實作。

使用者可在設定中啟用選用工具：

```json5
{
  tools: { allow: ["workflow_tool"] },
}
```

- 工具名稱不得與核心工具衝突（衝突項目會被略過）
- 註冊物件格式錯誤的工具（包括缺少 `parameters`）會被略過，並改在 Plugin 診斷中回報，而不是中斷代理程式執行
- 對於具有副作用或需要額外二進位檔的工具，請使用 `optional: true`
- 使用者可以將 Plugin ID 加到 `tools.allow`，以啟用某個 Plugin 的所有工具

## 註冊 CLI 指令

Plugin 可以透過 `api.registerCli` 新增根層級 `openclaw` 指令群組。請為每個頂層指令根提供 `descriptors`，讓 OpenClaw 不必急切載入每個 Plugin 執行階段，就能顯示並路由該指令。

```typescript
register(api) {
  api.registerCli(
    ({ program }) => {
      const demo = program
        .command("demo-plugin")
        .description("Run demo plugin commands");

      demo
        .command("ping")
        .description("Check that the plugin CLI is executable")
        .action(() => {
          console.log("demo-plugin:pong");
        });
    },
    {
      descriptors: [
        {
          name: "demo-plugin",
          description: "Run demo plugin commands",
          hasSubcommands: true,
        },
      ],
    },
  );
}
```

安裝後，驗證執行階段註冊並執行指令：

```bash
openclaw plugins inspect demo-plugin --runtime --json
openclaw demo-plugin ping
```

## 匯入慣例

一律從聚焦的 `openclaw/plugin-sdk/<subpath>` 路徑匯入：

```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

// Wrong: monolithic root (deprecated, will be removed)
import { ... } from "openclaw/plugin-sdk";
```

完整子路徑參考請見 [SDK 概覽](/zh-TW/plugins/sdk-overview)。

在你的 Plugin 內，請使用本機 barrel 檔案（`api.ts`、`runtime-api.ts`）進行內部匯入，絕對不要透過其 SDK 路徑匯入自己的 Plugin。

對於提供者 Plugin，請將提供者特定的輔助工具保留在那些套件根層級 barrel 中，除非該接縫確實是通用的。目前的內建範例：

- Anthropic：Claude 串流包裝器與 `service_tier` / beta 輔助工具
- OpenAI：提供者建構器、預設模型輔助工具、即時提供者
- OpenRouter：提供者建構器加上 onboarding/設定輔助工具

如果某個輔助工具只在單一內建提供者套件內有用，請將它保留在該套件根層級接縫上，而不是提升到 `openclaw/plugin-sdk/*`。

部分產生的 `openclaw/plugin-sdk/<bundled-id>` 輔助接縫仍存在，用於有追蹤擁有者使用情況的內建 Plugin 維護。請將這些視為保留介面，而不是新第三方 Plugin 的預設模式。

## 提交前檢查清單

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

## Beta 發布測試

1. 留意 [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) 上的 GitHub 發布標籤，並透過 `Watch` > `Releases` 訂閱。Beta 標籤看起來像 `v2026.3.N-beta.1`。你也可以開啟官方 OpenClaw X 帳號 [@openclaw](https://x.com/openclaw) 的通知，以接收發布公告。
2. Beta 標籤一出現，就立即針對它測試你的 Plugin。穩定版發布前的時間窗口通常只有幾個小時。
3. 測試後，請在 `plugin-forum` Discord 頻道中你的 Plugin 討論串張貼 `all good` 或說明壞掉的內容。如果你還沒有討論串，請建立一個。
4. 如果有東西壞掉，請開啟或更新標題為 `Beta blocker: <plugin-name> - <summary>` 的 issue，並套用 `beta-blocker` 標籤。將 issue 連結放到你的討論串中。
5. 開啟一個指向 `main`、標題為 `fix(<plugin-id>): beta blocker - <summary>` 的 PR，並在 PR 和你的 Discord 討論串中連結該 issue。貢獻者無法替 PR 加標籤，因此標題是給維護者與自動化使用的 PR 端訊號。有 PR 的阻擋問題會被合併；沒有 PR 的阻擋問題仍可能照常發布。維護者會在 beta 測試期間關注這些討論串。
6. 沉默代表綠燈。如果你錯過時間窗口，你的修正很可能會在下一個週期落地。

## 下一步

<CardGroup cols={2}>
  <Card title="Channel Plugins" icon="messages-square" href="/zh-TW/plugins/sdk-channel-plugins">
    建置訊息通道 Plugin
  </Card>
  <Card title="Provider Plugins" icon="cpu" href="/zh-TW/plugins/sdk-provider-plugins">
    建置模型提供者 Plugin
  </Card>
  <Card title="SDK 概覽" icon="book-open" href="/zh-TW/plugins/sdk-overview">
    匯入對應與註冊 API 參考
  </Card>
  <Card title="執行階段輔助工具" icon="settings" href="/zh-TW/plugins/sdk-runtime">
    TTS、搜尋、透過 api.runtime 使用 subagent
  </Card>
  <Card title="測試" icon="test-tubes" href="/zh-TW/plugins/sdk-testing">
    測試工具與模式
  </Card>
  <Card title="Plugin Manifest" icon="file-json" href="/zh-TW/plugins/manifest">
    完整 manifest schema 參考
  </Card>
</CardGroup>

## 相關

- [Plugin 架構](/zh-TW/plugins/architecture) — 內部架構深入解析
- [SDK 概覽](/zh-TW/plugins/sdk-overview) — Plugin SDK 參考
- [Manifest](/zh-TW/plugins/manifest) — Plugin manifest 格式
- [Channel Plugins](/zh-TW/plugins/sdk-channel-plugins) — 建置通道 Plugin
- [Provider Plugins](/zh-TW/plugins/sdk-provider-plugins) — 建置提供者 Plugin
