# CC Switch v3.12.0

> Stream Check 回归，OpenAI Responses API 上线，OpenClaw 与 WebDAV 迎来一次大升级

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

---

## 概览

CC Switch v3.12.0 是一个功能版本，重点提升供应商兼容性、OpenClaw 配置编辑体验、通用配置功能使用体验，以及同步与数据维护能力。本次恢复了增强稳定性后的 **模型健康检查（Stream Check）** UI，新增 **OpenAI Responses API** 格式转换，扩展了 **Ucloud**、**Micu**、**X-Code API**、**Novita**、**Bailian For Coding** 等供应商预设，并为 **WebDAV 同步** 引入双层版本控制。

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

**更新规模**：56 commits | 221 files changed | +20,582 / -8,026 lines

---

## 重点内容

- **Stream Check 回归**：恢复模型健康检查 UI，新增首次使用确认，并修复 `openai_chat` 供应商检测
- **OpenAI Responses API**：新增 `api_format = "openai_responses"`，支持双向格式转换并整理共享转换逻辑，只需要在添加供应商的时候选择 Response 接口格式并开启代理接管，您就可以在 Claude Code 中使用 gpt 系列模型了！
- **OpenClaw 面板升级**：引入 JSON5 round-trip 配置编辑、配置健康提示、改进后的 Agent Model 选择和 User-Agent 开关
- **预设扩展**：补充 Ucloud、Micu、X-Code API、Novita、Bailian For Coding 预设，并新增 SiliconFlow partner badge 与模型角色标识
- **同步与维护增强**：新增 WebDAV protocol v2 + db-v6 双层版本、daily rollups、增量 auto-vacuum 和 sync-aware backup
- **通用配置功能使用体验优化**：现在通用配置片段更新之后，会在切换供应商时自动同步到新的供应商，不需要再手动勾选。

---

## 主要功能

### 模型健康检查 Stream Check

恢复 Stream Check 面板，用于实时验证供应商可用性，增强供应商管理的可靠性。

- 恢复 Stream Check UI 面板，支持单个或批量检测供应商可用性
- 新增首次使用确认对话框，避免不支持健康检查的供应商报错误导用户
- 修复 `openai_chat` API 格式供应商的检测兼容性

### OpenAI Responses API

新增 `openai_responses` API 格式，为使用 OpenAI Responses API 的供应商提供原生支持。

- 新增 `api_format = "openai_responses"` 供应商格式选项
- 支持 Anthropic Messages <-> OpenAI Responses API 双向格式转换
- 整理共享转换逻辑，减少重复代码

### Bedrock 请求优化器

为 AWS Bedrock 供应商新增 PRE-SEND 阶段请求优化器，提升兼容性和性能。

- PRE-SEND thinking + cache injection 优化器（#1301，感谢 @keithyt06）

### OpenClaw 配置增强

OpenClaw 配置编辑体验全面升级，支持更丰富的配置管理。

- JSON5 round-trip 写回：编辑配置时保留注释和格式
- EnvPanel 支持 JSON 编辑模式和 `tools.profile` 选择
- 新增配置校验提示和配置健康状态检查
- Agent 模型下拉框改进，支持从供应商预设填充推荐模型
- User-Agent 开关：可选在请求中附加 User-Agent 标识（默认关闭）
- Legacy timeout 配置自动迁移

### 供应商预设 Preset

新增和扩展多组供应商预设，覆盖更多供应商和使用场景。

- **Ucloud**：新增 `endpointCandidates` 以及 OpenClaw 默认值，刷新 `templateValues` / `suggestedDefaults`
- **Micu**：新增预设默认值及 OpenClaw 推荐模型
- **X-Code API**：新增 Claude 预设及 `endpointCandidates`
- **Novita**：新增供应商预设（#1192，感谢 @Alex-wuhu）
- **Bailian For Coding**：新增供应商预设（#1263，感谢 @suki135246）
- **SiliconFlow**：新增 partner badge 标识
- **模型角色标识**：供应商预设支持模型角色 badge 显示

### WebDAV 同步增强

WebDAV 同步引入双层版本控制，提升同步可靠性和数据安全性。

- 新增 WebDAV protocol v2 + db-v6 双层版本控制
- 切换 WebDAV auto-sync 时弹出确认对话框，防止误操作
- sync-aware backup：WebDAV 同步时使用 sync 变体备份，跳过仅本地使用的表数据

### 用量与数据

用量统计和数据维护能力增强，数据管理更精细，极大降低数据库增长速度。

