跳轉到主要內容

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.

Plugin 可為 OpenClaw 擴充新功能：通道、模型供應商、 代理程式執行框架、工具、Skills、語音、即時轉錄、即時 語音、媒體理解、圖像生成、影片生成、Web 擷取、Web 搜尋，以及更多功能。有些 Plugin 是 核心（隨 OpenClaw 提供），其他則是 外部 Plugin。多數外部 Plugin 都透過 ClawHub 發布與探索。npm 仍支援直接安裝，以及在遷移完成前 暫時保留的一組 OpenClaw 擁有的 Plugin 套件。

​
快速開始

如需可直接複製貼上的安裝、列出、解除安裝、更新與發布範例，請參閱 管理 Plugin。
1

查看已載入的項目

openclaw plugins list
2

安裝 Plugin

# Search ClawHub plugins
openclaw plugins search "calendar"

# From ClawHub
openclaw plugins install clawhub:openclaw-codex-app-server

# From npm
openclaw plugins install npm:@acme/openclaw-plugin
openclaw plugins install npm-pack:./openclaw-plugin-1.2.3.tgz

# From git
openclaw plugins install git:github.com/acme/openclaw-plugin@v1.0.0

# From a local directory or archive
openclaw plugins install ./my-plugin
openclaw plugins install ./my-plugin.tgz
3

重新啟動 Gateway

openclaw gateway restart
然後在設定檔的 plugins.entries.\<id\>.config 下進行設定。
4

聊天原生管理

在執行中的 Gateway 中，僅限擁有者使用的 /plugins enable 和 /plugins disable 會觸發 Gateway 設定重新載入器。Gateway 會在程序內重新載入 Plugin 執行階段 介面，而新的代理程式回合會從重新整理後的登錄檔重建其工具清單。/plugins install 會變更 Plugin 原始碼，因此 Gateway 會要求重新啟動，而不是假裝目前程序能夠 安全地重新載入已匯入的模組。
5

驗證 Plugin

openclaw plugins inspect <plugin-id> --runtime --json

# If the plugin registered a CLI root, run one command from that root.
openclaw <plugin-command> --help
當你需要證明已註冊的工具、服務、gateway 方法、hook，或 Plugin 擁有的 CLI 命令時，請使用 --runtime。一般的 inspect 是冷態 manifest/registry 檢查，並且有意避免匯入 Plugin 執行階段。
如果你偏好聊天原生控制，請啟用 commands.plugins: true 並使用： 
/plugin install clawhub:<package>
/plugin show <plugin-id>
/plugin enable <plugin-id>
安裝路徑使用與 CLI 相同的解析器：本機路徑/封存檔、明確的 clawhub:<pkg>、明確的 npm:<pkg>、明確的 npm-pack:<path.tgz>、 明確的 git:<repo>，或透過 npm 的裸套件規格。 如果設定無效，安裝通常會以失敗關閉並指引你使用 openclaw doctor --fix。唯一的復原例外，是針對選擇加入 openclaw.install.allowInvalidConfigRecovery 的 Plugin 所提供的狹窄內建 Plugin 重新安裝路徑。 Gateway 啟動期間，無效的 Plugin 設定會像任何其他無效設定一樣以失敗關閉。 執行 openclaw doctor --fix，透過停用該 Plugin 項目並移除其無效設定酬載， 將有問題的 Plugin 設定隔離；一般設定備份會保留先前的值。 當通道設定參照已無法探索的 Plugin，但同一個過時 Plugin id 仍存在於 Plugin 設定或安裝記錄中時，Gateway 啟動會記錄警告並略過該通道，而不是阻擋所有其他通道。 執行 openclaw doctor --fix 以移除過時的通道/Plugin 項目；沒有過時 Plugin 證據的未知通道鍵仍會驗證失敗，讓拼字錯誤保持可見。 如果設定了 plugins.enabled: false，過時的 Plugin 參照會被視為惰性： Gateway 啟動會略過 Plugin 探索/載入工作，而 openclaw doctor 會保留已停用的 Plugin 設定，而不是自動移除它。如果你想移除過時的 Plugin id，請先重新啟用 Plugin，再執行 doctor 清理。 Plugin 相依性安裝只會在明確的安裝/更新或 doctor 修復流程中發生。Gateway 啟動、 設定重新載入，以及執行階段檢查不會執行套件管理器，也不會修復相依性樹。 本機 Plugin 必須已安裝其相依性，而 npm、git 和 ClawHub Plugin 會安裝在 OpenClaw 的受管理 Plugin 根目錄下。npm 相依性可能會在 OpenClaw 的受管理 npm 根目錄內提升；安裝/更新會在信任前掃描該受管理根目錄，而解除安裝會透過 npm 移除 npm 管理的套件。外部 Plugin 和自訂載入路徑仍必須透過 openclaw plugins install 安裝。 使用 openclaw plugins list --json 可查看每個可見 Plugin 的靜態 dependencyStatus，而不會匯入執行階段程式碼或修復相依性。 如需安裝時生命週期，請參閱 Plugin 相依性解析。

