为什么要把 Codex 配置当成一项工程资产

在 Windows 上使用 Codex 接入 DeepSeek、Qwen 等国内模型时，很多教程只关注 API Key、模型名称和 API 地址是否填写正确。但真正影响稳定性的，往往是配置能否备份、切换、审计和回滚。

Codex 的配置通常由三部分组成：

config.toml  → 模型、供应商、地址和协议
环境变量     → API Key 等运行时凭证
cc-switch    → 多套配置的保存与切换

有些版本还会使用：

auth.json    → 登录状态或认证信息

因此，一套可维护的 Windows Codex 配置，应当满足四个条件：

1. 密钥不写入公开配置。
2. 每套模型都有明确用途。
3. 修改前可以恢复旧配置。
4. 发生 401、400、404 或协议错误时能够快速定位。

本文不讨论某个服务商是否一定可用，而是提供一套通用的配置管理方法。具体模型、字段和协议仍需以当前 Codex 版本及模型服务方说明为准。

先划分三类配置：稳定、测试和应急

不要让所有模型共用一份随时修改的配置。建议至少划分三种用途：

配置类型	用途	允许的操作
稳定配置	日常编码和代码审查	使用已经验证过的模型
测试配置	新模型、新地址或新协议测试	只在空白或脱敏项目中使用
应急配置	主模型故障时临时切换	只保留基础功能

例如可以在自己的记录中使用以下命名：

coding-stable
coding-lab
coding-fallback

名称只是管理标签，不代表 Codex 会自动识别这些名字。真正决定请求发往哪里的，是 model、model_provider 和对应的供应商配置段。

每套配置建议记录以下信息：

配置名称：
模型 ID：
供应商 ID：
API Base URL：
wire_api：
已验证能力：
最近验证时间：
已知限制：

API Key 不应出现在这份记录中。

Windows 先准备一套可复现的命令行环境

Codex CLI 依赖 Node.js 和 npm。可以先在 PowerShell 中执行：

node --version
npm --version

如果两个命令均能返回版本信息，再安装 Codex：

npm install -g @openai/codex

这里的 -g 表示全局安装。全局安装后，Codex 命令通常可以在不同项目目录中直接使用。

关闭当前终端，重新打开 PowerShell、CMD 或 Git Bash，然后验证：

codex --version

如果出现“找不到 codex 命令”，不要立即重复安装。先检查 npm 全局安装位置：

npm config get prefix
Get-Command codex

常见原因包括：

• npm 安装失败；
• npm 全局命令目录未加入 PATH；
• 安装后终端没有刷新；
• 安装和运行使用了不同的 Windows 用户；
• Git Bash、CMD 和 PowerShell 使用的进程环境不同。

Git Bash 不是 Codex 的强制依赖，但对习惯 Bash 命令的用户很方便。无论使用哪种终端，修改环境变量后都应关闭旧窗口并重新打开。

找准 .codex 目录，避免配置写到了“看不见的地方”

Codex 的用户级配置通常位于：

%USERPROFILE%\.codex

PowerShell 中可以查看当前用户目录：

$env:USERPROFILE

也可以检查配置文件是否存在：

Test-Path "$env:USERPROFILE\.codex\config.toml"

Windows 资源管理器可能隐藏文件扩展名，因此要特别注意以下错误：

config.toml.txt

这并不是 Codex 期望的配置文件名。

如果 .codex 目录不存在，是否可以直接创建，取决于当前 Codex 版本的配置规则。确认版本路径后，再创建目录和文件。不要因为网上某个旧教程使用了不同目录，就直接覆盖现有配置。

如果同时使用 Codex 桌面端、命令行和编辑器扩展，还要注意它们可能读取不同范围的配置。排错时应先确认当前实际运行的客户端。

用最小 config.toml 建立第一条可验证路由

第一次接入第三方模型时，建议从最小配置开始：

model = "YOUR_CODEX_MODEL"
model_provider = "custom_provider"

[model_providers.custom_provider]
name = "CustomProvider"
base_url = "https://example.invalid/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

https://example.invalid/v1 是不可用的占位地址，只用于展示格式。实际使用时必须替换成服务方提供的 API Base URL。

这段配置的关系是：

model
  ↓
model_provider
  ↓
model_providers.custom_provider
  ↓
base_url + env_key + wire_api

字段说明：

