外掛（擴充功能）

OpenClaw 外掛系統，透過小型程式碼模組擴充平台功能，包含安裝、設定及開發指南。

快速開始（外掛新手？）

外掛是一個小型程式碼模組，用於擴充 OpenClaw 的額外功能（命令、工具和閘道 RPC）。

大多數時候，你會在需要核心 OpenClaw 尚未內建的功能時使用外掛（或你想將選用功能排除在主安裝之外）。

快速路徑：

查看已載入的內容：

openclaw plugins list

安裝官方外掛（範例：Voice Call）：

openclaw plugins install @openclaw/voice-call

Npm 規格為僅限登錄庫（套件名稱 + 選用版本/標籤）。Git/URL/檔案規格會被拒絕。

重啟閘道，然後在 plugins.entries.<id>.config 下設定。

參閱 Voice Call 了解具體的外掛範例。尋找第三方列表？參閱社群外掛。

可用外掛（官方）

Microsoft Teams 自 2026.1.15 起僅限外掛；若使用 Teams 請安裝 @openclaw/msteams。
Memory (Core) — 內建記憶搜尋外掛（預設透過 plugins.slots.memory 啟用）
Memory (LanceDB) — 內建長期記憶外掛（自動召回/擷取；設定 plugins.slots.memory = "memory-lancedb"）
Voice Call — @openclaw/voice-call
Zalo Personal — @openclaw/zalouser
Matrix — @openclaw/matrix
Nostr — @openclaw/nostr
Zalo — @openclaw/zalo
Microsoft Teams — @openclaw/msteams
Google Antigravity OAuth（供應商驗證） — 內建為 google-antigravity-auth（預設停用）
Gemini CLI OAuth（供應商驗證） — 內建為 google-gemini-cli-auth（預設停用）
Qwen OAuth（供應商驗證） — 內建為 qwen-portal-auth（預設停用）
Copilot Proxy（供應商驗證） — 本地 VS Code Copilot Proxy 橋接；與內建 github-copilot 裝置登入不同（內建，預設停用）

OpenClaw 外掛是透過 jiti 在執行時載入的 TypeScript 模組。設定驗證不會執行外掛程式碼；它使用外掛清單和 JSON Schema。參閱外掛清單。

外掛可以註冊：

閘道 RPC 方法
閘道 HTTP 處理器
代理工具
CLI 命令
背景服務
選用的設定驗證
技能（透過在外掛清單中列出 skills 目錄）
自動回覆命令（不呼叫 AI 代理即可執行）

外掛與閘道在同一程序中運行，因此應將其視為受信任的程式碼。工具撰寫指南：外掛代理工具。

執行時輔助工具

外掛可以透過 api.runtime 存取選定的核心輔助工具。對於電話 TTS：

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

注意事項：

使用核心 messages.tts 設定（OpenAI 或 ElevenLabs）。
回傳 PCM 音訊緩衝區 + 取樣率。外掛必須為供應商重新取樣/編碼。
Edge TTS 不支援電話功能。

探索與優先順序

OpenClaw 依序掃描：