​
被封鎖的 Plugin 路徑擁有權

如果 Plugin 診斷顯示 blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) 且設定驗證接著顯示 plugin present but blocked，表示 OpenClaw 找到的 Plugin 檔案擁有者，與載入這些檔案的程序所屬 Unix 使用者不同。 請保留 Plugin 設定；修正檔案系統擁有權，或以擁有狀態目錄的同一使用者執行 OpenClaw。 對於 Docker 安裝，官方映像檔會以 node（uid 1000）執行，因此主機 bind-mounted 的 OpenClaw 設定與工作區目錄通常應由 uid 1000 擁有： 
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
如果你刻意以 root 執行 OpenClaw，請改為將受管理 Plugin 根目錄修復為 root 擁有權： 
sudo chown -R root:root /path/to/openclaw-config/npm
修正擁有權後，重新執行 openclaw doctor --fix 或 openclaw plugins registry --refresh，讓持久化的 Plugin 登錄檔與修復後的檔案相符。 對於 npm 安裝，像 latest 或 dist-tag 這類可變選擇器會在安裝前解析， 然後固定為 OpenClaw 受管理 npm 根目錄中已驗證的精確版本。npm 完成後， OpenClaw 會驗證已安裝的 package-lock.json 項目仍符合解析出的版本與完整性。 如果 npm 寫入不同的套件中繼資料，安裝會失敗並回復受管理套件，而不是接受不同的 Plugin 成品。 受管理 npm 根目錄也會繼承 OpenClaw 套件層級的 npm overrides，因此保護封裝主機的 安全釘選也會套用至提升的外部 Plugin 相依性。 原始碼 checkout 是 pnpm 工作區。如果你 clone OpenClaw 來修改內建 Plugin， 請執行 pnpm install；接著 OpenClaw 會從 extensions/<id> 載入內建 Plugin， 讓編輯內容與套件本機相依性可直接使用。 一般 npm 根目錄安裝適用於封裝版 OpenClaw，不適用於原始碼 checkout 開發。

​
Plugin 類型

OpenClaw 識別兩種 Plugin 格式：
格式運作方式範例
原生openclaw.plugin.json + 執行階段模組；在程序內執行官方 Plugin、社群 npm 套件
Bundle與 Codex/Claude/Cursor 相容的版面配置；對應到 OpenClaw 功能.codex-plugin/、.claude-plugin/、.cursor-plugin/
兩者都會顯示在 openclaw plugins list 下。請參閱 Plugin Bundles 了解 bundle 詳細資訊。 如果你正在撰寫原生 Plugin，請從 建置 Plugin 和 Plugin SDK 概觀 開始。

​
套件進入點

