擴充 OpenClaw 功能：Plugin 入門指南

有時候你會發現，手邊的工具雖然好用，但就差那麼一點特定的功能，比如某個冷門的通訊平台支援，或是特殊的自動化邏輯。如果把所有功能都塞進核心程式碼，整個專案會變得臃腫且難以維護，這對開發者來說通常是場災難。

這種時候，Plugin 系統就是最好的解法。它讓你可以根據需求彈性擴充功能，保持環境乾淨，同時又能快速導入社群或官方開發的新工具。

需要準備的東西

已安裝並能執行的 OpenClaw 環境
終端機 (CLI) 操作權限

快速開始

Plugin 是擴充 OpenClaw 功能（指令、工具與 Gateway RPC）的小型程式碼模組。如果你需要核心功能以外的特色，請參考以下快速路徑：

查看已載入的 Plugin：
Terminal window
```
openclaw plugins list
```
安裝官方 Plugin（以 Voice Call 為例）：
Terminal window
```
openclaw plugins install @openclaw/voice-call
```
重啟 Gateway：安裝完成後，請重新啟動 Gateway 服務。
進行設定：在設定檔中的 plugins.entries.<id>.config 區塊進行配置。

官方可用 Plugin

OpenClaw 提供多種官方維護的 Plugin，部分功能已從核心移出：

Microsoft Teams：自 2026.1.15 版本起改為純 Plugin 形式，若有需求請安裝 @openclaw/msteams。
Memory (LanceDB)：內建的長期記憶 Plugin，支援自動召回與擷取。
通訊管道：包含 Voice Call, Zalo Personal, Matrix, Nostr 等。
身份驗證 (OAuth)：包含 Google Antigravity, Gemini CLI, Qwen 等 Provider 驗證工具。
Copilot Proxy：本地 VS Code Copilot Proxy 橋接器，與內建的 github-copilot 裝置登入不同。

技術細節

OpenClaw Plugin 是透過 jiti 在執行時載入的 TypeScript 模組。Plugin 運行時會與 Gateway 處於同一個 Process，因此請確保你信任這些程式碼。

你可以透過 Plugin 註冊以下內容：

Gateway RPC 方法與 HTTP handlers
Agent 工具與 CLI 指令
背景服務與設定驗證
Skills（透過 manifest 中的 skills 目錄）
自動回覆指令（不需啟動 AI Agent 即可執行）

Runtime Helpers

Plugin 可以透過 api.runtime 使用核心輔助工具。例如在處理電話語音 (Telephony TTS) 時：

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

這會回傳 PCM 音訊 Buffer 與採樣率。注意 Plugin 必須自行處理對應 Provider 的重新採樣或編碼。

疑難排解

設定驗證失敗：Config 驗證過程並不會執行 Plugin 程式碼，而是使用 Plugin manifest 與 JSON Schema 進行檢查。請確認你的 Plugin manifest 設定正確。
Telephony 語音不工作：請檢查 messages.tts 設定。目前電話語音功能僅支援 OpenAI 或 ElevenLabs，不支援 Edge TTS。

有安裝或設定上的疑問嗎？直接問問 AI Setup Assistant。

下一步

你在開發插件時，有沒有遇過明明寫好了代碼，系統卻沒反應，或是載入到舊版本的狀況？這種「到底讀到哪一個檔案」的猜謎遊戲，往往是開發中最浪費時間的部分。

OpenClaw 有一套清晰的掃描邏輯，搞懂這些載入順序（Precedence），你就能精準控制插件的行為，不再被路徑問題困擾。

需要準備的東西

OpenClaw 環境
插件目錄中必須包含 openclaw.plugin.json 檔案
如果插件有 npm 依賴，需在該目錄執行 npm install 或 pnpm install

快速開始

OpenClaw 會按照以下順序掃描插件，一旦發現相同的 Plugin ID，排在前面的會直接勝出，後面的則會被忽略：

