跳转至

模型字段

描述 provider 插件所暴露模型的 manifest 字段:它声明了哪些简写 id,core 在 runtime 加载前可以读取的 catalog 行,model-id 清理,以及托管定价策略。属于 插件 manifest 参考的一部分;顶层字段参考 列出了所有字段。

modelSupport 参考

当 OpenClaw 需要在插件 runtime 加载前,根据 gpt-6-astra 或 claude-sonnet-4.6 等简写 model id 推断你的 provider 插件时,使用 modelSupport。

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

OpenClaw 按以下优先级处理:

  • 显式 provider/model 引用使用所属 providers manifest 元数据
  • modelPatterns 优先于 modelPrefixes
  • 如果一个非捆绑插件和一个捆绑插件都匹配,则非捆绑插件胜出
  • 其余歧义会被忽略,直到用户或配置指定 provider

字段:

字段 类型 含义
modelPrefixes string[] 与简写 model id 进行 startsWith 前缀匹配的前缀。
modelPatterns string[] 移除 profile 后缀后,与简写 model id 匹配的正则表达式源。

modelPatterns 条目会通过 compileSafeRegex 编译,它会拒绝包含嵌套重复的模式(例如 (a+)+$)。未通过安全检查的模式会被静默跳过,与语法无效的正则表达式相同。请保持模式简单,并避免嵌套量词。

modelCatalog 参考

当 OpenClaw 需要在加载插件 runtime 之前获知 provider 模型元数据时,使用 modelCatalog。这是 manifest 管理的固定 catalog 行、发布时元数据源、provider 别名、抑制规则和发现模式的来源。Runtime 刷新仍应放在 provider runtime 代码中,但 manifest 会告诉 core 何时需要 runtime。

