> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 外掛

外掛透過通道、模型提供者、代理工具框架、工具、Skills、語音、即時轉錄、聲音、媒體理解、生成、網頁擷取、網頁搜尋，以及其他執行階段能力來擴充 OpenClaw。

使用本頁安裝外掛、重新啟動閘道、驗證執行階段已載入它，並處理常見設定失敗。僅含命令的範例請參閱[管理外掛](/zh-TW/plugins/manage-plugins)。如需內建、官方外部與僅原始碼外掛的產生清單，請參閱[外掛清單](/zh-TW/plugins/plugin-inventory)。

## 需求

* 可使用 `openclaw` 命令列介面的 OpenClaw checkout 或安裝
* 可存取所選來源（ClawHub、npm 或 git 主機）的網路連線
* 該外掛設定文件中指定的任何外掛專屬憑證、設定鍵或作業系統工具
* 服務你的通道的閘道具備重新載入或重新啟動的權限

## 快速開始

<Steps>
  <Step title="尋找外掛">
    在 [ClawHub](/clawhub) 搜尋公開外掛套件：

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw plugins search "calendar"
    ```

    ClawHub 是社群外掛的主要探索介面。在啟動切換期間，普通的裸套件規格仍會從 npm 安裝，除非它們符合官方外掛 id。符合內建外掛的原始 `@openclaw/*` 規格會解析為該內建副本。當你需要特定來源時，請使用明確的來源前綴。
  </Step>

  <Step title="安裝外掛">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    # From ClawHub.
    openclaw plugins install clawhub:<package>

    # From npm.
    openclaw plugins install npm:<package>

    # From git.
    openclaw plugins install git:github.com/<owner>/<repo>@<ref>

    # From a local development checkout.
    openclaw plugins install ./my-plugin
    openclaw plugins install --link ./my-plugin
    ```

    將安裝外掛視同執行程式碼。為了可重現的正式環境安裝，優先使用釘選版本。
  </Step>

  <Step title="設定並啟用它">
    在 `plugins.entries.<id>.config` 下設定外掛專屬設定。
    如果外掛尚未啟用，請啟用它：

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw plugins enable <plugin-id>
    ```

    如果已設定 `plugins.allow`，已安裝的外掛 id 必須在該清單中，外掛才能載入。`openclaw plugins install` 會將已安裝的 id 加入現有的 `plugins.allow` 清單，並從 `plugins.deny` 移除相同 id，讓明確安裝的外掛在重新啟動後可載入。
  </Step>

  <Step title="讓閘道重新載入">
    安裝、更新或解除安裝外掛程式碼需要重新啟動閘道。已啟用設定重新載入的受管理閘道會偵測變更後的外掛安裝記錄並自動重新啟動。否則，請自行重新啟動：

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw gateway restart
    ```

    啟用/停用更新設定與冷登錄。執行階段檢查仍是證明即時執行階段介面的最清楚方式。
  </Step>

  <Step title="驗證執行階段註冊">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw plugins inspect <plugin-id> --runtime --json
    ```

    使用 `--runtime` 證明已註冊的工具、掛鉤、服務、閘道方法或外掛擁有的命令列介面命令。單純的 `inspect` 只會進行冷 manifest 與登錄檢查。
  </Step>
</Steps>

## 設定

### 選擇安裝來源

| 來源          | 使用時機                             | 範例                                                             |
| ----------- | -------------------------------- | -------------------------------------------------------------- |
| ClawHub     | 你想要 OpenClaw 原生探索、掃描、版本中繼資料與安裝提示 | `openclaw plugins install clawhub:<package>`                   |
| npm         | 你需要直接的 npm 登錄或 dist-tag 工作流程     | `openclaw plugins install npm:<package>`                       |
| git         | 你需要儲存庫中的分支、標籤或提交                 | `openclaw plugins install git:github.com/<owner>/<repo>@<ref>` |
| 本機路徑        | 你正在同一台機器上開發或測試外掛                 | `openclaw plugins install --link ./my-plugin`                  |
| marketplace | 你正在安裝 Claude 相容的 marketplace 外掛  | `openclaw plugins install <plugin> --marketplace <source>`     |

裸套件規格具有特殊相容性行為：符合內建外掛 id 的裸名稱會使用該內建來源；符合官方外部外掛 id 的裸名稱會使用官方套件目錄；任何其他裸規格在啟動切換期間會透過 npm 安裝。符合內建外掛的原始 `@openclaw/*` 規格也會先解析為內建副本，再進行 npm fallback。使用 `npm:@openclaw/<plugin>@<version>` 可刻意安裝外部 npm 套件，而不是內建副本。使用 `clawhub:`、`npm:`、`git:` 或 `npm-pack:` 進行確定性的來源選擇。完整命令合約請參閱 [`openclaw plugins`](/zh-TW/cli/plugins#install)。

對於 npm 安裝，未釘選的規格和 `@latest` 會選擇宣告與此 OpenClaw 建置相容的最新穩定套件。如果 npm 目前的 latest 發行宣告的 `openclaw.compat.pluginApi` 或 `openclaw.install.minHostVersion` 比此建置支援的版本更新，OpenClaw 會掃描較舊的穩定版本，並安裝符合條件的最新版本。精確版本與明確通道標籤（例如 `@beta`）會持續釘選到所選套件，並在不相容時失敗。

### 操作者安裝政策

設定 `security.installPolicy`，在外掛安裝或更新繼續之前執行受信任的本機政策命令。該政策會接收中繼資料與暫存來源路徑，並可允許或封鎖安裝。它涵蓋命令列介面與閘道支援的安裝/更新路徑。外掛 `before_install` 掛鉤會在稍後執行，而且只會在已載入外掛掛鉤的 OpenClaw 程序中執行，因此請改用 `security.installPolicy` 處理操作者擁有的安裝決策。已棄用的 `--dangerously-force-unsafe-install` 旗標基於相容性仍會接受，但不會執行任何動作：它不會繞過安裝政策或 OpenClaw 內建的外掛依賴 denylist。

請參閱 [Skills 設定](/zh-TW/tools/skills-config#operator-install-policy-securityinstallpolicy)，了解 Skills 與外掛共用的 `security.installPolicy` exec schema。

### 設定外掛政策

常見外掛設定形狀如下：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-plugin"] },
    slots: { memory: "memory-core" },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}
```

主要政策規則：

* `plugins.enabled: false` 會停用所有外掛並略過探索/載入工作。過時的外掛參照在此狀態啟用時會保持惰性；如果你想移除過時 id，請在執行 doctor 清理之前重新啟用外掛。
* `plugins.deny` 優先於 allow 與個別外掛啟用狀態。
* `plugins.allow` 是獨占 allowlist。不在 allowlist 中的外掛擁有工具即使 `tools.allow` 包含 `"*"` 仍不可用。
* `plugins.entries.<id>.enabled: false` 會停用單一外掛，同時保留其設定。
* `plugins.load.paths` 會加入明確的本機外掛檔案或目錄。受管理的 `plugins install` 本機路徑必須是外掛目錄或封存檔；獨立外掛檔案請使用 `plugins.load.paths`。
* 來自工作區的外掛預設停用；使用本機工作區程式碼前，請明確啟用或將其加入 allowlist。
* 內建外掛會遵循其內建的預設開啟/預設關閉中繼資料，除非設定明確覆寫。
* `plugins.slots.<slot>`（`memory` 或 `contextEngine`）會為獨占類別選擇一個外掛。Slot 選擇算作明確啟用，並會為該 slot 強制啟用所選外掛，即使它原本需要 opt-in。`plugins.deny` 與 `plugins.entries.<id>.enabled: false` 仍會封鎖它。
* 當設定指定內建 opt-in 外掛擁有的其中一個介面時，該外掛可自動啟用，例如 provider/model ref、通道設定、命令列介面後端或代理工具框架執行階段。
* OpenAI 系列 Codex 路由會保持提供者與執行階段外掛邊界分離：舊版 Codex model refs 是由 doctor 修復的舊版設定，而內建 `codex` 外掛則擁有標準 `openai/*` agent refs、明確 `agentRuntime.id: "codex"` 與舊版 `codex/*` refs 的 Codex app-server 執行階段。

當未設定 `plugins.allow`，且非內建外掛是從工作區或全域外掛根目錄自動探索而來時，啟動日誌會輸出 `plugins.allow is empty; discovered non-bundled plugins may auto-load: ...`，其中包含探索到的外掛 id；若清單較短，還會包含最小的 `plugins.allow` 片段。在將受信任外掛複製到 `openclaw.json` 之前，請對列出的外掛 id 執行 [`openclaw plugins list --enabled --verbose`](/zh-TW/cli/plugins#list) 或 [`openclaw plugins inspect <id>`](/zh-TW/cli/plugins#inspect)。當診斷指出某外掛是在 `without install/load-path provenance` 狀態下載入時，也適用相同的信任釘選：檢查該外掛 id，然後將它釘選到 `plugins.allow`，或從受信任來源重新安裝，讓 OpenClaw 記錄安裝 provenance。

當設定驗證回報過時外掛 id、allowlist/工具不相符，或舊版內建外掛路徑時，請執行 `openclaw doctor` 或 `openclaw doctor --fix`。

## 了解外掛格式

OpenClaw 可辨識兩種外掛格式：

| 格式             | 載入方式                                        | 使用時機                               |
| -------------- | ------------------------------------------- | ---------------------------------- |
| 原生 OpenClaw 外掛 | `openclaw.plugin.json` 加上在程序內載入的執行階段模組      | 你正在安裝或建置 OpenClaw 專用的執行階段能力        |
| 相容 bundle      | Codex、Claude 或 Cursor 外掛配置對應到 OpenClaw 外掛清單 | 你正在重用相容的 Skills、命令、掛鉤或 bundle 中繼資料 |

兩種格式都會出現在 `openclaw plugins list`、`openclaw plugins inspect`、`openclaw plugins enable` 和 `openclaw plugins disable` 中。請參閱[外掛 bundles](/zh-TW/plugins/bundles) 了解 bundle 相容性邊界，並參閱[建置外掛](/zh-TW/plugins/building-plugins) 了解原生外掛撰寫。

## 外掛掛鉤

外掛可透過兩種不同 API 在執行階段註冊掛鉤：

* `api.on(...)` 型別化掛鉤，用於執行階段生命週期事件。這是 middleware、政策、訊息重寫、提示塑形與工具控制的首選介面。
* `api.registerHook(...)` 用於[掛鉤](/zh-TW/automation/hooks)中描述的內部掛鉤系統。這主要用於粗略命令/生命週期副作用，以及與現有 HOOK 風格自動化相容。

快速規則：如果處理器需要優先順序、合併語意或封鎖/取消行為，請使用型別化掛鉤。如果它只是回應 `command:new`、`command:reset`、`message:sent` 或類似的粗略事件，`api.registerHook` 即可。

外掛管理的內部掛鉤會以 `plugin:<id>` 顯示在 `openclaw hooks list` 中。你無法透過 `openclaw hooks` 啟用或停用它們；請改為啟用或停用外掛。

## 驗證作用中的閘道

`openclaw plugins list` 和一般的 `openclaw plugins inspect` 會讀取冷設定、manifest 與登錄狀態。它們無法證明已在執行的閘道已匯入相同的外掛程式碼。

當外掛看似已安裝，但即時聊天流量未使用它時：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway status --deep --require-rpc
openclaw plugins inspect <plugin-id> --runtime --json
openclaw gateway restart
```

受管理的閘道會在外掛安裝、更新和解除安裝變更改動外掛來源後自動重新啟動。在 VPS 或容器安裝中，請確保任何手動重新啟動都針對實際提供你頻道服務的 `openclaw gateway run` 子程序，而不只是包裝程式或監督程式。

## 疑難排解

| 症狀                                | 檢查                                                                                                    | 修正                                                      |
| --------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| 外掛出現在 `plugins list` 中，但執行階段鉤子未執行 | 使用 `openclaw plugins inspect <id> --runtime --json`，並用 `gateway status --deep --require-rpc` 確認作用中的閘道 | 在安裝、更新、設定或來源變更後重新啟動即時閘道                                 |
| 出現重複的頻道或工具擁有權診斷                   | 執行 `openclaw plugins list --enabled --verbose`，使用 `--runtime --json` 檢查每個疑似外掛，並比較頻道/工具擁有權             | 停用其中一個擁有者、移除過期安裝，或使用資訊清單 `preferOver` 進行有意替換            |
| 設定顯示缺少某個外掛                        | 查看[外掛清單](/zh-TW/plugins/plugin-inventory)，確認它是內建、官方外部，還是僅來源                                           | 安裝外部套件、啟用內建外掛，或移除過期設定                                   |
| 安裝期間設定無效                          | 閱讀驗證訊息；如果它指向過期的外掛狀態，請執行 `openclaw doctor --fix`                                                       | Doctor 可透過停用該項目並移除無效承載資料來隔離無效的外掛設定                      |
| 外掛路徑因可疑擁有權或權限而被封鎖                 | 在設定錯誤之前檢查診斷                                                                                           | 修正檔案系統擁有權/權限，然後執行 `openclaw plugins registry --refresh` |
| `OPENCLAW_NIX_MODE=1` 封鎖生命週期命令    | 確認安裝是由 Nix 管理                                                                                         | 在 Nix 來源中變更外掛選擇，而不是使用外掛變更命令                             |
| 相依性匯入在執行階段失敗                      | 檢查該外掛是透過 npm/git/ClawHub 安裝，還是從本機路徑載入                                                                 | 執行 `openclaw plugins update <id>`、重新安裝來源，或自行安裝本機外掛相依性   |

當過期的外掛設定仍命名一個已無法探索的頻道外掛時，設定驗證會將該頻道鍵降級為警告，而不是硬性失敗，因此閘道啟動仍可服務所有其他頻道。執行 `openclaw doctor --fix` 以移除過期的外掛和頻道項目。沒有過期外掛證據的未知頻道鍵仍會使驗證失敗，讓拼字錯誤保持可見。

對於有意的頻道替換，偏好的外掛應宣告 `channelConfigs.<channel-id>.preferOver`，並填入舊版或較低優先順序的外掛 ID。如果兩個外掛都明確啟用，OpenClaw 會保留該請求並回報重複的頻道/工具診斷，而不是默默選擇其中一個擁有者。

如果已安裝套件回報它 `requires compiled runtime output for
TypeScript entry ...`，表示該套件發佈時缺少 OpenClaw 在執行階段需要的 JavaScript 檔案。請在發佈者提供已編譯的 JavaScript 後更新或重新安裝，或在那之前停用/解除安裝該外掛。

### 被封鎖的外掛路徑擁有權

如果診斷顯示
`blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)`
且驗證接著顯示 `plugin present but blocked`，表示 OpenClaw 發現外掛檔案的擁有者與載入它們的程序所屬 Unix 使用者不同。保留外掛設定；修正檔案系統擁有權，或以擁有狀態目錄的相同使用者身分執行 OpenClaw。

對於 Docker 安裝，官方映像檔會以 `node`（uid `1000`）執行，因此主機綁定掛載的 OpenClaw 設定和工作區目錄通常應由 uid `1000` 擁有：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
```

如果你有意以 root 執行 OpenClaw，請改為將受管理的外掛根目錄修復為 root 擁有權：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
sudo chown -R root:root /path/to/openclaw-config/npm
```

修正擁有權後，重新執行 `openclaw doctor --fix` 或
`openclaw plugins registry --refresh`，讓持久化的外掛登錄與已修復的檔案相符。

### 緩慢的外掛工具設定

如果代理回合在準備工具時看似停滯，請啟用追蹤記錄並檢查外掛工具工廠計時行：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw config set logging.level trace
openclaw logs --follow
```

尋找：

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
[trace:plugin-tools] factory timings ...
```

摘要會列出總工廠時間和最慢的外掛工具工廠，包括外掛 ID、宣告的工具名稱、結果形狀，以及該工具是否為選用。當單一工廠耗時至少 1 秒，或外掛工具工廠準備總時間至少 5 秒時，緩慢行會提升為警告。

OpenClaw 會快取成功的外掛工具工廠結果，以供相同有效請求內容的重複解析使用。快取鍵包含有效的執行階段設定、工作區和代理 ID、沙箱政策、瀏覽器設定、傳遞內容、請求者身分和擁有權狀態，因此依賴這些受信任欄位的工廠會在內容變更時重新執行。如果計時仍然偏高，外掛可能在回傳其工具定義之前執行了昂貴的工作。

如果某個外掛主導計時，請檢查其執行階段註冊：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins inspect <plugin-id> --runtime --json
```

然後更新、重新安裝或停用該外掛。外掛作者應將昂貴的相依性載入移到工具執行路徑之後，而不是在工具工廠內執行。

如需相依性根目錄、套件中繼資料驗證、登錄記錄、啟動重新載入行為和舊版清理，請參閱[外掛相依性解析](/zh-TW/plugins/dependency-resolution)。

## 相關

* [管理外掛](/zh-TW/plugins/manage-plugins) - list、install、update、uninstall 和 publish 的命令範例
* [`openclaw plugins`](/zh-TW/cli/plugins) - 完整的命令列介面參考
* [外掛清單](/zh-TW/plugins/plugin-inventory) - 產生的內建與外部外掛清單
* [外掛參考](/zh-TW/plugins/reference) - 產生的個別外掛參考頁面
* [社群外掛](/zh-TW/plugins/community) - ClawHub 探索與文件 PR 政策
* [外掛相依性解析](/zh-TW/plugins/dependency-resolution) - 安裝根目錄、登錄記錄和執行階段邊界
* [建置外掛](/zh-TW/plugins/building-plugins) - 原生外掛撰寫指南
* [外掛 SDK 概觀](/zh-TW/plugins/sdk-overview) - 執行階段註冊、鉤子和 API 欄位
* [外掛資訊清單](/zh-TW/plugins/manifest) - 資訊清單與套件中繼資料