外掛資訊清單

本頁說明原生 OpenClaw 外掛資訊清單 openclaw.plugin.json。如需瞭解相容的套件配置（Codex、Claude、Cursor），請參閱外掛套件。

相容的套件格式會改用各自的資訊清單檔案：

• Codex 套件：.codex-plugin/plugin.json
• Claude 套件：.claude-plugin/plugin.json，或不含資訊清單的預設 Claude 元件配置
• Cursor 套件：.cursor-plugin/plugin.json

OpenClaw 會自動偵測這些配置，但不會使用下方的 openclaw.plugin.json 結構描述來驗證它們。對於相容套件，若其配置符合 OpenClaw 的執行階段預期，OpenClaw 會讀取套件中繼資料、宣告的 Skills 根目錄、Claude 命令根目錄、Claude settings.json 預設值、Claude LSP 預設值，以及支援的鉤子套件。

每個原生 OpenClaw 外掛都必須在外掛根目錄中提供 openclaw.plugin.json。OpenClaw 會讀取此檔案，以便在不執行外掛程式碼的情況下驗證設定。資訊清單缺失或無效會阻止設定驗證，並視為外掛錯誤。

如需完整的外掛系統指南，請參閱外掛；如需瞭解原生功能模型與目前的外部相容性指南，請參閱功能模型。

此檔案的用途

openclaw.plugin.json 是 OpenClaw 在載入外掛程式碼之前讀取的中繼資料。其中的所有內容都必須能以足夠低的成本進行檢查，無須啟動外掛執行階段。

請將其用於：

• 外掛識別、設定驗證與設定介面提示
• 驗證、初始設定與設置中繼資料（別名、自動啟用、供應商環境變數、驗證選項）
• 控制平面介面的啟用提示
• 模型系列所有權的簡寫
• 靜態功能所有權快照（contracts）
• 共用 openclaw qa 主機可檢查的 QA 執行器中繼資料
• 合併至目錄與驗證介面的頻道專屬設定中繼資料

**請勿將其用於：**註冊執行階段行為、宣告程式碼進入點，或 npm 安裝中繼資料。這些內容應放在外掛程式碼與 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-"]  },  "modelIdNormalization": {    "providers": {      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  },  "providerEndpoints": [    {      "endpointClass": "openrouter",      "hostSuffixes": ["openrouter.ai"]    }  ],  "providerRequest": {    "providers": {      "openrouter": {        "family": "openrouter"      }    }  },  "cliBackends": ["openrouter-cli"],  "syntheticAuthRefs": ["openrouter-cli"],  "setup": {    "providers": [      {        "id": "openrouter",        "envVars": ["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"      }    }  }}

頂層欄位參考

目錄參考

catalog 為外掛瀏覽器提供選用的顯示提示。主機可以忽略這些提示。它們絕不會安裝或啟用外掛，也不會變更其執行階段行為或信任等級。

{  "catalog": {    "featured": true,    "order": 10  }}

生成提供者中繼資料參考

生成提供者中繼資料欄位描述相符 contracts.*GenerationProviders 清單中所宣告提供者的靜態驗證訊號。OpenClaw 會在提供者執行階段載入前讀取這些欄位，讓核心工具無須匯入每個提供者外掛，即可判斷生成提供者是否可用。

這些欄位僅用於成本低廉的宣告式事實。傳輸、請求轉換、權杖重新整理、憑證驗證及實際生成行為仍由外掛執行階段負責。

{  "contracts": {    "imageGenerationProviders": ["example-image"]  },  "imageGenerationProviderMetadata": {    "example-image": {      "aliases": ["example-image-oauth"],      "authProviders": ["example-image"],      "configSignals": [        {          "rootPath": "plugins.entries.example-image.config",          "overlayPath": "image",          "mode": {            "path": "mode",            "default": "local",            "allowed": ["local"]          },          "requiredAny": ["workflow", "workflowPath"],          "required": ["promptNodeId"]        }      ],      "authSignals": [        {          "provider": "example-image"        },        {          "provider": "example-image-oauth",          "providerBaseUrl": {            "provider": "example-image",            "defaultBaseUrl": "https://api.example.com/v1",            "allowedBaseUrls": ["https://api.example.com/v1"]          }        }      ]    }  }}

每個中繼資料項目支援：

每個 configSignals 項目支援：

每個 mode 防護條件支援：

每個 authSignals 項目支援：

每個 providerBaseUrl 防護條件支援：

工具中繼資料參考

toolMetadata 使用與生成提供者中繼資料相同的 configSignals 和 authSignals 結構，並以工具名稱為鍵。contracts.tools 宣告擁有權。toolMetadata 宣告低成本的可用性證據，讓 OpenClaw 不必只為了讓工具工廠傳回 null 而匯入外掛執行階段。

{  "setup": {    "providers": [      {        "id": "example",        "envVars": ["EXAMPLE_API_KEY"]      }    ]  },  "contracts": {    "tools": ["example_search"]  },  "toolMetadata": {    "example_search": {      "authSignals": [        {          "provider": "example"        }      ],      "configSignals": [        {          "rootPath": "plugins.entries.example.config",          "overlayPath": "search",          "required": ["apiKey"]        }      ]    }  }}

除上述共用的 configSignals／authSignals 欄位外，toolMetadata 項目也接受 optional（將工具標示為啟用外掛時非必要）和 replaySafe（將工具執行標示為可在模型回合未完整結束後安全重複執行）。

