快速规则

• 模型引用使用 provider/model 格式（示例：opencode/claude-opus-4-6）。
• agents.defaults.models 存储别名和每模型设置；agents.defaults.modelPolicy.allow 是可选的显式覆盖允许列表。
• CLI 辅助命令：openclaw onboard、openclaw models list、openclaw models set <provider/model>。
• models.providers.*.maxTokens 设置提供商级别的输出 token 默认值。在每条 models.providers.*.models[] 条目中，contextWindow 声明原生窗口，contextTokens 限制有效输入，maxTokens 覆盖该模型的输出容量。配置的输出限制在已知时会钳制到最终的原生上下文窗口：优先使用该模型的 contextWindow，否则使用发现的窗口。
• 回退规则、冷却探测和会话覆盖持久化：模型故障转移。

当你添加或重新认证提供商时，openclaw configure 会保留现有的 agents.defaults.model.primary。openclaw models auth login 也是如此，除非你传入 --set-default。提供商插件仍可能在其认证配置补丁中返回推荐的默认模型，但当主模型已存在时，OpenClaw 会将其视为“让该模型可用”，而不是“替换当前主模型”。

若要主动切换默认模型，请使用 openclaw models set <provider/model> 或 openclaw models auth login --provider <id> --set-default。

OpenAI 模型引用与代理运行时是分离的：

• openai/<model> 选择规范的 OpenAI 提供商和模型。仅凭该前缀绝不会选择 Codex。
• 当 provider/model 运行时策略未设置或为 auto 时，OpenAI 可能仅在没有编写 provider 请求覆盖的精确官方 HTTPS Platform Responses 或 ChatGPT Responses 路由上隐式选择 Codex。有效的模型级 Fast-mode 控制不计为编写的请求参数。
• 编写的 Completions 适配器、自定义端点以及具有编写的请求行为的路由仍保留在 OpenClaw 上。明文官方 HTTP 端点会被拒绝。
• 旧版 Codex 模型引用是旧配置，doctor 会将其重写为 openai/<model>。
• provider/model agentRuntime.id: "openclaw" 会显式将原本符合条件的路由保留在 OpenClaw 上。agentRuntime.id: "codex" 需要 Codex，并且当有效路由与 Codex 不兼容时会失败关闭。

参见 OpenAI 隐式代理运行时 和 Codex 工具链。如果 provider/runtime 分离让你困惑，请先阅读 代理运行时。

插件自动启用遵循相同的边界：隐式兼容 Codex 的有效路由可以启用 Codex 插件，而显式的 provider/model agentRuntime.id: "codex" 或旧版 codex/<model> 引用则需要该插件。openai/* 前缀本身不会。

全新的 OpenAI API 密钥及 ChatGPT/Codex OAuth 设置会选用规范的 openai/gpt-6-astra 引用。裸 direct-API 别名 openai/gpt-5.6 仍受支持，并解析为 Sol。当 OpenAI 认证被添加或刷新时，现有的显式主模型（包括 openai/gpt-5.5）会得到保留。GPT-5.5 仍可通过任一运行时作为没有 GPT-5.6 访问权限的账户的显式恢复选项。

CLI 运行时使用同样的分离方式：选择规范模型引用（如 anthropic/claude-* 或 google/gemini-*），然后在需要本地 CLI 后端时将 provider/model 运行时策略设置为 claude-cli 或 google-gemini-cli。

旧版 claude-cli/* 和 google-gemini-cli/* 引用会迁移回规范提供商引用，同时单独记录运行时。旧版 codex-cli/* 引用会迁移到 openai/* 并使用 Codex 应用服务器路由；OpenClaw 不再保留捆绑的 Codex CLI 后端。