【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址https://gitcode.com/gh_mirrors/ope/opencodex点击查看免费下载本篇技术指南聚焦 opencodex 在接入 grok-buildGrok 侧grokCLI 的构建版 harness时的关键兼容性问题pinnedasync-openaifork 将 Responses 协议的input_tokens_details/output_tokens_details定义为 required 字段而 opencodex 桥接层此前会在上游未上报缓存/推理 token 时省略这些明细导致调用方在response.completed之后硬性反序列化失败。读完本文你将掌握 opencodex 的responsesUsage()与chatCompletionsUsage()双编码器零默认值归一化的实现原理、本地冒烟验证方法以及 Grok 侧[model_providers.opencodex]复用块与/v1/models目录联动的推荐配置。一、背景一次只读源码分析 fold-in 的判定结论devlog/_fin/260723_grok_build_bridge/001_sol_source_analysis.md记录了 Sol(medium) 子代理对grok-build a5727c5树位于180_grok-buildSOURCE_REV30192d2eef5d的只读源码分析。核心判定可归纳为五条Responses usage details 是强制字段non-Optionpinnedasync-openaiforkrev95b52ebd的ResponseUsage将input_tokens_details/output_tokens_details定义为 required struct无#[serde(default)]嵌套字段cached_tokens、reasoning_tokens同样是 required。Chat Completions 客户端相对宽松chunk 的usage是 Optionaldetails 也是 Optional嵌套字段走 zero-default见xai-grok-sampling-types/src/types.rs:535-587。system 消息在 chat 后端按正常 role 发送conversation.rs:1781-1784——ocx chat 入站将其折叠为 instructions因此不构成问题。目录抓取在 loopback 场景下也无豁免、必须带 Bearerremote/client.rs:686-738空 key 报No API key for custom models endpoint返回{data:[...]}形状id 取自model|modelIdbegin▁of▁sentence- id|_meta.*context_window缺失时默认 256k。新增配置面[model_providers.id]复用块 [model.id]上的auth_provider动态 Bearer 助手后端枚举保持 3 种chat_completions为默认。custom-models 指南11-custom-models.md在旧/新 revision 下 blob 相同契约未变。这条分析的意义在于Grok 侧三个后端/新配置面无论选用哪一个只要 ocx 在桥接时省略 usage details就会触发严格客户端的硬失败。这是一个发生在响应已经完成之后的反序列化错误形态上表现为整轮 turn 以非零退出码收场。二、根因拆解required 的ResponseUsage结构问题源头不在 opencodex 本身而在 grok-build 锁定的async-openaifork 对 Responses 事件的结构定义。该 fork 中ResponseUsage把input_tokens_details、output_tokens_details声明为无#[serde(default)]的 required struct且嵌套的cached_tokens、reasoning_tokens也非可选。这意味着反序列化器在解析response.completed事件时若 usage 对象里缺少任一 details 键整条事件流都会报错。涉及的位置文档记录位于 grok-build 源码树非本仓库crates/codegen/xai-grok-sampler/src/client.rs:99-129——SSE 反序列化入口失败时抛SamplingErrorcrates/codegen/xai-grok-sampler/src/stream/responses.rs:319-327, 482-488——流式 Responses 事件的解析路径。对比之下同一仓的 Chat Completions 采样器xai-grok-sampling-types/src/types.rs:535-587对 chunkusage、details 及嵌套字段全部放宽为 Optional / zero-default。这种两套客户端严苛度不一致的现状正是下文双编码器修复的出发点。三、本地冒烟交叉验证raw_data 的决定性证据主 agent 于 2026-07-23 的本地冒烟给出决定性证据/tmp/grok-smoke-chat.err中的 raw_dataFailed to deserialize ResponseStreamEvent … missing field input_tokens_details raw_data{type:response.completed, … usage:{input_tokens:0,output_tokens:22,total_tokens:22}}三个关键观察即便显式设置api_backend chat_completionsocx-chatcursor/grok-4.5的实际 wire 仍是 Responses 事件并在反序列化时失败。grok 0.2.101 harness 在这一 turn 走了 Responses 客户端——即 harness 内部存在与配置无关的路径强制使用 Responses 词汇表精确触发条件列为残留调查项。原生gpt-5.4-mini退出码为 0ChatGPT 上游总是携带 detailsocx 原样保留反序列化自然通过。routed 场景死亡的原因ocx 的src/bridge.tsresponsesUsage()在上游未上报 cached/reasoning 时省略了*_tokens_details。由此收敛出修复方向无论 Grok 侧走哪条后端路径只要 ocx 恒定输出 usage details整个矩阵native / chat / routed即可全部打通。wp1 必须同时覆盖两个编码器详见下一节。四、收敛结论responsesUsage()与chatCompletionsUsage()双编码器修复结合 Sol 建议chat 默认桥接与本地冒烟事实上强制 Responses 路径修复需覆盖两处4.1src/bridge.ts的responsesUsage()src/bridge/internal.ts中responsesUsage()internal.ts实现了details 恒常输出、缺省补零的归一化input_tokens_details.cached_tokens恒常存在上游无值时为 0output_tokens_details.reasoning_tokens恒常存在无值时为 0usage 整体为 undefined 时默认返回对象也包含两者。cached_tokens只承载 cache 读与 OpenAI 语义一致并钳制在inputTokens之内防止上游绝对 check-point 报出超过输入的 cache 读cache_write_tokens仅在cacheCreationInputTokens已知时按inputTokens - cacheRead的下界输出。来自上游的未知 usage 字段订阅元数据、未来计数器等按 openai/codex#41980 的对齐方式透传但cache_write_tokens只从归一化后的合法值发出绝不从 raw 复制未知形状。contextTotalTokens存在时inputTokens按contextTotalTokens - outputTokens拆算避免活跃上下文 check-point 被重复计入 output。这段逻辑被严格客户端契约直接引用——注释里明确写着pinned forkrev95b52ebd的response_usage.rs中InputTokenDetails/OutputTokenDetails均为非 Option省略它们会把一次成功 turn 变成response.completed之后的硬退出missing field input_tokens_details2026-07-23 实测复现。4.2src/chat/outbound.ts的chatCompletionsUsage()src/chat/outbound.ts的chatCompletionsUsage()outbound.ts做 Responses 内耗量到 Chat Completions 形状的换算prompt_tokens/completion_tokens/total_tokens之外prompt_tokens_details.cached_tokens与completion_tokens_details.reasoning_tokens也恒常输出。注释明确其动机grok 的 chat 客户端虽然对 details 是 Optional但为保持与responsesUsage()的对称性、并提前适配未来可能出现严格反序列化的客户端始终补齐。4.3 使用场景编码器与投递链responsesUsage()的调用面覆盖了所有对外出口保证任意出口的 usage 形状都一致sse.tscompleted/incomplete/failed各终止事件统一经responsesUsage()归一化后 emitadapter_eof的兜底response.incomplete甚至以responsesUsage(undefined)输出全零。client-encoder-delivery.ts投递终端按terminal.usageOnWire选择responsesUsage(terminal.usage)或 null。chat.ts 与 messages.tsChat Completions 与 Anthropic Messages 编码器在completed/incomplete终止时均走同一归一化。chatCompletionsUsage()则用于 Chat Completions 出口outbound.ts 的流式帧与 outbound.ts 的非流式响应体以及 chat.ts 的终止帧。五、Grok 侧新配置面[model_providers.opencodex]复用块文档将 Grok 0.2.109 之后可用的 provider 继承能力列为 wp2 文档化对象仓库内的 grok/inject.ts 印证了这一点Grok 0.2.1092026-07-21起[model_providers.id]上声明的base_url、api_backend、api_key、extra_headers会经由with_provider_defaults → resolve_model_list → sampling_config_for_model → SamplingClient链路应用到继承模型的路由。ocx 因此只发射一张共享的[model_providers.opencodex]表每个[model.*]通过model_provider引用它模型别名只做薄层追加。推荐配置形态一个块共享 base_url/backend逐模型加薄别名[model_providers.opencodex] name opencodex base_url http://127.0.0.1:10100/v1 api_backend chat_completions # 后端枚举 3 种之一chat_completions 为默认 api_key ocx admission key extra_headers { x-opencodex-grok 1 } [model.grok-4.5] model_provider opencodex name OCX grok-4.5值得注意的工程细节ocx 在 grok/inject.ts 中区分生成别名与人类手写条目——手写[model.x]表、人类自设的api_key、指向远程主机的 loopback base_url、或仅凭 loopback base_url 本身均不会被误判为 ocx 管理条目而清扫只有命中确定性生成别名形状chat_completionsname OCX modelx-opencodex-grok 1标记或model_provider opencodex继承形状的条目才归属管理块。api_backend在 enum 层面仍是三选一、chat_completions为默认auth_provider作为[model.id]上的动态 Bearer 助手出现二者共同构成新配置表面。六、模型目录联动GROK_MODELS_BASE_URL与 ocx/v1/models文档给出的目录联动方案GROK_MODELS_BASE_URLhttp://127.0.0.1:10100/v1 XAI_API_KEY任意非空值loopback 场景下 ocx 忽略 admission key因此XAI_API_KEY只需非空即可满足 grok 目录抓取的 Bearer 要求该抓取对 loopback 也无豁免。ocx 的/v1/models已经以{data:[{id,…}]}形状返回模型列表若 ocx 能按模型携带api_backend/context_window字段即可接近 zero-config文档标注为选择性的 out-of-scope 项。仓库侧确有对应基础server/models-capabilities.ts 把context_window/context_length/max_output_tokens镜像为每个模型行的顶层字段供 pi-ai、DSH、LibreChat 等只读扁平属性的外部客户端发现并针对grok-4.x与grok-build-latest提供 effort 阶梯minimal/low/medium/high/xhigh。这些模型行正是/v1/models响应的数据来源。七、可观测性零默认合成值与真实测量的区分零默认归一化带来一个副作用wire 上的cached_tokens: 0可能是合成值而非实测值。仓库在日志层对此做了明确隔离usage/log.ts严格客户端归一化会在每条桥接 wire 上输出 zero-default 明细对象responsesUsage因此从 wire 回读的cached_tokens: 0属于兼容性产物不是 cache miss 的测量结果observed/synthesized/unknown三类值在全链路保持独立避免池丢弃全部热前缀后仍报出看似合理的命中率#4546。request-log.ts桥接上报原始 adapter 用量时置usageFromBridge标记SSE/JSON 二次解析不得覆盖原始来源——合成的cached_tokens: 0不是实测 cache 读cache_detail_missing不得被静默吞掉。sse.tsresponsesUsage()在终止事件处总是输出 zero-default 明细因此 wire 不能作为 provenance 来源调用方需在logCtx.usage保留原始上报值。这一点对排障很重要当你在日志里看到cached_tokens: 0时需先确认它来自上游真实上报还是桥接合成避免把兼容性产物当成容量/缓存策略的测量依据。八、残留待办与适用前提grok 0.2.101 在api_backendchat_completionscustom model 上强制走 Responses wire 的精确触发条件config 解析harness goal-tracker 侧车尚未定位需在 wp1 验证时用 grok 调试日志复现确认。tool-call 往返冒烟划入 wp2本次 bridge 修复仅覆盖 usage 形状。适用前提本仓库内responsesUsage/chatCompletionsUsage的实现、[model_providers.opencodex]发射逻辑、/v1/models能力字段均以当前仓库为准grok-build 侧的行号与 fork rev 来自关联文档的只读分析记录。九、参考路径关联文档001_sol_source_analysis.md桥接归一化src/bridge/internal.tsChat 出口归一化src/chat/outbound.tsSSE 终止事件src/bridge/sse.tsGrok provider 继承注入src/grok/inject.ts模型目录能力字段src/server/models-capabilities.ts合成零值溯源隔离src/usage/log.ts、src/server/request-log.ts赞分享【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址https://gitcode.com/gh_mirrors/ope/opencodex点击查看免费下载相关推荐OpenCodex 与 Grok Build 桥接兼容实战usage token 明细常量化输出与严格 Responses 解码器适配OpenCodex 与 Grok Build 桥接兼容实战usage token 明细常量化输出与严格 Responses 解码器适配 导读 本文围绕 OpeOpenCodex 与 Grok Build 桥接Usage Token-Details 常时发射修复严格 Responses 客户端反序列化失败OpenCodex 与 Grok Build 桥接Usage Token Details 常时发射修复严格 Responses 客户端反序列化失败 导读 本文使用 Rube MCP 自动化 Storeganise 业务操作awesome-codex-skills 实战指南使用 Rube MCP 自动化 Storeganise 业务操作awesome codex skills 实战指南 本文基于 awesome codex sk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考