# CC Switch v3.13.0

> 轻量模式、配额与余额展示、供应商模型自动获取、Codex OAuth 反向代理、托盘按应用分级菜单

**[English →](v3.13.0-en.md) | [日本語版 →](v3.13.0-ja.md)**

---

## 概览

CC Switch v3.13.0 是一次重要的功能版本，聚焦于可观测性、供应商工作流与代理兼容性。本版本在各主要供应商卡片上新增了**配额与余额展示**，覆盖 Claude / Codex / Gemini 官方订阅、Token Plan（Kimi / Zhipu GLM / MiniMax）、Copilot premium interactions 以及 DeepSeek / StepFun / SiliconFlow / OpenRouter / Novita AI 等第三方余额查询；引入了**轻量模式**，让 CC Switch 可以仅驻留在系统托盘中运行；通过 OpenAI 兼容的 `/v1/models` 端点在 Claude / Codex / Gemini / OpenCode / OpenClaw 五个应用的供应商表单中实现了**模型自动发现**；为 ChatGPT 订阅者提供了 **Codex OAuth 反向代理**；将托盘菜单重构为**按应用分级的子菜单**；将代理转发层重建在 **Hyper 客户端**之上；并完成了 **Skills 工作流**的发现、批量更新和存储位置切换改造，内置了 skills.sh 搜索安装。其他改进还包括完整 URL 端点模式、更完善的 token 用量追踪、Copilot 调用优化器、多字节 UTF-8 流式分片边界修复以及 Linux 启动时 UI 无响应修复，以及更友善的新用户引导等。

**发布日期**：2026-04-10

**更新规模**：139 commits | 280 files changed | +31,627 / -3,042 lines

---

## 重点内容

