【免费下载链接】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通用 provider 代理为 OpenAI Codex 与 Claude Code 提供统一 LLM 接入中 xAI/Grok 请求头对齐request-header parity的设计与落地展开聚焦该功能从架构决策、传输层实现、服务端 executor 接缝到端到端测试的完整链路。读完本文你将掌握如何为代理网关为上游厂商的私有请求头契约conv/session/req-id 三元组、User-Agent、OAuth 专属头实现诚实且可回滚的对齐方案以及如何在不破坏既有超时、重试与密钥轮换语义的前提下将自定义 fetch 执行器安全注入真实服务路径。背景为什么需要一个诚实的请求头契约当 opencodex 作为代理把 Codex CLI/App 与 Claude Code 的流量转发给 GrokxAI时上游服务端会根据一组 Grok CLI 私有请求头x-grok-conv-id、x-grok-session-id、x-grok-req-id等来识别会话、做缓存亲和affinity与请求去重。如果代理不发送这些头会话连续性、prompt 缓存命中率乃至请求去重都会退化如果代理伪造这些头例如编造并不存在的 agent ID、deployment ID、user ID则会在上游留下错误痕迹。本阶段devlog/_fin/260716_grok_build_hardening/050_header_parity.md的结论非常明确只发射请求作用域内诚实的官方 Grok 头子集——会话/对话身份在每个已解析传输resolved transport上只计算一次而每次调用的x-grok-req-id由该传输的 fetch 包装器生成。这一设计同时回答了哪些头要发、哪些头坚决不发、在哪里生成、如何不破坏超时语义四个问题。Header 决策表发送什么、省略什么这是整个方案的灵魂。官方 Grok 头契约被拆成三档Header决策x-grok-conv-idpromptCacheKey.trim()非空时取其稳定哈希SHA-256 前 32 位十六进制x-grok-session-id与 conv-id 相同的稳定不透明哈希省略规则一致x-grok-req-id每个 transport-fetch 调用内生成全新 UUIDv4调用方显式覆盖优先User-AgentOAuth 与 API-key 两种模式恒为opencodex-grok/${version}调用方覆盖优先x-grok-client-identifier、x-grok-client-version仅 OAuth 模式X-XAI-Token-Auth、x-authenticateresponse仅 OAuth 模式model override、agent ID、turn index、deployment ID、user ID、client mode一律省略OMIT——本地不存在可如实填写的值后者的省略并非偷懒而是原则opencodex 作为代理并不拥有这些身份字段的真实值编造它们会污染上游日志与计费归属。从当前源码 xai-transport.ts 的注释可以看到同样的表述Agent, deployment, model-override, turn, mode, and user identity headers are intentionally omitted because opencodex has no truthful values for the official fields.架构边界为什么不用 adapter fetchResponse而用服务端 executor 接缝这是文档中最关键的架构决策Round-3 ownership decision, R3-3不向createOpenAIChatAdapter增加fetchResponse钩子。原因来自服务端真实的调用拓扑服务端在 adapter-dispatch.ts 与 passthrough-dispatch.ts 中优先选用adapter.fetchResponse其回退路径才走fetchWithHeaderTimeout若把请求头发射塞进 adapter 钩子就会绕过fetchWithHeaderTimeout——该函数持有连接超时定时器与组合中止信号AbortSignal.any([abortSignal, timeout.signal])一旦被绕过xAI 接受连接但迟迟不返回响应头时请求可能无限挂起。因此 050 阶段的做法是给fetchWithHeaderTimeout增加一个可选 executor 参数默认globalThis.fetch所有真实服务调用方传入route.provider.fetch ?? globalThis.fetch。要求的调用链为server passthrough/ordinary/recovery/replay branch - fetchWithHeaderTimeout(url, init, upstream.signal, connectMs, parsed.stream, provider.fetch) - provider.fetch(url, { ...init, signal: AbortSignal.any([...]) }) - xAI wrapper generates x-grok-req-id and delegates to globalThis.fetch这样connectTimeoutMs的定时器、流式accept-encoding: identity语义、以及流身份编码语义全部原地保留。传输层实现src/providers/xai-transport.ts当前仓库中 xai-transport.ts 已经落地并演进。核心要素如下。兼容性常量与头名映射export const XAI_GROK_CLI_BASE_URL https://cli-chat-proxy.grok.com/v1; export const XAI_GROK_COMPATIBILITY { version: 0.2.93, userAgent: opencodex-grok/0.2.93, headers: { clientIdentifier: x-grok-client-identifier, clientVersion: x-grok-client-version, tokenAuth: x-xai-token-auth, authenticateResponse: x-authenticateresponse, conversationId: x-grok-conv-id, requestId: x-grok-req-id, sessionId: x-grok-session-id, userAgent: User-Agent, }, } as const;OAuth 模式独有的官方 CLI 头集中在XAI_GROK_CLI_HEADERSx-grok-client-identifier: opencodex、x-grok-client-version、x-xai-token-auth: xai-grok-cli、x-authenticateresponse: authenticate-response且 OAuth 模式的 baseUrl 会被强制替换为 Grok CLI 代理地址。稳定哈希deriveXaiConvIdexport function deriveXaiConvId(promptCacheKey: string): string { return createHash(sha256).update(promptCacheKey).digest(hex).slice(0, 32); }对话/会话亲和值取自promptCacheKey对应响应请求体中的prompt_cache_key是哈希而非原文——测试断言effective.headers[...]稳定跨请求、且绝不包含原始 session 字符串见 xai-transport.test.ts。哈希截断为 32 位十六进制避免把会话标识明文泄露给上游。resolveProviderTransport一次解析、稳定亲和、包装 fetchexport function resolveProviderTransport( providerName: string, provider: OcxProviderTransport, promptCacheKey?: string, ): OcxProviderTransport { if (providerName github-copilot) { return resolveGithubCopilotTransport(provider, apiBaseUrl); } if (providerName ! xai) return provider; const cacheKey promptCacheKey?.trim(); const affinity cacheKey ? deriveXaiConvId(cacheKey) : undefined; const stableDefaults: Recordstring, string { [XAI_GROK_COMPATIBILITY.headers.userAgent]: XAI_GROK_COMPATIBILITY.userAgent, ...(affinity ? { [XAI_GROK_COMPATIBILITY.headers.conversationId]: affinity, [XAI_GROK_COMPATIBILITY.headers.sessionId]: affinity, } : {}), ...(provider.authMode oauth ? XAI_GROK_CLI_HEADERS : {}), }; // ...合并用户覆盖、解析 configuredRequestId、构造 attemptFetch 包装器 }几个关键语义边界空白 promptCacheKey 完全省略 conv/session 头promptCacheKey?.trim()为空时affinity为undefined但 User-Agent 与 req-id 仍照常发送调用方覆盖优先且大小写不敏感withoutUserOverridden会剔除默认集中已被用户显式覆盖的键Headers.has保证大小写不敏感configuredRequestId从配置层提取用户钉死的 req-id即使服务端重建请求头也能保留生成时机UUID 生成在attemptFetch的调用体内而不是 resolve 时——这是每个逻辑请求一个 ID、避免 resolve 一次就复用同一 ID的关键。值得注意的是当前代码对 req-id 的语义已比原始设计文档更进一步源码注释明确Pin the request id per resolved transport ( per logical request until key rotation)xai-transport.ts即同目标 429 重放携带与首次派发相同的x-grok-req-id以便上游去重密钥轮换会解析出全新 transport从而获得全新 req-id。这解决了瞬时重试应携带同一 ID的字段语义而文档初版要求的每次调用全新 UUID由 transport 级别的每次逻辑请求一次解析来满足。服务端接缝fetchWithHeaderTimeout与 executor 注入文档中给出的fetchWithHeaderTimeout改造要点是新增可选executor: typeof globalThis.fetch globalThis.fetch参数定时器、header 变更、竞争与清理逻辑原样不动仅把内部fetch(...)替换为executor(...)export async function fetchWithHeaderTimeout( url: string, init: OmitRequestInit, signal, abortSignal: AbortSignal, timeoutMs: number, preferIdentityEncoding false, executor: typeof globalThis.fetch globalThis.fetch, ): PromiseResponse { const timeout new AbortController(); const timer setTimeout(() { if (!timeout.signal.aborted) timeout.abort(new DOMException(Timeout elapsed, TimeoutError)); }, timeoutMs); const headers new Headers(init.headers); if (preferIdentityEncoding !headers.has(accept-encoding)) { headers.set(accept-encoding, identity); } try { return await executor(url, { ...init, headers, signal: AbortSignal.any([abortSignal, timeout.signal]), }); } finally { clearTimeout(timer); } }在经历后续260701_server-ts-split重构后该函数现已位于 src/server/responses/fetch-helpers.ts并在默认 executor 之外还保留了流式preferIdentityEncoding的accept-encoding: identity注入与redirect: manual语义。服务端各真实调用方passthrough、ordinary、429/413 recovery、401 replay都必须以route.provider.fetch ?? globalThis.fetch作为最后一个参数恢复路径rebuildAndRefetch刻意在调用时刻读取可变的route.provider以保证 429 密钥轮换后立即使用轮换后的传输包装器绝不捕获轮换前的旧 executor。对 040 阶段落地的 replay 代码文档要求同样的最终参数应用到每一个新落地的重放 fetch并通过rg -n fetchWithHeaderTimeout审计保证没有遗漏的服务调用方。从当前调用方分布看该接缝已覆盖 request-transport.ts、adapter-dispatch.ts 与 passthrough-dispatch.ts 中的传输解析与重试路径。非 xAI provider 保持全局 fetch 行为不变因为resolveProviderTransport对非 xai/github-copilot 名称直接原样返回 provider。测试体系传输级快照 真实服务路径证明文档规划了两层测试且均已落地。传输级直测tests/providers/xai/xai-transport.test.ts该文件以Headers级别快照直接断言出站头覆盖OAuth 精确快照authorization: Bearer oauth-token、user-agent: opencodex-grok/0.2.93、x-grok-client-identifier: opencodex、x-grok-client-version、x-grok-conv-id/x-grok-session-id均等于deriveXaiConvId(codex-session-abc)、x-grok-req-id匹配 UUIDv4 正则且 OMIT 列表x-grok-model-override、x-grok-agent-id、x-grok-turn-idx、x-grok-deployment-id、x-grok-user-id、x-grok-client-mode全部不存在API-key 精确快照baseUrl 保持https://api.x.ai/v1不含任何 OAuth 专属头但 User-Agent 与 conv/session 亲和仍在同一 transport 多次调用conv/session 稳定req-id 在重放场景下保持一致、在新解析 transport 下刷新混合大小写调用方覆盖custom-agent/caller-id生效且无重复头空白 cache key省略 conv/session但保留 User-Agent 与全新 req-id。真实路径端到端tests/server/server-xai-header-parity.test.ts该文件遵循仓库既有的saveConfigstartServer(0) 隔离OPENCODEX_HOME约定helpers 见 isolated-codex-home.ts通过真实/v1/responses入口验证两次服务调用向 mock 上游连续 POST 两次携带同一prompt_cache_key断言两次 req-id 均为 UUIDv4 且互不相同、conv-id 均等于deriveXaiConvId(CONV_KEY)且两次一致悬挂响应头超时mock 上游接受请求但 handler 永不 resolve仅挂载 abort 监听connectTimeoutMs设为 25ms断言公开端点返回 502 且响应体包含Provider connect timeout after 25ms——这直接证明provider executor 仍处于超时竞争之内fetchWithHeaderTimeout的定时器没有被绕过。验收标准与风险防护文档列出的验收标准即实现的完成定义不新增 adapterfetchResponsesrc/adapters/openai-chat.ts保持不变fetchWithHeaderTimeout具备 executor 参数且每个服务调用方都传入当前 provider executor非 xAI provider 保持全局 fetch 行为xAI 传输 fetch 仅在fetchWithHeaderTimeout内部被调用其定时器、组合中止信号与流身份行为不变同一 resolved transport 的两次顺序调用req-id 语义符合上文约定、conv/session 相等真实/v1/responses两调用mock 上游可见不同 req-id 与稳定 conv-id对接受连接但不返回头的上游返回既有 connect-timeout 错误OAuth/API-key 精确快照均含 User-Agent所有 OMIT 断言成立空白 cache key 只省略 conv/session不省略 User-Agent/req-id用户覆盖在大小写不敏感前提下生效且无重复。风险与回滚设计同样清晰超时回归若把 provider fetch 放到fetchWithHeaderTimeout之外调用会丢失响应头截止时间——缓解手段正是真实服务路径的悬挂头测试轮换/重放后的陈旧 executor捕获旧 provider fetch 会丢失新密钥或新尝试状态——所有调用方读取当前route.provider.fetch尝试身份resolve 时生成 UUID 会导致复用包装器调用体内生成 同一 transport 两次调用测试可防此问题头兼容性精确 OAuth/API-key 快照可捕获意外伪造的或订阅专属头回滚撤销 050 实现提交即可executor 参数的默认值保证部分回滚期间调用方仍走全局 fetch且不写入任何持久化 schema 或状态。验证命令与现状说明文档规定的验证命令在仓库根目录执行bun test --isolate ./tests/providers/xai/xai-transport.test.ts bun test --isolate ./tests/server/server-xai-header-parity.test.ts bun test --isolate ./tests/server/server-xai-oauth-401-replay.test.ts bun run typecheck bun run test bun run privacy:scan实现记录2026-07-16 落地于1bf9de02之上表明当时新增了一行版本常量XAI_GROK_COMPATIBILITY、恒开出站 User-Agent、OAuth 专属官方兼容头、稳定哈希对话/会话亲和以及每个 resolved xAI transport fetch 调用内生成的 UUIDv4 req-idagent/deployment/model-override/turn/client-mode/user identity 等头保持省略。验证结果三个针对性测试文件 30 pass / 0 fail全套bun test --isolate ./tests/2628 pass / 0 fail246 个文件bun run typechecktsc --noEmit通过。需要留意的是本文档对应的代码此后经历了仓库的模块化演进文档中反复提到的src/server/responses.ts已按功能拆分为 fetch-helpers.ts、adapter-dispatch.ts、passthrough-dispatch.ts 与 request-transport.ts传输类型OcxProviderTransport也在 xai-transport.ts 本地声明fetch仅运行时使用、绝不持久化而非写进OcxProviderConfig。这些演进进一步印证了本文档的核心设计原则请求头对齐发生在传输包装层超时语义锚定在服务端 executor 接缝两者各司其职任何一方都不越界——这正是把上游私有头契约安全接入通用代理网关的可复用范本。赞分享【免费下载链接】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点击查看免费下载相关推荐Opik 项目 Jira Ticket 创建全流程指南从信息收集到 HOW 注释的标准工作流Opik 项目 Jira Ticket 创建全流程指南从信息收集到 HOW 注释的标准工作流 本文系统讲解 Opikcomet llm仓库中 AI AgeOpenCodex 上游连接超时统一实战Anthropic 原生透传 connectTimeoutMs 回退值从 120s 对齐到 200sOpenCodex 上游连接超时统一实战Anthropic 原生透传 connectTimeoutMs 回退值从 120s 对齐到 200s 本文基于 OpeAppium Header Handling 请求头处理指南使用 x-request-id 实现跨服务请求追踪Appium Header Handling 请求头处理指南使用 x request id 实现跨服务请求追踪 导读 本文以 Appium 官方文档 Head测试移动开发质量保障上一篇5分钟掌握RePKG轻松提取Wallpaper Engine壁纸资源下一篇Iwara视频下载终极方案5步告别手动下载烦恼创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考