OpenClaw Plugins 擴充指南：輕鬆增加機器人功能

每次想幫專案加個新功能，最怕的就是要把原本跑得好好的核心代碼拆開來改。改壞了很難修，不改又沒辦法滿足需求。這種進退兩難的情況，通常就是需要 Plugin 系統的時候。

我通常會用 Plugin 來處理從語音通話到自定義 Slack 整合的所有事情。只要你掌握了這個模式，就會發現開發起來非常輕鬆。

需要準備的東西

已安裝並運行中的 OpenClaw
基本 TypeScript 知識（如果你想開發自定義 Plugin）

Quick Start (3 分鐘上手)

第一步：查看目前已載入的內容

openclaw plugins list

第二步：安裝官方 Plugin

openclaw plugins install @openclaw/voice-call

第三步：重啟與配置

重啟你的 Gateway，然後在 plugins.entries.<id>.config 下方加入設定：

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio"
        }
      }
    }
  }
}

搞定，你的新 Plugin 已經準備好了。

官方 Plugin 列表

Plugin	Package	說明
Voice Call	`@openclaw/voice-call`	撥打與接聽電話
Microsoft Teams	`@openclaw/msteams`	Teams 頻道整合
Matrix	`@openclaw/matrix`	Matrix 聊天協定
Nostr	`@openclaw/nostr`	Nostr 去中心化聊天
Zalo	`@openclaw/zalo`	越南通訊軟體

內建 Plugin（預設停用）：

Memory (Core) — 基礎記憶搜尋
Memory (LanceDB) — 具備自動回想功能的長期記憶
Google/Gemini/Qwen OAuth — 供應商身分驗證流程

你可以用這行指令啟用內建 Plugin：

openclaw plugins enable memory-lancedb

Plugin 搜尋順序

OpenClaw 會依照以下順序掃描 Plugin：

