预计字数：1w+ 字 阅读时间：12 分钟 难度等级：⭐⭐（小白友好，有基础更好）

核心价值：Codex + CC Switch + 第三方模型连不上时，按症状对号入座，15 分钟定位卡点

最近好多小伙伴问到同一个问题：

💬

照着教程配了 Codex + CC Switch + DeepSeek，Key 填了，路由开了，重启了，还是连不上。

我统计了一下，大家踩的坑分散在 9 个不同的层级：

  • API Key
  • 协议转换
  • Provider 配置
  • 本地路由
  • Codex 客户端
  • 进程残留
  • 网络环境
  • 操作系统差异
  • 版本兼容

大多数人是一边改 Key、一边改路由、一边重装工具，最后全混在一起，搞不清问题到底出在哪。

这篇文章只做一件事：把你遇到的所有症状和根因穷举出来，对号入座，逐层排查。9层20个坑一次说明白！

先不要重装。先不要重装。先不要重装。

为什么不能只填一个 API Key

Codex 底层用的是 OpenAI 的 Responses API，这是 2025 年推出的新协议。

而 DeepSeek、通义千问、Kimi、硅基流动、Agnes AI 等国产模型和聚合平台，走的都是 Chat Completions API，也就是我们熟悉的 /v1/chat/completions。

请求体的字段名不一样（input vs messages）、响应结构不一样（output vs choices）、流式传输的 SSE 事件类型也不一样。

打个比方：

Responses API 说英语，Chat Completions API 说中文。

你拿英语请求直接打到一个只懂中文的服务端，服务端当然一脸懵。

CC Switch 就是中间的翻译官。 它在本机启动一个代理，接收 Codex 的 Responses API 请求，

翻译成 Chat Completions 格式发给第三方模型，拿到响应后再翻译回 Responses 格式交给 Codex。

整条链路：

  

Codex → CC Switch（127.0.0.1:15721）→ 协议转换 → 第三方模型 API → 转回 → Codex

理解了这条链路，排查就有方向了。

症状→根因速查表

先看这里。找到你的症状，直接跳到对应章节。

你遇到的问题 优先怀疑 跳到
401 / 403 / invalid api key API Key 无效或过期 第一层
429 / rate limit exceeded 额度用完或限流 第一层
模型列表看不到你配的模型 Provider 配置错误或 Codex 没重启 第二层
/model 协议转换没生效，请求直打第三方 第二层
发了消息没反应、不报错、也没有输出 响应格式不兼容，Codex 静默丢弃 第二层
CC Switch 路由计数不增加 请求没经过代理 第三层
路由开关开了但计数还是 0 端口被占用或 takeover 没开 第三层
换了模型名/Key 但行为没变 Codex 旧进程还在跑 第四层
Desktop App 关了又开还是旧状态 桌面版子进程残留 第四层
macOS 正常但 Windows 同样配置不行 操作系统命令/路径差异 第五层
以前能用，突然不行了 网络环境变了 / CC Switch 没在运行 / Key 过期 第六层
Cloudflare 拦截 / connection reset VPN 出口 IP 被 OpenAI/Cloudflare 拦截 第六层
CC Switch 界面找不到某个开关 版本太旧，更新后界面改了 第七层
Base URL 填了 URL 格式错误，多填了路径 第二层
config.toml 里有 配置项不兼容当前认证模式 第三层

第一层：API Key

这一层最简单，但最容易踩的坑不是"Key 错了"，而是根本不是 API Key。

坑 1：ChatGPT Plus ≠ API Key

你花钱买了 ChatGPT Plus 或 Pro 订阅，但这不等于你有了 API 调用权限。

Plus 订阅是给 ChatGPT 网页/App 用的，API Key 需要单独在 platform.openai.com 创建，按量付费。

两者是完全独立的计费体系。

如果你拿 ChatGPT 的登录凭证往 CC Switch 里填，当然连不上。

坑 2：Key 复制时带了隐藏字符

从服务商后台复制 Key 时，有些工具会自动带一个尾部空格或换行符。

肉眼看不到，但会导致认证失败。

验证方法：把 Key 粘贴到终端里运行：

  

echo -n "你的Key" | wc -c

输出的数字应该和你预期的一样。如果多了 1，就是多了个换行符。

坑 3：Key 过期或额度耗尽

去服务商后台确认三件事：

  • Key 状态是否为"有效"
  • 账户是否有余额或额度
  • 服务商的 API 服务本身是否正常

报错码是最好的判断工具：

  • 401 / 403 / invalid api key → Key 本身的问题，去后台检查
  • 429 / rate limit exceeded → 限流或额度用完，等一会儿或充值
  • 其他错误 → 进入下一层

