一、先看懂整条链路：你到底在配置什么

第一次接入 Codex 时，最容易把“命令行工具”“配置切换器”“API 服务”混成一个东西。实际上它们负责的是三件不同的事：Codex 负责接收任务并执行；cc-switch 负责保存、切换和写入供应商配置；中转站负责接收请求、完成鉴权，再把请求转发到可用模型。

因此，排错时不要只盯着一个界面。命令找不到，通常是 Node.js 或 PATH；401/403，通常是 API Key、权限或启用状态；模型不存在，通常是模型名与账户可用列表不一致；改完配置却没有变化，通常是旧终端或旧进程仍在读取旧配置。把问题归类后，处理速度会快很多。

• Codex：在项目目录中运行的命令行 AI 编程工具。
• cc-switch：把不同供应商的配置集中管理，并切换到当前要使用的一套。
• API Key：证明请求来自哪个账户，并决定账户具有什么调用权限。
• *ase **L：Codex 发起请求时要访问的 API 根地址，通常填写到 /v1。
• Model：实际请求使用的模型标识，必须以控制台显示的可用名称为准。

✅ 二、开始前准备：先把四个检查点做完

建议在 Windows 10/11 上使用 PowerShell 或 Windows Terminal 操作。整个流程需要浏览器、Node.js、Codex、cc-switch 和一个已经开通 API 权限的账户。为了让后面的排错有依据，先不要急着改配置，依次确认下面四件事。

这里有一个很实用的习惯：把“安装是否成功”和“接口是否可用”分开验证。前者只看版本号，后者才看 API Key、*ase **L 和模型。分开以后，即使接口暂时不可用，也不需要反复重装 Codex。

• 终端能够正常打开，并且当前用户有权限安装 Node.js 全局包。
• 账户**能够创建 API Key，并能看到可用模型名称。
• 本机没有同时运行多套会改写 Codex 配置的工具。
• 准备一个小型测试项目，不要一上来就在生产仓库中验证。

三、安装 Node.js 并确认 npm 环境

Codex 的安装依赖 Node.js。建议使用当前仍在维护的 LTS 版本，安装过程保留默认选项即可。安装结束后，关闭已经打开的旧终端，再新开一个 PowerShell，让系统重新加载 PATH。

node -v
npm -v
where.exe node
where.exe npm

正常情况下，前两条会返回版本号，后两条会返回可执行文件路径。如果 node -v 有结果而 npm -v 没有结果，通常是安装不完整或 PATH 没有刷新；如果两条都找不到，先重新打开终端，仍然无效再检查 Node.js 安装目录是否加入系统 PATH。

如果下载依赖速度不稳定，可以只调整 npm 的下载源，不要把它和 API 的 *ase **L 混为一谈。npm 源只影响安装包下载，和后面请求模型的地址是两条独立链路。

npm config set registry https://registry.npmmirror.com
npm config get registry

四、安装 Codex：先验证命令，再进入配置

在确认 Node.js 和 npm 都可用后，再安装 Codex。全局安装的好处是可以在不同项目目录直接调用；如果电脑上已经存在旧版本，先记录当前版本，后续出现问题时更容易判断是否与升级有关。

npm install -g @openai/codex
codex --version
Get-Com**nd codex

看到版本号后，不要立刻开始复杂任务。先用 codex --help 确认命令能够启动，再关闭当前终端，重新打开一个 PowerShell。重新打开这一步看似多余，但可以排除全局 npm **n 目录尚未进入当前会话的问题。

codex --help

️ 五、打开 cc-switch，进入 Codex 配置页

启动 cc-switch 后，先确认当前页面对应的是 Codex，而不是其他命令行工具。不同工具的配置文件和字段并不完全相同，页面选错会导致你填完后看似保存成功，实际 Codex 并没有读取这套配置。

进入 Codex 页面后，点击右上角的“添加”按钮，选择“自定义配置”。第一次配置建议只添加一套线路，先把最小闭环跑通，再逐步增加其他模型或备用线路。配置越少，出错时越容易确认到底是哪一项造成影响。

六、逐项填写供应商：每个字段都讲清楚

下面以灵能API作为接入示例。打开控制台后，先登录账户并创建一枚专门给 Codex 使用的 API Key。API Key 只在本机配置窗口中粘贴，不要放到文章、截图、代码仓库或聊天窗口里；如果怀疑已经泄露，应立即在控制台撤销并重新生成。

在自定义供应商页面，按照下面的含义填写。字段名称可能会随着 cc-switch 版本变化，但它们表达的含义基本一致：

最常见的错误有三个：把官网地址填进 API 请求地址；只填写域名而漏掉接口版本路径；模型名凭记忆填写，实际与账户可用列表不一致。出现请求失败时，优先逐字对照控制台和配置窗口，不要先反复点击保存。

如果页面提供“获取模型列表”或“管理与测速”，可以在 API Key 和请求地址填写完成后使用。能获取列表，说明基础连通性和鉴权大概率已经通过；如果获取失败，先处理地址、密钥或权限问题，再继续填写模型。

• 供应商名称：填写一个便于识别的名称，例如“灵能API-Codex”。这个名称只用于本机区分配置。
• 备注：可以填写“Codex 主线路”或项目名称，方便之后切换时确认用途。
• 官网链接：可选，填写控制台地址即可，不参与 API 请求。
• API Key：粘贴控制台生成的完整密钥，注意不要带空格、引号或换行。
• API 请求地址：填写兼容接口的完整 *ase **L，例如 灵能API/v1" target="_*lank" rel="noopener">灵能API。不要重复追加 /v1/v1。
• 模型名称：填写账户实际可用的模型 ID。标题中的 GPT-5.6 只是本教程的示例，最终以你的控制台模型列表为准。

