第5章：模型调用 —— 只说一种协议的客户端

第5章：模型调用 —— 只说一种协议的客户端

大部分 agent 框架把"支持多种模型 API"当卖点。Codex 走了相反的路：只支持一种 wire 协议，然后把省下的复杂度预算全部投到传输层和模型元数据上。本章拆这个取舍。

一、一个只有一个变体的枚举

先看这个 [源码 model-provider-info/src/lib.rs:64]：

pub enum WireApi {
    /// The Responses API exposed by OpenAI at `/v1/responses`.
    #[default]
    Responses,
}

一个枚举，一个变体。

这不是笔误。全仓库 grep -rn "chat_completions\|ChatCompletions\|chat/completions" --include=*.rs 的结果是零 [源码，实测]。Chat Completions 支持被完整移除了。

对比一下 Pi 教程第 4 章讲的"一行代码驾驭多个模型"——那是把不同 provider 的差异抹平在一个抽象层里。Codex 的选择是：差异不抹平，直接不支持。

那本地模型怎么办？

仓库里确实有 ollama 和 lmstudio 两个 crate，codex --oss 会拉起本地 Ollama 跑 gpt-oss:20b [源码 ollama/src/lib.rs:16]。它们走的是这些服务的 OpenAI 兼容端点——必须是 Responses 形态的兼容端点。这条路是"支持"，但显然不是一等公民。

为什么敢这么砍

两个原因：

1. Responses API 是有状态的。它支持 previous_response_id、服务端保存推理链、服务端压缩（第 7 章）。这些能力在 Chat Completions 里根本不存在。要用它们，就得放弃兼容
2. Codex 是 OpenAI 的产品。它没有"接入任意模型"的商业动机

这条判断不可无脑迁移 如果你在做的是一个需要接多家模型的产品，Codex 的做法就是错误示范。

但反过来的教训成立："支持所有模型"这个目标本身是有代价的——你只能用到所有 API 的交集能力。Codex 用放弃兼容换来的是服务端压缩、有状态会话、WebSocket 流式这些交集里没有的东西。第 7 章会看到这个交换值不值。

二、ModelClient 与 ModelClientSession：两层的必要性

模型调用被拆成两个对象 [源码 core/src/client.rs:256, 276]：

pub struct ModelClient {                    // 会话级，长生命周期
    state: Arc<ModelClientState>,
    agent_identity_policy: AgentIdentityAuthPolicy,
    prompt_cache_key_override: Option<String>,
    http_client_factory: HttpClientFactory,
}

pub struct ModelClientSession {             // 轮次级，一轮一个
    client: ModelClient,
    websocket_session: WebsocketSession,
    turn_state: Arc<OnceLock<String>>,
}

ModelClientSession 的文档注释把设计约束写得非常清楚，值得完整引用：

A turn-scoped streaming session created from a ModelClient. The session establishes a Responses WebSocket connection lazily and reuses it across multiple requests within the turn. It also caches per-turn state:

• The last full request, so subsequent calls can reuse incremental websocket request payloads only when the current request is an incremental extension of the previous one.
• The x-codex-turn-state sticky-routing token, which must be replayed for all requests within the same turn.

Create a fresh ModelClientSession for each Codex turn. Reusing it across turns would replay the previous turn's sticky-routing token into the next turn, which violates the client/server contract and can cause routing bugs.

三件事都很有信息量：

2.1 WebSocket 连接按轮复用

不是每次请求建连，也不是全程一条连接，而是一轮一条。因为一轮之内可能有多次采样（第 4 章：工具调用后模型继续），建连成本不该重复付。

2.2 增量请求

"只有当前请求是上一个请求的增量扩展时，才复用增量 websocket 请求载荷"——也就是说，第二次采样不用把整个历史重发一遍，只发新增的部分。

这对长会话是巨大的带宽和延迟节省。但它有个前提：连接得是同一条，服务端得记得上一次发了什么。这就是为什么要有 WebSocket，也是为什么要有下面这个。

2.3 粘性路由 token

/// This is an `OnceLock` that stores the turn state value received from the server
/// on turn start via the `x-codex-turn-state` response header. Once set, this value
/// should be sent back to the server in the `x-codex-turn-state` request header for
/// all subsequent requests within the same turn to maintain sticky routing.
///
/// This is a contract between the client and server: we receive it at turn start,
/// keep sending it unchanged between turn requests (e.g., for retries, incremental
/// appends, or continuation requests), and must not send it between different turns.
turn_state: Arc<OnceLock<String>>,

服务端是分布式的。一轮之内的多次请求必须打到同一个后端实例（否则增量状态就丢了），所以服务端在轮次开始时发一个 token，客户端后续原样带回。

用 OnceLock 而不是 Mutex<Option<String>> 是个恰当的类型选择：这个值一旦设定就不能改，类型系统直接保证了这一点。

可迁移的判断 ⑤ 把"会话级"和"轮次级"的客户端状态分成两个类型，并在文档里写清楚跨界复用会出什么问题。

