opencodex 的 OpenAI 单一 Codex 登录 Provider 化：codexAccountMode 迁移契约与 Pool/Direct 路由隔离实现解析

【免费下载链接】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点击查看免费下载导读本文围绕 opencodexUniversal provider proxy for OpenAI Codex Claude Code中一次重要的provider 契约重构展开项目把历史上公开的openai/openai-multi双 Codex 登录 provider 拆分收敛为唯一的openai内置 Codex 登录 provider并以持久化的providers.openai.codexAccountModepool | direct作为账户选择策略。文章依据 devlog/_fin/260717_openai_single_provider_option/010_core_contract.md 中的核心契约、迁移规则、路由边界与验证矩阵结合仓库源码逐一还原其实现细节。读完本文你将掌握codexAccountMode的 schema 校验与默认语义、v1→v2 配置迁移含.pre-openai-tiers-v2.bak备份的完整规则、Pool主登录 附加账户轮换与 Direct仅主登录短路在路由/认证/配额/侧车各链路上的隔离边界以及该契约对应的测试矩阵与验收标准。一、背景从「三 provider 拆分」到「单 provider 账户模式」在本次重构之前仓库中面向 Codex 登录的 OpenAI provider 采用「三层」布局openaiCodex Direct、openai-multiCodex Multi可管理多个附加 Codex 账户、openai-apikey纯 API Key 路由。这种结构的问题在于openai-multi作为可路由、可配置的公开 provider id会让同一套 Codex 登录能力在注册表、预置、初始化配置、模型目录和侧车候选中反复出现两份容易造成路由分支分裂与术语混乱如「provider tier」「Codex Multi-account」等表述。本次重构的核心决策来自 000_plan.md 的 User decision record是openai-multi被移除为公开/可配置的 provider 与模型命名空间仅保留为迁移期遗留 idLEGACY_OPENAI_MULTI_PROVIDER_ID。所有裸原生 OpenAI 模型 id 的账户选择统一由providers.openai.codexAccountMode决定。默认值为pool且主登录main login作为普通合格成员参与轮换。direct仅使用主登录绝不触碰账户亲和性、附加账户凭据、池配额、冷却、健康或 active-account 状态。openai-apikey及其八个模型的目录、Pro 虚拟别名、密钥池所有权、selected-id 保留与 wire 重写完全不变。锁定契约可以概括为一张表公开 provider id选中模型身份凭据归属账户规则可变设置openai裸 id如gpt-5.6-sol按模式由 Codex 登录/账户存储提供pool轮换主登录 附加账户direct仅用调用方/主登录codexAccountMode默认poolopenai-apikey命名空间 id如openai-apikey/gpt-5.6-sol、...-pro仅配置的 API Key 或活跃密钥池条目永不读取 Codex 账户永不接收 Codex 登录兜底不变关键不变量裸 OpenAI 家族模型只经启用的openai路由绝不静默落入openai-apikeypool与direct是同一个 canonical forward 传输openai-responsesadapter、https://chatgpt.com/backend-api/codexbase URL、authMode: forward的两种模式而不是两组 base URL 或 auth 模式。二、类型层codexAccountMode 落地与版本标记提升契约首先落在类型定义上。当前实现中模式类型与版本常量定义于 src/types/wire.ts// src/types/wire.ts export type CodexAccountMode direct | pool; export const OPENAI_PROVIDER_TIER_VERSION 2 as const;CodexAccountMode direct | pool维持两个合法值不引入第三/回退状态——这是本契约刻意为之任何非法值都应在 schema 层失败而不是在运行时悄悄退化为某种模式。OPENAI_PROVIDER_TIER_VERSION从 1 提升到 2作为「OpenAI provider-contract 迁移标记」配置键名openaiProviderTierVersion为磁盘向后兼容而保留原名。OcxProviderConfig上新增codexAccountMode?: CodexAccountMode位于authMode之旁仅在 canonical 内置openaiforward provider 上合法缺失时默认pool。从源码结构看类型导出经由 src/types.ts 汇集export type { UpstreamHttpVersion, ReasoningSummaryDelivery, CodexAccountMode } from ./types/wire与OPENAI_PROVIDER_TIER_VERSION的再导出使配置、路由、认证模块可以共享同一套契约。三、配置层schema 校验、superRefine 拒绝规则与默认值3.1 模式字段的 schema 约束在 src/config/schema/config-schema.ts 中providerConfigSchema扩展了codexAccountMode: z.enum([pool, direct]).optional()使非法字符串在 schema 解析时直接失败而不是经.passthrough()泄漏到运行时。configSchema.openaiProviderTierVersion改为接受字面量1 | 2见该文件第 161 行z.union([z.literal(1), z.literal(2)]).optional()保证 v1 旧配置在迁移前仍可解析、可启动。3.2 superRefine 的归属限制schema.superRefine阶段强制执行两条归属规则见 src/config/schema/config-schema.ts 第 617 行附近除 canonicalopenai外的每个provider 都不允许携带codexAccountMode报错路径[providers, name, codexAccountMode]消息为codexAccountMode is valid only on the canonical built-in openai provideropenai上若 adapter/base URL/auth 模式不是内置 forward 形状同样拒绝该字段。同时旧openai-multi行在标记缺失或为 1 时必须保持可解析以便启动迁移migrate而非直接丢弃配置——即「可迁移不可悬空」。3.3 默认值getDefaultConfig().providers.openai携带codexAccountMode: pool保证全新安装即进入 Pool 默认而mergeConfigDefaults的 provider 合并行为保持不变——运行时解析器仍然会把一个手工编写、缺省模式的openai行在下次保存前默认为pool因此「手写最简配置」也能符合新默认。四、迁移引擎projectOpenAiTierMigration 的纯函数投影迁移是本次重构中最重要的工程部件它由 src/providers/openai-tiers.ts 中的projectOpenAiTierMigration(config)承担该文件保留「tier」命名仅为了向后兼容。4.1 常量重命名把遗留 id 关进笼子模块顶部重新导出来自openai-tiers-destinationOPENAI_CODEX_PROVIDER_IDopenai原OPENAI_DIRECT_PROVIDER_ID更名LEGACY_OPENAI_MULTI_PROVIDER_IDopenai-multi原OPENAI_MULTI_PROVIDER_ID更名——除迁移模块外任何非迁移模块不得再导入旧常量名OPENAI_API_PROVIDER_ID与LEGACY_CHATGPT_PROVIDER_ID值不变。canonicalCodexForwardProvider(mode)现在接受一个模式参数并返回完整 canonical 传输加codexAccountModefunction canonicalCodexForwardProvider(mode: CodexAccountMode): OcxProviderConfig { return { adapter: openai-responses, baseUrl: CODEX_FORWARD_BASE_URL, authMode: forward, codexAccountMode: mode, }; }而isCanonicalOpenAiForwardProvider保持传输聚焦接受任一合法模式但拒绝 key auth、自定义 base URL、query/fragment 凭据或其他 adapter。4.2 投影的有序规则对照 000_plan 的十条投影是纯函数且有序的实现细节如下structuredClone(config)克隆输入绝不修改调用方状态。校验providers[openai-multi]managedLegacyMultiOverlay允许集仅为adapter、authMode、baseUrl、disabled、selectedModels、modelCosts非 canonical 行直接抛OpenAiTierMigrationCollisionError不保存、不备份因为携带密钥/自定义形状的配置不能被静默丢弃。模式解析resolvedOpenAiMode显式合法的providers.openai.codexAccountMode优先否则启用的遗留openai-multi行、defaultProvider openai-multi或已知openai-multi/引用 →poolv1 下仅有历史 Direct 的openai→direct保留先前显式行为未标记/全新配置 → 默认pool。仅在配置确实引用 Codex-forward 面时保证一个 canonicalopenai行审计回折 A1marker 1 且既无openai也无openai-multi时保留缺席、不复活已删除的 provider仅禁用的 Multi 行则吸收进openai模式pool并保留disabled: true。mergeLegacyOpenAiProviderRows合并selectedModels先 canonical 后遗留去重、稳定顺序modelCosts键经rewriteLegacyOpenAiCostKeys重写后合并bare 键优先。删除providers[openai-multi]与providers.chatgpt遗留默认映射到defaultProvider: openai。rewriteLegacyOpenAiReferences将openai-multi/model精确改写为裸model覆盖disabledModels、subagentModels、injectionModel、shadowCallIntercept.model、webSearchSidecar.model、visionSidecar.model、claudeCode.webSearchSidecar.model、claudeCode.visionSidecar.model、claudeCode.model、claudeCode.smallFastModel、claudeCode.tierModels.{opus,sonnet,haiku,fable}以及modelMap的 DESTINATION 值绝不重写 source 键。providerContextCaps[openai-multi]移入providerContextCaps.openai两者并存时取更低的正值上限并产生仅含路径的 warningproviderContextCaps.openai providerContextCaps.openai-multi: kept lower positive cap。去重且保留首次出现顺序不重写openai-apikey/...、自定义 provider id、用量历史与请求日志。写openaiProviderTierVersion: 2对已是 marker 2 的 canonical 单 provider 配置二次投影changed: false、克隆相同、无警告幂等。值得强调的安全边界源码unknownLegacyOpenAiWarnings投影只按已知路径白名单isKnownLegacyValuePath重写未知 passthrough 字段中出现的openai-multi只产生路径级 warningpath: legacy OpenAI provider id left unchanged绝不递归改写任意字符串——因为 passthrough 配置里允许出现 provider 密钥和自由格式 prompt。4.3 备份v2 快照与字节级安全backupConfigBeforeOpenAiTierMigration泛化为~/.opencodex/config.json.pre-openai-tiers-v2.bak见 src/config/openai-tier-backup.ts保留 v1 备份只读、绝不覆盖/改名/删除——v1 备份恢复的是「三 provider」之前的旧状态v2 备份恢复的是本次反转之前的即时状态字节一致的既有 v2 备份直接复用不一致的既有 v2 备份构成硬冲突保存前中止维持 mode 0600、Windows ACL 加固、回滚与密钥残留错误处理OpenAiTierBackupIO语义不变。4.4 启动边界src/providers/openai-tier-startup.ts 的runOpenAiTierStartupMigration保持服务器启动边界严格顺序为project → backup → save仅当changed true冲突或幂等输入时零备份/零保存。保存成功后projection.warnings才逐条以仅含路径的console.warn输出——持久化成功之前不告警。五、路由层单一 openai 选择与 API 命名空间的隔离src/router.ts 是本契约的语义执行点移除OPENAI_MULTI_PROVIDER_ID与三元素OPENAI_TIER_ORDER不再存在「多 provider 顺序选择」。routeResult中调用providerCodexAccountMode(providerName, provider)显式direct优先缺失模式默认pool。routeModel的isBareOpenAiFamilyModel分支只选择启用状态的openai若缺失或禁用则抛NoEnabledOpenAiProviderError原NoEnabledOpenAiTierError更名——绝不回落openai-apikey见 src/router.ts 第 495 行类定义与第 659/667/795 行抛点。显式openai-apikey/model保持原routeResult路径不携带codexAccountMode。显式openai-multi/model迁移后不再匹配走正常 no-provider 错误没有运行时兼容别名——兼容性是一次性的配置/模型 id 重写而非永久第二条路由。providerCodexAccountMode实现在 src/providers/registry.ts 第 210–216 行附近注册表模式仅作为缺省来源持久化的 provider 值优先调用方在解析运行时/DTO 模式时必须传入 provider 对象。六、认证层Direct 短路边界与 Pool 引擎所有权src/codex/auth-context.ts 的resolveCodexAuthContext把 Direct 分支放在第一优先位置构成「direct-pin 边界」if (mode direct) { if (!hasCallerCodexBearer(headers)) throw new CodexDirectAuthenticationError(); return { kind: main, accountId: null }; }该分支必须先于读取x-codex-parent-thread-id、调用resolveCodexAccountForThreadDetailed、读取配额、检查冷却、导入primeCodexPoolQuotas、读取getMainAccountToken或调用getValidCodexToken——即任何池状态查找或池状态变更之前。CodexDirectAuthenticationError类定义见该文件第 431 行。Pool 分支是唯一调用resolveCodexAccountForThreadDetailed的分支继续产出main-pool主登录与pool附加凭据两种身份applyCodexAuthContextToProvider受mode pool保护Direct 永不收到_codexAccountOverride或_codexAccountRequiredheadersForCodexAuthContext对kind: main转发调用方 headers仅对pool/main-pool替换认证。用户可见文案从「Codex Multi-account」更名为「OpenAI account pool」。src/codex/routing.ts 的选择算法被复用而非重设计getEligiblePoolAccounts含MAIN_CODEX_ACCOUNT_ID、线程亲和性处理、applyQuotaAutoSwitch、applyFailureFailover、recordCodexUpstreamOutcome语义不变formatCodexProviderForLog(providerName, accountId, config)让 Pool 请求聚合在openai或附加账户的openai-safe-label下永不再出现openai-multi日志身份。Direct 模式绝不从resolveCodexAuthContext进入该模块——认证上下文分支是唯一的所有权边界。七、配额、启动预载、用量标签与侧车模式感知的收尾链路模式感知同样贯彻到配额与预热链路避免 Direct 意外触碰附加账户存储src/providers/quota.tsisBuiltInChatGptForwardProvider识别 canonicalopenai而非遗留 MultimaybeFetchProviderQuota返回单个openai报告键。审计回折 A3 要求listCodexAuthAccountssrc/codex/auth-api.ts 第 353 行附近会读取/刷新每个附加账户因此Direct 模式配额路径必须只解析主账户、不触碰附加账户存储配额缓存键需包含解析后的模式且管理模式 PATCH 必须失效该缓存避免 Direct 下显示过期的 Pool 报告。src/codex/auth-api.tsprimeCodexPoolQuotas的判定从config.providers[OPENAI_MULTI_PROVIDER_ID]改为「canonical 启用的openai且解析模式为pool」Direct 模式在 WHAM 抓取、池账户迭代、primeInFlight创建之前即返回。src/oauth/token-guardian.tsguardian 预热从内部 idchatgpt改键为 canonicalopenai并模式感知——Pool 预热主登录 附加账户Direct 只预热主登录、绝不迭代附加账户存储。src/providers/label.ts 与 src/usage/summary.tsbaseProviderLabel增加读时 canonicalization历史openai-multi及 safe 账户标签变体映射到openai使迁移前的 Pool 用量与迁移后按同一身份合并用量与请求日志文件永不改写openai-apikey行保持独立。src/providers/openai-sidecar.tsOpenAiForwardSidecarCandidate.providerName收窄为OPENAI_CODEX_PROVIDER_IDlistOpenAiForwardSidecarCandidates只读config.providers.openaicanonical 且启用时返回恰好一个候选其accountMode取自providerCodexAccountMode(openai, provider)。Direct 要求调用方 bearerPool 可注入选中的主/附加凭据selectOpenAiImagesProvider保持独立 keyed 候选池认证失败归池自身不静默改计费到 API Key。八、管理面与 GUI无重启的模式切换管理模式 DTO 与 GUI 在本契约下保持一致详见 020_surfaces.mdsrc/server/auth-cors.tscodexAccountMode从FORBIDDEN_PROVIDER_RUNTIME_FIELDS移除它现在是持久化配置而非运行时元数据providerManagementConfigError拒绝向chatgpt/openai-multiPOSTopenai必须等于 canonical 注册表种子仅codexAccountMode可为pool | direct自定义 provider 与openai-apikey不可携带该字段safeConfigDTO通过providerCodexAccountMode(name, provider)输出解析后的模式。src/server/management-api.tsPATCH /api/providers只接受两个互斥操作——{ disabled: true }或{ codexAccountMode: direct | pool }模式 patch 写新 provider 对象保留全部安全 overlay→saveConfig(config)→clearThreadAccountMap()防止后续切回 Pool 复用旧策略下的亲和性→ 切到 Pool 时 best-effortprimeCodexPoolQuotas(config, mode-change)Direct 不预热→ 返回{ success: true, name: openai, codexAccountMode }。不刷新模型目录、不重启、不 drain 服务器下一轮直接从活动配置对象读取新模式。GUI 侧gui/src/codex-multi-state.ts、gui/src/pages/Providers.tsx、gui/src/pages/CodexAuth.tsx、gui/src/pages/Models.tsx 等codexAccountModeState(config)以Object.hasOwn判定absent / disabled / direct / pool畸形值保守回落absentProviders 页对openai卡渲染可访问的 Pool/Directradiogroup控件并即时 PATCHModels 页保持一个openai裸 id 分组i18n 四语言en/ko/de/zh同步新增prov.openaiMode*、codexAuth.accountMode*等键并删除全部 Multi 相关旧键。九、测试矩阵与验收如何证明迁移正确与模式隔离9.1 迁移投影矩阵必须逐条覆盖010_core_contract.md 定义了完整的「输入 → 输出」矩阵核心用例包括输入结果未标记的最简openai单个 canonicalopenai、显式pool、marker 2未标记的chatgpt含/不含附加账户单个 canonicalopenai、pool、隐藏chatgpt、无瞬时 Multimarker 1、仅 Direct 的openai单个openai、direct、marker 2marker 1、启用的openai-multi单个openai、pool、遗留行移除marker 1、默认openai-multi默认映射openai、模式poolmarker 1、禁用 Multi 启用 Direct 且无 Multi 引用单个启用openai、模式directmarker 1、openai与openai-multi均缺席A1保留缺席——不创建openaimarker 2marker 1、仅禁用 Multi无openai行A1单个openai、pool、保留disabled: truemarker 1、仅 Direct 过期activeCodexAccountIdA1单个openai、direct过期 active id 清除或忽略定义并测试marker 1、无 provider 过期池状态A1保留缺席池状态不动claudeCode.model/smallFastModel/tierModels.*/modelMap含 Multi idA2精确裸 id 重写modelMap源键绝不重写两行均含selectedModels稳定并集、无重复双 provider 上下文上限取更低正上限于openai仅路径 warningdisabledModels/subagentModels含命名空间 Multi id裸 id、稳定顺序、去重injection/shadow/全局侧车/Claude 侧车模型引用精确裸 id 重写canonical 行 未知 passthrough 路径含 Multi id已知路径迁移、未知路径保留、仅路径 warning非 canonical/含密钥的 Multi 行冲突、输入不变、无备份/保存marker 2 canonical 结果changed: false、深等克隆、无 warning恢复 v2 备份marker 1/旧拆分可解析下次启动重现相同 marker-2 字节仅字节一致时复用备份9.2 激活场景C-ACTIVATION-GROUNDING-01场景 A缺省模式默认 Pool 并轮换到非主合格账户providers.openai无codexAccountMode字段 可用主令牌 一个可用附加账户凭据 主配额高于autoSwitchThreshold、附加账户配额低于阈值 初始activeCodexAccountId为主账户。POST 裸gpt-5.6-sol后上游应收到附加账户 bearer/account id、配置 active id 变为该账户、选中/wire 模型保持裸 id且 route/log/catalog 中不出现openai-multi字符串。缺省解析为 direct 或池引擎未激活即判失败。场景 B显式 Direct 绝不触碰池状态codexAccountMode: direct 有效调用方 bearer 已填充的附加账户存储/active id/配额/冷却/重认证/线程亲和状态。发送 HTTP、compact 与一次 Responses WebSocket 裸模型回合后所有池快照哈希与 active id 必须不变、不产生配额预热抓取、即使所有池账户不可用请求仍成功。测试要求Direct 分支一旦移动到 thread-id、配额、冷却、main-pool-token 或账户存储解析之后即失败通过管理模式 PATCH 设置模式时基线快照须在 PATCH 完成之后采集PATCH 本身会保存配置并清空亲和性。9.3 验收命令与最终结果聚焦核心套件迁移/路由/认证/目录/配额/侧车bun test --isolate \ tests/openai-provider-option.test.ts \ tests/openai-provider-option-migration.test.ts \ tests/openai-provider-option-startup.test.ts \ tests/router.test.ts \ tests/codex-routing.test.ts \ tests/server-auth.test.ts \ tests/codex-catalog.test.ts \ tests/codex-quota-prime.test.ts \ tests/provider-quota.test.ts \ tests/server-images.test.ts \ tests/server-search.test.ts验收标准Cycle 1 acceptance注册表/预置/初始化不再暴露openai-multi全新/缺省openai解析 Pool、显式 direct 解析 Directv1 拆分迁移为单行 v2 备份 幂等 marker 2全部已知 selected-id 侧车位置改写为裸 id裸 id 永不凭据回退openai-apikeyPool 在配额压力下可验证地轮换主 附加账户Direct 可验证地保持所有池状态不变原生目录无命名空间 Multi 重复、API 行/别名/元数据不变。实现与验证的最终证据记录在该单元的 closeout 中010_core_contract.md 与 000_plan.md 收据Cycle 1 落地于提交4da9c167、Cycle 2 落地于14e57661聚焦超集 309 pass / 0 fail全库隔离套件 2,850 pass / 0 fail12,188 断言、256 文件隔离运行时验证了 Pool 轮换、Direct 隔离、API Pro 身份、真实 Codex 客户端历史与用户状态哈希不变127.0.0.1:10100活跃代理监听器身份在前后均为 PID 17423 且字节一致全程零控制操作。存储扫描确认openai-multi仅存在于迁移实现、历史与拒绝语义上下文中活动 README/docs-site/structure 匹配数为 0。十、迁移兼容性要点与实操注意升级路径携带 marker 1或未标记的既有配置会在下次启动时被投影为 marker 2先写入config.json.pre-openai-tiers-v2.bak0600no-replace.pre-openai-tiers-v1.bak保持只读历史。手动编写配置缺省codexAccountMode的openai行在运行时解析为pool若要在管理写路径上显式设置必须写pool或direct之一非法值在 schema 层即被拒绝。不要为裸模型配置openai-apikey兜底裸 OpenAI 家族模型只走启用的openaiAPI Key 路由必须显式使用openai-apikey/model命名空间。Direct 的语义边界direct是「仅当前/主 Codex 登录」它与 Pool 共享同一 forward 传输只是不查询、不预热、不轮换任何池状态切回 Pool 前亲和性映射已被 PATCH 清空新回合重新进入正常的配额/亲和性选择。用量归并迁移前的 Pool 用量历史openai-multi行在读时归一到openai身份与迁移后合并展示文件本身不被改写。结语codexAccountMode契约把「多个 Codex 登录 provider」重构为「一个 provider、两种账户模式」是 opencodex 在配置面、迁移面、路由面、认证面、配额面与 GUI 面的一次系统性收敛。从 src/types/wire.ts 的类型常量、src/config/schema/config-schema.ts 的严格校验、src/providers/openai-tiers.ts 的纯投影迁移到 src/router.ts 的单 provider 路由与 src/codex/auth-context.ts 的 Direct 短路边界每一层都有明确的源码实现与测试矩阵背书。读者可沿文中所列路径直接深入源码或继续阅读同目录的 000_plan.md规划与决策、020_surfaces.md管理面/GUI与 030_verification_closeout.md集成与验证获取完整闭环。赞分享【免费下载链接】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点击查看免费下载相关推荐ZeroTierOne Windows 构建与本地联调指南从 MSBuild 编译到双会话测试ZeroTierOne Windows 构建与本地联调指南从 MSBuild 编译到双会话测试 ZeroTierOne 在 Windows 平台上的工程代码集opencodex 原生 Codex 路由模型目录规约Phase 100 实现指南opencodex 原生 Codex 路由模型目录规约Phase 100 实现指南 opencodex 作为 OpenAI Codex 与 Claude CoOpenCodex 维护实录codex-rs Realtime 与 Subagent 契约研究及 devlog _plan → _fin 归档清扫单元OpenCodex 维护实录codex rs Realtime 与 Subagent 契约研究及 devlog _plan → _fin 归档清扫单元 本文基上一篇Laravel Livewire 终极指南10个技巧快速构建动态应用下一篇Oh my tmux!在Windows WSL中的完美部署指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考