摘要

本文面向 Windows 用户，介绍如何从零安装 Codex 命令行工具，并将其配置为调用 DeepSeek 等国内代码模型。文章同时覆盖 cc-switch 图形化配置和 .codex/config.toml 手动配置两种方式，解释 model、model_provider、base_url、env_key、wire_api、auth.json 与 OPENAI_API_KEY 的作用，并给出 PowerShell 环境变量设置、模型切换验证以及 401、400、404、PATH 和配置不生效等问题的排查方法。需要注意的是，不同 Codex、cc-switch 版本以及模型服务的字段名称和协议支持可能不同，实际使用时应以当前版本帮助信息和服务方文档为准。

先理解 Codex 接入国内模型的请求链路

在 Windows 上配置 Codex 国内模型，本质上不是修改模型本身，而是让 Codex 客户端按照第三方服务提供的接口协议发送请求。

一个完整的配置链路通常如下：

Codex 客户端
    ↓
.codex/config.toml
    ↓
model_provider
    ↓
model_providers.<provider>
    ↓
base_url + env_key + wire_api
    ↓
第三方模型服务接口

这几个字段分别承担不同职责：

字段	作用	常见错误
model	指定请求使用的模型名称或模型 ID	模型名称拼写错误、模型未开放
model_provider	指向一个供应商配置	供应商 ID 前后不一致
name	供应商的显示名称	通常不影响请求，仅用于识别
base_url	API 基础地址	多写或少写路径、末尾路径不匹配
env_key	指定读取 API Key 的环境变量名称	环境变量名称与实际设置不一致
wire_api	指定请求协议	responses 与 Chat Completions 不兼容
auth.json	某些版本用于保存登录或认证状态	文件格式与当前版本不匹配

例如：

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"

其中 example.invalid 只是不可用的占位地址，不能直接用于实际请求。读者需要替换为模型服务方提供的 API Base URL。

需要特别注意，base_url 通常是 API 基础地址，不一定是完整的请求路径。有些服务要求填写到 /v1，有些服务则有自己的路径结构。不要根据其他平台的配置经验随意拼接地址。

model 也不是随便填写的产品名称。服务方可能同时提供多个模型、不同版本模型或专门的 Codex 模型分组，必须使用服务方实际公布的模型 ID。

Windows 下准备 Git Bash、CMD 和 PowerShell

Codex 的安装和配置并不强制要求 Git Bash，但 Git Bash、CMD 和 PowerShell 各有适合的场景。

• CMD 适合执行简单的 Windows 命令和检查 PATH。
• PowerShell 适合设置、读取环境变量以及执行系统管理命令。
• Git Bash 提供接近 Linux 的命令行体验，适合习惯 Bash 语法的开发者。

如果电脑尚未安装 Git Bash，可以安装 Git for Windows。安装完成后，在开始菜单中打开 Git Bash，执行：

git --version

如果能看到 Git 的版本信息，说明 Git Bash 已经可以使用。

也可以在 PowerShell 中检查：

git --version

如果 PowerShell 能识别而 Git Bash 不能识别，通常是终端启动时间不同或 PATH 尚未刷新。关闭所有相关终端后重新打开，通常可以解决这一类问题。

不同终端之间的环境变量通常来自同一套 Windows 用户环境，但已经打开的进程不会自动获得后来新增的变量。因此，设置环境变量后，不能只在原来的窗口中反复测试，最好关闭并重新打开终端。

在 Windows 中查看当前用户目录，可以使用：

$env:USERPROFILE

Codex 的配置目录通常位于：

%USERPROFILE%\.codex

对应到 PowerShell，一般可以表示为：

$env:USERPROFILE\.codex

具体路径可能因 Codex 版本、安装方式或桌面端实现不同而变化。如果找不到目录，应优先查看当前版本的帮助信息或通过配置工具确认实际路径。

安装 Codex CLI 并确认命令可用

Codex CLI 通常通过 npm 全局安装。执行安装前，先检查 Node.js 和 npm：

node --version
npm --version

如果两个命令都能返回版本号，说明 Node.js 环境基本可用。

安装 Codex：

npm install -g @openai/codex

这里的 -g 表示全局安装。全局安装后，Codex 命令可以在多个项目目录中使用，而不需要把包安装到某一个项目的 node_modules 中。