{
  "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 Record<string, string> 发布时从所属 OpenClaw provider id 到 models.dev provider id 的选择性加入映射。
providers Record<string, object> 本插件拥有的 provider id 的 catalog 行。键也应出现在顶层 providers 中。
aliases Record<string, object> 应解析到所属 provider 的 provider 别名,用于 catalog 或抑制规划。
suppressions object[] 本插件因 provider 特定原因而抑制的来自其他来源的 model 行。
discovery Record<string, "static" \| "refreshable" \| "runtime"> provider catalog 是否可以从 manifest 元数据读取、刷新到缓存,或需要 runtime。
runtimeAugment boolean 仅当 provider runtime 必须在 manifest/config 规划后追加 catalog 行时,才设置为 true。

modelsDev 在托管 catalog 发布时,将所属 provider 加入 models.dev 元数据水合。每个 OpenClaw provider 只声明一次上游 provider,而不是每个 model 声明一次。省略表示不进行 models.dev 水合;没有中央 provider 回退。键会规范化为 OpenClaw provider id,源 id 会被去除首尾空格。空或非字符串源 id,以及针对非所属 provider 的映射会被忽略;仅别名不会授予所有权。映射不会创建 catalog provider 行,也不会放宽其验证。

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

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

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

suppressions 取代旧的 provider 运行时 suppressBuiltInModel 钩子。仅当 provider 由插件拥有,或声明为指向由插件拥有的 provider 的 modelCatalog.aliases 键时,抑制条目才会被遵守。在模型解析期间,运行时抑制钩子不再被调用。

Provider 字段:

字段 类型 含义
baseUrl string 此 provider 目录中模型的可选默认基础 URL。
api ModelApi 此 provider 目录中模型的可选默认 API 适配器。
headers Record<string, string> 适用于此 provider 目录的可选静态请求头。
defaultUtilityModel string 可选的 provider 推荐小型模型 id,用于简短的内部实用任务(标题、进度旁白)。当 agents.defaults.utilityModel 未设置且此 provider 提供 agent 的主要模型时使用。
models object[] 必需的模型行。没有 id 的行会被忽略。

manifest 不编写推荐项。Catalog v2 从精选推荐模型列表派生每个 provider 的 recommendedModels。 仍然设置 recommendedModels 的 manifest 会按原样加载;该字段会被忽略。

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

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

模型字段:

字段 类型 含义
id string provider 本地模型 id,不带 provider/ 前缀。
name string 可选显示名称。
api ModelApi 可选的按模型 API 覆盖。
baseUrl string 可选的按模型基础 URL 覆盖。
headers Record<string, string> 可选的按模型静态请求头。
字段 类型 含义
input Array<"text" \| "image" \| "document"> 模型接受的模态。其他值会被静默丢弃。
reasoning boolean 模型是否暴露推理行为。
contextWindow number 原生提供商上下文窗口。
contextWindows Array<{ id: string; label: string; contextWindow: number }> 最多 16 个可选窗口,按 token 数量升序规范化。
contextWindowDefault string 默认可选窗口 id;必须指向 contextWindows 中的一个条目。
contextTokens number 当与 contextWindow 不同时,可选的有效运行时上下文上限。
maxTokens number 已知时的最大输出 token 数。
thinkingLevelMap Record<string, string \| null> 可选的按 thinking 级别的模型 ID 或参数覆盖。
cost object 可选的每百万 token 美元定价,包括可选的 tieredPricing。
compat object 可选的兼容性标志,匹配 OpenClaw 模型配置兼容性。
upstreamModel string 可选的 provider/model 引用,指向另一个捆绑目录中相同的上游模型。
mediaInput object 可选的按模态输入配置。image 是唯一模态。
status "available" | "preview" | "deprecated" | "disabled" 列表状态。仅当该行完全不应出现时才抑制。
statusReason string 可选的原因,随非 available 状态显示。
replaces string[] 该模型取代的旧提供商本地模型 id。
replacedBy string 已弃用行的替换提供商本地模型 id。
tags string[] 选择器和筛选器使用的稳定标签。

抑制字段:

字段 类型 含义
provider string 要抑制的上游行提供商 id。必须由本插件拥有或声明为拥有的别名。
model string 要抑制的提供商本地模型 id。
reason string 可选消息,在直接请求被抑制的行时显示。
retirement object 显式永久退役元数据。启用 doctor 修复;空对象表示未声明后继模型。
retirement.replacedBy string 已记录的提供商本地后继模型 id,包括该 id 中的任何斜杠。doctor 会保留适用的账户固定项并修复持久化引用。
when.baseUrlHosts string[] 可选的有效提供商基础 URL 主机列表,抑制生效前必须满足。
when.providerConfigApiIn string[] 可选的精确 provider-config api 值列表,抑制生效前必须满足。

仅根据明确的提供商证据声明退役,绝不能根据失败或空的发现请求声明。使用 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。参见 Code mode。

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

在 provider 获得凭据后,在所有发现模式下,列表和选择器界面都会显示其已声明的清单行,同时账户发现仍在等待中。一旦该 provider 的发现发布,其账户结果就会替换这些行。

目录刷新计划将手动根声明与生成的 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 字段:

字段 类型 含义
aliases Record<string,string> 不区分大小写的精确 model-id 别名。值按原样返回。
stripPrefixes string[] 在别名查找前移除的前缀,适用于旧 provider/model 重复。
prefixWhenBare string 当规范化后的 model id 尚不包含 / 时要添加的前缀。
prefixWhenBareAfterAliasStartsWith object[] 别名查找后针对裸 id 的条件前缀规则,以 modelPrefix 和 prefix 为键。

modelPricing 参考

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

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

Provider 字段:

字段 类型 含义
cerebras false \| object 显式映射到公共 Cerebras /public/v1/models 目录。绝不会隐式启用。
chutes false \| object 显式映射到公共 Chutes /v1/models 目录。绝不会隐式启用。
deepinfra false \| object 显式映射到公共 DeepInfra /models/list 目录。绝不会隐式启用。
external boolean 对于本地/自托管 provider,设置为 false,表示它们永远不应使用已发布的外部定价。
openCode false \| object 显式映射到公共 models.opencode.ai/api.json 目录。绝不会隐式启用。
modelsDev false \| object 为计费请求的 provider 提供 models.dev 价格列表。默认启用。
openRouter false \| object OpenRouter 自己的价格。它们仅为 openrouter/* 键定价,绝不为供应商模型定价。
liteLLM false \| object LiteLLM 发布键映射。false 会禁用此 provider 的 LiteLLM 匹配。
venice false \| object 显式映射到公共 Venice /api/v1/models 目录。绝不会隐式启用。

源字段:

字段 类型 含义
provider string 当外部目录 provider id 与 OpenClaw provider id 不同时使用,例如对于 zai provider 使用 z-ai。
passthroughProviderModel boolean 将包含斜杠的 model id 视为 vendor/model 引用,并按供应商费率定价,适用于按此计费的网关。
字段 类型 含义
modelIdTransforms "version-dots"[] 额外的外部目录模型 ID 变体。version-dots 会尝试带点号的版本 ID,例如 claude-opus-4.6。

价格来自对请求进行计费的方。已声明的提供商策略仅启用其已声明的来源映射。如果没有策略,发布会先尝试提供商的 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 和提供商 ID。轻量级的插件拥有的 pricing-api.ts 工件与运行时发现共享负载解析,而不导入提供商运行时。

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

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

OpenClaw 提供商索引

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

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

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw