CCSwitch 启动后端口冲突怎么办？

CCSwitch 配置看起来没问题，却启动失败、Codex 调用超时，或者请求走到旧代理，很多时候不是 Key 错了，而是本地端口和代理链路已经被别的服务占用。

适用场景：配置没改，但本地突然连不上

这篇适合 CCSwitch 启动报端口占用、浏览器代理正常但 Codex 调用失败、本地开发服务和模型接口代理抢端口、团队文档里的端口与实际不一致等情况。如果是证书、DNS 或 API 地址问题，可以先看 CCSwitch 配好后一直连接失败怎么办；如果调用地址总是旧的，可结合 Codex 调用的 API 地址为什么总是旧的。

先画出本地请求链路

不要一上来重装。先写清楚 Codex、CCSwitch、本地代理、浏览器、上游 AI 模型接口之间的路径：Codex 读取哪个环境变量，指向哪个本地端口，CCSwitch 再转发到哪个 API 地址。链路画出来后，端口冲突通常会变成一个具体进程，而不是“网络不通”。

操作步骤：按端口、进程、配置三层查

1. 查端口是否被占用

在 Windows 上可以先看常用端口，例如本地代理、开发服务和工具默认端口：

Get-NetTCPConnection -LocalPort 7890 -ErrorAction SilentlyContinue |
  Select-Object LocalAddress,LocalPort,State,OwningProcess
Get-Process -Id <PID>

不要看到占用就直接结束进程。先确认它是不是浏览器代理、开发服务器、旧版 CCSwitch 或另一个模型调用工具。

2. 查 Codex 实际读取的地址

同一台机器上，终端环境变量、配置文件和 CCSwitch 默认 profile 可能不一致。团队共享配置漂移时，可以参考 团队里的 CCSwitch 配置不一致怎么排查，把本机 profile、模型名和 API 地址输出成一张表。

3. 查代理链路是否套娃

常见错误是浏览器走一个代理，Codex 走另一个代理，CCSwitch 又转发到第三个地址。短期能跑通，长期很难定位超时和 401。AI API 接入时要保留 request_id、模型名、profile 和上游地址，方便判断请求到底经过了哪一层。

4. 改端口后同步文档和测试

如果确实需要改端口，不要只改自己机器。文档、环境变量示例、启动脚本、Codex 任务说明和固定测试提示词都要同步。多模型路由规则可参考 CCSwitch 多模型怎么按任务切换。

常见问题/避坑：端口冲突经常被误判成模型问题

第一个坑是只看上游错误码，不看请求有没有到达上游。第二个坑是本地启动了两个同类工具，后启动的工具改了端口，Codex 仍指向旧端口。第三个坑是公司代理、系统代理和工具代理叠加，导致偶发超时。

第四个坑是把测试 profile 的端口写进正式脚本。测试和正式 Key 隔离可参考 CCSwitch 怎么区分测试 Key 和正式 Key。端口、Key 和模型名要一起看，否则你可能修好了连接，却把请求发到错误账号。

如果团队里多人共用一份说明，端口变更还要同步到文档、截图和固定测试命令。只在自己电脑上改通，其他同事仍会按旧端口配置 Codex，后续排查又会变成“我这里正常、你那里失败”的循环。

如果端口查不到占用，但 Codex 仍无法访问，继续检查防火墙、IPv4/IPv6 绑定、管理员权限、代理规则和终端重启。很多环境变量只在新开的终端生效，旧终端里的 Codex 仍拿着旧地址。这个现象在开发者 AI 调用和 AI 自动化办公脚本里都很常见。

我建议每次调整 CCSwitch 本地端口后都跑一条固定测试：简单中文回答、JSON 输出、一次长文本摘要和一次失败输入。模型命名治理可参考 CCSwitch 模型名总填错怎么办，把端口变更也纳入同一张配置表。

检查清单：端口冲突排查顺序

• 是否列出 Codex、CCSwitch、本地代理和上游接口的完整链路。
• 是否查到端口占用进程和进程来源。
• 是否确认 Codex 当前终端读取的是新地址。
• 是否排除系统代理、浏览器代理和工具代理叠加。
• 改端口后是否同步文档、脚本和团队 profile。
• 是否用固定提示词验证简单回答、JSON 输出和错误输入。

验收标准：请求路径可解释

合格的 CCSwitch 端口排查，应能说明每个请求从本地哪一个端口出发，经过哪一层代理，到达哪个 AI 模型接口。永沃云枢建议把端口、profile 和 CCSwitch 配置专题 一起维护，后续在 https://ai.jn83.com 做 Codex 接入和模型调用管理时，减少“配置看起来没错但就是不通”的时间损耗。