注释里那句 "Reusing it across turns would replay the previous turn's sticky-routing token into the next turn, which violates the client/server contract and can cause routing bugs" 是典型的代价前置写法——它没有依赖 reviewer 记得这条规则，而是把违反后果写在了类型定义上。

三、传输层：WebSocket 优先，HTTP 兜底

stream() 的主体是一个降级链 [源码 core/src/client.rs:1878]：

pub async fn stream(&mut self, prompt: &Prompt, model_info: &ModelInfo, …) -> Result<ResponseStream> {
    let wire_api = self.client.state.provider.info().wire_api;
    match wire_api {
        WireApi::Responses => {
            if self.client.responses_websocket_enabled() {
                match self.stream_responses_websocket(…, /*warmup*/ false, …).await? {
                    WebsocketStreamOutcome::Stream(stream) => return Ok(stream),
                    WebsocketStreamOutcome::FallbackToHttp => {
                        self.try_switch_fallback_transport(session_telemetry, model_info);
                    }
                }
            }
            self.stream_responses_api(…).await     // HTTP SSE
        }
    }
}

降级是永久性的 [源码 core/src/client.rs:1935]：

Permanently disables WebSockets for this Codex session and resets WebSocket state. This is used after exhausting the provider retry budget, to force subsequent requests onto the HTTP transport.

一旦 WebSocket 用尽重试预算，整个会话余下时间都走 HTTP。不做反复试探——因为在一个用户面前反复卡顿比一直慢一点更糟。

预热

ModelClientSession 有两个预热方法 [源码 core/src/client.rs:1320, 1817]：

• preconnect_websocket —— 提前建连
• prewarm_websocket —— 带 warmup: true 标记发一次请求

配合 core/src/session_startup_prewarm.rs（会话启动时就把 base instructions 送过去预热），这套机制的目的是：用户敲下第一个字符之前，连接和 KV cache 都已经就绪。

这是纯粹的产品化投入，对架构没有贡献，但对"感觉快不快"贡献极大。dsh 教程里反复出现的"KV Cache 影响"视角，在 Codex 这里变成了具体的预热代码。

四、模型元数据：本章最大的发现

4.1 一个 424 KB 的 JSON

models-manager/models.json 是 424117 字节，内含 10 个模型的完整元数据 [源码，实测]：

注意最后一列：系统提示词是模型元数据的一个字段。

这是本教程认为 Codex 在架构上最值得注意的一个决定，第 6 章会展开讲它对上下文工程的意义。这里先说它对模型层的意义。

4.2 ModelInfo 有多少字段

ModelInfo 结构体有 40 多个字段 [源码 protocol/src/openai_models.rs:389]。分类看：

几个特别值得看的：

effective_context_window_percent —— 注释写道：

Percentage of the context window considered usable for inputs, after reserving headroom for system prompts, tool overhead, and model output.

（在为系统提示词、工具开销和模型输出预留余量后，认为可用于输入的上下文窗口百分比。）

上下文窗口不等于可用窗口。 这个显而易见但经常被忽略的事实，在这里被做成了一个可下发的参数。

auto_compact_token_limit 的计算逻辑很有意思 [源码 protocol/src/openai_models.rs:487]：

pub fn auto_compact_token_limit(&self) -> Option<i64> {
    let context_limit = self.resolved_context_window().map(|cw| (cw * 9) / 10);
    let config_limit = self.auto_compact_token_limit;
    if let Some(context_limit) = context_limit {
        return Some(config_limit.map_or(context_limit, |limit| std::cmp::min(limit, context_limit)));
    }
    config_limit
}

默认取上下文窗口的 90%，用户配置只能更严，不能更松（min）。这是一个防御性设计：用户把阈值配大了，系统不会跟着他跳崖。

comp_hash —— "Opaque identifier for compaction-compatible model configurations."（压缩兼容的模型配置的不透明标识符。）第 7 章会看到：模型切换时如果 comp_hash 变了，之前的压缩结果就不能复用了。

upgrade 带 migration_markdown 和退役时间 —— 模型的淘汰路径被写进了元数据，客户端可以直接把迁移说明展示给用户。

4.3 元数据是远程刷新的

models.json 只是 bundled 的兜底 [源码 models-manager/src/lib.rs:12]：

/// Load the bundled model catalog shipped with `codex-models-manager`.
pub fn bundled_models_response() -> Result<ModelsResponse, serde_json::Error> {
    serde_json::from_str(include_str!("../models.json"))
}

真正的目录从服务端拉，带完整的缓存语义 [源码 models-manager/src/cache.rs:63]：

pub struct ModelsCacheEntry {
    pub fetched_at: DateTime<Utc>,
    pub etag: Option<String>,
    pub client_version: Option<String>,
    pub models: Vec<ModelInfo>,
}

etag + TTL + client_version 三件套。client_version 尤其关键：同一个模型对不同版本的客户端可以下发不同的元数据——新客户端拿到新的工具集和新的提示词，老客户端拿到兼容版本。