Config 路徑 — plugins.load.paths
Workspace 擴充 — .openclaw/extensions/*.ts
全域擴充 — ~/.openclaw/extensions/*.ts
內建 — OpenClaw 自帶（預設停用）

系統會採用第一個找到的 Plugin，後續的複本會被忽略。

配置說明

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],           // 允許列表 (選填)
    deny: ["untrusted-plugin"],      // 拒絕列表優先級較高
    load: {
      paths: ["~/my-plugins/custom"]
    },
    entries: {
      "voice-call": {
        enabled: true,
        config: { provider: "twilio" }
      }
    }
  }
}

請注意：修改配置後必須重啟 Gateway 才會生效。

Plugin Slots (排他性分類)

某些類別（例如記憶供應商）同時間只允許一個啟用的 Plugin：

{
  plugins: {
    slots: {
      memory: "memory-lancedb"  // 或 "memory-core" 或 "none"
    }
  }
}

CLI 指令表

openclaw plugins list                    # 查看所有 Plugin
openclaw plugins info <id>               # Plugin 詳細資訊
openclaw plugins install &lt;path|npm&gt;      # 安裝 Plugin
openclaw plugins install -l <path>       # 開發用的 Link 模式
openclaw plugins enable <id>             # 啟用 Plugin
openclaw plugins disable <id>            # 停用 Plugin
openclaw plugins update <id>             # 更新 npm Plugin
openclaw plugins update --all            # 更新所有 npm Plugin
openclaw plugins doctor                  # 診斷問題

疑難排解

如果你發現 Plugin 沒有按預期運作，請嘗試以下步驟：

診斷問題：執行 openclaw plugins doctor 來檢查潛在的錯誤或衝突。
重啟檢查：確保你在修改 entries 或 slots 配置後已經重啟 Gateway。
優先級衝突：檢查是否有同名的 Plugin 存在於多個搜尋路徑中，OpenClaw 會優先採用路徑較前的版本。

如果你在設定過程中遇到任何困難，可以詢問我們的 AI Setup Assistant。

What’s Next?

你是否遇過這種情況：想要在現有的系統裡加個小功能，卻發現要改動核心代碼太麻煩？或是想串接一個冷門的通訊軟體，但官方還沒支援？

這就是為什麼我們需要 Plugin 系統。你不需要去動 OpenClaw 的核心，只要寫幾行 TypeScript，就能把你的想法變成功能。

需要準備的東西

安裝好的 OpenClaw 環境
基本的 Node.js 與 TypeScript 知識

快速開始

只要 5 分鐘，你就能讓第一個 Plugin 跑起來。

建立目錄與進入點 ~/.openclaw/extensions/my-plugin/index.ts：

export default function(api) {
  api.registerGatewayMethod("myplugin.status", ({ respond }) => {
    respond(true, { status: "running" });
  });
}

建立設定檔 ~/.openclaw/extensions/my-plugin/openclaw.plugin.json：

{
  "id": "my-plugin",
  "name": "My Custom Plugin",
  "version": "1.0.0"
}

重啟 Gateway，你的 Plugin 就已經正式上線了。

註冊 Tool

如果你想讓 AI 能夠執行你的代碼，你可以註冊一個 Tool：

export default function(api) {
  api.registerTool({
    name: "my_tool",
    description: "Does something useful",
    parameters: {
      type: "object",
      properties: {
        input: { type: "string" }
      }
    },
    handler: async ({ input }) => {
      return { result: `Processed: ${input}` };
    }
  });
}

註冊 Slash Command

有時候你只想手動執行指令，不想觸發 AI。Slash Command 非常適合用來做狀態檢查或快速切換設定：

export default function(api) {
  api.registerCommand({
    name: "mystatus",
    description: "Show plugin status",
    handler: (ctx) => ({
      text: `Plugin running on ${ctx.channel}`
    })
  });
}

註冊 Channel

如果你想讓 OpenClaw 支援新的通訊平台（例如特定的企業內部訊息軟體），你可以註冊一個 Channel：

const plugin = {
  id: "acmechat",
  meta: {
    label: "AcmeChat",
    docsPath: "/channels/acmechat",
    blurb: "AcmeChat messaging."
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) =>
      Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, id) =>
      cfg.channels?.acmechat?.accounts?.[id ?? "default"]
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text }) => {
      // Send message
      return { ok: true };
    }
  }
};

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

Plugin Hooks

Plugin 可以自帶 Hooks 並在運行時註冊。這讓你可以把事件驅動的自動化邏輯打包在 Plugin 裡，不需要另外安裝 Hook pack。

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

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

關於 Hooks 的注意事項：

Hook 目錄必須遵循標準結構（HOOK.md + handler.ts）。
Hook 的資格檢查規則依然有效（例如 OS、二進位檔案、環境變數或 config 要求）。
透過 Plugin 管理的 Hooks 會顯示在 openclaw hooks list 中，標記為 plugin:<id>。
你可以透過啟用或停用 Plugin 來控制這些 Hooks。

Runtime Helpers

你可以透過 api.runtime 存取核心的 Helper 功能。例如，使用語音通訊的 TTS：

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

請注意：

這會使用核心的 messages.tts 設定（OpenAI 或 ElevenLabs）。
回傳的是 PCM 音訊 buffer 與取樣率。
Plugin 必須自行為其 Provider 進行重採樣或編碼。
Telephony 不支援 Edge TTS。

Provider Plugins (Model Auth)

你可以為 Plugin 註冊 model provider auth 流程，讓用戶直接在 OpenClaw 內部完成 OAuth 或 API-key 設定。

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",
        };
      },
    },
  ],
});

開發細節：

run 函式會接收 ProviderAuthContext，包含 prompter、runtime 和 openUrl 等工具。
如果需要加入預設模型，請回傳 configPatch。
回傳 defaultModel 可以讓 --set-default 指令更新 Agent 的預設值。

用戶可以使用以下 CLI 指令進行登入：

openclaw models auth login --provider acme --method oauth

疑難排解

Plugin 沒反應？ 檢查 openclaw.plugin.json 中的 id 是否與目錄名稱一致。
TTS 沒聲音？ 確保你沒有使用 Edge TTS，因為 Telephony 模式不支援它。
Hook 沒出現在清單？ 確認 handler.ts 是否在正確的子目錄中，且符合環境要求。
Auth 失敗？ 檢查 run 函式回傳的 expires 時間戳記是否為毫秒。

如果你在開發過程中遇到困難，可以詢問 AI Setup Assistant。

下一步

開發 Bot 的時候，最煩的就是明明只要一個簡單的狀態查詢或固定資訊，卻還要經過 AI agent 繞一圈才回傳。這種簡單的邏輯如果能直接跳過 AI 處理，不只反應更快，還能省下不必要的 API Token 開銷。

這篇會教你如何利用 OpenClaw 的外掛系統，直接註冊自動回覆指令，並處理背景服務與 CLI 整合。

需要準備的東西

在開始之前，請確保你已經準備好：

一個開發中的 OpenClaw 外掛專案
openclaw.plugin.json 外掛清單檔案

快速開始

要在外掛中註冊一個不經過 AI agent 的斜線指令（Slash Command），你可以直接在導出的函式中使用 api.registerCommand。

export default function(api) {
  api.registerCommand({
    name: "mystatus",
    description: "Show plugin status",
    acceptsArgs: false,
    requireAuth: true,
    handler: (ctx) => ({
      text: `Plugin running on ${ctx.channel}`
    })
  });
}

Command Context 參數說明

當指令被觸發時，handler 會接收到一個 Context 物件，包含以下欄位：

欄位	說明
`senderId`	發送者的 ID
`channel`	發送指令的頻道
`isAuthorizedSender`	發送者是否已獲得授權
`args`	指令參數（若 `acceptsArgs` 為 `true`）
`commandBody`	完整的指令文字內容
`config`	當前的 OpenClaw 設定

Command Options 設定項

選項	說明
`name`	指令名稱（不含 `/`）
`description`	說明文字（用於 Help）
`acceptsArgs`	是否接受參數（預設：false）
`requireAuth`	是否需要授權用戶才能執行（預設：true）
`handler`	執行的函式，需回傳 `{ text: string }`

註冊背景服務

如果你的外掛需要在後台執行任務（例如定時檢查更新或維持連線），可以使用 api.registerService：

export default function(api) {
  api.registerService({
    id: "my-service",
    start: () => api.logger.info("ready"),
    stop: () => api.logger.info("bye"),
  });
}

註冊 CLI 指令

你也可以將外掛的功能整合進 OpenClaw 的終端機指令中：

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

外掛清單 (Plugin Manifest)

每個外掛都必須包含一個 openclaw.plugin.json 檔案，用來定義 ID、名稱以及設定檔的 Schema：

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "configSchema": {
    "type": "object",
    "properties": {
      "apiKey": { "type": "string" }
    }
  },
  "uiHints": {
    "apiKey": { "label": "API Key", "sensitive": true }
  }
}

發佈到 npm

準備好後，你可以按照以下步驟分享你的外掛：

在 package.json 加入 OpenClaw 設定：

{
  "name": "@yourscope/my-plugin",
  "openclaw": {
    "extensions": ["./index.ts"]
  }
}

執行發佈：npm publish
其他使用者只需執行此指令即可安裝：

openclaw plugins install @yourscope/my-plugin

疑難排解

指令沒反應？ 請檢查指令名稱是否與內建指令（如 help, status, reset）衝突，這些保留指令無法被覆蓋。
大小寫問題： 指令名稱不區分大小寫。
優先權順序： 外掛指令會比內建指令與 AI agent 更早被處理。

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

下一步

你是不是也遇過這種情況：明明照著文件寫了配置，重啟之後插件卻像消失了一樣完全沒反應？或者是改了一個小地方，結果整個系統噴出一堆 Config Validation 錯誤，讓你盯著螢幕發呆。

這種卡在環境設定、找不到為什麼插件不載入的感覺真的很煩人。為了讓你把時間花在開發功能而不是 debug 環境，我整理了這份清單，幫你快速排除常見的插件問題。

需要準備的東西

openclaw.plugin.json 檔案
你的插件目錄路徑（例如 ~/.openclaw/extensions/）
package.json (如果你打算使用 Package Packs)

快速開始

遇到插件沒反應時，請先執行這四個檢查動作：

確認 plugins.enabled 是否設定為 true。
檢查插件是否不小心被放進了 deny 名單。
確保插件目錄下確實存在 openclaw.plugin.json。
如果你手動安裝了多個插件，請檢查是否有重複的 ID，並移除多餘的目錄。

疑難排解

插件無法載入 (Plugin not loading)

請檢查：

plugins.enabled 是不是 true？
插件有沒有在 deny 名單裡？
目錄下有沒有 openclaw.plugin.json？

配置驗證錯誤 (Config validation errors)

原因： 配置中出現了未知的插件 ID。OpenClaw 對於這類錯誤檢查非常嚴格。

解決方法： 從 entries、allow、deny 這些欄位中，移除所有指向已禁用或已卸載插件的引用。

插件衝突 (Plugin conflicts)

原因： 多個插件使用了相同的 ID。

解決方法： 系統只會載入第一個找到的插件。請檢查你的 extension 目錄並移除重複的插件。

進階配置：Package Packs

如果你的插件目錄包含一個帶有 openclaw.extensions 的 package.json，你可以一次定義多個擴充功能：

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

在這種情況下，每個項目都會變成一個獨立插件。如果一個 pack 列出了多個 extensions，插件 ID 的格式會變成 name/<fileBase>。

如果你的插件需要用到 npm 依賴，記得在該目錄下執行安裝：

cd ~/.openclaw/extensions/my-pack
npm install

Channel Catalog Metadata

Channel 插件可以透過 openclaw.channel 宣告上架元數據，並透過 openclaw.install 提供安裝提示：

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/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"
    }
  }
}

外部目錄 (External catalogs)

你可以將 JSON 檔案放在以下路徑來擴充目錄：

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

或者直接設定 OPENCLAW_PLUGIN_CATALOG_PATHS 環境變數。

還是搞不定嗎？我們的 AI Setup Assistant 可以幫你調試插件設定。

下一步

當你想把機器人接到一個新的聊天平台，卻發現現有的 Provider 都不支援時，那種卡住的感覺真的很煩。你明明已經寫好了對話邏輯，卻因為沒有對應的通道而沒辦法讓訊息傳出去。

如果你需要的是一個全新的聊天介面（而非新的模型供應商），你就需要為 Gateway 撰寫一個 Messaging Channel。這篇文章會帶你走一遍實作流程。

需要準備的東西

OpenClaw API 權限
TypeScript 開發環境

快速開始

建立一個新的 Channel 只需要五個步驟。

Step 1: 決定 ID 與 Config 形狀

所有的 Channel 配置都放在 channels.<id> 底下。你需要先定義你的配置格式：

{
  channels: {
    acmechat: {
      accounts: {
        default: { token: "TOKEN", enabled: true }
      }
    }
  }
}

Step 2: 定義 Channel Metadata

Metadata 決定了你的 Channel 在 CLI 或 UI 中如何顯示。

欄位	用途
`meta.label`	在 CLI/UI 顯示的名稱
`meta.selectionLabel`	較長的選取文字描述
`meta.docsPath`	文件連結 (例如：`/channels/acmechat`)
`meta.blurb`	簡短描述
`meta.aliases`	替代的 Channel ID
`meta.preferOver`	替換掉另一個 Channel

Step 3: 實作必要的 Adapter

這是插件的核心，你需要定義如何取得帳號資訊以及如何傳送訊息。

const plugin = {
  id: "acmechat",
  meta: { /* ... */ },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, id) => cfg.channels?.acmechat?.accounts?.[id ?? "default"]
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text }) => ({ ok: true })
  }
};

