vLLM 目前尚无法支持 Codex CLI：Responses API 兼容性问题的深度剖析与修复跟踪

vLLM 目前无法兼容新版 Codex CLI 的 Responses API，主要由于无法识别 developer 角色和工具定义格式。OpenAI 已全面迁移至 Responses API，不再支持旧版协议。社区通过 PR #41828 和 #43590 提出修复方案，将 developer 消息转换为 system 角色或合并到 instructions 字段，但仍需完善细节。建议开发者等待

lazyn

143人浏览 · 2026-05-25 22:07:35

lazyn · 2026-05-25 22:07:35 发布

vLLM 目前尚无法支持 Codex CLI：Responses API 兼容性问题的深度剖析与修复跟踪

引言
问题根源：`developer` 角色与 chat template 的冲突
社区反馈汇总
修复进展
结论与建议
参考来源

引言

在尝试将 vLLM 作为后端推理引擎部署本地大模型并与 Codex 集成时，触发 Unexpected message role 错误。这是因为 OpenAI 将 Codex CLI 全面迁移至 Responses API，版本 0.80.0 以上的新版 Codex CLI 已经全面采用 Responses API 协议，并且不再向后兼容旧的 Chat Completions API，而vLLM 当前的请求处理管线无法识别 Responses API 引入的 developer 角色导致工具调用、文件检索等功能完全无法使用。本文基于 vLLM 社区近期活跃的 Issues 与 Pull Requests，厘清问题的技术本质，并梳理修复工作的最新进展。

问题根源：`developer` 角色与 chat template 的冲突

OpenAI Responses API 在 input 消息数组中引入了 role: "developer" 这一新角色，用于承载工具声明、系统策略等结构化控制信息。Codex CLI 依赖该机制向模型传递代码上下文和可用工具列表。

vLLM 的非 harmony 路径在接收到请求后，会原样将 input 中的消息传入 chat template 进行渲染。而标准的 chat template 仅支持 system、user、assistant、tool 等固定角色集合，面对未预定义的 developer 角色时，模板引擎将抛出异常，导致整个请求失败。

此外，新版 Codex CLI 已彻底移除对旧版 Chat Completions API 的兼容支持，因此用户无法通过切换 API 协议来规避该问题。只要 vLLM 没有在内部完成角色转换，任何配置调整都无法使其正常工作。

社区反馈汇总

2026 年 5 月，相关讨论在 GitHub 上出现，反映出该问题的普遍性与紧迫性：

Issue #42407 直接询问 vLLM 对 Codex CLI 的官方支持版本。社区协作开发者明确回复，该能力需要尚未正式发布的更新版本。
Issue #42475 报告了在部署 Qwen3.6-27B-FP8 模型时的具体失败案例。日志分析表明，除 developer 角色外，Codex 还发送了 type: "namespace" 的工具定义（例如 FileSearchTool），并携带 vector_store_ids 等新参数，而 vLLM 当前的工具解析器仅能处理 type: "function" 的标准格式。这揭示了除角色不兼容外的第二层障碍。

修复进展

针对上述问题，社区已提交了两个关键 PR，均旨在实现 developer 角色的优雅降级。

PR #41828：将 `developer` 消息折叠至 `instructions`

该 PR 由 kdcyberdude 发起，标题为 [Responses API] Fold developer-role input messages into instructions。其核心设计如下：

在请求进入 chat template 之前，遍历 input 数组，提取所有 role: "developer" 消息的文本内容；
将提取出的文本追加到请求顶层的 instructions 字段末尾（以 \n\n 分隔）；
从 input 数组中移除这些 developer 消息，确保下游只能看到标准角色。

该方案在不修改 chat template 的前提下绕过了角色校验问题，为后续的规范化处理提供了基础。

PR #43590：角色映射与消息合并

在上一 PR 的基础上，chaunceyjiang 将 kdcyberdude 作为共同合作者，提交了 [Frontend][Responses API] Fold developer-role input messages into instructions，引入了更贴合 OpenAI 规范的转换策略：

将 developer 角色显式映射为 system 角色；
合并多条 system 消息为消息列表开头的单一条目，避免冗余；
增加了完整的单元测试，覆盖文本提取与合并逻辑。

该版本标志着修复从“绕过问题”向“语义对齐”的转变。

当前待解决的问题

代码评审指出，当前的规范化函数仍存在两个局限：

检查了标准 OpenAI 消息中并不存在的 type 字段，可能导致部分合法消息被错误跳过；
文本提取逻辑尚未兼容标准的 text 内容部分类型，有待后续 PR 完善。

这些细节不阻碍主干流程的验证，但需要在合并前修复，以确保对各类 Responses API 请求的广泛兼容性。

结论与建议

vLLM 当前版本无法直接支持 Codex CLI 的 Responses API，核心症结在于 developer 角色的缺失与工具解析的滞后。PR #41828 和 #43590 通过将 developer 消息转写为 system 角色的方式，已经走通了最关键的技术路径。然而，修复代码仍处于审查和打磨阶段，尚未合入任何正式发布分支。

对于计划在 vLLM 上使用 Codex CLI 的开发者，建议密切关注上述 PR 的合并动态。待相关补丁完成合并并通过版本发布后，再进行部署和集成。在此之间，强行对接将无法获得预期功能。