原生 Plugin npm 套件必須在 package.json 中宣告 openclaw.extensions。 每個項目都必須留在套件目錄內，並解析為可讀取的執行階段檔案，或解析為具有推斷建置後 JavaScript 對應檔的 TypeScript 原始碼檔案，例如 src/index.ts 到 dist/index.js。 封裝安裝必須隨附該 JavaScript 執行階段輸出。TypeScript 原始碼 fallback 適用於 原始碼 checkout 和本機開發路徑，不適用於安裝到 OpenClaw 受管理 Plugin 根目錄的 npm 套件。 丟入全域擴充根目錄且未追蹤的目錄會被視為本機原始碼 checkout，並可直接載入 TypeScript 進入點。仍由安裝記錄命名的目錄，包括 installPath 或 sourcePath， 會保持受管理狀態，即使全域掃描看見它們，也仍保留編譯輸出需求。 如果你刻意將受管理安裝轉換為未追蹤的本機 checkout，請先透過解除安裝或 doctor 清理移除過時的安裝記錄。 如果受管理套件警告指出它 requires compiled runtime output for TypeScript entry ...，表示該套件發布時缺少 OpenClaw 執行階段所需的 JavaScript 檔案。這是 Plugin 封裝問題，不是本機設定問題。請在發布者重新發布已編譯的 JavaScript 後更新或重新安裝 Plugin，或停用/解除安裝該 Plugin，直到修正版套件可用。 當已發布的執行階段檔案不在與原始碼項目相同的路徑時，請使用 openclaw.runtimeExtensions。如果存在，runtimeExtensions 必須為每個 extensions 項目精確包含一個項目。不相符的清單會讓安裝與 Plugin 探索失敗， 而不是默默 fallback 到原始碼路徑。如果你也發布 openclaw.setupEntry，請為其建置後的 JavaScript 對應檔使用 openclaw.runtimeSetupEntry；宣告時該檔案為必要項目。 
{
  "name": "@acme/openclaw-plugin",
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"]
  }
}

​
官方 Plugin

​
遷移期間由 OpenClaw 擁有的 npm 套件