- **轻量模式**：新增仅托盘运行模式，退出到托盘时销毁主窗口、按需重建，空闲时资源占用接近零
- **配额与余额展示**：供应商卡片上直接展示配额或余额 —— 覆盖 Claude / Codex / Gemini 官方订阅、GitHub Copilot premium interactions、Codex OAuth、Token Plan（Kimi / Zhipu GLM / MiniMax），以及 DeepSeek / StepFun / SiliconFlow / OpenRouter / Novita AI 的官方余额查询
- **供应商模型自动获取**：为 Claude / Codex / Gemini / OpenCode / OpenClaw 的供应商表单新增 OpenAI 兼容的 `/v1/models` 发现能力，按分组下拉展示并提供针对性错误提示
- **Codex OAuth 反向代理**：新增 ChatGPT 的 Codex 反向代理，作为新的 Claude 供应商卡片类型，让用户在可以在 Claude Code 里面使用 ChatGPT 订阅。包含受管 OAuth 登录流程和订阅配额展示（[⚠️ 风险提示](#️-风险提示)）
- **托盘按应用分级菜单**：将托盘菜单重构为按应用分组的子菜单，防止供应商多时菜单溢出，让后台切换供应商在大量供应商场景下仍可用
- **Skills 发现与批量更新**：基于 SHA-256 内容哈希的更新检测、单项和"全部更新"批量操作、`skills.sh` 表搜索集成，以及 CC Switch 与 `~/.agents/skills` 的存储位置切换
- **会话工作流升级**：会话管理器批量删除、Claude 终端恢复前的目录选择器、无需代理拦截即可导入 Claude / Codex / Gemini 会话日志用量、精确的 Codex JSONL 解析、按应用筛选用量面板
- **OpenCode / OpenClaw 流式检测覆盖**：新增 OpenCode 的 npm 包映射检测、OpenClaw `openai-completions` 支持，以及其余所有 OpenClaw 协议变体
- **完整 URL 端点模式**：新增将 `base_url` 视作完整上游端点的供应商选项，支持非标准 URL 布局的厂商
- **Hyper 代理转发栈**：将代理转发层重构到 Hyper 客户端之上，实现透明头部转发、改进的端点重写以及对动态上游端点的更好支持
- **Copilot 调用优化器**：新增请求分类和路由逻辑，降低 GitHub Copilot premium interaction 的不必要消耗
- **UTF-8 流式分片边界修复**：所有 4 条 SSE 流式路径改为跨分片保留残留多字节序列，消除 Copilot 反代下中文/emoji 乱码
- **Linux 启动 UI 修复**：修复长期存在的 Linux 窗口初次无法响应点击、需用户手动最大化再还原才能操作的问题
- **首次运行引导**：新安装时弹出一次性欢迎对话框、自动种入 Claude / OpenAI / Google 官方预设、启动时自动导入 OpenCode / OpenClaw 的 live 配置
- **Claude 会话标题与搜索高亮**：从 Claude 会话中提取有意义的标题（自定义标题 → 首条用户消息 → 目录名），在会话管理器搜索时高亮匹配关键词
- **URL 图标支持**：图标系统新增双渲染模式，大 SVG 和光栅图片（PNG / JPG / WebP）通过 Vite URL import 加载，小 SVG 保持内联
- **新供应商预设**：新增 TheRouter、DDSHub、LionCCAPI、胜算云、PIPELLM、E-FlowCode 预设

---

## 新功能

### 轻量模式

新增仅托盘运行模式，显著降低 CC Switch 空闲时的桌面占用。

- 退出到托盘时销毁主窗口而非隐藏，释放 UI 资源和内存
- 用户从托盘、深链接或单例激活时按需重建窗口
- 覆盖所有窗口重新显示路径：正常启动、深链接、单例、托盘 `show_main` 以及轻量模式退出返程

### 配额与余额展示

在供应商卡片上新增配额和余额读数，用户无需离开卡片即可查看剩余容量。

- **官方订阅**：Claude / Codex / Gemini 官方供应商的订阅配额展示
- **GitHub Copilot**：在 Copilot 供应商卡片上显示 premium interactions 剩余量
- **Codex OAuth**：在 Codex OAuth 卡片上内联展示 ChatGPT 订阅配额
- **Token Plan 供应商**：Kimi、Zhipu GLM、MiniMax 用量进度显示（为避免混淆，需要手动开启）
- **第三方余额**：为 DeepSeek、StepFun、SiliconFlow、OpenRouter、Novita AI 提供官方余额查询（为避免混淆，需要手动开启）
- 官方供应商的健康检查和用量配置按钮自动隐藏，保持卡片简洁

### 供应商模型自动获取

为所有供应商表单新增 OpenAI 兼容的模型发现能力，消除手动复制粘贴模型 ID 的繁琐流程。

- 使用配置的 API key 向供应商的 `/v1/models` 端点发起请求
- 在下拉菜单中按类别分组展示模型
- 对网络 / 认证 / 端点不存在 / 解析失败等场景提供具体错误消息
- 支持全部五个应用（Claude / Codex / Gemini / OpenCode / OpenClaw）

### Codex OAuth 反向代理

新增 ChatGPT 订阅者的 Codex OAuth 反向代理路径，让 ChatGPT 订阅者可以在 Claude Code 中使用自己的订阅。

- 受管 OAuth 登录流程，通过 ChatGPT 认证
- 作为新的 Claude 供应商卡片类型出现在列表中，与 API-key 型供应商并列
- 订阅配额内联展示
- 与 Auth Center UI 紧密集成，统一管理 Token
- 启用前请参见下文的 [⚠️ 风险提示](#️-风险提示)

### 托盘按应用分级菜单

将托盘菜单重构为按应用分组的子菜单，取代原来的扁平列表。

- 为 Claude / Codex / Gemini / OpenCode / OpenClaw 分别建立独立的子菜单
- 防止用户有大量供应商时托盘菜单溢出屏幕
- 后台切换供应商的可扩展性更好

### Skills 发现与批量更新

将 Skills 管理面板升级为完整的发现 + 维护工作流。

- **SHA-256 更新检测**：通过内容哈希判断哪些 skill 在远端有更新
- **单项与批量更新**：单项"更新"按钮 + 带滑入动画的"全部更新"批量操作
- **存储位置切换**：在 CC Switch 存储和 `~/.agents/skills` 之间切换而不丢失 skill 状态
- **公共注册表搜索**：将 `skills.sh` 搜索直接集成到对话框中，方便发现社区 skill

### 会话工作流升级

多项会话管理改进，降低使用 Claude / Codex / Gemini 会话时的摩擦。

- **批量删除会话**：在会话管理器中选择并一次删除多个会话 (#1693, 感谢 @Alexlangl)
- **恢复前目录选择器**：Claude 终端恢复前先选择工作目录 (#1752, 感谢 @yovinchen)
- **无需代理的会话日志用量**：直接从 Claude / Codex / Gemini 会话日志导入用量数据，无需代理拦截
- **精确的 Codex JSONL 解析**：替换 Codex 的估算用量为基于 JSONL 会话日志的精确解析，同时对模型名称做归一化以保证定价查询一致性
- **Gemini CLI 会话日志集成**：Gemini 用量现在从 Gemini CLI 会话日志精确同步
- **按应用筛选用量**：用量面板可按 Claude / Codex / Gemini 独立筛选

### OpenCode / OpenClaw 流式检测覆盖

将 Stream Check 面板的覆盖范围扩展到 OpenCode 和所有 OpenClaw 协议变体。

- 通过 npm 包映射检测 OpenCode 供应商
- 支持 OpenClaw `openai-completions` 协议
- 支持剩余的三个 OpenClaw 协议变体
- 针对自定义头透传、OpenClaw 自定义 auth-header 检测、Bedrock 错误消息、OpenCode 默认 `baseURL` 回退等边界情况进行了处理

### 完整 URL 端点模式

新增将 `base_url` 视作完整上游端点的供应商选项，取代原有的 base-URL 加路径拼接模式 (#1561, 感谢 @yovinchen)。

- 代理转发和 Stream Check 都会遵循完整 URL 模式
- 解锁需要非标准 URL 布局的厂商
- 可在供应商表单中按供应商配置

### OpenCode StepFun Step Plan 预设

- 为 OpenCode 新增 StepFun Step Plan 供应商预设及合理默认值 (#1668, 感谢 @sky-wang-salvation)

### Copilot 调用优化器

新增请求分类和路由逻辑，降低 GitHub Copilot premium interaction 的不必要消耗。

- 根据请求意图和权重进行分类
- 将低价值请求路由到非 premium 通道
- 旨在延长 Copilot 订阅的可用时长
- 注意，即使优化过消耗以后，在 Copilot 外使用 Copilot 的 API 消耗仍然会高于在 Copilot 内使用。

### 首次运行欢迎对话框

新安装用户首次打开时显示一次性欢迎对话框，引导了解 CC Switch 工作流程。

- 说明已有 live 配置如何被保留为默认供应商
- 介绍内置官方预设如何实现一键回滚到官方端点
- 升级用户通过空供应商检查自动跳过

### 官方供应商自动种入

- 启动时自动种入 Claude Official / OpenAI Official / Google Official 供应商条目，为每位用户提供一键回滚到官方端点的路径

### OpenCode / OpenClaw 自动导入

- 启动时自动导入 OpenCode 和 OpenClaw 的 live 供应商配置，与 Claude / Codex / Gemini 已有的自动导入行为对齐

### Common Config 编辑器引导

- 在 Claude / Codex / Gemini 的 Common Config 代码片段编辑器弹窗中添加引导信息和空状态提示
- 用户首次打开供应商添加/编辑表单时弹出一次性对话框说明 Common Config Snippets

### Claude 会话标题与搜索高亮

- 为 Claude 会话新增有意义的标题提取，优先链：自定义标题元数据 → 首条真实用户消息 → 目录名回退
- 在会话管理器搜索时高亮匹配关键词

### URL 图标支持

- 图标系统新增双渲染模式：小 SVG 以 React 组件内联，大 SVG 和光栅图片（PNG / JPG / WebP）通过 Vite URL import 以 `<img>` 标签加载

### Kaku 终端支持

- macOS 上新增 Kaku 作为可选终端用于启动会话，复用 WezTerm 兼容的启动路径 (#1983, 感谢 @yovinchen)

### OMO Slim Council 支持

- 恢复 council 作为内置 oh-my-opencode-slim agent 的一等支持，更新元数据和 UI 文案 (#1982, 感谢 @yovinchen)

### 新供应商预设

- **TheRouter**：覆盖 Claude / Codex / Gemini / OpenCode / OpenClaw 五个应用 (#1891, #1892, 感谢 @cmzz)
- **DDSHub**：作为 Claude 的第三方合作伙伴供应商，含图标和推广文案
- **LionCCAPI**：覆盖全部五个应用，OpenCode / OpenClaw 使用 anthropic-messages 协议
- **胜算云 (Shengsuanyun)**：作为聚合类合作伙伴供应商覆盖全部五个应用，支持 URL 图标和本地化名称
- **PIPELLM**：覆盖 Claude / Codex / OpenCode / OpenClaw，含完整模型定义和图标
- **E-FlowCode**：覆盖全部五个应用，按应用配置不同协议

---

## 变更

### 托盘菜单组织

- 将托盘菜单重构为按应用分级的子菜单（Claude / Codex / Gemini / OpenCode / OpenClaw）
- 防止菜单溢出，支持大量供应商的场景

### 代理转发栈

将代理转发层重建在 Hyper HTTP 客户端之上 (#1714, 感谢 @yovinchen)。

- 透明头部转发：头部透传，不做激进过滤
- 改进的端点重写逻辑
- 更好地支持动态上游端点
- 与新的"完整 URL 端点模式"配合，解锁非标准 URL 布局的厂商

### OAuth Auth Center UI 精修

- 精修 Auth Center 的文案、布局和图标呈现，让 Codex OAuth 登录流程更清爽

### 供应商键生命周期与 Live 同步

重做了新增模式供应商的创建/重命名/复制流程，让 Live 配置写入、清理和回滚在 OpenCode / OpenClaw 与接管场景下保持一致 (#1724, 感谢 @yovinchen)。

- 新增模式高亮行为在刷新后依旧保持 (#1747, 感谢 @yovinchen)
- OpenCode / OpenClaw 的 Live 配置写入保持一致
- 失败时正确回滚，避免半提交状态

### Codex OAuth 默认值

- Codex OAuth 预设升级到 GPT-5.4 系列

---

## Bug 修复

### Copilot 认证与代理兼容性

- 修复 GitHub Copilot 认证回归问题 (#1854, 感谢 @Mason-mengze)
- 修正企业版和动态端点处理
- 修复 macOS 和 Linux 上的剪贴板验证码复制问题
- 修复 Copilot 作为 Claude 供应商时 OpenAI 模型的 Responses 分流 (#1735, 感谢 @Mason-mengze)

### UTF-8 流式分片边界

修复 Claude Code 在 Copilot 反代下，当中文字符或 emoji 等多字节 UTF-8 序列跨 TCP 分片传输时出现的间歇性乱码（U+FFFD 替换字符）问题 (#1923, 感谢 @Cod1ng)。

- 将所有 4 条 SSE 流式路径中的 `String::from_utf8_lossy` 替换为新的 `append_utf8_safe` 辅助函数
- 通过残留缓冲区保留不完整的尾部字节，并在下一个分片合并后再解码
- 直连 Copilot 的场景不可复现，因为直连模式透传原始字节而不做格式转换

### 碎片 System Prompt 规范化

修复严格的 OpenAI 兼容 chat 后端（Nvidia、Qwen 风格）在转换后 Claude 负载包含多条 system 消息时拒绝请求的问题 (#1942, 感谢 @yovinchen)。

- 在 Anthropic → OpenAI chat 转换时将 system 内容合并为单条前置 system 消息
- 其余消息流保持不变

### 流式解析兼容性

- 修复 SSE 解析以接受包含可选空格的字段，提升对非严格流式实现的兼容性 (#1664, 感谢 @Alexlangl)

### 供应商切换状态损坏

- 将按应用的供应商切换串行化，防止并发故障转移或热切换操作导致 `is_current`、设置状态和 Live 备份状态不一致

### Claude 接管 Live 配置漂移

- 修复 Claude 接管启用时供应商编辑导致 Live 设置与供应商状态失步，同时保持接管恢复行为不被破坏 (#1828, 感谢 @geekdada)

### WebDAV 密码保留与校验

- 修复 WebDAV 密码字段在刷新后不可见的问题
- 连接校验时正确处理 `MKCOL 405` 响应 (#1685, 感谢 @Alexlangl)

### 供应商卡片动作状态

- 修复新增模式高亮行为 (#1747, 感谢 @yovinchen)
- 始终渲染动作按钮，对齐各卡片的用量显示布局
- 用警告路径替换硬阻塞的代理切换
- 禁用 Copilot 和 Codex OAuth 卡片上不受支持的测试/用量动作
- 隐藏官方供应商的用量配置和健康检查按钮
- 移除供应商卡片上的 hover 推送动画

### 用量精确性与定价

- 修复 MiniMax 配额数学和 0% → 100% 进度
- 修正 CNY → USD 定价并补齐缺失模型
- 改进 Gemini 会话日志同步的精度
- 修复基于会话的用量条目显示为"未知供应商"的问题

### 用量编辑器与 Skills UI 回归

- 修复编辑提取器代码时用量查询字段被重置的问题 (#1771, 感谢 @if-nil)
- 修正 `skills.sh` 链接失效和空描述问题
- 修复用量配置中的 auto-query 默认间隔（5 分钟）和 number-input 清空问题

### 中文 Skills 术语

- 统一 zh locale 下设置面板中的 Skills 相关标签，保持存储与同步选项用词一致

### 环境与预设兼容性

- 在 CLI 扫描中新增 Bun 全局 bin 检测 (#1742, 感谢 @makoMakoGo)
- 适配 oh-my-openagent 重命名并保持向后兼容 (#1746, 感谢 @yovinchen)
- 修正 OpenCode `kimi-for-coding` 预设 (#1738, 感谢 @makoMakoGo)
- 将 Gemini keychain 解析限制为仅 macOS
- 修复空集合时 OpenClaw 序列化器 panic (#1724, 感谢 @yovinchen)

### Linux 启动时 UI 无响应

修复长期存在的 Linux 专属 bug：窗口 UI（包括原生标题栏按钮）在用户手动最大化再还原之前无法接收点击。

- **根因 1**：Tauri webview 在 Linux 上 `show()` 之后未获得键盘焦点，首次点击被 X11 / Wayland 的 click-to-activate 消费掉（Tauri #10746、wry #637）
- **根因 2**：在某些 WebKitGTK / 合成器组合下，GTK surface 的输入区域在 `visible:false → show()` 路径上未能重协商，导致整个窗口无响应
- **缓解措施**：启动时设置 `WEBKIT_DISABLE_COMPOSITING_MODE=1`，并新增 `linux_fix::nudge_main_window` 辅助函数，在 show 之后 ~200ms 执行 `set_focus` + ±1px 无操作尺寸调整，等效于一次视觉上不可见的"最大化再还原"
- **覆盖范围**：接入所有窗口重新显示路径 —— 正常启动、深链接、单例、托盘 `show_main` 以及轻量模式退出返程

### Linux 标题栏拖动区域

- 在 Linux 上从顶部标题栏移除 `data-tauri-drag-region`，避免触发 Wayland 下受 Tauri #13440 影响的 `gtk_window_begin_move_drag` 路径
- macOS 拖动行为保持不变

### OpenCode / OpenClaw 流式检测边界情况

- 修复自定义头透传
- 修复 OpenClaw 自定义 auth-header 检测
- 修复 Bedrock 错误消息
- 修复 OpenCode 默认 `baseURL` 回退处理

### 供应商切换时重复 Toast

- 修复代理未运行时切换到 Copilot / ChatGPT / OpenAI 格式供应商时出现双重 toast 通知（代理必需警告 + 切换成功）

### 会话搜索精度与中文支持

- 修复会话搜索结果在跨供应商时被截断的问题
- 将 FlexSearch 分词器切换为 full 模式以支持中文子串匹配

### 自适应思维推理力度

- 修复 `resolve_reasoning_effort()` 将自适应思维错误映射为 `high`，应为 `xhigh`（OpenAI 格式转换场景）

### Thinking 模型回退显示

- 修复 Claude 供应商表单仅填写主模型后 Thinking 模型字段显示为空，改为只读回退到 ANTHROPIC_MODEL (#1984, 感谢 @yovinchen)

### Auth Tab 本地化

- 修复设置面板 auth tab 标签在所有语言包中缺失 i18n 翻译 key (#1985, 感谢 @yovinchen)

### 数据库迁移守卫

- 修复 skills 或 model_pricing 表不存在时数据库迁移失败，在 ALTER 和 UPDATE 操作前添加表存在性检查

---

## 文档

### 用户手册刷新

- 在 EN / ZH / JA 用户手册中覆盖托盘子菜单、轻量模式、供应商模型获取、会话管理、工作区文件、WebDAV v2 行为、OpenCode / OpenClaw 启用等供应商工作流改进

### 社区与贡献文档

- 新增 `CONTRIBUTING.md`、`SECURITY.md`、`CODE_OF_CONDUCT.md`
- 新增双语 GitHub issue 和 PR 模板
- 新增 Dependabot 配置 (#1829, 感谢 @bengbengbalabalabeng) 和 stale-bot 工作流以自动关闭不活跃的 issue
- 新增 PR / push 质量检查 CI 工作流

### Release Notes 风险提示回填

- 在三语 v3.12.3 release notes 中新增 Copilot 反代风险提示，并为重点内容添加锚点链接

### 赞助商合作伙伴

- 在三语 README 中新增胜算云、LionCC、DDS 作为赞助商合作伙伴

---

## ⚠️ 风险提示

**Codex OAuth 反向代理免责声明**

本版本新增的 Codex OAuth 反向代理功能通过逆向工程的 OAuth 流程访问 ChatGPT 的 Codex 服务。启用此功能前，请注意以下风险：

1. **违反服务条款**：使用逆向 OAuth 流程访问 OpenAI 服务可能违反 OpenAI 的服务条款，其中禁止未经授权的自动化访问、服务复制以及绕过既定的访问路径。
2. **账号风险**：OpenAI 可能将异常使用模式标记为可疑的自动化行为，从而对 ChatGPT 访问施加临时或永久限制。
3. **无法保证长期可用**：OpenAI 可能随时更新其认证和检测机制，当前可用的使用方式未来可能被标记。

v3.12.3 引入的 **GitHub Copilot 反向代理**同样适用原有风险提示 —— 详见 [v3.12.3 release notes](v3.12.3-zh.md#️-风险提示)。

用户启用上述功能即表示**自行承担所有风险**。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。

---

## 下载与安装

访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。

### 系统要求

| 系统    | 最低版本                   | 架构                                |
| ------- | -------------------------- | ----------------------------------- |
| Windows | Windows 10 及以上          | x64                                 |
| macOS   | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
| Linux   | 见下表                     | x64                                 |

### Windows

| 文件                                     | 说明                                |
| ---------------------------------------- | ----------------------------------- |
| `CC-Switch-v3.13.0-Windows.msi`          | **推荐** - MSI 安装包，支持自动更新 |
| `CC-Switch-v3.13.0-Windows-Portable.zip` | 便携版，解压即用，不写入注册表      |

### macOS

| 文件                             | 说明                                          |
| -------------------------------- | --------------------------------------------- |
| `CC-Switch-v3.13.0-macOS.dmg`    | **推荐** - DMG 安装包，拖入 Applications 即可 |
| `CC-Switch-v3.13.0-macOS.zip`    | 解压后拖入 Applications，Universal Binary     |
| `CC-Switch-v3.13.0-macOS.tar.gz` | 用于 Homebrew 安装和自动更新                  |

> macOS 版本已通过 Apple 代码签名和公证，可直接安装使用。

### Homebrew（macOS）

```bash
brew tap farion1231/ccswitch
brew install --cask cc-switch
```

更新：

```bash
brew upgrade --cask cc-switch
```

### Linux

| 发行版                                  | 推荐格式    | 安装方式                                                               |
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` |
| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm`  |
| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                |
| Arch Linux / Manjaro                    | `.AppImage` | 添加执行权限后直接运行，或使用 AUR                                     |
| 其他发行版 / 不确定                     | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |