企业官网建设流程全解析

导读

本文围绕 opencodex（Universal provider proxy for OpenAI Codex & Claude Code）中一次重要的provider 契约重构展开：项目把历史上公开的openai/openai-multi双 Codex 登录 provider 拆分，收敛为唯一的openai内置 Codex 登录 provider，并以持久化的providers.openai.codexAccountMode（"pool" | "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 采用「三层」布局：openai（Codex Direct）、openai-multi（Codex Multi，可管理多个附加 Codex 账户）、openai-apikey（纯 API Key 路由）。这种结构的问题在于：openai-multi作为可路由、可配置的公开 provider id，会让同一套 Codex 登录能力在注册表、预置、初始化配置、模型目录和侧车候选中反复出现两份，容易造成路由分支分裂与术语混乱（如「provider tier」「Codex Multi-account」等表述）。

本次重构的核心决策（来自 000_plan.md 的 User decision record）是：

1. openai-multi被移除为公开/可配置的 provider 与模型命名空间，仅保留为迁移期遗留 id（LEGACY_OPENAI_MULTI_PROVIDER_ID）。
2. 所有裸原生 OpenAI 模型 id 的账户选择统一由providers.openai.codexAccountMode决定。
3. 默认值为"pool"，且主登录（main login）作为普通合格成员参与轮换。
4. "direct"仅使用主登录，绝不触碰账户亲和性、附加账户凭据、池配额、冷却、健康或 active-account 状态。
5. openai-apikey及其八个模型的目录、Pro 虚拟别名、密钥池所有权、selected-id 保留与 wire 重写完全不变。

锁定契约可以概括为一张表：

关键不变量：裸 OpenAI 家族模型只经启用的openai路由，绝不静默落入openai-apikey；pool与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 provider）；
• openai上若 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-destination）：

• OPENAI_CODEX_PROVIDER_ID（"openai"，原OPENAI_DIRECT_PROVIDER_ID更名）；
• LEGACY_OPENAI_MULTI_PROVIDER_ID（"openai-multi"，原OPENAI_MULTI_PROVIDER_ID更名——除迁移模块外，任何非迁移模块不得再导入旧常量名）；
• OPENAI_API_PROVIDER_ID与LEGACY_CHATGPT_PROVIDER_ID值不变。

canonicalCodexForwardProvider(mode)现在接受一个模式参数并返回完整 canonical 传输加codexAccountMode：

function 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 的十条）

投影是纯函数且有序的，实现细节如下：

1. structuredClone(config)克隆输入，绝不修改调用方状态。
2. 校验providers["openai-multi"]：managedLegacyMultiOverlay允许集仅为adapter、authMode、baseUrl、disabled、selectedModels、modelCosts；非 canonical 行直接抛OpenAiTierMigrationCollisionError（不保存、不备份），因为携带密钥/自定义形状的配置不能被静默丢弃。
3. 模式解析（resolvedOpenAiMode）：
   • 显式合法的providers.openai.codexAccountMode优先；
   • 否则，启用的遗留openai-multi行、defaultProvider === "openai-multi"或已知openai-multi/引用 →pool；
   • v1 下仅有历史 Direct 的openai→direct（保留先前显式行为）；
   • 未标记/全新配置 → 默认pool。
4. 仅在配置确实引用 Codex-forward 面时保证一个 canonicalopenai行（审计回折 A1）：marker 1 且既无openai也无openai-multi时保留缺席、不复活已删除的 provider；仅禁用的 Multi 行则吸收进openai（模式pool）并保留disabled: true。
5. mergeLegacyOpenAiProviderRows合并selectedModels（先 canonical 后遗留，去重、稳定顺序）；modelCosts键经rewriteLegacyOpenAiCostKeys重写后合并（bare 键优先）。
6. 删除providers["openai-multi"]与providers.chatgpt；遗留默认映射到defaultProvider: "openai"。
7. 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 键）。
8. providerContextCaps["openai-multi"]移入providerContextCaps.openai；两者并存时取更低的正值上限并产生仅含路径的 warning（providerContextCaps.openai + providerContextCaps.openai-multi: kept lower positive cap）。
9. 去重且保留首次出现顺序；不重写openai-apikey/...、自定义 provider id、用量历史与请求日志。
10. 写openaiProviderTierVersion: 2；对已是 marker 2 的 canonical 单 provider 配置，二次投影changed: false、克隆相同、无警告（幂等）。

值得强调的安全边界（源码unknownLegacyOpenAiWarnings）：投影只按已知路径白名单（isKnownLegacyValuePath）重写；未知 passthrough 字段中出现的openai-multi只产生路径级 warning（<path>: 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或_codexAccountRequired；headersForCodexAuthContext对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.ts：isBuiltInChatGptForwardProvider识别 canonicalopenai而非遗留 Multi；maybeFetchProviderQuota返回单个openai报告键。审计回折 A3 要求：listCodexAuthAccounts（src/codex/auth-api.ts 第 353 行附近）会读取/刷新每个附加账户，因此Direct 模式配额路径必须只解析主账户、不触碰附加账户存储；配额缓存键需包含解析后的模式，且管理模式 PATCH 必须失效该缓存，避免 Direct 下显示过期的 Pool 报告。
• src/codex/auth-api.ts：primeCodexPoolQuotas的判定从config.providers[OPENAI_MULTI_PROVIDER_ID]改为「canonical 启用的openai且解析模式为pool」；Direct 模式在 WHAM 抓取、池账户迭代、primeInFlight创建之前即返回。
• src/oauth/token-guardian.ts：guardian 预热从内部 idchatgpt改键为 canonicalopenai并模式感知——Pool 预热主登录 + 附加账户；Direct 只预热主登录、绝不迭代附加账户存储。
• src/providers/label.ts 与 src/usage/summary.ts：baseProviderLabel增加读时 canonicalization，历史openai-multi（及 safe 账户标签变体）映射到openai，使迁移前的 Pool 用量与迁移后按同一身份合并；用量与请求日志文件永不改写，openai-apikey行保持独立。
• src/providers/openai-sidecar.ts：OpenAiForwardSidecarCandidate.providerName收窄为OPENAI_CODEX_PROVIDER_ID；listOpenAiForwardSidecarCandidates只读config.providers.openai，canonical 且启用时返回恰好一个候选，其accountMode取自providerCodexAccountMode("openai", provider)。Direct 要求调用方 bearer；Pool 可注入选中的主/附加凭据；selectOpenAiImagesProvider保持独立 keyed 候选，池认证失败归池自身，不静默改计费到 API Key。

八、管理面与 GUI：无重启的模式切换

管理模式 DTO 与 GUI 在本契约下保持一致（详见 020_surfaces.md）：

• src/server/auth-cors.ts：codexAccountMode从FORBIDDEN_PROVIDER_RUNTIME_FIELDS移除（它现在是持久化配置而非运行时元数据）；providerManagementConfigError拒绝向chatgpt/openai-multiPOST，openai必须等于 canonical 注册表种子（仅codexAccountMode可为"pool" | "direct"），自定义 provider 与openai-apikey不可携带该字段；safeConfigDTO通过providerCodexAccountMode(name, provider)输出解析后的模式。
• src/server/management-api.ts：PATCH /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，畸形值保守回落absent；Providers 页对openai卡渲染可访问的 Pool/Directradiogroup控件并即时 PATCH；Models 页保持一个openai裸 id 分组；i18n 四语言（en/ko/de/zh）同步新增prov.openaiMode*、codexAuth.accountMode*等键并删除全部 Multi 相关旧键。

九、测试矩阵与验收：如何证明迁移正确与模式隔离

9.1 迁移投影矩阵（必须逐条覆盖）

010_core_contract.md 定义了完整的「输入 → 输出」矩阵，核心用例包括：

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 解析 Direct；v1 拆分迁移为单行 + v2 备份 + 幂等 marker 2；全部已知 selected-id 侧车位置改写为裸 id；裸 id 永不凭据回退openai-apikey；Pool 在配额压力下可验证地轮换主 + 附加账户；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 fail（12,188 断言、256 文件）；隔离运行时验证了 Pool 轮换、Direct 隔离、API Pro 身份、真实 Codex 客户端历史与用户状态哈希不变；127.0.0.1:10100活跃代理监听器身份在前后均为 PID 17423 且字节一致，全程零控制操作。存储扫描确认openai-multi仅存在于迁移实现、历史与拒绝语义上下文中，活动 README/docs-site/structure 匹配数为 0。

十、迁移兼容性要点与实操注意

1. 升级路径：携带 marker 1（或未标记）的既有配置会在下次启动时被投影为 marker 2，先写入config.json.pre-openai-tiers-v2.bak（0600，no-replace）；.pre-openai-tiers-v1.bak保持只读历史。
2. 手动编写配置：缺省codexAccountMode的openai行在运行时解析为pool；若要在管理写路径上显式设置，必须写"pool"或"direct"之一，非法值在 schema 层即被拒绝。
3. 不要为裸模型配置openai-apikey兜底：裸 OpenAI 家族模型只走启用的openai；API Key 路由必须显式使用openai-apikey/<model>命名空间。
4. Direct 的语义边界：direct是「仅当前/主 Codex 登录」，它与 Pool 共享同一 forward 传输，只是不查询、不预热、不轮换任何池状态；切回 Pool 前亲和性映射已被 PATCH 清空，新回合重新进入正常的配额/亲和性选择。
5. 用量归并：迁移前的 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（集成与验证）获取完整闭环。