ClawHub 是多數 Plugin 的主要發行路徑。目前封裝版 OpenClaw 版本已內建許多官方 Plugin，因此在一般設定中不需要另外 npm 安裝。在所有 OpenClaw 擁有的 Plugin 都遷移到 ClawHub 前，OpenClaw 仍會在 npm 上提供一些 @openclaw/* Plugin 套件， 供較舊/自訂安裝與直接 npm 工作流程使用。 如果 npm 回報某個 @openclaw/* Plugin 套件已棄用，該套件版本來自較舊的外部套件列。 請使用目前 OpenClaw 的內建 Plugin 或本機 checkout，直到較新的 npm 套件發布。
Plugin套件文件
Discord@openclaw/discordDiscord
Feishu@openclaw/feishuFeishu
Matrix@openclaw/matrixMatrix
Mattermost@openclaw/mattermostMattermost
Microsoft Teams@openclaw/msteamsMicrosoft Teams
Nextcloud Talk@openclaw/nextcloud-talkNextcloud Talk
Nostr@openclaw/nostrNostr
Synology Chat@openclaw/synology-chatSynology Chat
Tlon@openclaw/tlonTlon
WhatsApp@openclaw/whatsappWhatsApp
Zalo@openclaw/zaloZalo
Zalo Personal@openclaw/zalouserZalo Personal

​
核心（隨 OpenClaw 提供）

anthropic, byteplus, cloudflare-ai-gateway, github-copilot, google, huggingface, kilocode, kimi-coding, minimax, mistral, qwen, moonshot, nvidia, openai, opencode, opencode-go, openrouter, qianfan, synthetic, together, venice, vercel-ai-gateway, volcengine, xiaomi, zai
  • memory-core - 內建記憶體搜尋（預設透過 plugins.slots.memory）
  • memory-lancedb - 由 LanceDB 支援、具備自動回想/擷取的長期記憶體（設定 plugins.slots.memory = "memory-lancedb"）
請參閱 Memory LanceDB，了解 OpenAI 相容的 嵌入設定、Ollama 範例、回想限制與疑難排解。
elevenlabs, microsoft
  • browser - 用於瀏覽器工具、openclaw browser CLI、browser.request Gateway 方法、瀏覽器執行階段，以及預設瀏覽器控制服務的內建瀏覽器 Plugin（預設啟用；替換前請先停用）
  • copilot-proxy - VS Code Copilot Proxy 橋接器（預設停用）
在尋找第三方 Plugin？請參閱 ClawHub。

​
設定

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-plugin"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}
欄位說明
enabled主開關（預設：true）
allowPlugin 允許清單（選用）
bundledDiscovery內建 Plugin 探索模式（預設為 allowlist）
denyPlugin 拒絕清單（選用；拒絕優先）
load.paths額外 Plugin 檔案/目錄
slots專屬插槽選擇器（例如 memory、contextEngine）
entries.\<id\>個別 Plugin 開關 + 設定
plugins.allow 是排他性的。當它非空時，只有列出的 Plugin 可以載入 或公開工具，即使 tools.allow 包含 "*" 或特定 Plugin 擁有的 工具名稱也一樣。如果工具允許清單參照 Plugin 工具，請將擁有該工具的 Plugin id 加入 plugins.allow，或移除 plugins.allow；openclaw doctor 會對這種 結構發出警告。 新設定中的 plugins.bundledDiscovery 預設為 "allowlist"，因此 限制性的 plugins.allow 清單也會封鎖被省略的內建提供者 Plugin，包括執行階段網頁搜尋提供者探索。Doctor 會在遷移期間，為較舊的 限制性允許清單設定標記 "compat"，讓升級在操作員選擇採用更嚴格模式前， 保留舊版內建提供者行為。空的 plugins.allow 仍會被視為未設定/開放。 透過 /plugins enable 或 /plugins disable 進行的設定變更，會觸發 程序內 Gateway Plugin 重新載入。新的代理回合會從重新整理後的 Plugin 登錄 重建其工具清單。安裝、更新與解除安裝等會變更來源的操作，仍會重新啟動 Gateway 程序，因為已匯入的 Plugin 模組無法安全地就地替換。 openclaw plugins list 是本機 Plugin 登錄/設定快照。其中的 enabled Plugin 表示持久化登錄與目前設定允許該 Plugin 參與。它並不證明已在執行中的遠端 Gateway 已重新載入或重新啟動到相同的 Plugin 程式碼。在使用包裝程序的 VPS/容器設定中， 請將重新啟動或會觸發重新載入的寫入傳送到實際的 openclaw gateway run 程序，或在重新載入回報失敗時，對執行中的 Gateway 使用 openclaw gateway restart。
  • 已停用：Plugin 存在，但啟用規則將其關閉。設定會保留。
  • 缺失：設定參照了探索找不到的 Plugin id。
  • 無效：Plugin 存在，但其設定不符合宣告的結構描述。Gateway 啟動只會略過該 Plugin；openclaw doctor --fix 可以透過停用它並移除其設定承載，隔離無效項目。

​
探索與優先順序

OpenClaw 會依下列順序掃描 Plugin（第一個符合者勝出）：
1

設定路徑

plugins.load.paths - 明確的檔案或目錄路徑。指回 OpenClaw 自身封裝內建 Plugin 目錄的路徑會被忽略； 執行 openclaw doctor --fix 以移除這些過時別名。
2

工作區 Plugin

\<workspace\>/.openclaw/<plugin-root>/*.ts 和 \<workspace\>/.openclaw/<plugin-root>/*/index.ts。
3

全域 Plugin

~/.openclaw/<plugin-root>/*.ts 和 ~/.openclaw/<plugin-root>/*/index.ts。
4

內建 Plugin

隨 OpenClaw 一起提供。許多預設啟用（模型提供者、語音）。 其他則需要明確啟用。
封裝安裝與 Docker 映像通常會從已編譯的 dist/extensions 樹解析內建 Plugin。 如果內建 Plugin 來源目錄被 bind mount 到相符的封裝來源路徑上，例如 /app/extensions/synology-chat，OpenClaw 會將該掛載的來源目錄 視為內建來源覆蓋，並在封裝的 /app/dist/extensions/synology-chat 套件之前探索它。這讓維護者容器 迴圈能持續運作，而不必把每個內建 Plugin 都切回 TypeScript 來源。 設定 OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1 可強制使用封裝的 dist 套件， 即使存在來源覆蓋掛載也一樣。

​
啟用規則

  • plugins.enabled: false 會停用所有 Plugin，並略過 Plugin 探索/載入工作
  • plugins.deny 一律優先於 allow
  • plugins.entries.\<id\>.enabled: false 會停用該 Plugin
  • 來源為工作區的 Plugin 預設停用（必須明確啟用）
  • 除非被覆寫，否則內建 Plugin 會遵循內建的預設啟用集合
  • 專屬插槽可以強制啟用該插槽所選取的 Plugin
  • 當設定命名了 Plugin 擁有的表面，例如提供者模型參照、頻道設定或 harness 執行階段時，某些需要選擇加入的內建 Plugin 會自動啟用
  • 當 plugins.enabled: false 啟用時，過時的 Plugin 設定會保留； 如果你想移除過時 id，請先重新啟用 Plugin 再執行 doctor 清理
  • OpenAI 家族的 Codex 路由會維持分離的 Plugin 邊界： openai-codex/* 屬於 OpenAI Plugin，而內建 Codex app-server Plugin 會由標準 openai/* 代理參照、明確的 provider/model agentRuntime.id: "codex"，或舊版 codex/* 模型參照選取

​
疑難排解執行階段 hook

如果某個 Plugin 出現在 plugins list 中，但 register(api) 副作用或 hook 未在即時聊天流量中執行，請先檢查這些項目：
  • 執行 openclaw gateway status --deep --require-rpc，並確認作用中的 Gateway URL、profile、設定路徑與程序就是你正在編輯的項目。
  • 在 Plugin 安裝/設定/程式碼變更後，重新啟動即時 Gateway。在包裝 容器中，PID 1 可能只是 supervisor；請重新啟動或傳送訊號給子 openclaw gateway run 程序。
  • 使用 openclaw plugins inspect <id> --runtime --json 確認 hook 註冊與 診斷。非內建對話 hook，例如 before_model_resolve、 before_agent_reply、before_agent_run、llm_input、llm_output、 before_agent_finalize 和 agent_end，需要 plugins.entries.<id>.hooks.allowConversationAccess=true。
  • 對於模型切換，優先使用 before_model_resolve。它會在代理回合的模型 解析前執行；llm_output 只會在某次模型嘗試產生助理輸出後執行。
  • 若要證明有效工作階段模型，請使用 openclaw sessions 或 Gateway 工作階段/狀態表面；除錯提供者承載時，請以 --raw-stream --raw-stream-path <path> 啟動 Gateway。

​
緩慢的 Plugin 工具設定

如果代理回合在準備工具時看似停滯，請啟用 trace 記錄並 檢查 Plugin 工具 factory 計時行： 
openclaw config set logging.level trace
openclaw logs --follow
尋找： 
[trace:plugin-tools] factory timings ...
摘要會列出總 factory 時間以及最慢的 Plugin 工具 factory， 包括 Plugin id、宣告的工具名稱、結果形狀，以及該工具是否為 選用。當單一 factory 至少花費 1 秒，或 Plugin 工具 factory 準備總計至少花費 5 秒時， 緩慢行會提升為警告。 OpenClaw 會快取成功的 Plugin 工具 factory 結果，以便在相同有效請求內容中 重複解析時使用。快取鍵包含有效的執行階段設定、工作區、代理/工作階段 id、 沙箱政策、瀏覽器設定、傳遞內容、請求者身分與所有權狀態，因此依賴 這些受信任欄位的 factory 會在內容變更時重新執行。 如果某個 Plugin 主導計時，請檢查其執行階段註冊： 
openclaw plugins inspect <plugin-id> --runtime --json
接著更新、重新安裝或停用該 Plugin。Plugin 作者應將昂貴的相依性載入 移到工具執行路徑之後，而不是在工具 factory 內進行。

​
重複的頻道或工具所有權

症狀：
  • channel already registered: <channel-id> (<plugin-id>)
  • channel setup already registered: <channel-id> (<plugin-id>)
  • plugin tool name conflict (<plugin-id>): <tool-name>
這些表示有多個已啟用的 Plugin 嘗試擁有相同的頻道、 設定流程或工具名稱。最常見的原因是外部頻道 Plugin 安裝在內建 Plugin 旁邊，而該內建 Plugin 現在提供相同的頻道 id。 除錯步驟：
  • 執行 openclaw plugins list --enabled --verbose，查看每個已啟用的 Plugin 與來源。
  • 對每個疑似 Plugin 執行 openclaw plugins inspect <id> --runtime --json，並 比較 channels、channelConfigs、tools 和診斷。
  • 在安裝或移除 Plugin 套件後，執行 openclaw plugins registry --refresh， 讓持久化中繼資料反映目前安裝。
  • 在安裝、登錄或設定變更後，重新啟動 Gateway。
修正選項：
  • 如果某個 Plugin 有意替換另一個相同頻道 id 的 Plugin，偏好的 Plugin 應宣告 channelConfigs.<channel-id>.preferOver，並指定 較低優先順序的 Plugin id。請參閱 /plugins/manifest#replacing-another-channel-plugin。
  • 如果重複是意外造成，請使用 plugins.entries.<plugin-id>.enabled: false 停用其中一方，或移除過時的 Plugin 安裝。
  • 如果你明確啟用了兩個 Plugin，OpenClaw 會保留該請求並 回報衝突。請為該頻道選擇一個擁有者，或重新命名 Plugin 擁有的 工具，讓執行階段表面明確無歧義。

​
Plugin 插槽（專屬類別）

有些類別是專屬的（一次只能有一個作用中）： 
{
  plugins: {
    slots: {
      memory: "memory-core", // or "none" to disable
      contextEngine: "legacy", // or a plugin id
    },
  },
}
插槽控制項目預設
memory作用中記憶體 Pluginmemory-core
contextEngine作用中內容引擎legacy（內建）

​
CLI 參考

openclaw plugins list                       # compact inventory
openclaw plugins list --enabled            # only enabled plugins
openclaw plugins list --verbose            # per-plugin detail lines
openclaw plugins list --json               # machine-readable inventory
openclaw plugins search <query>            # search ClawHub plugin catalog
openclaw plugins inspect <id>              # static detail
openclaw plugins inspect <id> --runtime    # registered hooks/tools/CLI/gateway methods
openclaw plugins inspect <id> --json       # machine-readable
openclaw plugins inspect --all             # fleet-wide table
openclaw plugins info <id>                 # inspect alias
openclaw plugins doctor                    # diagnostics
openclaw plugins registry                  # inspect persisted registry state
openclaw plugins registry --refresh        # rebuild persisted registry
openclaw doctor --fix                      # repair plugin registry state

openclaw plugins install <package>         # install from npm by default
openclaw plugins install clawhub:<pkg>     # install from ClawHub only
openclaw plugins install npm:<pkg>         # install from npm only
openclaw plugins install git:<repo>        # install from git
openclaw plugins install git:<repo>@<ref>  # install from git ref
openclaw plugins install <spec> --force    # overwrite existing install
openclaw plugins install <path>            # install from local path
openclaw plugins install -l <path>         # link (no copy) for dev
openclaw plugins install <plugin> --marketplace <source>
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <spec> --pin      # record exact resolved npm spec
openclaw plugins install <spec> --dangerously-force-unsafe-install
openclaw plugins update <id-or-npm-spec> # update one plugin
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
openclaw plugins update --all            # update all
openclaw plugins uninstall <id>          # remove config and plugin index records
openclaw plugins uninstall <id> --keep-files
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json

# Verify runtime registrations after install.
openclaw plugins inspect <id> --runtime --json

# Run plugin-owned CLI commands directly from the OpenClaw root CLI.
openclaw <plugin-command> --help

openclaw plugins enable <id>
openclaw plugins disable <id>
隨 OpenClaw 一起出貨的 bundled Plugin。許多預設已啟用（例如 bundled 模型提供者、bundled 語音提供者，以及 bundled 瀏覽器 Plugin）。其他 bundled Plugin 仍需要 openclaw plugins enable <id>。 --force 會就地覆寫既有已安裝的 Plugin 或 Hook 套件。若要例行升級受追蹤的 npm Plugin，請使用 openclaw plugins update <id-or-npm-spec>。它不支援與 --link 搭配使用，因為 --link 會重用來源路徑，而不是複製到受管理的安裝目標上。 當 plugins.allow 已設定時，openclaw plugins install 會先把已安裝的 Plugin ID 加入該 allowlist，再啟用它。如果同一個 Plugin ID 出現在 plugins.deny 中，安裝會移除該過期的 deny 項目，讓明確安裝的 Plugin 在重新啟動後可立即載入。 OpenClaw 會保留一份持久化的本機 Plugin registry，作為 Plugin 清單、貢獻擁有權與啟動規劃的冷讀取模型。安裝、更新、解除安裝、啟用與停用流程會在變更 Plugin 狀態後重新整理該 registry。同一個 plugins/installs.json 檔案會在頂層 installRecords 中保存持久安裝中繼資料，並在 plugins 中保存可重建的 manifest 中繼資料。如果 registry 遺失、過期或無效，openclaw plugins registry --refresh 會從安裝記錄、設定政策與 manifest/package 中繼資料重建其 manifest 檢視，而不載入 Plugin 執行階段模組。 在 Nix 模式（OPENCLAW_NIX_MODE=1）中，Plugin 生命週期變更指令會被停用。請改為透過該安裝的 Nix 來源管理 Plugin 套件選擇與設定；若使用 nix-openclaw，請先閱讀以代理程式為優先的 快速開始。openclaw plugins update <id-or-npm-spec> 適用於受追蹤的安裝。傳入含有 dist-tag 或精確版本的 npm package spec，會將 package 名稱解析回受追蹤的 Plugin 記錄，並記錄新的 spec 供未來更新使用。傳入不含版本的 package 名稱，會將精確 pin 住的安裝移回 registry 的預設發行線。如果已安裝的 npm Plugin 已符合解析後的版本與記錄的 artifact 身分，OpenClaw 會略過更新，不下載、不重新安裝，也不重寫設定。 當 openclaw update 在 beta 頻道上執行時，預設發行線的 npm 與 ClawHub Plugin 記錄會先嘗試 @beta，並在沒有 Plugin beta 版本時回退到 default/latest。精確版本與明確標籤會維持 pin 住。 --pin 僅適用於 npm。它不支援與 --marketplace 搭配使用，因為 marketplace 安裝會保存 marketplace 來源中繼資料，而不是 npm spec。 --dangerously-force-unsafe-install 是用於內建危險程式碼掃描器誤判的緊急覆寫。它允許 Plugin 安裝與 Plugin 更新在內建 critical 發現項目後繼續進行，但仍不會繞過 Plugin before_install 政策封鎖或掃描失敗封鎖。安裝掃描會忽略常見測試檔案與目錄，例如 tests/、__tests__/、*.test.* 與 *.spec.*，以避免封鎖封裝的測試 mock；宣告的 Plugin 執行階段進入點即使使用其中一種名稱，仍會被掃描。 此 CLI 旗標僅適用於 Plugin 安裝/更新流程。Gateway 支援的 skill 相依項安裝會改用對應的 dangerouslyForceUnsafeInstall 請求覆寫，而 openclaw skills install 仍是獨立的 ClawHub skill 下載/安裝流程。 如果你在 ClawHub 發布的 Plugin 因掃描而被隱藏或封鎖，請開啟 ClawHub dashboard，或執行 clawhub package rescan <name> 要求 ClawHub 重新檢查。--dangerously-force-unsafe-install 只影響你自己機器上的安裝；它不會要求 ClawHub 重新掃描該 Plugin，也不會讓被封鎖的發行版本公開。 相容的 bundles 會參與相同的 Plugin list/inspect/enable/disable 流程。目前的執行階段支援包含 bundle Skills、Claude command-skills、Claude settings.json 預設值、Claude .lsp.json 與 manifest 宣告的 lspServers 預設值、Cursor command-skills，以及相容的 Codex hook 目錄。 openclaw plugins inspect <id> 也會回報偵測到的 bundle 能力，以及 bundle 支援的 Plugin 的受支援或不受支援 MCP 與 LSP server 項目。 Marketplace 來源可以是來自 ~/.claude/plugins/known_marketplaces.json 的 Claude 已知 marketplace 名稱、本機 marketplace root 或 marketplace.json 路徑、像 owner/repo 這樣的 GitHub 簡寫、GitHub repo URL，或 git URL。對於遠端 marketplaces，Plugin 項目必須保留在複製出的 marketplace repo 內，且只能使用相對路徑來源。 完整詳細資訊請參閱 openclaw plugins CLI 參考。

​
Plugin API 概觀

原生 Plugin 會匯出一個公開 register(api) 的 entry object。較舊的 Plugin 可能仍使用 activate(api) 作為舊版別名，但新的 Plugin 應使用 register。 
export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
    api.registerChannel({
      /* ... */
    });
  },
});
OpenClaw 會在 Plugin 啟用期間載入 entry object，並呼叫 register(api)。loader 仍會對較舊的 Plugin 回退使用 activate(api)，但 bundled Plugin 與新的外部 Plugin 應將 register 視為公開合約。 api.registrationMode 會告訴 Plugin 其 entry 為何被載入：
模式含義
full執行階段啟用。註冊工具、hook、服務、命令、路由與其他即時副作用。
discovery唯讀能力探索。註冊提供者與中繼資料；受信任的 Plugin entry 程式碼可能會載入，但應略過即時副作用。
setup-only透過輕量 setup entry 載入通道 setup 中繼資料。
setup-runtime也需要執行階段 entry 的通道 setup 載入。
cli-metadata僅收集 CLI 命令中繼資料。
會開啟 socket、database、背景 worker 或長生命週期 client 的 Plugin entry，應使用 api.registrationMode === "full" 保護這些副作用。Discovery 載入會與啟用載入分開快取，且不會取代執行中的 Gateway registry。Discovery 是非啟用式的，但並非無匯入：OpenClaw 可能會評估受信任的 Plugin entry 或通道 Plugin 模組，以建立快照。請保持模組頂層輕量且無副作用，並將 network client、subprocess、listener、credential 讀取與 service 啟動移到完整執行階段路徑之後。 常見註冊方法：
方法註冊內容
registerProvider模型提供者（LLM）
registerChannel聊天通道
registerTool代理程式工具
registerHook / on(...)生命週期 hooks
registerSpeechProvider文字轉語音 / STT
registerRealtimeTranscriptionProvider串流 STT
registerRealtimeVoiceProvider雙工即時語音
registerMediaUnderstandingProvider影像/音訊分析
registerImageGenerationProvider影像生成
registerMusicGenerationProvider音樂生成
registerVideoGenerationProvider影片生成
registerWebFetchProviderWeb 擷取 / scrape 提供者
registerWebSearchProviderWeb 搜尋
registerHttpRouteHTTP endpoint
registerCommand / registerCliCLI 命令
registerContextEngineContext engine
registerService背景服務
typed 生命週期 hooks 的 Hook guard 行為：
  • before_tool_call：{ block: true } 為終止狀態；會略過較低優先順序的 handlers。
  • before_tool_call：{ block: false } 為無操作，且不會清除先前的 block。
  • before_install：{ block: true } 為終止狀態；會略過較低優先順序的 handlers。
  • before_install：{ block: false } 為無操作，且不會清除先前的 block。
  • message_sending：{ cancel: true } 為終止狀態；會略過較低優先順序的 handlers。
  • message_sending：{ cancel: false } 為無操作，且不會清除先前的 cancel。
Codex 原生 app-server 會執行橋接，將 Codex 原生工具事件帶回這個 hook 介面。Plugin 可以透過 before_tool_call 封鎖 Codex 原生工具、 透過 after_tool_call 觀察結果，並參與 Codex PermissionRequest 核准。此橋接尚不會改寫 Codex 原生工具 引數。確切的 Codex runtime 支援邊界位於 Codex harness v1 支援合約。 如需完整的 typed hook 行為，請參閱 SDK 概覽。

​
相關