迁移前先承认一个现实：旧配置通常不干净

很多 Codex 接入并不是一开始就按团队标准做的。最初可能只是某个成员为了试用，临时填了一个 *ase **L，随手建了一枚 Key，再把配置截图发给同事。后来项目越用越多，配置慢慢进入真实开发、脚本检查、文档生成和问题排查流程。等你想切到新的 API 中转站时，才发现旧配置已经分散在多台电脑和多个文档里。

迁移最忌讳的动作，是直接覆盖旧配置。看起来省事，实际上没有回滚点。更稳的做法是把旧线路保留，把灵能API新线路作为独立配置接入，在同一台机器、同一套任务、同一个项目里逐步对比。确认稳定后，再通知团队分批切换。

• 旧配置可能散在 CC Switch、终端环境变量、CI Secret 和团队文档里。
• 迁移不是删除旧线路，而是先建立**证的新线路。
• 每次只改一项变量，才能知道问题来自哪里。

第一阶段：盘点旧配置在哪里

开始迁移前，先做一份旧配置清单。不要只问“现在谁能用”，而要问“现在有哪些地方正在用”。常见位置包括开发者本机的 CC Switch 配置卡、PowerShell 环境变量、项目 README、脚本模板、CI 平台 Secret、内部知识库和历史问题记录。

盘点时不需要收集完整 API Key，甚至不应该收集完整 Key。你只需要记录配置名称、用途、负责人、是否仍在使用、是否影响自动化任务。敏感值仍保留在原安全位置里，迁移清单只记录元信息。

盘点项：
配置名称：旧-Codex-日常开发
所在位置：成员 A 的 CC Switch
用途：本地代码解释和排错
负责人：成员 A
是否仍在使用：是
迁移风险：低，先复制新卡验证

配置名称：旧-Codex-CI-检查
所在位置：CI Secret
用途：合并前只读检查
负责人：项目负责人
是否仍在使用：是
迁移风险：中，需要单独灰度

• 盘点清单写用途和位置，不写完整密钥。
• 自动化配置要单独标记，不能和个人配置混在一起。
• 没人认领的旧配置先不要删除，等确认无依赖后再处理。

第二阶段：从灵能API确认新入口

迁移的新入口要从当前控制台获取。通过 https://www.lnsns.com/ 进入灵能API，确认账号、控制台入口、接入说明、可用模型和余额状态。不要从旧聊天记录复制地址，也不要用几个月前保存的截图作为依据。

这里要特别注意账号上下文。团队如果有多个账号，迁移时一定要确认新 Key、*ase **L、模型权限来自同一套灵能API账号。旧线路能跑通，不代表新账号具备相同模型权限；新入口能打开，也不代表所有项目都应该立刻切过去。

• 确认 *ase **L 来自当前控制台说明。
• 确认模型列表和旧配置里使用的模型是否能对应。
• 确认账户状态正常，再进行 CC Switch 配置。

第三阶段：不要改旧卡，先复制一张新卡

打开 CC Switch 后，先找到旧配置卡。不要直接覆盖旧卡里的字段，而是复制一张新卡，命名为“灵能API-Codex-迁移验证”。这张新卡只用于迁移测试，旧卡继续保留，确保新线路失败时可以立即切回。

新卡里先只替换灵能API相关字段：*ase **L、API Key、必要的模型 ID。其他参数保持旧配置一致。这样做的好处是变量更少，问题更容易定位。如果你同时换地址、换模型、换**、换提示词，一旦失败，就很难判断是哪一项造成的。

旧卡：Codex-旧线路-日常
状态：保留，不修改

新卡：灵能API-Codex-迁移验证
第一轮：只替换 *ase **L 和 API Key
第二轮：再核对模型 ID
第三轮：通过短任务后再进入真实项目

• 旧卡不动，迁移失败时可以立即切回。
• 新卡先只改中转站字段，不同时改多项。
• 新卡名称要写明迁移验证，避免被当成正式配置长期使用。

**阶段：核对新旧字段差异

新旧线路对比时，不要只看能不能返回。要逐项核对字段：*ase **L、接口兼容方式、模型 ID、Key 来源、**设置、超时策略、默认提示词和使用场景。尤其是模型 ID，旧配置里写的名称未必能在新入口下直接使用。

建议把字段差异写成一份迁移表。表里不**实密钥，只写字段来源和处理动作。例如 *ase **L 从灵能API当前控制台复制，API Key 由***新建并安全分发，模型 ID 由项目负责人确认。这样迁移不是某个人凭记忆完成，而是有记录可复查。

• *ase **L：确认入口和路径层级。
• API Key：确认是新建 Key，而不是旧 Key 继续沿用。
• Model ID：确认在新账号中可用。
• Proxy：确认终端**和浏览器**不是两套逻辑。

第五阶段：先跑空目录短任务

新线路配置好后，第一轮验证必须在空目录里做。不要直接拿真实项目做迁移测试，因为真实项目失败时变量太多：可能是读取范围大，可能是模型响应慢，可能是某个文件权限问题，也可能是新线路本身没有通。空目录短任务能把问题压缩到连接层。

mkdir codex-migration-check
cd codex-migration-check
codex "请只回复：迁移验证通过。不要创建、修改或删除文件。"

如果这一步失败，先不要进真实项目，也不要急着换模型。优先检查灵能API控制台入口、Key 是否复制完整、CC Switch 当前是否选中新卡、终端是否继承**、*ase **L 是否多写或少写路径。每次只改一项，改完重新跑同一条短任务。

