CC Switch 可以把青云TOP API 的自定义 Provider 写入 Codex 配置。下面按“安装 CC Switch、添加 Provider、安装并启动 Codex、验证请求”的顺序完成接入。

第一步：安装 CC Switch

  1. 从 CC Switch 官方 Releases 下载并安装适合当前系统的版本。
  2. 打开 CC Switch，在顶部应用栏进入 Codex。
  3. 选择添加供应商（中转站）或 自定义 Provider，填写以下信息：
配置项填写内容
供应商名称青云TOP API
API Key粘贴在控制台创建的客户端专用 API Key
API 请求地址https://top.qingyuntop.ai/v1
默认模型填写 /v1/models 返回且支持 Responses API 的完整模型 ID
CC Switch 的 Codex 应用配置入口
CC Switch 自定义 Provider 配置示例
  1. 保存配置并点击 启用，确认 Provider 卡片显示“使用中”。
CC Switch 启用 Provider 的示例

第二步：安装并启动 Codex

  1. 从 OpenAI Codex 官方页面 下载并安装 Codex。
  2. 安装完成后启动 Codex。根据当前版本的登录界面，选择支持自定义 Provider 或 API Key 的方式；如果版本要求 OpenAI 账号登录且没有读取 CC Switch 配置，不要修改 OAuth 文件或系统代理绕过登录。
  3. 完全退出并重新打开终端，运行：
codex
Codex 启动后的示例

连接失败时检查 config.toml

如果 Codex 反复提示连接失败，可以检查配置文件中是否包含页面提示的 OpenAI HTTP Provider 片段：

model_provider = "openai_http"

[model_providers.openai_http]
name = "OpenAI HTTP"

这段内容只用于确认 Provider 类型；API Key、Base URL 和模型仍应以 CC Switch 中保存的青云TOP API Provider 为准。修改前请备份 ~/.codex/config.toml，并在修改后完全重启 Codex。

验证是否接入成功

  1. 在 Codex 中发送一条简短消息。
  2. 确认收到正常回复。
  3. 到青云TOP API 控制台的调用日志中核对请求时间、模型和状态。

常见问题

  • 401：检查 API Key 是否完整、是否仍在使用旧认证信息。
  • 403：检查 API Key 分组、余额和模型权限。
  • 404：检查 Base URL 是否重复填写 /v1，以及模型是否支持 Responses API。
  • 仍访问官方 Provider：完全退出 Codex 和后台驻留的编辑器，再确认 CC Switch 卡片显示“使用中”。
  • 切换后无变化：关闭终端和 Codex 后重新启动，并以控制台调用日志为最终依据。

发布前检查

以下检查适用于客户端中选择 OpenAI 兼容 或 Responses 提供商的场景；如果你选择的是 Anthropic、Gemini 等原生协议，请按对应协议的接口和返回结构配置。

  1. 模型 ID：先用目标 API Key 请求 GET https://top.qingyuntop.ai/v1/models，把返回的 data[].id 原样填入客户端。截图、教程和历史配置中的模型名不保证仍可用。
  2. 协议选择：新 OpenAI 集成优先选择 Responses；只有客户端或模型明确要求 Chat Completions 时才选择 Chat。Responses 的返回从 output 读取，Chat 的返回从 choices[].message 读取。
  3. Base URL：通常填写 https://top.qingyuntop.ai/v1，也就是只保留一个 /v1。要求完整接口地址的客户端才追加 /responses 或 /chat/completions，不要重复追加。
  4. 流式与重试：流式响应必须按所选协议解析事件；连接中断后不要盲目重放可能已被服务端接受的生成请求。对 429 和 5xx 使用带抖动的退避，并设置连接、读取和总超时。
  5. 上线前验证：分别验证普通文本、流式文本、工具调用或结构化输出中实际用到的能力，并记录 request id、HTTP 状态、业务状态和完成原因，避免只根据 HTTP 200 判定成功。