1. 为什么要在 Windows 上折腾 Codex CLI 加 CC Switch 这套组合

在 Windows 上把 AI 编程助手跑起来，很多人第一反应是装个桌面客户端或者用网页版。但如果你像我一样，日常大量时间泡在终端里，就会觉得来回切窗口特别割裂。Codex CLI 这类终端工具的价值就在于，它把 AI 能力直接塞进命令行，你敲代码、跑测试、看日志的时候顺手就能调用，不用离开当前工作流。而 CC Switch 解决的是另一个痛点：模型切换和 API 端点管理。你不可能永远只用一个模型，有时候想用官方账号，有时候想接第三方 API，手动改配置文件改到崩溃，CC Switch 就是来干这个脏活累活的。

这套组合适合谁？适合那些已经习惯命令行操作、手头有 DeepSeek API 或者其他兼容 OpenAI 接口的模型服务、并且希望在 Windows 上获得接近 Unix 体验的开发者。如果你连 Node.js 都没装过，别慌，我会把每一步拆到你能照着敲的程度。但如果你期待的是“一键安装包双击完事”，那这套方案可能不太适合你，因为它本质上还是需要你理解配置文件在哪、环境变量怎么设、代理为什么报错。

我前后在 Windows 上配过三台机器，踩过的坑包括但不限于：Node 版本不对导致 Codex CLI 装不上、CC Switch 的本地代理端口被占用、DeepSeek API 的 base URL 写错导致 401、环境变量在 PowerShell 和 CMD 里行为不一致。这些问题的解法我都会在下面展开，你照着做能省至少两个晚上的排查时间。

2. 环境准备：Node.js、Git 和终端的选择

2.1 Node.js 安装与版本选择

Codex CLI 本质是一个 Node.js 包，所以第一步是把 Node 装好。截至我写这篇内容的时候，Codex CLI 对 Node 版本的要求是 18 以上，推荐 20 LTS。你直接去 Node.js 官网下载 Windows 的 LTS 安装包，双击下一步就行。但这里有个细节：安装向导里有一个“Automatically install the necessary tools”的勾选项，如果你不打算做原生模块编译，可以不勾，省得它又去下载一堆 Visual Studio Build Tools，那个过程在 Windows 上极其漫长。

装完之后打开 PowerShell，敲：

node -v npm -v

如果都能正常输出版本号，说明基础环境没问题。我遇到过一种情况：公司电脑上之前装过旧版 Node，PATH 里指向的是旧目录，新装的没生效。这时候你需要手动去“系统属性 -> 环境变量”里把 Node 的路径挪到最前面，或者干脆卸载重装。

提示：如果你同时需要多个 Node 版本，建议用 nvm-windows 来管理，但 nvm-windows 和全局 npm 包的兼容性偶尔会抽风，新手建议先用单一版本。

2.2 Git 的安装与配置

Git 不是必须的，但强烈建议装。因为 Codex CLI 在某些场景下会调用 git 来读取仓库状态，而且你后续更新工具、拉取配置都方便。Windows 上装 Git 直接去官网下安装包，一路默认选项即可。唯一需要注意的是“Adjusting your PATH environment”那一步，选“Git from the command line and also from 3rd-party software”，这样 PowerShell 里也能直接用 git 命令。

装完之后配置一下用户名和邮箱：

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

这两条命令看起来简单，但如果你不配，后续某些工具在读取 git 信息时会报错，虽然不影响核心功能，但日志里一堆 warning 看着烦。

2.3 Windows Terminal 与 PowerShell 版本

Windows 10 和 11 自带的 Windows Terminal 已经很好用了，建议用它替代老旧的 CMD。PowerShell 方面，尽量用 PowerShell 7 而不是 Windows PowerShell 5.1，因为 7 的跨平台兼容性更好，环境变量的读写行为也更一致。你可以通过 winget 安装：

winget install Microsoft.PowerShell winget install Microsoft.WindowsTerminal

装完之后把 Windows Terminal 的默认配置文件设为 PowerShell 7。这一步不影响 Codex CLI 的核心功能，但能让你后续操作少遇到一些编码和转义问题。

3. Codex CLI 的安装与首次运行

3.1 全局安装 Codex CLI

Node 环境就绪后，安装 Codex CLI 就是一条命令的事：

npm install -g @openai/codex

如果你网络环境正常，这条命令会在几十秒内完成。但如果你遇到ETIMEDOUT或者ECONNRESET，大概率是 npm 源的问题。可以临时切换到国内镜像：

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

