📖 CC‑Switch Codex 中转文档

CC‑Switch 中转 Codex API 文档

本网关使用 CC‑Switch 模式对接上游 Codex 服务，对外暴露标准 OpenAI‑兼容接口，客户端无需修改大量代码，替换 base_url 即可调用 Codex。

  • 网关地址：https://www.wdsf.com.cn/v1
  • 传输协议：HTTPS
  • Content‑Type：application/json
  • 客户端：OpenAI SDK / curl / 各类兼容客户端直接使用
  • 上游：Codex，CC‑Switch 负责密钥代理、模型路由、限流、日志

🔧 CC‑Switch 对接 Codex 原理

CC‑Switch模式：客户端携带网关Key，网关内部替换为 Codex 的 upstream key，转发请求到 Codex 上游，将上游响应原样透传给客户端。
  • 客户端 → CC‑Switch网关（使用网关sk‑xxx）：https://www.wdsf.com.cn/v1
  • 网关内部：替换 Authorization 为 Codex 的 Api‑Key，转发至 Codex 上游地址
  • 流式SSE响应完整透传，不截断；上游错误直接透传给调用方
  • 支持模型重命名映射，客户端模型名和上游Codex模型名可不一致
网关配置要点：在CC‑Switch后台添加通道，通道类型选择OpenAI兼容，上游地址填写Codex接口地址，填入Codex的api key，配置模型映射。

🔐 鉴权说明（客户端）

客户端请求头 Authorization 使用网关分配的 Key，格式 Bearer + key。
注意：客户端不要填写Codex原始key，全部交由CC‑Switch内部处理上游密钥。

Authorization: Bearer sk‑gateway‑xxxxxxxxxxxx
网关密钥请勿泄露，所有请求经过CC‑Switch代理到Codex上游。

📋 模型映射配置（CC‑Switch后台）

客户端传模型名 → CC‑Switch映射为Codex真实模型名向上游请求。示例配置：

客户端请求modelCodex上游真实模型说明
code‑davinci‑002code‑davinci‑002Codex代码补全模型
gpt‑3.5‑codexcode‑davinci‑002别名映射，客户端用这个名字访问codex
修改映射在CC‑Switch通道配置中设置模型重写，不需要修改客户端代码。

GET /v1/models

获取CC‑Switch网关暴露的模型列表，由CC‑Switch从Codex上游同步/配置返回。

curl示例
curl https://www.wdsf.com.cn/v1/models \
  -H "Authorization: Bearer sk‑gateway‑xxxxxxxxxxxx"
响应示例
{
  "object": "list",
  "data": [
    {
      "id": "code‑davinci‑002",
      "object": "model",
      "owned_by": "codex"
    }
  ]
}

POST /v1/chat/completions

对话接口；若Codex本身不支持chat，CC‑Switch会做适配转换；支持stream流式SSE。

参数类型必填说明
modelstring是网关侧模型名，会被映射到Codex真实模型
messagesarray是对话消息数组
streamboolean否true开启SSE流式输出，Codex透传
temperaturefloat否0‑2，生成随机性
max_tokensint否最大输出token
curl示例
curl https://www.wdsf.com.cn/v1/chat/completions \
  -H "Authorization: Bearer sk‑gateway‑xxxxxxxxxxxx" \
  -H "Content‑Type: application/json" \
  -d '{
    "model":"code‑davinci‑002",
    "messages":[{"role":"user","content":"写一个python快速排序"}],
    "stream":false,
    "temperature":0.1
  }'

POST /v1/completions

Codex原生文本补全接口，用于代码续写，prompt输入原始代码片段。CC‑Switch完整透传至Codex上游。

参数类型必填说明
modelstring是Codex模型code‑davinci‑002
promptstring是代码/文本提示词
max_tokensint是续写最大token
temperaturefloat否0‑1，代码生成建议0‑0.3
streamboolean否流式续写
stoparray|string否停止符，代码常用"\n\n"
curl示例(Codex代码续写)
curl https://www.wdsf.com.cn/v1/completions \
‑H "Authorization: Bearer sk‑gateway‑xxxxxxxxxxxx" \
‑H "Content‑Type: application/json" \
‑d '{
  "model":"code‑davinci‑002",
  "prompt":"def quick_sort(arr):",
  "max_tokens":128,
  "temperature":0,
  "stop":["\n\n"]
}'
响应示例
{
  "id":"cmpl‑xxxxxx",
  "object":"text_completion",
  "choices":[
    {
      "text":"\n    if len(arr) <=1:\n        return arr\n    pivot = arr[0]...",
      "index":0,
      "finish_reason":"stop"
    }
  ],
  "usage":{"prompt_tokens":8,"completion_tokens":64,"total_tokens":72}
}

⚠️ 错误码（CC‑Switch + Codex透传）

HTTP状态码来源说明
401CC‑Switch网关客户端网关key无效、缺失Authorization头
401上游Codex透传CC‑Switch配置的Codex上游密钥失效/错误
429Codex透传Codex侧限流，QPS超限
400Codex透传请求参数非法，prompt过长、模型不支持参数
502/504CC‑Switch网关无法连接Codex上游、超时
Codex 返回的原始 error 对象会原样透传给客户端；可查看返回体中 error.message 排查上游问题。 
{
  "error":{
    "message":"Rate limit reached for codex",
    "type":"rate_limit_error",
    "code":429
  }
}