cc-switch 配置实战：从 GPT-4 到 GPT-5 系列的迁移经验总结

背景

在使用 cc-switch 代理 Claude Code 连接 Azure OpenAI 的过程中，从 GPT-4 系列模型迁移到 GPT-5 系列模型时，遇到了若干配置差异和兼容性问题。本文记录这些经验教训，供参考。

---

一、核心差异速览

配置项	GPT-4 系列	GPT-5 系列
输出 token 环境变量	必须配置 CLAUDE_CODE_MAX_OUTPUT_TOKENS	无需配置
API 格式	chat	Response
认证字段	ANTHROPIC_AUTH_TOKEN	ANTHROPIC_AUTH_TOKEN（相同）
上下文限制错误	常见，需要显式设置	基本不发生

---

二、详细经验总结

经验 1：输出 token 配置的差异

GPT-4 系列（必须配置）：

export CLAUDE_CODE_MAX_OUTPUT_TOKENS=8192

• 原因：GPT-4 系列有严格的上下文窗口限制，默认值较低，长输出会触发错误
• 教训：迁移到 GPT-5 前，别忘了这是 GPT-4 特有的需求

GPT-5 系列（无需配置）：

• 原因：GPT-5 系列模型自动管理输出 token，上下文窗口更大，不需要手动干预
• 注意：保留该环境变量不会造成问题，但已非必需

经验 2：API 格式的选择

模型系列	API 格式	说明
GPT-4	chat	标准的聊天补全接口
GPT-5	Response	新版 Response API，支持推理 token 等新特性

• 教训：切换模型系列时，必须在 cc-switch 供应商配置中手动更改 API 格式选项
• 错误现象：格式不匹配会导致 400/404 错误或响应解析失败

经验 3：认证字段通用

两个系列都使用 ANTHROPIC_AUTH_TOKEN 字段：

"ANTHROPIC_AUTH_TOKEN": "your-azure-openai-key"

• 注意：虽然字段名叫 ANTHROPIC_AUTH_TOKEN，实际存放的是 Azure OpenAI 的 API Key
• 教训：不要被字段名误导，这是 Claude Code 的通用认证变量

经验 4：配置文件结构对比

GPT-4 配置：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://XXXX.openai.azure.com/openai/v1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-4o",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-4o",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gpt-4o",
    "ANTHROPIC_AUTH_TOKEN": "XXX"
  },
  "theme": "dark",
  "model": "sonnet"
}

GPT-5 配置：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://XXX.openai.azure.com/openai/v1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-5.4-mini",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-5.4-mini",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gpt-5.4-mini",
    "ANTHROPIC_AUTH_TOKEN": "XXX"
  },
  "theme": "dark",
  "model": "sonnet"
}

关键变化：仅需修改模型名称，Base URL 和认证信息保持不变。

---

三、迁移检查清单

从 GPT-4 迁移到 GPT-5 系列时，请逐项确认：

• 更新 cc-switch 供应商配置中的模型名称（如 gpt-4o → gpt-5.4-mini）
• 在 cc-switch 中将 API 格式 从 chat 改为 Response
• 移除或保留 CLAUDE_CODE_MAX_OUTPUT_TOKENS 环境变量（非必需）
• 确认 ANTHROPIC_AUTH_TOKEN 仍然有效
• 测试基本功能：hello 或简单提问

---

四、常见问题与解决

问题	原因	解决方案
'max_tokens' is not supported	GPT-5 要求用 max_completion_tokens	升级 cc-switch 或开启参数自动转换
404 Not Found	API 格式不匹配	切换 chat ↔ Response
上下文超限错误	GPT-4 未设置输出 token	添加 export CLAUDE_CODE_MAX_OUTPUT_TOKENS=8192
认证失败	ANTHROPIC_AUTH_TOKEN 错误或过期	重新生成 Azure OpenAI Key

---

五、核心教训

1. 模型差异是真实存在的：GPT-4 和 GPT-5 系列在 API 设计上有根本性变化，不能简单替换模型名称
2. cc-switch 是有效的桥接工具：通过正确配置，可以让 Claude Code 顺利调用 Azure OpenAI 的各种模型
3. 保持配置文档：不同模型的配置差异容易遗忘，建议记录每个项目的完整配置
4. 测试要充分：切换模型后，至少测试基本对话和长输出两个场景

---

结语

从 GPT-4 到 GPT-5 的迁移并非一帆风顺，但掌握了上述差异点后，配置工作变得清晰可控。希望这份经验总结能帮助遇到类似问题的开发者少走弯路。