cc-switch/docs/release-notes/v3.12.0-en.md

# CC Switch v3.12.0

> Stream Check Returns, OpenAI Responses API Arrives, and OpenClaw / WebDAV Get a Major Upgrade

**[中文版 →](v3.12.0-zh.md) | [日本語版 →](v3.12.0-ja.md)**

---

## Overview

CC Switch v3.12.0 is a feature release focused on provider compatibility, OpenClaw editing, Common Config usability, and sync/data reliability. It restores the **Model Health Check (Stream Check)** UI with improved stability, adds **OpenAI Responses API** format conversion, expands provider presets for **Ucloud**, **Micu**, **X-Code API**, **Novita**, and **Bailian For Coding**, and upgrades **WebDAV sync** with dual-layer versioning.

**Release Date**: 2026-03-09

**Update Scale**: 56 commits | 221 files changed | +20,582 / -8,026 lines

---

## Highlights

- **Stream Check returns**: Restored the model health check UI, added first-run confirmation, and fixed `openai_chat` provider support
- **OpenAI Responses API**: Added `api_format = "openai_responses"` with bidirectional conversion and shared conversion cleanup — simply select the Responses API format when adding a provider and enable proxy takeover, and you can use GPT-series models in Claude Code!
- **OpenClaw overhaul**: Introduced JSON5 round-trip config editing, a config health banner, better agent model selection, and a User-Agent toggle
- **Preset expansion**: Added Ucloud, Micu, X-Code API, Novita, and Bailian For Coding updates, plus SiliconFlow partner badge and model-role badges
- **Sync and maintenance improvements**: Added WebDAV protocol v2 + db-v6 versioning, daily rollups, incremental auto-vacuum, and sync-aware backup
- **Common Config usability improvements**: After updating a Common Config Snippet, it is now automatically applied when switching providers — no more manual checkbox needed

---

## Main Features

### Model Health Check (Stream Check)

Restored the Stream Check panel for live provider validation, improving the reliability of provider management.

- Restored Stream Check UI panel with single and batch provider availability testing
- Added first-run confirmation dialog to prevent unsupported providers from showing misleading errors
- Fixed detection compatibility for `openai_chat` API format providers

### OpenAI Responses API

Added native support for providers using the OpenAI Responses API with a new `openai_responses` API format.

- New `api_format = "openai_responses"` provider format option
- Bidirectional Anthropic Messages <-> OpenAI Responses API format conversion
- Consolidated shared conversion logic to reduce code duplication

### Bedrock Request Optimizer

Added a PRE-SEND phase request optimizer for AWS Bedrock providers to improve compatibility and performance.