七、保存不等于启用：完成一次完整切换

填写完成后点击“添加”或“保存”。保存的含义是把这套供应商记录到 cc-switch 的配置列表中；只有点击“启用”或切换到当前使用状态，Codex 才会读取它。这个区别是很多新手第一次失败的原因。

启用后，建议观察卡片是否出现“使用中”“已启用”或类似状态。若状态没有变化，先确认你操作的是 Codex 页面中的卡片，而不是其他工具的同名配置。cc-switch 的切换动作通常会更新 Codex 的配置文件，配置文件被其他程序占用或权限不足时，可能会出现写入失败。

完成启用后，关闭已经打开的 Codex 终端和相关进程，再新开 PowerShell。Codex 通常在启动时读取配置，旧终端不会自动获得新配置；这也是“界面显示已启用，但命令行仍然报旧错误”的常见原因。

八、先在 cc-switch 内测试，再启动 Codex

如果供应商卡片上有测试按钮，先进行一次轻量测试。测试的目标不是验证复杂功能，而是确认请求能够到达接口并返回响应。测试时不要使用过长提示词，也不要上传项目源码，避免把网络问题和上下文长度问题混在一起。

测试成功后，新开 PowerShell，进入一个空目录或测试项目，再启动 Codex。第一轮只做只读任务，例如让它列出项目目录、解释某个函数或给出修改计划，不要立即授权大范围写入。这样可以同时验证模型、工作目录和 Codex 进程是否正常。

mkdir codex-check
cd codex-check
codex

进入 Codex 后，可以输入：请先只读分析当前目录，列出你看到的文件，并说明下一步需要哪些信息，不要修改文件。如果能正常返回结构化分析，说明从终端到中转接口的最小链路已经打通。

九、需要手动兜底时：检查 config.toml 与 auth.json

如果 cc-switch 保存后没有生效，可以用手动检查确认它究竟写入了什么。Codex 常见配置目录位于用户目录下的 .codex 文件夹，常见文件包括 config.toml 和 auth.json。不同版本的字段可能存在差异，手动修改前建议先复制备份，避免把原有可用配置覆盖掉。

$codexHome = Join-Path $HOME '.codex'
Get-ChildItem $codexHome -Force
Get-Content (Join-Path $codexHome 'config.toml') -ErrorAction SilentlyContinue

一个便于理解的 TOML 结构示例如下。这里展示的是字段关系，不代表所有版本都必须逐字照抄；model 应替换为账户实际可用的模型，wire_api 等字段也应以当前 Codex 版本文档和中转接口兼容方式为准。

model_provider = "lingneng"
model = "gpt-5.6"

[model_providers.lingneng]
name = "灵能API"
*ase_url = "https://www.lnsns.com/v1"
wire_api = "responses"
requires_openai_auth = true

如果你在配置文件中看到了正确的 *ase **L 和模型，但 Codex 仍然鉴权失败，再检查 auth.json 是否存在旧凭据，或者当前终端是否设置了覆盖配置的环境变量。不要同时修改多个位置；一次只改一个变量，改完重启终端再测试。

十、按错误现象排查：不要盲目重装

下面这张排查表按现象分类，适合第一次接入失败时逐项核对。每处理一类问题，都用最小请求重新验证一次，避免多个改动叠加后无法判断真正原因。

如果问题仍未解决，可以按“版本号、当前启用卡片、请求地址、模型名称、错误码、是否重启终端”的顺序记录信息。排错记录越完整，越容易判断是本地配置问题还是接口侧问题。

• 提示找不到 codex：重新打开终端，执行 where.exe codex；确认全局 npm **n 路径在 PATH 中。
• 401 Unauthorized：重新生成或复制 API Key，检查是否带空格、是否已撤销、当前配置是否真的已启用。
• 403 For**dden：检查账户权限、额度、模型权限或接口侧的访问限制，不要只更换模型名。
• model not found：从控制台复制精确模型 ID，注意大小写、连字符、版本号和前后空格。
• 404 Not Found：检查 *ase **L 是否重复 /v1，或者是否把完整接口路径误当成根地址。
• 请求超时：先用 cc-switch 的短请求测试，再检查网络、**、接口地址和提示词长度。
• 改完仍走旧线路：完全退出 Codex 和旧终端，重新启用卡片，再打开新的 PowerShell。

️ 十一、稳定使用前的安全清单

尤其要注意：截图示例中的字段可以帮助你找到位置，但不能替代你自己的账户信息。API Key、模型列表和权限状态都属于账户级数据，实际操作时必须以自己的控制台为准。

• 不要把 API Key 写进 Git 仓库、截图、公开文章或前端代码。
• 为不同项目使用不同密钥，便于单独撤销和定位用量。
• 修改 cc-switch 配置前保留一份可回滚的备份。
• 先让 Codex 只读分析，再逐步开放写入和命令执行权限。
• 定期查看账户用量、密钥状态和可用模型，不要长期依赖过期配置。

十二、最后***四步验收

到这里，完整接入流程应该能用四个结果来验收：Node.js 和 Codex 能返回版本号；cc-switch 中的 Codex 卡片处于启用状态；cc-switch 内置测试能返回成功；新终端启动 Codex 后能够完成一次只读分析。四项全部通过，再把它用于真实项目。

后续如果要增加备用模型或切换不同线路，建议一次只新增一张卡片，并为每张卡片写清用途。这样以后遇到模型波动、额度变化或项目切换时，只需要切换配置并重启终端，不需要重新搭建整套环境。