装完之后验证：

codex --version

如果提示unable to locate the codex cli binary or required runtime components，说明全局安装路径没加到 PATH 里。你可以用npm config get prefix看看 npm 全局目录在哪，然后手动把这个目录加到系统环境变量 Path 中。Windows 上通常是C:\Users\你的用户名\AppData\Roaming\npm。

3.2 首次运行与登录方式选择

直接敲codex会进入交互界面。第一次运行它会让你选择登录方式。如果你有官方账号，可以走浏览器授权；如果你想接 DeepSeek API，就选择 API key 方式，或者先跳过，后续通过 CC Switch 来管理。

这里要说明一下：Codex CLI 本身支持配置自定义的 API base URL 和 key，但它的配置文件格式和 CC Switch 的托管方式有差异。如果你打算用 CC Switch 统一管理，建议先不要在 Codex CLI 里写死配置，而是让 CC Switch 来注入。

3.3 配置文件的位置与结构

Codex CLI 在 Windows 上的配置目录通常是C:\Users\你的用户名\.codex。里面会有一个config.json或者config.toml，取决于版本。你可以手动查看这个文件来确认当前使用的模型和端点。但手动改这个文件有个问题：每次切换模型你都得改一遍，而且容易改错。这就是 CC Switch 要解决的核心问题。

4. CC Switch 的定位与安装

4.1 CC Switch 到底解决了什么问题

简单说，CC Switch 是一个本地代理加配置管理器。它在本地起一个 HTTP 服务，Codex CLI 把请求发给这个本地服务，本地服务再根据你当前的配置，把请求转发到真正的 API 端点。这样做的好处是：你切换模型或 API 提供商的时候，只需要在 CC Switch 的界面里点一下，不用去动 Codex CLI 的配置文件。

另外，CC Switch 还能处理不同 API 之间的格式差异。比如 DeepSeek 的 API 和官方接口在请求体上有些细微差别，CC Switch 会帮你做转换。这就是为什么热词里会出现cc switch local proxy failed while handling codex endpoint /responses这类报错，因为代理层在转发时出了问题。

4.2 下载与安装 CC Switch

CC Switch 有图形界面版本，也有命令行版本。Windows 上建议用图形界面版，下载地址在它的官方仓库 release 页面。下载下来是一个 exe 或者 zip，解压后直接运行。注意：Windows Defender 可能会误报，你需要手动允许运行。

运行之后，它会默认监听一个本地端口，比如 3456 或者类似的。你可以在设置里改。这个端口就是 Codex CLI 要指向的本地代理地址。

4.3 配置 DeepSeek API 接入

在 CC Switch 里添加一个新的 provider，选择自定义或者 OpenAI 兼容模式。然后填入：

• Base URL:https://api.deepseek.com
• API Key: 你的 DeepSeek API key
• Model:deepseek-chat或者deepseek-coder，看你需要哪个

这里有个坑：DeepSeek 的 API 路径是/v1/chat/completions，但有些工具默认会拼成/chat/completions，少了一个/v1。如果你遇到 404，先检查这个路径。CC Switch 通常会在转发时自动补全，但如果你手动改了配置，就可能出问题。

注意：DeepSeek API 的计费和额度是独立的，跟官方账号不互通。你需要在 DeepSeek 平台上单独充值。

5. 把 Codex CLI 接到 CC Switch 上

5.1 修改 Codex CLI 的端点配置

现在要让 Codex CLI 把请求发给 CC Switch 的本地代理，而不是直接发给官方。你需要在 Codex CLI 的配置里把 base URL 改成http://127.0.0.1:3456（端口按你 CC Switch 里设的来）。同时 API key 可以随便填一个占位符，因为真正的 key 由 CC Switch 在转发时注入。

具体改法取决于 Codex CLI 的版本。如果是config.json，大概长这样：

{ "apiBase": "http://127.0.0.1:3456/v1", "apiKey": "sk-placeholder" }

如果是config.toml，格式又不一样。你可以先运行codex --help看看有没有--config参数，或者直接看官方文档里关于自定义端点的说明。

5.2 验证代理是否生效

配置完之后，在终端里跑一个简单的请求：

codex "写一个 Python 的 hello world"

