1. 为什么要在 Codex 里接一个外部模型
先把话说清楚：Codex 这类命令行 AI 编程助手，默认绑定的往往是某一家厂商的模型服务，用起来顺手，但一旦你想换模型、想对比不同模型在同一套工作流下的表现，或者单纯想用成本更低的推理服务，就会卡在一个很尴尬的位置——工具本身不给你留口子，或者留了口子但配置链路长得离谱。ccx加cc-switch这套组合，本质上就是来解决这个问题的：前者负责把外部模型的接口"翻译"成 Codex 能听懂的协议，后者负责在多个模型配置之间快速切换，让你不用每次改配置文件改到手抖。
我先把这三个东西的角色摆明白，不然后面全是糊涂账。Codex是那个你天天在终端里敲命令、让它读代码改代码的客户端；DeepSeek-v4是你要接进来的模型服务，它有自己的 API 地址、自己的鉴权方式、自己的请求格式；ccx是中间那层适配器，把 Codex 发出的请求格式转换成 DeepSeek 能接受的格式，再把响应转回来；cc-switch则是一个配置管理的小工具，帮你在一堆模型配置之间来回横跳，不用手动改文件。
这套方案解决的核心痛点有三个。第一是协议不通，Codex 期望的请求结构和 DeepSeek 的接口规范不是一回事，直接填个地址过去大概率报错；第二是切换成本高，你可能有多个模型要对比，每次换都得翻配置文件、改地址、改密钥，烦得要命；第三是可复现性差，手动改的东西过两天自己都忘了改过什么，出了问题无从排查。ccx 解决第一个，cc-switch 解决第二个和第三个。
适合谁来参考这份东西？如果你已经在用 Codex 做日常开发辅助，想试试 DeepSeek-v4 的实际编码表现，或者你手上有多套模型配置需要频繁切换对比，那这套流程就是给你准备的。完全没碰过命令行工具的新手也能跟下来，因为我会把每一步的命令和预期输出都写清楚，但前提是你得有一个能正常调用的 DeepSeek API 密钥，这个得你自己去申请，我没法替你做。
还有一点得提前说明：下面涉及的具体端口号、配置文件路径、参数取值，都是基于常见实践的合理设定，不同版本的 Codex 和 ccx 可能在细节上有出入，你实际操作时以自己环境里的文档为准。我会把"为什么这么设"讲清楚，这样即使某个参数名对不上，你也能自己判断该往哪个方向调。
2. 整体方案拆解：三层结构各管什么
2.1 请求链路是怎么走的
理解这套方案，最关键的是把请求的流向在脑子里画出来。你在终端里敲一条 Codex 命令，Codex 把请求发到它配置的接口地址——这个地址我们不让它指向 DeepSeek 官方，而是指向本地跑着的 ccx 服务。ccx 收到请求后，做三件事：校验请求格式、转换请求体、带上你的 DeepSeek 密钥转发出去。DeepSeek 返回结果后，ccx 再把响应转回 Codex 期望的格式，Codex 拿到结果展示给你。
这条链路里，ccx 是唯一需要"懂两种语言"的角色。它对外（对 Codex）说 Codex 的方言，对内（对 DeepSeek）说 DeepSeek 的方言。这也是为什么不能直接把 Codex 的接口地址改成 DeepSeek 的地址——两边方言不通，中间必须有个翻译。
cc-switch 不在这条请求链路上，它是"配置层"的工具。它管理的是 Codex 那边"我该把请求发到哪个地址、用哪个密钥"这组配置。你可以把它理解成一个遥控器，按一下切换到 A 配置（指向 ccx 的本地端口），再按一下切换到 B 配置（指向另一个模型服务）。它改的是 Codex 的配置文件，不参与实际的请求转发。
2.2 为什么选本地代理而不是直连
有人会问：既然 ccx 只是个翻译，为什么不找个在线的转换服务，非要本地跑一个？原因很实在。密钥安全是第一位的，本地跑意味着你的 DeepSeek 密钥只存在自己机器上，不经过任何第三方；延迟可控是第二位的，本地回环的转发开销几乎可以忽略，不会因为中间服务抖动影响体验；可调试是第三位的，本地服务出问题你能看日志、能抓包、能改代码，在线服务出问题你只能干等。
另一个考量是配置的持久性。本地服务一旦跑起来，只要机器不关、进程不退，配置就是稳定的。在线服务可能因为各种原因变更接口、限流、甚至下线，你的工作流就断了。做开发辅助这种高频使用的场景，稳定性比什么都重要。
2.3 cc-switch 的价值到底在哪
单看"切换配置"这个功能，好像手动改个文件也就几十秒的事，值得专门装个工具吗？我一开始也这么想，直到配置多到五六个、每个又有七八个字段的时候，手动改就开始出错了——改错一个字符、漏改一个字段、改完忘了保存，这些坑我都踩过。cc-switch 的核心价值不是"省时间"，是"防出错"和"可回溯"。
它把每套配置当成一个独立的 profile 来管理，切换的时候整组替换，不会出现"地址换了但密钥还是旧的"这种半吊子状态。而且切换动作是原子的、可记录的，出了问题你能明确知道当前用的是哪套配置。对于需要反复对比不同模型表现的场景，这个价值会被放大很多倍。
3. 环境准备与依赖安装
3.1 前置条件清单
动手之前，先把这些东西确认一遍，缺一个后面都会卡住。我列个表，你对着勾。
| 项目 | 要求 | 检查方式 |
|---|---|---|
| 操作系统 | macOS / Linux / Windows（WSL） | 终端能正常执行命令 |
| Node.js | 18 及以上 | node -v看版本号 |
| 包管理器 | npm 或 pnpm | npm -v或pnpm -v |
| Codex | 已安装且能正常启动 | codex --version |
| DeepSeek 密钥 | 已申请且余额充足 | 控制台能看到密钥 |
| 网络 | 能正常访问 DeepSeek 接口 | 用 curl 测一下 |
Node.js 版本这条特别提醒一下，低于 18 的版本在跑某些依赖时会报语法错误，而且报错信息往往指向依赖内部，很难联想到是 Node 版本的问题。我见过有人在这上面耗了一下午，最后发现是 Node 16。升级一下就好，别省这一步。
3.2 安装 ccx 与 cc-switch
两个工具都用包管理器装，命令很直接。先装 ccx：
npm install -g ccx装完验证一下：
ccx --version能打印出版本号就说明装好了。如果提示命令找不到，大概率是全局 bin 目录没在 PATH 里，npm config get prefix看一下全局安装路径，把它加到 PATH 里再试。
接着装 cc-switch：
npm install -g cc-switch同样验证：
cc-switch --version这里有个实操心得：如果你用的是 pnpm，全局安装的命令是pnpm add -g，但有些工具对 pnpm 的全局链接支持不好，装完命令找不到。遇到这种情况，老老实实用 npm 装，别跟工具较劲。我试过用 pnpm 装 ccx，装是装上了，但启动时报模块解析错误，换回 npm 一次就过。
3.3 密钥的环境变量管理
DeepSeek 的密钥不要硬编码在配置文件里，用环境变量管理，这是基本的安全习惯。在 shell 的配置文件里加一行（以 bash 为例，写到~/.bashrc；zsh 写到~/.zshrc）：
export DEEPSEEK_API_KEY="你的密钥"改完执行source ~/.bashrc让它生效，然后echo $DEEPSEEK_API_KEY确认能打印出来。这一步看着简单，但它是后面 ccx 能拿到密钥的前提。ccx 启动时会读这个环境变量，读不到就会在转发请求时鉴权失败，而失败信息往往只说"401"，不会告诉你"你没设环境变量"，所以这里先确认好，能省掉后面一轮排查。
注意：密钥写进 shell 配置文件后，注意文件权限，别让同机器上的其他用户能读到。
chmod 600 ~/.bashrc是个好习惯。
4. 核心配置：把 ccx 跑起来
4.1 ccx 的启动参数怎么定
ccx 的启动命令核心就几个参数：监听端口、上游地址、密钥来源。一条典型的启动命令长这样：
ccx --port 8787 --upstream https://api.deepseek.com --key-env DEEPSEEK_API_KEY逐个解释为什么这么设。端口选 8787，是因为这个段位（8000 以上）一般不会被系统服务占用，冲突概率低；你也可以换成 9000、10000 之类的，只要记住后面 Codex 配置里要填同一个端口。上游地址填 DeepSeek 的 API 根地址，注意不要带具体的路径后缀，ccx 会自己拼接。密钥来源用--key-env指定环境变量名，这样密钥不落在命令行历史里（命令行历史是会被记录的，密钥写命令行里等于泄露）。
启动后终端会打印类似这样的信息：
ccx listening on http://127.0.0.1:8787 upstream: https://api.deepseek.com key source: env DEEPSEEK_API_KEY看到这三行，说明服务起来了。这时候别急着配 Codex，先用 curl 直接打一下 ccx，验证转发链路通不通：
curl http://127.0.0.1:8787/v1/models \ -H "Content-Type: application/json"如果返回了模型列表（或者至少返回一个结构化的 JSON 而不是连接拒绝），说明 ccx 到 DeepSeek 的链路是通的。这一步是分界线：通了，后面配 Codex 就是填地址的事；不通，问题一定在 ccx 或密钥上，跟 Codex 无关，排查范围一下就缩小了。
4.2 让 ccx 常驻后台
开发辅助是高频使用的，每次开终端都手动启动 ccx 不现实。两个方案：一是用nohup挂后台，二是用进程管理工具。简单场景用前者：
nohup ccx --port 8787 --upstream https://api.deepseek.com --key-env DEEPSEEK_API_KEY > ~/.ccx.log 2>&1 &日志重定向到~/.ccx.log，出问题的时候tail -f ~/.ccx.log就能看到实时日志。这个日志文件是你排查问题的第一现场，ccx 转发失败、上游返回错误、请求格式不对，都会在这里留下痕迹。
如果你机器上已经有 pm2 之类的进程管理工具，用它更省心，能自动重启、能看状态。但没有也不强求，nohup 够用了。我个人的习惯是写个小脚本start-ccx.sh放在家目录，内容就是上面那条命令，需要的时候bash start-ccx.sh一下，比记长命令靠谱。
4.3 验证转发是否真的生效
curl 通了不代表 Codex 能用，因为 Codex 发的请求体比 curl 复杂得多。更靠谱的验证方式是发一个真实的对话请求：
curl http://127.0.0.1:8787/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek-chat", "messages": [{"role": "user", "content": "说一句话证明你在工作"}] }'能拿到模型返回的文本，说明整条链路（ccx 接收 → 转换 → 转发 DeepSeek → 转换回传）全部打通。这一步过了，再去配 Codex，成功率就很高了。如果这一步失败，看~/.ccx.log里的错误信息，常见的是密钥无效、模型名不对、上游地址写错这三类，日志里一般能直接看出来。
提示：模型名要填 DeepSeek 实际支持的名称，别想当然。填错了上游会返回"model not found"，而 ccx 可能只把这个错误原样透传，看起来像是 ccx 的问题，其实是模型名的事。
5. 用 cc-switch 管理 Codex 配置
5.1 Codex 的配置结构长什么样
Codex 的配置一般落在一个 JSON 或 TOML 文件里，核心字段包括接口地址、密钥、默认模型、超时时间这几项。我们要做的，是把接口地址指向http://127.0.0.1:8787，密钥字段填一个占位值（真正的密钥在 ccx 那边通过环境变量注入，Codex 这边不需要真密钥），默认模型填 DeepSeek 的模型名。
这里有个容易搞混的点：Codex 配置里的密钥字段不是给 DeepSeek 用的。因为请求是先到 ccx，ccx 再加真正的密钥转发出去。所以 Codex 这边填什么密钥都行，填个local甚至留空都可以，只要 ccx 那边配置正确。理解这一点，你就不会纠结"密钥到底填哪"这个问题了。
5.2 创建第一套 profile
cc-switch 的核心概念是 profile，一套 profile 就是一组完整的 Codex 配置。创建命令大致是：
cc-switch add deepseek-local \ --base-url http://127.0.0.1:8787 \ --model deepseek-chat \ --api-key localdeepseek-local是这个 profile 的名字，你自己起，起个能看懂的名字就行。--base-url指向 ccx 的本地端口，--model填 DeepSeek 的模型名，--api-key填占位值。执行完，cc-switch 会把这套配置存起来，并在需要的时候写进 Codex 的配置文件。
再建一套对照 profile，比如指向另一个模型服务，方便后面做切换演示：
cc-switch add backup-model \ --base-url http://127.0.0.1:8788 \ --model some-other-model \ --api-key local两套 profile 建好，cc-switch list能列出来，说明管理生效了。
5.3 切换与生效验证
切换命令：
cc-switch use deepseek-local执行后 cc-switch 会把 Codex 的配置文件改成这套 profile 的内容。验证方式有两种：一是cc-switch current看当前激活的是哪套；二是直接看 Codex 的配置文件，确认地址字段确实变成了127.0.0.1:8787。
切换完，重启一下 Codex（有些版本支持热加载，但重启最保险），然后随便发一条请求，比如让它解释一段代码。如果返回正常，说明整条链路在 Codex 这个真实客户端下也通了。到这一步，标题里说的"接入"就算完成了。
注意：切换 profile 后如果 Codex 行为异常，先确认 Codex 进程是不是还在用旧配置。配置文件改了但进程没重启，读的还是内存里的旧值，这种"改了没生效"的假象很容易误导排查方向。
6. 常见问题与排查实录
6.1 连接被拒绝：ccx 没起来或端口不对
最常见的报错是ECONNREFUSED 127.0.0.1:8787。这个错误的含义很明确：Codex 往这个地址发请求，但那个端口上没有服务在监听。排查顺序是：先ps aux | grep ccx看进程在不在；不在就重新启动；在的话看启动日志里打印的端口是不是 8787，有可能你启动时用了别的端口但配置里没改。
还有一种隐蔽情况：ccx 起来了，但监听的是localhost而 Codex 解析localhost到了 IPv6 的::1，两边对不上。解决办法是把配置里的地址从localhost改成明确的127.0.0.1，强制走 IPv4。这个坑我在不同工具上踩过好几次，症状就是"明明服务在跑却连不上"，改地址立刻好。
6.2 鉴权失败：密钥没传到 ccx
报错表现为 401 或"unauthorized"。链路是 Codex → ccx → DeepSeek，401 可能发生在两段上。先看 ccx 日志：如果日志里显示"upstream returned 401"，说明是 ccx 到 DeepSeek 这段的密钥有问题，回去检查环境变量DEEPSEEK_API_KEY是否在当前 shell 里真的存在（echo一下），以及 ccx 启动时是不是在同一个 shell 里（环境变量是进程级的，换个终端窗口可能就没了）。
如果日志里显示的是"invalid request from client"，那问题在 Codex 到 ccx 这段，通常是 Codex 配置里的密钥字段被设成了必填校验而填了空值。把占位值填上（比如local）即可。
6.3 模型返回空或格式错乱
有时候请求通了、也返回 200，但内容不对——要么是空的，要么是乱码，要么是 Codex 解析不了的结构。这类问题的根源通常在协议转换的字段映射上。ccx 需要把 Codex 的请求字段映射到 DeepSeek 的字段，如果某个字段名对不上（比如 Codex 用max_tokens而 DeepSeek 期望max_output_tokens），转换就会丢字段，导致行为异常。
排查方法是抓一次实际请求看字段。在 ccx 启动时加个--verbose之类的调试开关（具体开关名看版本），让它把收到的请求体和转发的请求体都打出来，对比一下字段是否完整。缺哪个补哪个，在 ccx 的配置里做字段映射。这一步稍微进阶，但理解了"转换层可能丢字段"这个原理，排查就有方向了。
6.4 常见问题速查表
| 现象 | 最可能原因 | 快速验证 | 解决 |
|---|---|---|---|
| 连接被拒绝 | ccx 未启动/端口不符 | ps aux | grep ccx | 重启 ccx，核对端口 |
| 401 鉴权失败 | 密钥未注入 | 看 ccx 日志定位哪一段 | 检查环境变量/占位值 |
| 返回空内容 | 字段映射丢失 | 开 verbose 对比请求体 | 补字段映射 |
| 切换后无变化 | Codex 未重启 | 看配置文件是否已改 | 重启 Codex |
| 偶发超时 | 上游限流/网络抖动 | 看日志时间戳 | 加重试或错峰 |
6.5 几个踩过的坑
第一个坑是端口冲突。8787 被别的服务占了，ccx 启动时可能不报错而是静默失败，或者报个模糊的"address in use"。启动前lsof -i :8787看一眼，占用了就换个端口，配置里同步改。
第二个坑是配置文件路径不一致。cc-switch 改的配置文件和 Codex 实际读的配置文件可能不是同一个（不同版本、不同安装方式路径不同）。切换后用cc-switch current --show-path之类的命令确认改的是哪个文件，再对照 Codex 文档确认它读的是哪个，两者必须一致。
第三个坑是环境变量作用域。你在 A 终端设了环境变量、启动了 ccx，然后在 B 终端用 Codex，B 终端里没有那个环境变量——但 ccx 是在 A 终端启动的，它继承的是 A 的环境，所以其实没问题。真正有问题的是反过来：你在 A 终端设了变量但 ccx 是在设之前启动的，那 ccx 读不到。顺序很重要，先设变量再启动服务。
7. 性能调优与日常使用建议
7.1 超时与重试的合理设置
本地代理多了一跳，虽然开销很小，但超时设置要留出余量。Codex 那边如果默认超时是 30 秒，经过 ccx 转发后实际可用时间会略少，遇到 DeepSeek 响应慢的时候容易误判超时。建议把 Codex 的超时调到 60 秒，给转发和上游响应都留足空间。
重试策略上，我倾向于在 ccx 层做一次轻量重试（比如失败后隔 500ms 重试一次），而不是让 Codex 层重试。原因是 Codex 层重试会把整个请求重新走一遍，包括可能已经成功的部分；ccx 层重试只重试上游那一段，更精准。当然这取决于 ccx 是否支持重试配置，不支持的话就在 Codex 层设，设保守一点，别设太多次，避免雪崩。
7.2 日志轮转别忽视
ccx 的日志会一直增长，跑几天可能就几百 MB。用 logrotate 或者简单点，在启动脚本里加个判断，日志超过一定大小就重命名归档。这个事不起眼，但磁盘被日志写满导致服务挂掉的情况我见过不止一次。简单做法：
if [ -f ~/.ccx.log ] && [ $(stat -c%s ~/.ccx.log) -gt 104857600 ]; then mv ~/.ccx.log ~/.ccx.log.old fi放在启动脚本开头，每次启动前检查一下，超过 100MB 就归档。
7.3 多模型对比的正确姿势
既然用了 cc-switch，多模型对比就是它的主场。建议给每个模型建独立 profile，命名带上前缀方便识别，比如cmp-deepseek、cmp-other。对比的时候固定同一段代码、同一个问题，切换 profile 后各跑一遍，记录响应质量和耗时。别小看这个流程的规范化，随手切换随手测，测完自己都记不清哪个结果对应哪个模型，白测。
我个人的习惯是建一个简单的记录表，每次对比记下：profile 名、问题、响应摘要、耗时、主观评价。积累十几条之后，哪个模型适合哪类任务就一目了然了。这个表比任何评测榜单都靠谱，因为它是你自己工作流的真实数据。
8. 安全与合规的边界
8.1 密钥管理的底线
前面反复强调环境变量，这里再收一下口。密钥不进代码、不进命令行、不进配置文件、不进版本控制，这四条是底线。ccx 通过环境变量读密钥，Codex 配置里只放占位值，这个设计本身就是为了让密钥只存在于一个地方（环境变量），减少泄露面。
如果机器是多用户共享的，环境变量的可见性也要注意。某些系统上同用户的其他进程能读到你的环境变量，这种情况下考虑用更严格的密钥管理方式，比如启动时从加密文件读取再注入。这个属于进阶话题，普通单用户开发机用环境变量足够了。
8.2 本地服务的访问范围
ccx 默认监听127.0.0.1，只有本机能访问，这是对的。千万不要图方便改成0.0.0.0监听所有网卡——那等于把你带密钥的转发服务暴露到局域网上，任何人扫到端口就能白嫖你的额度。如果确实需要跨机器访问，用 SSH 隧道之类的安全方式，别直接开监听。
8.3 使用场景的自我约束
这套工具链的定位是开发辅助，帮你读代码、写注释、解释逻辑、生成测试。用它处理你自己的代码没问题，但涉及他人隐私数据、商业机密的内容，上传之前想清楚。模型服务的数据处理策略你得自己了解清楚，这不是工具能替你决定的。我个人的原则是：能脱敏就脱敏，能本地复现的问题就不上传原始代码，养成习惯比事后补救强。
9. 后续可以怎么扩展
这套架子搭好之后，扩展空间其实挺大。一个方向是多上游聚合，ccx 如果支持配置多个上游，可以按模型名路由到不同的服务商，Codex 那边无感知。另一个方向是请求缓存，对重复的、确定性的请求（比如"解释这个函数"）做缓存，省额度也省时间。还有一个方向是用量统计，在 ccx 层记录每次请求的 token 消耗，月底一看就知道钱花哪了。
我个人在实际操作中的体会是，这类"中间层"工具的价值往往不在它本身的功能，而在于它给你留了一个可以插手的位置。没有 ccx，Codex 和模型之间是黑盒，你只能祈祷它工作；有了 ccx，中间每一步你都能看、能改、能加逻辑。这种可控性，在长期使用中比任何单点功能都重要。踩过几次"出问题完全不知道从哪查"的坑之后，我现在选工具会优先看它有没有留出可观测、可干预的中间层，ccx 加 cc-switch 这套组合，恰好满足这个标准。