可迁移的判断 ⑥ 把模型的能力、限制、提示词、工具偏好全部收进一份可远程刷新的元数据，而不是散在客户端代码的 match model_name 里。

这是本章最重要的一条。绝大多数 agent 项目的模型差异处理长这样：

text

if model.starts_with("gpt-4") { ... } else if model.contains("claude") { ... }

每加一个模型就改一次代码，每改一次就要发一次版本。Codex 的做法是把这些判断变成数据，改数据不改代码，改完立刻对所有已安装客户端生效。

对本仓的启示：如果我们的 AI 项目要同时支持多个模型，模型差异应该从第一天就设计成配置而不是分支。

五、Provider 配置：留给自定义的口子

虽然只支持 Responses 一种 wire 协议，ModelProviderInfo 还是留了相当完整的自定义空间 [源码 model-provider-info/src/lib.rs:96]：

两个细节：

① experimental_bearer_token 的注释是一句安全提醒：

Use of this config is discouraged in favor of env_key for security reasons, but this may be necessary when using this programmatically.

配置项本身就带着"别这么用"的说明。类型是 RedactedString——日志里不会打印出来。

② 重试次数有硬上限 [源码 model-provider-info/src/lib.rs:32]：

/// Hard cap for user-configured `stream_max_retries`.
/// Hard cap for user-configured `request_max_retries`.

用户可以调，但调不过天花板。和 auto_compact_token_limit 的 min 是同一种思路：给用户旋钮，但不给他打穿系统的权限。

六、错误分类与流式空闲超时

第 4 章讲过重试的分层。这里补充模型层的两个细节：

stream_idle_timeout_ms 的注释：

Idle timeout (in milliseconds) to wait for activity on a streaming response before treating the connection as lost.

（在把连接视为丢失之前，等待流式响应上出现活动的空闲超时。）

流式请求的"卡住"和"结束"在协议层没有区别——TCP 连接还在，就是不来数据。必须有一个客户端侧的空闲判定。这是所有做流式的人迟早会踩的坑（本仓 memory 里记的 aigateway.variflight.com 吊死问题，本质就是这个：成功 ~1s，失败不报错只吊死，而客户端没有空闲超时配置）。

ContextWindowExceeded 与 UsageLimitReached 被显式排除在重试之外（第 4 章已述）。后者还会顺手更新速率限制状态：

CodexErrorDetails::UsageLimitReached(e) => {
    if let Some(rate_limits) = e.rate_limits.clone() {
        sess.update_rate_limits(&turn_context, *rate_limits).await;
    }
    return Err(err);
}

错误响应里带的配额信息被提取出来喂给 UI，用户能看到自己还剩多少。这类细节决定了产品观感。

七、动手复核

cd codex/codex-rs

# 1. 确认只剩一种 wire 协议
grep -n 'pub enum WireApi' -A8 model-provider-info/src/lib.rs
grep -rn 'chat_completions\|ChatCompletions\|chat/completions' --include=*.rs . | grep -v '/tests/'
# ↑ 第二条应该没有输出

# 2. 两层客户端及其文档注释
sed -n '256,300p' core/src/client.rs

# 3. 传输降级链
sed -n '1878,1960p' core/src/client.rs

# 4. 模型目录
python3 - <<'PY'
import json
d = json.load(open('models-manager/models.json'))
for m in d['models']:
    mm = m.get('model_messages') or {}
    print(m['slug'], m.get('context_window'), len(mm.get('instructions_template') or ''))
PY

# 5. ModelInfo 的全部字段
sed -n '389,480p' protocol/src/openai_models.rs

# 6. 缓存语义
sed -n '60,100p' models-manager/src/cache.rs

八、总结

1. WireApi 只有一个变体：Chat Completions 被完整移除。放弃兼容换来了服务端压缩、有状态会话、WebSocket 增量请求这些"交集里没有的能力"
2. 客户端分两层：ModelClient 会话级、ModelClientSession 轮次级。粘性路由 token 用 OnceLock 保证只设一次，跨轮复用的后果写在文档注释里
3. WebSocket 优先、HTTP 兜底，降级是永久的——不在用户面前反复试探
4. 模型元数据是一份 424 KB 的可远程刷新目录，40+ 字段涵盖能力、限制、提示词、工具偏好、退役路径。client_version 让同一模型能对不同客户端版本下发不同配置
5. 给用户旋钮，但加硬上限：压缩阈值取 min、重试次数有 hard cap
6. effective_context_window_percent：上下文窗口不等于可用窗口，这件事被做成了参数

下一章接着这条线索往下：既然系统提示词是模型元数据的一个字段，Codex 的上下文到底是怎么装配出来的？

Related Documents

• 第4章-Agent-Loop-Task-Turn-Step三级循环
• 第6章-上下文工程-指令到底从哪来
• 第7章-上下文压缩-本地与远端两条路 —— 服务端压缩是砍掉兼容性换来的能力
• Pi 教程第 4 章 —— "抹平差异"的对照
• dsh 教程第 6 章 —— "provider 中立"的对照