安装完成后，建议关闭当前终端，再打开新的 CMD、PowerShell 或 Git Bash，执行：

codex --version

如果能够输出版本信息，说明命令行工具已经安装并且 PATH 基本正常。

如果出现“codex 不是内部或外部命令，也不是可运行的程序或批处理文件”之类的提示，可以按以下顺序排查：

1. 确认 npm 安装过程没有出现错误。
2. 确认安装包名称是 @openai/codex，没有漏写或拼写错误。
3. 关闭并重新打开终端。
4. 检查 npm 全局安装目录是否已经加入 PATH。
5. 确认安装和使用命令时使用的是同一个 Windows 用户。
6. 分别在 PowerShell、CMD 和 Git Bash 中测试，排除终端环境差异。

可以使用以下命令查看 npm 的全局安装位置：

npm config get prefix

不同 Node.js 安装方式可能会使用不同的全局目录。不要直接照搬其他电脑上的 PATH 路径，应以当前环境输出为准。

使用 cc-switch 添加自定义 Codex 供应商

cc-switch 的作用是通过图形界面管理多个 AI 编程模型配置。它通常可以帮助用户保存多套供应商信息、切换当前启用的配置，并减少手动编辑 TOML 文件时的格式错误。

不同版本的 cc-switch 菜单名称可能略有差异，但操作逻辑一般接近下面的流程：

1. 安装并启动与当前 Codex 版本匹配的 cc-switch。
2. 进入 Codex 配置或供应商管理页面。
3. 点击新增按钮。
4. 选择 Codex 供应商或自定义配置。
5. 填写一个便于识别的供应商名称。
6. 填写模型服务方提供的 API Key。
7. 填写 API Base URL。
8. 填写服务方提供的模型名称或模型 ID。
9. 根据服务方说明选择请求协议。
10. 启用这套配置。
11. 保存配置。
12. 返回模型切换页面，选择刚刚新增的供应商。
13. 完全退出并重新启动 Codex。
14. 发送一个简单的测试请求。
15. 通过界面状态、终端输出或日志确认当前模型和供应商。

填写供应商名称时，建议使用容易区分的名字，例如“个人测试模型”或“项目专用模型”，不要把 API Key 直接写进名称。

填写 API Base URL 时，必须确认以下几点：

• 地址是否包含服务方要求的版本路径。
• 是否需要 /v1 或其他固定后缀。
• 是否应该填写基础地址，而不是某个具体接口的完整路径。
• 是否存在多余的斜杠、空格或引号。
• 服务方是否要求使用特殊请求路径。

模型名称也要以服务方实际提供的 ID 为准。比如服务方展示的是某个带版本后缀的模型 ID，就不能只填写一个模糊的产品名称。

cc-switch 与手动编辑配置文件并不是两套完全独立的系统。图形界面最终通常仍然要生成或修改 Codex 能够读取的配置。也就是说，界面中填写的供应商、模型和地址，最终仍会影响 config.toml 或相关认证文件。

对比维度	cc-switch 图形化配置	手动编辑配置文件
操作难度	较低，适合初次配置	较高，需要理解 TOML
配置可视化	可以直接查看和切换	依赖文本编辑器
适合场景	快速管理多套配置	精确控制字段和批量备份
常见错误	未启用、保存范围错误	语法、路径、字段拼写错误
配置迁移	取决于工具是否支持导出	可以直接备份文本文件
排错方式	查看界面状态和工具日志	查看配置文件和 Codex 日志
版本风险	界面字段可能随版本变化	配置字段可能随 Codex 版本变化
推荐人群	初次使用者、频繁切换者	需要深度定制的开发者

因此，cc-switch 并不代表一定比手动配置更可靠。它的优势是降低操作门槛，而手动配置的优势是透明、可审查、便于版本控制。

手动创建 .codex/config.toml

如果需要精确控制模型、供应商和协议，可以直接编辑 Codex 配置文件。

首先确认配置目录。Windows 用户目录下通常是：

%USERPROFILE%\.codex

如果目录不存在，可以在确认当前版本确实使用该路径后创建它。创建目录时，应注意 Windows 资源管理器可能隐藏文件扩展名，避免把文件保存成：

