模型 CLI

• 模型故障转移

认证配置文件轮换、冷却时间，以及这些与回退之间的交互方式。

• 模型提供商

提供商快速概览与示例。

• Models CLI 参考

完整的 openclaw models 命令与标志参考。

• 配置参考

模型配置键、默认值及示例。

模型引用（provider/model）选择的是提供商和模型，而不是底层代理运行时。当运行时策略未设置或为 auto 时，OpenAI 提供商自有的路由策略可能仅针对精确的官方 HTTPS Platform Responses 或 ChatGPT Responses 路由（且没有自定义请求覆盖）选择 Codex。单独的 openai/* 前缀绝不会选择 Codex。Completions 适配器、自定义端点和自定义请求行为仍由 OpenClaw 处理。纯文本官方 HTTP 端点会被拒绝。参见 OpenAI 隐式代理运行时。

订阅版 Copilot 引用（github-copilot/*）可以选择使用外部 GitHub Copilot 代理运行时插件，但该路径始终是显式的（绝不会由 auto 选择）。运行时覆盖应放在 provider/model 策略上，而不是整个代理或会话上。运行时选择不决定计费方式：OpenAI API 密钥和 ChatGPT/Codex 订阅凭据仍然相互独立。参见 代理运行时 和 GitHub Copilot 代理运行时。

选择顺序¶

1. 主要模型

agents.defaults.model.primary（或者 agents.defaults.model 作为普通字符串）。

2. 回退

agents.defaults.model.fallbacks，按顺序尝试。

3. 认证故障转移

认证配置文件轮换在提供商内部发生，然后 OpenClaw 才会转向下一个回退模型。

相关的模型配置项：

• agents.defaults.models 存储别名和每模型设置。在旧版策略迁移之后，添加条目不会限制模型覆盖。
• agents.defaults.modelSelectionScope 在未显式指定作用域时，选择聊天命令和 Gateway 会话模型更新的作用域。默认是当前会话。参见 模型选择作用域。
• agents.defaults.modelPolicy.allow 是可选的覆盖白名单。使用精确引用或尾部前缀通配符，例如 provider/* 和 provider/namespace/*。省略它或设置为 [] 以允许任何模型。按代理设置的 agents.entries.*.modelPolicy.allow 会替换该代理的默认策略。
• agents.defaults.utilityModel 是一个可选的、成本更低的辅助模型，用于短时内部任务。这些任务包括生成的仪表板会话标题、受支持的频道线程或主题标题、进度解说，以及滚动更新的活动摘要。按代理的 agents.entries.*.utilityModel 会覆盖该设置。未设置时，如果主要提供商声明了小型模型默认值，OpenClaw 会使用该默认值（OpenAI → gpt-5.6-luna，Anthropic → claude-haiku-4-5），否则使用代理的主要模型。将其设置为空字符串可禁用辅助模型路由。当不同的辅助模型失败时，生成的标题会使用主要模型重试一次。对于仪表板标题，自动辅助模型推导和常规回退遵循当前有效的会话提供商和认证配置文件。显式指定的辅助模型会保留其配置的提供商和认证。空的辅助模型仅跳过备选小型模型路由，而不会跳过仪表板标题生成。辅助任务是独立的模型调用，并可能将有界任务内容发送到所选模型提供商。活动摘要使用有界的对话记录摘录和之前的摘要，失败时保留缓存的文本，并且不会回退到主要模型。
• agents.defaults.decisionModel 选择一个插件的类型化决策模型，以 provider/model 形式用于选项、评分和布尔概率。当未设置或为空时，该功能被禁用。按代理的 agents.entries.*.decisionModel 在未设置时继承该设置，在为空时禁用决策。Control UI 在 Utility 旁有一个独立的 Decision 选择器；决策模型绝不会出现在聊天、主要、回退或辅助选择中。支持插件调用决策运行时；仅选择本身不会启动后台工作，也不会替换聊天模型。
• agents.defaults.imageModel 仅在主要模型无法接受图像时使用。
• agents.defaults.pdfModel 由 pdf 工具使用。如果未设置，该工具会回退到 imageModel，然后是解析后的会话/默认模型。
• agents.defaults.mediaModels.{image,music,video} 支持共享的媒体生成工具。如果未设置，每个工具会推断一个由认证支持的提供商默认值：首先是当前默认提供商，然后是按 provider-id 顺序排列的、为该能力注册的其余提供商。跨提供商回退是固定的默认行为。
• 按代理的 agents.entries.*.model（加上绑定）会覆盖 agents.defaults.model——参见多代理路由。

完整的键参考、默认值和 JSON5 示例：配置参考。

有关类型化决策模型类、可用模型、评分标准和插件 API，请参阅决策模型。

显式的 modelPolicy.allow 限制是在 v2026.8.1 中引入的。对于旧版模型映射，当每个引用都有效时，openclaw doctor --fix 会将完整限制复制到 modelPolicy.allow 中。当一个受支持的 include 文件拥有该修复时，Doctor 会更新该文件并保留其祖先 include 指令（即使在更新期间也是如此）。跨越多个所有者的修复仍然需要编辑相应的拥有文件。如果任何引用需要提供商限定，Doctor 会保留整个旧版限制，并报告如何设置显式策略。在此之前，模型映射编辑仍然会更改旧版限制。不会有键被静默丢弃，也不会用空策略替代未解析的限制。

从包含的配置中移除显式默认模型策略会保留空的 modelPolicy: {}。当后续添加别名或模型设置时，这会使策略保持不受限制。

选择来源与回退严格性¶

相同的 provider/model 会根据其来源表现出不同行为：

其他选择规则：

• 更改 agents.defaults.model.primary 不会重写现有会话固定。如果状态报告 This session is pinned to X; config primary Y will apply to new/unpinned sessions.，运行 /model default 以清除固定。
• CLI 默认模型和允许列表选择器会遵循 models.mode: "replace"，仅列出 models.providers.*.models，而不是完整的内置目录。
• Control UI 从 Gateway 准备好的已配置模型视图开始，因此打开聊天不会启动提供商发现。打开聊天模型选择器会读取已发布行，包括由末尾 provider/* 策略条目匹配的行。使用其显式刷新操作请求立即提供商发现。默认和已配置的选择器视图会隐藏标记为 deprecated 或 disabled 的目录行。有一个例外：当该确切模型被配置为主模型、回退模型、实用工具或工具模型、别名或设置键，或确切策略条目时，该行保持可见。隐藏行仍可通过确切的 provider/model 引用进行选择。完整内置目录（包括隐藏行）仅保留给显式浏览视图（models.list 使用 view: "all"，或 openclaw models list --all）。
• 提供商清单 UI 使用 models.list 和 view: "provider-config" 来显示源编写的 models.providers.*.models 行，而不应用选择器允许列表。
• 聊天和新会话保持默认重置选项固定在其提供商组中，然后将所选模型放在其余目录选项之前。模型设置将所选模型放在最前。其他行保持 Gateway 的目录顺序，包括在提供时提供商精选的推荐。文本 /models <provider> 页面也会将当前模型放在最前，而不是按字母顺序排列目录。选择器搜索会检查完整列表，而不仅仅是可见行。
• 登录提供商时，在打开的 Control UI 和终端模型选择器中，现有选项保持可见，同时发现会在后台刷新。模型限制、操作员角色或目录模式的更改仍会停用旧选项，直到替代目录准备就绪。
• Gateway 启动后发布的第一份目录使用与后续刷新相同的提供商拥有的模型顺序。捕获的行在可用时继承提供商推荐；没有提供商排名的行保持目录的字母顺序回退。

在共享 Gateway 上，管理员还可以配置命名角色的模型策略。模型发现以及 Control UI、macOS 和 iOS 聊天选择器仅显示该策略允许的模型。这也适用于 Control UI 中的新会话。默认选项使用允许的自动默认值；它不会授予额外的手动选项。模型限制、操作员角色或目录模式的更改会在刷新目录之前丢弃旧选项。已保存的对话保留其历史模型信息。仅过滤不会覆盖已保存的新会话模型偏好。当策略再次允许时，已保存的选项可以返回；显式选择另一个模型仍会更新偏好。

Gateway 会为 CLI、/models、Control UI 和原生应用准备一个模型目录。聊天和会话元数据读取已发布的行，而不会启动提供商发现。模型清单请求会立即返回这些行，并可以在后台续订过期的提供商清单。选中的原生模型可以在该续订仍在运行时加载其自身元数据。

在聊天应用中，/models 和模型选择器按钮会返回最新完成的列表，而不会等待发现。待处理的提供商显示 checking models…。 再次打开菜单以查看新发现的模型；完成发现不会编辑已经发送的列表。

如果准备大型机群所需时间超过两分钟的启动预算，Gateway 会使用已完成准备的代理模型运行时启动。警告会列出剩余的代理和获取阶段，包括已知的工作区插件。openclaw health --json 和 Gateway status RPC 会报告 modelRuntime.degraded 和 modelRuntime.pendingAgents。准备会在后台继续；每个完成的代理都会变为可用，并且当完整发布完成时，降级状态会清除。未完成的代理在其运行时和身份验证事实就绪之前，无法处理模型请求。

登录后，初始模型立即可用。当 Gateway 发现账户模型时，选择器搜索字段中的小加载指示器表示后台刷新。将鼠标悬停、聚焦或点击它，以查看哪些提供商正在刷新；现有模型保持可用，并且打开的选择器会在发现完成时更新。空选择器会显示“正在加载模型…”，直到其首批模型到达。 Gateway 启动和凭据更改 也会刷新受影响的目录。在“模型”中使用 刷新 或 openclaw models list --refresh 请求另一次刷新，包括新发布的模型。重试 在失败后再次请求发现。

如果凭据刷新丢失了其插件代际，OpenClaw 会针对当前插件重试发布一次。如果该重试失败，记录的失败和 Gateway 警告会标识失败的新一代重试。

对于配置为使用 CLI 运行时的模型，通道选择器可用性遵循该运行时的已准备身份验证。提供商 API 密钥不能替代其原生登录。

如果发现失败，设置 > 模型 和 openclaw models list 会报告失败并保留最后一个兼容的模型列表。如果没有，OpenClaw 会显示已准备的初始模型。聊天和原生 Quick Chat 模型选择器会保留可用选项，而不显示整个目录的警告；所选模型可用性仍然适用。其他提供商仍可以更新。成功的空响应会清除该提供商发现的模型；它不会恢复旧选项。显式配置的模型和独立的原生运行时目录会保留。

对别名或模型限制的更改会重用兼容清单。对提供商、插件、凭据、环境或工作区的更改可能会使其失效。

自动化和命令面板模型搜索会在提供商刷新失败时显示警告，同时保留 Gateway 返回的模型。打开模型以重试刷新。成功的空结果会清除发现的选项和警告。

成功的提供商结果优先于保留的行，即使另一个凭据报告失败。

完整机制：模型故障转移.

快速模型策略¶

• 将你的主模型设置为你可用的最强最新代模型。
• 对成本/延迟敏感的任务和低风险聊天使用回退。
• 对于启用工具的代理或不可信输入，避免使用较旧/较弱的模型层级。

入门¶

openclaw onboard

为常见提供商设置模型和身份验证，无需手动编辑配置，包括 OpenAI Codex 订阅 OAuth 和 Anthropic（API 密钥或 Claude CLI 复用）。

在未配置主模型的情况下，新的 OpenAI API 密钥和 ChatGPT/Codex OAuth 设置会选择精确的 openai/gpt-6-astra 目录引用。纯直接 API openai/gpt-5.6 别名仍受支持，并解析到 Sol 层级。 重新身份验证会保留现有的显式主模型，包括 openai/gpt-5.5。如果 GPT-5.6 对账户不可用，请显式选择 openai/gpt-5.5。OpenClaw 不会静默降级它。

“模型不允许”（以及为什么回复会停止）¶

当 modelPolicy.allow 被省略或为空时，即使显式 provider/model 不在有限的 /model 选择器目录中，你也可以选择它。 目录提供浏览选项和模型元数据。它不是隐式 允许列表。提供商可用性、运行时兼容性和身份验证会独立 检查。不受限制的策略不会使未知 提供商或不受支持的运行时可用。如果策略被省略，上述未迁移的 旧版模型映射限制仍然适用。

别名和策略条目不能证明某个模型在提供商端点上可用。 原生端点需要受支持的模型定义或提供商拥有的解析。 显式自定义和本地端点可以使用未列出的模型名称。子代理生成 在创建子状态之前会检查相同的支持。自动选择 在至少一个候选项受支持时，会保留其原始主模型和回退顺序。

相同策略适用于 /new 或 /reset 后的显式 provider/model 和已配置别名提示。无法识别的前导文本保留在提示中。

如果 agents.defaults.modelPolicy.allow 非空，它将成为 /model、会话覆盖和 --model 的允许列表。选择该允许列表之外的模型会在生成任何正常回复之前返回。每个代理的 agents.entries.*.modelPolicy.allow 会替换该代理的默认策略。

精确条目仅允许该模型。已配置的默认值和自动 回退不会授予额外的手动选项。更新后的选择器使用与显式模型命令相同的 策略，同时保留当前模型控制。 旧版客户端仍可能显示被禁止的选项；服务器会拒绝其选择。 重置为默认会清除会话固定 并保留现有的自动选择行为。

Model override "provider/model" is not allowed by agents.defaults.modelPolicy.allow.
Add "provider/model", "provider/*", or a narrower "provider/namespace/*" prefix to agents.defaults.modelPolicy.allow, or remove/empty the list to allow any model.

通过向指定的 modelPolicy.allow 键添加模型或提供商通配符、删除/清空该列表，或从 /model list 中选择一个模型来修复。如果被拒绝的命令包含运行时覆盖（例如 /model openai/gpt-5.5 --runtime codex），请先修复允许列表，然后重试同一命令。

对于本地/GGUF 模型，允许列表需要使用带提供商前缀的完整引用，例如 ollama/gemma4:26b 或 lmstudio/Gemma4-26b-a4-it-gguf — 使用 openclaw models list --provider <provider> 查看确切字符串。一旦允许列表生效，仅使用裸文件名或显示名称是不够的。

若要限制提供商而不必列出每个模型，请使用末尾前缀通配符条目。提供商范围的 provider/* 会匹配该提供商下的所有模型。更窄的前缀（例如 clawrouter/anthropic/*）仅匹配该命名空间：

{
  agents: {
    defaults: {
      modelPolicy: {
        allow: ["openai/*", "vllm/*"],
      },
    },
  },
}

之后，/model、/models 和模型选择器将仅显示这些提供商的发现目录，并且新模型可以在不编辑允许列表的情况下出现。将精确的 provider/model 条目与 provider/* 条目混合使用，可从其他提供商引入一个特定模型。

带有别名和按模型设置的允许列表示例：

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4-6" },
      modelPolicy: {
        allow: ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "anthropic/claude-opus-4-6": { alias: "Opus" },
      },
    },
  },
}

openclaw config set agents.defaults.modelPolicy.allow '["openai/gpt-5.4","anthropic/*"]' --strict-json

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.6-sol": {
          agentRuntime: { id: "openclaw" },
          pickerRuntimes: ["codex"],
        },
      },
    },
  },
}

为会话选择模型¶

在 Control UI 的聊天模型菜单中，可按模型或提供商名称搜索。使用方向键在结果中移动，按 Enter 选择一个。Escape 清除搜索。仅输入不会更改已选模型。

Gateway 的 sessions.create 和 sessions.patch 会在目标会话的代理作用域中解析模型别名和 modelPolicy.allow。显式的按代理允许列表会替换共享默认值，包括使用 [] 允许任意模型。策略权限不会提供提供商凭据，也不保证所选模型对其运行时可用。

在保存模型选择之前，这些 Gateway 方法会检查任何必需的嵌入式运行框架是否具有已安装且可激活的插件。缺失或禁用的插件会拒绝更改，并保留之前的会话选择和已配置的默认值。安装并启用指定的运行框架插件，重启 Gateway，然后再次选择该模型。此检查不会启动运行时或验证提供商凭据。

如果现有会话的运行框架变得不可用，失败的回合会在已知时报告所有者插件及其激活或加载阻塞项。请遵循错误中的 openclaw doctor --fix 或 openclaw plugins inspect <id> --runtime --json 指引，修复插件，并在重试前重启 Gateway。Gateway 健康探测独立于模型执行。使用 模型状态 和 Doctor 诊断已配置的路由。

尽可能在创建会话时选择模型。Control UI 的 New Chat 编辑器包含模型选择器，原因就在于此：新会话会为所选模型提供一个干净的会话边界。

更改已建立会话的模型是一项高级操作。会话记录仍然可用，但下一个模型可能具有不同的上下文窗口、提示词和工具行为，或提示词缓存实现。因此，会话中途切换可能会降低连续性、要求更早压缩，或失去提示词缓存复用并增加延迟或成本。对于计划中的模型更改，优先使用新会话。当你有意希望现有记录以另一个模型继续时，使用 /model 或活动会话模型选择器。

当缓存复用时，请保持会话的思考或推理级别稳定。在 OpenAI 上，更改推理强度会更改可复用请求状态，并可能迫使下一轮重新处理完整对话。其他提供商也可能将思考配置包含在其缓存标识中，因此即使模型本身保持不变，仅更改思考级别也可能增加延迟和输入 Token 成本。

保留的推理在当前 Claude 模型中与模型绑定。将会话从 Claude Fable 5.1 移开后，将继续而不携带 Fable 之前的思考；切换到它时会保留 Opus 5、Sonnet 5、Opus 4.8 和 Fable 5 的思考；切换离开再切回，或更改 /think，会使切换前的 Fable 推理失效。参见 Anthropic。

聊天中的 /model¶

/model <model> 更改当前会话。使用 -s 表示仅更改此会话，使用 -a 表示同时更新代理的默认值，或使用 -g 表示同时更新共享全局默认值。长格式为 --session、--agent 和 --global。写入已配置默认值需要所有者或管理员权限。

未指定范围标志时，选择仅更改当前会话。agents.defaults.modelSelectionScope 可显式选择 "agent" 或 "global" 范围。仅拥有所有者/管理员权限不会扩大未指定范围的选择。没有所有者/管理员权限时，裸命令仍仅限会话，显式 -a 或 -g 请求会被拒绝。

/model
/model list
/model Opus
/model openai/gpt-5.4
/model openai/gpt-5.4 -s
/model openai/gpt-5.4 -a
/model openai/gpt-5.4 -g
/model default -s
/model default
/model status

• 在文本聊天中，/model 显示当前选择。/model list（或 /models）浏览提供商。/models <provider> 列出模型引用。
• 使用 /model <provider/model> 或 /model <alias> 进行选择（例如，使用上面配置的别名时执行 /model Opus）。不支持 /model 3 这类数字选择。
• 在 Discord 上，不带参数的原生 /model 和 /models 会打开交互式选择器。选择提供商和模型，然后按 提交。Discord 选择器遵循直接命令行为，包括 modelSelectionScope。
• 在 Telegram 上，/model 提供 浏览提供商 按钮。/model list 和 /models 直接打开提供商菜单。点按提供商，然后点按模型。Telegram 回调选择始终仅限会话。
• /models add 已弃用，并返回一条消息，而不是从聊天中注册模型。
• 当前会话： /model <model> -s（或 --session）无论 modelSelectionScope 如何，都只更改此会话。两个已配置默认值均不会更改。
• 代理默认值： 所有者/管理员执行 /model <model> -a（或 --agent）会为此会话选择模型，并请求更新 agents.entries.<agent>.model。必要时会为已配置的该代理创建显式主模型，并且绝不会回退到共享全局默认值。
• 全局默认值： 所有者/管理员执行 /model <model> -g（或 --global）会更改此会话，并请求更新共享的 agents.defaults.model 回退值。它不会覆盖其他代理的显式主模型或其他会话的模型固定项。新的和现有的未固定会话，以及继承此默认值的 cron 任务，可在下次运行时使用已更改的模型。
• 不可变配置保持不变。异步写入错误会被记录，而不会回退会话选择。显式的模型和 auth-profile 固定项在有效期间会保留，即使经过 /new、/reset、会话轮换、压缩和冷却窗口。
• 使用已配置默认值： /model default -s 会清除当前会话的模型选择，而不会写入已配置默认值。兼容的 auth-profile 固定项会保留。不兼容的固定项会被清除。按名称选择生效的已配置默认值也会清除会话模型固定项，但 agent/global 范围仍会请求写入该已配置目标。这不会恢复之前选择所更改的旧已配置默认值。
• 遵循兼容的运行时选择： 仅更改模型时，如果会话运行时固定项支持所选提供商，则会保留该固定项。否则，固定项会被清除，所选模型会自动遵循其已配置的运行时。显式请求的不兼容运行时仍会被拒绝，且不会更改任一选择。使用 /model <provider/model> --runtime <runtime> -s 切换运行时，或使用 --runtime default 遵循已配置路由。Control UI 中的显式运行时行和 默认 仍可选择或重置运行时。
• 如果代理处于空闲状态，模型更改会立即应用于下一次运行。如果已有运行处于活动状态，切换会排队到下一个干净的重试点。如果工具活动或回复输出已经开始，它可能会被排队到更晚的点。
• 用户选择的 /model 引用对该会话是严格的：如果它变得不可达，回复会明显失败，而不是通过 agents.defaults.model.fallbacks 静默回退。已配置默认值和 cron 任务主模型仍使用回退链。
• /model status 是详细视图：每个提供商的身份验证候选项，以及（如果已配置）提供商端点 baseUrl 和 api 模式。
• 模型引用通过按第一个 / 拆分来解析。输入 provider/model。如果模型 ID 本身包含 /（OpenRouter 风格），请包含提供商前缀，例如 /model openrouter/moonshotai/kimi-k2。如果省略提供商，OpenClaw 会先尝试别名匹配。然后，它会尝试针对该确切无前缀模型 ID 的唯一已配置提供商匹配。接着，它会尝试已配置的默认提供商，这是一种已弃用的回退方式。如果该提供商不再公开已配置的默认模型，OpenClaw 会改用第一个已配置的提供商和模型。这可避免暴露过时的已移除提供商默认值。
• 在推断提供商时，模型 ID 的精确大小写优先于同一配置范围内的不区分大小写匹配。仅当不区分大小写匹配能确定一个提供商时，才会使用它。每个代理的模型条目优先于全局条目和已配置的提供商目录。
• 提供商 ID 会被规范化为小写。模型 ID 遵循提供商的规范化规则。请使用插件公布的拼写。
• 已配置的主模型也接受 provider/alias。别名会在推断之前在该提供商内部解析，而为该提供商配置的精确模型 ID 会保留其字面身份。可选的 auth-profile 后缀（例如 @work）与模型身份保持分离。

完整命令行为和配置：斜杠命令。

CLI¶

openclaw models status
openclaw models list
openclaw models set <provider/model>
openclaw models set-image <provider/model>
openclaw models scan
openclaw models aliases list|add|remove
openclaw models fallbacks list|add|remove|clear
openclaw models image-fallbacks list|add|remove|clear
openclaw models auth list|add|login|paste-api-key|paste-token|setup-token|order

openclaw models 不带子命令时是 models status 的快捷方式，它还会显示 auth-store 配置文件的 OAuth 过期时间（默认在 24 小时内发出警告）。完整标志、JSON 结构和 auth-profile 子命令：Models CLI 参考。

模型注册表（models.json）¶

托管目录更新¶

OpenClaw 可以刷新由已安装 provider 插件随附的模型元数据，而无需等待新的 OpenClaw 版本。Gateway 在启动时执行一次后台 JSON GET，之后最多每六小时检查一次。该请求除正常的 HTTP user agent 和条件缓存头外，不会发送任何提示、凭据、模型使用情况或配置负载。

下载的捆绑包存储在共享 SQLite 状态数据库中，并在下一次 Gateway 重启后生效。远程数据只能更新或添加由已安装插件清单声明的 provider 的模型。它不能提供 API 基础 URL 或请求头，并且比已安装版本的构建时间戳更旧的目录会被忽略。

Gateway 会报告已检查的目录需要重启才能生效，包括由另一个进程下载的捆绑包。对同一来源和同一代次的重复检查不会重复提示。检查更新不会激活已下载的行或价格。

托管文件从公开的 openclaw/catalog GitHub 仓库发布。 发布时，它还会为拥有插件明确通过 modelCatalog.modelsDev 选择加入的 provider，从 models.dev 填充模型 ID 和元数据。每个映射 只命名一次上游 provider，而不是映射单个模型。没有 中央 provider 回退。清单值保持权威，因此 填充只会补全未定义的元数据，并且从不提供传输设置 或价格。成本仍然来自每个 provider 的定价策略。只导入具有 工具调用和文本输出的行，并且 models.dev 标记为弃用 或退役的行会被跳过。如果 models.dev 本身不可达或格式错误， 发布会失败，并且最后发布的工件保持原位。单个 缺失或重命名的上游 provider 只会跳过该 provider 的填充；其 清单行仍会发布，因此一个 provider 不会阻止其余目录更新。这是一个 发布时契约：它不增加 Gateway 获取或热重载，并且更新后的 元数据仍然在 Gateway 重启后生效。 其计划工作流每四小时检查 OpenClaw 默认分支的插件清单和 公开定价来源。每次目录内容变更都 保存为公开提交。Provider 拥有的策略选择完整价格 计划，包括上下文层级，而不混合来自不同来源的费率。 声明的原生来源读取公开的 Cerebras、Chutes、DeepInfra、OpenCode 和 Venice 目录，因此已连接的部署可以在没有 新 OpenClaw 版本的情况下收到宣传的价格变更。当有效的原生源不再提供某个模型的 价格时，发布会保留模型元数据而不提供估算。它不会 推断退役或替换另一个来源的费率。显式用户成本仍然 优先。DeepInfra 使用其代理投影作为模型元数据，并使用其原生 /models/list 源作为价格，包括数字折扣。符合条件的计划 如果无法表示为无条件 token 成本，则保持未知。模型 仍然可用。参见 DeepInfra 价格估算。

运行 openclaw models refresh 以立即检查元数据和定价，或者使用 models.catalogRefresh.enabled: false 禁用所有托管目录请求。禁用后，定价保持为捆绑值和显式配置值。可以使用 HTTPS models.catalogRefresh.url 选择自托管镜像（测试时可使用 localhost HTTP）。参见 配置参考。

在 models.providers 下配置的自定义 provider 会写入 agent 目录下的 models.json（默认 ~/.openclaw/agents/<agentId>/agent/models.json）。Provider 插件目录作为生成的插件拥有的目录分片单独存储，并自动加载。此文件默认与配置合并。设置 models.mode: "replace" 以仅使用你配置的 provider。

在默认 merge 模式下，已配置的模型行会与符合条件的 provider 发现结合。它们为匹配的模型提供元数据和请求覆盖；它们不会将发现限制为已保存的 ID。旧 provider 模型数组可以保留在你的配置中，而不会隐藏新宣传的模型。使用 agents.defaults.modelPolicy.allow 或按 agent 的策略来限制模型选择，并使用 models.mode: "replace" 保持完全静态的配置目录。

生成的插件目录提供模型清单，而不是请求凭据。它们的缓存 API 密钥、认证模式和请求头不会授权模型请求。请改用当前 auth profile 或编写的请求配置。如果没有当前配置快照，session SDK 会保留编写的 models.json 密钥和请求头，同时将生成的元数据合并到编写行之下。如果有当前快照，provider 的当前声明拥有请求设置；仅保留在旧文件中的密钥和请求头不会重新获得权限。

预构建目录在解析模型之前组合静态、生成、手写文件以及当前配置的行。显式模型路由优先于捕获的路由，捕获的路由优先于提供商默认值。在替换模式下，只有当前声明会进入目录；清单清单和运行时回退行不能添加其他模型。

models.providers.*.models 中的提供商别名在发现之前只解析一次。如果同时配置了别名及其精确目标，则目标行拥有模型字段；省略的字段不会从别名行复制。刷新期间，来自 models.json 和插件发现的目录 ID 保持字面值，除了针对已退役的 Google 和 Together 模型名称的内置更正。

标记持久化以源为权威。OpenClaw 从活动源配置快照（解析前）写入标记，而不是从已解析的运行时密钥值写入。每当它重新生成 models.json 时都会这样做，包括由命令驱动的路径，例如 openclaw agent。

相关¶

• 代理运行时 — OpenClaw、Codex 和其他代理循环运行时
• 配置参考 — 模型配置键
• 图像生成 — 图像模型配置
• 模型故障转移 — 回退链
• 模型提供商 — 提供商路由和认证
• 模型 CLI 参考 — 完整命令和标志参考
• 音乐生成 — 音乐模型配置
• 视频生成 — 视频模型配置
• openclaw infer — 面向提供商支持的模型、媒体和嵌入工作流的 infer 优先 CLI