# Windows 下 VS Code + Codex 插件 + 第三方中转 Key + CC Switch 完整配置教程

> 本文面向 Windows 用户，介绍如何在 VS Code 中安装 OpenAI Codex 插件，并使用 CC Switch 管理第三方 API 中转服务。文中所有地址、模型名和 Key 都是示例占位符，请替换为服务商实际提供的值。

## 摘要

Codex 可以直接在 VS Code 中读取项目上下文、修改代码、运行命令和解释报错。除了使用 ChatGPT 账号或 OpenAI 官方 API Key，也可以通过 Codex 的自定义模型提供商配置接入兼容服务。

如果经常切换不同服务商，手动维护 `config.toml` 和认证信息比较容易出错。CC Switch 提供了图形化的供应商管理、切换、配置备份和本地协议转换能力。本文完整说明安装、配置、验证和常见错误处理。

关键词：VS Code、Codex、CC Switch、第三方 API、中转 Key、Responses API、config.toml

## 一、先理解四个组件的关系

整套链路如下：

```text

VS Code

  -> OpenAI Codex 插件

  -> Codex 本地配置

  -> 第三方 API 中转地址

  -> 上游模型

```

CC Switch 不等于模型服务，它主要负责管理和切换 Codex 的本地配置。

各部分作用如下：

| 组件 | 作用 |

| --- | --- |

| VS Code | 代码编辑器 |

| OpenAI Codex 插件 | 在编辑器中提供 Codex 对话、代码修改和任务执行能力 |

| 第三方中转服务 | 提供 API 地址、API Key、模型 ID 和计费账户 |

| CC Switch | 图形化管理不同供应商，并把当前选择同步到 Codex 配置 |

需要特别说明：

1. CC Switch 是第三方开源工具，不是 OpenAI 官方产品。

2. 第三方中转 Key 不是 ChatGPT 密码，也不一定是 OpenAI 官方 API Key。

3. ChatGPT 订阅、OpenAI API 账单和第三方中转账单是三套不同的计费关系。

4. 第三方服务可能接触请求中的提示词、代码片段和工具结果，不要在来源不可信的服务上处理商业机密。

## 二、准备材料

开始前准备以下内容：

- Windows 10 或更高版本。

- 已安装的 VS Code。

- 第三方中转服务提供的 API Key。

- API Base URL，例如 `https://relay.example.com/v1`。

- 可用模型 ID，例如 `YOUR_MODEL_ID`。

- 服务商是否支持 OpenAI Responses API 的明确说明。

最关键的是最后一项。当前 Codex 自定义模型提供商原生使用 Responses API。服务商只写“兼容 OpenAI”并不能证明它支持 Codex，它可能只兼容 `/v1/chat/completions`。

向中转服务商确认以下问题：

```text

1. 是否支持 POST /v1/responses？

2. 是否支持流式 SSE 返回？

3. 是否支持工具调用？

4. Codex 应填写哪个模型 ID？

5. Base URL 应填写到域名、/v1，还是完整接口地址？

```

如果服务商原生支持 Responses API，可以直接接入；如果只支持 Chat Completions，则需要 CC Switch 的本地路由转换功能。

## 三、安装 VS Code 的 Codex 插件

### 1. 打开扩展市场

在 VS Code 左侧点击“扩展”，或按：

```text

Ctrl + Shift + X

```

搜索：

```text

Codex

```

安装前核对：

```text

发布者：OpenAI

扩展标识：openai.chatgpt

```

不要只看图标和名称，避免安装名称相似的非官方扩展。

### 2. 打开 Codex 面板

安装完成后，点击 VS Code 左侧的 Codex 图标。如果图标没有出现，按 `Ctrl + Shift + P` 打开命令面板，执行：

```text

Codex: Open Codex Sidebar

```

此时先不必进行 ChatGPT 登录。后续启用第三方供应商后，Codex 会读取本机的用户级配置。

## 四、安装 Codex CLI（可选但建议）

VS Code 插件可以独立使用，但安装 CLI 后更容易检查版本和定位连接问题。

先安装 Node.js LTS，然后执行：

```powershell

npm install -g @openai/codex

```

检查安装：

```powershell

codex --version

```

