docs(release): add v4.0 release notes in Chinese, English and Japanese

Add the v4.0 release notes and the screenshots they reference
(main page, Apps page, Aggregation, Codex model picker, session reader
and usage, in Chinese and English) under assets/release-notes/v4.0.0.
This commit is contained in:
Jason committed 2026-10-04 16:25:20 +08:00
1 parent bfd28b2f9f
commit 6d6bbe6747
15 files changed
+522

No files matched your search

+174
View File
@@ -0,0 +1,174 @@
# CC Switch v4.0
### A redesigned interface, the new Aggregation mode, and safer config switching
This is the biggest CC Switch release yet. With it, we've rethought the core of the CC Switch experience: how you connect to models, how you switch providers, and how you manage a growing set of AI coding tools.
The interface has been redesigned from the sidebar to the tray, giving apps, config, usage and sessions each a clear place. The new Aggregation mode puts models from several providers into one Claude Code or Codex model picker, so you can switch between them right inside the client. Session management has been rewritten from scratch: what the AI did in each turn, what it changed and which step failed are all visible at a glance. And the config-writing core has been rebuilt: switching providers now replaces only the key fields instead of rewriting the whole file, which removes a great deal of complexity and puts an end to a whole class of lost-settings problems.
---
## A Redesigned Interface
The new interface uses a sidebar layout and an orange theme. Switching apps, plus global features like MCP, Skills, Prompts, Sessions, Accounts and Usage, are all one click away in the sidebar.
![The new interface: sidebar, mode tabs and provider cards](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/main-en.png)
- **Modes at a glance**: Every app page has three tabs at the top: Direct / Routing / Aggregation. Clicking a tab only changes what you're looking at and never touches your config. The button that actually switches modes tells you what will happen, and going back to Direct takes one step and can be undone
- **A home for your tools**: The new Apps page shows each AI coding tool's version, install location and source, with install, upgrade and batch upgrade
- **A cleaner Add Provider panel**: Search, pick a preset, fill in the form. Search matches Chinese names and domains, and one vendor's plans and regions are merged into one row, so Claude's 94 presets now take 71 rows. Preset providers are no longer highlighted as recommendations
- **Quota shows what's left**: Cards read "5-hour 94% left" or "Balance 8.99 CNY". Quota stays quiet until you're running low, then turns bold. Click it to re-check and see the result. Codex subscriptions also show how many saved resets are left and when they expire
- **Tray organized by app**: Each row reads "name · mode · provider · quota", and submenus list only the providers you can switch to right now. The tray icon shows a dot only when something really needs your attention
- **Settings grouped by purpose**: General, App config, Local routing, Network, Data, About. Local routing's service status, listen address and failover settings now live in one place
![The Apps page: versions, installs and upgrades for every AI coding tool in one place](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/apps-en.png)
Upgrading users see a short note on first launch explaining where things have moved.
---
## Aggregation: Many Providers, One Model Picker
Until now, using another provider's model meant going back to CC Switch, switching providers, and returning to your client.
Turn on **Aggregation**, add a few providers, and their models all show up together in the Claude Code or Codex model picker. Whichever model you pick, the request goes straight to that provider, without ever leaving the client.
![Models from several providers listed together in Codex's model picker](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/agg-codex-en.png)
- **Add and remove anytime**: Click "Add" or "Remove" on a provider card, then choose one provider as the default to handle requests that don't name an aggregated model
- **Know every model at a glance**: Each model name carries its provider, like "Kimi K3 (Kimi For Coding)", and its description shows the real upstream model ID and context window, like `kimi-k3 · 256K`
- **A streamlined form**: Connection details and the model list sit on one page; that's all Aggregation needs
- **Mix providers in Codex without errors**: Set your official account as the default, and official and third-party models are listed side by side. Switch back and forth between providers' models and context compaction and reasoning state carry over
- **Switch models mid-session**: You can change to another model partway through a session. Note that after each switch, the new model has to build its prompt cache again, so the first turn after switching costs noticeably more
- **Restart reminders**: When the model list changes you're prompted to restart the client, and Codex CLI users can restart the background service from the banner in one click
![Aggregation: one default provider plus six added providers](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/agg-en.png)
Aggregation is opt-in and currently supports Claude Code and Codex. It routes each request by the model you pick, and does not offer failover.
| Mode | How requests travel | Best for |
|------|---------------------|----------|
| **Direct** | The client talks to the provider directly | Everyday use |
| **Routing** | Through local routing to one provider, with protocol conversion and failover | Incompatible protocols, or when you need failover |
| **Aggregation** | Through local routing, dispatched by model to several providers | Mixing models from several providers in one session |
> **A Tribute to opencodex**
>
> Aggregation learned a great deal from [opencodex](https://github.com/lidge-jun/opencodex) and builds directly on its ideas: prefixing model IDs with the provider so models from many providers can share the Claude Code and Codex pickers; letting Codex compact context on third-party models; and detecting when a background service is still using an old model list, then prompting a restart. All of these came out of opencodex's exploration. Our thanks to its author ([@lidge-jun](https://github.com/lidge-jun)) and contributors for open-sourcing this work, and our deepest respect for their open-source spirit!
>
> If you want a tool dedicated to bringing any model into Codex and Claude Code, we highly recommend giving opencodex a try!
---
## Session Management: See Every AI Coding Session Clearly
AI coding tools keep a complete record of every session on your machine, but the raw logs are thousands of lines of JSON and nearly impossible to read. This release rewrites session management from scratch to make those records as readable as possible, and adds token usage and cost for each session.
![The session reader: step summaries, tool call details and the conversation outline](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/session-en.png)
- **Nine clients, one way to read them**: Sessions from Claude Code, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes, Pi and MiniMax Code are parsed into structured content, with text, thinking, tool calls, tool results and images each shown in their own form
- **One turn, one summary line**: A long run of AI actions folds into a single line, such as "Steps · 44 · 27 commands · 2 files changed · 1 failed · 27m45s". Failed commands are marked in red, and expanding one shows its parameters, output and exit code. Runs of file reads and searches merge into "Read N files, searched N times"
- **Conversation outline**: The right-hand panel lists each of your prompts along with how many steps the turn took and what it concluded. Turns with failed steps get a red dot; click to jump there
- **Three views**: "All" shows the full process, "Chat" shows only what you and the AI said, and "Changes" shows only which files were changed
- **The whole session at a glance**: The header shows the project directory, start and end time, number of prompts and tool calls, model, total tokens and the cost at API prices
- **Find in session**: Matches hidden inside folded tool output are expanded and scrolled into view automatically, and typing stays smooth even in long sessions
- **From reading back to working**: Resume a session in your favorite terminal (Ghostty, for example) in one click, or copy the resume command. You can also export to Markdown and copy a single turn or the whole conversation
- **An easier-to-search list**: Group by project or time, search titles, directories, first and last messages or session IDs, and delete in bulk
- OpenCode 2.x sessions are now supported, and Hermes sessions open correctly again
The session reader redesign was led by [@Owlbay](https://github.com/Owlbay). Many thanks to Owlbay for the enormous effort.
---
## Switch Providers, Keep Your Config Intact
This is the most important under-the-hood change in this release. It applies to Claude Code, Codex, Gemini CLI, Grok Build and Claude Desktop.
CC Switch launched in August 2025, when the API ecosystem was far less mature than it is today. API formats often differed widely between official and third-party providers, so the original design rewrote the whole config file on every switch. That choice brought a series of problems and a lot of complexity. Now that the ecosystem has matured, it's time to rebuild.
**Before**: Switching providers rewrote the entire config file from that provider's saved snapshot. Hooks, plugins and permissions you added to `settings.json`, or MCP servers you added to `config.toml`, were either lost on switch or absorbed into one provider's snapshot, disappearing as soon as you switched to another.
**Now**: Switching replaces only the endpoint, credential, model and protocol, plus the provider's own switches. Everything else stays exactly where it was:
- In TOML and `.env` files, untouched lines, comments and order included, stay byte for byte the same
- In JSON files, every other key keeps its value and order
- Shared settings simply stay in your config file, so the "common config snippet" feature is no longer needed
**The editor previews what your config file will look like after switching**. Global settings you edit there are written to the config file, and before saving CC Switch checks whether another program has changed the file in the meantime.
The new write engine also adds several layers of protection:
- If a config file can't be parsed, writing stops and the original file is left untouched
- External changes are checked before writing, so a file another program just saved is never overwritten
- When several files change together, the intent is recorded first. If the app quits unexpectedly midway, the next launch finishes the job automatically instead of leaving things half-written
- Each file is backed up as-is before the new version writes to it for the first time
- Config files that hold keys are readable and writable only by you
Turning routing on or off no longer relies on backing up and restoring your whole config. When Codex switches to a third-party provider, the ChatGPT login it overwrites is stashed locally and restored automatically when you switch back to your official account.
---
## Usage
**The Usage page** has redesigned metrics, a trend chart, a request log, and four paginated tables for providers, models and pricing. A new "All" time range shows your daily usage as a 53-week heatmap, and wide-range queries no longer freeze the window.
![Usage: the 53-week heatmap and request log](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/usage-en.png)
**Output speed** is now measured over generation time only, without the wait for the first token. Even without routing, requests imported from Claude Code and Codex session logs get an estimated speed, marked with "≈".
---
## More Improvements
- **MCP**: Paste several server configs at once in JSON, TOML, Codex or OpenCode format. If writing to one app fails you can retry just that app, and one bad server no longer stops the others from syncing
- **Skills**: "Installed" and "Discover" are merged into one page with one-click "Update all", and you can choose the sync method: automatic, symlink only or copy only
- **Prompts**: Manage prompts for eight apps on one page, copy them to other apps, import existing files, and undo a delete
- **Accounts**: Accounts, re-login actions and remaining quota at a glance
- **Model metadata autofill**: When you pick a fetched model, its context window, output limit, reasoning levels and input types are filled in from presets and models.dev, without overwriting anything you've already entered
- **Claude Desktop**: With model mapping, the local routing service starts on its own and stops when no longer needed
- **OpenCode**: Comments and formatting in `opencode.jsonc` survive sync, and OpenCode 2.x usage is tracked
- **MiniMax Code**: Install and upgrade it from the Apps page, and choose your own provider key when creating a provider
- **Presets and pricing**: New Command Code preset; updated pricing for Claude Opus 5.5, GPT-6 Sol / Luna, MiMo V2.6 and more; all 738 presets now have proper icons
---
## Fixes
- After quitting with `⌘Q`, the Dock's "Quit" or logging out on macOS, clients stayed pointed at the stopped local routing service
- Replies on the Codex official route appeared only after a long delay, with usage recorded as 0
- GPT models in the Codex model catalog lost their official prompts, tool capabilities and reasoning levels
- MiniMax tool calls failed to parse their arguments, and some models' thinking showed up mixed into the reply text
- Since Codex 0.158, the `type` field in MCP config caused errors and could even stop Codex from starting
- Adding or importing a prompt could empty a prompt file you wrote by hand
- Syncing Skills deleted same-named folders inside OpenClaw's directory
- Upgrading some CLIs installed an extra npm copy
- The database file didn't shrink after old logs were pruned
- "Save and restart service" in settings didn't actually restart the service
---
## Before You Upgrade
**Where settings live has changed.** Shared settings now stay in the client's own config file, and the "common config snippet" feature has been removed. A model or reasoning effort you pick temporarily in the client goes back to the provider's value when you switch away and back. To keep it, save it in the provider editor.
**Some fixes take effect after one switch.** The Codex model catalog and session history fixes apply the next time CC Switch writes the Codex config, so just switch providers once after upgrading. Re-sync your existing MCP config once to clear the old `type` field.
**Restart when prompted after switching.** Codex, Gemini CLI and Grok Build need a restart after switching models, and clients need a restart after the Aggregation list changes.
**Existing cards stay as they are.** Preset updates only apply to newly created providers. New pricing only backfills requests previously recorded at $0; other historical costs are not recalculated.
**Two settings have been removed.** Per-provider cost multipliers (relay prices already include their multiplier, so applying another one only skews the numbers), and the connectivity-check advanced settings (built-in defaults are used now).
---
## Thanks
Thanks to everyone who contributed to this release:
[@Owlbay](https://github.com/Owlbay) (session reader redesign, usage heatmap and performance), [@qyinter](https://github.com/qyinter) (extensive UI/UX polish), [@funkpopo](https://github.com/funkpopo), [@allenxu09](https://github.com/allenxu09), [@ISuuuu](https://github.com/ISuuuu), [@SailingLoong](https://github.com/SailingLoong), [@ggbdpq](https://github.com/ggbdpq), [@tingfeng347](https://github.com/tingfeng347), [@Hexc01](https://github.com/Hexc01), [@zhengkaics](https://github.com/zhengkaics), [@DEAN-Cherry](https://github.com/DEAN-Cherry), [@7ten7](https://github.com/7ten7), [@2doright](https://github.com/2doright), [@RemindZ](https://github.com/RemindZ), [@M3chD09](https://github.com/M3chD09), [@Richard-Zhang1019](https://github.com/Richard-Zhang1019), [@YuxuZhou-CN](https://github.com/YuxuZhou-CN), [@Eureka0w0v0](https://github.com/Eureka0w0v0), [@Ne1ther](https://github.com/Ne1ther), [@h6rime](https://github.com/h6rime), [@bigben446](https://github.com/bigben446), [@szupzj18](https://github.com/szupzj18), [@AnxForever](https://github.com/AnxForever)
Thanks also to [@PnutCN](https://github.com/PnutCN), [@Aaron-WealthTech](https://github.com/Aaron-WealthTech), [@parkavenue9639](https://github.com/parkavenue9639), [@RuriLothlorien](https://github.com/RuriLothlorien), [@Ming-Sir-69](https://github.com/Ming-Sir-69) for detailed bug reports and investigation that helped us pin down the problems.
Special thanks to the [opencodex](https://github.com/lidge-jun/opencodex) project; much of Aggregation's design benefits from its open-source exploration.
And thanks to everyone who filed an issue or helped reproduce a bug. For the full technical details, see the [CHANGELOG](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md).
+174
View File
@@ -0,0 +1,174 @@
# CC Switch v4.0
### 新しい画面、新しい集約モード、より安全な設定切り替え
CC Switch 史上最大規模のアップデートです。今回は、モデルへの接続方法、プロバイダーの切り替え方、そして増え続ける AI コーディングツールの管理方法という、CC Switch の最も核となる体験を見直しました。
サイドバーからトレイまで画面をすべて作り直し、アプリ、設定、使用量、セッションのそれぞれにわかりやすい居場所を用意しました。新しい集約モードでは、複数のプロバイダーのモデルを Claude Code や Codex の 1 つのモデル一覧にまとめ、クライアントの中でそのまま切り替えられます。セッション管理もゼロから書き直し、AI が各ターンで何をしたか、何を変更したか、どのステップで失敗したかがひと目でわかるようになりました。さらに設定書き込みの土台も作り直しました。プロバイダーの切り替えはファイル全体の書き直しから重要項目だけの置き換えに変わり、複雑さを大きく減らすと同時に、設定が失われる一連の問題を解消しています。
---
## 新しい画面
新しい画面はサイドバーレイアウトとオレンジのテーマを採用しています。アプリの切り替えに加え、MCP、Skills、プロンプト、セッション、アカウント、使用量といった共通機能にも、サイドバーから直接移動できます。
![新しい画面:サイドバー、モードタブ、プロバイダーカード](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/main-en.png)
- **モードがひと目でわかる**:各アプリページの上部に「直接接続 / ルーティング / 集約」の 3 つのタブがあります。タブを押しても表示が切り替わるだけで、設定は変わりません。実際にモードを切り替えるボタンには何が起きるかが書かれており、直接接続へはワンステップで戻れて、元に戻すこともできます
- **ツールの居場所ができました**:新しい「アプリ」ページで、各 AI コーディングツールのバージョン、インストール場所、入手元をまとめて確認でき、インストール、アップグレード、一括アップグレードもここから行えます
- **すっきりしたプロバイダー追加パネル**:検索してプリセットを選び、フォームに入力するだけです。検索は中国語名やドメインにも対応し、同じ事業者のプランや地域違いは 1 行にまとめられるため、Claude の 94 個のプリセットは 71 行に収まりました。プリセットプロバイダーのおすすめ強調表示もすべて廃止しました
- **残量で表示する利用枠**:カードには「5時間 残り 94%」「残高 8.99 CNY」のように表示されます。普段は控えめで、残りわずかになると太字で知らせます。利用枠をクリックすると再取得し、その結果も表示します。Codex のサブスクリプションでは、残りのリセット回数と有効期限も表示されます
- **アプリごとに整理したトレイ**:各行に「名前 · モード · プロバイダー · 利用枠」を表示し、サブメニューには今切り替えられるプロバイダーだけを並べます。トレイアイコンのドットは、本当に対応が必要なときだけ表示されます
- **用途別の設定**:一般、アプリ設定、ローカルルーティング、ネットワーク、データ、情報に分類しました。ローカルルーティングのサービス状態、待ち受けアドレス、フェイルオーバー設定も 1 か所にまとまっています
![アプリページ:各 AI コーディングツールのバージョン、インストール、アップグレードを一元管理](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/apps-en.png)
既存ユーザーには、初回起動時に主な機能の移動先を説明する短い案内が表示されます。
---
## 集約:複数のプロバイダーを 1 つのモデル一覧で
これまでは別のプロバイダーのモデルを使いたいとき、CC Switch に戻ってプロバイダーを切り替え、それからクライアントに戻る必要がありました。
**集約**モードをオンにしてプロバイダーをいくつか追加すると、それぞれのモデルが Claude Code や Codex のモデル選択画面にまとめて表示されます。選んだモデルに応じてリクエストがそのプロバイダーへ直接送られるので、クライアントから離れる必要はありません。
![Codex のモデル選択画面に複数プロバイダーのモデルが並ぶ様子](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/agg-codex-en.png)
- **いつでも追加・削除**:プロバイダーカードの「追加」「削除」を押すだけです。さらに 1 社をデフォルトプロバイダーに選ぶと、集約モデルを指定していないリクエストはそこへ送られます
- **モデルをひと目で見分けられる**:モデル名の後ろには提供元のプロバイダーが付き(例:「Kimi K3(Kimi For Coding)」)、説明には上流の実際のモデル ID とコンテキストウィンドウ(例:`kimi-k3 · 256K`)が表示されます
- **シンプルな設定フォーム**:接続情報とモデル一覧を 1 ページにまとめ、集約に必要な項目だけを入力できます
- **Codex で混在させてもエラーにならない**:公式アカウントをデフォルトにすると、公式モデルとサードパーティのモデルが並んで表示されます。異なるプロバイダーのモデルを行き来しても、コンテキスト圧縮や推論の状態が引き継がれます
- **同じセッション内でモデルを変更**:セッションの途中で別のモデルに切り替えられます。ただし切り替えるたびに新しいモデルでプロンプトキャッシュを作り直すため、切り替え直後の 1 ターン目は料金が明らかに高くなります
- **再起動のお知らせ**:モデル一覧が変わるとクライアントの再起動を促します。Codex CLI はバナーからワンクリックでバックグラウンドサービスを再起動できます
![集約モード:デフォルトプロバイダー 1 社と、追加済みの 6 社](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/agg-en.png)
集約は手動でオンにする機能で、現在は Claude Code と Codex に対応しています。選んだモデルごとにリクエストを振り分ける仕組みのため、フェイルオーバーはありません。
| モード | リクエストの流れ | 向いている使い方 |
|------|-----------|--------|
| **直接接続** | クライアントがプロバイダーに直接接続 | 普段の利用 |
| **ルーティング** | ローカルルーティング経由で 1 社に転送。プロトコル変換やフェイルオーバーが可能 | プロトコルが合わないとき、フェイルオーバーが必要なとき |
| **集約** | ローカルルーティング経由で、モデルごとに複数社へ振り分け | 1 つのセッションで複数社のモデルを使い分けたいとき |
> **opencodex への敬意**
>
> 集約モードは [opencodex](https://github.com/lidge-jun/opencodex) から多くを学び、参考にしています。モデル ID にプロバイダーの接頭辞を付けて、複数社のモデルを Claude Code や Codex の選択画面に同時に並べること。サードパーティのモデルでも Codex がコンテキスト圧縮を行えるようにすること。バックグラウンドサービスが古いモデル一覧を使い続けていないか検知して再起動を促すこと。これらの発想はすべて opencodex の探求から生まれたものです。この成果をオープンソースとして公開してくださった opencodex の作者([@lidge-jun](https://github.com/lidge-jun))とコントリビューターの皆さんに感謝するとともに、そのオープンソース精神に心からの敬意を表します!
>
> 「あらゆるモデルを Codex と Claude Code で使う」ことに特化したツールをお探しなら、opencodex をぜひお試しください!
---
## セッション管理:AI コーディングのすべてをはっきりと
AI コーディングツールは各セッションの記録をローカルに丸ごと保存していますが、元の記録は何千行もの JSON で、そのまま読むのはほぼ不可能です。今回のバージョンではセッション管理をゼロから書き直し、記録をできる限り読みやすくしたうえで、トークン使用量と料金の集計も加えました。
![セッションビューア:実行過程の要約、ツール呼び出しの詳細、会話の目次](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/session-en.png)
- **9 つのクライアントを同じ読み方で**:Claude Code、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi、MiniMax Code の記録を構造化して解析し、本文、思考、ツール呼び出し、ツール結果、画像をそれぞれの形で表示します
- **1 ターンの作業を 1 行に要約**:AI の長い一連の操作を「実行過程 · 44 ステップ · コマンド 27 件 · 2 ファイルを変更 · 1 件失敗 · 27m45s」のように 1 行にまとめます。失敗したコマンドは赤で表示され、展開すると引数、出力、終了コードを確認できます。ファイルの読み込みや検索が続く部分は「N ファイルを参照、N 回検索」にまとめられます
- **会話の目次**:右側にあなたの各プロンプトと、そのターンのステップ数や結論を一覧表示します。失敗したステップがあるターンには赤いドットが付き、クリックするとその場所へ移動します
- **3 つの表示**:「すべて」で全過程を、「会話」であなたと AI のやり取りだけを、「変更」で変更されたファイルだけを表示します
- **セッションの全体像をひと目で**:上部にプロジェクトのディレクトリ、開始・終了時刻、プロンプト数、ツール呼び出し数、モデル、合計トークン数、API 価格で計算した料金を表示します
- **セッション内検索**:一致した内容が折りたたまれたツール出力の中にあっても、自動で展開して表示します。長いセッションでも入力がもたつきません
- **読んだらそのまま作業再開**:よく使うターミナル(Ghostty など)でワンクリックでセッションを再開でき、再開コマンドのコピーもできます。Markdown へのエクスポートや、1 ターン単位・会話全体のコピーにも対応しています
- **見つけやすい一覧**:プロジェクト別・時間別にグループ化し、タイトル、ディレクトリ、最初と最後のメッセージ、セッション ID で検索できます。一括削除にも対応しています
- OpenCode 2.x のセッションに対応し、Hermes のセッションも正しく開けるようになりました
セッションビューアの刷新は [@Owlbay](https://github.com/Owlbay) が中心となって進めてくれました。Owlbay の多大な尽力に感謝します。
---
## プロバイダーを切り替えても、設定はそのまま
今回のアップデートで最も重要な内部の変更です。対象は Claude Code、Codex、Gemini CLI、Grok Build、Claude Desktop です。
CC Switch を公開した 2025 年 8 月当時、API のエコシステムは今ほど成熟しておらず、公式とサードパーティのプロバイダーの間で API の形式が大きく異なることも珍しくありませんでした。そのため当初の設計では、切り替えのたびに設定ファイル全体を上書きする方式を選びました。しかしこの選択は、一連の問題と複雑さを生むことになりました。エコシステムが成熟した今こそ、作り直すときです。
**これまで**:プロバイダーを切り替えると、そのプロバイダーに保存されたスナップショットで設定ファイル全体を書き直していました。`settings.json` に追加した hooks、プラグイン、権限設定や、`config.toml` に追加した MCP サーバーは、切り替え時に失われるか、特定のプロバイダーのスナップショットに取り込まれ、別のプロバイダーに切り替えると消えてしまっていました。
**これから**:切り替えで置き換えるのは、エンドポイント、認証情報、モデル、プロトコルと、そのプロバイダー独自のスイッチだけです。それ以外はすべてそのまま残ります:
- TOML と `.env` ファイルでは、変更しない行はコメントや順序も含めて 1 バイトも変わりません
- JSON ファイルでは、ほかのすべてのキーの値と順序が保たれます
- 共有設定はもともと設定ファイルに残るため、「共通設定スニペット」機能は不要になりました
**エディターの下部に、切り替え後の設定ファイルのプレビューが表示されます**。ここで編集した全体設定は設定ファイルに書き込まれ、保存前にはほかのプログラムがファイルを変更していないかも確認します。
新しい書き込みの仕組みは、いくつもの保護も備えています:
- 設定ファイルの形式に誤りがある場合は書き込みを中止し、元のファイルには手を付けません
- 書き込み前に外部での変更を確認し、ほかのプログラムが保存したばかりの内容を上書きしません
- 複数のファイルを同時に変更するときは、先に操作内容を記録します。途中で予期せず終了しても、次回起動時に自動で後始末をするため、中途半端な状態で止まることはありません
- 新バージョンが各ファイルに初めて書き込む前に、元の状態のバックアップを取ります
- キーを含む設定ファイルは、本人だけが読み書きできるようにしています
ルーティングのオン・オフも、設定全体の「バックアップと復元」に頼らなくなりました。Codex をサードパーティのプロバイダーに切り替えたときに上書きされる ChatGPT のログイン情報はローカルに一時保存され、公式アカウントに戻すと自動で復元されます。
---
## 使用量
**使用量ページ**では、指標、トレンドグラフ、リクエストログ、そしてプロバイダー、モデル、料金の各統計表を作り直し、すべてページ送りに対応しました。新しい「すべて」の期間では、53 週分のヒートマップで日ごとの使用量を表示します。広い範囲の集計でも、ウィンドウが固まらなくなりました。
![使用量:53 週ヒートマップとリクエストログ](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/usage-en.png)
**出力速度**は、最初のトークンまでの待ち時間を除いた生成時間だけで計算するようになりました。ルーティングを使っていなくても、Claude Code や Codex のセッションログから取り込んだリクエストには推定速度が「≈」付きで表示されます。
---
## その他の改善
- **MCP**:複数のサーバー設定をまとめて貼り付けられ、JSON、TOML、Codex、OpenCode の形式を認識します。あるアプリへの書き込みに失敗してもそのアプリだけ再試行でき、1 つのサーバーのエラーがほかのサーバーに影響しなくなりました
- **Skills**:「インストール済み」と「見つける」を 1 ページに統合し、ワンクリックで一括更新できます。同期方法は自動、シンボリックリンクのみ、コピーのみから選べます
- **プロンプト**:8 つのアプリのプロンプトを 1 ページで管理でき、ほかのアプリへのコピー、既存ファイルの取り込み、削除の取り消しに対応しました
- **アカウント**:アカウント、再ログインの入口、利用枠の残量がひと目でわかります
- **モデル情報の自動補完**:取得したモデルを選ぶと、プリセットと models.dev からコンテキストウィンドウ、出力上限、推論レベル、入力の種類を補完します。入力済みの値は上書きしません
- **Claude Desktop**:モデルマッピングを使うと、ローカルルーティングのサービスが自動で起動し、不要になると自動で停止します
- **OpenCode**:同期しても `opencode.jsonc` のコメントや書式が保たれ、OpenCode 2.x の使用量にも対応しました
- **MiniMax Code**:「アプリ」ページからインストールとアップグレードができ、新しいプロバイダーを作るときにプロバイダーキーを自分で指定できます
- **プリセットと料金**:Command Code のプリセットを追加し、Claude Opus 5.5、GPT-6 Sol / Luna、MiMo V2.6 などの料金を更新しました。738 個のプリセットすべてに正式なアイコンが付きました
---
## 修正
- macOS で `⌘Q`、Dock の「終了」、ログアウトで終了したあと、クライアントが停止済みのローカルルーティングを向いたままになる問題
- Codex 公式ルートの応答がなかなか表示されず、使用量が 0 と記録される問題
- Codex のモデルカタログで、GPT モデルの公式プロンプト、ツール機能、推論レベルが失われる問題
- MiniMax のツール呼び出しで引数の解析に失敗する問題と、一部モデルの思考内容が本文に混ざって表示される問題
- Codex 0.158 以降、MCP 設定の `type` フィールドが原因でエラーになり、起動すらできなくなる問題
- プロンプトを追加・取り込みしたときに、手書きのプロンプトファイルが空になることがある問題
- Skills の同期で、OpenClaw のディレクトリ内にある同名フォルダーを誤って削除する問題
- 一部の CLI をアップグレードすると、npm のコピーが余分にインストールされる問題
- 古いログを整理してもデータベースファイルが小さくならない問題
- 設定の「保存してサービスを再起動」で、実際にはサービスが再起動されない問題
---
## アップグレードの前に
**設定の置き場所が変わりました。** 共有設定はクライアントの設定ファイルにそのまま残り、「共通設定スニペット」機能は廃止されました。クライアント内で一時的に選んだモデルや推論強度は、別のプロバイダーに切り替えて戻すと、プロバイダーに設定された値に戻ります。固定したい場合は、プロバイダーエディターで保存してください。
**一部の修正は、一度切り替えると反映されます。** Codex のモデルカタログとセッション履歴の分類に関する修正は、CC Switch が次に Codex の設定を書き込んだときに適用されます。アップグレード後にプロバイダーを一度切り替えてください。既存の MCP 設定は一度同期し直すと、古い `type` フィールドが削除されます。
**切り替え後は案内に従って再起動してください。** Codex、Gemini CLI、Grok Build はモデルを切り替えたあとに再起動が必要です。集約の一覧を変更したあとも、クライアントの再起動が必要です。
**既存のカードはそのままです。** プリセットの更新は新しく作成するプロバイダーにのみ適用されます。新しい料金で補完されるのは、これまで $0 で記録されていたリクエストだけで、それ以外の過去の料金は再計算されません。
**2 つの設定を廃止しました。** プロバイダーのコスト倍率(中継サービスの価格にはすでに倍率が含まれているため、さらに掛けると計算がずれます)と、接続チェックの詳細設定(現在は組み込みの既定値を使用します)です。
---
## 謝辞
このバージョンに貢献してくださった皆さんに感謝します:
[@Owlbay](https://github.com/Owlbay)(セッションビューアの刷新、使用量ヒートマップとパフォーマンス)、[@qyinter](https://github.com/qyinter)(UI/UX の大幅な磨き込み)、[@funkpopo](https://github.com/funkpopo)、[@allenxu09](https://github.com/allenxu09)、[@ISuuuu](https://github.com/ISuuuu)、[@SailingLoong](https://github.com/SailingLoong)、[@ggbdpq](https://github.com/ggbdpq)、[@tingfeng347](https://github.com/tingfeng347)、[@Hexc01](https://github.com/Hexc01)、[@zhengkaics](https://github.com/zhengkaics)、[@DEAN-Cherry](https://github.com/DEAN-Cherry)、[@7ten7](https://github.com/7ten7)、[@2doright](https://github.com/2doright)、[@RemindZ](https://github.com/RemindZ)、[@M3chD09](https://github.com/M3chD09)、[@Richard-Zhang1019](https://github.com/Richard-Zhang1019)、[@YuxuZhou-CN](https://github.com/YuxuZhou-CN)、[@Eureka0w0v0](https://github.com/Eureka0w0v0)、[@Ne1ther](https://github.com/Ne1ther)、[@h6rime](https://github.com/h6rime)、[@bigben446](https://github.com/bigben446)、[@szupzj18](https://github.com/szupzj18)、[@AnxForever](https://github.com/AnxForever)
詳しい問題報告と調査で原因の特定を助けてくださった [@PnutCN](https://github.com/PnutCN)、[@Aaron-WealthTech](https://github.com/Aaron-WealthTech)、[@parkavenue9639](https://github.com/parkavenue9639)、[@RuriLothlorien](https://github.com/RuriLothlorien)、[@Ming-Sir-69](https://github.com/Ming-Sir-69) にも感謝します。
[opencodex](https://github.com/lidge-jun/opencodex) プロジェクトにも特別な感謝を。集約モードの多くの設計は、そのオープンソースでの探求の恩恵を受けています。
issue を報告してくださった方、問題の再現に協力してくださった方にも感謝します。技術的な詳細は [CHANGELOG](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md) をご覧ください。
+174
View File
@@ -0,0 +1,174 @@
# CC Switch v4.0
### 全新界面,全新聚合模式,更稳的配置切换
这是 CC Switch 迄今规模最大的一次更新。这次更新,我们重新梳理了 CC Switch 最核心的体验:如何接入模型、如何切换供应商,以及如何管理越来越多的 AI 编程工具。
界面从侧边栏到托盘全部重新设计,应用、配置、用量和会话都有了清楚的位置。新推出的聚合模式可以把多家供应商的模型放进 Claude Code 或 Codex 的同一个模型列表,在客户端里随手切换。会话管理也从头重写,AI 每一轮做了什么、改了什么、哪一步失败了,都一目了然。重写了配置写入的底层机制:切换供应商时,由全量重写改为关键字段替换,大幅降低复杂度的同时避免了一系列配置丢失问题。
---
## 全新界面
新界面采用侧边栏布局和橙色主题。应用切换,以及 MCP、Skills、提示词、会话、授权中心、用量统计这些全局功能,都可以从侧边栏直接进入。
![新界面:侧边栏、模式标签和供应商卡片](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/main-zh.png)
- **模式一目了然**:每个应用页的顶部是「直连 / 路由 / 聚合」三个标签。点标签只切换查看的内容,不会改动配置;真正切换模式的按钮会写明会发生什么,回到直连只需一步,还能撤销
- **工具有了自己的家**:新的「应用」页集中显示每个 AI 编程工具的版本、安装位置和来源,支持安装、升级和批量升级
- **更简洁的添加供应商面板**:搜索、选预设,填表单。搜索支持中文名和域名;同一家的不同套餐和地区合并成一行,Claude 的 94 个预设现在只占 71 行。取消了所有预设供应商的高亮推荐
- **额度显示剩余量**:卡片上直接写「5 小时剩余 94%」「余额 8.99 CNY」。平时不显眼,快用完时才加粗提醒;点击额度会重新查询,并显示查询结果。Codex 订阅显示剩余重置次数和过期时间
- **托盘按应用重新组织**:每行显示「名称 · 模式 · 供应商 · 额度」,子菜单里只列出当前能切换的供应商。只有真正需要你处理时,托盘图标才显示提醒点
- **设置按用途分组**:通用、应用配置、本地路由、网络、数据、关于。本地路由的服务状态、监听地址和故障转移参数都集中在一处
![应用页:集中管理各个 AI 编程工具的版本、安装与升级](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/apps-zh.png)
老用户第一次打开新版时,会看到一次简短的说明,告诉你常用功能搬到了哪里。
---
## 聚合:一个模型列表,多家供应商
以前想用另一家供应商的模型,得先回到 CC Switch 切换供应商,再回到客户端继续工作。
现在开启**聚合**模式,把几家供应商添加进来,它们的模型会同时出现在 Claude Code 或 Codex 的模型选择器里。选哪个模型,请求就发给哪一家,不用离开客户端。
![Codex 的模型选择器里同时列出多家供应商的模型](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/agg-codex-zh.png)
- **随时添加和移除**:在供应商卡片上点「添加」或「移除」。再选一家作为默认供应商,没有指定聚合模型的请求都交给它
- **一眼认出模型**:每个模型名后面都标着来自哪家供应商,比如「Kimi K3(Kimi For Coding)」;说明里还会写出上游真实的模型 ID 和上下文窗口,比如 `kimi-k3 · 256K`
- **精简的配置表单**:连接信息和模型列表放在同一页,聚合时只需要填这些
- **Codex 混用不报错**:把官方账号设为默认,官方模型和第三方模型会并列显示。在不同供应商的模型之间来回切换,上下文压缩和推理状态都能接上
- **同一会话里换模型**:可以在一个会话中途换用其他模型。注意每次切换后,新模型都要重新建立提示词缓存,切换后的第一轮费用会明显高一些
- **重启提醒**:模型列表变化后会提示重启客户端,Codex CLI 可以在横幅里一键重启后台服务
![聚合模式:一家默认供应商,另外添加了 6 家](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/agg-zh.png)
聚合需要手动开启,目前支持 Claude Code 和 Codex。它按你选的模型分发请求,不提供故障转移。
| 模式 | 请求怎么走 | 适合什么情况 |
|------|-----------|--------|
| **直连** | 客户端直接连供应商 | 日常使用 |
| **路由** | 经本地路由转发给一家供应商,可以转换协议、设置故障转移 | 协议不兼容,或者需要故障转移 |
| **聚合** | 经本地路由,按模型分发给多家供应商 | 在一个会话里混用多家模型 |
> **致敬 opencodex**
>
> 聚合模式大量学习和参考了 [opencodex](https://github.com/lidge-jun/opencodex)。给模型 ID 加上供应商前缀,让多家模型同时出现在 Claude Code 和 Codex 的选择器里;让 Codex 在第三方模型上也能做上下文压缩;检测后台服务是否还在用旧的模型列表,并提醒重启。这些思路都来自 opencodex 的探索。感谢 opencodex 的作者([@lidge-jun](https://github.com/lidge-jun))和贡献者们把这些成果开源出来,向他们的开源精神致以崇高的敬意!
>
> 如果你想要一个专注于「任意模型接入 Codex 和 Claude Code」的工具,非常推荐试试 opencodex!
---
## 会话管理:每一次 AI 编程,都看得清清楚楚
AI 编程工具会把每次会话完整地记在本机,但原始记录是成千上万行 JSON,几乎没法直接读。这一版我们从头重写了会话管理,让会话记录尽可能地易读,同时添加了用量和消耗金额统计。
![会话阅读页:执行过程摘要、工具调用详情和对话目录](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/session-zh.png)
- **九个客户端,同一种读法**:Claude Code、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi、MiniMax Code 的记录都解析成结构化内容,正文、思考、工具调用、工具结果和图片各自呈现
- **一轮工作,一行摘要**:AI 的一长串操作折叠成一行,比如「执行过程 · 44 步 · 27 个命令 · 改了 2 个文件 · 1 个失败 · 27m45s」。失败的命令标成红色,展开就能看到参数、输出和退出码;连续读文件、搜索这类步骤会合并成「查看了 N 个文件、搜索 N 次」
- **对话目录**:右侧列出你的每一次提问,以及这一轮用了多少步、得出了什么结论。有失败步骤的轮次带红点,点一下就跳过去
- **三种视图**:「全部」看完整过程,「对话」只看你和 AI 说了什么,「改动」只看改了哪些文件
- **会话全貌一眼可见**:顶部显示项目目录、起止时间、提问次数、工具调用次数、模型、总 Token 数,以及按 API 价格算的费用
- **会话内查找**:命中的内容即使藏在折叠的工具输出里,也会自动展开定位;长会话里输入也不卡
- **从阅读到继续工作**:一键在你常用的终端(比如 Ghostty)里恢复会话,也可以复制恢复命令;还支持导出 Markdown、复制单轮或整段对话
- **列表更好找**:按项目或时间分组,搜索标题、目录、首末消息或会话 ID,支持批量删除
- 支持 OpenCode 2.x 的会话,Hermes 会话也能正常打开了
会话阅读页的重做由 [@Owlbay](https://github.com/Owlbay) 主导完成,感谢 Owlbay 投入的大量心血。
---
## 切换供应商,你的配置原封不动
这是这次更新里最重要的底层变化,适用于 Claude Code、Codex、Gemini CLI、Grok Build 和 Claude Desktop。
CC Switch 发布于 2025 年 8 月,那个时候 API 的生态远没有现在成熟,各家官方和第三方供应商之间的 API 格式往往差距非常大,所以在最初设计的时候,切换供应商选择了全量覆盖。但这个选择带来了一系列的问题和复杂度。随着生态的成熟,现在是时候重构了。
**以前**:切换供应商时,会用这家存下的快照重写整个配置文件。你在 `settings.json` 里加的 hooks、插件、权限设置,在 `config.toml` 里加的 MCP 服务器,要么在切换时丢失,要么被收进某一家供应商的快照,切到别家就没了。
**现在**:切换只替换地址、凭据、模型、协议这几项,以及这家供应商自己的开关。其他内容原样保留:
- TOML 和 `.env` 文件里,没改到的行连同注释、顺序,逐字节保持不变
- JSON 文件里,其他每个键的值和顺序都保持不变
- 共享设置本来就留在配置文件里,所以「通用配置片段」功能也就不需要了
**编辑器底部会预览切换后配置文件的样子**。在这里直接改的全局设置会写进配置文件,保存前还会检查文件是否被别的程序改过。
新的写入机制同时带来几层保护:
- 配置文件格式有误时停止写入,原文件保持不动
- 写入前先检查外部改动,不会覆盖其他程序刚保存的内容
- 同时改多个文件时先记下意图,即使中途意外退出,下次启动也会自动收尾,不会停在只改了一半的状态
- 每个文件第一次由新版写入前,原样备份一份
- 含密钥的配置文件只允许本人读写
开启或关闭路由,也不再依赖「备份、还原」整份配置。Codex 切到第三方供应商时被覆盖的 ChatGPT 登录会暂存在本机,切回官方账号时自动还原。
---
## 用量统计
**用量页**重新设计了指标、趋势图、请求日志,以及供应商、模型、定价四张统计表,都支持分页。新增「全部」时间范围,用 53 周热力图显示每天的用量。大范围统计时,窗口不再卡顿。
![用量统计:53 周热力图与请求日志](https://raw.githubusercontent.com/farion1231/cc-switch/main/assets/release-notes/v4.0.0/usage-zh.png)
**输出速度**改为只按生成时间计算,去掉了首字等待。即使没开路由,从 Claude Code、Codex 会话日志导入的请求也能显示估算速度,用「≈」标记。
---
## 更多改进
- **MCP**:可以一次粘贴多个服务器配置,JSON、TOML、Codex 和 OpenCode 格式都能识别。某个应用写入失败时可以单独重试,一个服务器出错也不会影响其他服务器
- **Skills**:「已安装」和「发现」合并成一页,可以一键全部更新,同步方式可选自动、仅符号链接、仅复制
- **提示词**:八个应用的提示词在同一页管理,支持复制到其他应用、导入已有文件、删除后撤销
- **授权中心**:账号、重新登录入口和剩余额度一目了然
- **模型参数自动补全**:选中拉取到的模型时,会从预设和 models.dev 补上上下文窗口、输出上限、推理档位和输入类型,不覆盖你已经填过的值
- **Claude Desktop**:使用模型映射时,本地路由服务会自动启动,用完自动停止
- **OpenCode**:`opencode.jsonc` 里的注释和格式在同步时会保留,支持 2.x 的用量统计
- **MiniMax Code**:可以在「应用」页安装和升级,新建供应商时可以自己填供应商 key
- **预设与定价**:新增 Command Code 预设,更新 Claude Opus 5.5、GPT-6 Sol / Luna、MiMo V2.6 等模型的定价;全部 738 个预设都有了正式图标
---
## 修复
- macOS 上用 `⌘Q`、Dock「退出」或注销退出后,客户端仍然指向已经停止的本地路由
- Codex 官方路由的回复迟迟不显示,用量记为 0
- Codex 模型目录里的 GPT 模型丢失官方提示词、工具能力和推理档位
- MiniMax 工具调用参数解析失败;部分模型的思考内容混在正文里显示
- Codex 0.158 起,MCP 配置里的 `type` 字段导致报错,甚至无法启动
- 新增或导入提示词时,可能清空你手写的提示词文件
- 同步 Skills 时误删 OpenClaw 目录下的同名文件夹
- 部分 CLI 升级时额外装出一份 npm 副本
- 清理旧日志后,数据库文件没有缩小
- 设置里「保存并重启服务」没有真正重启服务
---
## 升级须知
**配置的归属变了。** 共享设置直接留在客户端配置文件里,「通用配置片段」功能已经移除。在客户端里临时选的模型或推理强度,切到别家再切回来时,会恢复成供应商设定的值。想固定下来,在供应商编辑器里保存即可。
**有些修复需要切换一次才生效。** Codex 模型目录和会话分组的修复,要等 CC Switch 下一次写入 Codex 配置时才会应用,升级后切换一次供应商即可。已有的 MCP 配置重新同步一次,就能清掉旧的 `type` 字段。
**切换后记得按提示重启。** Codex、Gemini CLI、Grok Build 切换模型后需要重启,聚合列表变化后也需要重启客户端。
**已有的卡片保持原样。** 预设更新只影响新建的供应商;新定价只回补之前按 $0 记录的请求,其余历史费用不会重算。
**两个设置移除了。** 供应商成本倍率(中转站价格本身已经包含倍率,再乘一次只会算错),以及连通性检查的高级设置(现在使用内置默认值)。
---
## 致谢
感谢这一版的贡献者:
[@Owlbay](https://github.com/Owlbay)(会话阅读页重做、用量页热力图与性能)、[@qyinter](https://github.com/qyinter)(大量 UI/UX 打磨)、[@funkpopo](https://github.com/funkpopo)、[@allenxu09](https://github.com/allenxu09)、[@ISuuuu](https://github.com/ISuuuu)、[@SailingLoong](https://github.com/SailingLoong)、[@ggbdpq](https://github.com/ggbdpq)、[@tingfeng347](https://github.com/tingfeng347)、[@Hexc01](https://github.com/Hexc01)、[@zhengkaics](https://github.com/zhengkaics)、[@DEAN-Cherry](https://github.com/DEAN-Cherry)、[@7ten7](https://github.com/7ten7)、[@2doright](https://github.com/2doright)、[@RemindZ](https://github.com/RemindZ)、[@M3chD09](https://github.com/M3chD09)、[@Richard-Zhang1019](https://github.com/Richard-Zhang1019)、[@YuxuZhou-CN](https://github.com/YuxuZhou-CN)、[@Eureka0w0v0](https://github.com/Eureka0w0v0)、[@Ne1ther](https://github.com/Ne1ther)、[@h6rime](https://github.com/h6rime)、[@bigben446](https://github.com/bigben446)、[@szupzj18](https://github.com/szupzj18)、[@AnxForever](https://github.com/AnxForever)
感谢 [@PnutCN](https://github.com/PnutCN)、[@Aaron-WealthTech](https://github.com/Aaron-WealthTech)、[@parkavenue9639](https://github.com/parkavenue9639)、[@RuriLothlorien](https://github.com/RuriLothlorien)、[@Ming-Sir-69](https://github.com/Ming-Sir-69) 详细的问题报告和排查,帮我们准确定位了问题。
特别感谢 [opencodex](https://github.com/lidge-jun/opencodex) 项目,聚合模式的许多设计都受益于它的开源探索。
也感谢每一位提交 issue、帮忙复现问题的用户。完整的技术细节请见 [CHANGELOG](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md)。