YUNQIAO · AI GUIDE

Codex 或 Claude Code 中使用国模

用 CC Switch 配置国产模型，按工具选择接口，再验证实际调用。

先准备这三项

本教程适用于 Windows / macOS，以 Codex CLI 和 Claude Code 命令行为主。国模指 DeepSeek、通义千问、智谱 GLM、Kimi 等国产模型；具体能否使用，取决于服务商开放的模型及接口。

  1. 已安装并能启动 Codex 或 Claude Code。
  2. 准备同一服务商提供的 API Key、接口地址和准确模型 ID。使用云桥时，先阅读获取 API Key 与 URL，并确认该密钥有目标国模权限。
  3. 安装 CC Switch，并备份已有配置。它是独立的社区开源工具，不属于 OpenAI、Anthropic 或云桥；工具本身免费，模型调用按服务商规则计费。
云桥是否支持某个国模、对应协议及路径，以云桥控制台或客服确认为准。不要把 GPT / Claude 的模型名直接改成国模名称，就认为已经接入成功。

1. 下载 CC Switch

前往CC Switch 官方 GitHub Releases，在 Assets 中选择与你的系统及芯片架构匹配的安装包。Windows 选择 Windows 安装包，macOS 选择 macOS 安装包；以当次发布提供的文件为准。

安装后打开 CC Switch。首次使用时，先导入或保存当前供应商配置，方便随时切回。已经安装的用户可先检查更新，旧版本的预设和国模兼容能力可能不同。

需要备份哪些文件？

macOS：~/.codex/config.toml、~/.codex/auth.json 和 ~/.claude/settings.json。

Windows：用户目录下 .codex 中的 config.toml、auth.json，以及 .claude 中的 settings.json。只复制已存在的文件，另存到备份目录；自定义配置目录或 WSL 环境应备份实际使用的位置。

2. 先选工具，再选连接方式

使用的工具直接连接的要求上游只有其他协议时
Claude Code兼容 Anthropic Messages，并支持工具调用与流式输出。使用 CC Switch 当前版本支持的格式转换，并开启 Claude 应用路由。
Codex兼容 OpenAI Responses，并支持 Codex 需要的工具调用与流式输出。先检查 CC Switch 对该供应商的预设与路由支持；仅有 Chat Completions 的地址不能直接当作 Responses 地址。

优先使用经过确认的供应商预设。没有预设时再添加自定义供应商，按实际接口填写。国产模型并不都提供相同协议，也不保证支持原客户端的所有功能。

3. 在 Claude Code 中配置国模

  1. 在 CC Switch 顶部选择 Claude Code，点击「添加供应商 / Add Provider」。
  2. 使用云桥时选择自定义配置，名称填写「云桥 · 国模」。如果直接使用模型厂商，则选择该厂商的预设，并填写该厂商的 Key，不能混用云桥密钥。
  3. 填入 API Key 和该服务的 Anthropic 兼容 Base URL。云桥站点基础地址为 https://ai.aiyq.cloud；国模专用接口及额外路径须先确认，不要自行追加 /messages。
  4. 原生兼容接口选择 Anthropic Messages，按预设填写认证字段；常见为 ANTHROPIC_AUTH_TOKEN。默认模型填写服务商给出的国模 ID；若界面提供 Sonnet / Opus / Haiku 映射，也要映射到有权限的实际模型。
  5. 若上游提供的是 OpenAI Chat Completions，选择对应 API 格式，并在「设置 → 高级 → 路由服务」启动服务、开启 Claude 应用路由。旧版界面可能称为「本地代理 / 接管」。
  6. 保存，点击该供应商的「启用 / Enable」，退出并重新启动 Claude Code。
采用本地路由或格式转换时，保持 CC Switch 路由服务运行。它只负责配置与转发，不会自动为你的 Key 增加模型权限。

4. 在 Codex 中配置国模

  1. 切换到 Codex 标签页，添加供应商。Claude Code 和 Codex 的配置分别管理。
  2. 优先选当前版本提供的目标国模预设；使用云桥时建立「云桥 · 国模」自定义供应商，填写云桥 Key 和已确认的接口地址。
  3. 直接连接时，确认上游支持 Responses，再填写相应 Base URL。使用 Chat 格式上游时走下方第 5 步的本地路由。只有服务商明确给出 /v1 前缀时才保留它，不重复拼接 /v1，也不把完整 /responses 请求地址填作 Base URL。
  4. 直接连接时，模型填写有权限的准确国模 ID；路由模式在第 5 步的模型映射表中填写，并在重启后的 /model 列表选择。手动配置中的 model 对应该 ID，model_provider 应与供应商配置名称对应，wire_api 使用 responses。
  5. 使用 DeepSeek、Kimi 等 Chat 格式预设时，检查「需要本地路由映射」已开启。在下方「模型映射」表添加上游真实模型 ID，显示名称可自行填写，上下文长度按厂商文档填写。然后启动路由服务并开启 Codex 应用路由。自定义 Chat 格式供应商也需要此开关；接口地址填写上游实际地址，由路由完成转换。
  6. 保存并启用供应商，完全退出 Codex 后重开，创建新任务验证。桌面端接入还需确认当前 Codex 与 CC Switch 版本兼容。

若服务商只提供 Chat Completions，且 CC Switch 没有适配该供应商，先使用支持该协议的工具或向服务商确认 Responses 接口，不能靠更改地址后缀解决。

5. 验证与切换

  1. 启动 claude 或 codex，先发送一条简单问答，确认能正常返回。
  2. 再让它读取一个测试目录并解释文件内容，检查工具调用；需要写文件时用临时测试项目。
  3. 查看服务商调用记录，核对时间、实际模型 ID 和消耗。使用云桥就到云桥控制台查看；仅凭模型自报名称不能证明切换成功。

切回原供应商时，在对应工具标签页重新启用已保存的配置。若要退出本地路由，先关闭对应应用路由，让配置恢复，再退出 CC Switch；随后重新启动客户端。

常见问题

401 / 403：认证或权限错误确认 Key 与接口来自同一服务商，并检查额度、有效期及国模权限。
404：路径或模型不存在核对 Base URL、协议、模型 ID，排除重复 /v1 或手动拼接错误。
400 / 工具调用失败可能是模型或接口不支持当前工具参数。更新 CC Switch，核对供应商适配，不要仅以普通聊天成功判断全部功能可用。
仍在使用旧模型确认选对客户端标签页、供应商已启用，并检查默认模型与角色映射。退出旧进程后新建任务；检查环境变量或项目配置是否覆盖设置。
连接 127.0.0.1 失败检查 CC Switch 路由服务是否运行。若不再使用路由，先在 CC Switch 中关闭应用路由并恢复配置。

官方资料

以下外部链接均指向工具作者仓库或厂商官方文档，不使用第三方镜像、推广链接或私有安装脚本。

链接及文档核对：2026-09-12。界面名称以安装版本为准。