模型字段

描述提供商插件所暴露模型的清单字段：它声明了哪些简写 id、核心在运行时加载前可以读取的目录行、model-id 清理以及托管定价策略。属于 插件清单 参考的一部分；顶层字段参考 列出了所有字段。

modelSupport 参考¶

当 OpenClaw 需要在插件运行时加载之前，根据 gpt-6-astra 或 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": {
    "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，以及针对非所属提供商的映射会被忽略；仅别名不会授予所有权。映射不会创建目录提供商行，也不会放宽其验证。

填充会添加符合条件的模型 id，并只填充未定义的元数据。显式清单值仍具有权威性，包括 false；models.dev 从不提供传输设置或价格。价格仍遵循提供商拥有的定价策略。仅当提供商默认值适合新导入的行时才启用；按模型选择传输的提供商不应启用，除非这些默认值是安全的。如果 models.dev 不可达或其响应格式错误，发布将失败，且最后发布的产物保持完整。如果仅映射的上游提供商缺失或格式错误，则该提供商会发布其清单行而不进行填充，运行会记录一条指明该提供商的警告；其他提供商仍会更新。当 models.dev 重命名提供商时，请保持每个映射为最新。即使没有 --pricing，发布者也会填充已启用的元数据；该标志仅控制价格增强。试运行会执行相同的元数据填充，而不写入产物。

此字段是发布时的作者元数据，而不是 Gateway 发现钩子。它不会增加运行时网络调用或热重载；现有的 托管目录更新生命周期 保持不变。

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

suppressions 取代了旧的提供方运行时 suppressBuiltInModel 钩子。仅当提供方由插件拥有，或被声明为指向已拥有提供方的 modelCatalog.aliases 键时，抑制条目才会生效。模型解析期间不再调用运行时抑制钩子。

提供方字段：

recommendedModels 是此提供方 models 中不同模型 id 的可选有序短列表。id 会被修剪且必须非空。该字段保留用于选择器排序，目前尚未使用。它仅在目录 v2 中发布，绝不发布到 v1。无效的清单列表会被省略；无效的远程 v2 列表会被拒绝。

目录生成器通过 --out <v1-file> --out-v2 <v2-file> 选择本地成对输出。 它会验证两个包，并在替换任一输出之前准备候选字节和先前文件备份。成对目标必须解析为不同的常规文件或不存在的目标。输出符号链接和目录别名会在准备之前解析；发布会在真实父目录中替换每个目标，并保持输出符号链接不变。悬空的输出符号链接会在目标父目录存在时创建其目标。缺失的目标父目录和符号链接循环会在任一输出被替换之前导致失败。仅 v1 写入器保持不变。

每个文件分别替换：这不是多文件原子事务。 使用单一发布者，并在命令成功之前不要提供或部署该对文件。 如果发布失败或进程在替换之间停止，请检查两个输出旁边的 .catalog-pair-* 目录。每个目录包含 next.json、 如果输出曾存在则包含 previous.json，以及 RECOVERY.txt，其中映射了两个目标和恢复目录。停止竞争写入器，将当前输出与 这些工件进行比较，并在重试之前显式恢复或完成该对文件。没有 自动回滚或重放机制可以覆盖另一个写入器的替换。 身份检查可检测观察到的更改，但不是文件系统比较并交换； 此协议不承诺断电持久性。成功发布后， 清理失败会警告并保留路径，而不会将该对文件报告为未发布。 当恢复条目的设备或 inode 未知（为零） 或与捕获的身份不同时，清理会保留这些恢复条目。

模型字段：

抑制字段：

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

upstreamModel 标记一行，该行以不同名称提供与另一个捆绑目录中某行相同的上游模型，例如与供应商 API 端点并列的订阅端点。它是编写元数据：归一化会丢弃它，契约测试会使用它来防止 compat.codeMode 等能力标志在发布同一模型的目录之间发生漂移。大多数行无需标记，因为匹配会忽略前导供应商命名空间和大小写：moonshotai/kimi-k3 和 zai-org/GLM-5.2 已经匹配第一方 kimi-k3 和 glm-5.2 行。仅当供应商自身名称确实不同时，才使用 upstreamModel。参见 代码模式。

不要在 modelCatalog 中放入仅运行时可用的数据。只有当清单行足够完整，使按 provider 过滤的列表和选择器界面可以跳过注册表/运行时发现时，才使用 static。当清单行是有用的可列出种子或补充，但刷新/缓存之后可能添加更多行时，使用 refreshable；refreshable 行本身不是权威来源。当 OpenClaw 必须加载 provider 运行时才能知道列表时，使用 runtime。

目录刷新计划会将手动根声明与生成的 provider 清单分开。拥有相同 provider ID 的插件不会将手动模型变成可丢弃的缓存数据。合并模式会保留这些声明和仅认证记录；显式替换模式保留其替换契约。生成的目录仍遵循当前所有权、端点资格和权威替换规则。

对于具有 activation.onStartup: false 的插件，生成的缓存读取要求该目录中至少一个当前拥有且端点合格的 provider 具有当前认证。运行时读取器使用已捕获的认证或来自 provider 配置的可用密钥；保留的目录本身无法进行认证。显式编写的行保持独立。此成员资格规则不会删除已存储数据，也不会授予请求权限。

能力属于已声明的 API 和 base URL，而不仅仅是 provider/model id。当模型列表补充缓存行时，它仅对匹配的路由使用清单能力；自定义端点必须提供自己的限制和能力。

modelIdNormalization 参考¶

使用 modelIdNormalization 进行低开销的、由 provider 拥有的 model-id 清理，且必须在 provider 运行时加载之前发生。这样可以将别名（例如短模型名称、provider 本地旧 id 和代理前缀规则）保留在拥有该 provider 的插件清单中，而不是放在核心模型选择表中。

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

Provider 字段：

modelPricing 参考¶

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

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

Provider 字段：

源字段：

价格来自对请求进行计费的一方。已声明的提供商策略仅启用其已声明的源映射。如果没有策略，发布时会先尝试提供商的 models.dev 条目，然后尝试 LiteLLM。models.dev 条目是由 modelCatalog.modelsDev 指定的条目，或由 modelsDev.provider 指定的条目，否则使用 OpenClaw 提供商 ID。OpenRouter 的数据源描述 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。轻量级插件拥有的 pricing-api.ts 工件与运行时发现共享负载解析，而不导入提供商运行时。

DeepInfra 的顶层数组使用 model_name 标识。其数值折扣和缓存输入比例适用于原生每 token 美分价格。价格说明文字、非空表格、计划过期以及未记录的通用缓存写入费率会被验证，但作为不支持的价格计划被省略。优先级/弹性以及显式缓存保留倍数不会改变标准成本。其代理投影继续拥有运行时元数据；价格数据源不会发现聊天模型。

已选择加入的原生源拥有完整的提供商价格计划，包括缺失价格：通用源无法填补其缺口。对于捆绑模型没有价格的正常数据源会保留该模型的元数据，省略其成本，并发出发布警告。缺失价格不是模型退役或免费使用的证据。显式原生零价格仍然是已知免费估算。获取失败、格式错误的响应体或声明价格，以及没有可用价格的数据源会停止发布，保留之前的托管目录不变。显式操作员费率保持不变。此编写元数据不添加任何操作员设置，也不会改变网关现有的刷新和重启生命周期。

OpenClaw 提供商索引¶

已编译的 OpenClaw 提供商索引已弃用。模型元数据来自插件清单、提供商拥有的发现以及托管模型目录，配置的重写由模型解析应用。有关目录来源和刷新行为，请参阅 模型列表。

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

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