config.toml.txt

而不是：

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"

这段配置可以拆分理解：

model = "YOUR_CODEX_MODEL"

指定 Codex 请求时使用的模型。YOUR_CODEX_MODEL 只是占位符，需要替换成模型服务方提供的实际模型 ID。

model_provider = "custom_provider"

指定当前使用的供应商配置。这里的 custom_provider 必须和下面的配置段名称保持一致。

[model_providers.custom_provider]

定义名为 custom_provider 的供应商。供应商 ID 是配置内部使用的标识，不一定等于界面显示名称。

name = "CustomProvider"

设置供应商的显示名称。这个字段主要用于识别，通常不会改变 API 请求。

base_url = "https://example.invalid/v1"

设置 API 基础地址。示例中的地址不可用，仅用于展示格式。

env_key = "OPENAI_API_KEY"

告诉 Codex 从名为 OPENAI_API_KEY 的环境变量中读取 API Key。如果你设置的是其他环境变量名称，这里也必须同步修改。

wire_api = "responses"

指定请求协议为 Responses API 风格。只有在 Codex 当前版本和模型服务都支持该协议时，才应该使用这个值。

TOML 对格式比较敏感，修改时要注意：

• 字符串使用成对的英文双引号。
• 配置段名称必须完整匹配。
• 不要混用中文引号和英文引号。
• 不要在键名中加入多余空格。
• 不要把注释内容误写进字符串。
• 修改后保存为 UTF-8 文本。
• 每次只调整一个变量，便于定位问题。

如果配置文件中还存在其他段落，不要为了测试随意删除。先备份原文件，再进行最小修改。

用 PowerShell 设置 API Key

API Key 不适合直接写入 config.toml。更常见的做法是把它放入 Windows 用户级环境变量中，由 env_key 指定的名称负责关联。

在 PowerShell 中执行：

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

其中：

• OPENAI_API_KEY 是环境变量名称。
• YOUR_API_KEY 是占位符，需要替换成实际密钥。
• User 表示写入当前 Windows 用户范围。
• 该设置通常不需要管理员权限。

设置完成后，可以用以下命令读取当前用户范围的变量：

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

如果输出了内容，说明变量已经写入用户环境变量存储。但不要把输出内容截图、提交到代码仓库或发布到文章中。

需要注意，已经打开的 PowerShell、CMD、Git Bash、Codex 桌面端或其他应用，通常不会自动获得新设置的环境变量。设置完成后，应执行以下操作：

1. 关闭原来的终端窗口。
2. 重新打开 PowerShell 或 Git Bash。
3. 完全退出 Codex，而不是只关闭当前会话。
4. 重新启动 Codex。
5. 再进行模型调用测试。

如果只想在当前 PowerShell 会话中临时测试，也可以使用：

$env:OPENAI_API_KEY = 'YOUR_API_KEY'

这种方式只影响当前终端进程及其子进程，关闭窗口后通常不会保留，适合短期排查，不适合长期配置。

配置文件和环境变量的职责可以这样划分：

配置内容	更适合存放的位置
模型名称	config.toml
供应商 ID	config.toml
API 基础地址	config.toml
API Key	环境变量或凭证管理工具
请求协议	config.toml
临时测试参数	当前终端环境变量
多套配置切换	cc-switch 或独立配置文件
登录状态或认证信息	由当前版本管理的 auth.json

auth.json 的具体用途取决于 Codex 当前版本和登录模式。某些版本可能使用它保存认证状态、登录信息或其他凭证元数据。不要根据网上其他版本的示例手动猜测字段，也不要把完整的 auth.json 发布到公开仓库。

Responses API 与 Chat Completions 的兼容性

很多配置失败并不是 API Key 错了，而是请求协议不匹配。

wire_api = "responses" 通常表示 Codex 按 Responses API 风格构造请求。传统的 Chat Completions 接口则使用另一套请求字段、响应结构和流式输出方式。

两者可能在以下方面存在差异：

• 请求路径不同。
• 请求体字段不同。
• 输入消息结构不同。
• 返回对象结构不同。
• 流式事件格式不同。
• 工具调用和上下文参数的表示方式不同。
• 错误信息和状态码表现不同。

