清单模型字段

描述提供程序插件公开的模型的清单字段：它声明的速记 ID、目录行核心可以在运行时加载、模型 ID 清理和托管定价策略之前读取。 插件清单参考的一部分； 顶级字段引用 列出了每个字段。

modelSupport 参考

当 OpenClaw 应在插件运行时加载之前从速记模型 ID（例如 gpt-6-astra 或 claude-sonnet-4.6）推断您的提供程序插件时，请使用 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": {    "modelsDev": {      "openai": "openai"    },    "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"    }  }}

顶级字段：

发布托管目录时，modelsDev 选择自有提供商参与 models.dev 元数据水合作用。每个 OpenClaw 提供程序声明一次上游提供程序，而不是每个模型一次。省略表示没有models.dev水合作用；没有中央提供商后备。当 OpenClaw 提供者 ID 和源 ID 被修剪时，密钥将被标准化。空或非字符串源 ID 以及无主提供者的映射将被忽略；单独的别名并不授予所有权。映射不会创建目录提供程序行或放松其验证。

Hydration 添加符合条件的模型 ID，并仅填充未定义的元数据。显式清单值仍然具有权威性，包括 false； models.dev 从不提供运输设置或价格。价格仍然遵循提供商拥有的定价政策。仅当提供程序默认值适合新导入的行时才选择加入；为每个模型选择传输的提供商不应选择加入，除非这些默认设置是安全的。如果 models.dev 无法访问或其响应格式错误，则发布失败并且上次发布的工件保持不变。如果仅映射的上游提供程序丢失或格式错误，则该提供程序将发布其清单行而不进行水合作用，并且运行会记录一条警告并命名它；其他提供商仍在更新。当 models.dev 重命名提供程序时，使每个映射保持最新。即使没有 --pricing，发布者也会水合选择加入的元数据；该标志仅控制价格丰富。试运行执行相同的元数据水合作用，而不写入工件。

该字段是发布时创作元数据，而不是网关发现挂钩。它不添加运行时网络调用或热重载；现有的 托管目录更新生命周期 不变。

aliases 参与模型目录规划的提供商所有权查找。别名目标必须是同一插件拥有的顶级提供程序。当提供程序过滤的列表使用别名时，OpenClaw 可以读取所属清单并应用别名 API/base URL 覆盖，而无需加载提供程序运行时。别名不会扩展未过滤的目录列表；宽列表仅发出拥有的主要提供者行。

suppressions 替代了旧的 provider 运行时 suppressBuiltInModel 钩子。只有当 provider 归该插件拥有，或者被声明为指向已拥有 provider 的 modelCatalog.aliases 键时，抑制项才会生效。模型解析期间不再调用运行时抑制钩子。

提供方字段：

清单不提出建议。目录 v2 从 精选推荐模型列表 中派生出每个提供商的 recommendedModels。仍将 recommendedModels 负载设置不变的清单；该字段被忽略。

目录生成器选择使用 --out <v1-file> --out-v2 <v2-file> 进行本地配对输出。它会验证两个包并在替换任一输出之前准备候选字节和先前文件备份。配对的目标必须解析为不同的常规文件或不存在的目标。输出符号链接和目录别名在准备之前解析；发布替换其真正父级中的每个目标，并保持输出符号链接完好无损。如果目标父级存在，则悬空输出符号链接会创建其目标。在替换任一输出之前，缺少目标父级和符号链接循环会失败。仅 v1 的编写器未更改。

每个文件都单独替换：这是 not 多文件原子事务。使用单个发布者，并且在命令成功之前不要提供或部署该对。如果发布失败或过程在替换之间停止，请检查两个输出旁边的 .catalog-pair-* 目录。每个包含 next.json、previous.json（当输出存在时）以及 RECOVERY.txt 映射目标和恢复目录。停止竞争编写器，将当前输出与这些工件进行比较，并在重试之前显式恢复或完成该对。没有自动回滚或重播可以覆盖其他编写者的替换。不支持并发发布者和私人恢复文件的替换；该协议不保证断电耐久性。成功发布后，清理失败会发出保留路径警告，但不会将该对报告为未发布。

Model 字段：

抑制字段：

仅根据肯定的提供者证据来声明停用，而绝不能根据失败或空的发现请求来声明停用。范围帐户路由报废为 when.baseUrlHosts；匹配这些规则需要一个具体的选定端点，并且保持同级端点不变。无条件退休规则不需要凭证。格式错误或空的退休范围会被忽略，而不是成为全局规则。运行时阻止退休的路由，而 openclaw doctor --fix 拥有持久替换或覆盖删除。普通抑制和模型行的 deprecated 列表状态不授权报废修复。清单更改在网关重新启动或所属元数据重新加载后生效。

upstreamModel 将提供相同上游模型的行标记为另一个捆绑目录中具有不同名称的行，例如供应商的 API 端点旁边的订阅端点。它正在编写元数据：规范化会删除它，合同测试使用它来防止 compat.codeMode 等功能标志在发布相同模型的目录之间漂移。大多数行不需要标记，因为匹配会忽略领先的供应商命名空间和大小写：moonshotai/kimi-k3 和 zai-org/GLM-5.2 已与第一方 kimi-k3 和 glm-5.2 行匹配。仅当供应商自己的名称确实不同时，才可获取 upstreamModel。参见代码模式。