- Daily rollups：按天汇总用量数据，减少存储占用
- Auto-vacuum：增量式数据库清理，保持数据库健康
- UsageFooter 新增额外统计字段（#1137，感谢 @bugparty）

### 其他新功能

- **会话删除**：按供应商清理会话记录，带路径安全校验
- **Claude auth field selector 恢复**：恢复认证字段选择器
- **Failover 开关独立显示**：将 failover toggle 从设置面板移到主页独立展示，并新增首次确认对话框
- **通用配置自动抽取**：首次运行时自动从 live config 中抽取通用配置片段
- **新供应商页面改进**：优化新建供应商页面体验（#1155，感谢 @wugeer）

---

## 架构改进

### Common Config 运行时叠加

通用配置片段（Common Config Snippet）改为运行时叠加方式应用，不再物化写入每个供应商配置。

**变更前**：Common Config 内容在保存或切换时直接合并写入每个供应商的 `settings_config`。这导致公共配置被复制到每个供应商条目中，修改时需要逐一同步。

**变更后**：Common Config 仅在切换供应商写入 live 文件时以 runtime overlay 方式注入，供应商条目本身不包含公共配置。这意味着修改 Common Config 后立即生效，无需逐一更新每个供应商。

### 通用配置首次自动抽取

首次运行时，如果数据库中尚无 Common Config Snippet，会自动从当前 live config 中抽取通用配置。这确保了从旧版本升级的用户不会丢失已有的通用配置设置。

### 定期维护定时器整合

将 daily rollups 和 auto-vacuum 整合到统一的定期维护定时器中，避免多个独立定时器带来的资源竞争和复杂度。

---

## Bug 修复

### 代理与流式转换

- 修复 OpenAI ChatCompletion -> Anthropic Messages 流式转换问题
- 新增 Codex `/responses/compact` 路由支持（#1194，感谢 @Tsukumi233）
- 改进 TOML 配置合并逻辑，避免键值丢失
- 改进 proxy forwarder 失败日志，增加更多诊断信息

### 供应商预设修复

- X-Code 更名为 X-Code API，统一品牌命名
- 修复 SSSAiCode `/v1` 路径问题
- 移除 AICoding URL 错误的 `www` 前缀
- 优化新建供应商页面换行删除问题（#1155，感谢 @wugeer）

### 平台修复

- 修复 cache hit token 统计缺失（#1244，感谢 @a1398394385）
- 修复最小化到托盘后一段时间自动退出的问题（#1245，感谢 @YewFence）

### i18n 修复

- 补齐 69 个缺失翻译 key，清理剩余硬编码中文
- 修复 model test panel 的 i18n 问题
- 规范 JSON5 slash escaping，避免国际化字符串解析异常

### UI 修复

- 修复 Skills 计数显示问题（#1295，感谢 @fzzv）
- 移除 endpoint speed test 的 HTTP 状态码显示，减少视觉噪音
- 修复 outline button 样式问题（#1222，感谢 @Sube-py）

---

## 性能优化

- OpenClaw 配置未变化时跳过无意义写入，减少磁盘 I/O

---

## 文档

- 重构用户手册以支持国际化，补齐 EN/JA 完整内容
- 新增 OpenClaw 使用说明，补完设置章节
- 新增 UCloud 赞助商信息
- 重组 docs 目录结构，同步 EN/ZH/JA README 的功能说明

---

## 说明与注意事项

- **Common Config 改为运行时叠加**：通用配置片段不再物化写入每个供应商配置，而是在切换时动态叠加。修改 Common Config 后立即生效，无需逐一更新供应商。
- **Stream Check 首次使用需确认**：首次使用模型健康检查时会弹出确认对话框，确认后方可使用。
- **OpenClaw User-Agent 开关默认关闭**：需要在 OpenClaw 配置中手动开启 User-Agent 标识附加功能。

---

## 特别感谢

感谢以下贡献者为本版本做出的贡献！

@keithyt06 @bugparty @Alex-wuhu @suki135246 @Tsukumi233 @wugeer @fzzv @Sube-py @a1398394385 @YewFence

---

## 下载与安装

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

### 系统要求

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

### Windows

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

### macOS

| 文件                             | 说明                                                      |
| -------------------------------- | --------------------------------------------------------- |
| `CC-Switch-v3.12.0-macOS.zip`    | **推荐** - 解压后拖入 Applications 即可，Universal Binary |
| `CC-Switch-v3.12.0-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`              |