先说实话这个组合解决了一个特别实在的痛点手上同时用着 Codex、Claude Code 这类 AI 编程助手又想接 DeepSeek、或者其他 OpenAI 兼容接口时来回改环境变量、改配置文件真的能把人逼疯。我也是折腾了好几轮才把 CLIProxyApi 和 cc-switch 给盘顺这套搭配用熟了之后切换模型提供方基本就是一条命令的事。这篇文章就把我的完整实操过程、配置细节和踩过的坑全部写出来给正在被多配置切换折磨的朋友一个可以直接抄的作业。1. 先搞清楚这俩工具各自是干嘛的1.1 CLIProxyApi 解决了什么核心问题AI 编程助手接入模型服务时最常见的方式就是让工具直接去请求各家服务商的 API。但这里有个很尴尬的现实Codex 这类官方工具原生只认官方接口地址你想换到 DeepSeek、智谱、或者其他任何 OpenAI 兼容服务就得改环境变量里的BASE_URL、API_KEY改完一个工具另一个工具可能又要不同的配置格式。CLIProxyApi 做的事就是在你的本机上起一个轻量级的 API 转发服务。所有 AI 编程助手的请求都先打到这个本地端口它再根据你预设的规则把请求转发给真正想用的那个模型服务商。这就像你家里装了一个智能路由器所有设备连的都是同一个 WiFi但路由器背后连接的是哪家宽带你随时可以切换设备本身完全无感。这么做的好处非常直接不用反复改各个 AI 工具的环境变量统一的本地入口换后端只改一个配置文件不同工具可以共用同一套密钥管理密钥不用散落在各种配置文件里局域网内其他设备可以通过访问这台机器的地址间接使用你配置好的模型服务请求日志集中在一个地方排查问题的时候一目了然1.2 cc-switch 的价值在于配置切换的自动化CLIProxyApi 把转发逻辑管起来了但如果你有多个模型服务商轮着用每次手动去编辑 CLIProxyApi 的配置文件也够烦的。cc-switch 就是来解决最后这一公里的问题。cc-switch 是一个专门用来管理 AI 编程助手配置的工具它维护了一份模型提供方的配置清单里面预置了 DeepSeek、OpenAI、Anthropic 等常见服务的接入信息也支持你自己添加任意 OpenAI 兼容地址。它的核心能力是当你选定某个服务商时它自动帮你把环境变量、CLI 工具的配置文件改好几秒钟完成切换不用你再碰任何配置文件。我把它俩搭配起来用之后日常操作就变成了这样想用 DeepSeek 跑 Codex就在 cc-switch 里点一下 DeepSeek想切回官方接口再点一下。CLIProxyApi 一直在后台运行端口不变工具配置不变变的只是后端指向。1.3 这套方案适合哪些人如果你是以下情况之一这个组合值得一试同时使用 Codex CLI 和 Claude Code且在不同模型服务商之间反复横跳主要用 DeepSeek 等国产模型服务但不想放弃官方 CLI 工具的原生体验有团队协作需求想让多台开发机共用一套模型服务配置受够了在.bashrc、.zshrc、config.toml里来回翻找和修改 API 配置说白了这套东西的核心价值就四个字配置收敛。你只需要维护一个地方剩下的交给工具。2. 安装准备先把环境搞干净2.1 必须满足的依赖条件在动手之前先把环境检查一遍。我踩过一个坑就是 Node.js 版本太老导致 CLIProxyApi 启动直接报错。它的要求其实不算高但有几个基础项得确认Node.js 版本不低于 16建议 18 以上我目前用的是 20 LTS稳定不折腾npm 或者 yarn、pnpm至少有一个包管理器可用Git后面拉取源码或者安装 cc-switch 会用得到确认你的终端能正常执行全局安装命令不需要额外权限Mac 上如果遇到权限问题可以给 npm 配置用户级全局目录这个后面细说检查 Node.js 版本node -v npm -v如果版本太低推荐用 nvm 装一个新的 Node.js这个工具可以让你在多个 Node 版本之间随时切换比直接升级系统级 Node 稳妥得多。2.2 CLIProxyApi 的安装方式CLIProxyApi 的安装流程相当简单核心就是拉取项目、安装依赖、启动服务三步git clone https://github.com/你的仓库地址/CLIProxyApi.git cd CLIProxyApi npm install npm run build npm start这里想特别提醒一句不同人拿到的 CLIProxyApi 仓库可能版本有差异有的分支叫main有的叫master克隆下来之后先看一眼目录结构。正常的项目里应该能看到src、config、package.json这些标准文件如果你看到的目录跟正常 Node 项目差别很大建议先检查仓库地址是否正确。启动之后默认服务会监听在本机的某个端口日志里会打印一段访问地址。第一次跑起来的时候我建议先保持默认配置跑通确认服务正常响应了再去做自定义修改。先通后调这是排障的基本原则。2.3 cc-switch 的下载与安装细节cc-switch 提供了多种安装方式最简单的是直接下载对应平台的安装包。根据你用的系统选择Mac 用户下载.dmg或.zip包如果你装了 Homebrew也可以用 brew 安装命令大概是brew install cc-switch具体要看仓库里是否维护了对应的 formulaWindows 用户下载.exe安装包或者用.zip解压后直接运行里面的可执行文件Linux 用户下载.AppImage或者.tar.gz解压后赋予执行权限即可安装包获取渠道优先看 GitHub Releases 页面认准官方仓库别从第三方站点随便下。我在 Mac 上遇到过一个情况下载完双击提示无法打开因为无法验证开发者这是因为应用没有经过 App Store 公证。解决办法有两种在系统设置 → 隐私与安全性里找到被拦截的应用点击仍要打开或者在终端里执行xattr -dr com.apple.quarantine /Applications/cc-switch.app第二种方式更彻底一次搞定不会每次启动都弹窗。我个人用的是第二种实测下来干净利落。cc-switch 装好之后首次启动会引导你做一些基础配置。这里先别急着操作直接关掉我们先把 CLIProxyApi 的配置文件理清楚再来让 cc-switch 管理它。3. 核心配置把整个链路打通3.1 CLIProxyApi 配置文件逐项解读CLIProxyApi 的核心配置文件一般是config.json或者.env不同版本稍有区别。我以最常见的 JSON 配置为例把关键字段一个个拆开讲{ port: 8080, defaultProvider: deepseek, providers: { deepseek: { baseUrl: https://api.deepseek.com/v1, apiKey: sk-你的密钥, modelMapping: { gpt-4o: deepseek-chat, claude-sonnet-4: deepseek-chat } }, openai: { baseUrl: https://api.openai.com/v1, apiKey: sk-你的密钥 } } }port是本地服务的监听端口默认 8080如果你本机这个端口被占了可以换成 8787、3000 这类常见开发端口。defaultProvider是默认转发的目标服务商比如你配置了 DeepSeek 和 OpenAI 两个默认走 DeepSeek那所有请求不带特殊标记就会打到 DeepSeek 上。providers里面每个服务商有三个关键属性baseUrl服务商的 API 接入地址。DeepSeek 的 v1 地址、OpenAI 的 v1 地址格式基本都是域名/v1结尾照抄官方文档即可多一个斜杠少一个斜杠都可能导致 404apiKey对应服务商的密钥只存在这个文件里其他工具统一从这里读不用到处复制粘贴modelMapping模型名映射。这个东西非常实用举个例子Codex 原生请求的模型名是gpt-4o但 DeepSeek 那边的模型叫deepseek-chat有了映射关系CLIProxyApi 会在转发时把请求里的gpt-4o自动替换成deepseek-chat后端完全不感知这个配置文件的修改方式我建议在改之前先备份一份。cp config.json config.json.bak一行命令的事但能让你在改崩的时候有个后悔药。3.2 配置 DeepSeek 提供方的完整参数示例如果你主要目标是让 Codex 或者 Claude Code 使用 DeepSeek 的能力provider 配置可以这样写{ deepseek: { baseUrl: https://api.deepseek.com/v1, apiKey: sk-从DeepSeek控制台复制, modelMapping: { gpt-4o: deepseek-chat, gpt-4o-mini: deepseek-chat, o1: deepseek-reasoner } } }这里有个细节值得说deepseek-chat和deepseek-reasoner是两类不同的模型前者是对话模型响应快适合日常代码生成和问答后者是推理模型适合复杂逻辑分析、长链路任务。我一般建议日常快速生成代码映射到deepseek-chat复杂重构、疑难 bug 分析映射到deepseek-reasoner但注意一点DeepSeek 目前的版本兼容 OpenAI 的接口协议但模型能力边界跟 GPT 系列不同。你让 Codex 发一个gpt-4o的请求CLIProxyApi 转成deepseek-chatCodex 本身并不知道后端已经换了模型它还是按 GPT 的交互逻辑去用。大多数场景没问题但个别依赖特定模型能力的工具特性可能表现不一样。这不是配置的问题是模型本身能力差异决定的心里有数就好。3.3 在 cc-switch 中管理多个服务商配置cc-switch 的图形界面非常直观主界面就是一个服务商列表。首次使用的时候它内置了几个常见的服务商模板但更推荐自己手动添加这样每个字段都是可控的。添加服务商的路径一般是主界面 → 新建/添加配置 → 填写服务商信息。需要填写的字段跟 CLIProxyApi 的 provider 配置基本一一对应名称、API 地址、密钥以及一些额外的 Header 参数如果你对接的服务商需要在请求头里加自定义字段。这里有一个容易踩坑的点cc-switch 默认的配置模板里很多服务商的api字段叫baseUrl但有的服务商文档里叫base_url还有的会写成endpoint。你在 cc-switch 里添加的时候要看清楚它表单里字段的提示说明以表单位准不要照搬你从服务商文档里看来的变量名。配置好所有服务商之后cc-switch 主界面的列表就是你所有可选项。想切换的时候点击目标服务商的启用按钮它会自动做两件事同步更新 CLIProxyApi 配置文件里的defaultProvider字段刷新环境变量相关的配置缓存这个过程一般两三秒就完成它会提示你切换成功并且建议你重启正在使用的终端窗口让环境变量重新加载。3.4 密钥管理的心得API 密钥是整个链路里最敏感的东西。我见过不少人直接把密钥写进配置文件然后传到 Git 仓库里这是非常危险的操作。推荐的做法在.gitignore里把配置文件排除掉如果你用的是 Git 管理配置务必确认这点使用环境变量引用密钥比如在配置里写apiKey: process.env.DEEPSEEK_API_KEY这类形式或者让 CLIProxyApi 支持直接读取环境变量团队协作时统一由一个管理员维护真正的密钥其他人拿到的是经过脱敏的配置模板4. 与 Codex、VSCode 的实际联动操作4.1 让 Codex CLI 强制走本地代理地址Codex 是 OpenAI 出的命令行 AI 编程助手它的配置方式非常依赖环境变量。当你配好 CLIProxyApi 之后需要在 Codex 的环境变量里做两件事把 API 地址指到本地把密钥指到本地。在~/.zshrc或~/.bashrc里加这两行export OPENAI_BASE_URLhttp://127.0.0.1:8080/v1 export OPENAI_API_KEYlocal-proxy-key注意两点。第一OPENAI_API_KEY其实是一个任意占位字符串就行了因为真正校验密钥的是 CLIProxyApi 后端的服务商本地代理不校验密钥。第二地址里的/v1不能丢Codex 发请求时会在这个 base url 后面拼上实际的接口路径缺了/v1会导致路径错误。改完之后source ~/.zshrc让环境变量生效然后终端里跑一下codex命令。如果配置正确CLIProxyApi 的日志里应该能看到来自 Codex 的请求记录。有个小的确认技巧在命令行里执行echo $OPENAI_BASE_URL看输出是不是你刚配置的地址这能第一时间排除环境变量没生效的情况。4.2 VSCode 扩展如何对接这套代理VSCode 的 Codex 扩展和命令行版是两套不同的配置入口。扩展一般会有自己的配置面板你需要找到类似 API Base URL 的设置项把值填成http://127.0.0.1:8080/v1。这里要特别注意VSCode 扩展设置和工作区设置是两个层级。如果你某天发现扩展链接的是老地址而你在工作区里覆盖了新地址那就要检查是不是工作区设置把全局设置顶掉了。我遇到过类似问题排查了很久最后发现是项目下的.vscode/settings.json里写了一个旧的 base URL。对于 Mac 用户还有一个简便方式在 VSCode 的settings.json里直接添加{ codex.apiBaseUrl: http://127.0.0.1:8080/v1 }配置好之后重启 VSCode 让设置生效。建议关注扩展的输出面板如果输出里显示请求成功发送那基本就通了。4.3 Claude Code 接入时的特殊注意事项如果 Claude Code 也要走这个代理需要单独设置因为默认情况下它和三方服务商的协议路由不太一样。Claude Code 读取的是ANTHROPIC_BASE_URLexport ANTHROPIC_BASE_URLhttp://127.0.0.1:8080 export ANTHROPIC_API_KEYlocal-proxy-key export ANTHROPIC_MODELclaude-sonnet-4这里有个坑Claude Code 的路径拼接逻辑可能跟你预期的不同。有的版本如果 baseUrl 末尾带/v1它会把请求发送到http://127.0.0.1:8080/v1/v1/messages这种畸形地址上。所以配置ANTHROPIC_BASE_URL的时候先不加/v1只在 CLIProxyApi 的 baseUrl 配置里保留完整路径。如果你发现请求 404优先检查是不是路径重复拼接的问题。另一个细节是模型名。Claude Code 会向服务端发送它自己的想法包括它希望使用的模型名。如果你的 CLIProxyApi 配置了modelMapping一定要把 Claude Code 可能请求的模型名全部映射一遍否则其中一个漏掉那个请求就会带上不存在的模型名打到服务商那里直接报错。4.4 一个完整的请求链路长什么样为了方便理解整个链路我把一次典型请求走的路由过程写出来你在 VSCode 的 Codex 面板里输入一句话点击发送Codex 扩展读取配置的http://127.0.0.1:8080/v1作为 base URL请求带着模型名比如gpt-4o发到本地 8080 端口CLIProxyApi 收到请求根据defaultProvider判断要转发给 DeepSeekCLIProxyApi 根据modelMapping把请求体里的gpt-4o改写成deepseek-chatCLIProxyApi 把改写后的请求转发到https://api.deepseek.com/v1同时附上你的 DeepSeek 密钥DeepSeek 处理请求流式返回结果CLIProxyApi 把结果原样回传给 CodexCodex 在界面上正常展示整个过程在你看来就是Codex 界面没变配置没变命令没变但后端已经悄悄从 OpenAI 换成了 DeepSeek。这种无感切换的能力就是这套组合最值钱的地方。5. 局域网代理和团队协作场景5.1 如何开启局域网让其他设备共用CLIProxyApi 默认只监听127.0.0.1也就是只有本机能访问。如果你想让同一局域网下的其他开发机、或者同一台 Mac 上的不同用户也能用你配置好的代理服务需要做两处调整第一处修改 CLIProxyApi 的监听地址。在配置里找到 host 或 listen 字段默认是127.0.0.1改成0.0.0.0表示监听所有可用网卡接口{ host: 0.0.0.0, port: 8080 }第二处确认防火墙允许入站连接。Mac 上如果开了应用防火墙第一次启动时可能会弹窗询问是否允许网络连接要点允许。Linux 上如果你用的是云服务器或者带 ufw 的系统需要放行对应端口sudo ufw allow 8080改完之后重启 CLIProxyApi然后在另一台设备上测试把它的OPENAI_BASE_URL指向你这台机器的局域网 IP比如http://192.168.1.100:8080/v1。注意这里必须是局域网 IP不是127.0.0.1因为127.0.0.1在每台机器上都指自己。5.2 局域网共享时的安全底线开启局域网访问之后你的代理服务就相当于暴露在了整个网段内。这里有几个安全原则必须守住不要在不可信的网络比如公共 WiFi下开启0.0.0.0监听如果 CLIProxyApi 支持 token 鉴权一定要开启。通常是在配置里加一个API_KEY字段客户端请求时需要带上这个 key否则返回 401定期查看 CLIProxyApi 的访问日志确认没有异常来源的请求我实际在用的时候会给局域网共享配一个独立的服务端口并且只对办公内网段开放。操作上就是用防火墙规则限制来源 IP只允许公司网段访问其他网段一律拒绝。这样即使有人扫描到你的端口也没法直接调用。5.3 多台开发机如何统一配置团队场景下最烦的就是每台机器都要手动配一遍。我的做法是主机上维护一份标准的配置文件把服务商信息、模型映射、公共参数都写好密钥部分用占位符。其他同事克隆或者复制这份配置文件后只需要填上自己的密钥改一下host为127.0.0.1其余全部保持一致。更进一步如果你的 CLIProxyApi 支持从远程配置拉取可以把公共配置放在一个内部 Git 仓库里每台机器启动时自动拉取。不过这依赖具体版本的能力不是所有发行版都支持动手前先查一下文档。6. 实际操作中的高频问题和排查心法6.1 常见报错与解决方案速查表我把实操中频率最高的几个问题整理成一张表方便你遇到问题时直接对照现象可能原因解决方案请求返回 404baseUrl 路径拼接有误常见于多出/v1检查 CLIPROXYAPI 和工具侧的 baseUrl确保没有重复拼接请求返回 401服务商密钥错误或代理鉴权未通过先在 brew 终端用 curl 直接请求服务商接口验证密钥可用性请求超时网络不通或者服务商侧限流检查 CLIProxyApi 日志确认出网是否正常适当调大超时时间流式输出卡顿模型切换后兼容问题关闭流式模式测试或用deepseek-chat替代reasoner观察差异cc-switch 切换后不生效环境变量缓存未刷新重启终端或在当前终端重新 source 配置VSCode 扩展无法连接扩展不知道本地代理的存在重启 VSCode检查扩展设置里的 base URL 是否指向 8080Mac 无法打开 cc-switch未处理应用隔离属性执行xattr -dr com.apple.quarantine /Applications/cc-switch.app6.2 排查思路排序先分段再定位系统性地排查问题时我一般按这个顺序来第一步确认目标服务商接口本身可用。用 curl 直接请求curl https://api.deepseek.com/v1/models \ -H Authorization: Bearer sk-你的密钥如果这一步都返回错误那就是服务商密钥或网络问题跟代理配置无关。第二步确认 CLIProxyApi 自身转发是否正常。看它的启动日志和请求日志如果日志里有收到请求但转发失败的记录问题定位在路由配置上如果日志里根本没收到请求问题定位在客户端配置上。第三步确认客户端工具用的地址和端口对不对。在 Codex 或者 VSCode 里执行一个最简单的请求看 CLIProxyApi 日志有没有动静。没有动静说明客户端可能根本连的不是这个端口重点检查环境变量和设置项。这个顺序的逻辑是先验证最底层的能力再逐层往上查配置。跳步排查很容易浪费时间比如你花半小时改 Codex 的配置最后发现其实是 DeepSeek 密钥过期了这种亏我吃过不止一次。6.3 一些能省时间的操作习惯排障多了之后我总结出几个能极大提高效率的习惯CLIProxyApi 的日志窗口时刻开着不要关。它就是你的第一手证据来源请求成不成功、转发到哪个地址、响应码是多少全在里面修改配置后习惯性重启一下服务进程。多数配置改动需要重启才能生效别以为改完保存就完事了每个服务商的密钥用前先在服务商控制台里确认状态是启用避免拿着一个失效密钥排查了半天用版本管理工具管理配置文件的变更记录。这样哪天改坏了git diff一眼看出改了哪里git checkout一键还原在 cc-switch 里给每个服务商起一个看得懂的名字比如deepseek-日常、openai-官方、deepseek-reasoner-重活不要用默认的 provider 编号。切换的时候一眼就能选对7. 进阶技巧把效率再往上顶一档7.1 用模型映射实现一个工具吃百家饭CLIProxyApi 的modelMapping是我最喜欢的特性因为它实现了真正的请求不改模型随便换。举个例子我把 Codex 请求的gpt-4o映射到了三个不同服务的模型上平时默认走 DeepSeek高峰期切到其他服务Codex 侧完全无感知。这意味着什么意味着你的工具配置只需要写好一次之后所有的切换成本都是零。与其在工具里改模型名适配不同的服务商不如统一在 CLIPROXYApi 里管好映射。另外合理利用映射还能做资源分级。轻度任务走便宜的deepseek-chat重度任务走deepseek-reasoner需要国外服务时切到对应 provider。控制成本和保证体验可以兼得。7.2 配合 cc-switch 的快速回退机制cc-switch 在你切换服务商的时候会保留上一份配置的快照。如果新切换的服务商出了问题你可以一键回退到之前的配置。我的建议是切到新的服务商之前先确认旧配置在本地有备份切换后立刻跑一个简单的请求验证不要等真正写代码才发现不能用如果新服务商有问题立刻回退不要硬撑着排查时间成本太高这种先切后验不行就退的思路本质上跟线上发布系统的灰度回滚是一个道理。小工具的机制虽然简单用好了一样能救命。7.3 把启动流程做成一条命令完全配好之后我把整个启动流程写成了一个 shell 脚本放在家目录下#!/bin/bash # 启动 CLIProxyApi cd ~/CLIProxyApi nohup npm start cli-proxy.log 21 echo CLIProxyApi started on port 8080然后给脚本加执行权限chmod x ~/start-dev-proxy.sh。以后每次开机终端里一行命令就能把整个代理服务拉起来日志被重定向到cli-proxy.log想查看随时tail -f cli-proxy.log。这里再分享一个细节不要用sudo来启动这类本地代理服务本地端口 8080 本身就是普通用户权限范围不需要提权。用sudo反而容易引入权限问题和安全隐患。8. 一些掏心窝子的经验总结这套 CLIProxyApi cc-switch 的组合我用了大概一个多月最大的感受是配置这件事一旦做到了一处修改、全局生效整套开发体验会上一个台阶。以前我切一次服务商光改环境变量就要折腾好几分钟现在点一下界面等两秒继续干活完事。有几个小建议算是实操下来的体感第一刚开始搭建的时候不要贪多。先把最常用的一个服务商配置好跑通一条链路再加第二个、第三个。一次配三个 provider 如果链路不通你很难判断是哪个环节出了问题。第二日志这个习惯真的值得坚持。CLIProxyApi 的日志不要随手关掉它在排查问题时提供的信息比任何文档都准确。我在多次排障中都是先看日志再动手改配置基本能做到一次改对。第三cc-switch 的更新频率不低隔一段时间可以去仓库看看有没有新版本。新版本通常会修复一些边界情况的问题比如特定服务商配置模板过期、环境变量刷新不彻底等。升级前看一眼 release notes确认不影响现有配置。最后再提醒一次安全这件事局域网代理确实方便但一定记得给服务加上访问鉴权只在可信任的网络环境里开放。这个底线守住了工具带来的效率增益才是实打实的。用着顺手的组合不容易凑这套配置如果你也是 AI 编程助手的重度用户建议找个下午集中试一遍把链路从零到一跑通后面就是稳定的收益期。我实际用下来值回折腾的时间。
