外掛資訊清單

本頁說明 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 會讀取套件中繼資料、宣告的 Skill 根目錄、Claude 命令根目錄、Claude settings.json 預設值、Claude LSP 預設值，以及支援的鉤子套件。

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

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

此檔案的用途

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

適用於：

• 外掛識別、設定驗證及設定 UI 提示
• 驗證、初始設定及安裝中繼資料（別名、自動啟用、供應商環境變數、驗證選項）
• 控制平面介面的啟用提示
• 模型家族簡寫的所有權
• 靜態能力所有權快照（contracts）
• 儀表板小工具的資料繫結與動作動詞
• 外掛啟用期間應存在的靜態 MCP 伺服器
• 共用 openclaw qa 主機可檢查的 QA 執行器中繼資料
• 合併至目錄及驗證介面的頻道專屬設定中繼資料

**請勿用於：**註冊原生執行階段鉤子、宣告外掛程式碼進入點或 npm 安裝中繼資料。這些項目應放在你的外掛程式碼及 package.json 中。

最小範例

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

完整範例

{  "id": "openrouter",  "name": "OpenRouter",  "description": "OpenRouter 供應商外掛",  "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"  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "OpenRouter API 金鑰",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "OpenRouter API 金鑰",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "API 金鑰",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

頂層欄位參考

MCP 伺服器參考

mcpServers 可讓原生外掛隨附 MCP 伺服器（包括 MCP App），而不需要操作人員在 openclaw.json 中重複其靜態處理程序定義：

{  "mcpServers": {    "example": {      "transport": "stdio",      "command": "node",      "args": ["./mcp-server.js"]    }  }}

OpenClaw 只會在所屬外掛啟用時納入這些伺服器。相對的 command、args、cwd 和 workingDirectory 路徑會從外掛根目錄解析。使用者設定仍具有最高優先權：mcp.servers.<name> 可以取代外掛預設值，或將 enabled: false 設為略過該伺服器。MCP App 算繪和伺服器工具呼叫仍需要一般的 MCP Apps 設定與有效的工具原則；宣告伺服器不會繞過任一邊界。

儀表板參考

dashboard 可讓已啟用的外掛向已獲授權的儀表板小工具公開現有的閘道 RPC，而不需要將外掛原則加入核心。資料繫結必須指定同一外掛透過 operator.read 註冊的方法；動作動詞必須指定其透過 operator.write 註冊的方法。若不相符，外掛會在註冊期間遭拒。

{  "dashboard": {    "dataBindings": [      {        "id": "items.list",        "method": "example.items.list",        "description": "列出範例項目。"      }    ],    "actionVerbs": [      {        "id": "refresh",        "method": "example.items.refresh",        "description": "重新整理範例項目。",        "paramShape": {          "type": "object",          "additionalProperties": false,          "properties": {            "force": { "type": "boolean" }          }        }      }    ]  }}

資訊清單 ID 的作用域僅限外掛本身。小工具授權使用 <plugin-id>.<id>，例如 example.items.list 和 example.refresh。為確保持久化授權的命名空間明確無歧義，OpenClaw 會將外掛 ID 區段中的 % 和 . 分別逸出為 %25 和 %2E；一般外掛 ID 則維持自然形式。paramShape 是選用的 JSON Schema，OpenClaw 會在叫用外掛 RPC 前將其套用至動作參數物件。

目錄參考

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"]        }      ]    }  }}

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

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

providerAuthChoices 參考資料

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

當 appGuidedDiscovery 為 true 時，相符的提供者驗證方法必須公開 appGuidedSetup.detect 與 appGuidedSetup.prepare。偵測必須是 唯讀的：不得登入、拉取模型、下載或寫入設定。準備階段會重新檢查 確切選取的模型並傳回設定提案；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 可將傳輸方式公開給共用 QA 情境，而不會 變更已註冊命令的執行器。

{  "qaRunners": [    {      "commandName": "matrix",      "description": "對可拋棄式家用伺服器執行由 Docker 支援的 Matrix 即時 QA 流程"    }  ]}

adapterFactory ID 必須與 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 本機認證資訊"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

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

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

OpenClaw 會將 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 用於提供者擁有的本機認證資訊標記，這些標記可在不載入執行階段程式碼的情況下驗證。這些檢查必須保持輕量且僅在本機進行：不得進行網路呼叫、不得讀取鑰匙圈或機密資訊管理員、不得執行 Shell 命令，也不得探查提供者 API。

支援的證據項目：

setup 欄位

uiHints 參考資料

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

{  "uiHints": {    "apiKey": {      "label": "API 金鑰",      "help": "用於 OpenRouter 請求",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

每個欄位提示可包含：

contracts 參考資料

僅將 contracts 用於 OpenClaw 無須匯入外掛執行階段即可讀取的靜態功能擁有權中繼資料。

{  "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 應用程式伺服器使用的擴充功能工廠。隨附的工具結果轉換應改為宣告 contracts.agentToolResultMiddleware，並使用 api.registerAgentToolResultMiddleware(...) 註冊。已安裝外掛僅可在明確啟用時使用相同的中介軟體接合面，而且僅限於其在 contracts.agentToolResultMiddleware 中宣告的執行階段。

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

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

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

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

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

工作者提供者必須在 contracts.workerProviders 中宣告每個 api.registerWorkerProvider(...) ID。核心會在呼叫 provision 前保存持久意圖；提供者會在進行外部分配前驗證其設定，使用相同操作 ID 的重複呼叫必須採用相同租約。核心也會保存該已驗證的設定快照，並透過 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": "routes.*.secret",          "expected": "string",          "ownerKind": "route"        }      ]    }  }}

每個 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 仍可載入此外掛，但在外掛執行階段執行前，冷路徑設定結構描述、設定流程及控制介面無法得知該頻道擁有的選項形態或僅供顯示的介面提示。

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 的偏好擁有者，而另一個外掛也能提供該 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"]    }  }}

對應表的鍵是整合 ID。如果省略 providerAlias，OpenClaw 會使用整合 ID 作為 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 提供者索引預覽資料列。

Provider Index 不得包含密鑰、啟用狀態、執行階段掛鉤或即時的帳號特定模型資料。其預覽目錄使用與外掛資訊清單相同的 modelCatalog 提供者資料列形式，但除非刻意與已安裝的外掛資訊清單保持一致，否則應僅限於穩定的顯示中繼資料，不應包含 api、baseUrl、定價或相容性旗標等執行階段轉接器欄位。具有即時 /models 探索功能的提供者，應透過明確的模型目錄快取路徑寫入重新整理後的資料列，而不是讓一般列表或新手引導呼叫提供者 API。

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

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.channel.cliAddOptions，請使用 Commander 的長選項語法，例如 --initial-sync-limit <n>。將 valueType: "int" 設為解析非負整數，或將 valueType: "list" 設為在外掛設定轉接器收到輸入前，依逗號、分號或換行符號分割成字串。省略 valueType，即可將已解析的 Commander 值原樣傳遞。

對於非內建外掛來源，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 成品資訊。npmSpec 則仍作為尚未移至 ClawHub 之套件的相容性備援。

精確的 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、狀態或唯讀存在性流程需要在載入完整頻道外掛前，先進行低成本的是／否驗證探測時，請使用它。持久化驗證狀態並不是已設定的頻道狀態：請勿使用此中繼資料自動啟用外掛、修復執行階段相依性，或判斷是否應載入頻道執行階段。目標匯出應是一個只讀取持久化狀態的小型函式；請勿讓它經過完整的頻道執行階段 barrel。

openclaw.channel.configuredState 支援低成本的已設定檢查。當環境變數已足夠時，請優先使用宣告式環境中繼資料：

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "env": {          "allOf": ["TELEGRAM_BOT_TOKEN"]        }      }    }  }}

當列出的每個變數都為必要時，請使用 env.allOf；只要任一個非空白變數就足夠時，請使用 env.anyOf。如果小型非執行階段檢查需要的資訊超出環境中繼資料，請依 persistedAuthState 的示範使用 specifier 加上 exportName；當 env 存在時，OpenClaw 會直接使用它而不載入該模組。如果檢查需要完整的設定解析或實際頻道執行階段，請改將該邏輯保留在外掛的 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，即使它不接受任何設定。
• 空白 schema 也可以接受（例如 { "type": "object", "additionalProperties": false }）。
• Schema 會在讀寫設定時驗證，而不是在執行階段驗證。
• 使用新的設定鍵擴充或分支內建外掛時，請同時更新該外掛的 openclaw.plugin.json configSchema。內建外掛的 schema 採嚴格模式，因此如果在使用者設定中新增 plugins.entries.<id>.config.myNewKey，但未將 myNewKey 新增至 configSchema.properties，就會在外掛執行階段載入前遭到拒絕。

Schema 擴充範例：

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

驗證行為

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

如需完整的 plugins.* schema，請參閱設定參考。

注意事項

• 原生 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 中的環境變數中繼資料僅供宣告使用。狀態、稽核、排程傳遞驗證及其他唯讀介面，在將環境變數視為已設定之前，仍會套用外掛信任與有效啟用原則。
• 如需需要提供者程式碼的執行階段精靈中繼資料，請參閱提供者執行階段掛鉤。
• 如果你的外掛依賴原生模組，請記載建置步驟及任何套件管理器允許清單要求（例如 pnpm allow-build-scripts + pnpm rebuild <package>）。

相關內容