如果 PowerShell 拦截 `codex.ps1`，可以先尝试：

```powershell

codex.cmd --version

```

这通常是 PowerShell 脚本执行策略问题，不代表 Codex 安装失败。不要为了运行一个命令就直接把整台电脑的执行策略改成完全不受限。

## 五、安装 CC Switch

只从以下渠道获取：

- 官网：<https://ccswitch.io>

- GitHub Releases：<https://github.com/farion1231/cc-switch/releases>

Windows 可选择：

- MSI 安装包：适合长期使用。

- Portable ZIP：解压后直接运行，适合临时测试。

安装完成后打开 CC Switch。在开始切换前，建议先使用 CC Switch 自带的数据导出或备份功能保存当前状态。

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

```text

%USERPROFILE%\.codex\config.toml

%USERPROFILE%\.codex\auth.json

```

这两个文件可能包含认证信息。不要上传到 Git，不要粘贴到公开文章，也不要在截图中展示完整内容。

## 六、判断应该使用哪种接入模式

### 模式 A：中转原生支持 Responses API

满足以下条件时优先使用直连：

- 支持 `POST /v1/responses`。

- 支持流式响应。

- 支持 Codex 使用的工具调用格式。

- 服务商给出了明确的 Codex 配置说明。

这种模式不要求 CC Switch 本地代理持续运行，链路更短，也更容易排错。

### 模式 B：中转只支持 Chat Completions

如果服务商只支持：

```text

POST /v1/chat/completions

```

则不能把该地址直接当作 Codex 的 Responses 端点使用。需要在 CC Switch 中打开“需要本地路由映射”，由本地代理完成：

```text

Codex Responses 请求

  -> CC Switch 本地路由

  -> 转换为 Chat Completions

  -> 第三方服务

```

此模式下必须：

- 开启 CC Switch 本地路由服务。

- 开启 Codex 接管。

- 使用期间保持 CC Switch 或其本地代理运行。

- 正确填写模型映射。

## 七、使用 CC Switch 添加 Codex 供应商

不同版本的按钮位置可能略有变化，但字段含义基本一致。

### 1. 进入 Codex 页面

打开 CC Switch，在应用列表中选择“Codex”，然后点击右上角 `+` 添加供应商。

### 2. 优先使用现成预设

如果列表中已经有你的服务商：

1. 选择对应预设。

2. 填写服务商提供的 API Key。

3. 核对自动填入的 API 地址。

4. 获取或选择模型。

5. 保存供应商。

预设会随 CC Switch 版本变化，最终以当前软件界面和服务商文档为准。

### 3. 没有预设时选择“自定义”

建议按下面方式填写：

| 字段 | 示例 | 说明 |

| --- | --- | --- |

| 名称 | `My Relay` | 仅用于本机识别 |

| API Key | `YOUR_RELAY_API_KEY` | 填服务商生成的 Key |

| Base URL | `https://relay.example.com/v1` | 以服务商文档为准 |

| 模型 | `YOUR_MODEL_ID` | 必须使用服务商实际支持的模型 ID |

| 协议 | `responses` | 原生直连时选择 Responses |

| 推理强度 | `medium` | 仅在模型和中转支持时生效 |

不要把示例中的 `YOUR_RELAY_API_KEY` 或 `YOUR_MODEL_ID` 原样提交。

### 4. Base URL 最容易填错

标准形式通常是：

```text

https://relay.example.com/v1

```

通常不要直接填写：

```text

https://relay.example.com/v1/responses

https://relay.example.com/v1/chat/completions

```

Codex 或本地路由会根据协议拼接具体路径。如果服务商明确要求完整 URL，则以它的文档为准，并检查 CC Switch 是否需要打开“完整 URL”之类的选项。

典型错误包括：

```text

/v1/v1/responses

/responses/responses

把 chat/completions 填给 Responses 客户端

```

### 5. 获取模型

填写 Key 和地址后，可以尝试点击“获取模型”。CC Switch 会调用服务商的模型列表接口。

如果获取失败：

- 服务商可能不支持 `/v1/models`。

- Key 可能没有模型列表权限。

- Base URL 可能填写错误。

- 服务商可能要求手动填写模型 ID。

“获取模型失败”不一定代表推理接口不可用。以服务商提供的准确模型 ID 手动填写后，还要实际发起一次测试请求。

### 6. 是否打开“需要本地路由映射”

按照下面判断：

| 上游能力 | 是否打开本地路由 |

| --- | --- |

| 原生支持 Responses API | 不打开 |

| 只支持 Chat Completions | 打开 |

| 使用非 GPT 模型且需要模型映射 | 通常打开 |

| 服务商预设已自动配置 | 保持预设值 |

不要在已经原生兼容 Responses 的线路上重复增加协议转换，否则会增加故障点。

### 7. 保存并启用

保存供应商后，在供应商卡片上点击“启用”。卡片显示“当前启用”才表示配置已切换。

CC Switch 会把当前供应商同步到 Codex 的活动配置。Codex 通常不会让已经运行的进程自动完整重载提供商配置，因此切换后需要重启相关进程。

## 八、让 VS Code 读取新配置

完成 CC Switch 切换后：

1. 结束正在运行的 Codex CLI。

2. 在 VS Code 中按 `Ctrl + Shift + P`。

3. 执行 `Developer: Reload Window`。

4. 重新打开 Codex 面板。

5. 新建一个 Codex 对话，不要继续使用切换前的旧会话做首次验证。

如果仍然读取旧配置，完全退出所有 VS Code 窗口后重新启动。

## 九、如何检查 CC Switch 生成的配置

正常情况下不需要手工修改文件。本节仅用于理解和排错。

OpenAI 官方文档说明，Codex 的用户级配置位于 `~/.codex/config.toml`。Windows 对应：

```text

C:\Users\你的用户名\.codex\config.toml

```

一个自定义 Responses 提供商的结构大致如下：

```toml

model = "YOUR_MODEL_ID"

model_provider = "relay"

model_reasoning_effort = "medium"

[model_providers.relay]

name = "My Relay"

base_url = "https://relay.example.com/v1"

wire_api = "responses"

env_key = "CODEX_RELAY_API_KEY"

```

字段含义：

| 字段 | 说明 |

| --- | --- |

| `model` | 中转服务真实支持的模型 ID |

| `model_provider` | 当前启用的提供商 ID |

| `[model_providers.relay]` | 名为 `relay` 的提供商定义，名称必须对应 |

| `base_url` | API 基础地址 |

| `wire_api` | 当前只支持 `responses` |

| `env_key` | 指定从哪个环境变量读取 Key，而不是 Key 本身 |

注意事项：

- `relay` 只是自定义 ID，可以换成其他英文标识。

- 不要使用保留 ID：`openai`、`ollama`、`lmstudio`。

- 提供商配置必须放在用户级 `config.toml`。项目内 `.codex/config.toml` 不能覆盖 `model_provider` 和 `model_providers`。

- `env_key` 填的是环境变量名称，不是实际 Key。

- `requires_openai_auth = true` 与 `env_key` 是两种认证方式，不应同时使用；前者启用时会忽略 `env_key`。

CC Switch 的部分版本或预设可能选择文件式认证，并把 Key 管理到：

```text

%USERPROFILE%\.codex\auth.json

```

检查文件时只确认字段存在，不要展示字段值。例如文章截图应处理成：

```json

{

  "OPENAI_API_KEY": "<REDACTED>"

}

```

`auth.json` 应当被当作密码文件管理。

## 十、不使用 CC Switch 时的官方配置思路

这部分是备用方案，也方便理解 CC Switch 做了什么。

### 1. 设置环境变量

仅当前 PowerShell 窗口有效：

```powershell

$env:CODEX_RELAY_API_KEY = "YOUR_RELAY_API_KEY"

```

设置用户级环境变量：

```powershell

[Environment]::SetEnvironmentVariable(

  "CODEX_RELAY_API_KEY",

  "YOUR_RELAY_API_KEY",

  "User"

)

```

设置后需要彻底重启 VS Code，新进程才能读取新环境变量。

### 2. 配置用户级 config.toml

```toml

model = "YOUR_MODEL_ID"

model_provider = "relay"

[model_providers.relay]

name = "My Relay"

base_url = "https://relay.example.com/v1"

env_key = "CODEX_RELAY_API_KEY"

wire_api = "responses"

```