Step 4: 加入選配的 Adapter

根據你的需求，你可以實作更多的功能：

Adapter	用途
`setup`	設定精靈整合
`security`	私訊（DM）政策
`status`	健康檢查與診斷
`gateway`	啟動/停止/登入
`mentions`	@提及處理
`threading`	討論串支援
`streaming`	串流回應
`actions`	訊息動作
`commands`	原生指令行為

Step 5: 註冊插件

最後，在你的進入點註冊這個 Channel：

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

命名規範

在開發過程中，請遵循以下慣例：

類型	規範	範例
Gateway 方法	`pluginId.action`	`voicecall.status`
Tools	`snake_case`	`voice_call`
CLI 指令	kebab-case	`voicecall-start`

請注意，命名時要避開與核心指令衝突。

在插件中使用 Skills

插件可以透過加入 skills/ 目錄來提供 Skill 功能：

my-plugin/
├── index.ts
├── openclaw.plugin.json
└── skills/
    └── my-skill/
        └── SKILL.md

你可以透過 plugins.entries.<id>.enabled 來啟用它，並確保它存在於你管理的 Skill 路徑中。

安全注意事項

插件會與 Gateway 共用程序（in-process） 執行。請將它們視為受信任的程式碼：

只安裝你信任的插件
優先使用 plugins.allow 白名單
修改後請重啟 Gateway
在啟用前務必審查插件原始碼

測試插件

你的插件應該附帶測試：

Repo 內插件：將 Vitest 測試放在 src/** 下（例如：src/plugins/voice-call.plugin.test.ts）
已發佈插件：執行自己的 CI 並驗證 openclaw.extensions 指向建置後的進入點

# 執行插件測試
cd ~/.openclaw/extensions/my-plugin
npm test

疑難排解

指令衝突：如果你的指令沒反應，請檢查命名規範，確保沒有與核心指令撞名。
權限問題：如果插件行為異常，請確認該插件是否已加入 plugins.allow 白名單。

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

下一步

Plugin Agent Tools → — 建立 AI 可呼叫的工具
Plugin Manifest → — 完整的 Manifest 參考文件
Voice Call Plugin → — 範例插件實作導覽助

OpenClaw Expert

還是卡住了？

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