CodexManager网关内幕：/v1/chat/completions与/v1/responses如何实现协议适配与SSE流式转换

【免费下载链接】Codex-Manager一个Codex cli 账号管理与切换工具。为 Codex cli提供本地网关转发。项目地址: https://gitcode.com/gh_mirrors/co/Codex-Manager

Codex-Manager（CodexManager）是一款面向 Codex CLI 的账号管理与切换工具，内置本地网关转发能力。它的网关同时受理 OpenAI 生态中最常用的两条接口：/v1/chat/completions（Chat Completions）与/v1/responses（Responses API）。两者请求结构、事件流格式完全不同，CodexManager 通过一套“协议适配 + SSE 流式转换”机制，让任意客户端都能透明接入上游 Codex 账号，这篇文章带你拆解它的实现内幕。

先搞懂问题：两条协议差在哪？

想理解网关的难度，先要清楚两套协议的“语言习惯”不同：

也就是说，即便客户端都发的是“流式请求”，Chat Completions 拿到的是块级 delta，而 Responses 拿到的是带事件名的语义流。网关要做的事，就是让两条链路在入口改写请求、在出口逐帧改写响应，做到客户端无感。

网关总架构：请求进来后走了哪些子模块

CodexManager 的网关实现集中在 crates/service/src/gateway/ 目录，官方协作文档把职责拆得很清晰，典型链路是：

1. request/：入站请求规范化与 chat/responses 请求改写
2. routing/：按模型目录 V2 选择候选账号与路由策略
3. auth/+upstream/：补全上游鉴权并发送请求
4. protocol_adapter/：产出内部统一请求结构与响应适配标记
5. observability/：写入 trace、请求日志与指标

其中决定“这条响应该怎么做适配”的核心是 protocol_adapter/types.rs 中的ResponseAdapter枚举，它定义了网关支持的全部适配方向，包括Passthrough（原样透传）、ChatCompletionsFromResponses（Responses 流转 Chat Completions 流）、ResponsesFromAnthropicMessages、ImagesB64JsonFromResponses等——这正是文章标题里“协议适配”的代码级对应物。

/v1/chat/completions 入站改写：把“旧协议”翻译成 Responses

当客户端以 Chat Completions 协议接入、而上游链路是 Responses 时，请求体会先在 request_rewrite_chat_completions.rs 中完成结构化改写，关键动作包括：

• 角色映射：developer/system归一为system，assistant、tool保持，其余落入user
• 内容扁平化：Responses 的多段 content（input_text、input_image等）被展平为 Chat Completions 的字符串或image_url结构
• 流式判定：读取请求体中的stream字段，决定后续走 SSE 转换器还是 JSON 直出

配套的路径识别与字段白名单逻辑放在 request_rewrite_shared.rs，协议路由的总入口则是 protocol_adapter/request_router.rs 中的adapt_request_for_protocol。改写完成后，网关内部持有的是一份统一结构AdaptedGatewayRequest（path + body + 响应适配器 + 工具名还原映射），上游发出去的才是对应协议的原始报文。

/v1/responses 直通链路：能不动就不动

与 Chat Completions 需要“翻译”不同，/v1/responses是 Codex 官方链路，CodexManager 对它采取透传优先策略：

• 请求侧默认完全跟随客户端model字段，不做隐式改写（仅在显式转发规则、平台密钥强绑模型等明确配置下才替换）
• 流式响应由 stream_readers/openai_responses.rs 中的OpenAIResponsesPassthroughSseReader逐帧透传
• 唯一的“加工”是旁路收集 usage 与首响应耗时，供日志与计费使用

这种设计保证了 Codex CLI 官方体验不被网关“损耗”，而跨协议兼容只在确实需要时才发生。

SSE 流式转换核心：Responses 事件流 → Chat Completions 帧

真正体现工程功力的，是出口侧的ChatCompletionsFromResponsesSseReader，实现位于 stream_readers/chat_completions.rs。它的工作方式可以概括为“读一帧、翻译一帧、立刻下发”：

1. 帧泵驱动：底层的UpstreamSseFramePump从上游响应体中持续切出 SSE 帧，解析data:与event:行，[DONE]被识别为终止信号
2. 元数据记忆：首个带response的帧会被提取id、model、created_at，并顺手合并 usage 到共享收集器，保证计费数据完整
3. 状态机去重：读者内部维护emitted_assistant_role、emitted_text、emitted_tool_call_indices等状态，确保choices[0].delta.role只发一次、工具调用按索引顺序聚合 arguments 片段，不会把 Responses 的语义事件“原样泄漏”给 Chat Completions 客户端
4. 流保护：配合公共模块 stream_readers/common.rs 提供首响应计时、流空闲超时判定与 keepalive 帧，慢首字时下游不会被挂死

非流式场景则由 http_bridge 的 body_conversion.rs 完成整包 JSON 的结构转换；错误体统一由 compact_errors.rs 收敛，客户端看到始终是标准 OpenAI 错误格式。

可观测性：每一次适配都留痕

协议转换最怕“出了问题查不到”，因此 observability/request_log.rs 会把每条请求的入站路径、适配方向、账号命中、token 用量与耗时写入请求日志；metrics.rs 则汇总成面板趋势。网关侧还保留了与官方 Codex 请求头/参数的逐项对照文档，方便排查兼容性问题：

• docs/zh-CN/report/当前网关与Codex官方请求参数对照表.md
• docs/zh-CN/report/当前网关与Codex请求头和参数差异表.md
• docs/zh-CN/ARCHITECTURE.md

关键文件速查表

小结：网关价值的本质是“翻译层”

CodexManager 网关的设计哲学可以总结为三点：入站先归一、上游能透传就透传、出口按客户端协议逐帧回译。/v1/responses链路追求零损耗直通，/v1/chat/completions链路靠请求改写与 SSE 状态机实现无损兼容，两条链路共用同一套路由、鉴权与可观测性底座。理解了这套协议适配与 SSE 流式转换机制，你也就理解了它为什么能让 Codex 账号同时服务 Chat Completions、Responses、Anthropic 乃至图像等多类客户端。

【免费下载链接】Codex-Manager一个Codex cli 账号管理与切换工具。为 Codex cli提供本地网关转发。项目地址: https://gitcode.com/gh_mirrors/co/Codex-Manager