主题
CC Switch 一键导入使用指南
适用产品：aicodex-api 平台
功能版本：v1.0+
最后更新：2025-01-08
什么是 CC Switch 一键导入？
CC Switch 一键导入功能让您在 aicodex-api 平台创建 API 令牌后，无需手动复制和配置，即可直接将令牌信息导入到 CC Switch 应用中。
功能特点：
- 创建令牌后立即导入，无需额外操作
- 自动配置服务器地址和认证信息
- 安全可靠，保护您的原始令牌
- 支持 Windows、macOS、Linux 全平台
使用前准备
1. 安装 CC Switch 应用
⚠️ 必须先安装 CC Switch，否则导入功能无法使用
- 下载地址：请从官方渠道下载 CC Switch 应用
- 安装说明：根据您的操作系统完成安装
- 启动应用：安装后请先启动一次 CC Switch（建议保持运行）
2. 登录 aicodex-api 平台
- 打开浏览器访问您的 aicodex-api 站点
- 使用账号密码登录系统
- 确保账号有权限创建 API 令牌
📖 使用步骤
第一步：创建新的 API 令牌
1. 进入令牌管理页面
- 登录后点击左侧菜单栏的 「令牌管理」
- 点击页面右上角的 「添加令牌」 按钮
2. 填写令牌信息
在弹出的表单中填写以下信息：
| 字段 | 说明 | 建议填写 |
|---|---|---|
| 名称 | 令牌的显示名称 | 例如：Production-API、开发测试 |
| 过期时间 | 令牌的有效期 | 可设置永不过期或具体过期时间 |
| 模型限制 | 限制可使用的 AI 模型 | （可选）如不需要请留空 |
| 分组 | 令牌所属的分组 | 选择适合的分组或留空 |
💡 提示：
- 令牌名称建议包含使用场景，如
生产环境-主API
3. 提交创建
- 确认信息无误后，点击 「提交」 按钮
- 等待系统创建令牌
第二步：一键导入到 CC Switch
1. 点击「导入CCS」按钮
在密钥展示窗口的底部，点击 「导入CCS」 按钮。
系统会弹出导入说明对话框，展示三种可能的情况：
📊 三种情况说明
| 状态 | 图标 | 您的情况 | 会发生什么 |
|---|---|---|---|
| 未安装 | ❌ | 您还未安装 CC Switch | 点击导入无效，请先下载并安装 |
| 已安装未启动 | ⚠️ | 已安装但没有打开 | 会打开 CC Switch，但需要再次点击导入 |
| 已启动 | ✅ | 已安装并正在运行 | 最佳体验，自动导入配置 |
2. 选择模型，确认导入
- 如果您还未启动 CC Switch，建议先启动应用
- 选择AI模型
- 点击 「确认导入」 按钮
3. 系统自动执行
系统会自动完成以下操作：
- ✅ 获取您的 aicodex-api 服务器地址
- ✅ 生成 CC Switch 专用导入链接
- ✅ 自动唤起 CC Switch 应用
- ✅ 导入并配置 API 提供商
4. 查看导入结果
成功导入后，在 CC Switch 中您会看到：
提供商名称: NewAPI-您的令牌名称
API 端点: https://your-api-domain.com
API 密钥: •••••••••••••••• （已自动配置）
状态: ✅ 已启用
验证方法：
- 在 CC Switch 中查看提供商列表
- 点击「测试连接」按钮验证配置
- 尝试使用 Claude Code 进行对话测试
❓ 常见问题
问题 1：点击「导入CCS」后没有反应？
可能原因和解决方法：
原因 ①：未安装 CC Switch
- 请先下载并安装 CC Switch 应用
- 安装后需要重启浏览器
原因 ②：CC Switch 未启动
- 启动 CC Switch 应用
- 保持应用在后台运行
- 重新点击「导入CCS」按钮
原因 ③：浏览器拦截了协议调用
- 浏览器地址栏下方可能出现提示条
- 点击「允许」或「打开 CC Switch」
- 或检查浏览器设置中的协议处理程序
原因 ④：Windows 用户可能缺少协议注册
- 重新安装 CC Switch（会自动注册协议）
- 或手动运行注册命令
问题 2：导入成功了，但无法使用？
检查清单：
① 检查 API 地址
- 在 CC Switch 中查看提供商配置
- 确认地址格式：
https://your-api-domain.com - 注意：codex类型地址末尾包含
/v1
② 检查令牌状态
- 返回 aicodex-api 平台
- 进入「令牌」页面
- 确认令牌显示为「已启用」状态
- 检查是否有剩余额度和未过期
③ 测试连接
- 在 CC Switch 中点击「测试连接」
- 如果失败，记录错误信息
- 检查网络是否能访问 API 地址
④ 验证密钥
- 如果测试连接失败，可能是密钥问题
- 需要重新创建令牌并再次导入
问题 3：如何更新已导入的令牌配置？
更新方法：
情况 1：令牌到期或额度用完
- 在 aicodex-api 平台创建新令牌
- 按照上述步骤重新导入
- 在 CC Switch 中删除旧配置
情况 2：需要修改配置
- 在 CC Switch 中直接编辑提供商配置
- 修改 API 地址、密钥或其他参数
- 保存修改
情况 3：原配置有变动
- 在 aicodex-api 平台修改原令牌配置
- 在 CC Switch 中更新对应的配置
- 或重新导入新令牌
问题 4：支持哪些操作系统？
支持平台：
✅ Windows（Windows 10/11）
- 支持 Edge、Chrome、Firefox 浏览器
- 需要注册
ccswitch://协议
✅ macOS（macOS 10.15+）
- 支持 Safari、Chrome、Edge 浏览器
- 协议自动注册
✅ Linux（Ubuntu、CentOS 等）
- 支持 Chrome、Firefox 浏览器
- 可能需要手动配置协议
浏览器兼容性：
- ✅ Chrome / Edge（推荐）
- ✅ Firefox
- ⚠️ Safari（可能需要额外配置）
💡 最佳实践建议
1. 命名规范
采用清晰的命名规范，便于管理：
环境-用途-项目名称
好例子：
✅ Production-MainApp-API
✅ Development-Testing-GPT4
✅ Staging-Internal-Assistant
✅ Personal-Project-X-Claude
坏例子：
❌ Token1
❌ MyKey
❌ Test2. 环境分离
为不同使用场景创建独立令牌：
| 环境 | 有效期 | 额度 | IP限制 | 用途 |
|---|---|---|---|---|
| 生产环境 | 1年 | 大额/无限 | 建议限制 | 正式业务使用 |
| 开发环境 | 3个月 | 中等 | 宽松 | 开发测试 |
| 临时测试 | 7天 | 小额 | 不限制 | 一次性测试 |
| 内部工具 | 1年 | 根据需求 | 内网IP | 内部系统 |
3. 导入流程建议
推荐流程：
1. 启动 CC Switch 应用 ← 先启动，体验最佳
2. 在平台创建新令牌
3. 保存密钥到密码管理器
4. 点击「导入CCS」按钮
5. 确认导入
6. 在 CC Switch 中测试连接
7. 开始使用不推荐流程：
❌ 不安装 CC Switch 就点击导入
❌ 不保存密钥就直接导入
❌ 关闭密钥窗口后才尝试导入5. 故障排查
遇到问题时，按以下顺序排查：
第一步：检查基础条件
- [ ] CC Switch 已安装并正在运行
- [ ] aicodex-api 平台可正常访问
- [ ] 网络连接正常
- [ ] 浏览器允许打开外部应用
第二步：检查令牌状态
- [ ] 令牌状态为「已启用」
- [ ] 额度未用完（或设置为无限）
- [ ] 令牌未过期
- [ ] 账号有足够额度
第三步：检查配置
- [ ] API 地址格式正确（不含
/v1） - [ ] 密钥已正确导入
- [ ] CC Switch 配置已启用
第四步：测试连接
- 使用 CC Switch 的「测试连接」功能
- 记录错误信息
- 联系管理员时提供错误详情
📊 常见问题速查表
| 问题 | 快速解决 |
|---|---|
| 点击导入无反应 | 检查是否安装并启动 CC Switch |
| 导入后无法使用 | 核对令牌状态、额度、过期时间 |
| 浏览器提示不安全 | 点击「允许」或「打开 CC Switch」 |
| 想导入多个令牌 | 目前需逐个创建和导入 |
| 密钥泄露怎么办 | 立即在平台禁用该令牌，创建新令牌 |
| 忘记保存密钥 | 无法找回，只能创建新令牌 |
| CC Switch 无法打开 | 重新安装 CC Switch |
| 如何删除导入的配置 | 在 CC Switch 中直接删除提供商 |
📌 重要提醒
⚠️ 密钥安全提醒
- 密钥仅在创建时显示一次
- 关闭窗口后无法再次查看
- 请立即复制并妥善保存
- 建议使用密码管理器存储
⚠️ 导入前准备
- 必须先安装 CC Switch 应用
- 建议先启动 CC Switch 再点击导入
- 确保网络连接正常
⚠️ 使用限制
- 临时密钥有效期与原令牌一致
- 密钥过期后需重新导入
- 删除原令牌后导入的配置将失效
文档版本：v1.0.2
适用系统：aicodex-api v1.0+
最后更新：2025-01-09