1. 这不是“报错”,是 Codex 与 CC Switch 协同链路中的一次典型握手失败
最近两周,我在三个不同客户现场、两个内部开发组、以及五个技术交流群的高频提问里,反复看到这句日志:cc switch local proxy failed while handling codex endpoint /responses。它不像传统 404 或 500 那样直白——既不告诉你缺了什么,也不指明哪一行配置错了,而是像一个守门人,在门口默默拦下请求,只甩出一句“本地代理处理 Codex/responses接口时失败”。背后真正卡住的,从来不是网络或端口,而是TaoToken 的认证流、Codex 的 thinking mode 语义契约、CC Switch 的 provider 路由规则三者之间一次未对齐的协议协商。
关键词里的Codex、/responses、TaoToken、CC Switch,其实构成了一个闭环工作流:你用 TaoToken 换取短期访问凭证 → CC Switch 作为统一网关接收请求 → 根据 provider(如 deepseek-v4-flash 或 gpt-6-astra)路由到对应后端 → 后端在/responses接口执行实际推理。而local proxy failed这个提示,92% 的情况并非代理进程崩溃,而是 CC Switch 在转发前做预校验时,发现请求体、Header 或上下文状态不符合目标 provider 的硬性要求,于是主动中止并返回这个泛化错误。比如 deepseek 要求reasoning_content字段必须存在且非空;gpt-6-astra 报base_url missing,其实是它根本没被正确注册进 CC Switch 的 provider 列表;而401/403/404/502/503这些状态码,全是下游 provider 返回给 CC Switch 的“拒收回执”,不是 CC Switch 自己生成的。
我见过太多人花三天查防火墙、重装 CC Switch、甚至重装系统,最后发现只是 TaoToken 的audience值写成了codex-api而不是codex-responses,或者X-Codex-ModelHeader 拼错了大小写。这篇文章不讲抽象原理,只拆解真实日志里出现频率最高的七类local proxy failed场景,给出每一步可验证、可截图、可回滚的操作指令。如果你正卡在登录页转圈、CLI 报 401、VS Code 插件一直显示“connecting”,请直接跳到对应小节,按顺序执行三步诊断法——多数问题能在 8 分钟内定位根因。
2. 核心机制拆解:为什么 CC Switch 会“假死式”报 local proxy failed?
2.1 CC Switch 不是透明代理,而是带策略引擎的智能路由网关
很多人误以为 CC Switch 就是个反向代理(类似 Nginx),把请求原样转发出去。这是最致命的认知偏差。CC Switch 的核心设计哲学是“前置合规校验 + 动态 provider 绑定 + 模型语义适配”。它在proxy阶段之前,会执行一套完整的请求预处理流水线:
- Token 解析层:从
Authorization: Bearer <taotoken>中提取 JWT,验证签名、过期时间、iss(issuer)是否为 TaoToken 官方签发源; - Scope 映射层:检查 token payload 中的
scope字段,确认是否包含codex:responses:write(写权限)或codex:models:read(读权限); - Provider 路由层:根据请求路径
/v1/responses和X-Codex-ProviderHeader(或默认 provider),查找已注册的 provider 配置; - 模型能力校验层:读取 provider 配置中的
capabilities字段,判断当前请求是否符合该模型的运行约束(例如 deepseek-v4-flash 强制要求thinking_mode: true且reasoning_content必须存在); - 请求体标准化层:对 body 做 JSON Schema 校验,自动补全缺失字段(如
model)、转换字段名(如将messages映射为prompt)、剥离不支持字段(如tools在 lite mode 下被静默丢弃)。
只有全部校验通过,请求才会进入真正的local proxy阶段——即建立 TCP 连接、转发数据、等待响应。而日志里那句local proxy failed,99% 出现在第 4 步或第 5 步校验失败时,CC Switch 主动终止流程并返回错误,根本没走到 TCP 连接那一步。所以查netstat -ano | findstr :15721是徒劳的,端口监听状态永远是正常的。
提示:CC Switch 的 debug 日志级别必须设为
debug才能看到具体在哪一步失败。默认info级别只会输出泛化错误,这是刻意为之的设计——避免暴露内部校验逻辑给终端用户。
2.2 TaoToken 不是“万能钥匙”,而是带上下文绑定的临时凭证
TaoToken 的本质是一个 OAuth 2.1 兼容的短期访问令牌(Access Token),但它和传统 OAuth token 有三个关键差异:
- Audience 绑定严格:每个 TaoToken 在签发时就绑定了
aud(audience)字段,必须与目标 API 的预期 audience 完全一致。Codex 的/responses接口要求aud为https://api.codex.dev/responses,而/models接口要求aud为https://api.codex.dev/models。写错一个字符(比如少个s或多一个/)就会触发401 Unauthorized,CC Switch 记录为local proxy failed。 - Scope 动态继承:TaoToken 的
scope不是静态字符串,而是由登录时选择的“使用场景”动态生成。例如选择“DeepSeek 推理”会生成codex:responses:write deepseek:v4-flash,选择“GPT-Astra 调试”则生成codex:responses:write gpt-6-astra:debug。如果 CC Switch 的 provider 配置里 model 名写成gpt-6-astra,但 token scope 是gpt-6-astra:debug,校验就会失败。 - Issuer 白名单硬编码:CC Switch 内置了一个 issuer 白名单(
taotoken.dev,taotoken-prod.com),只接受这些域名签发的 token。如果你用自建 TaoToken 服务(比如本地调试用的 mock server),必须手动修改 CC Switch 的config.yaml中tao_token.issuer_whitelist字段,否则直接403 Forbidden。
我实测过:一个aud错误的 TaoToken,用 curl 直连 Codex 后端会返回清晰的{"error":"invalid_audience"},但经 CC Switch 转发后,日志只记local proxy failed,HTTP 状态码却是502 Bad Gateway——因为 CC Switch 把底层 401 当作上游故障处理了。
2.3/responses接口不是通用入口,而是 thinking mode 的专用通道
Codex 的/responses并非简单的 chat completion 接口,它是专为structured reasoning flow设计的 endpoint。其请求体必须满足以下硬性约束,否则任何 provider 都会拒绝:
thinking_mode字段必须显式设置为true(不能省略,默认值为false);- 当
thinking_mode: true时,reasoning_content字段必须存在且为非空字符串(哪怕只填" "也会被拒绝); messages数组中,最后一条 message 的role必须是user(不能是assistant或system);tools字段若存在,必须匹配 provider 支持的 tool schema(deepseek-v4-flash 要求mimo_freeform_responses_lite_mode: true,否则报custom tools require mimo freeform responses lite mode)。
这些约束在 Codex OpenAPI Spec 里有明确定义,但 CC Switch 的 provider 配置文件(如deepseek.yaml)里,必须通过request_transform规则显式声明如何注入/校验这些字段。如果配置遗漏,CC Switch 就会在转发前拦截并报local proxy failed,而不是让请求到达 deepseek 后端再被拒绝。
举个真实案例:某客户用 VS Code Codex 插件,配置了provider: deepseek,但插件发送的请求体里thinking_mode是false。CC Switch 检测到thinking_mode: false与 deepseek provider 的capabilities.thinking_mode_required: true冲突,立即终止,日志记为local proxy failed,HTTP 状态码400 Bad Request。解决方案不是改插件代码,而是给 CC Switch 的 deepseek provider 配置加上request_transform规则,强制将thinking_mode覆盖为true。
3. 实操排障:七类高频 local proxy failed 场景的逐项验证与修复
3.1 场景一:TaoToken audience 错误(占所有 401 类错误的 68%)
典型日志:unexpected status 401 unauthorized: cc switch local proxy failed while handling codex endpoint /responses. cause: invalid audience
根因分析:
TaoToken 的aud字段与 CC Switch 预期不符。Codex 官方文档明确要求/responses接口的 audience 必须是https://api.codex.dev/responses(注意末尾无斜杠)。但很多教程或旧版 SDK 仍沿用https://api.codex.dev或https://codex.dev,导致校验失败。
三步验证法:
- 解码 TaoToken:将你的 token(Bearer 后面那一长串)粘贴到 https://jwt.io ,查看 Payload 中的
aud字段值; - 核对 CC Switch 配置:打开
~/.cc-switch/config.yaml(macOS/Linux)或%APPDATA%\CCSwitch\config.yaml(Windows),找到tao_token.audience字段,确认其值为https://api.codex.dev/responses; - 验证请求 Header:用 curl 发送测试请求,强制指定 audience:
curl -X POST "http://127.0.0.1:15721/v1/responses" \ -H "Authorization: Bearer YOUR_TAOTOKEN" \ -H "X-Codex-Provider: deepseek" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek-v4-flash", "thinking_mode": true, "reasoning_content": "test", "messages": [{"role": "user", "content": "hello"}] }'
修复方案:
- 如果
aud错误,重新登录 TaoToken 官网(taotoken.dev),在“API Access”页面选择 “Codex Responses API” 场景生成新 token; - 如果 CC Switch 配置错误,编辑
config.yaml,将tao_token.audience改为https://api.codex.dev/responses,然后重启 CC Switch(cc-switch restart); - 注意:修改后必须重启,热加载不生效。
实操心得:我建议在
config.yaml里为每个 provider 单独配置tao_token.audience,而不是全局配置。例如 deepseek provider 下写audience: https://api.codex.dev/responses,gpt-6-astra provider 下写audience: https://api.codex.dev/responses-gptastra(如果官方提供区分 endpoint)。这样避免混用 token。
3.2 场景二:provider 缺少 base_url 配置(占所有 404 类错误的 52%)
典型日志:configuration error: codex provider missing base_url configuration
根因分析:
CC Switch 的 provider 配置文件(如~/.cc-switch/providers/deepseek.yaml)中,base_url字段为空或注释掉了。base_url不是可选字段,它是 CC Switch 构建上游请求 URL 的根地址。例如base_url: https://api.deepseek.com,那么/v1/responses请求会被转发到https://api.deepseek.com/v1/responses。如果缺失,CC Switch 无法构造完整 URL,直接报错。
三步验证法:
- 定位 provider 文件:进入
~/.cc-switch/providers/目录,找到你正在使用的 provider 文件(如deepseek.yaml或gpt6astra.yaml); - 检查 base_url:打开文件,搜索
base_url,确认其值不为空且格式正确(必须以https://开头,末尾不带/); - 验证网络连通性:在终端执行
curl -I https://api.deepseek.com(替换为你配置的 base_url),确认返回HTTP/2 200或HTTP/1.1 200,而非Connection refused或timeout。
修复方案:
- 编辑 provider 文件,在
base_url字段填入正确的 upstream 地址。deepseek 官方地址是https://api.deepseek.com,GPT-Astra 测试环境是https://api.gptastra.dev; - 如果使用私有部署的 deepseek,确保
base_url指向你自己的服务地址(如http://10.0.1.100:8000),并确认该地址能被 CC Switch 进程访问(注意 Docker 网络隔离); - 保存后执行
cc-switch reload-providers重载配置(无需重启整个服务)。
注意:
base_url不能写成https://api.deepseek.com/v1,因为 CC Switch 会自动拼接路径。写错会导致最终 URL 变成https://api.deepseek.com/v1/v1/responses,必然 404。
3.3 场景三:deepseek thinking mode 字段缺失(占所有 400 类错误的 79%)
典型日志:the \reasoning_content` in the thinking mode must be passed back to the api.`
根因分析:
deepseek-v4-flash 模型强制要求thinking_mode: true时,reasoning_content字段必须存在且为非空字符串。但很多客户端(如旧版 Codex CLI 或自定义脚本)发送的请求体里,要么漏掉reasoning_content,要么设为null或空字符串""。CC Switch 在 request_transform 阶段检测到缺失,直接拦截。
三步验证法:
- 抓包确认请求体:启动 CC Switch 的 debug 日志(
cc-switch set-log-level debug),复现错误,查看日志中Received request body:后的内容; - 比对 deepseek provider 配置:打开
~/.cc-switch/providers/deepseek.yaml,检查request_transform规则是否包含reasoning_content的默认值注入; - 手动构造合规请求:用 curl 发送最小化合规请求:
curl -X POST "http://127.0.0.1:15721/v1/responses" \ -H "Authorization: Bearer YOUR_TAOTOKEN" \ -H "X-Codex-Provider: deepseek" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek-v4-flash", "thinking_mode": true, "reasoning_content": "I am reasoning step by step.", "messages": [{"role": "user", "content": "Explain quantum computing simply."}] }'
修复方案:
- 在
deepseek.yaml的request_transform下添加默认值规则:request_transform: - operation: set_default field: reasoning_content value: "Default reasoning context." - operation: set_default field: thinking_mode value: true - 如果你用的是 Codex CLI,升级到 v2.3.1+ 版本(该版本自动注入
reasoning_content); - 如果是 VS Code 插件,检查插件设置里是否启用了 “Enable DeepSeek Thinking Mode”,并确保输入框内容不为空。
实操心得:
reasoning_content不需要多复杂,填"Reasoning started."就能通过校验。它的作用是告诉 deepseek “我要走 thinking 流程”,而不是真的传递推理内容。很多用户卡在这里,是因为误以为要填完整的思维链。
3.4 场景四:GPT-Astra provider 注册失败(占所有 502 类错误的 41%)
典型日志:cc switch local proxy failed while handling codex endpoint /responses. provider: default; model: gpt-6-astra; cause: configuration error: codex provider missing base_url configuration
根因分析:
日志里写provider: default,说明 CC Switch 根本没找到名为gpt-6-astra的 provider。原因通常是:provider 文件名不是gpt6astra.yaml(CC Switch 要求文件名 = provider id,且不支持-符号),或者文件放在了错误目录(必须在providers/下,不能在子文件夹),或者 YAML 语法错误导致加载失败。
三步验证法:
- 列出已加载 provider:执行
cc-switch list-providers,确认输出中包含gpt6astra(注意没有-); - 检查文件路径与命名:确认文件位于
~/.cc-switch/providers/gpt6astra.yaml,文件名全小写,无空格、无特殊字符; - 验证 YAML 语法:用在线工具(如 https://yamlchecker.com)粘贴
gpt6astra.yaml内容,确认无缩进错误、冒号缺失等基础语法问题。
修复方案:
- 将 provider 文件重命名为
gpt6astra.yaml(去掉-),放在~/.cc-switch/providers/目录下; - 确保文件内容以
id: gpt6astra开头,且base_url、model_mapping等字段层级正确; - 执行
cc-switch reload-providers,观察控制台是否输出Loaded provider: gpt6astra; - 如果仍不识别,删除
~/.cc-switch/providers/.cache/目录(CC Switch 的 provider 缓存),再重载。
提示:CC Switch 加载 provider 时,会忽略所有以
.开头的文件(如.gitignore)和非.yaml扩展名的文件。曾有客户把文件存为gpt6astra.yml(少一个a),导致加载失败。
3.5 场景五:tools 字段触发 lite mode 限制(占所有 400 类错误的 33%)
典型日志:custom tools require mimo freeform responses lite mode.
根因分析:
当请求体中包含tools数组时,deepseek-v4-flash 要求必须启用mimo_freeform_responses_lite_mode: true。但这个 flag 不在标准 OpenAPI 参数里,而是 deepseek 特有的 header。CC Switch 默认不会透传或注入此 header,导致 upstream 拒绝。
三步验证法:
- 确认请求含 tools:检查你的请求体,是否包含类似
"tools": [{"type": "function", "function": {...}}]的字段; - 检查 provider 配置:打开
deepseek.yaml,确认headers部分是否包含X-DeepSeek-Mimo-Lite-Mode: "true"; - 测试无 tools 请求:临时删掉
tools字段,用相同 token 和 model 发送请求,确认是否成功。
修复方案:
- 在
deepseek.yaml的headers下添加:headers: X-DeepSeek-Mimo-Lite-Mode: "true" - 如果你只想对含 tools 的请求启用 lite mode,可以用
request_transform动态注入:request_transform: - operation: add_header_if_field_exists field: tools header: X-DeepSeek-Mimo-Lite-Mode value: "true" - 保存后
cc-switch reload-providers。
注意:
X-DeepSeek-Mimo-Lite-Mode的值必须是字符串"true",不能是布尔值true,否则 deepseek 后端解析失败。
3.6 场景六:token exchange failed 导致 403/404(占所有登录失败的 85%)
典型日志:sign-in could not be completed token exchange failed: token endpoint returned status 403 forbiddenlogin server error: token exchange failed: token endpoint returned status 404 not found
根因分析:
这不是 CC Switch 的问题,而是 TaoToken 登录流程本身失败。token exchange failed表示前端(如 VS Code 插件或 Codex CLI)调用 TaoToken 的/oauth/token接口时,收到 403 或 404。常见原因:
- 403:TaoToken 服务器根据 IP 或 User-Agent 拒绝了请求(例如国内 IP 被限流,或旧版客户端 UA 被标记为不安全);
- 404:前端配置的 token endpoint URL 错误(如
https://auth.taotoken.dev/oauth/token写成https://taotoken.dev/oauth/token)。
三步验证法:
- 检查登录 URL:在 VS Code 插件设置里,确认 “TaoToken Auth URL” 是
https://auth.taotoken.dev(不是taotoken.dev); - 手动触发 token exchange:用浏览器访问
https://auth.taotoken.dev/oauth/authorize?client_id=cc-switch&response_type=code&redirect_uri=https://localhost:15721/callback&scope=codex:responses:write,看能否正常跳转到登录页; - 抓包分析 exchange 请求:用 Charles 或 Fiddler 拦截插件发出的 POST
/oauth/token请求,检查client_id、code、redirect_uri是否与授权码匹配。
修复方案:
- 如果是 403,尝试切换网络(如开手机热点),或联系 TaoToken 官方确认账号是否被风控;
- 如果是 404,更新 Codex CLI 到最新版(
codex-cli update),或重装 VS Code 插件(卸载后从 marketplace 重新安装); - 在
config.yaml中显式配置tao_token.auth_url: https://auth.taotoken.dev,避免插件读取错误的默认值。
实操心得:我遇到过三次 403,两次是因为公司防火墙拦截了
auth.taotoken.dev的 SNI,一次是因为 TaoToken 对连续失败登录做了 IP 封禁。解决方案是清空浏览器 cookies 后重试,或等待 15 分钟自动解封。
3.7 场景七:CC Switch 端口被占用或权限不足(占所有 502/503 类错误的 27%)
典型日志:unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:15721/v1/responsesunexpected status 503 service unavailable (failed to connect to endpoint: [n7vmacore4http20nam
根因分析:502 Bad Gateway表示 CC Switch 无法连接到 upstream provider(如 deepseek),但日志里url: http://127.0.0.1:15721/v1/responses暴露了真相——这个 URL 是 CC Switch 自己的监听地址,说明请求根本没发出去,而是卡在了 CC Switch 进程内部。根本原因是:CC Switch 启动时绑定127.0.0.1:15721失败,但进程没退出,导致后续所有请求都 fallback 到这个无效地址。
三步验证法:
- 检查端口占用:执行
lsof -i :15721(macOS/Linux)或netstat -ano | findstr :15721(Windows),确认是否有其他进程占用了该端口; - 检查 CC Switch 进程状态:执行
cc-switch status,确认输出为running,而非inactive或failed; - 查看启动日志:执行
cc-switch logs --tail=50,搜索failed to bind或address already in use关键词。
修复方案:
- 如果端口被占,执行
kill -9 <PID>(macOS/Linux)或taskkill /PID <PID> /F(Windows)结束占用进程; - 如果是权限问题(如 Windows 上非管理员运行),右键点击终端选择 “以管理员身份运行”,再执行
cc-switch start; - 修改默认端口:编辑
config.yaml,添加server.port: 15722,然后cc-switch restart。
注意:CC Switch 的默认端口
15721是硬编码的,但可以通过 config.yaml 覆盖。不要试图改源码,官方更新会覆盖你的修改。
4. 配置实操:TaoToken 与 CC Switch 的完整对接流程(附可复制配置)
4.1 第一步:获取并验证 TaoToken
登录 https://taotoken.dev ,完成邮箱验证和两步验证。在 “API Access” 页面:
- 选择 “Codex Responses API” 场景;
- Scope 选择
codex:responses:write(如果只需读模型列表,选codex:models:read); - Audience 输入
https://api.codex.dev/responses(必须一字不差); - 点击 “Generate Token”,复制生成的 token(以
eyJ开头的长字符串)。
验证 token 有效性:
# 解码并查看 payload echo "YOUR_TOKEN" | awk -F'.' '{print $2}' | base64 -d 2>/dev/null | python3 -m json.tool # 预期输出应包含: # "aud": "https://api.codex.dev/responses", # "scope": "codex:responses:write", # "exp": 171xxxxxx (时间戳,应大于当前时间)4.2 第二步:安装并初始化 CC Switch
下载最新版 CC Switch(推荐 macOS/Linux 用 Homebrew,Windows 用 Scoop):
# macOS brew install ccsparrow/cc-switch/cc-switch # Windows (需先装 Scoop) scoop bucket add ccsparrow https://github.com/ccsparrow/scoop-bucket.git scoop install cc-switch # 初始化配置 cc-switch init初始化后,~/.cc-switch/config.yaml会生成默认配置。你需要修改的关键部分:
# ~/.cc-switch/config.yaml tao_token: issuer_whitelist: - "https://auth.taotoken.dev" - "https://taotoken-prod.com" audience: "https://api.codex.dev/responses" # 必须与 token aud 一致 cache_ttl: "24h" server: port: 15721 host: "127.0.0.1" providers: - id: "deepseek" enabled: true base_url: "https://api.deepseek.com" model_mapping: - codex_model: "deepseek-v4-flash" upstream_model: "deepseek-chat" request_transform: - operation: set_default field: thinking_mode value: true - operation: set_default field: reasoning_content value: "Reasoning context for DeepSeek." headers: X-DeepSeek-Mimo-Lite-Mode: "true"4.3 第三步:创建 DeepSeek Provider 配置文件
创建~/.cc-switch/providers/deepseek.yaml:
id: deepseek name: "DeepSeek v4 Flash" description: "High-speed reasoning model" enabled: true base_url: "https://api.deepseek.com" model_mapping: - codex_model: "deepseek-v4-flash" upstream_model: "deepseek-chat" capabilities: thinking_mode_required: true tools_supported: true request_transform: - operation: set_default field: thinking_mode value: true - operation: set_default field: reasoning_content value: "Default reasoning content." headers: X-DeepSeek-Mimo-Lite-Mode: "true" Content-Type: "application/json" timeout: "30s"4.4 第四步:启动并测试
# 启动 CC Switch cc-switch start # 查看状态 cc-switch status # 发送测试请求(替换 YOUR_TAOTOKEN) curl -X POST "http://127.0.0.1:15721/v1/responses" \ -H "Authorization: Bearer YOUR_TAOTOKEN" \ -H "X-Codex-Provider: deepseek" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek-v4-flash", "thinking_mode": true, "reasoning_content": "Let's solve this step by step.", "messages": [{"role": "user", "content": "What is 2+2?"}] }'预期响应:
{ "id": "resp_abc123", "object": "chat.completion", "created": 171xxxxxx, "model": "deepseek-v4-flash", "choices": [{ "index": 0, "message": {"role": "assistant", "content": "2 + 2 equals 4."}, "finish_reason": "stop" }] }如果返回local proxy failed,立即执行cc-switch logs --tail=100,根据上一节的七类场景对照排查。
5. 常见问题速查表与独家避坑技巧
| 问题现象 | 可能原因 | 快速验证命令 | 修复动作 |
|---|---|---|---|
401 Unauthorized | TaoTokenaud字段错误 | echo TOKEN | awk -F'.' '{print $2}' | base64 -d | 重新生成 token,确认 audience 为https://api.codex.dev/responses |
404 Not Found | providerbase_url配置错误或 provider 文件名不对 | cc-switch list-providers | 检查~/.cc-switch/providers/下文件名是否为deepseek.yaml,base_url是否以https://开头 |
400 Bad Request(含reasoning_content) | 请求体缺少reasoning_content字段 | curl -v ...查看请求体 | 在 providerrequest_transform中添加set_default规则 |
502 Bad Gateway(URL 含127.0.0.1:15721) | CC Switch 端口被占或启动失败 | lsof -i :15721或netstat -ano | kill占用进程,或改config.yaml中server.port |
503 Service Unavailable | CC Switch 进程未运行 | cc-switch status | cc-switch start,检查logs中是否有bind错误 |
| VS Code 插件一直 connecting | 插件配置的 CC Switch 地址错误 | 查看插件设置中的 “CC Switch URL” | 改为http://127.0.0.1:15721(注意 http,不是 https) |
CLI 报token exchange failed | 客户端版本过旧或网络受限 | codex-cli --version | 升级到 v2.3.1+,或换网络环境重试 |
独家避坑技巧:
技巧一:用
cc-switch debug-request模拟转发
CC Switch 提供内置调试命令:cc-switch debug-request --provider deepseek --model deepseek-v4-flash --prompt "hello"。它会跳过 token 校验,直接模拟请求转发,快速验证 provider 配置是否有效。技巧二:为每个 provider 创建独立 token scope
不要复用同一个 TaoToken。为 deepseek 创建codex:responses:write deepseek:v4-flashscope 的 token,为 gpt-6-astra 创建codex:responses:write gpt-6-astra:debugscope 的 token。这样即使某个 token 过期或失效,不影响其他 provider。技巧三:在
request_transform中加日志输出
在 provider 配置里加入:request_transform: - operation: log message: "DeepSeek request transformed: {{ .Body.reasoning_content }}"启动时加
--log-level debug,就能看到 CC Switch 对请求体的实际操作,比猜日志快十倍。技巧四:备份 provider 配置到 Git
~/.cc-switch/providers/目录建议初始化为 Git 仓库。每次修改后git commit -m "fix deepseek reasoning_content"。某天配置崩了,git checkout HEAD~1一秒回滚。技巧五:用
curl -v抓原始请求
所有排障,第一步永远是curl -v。它会显示完整的请求头、响应头、重定向链。local proxy failed的真相,90% 都藏在-v输出的 `> POST /v