字段	含义
model	要调用的模型 ID
model_provider	当前使用的供应商 ID
name	供应商显示名称
base_url	API 基础地址
env_key	API Key 对应的环境变量名称
wire_api	请求协议类型

其中最容易出错的是 ID 对应关系：

model_provider = "custom_provider"

[model_providers.custom_provider]

两处必须完全一致，不能混用下划线、连字符或大小写。

model 也必须填写服务方实际公布的模型 ID。产品名称、宣传名称和 API 模型 ID 可能并不相同。

第一次验证时，不要同时加入大量高级参数。推理强度、响应存储策略、代理设置等字段是否可用，都可能受到 Codex 版本影响。最小配置成功后，再逐项增加。

把 API Key 放到运行时环境中

推荐让 config.toml 保存结构，让环境变量保存凭证。

PowerShell 中设置当前用户级环境变量：

[Environment]::SetEnvironmentVariable(
  'OPENAI_API_KEY',
  'YOUR_API_KEY',
  'User'
)

读取并验证：

[Environment]::GetEnvironmentVariable(
  'OPENAI_API_KEY',
  'User'
)

User 表示当前 Windows 用户范围。

如果只是临时测试，可以使用：

$env:OPENAI_API_KEY = 'YOUR_API_KEY'

两种方式区别如下：

方式	生命周期	适用场景
用户级环境变量	持久保存	日常使用
当前会话变量	关闭窗口后失效	临时排错

设置变量后，旧终端和已经启动的 Codex 通常不会自动获得新值。因此必须：

1. 关闭原来的 PowerShell、CMD 或 Git Bash。
2. 完全退出 Codex。
3. 重新打开终端或桌面程序。
4. 再进行测试。

验证输出中可能包含完整密钥，禁止截图、转发或提交到仓库。

部分 Codex 版本可能通过 auth.json 保存认证状态。该文件同样属于敏感文件，不能公开上传。其字段格式可能随着版本变化，除非当前版本文档明确要求，否则不要自行猜测 JSON 结构。

cc-switch 负责“切换档案”，不负责证明兼容

cc-switch 的核心作用是保存和切换多套 Codex 供应商配置。图形界面可以降低 TOML 格式错误，但它无法替代服务端兼容性验证。

添加自定义 Codex 供应商时，通常需要填写：

1. 供应商名称。
2. API Key 或密钥来源。
3. API Base URL。
4. 模型名称或模型 ID。
5. 协议类型。
6. 是否启用当前配置。

保存后应检查：

• 当前档案是否处于启用状态；
• 模型 ID 是否被自动修改；
• 配置是否保存到正确的用户范围；
• 是否覆盖了原有 config.toml；
• Codex 是否已经完全退出并重启。

建议把 cc-switch 中的配置命名为用途，而不是简单使用服务商名称：

stable-code
deepseek-lab
review-only
fallback-chat

一套配置只有在测试通过后，才应标记为稳定。

如果你手动编辑过 config.toml，又使用 cc-switch 保存配置，务必重新检查文件内容。图形工具可能覆盖手动修改，手动修改也可能导致界面显示与实际文件不一致。

用“协议卡片”判断模型是否真的适合 Codex

服务商常说“兼容 OpenAI API”，但这句话可能只覆盖基础聊天接口。

建议为每个模型建立一张协议卡片：

模型 ID：YOUR_CODEX_MODEL
Base URL：已核对 / 未核对
Responses API：支持 / 不确定 / 不支持
Chat Completions：支持 / 不确定 / 不支持
流式输出：已验证 / 未验证
工具调用：已验证 / 未验证
上下文长度：以服务方说明为准

wire_api = "responses" 通常表示 Codex 使用 Responses API 风格发送请求。传统 Chat Completions 在请求字段、返回结构、流式事件和工具调用方面可能不同。

兼容性可以拆为三层：

层级	需要验证的内容	典型错误
路径层	Base URL、版本路径和资源路径	404
请求层	请求体字段和参数结构	400
响应层	返回对象、流式事件和工具结果	空输出、解析失败

因此，模型能否接入 Codex，应当判断：

客户端支持的协议
    ∩
服务端提供的协议
    ∩
目标模型具备的能力
    ∩
当前 API Key 拥有的权限

任何一项不在交集内，都可能导致调用失败。

采用四阶段验收，避免直接修改真实项目

配置完成后，不要直接让 Codex 操作重要项目。建议分四阶段测试。

第一阶段：启动验收

codex --version