如果一切正常，你会看到 DeepSeek 返回的结果。如果报401 Unauthorized，说明 CC Switch 没有正确注入 API key，或者 key 本身无效。如果报404 Not Found，检查 base URL 的路径拼接。如果报local proxy failed while handling codex endpoint /responses，说明 CC Switch 的代理层在处理这个特定端点时出了问题，可能是版本不匹配，升级 CC Switch 到最新版通常能解决。

5.3 切换回官方账号的注意事项

热词里有人问“cc switch 与官方账号是否冲突”。答案是：不冲突，但你需要理解切换逻辑。当你想切回官方账号时，在 CC Switch 里把 provider 切到官方，然后把 Codex CLI 的 base URL 改回官方地址，或者让 CC Switch 转发到官方。但官方账号的认证方式可能跟 API key 不同，涉及 OAuth 流程，CC Switch 不一定能完全代理。所以我的建议是：如果你频繁在官方和第三方之间切换，最好准备两套 Codex CLI 的配置，用的时候手动切，别指望一个代理层搞定所有认证方式。

6. 常见报错与排查速查表

6.1 代理层报错汇总

6.2 端口占用与防火墙问题

CC Switch 默认端口如果被其他程序占用，它会启动失败或者行为异常。你可以用netstat -ano | findstr 3456来查看端口占用情况。如果被占了，在 CC Switch 设置里换一个端口，然后同步更新 Codex CLI 的配置。

Windows 防火墙有时会拦截本地回环请求，虽然少见，但如果你发现代理明明启动了却连不上，可以临时关闭防火墙测试一下。如果确认是防火墙问题，给 CC Switch 加一条入站规则允许本地回环即可。

6.3 Node 版本与依赖冲突

Codex CLI 某些版本对 Node 的版本要求比较严格。如果你用 Node 22 遇到奇怪的报错，降到 Node 20 LTS 试试。另外，如果你之前装过旧版的 Codex CLI，先卸载再装：

npm uninstall -g @openai/codex npm install -g @openai/codex

7. 实操心得与进阶技巧

7.1 配置文件备份与版本管理

我习惯把~/.codex/config.json和 CC Switch 的配置文件都放到一个 git 仓库里管理。这样换机器的时候直接 clone 下来，改改路径就能用。但注意不要把 API key 提交上去，用环境变量或者单独的 secrets 文件来存。

7.2 用环境变量覆盖配置

Codex CLI 支持通过环境变量来覆盖配置，比如OPENAI_API_BASE和OPENAI_API_KEY。在 PowerShell 里临时设置：

$env:OPENAI_API_BASE="http://127.0.0.1:3456/v1" $env:OPENAI_API_KEY="sk-placeholder" codex "测试一下"

这种方式适合临时测试，不用改配置文件。但每次开新终端都要重设，所以长期用还是写进配置文件或者用 CC Switch 管理。

7.3 日志查看与调试

CC Switch 一般会有日志输出，你可以在它的界面里找到日志面板，或者看它安装目录下的 log 文件。Codex CLI 这边，你可以加--verbose或者类似的调试参数来看到更详细的请求信息。排查问题时，先确认请求有没有到达 CC Switch，再看 CC Switch 有没有成功转发出去，一层层往下查。

7.4 性能与超时设置

DeepSeek API 在国内的响应速度还可以，但如果你同时开了代理或者其他网络工具，可能会变慢。Codex CLI 和 CC Switch 都有超时设置，默认值通常够用。如果你遇到频繁超时，可以适当调大超时时间，但更重要的是检查网络链路。

8. 关于更新与维护的一些经验

Codex CLI 更新很频繁，隔几周就有新版本。更新命令就是重新跑一遍npm install -g @openai/codex。但更新后有时候配置文件格式会变，你需要留意 release note。CC Switch 的更新同理，去官方仓库下最新版覆盖安装即可。

我自己的做法是：每个月检查一次更新，更新前先备份配置文件，更新后跑一个简单的测试请求确认一切正常。这样不会因为某个 breaking change 导致工作流突然断掉。

另外，如果你同时用多个 AI 编程工具，比如还有其他的终端助手，建议把它们的配置目录分开管理，别混在一起。Windows 上路径不统一，混在一起很容易搞乱。

最后说一个我踩过的坑：有一次我把 CC Switch 的端口改成了 8080，结果跟本地的另一个服务冲突了，Codex CLI 一直报连接被拒绝。排查了半天才发现是端口问题。所以改端口之前，先用netstat确认一下端口没被占用。这个习惯能帮你省很多时间。