Appearance
CC Switch 安装与首次配置
CC Switch 是一款用于管理 AI 编程工具配置的桌面应用。它可以把不同模型服务保存为独立的 Provider，并帮助你在 Codex、Claude Code、Gemini CLI 等工具之间切换服务配置。
本文以 Windows 为主要示例，介绍 CC Switch 的下载安装、首次启动，以及如何通过应天AI控制台导入配置。完成后，你可以继续阅读 Codex 配合 CC Switch 接入应天AI，完成 Codex 的实际调用。
CC Switch 不是模型服务，也不是 Codex 的替代品。它负责管理本机配置；真正发起请求的仍然是 Codex、Claude Code 或其他受支持的 AI 工具。
一、安装前确认
开始前请准备：
- 一台 Windows、macOS 或 Linux 电脑
- 稳定的网络连接
- 需要接入的 AI 编程工具，例如 Codex 或 Claude Code
- 应天AI账号和 API Token
- 一个用于保存安装包的本地目录
如果你只想使用 CC Switch 管理 Codex，建议先安装并确认 Codex 本身能够正常启动，再安装 CC Switch。这样遇到问题时，可以快速判断是应用安装问题还是 Provider 配置问题。
二、获取安装包
建议从 CC Switch 官方渠道下载，避免使用来源不明的修改版安装包：
在 Releases 页面中，根据电脑系统选择对应文件：
| 系统 | 常见安装文件 | 适合场景 |
|---|---|---|
| Windows | .msi 安装包 | 希望按系统方式安装并创建快捷方式 |
| Windows | .zip 便携版 | 不想写入系统安装目录，解压后直接运行 |
| macOS | .dmg 或应用包 | 拖入 Applications 后使用 |
| Linux | .deb、.AppImage 等 | 根据发行版选择安装方式 |
下载时请注意系统架构。普通 Intel 或 AMD 电脑通常选择 x64；ARM 设备应选择 ARM64 或 aarch64 版本。
三、Windows 安装步骤
1. 运行安装程序
下载 Windows 安装包后，双击 .msi 文件启动安装：
- 按安装向导选择安装位置。
- 根据需要创建桌面或开始菜单快捷方式。
- 等待安装完成。
- 从开始菜单或桌面快捷方式启动 CC Switch。
如果 Windows 弹出安全提示，请先确认安装包来自官方 Releases 页面，再决定是否继续。不要为了绕过提示而运行来源不明的文件。
2. 使用便携版
如果下载的是 .zip 文件：
- 将压缩包解压到固定目录。
- 运行其中的 CC Switch 主程序。
- 不要只从临时下载目录运行，避免后续清理文件时丢失配置或快捷方式。
- 如果需要开机后继续使用，将程序目录移动到自己容易找到的位置。
便携版通常不需要传统安装流程，但仍可能需要系统注册外部链接协议，具体以当前版本行为为准。
四、首次启动检查
第一次打开 CC Switch 后，先不要急着导入多个服务，建议按以下顺序检查：
- 主窗口能够正常显示。
- 左侧或顶部可以看到应用分类或 Provider 管理入口。
- 可以创建或查看一个配置项。
- 关闭并重新打开应用后，界面仍能正常加载。
CC Switch 可能会缩小到系统托盘。找不到主窗口时，可以检查任务栏右侧的托盘区域，右键 CC Switch 图标后选择打开主界面或退出应用。
五、从应天AI导入配置
应天AI控制台支持从 API Token 的操作菜单唤起 CC Switch。这样可以减少手动填写服务地址和模型名称的步骤。
1. 打开 CC Switch 入口
2. 允许系统打开应用
浏览器可能会询问是否允许打开 CC Switch。选择允许后，系统会将配置传递给本机 CC Switch。
如果浏览器没有弹出确认窗口，或者点击后没有任何反应，请检查：
- CC Switch 是否已经安装并成功启动过
- 浏览器是否阻止了外部应用链接
- 系统是否已将
ccswitch://协议关联到 CC Switch - 是否需要先手动打开 CC Switch，再重新点击导入入口
3. 选择目标应用
导入窗口打开后，选择你实际要使用的应用，例如：
- Codex
- Claude
- Gemini
然后填写或确认以下内容：
| 字段 | 填写建议 |
|---|---|
| 配置名称 | 使用容易识别的名称，例如 应天AI Codex |
| 主模型 | 从应天AI模型广场选择当前可用模型 |
| API Token | 使用对应应用专用的 Token |
确认无误后，点击 打开 CC Switch 或页面中含义相同的按钮。不要在公开截图中保留真实 Token。
六、在 CC Switch 中启用 Provider
导入完成后，切换回 CC Switch 主窗口：
- 进入与目标应用对应的分类。
- 找到刚刚导入的 Provider。
- 打开配置详情，核对名称、模型和服务信息。
- 点击启用、设为当前配置或类似按钮。
- 确认界面显示当前 Provider 已生效。
Provider 是一组服务配置。你可以为不同平台、不同账号或不同用途分别创建 Provider，再按需要切换，而不必覆盖原有配置。
七、安装后如何验证
CC Switch 显示配置已启用，只能说明本地配置已经切换。还需要使用实际的 AI 工具发起请求验证：
- 完全退出正在运行的 Codex、Claude Code 或其他下游工具。
- 重新启动下游工具。
- 发送一条简单测试消息。
- 登录应天AI控制台，查看使用日志。
以 Codex 为例，可以发送：
text
请只回复：CC Switch 配置已生效如果客户端能返回内容，并且控制台日志出现对应请求，说明安装、Provider 切换和网络访问均已基本正常。
八、macOS 和 Linux 简要说明
macOS
从官方 Releases 下载对应安装包，将 CC Switch 放入 Applications 后启动。首次从互联网下载的应用可能会触发系统安全确认，请确认来源后再打开。
如果使用 Homebrew，也可以根据官方文档提供的命令安装。安装完成后，建议手动启动一次 CC Switch，再测试控制台的配置导入链接。
Linux
根据发行版选择 .deb、AppImage 或其他官方提供的格式。AppImage 通常需要先授予执行权限；安装后启动 CC Switch，并确认桌面环境能够处理 ccswitch:// 外部链接。
不同 Linux 桌面环境对协议注册的处理方式不同。如果应用本身可以打开，但浏览器无法唤起 CC Switch，可以先使用 CC Switch 的手动新增 Provider 功能。
常见问题
安装后无法启动
确认下载的文件与系统架构匹配，并重新从官方 Releases 下载当前版本。Windows 便携版请先完整解压，不要直接在压缩包预览窗口中运行。
找不到 CC Switch 窗口
检查任务栏右下角的系统托盘，应用可能已经在后台运行。也可以先退出托盘中的 CC Switch，再从开始菜单重新启动。
点击 CC Switch 没有反应
这通常与 ccswitch:// 协议关联有关。先手动打开一次 CC Switch，再回到应天AI Token 页面重试；如果仍然失败，可以在 CC Switch 中手动创建 Provider。
导入后看不到配置
确认导入时选择了正确的目标应用分类，并检查是否导入到了其他 Provider 列表。关闭并重新打开 CC Switch 后再次查看。
Provider 已启用，但客户端仍使用旧服务
切换 Provider 后，已经运行的 Codex 或 CLI 可能不会自动读取新配置。完全退出下游工具，必要时重新打开终端，再发起测试请求。
不知道应该填写哪个模型
打开应天AI模型广场，复制当前账号和 Token 可用的模型名称。不要直接照抄教程中的示例名称。
如何判断请求是否真正经过应天AI
不要只看客户端是否返回内容。请同时检查应天AI的使用日志，核对请求时间、模型、状态和消耗信息。
安全建议
- 只从 CC Switch 官方网站或 GitHub Releases 下载软件。
- 为不同应用创建独立的 API Token。
- 不要分享包含完整 Token 的截图或 Deep Link。
- 不要将 Token 写入公开仓库或提交到项目配置文件。
- 发现异常调用时，立即在应天AI控制台停用对应 Token。