• 短任务成功，说明基础链路可用。
• 短任务失败，先查配置，不查业务代码。
• 不要每次换一条提示词，否则验证结果不可对比。

第六阶段：真实项目只做只读验证

空目录通过后，第二轮才进入真实项目。这里依旧不建议让 Codex 直接改文件，而是做只读验证：读取 README、依赖文件、目录结构和少量核心源码，输出项目概览和后续检查建议。这样能确认新线路处理真实上下文的能力，同时把风险控制住。

如果项目很大，不要让 Codex 一次扫描全部目录。迁移验证阶段的目标不是全面**，而是确认新线路在真实项目中能稳定读取和回答。可以先选择一个低风险模块，例如工具函数、文档目录或测试目录。

推荐只读提示：
请只读取 README、依赖配置和 src 顶层目录，概括项目结构。
不要读取 .env、logs、*ackups、customer-**ta 目录。
不要创建、修改或删除文件。
输出分为：项目用途、主要模块、迁移后观察点。

• 真实项目第一轮只读，不写入。
• 先选低风险模块，不扫描全仓库。
• 输出里记录新线路响应速度和错误情况。

第七阶段：双线路并行观察，不要立刻停旧线路

新线路通过验证后，也不要马上停掉旧线路。建议保留一段观察期，让旧卡和新卡并行存在，但明确新卡优先使用、旧卡只用于回滚。观察期可以按项目节奏设定，比如三天、一周或一个迭代周期。

并行观察不是让大家随便切换，而是为了降低迁移风险。团队文档要写清楚：日常任务开始使用灵能API新卡，旧卡只在新卡连续失败且短任务无法通过时启用。每次切回旧卡都要记录原因，否则迁移状态会变得模糊。

观察期规则：
新卡：默认使用
旧卡：仅作回滚
切回条件：新卡连续失败 3 次，且排除本地变量错误
记录内容：时间、使用者、配置卡、错误码、处理动作

• 观察期要有明确开始和结束日期。
• 旧卡只作为回滚，不再作为日常默认配置。
• 每次回滚都要记录原因，避免长期停留在旧线路。

第八阶段：迁移 CI 和脚本时更要谨慎

个人本机迁移成功，不代表 CI 和脚本也能直接切换。自动化环境里可能有独立的 Secret、独立**、独立网络出口和不同的执行目录。把灵能API接入自动化任务时，建议单独创建 CI Key，并在非主发布流程里先跑预检。

迁移 CI 时，先增加一条独立任务，例如 codex-relay-migration-check。它只检查变量、连接和短任务，不影响原有构建流程。等这条任务稳定后，再把 Codex 分析任务切到新线路。不要在同一次提交里既换中转站，又改构建脚本，又改模型策略。

• CI 使用独立 Key，不混用个人 Key。
• 先新增迁移检查任务，再替换正式任务。
• 自动化迁移失败时，先停任务，不要无限重试。
• CI 日志不要打印完整 API Key 或完整请求头。

第九阶段：给回滚写一个明确开关

迁移方案没有回滚开关，就不算完整。个人本机可以通过 CC Switch 切回旧卡，CI 则应该有明确变量控制。例如 CODEX_RELAY_PROFILE=legacy 或 CODEX_RELAY_PROFILE=lingneng。这样出现异常时，不需要临时改代码，只改变量就能切换。

回滚不是失败，而是工程里的正常保护动作。真正的问题是回滚后没人追踪，旧线路继续长期使用。建议每次回滚都写明恢复条件：新卡短任务通过、真实项目只读验证通过、自动化任务连续两次正常，再切回灵能API新线路。

if ($env:CODEX_RELAY_PROFILE -eq "legacy") {
  Write-Host "当前使用旧线路，仅用于临时回滚"
}

if ($env:CODEX_RELAY_PROFILE -eq "lingneng") {
  Write-Host "当前使用灵能API新线路"
}

• 回滚要能快速执行，不依赖改代码。
• 回滚后要设恢复条件，不能无限期拖着。
• 旧线路停用前，确认没有成员和脚本仍在依赖。

第十阶段：迁移完成后归档旧配置

观察期结束后，如果灵能API新线路稳定，就可以开始归档旧配置。归档不是简单删除，而是先确认旧卡、旧 Key、旧文档、旧 CI 变量都不再被使用。确认后再停用旧 Key，更新团队文档，把旧配置标记为 deprecated。

建议保留迁移记录，内容包括迁移日期、负责人、旧配置名称、新配置名称、验证结果、回滚次数和最终停用时间。这些记录以后做问题复盘、人员交接或再次迁移时很有用。

• 旧 CC Switch 卡：标记 deprecated 后再删除。
• 旧 API Key：确认无依赖后停用。
• 旧文档：保留历史记录，但明显标注已过期。
• 旧 CI 变量：确认新任务稳定后再清理。

✅ 收尾：迁移要慢一点，后面才会快很多

Codex Claude中转或 API 中转站迁移，最稳的节奏不是一口气替换所有配置，而是先盘点、再复制、再验证、再灰度、再回收。灵能API提供新的统一入口，CC Switch保留新旧配置卡对照，团队文档记录每一步变化，这样迁移过程就不会靠记忆和运气。

如果你现在手里有一套旧 Codex 配置，建议先不要动它。通过灵能API建立新线路，用空目录短任务跑通，再进入真实项目只读验证，最后分批切换团队成员和自动化任务。迁移看起来多走了几步，但每一步都在为后续稳定性省时间。