确认 CLI 可用，再在测试目录启动：

cd C:\path\to\test-project
codex

如果启动阶段就报错，优先检查配置路径、TOML 语法和环境变量。

第二阶段：文本验收

发送简单问题：

请用三句话解释哈希表的平均查找复杂度。

这一阶段主要验证网络、Key、模型 ID 和基础请求路径。

第三阶段：代码验收

让模型生成一个小函数，并观察：

• 输出是否完整；
• 代码块是否正常；
• 是否出现异常中断；
• 推理参数是否被服务端接受。

第四阶段：工作区验收

只在无敏感信息的测试项目中，验证：

• 读取文件；
• 解释代码；
• 修改小文件；
• 返回修改结果。

如果前三阶段正常，第四阶段仍然失败，问题很可能出在工具调用、权限、流式事件或客户端能力，而不是 API Key。

错误排查要围绕“配置层级”进行

错误	可能所在层级	优先检查
codex 无法识别	本地命令层	npm、PATH、终端刷新
401	鉴权层	API Key、env_key、环境变量
403	权限层	模型分组、令牌权限、额度限制
404	路径或模型层	Base URL、模型 ID、接口版本
400	协议层	wire_api、请求字段、参数格式
429	限流层	并发、配额、请求频率
5xx	服务端层	上游状态、服务时间点
流式中断	响应层	流式协议、代理和事件格式
配置不生效	生命周期层	启用状态、进程重启、配置来源

401：先确认凭证是否真的进入 Codex 进程

环境变量已经写入，并不等于当前 Codex 已经读取。确认变量名称与 env_key 完全一致，并关闭旧终端和旧进程。

404：区分“模型不存在”和“路径不存在”

404 可能是模型 ID 错误，也可能是 Base URL 拼接后请求到了不存在的路径。不要只修改模型名称，先核对服务方给出的基础地址和接口版本。

400：优先怀疑协议不匹配

如果普通请求可以发送，但 Codex 请求返回 400，可能是 Responses API 与 Chat Completions 的字段不一致。查看服务端错误信息，确认具体哪个字段或请求结构不被支持。

配置不生效：检查是否被工具覆盖

手动修改后没有变化，可能是 cc-switch 覆盖了文件；cc-switch 切换后没有变化，也可能是 Codex 仍在使用旧进程或另一份配置。

版本升级后，先回滚再迁移

升级 Codex、cc-switch 或模型服务后，不要立即覆盖稳定配置。建议按以下流程操作：

备份旧配置
   ↓
复制为测试配置
   ↓
确认新版本字段
   ↓
执行四阶段验收
   ↓
通过后再切换为稳定配置

重点复测：

• model_provider 是否仍有效；
• wire_api 是否仍被支持；
• 模型 ID 是否变化；
• auth.json 是否需要迁移；
• 环境变量是否仍能读取；
• 流式输出和工具调用是否正常。

如果新版本出现异常，直接切换回上一套已验证配置，不要在生产项目中边用边试。

安全边界：配置可共享，凭证不可共享

可以公开的内容包括：

• 脱敏后的 config.toml；
• 字段解释；
• 错误排查步骤；
• 不含敏感信息的日志片段；
• 模型能力记录。

不能公开的内容包括：

• API Key；
• 完整 auth.json；
• Authorization Header；
• 完整请求体；
• 企业源代码；
• 私有项目路径；
• 含用户信息的日志。

使用第三方模型时，还要确认代码和上下文是否会被发送到外部服务。企业内部代码、客户数据和访问令牌不应在未经授权的情况下上传。

结语：一套好配置应该随时能解释、切换和恢复

Windows 下配置 Codex 国内模型，最终目标不是让某个模型“成功跑一次”，而是建立一套可以长期维护的配置系统：

• config.toml 管理模型和供应商关系；
• 环境变量管理 API Key；
• auth.json 按当前版本规则处理；
• cc-switch 管理多套配置档案；
• 能力矩阵记录模型真实表现；
• 分阶段测试证明兼容性；
• 版本升级保留回滚路径。

DeepSeek、Qwen 或其他代码模型是否适合 Codex，不能仅凭模型名称或“兼容某 API”的描述判断。只有路径、鉴权、请求、响应、流式输出和工具调用都经过验证，才适合进入稳定配置。

把配置当成可审计、可迁移、可回滚的工程资产，Codex 的模型切换才不会变成一次次重复试错。