如果模型服务只兼容传统 Chat Completions，而 Codex 当前配置使用 Responses API，可能出现：

• 404：请求路径不存在。
• 400：请求字段无法识别。
• 返回内容为空或结构异常。
• 流式输出中断。
• 工具调用参数解析失败。

反过来，如果服务方明确支持 Responses API，也不代表所有模型都支持 Codex 所需的全部功能。模型名称、工具调用、流式响应和上下文长度仍然需要单独确认。

因此，不能只通过反复修改 wire_api 来碰运气。正确做法是同时确认：

1. 当前 Codex 版本支持哪些协议。
2. cc-switch 当前版本暴露了哪些协议选项。
3. 服务方提供的 API 兼容说明。
4. 目标模型是否开放给当前接口。
5. API Base URL 对应的请求路径。
6. 服务端是否要求特定鉴权 Header。

如果图片、界面或服务说明没有明确写出协议类型，应将其视为“需要验证”，不要直接断言一定兼容。

重启后进行模型切换验证

完成 cc-switch 或手动配置后，建议按固定顺序验证，而不是直接运行复杂任务。

首先确认配置文件和环境变量：

Test-Path "$env:USERPROFILE\.codex\config.toml"
[Environment]::GetEnvironmentVariable(
  'OPENAI_API_KEY',
  'User'
)

第一条命令用于确认配置文件是否存在。第二条命令用于确认用户级环境变量是否已经写入。

随后完全退出 Codex，并重新打开。先发送一个最简单的测试请求，例如让 Codex 解释一段短代码或生成一个很小的函数。测试内容越简单，越容易区分配置问题和任务本身的问题。

验证时重点观察：

• Codex 是否能够正常启动。
• 是否出现认证错误。
• 日志中是否显示目标供应商或模型。
• 请求是否返回正常文本。
• 流式输出是否正常。
• 工具调用或代码编辑功能是否按预期工作。

如果界面没有直接显示模型名称，可以查看当前版本提供的诊断信息或终端日志。日志中可能会出现供应商 ID、请求地址、HTTP 状态码和错误原因。发布日志时必须删除 API Key、Authorization Header、完整请求体和项目源代码。

cc-switch 如何切换模型，通常就是切换当前启用的供应商配置。切换后仍然需要重启 Codex，因为桌面端或命令行进程可能在启动时读取配置，并在整个进程生命周期内保持不变。

常见错误的定位方法

现象	优先检查项	处理建议
codex 无法识别	npm 安装、全局目录、PATH、终端缓存	重新打开终端，确认 npm 全局目录已加入 PATH
cc-switch 配置后没有变化	是否启用、保存范围、Codex 是否完全退出	重新选择配置并完全重启 Codex
401 或鉴权失败	API Key、环境变量名称、空格、鉴权方式	重新设置 Key，核对 env_key，不要公开测试输出
404 或模型不存在	模型 ID、Base URL 路径、接口是否开放	使用服务方提供的精确模型名称和地址
400 或参数错误	wire_api、请求字段、协议兼容性	确认 Responses API 和 Chat Completions 的差异
配置文件不生效	文件名、扩展名、目录、TOML 语法	检查是否为 config.toml.txt，确认文件放在实际配置目录
请求超时	网络连接、服务端状态、代理或防火墙	先确认基础网络，再查看服务端状态和 Codex 日志
输出格式异常	流式协议、响应结构、模型能力	确认服务是否完整支持 Codex 需要的响应格式

codex 不是内部或外部命令

常见原因包括 npm 没有安装成功、npm 全局命令目录未加入 PATH、终端没有刷新、安装时使用了另一个 Windows 用户，或者不同终端读取了不同的环境变量。

可以先分别执行：

npm --version
npm config get prefix
codex --version

如果 npm 正常而 Codex 不可用，重点检查 npm 全局目录是否在 PATH 中。修改 PATH 后必须重新打开终端。

cc-switch 中有配置，但 Codex 没有变化

首先检查配置是否真的启用。有些工具允许保存多个供应商，但只有当前选中的配置会被写入或标记为活动配置。

其次确认 Codex 是否完全退出。只关闭窗口不一定会结束后台进程，必要时通过任务管理器确认相关进程已经退出，再重新启动。