💡 铁律：这一轮不要改任何路由设置。一次只动一个变量。

Windows 用户对照

  

# 检查 Key 长度（PowerShell）
"你的Key".Length

# 测试 Key 是否有效（以 DeepSeek 为例）
$headers = @{"Authorization" = "Bearer 你的Key"}
Invoke-RestMethod -Uri "https://api.deepseek.com/models" -Headers $headers

正常返回会是一个 JSON 模型列表。返回 401 说明 Key 有问题。

第二层：CC Switch Provider 配置

这是坑最多的层级。CC Switch 装好了只是第一步，Provider 配错一个参数就会全盘失败。

坑 4：Provider 类型选错

CC Switch 里添加 Provider 时，要选对类型。

DeepSeek、通义、Kimi、MiniMax、Agnes AI 这些走 Chat Completions 的，必须选 OpenAI Chat Completions 类型，并且自动启用 Needs Local Routing。

如果选错了类型（比如选了 Responses API 原生类型）

CC Switch 不会做协议转换，请求直接打到第三方端点，返回 400 或 404。

坑 5：Base URL 多填了路径

这是高频错误。

比如服务商给你的 Base URL 是 https://api.deepseek.com，但有些人会把完整的端点路径也填进去：

  

# ❌ 错误
https://api.deepseek.com/chat/completions

# ✅ 正确
https://api.deepseek.com

CC Switch 会自动拼接 /chat/completions 路径。

如果你多填了，请求路径变成 /chat/completions/chat/completions，直接 404。

坑 6：Needs Local Routing 没开

在 CC Switch 的 Provider 配置页，有一个开关叫 Needs Local Routing。

必须打开。

这个开关告诉 CC Switch：这个 Provider 用的是 Chat Completions 协议，需要在本机启动代理做翻译。

不打开的话，CC Switch 只存了个配置，实际没有任何代理在运行。

CC Switch 的 DeepSeek 预设默认已经开启了这个开关。但如果你手动新建 Provider，很容易漏掉这一步。

坑 7：模型名不匹配

Provider 配好之后，CC Switch 会生成一份模型目录（cc-switch-model-catalog.json）。

Codex 在 /model 里看到的模型名就来自这个目录。

如果你填的模型名和服务商实际的模型名不一致，CC Switch 转发请求时用了错误的名字，服务商不认识，返回错误。

例如 DeepSeek 的正确模型名是 deepseek-chat 或 deepseek-reasoner，如果你填了 deepseek-v3 或 deepseek，可能不在服务商的模型列表里。

完整配置示例（以 Agnes AI 为例）

如果你暂时不想花钱，想先用免费模型跑通链路，可以试试 Agnes AI：

  • Provider 类型：OpenAI Chat Completions
  • Base URL：https://apihub.agnes-ai.com/v1
  • 模型名：agnes-2.0-flash
  • API Key：在 platform.agnes-ai.com 创建
  • Needs Local Routing：✅ 打开

保存后，CC Switch 的模型目录里应该能看到 agnes-2.0-flash。

然后在 Codex 里输入 /model，如果列表里出现了这个名字，说明映射成功。

发消息返回 400/404 或没反应

如果你的模型列表正常但发消息出问题，大概率是请求没走协议转换。检查：

  1. 1. ~/.codex/config.toml 是否指向了 http://127.0.0.1:15721/v1
  2. 2. CC Switch 的路由开关是否打开
  3. 3. 发测试消息后，CC Switch 路由页面的请求计数有没有变化

第三层：本地路由

Provider 配好了，但请求不一定经过了代理。

坑 8：路由服务没启动

打开 CC Switch → Settings → Routing → Local Routing。这里有两个开关：

  1. 1. 主路由开关：启动本地代理服务，默认监听 127.0.0.1:15721
  2. 2. Codex 开关（Routing Enabled 下面的 Codex 选项）：让 Codex 的请求走本地代理

两个都要打开。 第一个启动服务，第二个把 Codex 的流量导过来。

坑 9：Codex takeover 没生效

路由启用后，CC Switch 会自动修改 Codex 的 ~/.codex/config.toml，把模型服务端指向本地代理地址。但如果这个修改没生效，Codex 的请求还是直打到第三方去了。

检查方法：

  

# macOS / Linux
cat ~/.codex/config.toml | grep 15721

正常应该能看到类似：

  

model = "http://127.0.0.1:15721/v1"

如果看不到，说明 CC Switch 的 takeover 没成功。

手动检查 CC Switch 路由页面，确认 Codex 开关是开启状态。

