cc-switch 配置：Claude Code 连接 Azure OpenAI

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 系列（必须配置）：

bash 复制代码

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 字段：

json 复制代码

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

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

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

GPT-4 配置：

json 复制代码

{
  "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 配置：

json 复制代码

{
  "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

五、核心教训

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

结语

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