快速规则

• 模型引用使用 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 设置提供者级别的输出令牌默认值。在每个 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 可能仅针对确切的官方 HTTPS 平台响应或 ChatGPT 响应路由隐式选择 Codex，而无需重写提供者请求。有效的模型范围的快速模式控件不计为创作的请求参数。
• 手动指定的 Completions 适配器、自定义端点，以及带有手动指定请求行为的路由，都会继续使用 OpenClaw。纯文本官方 HTTP 端点会被拒绝。
• 旧版 Codex 模型引用属于旧版配置，doctor 会将其重写为 openai/<model>。
• Provider/model agentRuntime.id: "openclaw" 在 OpenClaw 上显式保留其他符合条件的路由。 agentRuntime.id: "codex" 需要 Codex，并且当有效路由与 Codex- 不兼容时拒绝执行。

请参阅 OpenAI 隐式代理运行时 和 Codex 工具 。如果 provider/runtime 拆分令人困惑，请先阅读 Agent 运行时。

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

新的 OpenAI API-key 和 ChatGPT/Codex OAuth 设置选择标准 openai/gpt-6-astra 参考。裸直接 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 后端。