不要将仅运行时数据放入 modelCatalog。仅当清单行足够完整以供提供者筛选的列表和选择器表面跳过 registry/runtime 发现时，才使用 static。当清单行是有用的可列出种子或补充但 refresh/cache 可以稍后添加更多行时，请使用 refreshable；可刷新的行本身并不具有权威性。当 OpenClaw 必须加载提供程序运行时才能了解列表时，请使用 runtime。

提供者获得凭据后，列表和选择器表面会显示其声明的清单行，而在每种发现模式下，帐户发现仍处于待定状态。一旦该提供商的发现发布，其帐户结果就会取代它们。

目录刷新计划将手动根声明与生成的提供者清单分开。拥有同一提供商 ID 的插件不会将手动模型转换为一次性缓存数据。合并模式保留这些声明和仅授权记录；显式替换模式保留其替换合同。生成的目录仍然遵循当前所有权、端点资格和权威替换规则。

使用 activation.onStartup: false 的插件生成的缓存读取需要对该目录中至少一个当前拥有的、符合端点资格的提供程序进行当前身份验证。运行时读取器使用捕获的身份验证或提供程序配置中的可用密钥；保留的目录无法验证自身。显式创作的行保持独立。此成员资格规则不会删除存储的数据或授予请求权限。

功能属于声明的 API 和基础 URL，而不仅仅是 provider/model id。当模型列表丰富缓存行时，它仅将清单功能用于匹配的路由；自定义端点必须提供自己的限制和功能。

modelIdNormalization 参考

使用 modelIdNormalization 进行廉价的提供者拥有的模型 ID 清理，该清理必须在提供者运行时加载之前进行。这会将别名（例如短模型名称、提供者本地旧 ID 和代理前缀规则）保留在所属插件清单中，而不是保留在核心模型选择表中。

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

提供方字段：

modelPricing 参考

当托管目录发布者需要提供方特定的定价键行为时，请使用 modelPricing。发布者读取此元数据时无需导入提供方运行时代码。

{  "providers": ["ollama", "openrouter"],  "modelPricing": {    "providers": {      "ollama": {        "external": false      },      "openrouter": {        "openRouter": {          "provider": "openrouter"        },        "modelsDev": false,        "liteLLM": false      }    }  }}

提供方字段：

来源字段：

价格来自于为请求开具账单的人。声明的提供者策略仅启用其声明的源映射。如果没有策略，发布将尝试提供者的 models.dev 条目，然后是 LiteLLM。 models.dev 条目是由 modelCatalog.modelsDev 或 modelsDev.provider 命名的条目，否则为 OpenClaw 提供者 ID。 OpenRouter 的 Feed 描述了 OpenRouter 的账单，包括其促销活动，因此它仅对 OpenRouter 航线进行定价。

具有 passthroughProviderModel 的网关在清单命名时首先使用自己的价格表，例如 kilo 或 vercel models.dev 条目。如果没有命名列表，网关将按供应商的费率计费：供应商自己的目录行，然后是供应商的独立价格。

每个选定的价格都是一个完整的时间表：基本费率和上下文层永远不会跨来源组合。支持 OpenRouter 的本机提示长度覆盖；基于时间的覆盖不表示为静态上下文层。

对于权威的本机源映射，请使用：

{  "providers": ["opencode", "venice"],  "modelPricing": {    "providers": {      "opencode": { "openCode": { "provider": "opencode" } },      "venice": { "venice": { "provider": "venice" } }    }  }}

仅当声明其源时，发布者才在没有凭据的情况下获取固定的公共端点，并且仅在显式映射的所有者命名空间中发布本机价格。 Cerebras、Chutes 和 DeepInfra 使用相同的形状及其各自的源 ID 和提供商 ID。轻量级插件拥有的 pricing-api.ts 工件与运行时发现共享有效负载解析，而无需导入提供程序运行时。

DeepInfra 的顶级数组使用 model_name 标识。其数字折扣和缓存输入比率适用于每个代币的原生美分价格。定价散文、非空表、计划的到期时间和未记录的通用缓存写入速率均经过验证，但作为不受支持的计划而被忽略。 Priority/flex 和显式缓存保留乘数不会改变标准成本。它的代理投影继续拥有运行时元数据；定价源不会发现聊天模型。

选择加入的本地来源拥有完整的提供商时间表，包括缺失的价格：通用来源无法填补其空白。捆绑模型的成功且无价格的提要会保留该模型的元数据，忽略其成本，并发出发布警告。缺少定价并不能证明该模型已退役或免费使用。明确的本地零价格仍然是未知的估计。获取失败、响应机构或声明价格格式错误以及没有可用价格的提要会停止发布，从而使之前托管的目录保持完整。显式运营商费率保持不变。此创作元数据不添加任何操作员设置，并且不会更改网关的现有刷新和重新启动生命周期。

OpenClaw 提供方索引

编制的 OpenClaw 提供商指数已停用。模型元数据来自插件清单、提供商拥有的发现和托管模型目录，并通过模型解析应用配置的覆盖。有关目录源和刷新行为，请参阅 模型列表。

提供程序设置使用已安装的清单元数据和官方外部插件目录。外部目录为未安装的插件提供安装提示和授权选择标签；安装的插件所有者优先。安装提示保留在 package.json#openclaw.install 中，而不是单独编译的提供程序索引中。

openclaw doctor --fix 会将一小组封闭的旧版顶层清单能力键迁移到 contracts.* 中：speechProviders、mediaUnderstandingProviders、imageGenerationProviders 和 tools。这些内容（以及任何其他能力列表）不再作为顶层清单字段读取；正常的清单加载只会在 contracts 下识别它们。