Config paths: 檢查 plugins.load.paths 指定的檔案或目錄。
Workspace extensions: 掃描 <workspace>/.openclaw/extensions/*.ts 或 <workspace>/.openclaw/extensions/*/index.ts。
Global extensions: 掃描 ~/.openclaw/extensions/*.ts 或 ~/.openclaw/extensions/*/index.ts。
Bundled extensions: OpenClaw 內建的擴充功能，路徑在 <openclaw>/extensions/*。注意：這部分預設是禁用的。

如果你想啟用內建插件，可以透過配置文件設定 plugins.entries.<id>.enabled，或是直接跑 CLI 指令： openclaw plugins enable <id>。

深入 Package packs 配置

如果你的插件目錄包含 package.json，你可以利用 openclaw.extensions 欄位來定義多個擴充點：

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"]
  }
}

在這種情況下，每個 entry 都會變成一個獨立插件。如果一個 Pack 裡面列出多個 extensions，Plugin ID 會自動命名為 name/fileBase（例如 my-pack/safety）。

Channel catalog 與元數據

如果你開發的是 Channel 插件，可以透過 openclaw.channel 提供註冊資訊，並透過 openclaw.install 提供安裝提示，這樣可以讓核心 Catalog 保持乾淨。

這是一個完整的範例：

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "extensions/nextcloud-talk",
      "defaultChoice": "npm"
    }
  }
}

合併外部 Catalog

OpenClaw 也支援合併外部的 Channel Catalog（例如從 MPM Registry 匯出的資料）。你只需要將 JSON 檔案丟到以下路徑之一：

~/.openclaw/mpm/plugins.json
~/.openclaw/mpm/catalog.json
~/.openclaw/plugins/catalog.json

或者，你也可以設定環境變數 OPENCLAW_PLUGIN_CATALOG_PATHS 或 OPENCLAW_MPM_CATALOG_PATHS 指向一個或多個 JSON 檔案（使用逗號、分號或系統路徑分隔符）。

每個 JSON 檔案的結構應該長這樣： { "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }

疑難排解

插件沒被載入？ 請檢查插件根目錄是否確實包含 openclaw.plugin.json。如果路徑指向一個檔案，該檔案所在的目錄必須有 manifest。
修改了代碼但沒生效？ 檢查是否有同名的插件存在於優先級更高的路徑中（例如 Workspace 路徑會蓋過 Global 路徑）。

如果你在設定過程中遇到任何問題，可以直接詢問 AI Setup Assistant。

下一步

---
title: 掌握 OpenClaw 插件系統：從 ID 識別到 Hook 自動化
description: 了解如何有效管理 OpenClaw 插件，包含 ID 規則、設定檔檢查、獨佔插槽以及透過 CLI 快速安裝。
---

你是否曾經在擴充專案功能時，被一堆混亂的套件依賴搞到頭大？或是改了設定卻不知道為什麼沒生效，最後只能對著螢幕發呆。管理插件不應該這麼痛苦，我們都希望擴充功能可以像拼積木一樣簡單直接。

這篇文章會帶你掌握 OpenClaw 插件的核心邏輯，讓你從 ID 命名規則到自動化 Hook 都能上手。

## 需要準備的東西

在開始之前，請確保你已經準備好以下內容：
- 已安裝 OpenClaw
- 準備好的插件檔案（`.ts`、`.zip`、`.tgz`）或 npm 套件
- 基礎的 JSON5 編輯能力

## 快速開始

要在 5 分鐘內跑通插件流程，請參考以下步驟：

1. **確認 ID**：如果是資料夾，看 `package.json` 的 `name`；如果是獨立檔案（如 `voice-call.ts`），ID 就是 `voice-call`。
2. **修改設定**：在 `plugins.entries` 加入你的插件 ID 並將 `enabled` 設為 `true`。
3. **安裝插件**：執行 `openclaw plugins install <path>` 將插件放入系統目錄。
4. **重啟生效**：任何設定更動後，請務必重啟 Gateway。

## 深入了解插件 ID

OpenClaw 識別插件的方式非常直覺：
- **套件包**：直接取用 `package.json` 裡的 `name` 欄位。
- **獨立檔案**：取用檔案的主檔名（例如 `~/.../voice-call.ts` 的 ID 就是 `voice-call`）。

如果插件程式碼裡有導出（export）特定的 `id`，OpenClaw 會優先使用它。但要注意，如果這個導出的 ID 跟你在設定檔裡寫的不一樣，系統會跳出警告。

## 設定檔詳解

所有的插件行為都在設定檔中定義。這是一個標準的 `json5` 範例：

```json
{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-extension"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}

欄位說明

enabled: 全域開關（預設為 true）。
allow: 白名單，只允許清單內的插件。
deny: 黑名單，若與白名單衝突，以黑名單為準。
load.paths: 額外載入插件的檔案路徑或目錄。
entries.<id>: 針對個別插件的開關與具體設定。

注意：修改設定後，你必須重啟 Gateway 才會生效。

嚴格驗證規則

OpenClaw 擁有一套嚴格的檢查機制：

在 entries、allow、deny 或 slots 中出現未知的插件 ID 會直接報錯（Error）。
channels.<id> 的 key 必須在插件 manifest 中有宣告，否則視為報錯。
插件設定會比對 openclaw.plugin.json 中的 configSchema。
如果插件被停用，它的設定會被保留，但系統會發出警告（Warning）。

插件插槽 (Plugin Slots)

有些插件分類是具有排他性的，也就是同一時間只能有一個插件在運作。你可以透過 plugins.slots 來指定誰來接管該插槽：

{
  plugins: {
    slots: {
      memory: "memory-core", // 或設定為 "none" 來停用 memory 插件
    },
  },
}

如果有多個插件都宣告自己屬於 kind: "memory"，只有你在 slots 裡挑選的那一個會被載入，其他的會被停用並記錄在診斷資訊中。

控制介面 (Control UI)

Control UI 會根據 config.schema 自動產生表單。OpenClaw 會在執行時幫你補強這些資訊：

為 plugins.entries.<id> 自動加上標籤（Label）。
將插件提供的欄位提示合併到 plugins.entries.<id>.config.<field> 下。

如果你希望你的插件設定欄位看起來更專業（例如隱藏敏感資訊），可以在插件 manifest 中提供 uiHints：

{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": { "type": "string" },
      "region": { "type": "string" }
    }
  },
  "uiHints": {
    "apiKey": { "label": "API Key", "sensitive": true },
    "region": { "label": "Region", "placeholder": "us-east-1" }
  }
}

CLI 指令大全

你可以透過 CLI 完整控管插件生命週期：

openclaw plugins list
openclaw plugins info \<id\>
openclaw plugins install \<path\>                 # 複製本地檔案/目錄到 ~/.openclaw/extensions/\<id\>
openclaw plugins install ./extensions/voice-call # 支援相對路徑
openclaw plugins install ./plugin.tgz           # 從 tarball 安裝
openclaw plugins install ./plugin.zip           # 從 zip 安裝
openclaw plugins install -l ./extensions/voice-call # 開發模式：建立連結而不複製檔案
openclaw plugins install @openclaw/voice-call # 從 npm 安裝
openclaw plugins update \<id\>
openclaw plugins update --all
openclaw plugins enable \<id\>
openclaw plugins disable \<id\>
openclaw plugins doctor

plugins update 僅適用於紀錄在 plugins.installs 下的 npm 套件。另外，有些插件會註冊自己的頂層指令（例如 openclaw voicecall）。

插件 API 與 Hook

插件可以導出一個函數或一個物件：

函數：(api) => { ... }
物件：{ id, name, configSchema, register(api) { ... } }

插件 Hook 範例

插件可以內建 Hook，讓你不需要額外安裝 Hook Pack 就能實現事件驅動的自動化。

import { registerPluginHooksFromDir } from "openclaw/plugin-sdk";

export default function register(api) {
  registerPluginHooksFromDir(api, "./hooks");
}

Hook 目錄結構需符合規範（HOOK.md + handler.ts）。
插件管理的 Hook 在執行 openclaw hooks list 時會顯示 plugin:<id> 標籤。
你不能單獨透過 openclaw hooks 指令來開關這些 Hook，必須直接啟用或停用該插件。

疑難排解

錯誤：Unknown plugin id：檢查你的 entries 或 allow 清單，確保 ID 與插件實際的 name 一致。
設定未生效：請確認你已經重啟了 Gateway。
Hook 沒出現：檢查該 Hook 是否符合目前的 OS、環境變數或相依二進位檔（bins）的要求。
Slot 衝突：若多個插件爭奪同一個插槽，請在 plugins.slots 中明確指定一個 ID。

如果你遇到更複雜的配置問題，可以試試 AI Setup Assistant。

下一步

開發者最煩的事情之一，就是每次換一個模型 Provider 或通訊平台，就要手動處理一堆認證流程或寫外掛腳本來對接。如果你想讓這些流程直接整合進 OpenClaw，而不是每次都在那邊複製貼上 API key，開發插件就是你的最佳選擇。

這篇文章會教你如何透過 Plugin 系統，把自定義的 Provider 認證、訊息頻道（如 WhatsApp 或 Telegram 的替代方案）以及自動回覆指令通通裝進 OpenClaw 裡面。

## 需要準備的東西

- OpenClaw 運行環境與 Node.js 基礎
- 你的 Provider API key 或 OAuth 憑證
- 準備好要對接的通訊平台（如 AcmeChat）

## 快速開始

要在 5 分鐘內讓你的插件跑起來，你可以先從註冊一個簡單的 Provider 開始。

### 1. 註冊模型 Provider 認證

透過 `api.registerProvider(...)`，你可以讓使用者直接在 OpenClaw 內部完成 OAuth 或 API key 的設定，不需要跑外部腳本。

```ts
api.registerProvider({
  id: "acme",
  label: "AcmeAI",
  auth: [
    {
      id: "oauth",
      label: "OAuth",
      kind: "oauth",
      run: async (ctx) => {
        // 執行 OAuth 流程並回傳 auth profiles
        return {
          profiles: [
            {
              profileId: "acme:default",
              credential: {
                type: "oauth",
                provider: "acme",
                access: "...",
                refresh: "...",
                expires: Date.now() + 3600 * 1000,
              },
            },
          ],
          defaultModel: "acme/opus-1",
        };
      },
    },
  ],
});

註冊後，你就能直接跑這行指令來登入： openclaw models auth login --provider acme

開發小撇步：

run 函式會拿到 ProviderAuthContext，裡面有 prompter、runtime、openUrl 和 oauth.createVpsAwareHandlers 這些好用的工具。
如果你需要新增預設模型或 Provider 配置，記得回傳 configPatch。
回傳 defaultModel 可以讓 --set-default 自動更新 Agent 的預設值。

2. 註冊訊息頻道 (Messaging Channel)

如果你想對接 WhatsApp 或 Telegram 以外的新平台，你可以註冊一個 Channel 插件。

const myChannel = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "demo channel plugin.",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async () => ({ ok: true }),
  },
};

export default function (api) {
  api.registerChannel({ plugin: myChannel });
}

設定重點：

設定檔要放在 channels.<id> 下面。
meta.aliases 可以讓你用簡稱來執行 CLI 指令。
meta.preferOver 可以指定當多個頻道同時存在時，優先自動啟用哪一個。

3. 加入自動回覆指令 (Slash Commands)

有時候你不需要 AI 介入，只需要簡單的指令（例如檢查狀態或切換模式），這時候可以用 api.registerCommand。

export default function (api) {
  api.registerCommand({
    name: "mystatus",
    description: "顯示插件狀態",
    handler: (ctx) => ({
      text: `插件正在運行！頻道：${ctx.channel}`,
    }),
  });
}

這些指令會在 AI Agent 處理之前被優先攔截，節省 LLM 的運算資源。

4. 註冊 CLI 與背景服務

如果你需要擴充 OpenClaw 的 CLI 工具或是跑一些背景工作：

export default function (api) {
  // 註冊 CLI 指令
  api.registerCli(
    ({ program }) => {
      program.command("mycmd").action(() => {
        console.log("Hello");
      });
    },
    { commands: ["mycmd"] },
  );

  // 註冊背景服務
  api.registerService({
    id: "my-service",
    start: () => api.logger.info("ready"),
    stop: () => api.logger.info("bye"),
  });
}

疑難排解

在開發過程中，你可能會遇到這些常見問題：

指令衝突：如果你註冊的指令名稱跟內建指令（如 help, status, reset）重複，插件會註冊失敗並拋出錯誤。
參數不匹配：如果你的指令設定 acceptsArgs: false 但使用者輸入了參數，該訊息會跳過你的 handler 並交給下一個處理器（或 AI）。
重複註冊：不同插件如果註冊了同名的指令，系統會回報 diagnostic error。
認證失敗：如果 requireAuth 設為 true（預設值），只有授權使用者才能觸發指令。

如果你在設定過程中卡住了，可以隨時諮詢 AI Setup Assistant。

下一步

Plugin agent tools：學習如何讓 AI 調用你的插件工具。
/providers/*：查看更多模型 Provider 的實作細節。

開發插件時，最讓人頭痛的往往不是邏輯本身，而是那些瑣碎的命名規則。如果每個人都隨心所欲地命名 API 或 CLI 指令，最後你的 Gateway 就會變成一團混亂。我們都遇過那種要在 camelCase、snake_case 和 kebab-case 之間猜來猜去的痛苦時刻。

這份指南會告訴你 OpenClaw 的標準做法，讓你的插件從第一天起就能完美融入生態系。

需要準備的東西

OpenClaw 核心環境
Node.js 開發環境
準備發佈到 npm 的插件代碼

快速開始

想讓你的插件快速跑起來？遵循這三個核心步驟：

遵循命名規範：Gateway 方法使用 pluginId.action，Tool 使用 snake_case。
配置 package.json：確保包含 openclaw.extensions 欄位指向你的入口文件。
安裝與啟用：使用 openclaw plugins install <npm-spec> 指令，並在 plugins.entries.<id>.enabled 開啟它。

命名規範 (Naming conventions)

為了保持一致性，請嚴格遵守以下格式：

Gateway methods: 採用 pluginId.action 格式（例如：voicecall.status）。
Tools: 採用 snake_case（例如：voice_call）。
CLI commands: 可以使用 kebab-case 或 camelCase，但請務必避開與核心指令衝突。

技能 (Skills)

插件可以在倉庫中附帶 Skill 說明文件（路徑為 skills/<name>/SKILL.md）。你可以透過 plugins.entries.<id>.enabled 或其他配置開關來啟用它，並確保它存在於你的 workspace 或受管理的 Skills 路徑中。

分發與安裝 (Distribution)

我們建議的打包方式如下：

主程式套件: openclaw
插件: 使用 @openclaw/* 範圍下的獨立 npm 套件（例如：@openclaw/voice-call）。

發佈規範

插件的 package.json 必須包含 openclaw.extensions 欄位，並列出一個或多個入口文件。
入口文件可以是 .js 或 .ts（系統會透過 jiti 在運行時載入 TS）。
使用 openclaw plugins install <npm-spec> 時，系統會透過 npm pack 將插件解壓縮至 ~/.openclaw/extensions/<id>/ 並在配置中啟用。
配置鍵值穩定性：為了方便管理，Scoped packages（具名範圍套件）會被標準化為 unscoped ID，用於 plugins.entries.* 的配置。

範例插件：Voice Call

OpenClaw 內建了一個語音通話插件（支援 Twilio 或 Log 回退機制）：

原始碼: extensions/voice-call
Skill: skills/voice-call
CLI: openclaw voicecall start|status
Tool: voice_call
RPC: voicecall.start, voicecall.status

配置選項

如果你使用 Twilio 提供商：

provider: "twilio"
twilio.accountSid / authToken / from
可選參數：statusCallbackUrl, twimlUrl

開發測試時：

provider: "log"（不會觸發實際網路請求）

更多細節請參考 Voice Call 或 extensions/voice-call/README.md。

安全注意事項 (Safety notes)

插件會與 Gateway 在同一個進程（in-process）中執行，請將它們視為受信任的代碼：

只安裝你信任的插件。
建議使用 plugins.allow 白名單機制。
修改插件後，請務必重啟 Gateway。

測試插件

插件應該包含完整的測試：

內置插件：可以在 src/** 下保留 Vitest 測試（例如：src/plugins/voice-call.plugin.test.ts）。
獨立發佈的插件：應執行自己的 CI (lint/build/test)，並驗證 openclaw.extensions 正確指向構建後的入口點（如 dist/index.js）。

疑難排解

CLI 指令無效：檢查你的指令名稱是否與 OpenClaw 核心指令衝突。
Skill 未載入：確認 SKILL.md 放置在正確的路徑，且配置中的 enabled 已設為 true。
修改未生效：插件是在進程內執行的，任何代碼更動後都需要手動重啟 Gateway。

如果你在配置過程中遇到任何問題，可以直接詢問 AI Setup Assistant 獲取即時協助。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。