OpenAI 官方更推荐通过 `env_key` 引用环境变量，而不是把 Bearer Token 直接写入 TOML。

使用 CC Switch 时，不建议同时手工维护同一份活动配置。CC Switch 将自己的数据库作为配置源，切换供应商时可能覆盖手工修改。

## 十一、验证是否配置成功

### 1. 先用 CC Switch 自检

可以依次检查：

- Key 是否已填写。

- 地址测速是否正常。

- 模型测试是否有返回。

- 当前供应商是否显示为“当前启用”。

- 如果启用了本地路由，代理服务是否正在运行。

测速成功只代表网络可达，不代表 Responses、流式和工具调用全部兼容。

### 2. 使用 Codex CLI 验证

关闭旧终端，重新打开 PowerShell：

```powershell

codex

```

输入一个不会修改文件的测试问题：

```text

只回复“连接成功”，不要读取或修改文件。

```

能够稳定流式返回，说明基础连接可用。

### 3. 使用 VS Code 插件验证

在 VS Code 中新建一个空目录或测试项目，然后新建 Codex 对话：

```text

请只说明当前工作目录中有哪些一级文件，不要修改任何内容。

```

确认以下结果：

- 能正常回复。

- 没有出现 401、403、404 或 405。

- 流式输出不中断。

- 模型名称与预期一致。

- 只读任务没有产生文件修改。

最后再用一个小型、可撤销的代码任务验证工具调用。

## 十二、常见错误与解决方法

### 1. 401 Unauthorized

常见原因：

- Key 复制不完整。

- Key 已过期或余额不足。

- Key 前后包含空格或换行。

- CC Switch 当前启用的不是刚添加的供应商。

- 环境变量覆盖了 CC Switch 写入的认证信息。

处理顺序：

1. 在服务商控制台确认 Key 状态。

2. 在 CC Switch 中重新粘贴 Key。

3. 检查环境变量冲突提示。

4. 启用供应商后重启 VS Code 和终端。

### 2. 403 Forbidden

常见原因：

- Key 没有目标模型权限。

- 服务商限制了来源 IP。

- 账户余额、套餐或并发权限不足。

- 模型不允许使用工具调用。

### 3. 404 Not Found

优先检查 Base URL：

```text

错误示例：https://relay.example.com/v1/responses/responses

错误示例：https://relay.example.com/v1/v1/responses

常见正确形式：https://relay.example.com/v1

```

最终仍以服务商文档为准。

### 4. 405 Method Not Allowed

通常表示接口路径或协议不匹配。例如服务商只实现了 Chat Completions，却收到了 Responses 请求。

解决方法：

- 向服务商确认是否支持 `/v1/responses`。

- 如果只支持 Chat Completions，在 CC Switch 中打开本地路由映射。

- 启动本地路由服务并开启 Codex 接管。

### 5. model_not_found

不要根据宣传名称猜模型 ID。服务商页面显示的“GPT 高级模型”和接口实际需要的模型字符串可能完全不同。

处理方法：

- 使用 CC Switch 的“获取模型”。

- 查看服务商 API 文档。

- 复制接口返回的原始模型 ID。

- 修改后重启 Codex，新建会话。

### 6. 流式输出中断或一直转圈

Codex 对流式响应和工具调用要求高于普通聊天页面。中转服务需要正确处理 SSE、长连接和 Responses 事件。

检查：

- 服务商是否明确支持 Codex。

- 网络代理是否缓存或截断 SSE。

- CC Switch 本地路由是否仍在运行。

- 防火墙是否阻止本地代理端口。

- 服务商是否在高峰期限制并发。

### 7. CC Switch 已切换，但 VS Code 仍使用旧供应商

依次执行：

1. 确认供应商卡片显示“当前启用”。

2. 关闭所有 Codex CLI 进程。

3. 执行 `Developer: Reload Window`。

4. 新建 Codex 会话。

5. 仍无效时完全退出 VS Code 后重新打开。

### 8. 环境变量冲突

旧的 `OPENAI_API_KEY`、其他代理地址或不同工具写入的变量可能覆盖当前设置。CC Switch 可以检测常见冲突。