- PRE-SEND thinking + cache injection optimizer (#1301, thanks @keithyt06)

### OpenClaw Config Enhancements

Comprehensive upgrade to the OpenClaw configuration editing experience with richer management capabilities.

- JSON5 round-trip write-back: preserves comments and formatting when editing configs
- EnvPanel JSON editing mode and `tools.profile` selection support
- New config validation warnings and config health status checks
- Improved agent model dropdown with recommended model fill from provider presets
- User-Agent toggle: optionally append OpenClaw identifier to requests (defaults to off)
- Legacy timeout configuration auto-migration

### Provider Presets

New and expanded provider presets covering more providers and use cases.

- **Ucloud**: Added `endpointCandidates` and OpenClaw defaults, refreshed `templateValues` / `suggestedDefaults`
- **Micu**: Added preset defaults and OpenClaw recommended models
- **X-Code API**: Added Claude presets and `endpointCandidates`
- **Novita**: New provider preset (#1192, thanks @Alex-wuhu)
- **Bailian For Coding**: New provider preset (#1263, thanks @suki135246)
- **SiliconFlow**: Added partner badge
- **Model Role Badges**: Provider presets now support model-role badge display

### WebDAV Sync Enhancements

WebDAV sync introduces dual-layer versioning for improved sync reliability and data safety.

- New WebDAV protocol v2 + db-v6 dual-layer versioning
- Confirmation dialog when toggling WebDAV auto-sync on/off to prevent accidental changes
- Sync-aware backup: uses a sync-specific backup variant that skips local-only table data

### Usage & Data

Enhanced usage statistics and data maintenance capabilities for finer-grained data management, significantly reducing database growth rate.

- Daily rollups: aggregate usage data by day to reduce storage overhead
- Auto-vacuum: incremental database cleanup to maintain database health
- UsageFooter extra statistics fields (#1137, thanks @bugparty)

### Other New Features

- **Session Deletion**: Per-provider session cleanup with path safety validation
- **Claude Auth Field Selector**: Restored authentication field selector
- **Failover Toggle on Main Page**: Moved the failover toggle to display independently on the main page with a first-use confirmation dialog
- **Common Config Auto-Extract**: On first run, automatically extracts common config snippets from live config files
- **New Provider Page Improvements**: Improved new provider page experience (#1155, thanks @wugeer)

---

## Architecture Improvements

### Common Config Runtime Overlay

Common Config Snippets are now applied as a runtime overlay instead of being materialized into stored provider configs.

**Before**: Common Config content was merged directly into each provider's `settings_config` on save or switch. This caused shared configuration to be duplicated across every provider entry, requiring manual sync when changes were needed.

**After**: Common Config is only injected as a runtime overlay when switching providers and writing to the live file — provider entries themselves no longer contain shared configuration. This means modifying Common Config takes effect immediately without updating each provider individually.

### Common Config Auto-Extract

On first run, if no Common Config Snippet exists in the database, one is automatically extracted from the current live config. This ensures users upgrading from older versions do not lose their existing shared configuration settings.

### Periodic Maintenance Timer Consolidation

Consolidated daily rollups and auto-vacuum into a unified periodic maintenance timer, eliminating resource contention and complexity from multiple independent timers.

---

## Bug Fixes

### Proxy & Streaming

- Fixed OpenAI ChatCompletion -> Anthropic Messages streaming conversion
- Added Codex `/responses/compact` route support (#1194, thanks @Tsukumi233)
- Improved TOML config merge logic to prevent key-value loss
- Improved proxy forwarder failure logs with additional diagnostic information

### Provider & Preset Fixes

- Renamed X-Code to X-Code API for consistent branding
- Fixed SSSAiCode `/v1` path issue
- Removed incorrect `www` prefix from AICoding URLs
- Fixed new provider page line-break deletion issue (#1155, thanks @wugeer)

### Platform Fixes

- Fixed cache hit token statistics not being reported (#1244, thanks @a1398394385)
- Fixed minimize-to-tray causing auto exit after some time (#1245, thanks @YewFence)

### i18n Fixes

- Added 69 missing translation keys and removed remaining hardcoded Chinese strings
- Fixed model test panel i18n issues
- Normalized JSON5 slash escaping to prevent i18n string parsing errors

### UI Fixes

- Fixed Skills count display (#1295, thanks @fzzv)
- Removed HTTP status code display from endpoint speed test to reduce visual noise
- Fixed outline button styling (#1222, thanks @Sube-py)

---

## Performance

- Skip unnecessary OpenClaw config writes when config is unchanged, reducing disk I/O

---

## Documentation

- Restructured the user manual for i18n and added complete EN/JA coverage
- Added OpenClaw usage documentation and completed settings documentation
- Added UCloud sponsor information
- Reorganized the docs directory and synced README feature sections across EN/ZH/JA

---

## Notes & Considerations

- **Common Config now uses runtime overlay**: Common Config Snippets are no longer materialized into each provider's stored config. They are dynamically applied at switch time. Modifying Common Config takes effect immediately without updating each provider.
- **Stream Check requires first-use confirmation**: A confirmation dialog appears when using the model health check for the first time. Testing proceeds only after confirmation.
- **OpenClaw User-Agent toggle defaults to off**: The User-Agent identifier must be manually enabled in the OpenClaw configuration.

---

## Special Thanks

Thanks to all contributors for their contributions to this release!

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

---

## Download & Installation

Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download the appropriate version.

### System Requirements

| System  | Minimum Version                 | Architecture                        |
| ------- | ------------------------------- | ----------------------------------- |
| Windows | Windows 10 or later             | x64                                 |
| macOS   | macOS 10.15 (Catalina) or later | Intel (x64) / Apple Silicon (arm64) |
| Linux   | See table below                 | x64                                 |

### Windows

| File                                     | Description                                          |
| ---------------------------------------- | ---------------------------------------------------- |
| `CC-Switch-v3.12.0-Windows.msi`          | **Recommended** - MSI installer with auto-update     |
| `CC-Switch-v3.12.0-Windows-Portable.zip` | Portable version, extract and run, no registry write |

### macOS

| File                             | Description                                                          |
| -------------------------------- | -------------------------------------------------------------------- |
| `CC-Switch-v3.12.0-macOS.zip`    | **Recommended** - Extract and drag to Applications, Universal Binary |
| `CC-Switch-v3.12.0-macOS.tar.gz` | For Homebrew installation and auto-update                            |

> **Note**: Since the author doesn't have an Apple Developer account, you may see an "unidentified developer" warning on first launch. Please close it, then go to "System Settings" -> "Privacy & Security" -> click "Open Anyway", and it will open normally afterwards.

### Homebrew (macOS)

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

Update:

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

### Linux

| Distribution                            | Recommended Format | Installation Method                                                    |
| --------------------------------------- | ------------------ | ---------------------------------------------------------------------- |
| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`             | `sudo dpkg -i CC-Switch-*.deb` or `sudo apt install ./CC-Switch-*.deb` |
| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`             | `sudo rpm -i CC-Switch-*.rpm` or `sudo dnf install ./CC-Switch-*.rpm`  |
| openSUSE                                | `.rpm`             | `sudo zypper install ./CC-Switch-*.rpm`                                |
| Arch Linux / Manjaro                    | `.AppImage`        | Add execute permission and run directly, or use AUR                    |
| Other distributions / Unsure            | `.AppImage`        | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |