Codex 的多模型适配方案
Codex 的多模型适配方案
学习目标
- 理解 Codex 的 ModelProvider trait 抽象和具体实现
- 掌握 Codex 的多种认证策略和自动刷新机制
- 分析 Codex 的传输层重试和故障转移策略
前置知识
本章涉及多模型适配的通用原理，建议先阅读：
下文假设你已理解上述概念，直接聚焦 Codex 的具体实现。
项目实践
ModelProvider 抽象层
model-provider/src/provider.rs 定义核心 trait：
pub trait ModelProvider: fmt::Debug + Send + Sync { fn info(&self) -> &ModelProviderInfo; fn capabilities(&self) -> ProviderCapabilities; fn auth_manager(&self) -> Option<Arc<AuthManager>>; async fn auth(&self) -> Option<CodexAuth>; async fn api_provider(&self) -> Result<Provider>; async fn runtime_base_url(&self) -> Result<Option<String>>; async fn api_auth(&self) -> Result<SharedAuthProvider>;}工厂路由（create_model_provider()）：
AmazonBedrockModelProvider：AWS SigV4 签名ConfiguredModelProvider：通用 OpenAI 兼容端点（含 ollama/lmstudio）
认证系统
login/src/auth/manager.rs 的 CodexAuth 枚举：
pub enum CodexAuth { ApiKey(ApiKeyAuth), Chatgpt(ChatgptAuth), // OAuth + refresh_token ChatgptAuthTokens(ChatgptAuthTokens), // 外部传入的 bearer token AgentIdentity(AgentIdentityAuth), // JWT + Ed25519 签名}认证恢复状态机（UnauthorizedRecovery）：
- 遇到 401/403 时触发
- 步骤：CheckRefreshToken → RefreshToken → Reauth → Fail
expected_account_id防止账户切换
传输层实现
codex-api/src/endpoint/ 目录包含三种传输：
| 传输 | 文件 | 用途 |
|---|---|---|
| HTTP/SSE | responses.rs | 标准流式请求 |
| WebSocket | responses_websocket.rs | 低延迟场景 |
| WebRTC | realtime_call.rs | 实时语音/视频 |
统一抽象（codex-api/src/transport.rs）：
#[async_trait]pub trait HttpTransport: Send + Sync { async fn execute(&self, req: Request) -> Result<Response, TransportError>; async fn stream( &self, req: Request ) -> Result<StreamResponse, TransportError>;}重试策略
codex-client/src/retry.rs：
pub fn backoff(base: Duration, attempt: u64) -> Duration { let exp = 2u64.saturating_pow(attempt as u32 - 1); let raw = base.as_millis() as u64 * exp; let jitter = rand::rng().random_range(0.9..1.1); Duration::from_millis((raw as f64 * jitter) as u64)}- 指数退避 + 0.9-1.1x 随机抖动
- 可重试状态码：429、5xx
- 集成 OpenTelemetry 追踪
本地模型支持
Ollama（ollama/src/lib.rs）：
- 健康探测：
probe_server - 模型拉取：
pull_model_stream - 版本检查：
fetch_version
LM Studio（lmstudio/src/lib.rs）：
- 类似 Ollama 的本地模型管理
- OpenAI 兼容 API 端点
问题与规避
认证过期
Codex 的双路径刷新：
- 预刷新：token 过期前主动刷新
- 后刷新：请求失败后自动刷新并重试
- 持久化：刷新后立即写回磁盘
流式响应超时
Codex 的配置：
- 连接超时：建立连接的最大等待
- 读取超时：两次数据包之间的最大间隔
- 流式请求不设总超时，避免长回复被中断
设计取舍
为什么统一走 Responses API 协议？
Codex 移除了 Chat API 支持，所有提供商统一走 OpenAI Responses API。优势是：
- 代码简洁，无需维护两套协议逻辑
- 新功能（如工具调用、图像生成）在 Responses API 中更完整
代价是限制了与仅支持 Chat API 的提供商的兼容性。
为什么支持 WebRTC？
Codex 除了 HTTP/SSE 和 WebSocket，还支持 WebRTC 实时 API。这是为了：
- 支持语音/视频交互场景
- 降低实时通信的延迟
- 与 OpenAI 的 Realtime API 对齐
代价是增加了传输层的复杂度，WebRTC 的 NAT 穿透和信号交换需要额外处理。