还要检查配置是否保存到了当前用户范围、工作区范围或其他配置范围。不同工具版本可能存在范围差异。

401 鉴权失败

401 通常表示服务端没有接受当前凭证。应检查：

• API Key 是否复制完整。
• Key 前后是否带有空格或换行。
• env_key 是否仍然是 OPENAI_API_KEY。
• 新环境变量是否已经注入当前终端和 Codex 进程。
• 服务端是否要求特定的鉴权方式。
• 是否同时存在旧的登录状态或其他凭证来源。

不要为了排查而把完整 Key 直接写进配置文件，也不要把 Key 发到聊天、截图或日志中。

404 或模型不存在

404 不一定意味着网络不可达，也可能是请求路径或模型名称错误。重点检查：

• model 是否使用了服务方公布的准确 ID。
• base_url 是否多写或少写版本路径。
• 目标模型是否对当前 API 开放。
• 服务端是否要求使用另一种协议路径。
• cc-switch 是否把模型名称转换成了其他值。

400 或参数格式错误

400 常见于协议不兼容。比如 Codex 按 Responses API 构造请求，而服务端只识别 Chat Completions 字段，就可能返回参数错误。

此时应查看服务端错误信息和 Codex 日志，确认具体是哪个字段无法识别。不要只修改模型名称，也不要在不了解协议的情况下不断切换 wire_api。

配置保存后没有生效

重点检查文件扩展名、文件目录和 TOML 语法。Windows 资源管理器隐藏扩展名时，最容易出现 config.toml.txt。

此外还要确认：

• 文件名大小写和版本要求一致。
• 配置段名称与 model_provider 完全一致。
• 英文双引号成对出现。
• 没有混入中文标点。
• 文件编码正常。
• Codex 已经完全重启。
• cc-switch 没有覆盖手动修改的内容。

安全边界与长期维护建议

API Key 应被视为密码管理。不要把它写入公开 Git 仓库、项目 README、教程截图、屏幕录制或自动化脚本。

配置文件中可以公开结构，但应删除以下内容：

• API Key。
• Authorization Header。
• 完整请求日志。
• 企业内部代码。
• 私有项目路径。
• 用户身份信息。
• 服务商返回的敏感错误信息。

如果需要备份配置，可以备份脱敏后的 config.toml，并将真实密钥通过环境变量或系统凭证管理工具单独保存。

使用第三方模型服务时，还要关注代码和数据的流向。发送到服务端的内容可能包括源代码、文件路径、错误日志和上下文信息。企业项目、客户代码和内部凭证不应在未经授权的情况下发送到外部服务。

同时应遵循模型服务商的使用协议，不要绕过权限限制，不要未经授权使用他人的 API Key，也不要把第三方 API 描述成官方 API。

Codex、cc-switch 和模型服务都可能更新。配置字段、默认协议、认证方式和文件路径都可能发生变化。遇到版本升级后配置失效，建议按照以下顺序处理：

1. 查看当前版本的帮助信息。
2. 备份现有配置文件。
3. 检查 cc-switch 是否生成了新的字段。
4. 对照服务方当前协议说明。
5. 用最小配置重新验证。
6. 确认模型、供应商和协议分别可用。
7. 最后再恢复其他高级选项。

总结：根据场景选择配置方式

如果刚开始使用 Codex，或者需要在多套模型之间频繁切换，cc-switch 的图形化方式更容易检查供应商、模型和启用状态。

如果需要审查每个字段、批量备份配置，或者希望把配置纳入自己的开发环境管理，手动编辑 config.toml 更透明。

无论采用哪种方式，真正决定请求能否成功的通常是五个部分：模型名称、供应商 ID、API Base URL、API Key 来源和请求协议。DeepSeek、Qwen 等国内模型是否能接入 Codex，也不能仅凭模型名称判断，必须确认服务端是否提供兼容接口、目标模型是否开放，以及当前 Codex 版本是否支持对应协议。

完成配置后，最可靠的验证方式是重启相关程序，发送一个简单请求，结合日志确认实际使用的供应商、模型、请求路径和返回格式。配置成功并不意味着所有模型能力都完全兼容，工具调用、流式输出、上下文长度和代码编辑能力仍然需要分别验证。