企业官网建设流程全解析

先说实话，这个组合解决了一个特别实在的痛点：手上同时用着 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，具体要看仓库里是否维护了对应的 formula
• Windows 用户：下载.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结尾，照抄官方文档即可，多一个斜杠少一个斜杠都可能导致 404
• apiKey：对应服务商的密钥，只存在这个文件里，其他工具统一从这里读，不用到处复制粘贴
• 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-chat，Codex 本身并不知道后端已经换了模型，它还是按 GPT 的交互逻辑去用。大多数场景没问题，但个别依赖特定模型能力的工具特性可能表现不一样。这不是配置的问题，是模型本身能力差异决定的，心里有数就好。

3.3 在 cc-switch 中管理多个服务商配置

cc-switch 的图形界面非常直观，主界面就是一个服务商列表。首次使用的时候，它内置了几个常见的服务商模板，但更推荐自己手动添加，这样每个字段都是可控的。

添加服务商的路径一般是：主界面 → 新建/添加配置 → 填写服务商信息。需要填写的字段跟 CLIProxyApi 的 provider 配置基本一一对应：名称、API 地址、密钥，以及一些额外的 Header 参数（如果你对接的服务商需要在请求头里加自定义字段）。

这里有一个容易踩坑的点：cc-switch 默认的配置模板里，很多服务商的api字段叫baseUrl，但有的服务商文档里叫base_url，还有的会写成endpoint。你在 cc-switch 里添加的时候，要看清楚它表单里字段的提示说明，以表单位准，不要照搬你从服务商文档里看来的变量名。

配置好所有服务商之后，cc-switch 主界面的列表就是你所有可选项。想切换的时候，点击目标服务商的"启用"按钮，它会自动做两件事：

1. 同步更新 CLIProxyApi 配置文件里的defaultProvider字段
2. 刷新环境变量相关的配置缓存

这个过程一般两三秒就完成，它会提示你"切换成功"，并且建议你重启正在使用的终端窗口，让环境变量重新加载。

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_URL="http://127.0.0.1:8080/v1" export OPENAI_API_KEY="local-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_URL：

export ANTHROPIC_BASE_URL="http://127.0.0.1:8080" export ANTHROPIC_API_KEY="local-proxy-key" export ANTHROPIC_MODEL="claude-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 一个完整的请求链路长什么样

为了方便理解整个链路，我把一次典型请求走的路由过程写出来：

1. 你在 VSCode 的 Codex 面板里输入一句话，点击发送
2. Codex 扩展读取配置的http://127.0.0.1:8080/v1作为 base URL
3. 请求带着模型名（比如gpt-4o）发到本地 8080 端口
4. CLIProxyApi 收到请求，根据defaultProvider判断要转发给 DeepSeek
5. CLIProxyApi 根据modelMapping把请求体里的gpt-4o改写成deepseek-chat
6. CLIProxyApi 把改写后的请求转发到https://api.deepseek.com/v1，同时附上你的 DeepSeek 密钥
7. DeepSeek 处理请求，流式返回结果
8. CLIProxyApi 把结果原样回传给 Codex，Codex 在界面上正常展示

整个过程在你看来就是：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 常见报错与解决方案速查表

我把实操中频率最高的几个问题整理成一张表，方便你遇到问题时直接对照：

6.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 2>&1 & 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 编程助手的重度用户，建议找个下午集中试一遍，把链路从零到一跑通，后面就是稳定的收益期。我实际用下来，值回折腾的时间。