若工具沒有 toolMetadata，OpenClaw 會保留既有行為，並在工具合約符合政策時載入擁有該工具的外掛。對於工廠依賴驗證／設定的熱路徑工具，外掛作者應宣告 toolMetadata，而不是讓核心匯入執行階段進行詢問。

providerAuthChoices 參考

每個 providerAuthChoices 項目描述一個初始設定或驗證選項。OpenClaw 會在提供者執行階段載入前讀取此資訊。提供者設定清單會使用這些資訊清單選項、由描述元衍生的設定選項，以及安裝目錄中繼資料，而不載入提供者執行階段。

commandAliases 參考

當外掛擁有某個執行階段命令名稱，而使用者可能誤將其放入 plugins.allow，或嘗試將其作為根命令列介面命令執行時，請使用 commandAliases。OpenClaw 會使用此中繼資料進行診斷，而無須匯入外掛執行階段程式碼。

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

activation 參考

當外掛能以低成本宣告哪些控制平面事件應將其納入啟用／載入計畫時，請使用 activation。

此區塊是規劃器中繼資料，而非生命週期 API。它不會註冊執行階段行為、不會取代 register(...)，也不保證外掛程式碼已執行。啟用規劃器會使用這些欄位縮小候選外掛範圍，之後才退回使用既有的資訊清單擁有權中繼資料，例如 providers、channels、commandAliases、setup.providers、contracts.tools 與掛鉤。

優先使用已能描述擁有權的最精確中繼資料。當 providers、channels、commandAliases、設定描述元或 contracts 能表達該關係時，請使用這些欄位。對於無法以這些擁有權欄位表示的額外規劃器提示，請使用 activation。對於 claude-cli、my-cli 或 google-gemini-cli 等命令列介面執行階段別名，請使用頂層 cliBackends；activation.onAgentHarnesses 僅用於尚無擁有權欄位的嵌入式代理程式執行框架 ID。

每個外掛都應明確設定 activation.onStartup。只有在外掛必須於閘道啟動期間執行時，才將其設為 true。當外掛在啟動時不執行任何動作，且只應由更精確的觸發條件載入時，請設為 false。省略 onStartup 不再會隱含地於啟動時載入外掛；對於啟動、頻道、設定、代理程式執行框架、記憶體或其他更精確的啟用觸發條件，請使用明確的啟用中繼資料。

{  "activation": {    "onStartup": false,    "onProviders": ["openai"],    "onCommands": ["models"],    "onChannels": ["web"],    "onRoutes": ["gateway-webhook"],    "onConfigPaths": ["browser"],    "onCapabilities": ["provider", "tool"]  }}

目前的實際使用端：

• 閘道啟動規劃使用 activation.onStartup 明確指定啟動時匯入。
• 由命令觸發的命令列介面規劃會退回使用舊版 commandAliases[].cliCommand 或 commandAliases[].name。
• 代理程式執行階段啟動規劃對嵌入式執行框架使用 activation.onAgentHarnesses，對命令列介面執行階段別名使用頂層 cliBackends[]。
• 當缺少明確的頻道啟用中繼資料時，由頻道觸發的設定／頻道規劃會退回使用舊版 channels[] 擁有權。
• 啟動外掛規劃對非頻道的根設定介面使用 activation.onConfigPaths，例如內建瀏覽器外掛的 browser 區塊。
• 當缺少明確的提供者啟用中繼資料時，由提供者觸發的設定／執行階段規劃會退回使用舊版 providers[] 與頂層 cliBackends[] 擁有權。

規劃器診斷可區分明確的啟用提示與資訊清單擁有權的退回機制。例如，activation-command-hint 表示 activation.onCommands 相符，而 manifest-command-alias 則表示規劃器改用 commandAliases 擁有權。這些原因標籤用於主機診斷與測試；外掛作者應持續宣告最能描述擁有權的中繼資料。

qaRunners 參考

當外掛在共用的 openclaw qa 根命令下提供一個或多個傳輸執行器時，請使用 qaRunners。請讓此中繼資料保持輕量且靜態；外掛執行階段仍透過輕量的 runtime-api.ts 介面負責實際的命令列介面註冊，該介面會匯出相符的 qaRunnerCliRegistrations。選用的 adapterFactory 可將傳輸方式公開給共用的品質保證情境，而不變更已註冊命令的執行器。

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"    }  ]}

adapterFactory 識別碼必須與 commandName 相符。請勿匯出資訊清單中不存在之命令的註冊項目。

setup 參考

當設定與初始引導介面需要在載入執行階段前取得成本低廉、由外掛擁有的中繼資料時，請使用 setup。

{  "setup": {    "providers": [      {        "id": "openai",        "authMethods": ["api-key"],        "envVars": ["OPENAI_API_KEY"],        "authEvidence": [          {            "type": "local-file-with-env",            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",            "requiresAllEnv": ["OPENAI_PROJECT"],            "credentialMarker": "openai-local-credentials",            "source": "openai local credentials"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

頂層的 cliBackends 仍然有效，並繼續描述命令列介面的推論後端。setup.cliBackends 是控制平面／設定流程專用的設定描述項介面，這些流程應僅使用中繼資料。

若存在 setup.providers 與 setup.cliBackends，它們會是設定探索時優先採用、以描述項為先的查詢介面。如果描述項只能縮小候選外掛的範圍，而設定仍需要更豐富的設定期間執行階段掛鉤，請設定 requiresRuntime: true，並保留 setup-api 作為備援執行路徑。

OpenClaw 也會將 setup.providers[].envVars 納入通用的供應商驗證與環境變數查詢。在棄用過渡期內，仍可透過相容性轉接器支援 providerAuthEnvVars，但仍使用它的非內建外掛會收到資訊清單診斷。新外掛應將設定／狀態環境中繼資料放在 setup.providers[].envVars。

當計費或組織層級的憑證必須啟用 resolveUsageAuth，但不應成為推論憑證時，請使用 providerUsageAuthEnvVars。這些名稱會加入工作區 dotenv 封鎖、ACP 子行程移除、沙箱機密篩選，以及廣泛的機密清除。供應商執行階段仍會在 resolveUsageAuth 內讀取值並加以分類。

當沒有設定進入點，或 setup.requiresRuntime: false 宣告不需要設定執行階段時，OpenClaw 也能從 setup.providers[].authMethods 衍生簡單的設定選項。若需要自訂標籤、命令列介面旗標、初始引導範圍及助理中繼資料，仍應優先使用明確的 providerAuthChoices 項目。

只有當這些描述項足以支援設定介面時，才設定 requiresRuntime: false。OpenClaw 會將明確的 false 視為僅使用描述項的契約，且不會為設定查詢執行 setup-api 或 openclaw.setupEntry。如果僅使用描述項的外掛仍附帶上述任一設定執行階段進入點，OpenClaw 會回報附加診斷，並繼續忽略該進入點。省略 requiresRuntime 會保留舊版備援行為，因此已新增描述項但未加入此旗標的現有外掛不會中斷。

由於設定查詢可能執行外掛擁有的 setup-api 程式碼，正規化後的 setup.providers[].id 與 setup.cliBackends[] 值在所有已探索的外掛中都必須保持唯一。若擁有權不明確，系統會採取封閉式失敗，而不是依探索順序選出其中一個。

執行設定執行階段時，若 setup-api 註冊的供應商或命令列介面後端未在資訊清單描述項中宣告，或描述項沒有對應的執行階段註冊，設定登錄診斷會回報描述項偏差。這些診斷屬於附加資訊，不會拒絕舊版外掛。

setup.providers 參考

authEvidence 用於由供應商擁有、可在不載入執行階段程式碼的情況下驗證的本機憑證標記。這些檢查必須維持低成本且僅在本機執行：不得進行網路呼叫、不得讀取鑰匙圈或機密管理員、不得執行殼層命令，也不得探查供應商 API。

支援的證據項目：

setup 欄位

uiHints 參考

uiHints 是從設定欄位名稱對應至簡短轉譯提示的映射。索引鍵可以使用句點表示巢狀設定欄位，但任何路徑區段都不可為 __proto__、constructor 或 prototype；設定程序會拒絕這些名稱。

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

每個欄位提示可包含：

contracts 參考

只有在 OpenClaw 可於不匯入外掛執行階段的情況下讀取靜態能力擁有權中繼資料時，才使用 contracts。

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"],    "trustedToolPolicies": ["workflow-budget"],    "externalAuthProviders": ["acme-ai"],    "embeddingProviders": ["openai-compatible"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "musicGenerationProviders": ["stability-audio"],    "documentExtractors": ["example-docs"],    "webContentExtractors": ["firecrawl"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "workerProviders": ["example-worker"],    "usageProviders": ["acme-ai"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

每個清單皆為選用：

contracts.embeddedExtensionFactories 保留給隨附且僅限 Codex app-server 的擴充功能工廠。隨附的工具結果轉換應改為宣告 contracts.agentToolResultMiddleware，並透過 api.registerAgentToolResultMiddleware(...) 註冊。已安裝外掛僅能在明確啟用時使用相同的中介軟體介面，且只能用於其在 contracts.agentToolResultMiddleware 中宣告的執行階段。

需要主機受信任工具執行前政策層級的已安裝外掛，必須在 contracts.trustedToolPolicies 中宣告每個已註冊的本機識別碼，並且明確啟用。隨附外掛會保留現有的受信任政策路徑，但具有未宣告政策識別碼的已安裝外掛會在註冊前遭到拒絕。政策識別碼的作用域限於註冊該政策的外掛，因此兩個外掛都可以宣告並註冊 workflow-budget；但單一外掛不得重複註冊相同的本機識別碼。

執行階段的 api.registerTool(...) 註冊必須符合 contracts.tools。工具探索會使用此清單，僅載入可能擁有所要求工具的外掛執行階段。

實作 resolveExternalAuthProfiles 的供應商外掛應宣告 contracts.externalAuthProviders；未宣告的外部驗證掛鉤會被忽略。

同時實作 resolveUsageAuth 與 fetchUsageSnapshot 的供應商外掛，應在 contracts.usageProviders 中宣告每個自動探索到的供應商識別碼。用量探索會在載入執行階段程式碼前讀取此合約，接著僅載入已宣告的擁有者，並在載入後驗證兩個掛鉤。

一般嵌入供應商應為每個透過 api.registerEmbeddingProvider(...) 註冊的配接器宣告 contracts.embeddingProviders。可重複使用的向量生成應使用一般合約，包括記憶搜尋所使用的供應商。contracts.memoryEmbeddingProviders 是已棄用的記憶專用相容性機制，僅在現有供應商遷移至通用嵌入供應商介面期間保留。

工作節點供應商必須在 contracts.workerProviders 中宣告每個 api.registerWorkerProvider(...) 識別碼。核心會在呼叫 provision 前持久保存長期意圖；供應商會在進行外部配置前驗證其設定，而使用相同操作識別碼的重複呼叫必須採用相同租約。核心也會持久保存該已驗證的設定快照，並將其連同 leaseId 傳給 inspect({ leaseId, profile }) 和 destroy({ leaseId, profile })，包括在具名設定檔已變更或移除後。銷毀操作具有等冪性，檢查會傳回封閉的 active / destroyed / unknown 狀態聯集，而 SSH 私密金鑰資料只能透過 SecretRef 參照。已佈建的 SSH 端點也必須包含來自受信任佈建輸出的公開 hostKey，且格式必須恰為 algorithm base64，不得包含主機名稱或註解，以便核心在連線前固定主機金鑰。產生動態身分參照的供應商可實作具權威性的 resolveSshIdentity({ leaseId, profile, keyRef })；未實作此功能的供應商則使用核心的通用機密解析器。具權威性的 unknown 會使使用中的本機記錄成為孤立記錄；在持久保存的銷毀要求之後，它則用於確認拆除完成。

contracts.gatewayMethodDispatch 目前接受 "authenticated-request"。它是針對刻意在程序內分派閘道控制平面方法之原生外掛 HTTP 路由的 API 衛生控管，而非用來防範惡意原生外掛的沙箱。請僅將其用於已經要求閘道 HTTP 驗證，且經過嚴格審查的隨附或操作員介面。當閘道的根工作准入已關閉時，具備權限的路由只有在同時宣告 auth: "gateway" 以及路由專屬的 gatewayRuntimeScopeSurface: "trusted-operator" 時，才仍可存取；同一外掛的一般同層路由仍會受到准入邊界限制。這可讓暫停狀態與恢復功能保持可用，而不會授予整個外掛略過准入的權限。應在分派之外限制解析與回應成形的範圍；實質性或會變更狀態的工作必須透過閘道方法分派進行，由其負責准入與作用域強制執行。

configContracts 參考

對於由資訊清單擁有、且通用核心輔助程式需要在不匯入外掛執行階段的情況下使用的設定行為，請使用 configContracts：危險旗標偵測、SecretRef 遷移目標，以及舊版設定路徑的縮限。

{  "configContracts": {    "compatibilityMigrationPaths": ["legacyProvider"],    "compatibilityRuntimePaths": ["legacyProvider.webhook"],    "dangerousFlags": [      {        "path": "accounts.*.allowUnverifiedSenders",        "equals": true      }    ],    "secretInputs": {      "bundledDefaultEnabled": false,      "paths": [        {          "path": "apiKey",          "expected": "string"        }      ]    }  }}

每個 dangerousFlags 項目支援：

secretInputs 支援：

mediaUnderstandingProviderMetadata 參考

當媒體理解提供者具有預設模型、自動驗證備援優先順序，或通用核心輔助程式需要在執行階段載入前得知的原生文件支援時，請使用 mediaUnderstandingProviderMetadata。鍵也必須在 contracts.mediaUnderstandingProviders 中宣告。

{  "contracts": {    "mediaUnderstandingProviders": ["example"]  },  "mediaUnderstandingProviderMetadata": {    "example": {      "capabilities": ["image", "audio"],      "defaultModels": {        "image": "example-vision-latest",        "audio": "example-transcribe-latest"      },      "autoPriority": {        "image": 40      },      "nativeDocumentInputs": ["pdf"],      "documentModels": {        "pdf": {          "textExtraction": "example-doc-text-latest",          "image": "example-doc-vision-latest"        }      }    }  }}

每個提供者項目可包含：

channelConfigs 參考

當頻道外掛需要在執行階段載入前取得低成本的設定中繼資料時，請使用 channelConfigs。當沒有設定項目可用，或 setup.requiresRuntime: false 宣告設定不需要執行階段時，唯讀的頻道設定／狀態探索可以直接針對已設定的外部頻道使用此中繼資料。

channelConfigs 是外掛資訊清單的中繼資料，而不是新的頂層使用者設定區段。使用者仍在 channels.<channel-id> 下設定頻道執行個體。OpenClaw 會讀取資訊清單中繼資料，以便在外掛執行階段程式碼執行前，判斷哪個外掛擁有已設定的頻道。

對於頻道外掛，configSchema 和 channelConfigs 描述不同的路徑：

• configSchema 驗證 plugins.entries.<plugin-id>.config
• channelConfigs.<channel-id>.schema 驗證 channels.<channel-id>

宣告 channels[] 的非隨附外掛也應宣告相符的 channelConfigs 項目。若未宣告，OpenClaw 仍可載入外掛，但冷路徑設定結構描述、設定流程及 Control UI 介面在外掛執行階段執行前，無法得知該頻道所擁有的選項結構。

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled 和 nativeSkillsAutoEnabled 可為頻道執行階段載入前執行的命令設定檢查，宣告靜態 auto 預設值。隨附頻道也可以透過 package.json#openclaw.channel.commands 發布相同的預設值，與其他由套件擁有的頻道目錄中繼資料並列。

{  "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",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

每個頻道項目可包含：

取代另一個頻道外掛

當另一個外掛也能提供某個頻道 ID，而您的外掛是該頻道的首選擁有者時，請使用 preferOver。常見情況包括重新命名的外掛 ID、取代隨附外掛的獨立外掛，或為了設定相容性而保留相同頻道 ID 的受維護分支。

{  "id": "acme-chat",  "channels": ["chat"],  "channelConfigs": {    "chat": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "webhookUrl": { "type": "string" }        }      },      "preferOver": ["chat"]    }  }}

設定 channels.chat 時，OpenClaw 會同時考量頻道 ID 與首選外掛 ID。若較低優先順序的外掛僅因其為隨附外掛或預設啟用而獲選，OpenClaw 會在有效的執行階段設定中停用該外掛，讓單一外掛擁有該頻道及其工具。明確的使用者選擇仍具有最高優先權：若使用者明確啟用兩個外掛（透過 plugins.allow 或實質的 plugins.entries 設定），OpenClaw 會保留該選擇，並回報重複的頻道／工具診斷，而不會默默變更所要求的外掛集合。

請將 preferOver 限定於確實能提供相同頻道的外掛 ID。它不是一般用途的優先順序欄位，也不會重新命名使用者設定鍵。

modelSupport 參考

當 OpenClaw 應在外掛執行階段載入前，從 gpt-5.6-sol 或 claude-sonnet-4.6 等簡寫模型 ID 推斷您的提供者外掛時，請使用 modelSupport。

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

OpenClaw 採用以下優先順序：

• 明確的 provider/model 參照使用其擁有者的 providers 資訊清單中繼資料
• modelPatterns 優先於 modelPrefixes
• 若一個非隨附外掛與一個隨附外掛皆符合，則非隨附外掛優先
• 在使用者或設定指定提供者前，其餘歧義會被忽略

欄位：

modelPatterns 項目會透過 compileSafeRegex 編譯，該函式會拒絕包含巢狀重複的模式（例如 (a+)+$）。未通過安全檢查的模式會被默默略過，處理方式與語法無效的正規表示式相同。請保持模式簡單，並避免巢狀量詞。

modelCatalog 參考

當 OpenClaw 應在載入外掛執行階段前得知提供者模型中繼資料時，請使用 modelCatalog。這是由資訊清單擁有的固定目錄列、提供者別名、抑制規則及探索模式來源。執行階段重新整理仍由提供者執行階段程式碼負責，但資訊清單會告知核心何時需要執行階段。

{  "providers": ["openai"],  "modelCatalog": {    "providers": {      "openai": {        "baseUrl": "https://api.openai.com/v1",        "api": "openai-responses",        "models": [          {            "id": "gpt-5.4",            "name": "GPT-5.4",            "input": ["text", "image"],            "reasoning": true,            "contextWindow": 256000,            "maxTokens": 128000,            "cost": {              "input": 1.25,              "output": 10,              "cacheRead": 0.125            },            "status": "available",            "tags": ["default"]          }        ]      }    },    "aliases": {      "azure-openai-responses": {        "provider": "openai",        "api": "azure-openai-responses"      }    },    "suppressions": [      {        "provider": "azure-openai-responses",        "model": "gpt-5.3-codex-spark",        "reason": "not available on Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

頂層欄位：

aliases 會參與模型目錄規劃的供應商擁有權查找。別名目標必須是由同一外掛擁有的頂層供應商。使用別名的供應商篩選清單中，OpenClaw 無須載入供應商執行階段，即可讀取擁有該供應商的資訊清單，並套用別名的 API／基礎 URL 覆寫。別名不會展開未篩選的目錄清單；廣泛清單只會輸出擁有該供應商的標準供應商資料列。

suppressions 取代舊有的供應商執行階段 suppressBuiltInModel 鉤子。僅當供應商由此外掛擁有，或宣告為 modelCatalog.aliases 中指向所擁有供應商的鍵時，才會採用抑制項目。模型解析期間不再呼叫執行階段抑制鉤子。

供應商欄位：

模型欄位：

抑制欄位：

請勿將僅限執行階段的資料放入 modelCatalog。只有當資訊清單資料列足夠完整，使供應商篩選清單與選擇器介面可略過登錄／執行階段探索時，才使用 static。當資訊清單資料列可作為有用且可列出的種子或補充資料，但之後可透過重新整理／快取加入更多資料列時，使用 refreshable；可重新整理的資料列本身並非權威來源。當 OpenClaw 必須載入供應商執行階段才能得知清單時，使用 runtime。

modelIdNormalization 參考

針對必須在供應商執行階段載入前進行的低成本、供應商自有模型 ID 清理，使用 modelIdNormalization。這可將簡短模型名稱、供應商本機舊版 ID 和代理前綴規則等別名保留在擁有它們的外掛資訊清單中，而不是放在核心模型選擇表內。

{  "providers": ["anthropic", "openrouter"],  "modelIdNormalization": {    "providers": {      "anthropic": {        "aliases": {          "sonnet-4.6": "claude-sonnet-4-6"        }      },      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  }}

供應商欄位：

providerEndpoints 參考

對於通用要求原則必須在供應商執行階段載入前得知的端點分類，使用 providerEndpoints。核心仍負責定義各個 endpointClass 的含義；外掛資訊清單則負責主機與基礎 URL 中繼資料。

正式外部化的供應商外掛不包含在核心發行版本中，因此在安裝前無法看到其資訊清單。其 providerEndpoints 也必須鏡像至 scripts/lib/official-external-provider-catalog.json，如此即使沒有該外掛，端點分類仍可運作；合約測試會強制確保兩者一致。

端點欄位：

providerRequest 參考

當通用請求政策需要低成本的請求相容性中繼資料，且不應載入供應商執行階段時，請使用 providerRequest。特定行為的承載資料重寫應保留在供應商執行階段鉤子或共用供應商系列輔助工具中。

{  "providerRequest": {    "providers": {      "vllm": {        "family": "vllm",        "openAICompletions": {          "supportsStreamingUsage": true        }      }    }  }}

供應商欄位：

secretProviderIntegrations 參考

當外掛可發布可重複使用的 SecretRef exec 供應商預設時，請使用 secretProviderIntegrations。OpenClaw 會在外掛執行階段載入前讀取此中繼資料，將外掛擁有權儲存在 secrets.providers.<alias>.pluginIntegration，並將實際的密鑰解析交由 SecretRef 執行階段處理。只有內建外掛，以及從受管理之外掛安裝根目錄中發現的已安裝外掛（例如透過 git 和 ClawHub 安裝者），才會公開這些預設。

{  "secretProviderIntegrations": {    "secret-store": {      "providerAlias": "team-secrets",      "displayName": "Team secrets",      "source": "exec",      "command": "${node}",      "args": ["./bin/resolve-secrets.mjs"]    }  }}

映射鍵是整合識別碼。若省略 providerAlias，OpenClaw 會使用整合識別碼作為 SecretRef 供應商別名。供應商別名必須符合一般 SecretRef 供應商別名模式，例如 team-secrets 或 onepassword-work。

當操作人員選取此預設時，OpenClaw 會寫入如下的供應商參照：

{  "secrets": {    "providers": {      "team-secrets": {        "source": "exec",        "pluginIntegration": {          "pluginId": "acme-secrets",          "integrationId": "secret-store"        }      }    }  }}

啟動或重新載入時，OpenClaw 會載入目前的外掛資訊清單中繼資料、檢查擁有該供應商的外掛是否已安裝且處於啟用狀態，並依資訊清單具體化 exec 命令，以解析該供應商。停用或移除外掛會撤銷作用中 SecretRef 的該供應商。需要獨立 exec 設定的操作人員仍可直接手動撰寫包含 command/args 的供應商設定。

目前僅支援 source: "exec" 預設。command 必須是 ${node}，且 args[0] 必須是以 ./ 開頭、相對於外掛根目錄的解析器指令碼。OpenClaw 會在啟動或重新載入時，將其具體化為目前的 Node 執行檔及外掛內指令碼的絕對路徑。--require、--import、--loader、--env-file、--eval 和 --print 等 Node 選項不屬於資訊清單預設契約。需要非 Node 命令的操作人員可以直接設定獨立的手動 exec 供應商。

OpenClaw 會從外掛根目錄推導資訊清單預設的 trustedDirs；對於 ${node} 預設，也會包含目前 Node 執行檔所在目錄。資訊清單中撰寫的 trustedDirs 會被忽略。timeoutMs、noOutputTimeoutMs、maxOutputBytes、jsonOnly、env、passEnv 和 allowInsecurePath 等其他 exec 供應商選項，會直接傳遞至一般 SecretRef exec 供應商設定。

modelPricing 參考

當供應商需要在執行階段載入前控制控制平面的定價行為時，請使用 modelPricing。閘道定價快取會讀取此中繼資料，而不匯入供應商執行階段程式碼。

{  "providers": ["ollama", "openrouter"],  "modelPricing": {    "providers": {      "ollama": {        "external": false      },      "openrouter": {        "openRouter": {          "passthroughProviderModel": true        },        "liteLLM": false      }    }  }}

供應商欄位：

來源欄位：

OpenClaw 供應商索引

OpenClaw 供應商索引是由 OpenClaw 維護的預覽中繼資料，適用於外掛可能尚未安裝的供應商。它不是外掛資訊清單的一部分。外掛資訊清單仍是已安裝外掛的權威來源。供應商索引是內部後備契約；當供應商外掛尚未安裝時，未來可安裝供應商及安裝前模型選擇器介面將使用此契約。

目錄權威順序：

1. 使用者設定。
2. 已安裝外掛資訊清單的 modelCatalog。
3. 明確重新整理所產生的模型目錄快取。
4. OpenClaw 供應商索引預覽列。

供應商索引不得包含密鑰、啟用狀態、執行階段鉤子或即時帳戶專屬模型資料。其預覽目錄使用與外掛資訊清單相同的 modelCatalog 供應商列結構，但應僅限於穩定的顯示中繼資料；除非有意讓 api、baseUrl、定價或相容性旗標等執行階段配接器欄位與已安裝外掛資訊清單保持一致。具有即時 /models 探索功能的供應商，應透過明確的模型目錄快取路徑寫入重新整理後的資料列，而不是在一般列出或上線設定期間呼叫供應商 API。

對於外掛已移出核心或尚未安裝的供應商，供應商索引項目也可包含可安裝外掛的中繼資料。此中繼資料仿照頻道目錄模式：套件名稱、npm 安裝規格、預期完整性，以及低成本的驗證選項標籤，足以顯示可安裝的設定選項。外掛安裝完成後，會以其資訊清單為準，並忽略該供應商的供應商索引項目。

openclaw doctor --fix 會將一小組封閉的舊版頂層資訊清單能力鍵遷移至 contracts.*：speechProviders、mediaUnderstandingProviders、imageGenerationProviders 和 tools。這些鍵（或任何其他能力清單）都不再以頂層資訊清單欄位形式讀取；一般資訊清單載入只會辨識 contracts 下的這些欄位。

資訊清單與 package.json 的比較

這兩個檔案各有不同用途：

如果不確定某項中繼資料應放在哪裡，請使用以下規則：

• 如果 OpenClaw 必須在載入外掛程式碼前得知該資訊，請將其放入 openclaw.plugin.json
• 如果該資訊與封裝、進入檔案或 npm 安裝行為有關，請將其放入 package.json

影響探索的 package.json 欄位

部分執行階段前的外掛中繼資料會刻意放在 package.json 的 openclaw 區塊下，而不是 openclaw.plugin.json 中。openclaw.bundle 和 openclaw.bundle.json 不是 OpenClaw 外掛契約；原生外掛必須使用 openclaw.plugin.json，以及下方支援的 package.json#openclaw 欄位。

重要範例：

資訊清單中繼資料決定執行階段載入前，初始設定中會顯示哪些供應商／頻道／設定選項。package.json#openclaw.install 會告訴初始設定流程，當使用者選擇其中一個選項時，該如何擷取或啟用此外掛。請勿將安裝提示移至 openclaw.plugin.json。

對非內建外掛來源，安裝及載入資訊清單登錄檔時會強制執行 openclaw.install.minHostVersion。無效值會遭拒；有效但較新的值，會使較舊主機略過外部外掛。內建來源外掛視為與主機簽出版本一致。

openclaw.install.requiredPlatformPackages 適用於透過選用、平台專屬別名提供必要原生二進位檔的 npm 套件。請為每個支援的平台別名列出不含版本限定的 npm 套件名稱。npm 安裝期間，OpenClaw 只會驗證鎖定檔限制符合目前主機的已宣告別名。若 npm 回報成功卻省略該別名，OpenClaw 會使用全新快取重試一次；若該別名仍缺失，則回復安裝。

對非內建外掛來源，套件安裝期間會強制執行 openclaw.compat.pluginApi。請用它指定套件建置時所依據的 OpenClaw 外掛 SDK／執行階段 API 下限。當外掛套件需要較新的 API，但仍刻意保留較低的安裝提示供其他流程使用時，它可以比 minHostVersion 更嚴格。依預設，OpenClaw 官方版本同步會將現有官方外掛的 API 下限提升至該 OpenClaw 發行版本；但若套件有意支援較舊主機，僅發布外掛的版本可以保留較低下限。請勿只使用套件版本作為相容性契約。peerDependencies.openclaw 仍是 npm 套件中繼資料；OpenClaw 會使用 openclaw.compat.pluginApi 契約進行安裝相容性判斷。

若外掛已發布至 ClawHub，官方隨選安裝中繼資料應使用 clawhubSpec；初始設定會將其視為偏好的遠端來源，並在安裝後記錄 ClawHub 成品資訊。對於尚未移至 ClawHub 的套件，npmSpec 仍作為相容性備援。

確切的 npm 版本固定已位於 npmSpec 中，例如 "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"。官方外部目錄項目應將確切規格與 expectedIntegrity 配對，確保所擷取的 npm 成品不再符合固定版本時，更新流程會以封閉方式失敗。為了相容性，互動式初始設定仍會提供受信任登錄檔的 npm 規格，包括不含版本限定的套件名稱與 dist-tag。目錄診斷可區分確切、浮動、已固定完整性、缺少完整性、套件名稱不符，以及無效預設選項等來源。當存在 expectedIntegrity，卻沒有可供其固定的有效 npm 來源時，也會發出警告。若存在 expectedIntegrity，安裝／更新流程會強制驗證；若省略，則會記錄登錄檔解析結果，但不固定完整性。

當狀態、頻道清單或 SecretRef 掃描需要在不載入完整執行階段的情況下識別已設定的帳號時，頻道外掛應提供 openclaw.setupEntry。設定進入點應公開頻道中繼資料，以及設定安全的組態、狀態和密鑰配接器；網路用戶端、閘道監聽器和傳輸執行階段則應保留在主要擴充功能進入點中。

執行階段進入點欄位不會覆寫來源進入點欄位的套件邊界檢查。例如，openclaw.runtimeExtensions 無法讓逸出套件目錄的 openclaw.extensions 路徑變成可載入。

openclaw.install.allowInvalidConfigRecovery 的適用範圍刻意受到嚴格限制。它不會讓任意損壞的設定變得可安裝。目前，它只允許安裝流程從特定的過時內建外掛升級失敗中復原，例如缺少內建外掛路徑，或同一內建外掛存在過時的 channels.<id> 項目。不相關的設定錯誤仍會阻止安裝，並指示操作者執行 openclaw doctor --fix。

openclaw.channel.persistedAuthState 是供小型檢查器模組使用的套件中繼資料：

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

當設定、Doctor、狀態或唯讀存在性流程需要在完整頻道外掛載入前，以低成本探測驗證狀態的是／否結果時，請使用此中繼資料。持久化驗證狀態並不是已設定的頻道狀態：請勿使用此中繼資料自動啟用外掛、修復執行階段相依性，或判斷是否應載入頻道執行階段。目標匯出應是只讀取持久化狀態的小型函式；請勿透過完整頻道執行階段的彙總匯出檔來路由它。

openclaw.channel.configuredState 使用相同的結構，供低成本的僅環境變數已設定檢查使用：

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

當頻道可以從環境變數或其他極小型的非執行階段輸入判斷已設定狀態時，請使用此中繼資料。若檢查需要完整設定解析或真正的頻道執行階段，則將該邏輯保留在外掛的 config.hasConfiguredState 掛鉤中。

探索優先順序（重複的外掛 ID）

OpenClaw 會從三個根目錄探索外掛，依序檢查：隨 OpenClaw 提供的內建外掛、全域安裝根目錄（~/.openclaw/extensions）及目前工作區根目錄（<workspace>/.openclaw/extensions），再加上任何明確的 plugins.load.paths 項目。

若兩個探索結果具有相同的 id，只會保留優先順序最高的資訊清單；優先順序較低的重複項目會被捨棄，而不會並列載入。優先順序由高至低如下：

1. 設定選定 — 在 plugins.entries.<id> 中明確固定的路徑
2. 符合追蹤安裝記錄的全域安裝 — 透過 openclaw plugin install／openclaw plugin update 安裝，且 OpenClaw 的安裝追蹤識別為相同 ID 的外掛，即使該 ID 也屬於內建外掛
3. 內建 — 隨 OpenClaw 提供的外掛
4. 工作區 — 相對於目前工作區探索到的外掛
5. 任何其他探索到的候選項目

影響如下：

• 放置在工作區或全域根目錄中、未受追蹤的內建外掛分支版本或過時副本，不會遮蔽內建版本。
• 若要覆寫內建外掛，可針對該 ID 執行 openclaw plugin install，使受追蹤的全域安裝優先於內建副本；或透過 plugins.entries.<id> 固定特定路徑，使其憑藉設定選定的優先順序勝出。
• 系統會記錄遭捨棄的重複項目，讓 Doctor 和啟動診斷可以指出被捨棄的副本。
• 診斷會將設定選定的重複覆寫描述為明確覆寫，但仍會發出警告，讓過時分支版本和意外遮蔽保持可見。

JSON Schema 要求

• 每個外掛都必須隨附 JSON Schema，即使它不接受任何設定也一樣。
• 空結構描述亦可接受（例如 { "type": "object", "additionalProperties": false }）。
• 結構描述會在讀取／寫入設定時進行驗證，而非在執行階段驗證。
• 使用新的設定鍵擴充或分支修改內建外掛時，請同時更新該外掛 openclaw.plugin.json 中的 configSchema。內建外掛的結構描述採嚴格模式，因此若在使用者設定中新增 plugins.entries.<id>.config.myNewKey，卻未將 myNewKey 加入 configSchema.properties，系統會在載入外掛執行階段之前拒絕該設定。

結構描述擴充範例：

{  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "myNewKey": {        "type": "string"      }    }  }}

驗證行為

• 未知的 channels.* 鍵會視為錯誤，除非外掛資訊清單已宣告該頻道 ID。如果相同 ID 也出現在 plugins.allow、plugins.entries 或 plugins.installs 中（亦即該外掛已被參照，但目前無法探索），OpenClaw 會改將其降級為警告。
• plugins.entries.<id>、plugins.allow 和 plugins.deny 若參照未知的外掛 ID，會產生警告（「已忽略過時的設定項目」），而非錯誤，因此升級及已移除／重新命名的外掛不會阻止閘道啟動。
• plugins.slots.memory 若參照未知的外掛 ID，會視為錯誤；但已知的官方外部外掛 memory-lancedb 除外，此時只會發出警告。
• 如果外掛已安裝，但其資訊清單或結構描述損壞或遺失，驗證將失敗，Doctor 也會回報此外掛錯誤。
• 如果外掛設定存在，但該外掛已停用，系統會保留設定，並在 Doctor 與日誌中顯示警告。

如需完整的 plugins.* 結構描述，請參閱設定參考。

注意事項

• 原生 OpenClaw 外掛必須提供資訊清單，包括從本機檔案系統載入的外掛。執行階段仍會另外載入外掛模組；資訊清單僅用於探索與驗證。
• 原生資訊清單使用 JSON5 解析，因此只要最終值仍為物件，即可使用註解、尾隨逗號及未加引號的鍵。
• 資訊清單載入器只會讀取已記載的資訊清單欄位。請避免使用自訂的頂層鍵。
• 外掛不需要相關功能時，可以省略 channels、providers、cliBackends 和 skills。
• providerCatalogEntry 必須保持輕量，不應匯入大範圍的執行階段程式碼；請將其用於靜態提供者目錄中繼資料或範圍明確的探索描述項，而非請求期間的執行。
• 互斥外掛類型透過 plugins.slots.* 選取：kind: "memory" 使用 plugins.slots.memory（預設為 memory-core），kind: "context-engine" 使用 plugins.slots.contextEngine（預設為 legacy）。
• 請在此資訊清單中宣告互斥外掛類型。執行階段進入點的 OpenClawPluginDefinition.kind 已淘汰，僅保留作為舊版外掛的相容性後備機制。
• 環境變數中繼資料（setup.providers[].envVars、已淘汰的 providerAuthEnvVars，以及 channelEnvVars）僅具宣告用途。狀態、稽核、排程傳遞驗證及其他唯讀介面，在將環境變數視為已設定之前，仍會套用外掛信任與實際啟用原則。
• 如需必須使用提供者程式碼的執行階段精靈中繼資料，請參閱提供者執行階段掛鉤。
• 如果外掛依賴原生模組，請記載建置步驟及套件管理器允許清單的任何要求（例如 pnpm 的 allow-build-scripts 與 pnpm rebuild <package>）。

相關內容