跳到主要内容

CC Switch

CC Switch 是一款开源的桌面应用，用于统一管理多个 AI 编程工具（Claude Code、Codex、Gemini CLI 等）的供应商配置。只需在 CC Switch 中添加一次云开发供应商配置，即可在多个工具中使用云开发大模型，无需为每个工具单独配置。

准备工作

Base URLhttps://<ENV_ID>.api.tcloudbasegateway.com/v1/ai/cloudbase

配置步骤​

我们以 CC Switch v3.16.1 版本为例。

1. 安装 CC Switch​

推荐使用 Homebrew 安装：

brew install --cask cc-switch

或从 Releases 页面 下载 CC-Switch-*-macOS.dmg。

2. 添加云开发供应商​

  1. 打开 CC Switch 桌面应用
  2. 点击右上角 + 按钮，选择 添加供应商
  3. 在预设列表中选择 自定义配置
  4. 填写以下信息：
字段说明
供应商名称输入"云开发"或自定义名称
API Key在 AI 控制台 中获取的 API 密钥
Base URL请求地址：https://{{cloudBase环境ID}}.api.tcloudbasegateway.com/v1/ai/cloudbase
  1. 根据使用的 AI 工具选择 API 格式

选择 API 格式​

云开发 CloudBase AI 支持以下协议：

  • Anthropic Messages：Claude 模型的原生接口协议
  • Chat Completions：OpenAI 兼容的通用对话协议
  • Responses API：OpenAI 新一代 API，目前仅部分模型支持

根据工具选择 API 格式：

AI 工具推荐 API 格式说明
Claude CodeAnthropic Messages原生格式，无需额外配置
Claude DesktopAnthropic Messages原生格式，无需额外配置
CodexChat Completions需开启本地路由
Gemini CLIChat Completions通用格式
OpenCodeChat Completions通用格式
OpenClawChat Completions通用格式
HermesChat Completions通用格式

配置 Claude Code / Claude Desktop（Anthropic Messages）：

选择 Anthropic Messages 格式（默认），粘贴云开发的 API Key 和 Base URL 即可。无需修改高级选项。

配置 Codex（Chat Completions）：

  1. 在高级选项中，将 API 格式切换为 Chat Completions

  2. 勾选 需要本地路由映射（Needs Local Route Mapping）

  3. 在模型映射表中填入模型 ID（从 AI 控制台 模型列表复制已启用的大模型标识）

  4. 保存配置，切换启用云开发供应商即可使用

备注

切换供应商后，大多数 AI 工具需要重启终端或对应的 CLI 工具。Claude Code 支持热切换，无需重启。

在 AI 工具中使用​

配置完成后，以下 AI 工具可直接使用云开发大模型：

  • Claude Code — 使用 Anthropic Messages 协议（原生），终端运行 claude
  • Claude Desktop — 使用 Anthropic Messages 协议（原生）
  • Codex — 使用 Chat Completions 协议（需开启本地路由），终端运行 codex
  • Gemini CLI — 使用 Chat Completions 协议，终端运行 gemini
  • OpenCode — 使用 Chat Completions 协议
  • OpenClaw — 使用 Chat Completions 协议
  • Hermes — 使用 Chat Completions 协议

常见错误排查​

报错信息解决方法
401 Credentials are invalidAPI Key 填写错误，或者可能被删除，请前往 AI 控制台 重新获取
404 未找到模型 / Model not foundBase URL 或模型名称配置不正确，请确认 AI 控制台中已启用该模型
429 Token usage exceeded quota limitToken 消耗完或未在 AI 控制台中启用模型
Codex 连接失败 / Connection refused确认已开启本地路由服务（代理模式），并且 API 格式选择为 Chat Completions
工具无法连接检查网络环境是否能正常访问云开发 API，确认 Base URL 中的环境 ID 是否正确