不要看到冲突后直接批量删除。先记录变量来源并做好备份，再判断哪个程序仍然需要它。

## 十三、如何在多个供应商之间切换

为每个供应商分别保存：

- 名称。

- Base URL。

- Key。

- 模型 ID。

- 是否需要本地路由。

- 备注和到期时间。

切换流程：

```text

在 CC Switch 中点击目标供应商“启用”

  -> 确认显示“当前启用”

  -> 重启 Codex CLI 或重新加载 VS Code

  -> 新建会话验证

```

不要在 Codex 正执行写文件、数据库迁移或发布任务时切换供应商。应等待当前任务结束后再切换，避免请求中断。

## 十四、安全建议

### 1. 不要在文章和截图中泄露 Key

截图前遮盖：

- API Key。

- `auth.json` 内容。

- 请求头中的 `Authorization`。

- CC Switch 导出文件中的凭据。

- 中转平台账户余额和个人信息。

Key 一旦公开，应立即在服务商控制台撤销并重新生成，单纯删除帖子不能保证密钥没有被复制。

### 2. 不要提交到 Git

至少确保以下内容不会进入仓库：

```gitignore

.codex/

.cc-switch/

.env

.env.*

```

通常这两个配置目录位于用户主目录，本来就不应复制进项目。

### 3. 谨慎处理私有代码

使用第三方中转意味着请求可能经过第三方服务器。企业项目应先确认：

- 数据是否被记录。

- 日志保留多久。

- 是否用于训练。

- 服务器所在地区。

- 是否支持数据删除。

- 是否有企业协议和审计能力。

### 4. 使用最小权限

首次测试建议使用只读任务和临时项目。确认服务稳定后，再逐步开放写文件、运行命令和网络访问权限。

## 十五、推荐配置策略

个人学习环境可以采用：

```text

VS Code Codex 插件

+ CC Switch 管理供应商

+ 原生 Responses 中转

+ workspace-write 权限

+ 操作前确认重要命令

```

企业环境更适合：

```text

经过合同审核的 API 服务

+ 独立 Key

+ 环境变量或系统凭据库

+ 最小沙盒权限

+ 用量和审计日志

+ 禁止敏感仓库走未知中转

```

原生支持 Responses API 时，优先使用直连模式。只有上游确实不支持 Responses 时，才启用 CC Switch 本地协议转换。

## 十六、发布前脱敏检查清单

发布到 CSDN 前全文搜索：

```text

sk-

Bearer

api_key

token

auth.json

C:\Users\

公司域名

个人邮箱

```

确认：

- 所有 Key 都已替换成 `YOUR_RELAY_API_KEY`。

- 所有域名都已替换成 `relay.example.com`。

- 所有用户名都已替换成“你的用户名”。

- 截图没有显示终端历史、环境变量或配置文件真实值。

- 没有把第三方工具描述成 OpenAI 官方工具。

## 十七、参考资料

OpenAI 官方文档：

- Codex IDE 插件：<https://developers.openai.com/codex/ide>

- Codex 配置基础：<https://developers.openai.com/codex/config-file/config-basic>

- Codex 自定义模型提供商：<https://developers.openai.com/codex/config-file/config-advanced#custom-model-providers>

- Codex 配置项参考：<https://developers.openai.com/codex/config-file/config-reference>

- Codex 认证：<https://developers.openai.com/codex/auth>

CC Switch 第三方资料：

- CC Switch 开源仓库：<https://github.com/farion1231/cc-switch>

- CC Switch Releases：<https://github.com/farion1231/cc-switch/releases>

- 添加供应商说明：<https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/zh/2-providers/2.1-add.md>

- 切换供应商说明：<https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/zh/2-providers/2.2-switch.md>

## 结语

这套配置能否成功，关键不在于 Key 有没有填进去，而在于三件事：API 地址是否正确、模型 ID 是否真实可用、上游协议是否兼容 Responses API。

使用 CC Switch 可以降低多供应商切换成本，但它仍然是在管理本机 Codex 配置。遇到问题时，按照“认证、地址、协议、模型、重启进程”的顺序排查，通常能快速定位原因。