設定 OpenClaw 外掛清單：建立 openclaw.plugin.json 指南

這檔案的作用

openclaw.plugin.json 是 OpenClaw 在載入你的 plugin 程式碼之前會讀取的 metadata。

你可以用它來處理：

plugin 身分識別
config 驗證
不需要啟動 plugin runtime 就能使用的 auth 和 onboarding metadata
在 plugin runtime 載入前就應該解析的 alias 和自動啟用 metadata
在 runtime 載入前就能自動啟用 plugin 的簡寫型 model-family 所有權 metadata
用於 bundled compat 串接和合約覆蓋的靜態 capability 所有權快照
不需要載入 runtime 就能合併到 catalog 和驗證介面的 channel 特定 config metadata
config UI 提示

不要用它來處理：

註冊 runtime 行為
宣告程式碼進入點
npm install metadata

這些內容應該放在你的 plugin 程式碼和 package.json 中。

最小範例

{
  "id": "voice-call",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

完整範例

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "cliBackends": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["OPENROUTER_API_KEY"]
  },
  "providerAuthAliases": {
    "openrouter-coding": "openrouter"
  },
  "channelEnvVars": {
    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "OpenRouter API key",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "OpenRouter API key",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

頂層欄位參考

欄位	必填	類型	含義
`id`	是	`string`	規範的 plugin id。這是在 `plugins.entries.<id>` 中使用的 id。
`configSchema`	是	`object`	此 plugin config 的內嵌 JSON Schema。
`enabledByDefault`	否	`true`	將 bundled plugin 標記為預設啟用。省略此項或設置為非 `true` 的值，則預設為停用。
`legacyPluginIds`	否	`string[]`	會正規化為此規範 plugin id 的舊版 id。
`autoEnableWhenConfiguredProviders`	否	`string[]`	當 auth、config 或 model 引用提到這些 provider id 時，應自動啟用此 plugin。
`kind`	否	`"memory"` \| `"context-engine"`	宣告 `plugins.slots.*` 使用的專屬 plugin 類型。
`channels`	否	`string[]`	此 plugin 擁有的 channel id。用於探索和 config 驗證。
`providers`	否	`string[]`	此 plugin 擁有的 provider id。
`modelSupport`	否	`object`	manifest 所有的簡寫 model-family metadata，用於在 runtime 之前自動載入 plugin。
`cliBackends`	否	`string[]`	此 plugin 擁有的 CLI inference backend id。用於從明確的 config 引用中啟動自動啟用。
`commandAliases`	否	`object[]`	此 plugin 擁有的指令名稱，應在 runtime 載入前產生 plugin 感知的 config 和 CLI 診斷。
`providerAuthEnvVars`	否	`Record<string, string[]>`	OpenClaw 無需載入 plugin 程式碼即可檢查的輕量級 provider-auth 環境變數 metadata。
`providerAuthAliases`	否	`Record<string, string>`	應重複使用另一個 provider id 進行 auth 查找的 provider id，例如與基礎 provider 共用 API key 和 auth profile 的 coding provider。
`channelEnvVars`	否	`Record<string, string[]>`	OpenClaw 無需載入 plugin 程式碼即可檢查的輕量級 channel 環境變數 metadata。用於環境驅動的 channel 設置或通用啟動/config 輔助程式應看到的 auth 介面。
`providerAuthChoices`	否	`object[]`	用於 onboarding 選擇器、偏好 provider 解析和簡單 CLI flag 串接的輕量級 auth-choice metadata。
`contracts`	否	`object`	語音、即時轉錄、即時語音、媒體理解、圖像生成、音樂生成、影片生成、web-fetch、網頁搜尋和 tool 所有權的靜態 bundled capability 快照。
`channelConfigs`	否	`Record<string, object>`	在 runtime 載入前合併到探索和驗證介面的 manifest 所有 channel config metadata。
`skills`	否	`string[]`	要載入的 skill 目錄，相對於 plugin 根目錄。
`name`	否	`string`	易於閱讀的 plugin 名稱。
`description`	否	`string`	在 plugin 介面中顯示的簡短摘要。
`version`	否	`string`	資訊性的 plugin 版本。
`uiHints`	否	`Record<string, object>`	config 欄位的 UI 標籤、佔位符和敏感度提示。

providerAuthChoices 參考

每個 providerAuthChoices 項目都描述了一個 onboarding 或驗證選項。OpenClaw 會在載入 provider runtime 之前先讀取這些資訊。

欄位	必填	類型	意義
`provider`	是	`string`	此選項所屬的 provider ID。
`method`	是	`string`	要分發到的驗證方法 ID。
`choiceId`	是	`string`	用於 onboarding 和 CLI 流程的固定驗證選項 ID。
`choiceLabel`	否	`string`	使用者看到的標籤。如果省略，OpenClaw 會退而使用 `choiceId`。
`choiceHint`	否	`string`	選擇器中的簡短輔助文字。
`assistantPriority`	否	`number`	較低的值會在助理引導的互動式選擇器中排在前面。
`assistantVisibility`	否	`"visible"` \| `"manual-only"`	在助理選擇器中隱藏該選項，但仍允許手動透過 CLI 選擇。
`deprecatedChoiceIds`	否	`string[]`	舊版的選項 ID，會將使用者重新導向至此替代選項。
`groupId`	否	`string`	用於將相關選項分組的可選群組 ID。
`groupLabel`	否	`string`	該群組的使用者標籤。
`groupHint`	否	`string`	該群組的簡短輔助文字。
`optionKey`	否	`string`	用於簡單單一 flag 驗證流程的內部選項 key。
`cliFlag`	否	`string`	CLI flag 名稱，例如 `--openrouter-api-key`。
`cliOption`	否	`string`	完整的 CLI 選項形式，例如 `--openrouter-api-key <key>`。
`cliDescription`	否	`string`	用於 CLI 說明的描述。
`onboardingScopes`	否	`Array<"text-inference" \| "image-generation">`	該選項應出現在哪些 onboarding 介面中。如果省略，預設為 `["text-inference"]`。

commandAliases 參考

當你的 plugin 擁有一個 runtime 指令名稱，而使用者可能會誤將其放入 plugins.allow 或嘗試將其作為根 CLI 指令執行時，請使用 commandAliases。OpenClaw 會使用這些元數據進行診斷，而不需要匯入 plugin 的 runtime 程式碼。

{
  "commandAliases": [
    {
      "name": "dreaming",
      "kind": "runtime-slash",
      "cliCommand": "memory"
    }
  ]
}

欄位	必填	類型	意義
`name`	是	`string`	屬於此 plugin 的指令名稱。
`kind`	否	`"runtime-slash"`	將別名標記為聊天斜線指令 (slash command)，而非根 CLI 指令。
`cliCommand`	否	`string`	相關的根 CLI 指令，用於在 CLI 操作時提供建議（如果存在的話）。

uiHints 參考

uiHints 是一個從設定欄位名稱到小型渲染提示的映射表。

{
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "help": "Used for OpenRouter requests",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}

每個欄位提示可以包含：

欄位	類型	意義
`label`	`string`	使用者看到的欄位標籤。
`help`	`string`	簡短的輔助文字。
`tags`	`string[]`	可選的 UI 標籤。
`advanced`	`boolean`	將欄位標記為進階。
`sensitive`	`boolean`	將欄位標記為機密或敏感資訊。
`placeholder`	`string`	表單輸入框的佔位文字。

contracts 參考

僅在 OpenClaw 需要在不匯入 plugin runtime 的情況下，讀取靜態功能所有權元數據時，才使用 contracts。

{
  "contracts": {
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

每個列表都是可選的：

欄位	類型	意義
`speechProviders`	`string[]`	此 plugin 擁有的語音 provider ID。
`realtimeTranscriptionProviders`	`string[]`	此 plugin 擁有的即時逐字稿 provider ID。
`realtimeVoiceProviders`	`string[]`	此 plugin 擁有的即時語音 provider ID。
`mediaUnderstandingProviders`	`string[]`	此 plugin 擁有的多媒體理解 provider ID。
`imageGenerationProviders`	`string[]`	此 plugin 擁有的圖片生成 provider ID。
`videoGenerationProviders`	`string[]`	此 plugin 擁有的影片生成 provider ID。
`webFetchProviders`	`string[]`	此 plugin 擁有的網頁擷取 provider ID。
`webSearchProviders`	`string[]`	此 plugin 擁有的網頁搜尋 provider ID。
`tools`	`string[]`	此 plugin 擁有的 Agent 工具名稱，用於綑綁合約檢查。

channelConfigs 參考

當 channel plugin 在 runtime 載入前需要輕量化的設定元資料（metadata）時，請使用 channelConfigs。

{
  "channelConfigs": {
    "matrix": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "homeserverUrl": { "type": "string" }
        }
      },
      "uiHints": {
        "homeserverUrl": {
          "label": "Homeserver URL",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Matrix homeserver connection",
      "preferOver": ["matrix-legacy"]
    }
  }
}

每個 channel 項目可以包含：

欄位	類型	說明
`schema`	`object`	`channels.<id>` 的 JSON Schema。每個宣告的 channel 設定項目都必須填寫。
`uiHints`	`Record<string, object>`	該 channel 設定區塊的選用 UI 標籤、佔位符（placeholder）或敏感資訊提示。
`label`	`string`	當 runtime 元資料尚未就緒時，合併到選擇器和檢查介面的 channel 標籤。
`description`	`string`	用於檢查和目錄介面的簡短 channel 描述。
`preferOver`	`string[]`	在選擇介面中，此 channel 應優先於哪些舊版或低優先順序的 plugin ID。

modelSupport 參考

當你希望 OpenClaw 在 plugin runtime 載入前，能從 gpt-5.4 或 claude-sonnet-4.6 這種簡寫的 model ID 推斷出你的 provider plugin 時，請使用 modelSupport。

{
  "modelSupport": {
    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],
    "modelPatterns": ["^computer-use-preview"]
  }
}

OpenClaw 會套用以下優先順序：

明確的 provider/model 參照會使用所屬 providers 的 manifest 元資料
modelPatterns 優先於 modelPrefixes
如果一個非內建（non-bundled）plugin 和一個內建 plugin 同時匹配，則由非內建 plugin 勝出
剩餘的歧義將被忽略，直到你或設定檔指定了 provider

欄位說明：

欄位	類型	說明
`modelPrefixes`	`string[]`	與簡寫 model ID 進行 `startsWith` 匹配的字首。
`modelPatterns`	`string[]`	在移除 profile 後綴後，與簡寫 model ID 匹配的 Regex 來源。

舊版的頂層 capability key 已被棄用。請使用 openclaw doctor --fix 將 speechProviders、realtimeTranscriptionProviders、realtimeVoiceProviders、mediaUnderstandingProviders、imageGenerationProviders、videoGenerationProviders、webFetchProviders 和 webSearchProviders 移至 contracts 底下；一般的 manifest 載入程序不再將這些頂層欄位視為 capability 的所有權宣告。

Manifest 與 package.json 的區別

這兩個檔案負責不同的工作：

檔案	用途
`openclaw.plugin.json`	探索、設定驗證、auth 選擇元數據，以及必須在 plugin 程式碼執行前存在的 UI 提示
`package.json`	npm 元數據、依賴安裝，以及用於 entrypoints、安裝門檻、設定或目錄元數據的 `openclaw` 區塊

如果你不確定某個元數據（metadata）該放哪裡，請遵循這個原則：

如果 OpenClaw 必須在載入 plugin 程式碼之前就知道它，請放在 openclaw.plugin.json
如果是關於打包、進入點檔案（entry files）或 npm 安裝行為，請放在 package.json

影響探索（discovery）的 package.json 欄位

有些運行前（pre-runtime）的 plugin 元數據刻意放在 package.json 的 openclaw 區塊中，而不是 openclaw.plugin.json。

重要範例：

欄位	意義
`openclaw.extensions`	宣告原生 plugin entrypoints。
`openclaw.setupEntry`	在 onboarding 和延遲 channel 啟動期間使用的輕量級純設定 entrypoint。
`openclaw.channel`	輕量級的 channel 目錄元數據，如標籤、文件路徑、別名和選擇文案。
`openclaw.channel.configuredState`	輕量級的設定狀態檢查器元數據，可以在不載入完整 channel runtime 的情況下，回答「是否已存在純環境變數設定？」。
`openclaw.channel.persistedAuthState`	輕量級的持久化 auth 檢查器元數據，可以在不載入完整 channel runtime 的情況下，回答「是否已有任何帳號登入？」。
`openclaw.install.npmSpec` / `openclaw.install.localPath`	針對內建和外部發佈 plugin 的安裝/更新提示。
`openclaw.install.defaultChoice`	當有多個安裝來源可用時，偏好的安裝路徑。
`openclaw.install.minHostVersion`	支援的最低 OpenClaw host 版本，使用 semver 門檻如 `>=2026.3.22`。
`openclaw.install.allowInvalidConfigRecovery`	當設定無效時，允許一條狹窄的內建 plugin 重新安裝恢復路徑。
`openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`	讓純設定的 channel 介面在啟動期間先於完整的 channel plugin 載入。

openclaw.install.minHostVersion 會在安裝和 manifest 註冊表載入期間強制執行。不合法的值會被拒絕；版本較新但合法的值則會在舊版 host 上跳過該 plugin。

openclaw.install.allowInvalidConfigRecovery 的用途刻意限縮。它不會讓隨便一個壞掉的設定變得可以安裝。目前它只允許安裝流程從特定的過時內建 plugin（bundled-plugin）升級失敗中恢復，例如遺失內建 plugin 路徑，或該 plugin 有過時的 channels.<id> 項目。其他無關的設定錯誤仍會阻礙安裝，並引導操作者執行 openclaw doctor --fix。

openclaw.channel.persistedAuthState 是給小型檢查模組使用的 package 元數據：

{
  "openclaw": {
    "channel": {
      "id": "whatsapp",
      "persistedAuthState": {
        "specifier": "./auth-presence",
        "exportName": "hasAnyWhatsAppAuth"
      }
    }
  }
}

當 setup, doctor 或已設定狀態（configured-state）流程需要在完整 channel plugin 載入前，進行輕量級的 auth 探測（是非題）時，就可以使用它。目標匯出（export）應該是一個只讀取持久化狀態的小型函式；不要讓它經過完整的 channel runtime。

openclaw.channel.configuredState 對於輕量級的純環境變數（env-only）設定檢查也遵循相同的格式：

{
  "openclaw": {
    "channel": {
      "id": "telegram",
      "configuredState": {
        "specifier": "./configured-state",
        "exportName": "hasTelegramConfiguredState"
      }
    }
  }
}

當 channel 可以從環境變數或其他微小的非運行輸入（non-runtime inputs）回答設定狀態時，請使用它。如果檢查需要完整的設定解析或真正的 channel runtime，請將該邏輯保留在 plugin 的 config.hasConfiguredState hook 中。

JSON Schema 要求

每個 plugin 都必須提供 JSON Schema，即使它不接受任何設定。
空的 schema 也是可以接受的（例如：{ "type": "object", "additionalProperties": false }）。
Schema 會在讀取/寫入設定時進行驗證，而不是在運行時。

驗證行為

未知的 channels.* key 會被視為 error，除非該 channel id 已在 plugin manifest 中聲明。
plugins.entries.<id>、plugins.allow、plugins.deny 以及 plugins.slots.* 必須引用可被偵測到的 plugin id。未知的 id 會被視為 error。
如果 plugin 已安裝但 manifest 或 schema 損壞或缺失，驗證將會失敗，且 Doctor 會回報該 plugin 錯誤。
如果 plugin 設定存在但該 plugin 被停用，設定會被保留，並在 Doctor 和 logs 中顯示 warning。

請參閱 Configuration reference 以取得完整的 plugins.* schema。

注意事項

原生 OpenClaw plugins 必須提供 manifest，包含從本地檔案系統載入的情況。
Runtime 仍會單獨載入 plugin 模組；manifest 僅用於偵測與驗證。
原生 manifest 使用 JSON5 解析，因此只要最終數值仍是物件，就允許使用註釋、結尾逗號以及不加引號的 key。
manifest 載入器僅會讀取文件中記載的 manifest 欄位。請避免在此處添加自定義的頂層 key。
providerAuthEnvVars 是處理 auth 探測、環境標記驗證以及類似 provider-auth 介面的輕量化中繼資料路徑，不需要為了檢查環境變數名稱而啟動 plugin runtime。
providerAuthAliases 讓 provider 變體可以重用另一個 provider 的 auth 環境變數、auth profiles、基於設定的 auth 以及 API-key 引導流程選擇，而不需要在核心程式碼中寫死這種關係。
channelEnvVars 是處理 shell 環境備援、設定提示以及類似 channel 介面的輕量化中繼資料路徑，不需要為了檢查環境變數名稱而啟動 plugin runtime。
providerAuthChoices 是用於 auth-choice 選擇器、--auth-choice 解析、偏好 provider 映射以及在載入 provider runtime 前進行簡單引導流程 CLI flag 註冊的輕量化中繼資料路徑。關於需要執行 provider 程式碼的 runtime 精靈中繼資料，請參閱 Provider runtime hooks。
專屬的 plugin 種類是透過 plugins.slots.* 選擇的。
- kind: "memory" 由 plugins.slots.memory 選擇。
- kind: "context-engine" 由 plugins.slots.contextEngine 選擇（預設為內建的 legacy）。
當 plugin 不需要 channels、providers、cliBackends 和 skills 時，可以省略這些欄位。
如果你的 plugin 依賴原生模組，請記錄建置步驟以及任何套件管理器的允許清單要求（例如 pnpm allow-build-scripts - pnpm rebuild <package>）。

還是卡住了？

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