設定路徑
- plugins.load.paths（檔案或目錄）
工作區擴充功能
- <workspace>/.openclaw/extensions/*.ts
- <workspace>/.openclaw/extensions/*/index.ts
全域擴充功能
- ~/.openclaw/extensions/*.ts
- ~/.openclaw/extensions/*/index.ts
內建擴充功能（隨 OpenClaw 附帶，預設停用）
- <openclaw>/extensions/*

內建外掛必須透過 plugins.entries.<id>.enabled 或 openclaw plugins enable <id> 明確啟用。已安裝的外掛預設啟用，但可以同樣方式停用。

安全強化注意事項：

若 plugins.allow 為空且有非內建外掛可被探索，OpenClaw 會在啟動時記錄警告，顯示外掛 ID 和來源。
候選路徑在探索准入前會進行安全檢查。OpenClaw 在以下情況封鎖候選：
- 擴充功能入口解析到外掛根目錄之外（包括符號連結/路徑穿越逃逸），
- 外掛根目錄/來源路徑為全球可寫，
- 非內建外掛的路徑擁有權可疑（POSIX 擁有者既非目前 uid 也非 root）。

每個外掛必須在其根目錄包含 openclaw.plugin.json 檔案。若路徑指向檔案，外掛根目錄為該檔案的目錄，且必須包含清單。

若多個外掛解析為相同 ID，上述順序中第一個匹配者勝出，較低優先順序的副本被忽略。

外掛 ID

預設外掛 ID：

套件包：package.json 的 name
獨立檔案：檔案基礎名稱（~/.../voice-call.ts -> voice-call）

若外掛匯出 id，OpenClaw 會使用它，但在與設定 ID 不匹配時發出警告。

設定

{
  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>：每個外掛的開關 + 設定

設定變更需要重啟閘道。

驗證規則（嚴格）：

entries、allow、deny 或 slots 中的未知外掛 ID 為錯誤。
未知的 channels.<id> 鍵為錯誤，除非外掛清單宣告了該頻道 ID。
外掛設定使用嵌入 openclaw.plugin.json 中的 JSON Schema（configSchema）進行驗證。
若外掛已停用，其設定會保留並發出警告。

外掛插槽（獨佔類別）

某些外掛類別為獨佔的（一次只能有一個活動）。使用 plugins.slots 選擇哪個外掛擁有該插槽：

{
  plugins: {
    slots: {
      memory: "memory-core", // 或 "none" 停用記憶外掛
    },
  },
}

若多個外掛宣告 kind: "memory"，僅選定的那個會載入。其他會被停用並顯示診斷資訊。

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 install @openclaw/voice-call --pin # 儲存精確解析的 name@version
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 會警告並要求確認（使用全域 --yes 可跳過提示）。

外掛也可以註冊自己的頂層命令（範例：openclaw voicecall）。

外掛 API（概述）

外掛匯出以下任一：

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

外掛 Hooks

外掛可以在執行時註冊 hooks。這讓外掛無需單獨的 hook 套件安裝即可捆綁事件驅動的自動化。

範例

export default function register(api) {
  api.registerHook(
    "command:new",
    async () => {
      // Hook 邏輯在此。
    },
    {
      name: "my-plugin.command-new",
      description: "Runs when /new is invoked",
    },
  );
}

注意事項：

透過 api.registerHook(...) 明確註冊 hooks。
Hook 資格規則仍然適用（作業系統/二進位檔/環境/設定需求）。
外掛管理的 hooks 在 openclaw hooks list 中顯示為 plugin:<id>。
你無法透過 openclaw hooks 啟用/停用外掛管理的 hooks；請改為啟用/停用外掛。

供應商外掛（模型驗證）

外掛可以註冊模型供應商驗證流程，讓使用者可以在 OpenClaw 內執行 OAuth 或 API 金鑰設定（不需要外部腳本）。

透過 api.registerProvider(...) 註冊供應商。每個供應商公開一個或多個驗證方法（OAuth、API 金鑰、裝置代碼等）。這些方法驅動：

openclaw models auth login --provider <id> [--method <id>]

註冊訊息頻道

外掛可以註冊行為與內建頻道（WhatsApp、Telegram 等）相同的頻道外掛。頻道設定位於 channels.<id> 下，由你的頻道外掛程式碼驗證。

註冊閘道 RPC 方法

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

註冊 CLI 命令

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

註冊自動回覆命令

外掛可以註冊不呼叫 AI 代理即可執行的自訂斜線命令。這對於切換命令、狀態檢查或不需要 LLM 處理的快速操作很有用。

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

命令選項：

name：命令名稱（不含前導 /）
description：命令清單中顯示的說明文字
acceptsArgs：命令是否接受引數（預設：false）
requireAuth：是否要求已授權的傳送者（預設：true）
handler：回傳 { text: string } 的函式（可為非同步）

注意事項：

外掛命令在內建命令和 AI 代理之前處理
命令全域註冊，跨所有頻道運作
命令名稱不區分大小寫（/MyStatus 匹配 /mystatus）
命令名稱必須以字母開頭，僅包含字母、數字、連字號和底線
保留的命令名稱（如 help、status、reset 等）無法被外掛覆寫

註冊背景服務

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

命名慣例

閘道方法：pluginId.action（範例：voicecall.status）
工具：snake_case（範例：voice_call）
CLI 命令：kebab 或 camel，但避免與核心命令衝突

技能

外掛可以在儲存庫中附帶技能（skills/<name>/SKILL.md）。透過 plugins.entries.<id>.enabled（或其他設定閘門）啟用，並確保它存在於你的工作區/受管理技能位置中。

發布（npm）

建議的封裝方式：

主套件：openclaw（此儲存庫）
外掛：在 @openclaw/* 下的獨立 npm 套件（範例：@openclaw/voice-call）

發布契約：

外掛的 package.json 必須包含帶有一個或多個入口檔案的 openclaw.extensions。
入口檔案可以是 .js 或 .ts（jiti 在執行時載入 TS）。
openclaw plugins install <npm-spec> 使用 npm pack，解壓到 ~/.openclaw/extensions/<id>/，並在設定中啟用。
設定鍵穩定性：作用域套件會正規化為 plugins.entries.* 的無作用域 ID。

安全注意事項

外掛與閘道在同一程序中運行。應將其視為受信任的程式碼：

僅安裝你信任的外掛。
偏好使用 plugins.allow 允許清單。
變更後重啟閘道。