读懂 Codex（5.1）：ModelInfo、ProviderInfo 与 Provider Capabilities

模型名称不能决定一次请求怎样发送。Codex 把“模型会什么”和“服务端怎样连接”拆成两份目录数据，再在请求点按能力门控字段；否则换一个兼容服务地址就会意外改变工具、推理或传输语义。

具体问题与启用条件

本节只解决能力事实从哪里来、谁负责校验，以及它们怎样限制后续分支。模型目录的刷新合并在 5.2，真正建立连接在 5.3 以后。

条件来源	决定字段或状态	对本机制的影响
模型目录	`ModelInfo` 中的 reasoning、tools、modalities、Lite 等字段	决定模型可见能力和请求字段
Provider 配置	`wire_api`、`supports_websockets`、认证与超时	决定地址、认证和传输
组合校验	AWS 认证与 WebSocket/其他认证互斥	非法组合在发请求前失败

协议、类型与状态所有权

状态或协议	所有者	生命周期	关键不变量
`ModelInfo`	ModelsManager	目录快照，可被远端覆盖	只描述模型，不携带连接凭据
`ModelProviderInfo`	有效配置	Codex Session	连接参数与认证来源保持同一 Provider
Capability gate	调用点	一次请求或 Step	缺能力时省略字段或选择替代路径

机制调用链如下：

配置与模型目录
→ ProviderInfo.validate()
→ ModelsManager 解析 ModelInfo
→ TurnContext 冻结所选模型
→ 请求编译器逐项读取 capability
→ 选择字段、工具和传输

ModelInfo 与 ProviderInfo 分别进入请求能力门控 — 图 5.1-1：模型能力和连接能力只有在请求点组合，不互相冒充。

机制怎样工作

ModelInfo 记录模型本身的行为合同：上下文窗口、默认与可选推理强度、是否支持推理摘要、详细度、并行工具、图片输入、Responses Lite 等。ModelProviderInfo 则记录线协议周边：Base URL、认证来源、附加 Header、请求与流重试预算、空闲超时以及 WebSocket 支持。二者不会合并成一个“万能配置对象”。

wire_api 在当前基线只接受 Responses；旧 chat 值会给出迁移错误，而不是悄悄走另一套协议。Provider 校验还拒绝 AWS 认证与 WebSocket、环境 Key、Bearer、命令认证或 OpenAI Auth 同时出现。真正发请求时再做细粒度能力判断，例如仅在模型支持时发送 verbosity，仅在 Provider 支持时选 WebSocket。

Python 风格伪代码

这段伪代码保留生产实现中会改变结果的状态、分支和异步边界；认证 SDK、遥测字段和 Rust 所有权样板被折叠为明确的领域对象。

@dataclass(frozen=True)
class ModelCapabilities:
    slug: str
    supports_reasoning_summary: bool
    supports_parallel_tools: bool
    use_responses_lite: bool
    context_window: int | None

@dataclass(frozen=True)
class ProviderContract:
    base_url: str
    wire_api: Literal["responses"]
    supports_websockets: bool
    auth: AuthStrategy

def resolve_route(model: ModelCapabilities, provider: ProviderContract) -> Route:
    provider.auth.validate_exclusive()
    return Route(
        transport="websocket" if provider.supports_websockets else "sse",
        dialect="responses_lite" if model.use_responses_lite else "responses",
        send_reasoning_summary=model.supports_reasoning_summary,
        parallel_tools=model.supports_parallel_tools,
    )

失败、取消与恢复

Provider 校验和模型能力门控的失败分支 — 图 5.1-2：非法 Provider 组合先失败；合法请求再逐项按能力选择字段。

故障或边界	已发生的状态	对上层的结果	能否直接重试	恢复动作
未知 `wire_api`	尚未联网	配置错误	否	改为 Responses Provider
认证策略冲突	尚未建立客户端	Provider 校验错误	否	只保留一条认证链
能力字段缺失	使用模型默认/保守值	相应请求字段被省略	是	刷新模型目录
错误地只看模型名	可能已构造错误请求	服务端 4xx	否	改为 capability gate

设计取舍与验证

分离模型与 Provider 增加了字段映射和组合测试，却允许同一个模型目录挂到不同网络与认证环境，也允许一个 Provider 承载多个能力不同的模型。把能力判断留在消费点的代价是分支分散；收益是每个字段都能明确回答“谁支持它”。

可验证契约	证据方式	预期结果
旧 Chat wire 值被拒绝	反序列化错误测试	返回带迁移提示的错误
AWS 认证组合互斥	Provider 校验测试	非法组合在网络前失败
自动压缩阈值不超过窗口 90%	ModelInfo 单元测试	过大阈值被钳制

Mini Codex 对照

Mini Codex 应保留两个不可变数据类和一次显式组合校验。可以省略 AWS、Azure 等认证变体，但不能把 supports_websockets、上下文窗口和模型输出能力推断自名字。

本节边界

这里证明的是能力与连接合同的分离。目录从本地、缓存和远端怎样合并，由 5.2 继续回答。