CC Switch 集成指南

通过 WOX 控制台将 API 配置一键导入 CC Switch

1. 概述

CC Switch 是一个跨平台的 AI 编程工具配置管理器，可集中管理 Claude Code、Codex、Gemini CLI 等客户端的提供商配置。

WOX 控制台支持为以下应用生成 CC Switch 官方 Deep Link：

• Codex
• Claude Code
• Gemini CLI

导入时，WOX 会根据所选应用自动填写服务地址、API Key 和模型映射。CC Switch 打开后仍会显示配置预览，只有在你确认后才会写入配置。

2. 安装 CC Switch

请从以下官方渠道下载：

• CC Switch 官方网站
• GitHub Releases

CC Switch 支持 Windows、macOS 和 Linux。macOS 也可以通过 Homebrew 安装：

brew install --cask cc-switch

安装后至少启动一次 CC Switch，以确保系统已注册 ccswitch:// 协议。

3. 准备 WOX API Key

1. 登录 WOX，打开 API Key 页面。
2. 创建一个新密钥，或选择已有密钥。
3. 前往 模型与价格页面，确认当前账户可用的模型 ID。

4. 一键导入

1. 在 API Key 页面 找到要使用的密钥。
2. 点击密钥卡片右上角的三个点按钮。
3. 选择 CC Switch 导入。
4. 选择目标应用：Codex、Claude 或 Gemini。
5. 填写提供商名称，并选择或输入主模型。
6. 如果选择 Claude，可按需填写 Haiku、Sonnet 和 Opus 的模型映射；不需要的映射可以留空。
7. 点击 打开 CC Switch。
8. 在 CC Switch 中检查提供商名称、服务地址、模型和其他配置，然后确认导入。

WOX 会自动处理不同客户端的地址格式：Codex 使用带 /v1 的 API 地址，Claude 和 Gemini 使用对应的基础服务地址。

5. 启用并验证

导入完成后，在 CC Switch 中选择刚导入的 WOX 提供商并启用，然后打开对应的客户端发起一次测试请求。

Claude Code 通常可以立即加载切换后的提供商配置。其他客户端如果仍在使用旧配置，请关闭并重新启动终端或对应的 CLI 工具。

如果请求失败，请依次检查：

1. CC Switch 中的 WOX 提供商是否已启用。
2. 主模型是否为账户当前可用的模型 ID。
3. API Key 是否仍然有效。
4. 当前网络是否可以访问 WOX 服务地址。

6. Deep Link 安全说明

浏览器会把链接交给本机的 CC Switch，WOX 不会把生成的导入链接展示为可复制文本。CC Switch 在写入配置前会显示确认对话框，请检查内容后再继续。

7. 链接无法打开

如果点击 打开 CC Switch 后没有反应，请先确认 CC Switch 已安装并至少启动过一次。

macOS

重新安装 CC Switch，或在终端运行官方提供的协议注册命令：

/usr/bin/open -a "CC Switch" --args --register-protocol

Windows

重新运行安装程序。如果仍无法打开，请检查系统注册表中是否存在：

HKEY_CLASSES_ROOT\ccswitch

Linux

确认 CC Switch 的 .desktop 文件已安装，并包含 ccswitch 协议对应的 MimeType 配置。

更多协议细节可查看 CC Switch 官方 Deep Link 文档。