# CC Switch v3.12.3

> Tool Search 域名限制绕过、Skill 备份/恢复生命周期、代理 Gzip 压缩与 o 系列模型兼容性

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

---

## 概览

CC Switch v3.12.3 新增了通过二进制补丁绕过 Tool Search 域名白名单限制的功能，引入了完整的 Skill 备份/恢复生命周期，改进了代理对 OpenAI o 系列模型的兼容性和 gzip 压缩支持，并修复了 Skills 导入、供应商表单和终端会话恢复等方面的问题。Skill 卸载前会自动备份并支持恢复和删除管理，导入流程从基于文件系统的隐式推断改为显式应用选择。

**发布日期**：2026-03-16

**更新规模**：17 commits | 61 files changed | +3,335 / -194 lines

---

## 重点内容

- **Tool Search 域名绕过**：新增设置项，通过等长二进制补丁移除 Claude CLI Tool Search 域名白名单检查，启动时自动备份和重新应用
- **Skill 备份/恢复生命周期**：卸载前自动备份 Skill 文件；新增备份列表、恢复和删除管理

- **代理 Gzip 压缩**：非流式代理请求现在自动协商 gzip 压缩，减少带宽消耗
- **o 系列模型兼容性**：Chat Completions 代理正确使用 `max_completion_tokens` 处理 o1/o3/o4-mini 模型；Responses API 保持使用正确的 `max_output_tokens` 字段
- **Skills 导入重构**：将基于文件系统的隐式应用推断替换为显式的 `ImportSkillSelection`，防止多应用错误激活
- **Ghostty 终端支持**：修复在 Ghostty 终端中恢复 Claude 会话的问题

---

## 新功能

### Tool Search 域名限制绕过

新增设置项，可绕过 Claude CLI Tool Search 的域名白名单限制。

- 从 PATH 中解析当前活跃的 `claude` 命令，应用等长字节补丁移除域名白名单检查
- 备份存储在 `~/.cc-switch/toolsearch-backups/`（以路径的 SHA-256 为文件名），Claude Code 升级后备份仍然有效
- 设置启用时，应用启动自动重新应用补丁
- 前端检查补丁结果，失败时自动回滚设置

### Skill 卸载自动备份

卸载 Skill 前自动备份文件，防止数据意外丢失。

- 备份存储在 `~/.cc-switch/skill-backups/`，包含所有 skill 文件和记录原始元数据的 `meta.json`
- 旧备份自动清理，最多保留 20 个
- 备份路径返回前端并在成功提示中显示

### Skill 备份恢复与删除

新增卸载时创建的 Skill 备份的管理功能。

- 列出所有可用的 skill 备份及元数据
- 恢复操作将文件拷回 SSOT，保存数据库记录，并同步到当前应用，失败时自动回滚
- 删除操作在确认对话框后移除备份目录
- ConfirmDialog 新增可配置的 zIndex 属性，支持嵌套对话框堆叠

---

## 变更

### 代理 Gzip 压缩

非流式代理请求现在支持 gzip 压缩，减少带宽消耗。

- 非流式请求允许 reqwest 自动协商 gzip 并透明解压响应
- 流式请求保守地保持 `Accept-Encoding: identity`，避免中断的 SSE 流解压出错

### o1/o3 模型兼容性

代理转发现在正确处理 OpenAI o 系列模型的 token 参数。

- Chat Completions 路径对 o1/o3/o4-mini 模型使用 `max_completion_tokens` 替代 `max_tokens` (#1451)
- Responses API 路径保持使用正确的 `max_output_tokens` 字段，不再错误注入 `max_completion_tokens`

### OpenCode 模型变体

- 将 OpenCode 的模型变体放在预设顶层而非嵌套在 options 内部，提升可发现性 (#1317)

### Skills 导入流程

Skills 导入流程经过重构，提升正确性和清理能力。

- 将基于文件系统的隐式应用推断替换为显式的 `ImportSkillSelection`，防止同一 skill 目录存在于多个应用路径下时错误激活多个应用
- 为 `sync_to_app` 增加协调逻辑，移除已禁用/孤立的符号链接
- MCP `sync_all_enabled` 现在会从 live 配置中移除已禁用的服务器
- 数据库迁移保留旧版应用映射快照，避免有损重建

---

## Bug 修复

### 供应商表单防重复提交

- 修复快速连续点击按钮时供应商添加/编辑表单重复提交的问题 (#1352)

### Ghostty 终端会话恢复

- 修复在 Ghostty 终端中恢复 Claude 会话失败的问题 (#1506，感谢 @canyonsehun)

### Skill ZIP 导入扩展名

- ZIP 导入对话框现在支持 `.skill` 文件扩展名 (#1240, #1455)

### Skill ZIP 安装目标应用

- ZIP 方式安装的 skill 现在使用当前活跃应用，而非始终默认为 Claude

### OpenClaw 活跃供应商高亮

- 修复 OpenClaw 当前激活的供应商卡片未高亮显示的问题 (#1419)

### 响应式布局与 TOC

- 改善存在 TOC 标题时的响应式布局 (#1491)

### Skills 导入对话框白屏

- 在 ImportSkillsDialog 中补充缺失的 TooltipProvider，修复打开对话框时的运行时崩溃

### 面板底部空白区域

- 将所有内容面板的硬编码 `h-[calc(100vh-8rem)]` 替换为 `flex-1 min-h-0`，消除因不同平台偏移量不匹配导致的底部空白

---

## 下载与安装

访问 [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.12.3-Windows.msi`            | **推荐** - MSI 安装包，支持自动更新 |
| `CC-Switch-v3.12.3-Windows-Portable.zip`   | 便携版，解压即用，不写入注册表      |

### macOS

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

> **注意**：由于作者没有苹果开发者账号，首次打开可能出现"未知开发者"警告，请先关闭，然后前往"系统设置" → "隐私与安全性" → 点击"仍要打开"，之后便可以正常打开

### 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`              |