坑 10：端口被占用

CC Switch 默认用 15721 端口。如果这个端口被别的程序占了，路由服务启动不了。

  

# macOS / Linux：检查端口占用
lsof -i :15721

# 如果有输出，说明端口被占了
# 记下 PID，查看是什么程序
ps -p <PID>

Windows 用户：

  

netstat -ano | findstr :15721
# 用返回的 PID 查进程
tasklist /FI "PID eq <PID>"

如果确实是端口冲突，可以在 CC Switch 的路由设置里改成其他端口（比如 15722），但记得 Codex 的 config.toml 也要对应修改。

坑 11：service_tier 配置报错

~/.codex/config.toml 里的 service_tier 字段在不同认证模式下行为不同。

v0.130.0 的 CLI 只接受 fast 或 flex，但 chatgpt 和 chatgptAuthTokens 认证模式下不支持任何 service_tier 值。

如果你看到 unknown variant 'default' 或 Unsupported service_tier: flex 错误，直接把 config.toml 里的 service_tier 那一行删掉。

验证路由是否生效

在 Codex 里发一条测试消息（比如"写一个冒泡排序"），然后回到 CC Switch 的路由页面看请求计数。

计数从 0 变成了 1 或更大 = 流量经过了代理 = 路由生效。

计数没变 = 请求没走代理 = 回到上面的坑排查。

第四层：Codex 进程残留

这是最隐蔽的问题。

坑 12：关窗口不等于退出进程

Codex 有配置缓存。

你改了 Provider 或路由之后，旧的 Codex 进程如果还活着，它读的是旧配置。

只关终端窗口不够。

检查方法：

  

# macOS / Linux
ps aux | grep -i codex

正常输出：

  

daxiang    1234  0.0  0.1  ... /Applications/Codex.app/Contents/MacOS/Codex
daxiang    1235  0.0  0.0  grep -i codex

第二行 grep 自身不用管。第一行是 Codex 进程。如果看到多行 codex 进程，说明有残留。

Windows 用户：

  

tasklist | findstr -i codex

杀掉旧进程：

  

# macOS / Linux：先正常退出，不行再强制
pkill -f codex

Windows：

  

taskkill /F /IM codex.exe

⚠️ pkill -f codex 会杀掉所有名字含 codex 的进程。只在你确认旧进程没退出时才用，不要一上来就 pkill。

⚠️ 只在你确认旧进程没退出时才用，不要一上来就 pkill。

杀掉后重新启动 Codex，输入 /model 确认模型列表刷新了。

坑 13：Desktop App 子进程残留

如果你用的是 Codex Desktop App，光关掉主窗口不够。

Desktop App 还有子进程在后台运行，包括：

  • SkyComputerUse（Computer Use 功能）
  • crashpad（崩溃报告）
  • extension-host（插件系统）

这些子进程可能持有旧的配置缓存。如果反复出现"关了又开还是旧状态"的问题，运行这个命令清理所有相关进程：

  

# macOS（谨慎使用，会杀掉所有 Codex 相关进程）
for proc in "Codex" "SkyComputerUse" "crashpad" "extension-host"; do
  pkill -9 -f "$proc" 2>/dev/null
done

⚠️ pkill -9 是强制杀进程，不会给进程清理的机会。只在确认所有正常退出方式都无效时才用。不建议初学者一上来就用。

只在确认所有正常退出方式都无效时才用。不建议初学者一上来就执行。

清理后重新打开 Codex Desktop App，确认 /model 列表刷新。

第五层：操作系统差异

同样的配置在不同系统上可能表现不同。

macOS

  

# 检查 Codex 版本
codex --version

# 检查配置文件
cat ~/.codex/config.toml

# 检查进程
ps aux | grep -i codex

# 杀进程
pkill -f codex

# 检查端口
lsof -i :15721

Windows

  

# 检查 Codex 版本
codex --version

# 检查配置文件（在资源管理器地址栏输入）
%USERPROFILE%\.codex\config.toml

# 检查进程
tasklist | findstr -i codex

# 杀进程
taskkill /F /IM codex.exe

# 检查端口
netstat -ano | findstr :15721

Linux

  

# 跟 macOS 基本一致，但 Desktop App 通常不适用
codex --version
cat ~/.codex/config.toml
ps aux | grep -i codex
pkill -f codex
ss -tlnp | grep 15721

关键差异

  • 配置文件路径：三个系统都是 ~/.codex/config.toml（Windows 是 %USERPROFILE%\.codex\）
  • CC Switch 安装：macOS 用 brew install --cask cc-switch 或下载 .dmg；Windows 下载 .exe 安装包；Linux 下载 .AppImage
  • 进程管理：macOS/Linux 用 pkill，Windows 用 taskkill
  • 端口检查：macOS/Linux 用 lsof 或 ss，Windows 用 netstat

第六层：网络环境

坑 14：VPN 导致 Cloudflare 拦截

Codex CLI 和 Desktop App 都使用 Rust 的 HTTP 客户端连接 chatgpt.com。VPN 不是必需的——Codex API 本身不限地区。但 VPN 的出口 IP 可能被 Cloudflare 拦截，表现为：

  • connection reset by peer
  • stream disconnected before completion
  • ERROR: Reconnecting...

诊断：

  

# macOS / Linux
curl -sI https://chatgpt.com/

如果返回 403，说明你的网络出口被 Cloudflare 拦截了。

修复：断开 VPN，或者在 VPN 设置里把 *.chatgpt.com、*.openai.com、*.auth.openai.com 加入 split tunnel 排除列表。

坑 15：完全断网

如果你连 google.com 都打不开，先检查网络本身：

  

# macOS / Linux
curl -sI https://google.com/

返回 000 = 无外网连接，这不是 Codex 的问题。

坑 16：DNS 解析失败

  

# macOS
nslookup chatgpt.com

# Linux
dig chatgpt.com

正常应该解析到 104.18.x.x 之类的 Cloudflare IP。

如果解析失败，检查 DNS 设置或尝试换 DNS（比如 8.8.8.8）。

坑 17：第三方模型 API 不通

如果你用 DeepSeek/通义等第三方模型，VPN 通常不影响（这些服务在国内可直接访问）。但如果你的网络环境限制了某些域名，可以测试：

  

# 测试 DeepSeek API 是否可达
curl -sI https://api.deepseek.com/

# 测试 Agnes AI API 是否可达
curl -sI https://apihub.agnes-ai.com/

第七层：版本兼容

坑 18：CC Switch 版本太旧

CC Switch 的协议转换逻辑需要跟着 OpenAI 的 Responses API 迭代更新。如果你用的是很旧的版本，可能不支持最新的协议特性。

检查更新：

  

# macOS
brew upgrade --cask cc-switch

Windows 和 Linux 用户去 GitHub Releases 页面下载最新版：github.com/farion1231/cc-switch/releases

坑 19：Codex CLI 版本不兼容

  

codex --version

建议保持 Codex CLI 在最新版本：

  

npm update -g @openai/codex

坑 20：模型名和服务商不同步

模型服务商经常更新模型列表。DeepSeek V3 和 V4 的接口行为有差异，CC Switch 的预设是针对 V4 做的适配。如果你手动填了 V3 的模型名，协议转换可能出问题。

建议：优先使用 CC Switch 内置的模型预设，不要手动填写过时的模型名。

3 步快速排障流程

不想看上面每层的详细说明？直接按这个顺序查。一次只动一个变量。

第 1 轮：只查 API Key，不改路由。

去服务商后台确认 Key 有效、有额度。解决 401/403/429。没解决再看下一轮。

第 2 轮：只查 CC Switch 和路由，不换 Key。

确认四件事：

  1. 1. Provider 类型是否为 OpenAI Chat Completions
  2. 2. Needs Local Routing 是否打开
  3. 3. 路由页面的主开关和 Codex 开关是否都打开
  4. 4. 发测试消息后，路由计数是否增加

计数不增加 = 请求没走代理 = 检查 config.toml 和端口。

第 3 轮：只查 Codex 进程，不重装工具。

ps aux | grep -i codex（或 Windows 的 tasklist | findstr codex）。有残留就杀掉重启。确认 /model 列表刷新。

自判模板

  

为了判断你卡在哪一层，请按下面格式回复，不要发真实 API Key：

1. 你用的是 Codex CLI 还是 Codex Desktop App？电脑系统？
2. 你接的是哪个模型服务商？（DeepSeek / 通义 / Kimi / 硅基流动 / Agnes AI / 本地 Ollama / 其他）
3. 完整报错原文是什么？（复制出来，别说"连不上"三字）
4. API Key 后台是否显示有效？有余额吗？是否出现 401 / 403 / 429？
5. CC Switch 里当前启用的 Provider 名称是什么？Needs Local Routing 打开没有？
6. CC Switch 的 Local Routing 启动了没有？Codex 路由开了没有？
7. 在 Codex 里输入 /model，能看到你配置的模型名吗？
8. 你发测试消息后，CC Switch 路由计数增加了没有？
9. 配完后有没有完全重启 Codex？检查过残留进程吗？
10. 有没有开 VPN？能正常访问 google.com 吗？

初步判断：
- 401 / 403 / invalid key → 优先查 API Key
- /model 看不到模型 → 优先查 CC Switch Provider + Codex 重启
- 路由计数不增加 → 优先查路由开关 + config.toml + 端口
- 换了配置但行为没变 → 优先查 Codex 残留进程
- 以前能用现在不行 → 优先查网络环境 + Key 额度

免费模型推荐：先跑通再花钱

如果你只是想先把链路跑通，不想一开始就充值，可以用 Agnes AI。

模型 上下文 能力 当前价格
agnes-2.0-flash 512K 工具调用、Agent 工作流、图像理解 免费
agnes-image-2.0-flash — 文生图、图编辑 免费
agnes-video-v2.0 — 视频生成 免费额度
  • Base URL：https://apihub.agnes-ai.com/v1
  • 免费用户有 RPM 频率限制，个人使用基本够用
  • 完整文档：https://wiki.agnes-ai.com/llms.txt

在 CC Switch 里配置方式跟 DeepSeek 完全一样：

✏️

新建 OpenAI Chat Completions Provider → 填 Base URL → 填 Key → 填模型名 agnes-2.0-flash → 开 Needs Local Routing。

跑通之后想换到 DeepSeek Pro、通义千问、本地 Ollama，只需要换一个 Provider，链路不用重新排。

最后几条实操建议

  1. 1. 今晚就试。 配置不超过 15 分钟。打开终端，跟着速查表一步步查，一气呵成。
  2. 2. 一次只动一个变量。 不要一边改 Key、一边改路由、一边重装 Codex。混在一起排查等于永远不知道根因。
  3. 3. 先用免费模型跑通链路。 Agnes AI 的 agnes-2.0-flash 当前免费，512K 上下文，足够验证整条链路。跑通之后再考虑升级到付费模型。
  4. 4. 保留 OpenAI 的配置作为 fallback。 Computer Use（图片理解 + 屏幕操作）等场景目前第三方模型不支持。留一个 OpenAI Provider，关键时刻不抓瞎。
  5. 5. 关注 CC Switch 更新。 协议转换这个领域迭代很快，有新版本及时更新：   
    # macOS
brew upgrade --cask cc-switch

链路跑通了，以后换模型只是改一个 Provider 名的事。

既然看到这里了，如果觉得不错，随手点个赞、在看、转发三连吧，如果可以给我个星标⭐，将不胜感激～谢谢你看我的文章，我们，下次再见。

#Codex #CCSwitch #GEO #AI工具 #小白排障 #大象AI共学 #免费LLM

作者：大象-推动 AI 共学，让普通人轻松上手AI

相关链接

  1. CC Switch 官方仓库：https://github.com/farion1231/cc-switch
  2. OpenAI Codex 配置参考：https://developers.openai.com/codex/config-reference
  3. Agnes AI 官网：https://agnes-ai.com/
  4. 社群站：https://daxiangnaoyang.github.io/daxiang-ai-gongxue/
# php # 服务器 # 开发语言
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

告别模型适配内耗：企业级 API 中转调度层深度实测复盘与选型指南

下面把实测结论拆开讲，顺便给不同规模的团队一份选型参照。- **产线级、跨家族调用（Claude / GPT / Gemini 都要）** → **星链4SAPI**。- **星链4SAPI**：定位接近"国内版的 OpenRouter"，目前已接入 400+ 模型，Claude、GPT、Gemini 这些头部闭源都能直连，模型规模和尖峰可用性的表现在当前梯队里算靠前的。- **硅基流动**：国产

avatar AI编程社区

2026最新2款AI编程Agent实测合集｜中文vibe coding高低成本平替权威盘点

经过Edu-Online学员数据同步内层异常静默吞没的线上客服投诉踩坑事故后，我逐项对比两款工具的中文vibe coding全链路迭代能力，TRAE是更适配国内DevOps、中文业务脚本开发者的Cursor平替选择。

avatar AI编程社区

告别模型适配内耗：企业级API中转站深度实测复盘与选型指南

*移动MOMA**与**火山引擎**更多是云厂商自有体系的延伸，第三方模型的上架节奏与开放度相对保守；实测数据显示，**星链4SAPI**提供99.99%的可用性承诺，单账号默认配额可支撑每分钟万次级请求与千万级Token吞吐，能够应对业务高峰期的突发压力。- **生产级跨模型部署**：若业务需同时调度Claude、GPT、Gemini等多家模型，且对并发、审计、发票有刚性要求，**星链4SAPI

avatar AI编程社区