chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,101 @@
|
||||
# Using DeepSeek-Style Chat APIs in Codex: CC Switch Local Routing Guide
|
||||
|
||||
> Applies to CC Switch 3.16.0 and nearby versions. This guide is based on the repository documentation and code, and uses DeepSeek as an example of an OpenAI Chat Completions-compatible API. Screenshots are generated from the current frontend UI with de-identified sample data to avoid exposing a real API key or account balance.
|
||||
|
||||
## Why local routing is needed
|
||||
|
||||
The newer Codex CLI targets the OpenAI Responses API, while DeepSeek, Kimi, MiniMax, SiliconFlow, and many other providers expose the OpenAI Chat Completions shape, usually `/chat/completions`. These two protocols use different request bodies, streaming events, and response structures. If you put a Chat endpoint directly into Codex configuration, common results include an incorrect model list, 404/400 requests, or streaming responses that Codex cannot parse correctly.
|
||||
|
||||
CC Switch solves this by making Codex always talk to a local route and continue sending Responses API requests. The route detects whether the active provider is Chat-format, rewrites the request into Chat Completions for the upstream provider, and finally converts the Chat response back into the Responses shape that Codex understands.
|
||||
|
||||
|
||||
|
||||
The chain has four main steps:
|
||||
|
||||
1. When Codex routing is enabled, the local configuration is written as `http://127.0.0.1:15721/v1`, while `wire_api = "responses"` is kept in place.
|
||||
2. The provider's `meta.apiFormat = "openai_chat"` tells the route that the real upstream is Chat Completions.
|
||||
3. The route rewrites `/responses` or `/v1/responses` to `/chat/completions`, and converts the Responses request body into a Chat request body.
|
||||
4. After the upstream responds, the route converts the Chat JSON or SSE stream back into Responses JSON/SSE.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Prepare these three things first:
|
||||
|
||||
- CC Switch installed and able to start.
|
||||
- Codex CLI installed and run at least once, so the `~/.codex/config.toml` directory structure exists.
|
||||
- An API key from DeepSeek or another Chat Completions provider.
|
||||
|
||||
DeepSeek's official documentation currently lists the OpenAI-compatible base URL as `https://api.deepseek.com` (other providers often use a base URL with a `/v1` suffix), and the Chat API path as `/chat/completions`. CC Switch's DeepSeek preset already contains these details, so prefer the preset and do not manually assemble the endpoint path.
|
||||
|
||||
## Step 1: Add a Codex provider
|
||||
|
||||
Open CC Switch, switch to the top-level `Codex` tab, and click the plus button in the upper-right corner to add a provider.
|
||||
|
||||
Choose the built-in `DeepSeek` preset. You only need to do two things:
|
||||
|
||||
- Enter your DeepSeek API key.
|
||||
- Save the provider.
|
||||
|
||||
|
||||
|
||||
The preset already includes DeepSeek's request base URL, default model, model menu, thinking/reasoning parameters, and automatically enables `Needs Local Routing`. You can adjust the default model or model display names if needed; the protocol conversion is handled by the routing layer.
|
||||
|
||||
## Step 2: Enable local routing and route Codex
|
||||
|
||||
Go to the `Routing` page in Settings, expand `Local Routing`, and complete two toggles:
|
||||
|
||||
1. Turn on the main routing switch to start the local service. The default address is `127.0.0.1:15721`.
|
||||
2. Turn on `Codex` under `Routing Enabled`. If you only want Codex to use local routing, you can leave Claude and Gemini off.
|
||||
|
||||
|
||||
|
||||
After routing is enabled, CC Switch points Codex's live configuration to the local route and manages authentication with a placeholder. The real DeepSeek key stays in the CC Switch provider configuration and is injected by the local route while forwarding requests, so you do not need to expose the key in Codex's live configuration.
|
||||
|
||||
## Step 3: Switch providers and restart Codex
|
||||
|
||||
Return to the Codex provider list and click `Enable` on the DeepSeek provider. If you see the `Needs Routing` marker, that provider must be used while routing is running; when the route is not started, CC Switch shows a prompt saying the routing service is required.
|
||||
|
||||
After switching, restart the current Codex terminal session. This is recommended because:
|
||||
|
||||
- The Codex process may already have read the old `config.toml`.
|
||||
- After `model_catalog_json` is generated, the `/model` menu usually needs a fresh process before it refreshes.
|
||||
|
||||
Inside Codex, use `/model` to check whether the current model comes from the DeepSeek preset, such as `DeepSeek V4 Flash`. The Codex app currently does not support multi-model selection, so it defaults to the first configured model. Then send a small test prompt and confirm that the request count increases in the routing panel, or that a Codex request appears in usage/request logs.
|
||||
|
||||
## How to handle other Chat providers
|
||||
|
||||
DeepSeek, Kimi, MiniMax, SiliconFlow, and other common Chat-format providers already have presets in CC Switch, so use presets first. Only choose custom configuration for providers that are not covered by presets; in that case, fill in the API key, base URL, and models according to the provider's documentation, and set `API Format` to `OpenAI Chat Completions (requires routing)`.
|
||||
|
||||
If the upstream provider directly supports the OpenAI Responses API, you do not need to enable `Needs Local Routing`; CC Switch can connect through Responses directly without Chat conversion.
|
||||
|
||||
## FAQ
|
||||
|
||||
**Codex reports 404 or cannot find `/responses`**
|
||||
|
||||
Usually Codex routing is not enabled, or the upstream Chat base URL was written directly into Codex manually. Check whether `~/.codex/config.toml` points to `http://127.0.0.1:15721/v1`.
|
||||
|
||||
**DeepSeek upstream reports 404**
|
||||
|
||||
If you are using the built-in DeepSeek preset, first confirm that the active provider really comes from the preset and that Codex routing is enabled. Only custom providers require extra base URL checks: the base URL should be the service root, not the full endpoint path with `/chat/completions`.
|
||||
|
||||
**`/model` does not show DeepSeek models**
|
||||
|
||||
Restart Codex after saving the provider. CC Switch generates `cc-switch-model-catalog.json` and writes its path to `model_catalog_json`, but a running Codex process may not hot-load the model catalog.
|
||||
The Codex app currently does not support multi-model selection, so it uses the first configured model by default.
|
||||
|
||||
**Routing is enabled, but requests still go to the wrong provider**
|
||||
|
||||
Confirm that all three states match: the current provider under the Codex tab is DeepSeek; the local routing service is running; and the Codex toggle is enabled under `Routing Enabled`.
|
||||
|
||||
**Can I use an official OpenAI Codex account through local routing?**
|
||||
|
||||
Not recommended. CC Switch blocks switching to official providers while local routing takeover is enabled, because accessing official APIs through a proxy may create account risk. Routing is mainly intended for third-party, aggregator, or protocol-conversion scenarios.
|
||||
|
||||
## References
|
||||
|
||||
- [CC Switch User Manual: Add Provider](../user-manual/en/2-providers/2.1-add.md)
|
||||
- [CC Switch User Manual: Proxy Service](../user-manual/en/4-proxy/4.1-service.md)
|
||||
- [CC Switch User Manual: App Routing](../user-manual/en/4-proxy/4.2-routing.md)
|
||||
- [DeepSeek API Docs: Your First API Call](https://api-docs.deepseek.com/)
|
||||
- [DeepSeek API Docs: Create Chat Completion](https://api-docs.deepseek.com/api/create-chat-completion)
|
||||
- [DeepSeek API Docs: Multi-round Conversation](https://api-docs.deepseek.com/guides/multi_round_chat)
|
||||
@@ -0,0 +1,101 @@
|
||||
# Codex で DeepSeek などの Chat 形式 API を使う: CC Switch ローカルルーティングガイド
|
||||
|
||||
> 対象バージョン: CC Switch 3.16.0 およびその前後のバージョン。本記事はリポジトリ内のドキュメントとコードをもとに整理し、OpenAI Chat Completions 互換 API の例として DeepSeek を使用します。スクリーンショットは現在のフロントエンド UI から、実際の API Key やアカウント残高が漏れないよう匿名化したサンプルデータで生成しています。
|
||||
|
||||
## ローカルルーティングが必要な理由
|
||||
|
||||
新しい Codex CLI は OpenAI Responses API を前提にしています。一方で DeepSeek、Kimi、MiniMax、SiliconFlow など多くのプロバイダーが実際に公開しているのは OpenAI Chat Completions 形式、つまり `/chat/completions` です。この 2 つのプロトコルは、リクエストボディ、ストリーミングイベント、レスポンス構造が異なります。Chat エンドポイントをそのまま Codex 設定に入れると、モデル一覧が合わない、リクエストが 404/400 になる、ストリーミングレスポンスを Codex が正しく解析できない、といった問題が起きがちです。
|
||||
|
||||
CC Switch では、Codex が常にローカルルートへ接続し、Responses API のままリクエストを送るようにします。ルート内部で現在のプロバイダーが Chat 形式かどうかを判定し、必要ならリクエストを Chat Completions に書き換えて上流へ送り、最後に Chat レスポンスを Codex が理解できる Responses 形式へ戻します。
|
||||
|
||||
|
||||
|
||||
この経路は主に 4 つのステップに分かれます：
|
||||
|
||||
1. Codex ルーティングを有効にすると、ローカル設定は `http://127.0.0.1:15721/v1` に書き換えられ、`wire_api = "responses"` は維持されます。
|
||||
2. Provider の `meta.apiFormat = "openai_chat"` が、実際の上流は Chat Completions だとルートに伝えます。
|
||||
3. ルートは `/responses` または `/v1/responses` を `/chat/completions` に書き換え、Responses のリクエストボディを Chat のリクエストボディへ変換します。
|
||||
4. 上流から返ってきた後、ルートは Chat の JSON または SSE ストリームを Responses JSON/SSE へ変換して返します。
|
||||
|
||||
## 事前準備
|
||||
|
||||
先に次の 3 つを用意してください：
|
||||
|
||||
- インストール済みで起動できる CC Switch。
|
||||
- インストール済みの Codex CLI。少なくとも 1 回は実行し、`~/.codex/config.toml` のディレクトリ構造が存在していること。
|
||||
- DeepSeek または同種の Chat Completions プロバイダーの API Key。
|
||||
|
||||
DeepSeek 公式ドキュメントでは、OpenAI 互換 base URL は現在 `https://api.deepseek.com`（他のプロバイダーでは `/v1` 付きの base URL もよくあります）、Chat API のパスは `/chat/completions` と記載されています。CC Switch の DeepSeek プリセットにはこれらの情報がすでに入っているため、まずはプリセットを使い、エンドポイントパスを手で組み立てる必要はありません。
|
||||
|
||||
## Step 1: Codex プロバイダーを追加する
|
||||
|
||||
CC Switch を開き、上部の `Codex` タブへ切り替え、右上のプラスボタンからプロバイダーを追加します。
|
||||
|
||||
内蔵プリセットの `DeepSeek` を選びます。必要なのは次の 2 つだけです：
|
||||
|
||||
- DeepSeek API Key を入力する。
|
||||
- プロバイダーを保存する。
|
||||
|
||||
|
||||
|
||||
プリセットには DeepSeek のリクエスト先、デフォルトモデル、モデルメニュー、thinking/reasoning パラメータがすでに含まれており、`ローカルルーティングが必要` も自動的に有効になります。必要に応じてデフォルトモデルやモデル表示名を調整できますが、プロトコル変換はルーティング層に任せれば十分です。
|
||||
|
||||
## Step 2: ローカルルーティングを有効にして Codex をルーティングする
|
||||
|
||||
設定の `ルーティング` ページに入り、`ローカルルーティング` を展開して、次の 2 つのスイッチを設定します：
|
||||
|
||||
1. `ルーティング総スイッチ` をオンにしてローカルサービスを起動します。デフォルトアドレスは `127.0.0.1:15721` です。
|
||||
2. `ルーティング有効` で `Codex` をオンにします。Codex だけをルーティングしたい場合は、Claude と Gemini はオフのままで構いません。
|
||||
|
||||
|
||||
|
||||
ルーティングを有効にすると、CC Switch は Codex の live 設定をローカルルートへ向け、認証はプレースホルダーで管理します。実際の DeepSeek Key は CC Switch の Provider 設定内に残り、ローカルルートが転送時に注入します。そのため、Codex の live 設定に Key を露出させる必要はありません。
|
||||
|
||||
## Step 3: プロバイダーを切り替えて Codex を再起動する
|
||||
|
||||
Codex プロバイダー一覧に戻り、DeepSeek プロバイダーの `有効化` をクリックします。`ルーティングが必要` の表示が見える場合、そのプロバイダーはルーティング実行中に使う必要があります。ルーティングが起動していない場合、CC Switch は「ルーティングサービスが必要」という趣旨のメッセージを表示します。
|
||||
|
||||
切り替え後は、現在の Codex ターミナルセッションを再起動することをおすすめします。理由は次のとおりです：
|
||||
|
||||
- Codex プロセスがすでに古い `config.toml` を読み込んでいる可能性があります。
|
||||
- `model_catalog_json` の生成後、`/model` メニューの更新には通常、新しいプロセスが必要です。
|
||||
|
||||
Codex に入ったら、`/model` で現在のモデルが DeepSeek プリセット由来かどうかを確認します。たとえば `DeepSeek V4 Flash` などです。現在の Codex app は複数モデル選択に対応していないため、設定内の最初のモデルをデフォルトで使用します。その後、小さな質問を 1 つ送って、ルーティングパネルのリクエスト数が増えるか、usage / リクエストログに Codex リクエストが出るかを確認します。
|
||||
|
||||
## 他の Chat プロバイダーの場合
|
||||
|
||||
DeepSeek、Kimi、MiniMax、SiliconFlow など一般的な Chat 形式プロバイダーは CC Switch にプリセットがあるため、まずはプリセットを使ってください。プリセットにないプロバイダーだけ、カスタム設定を選びます。その場合は相手側のドキュメントに従って API Key、base URL、モデルを入力し、`API 形式` を `OpenAI Chat Completions (ルーティングが必要)` に設定します。
|
||||
|
||||
上流が OpenAI Responses API を直接サポートしている場合は、`ローカルルーティングが必要` を有効にする必要はありません。その場合、CC Switch は Responses のまま直結でき、Chat 変換は行いません。
|
||||
|
||||
## よくある質問
|
||||
|
||||
**Codex が 404 を返す、または `/responses` が見つからない**
|
||||
|
||||
多くの場合、Codex ルーティングが有効になっていないか、上流 Chat base URL を手動で Codex に直接書いています。`~/.codex/config.toml` が `http://127.0.0.1:15721/v1` を指しているか確認してください。
|
||||
|
||||
**DeepSeek 上流が 404 を返す**
|
||||
|
||||
内蔵 DeepSeek プリセットを使っている場合は、まず現在のプロバイダーが本当にプリセット由来であること、そして Codex ルーティングが有効であることを確認してください。カスタムプロバイダーを使っている場合だけ、base URL を追加で確認します。base URL はサービスのルートであり、`/chat/completions` 付きの完全なエンドポイントパスではありません。
|
||||
|
||||
**`/model` に DeepSeek モデルが表示されない**
|
||||
|
||||
プロバイダーを保存した後、Codex を再起動してください。CC Switch は `cc-switch-model-catalog.json` を生成し、そのパスを `model_catalog_json` に書き込みますが、実行中の Codex プロセスがモデルカタログをホットロードするとは限りません。
|
||||
現在の Codex app は複数モデル選択に対応していないため、設定内の最初のモデルをデフォルトで使用します。
|
||||
|
||||
**ルーティングを有効にしたのに、リクエストが別のプロバイダーへ行く**
|
||||
|
||||
次の 3 つの状態が一致しているか確認してください：Codex タブの現在のプロバイダーが DeepSeek であること、ローカルルーティングサービスが実行中であること、`ルーティング有効` で Codex スイッチがオンであること。
|
||||
|
||||
**公式 OpenAI Codex アカウントをローカルルーティング経由で使えますか**
|
||||
|
||||
おすすめしません。CC Switch はローカルルーティング有効中、公式プロバイダーへの切り替えをブロックします。プロキシ経由で公式 API にアクセスすると、アカウントリスクが発生する可能性があるためです。ルーティングは主にサードパーティ、集約サービス、またはプロトコル変換のための機能です。
|
||||
|
||||
## 参考リンク
|
||||
|
||||
- [CC Switch ユーザーマニュアル: プロバイダーの追加](../user-manual/ja/2-providers/2.1-add.md)
|
||||
- [CC Switch ユーザーマニュアル: プロキシサービス](../user-manual/ja/4-proxy/4.1-service.md)
|
||||
- [CC Switch ユーザーマニュアル: アプリケーションルーティング](../user-manual/ja/4-proxy/4.2-routing.md)
|
||||
- [DeepSeek API Docs: Your First API Call](https://api-docs.deepseek.com/)
|
||||
- [DeepSeek API Docs: Create Chat Completion](https://api-docs.deepseek.com/api/create-chat-completion)
|
||||
- [DeepSeek API Docs: Multi-round Conversation](https://api-docs.deepseek.com/guides/multi_round_chat)
|
||||
@@ -0,0 +1,101 @@
|
||||
# 在 Codex 中用 DeepSeek 这类 Chat 格式 API：CC Switch 本地路由攻略
|
||||
|
||||
> 适用版本：CC Switch 3.16.0 及附近版本。本文根据仓库内文档与代码整理，并用 DeepSeek 作为 OpenAI Chat Completions 兼容接口的示例。截图来自当前前端界面，使用去敏示例数据生成，避免泄露真实 API Key 或账户余额。
|
||||
|
||||
## 为什么需要本地路由
|
||||
|
||||
新版 Codex CLI 面向的是 OpenAI Responses API，而 DeepSeek、Kimi、MiniMax、SiliconFlow 等很多供应商实际暴露的是 OpenAI Chat Completions 形态，也就是 `/chat/completions`。这两种协议的请求体、流式事件和返回结构不同，直接把 Chat 接口填进 Codex 配置里，常见结果就是模型列表不对、请求 404/400，或者流式响应无法被 Codex 正确解析。
|
||||
|
||||
CC Switch 的做法是让 Codex 始终连本机路由，仍以 Responses API 发送请求；路由在内部识别当前供应商是否是 Chat 格式，再把请求改写成 Chat Completions 发给上游，最后把 Chat 响应转换回 Responses 形态返回给 Codex。
|
||||
|
||||
|
||||
|
||||
这条链路主要分成四步：
|
||||
|
||||
1. Codex 接管时，本地配置会被写成 `http://127.0.0.1:15721/v1`，并强制保持 `wire_api = "responses"`。
|
||||
2. Provider 的 `meta.apiFormat = "openai_chat"` 会告诉路由：真实上游是 Chat Completions。
|
||||
3. 路由把 `/responses` 或 `/v1/responses` 改写到 `/chat/completions`，并把 Responses 请求体转换成 Chat 请求体。
|
||||
4. 上游返回后，路由再把 Chat 的 JSON 或 SSE 转回 Codex 能理解的 Responses JSON/SSE。
|
||||
|
||||
## 准备工作
|
||||
|
||||
你需要先准备好三样东西：
|
||||
|
||||
- 已安装并能启动的 CC Switch。
|
||||
- 已安装 Codex CLI，并至少运行过一次，让 `~/.codex/config.toml` 目录结构存在。
|
||||
- DeepSeek 或同类 Chat Completions 供应商的 API Key。
|
||||
|
||||
DeepSeek 官方文档目前写明 OpenAI 兼容 base URL 是 `https://api.deepseek.com`（其他供应商常见的是带 `/v1` 后缀的 base URL），Chat API 路径是 `/chat/completions`；CC Switch 的 DeepSeek 预设已经按这些信息配好，请优先使用预设，不需要手动拼接口路径。
|
||||
|
||||
## 第一步：添加 Codex 供应商
|
||||
|
||||
打开 CC Switch，切到顶部的 `Codex` 标签，点击右上角的加号添加供应商。
|
||||
|
||||
选择内置预设里的 `DeepSeek`，只需要做两件事：
|
||||
|
||||
- 填入 DeepSeek API Key。
|
||||
- 保存供应商。
|
||||
|
||||
|
||||
|
||||
预设已经内置 DeepSeek 的请求地址、默认模型、模型菜单、thinking/reasoning 参数，并会自动打开 `需要本地路由映射`。你可以按需调整默认模型或模型显示名；协议转换交给路由层完成即可。
|
||||
|
||||
## 第二步：开启本地路由并接管 Codex
|
||||
|
||||
进入设置里的 `路由` 页面，展开 `本地路由`，完成两个开关：
|
||||
|
||||
1. 打开 `路由总开关`，启动本地服务。默认地址是 `127.0.0.1:15721`。
|
||||
2. 在 `路由启用` 中打开 `Codex`。如果只想让 Codex 走路由，可以保持 Claude、Gemini 关闭。
|
||||
|
||||
|
||||
|
||||
接管后，CC Switch 会把 Codex 的 live 配置指向本机路由，并用占位符管理认证。真实 DeepSeek Key 仍保存在 CC Switch 的 Provider 配置里，由本地路由在转发时注入，不需要你把 Key 暴露给 Codex live 配置。
|
||||
|
||||
## 第三步：切换供应商并重启 Codex
|
||||
|
||||
回到 Codex 供应商列表，点击 DeepSeek 供应商的 `启用`。如果看到 `需要路由` 标记，说明这个供应商必须在路由运行时使用；没有启动路由时，CC Switch 会弹出“需要路由服务才能正常使用”的提示。
|
||||
|
||||
切换后建议重启当前 Codex 终端会话。原因是：
|
||||
|
||||
- Codex 进程可能已经读取过旧的 `config.toml`。
|
||||
- `model_catalog_json` 生成后，`/model` 菜单通常需要新进程才能刷新。
|
||||
|
||||
进入 Codex 后，可以用 `/model` 查看当前模型是否来自 DeepSeek 预设，例如 `DeepSeek V4 Flash`。目前 Codex app 不支持多模型选择时，会默认使用配置里的第一个模型。随后发一个小问题，确认路由面板的请求数增长，或者在用量/请求日志里看到 Codex 请求即可。
|
||||
|
||||
## 其它 Chat 供应商怎么处理
|
||||
|
||||
DeepSeek、Kimi、MiniMax、SiliconFlow 等常见 Chat 格式供应商在 CC Switch 里已有预设，优先用预设即可。只有预设里没有的供应商，才需要选择自定义配置；这时按对方文档填 API Key、base URL 和模型，并把 `API 格式` 选为 `OpenAI Chat Completions (需开启路由)`。
|
||||
|
||||
如果上游直接支持 OpenAI Responses API，就不需要打开 `需要本地路由映射`；这时 CC Switch 可以按 Responses 直连，不做 Chat 转换。
|
||||
|
||||
## 常见问题
|
||||
|
||||
**Codex 报 404 或找不到 `/responses`**
|
||||
|
||||
通常是没有开启 Codex 接管，或者你手动把上游 Chat base URL 直接写给了 Codex。检查 `~/.codex/config.toml` 是否指向 `http://127.0.0.1:15721/v1`。
|
||||
|
||||
**DeepSeek 上游报 404**
|
||||
|
||||
如果用的是内置 DeepSeek 预设，先确认当前供应商确实来自预设，并且 Codex 路由已启用。只有在使用自定义供应商时，才需要额外检查 base URL：它应该是服务根地址，而不是带 `/chat/completions` 的完整接口路径。
|
||||
|
||||
**`/model` 看不到 DeepSeek 模型**
|
||||
|
||||
保存供应商后重启 Codex。CC Switch 会生成 `cc-switch-model-catalog.json` 并把路径写入 `model_catalog_json`，但正在运行的 Codex 进程不一定会热加载模型目录。
|
||||
目前 Codex app 不支持多模型选择，默认使用配置的第一个模型。
|
||||
|
||||
**开了路由但请求仍走错供应商**
|
||||
|
||||
确认三处状态一致：Codex 标签下当前供应商是 DeepSeek；本地路由服务正在运行；`路由启用` 里 Codex 开关已打开。
|
||||
|
||||
**可以用官方 OpenAI Codex 账号走本地路由吗**
|
||||
|
||||
不建议。CC Switch 会在本地路由接管模式下阻止切到官方供应商，因为用代理访问官方 API 可能带来账号风险。路由主要用于第三方、聚合或协议转换场景。
|
||||
|
||||
## 参考链接
|
||||
|
||||
- [CC Switch 用户手册：添加供应商](../user-manual/zh/2-providers/2.1-add.md)
|
||||
- [CC Switch 用户手册：代理服务](../user-manual/zh/4-proxy/4.1-service.md)
|
||||
- [CC Switch 用户手册：应用路由](../user-manual/zh/4-proxy/4.2-routing.md)
|
||||
- [DeepSeek API 文档：Your First API Call](https://api-docs.deepseek.com/)
|
||||
- [DeepSeek API 文档：Create Chat Completion](https://api-docs.deepseek.com/api/create-chat-completion)
|
||||
- [DeepSeek API 文档：Multi-round Conversation](https://api-docs.deepseek.com/guides/multi_round_chat)
|
||||
@@ -0,0 +1,46 @@
|
||||
# Can't See Custom Models in the Codex Desktop App? (FAQ)
|
||||
|
||||
> Applies to CC Switch v3.16.1 and later. This article explains "why the Codex desktop app can't see custom models" and the available mitigation; for the detailed step-by-step setup with screenshots, see [Keep Codex Remote Control and Official Plugins While Using Third-Party APIs](./codex-official-auth-preservation-guide-en.md).
|
||||
|
||||
## Symptom
|
||||
|
||||
After you switch Codex to a third-party / custom model in CC Switch (DeepSeek, Kimi, GLM, MiniMax, an aggregator, etc.):
|
||||
|
||||
- The model picker in the **Codex desktop app** doesn't show these custom models — often only the official default model remains, and the reasoning level falls back to the official default;
|
||||
- but everything works fine in the **command-line `codex`** `/model` menu.
|
||||
|
||||
Many users have run into this. Here's why, and what you can do about it.
|
||||
|
||||
## Why this happens
|
||||
|
||||
This is **not a CC Switch local-config problem and not a CC Switch bug** — it is the **Codex desktop app's (the upstream closed-source client's) own model-gating behavior**.
|
||||
|
||||
The Codex desktop app's model picker decides which models to allow based on your **current login identity**: when it can't detect an official ChatGPT / Codex login state, it forces the picker back to the official default model and hides the custom models you configured through `config.toml` (the reasoning level falls back to the official default too). The upstream has marked "exposing custom-provider models in the desktop GUI" as not planned, so CC Switch cannot fully fix this at the desktop-GUI level.
|
||||
|
||||
The command-line `codex` `/model` menu and request routing both recognize the custom providers in `config.toml` correctly — **only the desktop GUI picker is constrained by this gating layer**.
|
||||
|
||||
## Mitigation: keep the official login
|
||||
|
||||
The workaround is to **keep the official login state** so the desktop app's gating allows your custom models through. The key points are below (the full step-by-step setup with screenshots is in the linked guide):
|
||||
|
||||
1. Log in once with an official ChatGPT / Codex account in Codex (a Free subscription is enough) to keep the official login state.
|
||||
2. In CC Switch, enable `Settings -> General -> Codex App Enhancements -> Keep official login when switching third-party providers` (**off by default**).
|
||||
3. Enable local routing and route Codex through it for this third-party provider (required for Chat Completions providers such as DeepSeek / Kimi / MiniMax).
|
||||
4. Fully quit and restart Codex.
|
||||
|
||||
Once enabled, CC Switch preserves the official login state in `~/.codex/auth.json` when switching to a third-party provider and writes the third-party key into `config.toml`, so the desktop app still recognizes the official login identity, the gating lets your models through, and the custom models you configured reappear in the picker. **The preserved official token is never sent to the third party** — third-party model requests still use the key you configured, forwarded through the local route.
|
||||
|
||||
> 📖 Detailed step-by-step setup: [Keep Codex Remote Control and Official Plugins While Using Third-Party APIs](./codex-official-auth-preservation-guide-en.md)
|
||||
|
||||
## Still can't see them?
|
||||
|
||||
- **Confirm the toggle is on**: this toggle is off by default, and many people overwrite the official login state the first time they switch to a third-party provider, which is exactly why the models disappear — enable it as above.
|
||||
- **The official login state expires**: if you haven't used the official login for several days, the picker may go empty again once the token expires — log in to the official account once more to restore it.
|
||||
- **Command-line fallback diagnosis**: run `codex debug models` to list the models actually available on the CLI side and confirm the model itself is configured correctly (the CLI is unaffected by this gating).
|
||||
- Individual Codex desktop versions may behave slightly differently; this is in the upstream client's domain, and no CC Switch version can fully fix it at the desktop-GUI level.
|
||||
|
||||
## References
|
||||
|
||||
- [Keep Codex Remote Control and Official Plugins While Using Third-Party APIs](./codex-official-auth-preservation-guide-en.md)
|
||||
- [Codex DeepSeek local routing hands-on guide](./codex-deepseek-routing-guide-en.md)
|
||||
- [Local Routing](../user-manual/en/4-proxy/4.2-routing.md)
|
||||
@@ -0,0 +1,47 @@
|
||||
# Codex デスクトップアプリでカスタムモデルが見えない？（よくある質問）
|
||||
|
||||
> 対象バージョン: CC Switch v3.16.1 以降。本記事は「なぜ Codex デスクトップアプリでカスタムモデルが見えないのか」と、使える緩和策を解説します。図入りの詳細な設定手順は [サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する](./codex-official-auth-preservation-guide-ja.md) を参照してください。
|
||||
|
||||
## 現象
|
||||
|
||||
CC Switch で Codex をサードパーティ / カスタムモデル（DeepSeek、Kimi、GLM、MiniMax、中継サービスなど）へ切り替えた後：
|
||||
|
||||
- **Codex デスクトップアプリ**のモデルセレクタにこれらのカスタムモデルが表示されず、多くの場合は公式の既定モデルだけが残り、思考レベルも公式の既定へ戻ってしまう。
|
||||
- 一方で**コマンドライン `codex`** の `/model` ではすべて正常に表示される。
|
||||
|
||||
多くのユーザーがこの現象に遭遇しています。以下で原因と対処を解説します。
|
||||
|
||||
## なぜこうなるのか
|
||||
|
||||
これは **CC Switch のローカル設定の問題でも、CC Switch のバグでもありません**。**Codex デスクトップアプリ（上流のクローズドソースクライアント）自身のモデルゲーティング挙動**です。
|
||||
|
||||
Codex デスクトップアプリのモデルセレクタは、あなたの**現在のログイン ID** に応じてどのモデルを通すかを決めます。公式 ChatGPT / Codex のログイン状態を検出できないとき、セレクタを公式の既定モデルへ強制的に戻し、`config.toml` で設定したカスタムモデルを隠します（思考レベルもあわせて公式の既定へ戻ります）。公式は「デスクトップ GUI でカスタムプロバイダーのモデルを公開する」ことを not planned としてマークしているため、CC Switch がデスクトップ GUI のレベルでこれを根本的に修正することはできません。
|
||||
|
||||
コマンドライン `codex` の `/model` とリクエストルーティングは `config.toml` 内のカスタムプロバイダーを正常に認識できます。**デスクトップ GUI のセレクタだけがこのゲーティングの制限を受けます**。
|
||||
|
||||
## 緩和策: 公式ログインを保持する
|
||||
|
||||
対処は**公式ログイン状態を保持する**ことで、デスクトップアプリのゲーティングにあなたのカスタムモデルを通させます。要点は次のとおりです（完全な図入り手順は下のリンク先のガイドを参照してください）：
|
||||
|
||||
1. まず Codex で公式 ChatGPT / Codex に一度ログインし（Free サブスクリプションで構いません）、公式ログイン状態を保持する。
|
||||
2. CC Switch で `設定 → 一般 → Codex アプリ拡張 → サードパーティ切替時に公式ログインを保持` をオンにする（**デフォルトはオフ**）。
|
||||
3. そのサードパーティプロバイダーでローカルルーティングを有効化し、Codex のルーティングをオンにする（DeepSeek / Kimi / MiniMax など Chat Completions プロトコルのプロバイダーでは必須）。
|
||||
4. Codex を完全に終了して再起動する。
|
||||
|
||||
オンにすると、CC Switch はサードパーティプロバイダーへ切り替える際に `~/.codex/auth.json` 内の公式ログイン状態を保持し、サードパーティの Key を `config.toml` へ書き込みます。これにより、デスクトップアプリは引き続き公式ログイン ID を認識してゲーティングを通すため、設定したカスタムモデルがセレクタに再び表示されます。**保持された公式 Token がサードパーティへ送られることはありません**——サードパーティのモデルリクエストは引き続き、設定した Key でローカルルーティング経由で転送されます。
|
||||
|
||||
> 📖 詳細な図入り手順: [サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する](./codex-official-auth-preservation-guide-ja.md)
|
||||
|
||||
## それでも見えない場合は
|
||||
|
||||
- **スイッチがオンか確認する**: このスイッチはデフォルトでオフです。多くの人は初めてサードパーティへ切り替えたときに公式ログイン状態を上書きしてしまい、その結果見えなくなっています——上記の手順でオンにしてください。
|
||||
- **公式ログイン状態は期限切れになる**: 数日間公式ログインを使わないと、Token が失効した後にセレクタが再び空になることがあります——公式に一度ログインし直せば回復します。
|
||||
- **コマンドラインでの確認**: `codex debug models` を使うと CLI 側で実際に利用可能なモデルを一覧でき、モデル自体が正しく設定されていることを確認できます（CLI はこのゲーティングの影響を受けません）。
|
||||
- 個々の Codex デスクトップ版で挙動が多少異なる場合があります。これは上流クライアントの範疇であり、CC Switch のどのバージョンでもデスクトップ GUI のレベルで根本解決することはできません。
|
||||
|
||||
## 参考リンク
|
||||
|
||||
- [サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する](./codex-official-auth-preservation-guide-ja.md)
|
||||
- [Codex DeepSeek ローカルルーティング実践ガイド](./codex-deepseek-routing-guide-ja.md)
|
||||
- [ローカルルーティング](../user-manual/ja/4-proxy/4.2-routing.md)
|
||||
</content>
|
||||
@@ -0,0 +1,46 @@
|
||||
# Codex 桌面应用里看不到自定义模型？（常见问题）
|
||||
|
||||
> 适用版本：CC Switch v3.16.1 及以上。本文解释「为什么 Codex 桌面应用看不到自定义模型」以及可用的缓解办法；详细的图文配置步骤见 [使用第三方 API 时保留 Codex 远程操作和官方插件](./codex-official-auth-preservation-guide-zh.md)。
|
||||
|
||||
## 现象
|
||||
|
||||
在 CC Switch 里把 Codex 切换到第三方 / 自定义模型（DeepSeek、Kimi、GLM、MiniMax、中转站等）后：
|
||||
|
||||
- **Codex 桌面应用**的模型选择器里看不到这些自定义模型，往往只剩官方默认模型，思考等级也回落到官方默认；
|
||||
- 但**命令行 `codex`** 的 `/model` 里一切正常。
|
||||
|
||||
很多用户都遇到过这个现象，下面解释原因与办法。
|
||||
|
||||
## 为什么会这样
|
||||
|
||||
这**不是 CC Switch 的本地配置问题，也不是 CC Switch 的 bug**，而是 **Codex 桌面应用（上游闭源客户端）自身的模型门控行为**。
|
||||
|
||||
Codex 桌面应用的模型选择器会按你**当前的登录身份**来决定放行哪些模型：当它检测不到官方 ChatGPT / Codex 登录态时，会把选择器强制回落到官方默认模型，把你通过 `config.toml` 配置的自定义模型藏起来（思考等级也会一并回落到官方默认）。官方已把「在桌面 GUI 里暴露自定义供应商模型」标记为 not planned，因此 CC Switch 无法从桌面 GUI 层面彻底修复它。
|
||||
|
||||
命令行 `codex` 的 `/model` 与请求路由都能正常识别 `config.toml` 里的自定义供应商，**唯独桌面 GUI 的选择器受这层门控限制**。
|
||||
|
||||
## 怎么缓解：保留官方登录
|
||||
|
||||
办法是**保留官方登录态**，让桌面应用的门控放行你的自定义模型。要点如下（完整图文步骤见下方链接的攻略）：
|
||||
|
||||
1. 先在 Codex 里登录一次官方 ChatGPT / Codex（Free 订阅即可），保留官方登录态。
|
||||
2. 在 CC Switch 开启 `设置 → 通用 → Codex 应用增强 → 切换第三方时保留官方登录`（**默认关闭**）。
|
||||
3. 为该第三方供应商开启本地路由并接管 Codex（Chat Completions 协议的供应商如 DeepSeek / Kimi / MiniMax 必须开启）。
|
||||
4. 完全退出并重启 Codex。
|
||||
|
||||
开启后，CC Switch 在切换第三方供应商时会保留 `~/.codex/auth.json` 里的官方登录态、把第三方 Key 写进 `config.toml`，于是桌面应用仍识别官方登录身份、门控放行，你配置的自定义模型就会重新出现在选择器里。**保留的官方 Token 不会被发往第三方**——第三方模型请求仍用你配置的 Key 经本地路由转发。
|
||||
|
||||
> 📖 详细图文步骤：[使用第三方 API 时保留 Codex 远程操作和官方插件](./codex-official-auth-preservation-guide-zh.md)
|
||||
|
||||
## 仍然看不到怎么办
|
||||
|
||||
- **确认开关已开**：该开关默认关闭，很多人第一次切到第三方就把官方登录态覆盖掉了，所以才看不到——按上面开启即可。
|
||||
- **官方登录态会过期**：如果连续几天没用过官方登录，Token 失效后选择器可能又变空——重新登录一次官方即可恢复。
|
||||
- **命令行兜底诊断**：用 `codex debug models` 可以列出 CLI 端实际可用的模型，确认模型本身已正确配置（CLI 不受此门控影响）。
|
||||
- 个别 Codex 桌面版本的行为可能略有差异；这属于上游客户端范畴，CC Switch 各版本都无法从桌面 GUI 层根治。
|
||||
|
||||
## 参考链接
|
||||
|
||||
- [使用第三方 API 时保留 Codex 远程操作和官方插件](./codex-official-auth-preservation-guide-zh.md)
|
||||
- [Codex DeepSeek 本地路由实战攻略](./codex-deepseek-routing-guide-zh.md)
|
||||
- [本地路由](../user-manual/zh/4-proxy/4.2-routing.md)
|
||||
@@ -0,0 +1,112 @@
|
||||
# Using Kimi in Codex: CC Switch Local Routing Guide
|
||||
|
||||
> Applies to CC Switch 3.16.5 and nearby versions. This guide is based on the repository documentation and code, and uses Kimi as an example of an OpenAI Chat Completions-compatible API. Screenshots are generated from the current frontend UI with de-identified sample data to avoid exposing a real API key or account balance.
|
||||
|
||||
## Why local routing is needed
|
||||
|
||||
The newer Codex CLI targets the OpenAI Responses API, while both the Kimi Open Platform and Kimi For Coding expose the OpenAI Chat Completions shape, `/chat/completions`. These two protocols use different request bodies, streaming events, and response structures. If you put a Kimi endpoint directly into Codex configuration, the usual result is a 404 on `/responses`, or streaming responses that Codex cannot parse correctly.
|
||||
|
||||
The third-party tools officially supported by Kimi For Coding are Anthropic-compatible coding agents such as Claude Code and Roo Code — Codex is not on the list. To use Kimi inside Codex, you need a protocol conversion layer, and that is exactly what CC Switch Local Routing does.
|
||||
|
||||
CC Switch solves this by making Codex always talk to a local route and continue sending Responses API requests. The route detects whether the active provider is Chat-format, rewrites the request into Chat Completions for the upstream provider, and finally converts the Chat response back into the Responses shape that Codex understands.
|
||||
|
||||
|
||||
|
||||
The chain has four main steps:
|
||||
|
||||
1. When Codex routing is enabled, the local configuration is written as `http://127.0.0.1:15721/v1`, while `wire_api = "responses"` is kept in place.
|
||||
2. The provider's `meta.apiFormat = "openai_chat"` tells the route that the real upstream is Chat Completions.
|
||||
3. The route rewrites `/responses` or `/v1/responses` to `/chat/completions`, and converts the Responses request body into a Chat request body.
|
||||
4. After the upstream responds, the route converts the Chat JSON or SSE stream back into Responses JSON/SSE.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Prepare these three things first:
|
||||
|
||||
- CC Switch installed and able to start.
|
||||
- Codex CLI installed and run at least once, so the `~/.codex/config.toml` directory structure exists.
|
||||
- A Kimi API key.
|
||||
|
||||
Kimi API keys come from two different places, matching two different built-in presets in CC Switch:
|
||||
|
||||
- **Kimi Open Platform** (platform.kimi.com): pay-as-you-go API keys billed by token usage, matching the `Kimi` preset. The OpenAI-compatible base URL is `https://api.moonshot.cn/v1` and the default model is `kimi-k2.7-code`.
|
||||
- **Kimi For Coding** (kimi.com/code): a dedicated key generated from the Kimi Code membership benefits, matching the `Kimi For Coding` preset. The base URL is `https://api.kimi.com/coding/v1` and the unified model is `kimi-for-coding`.
|
||||
|
||||
Both presets already contain the correct endpoint and model details, so prefer the presets and do not manually assemble the endpoint path.
|
||||
|
||||
## Step 1: Add a Codex provider
|
||||
|
||||
Open CC Switch, switch to the top-level `Codex` tab, and click the plus button in the upper-right corner to add a provider.
|
||||
|
||||
Depending on which kind of key you have, choose the built-in `Kimi` preset (Open Platform, pay-as-you-go) or `Kimi For Coding` preset (membership subscription). You only need to do two things:
|
||||
|
||||
- Enter the matching Kimi API key.
|
||||
- Save the provider.
|
||||
|
||||
|
||||
|
||||
The preset already includes Kimi's request base URL, default model, model menu, thinking/reasoning parameters, and presets `Upstream Format` under `Advanced Options` to `Chat Completions (routing required)`. You can adjust the default model or model display names if needed — for example, the Open Platform preset defaults to `kimi-k2.7-code`, and you can switch to `kimi-k2.7-code-highspeed` following the official documentation. The protocol conversion is handled by the routing layer.
|
||||
|
||||
## Step 2: Enable local routing and route Codex
|
||||
|
||||
Go to the `Routing` page in Settings, expand `Local Routing`, and complete two toggles:
|
||||
|
||||
1. Turn on the main routing switch to start the local service. The default address is `127.0.0.1:15721`.
|
||||
2. Turn on `Codex` under `Routing Enabled`. If you only want Codex to use local routing, you can leave Claude and Gemini off.
|
||||
|
||||
|
||||
|
||||
After routing is enabled, CC Switch points Codex's live configuration to the local route and manages authentication with a placeholder. The real Kimi key stays in the CC Switch provider configuration and is injected by the local route while forwarding requests, so you do not need to expose the key in Codex's live configuration.
|
||||
|
||||
## Step 3: Switch providers and restart Codex
|
||||
|
||||
Return to the Codex provider list and click `Enable` on the Kimi provider. If you see the `Needs Routing` marker, that provider must be used while routing is running; when the route is not started, CC Switch shows a prompt saying the routing service is required.
|
||||
|
||||
After switching, restart the current Codex terminal session. This is recommended because:
|
||||
|
||||
- The Codex process may already have read the old `config.toml`.
|
||||
- After `model_catalog_json` is generated, the `/model` menu usually needs a fresh process before it refreshes.
|
||||
|
||||
Inside Codex, use `/model` to check whether the current model comes from the Kimi preset, such as `Kimi K2.7 Code` or `Kimi For Coding`. The Codex app currently does not support multi-model selection, so it defaults to the first configured model. Then send a small test prompt and confirm that the request count increases in the routing panel, or that a Codex request appears in usage/request logs.
|
||||
|
||||
## How to handle other Chat providers
|
||||
|
||||
Kimi, DeepSeek, MiniMax, SiliconFlow, and other common Chat-format providers already have presets in CC Switch, so use presets first. Only choose custom configuration for providers that are not covered by presets; in that case, fill in the API key, base URL, and models according to the provider's documentation, and set `Upstream Format` under `Advanced Options` to `Chat Completions (routing required)`.
|
||||
|
||||
If the upstream provider directly supports the OpenAI Responses API, set `Upstream Format` to `Responses`; CC Switch then connects through Responses directly without Chat conversion.
|
||||
|
||||
## FAQ
|
||||
|
||||
**Codex reports 404 or cannot find `/responses`**
|
||||
|
||||
Usually Codex routing is not enabled, or the Kimi Chat base URL was written directly into Codex manually — the Kimi upstream has no `/responses` endpoint, so that always 404s. Check whether `~/.codex/config.toml` points to `http://127.0.0.1:15721/v1`.
|
||||
|
||||
**Kimi upstream reports 401 or 403**
|
||||
|
||||
First confirm the key matches the preset: Open Platform keys only work with the `Kimi` preset, and Kimi Code membership keys only work with the `Kimi For Coding` preset. The two key families are not interchangeable.
|
||||
|
||||
**Kimi upstream reports 404**
|
||||
|
||||
If you are using a built-in Kimi preset, first confirm that the active provider really comes from the preset and that Codex routing is enabled. Only custom providers require extra base URL checks: the base URL should be the service root, not the full endpoint path with `/chat/completions`.
|
||||
|
||||
**`/model` does not show Kimi models**
|
||||
|
||||
Restart Codex after saving the provider. CC Switch generates `cc-switch-model-catalog.json` and writes its path to `model_catalog_json`, but a running Codex process may not hot-load the model catalog.
|
||||
The Codex app currently does not support multi-model selection, so it uses the first configured model by default.
|
||||
|
||||
**Routing is enabled, but requests still go to the wrong provider**
|
||||
|
||||
Confirm that all three states match: the current provider under the Codex tab is Kimi; the local routing service is running; and the Codex toggle is enabled under `Routing Enabled`.
|
||||
|
||||
**Can I use an official OpenAI Codex account through local routing?**
|
||||
|
||||
Not recommended. CC Switch blocks switching to official providers while local routing takeover is enabled, because accessing official APIs through a proxy may create account risk. Routing is mainly intended for third-party, aggregator, or protocol-conversion scenarios.
|
||||
|
||||
## References
|
||||
|
||||
- [CC Switch User Manual: Add Provider](../user-manual/en/2-providers/2.1-add.md)
|
||||
- [CC Switch User Manual: Proxy Service](../user-manual/en/4-proxy/4.1-service.md)
|
||||
- [CC Switch User Manual: App Routing](../user-manual/en/4-proxy/4.2-routing.md)
|
||||
- [Kimi Open Platform: Using Kimi K2.7 Code in coding tools](https://platform.kimi.com/docs/guide/agent-support)
|
||||
- [Kimi Code Docs: Overview](https://www.kimi.com/code/docs/)
|
||||
- [Kimi Code Docs: Using with third-party coding agents](https://www.kimi.com/code/docs/third-party-tools/other-coding-agents.html)
|
||||
@@ -0,0 +1,112 @@
|
||||
# Codex で Kimi を使う: CC Switch ローカルルーティングガイド
|
||||
|
||||
> 対象バージョン: CC Switch 3.16.5 およびその前後のバージョン。本記事はリポジトリ内のドキュメントとコードをもとに整理し、OpenAI Chat Completions 互換 API の例として Kimi を使用します。スクリーンショットは現在のフロントエンド UI から、実際の API Key やアカウント残高が漏れないよう匿名化したサンプルデータで生成しています。
|
||||
|
||||
## ローカルルーティングが必要な理由
|
||||
|
||||
新しい Codex CLI は OpenAI Responses API を前提にしています。一方で Kimi オープンプラットフォームと Kimi For Coding が実際に公開しているのは、いずれも OpenAI Chat Completions 形式、つまり `/chat/completions` です。この 2 つのプロトコルは、リクエストボディ、ストリーミングイベント、レスポンス構造が異なります。Kimi のエンドポイントをそのまま Codex 設定に入れると、`/responses` へのリクエストが 404 になる、ストリーミングレスポンスを Codex が正しく解析できない、といった問題が起きがちです。
|
||||
|
||||
Kimi For Coding が公式にサポートするサードパーティツールは、Claude Code や Roo Code など Anthropic 互換のコーディング Agent であり、Codex はリストに含まれていません。Codex で Kimi を使うにはプロトコル変換レイヤーが必要で、それこそが CC Switch のローカルルーティングの役割です。
|
||||
|
||||
CC Switch では、Codex が常にローカルルートへ接続し、Responses API のままリクエストを送るようにします。ルート内部で現在のプロバイダーが Chat 形式かどうかを判定し、必要ならリクエストを Chat Completions に書き換えて上流へ送り、最後に Chat レスポンスを Codex が理解できる Responses 形式へ戻します。
|
||||
|
||||
|
||||
|
||||
この経路は主に 4 つのステップに分かれます：
|
||||
|
||||
1. Codex ルーティングを有効にすると、ローカル設定は `http://127.0.0.1:15721/v1` に書き換えられ、`wire_api = "responses"` は維持されます。
|
||||
2. Provider の `meta.apiFormat = "openai_chat"` が、実際の上流は Chat Completions だとルートに伝えます。
|
||||
3. ルートは `/responses` または `/v1/responses` を `/chat/completions` に書き換え、Responses のリクエストボディを Chat のリクエストボディへ変換します。
|
||||
4. 上流から返ってきた後、ルートは Chat の JSON または SSE ストリームを Responses JSON/SSE へ変換して返します。
|
||||
|
||||
## 事前準備
|
||||
|
||||
先に次の 3 つを用意してください：
|
||||
|
||||
- インストール済みで起動できる CC Switch。
|
||||
- インストール済みの Codex CLI。少なくとも 1 回は実行し、`~/.codex/config.toml` のディレクトリ構造が存在していること。
|
||||
- Kimi の API Key。
|
||||
|
||||
Kimi の API Key には 2 つの取得元があり、CC Switch の 2 つの内蔵プリセットに対応します：
|
||||
|
||||
- **Kimi オープンプラットフォーム**（platform.kimi.com）: トークン使用量に応じた従量課金の API Key。プリセット `Kimi` に対応し、OpenAI 互換 base URL は `https://api.moonshot.cn/v1`、デフォルトモデルは `kimi-k2.7-code` です。
|
||||
- **Kimi For Coding**（kimi.com/code）: Kimi メンバーシップの Kimi Code 特典から生成する専用 Key。プリセット `Kimi For Coding` に対応し、base URL は `https://api.kimi.com/coding/v1`、モデルは `kimi-for-coding` に統一されています。
|
||||
|
||||
どちらのプリセットにも公式情報に基づくエンドポイントとモデルがすでに設定されているため、まずはプリセットを使い、エンドポイントパスを手で組み立てる必要はありません。
|
||||
|
||||
## Step 1: Codex プロバイダーを追加する
|
||||
|
||||
CC Switch を開き、上部の `Codex` タブへ切り替え、右上のプラスボタンからプロバイダーを追加します。
|
||||
|
||||
手元の Key の種類に応じて、内蔵プリセットの `Kimi`（オープンプラットフォーム・従量課金）または `Kimi For Coding`（メンバーシップ）を選びます。必要なのは次の 2 つだけです：
|
||||
|
||||
- 対応する Kimi API Key を入力する。
|
||||
- プロバイダーを保存する。
|
||||
|
||||
|
||||
|
||||
プリセットには Kimi のリクエスト先、デフォルトモデル、モデルメニュー、thinking/reasoning パラメータがすでに含まれており、`高級オプション` の `上流フォーマット` も `Chat Completions（ルーティング必須）` にプリセットされています。必要に応じてデフォルトモデルやモデル表示名を調整できます。たとえばオープンプラットフォームのプリセットはデフォルトが `kimi-k2.7-code` で、公式ドキュメントに従って `kimi-k2.7-code-highspeed` に変更することもできます。プロトコル変換はルーティング層に任せれば十分です。
|
||||
|
||||
## Step 2: ローカルルーティングを有効にして Codex をルーティングする
|
||||
|
||||
設定の `ルーティング` ページに入り、`ローカルルーティング` を展開して、次の 2 つのスイッチを設定します：
|
||||
|
||||
1. `ルーティング総スイッチ` をオンにしてローカルサービスを起動します。デフォルトアドレスは `127.0.0.1:15721` です。
|
||||
2. `ルーティング有効` で `Codex` をオンにします。Codex だけをルーティングしたい場合は、Claude と Gemini はオフのままで構いません。
|
||||
|
||||
|
||||
|
||||
ルーティングを有効にすると、CC Switch は Codex の live 設定をローカルルートへ向け、認証はプレースホルダーで管理します。実際の Kimi Key は CC Switch の Provider 設定内に残り、ローカルルートが転送時に注入します。そのため、Codex の live 設定に Key を露出させる必要はありません。
|
||||
|
||||
## Step 3: プロバイダーを切り替えて Codex を再起動する
|
||||
|
||||
Codex プロバイダー一覧に戻り、Kimi プロバイダーの `有効化` をクリックします。`ルーティングが必要` の表示が見える場合、そのプロバイダーはルーティング実行中に使う必要があります。ルーティングが起動していない場合、CC Switch は「ルーティングサービスが必要」という趣旨のメッセージを表示します。
|
||||
|
||||
切り替え後は、現在の Codex ターミナルセッションを再起動することをおすすめします。理由は次のとおりです：
|
||||
|
||||
- Codex プロセスがすでに古い `config.toml` を読み込んでいる可能性があります。
|
||||
- `model_catalog_json` の生成後、`/model` メニューの更新には通常、新しいプロセスが必要です。
|
||||
|
||||
Codex に入ったら、`/model` で現在のモデルが Kimi プリセット由来かどうかを確認します。たとえば `Kimi K2.7 Code` や `Kimi For Coding` などです。現在の Codex app は複数モデル選択に対応していないため、設定内の最初のモデルをデフォルトで使用します。その後、小さな質問を 1 つ送って、ルーティングパネルのリクエスト数が増えるか、usage / リクエストログに Codex リクエストが出るかを確認します。
|
||||
|
||||
## 他の Chat プロバイダーの場合
|
||||
|
||||
Kimi、DeepSeek、MiniMax、SiliconFlow など一般的な Chat 形式プロバイダーは CC Switch にプリセットがあるため、まずはプリセットを使ってください。プリセットにないプロバイダーだけ、カスタム設定を選びます。その場合は相手側のドキュメントに従って API Key、base URL、モデルを入力し、`高級オプション` の `上流フォーマット` を `Chat Completions（ルーティング必須）` に設定します。
|
||||
|
||||
上流が OpenAI Responses API を直接サポートしている場合は、`上流フォーマット` を `Responses` にすれば、CC Switch は Responses のまま直結でき、Chat 変換は行いません。
|
||||
|
||||
## よくある質問
|
||||
|
||||
**Codex が 404 を返す、または `/responses` が見つからない**
|
||||
|
||||
多くの場合、Codex ルーティングが有効になっていないか、Kimi の Chat base URL を手動で Codex に直接書いています。Kimi の上流には `/responses` エンドポイントが存在しないため、必ず 404 になります。`~/.codex/config.toml` が `http://127.0.0.1:15721/v1` を指しているか確認してください。
|
||||
|
||||
**Kimi 上流が 401 または 403 を返す**
|
||||
|
||||
まず Key とプリセットの組み合わせを確認してください。オープンプラットフォームの Key はプリセット `Kimi` 専用、Kimi Code 特典の Key はプリセット `Kimi For Coding` 専用で、2 種類の Key は相互に使えません。
|
||||
|
||||
**Kimi 上流が 404 を返す**
|
||||
|
||||
内蔵 Kimi プリセットを使っている場合は、まず現在のプロバイダーが本当にプリセット由来であること、そして Codex ルーティングが有効であることを確認してください。カスタムプロバイダーを使っている場合だけ、base URL を追加で確認します。base URL はサービスのルートであり、`/chat/completions` 付きの完全なエンドポイントパスではありません。
|
||||
|
||||
**`/model` に Kimi モデルが表示されない**
|
||||
|
||||
プロバイダーを保存した後、Codex を再起動してください。CC Switch は `cc-switch-model-catalog.json` を生成し、そのパスを `model_catalog_json` に書き込みますが、実行中の Codex プロセスがモデルカタログをホットロードするとは限りません。
|
||||
現在の Codex app は複数モデル選択に対応していないため、設定内の最初のモデルをデフォルトで使用します。
|
||||
|
||||
**ルーティングを有効にしたのに、リクエストが別のプロバイダーへ行く**
|
||||
|
||||
次の 3 つの状態が一致しているか確認してください：Codex タブの現在のプロバイダーが Kimi であること、ローカルルーティングサービスが実行中であること、`ルーティング有効` で Codex スイッチがオンであること。
|
||||
|
||||
**公式 OpenAI Codex アカウントをローカルルーティング経由で使えますか**
|
||||
|
||||
おすすめしません。CC Switch はローカルルーティング有効中、公式プロバイダーへの切り替えをブロックします。プロキシ経由で公式 API にアクセスすると、アカウントリスクが発生する可能性があるためです。ルーティングは主にサードパーティ、集約サービス、またはプロトコル変換のための機能です。
|
||||
|
||||
## 参考リンク
|
||||
|
||||
- [CC Switch ユーザーマニュアル: プロバイダーの追加](../user-manual/ja/2-providers/2.1-add.md)
|
||||
- [CC Switch ユーザーマニュアル: プロキシサービス](../user-manual/ja/4-proxy/4.1-service.md)
|
||||
- [CC Switch ユーザーマニュアル: アプリケーションルーティング](../user-manual/ja/4-proxy/4.2-routing.md)
|
||||
- [Kimi オープンプラットフォーム: コーディングツールで Kimi K2.7 Code を使う](https://platform.kimi.com/docs/guide/agent-support)
|
||||
- [Kimi Code ドキュメント: 概要](https://www.kimi.com/code/docs/)
|
||||
- [Kimi Code ドキュメント: サードパーティ Coding Agent での利用](https://www.kimi.com/code/docs/third-party-tools/other-coding-agents.html)
|
||||
@@ -0,0 +1,112 @@
|
||||
# 在 Codex 中用 Kimi：CC Switch 本地路由攻略
|
||||
|
||||
> 适用版本：CC Switch 3.16.5 及附近版本。本文根据仓库内文档与代码整理，并用 Kimi 作为 OpenAI Chat Completions 兼容接口的示例。截图来自当前前端界面，使用去敏示例数据生成，避免泄露真实 API Key 或账户余额。
|
||||
|
||||
## 为什么需要本地路由
|
||||
|
||||
新版 Codex CLI 面向的是 OpenAI Responses API，而 Kimi 开放平台和 Kimi For Coding 实际暴露的都是 OpenAI Chat Completions 形态，也就是 `/chat/completions`。这两种协议的请求体、流式事件和返回结构不同，直接把 Kimi 的接口地址填进 Codex 配置里，常见结果就是请求 `/responses` 返回 404，或者流式响应无法被 Codex 正确解析。
|
||||
|
||||
Kimi For Coding 官方目前支持的第三方工具是 Claude Code、Roo Code 这类兼容 Anthropic 协议的编程 Agent，并没有覆盖 Codex。所以想在 Codex 里用 Kimi，需要一层协议转换——这正是 CC Switch 本地路由做的事。
|
||||
|
||||
CC Switch 的做法是让 Codex 始终连本机路由，仍以 Responses API 发送请求；路由在内部识别当前供应商是否是 Chat 格式，再把请求改写成 Chat Completions 发给上游，最后把 Chat 响应转换回 Responses 形态返回给 Codex。
|
||||
|
||||
|
||||
|
||||
这条链路主要分成四步：
|
||||
|
||||
1. Codex 接管时，本地配置会被写成 `http://127.0.0.1:15721/v1`，并强制保持 `wire_api = "responses"`。
|
||||
2. Provider 的 `meta.apiFormat = "openai_chat"` 会告诉路由：真实上游是 Chat Completions。
|
||||
3. 路由把 `/responses` 或 `/v1/responses` 改写到 `/chat/completions`，并把 Responses 请求体转换成 Chat 请求体。
|
||||
4. 上游返回后，路由再把 Chat 的 JSON 或 SSE 转回 Codex 能理解的 Responses JSON/SSE。
|
||||
|
||||
## 准备工作
|
||||
|
||||
你需要先准备好三样东西：
|
||||
|
||||
- 已安装并能启动的 CC Switch。
|
||||
- 已安装 Codex CLI，并至少运行过一次，让 `~/.codex/config.toml` 目录结构存在。
|
||||
- 一个 Kimi API Key。
|
||||
|
||||
Kimi 的 API Key 有两个来源，对应 CC Switch 里两个不同的内置预设：
|
||||
|
||||
- **Kimi 开放平台**（platform.kimi.com）：按 token 用量计费的 API Key，对应预设 `Kimi`，OpenAI 兼容 base URL 是 `https://api.moonshot.cn/v1`，默认模型 `kimi-k2.7-code`。
|
||||
- **Kimi For Coding**（kimi.com/code）：Kimi 会员 Kimi Code 权益生成的专用 Key，对应预设 `Kimi For Coding`，base URL 是 `https://api.kimi.com/coding/v1`，模型统一为 `kimi-for-coding`。
|
||||
|
||||
两个预设都已经按官方信息配好接口地址和模型，请优先使用预设，不需要手动拼接口路径。
|
||||
|
||||
## 第一步：添加 Codex 供应商
|
||||
|
||||
打开 CC Switch，切到顶部的 `Codex` 标签，点击右上角的加号添加供应商。
|
||||
|
||||
按你手里 Key 的类型，在内置预设里选择 `Kimi`（开放平台按量计费）或 `Kimi For Coding`（会员订阅），然后只需要做两件事：
|
||||
|
||||
- 填入对应的 Kimi API Key。
|
||||
- 保存供应商。
|
||||
|
||||
|
||||
|
||||
预设已经内置 Kimi 的请求地址、默认模型、模型菜单、thinking/reasoning 参数，并把 `高级选项` 里的 `上游格式` 预设为 `Chat Completions（需开启路由）`。你可以按需调整默认模型或模型显示名——例如开放平台预设默认是 `kimi-k2.7-code`，也可以按官方文档换成 `kimi-k2.7-code-highspeed`；协议转换交给路由层完成即可。
|
||||
|
||||
## 第二步：开启本地路由并接管 Codex
|
||||
|
||||
进入设置里的 `路由` 页面，展开 `本地路由`，完成两个开关：
|
||||
|
||||
1. 打开 `路由总开关`，启动本地服务。默认地址是 `127.0.0.1:15721`。
|
||||
2. 在 `路由启用` 中打开 `Codex`。如果只想让 Codex 走路由，可以保持 Claude、Gemini 关闭。
|
||||
|
||||
|
||||
|
||||
接管后，CC Switch 会把 Codex 的 live 配置指向本机路由，并用占位符管理认证。真实 Kimi Key 仍保存在 CC Switch 的 Provider 配置里，由本地路由在转发时注入，不需要你把 Key 暴露给 Codex live 配置。
|
||||
|
||||
## 第三步：切换供应商并重启 Codex
|
||||
|
||||
回到 Codex 供应商列表，点击 Kimi 供应商的 `启用`。如果看到 `需要路由` 标记，说明这个供应商必须在路由运行时使用；没有启动路由时，CC Switch 会弹出“需要路由服务才能正常使用”的提示。
|
||||
|
||||
切换后建议重启当前 Codex 终端会话。原因是：
|
||||
|
||||
- Codex 进程可能已经读取过旧的 `config.toml`。
|
||||
- `model_catalog_json` 生成后，`/model` 菜单通常需要新进程才能刷新。
|
||||
|
||||
进入 Codex 后，可以用 `/model` 查看当前模型是否来自 Kimi 预设，例如 `Kimi K2.7 Code` 或 `Kimi For Coding`。目前 Codex app 不支持多模型选择时，会默认使用配置里的第一个模型。随后发一个小问题，确认路由面板的请求数增长，或者在用量/请求日志里看到 Codex 请求即可。
|
||||
|
||||
## 其它 Chat 供应商怎么处理
|
||||
|
||||
Kimi、DeepSeek、MiniMax、SiliconFlow 等常见 Chat 格式供应商在 CC Switch 里已有预设，优先用预设即可。只有预设里没有的供应商，才需要选择自定义配置；这时按对方文档填 API Key、base URL 和模型，并把 `高级选项` 里的 `上游格式` 选为 `Chat Completions（需开启路由）`。
|
||||
|
||||
如果上游直接支持 OpenAI Responses API，把 `上游格式` 选为 `Responses` 即可；这时 CC Switch 按 Responses 直连，不做 Chat 转换。
|
||||
|
||||
## 常见问题
|
||||
|
||||
**Codex 报 404 或找不到 `/responses`**
|
||||
|
||||
通常是没有开启 Codex 接管，或者你手动把 Kimi 的 Chat base URL 直接写给了 Codex——Kimi 上游没有 `/responses` 端点，这样一定会 404。检查 `~/.codex/config.toml` 是否指向 `http://127.0.0.1:15721/v1`。
|
||||
|
||||
**Kimi 上游报 401 或 403**
|
||||
|
||||
先确认 Key 和预设是否匹配：开放平台的 Key 只能配 `Kimi` 预设，Kimi Code 会员权益的 Key 只能配 `Kimi For Coding` 预设，两套 Key 不能混用。
|
||||
|
||||
**Kimi 上游报 404**
|
||||
|
||||
如果用的是内置 Kimi 预设，先确认当前供应商确实来自预设，并且 Codex 路由已启用。只有在使用自定义供应商时，才需要额外检查 base URL：它应该是服务根地址，而不是带 `/chat/completions` 的完整接口路径。
|
||||
|
||||
**`/model` 看不到 Kimi 模型**
|
||||
|
||||
保存供应商后重启 Codex。CC Switch 会生成 `cc-switch-model-catalog.json` 并把路径写入 `model_catalog_json`，但正在运行的 Codex 进程不一定会热加载模型目录。
|
||||
目前 Codex app 不支持多模型选择，默认使用配置的第一个模型。
|
||||
|
||||
**开了路由但请求仍走错供应商**
|
||||
|
||||
确认三处状态一致：Codex 标签下当前供应商是 Kimi；本地路由服务正在运行；`路由启用` 里 Codex 开关已打开。
|
||||
|
||||
**可以用官方 OpenAI Codex 账号走本地路由吗**
|
||||
|
||||
不建议。CC Switch 会在本地路由接管模式下阻止切到官方供应商，因为用代理访问官方 API 可能带来账号风险。路由主要用于第三方、聚合或协议转换场景。
|
||||
|
||||
## 参考链接
|
||||
|
||||
- [CC Switch 用户手册：添加供应商](../user-manual/zh/2-providers/2.1-add.md)
|
||||
- [CC Switch 用户手册：代理服务](../user-manual/zh/4-proxy/4.1-service.md)
|
||||
- [CC Switch 用户手册：应用路由](../user-manual/zh/4-proxy/4.2-routing.md)
|
||||
- [Kimi 开放平台：在编程工具中使用 Kimi K2.7 Code 模型](https://platform.kimi.com/docs/guide/agent-support)
|
||||
- [Kimi Code 文档：概览](https://www.kimi.com/code/docs/)
|
||||
- [Kimi Code 文档：在第三方 Coding Agent 中使用](https://www.kimi.com/code/docs/third-party-tools/other-coding-agents.html)
|
||||
@@ -0,0 +1,210 @@
|
||||
# Keep Codex Remote Control and Official Plugins While Using Third-Party APIs: CC Switch Setup Guide
|
||||
|
||||
> Applies to CC Switch v3.16.1 and later. This guide is based on the current code, user manual, and v3.16.1 release notes. Screenshots use de-identified sample data and do not include real Access Tokens or API keys.
|
||||
|
||||
## What this guide solves
|
||||
|
||||
Many Codex users want both of these at the same time:
|
||||
|
||||
1. Use models from DeepSeek, Kimi, GLM, MiniMax, SiliconFlow, or other third-party APIs, or use GPT models through an aggregator.
|
||||
2. Keep Codex official-app capabilities such as mobile remote control and official plugins.
|
||||
|
||||
Previously, when switching to a third-party provider, the old behavior wrote the third-party API key into Codex `auth.json`, which could overwrite the original official ChatGPT / Codex login cache. The third-party model worked, but features that depend on the official login state disappeared.
|
||||
|
||||
The **Codex App Enhancements** switch added in v3.16.1 solves this conflict: the official Access Token stays in `auth.json`, while third-party provider information is written to `config.toml`. Codex App can still see an official account, but actual model requests follow the third-party provider currently selected in CC Switch.
|
||||
|
||||
This behavior already existed in v3.16.0 and was enabled by default. After some users reported that they did not want this behavior, v3.16.1 turned it into an explicit switch.
|
||||
|
||||
## Quick answer
|
||||
|
||||
Recommended order:
|
||||
|
||||
1. In the CC Switch Codex panel, switch to `OpenAI Official`.
|
||||
2. Start Codex and log in once with an official ChatGPT / Codex account. A Free subscription is enough.
|
||||
3. Return to CC Switch and enable `Settings -> General -> Codex App Enhancements -> Keep official login when switching third-party providers`.
|
||||
4. Add or switch to a third-party Codex provider.
|
||||
5. If the provider uses the Chat Completions protocol, such as DeepSeek / Kimi / MiniMax, also enable local routing and route Codex through it.
|
||||
6. Restart Codex so `config.toml` and the model catalog are reloaded.
|
||||
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Prepare the following:
|
||||
|
||||
- CC Switch v3.16.1 or later.
|
||||
- Codex installed and able to start. Installing both the app and CLI is recommended.
|
||||
- An official ChatGPT / Codex account that can log in to Codex. A Free subscription is enough.
|
||||
- A third-party API key, such as DeepSeek, Kimi, GLM, MiniMax, OpenRouter, SiliconFlow, or similar.
|
||||
|
||||
Do not manually copy or share the contents of `~/.codex/auth.json`. It stores official login cache and Access Tokens, so it is sensitive.
|
||||
|
||||
## Step 1: Switch back to OpenAI Official and complete official login
|
||||
|
||||
Open CC Switch and switch to the top-level `Codex` tab. First select the `OpenAI Official` provider, or add it from the preset providers if it is missing, and make it the current provider.
|
||||
|
||||
|
||||
|
||||
Then start Codex, preferably the CLI, and follow the official login flow to sign in with your ChatGPT / Codex account. This account can be on the Free plan. In this setup, it mainly preserves the official identity required by Codex App, and does not pay for third-party model usage.
|
||||
|
||||
After login, Codex stores the official login cache in `~/.codex/auth.json`. The key point for the following steps is: do not let third-party provider switching overwrite this file again.
|
||||
|
||||
## Step 2: Enable Codex App Enhancements
|
||||
|
||||
Return to CC Switch and open:
|
||||
|
||||
```text
|
||||
Settings -> General -> Codex App Enhancements
|
||||
```
|
||||
|
||||
Enable:
|
||||
|
||||
```text
|
||||
Keep official login when switching third-party providers
|
||||
```
|
||||
|
||||
This switch is off by default because some users do not want this behavior. Enable it only when you explicitly want "third-party API + official remote control / official plugins" at the same time.
|
||||
|
||||
After it is enabled, backend switching for third-party Codex providers uses a config-only write path:
|
||||
|
||||
- `auth.json`: keeps the official ChatGPT / Codex login cache.
|
||||
- `config.toml`: stores the active third-party provider's model, endpoint, `model_provider`, and provider-scoped `experimental_bearer_token`.
|
||||
|
||||
## Step 3: Add a third-party Codex provider
|
||||
|
||||
Return to the Codex panel and click the plus button in the upper-right corner to add a provider. Prefer built-in presets such as DeepSeek, Kimi, MiniMax, GLM, or SiliconFlow.
|
||||
|
||||
Using DeepSeek as an example, after selecting the preset, you only need to enter the API key. The preset automatically configures the base URL, default model, model mapping table, and "Needs Local Routing" flag.
|
||||
|
||||
|
||||
|
||||
If your third-party provider natively supports the OpenAI Responses API, such as an aggregator that offers GPT models, local routing may not be needed.
|
||||
If it only supports OpenAI Chat Completions, which is common for DeepSeek / Kimi / MiniMax paths, local routing must be enabled so CC Switch can convert Codex Responses requests into Chat Completions requests.
|
||||
|
||||
## Step 4: Enable local routing and route Codex when needed
|
||||
|
||||
Open:
|
||||
|
||||
```text
|
||||
Settings -> Routing -> Local Routing
|
||||
```
|
||||
|
||||
Complete two actions:
|
||||
|
||||
1. Turn on the main routing switch to start the local service. The default address is usually `127.0.0.1:15721`.
|
||||
2. Under `Routing Enabled`, turn on `Codex`.
|
||||
|
||||
|
||||
|
||||
After takeover, Codex's live `config.toml` temporarily points to the CC Switch local route. The real third-party API key remains in the CC Switch provider configuration, and is projected into the `experimental_bearer_token` in `config.toml` when providers are switched.
|
||||
|
||||
## Step 5: Switch to the third-party provider and restart Codex
|
||||
|
||||
Return to the Codex provider list and enable the third-party provider you just added. After switching, restarting Codex is recommended for two reasons:
|
||||
|
||||
- Codex reads `config.toml` at startup.
|
||||
- The Codex `/model` menu usually needs a restart before it reloads `model_catalog_json`.
|
||||
|
||||
After restart, you can run a quick verification:
|
||||
|
||||
- In Codex App, the account information still shows the official account. This is expected.
|
||||
- In CC Switch, the current Codex provider is the third-party provider.
|
||||
- If local routing is enabled, request logs or routing stats show Codex requests going through the local route.
|
||||
- The third-party provider dashboard or balance records show actual model requests.
|
||||
|
||||
## How it works
|
||||
|
||||
Codex mainly uses two configuration files:
|
||||
|
||||
```text
|
||||
~/.codex/auth.json
|
||||
~/.codex/config.toml
|
||||
```
|
||||
|
||||
They have different responsibilities:
|
||||
|
||||
- `auth.json` stores the official ChatGPT / Codex login cache, which Codex App needs to identify the official account and enable remote control and official plugins.
|
||||
- `config.toml` stores runtime configuration such as the current model provider, base URL, model, model catalog, and provider-scoped token.
|
||||
|
||||
After `Keep official login when switching third-party providers` is enabled, CC Switch takes the third-party provider API key from the provider configuration and writes it under the current provider in `config.toml`:
|
||||
|
||||
```toml
|
||||
model_provider = "custom"
|
||||
|
||||
[model_providers.custom]
|
||||
name = "DeepSeek"
|
||||
base_url = "https://api.deepseek.com"
|
||||
wire_api = "responses"
|
||||
experimental_bearer_token = "sk-..."
|
||||
```
|
||||
|
||||
At the same time, `auth.json` keeps the official login cache unchanged. Codex App can still identify the official account, while model requests follow the current provider and base URL in `config.toml`.
|
||||
|
||||
If the provider uses the Chat Completions protocol, CC Switch local routing adds another conversion layer:
|
||||
|
||||
```text
|
||||
Codex Responses request
|
||||
|
|
||||
CC Switch local route
|
||||
|
|
||||
Third-party Chat Completions API
|
||||
|
|
||||
Converted back to Codex Responses response
|
||||
```
|
||||
|
||||
This is why you can keep using official plugins / mobile remote control while moving model traffic to a third-party API.
|
||||
|
||||
## Side effects to understand
|
||||
|
||||
### Codex still shows the official account
|
||||
|
||||
This is the easiest part to misunderstand. After this capability is enabled, Codex App reads the official login state from `auth.json`, so it continues to display the official account.
|
||||
|
||||
That does not mean model requests are still going to official OpenAI. Actual traffic is determined by the current Codex provider in CC Switch, `config.toml`, and local routing logs.
|
||||
|
||||
### Do not use the Codex account display to judge billing
|
||||
|
||||
If you switch to DeepSeek, Codex can still display the official account, while model requests go to the DeepSeek API. Billing, quota, error codes, and data policy should all be understood according to the third-party provider. You can inspect specific request details in the usage panel.
|
||||
|
||||
### Restart Codex after changing model mappings
|
||||
|
||||
Codex reads the model catalog at startup. Even if CC Switch has generated a new model catalog, a running Codex process may not hot-load it, so restart Codex after editing model mappings.
|
||||
|
||||
### Turning the switch off returns to the old behavior
|
||||
|
||||
If `Keep official login when switching third-party providers` is turned off, third-party provider switching uses the compatibility behavior from older versions and may write `auth.json` again. If your goal is to keep official remote control and official plugins long term, keep this switch enabled.
|
||||
|
||||
## FAQ
|
||||
|
||||
**I switched to a third-party API. Why does Codex still show the official account?**
|
||||
|
||||
This is expected. Official account information comes from `auth.json`; the actual model provider comes from `config.toml` and the current provider in CC Switch.
|
||||
|
||||
**Is a Free subscription really enough?**
|
||||
|
||||
Yes. The official account is mainly used to obtain and preserve the official login state required by Codex App. Third-party model requests use the third-party API key configured in CC Switch.
|
||||
|
||||
**What should I do if official plugins or mobile remote control still do not work?**
|
||||
|
||||
Switch back to `OpenAI Official`, restart Codex, and complete official login once. Then confirm `Settings -> General -> Codex App Enhancements -> Keep official login when switching third-party providers` is enabled in CC Switch before switching back to the third-party provider.
|
||||
|
||||
**What if third-party requests return 404, the model list is wrong, or streaming responses are broken?**
|
||||
|
||||
If the provider uses Chat Completions, confirm that the provider form has `Needs Local Routing` enabled, and that `Settings -> Routing` has both the main routing switch and Codex takeover enabled.
|
||||
|
||||
**Can I switch back to OpenAI Official while local routing is enabled?**
|
||||
|
||||
Not recommended. CC Switch tries to prevent switching to official providers while local routing takeover is active, because accessing official APIs through a proxy may create account risk. Use official login only to preserve `auth.json`, and route model traffic to third-party providers.
|
||||
|
||||
**Why is this flow so complex? Can it be simplified?**
|
||||
|
||||
Because Codex App Enhancements and routing takeover can create unnecessary trouble for users who do not need them, these features are explicit switches instead of always-on behavior.
|
||||
|
||||
## References
|
||||
|
||||
- [Can't see custom models in the Codex desktop app? (FAQ)](./codex-desktop-custom-model-visibility-en.md)
|
||||
- [Codex DeepSeek local routing hands-on guide](./codex-deepseek-routing-guide-en.md)
|
||||
- [Add a Codex provider: Chat Completions routing and model mapping](../user-manual/en/2-providers/2.1-add.md)
|
||||
- [Local Proxy Service](../user-manual/en/4-proxy/4.1-service.md)
|
||||
- [Local Routing](../user-manual/en/4-proxy/4.2-routing.md)
|
||||
- [CC Switch v3.16.1 Release Note](../release-notes/v3.16.1-en.md)
|
||||
@@ -0,0 +1,210 @@
|
||||
# サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する: CC Switch 設定ガイド
|
||||
|
||||
> 対象バージョン: CC Switch v3.16.1 以降。本記事は現在のコード、ユーザーマニュアル、v3.16.1 Release Note をもとに整理しています。スクリーンショットは匿名化したサンプルデータを使用しており、実際の Access Token や API Key は含まれていません。
|
||||
|
||||
## このガイドで解決すること
|
||||
|
||||
Codex を使うとき、多くのユーザーには次の 2 つの要望があります。
|
||||
|
||||
1. DeepSeek、Kimi、GLM、MiniMax、SiliconFlow などのサードパーティ API、または中継サービス上の GPT モデルを使いたい。
|
||||
2. Codex 公式アプリのモバイルリモート操作、公式プラグインなどの機能は残したい。
|
||||
|
||||
以前は、サードパーティプロバイダーへ切り替えると、旧動作ではサードパーティ API Key が Codex の `auth.json` に書き込まれ、元の公式 ChatGPT / Codex ログインキャッシュを上書きする可能性がありました。これによりサードパーティモデルは使えるものの、公式ログイン状態に依存する機能が消えてしまうことがありました。
|
||||
|
||||
v3.16.1 で追加された **Codex アプリ拡張** スイッチは、この矛盾を解決するためのものです。公式 Access Token は `auth.json` に残し、サードパーティプロバイダー情報は `config.toml` に書き込みます。これにより Codex App は引き続き公式アカウントでログインしていると認識しつつ、実際のモデルリクエストは CC Switch で現在選択されているサードパーティプロバイダーへ流れます。
|
||||
|
||||
この機能自体は v3.16.0 から存在し、当時はデフォルトで有効でした。ただし一部のユーザーから不要というフィードバックがあったため、v3.16.1 で明示的なスイッチになりました。
|
||||
|
||||
## まず結論
|
||||
|
||||
おすすめの手順は次のとおりです。
|
||||
|
||||
1. CC Switch の Codex パネルで `OpenAI Official` に切り替える。
|
||||
2. Codex を起動し、公式 ChatGPT / Codex アカウントで一度ログインする。Free サブスクリプションでも構いません。
|
||||
3. CC Switch に戻り、`設定 → 一般 → Codex アプリ拡張 → サードパーティ切替時に公式ログインを保持` をオンにする。
|
||||
4. サードパーティ Codex プロバイダーを追加、または切り替える。
|
||||
5. そのプロバイダーが DeepSeek / Kimi / MiniMax などの Chat Completions プロトコルの場合は、ローカルルーティングも有効化し、Codex のルーティングをオンにする。
|
||||
6. Codex を再起動し、`config.toml` とモデルカタログを再読み込みさせる。
|
||||
|
||||
|
||||
|
||||
## 事前準備
|
||||
|
||||
次のものを用意してください。
|
||||
|
||||
- CC Switch v3.16.1 以降。
|
||||
- インストール済みで起動できる Codex。app と CLI の両方を入れておくことをおすすめします。
|
||||
- Codex にログインできる公式 ChatGPT / Codex アカウント。Free サブスクリプションで構いません。
|
||||
- DeepSeek、Kimi、GLM、MiniMax、OpenRouter、SiliconFlow などのサードパーティ API Key。
|
||||
|
||||
`~/.codex/auth.json` の内容を手動でコピーしたり共有したりしないでください。このファイルには公式ログインキャッシュと Access Token が保存されており、機密情報です。
|
||||
|
||||
## Step 1: OpenAI Official に戻して公式ログインを完了する
|
||||
|
||||
CC Switch を開き、上部の `Codex` タブへ切り替えます。まず `OpenAI Official` プロバイダーを選択します。存在しない場合は、プリセットプロバイダーから追加して現在のプロバイダーにしてください。
|
||||
|
||||
|
||||
|
||||
次に Codex を起動します。CLI の起動がおすすめです。Codex の公式ログインフローに従い、ChatGPT / Codex アカウントでログインします。このアカウントは Free プランでも問題ありません。この構成では、主に Codex App が必要とする公式ログイン ID を保持する役割であり、サードパーティモデルの課金には使いません。
|
||||
|
||||
ログイン後、Codex は `~/.codex/auth.json` に公式ログインキャッシュを保存します。以降の重要なポイントは、サードパーティプロバイダー切り替えでこのファイルを上書きさせないことです。
|
||||
|
||||
## Step 2: Codex アプリ拡張を有効化する
|
||||
|
||||
CC Switch に戻り、次を開きます。
|
||||
|
||||
```text
|
||||
設定 → 一般 → Codex アプリ拡張
|
||||
```
|
||||
|
||||
次のスイッチをオンにします。
|
||||
|
||||
```text
|
||||
サードパーティ切替時に公式ログインを保持
|
||||
```
|
||||
|
||||
このスイッチはデフォルトでオフです。一部のユーザーはこの機能を必要としていないためです。「サードパーティ API + 公式リモート操作 / 公式プラグイン」を同時に使いたい場合だけ有効化してください。
|
||||
|
||||
有効化すると、バックエンドで Codex サードパーティプロバイダーを切り替えるときに config-only の書き込み経路が使われます。
|
||||
|
||||
- `auth.json`: 公式 ChatGPT / Codex ログインキャッシュを保持します。
|
||||
- `config.toml`: 現在のサードパーティプロバイダーのモデル、endpoint、`model_provider`、provider-scoped `experimental_bearer_token` を書き込みます。
|
||||
|
||||
## Step 3: サードパーティ Codex プロバイダーを追加する
|
||||
|
||||
Codex パネルに戻り、右上のプラスボタンからプロバイダーを追加します。DeepSeek、Kimi、MiniMax、GLM、SiliconFlow などの内蔵プリセットを優先して使うのがおすすめです。
|
||||
|
||||
DeepSeek を例にすると、プリセットを選んだ後は API Key を入力するだけです。プリセットは base URL、デフォルトモデル、モデルマッピングテーブル、「ローカルルーティングが必要」設定を自動で構成します。
|
||||
|
||||
|
||||
|
||||
サードパーティプロバイダーが OpenAI Responses API をネイティブにサポートしている場合、たとえば GPT モデルを提供する中継サービスであれば、ローカルルーティングは不要なことがあります。
|
||||
一方で DeepSeek / Kimi / MiniMax のように OpenAI Chat Completions だけをサポートする場合は、CC Switch が Codex の Responses リクエストを Chat Completions リクエストへ変換する必要があるため、ローカルルーティングを有効化してください。
|
||||
|
||||
## Step 4: 必要に応じてローカルルーティングと Codex ルーティングを有効化する
|
||||
|
||||
次を開きます。
|
||||
|
||||
```text
|
||||
設定 → ルーティング → ローカルルーティング
|
||||
```
|
||||
|
||||
次の 2 つを行います。
|
||||
|
||||
1. `ルーティング総スイッチ` をオンにし、ローカルサービスを起動する。デフォルトアドレスは通常 `127.0.0.1:15721` です。
|
||||
2. `ルーティング有効` で `Codex` をオンにする。
|
||||
|
||||
|
||||
|
||||
ルーティング有効化後、Codex の live `config.toml` は一時的に CC Switch のローカルルートを指します。実際のサードパーティ API Key は CC Switch のプロバイダー設定内に残り、プロバイダー切り替え時に `config.toml` の `experimental_bearer_token` へ投影されます。
|
||||
|
||||
## Step 5: サードパーティプロバイダーへ切り替えて Codex を再起動する
|
||||
|
||||
Codex プロバイダー一覧に戻り、先ほど追加したサードパーティプロバイダーを有効化します。切り替え後は Codex の再起動をおすすめします。理由は 2 つあります。
|
||||
|
||||
- Codex は起動時に `config.toml` を読み込みます。
|
||||
- Codex の `/model` メニューは通常、再起動後に `model_catalog_json` を再読み込みします。
|
||||
|
||||
再起動後、簡単に確認できます。
|
||||
|
||||
- Codex App ではアカウント情報が引き続き公式アカウントとして表示される。これは期待される動作です。
|
||||
- CC Switch では現在の Codex プロバイダーがサードパーティプロバイダーになっている。
|
||||
- ローカルルーティングを有効化している場合、リクエストログまたはルーティング統計で Codex リクエストがローカルルートを通っていることを確認できる。
|
||||
- サードパーティプロバイダー側のダッシュボードや残高記録に実際のモデルリクエストが表示される。
|
||||
|
||||
## 仕組み
|
||||
|
||||
Codex の設定は主に 2 つのファイルに分かれています。
|
||||
|
||||
```text
|
||||
~/.codex/auth.json
|
||||
~/.codex/config.toml
|
||||
```
|
||||
|
||||
この 2 つは役割が異なります。
|
||||
|
||||
- `auth.json` は公式 ChatGPT / Codex ログインキャッシュを保存します。Codex App が公式アカウント、リモート操作、公式プラグインを認識するために必要なログイン材料です。
|
||||
- `config.toml` は現在のモデルプロバイダー、base URL、モデル、モデルカタログ、provider-scoped token などの実行時設定を保存します。
|
||||
|
||||
`サードパーティ切替時に公式ログインを保持` を有効化すると、CC Switch はサードパーティプロバイダー API Key をプロバイダー設定から取り出し、`config.toml` の現在の provider 配下へ書き込みます。
|
||||
|
||||
```toml
|
||||
model_provider = "custom"
|
||||
|
||||
[model_providers.custom]
|
||||
name = "DeepSeek"
|
||||
base_url = "https://api.deepseek.com"
|
||||
wire_api = "responses"
|
||||
experimental_bearer_token = "sk-..."
|
||||
```
|
||||
|
||||
同時に、`auth.json` は公式ログインキャッシュを保持したままです。そのため Codex App 側では公式アカウントを認識でき、モデルリクエストは `config.toml` の現在の provider と base URL に従ってサードパーティ API へ向かいます。
|
||||
|
||||
プロバイダーが Chat Completions プロトコルの場合、CC Switch のローカルルーティングがさらに変換層になります。
|
||||
|
||||
```text
|
||||
Codex Responses リクエスト
|
||||
|
|
||||
CC Switch ローカルルート
|
||||
|
|
||||
サードパーティ Chat Completions API
|
||||
|
|
||||
Codex Responses レスポンスへ変換
|
||||
```
|
||||
|
||||
これにより、公式プラグイン / モバイルリモート操作を使い続けながら、モデル通信だけをサードパーティ API に切り替えられます。
|
||||
|
||||
## 理解しておくべき副作用
|
||||
|
||||
### Codex 内の表示アカウントは公式アカウントのまま
|
||||
|
||||
ここが最も誤解されやすい点です。この機能を有効化すると、Codex App は `auth.json` 内の公式ログイン状態を見るため、公式アカウント情報を表示し続けます。
|
||||
|
||||
ただし、これはモデルリクエストが公式 OpenAI に流れているという意味ではありません。実際の通信先は、CC Switch の現在の Codex プロバイダー、`config.toml`、ローカルルーティングログで判断してください。
|
||||
|
||||
### Codex のアカウント表示で課金先を判断しない
|
||||
|
||||
DeepSeek に切り替えた場合でも、Codex には公式アカウントが表示されます。しかしモデルリクエストは DeepSeek API へ送られます。課金、上限、エラーコード、データポリシーはサードパーティプロバイダー側の仕様として理解してください。具体的なリクエスト情報は使用量パネルで確認できます。
|
||||
|
||||
### モデルマッピングを変更したら Codex を再起動する
|
||||
|
||||
Codex のモデルカタログは起動時に読み込まれます。CC Switch が新しいモデルカタログを生成していても、実行中の Codex がホットロードするとは限りません。モデルマッピングを変更した後は Codex を再起動してください。
|
||||
|
||||
### スイッチをオフにすると旧動作に戻る
|
||||
|
||||
`サードパーティ切替時に公式ログインを保持` をオフにすると、サードパーティプロバイダー切り替えは旧バージョン互換の動作になり、`auth.json` が再度書き込まれる可能性があります。公式リモート操作と公式プラグインを長期的に保持したい場合は、このスイッチをオンのままにすることをおすすめします。
|
||||
|
||||
## よくある質問
|
||||
|
||||
**サードパーティ API に切り替えたのに、なぜ Codex はまだ公式アカウントを表示しますか？**
|
||||
|
||||
これは期待される動作です。公式アカウント情報は `auth.json` から取得され、実際のモデルプロバイダーは `config.toml` と CC Switch の現在のプロバイダーで決まります。
|
||||
|
||||
**Free サブスクリプションで本当に大丈夫ですか？**
|
||||
|
||||
大丈夫です。ここでの公式アカウントは、Codex App が必要とする公式ログイン状態を取得・保持するために使います。サードパーティモデルリクエストは、CC Switch に設定したサードパーティ API Key を使います。
|
||||
|
||||
**有効化しても公式プラグインやモバイルリモート操作が使えない場合は？**
|
||||
|
||||
まず `OpenAI Official` に戻し、Codex を再起動して一度公式ログインを完了してください。その後、CC Switch の `設定 → 一般 → Codex アプリ拡張 → サードパーティ切替時に公式ログインを保持` がオンになっていることを確認し、再度サードパーティプロバイダーへ切り替えてください。
|
||||
|
||||
**サードパーティリクエストが 404 になる、モデル一覧が違う、ストリーミング応答がおかしい場合は？**
|
||||
|
||||
そのプロバイダーが Chat Completions プロトコルの場合、プロバイダーフォームで `ローカルルーティングが必要` が有効になっていること、さらに `設定 → ルーティング` でルーティング総スイッチと Codex ルーティングがオンになっていることを確認してください。
|
||||
|
||||
**ローカルルーティング中に OpenAI Official へ戻せますか？**
|
||||
|
||||
おすすめしません。CC Switch は、ローカルルーティングで Codex を管理している間に公式プロバイダーへ切り替えることをできるだけ防ぎます。プロキシ経由で公式 API にアクセスすると、アカウントリスクが発生する可能性があるためです。公式ログインは `auth.json` を保持するために使い、モデル通信はサードパーティプロバイダーへ切り替えるのがおすすめです。
|
||||
|
||||
**なぜ手順がこんなに複雑なのですか？もっと簡単にできますか？**
|
||||
|
||||
Codex アプリ拡張やルーティング管理は、必要ないユーザーにとっては余計なトラブルになり得るため、常時有効ではなく明示的なスイッチになっています。
|
||||
|
||||
## 参考リンク
|
||||
|
||||
- [Codex デスクトップアプリでカスタムモデルが見えない？（よくある質問）](./codex-desktop-custom-model-visibility-ja.md)
|
||||
- [Codex DeepSeek ローカルルーティング実践ガイド](./codex-deepseek-routing-guide-ja.md)
|
||||
- [Codex プロバイダーの追加: Chat Completions ルーティングとモデルマッピング](../user-manual/ja/2-providers/2.1-add.md)
|
||||
- [ローカルプロキシサービス](../user-manual/ja/4-proxy/4.1-service.md)
|
||||
- [ローカルルーティング](../user-manual/ja/4-proxy/4.2-routing.md)
|
||||
- [CC Switch v3.16.1 Release Note](../release-notes/v3.16.1-ja.md)
|
||||
@@ -0,0 +1,210 @@
|
||||
# 使用第三方 API 时保留 Codex 远程操作和官方插件：CC Switch 配置攻略
|
||||
|
||||
> 适用版本：CC Switch v3.16.1 及以上。本文根据当前代码、用户手册和 v3.16.1 Release Note 整理，截图使用去敏示例数据，不包含真实 Access Token 或 API Key。
|
||||
|
||||
## 这篇攻略解决什么问题
|
||||
|
||||
很多人使用 Codex 时有两个需求：
|
||||
|
||||
1. 模型使用 DeepSeek、Kimi、GLM、MiniMax、硅基流动等第三方 API，或者在中转站使用 gpt 模型。
|
||||
2. 保留 Codex 官方 App 的手机远程操作、官方插件等能力。
|
||||
|
||||
之前切换第三方供应商时，旧行为会把第三方 API Key 写进 Codex 的 `auth.json`，从而覆盖原来的官方 ChatGPT / Codex 登录缓存。这样第三方模型能用了，但依赖官方登录态的功能会消失。
|
||||
|
||||
v3.16.1 新增的 **Codex 应用增强**开关就是为了解决这个矛盾：让官方 Access Token 继续留在 `auth.json`，而第三方供应商信息写入 `config.toml`。这样 Codex App 仍然认为你登录的是官方账号，但实际模型请求会走 CC Switch 当前选中的第三方供应商。
|
||||
|
||||
v3.16.0 就有这个功能，并且默认开启，但是部分用户反映并不想要这个功能，所以在 v3.16.1 中把这个功能做成了开关。
|
||||
|
||||
## 先看结论
|
||||
|
||||
推荐顺序是：
|
||||
|
||||
1. 在 CC Switch 的 Codex 面板切换到 `OpenAI Official`。
|
||||
2. 启动 Codex，并用官方 ChatGPT / Codex 账号登录一次，Free 订阅也可以。
|
||||
3. 回到 CC Switch，打开 `设置 → 通用 → Codex 应用增强 → 切换第三方时保留官方登录`。
|
||||
4. 添加或切换到第三方 Codex 供应商。
|
||||
5. 如果该供应商是 Chat Completions 协议，例如 DeepSeek / Kimi / MiniMax，需要同时开启本地路由并启用 Codex 接管。
|
||||
6. 重启 Codex，让 `config.toml` 和模型目录重新加载。
|
||||
|
||||
|
||||
|
||||
## 准备工作
|
||||
|
||||
你需要准备：
|
||||
|
||||
- CC Switch v3.16.1 或更新版本。
|
||||
- 已安装并能启动的 Codex（建议 app 和 cli 都安装）。
|
||||
- 一个可以登录 Codex 的官方 ChatGPT / Codex 账号，Free 订阅即可。
|
||||
- 一个第三方 API Key，例如 DeepSeek、Kimi、GLM、MiniMax、OpenRouter、硅基流动等。
|
||||
|
||||
请不要手动复制或分享 `~/.codex/auth.json` 的内容。里面保存的是官方登录缓存和 Access Token，属于敏感信息。
|
||||
|
||||
## 第一步：先切回 OpenAI Official 并完成官方登录
|
||||
|
||||
打开 CC Switch，切到顶部的 `Codex` 标签页。先选择 `OpenAI Official` 供应商（如果没有的话，就在预设供应商当中添加一个），并把它设为当前供应商。
|
||||
|
||||
|
||||
|
||||
接着启动 Codex（建议启动 cli），按 Codex 的官方登录流程登录你的 ChatGPT / Codex 账号。这个账号可以是 Free 订阅；在这个方案里，它主要负责保留 Codex 官方 App 需要识别的登录身份，不负责第三方模型的计费。
|
||||
|
||||
登录完成后，Codex 会在 `~/.codex/auth.json` 中保存官方登录缓存。后面的关键点就是：不要再让第三方供应商切换覆盖这个文件。
|
||||
|
||||
## 第二步：开启 Codex 应用增强
|
||||
|
||||
回到 CC Switch，进入：
|
||||
|
||||
```text
|
||||
设置 → 通用 → Codex 应用增强
|
||||
```
|
||||
|
||||
打开：
|
||||
|
||||
```text
|
||||
切换第三方时保留官方登录
|
||||
```
|
||||
|
||||
这个开关默认关闭，是因为部分用户并不想要这个功能。只有在你明确需要“第三方 API + 官方远程操作 / 官方插件”同时存在时，才需要开启它。
|
||||
|
||||
开启后，后端切换 Codex 第三方供应商时会走 config-only 写入路径：
|
||||
|
||||
- `auth.json`：继续保留官方 ChatGPT / Codex 登录缓存。
|
||||
- `config.toml`：写入当前第三方供应商的模型、endpoint、`model_provider` 和 provider-scoped `experimental_bearer_token`。
|
||||
|
||||
## 第三步：添加第三方 Codex 供应商
|
||||
|
||||
回到 Codex 面板，点击右上角的加号添加供应商。推荐优先使用内置预设，例如 DeepSeek、Kimi、MiniMax、GLM、SiliconFlow 等。
|
||||
|
||||
以 DeepSeek 为例，选择预设后只需要填 API Key。预设会自动配置 base URL、默认模型、模型映射表和“需要本地路由映射”。
|
||||
|
||||
|
||||
|
||||
如果你的第三方供应商原生支持 OpenAI Responses API（比如提供 gpt 模型的中转站），可以不启用本地路由。
|
||||
如果它只支持 OpenAI Chat Completions，例如常见的 DeepSeek / Kimi / MiniMax 路径，就必须启用本地路由，让 CC Switch 把 Codex 的 Responses 请求转换成 Chat Completions 请求。
|
||||
|
||||
## 第四步：需要时开启本地路由并接管 Codex
|
||||
|
||||
进入：
|
||||
|
||||
```text
|
||||
设置 → 路由 → 本地路由
|
||||
```
|
||||
|
||||
完成两件事：
|
||||
|
||||
1. 打开 `路由总开关`，启动本地服务。默认地址通常是 `127.0.0.1:15721`。
|
||||
2. 在 `路由启用` 中打开 `Codex`。
|
||||
|
||||
|
||||
|
||||
接管后，Codex 的 live `config.toml` 会临时指向 CC Switch 本地路由。真实第三方 API Key 仍然存储在 CC Switch 的供应商配置中，切换供应商时再投影到 `config.toml` 的 `experimental_bearer_token`。
|
||||
|
||||
## 第五步：切换第三方供应商并重启 Codex
|
||||
|
||||
回到 Codex 供应商列表，启用你刚添加的第三方供应商。切换完成后建议重启 Codex，原因有两个：
|
||||
|
||||
- Codex 在启动时读取 `config.toml`。
|
||||
- Codex 的 `/model` 菜单通常需要重启后才会重新加载 `model_catalog_json`。
|
||||
|
||||
重启后，你可以做一个简单验证：
|
||||
|
||||
- 在 Codex App 里，账号信息仍然显示官方账号，这是预期行为。
|
||||
- 在 CC Switch 里，当前 Codex 供应商显示为第三方供应商。
|
||||
- 如果开启了本地路由，请求日志或路由统计会看到 Codex 请求经过本地路由。
|
||||
- 第三方供应商后台或余额记录会出现实际模型请求。
|
||||
|
||||
## 背后的原理
|
||||
|
||||
Codex 的配置主要分成两个文件：
|
||||
|
||||
```text
|
||||
~/.codex/auth.json
|
||||
~/.codex/config.toml
|
||||
```
|
||||
|
||||
这两个文件承担的职责不同：
|
||||
|
||||
- `auth.json` 保存官方 ChatGPT / Codex 登录缓存，也就是 Codex App 识别官方账号、远程操作和官方插件所需的登录材料。
|
||||
- `config.toml` 保存当前模型供应商、base URL、模型、模型目录和 provider-scoped token 等运行配置。
|
||||
|
||||
开启 `切换第三方时保留官方登录` 后，CC Switch 的切换逻辑会把第三方供应商 API Key 从供应商配置中取出，写到 `config.toml` 的当前 provider 下：
|
||||
|
||||
```toml
|
||||
model_provider = "custom"
|
||||
|
||||
[model_providers.custom]
|
||||
name = "DeepSeek"
|
||||
base_url = "https://api.deepseek.com"
|
||||
wire_api = "responses"
|
||||
experimental_bearer_token = "sk-..."
|
||||
```
|
||||
|
||||
同时，`auth.json` 保持官方登录缓存不变。于是 Codex App 侧依然能识别官方账号；而模型请求会根据 `config.toml` 的当前 provider 和 base URL 走第三方 API。
|
||||
|
||||
如果供应商是 Chat Completions 协议，CC Switch 本地路由会再做一层转换：
|
||||
|
||||
```text
|
||||
Codex Responses 请求
|
||||
↓
|
||||
CC Switch 本地路由
|
||||
↓
|
||||
第三方 Chat Completions API
|
||||
↓
|
||||
转换回 Codex Responses 响应
|
||||
```
|
||||
|
||||
这就是为什么你既能继续使用官方插件 / 手机远程操作，又能把模型流量切到第三方 API。
|
||||
|
||||
## 需要理解的副作用
|
||||
|
||||
### Codex 里显示的账号始终是官方账号
|
||||
|
||||
这是最容易误解的一点。开启该能力后，Codex App 看到的是 `auth.json` 里的官方登录态，所以它会继续显示官方账号信息。
|
||||
|
||||
但这不代表模型请求还在走官方 OpenAI。实际流量以 CC Switch 当前 Codex 供应商、`config.toml` 和本地路由日志为准。
|
||||
|
||||
### 不要用 Codex 账号信息判断计费方
|
||||
|
||||
如果你切到 DeepSeek，Codex 里仍然显示官方账号，但模型请求会走 DeepSeek API。计费、限额、错误码和数据策略都应按第三方供应商理解。可以查看设置用量面板里的具体请求信息。
|
||||
|
||||
### 修改模型映射后要重启 Codex
|
||||
|
||||
Codex 的模型目录是启动时读取的。即使 CC Switch 已经生成了新的模型目录，正在运行的 Codex 也不一定会热加载，所以修改模型映射后请重启 Codex。
|
||||
|
||||
### 关闭开关会回到旧行为
|
||||
|
||||
如果关闭 `切换第三方时保留官方登录`，第三方供应商切换会沿用兼容旧版本的行为，可能重新写入 `auth.json`。如果你的目标是长期保留官方远程操作和官方插件，建议保持该开关开启。
|
||||
|
||||
## 常见问题
|
||||
|
||||
**我已经切到第三方 API，为什么 Codex 还显示官方账号？**
|
||||
|
||||
这是预期行为。官方账号信息来自 `auth.json`，模型请求的实际供应商来自 `config.toml` 和 CC Switch 当前供应商。
|
||||
|
||||
**Free 订阅真的可以吗？**
|
||||
|
||||
可以。这里的官方账号主要用于获取并保留 Codex App 需要的官方登录态。第三方模型请求使用的是你在 CC Switch 里配置的第三方 API Key。
|
||||
|
||||
**开启后官方插件或手机远程操作还是不可用怎么办？**
|
||||
|
||||
先切回 `OpenAI Official`，重新启动 Codex 并完成一次官方登录；然后确认 CC Switch 的 `设置 → 通用 → Codex 应用增强 → 切换第三方时保留官方登录` 已开启，再切回第三方供应商。
|
||||
|
||||
**第三方请求 404、模型列表不对或流式响应异常怎么办？**
|
||||
|
||||
如果该供应商是 Chat Completions 协议，请确认供应商表单里开启了 `需要本地路由映射`，并且 `设置 → 路由` 里已经启动路由总开关、启用 Codex 接管。
|
||||
|
||||
**可以在本地路由模式下切回 OpenAI Official 吗？**
|
||||
|
||||
不建议。CC Switch 会尽量阻止在本地路由接管模式下切到官方供应商，因为用代理访问官方 API 可能带来账号风险。建议官方登录只用于保留 `auth.json`，模型流量则切到第三方供应商。
|
||||
|
||||
**为什么流程做的这么复杂？可以简化吗？**
|
||||
|
||||
因为 Codex 增强开关和路由接管等一系列功能，如果用户并不需要的话，默认打开会带来不必要的麻烦，所以都做成了开关形式。
|
||||
|
||||
## 参考链接
|
||||
|
||||
- [Codex 桌面应用里看不到自定义模型？（常见问题）](./codex-desktop-custom-model-visibility-zh.md)
|
||||
- [Codex DeepSeek 本地路由实战攻略](./codex-deepseek-routing-guide-zh.md)
|
||||
- [添加 Codex 供应商：Chat Completions 路由与模型映射](../user-manual/zh/2-providers/2.1-add.md)
|
||||
- [本地代理服务](../user-manual/zh/4-proxy/4.1-service.md)
|
||||
- [本地路由](../user-manual/zh/4-proxy/4.2-routing.md)
|
||||
- [CC Switch v3.16.1 Release Note](../release-notes/v3.16.1-zh.md)
|
||||
@@ -0,0 +1,467 @@
|
||||
# Unified Codex Session History: Feature Overview and Usage Guide (CC Switch)
|
||||
|
||||
> Applies to CC Switch v3.16.x and later. This guide is based on the current code; every command and path can be verified by hand. Examples use de-identified data and contain no real session content or API keys.
|
||||
|
||||
## What this feature is
|
||||
|
||||
"Unified Codex session history" is a switch that CC Switch v3.16.x adds for Codex. You'll find it under **Settings -> General -> the "Codex App Enhancements" group** ("Codex App Enhancements" is the group title; the switch itself is called "Unified Codex session history"). Once enabled, **sessions from your official subscription (ChatGPT login / OpenAI API key) appear in the same history / resume list as sessions from every third-party provider CC Switch manages**—they are no longer split into two lists that can't see each other.
|
||||
|
||||
## What problem it solves
|
||||
|
||||
Codex classifies sessions by a "provider tag" (a field called `model_provider`), and **the resume / history list only shows sessions whose tag matches your currently active provider**. As a result, sessions are naturally sorted into two separate "drawers":
|
||||
|
||||
- Sessions from your official subscription go under Codex's built-in **`openai`** tag;
|
||||
- Every third-party provider CC Switch manages goes under the **`custom`** tag.
|
||||
|
||||
The two drawers can't see each other. If you **switch frequently between official and third-party**, you'll hit this kind of fragmentation: "the session I was just chatting in with the official account disappeared from the history list after I switched to a third-party provider"—it isn't actually gone, it's just been sorted into the other drawer. This split both makes it easy to believe a session was lost, and makes it inconvenient to review and resume all your sessions in one place.
|
||||
|
||||
**This switch exists to eliminate that fragmentation**: it makes the official subscription run under the `custom` tag too, so official and third-party sessions merge into one list and everything is easy to find and resume in a single place.
|
||||
|
||||
> ✅ **One important premise that runs through this whole guide, please remember it first**: this feature (unify / migrate / restore) **only ever rewrites that one classification tag `model_provider` in your session records, and it automatically makes a backup of the original file before every rewrite**. It never deletes, clears, or overwrites a single line of your conversations. So whenever this guide later mentions "some sessions are no longer visible," it almost always means "they've been sorted into the other drawer," not "the data is gone." If you're truly worried, jump straight to the [symptom reference table](#i-feel-like-my-sessions-are-gone-symptom-reference-table) and [verify the files are still there by hand](#verify-by-hand-your-session-files-are-still-on-disk-the-most-important-section).
|
||||
|
||||
## How it works (one-line version)
|
||||
|
||||
Think of it as **two drawers + automatic backup**:
|
||||
|
||||
- By default, official sessions live in the `openai` drawer and third-party sessions live in the `custom` drawer, invisible to each other;
|
||||
- The switch makes **the official side use the `custom` drawer too**, merging the two drawers into one shared list;
|
||||
- You can optionally choose to "move" your **existing official sessions** into the shared drawer as well (this step is called **migration**; it's optional and requires you to opt in by checking a box), and **before anything is moved a backup copy is made first**, so the whole process is **reversible**;
|
||||
- **Authentication is completely unaffected**—your official subscription still uses your ChatGPT login and still goes through the official backend; only the session's classification tag changes.
|
||||
|
||||
For the full mechanism (what gets injected, why it's reversible, how migration / restore guarantee no data loss) see [The core mental model](#the-core-mental-model-two-drawers--automatic-backup) and the [Advanced mechanism appendix](#advanced-mechanism-appendix-for-users-who-want-to-truly-understand-how-it-works) at the end.
|
||||
|
||||
## How to use it (at a glance)
|
||||
|
||||
1. **Enable**: Settings -> General -> Codex App Enhancements -> turn on "Unified Codex session history" -> in the dialog decide whether to check "Also migrate existing official session history" (check it if you want your **earlier** official sessions merged into the unified list too; leave it unchecked if you only want unification from now on) -> confirm. See [What happens when you enable it](#what-happens-when-you-enable-it-step-by-step).
|
||||
2. **Disable**: turn the same switch off -> in the dialog keep "restore exactly from backup" checked (it's checked by default) -> confirm, and the official sessions you migrated in will be precisely flipped back to the official list. See [What happens when you disable it](#what-happens-when-you-disable-it-step-by-step).
|
||||
3. **Feel like a session is gone?** Don't panic—jump to the [symptom reference table](#i-feel-like-my-sessions-are-gone-symptom-reference-table) to locate it by symptom, and use the commands in the [verify by hand](#verify-by-hand-your-session-files-are-still-on-disk-the-most-important-section) section to see for yourself that the files are all there.
|
||||
|
||||
---
|
||||
|
||||
## The core mental model: two drawers + automatic backup
|
||||
|
||||
To understand this feature, you only need to remember two things: **drawers** and **backups**.
|
||||
|
||||
### Drawers: how Codex classifies sessions
|
||||
|
||||
Every time you start a Codex session, Codex records a tag `model_provider` in the session file header, marking "which provider this session was chatted with." Codex's **resume / history list is filtered precisely by the currently active tag**—it only shows sessions whose tag matches "the provider you're on right now."
|
||||
|
||||
- Sessions from your official subscription (ChatGPT login / OpenAI API key) carry the built-in tag **`openai`**.
|
||||
- Every third-party provider CC Switch manages uses the tag **`custom`**.
|
||||
|
||||
So by default, official sessions and third-party sessions are inherently invisible to each other—they live in two different drawers. This is **Codex's own design**, not CC Switch losing anything.
|
||||
|
||||
```text
|
||||
Default state (unified switch off):
|
||||
┌───────────────────────┐ ┌──────────────────────────┐
|
||||
│ openai drawer │ │ custom drawer │
|
||||
│ (official sessions) │ │ (third-party sessions) │
|
||||
└───────────────────────┘ └──────────────────────────┘
|
||||
▲ ▲
|
||||
visible only while visible only while
|
||||
on the official provider on a third-party provider
|
||||
|
||||
The two drawers can't see each other.
|
||||
```
|
||||
|
||||
**What the "Unified Codex session history" switch does is make the official subscription run under the `custom` tag too, merging the two drawers into one**, so official and third-party sessions appear in the same resume list. Note: **authentication doesn't change**—your official subscription still uses your ChatGPT login and still goes through the official backend; only the session's "classification tag" changes from `openai` to `custom`.
|
||||
|
||||
```text
|
||||
After the unified switch is on:
|
||||
┌──────────────────────────────────────────────┐
|
||||
│ custom shared drawer │
|
||||
│ official sessions + third-party sessions │
|
||||
│ (appear in the same history / resume list) │
|
||||
└──────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Backups: a copy is made before every tag change
|
||||
|
||||
"Merging the drawers" requires changing the tag of some official sessions from `openai` to `custom` (this step is called **migration**, and it's **optional and requires you to opt in**). And **before any rewrite, CC Switch first copies the original file untouched** to here:
|
||||
|
||||
```text
|
||||
~/.cc-switch/backups/codex-official-history-unify-v1/<timestamp>/
|
||||
```
|
||||
|
||||
This backup is the sole basis for "restore exactly from backup" later. It makes the whole process **reversible**: at any time you can turn off the switch and precisely flip the official sessions you migrated in back to the `openai` drawer.
|
||||
|
||||
Remember these two words—**drawer** (a session just gets reclassified) and **backup** (a copy is always made before a change)—and everything that follows will be easy to understand.
|
||||
|
||||
---
|
||||
|
||||
## What happens when you enable it: step by step
|
||||
|
||||
### Step 1: Find the switch
|
||||
|
||||
```text
|
||||
Settings -> General -> Codex App Enhancements
|
||||
```
|
||||
|
||||
In the "Codex App Enhancements" block there are two rows of switches; the **second row** (the blue history icon) is the subject of this guide:
|
||||
|
||||
> **Unified Codex session history**
|
||||
|
||||
Below it is a line of description text (verbatim):
|
||||
|
||||
> When enabled, the official subscription runs under the shared "custom" provider id so official and third-party sessions appear in one history list, optionally migrating existing official sessions in (backed up first). When turning it off, the migrated sessions can be restored from backup. Note: resuming an old session across providers may fail because its encrypted_content reasoning can only be decrypted by the backend that created it.
|
||||
|
||||
> **Note**: this single line of description already previews three things—sessions will appear in one list, you can optionally migrate them in with an automatic backup, and resuming across providers "may fail." Here, "fail" means **you can't resume / can't generate a new turn**, not "the record is lost." This is exactly the core misunderstanding we'll dig into below.
|
||||
|
||||
### Step 2: Flip the switch from off to on -> a confirmation dialog pops up
|
||||
|
||||
The moment you flip the switch on, CC Switch **does not save immediately**; instead it first pops up a confirmation dialog. The dialog text reads as follows (verbatim):
|
||||
|
||||
- **Title**: Unified Codex session history
|
||||
- **Body**:
|
||||
|
||||
> When enabled, the official subscription and third-party providers share one session history list. Note: resuming an old session across providers may fail because its encrypted_content reasoning cannot be decrypted by another backend.
|
||||
>
|
||||
> You can also migrate your existing official session history into the shared list (originals are backed up to ~/.cc-switch/backups first and can be restored when you turn this off).
|
||||
|
||||
- **Checkbox**: Also migrate existing official session history
|
||||
- **Confirm button**: I understand, enable
|
||||
- **Cancel button**: Cancel
|
||||
|
||||
**This checkbox is unchecked by default.** This is an important fork in the road:
|
||||
|
||||
| Your choice | Effect | Where your data is right now |
|
||||
|---|---|---|
|
||||
| **Unchecked** (default) | Only switches the tag. **Only official sessions created after enabling** land in the `custom` shared drawer | Your official sessions from **before** enabling keep the `openai` tag, stay exactly where they were, still in `~/.codex/sessions/` |
|
||||
| **Checked** | In addition to switching the tag, also migrates your **existing official sessions** from the `openai` drawer into the `custom` drawer | After being **copied to backup**, the old sessions' tag is rewritten to `custom`; the original data is covered by the backup |
|
||||
|
||||
> **If you want "my earlier official sessions to appear in the unified list too," you must opt in by checking this box.** Otherwise you'll run into "scenario A" in the reference table below—the old sessions look "gone," when in fact they're just sitting in the original drawer.
|
||||
|
||||
Click "Cancel" or click outside the dialog: the switch flips straight back to off and nothing happens.
|
||||
Click "I understand, enable": the switch is saved as on, and CC Switch persists the configuration in the background (and runs the migration if you checked it).
|
||||
|
||||
### Step 3 (only if you checked migration): how migration runs + data safety
|
||||
|
||||
If you check "Also migrate existing official session history," CC Switch runs this procedure on your existing official sessions:
|
||||
|
||||
```text
|
||||
For each official (openai tag) session file:
|
||||
① First copy the original file untouched into the backup directory <- data now has its first safety net
|
||||
② Using "write a temp file -> replace the whole thing" atomic style,
|
||||
change only the model_provider in the session_meta line at the header
|
||||
from "openai" to "custom" <- not a single byte of the conversation body is touched
|
||||
③ Update the index database state_5.sqlite to switch the tag in the same transaction
|
||||
```
|
||||
|
||||
- **Backup location**: `~/.cc-switch/backups/codex-official-history-unify-v1/<timestamp>/`. Each migration produces one timestamped "generation directory," containing `jsonl/` (session copies), `state/` (index DB copy), and `meta.json` (recording which Codex directory this migration belongs to).
|
||||
- **What's changed**: only the value of the single field `model_provider`. Your conversation content, reasoning content, and all body text are **kept exactly as is**.
|
||||
- **What's deleted**: **nothing**. The backup is a "copy," the rewrite is an "atomic replacement of the same file," and at no point is any session or index deleted. The file is complete at every moment (either the old content or the new content, never empty or half-written).
|
||||
|
||||
After a successful migration, these existing official sessions show up in the unified list. **At this moment your data is**: ① the original copy in the backup directory; ② in the active file, only the classification tag changed, the content intact.
|
||||
|
||||
> **Note**: enabling and migration themselves **do not pop a success toast**. Migration runs as a side task on the backend during save; in the UI you'll only see the switch turn on. So "I didn't see a migration-success popup" is normal and does not mean failure.
|
||||
|
||||
---
|
||||
|
||||
## What happens when you disable it: step by step
|
||||
|
||||
### Step 1: Flip the switch from on to off -> probe for backups -> a confirmation dialog pops up
|
||||
|
||||
When disabling, CC Switch **first spends a moment probing whether there's a migration backup**, then pops up a confirmation dialog (so the disable dialog has a slight delay, which is normal). The text reads as follows (verbatim):
|
||||
|
||||
- **Title**: Turn off unified session history
|
||||
- **Body**:
|
||||
|
||||
> After turning this off, the official subscription and third-party providers return to separate history lists. Sessions created while it was on cannot be attributed to a provider, so they stay in the third-party history and the official subscription will not see them.
|
||||
|
||||
- **Checkbox** (shown conditionally): Restore the official sessions migrated at enable time back to the official history (exact restore from backup)
|
||||
- **Confirm button**: Turn off
|
||||
- **Cancel button**: Cancel
|
||||
|
||||
> **Key point**: the body says the official subscription **will not see them**—**won't see**, not **delete**. The new sessions you chatted during the unified period are still fully present in the `custom` drawer; after disabling, the official side simply won't see them.
|
||||
|
||||
**This restore checkbox is checked by default.** In other words, the default behavior is "restore the official sessions you migrated in back to the official history at the same time you disable." You only need to keep it checked and click "Turn off."
|
||||
|
||||
If the checkbox **doesn't appear**, the system has determined there's no backup that needs restoring (either you never checked migration, or no backup was found)—in that case your existing official sessions were never touched, and turning off the switch returns them to the `openai` drawer on their own.
|
||||
|
||||
### Step 2: How restore runs (precise flip-back per the backup ledger)
|
||||
|
||||
If you keep the box checked and click "Turn off," CC Switch's restore flow goes like this:
|
||||
|
||||
```text
|
||||
① First copy the current state once more into a separate restore-backup directory
|
||||
~/.cc-switch/backups/codex-official-history-unify-restore-v1/<timestamp>/
|
||||
(restore itself backs up first, so restore won't lose data either)
|
||||
② Comb through all migration backup generations, find the session ids "whose tag was originally openai," and assemble a "ledger"
|
||||
③ Only for sessions that are [both in the ledger AND currently still custom], change the tag back to "openai"
|
||||
```
|
||||
|
||||
Note the **dual condition** in step ③—it must be in the ledger (proving it really was migrated from the official side) AND currently still `custom` (showing you haven't manually changed it). Only when both conditions hold does it get flipped back. This guarantees the restore is both precise and free of collateral damage.
|
||||
|
||||
**At this moment your data is**: the migrated-back official sessions have their tag changed back to `openai` and reappear in the official list; meanwhile both the migration backup and the restore backup copies are still on disk.
|
||||
|
||||
### Step 3: Read the toast, confirm the result
|
||||
|
||||
Only the "disable + check restore" path pops a result toast. The toasts you may see (verbatim):
|
||||
|
||||
| Toast you see | Meaning |
|
||||
|---|---|
|
||||
| **Official session history restored from backup ({{files}} session files, {{rows}} index rows)** | Restore succeeded. `{{files}}` / `{{rows}}` show the actual numbers |
|
||||
| **No restorable migration backup for the current Codex directory** | Nothing to restore (**does not mean data is lost**, see scenario E in the reference table) |
|
||||
| **Unified session history was re-enabled; restore skipped** | You turned the switch back on while restore was queued, so the system deliberately abandoned the restore (see scenario F) |
|
||||
| **Failed to restore official session history, please try again** | The restore process errored; just retry, the data is not corrupted |
|
||||
| **Save failed, please try again** | The disable save itself failed; in this case **restore is never triggered** and the switch flips back to its original position |
|
||||
|
||||
> **A thoughtful safety design**: if the "disable the switch" save fails, CC Switch **never runs the restore**. Otherwise you'd end up in a torn state of "switch still on, but sessions flipped back to the openai bucket." When the save fails, the switch **automatically flips back to its original position**, so you won't be stuck in a fake state of "looks off but didn't actually save."
|
||||
|
||||
---
|
||||
|
||||
## "I feel like my sessions are gone?" symptom reference table
|
||||
|
||||
The six scenarios below are the situations where users most easily believe "sessions are gone." **The truth in every one is: the data is intact, it just moved drawers or is temporarily out of sight.** Use this table to locate your symptom first, then read the detailed explanation below.
|
||||
|
||||
| Scenario | What you see | The data truth | One-line fix |
|
||||
|---|---|---|---|
|
||||
| **A** Didn't check migration | Old official sessions not in the unified list | All present, still carry the `openai` tag | Re-enable and check migration, or turn off the switch |
|
||||
| **B** Cross-provider resume fails | Can't resume / errors out | Files intact, the ciphertext just can't be decrypted across backends | Resume on the original provider; to only read content, read the jsonl directly |
|
||||
| **C** Proxy takeover / injection refused | No migration and no restore | Migration was safely skipped, files untouched | Exit takeover -> restart and retry; or just turn off the switch |
|
||||
| **D** New sessions didn't return to official after restore | New sessions from the unified period aren't on the official side | They're in the `custom` drawer, untouched by design | Switch to a third-party provider to see them |
|
||||
| **E** Toast "no restorable backup" | Restore "failed" | Usually nothing was ever migrated, sessions are in the original drawer | Turn off the switch and the official sessions reappear automatically |
|
||||
| **F** Toast "switch was re-enabled, restore skipped" | Restore refused | Prevents a torn data state, nothing was changed | Fully turn off the switch first, then restore |
|
||||
|
||||
### Scenario A: You enabled the switch but didn't check migration -> old official sessions "disappear"
|
||||
|
||||
**Symptom**: you turned on the unified switch, but didn't check "Also migrate existing official session history" in the enable dialog (it's unchecked by default). After enabling, your earlier official sessions seem to be gone from the list.
|
||||
|
||||
**The truth**: 100% of your data is present, not a single line moved. The switch only takes effect on official sessions "created after enabling"; your official sessions from **before** enabling still carry the `openai` tag and sit untouched in `~/.codex/sessions/`. You're now on the `custom` drawer, so naturally you can't see the old sessions left in the `openai` drawer—that's the entire reason for the "apparent disappearance."
|
||||
|
||||
**What to do** (pick either):
|
||||
1. **Re-enable the switch and check "Also migrate existing official session history,"** which moves the old sessions to the `custom` drawer and they immediately appear in the unified list (automatic backup before the rewrite).
|
||||
2. **Or simply turn off the unified switch**, the official side runs on the `openai` drawer again, and the old sessions reappear right where they were.
|
||||
|
||||
### Scenario B: Cross-provider resume of an old session fails -> you think "this session is broken / gone"
|
||||
|
||||
**Symptom**: after unification, the list shows an old session chatted with "another provider." You switch to your current provider and click "Resume," but it errors out or can't connect.
|
||||
|
||||
**The truth**: the session file is intact; what's lost is not data, it's "cross-backend decryption ability." A Codex session stores an encrypted block of reasoning content `encrypted_content`, and **this ciphertext can only be decrypted by the backend that originally generated it**. Using provider B to resume a session generated by provider A means B can't decrypt A's ciphertext -> resume fails. This is **a design limitation of upstream Codex (by design)** and has nothing to do with whether CC Switch touched the file. The text content of the session is readable at any time.
|
||||
|
||||
> This is the **only "looks like a real problem" genuine exception** in this whole guide—but note: it just means **you can't resume (can't generate a new turn)**, and **the original file is still fully present**, the conversation text readable at any time.
|
||||
|
||||
**What to do**:
|
||||
- **Resume with "the provider that originally created this session,"** so it can decrypt normally and connect.
|
||||
- Just want to read the history without continuing? Read that session's `.jsonl` file directly (commands at the end).
|
||||
- Rule of thumb: **cross-provider is better suited to "starting a new session"; resume old sessions on their original provider whenever possible.**
|
||||
|
||||
### Scenario C: You enabled the switch and checked migration, but migration was silently skipped -> you think "migration lost the sessions"
|
||||
|
||||
**Symptom**: you enabled the switch and checked migration, but the old official sessions neither entered the unified list nor could be restored when you turned the switch off (or the restore checkbox didn't even appear in the disable dialog, see scenario E). You suspect migration lost the sessions during the process.
|
||||
|
||||
**The truth**: migration **never ran**, so it couldn't have lost anything—not a single character of your sessions was changed. CC Switch has a safety gate before migration: it checks whether Codex's live config (`~/.codex/config.toml`) is **actually** routed to the shared `custom` drawer right now, and only migrates if the routing truly went there. The following two situations are judged "not yet unified" (internal reason code `live_not_unified`), so CC Switch **deliberately skips the migration, preserves your switch and migration intent, and migrates later once the conditions are met**:
|
||||
|
||||
- **During proxy takeover**: CC Switch's proxy has taken over the live config, and the live config during takeover doesn't carry the unified routing marker.
|
||||
- **Injection refused**: your `config.toml` already has a manually specified `model_provider`, or there's already a differently-shaped `[model_providers.custom]` table (possibly with a third-party address). To avoid incorrectly routing official traffic to a third-party backend, CC Switch would rather not inject and not migrate.
|
||||
|
||||
Skipping migration = touching no session files. **No migration means nothing moved, so there's nothing to lose.** This is "safe deferral," not "failure with data loss."
|
||||
|
||||
**What to do**:
|
||||
- Exit proxy takeover -> **restart CC Switch**: on startup it automatically retries migration (your migration intent is preserved the whole time).
|
||||
- Check `~/.codex/config.toml`: if there's a conflicting route you wrote by hand, clean up the conflict before enabling the switch.
|
||||
- If you'd rather not bother: just turn off the switch, the official sessions still display normally on the `openai` drawer, completely intact.
|
||||
|
||||
### Scenario D: You turned off the switch and restored, but "the new sessions chatted during the unified period" didn't return to official -> you think "the new sessions are gone"
|
||||
|
||||
**Symptom**: during the unified period, you chatted a few more new sessions with the official account. Later you turned off the switch, checked restore, and after restoring you find those new sessions didn't return to the official drawer.
|
||||
|
||||
**The truth**: this is **intentional** design; the new sessions are perfectly fine in the `custom` drawer, visible and resumable. Restore is based on "the backup ledger from migration time"—**only sessions that were originally migrated in from the `openai` drawer** are recorded in the backup and get precisely flipped back to `openai`. The sessions you **created during the unified period** are in no backup ledger; and after unification both official and third-party use the `custom` tag, so **CC Switch can't tell whether a new session was chatted with the official account or a third-party**. To avoid wrongly stuffing third-party sessions into the official history, the product decision is: these new sessions all stay in the `custom` (third-party) history and are never moved automatically. The disable dialog's text says this explicitly too—"Sessions created while it was on cannot be attributed to a provider, so they stay in the third-party history."
|
||||
|
||||
**What to do**:
|
||||
- Switch to any third-party provider (the `custom` drawer) to see these sessions in the history list.
|
||||
- To read content, read the `.jsonl` directly; to resume, follow scenario B's rule (go back to the backend that originally generated it).
|
||||
- If you really want to manually return **one specific** session to official: there's currently no automatic button (deliberately omitted, to avoid misjudging the direction). Advanced users can, **after backing up** that file first, manually change `model_provider` in the `session_meta` of the first line of its `.jsonl` from `custom` back to `openai` (an advanced operation; always make a copy before editing).
|
||||
|
||||
### Scenario E: Restore toast "No restorable migration backup for the current Codex directory" -> you think "restore failed = data is gone"
|
||||
|
||||
**Symptom**: you checked restore when turning off the switch, and got the toast "No restorable migration backup for the current Codex directory." You panic: restore failed, is the data completely gone?
|
||||
|
||||
**The truth**: "nothing to restore" ≠ "data is lost." On the contrary, it's usually because **there was no migration that needed restoring**. Common reasons:
|
||||
|
||||
- **You never checked "migrate existing official sessions" in the first place**: with no migration, there's naturally no migration backup and no sessions to flip back. Your old official sessions have been in the `openai` drawer all along and reappear after you turn off the switch (same as scenario A). (In this case, the disable dialog may **not even show the restore checkbox**—because the system can't find any backup.)
|
||||
- **You've already restored once**: the session tags have all been flipped back to `openai`, so clicking again naturally finds "no targets still in custom to restore"—this is **idempotent protection, not failure**.
|
||||
- **You switched Codex directories**: restore only recognizes the backup ledger belonging to the **current** directory; switch directories and it can't find the old directory's ledger. Just switch the directory back.
|
||||
|
||||
In all three cases, no session was deleted.
|
||||
|
||||
**What to do**: use the end-of-guide commands to count the total session files in `~/.codex/sessions/` and confirm the files are all there; then check whether `~/.cc-switch/backups/` contains a `codex-official-history-unify-v1` directory—if even this directory is absent, you never triggered a migration and the sessions have been in their original drawer all along.
|
||||
|
||||
### Scenario F: Restore refused, toast "Unified session history was re-enabled; restore skipped"
|
||||
|
||||
**Symptom**: you turned off the switch -> checked restore -> but you were quick and immediately turned the switch back on, then saw the toast "Unified session history was re-enabled; restore skipped."
|
||||
|
||||
**The truth**: this is a safeguard against putting your data into a "torn" state, and again no sessions are lost. The restore action is "flip session tags from `custom` back to `openai`," but if the switch is on again at this moment, the live config is routing to `custom`—flipping history back to `openai` on one side while new sessions land in `custom` on the other would artificially tear sessions in two. So when CC Switch detects "the switch is on again," it **deliberately abandons this restore and changes nothing**. Sessions stay as they are, with no deletion or corruption.
|
||||
|
||||
**What to do**: to truly restore, **turn the switch off and keep it off** (don't immediately turn it back on), then do disable + check restore; to keep things unified, don't restore, and let the sessions stay in the `custom` shared drawer for normal use.
|
||||
|
||||
**The overriding principle: CC Switch's unify / migrate / restore only ever changes a single tag field in a session, and automatically backs up before every rewrite. It never deletes your conversations. Out of sight ≠ gone—look in the other drawer, or use the commands below to confirm with your own eyes.**
|
||||
|
||||
---
|
||||
|
||||
## Verify by hand: your session files are still on disk (the most important section)
|
||||
|
||||
No amount of text beats seeing it for yourself. Below are the **real paths** (taken from the CC Switch source) and how to view session files and backup directories on different systems. **The whole process is read-only and changes nothing; you're strongly encouraged to try it by hand.**
|
||||
|
||||
### The simplest way: open it directly in a file manager (no command line at all)
|
||||
|
||||
- **macOS (Finder)**: press `Cmd + Shift + G`, paste `~/.codex/sessions` and hit Enter to see a pile of `.jsonl` session files and their modification times; for the backup directory paste `~/.cc-switch/backups`.
|
||||
- **Windows (File Explorer)**: paste `%USERPROFILE%\.codex\sessions` into the address bar and hit Enter to see the session folders and the `.jsonl` files inside; for the backup directory paste `%USERPROFILE%\.cc-switch\backups`.
|
||||
|
||||
**As long as you can see a batch of `.jsonl` files here, that proves your session data is intact on disk.** The file count and modification times are more intuitive than any amount of text.
|
||||
|
||||
### Where exactly your session / history files live
|
||||
|
||||
| Content | Real path | Notes |
|
||||
|---|---|---|
|
||||
| **Session body (the core)** | `~/.codex/sessions/` (includes date-based subdirectories, recursive) | One `.jsonl` text file per session—**this is your conversation content** |
|
||||
| **Archived sessions** | `~/.codex/archived_sessions/` | Also `.jsonl` |
|
||||
| **Session index database** | `~/.codex/state_5.sqlite` | The `model_provider` column of the `threads` table is the "drawer tag"—**this is the actual classification source the resume list reads** |
|
||||
| **Migration backup** (auto-created when migration is enabled) | `~/.cc-switch/backups/codex-official-history-unify-v1/<timestamp>/` | Contains `jsonl/`, `state/`, `meta.json` |
|
||||
| **Restore backup** (auto-created when you restore) | `~/.cc-switch/backups/codex-official-history-unify-restore-v1/<timestamp>/` | A safety copy taken before restore |
|
||||
|
||||
> **Note**: if you've changed the Codex directory in CC Switch, or set `sqlite_home` in `config.toml`, replace `~/.codex` above with your actual directory. Below, `~` = your user home directory.
|
||||
|
||||
### macOS / Linux commands
|
||||
|
||||
**1. Count the total number of session files (this is the hard evidence of "nothing lost")**
|
||||
|
||||
```bash
|
||||
# Count the total number of session files -- as long as this number matches your expectation, the data is all there
|
||||
find ~/.codex/sessions ~/.codex/archived_sessions -name '*.jsonl' 2>/dev/null | wc -l
|
||||
|
||||
# Show the 10 most recently modified session files
|
||||
find ~/.codex/sessions -name '*.jsonl' 2>/dev/null -print0 \
|
||||
| xargs -0 ls -lt 2>/dev/null | head -10
|
||||
```
|
||||
|
||||
**2. (Auxiliary) See how many sessions are in each "drawer"**
|
||||
|
||||
```bash
|
||||
# Number of session files in the official drawer (openai)
|
||||
grep -rlE '"model_provider"[[:space:]]*:[[:space:]]*"openai"' ~/.codex/sessions 2>/dev/null | wc -l
|
||||
|
||||
# Number of session files in the unified drawer (custom)
|
||||
grep -rlE '"model_provider"[[:space:]]*:[[:space:]]*"custom"' ~/.codex/sessions 2>/dev/null | wc -l
|
||||
|
||||
# See the tag distribution at a glance
|
||||
grep -rhoE '"model_provider"[[:space:]]*:[[:space:]]*"[^"]*"' ~/.codex/sessions 2>/dev/null | sort | uniq -c
|
||||
```
|
||||
|
||||
> **Important note, don't let this step scare you**: **early versions of Codex did not write the `model_provider` field into the `.jsonl`**, so these old official sessions **can't be counted** by the grep above—but they're still classified as `openai` in the index database `state_5.sqlite` and still show up in the resume list. So **judge "nothing lost" by the total file count from step 1**—the per-drawer grep is only there to help you understand the classification, and counting fewer than the total file count is **completely normal** and never means "a batch was lost."
|
||||
|
||||
**3. (Advanced) Query the index database `state_5.sqlite`—the classification the resume list actually reads**
|
||||
|
||||
```bash
|
||||
# Requires sqlite3 to be installed; skip if you don't have it
|
||||
sqlite3 ~/.codex/state_5.sqlite \
|
||||
"SELECT COALESCE(model_provider,'<empty>'), COUNT(*) FROM threads GROUP BY 1;"
|
||||
```
|
||||
|
||||
> This `threads` table is the actual classification source Codex's resume list reads; the `openai` row count ≈ the number of sessions you can see in your official drawer. It may not match step 2's jsonl grep—the reason is exactly what's described above: "old sessions don't write the jsonl field, but they're still openai in the index database." A mismatch between the two is not an anomaly.
|
||||
|
||||
**4. Read the content of a specific session directly (confirm the conversation text is still there)**
|
||||
|
||||
```bash
|
||||
# Replace <filename> with one of the .jsonl paths listed by ls above
|
||||
python3 -m json.tool < "<filename>.jsonl" 2>/dev/null | head -50
|
||||
|
||||
# Or just open it in an editor (plain text)
|
||||
open -e "<filename>.jsonl" # macOS
|
||||
```
|
||||
|
||||
**5. Look at CC Switch's backup directory (proof that a copy was kept before migration / restore)**
|
||||
|
||||
```bash
|
||||
ls -la ~/.cc-switch/backups/codex-official-history-unify-v1/ 2>/dev/null
|
||||
ls -la ~/.cc-switch/backups/codex-official-history-unify-restore-v1/ 2>/dev/null
|
||||
```
|
||||
|
||||
### Windows commands (PowerShell)
|
||||
|
||||
The session directory is usually at `C:\Users\<your username>\.codex\`, and backups at `C:\Users\<your username>\.cc-switch\backups\`.
|
||||
|
||||
```powershell
|
||||
# 1. Total number of session files (hard evidence of "nothing lost")
|
||||
(Get-ChildItem "$env:USERPROFILE\.codex\sessions","$env:USERPROFILE\.codex\archived_sessions" -Recurse -Filter *.jsonl -ErrorAction SilentlyContinue).Count
|
||||
|
||||
# 2. The 10 most recently modified sessions
|
||||
Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
|
||||
Sort-Object LastWriteTime -Descending | Select-Object -First 10 FullName,LastWriteTime
|
||||
|
||||
# 3. (Auxiliary) How many session files in the official (openai) / unified (custom) drawers
|
||||
(Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
|
||||
Select-String -Pattern 'model_provider"\s*:\s*"openai"' -List).Count
|
||||
(Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
|
||||
Select-String -Pattern 'model_provider"\s*:\s*"custom"' -List).Count
|
||||
|
||||
# 4. Look at the backup directories
|
||||
Get-ChildItem "$env:USERPROFILE\.cc-switch\backups\codex-official-history-unify-v1" -ErrorAction SilentlyContinue
|
||||
Get-ChildItem "$env:USERPROFILE\.cc-switch\backups\codex-official-history-unify-restore-v1" -ErrorAction SilentlyContinue
|
||||
```
|
||||
|
||||
> Same reminder: the step-3 grep counting **fewer** than the total file count is normal (old sessions don't write that field); judge "nothing lost" by the **total file count** from step 1.
|
||||
|
||||
---
|
||||
|
||||
## Advanced mechanism appendix (for users who want to truly understand how it works)
|
||||
|
||||
### 1. The bucketing mechanism (the essence of the drawers)
|
||||
|
||||
Codex's resume / history list filters by the currently active `model_provider` id with **exact string matching**. The **first line** of a session's `.jsonl` file is a `type:"session_meta"` record whose `payload.model_provider` is the drawer that session belongs to (`grep -rl` counts a file as long as the tag appears once anywhere in it, so no line-by-line parsing is needed; sessions from old versions that didn't write the field can't be counted). What actually drives the resume list is the `threads.model_provider` column of the index database `state_5.sqlite`. When `config.toml` has no explicit `model_provider`, the official subscription falls into the built-in default id `openai`; all of CC Switch's third-party providers uniformly use `custom`.
|
||||
|
||||
### 2. What the switch does (injection, lives only in live)
|
||||
|
||||
When enabled, CC Switch injects the following into the official live `config.toml`:
|
||||
|
||||
```toml
|
||||
model_provider = "custom"
|
||||
|
||||
[model_providers.custom]
|
||||
name = "OpenAI"
|
||||
requires_openai_auth = true
|
||||
supports_websockets = true
|
||||
wire_api = "responses"
|
||||
```
|
||||
|
||||
Every field has a purpose: `requires_openai_auth = true` keeps authentication going through the ChatGPT login in `auth.json`, with the base_url defaulting back to the official Codex backend; `name = "OpenAI"` lets Codex's official feature gates (web search, remote compaction, etc.) keep matching; `supports_websockets = true` restores the capability that custom entries lose by default; `wire_api = "responses"` uses the official responses protocol. **The net effect is: authentication is unchanged, only the bucket name changed.**
|
||||
|
||||
**Key invariant: this injection can only exist in the live `config.toml`, and is never written into the database's stored configuration.** When you switch away from the official provider and write live back to the database, CC Switch strips this injection precisely (it strips only when the shape exactly matches the injected artifact; a third-party-customized `custom` table is kept as is). Precisely because of this, "turning off the switch + switching once" fully restores live, and the database always holds your original clean official configuration—this is the cornerstone of the whole switch's reversibility.
|
||||
|
||||
### 3. The two refusal gates for injection (corresponding to scenario C)
|
||||
|
||||
- `config.toml` already has an explicit `model_provider` -> don't override the user's route;
|
||||
- A differently-shaped `[model_providers.custom]` table already exists (possibly with a third-party `base_url`) -> refuse injection, otherwise ChatGPT OAuth traffic would be routed to the wrong backend.
|
||||
|
||||
When injection is refused, live is not unified, and the migration gate (checking whether live's `model_provider` equals `custom` after trim) judges `live_not_unified` -> skip migration, preserve intent, and do it later on the next startup retry. This is "safe deferral," not "failure with data loss."
|
||||
|
||||
### 4. The three session classes (which determine the migration / restore boundary)
|
||||
|
||||
- **Class A**: existing official sessions migrated in at enable time—the backup is the ledger, and they can be precisely restored back to `openai`;
|
||||
- **Class B**: created during the unified period—in no backup, and official / third-party can't be distinguished, so they're **never moved automatically** (stay `custom`);
|
||||
- **Class C**: pure third-party history from before enabling—never touched.
|
||||
|
||||
### 5. The safety of migration / restore (data is never truly deleted; where the guarantee comes from)
|
||||
|
||||
Four layers of design jointly guarantee that under **all paths, normal and abnormal**, the original session data is never truly deleted.
|
||||
|
||||
- **Only change the field, never the body**: migration / restore only switch the `model_provider` value in session metadata between `openai` and `custom`; conversation content, `response_item`, and `encrypted_content` are all kept exactly as is.
|
||||
- **Always copy a backup before a rewrite**: jsonl uses file copy, the state DB uses a full SQLite copy, both stored in a timestamped generation directory. Migration backups live in `codex-official-history-unify-v1/`, restore backups in the separate `codex-official-history-unify-restore-v1/`—the two are kept apart to keep the ledger clean.
|
||||
- **Only move, never delete + atomic writes**: all jsonl rewrites go through "temp file + whole-file replacement," and the state DB goes through a transactional `UPDATE`, with no deletion of any session or index at any point. The file is complete at every moment.
|
||||
- **Pessimistic skip + idempotent and retryable**: when buckets are inconsistent (`live_not_unified`), it would rather not migrate; a single process lock serializes migration and restore to avoid "startup retry / post-save background task / disable-time restore" concurrently rewriting the same batch of files in both directions; the completion marker is bound to the Codex directory and written conditionally to prevent missed migrations; restore uses the "in the ledger + currently still custom" dual condition to prevent wrong changes. Restore scans the union of all backup generations, so even after many switch cycles it can still restore early-migrated sessions; a repeated restore returns `nothing_to_restore`, which is idempotent protection rather than failure.
|
||||
|
||||
### 6. Cross-backend encrypted_content (corresponding to scenario B)
|
||||
|
||||
The reasoning ciphertext inside a session can only be decrypted by the backend that generated it; upstream Codex by design does not support cross-backend decryption. This is the root cause of "resume failure" and has nothing to do with file integrity—the session `.jsonl` sits fully on disk and `encrypted_content` is intact too. Switching back to the original provider to resume, or starting a new session, both work fine.
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [Keep Codex Remote Control and Official Plugins While Using Third-Party APIs: CC Switch Setup Guide](./codex-official-auth-preservation-guide-en.md)
|
||||
- [Using DeepSeek-Style Chat APIs in Codex: CC Switch Local Routing Guide](./codex-deepseek-routing-guide-en.md)
|
||||
- The "Codex App Enhancements" section in the CC Switch user manual
|
||||
|
||||
---
|
||||
|
||||
**One last word for you**: what you see as "sessions disappeared / resume failed" is essentially **the session being moved to another history list (drawer), or the other backend being unable to decrypt the old reasoning content**; the files always sit untouched in `~/.codex/sessions/` (and `state_5.sqlite`). Checking "restore from backup" when you turn off the switch precisely flips the official sessions you migrated in back to the official list; and even if you don't restore, both the original `.jsonl` files and the backup copies under `~/.cc-switch/backups/codex-official-history-unify-*/` are all still there—**the data is never truly lost.**
|
||||
@@ -0,0 +1,467 @@
|
||||
# Codex セッション履歴の統一: 機能紹介と利用ガイド（CC Switch）
|
||||
|
||||
> 対象バージョン: CC Switch v3.16.x 以降。本記事は現在のコードをもとに整理しており、コマンドとパスはご自身で検証できます。例示には匿名化したデータを使用しており、実際のセッション内容や API Key は含まれていません。
|
||||
|
||||
## この機能とは何か
|
||||
|
||||
「Codex セッション履歴を統一」は、CC Switch v3.16.x が Codex 向けに新しく追加したスイッチです。その場所は **設定 → 一般 → 「Codex アプリ拡張」グループ** の中にあります（「Codex アプリ拡張」はこのグループの見出しで、スイッチ自体は「Codex セッション履歴を統一」という名前です）。オンにすると、**公式サブスクリプション（ChatGPT ログイン / OpenAI API Key）のセッションが、CC Switch で管理するすべてのサードパーティプロバイダーのセッションと同じ履歴 / セッション再開リストに表示されます**——もう、互いに見えない 2 つのリストに分断されることはありません。
|
||||
|
||||
## どんな問題を解決するのか
|
||||
|
||||
Codex は「プロバイダーのラベル」（`model_provider` というフィールド）でセッションを分類しており、しかも **セッション再開 / 履歴リストには、現在アクティブなプロバイダーと同じラベルのセッションしか表示しません**。そのため、セッションは自然と 2 つの「引き出し」に分けられてしまいます。
|
||||
|
||||
- 公式サブスクリプションのセッションは、Codex 内蔵の **`openai`** ラベルに分類されます。
|
||||
- CC Switch が管理するすべてのサードパーティプロバイダーは、**`custom`** ラベルに分類されます。
|
||||
|
||||
2 つの引き出しは互いに見えません。**公式とサードパーティを頻繁に切り替えている** 場合、この分断に遭遇します——「さっき公式で話したセッションが、サードパーティに切り替えたら履歴リストから消えた」というように。実際にはなくなっておらず、別の引き出しに分けられただけです。この分断は、セッションが失われたと誤解させやすいうえに、すべてのセッションを 1 か所でまとめて振り返ったり再開したりするのにも不便です。
|
||||
|
||||
**このスイッチは、まさにこの分断を解消するためのものです**。公式サブスクリプションも `custom` ラベルで動作させることで、公式とサードパーティのセッションが同じリストに統合され、探すのも再開するのも 1 か所で済みます。
|
||||
|
||||
> ✅ **本記事全体を貫く重要な前提を、まず覚えておいてください**: この機能（統一 / 移行 / 復元）は **常にセッション記録内のあの分類ラベル `model_provider` 1 つだけを書き換え、しかも毎回書き換える前に自動で元ファイルをバックアップします**。あなたの会話を 1 文たりとも削除・消去・上書きすることはありません。ですので、本記事の後半で「あるセッションが見えなくなった」とあっても、そのほとんどは「別の引き出しに分けられた」だけであり、「データが消えた」わけではありません——本当に心配なときは、[症状対照表](#会話が消えた症状対照表) と [自分の目でファイルが残っていることを確認する](#自分の目で確認-セッションファイルはディスク上に残っている最重要セクション) を直接ご覧ください。
|
||||
|
||||
## 動作原理（一言版）
|
||||
|
||||
これを **2 つの引き出し + 自動バックアップ** と考えてください。
|
||||
|
||||
- デフォルトでは、公式セッションは `openai` の引き出しに、サードパーティのセッションは `custom` の引き出しにあり、互いに見えません。
|
||||
- スイッチは **公式も `custom` の引き出しを使うように** させ、2 つの引き出しを 1 つの共有リストに統合します。
|
||||
- **既存の公式の古いセッション** も一緒に共有の引き出しへ「移す」ことを選べます（この操作を **移行** と呼びます。任意で、能動的にチェックを入れる必要があります）。そして **いかなる移動の前にも、まずコピーをバックアップ** するので、プロセス全体が **可逆** です。
|
||||
- **認証はまったく影響を受けません**——公式サブスクリプションは引き続きあなたの ChatGPT ログインを使い、引き続き公式バックエンドを経由します。変わるのはセッションの分類ラベルだけです。
|
||||
|
||||
完全な仕組み（何が注入されるのか、なぜ可逆なのか、移行 / 復元がどうやってデータ消失を防ぐのか）は、後述の [コア・メンタルモデル](#コアメンタルモデル-2-つの引き出し--自動バックアップ) と巻末の [応用原理付録](#応用原理付録仕組みを本当に理解したい人向け) をご覧ください。
|
||||
|
||||
## 使い方（クイック）
|
||||
|
||||
1. **有効化**: 設定 → 一般 → Codex アプリ拡張 → 「Codex セッション履歴を統一」をオン → ダイアログで「既存の公式セッション履歴も移行する」にチェックを入れるか決める（**以前** の公式セッションも統一リストに合流させたいならチェックを入れる。今後だけ統一したいならチェックを入れない）→ 確定。詳しくは [有効化したとき何が起きるか](#有効化したとき何が起きるか-ステップ別解説) を参照。
|
||||
2. **無効化**: 同じスイッチをオフにする → ダイアログで「バックアップから正確に復元する」のチェックを保持（デフォルトでチェック済み）→ 確定すれば、移行した公式セッションを正確に公式リストへ戻せます。詳しくは [無効化したとき何が起きるか](#無効化したとき何が起きるか-ステップ別解説) を参照。
|
||||
3. **セッションが消えた気がする？** 慌てずに [症状対照表](#会話が消えた症状対照表) へ進んで症状から原因を特定し、[自分の目で確認](#自分の目で確認-セッションファイルはディスク上に残っている最重要セクション) セクションのコマンドで、ファイルがすべて残っていることを自分の目で確かめてください。
|
||||
|
||||
---
|
||||
|
||||
## コア・メンタルモデル: 2 つの引き出し + 自動バックアップ
|
||||
|
||||
この機能を理解するには、**引き出し** と **バックアップ** の 2 つだけ覚えれば十分です。
|
||||
|
||||
### 引き出し: Codex はどうやってセッションを分類するか
|
||||
|
||||
Codex セッションを 1 つ開くたびに、Codex はセッションファイルの先頭に `model_provider` というラベルを記録し、「このセッションはどのプロバイダーで話したか」を示します。Codex の **セッション再開 / 履歴リストは、現在アクティブなこのラベルで正確にフィルタリングされます**——「今あなたが使っているプロバイダー」と同じラベルのセッションだけが表示されます。
|
||||
|
||||
- 公式サブスクリプション（ChatGPT ログイン / OpenAI API Key）のセッションのラベルは、内蔵の **`openai`** です。
|
||||
- CC Switch が管理するすべてのサードパーティプロバイダーは、一律にラベル **`custom`** を使います。
|
||||
|
||||
そのためデフォルトでは、公式セッションとサードパーティセッションは生まれつき互いに見えません——2 つの異なる引き出しにあるからです。これは **Codex 自身の設計** であり、CC Switch が何かをなくしたわけではありません。
|
||||
|
||||
```text
|
||||
デフォルト状態（統一スイッチをオンにしていない）：
|
||||
┌──────────────────────┐ ┌──────────────────────────────────┐
|
||||
│ openai の引き出し │ │ custom の引き出し │
|
||||
│ （公式セッション） │ │ （サードパーティのセッション） │
|
||||
└──────────────────────┘ └──────────────────────────────────┘
|
||||
▲ ▲
|
||||
公式のときは サードパーティのときは
|
||||
こちらだけ表示 こちらだけ表示
|
||||
|
||||
（2 つの引き出しは互いに見えない）
|
||||
```
|
||||
|
||||
**「Codex セッション履歴を統一」スイッチがすることは、公式サブスクリプションも `custom` ラベルで動作させ、2 つの引き出しを 1 つに統合することです**。その結果、公式セッションとサードパーティセッションが同じセッション再開リストに表示されます。注意してほしいのは、**認証は変わらない** ということです——あなたの公式サブスクリプションは引き続き ChatGPT ログインを使い、引き続き公式バックエンドを経由します。変わるのはセッションの「分類ラベル」が `openai` から `custom` になることだけです。
|
||||
|
||||
```text
|
||||
統一スイッチをオンにした後：
|
||||
┌────────────────────────────────────────────────┐
|
||||
│ custom 共有引き出し │
|
||||
│ 公式セッション ＋ サードパーティのセッション │
|
||||
│ （同じ履歴 / 再開リストに表示される） │
|
||||
└────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### バックアップ: ラベルを変更する前に必ずコピーを取る
|
||||
|
||||
「引き出しの統合」では、一部の公式セッションのラベルを `openai` から `custom` に変更する必要があります（この操作を **移行** と呼び、これは **任意で、あなたが能動的にチェックを入れる必要があります**）。そして **どの書き換えの前にも、CC Switch はまず元ファイルをそのままコピー** して、ここに保存します。
|
||||
|
||||
```text
|
||||
~/.cc-switch/backups/codex-official-history-unify-v1/<時間スタンプ>/
|
||||
```
|
||||
|
||||
このバックアップが、後の「バックアップから正確に復元する」ための唯一の拠り所です。これによってプロセス全体が **可逆** になります——いつでもスイッチをオフにして、移行した公式セッションを正確に `openai` の引き出しへ戻せます。
|
||||
|
||||
この 2 つの言葉——**引き出し**（セッションは分類が変わるだけ）、**バックアップ**（変更前に必ずコピー）——を覚えておけば、以降の内容はすべて簡単に理解できます。
|
||||
|
||||
---
|
||||
|
||||
## 有効化したとき何が起きるか: ステップ別解説
|
||||
|
||||
### Step 1: スイッチを見つける
|
||||
|
||||
```text
|
||||
設定 → 一般 → Codex アプリ拡張
|
||||
```
|
||||
|
||||
「Codex アプリ拡張」のセクションには 2 行のスイッチがあり、**2 行目**（青い履歴アイコン）が本ガイドの主役です。
|
||||
|
||||
> **Codex セッション履歴を統一**
|
||||
|
||||
その下には説明文があります（逐語）。
|
||||
|
||||
> オンにすると、公式サブスクリプションも共有の custom プロバイダー ID で動作し、公式とサードパーティのセッションが同じ履歴リストに表示されます。既存の公式セッションの移行も選択できます（移行前に自動バックアップ）。オフにする際はバックアップから復元できます。注意：プロバイダーをまたいで古いセッションを再開すると、encrypted_content の推論内容を相手のバックエンドが復号できず、再開に失敗する場合があります。
|
||||
|
||||
> **注意**: この説明文には、すでに 3 つのことが予告されています——同じリストに表示される、移行を選べて自動バックアップされる、プロバイダーをまたいだ再開は「失敗する場合がある」。ここでの「再開に失敗する」は **続けられない、新しいターンを生成できない** という意味であり、「記録が消える」ではありません。これこそ、この後で重点的に解きほぐす核心的な誤解です。
|
||||
|
||||
### Step 2: スイッチをオフからオンに切り替える → 確認ダイアログが表示される
|
||||
|
||||
スイッチをオンに切り替えると、CC Switch は **すぐには保存せず**、まず確認ダイアログを表示します。ダイアログの文言は次のとおりです（逐語）。
|
||||
|
||||
- **タイトル**: Codex セッション履歴を統一
|
||||
- **本文**:
|
||||
|
||||
> オンにすると、公式サブスクリプションとサードパーティが同じセッション履歴リストを共有します。注意：プロバイダーをまたいで古いセッションを再開すると、encrypted_content を相手のバックエンドが復号できず失敗する場合があります。
|
||||
>
|
||||
> 既存の公式セッション履歴を共有リストへ移行することもできます（移行前に ~/.cc-switch/backups へ自動バックアップされ、オフにする際に復元を選択できます）。
|
||||
|
||||
- **チェックボックス**: 既存の公式セッション履歴も移行する
|
||||
- **確認ボタン**: 理解しました、オンにする
|
||||
- **キャンセルボタン**: キャンセル
|
||||
|
||||
**このチェックボックスはデフォルトでオフです。** これは重要な分岐点です。
|
||||
|
||||
| あなたの選択 | 効果 | この時点でデータはどこにあるか |
|
||||
|---|---|---|
|
||||
| **チェックしない**（デフォルト） | ラベルを切り替えるだけ。**オンにした後に新規作成された公式セッションだけ** が `custom` の共有引き出しに入る | あなたが **オンにする前** の公式の古いセッションは、ラベルが `openai` のまま、その場で動かず、引き続き `~/.codex/sessions/` にある |
|
||||
| **チェックする** | ラベルの切り替えに加えて、**既存の公式の古いセッション** も `openai` の引き出しから `custom` の引き出しへ移行する | 古いセッションは **コピーしてバックアップ** された後、ラベルが `custom` に書き換えられる。元データはバックアップで保護される |
|
||||
|
||||
> **「以前の公式セッションも統一リストに表示したい」なら、必ずこのチェックボックスを能動的にオンにしてください。** さもないと、下の対照表の「シナリオ A」に遭遇します——古いセッションが「消えた」ように見えますが、実際は元の引き出しに残っているだけです。
|
||||
|
||||
「キャンセル」を押すか、ダイアログの外側をクリックすると、スイッチはそのままオフ状態に戻り、何も起きません。
|
||||
「理解しました、オンにする」を押すと、スイッチはオンとして保存され、CC Switch はバックグラウンドで設定をディスクに書き込みます（移行にチェックを入れていれば、移行を実行します）。
|
||||
|
||||
### Step 3（移行にチェックを入れた場合のみ）: 移行はどう実行されるか + データの安全性
|
||||
|
||||
「既存の公式セッション履歴も移行する」にチェックを入れた場合、CC Switch はあなたの公式の古いセッションに対して、次の一連の流れを実行します。
|
||||
|
||||
```text
|
||||
公式（openai ラベル）の各セッションファイルについて：
|
||||
① まず元ファイルをそのままバックアップディレクトリへコピー ← データの一次保険ができる
|
||||
② 「一時ファイルに書く → まるごと置換」という原子的な方法で、
|
||||
先頭行 session_meta 内の model_provider を
|
||||
"openai" から "custom" へ変更するだけ ← 会話本文は 1 バイトも触らない
|
||||
③ インデックス DB state_5.sqlite も同じトランザクション内でラベルを変更
|
||||
```
|
||||
|
||||
- **バックアップの場所**: `~/.cc-switch/backups/codex-official-history-unify-v1/<時間スタンプ>/`。移行のたびに、タイムスタンプ付きの「世代ディレクトリ」を生成し、その中に `jsonl/`（セッションのコピー）、`state/`（インデックス DB のコピー）、`meta.json`（この移行がどの Codex ディレクトリに属するかの記録）が含まれます。
|
||||
- **変更するもの**: `model_provider` というフィールドの値だけ。あなたの会話内容、推論内容、すべての本文は **そのまま保持** されます。
|
||||
- **削除するもの**: **何も削除しません**。バックアップは「コピー」、書き換えは「同一ファイルの原子的な置換」であり、全工程でセッションやインデックスを削除する操作は一切ありません。ファイルはいかなる時点でも完全です（古い内容か新しい内容かのどちらかであり、空や中途半端になることは決してありません）。
|
||||
|
||||
移行が成功すると、これらの公式の古いセッションが統一リストに表示されます。**この時点でのあなたのデータ**: ① 元のコピーがバックアップディレクトリにある。② アクティブファイルは分類ラベルが変わっただけで、内容は無傷。
|
||||
|
||||
> **注意**: 有効化と移行そのものは **成功通知を表示しません**。移行は保存時にバックエンドが付随的に実行するもので、UI 上ではスイッチがオン状態になったのが見えるだけです。ですので「移行成功のダイアログが見えなかった」のは正常であり、失敗を意味しません。
|
||||
|
||||
---
|
||||
|
||||
## 無効化したとき何が起きるか: ステップ別解説
|
||||
|
||||
### Step 1: スイッチをオンからオフに切り替える → バックアップを探索 → 確認ダイアログが表示される
|
||||
|
||||
無効化のとき、CC Switch はまず **一瞬かけて移行バックアップの有無を探索** し、それから確認ダイアログを表示します（そのため無効化のダイアログは少しだけ遅延しますが、これは正常です）。文言は次のとおりです（逐語）。
|
||||
|
||||
- **タイトル**: セッション履歴の統一をオフにする
|
||||
- **本文**:
|
||||
|
||||
> オフにすると、公式サブスクリプションとサードパーティはそれぞれ独立した履歴リストに戻ります。オン期間中に作成されたセッションは提供元を判別できないため、サードパーティの履歴に残り、公式サブスクリプションからは見えなくなります。
|
||||
|
||||
- **チェックボックス**（条件付き表示）: オンにした際に移行した公式セッションを公式履歴へ復元する（バックアップから正確に復元）
|
||||
- **確認ボタン**: オフにする
|
||||
- **キャンセルボタン**: キャンセル
|
||||
|
||||
> **ポイント**: 本文が言っているのは「公式サブスクリプションからは **見えなくなる**」——**見えなくなる** であり、**削除される** ではありません。オン期間中に新たに話したセッションは、引き続き `custom` の引き出しに完全な形で残っており、オフにした後で公式側から見えなくなるだけです。
|
||||
|
||||
**この復元チェックボックスはデフォルトでオンです。** つまりデフォルトの動作は「オフにすると同時に、移行した公式セッションを公式履歴へ正確に復元する」です。チェックを保持したまま「オフにする」を押すだけで構いません。
|
||||
|
||||
チェックボックスが **表示されない** 場合は、復元が必要なバックアップがないとシステムが判断したことを意味します（移行に一度もチェックを入れていない、またはバックアップを探索できない）——この場合、あなたの公式の古いセッションは一度も変更されていないので、スイッチをオフにすれば自然と `openai` の引き出しに戻ります。
|
||||
|
||||
### Step 2: 復元はどう実行されるか（バックアップ台帳に従って正確に戻す）
|
||||
|
||||
チェックを保持して「オフにする」を押すと、CC Switch の復元フローは次のようになります。
|
||||
|
||||
```text
|
||||
① まず現在の状態を独立した復元バックアップディレクトリへもう一度コピー
|
||||
~/.cc-switch/backups/codex-official-history-unify-restore-v1/<時間スタンプ>/
|
||||
（復元自体もまずバックアップするので、復元でもデータは失われない）
|
||||
② すべての移行バックアップ世代を走査し、「当初のラベルが openai」のセッション id を集めて「台帳」を作る
|
||||
③ 【台帳に含まれ、かつ現在もまだ custom】のセッションだけ、ラベルを "openai" に戻す
|
||||
```
|
||||
|
||||
③ のステップの **二重条件** に注意してください——台帳に含まれていること（当初確かに公式から移行されたものだと証明できる）に加えて、現在もまだ `custom` であること（あなたが手動で変更していないことを示す）。両方の条件を満たして初めて戻します。これにより、復元は正確であり、かつ誤って手を加えることもありません。
|
||||
|
||||
**この時点でのあなたのデータ**: 戻された公式セッションはラベルが `openai` に変わり、再び公式リストに表示されます。同時に、移行バックアップと復元バックアップの 2 つのコピーがどちらもディスク上に残っています。
|
||||
|
||||
### Step 3: 通知を見て、結果を確認する
|
||||
|
||||
「オフにする + 復元にチェック」というパスだけが結果通知を表示します。表示され得る通知（逐語）。
|
||||
|
||||
| 表示される通知 | 意味 |
|
||||
|---|---|
|
||||
| **バックアップから公式セッション履歴を復元しました（セッションファイル {{files}} 件、インデックス {{rows}} 行）** | 復元成功。`{{files}}` / `{{rows}}` の部分には実際の数字が表示される |
|
||||
| **現在の Codex ディレクトリに復元可能な移行バックアップはありません** | 復元できる内容がない（**データが消えたわけではない**。対照表シナリオ E を参照） |
|
||||
| **統一セッション履歴が再度有効化されたため、復元をスキップしました** | 復元のキュー待ち中にスイッチを再びオンにしたため、システムが復元を自発的に取りやめた（対照表シナリオ F を参照） |
|
||||
| **公式セッション履歴の復元に失敗しました。もう一度お試しください** | 復元の途中でエラー。もう一度試せばよく、データは破壊されていない |
|
||||
| **保存に失敗しました。もう一度お試しください** | オフにするステップの保存そのものが失敗。この場合 **復元は決して起動されず**、スイッチは元の位置に戻る |
|
||||
|
||||
> **気の利いた安全設計**: 「スイッチをオフにする」ステップの保存が失敗した場合、CC Switch は **復元を決して実行しません**。さもないと「スイッチはまだオン、しかしセッションは `openai` バケットに戻された」という矛盾状態が生じてしまいます。保存失敗時、スイッチは **自動で元の位置に戻る** ので、「オフに見えるのに実は保存されていない」という偽の状態に取り残されることはありません。
|
||||
|
||||
---
|
||||
|
||||
## 「会話が消えた？」症状対照表
|
||||
|
||||
以下の 6 つのシナリオは、ユーザーが最も「セッションが消えた」と誤解しやすいケースです。**どれも真相は: データは無傷で、引き出しが変わったか一時的に見えないだけ。** まずこの表で症状から原因を特定し、その後で下の詳細説明を読んでください。
|
||||
|
||||
| シナリオ | あなたが見るもの | データの真相 | 一言での解決法 |
|
||||
|---|---|---|---|
|
||||
| **A** 移行にチェックなし | 公式の古いセッションが統一リストにない | すべて存在、`openai` ラベルのまま | 移行にチェックを入れて再度オンにする、またはスイッチをオフにする |
|
||||
| **B** プロバイダーをまたいだ再開が失敗 | 続けられない / エラー | ファイルは無傷、暗号文がバックエンドをまたいで復号できないだけ | 元のプロバイダーで再開する。内容だけ見るなら jsonl を直接読む |
|
||||
| **C** プロキシ接管 / 注入が拒否 | 移行も復元もされない | 移行が安全にスキップされ、ファイルは未変更 | 接管を終了 → 再起動して再試行。またはスイッチを直接オフにする |
|
||||
| **D** 復元後、新セッションが公式に戻らない | オン期間中の新セッションが公式にない | `custom` の引き出しにある、設計上動かさない | サードパーティプロバイダーに切り替えれば見える |
|
||||
| **E** 「復元可能なバックアップなし」と通知 | 復元が「失敗」 | 通常はそもそも移行していない、セッションは元の引き出しにある | スイッチをオフにすれば公式セッションが自動で再表示 |
|
||||
| **F** 「スイッチが再度有効化、復元スキップ」と通知 | 復元が拒否 | データの矛盾を防止、何も変更していない | まずスイッチを完全にオフにしてから復元する |
|
||||
|
||||
### シナリオ A: スイッチをオンにしたが移行にチェックを入れなかった → 公式の古いセッションが「消えた」
|
||||
|
||||
**現象**: 統一スイッチをオンにしたが、有効化ダイアログの「既存の公式セッション履歴も移行する」にチェックを入れなかった（デフォルトでチェックなし）。オンにした後で見ると、以前の公式の古いセッションがすべてリストにないように見える。
|
||||
|
||||
**真相**: データは 100% すべて存在し、1 行も動いていません。スイッチは「オンにした後に新規作成された」公式セッションにのみ効きます。あなたが **オンにする前** の公式の古いセッションはラベルが `openai` のままで、そっくりそのまま `~/.codex/sessions/` に横たわっています。今あなたがアクティブにしているのは `custom` の引き出しなので、`openai` の引き出しに残った古いセッションが見えないのは当然です——これが「消えたように見える」理由のすべてです。
|
||||
|
||||
**どうするか**（いずれか）:
|
||||
1. **スイッチを再度オンにするときに「既存の公式セッション履歴も移行する」にチェックを入れ**、古いセッションを `custom` の引き出しへ移せば、すぐに統一リストに表示されます（書き換え前に自動バックアップ）。
|
||||
2. **または単に統一スイッチをオフにする** と、公式は再び `openai` の引き出しで動作し、古いセッションがその場で再表示されます。
|
||||
|
||||
### シナリオ B: プロバイダーをまたいで古いセッションを再開して失敗 → 「このセッションが壊れた / 消えた」と思う
|
||||
|
||||
**現象**: 統一した後、リストに「別のプロバイダー」で話した古いセッションが見える。今のプロバイダーに切り替えて「再開」を押すと、エラーになったり繋がらなかったりする。
|
||||
|
||||
**真相**: セッションファイルは完全に無傷で、失われたのはデータではなく「バックエンドをまたいだ復号能力」です。Codex セッションには暗号化された推論内容 `encrypted_content` が保存されており、**この暗号文は、それを生成したバックエンドだけが復号できます**。B プロバイダーで A プロバイダーが生成したセッションを再開しようとすると、B は A の暗号文を解けない → 再開失敗。これは **上流の Codex の設計上の制約（by design）** であり、CC Switch がファイルに手を加えたかどうかとは無関係です。セッション内の文字内容はいつでも読めます。
|
||||
|
||||
> これは本記事全体で **唯一「本当に問題が起きたように見える」実在の例外** です——ただし注意してください: これは **再開できない（新しいターンを生成できない）** だけであり、**元ファイルは依然として完全に存在し**、会話の文字はいつでも読めます。
|
||||
|
||||
**どうするか**:
|
||||
- **「このセッションを最初に作成したプロバイダー」で再開すれば**、正常に復号でき、繋がります。
|
||||
- 履歴の内容だけ見たくて、続ける必要がない場合は、そのセッションの `.jsonl` ファイルを直接読んでください（巻末にコマンドあり）。
|
||||
- 経験則: **プロバイダーをまたぐ場合は「新規セッションを始める」のが向いており、古いセッションはできるだけ元のプロバイダーで再開してください。**
|
||||
|
||||
### シナリオ C: スイッチをオンにし移行にもチェックを入れたが、移行が静かにスキップされた → 「移行がセッションをなくした」と思う
|
||||
|
||||
**現象**: オンにして移行にチェックを入れたのに、公式の古いセッションは統一リストに入らず、スイッチをオフにして復元しようとしても「復元できるものがない」と通知される（または無効化ダイアログに復元チェックボックスがそもそも現れない。シナリオ E を参照）。あなたは、移行の過程でセッションをなくしたのではと疑います。
|
||||
|
||||
**真相**: 移行はそもそも **実行されていない** ので、なくすことも不可能です——あなたのセッションは 1 文字も変更されていません。CC Switch には移行前に安全ゲートがあります: Codex の live 設定（`~/.codex/config.toml`）が、この時点で **本当に** 共有の `custom` 引き出しへルーティングされているかを確認し、本当にルーティングされている場合だけ移行します。以下の 2 つのケースでは「まだ統一されていない」と判定され（内部の理由コード `live_not_unified`）、**移行を自発的にスキップし、あなたのスイッチと移行の意思は保持し、条件が満たされてから移行します**。
|
||||
|
||||
- **プロキシ接管中**: CC Switch のプロキシが live 設定を接管しており、接管中の live には統一ルーティングのマークが付いていません。
|
||||
- **注入が拒否された**: あなたの `config.toml` にすでに手動指定の `model_provider` があるか、形態の異なる `[model_providers.custom]` テーブルが既に存在する（サードパーティのアドレスが付いている可能性がある）。公式トラフィックを誤ってサードパーティバックエンドへルーティングするのを避けるため、CC Switch は注入も移行もしないことを選びます。
|
||||
|
||||
移行のスキップ = どのセッションファイルにも触れない。**移行していない＝動かしていない、消えようがない。** これは「安全な先送り」であり、「失敗してデータが消えた」ではありません。
|
||||
|
||||
**どうするか**:
|
||||
- プロキシ接管を終了 → **CC Switch を再起動**: 起動時に自動で移行を再試行します（あなたの移行の意思はずっと保持されています）。
|
||||
- `~/.codex/config.toml` を確認: 手動で書いた競合するルーティングがあれば、競合を整理してからスイッチをオンにします。
|
||||
- どうしても手間をかけたくない場合は、スイッチをオフにすれば、公式セッションは引き続き `openai` の引き出しで正常に表示され、まったく無傷です。
|
||||
|
||||
### シナリオ D: スイッチをオフにして復元したが、「オン期間中に新たに話したセッション」が公式に戻らない → 「新セッションが消えた」と思う
|
||||
|
||||
**現象**: 統一をオンにしている間、公式でさらにいくつかの新セッションを話した。後でスイッチをオフにし、復元にチェックを入れた。復元が終わると、その数本の新セッションが公式の引き出しに戻っていない。
|
||||
|
||||
**真相**: これは **意図的な** 設計で、新セッションはちゃんと `custom` の引き出しにあり、見えるし続けられます。復元の拠り所は「移行時のバックアップ台帳」です——**当初 `openai` の引き出しから移行されてきたセッションだけ** がバックアップに記録されており、正確に `openai` へ戻されます。あなたが **オン期間中に新規作成した** セッションはどのバックアップ台帳にもありません。しかも統一後は公式もサードパーティも `custom` ラベルを使うので、**CC Switch はこの新セッションが公式で話したものかサードパーティで話したものか判別できません**。サードパーティのセッションを公式履歴に誤って押し込まないため、プロダクトの決定として、これらの新セッションは一律に `custom`（サードパーティ）の履歴に残し、決して自動で動かしません。無効化ダイアログの文言もこれを明示しています——「オン期間中に作成されたセッションは提供元を判別できないため、サードパーティの履歴に残ります」。
|
||||
|
||||
**どうするか**:
|
||||
- 任意のサードパーティプロバイダー（`custom` の引き出し）に切り替えれば、履歴リストでこれらのセッションが見えます。
|
||||
- 内容を見たいなら `.jsonl` を直接読み、再開したいならシナリオ B のルール（それを生成した元のバックエンドに戻る）に従ってください。
|
||||
- もし **ある 1 本** を手動で公式に戻したい場合: 現在は自動ボタンはありません（方向を誤判定するのを避けるため、あえて作っていません）。上級ユーザーは、そのファイルを **先にバックアップ** したうえで、`.jsonl` の 1 行目 `session_meta` 内の `model_provider` を `custom` から `openai` に手動で戻せます（上級操作です。変更前に必ずコピーを取ってください）。
|
||||
|
||||
### シナリオ E: 復元時に「現在の Codex ディレクトリに復元可能な移行バックアップはありません」と通知 → 「復元失敗 = データが消えた」と思う
|
||||
|
||||
**現象**: スイッチをオフにするときに復元にチェックを入れたら、「現在の Codex ディレクトリに復元可能な移行バックアップはありません」と通知が出た。あなたは慌てます: 復元すら失敗した、データは完全に消えたのでは？
|
||||
|
||||
**真相**: 「復元できるものがない」≠「データが消えた」。むしろ逆で、通常は **そもそも復元すべき移行が存在しない** からです。よくある原因:
|
||||
|
||||
- **当初「既存の公式セッションを移行する」にチェックを入れていない**: 移行していない以上、移行バックアップもなく、戻すべきセッションもありません。あなたの公式の古いセッションはずっと `openai` の引き出しにあり、スイッチをオフにすれば直接再表示されます（シナリオ A と同じ）。（この場合、無効化ダイアログは復元チェックボックスを **そもそも表示しない** こともあります——システムがバックアップを一切探索できないためです。）
|
||||
- **すでに一度復元済み**: セッションラベルはすべて `openai` に戻っており、もう一度押しても「まだ `custom` の対象がない」のは当然です——これは **冪等保護であり、失敗ではありません**。
|
||||
- **Codex ディレクトリを切り替えた**: 復元は **現在の** ディレクトリに属するバックアップ台帳しか認識しないので、ディレクトリを変えると旧ディレクトリの台帳が見つかりません。ディレクトリを戻せば解決します。
|
||||
|
||||
この 3 つのケースでは、どのセッションも削除されていません。
|
||||
|
||||
**どうするか**: 巻末のコマンドで `~/.codex/sessions/` 内のセッションファイル総数を数え、ファイルがすべて残っていることを確認してください。次に `~/.cc-switch/backups/` に `codex-official-history-unify-v1` ディレクトリがあるかを見てください——もしこのディレクトリすらなければ、あなたは一度も移行を起動しておらず、セッションはずっと元の引き出しにある、ということです。
|
||||
|
||||
### シナリオ F: 復元が拒否され、「統一セッション履歴が再度有効化されたため、復元をスキップしました」と通知
|
||||
|
||||
**現象**: スイッチをオフにする → 復元にチェック → 手が速くて、すぐにスイッチを再びオンにした。すると「統一セッション履歴が再度有効化されたため、復元をスキップしました」と通知が出た。
|
||||
|
||||
**真相**: これはデータを「矛盾」状態にしてしまうのを防ぐ防護であり、セッションは同じく消えていません。復元の動作は「セッションラベルを `custom` から `openai` へ戻す」ことですが、この時点でスイッチが再びオンになっていると、live 設定は `custom` へルーティングしています——一方で履歴を `openai` へ戻し、一方で新セッションを `custom` に落とせば、セッションが人為的に 2 つに引き裂かれてしまいます。そのため CC Switch は「スイッチが再びオンになった」のを検知すると、**この復元を自発的に取りやめ、何も変更しません**。セッションは現状を維持し、削除も破壊もありません。
|
||||
|
||||
**どうするか**: 本当に復元したいなら、**まずスイッチを安定してオフにし**（すぐにオンにし直さない）、それから「オフにする + 復元にチェック」を実行してください。統一を保ちたいなら、復元せず、セッションを `custom` の共有引き出しに残して通常どおり使ってください。
|
||||
|
||||
**大原則: CC Switch の統一 / 移行 / 復元は、全工程でセッションの 1 つのラベルフィールドだけを変更し、しかも毎回書き換える前に自動でバックアップします。あなたの会話を削除することはありません。見えない ≠ 消えた——別の引き出しを見るか、下のコマンドで自分の目で確かめてください。**
|
||||
|
||||
---
|
||||
|
||||
## 自分の目で確認: セッションファイルはディスク上に残っている（最重要セクション）
|
||||
|
||||
文字をいくら重ねるより、自分の目で見るのが一番です。以下に **実際のパス**（CC Switch のソースコードから取得）と、異なる OS でセッションファイル・バックアップディレクトリを見る方法を示します。**全工程は読み取りのみで変更なし。ぜひ一度ご自身で試してみてください。**
|
||||
|
||||
### 最も簡単な方法: ファイルマネージャーで直接開く（コマンドライン完全不要）
|
||||
|
||||
- **macOS（Finder）**: `Cmd + Shift + G` を押して `~/.codex/sessions` を貼り付けて Enter すれば、たくさんの `.jsonl` セッションファイルとその更新時刻が見えます。バックアップディレクトリは `~/.cc-switch/backups` を貼り付けます。
|
||||
- **Windows（エクスプローラー）**: アドレスバーに `%USERPROFILE%\.codex\sessions` を貼り付けて Enter すれば、セッションフォルダとその中の `.jsonl` が見えます。バックアップディレクトリは `%USERPROFILE%\.cc-switch\backups` を貼り付けます。
|
||||
|
||||
**ここで一連の `.jsonl` ファイルが見えれば、それがセッションデータが無傷でディスク上にある証拠です。** ファイル数や更新時刻は、どんな文章よりも直感的です。
|
||||
|
||||
### あなたのセッション / 履歴ファイルはどこにあるのか
|
||||
|
||||
| 内容 | 実際のパス | 説明 |
|
||||
|---|---|---|
|
||||
| **セッション本文（コア）** | `~/.codex/sessions/`（日付別サブディレクトリを含む、再帰的） | セッション 1 つにつき 1 つの `.jsonl` テキストファイル。**これがあなたの会話内容** |
|
||||
| **アーカイブ済みセッション** | `~/.codex/archived_sessions/` | 同じく `.jsonl` |
|
||||
| **セッションインデックス DB** | `~/.codex/state_5.sqlite` | `threads` テーブルの `model_provider` 列が「引き出しラベル」。**これこそ、セッション再開リストが実際に読み取る分類のソース** |
|
||||
| **移行バックアップ**（移行をオンにすると自動生成） | `~/.cc-switch/backups/codex-official-history-unify-v1/<時間スタンプ>/` | `jsonl/`、`state/`、`meta.json` を含む |
|
||||
| **復元バックアップ**（復元を押すと自動生成） | `~/.cc-switch/backups/codex-official-history-unify-restore-v1/<時間スタンプ>/` | 復元前の安全なコピー |
|
||||
|
||||
> **注意**: CC Switch で Codex ディレクトリを変更した場合や、`config.toml` で `sqlite_home` を設定している場合は、上記の `~/.codex` をあなたの実際のディレクトリに置き換えてください。以下の `~` = あなたのユーザーホームディレクトリ。
|
||||
|
||||
### macOS / Linux コマンド
|
||||
|
||||
**1. セッションファイル総数を数える（これこそ「消えていない」確固たる証拠）**
|
||||
|
||||
```bash
|
||||
# セッションファイルの総数を数える —— この数が想定どおりなら、データはすべて残っている
|
||||
find ~/.codex/sessions ~/.codex/archived_sessions -name '*.jsonl' 2>/dev/null | wc -l
|
||||
|
||||
# 最近更新されたセッションファイル上位 10 件を見る
|
||||
find ~/.codex/sessions -name '*.jsonl' 2>/dev/null -print0 \
|
||||
| xargs -0 ls -lt 2>/dev/null | head -10
|
||||
```
|
||||
|
||||
**2. （補助）各「引き出し」にそれぞれ何個のセッションがあるか見る**
|
||||
|
||||
```bash
|
||||
# 公式の引き出し（openai）のセッションファイル数
|
||||
grep -rlE '"model_provider"[[:space:]]*:[[:space:]]*"openai"' ~/.codex/sessions 2>/dev/null | wc -l
|
||||
|
||||
# 統一の引き出し（custom）のセッションファイル数
|
||||
grep -rlE '"model_provider"[[:space:]]*:[[:space:]]*"custom"' ~/.codex/sessions 2>/dev/null | wc -l
|
||||
|
||||
# 各ラベルの分布をひと目で確認
|
||||
grep -rhoE '"model_provider"[[:space:]]*:[[:space:]]*"[^"]*"' ~/.codex/sessions 2>/dev/null | sort | uniq -c
|
||||
```
|
||||
|
||||
> **重要なヒント、このステップに驚かないでください**: **初期バージョンの Codex は `.jsonl` に `model_provider` フィールドを書き込みません**。これらの古い公式セッションは上記の grep では **数えられません** が、インデックス DB `state_5.sqlite` では依然として `openai` に分類されており、セッション再開リストではちゃんと見えます。ですので **「セッションが消えていない」かの判断はステップ 1 のファイル総数を基準にしてください**——バケット別 grep は分類を理解する補助に過ぎず、数えた結果がファイル総数より少ないのは **まったく正常** であり、決して「ひとまとまり消えた」ことを意味しません。
|
||||
|
||||
**3. （応用）インデックス DB `state_5.sqlite` を見る——セッション再開リストが実際に読む分類**
|
||||
|
||||
```bash
|
||||
# sqlite3 がインストール済みであること；未インストールならスキップ可
|
||||
sqlite3 ~/.codex/state_5.sqlite \
|
||||
"SELECT COALESCE(model_provider,'<空>'), COUNT(*) FROM threads GROUP BY 1;"
|
||||
```
|
||||
|
||||
> この `threads` テーブルこそ、Codex のセッション再開リストが実際に読み取る分類のソースであり、`openai` の行数 ≈ あなたの公式の引き出しで見えるセッション数です。ステップ 2 の jsonl grep とは数が合わないことがあります——その理由は、上述の「古いセッションは jsonl フィールドを書き込まないが、インデックス DB では依然として openai」だからです。両者が合わないのは異常ではありません。
|
||||
|
||||
**4. あるセッションの内容を直接読む（会話の文字が残っていることを確認）**
|
||||
|
||||
```bash
|
||||
# <ファイル名> を、上の ls で表示された .jsonl のパスに置き換える
|
||||
python3 -m json.tool < "<ファイル名>.jsonl" 2>/dev/null | head -50
|
||||
|
||||
# またはエディタで直接開いて見る（プレーンテキスト）
|
||||
open -e "<ファイル名>.jsonl" # macOS
|
||||
```
|
||||
|
||||
**5. CC Switch のバックアップディレクトリを見る（移行 / 復元の前に必ずコピーを残した証拠）**
|
||||
|
||||
```bash
|
||||
ls -la ~/.cc-switch/backups/codex-official-history-unify-v1/ 2>/dev/null
|
||||
ls -la ~/.cc-switch/backups/codex-official-history-unify-restore-v1/ 2>/dev/null
|
||||
```
|
||||
|
||||
### Windows コマンド（PowerShell）
|
||||
|
||||
セッションディレクトリは通常 `C:\Users\<あなたのユーザー名>\.codex\` にあり、バックアップは `C:\Users\<あなたのユーザー名>\.cc-switch\backups\` にあります。
|
||||
|
||||
```powershell
|
||||
# 1. セッションファイルの総数（「消えていない」ことの動かぬ証拠）
|
||||
(Get-ChildItem "$env:USERPROFILE\.codex\sessions","$env:USERPROFILE\.codex\archived_sessions" -Recurse -Filter *.jsonl -ErrorAction SilentlyContinue).Count
|
||||
|
||||
# 2. 最近更新されたセッション上位 10 件
|
||||
Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
|
||||
Sort-Object LastWriteTime -Descending | Select-Object -First 10 FullName,LastWriteTime
|
||||
|
||||
# 3. （補助）公式(openai) / 統一(custom) の引き出しにそれぞれ何件のセッションファイルがあるか
|
||||
(Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
|
||||
Select-String -Pattern 'model_provider"\s*:\s*"openai"' -List).Count
|
||||
(Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
|
||||
Select-String -Pattern 'model_provider"\s*:\s*"custom"' -List).Count
|
||||
|
||||
# 4. バックアップディレクトリを見る
|
||||
Get-ChildItem "$env:USERPROFILE\.cc-switch\backups\codex-official-history-unify-v1" -ErrorAction SilentlyContinue
|
||||
Get-ChildItem "$env:USERPROFILE\.cc-switch\backups\codex-official-history-unify-restore-v1" -ErrorAction SilentlyContinue
|
||||
```
|
||||
|
||||
> 同じく注意: ステップ 3 の grep の数がファイル総数より **少なくなる** のは正常です（古いセッションはこのフィールドを書き込まないため）。「セッションが消えていない」の判断は、ステップ 1 の **ファイル総数** を基準にしてください。
|
||||
|
||||
---
|
||||
|
||||
## 応用原理付録（仕組みを本当に理解したい人向け）
|
||||
|
||||
### 1. バケット分け機構（引き出しの本質）
|
||||
|
||||
Codex のセッション再開 / 履歴リストは、現在アクティブな `model_provider` id で **厳密な文字列フィルタリング** を行います。セッションファイル `.jsonl` の **1 行目** は `type:"session_meta"` のレコードで、その `payload.model_provider` がそのセッションの属する引き出しです（`grep -rl` はファイル内にそのラベルが 1 回でも出現すればそのファイルをカウントするので、行ごとに解析する必要はありません。旧バージョンでこのフィールドを書き込んでいないセッションは数えられません）。セッション再開リストを実際に駆動するのはインデックス DB `state_5.sqlite` の `threads.model_provider` 列です。公式サブスクリプションは `config.toml` に明示的な `model_provider` がないとき、内蔵のデフォルト id `openai` に入ります。CC Switch のすべてのサードパーティプロバイダーは一律に `custom` を使います。
|
||||
|
||||
### 2. スイッチがすること（注入、live にのみ存在）
|
||||
|
||||
オンにすると、CC Switch は公式 live `config.toml` に次の内容を注入します。
|
||||
|
||||
```toml
|
||||
model_provider = "custom"
|
||||
|
||||
[model_providers.custom]
|
||||
name = "OpenAI"
|
||||
requires_openai_auth = true
|
||||
supports_websockets = true
|
||||
wire_api = "responses"
|
||||
```
|
||||
|
||||
各フィールドには役割があります。`requires_openai_auth = true` は認証を引き続き `auth.json` 内の ChatGPT ログインで行わせ、base_url 未指定時は公式 Codex バックエンドへフォールバックさせます。`name = "OpenAI"` は Codex の公式機能ゲート（web search、リモート圧縮など）を引き続きヒットさせます。`supports_websockets = true` は custom エントリでデフォルトに失われる能力を補います。`wire_api = "responses"` は公式の responses プロトコルを使います。**正味の効果は: 認証は変わらず、バケット名が変わるだけ。**
|
||||
|
||||
**重要な不変条件: この注入は live `config.toml` にのみ存在でき、決してデータベースの保存設定には書き込まれません。** 公式プロバイダーから切り替えて離れ、live をデータベースへ書き戻すとき、CC Switch はこの注入を正確に剥離します（形態が注入物と完全に一致するときだけ剥離し、サードパーティがカスタムした `custom` テーブルはそのまま保持します）。だからこそ「スイッチをオフにする + 一度切り替える」だけで live を完全に復元でき、データベースには常にあなた本来のクリーンな公式設定が保たれます——これがスイッチ全体の可逆性の礎です。
|
||||
|
||||
### 3. 注入の 2 つの拒否ゲート（シナリオ C に対応）
|
||||
|
||||
- `config.toml` に明示的な `model_provider` がすでにある → ユーザーのルーティングを上書きしない。
|
||||
- 形態の異なる `[model_providers.custom]` テーブルがすでに存在する（サードパーティの `base_url` が付いている可能性がある）→ 注入を拒否、さもないと ChatGPT OAuth トラフィックを誤ったバックエンドへルーティングしてしまう。
|
||||
|
||||
注入を拒否したとき live は統一されず、移行ゲート（live の `model_provider` が trim 後に `custom` と等しいかを確認）が `live_not_unified` と判定 → 移行をスキップし、意思を保持し、次回起動の再試行時に行います。これは「安全な先送り」であり、「失敗してデータが消えた」ではありません。
|
||||
|
||||
### 4. セッションの三分類（移行 / 復元の境界を決める）
|
||||
|
||||
- **A 類**: オン時に移行した既存の公式セッション——バックアップが台帳であり、正確に `openai` へ復元可能。
|
||||
- **B 類**: オン期間中に新規作成——どのバックアップにもなく、公式 / サードパーティを判別不能、**決して自動で動かさない**（`custom` に残す）。
|
||||
- **C 類**: オン前の純粋なサードパーティ履歴——絶対に触れない。
|
||||
|
||||
### 5. 移行 / 復元の安全性（データが本当に削除されることはない、その保証はどこから来るか）
|
||||
|
||||
4 層の設計が共同で保証します: **正常・異常のあらゆるパス** において、元のセッションデータが本当に削除されることはありません。
|
||||
|
||||
- **フィールドだけ変更、本文には触れない**: 移行 / 復元はセッションメタデータ内の `model_provider` の値を `openai` と `custom` の間で切り替えるだけで、会話内容、`response_item`、`encrypted_content` はすべてそのまま保持します。
|
||||
- **書き換え前に必ずコピーをバックアップ**: jsonl はファイルコピー、state DB は SQLite の完全なコピーで、タイムスタンプ付きの世代ディレクトリに保存します。移行バックアップは `codex-official-history-unify-v1/` に、復元バックアップは独立した `codex-official-history-unify-restore-v1/` にあり、台帳を純粋に保つため両者は分けられています。
|
||||
- **移すだけ削除しない + 原子書き込み**: すべての jsonl 書き換えは「一時ファイル + 全体置換」を経由し、state DB はトランザクション化された `UPDATE` を経由し、全工程でセッションやインデックスを削除する操作は一切ありません。ファイルはいかなる時点でも完全です。
|
||||
- **悲観的スキップ + 冪等で再試行可能**: バケットが不一致のとき（`live_not_unified`）は移行しないことを選びます。一つのプロセスロックが移行と復元を直列化し、「起動時の再試行 / 保存後のバックグラウンドタスク / 無効化時の復元」が同じ一群のファイルを並行して双方向に書き換えるのを防ぎます。完了マークは Codex ディレクトリに紐づけて条件付きで書き込み、移行漏れを防ぎます。復元は「台帳にある + 現在もまだ custom」の二重条件を使い、誤変更を防ぎます。復元スキャンはすべてのバックアップ世代の和集合を取り、何度もスイッチを切り替えた後でも初期に移行したセッションを復元できます。重複した復元は `nothing_to_restore` を返しますが、これは冪等保護であり失敗ではありません。
|
||||
|
||||
### 6. バックエンドをまたいだ encrypted_content（シナリオ B に対応）
|
||||
|
||||
セッション内の推論暗号文は、それを生成したバックエンドだけが復号でき、上流の Codex は by design でバックエンドをまたいだ復号をサポートしません。これが「再開失敗」の根本原因であり、ファイルの完全性とは無関係です——セッション `.jsonl` は完全にディスク上に横たわり、`encrypted_content` も無傷です。元のプロバイダーに戻して再開するか、新規セッションを始めれば、どちらも正常です。
|
||||
|
||||
---
|
||||
|
||||
## 参考リンク
|
||||
|
||||
- [サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する: CC Switch 設定ガイド](./codex-official-auth-preservation-guide-ja.md)
|
||||
- [Codex で DeepSeek などの Chat 形式 API を使う: CC Switch ローカルルーティングガイド](./codex-deepseek-routing-guide-ja.md)
|
||||
- CC Switch ユーザーマニュアル内の「Codex アプリ拡張」関連の章
|
||||
|
||||
---
|
||||
|
||||
**最後に一言**: あなたが見た「セッションが消えた / 再開失敗」は、本質的には **セッションが別の履歴リスト（引き出し）に移されたか、相手のバックエンドが古い推論内容を復号できない** ことであり、ファイルは常にそっくりそのまま `~/.codex/sessions/`（および `state_5.sqlite`）に横たわっています。スイッチをオフにするとき「バックアップから復元する」にチェックを入れれば、移行した公式セッションを正確に公式リストへ戻せます。たとえ復元しなくても、元の `.jsonl` ファイルと `~/.cc-switch/backups/codex-official-history-unify-*/` 配下のバックアップコピーはどちらも残っています——**データが本当に失われることは決してありません。**
|
||||
@@ -0,0 +1,467 @@
|
||||
# 统一 Codex 会话历史：功能介绍与使用攻略（CC Switch）
|
||||
|
||||
> 适用版本：CC Switch v3.16.x 及以上。本文根据当前代码整理，命令与路径均可亲手验证；示例使用去敏数据，不包含真实会话内容或 API Key。
|
||||
|
||||
## 这个功能是什么
|
||||
|
||||
「统一 Codex 会话历史」是 CC Switch v3.16.x 为 Codex 新增的一个开关。它的位置在 **设置 → 通用 → 「Codex 应用增强」分组**里（"Codex 应用增强"是这个分组的标题，开关本身叫"统一 Codex 会话历史"）。开启后，**官方订阅（ChatGPT 登录 / OpenAI API Key）的会话，会和 CC Switch 管理的所有第三方供应商会话，出现在同一个历史 / 续聊列表里**——不再被分隔在两个互相看不见的列表中。
|
||||
|
||||
## 它解决什么问题
|
||||
|
||||
Codex 自己按"供应商标签"（一个叫 `model_provider` 的字段）给会话分类，而且**续聊 / 历史列表只显示和你当前激活的供应商同标签的会话**。于是会话天然被分进两个"抽屉"：
|
||||
|
||||
- 官方订阅的会话，归在 Codex 内建的 **`openai`** 标签下；
|
||||
- CC Switch 管理的所有第三方供应商，归在 **`custom`** 标签下。
|
||||
|
||||
两个抽屉互相看不见。如果你**经常在官方与第三方之间切换**，就会遇到这种割裂："刚才用官方聊的会话，切到第三方后在历史列表里找不到了"——它其实没丢，只是被分到了另一个抽屉。这种割裂既容易让人误以为会话丢失，也不方便把所有会话放在一处统一回顾、续聊。
|
||||
|
||||
**这个开关就是为了消除这种割裂**：让官方订阅也以 `custom` 标签运行，于是官方与第三方会话合并进同一个列表，找起来、续起来都在一处。
|
||||
|
||||
> ✅ **一个贯穿全文的重要前提，请先记住**：这个功能（统一 / 迁移 / 还原）**全程只改写会话记录里那一个归类标签 `model_provider`，而且每次改写前都会自动把原文件备份一份**。它不会删除、清空或覆盖你的任何一句对话。所以本文后面若提到"某些会话看不到了"，几乎都是"被分到了另一个抽屉"，而不是"数据没了"——真担心时，直接看 [症状对照表](#我感觉会话丢了症状对照表) 与 [亲手验证文件还在](#亲手验证你的会话文件还在硬盘上最重要的一节)。
|
||||
|
||||
## 工作原理（一句话版）
|
||||
|
||||
把它想成 **两个抽屉 + 自动备份**：
|
||||
|
||||
- 默认时，官方会话在 `openai` 抽屉、第三方会话在 `custom` 抽屉，互不可见；
|
||||
- 开关让**官方也改用 `custom` 抽屉**，于是两个抽屉合并成一个共享列表；
|
||||
- 你可以选择把**现有的官方老会话**也一并"搬"进共享抽屉（这一步叫**迁移**，可选、需主动勾选），而**任何搬动前都会先复制一份备份**，所以整个过程**可逆**；
|
||||
- **认证完全不受影响**——官方订阅照常用你的 ChatGPT 登录、照常走官方后端，变的只是会话的归类标签。
|
||||
|
||||
完整机制（注入了什么、为什么可逆、迁移/还原如何保证不丢数据）见下文 [核心心智模型](#核心心智模型两个抽屉--自动备份) 与文末 [进阶原理附录](#进阶原理附录给想真正搞懂机制的用户)。
|
||||
|
||||
## 如何使用（速览）
|
||||
|
||||
1. **开启**：设置 → 通用 → Codex 应用增强 → 打开「统一 Codex 会话历史」→ 在弹窗里决定是否勾选"同时迁入现有官方会话历史"（想让**以前**的官方会话也并进统一列表，就勾上；只想从现在起统一，就不勾）→ 确认。详见 [开启时会发生什么](#开启时会发生什么分步说明)。
|
||||
2. **关闭**：关掉同一开关 → 弹窗里保持勾选"按备份精确还原"（默认就勾着）→ 确认，即可把当初迁入的官方会话精确翻回官方列表。详见 [关闭时会发生什么](#关闭时会发生什么分步说明)。
|
||||
3. **感觉会话丢了？** 别慌，跳到 [症状对照表](#我感觉会话丢了症状对照表) 按症状定位，并用 [亲手验证](#亲手验证你的会话文件还在硬盘上最重要的一节) 一节的命令亲眼确认文件都在。
|
||||
|
||||
---
|
||||
|
||||
## 核心心智模型：两个抽屉 + 自动备份
|
||||
|
||||
要理解这个功能，你只需要记住两件事：**抽屉**和**备份**。
|
||||
|
||||
### 抽屉：Codex 怎么给会话分类
|
||||
|
||||
你每开一个 Codex 会话，Codex 会在会话文件头部记一个标签 `model_provider`，标记"这条会话是用哪个供应商聊的"。Codex 的**续聊 / 历史列表是按当前激活的这个标签精确过滤的**——只显示和"你现在这个供应商"同标签的会话。
|
||||
|
||||
- 官方订阅（ChatGPT 登录 / OpenAI API Key）的会话，标签是内建的 **`openai`**。
|
||||
- CC Switch 管理的所有第三方供应商，统一用标签 **`custom`**。
|
||||
|
||||
所以默认情况下，官方会话和第三方会话天生互相看不见——它们在两个不同的抽屉里。这是 **Codex 自身的设计**，不是 CC Switch 弄丢了什么。
|
||||
|
||||
```text
|
||||
默认状态（没开统一开关）：
|
||||
|
||||
┌─────────────────┐ ┌─────────────────┐
|
||||
│ openai 抽屉 │ │ custom 抽屉 │
|
||||
│ （官方订阅会话） │ │ （第三方供应商会话）│
|
||||
└─────────────────┘ └─────────────────┘
|
||||
▲ ▲
|
||||
用官方时只看到这边 用第三方时只看到这边
|
||||
（两个抽屉互相看不见）
|
||||
```
|
||||
|
||||
**「统一 Codex 会话历史」开关做的事，就是让官方订阅也以 `custom` 标签运行，把两个抽屉合并成一个**，于是官方会话和第三方会话出现在同一个续聊列表里。注意：**认证没变**——你的官方订阅照常用你的 ChatGPT 登录、照常走官方后端，只是会话的"归类标签"从 `openai` 变成了 `custom`。
|
||||
|
||||
```text
|
||||
开启统一开关后：
|
||||
|
||||
┌─────────────────────────────────────────┐
|
||||
│ custom 共享抽屉 │
|
||||
│ 官方订阅会话 + 第三方供应商会话 │
|
||||
│ （出现在同一个历史 / 续聊列表里） │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 备份：每次改标签前都先复制一份
|
||||
|
||||
"合并抽屉"需要把一部分官方会话的标签从 `openai` 改成 `custom`（这一步叫**迁移**，且是**可选的、需要你主动勾选**）。而**任何一次改写之前，CC Switch 都会先把原文件原封不动地复制一份**到这里：
|
||||
|
||||
```text
|
||||
~/.cc-switch/backups/codex-official-history-unify-v1/<时间戳>/
|
||||
```
|
||||
|
||||
这份备份，就是日后"按备份精确还原"的唯一依据。它让整个过程变得**可逆**：你随时可以关掉开关，把当初迁进来的官方会话精确地翻回 `openai` 抽屉。
|
||||
|
||||
记住这两个词——**抽屉**（会话只是换了归类）、**备份**（改前必先复制）——后面所有内容你都能轻松理解。
|
||||
|
||||
---
|
||||
|
||||
## 开启时会发生什么：分步说明
|
||||
|
||||
### 第 1 步：找到开关
|
||||
|
||||
```text
|
||||
设置 → 通用 → Codex 应用增强
|
||||
```
|
||||
|
||||
在"Codex 应用增强"这个区块里有两行开关，**第二行**（蓝色历史图标）就是本攻略的主角：
|
||||
|
||||
> **统一 Codex 会话历史**
|
||||
|
||||
它下方有一段说明文字（逐字）：
|
||||
|
||||
> 开启后，官方订阅将以共享的 custom 供应商标识运行，官方与第三方会话出现在同一历史列表中，并可选择把现有官方会话一并迁入（迁移前自动备份）。关闭开关时可按备份恢复迁入的会话。注意：跨供应商继续旧会话时，对方后端可能无法解密会话中的 encrypted_content 推理内容，导致继续失败
|
||||
|
||||
> **注意**：这一句说明里已经预告了三件事——会出现在同一列表、可选迁入并自动备份、跨供应商续聊"可能继续失败"。这里的"继续失败"指的是**续不上、生成不了新回合**，不是"记录丢失"。这正是后面要重点拆解的核心误解。
|
||||
|
||||
### 第 2 步：把开关从关拨到开 → 弹出确认窗
|
||||
|
||||
一旦你把开关拨到开，CC Switch **不会立刻保存**，而是先弹出一个确认窗口。窗口文案如下（逐字）：
|
||||
|
||||
- **标题**：统一 Codex 会话历史
|
||||
- **正文**：
|
||||
|
||||
> 开启后，官方订阅与第三方将共用同一个会话历史列表。注意：跨供应商继续旧会话时，可能因对方后端无法解密 encrypted_content 推理内容而失败。
|
||||
>
|
||||
> 可选择同时把现有官方会话历史迁入共享列表（迁移前自动备份到 ~/.cc-switch/backups，关闭开关时可选择恢复）。
|
||||
|
||||
- **复选框**：同时迁入现有官方会话历史
|
||||
- **确认按钮**：我已了解，继续开启
|
||||
- **取消按钮**：取消
|
||||
|
||||
**这个复选框默认是不勾选的。** 这是一个重要的分岔点：
|
||||
|
||||
| 你的选择 | 效果 | 此刻你的数据在哪 |
|
||||
|---|---|---|
|
||||
| **不勾**（默认） | 只切换标识。**只有开启之后新建的官方会话**才会落进 `custom` 共享抽屉 | 你**开启前**的官方老会话，标签仍是 `openai`，原地未动，仍在 `~/.codex/sessions/` |
|
||||
| **勾上** | 除了切换标识，还会把**现有的官方老会话**也从 `openai` 抽屉迁进 `custom` 抽屉 | 老会话被**复制备份**后，标签改写为 `custom`；原始数据有备份兜底 |
|
||||
|
||||
> **如果你希望"以前的官方会话也出现在统一列表里"，必须主动勾选这个复选框。** 否则你会遇到下面对照表里的"场景 A"——老会话看起来"不见了"，其实只是留在原抽屉里。
|
||||
|
||||
点"取消"或点窗口外面：开关直接弹回关闭状态，什么都没发生。
|
||||
点"我已了解，继续开启"：开关保存为开启，CC Switch 在后台落盘配置（如果勾了迁移，就执行迁移）。
|
||||
|
||||
### 第 3 步（仅当勾了迁移）：迁移如何执行 + 数据安全
|
||||
|
||||
如果你勾了"同时迁入现有官方会话历史"，CC Switch 会对你的官方老会话做这套流程：
|
||||
|
||||
```text
|
||||
对每个官方（openai 标签）会话文件：
|
||||
① 先把原文件原样复制一份到备份目录 ← 数据有了第一道保险
|
||||
② 用「写临时文件 → 整体替换」的原子方式，
|
||||
只把头部那行 session_meta 里的 model_provider
|
||||
从 "openai" 改成 "custom" ← 对话正文一个字节都不动
|
||||
③ 索引数据库 state_5.sqlite 同步在一个事务里把标签改过来
|
||||
```
|
||||
|
||||
- **备份位置**：`~/.cc-switch/backups/codex-official-history-unify-v1/<时间戳>/`，每次迁移生成一个带时间戳的"代际目录"，内含 `jsonl/`（会话副本）、`state/`（索引库副本）、`meta.json`（记录这次迁移属于哪个 Codex 目录）。
|
||||
- **改的是什么**：只有 `model_provider` 这一个字段值。你的对话内容、推理内容、所有正文**原样保留**。
|
||||
- **删的是什么**：**什么都没删**。备份是"复制"，改写是"原子替换同一个文件"，全程没有任何删除会话或索引的动作。文件在任何时刻都是完整的（要么是旧内容、要么是新内容，绝不会是空或半截）。
|
||||
|
||||
迁移成功后，这些官方老会话就出现在统一列表里了。**此刻你的数据**：① 原始副本在备份目录；② 活动文件里只有归类标签变了，内容完好。
|
||||
|
||||
> **注意**：开启与迁移本身**不会弹成功提示**。迁移是后端在保存时顺带跑的，UI 上你只会看到开关变成了打开状态。所以"没看到迁移成功的弹窗"是正常的，不代表失败。
|
||||
|
||||
---
|
||||
|
||||
## 关闭时会发生什么：分步说明
|
||||
|
||||
### 第 1 步：把开关从开拨到关 → 探测备份 → 弹出确认窗
|
||||
|
||||
关闭时，CC Switch 会**先花一瞬间探测有没有迁移备份**，然后弹出确认窗口（所以关闭弹窗会有一点点延迟，属正常）。文案如下（逐字）：
|
||||
|
||||
- **标题**：关闭统一会话历史
|
||||
- **正文**：
|
||||
|
||||
> 关闭后，官方订阅与第三方将恢复各自独立的会话历史列表。开启期间产生的会话因无法区分来源，将留在第三方历史中，官方订阅将看不到它们。
|
||||
|
||||
- **复选框**（条件显示）：把开启时迁入的官方会话还原回官方历史（按备份精确还原）
|
||||
- **确认按钮**：关闭
|
||||
- **取消按钮**：取消
|
||||
|
||||
> **划重点**：正文说的是"官方订阅**将看不到它们**"——是**看不到**，不是**删除**。开启期间你新聊的会话仍然完整地在 `custom` 抽屉里，只是关闭后官方那一侧看不到而已。
|
||||
|
||||
**这个还原复选框默认是勾选的。** 也就是说，默认行为就是"关闭的同时，把当初迁入的官方会话精确还原回官方历史"。你只要保持勾选、点"关闭"即可。
|
||||
|
||||
如果复选框**没有出现**，说明系统判断当前没有需要还原的备份（要么你从没勾过迁移、要么探测不到备份）——这种情况下你的官方老会话从没被改动过，关掉开关它们自己就回到 `openai` 抽屉了。
|
||||
|
||||
### 第 2 步：还原如何执行（按备份账本精确翻回）
|
||||
|
||||
如果你保持勾选并点"关闭"，CC Switch 的还原流程是这样的：
|
||||
|
||||
```text
|
||||
① 先把当前现场再复制一份到独立的还原备份目录
|
||||
~/.cc-switch/backups/codex-official-history-unify-restore-v1/<时间戳>/
|
||||
（还原本身也先备份，所以还原也不会丢数据）
|
||||
② 翻遍所有迁移备份代际，找出"当初标签是 openai"的会话 id，组成一份"账本"
|
||||
③ 只对【既在账本里、当前又仍是 custom】的会话，把标签改回 "openai"
|
||||
```
|
||||
|
||||
注意第 ③ 步的**双重条件**——既要在账本里（证明它当初确实是官方迁来的），又要当前仍是 `custom`（说明你没手动改过它）。两个条件都满足才翻回。这保证了还原既精确又不会误伤。
|
||||
|
||||
**此刻你的数据**：被迁回的官方会话标签改回 `openai`，重新出现在官方列表；同时迁移备份和还原备份两份副本都还在硬盘上。
|
||||
|
||||
### 第 3 步：看提示，确认结果
|
||||
|
||||
只有"关闭 + 勾选还原"这条路径会弹结果提示。可能看到的提示（逐字）：
|
||||
|
||||
| 你看到的提示 | 含义 |
|
||||
|---|---|
|
||||
| **已按备份还原官方会话历史（{{files}} 个会话文件、{{rows}} 条索引记录）** | 还原成功。`{{files}}` / `{{rows}}` 处会显示实际数字 |
|
||||
| **当前 Codex 目录没有可恢复的迁移备份** | 没有可还原的内容（**不等于数据丢了**，详见对照表场景 E） |
|
||||
| **统一会话历史开关已重新开启，已跳过还原** | 还原排队期间你又把开关打开了，系统主动放弃还原（详见对照表场景 F） |
|
||||
| **还原官方会话历史失败，请重试** | 还原过程报错，重试即可，数据未被破坏 |
|
||||
| **保存失败，请重试** | 关闭这一步保存本身就失败了；此时**绝不会触发还原**，开关弹回原位 |
|
||||
|
||||
> **一个贴心的安全设计**：如果"关闭开关"这一步保存失败，CC Switch **绝不会去执行还原**。否则就会出现"开关还开着、会话却被翻回 openai 桶"的撕裂状态。保存失败时开关会**自动弹回原来的位置**，你不会停留在一个"看起来已关、实则没保存"的假状态里。
|
||||
|
||||
---
|
||||
|
||||
## "我感觉会话丢了？"症状对照表
|
||||
|
||||
下面六个场景，是用户最容易误以为"会话丢了"的情形。**每一个的真相都是：数据完好，只是换了抽屉或暂时看不到。** 先用这张表按症状定位，再看下面的详细说明。
|
||||
|
||||
| 场景 | 你看到的 | 数据真相 | 一句话解法 |
|
||||
|---|---|---|---|
|
||||
| **A** 没勾迁移 | 官方老会话不在统一列表 | 全在，仍带 `openai` 标签 | 重开并勾迁移，或关开关 |
|
||||
| **B** 跨供应商续聊失败 | 续不上 / 报错 | 文件完好，只是密文跨后端解不开 | 回原供应商续；只看内容直接读 jsonl |
|
||||
| **C** 代理接管 / 注入被拒 | 没迁也没还原 | 迁移被安全跳过，文件没动 | 退出接管 → 重启重试；或直接关开关 |
|
||||
| **D** 还原后新会话没回官方 | 开启期间新会话不在官方 | 在 `custom` 抽屉，设计上不动 | 切第三方供应商即可见 |
|
||||
| **E** 提示"没有可恢复备份" | 还原"失败" | 通常压根没迁移过，会话在原抽屉 | 关开关官方会话自动复现 |
|
||||
| **F** 提示"开关已重新开启，跳过还原" | 还原被拒 | 防数据撕裂，啥也没改 | 先彻底关开关再还原 |
|
||||
|
||||
### 场景 A：开了开关但没勾迁移 → 官方老会话"不见了"
|
||||
|
||||
**现象**：你开了统一开关，但开启弹窗里那个"同时迁入现有官方会话历史"没勾（它默认就不勾）。开启后一看，以前的官方老会话好像都不在列表里了。
|
||||
|
||||
**真相**：数据 100% 都在，一行都没动。开关只对"开启之后新建"的官方会话生效，你**开启前**的官方老会话标签仍是 `openai`，原封不动地躺在 `~/.codex/sessions/` 里。你现在激活的是 `custom` 抽屉，自然看不到留在 `openai` 抽屉里的老会话——这就是"看起来消失"的全部原因。
|
||||
|
||||
**怎么办**（任选其一）：
|
||||
1. **重新开启开关时勾上"同时迁入现有官方会话历史"**，把老会话换到 `custom` 抽屉，它们立刻出现在统一列表（改写前自动备份）。
|
||||
2. **或者干脆关掉统一开关**，官方重新以 `openai` 抽屉运行，老会话原地复现。
|
||||
|
||||
### 场景 B：跨供应商续聊旧会话失败 → 以为"这条会话坏了 / 没了"
|
||||
|
||||
**现象**：统一之后列表里能看到一条用"另一家供应商"聊出来的旧会话，你切到现在的供应商点"继续"，结果报错或接不上。
|
||||
|
||||
**真相**：会话文件完好无损，丢的不是数据，是"跨后端解密能力"。Codex 会话里保存了一段加密的推理内容 `encrypted_content`，**这段密文只有当初生成它的那个后端能解密**。你用 B 供应商去续 A 供应商生成的会话，B 解不开 A 的密文 → 续聊失败。这是**上游 Codex 的设计限制（by design）**，与 CC Switch 是否动过文件无关。会话里的文字内容你随时能读到。
|
||||
|
||||
> 这是整篇攻略里**唯一一个"看起来真出了问题"的真实例外**——但请注意：它只是**无法续聊（生成不了新回合）**，**原始文件依然完整存在**，对话文字随时可读。
|
||||
|
||||
**怎么办**：
|
||||
- **用"当初创建这条会话的那个供应商"去续聊**，就能正常解密、接上。
|
||||
- 只想看历史内容、不必继续？直接读那条会话的 `.jsonl` 文件（文末有命令）。
|
||||
- 经验法则：**跨供应商更适合"开新会话"，老会话尽量回原供应商续。**
|
||||
|
||||
### 场景 C：开了开关也勾了迁移，但迁移被静默跳过 → 以为"迁移把会话弄丢了"
|
||||
|
||||
**现象**：你开启并勾了迁移，但官方老会话既没进统一列表、关开关想还原也提示没东西可还原（或者关闭弹窗里压根没出现还原复选框，参见场景 E）。你怀疑迁移过程中把会话搞丢了。
|
||||
|
||||
**真相**：迁移根本**没执行**，所以也不可能弄丢——你的会话一个字都没被改。CC Switch 在迁移前有一道安全闸门：它会检查 Codex 的 live 配置（`~/.codex/config.toml`）此刻是否**真的**路由到了共享 `custom` 抽屉，只有真路由过去了才迁移。以下两种情况会判定"还没统一"（内部原因码 `live_not_unified`），于是**主动跳过迁移、保留你的开关和迁移意愿、等条件满足后再迁**：
|
||||
|
||||
- **代理接管期间**：CC Switch 的代理接管了 live 配置，接管期的 live 不带统一路由标记。
|
||||
- **注入被拒**：你的 `config.toml` 已有手工指定的 `model_provider`，或已存在一张形态不同的 `[model_providers.custom]` 表（可能带第三方地址）。为避免把官方流量错误路由到第三方后端，CC Switch 宁可不注入、不迁移。
|
||||
|
||||
跳过迁移 = 不碰任何会话文件。**没迁，等于没动，谈不上丢。** 这是"安全延后"，不是"失败丢数据"。
|
||||
|
||||
**怎么办**：
|
||||
- 退出代理接管 → **重启 CC Switch**：启动时会自动重试迁移（你的迁移意愿一直保留着）。
|
||||
- 检查 `~/.codex/config.toml`：若有你手工写的冲突路由，整理掉冲突后再开开关。
|
||||
- 实在不想折腾：直接关开关，官方会话仍以 `openai` 抽屉正常显示，毫发无损。
|
||||
|
||||
### 场景 D：关了开关并还原，但"开启期间新聊的会话"没回官方 → 以为"新会话丢了"
|
||||
|
||||
**现象**：你开启统一期间，用官方又聊了几条新会话。后来关开关、勾了还原，还原完发现那几条新会话没回到官方抽屉。
|
||||
|
||||
**真相**：这是**有意为之**的设计，新会话好端端在 `custom` 抽屉里，能看见、能续。还原的依据是"迁移时的备份账本"——**只有当初从 `openai` 抽屉迁进来的会话**，备份里有据可查，才会被精确翻回 `openai`。你**开启期间新建**的会话不在任何备份账本里；而且统一之后官方和第三方都用 `custom` 标签，**CC Switch 无法分辨这条新会话到底是官方聊的还是第三方聊的**。为了不把第三方会话误塞进官方历史，产品决策是：这些新会话一律留在 `custom`（第三方）历史里，绝不自动搬动。关闭弹窗的文案也明示了这一点——"开启期间产生的会话因无法区分来源，将留在第三方历史中"。
|
||||
|
||||
**怎么办**：
|
||||
- 切到任意一个第三方供应商（`custom` 抽屉），就能在历史列表里看到这些会话。
|
||||
- 想看内容直接读 `.jsonl`；想续聊遵循场景 B 的规则（回到当初生成它的后端）。
|
||||
- 如果你确实想把**某一条**手动归回官方：目前没有自动按钮（刻意不做，避免误判方向）。进阶用户可在**先备份**该文件后，手动把它 `.jsonl` 第一行 `session_meta` 里的 `model_provider` 从 `custom` 改回 `openai`（属高阶操作，改前务必复制一份）。
|
||||
|
||||
### 场景 E：还原提示"当前 Codex 目录没有可恢复的迁移备份" → 以为"还原失败 = 数据没了"
|
||||
|
||||
**现象**：关开关时勾了还原，结果弹出提示"当前 Codex 目录没有可恢复的迁移备份"。你慌了：还原都失败了，是不是数据彻底没了？
|
||||
|
||||
**真相**："没有可还原的东西"≠"数据丢了"。恰恰相反，通常是因为**根本没有需要还原的迁移**。常见原因：
|
||||
|
||||
- **你当初没勾过"迁入现有官方会话"**：既然没迁移，自然没有迁移备份、也没有需要翻回去的会话。你的官方老会话一直在 `openai` 抽屉，关开关后直接复现（同场景 A）。（这种情况下，关闭弹窗甚至可能**根本不显示还原复选框**——因为系统探测不到任何备份。）
|
||||
- **已经还原过一遍了**：会话标签已全部翻回 `openai`，再点一次自然"没有仍是 custom 的目标可还原"——这是**幂等保护，不是失败**。
|
||||
- **切换过 Codex 目录**：还原只认属于**当前**目录的备份账本，换了目录就找不到旧目录的账本，把目录切回去即可。
|
||||
|
||||
这三种情况下，没有任何会话被删除。
|
||||
|
||||
**怎么办**：用文末命令统计 `~/.codex/sessions/` 里的会话文件总数，确认文件都在；再看 `~/.cc-switch/backups/` 里有没有 `codex-official-history-unify-v1` 目录——如果连这个目录都没有，说明你从没触发过迁移，会话一直在原抽屉。
|
||||
|
||||
### 场景 F：还原被拒，提示"统一会话历史开关已重新开启，已跳过还原"
|
||||
|
||||
**现象**：关开关 → 勾还原 → 你手很快，紧接着又把开关重新打开了，然后看到提示"统一会话历史开关已重新开启，已跳过还原"。
|
||||
|
||||
**真相**：这是一道防护，防止把数据弄成"撕裂"状态，会话同样没丢。还原的动作是"把会话标签从 `custom` 翻回 `openai`"，但如果此刻开关又开着，live 配置正路由到 `custom`——一边把历史翻回 `openai`、一边新会话往 `custom` 落，会话会被人为撕成两半。所以 CC Switch 检测到"开关又开了"，**主动放弃这次还原、什么都不改**。会话维持现状，没有任何删除或破坏。
|
||||
|
||||
**怎么办**：想真正还原，就**先把开关稳定地关掉**（别再立刻打开），再执行关闭 + 勾还原；想保持统一，就别还原，让会话留在 `custom` 共享抽屉正常使用。
|
||||
|
||||
**总原则：CC Switch 的统一 / 迁移 / 还原全程只改会话的一个标签字段，并且每次改写前都自动备份。它不会删你的对话。看不见 ≠ 丢了——换个抽屉看，或用下面的命令亲眼确认。**
|
||||
|
||||
---
|
||||
|
||||
## 亲手验证：你的会话文件还在硬盘上（最重要的一节）
|
||||
|
||||
文字再多，不如亲眼看见。下面给出**真实路径**（取自 CC Switch 源码）和在不同系统下查看会话文件、备份目录的方法。**全程只读不改，强烈建议你亲手试一遍。**
|
||||
|
||||
### 最简单的方式：用文件管理器直接打开（完全不用命令行）
|
||||
|
||||
- **macOS（Finder）**：按 `Cmd + Shift + G`，粘贴 `~/.codex/sessions` 回车，就能看到一堆 `.jsonl` 会话文件和它们的修改时间；备份目录粘贴 `~/.cc-switch/backups`。
|
||||
- **Windows（文件资源管理器）**：在地址栏粘贴 `%USERPROFILE%\.codex\sessions` 回车，就能看到会话文件夹和里面的 `.jsonl`；备份目录粘贴 `%USERPROFILE%\.cc-switch\backups`。
|
||||
|
||||
**只要你能在这里看到一批 `.jsonl` 文件，就证明会话数据完好无损地在硬盘上。** 文件数量、修改时间，比任何文字都直观。
|
||||
|
||||
### 你的会话 / 历史文件到底在哪
|
||||
|
||||
| 内容 | 真实路径 | 说明 |
|
||||
|---|---|---|
|
||||
| **会话正文（核心）** | `~/.codex/sessions/`（含按日期分的子目录，递归） | 每个会话一个 `.jsonl` 文本文件，**这就是你的对话内容** |
|
||||
| **归档会话** | `~/.codex/archived_sessions/` | 同为 `.jsonl` |
|
||||
| **会话索引数据库** | `~/.codex/state_5.sqlite` | `threads` 表的 `model_provider` 列就是"抽屉标签"，**它才是续聊列表真正读取的归类来源** |
|
||||
| **迁移备份**（开启迁移时自动产生） | `~/.cc-switch/backups/codex-official-history-unify-v1/<时间戳>/` | 内含 `jsonl/`、`state/`、`meta.json` |
|
||||
| **还原备份**（点还原时自动产生） | `~/.cc-switch/backups/codex-official-history-unify-restore-v1/<时间戳>/` | 还原前的安全副本 |
|
||||
|
||||
> **注意**：如果你在 CC Switch 里改过 Codex 目录，或在 `config.toml` 里设了 `sqlite_home`，请把上面的 `~/.codex` 换成你的实际目录。下文 `~` = 你的用户主目录。
|
||||
|
||||
### macOS / Linux 命令
|
||||
|
||||
**1. 数会话文件总数（这才是"没丢"的硬证据）**
|
||||
|
||||
```bash
|
||||
# 统计会话文件总数 —— 只要这个数字符合你的预期，数据就都在
|
||||
find ~/.codex/sessions ~/.codex/archived_sessions -name '*.jsonl' 2>/dev/null | wc -l
|
||||
|
||||
# 看最近修改的 10 个会话文件
|
||||
find ~/.codex/sessions -name '*.jsonl' 2>/dev/null -print0 \
|
||||
| xargs -0 ls -lt 2>/dev/null | head -10
|
||||
```
|
||||
|
||||
**2. （辅助）看每个"抽屉"各有多少会话**
|
||||
|
||||
```bash
|
||||
# 官方抽屉（openai）会话文件数
|
||||
grep -rlE '"model_provider"[[:space:]]*:[[:space:]]*"openai"' ~/.codex/sessions 2>/dev/null | wc -l
|
||||
|
||||
# 统一抽屉（custom）会话文件数
|
||||
grep -rlE '"model_provider"[[:space:]]*:[[:space:]]*"custom"' ~/.codex/sessions 2>/dev/null | wc -l
|
||||
|
||||
# 看各标签分布一目了然
|
||||
grep -rhoE '"model_provider"[[:space:]]*:[[:space:]]*"[^"]*"' ~/.codex/sessions 2>/dev/null | sort | uniq -c
|
||||
```
|
||||
|
||||
> **重要提示，别被这一步吓到**：**早期版本的 Codex 不在 `.jsonl` 里写 `model_provider` 字段**，这些旧官方会话用上面的 grep 是**数不到**的，但它们在索引库 `state_5.sqlite` 里仍然归类为 `openai`、续聊列表照样能看到。所以**判断"会话没丢"请以第 1 步的文件总数为准**——分桶 grep 只是帮你理解归类，数出来比文件总数少**完全正常**，绝不代表"丢了一批"。
|
||||
|
||||
**3. （进阶）查索引库 `state_5.sqlite`——续聊列表真正读的归类**
|
||||
|
||||
```bash
|
||||
# 需要已安装 sqlite3；没装可跳过
|
||||
sqlite3 ~/.codex/state_5.sqlite \
|
||||
"SELECT COALESCE(model_provider,'<空>'), COUNT(*) FROM threads GROUP BY 1;"
|
||||
```
|
||||
|
||||
> 这张 `threads` 表才是 Codex 续聊列表真正读取的归类来源，`openai` 行数 ≈ 你官方抽屉里能看到的会话数。它和第 2 步的 jsonl grep 可能对不上数——原因就是上面说的"旧会话不写 jsonl 字段，但索引库里仍是 openai"。两边对不上不是异常。
|
||||
|
||||
**4. 直接读某条会话的内容（确认对话文字还在）**
|
||||
|
||||
```bash
|
||||
# 把 <文件名> 换成上面 ls 列出的某个 .jsonl 路径
|
||||
python3 -m json.tool < "<文件名>.jsonl" 2>/dev/null | head -50
|
||||
|
||||
# 或者直接用编辑器打开看（纯文本）
|
||||
open -e "<文件名>.jsonl" # macOS
|
||||
```
|
||||
|
||||
**5. 看 CC Switch 的备份目录（证明迁移 / 还原前都留了副本）**
|
||||
|
||||
```bash
|
||||
ls -la ~/.cc-switch/backups/codex-official-history-unify-v1/ 2>/dev/null
|
||||
ls -la ~/.cc-switch/backups/codex-official-history-unify-restore-v1/ 2>/dev/null
|
||||
```
|
||||
|
||||
### Windows 命令（PowerShell）
|
||||
|
||||
会话目录通常在 `C:\Users\<你的用户名>\.codex\`，备份在 `C:\Users\<你的用户名>\.cc-switch\backups\`。
|
||||
|
||||
```powershell
|
||||
# 1. 会话文件总数（"没丢"的硬证据）
|
||||
(Get-ChildItem "$env:USERPROFILE\.codex\sessions","$env:USERPROFILE\.codex\archived_sessions" -Recurse -Filter *.jsonl -ErrorAction SilentlyContinue).Count
|
||||
|
||||
# 2. 最近修改的 10 个会话
|
||||
Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
|
||||
Sort-Object LastWriteTime -Descending | Select-Object -First 10 FullName,LastWriteTime
|
||||
|
||||
# 3. （辅助）官方(openai) / 统一(custom) 抽屉各多少会话文件
|
||||
(Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
|
||||
Select-String -Pattern 'model_provider"\s*:\s*"openai"' -List).Count
|
||||
(Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
|
||||
Select-String -Pattern 'model_provider"\s*:\s*"custom"' -List).Count
|
||||
|
||||
# 4. 看备份目录
|
||||
Get-ChildItem "$env:USERPROFILE\.cc-switch\backups\codex-official-history-unify-v1" -ErrorAction SilentlyContinue
|
||||
Get-ChildItem "$env:USERPROFILE\.cc-switch\backups\codex-official-history-unify-restore-v1" -ErrorAction SilentlyContinue
|
||||
```
|
||||
|
||||
> 同样提醒：第 3 步的 grep 数会**少于**文件总数属正常（旧会话不写该字段），请以第 1 步的**文件总数**作为"会话没丢"的判断依据。
|
||||
|
||||
---
|
||||
|
||||
## 进阶原理附录（给想真正搞懂机制的用户）
|
||||
|
||||
### 1. 分桶机制（抽屉的本质）
|
||||
|
||||
Codex 的续聊 / 历史列表按当前激活的 `model_provider` id **精确字符串过滤**。会话文件 `.jsonl` 的**第一行**是一条 `type:"session_meta"` 记录，其 `payload.model_provider` 即该会话所属抽屉（`grep -rl` 只要文件里出现一次该标签就计入该文件，因此无需逐行解析；旧版本未写该字段的会话则数不到）。真正驱动续聊列表的是索引库 `state_5.sqlite` 的 `threads.model_provider` 列。官方订阅在 `config.toml` 没有显式 `model_provider` 时落进内建默认 id `openai`；CC Switch 的所有第三方供应商统一用 `custom`。
|
||||
|
||||
### 2. 开关做的事（注入，只活在 live）
|
||||
|
||||
开启后，CC Switch 对官方 live `config.toml` 注入如下内容：
|
||||
|
||||
```toml
|
||||
model_provider = "custom"
|
||||
|
||||
[model_providers.custom]
|
||||
name = "OpenAI"
|
||||
requires_openai_auth = true
|
||||
supports_websockets = true
|
||||
wire_api = "responses"
|
||||
```
|
||||
|
||||
每个字段都有作用：`requires_openai_auth = true` 让认证继续走 `auth.json` 里的 ChatGPT 登录、base_url 缺省回落官方 Codex 后端；`name = "OpenAI"` 让 Codex 的官方特性门控（web search、远程压缩等）继续命中；`supports_websockets = true` 补回 custom 条目默认丢失的能力；`wire_api = "responses"` 用官方 responses 协议。**净效果是：认证没变，只是桶名变了。**
|
||||
|
||||
**关键不变量：这段注入只能存在于 live `config.toml`，绝不写进数据库的存储配置。** 切换离开官方供应商、把 live 回写数据库时，CC Switch 会把这段注入精确剥离（只在形态与注入产物完全一致时才剥，第三方自定义的 `custom` 表原样保留）。正因如此，"关掉开关 + 切换一次"就能彻底还原 live，数据库里始终是你原本干净的官方配置——这是整个开关可逆性的基石。
|
||||
|
||||
### 3. 注入的两道拒绝闸（对应场景 C）
|
||||
|
||||
- `config.toml` 已有显式 `model_provider` → 不覆盖用户路由；
|
||||
- 已存在形态不同的 `[model_providers.custom]` 表（可能带第三方 `base_url`）→ 拒绝注入，否则会把 ChatGPT OAuth 流量路由到错误后端。
|
||||
|
||||
拒绝注入时 live 不统一，迁移闸门（检查 live 的 `model_provider` 是否 trim 后等于 `custom`）判定 `live_not_unified` → 跳过迁移、保留意愿、等下次启动重试时再做。这是"安全延后"，不是"失败丢数据"。
|
||||
|
||||
### 4. 会话三分类（决定迁移 / 还原边界）
|
||||
|
||||
- **A 类**：开启时迁入的存量官方会话——备份即账本，可精确还原回 `openai`；
|
||||
- **B 类**：开启期间新建——不在任何备份、官方 / 第三方不可分，**永不自动搬动**（留 `custom`）；
|
||||
- **C 类**：开启前的纯第三方历史——绝不触碰。
|
||||
|
||||
### 5. 迁移 / 还原的安全性（数据不会被真正删除，保障来自哪里）
|
||||
|
||||
四层设计共同保证：在**正常与异常的所有路径**下，原始会话数据都不会被真正删除。
|
||||
|
||||
- **只改字段，不动正文**：迁移 / 还原只把会话元数据里的 `model_provider` 值在 `openai` 与 `custom` 之间切换，对话内容、`response_item`、`encrypted_content` 一律原样保留。
|
||||
- **改写前必先复制备份**：jsonl 用文件复制、state DB 用 SQLite 完整副本，存进时间戳代际目录。迁移备份在 `codex-official-history-unify-v1/`，还原备份在独立的 `codex-official-history-unify-restore-v1/`，两者分开以保持账本纯净。
|
||||
- **只移不删 + 原子写**：所有 jsonl 改写走"临时文件 + 整体替换"，state DB 走事务化 `UPDATE`，全程没有任何删除会话或索引的动作。文件在任一时刻都是完整的。
|
||||
- **悲观跳过 + 幂等可重试**：桶不一致时（`live_not_unified`）宁可不迁；一把进程锁串行化迁移与还原，避免"启动重试 / 保存后台任务 / 关闭还原"并发对同批文件双向改写；完成标记按 Codex 目录绑定、条件写入，防漏迁；还原用"在账本 + 当前仍 custom"双重条件，防误改。还原扫描全部备份代际取并集，多次开关循环后仍能还原早期迁入的会话；重复还原返回 `nothing_to_restore`，是幂等保护而非失败。
|
||||
|
||||
### 6. 跨后端 encrypted_content（对应场景 B）
|
||||
|
||||
会话内的推理密文只能被生成它的后端解密，上游 Codex by design 不支持跨后端解密。这是"续聊失败"的根因，与文件完整性无关——会话 `.jsonl` 完整躺在磁盘上、`encrypted_content` 也完好无损。换回原供应商续聊，或开新会话，都正常。
|
||||
|
||||
---
|
||||
|
||||
## 参考链接
|
||||
|
||||
- [使用第三方 API 时保留 Codex 远程操作和官方插件：CC Switch 配置攻略](./codex-official-auth-preservation-guide-zh.md)
|
||||
- [在 Codex 中使用 DeepSeek 这类 Chat 格式 API：CC Switch 路由攻略](./codex-deepseek-routing-guide-zh.md)
|
||||
- CC Switch 用户手册中「Codex 应用增强」相关章节
|
||||
|
||||
---
|
||||
|
||||
**给你的最后一句话**：你看到的"会话不见了 / 续聊失败"，本质是**会话被换到了另一个历史列表（抽屉）里、或对方后端无法解密旧推理内容**，文件始终原封不动地躺在 `~/.codex/sessions/`（及 `state_5.sqlite`）里。关闭开关时勾选"按备份还原"即可把当初迁入的官方会话精确翻回官方列表；即便不还原，原始 `.jsonl` 文件和 `~/.cc-switch/backups/codex-official-history-unify-*/` 下的备份副本也都在——**数据绝不会真正丢失。**
|
||||
@@ -0,0 +1,165 @@
|
||||
# CC Switch 代理功能使用指南
|
||||
|
||||
## 功能介绍
|
||||
|
||||
CC Switch 的代理功能是一个本地 HTTP 代理服务器，可以统一管理 Claude Code、Codex 和 Gemini CLI 的 API 请求。主要特性包括：
|
||||
|
||||
- **统一代理入口** - 所有 CLI 应用的请求通过本地代理转发
|
||||
- **自动故障转移** - 当前供应商故障时自动切换到备用供应商
|
||||
- **按应用控制** - 可独立控制每个应用是否启用代理
|
||||
- **配置保护** - 自动备份原始配置，停止代理时安全恢复
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 启动代理
|
||||
|
||||
在 CC Switch 主界面，点击右上角的 **Proxy** 按钮，可以看到代理控制面板。
|
||||
|
||||
点击 **启动代理** 按钮启动本地代理服务器。代理默认监听 `127.0.0.1:15721`。
|
||||
|
||||
### 2. 启用应用接管
|
||||
|
||||
代理启动后，你可以选择让哪些应用的请求通过代理：
|
||||
|
||||
- **Claude** - 接管 Claude Code 的 API 请求
|
||||
- **Codex** - 接管 Codex CLI 的 API 请求
|
||||
- **Gemini** - 接管 Gemini CLI 的 API 请求
|
||||
|
||||
点击对应应用的开关即可启用/禁用接管。
|
||||
|
||||
> **注意**：启用接管后，CC Switch 会自动修改对应应用的配置文件，将 API 端点指向本地代理。原始配置会被安全备份。
|
||||
|
||||
### 3. 正常使用 CLI
|
||||
|
||||
启用接管后，你可以正常使用各个 CLI 工具。所有请求都会经过 CC Switch 代理转发到配置的供应商。
|
||||
|
||||
### 4. 停止代理
|
||||
|
||||
当你不再需要代理时，点击 **停止代理** 按钮。CC Switch 会：
|
||||
|
||||
1. 安全关闭代理服务器
|
||||
2. 自动恢复所有应用的原始配置
|
||||
3. 清除代理状态
|
||||
|
||||
## 自动故障转移
|
||||
|
||||
### 工作原理
|
||||
|
||||
代理功能内置了智能故障转移机制：
|
||||
|
||||
1. **健康监控** - 实时监控每个供应商的响应状态
|
||||
2. **熔断器** - 连续失败 5 次后触发熔断，暂停使用该供应商
|
||||
3. **自动切换** - 熔断后自动切换到列表中的下一个供应商
|
||||
4. **自动恢复** - 30 秒后尝试恢复熔断的供应商
|
||||
|
||||
### 配置故障转移
|
||||
|
||||
要使用故障转移功能，你需要：
|
||||
|
||||
1. 在对应应用下添加多个供应商（至少 2 个）
|
||||
2. 启动代理并启用接管
|
||||
3. 当主供应商故障时，代理会自动切换到备用供应商
|
||||
|
||||
### 健康状态指示
|
||||
|
||||
在供应商卡片上可以看到健康状态指示：
|
||||
|
||||
- **绿色** - 供应商正常
|
||||
- **红色** - 供应商故障/熔断中
|
||||
- **灰色** - 未使用代理或未检测
|
||||
|
||||
## 按应用接管
|
||||
|
||||
v3.9.0 新增了按应用分粒度控制功能：
|
||||
|
||||
- 你可以只接管 Claude，而让 Codex 使用原始配置
|
||||
- 每个应用的接管状态独立管理
|
||||
- 启用/禁用不会影响其他应用
|
||||
|
||||
### 接管状态检测
|
||||
|
||||
CC Switch 通过检测配置备份来判断接管状态：
|
||||
|
||||
- 存在备份 = 已接管
|
||||
- 无备份 = 未接管
|
||||
|
||||
这确保了即使 CC Switch 异常退出，重新启动后也能正确识别状态。
|
||||
|
||||
## 代理配置
|
||||
|
||||
在代理面板中，你可以配置以下参数：
|
||||
|
||||
| 参数 | 默认值 | 说明 |
|
||||
|------|--------|------|
|
||||
| 监听地址 | 127.0.0.1 | 代理服务器绑定地址 |
|
||||
| 监听端口 | 15721 | 代理服务器端口 |
|
||||
| 最大重试 | 3 | 请求失败时的最大重试次数 |
|
||||
| 请求超时 | 120 秒 | 单个请求的超时时间 |
|
||||
| 启用日志 | 是 | 是否记录请求日志 |
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 代理启动失败，提示端口被占用？
|
||||
|
||||
A: 默认端口 15721 可能被其他程序占用。你可以：
|
||||
- 关闭占用该端口的程序
|
||||
- 在代理配置中修改端口号
|
||||
|
||||
### Q: 启用接管后 CLI 无法使用？
|
||||
|
||||
A: 请检查：
|
||||
1. 代理服务器是否正常运行（查看代理面板状态）
|
||||
2. 供应商配置是否正确（API Key 等）
|
||||
3. 网络连接是否正常
|
||||
|
||||
### Q: 如何恢复原始配置？
|
||||
|
||||
A: 点击 **停止代理** 按钮，CC Switch 会自动恢复所有应用的原始配置。
|
||||
|
||||
如果 CC Switch 异常退出，重新启动后会检测到之前的备份，你可以：
|
||||
- 点击停止代理来恢复配置
|
||||
- 或继续使用代理功能
|
||||
|
||||
### Q: 故障转移没有生效？
|
||||
|
||||
A: 请确保：
|
||||
1. 配置了至少 2 个供应商
|
||||
2. 代理已启动且接管已启用
|
||||
3. 故障转移只在代理模式下工作
|
||||
|
||||
### Q: 代理会影响性能吗？
|
||||
|
||||
A: 本地代理的延迟开销非常小（通常 < 1ms）。但如果启用了请求日志，在高频请求场景下可能会有少量性能影响。
|
||||
|
||||
## 技术细节
|
||||
|
||||
### 配置文件位置
|
||||
|
||||
启用接管后，CC Switch 会修改以下配置文件：
|
||||
|
||||
| 应用 | 配置文件 | 修改内容 |
|
||||
|------|----------|----------|
|
||||
| Claude | `~/.claude/settings.json` | `apiBaseUrl` 指向代理 |
|
||||
| Codex | `~/.codex/config.toml` | `[api] baseUrl` 指向代理 |
|
||||
| Gemini | `~/.gemini/.env` | `GEMINI_BASE_URL` 指向代理 |
|
||||
|
||||
原始配置备份在 CC Switch 数据库中，停止代理时自动恢复。
|
||||
|
||||
### 代理模式
|
||||
|
||||
代理服务器运行在接管模式下，会：
|
||||
|
||||
1. 接收来自 CLI 的 HTTPS 请求
|
||||
2. 根据当前供应商配置转发到真实 API 端点
|
||||
3. 返回响应给 CLI
|
||||
4. 记录请求日志和健康状态
|
||||
|
||||
### 数据库表
|
||||
|
||||
代理功能使用以下数据库表：
|
||||
|
||||
- `proxy_config` - 代理配置
|
||||
- `provider_health` - 供应商健康状态
|
||||
- `proxy_request_logs` - 请求日志
|
||||
- `circuit_breaker_config` - 熔断器配置
|
||||
- `proxy_live_backup` - Live 配置备份
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 87 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 159 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 116 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 373 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 268 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 295 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 185 KiB |
@@ -0,0 +1,206 @@
|
||||
# CC Switch v3.10.0
|
||||
|
||||
> OpenCode Support, Global Proxy, Claude Rectifier & Multi-App Experience Enhancements
|
||||
|
||||
**[中文版 →](v3.10.0-zh.md) | [日本語版 →](v3.10.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.10.0 introduces OpenCode support, becoming the fourth managed CLI application.
|
||||
This release also brings global proxy settings, Claude Rectifier (thinking signature fixer), enhanced health checks, per-provider configuration, and many other important features, along with comprehensive improvements to multi-app workflows and terminal experience.
|
||||
|
||||
**Release Date**: 2026-01-21
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- OpenCode Support: Full management of providers, MCP servers, and Skills with auto-import on first launch
|
||||
- Global Proxy: Configure a unified proxy for all outbound network requests
|
||||
- Claude Rectifier: Thinking signature fixer for better compatibility with third-party APIs
|
||||
- Enhanced Health Checks: Configurable prompts and CLI-compatible request format
|
||||
- Per-Provider Config: Persistent provider-specific configuration support
|
||||
- App Visibility Control: Freely show/hide apps with synchronized tray menu updates
|
||||
- Terminal Improvements: Provider-specific terminal buttons, fnm path support, cross-platform safe launch
|
||||
- WSL Tool Detection: Detect tool versions in WSL environment with security hardening
|
||||
|
||||
---
|
||||
|
||||
## Main Features
|
||||
|
||||
### OpenCode Support (New Fourth App)
|
||||
|
||||
- Complete OpenCode provider management: add, edit, switch, delete
|
||||
- MCP server management: unified architecture with Claude/Codex/Gemini
|
||||
- Skills support: OpenCode can also use Skills functionality
|
||||
- Auto-import on first launch: automatically imports existing OpenCode configuration when detected
|
||||
- Full internationalization: Chinese/English/Japanese support (#695)
|
||||
|
||||
### Global Proxy
|
||||
|
||||
- Configure a unified proxy for all outbound network requests (#596, thanks @yovinchen)
|
||||
- Supports HTTP/HTTPS proxy protocols
|
||||
- Suitable for network environments requiring proxy access to external APIs
|
||||
|
||||
### Claude Rectifier (Thinking Signature Fixer)
|
||||
|
||||
- Automatically fixes Claude API thinking signatures (#595, thanks @yovinchen)
|
||||
- Resolves incompatible thinking block formats returned by some third-party API gateways
|
||||
- Can be enabled/disabled in Advanced Settings
|
||||
|
||||
### Enhanced Health Checks
|
||||
|
||||
- Configurable custom prompts for streaming health checks (#623, thanks @yovinchen)
|
||||
- Supports CLI-compatible request format for better simulation of real usage scenarios
|
||||
- Improves fault detection accuracy
|
||||
|
||||
### Per-Provider Config
|
||||
|
||||
- Support for saving configuration separately for each provider (#663, thanks @yovinchen)
|
||||
- Persistent configuration: provider-specific settings retained after restart
|
||||
- Suitable for scenarios where different providers require different configurations
|
||||
|
||||
### App Visibility Control
|
||||
|
||||
- Freely show/hide any app (Gemini hidden by default)
|
||||
- Tray menu automatically syncs visibility settings
|
||||
- Hidden apps won't appear in the main interface or tray menu
|
||||
|
||||
### Takeover Compact Mode
|
||||
|
||||
- Automatically uses compact layout when 3 or more visible apps are displayed
|
||||
- Optimizes space utilization in multi-app scenarios
|
||||
|
||||
### Terminal Improvements
|
||||
|
||||
- Provider-specific terminal button: one-click to use current provider in terminal (#564, thanks @kkkman22)
|
||||
- `fnm` path support: automatically recognizes Node.js paths managed by fnm
|
||||
- Cross-platform safe launch: improved terminal launch logic for Windows/macOS/Linux
|
||||
|
||||
### WSL Tool Detection
|
||||
|
||||
- Detect tool versions in WSL environment (#627, thanks @yovinchen)
|
||||
- Added security hardening to prevent command injection risks
|
||||
|
||||
### Skills Preset Enhancements
|
||||
|
||||
- Added `baoyu-skills` preset repository
|
||||
- Automatically supplements missing default repositories for out-of-the-box experience
|
||||
|
||||
---
|
||||
|
||||
## Experience Improvements
|
||||
|
||||
- Keyboard shortcuts: Press `ESC` to quickly return/close panels (#670, thanks @xxk8)
|
||||
- Simplified proxy logs: cleaner and more readable output (#585, thanks @yovinchen)
|
||||
- Pricing editor UX: unified `FullScreenPanel` style
|
||||
- Advanced settings layout: Rectifier section moved below Failover for better logical flow
|
||||
- OpenRouter compatibility mode: disabled by default, UI toggle hidden (reduces clutter)
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Proxy & Failover
|
||||
|
||||
- Immediately switch to P1 when auto-failover is enabled (instead of waiting for next request)
|
||||
|
||||
### Provider Management
|
||||
|
||||
- Fixed stale data when reopening provider edit dialog after save (#654, thanks @YangYongAn)
|
||||
- Fixed baseUrl and apiKey state not resetting when switching presets
|
||||
- Fixed endpoint auto-selection state not persisting (#611, thanks @yovinchen)
|
||||
- Automatically apply default color when icon color is not set
|
||||
|
||||
### Deep Links
|
||||
|
||||
- Support multi-endpoint import (#597, thanks @yovinchen)
|
||||
- Prefer `GOOGLE_GEMINI_BASE_URL` over `GEMINI_BASE_URL`
|
||||
|
||||
### MCP
|
||||
|
||||
- Skip `cmd /c` wrapper for WSL target paths (#592, thanks @cxyfer)
|
||||
|
||||
### Usage Templates
|
||||
|
||||
- Added variable hints, fixed validation issues (#628, thanks @YangYongAn)
|
||||
- Prevent configuration leakage between providers
|
||||
- Usage block offset automatically adapts to action button width (#613, thanks @yovinchen)
|
||||
|
||||
### Gemini
|
||||
|
||||
- Convert timeout parameters to Gemini CLI format (#580, thanks @cxyfer)
|
||||
|
||||
### UI
|
||||
|
||||
- Fixed Select dropdown rendering issues in `FullScreenPanel`
|
||||
|
||||
---
|
||||
|
||||
## Notes & Considerations
|
||||
|
||||
- **OpenCode is a newly supported app**: OpenCode CLI must be installed first to use related features.
|
||||
- **Global proxy affects all outbound requests**: including usage queries, health checks, and other network operations.
|
||||
- **Rectifier is experimental**: can be disabled in Advanced Settings if issues occur.
|
||||
|
||||
---
|
||||
|
||||
## Special Thanks
|
||||
|
||||
Thanks to @yovinchen @YangYongAn @cxyfer @xxk8 @kkkman22 @Shuimo03 for their contributions to this release!
|
||||
Thanks to @libukai for designing the elegant failover-related UI!
|
||||
|
||||
---
|
||||
|
||||
## 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.10.0-Windows.msi` | **Recommended** - MSI installer with auto-update |
|
||||
| `CC-Switch-v3.10.0-Windows-Portable.zip` | Portable version, extract and run, no registry write |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| -------------------------------- | ------------------------------------------------------------------ |
|
||||
| `CC-Switch-v3.10.0-macOS.zip` | **Recommended** - Extract and drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.10.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` |
|
||||
@@ -0,0 +1,206 @@
|
||||
# CC Switch v3.10.0
|
||||
|
||||
> OpenCode サポート、グローバルプロキシ、Claude Rectifier とマルチアプリ体験の強化
|
||||
|
||||
**[中文版 →](v3.10.0-zh.md) | [English →](v3.10.0-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.10.0 では OpenCode サポートが追加され、4番目の管理対象 CLI アプリケーションとなりました。
|
||||
また、グローバルプロキシ設定、Claude Rectifier（thinking 署名修正機能）、ヘルスチェックの強化、プロバイダー別設定など、多くの重要な機能が追加され、マルチアプリワークフローとターミナル体験が全面的に改善されました。
|
||||
|
||||
**リリース日**: 2026-01-21
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- OpenCode サポート：プロバイダー、MCP サーバー、Skills の完全管理、初回起動時の自動インポート
|
||||
- グローバルプロキシ：すべての送信ネットワークリクエストに統一プロキシを設定
|
||||
- Claude Rectifier：thinking 署名修正機能、サードパーティ API との互換性向上
|
||||
- ヘルスチェック強化：カスタムプロンプト設定、CLI 互換リクエスト形式
|
||||
- プロバイダー別設定：プロバイダー固有の設定の永続化をサポート
|
||||
- アプリ表示制御：アプリの表示/非表示を自由に設定、トレイメニューと同期
|
||||
- ターミナル改善：プロバイダー専用ターミナルボタン、fnm パスサポート、クロスプラットフォーム安全起動
|
||||
- WSL ツール検出：WSL 環境でのツールバージョン検出とセキュリティ強化
|
||||
|
||||
---
|
||||
|
||||
## 主な機能
|
||||
|
||||
### OpenCode サポート（新しい4番目のアプリ）
|
||||
|
||||
- 完全な OpenCode プロバイダー管理：追加、編集、切り替え、削除
|
||||
- MCP サーバー管理：Claude/Codex/Gemini と統一されたアーキテクチャ
|
||||
- Skills サポート：OpenCode でも Skills 機能を使用可能
|
||||
- 初回起動時の自動インポート：既存の OpenCode 設定を検出すると自動的にインポート
|
||||
- 完全な国際化：中国語/英語/日本語サポート (#695)
|
||||
|
||||
### グローバルプロキシ
|
||||
|
||||
- すべての送信ネットワークリクエストに統一プロキシを設定 (#596、@yovinchen に感謝)
|
||||
- HTTP/HTTPS プロキシプロトコルをサポート
|
||||
- 外部 API へのプロキシアクセスが必要なネットワーク環境に適用
|
||||
|
||||
### Claude Rectifier（Thinking 署名修正機能）
|
||||
|
||||
- Claude API の thinking 署名を自動修正 (#595、@yovinchen に感謝)
|
||||
- 一部のサードパーティ API ゲートウェイが返す互換性のない thinking ブロック形式を解決
|
||||
- 詳細設定で有効/無効を切り替え可能
|
||||
|
||||
### ヘルスチェック強化
|
||||
|
||||
- ストリーミングヘルスチェック用のカスタムプロンプトを設定可能 (#623、@yovinchen に感謝)
|
||||
- CLI 互換リクエスト形式をサポートし、実際の使用シナリオをより良くシミュレート
|
||||
- 障害検出の精度を向上
|
||||
|
||||
### プロバイダー別設定
|
||||
|
||||
- 各プロバイダーごとに設定を個別に保存可能 (#663、@yovinchen に感謝)
|
||||
- 設定の永続化：再起動後もプロバイダー固有の設定を保持
|
||||
- 異なるプロバイダーに異なる設定が必要なシナリオに適用
|
||||
|
||||
### アプリ表示制御
|
||||
|
||||
- 任意のアプリを自由に表示/非表示（Gemini はデフォルトで非表示）
|
||||
- トレイメニューは表示設定と自動的に同期
|
||||
- 非表示のアプリはメインインターフェースとトレイメニューに表示されない
|
||||
|
||||
### Takeover コンパクトモード
|
||||
|
||||
- 3つ以上の表示アプリがある場合、自動的にコンパクトレイアウトを使用
|
||||
- マルチアプリシナリオでのスペース利用を最適化
|
||||
|
||||
### ターミナル改善
|
||||
|
||||
- プロバイダー専用ターミナルボタン：ワンクリックでターミナルで現在のプロバイダーを使用 (#564、@kkkman22 に感謝)
|
||||
- `fnm` パスサポート：fnm で管理された Node.js パスを自動認識
|
||||
- クロスプラットフォーム安全起動：Windows/macOS/Linux のターミナル起動ロジックを改善
|
||||
|
||||
### WSL ツール検出
|
||||
|
||||
- WSL 環境でツールバージョンを検出 (#627、@yovinchen に感謝)
|
||||
- コマンドインジェクションリスクを防ぐためのセキュリティ強化を追加
|
||||
|
||||
### Skills プリセット強化
|
||||
|
||||
- `baoyu-skills` プリセットリポジトリを追加
|
||||
- 不足しているデフォルトリポジトリを自動補完し、すぐに使える状態を確保
|
||||
|
||||
---
|
||||
|
||||
## 体験の改善
|
||||
|
||||
- キーボードショートカット：`ESC` を押してパネルをすばやく戻る/閉じる (#670、@xxk8 に感謝)
|
||||
- プロキシログの簡素化：より明確で読みやすい出力 (#585、@yovinchen に感謝)
|
||||
- 価格エディター UX：統一された `FullScreenPanel` スタイル
|
||||
- 詳細設定レイアウト：Rectifier セクションを Failover の下に移動し、論理的な流れを改善
|
||||
- OpenRouter 互換モード：デフォルトで無効、UI トグルを非表示（煩雑さを軽減）
|
||||
|
||||
---
|
||||
|
||||
## バグ修正
|
||||
|
||||
### プロキシとフェイルオーバー
|
||||
|
||||
- 自動フェイルオーバーが有効な場合、すぐに P1 に切り替え（次のリクエストを待たずに）
|
||||
|
||||
### プロバイダー管理
|
||||
|
||||
- 保存後にプロバイダー編集ダイアログを再度開いたときにデータが古い問題を修正 (#654、@YangYongAn に感謝)
|
||||
- プリセット切り替え時に baseUrl と apiKey の状態がリセットされない問題を修正
|
||||
- エンドポイント自動選択状態が永続化されない問題を修正 (#611、@yovinchen に感謝)
|
||||
- アイコンカラーが設定されていない場合、デフォルトカラーを自動適用
|
||||
|
||||
### ディープリンク
|
||||
|
||||
- マルチエンドポイントインポートをサポート (#597、@yovinchen に感謝)
|
||||
- `GEMINI_BASE_URL` より `GOOGLE_GEMINI_BASE_URL` を優先
|
||||
|
||||
### MCP
|
||||
|
||||
- WSL ターゲットパスの `cmd /c` ラッパーをスキップ (#592、@cxyfer に感謝)
|
||||
|
||||
### 使用量テンプレート
|
||||
|
||||
- 変数ヒントを追加、検証の問題を修正 (#628、@YangYongAn に感謝)
|
||||
- プロバイダー間での設定漏洩を防止
|
||||
- 使用量ブロックのオフセットがアクションボタンの幅に自動適応 (#613、@yovinchen に感謝)
|
||||
|
||||
### Gemini
|
||||
|
||||
- タイムアウトパラメータを Gemini CLI 形式に変換 (#580、@cxyfer に感謝)
|
||||
|
||||
### UI
|
||||
|
||||
- `FullScreenPanel` での Select ドロップダウンのレンダリング問題を修正
|
||||
|
||||
---
|
||||
|
||||
## 注意事項
|
||||
|
||||
- **OpenCode は新しくサポートされたアプリです**：関連機能を使用するには、まず OpenCode CLI をインストールする必要があります。
|
||||
- **グローバルプロキシはすべての送信リクエストに影響します**：使用量クエリ、ヘルスチェックなどのネットワーク操作を含みます。
|
||||
- **Rectifier は実験的機能です**：問題が発生した場合は、詳細設定で無効にできます。
|
||||
|
||||
---
|
||||
|
||||
## 特別な感謝
|
||||
|
||||
@yovinchen @YangYongAn @cxyfer @xxk8 @kkkman22 @Shuimo03 の皆様、このリリースへの貢献に感謝します！
|
||||
@libukai 様、エレガントなフェイルオーバー関連 UI のデザインに感謝します！
|
||||
|
||||
---
|
||||
|
||||
## ダウンロードとインストール
|
||||
|
||||
[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.10.0-Windows.msi` | **推奨** - MSI インストーラー、自動更新対応 |
|
||||
| `CC-Switch-v3.10.0-Windows-Portable.zip` | ポータブル版、解凍して実行、レジストリ書き込みなし |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| -------------------------------- | ----------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.10.0-macOS.zip` | **推奨** - 解凍して Applications にドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.10.0-macOS.tar.gz` | Homebrew インストールと自動更新用 |
|
||||
|
||||
> **注意**：作者が Apple Developer アカウントを持っていないため、初回起動時に「開発元を確認できません」という警告が表示される場合があります。一度閉じてから、「システム設定」→「プライバシーとセキュリティ」→「このまま開く」をクリックすると、その後は正常に開けます。
|
||||
|
||||
### 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` |
|
||||
@@ -0,0 +1,206 @@
|
||||
# CC Switch v3.10.0
|
||||
|
||||
> OpenCode 支持、全局代理、Claude Rectifier 与多应用体验增强
|
||||
|
||||
**[English →](v3.10.0-en.md) | [日本語版 →](v3.10.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.10.0 新增 OpenCode 支持，成为第四个受管理的 CLI 应用。
|
||||
同时带来全局代理设置、Claude Rectifier（thinking 签名修正器）、健康检查增强、按供应商配置等多项重要功能，并对多应用工作流与终端体验做了全面改进。
|
||||
|
||||
**发布日期**：2026-01-21
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- OpenCode 支持：供应商、MCP 服务器、Skills 全面管理，首次启动自动导入
|
||||
- 全局代理：为出站网络请求统一配置代理
|
||||
- Claude Rectifier：thinking 签名修正器，兼容更多第三方 API
|
||||
- 健康检查增强：可配置提示词、CLI 兼容请求
|
||||
- 按供应商配置：支持供应商特定配置的持久化
|
||||
- 应用可见性控制：自由显示/隐藏应用，托盘菜单同步更新
|
||||
- 终端改进：供应商专属终端按钮、fnm 路径支持、跨平台安全启动
|
||||
- WSL 工具检测：在 WSL 环境检测工具版本，并增加安全加固
|
||||
|
||||
---
|
||||
|
||||
## 主要功能
|
||||
|
||||
### OpenCode 支持（新增第四应用）
|
||||
|
||||
- 完整的 OpenCode 供应商管理：新增、编辑、切换、删除
|
||||
- MCP 服务器管理：与 Claude/Codex/Gemini 统一架构
|
||||
- Skills 支持：OpenCode 也可使用 Skills 功能
|
||||
- 首次启动自动导入：检测到已有 OpenCode 配置时自动导入
|
||||
- 完整国际化：中/英/日三语支持（#695）
|
||||
|
||||
### 全局代理（Global Proxy）
|
||||
|
||||
- 为所有出站网络请求配置统一代理（#596，感谢 @yovinchen）
|
||||
- 支持 HTTP/HTTPS 代理协议
|
||||
- 适用于需要代理访问外部 API 的网络环境
|
||||
|
||||
### Claude Rectifier（Thinking 签名修正器）
|
||||
|
||||
- 自动修正 Claude API 的 thinking 签名（#595，感谢 @yovinchen）
|
||||
- 解决部分第三方 API 网关返回的 thinking 块格式不兼容问题
|
||||
- 在高级设置中可开启/关闭
|
||||
|
||||
### 健康检查增强
|
||||
|
||||
- 可配置自定义提示词（prompt）用于流式健康检查（#623，感谢 @yovinchen）
|
||||
- 支持 CLI 兼容请求格式，更好地模拟真实使用场景
|
||||
- 提升故障检测的准确性
|
||||
|
||||
### 按供应商配置（Per-Provider Config）
|
||||
|
||||
- 支持为每个供应商单独保存配置（#663，感谢 @yovinchen）
|
||||
- 配置持久化：重启后保留供应商专属设置
|
||||
- 适用于不同供应商需要不同配置的场景
|
||||
|
||||
### 应用可见性控制
|
||||
|
||||
- 自由显示/隐藏任意应用（Gemini 默认隐藏）
|
||||
- 托盘菜单自动同步可见性设置
|
||||
- 隐藏的应用不会出现在主界面和托盘菜单中
|
||||
|
||||
### Takeover Compact Mode
|
||||
|
||||
- 当显示 3 个及以上可见应用时，自动使用紧凑布局
|
||||
- 优化多应用场景下的空间利用
|
||||
|
||||
### 终端改进
|
||||
|
||||
- 供应商专属终端按钮：一键在终端中使用当前供应商（#564，感谢 @kkkman22）
|
||||
- `fnm` 路径支持：自动识别 fnm 管理的 Node.js 路径
|
||||
- 跨平台安全启动：改进 Windows/macOS/Linux 的终端启动逻辑
|
||||
|
||||
### WSL 工具检测
|
||||
|
||||
- 在 WSL 环境中检测工具版本（#627，感谢 @yovinchen）
|
||||
- 增加安全加固，防止命令注入风险
|
||||
|
||||
### Skills 预设增强
|
||||
|
||||
- 新增 `baoyu-skills` 预设仓库
|
||||
- 自动补充缺失的默认仓库，确保开箱即用
|
||||
|
||||
---
|
||||
|
||||
## 体验优化
|
||||
|
||||
- 键盘快捷键：按 `ESC` 快速返回/关闭面板（#670，感谢 @xxk8）
|
||||
- 代理日志简化：输出更清晰易读（#585，感谢 @yovinchen）
|
||||
- 定价编辑器 UX：统一使用 `FullScreenPanel` 风格
|
||||
- 高级设置布局：Rectifier 区块移至 Failover 下方，逻辑更顺畅
|
||||
- OpenRouter 兼容模式：默认禁用，UI 开关隐藏（减少干扰）
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 代理与故障切换
|
||||
|
||||
- 启用自动故障切换时立即切换到 P1（而非等待下次请求）
|
||||
|
||||
### 供应商管理
|
||||
|
||||
- 修复供应商编辑对话框保存后重新打开时数据过时的问题（#654，感谢 @YangYongAn）
|
||||
- 修复切换预设时 baseUrl 和 apiKey 状态未重置的问题
|
||||
- 修复端点自动选择状态未持久化的问题（#611，感谢 @yovinchen）
|
||||
- 未设置图标颜色时自动应用默认颜色
|
||||
|
||||
### 深链接
|
||||
|
||||
- 支持多端点导入（#597，感谢 @yovinchen）
|
||||
- 优先使用 `GOOGLE_GEMINI_BASE_URL` 而非 `GEMINI_BASE_URL`
|
||||
|
||||
### MCP
|
||||
|
||||
- WSL 目标路径跳过 `cmd /c` 包裹（#592，感谢 @cxyfer）
|
||||
|
||||
### 用量模板
|
||||
|
||||
- 新增变量提示，修复验证问题（#628，感谢 @YangYongAn）
|
||||
- 防止配置在供应商之间泄漏
|
||||
- 用量区块偏移量根据操作按钮宽度自动适应（#613，感谢 @yovinchen）
|
||||
|
||||
### Gemini
|
||||
|
||||
- 超时参数转换为 Gemini CLI 格式（#580，感谢 @cxyfer）
|
||||
|
||||
### UI
|
||||
|
||||
- 修复 `FullScreenPanel` 中 Select 下拉框渲染问题
|
||||
|
||||
---
|
||||
|
||||
## 说明与注意事项
|
||||
|
||||
- **OpenCode 为新支持的应用**：需要先安装 OpenCode CLI 才能使用相关功能。
|
||||
- **全局代理会影响所有出站请求**：包括用量查询、健康检查等网络操作。
|
||||
- **Rectifier 功能为实验性**：如遇问题可在高级设置中关闭。
|
||||
|
||||
---
|
||||
|
||||
## 特别感谢
|
||||
|
||||
感谢 @yovinchen @YangYongAn @cxyfer @xxk8 @kkkman22 @Shuimo03 为本版本做出的贡献！
|
||||
感谢 @libukai 设计的故障转移相关 UI，非常优雅！
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
访问 [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.10.0-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.10.0-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| -------------------------------- | --------------------------------------------------------- |
|
||||
| `CC-Switch-v3.10.0-macOS.zip` | **推荐** - 解压后拖入 Applications 即可，Universal Binary |
|
||||
| `CC-Switch-v3.10.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` |
|
||||
@@ -0,0 +1,302 @@
|
||||
# CC Switch v3.11.0
|
||||
|
||||
> OpenClaw Support, Session Manager, Backup Management & 50+ Improvements
|
||||
|
||||
**[中文版 →](v3.11.0-zh.md) | [日本語版 →](v3.11.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.11.0 is a major update that adds full management support for **OpenClaw** as the fifth application, introduces a new **Session Manager** and **Backup Management** feature. Additionally, **Oh My OpenCode (OMO) integration**, the **partial key-field merging** architecture upgrade for provider switching, **settings page refactoring**, and many other improvements make the overall experience more polished.
|
||||
|
||||
**Release Date**: 2026-02-26
|
||||
|
||||
**Update Scale**: 147 commits | 274 files changed | +32,179 / -5,467 lines
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- **OpenClaw Support**: Fifth managed application with 13 provider presets, Env/Tools/AgentsDefaults config editors, and Workspace file management
|
||||
- **Session Manager**: Browse conversation history across all five apps with table-of-contents navigation and in-session search
|
||||
- **Backup Management**: Independent backup panel with configurable policies, periodic backups, and pre-migration auto-backup
|
||||
- **Oh My OpenCode Integration**: Full OMO config management with OMO Slim lightweight mode support
|
||||
- **Partial Key-Field Merging (⚠️ Breaking Change)**: Provider switching now only replaces provider-related fields, preserving all other settings; the "Common Config Snippet" feature has been removed
|
||||
- **Settings Page Refactoring**: 5-tab layout with ~40% code reduction
|
||||
- **6 New Provider Presets**: AWS Bedrock, SSAI Code, CrazyRouter, AICoding, and more
|
||||
- **Thinking Budget Rectifier**: Fine-grained thinking budget control
|
||||
- **Theme Switch Animation**: Circular reveal transition animation
|
||||
- **WebDAV Auto Sync**: Automatic sync with large file protection
|
||||
|
||||
---
|
||||
|
||||
## Main Features
|
||||
|
||||
### OpenClaw Support (New Fifth App)
|
||||
|
||||
Full management support for OpenClaw, the fifth managed application following Claude Code, Codex, Gemini CLI, and OpenCode.
|
||||
|
||||
- **Provider Management**: Add, edit, switch, and delete OpenClaw providers with 13 built-in presets
|
||||
- **Config Editors**: Three dedicated panels for Env (environment variables), Tools, and AgentsDefaults
|
||||
- **Workspace Panel**: HEARTBEAT/BOOTSTRAP/BOOT file management and daily memory
|
||||
- **Additive Overlay Mode**: Support config overlay instead of overwrite
|
||||
- **Default Model Button**: One-click to fill recommended models; auto-register suggested models to allowlist when adding providers
|
||||
- **Brand & Interaction**: Dedicated brand icon, fade-in/fade-out transition animation when switching apps
|
||||
- **Deep Link Support**: Import OpenClaw provider configurations via URL
|
||||
- **Full Internationalization**: Complete Chinese/English/Japanese support
|
||||
|
||||
### Session Manager
|
||||
|
||||
A brand-new session manager to browse and search conversation history.
|
||||
|
||||
- Browse conversation history across Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw (#867, thanks @TinsFox)
|
||||
- Table-of-contents navigation and in-session search
|
||||
- Auto-filter by current app when entering the session page
|
||||
- Parallel directory scanning + head-tail JSONL reading for optimized loading performance
|
||||
|
||||
### Backup Management
|
||||
|
||||
An independent backup management panel for better data safety.
|
||||
|
||||
- Configurable backup policy: maximum backup count and auto-cleanup rules
|
||||
- Hourly automatic backup timer during runtime
|
||||
- Auto-backup before database schema migrations with backfill warning
|
||||
- Support backup rename and deletion (with confirmation dialog)
|
||||
- Backup filenames use local time for better clarity
|
||||
|
||||
### Oh My OpenCode (OMO) Integration
|
||||
|
||||
Full Oh My OpenCode config file management.
|
||||
|
||||
- Agent model selection, category configuration, and recommended model fill (#972, thanks @yovinchen)
|
||||
- Improved agent model selection UX with lowercase key fix (#1004, thanks @yovinchen)
|
||||
- OMO Slim lightweight mode support
|
||||
- OMO ↔ OMO Slim mutual exclusion (enforced at database level)
|
||||
|
||||
### Workspace
|
||||
|
||||
- Full-text search across daily memory files, sorted by date
|
||||
- Clickable directory paths for quick file location access
|
||||
|
||||
### Toolbar
|
||||
|
||||
- AppSwitcher auto-collapses to compact mode based on available width
|
||||
- Smooth transition animation for compact mode toggle
|
||||
|
||||
### Settings
|
||||
|
||||
- First-use confirmation dialogs for proxy and usage features to prevent accidental operations
|
||||
- New `enableLocalProxy` switch to control proxy UI visibility on home page
|
||||
- More granular local environment checks: CLI tool version detection (#870, thanks @kv-chiu), Volta path detection (#969, thanks @myjustify)
|
||||
|
||||
### Provider Presets
|
||||
|
||||
- **AWS Bedrock**: Support for AKSK and API Key authentication modes (#1047, thanks @keithyt06)
|
||||
- **SSAI Code**: Partner preset across all five apps
|
||||
- **CrazyRouter**: Partner preset with dedicated icon
|
||||
- **AICoding**: Partner preset with i18n promotion text
|
||||
- Updated domestic model provider presets to latest versions
|
||||
- Renamed Qwen Coder to Bailian (#965, thanks @zhu-jl18)
|
||||
|
||||
### Other New Features
|
||||
|
||||
- **Thinking Budget Rectifier**: Fine-grained thinking budget allocation control (#1005, thanks @yovinchen)
|
||||
- **WebDAV Auto Sync**: Automatic sync with large file protection (#923, thanks @clx20000410; #1043, thanks @SaladDay)
|
||||
- **Theme Switch Animation**: Circular reveal transition for a smoother visual experience (#905, thanks @funnytime75)
|
||||
- **Claude Config Editor Quick Toggles**: Quick toggle switches for common settings (#1012, thanks @JIA-ss)
|
||||
- **Dynamic Endpoint Hint**: Context-aware hint text based on API format selection (#860, thanks @zhu-jl18)
|
||||
- **Usage Dashboard Enhancement**: Auto-refresh control and robust formatting (#942, thanks @yovinchen)
|
||||
- **New Pricing Data**: claude-opus-4-6 and gpt-5.3-codex (#943, thanks @yovinchen)
|
||||
- **Silent Startup Optimization**: Silent startup option only shown when launch-on-startup is enabled
|
||||
|
||||
---
|
||||
|
||||
## Architecture Improvements
|
||||
|
||||
### Partial Key-Field Merging (⚠️ Breaking Change)
|
||||
|
||||
Provider switching now uses partial key-field merging instead of full config overwrite (#1098).
|
||||
|
||||
**Before**: Switching providers overwrote the entire `settings_config` to the live config file. This meant that any non-provider settings the user manually added to the live file (plugins, MCP config, permissions, etc.) would be lost on every switch. To work around this, previous versions offered a "Common Config Snippet" feature that let users define shared config to be merged on every switch.
|
||||
|
||||
**After**: Switching providers now only replaces provider-related key-values (API keys, endpoints, models, etc.), leaving all other settings intact. The "Common Config Snippet" feature is therefore no longer needed and has been removed.
|
||||
|
||||
**Impact & Migration**:
|
||||
- If you **didn't use** Common Config Snippets, this change is fully transparent — switching just works better now
|
||||
- If you **used** Common Config Snippets to preserve custom settings (MCP config, permissions, etc.), those settings are now automatically preserved during switches — no action needed
|
||||
- If you used Common Config Snippets for other purposes (e.g., injecting extra config on every switch), please manually add those settings to your live config file after upgrading
|
||||
|
||||
This refactoring removed 6 frontend files (3 components + 3 hooks) and ~150 lines of backend dead code.
|
||||
|
||||
### Manual Import Replaces Auto-Import
|
||||
|
||||
Startup no longer auto-imports external configurations. Users now click "Import Current Config" manually, preventing accidental data overwrites.
|
||||
|
||||
### OmoVariant Parameterization
|
||||
|
||||
Eliminated ~250 lines of duplicated code in the OMO module via `OmoVariant` struct parameterization.
|
||||
|
||||
### OMO Common Config Removal
|
||||
|
||||
Removed the two-layer merge system, reducing ~1,733 lines of code and simplifying the architecture.
|
||||
|
||||
### ProviderForm Decomposition
|
||||
|
||||
Reduced ProviderForm component from 2,227 lines to 1,526 lines by extracting 5 independent modules (opencodeFormUtils, useOmoModelSource, useOpencodeFormState, useOmoDraftState, useOpenclawFormState), significantly improving maintainability.
|
||||
|
||||
### Shared MCP/Skills Components
|
||||
|
||||
Extracted AppCountBar, AppToggleGroup, and ListItemRow shared components to reduce duplication across MCP and Skills panels (#897, thanks @PeanutSplash).
|
||||
|
||||
### Settings Page Refactoring
|
||||
|
||||
Refactored settings page to a 5-tab layout (General | Proxy | Advanced | Usage | About), reducing SettingsPage code from ~716 to ~426 lines.
|
||||
|
||||
### Other Improvements
|
||||
|
||||
- Unified terminal selection via global settings with WezTerm support added
|
||||
- Updated Claude model references from 4.5 to 4.6
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Critical Fixes
|
||||
|
||||
- **Windows Home Dir Regression**: Restored default home directory resolution to prevent providers/settings "disappearing" when `HOME` env var differs from the real user profile directory in Git/MSYS environments
|
||||
- **Linux White Screen**: Disabled WebKitGTK hardware acceleration on AMD GPUs (Cezanne/Radeon Vega) to prevent blank screen on startup (#986, thanks @ThendCN)
|
||||
- **OpenAI Beta Parameter**: Stopped appending `?beta=true` to `/v1/chat/completions` endpoints, fixing request failures for Nvidia and other `apiFormat="openai_chat"` providers (#1052, thanks @jnorthrup)
|
||||
- **Health Check Auth**: Health check now respects provider's `auth_mode` setting, preventing failures for proxy services that only support Bearer authentication (#824, thanks @Jassy930)
|
||||
|
||||
### Provider Preset Fixes
|
||||
|
||||
- Fixed OpenClaw `/v1` prefix causing double path (/v1/v1/messages)
|
||||
- Corrected Opus pricing ($15/$75 → $5/$25) and upgraded to 4.6
|
||||
- Unified AIGoCode URL to `https://api.aigocode.com` across all apps
|
||||
- Removed outdated partner status from Zhipu GLM presets
|
||||
- Restored API Key input visibility when creating new Claude providers
|
||||
- Hide quick toggles for non-active providers, show context-aware JSON editor hints
|
||||
|
||||
### OMO Fixes
|
||||
|
||||
- Added missing omo-slim category checks across add/form/mutation paths
|
||||
- Fixed OMO Slim query cache invalidation after provider mutations
|
||||
- Synced OMO agent/category recommended models with upstream sources
|
||||
- Added toast feedback for "Fill Recommended" button silent failures
|
||||
- Removed last-provider deletion restriction for OMO/OMO Slim
|
||||
- Reject saving OpenCode providers without configured models (#932, thanks @yovinchen)
|
||||
|
||||
### OpenClaw Fixes
|
||||
|
||||
- Fixed 25 missing i18n keys, replaced key={index} with stable IDs, added deep link additive merge, and other code review issues
|
||||
- Enhanced EnvPanel robustness (NaN guards, entry key names instead of array indices)
|
||||
- Merged duplicate i18n keys to restore provider form translations
|
||||
|
||||
### Platform Fixes
|
||||
|
||||
- Windows silent startup window flicker (#901, thanks @funnytime75)
|
||||
- Title bar dark mode theme following (#903, thanks @funnytime75)
|
||||
- Windows Skills path separator matching (#868, thanks @stmoonar)
|
||||
- WSL helper functions conditional compilation
|
||||
|
||||
### UI Fixes
|
||||
|
||||
- Toolbar height clipping causing AppSwitcher to be obscured
|
||||
- Show update badge instead of green checkmark when newer version available
|
||||
- Session Manager button only visible for Claude/Codex apps
|
||||
- Unified SQL import/export card dark mode styling (#1067, thanks @SaladDay)
|
||||
|
||||
### Other Fixes
|
||||
|
||||
- Replaced hardcoded Chinese strings in Session Manager with i18n keys
|
||||
- Fixed Skill documentation URL branch and path resolution (#977, thanks @yovinchen)
|
||||
- Added missing OpenCode install.sh installation path detection (#988, thanks @zhu-jl18)
|
||||
- Fixed Skill ZIP symlink resolution (#1040, thanks @yovinchen)
|
||||
- Added missing OpenCode checkbox in MCP add/edit form (#1026, thanks @yovinchen)
|
||||
- Removed auto-import side effect from useProvidersQuery queryFn
|
||||
|
||||
---
|
||||
|
||||
## Performance
|
||||
|
||||
- Parallel directory scanning + head-tail JSONL reading for session panel, significantly improving session list loading speed
|
||||
- Removed unnecessary TanStack Query cache overhead for Tauri local IPC calls
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
- Sponsor updates: SSSAiCode, Crazyrouter, AICoding, Right Code, MiniMax
|
||||
- Added user manual documentation (#979, thanks @yovinchen)
|
||||
|
||||
---
|
||||
|
||||
## Notes & Considerations
|
||||
|
||||
- **OpenClaw is a newly supported app**: OpenClaw CLI must be installed first to use related features.
|
||||
- **⚠️ Common Config Snippet feature has been removed**: Since provider switching now uses partial key-field merging (only replacing API keys, endpoints, models, etc.), user's other settings are automatically preserved, making Common Config Snippets unnecessary. See the "Architecture Improvements" section above for migration details.
|
||||
- **Auto-import changed to manual**: External configurations are no longer auto-imported on startup. Click "Import Current Config" manually when needed.
|
||||
- **OMO and OMO Slim are mutually exclusive**: Only one can be active at a time. Switching to one automatically disables the other.
|
||||
- **Backup is enabled by default**: Automatic hourly backup during runtime. Adjust the policy in the Backup panel.
|
||||
|
||||
---
|
||||
|
||||
## Special Thanks
|
||||
|
||||
Thanks to all contributors for their contributions to this release!
|
||||
|
||||
@TinsFox @keithyt06 @kv-chiu @SaladDay @jnorthrup @JIA-ss @clx20000410 @ThendCN @yovinchen @zhu-jl18 @myjustify @funnytime75 @PeanutSplash @Jassy930 @stmoonar
|
||||
|
||||
---
|
||||
|
||||
## 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.11.0-Windows.msi` | **Recommended** - MSI installer with auto-update |
|
||||
| `CC-Switch-v3.11.0-Windows-Portable.zip` | Portable version, extract and run, no registry write |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| -------------------------------- | -------------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.11.0-macOS.zip` | **Recommended** - Extract and drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.11.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` |
|
||||
@@ -0,0 +1,302 @@
|
||||
# CC Switch v3.11.0
|
||||
|
||||
> OpenClaw サポート、セッションマネージャー、バックアップ管理と 50 以上の改善
|
||||
|
||||
**[中文版 →](v3.11.0-zh.md) | [English →](v3.11.0-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.11.0 は大規模なアップデートです。5番目のアプリケーション **OpenClaw** の完全管理サポートを追加し、新しい**セッションマネージャー**と**バックアップ管理**機能を導入しました。さらに、**Oh My OpenCode (OMO) 統合**、プロバイダー切り替えの**部分キーフィールドマージ**アーキテクチャアップグレード、**設定ページのリファクタリング**など、多数の改善により全体的な体験がさらに向上しました。
|
||||
|
||||
**リリース日**: 2026-02-26
|
||||
|
||||
**更新規模**: 147 commits | 274 files changed | +32,179 / -5,467 lines
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **OpenClaw サポート**: 5番目の管理対象アプリ、13 のプロバイダープリセット、Env/Tools/AgentsDefaults 設定エディター、Workspace ファイル管理
|
||||
- **セッションマネージャー**: 5つのアプリの会話履歴を閲覧、目次ナビゲーションとセッション内検索
|
||||
- **バックアップ管理**: 独立バックアップパネル、設定可能なポリシー、定期バックアップ、マイグレーション前自動バックアップ
|
||||
- **Oh My OpenCode 統合**: 完全な OMO 設定管理、OMO Slim 軽量モードサポート
|
||||
- **部分キーフィールドマージ（⚠️ 破壊的変更）**: プロバイダー切り替え時にプロバイダー関連フィールドのみ置換し、その他の設定を保持；「共通設定スニペット」機能は削除されました
|
||||
- **設定ページリファクタリング**: 5タブレイアウト、コード量約 40% 削減
|
||||
- **6つの新プロバイダープリセット**: AWS Bedrock、SSAI Code、CrazyRouter、AICoding など
|
||||
- **Thinking Budget Rectifier**: より精密な thinking budget 制御
|
||||
- **テーマ切り替えアニメーション**: 円形リビール遷移アニメーション
|
||||
- **WebDAV 自動同期**: 自動同期と大容量ファイル保護
|
||||
|
||||
---
|
||||
|
||||
## 主な機能
|
||||
|
||||
### OpenClaw サポート（新しい5番目のアプリ）
|
||||
|
||||
Claude Code、Codex、Gemini CLI、OpenCode に続く5番目の管理対象アプリケーションとして OpenClaw の完全管理サポートを追加しました。
|
||||
|
||||
- **プロバイダー管理**: OpenClaw プロバイダーの追加、編集、切り替え、削除、13 の内蔵プリセット
|
||||
- **設定エディター**: Env（環境変数）、Tools（ツール）、AgentsDefaults（エージェントデフォルト）の3つの専用パネル
|
||||
- **Workspace パネル**: HEARTBEAT/BOOTSTRAP/BOOT ファイル管理とデイリーメモリ
|
||||
- **Additive オーバーレイモード**: 上書きではなく設定の重ね合わせをサポート
|
||||
- **デフォルトモデルボタン**: ワンクリックで推奨モデルを入力、プロバイダー追加時に候補モデルを allowlist に自動登録
|
||||
- **ブランドとインタラクション**: 専用ブランドアイコン、アプリ切り替えフェード遷移アニメーション
|
||||
- **ディープリンクサポート**: URL 経由で OpenClaw プロバイダー設定をインポート
|
||||
- **完全な国際化**: 中/英/日 三言語完全対応
|
||||
|
||||
### セッションマネージャー
|
||||
|
||||
会話履歴を閲覧・検索できる新しいセッションマネージャーです。
|
||||
|
||||
- Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw の5つのアプリの会話履歴を閲覧（#867、@TinsFox に感謝）
|
||||
- 目次ナビゲーションとセッション内検索
|
||||
- セッションページに入ると現在のアプリで自動フィルター
|
||||
- 並列ディレクトリスキャン + ヘッドテール JSONL 読み取りで読み込みパフォーマンスを最適化
|
||||
|
||||
### バックアップ管理
|
||||
|
||||
データの安全性を高める独立バックアップ管理パネルです。
|
||||
|
||||
- 設定可能なバックアップポリシー: 最大バックアップ数、自動クリーンアップルール
|
||||
- ランタイム中の1時間ごとの定期自動バックアップ
|
||||
- データベースマイグレーション前の自動バックアップ、バックフィル警告プロンプト
|
||||
- バックアップのリネームと削除をサポート（確認ダイアログ付き）
|
||||
- バックアップファイル名にローカルタイムを使用、より直感的に
|
||||
|
||||
### Oh My OpenCode (OMO) 統合
|
||||
|
||||
完全な Oh My OpenCode 設定ファイル管理です。
|
||||
|
||||
- エージェントモデル選択、カテゴリ設定、推奨モデル入力（#972、@yovinchen に感謝）
|
||||
- エージェントモデル選択 UX の改善、lowercase key 問題の修正（#1004、@yovinchen に感謝）
|
||||
- OMO Slim 軽量モードサポート
|
||||
- OMO と OMO Slim の相互排他（データベースレベルで一貫性を保証）
|
||||
|
||||
### ワークスペース
|
||||
|
||||
- デイリーメモリファイルの全文検索、日付順ソート
|
||||
- ディレクトリパスがクリック可能に、ファイル位置をすばやく開く
|
||||
|
||||
### ツールバー
|
||||
|
||||
- AppSwitcher がウィンドウ幅に応じて自動的にコンパクトモードに折りたたみ
|
||||
- コンパクトモード切り替えのスムーズ遷移アニメーション
|
||||
|
||||
### 設定
|
||||
|
||||
- プロキシと使用量機能に初回使用確認ダイアログを追加、誤操作を防止
|
||||
- `enableLocalProxy` スイッチを追加、ホーム画面のプロキシ UI 表示を制御
|
||||
- より詳細なローカル環境チェック: CLI ツールバージョン検出（#870、@kv-chiu に感謝）、Volta パス検出（#969、@myjustify に感謝）
|
||||
|
||||
### プロバイダープリセット
|
||||
|
||||
- **AWS Bedrock**: AKSK と API Key の2種類の認証方式をサポート（#1047、@keithyt06 に感謝）
|
||||
- **SSAI Code**: パートナープリセット、5アプリ対応
|
||||
- **CrazyRouter**: パートナープリセットと専用アイコン
|
||||
- **AICoding**: パートナープリセットとプロモーションテキスト
|
||||
- 国内モデルプロバイダープリセットを最新版に更新
|
||||
- Qwen Coder を百炼 (Bailian) にリネーム（#965、@zhu-jl18 に感謝）
|
||||
|
||||
### その他の新機能
|
||||
|
||||
- **Thinking Budget Rectifier**: より精密な thinking budget 制御（#1005、@yovinchen に感謝）
|
||||
- **WebDAV 自動同期**: 自動同期設定と大容量ファイル保護（#923、@clx20000410 に感謝；#1043、@SaladDay に感謝）
|
||||
- **テーマ切り替えアニメーション**: 円形リビール遷移アニメーション（#905、@funnytime75 に感謝）
|
||||
- **Claude 設定エディタークイックトグル**: よく使う設定項目のクイック切り替え（#1012、@JIA-ss に感謝）
|
||||
- **動的エンドポイントヒント**: API フォーマット選択に基づく動的ヒントテキスト（#860、@zhu-jl18 に感謝）
|
||||
- **使用量ダッシュボード強化**: 自動更新、堅牢なフォーマット（#942、@yovinchen に感謝）
|
||||
- **新しい価格データ**: claude-opus-4-6 と gpt-5.3-codex（#943、@yovinchen に感謝）
|
||||
- **サイレント起動の最適化**: サイレント起動オプションは自動起動が有効な場合のみ表示
|
||||
|
||||
---
|
||||
|
||||
## アーキテクチャ改善
|
||||
|
||||
### 部分キーフィールドマージ（⚠️ 破壊的変更）
|
||||
|
||||
プロバイダー切り替えを完全な設定上書きから部分キーフィールドマージ戦略に変更しました（#1098）。
|
||||
|
||||
**変更前**: プロバイダーを切り替えると、`settings_config` 全体がライブ設定ファイルに上書きされていました。つまり、ユーザーがライブファイルに手動で追加した非プロバイダー設定（プラグイン設定、MCP 設定、権限設定など）は、切り替えのたびに失われていました。この問題を補うため、以前のバージョンでは「共通設定スニペット」機能を提供し、毎回の切り替え時にマージされる共通設定を定義できました。
|
||||
|
||||
**変更後**: プロバイダー切り替え時に、プロバイダー関連のキー値（API キー、エンドポイント、モデルなど）のみが置換され、その他の設定はそのまま保持されます。そのため「共通設定スニペット」機能は不要となり、削除されました。
|
||||
|
||||
**影響と移行**:
|
||||
- 共通設定スニペットを**使用していなかった**場合、この変更は完全に透過的で、切り替え体験が向上するだけです
|
||||
- カスタム設定（MCP 設定、権限など）を保持するために共通設定スニペットを**使用していた**場合、それらの設定は切り替え時に自動的に保持されるようになり、追加の操作は不要です
|
||||
- 共通設定スニペットを他の目的（切り替え時に追加設定を注入するなど）で使用していた場合は、アップグレード後にライブ設定ファイルに手動で設定を追加してください
|
||||
|
||||
このリファクタリングにより、フロントエンドファイル 6 つ（コンポーネント 3 つ + hooks 3 つ）と約 150 行のバックエンドデッドコードを削除しました。
|
||||
|
||||
### 手動インポートに変更
|
||||
|
||||
起動時の自動インポートを廃止し、手動の「現在の設定をインポート」ボタンに変更。意図しないユーザーデータの上書きを防止します。
|
||||
|
||||
### OmoVariant パラメータ化
|
||||
|
||||
`OmoVariant` 構造体によるパラメータ化で、OMO モジュールの約250行の重複コードを削除しました。
|
||||
|
||||
### OMO 共通設定の削除
|
||||
|
||||
2層マージシステムを削除し、約1,733行のコードを削減、アーキテクチャを簡素化しました。
|
||||
|
||||
### ProviderForm 分割
|
||||
|
||||
ProviderForm コンポーネントを2,227行から1,526行に削減し、5つの独立モジュール（opencodeFormUtils、useOmoModelSource、useOpencodeFormState、useOmoDraftState、useOpenclawFormState）に分離。保守性が大幅に向上しました。
|
||||
|
||||
### MCP/Skills 共有コンポーネント
|
||||
|
||||
AppCountBar、AppToggleGroup、ListItemRow などの共有コンポーネントを抽出し、MCP と Skills パネルの重複コードを削減（#897、@PeanutSplash に感謝）。
|
||||
|
||||
### 設定ページリファクタリング
|
||||
|
||||
設定ページを5タブレイアウト（一般 | プロキシ | 詳細 | 使用量 | 情報）にリファクタリング。SettingsPage のコードを約716行から約426行に削減しました。
|
||||
|
||||
### その他の改善
|
||||
|
||||
- ターミナル統一: グローバル設定でターミナル選択を統一、WezTerm サポートを追加
|
||||
- Claude モデル参照を 4.5 から 4.6 に更新
|
||||
|
||||
---
|
||||
|
||||
## バグ修正
|
||||
|
||||
### 重大な修正
|
||||
|
||||
- **Windows ホームディレクトリ回帰**: デフォルトのホームディレクトリ解決を復元し、Git/MSYS 環境でのデータベースパス変更によるデータ「消失」を防止
|
||||
- **Linux 白画面**: AMD GPU の WebKitGTK ハードウェアアクセラレーションを無効化し、一部の Linux システムの起動白画面問題を解決（#986、@ThendCN に感謝）
|
||||
- **OpenAI Beta パラメータ**: `/v1/chat/completions` に `?beta=true` を追加しないように修正、Nvidia など OpenAI Chat 形式を使用するプロバイダーのリクエスト失敗を修正（#1052、@jnorthrup に感謝）
|
||||
- **ヘルスチェック認証**: プロバイダーの `auth_mode` 設定を尊重し、Bearer 認証のみをサポートするプロキシサービスのヘルスチェック失敗を回避（#824、@Jassy930 に感謝）
|
||||
|
||||
### プロバイダープリセット修正
|
||||
|
||||
- OpenClaw `/v1` プレフィックスの二重パス問題を修正
|
||||
- Opus 価格修正（$15/$75 → $5/$25）と 4.6 へのアップグレード
|
||||
- AIGoCode URL を `https://api.aigocode.com` に統一
|
||||
- Zhipu GLM の古いパートナーステータスを削除
|
||||
- 新規 Claude プロバイダー作成時の API Key 入力フィールドの表示を復元
|
||||
- 非アクティブプロバイダーのクイックトグルを非表示、コンテキスト対応の JSON エディターヒントを表示
|
||||
|
||||
### OMO 修正
|
||||
|
||||
- omo-slim カテゴリチェックの補完（add/form/mutation パス）
|
||||
- OMO Slim プロバイダー変更後のクエリキャッシュ無効化を修正
|
||||
- OMO agent/category 推奨モデルをアップストリームソースと同期
|
||||
- 「推奨を入力」ボタン失敗時の toast フィードバックを追加
|
||||
- OMO/OMO Slim の最後のプロバイダー削除制限を撤廃
|
||||
- OpenCode でモデル未設定時の保存を拒否（#932、@yovinchen に感謝）
|
||||
|
||||
### OpenClaw 修正
|
||||
|
||||
- 25個の欠落 i18n キー、key={index} を安定 ID に置換、ディープリンク additive マージなどのコードレビュー問題を修正
|
||||
- EnvPanel 堅牢性強化（NaN ガード、配列インデックスではなくエントリーキー名を使用）
|
||||
- i18n 重複キーのマージ、プロバイダーフォーム翻訳を復元
|
||||
|
||||
### プラットフォーム修正
|
||||
|
||||
- Windows サイレント起動時のウィンドウフラッシュ（#901、@funnytime75 に感謝）
|
||||
- タイトルバーのダークモード追従（#903、@funnytime75 に感謝）
|
||||
- Windows の Skills パスセパレーターマッチング（#868、@stmoonar に感謝）
|
||||
- WSL ヘルパー関数の条件付きコンパイル
|
||||
|
||||
### UI 修正
|
||||
|
||||
- ツールバーの高さクリッピングによる AppSwitcher の遮蔽を修正
|
||||
- 新バージョンがある場合、緑のチェックマークではなく更新バッジを表示
|
||||
- セッションマネージャーボタンを Claude/Codex アプリでのみ表示
|
||||
- SQL インポート/エクスポートカードのダークモードスタイルを統一（#1067、@SaladDay に感謝）
|
||||
|
||||
### その他の修正
|
||||
|
||||
- セッションマネージャーのハードコードされた中国語文字列を i18n キーに置換
|
||||
- Skill ドキュメント URL のブランチとパスを修正（#977、@yovinchen に感謝）
|
||||
- OpenCode install.sh インストールパス検出の補完（#988、@zhu-jl18 に感謝）
|
||||
- Skill ZIP シンボリックリンク解決の修正（#1040、@yovinchen に感謝）
|
||||
- MCP フォームに OpenCode チェックボックスを追加（#1026、@yovinchen に感謝）
|
||||
- useProvidersQuery の自動インポート副作用を削除
|
||||
|
||||
---
|
||||
|
||||
## パフォーマンス最適化
|
||||
|
||||
- セッションパネルの並列ディレクトリスキャン + ヘッドテール JSONL 読み取りで、セッションリスト読み込み速度を大幅向上
|
||||
- Tauri ローカル IPC の不要な query cache を削除し、メモリ使用量を削減
|
||||
|
||||
---
|
||||
|
||||
## ドキュメント
|
||||
|
||||
- スポンサー更新: SSSAiCode、Crazyrouter、AICoding、Right Code、MiniMax
|
||||
- ユーザーマニュアルを追加（#979、@yovinchen に感謝）
|
||||
|
||||
---
|
||||
|
||||
## 注意事項
|
||||
|
||||
- **OpenClaw は新しくサポートされたアプリです**: 関連機能を使用するには、先に OpenClaw CLI をインストールする必要があります。
|
||||
- **⚠️ 共通設定スニペット機能は削除されました**: プロバイダー切り替えが部分キーフィールドマージ（API キー、エンドポイント、モデルなどのみ置換）に変更されたため、ユーザーのその他の設定は自動的に保持され、共通設定スニペットは不要になりました。移行の詳細は上記「アーキテクチャ改善」セクションを参照してください。
|
||||
- **自動インポートは手動に変更されました**: 起動時に外部設定を自動インポートしなくなりました。必要に応じて「現在の設定をインポート」を手動でクリックしてください。
|
||||
- **OMO と OMO Slim は相互排他**: 同時に一つだけ有効にできます。切り替え時にもう一方は自動的に無効になります。
|
||||
- **バックアップ機能はデフォルトで有効**: ランタイム中に1時間ごとに自動バックアップします。バックアップパネルでポリシーを調整できます。
|
||||
|
||||
---
|
||||
|
||||
## 特別な感謝
|
||||
|
||||
以下のコントリビューターの皆様、このリリースへの貢献に感謝します！
|
||||
|
||||
@TinsFox @keithyt06 @kv-chiu @SaladDay @jnorthrup @JIA-ss @clx20000410 @ThendCN @yovinchen @zhu-jl18 @myjustify @funnytime75 @PeanutSplash @Jassy930 @stmoonar
|
||||
|
||||
---
|
||||
|
||||
## ダウンロードとインストール
|
||||
|
||||
[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.11.0-Windows.msi` | **推奨** - MSI インストーラー、自動更新対応 |
|
||||
| `CC-Switch-v3.11.0-Windows-Portable.zip` | ポータブル版、解凍して実行、レジストリ書き込みなし |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| -------------------------------- | ----------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.11.0-macOS.zip` | **推奨** - 解凍して Applications にドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.11.0-macOS.tar.gz` | Homebrew インストールと自動更新用 |
|
||||
|
||||
> **注意**: 作者が Apple Developer アカウントを持っていないため、初回起動時に「開発元を確認できません」という警告が表示される場合があります。一度閉じてから、「システム設定」→「プライバシーとセキュリティ」→「このまま開く」をクリックすると、その後は正常に開けます。
|
||||
|
||||
### 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` |
|
||||
@@ -0,0 +1,302 @@
|
||||
# CC Switch v3.11.0
|
||||
|
||||
> OpenClaw 支持、会话管理器、备份管理与 50+ 项改进
|
||||
|
||||
**[English →](v3.11.0-en.md) | [日本語版 →](v3.11.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.11.0 是一次大规模更新，新增第五个应用 **OpenClaw** 的完整管理支持，同时带来全新的**会话管理器**和**备份管理**功能。此外，**Oh My OpenCode (OMO) 集成**、供应商切换的**部分键值合并**架构升级、**设置页面重构**等多项改进使整体体验更加完善。
|
||||
|
||||
**发布日期**：2026-02-26
|
||||
|
||||
**更新规模**：147 commits | 274 files changed | +32,179 / -5,467 lines
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- **OpenClaw 支持**：第五个受管理应用，含 13 个供应商预设、Env/Tools/AgentsDefaults 配置编辑器、Workspace 文件管理
|
||||
- **会话管理器**：浏览五个应用的历史会话，支持目录导航和会话内搜索
|
||||
- **备份管理**：独立备份面板，可配置策略、定时备份、迁移前自动备份
|
||||
- **Oh My OpenCode 集成**：完整 OMO 配置管理，支持 OMO Slim 轻量模式
|
||||
- **部分键值合并（⚠️ 破坏性变更）**：供应商切换改为仅替换供应商相关字段，保留用户的其余设置；"通用配置片段"功能因此移除
|
||||
- **设置页面重构**：5 标签页布局，代码量减少约 40%
|
||||
- **6 组新供应商预设**：AWS Bedrock、SSAI Code、CrazyRouter、AICoding 等
|
||||
- **Thinking Budget Rectifier**：代理矫正器，更精细的 thinking budget 控制
|
||||
- **主题切换动画**：圆形揭示过渡动画，视觉体验升级
|
||||
- **WebDAV 自动同步**：支持自动同步与大文件防护
|
||||
|
||||
---
|
||||
|
||||
## 主要功能
|
||||
|
||||
### OpenClaw 支持（新增第五应用）
|
||||
|
||||
CC Switch 新增对 OpenClaw 的完整管理支持，这是继 Claude Code、Codex、Gemini CLI、OpenCode 之后的第五个受管理应用。
|
||||
|
||||
- **供应商管理**：新增、编辑、切换、删除 OpenClaw 供应商，含 13 个内置预设
|
||||
- **配置编辑器**：Env（环境变量）、Tools（工具）、AgentsDefaults（代理默认值）三个专属配置面板
|
||||
- **Workspace 面板**：支持 HEARTBEAT/BOOTSTRAP/BOOT 文件管理及每日记忆
|
||||
- **Additive 叠加模式**：支持配置叠加而非覆盖
|
||||
- **默认模型按钮**：一键填充推荐模型，添加供应商时自动将建议模型注册到 allowlist
|
||||
- **品牌与交互**：专属品牌图标、应用切换淡入淡出过渡动画
|
||||
- **深链接支持**：通过 URL 导入 OpenClaw 供应商配置
|
||||
- **完整国际化**：中/英/日三语全面支持
|
||||
|
||||
### 会话管理器 Sessions
|
||||
|
||||
全新的会话管理器，帮助你浏览和检索历史会话记录。
|
||||
|
||||
- 支持浏览 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 五个应用的历史会话（#867，感谢 @TinsFox）
|
||||
- 目录导航和会话内搜索
|
||||
- 进入会话页面时默认过滤为当前应用，快速定位
|
||||
- 并行目录扫描 + 头尾 JSONL 读取，优化加载性能
|
||||
|
||||
### 备份管理 Backup
|
||||
|
||||
独立的备份管理面板，让数据安全更有保障。
|
||||
|
||||
- 可配置备份策略：最大备份数量、自动清理规则
|
||||
- 运行时每小时定期自动备份
|
||||
- 数据库迁移前自动备份，带回填警告提示
|
||||
- 支持备份重命名和删除（含确认对话框）
|
||||
- 备份文件名使用本地时间，更直观
|
||||
|
||||
### Oh My OpenCode (OMO) 集成
|
||||
|
||||
完整的 Oh My OpenCode 配置文件管理。
|
||||
|
||||
- Agent 模型选择、Category 配置、推荐模型填充（#972，感谢 @yovinchen）
|
||||
- 改进 Agent 模型选择 UX，修复 lowercase key 问题（#1004，感谢 @yovinchen）
|
||||
- OMO Slim 轻量模式支持
|
||||
- OMO 与 OMO Slim 互斥切换（数据库层级强制保证一致性）
|
||||
|
||||
### 工作空间 Workspace
|
||||
|
||||
- 每日记忆文件全文搜索，按日期排序
|
||||
- 目录路径可点击跳转，快速打开文件位置
|
||||
|
||||
### 工具栏 Toolbar
|
||||
|
||||
- AppSwitcher 根据窗口宽度自动折叠为紧凑模式
|
||||
- 紧凑模式切换平滑过渡动画
|
||||
|
||||
### 设置 Settings
|
||||
|
||||
- 代理和用量功能新增首次使用确认对话框，避免误操作
|
||||
- 新增 `enableLocalProxy` 开关，控制主页代理 UI 显示
|
||||
- 更精细的本地环境检查：CLI 工具版本检测（#870，感谢 @kv-chiu）、Volta 路径检测（#969，感谢 @myjustify）
|
||||
|
||||
### 供应商预设 Preset
|
||||
|
||||
- **AWS Bedrock**：支持 AKSK 和 API Key 两种认证方式（#1047，感谢 @keithyt06）
|
||||
- **SSAI Code**：合作伙伴预设，覆盖五端
|
||||
- **CrazyRouter**：合作伙伴预设及专属图标
|
||||
- **AICoding**：合作伙伴预设及推广文案
|
||||
- 更新国内模型供应商预设至最新版本
|
||||
- Qwen Coder 重命名为百炼 (Bailian)（#965，感谢 @zhu-jl18）
|
||||
|
||||
### 其他新功能
|
||||
|
||||
- **Thinking Budget Rectifier**：代理矫正器，更精细地控制 thinking budget 分配（#1005，感谢 @yovinchen）
|
||||
- **WebDAV 自动同步**：支持自动同步配置，并增加大文件防护（#923，感谢 @clx20000410；#1043，感谢 @SaladDay）
|
||||
- **主题切换动画**：圆形揭示过渡动画，视觉体验更流畅（#905，感谢 @funnytime75）
|
||||
- **Claude 配置编辑器快速开关**：快速切换常用配置项（#1012，感谢 @JIA-ss）
|
||||
- **动态端点提示**：根据 API 格式选择动态显示端点提示文本（#860，感谢 @zhu-jl18）
|
||||
- **用量仪表盘增强**：自动刷新、更强健的数据格式化（#942，感谢 @yovinchen）
|
||||
- **新增定价数据**：claude-opus-4-6 和 gpt-5.3-codex（#943，感谢 @yovinchen）
|
||||
- **静默启动优化**：静默启动选项仅在开机启动开启时显示
|
||||
|
||||
---
|
||||
|
||||
## 架构改进
|
||||
|
||||
### 部分键值合并（⚠️ 破坏性变更）
|
||||
|
||||
供应商切换从全量配置覆写改为部分键值合并策略（#1098）。
|
||||
|
||||
**变更前**：切换供应商时，整个 `settings_config` 会覆写到 live 配置文件。这意味着用户在 live 文件中手动添加的非供应商设置（插件配置、MCP 配置、权限设置等）会在每次切换时丢失。为了弥补这个问题，之前版本提供了"通用配置片段"功能，让用户定义每次切换时都会合并的公共配置。
|
||||
|
||||
**变更后**：切换供应商时，仅替换供应商相关的键值（API Key、端点、模型等），用户的其余设置完整保留。因此"通用配置片段"功能不再需要，已被移除。
|
||||
|
||||
**影响与迁移**：
|
||||
- 如果你之前**没有使用**通用配置片段功能，此变更对你完全透明，切换体验只会更好
|
||||
- 如果你之前**使用了**通用配置片段功能来保留自定义设置（如 MCP 配置、权限等），升级后这些设置会在切换时自动保留，无需额外操作
|
||||
- 如果你利用通用配置片段做其他用途（如在切换时注入额外配置），请在升级后手动将这些配置写入 live 配置文件中
|
||||
|
||||
此次重构删除了 6 个前端文件（3 个组件 + 3 个 hooks）、约 150 行后端死代码。
|
||||
|
||||
### 手动导入替代自动导入
|
||||
|
||||
启动时不再自动导入外部配置，改为手动点击"导入当前配置"按钮，避免意外覆盖用户数据。
|
||||
|
||||
### OMO Variant 参数化
|
||||
|
||||
通过 `OmoVariant` 结构体参数化消除 OMO 模块约 250 行重复代码。
|
||||
|
||||
### OMO 公共配置移除
|
||||
|
||||
删除二层合并系统，减少约 1,733 行代码，简化架构。
|
||||
|
||||
### ProviderForm 拆分
|
||||
|
||||
ProviderForm 组件从 2,227 行减至 1,526 行，提取 5 个独立模块（opencodeFormUtils、useOmoModelSource、useOpencodeFormState、useOmoDraftState、useOpenclawFormState），可维护性显著提升。
|
||||
|
||||
### MCP/Skills 共享组件
|
||||
|
||||
提取 AppCountBar、AppToggleGroup、ListItemRow 等共享组件，减少 MCP 和 Skills 面板的重复代码（#897，感谢 @PeanutSplash）。
|
||||
|
||||
### 设置页面重构
|
||||
|
||||
设置页面重构为 5 标签页布局（通用 | 代理 | 高级 | 用量 | 关于），SettingsPage 代码从约 716 行减至约 426 行。
|
||||
|
||||
### 其他改进
|
||||
|
||||
- 终端统一：全局设置统一终端选择，新增 WezTerm 支持
|
||||
- Claude 模型引用从 4.5 更新到 4.6
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 严重修复
|
||||
|
||||
- **Windows 主目录回归**：恢复默认主目录解析，防止 Git/MSYS 环境下数据库路径变更导致数据"丢失"
|
||||
- **Linux 白屏**：禁用 AMD GPU 的 WebKitGTK 硬件加速，解决部分 Linux 系统启动白屏问题（#986，感谢 @ThendCN）
|
||||
- **OpenAI Beta 参数**：不再为 `/v1/chat/completions` 添加 `?beta=true`，修复 Nvidia 等使用 OpenAI Chat 格式的供应商请求失败（#1052，感谢 @jnorthrup）
|
||||
- **健康检查认证**：尊重供应商 `auth_mode` 设置，避免仅支持 Bearer 认证的代理服务健康检查失败（#824，感谢 @Jassy930）
|
||||
|
||||
### 供应商预设修复
|
||||
|
||||
- 修复 OpenClaw `/v1` 前缀双重路径问题
|
||||
- Opus 定价修正（$15/$75 → $5/$25）并升级到 4.6
|
||||
- AIGoCode URL 统一为 `https://api.aigocode.com`
|
||||
- Zhipu GLM 移除过时合作伙伴状态
|
||||
- 新建 Claude 供应商时 API Key 输入框可见性恢复
|
||||
- 非活跃供应商隐藏快速开关，显示上下文感知的 JSON 编辑器提示
|
||||
|
||||
### OMO 修复
|
||||
|
||||
- omo-slim 分类检查补齐（add/form/mutation 路径）
|
||||
- OMO Slim 供应商变更后正确失效查询缓存
|
||||
- OMO agent/category 推荐模型与上游源同步
|
||||
- "填充推荐"按钮失败时增加 toast 反馈
|
||||
- 移除 OMO/OMO Slim 最后一个供应商的删除限制
|
||||
- OpenCode 未配置模型时拒绝保存（#932，感谢 @yovinchen）
|
||||
|
||||
### OpenClaw 修复
|
||||
|
||||
- 修复 25 个缺失 i18n key、替换 key={index} 为稳定 ID、深链接 additive 合并等代码审查问题
|
||||
- EnvPanel 健壮性增强（NaN 守卫、使用条目键名而非数组索引）
|
||||
- i18n 重复键合并，恢复供应商表单翻译
|
||||
|
||||
### 平台修复
|
||||
|
||||
- Windows 静默启动时窗口闪烁（#901，感谢 @funnytime75）
|
||||
- 标题栏暗黑模式跟随主题（#903，感谢 @funnytime75）
|
||||
- Windows Skills 路径分隔符匹配（#868，感谢 @stmoonar）
|
||||
- WSL 辅助函数条件编译
|
||||
|
||||
### UI 修复
|
||||
|
||||
- 工具栏高度裁切导致 AppSwitcher 被遮挡
|
||||
- 有新版本时显示更新徽章而非绿色对勾
|
||||
- 仅 Claude/Codex 应用显示会话管理器按钮
|
||||
- SQL 导入/导出卡片暗黑模式样式统一（#1067，感谢 @SaladDay）
|
||||
|
||||
### 其他修复
|
||||
|
||||
- 会话管理器硬编码中文字符串替换为 i18n key
|
||||
- Skill 文档 URL 分支和路径修正（#977，感谢 @yovinchen）
|
||||
- OpenCode install.sh 安装路径检测补齐（#988，感谢 @zhu-jl18）
|
||||
- Skill ZIP 符号链接解析修复（#1040，感谢 @yovinchen）
|
||||
- MCP 表单补齐 OpenCode 复选框（#1026，感谢 @yovinchen）
|
||||
- useProvidersQuery 中自动导入副作用移除
|
||||
|
||||
---
|
||||
|
||||
## 性能优化
|
||||
|
||||
- 会话面板并行目录扫描 + 头尾 JSONL 读取，大幅提升会话列表加载速度
|
||||
- 移除 Tauri 本地 IPC 不必要的 query cache，减少内存占用
|
||||
|
||||
---
|
||||
|
||||
## 文档
|
||||
|
||||
- 赞助商更新：SSSAiCode、Crazyrouter、AICoding、Right Code、MiniMax
|
||||
- 新增用户手册（#979，感谢 @yovinchen）
|
||||
|
||||
---
|
||||
|
||||
## 说明与注意事项
|
||||
|
||||
- **OpenClaw 为新支持的应用**：需要先安装 OpenClaw CLI 才能使用相关功能。
|
||||
- **⚠️ 通用配置片段功能已移除**：由于供应商切换改为部分键值合并（仅替换 API Key、端点、模型等字段），用户的其余设置会自动保留，"通用配置片段"功能不再需要。详见上方"架构改进"章节的迁移说明。
|
||||
- **自动导入已改为手动**：启动时不再自动导入外部配置，请在需要时手动点击"导入当前配置"。
|
||||
- **OMO 与 OMO Slim 互斥**：同一时间只能启用其中一个，切换时另一个会自动禁用。
|
||||
- **备份功能默认开启**：运行时每小时自动备份，可在备份面板调整策略。
|
||||
|
||||
---
|
||||
|
||||
## 特别感谢
|
||||
|
||||
感谢以下贡献者为本版本做出的贡献！
|
||||
|
||||
@TinsFox @keithyt06 @kv-chiu @SaladDay @jnorthrup @JIA-ss @clx20000410 @ThendCN @yovinchen @zhu-jl18 @myjustify @funnytime75 @PeanutSplash @Jassy930 @stmoonar
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
访问 [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.11.0-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.11.0-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| -------------------------------- | --------------------------------------------------------- |
|
||||
| `CC-Switch-v3.11.0-macOS.zip` | **推荐** - 解压后拖入 Applications 即可，Universal Binary |
|
||||
| `CC-Switch-v3.11.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` |
|
||||
@@ -0,0 +1,122 @@
|
||||
# CC Switch v3.11.1
|
||||
|
||||
> Revert Partial Key-Field Merging, Restore Common Config Snippet & Bug Fixes
|
||||
|
||||
**[中文版 →](v3.11.1-zh.md) | [日本語版 →](v3.11.1-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.11.1 is a hotfix release that reverts the **Partial Key-Field Merging** architecture introduced in v3.11.0, restoring the proven "**full config overwrite + Common Config Snippet**" mechanism. It also includes several UI and platform compatibility fixes.
|
||||
|
||||
**Release Date**: 2026-02-28
|
||||
|
||||
**Update Scale**: 8 commits | 52 files changed | +3,948 / -1,411 lines
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- **Restore Full Config Overwrite + Common Config Snippet**: Reverted partial key-field merging due to critical data loss issues; restores full config snapshot write and Common Config Snippet UI
|
||||
- **Proxy Panel Improvements**: Proxy toggle moved into panel body for better discoverability of takeover options
|
||||
- **Theme & Compact Mode Fixes**: "Follow System" theme now auto-updates; compact mode exit works correctly
|
||||
- **Windows Compatibility**: Disabled env check and one-click install to prevent protocol handler side effects
|
||||
|
||||
---
|
||||
|
||||
## Reverted
|
||||
|
||||
### Restore Full Config Overwrite + Common Config Snippet
|
||||
|
||||
Reverted the partial key-field merging refactoring introduced in v3.11.0 (revert 992dda5c).
|
||||
|
||||
**Why reverted**: The partial key-field merging approach had three critical issues:
|
||||
1. **Data loss on switch**: Non-whitelisted custom fields were silently dropped during provider switching
|
||||
2. **Permanent backfill stripping**: Backfill permanently removed non-key fields from the database, causing irreversible data loss
|
||||
3. **Maintenance burden**: The whitelist of "key fields" required constant maintenance as new config keys were added
|
||||
|
||||
**What's restored**:
|
||||
- Full config snapshot write on provider switch (predictable, complete overwrite)
|
||||
- Common Config Snippet UI and backend commands
|
||||
- 6 frontend components/hooks (3 components + 3 hooks)
|
||||
|
||||
**Migration**:
|
||||
- If you upgraded to v3.11.0 and your providers lost custom fields, re-import your config or manually re-add the missing fields
|
||||
- Common Config Snippet is available again — use it to define shared config that should persist across provider switches
|
||||
|
||||
---
|
||||
|
||||
## Changed
|
||||
|
||||
- **Proxy Panel Layout**: Moved proxy on/off toggle from accordion header into panel content area, placed directly above app takeover options. This ensures users see takeover configuration immediately after enabling the proxy, avoiding the common mistake of enabling the proxy without configuring takeover
|
||||
- **Manual Import for OpenCode/OpenClaw**: Removed auto-import on startup; empty state now shows an "Import Current Config" button, consistent with Claude/Codex/Gemini behavior
|
||||
|
||||
---
|
||||
|
||||
## Fixed
|
||||
|
||||
- **"Follow System" Theme Not Auto-Updating**: Delegated to Tauri's native theme tracking (`set_window_theme(None)`) so the WebView's `prefers-color-scheme` media query stays in sync with OS theme changes
|
||||
- **Compact Mode Cannot Exit**: Restored `flex-1` on `toolbarRef` so `useAutoCompact`'s exit condition triggers correctly based on available width instead of content width
|
||||
- **Proxy Takeover Toast Shows {{app}}**: Added missing `app` interpolation parameter to i18next `t()` calls for proxy takeover enabled/disabled messages
|
||||
- **Windows Protocol Handler Side Effects**: Disabled environment check and one-click install on Windows to prevent unintended protocol handler registration
|
||||
|
||||
---
|
||||
|
||||
## Notes & Considerations
|
||||
|
||||
- **Common Config Snippet is back**: If you relied on this feature in v3.10.x and earlier, it works the same way again. Define shared config that should persist across all provider switches.
|
||||
- **v3.11.0 Partial Key-Field Merging users**: If you noticed missing config fields after switching providers in v3.11.0, re-import your config to restore them.
|
||||
|
||||
---
|
||||
|
||||
## 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.11.1-Windows.msi` | **Recommended** - MSI installer with auto-update |
|
||||
| `CC-Switch-v3.11.1-Windows-Portable.zip` | Portable version, extract and run, no registry write |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| -------------------------------- | -------------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.11.1-macOS.zip` | **Recommended** - Extract and drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.11.1-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` |
|
||||
@@ -0,0 +1,122 @@
|
||||
# CC Switch v3.11.1
|
||||
|
||||
> 部分キーフィールドマージの撤回、共通設定スニペットの復元とバグ修正
|
||||
|
||||
**[中文版 →](v3.11.1-zh.md) | [English →](v3.11.1-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.11.1 は修正リリースです。v3.11.0 で導入された**部分キーフィールドマージ**アーキテクチャを撤回し、実績のある「**完全設定上書き + 共通設定スニペット**」メカニズムを復元しました。また、複数の UI とプラットフォーム互換性の問題を修正しています。
|
||||
|
||||
**リリース日**: 2026-02-28
|
||||
|
||||
**更新規模**: 8 commits | 52 files changed | +3,948 / -1,411 lines
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **完全設定上書き + 共通設定スニペットの復元**: 重大なデータ損失問題のため部分キーフィールドマージを撤回、完全設定スナップショット書き込みと共通設定スニペット UI を復元
|
||||
- **プロキシパネルの改善**: プロキシトグルをパネル本体に移動し、テイクオーバーオプションの発見性を向上
|
||||
- **テーマとコンパクトモードの修正**: 「システムに従う」テーマが正しく自動更新、コンパクトモードの終了が正常に動作
|
||||
- **Windows 互換性**: プロトコルハンドラーの副作用を防ぐため、環境チェックとワンクリックインストールを無効化
|
||||
|
||||
---
|
||||
|
||||
## 撤回
|
||||
|
||||
### 完全設定上書き + 共通設定スニペットの復元
|
||||
|
||||
v3.11.0 で導入された部分キーフィールドマージリファクタリングを撤回しました（revert 992dda5c）。
|
||||
|
||||
**撤回理由**: 部分キーフィールドマージのアプローチには3つの重大な問題がありました：
|
||||
1. **切り替え時のデータ損失**: ホワイトリストにないカスタムフィールドがプロバイダー切り替え時にサイレントに破棄された
|
||||
2. **バックフィルによる永続的な剥離**: バックフィル操作がデータベースから非キーフィールドを永続的に削除し、不可逆なデータ損失を引き起こした
|
||||
3. **メンテナンス負担**: 「キーフィールド」のホワイトリストは新しい設定キーが追加されるたびに継続的なメンテナンスが必要
|
||||
|
||||
**復元された内容**:
|
||||
- プロバイダー切り替え時の完全設定スナップショット書き込み（予測可能な完全上書き）
|
||||
- 共通設定スニペット UI およびバックエンドコマンド
|
||||
- 6つのフロントエンドファイル（コンポーネント 3つ + hooks 3つ）
|
||||
|
||||
**移行ガイド**:
|
||||
- v3.11.0 にアップグレードしてプロバイダーのカスタムフィールドが失われた場合は、設定を再インポートするか、欠落したフィールドを手動で追加してください
|
||||
- 共通設定スニペット機能が再び利用可能です — プロバイダー切り替え時に保持すべき共有設定を定義するために使用してください
|
||||
|
||||
---
|
||||
|
||||
## 変更
|
||||
|
||||
- **プロキシパネルレイアウト**: プロキシのオン/オフトグルをアコーディオンヘッダーからパネルのコンテンツエリアに移動し、アプリテイクオーバーオプションの直上に配置。プロキシを有効にした後すぐにテイクオーバー設定が見えるようになり、「プロキシだけ有効にしてテイクオーバーを設定しない」というよくある誤操作を防止
|
||||
- **OpenCode/OpenClaw の手動インポート**: 起動時の自動インポートを削除。空の状態ページに「現在の設定をインポート」ボタンを表示し、Claude/Codex/Gemini と同じ動作に統一
|
||||
|
||||
---
|
||||
|
||||
## 修正
|
||||
|
||||
- **「システムに従う」テーマが自動更新されない**: Tauri のネイティブテーマ追跡（`set_window_theme(None)`）に委譲し、WebView の `prefers-color-scheme` メディアクエリが OS テーマの変更に同期するように修正
|
||||
- **コンパクトモードを終了できない**: `toolbarRef` の `flex-1` を復元し、`useAutoCompact` の終了条件がコンテンツ幅ではなく利用可能な幅に基づいて正しくトリガーされるように修正
|
||||
- **プロキシテイクオーバー Toast に {{app}} が表示される**: プロキシテイクオーバーの有効/無効メッセージの i18next `t()` 呼び出しに欠落していた `app` 補間パラメータを追加
|
||||
- **Windows プロトコルハンドラーの副作用**: 意図しないプロトコルハンドラー登録を防ぐため、Windows で環境チェックとワンクリックインストールを無効化
|
||||
|
||||
---
|
||||
|
||||
## 注意事項
|
||||
|
||||
- **共通設定スニペットが復活しました**: v3.10.x 以前でこの機能を使用していた場合、同じ方法で動作します。プロバイダー切り替え時に保持すべき共有設定を定義するために使用してください。
|
||||
- **v3.11.0 部分キーフィールドマージユーザーの方へ**: v3.11.0 でプロバイダー切り替え後に設定フィールドが欠落していた場合は、設定を再インポートして復元してください。
|
||||
|
||||
---
|
||||
|
||||
## ダウンロードとインストール
|
||||
|
||||
[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.11.1-Windows.msi` | **推奨** - MSI インストーラー、自動更新対応 |
|
||||
| `CC-Switch-v3.11.1-Windows-Portable.zip` | ポータブル版、解凍して実行、レジストリ書き込みなし |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| -------------------------------- | ----------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.11.1-macOS.zip` | **推奨** - 解凍して Applications にドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.11.1-macOS.tar.gz` | Homebrew インストールと自動更新用 |
|
||||
|
||||
> **注意**: 作者が Apple Developer アカウントを持っていないため、初回起動時に「開発元を確認できません」という警告が表示される場合があります。一度閉じてから、「システム設定」→「プライバシーとセキュリティ」→「このまま開く」をクリックすると、その後は正常に開けます。
|
||||
|
||||
### 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` |
|
||||
@@ -0,0 +1,122 @@
|
||||
# CC Switch v3.11.1
|
||||
|
||||
> 回退部分键值合并、恢复通用配置片段与多项修复
|
||||
|
||||
**[English →](v3.11.1-en.md) | [日本語版 →](v3.11.1-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.11.1 是一个修复版本，回退了 v3.11.0 中引入的**部分键值合并**架构，恢复经过验证的「**全量配置覆写 + 通用配置片段**」机制，同时修复了多个 UI 和平台兼容性问题。
|
||||
|
||||
**发布日期**：2026-02-28
|
||||
|
||||
**更新规模**：8 commits | 52 files changed | +3,948 / -1,411 lines
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- **恢复全量配置覆写 + 通用配置片段**：因关键数据丢失问题回退部分键值合并，恢复完整配置快照写入和通用配置片段 UI
|
||||
- **代理面板交互优化**：代理开关移入面板内部，接管选项一目了然
|
||||
- **主题与紧凑模式修复**：「跟随系统」主题现可正确自动更新，紧凑模式退出恢复正常
|
||||
- **Windows 兼容性**：禁用环境检查和一键安装，防止协议处理程序副作用
|
||||
|
||||
---
|
||||
|
||||
## 回退
|
||||
|
||||
### 恢复全量配置覆写 + 通用配置片段
|
||||
|
||||
回退了 v3.11.0 中引入的部分键值合并重构（revert 992dda5c）。
|
||||
|
||||
**回退原因**：部分键值合并方案存在三个关键缺陷：
|
||||
1. **切换时数据丢失**：非白名单的自定义字段在供应商切换时被静默丢弃
|
||||
2. **回填永久剥离**：回填操作永久移除数据库中的非键字段，造成不可逆的数据丢失
|
||||
3. **维护成本高**：「键字段」白名单需要随新配置项不断维护，容易遗漏
|
||||
|
||||
**恢复的内容**：
|
||||
- 供应商切换时的完整配置快照写入（可预测的全量覆写）
|
||||
- 通用配置片段 UI 及后端命令
|
||||
- 6 个前端文件（3 个组件 + 3 个 hooks）
|
||||
|
||||
**迁移说明**：
|
||||
- 如果你在 v3.11.0 中切换供应商后丢失了自定义字段，请重新导入配置或手动补回缺失的字段
|
||||
- 通用配置片段功能已恢复——用它来定义切换供应商时需要保留的共享配置
|
||||
|
||||
---
|
||||
|
||||
## 变更
|
||||
|
||||
- **代理面板交互优化**：将代理开关从折叠面板标题移入面板内部，紧邻应用接管选项。确保用户启用代理后能立即看到接管配置，避免「只开代理不接管」的常见误操作
|
||||
- **OpenCode/OpenClaw 手动导入**：移除启动时自动导入供应商配置的行为，改为在空状态页显示「导入当前配置」按钮，与 Claude/Codex/Gemini 保持一致
|
||||
|
||||
---
|
||||
|
||||
## 修复
|
||||
|
||||
- **「跟随系统」主题不自动更新**：改用 Tauri 原生主题追踪（`set_window_theme(None)`），使 WebView 的 `prefers-color-scheme` 媒体查询能正确响应 OS 主题切换
|
||||
- **紧凑模式无法退出**：恢复 `toolbarRef` 上的 `flex-1` class，修复 `useAutoCompact` 的退出条件因宽度计算错误而永远不触发的问题
|
||||
- **代理接管 Toast 显示 {{app}}**：为 proxy takeover 的 i18next `t()` 调用补充缺失的 `app` 插值参数
|
||||
- **Windows 协议处理副作用**：在 Windows 上禁用环境检查和一键安装功能，防止协议处理程序注册引发的意外副作用
|
||||
|
||||
---
|
||||
|
||||
## 说明与注意事项
|
||||
|
||||
- **通用配置片段已恢复**：如果你在 v3.10.x 及更早版本中使用了此功能，它的工作方式与之前完全一致。用它来定义切换供应商时需要保留的共享配置。
|
||||
- **v3.11.0 部分键值合并用户**：如果你在 v3.11.0 中切换供应商后发现配置字段丢失，请重新导入配置以恢复。
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
访问 [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.11.1-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.11.1-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| -------------------------------- | --------------------------------------------------------- |
|
||||
| `CC-Switch-v3.11.1-macOS.zip` | **推荐** - 解压后拖入 Applications 即可，Universal Binary |
|
||||
| `CC-Switch-v3.11.1-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` |
|
||||
@@ -0,0 +1,238 @@
|
||||
# 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` |
|
||||
@@ -0,0 +1,238 @@
|
||||
# CC Switch v3.12.0
|
||||
|
||||
> Stream Check が復活し、OpenAI Responses API に対応、OpenClaw と WebDAV も大幅強化
|
||||
|
||||
**[中文版 →](v3.12.0-zh.md) | [English →](v3.12.0-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.12.0 は、プロバイダー互換性、OpenClaw の設定編集、共通設定の使い勝手、同期とデータ保守性を強化する機能リリースです。安定性を強化した **Model Health Check (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"` を追加し、双方向変換と共有変換ロジックの整理を実施 — プロバイダー追加時に Responses API フォーマットを選択してプロキシテイクオーバーを有効にするだけで、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、incremental 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 トグル: リクエストに OpenClaw 識別子を付加する機能（デフォルトオフ）
|
||||
- Legacy timeout 設定の自動マイグレーション
|
||||
|
||||
### プロバイダープリセット
|
||||
|
||||
新規および既存のプロバイダープリセットを拡張し、より多くのプロバイダーとユースケースをカバーします。
|
||||
|
||||
- **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: 同期時にローカル専用テーブルを除外した 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 初回自動抽出
|
||||
|
||||
初回起動時にデータベースに Common Config Snippet がまだ存在しない場合、現在の live config から自動抽出します。これにより旧バージョンからアップグレードしたユーザーの既存の共通設定が失われないことを保証します。
|
||||
|
||||
### 定期メンテナンスタイマー統合
|
||||
|
||||
daily rollups と auto-vacuum を統一の定期メンテナンスタイマーに統合し、複数の独立タイマーによるリソース競合と複雑さを回避しました。
|
||||
|
||||
---
|
||||
|
||||
## バグ修正
|
||||
|
||||
### プロキシとストリーミング
|
||||
|
||||
- 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 個の欠落翻訳キーを補完し、残りのハードコード中国語を除去
|
||||
- model test panel の i18n 問題を修正
|
||||
- JSON5 slash escaping を正規化し、国際化文字列の解析異常を回避
|
||||
|
||||
### UI 修正
|
||||
|
||||
- Skills カウント表示の問題を修正（#1295、@fzzv に感謝）
|
||||
- endpoint speed test から HTTP ステータスコード表示を削除し、視覚的ノイズを軽減
|
||||
- outline button のスタイル問題を修正（#1222、@Sube-py に感謝）
|
||||
|
||||
---
|
||||
|
||||
## パフォーマンス
|
||||
|
||||
- OpenClaw 設定が未変更の場合に不要な書き込みをスキップし、ディスク I/O を削減
|
||||
|
||||
---
|
||||
|
||||
## ドキュメント
|
||||
|
||||
- ユーザーマニュアルを i18n 対応で再構成し、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 インストールと自動更新用 |
|
||||
|
||||
> **注意**: 作者が Apple Developer アカウントを持っていないため、初回起動時に「開発元を確認できません」という警告が表示される場合があります。一度閉じてから、「システム設定」→「プライバシーとセキュリティ」→「このまま開く」をクリックすると、その後は正常に開けます。
|
||||
|
||||
### 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` |
|
||||
@@ -0,0 +1,238 @@
|
||||
# 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` |
|
||||
@@ -0,0 +1,146 @@
|
||||
# CC Switch v3.12.1
|
||||
|
||||
> Stability Fixes, StepFun Presets, OpenClaw authHeader, and New Sponsor Partners
|
||||
|
||||
**[中文版 →](v3.12.1-zh.md) | [日本語版 →](v3.12.1-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.12.1 is a patch release focused on stability improvements and bug fixes. It resolves a Common Config modal infinite reopen loop, a WebDAV sync foreign key constraint failure, and several i18n interpolation issues. It also adds **StepFun** provider presets, **OpenClaw input type selection** and **authHeader** support, upgrades the default Gemini model to **3.1-pro**, and welcomes four new sponsor partners.
|
||||
|
||||
**Release Date**: 2026-03-12
|
||||
|
||||
**Update Scale**: 19 commits | 56 files changed | +1,429 / -396 lines
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- **Common Config modal fix**: Resolved an infinite reopen loop in the Common Config modal and added draft editing support
|
||||
- **WebDAV sync reliability**: Fixed a foreign key constraint failure when restoring `provider_health` during WebDAV sync
|
||||
- **StepFun presets**: Added StepFun (阶跃星辰) provider presets including the step-3.5-flash model
|
||||
- **OpenClaw enhancements**: Added input type selection for model Advanced Options and `authHeader` field for vendor-specific auth header support
|
||||
- **Gemini model upgrade**: Upgraded default Gemini model to 3.1-pro in provider presets
|
||||
- **New sponsors**: Welcomed Micu API, XCodeAPI, SiliconFlow, and CTok as sponsor partners
|
||||
|
||||
---
|
||||
|
||||
## New Features
|
||||
|
||||
### StepFun Provider Presets
|
||||
|
||||
Added provider presets for StepFun (阶跃星辰), a leading Chinese AI model provider.
|
||||
|
||||
- New preset entries for StepFun across supported applications
|
||||
- Includes the step-3.5-flash model (#1369, thanks @hengm3467)
|
||||
|
||||
### OpenClaw Enhancements
|
||||
|
||||
Enhanced the OpenClaw configuration with more granular control and better vendor compatibility.
|
||||
|
||||
- Added input type selection dropdown for model Advanced Options (#1368, thanks @liuxxxu)
|
||||
- Added optional `authHeader` boolean to `OpenClawProviderConfig` for vendor-specific auth header support (e.g. Longcat), and refactored form state to reuse the shared type
|
||||
|
||||
### Sponsor Partners
|
||||
|
||||
- **Micu API**: Added Micu API as sponsor partner with affiliate links
|
||||
- **XCodeAPI**: Added XCodeAPI as sponsor partner
|
||||
- **SiliconFlow**: Added SiliconFlow (硅基流动) as sponsor partner with affiliate links
|
||||
- **CTok**: Added CTok as sponsor partner
|
||||
|
||||
---
|
||||
|
||||
## Changes
|
||||
|
||||
- **UCloud → Compshare**: Renamed UCloud provider to Compshare (优云智算) with full i18n support across all three locales (EN/ZH/JA)
|
||||
- **Compshare Links**: Updated Compshare sponsor registration links to coding-plan page
|
||||
- **Gemini Model Upgrade**: Upgraded default Gemini model from 2.5-pro to 3.1-pro in provider presets
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Common Config & UI
|
||||
|
||||
- Fixed an infinite reopen loop in the Common Config modal and added draft editing support to prevent data loss during edits
|
||||
- Fixed toolbar compact mode not triggering on Windows due to left-side overflow (#1375, thanks @zuoliangyu)
|
||||
- Fixed session search index not syncing with query data, causing stale list display after session deletion
|
||||
|
||||
### Sync & Data
|
||||
|
||||
- Fixed foreign key constraint failure when restoring `provider_health` table during WebDAV sync
|
||||
|
||||
### Provider & Preset
|
||||
|
||||
- Added missing `authHeader: true` to Longcat provider preset (#1377, thanks @wavever)
|
||||
- Aligned OpenClaw tool permission profiles with upstream schema (#1355, thanks @bigsongeth)
|
||||
- Corrected X-Code API URL from `www.x-code.cn` to `x-code.cc`
|
||||
|
||||
### i18n & Localization
|
||||
|
||||
- Fixed stream check toast i18n interpolation keys not matching translation placeholders
|
||||
- Fixed proxy startup toast not interpolating address and port values (#1399, thanks @Mason-mengze)
|
||||
- Renamed OpenCode API format label from "OpenAI" to "OpenAI Responses" for accuracy
|
||||
|
||||
---
|
||||
|
||||
## Special Thanks
|
||||
|
||||
Thanks to all contributors for their contributions to this release!
|
||||
|
||||
@hengm3467 @liuxxxu @bigsongeth @zuoliangyu @wavever @Mason-mengze
|
||||
|
||||
---
|
||||
|
||||
## 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.1-Windows.msi` | **Recommended** - MSI installer with auto-update |
|
||||
| `CC-Switch-v3.12.1-Windows-Portable.zip` | Portable version, extract and run, no registry write |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| ---------------------------------- | -------------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.12.1-macOS.zip` | **Recommended** - Extract and drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.12.1-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` |
|
||||
@@ -0,0 +1,146 @@
|
||||
# CC Switch v3.12.1
|
||||
|
||||
> 安定性修正、StepFun プリセット、OpenClaw authHeader 対応、新スポンサーパートナー
|
||||
|
||||
**[中文版 →](v3.12.1-zh.md) | [English →](v3.12.1-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.12.1 は、安定性の改善とバグ修正に焦点を当てたパッチリリースです。共通設定モーダルの無限再オープンループ、WebDAV 同期時の外部キー制約エラー、複数の i18n 補間問題を修正しました。また、**StepFun（阶跃星辰）** プロバイダープリセットの追加、OpenClaw の**入力タイプ選択**と **authHeader** サポート、デフォルト Gemini モデルの **3.1-pro** へのアップグレード、4 つの新スポンサーパートナーの追加が含まれます。
|
||||
|
||||
**リリース日**: 2026-03-12
|
||||
|
||||
**更新規模**: 19 commits | 56 files changed | +1,429 / -396 lines
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **共通設定モーダル修正**: 共通設定モーダルの無限再オープンループを解決し、下書き編集サポートを追加
|
||||
- **WebDAV 同期の信頼性向上**: WebDAV 同期で `provider_health` 復元時の外部キー制約エラーを修正
|
||||
- **StepFun プリセット**: StepFun（阶跃星辰）プロバイダープリセットを追加、step-3.5-flash モデルを含む
|
||||
- **OpenClaw 強化**: モデル詳細設定に入力タイプ選択を追加、ベンダー固有の認証ヘッダーサポート用 `authHeader` フィールドを追加
|
||||
- **Gemini モデルアップグレード**: プロバイダープリセットのデフォルト Gemini モデルを 3.1-pro にアップグレード
|
||||
- **新スポンサー**: Micu API、XCodeAPI、SiliconFlow、CTok をスポンサーパートナーとして追加
|
||||
|
||||
---
|
||||
|
||||
## 新機能
|
||||
|
||||
### StepFun プロバイダープリセット
|
||||
|
||||
中国の主要 AI モデルプロバイダーである StepFun（阶跃星辰）のプロバイダープリセットを追加しました。
|
||||
|
||||
- サポート対象アプリケーション全体に StepFun プリセットエントリーを追加
|
||||
- step-3.5-flash モデルを含む（#1369、@hengm3467 に感謝）
|
||||
|
||||
### OpenClaw 強化
|
||||
|
||||
OpenClaw 設定をより細かく制御でき、ベンダー互換性を向上させました。
|
||||
|
||||
- モデル詳細設定に入力タイプ（input type）選択ドロップダウンを追加（#1368、@liuxxxu に感謝）
|
||||
- `OpenClawProviderConfig` にオプションの `authHeader` ブール値を追加し、ベンダー固有の認証ヘッダー（例: Longcat）をサポート。フォーム状態を共有型の再利用にリファクタリング
|
||||
|
||||
### スポンサーパートナー
|
||||
|
||||
- **Micu API**: Micu API をスポンサーパートナーとして追加、アフィリエイトリンク付き
|
||||
- **XCodeAPI**: XCodeAPI をスポンサーパートナーとして追加
|
||||
- **SiliconFlow**: SiliconFlow（硅基流动）をスポンサーパートナーとして追加、アフィリエイトリンク付き
|
||||
- **CTok**: CTok をスポンサーパートナーとして追加
|
||||
|
||||
---
|
||||
|
||||
## 変更
|
||||
|
||||
- **UCloud → Compshare**: UCloud プロバイダーを Compshare（优云智算）にリネームし、3 言語（EN/ZH/JA）の完全な i18n サポートを追加
|
||||
- **Compshare リンク**: Compshare スポンサー登録リンクを coding-plan ページに更新
|
||||
- **Gemini モデルアップグレード**: プロバイダープリセットのデフォルト Gemini モデルを 2.5-pro から 3.1-pro にアップグレード
|
||||
|
||||
---
|
||||
|
||||
## バグ修正
|
||||
|
||||
### 共通設定と UI
|
||||
|
||||
- 共通設定モーダルの無限再オープンループを修正し、編集中のデータ損失を防ぐための下書き編集サポートを追加
|
||||
- Windows でツールバーコンパクトモードが左側のオーバーフローにより機能しない問題を修正（#1375、@zuoliangyu に感謝）
|
||||
- セッション削除後にクエリデータと検索インデックスが同期されず、リストが更新されない問題を修正
|
||||
|
||||
### 同期とデータ
|
||||
|
||||
- WebDAV 同期で `provider_health` テーブルを復元する際の外部キー制約エラーを修正
|
||||
|
||||
### プロバイダーとプリセット
|
||||
|
||||
- Longcat プロバイダープリセットに欠落していた `authHeader: true` を追加（#1377、@wavever に感謝）
|
||||
- OpenClaw のツール権限プロファイルをアップストリームスキーマに合わせて修正（#1355、@bigsongeth に感謝）
|
||||
- X-Code API の URL を `www.x-code.cn` から `x-code.cc` に修正
|
||||
|
||||
### i18n とローカリゼーション
|
||||
|
||||
- Stream Check トーストの i18n 補間キーが翻訳プレースホルダーと一致しない問題を修正
|
||||
- プロキシ起動トーストでアドレスとポート値が補間されない問題を修正（#1399、@Mason-mengze に感謝）
|
||||
- OpenCode の API フォーマットラベルを「OpenAI」から「OpenAI Responses」にリネームし、正確性を向上
|
||||
|
||||
---
|
||||
|
||||
## 謝辞
|
||||
|
||||
以下のコントリビューターの皆様、このリリースへの貢献に感謝します！
|
||||
|
||||
@hengm3467 @liuxxxu @bigsongeth @zuoliangyu @wavever @Mason-mengze
|
||||
|
||||
---
|
||||
|
||||
## ダウンロードとインストール
|
||||
|
||||
[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.1-Windows.msi` | **推奨** - MSI インストーラー、自動更新対応 |
|
||||
| `CC-Switch-v3.12.1-Windows-Portable.zip` | ポータブル版、解凍して実行、レジストリ書き込みなし |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| ---------------------------------- | ----------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.12.1-macOS.zip` | **推奨** - 解凍して Applications にドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.12.1-macOS.tar.gz` | Homebrew インストールと自動更新用 |
|
||||
|
||||
> **注意**: 作者が Apple Developer アカウントを持っていないため、初回起動時に「開発元を確認できません」という警告が表示される場合があります。一度閉じてから、「システム設定」→「プライバシーとセキュリティ」→「このまま開く」をクリックすると、その後は正常に開けます。
|
||||
|
||||
### 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` |
|
||||
@@ -0,0 +1,146 @@
|
||||
# CC Switch v3.12.1
|
||||
|
||||
> 稳定性修复、StepFun 预设、OpenClaw authHeader 支持，以及新赞助商伙伴
|
||||
|
||||
**[English →](v3.12.1-en.md) | [日本語版 →](v3.12.1-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.12.1 是一个以稳定性改进和 Bug 修复为主的补丁版本。修复了通用配置弹窗无限重复打开的循环问题、WebDAV 同步时的外键约束失败以及多个 i18n 插值问题。同时新增了 **StepFun（阶跃星辰）** 供应商预设、OpenClaw **输入类型选择** 和 **authHeader** 支持，将默认 Gemini 模型升级到 **3.1-pro**，并欢迎四位新赞助商伙伴加入。
|
||||
|
||||
**发布日期**：2026-03-12
|
||||
|
||||
**更新规模**：19 commits | 56 files changed | +1,429 / -396 lines
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- **通用配置弹窗修复**：解决了通用配置弹窗无限重复打开的循环问题，并新增草稿编辑支持
|
||||
- **WebDAV 同步可靠性**：修复了 WebDAV 同步恢复 `provider_health` 时的外键约束失败
|
||||
- **StepFun 预设**：新增 StepFun（阶跃星辰）供应商预设，包含 step-3.5-flash 模型
|
||||
- **OpenClaw 增强**：新增模型高级选项的输入类型选择和 `authHeader` 字段，支持供应商特定的认证头
|
||||
- **Gemini 模型升级**：供应商预设中的默认 Gemini 模型升级到 3.1-pro
|
||||
- **新赞助商**：欢迎 Micu API、XCodeAPI、SiliconFlow、CTok 加入赞助伙伴
|
||||
|
||||
---
|
||||
|
||||
## 新功能
|
||||
|
||||
### StepFun 供应商预设
|
||||
|
||||
新增 StepFun（阶跃星辰）供应商预设，阶跃星辰是领先的中国 AI 模型提供商。
|
||||
|
||||
- 在各支持应用中新增 StepFun 预设条目
|
||||
- 包含 step-3.5-flash 模型（#1369，感谢 @hengm3467）
|
||||
|
||||
### OpenClaw 增强
|
||||
|
||||
增强 OpenClaw 配置能力，提供更细粒度的控制和更好的供应商兼容性。
|
||||
|
||||
- 新增模型高级选项的输入类型（input type）选择下拉框（#1368，感谢 @liuxxxu）
|
||||
- 在 `OpenClawProviderConfig` 中新增可选的 `authHeader` 布尔字段，支持供应商特定的认证头（如 Longcat），并重构表单状态以复用共享类型
|
||||
|
||||
### 赞助商伙伴
|
||||
|
||||
- **Micu API**：新增 Micu API 赞助商及推广链接
|
||||
- **XCodeAPI**：新增 XCodeAPI 赞助商
|
||||
- **SiliconFlow**：新增 SiliconFlow（硅基流动）赞助商及推广链接
|
||||
- **CTok**：新增 CTok 赞助商
|
||||
|
||||
---
|
||||
|
||||
## 变更
|
||||
|
||||
- **UCloud → Compshare**：将 UCloud 供应商更名为 Compshare（优云智算），支持三种语言（中/英/日）的完整国际化
|
||||
- **Compshare 链接**：更新 Compshare 赞助商注册链接指向 coding-plan 页面
|
||||
- **Gemini 模型升级**：供应商预设中的默认 Gemini 模型从 2.5-pro 升级到 3.1-pro
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 通用配置与 UI
|
||||
|
||||
- 修复通用配置弹窗无限重复打开的循环问题，并新增草稿编辑支持以防止编辑过程中数据丢失
|
||||
- 修复 Windows 下因左侧溢出导致工具栏紧凑模式不触发的问题（#1375，感谢 @zuoliangyu）
|
||||
- 修复会话删除后搜索索引未与查询数据同步，导致列表显示过期的问题
|
||||
|
||||
### 同步与数据
|
||||
|
||||
- 修复 WebDAV 同步恢复 `provider_health` 表时的外键约束失败
|
||||
|
||||
### 供应商与预设
|
||||
|
||||
- 为 Longcat 供应商预设补充缺失的 `authHeader: true`（#1377，感谢 @wavever）
|
||||
- 对齐 OpenClaw 工具权限配置与上游 schema（#1355，感谢 @bigsongeth）
|
||||
- 修正 X-Code API URL，从 `www.x-code.cn` 改为 `x-code.cc`
|
||||
|
||||
### i18n 与本地化
|
||||
|
||||
- 修复 Stream Check Toast 的 i18n 插值 key 与翻译占位符不匹配
|
||||
- 修复代理启动 Toast 未正确插值地址和端口的问题（#1399，感谢 @Mason-mengze）
|
||||
- 将 OpenCode API 格式标签从 "OpenAI" 改为 "OpenAI Responses"，更准确地反映实际格式
|
||||
|
||||
---
|
||||
|
||||
## 特别感谢
|
||||
|
||||
感谢以下贡献者为本版本做出的贡献！
|
||||
|
||||
@hengm3467 @liuxxxu @bigsongeth @zuoliangyu @wavever @Mason-mengze
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
访问 [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.1-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.12.1-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| ---------------------------------- | --------------------------------------------------------- |
|
||||
| `CC-Switch-v3.12.1-macOS.zip` | **推荐** - 解压后拖入 Applications 即可，Universal Binary |
|
||||
| `CC-Switch-v3.12.1-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` |
|
||||
@@ -0,0 +1,138 @@
|
||||
# CC Switch v3.12.2
|
||||
|
||||
> Common Config Protection During Proxy Takeover, Snippet Lifecycle Stability, Section-Aware Codex TOML Editing
|
||||
|
||||
**[中文版 →](v3.12.2-zh.md) | [日本語版 →](v3.12.2-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.12.2 is a reliability-focused patch release that addresses Common Config loss during proxy takeover and improves Codex TOML editing accuracy. Proxy takeover hot-switches and provider sync now update the restore backup instead of overwriting live config files; the startup sequence has been reordered so snippets are extracted from clean live files before takeover state is restored; and Codex `base_url` editing has been refactored into a section-aware model that no longer appends to the end of the file.
|
||||
|
||||
**Release Date**: 2026-03-12
|
||||
|
||||
**Update Scale**: 5 commits | 22 files changed | +1,716 / -288 lines
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- **Empty state guidance**: Provider list empty state now shows detailed import instructions with a conditional Common Config snippet hint for Claude/Codex/Gemini
|
||||
|
||||
- **Proxy takeover restore flow rework**: Hot-switches and provider sync now refresh the restore backup instead of overwriting live config files, preserving the full user configuration on rollback
|
||||
- **Snippet lifecycle stability**: Introduced a `cleared` flag to prevent auto-extraction from resurrecting cleared snippets, and reordered startup to extract from clean state
|
||||
- **Section-aware Codex TOML editing**: `base_url` and `model` field reads/writes now target the correct `[model_providers.<name>]` section
|
||||
- **Codex MCP config protection**: Existing `mcp_servers` blocks in restore snapshots survive provider hot-switches via per-server-id merge instead of wholesale replacement, with provider/common-config definitions winning on conflict
|
||||
|
||||
---
|
||||
|
||||
## New Features
|
||||
|
||||
### Empty State Guidance
|
||||
|
||||
Improved the first-run experience with helpful guidance when the provider list is empty.
|
||||
|
||||
- Empty state page shows step-by-step import instructions
|
||||
- Conditionally displays a Common Config snippet hint for Claude/Codex/Gemini providers (not shown for OpenCode/OpenClaw)
|
||||
|
||||
---
|
||||
|
||||
## Changes
|
||||
|
||||
### Proxy Takeover Restore Flow
|
||||
|
||||
The proxy takeover hot-switch and provider sync logic has been reworked to protect Common Config throughout the takeover lifecycle.
|
||||
|
||||
- Provider sync now updates the restore backup instead of writing directly to live config files when takeover is active
|
||||
- Effective provider settings are rebuilt with Common Config applied before saving restore snapshots, so rollback restores the real user configuration
|
||||
- Legacy providers with inferred common config usage are automatically marked with `commonConfigEnabled=true`
|
||||
|
||||
### Codex TOML Editing Engine
|
||||
|
||||
Codex `config.toml` update logic has been refactored onto shared section-aware TOML helpers.
|
||||
|
||||
- New Rust module `codex_config.rs` with `update_codex_toml_field` and `remove_codex_toml_base_url_if`
|
||||
- New frontend utilities `getTomlSectionRange` / `getCodexProviderSectionName` for section-aware operations
|
||||
- Inline TOML editing logic scattered across `proxy.rs` now delegates to the new module
|
||||
|
||||
### Common Config Initialization Lifecycle
|
||||
|
||||
The startup sequence has been reordered for more robust snippet extraction and migration.
|
||||
|
||||
- Startup now auto-extracts Common Config snippets from clean live files before restoring proxy takeover state
|
||||
- Introduced a snippet `cleared` flag to track whether a user intentionally cleared a snippet
|
||||
- Persisted a one-time legacy migration flag to avoid repeated `commonConfigEnabled` backfills
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Common Config Loss
|
||||
|
||||
- Fixed multiple scenarios where Common Config could be dropped during proxy takeover: sync overwriting live files, hot-switches producing incomplete restore snapshots, and provider switches losing config changes
|
||||
|
||||
### Codex Restore Snapshot Preservation
|
||||
|
||||
- Fixed Codex takeover restore backups discarding existing `mcp_servers` blocks during provider hot-switches; changed MCP backup preservation from wholesale table replacement to per-server-id merge so provider/common-config MCP updates win on conflict while backup-only servers are retained
|
||||
|
||||
### Cleared Snippet Resurrection
|
||||
|
||||
- Fixed startup auto-extraction recreating Common Config snippets that users had intentionally cleared
|
||||
|
||||
### Codex `base_url` Misplacement
|
||||
|
||||
- Fixed Codex `base_url` extraction and editing not targeting the correct `[model_providers.<name>]` section, causing it to append to the file tail or confuse `mcp_servers.*.base_url` entries for provider endpoints
|
||||
|
||||
---
|
||||
|
||||
## 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.2-Windows.msi` | **Recommended** - MSI installer with auto-update |
|
||||
| `CC-Switch-v3.12.2-Windows-Portable.zip` | Portable version, extract and run, no registry write |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| ---------------------------------- | -------------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.12.2-macOS.zip` | **Recommended** - Extract and drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.12.2-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` |
|
||||
@@ -0,0 +1,138 @@
|
||||
# CC Switch v3.12.2
|
||||
|
||||
> プロキシテイクオーバー中の共通設定保護、Snippet ライフサイクルの安定化、Codex TOML セクション対応編集
|
||||
|
||||
**[中文版 →](v3.12.2-zh.md) | [English →](v3.12.2-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.12.2 は、信頼性を重視したパッチリリースです。プロキシテイクオーバーモードでの共通設定（Common Config）の消失問題を解決し、Codex TOML 設定の編集精度を改善しました。テイクオーバーのホットスイッチとプロバイダー同期は、ライブ設定ファイルを上書きする代わりにリストアバックアップを更新するようになりました。起動シーケンスを再整理し、テイクオーバー状態を復元する前にクリーンなライブファイルから Snippet を抽出するようにしました。また Codex の `base_url` 編集をセクション対応モデルにリファクタリングし、ファイル末尾への誤追加を防止しました。
|
||||
|
||||
**リリース日**: 2026-03-12
|
||||
|
||||
**更新規模**: 5 commits | 22 files changed | +1,716 / -288 lines
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **空状態ガイダンスの改善**: プロバイダーリストが空の場合に詳細なインポート手順を表示し、Claude/Codex/Gemini には共通設定 Snippet のヒントを条件付きで表示
|
||||
|
||||
- **プロキシテイクオーバーリストアフロー刷新**: ホットスイッチとプロバイダー同期がライブ設定ファイルの上書きではなくリストアバックアップの更新を行うようになり、ロールバック時に完全なユーザー設定を保持
|
||||
- **Snippet ライフサイクルの安定化**: `cleared` フラグを導入し、クリア済み Snippet の自動再抽出を防止。起動順序を調整してクリーンな状態から抽出
|
||||
- **Codex TOML セクション対応編集**: `base_url` と `model` フィールドの読み書きが正しい `[model_providers.<name>]` セクションを対象にするように改善
|
||||
- **Codex MCP 設定の保護**: プロバイダーホットスイッチ時にリストアスナップショット内の既存 `mcp_servers` ブロックが保持されるように修正。テーブル全体の置換からサーバー ID ごとのマージに変更し、プロバイダー/共通設定の MCP 定義が競合時に優先
|
||||
|
||||
---
|
||||
|
||||
## 新機能
|
||||
|
||||
### 空状態ガイダンスの改善
|
||||
|
||||
プロバイダーリストが空の場合の初回利用体験を改善しました。
|
||||
|
||||
- 空状態ページにプロバイダーインポートの操作ガイドを表示
|
||||
- Claude/Codex/Gemini アプリケーションに共通設定 Snippet のヒントを条件付きで表示（OpenCode/OpenClaw には非表示）
|
||||
|
||||
---
|
||||
|
||||
## 変更
|
||||
|
||||
### プロキシテイクオーバーリストアフロー
|
||||
|
||||
テイクオーバーのホットスイッチとプロバイダー同期ロジックをリファクタリングし、テイクオーバーライフサイクル全体で共通設定を保護します。
|
||||
|
||||
- テイクオーバーがアクティブな場合、プロバイダー同期がライブ設定ファイルへの直接書き込みではなくリストアバックアップを更新
|
||||
- リストアスナップショットの保存前に共通設定を適用した実効プロバイダー設定を再構築し、ロールバックで実際のユーザー設定を復元
|
||||
- 共通設定の使用が推測されるレガシープロバイダーに `commonConfigEnabled=true` を自動マーク
|
||||
|
||||
### Codex TOML 編集エンジン
|
||||
|
||||
Codex `config.toml` の更新ロジックを共有のセクション対応 TOML ヘルパーにリファクタリングしました。
|
||||
|
||||
- Rust 側に新モジュール `codex_config.rs` を追加（`update_codex_toml_field` と `remove_codex_toml_base_url_if`）
|
||||
- フロントエンドにセクション対応ユーティリティ `getTomlSectionRange` / `getCodexProviderSectionName` を追加
|
||||
- `proxy.rs` に散在していたインライン TOML 編集ロジックを新モジュールに委譲
|
||||
|
||||
### 共通設定初期化ライフサイクル
|
||||
|
||||
Snippet の抽出とマイグレーションをより堅牢にするため、起動シーケンスを再整理しました。
|
||||
|
||||
- 起動時にプロキシテイクオーバー状態を復元する前に、クリーンなライブファイルから共通設定 Snippet を自動抽出
|
||||
- Snippet の `cleared` フラグを導入し、ユーザーが意図的にクリアしたかどうかを追跡
|
||||
- 一回限りのレガシーマイグレーションフラグを永続化し、`commonConfigEnabled` のバックフィルの繰り返しを防止
|
||||
|
||||
---
|
||||
|
||||
## バグ修正
|
||||
|
||||
### 共通設定の消失
|
||||
|
||||
- プロキシテイクオーバー中に共通設定が消失する複数のシナリオを修正：同期によるライブファイルの上書き、ホットスイッチによる不完全なリストアスナップショット、プロバイダー切り替え時の設定変更の消失
|
||||
|
||||
### Codex リストアスナップショットの保護
|
||||
|
||||
- プロバイダーホットスイッチ時に Codex テイクオーバーリストアバックアップが既存の `mcp_servers` ブロックを破棄する問題を修正。MCP バックアップ保持をテーブル全体の置換からサーバー ID ごとのマージに変更し、プロバイダー/共通設定の MCP 更新が競合時に優先され、バックアップのみのサーバーも保持
|
||||
|
||||
### クリア済み Snippet の復活
|
||||
|
||||
- 起動時の自動抽出が、ユーザーが意図的にクリアした共通設定 Snippet を再作成する問題を修正
|
||||
|
||||
### Codex `base_url` の配置エラー
|
||||
|
||||
- Codex `base_url` の抽出と編集が正しい `[model_providers.<name>]` セクションを対象にせず、ファイル末尾に追加されたり `mcp_servers.*.base_url` をプロバイダーエンドポイントと誤認する問題を修正
|
||||
|
||||
---
|
||||
|
||||
## ダウンロードとインストール
|
||||
|
||||
[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.2-Windows.msi` | **推奨** - MSI インストーラー、自動更新対応 |
|
||||
| `CC-Switch-v3.12.2-Windows-Portable.zip` | ポータブル版、解凍して実行、レジストリ書き込みなし |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| ---------------------------------- | ----------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.12.2-macOS.zip` | **推奨** - 解凍して Applications にドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.12.2-macOS.tar.gz` | Homebrew インストールと自動更新用 |
|
||||
|
||||
> **注意**: 作者が Apple Developer アカウントを持っていないため、初回起動時に「開発元を確認できません」という警告が表示される場合があります。一度閉じてから、「システム設定」→「プライバシーとセキュリティ」→「このまま開く」をクリックすると、その後は正常に開けます。
|
||||
|
||||
### 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` |
|
||||
@@ -0,0 +1,138 @@
|
||||
# CC Switch v3.12.2
|
||||
|
||||
> 代理接管期间通用配置保护、Snippet 生命周期稳定性、Codex TOML Section 感知编辑
|
||||
|
||||
**[English →](v3.12.2-en.md) | [日本語版 →](v3.12.2-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.12.2 是一个以可靠性为核心的补丁版本，重点解决代理（Proxy）接管模式下通用配置（Common Config）丢失的问题，并改进了 Codex TOML 配置的编辑准确性。代理接管的热切换和供应商同步现在会更新恢复备份而非直接覆盖 live 文件；启动流程重新排序，确保先从干净的 live 文件提取 Snippet 再恢复接管状态；Codex 的 `base_url` 编辑重构为 Section 感知模式，不再错误追加到文件末尾。
|
||||
|
||||
**发布日期**：2026-03-12
|
||||
|
||||
**更新规模**：5 commits | 22 files changed | +1,716 / -288 lines
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- **首次使用引导优化**：供应商列表空状态显示详细的导入说明，Claude/Codex/Gemini 还会提示通用配置 Snippet 功能
|
||||
|
||||
- **代理接管恢复流程重构**：热切换和供应商同步现在刷新恢复备份，而非覆盖 live 配置文件，回滚时保留完整的用户配置
|
||||
- **Snippet 生命周期稳定**：引入 `cleared` 标志防止已清除的 Snippet 被自动重新提取，启动顺序调整确保从干净状态提取
|
||||
- **Codex TOML Section 感知编辑**：`base_url` 和 `model` 字段的读写现在定位到正确的 `[model_providers.<name>]` Section
|
||||
- **Codex MCP 配置保护**：热切换供应商时保留恢复快照中已有的 `mcp_servers` 配置块，按 server id 合并而非整表替换，供应商/通用配置的 MCP 定义优先
|
||||
|
||||
---
|
||||
|
||||
## 新功能
|
||||
|
||||
### 空状态引导优化
|
||||
|
||||
改善首次使用体验，当供应商列表为空时显示详细的导入说明。
|
||||
|
||||
- 空状态页面展示导入供应商的操作指引
|
||||
- 对 Claude/Codex/Gemini 应用有条件地显示通用配置 Snippet 提示（OpenCode/OpenClaw 不显示）
|
||||
|
||||
---
|
||||
|
||||
## 变更
|
||||
|
||||
### 代理接管恢复流程
|
||||
|
||||
代理接管的热切换和供应商同步逻辑经过重构，确保通用配置在整个接管生命周期中得到保护。
|
||||
|
||||
- 接管活跃时，供应商同步更新恢复备份而非直接写入 live 配置文件
|
||||
- 保存恢复快照前先应用通用配置，使回滚能还原真实的用户配置
|
||||
- 遗留供应商中推断使用了通用配置的条目自动标记 `commonConfigEnabled=true`
|
||||
|
||||
### Codex TOML 编辑引擎
|
||||
|
||||
将 Codex `config.toml` 的更新逻辑重构到共享的 Section 感知 TOML 辅助函数上。
|
||||
|
||||
- Rust 端新增 `codex_config.rs` 模块，包含 `update_codex_toml_field` 和 `remove_codex_toml_base_url_if`
|
||||
- 前端新增 `getTomlSectionRange` / `getCodexProviderSectionName` 等 Section 感知工具函数
|
||||
- `proxy.rs` 中散落的 TOML 内联编辑逻辑统一委托给新模块
|
||||
|
||||
### 通用配置初始化生命周期
|
||||
|
||||
启动流程重新排序，通用配置 Snippet 的提取和迁移逻辑更加健壮。
|
||||
|
||||
- 启动时先从干净的 live 文件自动提取通用配置 Snippet，再恢复代理接管状态
|
||||
- 引入 Snippet `cleared` 标志，追踪用户是否主动清除了某个 Snippet
|
||||
- 持久化一次性遗留迁移标志，避免重复执行旧版 `commonConfigEnabled` 回填
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 通用配置丢失
|
||||
|
||||
- 修复代理接管期间通用配置可能被丢弃的多种场景：同步覆盖 live 文件、热切换产生不完整的恢复快照、供应商切换丢失配置变更
|
||||
|
||||
### Codex 恢复快照保护
|
||||
|
||||
- 修复 Codex 接管恢复备份在供应商热切换时丢弃已有 `mcp_servers` 配置块的问题；将 MCP 备份保留策略从整表替换改为按 server id 合并，供应商/通用配置的 MCP 定义在冲突时优先，备份中独有的服务器仍被保留
|
||||
|
||||
### 已清除 Snippet 复活
|
||||
|
||||
- 修复启动时自动提取机制重新创建用户已主动清除的通用配置 Snippet 的问题
|
||||
|
||||
### Codex `base_url` 位置错误
|
||||
|
||||
- 修复 Codex `base_url` 提取和编辑未定位到正确的 `[model_providers.<name>]` Section，导致追加到文件末尾或误将 `mcp_servers.*.base_url` 识别为供应商端点的问题
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
访问 [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.2-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.12.2-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| ---------------------------------- | --------------------------------------------------------- |
|
||||
| `CC-Switch-v3.12.2-macOS.zip` | **推荐** - 解压后拖入 Applications 即可，Universal Binary |
|
||||
| `CC-Switch-v3.12.2-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` |
|
||||
@@ -0,0 +1,313 @@
|
||||
# CC Switch v3.12.3
|
||||
|
||||
> GitHub Copilot Reverse Proxy, macOS Code Signing & Notarization, Reasoning Effort Mapping, OpenCode SQLite Backend
|
||||
|
||||
**[中文版 →](v3.12.3-zh.md) | [日本語版 →](v3.12.3-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.12.3 is a major feature release that adds GitHub Copilot reverse proxy support with a dedicated Auth Center, introduces macOS code signing and Apple notarization for a seamless install experience, maps reasoning effort levels across providers, migrates OpenCode to a SQLite backend, enables Tool Search via the native `ENABLE_TOOL_SEARCH` environment variable toggle, and delivers a full skill backup/restore lifecycle. Additional improvements include proxy gzip compression, o-series model compatibility, Skills import rework, Ghostty terminal fix, Skills cache strategy optimization, Claude 4.6 context window update, and multiple bug fixes.
|
||||
|
||||
**Release Date**: 2026-03-24
|
||||
|
||||
**Update Scale**: 36 commits | 107 files changed | +9,124 / -802 lines
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- **GitHub Copilot reverse proxy**: Full Copilot proxy support with OAuth device flow authentication, token refresh, and request fingerprint emulation ([⚠️ Risk Notice](#️-risk-notice))
|
||||
- **Copilot Auth Center**: Dedicated authentication management UI for GitHub Copilot OAuth flow with token status display and one-click refresh
|
||||
- **macOS code signing & notarization**: macOS builds are now code-signed and notarized by Apple, eliminating the "unidentified developer" warning entirely
|
||||
- **Reasoning Effort mapping**: Proxy-layer auto-mapping — explicit `output_config.effort` takes priority, falling back to `budget_tokens` thresholds (<4 000→low, 4 000–16 000→medium, ≥16 000→high) for o-series and GPT-5+ models
|
||||
- **OpenCode SQLite backend**: Added SQLite session storage for OpenCode alongside existing JSON backend; dual-backend scan with SQLite priority on ID conflicts
|
||||
- **Codex 1M context window toggle**: One-click checkbox to set `model_context_window = 1000000` with auto-populated `model_auto_compact_token_limit`
|
||||
- **Disable Auto-Upgrade toggle**: Added `DISABLE_AUTOUPDATER` env var checkbox in the Claude Common Config editor to prevent Claude Code from auto-upgrading
|
||||
- **Tool Search env var toggle**: Tool Search enabled via Claude 2.1.76+ native `ENABLE_TOOL_SEARCH` environment variable in the Common Config editor — no binary patching required
|
||||
- **Skill backup/restore lifecycle**: Skills are automatically backed up before uninstall; backup list with restore and delete management added
|
||||
- **Proxy gzip compression**: Non-streaming proxy requests now auto-negotiate gzip compression, reducing bandwidth usage
|
||||
- **o-series model compatibility**: Chat Completions proxy correctly uses `max_completion_tokens` for o1/o3/o4-mini models; Responses API kept on the correct `max_output_tokens` field
|
||||
- **Skills import rework**: Replaced implicit filesystem-based app inference with explicit `ImportSkillSelection` to prevent incorrect multi-app activation
|
||||
- **Ghostty terminal support**: Fixed Claude session restore in Ghostty terminal
|
||||
|
||||
---
|
||||
|
||||
## New Features
|
||||
|
||||
### GitHub Copilot Reverse Proxy
|
||||
|
||||
Added full reverse proxy support for GitHub Copilot, enabling Copilot-authenticated requests to be forwarded through CC Switch.
|
||||
|
||||
- Implements OAuth device flow authentication for GitHub Copilot
|
||||
- Automatic token refresh and session management
|
||||
- Request fingerprint emulation for seamless compatibility
|
||||
- Integrated into the existing proxy infrastructure alongside Claude, Codex, and Gemini handlers
|
||||
|
||||
### Copilot Auth Center
|
||||
|
||||
A dedicated authentication management UI for GitHub Copilot.
|
||||
|
||||
- OAuth device flow with code display and browser-based authorization
|
||||
- Token status display showing expiration and validity
|
||||
- One-click token refresh without re-authentication
|
||||
- Integrated into the settings panel for easy access
|
||||
|
||||
### Reasoning Effort Mapping
|
||||
|
||||
Proxy-layer auto-mapping of reasoning effort for OpenAI o-series and GPT-5+ models.
|
||||
|
||||
- Two-tier resolution: explicit `output_config.effort` takes priority, falling back to thinking `budget_tokens` thresholds (<4 000→low, 4 000–16 000→medium, ≥16 000→high)
|
||||
- Covers both Chat Completions and Responses API paths with 17 unit tests
|
||||
|
||||
### OpenCode SQLite Backend
|
||||
|
||||
Added SQLite session storage support for OpenCode alongside the existing JSON backend.
|
||||
|
||||
- Dual-backend scan with SQLite priority on ID conflicts
|
||||
- Atomic session deletion and path validation
|
||||
- JSON backend remains functional for backwards compatibility
|
||||
|
||||
### Codex 1M Context Window Toggle
|
||||
|
||||
Added a one-click toggle for Codex 1M context window in the config editor.
|
||||
|
||||
- Checkbox sets `model_context_window = 1000000` in `config.toml`
|
||||
- Auto-populates `model_auto_compact_token_limit = 900000` when enabled
|
||||
- Unchecking removes both fields cleanly
|
||||
|
||||
### Disable Auto-Upgrade Toggle
|
||||
|
||||
Added a checkbox in the Claude Common Config editor to disable Claude Code auto-upgrades.
|
||||
|
||||
- Sets `DISABLE_AUTOUPDATER=1` in the environment configuration when enabled
|
||||
- Displayed alongside Teammates mode, Tool Search, and High Effort toggles
|
||||
|
||||
### Tool Search Environment Variable Toggle
|
||||
|
||||
Tool Search is now enabled via the native `ENABLE_TOOL_SEARCH` environment variable introduced in Claude 2.1.76+.
|
||||
|
||||
- Toggle available in the Common Config editor under environment variables
|
||||
- Sets `ENABLE_TOOL_SEARCH=1` in the Claude environment configuration
|
||||
- No binary patching required — uses Claude's built-in support
|
||||
|
||||
### macOS Code Signing & Notarization
|
||||
|
||||
macOS builds are now code-signed and notarized by Apple.
|
||||
|
||||
- Application signed with a valid Apple Developer certificate
|
||||
- Notarized through Apple's notarization service for Gatekeeper approval
|
||||
- DMG installer also signed and notarized
|
||||
- Eliminates the "unidentified developer" warning on first launch
|
||||
|
||||
### Skill Auto-Backup on Uninstall
|
||||
|
||||
Skill files are now automatically backed up before uninstall to prevent accidental data loss.
|
||||
|
||||
- Backups stored in `~/.cc-switch/skill-backups/` with all skill files and a `meta.json` containing original metadata
|
||||
- Old backups are automatically pruned to keep at most 20
|
||||
- Backup path is returned to the frontend and shown in the success toast
|
||||
|
||||
### Skill Backup Restore & Delete
|
||||
|
||||
Added management commands for skill backups created during uninstall.
|
||||
|
||||
- List all available skill backups with metadata
|
||||
- Restore copies files back to SSOT, saves the DB record, and syncs to the current app with rollback on failure
|
||||
- Delete removes the backup directory after a confirmation dialog
|
||||
- ConfirmDialog gains a configurable zIndex prop to support nested dialog stacking
|
||||
|
||||
---
|
||||
|
||||
## Changes
|
||||
|
||||
### Skills Cache Strategy Optimization
|
||||
|
||||
Optimized the Skills cache invalidation strategy for better performance.
|
||||
|
||||
- Reduced unnecessary cache refreshes during skill operations
|
||||
- Improved cache coherence between skill install/uninstall and list queries
|
||||
|
||||
### Claude 4.6 Context Window Update
|
||||
|
||||
Updated Claude 4.6 model preset with the latest context window size.
|
||||
|
||||
- Reflects the expanded context window for Claude 4.6 models
|
||||
- Updated in provider presets for accurate model information display
|
||||
|
||||
### MiniMax M2.7 Upgrade
|
||||
|
||||
- Updated MiniMax provider preset to M2.7 model variant
|
||||
|
||||
### Xiaomi MiMo Upgrade
|
||||
|
||||
- Updated Xiaomi MiMo provider preset to the latest model version
|
||||
|
||||
### AddProviderDialog Simplification
|
||||
|
||||
- Removed redundant OAuth tab, reducing dialog from 3 tabs to 2 (app-specific + universal)
|
||||
|
||||
### Provider Form Advanced Options Collapse
|
||||
|
||||
- Model mapping, API format, and other advanced fields in the Claude provider form now auto-collapse when empty
|
||||
- Auto-expands when any value is set or when a preset fills them in; does not auto-collapse when manually cleared
|
||||
|
||||
### Proxy Gzip Compression
|
||||
|
||||
Non-streaming proxy requests now support gzip compression for reduced bandwidth usage.
|
||||
|
||||
- Non-streaming requests let reqwest auto-negotiate gzip and transparently decompress responses
|
||||
- Streaming requests conservatively keep `Accept-Encoding: identity` to avoid decompression errors on interrupted SSE streams
|
||||
|
||||
### o1/o3 Model Compatibility
|
||||
|
||||
Proxy forwarding now handles OpenAI o-series model token parameters correctly.
|
||||
|
||||
- Chat Completions path uses `max_completion_tokens` instead of `max_tokens` for o1/o3/o4-mini models (#1451, thanks @Hemilt0n)
|
||||
- Responses API path kept on the correct `max_output_tokens` field instead of incorrectly injecting `max_completion_tokens`
|
||||
|
||||
### OpenCode Model Variants
|
||||
|
||||
- Placed OpenCode model variants at top level instead of inside options for better discoverability (#1317)
|
||||
|
||||
### Skills Import Flow
|
||||
|
||||
The Skills import flow has been reworked for correctness and cleanup.
|
||||
|
||||
- Replaced implicit filesystem-based app inference with explicit `ImportSkillSelection` to prevent incorrect multi-app activation when the same skill directory exists under multiple app paths
|
||||
- Added reconciliation to `sync_to_app` to remove disabled/orphaned symlinks
|
||||
- MCP `sync_all_enabled` now removes disabled servers from live config
|
||||
- Schema migration preserves a snapshot of legacy app mappings to avoid lossy reconstruction
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### WebDAV Password Clearing
|
||||
|
||||
- Fixed an issue where the WebDAV password was silently cleared when saving unrelated settings
|
||||
|
||||
### Tool Message Parsing
|
||||
|
||||
- Fixed incorrect parsing of tool-use messages in certain proxy response formats
|
||||
|
||||
### Dark Mode Styling
|
||||
|
||||
- Fixed dark mode rendering inconsistencies in UI components
|
||||
|
||||
### Copilot Request Fingerprint
|
||||
|
||||
- Fixed request fingerprint generation for Copilot proxy to match expected format
|
||||
|
||||
### Provider Form Double Submit
|
||||
|
||||
- Prevented duplicate submissions on rapid button clicks in provider add/edit forms (#1352, thanks @Hexi1997)
|
||||
|
||||
### Ghostty Session Restore
|
||||
|
||||
- Fixed Claude session restore in Ghostty terminal (#1506, thanks @canyonsehun)
|
||||
|
||||
### Skill ZIP Import Extension
|
||||
|
||||
- Added `.skill` file extension support in ZIP import dialog (#1240, #1455, thanks @yovinchen)
|
||||
|
||||
### Skill ZIP Install Target App
|
||||
|
||||
- ZIP skill installs now use the currently active app instead of always defaulting to Claude
|
||||
|
||||
### OpenClaw Active Card Highlight
|
||||
|
||||
- Fixed active OpenClaw provider card not being highlighted (#1419, thanks @funnytime75)
|
||||
|
||||
### Responsive Layout with TOC
|
||||
|
||||
- Improved responsive design when TOC title exists (#1491, thanks @West-Pavilion)
|
||||
|
||||
### Import Skills Dialog White Screen
|
||||
|
||||
- Added missing TooltipProvider in ImportSkillsDialog to prevent runtime crash when opening the dialog
|
||||
|
||||
### Panel Bottom Blank Area
|
||||
|
||||
- Replaced hardcoded `h-[calc(100vh-8rem)]` with `flex-1 min-h-0` across all content panels to eliminate bottom gap caused by mismatched offset values on different platforms
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
### Pricing Model ID Normalization
|
||||
|
||||
- Added documentation section explaining model ID normalization rules (prefix stripping, suffix trimming, `@`→`-` replacement) in EN/ZH/JA user manuals (#1591, thanks @makoMakoGo)
|
||||
|
||||
### macOS Signed Build Messaging
|
||||
|
||||
- Removed all `xattr` workaround instructions and "unidentified developer" warnings from README, README_ZH, installation guides (EN/ZH/JA), and FAQ pages (EN/ZH/JA); replaced with "signed and notarized by Apple" messaging
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Risk Notice
|
||||
|
||||
**GitHub Copilot Reverse Proxy Disclaimer**
|
||||
|
||||
The Copilot reverse proxy feature introduced in this release accesses GitHub Copilot services through reverse-engineered, unofficial APIs. Please be aware of the following risks before enabling this feature:
|
||||
|
||||
1. **Terms of Service**: This feature may violate [GitHub's Acceptable Use Policies](https://docs.github.com/en/site-policy/acceptable-use-policies/github-acceptable-use-policies) and [Terms for Additional Products and Features](https://docs.github.com/en/site-policy/github-terms/github-terms-for-additional-products-and-features), which prohibit excessive automated bulk activity, unauthorized service reproduction, and placing undue burden on servers through automated means.
|
||||
2. **Account Risk**: There are documented cases of GitHub issuing warning emails to users of similar tools, citing "scripted interactions or otherwise deliberately unusual or strenuous" usage patterns. Continued use after a warning may result in temporary or permanent suspension of Copilot access.
|
||||
3. **No Guarantee**: GitHub may update its detection mechanisms at any time, and usage patterns that work today may be flagged in the future.
|
||||
|
||||
Users enable this feature **at their own risk**. CC Switch is not responsible for any account restrictions, warnings, or service suspensions resulting from the use of this feature.
|
||||
|
||||
---
|
||||
|
||||
## 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 12 (Monterey) or later | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | See table below | x64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| File | Description |
|
||||
| ------------------------------------------ | ---------------------------------------------------- |
|
||||
| `CC-Switch-v3.12.3-Windows.msi` | **Recommended** - MSI installer with auto-update |
|
||||
| `CC-Switch-v3.12.3-Windows-Portable.zip` | Portable version, extract and run, no registry write |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| ---------------------------------- | -------------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.12.3-macOS.dmg` | **Recommended** - DMG installer, drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.12.3-macOS.zip` | ZIP archive, extract and drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.12.3-macOS.tar.gz` | For Homebrew installation and auto-update |
|
||||
|
||||
> macOS builds are code-signed and notarized by Apple for a seamless install experience.
|
||||
|
||||
### 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` |
|
||||
@@ -0,0 +1,313 @@
|
||||
# CC Switch v3.12.3
|
||||
|
||||
> GitHub Copilot リバースプロキシ、macOS コード署名と公証、Reasoning Effort マッピング、Tool Search 環境変数トグル、Skill バックアップ/リストア、OpenCode SQLite バックエンド
|
||||
|
||||
**[中文版 →](v3.12.3-zh.md) | [English →](v3.12.3-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.12.3 は、GitHub Copilot リバースプロキシと Copilot Auth Center を追加し、Copilot トークンを使用した Claude/OpenAI API へのアクセスを実現しました。macOS ビルドに Apple コード署名と公証を導入し、「開発元を確認できません」の警告を解消しました。Reasoning Effort マッピングにより、Claude の thinking budget を OpenAI 互換の reasoning_effort パラメータに自動変換します。Tool Search は従来のバイナリパッチ方式から Claude 2.1.76+ ネイティブの `ENABLE_TOOL_SEARCH` 環境変数トグルに移行し、共通設定エディタから切り替え可能になりました。OpenCode バックエンドを JSON から SQLite に移行し、Skill バックアップ/リストアライフサイクル、プロキシ gzip 圧縮、o シリーズモデル互換性の改善も含まれます。
|
||||
|
||||
**リリース日**: 2026-03-24
|
||||
|
||||
**更新規模**: 36 commits | 107 files changed | +9,124 / -802 lines
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **GitHub Copilot リバースプロキシ**: Copilot トークンを使用して Claude/OpenAI API にアクセスするリバースプロキシを追加。Copilot Auth Center でトークンの取得と管理が可能（[⚠️ リスクに関する注意事項](#️-リスクに関する注意事項)）
|
||||
- **macOS コード署名と公証**: macOS ビルドが Apple のコード署名と公証に対応し、初回起動時の警告なしでインストール可能に。DMG インストーラーを新たに提供
|
||||
- **Reasoning Effort マッピング**: プロキシ層での自動マッピング — 明示的な `output_config.effort` を優先し、`budget_tokens` 閾値（<4000→low, 4000–16000→medium, ≥16000→high）にフォールバック。o シリーズおよび GPT-5+ モデルに対応
|
||||
- **Tool Search 環境変数トグル**: バイナリパッチ方式を廃止し、Claude 2.1.76+ ネイティブの `ENABLE_TOOL_SEARCH` 環境変数による切り替えに移行。共通設定エディタから設定可能
|
||||
- **Skill バックアップ/リストアライフサイクル**: アンインストール前に Skill ファイルを自動バックアップ。バックアップリスト、リストア、削除の管理機能を追加
|
||||
- **OpenCode SQLite バックエンド**: OpenCode に SQLite セッションストレージを追加（既存の JSON バックエンドと併存）。ID 競合時は SQLite を優先するデュアルバックエンドスキャン
|
||||
- **Codex 1M コンテキストウィンドウトグル**: 設定エディタでワンクリックで `model_context_window = 1000000` を設定可能。`model_auto_compact_token_limit` も自動設定
|
||||
- **自動アップグレード無効化トグル**: Claude 共通設定エディタに `DISABLE_AUTOUPDATER` 環境変数のチェックボックスを追加し、Claude Code の自動アップグレードを防止
|
||||
- **プロキシ Gzip 圧縮**: 非ストリーミングプロキシリクエストが gzip 圧縮を自動ネゴシエーションし、帯域幅消費を削減
|
||||
- **o シリーズモデル互換性**: Chat Completions プロキシが o1/o3/o4-mini モデルに `max_completion_tokens` を正しく使用。Responses API は正しい `max_output_tokens` フィールドを維持
|
||||
- **Skills インポートの刷新**: ファイルシステムベースの暗黙的なアプリ推論を明示的な `ImportSkillSelection` に置き換え、複数アプリの誤った有効化を防止
|
||||
- **Ghostty ターミナルサポート**: Ghostty ターミナルでの Claude セッション復元を修正
|
||||
|
||||
---
|
||||
|
||||
## 新機能
|
||||
|
||||
### GitHub Copilot リバースプロキシ
|
||||
|
||||
GitHub Copilot トークンを使用して Claude API および OpenAI API にアクセスするリバースプロキシ機能を追加しました。
|
||||
|
||||
- Copilot のアクセストークンを利用し、Claude Code や Codex などのクライアントからプロキシ経由で API リクエストを転送
|
||||
- Copilot 固有のリクエストフィンガープリントとヘッダー処理に対応
|
||||
- プロバイダープリセットに Copilot 用テンプレートを追加
|
||||
|
||||
### Copilot Auth Center
|
||||
|
||||
Copilot トークンの取得と管理を行う認証センターを追加しました。
|
||||
|
||||
- GitHub デバイスフローによるトークン取得をサポート
|
||||
- トークンの有効期限管理と自動リフレッシュ
|
||||
- フロントエンドから直接トークンステータスの確認と再認証が可能
|
||||
|
||||
### Reasoning Effort マッピング
|
||||
|
||||
OpenAI o シリーズおよび GPT-5+ モデル向けのプロキシ層自動マッピング機能を追加しました。
|
||||
|
||||
- 二段階の解決ロジック：明示的な `output_config.effort` を優先し、thinking `budget_tokens` 閾値（<4000→low, 4000–16000→medium, ≥16000→high）にフォールバック
|
||||
- Chat Completions と Responses API の両パスをカバー、17 個のユニットテスト付き
|
||||
|
||||
### Tool Search 環境変数トグル
|
||||
|
||||
Claude CLI Tool Search の有効化/無効化を環境変数で制御する設定を追加しました。
|
||||
|
||||
- Claude 2.1.76+ で導入されたネイティブの `ENABLE_TOOL_SEARCH` 環境変数を使用
|
||||
- 共通設定（Common Config）エディタから直接トグル可能
|
||||
- 従来のバイナリパッチ方式は不要になり、CLI アップデート時の再適用も不要
|
||||
|
||||
### Skill アンインストール時の自動バックアップ
|
||||
|
||||
アンインストール前に Skill ファイルを自動バックアップし、意図しないデータ損失を防止します。
|
||||
|
||||
- バックアップは `~/.cc-switch/skill-backups/` に保存され、すべての skill ファイルと元のメタデータを含む `meta.json` が含まれます
|
||||
- 古いバックアップは自動的にプルーニングされ、最大 20 個を保持
|
||||
- バックアップパスはフロントエンドに返され、成功トーストに表示
|
||||
|
||||
### Skill バックアップのリストアと削除
|
||||
|
||||
アンインストール時に作成された Skill バックアップの管理コマンドを追加しました。
|
||||
|
||||
- すべての利用可能な skill バックアップをメタデータ付きで一覧表示
|
||||
- リストアはファイルを SSOT にコピーし、DB レコードを保存し、現在のアプリに同期。失敗時は自動ロールバック
|
||||
- 削除は確認ダイアログの後にバックアップディレクトリを削除
|
||||
- ConfirmDialog にネストされたダイアログスタッキングをサポートする設定可能な zIndex プロパティを追加
|
||||
|
||||
### OpenCode SQLite バックエンド
|
||||
|
||||
OpenCode に SQLite セッションストレージサポートを追加しました（既存の JSON バックエンドと併存）。
|
||||
|
||||
- デュアルバックエンドスキャン、ID 競合時は SQLite を優先
|
||||
- アトミックなセッション削除とパス検証
|
||||
- JSON バックエンドは後方互換性のため引き続き機能
|
||||
|
||||
### Codex 1M コンテキストウィンドウトグル
|
||||
|
||||
設定エディタに Codex 1M コンテキストウィンドウのワンクリックトグルを追加しました。
|
||||
|
||||
- チェックボックスで `config.toml` に `model_context_window = 1000000` を設定
|
||||
- 有効化時に `model_auto_compact_token_limit = 900000` を自動設定
|
||||
- 無効化時は両フィールドをクリーンに削除
|
||||
|
||||
### 自動アップグレード無効化トグル
|
||||
|
||||
Claude 共通設定エディタに自動アップグレードを無効化するチェックボックスを追加しました。
|
||||
|
||||
- 有効化時に `DISABLE_AUTOUPDATER=1` 環境変数を設定し、Claude Code の自動アップグレードを防止
|
||||
- Teammates モード、Tool Search、高強度思考トグルと同じ行に表示
|
||||
|
||||
### macOS コード署名と公証
|
||||
|
||||
macOS ビルドに Apple のコード署名と公証を導入しました。
|
||||
|
||||
- Apple Developer ID による署名と Apple 公証サービスによる公証を実施
|
||||
- 初回起動時の「開発元を確認できません」警告が不要に
|
||||
- DMG インストーラーを新たに提供し、ドラッグ＆ドロップでのインストールに対応
|
||||
- CI/CD パイプラインに署名・公証ステップを統合
|
||||
|
||||
---
|
||||
|
||||
## 変更
|
||||
|
||||
### Skills キャッシュ戦略の最適化
|
||||
|
||||
Skills のキャッシュ戦略を最適化し、パフォーマンスと信頼性を向上しました。
|
||||
|
||||
- キャッシュの有効期限管理とインバリデーション戦略を改善
|
||||
- 不要なキャッシュ再構築を削減し、起動時間を短縮
|
||||
|
||||
### Claude 4.6 コンテキストウィンドウ更新
|
||||
|
||||
Claude 4.6 モデルのコンテキストウィンドウサイズを更新しました。
|
||||
|
||||
- Claude 4.6 の最新コンテキストウィンドウサイズをプリセットに反映
|
||||
|
||||
### MiniMax M2.7 アップグレード
|
||||
|
||||
MiniMax モデルプリセットを M2.7 にアップグレードしました。
|
||||
|
||||
- MiniMax プロバイダープリセットのモデル ID とパラメータを M2.7 に更新
|
||||
|
||||
### Xiaomi MiMo アップグレード
|
||||
|
||||
Xiaomi MiMo モデルプリセットをアップグレードしました。
|
||||
|
||||
- MiMo プロバイダープリセットのモデル ID とパラメータを最新版に更新
|
||||
|
||||
### AddProviderDialog の簡素化
|
||||
|
||||
- 冗長な OAuth タブを削除し、ダイアログを 3 タブから 2 タブ（アプリ固有 + ユニバーサル）に簡素化
|
||||
|
||||
### プロバイダーフォームの高度なオプション折りたたみ
|
||||
|
||||
- Claude プロバイダーフォームのモデルマッピング、API フォーマットなどの高度なフィールドが未入力時にデフォルトで折りたたまれるように変更
|
||||
- プリセットが値を入力すると自動展開。手動クリア時は自動折りたたみしない
|
||||
|
||||
### プロキシ Gzip 圧縮
|
||||
|
||||
非ストリーミングプロキシリクエストが gzip 圧縮をサポートし、帯域幅消費を削減しました。
|
||||
|
||||
- 非ストリーミングリクエストは reqwest が gzip を自動ネゴシエーションし、レスポンスを透過的に解凍
|
||||
- ストリーミングリクエストは中断された SSE ストリームの解凍エラーを避けるため、保守的に `Accept-Encoding: identity` を維持
|
||||
|
||||
### o1/o3 モデル互換性
|
||||
|
||||
プロキシ転送が OpenAI o シリーズモデルのトークンパラメータを正しく処理するようになりました。
|
||||
|
||||
- Chat Completions パスが o1/o3/o4-mini モデルに `max_tokens` の代わりに `max_completion_tokens` を使用 (#1451、@Hemilt0n に感謝)
|
||||
- Responses API パスが正しい `max_output_tokens` フィールドを維持し、`max_completion_tokens` の誤った注入を防止
|
||||
|
||||
### OpenCode モデルバリアント
|
||||
|
||||
- OpenCode のモデルバリアントを options 内部ではなくプリセットのトップレベルに配置し、発見しやすさを向上 (#1317)
|
||||
|
||||
### Skills インポートフロー
|
||||
|
||||
Skills インポートフローが正確性とクリーンアップのためにリワークされました。
|
||||
|
||||
- ファイルシステムベースの暗黙的なアプリ推論を明示的な `ImportSkillSelection` に置き換え、同じ skill ディレクトリが複数アプリパスに存在する場合の複数アプリ誤有効化を防止
|
||||
- `sync_to_app` に調整ロジックを追加し、無効化/孤立したシンボリックリンクを削除
|
||||
- MCP `sync_all_enabled` がライブ設定から無効化されたサーバーを削除するように改善
|
||||
- スキーママイグレーションがレガシーアプリマッピングのスナップショットを保持し、損失のある再構築を回避
|
||||
|
||||
---
|
||||
|
||||
## バグ修正
|
||||
|
||||
### WebDAV パスワードの消失
|
||||
|
||||
- 無関係な設定保存時に WebDAV パスワードがサイレントにクリアされる問題を修正
|
||||
|
||||
### ツールメッセージのパース
|
||||
|
||||
- プロキシのツールメッセージパース処理の不具合を修正し、特定のツール呼び出しパターンでのエラーを解消
|
||||
|
||||
### ダークモードの表示
|
||||
|
||||
- ダークモードでの一部 UI コンポーネントの表示不具合を修正
|
||||
|
||||
### Copilot リクエストフィンガープリント
|
||||
|
||||
- Copilot リバースプロキシのリクエストフィンガープリント生成の不具合を修正し、認証エラーを解消
|
||||
|
||||
### プロバイダーフォームの二重送信
|
||||
|
||||
- プロバイダー追加/編集フォームでの高速連続クリックによる重複送信を防止 (#1352、@Hexi1997 に感謝)
|
||||
|
||||
### Ghostty ターミナルセッション復元
|
||||
|
||||
- Ghostty ターミナルでの Claude セッション復元の失敗を修正 (#1506、@canyonsehun に感謝)
|
||||
|
||||
### Skill ZIP インポート拡張子
|
||||
|
||||
- ZIP インポートダイアログが `.skill` ファイル拡張子をサポートするように修正 (#1240, #1455、@yovinchen に感謝)
|
||||
|
||||
### Skill ZIP インストール対象アプリ
|
||||
|
||||
- ZIP 方式でインストールされた skill が常に Claude をデフォルトにするのではなく、現在アクティブなアプリを使用するように修正
|
||||
|
||||
### OpenClaw アクティブカードのハイライト
|
||||
|
||||
- OpenClaw の現在アクティブなプロバイダーカードがハイライト表示されない問題を修正 (#1419、@funnytime75 に感謝)
|
||||
|
||||
### TOC 付きレスポンシブレイアウト
|
||||
|
||||
- TOC タイトルが存在する場合のレスポンシブデザインを改善 (#1491、@West-Pavilion に感謝)
|
||||
|
||||
### Skills インポートダイアログの白い画面
|
||||
|
||||
- ImportSkillsDialog に不足していた TooltipProvider を追加し、ダイアログを開く際のランタイムクラッシュを防止
|
||||
|
||||
### パネル下部の空白エリア
|
||||
|
||||
- すべてのコンテンツパネルのハードコードされた `h-[calc(100vh-8rem)]` を `flex-1 min-h-0` に置き換え、異なるプラットフォーム間のオフセット値の不一致による下部のギャップを解消
|
||||
|
||||
---
|
||||
|
||||
## ドキュメント
|
||||
|
||||
### 料金モデル ID の正規化
|
||||
|
||||
- 中英日三言語のユーザーマニュアルにモデル ID 正規化ルール（プレフィックス除去、サフィックストリミング、`@`→`-` 置換）の説明セクションを追加 (#1591、@makoMakoGo に感謝)
|
||||
|
||||
### macOS 署名済みメッセージの更新
|
||||
|
||||
- README、README_ZH、インストールガイド（EN/ZH/JA）、FAQ ページ（EN/ZH/JA）からすべての `xattr` 回避策と「開発元を確認できません」警告を削除し、「Apple のコード署名と公証済み」メッセージに置換
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ リスクに関する注意事項
|
||||
|
||||
**GitHub Copilot リバースプロキシに関する免責事項**
|
||||
|
||||
本リリースで追加された Copilot リバースプロキシ機能は、リバースエンジニアリングによる非公式 API を通じて GitHub Copilot サービスにアクセスします。この機能を有効にする前に、以下のリスクをご確認ください：
|
||||
|
||||
1. **利用規約違反の可能性**：この機能は [GitHub 利用規約](https://docs.github.com/en/site-policy/acceptable-use-policies/github-acceptable-use-policies)および[追加製品の利用条件](https://docs.github.com/en/site-policy/github-terms/github-terms-for-additional-products-and-features)に違反する可能性があります。これらの規約では、過度な自動一括操作、サービスの無断複製、自動化手段によるサーバーへの過度な負荷が禁止されています。
|
||||
2. **アカウントリスク**：類似ツールの利用者が GitHub から「スクリプト化されたインタラクション、または意図的に異常もしくは過度な使用」を指摘する警告メールを受け取った事例が報告されています。警告後も使用を継続した場合、Copilot へのアクセスが一時的または永久的に停止される可能性があります。
|
||||
3. **将来の利用保証なし**：GitHub は検出メカニズムをいつでも更新する可能性があり、現在利用可能な使用パターンが将来的にフラグ付けされる可能性があります。
|
||||
|
||||
この機能を有効にすることで、ユーザーは**すべてのリスクを自己責任で負う**ものとします。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.12.3-Windows.msi` | **推奨** - MSI インストーラー、自動更新対応 |
|
||||
| `CC-Switch-v3.12.3-Windows-Portable.zip` | ポータブル版、解凍して実行、レジストリ書き込みなし |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| ---------------------------------- | ----------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.12.3-macOS.dmg` | **推奨** - DMG インストーラー、ドラッグ＆ドロップでインストール |
|
||||
| `CC-Switch-v3.12.3-macOS.zip` | 解凍して Applications にドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.12.3-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` |
|
||||
@@ -0,0 +1,296 @@
|
||||
# CC Switch v3.12.3
|
||||
|
||||
> GitHub Copilot 反向代理、macOS 代码签名与公证、Reasoning Effort 映射、Tool Search 环境变量开关、Skill 备份/恢复生命周期
|
||||
|
||||
**[English →](v3.12.3-en.md) | [日本語版 →](v3.12.3-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.12.3 新增了 **GitHub Copilot 反向代理** 支持和 **Copilot Auth Center** 认证管理，引入了 **Reasoning Effort 映射** 实现跨供应商推理强度控制，通过 Claude 2.1.76+ 原生 `ENABLE_TOOL_SEARCH` 环境变量实现了 **Tool Search 开关**，新增了 **OpenCode SQLite 后端** 支持，并完成了 **macOS 代码签名与 Apple 公证**。同时引入了完整的 Skill 备份/恢复生命周期，改进了代理对 OpenAI o 系列模型的兼容性和 gzip 压缩支持，优化了 Skills 缓存策略，更新了 Claude 4.6 上下文窗口、MiniMax M2.7 和小米 MiMo 模型预设，并修复了 WebDAV 密码、工具消息解析、暗色模式和 Copilot 请求指纹等方面的问题。
|
||||
|
||||
**发布日期**：2026-03-24
|
||||
|
||||
**更新规模**：36 commits | 107 files changed | +9,124 / -802 lines
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- **GitHub Copilot 反向代理**：新增 Copilot 反向代理支持，通过 Copilot Auth Center 管理 GitHub Token 认证，实现 Copilot 模型在 Claude Code 中的无缝使用（[⚠️ 风险提示](#️-风险提示)）
|
||||
- **macOS 代码签名与公证**：macOS 版本已通过 Apple 代码签名和公证，新增 DMG 安装格式，无需再手动绕过"未知开发者"警告
|
||||
- **Reasoning Effort 映射**：代理层自动映射 — 显式 `output_config.effort` 优先，回退到 `budget_tokens` 阈值（<4000→low, 4000–16000→medium, ≥16000→high），支持 o 系列和 GPT-5+ 模型
|
||||
- **Tool Search 环境变量开关**：利用 Claude 2.1.76+ 原生 `ENABLE_TOOL_SEARCH` 环境变量，在通用配置编辑器中一键启用 Tool Search
|
||||
- **Skill 备份/恢复生命周期**：卸载前自动备份 Skill 文件；新增备份列表、恢复和删除管理
|
||||
- **OpenCode SQLite 后端**：为 OpenCode 新增 SQLite 会话存储（与现有 JSON 后端并存），ID 冲突时 SQLite 优先的双后端扫描
|
||||
- **Codex 1M 上下文窗口开关**：配置编辑器中一键设置 `model_context_window = 1000000`，自动填充 `model_auto_compact_token_limit`
|
||||
- **禁用自动升级开关**：通用配置编辑器中新增 `DISABLE_AUTOUPDATER` 环境变量复选框，防止 Claude Code 自动升级
|
||||
- **代理 Gzip 压缩**：非流式代理请求自动协商 gzip 压缩，减少带宽消耗
|
||||
- **o 系列模型兼容性**：Chat Completions 代理正确使用 `max_completion_tokens` 处理 o1/o3/o4-mini 模型
|
||||
- **Skills 导入重构**：将基于文件系统的隐式应用推断替换为显式的 `ImportSkillSelection`，防止多应用错误激活
|
||||
|
||||
---
|
||||
|
||||
## 新功能
|
||||
|
||||
### GitHub Copilot 反向代理
|
||||
|
||||
新增完整的 GitHub Copilot 集成，作为 Claude Code 供应商使用。
|
||||
|
||||
- 通过 OAuth Device Code 流程进行 GitHub 认证
|
||||
- 支持多账号管理和自动 Token 刷新
|
||||
- Anthropic ↔ OpenAI 格式自动转换
|
||||
- 实时获取可用模型列表和用量统计 (#930，感谢 @Mason-mengze)
|
||||
|
||||
### Copilot Auth Center
|
||||
|
||||
在设置中新增认证中心面板，全局管理 GitHub 账号。
|
||||
|
||||
- 支持按供应商绑定账号（通过 `meta.authBinding`）
|
||||
- 统一的 Token 管理和刷新机制
|
||||
|
||||
### Tool Search 开关
|
||||
|
||||
利用 Claude 2.1.76+ 原生 `ENABLE_TOOL_SEARCH` 环境变量控制 Tool Search 功能。
|
||||
|
||||
- 在供应商通用配置编辑器中以复选框形式暴露
|
||||
- 替代了之前的二进制补丁方案，更简洁可靠 (#930，感谢 @Mason-mengze)
|
||||
|
||||
### Reasoning Effort 映射
|
||||
|
||||
新增代理层自动推理强度映射，支持 OpenAI o 系列和 GPT-5+ 模型。
|
||||
|
||||
- 两级解析：显式 `output_config.effort` 优先，回退到 `budget_tokens` 阈值（<4000→low, 4000–16000→medium, ≥16000→high）
|
||||
- 覆盖 Chat Completions 和 Responses API 两条路径，含 17 个单元测试
|
||||
|
||||
### OpenCode SQLite 后端
|
||||
|
||||
为 OpenCode 新增 SQLite 会话存储支持（与现有 JSON 后端并存）。
|
||||
|
||||
- 双后端扫描，ID 冲突时 SQLite 优先
|
||||
- 原子会话删除和路径校验
|
||||
- JSON 后端保持向后兼容
|
||||
|
||||
### Codex 1M 上下文窗口开关
|
||||
|
||||
在配置编辑器中新增 Codex 1M 上下文窗口一键开关。
|
||||
|
||||
- 复选框设置 `config.toml` 中的 `model_context_window = 1000000`
|
||||
- 启用时自动填充 `model_auto_compact_token_limit = 900000`
|
||||
- 关闭时干净移除两个字段
|
||||
|
||||
### 禁用自动升级开关
|
||||
|
||||
在 Claude 通用配置编辑器中新增禁用自动升级的复选框。
|
||||
|
||||
- 勾选后设置 `DISABLE_AUTOUPDATER=1` 环境变量，阻止 Claude Code 自动升级
|
||||
- 与 Teammates 模式、Tool Search、高强度思考等开关同一排显示
|
||||
|
||||
### Skill 卸载自动备份
|
||||
|
||||
卸载 Skill 前自动备份文件，防止数据意外丢失。
|
||||
|
||||
- 备份存储在 `~/.cc-switch/skill-backups/`，包含所有 skill 文件和记录原始元数据的 `meta.json`
|
||||
- 旧备份自动清理，最多保留 20 个
|
||||
- 备份路径返回前端并在成功提示中显示
|
||||
|
||||
### Skill 备份恢复与删除
|
||||
|
||||
新增卸载时创建的 Skill 备份的管理功能。
|
||||
|
||||
- 列出所有可用的 skill 备份及元数据
|
||||
- 恢复操作将文件拷回 SSOT，保存数据库记录，并同步到当前应用，失败时自动回滚
|
||||
- 删除操作在确认对话框后移除备份目录
|
||||
|
||||
### macOS 代码签名与 Apple 公证
|
||||
|
||||
CI 流程新增完整的 macOS 代码签名和 Apple 公证支持。
|
||||
|
||||
- 导入 Apple Developer ID 证书，签名 Universal Binary
|
||||
- 提交 Apple 公证并将票据装订到 `.app` 和 `.dmg`
|
||||
- 硬性验证步骤（`codesign --verify` + `spctl -a` + `stapler validate`）把关发布
|
||||
|
||||
---
|
||||
|
||||
## 变更
|
||||
|
||||
### Skills 缓存策略优化
|
||||
|
||||
- 将 `invalidateQueries` 替换为直接 `setQueryData` 更新，用于 skill 安装/卸载/导入操作
|
||||
- 新增 `staleTime: Infinity` 和 `keepPreviousData`，消除加载闪烁 (#1573，感谢 @TangZhiZzz)
|
||||
|
||||
### 代理 Gzip 压缩
|
||||
|
||||
- 非流式请求允许 reqwest 自动协商 gzip 并透明解压响应
|
||||
- 流式请求保守地保持 `Accept-Encoding: identity`，避免中断的 SSE 流解压出错
|
||||
|
||||
### o1/o3 模型兼容性
|
||||
|
||||
- Chat Completions 路径对 o1/o3/o4-mini 模型使用 `max_completion_tokens` 替代 `max_tokens` (#1451，感谢 @Hemilt0n)
|
||||
- Responses API 路径保持使用正确的 `max_output_tokens` 字段
|
||||
|
||||
### OpenCode 模型变体
|
||||
|
||||
- 将 OpenCode 的模型变体放在预设顶层而非嵌套在 options 内部，提升可发现性 (#1317)
|
||||
|
||||
### Skills 导入流程
|
||||
|
||||
- 将基于文件系统的隐式应用推断替换为显式的 `ImportSkillSelection`，防止同一 skill 目录存在于多个应用路径下时错误激活多个应用
|
||||
- 为 `sync_to_app` 增加协调逻辑，移除已禁用/孤立的符号链接
|
||||
- MCP `sync_all_enabled` 现在会从 live 配置中移除已禁用的服务器
|
||||
|
||||
### Claude 4.6 上下文窗口
|
||||
|
||||
- Claude Opus 4.6 和 Sonnet 4.6 上下文窗口从 200K 更新至 1M（GA 发布）
|
||||
|
||||
### MiniMax 模型升级
|
||||
|
||||
- MiniMax 预设从 M2.5 升级至 M2.7，更新三语合作伙伴描述
|
||||
|
||||
### 小米 MiMo 模型升级
|
||||
|
||||
- MiMo 预设从 mimo-v2-flash 升级至 mimo-v2-pro
|
||||
|
||||
### 添加供应商对话框简化
|
||||
|
||||
- 移除冗余的 OAuth 标签页，对话框从 3 个标签页减少到 2 个（应用专属 + 通用）
|
||||
|
||||
### 供应商表单高级选项折叠
|
||||
|
||||
- Claude 供应商表单中的模型映射、API 格式等高级字段在未填写时默认折叠
|
||||
- 预设填充值后自动展开，手动清空不会自动折叠
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### WebDAV 密码被静默清除
|
||||
|
||||
- 修复 ProviderList 或 UsageScriptModal 保存设置时 WebDAV 密码被静默清除的问题
|
||||
- 前端 payload 中剥离 `webdavSync`，后端 `merge_settings_for_save()` 增加回填逻辑保护现有密码
|
||||
|
||||
### 工具消息解析
|
||||
|
||||
- 修复 Claude（tool_result content blocks）、Codex（function_call/function_call_output payloads）和 Gemini（array content + toolCalls extraction）的 tool_use/tool_result 消息分类 (#1401，感谢 @BlueOcean223)
|
||||
|
||||
### 暗色模式选择器
|
||||
|
||||
- 将 Tailwind `darkMode` 从 `["selector", "class"]` 改为 `["selector", ".dark"]`，确保暗色模式正确激活 (#1596，感谢 @qinxiandiqi)
|
||||
|
||||
### Copilot 请求指纹
|
||||
|
||||
- 统一所有 Copilot API 调用点的请求指纹头，防止 User-Agent 泄漏和 Stream Check 不匹配
|
||||
|
||||
### 供应商表单防重复提交
|
||||
|
||||
- 修复快速连续点击按钮时供应商添加/编辑表单重复提交的问题 (#1352，感谢 @Hexi1997)
|
||||
|
||||
### Ghostty 终端会话恢复
|
||||
|
||||
- 修复在 Ghostty 终端中恢复 Claude 会话失败的问题 (#1506，感谢 @canyonsehun)
|
||||
|
||||
### Skill ZIP 导入扩展名
|
||||
|
||||
- ZIP 导入对话框现在支持 `.skill` 文件扩展名 (#1240, #1455，感谢 @yovinchen)
|
||||
|
||||
### Skill ZIP 安装目标应用
|
||||
|
||||
- ZIP 方式安装的 skill 现在使用当前活跃应用，而非始终默认为 Claude
|
||||
|
||||
### OpenClaw 活跃供应商高亮
|
||||
|
||||
- 修复 OpenClaw 当前激活的供应商卡片未高亮显示的问题 (#1419，感谢 @funnytime75)
|
||||
|
||||
### 响应式布局与 TOC
|
||||
|
||||
- 改善存在 TOC 标题时的响应式布局 (#1491，感谢 @West-Pavilion)
|
||||
|
||||
### Skills 导入对话框白屏
|
||||
|
||||
- 在 ImportSkillsDialog 中补充缺失的 TooltipProvider，修复打开对话框时的运行时崩溃
|
||||
|
||||
### 面板底部空白区域
|
||||
|
||||
- 将所有内容面板的硬编码 `h-[calc(100vh-8rem)]` 替换为 `flex-1 min-h-0`，消除因不同平台偏移量不匹配导致的底部空白
|
||||
|
||||
---
|
||||
|
||||
## 文档
|
||||
|
||||
### 定价模型 ID 归一化
|
||||
|
||||
- 在中英日三语用户手册中新增模型 ID 归一化规则说明（前缀剥离、后缀修剪、`@`→`-` 替换）(#1591，感谢 @makoMakoGo)
|
||||
|
||||
### macOS 签名与公证说明
|
||||
|
||||
- 移除 README、安装指南和 FAQ 中所有 `xattr` 变通方案和"未知开发者"警告
|
||||
- 替换为"已通过 Apple 代码签名和公证"的说明
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 风险提示
|
||||
|
||||
**GitHub Copilot 反向代理免责声明**
|
||||
|
||||
本版本新增的 Copilot 反向代理功能通过逆向工程的非官方 API 访问 GitHub Copilot 服务。启用此功能前，请注意以下风险：
|
||||
|
||||
1. **违反服务条款**：此功能可能违反 [GitHub 可接受使用政策](https://docs.github.com/en/site-policy/acceptable-use-policies/github-acceptable-use-policies)和[附加产品条款](https://docs.github.com/en/site-policy/github-terms/github-terms-for-additional-products-and-features)，其中禁止过度自动化批量活动、未经授权的服务复制以及通过自动化手段对服务器施加不当负担。
|
||||
2. **账号风险**：已有类似工具的用户收到 GitHub 官方警告邮件，指出其存在"脚本化交互或其他刻意的异常或高强度使用"行为。收到警告后继续使用可能导致 Copilot 访问权限被暂停甚至永久封禁。
|
||||
3. **无法保证长期可用**：GitHub 可能随时更新其检测机制，当前可用的使用方式未来可能被标记。
|
||||
|
||||
用户启用此功能即表示**自行承担所有风险**。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.12.3-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.12.3-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| ---------------------------------- | --------------------------------------------------------- |
|
||||
| `CC-Switch-v3.12.3-macOS.dmg` | **推荐** - DMG 安装包，拖入 Applications 即可 |
|
||||
| `CC-Switch-v3.12.3-macOS.zip` | 解压后拖入 Applications，Universal Binary |
|
||||
| `CC-Switch-v3.12.3-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` |
|
||||
@@ -0,0 +1,433 @@
|
||||
# CC Switch v3.13.0
|
||||
|
||||
> Lightweight Mode, Quota & Balance Visibility, Provider Model Auto-Fetch, Codex OAuth Reverse Proxy, and Tray Per-App Submenus
|
||||
|
||||
**[中文版 →](v3.13.0-zh.md) | [日本語版 →](v3.13.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.13.0 is a major feature release centered on observability, provider workflow ergonomics, and proxy compatibility. It adds inline **quota and balance displays** across official Claude / Codex / Gemini providers plus Token Plan, Copilot, and third-party balance APIs; introduces a **Lightweight Mode** that keeps CC Switch running from the system tray without a main window; delivers **automatic model discovery** via OpenAI-compatible `/v1/models` across all five supported applications; ships a **Codex OAuth reverse proxy** for ChatGPT subscribers; reorganizes the tray menu into **per-app submenus**; rebuilds the proxy forwarding stack on a **Hyper-based client**; and overhauls the **Skills workflow** with discovery, batch updates, storage-location toggling, and built-in skills.sh search and install. Additional improvements include full URL endpoint mode, enhanced token usage tracking, the Copilot interaction optimizer, a UTF-8 streaming chunk boundary fix for multi-byte output, a Linux startup UI responsiveness fix, and a friendlier new-user onboarding experience.
|
||||
|
||||
**Release Date**: 2026-04-10
|
||||
|
||||
**Update Scale**: 139 commits | 280 files changed | +31,627 / -3,042 lines
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- **Lightweight Mode**: Tray-only operating mode that destroys the main window on exit to tray and recreates it on demand, reducing CC Switch's desktop footprint to near zero when idle
|
||||
- **Quota & Balance Visibility**: Inline quota or balance readout across provider cards — official Claude / Codex / Gemini subscriptions, GitHub Copilot premium interactions, Codex OAuth, Token Plan providers (Kimi / Zhipu GLM / MiniMax), plus official balance queries for DeepSeek, StepFun, SiliconFlow, OpenRouter, and Novita AI
|
||||
- **Provider Model Auto-Fetch**: OpenAI-compatible `/v1/models` discovery across Claude, Codex, Gemini, OpenCode, and OpenClaw provider forms, with grouped dropdown selection and failure-specific error messages
|
||||
- **Codex OAuth Reverse Proxy**: ChatGPT Codex reverse proxy exposed as a new Claude provider card type, allowing users to use their ChatGPT subscription in Claude Code. Includes managed OAuth login and inline subscription quota display ([⚠️ Risk Notice](#️-risk-notice))
|
||||
- **Tray Per-App Submenus**: Reworked the tray menu into per-application submenus so it never overflows the screen and background provider switching scales to dozens of providers per app
|
||||
- **Skills Discovery & Batch Updates**: SHA-256-based skill update detection, per-skill and "Update All" batch actions, `skills.sh` search integration, and a storage-location toggle between CC Switch storage and `~/.agents/skills`
|
||||
- **Session Workflow Upgrades**: Batch session deletion, a directory picker before launching Claude terminal restore, usage import from Claude / Codex / Gemini session logs without proxy interception, precise Codex JSONL parsing, and per-app usage filtering
|
||||
- **OpenCode / OpenClaw Stream Check Coverage**: OpenCode detection via npm package mapping, OpenClaw `openai-completions` support, and the remaining OpenClaw protocol variants — with custom-header passthrough and auth-header detection fixes
|
||||
- **Full URL Endpoint Mode**: Provider option that treats `base_url` as a complete upstream endpoint, unblocking vendors that require nonstandard URL layouts
|
||||
- **Hyper-based Proxy Forwarding Stack**: Refactored proxy forwarding onto a Hyper-based client with transparent header forwarding, improved endpoint rewriting, and better support for dynamic upstream endpoints
|
||||
- **Copilot Interaction Optimizer**: Request classification and routing logic that reduces unnecessary GitHub Copilot premium interaction consumption
|
||||
- **UTF-8 Stream Chunk Boundary Fix**: All four SSE streaming paths now preserve incomplete multi-byte UTF-8 sequences across TCP chunks, eliminating intermittent U+FFFD garbled output via the Copilot reverse proxy
|
||||
- **Linux Startup UI Fix**: Fixed the long-standing issue where the window UI couldn't receive clicks on Linux until the user manually maximized and restored the window
|
||||
- **First-Run Onboarding**: One-time welcome dialog on fresh installs, automatic seeding of Claude / OpenAI / Google official presets, and auto-import of OpenCode / OpenClaw live configurations on startup
|
||||
- **Claude Session Titles & Search Highlighting**: Meaningful title extraction for Claude sessions using a priority chain (custom-title metadata → first user message → directory basename), plus keyword highlighting in Session Manager search results
|
||||
- **URL-Based Provider Icons**: Dual rendering mode supporting Vite URL imports for large SVGs and raster images (PNG, JPG, WebP), keeping small SVGs inlined
|
||||
- **New Provider Presets**: TheRouter, DDSHub, LionCCAPI, Shengsuanyun (胜算云), PIPELLM, and E-FlowCode across supported applications
|
||||
|
||||
---
|
||||
|
||||
## New Features
|
||||
|
||||
### Lightweight Mode
|
||||
|
||||
A tray-only operating mode that dramatically reduces CC Switch's desktop footprint when idle.
|
||||
|
||||
- Destroys the main window on exit-to-tray instead of hiding it, freeing UI resources and memory
|
||||
- Recreates the window on demand when the user reopens CC Switch from the tray, a deeplink, or single-instance activation
|
||||
- Integrated into every window-re-show path: normal startup, deeplink, single_instance, tray `show_main`, and the lightweight-exit round-trip
|
||||
|
||||
### Quota & Balance Visibility
|
||||
|
||||
Added inline quota and balance readouts to provider cards so users can see remaining capacity without leaving the card.
|
||||
|
||||
- **Official subscriptions**: Inline quota display for Claude, Codex, and Gemini official providers
|
||||
- **GitHub Copilot**: Premium interactions quota display on the Copilot provider card
|
||||
- **Codex OAuth**: ChatGPT subscription quota inline with the Codex OAuth provider card
|
||||
- **Token Plan providers**: Kimi, Zhipu GLM, and MiniMax usage progression display (requires manual activation to avoid confusion)
|
||||
- **Third-party balances**: Official balance queries for DeepSeek, StepFun, SiliconFlow, OpenRouter, and Novita AI (requires manual activation to avoid confusion)
|
||||
- Health-check and usage-config buttons are hidden for official providers to keep the card clean
|
||||
|
||||
### Provider Model Auto-Fetch
|
||||
|
||||
Added OpenAI-compatible model discovery to every provider form, removing the manual copy-paste loop for model IDs.
|
||||
|
||||
- Queries the configured provider endpoint's `/v1/models`
|
||||
- Groups models in the dropdown by category for easier selection
|
||||
- Failure-specific error messages distinguish network / authentication / endpoint issues
|
||||
- Supported across all five applications: Claude, Codex, Gemini, OpenCode, and OpenClaw
|
||||
|
||||
### Codex OAuth Reverse Proxy
|
||||
|
||||
Added a reverse proxy path for ChatGPT subscribers who want to use their ChatGPT subscription in Claude Code.
|
||||
|
||||
- Managed OAuth login flow with ChatGPT authentication
|
||||
- Surfaces as a new Claude provider card type alongside API-key providers
|
||||
- Inline subscription quota display
|
||||
- Integrated into the Auth Center for unified token management
|
||||
- See the [⚠️ Risk Notice](#️-risk-notice) below before enabling
|
||||
|
||||
### Tray Per-App Submenus
|
||||
|
||||
Reorganized the tray menu so providers are grouped under each application instead of living in a flat list.
|
||||
|
||||
- Per-application submenus for Claude, Codex, Gemini, OpenCode, and OpenClaw
|
||||
- Prevents the tray menu from overflowing the screen when users have many providers
|
||||
- Background provider switching scales cleanly to long provider lists
|
||||
|
||||
### Skills Discovery & Batch Updates
|
||||
|
||||
Upgraded the Skills management panel into a complete discovery plus maintenance workflow.
|
||||
|
||||
- **SHA-256 update detection**: Skills are content-hashed so the UI knows exactly which ones have upstream changes
|
||||
- **Per-skill and batch updates**: Individual "Update" buttons plus an animated "Update All" batch action
|
||||
- **Storage-location toggle**: Switch between CC Switch storage and `~/.agents/skills` without losing skill state
|
||||
- **Public registry search**: `skills.sh` search integrated directly into the dialog for discovering community skills
|
||||
|
||||
### Session Workflow Upgrades
|
||||
|
||||
Multiple session management improvements that reduce friction when working with Claude / Codex / Gemini sessions.
|
||||
|
||||
- **Batch session deletion**: Select and delete multiple sessions at once from Session Manager (#1693, thanks @Alexlangl)
|
||||
- **Directory picker before restore**: Claude terminal restore now prompts for the working directory up front (#1752, thanks @yovinchen)
|
||||
- **Usage from session logs without proxy**: Usage data imported directly from Claude / Codex / Gemini session logs — no proxy interception required
|
||||
- **Precise Codex JSONL parsing**: Replaced estimated Codex usage with precise JSONL session-log parsing plus Codex model name normalization for consistent pricing lookup
|
||||
- **Gemini CLI session log integration**: Gemini usage now syncs accurately from Gemini CLI session logs
|
||||
- **Per-app usage filtering**: Filter the usage dashboard by Claude, Codex, or Gemini independently
|
||||
|
||||
### OpenCode / OpenClaw Stream Check Coverage
|
||||
|
||||
Extended the Stream Check panel to cover the full OpenCode and OpenClaw surface area.
|
||||
|
||||
- OpenCode detection via npm package mapping
|
||||
- Support for the OpenClaw `openai-completions` protocol
|
||||
- Support for the remaining three OpenClaw protocol variants
|
||||
- Edge-case handling for custom-header passthrough, OpenClaw custom auth-header detection, Bedrock error messaging, and OpenCode default `baseURL` fallback
|
||||
|
||||
### Full URL Endpoint Mode
|
||||
|
||||
Added a provider option that treats `base_url` as a complete upstream endpoint instead of a base URL with path appending (#1561, thanks @yovinchen).
|
||||
|
||||
- Proxy forwarding and Stream Check both honor the full-URL mode
|
||||
- Unblocks vendors that require nonstandard URL layouts
|
||||
- Configurable per-provider on the provider form
|
||||
|
||||
### OpenCode StepFun Step Plan Preset
|
||||
|
||||
- Added a StepFun Step Plan provider preset for OpenCode with sensible defaults (#1668, thanks @sky-wang-salvation)
|
||||
|
||||
### Copilot Interaction Optimizer
|
||||
|
||||
Added request classification and routing logic that reduces unnecessary GitHub Copilot premium interaction consumption.
|
||||
|
||||
- Classifies incoming requests by intent and weight
|
||||
- Routes low-value requests away from premium interaction consumption paths
|
||||
- Designed to extend the usable lifetime of a Copilot subscription
|
||||
- Note: Even with optimized consumption, using the Copilot API outside of Copilot still consumes more than using it within Copilot.
|
||||
|
||||
### First-Run Welcome Dialog
|
||||
|
||||
Added a one-time welcome dialog on fresh installs to guide new users through the CC Switch workflow.
|
||||
|
||||
- Explains how existing live configuration is preserved as a default provider
|
||||
- Introduces the bundled official preset that enables one-click revert to official endpoints
|
||||
- Upgrade users are automatically excluded via empty provider check
|
||||
|
||||
### Official Provider Seeding
|
||||
|
||||
- Added automatic seeding of Claude Official, OpenAI Official, and Google Official provider entries on startup, giving every user a one-click path back to the official endpoint
|
||||
|
||||
### OpenCode / OpenClaw Auto-Import
|
||||
|
||||
- Added automatic startup import of live OpenCode and OpenClaw provider configurations, matching the auto-import behavior already present for Claude, Codex, and Gemini
|
||||
|
||||
### Common Config Editor Guidance
|
||||
|
||||
- Added an informational guide and empty-state prompt to the Common Config snippet editor modal for Claude, Codex, and Gemini
|
||||
- Added a one-time informational dialog explaining Common Config Snippets when users first open the provider add/edit form
|
||||
|
||||
### Claude Session Titles & Search Highlighting
|
||||
|
||||
- Added meaningful title extraction for Claude sessions using a priority chain: custom-title metadata, first real user message, then directory basename fallback
|
||||
- Added keyword highlighting in session titles and messages during Session Manager search
|
||||
|
||||
### URL-Based Provider Icons
|
||||
|
||||
- Added a dual rendering mode to the icon system: small SVGs are inlined as React components, while large SVGs and raster images (PNG, JPG, WebP) are loaded via Vite URL imports as `<img>` tags
|
||||
|
||||
### Kaku Terminal Support
|
||||
|
||||
- Added Kaku as a selectable terminal for session launch on macOS, reusing the WezTerm-compatible launch path (#1983, thanks @yovinchen)
|
||||
|
||||
### OMO Slim Council Support
|
||||
|
||||
- Restored first-class council support as a built-in oh-my-opencode-slim agent with updated metadata and UI copy (#1982, thanks @yovinchen)
|
||||
|
||||
### New Provider Presets
|
||||
|
||||
- **TheRouter**: Added across Claude, Codex, Gemini, OpenCode, and OpenClaw (#1891, #1892, thanks @cmzz)
|
||||
- **DDSHub**: Added as a third-party partner provider for Claude with icon and partner promotion text
|
||||
- **LionCCAPI**: Added across all five apps with anthropic-messages protocol for OpenCode and OpenClaw
|
||||
- **Shengsuanyun (胜算云)**: Added as an aggregator partner provider across all five apps with URL-based icon and localized display name
|
||||
- **PIPELLM**: Added across Claude, Codex, OpenCode, and OpenClaw with full model definitions and icon
|
||||
- **E-FlowCode**: Added across all five apps with per-app protocol configuration
|
||||
|
||||
---
|
||||
|
||||
## Changes
|
||||
|
||||
### Tray Menu Organization
|
||||
|
||||
- Reworked the tray menu into per-application submenus (Claude / Codex / Gemini / OpenCode / OpenClaw)
|
||||
- Prevents overflow and scales to long provider lists
|
||||
|
||||
### Proxy Forwarding Stack
|
||||
|
||||
Rebuilt the proxy forwarding layer on a Hyper-based HTTP client (#1714, thanks @yovinchen).
|
||||
|
||||
- Transparent header forwarding: headers are forwarded without aggressive filtering
|
||||
- Improved endpoint rewriting logic
|
||||
- Better support for dynamic upstream endpoints
|
||||
- Paired with the new Full URL Endpoint Mode to unblock vendors with nonstandard URL layouts
|
||||
|
||||
### OAuth Auth Center UI Polish
|
||||
|
||||
- Tightened the Auth Center copy, layout, and icon presentation so the Codex OAuth login flow feels cleaner and less cluttered
|
||||
|
||||
### Provider Key Lifecycle & Live Sync
|
||||
|
||||
Reworked the additive provider create / rename / duplicate flows so live config writes, cleanup, and rollback stay consistent across OpenCode / OpenClaw and takeover scenarios (#1724, thanks @yovinchen).
|
||||
|
||||
- Additive-mode highlight behavior made persistent across refreshes (#1747, thanks @yovinchen)
|
||||
- Consistent live config writes across OpenCode / OpenClaw
|
||||
- Rollback behavior preserved when operations fail
|
||||
|
||||
### Codex OAuth Defaults
|
||||
|
||||
- Updated the Codex OAuth preset to the GPT-5.4 model family
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Copilot Authentication & Proxy Compatibility
|
||||
|
||||
- Fixed GitHub Copilot authentication regressions (#1854, thanks @Mason-mengze)
|
||||
- Corrected enterprise and dynamic endpoint handling
|
||||
- Repaired clipboard verification-code copying on macOS and Linux
|
||||
- Fixed Responses routing when Copilot-backed Claude providers target OpenAI models (#1735, thanks @Mason-mengze)
|
||||
|
||||
### UTF-8 Stream Chunk Boundaries
|
||||
|
||||
Fixed intermittent garbled output (U+FFFD replacement characters) in Claude Code when multi-byte UTF-8 sequences such as Chinese characters and emoji were split across TCP stream chunks via the Copilot reverse proxy (#1923, thanks @Cod1ng).
|
||||
|
||||
- Replaced `String::from_utf8_lossy` with a new `append_utf8_safe` helper across all four SSE streaming paths
|
||||
- Preserves incomplete trailing bytes in a remainder buffer and merges them with the next chunk before decoding
|
||||
- Not reproducible with direct Copilot connections that pass through raw bytes without format conversion
|
||||
|
||||
### Fragmented System Prompt Normalization
|
||||
|
||||
Fixed strict OpenAI-compatible chat backends (Nvidia, Qwen-style) rejecting requests when converted Claude payloads contained multiple system messages (#1942, thanks @yovinchen).
|
||||
|
||||
- Normalized system content into a single leading system message during the Anthropic → OpenAI chat transformation
|
||||
- Leaves the rest of the message stream unchanged
|
||||
|
||||
### Streaming Parser Compatibility
|
||||
|
||||
- Fixed SSE parsing to accept fields with optional spaces, improving compatibility with non-strict streaming implementations (#1664, thanks @Alexlangl)
|
||||
|
||||
### Provider Switch State Corruption
|
||||
|
||||
- Serialized per-app provider switches to prevent concurrent failover or hot-switch operations from leaving `is_current`, settings state, and live backup state out of sync
|
||||
|
||||
### Claude Takeover Live Config Drift
|
||||
|
||||
- Fixed provider edits while Claude takeover is active so live settings remain aligned with the latest provider state without breaking takeover restore behavior (#1828, thanks @geekdada)
|
||||
|
||||
### WebDAV Password Retention & Validation
|
||||
|
||||
- Fixed the WebDAV password field so saved credentials remain visible after refresh
|
||||
- Treated `MKCOL 405` responses correctly during connection validation (#1685, thanks @Alexlangl)
|
||||
|
||||
### Provider Card Action States
|
||||
|
||||
- Fixed additive-mode highlight behavior (#1747, thanks @yovinchen)
|
||||
- Aligned usage display layout across provider cards by always rendering action buttons
|
||||
- Replaced hard proxy-switch blocking with a warning path
|
||||
- Disabled unsupported test and usage actions for Copilot and Codex OAuth cards
|
||||
- Hid usage-config and health-check buttons for official providers
|
||||
- Removed the hover-push animation from provider cards
|
||||
|
||||
### Usage Accuracy & Pricing
|
||||
|
||||
- Fixed MiniMax quota math and 0% → 100% progression
|
||||
- Corrected CNY → USD pricing plus missing model definitions
|
||||
- Improved Gemini session-log syncing accuracy
|
||||
- Resolved session-based usage entries being shown as unknown providers
|
||||
|
||||
### Usage Editor & Skills UI Regressions
|
||||
|
||||
- Fixed usage query fields being reset while editing extractor code (#1771, thanks @if-nil)
|
||||
- Corrected broken `skills.sh` links and empty descriptions
|
||||
- Fixed auto-query default interval (5 min) and number-input clearing in usage configuration
|
||||
|
||||
### Chinese Skills Terminology
|
||||
|
||||
- Unified Skills-related labels across settings panels in the `zh` locale so storage and sync options use consistent wording
|
||||
|
||||
### Environment & Preset Compatibility
|
||||
|
||||
- Added Bun global bin detection in CLI scan (#1742, thanks @makoMakoGo)
|
||||
- Adapted to the oh-my-openagent rename with backward compatibility (#1746, thanks @yovinchen)
|
||||
- Corrected the OpenCode `kimi-for-coding` preset (#1738, thanks @makoMakoGo)
|
||||
- Gated Gemini keychain parsing to macOS only
|
||||
- Fixed an OpenClaw serializer panic on empty collections (#1724, thanks @yovinchen)
|
||||
|
||||
### Linux UI Unresponsive on Startup
|
||||
|
||||
Fixed a long-standing Linux bug where the window UI (including native title bar buttons) couldn't receive clicks until the user manually maximized and restored the window.
|
||||
|
||||
- **Root causes**: (1) Tauri webview did not acquire keyboard focus after `show()` on Linux, so the first click was consumed by X11/Wayland click-to-activate (Tauri #10746, wry #637); (2) GTK surface's input region failed to renegotiate on the `visible:false → show()` path under some WebKitGTK/compositor combinations, leaving the entire window unresponsive
|
||||
- **Mitigations**: Set `WEBKIT_DISABLE_COMPOSITING_MODE=1` at startup, and added a new `linux_fix::nudge_main_window` helper that performs `set_focus` + a ±1px no-op resize ~200ms after show, equivalent to a visually invisible "maximize-and-restore"
|
||||
- **Coverage**: Wired into all window-re-show paths — normal startup, deeplink, single_instance, tray `show_main`, and lightweight-mode exit
|
||||
|
||||
### Linux Drag Region on Header
|
||||
|
||||
- Removed `data-tauri-drag-region` from the top header bar on Linux to avoid triggering `gtk_window_begin_move_drag` paths affected by Tauri #13440 under Wayland
|
||||
- macOS drag behavior is preserved
|
||||
|
||||
### OpenCode / OpenClaw Stream Check Edge Cases
|
||||
|
||||
- Fixed custom-header passthrough
|
||||
- OpenClaw custom auth-header detection
|
||||
- Bedrock error messaging
|
||||
- OpenCode default `baseURL` fallback handling
|
||||
|
||||
### Duplicate Toast on Provider Switch
|
||||
|
||||
- Fixed double toast notifications (proxy-required warning followed by switch-success) when switching to Copilot, ChatGPT, or OpenAI-format providers with the proxy not running
|
||||
|
||||
### Session Search Accuracy & Chinese Support
|
||||
|
||||
- Fixed session search result truncation across providers
|
||||
- Switched FlexSearch tokenizer to full mode for proper Chinese substring matching
|
||||
|
||||
### Adaptive Thinking Reasoning Effort
|
||||
|
||||
- Fixed `resolve_reasoning_effort()` mapping adaptive thinking to `xhigh` instead of incorrectly using `high` in OpenAI format conversions
|
||||
|
||||
### Thinking Model Fallback Display
|
||||
|
||||
- Fixed the Claude provider form showing an empty Thinking model field after saving only a main model by applying read-only fallback to ANTHROPIC_MODEL (#1984, thanks @yovinchen)
|
||||
|
||||
### Auth Tab Localization
|
||||
|
||||
- Fixed missing i18n translation keys for the settings auth tab label across all locale bundles (#1985, thanks @yovinchen)
|
||||
|
||||
### Schema Migration Guard
|
||||
|
||||
- Fixed database migrations failing when skills or model_pricing tables did not exist by adding table-existence checks before ALTER and UPDATE operations
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
### User Manual Refresh
|
||||
|
||||
- Updated the EN / ZH / JA user manuals to cover tray submenus, lightweight mode, provider model fetching, session management, workspace files, WebDAV v2 behavior, OpenCode / OpenClaw activation, and other provider workflow improvements
|
||||
|
||||
### Community & Contribution Docs
|
||||
|
||||
- Added `CONTRIBUTING.md`, `SECURITY.md`, and `CODE_OF_CONDUCT.md`
|
||||
- Added bilingual GitHub issue and PR templates
|
||||
- Added Dependabot configuration (#1829, thanks @bengbengbalabalabeng) and a stale-bot workflow for inactive issues
|
||||
- Added a PR / push quality-checks CI workflow
|
||||
|
||||
### Release Notes Risk Notice Backport
|
||||
|
||||
- Added a Copilot reverse proxy risk notice and anchored highlight links in the v3.12.3 release notes across all three languages
|
||||
|
||||
### Sponsor Partners
|
||||
|
||||
- Added Shengsuanyun, LionCC, and DDS as sponsor partners in README across all languages
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Risk Notice
|
||||
|
||||
**Codex OAuth Reverse Proxy Disclaimer**
|
||||
|
||||
The Codex OAuth reverse proxy introduced in this release accesses ChatGPT Codex services through reverse-engineered OAuth flows. Please be aware of the following risks before enabling this feature:
|
||||
|
||||
1. **Terms of Service**: Using reverse-engineered OAuth flows to access OpenAI services may violate OpenAI's terms of service, which prohibit unauthorized automated access, service reproduction, and circumventing intended access paths.
|
||||
2. **Account Risk**: OpenAI may flag unusual usage patterns as suspicious automated activity, potentially resulting in temporary or permanent restrictions on ChatGPT access.
|
||||
3. **No Guarantee**: OpenAI may update its authentication and detection mechanisms at any time, and usage patterns that work today may be flagged in the future.
|
||||
|
||||
The **GitHub Copilot reverse proxy** introduced in v3.12.3 also remains subject to its existing risk notice — see the [v3.12.3 release notes](v3.12.3-en.md#️-risk-notice) for the full disclosure.
|
||||
|
||||
Users enable these features **at their own risk**. CC Switch is not responsible for any account restrictions, warnings, or service suspensions resulting from the use of these features.
|
||||
|
||||
---
|
||||
|
||||
## 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 12 (Monterey) or later | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | See table below | x64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| File | Description |
|
||||
| ------------------------------------------ | ---------------------------------------------------- |
|
||||
| `CC-Switch-v3.13.0-Windows.msi` | **Recommended** - MSI installer with auto-update |
|
||||
| `CC-Switch-v3.13.0-Windows-Portable.zip` | Portable version, extract and run, no registry write |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| ---------------------------------- | -------------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.13.0-macOS.dmg` | **Recommended** - DMG installer, drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.13.0-macOS.zip` | ZIP archive, extract and drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.13.0-macOS.tar.gz` | For Homebrew installation and auto-update |
|
||||
|
||||
> macOS builds are code-signed and notarized by Apple for a seamless install experience.
|
||||
|
||||
### 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` |
|
||||
@@ -0,0 +1,433 @@
|
||||
# CC Switch v3.13.0
|
||||
|
||||
> 軽量モード、クォータ・残高の可視化、プロバイダーモデル自動取得、Codex OAuth リバースプロキシ、トレイのアプリ別サブメニュー
|
||||
|
||||
**[中文版 →](v3.13.0-zh.md) | [English →](v3.13.0-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.13.0 は、可観測性、プロバイダーワークフローの使いやすさ、プロキシ互換性を中心とした大型機能リリースです。Claude / Codex / Gemini の公式プロバイダー、Token Plan、Copilot、サードパーティ残高 API にわたる**クォータと残高のインライン表示**を追加し、メインウィンドウなしでシステムトレイから CC Switch を動作させる**軽量モード**を導入しました。OpenAI 互換の `/v1/models` による**自動モデル発見**を 5 つのサポート対象アプリケーションすべてに提供し、ChatGPT サブスクライバー向けの **Codex OAuth リバースプロキシ**を同梱しています。トレイメニューを**アプリ別サブメニュー**に再編成し、プロキシ転送スタックを **Hyper ベースのクライアント**に再構築し、**Skills ワークフロー**を発見、バッチ更新、ストレージ位置切り替え、および組み込みの skills.sh 検索・インストールで刷新しました。さらに、フル URL エンドポイントモード、強化されたトークン用量追跡、Copilot インタラクション最適化、マルチバイト UTF-8 ストリームチャンク境界修正、Linux 起動時の UI 応答性修正、およびよりフレンドリーな新規ユーザーオンボーディングなども含まれます。
|
||||
|
||||
**リリース日**: 2026-04-10
|
||||
|
||||
**更新規模**: 139 commits | 280 files changed | +31,627 / -3,042 lines
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **軽量モード**: トレイ専用の動作モード。トレイへの終了時にメインウィンドウを破棄し、必要時に再作成することで、アイドル時の CC Switch のデスクトップフットプリントを最小化
|
||||
- **クォータと残高の可視化**: プロバイダーカードでのインラインクォータ/残高表示 — 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 プロバイダーカードタイプとして追加。ユーザーは ChatGPT サブスクリプションを Claude Code で利用可能に。マネージド OAuth ログインとサブスクリプションクォータのインライン表示を提供（[⚠️ リスクに関する注意事項](#️-リスクに関する注意事項)）
|
||||
- **トレイのアプリ別サブメニュー**: トレイメニューをアプリ別サブメニューに再編成し、プロバイダー数が多くてもメニューがオーバーフローせず、バックグラウンドのプロバイダー切り替えが長いリストでもスケール
|
||||
- **Skills 発見とバッチ更新**: SHA-256 ベースの skill 更新検出、各 skill および「すべて更新」のバッチ更新、`skills.sh` 検索統合、CC Switch ストレージと `~/.agents/skills` の間のストレージ位置切り替え
|
||||
- **セッションワークフローの改善**: Session Manager でのバッチ削除、Claude ターミナル復元前のディレクトリピッカー、プロキシ傍受なしでの Claude / Codex / Gemini セッションログからの用量インポート、正確な Codex JSONL 解析、アプリ別の用量フィルタリング
|
||||
- **OpenCode / OpenClaw Stream Check カバレッジ**: OpenCode の npm パッケージマッピング検出、OpenClaw `openai-completions` サポート、および残りの OpenClaw プロトコルバリアント
|
||||
- **フル URL エンドポイントモード**: `base_url` を完全な上流エンドポイントとして扱うプロバイダーオプションを追加し、非標準 URL レイアウトを要求するベンダーに対応
|
||||
- **Hyper ベースのプロキシ転送スタック**: プロキシ転送層を Hyper ベースのクライアントに再構築し、透過的なヘッダー転送、改善されたエンドポイントリライト、および動的上流エンドポイントのサポートを強化
|
||||
- **Copilot インタラクション最適化**: GitHub Copilot premium interaction の不要な消費を削減するリクエスト分類とルーティングロジックを追加
|
||||
- **UTF-8 ストリームチャンク境界修正**: マルチバイト UTF-8 シーケンスが TCP チャンクを跨いで分割された際の Copilot リバースプロキシ経由での文字化け（U+FFFD 置換文字）を解消するため、すべての 4 つの SSE ストリーミングパスを修正
|
||||
- **Linux 起動時 UI 修正**: ユーザーが手動でウィンドウを最大化・復元するまでウィンドウ UI がクリックを受け付けない長年の問題を修正
|
||||
- **初回起動オンボーディング**: 新規インストール時のワンタイムウェルカムダイアログ、Claude / OpenAI / Google 公式プリセットの自動シード、起動時の OpenCode / OpenClaw ライブ設定の自動インポート
|
||||
- **Claude セッションタイトルと検索ハイライト**: カスタムタイトルメタデータ → 最初のユーザーメッセージ → ディレクトリベースネームの優先チェーンによる Claude セッションの意味のあるタイトル抽出、Session Manager 検索でのキーワードハイライト
|
||||
- **URL ベースのプロバイダーアイコン**: 大きな SVG とラスター画像（PNG / JPG / WebP）を Vite URL import でロードし、小さな SVG はインライン保持するデュアルレンダリングモード
|
||||
- **新プロバイダープリセット**: TheRouter、DDSHub、LionCCAPI、Shengsuanyun（胜算云）、PIPELLM、E-FlowCode を対応アプリケーションに追加
|
||||
|
||||
---
|
||||
|
||||
## 新機能
|
||||
|
||||
### 軽量モード
|
||||
|
||||
CC Switch のアイドル時のデスクトップフットプリントを大幅に削減するトレイ専用動作モード。
|
||||
|
||||
- トレイへの終了時にメインウィンドウを隠すのではなく破棄し、UI リソースとメモリを解放
|
||||
- トレイ、ディープリンク、またはシングルインスタンスアクティベーションからユーザーが CC Switch を再オープンしたときにウィンドウを再作成
|
||||
- 通常起動、ディープリンク、シングルインスタンス、トレイ `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 キーを使ってプロバイダーの `/v1/models` エンドポイントをクエリ
|
||||
- ドロップダウンでモデルをカテゴリ別にグループ化
|
||||
- ネットワーク / 認証 / エンドポイント未検出 / パース失敗を区別する具体的なエラーメッセージを提供
|
||||
- 5 つのアプリケーション（Claude / Codex / Gemini / OpenCode / OpenClaw）すべてをサポート
|
||||
|
||||
### Codex OAuth リバースプロキシ
|
||||
|
||||
ChatGPT サブスクライバーが ChatGPT サブスクリプションを Claude Code で利用できるリバースプロキシパスを追加。
|
||||
|
||||
- ChatGPT 認証を使ったマネージド OAuth ログインフロー
|
||||
- API キー型プロバイダーと並ぶ新しい Claude プロバイダーカードタイプとして表示
|
||||
- サブスクリプションクォータのインライン表示
|
||||
- Auth Center との統合によるトークンの一元管理
|
||||
- 有効化前に下記の [⚠️ リスクに関する注意事項](#️-リスクに関する注意事項) をご確認ください
|
||||
|
||||
### トレイのアプリ別サブメニュー
|
||||
|
||||
トレイメニューを、フラットリストの代わりにアプリケーション別にプロバイダーをグループ化する構造に再編成しました。
|
||||
|
||||
- Claude / Codex / Gemini / OpenCode / OpenClaw のアプリ別サブメニュー
|
||||
- プロバイダーが多い場合にトレイメニューが画面からはみ出すことを防止
|
||||
- バックグラウンドのプロバイダー切り替えが長いリストでもクリーンにスケール
|
||||
|
||||
### Skills 発見とバッチ更新
|
||||
|
||||
Skills 管理パネルを、発見と保守を備えた完全なワークフローにアップグレード。
|
||||
|
||||
- **SHA-256 更新検出**: Skill をコンテンツハッシュ化することで、どれが上流で変更されたかを UI が正確に把握
|
||||
- **各 skill およびバッチ更新**: 個別の「更新」ボタンと、スライドインアニメーション付きの「すべて更新」バッチアクション
|
||||
- **ストレージ位置切り替え**: CC Switch ストレージと `~/.agents/skills` の間を skill 状態を失わずに切り替え
|
||||
- **公開レジストリ検索**: `skills.sh` 検索をダイアログに直接統合し、コミュニティ skill を発見しやすく
|
||||
|
||||
### セッションワークフローの改善
|
||||
|
||||
Claude / Codex / Gemini セッションでの作業を効率化する複数のセッション管理改善。
|
||||
|
||||
- **セッションのバッチ削除**: Session Manager で複数のセッションを選択し、1 つのアクションで削除 (#1693, @Alexlangl に感謝)
|
||||
- **復元前のディレクトリピッカー**: Claude ターミナルの復元時、事前に作業ディレクトリを選択 (#1752, @yovinchen に感謝)
|
||||
- **プロキシなしのセッションログ用量**: Claude / Codex / Gemini セッションログから直接用量データをインポート — プロキシ傍受は不要
|
||||
- **正確な Codex JSONL 解析**: Codex の推定用量を、JSONL セッションログの正確な解析に置き換え。Codex モデル名の正規化により料金ルックアップが一貫
|
||||
- **Gemini CLI セッションログ統合**: Gemini 用量が Gemini CLI セッションログから正確に同期
|
||||
- **アプリ別の用量フィルタリング**: 用量ダッシュボードを Claude / Codex / Gemini ごとに独立してフィルタリング可能
|
||||
|
||||
### OpenCode / OpenClaw Stream Check カバレッジ
|
||||
|
||||
Stream Check パネルのカバレッジを OpenCode と OpenClaw のサーフェス全体に拡張。
|
||||
|
||||
- npm パッケージマッピングによる OpenCode 検出
|
||||
- OpenClaw `openai-completions` プロトコルのサポート
|
||||
- 残りの 3 つの OpenClaw プロトコルバリアントのサポート
|
||||
- カスタムヘッダー透過、OpenClaw カスタム auth-header 検出、Bedrock エラーメッセージ、OpenCode デフォルト `baseURL` フォールバックのエッジケース処理
|
||||
|
||||
### フル 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 interaction 消費パスから迂回
|
||||
- Copilot サブスクリプションの使用可能期間を延長することを目的
|
||||
- 注意: 消費を最適化しても、Copilot 外で Copilot API を使用する場合、Copilot 内で使用するよりも消費量は多くなります。
|
||||
|
||||
### 初回起動ウェルカムダイアログ
|
||||
|
||||
新規インストールのユーザーに CC Switch のワークフローを案内するワンタイムウェルカムダイアログを追加。
|
||||
|
||||
- 既存のライブ設定がデフォルトプロバイダーとして保持される仕組みを説明
|
||||
- 内蔵の公式プリセットによるワンクリックでの公式エンドポイント復帰を紹介
|
||||
- アップグレードユーザーは空プロバイダーチェックにより自動的にスキップ
|
||||
|
||||
### 公式プロバイダーの自動シード
|
||||
|
||||
- 起動時に Claude Official / OpenAI Official / Google Official プロバイダーエントリを自動シードし、すべてのユーザーにワンクリックで公式エンドポイントに戻るパスを提供
|
||||
|
||||
### OpenCode / OpenClaw 自動インポート
|
||||
|
||||
- 起動時に OpenCode と OpenClaw のライブプロバイダー設定を自動インポート。Claude / Codex / Gemini で既にある自動インポート動作と同等に
|
||||
|
||||
### Common Config エディタガイダンス
|
||||
|
||||
- Claude / Codex / Gemini の Common Config スニペットエディタモーダルに情報ガイドと空状態プロンプトを追加
|
||||
- ユーザーがプロバイダー追加/編集フォームを初めて開く際、Common Config Snippets を説明するワンタイムダイアログを追加
|
||||
|
||||
### Claude セッションタイトルと検索ハイライト
|
||||
|
||||
- Claude セッションの意味のあるタイトル抽出を追加。優先チェーン: カスタムタイトルメタデータ → 最初の実ユーザーメッセージ → ディレクトリベースネームフォールバック
|
||||
- Session Manager 検索時にセッションタイトルとメッセージ内のキーワードをハイライト
|
||||
|
||||
### URL ベースのプロバイダーアイコン
|
||||
|
||||
- アイコンシステムにデュアルレンダリングモードを追加: 小さな SVG は React コンポーネントとしてインライン、大きな SVG とラスター画像（PNG / JPG / WebP）は Vite URL import で `<img>` タグとしてロード
|
||||
|
||||
### Kaku ターミナルサポート
|
||||
|
||||
- macOS でセッション起動用の選択可能なターミナルとして Kaku を追加。WezTerm 互換の起動パスを再利用 (#1983, @yovinchen に感謝)
|
||||
|
||||
### OMO Slim Council サポート
|
||||
|
||||
- 内蔵 oh-my-opencode-slim エージェントとしての council のファーストクラスサポートを復元。メタデータと UI コピーを更新 (#1982, @yovinchen に感謝)
|
||||
|
||||
### 新プロバイダープリセット
|
||||
|
||||
- **TheRouter**: Claude / Codex / Gemini / OpenCode / OpenClaw の 5 アプリに追加 (#1891, #1892, @cmzz に感謝)
|
||||
- **DDSHub**: Claude のサードパーティパートナープロバイダーとして追加。アイコンとパートナープロモーションテキスト付き
|
||||
- **LionCCAPI**: 5 アプリすべてに追加。OpenCode / OpenClaw は anthropic-messages プロトコルを使用
|
||||
- **Shengsuanyun（胜算云）**: アグリゲーターパートナープロバイダーとして 5 アプリすべてに追加。URL ベースのアイコンとローカライズ名をサポート
|
||||
- **PIPELLM**: Claude / Codex / OpenCode / OpenClaw に追加。完全なモデル定義とアイコン付き
|
||||
- **E-FlowCode**: 5 アプリすべてに追加。アプリごとに異なるプロトコル設定
|
||||
|
||||
---
|
||||
|
||||
## 変更
|
||||
|
||||
### トレイメニュー構成
|
||||
|
||||
- トレイメニューをアプリ別サブメニュー（Claude / Codex / Gemini / OpenCode / OpenClaw）に再編成
|
||||
- オーバーフローを防ぎ、長いプロバイダーリストでもスケール
|
||||
|
||||
### プロキシ転送スタック
|
||||
|
||||
プロキシ転送層を Hyper ベースの HTTP クライアント上に再構築 (#1714, @yovinchen に感謝)。
|
||||
|
||||
- 透過的なヘッダー転送: ヘッダーをアグレッシブにフィルタせずに転送
|
||||
- 改善されたエンドポイントリライトロジック
|
||||
- 動的上流エンドポイントへのより良いサポート
|
||||
- 新しいフル URL エンドポイントモードと組み合わせ、非標準 URL レイアウトのベンダーをアンブロック
|
||||
|
||||
### OAuth Auth Center UI 調整
|
||||
|
||||
- Auth Center のコピー、レイアウト、アイコンの表現を調整し、Codex OAuth ログインフローをよりクリーンに
|
||||
|
||||
### プロバイダーキーライフサイクルと Live 同期
|
||||
|
||||
アディティブプロバイダーの作成/名前変更/複製フローを再構築し、OpenCode / OpenClaw およびテイクオーバーシナリオで Live 設定の書き込み、クリーンアップ、ロールバックが一貫するように (#1724, @yovinchen に感謝)。
|
||||
|
||||
- アディティブモードのハイライト動作がリフレッシュ後も保持 (#1747, @yovinchen に感謝)
|
||||
- OpenCode / OpenClaw 全体で Live 設定の書き込みが一貫
|
||||
- 操作失敗時のロールバック動作を保持
|
||||
|
||||
### Codex OAuth デフォルト
|
||||
|
||||
- Codex OAuth プリセットを GPT-5.4 モデルファミリーに更新
|
||||
|
||||
---
|
||||
|
||||
## バグ修正
|
||||
|
||||
### Copilot 認証とプロキシ互換性
|
||||
|
||||
- GitHub Copilot 認証の回帰を修正 (#1854, @Mason-mengze に感謝)
|
||||
- エンタープライズおよび動的エンドポイントの処理を修正
|
||||
- macOS と Linux でのクリップボード検証コードコピーを修復
|
||||
- Copilot バックの Claude プロバイダーが OpenAI モデルをターゲットとする場合の Responses ルーティングを修正 (#1735, @Mason-mengze に感謝)
|
||||
|
||||
### UTF-8 ストリームチャンク境界
|
||||
|
||||
Claude Code で Copilot リバースプロキシ経由時、中国語文字や絵文字などのマルチバイト 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 カードでサポートされていないテスト/用量アクションを無効化
|
||||
- 公式プロバイダーでは用量設定とヘルスチェックのボタンを非表示
|
||||
- プロバイダーカードのホバープッシュアニメーションを削除
|
||||
|
||||
### 用量精度と料金
|
||||
|
||||
- MiniMax クォータの計算と 0% → 100% 進行を修正
|
||||
- CNY → USD の料金を修正し、不足モデルを追加
|
||||
- Gemini セッションログ同期の精度を改善
|
||||
- セッションベースの用量エントリが「不明なプロバイダー」として表示される問題を解決
|
||||
|
||||
### 用量エディタと Skills UI の回帰
|
||||
|
||||
- エクストラクタコード編集時に用量クエリフィールドがリセットされる問題を修正 (#1771, @if-nil に感謝)
|
||||
- 壊れた `skills.sh` リンクと空の説明を修正
|
||||
- 用量設定の auto-query デフォルト間隔（5 分）と数値入力のクリア問題を修正
|
||||
|
||||
### 中国語 Skills 用語
|
||||
|
||||
- zh ロケールの設定パネルで Skills 関連ラベルを統一し、ストレージと同期オプションで一貫した表現を使用
|
||||
|
||||
### 環境とプリセット互換性
|
||||
|
||||
- CLI スキャンで Bun グローバル bin 検出を追加 (#1742, @makoMakoGo に感謝)
|
||||
- oh-my-openagent のリネームに後方互換性を持って対応 (#1746, @yovinchen に感謝)
|
||||
- OpenCode `kimi-for-coding` プリセットを修正 (#1738, @makoMakoGo に感謝)
|
||||
- Gemini キーチェーン解析を macOS のみに制限
|
||||
- 空コレクションで発生する OpenClaw シリアライザのパニックを修正 (#1724, @yovinchen に感謝)
|
||||
|
||||
### Linux 起動時の UI 応答性
|
||||
|
||||
ユーザーが手動でウィンドウを最大化・復元するまで、ウィンドウ UI（ネイティブタイトルバーボタンを含む）がクリックを受け付けないという長年の Linux 固有のバグを修正。
|
||||
|
||||
- **根本原因**: (1) Tauri webview が Linux の `show()` 後にキーボードフォーカスを取得せず、最初のクリックが X11/Wayland の click-to-activate によって消費される（Tauri #10746、wry #637）; (2) GTK surface の入力領域が、一部の WebKitGTK/コンポジター組み合わせで `visible:false → show()` パスの再交渉に失敗し、ウィンドウ全体が応答しなくなる
|
||||
- **緩和策**: 起動時に `WEBKIT_DISABLE_COMPOSITING_MODE=1` を設定し、新しい `linux_fix::nudge_main_window` ヘルパーを追加。show から ~200ms 後に `set_focus` + ±1px のノーオペレーションリサイズを実行し、視覚的に見えない「最大化と復元」と同等の動作を実現
|
||||
- **カバレッジ**: すべてのウィンドウ再表示パス（通常起動、ディープリンク、シングルインスタンス、トレイ `show_main`、軽量モード終了）に統合
|
||||
|
||||
### Linux ヘッダーのドラッグ領域
|
||||
|
||||
- Wayland 下で Tauri #13440 の影響を受ける `gtk_window_begin_move_drag` パスのトリガーを回避するため、Linux ではトップヘッダーバーから `data-tauri-drag-region` を削除
|
||||
- macOS のドラッグ動作は保持
|
||||
|
||||
### OpenCode / OpenClaw Stream Check のエッジケース
|
||||
|
||||
- カスタムヘッダー透過を修正
|
||||
- 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 タブのローカライゼーション
|
||||
|
||||
- 設定の auth タブラベルに不足していた i18n 翻訳キーをすべてのロケールバンドルで修正 (#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 に感謝) と、非アクティブな issue を自動クローズする stale-bot ワークフローを追加
|
||||
- PR / push 品質チェック CI ワークフローを追加
|
||||
|
||||
### Release Notes のリスク通知バックポート
|
||||
|
||||
- v3.12.3 の release notes に Copilot リバースプロキシのリスク通知とハイライトリンクのアンカーを 3 言語すべてに追加
|
||||
|
||||
### スポンサーパートナー
|
||||
|
||||
- README の 3 言語すべてに Shengsuanyun、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 リリースノート](v3.12.3-ja.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 インストーラー、ドラッグ＆ドロップでインストール |
|
||||
| `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` |
|
||||
@@ -0,0 +1,434 @@
|
||||
# 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` |
|
||||
@@ -0,0 +1,469 @@
|
||||
# CC Switch v3.14.0
|
||||
|
||||
> Hermes Agent becomes the 6th managed app, Claude Opus 4.7 rolls out across the preset matrix, Gemini Native API proxy, "Local Routing" rename, and application-level window controls
|
||||
|
||||
**[中文版 →](v3.14.0-zh.md) | [日本語版 →](v3.14.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.14.0 is a major release centered on onboarding **Hermes Agent as the 6th first-class managed app** and rolling out **Claude Opus 4.7** across the full aggregator and Bedrock preset matrix. Hermes support covers a database v9 → v10 migration, a complete Rust command surface, YAML-backed `~/.hermes/config.yaml` read/write with atomic backups, MCP sync, Skills sync, SQLite + JSONL session management, and dedicated frontend panels including a Memory editor. All four API protocols aligned with Hermes Agent 0.10.0 (`chat_completions`, `anthropic_messages`, `codex_responses`, `bedrock_converse`) are selectable. Providers owned by the user-authored `providers:` dict are rendered as read-only cards, and deep YAML configuration is delegated directly to the Hermes Web UI.
|
||||
|
||||
Beyond Hermes, this release adds a **Gemini Native API proxy** (`api_format = "gemini_native"`) so the proxy can forward directly to Google's `generateContent` endpoint with full streaming, schema conversion, and shadow request support; renames the legacy "Local Proxy Takeover" to **Local Routing** across UI copy, README, and docs in all three locales; introduces **application-level window controls**, an opt-in setting that materially improves the experience on Linux Wayland where compositor-drawn buttons can become inert; and bundles late additions for launching `hermes dashboard` from the toolbar, a LemonData preset across all six apps, a DDSHub Codex endpoint, plus several Hermes health-check and Usage modal fixes.
|
||||
|
||||
On the session side, the message list is **virtualized** via `@tanstack/react-virtual` so conversations with thousands of records scroll smoothly and long messages collapse by default; the Usage dashboard adds a **date range picker** (Today / 1d / 7d / 14d / 30d + custom date-time calendar) and a page-jump input; **Stream Check error classification** now surfaces color-coded toasts with refreshed default probe models and an explicit "model not found" branch; and switching to official providers is **blocked while Local Routing is active** to avoid account-suspension risk. The pricing database is reseeded from v8 → v9 with ~50 new model entries (Claude 4.7, Opus 4.7 Adaptive Thinking, Grok 4, Qwen 3.5/3.6, MiniMax M2.5/M2.7, Doubao Seed 2.0 series, GLM-5/5.1 and others) and corrected stale prices.
|
||||
|
||||
**Release Date**: 2026-04-21
|
||||
|
||||
**Update Scale**: 100 commits | 219 files changed | +20,548 / -3,569 lines
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- **Hermes Agent Support (6th Managed App)**: Database v9 → v10 migration, full Rust command surface, YAML read/write with atomic backups, MCP sync, Skills sync, SQLite + JSONL session management, dedicated frontend panels, and four API protocols (`chat_completions` / `anthropic_messages` / `codex_responses` / `bedrock_converse`)
|
||||
- **Claude Opus 4.7 Rollout**: Adaptive thinking whitelisting, per-million pricing seed, Bedrock SKU (`anthropic.claude-opus-4-7` / `global.anthropic.claude-opus-4-7`, dropping the legacy `-v1` suffix); all aggregator and Bedrock presets migrated to Opus 4.7 as the default Opus model
|
||||
- **Claude `max` Effort Tier**: Effort dropdown upgraded from `high` to `max`
|
||||
- **Gemini Native API Proxy**: New `api_format = "gemini_native"` forwards directly to Google's `generateContent` with full streaming / schema conversion / shadow request support
|
||||
- **GitHub Copilot Enterprise Server**: GHES authentication and endpoint configuration for Copilot-backed Claude providers
|
||||
- **Copilot Premium Consumption Deep Optimization**: Proactive thinking-block stripping before forwarding, `tool_result` classification fix, subagent detection, `x-interaction-id` billing merge, orphan `tool_result` sanitization, and default warmup downgrade — a systematic reduction in premium interaction consumption
|
||||
- **Session List Virtualization**: Long conversations scroll smoothly and long messages collapse by default to reduce text layout cost
|
||||
- **Codex / OpenClaw Session Title Extraction**: Meaningful title extraction with 2-line display; strips OpenClaw `message_id` suffix noise
|
||||
- **Usage Date Range Picker**: Today / 1d / 7d / 14d / 30d preset tabs + custom date-time calendar; page-jump input on paginated lists
|
||||
- **Stream Check Error Classification**: Color-coded error toasts; refreshed default probe models; explicit "model not found" detection
|
||||
- **Block Official Provider Switching During Local Routing**: Routing official API traffic through the local proxy carries account-suspension risk — switches are blocked with a warning toast
|
||||
- **Pricing Database Refresh (v8 → v9)**: ~50 new model entries and corrected stale prices
|
||||
- **Application-Level Window Controls**: Opt-in setting to render CC Switch's own min/max/close buttons, materially improving Linux Wayland experience
|
||||
- **Hermes in Unified Skills Management**: Skill install, enable, and filter now cover Hermes
|
||||
- **Hermes / OpenClaw Config Directory Override**: Point CC Switch at a custom `~/.hermes/config.yaml` or `openclaw.json` location
|
||||
- **Launch Hermes Dashboard from Toolbar**: When the Hermes Web UI probe fails, the toolbar entry offers to run `hermes dashboard` in the user's preferred terminal
|
||||
- **New Partner Presets**: LemonData across all six apps; DDSHub Codex endpoint; StepFun Step Plan
|
||||
|
||||
---
|
||||
|
||||
## Added
|
||||
|
||||
### Hermes Agent Support (6th Managed App)
|
||||
|
||||
CC Switch now treats Hermes Agent as a first-class managed app alongside Claude / Codex / Gemini / OpenCode / OpenClaw.
|
||||
|
||||
- **Database Migration v9 → v10**: Adds `enabled_hermes` columns to `mcp_servers` and `skills` tables (`DEFAULT 0`, auto-migrated, no data loss)
|
||||
- **YAML Configuration Read/Write**: `~/.hermes/config.yaml` read/write with atomic backups; `tests/hermes_roundtrip.rs` guards against dropped OAuth MCP `auth` blocks or pollution of unrelated YAML keys
|
||||
- **Four API Protocols**: Aligned with Hermes Agent 0.10.0 — `chat_completions` / `anthropic_messages` / `codex_responses` / `bedrock_converse`; new deeplinks default to `chat_completions`
|
||||
- **User `providers:` Dict Read-Only Rendering**: User-authored providers in the YAML appear as read-only cards in CC Switch; deep configuration delegates to the Hermes Web UI
|
||||
- **Additive Switching**: Unlike Claude / Codex's "override" style, all Hermes providers coexist in the same YAML
|
||||
|
||||
### Hermes Memory Panel
|
||||
|
||||
- New Memory panel for editing `MEMORY.md` / `USER.md` directly, with an enable switch, character-count limits, and a live save flow
|
||||
- Replaces the Prompts entry for Hermes
|
||||
|
||||
### Hermes Provider Presets (~50)
|
||||
|
||||
- Covers Nous Research, Shengsuanyun, OpenRouter, DeepSeek, Together AI, StepFun, Zhipu GLM, Bailian, Kimi, MiniMax, DouBao, BaiLing, ModelScope, KAT-Coder, PackyCode, Cubence, AIGoCode, RightCode, AICodeMirror, AICoding, CrazyRouter, SSSAiCode, Micu, CTok.ai, DDSHub, E-FlowCode, LionCCAPI, PIPELLM, Compshare, SiliconFlow, AiHubMix, DMXAPI, TheRouter, Novita, Nvidia, and Xiaomi MiMo
|
||||
|
||||
### Launch Hermes Dashboard from Toolbar
|
||||
|
||||
- When the Hermes Web UI probe fails, the toolbar entry opens a confirm dialog offering to run `hermes dashboard` in the user's preferred terminal
|
||||
- Spawned via a temp bash / batch script; `hermes dashboard` opens the browser itself once ready, so no polling is required
|
||||
- The Memory panel and Health banner keep the existing toast behavior
|
||||
- Also corrects the stale `hermes web` hint in the offline toast (the real command is `hermes dashboard`)
|
||||
- Linux terminal detection reordered to try `which` before stat'ing `/usr/bin`, `/bin`, `/usr/local/bin`
|
||||
|
||||
### Claude Opus 4.7 Support
|
||||
|
||||
- New Claude Opus 4.7 with adaptive thinking whitelisting, per-million pricing seed, and Bedrock SKU (`anthropic.claude-opus-4-7` / `global.anthropic.claude-opus-4-7`, dropping the legacy `-v1` suffix)
|
||||
- All aggregator and Bedrock presets migrated to Opus 4.7 as the default Opus model
|
||||
|
||||
### Claude `max` Effort Tier
|
||||
|
||||
- Claude effort dropdown upgraded from `high` to `max` for extended reasoning capacity
|
||||
|
||||
### Gemini Native API Proxy
|
||||
|
||||
- New `api_format = "gemini_native"` so the proxy can forward directly to Google's `generateContent` API (#1918, thanks @yovinchen)
|
||||
- Full streaming, schema conversion, and shadow request support
|
||||
- Adds `gemini_url.rs`, `gemini_schema.rs`, `gemini_shadow.rs`, `streaming_gemini.rs`, and `transform_gemini.rs` under the proxy providers module
|
||||
|
||||
### GitHub Copilot Enterprise Server (GHES)
|
||||
|
||||
- GHES authentication and endpoint configuration for Copilot-backed Claude providers (#2175, thanks @hotelbe)
|
||||
|
||||
### Session List Virtualization
|
||||
|
||||
- Virtualized the session list via `@tanstack/react-virtual` so long conversations (thousands of records) scroll smoothly
|
||||
- Long session messages are collapsed by default to reduce text layout cost
|
||||
|
||||
### Codex / OpenClaw Session Title Extraction
|
||||
|
||||
- Meaningful title auto-extraction for Codex and OpenClaw sessions with 2-line display
|
||||
- Strips OpenClaw `message_id` suffix noise
|
||||
|
||||
### Usage Date Range Picker
|
||||
|
||||
- New date range selector on the usage dashboard with preset tabs (Today / 1d / 7d / 14d / 30d) + custom date + time calendar (#2002, thanks @yovinchen)
|
||||
- Page-jump input added on paginated lists
|
||||
|
||||
### Model Mapping Quick-Set
|
||||
|
||||
- New quick-set button next to model mapping fields in provider forms for faster edits (#2179, thanks @lispking)
|
||||
|
||||
### Stream Check Error Classification
|
||||
|
||||
- Stream Check errors are classified and surfaced as color-coded toasts
|
||||
- Refreshed default probe models to match each vendor's current lineup
|
||||
- Explicit detection for "model not found" responses
|
||||
|
||||
### Block Official Provider Switching During Local Routing
|
||||
|
||||
- Switching to official providers is blocked while Local Routing is active, with a warning toast
|
||||
- Reason: routing official API traffic through the local proxy carries account-suspension risk
|
||||
|
||||
### Pricing Database Refresh (v8 → v9)
|
||||
|
||||
- Reseed-on-migration pricing table
|
||||
- ~50 new model pricing entries including Claude 4.7, Opus 4.7 Adaptive Thinking, Grok 4, Qwen 3.5/3.6, MiniMax M2.5/M2.7, Doubao Seed 2.0 series, GLM-5/5.1
|
||||
- Corrected stale prices for DeepSeek, Kimi K2.5, and others
|
||||
|
||||
### Application-Level Window Controls
|
||||
|
||||
- Opt-in setting to render CC Switch's own minimize / toggle-maximize / close buttons instead of system decorations (#1119, thanks @git1677967754)
|
||||
- Materially improves the experience on Linux Wayland where compositor-drawn buttons can become inert
|
||||
|
||||
### Hermes in Unified Skills Management
|
||||
|
||||
- Hermes is added to the unified Skills surface
|
||||
- Skill install, enable, and filter now cover the Hermes app alongside Claude / Codex / Gemini / OpenCode / OpenClaw
|
||||
|
||||
### OpenClaw Config Directory Override
|
||||
|
||||
- New settings option to point CC Switch at a custom `openclaw.json` location (#1518, thanks @mrFranklin)
|
||||
|
||||
### Hermes Config Directory Override
|
||||
|
||||
- New settings option to point CC Switch at a custom `~/.hermes/config.yaml` location, backed by data-driven dispatch
|
||||
|
||||
### StepFun Step Plan Preset
|
||||
|
||||
- StepFun Step Plan (EN / ZH) provider presets (#2155, thanks @hengm3467)
|
||||
|
||||
### New API Usage Script Template
|
||||
|
||||
- Added a User-Agent header to the New API usage script template for better upstream compatibility
|
||||
|
||||
### LemonData Provider Preset (All Six Apps)
|
||||
|
||||
- LemonData registered as a third-party partner preset across Claude, Codex, Gemini, OpenCode, OpenClaw, and Hermes
|
||||
- Icon assets and zh / en / ja partner-promotion copy
|
||||
- Claude preset uses `ANTHROPIC_API_KEY` auth; OpenAI-compatible apps target `gpt-5.4`
|
||||
|
||||
### DDSHub Codex Preset
|
||||
|
||||
- Added a Codex-compatible endpoint for DDSHub at the same host as its Claude service
|
||||
- Base URL omits the `/v1` suffix because the gateway auto-routes OpenAI SDK paths
|
||||
|
||||
---
|
||||
|
||||
## Changed
|
||||
|
||||
### "Local Proxy Takeover" → "Local Routing"
|
||||
|
||||
- Unified the terminology across UI copy, README, and docs in all three locales
|
||||
- Functional behavior is unchanged
|
||||
|
||||
### Hermes `Auto` api_mode Removed
|
||||
|
||||
- Users must pick an explicit protocol; new deeplinks default to `chat_completions`
|
||||
- Eliminates URL-based heuristic surprises
|
||||
|
||||
### Hermes Provider Form
|
||||
|
||||
- Added an API mode dropdown and per-provider model editor
|
||||
- Binds per-provider models to the top-level `model:` when switching active providers
|
||||
|
||||
### Hermes Deep Config Delegation
|
||||
|
||||
- Deep YAML knobs are no longer duplicated in the CC Switch form — they are delegated to the Hermes Web UI via a direct launch action
|
||||
|
||||
### Hermes Toolbar Layout
|
||||
|
||||
- Swapped the Hermes Web UI button from `ExternalLink` to `LayoutDashboard` (clicking may spawn `hermes dashboard` rather than just opening a URL)
|
||||
- Moved MCP to the final toolbar slot so Hermes matches the Claude / Codex / Gemini / OpenCode layout
|
||||
|
||||
### `ANTHROPIC_REASONING_MODEL` Removed from Claude Quick-Set
|
||||
|
||||
- Decoupled the reasoning capability from model selection; the legacy field is no longer surfaced in the quick-set form
|
||||
|
||||
### Per-Provider Proxy Config Removed
|
||||
|
||||
- Consolidated into global Local Routing
|
||||
- Provider-level proxy toggle and associated storage are gone
|
||||
|
||||
### Unified Toolbar Icon Button Width
|
||||
|
||||
- Normalized icon-button widths across Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes panels for a consistent header look
|
||||
|
||||
### Rust Toolchain Pinned to 1.95
|
||||
|
||||
- Adopted clippy 1.95 suggestions across the workspace and pinned the toolchain to prevent nightly drift
|
||||
|
||||
### Tray Menu ID Constant
|
||||
|
||||
- The tray identifier moved from the hardcoded string `"main"` to a `TRAY_ID` constant (`"cc-switch"`) across all call sites (#1978, thanks @lidaxian121)
|
||||
|
||||
### Copilot Premium Consumption Deep Optimization
|
||||
|
||||
A systematic overhaul to reduce Copilot reverse-proxy premium interaction consumption across multiple dimensions:
|
||||
|
||||
- **Proactive Thinking Block Stripping Before Forwarding**: Anthropic's `thinking` / `redacted_thinking` blocks are rejected by OpenAI-compatible endpoints. Previously, the request failed upstream, burning one premium interaction before the `thinking_rectifier` could retry. A new proactive strip step (Copilot optimization pipeline step 3.5, after `tool_result` merging) eliminates that wasted interaction
|
||||
- **Request Classification Fix**: Messages containing `tool_result` are now classified as agent continuation instead of user-initiated, preventing every tool call from being falsely counted as a premium interaction
|
||||
- **Subagent Detection**: Identifies subagents via `__SUBAGENT_MARKER__` with `metadata._agent_` fallback, setting `x-interaction-type=conversation-subagent`
|
||||
- **Deterministic `x-interaction-id` Billing Merge**: Derives `x-interaction-id` from the session ID so multiple requests within the same session collapse into a single billing interaction
|
||||
- **Orphan `tool_result` Sanitization**: Cleans up orphan `tool_result` entries to prevent upstream errors that would trigger retries and duplicate billing
|
||||
- **Warmup Downgrade Enabled by Default**: Uses `gpt-5-mini` as the default downgrade model
|
||||
- **Optimization Pipeline Reorder**: classify → sanitize → merge → warmup, so classification sees raw `tool_result` semantics
|
||||
- Fixed a `CopilotOptimizerConfig` default-value inconsistency (unified to `gpt-5-mini`)
|
||||
|
||||
### Usage Script Intranet Support
|
||||
|
||||
- Removed private-IP / suspicious-hostname blocking from usage scripts, unblocking enterprise intranet, Docker, and self-hosted API endpoints
|
||||
- Built-in templates still enforce HTTPS (except localhost) and same-origin checks; custom templates remain user-controlled with those request-URL checks skipped
|
||||
|
||||
### Failover Queue Notes
|
||||
|
||||
- Provider notes now appear in failover queue selectors and queue rows for easier identification across multi-provider queues (#2138, thanks @Coconut-Fish)
|
||||
|
||||
---
|
||||
|
||||
## Fixed
|
||||
|
||||
### Header Auto-Compact Latching After Maximize
|
||||
|
||||
- The toolbar no longer stays compacted after maximize/restore; compaction now reevaluates on size changes
|
||||
|
||||
### Hermes YAML Pollution & OAuth MCP `auth` Drop
|
||||
|
||||
- Round-tripping through CC Switch no longer drops OAuth MCP `auth` blocks or pollutes unrelated YAML keys
|
||||
- Guard tests added via `tests/hermes_roundtrip.rs`
|
||||
|
||||
### Hermes Active Provider Display
|
||||
|
||||
- Hermes UI now correctly surfaces the active provider and wires add / enable / remove actions
|
||||
|
||||
### Hermes Provider Persistence
|
||||
|
||||
- Providers persist under `custom_providers:` so `api_mode` and `model` survive restarts and config reloads
|
||||
|
||||
### Hermes Health Check Borrowing OpenClaw Schema
|
||||
|
||||
- Hermes providers were routed through `check_additive_app_stream` (the OpenClaw dispatcher), which reads camelCase `baseUrl` / `apiKey` / `api` and surfaced "OpenClaw provider is missing baseUrl" even when every Hermes field was filled
|
||||
- Introduced `check_hermes_stream` with Hermes-specific extractors that map `api_mode` (`chat_completions` / `anthropic_messages` / `codex_responses`) to the matching `check_claude_stream` `api_format`; `bedrock_converse` returns as unsupported
|
||||
- `api_mode` is now resolved before URL / API key extraction, so `bedrock_converse` users see the real cause rather than a misleading "missing base_url"
|
||||
|
||||
### Usage Query Modal for Hermes & OpenClaw
|
||||
|
||||
- `getProviderCredentials` now reads flat `settingsConfig` fields for Hermes (snake_case `base_url` / `api_key`) and OpenClaw (camelCase `baseUrl` / `apiKey`), so the "official balance" template auto-selects for matching providers like SiliconFlow
|
||||
- Refactored the BALANCE and TOKEN_PLAN test paths to reuse the precomputed `providerCredentials` instead of re-reading `env.ANTHROPIC_*` directly, fixing the "empty key" error for non-Claude apps even when the key was configured
|
||||
|
||||
### Codex `cache_control` Preservation
|
||||
|
||||
- Preserve `cache_control` when merging system prompts during Codex format conversion (#1946, thanks @yovinchen)
|
||||
|
||||
### Claude Prompt Cache Key Leak
|
||||
|
||||
- Stopped sending prompt cache keys during Claude chat conversions (#2003, thanks @yovinchen)
|
||||
|
||||
### Proxy Hop-by-Hop Header Stripping
|
||||
|
||||
- Strip hop-by-hop response headers (Connection, Keep-Alive, Transfer-Encoding, etc.) per RFC 7230 (#2060, thanks @yovinchen)
|
||||
|
||||
### Permissive Proxy CORS Removed
|
||||
|
||||
- Removed the permissive CORS layer from the proxy (#1915, thanks @zerone0x)
|
||||
|
||||
### Backend Error Details in Proxy Toast
|
||||
|
||||
- Surface backend error payload details in proxy-related toast messages instead of a generic failure string
|
||||
|
||||
### Usage Log Deduplication
|
||||
|
||||
- Deduplicated proxy and session-log usage records so the same request is no longer double-counted
|
||||
- Synced the request log time range with the dashboard's 1d / 7d / 30d selector
|
||||
|
||||
### Common Config Checkbox Persistence
|
||||
|
||||
- Checkbox state for Claude / Codex / Gemini common-config toggles now persists correctly across reopens (#2191, thanks @zxZeng)
|
||||
|
||||
### Claude Plugin `settings.json` Sync
|
||||
|
||||
- Editing the current provider now syncs back to `settings.json` for the Claude plugin path (#1905, thanks @chengww5217)
|
||||
|
||||
### Google Official Gemini Env Preservation
|
||||
|
||||
- Saving the Google Official Gemini provider no longer clobbers the `env` block
|
||||
|
||||
### OpenCode JSON5 Parser for Trailing Commas
|
||||
|
||||
- OpenCode config reads now tolerate trailing commas via a JSON5 parser (#2023, thanks @wwminger)
|
||||
|
||||
### Preset Refreshes
|
||||
|
||||
- Refreshed stale context windows for DeepSeek and Claude 1M
|
||||
- Refreshed stale model IDs; backfilled Hermes model lists
|
||||
- Fixed the Nous endpoint and replaced the Hermes placeholder icon with Nous brand artwork
|
||||
- Pruned unused official Hermes presets
|
||||
|
||||
### Auto-Expand Collapsed Messages on Search Hit
|
||||
|
||||
- Collapsed messages now auto-expand when a search match lands inside hidden content
|
||||
|
||||
### Unknown Subscription Quota Tiers Hidden
|
||||
|
||||
- Provider cards no longer render unknown subscription quota tiers
|
||||
|
||||
### Weekly Limit Label Unified
|
||||
|
||||
- Aligned the `weekly_limit` tier label with the official 7-day naming across locales
|
||||
|
||||
### Root-Level Skill Repo Install
|
||||
|
||||
- Fixed skill installation when the repository root itself is a skill
|
||||
|
||||
### Session ID Parsing Clippy
|
||||
|
||||
- Removed a redundant closure in session ID parsing (clippy warning)
|
||||
|
||||
### Stream Check Default Models Refresh
|
||||
|
||||
- Updated stream-check default probe models to match each vendor's current lineup
|
||||
|
||||
### Skills Import Sync
|
||||
|
||||
- Imported Skills are now immediately synced into enabled app directories instead of only being recorded in the database (#2101, thanks @yaoguohh)
|
||||
- The UI no longer shows "installed" while the target app directory is missing the skill
|
||||
|
||||
### Ghostty Session Restore
|
||||
|
||||
- Fixed Ghostty session restore launch by using shell execution with `--working-directory` (#1976, thanks @Suda202)
|
||||
- Avoids `cwd` escaping issues when the path contains spaces or special characters
|
||||
|
||||
---
|
||||
|
||||
## Docs
|
||||
|
||||
### README Sponsor Updates
|
||||
|
||||
- Updated SiliconFlow signup bonus to ¥16
|
||||
- Trimmed the SSSAiCode sponsor blurb
|
||||
- Updated partner logos
|
||||
- Added LemonData as a new sponsor
|
||||
|
||||
### Global Proxy Hint Clarified
|
||||
|
||||
- Clarified the global proxy hint about local routing across all three locales
|
||||
|
||||
### Takeover → Routing Rename
|
||||
|
||||
- Renamed takeover docs to routing and updated anchors across all languages
|
||||
|
||||
### PIPELLM Website URL
|
||||
|
||||
- Updated the PIPELLM sponsor website URL to `code.pipellm.ai`
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Breaking Changes
|
||||
|
||||
### Hermes requires explicit `api_mode`
|
||||
|
||||
- The `Auto` mode is gone; imported or deeplinked providers default to `chat_completions`
|
||||
- Users with prior `Auto` configs will be prompted to pick a protocol
|
||||
|
||||
### `ANTHROPIC_REASONING_MODEL` removed from Claude quick-set
|
||||
|
||||
- The legacy field is no longer exposed; existing settings are cleaned up automatically
|
||||
|
||||
### Per-provider proxy configuration removed
|
||||
|
||||
- Migrate to the global Local Routing setting
|
||||
- Existing per-provider proxy values are ignored
|
||||
|
||||
### Database schema v9 → v10
|
||||
|
||||
- Adds `enabled_hermes` columns to `mcp_servers` and `skills`
|
||||
- Auto-migrated with `DEFAULT 0`; no data loss
|
||||
|
||||
### Pricing table reseeded (v8 → v9)
|
||||
|
||||
- The `model_pricing` table is cleared and reseeded on first launch to pick up new models and corrected prices
|
||||
|
||||
### XCodeAPI preset removed
|
||||
|
||||
- Users of the XCodeAPI preset should switch to another provider
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Risk Notice
|
||||
|
||||
This release inherits the risk notices originally introduced in v3.12.3 / v3.13.0 for reverse-proxy-style features.
|
||||
|
||||
**GitHub Copilot Reverse Proxy**: Using Copilot's reverse-proxy path may violate GitHub / Microsoft's terms of service. See [v3.12.3 release notes](v3.12.3-en.md#️-risk-notice).
|
||||
|
||||
**Codex OAuth Reverse Proxy**: Using the Codex OAuth reverse proxy with a ChatGPT subscription may violate OpenAI's terms of service. See [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice).
|
||||
|
||||
By enabling these features, users **accept all associated risks**. CC Switch is not responsible for any account restrictions, warnings, or service suspensions that result from using these features.
|
||||
|
||||
---
|
||||
|
||||
## Download & Installation
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download the appropriate version.
|
||||
|
||||
### System Requirements
|
||||
|
||||
| OS | Minimum Version | Architecture |
|
||||
| ------- | ----------------------- | ----------------------------------- |
|
||||
| Windows | Windows 10 or later | x64 |
|
||||
| macOS | macOS 12 (Monterey) or later | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | See table below | x64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| File | Description |
|
||||
| ---------------------------------------- | ----------------------------------------------- |
|
||||
| `CC-Switch-v3.14.0-Windows.msi` | **Recommended** - MSI installer, supports auto-update |
|
||||
| `CC-Switch-v3.14.0-Windows-Portable.zip` | Portable, extract and run, no registry writes |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| -------------------------------- | -------------------------------------------------------- |
|
||||
| `CC-Switch-v3.14.0-macOS.dmg` | **Recommended** - DMG installer, drag into Applications |
|
||||
| `CC-Switch-v3.14.0-macOS.zip` | Extract and drag into Applications, Universal Binary |
|
||||
| `CC-Switch-v3.14.0-macOS.tar.gz` | For Homebrew installation and auto-update |
|
||||
|
||||
> macOS builds are Apple code-signed and notarized — install directly.
|
||||
|
||||
### Homebrew (macOS)
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
| Distribution | Recommended | Installation |
|
||||
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| 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, or use AUR |
|
||||
| Other distros / not sure | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
@@ -0,0 +1,469 @@
|
||||
# CC Switch v3.14.0
|
||||
|
||||
> Hermes Agent が 6 番目の管理対象アプリに、Claude Opus 4.7 をプリセットマトリクス全体へ展開、Gemini Native API プロキシ、「Local Routing」への名称統一、アプリケーションレベルのウィンドウコントロール
|
||||
|
||||
**[中文版 →](v3.14.0-zh.md) | [English →](v3.14.0-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.14.0 は、**Hermes Agent を 6 番目の一等管理対象アプリケーション**として CC Switch に取り込み、**Claude Opus 4.7** をアグリゲーターおよび Bedrock プリセットのマトリクス全体に展開することを中心に据えた大型リリースです。Hermes サポートは、データベース v9 → v10 マイグレーション、完全な Rust コマンド面、アトミックバックアップ付きの YAML ベースな `~/.hermes/config.yaml` 読み書き、MCP 同期、Skills 同期、SQLite + JSONL セッション管理、および Memory エディターを含む専用のフロントエンドパネルをカバーします。Hermes Agent 0.10.0 スキーマに整合する 4 つの API プロトコル（`chat_completions`、`anthropic_messages`、`codex_responses`、`bedrock_converse`）すべてを選択可能です。ユーザーが直接記述した `providers:` dict のエントリは読み取り専用カードとして表示され、深い YAML 設定は Hermes Web UI に委譲されます。
|
||||
|
||||
Hermes に加えて、本リリースでは **Gemini Native API プロキシ**（`api_format = "gemini_native"`）を追加し、プロキシがリクエストを Google の `generateContent` エンドポイントに直接転送できるようにしました（完全なストリーミング、スキーマ変換、シャドウリクエストをサポート）。また、旧「Local Proxy Takeover」を三言語の UI / README / ドキュメント全体で **Local Routing** に統一リネームし、コンポジターが描画するボタンが無反応になり得る Linux Wayland などのシーンで、CC Switch が自前で最小化 / 最大化 / 閉じるボタンを描画できるオプション「**アプリケーションレベルのウィンドウコントロール**」を導入しました。さらにリリース直前に、ツールバーからの `hermes dashboard` 直接起動、LemonData の全アプリプリセット、DDSHub の Codex エンドポイント、および複数の Hermes ヘルスチェックと Usage モーダルの修正が追加されました。
|
||||
|
||||
セッション側では、`@tanstack/react-virtual` によるセッションリストの**仮想化**で数千件のレコードを持つ長い会話も滑らかにスクロールでき、長いメッセージはデフォルトで折り畳まれます。Usage ダッシュボードには**日付範囲ピッカー**（今日 / 1d / 7d / 14d / 30d + カスタム日時カレンダー）とページジャンプ入力が追加され、**Stream Check エラー分類**は色分けされたトーストで提示され、デフォルトの探索モデルが更新され、「モデルが見つからない」レスポンスを個別に識別するようになりました。また、Local Routing が有効な間に公式プロバイダーへの切り替えを**強制的にブロック**する保護を追加し、公式 API トラフィックがローカルプロキシを経由することによるアカウント停止リスクを防ぎます。Pricing データベースは v8 → v9 で再シードされ、約 50 件の新しいモデルエントリ（Claude 4.7、Opus 4.7 Adaptive Thinking、Grok 4、Qwen 3.5/3.6、MiniMax M2.5/M2.7、Doubao Seed 2.0 系列、GLM-5/5.1 など）を追加し、いくつかの古い価格を修正しました。
|
||||
|
||||
**リリース日**: 2026-04-21
|
||||
|
||||
**更新規模**: 100 commits | 219 files changed | +20,548 / -3,569 lines
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **Hermes Agent サポート（6 番目の管理対象アプリ）**: データベース v9 → v10 マイグレーション、完全な Rust コマンド面、アトミックバックアップ付き YAML 読み書き、MCP 同期、Skills 同期、SQLite + JSONL セッション管理、専用フロントエンドパネル、4 つの API プロトコル（`chat_completions` / `anthropic_messages` / `codex_responses` / `bedrock_converse`）
|
||||
- **Claude Opus 4.7 の全面展開**: 適応的思考のホワイトリスト、百万トークン単位の価格シード、Bedrock SKU（`anthropic.claude-opus-4-7` / `global.anthropic.claude-opus-4-7`、旧 `-v1` サフィックスを廃止）、全アグリゲーター / Bedrock プリセットを Opus 4.7 をデフォルト Opus モデルに移行
|
||||
- **Claude `max` エフォートティア**: エフォートのドロップダウンを `high` から `max` に引き上げ
|
||||
- **Gemini Native API プロキシ**: 新しい `api_format = "gemini_native"` により、プロキシが Google の `generateContent` に直接転送可能に（完全なストリーミング / スキーマ変換 / シャドウリクエスト対応）
|
||||
- **GitHub Copilot Enterprise Server**: Copilot ベースの Claude プロバイダーに GHES 認証とエンドポイント設定を追加
|
||||
- **Copilot 交互消費の大幅最適化**: 転送前の thinking ブロック主動削除、`tool_result` メッセージ分類修正、subagent 検出、`x-interaction-id` 課金マージ、孤立 `tool_result` のサニタイズ、Warmup ダウングレードのデフォルト有効化など、premium 交互消費を系統的に削減
|
||||
- **セッションリスト仮想化**: 長い会話が滑らかにスクロール。長いメッセージはデフォルトで折り畳まれ、テキストレイアウトコストを削減
|
||||
- **Codex / OpenClaw セッションタイトル抽出**: 意味のあるタイトルを自動抽出（2 行表示）、OpenClaw の `message_id` 末尾ノイズを除去
|
||||
- **Usage 日付範囲ピッカー**: Today / 1d / 7d / 14d / 30d プリセットタブ + カスタム日時カレンダー。ページネーションリストにページジャンプ入力
|
||||
- **Stream Check エラー分類**: エラーを分類し色分けトーストで提示。デフォルト探索モデル更新。「モデルが見つからない」レスポンスを明示的に検出
|
||||
- **Local Routing 有効時の公式プロバイダー切り替えブロック**: 公式 API トラフィックをローカルプロキシ経由で流すとアカウント停止のリスクがあるため、切り替えを強制ブロックして警告トーストを表示
|
||||
- **Pricing データベース刷新（v8 → v9）**: 約 50 件の新しいモデルエントリを追加し、古い価格を修正
|
||||
- **アプリケーションレベルのウィンドウコントロール**: CC Switch が自前で最小化 / 最大化トグル / 閉じるボタンを描画するオプション設定。Linux Wayland での体験を大きく改善
|
||||
- **統一 Skills 管理への Hermes 追加**: Skill のインストール / 有効化 / フィルターが Hermes をカバー
|
||||
- **Hermes / OpenClaw 設定ディレクトリのカスタマイズ**: 設定で `~/.hermes/config.yaml` や `openclaw.json` のカスタム位置を指定可能
|
||||
- **ツールバーからの Hermes Dashboard 起動**: Hermes Web UI のプローブに失敗した際、ツールバーエントリからユーザーの優先ターミナルで `hermes dashboard` を実行可能
|
||||
- **新パートナープリセット**: LemonData を全 6 アプリにわたって追加、DDSHub の Codex エンドポイント、StepFun Step Plan
|
||||
|
||||
---
|
||||
|
||||
## 新機能
|
||||
|
||||
### Hermes Agent サポート（6 番目の管理対象アプリ）
|
||||
|
||||
CC Switch は Hermes Agent を Claude / Codex / Gemini / OpenCode / OpenClaw と並ぶ一等の管理対象アプリとして初めてサポートします。
|
||||
|
||||
- **データベースマイグレーション v9 → v10**: `mcp_servers` と `skills` テーブルに `enabled_hermes` カラムを追加（`DEFAULT 0`、自動マイグレーション、データ損失なし）
|
||||
- **YAML 設定の読み書き**: `~/.hermes/config.yaml` をアトミックバックアップ付きで読み書き。`tests/hermes_roundtrip.rs` が OAuth MCP `auth` ブロックの消失や無関係なキーの汚染を防止
|
||||
- **4 つの API プロトコル**: Hermes Agent 0.10.0 と整合する `chat_completions` / `anthropic_messages` / `codex_responses` / `bedrock_converse`。新しいディープリンクはデフォルトで `chat_completions`
|
||||
- **ユーザー `providers:` dict の読み取り専用表示**: YAML に手書きされたプロバイダーエントリは CC Switch で読み取り専用カードとして表示され、深い設定は Hermes Web UI に委譲
|
||||
- **加算的な切り替え**: Claude / Codex の「上書き」型切り替えと異なり、Hermes ではすべてのプロバイダーが同じ YAML に共存
|
||||
|
||||
### Hermes Memory パネル
|
||||
|
||||
- `MEMORY.md` / `USER.md` を直接編集できる Memory パネルを追加（有効化スイッチ、文字数制限、ライブ保存フロー付き）
|
||||
- Hermes の Prompts エントリを置き換え
|
||||
|
||||
### Hermes プロバイダープリセット（約 50 個）
|
||||
|
||||
- Nous Research、Shengsuanyun（胜算云）、OpenRouter、DeepSeek、Together AI、StepFun、Zhipu GLM、Bailian（百炼）、Kimi、MiniMax、DouBao（豆包）、BaiLing（百灵）、ModelScope（魔搭）、KAT-Coder、PackyCode、Cubence、AIGoCode、RightCode、AICodeMirror、AICoding、CrazyRouter、SSSAiCode、Micu、CTok.ai、DDSHub、E-FlowCode、LionCCAPI、PIPELLM、Compshare、SiliconFlow、AiHubMix、DMXAPI、TheRouter、Novita、Nvidia、Xiaomi MiMo をカバー
|
||||
|
||||
### ツールバーからの Hermes Dashboard 起動
|
||||
|
||||
- Hermes Web UI のプローブに失敗した際、ツールバーエントリがユーザーの優先ターミナルで `hermes dashboard` を実行する確認ダイアログを表示
|
||||
- 一時 bash / batch スクリプト経由で起動。`hermes dashboard` 自身が準備完了後にブラウザを開くため、ポーリングは不要
|
||||
- Memory パネルと Health バナーは既存のトースト動作を維持
|
||||
- オフラインのトーストにあった古い `hermes web` のヒントも修正（正しいコマンドは `hermes dashboard`）
|
||||
- Linux ターミナル検出の順序を変更し、`/usr/bin`、`/bin`、`/usr/local/bin` を stat する前に `which` を試すように
|
||||
|
||||
### Claude Opus 4.7 サポート
|
||||
|
||||
- Claude Opus 4.7 を追加。適応的思考のホワイトリスト、百万トークン単位の価格シード、Bedrock SKU（`anthropic.claude-opus-4-7` / `global.anthropic.claude-opus-4-7`、旧 `-v1` サフィックスを廃止）
|
||||
- 全アグリゲーター / Bedrock プリセットをデフォルト Opus モデルとして Opus 4.7 に移行
|
||||
|
||||
### Claude `max` エフォートティア
|
||||
|
||||
- Claude エフォートドロップダウンを `high` から `max` に引き上げ、より強力な推論容量を解放
|
||||
|
||||
### Gemini Native API プロキシ
|
||||
|
||||
- 新しい `api_format = "gemini_native"` により、プロキシが Google の `generateContent` API に直接転送可能 (#1918, 感謝 @yovinchen)
|
||||
- 完全なストリーミング、スキーマ変換、シャドウリクエストに対応
|
||||
- proxy providers モジュール下に `gemini_url.rs`、`gemini_schema.rs`、`gemini_shadow.rs`、`streaming_gemini.rs`、`transform_gemini.rs` を追加
|
||||
|
||||
### GitHub Copilot Enterprise Server（GHES）
|
||||
|
||||
- Copilot ベースの Claude プロバイダーに GHES 認証とエンドポイント設定を追加 (#2175, 感謝 @hotelbe)
|
||||
|
||||
### セッションリスト仮想化
|
||||
|
||||
- `@tanstack/react-virtual` によりセッションリストを仮想化。数千件のレコードを持つ長い会話も滑らかにスクロール
|
||||
- 長いセッションメッセージはデフォルトで折り畳まれ、テキストレイアウトコストを削減
|
||||
|
||||
### Codex / OpenClaw セッションタイトル抽出
|
||||
|
||||
- Codex と OpenClaw セッションから意味のあるタイトルを自動抽出し、2 行表示
|
||||
- OpenClaw の `message_id` 末尾ノイズを除去
|
||||
|
||||
### Usage 日付範囲ピッカー
|
||||
|
||||
- Usage ダッシュボードに日付範囲セレクターを追加。プリセットタブ（Today / 1d / 7d / 14d / 30d）+ カスタム日時カレンダー (#2002, 感謝 @yovinchen)
|
||||
- ページネーションリストにページジャンプ入力を追加
|
||||
|
||||
### モデルマッピングのクイック入力
|
||||
|
||||
- プロバイダーフォームのモデルマッピングフィールドの横にクイック入力ボタンを追加し、編集を高速化 (#2179, 感謝 @lispking)
|
||||
|
||||
### Stream Check エラー分類
|
||||
|
||||
- Stream Check エラーを分類し、色分けトーストとして提示
|
||||
- デフォルトの探索モデルを各ベンダーの現行ラインナップに合わせて更新
|
||||
- 「モデルが見つからない」レスポンスを明示的に検出
|
||||
|
||||
### Local Routing 有効時の公式プロバイダー切り替えブロック
|
||||
|
||||
- Local Routing が有効な状態で公式プロバイダーに切り替えようとすると、強制的にブロックされ警告トーストが表示される
|
||||
- 理由: 公式 API トラフィックをローカルプロキシ経由で流すとアカウント停止のリスクがあるため
|
||||
|
||||
### Pricing データベース刷新（v8 → v9）
|
||||
|
||||
- マイグレーション時に定価テーブルを再シード
|
||||
- Claude 4.7、Opus 4.7 Adaptive Thinking、Grok 4、Qwen 3.5/3.6、MiniMax M2.5/M2.7、Doubao Seed 2.0 系列、GLM-5/5.1 などを含む約 50 件の新しいモデルエントリを追加
|
||||
- DeepSeek、Kimi K2.5 などの古い価格を修正
|
||||
|
||||
### アプリケーションレベルのウィンドウコントロール
|
||||
|
||||
- CC Switch が自前で最小化 / 最大化トグル / 閉じるボタンを描画するオプション設定を追加。システム装飾の代わりに使用 (#1119, 感謝 @git1677967754)
|
||||
- コンポジター描画ボタンが無反応になり得る Linux Wayland での体験を大きく改善
|
||||
|
||||
### 統一 Skills 管理への Hermes 追加
|
||||
|
||||
- 統一 Skills サーフェスに Hermes を追加
|
||||
- Skill のインストール / 有効化 / フィルターが、Claude / Codex / Gemini / OpenCode / OpenClaw と並んで Hermes アプリをカバー
|
||||
|
||||
### OpenClaw 設定ディレクトリのカスタマイズ
|
||||
|
||||
- CC Switch が参照する `openclaw.json` のカスタム位置を設定できるオプションを追加 (#1518, 感謝 @mrFranklin)
|
||||
|
||||
### Hermes 設定ディレクトリのカスタマイズ
|
||||
|
||||
- CC Switch が参照する `~/.hermes/config.yaml` のカスタム位置を設定できるオプションを追加。データ駆動 dispatch でサポート
|
||||
|
||||
### StepFun Step Plan プリセット
|
||||
|
||||
- StepFun Step Plan（EN / ZH）プロバイダープリセットを追加 (#2155, 感謝 @hengm3467)
|
||||
|
||||
### New API 用量スクリプトテンプレート
|
||||
|
||||
- New API の用量スクリプトテンプレートに User-Agent ヘッダーを追加し、上流互換性を向上
|
||||
|
||||
### LemonData プロバイダープリセット（全 6 アプリ）
|
||||
|
||||
- LemonData をサードパーティパートナープリセットとして Claude、Codex、Gemini、OpenCode、OpenClaw、Hermes の全 6 アプリに登録
|
||||
- アイコンアセットと zh / en / ja 三言語のパートナー推奨文面を追加
|
||||
- Claude プリセットは `ANTHROPIC_API_KEY` 認証を使用。OpenAI 互換アプリは `gpt-5.4` をターゲット
|
||||
|
||||
### DDSHub Codex プリセット
|
||||
|
||||
- DDSHub の Codex 互換エンドポイントを追加（Claude サービスと同じホスト）
|
||||
- ベース URL は `/v1` サフィックスを省略（ゲートウェイが OpenAI SDK パスを自動ルーティング）
|
||||
|
||||
---
|
||||
|
||||
## 変更
|
||||
|
||||
### 「Local Proxy Takeover」→「Local Routing」
|
||||
|
||||
- 三言語の UI 文言、README、ドキュメント全体で用語を統一リネーム
|
||||
- 機能的な動作は変更なし
|
||||
|
||||
### Hermes `Auto` api_mode の削除
|
||||
|
||||
- ユーザーは明示的にプロトコルを選択する必要あり。新しいディープリンクはデフォルトで `chat_completions`
|
||||
- URL ベースのヒューリスティックによる意外な挙動を排除
|
||||
|
||||
### Hermes プロバイダーフォーム
|
||||
|
||||
- API モードドロップダウンとプロバイダー単位のモデルエディターを追加
|
||||
- アクティブなプロバイダーを切り替える際、プロバイダー単位のモデルをトップレベルの `model:` にバインド
|
||||
|
||||
### Hermes 深い設定の委譲
|
||||
|
||||
- 深い YAML 設定は CC Switch フォームで重複させず、「Hermes Web UI を起動」ボタン経由で Web UI に直接委譲
|
||||
|
||||
### Hermes ツールバーレイアウト
|
||||
|
||||
- Hermes Web UI ボタンのアイコンを `ExternalLink` から `LayoutDashboard` に変更（クリック時に単に URL を開くのではなく `hermes dashboard` を起動する場合があるため、パネル型アイコンのほうが意味的に正確）
|
||||
- MCP をツールバーの末尾に移動し、Hermes のレイアウトを Claude / Codex / Gemini / OpenCode と揃える
|
||||
|
||||
### Claude Quick-Set から `ANTHROPIC_REASONING_MODEL` を削除
|
||||
|
||||
- 推論能力とモデル選択を分離。レガシーフィールドは Quick-Set フォームから除外
|
||||
|
||||
### プロバイダー単位のプロキシ設定を削除
|
||||
|
||||
- グローバルな Local Routing に統合
|
||||
- プロバイダー単位のプロキシトグルと関連ストレージは削除済み
|
||||
|
||||
### ツールバーアイコンボタン幅の統一
|
||||
|
||||
- Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes パネルの間でアイコンボタン幅を正規化し、ヘッダーの見た目を統一
|
||||
|
||||
### Rust Toolchain を 1.95 にピン留め
|
||||
|
||||
- ワークスペース全体で clippy 1.95 の提案を採用し、nightly ドリフトを防ぐためツールチェーンをピン留め
|
||||
|
||||
### トレイメニュー ID 定数
|
||||
|
||||
- トレイ識別子をハードコーディング文字列 `"main"` から `TRAY_ID` 定数（`"cc-switch"`）に移行。すべての呼び出し箇所で同期 (#1978, 感謝 @lidaxian121)
|
||||
|
||||
### Copilot 交互消費の大幅最適化
|
||||
|
||||
Copilot リバースプロキシの premium 交互消費を削減するための系統的な最適化。以下の複数の改善をカバー:
|
||||
|
||||
- **転送前に thinking ブロックを主動削除**: Anthropic の `thinking` / `redacted_thinking` ブロックは OpenAI 互換エンドポイントに拒否される。従来は上流でリクエストが失敗して premium 交互を 1 回消費した後、`thinking_rectifier` によってリトライされていた。新しい主動削除ステップ（Copilot 最適化パイプラインの 3.5 ステップ目、`tool_result` マージ後）により、この無駄な premium 消費を直接解消
|
||||
- **リクエスト分類の修正**: `tool_result` を含むメッセージをユーザー発起の新規リクエストではなく、エージェント継続として分類。ツール呼び出しが毎回 premium 交互としてカウントされる問題を防止
|
||||
- **subagent 検出**: `__SUBAGENT_MARKER__` と `metadata._agent_` フォールバックで subagent を識別し、`x-interaction-type=conversation-subagent` を設定
|
||||
- **決定論的 `x-interaction-id` による課金マージ**: セッション ID から `x-interaction-id` を導出し、同一セッション内の複数リクエストを 1 回の課金交互に統合
|
||||
- **孤立 `tool_result` のサニタイズ**: 孤立した `tool_result` を整理し、上流エラーによるリトライおよび重複課金を防止
|
||||
- **Warmup ダウングレードをデフォルトで有効化**: `gpt-5-mini` をデフォルトのダウングレードモデルとして使用
|
||||
- **最適化パイプラインの並び替え**: classify → sanitize → merge → warmup の順序で、分類が生の `tool_result` セマンティクスを参照可能に
|
||||
- `CopilotOptimizerConfig` のデフォルト値の不一致を修正（`gpt-5-mini` に統一）
|
||||
|
||||
### 用量スクリプトのイントラネットサポート
|
||||
|
||||
- 用量スクリプトからプライベート IP / 不審なホスト名のブロッキングを削除し、エンタープライズイントラネット、Docker、自己ホスト API エンドポイントを解放
|
||||
- ビルトインテンプレートは引き続き HTTPS（localhost を除く）と同一オリジンチェックを強制。カスタムテンプレートはユーザー制御のまま、リクエスト URL のチェックをスキップ
|
||||
|
||||
### Failover キューの備考表示
|
||||
|
||||
- プロバイダーの備考が failover キューセレクターとキュー行に表示され、マルチプロバイダーキューでの識別が容易に (#2138, 感謝 @Coconut-Fish)
|
||||
|
||||
---
|
||||
|
||||
## バグ修正
|
||||
|
||||
### 最大化後のツールバー自動折り畳みラッチ
|
||||
|
||||
- ウィンドウの最大化 / 復元後、ツールバーが折り畳まれたままになる問題を修正。折り畳み判定はサイズ変更時に再評価される
|
||||
|
||||
### Hermes YAML 汚染と OAuth MCP `auth` 消失
|
||||
|
||||
- CC Switch 経由でラウンドトリップしても OAuth MCP `auth` ブロックが消失したり、無関係な YAML キーが汚染されたりしなくなった
|
||||
- `tests/hermes_roundtrip.rs` をガードテストとして追加
|
||||
|
||||
### Hermes アクティブプロバイダー表示
|
||||
|
||||
- Hermes UI がアクティブプロバイダーを正しく表示するようになり、追加 / 有効化 / 削除アクションが正しく動作
|
||||
|
||||
### Hermes プロバイダーの永続化
|
||||
|
||||
- プロバイダーは `custom_providers:` の下に永続化され、`api_mode` と `model` が再起動 / 設定再読み込みを生き延びる
|
||||
|
||||
### Hermes ヘルスチェックが OpenClaw のスキーマを流用していた問題
|
||||
|
||||
- 以前 Hermes プロバイダーは `check_additive_app_stream`（OpenClaw のディスパッチャー）にルーティングされており、これは camelCase の `baseUrl` / `apiKey` / `api` を読むため、Hermes フィールドをすべて記入しても "OpenClaw provider is missing baseUrl" と表示されていた
|
||||
- `check_hermes_stream` を導入し、Hermes 専用のエクストラクターで `api_mode`（`chat_completions` / `anthropic_messages` / `codex_responses`）を対応する `check_claude_stream` の `api_format` にマッピング。`bedrock_converse` は非対応として返す
|
||||
- URL / API キーの抽出前に `api_mode` を解決することで、`bedrock_converse` を選んだユーザーには「missing base_url」という誤解を招くメッセージではなく実際の原因が表示される
|
||||
|
||||
### Hermes / OpenClaw 向け Usage クエリモーダル
|
||||
|
||||
- `getProviderCredentials` が Hermes（snake_case の `base_url` / `api_key`）と OpenClaw（camelCase の `baseUrl` / `apiKey`）のフラットな `settingsConfig` フィールドを読むようになり、SiliconFlow などマッチするプロバイダーで「official balance」テンプレートが自動選択される
|
||||
- BALANCE と TOKEN_PLAN テストパスをリファクタリングし、`env.ANTHROPIC_*` を直接再読するのではなく、事前計算された `providerCredentials` を再利用するように変更。これにより非 Claude アプリでキーが設定されていても「empty key」エラーが出ていた問題を修正
|
||||
|
||||
### Codex `cache_control` 保持
|
||||
|
||||
- Codex フォーマット変換中に system prompt をマージする際の `cache_control` を保持 (#1946, 感謝 @yovinchen)
|
||||
|
||||
### Claude プロンプトキャッシュキーのリーク
|
||||
|
||||
- Claude chat 変換時にプロンプトキャッシュキーを送信しないように修正 (#2003, 感謝 @yovinchen)
|
||||
|
||||
### プロキシ Hop-by-Hop レスポンスヘッダーの削除
|
||||
|
||||
- RFC 7230 に従ってプロキシレスポンスの hop-by-hop ヘッダー（Connection、Keep-Alive、Transfer-Encoding など）を削除 (#2060, 感謝 @yovinchen)
|
||||
|
||||
### プロキシの寛容な CORS レイヤー削除
|
||||
|
||||
- プロキシの寛容な CORS レイヤーを削除 (#1915, 感謝 @zerone0x)
|
||||
|
||||
### プロキシトーストでのバックエンドエラー詳細表示
|
||||
|
||||
- プロキシ関連のトーストメッセージで、汎用的な失敗文字列ではなくバックエンドのエラーペイロードの詳細を表示
|
||||
|
||||
### Usage ログの重複排除
|
||||
|
||||
- プロキシとセッションログの用量レコードを重複排除し、同じリクエストが二重にカウントされないように修正
|
||||
- リクエストログの時間範囲をダッシュボードの 1d / 7d / 30d セレクターと同期
|
||||
|
||||
### Common Config チェックボックスの永続化
|
||||
|
||||
- Claude / Codex / Gemini の common-config トグルのチェック状態が再オープンをまたいで正しく保持されるように修正 (#2191, 感謝 @zxZeng)
|
||||
|
||||
### Claude プラグイン `settings.json` 同期
|
||||
|
||||
- 現在のプロバイダーを編集すると、Claude プラグインパスの `settings.json` に同期されるように修正 (#1905, 感謝 @chengww5217)
|
||||
|
||||
### Google Official Gemini の env 保持
|
||||
|
||||
- Google Official Gemini プロバイダーを保存しても `env` ブロックが消えないように修正
|
||||
|
||||
### OpenCode の JSON5 による末尾カンマ解析
|
||||
|
||||
- OpenCode 設定読み取りが JSON5 パーサーにより末尾カンマを許容するように修正 (#2023, 感謝 @wwminger)
|
||||
|
||||
### プリセットの刷新
|
||||
|
||||
- DeepSeek と Claude 1M の古いコンテキストウィンドウを刷新
|
||||
- 古いモデル ID を刷新。Hermes のモデルリストをバックフィル
|
||||
- Nous エンドポイントを修正し、Hermes のプレースホルダーアイコンを Nous ブランドのアートワークに置き換え
|
||||
- 未使用の公式 Hermes プリセットを整理
|
||||
|
||||
### 検索ヒット時の折り畳みメッセージの自動展開
|
||||
|
||||
- 隠されたコンテンツ内部で検索マッチが発生した場合、折り畳みメッセージを自動展開してマッチを示す
|
||||
|
||||
### 不明なサブスクリプション配額ティアの非表示
|
||||
|
||||
- プロバイダーカードは不明なサブスクリプション配額ティアを表示しないように変更
|
||||
|
||||
### weekly_limit ラベルの統一
|
||||
|
||||
- `weekly_limit` ティアラベルを公式の「7 日」命名にロケール間で揃えた
|
||||
|
||||
### ルートレベルの Skill リポジトリインストール
|
||||
|
||||
- リポジトリのルート自体が skill の場合のインストール失敗を修正
|
||||
|
||||
### Session ID 解析の clippy 警告
|
||||
|
||||
- session ID 解析内の冗長なクロージャを削除（clippy 警告）
|
||||
|
||||
### Stream Check デフォルトモデルの刷新
|
||||
|
||||
- Stream Check のデフォルト探索モデルを各ベンダーの現行ラインナップに合わせて更新
|
||||
|
||||
### Skills インポートの同期
|
||||
|
||||
- インポートされた Skills はデータベースに記録されるだけでなく、有効化されたアプリディレクトリにも即座に同期されるように変更 (#2101, 感謝 @yaoguohh)
|
||||
- UI が「インストール済み」と表示しているのに対象アプリディレクトリに skill が存在しない状態を解消
|
||||
|
||||
### Ghostty セッション復元
|
||||
|
||||
- Ghostty セッション復元の起動を `--working-directory` 付きのシェル実行に変更 (#1976, 感謝 @Suda202)
|
||||
- パスにスペースや特殊文字が含まれる場合の `cwd` エスケープ問題を回避
|
||||
|
||||
---
|
||||
|
||||
## ドキュメント
|
||||
|
||||
### README スポンサー更新
|
||||
|
||||
- SiliconFlow のサインアップボーナスを ¥16 に更新
|
||||
- SSSAiCode のスポンサー文面を簡潔化
|
||||
- パートナーロゴを更新
|
||||
- 新しいスポンサーとして LemonData を追加
|
||||
|
||||
### グローバルプロキシヒントの明確化
|
||||
|
||||
- 三言語でグローバルプロキシと Local Routing の関係を明確化
|
||||
|
||||
### Takeover → Routing ドキュメントのリネーム
|
||||
|
||||
- テイクオーバー関連ドキュメントを三言語で routing にリネームし、アンカーを同期更新
|
||||
|
||||
### PIPELLM ウェブサイト URL
|
||||
|
||||
- PIPELLM スポンサーのウェブサイト URL を `code.pipellm.ai` に更新
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 重要な変更（Breaking）
|
||||
|
||||
### Hermes は明示的な `api_mode` が必須
|
||||
|
||||
- `Auto` モードは廃止。インポートまたはディープリンクで取得したプロバイダーはデフォルトで `chat_completions`
|
||||
- 既存の `Auto` 設定のユーザーはプロトコルを選択するよう促される
|
||||
|
||||
### Claude Quick-Set から `ANTHROPIC_REASONING_MODEL` を削除
|
||||
|
||||
- レガシーフィールドは公開されなくなった。既存の設定は自動的にクリーンアップされる
|
||||
|
||||
### プロバイダー単位のプロキシ設定を削除
|
||||
|
||||
- グローバル Local Routing 設定に移行
|
||||
- 既存のプロバイダー単位のプロキシ値は無視される
|
||||
|
||||
### データベーススキーマ v9 → v10
|
||||
|
||||
- `mcp_servers` と `skills` に `enabled_hermes` カラムを追加
|
||||
- `DEFAULT 0` で自動マイグレーション、データ損失なし
|
||||
|
||||
### Pricing テーブルの再シード（v8 → v9）
|
||||
|
||||
- 新しいモデルと修正済み価格を取り込むため、初回起動時に `model_pricing` テーブルがクリアされ再シードされる
|
||||
|
||||
### XCodeAPI プリセットの削除
|
||||
|
||||
- XCodeAPI プリセットを使用していたユーザーは別のプロバイダーに切り替える必要がある
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ リスクに関する注意事項
|
||||
|
||||
本リリースは、リバースプロキシ型機能について v3.12.3 / v3.13.0 で提起された既存のリスク注意事項を継承します。
|
||||
|
||||
**GitHub Copilot リバースプロキシ**: Copilot のリバースプロキシパスを使用すると、GitHub / Microsoft の利用規約に違反する可能性があります。詳細は [v3.12.3 リリースノート](v3.12.3-ja.md#️-リスクに関する注意事項) を参照してください。
|
||||
|
||||
**Codex OAuth リバースプロキシ**: ChatGPT サブスクリプションで Codex OAuth リバースプロキシを使用すると、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 リリースノート](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
|
||||
|
||||
これらの機能を有効にすることで、ユーザーは**すべての関連リスクを自己責任で受諾**したものとみなされます。CC Switch はこれらの機能の使用に起因するアカウントの制限、警告、サービス停止について一切の責任を負いません。
|
||||
|
||||
---
|
||||
|
||||
## ダウンロード・インストール
|
||||
|
||||
[Releases](https://github.com/farion1231/cc-switch/releases/latest) から対応バージョンをダウンロードしてください。
|
||||
|
||||
### システム要件
|
||||
|
||||
| OS | 最小バージョン | アーキテクチャ |
|
||||
| ------- | ---------------------------- | ----------------------------------- |
|
||||
| Windows | Windows 10 以降 | x64 |
|
||||
| macOS | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 下表参照 | x64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| ファイル | 説明 |
|
||||
| ---------------------------------------- | ------------------------------------------- |
|
||||
| `CC-Switch-v3.14.0-Windows.msi` | **推奨** - MSI インストーラー、自動更新対応 |
|
||||
| `CC-Switch-v3.14.0-Windows-Portable.zip` | ポータブル版、解凍して実行、レジストリ不要 |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| -------------------------------- | -------------------------------------------------------- |
|
||||
| `CC-Switch-v3.14.0-macOS.dmg` | **推奨** - DMG インストーラー、Applications にドラッグ |
|
||||
| `CC-Switch-v3.14.0-macOS.zip` | 解凍して Applications にドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.14.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` |
|
||||
@@ -0,0 +1,468 @@
|
||||
# CC Switch v3.14.0
|
||||
|
||||
> Hermes Agent 成为第 6 个受管应用、Claude Opus 4.7 全面接入、Gemini Native API 代理、Local Routing 统一重命名、应用级窗口控件
|
||||
|
||||
**[English →](v3.14.0-en.md) | [日本語版 →](v3.14.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.14.0 是一次大版本更新，核心焦点是把 **Hermes Agent 作为第 6 个一等受管应用**接入 CC Switch，并把 **Claude Opus 4.7** 铺设到全部聚合器与 Bedrock 预设矩阵。Hermes 支持覆盖数据库 v9 → v10 迁移、完整的 Rust 命令面、基于 YAML 的 `~/.hermes/config.yaml` 读写（含原子备份）、MCP 同步、Skills 同步、SQLite + JSONL 会话管理，以及专属的前端面板和 Memory 编辑面板；与 Hermes Agent 0.10.0 schema 对齐的四种协议（`chat_completions`、`anthropic_messages`、`codex_responses`、`bedrock_converse`）全部可选。用户自行维护的 `providers:` dict 条目以只读卡片形式呈现，深度 YAML 配置则直接委托给 Hermes Web UI。
|
||||
|
||||
除了 Hermes，本次还新增了 **Gemini Native API 代理**（`api_format = "gemini_native"`），让代理可以把请求直接转发到 Google 的 `generateContent` 端点，完整支持流式、schema 转换和 shadow 请求；把老的 "Local Proxy Takeover" 在三语 UI / README / 文档中统一重命名为 **Local Routing**；新增 **应用级窗口控件**，在 Linux Wayland 等合成器绘制按钮失灵的场景下可选让 CC Switch 自绘最小化 / 最大化 / 关闭按钮；并在本版本发布前额外合入了从工具栏直接启动 `hermes dashboard`、LemonData 全应用预设、DDSHub Codex 端点以及若干 Hermes 健康检查与 Usage 模态框的修复。
|
||||
|
||||
会话侧通过 `@tanstack/react-virtual` **虚拟化会话列表**，让上千条记录的长会话也能流畅滚动，长消息默认折叠；Usage 面板新增**日期范围选择器**（今日 / 1d / 7d / 14d / 30d + 自定义日期时间）和翻页输入；**Stream Check 错误分类**以彩色 toast 呈现，默认探测模型重新梳理，"模型不存在"响应被单独识别；并新增在 Local Routing 激活时**阻止切换到官方供应商**的保护，以免官方流量被引入本地代理造成账号风险。Pricing 数据库 v8 → v9 重新种入约 50 个新模型条目（包括 Claude 4.7、Opus 4.7 Adaptive Thinking、Grok 4、Qwen 3.5/3.6、MiniMax M2.5/M2.7、Doubao Seed 2.0 系列、GLM-5/5.1 等），并修正了多项陈旧价格。
|
||||
|
||||
**发布日期**：2026-04-21
|
||||
|
||||
**更新规模**：100 commits | 219 files changed | +20,548 / -3,569 lines
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- **Hermes Agent 支持（第 6 个受管应用）**：数据库 v9 → v10 迁移、完整 Rust 命令面、YAML 读写带原子备份、MCP 同步、Skills 同步、SQLite + JSONL 会话管理、专属前端面板、四种 API 协议（`chat_completions` / `anthropic_messages` / `codex_responses` / `bedrock_converse`）
|
||||
- **Claude Opus 4.7 全面接入**：自适应思维白名单、按百万 token 定价种子、Bedrock SKU（`anthropic.claude-opus-4-7` / `global.anthropic.claude-opus-4-7`，丢弃老 `-v1` 后缀），全部聚合器 / Bedrock 预设升级为默认 Opus 模型
|
||||
- **Claude `max` 推理力度**：推理下拉从 `high` 升级到 `max`
|
||||
- **Gemini Native API 代理**：新增 `api_format = "gemini_native"`，代理可直达 Google `generateContent`，完整流式 / schema 转换 / shadow 请求
|
||||
- **GitHub Copilot 企业版**：为 Copilot 型 Claude 供应商新增 GHES 认证与端点配置
|
||||
- **Copilot 次数消耗深度优化**：转发前主动剥离 thinking 块、`tool_result` 消息归类修正、subagent 检测、`x-interaction-id` 合并计费、orphan `tool_result` 清理、默认启用 warmup 降级 —— 系统性降低 premium 交互消耗
|
||||
- **会话列表虚拟化**：长会话流畅滚动，长消息默认折叠降低文字布局成本
|
||||
- **Codex / OpenClaw 会话标题提取**：自动抽取有意义标题，两行显示，剥离 OpenClaw `message_id` 尾噪声
|
||||
- **Usage 日期范围选择器**：Today / 1d / 7d / 14d / 30d 预设 + 自定义日期时间日历；分页列表支持页码跳转输入
|
||||
- **Stream Check 错误分类**：错误按类别分色 toast；默认探测模型刷新；单独识别 "model not found"
|
||||
- **Local Routing 激活时阻止官方供应商切换**：官方流量走本地代理有账号暂停风险，强制拦截并 toast 警告
|
||||
- **Pricing 数据库刷新（v8 → v9）**：新增 ~50 条模型条目并修正陈旧价格
|
||||
- **应用级窗口控件**：可选让 CC Switch 自绘 min/max/close，显著改善 Linux Wayland 体验
|
||||
- **Hermes 接入统一 Skills 管理**：Skills 安装 / 启用 / 过滤现覆盖 Hermes
|
||||
- **Hermes / OpenClaw 配置目录自定义**：在设置里指定 `~/.hermes/config.yaml` 或 `openclaw.json` 的自定义位置
|
||||
- **从工具栏启动 Hermes Dashboard**：Web UI 探测失败时，点击可在用户首选终端中启动 `hermes dashboard`
|
||||
- **新合作伙伴预设**：LemonData 覆盖全部 6 个应用；DDSHub 新增 Codex 端点；StepFun Step Plan
|
||||
|
||||
---
|
||||
|
||||
## 新功能
|
||||
|
||||
### Hermes Agent 支持（第 6 个受管应用）
|
||||
|
||||
CC Switch 首次支持 Hermes Agent 作为一等受管应用，与 Claude / Codex / Gemini / OpenCode / OpenClaw 并列。
|
||||
|
||||
- **数据库迁移 v9 → v10**：为 `mcp_servers` 和 `skills` 表新增 `enabled_hermes` 列（`DEFAULT 0` 自动迁移，无数据丢失）
|
||||
- **YAML 配置读写**：`~/.hermes/config.yaml` 读写带原子备份；`tests/hermes_roundtrip.rs` 守护不损坏不相关键和 OAuth MCP `auth` 块
|
||||
- **四种 API 协议**：与 Hermes Agent 0.10.0 对齐的 `chat_completions` / `anthropic_messages` / `codex_responses` / `bedrock_converse`；新 deeplink 默认为 `chat_completions`
|
||||
- **用户 `providers:` dict 只读呈现**：用户在 YAML 里手写的 providers 条目在 CC Switch 中以只读卡片展示，深度配置跳转到 Hermes Web UI
|
||||
- **累加式切换**：与 Claude / Codex 的"覆盖式"切换不同，Hermes 所有供应商共存于同一 YAML
|
||||
|
||||
### Hermes Memory 面板
|
||||
|
||||
- 新增 Memory 面板直接编辑 `MEMORY.md` / `USER.md`，带启用开关、字符数限制和保存流
|
||||
- 替换 Hermes 的 Prompts 入口
|
||||
|
||||
### Hermes 供应商预设（约 50 个）
|
||||
|
||||
- 覆盖 Nous Research、胜算云、OpenRouter、DeepSeek、Together AI、StepFun、智谱 GLM、百炼、Kimi、MiniMax、豆包、百灵、魔搭、KAT-Coder、PackyCode、Cubence、AIGoCode、RightCode、AICodeMirror、AICoding、CrazyRouter、SSSAiCode、Micu、CTok.ai、DDSHub、E-FlowCode、LionCCAPI、PIPELLM、Compshare、SiliconFlow、AiHubMix、DMXAPI、TheRouter、Novita、Nvidia、小米 MiMo
|
||||
|
||||
### 从工具栏启动 Hermes Dashboard
|
||||
|
||||
- Hermes Web UI 探测失败时，工具栏按钮改为弹出确认框，提供在用户首选终端里运行 `hermes dashboard`
|
||||
- 通过临时 bash / batch 脚本启动，`hermes dashboard` 就绪后自动打开浏览器，无需轮询
|
||||
- Memory 面板和 Health banner 保留原有 toast 行为
|
||||
- 顺便修正了离线 toast 里过时的 `hermes web` 提示（正确命令是 `hermes dashboard`）
|
||||
- Linux 终端探测改为先 `which` 后 stat，提升兼容性
|
||||
|
||||
### Claude Opus 4.7 支持
|
||||
|
||||
- 新增 Claude Opus 4.7 及其自适应思维白名单、按百万 token 定价种子、Bedrock SKU（`anthropic.claude-opus-4-7` / `global.anthropic.claude-opus-4-7`，丢弃老 `-v1` 后缀）
|
||||
- 全部聚合器 / Bedrock 预设升级为默认 Opus 模型
|
||||
|
||||
### Claude `max` 推理力度
|
||||
|
||||
- Claude 推理下拉从 `high` 升级到 `max`，解锁更强的思考容量
|
||||
|
||||
### Gemini Native API 代理
|
||||
|
||||
- 新增 `api_format = "gemini_native"`，代理可直接转发到 Google `generateContent` API (#1918, 感谢 @yovinchen)
|
||||
- 完整支持流式、schema 转换、shadow 请求
|
||||
- 在 proxy providers 模块下新增 `gemini_url.rs`、`gemini_schema.rs`、`gemini_shadow.rs`、`streaming_gemini.rs`、`transform_gemini.rs`
|
||||
|
||||
### GitHub Copilot 企业版（GHES）
|
||||
|
||||
- 为 Copilot 型 Claude 供应商新增 GHES 认证与端点配置 (#2175, 感谢 @hotelbe)
|
||||
|
||||
### 会话列表虚拟化
|
||||
|
||||
- 通过 `@tanstack/react-virtual` 虚拟化会话列表，上千条记录流畅滚动
|
||||
- 长会话消息默认折叠，减少文字布局开销
|
||||
|
||||
### Codex / OpenClaw 会话标题提取
|
||||
|
||||
- Codex 和 OpenClaw 会话自动抽取有意义的标题，两行显示
|
||||
- 剥离 OpenClaw `message_id` 后缀噪声
|
||||
|
||||
### Usage 日期范围选择器
|
||||
|
||||
- Usage 面板新增日期范围选择器，预设 Tab（Today / 1d / 7d / 14d / 30d）+ 自定义日期 + 时间日历 (#2002, 感谢 @yovinchen)
|
||||
- 分页列表新增页码跳转输入
|
||||
|
||||
### 模型映射快速填入
|
||||
|
||||
- 供应商表单的模型映射字段旁新增快速填入按钮，加快编辑 (#2179, 感谢 @lispking)
|
||||
|
||||
### Stream Check 错误分类
|
||||
|
||||
- 按类别为 Stream Check 错误上色并以 toast 呈现
|
||||
- 刷新所有厂商默认探测模型到当前主力机型
|
||||
- 对 "model not found" 响应做单独识别
|
||||
|
||||
### Local Routing 激活时阻止官方供应商切换
|
||||
|
||||
- 在 Local Routing 激活状态下，切换到官方供应商会被强制拦截并弹出警告 toast
|
||||
- 原因：官方 API 流量经由本地代理存在账号暂停风险
|
||||
|
||||
### Pricing 数据库刷新（v8 → v9）
|
||||
|
||||
- 迁移时重新种入定价表
|
||||
- 新增约 50 条模型条目，覆盖 Claude 4.7、Opus 4.7 Adaptive Thinking、Grok 4、Qwen 3.5/3.6、MiniMax M2.5/M2.7、Doubao Seed 2.0 系列、GLM-5/5.1
|
||||
- 修正 DeepSeek、Kimi K2.5 等陈旧价格
|
||||
|
||||
### 应用级窗口控件
|
||||
|
||||
- 新增可选设置，让 CC Switch 自绘最小化 / 切换最大化 / 关闭按钮，代替系统装饰 (#1119, 感谢 @git1677967754)
|
||||
- 在合成器按钮可能失灵的 Linux Wayland 上显著改善体验
|
||||
|
||||
### Hermes 接入统一 Skills 管理
|
||||
|
||||
- 统一的 Skills 界面新增 Hermes
|
||||
- Skills 安装 / 启用 / 过滤现覆盖 Hermes，与 Claude / Codex / Gemini / OpenCode / OpenClaw 并列
|
||||
|
||||
### OpenClaw 配置目录自定义
|
||||
|
||||
- 新增设置项，允许把 CC Switch 指向自定义的 `openclaw.json` 位置 (#1518, 感谢 @mrFranklin)
|
||||
|
||||
### Hermes 配置目录自定义
|
||||
|
||||
- 新增设置项，允许把 CC Switch 指向自定义的 `~/.hermes/config.yaml` 位置，底层通过数据驱动 dispatch
|
||||
|
||||
### StepFun Step Plan 预设
|
||||
|
||||
- 新增 StepFun Step Plan（EN / ZH）供应商预设 (#2155, 感谢 @hengm3467)
|
||||
|
||||
### New API 用量脚本模板
|
||||
|
||||
- 为 New API 用量脚本模板新增 User-Agent 头，提升上游兼容性
|
||||
|
||||
### LemonData 全应用预设
|
||||
|
||||
- LemonData 作为第三方合作伙伴预设覆盖 Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes 全部 6 个应用
|
||||
- 含图标资源和 zh / en / ja 三语合作伙伴推广文案
|
||||
- Claude 预设使用 `ANTHROPIC_API_KEY` 认证，OpenAI 兼容应用目标为 `gpt-5.4`
|
||||
|
||||
### DDSHub Codex 预设
|
||||
|
||||
- 新增 DDSHub 的 Codex 兼容端点（与 Claude 服务同 host）
|
||||
- base URL 省略 `/v1` 后缀，由网关自动路由 OpenAI SDK 路径
|
||||
|
||||
---
|
||||
|
||||
## 变更
|
||||
|
||||
### "Local Proxy Takeover" → "Local Routing"
|
||||
|
||||
- 三语 UI 文案、README、文档中全部统一重命名
|
||||
- 功能行为保持不变
|
||||
|
||||
### Hermes `Auto` api_mode 移除
|
||||
|
||||
- 用户必须显式选择协议；新 deeplink 默认为 `chat_completions`
|
||||
- 消除了基于 URL 的启发式识别带来的意外
|
||||
|
||||
### Hermes 供应商表单
|
||||
|
||||
- 新增 API mode 下拉和按供应商的模型编辑器
|
||||
- 切换激活供应商时，把按供应商的模型绑定到顶层 `model:`
|
||||
|
||||
### Hermes 深度配置委托
|
||||
|
||||
- 深度 YAML 配置不再在 CC Switch 表单里重复，直接通过"启动 Hermes Web UI"按钮交给 Web UI
|
||||
|
||||
### Hermes 工具栏布局
|
||||
|
||||
- Web UI 按钮图标从 `ExternalLink` 换成 `LayoutDashboard` —— 点击可能启动 `hermes dashboard` 而非仅仅打开 URL，面板式图标语义更准
|
||||
- MCP 移到工具栏末尾，与 Claude / Codex / Gemini / OpenCode 的布局对齐
|
||||
|
||||
### Claude Quick-Set 移除 `ANTHROPIC_REASONING_MODEL`
|
||||
|
||||
- 把推理能力和模型选择解耦，quick-set 表单不再暴露该遗留字段
|
||||
|
||||
### 按供应商代理配置移除
|
||||
|
||||
- 统一到全局的 Local Routing
|
||||
- 按供应商的代理开关和存储都已移除
|
||||
|
||||
### 统一工具栏图标按钮宽度
|
||||
|
||||
- 在 Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes 面板之间规格化图标按钮宽度，表头视觉一致
|
||||
|
||||
### Rust Toolchain 锁定 1.95
|
||||
|
||||
- 全仓库采纳 clippy 1.95 建议并锁定 toolchain，防止 nightly 漂移
|
||||
|
||||
### 托盘菜单 ID 常量
|
||||
|
||||
- 托盘标识符从硬编码字符串 `"main"` 改为 `TRAY_ID` 常量（`"cc-switch"`），所有调用点同步 (#1978, 感谢 @lidaxian121)
|
||||
|
||||
### Copilot 次数消耗深度优化
|
||||
|
||||
一次系统性优化专门降低 Copilot 反向代理的 premium 交互消耗，涵盖以下多项改进：
|
||||
|
||||
- **转发前主动剥离 thinking 块**：Anthropic 的 `thinking` / `redacted_thinking` 块会被 OpenAI 兼容端点拒绝，过去一次请求先失败消耗一次 premium 交互、再由 `thinking_rectifier` 触发重试。新增主动剥离步骤（Copilot 优化管线第 3.5 步，位于 `tool_result` 合并之后），直接省掉那一次无谓的 premium 消耗
|
||||
- **请求分类修正**：含 `tool_result` 的消息归类为代理继续，而不是用户发起的新请求 —— 避免每次工具调用都被错误计入 premium 次数
|
||||
- **subagent 检测**：通过 `__SUBAGENT_MARKER__` 和 `metadata._agent_` 回退识别 subagent，设置 `x-interaction-type=conversation-subagent`
|
||||
- **确定性 `x-interaction-id` 合并计费**：从 session ID 推导 `x-interaction-id`，把同一会话内的多次请求合并为一次计费交互
|
||||
- **Orphan `tool_result` 清理**：清理孤立的 `tool_result`，避免触发上游错误导致重试和重复计费
|
||||
- **Warmup 降级默认开启**：使用 `gpt-5-mini` 作为默认降级模型
|
||||
- **优化管线重排**：classify → sanitize → merge → warmup，让分类看到原始 `tool_result` 语义
|
||||
- 修复 `CopilotOptimizerConfig` 默认值不一致（统一到 `gpt-5-mini`）
|
||||
|
||||
### 用量脚本内网支持
|
||||
|
||||
- 移除 usage script 的私网 IP / 可疑主机名屏蔽，解锁企业内网、Docker、自建 API 端点
|
||||
- 内置模板仍强制 HTTPS（localhost 除外）和同源检查；自定义模板仍由用户控制，这类请求 URL 检查跳过
|
||||
|
||||
### Failover 队列备注
|
||||
|
||||
- 供应商备注现在在 failover 队列选择器和队列行中显示，方便在多供应商队列里识别 (#2138, 感谢 @Coconut-Fish)
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 工具栏最大化后持续折叠
|
||||
|
||||
- 窗口最大化 / 还原后，工具栏不再卡在折叠状态；折叠判定会随尺寸变化重新计算
|
||||
|
||||
### Hermes YAML 污染与 OAuth MCP `auth` 丢失
|
||||
|
||||
- 经 CC Switch 往返写入不再丢失 OAuth MCP `auth` 块、也不污染不相关的 YAML 键
|
||||
- 新增 `tests/hermes_roundtrip.rs` 作为守护测试
|
||||
|
||||
### Hermes 激活供应商展示
|
||||
|
||||
- Hermes UI 现在正确展示激活供应商，并连通添加 / 启用 / 移除动作
|
||||
|
||||
### Hermes 供应商持久化
|
||||
|
||||
- 供应商持久化到 `custom_providers:` 下，`api_mode` 和 `model` 可跨重启 / 配置重载存活
|
||||
|
||||
### Hermes 健康检查错借 OpenClaw schema
|
||||
|
||||
- 以前 Hermes 供应商被路由到 `check_additive_app_stream`（OpenClaw 的调度器），后者读 camelCase 的 `baseUrl` / `apiKey` / `api`，导致即便 Hermes 字段全填还是报 "OpenClaw provider is missing baseUrl"
|
||||
- 新增 `check_hermes_stream`，用 Hermes 专用提取器把 `api_mode`（`chat_completions` / `anthropic_messages` / `codex_responses`）映射到对应的 `check_claude_stream` `api_format`，`bedrock_converse` 明确标记为不支持
|
||||
- 先解析 `api_mode` 再抽 URL / API key，让 `bedrock_converse` 用户看到真实原因，而不是误导性的 "missing base_url"
|
||||
|
||||
### Usage 查询模态框支持 Hermes / OpenClaw
|
||||
|
||||
- `getProviderCredentials` 新增对 Hermes（snake_case `base_url` / `api_key`）和 OpenClaw（camelCase `baseUrl` / `apiKey`）的扁平 `settingsConfig` 字段读取，让 SiliconFlow 等匹配供应商自动选中 "official balance" 模板
|
||||
- 重构 BALANCE 和 TOKEN_PLAN 测试路径复用 `providerCredentials`，不再直接读 `env.ANTHROPIC_*`，修正了非 Claude 应用即使配置了 key 也报 "empty key" 的问题
|
||||
|
||||
### Codex `cache_control` 保留
|
||||
|
||||
- 在 Codex 格式转换合并 system prompt 时保留 `cache_control` (#1946, 感谢 @yovinchen)
|
||||
|
||||
### Claude prompt cache key 泄漏
|
||||
|
||||
- Claude chat 转换时不再发送 prompt cache key (#2003, 感谢 @yovinchen)
|
||||
|
||||
### 代理逐跳响应头剥离
|
||||
|
||||
- 按 RFC 7230 剥离代理响应的 hop-by-hop 头（Connection、Keep-Alive、Transfer-Encoding 等） (#2060, 感谢 @yovinchen)
|
||||
|
||||
### 代理 CORS 层移除
|
||||
|
||||
- 移除代理中过于宽松的 CORS 层 (#1915, 感谢 @zerone0x)
|
||||
|
||||
### 代理 toast 显示后端错误详情
|
||||
|
||||
- 代理相关 toast 现在展示后端错误 payload 的详情，而不是一句笼统的失败
|
||||
|
||||
### Usage 日志去重
|
||||
|
||||
- 代理和会话日志的用量记录去重，相同请求不再被重复计数
|
||||
- 请求日志时间范围与面板的 1d / 7d / 30d 选择器同步
|
||||
|
||||
### Common Config 勾选持久化
|
||||
|
||||
- Claude / Codex / Gemini common-config 勾选状态重开后正确保留 (#2191, 感谢 @zxZeng)
|
||||
|
||||
### Claude 插件 `settings.json` 同步
|
||||
|
||||
- 编辑当前供应商时，会同步回 Claude 插件路径下的 `settings.json` (#1905, 感谢 @chengww5217)
|
||||
|
||||
### Google Official Gemini env 保留
|
||||
|
||||
- 保存 Google Official Gemini 供应商时不再清空 `env` 块
|
||||
|
||||
### OpenCode JSON5 尾逗号解析
|
||||
|
||||
- OpenCode 配置读取容忍尾逗号（JSON5） (#2023, 感谢 @wwminger)
|
||||
|
||||
### 预设刷新
|
||||
|
||||
- 刷新 DeepSeek 和 Claude 1M 的陈旧 context 窗口
|
||||
- 刷新陈旧模型 ID，回填 Hermes 模型列表
|
||||
- 修正 Nous 端点，Hermes 占位图替换为 Nous 品牌图
|
||||
- 移除未使用的官方 Hermes 预设
|
||||
|
||||
### 搜索命中时折叠消息自动展开
|
||||
|
||||
- 搜索匹配落在折叠内容内部时，消息自动展开以定位匹配
|
||||
|
||||
### 未知订阅配额等级隐藏
|
||||
|
||||
- 供应商卡片不再渲染未知订阅配额等级
|
||||
|
||||
### weekly_limit 标签统一
|
||||
|
||||
- 跨语言把 `weekly_limit` 等级标签对齐到官方的"7 天"命名
|
||||
|
||||
### 根级 Skill 仓库安装
|
||||
|
||||
- 修复当仓库根本身就是一个 skill 时的安装失败
|
||||
|
||||
### Session ID 解析 clippy
|
||||
|
||||
- 移除 session ID 解析里的冗余闭包（clippy 警告）
|
||||
|
||||
### Stream Check 默认探测模型刷新
|
||||
|
||||
- 默认探测模型更新到每家厂商当前主力
|
||||
|
||||
### Skills 导入同步
|
||||
|
||||
- 导入的 Skills 即时同步到启用应用目录，不再仅记录在数据库里导致 UI 显示"已安装"但目标目录空缺 (#2101, 感谢 @yaoguohh)
|
||||
|
||||
### Ghostty 会话恢复
|
||||
|
||||
- 改为通过 shell 执行 + `--working-directory` 启动 Ghostty 会话恢复 (#1976, 感谢 @Suda202)
|
||||
- 避免路径含空格 / 特殊字符时 `cwd` 转义问题
|
||||
|
||||
---
|
||||
|
||||
## 文档
|
||||
|
||||
### README 赞助商更新
|
||||
|
||||
- SiliconFlow 注册赠送更新为 ¥16
|
||||
- 精简 SSSAiCode 赞助文案
|
||||
- 更新合作伙伴 logo
|
||||
- 新增 LemonData 赞助商
|
||||
|
||||
### 全局代理提示澄清
|
||||
|
||||
- 三语澄清全局代理与 Local Routing 的关系
|
||||
|
||||
### Takeover → Routing 文档重命名
|
||||
|
||||
- 接管相关文档在三语下重命名为 routing，同步更新锚点
|
||||
|
||||
### PIPELLM 网站 URL
|
||||
|
||||
- PIPELLM 赞助商网站 URL 更新为 `code.pipellm.ai`
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 重要变更（Breaking）
|
||||
|
||||
### Hermes 必须显式 `api_mode`
|
||||
|
||||
- `Auto` 模式移除；导入或 deeplink 得到的供应商默认落到 `chat_completions`
|
||||
- 既有 `Auto` 配置的用户会被提示选择协议
|
||||
|
||||
### Claude Quick-Set 移除 `ANTHROPIC_REASONING_MODEL`
|
||||
|
||||
- 该遗留字段不再暴露；既有设置自动清理
|
||||
|
||||
### 按供应商代理配置移除
|
||||
|
||||
- 迁移到全局 Local Routing 设置
|
||||
- 既有按供应商代理值被忽略
|
||||
|
||||
### 数据库 schema v9 → v10
|
||||
|
||||
- 为 `mcp_servers` 和 `skills` 表新增 `enabled_hermes` 列
|
||||
- 自动迁移，`DEFAULT 0`，无数据丢失
|
||||
|
||||
### Pricing 表 v8 → v9 重置
|
||||
|
||||
- 首次启动时 `model_pricing` 表被清空并重新种入，以应用新模型和修正后的价格
|
||||
|
||||
### XCodeAPI 预设移除
|
||||
|
||||
- 使用 XCodeAPI 预设的用户请迁移到其它供应商
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 风险提示
|
||||
|
||||
本版本在涉及反向代理类功能上沿用 v3.12.3 / v3.13.0 提出的风险提示。
|
||||
|
||||
**GitHub Copilot 反向代理**：使用 Copilot 的反代路径可能违反 GitHub / Microsoft 服务条款。详情见 [v3.12.3 release notes](v3.12.3-zh.md#️-风险提示)。
|
||||
|
||||
**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-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.14.0-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.14.0-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| -------------------------------- | --------------------------------------------- |
|
||||
| `CC-Switch-v3.14.0-macOS.dmg` | **推荐** - DMG 安装包，拖入 Applications 即可 |
|
||||
| `CC-Switch-v3.14.0-macOS.zip` | 解压后拖入 Applications，Universal Binary |
|
||||
| `CC-Switch-v3.14.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` |
|
||||
@@ -0,0 +1,185 @@
|
||||
# CC Switch v3.14.1
|
||||
|
||||
> Tray usage visibility, Codex OAuth stability fixes, Skills import/install reliability, and removal of the Hermes config health scanner
|
||||
|
||||
**[中文版 →](v3.14.1-zh.md) | [日本語版 →](v3.14.1-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.14.1 is a patch release following v3.14.0, focused on **Codex OAuth reverse-proxy stability**, **tray usage visibility**, **Skills import / install reliability**, **Gemini session restore paths**, and **simplifying Hermes configuration health handling**.
|
||||
|
||||
For the first time, the system tray surfaces **cached usage** for the current Claude / Codex / Gemini provider directly in its submenus — including subscription summaries and usage-script summaries with color-coded utilization markers. For Chinese coding-plan providers like Kimi / Zhipu / MiniMax, the tray additionally renders a **5-hour + weekly window** layout in the `🟢 h12% w80%` style (worst utilization drives the emoji), semantically identical to the official subscription badges. Creating a Claude provider whose `ANTHROPIC_BASE_URL` matches a known coding-plan host now auto-injects `meta.usage_script` so the tray lights up without opening the Usage Script modal.
|
||||
|
||||
Several Codex OAuth reverse-proxy stability issues are addressed this release: client-provided session IDs are now used as both `prompt_cache_key` and the Codex session header to avoid UUID-driven cache churn; non-streaming Anthropic clients receive proper JSON responses even when the ChatGPT Codex upstream forces OpenAI Responses SSE; and Stream Check now builds probes with the same `store: false`, encrypted reasoning include, and provider FAST mode setting as production requests, eliminating the "check fails but it actually works" mismatch. Paired with a new explicit **FAST mode toggle**, users can now opt into `service_tier="priority"` on Codex OAuth-backed Claude providers, trading latency against ChatGPT quota consumption on their own terms.
|
||||
|
||||
Additionally, the in-app **Hermes config health scanner** and its warning banner are removed (along with the `scan_hermes_config_health` command, `HermesHealthWarning` type, and `HermesWriteOutcome.warnings` payload), refocusing the Hermes surface on active provider display, switching defaults, memory editing, and launching the Hermes Web UI — deep configuration health is now Hermes's own responsibility.
|
||||
|
||||
**Release Date**: 2026-04-23
|
||||
|
||||
**Update Scale**: 13 commits | 48 files changed | +1,883 / -808 lines
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- **Tray Usage Visibility**: Claude / Codex / Gemini tray submenus show cached usage for the current provider, including subscription and script-based summaries with color markers; refreshes are throttled, limited to visible apps, and synchronized back into React Query (#2184, thanks @TuYv)
|
||||
- **Tray Coding-Plan Usage (Kimi / Zhipu / MiniMax)**: The tray renders 5-hour + weekly window usage using the `🟢 h12% w80%` layout; Claude providers whose base URL matches a known host auto-inject `meta.usage_script`
|
||||
- **Codex OAuth FAST Mode**: New explicit FAST mode toggle for Codex OAuth-backed Claude providers; when enabled, converted Responses requests send `service_tier="priority"`. Off by default (#2210, thanks @JesusDR01)
|
||||
- **Codex OAuth Stability**: Fixed reverse-proxy cache routing (#2218, thanks @majiayu000), Responses SSE aggregation (#2235, thanks @xpfo-go), and Stream Check parity with production (#2210, thanks @JesusDR01)
|
||||
- **Hermes Config Health Scanner Removed**: Refocuses the Hermes surface on provider management, memory editing, and launching the Web UI — no longer duplicates deep configuration health judgments
|
||||
- **Skills Import / Install Reliability**: Import dialog disables actions while pending and deduplicates results by ID (#2211, thanks @TuYv); model quick-set / one-click config applies against the latest form state (#2249, thanks @Coconut-Fish); root-level `SKILL.md` repo installs are stable (#2231, thanks @santugege)
|
||||
- **Gemini Session Restore Paths**: Session scanning reads `.project_root` metadata and passes the original project directory back into restore flows (#2240, thanks @tisonkun)
|
||||
- **Session / Settings Layout Polish**: Hardened the scroll-area viewport with width containment to fix horizontal overflow; tightened app bottom and settings footer spacing (#2201, thanks @Coconut-Fish)
|
||||
|
||||
---
|
||||
|
||||
## Added
|
||||
|
||||
### Tray Usage Visibility
|
||||
|
||||
- System tray submenus now show **cached usage** for the current Claude / Codex / Gemini provider (#2184, thanks @TuYv)
|
||||
- Includes subscription quota summaries and usage-script summaries with color-coded utilization markers
|
||||
- Tray-triggered refreshes are **throttled**, **limited to visible apps**, and synchronized back into React Query so the main window and tray share the same usage data
|
||||
|
||||
### Tray Coding-Plan Usage (Kimi / Zhipu / MiniMax)
|
||||
|
||||
- The tray renders **5-hour + weekly window** usage for Chinese coding-plan providers
|
||||
- Uses the same `🟢 h12% w80%` two-window layout as official subscription badges (worst utilization drives the emoji color)
|
||||
- Creating a Claude provider whose `ANTHROPIC_BASE_URL` matches a known coding-plan host **auto-injects** `meta.usage_script`, so the tray lights up without opening the Usage Script modal
|
||||
- Existing `usage_script` values are **preserved on update**, never clobbering user customizations
|
||||
|
||||
### Codex OAuth FAST Mode
|
||||
|
||||
- New explicit FAST mode toggle for Codex OAuth-backed Claude providers (#2210, thanks @JesusDR01)
|
||||
- When enabled, converted Responses requests send `service_tier="priority"` for lower latency
|
||||
- Off by default to avoid unexpectedly increasing ChatGPT quota consumption
|
||||
|
||||
---
|
||||
|
||||
## Changed
|
||||
|
||||
### Session and Settings Layout Polish
|
||||
|
||||
- Hardened the scroll-area viewport with width containment to fix horizontal overflow (#2201, thanks @Coconut-Fish)
|
||||
- Tightened app bottom and settings footer spacing so long session / settings views fit more cleanly
|
||||
|
||||
---
|
||||
|
||||
## Removed
|
||||
|
||||
### Hermes Config Health Scanner
|
||||
|
||||
- Removed the in-app Hermes config health scanner and its warning banner
|
||||
- Removed the `scan_hermes_config_health` command, `HermesHealthWarning` type, and `HermesWriteOutcome.warnings` payload
|
||||
- The CC Switch Hermes surface now focuses on its core job: active provider display, default provider switching, memory editing, and launching the Hermes Web UI for deep configuration
|
||||
|
||||
---
|
||||
|
||||
## Fixed
|
||||
|
||||
### Codex OAuth Cache Routing
|
||||
|
||||
- Use the client-provided session ID as both `prompt_cache_key` and the Codex session header, preserving explicit cache keys (#2218, thanks @majiayu000)
|
||||
- Stop generating UUIDs that caused cache-identity churn, stabilizing the ChatGPT Codex reverse-proxy cache identity
|
||||
|
||||
### Codex OAuth Responses SSE Aggregation
|
||||
|
||||
- Non-streaming Anthropic clients now receive proper JSON even when the ChatGPT Codex upstream forces OpenAI Responses SSE (#2235, thanks @xpfo-go)
|
||||
- CC Switch aggregates the upstream SSE events before running the non-streaming transform
|
||||
|
||||
### Codex OAuth Stream Check Parity
|
||||
|
||||
- Stream Check now builds Codex OAuth probe requests with the same `store: false`, encrypted reasoning include, and provider FAST mode setting as production proxy traffic (#2210, thanks @JesusDR01)
|
||||
- Eliminates the "check fails but it actually works" mismatch
|
||||
|
||||
### Codex Model Extraction
|
||||
|
||||
- Reading the `model` field from Codex config now uses TOML parsing instead of first-line regex matching (#2227, thanks @nmsn)
|
||||
- Multiline TOML is handled correctly
|
||||
|
||||
### Model Quick-Set / One-Click Config
|
||||
|
||||
- Model quick-set now applies against the **latest** provider form config (#2249, thanks @Coconut-Fish)
|
||||
- Fixes stale form state preventing one-click configuration from succeeding
|
||||
|
||||
### Skills Import Duplicates
|
||||
|
||||
- The Skills import dialog disables actions while import is pending (#2211, thanks @TuYv)
|
||||
- The installed-skills cache deduplicates imported results by ID, preventing double-clicks from adding duplicate installed entries (#2139)
|
||||
|
||||
### Root-Level Skill Repos
|
||||
|
||||
- Skill install and update flows now consistently resolve three source patterns: direct nested paths, install-name recursive search, and repository-root `SKILL.md` sources (#2231, thanks @santugege)
|
||||
|
||||
### Gemini Session Restore Paths
|
||||
|
||||
- Gemini session scanning now reads `.project_root` metadata (#2240, thanks @tisonkun)
|
||||
- Restore flows can pass the original project directory when available
|
||||
|
||||
### Provider Hover Names
|
||||
|
||||
- Provider icons now expose the provider name on hover for inline SVG, image URL, and fallback initials render paths (#2237, thanks @tisonkun)
|
||||
|
||||
---
|
||||
|
||||
## Notes & Caveats
|
||||
|
||||
- **Hermes Health Scanner Removed**: If you were relying on CC Switch to surface deep Hermes YAML configuration issues, switch to the "Launch Hermes Web UI" toolbar button and inspect them in Hermes's own panel. Day-to-day provider management, switching, memory editing, and MCP / Skills sync continue to be handled by CC Switch.
|
||||
- **Codex OAuth FAST Mode Off by Default**: Only turn it on if you accept potentially increased ChatGPT quota consumption in exchange for lower latency.
|
||||
- **Tray Cached Usage**: Refreshes are throttled and limited to the currently visible app to avoid unnecessary upstream API calls; values are synchronized into React Query so the main window and tray stay in sync.
|
||||
|
||||
---
|
||||
|
||||
## Download & Installation
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download the appropriate version.
|
||||
|
||||
### System Requirements
|
||||
|
||||
| OS | Minimum Version | Architecture |
|
||||
| ------- | ---------------------------- | ----------------------------------- |
|
||||
| Windows | Windows 10 or later | x64 |
|
||||
| macOS | macOS 12 (Monterey) or later | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | See table below | x64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| File | Description |
|
||||
| ---------------------------------------- | ----------------------------------------------------- |
|
||||
| `CC-Switch-v3.14.1-Windows.msi` | **Recommended** - MSI installer, supports auto-update |
|
||||
| `CC-Switch-v3.14.1-Windows-Portable.zip` | Portable, extract and run, no registry writes |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| -------------------------------- | ------------------------------------------------------- |
|
||||
| `CC-Switch-v3.14.1-macOS.dmg` | **Recommended** - DMG installer, drag into Applications |
|
||||
| `CC-Switch-v3.14.1-macOS.zip` | Extract and drag into Applications, Universal Binary |
|
||||
| `CC-Switch-v3.14.1-macOS.tar.gz` | For Homebrew installation and auto-update |
|
||||
|
||||
> macOS builds are Apple code-signed and notarized — install directly.
|
||||
|
||||
### Homebrew (macOS)
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
| Distribution | Recommended | Installation |
|
||||
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| 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, or use AUR |
|
||||
| Other distros / not sure | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
@@ -0,0 +1,185 @@
|
||||
# CC Switch v3.14.1
|
||||
|
||||
> トレイでの用量可視化、Codex OAuth の複数の安定性修正、Skills インポート/インストールの信頼性向上、Hermes 設定ヘルススキャナーの削除
|
||||
|
||||
**[中文版 →](v3.14.1-zh.md) | [English →](v3.14.1-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.14.1 は v3.14.0 に続くパッチリリースで、**Codex OAuth リバースプロキシの安定性**、**トレイでの用量可視化**、**Skills インポート / インストールの信頼性**、**Gemini セッション復元パス**、および **Hermes 設定ヘルス処理の簡素化**を中心に据えています。
|
||||
|
||||
システムトレイは初めて、現在の Claude / Codex / Gemini プロバイダーの**キャッシュ済み用量**をサブメニューに直接表示するようになりました — サブスクリプション要約と用量スクリプト要約を、使用率に応じた色分けマーカーとともに表示します。Kimi / Zhipu / MiniMax のような中国系コーディングプランプロバイダーには、公式サブスクリプションバッジと同じ `🟢 h12% w80%` スタイルで **5 時間 + 週次ウィンドウ**の 2 ウィンドウレイアウトを追加描画します（より厳しい方の使用率が絵文字色を決定）。`ANTHROPIC_BASE_URL` が既知のコーディングプランホストに一致する Claude プロバイダーを作成すると、`meta.usage_script` が自動注入されるため、Usage Script モーダルを開かなくてもトレイが点灯します。
|
||||
|
||||
Codex OAuth 側では、複数のリバースプロキシ安定性の問題を修正しました: クライアント提供の session ID を `prompt_cache_key` と Codex session ヘッダーの両方に使用し、UUID 生成によるキャッシュ揺らぎを回避。ChatGPT Codex 上流が OpenAI Responses SSE を強制する場合でも、非ストリーミングの Anthropic クライアントが適切な JSON レスポンスを受け取れるようになりました。Stream Check は、本番環境と同じ `store: false`、暗号化 reasoning include、およびプロバイダーの FAST モード設定でプローブを構築するようになり、「検出は失敗するのに実際は動く」というズレが解消されました。新しい明示的な **FAST モードトグル**と組み合わせることで、ユーザーは Codex OAuth バックの Claude プロバイダーで `service_tier="priority"` を選択的に送信でき、レイテンシと ChatGPT 配額消費の間で自分で選べるようになりました。
|
||||
|
||||
さらに、CC Switch 内蔵の **Hermes 設定ヘルススキャナー**と警告バナー（および対応する `scan_hermes_config_health` コマンド、`HermesHealthWarning` 型、`HermesWriteOutcome.warnings` ペイロード）を削除し、Hermes サーフェスをアクティブプロバイダー表示、デフォルト切り替え、Memory 編集、および Hermes Web UI の起動に再フォーカスしました — 深い設定ヘルスは Hermes 自身の責任になります。
|
||||
|
||||
**リリース日**: 2026-04-23
|
||||
|
||||
**更新規模**: 13 commits | 48 files changed | +1,883 / -808 lines
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **トレイでの用量可視化**: Claude / Codex / Gemini のトレイサブメニューに、現在のプロバイダーのキャッシュ済み用量（サブスクリプション要約とスクリプト要約、色分けマーカー付き）を表示。リフレッシュはスロットル、可視アプリに限定、React Query に同期 (#2184, 感謝 @TuYv)
|
||||
- **トレイのコーディングプラン用量（Kimi / Zhipu / MiniMax）**: トレイが 5 時間 + 週次ウィンドウの用量を `🟢 h12% w80%` レイアウトで描画。既知のホストにマッチする Claude プロバイダーは `meta.usage_script` を自動注入
|
||||
- **Codex OAuth FAST モード**: Codex OAuth バックの Claude プロバイダーに明示的な FAST モードトグルを追加。有効時は変換された Responses リクエストに `service_tier="priority"` を送信、デフォルトは OFF (#2210, 感謝 @JesusDR01)
|
||||
- **Codex OAuth 安定性**: リバースプロキシのキャッシュルーティング (#2218, 感謝 @majiayu000)、Responses SSE 集約 (#2235, 感謝 @xpfo-go)、Stream Check と本番の一致性 (#2210, 感謝 @JesusDR01) を修正
|
||||
- **Hermes 設定ヘルススキャナー削除**: Hermes サーフェスをプロバイダー管理、Memory 編集、Web UI 起動に再フォーカス。深い設定ヘルス判定を重複して担わなくなる
|
||||
- **Skills インポート / インストールの信頼性**: インポート中はダイアログのアクションを無効化し、結果を ID で重複排除 (#2211, 感謝 @TuYv); ワンクリック設定は最新のフォーム状態に基づいて適用 (#2249, 感謝 @Coconut-Fish); ルートレベルの `SKILL.md` リポジトリインストールが安定 (#2231, 感謝 @santugege)
|
||||
- **Gemini セッション復元パス**: セッションスキャン時に `.project_root` メタデータを読み、元のプロジェクトディレクトリを復元フローに渡す (#2240, 感謝 @tisonkun)
|
||||
- **セッション / 設定レイアウトの磨き込み**: スクロールエリアビューポートに幅制約を追加して横方向のはみ出しを修正。アプリ下部と設定フッター間隔をよりタイトに (#2201, 感謝 @Coconut-Fish)
|
||||
|
||||
---
|
||||
|
||||
## 新機能
|
||||
|
||||
### トレイでの用量可視化
|
||||
|
||||
- システムトレイサブメニューに、現在の Claude / Codex / Gemini プロバイダーの**キャッシュ済み用量**を表示 (#2184, 感謝 @TuYv)
|
||||
- サブスクリプション配額要約と用量スクリプト要約を含み、使用率に応じた色分けマーカー付き
|
||||
- トレイ起因のリフレッシュは**スロットル**、**可視アプリに限定**、React Query に同期されるため、メインウィンドウとトレイが同じ用量データを共有
|
||||
|
||||
### トレイのコーディングプラン用量（Kimi / Zhipu / MiniMax）
|
||||
|
||||
- 中国系コーディングプランプロバイダー向けに、トレイが **5 時間 + 週次ウィンドウ**の用量を描画
|
||||
- 公式サブスクリプションバッジと同じ `🟢 h12% w80%` の 2 ウィンドウレイアウトを使用（より厳しい使用率が絵文字色を決定）
|
||||
- `ANTHROPIC_BASE_URL` が既知のコーディングプランホストにマッチする Claude プロバイダーを作成すると、`meta.usage_script` が**自動注入**され、Usage Script モーダルを開かなくてもトレイが点灯
|
||||
- 更新時は既存の `usage_script` 値を**保持**し、ユーザーカスタマイズを上書きしない
|
||||
|
||||
### Codex OAuth FAST モード
|
||||
|
||||
- Codex OAuth バックの Claude プロバイダーに明示的な FAST モードトグルを追加 (#2210, 感謝 @JesusDR01)
|
||||
- 有効時は変換された Responses リクエストに `service_tier="priority"` を送信してレイテンシを低減
|
||||
- 予期せぬ ChatGPT 配額消費の増加を避けるため、デフォルトは OFF
|
||||
|
||||
---
|
||||
|
||||
## 変更
|
||||
|
||||
### セッション・設定レイアウトの磨き込み
|
||||
|
||||
- スクロールエリアビューポートに幅制約を追加して横方向のはみ出しを修正 (#2201, 感謝 @Coconut-Fish)
|
||||
- アプリ下部と設定フッター間隔をよりタイトにし、長いセッション / 設定ビューをすっきり表示
|
||||
|
||||
---
|
||||
|
||||
## 削除
|
||||
|
||||
### Hermes 設定ヘルススキャナー
|
||||
|
||||
- アプリ内の Hermes 設定ヘルススキャナーと警告バナーを削除
|
||||
- `scan_hermes_config_health` コマンド、`HermesHealthWarning` 型、`HermesWriteOutcome.warnings` ペイロードを削除
|
||||
- CC Switch の Hermes サーフェスは本来の役割に回帰: アクティブプロバイダー表示、デフォルトプロバイダー切り替え、Memory 編集、および深い設定用の Hermes Web UI 起動
|
||||
|
||||
---
|
||||
|
||||
## バグ修正
|
||||
|
||||
### Codex OAuth キャッシュルーティング
|
||||
|
||||
- クライアント提供の session ID を `prompt_cache_key` と Codex session ヘッダーの両方に使用し、明示的なキャッシュキーを保持 (#2218, 感謝 @majiayu000)
|
||||
- キャッシュアイデンティティの揺らぎを引き起こしていた UUID 生成を停止し、ChatGPT Codex リバースプロキシのキャッシュアイデンティティを安定化
|
||||
|
||||
### Codex OAuth Responses SSE 集約
|
||||
|
||||
- ChatGPT Codex 上流が OpenAI Responses SSE を強制する場合でも、非ストリーミングの Anthropic クライアントが適切な JSON を受け取れるように修正 (#2235, 感謝 @xpfo-go)
|
||||
- CC Switch が非ストリーミング変換を実行する前に上流 SSE イベントを集約
|
||||
|
||||
### Codex OAuth Stream Check の一致性
|
||||
|
||||
- Stream Check が構築する Codex OAuth プローブリクエストは、本番プロキシと同じ `store: false`、暗号化 reasoning include、プロバイダー FAST モード設定を使用するように修正 (#2210, 感謝 @JesusDR01)
|
||||
- 「検出は失敗するのに実際は動く」ズレを解消
|
||||
|
||||
### Codex モデル抽出
|
||||
|
||||
- Codex 設定の `model` フィールドを読む際、先頭行の正規表現マッチではなく TOML パーサーを使用するように変更 (#2227, 感謝 @nmsn)
|
||||
- 複数行 TOML も正しく処理
|
||||
|
||||
### モデルのクイック入力 / ワンクリック設定
|
||||
|
||||
- モデルクイック入力は**最新の**プロバイダーフォーム設定に対して適用されるように修正 (#2249, 感謝 @Coconut-Fish)
|
||||
- 古いフォーム状態によってワンクリック設定が失敗する問題を修正
|
||||
|
||||
### Skills インポートの重複排除
|
||||
|
||||
- Skills インポートダイアログは、インポート中にすべてのアクションボタンを無効化 (#2211, 感謝 @TuYv)
|
||||
- インストール済み Skills のキャッシュを ID で重複排除し、ダブルクリックによる重複したインストール済みエントリを防止 (#2139)
|
||||
|
||||
### ルートレベルの Skill リポジトリ
|
||||
|
||||
- Skill のインストールと更新フローが 3 つのソースパターンを一貫して解決: 直接ネストパス、install-name の再帰検索、およびリポジトリルートの `SKILL.md` ソース (#2231, 感謝 @santugege)
|
||||
|
||||
### Gemini セッション復元パス
|
||||
|
||||
- Gemini セッションスキャンが `.project_root` メタデータを読み取るように修正 (#2240, 感謝 @tisonkun)
|
||||
- 復元フローは利用可能な場合に元のプロジェクトディレクトリを渡せる
|
||||
|
||||
### プロバイダー名のホバー表示
|
||||
|
||||
- プロバイダーアイコンは、inline SVG、画像 URL、およびフォールバックの頭文字レンダリングパスで、ホバー時にプロバイダー名を表示 (#2237, 感謝 @tisonkun)
|
||||
|
||||
---
|
||||
|
||||
## 備考・注意事項
|
||||
|
||||
- **Hermes ヘルススキャナー削除済み**: Hermes YAML の深い設定の問題提示を CC Switch に頼っていた場合は、ツールバーの「Hermes Web UI を起動」ボタンから Hermes 自身のパネルで確認してください。日常のプロバイダー管理、切り替え、Memory 編集、MCP / Skills 同期は引き続き CC Switch が担います。
|
||||
- **Codex OAuth FAST モードはデフォルト OFF**: レイテンシ低減と引き換えに ChatGPT 配額消費が増える可能性を許容する場合にのみ有効化してください。
|
||||
- **トレイのキャッシュ用量**: リフレッシュはスロットル済み、かつ現在可視のアプリに限定されており、不要な上流 API 呼び出しを回避します。値は React Query に同期されるため、メインウィンドウとトレイで同じ値が見えます。
|
||||
|
||||
---
|
||||
|
||||
## ダウンロード・インストール
|
||||
|
||||
[Releases](https://github.com/farion1231/cc-switch/releases/latest) から対応バージョンをダウンロードしてください。
|
||||
|
||||
### システム要件
|
||||
|
||||
| OS | 最小バージョン | アーキテクチャ |
|
||||
| ------- | ------------------------ | ----------------------------------- |
|
||||
| Windows | Windows 10 以降 | x64 |
|
||||
| macOS | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 下表参照 | x64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| ファイル | 説明 |
|
||||
| ---------------------------------------- | ------------------------------------------- |
|
||||
| `CC-Switch-v3.14.1-Windows.msi` | **推奨** - MSI インストーラー、自動更新対応 |
|
||||
| `CC-Switch-v3.14.1-Windows-Portable.zip` | ポータブル版、解凍して実行、レジストリ不要 |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| -------------------------------- | ------------------------------------------------------ |
|
||||
| `CC-Switch-v3.14.1-macOS.dmg` | **推奨** - DMG インストーラー、Applications にドラッグ |
|
||||
| `CC-Switch-v3.14.1-macOS.zip` | 解凍して Applications にドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.14.1-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` |
|
||||
@@ -0,0 +1,185 @@
|
||||
# CC Switch v3.14.1
|
||||
|
||||
> 托盘用量可见化、Codex OAuth 多项稳定性修复、Skills 导入/安装可靠性提升、Hermes 配置健康扫描器移除
|
||||
|
||||
**[English →](v3.14.1-en.md) | [日本語版 →](v3.14.1-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.14.1 是 v3.14.0 之后的一次补丁版本，围绕 **Codex OAuth 反代稳定性**、**托盘用量可见化**、**Skills 导入 / 安装可靠性**、**Gemini 会话恢复路径**，以及**简化 Hermes 配置健康处理**展开。
|
||||
|
||||
系统托盘第一次把当前 Claude / Codex / Gemini 供应商的**缓存用量**直接呈现在子菜单里——包含订阅额度摘要和用量脚本摘要，并用颜色标记利用率；针对 Kimi / 智谱 / MiniMax 这类中国编码套餐供应商，托盘还会额外渲染 `🟢 h12% w80%` 风格的 **5 小时 + 周窗口**双窗口排版，语义与官方订阅徽章完全一致（取更紧的那个驱动 emoji）。创建 Claude 供应商时，如果 `ANTHROPIC_BASE_URL` 命中已知的编码套餐 host，会自动注入 `meta.usage_script`，托盘可以不打开 Usage Script 模态框就直接点亮。
|
||||
|
||||
Codex OAuth 侧修复了多项反代稳定性问题：使用客户端自带的 session ID 作为 `prompt_cache_key` 和 Codex session 头，避免生成 UUID 造成缓存抖动，显著提高缓存命中率；非流式 Anthropic 客户端在 ChatGPT Codex 上游强制 OpenAI Responses SSE 时也能正确拿到 JSON 响应；Stream Check 现在会以和生产一致的 `store: false`、encrypted reasoning include 以及供应商 FAST 模式构造探测请求，避免出现"检测失败但实际能用"的错位。配合新增的 **FAST 模式显式开关**，让用户可以在 Codex OAuth 型 Claude 供应商上按需发 `service_tier="priority"`，在延迟和 ChatGPT 配额消耗之间自己选。
|
||||
|
||||
另外，移除了 CC Switch 内置的 **Hermes 配置健康扫描器**及其警告横幅（以及对应的 `scan_hermes_config_health` 命令、`HermesHealthWarning` 类型和 `HermesWriteOutcome.warnings` 载荷），把 Hermes 面板聚焦回当前供应商展示、默认切换、Memory 编辑和启动 Hermes Web UI，深度配置健康度由 Hermes 自己负责。
|
||||
|
||||
**发布日期**：2026-04-23
|
||||
|
||||
**更新规模**：13 commits | 48 files changed | +1,883 / -808 lines
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- **托盘用量可见化**：Claude / Codex / Gemini 托盘子菜单展示当前供应商缓存用量，含订阅与脚本摘要及颜色标记；刷新带节流、仅针对可见应用、并回写到 React Query (#2184, 感谢 @TuYv)
|
||||
- **托盘编码套餐用量（Kimi / 智谱 / MiniMax）**：托盘渲染 5 小时 + 周窗口双窗口用量，沿用 `🟢 h12% w80%` 排版；命中已知 host 的 Claude 供应商自动注入 `meta.usage_script`
|
||||
- **Codex OAuth FAST 模式**：为 Codex OAuth 型 Claude 供应商新增显式 FAST 开关，开启后转换后的 Responses 请求发 `service_tier="priority"`，默认关闭 (#2210, 感谢 @JesusDR01)
|
||||
- **Codex OAuth 稳定性**：修复反代缓存路由 (#2218, 感谢 @majiayu000)、Responses SSE 聚合 (#2235, 感谢 @xpfo-go)、Stream Check 与生产一致性 (#2210, 感谢 @JesusDR01)
|
||||
- **Hermes 配置健康扫描器移除**：把 Hermes 面板聚焦回供应商管理、Memory 编辑和 Web UI 启动，不再重复承担深度配置健康判断
|
||||
- **Skills 导入 / 安装可靠性**：导入过程中禁用操作按钮、结果按 ID 去重 (#2211, 感谢 @TuYv)；一键配置基于最新表单状态 (#2249, 感谢 @Coconut-Fish)；根级 `SKILL.md` 仓库安装稳定 (#2231, 感谢 @santugege)
|
||||
- **Gemini 会话恢复路径**：扫描会话时读取 `.project_root` 元数据，把原始项目目录带回恢复流程 (#2240, 感谢 @tisonkun)
|
||||
- **Session / 设置布局打磨**：滚动区域视口加宽度约束修复横向溢出，应用底部和设置页底部间距更紧凑 (#2201, 感谢 @Coconut-Fish)
|
||||
|
||||
---
|
||||
|
||||
## 新功能
|
||||
|
||||
### 托盘用量可见化
|
||||
|
||||
- 系统托盘子菜单新增当前 Claude / Codex / Gemini 供应商的**缓存用量**展示 (#2184, 感谢 @TuYv)
|
||||
- 包含订阅额度摘要和用量脚本摘要，并用颜色标记利用率
|
||||
- 托盘触发的刷新**带节流**、**只覆盖可见应用**，并同步回 React Query，主窗口和托盘共享同一份用量数据
|
||||
|
||||
### 托盘编码套餐用量（Kimi / 智谱 / MiniMax）
|
||||
|
||||
- 托盘为中国编码套餐供应商渲染 **5 小时 + 周窗口**双窗口用量
|
||||
- 使用与官方订阅徽章一致的 `🟢 h12% w80%` 两窗口排版，取更紧的那个利用率驱动 emoji 颜色
|
||||
- 创建 Claude 供应商时，如果 `ANTHROPIC_BASE_URL` 匹配已知编码套餐 host，会**自动注入** `meta.usage_script`，托盘不打开 Usage Script 模态框也能直接点亮
|
||||
- 更新时会**保留已有** `usage_script` 值，不覆盖用户自定义
|
||||
|
||||
### Codex OAuth FAST 模式
|
||||
|
||||
- 为 Codex OAuth 型 Claude 供应商新增显式 FAST 模式开关 (#2210, 感谢 @JesusDR01)
|
||||
- 开启时，转换后的 Responses 请求会发 `service_tier="priority"` 以降低延迟
|
||||
- 默认关闭，避免意外增加 ChatGPT 配额消耗
|
||||
|
||||
---
|
||||
|
||||
## 变更
|
||||
|
||||
### Session 与设置布局打磨
|
||||
|
||||
- 滚动区域视口加上宽度约束，修复横向溢出 (#2201, 感谢 @Coconut-Fish)
|
||||
- 应用底部和设置页底部间距更紧凑，让长 Session / 设置视图看起来更干净
|
||||
|
||||
---
|
||||
|
||||
## 移除
|
||||
|
||||
### Hermes 配置健康扫描器
|
||||
|
||||
- 移除应用内的 Hermes 配置健康扫描器和警告横幅
|
||||
- 移除 `scan_hermes_config_health` 命令、`HermesHealthWarning` 类型以及 `HermesWriteOutcome.warnings` 载荷
|
||||
- CC Switch 的 Hermes 面板回归核心职责：当前供应商展示、切换默认供应商、Memory 编辑、以及启动 Hermes Web UI 处理深度配置
|
||||
|
||||
---
|
||||
|
||||
## 修复
|
||||
|
||||
### Codex OAuth 缓存路由
|
||||
|
||||
- 使用客户端自带的 session ID 作为 `prompt_cache_key` 和 Codex session 头，保留显式缓存 key (#2218, 感谢 @majiayu000)
|
||||
- 停止生成 UUID 导致的缓存抖动，让 ChatGPT Codex 反代的缓存身份更稳定
|
||||
|
||||
### Codex OAuth Responses SSE 聚合
|
||||
|
||||
- ChatGPT Codex 上游强制 OpenAI Responses SSE 时，非流式 Anthropic 客户端也能正确拿到 JSON (#2235, 感谢 @xpfo-go)
|
||||
- CC Switch 会在非流式转换之前先聚合上游 SSE 事件
|
||||
|
||||
### Codex OAuth Stream Check 对齐
|
||||
|
||||
- Stream Check 构造的 Codex OAuth 测试请求现在与生产代理一致，使用相同的 `store: false`、加密 reasoning include 和供应商 FAST 模式设置 (#2210, 感谢 @JesusDR01)
|
||||
- 避免"检测失败但实际能用"的错位
|
||||
|
||||
### Codex 模型提取
|
||||
|
||||
- 读取 Codex 配置的 `model` 字段时，改用 TOML 解析替代首行正则匹配 (#2227, 感谢 @nmsn)
|
||||
- 多行 TOML 也能正确处理
|
||||
|
||||
### 模型快速填入 / 一键配置
|
||||
|
||||
- 模型快速填入现在基于**最新的**供应商表单配置应用 (#2249, 感谢 @Coconut-Fish)
|
||||
- 修复陈旧表单状态导致一键配置失败的问题
|
||||
|
||||
### Skills 导入去重
|
||||
|
||||
- Skills 导入对话框在导入进行时禁用所有操作按钮 (#2211, 感谢 @TuYv)
|
||||
- 已安装 Skills 的缓存按 ID 去重，避免双击造成重复的已安装条目 (#2139)
|
||||
|
||||
### 根级 Skill 仓库
|
||||
|
||||
- Skill 的安装与更新流程现在能一致地识别三种源路径：直接嵌套路径、按 install-name 递归搜索、以及仓库根的 `SKILL.md` 源 (#2231, 感谢 @santugege)
|
||||
|
||||
### Gemini 会话恢复路径
|
||||
|
||||
- Gemini 会话扫描时读取 `.project_root` 元数据 (#2240, 感谢 @tisonkun)
|
||||
- 恢复流程可以在可用时把原始项目目录传回
|
||||
|
||||
### 供应商名悬浮提示
|
||||
|
||||
- 供应商图标在 inline SVG、图像 URL、以及首字母回退渲染路径下都会在 hover 时展示供应商名称 (#2237, 感谢 @tisonkun)
|
||||
|
||||
---
|
||||
|
||||
## 说明与注意事项
|
||||
|
||||
- **Hermes 健康扫描器已移除**：如果你依赖 CC Switch 提示 Hermes YAML 的深度配置问题，请改为通过工具栏的"启动 Hermes Web UI"按钮在 Hermes 原生面板里查看。日常供应商管理、切换、Memory 编辑、MCP 与 Skills 同步仍然由 CC Switch 负责。
|
||||
- **Codex OAuth FAST 模式默认关闭**：只有在你接受可能增加 ChatGPT 配额消耗换取更低延迟时，才需要打开。
|
||||
- **托盘缓存用量**：刷新带节流，只覆盖当前显示的应用，避免无必要的上游 API 调用；数据会回写到 React Query，因此主窗口和托盘看到的值一致。
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
访问 [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.14.1-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.14.1-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| -------------------------------- | --------------------------------------------- |
|
||||
| `CC-Switch-v3.14.1-macOS.dmg` | **推荐** - DMG 安装包，拖入 Applications 即可 |
|
||||
| `CC-Switch-v3.14.1-macOS.zip` | 解压后拖入 Applications，Universal Binary |
|
||||
| `CC-Switch-v3.14.1-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` |
|
||||
@@ -0,0 +1,527 @@
|
||||
# CC Switch v3.15.0
|
||||
|
||||
> Claude Desktop becomes a first-class managed surface with third-party provider switching via proxy gateway, role-based model mapping, major reverse-proxy hardening, Codex OAuth live model discovery, and a filter-driven usage dashboard Hero card
|
||||
|
||||
**[中文版 →](v3.15.0-zh.md) | [日本語版 →](v3.15.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## Only Official Channels (Please Read)
|
||||
>
|
||||
> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Multiple imposter websites have recently been spotted impersonating CC Switch to solicit payments and harvest account credentials, with some users already reporting financial losses. Please only obtain the software through the official channels listed below:
|
||||
>
|
||||
> | Channel | Only Official |
|
||||
> | ------------------ | ------------------------------------------------------------------------------ |
|
||||
> | Website | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | Source | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | Downloads | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | Author | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues so we can take down the imposter site as quickly as possible.
|
||||
|
||||
---
|
||||
|
||||
## Claude Desktop Guide
|
||||
|
||||
The headline feature in this release is the **first-class Claude Desktop management panel**. If you already have many providers configured for Claude Code, start here:
|
||||
|
||||
**[Use CC Switch to configure, manage, and switch Claude Desktop providers in one place](../user-manual/en/2-providers/2.6-claude-desktop.md)**
|
||||
|
||||
The guide walks through one-click import from Claude Code, adding Claude Desktop-specific providers, direct mode vs. model-mapping mode, showing the hidden local-routing toggle, and returning to Claude Desktop's official sign-in mode.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.15.0 is a major release following the v3.14.x line, centered on **promoting Claude Desktop to a first-class managed surface**. It ships third-party provider switching through the in-app proxy gateway, role-based model mapping (`sonnet` / `opus` / `haiku`) with a `supports1m` long-context flag, Copilot/Codex OAuth provider reuse, a redesigned Claude Code import flow, app-switcher differentiation between "Claude Code" and "Claude Desktop", and 44 provider presets translated from the Claude Code catalog into the new Claude Desktop surface.
|
||||
|
||||
Around proxy reliability, this release performs a systematic hardening pass: P0–P3 patches across routing / lifecycle / retry / failover / rectifier paths; pooled HTTPS connection reuse for non-Anthropic backends to cut per-request latency; cache hit-rate improvements for Codex and OpenAI Responses (emit `prompt_cache_key` only when a real client-provided session identity exists, canonicalize JSON keys in outgoing request bodies plus `tool_call` arguments and `tool_result` content, and thread `session_id` into the usage logger); correct Anthropic ↔ OpenAI `tool_choice` mapping; Vertex AI full URLs are no longer truncated; Gemini request models are now extracted from the URI path; takeover detection is tightened; and IPv6 listen addresses are supported. ChatGPT Codex OAuth providers no longer depend on hardcoded model lists — CC Switch now fetches a live model list from the ChatGPT backend on demand.
|
||||
|
||||
Claude Code's model mapping is now role-based (`sonnet` / `opus` / `haiku`) with display names and a new `supports1m` boolean flag, replacing the legacy `[1M]` suffix and decoupling routing decisions from raw model IDs. The usage dashboard adds a **filter-driven Hero card** that exposes cache-normalized real total tokens and cache hit rate, updated live as the active date range / provider / model filters change; paired with a fix for cache-cost semantics and the noisy pricing warning storm that fired on every request. Robustness improvements in the OpenAI Responses API usage parsing path mean missing or malformed upstream `usage` no longer crashes the VSCode Claude Code extension with a `null` output.
|
||||
|
||||
The provider ecosystem expands further: new BytePlus, Volcengine Agentplan, ClaudeAPI, ClaudeCN, RunAPI, RelaxyCode, PatewayAI, and Baidu Qianfan Coding Plan partner presets; DouBao Seed is promoted to partner status; and provider cards now surface a "routing support" badge so users can tell at a glance which providers can be served through Local Routing. This release also fixes a long tail of issues across Codex sessions, OAuth, Claude Desktop forms, Linux segfaults, terminal fallbacks, and ships several GitHub Actions dependency bumps.
|
||||
|
||||
**Release date**: 2026-05-16
|
||||
|
||||
**Stats**: 127 commits | 211 files changed | +17,980 insertions | -2,748 deletions
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- **Claude Desktop Becomes a First-Class Managed Surface**: Third-party provider switching through the in-app proxy gateway, role-based model mapping (`sonnet` / `opus` / `haiku`) with a `supports1m` long-context flag, Copilot/Codex OAuth provider reuse, and 44 provider presets translated from the Claude Code catalog. Note: 20 Claude Desktop presets now default to direct mode instead of proxy mode — verify connectivity after upgrade if you previously relied on proxy routing.
|
||||
- **Major Reverse-Proxy Hardening**: P0–P3 lifecycle / retry / failover / rectifier patches; pooled HTTPS reuse for non-Anthropic backends; Codex / Responses cache hit-rate improvements; correct Anthropic ↔ OpenAI `tool_choice` mapping; Vertex AI URL preservation; Gemini path-based model extraction; refined takeover detection; IPv6 listen address support.
|
||||
- **Provider Ecosystem Expansion**: New BytePlus, Volcengine Agentplan, ClaudeAPI, ClaudeCN, RunAPI, RelaxyCode, PatewayAI, and Baidu Qianfan Coding Plan partner presets; DouBao Seed promoted to partner status; routing-support badges on provider cards.
|
||||
- **Role-Based Model Mapping with 1M Flag**: Role-based `sonnet` / `opus` / `haiku` routing with display names and a `supports1m` flag replaces the legacy `[1M]` suffix.
|
||||
- **Codex OAuth Live Model Discovery**: ChatGPT Codex providers fetch the live model list from the ChatGPT backend on demand.
|
||||
- **Usage Dashboard Filter-Driven Hero**: Surfaces cache-normalized real total tokens and cache hit rate, updated live as date / provider / model filters change.
|
||||
- **DeepSeek Tool Calls + Zero-Usage Final Delta**: DeepSeek tool calls now return `reasoning_content` alongside `tool_calls` (#2543, thanks @bling-yshs); the final `message_delta` always includes a usage block (even when zero) so strict Anthropic clients no longer crash on `null` (#2485, thanks @Myoontyee).
|
||||
- **OpenAI Responses API Usage Parsing Robustness**: Missing or malformed upstream `usage` no longer crashes the VSCode Claude Code extension (#2422, thanks @magucas).
|
||||
|
||||
---
|
||||
|
||||
## Added
|
||||
|
||||
### Claude Desktop Third-Party Provider Switching via Proxy Gateway
|
||||
|
||||
CC Switch now treats **Claude Desktop** as a first-class managed surface alongside Claude Code / Codex / Gemini / OpenCode / OpenClaw / Hermes.
|
||||
|
||||
- New dedicated Claude Desktop panel that brokers third-party providers to Claude Desktop through CC Switch's in-app proxy gateway
|
||||
- Routing-support badge on cards for providers that need Local Routing
|
||||
- Role-based model route mapping locked to `sonnet` / `opus` / `haiku`
|
||||
- Copilot / Codex OAuth providers can be reused in the Claude Desktop panel
|
||||
- Redesigned Claude Code settings import flow
|
||||
- App switcher visually distinguishes "Claude Code" from "Claude Desktop", and the app visibility settings use the "Claude Code" label
|
||||
- 44 Claude Desktop provider presets translated from the Claude Code preset catalog
|
||||
|
||||
### Routing Support Badges on Provider Cards
|
||||
|
||||
Provider cards in both the Claude Code and Codex panels now show a routing-support badge so users can tell at a glance which providers can be served through Local Routing.
|
||||
|
||||
### Codex OAuth Live Model List
|
||||
|
||||
ChatGPT Codex providers no longer rely on a hardcoded model selection — CC Switch fetches a **live model list** from the ChatGPT backend on demand.
|
||||
|
||||
### Role-Based Model Mapping with 1M Flag
|
||||
|
||||
Claude Code model mapping is now role-based (`sonnet` / `opus` / `haiku`) with display names and a `supports1m` boolean flag, replacing the legacy `[1M]` suffix and decoupling routing from raw model IDs.
|
||||
|
||||
### Filter-Driven Usage Hero
|
||||
|
||||
The usage dashboard's Hero summary is now filter-driven, updating live as the active date range / provider / model filters change; it surfaces **cache-normalized real total tokens** and cache hit rate so the Hero figures line up with the detail list below.
|
||||
|
||||
### Provider Form "Save Anyway" Prompt
|
||||
|
||||
Softened provider form input validation by turning non-blocking input issues into a "save anyway" prompt, so a harmless field issue no longer blocks saving (#2307, thanks @allenxln).
|
||||
|
||||
### Universal Provider Duplicate Action
|
||||
|
||||
Added a "duplicate" button for universal providers from the provider list (#2416, thanks @hubutui).
|
||||
|
||||
### Persisted Tauri Window State
|
||||
|
||||
Window position and size now persist across launches (#2377, thanks @BillSaul).
|
||||
|
||||
### Tray Icon Tooltip
|
||||
|
||||
The system tray icon now surfaces a status tooltip on hover (#2417, thanks @Coconut-Fish).
|
||||
|
||||
### Warp Terminal Session Launch
|
||||
|
||||
Added support for launching Warp and executing a saved session inside it (#2466, thanks @tisonkun).
|
||||
|
||||
### DeepSeek `reasoning_content` for Tool Calls
|
||||
|
||||
DeepSeek tool-call responses now return `reasoning_content` and `tool_calls` together, so callers can render both (#2543, thanks @bling-yshs).
|
||||
|
||||
### Baidu Qianfan Coding Plan (Claude Code)
|
||||
|
||||
Added a Baidu Qianfan Coding Plan preset (#2322, thanks @jimmyzhuu).
|
||||
|
||||
### Compshare Coding Plan Preset (Cross-App)
|
||||
|
||||
The Compshare Coding Plan preset now lands across claude / codex / hermes / openclaw.
|
||||
|
||||
### Partner Provider Presets
|
||||
|
||||
Added **BytePlus**, **Volcengine Agentplan**, **ClaudeAPI**, **ClaudeCN**, **RunAPI**, **RelaxyCode**, and **PatewayAI** partner presets; promoted **DouBao Seed** to partner status (refreshed endpoint and links).
|
||||
|
||||
### 44 Claude Desktop Provider Presets
|
||||
|
||||
Translated 44 provider presets from the Claude Code preset catalog into the new Claude Desktop panel.
|
||||
|
||||
---
|
||||
|
||||
## Changed
|
||||
|
||||
### 20 Claude Desktop Presets Default to Direct Mode
|
||||
|
||||
20 Claude Desktop presets now ship in direct mode instead of routing through the proxy by default, reducing setup friction for users who don't need proxy-specific compatibility shims. If you previously relied on proxy routing for these presets, verify connectivity after upgrading.
|
||||
|
||||
### Claude Desktop Operational Notes
|
||||
|
||||
Switching a Claude Desktop provider writes CC Switch's managed 3P profile and **requires restarting Claude Desktop** to take effect; proxy-mode providers require CC Switch's Local Routing to stay running while in use.
|
||||
|
||||
### Failover / Local Routing Guardrails
|
||||
|
||||
Failover controls now require the target app's Local Routing takeover to be enabled before they can be turned on; stopping only the proxy service is blocked while any app still depends on takeover state, preventing the "proxy stopped but the app still thinks takeover is running" inconsistency.
|
||||
|
||||
### Usage Accounting Semantics Changed
|
||||
|
||||
Usage summaries now report **cache-normalized real total tokens** and **cache hit rate**. Historical token and cost figures may **shift** after deduplication and pricing recalculation — the new numbers are more accurate but will not equal the values reported in earlier versions.
|
||||
|
||||
### Provider Preset Rendering Order
|
||||
|
||||
Preset lists now render in the author-defined array order, with partners prioritized first, replacing the previous implicit sort.
|
||||
|
||||
### Model Mapping Hint Copy Simplified
|
||||
|
||||
`modelMappingOffHint` was rewritten as action-oriented copy across zh / en / ja.
|
||||
|
||||
### CC Switch Brand Surface Unified to ccswitch.io
|
||||
|
||||
All in-app and README "official website" references now point at ccswitch.io as the sole official site; the release notes template also surfaces ccswitch.io.
|
||||
|
||||
### Theme Switch Simplified
|
||||
|
||||
Removed the circular reveal animation during theme switches; theme changes are now an instant cross-fade.
|
||||
|
||||
### Claude Code App Switcher Differentiation
|
||||
|
||||
The app switcher visually distinguishes "Claude Code" from "Claude Desktop", and the app visibility settings use the "Claude Code" label.
|
||||
|
||||
### CI: Claude Review Upgraded to Opus 4.7
|
||||
|
||||
The Claude review GitHub Action is upgraded to Opus 4.7; the prompt is tuned to reduce nitpick noise; a new `@claude` review-only Code Action is added; PR head SHA is pinned for checkout; the `--max-turns 5` limit is removed.
|
||||
|
||||
### GitHub Actions Dependency Bumps
|
||||
|
||||
- `actions/checkout` 4 → 6 (#2517)
|
||||
- `pnpm/action-setup` 5 → 6 (#2518)
|
||||
- `softprops/action-gh-release` 2 → 3 (#2519)
|
||||
- `actions/stale` 9 → 10 (#2520)
|
||||
|
||||
### DeepSeek Presets Switched to V4
|
||||
|
||||
DeepSeek presets now ship V4 (flash / pro) with refreshed pricing seeds.
|
||||
|
||||
### Codex 1M Context Toggle Hidden in Edit Form
|
||||
|
||||
The 1M context-window toggle is no longer surfaced in the Codex provider edit form, reducing the density of knobs that have no effect in current Codex deployments.
|
||||
|
||||
### OpenClaudeCode Migrated to MicuAPI Domain
|
||||
|
||||
The OpenClaudeCode preset is migrated to the MicuAPI domain; Micu API links are refreshed to `micuapi.ai`.
|
||||
|
||||
### CrazyRouter Endpoints Switched to `cn` Subdomain
|
||||
|
||||
CrazyRouter preset endpoints now use the `cn` subdomain.
|
||||
|
||||
### RelaxyCode Custom Icon
|
||||
|
||||
The RelaxyCode preset icon is switched to a custom `relaxcode.png` asset.
|
||||
|
||||
### Kimi For Coding Doc URL
|
||||
|
||||
The Kimi For Coding website URL is updated to the `/code/docs/` path.
|
||||
|
||||
### SiliconFlow International Site Shows USD
|
||||
|
||||
The SiliconFlow international site now correctly shows USD for balance display (it previously displayed CNY incorrectly).
|
||||
|
||||
---
|
||||
|
||||
## Fixed
|
||||
|
||||
### OpenAI Responses API Usage Parsing Robustness
|
||||
|
||||
Hardened `build_anthropic_usage_from_responses()` and the Responses → Anthropic SSE translator so a missing or malformed upstream `usage` no longer produces `"usage": null` in `message_delta`. This unblocks strict Anthropic clients (notably the VSCode Claude Code extension) that crashed with `Cannot read properties of null (reading 'output_tokens')` against providers such as Codex OAuth and DashScope's `compatible-mode/v1/responses` endpoint. Added OpenAI field-name fallbacks (`prompt_tokens` / `completion_tokens`), null / empty / partial object handling, and preserved cache token fields even when input/output tokens are missing (#2422, thanks @magucas).
|
||||
|
||||
### Proxy Reliability Patches (P0–P3)
|
||||
|
||||
Multiple rounds of routing / lifecycle / retry / rectifier patches across the request-forwarder paths; extracted a shared `handle_rectifier_retry_failure` helper and a shared `auth_header_value` helper.
|
||||
|
||||
### Proxy: Pooled HTTPS Connection Reuse for Non-Anthropic Backends
|
||||
|
||||
Non-Anthropic backends now reuse pooled HTTPS connections instead of opening a fresh TLS session per request, materially reducing per-request latency.
|
||||
|
||||
### Proxy: Forward Client's Actual HTTP Method
|
||||
|
||||
The proxy no longer hard-codes `POST` — it forwards the client's actual HTTP method, so non-POST upstream endpoints (e.g. GET `/v1/models`) now work correctly.
|
||||
|
||||
### Proxy: Per-Attempt Counters and `max_retries` Wiring
|
||||
|
||||
Client-request counters are moved out of the per-attempt loop; `AppProxyConfig.max_retries` is now correctly wired into the request forwarder.
|
||||
|
||||
### Proxy: Failover Decision Refinements
|
||||
|
||||
Refined retryable vs. unretryable error classification in the request forwarder.
|
||||
|
||||
### Proxy: Takeover Detection Tightening
|
||||
|
||||
Takeover detection is tightened; disabling takeover uses fallback restore, so leftover state no longer strands a provider.
|
||||
|
||||
### Proxy: Anthropic ↔ OpenAI `tool_choice` Mapping
|
||||
|
||||
During format conversion, Anthropic's `tool_choice` is now correctly mapped to the OpenAI Chat nested form.
|
||||
|
||||
### Proxy: Gemini Request Model Extracted from URI Path
|
||||
|
||||
Gemini request models are now extracted from the URI path (instead of the body), so transformed traffic reports the right model name.
|
||||
|
||||
### Proxy: Auth Header Error Handling
|
||||
|
||||
`get_auth_headers` now returns `Result` instead of panicking on bad credentials.
|
||||
|
||||
### Proxy: IPv6 Listen Address Validation
|
||||
|
||||
The Proxy panel now accepts IPv6 listen addresses.
|
||||
|
||||
### Proxy: Codex / Responses Cache Hit Rate
|
||||
|
||||
Improved cache hit rate for Codex and OpenAI Responses requests by stabilizing cache key derivation: emit `prompt_cache_key` only when the client actually carries a session identity, so unrelated conversations no longer collapse onto a single key; canonicalize (sort) JSON keys in outgoing request bodies and in `tool_call` arguments / `tool_result` content for byte-identical prefix-cache reuse; thread `session_id` into the usage logger for request correlation.
|
||||
|
||||
### Proxy: JSON Schema Underscore Fields Preserved
|
||||
|
||||
Private-parameter filtering now preserves underscore-prefixed field names inside JSON Schema name maps (`properties`, `patternProperties`, `definitions`, `$defs`), so user-defined schema keys like `_id` and `_meta` pass through the filter intact.
|
||||
|
||||
### Proxy: Read Tool Empty Pages
|
||||
|
||||
Drop empty pages from `Read` tool inputs so providers no longer reject the request (#2472, thanks @Kwensiu).
|
||||
|
||||
### Proxy: Per-Request Hot-Path Trim
|
||||
|
||||
Trimmed per-request hot-path work and database wait time.
|
||||
|
||||
### Proxy: Real Provider Model Names Under Takeover
|
||||
|
||||
Under takeover, the Claude Code menu now exposes the real provider model names instead of a stale alias.
|
||||
|
||||
### Proxy: Zero Usage in Final `message_delta`
|
||||
|
||||
The final `message_delta` event now always includes a usage block (even when zero) so strict Anthropic clients no longer crash on `null` (#2485, thanks @Myoontyee).
|
||||
|
||||
### Proxy: Streaming `message_delta` Deduplication
|
||||
|
||||
Deduplicated `message_delta` events that some upstreams emit twice (#2366, thanks @codeasier).
|
||||
|
||||
### Proxy: Scoped `reasoning_content` Preserved for Tool Calls
|
||||
|
||||
Tool-call paths now correctly preserve the scoped `reasoning_content` field during transformation; Kimi / Moonshot's OpenAI Chat compatibility path keeps the field while generic OpenAI-compatible requests stay free of it (#2367, thanks @codeasier).
|
||||
|
||||
### Proxy: Vertex AI Full URL Preserved
|
||||
|
||||
Full Vertex AI URLs are no longer truncated during proxy forwarding (#2415, thanks @xpfo-go).
|
||||
|
||||
### Proxy: Leading Billing Header Stripped from System Content
|
||||
|
||||
Some upstreams prepend a billing-header chunk to the system message; this content is now stripped (#2350).
|
||||
|
||||
### Proxy: Claude Auth Strategy Derived from `ANTHROPIC_*` Env Var
|
||||
|
||||
The Claude auth strategy is now derived from the actual `ANTHROPIC_*` env variable name rather than an opaque heuristic.
|
||||
|
||||
### Third-Party Claude Providers: Disable Model Test
|
||||
|
||||
Model probing is disabled for third-party Claude gateways that don't implement `/v1/models` consistently.
|
||||
|
||||
### Model-Fetch: `/models` for Anthropic-Compatible Subpath Providers
|
||||
|
||||
`/models` discovery now works for Anthropic-compatible subpath providers.
|
||||
|
||||
### Copilot: Claude Model IDs Resolved Against Live `/models`
|
||||
|
||||
Copilot-backed providers now resolve Claude model IDs against the live `/models` list to avoid stale ID mismatches.
|
||||
|
||||
### Codex: Session Title No Longer Pulls in `environment_context`
|
||||
|
||||
Codex session title extraction no longer pulls in the `environment_context` noise (#2439, thanks @eclipsehx).
|
||||
|
||||
### Codex: Subagent Sessions Hidden
|
||||
|
||||
Codex subagent sessions are now hidden from the main session list (#2445, thanks @LanternCX).
|
||||
|
||||
### Codex Startup Live Import Duplication
|
||||
|
||||
Fixed a duplicate-import bug in the Codex startup live-import path (#2590, thanks @DhruvShankpal).
|
||||
|
||||
### Codex Provider Switch No Longer Disturbs History
|
||||
|
||||
Switching the active Codex provider no longer changes existing session history (#2349, thanks @SaladDay).
|
||||
|
||||
### Codex Usage Log Wording
|
||||
|
||||
Corrected a misleading log message for Codex session usage (#2473, thanks @tisonkun).
|
||||
|
||||
### Claude: Persist `max` Effort via Env
|
||||
|
||||
`max` effort now correctly persists across restart via the env variable (#2493, thanks @makoMakoGo).
|
||||
|
||||
### Claude Desktop: Model Route Matching Without `[1M]` Suffix
|
||||
|
||||
Route matching no longer requires the legacy `[1M]` suffix.
|
||||
|
||||
### Claude Desktop: Provider Form Input Focus Loss
|
||||
|
||||
Fixed an input in the Claude Desktop provider form that lost focus while being edited.
|
||||
|
||||
### Claude Desktop: Spurious Proxy-Stopped Status Alert
|
||||
|
||||
Removed an alert that fired spuriously when the proxy was intentionally stopped.
|
||||
|
||||
### Claude Desktop: Empty Toolbar Capsule Hidden
|
||||
|
||||
The empty toolbar capsule is now hidden when Claude Desktop is the active app.
|
||||
|
||||
### UI: Monitor Badge Icon Centering
|
||||
|
||||
Centered the Monitor badge icon in the app switcher.
|
||||
|
||||
### Linux: Theme Selection Segfault
|
||||
|
||||
Prevented a segfault triggered by selecting a theme on Linux (#2502, thanks @definfo).
|
||||
|
||||
### Terminal: iTerm Fallback on Cold Launch
|
||||
|
||||
Prevented iTerm from being selected as a fallback on cold launch when it isn't actually installed (#2448, thanks @hulkbig).
|
||||
|
||||
### Config: JSON Keys Sorted Alphabetically
|
||||
|
||||
Config writes now sort JSON keys alphabetically for deterministic output (#2469, thanks @fuleinist).
|
||||
|
||||
### "Import Existing" Made Side-Effect Free
|
||||
|
||||
The "import existing" action is now side-effect free (#2429, thanks @xwil1).
|
||||
|
||||
### Coding Plan: Zhipu Weekly Tier Named by Reset Time
|
||||
|
||||
Corrected the Zhipu weekly tier name to match the actual reset time (#2420, thanks @TuYv).
|
||||
|
||||
### DashScope: Usage Parsing Robustness
|
||||
|
||||
Hardened DashScope usage parsing so a malformed payload no longer crashes the VSCode Claude Code extension (#2425, thanks @magucas).
|
||||
|
||||
### Usage: Deduplicate Proxy and Session-Log Sources
|
||||
|
||||
Deduplicated usage records sourced from both the proxy and session logs.
|
||||
|
||||
### Usage: Cache Cost Semantics + Pricing Warn Storm
|
||||
|
||||
Corrected cache-cost semantics and silenced the noisy pricing warning that fired on every request.
|
||||
|
||||
### CI: Frontend Formatting + Linux Clippy Restored
|
||||
|
||||
Restored frontend formatting and Linux clippy checks in CI.
|
||||
|
||||
### Proxy Test Helper Clippy Warning
|
||||
|
||||
Fixed a clippy warning in the proxy test helper.
|
||||
|
||||
---
|
||||
|
||||
## Removed
|
||||
|
||||
### Hermes Agent Usage Tracking Integration
|
||||
|
||||
Removed the Hermes Agent usage tracking integration originally planned for this cycle — upstream behavior changes made the integration impractical to maintain. The integration was **never enabled in any released version**; the "zero-cost rendering" bug discovered during its development was fixed before the integration was rolled back.
|
||||
|
||||
### Theme Switch Circular Reveal Animation
|
||||
|
||||
Removed the circular reveal animation used during theme switches — it stuttered on slower compositors and added little visible value.
|
||||
|
||||
### DDSHub Partner Integration
|
||||
|
||||
Removed DDSHub as a partner preset and dropped the cross-link blurbs from the READMEs.
|
||||
|
||||
---
|
||||
|
||||
## Docs
|
||||
|
||||
### README Sponsor Refresh (zh / en / ja)
|
||||
|
||||
Added BytePlus, ClaudeCN, RunAPI, and PatewayAI sponsor entries; cross-linked BytePlus and Volcengine entries; refreshed the CrazyRouter $2 credit claim flow, the Compshare blurb, the Right Code blurb, and other sponsor logos and listings; flattened the LionCC logo onto a white background; switched the Chinese README's sponsor logo to the Volcengine artwork; added Hermes Agent to the README subtitles.
|
||||
|
||||
### Release Notes Template
|
||||
|
||||
The release notes template now surfaces `ccswitch.io`.
|
||||
|
||||
### Brand Surface
|
||||
|
||||
Documented `ccswitch.io` as the sole official website across READMEs and in-app references.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Upgrade Notes
|
||||
|
||||
### 20 Claude Desktop Presets Default to Direct Mode
|
||||
|
||||
These 20 presets previously routed through the proxy by default and now default to direct mode. If you were using one of these presets pre-upgrade and depended on the proxy path for connectivity (for example because the proxy applies a special rectifier or transformation layer), verify connectivity after upgrading; you can manually switch them back to proxy mode from the CC Switch panel if needed.
|
||||
|
||||
### Claude Desktop Operational Constraints
|
||||
|
||||
Switching a Claude Desktop provider **requires restarting Claude Desktop** to take effect; proxy-mode providers require CC Switch's Local Routing to stay running while in use — quitting CC Switch or stopping Local Routing will cut off any proxy-mode Claude Desktop providers.
|
||||
|
||||
### Failover Requires Takeover Enabled
|
||||
|
||||
Before enabling Failover, make sure the target app's Local Routing takeover is enabled, otherwise the Failover control will refuse to start; stopping the proxy service while any app still depends on takeover state is blocked, so you need to disable takeover at the app layer first before stopping the proxy.
|
||||
|
||||
### Usage Figures May Diverge from History
|
||||
|
||||
Usage summaries now use cache-normalized real total tokens + cache hit rate. Historical token and cost figures may **shift** after deduplication and pricing recalculation — the new numbers are more accurate but will not equal what earlier versions reported.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Risk Notice
|
||||
|
||||
This release inherits the risk notices originally introduced in v3.12.3 / v3.13.0 for reverse-proxy-style features.
|
||||
|
||||
**GitHub Copilot Reverse Proxy**: Using Copilot's reverse-proxy path may violate GitHub / Microsoft's terms of service. See the [v3.12.3 release notes](v3.12.3-en.md#️-risk-notice) for details.
|
||||
|
||||
**Codex OAuth Reverse Proxy**: Using the Codex OAuth reverse proxy with a ChatGPT subscription may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details.
|
||||
|
||||
**Claude Desktop Third-Party Provider Switching via Proxy Gateway**: Routing Claude Desktop traffic through CC Switch's in-app proxy gateway to a third-party provider exposes those requests to that provider's billing, compliance, and data-retention policies — read the target provider's terms of service before using.
|
||||
|
||||
By enabling these features, users **accept all associated risks**. CC Switch is not responsible for any account restrictions, warnings, or service suspensions that result from using these features.
|
||||
|
||||
---
|
||||
|
||||
## Download & Installation
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download the appropriate version.
|
||||
|
||||
### System Requirements
|
||||
|
||||
| OS | Minimum Version | Architecture |
|
||||
| ------- | ---------------------------- | ----------------------------------- |
|
||||
| Windows | Windows 10 or later | x64 |
|
||||
| macOS | macOS 12 (Monterey) or later | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | See table below | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| File | Description |
|
||||
| ---------------------------------------- | ----------------------------------------------------- |
|
||||
| `CC-Switch-v3.15.0-Windows.msi` | **Recommended** - MSI installer, supports auto-update |
|
||||
| `CC-Switch-v3.15.0-Windows-Portable.zip` | Portable, extract and run, no registry writes |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| -------------------------------- | ------------------------------------------------------- |
|
||||
| `CC-Switch-v3.15.0-macOS.dmg` | **Recommended** - DMG installer, drag into Applications |
|
||||
| `CC-Switch-v3.15.0-macOS.zip` | Extract and drag into Applications, Universal Binary |
|
||||
| `CC-Switch-v3.15.0-macOS.tar.gz` | For Homebrew installation and auto-update |
|
||||
|
||||
> macOS builds are Apple code-signed and notarized — install directly.
|
||||
|
||||
### Homebrew (macOS)
|
||||
|
||||
> 🎉 CC Switch is now available in the official Homebrew cask repository — no need to add a custom tap!
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
> Linux artifacts are published for both **x86_64** and **ARM64** (`aarch64`). The architecture is included in the asset filename — pick the one matching your machine's `uname -m` output:
|
||||
>
|
||||
> - `CC-Switch-v3.15.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
> - `CC-Switch-v3.15.0-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| Distribution | Recommended | Installation |
|
||||
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| 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, or use AUR |
|
||||
| Other distros / not sure | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
@@ -0,0 +1,527 @@
|
||||
# CC Switch v3.15.0
|
||||
|
||||
> Claude Desktop が一等管理パネルに昇格（プロキシゲートウェイ経由のサードパーティプロバイダー切り替えを含む）、ロールベースのモデルマッピング、リバースプロキシの大幅強化、Codex OAuth ライブモデル検出、Usage ダッシュボードのフィルター駆動 Hero カード
|
||||
|
||||
**[English →](v3.15.0-en.md) | [中文 →](v3.15.0-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## 唯一の公式チャネル（必ずお読みください）
|
||||
>
|
||||
> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。最近、CC Switch の名を騙って課金を要求したり認証情報を収集する偽サイトが複数確認されており、一部のユーザーには既に金銭的被害が発生しています。本ソフトウェアは下記の公式チャネルからのみ入手してください：
|
||||
>
|
||||
> | チャネル | 唯一の公式 |
|
||||
> | ------------ | ------------------------------------------------------------------------------ |
|
||||
> | 公式サイト | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | 作者 | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は、直ちに取引を中止し、偽サイトを速やかに削除できるよう GitHub Issues からご報告ください。
|
||||
|
||||
---
|
||||
|
||||
## Claude Desktop 利用ガイド
|
||||
|
||||
本リリースの主役は **Claude Desktop の一等管理パネル**です。すでに Claude Code 側で多くのプロバイダーを設定している場合は、まずこのガイドをご覧ください：
|
||||
|
||||
**[CC Switch で Claude Desktop プロバイダーを一括設定・管理・切り替える](../user-manual/ja/2-providers/2.6-claude-desktop.md)**
|
||||
|
||||
このガイドでは、Claude Code から既存プロバイダーを一括インポートする方法、Claude Desktop 専用プロバイダーの追加、直結 / モデルマッピングの 2 モード、非表示のローカルルーティング切り替えを表示する設定、Claude Desktop 公式サインインモードへの復帰までを説明しています。
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.15.0 は v3.14.x に続く大型バージョンアップで、コアの焦点は **Claude Desktop を一等管理パネルに昇格させること**にあります。これに合わせて、内蔵プロキシゲートウェイを介したサードパーティプロバイダーの切り替え、ロールベースのモデルマッピング（sonnet / opus / haiku）+ `supports1m` ロングコンテキストフラグ、Copilot / Codex OAuth プロバイダーの再利用、再設計された Claude Code インポートフロー、App スイッチャーでの「Claude Code」と「Claude Desktop」の視覚的な区別、そして Claude Code プリセットディレクトリから翻訳された 44 個の Claude Desktop プリセットを提供します。
|
||||
|
||||
リバースプロキシの信頼性については、本リリースで系統的なハードニングを行いました: P0–P3 の複数回にわたるルーティング / ライフサイクル / リトライ / フェイルオーバー / 補正器の修正; 非 Anthropic バックエンドで HTTPS コネクションプールを再利用してリクエスト単位のレイテンシを低減; Codex と OpenAI Responses のキャッシュヒット率改善（`prompt_cache_key` は本物のクライアントセッション識別子がある場合のみ送信、外部リクエストボディと `tool_call` 引数 / `tool_result` 内容の JSON キーを正規化してソート、`session_id` を Usage ロガーに通す）; Anthropic ↔ OpenAI `tool_choice` の正しい相互変換; Vertex AI の完全な URL を切り詰めない; Gemini は URI パスからモデル名を抽出するように変更; Local Routing のテイクオーバー検出をより精緻化; IPv6 リッスンアドレスのサポート。Codex OAuth 系の Claude プロバイダーはハードコードされたモデルリストに依存しなくなり、CC Switch が必要に応じて ChatGPT バックエンドからライブモデルリストを取得します。
|
||||
|
||||
Claude Code のモデルマッピングはロールベース（`sonnet` / `opus` / `haiku`）+ 表示名に変更され、`supports1m` 真偽値フラグが導入されました。これは旧来の `[1M]` サフィックス記法に取って代わり、ルーティング判定と元のモデル ID を分離します。Usage ダッシュボードには**フィルター駆動 Hero カード**が追加され、キャッシュ正規化後の真の総トークン数とキャッシュヒット率を表示し、現在の日付範囲 / プロバイダー / モデルのフィルターに追従してリアルタイム更新します。あわせてキャッシュコストのセマンティクスエラーと、リクエストごとに発生していた pricing 警告ノイズを修正しました。OpenAI Responses API の usage 解析パスを堅牢化し、上流の欠損または不正な `usage` のせいで VSCode Claude Code プラグインが `null` 出力でクラッシュしないようにしました。
|
||||
|
||||
プロバイダーエコシステムはさらに拡張されました: BytePlus、Volcengine Agentplan、ClaudeAPI、ClaudeCN、RunAPI、RelaxyCode、PatewayAI、Baidu Qianfan Coding Plan のパートナープリセットを追加; Doubao Seed をパートナープリセットに昇格; プロバイダーカードに「Local Routing 対応」バッジを表示。本リリースでは、Codex セッション、OAuth、Claude Desktop フォーム、Linux segfault、ターミナルフォールバックなどに関する多くの細部の問題も修正し、複数の GitHub Actions 依存関係をアップグレードしました。
|
||||
|
||||
**リリース日**: 2026-05-16
|
||||
|
||||
**Stats**: 127 commits | 211 files changed | +17,980 insertions | -2,748 deletions
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **Claude Desktop が一等管理パネルに**: 内蔵プロキシゲートウェイを介したサードパーティプロバイダーの切り替え、ロールベースのモデルマッピング（sonnet / opus / haiku）+ `supports1m` ロングコンテキストフラグ、Copilot / Codex OAuth プロバイダーの再利用、Claude Code プリセットディレクトリから翻訳された 44 個のプリセットを提供。注意: 20 個の Claude Desktop プリセットがデフォルトでプロキシモードから直接接続モードに切り替わったため、アップグレード後にプロキシルーティングに依存している場合は接続性を検証してください
|
||||
- **リバースプロキシの大幅強化**: P0–P3 のライフサイクル / リトライ / フェイルオーバー / 補正器の修正; 非 Anthropic バックエンドの HTTPS コネクションプール再利用; Codex / Responses キャッシュヒット率改善; Anthropic ↔ OpenAI `tool_choice` の正しいマッピング; Vertex AI URL の完全保持; Gemini パスベースのモデル抽出; テイクオーバー検出の精緻化; IPv6 リッスンアドレスのサポート
|
||||
- **プロバイダーエコシステムの拡張**: BytePlus、Volcengine Agentplan、ClaudeAPI、ClaudeCN、RunAPI、RelaxyCode、PatewayAI、Baidu Qianfan Coding Plan のパートナープリセットを追加; Doubao Seed をパートナーに昇格; プロバイダーカードに「ルーティングプロキシ対応」バッジを表示
|
||||
- **ロールベースのモデルマッピング + 1M フラグ**: ロールベースの sonnet / opus / haiku ルーティング + 表示名 + `supports1m` フラグ。旧来の `[1M]` サフィックスに取って代わる
|
||||
- **Codex OAuth ライブモデル検出**: ChatGPT Codex 系プロバイダーは必要に応じて ChatGPT バックエンドからライブモデルリストを取得
|
||||
- **Usage ダッシュボードのフィルター駆動 Hero**: キャッシュ正規化後の真の総トークン数とキャッシュヒット率を表示し、現在の日付 / プロバイダー / モデルフィルターに追従してリアルタイム更新
|
||||
- **DeepSeek ツール呼び出し + ゼロ usage 最終 delta**: DeepSeek のツール呼び出しが `reasoning_content` も返却するように (#2543, 感謝 @bling-yshs); 最終 `message_delta` は常に usage ブロックを含む（すべてゼロでも）ため、厳格な Anthropic クライアントが `null` でクラッシュしなくなった (#2485, 感謝 @Myoontyee)
|
||||
- **OpenAI Responses API usage 解析の堅牢化**: 上流の欠損または不正な usage によって VSCode Claude Code プラグインがクラッシュしないように (#2422, 感謝 @magucas)
|
||||
|
||||
---
|
||||
|
||||
## 追加機能
|
||||
|
||||
### Claude Desktop サードパーティプロバイダーのプロキシ切り替え
|
||||
|
||||
CC Switch は初めて **Claude Desktop** を一等管理対象パネルとして扱い、Claude Code / Codex / Gemini / OpenCode / OpenClaw / Hermes と並列に位置づけます。
|
||||
|
||||
- Claude Desktop 専用パネルを追加し、CC Switch 内蔵プロキシゲートウェイを介してサードパーティプロバイダーを Claude Desktop に代理転送
|
||||
- ルーティングプロキシを必要とするプロバイダーには、カード上に「Local Routing 対応」バッジを表示
|
||||
- ロールベースのモデルルーティングマッピングで `sonnet` / `opus` / `haiku` にロック
|
||||
- Copilot / Codex OAuth プロバイダーを Claude Desktop パネルで再利用可能
|
||||
- 再設計された Claude Code 設定インポートフロー
|
||||
- App スイッチャーで「Claude Code」と「Claude Desktop」を視覚的に区別、アプリ可視性設定では「Claude Code」ラベルを使用
|
||||
- Claude Code プリセットディレクトリから翻訳された 44 個の Claude Desktop プロバイダープリセット
|
||||
|
||||
### プロバイダーカード: ルーティングプロキシ対応バッジ
|
||||
|
||||
Claude Code と Codex パネルのプロバイダーカードに「ルーティングプロキシ対応」バッジを追加し、Local Routing 経由で提供可能なプロバイダーを一目で識別できるようにしました。
|
||||
|
||||
### Codex OAuth ライブモデルリスト
|
||||
|
||||
ChatGPT Codex 系プロバイダーはハードコードされたモデル選択に依存しなくなり、CC Switch が必要に応じて ChatGPT バックエンドから**ライブモデルリスト**を取得します。
|
||||
|
||||
### ロールベースのモデルマッピング + 1M フラグ
|
||||
|
||||
Claude Code のモデルマッピングはロールベース（`sonnet` / `opus` / `haiku`）+ 表示名に変更され、`supports1m` 真偽値フラグが導入されました。これは旧来の `[1M]` サフィックス記法に取って代わり、ルーティング判定と元のモデル ID を分離します。
|
||||
|
||||
### Usage ダッシュボードのフィルター駆動 Hero
|
||||
|
||||
Usage ダッシュボードの Hero サマリーがフィルター駆動になり、現在の日付範囲 / プロバイダー / モデルフィルターに追従してリアルタイムに変化します。**キャッシュ正規化後の真の総トークン数**とキャッシュヒット率を表示することで、Hero の数値が下部の詳細リストと整合するようになります。
|
||||
|
||||
### プロバイダーフォームの「とりあえず保存」
|
||||
|
||||
プロバイダーフォームの入力検証を緩和し、非ブロッキングな入力上の問題を「とりあえず保存」型のヒントに変更しました。無害な軽微なフィールド問題が原因で保存が阻まれることがなくなります (#2307, 感謝 @allenxln)。
|
||||
|
||||
### Universal プロバイダーの複製アクション
|
||||
|
||||
プロバイダーリスト内の universal プロバイダーに「複製」ボタンを追加しました (#2416, 感謝 @hubutui)。
|
||||
|
||||
### Tauri ウィンドウ状態の永続化
|
||||
|
||||
ウィンドウの位置とサイズが再起動をまたいで保持されるようになりました (#2377, 感謝 @BillSaul)。
|
||||
|
||||
### トレイアイコンのホバーヒント
|
||||
|
||||
システムトレイアイコンにホバー時のステータスヒントを表示するようになりました (#2417, 感謝 @Coconut-Fish)。
|
||||
|
||||
### Warp ターミナルセッション起動
|
||||
|
||||
Warp ターミナルのサポートを追加し、保存されたセッションを Warp で実行できるようになりました (#2466, 感謝 @tisonkun)。
|
||||
|
||||
### DeepSeek ツール呼び出し `reasoning_content`
|
||||
|
||||
DeepSeek のツール呼び出しレスポンスが `reasoning_content` と `tool_calls` を同時に返却するようになり、呼び出し側が両方を一緒にレンダリングできるようになりました (#2543, 感謝 @bling-yshs)。
|
||||
|
||||
### Baidu Qianfan Coding Plan（Claude Code）
|
||||
|
||||
Baidu Qianfan Coding Plan プリセットを追加しました (#2322, 感謝 @jimmyzhuu)。
|
||||
|
||||
### Compshare Coding Plan プリセット（クロスアプリ）
|
||||
|
||||
Compshare Coding Plan プリセットを claude / codex / hermes / openclaw の全アプリに展開しました。
|
||||
|
||||
### パートナープロバイダープリセット
|
||||
|
||||
**BytePlus**、**Volcengine Agentplan**、**ClaudeAPI**、**ClaudeCN**、**RunAPI**、**RelaxyCode**、**PatewayAI** のパートナープリセットを追加; **Doubao Seed** をパートナープリセットに昇格（エンドポイントとリンクをリフレッシュ）。
|
||||
|
||||
### 44 個の Claude Desktop プロバイダープリセット
|
||||
|
||||
Claude Code プリセットディレクトリから 44 個のプロバイダープリセットを翻訳し、新しい Claude Desktop パネルに投入しました。
|
||||
|
||||
---
|
||||
|
||||
## 変更
|
||||
|
||||
### 20 個の Claude Desktop プリセットがデフォルトで直接接続モードに
|
||||
|
||||
20 個の Claude Desktop プリセットがデフォルトでプロキシモードから直接接続モードに切り替わり、プロキシ互換シムを必要としないユーザーの導入摩擦を低減しました。アップグレード前にこれらのプリセットのプロキシルーティング経由の接続性に依存していた場合は、アップグレード後に検証してください。
|
||||
|
||||
### Claude Desktop の操作制約
|
||||
|
||||
Claude Desktop のプロバイダーを切り替えると CC Switch 管理の 3P プロファイルが書き込まれます。**Claude Desktop の再起動**が必要です; プロキシモードのプロバイダーは、使用中 CC Switch の Local Routing が動作し続けている必要があります。
|
||||
|
||||
### Failover / Local Routing 連動検証
|
||||
|
||||
Failover コントロールは、ターゲットアプリの Local Routing テイクオーバーが有効になっていないと開けないように変更しました。プロキシサービスのみを止めてもテイクオーバー状態に依存するアプリがある場合はブロックされ、「プロキシは止めたがアプリはまだテイクオーバー中と認識している」という不整合を回避します。
|
||||
|
||||
### Usage 統計のセマンティクス変更
|
||||
|
||||
Usage サマリーは**キャッシュ正規化後の真の総トークン数**と**キャッシュヒット率**を報告するようになりました。データの重複排除と価格再計算により、過去のトークン数とコスト数値は**ずれる可能性があります** — 新しい数値の方が正確ですが、旧バージョンの数値とは一致しません。
|
||||
|
||||
### プロバイダープリセットのレンダリング順序
|
||||
|
||||
プリセットリストは作者が定義した配列順序でレンダリングされるようになり、パートナーが先頭に並びます。以前の暗黙的なソートを置き換えます。
|
||||
|
||||
### モデルマッピングヒント文面の簡素化
|
||||
|
||||
`modelMappingOffHint` を中 / 英 / 日でアクション指向の簡潔な文面に書き直しました。
|
||||
|
||||
### CC Switch ブランド公式サイトを ccswitch.io に統一
|
||||
|
||||
アプリ内および README 内のすべての「公式サイト」参照を、唯一の公式サイトとして ccswitch.io に統一しました; Release notes テンプレートにも ccswitch.io を反映。
|
||||
|
||||
### テーマ切り替えの簡素化
|
||||
|
||||
テーマ切り替え時の円形拡散アニメーションを削除し、即座にクロスフェードする方式に変更しました。
|
||||
|
||||
### Claude Code App スイッチャーの視覚的な区別
|
||||
|
||||
App スイッチャーで「Claude Code」と「Claude Desktop」を視覚的に区別し、アプリ可視性設定では「Claude Code」ラベルを使用するようにしました。
|
||||
|
||||
### CI: Claude Review を Opus 4.7 にアップグレード
|
||||
|
||||
Claude review GitHub Action を Opus 4.7 にアップグレード; nitpick ノイズを減らすためプロンプトを調整; `@claude` レビュー専用 Code Action を追加; PR head SHA を checkout 用にロック; `--max-turns 5` 制限を削除。
|
||||
|
||||
### GitHub Actions 依存関係のアップグレード
|
||||
|
||||
- `actions/checkout` 4 → 6 (#2517)
|
||||
- `pnpm/action-setup` 5 → 6 (#2518)
|
||||
- `softprops/action-gh-release` 2 → 3 (#2519)
|
||||
- `actions/stale` 9 → 10 (#2520)
|
||||
|
||||
### DeepSeek プリセットを V4 に
|
||||
|
||||
DeepSeek プリセットが V4（flash / pro）+ リフレッシュされた価格シードを出荷するようになりました。
|
||||
|
||||
### Codex 1M コンテキストトグルを編集フォームから隠す
|
||||
|
||||
Codex プロバイダー編集フォームでは 1M コンテキストトグルを表示しなくなり、現在の Codex デプロイメントには実効性のないノブの密度を低減しました。
|
||||
|
||||
### OpenClaudeCode を MicuAPI ドメインに移行
|
||||
|
||||
OpenClaudeCode プリセットを MicuAPI ドメインに移行; Micu API リンクを `micuapi.ai` にリフレッシュ。
|
||||
|
||||
### CrazyRouter エンドポイントを `cn` サブドメインに切り替え
|
||||
|
||||
CrazyRouter プリセットのエンドポイントを `cn` サブドメインに変更しました。
|
||||
|
||||
### RelaxyCode カスタムアイコン
|
||||
|
||||
RelaxyCode プリセットのアイコンをカスタム `relaxcode.png` アセットに変更しました。
|
||||
|
||||
### Kimi For Coding ドキュメント URL
|
||||
|
||||
Kimi For Coding のウェブサイト URL を `/code/docs/` パスに更新しました。
|
||||
|
||||
### SiliconFlow 国際版で USD 表示
|
||||
|
||||
SiliconFlow 国際版の残高を正しく USD で表示するように修正しました（以前は誤って CNY と表示）。
|
||||
|
||||
---
|
||||
|
||||
## 修正
|
||||
|
||||
### OpenAI Responses API usage 解析の堅牢化
|
||||
|
||||
`build_anthropic_usage_from_responses()` と Responses → Anthropic SSE トランスレーターを強化し、上流の欠損または不正な `usage` が `message_delta` 内で `"usage": null` を生成しないようにしました。これにより、厳格な Anthropic クライアント（典型例: VSCode Claude Code プラグイン）が一部のプロバイダー（Codex OAuth、DashScope の `compatible-mode/v1/responses` エンドポイント）で `Cannot read properties of null (reading 'output_tokens')` でクラッシュしていた問題が解消されます。OpenAI フィールド名のフォールバック（`prompt_tokens` / `completion_tokens`）、null / 空 / 部分オブジェクトの処理、input/output tokens が欠損していても cache token フィールドを保持する処理を追加しました (#2422, 感謝 @magucas)。
|
||||
|
||||
### プロキシ信頼性パッチ（P0–P3）
|
||||
|
||||
request-forwarder パス全体で複数回にわたるルーティング / ライフサイクル / リトライ / 補正器の修正を実施; 共有された `handle_rectifier_retry_failure` ヘルパーと `auth_header_value` ヘルパーを抽出。
|
||||
|
||||
### プロキシ: 非 Anthropic バックエンドの HTTPS コネクションプール再利用
|
||||
|
||||
非 Anthropic バックエンドはプールされた HTTPS コネクションを再利用し、リクエストごとに新しい TLS セッションを開かなくなりました。リクエスト単位のレイテンシが大幅に低減します。
|
||||
|
||||
### プロキシ: クライアントの実際の HTTP メソッドを転送
|
||||
|
||||
`POST` のハードコーディングをやめ、クライアントの実際の HTTP メソッドに従って転送するようになりました; 上流の非 POST エンドポイント（例: GET `/v1/models`）が正常に動作します。
|
||||
|
||||
### プロキシ: 試行ごとのカウンター + `max_retries` の接続
|
||||
|
||||
クライアントリクエストカウンターを試行ごとのループから外に移動; `AppProxyConfig.max_retries` がリクエストフォワーダーに正しく接続されるようになりました。
|
||||
|
||||
### プロキシ: フェイルオーバー判定の精緻化
|
||||
|
||||
リクエストフォワーダー内でのリトライ可能 / 不可能エラーの分類がより正確になりました。
|
||||
|
||||
### プロキシ: テイクオーバー検出の精緻化
|
||||
|
||||
テイクオーバー検出をより厳密にしました; テイクオーバー OFF 時はフォールバック復旧パスを通り、残留状態によってプロバイダーが固まらないようにします。
|
||||
|
||||
### プロキシ: Anthropic ↔ OpenAI `tool_choice` の相互変換
|
||||
|
||||
フォーマット変換時に Anthropic の `tool_choice` を OpenAI Chat のネスト形式に正しくマッピングするようになりました。
|
||||
|
||||
### プロキシ: Gemini リクエストのモデルを URI パスから抽出
|
||||
|
||||
Gemini リクエストのモデルを URI パスから抽出するようになりました（body からは取らない）。変換後のトラフィックが正しいモデル名を報告します。
|
||||
|
||||
### プロキシ: 認証ヘッダーのエラー処理
|
||||
|
||||
`get_auth_headers` が `Result` を返すようになり、認証情報に問題がある場合にパニックしなくなりました。
|
||||
|
||||
### プロキシ: IPv6 リッスンアドレスの検証
|
||||
|
||||
プロキシパネルが IPv6 リッスンアドレスを受け付けるようになりました。
|
||||
|
||||
### プロキシ: Codex / Responses キャッシュヒット率の改善
|
||||
|
||||
安定したキャッシュキー導出によって Codex と OpenAI Responses リクエストのキャッシュヒット率を改善: クライアントが本当にセッション識別子を持参してきた場合にのみ `prompt_cache_key` を送信し、無関係な会話が同じキーに潰されないようにする; 外部リクエストボディと `tool_call` 引数 / `tool_result` 内容内の JSON キーを正規化してソートし、プレフィックスキャッシュがバイト単位でマッチできるようにする; `session_id` を usage ロガーに通してリクエストを関連付けする。
|
||||
|
||||
### プロキシ: JSON Schema のアンダースコアフィールド保持
|
||||
|
||||
プライベートパラメータフィルタリングが JSON Schema name map（`properties`、`patternProperties`、`definitions`、`$defs`）内のアンダースコア接頭辞のフィールド名を保持するようになりました。ユーザー定義 schema キー（`_id`、`_meta` など）がフィルターを正常に通り抜けられます。
|
||||
|
||||
### プロキシ: Read ツールの空白ページ除去
|
||||
|
||||
`Read` ツールの入力から空白ページを除去し、プロバイダーがリクエストを拒否しないようにしました (#2472, 感謝 @Kwensiu)。
|
||||
|
||||
### プロキシ: リクエスト単位のホットパス軽量化
|
||||
|
||||
リクエストごとのホットパスのオーバーヘッドとデータベース待ち時間を削減しました。
|
||||
|
||||
### プロキシ: テイクオーバー下で真のプロバイダーモデル名を表示
|
||||
|
||||
テイクオーバー実行時に、Claude Code メニューが古いエイリアスではなく真のプロバイダーモデル名を露出するようになりました。
|
||||
|
||||
### プロキシ: 最終 `message_delta` は常に usage を含む
|
||||
|
||||
最終 `message_delta` イベントには常に usage ブロックが含まれるようになりました（すべてゼロでも）。厳格な Anthropic クライアントが `null` でクラッシュしなくなります (#2485, 感謝 @Myoontyee)。
|
||||
|
||||
### プロキシ: ストリーミング `message_delta` の重複排除
|
||||
|
||||
一部の上流が二重に送信する `message_delta` イベントの重複排除を行います (#2366, 感謝 @codeasier)。
|
||||
|
||||
### プロキシ: ツール呼び出しパスでの `reasoning_content` 保持
|
||||
|
||||
ツール呼び出しパスの変換時に scoped `reasoning_content` フィールドを正しく保持するようにしました; Kimi / Moonshot の OpenAI Chat 互換パスではこのフィールドを保持し、汎用 OpenAI 互換リクエストでは引き続き付加しません (#2367, 感謝 @codeasier)。
|
||||
|
||||
### プロキシ: Vertex AI の完全 URL 保持
|
||||
|
||||
Vertex AI の完全 URL がプロキシ転送時に切り詰められないようにしました (#2415, 感謝 @xpfo-go)。
|
||||
|
||||
### プロキシ: system content 先頭の課金ヘッダーを除去
|
||||
|
||||
一部の上流が system message の先頭に挿入する課金ヘッダー内容を除去するようにしました (#2350)。
|
||||
|
||||
### プロキシ: Claude 認証ストラテジーを `ANTHROPIC_*` 環境変数名から導出
|
||||
|
||||
不透明なヒューリスティックに依存するのをやめ、認証ストラテジーを実際の `ANTHROPIC_*` 環境変数名から導出するようにしました。
|
||||
|
||||
### サードパーティ Claude プロバイダー: モデルテストの無効化
|
||||
|
||||
`/v1/models` を一貫して実装していないサードパーティ Claude ゲートウェイに対して、モデルプローブを無効化しました。
|
||||
|
||||
### Model-Fetch: Anthropic 互換サブパスプロバイダーの `/models`
|
||||
|
||||
`/models` ディスカバリーが Anthropic 互換のサブパスプロバイダーに対しても動作するようになりました。
|
||||
|
||||
### Copilot: Claude モデル ID をライブ `/models` と照合
|
||||
|
||||
Copilot バックエンドのプロバイダーはライブ `/models` リストを使って Claude モデル ID を照合し、古い ID の不整合を回避するようになりました。
|
||||
|
||||
### Codex: セッションタイトルが `environment_context` を取り込まないように
|
||||
|
||||
Codex のセッションタイトル抽出が `environment_context` のノイズを引き込まなくなりました (#2439, 感謝 @eclipsehx)。
|
||||
|
||||
### Codex: subagent セッションを非表示
|
||||
|
||||
Codex の subagent セッションをメインセッションリストから非表示にしました (#2445, 感謝 @LanternCX)。
|
||||
|
||||
### Codex 起動時の live import 重複排除
|
||||
|
||||
Codex 起動時の live import パスにおける重複インポートのバグを修正しました (#2590, 感謝 @DhruvShankpal)。
|
||||
|
||||
### Codex プロバイダー切り替えで履歴を擾乱しないように
|
||||
|
||||
アクティブな Codex プロバイダーの切り替えが既存のセッション履歴を変更しなくなりました (#2349, 感謝 @SaladDay)。
|
||||
|
||||
### Codex usage ログの文言修正
|
||||
|
||||
Codex セッション usage の誤解を招くログを 1 件修正しました (#2473, 感謝 @tisonkun)。
|
||||
|
||||
### Claude: `max` effort を env 経由で永続化
|
||||
|
||||
`max` effort が再起動をまたいで env 変数経由で正しく永続化されるようになりました (#2493, 感謝 @makoMakoGo)。
|
||||
|
||||
### Claude Desktop: モデルルーティングで `[1M]` サフィックスを要求しないように
|
||||
|
||||
ルーティングマッチングがレガシーな `[1M]` サフィックスを要求しなくなりました。
|
||||
|
||||
### Claude Desktop: プロバイダーフォームの入力フォーカス消失
|
||||
|
||||
Claude Desktop プロバイダーフォームで入力ボックス編集中にフォーカスを失う問題を修正しました。
|
||||
|
||||
### Claude Desktop: 偽の「プロキシ停止」ステータス通知
|
||||
|
||||
プロキシが能動的に停止された際に誤って発火するヒントを削除しました。
|
||||
|
||||
### Claude Desktop: 空のツールバーカプセル非表示
|
||||
|
||||
Claude Desktop がアクティブアプリの場合、空のツールバーカプセルを非表示にします。
|
||||
|
||||
### UI: Monitor バッジアイコンのセンタリング
|
||||
|
||||
App スイッチャー内の Monitor バッジアイコンをセンタリングしました。
|
||||
|
||||
### Linux: テーマ選択で segfault
|
||||
|
||||
Linux でテーマを選択した際の segfault を防止しました (#2502, 感謝 @definfo)。
|
||||
|
||||
### ターミナル: コールドスタート時の iTerm fallback
|
||||
|
||||
コールドスタート時に存在しない iTerm をフォールバックに選んでしまうのを防止しました (#2448, 感謝 @hulkbig)。
|
||||
|
||||
### 設定: JSON キーを辞書順でソート
|
||||
|
||||
設定の書き込みが JSON キーを辞書順にソートするようになり、出力が決定的になりました (#2469, 感謝 @fuleinist)。
|
||||
|
||||
### 「既存をインポート」を副作用なしに
|
||||
|
||||
「既存をインポート」操作を副作用なしに変更しました (#2429, 感謝 @xwil1)。
|
||||
|
||||
### Coding Plan: Zhipu の週次ウィンドウをリセット時刻で命名
|
||||
|
||||
Zhipu の週次ウィンドウのティア名を実際のリセット時刻に合うように修正しました (#2420, 感謝 @TuYv)。
|
||||
|
||||
### DashScope: usage 解析の堅牢化
|
||||
|
||||
DashScope の usage 解析を強化し、不正なペイロードが VSCode Claude Code プラグインをクラッシュさせないようにしました (#2425, 感謝 @magucas)。
|
||||
|
||||
### Usage: プロキシとセッションログの重複排除
|
||||
|
||||
プロキシとセッションログという 2 つのソースをまたいで usage レコードの重複排除を行います。
|
||||
|
||||
### Usage: キャッシュコストのセマンティクス + pricing 警告の嵐
|
||||
|
||||
キャッシュコストのセマンティクスを修正し、リクエストごとに発生していたノイズの多い pricing 警告を解消しました。
|
||||
|
||||
### CI: フロントエンドフォーマット + Linux clippy の復活
|
||||
|
||||
CI のフロントエンドフォーマットと Linux clippy の実行を復活させました。
|
||||
|
||||
### プロキシテストヘルパー clippy 警告
|
||||
|
||||
プロキシテストヘルパーの clippy 警告を 1 件修正しました。
|
||||
|
||||
---
|
||||
|
||||
## 削除
|
||||
|
||||
### Hermes Agent usage トラッキング統合
|
||||
|
||||
本サイクルでオンラインにする予定だった Hermes Agent usage トラッキング統合を削除しました — 上流の動作変更によって、この統合のメンテナンスが現実的でなくなりました。この統合は**いかなるリリース版でも有効化されたことはなく**; 開発過程で発見された「ゼロコストレンダリング」バグは統合をロールバックする前に修正済みです。
|
||||
|
||||
### テーマ切り替えの円形拡散アニメーション
|
||||
|
||||
テーマ切り替え時の円形拡散アニメーションを削除しました — 性能の弱いコンポジターでカクつき、視覚的なメリットが限定的でした。
|
||||
|
||||
### DDSHub パートナー統合
|
||||
|
||||
DDSHub をパートナープリセットから削除し、各 README 内の相互リンクセクションも削除しました。
|
||||
|
||||
---
|
||||
|
||||
## ドキュメント
|
||||
|
||||
### README スポンサー更新（中 / 英 / 日）
|
||||
|
||||
BytePlus、ClaudeCN、RunAPI、PatewayAI のスポンサーエントリを追加; BytePlus と Volcengine のエントリを相互リンク; CrazyRouter の $2 クレジット受領フロー、Compshare の説明、Right Code の説明、その他スポンサーのロゴおよびリストアイテムをリフレッシュ; LionCC のロゴを白背景にフラット化; 中国語 README のスポンサーロゴを Volcengine 画像に切り替え; README のサブタイトルに Hermes Agent を追加。
|
||||
|
||||
### Release notes テンプレート
|
||||
|
||||
Release notes テンプレート内に `ccswitch.io` を反映しました。
|
||||
|
||||
### ブランド公式サイト
|
||||
|
||||
各 README およびアプリ内参照で `ccswitch.io` を唯一の公式サイトとしてドキュメント化しました。
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ アップグレード時の注意
|
||||
|
||||
### 20 個の Claude Desktop プリセットがデフォルトで直接接続モードに
|
||||
|
||||
これら 20 個のプリセットは以前はデフォルトでプロキシ経由でルーティングされていましたが、現在はデフォルトで直接接続です。アップグレード前にこのうちのいずれかを使用しており、かつプロキシルーティングの接続性に依存していた場合（例: プロキシに特殊な補正器や変換層がある場合）、接続性を検証してください; 必要に応じて、CC Switch パネル内で手動でプロキシモードに戻すことができます。
|
||||
|
||||
### Claude Desktop の操作制約
|
||||
|
||||
Claude Desktop プロバイダーの切り替えには、**Claude Desktop の再起動**が必要です; プロキシモードのプロバイダーは、使用中 CC Switch の Local Routing が動作し続けている必要があります — CC Switch を終了させたり Local Routing を停止させたりすると、プロキシモードの Claude Desktop プロバイダーへの接続が切断されます。
|
||||
|
||||
### Failover にはテイクオーバーの有効化が必要
|
||||
|
||||
Failover を有効化する前に、ターゲットアプリの Local Routing テイクオーバーが有効になっていることを確認してください。さもないと Failover コントロールは起動を拒否します; プロキシサービスを止めたいがテイクオーバーに依存するアプリがある場合はブロックされるため、アプリ層で先にテイクオーバーを止めてからプロキシを停止する必要があります。
|
||||
|
||||
### Usage 統計の数値が過去と一致しない可能性
|
||||
|
||||
Usage サマリーはキャッシュ正規化後の真の総トークン数 + キャッシュヒット率を使用するようになりました。データの重複排除と価格再計算により、過去のトークン数とコスト数値は**ずれる可能性があります** — 新しい数値の方が正確ですが、旧バージョンの数値とは一致しません。
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ リスク通知
|
||||
|
||||
本リリースは、リバースプロキシ系機能について v3.12.3 / v3.13.0 で提起されたリスク通知を継承します。
|
||||
|
||||
**GitHub Copilot リバースプロキシ**: Copilot のリバースプロキシパスを使用すると、GitHub / Microsoft の利用規約に違反する可能性があります。詳細は [v3.12.3 リリースノート](v3.12.3-ja.md#️-リスクに関する注意事項) を参照してください。
|
||||
|
||||
**Codex OAuth リバースプロキシ**: ChatGPT サブスクリプションを使用した Codex OAuth リバースプロキシは、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 リリースノート](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
|
||||
|
||||
**Claude Desktop サードパーティプロバイダーのプロキシ切り替え**: CC Switch 内蔵プロキシゲートウェイ経由で Claude Desktop のリクエストをサードパーティプロバイダーに転送する際、サードパーティプロバイダーの課金、コンプライアンス、データ保持に関する制約はそれぞれ異なります。利用前にターゲットプロバイダーの利用規約をお読みください。
|
||||
|
||||
ユーザーが上記機能を有効化することで、**すべてのリスクを自己責任で**受諾したものとみなされます。CC Switch は、これらの機能の使用に起因するアカウントの制限、警告、サービス停止について一切の責任を負いません。
|
||||
|
||||
---
|
||||
|
||||
## ダウンロード・インストール
|
||||
|
||||
[Releases](https://github.com/farion1231/cc-switch/releases/latest) から対応バージョンをダウンロードしてください。
|
||||
|
||||
### システム要件
|
||||
|
||||
| OS | 最小バージョン | アーキテクチャ |
|
||||
| ------- | ------------------------ | ----------------------------------- |
|
||||
| Windows | Windows 10 以降 | x64 |
|
||||
| macOS | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 下表参照 | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| ファイル | 説明 |
|
||||
| ---------------------------------------- | ------------------------------------------- |
|
||||
| `CC-Switch-v3.15.0-Windows.msi` | **推奨** - MSI インストーラー、自動更新対応 |
|
||||
| `CC-Switch-v3.15.0-Windows-Portable.zip` | ポータブル版、解凍して実行、レジストリ不要 |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| -------------------------------- | ------------------------------------------------------ |
|
||||
| `CC-Switch-v3.15.0-macOS.dmg` | **推奨** - DMG インストーラー、Applications にドラッグ |
|
||||
| `CC-Switch-v3.15.0-macOS.zip` | 解凍して Applications にドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.15.0-macOS.tar.gz` | Homebrew インストールと自動更新用 |
|
||||
|
||||
> macOS 版は Apple のコード署名および公証済みで、直接インストールして使用できます。
|
||||
|
||||
### Homebrew（macOS）
|
||||
|
||||
> 🎉 CC Switch は Homebrew 公式 cask リポジトリに収録されました。カスタム tap の追加は不要です！
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
> Linux 向けの成果物は **x86_64** と **ARM64**（`aarch64`）の両方が提供されます。ファイル名にアーキテクチャ識別子が含まれているため、`uname -m` の出力に応じて選択してください：
|
||||
>
|
||||
> - `CC-Switch-v3.15.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
> - `CC-Switch-v3.15.0-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| ディストリビューション | 推奨形式 | インストール方法 |
|
||||
| --------------------------------------- | ----------- | -------------------------------------------------------------------------- |
|
||||
| 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` |
|
||||
@@ -0,0 +1,527 @@
|
||||
# CC Switch v3.15.0
|
||||
|
||||
> Claude Desktop 升级为一等管理面板（含第三方供应商代理切换）、按角色的模型映射、反向代理大幅强化、Codex OAuth 实时模型发现、用量看板筛选驱动 Hero 卡
|
||||
|
||||
**[English →](v3.15.0-en.md) | [日本語版 →](v3.15.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## 唯一官方渠道声明（请务必阅读）
|
||||
>
|
||||
> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。最近发现多个山寨网站冒用 CC Switch 名义诱导用户付费、收集账号信息，部分已造成实际经济损失。请仅通过下列官方渠道获取本软件：
|
||||
>
|
||||
> | 类别 | 唯一官方 |
|
||||
> | -------- | ------------------------------------------------------------------------------ |
|
||||
> | 官网 | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | 源码 | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | 下载 | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | 作者 | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈，让我们能尽快下线相关山寨站点。
|
||||
|
||||
---
|
||||
|
||||
## Claude Desktop 使用攻略
|
||||
|
||||
本版本最主打的能力是 **Claude Desktop 一等管理面板**。如果你已经在 Claude Code 里配置了很多供应商，建议先阅读这篇攻略：
|
||||
|
||||
**[使用 CC Switch，一键配置、管理和切换 Claude Desktop 供应商](../user-manual/zh/2-providers/2.6-claude-desktop.md)**
|
||||
|
||||
攻略覆盖从 Claude Code 一键导入已有供应商、添加 Claude Desktop 专属供应商、直连 / 模型映射两种模式、本地路由开关显示设置，到恢复 Claude Desktop 官方登录模式的完整流程。
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.15.0 是 v3.14.x 之后的一次大版本更新，核心聚焦在**把 Claude Desktop 升级为一等管理面板**，并配套提供第三方供应商通过内置代理网关进行切换、按角色的模型映射（sonnet / opus / haiku）+ `supports1m` 长上下文标志、Copilot/Codex OAuth 供应商复用、重新设计的 Claude Code 导入流程、App 切换器对"Claude Code"和"Claude Desktop"的可视化区分，以及 44 个从 Claude Code 预设目录翻译而来的 Claude Desktop 预设。
|
||||
|
||||
围绕反向代理的可靠性，本版本进行了一次系统性硬化：P0–P3 多轮针对路由 / 生命周期 / 重试 / 故障转移 / 补正器的修补；非 Anthropic 后端启用 HTTPS 连接池复用以降低单请求延迟；Codex 与 OpenAI Responses 缓存命中率提升（`prompt_cache_key` 仅在有真实客户端会话标识时发送、对外请求体与 `tool_call` 参数 / `tool_result` 内容的 JSON key 规范化排序、`session_id` 串入用量记录器）；Anthropic ↔ OpenAI `tool_choice` 正确互转；Vertex AI 完整 URL 不再被截断；Gemini 改为从 URI 路径提取模型名；Local Routing 接管检测更精细；可监听 IPv6 地址。Codex OAuth 类 Claude 供应商不再依赖硬编码的模型列表，CC Switch 会按需从 ChatGPT 后端拉取实时模型列表。
|
||||
|
||||
Claude Code 的模型映射改为基于角色（`sonnet` / `opus` / `haiku`）+ 显示名，并引入 `supports1m` 布尔标志，替代旧版的 `[1M]` 后缀写法，把路由决策与原始模型 ID 解耦。用量看板新增**筛选驱动的 Hero 卡**，展示缓存归一化后的真实总 token 与缓存命中率，并跟随当前日期范围 / 供应商 / 模型筛选实时更新；配套修复了缓存成本语义错误以及每个请求都触发的定价警告噪声。在 OpenAI Responses API usage 解析路径上做了鲁棒化处理，让上游缺失或畸形的 `usage` 不再让 VSCode Claude Code 插件因 `null` 输出崩溃。
|
||||
|
||||
供应商生态进一步扩张：新增 BytePlus、火山 Agentplan、ClaudeAPI、ClaudeCN、RunAPI、RelaxyCode、PatewayAI、百度千帆 Coding Plan 合作伙伴预设；豆包 Seed 升级为合作伙伴预设；供应商卡片现在会显示"是否支持 Local Routing"的徽章。本版本还修复了大量 Codex 会话、OAuth、Claude Desktop 表单、Linux 段错误、终端 fallback 等场景下的细节问题，并完成了多项 GitHub Actions 依赖升级。
|
||||
|
||||
**发布日期**：2026-05-16
|
||||
|
||||
**更新规模**：127 commits | 211 files changed | +17,980 / -2,748 lines
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- **Claude Desktop 成为一等管理面板**：通过内置代理网关提供第三方供应商切换、按角色的模型映射（sonnet / opus / haiku）+ `supports1m` 长上下文标志、Copilot/Codex OAuth 供应商复用、44 个从 Claude Code 预设目录翻译过来的预设。注意：20 个 Claude Desktop 预设默认从代理模式切到直连模式，升级后如依赖代理路由请验证连通性
|
||||
- **反向代理大幅强化**：P0–P3 生命周期 / 重试 / 故障转移 / 补正器修补；非 Anthropic 后端 HTTPS 连接池复用；Codex/Responses 缓存命中率提升；Anthropic ↔ OpenAI `tool_choice` 正确映射；Vertex AI URL 完整保留；Gemini 路径式模型提取；接管检测细化；支持 IPv6 监听地址
|
||||
- **供应商生态扩张**：新增 BytePlus、火山 Agentplan、ClaudeAPI、ClaudeCN、RunAPI、RelaxyCode、PatewayAI、百度千帆 Coding Plan 合作伙伴预设；豆包 Seed 升级合作伙伴；供应商卡片显示"路由代理支持"徽章
|
||||
- **按角色的模型映射 + 1M 标志**：基于角色的 sonnet / opus / haiku 路由 + 显示名 + `supports1m` 标志，替代旧的 `[1M]` 后缀
|
||||
- **Codex OAuth 实时模型发现**：ChatGPT Codex 类供应商按需从 ChatGPT 后端拉取实时模型列表
|
||||
- **用量看板筛选驱动 Hero**：展示缓存归一化的真实总 token 和缓存命中率，跟随当前日期 / 供应商 / 模型筛选实时更新
|
||||
- **DeepSeek 工具调用 + 零 usage 最终 delta**：DeepSeek 工具调用一并返回 `reasoning_content` (#2543, 感谢 @bling-yshs)；最终 `message_delta` 总是带 usage 块（即便全为 0），严格 Anthropic 客户端不再因 `null` 崩溃 (#2485, 感谢 @Myoontyee)
|
||||
- **OpenAI Responses API usage 解析鲁棒化**：让上游缺失或畸形 usage 不再让 VSCode Claude Code 插件崩溃 (#2422, 感谢 @magucas)
|
||||
|
||||
---
|
||||
|
||||
## 新功能
|
||||
|
||||
### Claude Desktop 第三方供应商代理切换
|
||||
|
||||
CC Switch 第一次把 **Claude Desktop** 作为一等受管面板对待，与 Claude Code / Codex / Gemini / OpenCode / OpenClaw / Hermes 并列。
|
||||
|
||||
- 新增 Claude Desktop 专属面板，通过 CC Switch 内置代理网关把第三方供应商代理给 Claude Desktop
|
||||
- 为需要路由代理的供应商在卡片上呈现"是否支持 Local Routing"的徽章
|
||||
- 按角色的模型路由映射，锁定到 `sonnet` / `opus` / `haiku`
|
||||
- Copilot / Codex OAuth 供应商在 Claude Desktop 面板中可复用
|
||||
- 重新设计的 Claude Code 设置导入流程
|
||||
- App 切换器视觉区分"Claude Code"与"Claude Desktop"，应用可见性设置中使用"Claude Code"标签
|
||||
- 44 个从 Claude Code 预设目录翻译过来的 Claude Desktop 供应商预设
|
||||
|
||||
### 供应商卡片：路由代理支持徽章
|
||||
|
||||
Claude Code 与 Codex 面板中的供应商卡片新增"路由代理支持"徽章，方便一眼识别哪些供应商可以通过 Local Routing 提供服务。
|
||||
|
||||
### Codex OAuth 实时模型列表
|
||||
|
||||
ChatGPT Codex 类供应商不再依赖硬编码的模型选择，CC Switch 会按需从 ChatGPT 后端拉取**实时模型列表**。
|
||||
|
||||
### 按角色的模型映射 + 1M 标志
|
||||
|
||||
Claude Code 模型映射改为基于角色（`sonnet` / `opus` / `haiku`）+ 显示名，并引入 `supports1m` 布尔标志，替代旧版 `[1M]` 后缀，把路由决策与原始模型 ID 解耦。
|
||||
|
||||
### 用量看板筛选驱动 Hero
|
||||
|
||||
用量看板的 Hero 摘要现在是筛选驱动的，跟随当前日期范围 / 供应商 / 模型筛选实时变化；展示**缓存归一化后的真实总 token**与缓存命中率，让 Hero 数字与下方明细列表对齐。
|
||||
|
||||
### 供应商表单"先存上再说"
|
||||
|
||||
软化供应商表单的输入校验，把非阻塞性的输入问题改为"先存上再说"的提示，不会因为一个无伤大雅的字段问题阻止保存 (#2307, 感谢 @allenxln)。
|
||||
|
||||
### Universal 供应商复制动作
|
||||
|
||||
为 universal 供应商在供应商列表中新增"复制"按钮 (#2416, 感谢 @hubutui)。
|
||||
|
||||
### 持久化 Tauri 窗口状态
|
||||
|
||||
窗口位置和尺寸现在跨重启保留 (#2377, 感谢 @BillSaul)。
|
||||
|
||||
### 托盘图标 hover 提示
|
||||
|
||||
系统托盘图标现在悬浮显示状态提示 (#2417, 感谢 @Coconut-Fish)。
|
||||
|
||||
### Warp 终端会话启动
|
||||
|
||||
新增对 Warp 终端的支持，可在 Warp 中执行保存的会话 (#2466, 感谢 @tisonkun)。
|
||||
|
||||
### DeepSeek 工具调用 `reasoning_content`
|
||||
|
||||
DeepSeek 工具调用响应现在同时返回 `reasoning_content` 和 `tool_calls`，调用方可以两者一并渲染 (#2543, 感谢 @bling-yshs)。
|
||||
|
||||
### 百度千帆 Coding Plan（Claude Code）
|
||||
|
||||
新增百度千帆 Coding Plan 预设 (#2322, 感谢 @jimmyzhuu)。
|
||||
|
||||
### Compshare Coding Plan 预设（跨应用）
|
||||
|
||||
Compshare Coding Plan 预设跨 claude / codex / hermes / openclaw 全应用就位。
|
||||
|
||||
### 合作伙伴供应商预设
|
||||
|
||||
新增 **BytePlus**、**火山 Agentplan**、**ClaudeAPI**、**ClaudeCN**、**RunAPI**、**RelaxyCode**、**PatewayAI** 合作伙伴预设；**豆包 Seed** 升级合作伙伴预设（端点和链接刷新）。
|
||||
|
||||
### 44 个 Claude Desktop 供应商预设
|
||||
|
||||
从 Claude Code 预设目录翻译 44 个供应商预设进入新的 Claude Desktop 面板。
|
||||
|
||||
---
|
||||
|
||||
## 变更
|
||||
|
||||
### 20 个 Claude Desktop 预设默认切到直连模式
|
||||
|
||||
20 个 Claude Desktop 预设默认从代理模式切到直连模式，降低对不需要代理兼容垫片的用户的上手摩擦。如果你升级前依赖代理路由这些预设的连通性，请升级后验证。
|
||||
|
||||
### Claude Desktop 操作约束
|
||||
|
||||
切换 Claude Desktop 供应商会写入 CC Switch 管理的 3P profile，**需要重启 Claude Desktop** 才能生效；代理模式的供应商在使用期间需要 CC Switch 的 Local Routing 保持运行。
|
||||
|
||||
### Failover / Local Routing 联动校验
|
||||
|
||||
Failover 控件现在要求目标应用的 Local Routing 接管已启用才能开启；只关代理服务但仍有应用依赖接管状态的情况会被拦下，避免出现"代理关了但应用仍以为接管在跑"的不一致。
|
||||
|
||||
### 用量统计语义变化
|
||||
|
||||
用量摘要现在报告**缓存归一化后的真实总 token**和**缓存命中率**。历史 token 与成本数字在数据去重 + 价格重算后**可能会有偏移**——新数字更准，但不会等于旧版给出的数字。
|
||||
|
||||
### 供应商预设渲染顺序
|
||||
|
||||
预设列表现在按作者定义的数组顺序渲染，合作伙伴排前面，替代之前的隐式排序。
|
||||
|
||||
### 模型映射提示文案简化
|
||||
|
||||
`modelMappingOffHint` 跨中 / 英 / 日重写为动作导向的简洁文案。
|
||||
|
||||
### CC Switch 品牌官网统一到 ccswitch.io
|
||||
|
||||
应用内和 README 中所有"官网"引用都统一到 ccswitch.io 作为唯一官方网站；Release notes 模板也呈现 ccswitch.io。
|
||||
|
||||
### 主题切换简化
|
||||
|
||||
移除主题切换时的圆形扩散动画，改为即时交叉淡入。
|
||||
|
||||
### Claude Code App 切换器视觉区分
|
||||
|
||||
App 切换器视觉上区分"Claude Code"和"Claude Desktop"，应用可见性设置中使用"Claude Code"标签。
|
||||
|
||||
### CI：Claude Review 升级到 Opus 4.7
|
||||
|
||||
Claude review GitHub Action 升级到 Opus 4.7；调整 prompt 降低 nitpick 噪声；新增 `@claude` 仅 review 的 Code Action；锁定 PR head SHA 用于 checkout；移除 `--max-turns 5` 限制。
|
||||
|
||||
### GitHub Actions 依赖升级
|
||||
|
||||
- `actions/checkout` 4 → 6 (#2517)
|
||||
- `pnpm/action-setup` 5 → 6 (#2518)
|
||||
- `softprops/action-gh-release` 2 → 3 (#2519)
|
||||
- `actions/stale` 9 → 10 (#2520)
|
||||
|
||||
### DeepSeek 预设切到 V4
|
||||
|
||||
DeepSeek 预设现在出货 V4（flash / pro）+ 刷新定价种子。
|
||||
|
||||
### Codex 1M 上下文开关在编辑表单隐藏
|
||||
|
||||
Codex 供应商编辑表单中不再呈现 1M 上下文开关，降低对当前 Codex 部署无实际效果的旋钮密度。
|
||||
|
||||
### OpenClaudeCode 迁移到 MicuAPI 域名
|
||||
|
||||
OpenClaudeCode 预设迁移到 MicuAPI 域名；Micu API 链接刷新到 `micuapi.ai`。
|
||||
|
||||
### CrazyRouter 端点切到 `cn` 子域
|
||||
|
||||
CrazyRouter 预设端点改用 `cn` 子域。
|
||||
|
||||
### RelaxyCode 自定义图标
|
||||
|
||||
RelaxyCode 预设图标改用自定义 `relaxcode.png` 资源。
|
||||
|
||||
### Kimi For Coding 文档 URL
|
||||
|
||||
Kimi For Coding 网站 URL 更新到 `/code/docs/` 路径。
|
||||
|
||||
### SiliconFlow 国际站显示 USD
|
||||
|
||||
SiliconFlow 国际站的余额显示正确为 USD（之前错显 CNY）。
|
||||
|
||||
---
|
||||
|
||||
## 修复
|
||||
|
||||
### OpenAI Responses API usage 解析鲁棒化
|
||||
|
||||
强化 `build_anthropic_usage_from_responses()` 与 Responses → Anthropic SSE 翻译器，让上游缺失或畸形的 `usage` 不再在 `message_delta` 中产出 `"usage": null`。这解决了严格 Anthropic 客户端（典型如 VSCode Claude Code 插件）在某些供应商（Codex OAuth、DashScope 的 `compatible-mode/v1/responses` 端点）下崩在 `Cannot read properties of null (reading 'output_tokens')` 的问题。增加 OpenAI 字段名回退（`prompt_tokens` / `completion_tokens`）、null / 空 / 部分对象处理、即使 input/output tokens 缺失也保留缓存 token 字段 (#2422, 感谢 @magucas)。
|
||||
|
||||
### 代理可靠性补丁（P0–P3）
|
||||
|
||||
跨 request-forwarder 路径多轮路由 / 生命周期 / 重试 / 补正器修补；抽取共享的 `handle_rectifier_retry_failure` helper 与 `auth_header_value` helper。
|
||||
|
||||
### 代理：非 Anthropic 后端 HTTPS 连接池复用
|
||||
|
||||
非 Anthropic 后端复用池化的 HTTPS 连接，不再每个请求开新 TLS session，显著降低单请求延迟。
|
||||
|
||||
### 代理：转发客户端真实 HTTP 方法
|
||||
|
||||
不再硬编码 `POST`，按客户端实际的 HTTP 方法转发；上游的非 POST 端点（如 GET `/v1/models`）现在能正常工作。
|
||||
|
||||
### 代理：每次尝试计数器 + `max_retries` 接线
|
||||
|
||||
客户端请求计数器移出每次尝试的循环；`AppProxyConfig.max_retries` 现在正确接到请求转发器。
|
||||
|
||||
### 代理：故障转移判定细化
|
||||
|
||||
请求转发器中重试 / 不可重试错误的分类更准确。
|
||||
|
||||
### 代理：接管检测细化
|
||||
|
||||
接管检测更紧；关接管时走 fallback 恢复，避免遗留状态把供应商卡住。
|
||||
|
||||
### 代理：Anthropic ↔ OpenAI `tool_choice` 互转
|
||||
|
||||
格式转换时把 Anthropic 的 `tool_choice` 正确映射到 OpenAI Chat 的嵌套形式。
|
||||
|
||||
### 代理：Gemini 请求模型从 URI 路径提取
|
||||
|
||||
Gemini 请求模型从 URI 路径提取（不再从 body 取），转换后的流量上报正确的模型名。
|
||||
|
||||
### 代理：认证 header 错误处理
|
||||
|
||||
`get_auth_headers` 现在返回 `Result`，凭据有问题时不再 panic。
|
||||
|
||||
### 代理：IPv6 监听地址校验
|
||||
|
||||
代理面板现在接受 IPv6 监听地址。
|
||||
|
||||
### 代理：Codex / Responses 缓存命中率提升
|
||||
|
||||
通过稳定缓存键派生提高 Codex 与 OpenAI Responses 请求的缓存命中率；只在客户端确实带了会话标识时才发 `prompt_cache_key`，避免不相关对话被坍缩到同一个 key 上；对外请求体与 `tool_call` 参数 / `tool_result` 内容里的 JSON key 做规范化排序以便前缀缓存能字节级匹配；把 `session_id` 串到 usage 日志记录器做请求关联。
|
||||
|
||||
### 代理：JSON Schema 下划线字段保留
|
||||
|
||||
私参过滤现在保留 JSON Schema name map（`properties`、`patternProperties`、`definitions`、`$defs`）内的下划线前缀字段名，用户自定义 schema key（如 `_id`、`_meta`）能正常穿过过滤。
|
||||
|
||||
### 代理：Read 工具空白页剔除
|
||||
|
||||
从 `Read` 工具输入中剔除空白页，避免供应商拒绝请求 (#2472, 感谢 @Kwensiu)。
|
||||
|
||||
### 代理：单请求热路径瘦身
|
||||
|
||||
缩减每个请求的热路径开销和数据库等待时间。
|
||||
|
||||
### 代理：接管下展示真实供应商模型名
|
||||
|
||||
接管运行时，Claude Code 菜单现在暴露真实供应商模型名，不是陈旧的 alias。
|
||||
|
||||
### 代理：最终 `message_delta` 总是带 usage
|
||||
|
||||
最终 `message_delta` 事件现在总是包含 usage 块（即使全为 0），严格 Anthropic 客户端不再因为 `null` 崩溃 (#2485, 感谢 @Myoontyee)。
|
||||
|
||||
### 代理：流式 `message_delta` 去重
|
||||
|
||||
对某些上游会发两次的 `message_delta` 事件做去重 (#2366, 感谢 @codeasier)。
|
||||
|
||||
### 代理：工具调用路径的 `reasoning_content` 保留
|
||||
|
||||
工具调用路径转换时正确保留 scoped `reasoning_content` 字段；Kimi / Moonshot 的 OpenAI Chat 兼容路径保留该字段，通用 OpenAI 兼容请求保持不带 (#2367, 感谢 @codeasier)。
|
||||
|
||||
### 代理：Vertex AI 完整 URL 保留
|
||||
|
||||
Vertex AI 的完整 URL 在代理转发时不再被截断 (#2415, 感谢 @xpfo-go)。
|
||||
|
||||
### 代理：剥离 system content 开头的计费 header
|
||||
|
||||
某些上游会在 system message 开头插一段计费 header 内容，现在被剥离 (#2350)。
|
||||
|
||||
### 代理：Claude 鉴权策略从 `ANTHROPIC_*` 环境变量名派生
|
||||
|
||||
不再依赖不透明的启发式，鉴权策略从实际的 `ANTHROPIC_*` 环境变量名派生。
|
||||
|
||||
### 第三方 Claude 供应商：禁用模型测试
|
||||
|
||||
对那些不一致实现 `/v1/models` 的第三方 Claude 网关，关闭模型探测。
|
||||
|
||||
### Model-Fetch：Anthropic 兼容子路径供应商的 `/models`
|
||||
|
||||
`/models` 发现现在对 Anthropic 兼容的子路径供应商生效。
|
||||
|
||||
### Copilot：Claude 模型 ID 对比实时 `/models`
|
||||
|
||||
Copilot 后端的供应商现在用实时 `/models` 列表来比对 Claude 模型 ID，避免陈旧 ID 不一致。
|
||||
|
||||
### Codex：会话标题不再吸入 `environment_context`
|
||||
|
||||
Codex 会话标题提取不再把 `environment_context` 的噪声拉进来 (#2439, 感谢 @eclipsehx)。
|
||||
|
||||
### Codex：隐藏 subagent 会话
|
||||
|
||||
Codex subagent 会话从主会话列表隐藏 (#2445, 感谢 @LanternCX)。
|
||||
|
||||
### Codex 启动期 live import 去重
|
||||
|
||||
修复 Codex 启动期 live import 路径里的重复导入 bug (#2590, 感谢 @DhruvShankpal)。
|
||||
|
||||
### Codex 供应商切换不再扰动历史
|
||||
|
||||
切换激活 Codex 供应商不再改动现有会话历史 (#2349, 感谢 @SaladDay)。
|
||||
|
||||
### Codex 用量日志措辞修正
|
||||
|
||||
修正一条 Codex 会话用量的误导性日志 (#2473, 感谢 @tisonkun)。
|
||||
|
||||
### Claude：`max` effort 通过 env 持久化
|
||||
|
||||
`max` effort 现在能跨重启正确通过 env 变量持久化 (#2493, 感谢 @makoMakoGo)。
|
||||
|
||||
### Claude Desktop：模型路由不再要求 `[1M]` 后缀
|
||||
|
||||
路由匹配不再要求遗留的 `[1M]` 后缀。
|
||||
|
||||
### Claude Desktop：供应商表单输入失焦
|
||||
|
||||
修复 Claude Desktop 供应商表单中输入框编辑时丢失焦点的问题。
|
||||
|
||||
### Claude Desktop：假的"代理停止"状态提示
|
||||
|
||||
移除代理主动停止时假触发的提示。
|
||||
|
||||
### Claude Desktop：空工具栏胶囊隐藏
|
||||
|
||||
当 Claude Desktop 是激活应用时，空的工具栏胶囊会被隐藏。
|
||||
|
||||
### UI：Monitor 徽章图标居中
|
||||
|
||||
在 App 切换器里居中 Monitor 徽章图标。
|
||||
|
||||
### Linux：选择主题触发 segfault
|
||||
|
||||
防止在 Linux 上选择主题触发 segfault (#2502, 感谢 @definfo)。
|
||||
|
||||
### 终端：冷启动时 iTerm fallback
|
||||
|
||||
防止冷启动时把不存在的 iTerm 选为 fallback (#2448, 感谢 @hulkbig)。
|
||||
|
||||
### 配置：JSON key 字母序排序
|
||||
|
||||
配置写入现在按字母序排 JSON key，输出确定 (#2469, 感谢 @fuleinist)。
|
||||
|
||||
### "导入已有"无副作用化
|
||||
|
||||
"导入已有"操作改为无副作用 (#2429, 感谢 @xwil1)。
|
||||
|
||||
### Coding Plan：智谱周窗口按重置时间命名
|
||||
|
||||
修正智谱周窗口的等级名以匹配实际重置时间 (#2420, 感谢 @TuYv)。
|
||||
|
||||
### DashScope：usage 解析鲁棒化
|
||||
|
||||
强化 DashScope usage 解析，畸形 payload 不会再让 VSCode Claude Code 插件崩 (#2425, 感谢 @magucas)。
|
||||
|
||||
### 用量：代理和会话日志去重
|
||||
|
||||
跨代理和会话日志两个来源的用量记录去重。
|
||||
|
||||
### 用量：缓存成本语义 + 定价警告风暴
|
||||
|
||||
修正缓存成本语义，并消除每个请求都触发的噪声定价警告。
|
||||
|
||||
### CI：前端格式化 + Linux clippy 恢复
|
||||
|
||||
恢复前端格式化与 Linux clippy 在 CI 中的运行。
|
||||
|
||||
### 代理测试 helper clippy 警告
|
||||
|
||||
修复代理测试 helper 中的一个 clippy 警告。
|
||||
|
||||
---
|
||||
|
||||
## 移除
|
||||
|
||||
### Hermes Agent 用量追踪集成
|
||||
|
||||
移除原本计划在本周期上线的 Hermes Agent 用量追踪集成——上游行为变化让维护这个集成变得不切实际。该集成**从未在任何已发布版本中启用**；开发过程中发现的"零成本渲染" bug 在回滚集成前已经修复。
|
||||
|
||||
### 主题切换圆形扩散动画
|
||||
|
||||
移除主题切换时的圆形扩散动画——在性能较弱的合成器上会卡顿，视觉收益有限。
|
||||
|
||||
### DDSHub 合作伙伴整合
|
||||
|
||||
移除 DDSHub 作为合作伙伴预设，并删除各 README 中的交叉链接段落。
|
||||
|
||||
---
|
||||
|
||||
## 文档
|
||||
|
||||
### README 赞助商刷新（中 / 英 / 日）
|
||||
|
||||
新增 BytePlus、ClaudeCN、RunAPI、PatewayAI 赞助商条目；交叉链接 BytePlus 与火山条目；刷新 CrazyRouter 的 $2 额度领取流程、Compshare 描述、Right Code 描述、其他赞助商的 logo 与列表项；把 LionCC logo 抹平到白底；中文 README 的赞助商 logo 切到火山图；在 README 副标题中加入 Hermes Agent。
|
||||
|
||||
### Release notes 模板
|
||||
|
||||
Release notes 模板中呈现 `ccswitch.io`。
|
||||
|
||||
### 品牌官网
|
||||
|
||||
在各 README 与应用内引用中把 `ccswitch.io` 文档化为唯一官方网站。
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 升级提醒
|
||||
|
||||
### 20 个 Claude Desktop 预设默认切到直连模式
|
||||
|
||||
这 20 个预设之前默认通过代理路由，现在默认直连。如果你升级前正好用着其中某个、又依赖代理路由的连通性（比如代理里有特殊补正器或转换层），请验证一下连通性；如有需要，可在 CC Switch 面板里手动切回代理模式。
|
||||
|
||||
### Claude Desktop 操作约束
|
||||
|
||||
切换 Claude Desktop 供应商需要**重启 Claude Desktop** 才能生效；代理模式的供应商在使用期间需要 CC Switch 的 Local Routing 保持运行——退出 CC Switch 或停止 Local Routing 会让代理模式的 Claude Desktop 供应商断流。
|
||||
|
||||
### Failover 需要接管启用
|
||||
|
||||
启用 Failover 前请先确认目标应用的 Local Routing 接管已开启，否则 Failover 控件会拒绝启动；想关代理服务但仍有应用依赖接管的情况会被拦下，需要先在应用层关掉接管再停代理。
|
||||
|
||||
### 用量统计数字可能与历史不一致
|
||||
|
||||
用量摘要现在用缓存归一化的真实总 token + 缓存命中率。历史 token 与成本数字在数据去重 + 价格重算后**可能会有偏移**——新数字更准，但不会等于旧版给出的数字。
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 风险提示
|
||||
|
||||
本版本在涉及反向代理类功能上沿用 v3.12.3 / v3.13.0 提出的风险提示。
|
||||
|
||||
**GitHub Copilot 反向代理**：使用 Copilot 的反代路径可能违反 GitHub / Microsoft 服务条款。详情见 [v3.12.3 release notes](v3.12.3-zh.md#️-风险提示)。
|
||||
|
||||
**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
|
||||
|
||||
**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，第三方供应商对计费、合规与数据留存的约束各不相同，请在使用前阅读目标供应商的服务条款。
|
||||
|
||||
用户启用上述功能即表示**自行承担所有风险**。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 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| 文件 | 说明 |
|
||||
| ---------------------------------------- | ----------------------------------- |
|
||||
| `CC-Switch-v3.15.0-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.15.0-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| -------------------------------- | --------------------------------------------- |
|
||||
| `CC-Switch-v3.15.0-macOS.dmg` | **推荐** - DMG 安装包，拖入 Applications 即可 |
|
||||
| `CC-Switch-v3.15.0-macOS.zip` | 解压后拖入 Applications，Universal Binary |
|
||||
| `CC-Switch-v3.15.0-macOS.tar.gz` | 用于 Homebrew 安装和自动更新 |
|
||||
|
||||
> macOS 版本已通过 Apple 代码签名和公证，可直接安装使用。
|
||||
|
||||
### Homebrew（macOS）
|
||||
|
||||
> 🎉 CC Switch 现已收录至 Homebrew 官方 cask 仓库，无需添加第三方 tap！
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
> Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本：
|
||||
>
|
||||
> - `CC-Switch-v3.15.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
> - `CC-Switch-v3.15.0-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| 发行版 | 推荐格式 | 安装方式 |
|
||||
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| 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` |
|
||||
@@ -0,0 +1,434 @@
|
||||
# CC Switch v3.16.0
|
||||
|
||||
> Chat Completions → Responses format conversion for Codex (you can now use DeepSeek, Kimi, GLM in Codex!), unified Codex provider identity and history, an all-around upgraded app management surface, partner preset expansion, default model / pricing matrix upgraded to GPT-5.5 and Claude Opus 4.8, and proxy / format-conversion robustness hardening
|
||||
|
||||
**[中文版 →](v3.16.0-zh.md) | [日本語版 →](v3.16.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Usage Guide
|
||||
|
||||
The two headline capabilities in this release are **Codex third-party provider Chat Completions routing** and **in-app managed CLI tool management**. If you want providers that only speak the OpenAI Chat protocol (DeepSeek, Kimi, MiniMax, etc.) to work directly in Codex, or want to install / upgrade CLI tools from one place inside the app, start with these guides:
|
||||
|
||||
- **[Using DeepSeek in Codex: local routing hands-on guide](../guides/codex-deepseek-routing-guide-en.md)** — uses the built-in DeepSeek preset to walk through adding a Codex provider, enabling local routing, and verifying request forwarding.
|
||||
- **[Add a Codex provider: Chat Completions routing and model mapping](../user-manual/en/2-providers/2.1-add.md)** — covers the "Needs Local Routing" toggle, the model mapping table, and reasoning (thinking) auto-detection.
|
||||
- **[Settings → About: managed CLI tool management](../user-manual/en/1-getting-started/1.5-settings.md)** — covers version detection, per-tool / update-all upgrades, conflict diagnostics, and source-anchored upgrade commands.
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## Only Official Channels (Please Read)
|
||||
>
|
||||
> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Multiple imposter websites have recently been spotted impersonating CC Switch to solicit payments and harvest account credentials, with some users already reporting financial losses. Please only obtain the software through the official channels listed below:
|
||||
>
|
||||
> | Channel | Only Official |
|
||||
> | ------------------ | ------------------------------------------------------------------------------ |
|
||||
> | Website | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | Source | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | Downloads | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | Author | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues so we can take down the imposter site as quickly as possible.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.16.0's development since v3.15.0 centers on **promoting third-party Codex providers to first-class citizens through Chat Completions routing**. Codex natively only speaks the OpenAI Responses API and GPT-family models; this release lets CC Switch's local proxy convert Codex's outgoing Responses requests into Chat Completions and rebuild the JSON and SSE streaming responses back into Responses shape, preserving `reasoning_content` / inline `<think>` blocks / streamed reasoning summaries / tool calls / `previous_response_id` follow-ups along the way, normalizing error envelopes, and probing Chat-format providers correctly in Stream Check. It ships 22 Chat-routing presets with explicit model catalogs (DeepSeek, Zhipu GLM, Kimi, MiniMax, StepFun, Baidu Qianfan, Bailian, ModelScope, Longcat, BaiLing, Xiaomi MiMo, Volcengine Agentplan, BytePlus, DouBao Seed, SiliconFlow, Novita AI, Nvidia, and more).
|
||||
|
||||
Codex third-party providers' **identity and history** are unified and hardened this release: all third-party providers now normalize to the stable `custom` model-provider bucket, with a one-shot device migration that rewrites historical JSONL sessions and the `state_5.sqlite` threads table (originals backed up under `~/.cc-switch/backups/`), preventing past sessions from appearing to vanish when provider ids change. It also fixes OAuth login state, user-selected catalog models, and user-authored provider ids being overwritten during live reads / switches.
|
||||
|
||||
This release also adds an **in-app managed CLI tool lifecycle**: the Settings / About tab becomes a tool management panel for Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes, with silent install / update, update-all, conflict diagnostics, source-aware anchored upgrades, WSL handling, and visible "installed but not runnable" states.
|
||||
|
||||
The provider ecosystem and model matrix are refreshed in tandem: added APIKEY.FUN, APINebula, AtlasCloud, SudoCode, Xiaomi MiMo Token Plan, and Claude Desktop Official presets; refreshed partner links and default models / pricing across apps; upgraded the default Claude Opus line to **4.8** and GPT defaults to **5.5** where applicable. Plus extensive polish and fixes across usage observability, Traditional Chinese localization, docs, and proxy / format-conversion robustness.
|
||||
|
||||
**Release date**: 2026-05-29
|
||||
|
||||
**Stats**: 101 commits | 221 files changed | +27,063 insertions | -3,052 deletions
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- **Codex Chat Completions routing**: Codex providers can now be served by OpenAI-compatible Chat Completions upstreams. CC Switch converts Codex Responses requests into Chat Completions, rebuilds JSON and SSE responses back into Responses shape, preserves reasoning / `<think>` / tool-call state, normalizes error envelopes, and probes Chat-format providers correctly in Stream Check.
|
||||
- **Codex third-party provider state is unified and safer**: third-party Codex providers now share the stable `custom` model-provider bucket, with a one-shot migration for historical JSONL sessions and `state_5.sqlite` threads, plus fixes that preserve OAuth login state, user-selected catalog models, and user-authored provider ids during live reads / switches.
|
||||
- **Managed CLI tool management**: the About page is now a tool management panel for Claude, Codex, Gemini, OpenCode, OpenClaw, and Hermes, with install / update actions, update-all, conflict diagnostics, source-aware anchored upgrades, WSL handling, and visible "installed but not runnable" states.
|
||||
- **Provider ecosystem and model matrix refresh**: added APIKEY.FUN, APINebula, AtlasCloud, SudoCode, Xiaomi MiMo Token Plan, and Claude Desktop Official presets; refreshed partner links and default models / pricing across apps; upgraded the default Claude Opus model line to 4.8 and GPT defaults to 5.5 where applicable.
|
||||
- **Usage and docs polish**: Usage Dashboard updates now react immediately when logs are written, custom usage-script summaries and subagent session-log accounting were fixed, Traditional Chinese UI localization landed, and a German README plus expanded Claude Desktop / Codex Chat / tool-management manuals were added.
|
||||
- **Proxy and conversion hardening**: fixed Codex Chat reasoning / cache / usage edge cases, DeepSeek Anthropic tool-thinking history, Claude-compatible empty `tool_calls` streams, managed-account takeover auth, MiMo reasoning output, Gemini Native tool-call replay, and several panic-prone proxy paths.
|
||||
|
||||
---
|
||||
|
||||
## Added
|
||||
|
||||
### Codex Chat Completions Routing
|
||||
|
||||
Codex providers can now be served by upstreams that only speak the OpenAI Chat Completions API. CC Switch's local proxy converts Codex's outgoing Responses requests into Chat Completions and rebuilds the Chat response (both JSON and SSE) back into Responses shape, preserving `reasoning_content`, inline `<think>` blocks, streamed reasoning summaries, tool calls, and `previous_response_id` follow-ups. A bounded Codex Chat history cache restores tool calls before their tool outputs.
|
||||
|
||||
> 💡 Special thanks to [@EldenPdx](https://github.com/EldenPdx) for PR [#2804](https://github.com/farion1231/cc-switch/pull/2804): this feature's Chat ↔ Responses format conversion references the implementation in his PR.
|
||||
|
||||
### 22 Codex Third-Party Provider Presets with Chat Routing
|
||||
|
||||
Enabled Chat Completions routing with explicit model catalogs for major Chinese/Asian providers — DeepSeek, Zhipu GLM (+ en), Kimi, MiniMax (+ en), StepFun (+ en), Baidu Qianfan Coding Plan, Bailian, ModelScope, Longcat, BaiLing, Xiaomi MiMo (+ Token Plan), Volcengine Agentplan, BytePlus, DouBao Seed, SiliconFlow (+ en), Novita AI, and Nvidia. Each preset declares its context window so the UI can size the model-mapping rows.
|
||||
|
||||
### Codex Model Mapping Table
|
||||
|
||||
Codex provider forms now expose a model catalog (model + display name + context window per row) that is the single source of truth for the upstream model list, projected to `~/.codex/cc-switch-model-catalog.json`.
|
||||
|
||||
### Codex Chat Providers in Stream Check
|
||||
|
||||
Stream Check now probes Chat-format Codex providers against `/chat/completions` with a Chat-shaped body instead of `/v1/responses`, and aligns its URL fallback order with the production `CodexAdapter` (origin-only base URLs hit `/v1/<endpoint>` first) so a non-404 error on the bare path no longer flags a working provider as down.
|
||||
|
||||
### Codex Chat Reasoning Auto-Detection
|
||||
|
||||
When a Codex provider is served through Chat Completions routing, CC Switch now auto-detects the upstream's reasoning interface from its name, base URL, and model — injecting the correct thinking parameter (`thinking:{type}`, `enable_thinking`, `reasoning_split`, top-level `reasoning_effort`, or OpenRouter's native `reasoning:{effort}` object) with no manual setup. Aggregator/hosting platforms (OpenRouter, SiliconFlow) are matched platform-first, since the same model can expose different reasoning controls on different platforms. Providers that only expose a thinking on/off switch (Kimi, GLM, Qwen, MiniMax, MiMo, SiliconFlow) drop the effort _level_ instead of forwarding an unsupported field — so changing Codex's reasoning effort has no effect for them — while providers with real effort tiers (DeepSeek, OpenRouter, and StepFun's `step-3.5-flash-2603` only) pass the level through. OpenRouter specifically uses the native `reasoning:{effort}` object, clamps `max` to `xhigh` (its enum has no `max`), and forwards an explicit `effort:"none"` so reasoning can be turned off.
|
||||
|
||||
### Codex Goal Mode and Remote Compaction Controls
|
||||
|
||||
Codex config editing now exposes a Goal Mode toggle and a Remote Compaction toggle for third-party providers; new Codex templates default to `disable_response_storage = true` while still allowing explicit goal support.
|
||||
|
||||
### Xiaomi MiMo Token Plan Presets
|
||||
|
||||
Added Xiaomi MiMo Token Plan presets with specs aligned to the official documentation (#2803, thanks @BlueOcean223).
|
||||
|
||||
### Claude Desktop Official Preset
|
||||
|
||||
Added a Claude Desktop Official preset that restores the native Claude Desktop login, plus a localized Claude Desktop user guide (en / zh / ja).
|
||||
|
||||
### Managed CLI Tool Lifecycle
|
||||
|
||||
Added silent install / update commands for managed CLI tools, latest-version checks, per-tool and batch actions, update-all, and diagnostics for multiple installations across PATH, Homebrew, npm, pnpm, bun, volta, fnm, nvm, scoop, WinGet, Windows native paths, and WSL.
|
||||
|
||||
### Source-Aware Tool Diagnostics
|
||||
|
||||
The Settings / About surface can now diagnose conflicting tool installations, show the concrete install source and version for each path, and generate backend-planned upgrade commands anchored to the actual installation source.
|
||||
|
||||
### Real-Time Usage Refresh
|
||||
|
||||
The backend now emits `usage-log-recorded` when proxy logs, session-log syncs, or rollups write usage data; Usage Dashboard listens for that event and invalidates its queries immediately instead of waiting for the next polling interval (#3027, thanks @in30mn1a).
|
||||
|
||||
### Traditional Chinese Localization
|
||||
|
||||
Added `zh-TW` UI localization and a settings language option (#3093, thanks @LaiYueTing).
|
||||
|
||||
### German README
|
||||
|
||||
Added `README_DE.md` and linked it from the existing README language switchers (#2994, thanks @flitzrrr).
|
||||
|
||||
### New Partner Presets
|
||||
|
||||
Added APIKEY.FUN, APINebula, AtlasCloud, and SudoCode partner presets across the supported app surfaces, with partner copy, icons, and README entries.
|
||||
|
||||
---
|
||||
|
||||
## Changed
|
||||
|
||||
### Codex Third-Party Providers Unified into a "custom" History Bucket
|
||||
|
||||
Codex filters resume history by `model_provider`, so switching between provider-specific ids made past sessions appear to vanish. All third-party providers now normalize to a single stable `custom` bucket (reserved built-in ids like `openai` / `ollama` are preserved), with a one-shot device migration that rewrites historical JSONL sessions and the `state_5.sqlite` threads table and backs up originals under `~/.cc-switch/backups/codex-history-provider-migration-v1/`.
|
||||
|
||||
### Codex Provider Form Simplified
|
||||
|
||||
Removed the API Format selector from the Codex form (`wire_api` is always `responses`, so the selector misleadingly implied a protocol change); the model mapping table is now the only source of truth with no hidden default entries, and the form notes that a Codex restart is required after catalog changes since `model_catalog_json` is loaded at startup. Only the "Needs Local Routing" toggle remains.
|
||||
|
||||
### Codex Local Routing Toggle Hints Rewritten
|
||||
|
||||
Reframed the OFF / ON hints as action guidance (when to enable) rather than scenario descriptions, synced across zh / en / ja.
|
||||
|
||||
### Codex Live Config Preservation
|
||||
|
||||
Live Codex config reads no longer force-rewrite a user's `model_provider` field, and provider-scoped `experimental_bearer_token` handling now preserves OAuth login state when switching between third-party providers.
|
||||
|
||||
### Tool Install / Upgrade Strategy
|
||||
|
||||
Managed tool installation now prefers official native installers where available, falls back to package managers when appropriate, runs self-update first for compatible tools, anchors upgrades to the detected install source, and locks duplicate batch actions while work is in flight.
|
||||
|
||||
### About Page Becomes Tool Management
|
||||
|
||||
The About settings page now presents installed / latest versions, install and update actions, conflict diagnostics, WSL shell preferences, and clearer status for broken or unrunnable tools.
|
||||
|
||||
### Default Models and Pricing Refreshed
|
||||
|
||||
Upgraded the default Claude Opus model to 4.8, moved GPT-based presets and templates to GPT-5.5 where applicable, refreshed pricing seeds, aligned Claude Desktop model mapping with Claude Code's three-role tiers, and renamed the OpenCode Go preset to drop a stale model suffix.
|
||||
|
||||
### Partner Links Refreshed
|
||||
|
||||
Updated ShengSuanYun referral links, Atlas Cloud UTM links, and partner copy across README locales and provider metadata.
|
||||
|
||||
### Homebrew Official Cask Installation
|
||||
|
||||
Installation simplified to `brew install --cask cc-switch` now that CC Switch is in the official Homebrew repository; the personal-tap requirement was removed from all READMEs.
|
||||
|
||||
### Shared Frontend Utilities
|
||||
|
||||
Replaced JSON stringify / parse deep-copy patterns with a shared `deepClone` helper and extracted a shared `useTauriEvent` hook (#3140, thanks @ChongBiaoZhang).
|
||||
|
||||
---
|
||||
|
||||
## Fixed
|
||||
|
||||
### Codex Chat Error Responses Converted to Responses Envelope
|
||||
|
||||
The Codex Chat-to-Responses bridge previously passed upstream error bodies through untouched, leaving Codex clients unable to recognize MiniMax `base_resp`, raw OpenAI Chat errors, or plain-text / HTML error pages. Errors are now regularized into the standard `{error: {message, type, code, param}}` envelope with the original HTTP status preserved; non-JSON bodies are wrapped and truncated to 1KB at a UTF-8 char boundary. Also fixed a pre-existing append-vs-insert bug that emitted a duplicate `Content-Type` header on rewritten JSON bodies.
|
||||
|
||||
### Codex Mid-Stream System Messages Collapsed
|
||||
|
||||
MiniMax's OpenAI-compatible endpoint strict-rejects any non-leading `system` message (error 2013). All `system` fragments are now collapsed into a single leading message (joined in original order), losslessly for permissive backends too.
|
||||
|
||||
### Codex Model Catalog Wiped After Restart
|
||||
|
||||
Editing the active Codex provider triggered a live read that omitted `modelCatalog`, so a subsequent save silently destroyed user-configured model mappings. Live reads now reverse-parse the on-disk catalog projection to round-trip the same shape the save path writes.
|
||||
|
||||
### Codex Model Catalog Infinite Render Loop
|
||||
|
||||
Broke a bidirectional sync cycle between the catalog table and its parent state that caused severe UI jittering when adding or editing entries.
|
||||
|
||||
### Codex Chat Preserves User-Selected Catalog Model
|
||||
|
||||
A model the client selects from the catalog (e.g. via `/model`) is no longer overwritten by `config.toml`'s default model.
|
||||
|
||||
### Codex Chat Reasoning and Cache Stability
|
||||
|
||||
Restored a unique call-id fallback when Codex omits or rewrites `previous_response_id`, stopped deriving cache identity from `previous_response_id`, and canonicalized parseable JSON string payloads in tool conversions for stable prefix-cache reuse.
|
||||
|
||||
### Codex Chat Streaming Usage Recovered
|
||||
|
||||
The Responses-to-Chat conversion now injects `stream_options.include_usage` (merging into any client-provided `stream_options`) when a request is streaming, so OpenAI-compatible upstreams like Kimi and MiniMax emit the trailing usage chunk again. Previously their streamed token / cost / cache stats were recorded as zero on the Codex Chat path.
|
||||
|
||||
### Codex Chat Tool-Call Reasoning Backfill
|
||||
|
||||
Thinking models like Kimi/Moonshot and DeepSeek reject an assistant message that carries `tool_calls` without a non-empty `reasoning_content`. When cross-turn history recovery misses (proxy restart, ambiguous `call_id`, or a turn with no upstream reasoning), a placeholder `reasoning_content` is now backfilled in a final pass — genuine trailing reasoning still attaches first — so the request no longer fails with `reasoning_content is missing in assistant tool call message`.
|
||||
|
||||
### Managed-Account Claude Takeover Auth
|
||||
|
||||
Managed-account providers (GitHub Copilot / Codex OAuth) now drop token env keys and write only the `ANTHROPIC_API_KEY` placeholder when taking over Claude Live config, with an outbound guard that refuses to send the `PROXY_MANAGED` placeholder upstream.
|
||||
|
||||
### Claude Desktop Profile Sync During Takeover
|
||||
|
||||
Claude Desktop profile data is now synced during proxy takeover, model routes align with the Claude Code three-role tiers, and the Cowork egress profile has been corrected (#3157, #3172, thanks @MelorTang, @JGSphaela).
|
||||
|
||||
### Managed-Account Takeover Model Fields
|
||||
|
||||
Local Routing now sources takeover model fields from the target provider on managed accounts instead of carrying stale model values.
|
||||
|
||||
### DeepSeek Anthropic Tool Thinking History
|
||||
|
||||
Normalized DeepSeek Anthropic-compatible tool-thinking history so later turns can replay reasoning / tool-call context without malformed messages (#3203, thanks @Q3yp).
|
||||
|
||||
### Claude-Compatible Empty Tool Calls in Streams
|
||||
|
||||
Fixed a Claude-compatible streaming edge case where an empty `tool_calls` array reset block state and broke streamed responses (#2915, thanks @zhizhuowq).
|
||||
|
||||
### MiMo Reasoning for Claude Code Proxy
|
||||
|
||||
Added MiMo `reasoning_content` support on the Claude Code proxy path (#2990, thanks @zhangyapu1).
|
||||
|
||||
### Gemini Native Tool-Call Robustness
|
||||
|
||||
Fixed `functionResponse.name` resolution (422) and `thought_signature` replay (400) for synthesized tool-call IDs in long multi-turn sessions (#2814, thanks @Tiancrimson).
|
||||
|
||||
### Session Log Subagent Token Accounting
|
||||
|
||||
`collect_jsonl_files()` now scans subagent JSONL logs that were previously missed, so subagent token usage is counted in session cost (session-log mode only) (#2821, thanks @LaoYueHanNi).
|
||||
|
||||
### Usage Dashboard / Sync Stability
|
||||
|
||||
Fixed a Codex usage-sync panic on non-ASCII model names, custom usage-script summaries, and missing real-time refresh after usage rollups (#3027, #3129, thanks @in30mn1a, @hanhan3344).
|
||||
|
||||
### ZhiPu Coding-Plan Quota Tier Ordering
|
||||
|
||||
When the 5-hour bucket is at 0% utilization, ZhiPu's API omits `nextResetTime`; the old `i64::MAX` sentinel sorted those entries last, letting the weekly bucket incorrectly claim the five-hour slot. Tiers now sort so a missing `nextResetTime` maps to the five-hour bucket, so tray and usage quota display stays correct for ZhiPu coding plans.
|
||||
|
||||
### Skills Install by Key
|
||||
|
||||
Installing from skills.sh search results now uses the unique key instead of the directory name, so skills that share a directory name install the correct one (#2784, thanks @zhaomoran); also fixed a skill sync copy fallback (#2791, thanks @rogerdigital).
|
||||
|
||||
### Usage Price Input Precision
|
||||
|
||||
Reduced the price input step to 0.0001 so sub-cent costs like DeepSeek cache reads can be entered (#2793, closes #2503, thanks @rogerdigital).
|
||||
|
||||
### Ghostty Clean Window Launch
|
||||
|
||||
Ghostty now opens a single clean window instead of cloning existing tabs, and other terminals open a new window via `open -na` (#2801, closes #2798, thanks @luw2007).
|
||||
|
||||
### Tool Version and Update Reliability
|
||||
|
||||
Version probing no longer masks unrunnable installs, prerelease tools are handled correctly in version checks, batch updates run per tool, install / update buttons stay locked during preflight, anchored upgrade branches enforce absolute paths, and WSL installer paths use native Unix installers when needed.
|
||||
|
||||
### Codex mise Detection
|
||||
|
||||
Fixed Codex mise environment detection (#2822, thanks @iambinlin).
|
||||
|
||||
### Codex Archived Sessions
|
||||
|
||||
Codex archived sessions are now included in session discovery (#2861, thanks @nanmen2).
|
||||
|
||||
### Codex Chat Empty Tool Arguments
|
||||
|
||||
Empty tool-call argument payloads are coerced to `{}` during Codex Chat conversion so upstreams and clients receive valid JSON.
|
||||
|
||||
### Claude Provider Deeplink Imports
|
||||
|
||||
Importing Claude providers through deeplinks now preserves custom environment fields (#2928, thanks @doutuifei).
|
||||
|
||||
### OMO Recommended Models
|
||||
|
||||
Synced OMO recommended models with upstream defaults and improved Fill Recommended feedback.
|
||||
|
||||
### ShengSuanYun Model IDs Prefixed for Routing
|
||||
|
||||
ShengSuanYun (胜算云) presets now carry the vendor prefixes the upstream gateway requires — `anthropic/…`, `google/…`, and `openai/…` (e.g. `anthropic/claude-sonnet-4.6`, `google/gemini-3.1-pro-preview`) — across the Claude Code, Claude Desktop, Codex, Gemini, OpenCode, and OpenClaw presets, including the Claude Code routing env (`ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_{HAIKU,SONNET,OPUS}_MODEL`), so they resolve to valid upstream models instead of failing to route.
|
||||
|
||||
### ClaudeAPI Model Test Re-Enabled
|
||||
|
||||
Reclassified the ClaudeAPI preset (Claude Code and Claude Desktop) from `third_party` to `aggregator` so its model test button is no longer disabled by the third-party Claude gate; the partner star is unaffected since it is driven by `isPartner`, not category.
|
||||
|
||||
### About Version Check
|
||||
|
||||
Version checks now handle prerelease tool versions without misclassifying update state.
|
||||
|
||||
### App Switcher Text Clipping
|
||||
|
||||
Removed a fixed width constraint that clipped app-switcher text (#3161, thanks @loocor).
|
||||
|
||||
### useEffect Race Condition
|
||||
|
||||
Added an active-flag pattern to App.tsx effects to prevent listener leaks on unmount, and guarded against storing `undefined` language in localStorage (#2827, thanks @Zylo206).
|
||||
|
||||
---
|
||||
|
||||
## Removed
|
||||
|
||||
### LionCC Sponsor and Presets
|
||||
|
||||
Removed the LionCC sponsor entry and LionCCAPI presets across READMEs, provider configs, and locales (icon asset retained).
|
||||
|
||||
### AICoding Partner Entry
|
||||
|
||||
Removed the AICoding partner from README sponsor listings, provider presets, and i18n metadata.
|
||||
|
||||
### Kimi For Coding Codex Preset
|
||||
|
||||
Removed the Kimi For Coding preset from the Codex preset catalog.
|
||||
|
||||
### CLI Uninstall Command Hints
|
||||
|
||||
Dropped generated CLI uninstall command hints from the tool-management UI while keeping conflict diagnostics visible.
|
||||
|
||||
---
|
||||
|
||||
## Docs
|
||||
|
||||
### Codex Chat Provider Support
|
||||
|
||||
Documented Chat Completions routing, provider support, reasoning auto-detection, and Local Routing guidance in the changelog and user manual.
|
||||
|
||||
### Settings Manual Refresh
|
||||
|
||||
Updated settings documentation for the new managed tool lifecycle and Hermes installer behavior.
|
||||
|
||||
### Claude Desktop Guide
|
||||
|
||||
Added localized Claude Desktop guide pages and screenshots for provider setup, import, model mapping, and Local Routing context.
|
||||
|
||||
### Installation Docs
|
||||
|
||||
Updated installation docs and READMEs to recommend the official Homebrew cask and refreshed the v3.15.0 release-note imposter-site warning wording across locales.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Upgrade Notes
|
||||
|
||||
### One-Shot Codex History Migration
|
||||
|
||||
The first launch after upgrading runs a one-shot migration of Codex history: third-party providers are normalized into the `custom` bucket and historical JSONL sessions plus the `state_5.sqlite` threads table are rewritten. Originals are backed up under `~/.cc-switch/backups/codex-history-provider-migration-v1/`. This step fixes the "past sessions vanish after switching provider" problem — history resumes correctly after the migration.
|
||||
|
||||
### Codex Catalog Changes Require a Restart
|
||||
|
||||
Codex loads `model_catalog_json` at startup, so after editing the model mapping table in CC Switch you must **restart Codex** for the new catalog to take effect.
|
||||
|
||||
### Reasoning Effort May Have No Effect for Chat-Routing Providers
|
||||
|
||||
For providers that only expose a thinking on/off switch (Kimi, GLM, Qwen, MiniMax, MiMo, SiliconFlow), changing the reasoning effort in Codex (`model_reasoning_effort`: low / medium / high) **has no effect** — CC Switch will not forward an unsupported effort field to them. Only providers with real effort tiers (DeepSeek, OpenRouter, and StepFun's `step-3.5-flash-2603` only) actually honor the level.
|
||||
|
||||
### Default Models Upgraded to Opus 4.8 / GPT-5.5
|
||||
|
||||
The default Claude Opus model line is upgraded to 4.8 and GPT defaults to 5.5 where applicable. If you rely on a pinned older default model, check the model fields of the relevant presets / templates after upgrading.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Risk Notice
|
||||
|
||||
This release inherits the risk notices originally introduced in v3.12.3 / v3.13.0 / v3.15.0 for reverse-proxy-style features.
|
||||
|
||||
**GitHub Copilot Reverse Proxy**: Using Copilot's reverse-proxy path may violate GitHub / Microsoft's terms of service. See the [v3.12.3 release notes](v3.12.3-en.md#️-risk-notice) for details.
|
||||
|
||||
**Codex OAuth Reverse Proxy**: Using the Codex OAuth reverse proxy with a ChatGPT subscription may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details.
|
||||
|
||||
**Codex Third-Party Provider Chat Routing**: Converting and forwarding Codex requests through CC Switch's local proxy to a third-party provider exposes those requests to that provider's billing, compliance, and data-retention policies — read the target provider's terms of service before using.
|
||||
|
||||
**Claude Desktop Third-Party Provider Switching via Proxy Gateway**: Routing Claude Desktop traffic through CC Switch's in-app proxy gateway to a third-party provider exposes those requests to that provider's billing, compliance, and data-retention policies — read the target provider's terms of service before using.
|
||||
|
||||
By enabling these features, users **accept all associated risks**. CC Switch is not responsible for any account restrictions, warnings, or service suspensions that result from using these features.
|
||||
|
||||
---
|
||||
|
||||
## Download & Installation
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download the appropriate version.
|
||||
|
||||
### System Requirements
|
||||
|
||||
| OS | Minimum Version | Architecture |
|
||||
| ------- | ---------------------------- | ----------------------------------- |
|
||||
| Windows | Windows 10 or later | x64 |
|
||||
| macOS | macOS 12 (Monterey) or later | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | See table below | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| File | Description |
|
||||
| ---------------------------------------- | ----------------------------------------------------- |
|
||||
| `CC-Switch-v3.16.0-Windows.msi` | **Recommended** - MSI installer, supports auto-update |
|
||||
| `CC-Switch-v3.16.0-Windows-Portable.zip` | Portable, extract and run, no registry writes |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| -------------------------------- | ------------------------------------------------------- |
|
||||
| `CC-Switch-v3.16.0-macOS.dmg` | **Recommended** - DMG installer, drag into Applications |
|
||||
| `CC-Switch-v3.16.0-macOS.zip` | Extract and drag into Applications, Universal Binary |
|
||||
| `CC-Switch-v3.16.0-macOS.tar.gz` | For Homebrew installation and auto-update |
|
||||
|
||||
> macOS builds are Apple code-signed and notarized — install directly.
|
||||
|
||||
### Homebrew (macOS)
|
||||
|
||||
> 🎉 CC Switch is now available in the official Homebrew cask repository — no need to add a custom tap!
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
> Linux artifacts are published for both **x86_64** and **ARM64** (`aarch64`). The architecture is included in the asset filename — pick the one matching your machine's `uname -m` output:
|
||||
>
|
||||
> - `CC-Switch-v3.16.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
> - `CC-Switch-v3.16.0-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| Distribution | Recommended | Installation |
|
||||
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| 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, or use AUR |
|
||||
| Other distros / not sure | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
@@ -0,0 +1,434 @@
|
||||
# CC Switch v3.16.0
|
||||
|
||||
> Codex 向けに Chat Completions → Responses フォーマット変換を追加（Codex で DeepSeek・Kimi・GLM が使えるようになりました！）、Codex プロバイダーの身元と履歴を統一、アプリ管理パネルの全方位強化、パートナープリセットの拡張、デフォルトモデル / 価格マトリクスを GPT-5.5 と Claude Opus 4.8 にアップグレード、プロキシ / フォーマット変換のロバスト性強化
|
||||
|
||||
**[English →](v3.16.0-en.md) | [中文 →](v3.16.0-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## 利用ガイド
|
||||
|
||||
本リリースの主役となる 2 つの機能は、**Codex サードパーティプロバイダーの Chat Completions ルーティング**と**アプリ内の管理対象 CLI ツール管理**です。OpenAI Chat プロトコルにしか対応していないプロバイダー（DeepSeek、Kimi、MiniMax など）を Codex で直接使いたい場合、またはアプリ内で CLI ツールの一括インストール / アップグレードをしたい場合は、まずこちらをご覧ください：
|
||||
|
||||
- **[Codex で DeepSeek を使う: ローカルルーティング実践ガイド](../guides/codex-deepseek-routing-guide-ja.md)** —— DeepSeek 内蔵プリセットを例に、Codex プロバイダーの追加、ローカルルーティングの有効化、リクエスト転送の確認までを説明します。
|
||||
- **[Codex プロバイダーの追加: Chat Completions ルーティングとモデルマッピング](../user-manual/ja/2-providers/2.1-add.md)** —— 「ローカルルーティングが必要」トグル、モデルマッピングテーブル、思考能力（reasoning）の自動判別までの一連の流れを説明しています。
|
||||
- **[設定 → バージョン情報: 管理対象 CLI ツール管理](../user-manual/ja/1-getting-started/1.5-settings.md)** —— バージョン検出、個別アップグレード / 全体アップグレード、競合診断、インストール元にアンカーされたアップグレードコマンドを説明しています。
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## 唯一の公式チャネル（必ずお読みください）
|
||||
>
|
||||
> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。最近、CC Switch の名を騙って課金を要求したり認証情報を収集する偽サイトが複数確認されており、一部のユーザーには既に金銭的被害が発生しています。本ソフトウェアは下記の公式チャネルからのみ入手してください：
|
||||
>
|
||||
> | チャネル | 唯一の公式 |
|
||||
> | ------------ | ------------------------------------------------------------------------------ |
|
||||
> | 公式サイト | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | 作者 | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は、直ちに取引を中止し、偽サイトを速やかに削除できるよう GitHub Issues からご報告ください。
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.16.0 の v3.15.0 以降の開発のコアは、**サードパーティ Codex プロバイダーを Chat Completions ルーティングによって一等市民へ昇格させること**です。Codex はネイティブには OpenAI Responses API と GPT 系モデルしか認識しませんが、本リリースでは CC Switch のローカルプロキシが Codex の送出する Responses リクエストを Chat Completions に変換し、JSON と SSE のストリーミングレスポンスを Responses 形態へ再構築します。その道中で `reasoning_content` / インライン `<think>` ブロック / ストリーミング推論サマリー / ツール呼び出し / `previous_response_id` の継続を保持し、エラーエンベロープを正規化し、Stream Check で Chat 形式プロバイダーを正しくプローブします。あわせて明示的なモデルカタログ付きの 22 個の Chat ルーティングプリセット（DeepSeek、Zhipu GLM、Kimi、MiniMax、StepFun、Baidu Qianfan、Bailian、ModelScope、Longcat、BaiLing、Xiaomi MiMo、Volcengine Agentplan、BytePlus、DouBao Seed、SiliconFlow、Novita AI、Nvidia など）を出荷します。
|
||||
|
||||
Codex サードパーティプロバイダーの**身元と履歴**は、本リリースで統一・堅牢化されました: すべてのサードパーティプロバイダーが安定した `custom` model-provider バケットに正規化され、過去の JSONL セッションと `state_5.sqlite` のスレッドテーブルを書き換える一回限りのデバイスマイグレーション（オリジナルは `~/.cc-switch/backups/` 配下にバックアップ）を提供することで、プロバイダー id の変更によって過去のセッションが消えたように見える問題を防ぎます。あわせて、live 読み取り / 切り替えの際に OAuth ログイン状態、ユーザーが選択したカタログモデル、ユーザー定義のプロバイダー id が上書きされる問題も修正しました。
|
||||
|
||||
本リリースではさらに、**アプリ内蔵の受託 CLI ツールライフサイクル**を追加しました: 設定の「バージョン情報」タブが Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes のツール管理パネルに昇格し、サイレントインストール / 更新、全体アップグレード、競合診断、インストール元を考慮したアンカー型アップグレード、WSL の取り扱い、「インストール済みだが実行できない」状態の可視化に対応します。
|
||||
|
||||
プロバイダーエコシステムとモデルマトリクスも並行してリフレッシュされました: APIKEY.FUN、APINebula、AtlasCloud、SudoCode、Xiaomi MiMo Token Plan、Claude Desktop 公式プリセットを追加; 各アプリのパートナーリンクとデフォルトモデル / 価格をリフレッシュ; デフォルトの Claude Opus ラインを **4.8** に、該当箇所の GPT デフォルトを **5.5** にアップグレード。さらに、Usage の可観測性、繁体字中国語ローカライズ、ドキュメント、プロキシ / フォーマット変換のロバスト性についても多くの改善と修正を行いました。
|
||||
|
||||
**リリース日**: 2026-05-29
|
||||
|
||||
**Stats**: 101 commits | 221 files changed | +27,063 insertions | -3,052 deletions
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **Codex Chat Completions ルーティング**: Codex プロバイダーを OpenAI 互換の Chat Completions 上流で提供できるようになりました。CC Switch は Codex の Responses リクエストを Chat Completions に変換し、JSON と SSE レスポンスを Responses 形態へ再構築し、reasoning / `<think>` / ツール呼び出し状態を保持し、エラーエンベロープを正規化し、Stream Check で Chat 形式プロバイダーを正しくプローブします
|
||||
- **Codex サードパーティプロバイダーの状態を統一しより安全に**: サードパーティ Codex プロバイダーは安定した `custom` model-provider バケットを共有するようになり、過去の JSONL セッションと `state_5.sqlite` スレッドの一回限りのマイグレーションに加え、live 読み取り / 切り替え時に OAuth ログイン状態、ユーザー選択のカタログモデル、ユーザー定義のプロバイダー id を保持する修正を実施
|
||||
- **受託 CLI ツール管理**: 「バージョン情報」ページが Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes のツール管理パネルに昇格し、インストール / 更新アクション、全体アップグレード、競合診断、インストール元にアンカーしたアップグレード、WSL の取り扱い、「インストール済みだが実行できない」状態の可視化を搭載
|
||||
- **プロバイダーエコシステムとモデルマトリクスのリフレッシュ**: APIKEY.FUN、APINebula、AtlasCloud、SudoCode、Xiaomi MiMo Token Plan、Claude Desktop 公式プリセットを追加; 各アプリのパートナーリンクとデフォルトモデル / 価格をリフレッシュ; デフォルトの Claude Opus を 4.8 に、該当箇所の GPT デフォルトを 5.5 にアップグレード
|
||||
- **Usage とドキュメントの磨き込み**: Usage ダッシュボードがログ書き込み時に即座に反応して更新、カスタム usage スクリプトのサマリーと subagent セッションログの計上を修正、繁体字中国語 UI ローカライズが着地、ドイツ語 README と拡充された Claude Desktop / Codex Chat / ツール管理マニュアルを追加
|
||||
- **プロキシと変換のハードニング**: Codex Chat の推論 / キャッシュ / usage のエッジケース、DeepSeek Anthropic ツール思考履歴、Claude 互換の空 `tool_calls` ストリーム、受託アカウントのテイクオーバー認証、MiMo 推論出力、Gemini Native ツール呼び出しの再生、いくつかのパニックしやすいプロキシパスを修正
|
||||
|
||||
---
|
||||
|
||||
## 追加機能
|
||||
|
||||
### Codex Chat Completions ルーティング
|
||||
|
||||
Codex プロバイダーを、OpenAI Chat Completions API しか話せない上流で提供できるようになりました。CC Switch のローカルプロキシは Codex の送出する Responses リクエストを Chat Completions に変換し、Chat レスポンス（JSON と SSE の両方）を Responses 形態へ再構築します。その際、`reasoning_content`、インライン `<think>` ブロック、ストリーミング推論サマリー、ツール呼び出し、`previous_response_id` の継続を保持します。有界の Codex Chat 履歴キャッシュが、ツール出力の前に対応するツール呼び出しを復元します。
|
||||
|
||||
> 💡 [@EldenPdx](https://github.com/EldenPdx) の PR [#2804](https://github.com/farion1231/cc-switch/pull/2804) に特別な感謝を: 本機能の Chat ↔ Responses フォーマット変換の実装は、彼の PR の実装を参考にしています。
|
||||
|
||||
### Chat ルーティング対応の 22 個の Codex サードパーティプロバイダープリセット
|
||||
|
||||
主要な中国 / アジア系プロバイダー向けに、明示的なモデルカタログ付きで Chat Completions ルーティングを有効化しました —— DeepSeek、Zhipu GLM（+ 英語版）、Kimi、MiniMax（+ 英語版）、StepFun（+ 英語版）、Baidu Qianfan Coding Plan、Bailian、ModelScope、Longcat、BaiLing、Xiaomi MiMo（+ Token Plan）、Volcengine Agentplan、BytePlus、DouBao Seed、SiliconFlow（+ 英語版）、Novita AI、Nvidia。各プリセットは自身のコンテキストウィンドウを宣言するため、UI がモデルマッピング行のサイズを決定できます。
|
||||
|
||||
### Codex モデルマッピングテーブル
|
||||
|
||||
Codex プロバイダーフォームがモデルカタログ（行ごとに モデル + 表示名 + コンテキストウィンドウ）を公開するようになりました。これは上流モデルリストの唯一の信頼できる情報源であり、`~/.codex/cc-switch-model-catalog.json` に投影されます。
|
||||
|
||||
### Stream Check の Codex Chat プロバイダー対応
|
||||
|
||||
Stream Check は Chat 形式の Codex プロバイダーに対して、`/v1/responses` ではなく Chat 形態のボディで `/chat/completions` をプローブするようになりました。また URL のフォールバック順序を本番の `CodexAdapter` と揃え（origin のみの base URL はまず `/v1/<endpoint>` を叩く）、裸のパスでの 404 以外のエラーが、正常に動作しているプロバイダーをダウンと誤判定しなくなりました。
|
||||
|
||||
### Codex Chat 思考能力（Reasoning）の自動判別
|
||||
|
||||
Codex プロバイダーが Chat Completions ルーティング経由で提供される場合、CC Switch は上流の推論インターフェースを名前、base URL、モデル名から**自動判別**し、正しい思考パラメータ（`thinking:{type}`、`enable_thinking`、`reasoning_split`、トップレベルの `reasoning_effort`、または OpenRouter のネイティブ `reasoning:{effort}` オブジェクト）を手動設定なしで注入します。アグリゲーター / ホスティングプラットフォーム（OpenRouter、SiliconFlow）は**プラットフォーム優先**でマッチします。同じモデルでもプラットフォームによって異なる推論コントロールを公開する場合があるためです。思考の オン / オフ スイッチしか公開しないプロバイダー（Kimi、GLM、Qwen、MiniMax、MiMo、SiliconFlow）は、未対応のフィールドを転送する代わりに effort の*レベル*を破棄します —— そのため Codex の推論 effort を変更してもこれらには効果がありません —— 一方、本物の effort 階層を持つプロバイダー（DeepSeek、OpenRouter、および StepFun の `step-3.5-flash-2603` のみ）はレベルを透過させます。OpenRouter は特にネイティブ `reasoning:{effort}` オブジェクトを使用し、`max` を `xhigh` にクランプし（その enum に `max` はない）、推論をオフにできるよう明示的に `effort:"none"` を転送します。
|
||||
|
||||
### Codex Goal Mode とリモートコンパクション制御
|
||||
|
||||
Codex の設定編集で、サードパーティプロバイダー向けに Goal Mode トグルとリモートコンパクション（Remote Compaction）トグルを公開するようになりました; 新規 Codex テンプレートはデフォルトで `disable_response_storage = true` としつつ、明示的な goal サポートも許可します。
|
||||
|
||||
### Xiaomi MiMo Token Plan プリセット
|
||||
|
||||
公式ドキュメントに準拠した仕様で Xiaomi MiMo Token Plan プリセットを追加しました (#2803, 感謝 @BlueOcean223)。
|
||||
|
||||
### Claude Desktop 公式プリセット
|
||||
|
||||
ネイティブの Claude Desktop ログインを復元する Claude Desktop 公式プリセットと、ローカライズされた Claude Desktop ユーザーガイド（en / zh / ja）を追加しました。
|
||||
|
||||
### 受託 CLI ツールライフサイクル
|
||||
|
||||
受託 CLI ツール向けに、サイレントインストール / 更新コマンド、最新バージョンチェック、ツール単位およびバッチアクション、全体アップグレード、そして PATH、Homebrew、npm、pnpm、bun、volta、fnm、nvm、scoop、WinGet、Windows ネイティブパス、WSL をまたいだ複数インストールの診断を追加しました。
|
||||
|
||||
### インストール元を考慮したツール診断
|
||||
|
||||
設定 / バージョン情報の画面で、競合するツールインストールを診断し、各パスの具体的なインストール元とバージョンを表示し、実際のインストール元にアンカーされたバックエンド計画のアップグレードコマンドを生成できるようになりました。
|
||||
|
||||
### リアルタイム Usage 更新
|
||||
|
||||
バックエンドは、プロキシログ、セッションログ同期、ロールアップが usage データを書き込んだ際に `usage-log-recorded` を発行するようになりました; Usage ダッシュボードはそのイベントを購読し、次のポーリング間隔を待たずに即座にクエリを無効化します (#3027, 感謝 @in30mn1a)。
|
||||
|
||||
### 繁体字中国語ローカライズ
|
||||
|
||||
`zh-TW` の UI ローカライズと設定の言語オプションを追加しました (#3093, 感謝 @LaiYueTing)。
|
||||
|
||||
### ドイツ語 README
|
||||
|
||||
`README_DE.md` を追加し、既存の README 言語スイッチャーからリンクしました (#2994, 感謝 @flitzrrr)。
|
||||
|
||||
### 新しいパートナープリセット
|
||||
|
||||
対応する各アプリ面に APIKEY.FUN、APINebula、AtlasCloud、SudoCode のパートナープリセットを、パートナー文面、アイコン、README エントリとともに追加しました。
|
||||
|
||||
---
|
||||
|
||||
## 変更
|
||||
|
||||
### Codex サードパーティプロバイダーを "custom" 履歴バケットに統一
|
||||
|
||||
Codex は復元履歴を `model_provider` でフィルタリングするため、プロバイダー固有の id 間を切り替えると過去のセッションが消えたように見えていました。すべてのサードパーティプロバイダーは単一の安定した `custom` バケットに正規化されるようになり（`openai` / `ollama` のような予約済みの組み込み id は保持）、過去の JSONL セッションと `state_5.sqlite` のスレッドテーブルを書き換え、オリジナルを `~/.cc-switch/backups/codex-history-provider-migration-v1/` 配下にバックアップする一回限りのデバイスマイグレーションを伴います。
|
||||
|
||||
### Codex プロバイダーフォームの簡素化
|
||||
|
||||
Codex フォームから API Format セレクターを削除しました（`wire_api` は常に `responses` であり、セレクターはプロトコルを変更できるかのように誤解を招くため）; モデルマッピングテーブルが唯一の信頼できる情報源となり、隠れたデフォルトエントリはなくなりました。`model_catalog_json` は起動時に読み込まれるため、カタログ変更後は Codex の再起動が必要である旨をフォームに明記しています。残るのは「ローカルルーティングが必要」トグルのみです。
|
||||
|
||||
### Codex ローカルルーティングトグルのヒント書き直し
|
||||
|
||||
OFF / ON のヒントを、シナリオの説明ではなくアクションのガイダンス（いつ有効化すべきか）として再構成し、zh / en / ja で同期しました。
|
||||
|
||||
### Codex Live 設定の保持
|
||||
|
||||
Codex の live 設定読み取りがユーザーの `model_provider` フィールドを強制的に書き換えなくなり、プロバイダースコープの `experimental_bearer_token` 処理がサードパーティプロバイダー間の切り替え時に OAuth ログイン状態を保持するようになりました。
|
||||
|
||||
### ツールのインストール / アップグレード戦略
|
||||
|
||||
受託ツールのインストールは、可能な場合は公式のネイティブインストーラーを優先し、適切な場合はパッケージマネージャーにフォールバックし、互換性のあるツールではまず self-update を実行し、アップグレードを検出されたインストール元にアンカーし、作業中は重複するバッチアクションをロックするようになりました。
|
||||
|
||||
### 「バージョン情報」ページがツール管理に
|
||||
|
||||
「バージョン情報」設定ページが、インストール済み / 最新バージョン、インストールおよび更新アクション、競合診断、WSL シェル設定、壊れている / 実行できないツールのより明確なステータスを表示するようになりました。
|
||||
|
||||
### デフォルトモデルと価格のリフレッシュ
|
||||
|
||||
デフォルトの Claude Opus モデルを 4.8 にアップグレードし、該当箇所の GPT ベースのプリセットとテンプレートを GPT-5.5 に移行し、価格シードをリフレッシュし、Claude Desktop のモデルマッピングを Claude Code の三ロール階層に揃え、OpenCode の Go プリセットを古いモデルサフィックスを落とすようリネームしました。
|
||||
|
||||
### パートナーリンクのリフレッシュ
|
||||
|
||||
ShengSuanYun の紹介リンク、Atlas Cloud の UTM リンク、各 README ロケールおよびプロバイダーメタデータのパートナー文面を更新しました。
|
||||
|
||||
### Homebrew 公式 Cask インストール
|
||||
|
||||
CC Switch が公式 Homebrew リポジトリに収録されたため、インストールを `brew install --cask cc-switch` に簡素化しました; 個人 tap の要件はすべての README から削除しました。
|
||||
|
||||
### 共有フロントエンドユーティリティ
|
||||
|
||||
JSON stringify / parse によるディープコピーのパターンを共有の `deepClone` ヘルパーに置き換え、共有の `useTauriEvent` フックを抽出しました (#3140, 感謝 @ChongBiaoZhang)。
|
||||
|
||||
---
|
||||
|
||||
## 修正
|
||||
|
||||
### Codex Chat エラーレスポンスを Responses エンベロープに変換
|
||||
|
||||
Codex Chat → Responses ブリッジは以前、上流のエラーボディをそのまま透過させていたため、Codex クライアントが MiniMax の `base_resp`、生の OpenAI Chat エラー、プレーンテキスト / HTML のエラーページを認識できませんでした。エラーは標準の `{error: {message, type, code, param}}` エンベロープに整形され、元の HTTP ステータスが保持されるようになりました; 非 JSON ボディはラップされ、UTF-8 文字境界で 1KB に切り詰められます。また、書き換え後の JSON ボディに重複する `Content-Type` ヘッダーを出力していた既存の append-vs-insert バグも修正しました。
|
||||
|
||||
### Codex のストリーム中間の system メッセージを折りたたみ
|
||||
|
||||
MiniMax の OpenAI 互換エンドポイントは、先頭以外の `system` メッセージを厳格に拒否します（エラー 2013）。すべての `system` 断片は単一の先頭メッセージに折りたたまれるようになりました（元の順序で結合）。寛容なバックエンドに対しても損失なく行われます。
|
||||
|
||||
### 再起動後に Codex モデルカタログが消える問題
|
||||
|
||||
アクティブな Codex プロバイダーを編集すると `modelCatalog` を省略した live 読み取りがトリガーされ、その後の保存がユーザー設定のモデルマッピングを無言で破壊していました。live 読み取りはディスク上のカタログ投影を逆解析し、保存パスが書き込むのと同じ形態をラウンドトリップするようになりました。
|
||||
|
||||
### Codex モデルカタログの無限レンダリングループ
|
||||
|
||||
カタログテーブルとその親 state の間の双方向同期サイクルを断ち切りました。これはエントリの追加や編集時に深刻な UI のジッターを引き起こしていました。
|
||||
|
||||
### Codex Chat がユーザー選択のカタログモデルを保持
|
||||
|
||||
クライアントがカタログから選択したモデル（例: `/model` 経由）が、`config.toml` のデフォルトモデルによって上書きされなくなりました。
|
||||
|
||||
### Codex Chat の推論とキャッシュの安定性
|
||||
|
||||
Codex が `previous_response_id` を省略または書き換える際の一意な call-id フォールバックを復元し、`previous_response_id` からキャッシュの同一性を導出するのをやめ、ツール変換でパース可能な JSON 文字列ペイロードを正規化して安定したプレフィックスキャッシュ再利用を実現しました。
|
||||
|
||||
### Codex Chat のストリーミング usage を復旧
|
||||
|
||||
Responses → Chat 変換が、リクエストがストリーミングの場合に `stream_options.include_usage` を注入する（クライアント提供の `stream_options` にマージ）ようになり、Kimi や MiniMax のような OpenAI 互換上流が末尾の usage チャンクを再び発行するようになりました。以前は、これらのストリーミングのトークン / コスト / キャッシュ統計が Codex Chat パスでゼロとして記録されていました。
|
||||
|
||||
### Codex Chat ツール呼び出しの推論バックフィル
|
||||
|
||||
Kimi/Moonshot や DeepSeek のような思考モデルは、空でない `reasoning_content` を伴わない `tool_calls` を持つ assistant メッセージを拒否します。ターンをまたいだ履歴復元が失敗した場合（プロキシ再起動、曖昧な `call_id`、または上流の推論がないターン）、最終パスでプレースホルダーの `reasoning_content` をバックフィルするようになりました —— 本物の末尾推論が先に付加されます —— そのためリクエストが `reasoning_content is missing in assistant tool call message` で失敗しなくなりました。
|
||||
|
||||
### 受託アカウントの Claude テイクオーバー認証
|
||||
|
||||
受託アカウントのプロバイダー（GitHub Copilot / Codex OAuth）は、Claude Live 設定をテイクオーバーする際にトークン環境変数キーを破棄し、`ANTHROPIC_API_KEY` プレースホルダーのみを書き込むようになりました。さらに、`PROXY_MANAGED` プレースホルダーを上流に送信するのを拒否するアウトバウンドガードを備えます。
|
||||
|
||||
### テイクオーバー中の Claude Desktop プロファイル同期
|
||||
|
||||
プロキシテイクオーバー中に Claude Desktop プロファイルデータが同期されるようになり、モデルルートが Claude Code の三ロール階層に揃い、Cowork egress プロファイルが修正されました (#3157, #3172, 感謝 @MelorTang, @JGSphaela)。
|
||||
|
||||
### 受託アカウントのテイクオーバーモデルフィールド
|
||||
|
||||
ローカルルーティングは、受託アカウントにおいて、古いモデル値を持ち回るのではなく、ターゲットプロバイダーからテイクオーバーモデルフィールドを取得するようになりました。
|
||||
|
||||
### DeepSeek Anthropic ツール思考履歴
|
||||
|
||||
DeepSeek Anthropic 互換のツール思考履歴を正規化し、後続のターンが不正なメッセージなしで推論 / ツール呼び出しコンテキストを再生できるようにしました (#3203, 感謝 @Q3yp)。
|
||||
|
||||
### Claude 互換のストリーム内の空ツール呼び出し
|
||||
|
||||
空の `tool_calls` 配列がブロック状態をリセットしてストリーミングレスポンスを壊す、Claude 互換のストリーミングエッジケースを修正しました (#2915, 感謝 @zhizhuowq)。
|
||||
|
||||
### Claude Code プロキシ向けの MiMo 推論
|
||||
|
||||
Claude Code プロキシパスで MiMo の `reasoning_content` サポートを追加しました (#2990, 感謝 @zhangyapu1)。
|
||||
|
||||
### Gemini Native ツール呼び出しのロバスト性
|
||||
|
||||
長いマルチターンセッションにおける合成ツール呼び出し ID の `functionResponse.name` 解決（422）と `thought_signature` 再生（400）を修正しました (#2814, 感謝 @Tiancrimson)。
|
||||
|
||||
### セッションログの subagent トークン計上
|
||||
|
||||
`collect_jsonl_files()` がこれまで見落とされていた subagent の JSONL ログをスキャンするようになり、subagent のトークン使用量がセッションコストに計上されるようになりました（セッションログモードのみ）(#2821, 感謝 @LaoYueHanNi)。
|
||||
|
||||
### Usage ダッシュボード / 同期の安定性
|
||||
|
||||
非 ASCII モデル名による Codex usage 同期パニック、カスタム usage スクリプトのサマリー、usage ロールアップ後のリアルタイム更新の欠落を修正しました (#3027, #3129, 感謝 @in30mn1a, @hanhan3344)。
|
||||
|
||||
### ZhiPu Coding-Plan のクォータ階層の並び順
|
||||
|
||||
5 時間バケットの使用率が 0% の場合、ZhiPu の API は `nextResetTime` を省略します; 古い `i64::MAX` センチネルはこれらのエントリを最後にソートしていたため、週次バケットが五時間スロットを誤って占有していました。階層は、`nextResetTime` の欠落が五時間バケットにマップされるようにソートされるようになり、ZhiPu の coding plan でトレイと usage クォータの表示が正しく保たれます。
|
||||
|
||||
### スキルを key でインストール
|
||||
|
||||
skills.sh の検索結果からインストールする際に、ディレクトリ名ではなく一意の key を使用するようになり、ディレクトリ名を共有するスキルでも正しいものがインストールされます (#2784, 感謝 @zhaomoran); スキル同期のコピーフォールバックも修正しました (#2791, 感謝 @rogerdigital)。
|
||||
|
||||
### Usage 価格入力の精度
|
||||
|
||||
価格入力のステップを 0.0001 に下げ、DeepSeek のキャッシュ読み取りのような 1 セント未満のコストも入力できるようにしました (#2793, #2503 をクローズ, 感謝 @rogerdigital)。
|
||||
|
||||
### Ghostty のクリーンウィンドウ起動
|
||||
|
||||
Ghostty は既存タブを複製する代わりに単一のクリーンウィンドウを開くようになり、他のターミナルは `open -na` 経由で新しいウィンドウを開きます (#2801, #2798 をクローズ, 感謝 @luw2007)。
|
||||
|
||||
### ツールバージョンと更新の信頼性
|
||||
|
||||
バージョンプローブが実行できないインストールを覆い隠さなくなり、プレリリースツールがバージョンチェックで正しく扱われ、バッチ更新がツール単位で実行され、インストール / 更新ボタンがプリフライト中ロックされ続け、アンカー型アップグレードブランチが絶対パスを強制し、WSL のインストーラーパスが必要に応じてネイティブ Unix インストーラーを使用するようになりました。
|
||||
|
||||
### Codex の mise 検出
|
||||
|
||||
Codex の mise 環境検出を修正しました (#2822, 感謝 @iambinlin)。
|
||||
|
||||
### Codex のアーカイブ済みセッション
|
||||
|
||||
Codex のアーカイブ済みセッションがセッション検出に含まれるようになりました (#2861, 感謝 @nanmen2)。
|
||||
|
||||
### Codex Chat の空ツール引数
|
||||
|
||||
空のツール呼び出し引数ペイロードが Codex Chat 変換時に `{}` に強制変換され、上流とクライアントが有効な JSON を受け取るようになりました。
|
||||
|
||||
### Claude プロバイダーの deeplink インポート
|
||||
|
||||
deeplink 経由で Claude プロバイダーをインポートする際に、カスタム環境フィールドが保持されるようになりました (#2928, 感謝 @doutuifei)。
|
||||
|
||||
### OMO 推奨モデル
|
||||
|
||||
OMO の推奨モデルを上流のデフォルトと同期し、「推奨を入力」のフィードバックを改善しました。
|
||||
|
||||
### ShengSuanYun のモデル ID にルーティング用プレフィックスを付与
|
||||
|
||||
ShengSuanYun（胜算云）プリセットが、上流ゲートウェイが要求するベンダープレフィックス —— `anthropic/…`、`google/…`、`openai/…`（例: `anthropic/claude-sonnet-4.6`、`google/gemini-3.1-pro-preview`）—— を、Claude Code、Claude Desktop、Codex、Gemini、OpenCode、OpenClaw の各プリセットにわたって持つようになりました。Claude Code のルーティング環境変数（`ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_{HAIKU,SONNET,OPUS}_MODEL`）も含まれるため、ルーティングに失敗するのではなく有効な上流モデルに解決されます。
|
||||
|
||||
### ClaudeAPI モデルテストの再有効化
|
||||
|
||||
ClaudeAPI プリセット（Claude Code と Claude Desktop）を `third_party` から `aggregator` に再分類し、サードパーティ Claude ゲートによってモデルテストボタンが無効化されないようにしました; パートナースターは `isPartner` によって駆動され、category には依存しないため影響を受けません。
|
||||
|
||||
### バージョン情報のバージョンチェック
|
||||
|
||||
バージョンチェックがプレリリースのツールバージョンを、更新状態を誤分類することなく扱えるようになりました。
|
||||
|
||||
### App スイッチャーのテキスト切れ
|
||||
|
||||
App スイッチャーのテキストを切り取っていた固定幅の制約を削除しました (#3161, 感謝 @loocor)。
|
||||
|
||||
### useEffect の競合状態
|
||||
|
||||
App.tsx の effects に active フラグのパターンを追加してアンマウント時のリスナーリークを防止し、localStorage に `undefined` の言語を保存しないようガードしました (#2827, 感謝 @Zylo206)。
|
||||
|
||||
---
|
||||
|
||||
## 削除
|
||||
|
||||
### LionCC スポンサーとプリセット
|
||||
|
||||
LionCC スポンサーエントリと LionCCAPI プリセットを、各 README、プロバイダー設定、ロケールにわたって削除しました（アイコンアセットは保持）。
|
||||
|
||||
### AICoding パートナーエントリ
|
||||
|
||||
AICoding パートナーを README スポンサー一覧、プロバイダープリセット、i18n メタデータから削除しました。
|
||||
|
||||
### Kimi For Coding の Codex プリセット
|
||||
|
||||
Kimi For Coding プリセットを Codex プリセットカタログから削除しました。
|
||||
|
||||
### CLI アンインストールコマンドのヒント
|
||||
|
||||
ツール管理 UI から生成された CLI アンインストールコマンドのヒントを削除しつつ、競合診断は引き続き表示します。
|
||||
|
||||
---
|
||||
|
||||
## ドキュメント
|
||||
|
||||
### Codex Chat プロバイダーサポート
|
||||
|
||||
Chat Completions ルーティング、プロバイダーサポート、推論の自動判別、ローカルルーティングのガイダンスを changelog とユーザーマニュアルにドキュメント化しました。
|
||||
|
||||
### 設定マニュアルのリフレッシュ
|
||||
|
||||
新しい受託ツールライフサイクルと Hermes インストーラーの挙動について、設定ドキュメントを更新しました。
|
||||
|
||||
### Claude Desktop ガイド
|
||||
|
||||
プロバイダー設定、インポート、モデルマッピング、ローカルルーティングのコンテキストについて、ローカライズされた Claude Desktop ガイドページとスクリーンショットを追加しました。
|
||||
|
||||
### インストールドキュメント
|
||||
|
||||
公式 Homebrew cask を推奨するようインストールドキュメントと README を更新し、v3.15.0 リリースノートの偽サイト警告の文言を各ロケールでリフレッシュしました。
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ アップグレード時の注意
|
||||
|
||||
### Codex 履歴の一回限りのマイグレーション
|
||||
|
||||
アップグレード後の初回起動で、Codex 履歴の一回限りのマイグレーションが実行されます: サードパーティプロバイダーが `custom` バケットに正規化され、過去の JSONL セッションと `state_5.sqlite` スレッドテーブルが書き換えられます。オリジナルは `~/.cc-switch/backups/codex-history-provider-migration-v1/` 配下にバックアップされます。このステップは「プロバイダー切り替え後に過去のセッションが消える」問題を修正するもので、マイグレーション後は履歴が正しく復元されます。
|
||||
|
||||
### Codex のカタログ変更には再起動が必要
|
||||
|
||||
Codex は `model_catalog_json` を起動時に読み込むため、CC Switch でモデルマッピングテーブルを編集した後は、新しいカタログを反映させるために **Codex を再起動**する必要があります。
|
||||
|
||||
### Chat ルーティングのプロバイダーでは推論 effort が効かない場合がある
|
||||
|
||||
思考の オン / オフ スイッチしか公開しないプロバイダー（Kimi、GLM、Qwen、MiniMax、MiMo、SiliconFlow）では、Codex で推論 effort（`model_reasoning_effort`: low / medium / high）を変更しても**効果がありません** —— CC Switch は未対応の effort フィールドをこれらに転送しません。本物の effort 階層を持つプロバイダー（DeepSeek、OpenRouter、および StepFun の `step-3.5-flash-2603` のみ）でのみ、レベルが実際に反映されます。
|
||||
|
||||
### デフォルトモデルが Opus 4.8 / GPT-5.5 にアップグレード
|
||||
|
||||
デフォルトの Claude Opus モデルラインが 4.8 に、該当箇所の GPT デフォルトが 5.5 にアップグレードされました。固定した古いデフォルトモデルに依存している場合は、アップグレード後に該当プリセット / テンプレートのモデルフィールドを確認してください。
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ リスク通知
|
||||
|
||||
本リリースは、リバースプロキシ系機能について v3.12.3 / v3.13.0 / v3.15.0 で提起されたリスク通知を継承します。
|
||||
|
||||
**GitHub Copilot リバースプロキシ**: Copilot のリバースプロキシパスを使用すると、GitHub / Microsoft の利用規約に違反する可能性があります。詳細は [v3.12.3 リリースノート](v3.12.3-ja.md#️-リスクに関する注意事項) を参照してください。
|
||||
|
||||
**Codex OAuth リバースプロキシ**: ChatGPT サブスクリプションを使用した Codex OAuth リバースプロキシは、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 リリースノート](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
|
||||
|
||||
**Codex サードパーティプロバイダー Chat ルーティング**: CC Switch のローカルプロキシ経由で Codex のリクエストを変換し、サードパーティプロバイダーに転送する際、各プロバイダーの課金、コンプライアンス、データ保持に関する制約はそれぞれ異なります。利用前にターゲットプロバイダーの利用規約をお読みください。
|
||||
|
||||
**Claude Desktop サードパーティプロバイダーのプロキシ切り替え**: CC Switch 内蔵プロキシゲートウェイ経由で Claude Desktop のリクエストをサードパーティプロバイダーに転送する際、サードパーティプロバイダーの課金、コンプライアンス、データ保持に関する制約はそれぞれ異なります。利用前にターゲットプロバイダーの利用規約をお読みください。
|
||||
|
||||
ユーザーが上記機能を有効化することで、**すべてのリスクを自己責任で**受諾したものとみなされます。CC Switch は、これらの機能の使用に起因するアカウントの制限、警告、サービス停止について一切の責任を負いません。
|
||||
|
||||
---
|
||||
|
||||
## ダウンロード・インストール
|
||||
|
||||
[Releases](https://github.com/farion1231/cc-switch/releases/latest) から対応バージョンをダウンロードしてください。
|
||||
|
||||
### システム要件
|
||||
|
||||
| OS | 最小バージョン | アーキテクチャ |
|
||||
| ------- | ------------------------ | ----------------------------------- |
|
||||
| Windows | Windows 10 以降 | x64 |
|
||||
| macOS | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 下表参照 | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| ファイル | 説明 |
|
||||
| ---------------------------------------- | ------------------------------------------- |
|
||||
| `CC-Switch-v3.16.0-Windows.msi` | **推奨** - MSI インストーラー、自動更新対応 |
|
||||
| `CC-Switch-v3.16.0-Windows-Portable.zip` | ポータブル版、解凍して実行、レジストリ不要 |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| -------------------------------- | ------------------------------------------------------ |
|
||||
| `CC-Switch-v3.16.0-macOS.dmg` | **推奨** - DMG インストーラー、Applications にドラッグ |
|
||||
| `CC-Switch-v3.16.0-macOS.zip` | 解凍して Applications にドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.16.0-macOS.tar.gz` | Homebrew インストールと自動更新用 |
|
||||
|
||||
> macOS 版は Apple のコード署名および公証済みで、直接インストールして使用できます。
|
||||
|
||||
### Homebrew（macOS）
|
||||
|
||||
> 🎉 CC Switch は Homebrew 公式 cask リポジトリに収録されました。カスタム tap の追加は不要です！
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
> Linux 向けの成果物は **x86_64** と **ARM64**（`aarch64`）の両方が提供されます。ファイル名にアーキテクチャ識別子が含まれているため、`uname -m` の出力に応じて選択してください：
|
||||
>
|
||||
> - `CC-Switch-v3.16.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
> - `CC-Switch-v3.16.0-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| ディストリビューション | 推奨形式 | インストール方法 |
|
||||
| --------------------------------------- | ----------- | -------------------------------------------------------------------------- |
|
||||
| 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` |
|
||||
@@ -0,0 +1,434 @@
|
||||
# CC Switch v3.16.0
|
||||
|
||||
> 为 Codex 增加 Chat Completions -> Response 格式转换（你可以在 Codex 里使用 DeepSeek, Kimi, GLM 了！）、Codex 供应商身份与历史统一、应用管理面板全方位增强、合作伙伴预设扩张、默认模型 / 定价矩阵升级到 GPT-5.5 与 Claude Opus 4.8、代理与格式转换鲁棒性强化
|
||||
|
||||
**[English →](v3.16.0-en.md) | [日本語版 →](v3.16.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 使用攻略
|
||||
|
||||
本版本最主打的两块能力是 **Codex 第三方供应商 Chat Completions 路由**与**应用内受管 CLI 工具管理**。如果你想让 DeepSeek、Kimi、MiniMax 这类只支持 OpenAI Chat 协议的供应商在 Codex 里直接可用，或者想在应用内一站式安装 / 升级 CLI 工具，建议先读这几篇：
|
||||
|
||||
- **[在 Codex 中使用 DeepSeek：本地路由实战攻略](../guides/codex-deepseek-routing-guide-zh.md)** —— 以 DeepSeek 内置预设为例，演示从添加 Codex 供应商、开启本地路由到验证请求转发的完整路径。
|
||||
- **[添加 Codex 供应商：Chat Completions 路由与模型映射](../user-manual/zh/2-providers/2.1-add.md)** —— 覆盖「需要本地路由映射」开关、模型映射表、思考能力（reasoning）自适应识别的完整流程。
|
||||
- **[设置 → 关于：受管 CLI 工具管理](../user-manual/zh/1-getting-started/1.5-settings.md)** —— 覆盖版本检测、单独升级 / 全部升级、冲突诊断、按安装来源锚定的升级命令。
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## 唯一官方渠道声明（请务必阅读）
|
||||
>
|
||||
> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。最近发现多个山寨网站冒用 CC Switch 名义诱导用户付费、收集账号信息，部分已造成实际经济损失。请仅通过下列官方渠道获取本软件：
|
||||
>
|
||||
> | 类别 | 唯一官方 |
|
||||
> | -------- | ------------------------------------------------------------------------------ |
|
||||
> | 官网 | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | 源码 | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | 下载 | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | 作者 | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈，让我们能尽快下线相关山寨站点。
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.16.0 自 v3.15.0 以来的开发核心，是把**第三方 Codex 供应商通过 Chat Completions 路由升级为一等公民**。Codex 原生只认 OpenAI Responses API 与 GPT 系列模型，本版本让 CC Switch 的本地代理把 Codex 发出的 Responses 请求转换为上游的 Chat Completions，再把 JSON 与 SSE 流式响应重建回 Responses 形态，沿途保留 `reasoning_content` / 内联 `<think>` 块 / 流式推理摘要 / 工具调用 / `previous_response_id` 续接状态，并把错误信封规范化、在 Stream Check 中正确探测 Chat 格式供应商。配套上货 22 个带显式模型目录的 Chat 路由预设（DeepSeek、智谱 GLM、Kimi、MiniMax、StepFun、百度千帆、百炼、ModelScope、Longcat、百灵、小米 MiMo、火山 Agentplan、BytePlus、豆包 Seed、SiliconFlow、Novita AI、Nvidia 等）。
|
||||
|
||||
Codex 第三方供应商的**身份与历史**这一版被统一并加固：所有第三方供应商现在归并到稳定的 `custom` model-provider 桶，并提供一次性设备迁移来改写历史 JSONL 会话与 `state_5.sqlite` 线程表（原文件备份在 `~/.cc-switch/backups/` 下），避免因供应商 id 变化导致过往会话"凭空消失"；同时修复了 live 读取 / 切换过程中 OAuth 登录态、用户选中的目录模型、用户自定义 provider id 被覆盖的问题。
|
||||
|
||||
本版本还新增了**应用内受管 CLI 工具生命周期**：设置页的「关于」Tab 升级为 Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes 的工具管理面板，支持静默安装 / 更新、全部升级、冲突诊断、按安装来源锚定的升级，以及对 WSL 的处理和"已安装但跑不起来"状态的可见化。
|
||||
|
||||
供应商生态与模型矩阵同步刷新：新增 APIKEY.FUN、APINebula、AtlasCloud、SudoCode、小米 MiMo Token Plan、Claude Desktop 官方预设；跨应用刷新合作伙伴链接与默认模型 / 定价；默认 Claude Opus 模型线升级到 **4.8**，适用处的 GPT 默认升级到 **5.5**。此外还在用量可观测性、繁体中文本地化、文档、以及代理 / 格式转换的鲁棒性上做了大量打磨与修复。
|
||||
|
||||
**发布日期**：2026-05-29
|
||||
|
||||
**更新规模**：101 commits | 221 files changed | +27,063 / -3,052 lines
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- **Codex Chat Completions 路由**：Codex 供应商现在可以由仅支持 OpenAI Chat Completions 的上游提供服务。CC Switch 把 Codex 的 Responses 请求转成 Chat Completions、把 JSON 与 SSE 响应重建回 Responses 形态、保留 reasoning / `<think>` / 工具调用状态、规范化错误信封，并在 Stream Check 中正确探测 Chat 格式供应商
|
||||
- **Codex 第三方供应商身份与历史统一并更安全**：第三方 Codex 供应商现在共用稳定的 `custom` model-provider 桶，配一次性迁移改写历史 JSONL 会话与 `state_5.sqlite` 线程，并修复 live 读取 / 切换时 OAuth 登录态、用户选中的目录模型、用户自定义 provider id 的保留
|
||||
- **受管 CLI 工具管理**：「关于」页升级为 Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes 的工具管理面板，含安装 / 更新动作、全部升级、冲突诊断、按来源锚定的升级、WSL 处理，以及"已安装但跑不起来"状态可见化
|
||||
- **供应商生态与模型矩阵刷新**：新增 APIKEY.FUN、APINebula、AtlasCloud、SudoCode、小米 MiMo Token Plan、Claude Desktop 官方预设；跨应用刷新合作伙伴链接与默认模型 / 定价；默认 Claude Opus 升级到 4.8、适用处 GPT 默认升级到 5.5
|
||||
- **用量与文档打磨**：用量看板在日志写入时即时响应更新，修复自定义用量脚本摘要与 subagent 会话日志计费，繁体中文 UI 本地化落地，新增德文 README 与扩充后的 Claude Desktop / Codex Chat / 工具管理手册
|
||||
- **代理与转换硬化**：修复 Codex Chat 推理 / 缓存 / usage 边角情况、DeepSeek Anthropic 工具思考历史、Claude 兼容的空 `tool_calls` 流、受管账号接管鉴权、MiMo 推理输出、Gemini Native 工具调用重放，以及多条易 panic 的代理路径
|
||||
|
||||
---
|
||||
|
||||
## 新功能
|
||||
|
||||
### Codex Chat Completions 路由
|
||||
|
||||
Codex 供应商现在可以由只会说 OpenAI Chat Completions API 的上游提供服务。CC Switch 的本地代理把 Codex 发出的 Responses 请求转换为 Chat Completions，并把 Chat 响应（JSON 与 SSE 两种）重建回 Responses 形态，沿途保留 `reasoning_content`、内联 `<think>` 块、流式推理摘要、工具调用，以及 `previous_response_id` 续接。一个有界的 Codex Chat 历史缓存会在工具输出之前恢复对应的工具调用。
|
||||
|
||||
> 💡 特别感谢 [@EldenPdx](https://github.com/EldenPdx) 的 PR [#2804](https://github.com/farion1231/cc-switch/pull/2804)：本功能的 Chat ↔ Responses 格式转换实现参考了他在该 PR 中的实现。
|
||||
|
||||
### 22 个带 Chat 路由的 Codex 第三方供应商预设
|
||||
|
||||
为主流中国开源模型启用了 Chat Completions 路由并带显式模型目录——DeepSeek、智谱 GLM（+ 英文站）、Kimi、MiniMax（+ 英文站）、StepFun（+ 英文站）、百度千帆 Coding Plan、百炼（Bailian）、ModelScope、Longcat、百灵（BaiLing）、小米 MiMo（+ Token Plan）、火山 Agentplan、BytePlus、豆包 Seed、SiliconFlow（+ 英文站）、Novita AI、Nvidia。每个预设都声明了自己的上下文窗口，便于 UI 给模型映射行确定尺寸。
|
||||
|
||||
### Codex 模型映射表
|
||||
|
||||
Codex 供应商表单现在提供模型目录（每行：模型 + 显示名 + 上下文窗口），它是上游模型列表的唯一真相来源，并投影到 `~/.codex/cc-switch-model-catalog.json`。
|
||||
|
||||
### Stream Check 支持 Codex Chat 供应商
|
||||
|
||||
Stream Check 现在对 Chat 格式的 Codex 供应商改用 Chat 形态的请求体打 `/chat/completions`，而不是 `/v1/responses`；并把 URL 回退顺序与生产环境的 `CodexAdapter` 对齐（仅 origin 的 base URL 先打 `/v1/<endpoint>`），这样裸路径上的非 404 错误不会再把一个正常工作的供应商误判为不可用。
|
||||
|
||||
### Codex Chat 思考能力（Reasoning）自适应
|
||||
|
||||
当 Codex 供应商走 Chat Completions 路由时，CC Switch 现在会**自动识别**上游的推理接口——依据是供应商的名称、base URL 和模型名——并注入正确的思考参数（`thinking:{type}`、`enable_thinking`、`reasoning_split`、顶层 `reasoning_effort`，或 OpenRouter 的原生 `reasoning:{effort}` 对象），无需手动配置。聚合 / 托管平台（OpenRouter、SiliconFlow）按**平台优先**匹配，因为同一个模型在不同平台上可能暴露不同的推理控制。只暴露"思考开 / 关"开关的供应商（Kimi、GLM、Qwen、MiniMax、MiMo、SiliconFlow）会**丢弃 effort 等级**而不是透传一个不支持的字段——因此在 Codex 里调节这类供应商的思考等级不会有任何效果——而有真实 effort 档位的供应商（DeepSeek、OpenRouter，以及 StepFun 仅 `step-3.5-flash-2603`）则会把等级透传上去。OpenRouter 特别使用原生 `reasoning:{effort}` 对象，把 `max` 钳到 `xhigh`（它的枚举里没有 `max`），并显式转发 `effort:"none"` 以便关闭推理。
|
||||
|
||||
### Codex Goal Mode 与远程压缩控制
|
||||
|
||||
Codex 配置编辑现在为第三方供应商暴露一个 Goal Mode 开关和一个远程压缩（Remote Compaction）开关；新建的 Codex 模板默认 `disable_response_storage = true`，同时仍允许显式开启 goal 支持。
|
||||
|
||||
### 小米 MiMo Token Plan 预设
|
||||
|
||||
新增小米 MiMo Token Plan 预设，规格与官方文档对齐（#2803，感谢 @BlueOcean223）。
|
||||
|
||||
### Claude Desktop 官方预设
|
||||
|
||||
新增一个 Claude Desktop 官方预设，用于恢复原生 Claude Desktop 登录，并附带本地化的 Claude Desktop 使用指南（中 / 英 / 日）。
|
||||
|
||||
### 受管 CLI 工具生命周期
|
||||
|
||||
为受管 CLI 工具新增静默安装 / 更新命令、最新版本检查、单工具与批量动作、全部升级，以及跨 PATH、Homebrew、npm、pnpm、bun、volta、fnm、nvm、scoop、WinGet、Windows 原生路径和 WSL 的多安装诊断。
|
||||
|
||||
### 按来源感知的工具诊断
|
||||
|
||||
设置 / 关于 页面现在可以诊断冲突的工具安装、为每条路径展示具体的安装来源与版本，并生成由后端规划、锚定到真实安装来源的升级命令。
|
||||
|
||||
### 实时用量刷新
|
||||
|
||||
后端现在在代理日志、会话日志同步或汇总写入用量数据时发出 `usage-log-recorded` 事件；用量看板监听该事件并立即让查询失效，而不是等到下一个轮询周期（#3027，感谢 @in30mn1a）。
|
||||
|
||||
### 繁体中文本地化
|
||||
|
||||
新增 `zh-TW` UI 本地化与一个设置语言选项（#3093，感谢 @LaiYueTing）。
|
||||
|
||||
### 德文 README
|
||||
|
||||
新增 `README_DE.md` 并从现有 README 的语言切换器中链接到它（#2994，感谢 @flitzrrr）。
|
||||
|
||||
### 新合作伙伴预设
|
||||
|
||||
跨各受支持的应用面新增 APIKEY.FUN、APINebula、AtlasCloud、SudoCode 合作伙伴预设，含合作伙伴文案、图标与 README 条目。
|
||||
|
||||
---
|
||||
|
||||
## 变更
|
||||
|
||||
### Codex 第三方供应商统一进 "custom" 历史桶
|
||||
|
||||
Codex 按 `model_provider` 过滤可恢复历史，因此在供应商专属 id 之间切换会让过去的会话看起来"消失"了。所有第三方供应商现在归并到单一稳定的 `custom` 桶（保留 `openai` / `ollama` 这类预留的内置 id），并配一次性设备迁移：改写历史 JSONL 会话与 `state_5.sqlite` 线程表，原文件备份到 `~/.cc-switch/backups/codex-history-provider-migration-v1/`。
|
||||
|
||||
### Codex 供应商表单简化
|
||||
|
||||
从 Codex 表单中移除了 API Format 选择器（`wire_api` 永远是 `responses`，该选择器会误导用户以为能改协议）；模型映射表现在是唯一真相来源，不再有隐藏的默认条目；表单注明改动目录后需要重启 Codex，因为 `model_catalog_json` 在启动时加载。表单只保留「需要本地路由映射」开关。
|
||||
|
||||
### Codex 本地路由开关提示重写
|
||||
|
||||
把「关 / 开」两段提示从"场景描述"改写为"动作指引"（什么时候该开），并在中 / 英 / 日三语同步。
|
||||
|
||||
### Codex Live 配置保留
|
||||
|
||||
Codex live 配置读取不再强制改写用户的 `model_provider` 字段；供应商作用域的 `experimental_bearer_token` 处理现在会在第三方供应商之间切换时保留 OAuth 登录态。
|
||||
|
||||
### 工具安装 / 升级策略
|
||||
|
||||
受管工具安装现在优先使用官方原生安装器（在有的情况下），适当时回退到包管理器，对兼容工具先跑 self-update，把升级锚定到检测到的安装来源，并在工作进行中锁定重复的批量动作。
|
||||
|
||||
### 「关于」页升级为工具管理
|
||||
|
||||
设置的「关于」页现在呈现已安装 / 最新版本、安装与更新动作、冲突诊断、WSL shell 偏好，以及对损坏或跑不起来工具更清晰的状态。
|
||||
|
||||
### 默认模型与定价刷新
|
||||
|
||||
默认 Claude Opus 模型升级到 4.8，适用处把基于 GPT 的预设与模板迁到 GPT-5.5，刷新定价种子，把 Claude Desktop 模型映射与 Claude Code 的三角色档位对齐，并重命名 OpenCode 的 Go 预设以去掉一个陈旧的模型后缀。
|
||||
|
||||
### 合作伙伴链接刷新
|
||||
|
||||
更新了胜算云推荐链接、Atlas Cloud 的 UTM 链接，以及跨各 README 语言版本与供应商元数据中的合作伙伴文案。
|
||||
|
||||
### Homebrew 官方 Cask 安装
|
||||
|
||||
由于 CC Switch 已进入 Homebrew 官方仓库，安装简化为 `brew install --cask cc-switch`；各 README 中移除了对私有 tap 的要求。
|
||||
|
||||
### 共享前端工具
|
||||
|
||||
用一个共享的 `deepClone` helper 替换 JSON stringify / parse 的深拷贝写法，并抽取了一个共享的 `useTauriEvent` hook（#3140，感谢 @ChongBiaoZhang）。
|
||||
|
||||
---
|
||||
|
||||
## 修复
|
||||
|
||||
### Codex Chat 错误响应转换为 Responses 信封
|
||||
|
||||
Codex Chat → Responses 桥接此前会原样透传上游错误体，导致 Codex 客户端无法识别 MiniMax 的 `base_resp`、裸 OpenAI Chat 错误，或纯文本 / HTML 错误页。现在错误会被规整为标准的 `{error: {message, type, code, param}}` 信封并保留原始 HTTP 状态码；非 JSON 体会被包裹并在 UTF-8 字符边界截断到 1KB。同时修复了一个既存的 append-vs-insert bug，它会在重写后的 JSON 体上产生重复的 `Content-Type` 头。
|
||||
|
||||
### Codex 流中段 system 消息折叠
|
||||
|
||||
MiniMax 的 OpenAI 兼容端点会严格拒绝任何非首位的 `system` 消息（错误 2013）。现在所有 `system` 片段会被折叠为单条首位消息（按原顺序拼接），对宽松后端也是无损的。
|
||||
|
||||
### Codex 模型目录重启后被清空
|
||||
|
||||
编辑当前激活的 Codex 供应商会触发一次省略了 `modelCatalog` 的 live 读取，于是随后的保存会静默销毁用户配置的模型映射。Live 读取现在会反向解析磁盘上的目录投影，往返出与保存路径写入的相同形状。
|
||||
|
||||
### Codex 模型目录无限渲染循环
|
||||
|
||||
打断了目录表格与其父状态之间的双向同步环路——它在添加或编辑条目时会导致 UI 严重抖动。
|
||||
|
||||
### Codex Chat 保留用户选中的目录模型
|
||||
|
||||
客户端从目录里选中的模型（例如通过 `/model`）不再被 `config.toml` 的默认模型覆盖。
|
||||
|
||||
### Codex Chat 推理与缓存稳定性
|
||||
|
||||
在 Codex 省略或改写 `previous_response_id` 时恢复一个唯一的 call-id 回退；停止从 `previous_response_id` 派生缓存身份；并在工具转换中对可解析的 JSON 字符串载荷做规范化，以便前缀缓存稳定复用。
|
||||
|
||||
### Codex Chat 流式 usage 恢复
|
||||
|
||||
Responses → Chat 转换现在会在请求为流式时注入 `stream_options.include_usage`（并入客户端提供的任何 `stream_options`），这样 Kimi、MiniMax 这类 OpenAI 兼容上游会重新吐出尾部的 usage 块。此前它们在 Codex Chat 路径上的流式 token / 成本 / 缓存统计都被记成了零。
|
||||
|
||||
### Codex Chat 工具调用推理回填
|
||||
|
||||
Kimi / Moonshot、DeepSeek 这类思考模型会拒绝携带 `tool_calls` 但 `reasoning_content` 为空的 assistant 消息。当跨轮历史恢复未命中时（代理重启、`call_id` 含糊，或某轮上游没有推理），现在会在最后一遍补回一个占位 `reasoning_content`——真实的尾部推理仍会优先附上——这样请求不再因 `reasoning_content is missing in assistant tool call message` 而失败。
|
||||
|
||||
### 受管账号 Claude 接管鉴权
|
||||
|
||||
受管账号供应商（GitHub Copilot / Codex OAuth）在接管 Claude live 配置时，现在会丢弃 token 环境变量键、只写入 `ANTHROPIC_API_KEY` 占位符，并带一个出站守卫拒绝把 `PROXY_MANAGED` 占位符发往上游。
|
||||
|
||||
### 接管期间的 Claude Desktop profile 同步
|
||||
|
||||
代理接管时现在会同步 Claude Desktop 的 profile 数据，模型路由与 Claude Code 的三角色档位对齐，并修正了 Cowork egress profile（#3157、#3172，感谢 @MelorTang、@JGSphaela）。
|
||||
|
||||
### 受管账号接管的模型字段
|
||||
|
||||
本地路由现在在受管账号上从目标供应商取接管模型字段，而不是携带陈旧的模型值。
|
||||
|
||||
### DeepSeek Anthropic 工具思考历史
|
||||
|
||||
规范化了 DeepSeek Anthropic 兼容的工具思考历史，让后续轮次能够重放推理 / 工具调用上下文而不产生畸形消息（#3203，感谢 @Q3yp）。
|
||||
|
||||
### Claude 兼容流中的空工具调用
|
||||
|
||||
修复了一个 Claude 兼容流式边角情况：空的 `tool_calls` 数组会重置块状态并破坏流式响应（#2915，感谢 @zhizhuowq）。
|
||||
|
||||
### Claude Code 代理路径的 MiMo 推理
|
||||
|
||||
在 Claude Code 代理路径上新增 MiMo 的 `reasoning_content` 支持（#2990，感谢 @zhangyapu1）。
|
||||
|
||||
### Gemini Native 工具调用鲁棒性
|
||||
|
||||
修复了长多轮会话中合成工具调用 ID 的 `functionResponse.name` 解析（422）与 `thought_signature` 重放（400）问题（#2814，感谢 @Tiancrimson）。
|
||||
|
||||
### 会话日志 subagent token 计费
|
||||
|
||||
`collect_jsonl_files()` 现在会扫描此前被漏掉的 subagent JSONL 日志，使 subagent 的 token 用量被计入会话成本（仅会话日志模式）（#2821，感谢 @LaoYueHanNi）。
|
||||
|
||||
### 用量看板 / 同步稳定性
|
||||
|
||||
修复了非 ASCII 模型名导致的 Codex 用量同步 panic、自定义用量脚本摘要，以及用量汇总后缺失实时刷新的问题（#3027、#3129，感谢 @in30mn1a、@hanhan3344）。
|
||||
|
||||
### 智谱 Coding Plan 配额档位排序
|
||||
|
||||
当 5 小时桶利用率为 0% 时，智谱 API 会省略 `nextResetTime`；旧的 `i64::MAX` 哨兵会把这类条目排到最后，导致周窗口错误地占用五小时槽位。现在档位排序会让缺失的 `nextResetTime` 映射到五小时桶，使智谱 Coding Plan 的托盘与用量配额显示保持正确。
|
||||
|
||||
### 技能按 key 安装
|
||||
|
||||
从 skills.sh 搜索结果安装时现在使用唯一 key 而不是目录名，使共享目录名的技能能安装到正确的那个（#2784，感谢 @zhaomoran）；同时修复了一处技能同步的复制回退（#2791，感谢 @rogerdigital）。
|
||||
|
||||
### 用量价格输入精度
|
||||
|
||||
把价格输入步长降到 0.0001，使 DeepSeek 缓存读取这类不足一分的成本也能录入（#2793，关闭 #2503，感谢 @rogerdigital）。
|
||||
|
||||
### Ghostty 干净窗口启动
|
||||
|
||||
Ghostty 现在打开单个干净窗口，而不是克隆已有标签页；其他终端则通过 `open -na` 打开新窗口（#2801，关闭 #2798，感谢 @luw2007）。
|
||||
|
||||
### 工具版本与更新可靠性
|
||||
|
||||
版本探测不再掩盖跑不起来的安装；预发布工具在版本检查中被正确处理；批量更新逐工具执行；安装 / 更新按钮在预检期间保持锁定；锚定升级分支强制使用绝对路径；WSL 安装器路径在需要时使用原生 Unix 安装器。
|
||||
|
||||
### Codex mise 检测
|
||||
|
||||
修复了 Codex 的 mise 环境检测（#2822，感谢 @iambinlin）。
|
||||
|
||||
### Codex 归档会话
|
||||
|
||||
Codex 的归档会话现在会被纳入会话发现（#2861，感谢 @nanmen2）。
|
||||
|
||||
### Codex Chat 空工具参数
|
||||
|
||||
在 Codex Chat 转换中，空的工具调用参数载荷会被强制为 `{}`，使上游与客户端收到合法 JSON。
|
||||
|
||||
### Claude 供应商 deeplink 导入
|
||||
|
||||
通过 deeplink 导入 Claude 供应商时现在会保留自定义环境字段（#2928，感谢 @doutuifei）。
|
||||
|
||||
### OMO 推荐模型
|
||||
|
||||
把 OMO 推荐模型与上游默认值同步，并改进了「填入推荐」的反馈。
|
||||
|
||||
### 胜算云模型 ID 加前缀以正确路由
|
||||
|
||||
胜算云（ShengSuanYun）预设现在带上了上游网关要求的厂商前缀——`anthropic/…`、`google/…`、`openai/…`（如 `anthropic/claude-sonnet-4.6`、`google/gemini-3.1-pro-preview`）——覆盖 Claude Code、Claude Desktop、Codex、Gemini、OpenCode、OpenClaw 各预设，含 Claude Code 路由环境变量（`ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_{HAIKU,SONNET,OPUS}_MODEL`），使它们解析到合法的上游模型而不是路由失败。
|
||||
|
||||
### ClaudeAPI 重新启用模型测试
|
||||
|
||||
把 ClaudeAPI 预设（Claude Code 与 Claude Desktop）从 `third_party` 重新归类为 `aggregator`，使其模型测试按钮不再被第三方 Claude 门禁禁用；合作伙伴金星不受影响，因为它由 `isPartner` 而非 category 驱动。
|
||||
|
||||
### 关于页版本检查
|
||||
|
||||
版本检查现在能处理预发布工具版本，不会再误判更新状态。
|
||||
|
||||
### App 切换器文本裁切
|
||||
|
||||
移除了一个会裁切 App 切换器文本的固定宽度约束（#3161，感谢 @loocor）。
|
||||
|
||||
### useEffect 竞态条件
|
||||
|
||||
为 `App.tsx` 的 effects 加了 active-flag 模式以防卸载时的监听器泄漏，并守卫了把 `undefined` 语言存进 localStorage 的情况（#2827，感谢 @Zylo206）。
|
||||
|
||||
---
|
||||
|
||||
## 移除
|
||||
|
||||
### LionCC 赞助商与预设
|
||||
|
||||
跨各 README、供应商配置与 locale 移除了 LionCC 赞助商条目与 LionCCAPI 预设（图标资源保留）。
|
||||
|
||||
### AICoding 合作伙伴条目
|
||||
|
||||
从 README 赞助商列表、供应商预设与 i18n 元数据中移除了 AICoding 合作伙伴。
|
||||
|
||||
### Kimi For Coding 的 Codex 预设
|
||||
|
||||
从 Codex 预设目录中移除了 Kimi For Coding 预设。
|
||||
|
||||
### CLI 卸载命令提示
|
||||
|
||||
从工具管理 UI 中去掉了生成的 CLI 卸载命令提示，同时保留冲突诊断的可见性。
|
||||
|
||||
---
|
||||
|
||||
## 文档
|
||||
|
||||
### Codex Chat 供应商支持
|
||||
|
||||
在 changelog 与用户手册中记录了 Chat Completions 路由、供应商支持、推理自适应识别，以及本地路由指引。
|
||||
|
||||
### 设置手册刷新
|
||||
|
||||
更新了设置文档，覆盖新的受管工具生命周期与 Hermes 安装器行为。
|
||||
|
||||
### Claude Desktop 指南
|
||||
|
||||
新增了本地化的 Claude Desktop 指南页与截图，覆盖供应商设置、导入、模型映射，以及本地路由上下文。
|
||||
|
||||
### 安装文档
|
||||
|
||||
更新了安装文档与 README，推荐官方 Homebrew cask，并跨各语言刷新了 v3.15.0 发布说明里关于山寨站点的警告措辞。
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 升级提醒
|
||||
|
||||
### Codex 第三方供应商历史一次性迁移
|
||||
|
||||
升级后首次启动会对 Codex 历史执行一次性迁移：把第三方供应商归并到 `custom` 桶，并改写历史 JSONL 会话与 `state_5.sqlite` 线程表。原文件会备份到 `~/.cc-switch/backups/codex-history-provider-migration-v1/`。这一步是为了修复"切换供应商后过往会话消失"的问题——迁移后历史能正常恢复。
|
||||
|
||||
### Codex 改动模型目录需重启
|
||||
|
||||
Codex 在启动时加载 `model_catalog_json`，因此在 CC Switch 里改动模型映射表后，需要**重启 Codex** 才能让新目录生效。
|
||||
|
||||
### Chat 路由供应商的思考等级可能无效
|
||||
|
||||
对只暴露"思考开 / 关"开关的供应商（Kimi、GLM、Qwen、MiniMax、MiMo、SiliconFlow），在 Codex 里调节思考等级（`model_reasoning_effort` 的 low / medium / high）**不会有任何效果**——CC Switch 不会把不被支持的 effort 字段透传给它们。只有具备真实 effort 档位的供应商（DeepSeek、OpenRouter，以及 StepFun 仅 `step-3.5-flash-2603`）调节等级才真正生效。
|
||||
|
||||
### 默认模型升级到 Opus 4.8 / GPT-5.5
|
||||
|
||||
默认 Claude Opus 模型线升级到 4.8，适用处的 GPT 默认升级到 5.5。如果你依赖某个固定的旧默认模型，升级后请检查相关预设 / 模板的模型字段是否符合预期。
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 风险提示
|
||||
|
||||
本版本在涉及反向代理类功能上沿用 v3.12.3 / v3.13.0 / v3.15.0 提出的风险提示。
|
||||
|
||||
**GitHub Copilot 反向代理**：使用 Copilot 的反代路径可能违反 GitHub / Microsoft 服务条款。详情见 [v3.12.3 release notes](v3.12.3-zh.md#️-风险提示)。
|
||||
|
||||
**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
|
||||
|
||||
**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束各不相同，请在使用前阅读目标供应商的服务条款。
|
||||
|
||||
**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，第三方供应商对计费、合规与数据留存的约束各不相同，请在使用前阅读目标供应商的服务条款。
|
||||
|
||||
用户启用上述功能即表示**自行承担所有风险**。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 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| 文件 | 说明 |
|
||||
| ---------------------------------------- | ----------------------------------- |
|
||||
| `CC-Switch-v3.16.0-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.16.0-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| -------------------------------- | --------------------------------------------- |
|
||||
| `CC-Switch-v3.16.0-macOS.dmg` | **推荐** - DMG 安装包，拖入 Applications 即可 |
|
||||
| `CC-Switch-v3.16.0-macOS.zip` | 解压后拖入 Applications，Universal Binary |
|
||||
| `CC-Switch-v3.16.0-macOS.tar.gz` | 用于 Homebrew 安装和自动更新 |
|
||||
|
||||
> macOS 版本已通过 Apple 代码签名和公证，可直接安装使用。
|
||||
|
||||
### Homebrew（macOS）
|
||||
|
||||
> 🎉 CC Switch 现已收录至 Homebrew 官方 cask 仓库，无需添加第三方 tap！
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
> Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本：
|
||||
>
|
||||
> - `CC-Switch-v3.16.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
> - `CC-Switch-v3.16.0-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| 发行版 | 推荐格式 | 安装方式 |
|
||||
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| 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` |
|
||||
@@ -0,0 +1,236 @@
|
||||
# CC Switch v3.16.1
|
||||
|
||||
> Codex stability patch: because some users did not want CC Switch to change how Codex config files are written, Codex App Enhancements now has a switch and is off by default. After enabling it, you can keep using Codex mobile remote control, official plugins, and other official-app features while using third-party APIs; this release also includes a series of stability fixes.
|
||||
|
||||
**[中文版 →](v3.16.1-zh.md) | [日本語版 →](v3.16.1-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Usage Guides
|
||||
|
||||
If you want to unlock official-subscription-only Codex remote control and official plugins while using third-party APIs, or want to use DeepSeek / Kimi / GLM / MiniMax and other Chat Completions upstreams in Codex, start with these docs:
|
||||
|
||||
- **[Keep Codex remote control and official plugins while using third-party APIs](../guides/codex-official-auth-preservation-guide-en.md)**: explains how to complete official login first, enable Codex App Enhancements, keep official login state in `auth.json`, and route model traffic to third-party APIs.
|
||||
- **[Using DeepSeek in Codex: local routing hands-on guide](../guides/codex-deepseek-routing-guide-en.md)**: walks through adding a Codex provider, enabling local routing, and verifying request forwarding.
|
||||
- **[Add a Codex provider: Chat Completions routing and model mapping](../user-manual/en/2-providers/2.1-add.md)**: covers the "Needs Local Routing" option, model mapping table, and reasoning capability configuration.
|
||||
- **[Local Proxy Service](../user-manual/en/4-proxy/4.1-service.md)** and **[Local Routing](../user-manual/en/4-proxy/4.2-routing.md)**: explain the proxy service, live-config takeover, and related risk notes.
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## Only Official Channels (Please Read)
|
||||
>
|
||||
> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Please only obtain the software through the official channels listed below:
|
||||
>
|
||||
> | Channel | Only Official |
|
||||
> | ------------------ | ------------------------------------------------------------------------------ |
|
||||
> | Website | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | Source | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | Downloads | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | Author | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.16.1 is a Codex stability patch following v3.16.0. v3.16.0 promoted third-party Codex providers to first-class citizens through Chat Completions routing; this release focuses on several high-risk edges discovered in real use: official ChatGPT / Codex OAuth login state could be overwritten while switching third-party providers or during local routing takeover, the Codex model catalog could be cleared during live backfill, hot switching, takeover shutdown restore, or editing the active provider, and Codex `tool_search`, plugin / connector namespace tools, and custom tools were not fully restored back into Responses events on the Chat Completions upstream path.
|
||||
|
||||
This release also hardens local routing takeover ownership checks. Provider switching and takeover toggles now run serially per app. When deciding whether the live files are proxy-managed, CC Switch no longer relies only on stale `enabled` state or whether the proxy service is currently running; it also checks backups and proxy placeholders in the live files. This prevents ordinary live writes from overwriting proxy-managed config immediately after takeover is enabled, while the proxy is temporarily stopped, or during hot switching.
|
||||
|
||||
**Release date**: 2026-06-01
|
||||
|
||||
**Stats**: 23 commits | 62 files changed | +5,603 insertions | -1,113 deletions
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- **Safer Codex OAuth and third-party provider switching**: added an optional official-auth preservation setting. When enabled, third-party provider tokens are written to `config.toml`, while official ChatGPT / Codex OAuth login stays in `auth.json`.
|
||||
- **Codex model catalogs are no longer silently wiped**: `modelCatalog` now treats the database as the source of truth, avoiding overwrites from live configs with missing catalog projections during live backfill, provider switching, takeover shutdown restore, and provider editing.
|
||||
- **Codex Chat tools / plugin routing restored**: `tool_search`, loaded namespace tools, and custom tools from Chat Completions upstreams are remapped back to Codex Responses shape; streaming custom tools now emit native `response.custom_tool_call_input.*` events.
|
||||
- **More stable local routing takeover and hot switching**: provider switching and takeover toggles are serialized per app. Hot switching refreshes provider display information in Codex live config while keeping the endpoint pointed at the local proxy.
|
||||
- **Diagnostics and platform compatibility fixes**: Codex proxy errors now include richer context; Codex CLI model-template discovery supports more platforms and falls back to a static GPT-5.5 template; Windows tool version detection fixes localized output and command quoting issues.
|
||||
|
||||
---
|
||||
|
||||
## Added
|
||||
|
||||
### Codex Official Auth Preservation Setting
|
||||
|
||||
Added an optional setting for preserving official ChatGPT / Codex OAuth login state when switching to third-party Codex providers. When enabled, CC Switch stores third-party provider API keys in the provider-scoped `experimental_bearer_token` inside Codex `config.toml` instead of overwriting the official login cache in `auth.json`.
|
||||
|
||||
Because some users do not want this feature to change how config files are written, the setting is off by default and keeps the compatibility behavior from before v3.16.0. Users who need both official Codex login and third-party providers can manually enable it under Settings -> Codex App Enhancements.
|
||||
|
||||
### Codex DeepSeek Routing Guide
|
||||
|
||||
Added Codex DeepSeek routing guides in Chinese, English, and Japanese, covering provider routing requirements, the DeepSeek Codex provider form, and screenshot-based local routing takeover instructions.
|
||||
|
||||
---
|
||||
|
||||
## Changed
|
||||
|
||||
### Codex Auth Preservation Is Now Opt-In
|
||||
|
||||
Official auth preservation is off by default. Third-party Codex provider switching therefore keeps the old behavior unless the user opts in, avoiding surprise changes to how `auth.json` / `config.toml` are written.
|
||||
|
||||
### Codex Restart Prompt After Provider Switching
|
||||
|
||||
Codex loads the model catalog and part of its config at startup. After successfully switching a Codex provider, the UI now reminds the user to restart Codex so model catalog and config changes actually take effect.
|
||||
|
||||
### Provider Switching and Takeover Toggles Are Serialized
|
||||
|
||||
Codex / Claude / Gemini provider switching and local routing takeover toggles now share a per-app lock, avoiding concurrent writes to live config and backups. Ownership checks also prioritize live backups and the `PROXY_MANAGED` placeholder instead of relying only on whether the proxy service is running.
|
||||
|
||||
### Codex Hot Switching Refreshes Display Info
|
||||
|
||||
When hot switching Codex providers during local routing takeover, CC Switch refreshes the provider id, model, and display name in the live config so the Codex client menu follows the active provider. The base URL still stays pointed at the local proxy, preventing the real upstream endpoint from leaking back into the live file.
|
||||
|
||||
---
|
||||
|
||||
## Fixed
|
||||
|
||||
### Codex Provider Editor Showing Live OAuth During Takeover
|
||||
|
||||
When Codex is under local routing takeover, live `auth.json` / `config.toml` are temporarily rewritten by the proxy. Editing the active provider from those live files could incorrectly show proxy placeholders or official OAuth login as provider config. The editor now explicitly explains that it is showing the provider config stored in the database, not the proxy-managed live files; even if the proxy service is temporarily stopped, CC Switch still treats the app as under takeover when the takeover state indicates so.
|
||||
|
||||
### Codex OAuth Cleared or Overwritten During Takeover
|
||||
|
||||
Fixed multiple preserve-mode takeover paths that could clear or overwrite official ChatGPT / Codex OAuth `auth.json`. Takeover detection now recognizes `PROXY_MANAGED` in `config.toml`, cleanup only removes proxy placeholder tokens, and third-party providers misclassified as official no longer enter the official-auth overwrite path. Provider sync and switching also treat live backups and placeholders as takeover ownership signals, preventing normal live writes from overwriting proxy config right after takeover or while the proxy is paused.
|
||||
|
||||
### Codex Model Catalog Data Loss
|
||||
|
||||
Fixed cases where `modelCatalog` could be cleared during live backfill, active-provider editing, provider switching, and takeover shutdown restore. Snapshot backups preserve existing `model_catalog_json` pointers; backups rebuilt from providers regenerate catalog projections from the database source of truth; editing the active provider now prefers the database model catalog instead of trusting a live reverse-parse result that may have lost its projection.
|
||||
|
||||
Provider switching also now always refreshes the generated Codex model catalog JSON ([#3360](https://github.com/farion1231/cc-switch/pull/3360), thanks @Postroggy).
|
||||
|
||||
### Codex Chat Tools, Plugins, and Custom Tools Restored
|
||||
|
||||
Fixed Chat Completions routing for third-party Codex providers so `tool_search`, loaded MCP / connector namespace tools, and custom tools are fully restored back into Codex Responses shape. Non-streaming and streaming Chat responses now recover the correct tool type, namespace, call id, and arguments from the original Responses request; custom-tool streaming now emits native `response.custom_tool_call_input.delta` and `response.custom_tool_call_input.done` events.
|
||||
|
||||
### Fuller Codex Proxy Error Diagnostics
|
||||
|
||||
When Codex forwarding fails, CC Switch now returns JSON errors that include provider, model, endpoint, upstream HTTP status, stable `cc_switch_*` error codes, and normalized HTTP status. This makes it much clearer which provider, endpoint, and upstream error caused the failure.
|
||||
|
||||
### Codex Native Balance / Coding Plan Credential Lookup
|
||||
|
||||
Fixed native balance and Coding Plan queries using credentials from the wrong app. Each app now resolves its own provider credentials instead of carrying authentication assumptions from another app surface into the query flow ([#3355](https://github.com/farion1231/cc-switch/pull/3355), thanks @SiskonEmilia).
|
||||
|
||||
### Codex CLI Discovery and Model Catalog Template Fallback
|
||||
|
||||
Fixed a too-narrow Codex CLI discovery path for third-party Codex model catalog projection. The backend now searches common Codex CLI install locations across platforms, and falls back to a built-in GPT-5.5 model catalog template if no template can be found ([#3382](https://github.com/farion1231/cc-switch/pull/3382), thanks @chofuhoyu).
|
||||
|
||||
### Claude Desktop Official Provider Add Failure
|
||||
|
||||
Fixed an error when adding the Claude Desktop Official provider ([#3405](https://github.com/farion1231/cc-switch/pull/3405), thanks @Eunknight).
|
||||
|
||||
### Kimi / Moonshot Tool-Thinking History Normalization
|
||||
|
||||
Added Kimi / Moonshot to the Anthropic-compatible tool-thinking history normalizer. Later turns can now correctly replay reasoning and tool-call context, avoiding failures caused by history messages that do not match upstream requirements ([#3377](https://github.com/farion1231/cc-switch/pull/3377), thanks @Neon-Wang).
|
||||
|
||||
### Windows Tool Version Detection
|
||||
|
||||
Fixed incorrect quoting for `.cmd` / `.bat` version commands on Windows, and fixed localized command output being decoded as mojibake. Previously, these issues could make runnable tools appear as "installed but not runnable."
|
||||
|
||||
---
|
||||
|
||||
## Upgrade Notes
|
||||
|
||||
### Official OAuth Preservation Must Be Enabled Manually
|
||||
|
||||
If you want official ChatGPT / Codex OAuth login to stay in `auth.json` while you frequently switch third-party Codex providers, enable Codex official auth preservation in Settings. It is off by default to keep compatibility for existing users.
|
||||
|
||||
### Restart Codex After Editing Model Mappings
|
||||
|
||||
Codex reads `model_catalog_json` at startup. Even though v3.16.1 fixes model catalog wiping, Codex still needs to be restarted after you edit the model mapping table so the `/model` menu refreshes.
|
||||
|
||||
### During Takeover, the Editor Shows Stored Config, Not Live Files
|
||||
|
||||
When local routing takeover is enabled, live `auth.json` / `config.toml` temporarily point to the CC Switch proxy. The provider editor therefore shows the provider config saved in the database. This is expected; after takeover is disabled, CC Switch restores live config from backups or the database source of truth.
|
||||
|
||||
---
|
||||
|
||||
## Risk Notice
|
||||
|
||||
This release continues the risk notices from previous versions for reverse-proxy-style features.
|
||||
|
||||
**Codex OAuth reverse proxy**: using a ChatGPT subscription's Codex OAuth through a reverse proxy may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details.
|
||||
|
||||
**Codex third-party provider Chat routing**: when CC Switch local proxy converts and forwards Codex requests to third-party providers, each provider may have different requirements for billing, compliance, and data retention. Read the target provider's terms before use.
|
||||
|
||||
**Claude Desktop third-party provider proxy switching**: when CC Switch's built-in proxy gateway forwards Claude Desktop requests to third-party providers, you must also follow the target provider's billing, compliance, and data-retention terms.
|
||||
|
||||
By enabling these features, users accept the related risks. CC Switch is not responsible for account restrictions, warnings, or service suspensions caused by using these features.
|
||||
|
||||
---
|
||||
|
||||
## Thanks
|
||||
|
||||
Thanks to the following contributors for fixes in v3.16.1:
|
||||
|
||||
- [#3360](https://github.com/farion1231/cc-switch/pull/3360): always update Codex model catalog JSON when switching providers, thanks @Postroggy.
|
||||
- [#3355](https://github.com/farion1231/cc-switch/pull/3355): resolve native balance / Coding Plan credentials per app, thanks @SiskonEmilia.
|
||||
- [#3405](https://github.com/farion1231/cc-switch/pull/3405): fix Claude Desktop Official provider add failure, thanks @Eunknight.
|
||||
- [#3382](https://github.com/farion1231/cc-switch/pull/3382): Codex CLI multi-platform discovery and GPT-5.5 model template fallback, thanks @chofuhoyu.
|
||||
- [#3377](https://github.com/farion1231/cc-switch/pull/3377): Kimi / Moonshot tool-thinking history normalization, thanks @Neon-Wang.
|
||||
|
||||
Thanks also to everyone who reported Codex OAuth, model catalog, local routing takeover, and Chat Completions tool-call issues after v3.16.0. Many of these fixes came directly from real-world reproduction details.
|
||||
|
||||
---
|
||||
|
||||
## Download & Install
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) and download the build for your system.
|
||||
|
||||
### System Requirements
|
||||
|
||||
| System | Minimum Version | Architecture |
|
||||
| ------- | ------------------------ | ----------------------------------- |
|
||||
| Windows | Windows 10 and later | x64 |
|
||||
| macOS | macOS 12 (Monterey)+ | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | See table below | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| File | Description |
|
||||
| ---------------------------------------- | ----------------------------------------------- |
|
||||
| `CC-Switch-v3.16.1-Windows.msi` | **Recommended** - MSI installer with auto-update |
|
||||
| `CC-Switch-v3.16.1-Windows-Portable.zip` | Portable build, unzip and run |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| -------------------------------- | ----------------------------------------------------- |
|
||||
| `CC-Switch-v3.16.1-macOS.dmg` | **Recommended** - DMG installer, drag to Applications |
|
||||
| `CC-Switch-v3.16.1-macOS.zip` | Unzip and drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.16.1-macOS.tar.gz` | For Homebrew install and auto-update |
|
||||
|
||||
Homebrew install:
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Upgrade:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Linux assets are available for both **x86_64** and **ARM64** (`aarch64`). Choose the file whose architecture tag matches your machine's `uname -m` output:
|
||||
|
||||
- `CC-Switch-v3.16.1-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- `CC-Switch-v3.16.1-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| Distribution | Recommended Format | Install Command |
|
||||
| ---------------------------------------- | ------------------ | ---------------------------------------------------------------------- |
|
||||
| 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` | Make executable and run directly, or use AUR |
|
||||
| Other distributions / unsure | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
@@ -0,0 +1,236 @@
|
||||
# CC Switch v3.16.1
|
||||
|
||||
> Codex 安定性パッチ: 一部のユーザーから「設定ファイルの書き込み方式を変えたくない」というフィードバックがあったため、Codex アプリ拡張にスイッチを追加し、デフォルトではオフにしました。有効化すると、サードパーティ API を使いながら Codex のモバイルリモート操作、公式プラグインなどの公式アプリ機能を引き続き利用できます。本リリースには一連の安定性修正も含まれます。
|
||||
|
||||
**[English →](v3.16.1-en.md) | [中文 →](v3.16.1-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## 利用ガイド
|
||||
|
||||
サードパーティ API 利用中に、公式サブスクリプションでのみ使える Codex のリモート操作や公式プラグインを有効化したい場合、または DeepSeek / Kimi / GLM / MiniMax などの Chat Completions 上流を Codex で使いたい場合は、まず以下のドキュメントをご覧ください：
|
||||
|
||||
- **[サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する](../guides/codex-official-auth-preservation-guide-ja.md)**: 先に公式ログインを完了し、Codex アプリ拡張を有効化して、公式ログイン状態を `auth.json` に残したままモデル通信をサードパーティ API へ切り替える手順を説明します。
|
||||
- **[Codex で DeepSeek を使う: ローカルルーティング実践ガイド](../guides/codex-deepseek-routing-guide-ja.md)**: Codex プロバイダーの追加、ローカルルーティングの有効化、リクエスト転送の確認までを説明します。
|
||||
- **[Codex プロバイダーの追加: Chat Completions ルーティングとモデルマッピング](../user-manual/ja/2-providers/2.1-add.md)**: 「ローカルルーティングが必要」設定、モデルマッピングテーブル、思考能力の設定を説明します。
|
||||
- **[ローカルプロキシサービス](../user-manual/ja/4-proxy/4.1-service.md)** と **[ローカルルーティング](../user-manual/ja/4-proxy/4.2-routing.md)**: プロキシサービス、live 設定のテイクオーバー、関連するリスク注意事項を説明します。
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## 唯一の公式チャネル（必ずお読みください）
|
||||
>
|
||||
> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。本ソフトウェアは下記の公式チャネルからのみ入手してください：
|
||||
>
|
||||
> | チャネル | 唯一の公式 |
|
||||
> | ------------ | ------------------------------------------------------------------------------ |
|
||||
> | 公式サイト | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | 作者 | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は直ちに操作を中止し、GitHub Issues からご報告ください。
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.16.1 は v3.16.0 に続く Codex 安定性パッチです。v3.16.0 では Chat Completions ルーティングによってサードパーティ Codex プロバイダーを一等市民にしました。本リリースでは、実際の利用で見つかったいくつかの高リスクなエッジケースを中心に修正しています。具体的には、サードパーティプロバイダーの切り替えやローカルルーティングのテイクオーバー中に公式 ChatGPT / Codex OAuth ログイン状態が上書きされる問題、live バックフィル・ホットスイッチ・テイクオーバー解除時の復元・現在のプロバイダー編集で Codex モデルカタログが空になる問題、そして Chat Completions 上流パスで Codex の `tool_search`、プラグイン / コネクタの namespace ツール、カスタムツールが Responses イベントへ完全には復元されない問題です。
|
||||
|
||||
本リリースではローカルルーティングのテイクオーバー所有権判定も強化しました。プロバイダー切り替えとテイクオーバートグルはアプリごとに直列実行されます。live ファイルがプロキシ管理下にあるかを判定するとき、遅延しがちな `enabled` 状態やプロキシサービスの起動状態だけに頼らず、バックアップと live 内のプロキシプレースホルダーも確認します。これにより、テイクオーバー直後、プロキシの一時停止中、ホットスイッチ中に、通常の live 書き込みがプロキシ管理設定を上書きしてしまうことを防ぎます。
|
||||
|
||||
**リリース日**: 2026-06-01
|
||||
|
||||
**Stats**: 23 commits | 62 files changed | +5,603 insertions | -1,113 deletions
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **Codex OAuth とサードパーティプロバイダー切り替えをより安全に**: 公式認証を保持する任意設定を追加しました。有効化すると、サードパーティプロバイダーの token は `config.toml` に書き込まれ、公式 ChatGPT / Codex OAuth ログインは `auth.json` に残ります。
|
||||
- **Codex モデルカタログが静かに消えないように**: `modelCatalog` はデータベースを信頼できる情報源として扱い、live バックフィル、プロバイダー切り替え、テイクオーバー解除時の復元、プロバイダー編集で、カタログ投影を失った live 設定によりデータベースが上書きされることを避けます。
|
||||
- **Codex Chat ツール / プラグインルーティングを復元**: Chat Completions 上流から返る `tool_search`、読み込み済み namespace ツール、カスタムツールを Codex Responses 形態へ再マッピングします。ストリーミングのカスタムツールはネイティブの `response.custom_tool_call_input.*` イベントを出力します。
|
||||
- **ローカルルーティングのテイクオーバーとホットスイッチがより安定**: プロバイダー切り替えとテイクオーバートグルはアプリごとに直列化されます。ホットスイッチ時は Codex live 内のプロバイダー表示情報を更新しつつ、endpoint は引き続きローカルプロキシを指します。
|
||||
- **診断とプラットフォーム互換性の修正**: Codex プロキシエラーがより豊富な文脈を返すようになりました。Codex CLI のモデルテンプレート探索はより多くのプラットフォームに対応し、静的な GPT-5.5 テンプレートのフォールバックを備えます。Windows のツールバージョン検出では、ローカライズ出力とコマンド引用符の問題を修正しました。
|
||||
|
||||
---
|
||||
|
||||
## 追加機能
|
||||
|
||||
### Codex 公式認証保持設定
|
||||
|
||||
サードパーティ Codex プロバイダーへ切り替えるときに、公式 ChatGPT / Codex OAuth ログイン状態を保持する任意設定を追加しました。有効化すると、CC Switch はサードパーティプロバイダーの API key を Codex `config.toml` の provider-scoped `experimental_bearer_token` に保存し、`auth.json` 内の公式ログインキャッシュを上書きしません。
|
||||
|
||||
一部のユーザーはこの機能によって設定ファイルの書き込み方式が変わることを望んでいないため、この設定はデフォルトでオフです。v3.16.0 以前の互換動作を維持します。公式 Codex ログインとサードパーティプロバイダーを同時に使いたい場合は、「設定 → Codex アプリ拡張」で手動で有効化できます。
|
||||
|
||||
### Codex DeepSeek ルーティングガイド
|
||||
|
||||
Codex DeepSeek ルーティングガイドを中国語 / 英語 / 日本語で追加しました。プロバイダーのルーティング要件、DeepSeek Codex プロバイダーフォームの設定、ローカルルーティングのテイクオーバー手順をスクリーンショット付きで説明します。
|
||||
|
||||
---
|
||||
|
||||
## 変更
|
||||
|
||||
### Codex 認証保持は opt-in に変更
|
||||
|
||||
公式認証保持設定はデフォルトでオフです。これにより、サードパーティ Codex プロバイダーの切り替えは従来の動作を維持し、ユーザーが気づかないうちに `auth.json` / `config.toml` の書き込み方式が変わることを避けます。
|
||||
|
||||
### Codex プロバイダー切り替え後に再起動を案内
|
||||
|
||||
Codex はモデルカタログと一部の設定をクライアント起動時に読み込みます。Codex プロバイダーの切り替えに成功した後、UI は Codex の再起動を案内し、モデルカタログと設定変更が実際に反映されるようにします。
|
||||
|
||||
### プロバイダー切り替えとテイクオーバートグルを直列化
|
||||
|
||||
Codex / Claude / Gemini のプロバイダー切り替えとローカルルーティングのテイクオーバートグルは、アプリごとのロックを共有するようになりました。これにより、2 つの処理が同時に live 設定とバックアップを書き換えることを避けます。live がプロキシ管理下にあるかの判定も、プロキシサービスが起動しているかだけでなく、live バックアップと `PROXY_MANAGED` プレースホルダーを優先して確認します。
|
||||
|
||||
### Codex ホットスイッチで表示情報を更新
|
||||
|
||||
ローカルルーティングのテイクオーバー中に Codex プロバイダーをホットスイッチすると、CC Switch は live 設定内の provider id、モデル、表示名を更新し、Codex クライアントのメニューが現在のプロバイダーに追従するようにします。同時に base URL はローカルプロキシアドレスのまま維持し、実際の上流 endpoint が live ファイルへ戻ってしまうことを防ぎます。
|
||||
|
||||
---
|
||||
|
||||
## 修正
|
||||
|
||||
### Codex テイクオーバー中の編集ダイアログが live OAuth を表示する問題
|
||||
|
||||
Codex がローカルルーティングのテイクオーバー状態にあるとき、live の `auth.json` / `config.toml` はプロキシによって一時的に書き換えられています。この live を読み続けると、現在のプロバイダー編集時にプロキシプレースホルダーや公式 OAuth ログインをプロバイダー設定として誤表示してしまいます。現在の編集ダイアログは、ここに表示されるのがプロキシ管理下の live ファイルではなく、データベースに保存されたプロバイダー設定であることを明示します。プロキシサービスが一時停止していても、そのアプリがテイクオーバー状態であればテイクオーバーとして扱います。
|
||||
|
||||
### Codex OAuth がテイクオーバー中に消去または上書きされる問題
|
||||
|
||||
公式 ChatGPT / Codex OAuth `auth.json` を消去または上書きする可能性があった複数の preserve-mode テイクオーバーパスを修正しました。テイクオーバー判定は `config.toml` 内の `PROXY_MANAGED` を認識し、クリーンアップはプロキシプレースホルダー token だけを削除します。サードパーティプロバイダーが official と誤分類されても、公式 auth の上書きパスには入りません。プロバイダー同期と切り替えでは、live バックアップとプレースホルダーをテイクオーバー所有権のシグナルとして扱い、テイクオーバー直後やプロキシ一時停止中に通常の live 書き込みがプロキシ設定を上書きすることを防ぎます。
|
||||
|
||||
### Codex モデルカタログのデータ消失
|
||||
|
||||
live バックフィル、現在のプロバイダー編集、プロバイダー切り替え、テイクオーバー解除時の復元などで `modelCatalog` が空になる問題を修正しました。スナップショットバックアップは既存の `model_catalog_json` ポインターを保持します。プロバイダーから再構築されるバックアップは、データベースの信頼できる情報源からカタログ投影を再生成します。現在のプロバイダー編集時は、投影を失っている可能性のある live の逆解析結果ではなく、データベース内のモデルカタログを優先します。
|
||||
|
||||
また、プロバイダー切り替え時には生成済みの Codex モデルカタログ JSON を常に更新するようになりました（[#3360](https://github.com/farion1231/cc-switch/pull/3360)、@Postroggy に感謝）。
|
||||
|
||||
### Codex Chat ツール、プラグイン、カスタムツールの復元
|
||||
|
||||
サードパーティ Codex プロバイダーが Chat Completions ルーティングを通るとき、`tool_search`、読み込み済みの MCP / connector namespace ツール、カスタムツールを Codex Responses 形態へ完全に復元できない問題を修正しました。非ストリーミングとストリーミングの Chat レスポンスは、元の Responses リクエストに基づいて正しいツール種別、namespace、call id、引数を復元します。カスタムツールのストリーミング出力は、ネイティブの `response.custom_tool_call_input.delta` と `response.custom_tool_call_input.done` イベントを発行します。
|
||||
|
||||
### Codex プロキシエラー診断の拡充
|
||||
|
||||
Codex の転送に失敗したとき、provider、model、endpoint、上流 HTTP ステータス、安定した `cc_switch_*` エラーコード、正規化された HTTP ステータスを含む JSON エラーを返すようになりました。これにより、どのプロバイダー、どの endpoint、どの上流エラーが原因なのかを追いやすくなります。
|
||||
|
||||
### Codex ネイティブ残高 / Coding Plan の認証情報検索
|
||||
|
||||
ネイティブ残高と Coding Plan の照会時に、別アプリの認証情報を誤って使う問題を修正しました。各 app は自分自身のプロバイダー認証情報を解析し、別のアプリ面の認証前提を照会フローへ持ち込まなくなりました（[#3355](https://github.com/farion1231/cc-switch/pull/3355)、@SiskonEmilia に感謝）。
|
||||
|
||||
### Codex CLI 探索とモデルカタログテンプレートのフォールバック
|
||||
|
||||
サードパーティ Codex モデルカタログ投影における Codex CLI の探索パスが狭すぎる問題を修正しました。バックエンドは複数プラットフォームの一般的な Codex CLI インストール場所を探し、それでもテンプレートが見つからない場合は内蔵の GPT-5.5 モデルカタログテンプレートへフォールバックします（[#3382](https://github.com/farion1231/cc-switch/pull/3382)、@chofuhoyu に感謝）。
|
||||
|
||||
### Claude Desktop Official プロバイダー追加失敗
|
||||
|
||||
Claude Desktop Official プロバイダー追加時のエラーを修正しました（[#3405](https://github.com/farion1231/cc-switch/pull/3405)、@Eunknight に感謝）。
|
||||
|
||||
### Kimi / Moonshot ツール思考履歴の正規化
|
||||
|
||||
Kimi / Moonshot を Anthropic 互換ツール思考履歴 normalizer に追加しました。後続ターンで reasoning と tool-call コンテキストを正しく再生できるようになり、履歴メッセージの形が上流要件に合わず失敗する問題を避けます（[#3377](https://github.com/farion1231/cc-switch/pull/3377)、@Neon-Wang に感謝）。
|
||||
|
||||
### Windows ツールバージョン検出
|
||||
|
||||
Windows で `.cmd` / `.bat` のバージョンコマンドに誤って引用符が付く問題と、ローカライズされたコマンド出力が文字化けしてデコードされる問題を修正しました。以前は、実行可能なツールが「インストール済みだが実行できない」と表示されることがありました。
|
||||
|
||||
---
|
||||
|
||||
## アップグレード時の注意
|
||||
|
||||
### 公式 OAuth 保持は手動で有効化が必要
|
||||
|
||||
公式 ChatGPT / Codex OAuth ログインを `auth.json` に長期保持しつつ、サードパーティ Codex プロバイダーを頻繁に切り替える場合は、設定で Codex 公式認証保持を有効化してください。既存ユーザーの互換動作を維持するため、デフォルトではオフです。
|
||||
|
||||
### モデルマッピング変更後は Codex の再起動が必要
|
||||
|
||||
Codex は起動時に `model_catalog_json` を読み込みます。v3.16.1 でモデルカタログが空になる問題は修正されていますが、モデルマッピングテーブルを変更した後は、`/model` メニューを更新するために Codex の再起動が必要です。
|
||||
|
||||
### テイクオーバー中に編集するのは保存済み設定であり live ファイルではありません
|
||||
|
||||
ローカルルーティングのテイクオーバーを有効化すると、live の `auth.json` / `config.toml` は一時的に CC Switch プロキシを指します。このときプロバイダー編集で表示されるのは、データベースに保存されたプロバイダー設定です。これは期待される動作です。テイクオーバーを無効化すると、CC Switch はバックアップまたはデータベースの信頼できる情報源から live 設定を復元します。
|
||||
|
||||
---
|
||||
|
||||
## リスク通知
|
||||
|
||||
本リリースは、リバースプロキシ系機能に関する以前のリスク通知を引き続き適用します。
|
||||
|
||||
**Codex OAuth リバースプロキシ**: ChatGPT サブスクリプションの Codex OAuth をリバースプロキシ経由で使用すると、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 release notes](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
|
||||
|
||||
**Codex サードパーティプロバイダー Chat ルーティング**: CC Switch ローカルプロキシで Codex リクエストを変換し、サードパーティプロバイダーへ転送する場合、課金、コンプライアンス、データ保持に関する制約はプロバイダーごとに異なります。利用前に対象プロバイダーの利用規約を確認してください。
|
||||
|
||||
**Claude Desktop サードパーティプロバイダープロキシ切り替え**: CC Switch 内蔵のプロキシゲートウェイで Claude Desktop のリクエストをサードパーティプロバイダーへ転送する場合も、対象プロバイダーの課金、コンプライアンス、データ保持に関する規約に従う必要があります。
|
||||
|
||||
上記機能を有効化したユーザーは、関連するリスクを自ら負うものとします。CC Switch は、これらの機能の利用によって発生したアカウント制限、警告、サービス停止について責任を負いません。
|
||||
|
||||
---
|
||||
|
||||
## 謝辞
|
||||
|
||||
v3.16.1 で修正を届けてくださった以下のコントリビューターに感謝します：
|
||||
|
||||
- [#3360](https://github.com/farion1231/cc-switch/pull/3360): Codex プロバイダー切り替え時にモデルカタログ JSON を常に更新、@Postroggy に感謝。
|
||||
- [#3355](https://github.com/farion1231/cc-switch/pull/3355): ネイティブ残高 / Coding Plan 照会の認証情報を app ごとに解析、@SiskonEmilia に感謝。
|
||||
- [#3405](https://github.com/farion1231/cc-switch/pull/3405): Claude Desktop Official プロバイダー追加エラーを修正、@Eunknight に感謝。
|
||||
- [#3382](https://github.com/farion1231/cc-switch/pull/3382): Codex CLI の複数プラットフォーム探索と GPT-5.5 モデルテンプレートフォールバック、@chofuhoyu に感謝。
|
||||
- [#3377](https://github.com/farion1231/cc-switch/pull/3377): Kimi / Moonshot ツール思考履歴の正規化、@Neon-Wang に感謝。
|
||||
|
||||
v3.16.0 リリース後に Codex OAuth、モデルカタログ、ローカルルーティングのテイクオーバー、Chat Completions ツール呼び出しの問題を報告してくださったすべてのユーザーにも感謝します。今回の多くの修正は、実際の利用シーンから得られた再現情報に基づいています。
|
||||
|
||||
---
|
||||
|
||||
## ダウンロードとインストール
|
||||
|
||||
[Releases](https://github.com/farion1231/cc-switch/releases/latest) から、お使いのシステムに対応するビルドをダウンロードしてください。
|
||||
|
||||
### システム要件
|
||||
|
||||
| システム | 最低バージョン | アーキテクチャ |
|
||||
| -------- | ------------------------ | --------------------------------- |
|
||||
| Windows | Windows 10 以降 | x64 |
|
||||
| macOS | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 下表を参照 | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| ファイル | 説明 |
|
||||
| ---------------------------------------- | --------------------------------------------------- |
|
||||
| `CC-Switch-v3.16.1-Windows.msi` | **推奨** - 自動更新対応の MSI インストーラー |
|
||||
| `CC-Switch-v3.16.1-Windows-Portable.zip` | ポータブル版、展開してそのまま実行できます |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| -------------------------------- | ------------------------------------------------------- |
|
||||
| `CC-Switch-v3.16.1-macOS.dmg` | **推奨** - DMG インストーラー、Applications へドラッグ |
|
||||
| `CC-Switch-v3.16.1-macOS.zip` | 展開して Applications へドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.16.1-macOS.tar.gz` | Homebrew インストールと自動更新用 |
|
||||
|
||||
Homebrew インストール：
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Linux アセットは **x86_64** と **ARM64**（`aarch64`）の両方を提供します。ファイル名にアーキテクチャ識別子が含まれているため、マシンの `uname -m` 出力に合わせて選択してください：
|
||||
|
||||
- `CC-Switch-v3.16.1-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- `CC-Switch-v3.16.1-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| ディストリビューション | 推奨形式 | インストール方法 |
|
||||
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| 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` |
|
||||
@@ -0,0 +1,236 @@
|
||||
# CC Switch v3.16.1
|
||||
|
||||
> Codex 稳定性补丁：由于部分用户反映不希望改变配置文件的写入方式，因此为 Codex 增强模式添加开关并默认关闭。开启此开关后，你可以在使用第三方 API 的情况下继续使用 Codex 的手机远程操作、官方插件等功能；本版本也包含一系列稳定性修复。
|
||||
|
||||
**[English →](v3.16.1-en.md) | [日本語版 →](v3.16.1-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 使用攻略
|
||||
|
||||
如果你希望在使用第三方 API 的时候解锁官方订阅才可以使用的远程操作 Codex、解锁官方插件，或希望在 Codex 中使用 DeepSeek / Kimi / GLM / MiniMax 等 Chat Completions 上游，建议先看这些文档：
|
||||
|
||||
- **[使用第三方 API 时保留 Codex 远程操作和官方插件](../guides/codex-official-auth-preservation-guide-zh.md)**：说明如何先完成官方登录，再开启 Codex 应用增强，让官方登录态留在 `auth.json`，同时把模型流量切到第三方 API。
|
||||
- **[在 Codex 中使用 DeepSeek：本地路由实战攻略](../guides/codex-deepseek-routing-guide-zh.md)**：从添加 Codex 供应商、开启本地路由，到验证请求转发的完整路径。
|
||||
- **[添加 Codex 供应商：Chat Completions 路由与模型映射](../user-manual/zh/2-providers/2.1-add.md)**：覆盖「需要本地路由映射」、模型映射表与思考能力配置。
|
||||
- **[本地代理服务](../user-manual/zh/4-proxy/4.1-service.md)** 与 **[本地路由](../user-manual/zh/4-proxy/4.2-routing.md)**：了解代理服务、接管 live 配置、以及相关风险提示。
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## 唯一官方渠道声明（请务必阅读）
|
||||
>
|
||||
> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。请仅通过下列官方渠道获取本软件：
|
||||
>
|
||||
> | 类别 | 唯一官方 |
|
||||
> | -------- | ------------------------------------------------------------------------------ |
|
||||
> | 官网 | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | 源码 | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | 下载 | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | 作者 | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.16.1 是 v3.16.0 之后的一版 Codex 稳定性补丁。v3.16.0 让第三方 Codex 供应商通过 Chat Completions 路由成为一等公民；这一版则主要处理真实使用中暴露出的几个高风险边角：官方 ChatGPT / Codex OAuth 登录态在第三方供应商切换或本地路由接管期间被覆盖，Codex 模型目录在 live 回填、热切换、关闭接管恢复或编辑当前供应商时被清空，以及 Codex 的 `tool_search`、插件 / 连接器命名空间、自定义工具在 Chat Completions 上游路径中没有完整恢复为 Responses 事件。
|
||||
|
||||
这版也加固了本地路由接管的所有权判断：切换供应商和开启 / 关闭接管现在按应用串行执行，判断 live 文件是否由代理接管时不再只看滞后的 `enabled` 或代理服务是否正在运行，而是结合备份和 live 中的代理占位符。这样可以避免刚开启接管、代理临时停止，或热切换时的普通 live 写入把代理托管配置覆盖掉。
|
||||
|
||||
**发布日期**：2026-06-01
|
||||
|
||||
**更新规模**：23 commits | 62 files changed | +5,603 / -1,113 lines
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- **Codex OAuth 与第三方供应商切换更安全**：新增可选的官方认证保留设置；开启后，第三方供应商 token 写入 `config.toml`，官方 ChatGPT / Codex OAuth 登录继续留在 `auth.json`。
|
||||
- **Codex 模型目录不再被静默清空**：`modelCatalog` 以数据库为真相来源，live 回填、供应商切换、接管关闭恢复、编辑弹窗都会避免用丢失投影的 live 配置覆盖数据库。
|
||||
- **Codex Chat 工具 / 插件路由恢复**：Chat Completions 上游返回的 `tool_search`、已加载命名空间工具、自定义工具会重新映射回 Codex Responses 形态；流式自定义工具现在发出原生 `response.custom_tool_call_input.*` 事件。
|
||||
- **本地路由接管与热切换更稳**：供应商切换和接管开关按 app 串行，热切换会刷新 Codex live 中的供应商显示信息，但 endpoint 仍保持指向本地代理。
|
||||
- **诊断与平台兼容性修复**：Codex 代理错误返回更丰富上下文；Codex CLI 模型模板发现支持更多平台并提供 GPT-5.5 静态兜底；Windows 工具版本探测修复乱码与误判。
|
||||
|
||||
---
|
||||
|
||||
## 新功能
|
||||
|
||||
### Codex 官方认证保留设置
|
||||
|
||||
新增一个可选设置，用于在切换第三方 Codex 供应商时保留官方 ChatGPT / Codex OAuth 登录态。开启后，CC Switch 会把第三方供应商的 API key 放进 Codex `config.toml` 的 provider-scoped `experimental_bearer_token`，而不是覆盖 `auth.json` 里的官方登录缓存。
|
||||
|
||||
由于部分用户不希望此功能改变配置文件的写入方式，因此该设置默认关闭，保持 v3.16.0 之前的兼容行为。需要同时使用官方 Codex 登录和第三方供应商的用户，可以在“设置 → Codex 应用增强”里手动开启。
|
||||
|
||||
### Codex DeepSeek 路由指南
|
||||
|
||||
新增中 / 英 / 日三语的 Codex DeepSeek 路由指南，包含供应商路由要求、DeepSeek Codex 供应商表单配置，以及本地路由接管的截图说明。
|
||||
|
||||
---
|
||||
|
||||
## 变更
|
||||
|
||||
### Codex 认证保留默认改为 opt-in
|
||||
|
||||
官方认证保留设置默认关闭。这样第三方 Codex 供应商切换继续沿用旧行为，避免已有用户在不知情的情况下改变 `auth.json` / `config.toml` 的写入方式。
|
||||
|
||||
### Codex 切换供应商后提示重启
|
||||
|
||||
Codex 的模型目录与部分配置在客户端启动时加载。现在成功切换 Codex 供应商后，界面会提示用户重启 Codex，让模型目录和配置变化真正生效。
|
||||
|
||||
### 供应商切换与接管开关串行化
|
||||
|
||||
Codex / Claude / Gemini 的供应商切换与本地路由接管开关现在共享 per-app 锁，避免两个流程同时修改 live 配置和备份。判断 live 是否由代理接管时，也会优先看 live 备份与 `PROXY_MANAGED` 占位符，而不是只看代理服务是否正在运行。
|
||||
|
||||
### Codex 热切换刷新显示信息
|
||||
|
||||
在本地路由接管期间热切换 Codex 供应商时，CC Switch 会刷新 live 配置中的 provider id、模型和显示名称，让 Codex 客户端菜单能跟随当前供应商；同时 base URL 仍保持本地代理地址，避免真实上游 endpoint 泄回 live 文件。
|
||||
|
||||
---
|
||||
|
||||
## 修复
|
||||
|
||||
### Codex 接管期间编辑弹窗误显示 live OAuth
|
||||
|
||||
当 Codex 处于本地路由接管状态时，live `auth.json` / `config.toml` 已被代理临时改写。编辑当前供应商如果继续读取 live，就会把代理占位符或官方 OAuth 登录误显示成供应商配置。现在编辑弹窗会明确提示：此处显示的是数据库中存储的供应商配置，而不是代理托管的 live 文件；即使代理服务暂时停止，只要该 app 仍处于接管状态，也会按接管逻辑处理。
|
||||
|
||||
### Codex OAuth 在接管期间被清空或覆盖
|
||||
|
||||
修复多条 preserve-mode 接管路径，它们此前可能清空或覆盖官方 ChatGPT / Codex OAuth `auth.json`。现在接管检测会识别 `config.toml` 里的 `PROXY_MANAGED`，清理流程只移除代理占位符 token，第三方供应商错误归类为 official 时也不会再走官方 auth 覆盖路径。供应商同步与切换会把 live 备份和占位符视为接管所有权信号，避免正常 live 写入覆盖刚接管或代理暂停时的代理配置。
|
||||
|
||||
### Codex 模型目录数据丢失
|
||||
|
||||
修复 `modelCatalog` 在 live 回填、当前供应商编辑弹窗、供应商切换、关闭接管恢复等场景被清空的问题。快照备份会保留已有 `model_catalog_json` 指针；由供应商重建的备份会从数据库真相来源重新生成目录投影；编辑当前供应商时会优先使用数据库里的模型目录，而不是信任可能已经丢失投影的 live 反解结果。
|
||||
|
||||
同时，供应商切换现在会始终刷新生成的 Codex 模型目录 JSON（[#3360](https://github.com/farion1231/cc-switch/pull/3360)，感谢 @Postroggy）。
|
||||
|
||||
### Codex Chat 工具、插件和自定义工具恢复
|
||||
|
||||
修复第三方 Codex 供应商走 Chat Completions 路由时，`tool_search`、已加载的 MCP / connector 命名空间工具、自定义工具无法完整恢复为 Codex Responses 形态的问题。非流式与流式 Chat 响应现在都会根据原始 Responses 请求恢复正确的工具类型、namespace、call id 与参数；自定义工具流式输出会发出原生的 `response.custom_tool_call_input.delta` 和 `response.custom_tool_call_input.done` 事件。
|
||||
|
||||
### Codex 代理错误诊断更完整
|
||||
|
||||
Codex 转发失败时，现在返回包含 provider、model、endpoint、上游 HTTP 状态、稳定 `cc_switch_*` 错误码和规范 HTTP 状态的 JSON 错误。这样排查「到底是哪个供应商、哪个 endpoint、哪种上游错误」会清楚很多。
|
||||
|
||||
### Codex 原生余额 / Coding Plan 查询凭据
|
||||
|
||||
修复原生余额与 Coding Plan 查询时跨 app 错用凭据的问题。现在每个 app 会解析自己的供应商凭据，不再把其他应用面的认证假设带进查询流程（[#3355](https://github.com/farion1231/cc-switch/pull/3355)，感谢 @SiskonEmilia）。
|
||||
|
||||
### Codex CLI 发现与模型目录模板兜底
|
||||
|
||||
修复第三方 Codex 模型目录投影对 Codex CLI 发现路径过窄的问题。现在后端会在多平台常见安装位置寻找 Codex CLI，并在仍找不到模板时使用内置 GPT-5.5 模型目录模板兜底（[#3382](https://github.com/farion1231/cc-switch/pull/3382)，感谢 @chofuhoyu）。
|
||||
|
||||
### Claude Desktop 官方供应商添加失败
|
||||
|
||||
修复添加 Claude Desktop 官方供应商时报错的问题（[#3405](https://github.com/farion1231/cc-switch/pull/3405)，感谢 @Eunknight）。
|
||||
|
||||
### Kimi / Moonshot 工具思考历史规范化
|
||||
|
||||
把 Kimi / Moonshot 加入 Anthropic 兼容工具思考历史 normalizer。后续轮次现在能正确重放 reasoning 与 tool-call 上下文，避免因为历史消息形态不符合上游要求而失败（[#3377](https://github.com/farion1231/cc-switch/pull/3377)，感谢 @Neon-Wang）。
|
||||
|
||||
### Windows 工具版本探测
|
||||
|
||||
修复 Windows 上 `.cmd` / `.bat` 版本命令被错误加引号，以及本地化命令输出被解码成乱码的问题。此前这些问题会让可运行的工具显示为「已安装但无法运行」。
|
||||
|
||||
---
|
||||
|
||||
## 升级提醒
|
||||
|
||||
### 官方 OAuth 保留需要手动开启
|
||||
|
||||
如果你希望官方 ChatGPT / Codex OAuth 登录长期保留在 `auth.json`，同时又频繁切换第三方 Codex 供应商，请在设置中开启 Codex 官方认证保留。默认关闭是为了保持老用户的兼容行为。
|
||||
|
||||
### 修改模型映射后仍需重启 Codex
|
||||
|
||||
Codex 在启动时读取 `model_catalog_json`。因此即使 v3.16.1 已修复模型目录被清空的问题，只要你修改了模型映射表，仍然需要重启 Codex 才能让 `/model` 菜单刷新。
|
||||
|
||||
### 接管期间编辑的是存储配置，不是 live 文件
|
||||
|
||||
本地路由接管开启后，live `auth.json` / `config.toml` 会临时指向 CC Switch 代理。此时编辑供应商时看到的是数据库里保存的供应商配置，属于预期行为；关闭接管后，CC Switch 会按备份或数据库真相来源恢复 live 配置。
|
||||
|
||||
---
|
||||
|
||||
## 风险提示
|
||||
|
||||
本版本继续沿用此前版本对反向代理类功能的风险提示。
|
||||
|
||||
**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
|
||||
|
||||
**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
|
||||
|
||||
**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，同样需要遵守目标供应商的计费、合规与数据留存约束。
|
||||
|
||||
用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
|
||||
|
||||
---
|
||||
|
||||
## 致谢
|
||||
|
||||
感谢以下贡献者在 v3.16.1 中提交修复：
|
||||
|
||||
- [#3360](https://github.com/farion1231/cc-switch/pull/3360)：Codex 供应商切换时始终更新模型目录 JSON，感谢 @Postroggy。
|
||||
- [#3355](https://github.com/farion1231/cc-switch/pull/3355)：原生余额 / Coding Plan 查询按 app 解析凭据，感谢 @SiskonEmilia。
|
||||
- [#3405](https://github.com/farion1231/cc-switch/pull/3405)：修复 Claude Desktop 官方供应商添加报错，感谢 @Eunknight。
|
||||
- [#3382](https://github.com/farion1231/cc-switch/pull/3382)：Codex CLI 多平台发现与 GPT-5.5 模型模板兜底，感谢 @chofuhoyu。
|
||||
- [#3377](https://github.com/farion1231/cc-switch/pull/3377)：Kimi / Moonshot 工具思考历史规范化，感谢 @Neon-Wang。
|
||||
|
||||
也感谢所有在 v3.16.0 发布后反馈 Codex OAuth、模型目录、本地路由接管和 Chat Completions 工具调用问题的用户。很多补丁都来自这些真实使用场景里的复现线索。
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
|
||||
|
||||
### 系统要求
|
||||
|
||||
| 系统 | 最低版本 | 架构 |
|
||||
| ------- | -------------------------- | ----------------------------------- |
|
||||
| Windows | Windows 10 及以上 | x64 |
|
||||
| macOS | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 见下表 | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| 文件 | 说明 |
|
||||
| ---------------------------------------- | ----------------------------------- |
|
||||
| `CC-Switch-v3.16.1-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.16.1-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| -------------------------------- | --------------------------------------------- |
|
||||
| `CC-Switch-v3.16.1-macOS.dmg` | **推荐** - DMG 安装包，拖入 Applications 即可 |
|
||||
| `CC-Switch-v3.16.1-macOS.zip` | 解压后拖入 Applications，Universal Binary |
|
||||
| `CC-Switch-v3.16.1-macOS.tar.gz` | 用于 Homebrew 安装和自动更新 |
|
||||
|
||||
Homebrew 安装：
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本：
|
||||
|
||||
- `CC-Switch-v3.16.1-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- `CC-Switch-v3.16.1-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| 发行版 | 推荐格式 | 安装方式 |
|
||||
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| 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` |
|
||||
@@ -0,0 +1,347 @@
|
||||
# CC Switch v3.16.2
|
||||
|
||||
> Following the v3.16.1 Codex stability patch, this release mainly broadens data portability and usage observability — adding S3-compatible cloud sync, OpenCode session usage sync, and an official-subscription quota template — while continuing to harden Codex's Chat Completions routing for third-party providers, fixing a batch of Windows / macOS platform issues, adding the CherryIN and ZenMux providers, and fully refreshing the trilingual user manual.
|
||||
|
||||
**[中文版 →](v3.16.2-zh.md) | [日本語版 →](v3.16.2-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Usage Guides
|
||||
|
||||
This release adds an S3 backend for cloud sync and more usage data sources. If you want to use them, start with these docs:
|
||||
|
||||
- **[Settings](../user-manual/en/1-getting-started/1.5-settings.md)**: configure cloud sync (WebDAV / S3-compatible storage) on the settings page to back up and restore providers, MCP, prompts, skills, and other config across multiple devices.
|
||||
- **[Usage Statistics](../user-manual/en/4-proxy/4.4-usage.md)**: understand the Usage Dashboard's data sources (proxy logs, Codex / Gemini / OpenCode session sync) and how the statistics are counted.
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## Only Official Channels (Please Read)
|
||||
>
|
||||
> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Please only obtain the software through the official channels listed below:
|
||||
>
|
||||
> | Channel | Only Official |
|
||||
> | ------------------ | ------------------------------------------------------------------------------ |
|
||||
> | Website | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | Source | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | Downloads | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | Author | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.16.2 is a maintenance update following v3.16.1. After the previous release focused on the security of Codex official authentication and local routing takeover, this release concentrates on two things. First, broadening data portability and usage observability — adding S3-compatible cloud sync (a second cloud-backup backend alongside WebDAV), OpenCode session usage sync, and a quota-statistics template for official subscriptions. Second, continuing to polish the edges exposed when Codex routes third-party providers through Chat Completions — stream-truncation detection, `tool_choice` when tools is empty, custom-tool metadata, reasoning-token statistics, file / audio attachment conversion, and more.
|
||||
|
||||
This release also fixes a batch of local proxy robustness issues (ephemeral port resolution, the takeover placeholder restore loop, Anthropic `system` message normalization, the upstream 413 message, and Claude Desktop's `[1m]` model routing), addresses several Windows / macOS platform experience issues, adds the CherryIN and ZenMux providers, and fully refreshes the trilingual user manual.
|
||||
|
||||
**Release date**: 2026-06-07
|
||||
|
||||
**Stats**: 41 commits | 132 files changed | +11,116 / -1,636 lines
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- **S3-compatible cloud sync**: adds S3-compatible object storage as a second cloud-backup backend alongside WebDAV, with one-click presets for AWS S3, MinIO, Cloudflare R2, Alibaba Cloud OSS, Tencent Cloud COS, Huawei OBS, and more.
|
||||
- **More usage data sources**: added OpenCode session usage sync, plus an official-subscription quota template for Claude / Codex / Gemini official providers (explicit toggle, off by default).
|
||||
- **Continued Codex Chat Completions routing hardening**: fixed stream-truncation misdetection, `tool_choice` rejection when tools is empty, custom-tool metadata loss, and missing reasoning-token stats, and added file / audio attachment conversion plus a `/v1/models` reachability endpoint.
|
||||
- **A more robust local proxy**: fixed ephemeral port (port 0) resolution, the takeover placeholder restore loop, Anthropic `system` message normalization, the upstream 413 message, and Claude Desktop 1M-context model routing.
|
||||
- **Platform and providers**: fixed Windows tray / taskbar icons, subdirectory skill updates, and macOS input auto-capitalization, and added the CherryIN and ZenMux providers.
|
||||
|
||||
---
|
||||
|
||||
## Added
|
||||
|
||||
### S3-Compatible Cloud Sync
|
||||
|
||||
Cloud Sync now supports S3-compatible object storage as a second backend alongside WebDAV, signing requests with a self-implemented AWS Signature V4 for the broadest possible compatibility. The settings page offers one-click presets for AWS S3, MinIO, Cloudflare R2, Alibaba Cloud OSS, Tencent Cloud COS, Huawei OBS, and a custom endpoint, with connection testing, manual upload / download, and auto-sync on configuration changes (the providers, endpoint, MCP, prompt, skill, settings, and proxy tables — **not** high-frequency data like usage logs). Enabling S3 sync disables a running WebDAV sync and vice versa (#1351).
|
||||
|
||||
### OpenCode Session Usage Sync
|
||||
|
||||
Added OpenCode as a usage-statistics source that reads per-message token, cost, and model data from OpenCode's local SQLite database and imports it into the usage records, with a dedicated "OpenCode" app filter tab and an "OpenCode Session" data-source label. The database path respects `OPENCODE_DB` and `XDG_DATA_HOME` (defaulting to `~/.local/share/opencode` on all platforms), only finalized messages are imported, and the freshness check includes the WAL file so just-written sessions are not skipped (#3215).
|
||||
|
||||
### Official Subscription Quota Template
|
||||
|
||||
Because some users were concerned that the IP issuing the usage query could differ from the IP issuing in-app requests, risking an account ban, the official-subscription usage template for Claude / Codex / Gemini official providers is now an explicit, opt-in template that queries plan quota via CLI / OAuth credentials, replacing the previous implicit auto-query for official providers. The template is off by default, is enabled from the usage-script modal, and supports a configurable refresh interval. When using this feature, enabling the proxy's TUN mode is recommended.
|
||||
|
||||
### Text-Only Model Image Fallback Rectifier
|
||||
|
||||
Added a proxy rectifier that replaces Anthropic image blocks with an `[Unsupported Image]` placeholder when the routed model is text-only (declared, or detected by a built-in model-name heuristic) or the upstream rejects image input, so conversations are not interrupted. The settings page provides a toggle for this fallback, plus a separate toggle for the heuristic detection (which can be turned off to avoid misjudging multimodal models).
|
||||
|
||||
### ZenMux Token Plan Provider
|
||||
|
||||
Added ZenMux as a Token Plan Coding Plan provider. You can manually enter its API key and base URL in the usage-script modal, and it renders used / quota in USD (#2709).
|
||||
|
||||
### CherryIN Preset
|
||||
|
||||
Added the CherryIN aggregator gateway as a quick-config preset across all 7 managed apps — Claude Code / Claude Desktop / OpenClaw / Hermes use the Anthropic-format endpoint (open.cherryin.net), OpenCode uses `@ai-sdk/anthropic` (`/v1`), Codex uses the OpenAI-compatible endpoint, and Gemini CLI uses the Gemini-compatible endpoint — with the official brand icon, placed next to AiHubMix (#3643).
|
||||
|
||||
### Codex CLI Reachability Endpoint `/v1/models`
|
||||
|
||||
The local proxy now responds to `GET /v1/models`, which Codex CLI probes at startup, returning the CC Switch-managed Codex model catalog. A stale-catalog guard was added: it parses the live `config.toml` and only serves the catalog when `model_catalog_json` still points at the CC Switch-owned catalog file, avoiding exposing a previous provider's leftover catalog to Codex (#3818).
|
||||
|
||||
### Codex Chat File and Audio Attachments
|
||||
|
||||
Codex's Responses→Chat conversion now maps `input_file` parts (carrying `file_id` or inline `file_data`) and `input_audio` parts into their Chat Completions equivalents, and emits top-level `input_*` items that were previously dropped, so file and audio attachments reach Chat-only Codex upstreams.
|
||||
|
||||
---
|
||||
|
||||
## Changed
|
||||
|
||||
### Usage Dashboard Hero Redesign
|
||||
|
||||
Rearranged the Usage Dashboard hero and summary cards into a more compact layout, consolidating the real-token total, request count, and cost into a single top row (#3426).
|
||||
|
||||
### SSSAiCode Endpoint Refresh
|
||||
|
||||
Updated the SSSAiCode preset's website, signup, and API base URLs to the `sssaicodeapi.com` domain, and refreshed its candidate endpoint nodes (default `node-hk.sssaicodeapi.com`, plus `node-hk.sssaiapi.com` and `node-cf.sssaicodeapi.com`) across all 7 app presets.
|
||||
|
||||
---
|
||||
|
||||
## Fixed
|
||||
|
||||
### Codex Chat Stream Truncation Detection
|
||||
|
||||
When a Chat Completions upstream ends a stream without a `finish_reason` or `[DONE]`, CC Switch no longer treats it as a normal completion: it finalizes normally only when the stream truly ended; emits an incomplete (`max_output_tokens`) response when partial output was produced; and emits a failed `stream_truncated` event when nothing was produced. Late-arriving reasoning is also backfilled onto still-active streaming tool calls.
|
||||
|
||||
### Codex Chat `tool_choice` Without Tools
|
||||
|
||||
The Responses→Chat conversion now drops `tool_choice` and `parallel_tool_calls` when the final tools array is missing or empty (including when all tools are filtered out), avoiding 503/400 errors from strict OpenAI-compatible upstreams (vLLM, enterprise gateways) with "When using `tool_choice`, `tools` must be set." (#3640).
|
||||
|
||||
### Codex Custom Tool Metadata Preserved
|
||||
|
||||
Custom Codex tools (such as the freeform `apply_patch` tool) now embed their full original definition — including format and grammar metadata — as a compact, order-stable JSON block in the generated Chat function description, instead of being replaced with a generic placeholder, so they remain usable on Chat Completions upstreams (#3644).
|
||||
|
||||
### Codex Chat Usage Missing `reasoning_tokens`
|
||||
|
||||
The Chat→Responses usage conversion now always includes `output_tokens_details.reasoning_tokens` (defaulting to 0), even when a provider omits `completion_tokens_details` or returns a non-object, satisfying Codex CLI's strict requirement and avoiding repeated response-parse failures and retries (#3514).
|
||||
|
||||
### Cross-Turn Reasoning for Codex Custom / Search Tools
|
||||
|
||||
The cross-turn reasoning cache in Codex Chat history now covers the full tool-call set (`function_call`, `custom_tool_call`, `tool_search_call`) and their outputs, not just plain function calls, so `apply_patch` and tool-search calls keep their own `reasoning_content` when restored via `previous_response_id`.
|
||||
|
||||
### Ephemeral Port (port 0) Resolution
|
||||
|
||||
When the proxy is configured to listen on port 0 (OS-assigned), takeover now starts the proxy first to obtain the real port before writing live configs and the database, avoiding client URLs pointing at an invalid `:0` address; if no concrete port has been resolved yet, the Claude Desktop gateway URL is rejected outright.
|
||||
|
||||
### Proxy Placeholder Backup / Restore Loop
|
||||
|
||||
If a previous proxy stop failed to restore the original live config and left proxy placeholders in live, taking over again no longer overwrites the good backup with the proxy config, and restore no longer writes the placeholder back to live: both paths detect the placeholder state and rebuild live from the current provider as the source of truth, fixing cases where the proxy toggle became a no-op and the client was pinned to the local proxy address (#3689).
|
||||
|
||||
### Provider Switching Wrongly Blocked During Proxy Takeover
|
||||
|
||||
During local routing takeover, only providers explicitly classified as official are now blocked from switching, instead of also disabling custom providers whose endpoint lives in meta or whose fields are simply unfilled. The disabled "Enable" button now shows a lighter hint tooltip instead of the previous red "Blocked" badge.
|
||||
|
||||
### localhost Listen Address Normalization
|
||||
|
||||
When saving the proxy with a listen address of `localhost`, it is now normalized to `127.0.0.1` before persisting, avoiding binding inconsistencies (#3016).
|
||||
|
||||
### Anthropic `system` Message Normalization
|
||||
|
||||
For Anthropic-format providers, system-role entries inside the `messages` array are now collapsed and merged into the top-level `system` field (preserving original order and any existing top-level system), avoiding strict upstreams rejecting non-leading system messages; OpenAI Chat routing is unaffected (#3775).
|
||||
|
||||
### Claude Desktop 1M-Context Model Routing
|
||||
|
||||
Claude Desktop appends a `[1m]` marker to the model name when the 1M-context beta is active (e.g. `claude-opus-4-8[1m]`). The proxy now strips that suffix before route matching so exact, alias, legacy, and role-keyword matching all resolve correctly, fixing `route_unknown` (HTTP 400) failures when switching to a 1M model mid-conversation; the original model name is still kept in the `route_unknown` error for diagnostics.
|
||||
|
||||
### Codex 413 Error Message
|
||||
|
||||
When a Codex upstream gateway rejects an oversized request body with HTTP 413, the proxy now returns a dedicated message explaining that this is the provider's server-side body-size limit (not a CC Switch local limit), with actionable recovery steps (run `/compact`, remove large logs or inline images, or ask the provider to raise the limit), instead of echoing the upstream's raw HTML error page.
|
||||
|
||||
### Proxy Panel Error Detail
|
||||
|
||||
When toggling proxy takeover fails, the proxy panel toast now includes the specific error detail returned by the backend, instead of only a generic failure message (#3656).
|
||||
|
||||
### Copilot Infinite-Whitespace Threshold
|
||||
|
||||
Raised the streaming infinite-whitespace abort threshold from 20 to 500 consecutive whitespace characters, avoiding false aborts of legitimate tool calls whose arguments contain deeply indented code (Python, YAML, Rust, Markdown), while still catching the real Copilot infinite-whitespace bug (#2647).
|
||||
|
||||
### Subscription Tier Tray Rendering
|
||||
|
||||
Via a unified tier-to-label mapping, fixed rendering of official subscription tiers in the tray and quota display: Claude / Codex no longer drop the 7-day window, Gemini Pro / Flash / Flash-Lite tiers no longer leak raw machine names, and multi-window plans (e.g. Opus + Sonnet) now show the worst utilization instead of the first match.
|
||||
|
||||
### Inflated Claude Stream input_tokens
|
||||
|
||||
Some Anthropic-compatible streaming providers (e.g. Qwen, MiniMax) report the full context as `input_tokens` in `message_start`, double-counting the cached portion already reported separately and artificially lowering the displayed cache hit rate. The parser now prefers the smaller positive `input_tokens` from `message_delta` and adopts the paired cache counts from the same usage block; native Claude and OpenRouter-converted paths are unchanged.
|
||||
|
||||
### Zhipu Quota Query Endpoint Routing
|
||||
|
||||
The Zhipu Coding Plan quota query was hard-coded to `api.z.ai`, so users on the mainland preset (`open.bigmodel.cn`) could not retrieve usage when the international endpoint was unreachable. The quota request now routes to the host matching the user's configured base URL (#3702).
|
||||
|
||||
### MiniMax Balance API and Pricing
|
||||
|
||||
Adapted MiniMax Coding Plan quota to its new balance API (which returns remaining-percent fields instead of the usage counts the old parser relied on, which left tiers empty and the tray showing no usage), filtered out non-coding models (such as video), handled plans without a weekly limit, and added default pricing for the MiniMax M3 model (#3518).
|
||||
|
||||
### GLM Coding Plan Endpoints and Model Fetch
|
||||
|
||||
Fixed the Zhipu / Z.AI GLM Coding Plan presets to the `/api/coding/paas/v4` endpoints (covering Codex, OpenCode, OpenClaw, Hermes), and made the model-list probe query `{base}/models` first for base URLs that already end in a `/v{N}` version segment (keeping `/v1/models` as a fallback), so the "Fetch models" button no longer 404s on versioned endpoints (#3524).
|
||||
|
||||
### Codex Model Catalog Path Portability
|
||||
|
||||
Codex now writes only the relative filename `cc-switch-model-catalog.json` to `config.toml` instead of an absolute path (Codex CLI resolves it from the config directory), fixing the model catalog breaking on WSL and symlinked setups where the absolute path could not be translated (#3614).
|
||||
|
||||
### APINebula's OpenCode SDK
|
||||
|
||||
The APINebula OpenCode preset now loads `@ai-sdk/openai-compatible` instead of `@ai-sdk/openai`, so requests use the OpenAI Chat Completions format the relay expects, rather than the Responses API that fails against chat-completions-only upstreams.
|
||||
|
||||
### Windows Tray Icon Residue After Exit
|
||||
|
||||
On Windows, quitting CC Switch could leave a dead tray icon behind until the mouse passed over it. The app now explicitly removes the tray icon before exiting, so it disappears cleanly when the process ends (#3797).
|
||||
|
||||
### Windows Taskbar Icon
|
||||
|
||||
Sets an explicit Windows AppUserModelID at runtime and writes the same ID and product icon onto the installer's desktop and start-menu shortcuts, so CC Switch shows the correct icon and groups properly in the taskbar (#3457).
|
||||
|
||||
### Windows Update Check for Subdirectory Skills
|
||||
|
||||
When scanning installed skills on Windows, backslash path separators are now normalized to forward slashes, so skills nested in subdirectories (e.g. `skills/my-skill`) are matched by the update check instead of being silently skipped (#3430).
|
||||
|
||||
### macOS Input Auto-Capitalization
|
||||
|
||||
Disabled autocomplete, autocorrect, autocapitalize, and spellcheck on the shared text Input component, so macOS no longer auto-capitalizes or auto-corrects the first letter typed into configuration fields (#3626).
|
||||
|
||||
### Codex VS Code Session Previews
|
||||
|
||||
For Codex requests sent from VS Code, the session preview could show selection or open-file content instead of the real prompt when a markdown heading preceded the injected request. The backend title and frontend preview now both match the last "## My request for Codex:" heading (the IDE injects the real request as the final section), so the preview reflects the user's prompt (#3593).
|
||||
|
||||
### VS Code Wording in the Chinese UI
|
||||
|
||||
Corrected the "Apply to Claude Code plugin" description in Simplified and Traditional Chinese to write "VS Code" properly instead of "Vscode", aligning with the English and Japanese strings (#3228).
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
### User Manual Refresh
|
||||
|
||||
Refreshed the README localizations and the en / zh / ja user manuals to reflect all 7 managed apps (adding Claude Desktop and Hermes to the intro and overview copy), corrected the OpenCode config path to `~/.config/opencode/` (`opencode.json`), documented Hermes config files, updated the language docs to four languages, corrected per-app MCP / prompt / skill support, noted that export now produces a timestamped SQL backup that includes usage logs, and documented the pricing model-ID matching rules (#3411).
|
||||
|
||||
### Codex Official Auth Preservation Guide
|
||||
|
||||
Added a Chinese / English / Japanese guide explaining how to keep Codex official remote control and official plugins working while routing model traffic to third-party APIs, and linked it from the v3.16.1 release notes.
|
||||
|
||||
### README Links and Sponsor Markup
|
||||
|
||||
Updated the Release Notes links in each language README to v3.16.1, and fixed broken curly-quote characters in the README_ZH sponsor blocks so their HTML attributes render correctly (#3772).
|
||||
|
||||
---
|
||||
|
||||
## Upgrade Notes
|
||||
|
||||
### S3 and WebDAV Cloud Sync Are Mutually Exclusive
|
||||
|
||||
Cloud Sync runs only one backend at a time. Enabling S3 auto-sync disables a running WebDAV auto-sync and vice versa. If you previously used WebDAV, make sure both ends are aligned before switching to S3, so you don't assume the old backend is still backing up.
|
||||
|
||||
### Restart Codex After Editing Model Mappings
|
||||
|
||||
Codex reads `model_catalog_json` at startup. Even though this release rewrites the model catalog to a relative path and adds the `/v1/models` reachability endpoint, you still need to restart Codex after editing the model mapping table for the `/model` menu to refresh.
|
||||
|
||||
---
|
||||
|
||||
## Risk Notice
|
||||
|
||||
This release continues the risk notices from previous versions for reverse-proxy-style features.
|
||||
|
||||
**Codex OAuth reverse proxy**: using a ChatGPT subscription's Codex OAuth through a reverse proxy may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details.
|
||||
|
||||
**Codex third-party provider Chat routing**: when CC Switch local proxy converts and forwards Codex requests to third-party providers, each provider may have different requirements for billing, compliance, and data retention. Read the target provider's terms before use.
|
||||
|
||||
**Claude Desktop third-party provider proxy switching**: when CC Switch's built-in proxy gateway forwards Claude Desktop requests to third-party providers, you must also follow the target provider's billing, compliance, and data-retention terms.
|
||||
|
||||
By enabling these features, users accept the related risks. CC Switch is not responsible for account restrictions, warnings, or service suspensions caused by using these features.
|
||||
|
||||
---
|
||||
|
||||
## Thanks
|
||||
|
||||
Thanks to the following contributors for the features and fixes in v3.16.2:
|
||||
|
||||
- [#1351](https://github.com/farion1231/cc-switch/pull/1351): add S3-compatible cloud storage sync, thanks @keithyt06.
|
||||
- [#3215](https://github.com/farion1231/cc-switch/pull/3215): add OpenCode session usage sync, thanks @nothingness0db.
|
||||
- [#2709](https://github.com/farion1231/cc-switch/pull/2709): add the ZenMux Token Plan provider, thanks @Eter365.
|
||||
- [#3643](https://github.com/farion1231/cc-switch/pull/3643): add the CherryIN preset provider, thanks @zhibisora.
|
||||
- [#3818](https://github.com/farion1231/cc-switch/pull/3818): add the Codex CLI reachability `GET /v1/models` endpoint, thanks @CSberlin.
|
||||
- [#3426](https://github.com/farion1231/cc-switch/pull/3426): Usage Dashboard hero redesign, thanks @allenxu09.
|
||||
- [#3640](https://github.com/farion1231/cc-switch/pull/3640): drop `tool_choice` when tools is empty, thanks @Postroggy.
|
||||
- [#3644](https://github.com/farion1231/cc-switch/pull/3644): preserve Codex custom tool metadata in chat routing, thanks @LanternCX.
|
||||
- [#3514](https://github.com/farion1231/cc-switch/pull/3514): always include `reasoning_tokens` in Chat→Responses, thanks @yeeyzy.
|
||||
- [#3689](https://github.com/farion1231/cc-switch/pull/3689): skip backup / restore when live is already a proxy placeholder, thanks @YongmaoLuo.
|
||||
- [#3016](https://github.com/farion1231/cc-switch/pull/3016): normalize the localhost listen address, thanks @Alexlangl.
|
||||
- [#3775](https://github.com/farion1231/cc-switch/pull/3775): normalize Anthropic `system` messages, thanks @Dearli666.
|
||||
- [#3656](https://github.com/farion1231/cc-switch/pull/3656): improve error message display in the proxy panel, thanks @lzcndm.
|
||||
- [#2647](https://github.com/farion1231/cc-switch/pull/2647): raise the infinite-whitespace threshold 20 → 500, thanks @NiuBlibing.
|
||||
- [#3702](https://github.com/farion1231/cc-switch/pull/3702): route the Zhipu quota query to the configured base URL, thanks @YongmaoLuo.
|
||||
- [#3518](https://github.com/farion1231/cc-switch/pull/3518): adapt to the MiniMax new balance API and default pricing, thanks @LaoYueHanNi.
|
||||
- [#3524](https://github.com/farion1231/cc-switch/pull/3524): fix the Zhipu Coding Plan presets and model probing for versioned endpoints, thanks @makoMakoGo.
|
||||
- [#3614](https://github.com/farion1231/cc-switch/pull/3614): use a relative filename for the model catalog, thanks @steponeerror.
|
||||
- [#3797](https://github.com/farion1231/cc-switch/pull/3797): fix the Windows tray icon residue after exit, thanks @iAJue.
|
||||
- [#3457](https://github.com/farion1231/cc-switch/pull/3457): fix the Windows taskbar icon, thanks @ZhangNanNan1018.
|
||||
- [#3430](https://github.com/farion1231/cc-switch/pull/3430): normalize Windows path separators to match subdirectory skill updates, thanks @Ninthless.
|
||||
- [#3626](https://github.com/farion1231/cc-switch/pull/3626): disable macOS input auto-capitalization, thanks @ZHLHZHU.
|
||||
- [#3593](https://github.com/farion1231/cc-switch/pull/3593): fix Codex VS Code session previews, thanks @xwil1.
|
||||
- [#3228](https://github.com/farion1231/cc-switch/pull/3228): align the VS Code wording in the Chinese UI, thanks @Games55k.
|
||||
- [#3411](https://github.com/farion1231/cc-switch/pull/3411): refresh the user manual to reflect current app support, thanks @makoMakoGo.
|
||||
- [#3772](https://github.com/farion1231/cc-switch/pull/3772): fix README release-note links and sponsor markup, thanks @null-easy.
|
||||
|
||||
Thanks also to everyone who reported Codex Chat routing, local proxy takeover, usage statistics, and platform compatibility issues after v3.16.1. Many of these fixes came directly from real-world reproduction details.
|
||||
|
||||
---
|
||||
|
||||
## Download & Install
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) and download the build for your system.
|
||||
|
||||
### System Requirements
|
||||
|
||||
| System | Minimum Version | Architecture |
|
||||
| ------- | ------------------------ | ----------------------------------- |
|
||||
| Windows | Windows 10 and later | x64 |
|
||||
| macOS | macOS 12 (Monterey)+ | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | See table below | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| File | Description |
|
||||
| ---------------------------------------- | ------------------------------------------------ |
|
||||
| `CC-Switch-v3.16.2-Windows.msi` | **Recommended** - MSI installer with auto-update |
|
||||
| `CC-Switch-v3.16.2-Windows-Portable.zip` | Portable build, unzip and run |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| -------------------------------- | ----------------------------------------------------- |
|
||||
| `CC-Switch-v3.16.2-macOS.dmg` | **Recommended** - DMG installer, drag to Applications |
|
||||
| `CC-Switch-v3.16.2-macOS.zip` | Unzip and drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.16.2-macOS.tar.gz` | For Homebrew install and auto-update |
|
||||
|
||||
Homebrew install:
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Upgrade:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Linux assets are available for both **x86_64** and **ARM64** (`aarch64`). Choose the file whose architecture tag matches your machine's `uname -m` output:
|
||||
|
||||
- `CC-Switch-v3.16.2-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- `CC-Switch-v3.16.2-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| Distribution | Recommended Format | Install Command |
|
||||
| --------------------------------------- | ------------------ | --------------------------------------------------------------------- |
|
||||
| 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` | Make executable and run directly, or use AUR |
|
||||
| Other distributions / unsure | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
@@ -0,0 +1,347 @@
|
||||
# CC Switch v3.16.2
|
||||
|
||||
> v3.16.1 の Codex 安定性パッチに続き、本リリースはデータの可搬性と用量の可観測性の拡張を主眼としています。S3 互換クラウド同期、OpenCode セッション用量同期、公式サブスクリプション残量テンプレートを追加し、Codex がサードパーティプロバイダーを Chat Completions ルーティングする際の堅牢性を引き続き強化しました。あわせて Windows / macOS のプラットフォーム問題を一括修正し、CherryIN・ZenMux プロバイダーを追加し、3 言語のユーザーマニュアルを全面的に刷新しました。
|
||||
|
||||
**[English →](v3.16.2-en.md) | [中文 →](v3.16.2-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## 利用ガイド
|
||||
|
||||
本リリースではクラウド同期の S3 バックエンドと、より多くの用量統計ソースを追加しました。利用したい場合は、まず以下のドキュメントをご覧ください：
|
||||
|
||||
- **[設定](../user-manual/ja/1-getting-started/1.5-settings.md)**: 設定ページでクラウド同期（WebDAV / S3 互換ストレージ）を構成し、プロバイダー、MCP、プロンプト、スキルなどの設定を複数デバイス間でバックアップ・復元します。
|
||||
- **[用量統計](../user-manual/ja/4-proxy/4.4-usage.md)**: 用量ダッシュボードのデータソース（プロキシログ、Codex / Gemini / OpenCode セッション同期）と統計の数え方を確認できます。
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## 唯一の公式チャネル（必ずお読みください）
|
||||
>
|
||||
> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。本ソフトウェアは下記の公式チャネルからのみ入手してください：
|
||||
>
|
||||
> | チャネル | 唯一の公式 |
|
||||
> | ------------ | ------------------------------------------------------------------------------ |
|
||||
> | 公式サイト | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | 作者 | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は直ちに操作を中止し、GitHub Issues からご報告ください。
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.16.2 は v3.16.1 に続くメンテナンスアップデートです。前リリースでは Codex 公式認証とローカルルーティングのテイクオーバーのセキュリティ問題に集中しましたが、本リリースは 2 点に重きを置いています。1 つ目はデータの可搬性と用量の可観測性の拡張で、S3 互換クラウド同期（WebDAV に並ぶ 2 つ目のクラウドバックアップバックエンド）、OpenCode セッション用量同期、公式サブスクリプション向けの残量統計テンプレートを追加しました。2 つ目は、Codex がサードパーティプロバイダーを Chat Completions ルーティングする際に露呈したエッジケースの継続的な改善で、ストリーム切断の判定、tools が空のときの `tool_choice`、カスタムツールのメタデータ、推論トークン統計、ファイル / 音声添付の変換などです。
|
||||
|
||||
本リリースではローカルプロキシの堅牢性に関する問題（一時ポートの解決、テイクオーバーのプレースホルダー復元ループ、Anthropic `system` メッセージの正規化、上流 413 の文言、Claude Desktop の `[1m]` モデルルーティング）を一括修正し、いくつかの Windows / macOS のプラットフォーム体験の問題に対処し、CherryIN・ZenMux の 2 プロバイダーを追加し、3 言語のユーザーマニュアルを全面的に刷新しました。
|
||||
|
||||
**リリース日**: 2026-06-07
|
||||
|
||||
**Stats**: 41 commits | 132 files changed | +11,116 / -1,636 lines
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **S3 互換クラウド同期**: WebDAV に並ぶ 2 つ目のクラウドバックアップバックエンドとして S3 互換オブジェクトストレージを追加。AWS S3、MinIO、Cloudflare R2、Alibaba Cloud OSS、Tencent Cloud COS、Huawei OBS などのワンクリックプリセットを内蔵します。
|
||||
- **より多くの用量データソース**: OpenCode セッション用量同期と、Claude / Codex / Gemini 公式プロバイダー向けの公式サブスクリプション残量テンプレート（明示的なトグル、デフォルトでオフ）を追加しました。
|
||||
- **Codex Chat Completions ルーティングの継続的な強化**: ストリーム切断の誤判定、tools が空のときの `tool_choice` 拒否、カスタムツールメタデータの欠落、推論トークン統計の欠落を修正し、ファイル / 音声添付の変換と `/v1/models` 到達性エンドポイントを追加しました。
|
||||
- **より堅牢なローカルプロキシ**: 一時ポート（port 0）の解決、テイクオーバーのプレースホルダー復元ループ、Anthropic `system` メッセージの正規化、上流 413 の文言、Claude Desktop の 1M コンテキストモデルルーティングを修正しました。
|
||||
- **プラットフォームとプロバイダー**: Windows のトレイ / タスクバーアイコン、サブディレクトリスキルの更新、macOS の入力自動大文字化を修正し、CherryIN・ZenMux プロバイダーを追加しました。
|
||||
|
||||
---
|
||||
|
||||
## 追加機能
|
||||
|
||||
### S3 互換クラウド同期
|
||||
|
||||
クラウド同期は WebDAV に並ぶ 2 つ目のバックエンドとして S3 互換オブジェクトストレージに対応しました。署名は自前実装の AWS Signature V4 を用い、できるだけ多くのサービスと互換性を持たせています。設定ページでは AWS S3、MinIO、Cloudflare R2、Alibaba Cloud OSS、Tencent Cloud COS、Huawei OBS、およびカスタム endpoint のワンクリックプリセットを提供し、接続テスト、手動アップロード / ダウンロード、設定変更時の自動同期（providers、endpoint、MCP、プロンプト、スキル、設定、プロキシなどの設定テーブル。用量ログのような高頻度書き込みデータは**含みません**）に対応します。S3 同期を有効化すると、実行中の WebDAV 同期は停止し、その逆も同様です（#1351）。
|
||||
|
||||
### OpenCode セッション用量同期
|
||||
|
||||
OpenCode を用量統計のソースとして追加しました。OpenCode のローカル SQLite データベースからメッセージごとの token、コスト、モデルのデータを読み取り、用量レコードへインポートします。専用の「OpenCode」アプリフィルタタブと「OpenCode Session」データソースラベルを備えます。データベースパスは `OPENCODE_DB` と `XDG_DATA_HOME` を尊重し（全プラットフォームで既定は `~/.local/share/opencode`）、完了済みのメッセージのみをインポートし、新鮮度判定で WAL ファイルも含めるため、書き込み直後のセッションがスキップされません（#3215）。
|
||||
|
||||
### 公式サブスクリプション残量テンプレート
|
||||
|
||||
用量照会を発行する IP とアプリ内リクエストを発行する IP が異なるとアカウント停止のリスクがある、という一部ユーザーの懸念を受けて、Claude / Codex / Gemini 公式プロバイダー向けに、CLI / OAuth 認証情報でプラン残量を照会する明示的・任意の「公式サブスクリプション」用量テンプレートを追加し、これまでの公式プロバイダーに対する暗黙の自動照会を置き換えました。このテンプレートはデフォルトでオフで、用量スクリプトのモーダルから有効化でき、更新間隔を設定できます。本機能を利用する際は、プロキシの TUN モードを有効化することを推奨します。
|
||||
|
||||
### テキスト専用モデルの画像フォールバック整流器
|
||||
|
||||
ルーティング先のモデルがテキスト専用（明示的な宣言、または内蔵のモデル名ヒューリスティックで判定）の場合、または上流が画像入力を拒否する場合に、Anthropic の画像ブロックを `[Unsupported Image]` プレースホルダーへ置き換えるプロキシ整流器を追加し、会話の中断を防ぎます。設定ページにこのフォールバックのトグルを用意し、さらにヒューリスティック検出を制御する別のトグル（マルチモーダルモデルの誤判定を避けるためオフにできます）を用意しました。
|
||||
|
||||
### ZenMux Token Plan プロバイダー
|
||||
|
||||
ZenMux を Token Plan 系の Coding Plan プロバイダーとして追加しました。用量スクリプトのモーダルで API key と base URL を手動入力でき、使用量 / 残量を米ドル建てでリッチに表示します（#2709）。
|
||||
|
||||
### CherryIN プリセット
|
||||
|
||||
CherryIN アグリゲーターゲートウェイをクイック設定プリセットとして、受管 7 アプリすべてに追加しました。Claude Code / Claude Desktop / OpenClaw / Hermes は Anthropic 形式の endpoint（open.cherryin.net）、OpenCode は `@ai-sdk/anthropic`（`/v1`）、Codex は OpenAI 互換 endpoint、Gemini CLI は Gemini 互換 endpoint を使用します。公式ブランドアイコン付きで、AiHubMix の隣に配置されます（#3643）。
|
||||
|
||||
### Codex CLI 到達性エンドポイント `/v1/models`
|
||||
|
||||
ローカルプロキシは、Codex CLI が起動時にプローブする `GET /v1/models` に応答し、CC Switch が管理する Codex モデルカタログを返すようになりました。あわせて古いカタログのガードを追加: live の `config.toml` を解析し、`model_catalog_json` が CC Switch 所有のカタログファイルを指している場合のみ提供することで、前のプロバイダーが残したカタログを Codex に見せてしまうことを防ぎます（#3818）。
|
||||
|
||||
### Codex Chat のファイル・音声添付
|
||||
|
||||
Codex の Responses→Chat 変換は、`input_file`（`file_id` またはインライン `file_data` を持つ）と `input_audio` のコンテンツ部分を Chat Completions の対応形態へマッピングし、これまで破棄されていたトップレベルの `input_*` 項目も出力するようになりました。これにより、ファイルと音声の添付が Chat のみ対応の Codex 上流へ届きます。
|
||||
|
||||
---
|
||||
|
||||
## 変更
|
||||
|
||||
### 用量ダッシュボードのヒーロー再設計
|
||||
|
||||
用量ダッシュボードのヒーロー領域とサマリーカードをよりコンパクトなレイアウトに再構成し、実トークン総量、リクエスト数、コストを最上部の 1 行にまとめました（#3426）。
|
||||
|
||||
### SSSAiCode エンドポイント刷新
|
||||
|
||||
SSSAiCode プリセットの公式サイト、登録、API base URL を `sssaicodeapi.com` ドメインへ更新し、endpoint 候補ノード（既定 `node-hk.sssaicodeapi.com`、ほかに `node-hk.sssaiapi.com` と `node-cf.sssaicodeapi.com`）を全 7 アプリのプリセットで刷新しました。
|
||||
|
||||
---
|
||||
|
||||
## 修正
|
||||
|
||||
### Codex Chat ストリーム切断の判定
|
||||
|
||||
Chat Completions 上流が `finish_reason` も `[DONE]` もなくストリームを終了した場合、CC Switch はこれを正常完了として扱わなくなりました: 本当に終了したときのみ正常に締め、部分的な出力があった場合は incomplete（`max_output_tokens`）レスポンスを、何も出力されなかった場合は失敗 `stream_truncated` イベントを発行します。遅れて届いた推論も、まだアクティブなストリーミングのツール呼び出しへバックフィルされます。
|
||||
|
||||
### tools が空のときの Codex Chat `tool_choice`
|
||||
|
||||
Responses→Chat 変換は、最終的な tools 配列が欠落または空（すべてのツールがフィルタで除外された場合を含む）のときに `tool_choice` と `parallel_tool_calls` を破棄するようになりました。これにより、厳格な OpenAI 互換上流（vLLM、エンタープライズゲートウェイ）が「When using `tool_choice`, `tools` must be set.」で 503/400 を返すことを避けます（#3640）。
|
||||
|
||||
### Codex カスタムツールメタデータの保持
|
||||
|
||||
カスタム Codex ツール（自由形式の `apply_patch` ツールなど）は、汎用プレースホルダーへ置き換えられる代わりに、format と grammar のメタデータを含む完全な元定義を、生成される Chat 関数の説明にコンパクトで順序の安定した JSON ブロックとして埋め込むようになりました。これにより Chat Completions 上流でも引き続き利用できます（#3644）。
|
||||
|
||||
### Codex Chat 用量の `reasoning_tokens` 欠落
|
||||
|
||||
Chat→Responses の用量変換は、プロバイダーが `completion_tokens_details` を省略したり非オブジェクトを返したりしても、常に `output_tokens_details.reasoning_tokens`（既定 0）を含めるようになりました。これにより Codex CLI の厳格な要件を満たし、レスポンス解析の失敗と再試行の繰り返しを避けます（#3514）。
|
||||
|
||||
### Codex カスタム / 検索ツールのターン跨ぎ推論
|
||||
|
||||
Codex Chat 履歴のターン跨ぎ推論キャッシュが、通常の関数呼び出しだけでなく、ツール呼び出しの全集合（`function_call`、`custom_tool_call`、`tool_search_call`）とその出力をカバーするようになりました。これにより `apply_patch` とツール検索の呼び出しは、`previous_response_id` で復元されるときにそれぞれの `reasoning_content` を保持します。
|
||||
|
||||
### 一時ポート（port 0）の解決
|
||||
|
||||
プロキシが port 0（OS 割り当て）でリッスンするよう構成されている場合、テイクオーバーはまずプロキシを起動して実際のポートを取得してから live 設定とデータベースへ書き込むようになり、クライアント URL が無効な `:0` アドレスを指すことを避けます。具体的なポートがまだ解決されていない場合、Claude Desktop のゲートウェイ URL は拒否されます。
|
||||
|
||||
### プロキシプレースホルダーのバックアップ / 復元ループ
|
||||
|
||||
前回プロキシ停止時に元の live 設定の復元に失敗し、プロキシプレースホルダーが live に残ってしまった場合でも、再度テイクオーバーする際に正常なバックアップをプロキシ設定で上書きすることはなくなり、復元時にプレースホルダーを live へ書き戻すこともなくなりました: いずれの経路もプレースホルダー状態を検知し、現在のプロバイダーを信頼できる情報源として live を再構築します。これにより、プロキシのトグルが何もしない状態になり、クライアントがローカルプロキシアドレスに固定されてしまう問題を修正しました（#3689）。
|
||||
|
||||
### プロキシテイクオーバー中のプロバイダー切り替え誤ブロック
|
||||
|
||||
ローカルルーティングのテイクオーバー中、明示的に official と分類されたプロバイダーのみが切り替えをブロックされるようになり、endpoint が meta に存在する、またはフィールドが未入力なだけのカスタムプロバイダーまで無効化することはなくなりました。無効化された「有効化」ボタンは、以前の赤い「ブロック済み」バッジの代わりに、より軽いヒントのツールチップを表示します。
|
||||
|
||||
### localhost リッスンアドレスの正規化
|
||||
|
||||
プロキシのリッスンアドレスを `localhost` で保存した場合、永続化前に `127.0.0.1` へ正規化されるようになり、バインドの不整合を避けます（#3016）。
|
||||
|
||||
### Anthropic `system` メッセージの正規化
|
||||
|
||||
Anthropic 形式のプロバイダーでは、`messages` 配列内の system ロールのエントリを折りたたんでトップレベルの `system` フィールドへマージするようになり（元の順序と既存のトップレベル system を保持）、厳格な上流が先頭以外の system メッセージを拒否することを避けます。OpenAI Chat ルーティングは影響を受けません（#3775）。
|
||||
|
||||
### Claude Desktop 1M コンテキストモデルルーティング
|
||||
|
||||
Claude Desktop は 1M コンテキスト beta が有効なとき、モデル名に `[1m]` マーカーを付加します（例: `claude-opus-4-8[1m]`）。プロキシはルーティング照合の前にこの接尾辞を除去するようになり、完全一致・エイリアス・旧名・ロールキーワードの照合がすべて正しく解決されます。これにより、会話の途中で 1M モデルへ切り替えたときの `route_unknown`（HTTP 400）の失敗を修正しました。診断用に、`route_unknown` エラーには元のモデル名を引き続き保持します。
|
||||
|
||||
### Codex 413 エラーの文言
|
||||
|
||||
Codex 上流ゲートウェイが過大なリクエストボディを HTTP 413 で拒否したとき、プロキシはこれが CC Switch のローカル制限ではなくプロバイダーのサーバー側ボディサイズ制限であることを説明する専用メッセージを返し、実行可能な回復手順（`/compact` の実行、大きなログやインライン画像の削除、プロバイダーへの上限引き上げ依頼）を提示するようになりました。上流の生の HTML エラーページをそのまま返すことはなくなりました。
|
||||
|
||||
### プロキシパネルのエラー詳細
|
||||
|
||||
プロキシのテイクオーバー切り替えに失敗したとき、プロキシパネルのトーストは、汎用の失敗メッセージだけでなく、バックエンドが返す具体的なエラー詳細を含めるようになりました（#3656）。
|
||||
|
||||
### Copilot 無限空白検出のしきい値
|
||||
|
||||
ストリーミングの無限空白の中断しきい値を、連続する空白文字 20 から 500 へ引き上げました。これにより、引数に深くインデントされたコード（Python、YAML、Rust、Markdown）を含む正当なツール呼び出しが誤って中断されることを避けつつ、本物の Copilot 無限空白バグは引き続き捕捉します（#2647）。
|
||||
|
||||
### サブスクリプション階層のトレイ表示
|
||||
|
||||
統一された階層→ラベルのマッピングにより、トレイと残量表示における公式サブスクリプション階層の表示を修正しました: Claude / Codex は 7 日ウィンドウを取りこぼさなくなり、Gemini Pro / Flash / Flash-Lite の階層は生のマシン名を漏らさなくなり、複数ウィンドウのプラン（Opus + Sonnet など）は最初の一致ではなく最悪の利用率を表示するようになりました。
|
||||
|
||||
### Claude ストリームの input_tokens 過大計上
|
||||
|
||||
一部の Anthropic 互換ストリーミングプロバイダー（Qwen、MiniMax など）は `message_start` で完全なコンテキストを `input_tokens` として報告し、別途報告済みのキャッシュ分を二重計上して、表示上のキャッシュヒット率を不当に低下させていました。パーサーは `message_delta` のより小さい正の `input_tokens` を優先し、同じ usage ブロックのキャッシュカウントを採用するようになりました。ネイティブ Claude と OpenRouter 変換の経路は変更ありません。
|
||||
|
||||
### 智譜（Zhipu）残量照会の endpoint ルーティング
|
||||
|
||||
智譜 Coding Plan の残量照会は `api.z.ai` にハードコードされていたため、本土プリセット（`open.bigmodel.cn`）のユーザーは国際 endpoint が到達不能なときに用量を取得できませんでした。残量リクエストは、ユーザーが構成した base URL に一致するホストへルーティングされるようになりました（#3702）。
|
||||
|
||||
### MiniMax 残量 API と価格
|
||||
|
||||
MiniMax Coding Plan の残量を新しい残量 API に対応させました（新 API は、旧パーサーが依存していた用量カウント（階層が空になりトレイに用量が表示されなくなる）の代わりに、残り割合のフィールドを返します）。非コーディングモデル（動画など）を除外し、週次上限のないプランに対応し、MiniMax M3 モデルの既定価格を追加しました（#3518）。
|
||||
|
||||
### GLM Coding Plan の endpoint とモデル取得
|
||||
|
||||
智譜 / Z.AI の GLM Coding Plan プリセットを `/api/coding/paas/v4` endpoint に修正し（Codex、OpenCode、OpenClaw、Hermes をカバー）、すでに `/v{N}` のバージョンセグメントで終わる base URL については、モデル一覧プローブが `{base}/models` を先に照会するようにしました（`/v1/models` はフォールバックとして保持）。これにより「モデル取得」ボタンがバージョン付き endpoint で 404 にならなくなりました（#3524）。
|
||||
|
||||
### Codex モデルカタログパスの可搬性
|
||||
|
||||
Codex は `config.toml` に絶対パスではなく相対ファイル名 `cc-switch-model-catalog.json` のみを書き込むようになりました（Codex CLI は設定ディレクトリから解決します）。これにより、絶対パスを変換できない WSL やシンボリックリンク環境でモデルカタログが壊れる問題を修正しました（#3614）。
|
||||
|
||||
### APINebula の OpenCode SDK
|
||||
|
||||
APINebula の OpenCode プリセットは `@ai-sdk/openai` ではなく `@ai-sdk/openai-compatible` を読み込むようになり、chat-completions のみ対応の上流で失敗する Responses API ではなく、このリレーが期待する OpenAI Chat Completions 形式でリクエストを行います。
|
||||
|
||||
### Windows 終了後のトレイアイコン残留
|
||||
|
||||
Windows では CC Switch を終了すると、マウスを重ねるまで無効なトレイアイコンが残ることがありました。アプリは終了前にトレイアイコンを明示的に削除するようになり、プロセス終了とともにきれいに消えます（#3797）。
|
||||
|
||||
### Windows タスクバーアイコン
|
||||
|
||||
実行時に Windows AppUserModelID を明示的に設定し、インストーラーが生成するデスクトップとスタートメニューのショートカットに同じ ID と製品アイコンを書き込みます。これにより CC Switch がタスクバーで正しいアイコンを表示し、正しくグループ化されます（#3457）。
|
||||
|
||||
### Windows サブディレクトリスキルの更新チェック
|
||||
|
||||
Windows でインストール済みスキルをスキャンする際、バックスラッシュのパス区切りをスラッシュへ正規化するようになり、サブディレクトリにネストされたスキル（`skills/my-skill` など）が静かにスキップされず、更新チェックで一致するようになりました（#3430）。
|
||||
|
||||
### macOS の入力自動大文字化
|
||||
|
||||
共有のテキスト Input コンポーネントで autocomplete、autocorrect、autocapitalize、spellcheck を無効化し、macOS が設定フィールドに入力された最初の文字を自動で大文字化・自動修正しないようにしました（#3626）。
|
||||
|
||||
### Codex VS Code セッションプレビュー
|
||||
|
||||
VS Code から送信された Codex リクエストでは、注入されたリクエストの前に markdown 見出しがあると、セッションプレビューが本当のプロンプトではなく選択範囲や開いているファイルの内容を表示することがありました。バックエンドのタイトルとフロントエンドのプレビューはいずれも、最後の「## My request for Codex:」見出しに一致するようになり（IDE は本当のリクエストを最後のセクションとして注入します）、プレビューがユーザーのプロンプトを反映します（#3593）。
|
||||
|
||||
### 中国語 UI の VS Code 表記
|
||||
|
||||
簡体字・繁体字中国語の「Claude Code プラグインに適用」の説明を、「Vscode」ではなく正しく「VS Code」と表記するよう修正し、英語・日本語の文言と揃えました（#3228）。
|
||||
|
||||
---
|
||||
|
||||
## ドキュメント
|
||||
|
||||
### ユーザーマニュアル刷新
|
||||
|
||||
README の各言語版と en / zh / ja のユーザーマニュアルを刷新し、受管 7 アプリすべてを反映（紹介と概要の文面に Claude Desktop と Hermes を追加）、OpenCode の設定パスを `~/.config/opencode/`（`opencode.json`）に修正、Hermes の設定ファイルの説明を追加、言語ドキュメントを 4 言語に更新、アプリごとの MCP / プロンプト / スキルの対応状況を訂正、エクスポートがタイムスタンプ付きで用量ログを含む SQL バックアップを生成することを記載、価格モデル ID のマッチングルールを追記しました（#3411）。
|
||||
|
||||
### Codex 公式認証保持ガイド
|
||||
|
||||
モデル通信をサードパーティ API へ切り替えつつ、Codex の公式リモート操作と公式プラグインを動作させ続ける方法を説明する中国語 / 英語 / 日本語のガイドを追加し、v3.16.1 のリリースノートからリンクしました。
|
||||
|
||||
### README リンクとスポンサー表記
|
||||
|
||||
各言語の README のリリースノートリンクを v3.16.1 に更新し、README_ZH のスポンサーブロックで壊れていた曲線引用符文字を修正して、HTML 属性が正しくレンダリングされるようにしました（#3772）。
|
||||
|
||||
---
|
||||
|
||||
## アップグレード時の注意
|
||||
|
||||
### S3 と WebDAV のクラウド同期は排他
|
||||
|
||||
クラウド同期は同時に 1 つのバックエンドのみを実行します。S3 自動同期を有効化すると、実行中の WebDAV 自動同期は停止し、その逆も同様です。以前 WebDAV を使っていた場合は、S3 へ切り替える前に両端のデータが揃っていることを確認し、旧バックエンドがまだバックアップしていると誤解しないようにしてください。
|
||||
|
||||
### モデルマッピング変更後は Codex の再起動が必要
|
||||
|
||||
Codex は起動時に `model_catalog_json` を読み込みます。本リリースでモデルカタログを相対パスへ書き換え、`/v1/models` 到達性エンドポイントを追加しましたが、モデルマッピングテーブルを変更した後は、`/model` メニューを更新するために Codex の再起動が必要です。
|
||||
|
||||
---
|
||||
|
||||
## リスク通知
|
||||
|
||||
本リリースは、リバースプロキシ系機能に関する以前のリスク通知を引き続き適用します。
|
||||
|
||||
**Codex OAuth リバースプロキシ**: ChatGPT サブスクリプションの Codex OAuth をリバースプロキシ経由で使用すると、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 release notes](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
|
||||
|
||||
**Codex サードパーティプロバイダー Chat ルーティング**: CC Switch ローカルプロキシで Codex リクエストを変換し、サードパーティプロバイダーへ転送する場合、課金、コンプライアンス、データ保持に関する制約はプロバイダーごとに異なります。利用前に対象プロバイダーの利用規約を確認してください。
|
||||
|
||||
**Claude Desktop サードパーティプロバイダープロキシ切り替え**: CC Switch 内蔵のプロキシゲートウェイで Claude Desktop のリクエストをサードパーティプロバイダーへ転送する場合も、対象プロバイダーの課金、コンプライアンス、データ保持に関する規約に従う必要があります。
|
||||
|
||||
上記機能を有効化したユーザーは、関連するリスクを自ら負うものとします。CC Switch は、これらの機能の利用によって発生したアカウント制限、警告、サービス停止について責任を負いません。
|
||||
|
||||
---
|
||||
|
||||
## 謝辞
|
||||
|
||||
v3.16.2 で機能と修正を届けてくださった以下のコントリビューターに感謝します：
|
||||
|
||||
- [#1351](https://github.com/farion1231/cc-switch/pull/1351): S3 互換クラウドストレージ同期を追加、@keithyt06 に感謝。
|
||||
- [#3215](https://github.com/farion1231/cc-switch/pull/3215): OpenCode セッション用量同期を追加、@nothingness0db に感謝。
|
||||
- [#2709](https://github.com/farion1231/cc-switch/pull/2709): ZenMux Token Plan プロバイダーを追加、@Eter365 に感謝。
|
||||
- [#3643](https://github.com/farion1231/cc-switch/pull/3643): CherryIN プリセットプロバイダーを追加、@zhibisora に感謝。
|
||||
- [#3818](https://github.com/farion1231/cc-switch/pull/3818): Codex CLI 到達性確認用の `GET /v1/models` エンドポイントを追加、@CSberlin に感謝。
|
||||
- [#3426](https://github.com/farion1231/cc-switch/pull/3426): 用量ダッシュボードのヒーロー再設計、@allenxu09 に感謝。
|
||||
- [#3640](https://github.com/farion1231/cc-switch/pull/3640): tools が空のとき `tool_choice` を破棄、@Postroggy に感謝。
|
||||
- [#3644](https://github.com/farion1231/cc-switch/pull/3644): Chat ルーティングで Codex カスタムツールメタデータを保持、@LanternCX に感謝。
|
||||
- [#3514](https://github.com/farion1231/cc-switch/pull/3514): Chat→Responses で常に `reasoning_tokens` を含める、@yeeyzy に感謝。
|
||||
- [#3689](https://github.com/farion1231/cc-switch/pull/3689): live がすでにプロキシプレースホルダーのときバックアップ / 復元をスキップ、@YongmaoLuo に感謝。
|
||||
- [#3016](https://github.com/farion1231/cc-switch/pull/3016): localhost リッスンアドレスを正規化、@Alexlangl に感謝。
|
||||
- [#3775](https://github.com/farion1231/cc-switch/pull/3775): Anthropic `system` メッセージを正規化、@Dearli666 に感謝。
|
||||
- [#3656](https://github.com/farion1231/cc-switch/pull/3656): プロキシパネルのエラー表示を改善、@lzcndm に感謝。
|
||||
- [#2647](https://github.com/farion1231/cc-switch/pull/2647): 無限空白検出のしきい値を 20 → 500 へ引き上げ、@NiuBlibing に感謝。
|
||||
- [#3702](https://github.com/farion1231/cc-switch/pull/3702): 智譜の残量照会を構成済み base URL へルーティング、@YongmaoLuo に感謝。
|
||||
- [#3518](https://github.com/farion1231/cc-switch/pull/3518): MiniMax の新残量 API と既定価格に対応、@LaoYueHanNi に感謝。
|
||||
- [#3524](https://github.com/farion1231/cc-switch/pull/3524): 智譜 Coding Plan プリセットとバージョン付き endpoint のモデル探索を修正、@makoMakoGo に感謝。
|
||||
- [#3614](https://github.com/farion1231/cc-switch/pull/3614): モデルカタログを相対ファイル名に変更、@steponeerror に感謝。
|
||||
- [#3797](https://github.com/farion1231/cc-switch/pull/3797): Windows 終了後のトレイアイコン残留を修正、@iAJue に感謝。
|
||||
- [#3457](https://github.com/farion1231/cc-switch/pull/3457): Windows タスクバーアイコンを修正、@ZhangNanNan1018 に感謝。
|
||||
- [#3430](https://github.com/farion1231/cc-switch/pull/3430): Windows のパス区切りを正規化してサブディレクトリスキルの更新に対応、@Ninthless に感謝。
|
||||
- [#3626](https://github.com/farion1231/cc-switch/pull/3626): macOS の入力自動大文字化を無効化、@ZHLHZHU に感謝。
|
||||
- [#3593](https://github.com/farion1231/cc-switch/pull/3593): Codex VS Code セッションプレビューを修正、@xwil1 に感謝。
|
||||
- [#3228](https://github.com/farion1231/cc-switch/pull/3228): 中国語 UI の VS Code 表記を揃える、@Games55k に感謝。
|
||||
- [#3411](https://github.com/farion1231/cc-switch/pull/3411): 現行のアプリ対応を反映してユーザーマニュアルを刷新、@makoMakoGo に感謝。
|
||||
- [#3772](https://github.com/farion1231/cc-switch/pull/3772): README のリリースノートリンクとスポンサー表記を修正、@null-easy に感謝。
|
||||
|
||||
v3.16.1 リリース後に Codex Chat ルーティング、ローカルプロキシのテイクオーバー、用量統計、プラットフォーム互換性の問題を報告してくださったすべてのユーザーにも感謝します。今回の多くの修正は、実際の利用シーンから得られた再現情報に基づいています。
|
||||
|
||||
---
|
||||
|
||||
## ダウンロードとインストール
|
||||
|
||||
[Releases](https://github.com/farion1231/cc-switch/releases/latest) から、お使いのシステムに対応するビルドをダウンロードしてください。
|
||||
|
||||
### システム要件
|
||||
|
||||
| システム | 最低バージョン | アーキテクチャ |
|
||||
| -------- | ------------------------ | ----------------------------------- |
|
||||
| Windows | Windows 10 以降 | x64 |
|
||||
| macOS | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 下表を参照 | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| ファイル | 説明 |
|
||||
| ---------------------------------------- | ------------------------------------------ |
|
||||
| `CC-Switch-v3.16.2-Windows.msi` | **推奨** - 自動更新対応の MSI インストーラー |
|
||||
| `CC-Switch-v3.16.2-Windows-Portable.zip` | ポータブル版、展開してそのまま実行できます |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| -------------------------------- | ------------------------------------------------------ |
|
||||
| `CC-Switch-v3.16.2-macOS.dmg` | **推奨** - DMG インストーラー、Applications へドラッグ |
|
||||
| `CC-Switch-v3.16.2-macOS.zip` | 展開して Applications へドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.16.2-macOS.tar.gz` | Homebrew インストールと自動更新用 |
|
||||
|
||||
Homebrew インストール：
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Linux アセットは **x86_64** と **ARM64**（`aarch64`）の両方を提供します。ファイル名にアーキテクチャ識別子が含まれているため、マシンの `uname -m` 出力に合わせて選択してください：
|
||||
|
||||
- `CC-Switch-v3.16.2-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- `CC-Switch-v3.16.2-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| ディストリビューション | 推奨形式 | インストール方法 |
|
||||
| --------------------------------------- | ----------- | ------------------------------------------------------------------------- |
|
||||
| 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` |
|
||||
@@ -0,0 +1,347 @@
|
||||
# CC Switch v3.16.2
|
||||
|
||||
> 在 v3.16.1 的 Codex 稳定性补丁之后，这一版主要拓宽了数据的可携带性与用量观测能力——新增 S3 兼容云同步、OpenCode 会话用量同步、官方订阅额度模板——并继续加固 Codex 通过 Chat Completions 路由第三方供应商的稳健性，同时修复了一批 Windows / macOS 平台问题，新增 CherryIN、ZenMux 供应商，并全面刷新了三语用户手册。
|
||||
|
||||
**[English →](v3.16.2-en.md) | [日本語版 →](v3.16.2-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 使用攻略
|
||||
|
||||
这一版新增了云同步的 S3 后端和更多用量统计来源，如果你想用上，可以先看这些文档：
|
||||
|
||||
- **[设置](../user-manual/zh/1-getting-started/1.5-settings.md)**：在设置页配置云同步（WebDAV / S3 兼容存储），用于在多台设备间备份和恢复供应商、MCP、提示词、技能等配置。
|
||||
- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：了解用量看板的数据来源（代理日志、Codex / Gemini / OpenCode 会话同步）与统计口径。
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## 唯一官方渠道声明（请务必阅读）
|
||||
>
|
||||
> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。请仅通过下列官方渠道获取本软件：
|
||||
>
|
||||
> | 类别 | 唯一官方 |
|
||||
> | -------- | ------------------------------------------------------------------------------ |
|
||||
> | 官网 | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | 源码 | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | 下载 | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | 作者 | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.16.2 是 v3.16.1 之后的一版维护更新。在上一版集中处理 Codex 官方鉴权与本地路由接管的安全问题之后，这一版把重心放在两件事上：一是拓宽数据的可携带性和用量观测——新增 S3 兼容云同步（WebDAV 之外的第二套云备份后端）、OpenCode 会话用量同步，以及面向官方订阅的额度统计模板；二是继续打磨 Codex 通过 Chat Completions 路由第三方供应商时暴露出来的边角问题——流式截断判定、空 tools 下的 `tool_choice`、自定义工具元数据、推理 token 统计、文件 / 音频附件转换等。
|
||||
|
||||
此外，本版还修复了一批本地代理的稳健性问题（临时端口解析、接管占位符还原死循环、Anthropic `system` 消息归一化、上游 413 文案、Claude Desktop 的 `[1m]` 模型路由），处理了若干 Windows / macOS 平台体验问题，并新增 CherryIN、ZenMux 两个供应商，同时全面刷新了三语用户手册。
|
||||
|
||||
**发布日期**：2026-06-07
|
||||
|
||||
**更新规模**：41 commits | 132 files changed | +11,116 / -1,636 lines
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- **S3 兼容云同步**：在 WebDAV 之外新增 S3 兼容对象存储作为第二套云备份后端，内置 AWS S3、MinIO、Cloudflare R2、阿里云 OSS、腾讯云 COS、华为 OBS 等一键预设。
|
||||
- **更多用量统计来源**：新增 OpenCode 会话用量同步，以及面向 Claude / Codex / Gemini 官方订阅的额度统计模板（显式开关、默认关闭）。
|
||||
- **Codex Chat Completions 路由继续加固**：修复流式截断误判、空 tools 下 `tool_choice` 被拒、自定义工具元数据丢失、推理 token 统计缺失，并支持文件 / 音频附件转换与 `/v1/models` 探活端点。
|
||||
- **本地代理更稳**：修复临时端口（port 0）解析、接管占位符还原死循环、Anthropic `system` 消息归一化、上游 413 文案，以及 Claude Desktop 1M 上下文模型路由。
|
||||
- **平台与供应商**：修复 Windows 托盘 / 任务栏图标、子目录技能更新、macOS 输入自动大写等问题，并新增 CherryIN、ZenMux 供应商。
|
||||
|
||||
---
|
||||
|
||||
## 新功能
|
||||
|
||||
### S3 兼容云同步
|
||||
|
||||
云同步现在支持 S3 兼容对象存储作为 WebDAV 之外的第二套后端，签名采用自实现的 AWS Signature V4，以兼容尽可能多的服务。设置页提供 AWS S3、MinIO、Cloudflare R2、阿里云 OSS、腾讯云 COS、华为 OBS 以及自定义 endpoint 的一键预设，支持连接测试、手动上传 / 下载，以及在配置变更时自动同步（providers、endpoint、MCP、提示词、技能、设置、代理等配置表，**不含**用量日志这类高频写入数据）。开启 S3 同步会停用正在运行的 WebDAV 同步，反之亦然（[#1351](https://github.com/farion1231/cc-switch/pull/1351)）。
|
||||
|
||||
### OpenCode 会话用量同步
|
||||
|
||||
新增 OpenCode 作为用量统计来源，从 OpenCode 本地 SQLite 数据库读取每条消息的 token、成本和模型数据并导入用量记录，并提供独立的「OpenCode」应用筛选页签和「OpenCode Session」数据来源标签。数据库路径会遵循 `OPENCODE_DB` 和 `XDG_DATA_HOME`（在所有平台默认 `~/.local/share/opencode`），只导入已完成的消息，并在判断新鲜度时把 WAL 文件一并计入，避免刚写入的会话被跳过（[#3215](https://github.com/farion1231/cc-switch/pull/3215)）。
|
||||
|
||||
### 官方订阅额度模板
|
||||
|
||||
由于部分用户担心发起用量查询的 IP 和发起应用内请求的不一致导致封号风险，因此为 Claude / Codex / Gemini 官方供应商新增一个显式、可选的「官方订阅」用量模板，通过 CLI / OAuth 凭据查询套餐额度，替代此前对官方供应商的隐式自动查询。该模板默认关闭，需要在用量脚本弹窗里开启，并可配置刷新间隔。使用此功能建议开启代理的 TUN 模式。
|
||||
|
||||
### 文本模型图片回退整流器
|
||||
|
||||
新增一个代理整流器：当路由到的模型仅支持文本（显式声明，或由内置的模型名启发式判定），或上游拒绝图片输入时，会把 Anthropic 图片块替换为 `[Unsupported Image]` 占位标记，避免对话被中断。设置页提供该回退功能的开关，并单独提供一个开关控制启发式检测（可关闭以避免误判多模态模型）。
|
||||
|
||||
### ZenMux Token Plan 供应商
|
||||
|
||||
新增 ZenMux 作为 Token Plan 类的 Coding Plan 供应商，可在用量脚本弹窗里手动填写 API key 和 base URL，并以美元口径富展示已用 / 额度（[#2709](https://github.com/farion1231/cc-switch/pull/2709)）。
|
||||
|
||||
### CherryIN 预设
|
||||
|
||||
新增 CherryIN 聚合网关作为快捷配置预设，覆盖全部 7 个受管应用——Claude Code / Claude Desktop / OpenClaw / Hermes 使用 Anthropic 格式端点（open.cherryin.net），OpenCode 使用 `@ai-sdk/anthropic`（`/v1`），Codex 使用 OpenAI 兼容端点，Gemini CLI 使用 Gemini 兼容端点，附带官方品牌图标，位置紧挨 AiHubMix（[#3643](https://github.com/farion1231/cc-switch/pull/3643)）。
|
||||
|
||||
### Codex CLI 模型探活端点 `/v1/models`
|
||||
|
||||
本地代理现在会响应 Codex CLI 启动时探测的 `GET /v1/models`，返回 CC Switch 托管的 Codex 模型目录。同时加入了过期目录守卫：解析 live 的 `config.toml`，仅当 `model_catalog_json` 仍指向 CC Switch 持有的目录文件时才提供，避免把上一个供应商遗留的目录暴露给 Codex（[#3818](https://github.com/farion1231/cc-switch/pull/3818)）。
|
||||
|
||||
### Codex Chat 文件与音频附件
|
||||
|
||||
Codex 的 Responses→Chat 转换现在会把 `input_file`（携带 `file_id` 或内联 `file_data`）和 `input_audio` 内容部分映射为 Chat Completions 的对应形态，并补发此前会被丢弃的顶层 `input_*` 项，让文件和音频附件能够送达只支持 Chat 的 Codex 上游。
|
||||
|
||||
---
|
||||
|
||||
## 变更
|
||||
|
||||
### 用量看板 Hero 重新设计
|
||||
|
||||
把用量看板的 Hero 区与汇总卡片重排为更紧凑的布局，将真实 token 总量、请求数和成本合并到顶部一行展示（[#3426](https://github.com/farion1231/cc-switch/pull/3426)）。
|
||||
|
||||
### SSSAiCode 端点刷新
|
||||
|
||||
把 SSSAiCode 预设的官网、注册和 API base URL 更新到 `sssaicodeapi.com` 域名，并刷新其端点候选节点（默认 `node-hk.sssaicodeapi.com`，另含 `node-hk.sssaiapi.com` 和 `node-cf.sssaicodeapi.com`），覆盖全部 7 个应用预设。
|
||||
|
||||
---
|
||||
|
||||
## 修复
|
||||
|
||||
### Codex Chat 流式截断判定
|
||||
|
||||
当 Chat Completions 上游在没有 `finish_reason` 或 `[DONE]` 的情况下结束流时，CC Switch 不再把它当作正常完成：只有流真正结束才正常收尾；已产出部分内容时发出 incomplete（`max_output_tokens`）响应；完全没有产出时发出失败的 `stream_truncated` 事件。晚到的推理内容也会回填到仍在进行的流式工具调用上。
|
||||
|
||||
### Codex Chat 空 tools 下的 `tool_choice`
|
||||
|
||||
Responses→Chat 转换现在会在最终 tools 数组缺失或为空（包括所有工具被过滤掉）时一并丢弃 `tool_choice` 和 `parallel_tool_calls`，避免严格的 OpenAI 兼容上游（vLLM、企业网关）以"When using `tool_choice`, `tools` must be set."报 503/400（[#3640](https://github.com/farion1231/cc-switch/pull/3640)）。
|
||||
|
||||
### Codex 自定义工具元数据保留
|
||||
|
||||
自定义 Codex 工具（如自由格式的 `apply_patch` 工具）现在会把完整的原始定义——包括 format 和 grammar 元数据——以紧凑、顺序稳定的 JSON 块嵌入生成的 Chat 函数描述中，而不是替换成通用占位符，从而在 Chat Completions 上游上仍可正常使用（[#3644](https://github.com/farion1231/cc-switch/pull/3644)）。
|
||||
|
||||
### Codex Chat 用量缺少 `reasoning_tokens`
|
||||
|
||||
Chat→Responses 的用量转换现在总会包含 `output_tokens_details.reasoning_tokens`（默认 0），即使供应商省略 `completion_tokens_details` 或返回非对象也是如此，满足 Codex CLI 的严格要求，避免反复的响应解析失败和重试（[#3514](https://github.com/farion1231/cc-switch/pull/3514)）。
|
||||
|
||||
### Codex 自定义工具 / 搜索工具的跨轮推理
|
||||
|
||||
Codex Chat 历史里的跨轮推理缓存现在覆盖完整的工具调用集合（`function_call`、`custom_tool_call`、`tool_search_call`）及其输出，而不再仅限普通函数调用，因此 `apply_patch` 和工具搜索调用在通过 `previous_response_id` 恢复时能保留各自的 `reasoning_content`。
|
||||
|
||||
### 临时端口（port 0）解析
|
||||
|
||||
当代理被配置为监听 0 端口（由系统分配）时，接管流程现在会先启动代理以拿到真实端口，再写入 live 配置和数据库，避免客户端 URL 指向无效的 `:0` 地址；若还没解析出具体端口，Claude Desktop 的网关 URL 会被直接拒绝。
|
||||
|
||||
### 代理占位符备份 / 恢复死循环
|
||||
|
||||
如果上一次停止代理时未能还原原始 live 配置、把代理占位符遗留在了 live 中，再次接管时不会再用代理配置覆盖掉正常备份，恢复时也不会把占位符写回 live：两条路径都会识别占位符状态并以当前供应商为真相来源重建 live，修复了代理开关变成空操作、客户端被钉死在本地代理地址的问题（[#3689](https://github.com/farion1231/cc-switch/pull/3689)）。
|
||||
|
||||
### 代理接管期间误拦截供应商切换
|
||||
|
||||
在本地路由接管期间，现在只有显式归类为官方的供应商会被禁止切换，而不会再把端点存在 meta 里、或字段尚未填写的自定义供应商一并禁用。被禁用的「启用」按钮现在以更轻量的提示气泡替代原先的红色「已拦截」标记。
|
||||
|
||||
### localhost 监听地址归一化
|
||||
|
||||
保存代理时如果监听地址填的是 `localhost`，现在会先归一化为 `127.0.0.1` 再持久化，避免绑定不一致（[#3016](https://github.com/farion1231/cc-switch/pull/3016)）。
|
||||
|
||||
### Anthropic `system` 消息归一化
|
||||
|
||||
对 Anthropic 格式的供应商，`messages` 数组里的 system 角色条目现在会被折叠并合并到顶层 `system` 字段（保留原顺序以及已有的顶层 system），避免严格上游拒绝非首位的 system 消息；OpenAI Chat 路由不受影响（[#3775](https://github.com/farion1231/cc-switch/pull/3775)）。
|
||||
|
||||
### Claude Desktop 1M 上下文模型路由
|
||||
|
||||
Claude Desktop 在 1M 上下文 beta 激活时会给模型名追加 `[1m]` 标记（如 `claude-opus-4-8[1m]`）。代理现在会在路由匹配前先剥掉该后缀，让精确、别名、旧名和角色关键词匹配都能正确命中，修复了对话中途切换到 1M 模型时的 `route_unknown`（HTTP 400）失败；诊断用的 `route_unknown` 错误里仍保留原始模型名。
|
||||
|
||||
### Codex 413 错误文案
|
||||
|
||||
当 Codex 上游网关以 HTTP 413 拒绝过大的请求体时，代理现在返回专门的提示，说明这是供应商服务端的请求体大小限制（而非 CC Switch 本地限制），并给出可操作的恢复步骤（运行 `/compact`、移除大段日志或内联图片，或请供应商调高限制），不再原样回显上游的 HTML 错误页。
|
||||
|
||||
### 代理面板错误详情
|
||||
|
||||
切换代理接管失败时，代理面板的提示现在会带上后端返回的具体错误详情，而不是只显示一句笼统的失败信息（[#3656](https://github.com/farion1231/cc-switch/pull/3656)）。
|
||||
|
||||
### Copilot 无限空白检测阈值
|
||||
|
||||
把流式无限空白的中断阈值从 20 调高到 500 个连续空白字符，避免参数里含深层缩进代码（Python、YAML、Rust、Markdown）的正常工具调用被误判中断，同时仍能捕获真正的 Copilot 无限空白 bug（[#2647](https://github.com/farion1231/cc-switch/pull/2647)）。
|
||||
|
||||
### 订阅档位托盘渲染
|
||||
|
||||
通过统一的档位到标签映射，修复官方订阅档位在托盘和额度展示上的渲染问题：Claude / Codex 不再漏掉 7 天窗口，Gemini Pro / Flash / Flash-Lite 档位不再泄露原始机器名，多窗口套餐（如 Opus + Sonnet）现在按最差利用率展示而非取第一个匹配。
|
||||
|
||||
### Claude 流式 input_tokens 虚高
|
||||
|
||||
部分 Anthropic 兼容的流式供应商（如 Qwen、MiniMax）会在 `message_start` 里把完整上下文当作 `input_tokens` 上报，重复计入了已经单独统计的缓存部分，导致显示的缓存命中率被人为拉低。现在解析器会优先采用 `message_delta` 中更小的正 `input_tokens`，并采用同一 usage 块里配套的缓存计数；原生 Claude 和 OpenRouter 转换路径不变。
|
||||
|
||||
### 智谱配额查询端点路由
|
||||
|
||||
智谱 Coding Plan 的配额查询此前被硬编码到 `api.z.ai`，导致使用大陆预设（`open.bigmodel.cn`）的用户在国际端点不可达时查不到用量。现在配额请求会路由到与用户所配 base URL 匹配的主机（[#3702](https://github.com/farion1231/cc-switch/pull/3702)）。
|
||||
|
||||
### MiniMax 余额接口与定价
|
||||
|
||||
适配 MiniMax Coding Plan 配额的新余额接口（新接口返回剩余百分比字段，而非旧解析器依赖、会导致档位为空、托盘不再显示用量的用量计数），过滤掉非编程模型（如视频），兼容无周限额的套餐，并为 MiniMax M3 模型补充了默认定价（[#3518](https://github.com/farion1231/cc-switch/pull/3518)）。
|
||||
|
||||
### GLM Coding Plan 端点与模型拉取
|
||||
|
||||
把智谱 / Z.AI 的 GLM Coding Plan 预设修正到 `/api/coding/paas/v4` 端点（覆盖 Codex、OpenCode、OpenClaw、Hermes），并让模型列表探测对已经以 `/v{N}` 版本段结尾的 base URL 改为先查 `{base}/models`（保留 `/v1/models` 作为兜底），让「拉取模型」按钮不再在带版本号的端点上 404（[#3524](https://github.com/farion1231/cc-switch/pull/3524)）。
|
||||
|
||||
### Codex 模型目录路径可移植性
|
||||
|
||||
Codex 现在只把相对文件名 `cc-switch-model-catalog.json` 写入 `config.toml`，而不是绝对路径（Codex CLI 会从配置目录解析它），修复了在 WSL 和符号链接环境下绝对路径无法转换、导致模型目录失效的问题（[#3614](https://github.com/farion1231/cc-switch/pull/3614)）。
|
||||
|
||||
### APINebula 的 OpenCode SDK
|
||||
|
||||
APINebula 的 OpenCode 预设现在加载 `@ai-sdk/openai-compatible` 而非 `@ai-sdk/openai`，让请求使用该中转期望的 OpenAI Chat Completions 格式，而不是只支持 chat-completions 的上游会失败的 Responses API。
|
||||
|
||||
### Windows 退出后托盘图标残留
|
||||
|
||||
在 Windows 上退出 CC Switch 可能会留下一个失效的托盘图标，直到鼠标划过才消失。现在应用会在退出前显式移除托盘图标，让它随进程结束干净消失（[#3797](https://github.com/farion1231/cc-switch/pull/3797)）。
|
||||
|
||||
### Windows 任务栏图标
|
||||
|
||||
在运行时显式设置 Windows AppUserModelID，并给安装器生成的桌面和开始菜单快捷方式写入相同的 ID 和产品图标，让 CC Switch 在任务栏上显示正确图标并正确归组（[#3457](https://github.com/farion1231/cc-switch/pull/3457)）。
|
||||
|
||||
### Windows 子目录技能的更新检查
|
||||
|
||||
在 Windows 上扫描已安装技能时，把反斜杠路径分隔符归一化为正斜杠，让嵌套在子目录里的技能（如 `skills/my-skill`）能被更新检查匹配到，而不是被静默跳过（[#3430](https://github.com/farion1231/cc-switch/pull/3430)）。
|
||||
|
||||
### macOS 输入自动大写
|
||||
|
||||
为共享的文本 Input 组件关闭自动完成、自动纠错、自动大写和拼写检查，让 macOS 不再对配置字段里输入的首字母自动大写或自动纠正（[#3626](https://github.com/farion1231/cc-switch/pull/3626)）。
|
||||
|
||||
### Codex VS Code 会话预览
|
||||
|
||||
从 VS Code 发起的 Codex 请求，其会话预览在注入请求前存在 markdown 标题时，可能显示选区或打开文件的内容而非真实提示。现在后端标题和前端预览都会匹配最后一个「## My request for Codex:」标题（IDE 把真实请求作为最后一节注入），让预览反映用户的提示（[#3593](https://github.com/farion1231/cc-switch/pull/3593)）。
|
||||
|
||||
### 中文界面 VS Code 文案
|
||||
|
||||
把简体和繁体中文里「应用到 Claude Code 插件」的描述改为正确书写「VS Code」而非「Vscode」，与英文、日文文案对齐（[#3228](https://github.com/farion1231/cc-switch/pull/3228)）。
|
||||
|
||||
---
|
||||
|
||||
## 文档
|
||||
|
||||
### 用户手册刷新
|
||||
|
||||
刷新了 README 各语言版本以及 en / zh / ja 用户手册，使其反映全部 7 个受管应用（在介绍和总览文案里补上 Claude Desktop 与 Hermes），把 OpenCode 配置路径修正为 `~/.config/opencode/`（`opencode.json`），补充了 Hermes 配置文件说明，把语言文档更新为四种语言，订正各应用 MCP / 提示词 / 技能的支持情况，说明导出现在会生成带时间戳、含用量日志的 SQL 备份，并补充了定价模型 ID 匹配规则（[#3411](https://github.com/farion1231/cc-switch/pull/3411)）。
|
||||
|
||||
### Codex 官方认证保留指南
|
||||
|
||||
新增中 / 英 / 日三语指南，说明如何在把模型流量切到第三方 API 的同时，保留 Codex 官方远程操作和官方插件的可用性，并从 v3.16.1 release notes 链接到该指南。
|
||||
|
||||
### README 链接与赞助商标记
|
||||
|
||||
把各语言 README 里的 Release Notes 链接更新到 v3.16.1，并修复 README_ZH 赞助商区块里损坏的弯引号字符，让其 HTML 属性能正确渲染（[#3772](https://github.com/farion1231/cc-switch/pull/3772)）。
|
||||
|
||||
---
|
||||
|
||||
## 升级提醒
|
||||
|
||||
### S3 与 WebDAV 云同步互斥
|
||||
|
||||
云同步同一时间只会运行一套后端。开启 S3 自动同步会停用正在运行的 WebDAV 自动同步，反之亦然。如果你之前用的是 WebDAV，切到 S3 前请确认两端数据已对齐，避免误以为旧后端仍在备份。
|
||||
|
||||
### 修改模型映射后仍需重启 Codex
|
||||
|
||||
Codex 在启动时读取 `model_catalog_json`。即使本版已把模型目录改写为相对路径并新增了 `/v1/models` 探活端点，只要你修改了模型映射表，仍然需要重启 Codex 才能让 `/model` 菜单刷新。
|
||||
|
||||
---
|
||||
|
||||
## 风险提示
|
||||
|
||||
本版本继续沿用此前版本对反向代理类功能的风险提示。
|
||||
|
||||
**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
|
||||
|
||||
**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
|
||||
|
||||
**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，同样需要遵守目标供应商的计费、合规与数据留存约束。
|
||||
|
||||
用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
|
||||
|
||||
---
|
||||
|
||||
## 致谢
|
||||
|
||||
感谢以下贡献者在 v3.16.2 中提交的功能与修复：
|
||||
|
||||
- [#1351](https://github.com/farion1231/cc-switch/pull/1351)：新增 S3 兼容云存储同步，感谢 @keithyt06。
|
||||
- [#3215](https://github.com/farion1231/cc-switch/pull/3215)：新增 OpenCode 会话用量同步，感谢 @nothingness0db。
|
||||
- [#2709](https://github.com/farion1231/cc-switch/pull/2709)：新增 ZenMux Token Plan 供应商，感谢 @Eter365。
|
||||
- [#3643](https://github.com/farion1231/cc-switch/pull/3643)：新增 CherryIN 预设供应商，感谢 @zhibisora。
|
||||
- [#3818](https://github.com/farion1231/cc-switch/pull/3818)：新增 Codex CLI 探活用的 `GET /v1/models` 端点，感谢 @CSberlin。
|
||||
- [#3426](https://github.com/farion1231/cc-switch/pull/3426)：用量看板 Hero 重新设计，感谢 @allenxu09。
|
||||
- [#3640](https://github.com/farion1231/cc-switch/pull/3640)：空 tools 时丢弃 `tool_choice`，感谢 @Postroggy。
|
||||
- [#3644](https://github.com/farion1231/cc-switch/pull/3644)：Chat 路由保留 Codex 自定义工具元数据，感谢 @LanternCX。
|
||||
- [#3514](https://github.com/farion1231/cc-switch/pull/3514)：Chat→Responses 始终包含 `reasoning_tokens`，感谢 @yeeyzy。
|
||||
- [#3689](https://github.com/farion1231/cc-switch/pull/3689)：live 已是代理占位符时跳过备份 / 恢复，感谢 @YongmaoLuo。
|
||||
- [#3016](https://github.com/farion1231/cc-switch/pull/3016)：归一化 localhost 监听地址，感谢 @Alexlangl。
|
||||
- [#3775](https://github.com/farion1231/cc-switch/pull/3775)：规范化 Anthropic `system` 消息，感谢 @Dearli666。
|
||||
- [#3656](https://github.com/farion1231/cc-switch/pull/3656)：改进代理面板错误信息展示，感谢 @lzcndm。
|
||||
- [#2647](https://github.com/farion1231/cc-switch/pull/2647)：调高无限空白检测阈值 20 → 500，感谢 @NiuBlibing。
|
||||
- [#3702](https://github.com/farion1231/cc-switch/pull/3702)：智谱配额查询按所配 base URL 路由，感谢 @YongmaoLuo。
|
||||
- [#3518](https://github.com/farion1231/cc-switch/pull/3518)：适配 MiniMax 余额查询新接口与默认定价，感谢 @LaoYueHanNi。
|
||||
- [#3524](https://github.com/farion1231/cc-switch/pull/3524)：修复智谱 Coding Plan 预设与带版本号端点的模型探测，感谢 @makoMakoGo。
|
||||
- [#3614](https://github.com/farion1231/cc-switch/pull/3614)：模型目录改用相对文件名，感谢 @steponeerror。
|
||||
- [#3797](https://github.com/farion1231/cc-switch/pull/3797)：修复 Windows 退出后托盘图标残留，感谢 @iAJue。
|
||||
- [#3457](https://github.com/farion1231/cc-switch/pull/3457)：修复 Windows 任务栏图标，感谢 @ZhangNanNan1018。
|
||||
- [#3430](https://github.com/farion1231/cc-switch/pull/3430)：归一化 Windows 路径分隔符以匹配子目录技能更新，感谢 @Ninthless。
|
||||
- [#3626](https://github.com/farion1231/cc-switch/pull/3626)：关闭 macOS 输入框自动大写，感谢 @ZHLHZHU。
|
||||
- [#3593](https://github.com/farion1231/cc-switch/pull/3593)：修复 Codex VS Code 会话预览，感谢 @xwil1。
|
||||
- [#3228](https://github.com/farion1231/cc-switch/pull/3228)：对齐中文界面 VS Code 文案，感谢 @Games55k。
|
||||
- [#3411](https://github.com/farion1231/cc-switch/pull/3411)：刷新用户手册以反映当前应用支持，感谢 @makoMakoGo。
|
||||
- [#3772](https://github.com/farion1231/cc-switch/pull/3772)：修复 README release note 链接与赞助商标记，感谢 @null-easy。
|
||||
|
||||
也感谢所有在 v3.16.1 发布后反馈 Codex Chat 路由、本地代理接管、用量统计和平台兼容性问题的用户，很多补丁都来自这些真实使用场景里的复现线索。
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
|
||||
|
||||
### 系统要求
|
||||
|
||||
| 系统 | 最低版本 | 架构 |
|
||||
| ------- | -------------------------- | ----------------------------------- |
|
||||
| Windows | Windows 10 及以上 | x64 |
|
||||
| macOS | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 见下表 | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| 文件 | 说明 |
|
||||
| ---------------------------------------- | ----------------------------------- |
|
||||
| `CC-Switch-v3.16.2-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.16.2-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| -------------------------------- | --------------------------------------------- |
|
||||
| `CC-Switch-v3.16.2-macOS.dmg` | **推荐** - DMG 安装包，拖入 Applications 即可 |
|
||||
| `CC-Switch-v3.16.2-macOS.zip` | 解压后拖入 Applications，Universal Binary |
|
||||
| `CC-Switch-v3.16.2-macOS.tar.gz` | 用于 Homebrew 安装和自动更新 |
|
||||
|
||||
Homebrew 安装：
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本：
|
||||
|
||||
- `CC-Switch-v3.16.2-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- `CC-Switch-v3.16.2-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| 发行版 | 推荐格式 | 安装方式 |
|
||||
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| 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` |
|
||||
@@ -0,0 +1,340 @@
|
||||
# CC Switch v3.16.3
|
||||
|
||||
> 🎉 **CC Switch has passed 100,000 Stars!**
|
||||
> Thank you to every user, contributor, and Star — you are the reason it has come this far. 🙏
|
||||
|
||||
> 💎 **This release was developed with help from the Claude Fable 5 model** — it helped untangle several critical, error-prone pieces of logic: the attribution chain that bills route-takeover traffic by the real upstream model, the metering and de-duplication of cache tokens on format-conversion paths, the in-app update restart deadlock, and the migration / restore invariants of Codex unified session history. This is also why this release adds a **Fable 5 Verified** badge to the About page.
|
||||
|
||||
> After v3.16.2 broadened data portability and usage observability, this release puts the focus on "making usage billing truly accurate" — billing by the real upstream model, fixing cache double-counting on format-conversion paths, counting Claude Code Workflow sub-agent usage (schema v11), and a round of redesign for the usage dashboard (dashboard-wide provider / model filters, a brand-icon toolbar, and more resilient quota queries) — while also hardening a batch of local proxy and platform issues, adding a custom User-Agent override, a Codex unified session history toggle, and a Claude Fable 5 tier.
|
||||
|
||||
**[中文版 →](v3.16.3-zh.md) | [日本語版 →](v3.16.3-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Usage Guides
|
||||
|
||||
This release adds a **Codex unified session history** toggle — it migrates / restores sessions, and if used without care it can make you think sessions were "lost," so it is well worth reading its guide first. This release also changes how usage is counted and reworks the dashboard quite a bit, so both are worth starting with:
|
||||
|
||||
- **[Codex Unified Session History: Feature Overview and Usage Guide](../guides/codex-unified-session-history-guide-en.md)**: what "unify / migrate / restore" actually changes, why your data is never truly lost, and how to verify and precisely restore sessions when you can't see them. **If you used this toggle or worry a session is gone, read this first.**
|
||||
- **[Usage Statistics](../user-manual/en/4-proxy/4.4-usage.md)**: understand the Usage Dashboard's data sources (proxy logs, session sync) and how the statistics are counted. This release adds dashboard-wide provider / model filters and surfaces the real pricing model for route-takeover traffic.
|
||||
- **[Settings](../user-manual/en/1-getting-started/1.5-settings.md)**: the custom User-Agent override, the Codex unified session history toggle, and other switches live in the provider form's advanced options and on the settings page.
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## Only Official Channels (Please Read)
|
||||
>
|
||||
> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Please only obtain the software through the official channels listed below:
|
||||
>
|
||||
> | Channel | Only Official |
|
||||
> | ------------------ | ------------------------------------------------------------------------------ |
|
||||
> | Website | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | Source | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | Downloads | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | Author | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.16.3 is a maintenance update following v3.16.2. After the previous release concentrated on broadening data portability and usage observability, this release puts the focus on "making usage billing truly accurate" — billing by the real upstream model rather than whatever the upstream echoes back, fixing the cache-token double-counting on format-conversion paths (Chat / Responses / Gemini converted to Anthropic), folding Claude Code Workflow sub-agent usage into the local statistics, and persisting the actual pricing basis used by each record as schema v11. The usage dashboard was reworked along with it, adding dashboard-wide provider / model filters, a brand-icon toolbar, and more resilient quota queries (retry on failure plus keeping the last successful result).
|
||||
|
||||
In addition, this release hardens a batch of local proxy robustness issues (aggregating SSE responses returned under a mislabeled Content-Type, Codex `/responses` image rectification for text-only models, recovery of Codex OAuth credentials and takeover residue, duplicate YAML keys in Hermes config), reworks the provider configuration experience (a custom User-Agent override, a unified Codex advanced section, searchable and sortable presets, a Claude Fable 5 tier), adds a Codex unified session history toggle, and fixes the in-app update hang, the Codex upgrade that broke the install, duplicate macOS terminal windows, and more.
|
||||
|
||||
**Release date**: 2026-06-14
|
||||
|
||||
**Stats**: 59 commits | 130 files changed | +10,223 / -4,232 lines
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- **More accurate usage billing**: route-takeover traffic is now billed by the real upstream model (not the alias the upstream echoes back), format-conversion paths no longer count cache tokens into input twice, and Claude Code Workflow sub-agent usage is now counted — with the pricing basis persisted as schema v11.
|
||||
- **Usage dashboard redesign**: provider / model filters are promoted from inside the request-log table up to dashboard-wide filters, the app filter switches to brand icons, and quota queries gain retry-on-failure plus "keep the last successful result" so a single network blip no longer turns cards red.
|
||||
- **Custom User-Agent override**: providers can set a custom UA that applies consistently across forwarding, connectivity detection, and model listing, getting past coding-plan upstreams that gate on a UA whitelist (which is how the Codex "Kimi For Coding" preset was restored).
|
||||
- **Codex unified session history**: a new opt-in toggle lets official Codex sessions share a single resume-history bucket with third-party sessions, with optional migration of existing sessions and precise ledger-based restore.
|
||||
- **Proxy and platform hardening**: aggregating mislabeled SSE responses, Codex image rectification, takeover-residue recovery, Hermes YAML de-duplication; in-app updates no longer hang on "restarting", and Codex upgrades no longer break the install.
|
||||
|
||||
---
|
||||
|
||||
## Added
|
||||
|
||||
### Custom User-Agent Override
|
||||
|
||||
Provider configs can now set a custom User-Agent that the proxy applies consistently across request forwarding, stream check, and model listing (`GET /v1/models`), so coding-plan upstreams that gate on UA no longer fail detection or return 403 while the proxy itself works. The Claude and Codex forms expose it in advanced settings with a curated presets dropdown (Claude Code / Kilo Code families that pass UA whitelists) and live non-blocking validation; stale custom UAs are dropped when switching to an official preset to avoid silently altering headers (#3671).
|
||||
|
||||
### Unified Codex Session History
|
||||
|
||||
Official Codex sessions can now share a single resume-history bucket with cc-switch third-party sessions via an opt-in toggle under Settings → Codex App Enhancements, so the resume picker no longer hides them from each other. When enabled, the live `config.toml` routes official runs through a shared `custom` model_provider that mirrors the built-in OpenAI provider (`auth.json` is untouched); the toggle is forward-only by default but the enable dialog offers a checkbox to migrate existing official sessions (with per-generation backups), and the disable dialog offers a precise ledger-based restore that only reverts sessions originally recorded as `openai` while leaving sessions created during the toggle untouched.
|
||||
|
||||
### Dashboard-Wide Provider / Model Filters
|
||||
|
||||
The provider and model filters move from inside the request-log table up to the top bar, applying globally to the hero summary, trend chart, request logs, and both stats tabs so you can scope the whole dashboard to a given source and model. Sources match by exact display name (so session placeholder rows like "Claude (Session)" are selectable) and models match by effective pricing model, with the model dropdown cascading from the selected source and both lists showing only options that have data in the current range.
|
||||
|
||||
### Refreshed Model Pricing Seed
|
||||
|
||||
Added pricing for 9 models including Claude Fable 5, Grok 4.3, Mistral Medium 3.5 / Small 4, and Qwen 3.7 Max/Plus, and corrected 28 existing prices against current official vendor list pricing (GLM, Grok, MiMo, Doubao, Kimi, MiniMax, Mistral, Qwen) so usage cost estimates are accurate. Each change updates the seed for fresh installs and adds a guarded repair for existing databases without clobbering user-edited rows.
|
||||
|
||||
### Claude Fable 5 Model Tier
|
||||
|
||||
Provider forms now expose `claude-fable-5` as a fourth model-mapping tier on both the Claude Code and Claude Desktop proxy paths, with a fable → opus → default fallback mirroring the official downgrade and the `fable-` prefix whitelisted for the Desktop 1.12603.1+ validator. A clarified four-language fallback hint warns that leaving a tier blank on third-party endpoints forwards the literal model name and 404s (#3980, #4026, #4049).
|
||||
|
||||
### Unity2.ai Partner Provider
|
||||
|
||||
Added Unity2.ai, an AI API relay partner, as a preset across all seven managed apps (Claude Code, Codex, Gemini, OpenCode, OpenClaw, Claude Desktop, Hermes), each carrying the referral signup link and partner promotion copy in all four locales. Codex uses the bare base URL (the gateway exposes `/responses` at root) while OpenCode / OpenClaw / Hermes use the `/v1` chat-completions endpoint with `gpt-5.5`.
|
||||
|
||||
### Kimi K2.7 Code Model
|
||||
|
||||
Added the `kimi-k2.7-code` model (in $0.95 / out $4.00 / cache-read $0.19 per 1M tokens, 256K context) and pointed all six official Moonshot Kimi presets (Claude Code, Codex, Claude Desktop, Hermes, OpenCode, OpenClaw) at it, renaming the OpenCode / OpenClaw presets to "Kimi K2.7 Code". The pricing seed applies on startup via the idempotent insert path, so existing users pick up the new pricing without a migration.
|
||||
|
||||
### Codex "Kimi For Coding" Preset Restored
|
||||
|
||||
Re-added the Codex "Kimi For Coding" preset (`openai_chat`, `kimi-for-coding`, 256K context) with thinking mode enabled by default; it was previously removed because the coding endpoint rejects Codex's default `codex-cli` User-Agent with 403. It now works via proxy takeover combined with the custom User-Agent override (set to a whitelisted UA such as `claude-cli/*`).
|
||||
|
||||
### Pricing-Model Audit in Request Detail
|
||||
|
||||
The request detail panel now shows the requested model and the pricing model when they differ from the response model, making route-takeover bills auditable directly from the usage UI.
|
||||
|
||||
### Preset Provider Search & Sorting
|
||||
|
||||
The provider preset selector gains a searchable, sorted list with an inline search box (toggled via a magnifier icon, dismissed on ESC or outside click). Buttons use a responsive grid with consistent sizing and default icons, and search matches only provider display/raw names so URL fragments and shared category labels no longer produce noisy matches (#3975, #4183).
|
||||
|
||||
### Claude Mythos 5 Pricing
|
||||
|
||||
Registered the `claude-mythos-5` model in the bundled model/pricing table (in $10 / out $50 per 1M tokens, cache read $1.00, cache write $12.50), so usage metering prices and displays it correctly (#4077).
|
||||
|
||||
### Fable 5 Verified Banner
|
||||
|
||||
The Settings About page now displays a Fable 5 Verified banner beside the app name and version, marking this as a special build, with the version badge centered under the app name.
|
||||
|
||||
---
|
||||
|
||||
## Changed
|
||||
|
||||
### Claude Desktop Usage Folded Into Claude
|
||||
|
||||
The dashboard no longer shows a standalone "Claude Desktop" bucket, which only ever displayed a partial number (Desktop chat usage never passes through the proxy and its Code-tab sessions write into the shared `~/.claude/projects` tree). Desktop proxy traffic is now folded into the `claude` view for display while still recorded under its own `app_type` for route-takeover billing audit, with the real value visible in the request detail panel.
|
||||
|
||||
### Lightweight Provider Health Check
|
||||
|
||||
The provider health check no longer sends a real streaming model request (which many third-party providers blocked with 401/403/WAF, causing false negatives); it now performs a lightweight HTTP reachability probe of the provider `base_url`, treating any HTTP response as reachable and counting only DNS/connect/TLS/timeout as failure. The connectivity button is hidden for official providers (which use OAuth with an empty base URL and no reliable reachability target), the real-request confirmation dialog and test model/prompt fields are removed, and the degraded-latency threshold is set to 6s with an 8s timeout. The reachability check never resets the circuit breaker, so failover detection stays driven solely by real proxy traffic.
|
||||
|
||||
### Codex Advanced Options Section
|
||||
|
||||
The Codex provider form now folds local routing, model mapping, reasoning overrides, and custom User-Agent into a single collapsible advanced section mirroring the Claude form (auto-expanding when a UA is set or local routing is on). Custom User-Agent is now also configurable for native Responses providers, where it was previously reachable only with `openai_chat` routing enabled.
|
||||
|
||||
### Usage Toolbar Refresh and Layout
|
||||
|
||||
The app filter now renders brand icons (via ProviderIcon, with a grid icon for "All") instead of text tabs that wrapped awkwardly in narrow windows, and the usage hero shows the selected app's brand icon with Codex recolored to a neutral gray matching OpenAI's monochrome branding. The click-to-cycle refresh button becomes a Select with a localized "off" label, and the top-bar controls are compacted and aligned into consistent width groups with truncated long date-range labels.
|
||||
|
||||
### Faster About Panel Loading
|
||||
|
||||
The Settings About panel now loads progressively: the app version badge appears the instant it resolves instead of waiting for tool probes, each tool card updates the moment its own version check finishes (probes run concurrently rather than sequentially), and results are cached for the app session with a 10-minute TTL so reopening the About tab reuses cached values and revalidates stale ones in the background instead of re-probing all six tools every time.
|
||||
|
||||
### Volcengine Ark Coding Plan Promo
|
||||
|
||||
Updated the Volcengine Ark preset across all six apps with the new Coding Plan invite link (replacing the old Agent Plan / activity links) and refreshed the partner promotion copy in all four locales (two-month 75% off plus invite code 6J6FV5N2), correcting the product name from Agent Plan to Coding Plan.
|
||||
|
||||
### MiniMax Demoted to Regular Provider
|
||||
|
||||
Removed the gold partner star badge and the API-key promotion banner for MiniMax by dropping the `isPartner` flag from all its presets; it stays as a regular `cn_official` provider keeping its icon and theme. The promotion copy is kept dormant so the partnership can be re-enabled with a single line.
|
||||
|
||||
### LemonData Removed, SudoCode Demoted
|
||||
|
||||
Removed the LemonData provider preset entirely from all apps along with its promotion copy, icons, and sponsor listings, and demoted SudoCode from a partner to a regular `third_party` provider by dropping its `isPartner` flag and promotion copy (it keeps its icon).
|
||||
|
||||
### AtlasCloud Codex GLM 5.1 Context Window
|
||||
|
||||
Declared the 200,000-token context window for the `zai-org/glm-5.1` model in the AtlasCloud Codex preset, matching the other GLM 5.1 preset entries.
|
||||
|
||||
---
|
||||
|
||||
## Fixed
|
||||
|
||||
### Route-Takeover Traffic Billed by the Real Upstream Model
|
||||
|
||||
When a request was routed to a different upstream (env model mapping, Claude Desktop routes, Copilot normalization, Codex chat override), the proxy used to attribute and price usage by whatever model the upstream echoed back, recording kimi/glm tokens as `claude-*` and overstating cost roughly 5–25×. The forwarder now captures the real outbound model, attributes usage by upstream-echo then outbound then client alias, persists the actual pricing basis on every row (schema v11), and keeps that basis through cost backfill and 30-day rollup pruning; Claude Desktop traffic is now logged under its own `app_type` so its pricing overrides apply.
|
||||
|
||||
### Usage Metering on Format-Conversion Proxy Paths
|
||||
|
||||
Audited and fixed token/cache accounting across the proxy's format-conversion paths (Chat, Responses, and Gemini converted to Anthropic). The proxy now records the actually returned model, injects `stream_options.include_usage` so OpenAI-compatible upstreams emit usage in streaming, excludes `cache_read` and `cache_creation` from input on Claude←OpenAI paths to stop double-billing cache tokens, subtracts cached Gemini prompt tokens, still records fully-cached requests, and skips synthetic all-zero usage that previously inflated request counts (#2774).
|
||||
|
||||
### In-App Update No Longer Hangs on Restart
|
||||
|
||||
Installing an update from within the app no longer freezes on the "restarting" screen, leaving the new version installed but requiring a manual force-quit. The download-install-restart chain now runs entirely in the backend (a new `install_update_and_restart` command) with platform-aware install ordering and single-instance-lock teardown before re-exec, instead of depending on the old WebView to keep running JS after the app bundle was already swapped; exit requests are also classified so restart requests fall through to Tauri's default flow rather than deadlocking on the window-state plugin mutex (#4069, #4074).
|
||||
|
||||
### Codex Upgrade No Longer Breaks the Install
|
||||
|
||||
Upgrading Codex from the Settings "About" tab no longer leaves it throwing "Missing optional dependency @openai/codex-…" errors. The upgrade chain previously ran `codex update` first, which on an npm install is a bare reinstall that reports success even when the per-platform binary fails to land; Codex is now removed from the self-update-first path and a runnable check triggers an uninstall+reinstall self-heal (scoped to npm-managed installs) that actually re-lands the missing platform binary.
|
||||
|
||||
### Codex OAuth Auth Token Preserved on Proxy Takeover
|
||||
|
||||
Enabling proxy takeover for a Codex provider no longer strips the `ANTHROPIC_AUTH_TOKEN` placeholder, which previously broke Claude Code's login on hot-switches, fresh installs, and configs already stripped by older releases. The placeholder is now injected unconditionally for managed (non-Copilot) Codex providers, including URL-only ones; GitHub Copilot behavior (API_KEY only) is unchanged (#3789, #3784).
|
||||
|
||||
### Takeover-Residue Recovery Across Config-Dir Switches
|
||||
|
||||
Restarting the app after changing the config directory while proxy takeover is active no longer leaves Claude/Codex/Gemini pointed at a dead local proxy. The old instance now restores the taken-over live files before restarting, the first-run import refuses to persist a takeover placeholder as a provider, and SSOT restore validates that the current provider's config is free of placeholders before writing it back (#4076).
|
||||
|
||||
### Mislabeled SSE Bodies in Format-Transform Fallback
|
||||
|
||||
Requests routed through Claude/Codex format conversion no longer fail with an opaque 422 "Failed to parse upstream response" when a MaaS gateway force-streams a `stream:false` request and returns an SSE body under a non-SSE Content-Type. The proxy now sniffs for SSE on parse failure, aggregates the chunks into a single JSON, and runs the existing converter so clients still get a valid non-stream response; remaining parse failures are enriched with content-type, encoding, and body-snippet diagnostics, and deflate decoding now tries zlib before raw (#2234).
|
||||
|
||||
### Duplicate YAML Keys in Hermes Config
|
||||
|
||||
Hermes config writes no longer accumulate duplicate top-level keys (e.g. `mcp_servers`) that caused "Failed to parse Hermes config as YAML: duplicate entry with key" errors. Section replacement now strips all stale occurrences from the remainder instead of degrading into appends, the dedup safety net handles both LF and CRLF line endings, and healing keeps the last (newest) occurrence to match Hermes's own last-wins PyYAML semantics (#3267, #3633, #2973, #2529, #3310, #3762).
|
||||
|
||||
### Usage Query Resilience and Error Clarity
|
||||
|
||||
Usage cards no longer flip to red on a single transient blip: queries now retry once and keep showing the last successful result for up to 10 minutes on network/timeout/5xx failures, while deterministic failures (auth, empty key, unknown provider, 4xx) surface immediately and clear the snapshot so a stale quota can't resurface after credentials change. Native balance/coding-plan/subscription timeouts were raised from 10s to 15s for slow cross-border endpoints, and coding-plan now returns explicit "API key is empty" / "Unknown coding plan provider" errors instead of a blank failure.
|
||||
|
||||
### Usage Script Provider Credential Resolution
|
||||
|
||||
Custom JS-script usage queries resolved `{{apiKey}}` / `{{baseUrl}}` by guessing env fields only, so providers that store credentials elsewhere (e.g. Codex's `auth.OPENAI_API_KEY` plus `config.toml` base_url) always got empty values and failed despite being fully configured. Script queries and the test/preview now reuse the same per-app credential resolver as the native balance path, with explicit non-empty script values still taking precedence (#1479).
|
||||
|
||||
### Claude Code Workflow Sub-Agent Usage Counted
|
||||
|
||||
Local (no-proxy) session-log usage accounting missed Claude Code Workflow sub-agent traffic, under-counting overall usage by roughly 4.1% (concentrated in workflow/subagent transcripts). The scanner now descends into the deeper `subagents/workflows/wf_*/` transcript directories, and the parser no longer drops billable assistant messages that lack a `stop_reason` but already incurred input/cache token cost; dedup is unchanged so no usage is double-counted.
|
||||
|
||||
### Codex Image Rectifier for /responses Text-Only Upstreams
|
||||
|
||||
Codex `/responses` requests carrying images and routed to text-only OpenAI-chat models (e.g. DeepSeek `deepseek-v4-flash`) no longer fail with HTTP 400 "unknown variant `image_url`". The media rectifier now also covers the Codex adapter, scanning the responses `input` for `input_image` blocks so it can proactively strip images for known text-only models and reactively retry with images replaced on upstream image-unsupported errors.
|
||||
|
||||
### Zhipu Coding-Plan Quota Window Mislabeling
|
||||
|
||||
The Zhipu coding-plan view no longer swaps the 5-hour and weekly quota buckets in the final hours of each weekly cycle. The two windows are now classified by the explicit `unit` field (3 = 5-hour, 6 = weekly) instead of by sorting reset-time ascending, which mislabeled them exactly when users check their weekly quota most; the old reset-time heuristic remains as a fallback (#3036).
|
||||
|
||||
### Duplicate Provider Terminal Sessions on macOS
|
||||
|
||||
Launching a provider terminal on macOS no longer opens an extra empty window alongside the command session; Terminal.app uses `launch` (not `activate`) on cold start and Ghostty uses an initial-command so a single session opens, with a fallback retained if the AppleScript path fails (#4156).
|
||||
|
||||
### Claude Desktop Model-Mapping Placeholders
|
||||
|
||||
The Claude Desktop model-mapping form previously showed mismatched example brands across the menu display name and request model columns (DeepSeek vs Kimi), implying a display name maps to an unrelated model. Both placeholders are now derived from each row's role so they stay brand-consistent, with the lightweight Haiku tier using a flash example.
|
||||
|
||||
### Popovers Behind Fullscreen Panels
|
||||
|
||||
Popovers and tooltips such as the provider preset search no longer render behind fullscreen panels and appear unresponsive on click; their z-index is raised above the fullscreen overlay while staying below modal dialogs.
|
||||
|
||||
### ToggleRow Icon Shrinking
|
||||
|
||||
Toggle row icons no longer shrink or distort when paired with long descriptions, keeping the icon at a fixed size next to multi-line text.
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
### Release Notes Contributor Mentions
|
||||
|
||||
Restored contributor mentions in the v3.16.1 and v3.16.2 release notes across all three locales.
|
||||
|
||||
---
|
||||
|
||||
## Upgrade Notes
|
||||
|
||||
### Pricing Database schema v11 Auto-Migration
|
||||
|
||||
This release adds a `pricing_model` column to `proxy_request_logs` and rebuilds the rollup by `request_model` + `pricing_model`, migrating automatically on startup with no manual action required. Historical rows have their cost frozen at write time and are not recalculated (rows with `app_type="claude"` mix native and converted sources); only real but previously un-priced takeover rows stay at zero cost until pricing is supplied and then backfilled.
|
||||
|
||||
### Model Mapping Adds a Fourth Tier (Fable 5)
|
||||
|
||||
The Claude Code and Claude Desktop model mappings now have four tiers (Sonnet / Opus / Fable / Haiku). Older three-tier providers pick up the `claude-fable-5` tier after being reopened and saved; leaving that tier blank means it inherits Sonnet. Note: leaving any tier blank on third-party endpoints forwards the literal model name of that tier and may 404, so fill it in as needed.
|
||||
|
||||
### The "Kimi For Coding" Preset Needs Proxy Takeover + a Whitelisted UA
|
||||
|
||||
The restored Codex "Kimi For Coding" preset is still rejected with 403 if used with the default `codex-cli` User-Agent. To use it, enable proxy takeover and set the custom User-Agent in the provider's advanced options to a whitelisted UA (such as `claude-cli/*`).
|
||||
|
||||
### Provider Health Check Semantics Changed
|
||||
|
||||
The health check changed from "send a real model request" to "HTTP reachability probe". Note that reachable ≠ usable: a host that returns 403 is reachable but may be broken for real traffic. Failover decisions remain driven solely by real proxy traffic and are unaffected by the health check.
|
||||
|
||||
---
|
||||
|
||||
## Risk Notice
|
||||
|
||||
This release continues the risk notices from previous versions for reverse-proxy-style features.
|
||||
|
||||
**Codex OAuth reverse proxy**: using a ChatGPT subscription's Codex OAuth through a reverse proxy may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details.
|
||||
|
||||
**Codex third-party provider Chat routing**: when CC Switch local proxy converts and forwards Codex requests to third-party providers, each provider may have different requirements for billing, compliance, and data retention. Read the target provider's terms before use.
|
||||
|
||||
**Claude Desktop third-party provider proxy switching**: when CC Switch's built-in proxy gateway forwards Claude Desktop requests to third-party providers, you must also follow the target provider's billing, compliance, and data-retention terms.
|
||||
|
||||
By enabling these features, users accept the related risks. CC Switch is not responsible for account restrictions, warnings, or service suspensions caused by using these features.
|
||||
|
||||
---
|
||||
|
||||
## Thanks
|
||||
|
||||
Thanks to the following contributors for the features and fixes in v3.16.3:
|
||||
|
||||
- [#3789](https://github.com/farion1231/cc-switch/pull/3789): preserve Codex OAuth auth token on takeover, thanks @codeasier.
|
||||
- [#2774](https://github.com/farion1231/cc-switch/pull/2774): fix model / input-token recording on Completions→Anthropic, thanks @LaoYueHanNi.
|
||||
- [#4069](https://github.com/farion1231/cc-switch/pull/4069): fix the deadlock on relaunch after an in-app update, thanks @thisTom.
|
||||
- [#4156](https://github.com/farion1231/cc-switch/pull/4156): fix duplicate provider terminal sessions on macOS, thanks @thisTom.
|
||||
- [#3267](https://github.com/farion1231/cc-switch/pull/3267): fix duplicate YAML keys in the Hermes config, thanks @que3sui.
|
||||
- [#1479](https://github.com/farion1231/cc-switch/pull/1479): fix usage script provider credential resolution, thanks @pa001024.
|
||||
- [#3975](https://github.com/farion1231/cc-switch/pull/3975): add preset search and sorting, thanks @Nastem.
|
||||
- [#4183](https://github.com/farion1231/cc-switch/pull/4183): adjust the preset-provider button appearance and search-box position, thanks @WangJiati.
|
||||
- [#4077](https://github.com/farion1231/cc-switch/pull/4077): add claude-mythos-5 model pricing, thanks @osscv.
|
||||
|
||||
Thanks also to everyone who reported usage billing, local proxy robustness, Codex upgrade, and platform compatibility issues after v3.16.2. Many of these fixes came directly from real-world reproduction details.
|
||||
|
||||
---
|
||||
|
||||
## Download & Install
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) and download the build for your system.
|
||||
|
||||
### System Requirements
|
||||
|
||||
| System | Minimum Version | Architecture |
|
||||
| ------- | ------------------------ | ----------------------------------- |
|
||||
| Windows | Windows 10 and later | x64 |
|
||||
| macOS | macOS 12 (Monterey)+ | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | See table below | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| File | Description |
|
||||
| ---------------------------------------- | ------------------------------------------------ |
|
||||
| `CC-Switch-v3.16.3-Windows.msi` | **Recommended** - MSI installer with auto-update |
|
||||
| `CC-Switch-v3.16.3-Windows-Portable.zip` | Portable build, unzip and run |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| -------------------------------- | ----------------------------------------------------- |
|
||||
| `CC-Switch-v3.16.3-macOS.dmg` | **Recommended** - DMG installer, drag to Applications |
|
||||
| `CC-Switch-v3.16.3-macOS.zip` | Unzip and drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.16.3-macOS.tar.gz` | For Homebrew install and auto-update |
|
||||
|
||||
Homebrew install:
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Upgrade:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Linux assets are available for both **x86_64** and **ARM64** (`aarch64`). Choose the file whose architecture tag matches your machine's `uname -m` output:
|
||||
|
||||
- `CC-Switch-v3.16.3-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- `CC-Switch-v3.16.3-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| Distribution | Recommended Format | Install Command |
|
||||
| --------------------------------------- | ------------------ | --------------------------------------------------------------------- |
|
||||
| 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` | Make executable and run directly, or use AUR |
|
||||
| Other distributions / unsure | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
@@ -0,0 +1,340 @@
|
||||
# CC Switch v3.16.3
|
||||
|
||||
> 🎉 **CC Switch が 100,000 Star を突破しました！**
|
||||
> すべてのユーザー・コントリビューター・Star をくださった方々に感謝します —— 皆さんのおかげでここまで来ました。🙏
|
||||
|
||||
> 💎 **本リリースは Claude Fable 5 モデルの協力のもとで開発されました**——重要かつ間違えやすいロジックの整理を手伝ってくれました: ルーティングテイクオーバー時に本物の上流モデルで課金する帰属チェーン、形式変換経路でのキャッシュ token の計上と重複排除、アプリ内更新の再起動デッドロック、そして Codex 統一セッション履歴の移行 / 復元の不変条件です。本リリースの「バージョン情報」ページに **Fable 5 Verified** バッジを新設したのもこのためです。
|
||||
|
||||
> v3.16.2 でデータの可搬性と使用量の可観測性を広げたのに続き、本リリースは「使用量の課金を本当に正確にする」ことに重きを置いています——本物の上流モデルで課金し、形式変換経路でのキャッシュの二重計上を修正し、Claude Code Workflow のサブ agent の使用量を統計に取り込み（schema v11）、使用量ダッシュボードを一通り刷新しました（全体に効くプロバイダー / モデルフィルタ、ブランドアイコンのツールバー、より安定した残量照会）。あわせて一連のローカルプロキシとプラットフォームの問題を補強し、カスタム User-Agent オーバーライド、Codex 統一セッション履歴のトグル、Claude Fable 5 階層を新設しました。
|
||||
|
||||
**[English →](v3.16.3-en.md) | [中文版 →](v3.16.3-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## 利用ガイド
|
||||
|
||||
本リリースでは **Codex 統一セッション履歴** のトグルを新設しました——セッションの移行 / 復元を伴い、操作を誤ると「セッションが消えた」と誤解しやすいため、まずこのガイドを読むことを強くおすすめします。また使用量統計の数え方とダッシュボードにも多くの調整を加えたので、あわせて以下をご覧ください：
|
||||
|
||||
- **[Codex セッション履歴の統一: 機能紹介と利用ガイド](../guides/codex-unified-session-history-guide-ja.md)**: 「統一 / 移行 / 復元」が実際に何を変えるのか、なぜデータが本当に失われないのか、そしてセッションが見えないときの自己点検と正確な復元の方法を解説します。**このトグルを使った、またはセッションが消えたと心配な方は、まずこちらをお読みください。**
|
||||
- **[使用量統計](../user-manual/ja/4-proxy/4.4-usage.md)**: 使用量ダッシュボードのデータソース（プロキシログ、セッション同期）と集計の仕組みを確認できます。本リリースで全体に効くプロバイダー / モデルフィルタを追加し、ルーティングテイクオーバー時の本物の課金モデルを表示するようにしました。
|
||||
- **[設定](../user-manual/ja/1-getting-started/1.5-settings.md)**: カスタム User-Agent オーバーライド、Codex 統一セッション履歴などのトグルは、プロバイダーフォームの高度なオプションと設定ページにあります。
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## 唯一の公式チャネル（必ずお読みください）
|
||||
>
|
||||
> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。本ソフトウェアは下記の公式チャネルからのみ入手してください：
|
||||
>
|
||||
> | チャネル | 唯一の公式 |
|
||||
> | ------------ | ------------------------------------------------------------------------------ |
|
||||
> | 公式サイト | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | 作者 | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は直ちに操作を中止し、GitHub Issues からご報告ください。
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.16.3 は v3.16.2 に続くメンテナンスアップデートです。前リリースではデータの可搬性と使用量の可観測性の拡張に集中しましたが、本リリースは「使用量の課金を本当に正確にする」ことに重きを置いています——上流が返すエイリアスではなく本物の上流モデルで課金し、形式変換（Chat / Responses / Gemini を Anthropic へ）経路でのキャッシュ token の二重計上を修正し、Claude Code Workflow のサブ agent の使用量をローカル統計に取り込み、schema v11 で各レコードが実際に使用した課金根拠を永続化しました。使用量ダッシュボードもこれにあわせて一通り刷新し、全体に効くプロバイダー / モデルフィルタ、ブランドアイコンのツールバー、より安定した残量照会（失敗時の再試行 + 前回成功した結果の保持）を追加しました。
|
||||
|
||||
さらに本リリースでは、一連のローカルプロキシの堅牢性に関する問題（Content-Type が誤ってラベル付けされた SSE レスポンスの集約、Codex `/responses` のテキスト専用モデル向け画像整流、Codex OAuth 認証情報とテイクオーバー残留の復元、Hermes 設定の重複 YAML キー）を補強し、プロバイダー設定まわりを作り直し（カスタム User-Agent オーバーライド、Codex フォームの高度なオプションへの統合、プリセット検索とソート、Claude Fable 5 階層）、Codex 統一セッション履歴のトグルを新設し、アプリ内更新のハング、Codex のアップグレードによるインストール破損、macOS の重複ターミナルウィンドウなどの問題を修正しました。
|
||||
|
||||
**リリース日**: 2026-06-14
|
||||
|
||||
**Stats**: 59 commits | 130 files changed | +10,223 / -4,232 lines
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **使用量の課金がより正確に**: ルーティングテイクオーバーのトラフィックを本物の上流モデルで課金するようになり（上流が返すエイリアスではなく）、形式変換経路でキャッシュ token を input に二重計上しなくなり、Claude Code Workflow のサブ agent の使用量も統計に取り込みました——schema v11 で課金根拠を永続化します。
|
||||
- **使用量ダッシュボードの刷新**: プロバイダー / モデルフィルタをリクエストログテーブルから全体フィルタへ引き上げ、アプリフィルタをブランドアイコンに変更し、残量照会に失敗時の再試行と「前回成功した結果の保持」を追加して、一度のネットワークのゆらぎでカードが赤くならないようにしました。
|
||||
- **カスタム User-Agent オーバーライド**: プロバイダーにカスタム UA を設定でき、転送・接続性チェック・モデル一覧の 3 か所で一貫して有効になり、UA ホワイトリストで制限する Coding Plan 上流を通過できます（これにより Codex「Kimi For Coding」プリセットを復活させました）。
|
||||
- **Codex 統一セッション履歴**: 公式 Codex セッションとサードパーティセッションが同じ resume 履歴バケットを共有できる任意のトグルを新設し、既存セッションの任意移行と台帳に基づく精密な復元を備えます。
|
||||
- **プロキシとプラットフォームの補強**: 誤ラベルの SSE レスポンスの集約、Codex 画像整流、テイクオーバー残留の復元、Hermes YAML 重複排除。アプリ内更新が「再起動中」でハングしなくなり、Codex のアップグレードでインストールを壊さなくなりました。
|
||||
|
||||
---
|
||||
|
||||
## 追加機能
|
||||
|
||||
### カスタム User-Agent オーバーライド
|
||||
|
||||
プロバイダー設定でカスタム User-Agent を設定できるようになり、プロキシがリクエスト転送、接続性チェック、モデル一覧（`GET /v1/models`）の 3 つの経路で一貫して適用します。これにより、UA ホワイトリストで制限する Coding Plan 上流で「検出は失敗 / モデル一覧は 403 なのにプロキシ本体は正常に動く」という不整合が起きなくなります。Claude と Codex のフォームはいずれも高度なオプションでこのフィールドを公開し、厳選した UA プリセットのドロップダウン（Claude Code / Kilo Code など UA ホワイトリストを通過できるファミリー）とリアルタイムで非ブロッキングな形式検証を備えます。公式プリセットへ切り替えると残っていたカスタム UA は破棄され、リクエストヘッダーを密かに変更しないようにします（[#3671](https://github.com/farion1231/cc-switch/pull/3671)）。
|
||||
|
||||
### Codex 統一セッション履歴
|
||||
|
||||
任意のトグル（設定 → Codex アプリ拡張）を新設し、公式 Codex セッションと CC Switch のサードパーティセッションが同じ resume 履歴バケットを共有できるようにしました。resume セレクタが両者を互いに隠さなくなります。有効化すると、live の `config.toml` は公式の実行を、内蔵 OpenAI プロバイダーをミラーした共有 `custom` model_provider へルーティングします（`auth.json` は変更しません）。デフォルトでは今後のセッションにのみ有効です。有効化ダイアログには既存の公式セッションを共有バケットへ移行できるチェックボックスがあり（世代ごとのバックアップ付き）、無効化ダイアログにはバックアップ台帳に基づく精密な復元が用意されています——バックアップ内で `openai` として記録されたセッションのみを巻き戻し、有効化中に新規作成されたセッションは決して変更しません。
|
||||
|
||||
### 使用量ダッシュボードの全体プロバイダー / モデルフィルタ
|
||||
|
||||
プロバイダーフィルタとモデルフィルタを、リクエストログテーブルの内部からトップバーへ引き上げ、Hero サマリー、トレンドグラフ、リクエストログ、2 つの統計タブ全体に効くようにしました。ダッシュボード全体を特定のソースとモデルで絞り込めます。ソースは表示名で厳密に一致するため「Claude (Session)」のようなセッションのプレースホルダー行も選択でき、モデルは有効な課金モデルで一致し、モデルのドロップダウンは選択したソースに応じてカスケードし、どちらの一覧も現在の期間にデータがある選択肢のみを表示します。
|
||||
|
||||
### モデル価格シードの刷新
|
||||
|
||||
`seed_model_pricing` の全件価格点検を実施しました: 9 個のモデルの価格を新規追加し（Claude Fable 5、Grok 4.3、Mistral Medium 3.5 / Small 4、Qwen 3.7 Max/Plus などを含む）、各ベンダー公式の定価に合わせて既存価格 28 か所を訂正し（GLM、Grok、MiMo、Doubao、Kimi、MiniMax、Mistral、Qwen）、使用量コストの見積りをより正確にしました。各変更はシード（新規インストールに影響）を更新すると同時に、`repair_current_model_pricing` に旧→新のガードを 1 件追加します（既存データベースを修復し、ユーザーが手動で編集した行は上書きしません）。
|
||||
|
||||
### Claude Fable 5 モデル階層
|
||||
|
||||
プロバイダーフォームは、Claude Code と Claude Desktop の両プロキシ経路で `claude-fable-5` を 4 つ目のモデルマッピング階層として公開するようになりました。フォールバックチェーンは fable → opus → default で、公式の降格と一致し、Claude Desktop 1.12603.1+ の検証器で `fable-` プレフィックスを許可しました。4 言語のフォールバックヒントも明確化しました: サードパーティの endpoint である階層を空のままにすると、その階層のモデル名がそのまま透過されて 404 になります（[#3980](https://github.com/farion1231/cc-switch/issues/3980)、[#4026](https://github.com/farion1231/cc-switch/issues/4026)、[#4049](https://github.com/farion1231/cc-switch/issues/4049)）。
|
||||
|
||||
### Unity2.ai パートナープロバイダー
|
||||
|
||||
Unity2.ai（AI API 中継のパートナー）をプリセットとして追加し、管理対象の 7 アプリすべて（Claude Code、Codex、Gemini、OpenCode、OpenClaw、Claude Desktop、Hermes）をカバーしました。各プリセットには紹介登録リンクを付け、4 言語でパートナー宣伝文を補いました。Codex は素の base URL を使用し（このゲートウェイはルートパスに `/responses` を公開）、OpenCode / OpenClaw / Hermes は `/v1` chat-completions の endpoint を使用し、`gpt-5.5` を既定モデルとします。
|
||||
|
||||
### Kimi K2.7 Code モデル
|
||||
|
||||
`kimi-k2.7-code` モデル（入力 $0.95 / 出力 $4.00 / キャッシュ読み取り $0.19、100 万 token あたり、256K コンテキスト）を新規追加し、6 つの公式 Moonshot Kimi プリセットすべて（Claude Code、Codex、Claude Desktop、Hermes、OpenCode、OpenClaw）をこれに向けました。OpenCode / OpenClaw のプリセットは「Kimi K2.7 Code」へ改名しました。価格シードは起動時の冪等な挿入経路で有効になるため、既存ユーザーは移行なしで新価格を取得できます。
|
||||
|
||||
### Codex「Kimi For Coding」プリセットの復活
|
||||
|
||||
Codex「Kimi For Coding」プリセット（`openai_chat`、`kimi-for-coding`、256K コンテキスト）を再追加し、思考モードをデフォルトで有効にしました。以前これを削除したのは、このコーディング endpoint が Codex 既定の `codex-cli` User-Agent を 403 で拒否するためでしたが、現在はプロキシテイクオーバー + カスタム User-Agent オーバーライド（ホワイトリストの UA、例 `claude-cli/*` に設定）を使えば正常に使えます。
|
||||
|
||||
### リクエスト詳細での課金モデル監査
|
||||
|
||||
リクエスト詳細パネルは、「リクエストされたモデル」「課金モデル」がレスポンスのモデルと一致しないときにそれらをすべて表示するようになり、ルーティングテイクオーバーが生む請求を使用量画面から直接照合できます。
|
||||
|
||||
### プリセットプロバイダーの検索とソート
|
||||
|
||||
プリセットプロバイダーのセレクタが、検索・ソート可能な一覧になり、インライン検索ボックスを備えました（虫眼鏡アイコンで切り替え、ESC または外側クリックで畳む）。ボタンはレスポンシブグリッドに変わってサイズが統一され、既定アイコンを表示します。検索はプロバイダーの表示名 / 生の名前のみに一致するため、URL の断片や共有のカテゴリラベルがノイズ一致を生まなくなります（[#3975](https://github.com/farion1231/cc-switch/pull/3975)、[#4183](https://github.com/farion1231/cc-switch/pull/4183)）。
|
||||
|
||||
### Claude Mythos 5 の価格
|
||||
|
||||
内蔵のモデル / 価格表に `claude-mythos-5` モデル（入力 $10 / 出力 $50、100 万 token あたり；キャッシュ読み取り $1.00、キャッシュ書き込み $12.50）を登録し、使用量統計が正しく課金・表示できるようにしました（[#4077](https://github.com/farion1231/cc-switch/pull/4077)）。
|
||||
|
||||
### Fable 5 Verified バッジ
|
||||
|
||||
設定の「バージョン情報」ページが、アプリ名とバージョンの隣に Fable 5 Verified バッジを表示し、これが特別ビルドであることを示すようになりました。バージョンバッジもアプリ名の下に中央揃えしました。
|
||||
|
||||
---
|
||||
|
||||
## 変更
|
||||
|
||||
### Claude Desktop の使用量を Claude に折りたたみ
|
||||
|
||||
ダッシュボードは独立した「Claude Desktop」バケットを表示しなくなりました——これは常に不完全な数字しか表示できませんでした（Desktop のチャット使用量はそもそもプロキシを経由せず、その Code タブのセッションは内蔵の Claude Code ランタイムが共有の `~/.claude/projects` ディレクトリへ書き込んでいるだけです）。Desktop のプロキシトラフィックは表示上 `claude` に折りたたまれますが、記帳層はルーティングテイクオーバー課金の監査のために引き続き自身の `app_type` で記録し、本物の値はリクエスト詳細パネルで確認できます。
|
||||
|
||||
### 軽量化したプロバイダーヘルスチェック
|
||||
|
||||
プロバイダーヘルスチェックは、本物のストリーミングモデルリクエストを送らなくなりました（多くのサードパーティプロバイダーが 401/403/WAF でブロックし、利用不可の誤検知を生むため）。代わりにプロバイダーの `base_url` へ軽量な HTTP 到達性プローブを 1 回行います: あらゆる HTTP レスポンスを到達可能とみなし、DNS / 接続 / TLS / タイムアウトのみを失敗とします。公式プロバイダー（OAuth を使用し、base_url が意図的に空で、信頼できる到達性ターゲットがない）は接続性チェックのボタンを隠します。従来の「本物のリクエストを送る」確認ダイアログ、テストモデル / プロンプトのフィールドは削除し、劣化レイテンシのしきい値を 6s、タイムアウトを 8s としました。この到達性チェックは決してサーキットブレーカーをリセットしません——到達可能 ≠ 利用可能（403 を返す host は到達可能でも、本物のトラフィックには壊れています）。フェイルオーバーの判定は引き続き本物のプロキシトラフィックのみで駆動されます。
|
||||
|
||||
### Codex の高度なオプション領域の統合
|
||||
|
||||
Codex プロバイダーフォームは、ローカルルーティング、モデルマッピング、推論オーバーライド、カスタム User-Agent を展開可能な高度なオプション領域に折りたたみ、Claude フォームと揃えました（UA が設定されているか、ローカルルーティングが有効なときは自動展開）。カスタム User-Agent はネイティブ Responses プロバイダーでも設定できるようになりました。以前は `openai_chat` ルーティングを有効にしたときにしか触れられませんでした。
|
||||
|
||||
### 使用量ツールバーとレイアウトの刷新
|
||||
|
||||
アプリフィルタはブランドアイコン（ProviderIcon 経由、「すべて」はグリッドアイコン）で描画するように変更し、狭いウィンドウで折り返すと見栄えの悪かったテキストタブを置き換えました。使用量 Hero も選択したアプリのブランドアイコンを表示し、Codex のテーマ色をエメラルドからニュートラルグレーへ変更して、OpenAI のモノクロブランドに合わせました。クリックで循環切り替えしていた更新ボタンは、ローカライズした「オフ」ラベルを持つドロップダウン選択に変更し、トップバーのコントロールも圧縮して幅のグループを揃え、長すぎる日付範囲のラベルは省略表示するようにしました。
|
||||
|
||||
### バージョン情報パネルの読み込みを高速化
|
||||
|
||||
設定の「バージョン情報」パネルが段階的に読み込むようになりました: アプリのバージョンバッジは解決した瞬間に表示され、ツールのプローブを待たなくなります。各ツールカードは自身のバージョン検出が完了した時点で即座に更新されます（プローブは直列ではなく並行に実行）。プローブ結果はアプリのセッション中、10 分の TTL 付きでキャッシュされるため、「バージョン情報」タブを再度開くとキャッシュ値を再利用し、期限切れの項目だけをバックグラウンドで再検証します。毎回 6 つのツールすべてを再プローブすることはなくなりました。
|
||||
|
||||
### 火山方舟 Coding Plan の宣伝更新
|
||||
|
||||
火山方舟（Volcengine Ark）プリセットを 6 アプリすべてで新しい Coding Plan 招待リンクへ更新し（旧 Agent Plan / キャンペーンリンクを置き換え）、4 言語でパートナー宣伝文を刷新しました（2 か月 75% 割引 + 招待コード 6J6FV5N2）。製品名も Agent Plan から Coding Plan へ訂正しました。
|
||||
|
||||
### MiniMax を通常プロバイダーへ降格
|
||||
|
||||
MiniMax の金色のパートナースター印と API key 宣伝バナーを削除し（全プリセットから `isPartner` フラグを除去）、引き続き通常の `cn_official` プロバイダーとしてアイコンとテーマを保持します。宣伝文は休眠状態のまま残し、必要であれば 1 行で提携関係を再有効化できます。
|
||||
|
||||
### LemonData を削除、SudoCode を降格
|
||||
|
||||
LemonData プロバイダープリセットを完全に削除し（宣伝文、アイコン、スポンサー項目もあわせて）、SudoCode をパートナーから通常の `third_party` プロバイダーへ降格しました（`isPartner` フラグと宣伝文を外し、アイコンは保持）。
|
||||
|
||||
### AtlasCloud Codex GLM 5.1 のコンテキストウィンドウ
|
||||
|
||||
AtlasCloud Codex プリセットの `zai-org/glm-5.1` モデルに 200,000 token のコンテキストウィンドウを宣言し、ほかの GLM 5.1 プリセット項目に揃えました。
|
||||
|
||||
---
|
||||
|
||||
## 修正
|
||||
|
||||
### ルーティングテイクオーバーのトラフィックを本物の上流モデルで課金
|
||||
|
||||
リクエストが別の上流へルーティングされた場合（env モデルマッピング、Claude Desktop ルーティング、Copilot 正規化、Codex chat オーバーライド）、プロキシは以前、上流が返したモデルで帰属・課金していたため、kimi / glm の token を `claude-*` として記録・課金し、コストが約 5〜25 倍に過大評価されていました。現在は転送器が本物のアウトバウンドモデルを捕捉し、「上流が返した値 → アウトバウンドモデル → クライアントのエイリアス」の順で帰属し、各行に実際に使用した課金根拠を永続化します（schema v11）。この根拠はコストのバックフィルと 30 日 rollup のプルーニングまで一貫して使われます。Claude Desktop のトラフィックも自身の `app_type` で記録されるようになり、その価格オーバーライドが正しく効くようになりました。
|
||||
|
||||
### 形式変換経路での使用量計上
|
||||
|
||||
プロキシの各形式変換経路（Chat、Responses、Gemini を Anthropic へ）での token / キャッシュの計上を監査・修正しました。プロキシは実際に返ったモデルを記録し、`stream_options.include_usage` を注入して OpenAI 互換の上流がストリーミング時に usage を吐くようにし、Claude←OpenAI 経路では `cache_read` と `cache_creation` を input から除外してキャッシュ token の二重計上を防ぎ、Gemini のキャッシュ済みプロンプト token を差し引き、完全にキャッシュヒットしたリクエストも引き続き記録し、過去にリクエスト数を水増ししていた合成の全ゼロ usage をスキップするようになりました（[#2774](https://github.com/farion1231/cc-switch/pull/2774)）。
|
||||
|
||||
### アプリ内更新がハングしなくなった
|
||||
|
||||
アプリ内から更新をインストールするとき、「再起動中」の画面でハングしなくなりました——以前は新版がインストール済みなのに、手動で強制終了せざるを得ない状況が起きていました。ダウンロード—インストール—再起動の一連の流れは、完全にバックエンドで実行するようになり（`install_update_and_restart` コマンドを新設）、プラットフォームごとにインストール順序を決め、再実行の前にまず単一インスタンスロックを破棄します。アプリパッケージがすでに置き換えられた後に古い WebView が JS を走らせ続けることに依存しなくなりました。終了リクエストも分類して、再起動リクエストが Tauri の既定フローに落ちるようにし、ウィンドウ状態プラグインのミューテックスでデッドロックしないようにしました（[#4069](https://github.com/farion1231/cc-switch/pull/4069)、[#4074](https://github.com/farion1231/cc-switch/pull/4074)）。
|
||||
|
||||
### Codex のアップグレードがインストールを壊さなくなった
|
||||
|
||||
設定の「バージョン情報」ページから Codex をアップグレードしても、「Missing optional dependency @openai/codex-…」エラーを投げなくなりました。アップグレードのチェーンは以前まず `codex update` を実行しますが、これは npm インストール下では実質的に素の再インストールであり、対応するプラットフォームのバイナリがインストールされていなくても成功を報告していました。現在は Codex を「self-update 優先」経路から除外し、runnable 検出が「アンインストール + 再インストール」の自己修復を駆動するようにしました（npm 管理のインストールに限定）。これが、欠けたプラットフォームバイナリを本当に補える唯一の修正です。
|
||||
|
||||
### テイクオーバー時に Codex OAuth 認証情報を保持
|
||||
|
||||
Codex プロバイダーでプロキシテイクオーバーを有効にするとき、`ANTHROPIC_AUTH_TOKEN` プレースホルダーを剥がさなくなりました——以前これはホットスイッチ、新規インストール、そして旧バージョンがすでに剥がしてしまった live 設定で、Claude Code のログインを壊していました。現在は管理対象（非 Copilot）の Codex プロバイダーに対して、URL のみのプロバイダーを含め無条件にこのプレースホルダーを注入します。GitHub Copilot の挙動（API_KEY のみ）は変わりません（[#3789](https://github.com/farion1231/cc-switch/pull/3789)、[#3784](https://github.com/farion1231/cc-switch/issues/3784)）。
|
||||
|
||||
### 設定ディレクトリをまたぐ切り替えでのテイクオーバー残留の復元
|
||||
|
||||
プロキシテイクオーバーが有効なときに設定ディレクトリを変更してアプリを再起動しても、Claude / Codex / Gemini を失効したローカルプロキシに向けたままにしなくなりました。現在は旧インスタンスが再起動の前にテイクオーバーされた live ファイルを先に復元し、初回実行のインポートはテイクオーバープレースホルダーをプロバイダーとして永続化することを拒否し、SSOT の復元も書き戻す前に、現在のプロバイダーの設定にプレースホルダーが含まれないことを検証します（[#4076](https://github.com/farion1231/cc-switch/pull/4076)）。
|
||||
|
||||
### 形式変換フォールバックでの誤ラベル SSE レスポンスの集約
|
||||
|
||||
Claude / Codex の形式変換を経たリクエストで、MaaS ゲートウェイが `stream:false` のリクエストを強制的にストリーミングし、非 SSE の Content-Type で SSE レスポンスボディを返したとき、難解な 422「Failed to parse upstream response」で失敗しなくなりました。プロキシは解析失敗時に SSE かどうかを検出し、チャンクを単一の JSON に集約してから既存の変換器を走らせ、クライアントが引き続き有効な非ストリーミングレスポンスを受け取れるようにします。残った解析失敗には content-type、エンコーディング、レスポンスボディの抜粋などの診断情報を付け、deflate のデコードも先に zlib を、次に素のストリームを試すように変更しました（[#2234](https://github.com/farion1231/cc-switch/pull/2234)）。
|
||||
|
||||
### Hermes 設定の重複 YAML キー
|
||||
|
||||
Hermes 設定の書き込みは、重複したトップレベルキー（`mcp_servers` など）を累積しなくなりました。これは「Failed to parse Hermes config as YAML: duplicate entry with key」エラーを引き起こしていました。セクションの置換は、追加へ退化する代わりに、残りのテキストから古いコピーをすべて取り除くようになりました。重複排除のセーフティネットは LF と CRLF の行末を両方処理します。修復時には最後（最新）のコピーを保持し、Hermes 自身の PyYAML ベースの「後勝ち」セマンティクスに揃えます（[#3267](https://github.com/farion1231/cc-switch/pull/3267)、[#3633](https://github.com/farion1231/cc-switch/issues/3633)、[#2973](https://github.com/farion1231/cc-switch/issues/2973)、[#2529](https://github.com/farion1231/cc-switch/issues/2529)、[#3310](https://github.com/farion1231/cc-switch/issues/3310)、[#3762](https://github.com/farion1231/cc-switch/issues/3762)）。
|
||||
|
||||
### 使用量照会の堅牢性とエラーの明確さ
|
||||
|
||||
使用量カードは、一度の瞬間的なゆらぎだけで赤くならなくなりました: 照会は一度再試行し、ネットワーク / タイムアウト / 5xx のような一時的な失敗下では前回成功した結果を最大 10 分間表示し続けます。一方、確定的な失敗（認証、空の key、未知のプロバイダー、4xx）は即座に表面化してスナップショットをクリアし、認証情報の変更後に古い残量が再び現れるのを防ぎます。ネイティブ残量 / Coding Plan / サブスクリプション照会のタイムアウトは、応答の遅い国際 endpoint に合わせて 10s から 15s へ引き上げました。Coding Plan も空白の失敗ではなく、明確な「API key is empty」/「Unknown coding plan provider」エラーを返すようになりました。
|
||||
|
||||
### 使用量スクリプトのプロバイダー認証情報の解決
|
||||
|
||||
カスタム JS スクリプトの使用量照会は、以前 env フィールドを推測して `{{apiKey}}` / `{{baseUrl}}` を解決していたため、認証情報を別の場所に置くアプリ（Codex の `auth.OPENAI_API_KEY` に加え `config.toml` の base_url など）は、プロバイダーが完全に設定されていても常に空の値となり失敗していました。スクリプト照会とそのテスト / プレビューは、ネイティブ残量経路と同じアプリごとの認証情報リゾルバを再利用するようになり、スクリプト内で明示的に記入した非空の値は引き続き優先されます（[#1479](https://github.com/farion1231/cc-switch/pull/1479)）。
|
||||
|
||||
### Claude Code Workflow サブ agent の使用量集計
|
||||
|
||||
ローカル（プロキシなし）のセッションログ使用量集計は、以前 Claude Code Workflow のサブ agent のトラフィックを取りこぼしており、全体の使用量が約 4.1% 過小評価されていました（workflow / subagent のセッションレコードに集中）。スキャナーはさらに一段深い `subagents/workflows/wf_*/` のレコードディレクトリまで掘り下げるようになり、パーサーも `stop_reason` を欠いているがすでに input / キャッシュ token のコストを生んだ assistant メッセージを捨てなくなりました。重複排除のロジックは変わらないため、重複計上はしません。
|
||||
|
||||
### Codex `/responses` のテキスト専用モデル向け画像整流
|
||||
|
||||
画像を伴い、テキストのみ対応の OpenAI-chat モデル（DeepSeek `deepseek-v4-flash` など）へルーティングされた Codex `/responses` リクエストが、HTTP 400「unknown variant `image_url`」で失敗しなくなりました。メディア整流器が Codex アダプターもカバーするようになり、responses の `input` 内の `input_image` ブロックをスキャンします。これにより、既知のテキスト専用モデルに対しては画像をプロアクティブに剥がし、上流が「画像非対応」を報告したときにも画像を置き換えて再試行できます。
|
||||
|
||||
### 智譜 Coding Plan のクォータウィンドウの誤ラベル
|
||||
|
||||
智譜 Coding Plan ビューは、各週周期の最後の数時間で 5 時間ウィンドウと週ウィンドウを取り違えてラベル付けしなくなりました。両ウィンドウは今や明示的な `unit` フィールドで分類され（3 = 5 時間、6 = 週）、リセット時刻の昇順ソートに頼らなくなりました——後者はユーザーが週クォータを最も照会するタイミングで、ちょうど両者を取り違えてラベル付けしていました。フィールドが欠けているときは引き続き従来のリセット時刻ヒューリスティックへフォールバックします（[#3036](https://github.com/farion1231/cc-switch/pull/3036)）。
|
||||
|
||||
### macOS の重複プロバイダーターミナルウィンドウ
|
||||
|
||||
macOS でプロバイダーターミナルを起動するとき、コマンドセッションの隣に空のウィンドウをもう 1 つ開かなくなりました。Terminal.app はコールドスタート時に `activate` ではなく `launch` を使い、Ghostty は初期コマンドを使うことで、単一のセッションだけを開きます。AppleScript 経路が失敗したときのフォールバックも残してあります（[#4156](https://github.com/farion1231/cc-switch/pull/4156)）。
|
||||
|
||||
### Claude Desktop モデルマッピングのプレースホルダー
|
||||
|
||||
Claude Desktop モデルマッピングフォームは、以前「メニュー表示名」と「リクエストモデル」の 2 列で一貫しないブランド例（DeepSeek vs Kimi）を使い、ある表示名が無関係なモデルへマッピングされるかのように見せていました。現在は両方のプレースホルダーが各行のロールから導かれ、ブランドの一貫性を保ち、軽量な Haiku 階層は flash の例を使います。
|
||||
|
||||
### ポップオーバーが全画面パネルに隠れる
|
||||
|
||||
プロバイダープリセット検索のようなポップオーバーやツールチップが、全画面パネルの後ろに描画されてクリックが効かないように見える問題がなくなりました。これらの z-index を全画面オーバーレイの上に引き上げつつ、モーダルダイアログよりは低く保ちました。
|
||||
|
||||
### ToggleRow アイコンの縮み
|
||||
|
||||
トグル行のアイコンは、長い説明と並んでも縮んだり歪んだりしなくなり、複数行のテキストの隣でアイコンが固定サイズを保ちます。
|
||||
|
||||
---
|
||||
|
||||
## ドキュメント
|
||||
|
||||
### Release Notes の貢献者謝辞の復元
|
||||
|
||||
v3.16.1 と v3.16.2 の release notes の貢献者謝辞を 3 言語で復元しました。
|
||||
|
||||
---
|
||||
|
||||
## アップグレード時の注意
|
||||
|
||||
### 価格ライブラリ schema v11 の自動移行
|
||||
|
||||
本リリースは `proxy_request_logs` に `pricing_model` 列を新設し、`request_model` + `pricing_model` で rollup を再構築しました。起動時に自動移行し、手動操作は不要です。過去の行のコストは書き込み時に確定済みで再計算されません（`app_type="claude"` の行はネイティブと変換の 2 種類のソースが混在しています）。本物だが当時課金されなかったテイクオーバー行のみがゼロコストのまま残り、価格が補われた後にバックフィルされます。
|
||||
|
||||
### モデルマッピングに 4 つ目の階層（Fable 5）を追加
|
||||
|
||||
Claude Code と Claude Desktop のモデルマッピングは 4 階層（Sonnet / Opus / Fable / Haiku）になりました。従来の 3 階層プロバイダーは、再度開いて保存すると `claude-fable-5` 階層が補われます。この階層を空のままにすると Sonnet を継承します。注意: サードパーティの endpoint でいずれかの階層を空のままにすると、その階層のモデル名がそのまま透過されて 404 になる可能性があるため、必要に応じて記入してください。
|
||||
|
||||
### 「Kimi For Coding」プリセットはプロキシテイクオーバー + ホワイトリスト UA が必要
|
||||
|
||||
復活した Codex「Kimi For Coding」プリセットは、既定の `codex-cli` User-Agent をそのまま使うと依然 403 になります。利用するには、プロキシテイクオーバーを有効にし、プロバイダーの高度なオプションでカスタム User-Agent をホワイトリストの UA（`claude-cli/*` など）に設定してください。
|
||||
|
||||
### プロバイダーヘルスチェックのセマンティクス変更
|
||||
|
||||
ヘルスチェックは「本物のモデルリクエストを送る」から「HTTP 到達性プローブ」へ変わりました。到達可能 ≠ 利用可能であることにご注意ください: 403 を返す host は到達可能でも、本物のトラフィックには壊れている可能性があります。フェイルオーバーの判定は引き続き本物のプロキシトラフィックのみで駆動され、ヘルスチェックの影響を受けません。
|
||||
|
||||
---
|
||||
|
||||
## リスク通知
|
||||
|
||||
本リリースは、リバースプロキシ系機能に関する以前のリスク通知を引き続き適用します。
|
||||
|
||||
**Codex OAuth リバースプロキシ**: ChatGPT サブスクリプションの Codex OAuth をリバースプロキシ経由で使用すると、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 release notes](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
|
||||
|
||||
**Codex サードパーティプロバイダー Chat ルーティング**: CC Switch ローカルプロキシで Codex リクエストを変換し、サードパーティプロバイダーへ転送する場合、課金・コンプライアンス・データ保持に関する制約はプロバイダーごとに異なります。利用前に対象プロバイダーの利用規約を確認してください。
|
||||
|
||||
**Claude Desktop サードパーティプロバイダープロキシ切り替え**: CC Switch 内蔵のプロキシゲートウェイで Claude Desktop のリクエストをサードパーティプロバイダーへ転送する場合も、対象プロバイダーの課金・コンプライアンス・データ保持に関する規約に従う必要があります。
|
||||
|
||||
上記機能を有効化したユーザーは、関連するリスクを自ら負うものとします。CC Switch は、これらの機能の利用によって発生したアカウント制限、警告、サービス停止について責任を負いません。
|
||||
|
||||
---
|
||||
|
||||
## 謝辞
|
||||
|
||||
v3.16.3 で機能と修正を届けてくださった以下のコントリビューターに感謝します：
|
||||
|
||||
- [#3789](https://github.com/farion1231/cc-switch/pull/3789): テイクオーバー時に Codex OAuth 認証情報を保持、@codeasier に感謝。
|
||||
- [#2774](https://github.com/farion1231/cc-switch/pull/2774): Completions を Anthropic へ変換する際に実際に返ったモデルを記録せず input token の計算が誤っていた問題を修正、@LaoYueHanNi に感謝。
|
||||
- [#4069](https://github.com/farion1231/cc-switch/pull/4069): アプリ内更新後の再起動デッドロックを修正、@thisTom に感謝。
|
||||
- [#4156](https://github.com/farion1231/cc-switch/pull/4156): macOS の重複プロバイダーターミナルウィンドウを修正、@thisTom に感謝。
|
||||
- [#3267](https://github.com/farion1231/cc-switch/pull/3267): Hermes 設定の重複 YAML キーを修正、@que3sui に感謝。
|
||||
- [#1479](https://github.com/farion1231/cc-switch/pull/1479): 使用量スクリプトのプロバイダー認証情報の解決を修正、@pa001024 に感謝。
|
||||
- [#3975](https://github.com/farion1231/cc-switch/pull/3975): プリセットプロバイダーの検索とソートを追加、@Nastem に感謝。
|
||||
- [#4183](https://github.com/farion1231/cc-switch/pull/4183): プリセットプロバイダーボタンの外観と検索ボックスの位置を調整、@WangJiati に感謝。
|
||||
- [#4077](https://github.com/farion1231/cc-switch/pull/4077): claude-mythos-5 モデルの価格を追加、@osscv に感謝。
|
||||
|
||||
v3.16.2 リリース後に使用量の課金、ローカルプロキシの堅牢性、Codex のアップグレード、プラットフォーム互換性の問題を報告してくださったすべてのユーザーにも感謝します。今回の多くの修正は、実際の利用シーンから得られた再現情報に基づいています。
|
||||
|
||||
---
|
||||
|
||||
## ダウンロードとインストール
|
||||
|
||||
[Releases](https://github.com/farion1231/cc-switch/releases/latest) から、お使いのシステムに対応するビルドをダウンロードしてください。
|
||||
|
||||
### システム要件
|
||||
|
||||
| システム | 最低バージョン | アーキテクチャ |
|
||||
| -------- | ------------------------ | ----------------------------------- |
|
||||
| Windows | Windows 10 以降 | x64 |
|
||||
| macOS | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 下表を参照 | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| ファイル | 説明 |
|
||||
| ---------------------------------------- | -------------------------------------------- |
|
||||
| `CC-Switch-v3.16.3-Windows.msi` | **推奨** - 自動更新対応の MSI インストーラー |
|
||||
| `CC-Switch-v3.16.3-Windows-Portable.zip` | ポータブル版、展開してそのまま実行できます |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| -------------------------------- | ------------------------------------------------------ |
|
||||
| `CC-Switch-v3.16.3-macOS.dmg` | **推奨** - DMG インストーラー、Applications へドラッグ |
|
||||
| `CC-Switch-v3.16.3-macOS.zip` | 展開して Applications へドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.16.3-macOS.tar.gz` | Homebrew インストールと自動更新用 |
|
||||
|
||||
Homebrew インストール：
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Linux アセットは **x86_64** と **ARM64**（`aarch64`）の両方を提供します。ファイル名にアーキテクチャ識別子が含まれているため、マシンの `uname -m` 出力に合わせて選択してください：
|
||||
|
||||
- `CC-Switch-v3.16.3-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- `CC-Switch-v3.16.3-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| ディストリビューション | 推奨形式 | インストール方法 |
|
||||
| --------------------------------------- | ----------- | ------------------------------------------------------------------------- |
|
||||
| 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` |
|
||||
@@ -0,0 +1,340 @@
|
||||
# CC Switch v3.16.3
|
||||
|
||||
> 🎉 **CC Switch 突破 100,000 Star！**
|
||||
> 感谢每一位用户、贡献者与 Star —— 是你们让它走到这里。🙏
|
||||
|
||||
> 💎 **本版由 Claude Fable 5 模型协助开发**——它帮忙梳理清楚了多处关键且容易出错的逻辑：路由接管时按真实上游模型计费的归因链、格式转换路径上缓存 token 的计量与去重、应用内更新的重启死锁，以及 Codex 统一会话历史的迁移 / 还原不变量。这也是本版在「关于」页新增 **Fable 5 Verified** 标识的由来。
|
||||
|
||||
> 在 v3.16.2 拓宽数据可携带性与用量观测之后，这一版把重心放在「让用量计费真正准确」——按真实上游模型计费、修正格式转换路径上的缓存双算、把 Claude Code Workflow 子 agent 的用量纳入统计（schema v11），并对用量看板做了一轮改版（全局供应商 / 模型筛选、品牌图标工具栏、更稳的额度查询）；同时加固了一批本地代理与平台问题，新增自定义 User-Agent 覆盖、Codex 统一会话历史开关与 Claude Fable 5 档位。
|
||||
|
||||
**[English →](v3.16.3-en.md) | [日本語版 →](v3.16.3-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 使用攻略
|
||||
|
||||
本版新增了 **Codex 统一会话历史** 开关——它涉及会话的迁移 / 还原，操作不当时容易让人误以为"会话丢了"，强烈建议先读这篇攻略；用量统计的口径和看板这一版也做了较多调整，一并附上：
|
||||
|
||||
- **[Codex 统一会话历史：功能介绍与使用攻略](../guides/codex-unified-session-history-guide-zh.md)**：讲清"统一 / 迁移 / 还原"到底改了什么、为什么数据不会真正丢失，以及看不到会话时如何自查与精确还原。**用过这个开关、或担心会话丢失，请务必先读。**
|
||||
- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：了解用量看板的数据来源（代理日志、会话同步）与统计口径，本版新增了全局的供应商 / 模型筛选，并把路由接管的真实计价模型展示了出来。
|
||||
- **[设置](../user-manual/zh/1-getting-started/1.5-settings.md)**：自定义 User-Agent 覆盖、Codex 统一会话历史等开关都在供应商表单的高级选项与设置页里。
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## 唯一官方渠道声明（请务必阅读）
|
||||
>
|
||||
> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。请仅通过下列官方渠道获取本软件：
|
||||
>
|
||||
> | 类别 | 唯一官方 |
|
||||
> | -------- | ------------------------------------------------------------------------------ |
|
||||
> | 官网 | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | 源码 | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | 下载 | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | 作者 | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.16.3 是 v3.16.2 之后的一版维护更新。在上一版集中拓宽数据可携带性与用量观测之后，这一版把重心放在「让用量计费真正准确」这件事上——按真实上游模型计费而非上游回显、修正格式转换（Chat / Responses / Gemini 转 Anthropic）路径上的缓存 token 双算、把 Claude Code Workflow 子 agent 的用量纳入本地统计，并以 schema v11 持久化每条记录实际使用的定价依据；用量看板也随之做了一轮改版，新增全局的供应商 / 模型筛选、品牌图标工具栏，以及更稳的额度查询（失败重试 + 保留上次成功结果）。
|
||||
|
||||
此外，本版还加固了一批本地代理的稳健性问题（错标 Content-Type 的 SSE 响应聚合、Codex `/responses` 文本模型图像整流、Codex OAuth 凭据与接管残留的恢复、Hermes 配置重复 YAML 键），重做了供应商配置体验（自定义 User-Agent 覆盖、Codex 表单统一进高级选项、预设搜索与排序、Claude Fable 5 档位），新增 Codex 统一会话历史开关，并修复了应用内更新卡死、Codex 升级损坏安装、macOS 重复终端窗口等问题。
|
||||
|
||||
**发布日期**：2026-06-14
|
||||
|
||||
**更新规模**：59 commits | 130 files changed | +10,223 / -4,232 lines
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- **用量计费更准**：路由接管的流量现在按真实上游模型计费（而非上游回显的别名），格式转换路径不再把缓存 token 重复计入 input，Claude Code Workflow 子 agent 的用量也纳入了统计——以 schema v11 持久化定价依据。
|
||||
- **用量看板改版**：供应商 / 模型筛选从请求日志表提升为全局筛选，应用筛选改用品牌图标，额度查询加入失败重试与「保留上次成功结果」，单次网络抖动不再让卡片变红。
|
||||
- **自定义 User-Agent 覆盖**：供应商可设置自定义 UA，并在转发、连通性检测、模型列表三处一致生效，绕过按 UA 白名单放行的 Coding Plan 上游（借此恢复了 Codex「Kimi For Coding」预设）。
|
||||
- **Codex 统一会话历史**：新增可选开关，让官方 Codex 会话与第三方会话共享同一份 resume 历史桶，附带可选的存量迁移与按账本精确还原。
|
||||
- **代理与平台加固**：错标 SSE 响应聚合、Codex 图像整流、接管残留恢复、Hermes YAML 去重；应用内更新不再卡在「重启中」，Codex 升级不再把安装弄坏。
|
||||
|
||||
---
|
||||
|
||||
## 新功能
|
||||
|
||||
### 自定义 User-Agent 覆盖
|
||||
|
||||
供应商配置现在可以设置自定义 User-Agent，并由代理在请求转发、连通性检测和模型列表（`GET /v1/models`）三条路径上一致应用，因此按 UA 白名单放行的 Coding Plan 上游不会再出现「检测失败 / 模型列表 403、但代理本身却能正常工作」的不一致。Claude 和 Codex 表单都在高级选项里暴露该字段，配有精选的 UA 预设下拉（Claude Code / Kilo Code 等能通过 UA 白名单的家族）和实时、非阻塞的格式校验；切换到官方预设时会丢弃残留的自定义 UA，避免悄悄改动请求头（[#3671](https://github.com/farion1231/cc-switch/pull/3671)）。
|
||||
|
||||
### Codex 统一会话历史
|
||||
|
||||
新增一个可选开关（设置 → Codex 应用增强），让官方 Codex 会话与 CC Switch 的第三方会话共享同一份 resume 历史桶，resume 选择器不再把两者互相隐藏。开启后，live 的 `config.toml` 会把官方运行路由到一个镜像内建 OpenAI 供应商的共享 `custom` model_provider（`auth.json` 不动）。默认只对未来会话生效；开启弹窗提供一个勾选项，可把已有官方会话迁入共享桶（含逐代备份），关闭弹窗则提供按备份账本精确还原——只回退备份中记录为 `openai` 的会话，开启期间新建的会话永不被改动。
|
||||
|
||||
### 用量看板全局供应商 / 模型筛选
|
||||
|
||||
供应商和模型筛选从请求日志表内部提升到了顶栏，对 Hero 汇总、趋势图、请求日志和两个统计页签全局生效，可以把整个看板按某个来源和模型缩小范围。来源按展示名精确匹配（因此像「Claude (Session)」这样的会话占位行也可选），模型按有效计价模型匹配，模型下拉会随所选来源级联，且两个列表只列出当前时间范围内有数据的选项。
|
||||
|
||||
### 模型定价种子刷新
|
||||
|
||||
对 `seed_model_pricing` 做了一次全量核价：新增 9 个模型的定价（含 Claude Fable 5、Grok 4.3、Mistral Medium 3.5 / Small 4、Qwen 3.7 Max/Plus 等），并按各厂商官方 list 价订正了 28 处既有价格（GLM、Grok、MiMo、Doubao、Kimi、MiniMax、Mistral、Qwen），让用量成本估算更准确。每处改动都同时更新种子（影响全新安装）并向 `repair_current_model_pricing` 加一条旧→新守卫（修复存量数据库，且不覆盖用户手改过的行）。
|
||||
|
||||
### Claude Fable 5 模型档位
|
||||
|
||||
供应商表单现在在 Claude Code 和 Claude Desktop 两条代理路径上都暴露 `claude-fable-5` 作为第四个模型映射档位，回落链为 fable → opus → default，与官方降级一致，并为 Claude Desktop 1.12603.1+ 的校验器放行了 `fable-` 前缀。四语回落提示也做了澄清：在第三方端点上把某一档留空，会原样透传该档的字面模型名并 404（[#3980](https://github.com/farion1231/cc-switch/issues/3980)、[#4026](https://github.com/farion1231/cc-switch/issues/4026)、[#4049](https://github.com/farion1231/cc-switch/issues/4049)）。
|
||||
|
||||
### Unity2.ai 合作伙伴供应商
|
||||
|
||||
新增 Unity2.ai（一个 AI API 中转合作伙伴）作为预设，覆盖全部 7 个受管应用（Claude Code、Codex、Gemini、OpenCode、OpenClaw、Claude Desktop、Hermes），每个预设都带上推广注册链接，并在四种语言里补充了合作伙伴推广文案。Codex 使用裸 base URL（该网关在根路径暴露 `/responses`），OpenCode / OpenClaw / Hermes 使用 `/v1` chat-completions 端点并以 `gpt-5.5` 为预设模型。
|
||||
|
||||
### Kimi K2.7 Code 模型
|
||||
|
||||
新增 `kimi-k2.7-code` 模型（输入 $0.95 / 输出 $4.00 / 缓存读取 $0.19，每百万 token，256K 上下文），并把全部 6 个官方 Moonshot Kimi 预设（Claude Code、Codex、Claude Desktop、Hermes、OpenCode、OpenClaw）指向它，OpenCode / OpenClaw 预设更名为「Kimi K2.7 Code」。定价种子通过启动时的幂等插入路径生效，存量用户无需迁移即可获得新价。
|
||||
|
||||
### 恢复 Codex「Kimi For Coding」预设
|
||||
|
||||
重新加入 Codex「Kimi For Coding」预设（`openai_chat`、`kimi-for-coding`、256K 上下文），默认开启思考模式。此前它被移除是因为该编程端点会以 403 拒绝 Codex 默认的 `codex-cli` User-Agent；现在借助代理接管 + 自定义 User-Agent 覆盖（设为 `claude-cli/*` 等白名单 UA）即可正常使用。
|
||||
|
||||
### 请求详情的计价模型审计
|
||||
|
||||
请求详情面板现在会在「请求的模型」「计价模型」与响应模型不一致时把它们都显示出来，让路由接管产生的账单可以直接在用量界面里核对。
|
||||
|
||||
### 预设供应商搜索与排序
|
||||
|
||||
预设供应商选择器现在是一个可搜索、可排序的列表，配有内联搜索框（点放大镜图标切换，按 ESC 或点击外部收起）。按钮改为响应式网格、尺寸统一并显示默认图标，搜索只匹配供应商的展示名 / 原始名，因此 URL 片段和共享的分类标签不会再产生噪声匹配（[#3975](https://github.com/farion1231/cc-switch/pull/3975)、[#4183](https://github.com/farion1231/cc-switch/pull/4183)）。
|
||||
|
||||
### Claude Mythos 5 定价
|
||||
|
||||
在内置模型 / 定价表里登记 `claude-mythos-5` 模型（输入 $10 / 输出 $50，每百万 token；缓存读取 $1.00、缓存写入 $12.50），让用量统计能正确计价并展示（[#4077](https://github.com/farion1231/cc-switch/pull/4077)）。
|
||||
|
||||
### Fable 5 Verified 标识
|
||||
|
||||
设置「关于」页现在会在应用名与版本旁展示 Fable 5 Verified 标识，标明这是一个特别构建，版本徽标也居中到了应用名下方。
|
||||
|
||||
---
|
||||
|
||||
## 变更
|
||||
|
||||
### Claude Desktop 用量折叠进 Claude
|
||||
|
||||
看板不再展示独立的「Claude Desktop」分桶——它一直只能显示一个不完整的数字（Desktop 聊天用量根本不经过代理，而其 Code 页签的会话只是内嵌的 Claude Code 运行时写进共享的 `~/.claude/projects` 目录）。Desktop 的代理流量现在在展示上折叠进 `claude`，但记账层仍按它自己的 `app_type` 记录以便路由接管计费审计，真实值可在请求详情面板看到。
|
||||
|
||||
### 轻量化供应商健康检查
|
||||
|
||||
供应商健康检查不再发送真实的流式模型请求（很多第三方供应商会以 401/403/WAF 拦截，造成误报不可用），改为对供应商 `base_url` 做一次轻量的 HTTP 可达性探测：任何 HTTP 响应都视为可达，只有 DNS / 连接 / TLS / 超时才算失败。官方供应商（使用 OAuth、base_url 故意为空、没有可靠的可达性目标）会隐藏连通性按钮，原先「发送真实请求」的确认弹窗以及测试模型 / 提示词字段都被移除，降级延迟阈值设为 6s、超时 8s。该可达性检查永不重置熔断器——可达不等于可用（403 的 host 可达，但对真实流量是坏的），失败转移仍只由真实代理流量驱动。
|
||||
|
||||
### Codex 高级选项区整合
|
||||
|
||||
Codex 供应商表单现在把本地路由、模型映射、推理覆盖和自定义 User-Agent 折叠进一个可展开的高级选项区，与 Claude 表单一致（设置了 UA 或开启本地路由时自动展开）。自定义 User-Agent 现在对原生 Responses 供应商也可配置，此前它只有在开启 `openai_chat` 路由时才能触及。
|
||||
|
||||
### 用量工具栏与布局刷新
|
||||
|
||||
应用筛选改用品牌图标（经 ProviderIcon，「全部」用网格图标）渲染，取代在窄窗口下换行难看的文字页签；用量 Hero 也会显示所选应用的品牌图标，并把 Codex 的主题色从翠绿改为中性灰，贴合 OpenAI 的单色品牌。点击循环切换的刷新按钮改成了带本地化「关闭」标签的下拉选择，顶栏控件也压缩并对齐成统一的宽度分组，过长的日期范围标签做了截断处理。
|
||||
|
||||
### 关于面板加载更快
|
||||
|
||||
设置「关于」面板现在渐进式加载：应用版本徽标在解析完成的瞬间就显示，不再等待工具探测；每张工具卡片在自己的版本检测完成时立即更新（探测并发执行而非串行）；探测结果在应用会话期内缓存并带 10 分钟 TTL，因此再次打开「关于」页签会复用缓存值、并在后台对过期项重新校验，而不是每次都把 6 个工具全部重探一遍。
|
||||
|
||||
### 火山方舟 Coding Plan 推广更新
|
||||
|
||||
把火山方舟（Volcengine Ark）预设在全部 6 个应用里更新到新的 Coding Plan 邀请链接（替换旧的 Agent Plan / 活动链接），并在四种语言里刷新了合作伙伴推广文案（两个月 75% 折扣 + 邀请码 6J6FV5N2），把产品名从 Agent Plan 订正为 Coding Plan。
|
||||
|
||||
### MiniMax 降为普通供应商
|
||||
|
||||
移除 MiniMax 的金色合作伙伴星标和 API key 推广横幅（从所有预设里删掉 `isPartner` 标志），它继续作为常规 `cn_official` 供应商保留图标与主题。推广文案保持休眠状态，必要时一行即可重新启用合作关系。
|
||||
|
||||
### 移除 LemonData、SudoCode 降级
|
||||
|
||||
彻底移除 LemonData 供应商预设（连同其推广文案、图标和赞助商条目），并把 SudoCode 从合作伙伴降为常规 `third_party` 供应商（去掉 `isPartner` 标志和推广文案，保留图标）。
|
||||
|
||||
### AtlasCloud Codex GLM 5.1 上下文窗口
|
||||
|
||||
为 AtlasCloud Codex 预设里的 `zai-org/glm-5.1` 模型声明 200,000 token 的上下文窗口，与其他 GLM 5.1 预设条目对齐。
|
||||
|
||||
---
|
||||
|
||||
## 修复
|
||||
|
||||
### 路由接管流量按真实上游模型计费
|
||||
|
||||
当请求被路由到了不同的上游（env 模型映射、Claude Desktop 路由、Copilot 归一化、Codex chat 覆盖）时，代理过去会按上游回显的模型来归因和计价，把 kimi / glm 的 token 记成、并按 `claude-*` 计价，成本被高估约 5–25 倍。现在转发器会捕获真实的出站模型，按「上游回显 → 出站模型 → 客户端别名」的顺序归因，并在每行持久化实际使用的定价依据（schema v11），该依据会贯穿成本回填和 30 天 rollup 裁剪；Claude Desktop 流量现在也记在它自己的 `app_type` 下，使其定价覆盖能正确生效。
|
||||
|
||||
### 格式转换路径的用量计量
|
||||
|
||||
审计并修复了代理各条格式转换路径（Chat、Responses、Gemini 转 Anthropic）上的 token / 缓存计量。代理现在会记录实际返回的模型，注入 `stream_options.include_usage` 让 OpenAI 兼容上游在流式时吐出 usage，在 Claude←OpenAI 路径上把 `cache_read` 和 `cache_creation` 从 input 中排除以阻止缓存 token 双计费，扣减 Gemini 的缓存提示 token，仍记录完全命中缓存的请求，并跳过过去会虚增请求数的合成全零 usage（[#2774](https://github.com/farion1231/cc-switch/pull/2774)）。
|
||||
|
||||
### 应用内更新不再卡死
|
||||
|
||||
从应用内安装更新时不再卡在「重启中」界面——过去会出现新版已装好、却必须手动强制退出的情况。下载—安装—重启整条链路现在完全在后端执行（新增 `install_update_and_restart` 命令），按平台决定安装顺序，并在重新执行前先销毁单实例锁，而不再依赖旧 WebView 在应用包已被替换之后继续跑 JS；退出请求也做了分类，让重启请求落到 Tauri 默认流程，而不是在窗口状态插件的互斥锁上死锁（[#4069](https://github.com/farion1231/cc-switch/pull/4069)、[#4074](https://github.com/farion1231/cc-switch/pull/4074)）。
|
||||
|
||||
### Codex 升级不再损坏安装
|
||||
|
||||
从设置「关于」页升级 Codex 不再让它抛出「Missing optional dependency @openai/codex-…」错误。升级链此前会先跑 `codex update`，而它在 npm 安装下其实是一次裸的重装、即便对应平台的二进制没装上也会报告成功；现在 Codex 已从「优先 self-update」路径里移除，并由一个 runnable 检测触发「卸载 + 重装」自愈（仅限 npm 管理的安装），这是唯一能真正补回缺失平台二进制的修复。
|
||||
|
||||
### 接管时保留 Codex OAuth 凭据
|
||||
|
||||
为 Codex 供应商开启代理接管时不再剥掉 `ANTHROPIC_AUTH_TOKEN` 占位符——此前这会在热切换、全新安装、以及被旧版本已剥过的 live 配置上破坏 Claude Code 的登录。现在对受管（非 Copilot）的 Codex 供应商无条件注入该占位符，包括只有 URL 的供应商；GitHub Copilot 的行为（仅 API_KEY）不变（[#3789](https://github.com/farion1231/cc-switch/pull/3789)、[#3784](https://github.com/farion1231/cc-switch/issues/3784)）。
|
||||
|
||||
### 跨配置目录切换的接管残留恢复
|
||||
|
||||
在代理接管激活时更改配置目录后重启应用，不再把 Claude / Codex / Gemini 留在指向已失效的本地代理上。现在旧实例会在重启前先还原被接管的 live 文件，首次运行的导入会拒绝把接管占位符当作供应商持久化，SSOT 还原也会在写回前校验当前供应商的配置里不含占位符（[#4076](https://github.com/farion1231/cc-switch/pull/4076)）。
|
||||
|
||||
### 格式转换兜底里错标的 SSE 响应聚合
|
||||
|
||||
经 Claude / Codex 格式转换的请求，当 MaaS 网关把一个 `stream:false` 的请求强制流式、并以非 SSE 的 Content-Type 返回 SSE 响应体时，不再以一句晦涩的 422「Failed to parse upstream response」失败。代理现在会在解析失败时嗅探 SSE、把分片聚合成单个 JSON 再跑既有转换器，让客户端仍能拿到有效的非流式响应；剩余的解析失败会附带 content-type、编码和响应体片段等诊断信息，deflate 解码也改为先尝试 zlib 再尝试裸流（[#2234](https://github.com/farion1231/cc-switch/pull/2234)）。
|
||||
|
||||
### Hermes 配置重复 YAML 键
|
||||
|
||||
Hermes 配置写入不再累积重复的顶层键（如 `mcp_servers`），那会导致「Failed to parse Hermes config as YAML: duplicate entry with key」错误。区段替换现在会从剩余文本里清除所有过期副本，而不是退化成追加；去重保护层同时处理 LF 和 CRLF 行尾；修复时保留最后（最新）的那份副本，与 Hermes 自身基于 PyYAML 的「后者胜」语义一致（[#3267](https://github.com/farion1231/cc-switch/pull/3267)、[#3633](https://github.com/farion1231/cc-switch/issues/3633)、[#2973](https://github.com/farion1231/cc-switch/issues/2973)、[#2529](https://github.com/farion1231/cc-switch/issues/2529)、[#3310](https://github.com/farion1231/cc-switch/issues/3310)、[#3762](https://github.com/farion1231/cc-switch/issues/3762)）。
|
||||
|
||||
### 用量查询韧性与错误清晰度
|
||||
|
||||
用量卡片不再因为单次瞬时抖动就变红：查询现在会重试一次，并在网络 / 超时 / 5xx 这类瞬时失败下继续展示上次成功的结果最多 10 分钟；而确定性失败（鉴权、空 key、未知供应商、4xx）会立即暴露并清空快照，避免凭据变更后陈旧额度又冒出来。原生余额 / Coding Plan / 订阅查询的超时从 10s 提高到 15s 以适配跨境慢端点，Coding Plan 也会返回明确的「API key is empty」/「Unknown coding plan provider」错误，而不是一句空白的失败。
|
||||
|
||||
### 用量脚本供应商凭据解析
|
||||
|
||||
自定义 JS 脚本的用量查询此前只靠猜测 env 字段来解析 `{{apiKey}}` / `{{baseUrl}}`，因此凭据存放在别处的应用（如 Codex 的 `auth.OPENAI_API_KEY` 加 `config.toml` 里的 base_url）总是拿到空值、即便供应商已完整配置也会失败。脚本查询及其测试 / 预览现在复用与原生余额路径相同的按应用凭据解析器，脚本里显式填写的非空值仍然优先（[#1479](https://github.com/farion1231/cc-switch/pull/1479)）。
|
||||
|
||||
### Claude Code Workflow 子 agent 用量统计
|
||||
|
||||
本地（无代理）的会话日志用量统计此前漏掉了 Claude Code Workflow 子 agent 的流量，整体用量被低估约 4.1%（集中在 workflow / subagent 的会话记录里）。扫描器现在会深入更深一层的 `subagents/workflows/wf_*/` 记录目录，解析器也不再丢弃那些缺少 `stop_reason`、但已经产生 input / 缓存 token 成本的 assistant 消息；去重逻辑不变，因此不会重复计数。
|
||||
|
||||
### Codex `/responses` 文本模型图像整流
|
||||
|
||||
携带图片、且被路由到只支持文本的 OpenAI-chat 模型（如 DeepSeek `deepseek-v4-flash`）的 Codex `/responses` 请求，不再以 HTTP 400「unknown variant `image_url`」失败。媒体整流器现在也覆盖 Codex 适配器，会扫描 responses 的 `input` 里的 `input_image` 块，从而既能为已知的纯文本模型主动剥掉图片，也能在上游报「不支持图片」时把图片替换后重试。
|
||||
|
||||
### 智谱 Coding Plan 配额窗口误标
|
||||
|
||||
智谱 Coding Plan 视图不再在每个周周期的最后几个小时把 5 小时窗口和周窗口标反。两个窗口现在按显式的 `unit` 字段分类（3 = 5 小时、6 = 周），而不再靠按重置时间升序排序——后者恰好在用户最常查周额度的时候把两者标反；当字段缺失时仍回退到旧的重置时间启发式（[#3036](https://github.com/farion1231/cc-switch/pull/3036)）。
|
||||
|
||||
### macOS 重复供应商终端窗口
|
||||
|
||||
在 macOS 上启动供应商终端时不再在命令会话旁多开一个空窗口；Terminal.app 在冷启动时改用 `launch`（而非 `activate`），Ghostty 使用初始命令，从而只打开单个会话，并在 AppleScript 路径失败时保留回退方案（[#4156](https://github.com/farion1231/cc-switch/pull/4156)）。
|
||||
|
||||
### Claude Desktop 模型映射占位符
|
||||
|
||||
Claude Desktop 模型映射表单此前在「菜单展示名」和「请求模型」两列用了不一致的示例品牌（DeepSeek vs Kimi），暗示一个展示名会映射到不相关的模型。现在两个占位符都由每行的角色派生，从而保持品牌一致，轻量的 Haiku 档使用 flash 示例。
|
||||
|
||||
### 弹层被全屏面板遮挡
|
||||
|
||||
像供应商预设搜索这样的弹层和提示气泡不再渲染到全屏面板后面、看起来点了没反应；它们的 z-index 被提到全屏遮罩之上，同时仍低于模态对话框。
|
||||
|
||||
### ToggleRow 图标被挤压
|
||||
|
||||
开关行的图标在配上长描述时不再被压缩或变形，让图标在多行文字旁保持固定大小。
|
||||
|
||||
---
|
||||
|
||||
## 文档
|
||||
|
||||
### Release Notes 贡献者致谢恢复
|
||||
|
||||
恢复了 v3.16.1 与 v3.16.2 release notes 在三种语言里的贡献者致谢。
|
||||
|
||||
---
|
||||
|
||||
## 升级提醒
|
||||
|
||||
### 定价库 schema v11 自动迁移
|
||||
|
||||
本版给 `proxy_request_logs` 新增了 `pricing_model` 列、并按 `request_model` + `pricing_model` 重建了 rollup，启动时自动迁移、无需手动操作。历史行的成本在写入时已冻结、不会重算（`app_type="claude"` 的行混合了原生与转换两类来源）；只有真实但当时未计价的接管行会保持零成本、待定价补齐后再回填。
|
||||
|
||||
### 模型映射新增第四档（Fable 5）
|
||||
|
||||
Claude Code 与 Claude Desktop 的模型映射现在是四档（Sonnet / Opus / Fable / Haiku）。老的三档供应商在重新打开并保存后会补上 `claude-fable-5` 档；该档留空表示继承 Sonnet。注意：在第三方端点上把任意一档留空，会原样透传该档的字面模型名并可能 404，请按需填写。
|
||||
|
||||
### 「Kimi For Coding」预设需要代理接管 + 白名单 UA
|
||||
|
||||
恢复的 Codex「Kimi For Coding」预设直接用默认的 `codex-cli` User-Agent 仍会被 403。要使用它，请开启代理接管，并在供应商高级选项里把自定义 User-Agent 设为白名单 UA（如 `claude-cli/*`）。
|
||||
|
||||
### 供应商健康检查语义变化
|
||||
|
||||
健康检查从「发送真实模型请求」改为「HTTP 可达性探测」。请注意可达 ≠ 可用：一个返回 403 的 host 是可达的，但对真实流量可能是坏的。失败转移的判定仍只由真实代理流量驱动，不受健康检查影响。
|
||||
|
||||
---
|
||||
|
||||
## 风险提示
|
||||
|
||||
本版本继续沿用此前版本对反向代理类功能的风险提示。
|
||||
|
||||
**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
|
||||
|
||||
**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
|
||||
|
||||
**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，同样需要遵守目标供应商的计费、合规与数据留存约束。
|
||||
|
||||
用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
|
||||
|
||||
---
|
||||
|
||||
## 致谢
|
||||
|
||||
感谢以下贡献者在 v3.16.3 中提交的功能与修复：
|
||||
|
||||
- [#3789](https://github.com/farion1231/cc-switch/pull/3789)：接管时保留 Codex OAuth 凭据，感谢 @codeasier。
|
||||
- [#2774](https://github.com/farion1231/cc-switch/pull/2774)：修复 Completions 转 Anthropic 时不记录实际返回模型、input token 计算错误，感谢 @LaoYueHanNi。
|
||||
- [#4069](https://github.com/farion1231/cc-switch/pull/4069)：修复应用内更新后重启死锁，感谢 @thisTom。
|
||||
- [#4156](https://github.com/farion1231/cc-switch/pull/4156)：修复 macOS 重复供应商终端窗口，感谢 @thisTom。
|
||||
- [#3267](https://github.com/farion1231/cc-switch/pull/3267)：修复 Hermes 配置重复 YAML 键，感谢 @que3sui。
|
||||
- [#1479](https://github.com/farion1231/cc-switch/pull/1479)：修复用量脚本供应商凭据解析，感谢 @pa001024。
|
||||
- [#3975](https://github.com/farion1231/cc-switch/pull/3975)：新增预设供应商搜索与排序，感谢 @Nastem。
|
||||
- [#4183](https://github.com/farion1231/cc-switch/pull/4183)：调整预设供应商按钮外观与搜索框位置，感谢 @WangJiati。
|
||||
- [#4077](https://github.com/farion1231/cc-switch/pull/4077)：新增 claude-mythos-5 模型定价，感谢 @osscv。
|
||||
|
||||
也感谢所有在 v3.16.2 发布后反馈用量计费、本地代理稳健性、Codex 升级与平台兼容性问题的用户，很多补丁都来自这些真实使用场景里的复现线索。
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
|
||||
|
||||
### 系统要求
|
||||
|
||||
| 系统 | 最低版本 | 架构 |
|
||||
| ------- | -------------------------- | ----------------------------------- |
|
||||
| Windows | Windows 10 及以上 | x64 |
|
||||
| macOS | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 见下表 | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| 文件 | 说明 |
|
||||
| ---------------------------------------- | ----------------------------------- |
|
||||
| `CC-Switch-v3.16.3-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.16.3-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| -------------------------------- | --------------------------------------------- |
|
||||
| `CC-Switch-v3.16.3-macOS.dmg` | **推荐** - DMG 安装包，拖入 Applications 即可 |
|
||||
| `CC-Switch-v3.16.3-macOS.zip` | 解压后拖入 Applications，Universal Binary |
|
||||
| `CC-Switch-v3.16.3-macOS.tar.gz` | 用于 Homebrew 安装和自动更新 |
|
||||
|
||||
Homebrew 安装：
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本：
|
||||
|
||||
- `CC-Switch-v3.16.3-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- `CC-Switch-v3.16.3-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| 发行版 | 推荐格式 | 安装方式 |
|
||||
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| 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` |
|
||||
@@ -0,0 +1,354 @@
|
||||
# CC Switch v3.16.4
|
||||
|
||||
> 🎉 **CC Switch is now in the global top 100 on GitHub by stars!**
|
||||
> Thank you to every user, contributor, and Star — you brought it here. 🙏
|
||||
|
||||
> After v3.16.3 made usage billing accurate, this release shifts the focus to polishing the Codex proxy chain and enriching the usage / pricing tooling — migrating Chinese providers to native Responses, decoupling the upstream-format selector from model mapping, decompressing zstd request / error bodies, and a batch of tool-call and OAuth-through-proxy fixes — while also adding local proxy request overrides, an in-app recovery screen when the database version is too new, native Windows ARM64 builds, and a wave of preset and branding updates (SubRouter, OpenCode Go, the CTok→ETok rename, the Kimi brand refresh, and a prime-partner badge).
|
||||
|
||||
**[中文版 →](v3.16.4-zh.md) | [日本語版 →](v3.16.4-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Usage Guides
|
||||
|
||||
This release is mostly polish and expansion, with the new capabilities landing mainly in the usage dashboard and the provider form's advanced options. The following docs are worth reading alongside it:
|
||||
|
||||
- **[Can't see custom models in the Codex desktop app?](../guides/codex-desktop-custom-model-visibility-en.md)**: many users report that their configured third-party / custom models do not show up in the Codex desktop app's model picker. This is the Codex desktop app's **own upstream gating behavior** (it gates the model picker by official login state), not a CC Switch local-config problem, and **this release (v3.16.4) does not change it**. The doc explains the cause and the available mitigation (keep official login + route takeover).
|
||||
- **[Usage Statistics](../user-manual/en/4-proxy/4.4-usage.md)**: understand the Usage Dashboard's data sources and how the statistics are counted. This release adds bulk import of model pricing from models.dev, AK/SK usage queries for Volcengine Ark Coding / Agent Plan, and a live end time for custom date ranges.
|
||||
- **[Settings](../user-manual/en/1-getting-started/1.5-settings.md)**: local proxy request overrides (custom headers / request body), the Codex upstream-format selector, the local routing toggle, and more live in the provider form's advanced options.
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## Only Official Channels (Please Read)
|
||||
>
|
||||
> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Please only obtain the software through the official channels listed below:
|
||||
>
|
||||
> | Channel | Only Official |
|
||||
> | ------------------ | ------------------------------------------------------------------------------ |
|
||||
> | Website | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | Source | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | Downloads | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | Author | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.16.4 is a maintenance update following v3.16.3. This release tightens the Codex proxy chain — switching several Chinese providers that have native OpenAI Responses endpoints to the native format (dropping the Responses→Chat route-takeover conversion), promoting "upstream format" out of the "local routing" toggle into its own control, adding decompression for zstd request and error response bodies, and fixing a string of tool-call and "OAuth module bypassing the global proxy" issues.
|
||||
|
||||
Alongside that, this release enriches the usage and pricing tooling (import pricing from models.dev, AK/SK usage queries for Volcengine Ark Coding / Agent Plan, a live end time for custom date ranges, GLM-5.2 and Doubao Seed 2.1 pricing), adds a batch of proxy and resilience capabilities (custom header / request-body overrides, an in-app recovery screen when the database version is too new, native Windows ARM64 builds), and brings a wave of preset and branding updates (SubRouter and OpenCode Go subscriptions, the CTok→ETok rename, the Kimi brand refresh and prime-partner badge, and a Kimi K2.7 Code sponsor banner).
|
||||
|
||||
**Release date**: 2026-06-27
|
||||
|
||||
**Stats**: 53 commits | 126 files changed | +8,149 / -1,016 lines
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- **Native Responses for Chinese Codex providers**: Qwen / DashScope, Xiaomi MiMo, Volcengine Doubao, Meituan LongCat, and MiniMax (domestic / international) now connect directly to their native Responses endpoints instead of going through the Responses→Chat format-conversion takeover, for a shorter and more stable chain.
|
||||
- **Local proxy request overrides**: providers can configure custom header and request-body overrides, applied by the local proxy when forwarding, with interception validation that blocks protected security headers.
|
||||
- **In-app recovery screen for a too-new database**: when the SQLite version is newer than the current app supports, you no longer get stuck in a native dialog where "retry just fails again"; instead you are guided to a recovery screen that can upgrade the app in one click.
|
||||
- **Richer usage / pricing tooling**: bulk import of model pricing from models.dev, AK/SK usage queries for Volcengine Ark Coding / Agent Plan, a live end time for custom date ranges, and pricing for GLM-5.2 and Doubao Seed 2.1.
|
||||
- **New presets and branding updates**: added SubRouter and OpenCode Go subscription presets, renamed CTok to ETok, refreshed the Kimi brand mark, and added a prime-partner heart badge to the official Kimi presets.
|
||||
- **Native Windows ARM64 builds**: release artifacts now include native ARM64 builds, so ARM Windows devices no longer depend on x64 emulation.
|
||||
|
||||
---
|
||||
|
||||
## Added
|
||||
|
||||
### In-App Recovery Screen for a Too-New Database
|
||||
|
||||
When the SQLite `user_version` is newer than the current app's supported `SCHEMA_VERSION` (for example after downgrading to an older release, or because a third-party client wrote the file), startup used to die in a native "retry / quit" dialog — where "retry" just fails again. The app now routes to a dedicated recovery screen: when an update is available it offers a one-click "Upgrade App" button (download + install + restart, with a progress bar), and when none is available it explains that even the latest version cannot read this database. The "too new" check runs before any write to the database, so the app never runs DDL against a database it cannot understand; a native close in recovery mode exits cleanly (the tray has not been created yet). ([#4575](https://github.com/farion1231/cc-switch/pull/4575))
|
||||
|
||||
### Local Proxy Request Overrides (Custom Headers and Request Body)
|
||||
|
||||
Provider configs can now define custom header and request-body overrides that the local proxy applies when forwarding, exposed via new fields in the Claude and Codex provider forms. Input is validated against a protected-header list that blocks overriding security-sensitive headers. ([#4589](https://github.com/farion1231/cc-switch/pull/4589))
|
||||
|
||||
### Volcengine Ark Coding / Agent Plan Usage Queries
|
||||
|
||||
The usage panel can now query Volcengine Ark's Coding Plan and Agent Plan quotas. Because the Ark control-plane OpenAPI (`open.volcengineapi.com`) requires an account-level AccessKey signature rather than an inference API key, the usage script gains a dedicated AK/SK input area with a clickable link straight to the Volcengine IAM key-management console (`https://console.volcengine.com/iam/keymanage`); the proxy implements Volcengine Signature V4 (an AWS SigV4 variant: a fixed canonical-header order, the `HMAC-SHA256` algorithm, and the `ark` service scope). It first probes `GetAFPUsage` (the Agent Plan's 5-hour / weekly / monthly quotas) to auto-detect the plan and falls back to `GetCodingPlanUsage`, parsing the window label from the `Level` field (with a guard for `ResetTimestamp <= 0`), and adds the `monthly` tier label across the usage footer, the tray menu, and all four locales.
|
||||
|
||||
### Import Model Pricing from models.dev
|
||||
|
||||
The "Add Pricing" panel gains an "Import from models.dev" button: it fetches `https://models.dev/api.json`, supports full-text search across the entire catalog, and imports the selected entries through the same `update_model_pricing` path as manual entry. Imported model ids are normalized by the backend's `clean_model_id_for_pricing` rules (strip the provider prefix, lowercase, truncate the `:` suffix, map `@` to `-`, drop the `[1m]` marker) so the persisted rows actually match cost-attribution queries. A companion fix changes "backfill zero-cost over a range" to match in Rust by raw model alias (route prefixes, `:free` variants, date suffixes) rather than by exact SQL string match, so newly priced alias rows are priced immediately instead of waiting for the next startup backfill (fixes [#4017](https://github.com/farion1231/cc-switch/issues/4017)). ([#4079](https://github.com/farion1231/cc-switch/pull/4079))
|
||||
|
||||
### Native Windows ARM64 Builds
|
||||
|
||||
Release artifacts now include native Windows ARM64 builds, so ARM Windows devices can grab the matching native build instead of relying on x64 emulation. The release matrix now also runs each platform independently (fail-fast disabled), so a job that fails for a missing secret (e.g. macOS signing in a fork) no longer cancels its still-running siblings. ([#3950](https://github.com/farion1231/cc-switch/pull/3950))
|
||||
|
||||
### Live End Time for Custom Date Ranges
|
||||
|
||||
The custom date-range picker gains a "follow the current time as the end time" checkbox; when enabled, the end time becomes read-only and tracks now, so usage data always reflects the live consumption from the chosen start to the present moment. This is especially useful within the Coding Plan's 5-hour quota window. `liveEndTime` is now part of the React Query cache key, so a live range and a fixed range with the same endpoint no longer share the same stale cache entry. ([#4438](https://github.com/farion1231/cc-switch/pull/4438))
|
||||
|
||||
### Source File Name in the Session Detail Header
|
||||
|
||||
The session detail header now shows the session log's file name next to the project directory (hover for the full path, click to copy), so you can locate and open the underlying JSONL file directly from the UI. For long file names without spaces, such as the ~70-character Codex rollout names, it truncates at `max-w-[200px]` to avoid overflowing into the action buttons in a narrow window. ([#4113](https://github.com/farion1231/cc-switch/pull/4113))
|
||||
|
||||
### Unmanaged-Skill Hint on the Import Button
|
||||
|
||||
The Skills import button in the top bar now shows a green dot and a tooltip when there are unmanaged Skills on disk available to import, so you can tell at a glance that a Skill on disk hasn't been brought under management yet. The scan runs once on mount and is shared across navigations (30s `staleTime` + `keepPreviousData`) to avoid redundant disk IO.
|
||||
|
||||
### OpenCode Go Subscription Presets
|
||||
|
||||
Added the OpenCode Go (`opencode.ai/zen/go`) preset, covering Claude, Codex, and OpenCode, using a paste-ready bare API key (no OAuth). The Codex preset uses `openai_chat` conversion with a GLM / Kimi / DeepSeek / MiMo model catalog (and without a static `codexChatReasoning`, inferring each model's capabilities), while OpenCode points at `/zen/go/v1` via `@ai-sdk/openai-compatible`. All four OpenCode Go presets — Claude, Claude Desktop, Codex, and OpenCode — carry the referral link and in-app promotion copy; the promotion banner now shows on `partnerPromotionKey` alone (no longer bound to `isPartner`), so a preset can surface a referral promotion without earning the gold paid-partner star (which incidentally brings the existing MiniMax promotion back into view).
|
||||
|
||||
### Prime-Partner Preset Badge and Sorting
|
||||
|
||||
The first-party Moonshot Kimi presets (Kimi / Kimi For Coding / Kimi K2.7 Code) are now marked as prime partners: instead of the gold star they render a solid gold heart (no badge border) and, in the default (Original) sort, float to just after the official-category presets and before the rest. The grouping is done with a three-way partition that keeps each group's internal order, and an official preset that is also marked prime-partner stays only in the official group.
|
||||
|
||||
### GLM-5.2 and Doubao Seed 2.1 Pricing
|
||||
|
||||
The seed model pricing now includes GLM-5.2 ([#4385](https://github.com/farion1231/cc-switch/pull/4385)) and Doubao Seed 2.1 Pro / Turbo, so these models' usage is priced correctly instead of being recorded at zero cost. Doubao prices use Volcengine's official list pricing (converted at roughly 7.14); `cache_creation` stays at 0 because Doubao bills cache storage by time rather than by token writes, and the existing 2.0 rows are retained for historical accounting.
|
||||
|
||||
### Kimi For Coding Auto-Compact Window
|
||||
|
||||
The Kimi For Coding preset now defaults `CLAUDE_CODE_AUTO_COMPACT_WINDOW` to 262144, matching Kimi's official documentation, and exposes it via `templateValues` so users can customize the value for future models or performance tuning. ([#4401](https://github.com/farion1231/cc-switch/pull/4401))
|
||||
|
||||
### SubRouter Partner Provider
|
||||
|
||||
Added SubRouter (`subrouter.ai`, an AI relay aggregator that lets one key reach many models across many providers) as a preset covering all seven managed apps — an Anthropic-format endpoint for Claude Code / Claude Desktop / OpenClaw / Hermes, an OpenAI-compatible `/v1` endpoint (`gpt-5.5`) for Codex and OpenCode, and a Gemini-compatible `/v1beta` endpoint (`gemini-3.5-flash`) for Gemini CLI — with its own brand icon, a gold partner star, four-language promotion copy, and a referral signup link prefilled to the API-key registration page (`?aff=l3ri`). ([#4522](https://github.com/farion1231/cc-switch/pull/4522))
|
||||
|
||||
---
|
||||
|
||||
## Changed
|
||||
|
||||
### Chinese Codex Providers Use the Native Responses API
|
||||
|
||||
Several Chinese providers (Qwen / DashScope, Xiaomi MiMo, Volcengine Doubao, Meituan LongCat, MiniMax domestic / international) now expose native OpenAI Responses endpoints, so their Codex presets switch to `apiFormat: "openai_responses"`, connecting directly to the upstream instead of going through the Responses→Chat route-takeover conversion. Dropping the no-longer-needed `codexChatReasoning` and `modelCatalog` also keeps the "local routing mapping" toggle unchecked by default. SiliconFlow-hosted MiniMax stays on `openai_chat` because that is a third-party endpoint, not MiniMax's own base_url. The remaining chat-based providers also refreshed stale model ids (GLM 5.1→5.2, StepFun 3.5-flash-2603→3.7-flash, Ling 2.5-1T→2.6-1T).
|
||||
|
||||
### Upstream-Format Selector Decoupled from the Model-Mapping Toggle
|
||||
|
||||
The Codex provider form previously bound Chat format conversion and route takeover (model mapping) to the same toggle, which meant a provider offering a native Responses API couldn't use model mapping without forcing Chat Completions conversion. "Upstream format" (Chat Completions / Responses) is now a separate, always-visible selector, while the local routing toggle only controls the advanced subsection (the model-mapping catalog, plus reasoning capabilities when the format is Chat). Its initial state is derived from whether a saved catalog exists, adding no new persisted field; the four-language (zh / en / ja / zh-TW) `codexConfig` copy was rewritten to match.
|
||||
|
||||
### Doubao Seed 2.1 Pro Preset
|
||||
|
||||
The DouBaoSeed preset now points to `doubao-seed-2-1-pro` (replacing `doubao-seed-2-0-code-preview-latest`) across all six clients (claude, claude-desktop, codex, opencode, openclaw, hermes), updates the display name to "Doubao Seed 2.1 Pro", and corrects the OpenClaw cost fields from 0.002 / 0.006 to 0.84 / 4.2 USD per million tokens to match the new model.
|
||||
|
||||
### CTok Renamed to ETok
|
||||
|
||||
Following the vendor's domain, endpoint, and trademark rename, all user-facing branding migrates from CTok to ETok (`ctok.ai`→`etok.ai`, `api.ctok.ai`→`api.etok.ai`, plus the internal id, display name, icon, and README partner banner), across every client preset. The Codex history-migration whitelist still keeps `ctok` as a legacy id alongside the new `etok`, so existing users' local session history stays correctly bucketed after the rename.
|
||||
|
||||
### Kimi Preset Naming Unified
|
||||
|
||||
The Kimi presets that OpenCode and OpenClaw previously labeled "Kimi K2.7 Code" are renamed to "Kimi" to match the other apps (OpenCode's provider display name is renamed too); the model label still keeps "Kimi K2.7 Code" because it describes the actual model.
|
||||
|
||||
### JSON Editor Dark Mode
|
||||
|
||||
The CodeMirror `JsonEditor` in the usage-script dialog, the provider form, and the universal provider form now follows the app theme via `useDarkMode()`, switching to the `oneDark` editor theme instead of staying light while the rest of the app is already dark. ([#4556](https://github.com/farion1231/cc-switch/pull/4556))
|
||||
|
||||
### More Compact "Add Provider" Header and Footer Hint
|
||||
|
||||
The "Add Provider" dialog tightens the vertical spacing from the title to the tabs and from the tabs to the cards from 24px to 12px, and adds an always-visible fixed footer hint guiding users to fill in the fields below after choosing a preset. `FullScreenPanel` gains an optional `contentClassName` prop so the padding override applies only to this panel without affecting other panels that share it.
|
||||
|
||||
### Theme-Adaptive Kimi Mark
|
||||
|
||||
The inline Kimi placeholder mark is replaced with the vendor's refreshed mark. The K glyph uses `currentColor` so it follows the theme text color (dark in light mode, white in dark mode), while the brand accent color is fixed to the new `#1783FF`, with the metadata fallback color aligned accordingly.
|
||||
|
||||
### Removed the Fable 5 Verified Banner
|
||||
|
||||
The Settings About page no longer shows the Fable 5 Verified commemorative banner that 3.16.3 added beside the app name to mark a special build; the banner image and its marker are removed, and the About panel returns to the standard version-badge layout.
|
||||
|
||||
---
|
||||
|
||||
## Fixed
|
||||
|
||||
### Copilot / Codex OAuth Requests Now Honor the Global Proxy
|
||||
|
||||
`CopilotAuthManager` and `CodexOAuthManager` hardcoded `Client::new()` at construction, so their auth flows (token exchange, fetching the `/models` list, determining model vendor, device-code and OAuth refresh requests) ignored the configured global proxy and connected directly to the target services. On Copilot, a direct connection made `/models` return 0 Claude models, breaking live model resolution, and the upstream rejected requests with `400 model_not_supported`. Both managers now pull from the shared client on each request (`crate::proxy::http_client::get()`), honoring the global proxy URL and supporting runtime hot reload. Fixes [#2016](https://github.com/farion1231/cc-switch/issues/2016) and [#2931](https://github.com/farion1231/cc-switch/issues/2931). ([#4583](https://github.com/farion1231/cc-switch/pull/4583))
|
||||
|
||||
### Decompressing Compressed Request and Error Bodies
|
||||
|
||||
Codex Desktop sends zstd-compressed request bodies when authenticating to the Codex backend, which broke local proxy routing because the handlers parsed the raw compressed bytes directly with `serde_json`. The proxy now decompresses the request body before JSON parsing (gzip / br / deflate, plus the newly added zstd support, including stacked encodings like `gzip, zstd`), across three Codex handlers, and strips the stale `content-encoding` / `content-length` / `transfer-encoding` request headers so the forwarder regenerates them. Upstream non-2xx error bodies are decompressed the same way, so compressed rate-limit and auth details are no longer dropped and hidden from the client. Fixes [#3764](https://github.com/farion1231/cc-switch/issues/3764) and [#3696](https://github.com/farion1231/cc-switch/issues/3696). ([#3817](https://github.com/farion1231/cc-switch/pull/3817))
|
||||
|
||||
### DeepSeek Endpoint 400 with `thinking: disabled`
|
||||
|
||||
DeepSeek's Anthropic-compatible endpoint rejects requests where `thinking.type=disabled` coexists with an effort parameter, returning HTTP 400, which broke Claude Code 2.1.166+ sub-agents (Workflow / Dynamic Workflow) that hardcode `thinking: disabled`. Rather than overriding the client's intent, the proxy now strips the conflicting `output_config.effort` / `reasoning_effort` parameters for the official DeepSeek endpoint, since sub-agents don't need to surface reasoning anyway. ([#4239](https://github.com/farion1231/cc-switch/pull/4239))
|
||||
|
||||
### Reverted Hoisting Anthropic system Messages
|
||||
|
||||
Reverted the [#3775](https://github.com/farion1231/cc-switch/pull/3775) change that hoisted `role=system` messages on Anthropic-compatible providers from `messages[]` up to the top-level `system` field. The DeepSeek endpoint natively accepts inline system messages, and the rewrite changed the request prefix; keeping messages in place preserves the prompt prefix and avoids a suspected cache-hit-rate regression (see [#4297](https://github.com/farion1231/cc-switch/issues/4297)). The unrelated Windows test fix and the tool-thinking-history normalization from #3775 are retained.
|
||||
|
||||
### Chat Tool Calls Missing Function Names
|
||||
|
||||
Some upstreams send empty or missing function names in streaming tool-call deltas, which used to produce invalid Codex Chat output items (or an `unknown_tool` fallback). Accumulated tool-call state is no longer overwritten by an empty delta, and tool calls that never receive a `call_id` and a valid name are skipped at finalization, across the streaming, non-streaming, and legacy `function_call` paths. ([#4159](https://github.com/farion1231/cc-switch/pull/4159))
|
||||
|
||||
### Restore Cached Codex Tool-Call Fields
|
||||
|
||||
When Codex makes a follow-up Chat request that references a `previous_response_id`, its `function_call` items may carry only the `call_id`. History enhancement previously backfilled only `reasoning` / `reasoning_content`, leaving the function's `name`, `arguments`, `status`, and other fields empty; it now restores all cached tool-call fields from history so the call can be correctly reconstructed for the Chat upstream. ([#4160](https://github.com/farion1231/cc-switch/pull/4160))
|
||||
|
||||
### Duplicate Codex base_url Entries in config.toml
|
||||
|
||||
Writing Codex's `base_url` into `config.toml` previously replaced or removed only one matching assignment per section, so a section that already contained multiple `base_url` lines kept the extras and accumulated duplicates. `setCodexBaseUrl` now collapses all matches in the target section or at the top level (replacing the first, removing the rest), and the TOML `base_url` regex now handles escaped quotes. ([#4316](https://github.com/farion1231/cc-switch/pull/4316))
|
||||
|
||||
### History Migration Probes the CODEX_SQLITE_HOME State DB
|
||||
|
||||
Codex session-history migration previously scanned only `~/.codex/state_5.sqlite` and the `sqlite_home` location in `config.toml`, so when Codex's SQLite state was relocated via the `CODEX_SQLITE_HOME` environment variable, the state DB was never scanned and its threads stayed in the old provider bucket. The `codex_state_db_paths` helper shared by both the third-party and unified-session migrations now falls back to `CODEX_SQLITE_HOME` (the `sqlite_home` in `config` still takes precedence).
|
||||
|
||||
### Provider Terminal Honors the User Shell
|
||||
|
||||
Launching a provider terminal on macOS / Linux previously hardcoded `bash`, so zsh / fish users' rc files weren't loaded. The launcher now detects the user's default shell from `$SHELL` (falling back to `/bin/zsh` on macOS, `/bin/bash` on Linux) and execs into it with the clean-start flag, while the launch script itself now uses POSIX `sh` for portability (e.g. fish, and NixOS where `/bin/sh` may not exist). ([#4140](https://github.com/farion1231/cc-switch/pull/4140), fixes [#1546](https://github.com/farion1231/cc-switch/issues/1546))
|
||||
|
||||
### Claude MCP Paths Honor the Custom Config Directory
|
||||
|
||||
When a custom Claude config directory is configured, MCP server reads and writes now resolve to the MCP file under that directory instead of the default location, isolating MCP state per profile. The old "copy on access" migration of the legacy file was removed in favor of resolving the override path directly. ([#3431](https://github.com/farion1231/cc-switch/pull/3431))
|
||||
|
||||
### Preset Results Clickable After Search
|
||||
|
||||
After searching in the "Add Provider" preset selector, results briefly couldn't be clicked or selected. The `requestAnimationFrame` `select()` that fought the input and swallowed the first character (e.g. "gateway" → "ateway") was removed, input auto-focus on the open-and-click path was restored, and pressing Ctrl/Cmd+F while the search box is already open now refocuses it. The provider list's typing guard was also narrowed to the Ctrl/Cmd+F branch so Escape can still close the search panel. ([#4315](https://github.com/farion1231/cc-switch/pull/4315))
|
||||
|
||||
### Skills Browsing and Provider Card Display Fixes
|
||||
|
||||
Fixed several display and interaction issues: repository management actions stay available while browsing skills.sh, and refresh stays available when a repository returns empty results; overly long provider names and website URLs on provider cards now truncate instead of overflowing; the OMO model-variant dropdown truncates the selected label with a full-text tooltip; and Select menu items show a checkmark on the currently selected item. ([#4323](https://github.com/farion1231/cc-switch/pull/4323))
|
||||
|
||||
### Reset Scroll When Switching Settings Tabs
|
||||
|
||||
Switching tabs in the Settings dialog used to keep the previous tab's scroll position, sometimes landing halfway down the new tab; the scroll container now resets to the top whenever the active tab changes. ([#4165](https://github.com/farion1231/cc-switch/pull/4165))
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
### Kimi Pinned Sponsor Banner
|
||||
|
||||
The pinned sponsor banner at the top of all four README languages (en / zh / ja / de) is now Kimi K2.7 Code, replacing the previous MiniMax M2.7 banner. The copy reflects the K2.7 Code release (a coding-oriented agentic model with thinking-token usage down roughly 30% from K2.6), the banner is now served from in-repo assets (`assets/partners/banners/kimi-banner-en.png` / `kimi-banner-zh.png`) instead of the Moonshot CDN, and it carries a clickable call to action pointing at the `aff=cc-switch` Moonshot console.
|
||||
|
||||
### Codex Unified Session History Guide
|
||||
|
||||
Added a three-language (zh / en / ja) guide explaining what the unified Codex session history toggle's enable-time migration (when enabled) and ledger-based restore (when disabled) actually do, why session data is never truly deleted (only re-tagged + auto-backed-up), and how to verify whether files really are on disk or were just filed into another provider's drawer. It includes a symptom table for the common "my sessions are gone" misunderstanding and disk-verification commands for macOS / Linux / Windows, and is linked as the first item in the v3.16.3 release notes' "Usage Guides".
|
||||
|
||||
### Simplified Homebrew Install Instructions
|
||||
|
||||
The install guide no longer asks users to run `brew tap farion1231/ccswitch` before `brew install --cask cc-switch`; this deprecated tap step is removed from the en / ja / zh user manuals, and the cask now installs directly. ([#4319](https://github.com/farion1231/cc-switch/pull/4319))
|
||||
|
||||
### Star-History Global Ranking Badge
|
||||
|
||||
Added a star-history global ranking badge next to the existing Trendshift badge across all four README languages, with light / dark theme variants.
|
||||
|
||||
### Volcengine Ark Coding Plan Activity Link
|
||||
|
||||
The "developers in mainland China click here" link in the ByteDance / Volcengine Ark sponsor entry now points to Volcengine's `ai618` activity page, replacing the previous `codingplan` referral URL, across all four README languages.
|
||||
|
||||
### CCSub Sponsor Banner Vector Asset
|
||||
|
||||
Replaced the low-resolution `ccsub.jpg` sponsor logo with the vector `ccsub.svg`, letterboxed from 2046x648 to 2046x850 (roughly 2.406:1) so it matches the other sponsor-table banners and renders at the same 62px height. All four README languages point to the new asset.
|
||||
|
||||
---
|
||||
|
||||
## Upgrade Notes
|
||||
|
||||
### Chinese Codex Providers' Native Responses Migration
|
||||
|
||||
This release switches the Codex presets of several Chinese providers with native Responses endpoints (Qwen / DashScope, Xiaomi MiMo, Volcengine Doubao, Meituan LongCat, MiniMax domestic / international) to `openai_responses` and removes their `modelCatalog`. Existing providers already configured from these presets are unaffected and keep their configuration as-is; if you want to switch to native Responses (dropping the format-conversion takeover), re-pick the preset once and save. SiliconFlow-hosted MiniMax stays on `openai_chat` and is not part of this migration.
|
||||
|
||||
### Recovery from a Too-New Database
|
||||
|
||||
If you opened the database with a higher version of CC Switch and then switched back to an older version, the older version will enter the new "database version too new" recovery screen on startup and guide you to upgrade to a version that can read the database. This is expected behavior — upgrading to the latest version restores normal operation.
|
||||
|
||||
---
|
||||
|
||||
## Risk Notice
|
||||
|
||||
This release continues the risk notices from previous versions for reverse-proxy-style features.
|
||||
|
||||
**Codex OAuth reverse proxy**: using a ChatGPT subscription's Codex OAuth through a reverse proxy may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details.
|
||||
|
||||
**Codex third-party provider Chat routing**: when CC Switch local proxy converts and forwards Codex requests to third-party providers, each provider may have different requirements for billing, compliance, and data retention. Read the target provider's terms before use.
|
||||
|
||||
**Claude Desktop third-party provider proxy switching**: when CC Switch's built-in proxy gateway forwards Claude Desktop requests to third-party providers, you must also follow the target provider's billing, compliance, and data-retention terms.
|
||||
|
||||
By enabling these features, users accept the related risks. CC Switch is not responsible for account restrictions, warnings, or service suspensions caused by using these features.
|
||||
|
||||
---
|
||||
|
||||
## Thanks
|
||||
|
||||
Thanks to the following contributors for the features and fixes in v3.16.4:
|
||||
|
||||
- [#3817](https://github.com/farion1231/cc-switch/pull/3817): decompress the request body before forwarding and add zstd support, thanks @chenx-dust.
|
||||
- [#4583](https://github.com/farion1231/cc-switch/pull/4583): fix the Copilot / Codex OAuth modules bypassing the global proxy and causing Claude model 400s, thanks @zymouse.
|
||||
- [#4589](https://github.com/farion1231/cc-switch/pull/4589): add local proxy request overrides (custom headers and request body), thanks @mfzzf.
|
||||
- [#4575](https://github.com/farion1231/cc-switch/pull/4575): add an in-app recovery screen for a too-new database version, thanks @SaladDay.
|
||||
- [#4556](https://github.com/farion1231/cc-switch/pull/4556): wire dark mode into the JsonEditor in several places, thanks @TanKimzeg.
|
||||
- [#4438](https://github.com/farion1231/cc-switch/pull/4438): add a live end time for custom date ranges, thanks @arichyx.
|
||||
- [#3950](https://github.com/farion1231/cc-switch/pull/3950): add Windows ARM64 release support, thanks @MOON-DREAM-STARS.
|
||||
- [#4401](https://github.com/farion1231/cc-switch/pull/4401): add CLAUDE_CODE_AUTO_COMPACT_WINDOW to the Kimi For Coding preset, thanks @cyijun.
|
||||
- [#4323](https://github.com/farion1231/cc-switch/pull/4323): fix the Skills management and model-config interaction display, thanks @thisTom.
|
||||
- [#3431](https://github.com/farion1231/cc-switch/pull/3431): align Claude MCP paths to the custom config directory, thanks @makoMakoGo.
|
||||
- [#4159](https://github.com/farion1231/cc-switch/pull/4159): skip Chat tool calls missing function names, thanks @hueifeng.
|
||||
- [#4385](https://github.com/farion1231/cc-switch/pull/4385): add glm-5.2 pricing, thanks @arichyx.
|
||||
- [#4079](https://github.com/farion1231/cc-switch/pull/4079): support importing model pricing from models.dev, thanks @kingcanfish.
|
||||
- [#4315](https://github.com/farion1231/cc-switch/pull/4315): fix preset results not being clickable / selectable after search, thanks @RuixeWolf.
|
||||
- [#4316](https://github.com/farion1231/cc-switch/pull/4316): prevent duplicate Codex base_url entries, thanks @jeffwcx.
|
||||
- [#4140](https://github.com/farion1231/cc-switch/pull/4140): make the provider terminal honor the user shell, thanks @zkforge.
|
||||
- [#4113](https://github.com/farion1231/cc-switch/pull/4113): show the source file name in the session detail header, thanks @xu-song.
|
||||
- [#4160](https://github.com/farion1231/cc-switch/pull/4160): restore cached Codex tool-call fields, thanks @chen-985211.
|
||||
- [#4239](https://github.com/farion1231/cc-switch/pull/4239): strip the effort parameter when thinking:disabled on DeepSeek endpoints, thanks @maskshell.
|
||||
- [#4165](https://github.com/farion1231/cc-switch/pull/4165): reset scroll when switching settings tabs, thanks @Muleizhang.
|
||||
- [#4319](https://github.com/farion1231/cc-switch/pull/4319): remove the deprecated Homebrew tap step, thanks @tianpeng-dev.
|
||||
- [#4522](https://github.com/farion1231/cc-switch/pull/4522): add the SubRouter provider preset, thanks @abingyyds.
|
||||
|
||||
Thanks also to everyone who reported Codex proxy chain, usage billing, local proxy robustness, and platform compatibility issues after the v3.16.3 release. Many of these patches came directly from real-world reproduction clues.
|
||||
|
||||
---
|
||||
|
||||
## Download & Install
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) and download the build for your system.
|
||||
|
||||
### System Requirements
|
||||
|
||||
| System | Minimum Version | Architecture |
|
||||
| ------- | ------------------------ | ----------------------------------- |
|
||||
| Windows | Windows 10 and later | x64 / ARM64 |
|
||||
| macOS | macOS 12 (Monterey)+ | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | See table below | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| File | Description |
|
||||
| ---------------------------------------- | ------------------------------------------------ |
|
||||
| `CC-Switch-v3.16.4-Windows.msi` | **Recommended** - MSI installer with auto-update |
|
||||
| `CC-Switch-v3.16.4-Windows-Portable.zip` | Portable build, unzip and run |
|
||||
|
||||
Windows ARM64 devices should pick the artifact whose file name carries the `arm64` tag.
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| -------------------------------- | ----------------------------------------------------- |
|
||||
| `CC-Switch-v3.16.4-macOS.dmg` | **Recommended** - DMG installer, drag to Applications |
|
||||
| `CC-Switch-v3.16.4-macOS.zip` | Unzip and drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.16.4-macOS.tar.gz` | For Homebrew install and auto-update |
|
||||
|
||||
Homebrew install:
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Upgrade:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Linux assets are available for both **x86_64** and **ARM64** (`aarch64`). Choose the file whose architecture tag matches your machine's `uname -m` output:
|
||||
|
||||
- `CC-Switch-v3.16.4-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- `CC-Switch-v3.16.4-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| Distribution | Recommended Format | Install Command |
|
||||
| --------------------------------------- | ------------------ | --------------------------------------------------------------------- |
|
||||
| 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` | Make executable and run directly, or use AUR |
|
||||
| Other distributions / unsure | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
@@ -0,0 +1,356 @@
|
||||
# CC Switch v3.16.4
|
||||
|
||||
> 🎉 **CC Switch が GitHub の全世界 Star ランキングでトップ 100 入り！**
|
||||
> ここまで支えてくださったすべてのユーザー、コントリビューター、そして Star に感謝します。🙏
|
||||
|
||||
> v3.16.3 で「使用量の課金を正確にする」ことに取り組んだのに続き、本リリースは Codex プロキシ経路の磨き込みと、使用量 / 価格ツールの拡充に重きを置いています——国産プロバイダーのネイティブ Responses への移行、上流の形式セレクタとモデルマッピングの分離、zstd リクエスト / エラーボディの展開、そしてツール呼び出しと OAuth がプロキシを経由するようにする一連の修正です。あわせて、ローカルプロキシのリクエストオーバーライド、データベースのバージョンが新しすぎる場合のアプリ内リカバリ画面、ネイティブ Windows ARM64 ビルドを新設し、一連のプリセットとブランドの更新（SubRouter、OpenCode Go、CTok→ETok の改名、Kimi のブランド刷新と prime-partner バッジ）を届けます。
|
||||
|
||||
**[English →](v3.16.4-en.md) | [中文版 →](v3.16.4-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## 利用ガイド
|
||||
|
||||
本リリースは磨き込みと拡張が中心で、新しい機能の多くは使用量パネルとプロバイダーフォームの高度なオプションに収まっています。以下のドキュメントとあわせてご覧ください：
|
||||
|
||||
- **[Codex デスクトップでカスタムモデルが見えない？](../guides/codex-desktop-custom-model-visibility-ja.md)**: Codex デスクトップアプリで、設定したサードパーティ / カスタムモデルが見えないというフィードバックが少なくありません。これは Codex デスクトップアプリ**上流自身のゲーティング挙動**（公式ログイン状態に応じてモデルセレクタを通す）であり、CC Switch のローカル設定の問題ではありません。**本リリース（v3.16.4）でこの点に変更はありません**。ドキュメントでは原因と、使える緩和策（公式ログインの保持 + ルーティングテイクオーバー）を解説しています。
|
||||
- **[使用量統計](../user-manual/ja/4-proxy/4.4-usage.md)**: 使用量ダッシュボードのデータソースと集計の仕組みを確認できます。本リリースでは models.dev からのモデル価格一括インポート、火山方舟 Coding / Agent Plan の AK/SK 使用量照会、カスタム日付範囲の「リアルタイム終了時刻」を追加しました。
|
||||
- **[設定](../user-manual/ja/1-getting-started/1.5-settings.md)**: ローカルプロキシのリクエストオーバーライド（カスタムリクエストヘッダー / リクエストボディ）、Codex の上流形式セレクタやローカルルーティングのトグルは、いずれもプロバイダーフォームの高度なオプションにあります。
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## 唯一の公式チャネル（必ずお読みください）
|
||||
>
|
||||
> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。本ソフトウェアは下記の公式チャネルからのみ入手してください：
|
||||
>
|
||||
> | チャネル | 唯一の公式 |
|
||||
> | ------------ | ------------------------------------------------------------------------------ |
|
||||
> | 公式サイト | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | 作者 | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は直ちに操作を中止し、GitHub Issues からご報告ください。
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.16.4 は v3.16.3 に続くメンテナンスアップデートです。本リリースは Codex プロキシ経路まわりを一通り締め直しました——ネイティブの OpenAI Responses endpoint を備える複数の国産プロバイダーをネイティブ形式へ切り替え（Responses→Chat のルーティングテイクオーバー変換を省く）、「上流形式」を「ローカルルーティング」トグルから独立させ、zstd のリクエストとエラーレスポンスボディの展開を補い、ツール呼び出しと「OAuth モジュールがグローバルプロキシをバイパスする」一連の問題を修正しました。
|
||||
|
||||
あわせて本リリースでは使用量と価格のツールを拡充し（models.dev からの価格インポート、火山方舟 Coding / Agent Plan の AK/SK 使用量照会、カスタム日付範囲のリアルタイム終了時刻、GLM-5.2 と Doubao Seed 2.1 の価格）、一連のプロキシと堅牢性の機能を新設し（カスタムリクエストヘッダー / リクエストボディのオーバーライド、データベースのバージョンが新しすぎる場合のアプリ内リカバリ画面、ネイティブ Windows ARM64 ビルド）、一連のプリセットとブランドの更新（SubRouter と OpenCode Go のサブスクリプション、CTok→ETok の改名、Kimi のブランド刷新と prime-partner バッジ、Kimi K2.7 Code スポンサーバナー）を届けます。
|
||||
|
||||
**リリース日**: 2026-06-27
|
||||
|
||||
**Stats**: 53 commits | 126 files changed | +8,149 / -1,016 lines
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **国産 Codex プロバイダーがネイティブ Responses を使用**: 千問 / 百炼、小米 MiMo、火山 Doubao、美団 LongCat、MiniMax（国内 / 国際）が、それぞれのネイティブ Responses endpoint に直結するようになり、Responses→Chat の形式変換テイクオーバーを経由しなくなりました。経路が短く、より安定します。
|
||||
- **ローカルプロキシのリクエストオーバーライド**: プロバイダーにカスタムリクエストヘッダーとリクエストボディのオーバーライドを設定でき、ローカルプロキシが転送時に適用します。保護対象のセキュリティ関連リクエストヘッダーにはブロック検証を行います。
|
||||
- **データベースのバージョンが新しすぎる場合のアプリ内リカバリ画面**: SQLite のバージョンが現在のアプリのサポート範囲より新しいとき、「再試行しても再び失敗するだけ」のネイティブダイアログで詰まらず、ワンクリックでアプリを更新できるリカバリ画面へ案内します。
|
||||
- **より充実した使用量 / 価格ツール**: models.dev からのモデル価格一括インポート、火山方舟 Coding / Agent Plan の AK/SK 使用量照会、カスタム日付範囲の「リアルタイム終了時刻」、そして GLM-5.2 と Doubao Seed 2.1 の価格。
|
||||
- **新しいプリセットとブランド更新**: SubRouter と OpenCode Go のサブスクリプションプリセットを追加し、CTok を ETok へ改名し、Kimi のブランドアイコンを刷新し、公式 Kimi プリセットに prime-partner のハートバッジを付けました。
|
||||
- **ネイティブ Windows ARM64 ビルド**: 配布物にネイティブ ARM64 版を追加し、ARM アーキテクチャの Windows デバイスは x64 エミュレーションに頼る必要がなくなりました。
|
||||
|
||||
---
|
||||
|
||||
## 追加機能
|
||||
|
||||
### データベースのバージョンが新しすぎる場合のアプリ内リカバリ画面
|
||||
|
||||
SQLite の `user_version` が現在のアプリのサポートする `SCHEMA_VERSION` より新しいとき（旧版へダウングレードした、あるいはサードパーティクライアントがこのファイルを書いた場合など）、これまでは起動時にネイティブの「再試行 / 終了」ダイアログで詰まっていました——しかし「再試行」は再び失敗するだけです。現在はアプリが専用のリカバリ画面へ案内します: 利用可能な更新があればワンクリックの「アプリを更新」ボタン（ダウンロード + インストール + 再起動、プログレスバー付き）を提供し、利用可能な更新がない場合は最新版であってもこのデータベースを読めない旨を案内します。この「バージョンが新しすぎる」チェックは、あらゆる書き込み動作の前に行われるため、アプリが読めないデータベースに対して DDL を実行することは決してありません。リカバリモードでのネイティブな終了はクリーンに終了します（この時点ではトレイがまだ作成されていません）。（[#4575](https://github.com/farion1231/cc-switch/pull/4575)）
|
||||
|
||||
### ローカルプロキシのリクエストオーバーライド（カスタムリクエストヘッダーとリクエストボディ）
|
||||
|
||||
プロバイダー設定で、カスタムリクエストヘッダーとリクエストボディのオーバーライドを定義できるようになり、ローカルプロキシが転送時に適用します。Claude と Codex のプロバイダーフォームの新しいフィールドから公開します。入力は検証を経て、その中にセキュリティに敏感なリクエストヘッダーの上書きを防ぐ保護対象リクエストヘッダーのリストを含みます。（[#4589](https://github.com/farion1231/cc-switch/pull/4589)）
|
||||
|
||||
### 火山方舟 Coding / Agent Plan 使用量照会
|
||||
|
||||
使用量パネルから火山方舟（Volcengine Ark）の Coding Plan と Agent Plan のクォータを照会できるようになりました。方舟のコントロールプレーン OpenAPI（`open.volcengineapi.com`）が要求するのは推論 API key ではなくアカウント単位の AccessKey 署名であるため、使用量スクリプトに独立した AK/SK 入力欄を新設し、火山 IAM のキー管理コンソール（`https://console.volcengine.com/iam/keymanage`）へ直接飛べるクリック可能なリンクを添えました。プロキシは火山署名 V4（AWS SigV4 の変種: 固定された canonical header 順、`HMAC-SHA256` アルゴリズム、`ark` サービス scope）を実装しています。まず `GetAFPUsage`（Agent Plan の 5 時間 / 週 / 月クォータ）をプローブしてプランを自動判定し、失敗した場合は `GetCodingPlanUsage` へフォールバックして `Level` フィールドからウィンドウラベルを解析し（`ResetTimestamp <= 0` にはガードを設けます）、あわせて使用量フッター、トレイメニュー、4 言語に `monthly` 階層のラベルを補いました。
|
||||
|
||||
### models.dev からのモデル価格インポート
|
||||
|
||||
「価格を追加」パネルに「models.dev からインポート」ボタンを新設しました: `https://models.dev/api.json` を取得し、カタログ全体の全文検索に対応し、選択した項目を手入力と同じ `update_model_pricing` 経路でインポートします。インポートされた model id は、バックエンドの `clean_model_id_for_pricing` ルール（プロバイダープレフィックスの除去、小文字化、`:` サフィックスの切り捨て、`@` を `-` へマッピング、`[1m]` マーカーの除去）で正規化されるため、保存される行がコスト帰属クエリと本当にマッチするようになります。あわせて、「範囲ごとのゼロコストバックフィル」を、精密な SQL 文字列マッチではなく Rust 側で元の model エイリアス（ルーティングプレフィックス、`:free` 変種、日付サフィックス）でマッチするように修正したため、新しい価格のエイリアス行が次回起動時のバックフィルを待たず即座に課金されるようになりました（[#4017](https://github.com/farion1231/cc-switch/issues/4017) を修正）。（[#4079](https://github.com/farion1231/cc-switch/pull/4079)）
|
||||
|
||||
### ネイティブ Windows ARM64 ビルド
|
||||
|
||||
配布物にネイティブの Windows ARM64 制品が含まれるようになり、ARM アーキテクチャの Windows デバイスは対応するネイティブビルドを入手でき、x64 エミュレーションに頼る必要がなくなりました。リリースマトリクスも各プラットフォームが独立して走るように変更し（fail-fast を無効化）、あるジョブがキー欠如で失敗しても（fork での macOS 署名など）、まだ完了していない同列のジョブをまとめてキャンセルしないようにしました。（[#3950](https://github.com/farion1231/cc-switch/pull/3950)）
|
||||
|
||||
### カスタム日付範囲のリアルタイム終了時刻
|
||||
|
||||
カスタム日付範囲セレクタに「終了時刻を現在時刻に追従」チェックボックスを新設しました。有効にすると終了時刻は読み取り専用になり、今この瞬間に自動追従するため、使用量データは選択した起点から現在までのリアルタイムの消費を常に反映します。これは Coding Plan の 5 時間クォータウィンドウで特に有用です。`liveEndTime` は React Query のキャッシュキーに取り込んだため、リアルタイム範囲と終点が同じ固定範囲が同一の古いキャッシュ項目を共有することはなくなりました。（[#4438](https://github.com/farion1231/cc-switch/pull/4438)）
|
||||
|
||||
### セッション詳細ヘッダーにソースファイル名を表示
|
||||
|
||||
セッション詳細ヘッダーが、プロジェクトディレクトリの隣にセッションログのファイル名を表示するようになりました（ホバーで完全パスを確認、クリックでコピー）。これにより、画面から直接、基礎となる JSONL ファイルを特定して開けます。~70 文字の Codex rollout のような空白を含まない長いファイル名は `max-w-[200px]` で切り詰め、狭いウィンドウで操作ボタン領域へあふれ出るのを防ぎます。（[#4113](https://github.com/farion1231/cc-switch/pull/4113)）
|
||||
|
||||
### インポートボタンの未管理 Skill ヒント
|
||||
|
||||
トップバーの Skills インポートボタンが、ローカルにインポート可能な未管理の Skill が存在するとき、緑のドットとヒントを表示するようになり、ディスク上の Skill がまだ管理対象になっていないことが一目で分かります。このスキャンはマウント時に一度実行され、複数のナビゲーションをまたいで共有され（30s の `staleTime` + `keepPreviousData`）、ディスク IO の重複を避けます。
|
||||
|
||||
### OpenCode Go サブスクリプションプリセット
|
||||
|
||||
OpenCode Go（`opencode.ai/zen/go`）プリセットを追加し、Claude、Codex、OpenCode をカバーし、そのまま貼り付けられる素の API key（OAuth なし）を使用します。Codex プリセットは `openai_chat` 変換を使い、GLM / Kimi / DeepSeek / MiMo のモデルカタログを備え（静的な `codexChatReasoning` は付けず、モデルごとに能力を推論します）、OpenCode は `@ai-sdk/openai-compatible` 経由で `/zen/go/v1` を指します。4 つの OpenCode Go プリセット——Claude、Claude Desktop、Codex、OpenCode——にはいずれも紹介リンクとアプリ内宣伝文を付けました。宣伝バナーは `partnerPromotionKey` だけで表示できるようになり（`isPartner` への紐付けを解除）、あるプリセットが金色の有料パートナースターを得ずに紹介宣伝を表示できるようになりました（これにより既存の MiniMax 宣伝も再表示されます）。
|
||||
|
||||
### Prime-Partner プリセットバッジとソート
|
||||
|
||||
第一方 Moonshot Kimi プリセット（Kimi / Kimi For Coding / Kimi K2.7 Code）が prime partner としてマークされるようになりました: 金色のスターは表示せず、塗りつぶしの金色ハート（バッジ枠なし）を描画し、既定（Original）ソートでは公式カテゴリプリセットの後、その他より前に浮かびます。グルーピングは 3 方向の partition で実装し、各グループは内部順序を保ち、prime-partner としてもマークされた公式プリセットは公式グループにのみ残ります。
|
||||
|
||||
### GLM-5.2 と Doubao Seed 2.1 の価格
|
||||
|
||||
シードモデル価格に GLM-5.2（[#4385](https://github.com/farion1231/cc-switch/pull/4385)）と Doubao Seed 2.1 Pro / Turbo を追加し、これらのモデルの使用量がゼロコストではなく正しく課金されるようにしました。Doubao の価格は火山公式の定価を採用し（約 7.14 のレートで換算）、`cache_creation` は 0 のままです。Doubao はキャッシュストレージを token 書き込みではなく時間で課金するためで、既存の 2.0 行も過去の記帳のために残します。
|
||||
|
||||
### Kimi For Coding 自動圧縮ウィンドウ
|
||||
|
||||
Kimi For Coding プリセットが `CLAUDE_CODE_AUTO_COMPACT_WINDOW` を既定で 262144 に設定するようになり、Kimi 公式ドキュメントと一致させ、`templateValues` 経由で公開して、将来のモデルや性能チューニングのためにユーザーがこの値をカスタマイズできるようにしました。（[#4401](https://github.com/farion1231/cc-switch/pull/4401)）
|
||||
|
||||
### SubRouter パートナープロバイダー
|
||||
|
||||
SubRouter（`subrouter.ai`、1 つの key で複数モデル・複数プロバイダーにアクセスできる AI 中継アグリゲーター）をプリセットとして追加し、管理対象の 7 アプリすべてをカバーしました——Claude Code / Claude Desktop / OpenClaw / Hermes 向けには Anthropic 形式 endpoint、Codex と OpenCode 向けには OpenAI 互換の `/v1` endpoint（`gpt-5.5`）、Gemini CLI 向けには Gemini 互換の `/v1beta` endpoint（`gemini-3.5-flash`）——自前のブランドアイコン、金色のパートナースター、4 言語の宣伝文、そして API key の登録ページへ事前入力された紹介登録リンク（`?aff=l3ri`）を備えます。（[#4522](https://github.com/farion1231/cc-switch/pull/4522)）
|
||||
|
||||
---
|
||||
|
||||
## 変更
|
||||
|
||||
### 国産 Codex プロバイダーがネイティブ Responses API を使用
|
||||
|
||||
複数の国産プロバイダー（千問 / DashScope 百炼、小米 MiMo、火山 Doubao、美団 LongCat、MiniMax 国内 / 国際）がネイティブの OpenAI Responses endpoint を公開したため、それらの Codex プリセットを `apiFormat: "openai_responses"` へ切り替え、Responses→Chat のルーティングテイクオーバー変換を経由せず上流に直結するようにしました。不要になった `codexChatReasoning` と `modelCatalog` を外したことで、「ローカルルーティングマッピング」トグルも既定で未選択のままになります。SiliconFlow がホストする MiniMax は `openai_chat` のままです。これは MiniMax 自身の base_url ではなくサードパーティの endpoint だからです。引き続き chat を使う他のプロバイダーも、古くなった model id を更新しました（GLM 5.1→5.2、StepFun 3.5-flash-2603→3.7-flash、Ling 2.5-1T→2.6-1T）。
|
||||
|
||||
### 上流形式セレクタとモデルマッピングトグルの分離
|
||||
|
||||
Codex プロバイダーフォームは以前、Chat 形式変換とルーティングテイクオーバー（モデルマッピング）を同じトグルに束ねていたため、ネイティブ Responses API を提供するプロバイダーが Chat Completions 変換を強制せずにモデルマッピングを使うことができませんでした。現在は「上流形式」（Chat Completions / Responses）が独立して常に見えるセレクタになり、ローカルルーティングトグルは高度なサブ領域（モデルマッピングカタログ、および形式が Chat のときの推論能力）の制御だけを担います。その初期状態は保存済みカタログの有無から導かれ、永続化フィールドは増やしません。`codexConfig` の 4 言語（zh / en / ja / zh-TW）の文言もあわせて書き直しました。
|
||||
|
||||
### Doubao Seed 2.1 Pro プリセット
|
||||
|
||||
DouBaoSeed プリセットが、6 つのクライアントすべて（claude、claude-desktop、codex、opencode、openclaw、hermes）で `doubao-seed-2-1-pro` を指すようになり（`doubao-seed-2-0-code-preview-latest` を置き換え）、表示名を「Doubao Seed 2.1 Pro」に更新し、OpenClaw のコストフィールドを新モデルに合わせて 0.002 / 0.006 から 0.84 / 4.2 ドル毎 100 万 token へ訂正しました。
|
||||
|
||||
### CTok を ETok へ改名
|
||||
|
||||
ベンダーによるドメイン・endpoint・商標の改名に合わせ、ユーザーに見えるブランドをすべて CTok から ETok へ移行しました（`ctok.ai`→`etok.ai`、`api.ctok.ai`→`api.etok.ai`、および内部 id、表示名、アイコン、README パートナーバナー）。各クライアントプリセットを網羅します。Codex 履歴移行のホワイトリストでは、改名後も既存ユーザーのローカルセッション履歴が正しく分類されるよう、旧 id の `ctok` を新しい `etok` と並存させたまま残します。
|
||||
|
||||
### Kimi プリセットの命名統一
|
||||
|
||||
OpenCode と OpenClaw で以前「Kimi K2.7 Code」とマークされていた Kimi プリセットを、他のアプリと一致する「Kimi」へ改名しました（OpenCode のプロバイダー表示名もあわせて改名）。モデルラベルは引き続き「Kimi K2.7 Code」のままです。これは実際のモデルを表しているためです。
|
||||
|
||||
### JSON エディタのダークモード
|
||||
|
||||
使用量スクリプトのダイアログ、プロバイダーフォーム、ユニバーサルプロバイダーフォーム内の CodeMirror `JsonEditor` が、`useDarkMode()` を通じてアプリのテーマに追従し、`oneDark` エディタテーマへ切り替わるようになり、アプリの他の部分がすでにダークなのにライトのままになることがなくなりました。（[#4556](https://github.com/farion1231/cc-switch/pull/4556)）
|
||||
|
||||
### よりコンパクトな「プロバイダーを追加」のタイトルとフッターヒント
|
||||
|
||||
「プロバイダーを追加」ダイアログで、タイトルからタブ、タブからカードへの縦方向の間隔を 24px から 12px へ詰め、プリセットを選んだ後に下のフィールドを記入するよう案内する、常に見える固定フッターヒントを新設しました。`FullScreenPanel` には任意の `contentClassName` プロパティを追加し、パディングの上書きをこのパネルだけに作用させ、これを共有する他のパネルに影響しないようにしました。
|
||||
|
||||
### テーマ追従の Kimi アイコン
|
||||
|
||||
インラインの Kimi プレースホルダーマーカーを、ベンダーが刷新したアイコンへ置き換えました。K 字形は `currentColor` を使うため、テーマのテキスト色に追従し（ライトモードは濃く、ダークモードは白く）、ブランドのアクセント色は新しい `#1783FF` に固定し、メタデータのフォールバック色もそれに合わせました。
|
||||
|
||||
### Fable 5 Verified 記念バナーの削除
|
||||
|
||||
設定の「バージョン情報」ページが、3.16.3 で特別ビルドを示すためにアプリ名の隣に付けていた Fable 5 Verified 記念バナーを表示しなくなりました。バナー画像とそのマーカーを削除し、「バージョン情報」パネルは標準のバージョンバッジレイアウトに戻りました。
|
||||
|
||||
---
|
||||
|
||||
## 修正
|
||||
|
||||
### Copilot / Codex OAuth リクエストがグローバルプロキシに従うように
|
||||
|
||||
`CopilotAuthManager` と `CodexOAuthManager` は構築時に `Client::new()` をハードコードしていたため、それらの認証フロー（token の交換、`/models` リストの取得、model vendor の判定、device-code と OAuth のリフレッシュリクエスト）が設定済みのグローバルプロキシを無視し、対象サービスへ直結していました。Copilot では、直結により `/models` が Claude モデルを 0 個返し、live のモデル解決が失効し、上流が `400 model_not_supported` でリクエストを拒否していました。現在は両 manager が、リクエストのたびに共有クライアント（`crate::proxy::http_client::get()`）からその場で取得するように変更され、グローバルプロキシ URL に従い、ランタイムのホット更新にも対応します。[#2016](https://github.com/farion1231/cc-switch/issues/2016)、[#2931](https://github.com/farion1231/cc-switch/issues/2931) を修正。（[#4583](https://github.com/farion1231/cc-switch/pull/4583)）
|
||||
|
||||
### 圧縮されたリクエストボディとエラーボディの展開
|
||||
|
||||
Codex Desktop は Codex バックエンドへ認証するとき zstd 圧縮のリクエストボディを送ります。これがローカルプロキシのルーティングを壊していました。ハンドラーが生の圧縮バイトをそのまま `serde_json` で解析していたためです。プロキシは現在、JSON 解析の前にリクエストボディを展開し（gzip / br / deflate に加え、新たに zstd に対応、`gzip, zstd` のような積み重ねエンコーディングを含む）、3 つの Codex ハンドラーをカバーし、古くなった `content-encoding` / `content-length` / `transfer-encoding` リクエストヘッダーを剥がして転送器に再生成させます。上流の非 2xx のエラーボディも同様に展開されるため、圧縮されたレート制限や認証の詳細がクライアントに対して破棄・隠蔽されることがなくなりました。[#3764](https://github.com/farion1231/cc-switch/issues/3764)、[#3696](https://github.com/farion1231/cc-switch/issues/3696) を修正。（[#3817](https://github.com/farion1231/cc-switch/pull/3817)）
|
||||
|
||||
### DeepSeek endpoint で `thinking: disabled` のときの 400 エラー
|
||||
|
||||
DeepSeek の Anthropic 互換 endpoint は、`thinking.type=disabled` と effort パラメータが共存するリクエストを HTTP 400 で拒否します。これは Claude Code 2.1.166+ で `thinking: disabled` をハードコードするサブ agent（Workflow / Dynamic Workflow）を壊していました。プロキシは現在、クライアントの意図を上書きするのではなく、公式 DeepSeek endpoint に対しては競合する `output_config.effort` / `reasoning_effort` パラメータを剥がします。サブ agent はそもそも推論の表示を必要としないためです。（[#4239](https://github.com/farion1231/cc-switch/pull/4239)）
|
||||
|
||||
### Anthropic system メッセージの引き上げをロールバック
|
||||
|
||||
Anthropic 互換プロバイダーの `role=system` メッセージを `messages[]` からトップレベルの `system` フィールドへ引き上げる [#3775](https://github.com/farion1231/cc-switch/pull/3775) の変更をロールバックしました。DeepSeek endpoint はそもそもインラインの system メッセージをネイティブに受け付けますが、この書き換えはリクエストのプレフィックスを変えてしまいました。メッセージを元の位置に保つことで prompt プレフィックスを保持し、一見キャッシュヒット率の後退と思われる現象を回避します（[#4297](https://github.com/farion1231/cc-switch/issues/4297) を参照）。#3775 由来の、無関係な Windows テスト修正と tool-thinking-history の正規化は残します。
|
||||
|
||||
### Chat ツール呼び出しの関数名欠落
|
||||
|
||||
一部の上流は、ストリーミングのツール呼び出し増分で空の、または欠落した関数名を送ります。これは以前、無効な Codex Chat の出力項（または `unknown_tool` フォールバック）を生んでいました。現在は累積したツール呼び出し状態が空の増分で上書きされることがなくなり、最後まで `call_id` と有効な名前を得られなかったツール呼び出しは最終化フェーズでスキップされます。ストリーミング、非ストリーミング、旧版 `function_call` の 3 経路をカバーします。（[#4159](https://github.com/farion1231/cc-switch/pull/4159)）
|
||||
|
||||
### Codex のキャッシュされたツール呼び出しフィールドの復元
|
||||
|
||||
Codex が `previous_response_id` を参照する後続の Chat リクエストを発行するとき、その `function_call` 項が `call_id` だけを携える場合があります。履歴拡張は以前 `reasoning` / `reasoning_content` だけをバックフィルし、関数の `name`、`arguments`、`status` などのフィールドを空のまま残していました。現在は履歴からキャッシュされたツール呼び出しフィールドをすべて復元し、その呼び出しを Chat 上流向けに正しく再構築できるようにします。（[#4160](https://github.com/farion1231/cc-switch/pull/4160)）
|
||||
|
||||
### config.toml 内の重複した Codex base_url 項
|
||||
|
||||
Codex の `base_url` を `config.toml` へ書き込むとき、以前は各セクションで一致する代入を 1 つだけ置換または削除していたため、すでに複数行の `base_url` を含むセクションでは余分な項が残り、重複が累積していました。`setCodexBaseUrl` は現在、対象セクションまたはトップレベルの一致をすべて折りたたみ（最初の 1 つを置換し、残りを削除）、TOML の `base_url` 正規表現もエスケープされた引用符を処理します。（[#4316](https://github.com/farion1231/cc-switch/pull/4316)）
|
||||
|
||||
### 履歴移行が CODEX_SQLITE_HOME の状態 DB をプローブ
|
||||
|
||||
Codex セッション履歴の移行は、以前 `~/.codex/state_5.sqlite` と `config.toml` の `sqlite_home` の場所だけをスキャンしていたため、Codex の SQLite 状態が `CODEX_SQLITE_HOME` 環境変数で再配置されたとき、状態 DB は一度もスキャンされず、その threads は古いプロバイダーバケットに残ったままでした。サードパーティ移行と統一セッション移行の両方が共有する `codex_state_db_paths` ヘルパーが、現在は `CODEX_SQLITE_HOME` へフォールバックします（`config` 内の `sqlite_home` は引き続き優先）。
|
||||
|
||||
### プロバイダーターミナルがユーザーの shell を尊重
|
||||
|
||||
macOS / Linux でプロバイダーターミナルを起動するとき、以前は `bash` をハードコードしていたため、zsh / fish ユーザーの rc ファイルが読み込まれませんでした。ランチャーは現在、`$SHELL` からユーザーの既定 shell を検出し（macOS は `/bin/zsh`、Linux は `/bin/bash` へフォールバック）、クリーンスタートのフラグ付きで exec します。一方、起動スクリプト自体は移植性のために POSIX `sh` を使うようにしました（fish や、`/bin/sh` が存在しないことのある NixOS など）。（[#4140](https://github.com/farion1231/cc-switch/pull/4140)、[#1546](https://github.com/farion1231/cc-switch/issues/1546) を修正）
|
||||
|
||||
### Claude MCP のパスがカスタム設定ディレクトリを尊重
|
||||
|
||||
カスタムの Claude 設定ディレクトリが設定されているとき、MCP server の読み書きが、既定の場所ではなくそのディレクトリ配下の MCP ファイルへ解決されるようになり、MCP の状態が profile ごとに分離されます。旧ファイルに対する以前の「アクセス時コピー」移行は削除し、オーバーライドパスへ直接解決するようにしました。（[#3431](https://github.com/farion1231/cc-switch/pull/3431)）
|
||||
|
||||
### 検索後にプリセット結果をクリック可能に
|
||||
|
||||
「プロバイダーを追加」のプリセットセレクタで検索した後、結果がクリックも選択もできなくなることがありました。入力と競合して先頭文字を飲み込んでいた（「gateway」→「ateway」など）`requestAnimationFrame` の `select()` を削除し、すぐクリックできる経路の入力オートフォーカスを復元し、検索ボックスが開いているときに Ctrl/Cmd+F を押せば再フォーカスするようにもしました。プロバイダーリストのタイピングガードも Ctrl/Cmd+F 分岐に絞り込み、Escape で引き続き検索パネルを閉じられるようにしました。（[#4315](https://github.com/farion1231/cc-switch/pull/4315)）
|
||||
|
||||
### Skills ブラウズとプロバイダーカードの表示修正
|
||||
|
||||
いくつかの表示とインタラクションの問題を修正しました: skills.sh をブラウズ中もリポジトリ管理操作が引き続き使え、リポジトリが空の結果を返したときも更新が引き続き使え、プロバイダーカード上の長すぎるプロバイダー名やウェブサイト URL があふれずに切り詰められ、OMO のモデル変種ドロップダウンが選択ラベルを切り詰めて完全な内容をツールチップで示し、Select のメニュー項目が現在選択中の項目にチェックマークを表示します。（[#4323](https://github.com/farion1231/cc-switch/pull/4323)）
|
||||
|
||||
### 設定タブ切り替え時のスクロールリセット
|
||||
|
||||
設定ダイアログ内でタブを切り替えると前のタブのスクロール位置が引き継がれ、新しいタブの途中で止まることがありました。現在はアクティブなタブが変わるたびに、スクロールコンテナがトップへリセットされます。（[#4165](https://github.com/farion1231/cc-switch/pull/4165)）
|
||||
|
||||
---
|
||||
|
||||
## ドキュメント
|
||||
|
||||
### Kimi ピン留めスポンサーバナー
|
||||
|
||||
4 言語すべての README（en / zh / ja / de）の冒頭のピン留めスポンサーバナーが、これまでの MiniMax M2.7 バナーに代わって Kimi K2.7 Code になりました。文言は K2.7 Code のリリース（コーディング向けの agentic モデルで、思考 token の使用量が K2.6 比で約 30% 低減）を反映し、バナーは Moonshot CDN ではなくリポジトリ内のリソース（`assets/partners/banners/kimi-banner-en.png` / `kimi-banner-zh.png`）から提供し、`aff=cc-switch` の Moonshot コンソールを指すクリック可能な行動喚起を添えました。
|
||||
|
||||
### Codex 統一セッション履歴ガイド
|
||||
|
||||
3 言語（zh / en / ja）のガイドを新設し、Codex 統一セッション履歴トグルの有効化時の移行（有効化時）と台帳に基づく復元（無効化時）が実際に何をするのか、なぜセッションデータが本当に削除されないのか（マーカーの変更 + 自動バックアップのみ）、そしてファイルが本当にディスク上にあるのか、それとも別のプロバイダードロワーに分類されただけなのかを照合する方法を解説しました。「セッションが消えた」という、よくある誤解に対する症状の対照表と、macOS / Linux / Windows のディスク照合コマンドを含み、v3.16.3 の「利用ガイド」release notes の冒頭項としてリンクしました。
|
||||
|
||||
### Homebrew インストール手順の簡素化
|
||||
|
||||
インストールガイドが、`brew install --cask cc-switch` の前に `brew tap farion1231/ccswitch` を実行するようユーザーに求めなくなりました。この廃止された tap 手順を en / ja / zh のユーザーマニュアルから削除し、cask を直接インストールできるようにしました。（[#4319](https://github.com/farion1231/cc-switch/pull/4319)）
|
||||
|
||||
### Star-History 世界ランキングバッジ
|
||||
|
||||
4 言語すべての README で、既存の Trendshift バッジの隣に star-history の世界ランキングバッジを新設し、ライト / ダークテーマの変種を付けました。
|
||||
|
||||
### 火山方舟 Coding Plan キャンペーンリンク
|
||||
|
||||
ByteDance / 火山方舟スポンサー項目内の「中国本土の開発者はこちらをクリック」リンクが、これまでの `codingplan` 紹介 URL に代わって火山の `ai618` キャンペーンページを指すようになり、4 言語すべての README をカバーします。
|
||||
|
||||
### CCSub スポンサーバナーのベクター素材
|
||||
|
||||
低解像度の `ccsub.jpg` スポンサーロゴをベクターの `ccsub.svg` へ置き換え、2046x648 のレターボックスから 2046x850（約 2.406:1）へ拡げ、他のスポンサー表バナーと揃えて同じ 62px の高さで描画されるようにしました。4 言語すべての README が新しい素材を指します。
|
||||
|
||||
---
|
||||
|
||||
## アップグレード時の注意
|
||||
|
||||
### 国産 Codex プロバイダーのネイティブ Responses 移行
|
||||
|
||||
本リリースは、ネイティブ Responses endpoint を備える複数の国産プロバイダー（千問 / 百炼、小米 MiMo、火山 Doubao、美団 LongCat、MiniMax 国内 / 国際）の Codex プリセットを `openai_responses` へ切り替え、`modelCatalog` を削除しました。すでにこれらのプリセットをもとに設定済みの既存プロバイダーは影響を受けず、設定はそのまま保たれます。ネイティブ Responses（形式変換テイクオーバーを省く）へ切り替えたい場合は、プリセットからもう一度選び直して保存してください。SiliconFlow がホストする MiniMax は引き続き `openai_chat` を使い、今回の移行の対象外です。
|
||||
|
||||
### データベースのバージョンが新しすぎる場合の復旧
|
||||
|
||||
より高いバージョンの CC Switch でデータベースを開いた後、旧版へ戻した場合、旧版は起動時に新しい「データベースのバージョンが新しすぎる」リカバリ画面に入り、そのデータベースを読めるバージョンへのアップグレードへ案内します。これは期待される動作です——最新版へアップグレードすれば正常に戻ります。
|
||||
|
||||
---
|
||||
|
||||
## リスク通知
|
||||
|
||||
本リリースは、リバースプロキシ系機能に関する以前のリスク通知を引き続き適用します。
|
||||
|
||||
**Codex OAuth リバースプロキシ**: ChatGPT サブスクリプションの Codex OAuth をリバースプロキシ経由で使用すると、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 release notes](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
|
||||
|
||||
**Codex サードパーティプロバイダー Chat ルーティング**: CC Switch ローカルプロキシで Codex リクエストを変換し、サードパーティプロバイダーへ転送する場合、課金・コンプライアンス・データ保持に関する制約はプロバイダーごとに異なります。利用前に対象プロバイダーの利用規約を確認してください。
|
||||
|
||||
**Claude Desktop サードパーティプロバイダープロキシ切り替え**: CC Switch 内蔵のプロキシゲートウェイで Claude Desktop のリクエストをサードパーティプロバイダーへ転送する場合も、対象プロバイダーの課金・コンプライアンス・データ保持に関する規約に従う必要があります。
|
||||
|
||||
上記機能を有効化したユーザーは、関連するリスクを自ら負うものとします。CC Switch は、これらの機能の利用によって発生したアカウント制限、警告、サービス停止について責任を負いません。
|
||||
|
||||
---
|
||||
|
||||
## 謝辞
|
||||
|
||||
v3.16.4 で機能と修正を届けてくださった以下のコントリビューターに感謝します：
|
||||
|
||||
- [#3817](https://github.com/farion1231/cc-switch/pull/3817): 転送前にリクエストボディを展開し zstd に対応、@chenx-dust に感謝。
|
||||
- [#4583](https://github.com/farion1231/cc-switch/pull/4583): Copilot / Codex OAuth モジュールがグローバルプロキシをバイパスし Claude モデルが 400 になる問題を修正、@zymouse に感謝。
|
||||
- [#4589](https://github.com/farion1231/cc-switch/pull/4589): ローカルプロキシのリクエストオーバーライド（カスタムリクエストヘッダーとリクエストボディ）を追加、@mfzzf に感謝。
|
||||
- [#4575](https://github.com/farion1231/cc-switch/pull/4575): データベースのバージョンが新しすぎる場合のアプリ内リカバリ画面を追加、@SaladDay に感謝。
|
||||
- [#4556](https://github.com/farion1231/cc-switch/pull/4556): 複数箇所の JsonEditor にダークモードを導入、@TanKimzeg に感謝。
|
||||
- [#4438](https://github.com/farion1231/cc-switch/pull/4438): カスタム日付範囲のリアルタイム終了時刻を追加、@arichyx に感謝。
|
||||
- [#3950](https://github.com/farion1231/cc-switch/pull/3950): Windows ARM64 リリースのサポートを追加、@MOON-DREAM-STARS に感謝。
|
||||
- [#4401](https://github.com/farion1231/cc-switch/pull/4401): Kimi For Coding プリセットに CLAUDE_CODE_AUTO_COMPACT_WINDOW を追加、@cyijun に感謝。
|
||||
- [#4323](https://github.com/farion1231/cc-switch/pull/4323): Skills 管理とモデル設定のインタラクション表示を修正、@thisTom に感謝。
|
||||
- [#3431](https://github.com/farion1231/cc-switch/pull/3431): カスタム設定ディレクトリの Claude MCP パスを揃える、@makoMakoGo に感謝。
|
||||
- [#4159](https://github.com/farion1231/cc-switch/pull/4159): 関数名を欠く Chat ツール呼び出しをスキップ、@hueifeng に感謝。
|
||||
- [#4385](https://github.com/farion1231/cc-switch/pull/4385): glm-5.2 の価格を追加、@arichyx に感謝。
|
||||
- [#4079](https://github.com/farion1231/cc-switch/pull/4079): models.dev からのモデル価格インポートに対応、@kingcanfish に感謝。
|
||||
- [#4315](https://github.com/farion1231/cc-switch/pull/4315): プリセット検索後に結果をクリック選択できない問題を修正、@RuixeWolf に感謝。
|
||||
- [#4316](https://github.com/farion1231/cc-switch/pull/4316): 重複した Codex base_url 項を防止、@jeffwcx に感謝。
|
||||
- [#4140](https://github.com/farion1231/cc-switch/pull/4140): プロバイダーターミナルがユーザーの shell を尊重するように、@zkforge に感謝。
|
||||
- [#4113](https://github.com/farion1231/cc-switch/pull/4113): セッション詳細ヘッダーにソースファイル名を表示、@xu-song に感謝。
|
||||
- [#4160](https://github.com/farion1231/cc-switch/pull/4160): Codex のキャッシュされたツール呼び出しフィールドを復元、@chen-985211 に感謝。
|
||||
- [#4239](https://github.com/farion1231/cc-switch/pull/4239): DeepSeek endpoint で thinking:disabled のとき effort パラメータを剥がす、@maskshell に感謝。
|
||||
- [#4165](https://github.com/farion1231/cc-switch/pull/4165): 設定タブ切り替え時にスクロールをリセット、@Muleizhang に感謝。
|
||||
- [#4319](https://github.com/farion1231/cc-switch/pull/4319): 廃止された Homebrew tap 手順を削除、@tianpeng-dev に感謝。
|
||||
- [#4522](https://github.com/farion1231/cc-switch/pull/4522): SubRouter プロバイダープリセットを追加、@abingyyds に感謝。
|
||||
|
||||
v3.16.3 リリース後に Codex プロキシ経路、使用量の課金、ローカルプロキシの堅牢性、プラットフォーム互換性の問題を報告してくださったすべてのユーザーにも感謝します。今回の多くのパッチは、こうした実際の利用シーンから得られた再現の手がかりに基づいています。
|
||||
|
||||
---
|
||||
|
||||
## ダウンロードとインストール
|
||||
|
||||
[Releases](https://github.com/farion1231/cc-switch/releases/latest) から、お使いのシステムに対応するビルドをダウンロードしてください。
|
||||
|
||||
### システム要件
|
||||
|
||||
| システム | 最低バージョン | アーキテクチャ |
|
||||
| -------- | ------------------------ | ----------------------------------- |
|
||||
| Windows | Windows 10 以降 | x64 / ARM64 |
|
||||
| macOS | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 下表を参照 | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| ファイル | 説明 |
|
||||
| ---------------------------------------- | -------------------------------------------- |
|
||||
| `CC-Switch-v3.16.4-Windows.msi` | **推奨** - 自動更新対応の MSI インストーラー |
|
||||
| `CC-Switch-v3.16.4-Windows-Portable.zip` | ポータブル版、展開してそのまま実行できます |
|
||||
|
||||
Windows ARM64 デバイスをお使いの場合は、ファイル名に `arm64` 識別子が含まれる対応する制品を選択してください。
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| -------------------------------- | ------------------------------------------------------ |
|
||||
| `CC-Switch-v3.16.4-macOS.dmg` | **推奨** - DMG インストーラー、Applications へドラッグ |
|
||||
| `CC-Switch-v3.16.4-macOS.zip` | 展開して Applications へドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.16.4-macOS.tar.gz` | Homebrew インストールと自動更新用 |
|
||||
|
||||
Homebrew インストール：
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Linux アセットは **x86_64** と **ARM64**（`aarch64`）の両方を提供します。ファイル名にアーキテクチャ識別子が含まれているため、マシンの `uname -m` 出力に合わせて選択してください：
|
||||
|
||||
- `CC-Switch-v3.16.4-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- `CC-Switch-v3.16.4-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| ディストリビューション | 推奨形式 | インストール方法 |
|
||||
| --------------------------------------- | ----------- | ------------------------------------------------------------------------- |
|
||||
| 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` |
|
||||
</content>
|
||||
</invoke>
|
||||
@@ -0,0 +1,354 @@
|
||||
# CC Switch v3.16.4
|
||||
|
||||
> 🎉 **CC Switch 跻身 GitHub 全球 Star 排行榜前 100！**
|
||||
> 感谢每一位用户、贡献者与 Star —— 是你们让它走到这里。🙏
|
||||
|
||||
> 继 v3.16.3 把「用量计费做准」之后，这一版把重心放在打磨 Codex 代理链路与丰富用量 / 定价工具上——国产供应商原生 Responses 迁移、上游格式选择器与模型映射解耦、zstd 请求 / 错误体解压，以及一批工具调用与 OAuth 走代理的修复；同时新增本地代理请求覆盖、数据库版本过新时的应用内恢复屏、原生 Windows ARM64 构建，并带来一波预设与品牌更新（SubRouter、OpenCode Go、CTok→ETok 改名、Kimi 品牌刷新与 prime-partner 徽标）。
|
||||
|
||||
**[English →](v3.16.4-en.md) | [日本語版 →](v3.16.4-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 使用攻略
|
||||
|
||||
本版以打磨与扩展为主，新增的能力主要落在用量面板与供应商表单的高级选项里，建议结合以下文档了解：
|
||||
|
||||
- **[Codex 桌面看不到自定义模型？](../guides/codex-desktop-custom-model-visibility-zh.md)**：不少用户反馈在 Codex 桌面应用里看不到配置的第三方 / 自定义模型。这是 Codex 桌面应用**上游自身的门控行为**（按官方登录状态放行模型选择器），并非 CC Switch 的本地配置问题，**本版（v3.16.4）未对此做改动**；文档里说明了原因，以及可用的缓解办法（保留官方登录 + 路由接管）。
|
||||
- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：了解用量看板的数据来源与统计口径。本版新增了从 models.dev 批量导入模型定价、火山方舟 Coding / Agent Plan 的 AK/SK 用量查询，以及自定义日期范围的「实时结束时间」。
|
||||
- **[设置](../user-manual/zh/1-getting-started/1.5-settings.md)**：本地代理请求覆盖（自定义请求头 / 请求体）、Codex 上游格式选择器与本地路由开关等都在供应商表单的高级选项里。
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## 唯一官方渠道声明（请务必阅读）
|
||||
>
|
||||
> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。请仅通过下列官方渠道获取本软件：
|
||||
>
|
||||
> | 类别 | 唯一官方 |
|
||||
> | -------- | ------------------------------------------------------------------------------ |
|
||||
> | 官网 | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | 源码 | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | 下载 | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | 作者 | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.16.4 是 v3.16.3 之后的一版维护更新。这一版围绕 Codex 代理链路做了一轮收紧——为多家具备原生 OpenAI Responses 端点的国产供应商切换到原生格式（省去 Responses→Chat 的路由接管转换）、把「上游格式」从「本地路由」开关里独立出来、补上 zstd 请求与错误响应体的解压，并修了一串工具调用与「OAuth 模块绕过全局代理」的问题。
|
||||
|
||||
与此同时，本版还丰富了用量与定价工具（从 models.dev 导入定价、火山方舟 Coding / Agent Plan 的 AK/SK 用量查询、自定义日期范围的实时结束时间、GLM-5.2 与豆包 Seed 2.1 定价），新增了一批代理与韧性能力（自定义请求头 / 请求体覆盖、数据库版本过新时的应用内恢复屏、原生 Windows ARM64 构建），并带来一波预设与品牌更新（SubRouter 与 OpenCode Go 订阅、CTok→ETok 改名、Kimi 品牌刷新与 prime-partner 徽标、Kimi K2.7 Code 赞助横幅）。
|
||||
|
||||
**发布日期**：2026-06-27
|
||||
|
||||
**更新规模**：53 commits | 126 files changed | +8,149 / -1,016 lines
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- **国产 Codex 供应商走原生 Responses**：千问 / 百炼、小米 MiMo、火山豆包、美团 LongCat、MiniMax（国内 / 国际）现在直连各自的原生 Responses 端点，不再经过 Responses→Chat 的格式转换接管，链路更短、更稳。
|
||||
- **本地代理请求覆盖**：供应商可配置自定义请求头与请求体覆盖，由本地代理在转发时应用，并对受保护的安全请求头做了拦截校验。
|
||||
- **数据库版本过新的应用内恢复屏**：当 SQLite 版本比当前应用支持的更新时，不再死在「重试只会再次失败」的原生弹窗里，而是引导到一个可一键升级应用的恢复界面。
|
||||
- **更丰富的用量 / 定价工具**：从 models.dev 批量导入模型定价、火山方舟 Coding / Agent Plan 的 AK/SK 用量查询、自定义日期范围的「实时结束时间」，以及 GLM-5.2 与豆包 Seed 2.1 的定价。
|
||||
- **新预设与品牌更新**：新增 SubRouter 与 OpenCode Go 订阅预设，CTok 改名为 ETok，刷新 Kimi 品牌标识并为官方 Kimi 预设加上 prime-partner 心形徽标。
|
||||
- **原生 Windows ARM64 构建**：发布产物新增原生 ARM64 版本，ARM 架构的 Windows 设备不再依赖 x64 模拟。
|
||||
|
||||
---
|
||||
|
||||
## 新功能
|
||||
|
||||
### 数据库版本过新时的应用内恢复屏
|
||||
|
||||
当 SQLite 的 `user_version` 比当前应用支持的 `SCHEMA_VERSION` 更新时（例如降级回旧版、或被第三方客户端写过该文件），启动过去会死在一个原生的「重试 / 退出」弹窗里——而「重试」只会再次失败。现在应用会引导到一个专门的恢复界面：有可用更新时提供一键「升级应用」按钮（下载 + 安装 + 重启，带进度条），没有可用更新时则提示即便是最新版也读不了这个数据库。该「版本过新」检查在任何写库动作之前进行，因此应用永远不会对一个读不懂的数据库执行 DDL；恢复模式下的原生关闭会干净退出（此时托盘尚未创建）。（[#4575](https://github.com/farion1231/cc-switch/pull/4575)）
|
||||
|
||||
### 本地代理请求覆盖（自定义请求头与请求体）
|
||||
|
||||
供应商配置现在可以定义自定义请求头与请求体覆盖，由本地代理在转发时应用，并通过 Claude 与 Codex 供应商表单里的新字段暴露。输入会经过校验，其中包含一份受保护的请求头名单，用于阻止覆盖安全敏感的请求头。（[#4589](https://github.com/farion1231/cc-switch/pull/4589)）
|
||||
|
||||
### 火山方舟 Coding / Agent Plan 用量查询
|
||||
|
||||
用量面板现在可以查询火山方舟（Volcengine Ark）的 Coding Plan 与 Agent Plan 配额。由于方舟控制面 OpenAPI（`open.volcengineapi.com`）要求的是账号级 AccessKey 签名、而非推理 API key，用量脚本新增了独立的 AK/SK 输入区，并配有一个直达火山 IAM 密钥管理控制台（`https://console.volcengine.com/iam/keymanage`）的可点击链接；代理实现了火山签名 V4（一个 AWS SigV4 变体：固定的 canonical header 顺序、`HMAC-SHA256` 算法、`ark` 服务 scope）。它会先探测 `GetAFPUsage`（Agent Plan 的 5 小时 / 周 / 月配额）自动判定套餐，失败再回退到 `GetCodingPlanUsage`，从 `Level` 字段解析窗口标签（并对 `ResetTimestamp <= 0` 做守卫），同时在用量页脚、托盘菜单与四种语言里补上了 `monthly` 档标签。
|
||||
|
||||
### 从 models.dev 导入模型定价
|
||||
|
||||
「添加定价」面板新增了一个「从 models.dev 导入」按钮：拉取 `https://models.dev/api.json`，支持全文搜索整个目录，并通过与手动录入相同的 `update_model_pricing` 路径导入所选条目。导入的 model id 会按后端的 `clean_model_id_for_pricing` 规则归一化（剥供应商前缀、转小写、截断 `:` 后缀、把 `@` 映射为 `-`、丢掉 `[1m]` 标记），让落库的行真正能匹配成本归因查询。配套修复让「按范围回填零成本」改用 Rust 端按原始 model 别名（路由前缀、`:free` 变体、日期后缀）匹配，而不再用精确 SQL 字符串匹配，从而新定价的别名行能立刻被计价、而不必等下次启动回填（修复 [#4017](https://github.com/farion1231/cc-switch/issues/4017)）。（[#4079](https://github.com/farion1231/cc-switch/pull/4079)）
|
||||
|
||||
### 原生 Windows ARM64 构建
|
||||
|
||||
发布产物现在包含原生的 Windows ARM64 制品，ARM 架构的 Windows 设备可以拿到对应的原生构建，不必再依赖 x64 模拟。发布矩阵也改为各平台独立运行（关闭 fail-fast），因此某个任务缺少密钥而失败（例如 fork 里的 macOS 签名）不会再把尚未完成的同级任务一并取消。（[#3950](https://github.com/farion1231/cc-switch/pull/3950)）
|
||||
|
||||
### 自定义日期范围的实时结束时间
|
||||
|
||||
自定义日期范围选择器新增了一个「结束时间跟随当前时间」勾选框；开启后结束时间变为只读并自动跟随此刻，因此用量数据始终反映从所选起点到当下的实时消耗。这在 Coding Plan 的 5 小时配额窗口里尤其有用。`liveEndTime` 已纳入 React Query 的缓存键，因此一个实时范围和一个端点相同的固定范围不会再共用同一个陈旧缓存项。（[#4438](https://github.com/farion1231/cc-switch/pull/4438)）
|
||||
|
||||
### 会话详情头显示源文件名
|
||||
|
||||
会话详情头现在会在项目目录旁显示会话日志的文件名（悬停看完整路径、可点击复制），方便用户直接从界面定位并打开底层的 JSONL 文件。对于像 ~70 字符的 Codex rollout 这类没有空格的长文件名，会截断到 `max-w-[200px]`，避免在窄窗口里溢出到操作按钮区。（[#4113](https://github.com/farion1231/cc-switch/pull/4113)）
|
||||
|
||||
### 导入按钮的未托管 Skill 提示
|
||||
|
||||
顶栏的 Skills 导入按钮现在会在本地存在未托管的 Skill 可导入时显示一个绿点与提示，让你一眼看出磁盘上的 Skill 还没被纳管。该扫描在挂载时执行一次，并在多次导航间共享（30s `staleTime` + `keepPreviousData`），避免重复磁盘 IO。
|
||||
|
||||
### OpenCode Go 订阅预设
|
||||
|
||||
新增 OpenCode Go（`opencode.ai/zen/go`）预设，覆盖 Claude、Codex 与 OpenCode，使用可直接粘贴的纯 API key（无 OAuth）。Codex 预设走 `openai_chat` 转换并带 GLM / Kimi / DeepSeek / MiMo 模型目录（且不带静态 `codexChatReasoning`，按每个模型推断能力），OpenCode 则通过 `@ai-sdk/openai-compatible` 指向 `/zen/go/v1`。四个 OpenCode Go 预设——Claude、Claude Desktop、Codex、OpenCode——都带上了推荐链接与应用内推广文案；推广横幅现在仅凭 `partnerPromotionKey` 即可展示（不再绑定 `isPartner`），因此一个预设可以展示推荐推广却不获得金色付费合作伙伴星标（这也顺带让既有的 MiniMax 推广重新显示出来）。
|
||||
|
||||
### Prime-Partner 预设徽标与排序
|
||||
|
||||
第一方 Moonshot Kimi 预设（Kimi / Kimi For Coding / Kimi K2.7 Code）现在被标记为 prime partner：不再显示金色星标，而是渲染一颗实心金色心形（无徽标边框），并在默认（Original）排序里浮到官方分类预设之后、其余之前。分组用三路 partition 实现，每组保持内部顺序，且一个同时被标为 prime-partner 的官方预设只会留在官方组里。
|
||||
|
||||
### GLM-5.2 与豆包 Seed 2.1 定价
|
||||
|
||||
种子模型定价现在包含 GLM-5.2（[#4385](https://github.com/farion1231/cc-switch/pull/4385)）与豆包 Seed 2.1 Pro / Turbo，让这些模型的用量被正确计价、而不是记成零成本。豆包价格采用火山官方 list 价（按约 7.14 的汇率折算）；`cache_creation` 保持为 0，因为豆包按时间而非按 token 写入计费缓存存储，既有的 2.0 行也保留以供历史记账。
|
||||
|
||||
### Kimi For Coding 自动压缩窗口
|
||||
|
||||
Kimi For Coding 预设现在把 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 默认设为 262144，与 Kimi 官方文档一致，并通过 `templateValues` 暴露，方便用户为将来的模型或性能调优自定义该值。（[#4401](https://github.com/farion1231/cc-switch/pull/4401)）
|
||||
|
||||
### SubRouter 合作伙伴供应商
|
||||
|
||||
新增 SubRouter（`subrouter.ai`，一个让一把 key 访问多模型多供应商的 AI 中转聚合商）作为预设，覆盖全部 7 个受管应用——Anthropic 格式端点用于 Claude Code / Claude Desktop / OpenClaw / Hermes，OpenAI 兼容的 `/v1` 端点（`gpt-5.5`）用于 Codex 与 OpenCode，Gemini 兼容的 `/v1beta` 端点（`gemini-3.5-flash`）用于 Gemini CLI——带上自有品牌图标、金色合作伙伴星标、四语推广文案，以及预填为 API key 注册地址的推荐注册链接（`?aff=l3ri`）。（[#4522](https://github.com/farion1231/cc-switch/pull/4522)）
|
||||
|
||||
---
|
||||
|
||||
## 变更
|
||||
|
||||
### 国产 Codex 供应商走原生 Responses API
|
||||
|
||||
多家国产供应商（千问 / DashScope 百炼、小米 MiMo、火山豆包、美团 LongCat、MiniMax 国内 / 国际）现在暴露了原生的 OpenAI Responses 端点，因此它们的 Codex 预设切换到 `apiFormat: "openai_responses"`，直连上游而不再经过 Responses→Chat 的路由接管转换。丢掉不再需要的 `codexChatReasoning` 与 `modelCatalog` 也让「本地路由映射」开关默认保持未勾选。SiliconFlow 托管的 MiniMax 仍保持 `openai_chat`，因为那是第三方端点、并非 MiniMax 自家 base_url。其余仍走 chat 的供应商也刷新了过期的 model id（GLM 5.1→5.2、StepFun 3.5-flash-2603→3.7-flash、Ling 2.5-1T→2.6-1T）。
|
||||
|
||||
### 上游格式选择器与模型映射开关解耦
|
||||
|
||||
Codex 供应商表单此前把 Chat 格式转换与路由接管（模型映射）绑在同一个开关上，导致一个提供原生 Responses API 的供应商无法在不强制 Chat Completions 转换的情况下使用模型映射。现在「上游格式」（Chat Completions / Responses）成了一个独立、始终可见的选择器，而本地路由开关只负责控制高级子区（模型映射目录，以及格式为 Chat 时的推理能力）。它的初始状态由已保存目录是否存在派生，不新增持久化字段；`codexConfig` 的四语（zh / en / ja / zh-TW）文案也随之重写。
|
||||
|
||||
### 豆包 Seed 2.1 Pro 预设
|
||||
|
||||
DouBaoSeed 预设现在在全部 6 个客户端（claude、claude-desktop、codex、opencode、openclaw、hermes）指向 `doubao-seed-2-1-pro`（替换 `doubao-seed-2-0-code-preview-latest`），展示名更新为「Doubao Seed 2.1 Pro」，并把 OpenClaw 的成本字段从 0.002 / 0.006 订正为 0.84 / 4.2 美元每百万 token 以匹配新模型。
|
||||
|
||||
### CTok 改名为 ETok
|
||||
|
||||
随着厂商对域名、端点与商标的更名，所有面向用户的品牌从 CTok 迁移到 ETok（`ctok.ai`→`etok.ai`、`api.ctok.ai`→`api.etok.ai`，以及内部 id、展示名、图标和 README 合作伙伴横幅），覆盖每一个客户端预设。Codex 历史迁移白名单里仍保留 `ctok` 作为旧 id、与新 `etok` 并存，以保证改名后存量用户的本地会话历史仍被正确分桶。
|
||||
|
||||
### Kimi 预设命名统一
|
||||
|
||||
OpenCode 与 OpenClaw 此前被标为「Kimi K2.7 Code」的 Kimi 预设，更名为与其它应用一致的「Kimi」（OpenCode 的供应商展示名也一并更名）；模型标签仍保留「Kimi K2.7 Code」，因为它描述的是实际模型。
|
||||
|
||||
### JSON 编辑器暗色模式
|
||||
|
||||
用量脚本弹窗、供应商表单与通用供应商表单里的 CodeMirror `JsonEditor` 现在会通过 `useDarkMode()` 跟随应用主题，切换到 `oneDark` 编辑器主题，而不再在应用其余部分已是暗色时仍停留在亮色。（[#4556](https://github.com/farion1231/cc-switch/pull/4556)）
|
||||
|
||||
### 更紧凑的「添加供应商」标题与底部提示
|
||||
|
||||
「添加供应商」对话框把标题到页签、页签到卡片的纵向间距从 24px 收到 12px，并新增一个始终可见的固定底部提示，引导用户在选好预设后填写下方字段。`FullScreenPanel` 新增可选的 `contentClassName` 属性，让内边距覆盖只作用于此面板、不影响其它共用它的面板。
|
||||
|
||||
### 主题自适应的 Kimi 标识
|
||||
|
||||
内联的 Kimi 占位标记替换为厂商刷新后的标识。K 字形使用 `currentColor`，因此会跟随主题文字色（亮色模式深、暗色模式白），而品牌点缀色固定为新的 `#1783FF`，元数据回退色也相应对齐。
|
||||
|
||||
### 移除 Fable 5 Verified 纪念横幅
|
||||
|
||||
设置「关于」页不再显示 3.16.3 为标明特别构建而加在应用名旁的 Fable 5 Verified 纪念横幅；横幅图片及其标记被移除，「关于」面板回到标准的版本徽标布局。
|
||||
|
||||
---
|
||||
|
||||
## 修复
|
||||
|
||||
### Copilot / Codex OAuth 请求现在遵循全局代理
|
||||
|
||||
`CopilotAuthManager` 与 `CodexOAuthManager` 在构造时写死了 `Client::new()`，导致它们的认证流程（换 token、拉 `/models` 列表、判定 model vendor、device-code 与 OAuth 刷新请求）无视配置的全局代理、直连目标服务。在 Copilot 上，直连会让 `/models` 返回 0 个 Claude 模型，使 live 模型解析失效，上游以 `400 model_not_supported` 拒绝请求。现在两个 manager 都改为每次请求从共享客户端现取（`crate::proxy::http_client::get()`），从而遵循全局代理 URL 并支持运行时热更新。修复 [#2016](https://github.com/farion1231/cc-switch/issues/2016)、[#2931](https://github.com/farion1231/cc-switch/issues/2931)。（[#4583](https://github.com/farion1231/cc-switch/pull/4583)）
|
||||
|
||||
### 压缩请求体与错误体的解压
|
||||
|
||||
Codex Desktop 在对 Codex 后端认证时会发送 zstd 压缩的请求体，这会破坏本地代理路由，因为处理器直接用 `serde_json` 解析原始压缩字节。代理现在会在 JSON 解析前对请求体解压（gzip / br / deflate，外加新增的 zstd 支持，包括 `gzip, zstd` 这类堆叠编码），覆盖三个 Codex 处理器，并剥掉过期的 `content-encoding` / `content-length` / `transfer-encoding` 请求头让转发器重新生成。上游非 2xx 的错误体也以同样方式解压，因此压缩过的限流与鉴权细节不再被丢弃、对客户端隐藏。修复 [#3764](https://github.com/farion1231/cc-switch/issues/3764)、[#3696](https://github.com/farion1231/cc-switch/issues/3696)。（[#3817](https://github.com/farion1231/cc-switch/pull/3817)）
|
||||
|
||||
### DeepSeek 端点 `thinking: disabled` 的 400 错误
|
||||
|
||||
DeepSeek 的 Anthropic 兼容端点会拒绝 `thinking.type=disabled` 与 effort 参数共存的请求、返回 HTTP 400，这会破坏 Claude Code 2.1.166+ 那些硬编码 `thinking: disabled` 的子 agent（Workflow / Dynamic Workflow）。代理现在不是去覆盖客户端的意图，而是对官方 DeepSeek 端点剥掉冲突的 `output_config.effort` / `reasoning_effort` 参数，因为子 agent 本就不需要展示推理。（[#4239](https://github.com/farion1231/cc-switch/pull/4239)）
|
||||
|
||||
### 回滚 Anthropic system 消息上提
|
||||
|
||||
回滚了 [#3775](https://github.com/farion1231/cc-switch/pull/3775) 把 Anthropic 兼容供应商的 `role=system` 消息从 `messages[]` 上提到顶层 `system` 字段的改动。DeepSeek 端点本就原生接受内联的 system 消息，而该重写改变了请求前缀；保持消息原位能保留 prompt 前缀，避免一处疑似的缓存命中率回退（参见 [#4297](https://github.com/farion1231/cc-switch/issues/4297)）。来自 #3775 的、不相关的 Windows 测试修复以及 tool-thinking-history 归一化都保留。
|
||||
|
||||
### Chat 工具调用缺函数名
|
||||
|
||||
一些上游会在流式工具调用增量里发送空的或缺失的函数名，过去这会产生无效的 Codex Chat 输出项（或一个 `unknown_tool` 回退）。现在累积的工具调用状态不会再被空增量覆盖，而那些始终没拿到 `call_id` 与有效名字的工具调用会在最终化阶段被跳过，覆盖流式、非流式与旧版 `function_call` 三条路径。（[#4159](https://github.com/farion1231/cc-switch/pull/4159)）
|
||||
|
||||
### 恢复 Codex 缓存的工具调用字段
|
||||
|
||||
当 Codex 发起一个引用 `previous_response_id` 的后续 Chat 请求时，它的 `function_call` 项可能只携带 `call_id`。历史增强此前只回填 `reasoning` / `reasoning_content`，留空了函数的 `name`、`arguments`、`status` 等字段；现在它会从历史里恢复全部缓存的工具调用字段，让该调用能为 Chat 上游正确重建。（[#4160](https://github.com/farion1231/cc-switch/pull/4160)）
|
||||
|
||||
### config.toml 里重复的 Codex base_url 条目
|
||||
|
||||
把 Codex 的 `base_url` 写入 `config.toml` 时此前每个区段只替换或移除一个匹配的赋值，因此一个已经含多行 `base_url` 的区段会留下多余项、累积重复。`setCodexBaseUrl` 现在会折叠目标区段或顶层的所有匹配（替换第一处、移除其余），TOML 的 `base_url` 正则也处理了转义引号。（[#4316](https://github.com/farion1231/cc-switch/pull/4316)）
|
||||
|
||||
### 历史迁移探测 CODEX_SQLITE_HOME 的状态库
|
||||
|
||||
Codex 会话历史迁移此前只扫描 `~/.codex/state_5.sqlite` 与 `config.toml` 的 `sqlite_home` 位置，因此当 Codex 的 SQLite 状态通过 `CODEX_SQLITE_HOME` 环境变量被重定位时，状态库从未被扫描、其 threads 仍留在旧的供应商分桶里。第三方与统一会话两套迁移共用的 `codex_state_db_paths` 辅助函数现在会回退到 `CODEX_SQLITE_HOME`（`config` 里的 `sqlite_home` 仍优先）。
|
||||
|
||||
### 供应商终端尊重用户 shell
|
||||
|
||||
在 macOS / Linux 上启动供应商终端时此前硬编码了 `bash`，导致 zsh / fish 用户的 rc 文件不会加载。启动器现在会从 `$SHELL` 检测用户默认 shell（macOS 回退 `/bin/zsh`、Linux 回退 `/bin/bash`）并以干净启动的 flag exec 进去，而启动脚本本身改走 POSIX `sh` 以保证可移植性（例如 fish，以及 `/bin/sh` 可能不存在的 NixOS）。（[#4140](https://github.com/farion1231/cc-switch/pull/4140)，修复 [#1546](https://github.com/farion1231/cc-switch/issues/1546)）
|
||||
|
||||
### Claude MCP 路径尊重自定义配置目录
|
||||
|
||||
当配置了自定义的 Claude 配置目录时，MCP server 的读写现在会解析到该目录下的 MCP 文件、而非默认位置，让 MCP 状态按 profile 隔离。此前对旧文件的「访问即拷贝」迁移被移除，改为直接解析覆盖路径。（[#3431](https://github.com/farion1231/cc-switch/pull/3431)）
|
||||
|
||||
### 搜索后预设结果可点击
|
||||
|
||||
在「添加供应商」预设选择器里搜索后，结果一度无法点击或选中。那个与输入打架、会吃掉首字符（如「gateway」→「ateway」）的 `requestAnimationFrame` `select()` 被移除，开箱即点路径的输入自动聚焦被恢复，当搜索框已打开时按 Ctrl/Cmd+F 也接上了重新聚焦。供应商列表的打字守卫也被收窄到 Ctrl/Cmd+F 分支，从而 Escape 仍能关闭搜索面板。（[#4315](https://github.com/farion1231/cc-switch/pull/4315)）
|
||||
|
||||
### Skills 浏览与供应商卡片显示修复
|
||||
|
||||
修复了若干显示与交互问题：浏览 skills.sh 时仓库管理操作保持可用，仓库返回空结果时刷新也保持可用；供应商卡片上过长的供应商名与网站 URL 现在会截断而非溢出；OMO 模型变体下拉会截断所选标签并配全文提示；Select 菜单项会在当前选中项上显示对勾。（[#4323](https://github.com/farion1231/cc-switch/pull/4323)）
|
||||
|
||||
### 切换设置页签时重置滚动
|
||||
|
||||
在设置对话框里切换页签会保留上一个页签的滚动位置，有时会停在新页签的中途；现在每当激活页签变化时，滚动容器都会重置到顶部。（[#4165](https://github.com/farion1231/cc-switch/pull/4165)）
|
||||
|
||||
---
|
||||
|
||||
## 文档
|
||||
|
||||
### Kimi 置顶赞助横幅
|
||||
|
||||
全部四种 README 语言（en / zh / ja / de）顶部的置顶赞助横幅现在换成了 Kimi K2.7 Code，取代此前的 MiniMax M2.7 横幅。文案反映 K2.7 Code 发布（一个面向编程的 agentic 模型，思考 token 用量较 K2.6 降低约 30%），横幅改由仓库内资源（`assets/partners/banners/kimi-banner-en.png` / `kimi-banner-zh.png`）提供、不再走 Moonshot CDN，并附一个指向 `aff=cc-switch` Moonshot 控制台的可点击行动号召。
|
||||
|
||||
### Codex 统一会话历史攻略
|
||||
|
||||
新增三语（zh / en / ja）攻略，讲清统一 Codex 会话历史开关的开启迁移（启用时）与按账本还原（禁用时）到底做了什么、为什么会话数据从不会真正删除（只改标记 + 自动备份），以及如何核对文件是真在磁盘上、还是只是被归到了另一个供应商抽屉里。它包含一张针对常见「我的会话不见了」误解的症状对照表，以及 macOS / Linux / Windows 的磁盘核对命令，并作为首项链入 v3.16.3 的「使用攻略」release notes。
|
||||
|
||||
### 简化 Homebrew 安装说明
|
||||
|
||||
安装指南不再要求用户在 `brew install --cask cc-switch` 之前先运行 `brew tap farion1231/ccswitch`；这个已废弃的 tap 步骤已从 en / ja / zh 用户手册里移除，cask 现在可直接安装。（[#4319](https://github.com/farion1231/cc-switch/pull/4319)）
|
||||
|
||||
### Star-History 全球排名徽标
|
||||
|
||||
在全部四种 README 语言里、既有的 Trendshift 徽标旁新增了一个 star-history 全球排名徽标，并带亮 / 暗主题变体。
|
||||
|
||||
### 火山方舟 Coding Plan 活动链接
|
||||
|
||||
ByteDance / 火山方舟赞助条目里的「中国大陆地区的开发者请点击这里」链接现在指向火山的 `ai618` 活动页，取代此前的 `codingplan` 推荐 URL，覆盖全部四种 README 语言。
|
||||
|
||||
### CCSub 赞助横幅矢量资源
|
||||
|
||||
把低分辨率的 `ccsub.jpg` 赞助 logo 替换为矢量的 `ccsub.svg`，并从 2046x648 letterbox 到 2046x850（约 2.406:1），使其与其它赞助表横幅匹配、以相同的 62px 高度渲染。全部四种 README 语言都指向新资源。
|
||||
|
||||
---
|
||||
|
||||
## 升级提醒
|
||||
|
||||
### 国产 Codex 供应商原生 Responses 迁移
|
||||
|
||||
本版把多家具备原生 Responses 端点的国产供应商（千问 / 百炼、小米 MiMo、火山豆包、美团 LongCat、MiniMax 国内 / 国际）的 Codex 预设切换为 `openai_responses` 并移除了 `modelCatalog`。已经基于这些预设配置过的存量供应商不受影响、配置保持原样；如果你希望改用原生 Responses（省去格式转换接管），可以重新从预设选择一次并保存。SiliconFlow 托管的 MiniMax 仍走 `openai_chat`，不在此次迁移之列。
|
||||
|
||||
### 数据库版本过新的恢复
|
||||
|
||||
如果你曾用更高版本的 CC Switch 打开过数据库、再切回旧版，旧版启动时会进入新的「数据库版本过新」恢复屏，并引导你升级到能读懂该数据库的版本。这是预期行为——升级到最新版即可恢复正常。
|
||||
|
||||
---
|
||||
|
||||
## 风险提示
|
||||
|
||||
本版本继续沿用此前版本对反向代理类功能的风险提示。
|
||||
|
||||
**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
|
||||
|
||||
**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
|
||||
|
||||
**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，同样需要遵守目标供应商的计费、合规与数据留存约束。
|
||||
|
||||
用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
|
||||
|
||||
---
|
||||
|
||||
## 致谢
|
||||
|
||||
感谢以下贡献者在 v3.16.4 中提交的功能与修复：
|
||||
|
||||
- [#3817](https://github.com/farion1231/cc-switch/pull/3817)：转发前解压请求体并支持 zstd，感谢 @chenx-dust。
|
||||
- [#4583](https://github.com/farion1231/cc-switch/pull/4583)：修复 Copilot / Codex OAuth 模块绕过全局代理导致 Claude 模型 400，感谢 @zymouse。
|
||||
- [#4589](https://github.com/farion1231/cc-switch/pull/4589)：新增本地代理请求覆盖（自定义请求头与请求体），感谢 @mfzzf。
|
||||
- [#4575](https://github.com/farion1231/cc-switch/pull/4575)：新增数据库版本过新时的应用内恢复屏，感谢 @SaladDay。
|
||||
- [#4556](https://github.com/farion1231/cc-switch/pull/4556)：为多处 JsonEditor 接入暗色模式，感谢 @TanKimzeg。
|
||||
- [#4438](https://github.com/farion1231/cc-switch/pull/4438)：新增自定义日期范围的实时结束时间，感谢 @arichyx。
|
||||
- [#3950](https://github.com/farion1231/cc-switch/pull/3950)：新增 Windows ARM64 发布支持，感谢 @MOON-DREAM-STARS。
|
||||
- [#4401](https://github.com/farion1231/cc-switch/pull/4401)：为 Kimi For Coding 预设添加 CLAUDE_CODE_AUTO_COMPACT_WINDOW，感谢 @cyijun。
|
||||
- [#4323](https://github.com/farion1231/cc-switch/pull/4323)：修复 Skills 管理与模型配置的交互展示，感谢 @thisTom。
|
||||
- [#3431](https://github.com/farion1231/cc-switch/pull/3431)：对齐自定义配置目录的 Claude MCP 路径，感谢 @makoMakoGo。
|
||||
- [#4159](https://github.com/farion1231/cc-switch/pull/4159)：跳过缺函数名的 Chat 工具调用，感谢 @hueifeng。
|
||||
- [#4385](https://github.com/farion1231/cc-switch/pull/4385)：新增 glm-5.2 定价，感谢 @arichyx。
|
||||
- [#4079](https://github.com/farion1231/cc-switch/pull/4079)：支持从 models.dev 导入模型定价，感谢 @kingcanfish。
|
||||
- [#4315](https://github.com/farion1231/cc-switch/pull/4315)：修复搜索预设后结果无法点击选中，感谢 @RuixeWolf。
|
||||
- [#4316](https://github.com/farion1231/cc-switch/pull/4316)：防止重复的 Codex base_url 条目，感谢 @jeffwcx。
|
||||
- [#4140](https://github.com/farion1231/cc-switch/pull/4140)：让供应商终端尊重用户 shell，感谢 @zkforge。
|
||||
- [#4113](https://github.com/farion1231/cc-switch/pull/4113)：在会话详情头显示源文件名，感谢 @xu-song。
|
||||
- [#4160](https://github.com/farion1231/cc-switch/pull/4160)：恢复 Codex 缓存的工具调用字段，感谢 @chen-985211。
|
||||
- [#4239](https://github.com/farion1231/cc-switch/pull/4239)：DeepSeek 端点 thinking:disabled 时剥掉 effort 参数，感谢 @maskshell。
|
||||
- [#4165](https://github.com/farion1231/cc-switch/pull/4165)：切换设置页签时重置滚动，感谢 @Muleizhang。
|
||||
- [#4319](https://github.com/farion1231/cc-switch/pull/4319)：移除已废弃的 Homebrew tap 步骤，感谢 @tianpeng-dev。
|
||||
- [#4522](https://github.com/farion1231/cc-switch/pull/4522)：新增 SubRouter 供应商预设，感谢 @abingyyds。
|
||||
|
||||
也感谢所有在 v3.16.3 发布后反馈 Codex 代理链路、用量计费、本地代理稳健性与平台兼容性问题的用户，很多补丁都来自这些真实使用场景里的复现线索。
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
|
||||
|
||||
### 系统要求
|
||||
|
||||
| 系统 | 最低版本 | 架构 |
|
||||
| ------- | -------------------------- | ----------------------------------- |
|
||||
| Windows | Windows 10 及以上 | x64 / ARM64 |
|
||||
| macOS | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 见下表 | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| 文件 | 说明 |
|
||||
| ---------------------------------------- | ----------------------------------- |
|
||||
| `CC-Switch-v3.16.4-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.16.4-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
Windows ARM64 设备请选择文件名中带 `arm64` 标识的对应制品。
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| -------------------------------- | --------------------------------------------- |
|
||||
| `CC-Switch-v3.16.4-macOS.dmg` | **推荐** - DMG 安装包，拖入 Applications 即可 |
|
||||
| `CC-Switch-v3.16.4-macOS.zip` | 解压后拖入 Applications，Universal Binary |
|
||||
| `CC-Switch-v3.16.4-macOS.tar.gz` | 用于 Homebrew 安装和自动更新 |
|
||||
|
||||
Homebrew 安装：
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本：
|
||||
|
||||
- `CC-Switch-v3.16.4-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- `CC-Switch-v3.16.4-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| 发行版 | 推荐格式 | 安装方式 |
|
||||
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| 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` |
|
||||
@@ -0,0 +1,278 @@
|
||||
# CC Switch v3.16.5
|
||||
|
||||
> The centerpiece of this release is **getting native-Responses direct-connect properly adapted for domestic (Chinese) model providers** — generating Codex model catalogs for providers with native Responses endpoints (Xiaomi MiMo, Volcengine Doubao, Qwen3-Coder, Meituan LongCat, MiniMax) so the Codex desktop app can actually see these models and their built-in tools work, and automatically disabling `web_search` for the few domestic gateways that reject it so requests are no longer hard-rejected. Two other important improvements: when you switch providers, the plugins, environment variables, etc. you added inside the app are **automatically written back to the common config and carried over to the next provider**; and Linux (Wayland + NVIDIA) users hitting the "title bar clicks, page is dead, black screen on resize" problem now have an environment-variable escape hatch. This release also brings Claude Sonnet 5 pricing and a default-tier bump, a two-level grouped session view, and a batch of credential-safety and platform-compatibility fixes.
|
||||
|
||||
**[中文版 →](v3.16.5-zh.md) | [日本語版 →](v3.16.5-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Usage Guides
|
||||
|
||||
The new capabilities in this release land mainly in the Codex provider form, the session panel, and usage / common config. The following docs are worth reading alongside it:
|
||||
|
||||
- **[Can't see custom models in the Codex desktop app?](../guides/codex-desktop-custom-model-visibility-en.md)**: this release reworks **model-catalog generation for native direct-connect** — when a Codex provider connects directly via native Responses (`openai_responses`), CC Switch generates `~/.codex/cc-switch-model-catalog.json` so the Codex desktop app can display the configured custom models and their tools work. If you previously configured a native Codex provider, **re-save it once** to regenerate the catalog (see "Upgrade Notes" below).
|
||||
- **[Usage Statistics](../user-manual/en/4-proxy/4.4-usage.md)**: understand the Usage Dashboard's data sources and how the statistics are counted. This release adds Claude Sonnet 5 pricing and fixes usage-script credentials being persisted as "explicit overrides".
|
||||
- **[Settings](../user-manual/en/1-getting-started/1.5-settings.md)**: the Codex upstream-format selector and local routing toggle, and Claude's common config (now renamed "Apply Common Config" and auto-synced on switch) all live in the provider form's advanced options.
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## Only Official Channels (Please Read)
|
||||
>
|
||||
> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Please only obtain the software through the official channels listed below:
|
||||
>
|
||||
> | Channel | Only Official |
|
||||
> | ------------------ | ------------------------------------------------------------------------------ |
|
||||
> | Website | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | Source | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | Downloads | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | Author | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.16.5 is a maintenance update following v3.16.4, centered on **making native Codex direct-connect work end-to-end for domestic model providers**. v3.16.4 already switched Qwen / DashScope, Xiaomi MiMo, Volcengine Doubao, Meituan LongCat, and MiniMax to native Responses endpoints; this release goes a step further and generates the **model catalog** Codex needs (`~/.codex/cc-switch-model-catalog.json`), so the Codex desktop app can really see these custom models and invoke their built-in tools, and it fully decouples model mapping from the "local routing" toggle. For the few domestic gateways whose first-party models don't support OpenAI's built-in `web_search` (MiMo, LongCat, MiniMax, Qwen3-Coder), this release also disables that tool automatically, so Codex's default doesn't trigger a hard 400.
|
||||
|
||||
For everyday use, this release makes Claude's **common config auto-sync and carry over when you switch providers** — the plugins, environment variables, theme, etc. you added inside the running app are first written back to the common config and then handed to the next provider, so they're not lost on switch; it adds an escape-hatch environment variable for Linux (Wayland + NVIDIA) users hitting click-dead / black-screen issues; it adds Claude Sonnet 5 pricing and bumps the default Sonnet tier to it; it brings a two-level "provider → project directory" grouped session view; and it fixes a string of credential-safety (the common-config snippet now strips all secrets, usage-script credentials are only kept as explicit overrides), platform-compatibility (Hermes Windows config directory, Windows Codex npm shims), and UI (long dropdown scrolling, narrow-window date-range picker) issues. It also adds several new provider presets, ready to pick out of the box.
|
||||
|
||||
**Release date**: 2026-07-01
|
||||
|
||||
**Stats**: 36 commits | 93 files changed | +5,678 / -2,804 lines
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- **Native Codex direct-connect actually works for domestic model providers**: CC Switch generates a Codex model catalog (`~/.codex/cc-switch-model-catalog.json`) for domestic providers like Xiaomi MiMo, Volcengine Doubao, Qwen3-Coder, Meituan LongCat, and MiniMax, so the Codex desktop app can see these models and their built-in tools work; and it auto-disables `web_search` for the domestic gateways that reject it (MiMo, LongCat, MiniMax, Qwen3-Coder) to avoid hard 400s. **Existing native providers need a one-time re-save** to regenerate the catalog.
|
||||
- **Common config auto-synced and carried over on switch**: when you switch away from a Claude provider that has the common config enabled, the plugins, environment variables, theme, and hooks you added inside the app are first written back to the common config and then handed to the next provider — no longer overwritten and lost on switch.
|
||||
- **Escape hatch for Linux Wayland click-dead / black-screen**: when you hit "title bar clicks, page doesn't, black screen on resize" on Wayland + NVIDIA, launch with `CC_SWITCH_GDK_BACKEND=wayland` to switch back to native Wayland (set it to `x11` for the inverse problem on tiling compositors).
|
||||
- **Claude Sonnet 5**: adds Sonnet 5 pricing and bumps each preset's default Sonnet tier to `claude-sonnet-5`.
|
||||
- **Categorized session view with grouping**: the session panel gains a two-level "provider → project directory" grouped view, with a tri-state checkbox on each group header for one-click batch selection.
|
||||
- **New provider presets**: adds Qiniu, FennoAI, ZetaAPI, TeamoRouter, NekoCode, Code0.ai, and Amux presets across the managed apps, ready to pick out of the box.
|
||||
|
||||
---
|
||||
|
||||
## Added
|
||||
|
||||
### Native Codex Direct-Connect for Domestic Model Providers (Generated Model Catalog)
|
||||
|
||||
This release makes native Codex direct-connect work for domestic providers. After v3.16.4 switched Xiaomi MiMo, Volcengine Doubao, Qwen3-Coder, Meituan LongCat, and MiniMax to native Responses (`apiFormat: "openai_responses"`), this release reverses the then-current "drop the model catalog on native direct-connect" approach: when these providers connect directly without the local proxy, CC Switch generates `~/.codex/cc-switch-model-catalog.json` for them, so the Codex desktop app really shows these custom models and their built-in tools work — without triggering the freeform `apply_patch` (`type=custom`) tool that native gateways like MiMo reject (editing falls back to `shell_command`). Catalog generation is keyed on `apiFormat` and decoupled from the "local routing" toggle, so a native provider persists a catalog without turning on local route mapping, while `openai_chat` keeps the existing Responses↔Chat proxy conversion unchanged. Because Codex's parser requires `base_instructions` on every entry, the native template carries a neutral default that each vendor's official copy overrides (MiMo, MiniMax). **Existing native providers need a one-time re-save to generate a valid catalog** (no database migration).
|
||||
|
||||
Alongside that, for the few domestic gateways whose first-party models don't support OpenAI's built-in `web_search` tool (MiMo, LongCat, MiniMax, Qwen3-Coder), this release auto-disables the tool on switch, so Codex's default doesn't include it and get hard-rejected with a 400 (see "Fixed" below).
|
||||
|
||||
### Categorized Session View with Grouping
|
||||
|
||||
The Session Manager panel gains a grouped view alongside the existing flat list, toggled via a List / ListTree selector in the toolbar, with view mode and expansion state persisted to `localStorage`. Grouping builds a two-level "provider → project directory" hierarchy: sessions are grouped by project directory name, and sessions with no project directory fall into an "unknown directory" bucket. Both levels are collapsible sections, with a "collapse all" button; in batch mode, each group header shows a tri-state checkbox that selects / deselects every selectable session in that group at once, along with a selected / selectable count badge. Copy across all four locales (zh / en / ja / zh-TW) is in sync. The change is entirely front-end, with no backend commands or data-access changes. ([#4776](https://github.com/farion1231/cc-switch/pull/4776))
|
||||
|
||||
### Claude Sonnet 5 Model Pricing
|
||||
|
||||
Added a `claude-sonnet-5` pricing row in `schema.rs` at Anthropic list pricing — \$3 / \$15 per million input / output tokens and \$0.30 / \$3.75 cache read / write, matching Sonnet 4.6. The introductory \$2 / \$10 promotion (valid through 2026-08-31) is deliberately not seeded, so accounting reflects steady-state list pricing rather than a temporary discount. The row is applied on the app's next start via `ensure_model_pricing_seeded`, with no `SCHEMA_VERSION` bump.
|
||||
|
||||
### New Provider Presets
|
||||
|
||||
This release adds a batch of provider presets; pick one and fill in your own API key to use it:
|
||||
|
||||
- **Qiniu**: covers all seven managed apps (including Gemini), relaying native Claude / GPT / Gemini.
|
||||
- **FennoAI / ZetaAPI / TeamoRouter / NekoCode**: each covers six apps (Claude, Claude Desktop, Codex, OpenCode, OpenClaw, Hermes).
|
||||
- **Code0.ai**: covers all seven apps (including Gemini).
|
||||
- **Amux**: covers six apps.
|
||||
|
||||
Each preset's endpoints and default models are configured for the corresponding app — the Claude family connects directly to an Anthropic-compatible host, Codex uses native Responses, and the rest use the OpenAI-compatible `/v1`.
|
||||
|
||||
---
|
||||
|
||||
## Changed
|
||||
|
||||
### Common Config Auto-Synced and Carried Over on Provider Switch
|
||||
|
||||
This is a very practical change in this release: when you switch away from a Claude provider that has the common config enabled, the service first **re-extracts the shareable portion from its live `settings.json` and updates the common config**, then hands it to the next provider, instead of only writing one way. As a result, the plugins (`enabledPlugins`), hooks, environment variables (`env`), theme (`theme`), and other shared config you added directly in the running app are not silently lost on switch, but automatically follow along to the next provider; deletions sync too (a removed key is not re-injected). This sync is strictly scoped to Claude providers that have the common config enabled, is skipped when it was explicitly cleared, and all failures are non-fatal (warn only) and never block the switch.
|
||||
|
||||
### Codex Model Mapping Decoupled from the "Local Routing" Toggle
|
||||
|
||||
The Codex provider form aligns with Claude Code — the model-mapping catalog is now independent of route takeover, because native Responses providers (MiMo, Doubao, MiniMax) need it for proxy-less direct-connect, while Chat providers go through the proxy regardless. The "needs local routing" toggle is removed (it had no backend field and only gated catalog / reasoning persistence, which is equivalent to whether the mapping is filled in). Model mapping is now always shown for non-official providers and persisted whenever it's non-empty, while reasoning visibility / persistence is gated on the Chat format instead. Copy across all four locales (zh / en / ja / zh-TW) was rewritten accordingly. As a side fix, `useCodexConfigState` no longer drops `supportsParallelToolCalls` / `inputModalities` / `baseInstructions` when loading a saved provider (which used to silently lose parallel tools, image input, and the official base instructions on edit).
|
||||
|
||||
### Default Sonnet Tier Bumped to Claude Sonnet 5
|
||||
|
||||
Bumped the default Sonnet tier in each provider preset from `claude-sonnet-4-6` to `claude-sonnet-5` (across the claude / claude-desktop / hermes / openclaw / opencode presets and the universal `NEWAPI_DEFAULT_MODELS`), covering keys like `ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_OPUS_MODEL` and their prefixed variants. Claude Desktop's default-route sonnet `route_id` also migrates to `claude-sonnet-5`. Non-Anthropic pins (gpt / gemini / glm / sonnet-4-5) are left unchanged.
|
||||
|
||||
### Doubao Dated Model Id and Pricing Normalization
|
||||
|
||||
The Doubao (DouBaoSeed) preset's model id switches to the dated form `doubao-seed-2-1-pro-260628` (across all apps), because Volcengine Ark rejects the bare `doubao-seed-2-1-pro` with a 404 and only accepts the full dated id. Since real usage now carries a date suffix, `strip_model_date_suffix` was extended to also strip Volcengine's 6-digit YYMMDD form (validating month 01-12 and day 01-31 to avoid eating non-date version suffixes like `-123456`), so it normalizes back to hit the bare-name seed row in the pricing table, fixing the \$0-cost display for Doubao models.
|
||||
|
||||
### "Write Common Config" Renamed to "Apply Common Config"
|
||||
|
||||
The original label "Write Common Config" was ambiguous about data-flow direction (it read like "write the current config into the common config"), whereas the actual behavior is the reverse — it merges the saved common-config snippet into this provider's config. The checkbox is renamed to "Apply Common Config" across all four locales (zh / en / ja / zh-TW), including every hint / guide / notice reference, with the Japanese user manual and `README_JA.md` synced too. ([#4829](https://github.com/farion1231/cc-switch/pull/4829))
|
||||
|
||||
### Other Preset and Asset Adjustments
|
||||
|
||||
- **OpenClaw Doubao context aligned to 262144**: OpenClaw's DouBaoSeed preset previously hardcoded 128000 while the Codex side used 262144 for the same model, giving OpenClaw users too small a window; the two are now aligned, with a cross-preset consistency test to prevent drift.
|
||||
- **Volcengine / Doubao / BytePlus website links corrected**: the "visit website" links on these three presets had been mistakenly set to console / signup links, and are restored to clean product homepages.
|
||||
- **Downscale oversized provider icons to 256px**: a batch of bundled icons were far larger than their ~32px on-screen render size; downscaling significantly reduces their size with no code / filename / import changes (e.g. ZetaAPI 940KB→40KB, relaxcode 1.16MB→42KB), and the never-referenced 1.4MB `dds.svg` orphan was removed.
|
||||
|
||||
---
|
||||
|
||||
## Fixed
|
||||
|
||||
### Disable web_search for Native Codex Gateways That Reject It
|
||||
|
||||
Some native `/responses` gateways whose first-party models lack OpenAI's hosted `web_search` tool reject it with "tool type 'web_search' is not supported", and Codex sends the tool by default, producing a hard 400. CC Switch now writes the top-level TOML line `web_search = "disabled"` for those vendors on switch. The scope is a blacklist (default-on): only providers matched by `base_url` host (`xiaomimimo.com`, `longcat.chat`, `minimax.io`, `minimaxi.com`) or by model brand prefix (`mimo`, `longcat`, `minimax`, `qwen3-coder`) are disabled, so relays serving real GPT, Doubao, general Qwen, and any unknown provider keep Codex's default. The `qwen3-coder` prefix only suppresses native `qwen3-coder-plus` (Bailian / DashScope marks built-in tools unsupported for the coder series), while general Qwen sharing the same host stays enabled; matching is on the model axis (stripping any aggregator `vendor/` path segment), so it also catches cases like SiliconFlow fronting a reject vendor's model. A blacklist was chosen over a fuzzy "is this GPT?" whitelist because wrongly keeping `web_search` on fails with a hard 400; an ownership sentinel ensures CC Switch only ever removes a `disabled` value it wrote itself, so existing providers need no re-save and switching back re-enables it. As a side fix, the LongCat-2.0-Preview preset's context window is corrected from 131072 (128K) to the real 1048576 (1M).
|
||||
|
||||
### Strip All Credential-Like Keys from the Shared Claude Common-Config Snippet
|
||||
|
||||
`extract_claude_common_config` previously only redacted `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN`, but Claude providers legitimately carry other credentials (`OPENROUTER_API_KEY`, `GOOGLE_API_KEY`, and possibly OpenAI / Gemini / AWS Bedrock / Vertex secrets), which could leak into the shared snippet and then be injected into other providers. Extraction now pattern-matches and strips any credential-shaped env key (`*_API_KEY` / `*_AUTH_TOKEN` / `*secret*` / `*token*`, etc.), while preserving legitimately shareable plural `*_TOKENS` values like `MAX_OUTPUT_TOKENS`. This also closes the same leak on the manual "Extract" and one-time auto-extract paths.
|
||||
|
||||
### Usage-Script Credentials Persisted Only as Explicit Overrides
|
||||
|
||||
Provider usage scripts store optional `api_key` / `base_url` fields that override the live credentials when querying quota, but they used to silently mirror the provider's own credentials — so copying a provider or editing its main API key / base URL left the usage script pinned to the old endpoint and key, and quota queries kept hitting a stale target. `ProviderService` now normalizes before persisting: if the script's `api_key` or `base_url` matches the provider's resolved usage credentials (or is blank), it is cleared to `None` so queries fall back to the live config; genuinely different overrides are kept (`token_plan` scripts are left alone). The deeplink import path gets matching normalization too, and the front-end invalidates the relevant cache keys on update so the home page re-queries with the corrected config. ([#4654](https://github.com/farion1231/cc-switch/pull/4654))
|
||||
|
||||
### Hermes Config Directory Resolves Correctly on Windows
|
||||
|
||||
CC Switch hardcoded `~/.hermes` as the Hermes config directory, but Hermes itself resolves it via the `HERMES_HOME` environment variable, then a platform default (`%LOCALAPPDATA%\hermes` on Windows). On Windows this meant CC Switch wrote provider configs to a path Hermes never reads, so provider switches had no effect. `get_hermes_dir()` now mirrors Hermes' own resolution order — explicit override, then `HERMES_HOME` (taken verbatim, no `~` expansion), then the platform default — re-honoring the `HERMES_HOME` that #3470 had dropped (Hermes' Windows installer sets it as the first-class mechanism for relocated installs). ([#4680](https://github.com/farion1231/cc-switch/pull/4680), see #3178, #3470)
|
||||
|
||||
### Linux Wayland: Override the AppImage's Forced `GDK_BACKEND=x11`
|
||||
|
||||
The AppImage's GTK launch hook unconditionally exports `GDK_BACKEND=x11` to dodge a historical native-Wayland crash. On newer Wayland + NVIDIA setups, this forced XWayland leaves the WebKitGTK web content unable to receive pointer events (the title bar clicks, the page is dead) and black-screens on resize, and the existing `WEBKIT_DISABLE_*` mitigations don't help because the root cause is the forced window backend, not rendering. `main.rs` now reads an optional `CC_SWITCH_GDK_BACKEND` escape hatch before GTK init (the AppImage's launch hook never touches it): leaving it unset keeps current behavior (zero regression). When you hit the problem above, launch with it set to switch back to native Wayland:
|
||||
|
||||
```bash
|
||||
CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
|
||||
```
|
||||
|
||||
The override is generic — if you're on a tiling Wayland compositor hitting the inverse input problem, set `CC_SWITCH_GDK_BACKEND=x11` instead. ([#4351](https://github.com/farion1231/cc-switch/pull/4351), fixes #4350)
|
||||
|
||||
### "Get API Key" Link Now Shows in Claude Desktop, OpenClaw, and Hermes Forms
|
||||
|
||||
The "Get API Key" link and partner-promotion block below the API key input was only wired for claude / codex / gemini / opencode. Claude Desktop rendered a bare input that never showed it, and OpenClaw / Hermes were blocked by two gaps (the whitelist only listed those four appIds, and category parsing only recognized those four preset-id patterns). Claude Desktop now uses the shared `ApiKeySection`, and both the whitelist and category parsing were extended to claude-desktop / openclaw / hermes; additionally, the Hermes / OpenClaw forms no longer let an "official" category disable the key input (these apps have no OAuth-only official providers — e.g. Hermes' Nous Research is official but still needs a user-supplied key).
|
||||
|
||||
### Deduplicate Windows Codex npm Shims
|
||||
|
||||
On Windows, npm installs a tool as three sibling files — `codex.cmd`, `codex.exe`, and an extensionless Unix shim `codex` — and CC Switch previously listed all three as candidates, so the non-executable extensionless shim was probed as a redundant / failing candidate. It now appends the extensionless path only when there's no runnable `.cmd` / `.exe` sibling adjacent, and path resolution prefers the runnable `.cmd` / `.exe`, anchoring version detection and launch to the actually-runnable Windows shim. ([#4782](https://github.com/farion1231/cc-switch/pull/4782))
|
||||
|
||||
### Scroll Bounds for Long Select Dropdowns
|
||||
|
||||
`SelectContent` previously used `overflow-hidden` with no height cap, so dropdowns with many options (e.g. long model / provider lists) rendered taller than the viewport and clipped their overflow with no way to reach it. It now sets `max-h-[min(24rem,var(--radix-select-content-available-height))]` and `overflow-y-auto`, bounding the content to 24rem or the Radix-computed available height and allowing vertical scrolling. ([#4798](https://github.com/farion1231/cc-switch/pull/4798))
|
||||
|
||||
### Date-Range Picker Calendar Stays On-Screen in Narrow Popovers
|
||||
|
||||
The custom date-range picker previously switched to its two-column layout (date fields | calendar) based on the **viewport** width (Tailwind's `sm:` 640px breakpoint), but the popover is clamped to `100vw - 2rem` and anchored to its trigger, so its real available width is narrower than the viewport. On narrow windows the two-column layout could activate while the popover only had room for one column, pushing the calendar column off the right edge where it was clipped (the month header and 4 of 7 weekday columns cut off and unreachable). The layout now keys off the popover's own inline size via a CSS container query, so it collapses to one column exactly when the popover itself is narrow, keeping the calendar fully visible at any window width. ([#4860](https://github.com/farion1231/cc-switch/pull/4860))
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
### `CC_SWITCH_GDK_BACKEND` Escape Hatch Documented
|
||||
|
||||
Added an FAQ entry for the optional `CC_SWITCH_GDK_BACKEND` environment variable across all four README languages and the zh / en / ja user-manual troubleshooting pages, explaining how Wayland + NVIDIA users can switch back to native Wayland when the web content goes "click-dead + black screen on resize", and how tiling-Wayland users can set it to `x11` for the inverse input problem.
|
||||
|
||||
### Overseas Kimi READMEs Point to platform.kimi.ai
|
||||
|
||||
The Kimi K2.7 Code partner section in the English, German, and Japanese READMEs now points its banner and inline calls to action at `https://platform.kimi.ai?aff=cc-switch` (keeping the referral tag), and all four READMEs gained a line promoting the Kimi For Coding subscription linked to `https://www.kimi.com/code/?aff=cc-switch`.
|
||||
|
||||
---
|
||||
|
||||
## Upgrade Notes
|
||||
|
||||
### Existing Native Codex Providers Need a One-Time Re-Save
|
||||
|
||||
This release reworks model-catalog generation for native Responses direct-connect. If you previously configured a Codex provider using native Responses (`openai_responses`), **re-pick the preset or open the provider and save it once** to generate the new `~/.codex/cc-switch-model-catalog.json` — that's what lets the Codex desktop app show the custom models and makes the tools work. This requires no database migration and does not affect providers on the `openai_chat` format.
|
||||
|
||||
### web_search Blacklist Is Default Behavior
|
||||
|
||||
For known-to-reject-`web_search` domestic native gateways (Xiaomi MiMo, Meituan LongCat, MiniMax, Qwen3-Coder), this release automatically writes `web_search = "disabled"` on switch. Relays serving real GPT, Doubao, general Qwen, and unknown providers are unaffected and keep Codex's default. The switch is managed by CC Switch with an ownership sentinel, so switching back to a provider not on the blacklist restores it automatically, with no manual intervention.
|
||||
|
||||
### Default Sonnet Tier Change
|
||||
|
||||
Claude-family providers newly created from a preset now have their default Sonnet tier pointing to `claude-sonnet-5`. Existing configured providers are unaffected and keep their configuration as-is; to switch to Sonnet 5, re-pick the preset and save.
|
||||
|
||||
---
|
||||
|
||||
## Risk Notice
|
||||
|
||||
This release continues the risk notices from previous versions for reverse-proxy-style features.
|
||||
|
||||
**Codex OAuth reverse proxy**: using a ChatGPT subscription's Codex OAuth through a reverse proxy may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details.
|
||||
|
||||
**Codex third-party provider Chat routing**: when CC Switch local proxy converts and forwards Codex requests to third-party providers, each provider may have different requirements for billing, compliance, and data retention. Read the target provider's terms before use.
|
||||
|
||||
**Claude Desktop third-party provider proxy switching**: when CC Switch's built-in proxy gateway forwards Claude Desktop requests to third-party providers, you must also follow the target provider's billing, compliance, and data-retention terms.
|
||||
|
||||
By enabling these features, users accept the related risks. CC Switch is not responsible for account restrictions, warnings, or service suspensions caused by using these features.
|
||||
|
||||
---
|
||||
|
||||
## Thanks
|
||||
|
||||
Thanks to the following contributors for the features and fixes in v3.16.5:
|
||||
|
||||
- [#4776](https://github.com/farion1231/cc-switch/pull/4776): add the categorized session view and group management, thanks @alkaid616.
|
||||
- [#4829](https://github.com/farion1231/cc-switch/pull/4829): rename "Write Common Config" to "Apply Common Config", thanks @arichyx.
|
||||
- [#4654](https://github.com/farion1231/cc-switch/pull/4654): persist usage-script credentials only as explicit overrides, thanks @yyhhyyyyyy.
|
||||
- [#4680](https://github.com/farion1231/cc-switch/pull/4680): fix Hermes provider config not taking effect on Windows, thanks @thisTom.
|
||||
- [#4782](https://github.com/farion1231/cc-switch/pull/4782): deduplicate Windows Codex npm shims, thanks @justjavac.
|
||||
- [#4798](https://github.com/farion1231/cc-switch/pull/4798): fix long dropdown lists not being scrollable, thanks @xwil1.
|
||||
- [#4351](https://github.com/farion1231/cc-switch/pull/4351): allow overriding the AppImage's forced `GDK_BACKEND=x11` via `CC_SWITCH_GDK_BACKEND`, thanks @BoneLiu.
|
||||
- [#4860](https://github.com/farion1231/cc-switch/pull/4860): keep the date-range picker calendar on-screen in narrow popovers, thanks @SaladDay.
|
||||
|
||||
Thanks also to everyone who reported native Codex direct-connect, common config, credential reuse, and platform compatibility issues after the v3.16.4 release. Many of these patches came directly from real-world reproduction clues.
|
||||
|
||||
---
|
||||
|
||||
## Download & Install
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) and download the build for your system.
|
||||
|
||||
### System Requirements
|
||||
|
||||
| System | Minimum Version | Architecture |
|
||||
| ------- | ------------------------ | ----------------------------------- |
|
||||
| Windows | Windows 10 and later | x64 / ARM64 |
|
||||
| macOS | macOS 12 (Monterey)+ | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | See table below | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| File | Description |
|
||||
| ---------------------------------------- | ------------------------------------------------ |
|
||||
| `CC-Switch-v3.16.5-Windows.msi` | **Recommended** - MSI installer with auto-update |
|
||||
| `CC-Switch-v3.16.5-Windows-Portable.zip` | Portable build, unzip and run |
|
||||
|
||||
Windows ARM64 devices should pick the artifact whose file name carries the `arm64` tag.
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| -------------------------------- | ----------------------------------------------------- |
|
||||
| `CC-Switch-v3.16.5-macOS.dmg` | **Recommended** - DMG installer, drag to Applications |
|
||||
| `CC-Switch-v3.16.5-macOS.zip` | Unzip and drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.16.5-macOS.tar.gz` | For Homebrew install and auto-update |
|
||||
|
||||
Homebrew install:
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Upgrade:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Linux assets are available for both **x86_64** and **ARM64** (`aarch64`). Choose the file whose architecture tag matches your machine's `uname -m` output:
|
||||
|
||||
- `CC-Switch-v3.16.5-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- `CC-Switch-v3.16.5-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| Distribution | Recommended Format | Install Command |
|
||||
| --------------------------------------- | ------------------ | --------------------------------------------------------------------- |
|
||||
| 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` | Make executable and run directly, or use AUR |
|
||||
| Other distributions / unsure | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
@@ -0,0 +1,278 @@
|
||||
# CC Switch v3.16.5
|
||||
|
||||
> 本リリースの目玉は、**ネイティブ Responses 形式の国産モデルプロバイダーをきちんと適合させたこと**です——ネイティブ Responses endpoint を備えるプロバイダー（小米 MiMo、火山 Doubao、Qwen3-Coder、美団 LongCat、MiniMax）向けに Codex モデルカタログを生成し、Codex デスクトップがこれらのモデルを表示でき、内蔵ツールも正しく動くようにしました。また、`web_search` を拒否する一部の国産ゲートウェイに対しては、そのツールを自動で無効化し、リクエストがハード拒否されないようにします。ほかに 2 つの重要な改善があります: プロバイダーを切り替えるとき、アプリ内で追加したプラグインや環境変数などが**自動的に共通設定へ書き戻され、次のプロバイダーへ引き継がれます**。そして Linux（Wayland + NVIDIA）で「タイトルバーは押せるのにページが反応しない、リサイズで黒画面」になる問題も、環境変数のスイッチで自力回避できるようになりました。本リリースはさらに Claude Sonnet 5 の価格と既定階層の引き上げ、2 段階グルーピングのセッションビュー、そして一連の認証情報の安全性とプラットフォーム互換性の修正を届けます。
|
||||
|
||||
**[English →](v3.16.5-en.md) | [中文版 →](v3.16.5-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## 利用ガイド
|
||||
|
||||
本リリースの新機能は、主に Codex プロバイダーフォーム、セッションパネル、使用量 / 共通設定に収まっています。以下のドキュメントとあわせてご覧ください：
|
||||
|
||||
- **[Codex デスクトップでカスタムモデルが見えない？](../guides/codex-desktop-custom-model-visibility-ja.md)**: 本リリースは**ネイティブ直結時のモデルカタログ生成**を作り直しました——Codex プロバイダーがネイティブ Responses（`openai_responses`）で直結するとき、CC Switch が `~/.codex/cc-switch-model-catalog.json` を生成し、Codex デスクトップが設定済みのカスタムモデルを表示でき、ツールも動くようにします。以前にネイティブ Codex プロバイダーを設定していた場合は、新しいカタログを生成するために**一度保存し直して**ください（下記「アップグレード時の注意」を参照）。
|
||||
- **[使用量統計](../user-manual/ja/4-proxy/4.4-usage.md)**: 使用量ダッシュボードのデータソースと集計の仕組みを確認できます。本リリースでは Claude Sonnet 5 の価格を追加し、使用量スクリプトの認証情報が「明示的なオーバーライド」として永続化される問題を修正しました。
|
||||
- **[設定](../user-manual/ja/1-getting-started/1.5-settings.md)**: Codex の上流形式セレクタとローカルルーティングのトグル、Claude の共通設定（「共通設定を適用」に改名され、切り替え時に自動同期）は、いずれもプロバイダーフォームの高度なオプションにあります。
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## 唯一の公式チャネル（必ずお読みください）
|
||||
>
|
||||
> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。本ソフトウェアは下記の公式チャネルからのみ入手してください：
|
||||
>
|
||||
> | チャネル | 唯一の公式 |
|
||||
> | ------------ | ------------------------------------------------------------------------------ |
|
||||
> | 公式サイト | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | 作者 | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は直ちに操作を中止し、GitHub Issues からご報告ください。
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.16.5 は v3.16.4 に続くメンテナンスアップデートで、その中心は**国産モデルプロバイダーの Codex ネイティブ直結をエンドツーエンドで通すこと**です。v3.16.4 ですでに千問 / DashScope 百炼、小米 MiMo、火山 Doubao、美団 LongCat、MiniMax をネイティブ Responses endpoint へ切り替えていましたが、本リリースはさらに Codex が必要とする**モデルカタログ**（`~/.codex/cc-switch-model-catalog.json`）を生成し、Codex デスクトップがこれらのカスタムモデルを本当に表示でき、内蔵ツールも呼び出せるようにし、モデルマッピングを「ローカルルーティング」トグルから完全に分離しました。第一方モデルが OpenAI 内蔵の `web_search` に対応しない一部の国産ゲートウェイ（MiMo、LongCat、MiniMax、Qwen3-Coder）については、本リリースがそのツールを自動で無効化し、Codex の既定でそれが付いてハード 400 を招くことを避けます。
|
||||
|
||||
日々の使い勝手の面では、本リリースは Claude の**共通設定をプロバイダー切り替え時に自動で同期・引き継ぐ**ようにしました——アプリ内で直接追加したプラグイン、環境変数、テーマなどが、まず共通設定へ書き戻され、次のプロバイダーへ渡されるため、切り替え時に失われません。Linux（Wayland + NVIDIA）でクリック無反応 / 黒画面になるユーザー向けに、自力回避できる環境変数を追加し、Claude Sonnet 5 の価格を補って既定の Sonnet 階層をそれへ引き上げ、「プロバイダー → プロジェクトディレクトリ」の 2 段階グルーピングのセッションビューを届け、一連の認証情報の安全性（共通設定スニペットからすべての秘密情報を除去、使用量スクリプトの認証情報は明示的なオーバーライドとしてのみ保持）、プラットフォーム互換性（Hermes の Windows 設定ディレクトリ、Windows の Codex npm シム）、UI（長いドロップダウンのスクロール、狭いウィンドウの日付範囲セレクタ）の問題を修正しました。あわせて、いくつかのプロバイダープリセットも追加し、そのまますぐ選べます。
|
||||
|
||||
**リリース日**: 2026-07-01
|
||||
|
||||
**Stats**: 36 commits | 93 files changed | +5,678 / -2,804 lines
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **国産モデルプロバイダーの Codex ネイティブ直結が本当に使える**: 小米 MiMo、火山 Doubao、Qwen3-Coder、美団 LongCat、MiniMax などの国産プロバイダー向けに Codex モデルカタログ（`~/.codex/cc-switch-model-catalog.json`）を生成し、Codex デスクトップがこれらのモデルを表示でき、内蔵ツールが動くようにします。あわせて `web_search` を拒否する国産ゲートウェイ（MiMo、LongCat、MiniMax、Qwen3-Coder）に対してはそのツールを自動で無効化し、ハード 400 を避けます。**既存のネイティブプロバイダーは、新しいカタログ生成のために一度保存し直す必要があります。**
|
||||
- **共通設定を切り替え時に自動同期・引き継ぎ**: 共通設定を有効にした Claude プロバイダーから切り替えるとき、アプリ内で追加したプラグイン、環境変数、テーマ、hooks が、まず共通設定へ書き戻され、次のプロバイダーへ渡されます——切り替え時に上書きで失われることがなくなりました。
|
||||
- **Linux Wayland のクリック無反応 / 黒画面の回避スイッチ**: Wayland + NVIDIA で「タイトルバーは押せるのにページが反応しない、リサイズで黒画面」に遭遇したら、`CC_SWITCH_GDK_BACKEND=wayland` で起動すればネイティブ Wayland へ切り替えられます（タイリング系コンポジタで逆の問題に遭遇する場合は `x11` に設定）。
|
||||
- **Claude Sonnet 5**: Sonnet 5 の価格を追加し、各プリセットの既定 Sonnet 階層を `claude-sonnet-5` へ引き上げます。
|
||||
- **セッションの分類ビューとグルーピング**: セッションパネルに「プロバイダー → プロジェクトディレクトリ」の 2 段階グルーピングビューを新設し、グループヘッダーの 3 状態チェックボックスでワンクリックの一括選択に対応します。
|
||||
- **新しいプロバイダープリセット**: 七牛云、FennoAI、ZetaAPI、TeamoRouter、NekoCode、Code0.ai、Amux などのプロバイダープリセットを、管理対象アプリ全体に追加し、そのまますぐ選べます。
|
||||
|
||||
---
|
||||
|
||||
## 追加機能
|
||||
|
||||
### 国産モデルプロバイダーの Codex ネイティブ直結（モデルカタログの生成）
|
||||
|
||||
本リリースは、国産プロバイダーの Codex ネイティブ直結を通しました。v3.16.4 で小米 MiMo、火山 Doubao、Qwen3-Coder、美団 LongCat、MiniMax をネイティブ Responses（`apiFormat: "openai_responses"`）へ切り替えたのに続き、本リリースは当時の「ネイティブ直結ならモデルカタログを削除する」やり方を覆しました: これらのプロバイダーがローカルプロキシを経由せず直結するとき、CC Switch が `~/.codex/cc-switch-model-catalog.json` を生成し、Codex デスクトップがこれらのカスタムモデルを本当に表示でき、内蔵ツールも動くようにします——MiMo のようなネイティブゲートウェイが拒否する freeform `apply_patch`（`type=custom`）ツールを発生させません（編集は `shell_command` へフォールバック）。カタログ生成は `apiFormat` で判定され、「ローカルルーティング」トグルから分離されているため、ネイティブプロバイダーはローカルルートマッピングを有効にしなくてもカタログを永続化します。一方 `openai_chat` 形式は、既存の Responses↔Chat プロキシ変換をそのまま保ちます。Codex のパーサーは各項目に `base_instructions` を要求するため、ネイティブテンプレートは中立の既定値を携え、各ベンダーの公式文面がそれを上書きします（MiMo、MiniMax）。**既存のネイティブプロバイダーは、有効なカタログを生成するために一度保存し直す必要があります**（データベース移行は不要）。
|
||||
|
||||
あわせて、第一方モデルが OpenAI 内蔵の `web_search` ツールに対応しない一部の国産ゲートウェイ（MiMo、LongCat、MiniMax、Qwen3-Coder）については、本リリースが切り替え時にそのツールを自動で無効化し、Codex の既定でそれが付いてハード 400 で拒否されるのを避けます（下記「修正」を参照）。
|
||||
|
||||
### セッションの分類ビューとグルーピング
|
||||
|
||||
セッション管理パネルに、既存のフラットなリストに加えてグルーピングビューを新設し、ツールバーの List / ListTree セレクタで切り替え、ビューモードと展開状態を `localStorage` に永続化します。グルーピングは「プロバイダー → プロジェクトディレクトリ」の 2 段階階層を構築します: プロジェクトディレクトリ名でグループ化し、プロジェクトディレクトリを持たないセッションは「不明なディレクトリ」バケットに入ります。両方の段階が折りたたみ可能な区画で、「すべて折りたたむ」ボタンを備えます。バッチモードでは、各グループヘッダーに 3 状態チェックボックスが現れ、そのグループ内の選択可能なセッションをすべて一括で選択 / 解除でき、選択数 / 選択可能数のバッジも表示します。4 言語（zh / en / ja / zh-TW）の文言は同期済みです。この変更は完全にフロントエンドで、バックエンドのコマンドやデータアクセス層には手を加えていません。（[#4776](https://github.com/farion1231/cc-switch/pull/4776)）
|
||||
|
||||
### Claude Sonnet 5 のモデル価格
|
||||
|
||||
`schema.rs` に `claude-sonnet-5` の価格行を Anthropic の定価で追加しました——入力 / 出力が 100 万 token あたり \$3 / \$15、キャッシュ読み書きが \$0.30 / \$3.75 で、Sonnet 4.6 と同一です。導入期の \$2 / \$10 プロモーション（2026-08-31 まで有効）は意図的にシードせず、記帳が一時的な割引ではなく定常の定価を反映するようにしています。この行はアプリの次回起動時に `ensure_model_pricing_seeded` 経由で適用され、`SCHEMA_VERSION` の引き上げは不要です。
|
||||
|
||||
### 新しいプロバイダープリセット
|
||||
|
||||
本リリースは一連のプロバイダープリセットを追加しました。選択して自分の API key を入力すればすぐ使えます：
|
||||
|
||||
- **七牛云（Qiniu）**: 管理対象の 7 アプリすべて（Gemini を含む）をカバーし、ネイティブ Claude / GPT / Gemini を中継します。
|
||||
- **FennoAI / ZetaAPI / TeamoRouter / NekoCode**: それぞれ 6 アプリ（Claude、Claude Desktop、Codex、OpenCode、OpenClaw、Hermes）をカバーします。
|
||||
- **Code0.ai**: 7 アプリすべて（Gemini を含む）をカバーします。
|
||||
- **Amux**: 6 アプリをカバーします。
|
||||
|
||||
各プリセットの endpoint と既定モデルは対応するアプリに合わせて設定済みです——Claude 系は Anthropic 互換ホストへ直結、Codex はネイティブ Responses、その他は OpenAI 互換の `/v1` を使います。
|
||||
|
||||
---
|
||||
|
||||
## 変更
|
||||
|
||||
### プロバイダー切り替え時に共通設定を自動同期・引き継ぎ
|
||||
|
||||
これは本リリースのとても実用的な変更です: 共通設定を有効にした Claude プロバイダーから切り替えるとき、サービスはまずその live の `settings.json` から**共有可能な部分を再抽出して共通設定を更新し**、次のプロバイダーへ渡します。以前のような一方向の書き込みだけではありません。これにより、実行中のアプリで直接追加したプラグイン（`enabledPlugins`）、hooks、環境変数（`env`）、テーマ（`theme`）などの共有設定が、切り替え時に静かに失われることなく、自動的に次のプロバイダーへ引き継がれます。削除も同期されます（削除されたキーは再注入されません）。この同期は共通設定を有効にした Claude プロバイダーに厳密に限定され、明示的にクリアされた場合はスキップされ、すべての失敗は非致命的（警告のみ）で、切り替えを妨げることは決してありません。
|
||||
|
||||
### Codex のモデルマッピングと「ローカルルーティング」トグルの分離
|
||||
|
||||
Codex プロバイダーフォームが Claude Code に揃いました——モデルマッピングカタログがルーティングテイクオーバーから独立しました。ネイティブ Responses プロバイダー（MiMo、Doubao、MiniMax）はプロキシなし直結のためにそれを必要とする一方、Chat プロバイダーはいずれにせよプロキシを経由するためです。「ローカルルーティングが必要」トグルは削除されました（バックエンドのフィールドを持たず、カタログ / 推論の永続化を制御していただけで、これはマッピングが記入されているかどうかと等価です）。モデルマッピングは非公式プロバイダーに対して常に表示され、空でなければ永続化されます。一方、推論能力の表示 / 永続化は Chat 形式で制御されるようになりました。4 言語（zh / en / ja / zh-TW）の文言もあわせて書き直しました。副次的な修正として、`useCodexConfigState` が保存済みプロバイダーを読み込むときに `supportsParallelToolCalls` / `inputModalities` / `baseInstructions` を落とす問題（編集時に並列ツール、画像入力、公式の base instructions を静かに失っていた）も修正しました。
|
||||
|
||||
### 既定の Sonnet 階層を Claude Sonnet 5 へ引き上げ
|
||||
|
||||
各プロバイダープリセットの既定 Sonnet 階層を `claude-sonnet-4-6` から `claude-sonnet-5` へ引き上げました（claude / claude-desktop / hermes / openclaw / opencode のプリセットとユニバーサルの `NEWAPI_DEFAULT_MODELS` をカバー）。`ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_OPUS_MODEL` などのキーとそのプレフィックス付き変種が対象です。Claude Desktop の既定ルートの sonnet `route_id` もあわせて `claude-sonnet-5` へ移行しました。非 Anthropic の pin（gpt / gemini / glm / sonnet-4-5）はそのままです。
|
||||
|
||||
### Doubao の日付付き model id と価格の正規化
|
||||
|
||||
Doubao（DouBaoSeed）プリセットの model id を日付付きの `doubao-seed-2-1-pro-260628` へ切り替えました（各アプリをカバー）。火山方舟が素の `doubao-seed-2-1-pro` を 404 で拒否し、完全な日付付き id のみを受け付けるためです。実際の使用量が日付サフィックスを伴うようになったため、`strip_model_date_suffix` を火山の 6 桁 YYMMDD 形式も剥がせるように拡張し（`-123456` のような非日付のバージョンサフィックスを誤って食わないよう、月 01-12・日 01-31 を検証）、価格表の素の名前のシード行にマッチするよう正規化して、Doubao モデルが \$0 コストで表示される問題を修正しました。
|
||||
|
||||
###「共通設定を書き込む」を「共通設定を適用」へ改名
|
||||
|
||||
元のラベル「共通設定を書き込む」はデータの流れの方向が曖昧でした（「現在の設定を共通設定へ書き込む」と読めた）。実際の挙動は逆で——保存済みの共通設定スニペットをこのプロバイダーの設定へマージするものです。チェックボックスを 4 言語（zh / en / ja / zh-TW）で「共通設定を適用」へ改名し、すべてのヒント / ガイド / 説明の参照を含め、日本語ユーザーマニュアルと `README_JA.md` もあわせて同期しました。（[#4829](https://github.com/farion1231/cc-switch/pull/4829)）
|
||||
|
||||
### その他のプリセットと素材の調整
|
||||
|
||||
- **OpenClaw の Doubao コンテキストを 262144 へ整合**: OpenClaw の DouBaoSeed プリセットは以前 128000 をハードコードしていましたが、Codex 側は同モデルで 262144 を使っており、OpenClaw ユーザーのウィンドウが小さすぎました。両者を整合させ、再びずれないようクロスプリセットの一貫性テストを追加しました。
|
||||
- **火山 / Doubao / BytePlus の公式サイトリンクを訂正**: これら 3 つのプリセットの「公式サイトを訪問」リンクが、誤ってコンソール / 登録リンクに設定されていたため、クリーンな製品トップページへ戻しました。
|
||||
- **過大なプロバイダーアイコンを 256px へダウンスケール**: 一連のバンドルアイコンが、実際の描画サイズ（~32px）よりはるかに大きかったため、ダウンスケールで大幅に容量を削減しました（コード / ファイル名 / インポートの変更なし。例: ZetaAPI 940KB→40KB、relaxcode 1.16MB→42KB）。また、一度も参照されていない 1.4MB の `dds.svg` 孤立ファイルを削除しました。
|
||||
|
||||
---
|
||||
|
||||
## 修正
|
||||
|
||||
### `web_search` を拒否するネイティブ Codex ゲートウェイでは無効化
|
||||
|
||||
一部のネイティブ `/responses` ゲートウェイは、第一方モデルが OpenAI のホスト型 `web_search` ツールを備えないため、それを「tool type 'web_search' is not supported」で拒否します。そして Codex は既定でそのツールを送るため、ハード 400 を招きます。CC Switch は現在、これらのベンダーに対して切り替え時にトップレベルの TOML 行 `web_search = "disabled"` を書き込みます。スコープはブラックリスト（既定オン）で、`base_url` ホスト（`xiaomimimo.com`、`longcat.chat`、`minimax.io`、`minimaxi.com`）または model のブランドプレフィックス（`mimo`、`longcat`、`minimax`、`qwen3-coder`）に一致するプロバイダーだけが無効化されるため、本物の GPT、Doubao、一般の Qwen、そして未知のプロバイダーはいずれも Codex の既定を保ちます。`qwen3-coder` プレフィックスはネイティブの `qwen3-coder-plus` だけを抑制し（百炼 / DashScope は coder 系で内蔵ツールを非対応と示します）、同じホストを共有する一般の Qwen は有効のままです。マッチングは model 軸で行われ（アグリゲーターの `vendor/` パスセグメントを剥がす）、SiliconFlow が拒否ベンダーのモデルを前面に立てるようなケースも捕捉します。曖昧な「これは GPT か？」というホワイトリストではなくブラックリストを選んだのは、`web_search` を誤ってオンのままにするとハード 400 で失敗するためです。所有権のセンチネルにより、CC Switch は自らが書いた `disabled` 値だけを削除するため、既存プロバイダーは保存し直す必要がなく、切り替えて戻せば再び有効になります。副次的な修正として、LongCat-2.0-Preview プリセットのコンテキストウィンドウを 131072（128K）から本来の 1048576（1M）へ訂正しました。
|
||||
|
||||
### 共有される Claude 共通設定スニペットからすべての認証情報系キーを除去
|
||||
|
||||
`extract_claude_common_config` は以前 `ANTHROPIC_API_KEY` と `ANTHROPIC_AUTH_TOKEN` だけをマスクしていましたが、Claude プロバイダーは正当に他の認証情報（`OPENROUTER_API_KEY`、`GOOGLE_API_KEY`、場合によっては OpenAI / Gemini / AWS Bedrock / Vertex の秘密情報）を携えることがあり、それらが共有スニペットへ漏れ、他のプロバイダーへ注入されるおそれがありました。抽出は現在、認証情報の形をした環境変数キー（`*_API_KEY` / `*_AUTH_TOKEN` / `*secret*` / `*token*` など）をパターンマッチで除去し、`MAX_OUTPUT_TOKENS` のような正当に共有可能な複数形 `*_TOKENS` の値は保持します。手動の「抽出」と一度きりの自動抽出の経路にあった同じ漏れも、あわせて塞ぎました。
|
||||
|
||||
### 使用量スクリプトの認証情報は明示的なオーバーライドとしてのみ永続化
|
||||
|
||||
プロバイダーの使用量スクリプトは、クォータ照会時に live の認証情報を上書きする任意の `api_key` / `base_url` フィールドを保持しますが、これらが以前はプロバイダー自身の認証情報を静かにミラーしていました——そのため、プロバイダーを複製したり、メインの API key / base URL を編集したりすると、使用量スクリプトが古い endpoint と key に固定されたまま残り、クォータ照会が古い対象を叩き続けていました。`ProviderService` は現在、永続化の前に正規化します: スクリプトの `api_key` または `base_url` がプロバイダーの解決済み使用量認証情報と一致する（または空の）場合は `None` にクリアして、照会が live 設定へフォールバックするようにします。本当に異なるオーバーライドは保持されます（`token_plan` スクリプトはそのまま）。deeplink インポート経路にも同様の正規化を加え、フロントエンドは更新時に関連するキャッシュキーを無効化して、ホームページが訂正済みの設定で再照会するようにします。（[#4654](https://github.com/farion1231/cc-switch/pull/4654)）
|
||||
|
||||
### Hermes 設定ディレクトリが Windows で正しく解決されるように
|
||||
|
||||
CC Switch は Hermes の設定ディレクトリとして `~/.hermes` をハードコードしていましたが、Hermes 自身は `HERMES_HOME` 環境変数、次にプラットフォーム既定（Windows では `%LOCALAPPDATA%\hermes`）で解決します。Windows ではこれにより、CC Switch がプロバイダー設定を Hermes が決して読まないパスへ書いていたため、プロバイダーの切り替えが効きませんでした。`get_hermes_dir()` は現在、Hermes 自身の解決順序——明示的なオーバーライド、次に `HERMES_HOME`（そのまま使用、`~` 展開なし）、次にプラットフォーム既定——をミラーし、#3470 が落としていた `HERMES_HOME` を再び尊重します（Hermes の Windows インストーラーは、再配置されたインストールの第一級の仕組みとしてそれを設定します）。（[#4680](https://github.com/farion1231/cc-switch/pull/4680)、#3178、#3470 を参照）
|
||||
|
||||
### Linux Wayland: AppImage が強制する `GDK_BACKEND=x11` を上書き可能に
|
||||
|
||||
AppImage の GTK 起動フックは、歴史的なネイティブ Wayland のクラッシュを避けるために `GDK_BACKEND=x11` を無条件でエクスポートします。新しめの Wayland + NVIDIA 環境では、この強制された XWayland により WebKitGTK のウェブコンテンツがポインタイベントを受け取れなくなり（タイトルバーは押せてもページは反応しない）、リサイズで黒画面になります。既存の `WEBKIT_DISABLE_*` の緩和策は効きません。根本原因が描画ではなく、強制されたウィンドウバックエンドだからです。`main.rs` は現在、GTK の初期化前に任意の `CC_SWITCH_GDK_BACKEND` 回避スイッチを読みます（AppImage の起動フックはそれに触れません）: 未設定なら現状のまま（回帰ゼロ）。上記の問題に遭遇したら、これを設定してネイティブ Wayland へ切り替えて起動できます:
|
||||
|
||||
```bash
|
||||
CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
|
||||
```
|
||||
|
||||
この上書きは汎用です——タイリング系 Wayland コンポジタで逆の入力問題に遭遇する場合は、代わりに `CC_SWITCH_GDK_BACKEND=x11` に設定してください。（[#4351](https://github.com/farion1231/cc-switch/pull/4351)、#4350 を修正）
|
||||
|
||||
###「API Key を取得」リンクが Claude Desktop / OpenClaw / Hermes フォームでも表示されるように
|
||||
|
||||
API key 入力欄の下の「API Key を取得」リンクとパートナー宣伝ブロックは、以前 claude / codex / gemini / opencode にしか配線されていませんでした。Claude Desktop はそれを表示しない素の入力欄を描画し、OpenClaw / Hermes は 2 つの欠落（ホワイトリストがその 4 つの appId しか列挙しておらず、カテゴリ解析もその 4 つのプリセット id パターンしか認識しなかった）にブロックされていました。Claude Desktop は現在、共有の `ApiKeySection` を使い、ホワイトリストとカテゴリ解析の両方を claude-desktop / openclaw / hermes へ拡張しました。さらに、Hermes / OpenClaw のフォームは「公式」カテゴリで key 入力欄を無効化しなくなりました（これらのアプリには OAuth 専用の公式プロバイダーが存在しません——例えば Hermes の Nous Research は公式ですが、それでもユーザー入力の key が必要です）。
|
||||
|
||||
### Windows の Codex npm シムの重複排除
|
||||
|
||||
Windows では、npm がツールを 3 つの兄弟ファイル——`codex.cmd`、`codex.exe`、拡張子なしの Unix シム `codex`——としてインストールし、CC Switch は以前この 3 つすべてを候補に列挙していたため、実行できない拡張子なしシムが冗長 / 失敗する候補としてプローブされていました。現在は、隣接する実行可能な `.cmd` / `.exe` の兄弟が見つからない場合にのみ拡張子なしパスを追加し、パス解決も実行可能な `.cmd` / `.exe` を優先して、バージョン検出と起動を実際に実行可能な Windows シムに固定します。（[#4782](https://github.com/farion1231/cc-switch/pull/4782)）
|
||||
|
||||
### 長い Select ドロップダウンのスクロール境界
|
||||
|
||||
`SelectContent` は以前、高さの上限なしで `overflow-hidden` を使っていたため、選択肢の多いドロップダウン（長いモデル / プロバイダーのリストなど）がビューポートより高く描画され、あふれた項目が切り取られて届かなくなっていました。現在は `max-h-[min(24rem,var(--radix-select-content-available-height))]` と `overflow-y-auto` を設定し、内容を 24rem または Radix が計算した利用可能高さに収め、縦方向のスクロールを許可します。（[#4798](https://github.com/farion1231/cc-switch/pull/4798)）
|
||||
|
||||
### 日付範囲セレクタのカレンダーが狭いポップオーバーでも画面内に収まるように
|
||||
|
||||
カスタム日付範囲セレクタは以前、2 列レイアウト（日付フィールド | カレンダー）への切り替えを**ビューポート**幅（Tailwind の `sm:` 640px ブレークポイント）で判定していましたが、ポップオーバーは `100vw - 2rem` に制限され、トリガーにアンカーされているため、実際に使える幅はビューポートより狭くなります。狭いウィンドウでは、ポップオーバーに 1 列分しか収まらないのに 2 列レイアウトが有効化されることがあり、カレンダー列が右端の外へ押し出されて切り取られていました（月ヘッダーと 7 列中 4 列の曜日が切れて届かない）。レイアウトは現在、CSS コンテナクエリでポップオーバー自身のインラインサイズに基づいて切り替わるため、ポップオーバー自体が狭いときにちょうど 1 列へ折りたたまれ、どのウィンドウ幅でもカレンダーが完全に見えるようになりました。（[#4860](https://github.com/farion1231/cc-switch/pull/4860)）
|
||||
|
||||
---
|
||||
|
||||
## ドキュメント
|
||||
|
||||
### `CC_SWITCH_GDK_BACKEND` 回避スイッチのドキュメント化
|
||||
|
||||
任意の `CC_SWITCH_GDK_BACKEND` 環境変数について、4 言語すべての README と zh / en / ja のユーザーマニュアルのトラブルシューティングページに FAQ 項目を追加し、Wayland + NVIDIA ユーザーがウェブコンテンツの「クリック無反応 + リサイズで黒画面」時にネイティブ Wayland へ切り替える方法、そしてタイリング系 Wayland ユーザーが逆の入力問題で `x11` に設定する方法を解説しました。
|
||||
|
||||
### 海外向け Kimi README が platform.kimi.ai を指すように
|
||||
|
||||
英語・ドイツ語・日本語の README の Kimi K2.7 Code パートナー段落で、バナーとインラインの行動喚起を `https://platform.kimi.ai?aff=cc-switch` へ向け（紹介タグは維持）、4 言語すべての README に `https://www.kimi.com/code/?aff=cc-switch` へリンクした Kimi For Coding サブスクリプションの宣伝行を追加しました。
|
||||
|
||||
---
|
||||
|
||||
## アップグレード時の注意
|
||||
|
||||
### 既存のネイティブ Codex プロバイダーは一度保存し直しが必要
|
||||
|
||||
本リリースは、ネイティブ Responses 直結のモデルカタログ生成を作り直しました。以前にネイティブ Responses（`openai_responses`）を使う Codex プロバイダーを設定していた場合は、新しい `~/.codex/cc-switch-model-catalog.json` を生成するために、**プリセットから選び直すか、プロバイダーを開いて一度保存し直して**ください——それが、Codex デスクトップにカスタムモデルを表示させ、ツールを動かすための鍵です。これはデータベース移行を必要とせず、`openai_chat` 形式のプロバイダーには影響しません。
|
||||
|
||||
### `web_search` ブラックリストは既定の挙動
|
||||
|
||||
`web_search` を拒否することが分かっている国産ネイティブゲートウェイ（小米 MiMo、美団 LongCat、MiniMax、Qwen3-Coder）に対しては、本リリースが切り替え時に自動で `web_search = "disabled"` を書き込みます。本物の GPT、Doubao、一般の Qwen、そして未知のプロバイダーは影響を受けず、Codex の既定を保ちます。このスイッチは CC Switch が所有権のセンチネルで管理するため、ブラックリストにないプロバイダーへ切り替えて戻せば自動的に復元され、手動の介入は不要です。
|
||||
|
||||
### 既定の Sonnet 階層の変化
|
||||
|
||||
プリセットから新規作成した Claude 系プロバイダーは、既定の Sonnet 階層が `claude-sonnet-5` を指すようになりました。設定済みの既存プロバイダーは影響を受けず、設定はそのまま保たれます。Sonnet 5 へ切り替えたい場合は、プリセットから選び直して保存してください。
|
||||
|
||||
---
|
||||
|
||||
## リスク通知
|
||||
|
||||
本リリースは、リバースプロキシ系機能に関する以前のリスク通知を引き続き適用します。
|
||||
|
||||
**Codex OAuth リバースプロキシ**: ChatGPT サブスクリプションの Codex OAuth をリバースプロキシ経由で使用すると、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 release notes](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
|
||||
|
||||
**Codex サードパーティプロバイダー Chat ルーティング**: CC Switch ローカルプロキシで Codex リクエストを変換し、サードパーティプロバイダーへ転送する場合、課金・コンプライアンス・データ保持に関する制約はプロバイダーごとに異なります。利用前に対象プロバイダーの利用規約を確認してください。
|
||||
|
||||
**Claude Desktop サードパーティプロバイダープロキシ切り替え**: CC Switch 内蔵のプロキシゲートウェイで Claude Desktop のリクエストをサードパーティプロバイダーへ転送する場合も、対象プロバイダーの課金・コンプライアンス・データ保持に関する規約に従う必要があります。
|
||||
|
||||
上記機能を有効化したユーザーは、関連するリスクを自ら負うものとします。CC Switch は、これらの機能の利用によって発生したアカウント制限、警告、サービス停止について責任を負いません。
|
||||
|
||||
---
|
||||
|
||||
## 謝辞
|
||||
|
||||
v3.16.5 で機能と修正を届けてくださった以下のコントリビューターに感謝します：
|
||||
|
||||
- [#4776](https://github.com/farion1231/cc-switch/pull/4776): セッションの分類ビューとグループ管理を追加、@alkaid616 に感謝。
|
||||
- [#4829](https://github.com/farion1231/cc-switch/pull/4829):「共通設定を書き込む」を「共通設定を適用」へ改名、@arichyx に感謝。
|
||||
- [#4654](https://github.com/farion1231/cc-switch/pull/4654): 使用量スクリプトの認証情報を明示的なオーバーライドとしてのみ永続化、@yyhhyyyyyy に感謝。
|
||||
- [#4680](https://github.com/farion1231/cc-switch/pull/4680): Windows で Hermes プロバイダー設定が効かない問題を修正、@thisTom に感謝。
|
||||
- [#4782](https://github.com/farion1231/cc-switch/pull/4782): Windows の Codex npm シムを重複排除、@justjavac に感謝。
|
||||
- [#4798](https://github.com/farion1231/cc-switch/pull/4798): 長いドロップダウンリストがスクロールできない問題を修正、@xwil1 に感謝。
|
||||
- [#4351](https://github.com/farion1231/cc-switch/pull/4351): AppImage が強制する `GDK_BACKEND=x11` を `CC_SWITCH_GDK_BACKEND` で上書き可能に、@BoneLiu に感謝。
|
||||
- [#4860](https://github.com/farion1231/cc-switch/pull/4860): 日付範囲セレクタのカレンダーが狭いポップオーバーでも画面内に収まるように、@SaladDay に感謝。
|
||||
|
||||
v3.16.4 リリース後に Codex ネイティブ直結、共通設定、認証情報の再利用、プラットフォーム互換性の問題を報告してくださったすべてのユーザーにも感謝します。今回の多くのパッチは、こうした実際の利用シーンから得られた再現の手がかりに基づいています。
|
||||
|
||||
---
|
||||
|
||||
## ダウンロードとインストール
|
||||
|
||||
[Releases](https://github.com/farion1231/cc-switch/releases/latest) から、お使いのシステムに対応するビルドをダウンロードしてください。
|
||||
|
||||
### システム要件
|
||||
|
||||
| システム | 最低バージョン | アーキテクチャ |
|
||||
| -------- | ------------------------ | ----------------------------------- |
|
||||
| Windows | Windows 10 以降 | x64 / ARM64 |
|
||||
| macOS | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 下表を参照 | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| ファイル | 説明 |
|
||||
| ---------------------------------------- | -------------------------------------------- |
|
||||
| `CC-Switch-v3.16.5-Windows.msi` | **推奨** - 自動更新対応の MSI インストーラー |
|
||||
| `CC-Switch-v3.16.5-Windows-Portable.zip` | ポータブル版、展開してそのまま実行できます |
|
||||
|
||||
Windows ARM64 デバイスをお使いの場合は、ファイル名に `arm64` 識別子が含まれる対応する制品を選択してください。
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| -------------------------------- | ------------------------------------------------------ |
|
||||
| `CC-Switch-v3.16.5-macOS.dmg` | **推奨** - DMG インストーラー、Applications へドラッグ |
|
||||
| `CC-Switch-v3.16.5-macOS.zip` | 展開して Applications へドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.16.5-macOS.tar.gz` | Homebrew インストールと自動更新用 |
|
||||
|
||||
Homebrew インストール：
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Linux アセットは **x86_64** と **ARM64**（`aarch64`）の両方を提供します。ファイル名にアーキテクチャ識別子が含まれているため、マシンの `uname -m` 出力に合わせて選択してください：
|
||||
|
||||
- `CC-Switch-v3.16.5-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- `CC-Switch-v3.16.5-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| ディストリビューション | 推奨形式 | インストール方法 |
|
||||
| --------------------------------------- | ----------- | ------------------------------------------------------------------------- |
|
||||
| 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` |
|
||||
@@ -0,0 +1,278 @@
|
||||
# CC Switch v3.16.5
|
||||
|
||||
> 这一版的重头戏是**让原生 Responses 格式的国产模型供应商真正适配到位**——为小米 MiMo、火山豆包、千问 Qwen3-Coder、美团 LongCat、MiniMax 等具备原生 Responses 端点的供应商生成 Codex 模型目录，让 Codex 桌面能看到这些模型、内置工具也能正常工作，并对少数拒收 `web_search` 的国产网关自动禁用该工具、避免请求被硬性拒绝。另有两处重要改进：切换供应商时，你在应用内新增的插件、环境变量等会**自动回写到通用配置并带给下一个供应商**；Linux（Wayland + NVIDIA）上「标题栏能点、页面点不动、缩放黑屏」的问题，现在也能用一个环境变量开关自救。本版还带来 Claude Sonnet 5 定价与默认档升级、两级分组的会话视图，以及一批凭据安全与平台兼容修复。
|
||||
|
||||
**[English →](v3.16.5-en.md) | [日本語版 →](v3.16.5-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 使用攻略
|
||||
|
||||
本版的新能力主要落在 Codex 供应商表单、会话面板与用量 / 通用配置里，建议结合以下文档了解：
|
||||
|
||||
- **[Codex 桌面看不到自定义模型？](../guides/codex-desktop-custom-model-visibility-zh.md)**：本版重做了**原生直连时的模型目录生成**——当 Codex 供应商使用原生 Responses（`openai_responses`）直连时，CC Switch 会生成 `~/.codex/cc-switch-model-catalog.json`，让 Codex 桌面能显示配置的自定义模型、工具也可用。若你此前配过原生 Codex 供应商，请**重新保存一次**以生成新目录（详见下方「升级提醒」）。
|
||||
- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：了解用量看板的数据来源与统计口径。本版新增了 Claude Sonnet 5 定价，并修复了用量脚本凭据被当作「显式覆盖」持久化的问题。
|
||||
- **[设置](../user-manual/zh/1-getting-started/1.5-settings.md)**：Codex 上游格式选择器与本地路由开关、Claude 通用配置（现更名为「应用通用配置」并支持切换时自动同步）都在供应商表单的高级选项里。
|
||||
|
||||
---
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> ## 唯一官方渠道声明（请务必阅读）
|
||||
>
|
||||
> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。请仅通过下列官方渠道获取本软件：
|
||||
>
|
||||
> | 类别 | 唯一官方 |
|
||||
> | -------- | ------------------------------------------------------------------------------ |
|
||||
> | 官网 | **[ccswitch.io](https://ccswitch.io)** |
|
||||
> | 源码 | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
|
||||
> | 下载 | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** |
|
||||
> | 作者 | **[@farion1231](https://github.com/farion1231)** |
|
||||
> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** |
|
||||
>
|
||||
> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.16.5 是 v3.16.4 之后的一版维护更新，核心是把**国产模型供应商的 Codex 原生直连做通**。v3.16.4 已经把千问 / 百炼、小米 MiMo、火山豆包、美团 LongCat、MiniMax 等供应商切到了原生 Responses 端点，本版进一步为它们生成 Codex 所需的**模型目录**（`~/.codex/cc-switch-model-catalog.json`），让 Codex 桌面真正能看到这些自定义模型、内置工具也能正常调用，并把模型映射从「本地路由」开关里彻底解耦。针对少数第一方模型不支持 OpenAI 内置 `web_search` 的国产网关（MiMo、LongCat、MiniMax、Qwen3-Coder），本版还会自动禁用该工具，避免 Codex 默认带上它触发硬 400。
|
||||
|
||||
围绕日常使用体验，本版让 Claude 的**通用配置在切换供应商时自动同步并传递**——你在应用内新增的插件、环境变量、主题等会先回写到通用配置、再带给下一个供应商，不会在切换时丢失；给 Linux（Wayland + NVIDIA）上点击失灵 / 黑屏的用户加了一个可自救的环境变量开关；补上 Claude Sonnet 5 定价并把默认 Sonnet 档升级到它；带来「供应商 → 项目目录」两级分组的会话视图；并修了一串凭据安全（通用配置片段剥离全部密钥、用量脚本凭据仅作显式覆盖）、平台兼容（Hermes Windows 配置目录、Windows Codex npm 影子命令）与界面（长下拉滚动、窄窗口日期选择器）的问题。此外也新增了若干供应商预设，开箱即可选用。
|
||||
|
||||
**发布日期**：2026-07-01
|
||||
|
||||
**更新规模**：36 commits | 93 files changed | +5,678 / -2,804 lines
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- **让国产模型供应商的 Codex 原生直连真正可用**：为小米 MiMo、火山豆包、千问 Qwen3-Coder、美团 LongCat、MiniMax 等国产供应商生成 Codex 模型目录（`~/.codex/cc-switch-model-catalog.json`），让 Codex 桌面能看到这些模型、内置工具可用；并对拒收 `web_search` 的国产网关（MiMo、LongCat、MiniMax、Qwen3-Coder）自动禁用该工具、避免硬 400。**存量原生供应商需重存一次**以生成新目录。
|
||||
- **通用配置切换时自动同步并传递**：切走一个启用了通用配置的 Claude 供应商时，你在应用内新增的插件、环境变量、主题、hooks 会先自动回写到通用配置，再带给下一个供应商——不再在切换时被覆盖丢失。
|
||||
- **Linux Wayland 点击失灵 / 黑屏的自救开关**：遇到 Wayland + NVIDIA 上「标题栏能点、页面点不动、缩放黑屏」时，用 `CC_SWITCH_GDK_BACKEND=wayland` 启动即可切回原生 Wayland（平铺式合成器上遇到反向问题可设为 `x11`）。
|
||||
- **Claude Sonnet 5**：新增 Sonnet 5 定价，并把各预设的默认 Sonnet 档升级到 `claude-sonnet-5`。
|
||||
- **会话分类视图与分组管理**：会话面板新增「供应商 → 项目目录」两级分组视图，分组头支持三态复选框一键批量选择。
|
||||
- **新增供应商预设**：新增七牛云、FennoAI、ZetaAPI、TeamoRouter、NekoCode、Code0.ai、Amux 等供应商预设，覆盖各受管应用，开箱即可选用。
|
||||
|
||||
---
|
||||
|
||||
## 新功能
|
||||
|
||||
### 国产模型供应商的 Codex 原生直连（生成模型目录）
|
||||
|
||||
本版把国产供应商的 Codex 原生直连做通了。继 v3.16.4 把小米 MiMo、火山豆包、千问 Qwen3-Coder、美团 LongCat、MiniMax 等供应商切换到原生 Responses（`apiFormat: "openai_responses"`）之后，本版推翻了当时「原生直连就删掉模型目录」的做法：这些供应商不经过本地代理直连时，CC Switch 会为它们生成 `~/.codex/cc-switch-model-catalog.json`，让 Codex 桌面真正显示这些自定义模型、内置工具也能用——不会触发像 MiMo 这类原生网关会拒绝的 freeform `apply_patch`（`type=custom`）工具（编辑回退到 `shell_command`）。目录生成按 `apiFormat` 判定、与「本地路由」开关解耦，因此一个原生供应商无需开启本地路由映射也会持久化目录；而 `openai_chat` 格式仍保持既有的 Responses↔Chat 代理转换不变。由于 Codex 解析器要求每个条目都带 `base_instructions`，原生模板携带一个中性默认值、由各厂商官方文案覆盖（MiMo、MiniMax）。**存量原生供应商需重新保存一次以生成有效目录**（无需数据库迁移）。
|
||||
|
||||
配套地，对少数第一方模型不支持 OpenAI 内置 `web_search` 工具的国产网关（MiMo、LongCat、MiniMax、Qwen3-Coder），本版会在切换时自动禁用该工具，避免 Codex 默认带上它、被网关以硬 400 拒绝（详见下方「修复」）。
|
||||
|
||||
### 会话分类视图与分组管理
|
||||
|
||||
会话管理面板在原有平铺列表之外新增了分组视图，通过工具栏的 List / ListTree 选择器切换，视图模式与展开状态都持久化到 `localStorage`。分组构建「供应商 → 项目目录」两级层级：按项目目录名归组，缺少项目目录的会话落入「未知目录」桶。两级都是可折叠区块，并提供「全部折叠」按钮；在批量模式下，每个分组头会出现一个三态复选框，可一键选中 / 取消该组内全部可选会话，并显示已选 / 可选计数徽标。四语（zh / en / ja / zh-TW）文案已同步。该改动完全在前端，不涉及后端命令或数据访问层。（[#4776](https://github.com/farion1231/cc-switch/pull/4776)）
|
||||
|
||||
### Claude Sonnet 5 模型定价
|
||||
|
||||
在 `schema.rs` 里按 Anthropic list 价新增 `claude-sonnet-5` 定价行——输入 / 输出 \$3 / \$15 每百万 token、缓存读写 \$0.30 / \$3.75，与 Sonnet 4.6 一致。介绍期 \$2 / \$10 促销（有效期至 2026-08-31）刻意不入表，让记账反映稳态 list 价而非临时折扣。该行在应用下次启动时通过 `ensure_model_pricing_seeded` 应用，无需 `SCHEMA_VERSION` 变更。
|
||||
|
||||
### 新增供应商预设
|
||||
|
||||
本版新增了一批供应商预设，选中后填入自己的 API Key 即可使用：
|
||||
|
||||
- **七牛云（Qiniu）**：覆盖全部 7 个受管应用（含 Gemini），中转原生 Claude / GPT / Gemini。
|
||||
- **FennoAI / ZetaAPI / TeamoRouter / NekoCode**：各覆盖 6 个应用（Claude、Claude Desktop、Codex、OpenCode、OpenClaw、Hermes）。
|
||||
- **Code0.ai**：覆盖全部 7 个应用（含 Gemini）。
|
||||
- **Amux**：覆盖 6 个应用。
|
||||
|
||||
各预设的端点与默认模型已按对应应用配好——Claude 类走 Anthropic 兼容主机直连、Codex 走原生 Responses、其余走 OpenAI 兼容 `/v1`。
|
||||
|
||||
---
|
||||
|
||||
## 变更
|
||||
|
||||
### 切换供应商时自动同步并传递通用配置
|
||||
|
||||
这是本版一个很实用的改动：切走一个启用了通用配置的 Claude 供应商时，服务会先从它的 live `settings.json` 里**重新提取可共享部分、更新到通用配置**，再带给下一个供应商，而不再只是单向写入。这样一来，你在运行中的应用里直接新增的插件（`enabledPlugins`）、hooks、环境变量（`env`）、主题（`theme`）等共享配置就不会在切换时被静默丢失，而是自动跟着走到下一个供应商；删除也会同步（移除的键不会被再次注入）。该同步严格限定在启用了通用配置的 Claude 供应商，被显式清空时会跳过，且所有失败都是非致命（仅告警）、永不阻断切换。
|
||||
|
||||
### Codex 模型映射与「本地路由」开关解耦
|
||||
|
||||
Codex 供应商表单向 Claude Code 对齐——模型映射目录现在独立于路由接管，因为原生 Responses 供应商（MiMo、豆包、MiniMax）需要它来做无代理直连，而 Chat 供应商无论如何都走代理。「需要本地路由」开关被移除（它没有后端字段，只是门控目录 / 推理的持久化，等价于「映射是否填了」）。模型映射现在对非官方供应商始终显示、非空即持久化，而推理能力的显示 / 持久化改由 Chat 格式门控。四语（zh / en / ja / zh-TW）文案随之重写。顺带修复了 `useCodexConfigState` 在加载已存供应商时丢掉 `supportsParallelToolCalls` / `inputModalities` / `baseInstructions` 的问题（会在编辑时静默丢失并行工具、图像输入与官方 base instructions）。
|
||||
|
||||
### 默认 Sonnet 档升级到 Claude Sonnet 5
|
||||
|
||||
把各供应商预设里的默认 Sonnet 档从 `claude-sonnet-4-6` 升级到 `claude-sonnet-5`（覆盖 claude / claude-desktop / hermes / openclaw / opencode 预设与通用 `NEWAPI_DEFAULT_MODELS`），涉及 `ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_OPUS_MODEL` 等键及其带前缀变体。Claude Desktop 的默认路由 sonnet `route_id` 也一并迁移到 `claude-sonnet-5`。非 Anthropic 的 pin（gpt / gemini / glm / sonnet-4-5）保持不变。
|
||||
|
||||
### 豆包带日期 model id 与定价归一化
|
||||
|
||||
豆包（DouBaoSeed）预设的 model id 切换到带日期的 `doubao-seed-2-1-pro-260628`（覆盖各应用），因为火山方舟会以 404 拒绝裸名 `doubao-seed-2-1-pro`、只接受完整带日期 id。由于真实用量现在带日期后缀，`strip_model_date_suffix` 扩展为也能剥掉火山的 6 位 YYMMDD 形式（并校验月 01-12、日 01-31 以免误伤 `-123456` 这类非日期版本后缀），从而归一化命中定价表里的裸名 seed 行、修复豆包模型显示 \$0 成本的问题。
|
||||
|
||||
###「写入通用配置」更名为「应用通用配置」
|
||||
|
||||
原标签「写入通用配置」在数据流向上有歧义（读起来像「把当前配置写进通用配置」），而实际行为相反——是把已存的通用配置片段合并进本供应商配置。复选框在四语（zh / en / ja / zh-TW）里更名为「应用通用配置」，包括所有提示 / 攻略 / 说明引用，日文用户手册与 `README_JA.md` 也一并同步。（[#4829](https://github.com/farion1231/cc-switch/pull/4829)）
|
||||
|
||||
### 其它预设与资源调整
|
||||
|
||||
- **OpenClaw 豆包上下文对齐 262144**：OpenClaw 的 DouBaoSeed 预设此前硬编码 128000，而 Codex 侧同模型用 262144，导致 OpenClaw 用户窗口偏小；已对齐并加了跨预设一致性测试防止再次漂移。
|
||||
- **火山 / 豆包 / BytePlus 官网链接订正**：这三个预设的「访问官网」链接被误设成了控制台 / 注册链接，已恢复为干净的产品主页。
|
||||
- **过大的供应商图标降采样到 256px**：一批捆绑图标此前远大于其 ~32px 的实际渲染尺寸，降采样后显著减小体积、无代码 / 文件名 / 导入改动（如 ZetaAPI 940KB→40KB、relaxcode 1.16MB→42KB），并删除了从未被引用的 1.4MB `dds.svg` 孤儿。
|
||||
|
||||
---
|
||||
|
||||
## 修复
|
||||
|
||||
### 对拒收 `web_search` 的原生 Codex 网关禁用该工具
|
||||
|
||||
一些原生 `/responses` 网关的第一方模型不具备 OpenAI 内置的 `web_search` 工具，会以「tool type 'web_search' is not supported」拒绝，而 Codex 默认就会带上该工具，导致硬 400。CC Switch 现在会为这些厂商写入顶层 TOML 行 `web_search = "disabled"`。作用域是一份黑名单（默认开启）：仅命中 `base_url` 主机（`xiaomimimo.com`、`longcat.chat`、`minimax.io`、`minimaxi.com`）或模型品牌前缀（`mimo`、`longcat`、`minimax`、`qwen3-coder`）的供应商会被禁用，因此中转真 GPT、豆包、通用 Qwen 及任何未知供应商都保持 Codex 默认。其中 `qwen3-coder` 前缀只压制原生 `qwen3-coder-plus`（百炼 / DashScope 对 coder 系标记内置工具不支持），共享同一主机的通用 Qwen 保持开启；匹配走模型轴（会剥掉聚合器的 `vendor/` 路径段），因此也能兜住硅基流动这类中转拒收厂商模型的情形。选黑名单而非模糊的「是不是 GPT」白名单，是因为误让 `web_search` 保持开启会以硬 400 失败；同时用归属哨兵保证 CC Switch 只会移除由它自己写入的 `disabled` 值，因此存量供应商无需重存、切回也会重新启用。此外顺带把 LongCat-2.0-Preview 预设的上下文窗口从 131072（128K）订正为真实的 1048576（1M）。
|
||||
|
||||
### 通用配置片段剥离全部凭据类键
|
||||
|
||||
`extract_claude_common_config` 此前只脱敏 `ANTHROPIC_API_KEY` 与 `ANTHROPIC_AUTH_TOKEN`，但 Claude 供应商合法地携带其它凭据（`OPENROUTER_API_KEY`、`GOOGLE_API_KEY`，可能还有 OpenAI / Gemini / AWS Bedrock / Vertex 密钥），这些可能泄漏进共享片段、再被注入到其它供应商。提取现在会按模式匹配并剥掉任何凭据形态的环境变量键（`*_API_KEY` / `*_AUTH_TOKEN` / `*secret*` / `*token*` 等），同时保留 `MAX_OUTPUT_TOKENS` 这类合法可共享的复数 `*_TOKENS` 值。手动「提取」与一次性自动提取路径的同一泄漏也一并堵上。
|
||||
|
||||
### 用量脚本凭据仅作显式覆盖持久化
|
||||
|
||||
供应商用量脚本存有可选的 `api_key` / `base_url` 字段用于查询配额时覆盖 live 凭据，但它们此前会静默镜像供应商自身的凭据——因此复制供应商或修改主 API key / base URL 后，用量脚本仍 pin 在旧端点旧 key，配额查询一直打向陈旧目标。现在 `ProviderService` 在持久化前会归一化：若脚本的 `api_key` 或 `base_url` 与供应商解析出的用量凭据相同（或为空）就清为 `None`，让查询回退到 live 配置；真正不同的覆盖才保留（`token_plan` 类脚本不动）。deeplink 导入路径也加了对应的归一化，前端在更新时会失效相关缓存键让首页用修正后的配置重新查询。（[#4654](https://github.com/farion1231/cc-switch/pull/4654)）
|
||||
|
||||
### Hermes 配置目录在 Windows 上正确解析
|
||||
|
||||
CC Switch 此前硬编码 `~/.hermes` 作为 Hermes 配置目录，但 Hermes 自身是按 `HERMES_HOME` 环境变量、再退到平台默认（Windows 上 `%LOCALAPPDATA%\hermes`）解析的。在 Windows 上这意味着 CC Switch 把供应商配置写到了 Hermes 根本不读的路径，导致供应商切换无效。`get_hermes_dir()` 现在镜像 Hermes 自己的解析顺序——显式覆盖、`HERMES_HOME`（原样取用、不做 `~` 展开）、平台默认——从而重新尊重被 #3470 丢掉的 `HERMES_HOME`（Hermes 的 Windows 安装器把它作为重定位安装的首要机制）。（[#4680](https://github.com/farion1231/cc-switch/pull/4680)，参见 #3178、#3470）
|
||||
|
||||
### Linux Wayland：允许覆盖 AppImage 强制的 `GDK_BACKEND=x11`
|
||||
|
||||
AppImage 的 GTK 启动钩子无条件导出 `GDK_BACKEND=x11` 以规避一个历史上的原生 Wayland 崩溃。在较新的 Wayland + NVIDIA 环境上，这个被强制的 XWayland 会让 WebKitGTK 网页内容收不到指针事件（标题栏可点、页面却死了）、并在缩放时黑屏，而既有的 `WEBKIT_DISABLE_*` 缓解不起作用，因为根因是被强制的窗口后端而非渲染。`main.rs` 现在会在 GTK 初始化前读取一个可选的 `CC_SWITCH_GDK_BACKEND` 逃生开关（AppImage 的启动钩子从不改动它）：不设保持现状（零回归）。遇到上述问题时，用它切回原生 Wayland 启动即可：
|
||||
|
||||
```bash
|
||||
CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
|
||||
```
|
||||
|
||||
该覆盖是通用的——若你在平铺式 Wayland 合成器上遇到的是反向的输入问题，则改设为 `CC_SWITCH_GDK_BACKEND=x11`。（[#4351](https://github.com/farion1231/cc-switch/pull/4351)，修复 #4350）
|
||||
|
||||
### Claude Desktop / OpenClaw / Hermes 表单显示「获取 API Key」链接
|
||||
|
||||
API key 输入框下的「获取 API Key」链接与合作推广块此前只对 claude / codex / gemini / opencode 生效。Claude Desktop 渲染的是不显示它的裸输入框，而 OpenClaw / Hermes 则被两处遗漏挡住（白名单只列了那四个 appId、供应商分类解析只认那四类预设 id 模式）。现在 Claude Desktop 改用共享的 `ApiKeySection`，白名单与分类解析都补上了 claude-desktop / openclaw / hermes；此外 Hermes / OpenClaw 表单不再让「官方」分类禁用 key 输入（这两个应用没有只走 OAuth 的官方供应商，如 Hermes 的 Nous Research 虽是官方但仍需用户自填 key）。
|
||||
|
||||
### 去重 Windows 上的 Codex npm 影子命令
|
||||
|
||||
在 Windows 上，npm 会把一个工具装成三个同名兄弟文件——`codex.cmd`、`codex.exe` 和一个无扩展名的 Unix shim `codex`——而 CC Switch 此前把三者都列为候选，导致无法直接执行的无扩展名 shim 被当作多余 / 失败候选去探测。现在仅当相邻没有可执行的 `.cmd` / `.exe` 兄弟时才追加无扩展名路径，路径解析也会优先选可执行的 `.cmd` / `.exe`，从而把版本探测与启动锚定到真正可运行的 Windows shim 上。（[#4782](https://github.com/farion1231/cc-switch/pull/4782)）
|
||||
|
||||
### 长下拉列表的滚动边界
|
||||
|
||||
`SelectContent` 弹层此前用 `overflow-hidden` 且没有高度上限，因此选项很多的下拉（如长模型 / 供应商列表）会渲染得比视口还高、把溢出项裁掉且无法触及。现在它设了 `max-h-[min(24rem,var(--radix-select-content-available-height))]` 与 `overflow-y-auto`，把内容限制在 24rem 或 Radix 计算出的可用高度内并允许纵向滚动。（[#4798](https://github.com/farion1231/cc-switch/pull/4798)）
|
||||
|
||||
### 日期范围选择器的日历在窄弹层里保持可见
|
||||
|
||||
自定义日期范围选择器此前按**视口宽度**（Tailwind `sm:` 640px 断点）切换两列布局（日期字段 | 日历），但弹层被夹在 `100vw - 2rem` 且锚定到触发器，实际可用宽度比视口窄。在窄窗口上，两列布局可能在弹层只放得下一列时被激活，把日历列挤出右边界裁掉（月份头与 7 列里的 4 列被切掉且无法触及）。现在布局改用 **CSS 容器查询**按弹层自身的行内尺寸切换，因此只有当弹层本身窄时才收成一列，让日历在任意窗口宽度下都完整可见。（[#4860](https://github.com/farion1231/cc-switch/pull/4860)）
|
||||
|
||||
---
|
||||
|
||||
## 文档
|
||||
|
||||
### `CC_SWITCH_GDK_BACKEND` 逃生开关文档
|
||||
|
||||
为可选的 `CC_SWITCH_GDK_BACKEND` 环境变量新增了 FAQ 条目，覆盖全部四种 README 语言与 zh / en / ja 用户手册的排障页，说明 Wayland + NVIDIA 用户如何在网页内容「点击失灵 + 缩放黑屏」时切回原生 Wayland，以及平铺式 Wayland 用户如何设为 `x11` 处理反向输入问题。
|
||||
|
||||
### Kimi 海外 README 指向 platform.kimi.ai
|
||||
|
||||
英语、德语、日语 README 的 Kimi K2.7 Code 合作段落的横幅与内联行动号召改指 `https://platform.kimi.ai?aff=cc-switch`（保留推荐标签），四语 README 也都新增了一行指向 `https://www.kimi.com/code/?aff=cc-switch` 的 Kimi For Coding 订阅推广。
|
||||
|
||||
---
|
||||
|
||||
## 升级提醒
|
||||
|
||||
### 原生 Codex 供应商需重存一次
|
||||
|
||||
本版重做了原生 Responses 直连的模型目录生成。如果你此前配过使用原生 Responses（`openai_responses`）的 Codex 供应商，请**重新从预设选择或打开该供应商并保存一次**，以生成新的 `~/.codex/cc-switch-model-catalog.json`——这样 Codex 桌面才能显示自定义模型、工具才可用。此过程无需数据库迁移，也不影响走 `openai_chat` 格式的供应商。
|
||||
|
||||
### `web_search` 黑名单是默认行为
|
||||
|
||||
对小米 MiMo、美团 LongCat、MiniMax、千问 Qwen3-Coder 这些已知拒收 `web_search` 的原生网关，本版会在切换时自动写入 `web_search = "disabled"`。中转真 GPT、豆包、通用 Qwen 及未知供应商不受影响、保持 Codex 默认。该开关由 CC Switch 用归属哨兵管理，切回到未命中黑名单的供应商会自动恢复，无需手动干预。
|
||||
|
||||
### 默认 Sonnet 档变化
|
||||
|
||||
新从预设创建的 Claude 类供应商，其默认 Sonnet 档现在指向 `claude-sonnet-5`。已配置好的存量供应商不受影响、配置保持原样；如需改用 Sonnet 5，可重新从预设选择一次并保存。
|
||||
|
||||
---
|
||||
|
||||
## 风险提示
|
||||
|
||||
本版本继续沿用此前版本对反向代理类功能的风险提示。
|
||||
|
||||
**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
|
||||
|
||||
**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
|
||||
|
||||
**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，同样需要遵守目标供应商的计费、合规与数据留存约束。
|
||||
|
||||
用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
|
||||
|
||||
---
|
||||
|
||||
## 致谢
|
||||
|
||||
感谢以下贡献者在 v3.16.5 中提交的功能与修复：
|
||||
|
||||
- [#4776](https://github.com/farion1231/cc-switch/pull/4776)：新增会话分类视图与分组管理，感谢 @alkaid616。
|
||||
- [#4829](https://github.com/farion1231/cc-switch/pull/4829)：把「写入通用配置」更名为「应用通用配置」，感谢 @arichyx。
|
||||
- [#4654](https://github.com/farion1231/cc-switch/pull/4654)：让用量脚本凭据仅作显式覆盖持久化，感谢 @yyhhyyyyyy。
|
||||
- [#4680](https://github.com/farion1231/cc-switch/pull/4680)：修复 Windows 上 Hermes 供应商配置不生效，感谢 @thisTom。
|
||||
- [#4782](https://github.com/farion1231/cc-switch/pull/4782)：去重 Windows 上的 Codex npm 影子命令，感谢 @justjavac。
|
||||
- [#4798](https://github.com/farion1231/cc-switch/pull/4798)：修复长下拉列表无法滚动，感谢 @xwil1。
|
||||
- [#4351](https://github.com/farion1231/cc-switch/pull/4351)：允许通过 `CC_SWITCH_GDK_BACKEND` 覆盖 AppImage 强制的 `GDK_BACKEND=x11`，感谢 @BoneLiu。
|
||||
- [#4860](https://github.com/farion1231/cc-switch/pull/4860)：让日期范围选择器的日历在窄弹层里保持可见，感谢 @SaladDay。
|
||||
|
||||
也感谢所有在 v3.16.4 发布后反馈 Codex 原生直连、通用配置、凭据复用与平台兼容性问题的用户，很多补丁都来自这些真实使用场景里的复现线索。
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
|
||||
|
||||
### 系统要求
|
||||
|
||||
| 系统 | 最低版本 | 架构 |
|
||||
| ------- | -------------------------- | ----------------------------------- |
|
||||
| Windows | Windows 10 及以上 | x64 / ARM64 |
|
||||
| macOS | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
|
||||
| Linux | 见下表 | x64 / ARM64 |
|
||||
|
||||
### Windows
|
||||
|
||||
| 文件 | 说明 |
|
||||
| ---------------------------------------- | ----------------------------------- |
|
||||
| `CC-Switch-v3.16.5-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.16.5-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
Windows ARM64 设备请选择文件名中带 `arm64` 标识的对应制品。
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| -------------------------------- | --------------------------------------------- |
|
||||
| `CC-Switch-v3.16.5-macOS.dmg` | **推荐** - DMG 安装包，拖入 Applications 即可 |
|
||||
| `CC-Switch-v3.16.5-macOS.zip` | 解压后拖入 Applications，Universal Binary |
|
||||
| `CC-Switch-v3.16.5-macOS.tar.gz` | 用于 Homebrew 安装和自动更新 |
|
||||
|
||||
Homebrew 安装：
|
||||
|
||||
```bash
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本：
|
||||
|
||||
- `CC-Switch-v3.16.5-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||||
- `CC-Switch-v3.16.5-Linux-arm64.AppImage` / `.deb` / `.rpm`
|
||||
|
||||
| 发行版 | 推荐格式 | 安装方式 |
|
||||
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| 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` |
|
||||
@@ -0,0 +1,249 @@
|
||||
## Major architecture refactoring with enhanced config sync and data protection
|
||||
|
||||
**[中文更新说明 Chinese Documentation →](https://github.com/farion1231/cc-switch/blob/main/docs/release-notes/v3.6.0-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## What's New
|
||||
|
||||
### Edit Mode & Provider Management
|
||||
|
||||
- **Provider Duplication** - Quickly duplicate existing provider configurations to create variants with one click
|
||||
- **Manual Sorting** - Drag and drop to reorder providers, with visual push effect animations. Thanks to @ZyphrZero
|
||||
- **Edit Mode Toggle** - Show/hide drag handles to optimize editing experience
|
||||
|
||||
### Custom Endpoint Management
|
||||
|
||||
- **Multi-Endpoint Configuration** - Support for aggregator providers with multiple API endpoints
|
||||
- **Endpoint Input Visibility** - Shows endpoint field for all non-official providers automatically
|
||||
|
||||
### Usage Query Enhancements
|
||||
|
||||
- **Auto-Refresh Interval** - Configure periodic automatic usage queries with customizable intervals
|
||||
- **Test Script API** - Validate JavaScript usage query scripts before execution
|
||||
- **Enhanced Templates** - Custom blank templates with access token and user ID parameter support
|
||||
Thanks to @Sirhexs
|
||||
|
||||
### Custom Configuration Directory (Cloud Sync)
|
||||
|
||||
- **Customizable Storage Location** - Customize CC Switch's configuration storage directory
|
||||
- **Cloud Sync Support** - Point to cloud sync folders (Dropbox, OneDrive, iCloud Drive, etc.) to enable automatic config synchronization across devices
|
||||
- **Independent Management** - Managed via Tauri Store for better isolation and reliability
|
||||
Thanks to @ZyphrZero
|
||||
|
||||
### Configuration Directory Switching (WSL Support)
|
||||
|
||||
- **Auto-Sync on Directory Change** - When switching Claude/Codex config directories (e.g., WSL environment), automatically sync current provider to the new directory without manual operation
|
||||
- **Post-Change Sync Utility** - Unified `postChangeSync.ts` utility for graceful error handling without blocking main flow
|
||||
- **Import Config Auto-Sync** - Automatically sync after config import to ensure immediate effectiveness
|
||||
- **Smart Conflict Resolution** - Distinguishes "fully successful" and "partially successful" states for precise user feedback
|
||||
|
||||
### Configuration Editor Improvements
|
||||
|
||||
- **JSON Format Button** - One-click JSON formatting in configuration editors
|
||||
- **Real-Time TOML Validation** - Live syntax validation for Codex configuration with error highlighting
|
||||
|
||||
### Load Live Config When Editing
|
||||
|
||||
- **Protect Manual Modifications** - When editing the currently active provider, prioritize displaying the actual effective configuration from live files
|
||||
- **Dual-Source Strategy** - Automatically loads from live config for active provider, SSOT for inactive ones
|
||||
|
||||
### Claude Configuration Data Structure Enhancements
|
||||
|
||||
- **Granular Model Configuration** - Migrated from dual-key to quad-key system for better model tier differentiation
|
||||
- New fields: `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_MODEL`
|
||||
- Replaces legacy `ANTHROPIC_SMALL_FAST_MODEL` with automatic migration
|
||||
- Backend normalizes old configs on first read/write with smart fallback chain
|
||||
- UI expanded from 2 to 4 model input fields with intelligent defaults
|
||||
- **ANTHROPIC_API_KEY Support** - Providers can now use `ANTHROPIC_API_KEY` field in addition to `ANTHROPIC_AUTH_TOKEN`
|
||||
- **Template Variable System** - Support for dynamic configuration replacement (e.g., KAT-Coder's `ENDPOINT_ID` parameter)
|
||||
- **Endpoint Candidates** - Predefined endpoint list for speed testing and endpoint management
|
||||
- **Visual Theme Configuration** - Custom icons and colors for provider cards
|
||||
|
||||
### Updated Provider Models
|
||||
|
||||
- **Kimi k2** - Updated to latest `kimi-k2-thinking` model
|
||||
|
||||
### New Provider Presets
|
||||
|
||||
Added 5 new provider presets:
|
||||
|
||||
- **DMXAPI** - Multi-model aggregation service
|
||||
- **Azure Codex** - Microsoft Azure OpenAI endpoint
|
||||
- **AnyRouter** - None-profit routing service
|
||||
- **AiHubMix** - Multi-model aggregation service
|
||||
- **MiniMax** - Open source AI model provider
|
||||
|
||||
### Partner Promotion Mechanism
|
||||
|
||||
- Support for ecosystem partner promotion (Zhipu GLM Z.ai)
|
||||
- Sponsored banner integration in README
|
||||
|
||||
---
|
||||
|
||||
## Improvements
|
||||
|
||||
### Configuration & Sync
|
||||
|
||||
- **Unified Error Handling** - AppError with internationalized error messages throughout backend
|
||||
- **Fixed apiKeyUrl Priority** - Correct priority order for API key URL resolution
|
||||
- **Fixed MCP Sync Issues** - Resolved sync-to-other-side functionality failures
|
||||
- **Import Config Sync** - Fixed sync issues after configuration import
|
||||
- **Config Error Handling** - Force exit on config error to prevent silent fallback and data loss
|
||||
|
||||
### UI/UX Enhancements
|
||||
|
||||
- **Unique Provider Icons** - Each provider card now has unique icons and color identification
|
||||
- **Unified Border System** - Consistent border design across all components
|
||||
- **Drag Interaction** - Push effect animation and improved drag handle icons
|
||||
- **Enhanced Visual Feedback** - Better current provider visual indication
|
||||
- **Dialog Standardization** - Unified dialog sizes and layout consistency
|
||||
- **Form Improvements** - Optimized model placeholders, simplified provider hints, category-specific hints
|
||||
- **Usage Display Inline** - Usage info moved next to enable button for better space utilization
|
||||
|
||||
### Complete Internationalization
|
||||
|
||||
- **Error Messages i18n** - All backend error messages support Chinese/English
|
||||
- **Tray Menu i18n** - System tray menu fully internationalized
|
||||
- **UI Components i18n** - 100% coverage across all user-facing components
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Configuration Management
|
||||
|
||||
- Fixed `apiKeyUrl` priority issue
|
||||
- Fixed MCP sync-to-other-side functionality failure
|
||||
- Fixed sync issues after config import
|
||||
- Fixed Codex API Key auto-sync
|
||||
- Fixed endpoint speed test functionality
|
||||
- Fixed provider duplicate insertion position (now inserts next to original)
|
||||
- Fixed custom endpoint preservation in edit mode
|
||||
- Prevent silent fallback and data loss on config error
|
||||
|
||||
### Usage Query
|
||||
|
||||
- Fixed auto-query interval timing issue
|
||||
- Ensured refresh button shows loading animation on click
|
||||
|
||||
### UI Issues
|
||||
|
||||
- Fixed name collision error (`get_init_error` command)
|
||||
- Fixed language setting rollback after successful save
|
||||
- Fixed language switch state reset (dependency cycle)
|
||||
- Fixed edit mode button alignment
|
||||
|
||||
### Startup Issues
|
||||
|
||||
- Force exit on config error (no silent fallback)
|
||||
- Eliminated code duplication causing initialization errors
|
||||
|
||||
---
|
||||
|
||||
## Architecture Refactoring
|
||||
|
||||
### Backend (Rust) - 5 Phase Refactoring
|
||||
|
||||
1. **Phase 1**: Unified error handling (`AppError` + i18n error messages)
|
||||
2. **Phase 2**: Command layer split by domain (`commands/{provider,mcp,config,settings,plugin,misc}.rs`)
|
||||
3. **Phase 3**: Integration tests and transaction mechanism (config snapshot + failure rollback)
|
||||
4. **Phase 4**: Extracted Service layer (`services/{provider,mcp,config,speedtest}.rs`)
|
||||
5. **Phase 5**: Concurrency optimization (`RwLock` instead of `Mutex`, scoped guard to avoid deadlock)
|
||||
|
||||
### Frontend (React + TypeScript) - 4 Stage Refactoring
|
||||
|
||||
1. **Stage 1**: Test infrastructure (vitest + MSW + @testing-library/react)
|
||||
2. **Stage 2**: Extracted custom hooks (`useProviderActions`, `useMcpActions`, `useSettings`, `useImportExport`, etc.)
|
||||
3. **Stage 3**: Component splitting and business logic extraction
|
||||
4. **Stage 4**: Code cleanup and formatting unification
|
||||
|
||||
### Testing System
|
||||
|
||||
- **Hooks Unit Tests** - 100% coverage for all custom hooks
|
||||
- **Integration Tests** - Coverage for key processes (App, SettingsDialog, MCP Panel)
|
||||
- **MSW Mocking** - Backend API mocking to ensure test independence
|
||||
- **Test Infrastructure** - vitest + MSW + @testing-library/react
|
||||
|
||||
### Code Quality
|
||||
|
||||
- **Unified Parameter Format** - All Tauri commands migrated to camelCase (Tauri 2 specification)
|
||||
- **Semantic Clarity** - `AppType` renamed to `AppId` for better semantics
|
||||
- **Centralized Parsing** - Unified `app` parameter parsing with `FromStr` trait
|
||||
- **DRY Violations Cleanup** - Eliminated code duplication throughout codebase
|
||||
- **Dead Code Removal** - Removed unused `missing_param` helper, deprecated `tauri-api.ts`, redundant `KimiModelSelector`
|
||||
|
||||
---
|
||||
|
||||
## Internal Optimizations (User Transparent)
|
||||
|
||||
### Removed Legacy Migration Logic
|
||||
|
||||
v3.6.0 removed v1 config auto-migration and copy file scanning logic:
|
||||
|
||||
- **Impact**: Improved startup performance, cleaner codebase
|
||||
- **Compatibility**: v2 format configs fully compatible, no action required
|
||||
- **Note**: Users upgrading from v3.1.0 or earlier should first upgrade to v3.2.x or v3.5.x for one-time migration, then upgrade to v3.6.0
|
||||
|
||||
### Command Parameter Standardization
|
||||
|
||||
Backend unified to use `app` parameter (values: `claude` or `codex`):
|
||||
|
||||
- **Impact**: More standardized code, friendlier error prompts
|
||||
- **Compatibility**: Frontend fully adapted, users don't need to care about this change
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Updated to **Tauri 2.8.x**
|
||||
- Updated to **TailwindCSS 4.x**
|
||||
- Updated to **TanStack Query v5.90.x**
|
||||
- Maintained **React 18.2.x** and **TypeScript 5.3.x**
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
### macOS
|
||||
|
||||
**Via Homebrew (Recommended):**
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
**Manual Download:**
|
||||
|
||||
- Download `CC-Switch-v3.6.0-macOS.zip` from [Assets](#assets) below
|
||||
|
||||
> **Note**: Due to lack of Apple Developer account, you may see "unidentified developer" warning. Go to System Settings → Privacy & Security → Click "Open Anyway"
|
||||
|
||||
### Windows
|
||||
|
||||
- **Installer**: `CC-Switch-v3.6.0-Windows.msi`
|
||||
- **Portable**: `CC-Switch-v3.6.0-Windows-Portable.zip`
|
||||
|
||||
### Linux
|
||||
|
||||
- **AppImage**: `CC-Switch-v3.6.0-Linux.AppImage`
|
||||
- **Debian**: `CC-Switch-v3.6.0-Linux.deb`
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
- [中文文档 (Chinese)](https://github.com/farion1231/cc-switch/blob/main/README_ZH.md)
|
||||
- [English Documentation](https://github.com/farion1231/cc-switch/blob/main/README.md)
|
||||
- [完整更新日志 (Full Changelog)](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
Special thanks to **Zhipu AI** for sponsoring this project with their GLM CODING PLAN!
|
||||
|
||||
---
|
||||
|
||||
**Full Changelog**: https://github.com/farion1231/cc-switch/compare/v3.5.1...v3.6.0
|
||||
@@ -0,0 +1,249 @@
|
||||
# CC Switch v3.6.0
|
||||
|
||||
> 全栈架构重构，增强配置同步与数据保护
|
||||
|
||||
**[English Version →](v3.6.0-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 新增功能
|
||||
|
||||
### 编辑模式与供应商管理
|
||||
|
||||
- **供应商复制功能** - 一键快速复制现有供应商配置，轻松创建变体配置
|
||||
- **手动排序功能** - 通过拖拽对供应商进行重新排序，带有视觉推送效果动画
|
||||
- **编辑模式切换** - 显示/隐藏拖拽手柄，优化编辑体验
|
||||
|
||||
### 自定义端点管理
|
||||
|
||||
- **多端点配置** - 支持聚合类供应商的多 API 端点配置
|
||||
- **端点输入可见性** - 为所有非官方供应商自动显示端点字段
|
||||
|
||||
### 自定义配置目录（云同步）
|
||||
|
||||
- **自定义存储位置** - 自定义 CC Switch 的配置存储目录
|
||||
- **云同步支持** - 指定到云同步文件夹（Dropbox、OneDrive、iCloud Drive、坚果云等）即可实现跨设备配置自动同步
|
||||
- **独立管理** - 通过 Tauri Store 管理，更好的隔离性和可靠性
|
||||
|
||||
### 使用量查询增强
|
||||
|
||||
- **自动刷新间隔** - 配置定时自动使用量查询，支持自定义间隔时间
|
||||
- **测试脚本 API** - 在执行前验证 JavaScript 使用量查询脚本
|
||||
- **增强模板系统** - 自定义空白模板，支持 access token 和 user ID 参数
|
||||
|
||||
### 配置目录切换（WSL 支持）
|
||||
|
||||
- **目录变更自动同步** - 切换 Claude/Codex 配置目录（如 WSL 环境）时，自动同步当前供应商到新目录，无需手动操作
|
||||
- **后置同步工具** - 统一的 `postChangeSync.ts` 工具，优雅处理错误而不阻塞主流程
|
||||
- **导入配置自动同步** - 配置导入后自动同步，确保立即生效
|
||||
- **智能冲突解决** - 区分"完全成功"和"部分成功"状态，提供精确的用户反馈
|
||||
|
||||
### 配置编辑器改进
|
||||
|
||||
- **JSON 格式化按钮** - 配置编辑器中一键 JSON 格式化
|
||||
- **实时 TOML 验证** - Codex 配置的实时语法验证，带有错误高亮
|
||||
|
||||
### 编辑时加载 Live 配置
|
||||
|
||||
- **保护手动修改** - 编辑当前激活的供应商时，优先显示来自 live 文件的实际生效配置
|
||||
- **双源策略** - 活动供应商自动从 live 配置加载，非活动供应商从 SSOT 加载
|
||||
|
||||
### Claude 配置数据结构增强
|
||||
|
||||
- **细粒度模型配置** - 从双键系统升级到四键系统，以匹配官方最新数据结构
|
||||
- 新增字段：`ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_MODEL`
|
||||
- 替换旧版 `ANTHROPIC_SMALL_FAST_MODEL`，支持自动迁移
|
||||
- 后端在首次读写时自动规范化旧配置，带有智能回退链
|
||||
- UI 从 2 个模型输入字段扩展到 4 个，具有智能默认值
|
||||
- **ANTHROPIC_API_KEY 支持** - 供应商现可使用 `ANTHROPIC_API_KEY` 字段（除 `ANTHROPIC_AUTH_TOKEN` 外）
|
||||
- **模板变量系统** - 支持动态配置替换（如 KAT-Coder 的 `ENDPOINT_ID` 参数）
|
||||
- **端点候选列表** - 预定义端点列表，用于速度测试和端点管理
|
||||
- **视觉主题配置** - 供应商卡片自定义图标和颜色
|
||||
|
||||
### 供应商模型更新
|
||||
|
||||
- **Kimi k2** - 更新到最新的 `kimi-k2-thinking` 模型
|
||||
|
||||
### 新增供应商预设
|
||||
|
||||
新增 5 个供应商预设：
|
||||
|
||||
- **DMXAPI** - 多模型聚合服务
|
||||
- **Azure Codex** - 微软 Azure OpenAI 端点
|
||||
- **AnyRouter** - API 路由服务
|
||||
- **AiHubMix** - AI 模型集合
|
||||
- **MiniMax** - 国产 AI 模型提供商
|
||||
|
||||
### 合作伙伴推广机制
|
||||
|
||||
- 支持生态合作伙伴推广（智谱 GLM Z.ai）
|
||||
- README 中集成赞助商横幅
|
||||
|
||||
---
|
||||
|
||||
## 改进优化
|
||||
|
||||
### 配置与同步
|
||||
|
||||
- **统一错误处理** - 后端全面使用 AppError 与国际化错误消息
|
||||
- **修复 apiKeyUrl 优先级** - 修正 API key URL 解析的优先级顺序
|
||||
- **修复 MCP 同步问题** - 解决同步到另一端功能失效的问题
|
||||
- **导入配置同步** - 修复配置导入后的同步问题
|
||||
- **配置错误处理** - 配置错误时强制退出，防止静默回退和数据丢失
|
||||
|
||||
### UI/UX 增强
|
||||
|
||||
- **独特的供应商图标** - 每个供应商卡片现在都有独特的图标和颜色识别
|
||||
- **统一边框系统** - 所有组件采用一致的边框设计
|
||||
- **拖拽交互** - 推送效果动画和改进的拖拽手柄图标
|
||||
- **增强视觉反馈** - 更好的当前供应商视觉指示
|
||||
- **对话框标准化** - 统一的对话框尺寸和布局一致性
|
||||
- **表单改进** - 优化模型占位符，简化供应商提示，分类特定提示
|
||||
- **使用量内联显示** - 使用量信息移至启用按钮旁边，更好地利用空间
|
||||
|
||||
### 完整国际化
|
||||
|
||||
- **错误消息国际化** - 所有后端错误消息支持中英文
|
||||
- **托盘菜单国际化** - 系统托盘菜单完全国际化
|
||||
- **UI 组件国际化** - 所有面向用户的组件 100% 覆盖
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 配置管理
|
||||
|
||||
- 修复 `apiKeyUrl` 优先级问题
|
||||
- 修复 MCP 同步到另一端功能失效
|
||||
- 修复配置导入后的同步问题
|
||||
- 修复 Codex API Key 自动同步
|
||||
- 修复端点速度测试功能
|
||||
- 修复供应商复制插入位置（现在插入到原供应商旁边）
|
||||
- 修复编辑模式下自定义端点保留问题
|
||||
- 防止配置错误时的静默回退和数据丢失
|
||||
|
||||
### 使用量查询
|
||||
|
||||
- 修复自动查询间隔时间问题
|
||||
- 确保刷新按钮点击时显示加载动画
|
||||
|
||||
### UI 问题
|
||||
|
||||
- 修复名称冲突错误（`get_init_error` 命令）
|
||||
- 修复保存成功后语言设置回滚
|
||||
- 修复语言切换状态重置（依赖循环）
|
||||
- 修复编辑模式按钮对齐
|
||||
|
||||
### 启动问题
|
||||
|
||||
- 配置错误时强制退出（不再静默回退）
|
||||
- 消除导致初始化错误的代码重复
|
||||
|
||||
---
|
||||
|
||||
## 架构重构
|
||||
|
||||
### 后端（Rust）- 5 阶段重构
|
||||
|
||||
1. **阶段 1**：统一错误处理（`AppError` + 国际化错误消息）
|
||||
2. **阶段 2**：命令层按领域拆分（`commands/{provider,mcp,config,settings,plugin,misc}.rs`）
|
||||
3. **阶段 3**：集成测试和事务机制（配置快照 + 失败回滚）
|
||||
4. **阶段 4**：提取 Service 层（`services/{provider,mcp,config,speedtest}.rs`）
|
||||
5. **阶段 5**：并发优化（`RwLock` 替代 `Mutex`，作用域 guard 避免死锁）
|
||||
|
||||
### 前端（React + TypeScript）- 4 阶段重构
|
||||
|
||||
1. **阶段 1**：测试基础设施（vitest + MSW + @testing-library/react）
|
||||
2. **阶段 2**：提取自定义 hooks（`useProviderActions`、`useMcpActions`、`useSettings`、`useImportExport` 等）
|
||||
3. **阶段 3**：组件拆分和业务逻辑提取
|
||||
4. **阶段 4**：代码清理和格式化统一
|
||||
|
||||
### 测试体系
|
||||
|
||||
- **Hooks 单元测试** - 所有自定义 hooks 100% 覆盖
|
||||
- **集成测试** - 关键流程覆盖（App、SettingsDialog、MCP 面板）
|
||||
- **MSW 模拟** - 后端 API 模拟确保测试独立性
|
||||
- **测试基础设施** - vitest + MSW + @testing-library/react
|
||||
|
||||
### 代码质量
|
||||
|
||||
- **统一参数格式** - 所有 Tauri 命令迁移到 camelCase（Tauri 2 规范）
|
||||
- **语义清晰** - `AppType` 重命名为 `AppId` 以获得更好的语义
|
||||
- **集中解析** - 使用 `FromStr` trait 统一 `app` 参数解析
|
||||
- **DRY 违规清理** - 消除整个代码库中的代码重复
|
||||
- **死代码移除** - 移除未使用的 `missing_param` 辅助函数、废弃的 `tauri-api.ts`、冗余的 `KimiModelSelector`
|
||||
|
||||
---
|
||||
|
||||
## 内部优化（用户无感知）
|
||||
|
||||
### 移除遗留迁移逻辑
|
||||
|
||||
v3.6.0 移除了 v1 配置自动迁移和副本文件扫描逻辑：
|
||||
|
||||
- **影响**：提升启动性能，代码更简洁
|
||||
- **兼容性**：v2 格式配置完全兼容，无需任何操作
|
||||
- **注意**：从 v3.1.0 或更早版本升级的用户，请先升级到 v3.2.x 或 v3.5.x 进行一次性迁移，然后再升级到 v3.6.0
|
||||
|
||||
### 命令参数标准化
|
||||
|
||||
后端统一使用 `app` 参数（取值：`claude` 或 `codex`）：
|
||||
|
||||
- **影响**：代码更规范，错误提示更友好
|
||||
- **兼容性**：前端已完全适配，用户无需关心此变更
|
||||
|
||||
---
|
||||
|
||||
## 依赖更新
|
||||
|
||||
- 更新到 **Tauri 2.8.x**
|
||||
- 更新到 **TailwindCSS 4.x**
|
||||
- 更新到 **TanStack Query v5.90.x**
|
||||
- 保持 **React 18.2.x** 和 **TypeScript 5.3.x**
|
||||
|
||||
---
|
||||
|
||||
## 安装方式
|
||||
|
||||
### macOS
|
||||
|
||||
**通过 Homebrew 安装（推荐）：**
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
**手动下载：**
|
||||
|
||||
- 从下方 [Assets](#assets) 下载 `CC-Switch-v3.6.0-macOS.zip`
|
||||
|
||||
> **注意**：由于作者没有苹果开发者账号，首次打开可能出现"未知开发者"警告。请前往"系统设置" → "隐私与安全性" → 点击"仍要打开"
|
||||
|
||||
### Windows
|
||||
|
||||
- **安装包**：`CC-Switch-v3.6.0-Windows.msi`
|
||||
- **便携版**：`CC-Switch-v3.6.0-Windows-Portable.zip`
|
||||
|
||||
### Linux
|
||||
|
||||
- **AppImage**：`CC-Switch-v3.6.0-Linux.AppImage`
|
||||
- **Debian**：`CC-Switch-v3.6.0-Linux.deb`
|
||||
|
||||
---
|
||||
|
||||
## 文档
|
||||
|
||||
- [中文文档](https://github.com/farion1231/cc-switch/blob/main/README_ZH.md)
|
||||
- [English Documentation](https://github.com/farion1231/cc-switch/blob/main/README.md)
|
||||
- [完整更新日志](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## 致谢
|
||||
|
||||
特别感谢**智谱 AI** 通过 GLM CODING PLAN 赞助本项目！
|
||||
|
||||
---
|
||||
|
||||
**完整变更记录**: https://github.com/farion1231/cc-switch/compare/v3.5.1...v3.6.0
|
||||
@@ -0,0 +1,391 @@
|
||||
# CC Switch v3.6.1
|
||||
|
||||
> Stability improvements and user experience optimization (based on v3.6.0)
|
||||
|
||||
**[中文更新说明 Chinese Documentation →](https://github.com/farion1231/cc-switch/blob/main/docs/release-notes/v3.6.1-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## 📦 What's New in v3.6.1 (2025-11-10)
|
||||
|
||||
This release focuses on **user experience optimization** and **configuration parsing robustness**, fixing several critical bugs and enhancing the usage query system.
|
||||
|
||||
### ✨ New Features
|
||||
|
||||
#### Usage Query System Enhancements
|
||||
|
||||
- **Credential Decoupling** - Usage queries can now use independent API Key and Base URL, no longer dependent on provider configuration
|
||||
- Support for different query endpoints and authentication methods
|
||||
- Automatically displays credential input fields based on template type
|
||||
- General template: API Key + Base URL
|
||||
- NewAPI template: Base URL + Access Token + User ID
|
||||
- Custom template: Fully customizable
|
||||
- **UI Component Upgrade** - Replaced native checkbox with shadcn/ui Switch component for modern experience
|
||||
- **Form Unification** - Unified use of shadcn/ui Input components, consistent styling with the application
|
||||
- **Password Visibility Toggle** - Added show/hide password functionality (API Key, Access Token)
|
||||
|
||||
#### Form Validation Infrastructure
|
||||
|
||||
- **Common Schema Library** - New JSON/TOML generic validators to reduce code duplication
|
||||
- `jsonConfigSchema`: Generic JSON object validator
|
||||
- `tomlConfigSchema`: Generic TOML format validator
|
||||
- `mcpJsonConfigSchema`: MCP-specific JSON validator
|
||||
- **MCP Conditional Field Validation** - Strict type checking
|
||||
- stdio type requires `command` field
|
||||
- http type requires `url` field
|
||||
|
||||
#### Partner Integration
|
||||
|
||||
- **PackyCode** - New official partner
|
||||
- Added to Claude and Codex provider presets
|
||||
- 10% discount promotion support
|
||||
- New logo and partner identification
|
||||
|
||||
---
|
||||
|
||||
### 🔧 Improvements
|
||||
|
||||
#### User Experience
|
||||
|
||||
- **Drag Sort Sync** - Tray menu order now syncs with drag-and-drop sorting in real-time
|
||||
- **Enhanced Error Notifications** - Provider switch failures now display copyable error messages
|
||||
- **Removed Misleading Placeholders** - Deleted example text from model input fields to avoid user confusion
|
||||
- **Auto-fill Base URL** - All non-official provider categories automatically populate the Base URL input field
|
||||
|
||||
#### Configuration Parsing
|
||||
|
||||
- **CJK Quote Normalization** - Automatically handles IME-input fullwidth quotes to prevent TOML parsing errors
|
||||
- Supports automatic conversion of Chinese quotes (" " ' ') to ASCII quotes
|
||||
- Applied in TOML input handlers
|
||||
- Disabled browser auto-correction in Textarea component
|
||||
- **Preserve Custom Fields** - Editing Codex MCP TOML configuration now preserves unknown fields
|
||||
- Supports extension fields like timeout_ms, retry_count
|
||||
- Forward compatibility with future MCP protocol extensions
|
||||
|
||||
---
|
||||
|
||||
### 🐛 Bug Fixes
|
||||
|
||||
#### Critical Fixes
|
||||
|
||||
- **Fixed usage script panel white screen crash** - FormLabel component missing FormField context caused entire app to crash
|
||||
- Replaced with standalone Label component
|
||||
- Root cause: FormLabel internally calls useFormField() hook which requires FormFieldContext
|
||||
- **Fixed CJK input quote parsing failure** - IME-input fullwidth quotes caused TOML parsing errors
|
||||
- Added textNormalization utility function
|
||||
- Automatically normalizes quotes before parsing
|
||||
- **Fixed drag sort tray desync** (#179) - Tray menu order not updated after drag-and-drop sorting
|
||||
- Automatically calls updateTrayMenu after sorting completes
|
||||
- Ensures UI and tray menu stay consistent
|
||||
- **Fixed MCP custom field loss** - Custom fields silently dropped when editing Codex MCP configuration
|
||||
- Uses spread operator to retain all fields
|
||||
- Preserves unknown fields in normalizeServerConfig
|
||||
|
||||
#### Stability Improvements
|
||||
|
||||
- **Error Isolation** - Tray menu update failures no longer affect main operations
|
||||
- Decoupled tray update errors from main operations
|
||||
- Provides warning when main operation succeeds but tray update fails
|
||||
- **Safe Pattern Matching** - Replaced `unwrap()` with safe pattern matching
|
||||
- Avoids panic-induced app crashes
|
||||
- Tray menu event handling uses match patterns
|
||||
- **Import Config Classification** - Importing from default config now automatically sets category to `custom`
|
||||
- Avoids imported configs being mistaken for official presets
|
||||
- Provides clearer configuration source identification
|
||||
|
||||
---
|
||||
|
||||
### 📊 Technical Statistics
|
||||
|
||||
```
|
||||
Commits: 17 commits
|
||||
Code Changes: 31 files
|
||||
- Additions: 1,163 lines
|
||||
- Deletions: 811 lines
|
||||
- Net Growth: +352 lines
|
||||
Contributors: Jason (16), ZyphrZero (1)
|
||||
```
|
||||
|
||||
**By Module**:
|
||||
- UI/User Interface: 3 commits
|
||||
- Usage Query System: 3 commits
|
||||
- Configuration Parsing: 2 commits
|
||||
- Form Validation: 1 commit
|
||||
- Other Improvements: 8 commits
|
||||
|
||||
---
|
||||
|
||||
### 📥 Installation
|
||||
|
||||
#### macOS
|
||||
|
||||
**Via Homebrew (Recommended):**
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
**Manual Download:**
|
||||
|
||||
- Download `CC-Switch-v3.6.1-macOS.zip` from [Assets](#assets) below
|
||||
|
||||
> **Note**: Due to lack of Apple Developer account, you may see "unidentified developer" warning. Go to System Settings → Privacy & Security → Click "Open Anyway"
|
||||
|
||||
#### Windows
|
||||
|
||||
- **Installer**: `CC-Switch-v3.6.1-Windows.msi`
|
||||
- **Portable**: `CC-Switch-v3.6.1-Windows-Portable.zip`
|
||||
|
||||
#### Linux
|
||||
|
||||
- **AppImage**: `CC-Switch-v3.6.1-Linux.AppImage`
|
||||
- **Debian**: `CC-Switch-v3.6.1-Linux.deb`
|
||||
|
||||
---
|
||||
|
||||
### 📚 Documentation
|
||||
|
||||
- [中文文档 (Chinese)](https://github.com/farion1231/cc-switch/blob/main/README_ZH.md)
|
||||
- [English Documentation](https://github.com/farion1231/cc-switch/blob/main/README.md)
|
||||
- [完整更新日志 (Full Changelog)](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
### 🙏 Acknowledgments
|
||||
|
||||
Special thanks to:
|
||||
- **Zhipu AI** - For sponsoring this project with GLM CODING PLAN
|
||||
- **PackyCode** - New official partner
|
||||
- **ZyphrZero** - For contributing tray menu sync fix (#179)
|
||||
|
||||
---
|
||||
|
||||
**Full Changelog**: https://github.com/farion1231/cc-switch/compare/v3.6.0...v3.6.1
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## 📜 v3.6.0 Complete Feature Review
|
||||
|
||||
> Content below is from v3.6.0 (2025-11-07), helping you understand the complete feature set
|
||||
|
||||
<details>
|
||||
<summary><b>Click to expand v3.6.0 detailed content →</b></summary>
|
||||
|
||||
## What's New
|
||||
|
||||
### Edit Mode & Provider Management
|
||||
|
||||
- **Provider Duplication** - Quickly duplicate existing provider configurations to create variants with one click
|
||||
- **Manual Sorting** - Drag and drop to reorder providers, with visual push effect animations. Thanks to @ZyphrZero
|
||||
- **Edit Mode Toggle** - Show/hide drag handles to optimize editing experience
|
||||
|
||||
### Custom Endpoint Management
|
||||
|
||||
- **Multi-Endpoint Configuration** - Support for aggregator providers with multiple API endpoints
|
||||
- **Endpoint Input Visibility** - Shows endpoint field for all non-official providers automatically
|
||||
|
||||
### Usage Query Enhancements
|
||||
|
||||
- **Auto-Refresh Interval** - Configure periodic automatic usage queries with customizable intervals
|
||||
- **Test Script API** - Validate JavaScript usage query scripts before execution
|
||||
- **Enhanced Templates** - Custom blank templates with access token and user ID parameter support
|
||||
Thanks to @Sirhexs
|
||||
|
||||
### Custom Configuration Directory (Cloud Sync)
|
||||
|
||||
- **Customizable Storage Location** - Customize CC Switch's configuration storage directory
|
||||
- **Cloud Sync Support** - Point to cloud sync folders (Dropbox, OneDrive, iCloud Drive, etc.) to enable automatic config synchronization across devices
|
||||
- **Independent Management** - Managed via Tauri Store for better isolation and reliability
|
||||
Thanks to @ZyphrZero
|
||||
|
||||
### Configuration Directory Switching (WSL Support)
|
||||
|
||||
- **Auto-Sync on Directory Change** - When switching Claude/Codex config directories (e.g., WSL environment), automatically sync current provider to the new directory without manual operation
|
||||
- **Post-Change Sync Utility** - Unified `postChangeSync.ts` utility for graceful error handling without blocking main flow
|
||||
- **Import Config Auto-Sync** - Automatically sync after config import to ensure immediate effectiveness
|
||||
- **Smart Conflict Resolution** - Distinguishes "fully successful" and "partially successful" states for precise user feedback
|
||||
|
||||
### Configuration Editor Improvements
|
||||
|
||||
- **JSON Format Button** - One-click JSON formatting in configuration editors
|
||||
- **Real-Time TOML Validation** - Live syntax validation for Codex configuration with error highlighting
|
||||
|
||||
### Load Live Config When Editing
|
||||
|
||||
- **Protect Manual Modifications** - When editing the currently active provider, prioritize displaying the actual effective configuration from live files
|
||||
- **Dual-Source Strategy** - Automatically loads from live config for active provider, SSOT for inactive ones
|
||||
|
||||
### Claude Configuration Data Structure Enhancements
|
||||
|
||||
- **Granular Model Configuration** - Migrated from dual-key to quad-key system for better model tier differentiation
|
||||
- New fields: `ANTHROPIC_DEFAULT_HAIKU_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_MODEL`
|
||||
- Replaces legacy `ANTHROPIC_SMALL_FAST_MODEL` with automatic migration
|
||||
- Backend normalizes old configs on first read/write with smart fallback chain
|
||||
- UI expanded from 2 to 4 model input fields with intelligent defaults
|
||||
- **ANTHROPIC_API_KEY Support** - Providers can now use `ANTHROPIC_API_KEY` field in addition to `ANTHROPIC_AUTH_TOKEN`
|
||||
- **Template Variable System** - Support for dynamic configuration replacement (e.g., KAT-Coder's `ENDPOINT_ID` parameter)
|
||||
- **Endpoint Candidates** - Predefined endpoint list for speed testing and endpoint management
|
||||
- **Visual Theme Configuration** - Custom icons and colors for provider cards
|
||||
|
||||
### Updated Provider Models
|
||||
|
||||
- **Kimi k2** - Updated to latest `kimi-k2-thinking` model
|
||||
|
||||
### New Provider Presets
|
||||
|
||||
Added 5 new provider presets:
|
||||
|
||||
- **DMXAPI** - Multi-model aggregation service
|
||||
- **Azure Codex** - Microsoft Azure OpenAI endpoint
|
||||
- **AnyRouter** - None-profit routing service
|
||||
- **AiHubMix** - Multi-model aggregation service
|
||||
- **MiniMax** - Open source AI model provider
|
||||
|
||||
### Partner Promotion Mechanism
|
||||
|
||||
- Support for ecosystem partner promotion (Zhipu GLM Z.ai)
|
||||
- Sponsored banner integration in README
|
||||
|
||||
---
|
||||
|
||||
## Improvements
|
||||
|
||||
### Configuration & Sync
|
||||
|
||||
- **Unified Error Handling** - AppError with internationalized error messages throughout backend
|
||||
- **Fixed apiKeyUrl Priority** - Correct priority order for API key URL resolution
|
||||
- **Fixed MCP Sync Issues** - Resolved sync-to-other-side functionality failures
|
||||
- **Import Config Sync** - Fixed sync issues after configuration import
|
||||
- **Config Error Handling** - Force exit on config error to prevent silent fallback and data loss
|
||||
|
||||
### UI/UX Enhancements
|
||||
|
||||
- **Unique Provider Icons** - Each provider card now has unique icons and color identification
|
||||
- **Unified Border System** - Consistent border design across all components
|
||||
- **Drag Interaction** - Push effect animation and improved drag handle icons
|
||||
- **Enhanced Visual Feedback** - Better current provider visual indication
|
||||
- **Dialog Standardization** - Unified dialog sizes and layout consistency
|
||||
- **Form Improvements** - Optimized model placeholders, simplified provider hints, category-specific hints
|
||||
- **Usage Display Inline** - Usage info moved next to enable button for better space utilization
|
||||
|
||||
### Complete Internationalization
|
||||
|
||||
- **Error Messages i18n** - All backend error messages support Chinese/English
|
||||
- **Tray Menu i18n** - System tray menu fully internationalized
|
||||
- **UI Components i18n** - 100% coverage across all user-facing components
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Configuration Management
|
||||
|
||||
- Fixed `apiKeyUrl` priority issue
|
||||
- Fixed MCP sync-to-other-side functionality failure
|
||||
- Fixed sync issues after config import
|
||||
- Fixed Codex API Key auto-sync
|
||||
- Fixed endpoint speed test functionality
|
||||
- Fixed provider duplicate insertion position (now inserts next to original)
|
||||
- Fixed custom endpoint preservation in edit mode
|
||||
- Prevent silent fallback and data loss on config error
|
||||
|
||||
### Usage Query
|
||||
|
||||
- Fixed auto-query interval timing issue
|
||||
- Ensured refresh button shows loading animation on click
|
||||
|
||||
### UI Issues
|
||||
|
||||
- Fixed name collision error (`get_init_error` command)
|
||||
- Fixed language setting rollback after successful save
|
||||
- Fixed language switch state reset (dependency cycle)
|
||||
- Fixed edit mode button alignment
|
||||
|
||||
### Startup Issues
|
||||
|
||||
- Force exit on config error (no silent fallback)
|
||||
- Eliminated code duplication causing initialization errors
|
||||
|
||||
---
|
||||
|
||||
## Architecture Refactoring
|
||||
|
||||
### Backend (Rust) - 5 Phase Refactoring
|
||||
|
||||
1. **Phase 1**: Unified error handling (`AppError` + i18n error messages)
|
||||
2. **Phase 2**: Command layer split by domain (`commands/{provider,mcp,config,settings,plugin,misc}.rs`)
|
||||
3. **Phase 3**: Integration tests and transaction mechanism (config snapshot + failure rollback)
|
||||
4. **Phase 4**: Extracted Service layer (`services/{provider,mcp,config,speedtest}.rs`)
|
||||
5. **Phase 5**: Concurrency optimization (`RwLock` instead of `Mutex`, scoped guard to avoid deadlock)
|
||||
|
||||
### Frontend (React + TypeScript) - 4 Stage Refactoring
|
||||
|
||||
1. **Stage 1**: Test infrastructure (vitest + MSW + @testing-library/react)
|
||||
2. **Stage 2**: Extracted custom hooks (`useProviderActions`, `useMcpActions`, `useSettings`, `useImportExport`, etc.)
|
||||
3. **Stage 3**: Component splitting and business logic extraction
|
||||
4. **Stage 4**: Code cleanup and formatting unification
|
||||
|
||||
### Testing System
|
||||
|
||||
- **Hooks Unit Tests** - 100% coverage for all custom hooks
|
||||
- **Integration Tests** - Coverage for key processes (App, SettingsDialog, MCP Panel)
|
||||
- **MSW Mocking** - Backend API mocking to ensure test independence
|
||||
- **Test Infrastructure** - vitest + MSW + @testing-library/react
|
||||
|
||||
### Code Quality
|
||||
|
||||
- **Unified Parameter Format** - All Tauri commands migrated to camelCase (Tauri 2 specification)
|
||||
- **Semantic Clarity** - `AppType` renamed to `AppId` for better semantics
|
||||
- **Centralized Parsing** - Unified `app` parameter parsing with `FromStr` trait
|
||||
- **DRY Violations Cleanup** - Eliminated code duplication throughout codebase
|
||||
- **Dead Code Removal** - Removed unused `missing_param` helper, deprecated `tauri-api.ts`, redundant `KimiModelSelector`
|
||||
|
||||
---
|
||||
|
||||
## Internal Optimizations (User Transparent)
|
||||
|
||||
### Removed Legacy Migration Logic
|
||||
|
||||
v3.6.0 removed v1 config auto-migration and copy file scanning logic:
|
||||
|
||||
- **Impact**: Improved startup performance, cleaner codebase
|
||||
- **Compatibility**: v2 format configs fully compatible, no action required
|
||||
- **Note**: Users upgrading from v3.1.0 or earlier should first upgrade to v3.2.x or v3.5.x for one-time migration, then upgrade to v3.6.0
|
||||
|
||||
### Command Parameter Standardization
|
||||
|
||||
Backend unified to use `app` parameter (values: `claude` or `codex`):
|
||||
|
||||
- **Impact**: More standardized code, friendlier error prompts
|
||||
- **Compatibility**: Frontend fully adapted, users don't need to care about this change
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Updated to **Tauri 2.8.x**
|
||||
- Updated to **TailwindCSS 4.x**
|
||||
- Updated to **TanStack Query v5.90.x**
|
||||
- Maintained **React 18.2.x** and **TypeScript 5.3.x**
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🌟 About CC Switch
|
||||
|
||||
CC Switch is a cross-platform desktop application for managing and switching between different provider configurations for Claude Code and Codex. Built with Tauri 2.0 + React 18 + TypeScript, supporting Windows, macOS, and Linux.
|
||||
|
||||
**Core Features**:
|
||||
- 🔄 One-click switching between multiple AI providers
|
||||
- 📦 Support for both Claude Code and Codex applications
|
||||
- 🎨 Modern UI with complete Chinese/English internationalization
|
||||
- 🔐 Local storage, secure and reliable data
|
||||
- ☁️ Support for cloud sync configurations
|
||||
- 🧩 Unified MCP server management
|
||||
|
||||
---
|
||||
|
||||
**Project Repository**: https://github.com/farion1231/cc-switch
|
||||
@@ -0,0 +1,389 @@
|
||||
# CC Switch v3.6.1
|
||||
|
||||
> 稳定性提升与用户体验优化（基于 v3.6.0）
|
||||
|
||||
**[English Version →](v3.6.1-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 📦 v3.6.1 新增内容 (2025-11-10)
|
||||
|
||||
本次更新主要聚焦于**用户体验优化**和**配置解析健壮性**，修复了多个关键 Bug，并增强了用量查询系统。
|
||||
|
||||
### ✨ 新增功能
|
||||
|
||||
#### 用量查询系统增强
|
||||
|
||||
- **凭证解耦** - 用量查询可使用独立的 API Key 和 Base URL，不再依赖供应商配置
|
||||
- 支持不同的查询端点和认证方式
|
||||
- 根据模板类型自动显示对应的凭证输入框
|
||||
- General 模板：API Key + Base URL
|
||||
- NewAPI 模板：Base URL + Access Token + User ID
|
||||
- Custom 模板：完全自定义
|
||||
- **UI 组件升级** - 使用 shadcn/ui Switch 替代原生 checkbox，体验更现代
|
||||
- **表单统一化** - 统一使用 shadcn/ui 输入组件，样式与应用保持一致
|
||||
- **密码显示切换** - 添加查看/隐藏密码功能（API Key、Access Token）
|
||||
|
||||
#### 表单验证基础设施
|
||||
|
||||
- **通用 Schema 库** - 新增 JSON/TOML 通用验证器，减少重复代码
|
||||
- `jsonConfigSchema`：通用 JSON 对象验证器
|
||||
- `tomlConfigSchema`：通用 TOML 格式验证器
|
||||
- `mcpJsonConfigSchema`：MCP 专用 JSON 验证器
|
||||
- **MCP 条件字段验证** - 严格的类型检查
|
||||
- stdio 类型强制要求 `command` 字段
|
||||
- http 类型强制要求 `url` 字段
|
||||
|
||||
#### 合作伙伴集成
|
||||
|
||||
- **PackyCode** - 新增官方合作伙伴
|
||||
- 添加到 Claude 和 Codex 供应商预设
|
||||
- 支持 10% 折扣优惠（促销信息集成）
|
||||
- 新增 Logo 和合作伙伴标识
|
||||
|
||||
---
|
||||
|
||||
### 🔧 改进优化
|
||||
|
||||
#### 用户体验
|
||||
|
||||
- **拖拽排序同步** - 托盘菜单顺序实时同步拖拽排序结果
|
||||
- **错误通知增强** - 切换供应商失败时显示可复制的错误信息
|
||||
- **移除误导性占位符** - 删除模型输入框的示例文本，避免用户混淆
|
||||
- **Base URL 自动填充** - 所有非官方供应商类别自动填充 Base URL 输入框
|
||||
|
||||
#### 配置解析
|
||||
|
||||
- **中文引号规范化** - 自动处理 IME 输入的全角引号，防止 TOML 解析错误
|
||||
- 支持中文引号（" " ' '）自动转换为 ASCII 引号
|
||||
- 在 TOML 输入处理器中应用
|
||||
- Textarea 组件禁用浏览器自动纠正
|
||||
- **自定义字段保留** - 编辑 Codex MCP TOML 配置时保留未知字段
|
||||
- 支持 timeout_ms、retry_count 等扩展字段
|
||||
- 向前兼容未来的 MCP 协议扩展
|
||||
|
||||
---
|
||||
|
||||
### 🐛 Bug 修复
|
||||
|
||||
#### 关键修复
|
||||
|
||||
- **修复用量脚本面板白屏崩溃** - FormLabel 组件缺少 FormField context 导致整个应用崩溃
|
||||
- 替换为独立的 Label 组件
|
||||
- 根本原因：FormLabel 内部调用 useFormField() hook 需要 FormFieldContext
|
||||
- **修复中文输入法引号解析失败** - IME 输入的全角引号导致 TOML 解析错误
|
||||
- 新增 textNormalization 工具函数
|
||||
- 在解析前自动规范化引号
|
||||
- **修复拖拽排序托盘不同步** (#179) - 拖拽排序后托盘菜单顺序未更新
|
||||
- 在排序完成后自动调用 updateTrayMenu
|
||||
- 确保 UI 和托盘菜单保持一致
|
||||
- **修复 MCP 自定义字段丢失** - 编辑 Codex MCP 配置时自定义字段被静默丢弃
|
||||
- 使用 spread 操作符保留所有字段
|
||||
- normalizeServerConfig 中保留未知字段
|
||||
|
||||
#### 稳定性改进
|
||||
|
||||
- **错误隔离** - 托盘菜单更新失败不再影响主操作流程
|
||||
- 将托盘更新错误与主操作解耦
|
||||
- 主操作成功但托盘更新失败时给出警告
|
||||
- **安全模式匹配** - 替换 `unwrap()` 为安全的 pattern matching
|
||||
- 避免 panic 导致应用崩溃
|
||||
- 托盘菜单事件处理使用 match 模式
|
||||
- **导入配置分类** - 从默认配置导入时自动设置 category 为 `custom`
|
||||
- 避免导入的配置被误认为官方预设
|
||||
- 提供更清晰的配置来源标识
|
||||
|
||||
---
|
||||
|
||||
### 📊 技术统计
|
||||
|
||||
```
|
||||
提交数: 17 commits
|
||||
代码变更: 31 个文件
|
||||
- 新增: 1,163 行
|
||||
- 删除: 811 行
|
||||
- 净增长: +352 行
|
||||
贡献者: Jason (16), ZyphrZero (1)
|
||||
```
|
||||
|
||||
**按模块分类**：
|
||||
- UI/用户界面：3 commits
|
||||
- 用量查询系统：3 commits
|
||||
- 配置解析：2 commits
|
||||
- 表单验证：1 commit
|
||||
- 其他改进：8 commits
|
||||
|
||||
---
|
||||
|
||||
### 📥 安装方式
|
||||
|
||||
#### macOS
|
||||
|
||||
**通过 Homebrew 安装（推荐）：**
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
**手动下载：**
|
||||
|
||||
- 从下方 [Assets](#assets) 下载 `CC-Switch-v3.6.1-macOS.zip`
|
||||
|
||||
> **注意**：由于作者没有苹果开发者账号，首次打开可能出现"未知开发者"警告。请前往"系统设置" → "隐私与安全性" → 点击"仍要打开"
|
||||
|
||||
#### Windows
|
||||
|
||||
- **安装包**：`CC-Switch-v3.6.1-Windows.msi`
|
||||
- **便携版**：`CC-Switch-v3.6.1-Windows-Portable.zip`
|
||||
|
||||
#### Linux
|
||||
|
||||
- **AppImage**：`CC-Switch-v3.6.1-Linux.AppImage`
|
||||
- **Debian**：`CC-Switch-v3.6.1-Linux.deb`
|
||||
|
||||
---
|
||||
|
||||
### 📚 文档
|
||||
|
||||
- [中文文档](https://github.com/farion1231/cc-switch/blob/main/README_ZH.md)
|
||||
- [English Documentation](https://github.com/farion1231/cc-switch/blob/main/README.md)
|
||||
- [完整更新日志](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
### 🙏 致谢
|
||||
|
||||
特别感谢：
|
||||
- **智谱 AI** - 通过 GLM CODING PLAN 赞助本项目
|
||||
- **PackyCode** - 新加入的官方合作伙伴
|
||||
- **ZyphrZero** - 贡献托盘菜单同步修复 (#179)
|
||||
|
||||
---
|
||||
|
||||
**完整变更记录**: https://github.com/farion1231/cc-switch/compare/v3.6.0...v3.6.1
|
||||
|
||||
---
|
||||
---
|
||||
|
||||
## 📜 v3.6.0 完整功能回顾
|
||||
|
||||
> 以下内容来自 v3.6.0 (2025-11-07)，帮助您了解完整的功能集
|
||||
|
||||
<details>
|
||||
<summary><b>点击展开 v3.6.0 的详细内容 →</b></summary>
|
||||
|
||||
## 新增功能
|
||||
|
||||
### 编辑模式与供应商管理
|
||||
|
||||
- **供应商复制功能** - 一键快速复制现有供应商配置，轻松创建变体配置
|
||||
- **手动排序功能** - 通过拖拽对供应商进行重新排序，带有视觉推送效果动画
|
||||
- **编辑模式切换** - 显示/隐藏拖拽手柄，优化编辑体验
|
||||
|
||||
### 自定义端点管理
|
||||
|
||||
- **多端点配置** - 支持聚合类供应商的多 API 端点配置
|
||||
- **端点输入可见性** - 为所有非官方供应商自动显示端点字段
|
||||
|
||||
### 自定义配置目录（云同步）
|
||||
|
||||
- **自定义存储位置** - 自定义 CC Switch 的配置存储目录
|
||||
- **云同步支持** - 指定到云同步文件夹（Dropbox、OneDrive、iCloud Drive、坚果云等）即可实现跨设备配置自动同步
|
||||
- **独立管理** - 通过 Tauri Store 管理，更好的隔离性和可靠性
|
||||
|
||||
### 使用量查询增强
|
||||
|
||||
- **自动刷新间隔** - 配置定时自动使用量查询，支持自定义间隔时间
|
||||
- **测试脚本 API** - 在执行前验证 JavaScript 使用量查询脚本
|
||||
- **增强模板系统** - 自定义空白模板，支持 access token 和 user ID 参数
|
||||
|
||||
### 配置目录切换（WSL 支持）
|
||||
|
||||
- **目录变更自动同步** - 切换 Claude/Codex 配置目录（如 WSL 环境）时，自动同步当前供应商到新目录，无需手动操作
|
||||
- **后置同步工具** - 统一的 `postChangeSync.ts` 工具，优雅处理错误而不阻塞主流程
|
||||
- **导入配置自动同步** - 配置导入后自动同步，确保立即生效
|
||||
- **智能冲突解决** - 区分"完全成功"和"部分成功"状态，提供精确的用户反馈
|
||||
|
||||
### 配置编辑器改进
|
||||
|
||||
- **JSON 格式化按钮** - 配置编辑器中一键 JSON 格式化
|
||||
- **实时 TOML 验证** - Codex 配置的实时语法验证，带有错误高亮
|
||||
|
||||
### 编辑时加载 Live 配置
|
||||
|
||||
- **保护手动修改** - 编辑当前激活的供应商时，优先显示来自 live 文件的实际生效配置
|
||||
- **双源策略** - 活动供应商自动从 live 配置加载，非活动供应商从 SSOT 加载
|
||||
|
||||
### Claude 配置数据结构增强
|
||||
|
||||
- **细粒度模型配置** - 从双键系统升级到四键系统，以匹配官方最新数据结构
|
||||
- 新增字段：`ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_MODEL`
|
||||
- 替换旧版 `ANTHROPIC_SMALL_FAST_MODEL`，支持自动迁移
|
||||
- 后端在首次读写时自动规范化旧配置，带有智能回退链
|
||||
- UI 从 2 个模型输入字段扩展到 4 个，具有智能默认值
|
||||
- **ANTHROPIC_API_KEY 支持** - 供应商现可使用 `ANTHROPIC_API_KEY` 字段（除 `ANTHROPIC_AUTH_TOKEN` 外）
|
||||
- **模板变量系统** - 支持动态配置替换（如 KAT-Coder 的 `ENDPOINT_ID` 参数）
|
||||
- **端点候选列表** - 预定义端点列表，用于速度测试和端点管理
|
||||
- **视觉主题配置** - 供应商卡片自定义图标和颜色
|
||||
|
||||
### 供应商模型更新
|
||||
|
||||
- **Kimi k2** - 更新到最新的 `kimi-k2-thinking` 模型
|
||||
|
||||
### 新增供应商预设
|
||||
|
||||
新增 5 个供应商预设：
|
||||
|
||||
- **DMXAPI** - 多模型聚合服务
|
||||
- **Azure Codex** - 微软 Azure OpenAI 端点
|
||||
- **AnyRouter** - API 路由服务
|
||||
- **AiHubMix** - AI 模型集合
|
||||
- **MiniMax** - 国产 AI 模型提供商
|
||||
|
||||
### 合作伙伴推广机制
|
||||
|
||||
- 支持生态合作伙伴推广（智谱 GLM Z.ai）
|
||||
- README 中集成赞助商横幅
|
||||
|
||||
---
|
||||
|
||||
## 改进优化
|
||||
|
||||
### 配置与同步
|
||||
|
||||
- **统一错误处理** - 后端全面使用 AppError 与国际化错误消息
|
||||
- **修复 apiKeyUrl 优先级** - 修正 API key URL 解析的优先级顺序
|
||||
- **修复 MCP 同步问题** - 解决同步到另一端功能失效的问题
|
||||
- **导入配置同步** - 修复配置导入后的同步问题
|
||||
- **配置错误处理** - 配置错误时强制退出，防止静默回退和数据丢失
|
||||
|
||||
### UI/UX 增强
|
||||
|
||||
- **独特的供应商图标** - 每个供应商卡片现在都有独特的图标和颜色识别
|
||||
- **统一边框系统** - 所有组件采用一致的边框设计
|
||||
- **拖拽交互** - 推送效果动画和改进的拖拽手柄图标
|
||||
- **增强视觉反馈** - 更好的当前供应商视觉指示
|
||||
- **对话框标准化** - 统一的对话框尺寸和布局一致性
|
||||
- **表单改进** - 优化模型占位符，简化供应商提示，分类特定提示
|
||||
- **使用量内联显示** - 使用量信息移至启用按钮旁边，更好地利用空间
|
||||
|
||||
### 完整国际化
|
||||
|
||||
- **错误消息国际化** - 所有后端错误消息支持中英文
|
||||
- **托盘菜单国际化** - 系统托盘菜单完全国际化
|
||||
- **UI 组件国际化** - 所有面向用户的组件 100% 覆盖
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 配置管理
|
||||
|
||||
- 修复 `apiKeyUrl` 优先级问题
|
||||
- 修复 MCP 同步到另一端功能失效
|
||||
- 修复配置导入后的同步问题
|
||||
- 修复 Codex API Key 自动同步
|
||||
- 修复端点速度测试功能
|
||||
- 修复供应商复制插入位置（现在插入到原供应商旁边）
|
||||
- 修复编辑模式下自定义端点保留问题
|
||||
- 防止配置错误时的静默回退和数据丢失
|
||||
|
||||
### 使用量查询
|
||||
|
||||
- 修复自动查询间隔时间问题
|
||||
- 确保刷新按钮点击时显示加载动画
|
||||
|
||||
### UI 问题
|
||||
|
||||
- 修复名称冲突错误（`get_init_error` 命令）
|
||||
- 修复保存成功后语言设置回滚
|
||||
- 修复语言切换状态重置（依赖循环）
|
||||
- 修复编辑模式按钮对齐
|
||||
|
||||
### 启动问题
|
||||
|
||||
- 配置错误时强制退出（不再静默回退）
|
||||
- 消除导致初始化错误的代码重复
|
||||
|
||||
---
|
||||
|
||||
## 架构重构
|
||||
|
||||
### 后端（Rust）- 5 阶段重构
|
||||
|
||||
1. **阶段 1**：统一错误处理（`AppError` + 国际化错误消息）
|
||||
2. **阶段 2**：命令层按领域拆分（`commands/{provider,mcp,config,settings,plugin,misc}.rs`）
|
||||
3. **阶段 3**：集成测试和事务机制（配置快照 + 失败回滚）
|
||||
4. **阶段 4**：提取 Service 层（`services/{provider,mcp,config,speedtest}.rs`）
|
||||
5. **阶段 5**：并发优化（`RwLock` 替代 `Mutex`，作用域 guard 避免死锁）
|
||||
|
||||
### 前端（React + TypeScript）- 4 阶段重构
|
||||
|
||||
1. **阶段 1**：测试基础设施（vitest + MSW + @testing-library/react）
|
||||
2. **阶段 2**：提取自定义 hooks（`useProviderActions`、`useMcpActions`、`useSettings`、`useImportExport` 等）
|
||||
3. **阶段 3**：组件拆分和业务逻辑提取
|
||||
4. **阶段 4**：代码清理和格式化统一
|
||||
|
||||
### 测试体系
|
||||
|
||||
- **Hooks 单元测试** - 所有自定义 hooks 100% 覆盖
|
||||
- **集成测试** - 关键流程覆盖（App、SettingsDialog、MCP 面板）
|
||||
- **MSW 模拟** - 后端 API 模拟确保测试独立性
|
||||
- **测试基础设施** - vitest + MSW + @testing-library/react
|
||||
|
||||
### 代码质量
|
||||
|
||||
- **统一参数格式** - 所有 Tauri 命令迁移到 camelCase（Tauri 2 规范）
|
||||
- **语义清晰** - `AppType` 重命名为 `AppId` 以获得更好的语义
|
||||
- **集中解析** - 使用 `FromStr` trait 统一 `app` 参数解析
|
||||
- **DRY 违规清理** - 消除整个代码库中的代码重复
|
||||
- **死代码移除** - 移除未使用的 `missing_param` 辅助函数、废弃的 `tauri-api.ts`、冗余的 `KimiModelSelector`
|
||||
|
||||
---
|
||||
|
||||
## 内部优化（用户无感知）
|
||||
|
||||
### 移除遗留迁移逻辑
|
||||
|
||||
v3.6.0 移除了 v1 配置自动迁移和副本文件扫描逻辑：
|
||||
|
||||
- **影响**：提升启动性能，代码更简洁
|
||||
- **兼容性**：v2 格式配置完全兼容，无需任何操作
|
||||
- **注意**：从 v3.1.0 或更早版本升级的用户，请先升级到 v3.2.x 或 v3.5.x 进行一次性迁移，然后再升级到 v3.6.0
|
||||
|
||||
### 命令参数标准化
|
||||
|
||||
后端统一使用 `app` 参数（取值：`claude` 或 `codex`）：
|
||||
|
||||
- **影响**：代码更规范，错误提示更友好
|
||||
- **兼容性**：前端已完全适配，用户无需关心此变更
|
||||
|
||||
---
|
||||
|
||||
## 依赖更新
|
||||
|
||||
- 更新到 **Tauri 2.8.x**
|
||||
- 更新到 **TailwindCSS 4.x**
|
||||
- 更新到 **TanStack Query v5.90.x**
|
||||
- 保持 **React 18.2.x** 和 **TypeScript 5.3.x**
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🌟 关于 CC Switch
|
||||
|
||||
CC Switch 是一个跨平台桌面应用，用于管理和切换 Claude Code 与 Codex 的不同供应商配置。基于 Tauri 2.0 + React 18 + TypeScript 构建，支持 Windows、macOS、Linux。
|
||||
|
||||
**核心特性**：
|
||||
- 🔄 一键切换多个 AI 供应商
|
||||
- 📦 支持 Claude Code 和 Codex 双应用
|
||||
- 🎨 现代化 UI，完整的中英文国际化
|
||||
- 🔐 本地存储，数据安全可靠
|
||||
- ☁️ 支持云同步配置
|
||||
- 🧩 MCP 服务器统一管理
|
||||
|
||||
---
|
||||
|
||||
**项目地址**: https://github.com/farion1231/cc-switch
|
||||
@@ -0,0 +1,439 @@
|
||||
# CC Switch v3.7.0
|
||||
|
||||
> From Provider Switcher to All-in-One AI CLI Management Platform
|
||||
|
||||
**[中文更新说明 Chinese Documentation →](v3.7.0-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.7.0 introduces six major features with over 18,000 lines of new code.
|
||||
|
||||
**Release Date**: 2025-11-19
|
||||
**Commits**: 85 from v3.6.0
|
||||
**Code Changes**: 152 files, +18,104 / -3,732 lines
|
||||
|
||||
---
|
||||
|
||||
## New Features
|
||||
|
||||
### Gemini CLI Integration
|
||||
|
||||
Complete support for Google Gemini CLI, becoming the third supported application (Claude Code, Codex, Gemini).
|
||||
|
||||
**Core Capabilities**:
|
||||
|
||||
- **Dual-file configuration** - Support for both `.env` and `settings.json` formats
|
||||
- **Auto-detection** - Automatically detect `GOOGLE_GEMINI_BASE_URL`, `GEMINI_MODEL`, etc.
|
||||
- **Full MCP support** - Complete MCP server management for Gemini
|
||||
- **Deep link integration** - Import via `ccswitch://` protocol
|
||||
- **System tray** - Quick-switch from tray menu
|
||||
|
||||
**Provider Presets**:
|
||||
|
||||
- **Google Official** - OAuth authentication support
|
||||
- **PackyCode** - Partner integration
|
||||
- **Custom** - Full customization support
|
||||
|
||||
**Technical Implementation**:
|
||||
|
||||
- New backend modules: `gemini_config.rs` (20KB), `gemini_mcp.rs`
|
||||
- Form synchronization with environment editor
|
||||
- Dual-file atomic writes
|
||||
|
||||
---
|
||||
|
||||
### MCP v3.7.0 Unified Architecture
|
||||
|
||||
Complete refactoring of MCP management system for cross-application unification.
|
||||
|
||||
**Architecture Improvements**:
|
||||
|
||||
- **Unified panel** - Single interface for Claude/Codex/Gemini MCP servers
|
||||
- **SSE transport** - New Server-Sent Events support
|
||||
- **Smart parser** - Fault-tolerant JSON parsing
|
||||
- **Format correction** - Auto-fix Codex `[mcp_servers]` format
|
||||
- **Extended fields** - Preserve custom TOML fields
|
||||
|
||||
**User Experience**:
|
||||
|
||||
- Default app selection in forms
|
||||
- JSON formatter for validation
|
||||
- Improved visual hierarchy
|
||||
- Better error messages
|
||||
|
||||
**Import/Export**:
|
||||
|
||||
- Unified import from all three apps
|
||||
- Bidirectional synchronization
|
||||
- State preservation
|
||||
|
||||
---
|
||||
|
||||
### Claude Skills Management System
|
||||
|
||||
**Approximately 2,000 lines of code** - A complete skill ecosystem platform.
|
||||
|
||||
**GitHub Integration**:
|
||||
|
||||
- Auto-scan skills from GitHub repositories
|
||||
- Pre-configured repos:
|
||||
- `ComposioHQ/awesome-claude-skills` - Curated collection
|
||||
- `anthropics/skills` - Official Anthropic skills
|
||||
- `cexll/myclaude` - Community contributions
|
||||
- Add custom repositories
|
||||
- Subdirectory scanning support (`skillsPath`)
|
||||
|
||||
**Lifecycle Management**:
|
||||
|
||||
- **Discover** - Auto-detect `SKILL.md` files
|
||||
- **Install** - One-click to `~/.claude/skills/`
|
||||
- **Uninstall** - Safe removal with tracking
|
||||
- **Update** - Check for updates (infrastructure ready)
|
||||
|
||||
**Technical Architecture**:
|
||||
|
||||
- **Backend**: `SkillService` (526 lines) with GitHub API integration
|
||||
- **Frontend**: SkillsPage, SkillCard, RepoManager
|
||||
- **UI Components**: Badge, Card, Table (shadcn/ui)
|
||||
- **State**: Persistent storage in `skills.json`
|
||||
- **i18n**: 47+ translation keys
|
||||
|
||||
---
|
||||
|
||||
### Prompts Management System
|
||||
|
||||
**Approximately 1,300 lines of code** - Complete system prompt management.
|
||||
|
||||
**Multi-Preset Management**:
|
||||
|
||||
- Create unlimited prompt presets
|
||||
- Quick switch between presets
|
||||
- One active prompt at a time
|
||||
- Delete protection for active prompts
|
||||
|
||||
**Cross-App Support**:
|
||||
|
||||
- **Claude**: `~/.claude/CLAUDE.md`
|
||||
- **Codex**: `~/.codex/AGENTS.md`
|
||||
- **Gemini**: `~/.gemini/GEMINI.md`
|
||||
|
||||
**Markdown Editor**:
|
||||
|
||||
- Full-featured CodeMirror 6 integration
|
||||
- Syntax highlighting
|
||||
- Dark theme (One Dark)
|
||||
- Real-time preview
|
||||
|
||||
**Smart Synchronization**:
|
||||
|
||||
- **Auto-write** - Immediately write to live files
|
||||
- **Backfill protection** - Save current content before switching
|
||||
- **Auto-import** - Import from live files on first launch
|
||||
- **Modification protection** - Preserve manual modifications
|
||||
|
||||
**Technical Implementation**:
|
||||
|
||||
- **Backend**: `PromptService` (213 lines)
|
||||
- **Frontend**: PromptPanel (177), PromptFormModal (160), MarkdownEditor (159)
|
||||
- **Hooks**: usePromptActions (152 lines)
|
||||
- **i18n**: 41+ translation keys
|
||||
|
||||
---
|
||||
|
||||
### Deep Link Protocol (ccswitch://)
|
||||
|
||||
One-click provider configuration import via URL scheme.
|
||||
|
||||
**Features**:
|
||||
|
||||
- Protocol registration on all platforms
|
||||
- Import from shared links
|
||||
- Lifecycle integration
|
||||
- Security validation
|
||||
|
||||
---
|
||||
|
||||
### Environment Variable Conflict Detection
|
||||
|
||||
Intelligent detection and management of configuration conflicts.
|
||||
|
||||
**Detection Scope**:
|
||||
|
||||
- **Claude & Codex** - Cross-app conflicts
|
||||
- **Gemini** - Auto-discovery
|
||||
- **MCP** - Server configuration conflicts
|
||||
|
||||
**Management Features**:
|
||||
|
||||
- Visual conflict indicators
|
||||
- Resolution suggestions
|
||||
- Override warnings
|
||||
- Backup before changes
|
||||
|
||||
---
|
||||
|
||||
## Improvements
|
||||
|
||||
### Provider Management
|
||||
|
||||
**New Presets**:
|
||||
|
||||
- **DouBaoSeed** - ByteDance's DouBao
|
||||
- **Kimi For Coding** - Moonshot AI
|
||||
- **BaiLing** - BaiLing AI
|
||||
- **Removed AnyRouter** - To avoid confusion
|
||||
|
||||
**Enhancements**:
|
||||
|
||||
- Model name configuration for Codex and Gemini
|
||||
- Provider notes field for organization
|
||||
- Enhanced preset metadata
|
||||
|
||||
### Configuration Management
|
||||
|
||||
- **Common config migration** - From localStorage to `config.json`
|
||||
- **Unified persistence** - Shared across all apps
|
||||
- **Auto-import** - First launch configuration import
|
||||
- **Backfill priority** - Correct handling of live files
|
||||
|
||||
### UI/UX Improvements
|
||||
|
||||
**Design System**:
|
||||
|
||||
- **macOS native** - System-aligned color scheme
|
||||
- **Window centering** - Default centered position
|
||||
- **Visual polish** - Improved spacing and hierarchy
|
||||
|
||||
**Interactions**:
|
||||
|
||||
- **Password input** - Fixed Edge/IE reveal buttons
|
||||
- **URL overflow** - Fixed card overflow
|
||||
- **Error copying** - Copy-to-clipboard errors
|
||||
- **Tray sync** - Real-time drag-and-drop sync
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Critical Fixes
|
||||
|
||||
- **Usage script validation** - Boundary checks
|
||||
- **Gemini validation** - Relaxed constraints
|
||||
- **TOML parsing** - CJK quote handling
|
||||
- **MCP fields** - Custom field preservation
|
||||
- **White screen** - FormLabel crash fix
|
||||
|
||||
### Stability
|
||||
|
||||
- **Tray safety** - Pattern matching instead of unwrap
|
||||
- **Error isolation** - Tray failures don't block operations
|
||||
- **Import classification** - Correct category assignment
|
||||
|
||||
### UI Fixes
|
||||
|
||||
- **Model placeholders** - Removed misleading hints
|
||||
- **Base URL** - Auto-fill for third-party providers
|
||||
- **Drag sort** - Tray menu synchronization
|
||||
|
||||
---
|
||||
|
||||
## Technical Improvements
|
||||
|
||||
### Architecture
|
||||
|
||||
**MCP v3.7.0**:
|
||||
|
||||
- Removed legacy code (~1,000 lines)
|
||||
- Unified initialization structure
|
||||
- Backward compatibility maintained
|
||||
- Comprehensive code formatting
|
||||
|
||||
**Platform Compatibility**:
|
||||
|
||||
- Windows winreg API fix (v0.52)
|
||||
- Safe pattern matching (no `unwrap()`)
|
||||
- Cross-platform tray handling
|
||||
|
||||
### Configuration
|
||||
|
||||
**Synchronization**:
|
||||
|
||||
- MCP sync across all apps
|
||||
- Gemini form-editor sync
|
||||
- Dual-file reading (.env + settings.json)
|
||||
|
||||
**Validation**:
|
||||
|
||||
- Input boundary checks
|
||||
- TOML quote normalization (CJK)
|
||||
- Custom field preservation
|
||||
- Enhanced error messages
|
||||
|
||||
### Code Quality
|
||||
|
||||
**Type Safety**:
|
||||
|
||||
- Complete TypeScript coverage
|
||||
- Rust type refinements
|
||||
- API contract validation
|
||||
|
||||
**Testing**:
|
||||
|
||||
- Simplified assertions
|
||||
- Better test coverage
|
||||
- Integration test updates
|
||||
|
||||
**Dependencies**:
|
||||
|
||||
- Tauri 2.8.x
|
||||
- Rust: `anyhow`, `zip`, `serde_yaml`, `tempfile`
|
||||
- Frontend: CodeMirror 6 packages
|
||||
- winreg 0.52 (Windows)
|
||||
|
||||
---
|
||||
|
||||
## Technical Statistics
|
||||
|
||||
```
|
||||
Total Changes:
|
||||
- Commits: 85
|
||||
- Files: 152 changed
|
||||
- Additions: +18,104 lines
|
||||
- Deletions: -3,732 lines
|
||||
|
||||
New Modules:
|
||||
- Skills Management: 2,034 lines (21 files)
|
||||
- Prompts Management: 1,302 lines (20 files)
|
||||
- Gemini Integration: ~1,000 lines
|
||||
- MCP Refactor: ~3,000 lines refactored
|
||||
|
||||
Code Distribution:
|
||||
- Backend (Rust): ~4,500 lines new
|
||||
- Frontend (React): ~3,000 lines new
|
||||
- Configuration: ~1,500 lines refactored
|
||||
- Tests: ~500 lines
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Strategic Positioning
|
||||
|
||||
### From Tool to Platform
|
||||
|
||||
v3.7.0 represents a shift in CC Switch's positioning:
|
||||
|
||||
| Aspect | v3.6 | v3.7.0 |
|
||||
| ----------------- | ------------------------ | ---------------------------- |
|
||||
| **Identity** | Provider Switcher | AI CLI Management Platform |
|
||||
| **Scope** | Configuration Management | Ecosystem Management |
|
||||
| **Applications** | Claude + Codex | Claude + Codex + Gemini |
|
||||
| **Capabilities** | Switch configs | Extend capabilities (Skills) |
|
||||
| **Customization** | Manual editing | Visual management (Prompts) |
|
||||
| **Integration** | Isolated apps | Unified management (MCP) |
|
||||
|
||||
### Six Pillars of AI CLI Management
|
||||
|
||||
1. **Configuration Management** - Provider switching and management
|
||||
2. **Capability Extension** - Skills installation and lifecycle
|
||||
3. **Behavior Customization** - System prompt presets
|
||||
4. **Ecosystem Integration** - Deep links and sharing
|
||||
5. **Multi-AI Support** - Claude/Codex/Gemini
|
||||
6. **Intelligent Detection** - Conflict prevention
|
||||
|
||||
---
|
||||
|
||||
## Download & Installation
|
||||
|
||||
### System Requirements
|
||||
|
||||
- **Windows**: Windows 10+
|
||||
- **macOS**: macOS 10.15 (Catalina)+
|
||||
- **Linux**: Ubuntu 22.04+ / Debian 11+ / Fedora 34+
|
||||
|
||||
### Download Links
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download:
|
||||
|
||||
- **Windows**: `CC-Switch-v3.7.0-Windows.msi` or `-Portable.zip`
|
||||
- **macOS**: `CC-Switch-v3.7.0-macOS.tar.gz` or `.zip`
|
||||
- **Linux**: `CC-Switch-v3.7.0-Linux.AppImage` or `.deb`
|
||||
|
||||
### Homebrew (macOS)
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Notes
|
||||
|
||||
### From v3.6.x
|
||||
|
||||
**Automatic migration** - No action required, configs are fully compatible
|
||||
|
||||
### From v3.1.x or Earlier
|
||||
|
||||
**Two-step migration required**:
|
||||
|
||||
1. First upgrade to v3.2.x (performs one-time migration)
|
||||
2. Then upgrade to v3.7.0
|
||||
|
||||
### New Features
|
||||
|
||||
- **Skills**: No migration needed, start fresh
|
||||
- **Prompts**: Auto-import from live files on first launch
|
||||
- **Gemini**: Install Gemini CLI separately if needed
|
||||
- **MCP v3.7.0**: Backward compatible with previous configs
|
||||
|
||||
---
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
### Contributors
|
||||
|
||||
Thanks to all contributors who made this release possible:
|
||||
|
||||
- [@YoVinchen](https://github.com/YoVinchen) - Skills & Prompts & Gemini integration implementation
|
||||
- [@farion1231](https://github.com/farion1231) - From developer to issue responder
|
||||
- Community members for testing and feedback
|
||||
|
||||
### Sponsors
|
||||
|
||||
**Z.ai** - GLM CODING PLAN sponsor
|
||||
[Get 10% OFF with this link](https://z.ai/subscribe?ic=8JVLJQFSKB)
|
||||
|
||||
**PackyCode** - API relay service partner
|
||||
[Register with "cc-switch" code for 10% discount](https://www.packyapi.com/register?aff=cc-switch)
|
||||
|
||||
---
|
||||
|
||||
## Feedback & Support
|
||||
|
||||
- **Issues**: [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/farion1231/cc-switch/discussions)
|
||||
- **Documentation**: [README](../README.md)
|
||||
- **Changelog**: [CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## What's Next
|
||||
|
||||
**v3.8.0 Preview** (Tentative):
|
||||
|
||||
- Local proxy functionality
|
||||
|
||||
Stay tuned for more updates!
|
||||
|
||||
---
|
||||
|
||||
**Happy Coding!**
|
||||
@@ -0,0 +1,435 @@
|
||||
# CC Switch v3.7.0
|
||||
|
||||
> 从供应商切换器到 AI CLI 一体化管理平台
|
||||
|
||||
**[English Version →](v3.7.0-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.7.0 新增六大核心功能，新增超过 18,000 行代码。
|
||||
|
||||
**发布日期**：2025-11-19
|
||||
**提交数量**：从 v3.6.0 开始 85 个提交
|
||||
**代码变更**：152 个文件，+18,104 / -3,732 行
|
||||
|
||||
---
|
||||
|
||||
## 新增功能
|
||||
|
||||
### Gemini CLI 集成
|
||||
|
||||
完整支持 Google Gemini CLI，成为第三个支持的应用（Claude Code、Codex、Gemini）。
|
||||
|
||||
**核心能力**：
|
||||
|
||||
- **双文件配置** - 同时支持 `.env` 和 `settings.json` 格式
|
||||
- **自动检测** - 自动检测 `GOOGLE_GEMINI_BASE_URL`、`GEMINI_MODEL` 等环境变量
|
||||
- **完整 MCP 支持** - 为 Gemini 提供完整的 MCP 服务器管理
|
||||
- **深度链接集成** - 通过 `ccswitch://` 协议导入配置
|
||||
- **系统托盘** - 从托盘菜单快速切换
|
||||
|
||||
**供应商预设**：
|
||||
|
||||
- **Google Official** - 支持 OAuth 认证
|
||||
- **PackyCode** - 合作伙伴集成
|
||||
- **自定义** - 完全自定义支持
|
||||
|
||||
**技术实现**：
|
||||
|
||||
- 新增后端模块：`gemini_config.rs`（20KB）、`gemini_mcp.rs`
|
||||
- 表单与环境编辑器同步
|
||||
- 双文件原子写入
|
||||
|
||||
---
|
||||
|
||||
### MCP v3.7.0 统一架构
|
||||
|
||||
MCP 管理系统完整重构，实现跨应用统一管理。
|
||||
|
||||
**架构改进**：
|
||||
|
||||
- **统一管理面板** - 单一界面管理 Claude/Codex/Gemini MCP 服务器
|
||||
- **SSE 传输类型** - 新增 Server-Sent Events 支持
|
||||
- **智能解析器** - 容错性 JSON 解析
|
||||
- **格式修正** - 自动修复 Codex `[mcp_servers]` 格式
|
||||
- **扩展字段** - 保留自定义 TOML 字段
|
||||
|
||||
**用户体验**：
|
||||
|
||||
- 表单中的默认应用选择
|
||||
- JSON 格式化器用于验证
|
||||
- 改进的视觉层次
|
||||
- 更好的错误消息
|
||||
|
||||
**导入/导出**：
|
||||
|
||||
- 统一从三个应用导入
|
||||
- 双向同步
|
||||
- 状态保持
|
||||
|
||||
---
|
||||
|
||||
### Claude Skills 管理系统
|
||||
|
||||
**约 2,000 行代码** - 完整的技能生态平台。
|
||||
|
||||
**GitHub 集成**：
|
||||
|
||||
- 从 GitHub 仓库自动扫描技能
|
||||
- 预配置仓库：
|
||||
- `ComposioHQ/awesome-claude-skills` - 精选集合
|
||||
- `anthropics/skills` - Anthropic 官方技能
|
||||
- `cexll/myclaude` - 社区贡献
|
||||
- 添加自定义仓库
|
||||
- 子目录扫描支持（`skillsPath`）
|
||||
|
||||
**生命周期管理**：
|
||||
|
||||
- **发现** - 自动检测 `SKILL.md` 文件
|
||||
- **安装** - 一键安装到 `~/.claude/skills/`
|
||||
- **卸载** - 安全移除并跟踪状态
|
||||
- **更新** - 检查更新（基础设施已就绪）
|
||||
|
||||
**技术架构**：
|
||||
|
||||
- **后端**：`SkillService`（526 行）集成 GitHub API
|
||||
- **前端**：SkillsPage、SkillCard、RepoManager
|
||||
- **UI 组件**：Badge、Card、Table（shadcn/ui）
|
||||
- **状态**：持久化存储在 `skills.json`
|
||||
- **国际化**：47+ 个翻译键
|
||||
|
||||
---
|
||||
|
||||
### Prompts 管理系统
|
||||
|
||||
**约 1,300 行代码** - 完整的系统提示词管理。
|
||||
|
||||
**多预设管理**：
|
||||
|
||||
- 创建无限数量的提示词预设
|
||||
- 快速在预设间切换
|
||||
- 同时只能激活一个提示词
|
||||
- 活动提示词删除保护
|
||||
|
||||
**跨应用支持**：
|
||||
|
||||
- **Claude**：`~/.claude/CLAUDE.md`
|
||||
- **Codex**：`~/.codex/AGENTS.md`
|
||||
- **Gemini**：`~/.gemini/GEMINI.md`
|
||||
|
||||
**Markdown 编辑器**：
|
||||
|
||||
- 完整的 CodeMirror 6 集成
|
||||
- 语法高亮
|
||||
- 暗色主题（One Dark）
|
||||
- 实时预览
|
||||
|
||||
**智能同步**：
|
||||
|
||||
- **自动写入** - 立即写入 live 文件
|
||||
- **回填保护** - 切换前保存当前内容
|
||||
- **自动导入** - 首次启动从 live 文件导入
|
||||
- **修改保护** - 保留手动修改
|
||||
|
||||
**技术实现**：
|
||||
|
||||
- **后端**：`PromptService`（213 行）
|
||||
- **前端**：PromptPanel（177）、PromptFormModal（160）、MarkdownEditor（159）
|
||||
- **Hooks**：usePromptActions（152 行）
|
||||
- **国际化**：41+ 个翻译键
|
||||
|
||||
---
|
||||
|
||||
### 深度链接协议（ccswitch://）
|
||||
|
||||
通过 URL 方案一键导入供应商配置。
|
||||
|
||||
**功能特性**：
|
||||
|
||||
- 所有平台的协议注册
|
||||
- 从共享链接导入
|
||||
- 生命周期集成
|
||||
- 安全验证
|
||||
|
||||
---
|
||||
|
||||
### 环境变量冲突检测
|
||||
|
||||
智能检测和管理配置冲突。
|
||||
|
||||
**检测范围**：
|
||||
|
||||
- **Claude & Codex** - 跨应用冲突
|
||||
- **Gemini** - 自动发现
|
||||
- **MCP** - 服务器配置冲突
|
||||
|
||||
**管理功能**：
|
||||
|
||||
- 可视化冲突指示器
|
||||
- 解决建议
|
||||
- 覆盖警告
|
||||
- 更改前备份
|
||||
|
||||
---
|
||||
|
||||
## 改进优化
|
||||
|
||||
### 供应商管理
|
||||
|
||||
**新增预设**：
|
||||
|
||||
- **DouBaoSeed** - 字节跳动的豆包
|
||||
- **Kimi For Coding** - 月之暗面
|
||||
- **BaiLing** - 百灵 AI
|
||||
- **移除 AnyRouter** - 避免误导
|
||||
|
||||
**增强功能**：
|
||||
|
||||
- Codex 和 Gemini 的模型名称配置
|
||||
- 供应商备注字段用于组织
|
||||
- 增强的预设元数据
|
||||
|
||||
### 配置管理
|
||||
|
||||
- **通用配置迁移** - 从 localStorage 迁移到 `config.json`
|
||||
- **统一持久化** - 跨所有应用共享
|
||||
- **自动导入** - 首次启动配置导入
|
||||
- **回填优先级** - 正确处理 live 文件
|
||||
|
||||
### UI/UX 改进
|
||||
|
||||
**设计系统**：
|
||||
|
||||
- **macOS 原生** - 与系统对齐的配色方案
|
||||
- **窗口居中** - 默认居中位置
|
||||
- **视觉优化** - 改进的间距和层次
|
||||
|
||||
**交互优化**：
|
||||
|
||||
- **密码输入** - 修复 Edge/IE 显示按钮
|
||||
- **URL 溢出** - 修复卡片溢出
|
||||
- **错误复制** - 可复制到剪贴板的错误
|
||||
- **托盘同步** - 实时拖放同步
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 关键修复
|
||||
|
||||
- **用量脚本验证** - 边界检查
|
||||
- **Gemini 验证** - 放宽约束
|
||||
- **TOML 解析** - CJK 引号处理
|
||||
- **MCP 字段** - 自定义字段保留
|
||||
- **白屏** - FormLabel 崩溃修复
|
||||
|
||||
### 稳定性
|
||||
|
||||
- **托盘安全** - 模式匹配替代 unwrap
|
||||
- **错误隔离** - 托盘失败不阻塞操作
|
||||
- **导入分类** - 正确的类别分配
|
||||
|
||||
### UI 修复
|
||||
|
||||
- **模型占位符** - 移除误导性提示
|
||||
- **Base URL** - 第三方供应商自动填充
|
||||
- **拖拽排序** - 托盘菜单同步
|
||||
|
||||
---
|
||||
|
||||
## 技术改进
|
||||
|
||||
### 架构
|
||||
|
||||
**MCP v3.7.0**：
|
||||
|
||||
- 移除遗留代码（约 1,000 行）
|
||||
- 统一初始化结构
|
||||
- 保持向后兼容性
|
||||
- 全面的代码格式化
|
||||
|
||||
**平台兼容性**：
|
||||
|
||||
- Windows winreg API 修复（v0.52）
|
||||
- 安全模式匹配（无 `unwrap()`）
|
||||
- 跨平台托盘处理
|
||||
|
||||
### 配置
|
||||
|
||||
**同步机制**：
|
||||
|
||||
- 跨所有应用的 MCP 同步
|
||||
- Gemini 表单-编辑器同步
|
||||
- 双文件读取（.env + settings.json）
|
||||
|
||||
**验证增强**：
|
||||
|
||||
- 输入边界检查
|
||||
- TOML 引号规范化（CJK）
|
||||
- 自定义字段保留
|
||||
- 增强的错误消息
|
||||
|
||||
### 代码质量
|
||||
|
||||
**类型安全**：
|
||||
|
||||
- 完整的 TypeScript 覆盖
|
||||
- Rust 类型改进
|
||||
- API 契约验证
|
||||
|
||||
**测试**：
|
||||
|
||||
- 简化的断言
|
||||
- 更好的测试覆盖
|
||||
- 集成测试更新
|
||||
|
||||
**依赖项**：
|
||||
|
||||
- Tauri 2.8.x
|
||||
- Rust：`anyhow`、`zip`、`serde_yaml`、`tempfile`
|
||||
- 前端：CodeMirror 6 包
|
||||
- winreg 0.52（Windows）
|
||||
|
||||
---
|
||||
|
||||
## 技术统计
|
||||
|
||||
```
|
||||
总体变更：
|
||||
- 提交数：85
|
||||
- 文件数：152 个文件变更
|
||||
- 新增：+18,104 行
|
||||
- 删除：-3,732 行
|
||||
|
||||
新增模块：
|
||||
- Skills 管理：2,034 行（21 个文件）
|
||||
- Prompts 管理：1,302 行（20 个文件）
|
||||
- Gemini 集成：约 1,000 行
|
||||
- MCP 重构：约 3,000 行重构
|
||||
|
||||
代码分布：
|
||||
- 后端（Rust）：约 4,500 行新增
|
||||
- 前端（React）：约 3,000 行新增
|
||||
- 配置：约 1,500 行重构
|
||||
- 测试：约 500 行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 战略定位
|
||||
|
||||
### 从工具到平台
|
||||
|
||||
v3.7.0 代表了 CC Switch 定位的转变：
|
||||
|
||||
| 方面 | v3.6 | v3.7.0 |
|
||||
| -------- | -------------- | ----------------------- |
|
||||
| **身份** | 供应商切换器 | AI CLI 管理平台 |
|
||||
| **范围** | 配置管理 | 生态系统管理 |
|
||||
| **应用** | Claude + Codex | Claude + Codex + Gemini |
|
||||
| **能力** | 切换配置 | 扩展能力（Skills） |
|
||||
| **定制** | 手动编辑 | 可视化管理（Prompts） |
|
||||
| **集成** | 孤立应用 | 统一管理（MCP） |
|
||||
|
||||
### AI CLI 管理六大支柱
|
||||
|
||||
1. **配置管理** - 供应商切换和管理
|
||||
2. **能力扩展** - Skills 安装和生命周期
|
||||
3. **行为定制** - 系统提示词预设
|
||||
4. **生态集成** - 深度链接和共享
|
||||
5. **多 AI 支持** - Claude/Codex/Gemini
|
||||
6. **智能检测** - 冲突预防
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
### 系统要求
|
||||
|
||||
- **Windows**：Windows 10+
|
||||
- **macOS**：macOS 10.15（Catalina）+
|
||||
- **Linux**：Ubuntu 22.04+ / Debian 11+ / Fedora 34+
|
||||
|
||||
### 下载链接
|
||||
|
||||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载：
|
||||
|
||||
- **Windows**：`CC-Switch-v3.7.0-Windows.msi` 或 `-Portable.zip`
|
||||
- **macOS**：`CC-Switch-v3.7.0-macOS.tar.gz` 或 `.zip`
|
||||
- **Linux**：`CC-Switch-v3.7.0-Linux.AppImage` 或 `.deb`
|
||||
|
||||
### Homebrew（macOS）
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 迁移说明
|
||||
|
||||
### 从 v3.6.x 升级
|
||||
|
||||
**自动迁移** - 无需任何操作，配置完全兼容
|
||||
|
||||
### 从 v3.1.x 或更早版本升级
|
||||
|
||||
**需要两步迁移**：
|
||||
|
||||
1. 首先升级到 v3.2.x（执行一次性迁移）
|
||||
2. 然后升级到 v3.7.0
|
||||
|
||||
### 新功能
|
||||
|
||||
- **Skills**：无需迁移，全新开始
|
||||
- **Prompts**：首次启动时从 live 文件自动导入
|
||||
- **Gemini**：需要单独安装 Gemini CLI
|
||||
- **MCP v3.7.0**：与之前的配置向后兼容
|
||||
|
||||
---
|
||||
|
||||
## 致谢
|
||||
|
||||
### 贡献者
|
||||
|
||||
感谢所有让这个版本成为可能的贡献者：
|
||||
|
||||
- [@YoVinchen](https://github.com/YoVinchen) - Skills & Prompts & Geimini 集成实现
|
||||
- [@farion1231](https://github.com/farion1231) - 从开发沦为 issue 回复机
|
||||
- 社区成员的测试和反馈
|
||||
|
||||
### 赞助商
|
||||
|
||||
**Z.ai** - GLM CODING PLAN 赞助商
|
||||
[通过此链接获得 10% 折扣](https://z.ai/subscribe?ic=8JVLJQFSKB)
|
||||
|
||||
**PackyCode** - API 中继服务合作伙伴
|
||||
[使用 "cc-switch" 代码注册可享受 10% 折扣](https://www.packyapi.com/register?aff=cc-switch)
|
||||
|
||||
---
|
||||
|
||||
## 反馈与支持
|
||||
|
||||
- **问题反馈**：[GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- **讨论**：[GitHub Discussions](https://github.com/farion1231/cc-switch/discussions)
|
||||
- **文档**：[README](../README_ZH.md)
|
||||
- **更新日志**：[CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## 未来展望
|
||||
|
||||
**v3.8.0 预览**（暂定）：
|
||||
|
||||
- 本地代理功能
|
||||
|
||||
敬请期待更多更新！
|
||||
@@ -0,0 +1,481 @@
|
||||
# CC Switch v3.7.1
|
||||
|
||||
> Stability Enhancements and User Experience Improvements
|
||||
|
||||
**[中文更新说明 Chinese Documentation →](v3.7.1-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## v3.7.1 Updates
|
||||
|
||||
**Release Date**: 2025-11-22
|
||||
**Code Changes**: 17 files, +524 / -81 lines
|
||||
|
||||
### Bug Fixes
|
||||
|
||||
- **Fix Third-Party Skills Installation Failure** (#268)
|
||||
Fixed installation issues for skills repositories with custom subdirectories, now supports repos like `ComposioHQ/awesome-claude-skills` with subdirectories
|
||||
|
||||
- **Fix Gemini Configuration Persistence Issue**
|
||||
Resolved the issue where settings.json edits in Gemini form were lost when switching providers
|
||||
|
||||
- **Prevent Dialogs from Closing on Overlay Click**
|
||||
Added protection against clicking overlay/backdrop, preventing accidental form data loss across all 11 dialog components
|
||||
|
||||
### New Features
|
||||
|
||||
- **Gemini Configuration Directory Support** (#255)
|
||||
Added Gemini configuration directory option in settings, supports customizing `~/.gemini/` path
|
||||
|
||||
- **ArchLinux Installation Support** (#259)
|
||||
Added AUR installation method: `paru -S cc-switch-bin`
|
||||
|
||||
### Improvements
|
||||
|
||||
- **Skills Error Message i18n Enhancement**
|
||||
Added 28+ detailed error messages (English & Chinese) with specific resolution suggestions, extended download timeout from 15s to 60s
|
||||
|
||||
- **Code Formatting**
|
||||
Applied unified Rust and TypeScript code formatting standards
|
||||
|
||||
### Download
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download the latest version
|
||||
|
||||
---
|
||||
|
||||
## v3.7.0 Complete Release Notes
|
||||
|
||||
> From Provider Switcher to All-in-One AI CLI Management Platform
|
||||
|
||||
**Release Date**: 2025-11-19
|
||||
**Commits**: 85 from v3.6.0
|
||||
**Code Changes**: 152 files, +18,104 / -3,732 lines
|
||||
|
||||
---
|
||||
|
||||
## New Features
|
||||
|
||||
### Gemini CLI Integration
|
||||
|
||||
Complete support for Google Gemini CLI, becoming the third supported application (Claude Code, Codex, Gemini).
|
||||
|
||||
**Core Capabilities**:
|
||||
|
||||
- **Dual-file configuration** - Support for both `.env` and `settings.json` formats
|
||||
- **Auto-detection** - Automatically detect `GOOGLE_GEMINI_BASE_URL`, `GEMINI_MODEL`, etc.
|
||||
- **Full MCP support** - Complete MCP server management for Gemini
|
||||
- **Deep link integration** - Import via `ccswitch://` protocol
|
||||
- **System tray** - Quick-switch from tray menu
|
||||
|
||||
**Provider Presets**:
|
||||
|
||||
- **Google Official** - OAuth authentication support
|
||||
- **PackyCode** - Partner integration
|
||||
- **Custom** - Full customization support
|
||||
|
||||
**Technical Implementation**:
|
||||
|
||||
- New backend modules: `gemini_config.rs` (20KB), `gemini_mcp.rs`
|
||||
- Form synchronization with environment editor
|
||||
- Dual-file atomic writes
|
||||
|
||||
---
|
||||
|
||||
### MCP v3.7.0 Unified Architecture
|
||||
|
||||
Complete refactoring of MCP management system for cross-application unification.
|
||||
|
||||
**Architecture Improvements**:
|
||||
|
||||
- **Unified panel** - Single interface for Claude/Codex/Gemini MCP servers
|
||||
- **SSE transport** - New Server-Sent Events support
|
||||
- **Smart parser** - Fault-tolerant JSON parsing
|
||||
- **Format correction** - Auto-fix Codex `[mcp_servers]` format
|
||||
- **Extended fields** - Preserve custom TOML fields
|
||||
|
||||
**User Experience**:
|
||||
|
||||
- Default app selection in forms
|
||||
- JSON formatter for validation
|
||||
- Improved visual hierarchy
|
||||
- Better error messages
|
||||
|
||||
**Import/Export**:
|
||||
|
||||
- Unified import from all three apps
|
||||
- Bidirectional synchronization
|
||||
- State preservation
|
||||
|
||||
---
|
||||
|
||||
### Claude Skills Management System
|
||||
|
||||
**Approximately 2,000 lines of code** - A complete skill ecosystem platform.
|
||||
|
||||
**GitHub Integration**:
|
||||
|
||||
- Auto-scan skills from GitHub repositories
|
||||
- Pre-configured repos:
|
||||
- `ComposioHQ/awesome-claude-skills` - Curated collection
|
||||
- `anthropics/skills` - Official Anthropic skills
|
||||
- `cexll/myclaude` - Community contributions
|
||||
- Add custom repositories
|
||||
- Subdirectory scanning support (`skillsPath`)
|
||||
|
||||
**Lifecycle Management**:
|
||||
|
||||
- **Discover** - Auto-detect `SKILL.md` files
|
||||
- **Install** - One-click to `~/.claude/skills/`
|
||||
- **Uninstall** - Safe removal with tracking
|
||||
- **Update** - Check for updates (infrastructure ready)
|
||||
|
||||
**Technical Architecture**:
|
||||
|
||||
- **Backend**: `SkillService` (526 lines) with GitHub API integration
|
||||
- **Frontend**: SkillsPage, SkillCard, RepoManager
|
||||
- **UI Components**: Badge, Card, Table (shadcn/ui)
|
||||
- **State**: Persistent storage in `config.json`
|
||||
- **i18n**: 47+ translation keys
|
||||
|
||||
---
|
||||
|
||||
### Prompts Management System
|
||||
|
||||
**Approximately 1,300 lines of code** - Complete system prompt management.
|
||||
|
||||
**Multi-Preset Management**:
|
||||
|
||||
- Create unlimited prompt presets
|
||||
- Quick switch between presets
|
||||
- One active prompt at a time
|
||||
- Delete protection for active prompts
|
||||
|
||||
**Cross-App Support**:
|
||||
|
||||
- **Claude**: `~/.claude/CLAUDE.md`
|
||||
- **Codex**: `~/.codex/AGENTS.md`
|
||||
- **Gemini**: `~/.gemini/GEMINI.md`
|
||||
|
||||
**Markdown Editor**:
|
||||
|
||||
- Full-featured CodeMirror 6 integration
|
||||
- Syntax highlighting
|
||||
- Dark theme (One Dark)
|
||||
- Real-time preview
|
||||
|
||||
**Smart Synchronization**:
|
||||
|
||||
- **Auto-write** - Immediately write to live files
|
||||
- **Backfill protection** - Save current content before switching
|
||||
- **Auto-import** - Import from live files on first launch
|
||||
- **Modification protection** - Preserve manual modifications
|
||||
|
||||
**Technical Implementation**:
|
||||
|
||||
- **Backend**: `PromptService` (213 lines)
|
||||
- **Frontend**: PromptPanel (177), PromptFormModal (160), MarkdownEditor (159)
|
||||
- **Hooks**: usePromptActions (152 lines)
|
||||
- **i18n**: 41+ translation keys
|
||||
|
||||
---
|
||||
|
||||
### Deep Link Protocol (ccswitch://)
|
||||
|
||||
One-click provider configuration import via URL scheme.
|
||||
|
||||
**Features**:
|
||||
|
||||
- Protocol registration on all platforms
|
||||
- Import from shared links
|
||||
- Lifecycle integration
|
||||
- Security validation
|
||||
|
||||
---
|
||||
|
||||
### Environment Variable Conflict Detection
|
||||
|
||||
Intelligent detection and management of configuration conflicts.
|
||||
|
||||
**Detection Scope**:
|
||||
|
||||
- **Claude & Codex** - Cross-app conflicts
|
||||
- **Gemini** - Auto-discovery
|
||||
- **MCP** - Server configuration conflicts
|
||||
|
||||
**Management Features**:
|
||||
|
||||
- Visual conflict indicators
|
||||
- Resolution suggestions
|
||||
- Override warnings
|
||||
- Backup before changes
|
||||
|
||||
---
|
||||
|
||||
## Improvements
|
||||
|
||||
### Provider Management
|
||||
|
||||
**New Presets**:
|
||||
|
||||
- **DouBaoSeed** - ByteDance's DouBao
|
||||
- **Kimi For Coding** - Moonshot AI
|
||||
- **BaiLing** - BaiLing AI
|
||||
- **Removed AnyRouter** - To avoid confusion
|
||||
|
||||
**Enhancements**:
|
||||
|
||||
- Model name configuration for Codex and Gemini
|
||||
- Provider notes field for organization
|
||||
- Enhanced preset metadata
|
||||
|
||||
### Configuration Management
|
||||
|
||||
- **Common config migration** - From localStorage to `config.json`
|
||||
- **Unified persistence** - Shared across all apps
|
||||
- **Auto-import** - First launch configuration import
|
||||
- **Backfill priority** - Correct handling of live files
|
||||
|
||||
### UI/UX Improvements
|
||||
|
||||
**Design System**:
|
||||
|
||||
- **macOS native** - System-aligned color scheme
|
||||
- **Window centering** - Default centered position
|
||||
- **Visual polish** - Improved spacing and hierarchy
|
||||
|
||||
**Interactions**:
|
||||
|
||||
- **Password input** - Fixed Edge/IE reveal buttons
|
||||
- **URL overflow** - Fixed card overflow
|
||||
- **Error copying** - Copy-to-clipboard errors
|
||||
- **Tray sync** - Real-time drag-and-drop sync
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Critical Fixes
|
||||
|
||||
- **Usage script validation** - Boundary checks
|
||||
- **Gemini validation** - Relaxed constraints
|
||||
- **TOML parsing** - CJK quote handling
|
||||
- **MCP fields** - Custom field preservation
|
||||
- **White screen** - FormLabel crash fix
|
||||
|
||||
### Stability
|
||||
|
||||
- **Tray safety** - Pattern matching instead of unwrap
|
||||
- **Error isolation** - Tray failures don't block operations
|
||||
- **Import classification** - Correct category assignment
|
||||
|
||||
### UI Fixes
|
||||
|
||||
- **Model placeholders** - Removed misleading hints
|
||||
- **Base URL** - Auto-fill for third-party providers
|
||||
- **Drag sort** - Tray menu synchronization
|
||||
|
||||
---
|
||||
|
||||
## Technical Improvements
|
||||
|
||||
### Architecture
|
||||
|
||||
**MCP v3.7.0**:
|
||||
|
||||
- Removed legacy code (~1,000 lines)
|
||||
- Unified initialization structure
|
||||
- Backward compatibility maintained
|
||||
- Comprehensive code formatting
|
||||
|
||||
**Platform Compatibility**:
|
||||
|
||||
- Windows winreg API fix (v0.52)
|
||||
- Safe pattern matching (no `unwrap()`)
|
||||
- Cross-platform tray handling
|
||||
|
||||
### Configuration
|
||||
|
||||
**Synchronization**:
|
||||
|
||||
- MCP sync across all apps
|
||||
- Gemini form-editor sync
|
||||
- Dual-file reading (.env + settings.json)
|
||||
|
||||
**Validation**:
|
||||
|
||||
- Input boundary checks
|
||||
- TOML quote normalization (CJK)
|
||||
- Custom field preservation
|
||||
- Enhanced error messages
|
||||
|
||||
### Code Quality
|
||||
|
||||
**Type Safety**:
|
||||
|
||||
- Complete TypeScript coverage
|
||||
- Rust type refinements
|
||||
- API contract validation
|
||||
|
||||
**Testing**:
|
||||
|
||||
- Simplified assertions
|
||||
- Better test coverage
|
||||
- Integration test updates
|
||||
|
||||
**Dependencies**:
|
||||
|
||||
- Tauri 2.8.x
|
||||
- Rust: `anyhow`, `zip`, `serde_yaml`, `tempfile`
|
||||
- Frontend: CodeMirror 6 packages
|
||||
- winreg 0.52 (Windows)
|
||||
|
||||
---
|
||||
|
||||
## Technical Statistics
|
||||
|
||||
```
|
||||
Total Changes:
|
||||
- Commits: 85
|
||||
- Files: 152 changed
|
||||
- Additions: +18,104 lines
|
||||
- Deletions: -3,732 lines
|
||||
|
||||
New Modules:
|
||||
- Skills Management: 2,034 lines (21 files)
|
||||
- Prompts Management: 1,302 lines (20 files)
|
||||
- Gemini Integration: ~1,000 lines
|
||||
- MCP Refactor: ~3,000 lines refactored
|
||||
|
||||
Code Distribution:
|
||||
- Backend (Rust): ~4,500 lines new
|
||||
- Frontend (React): ~3,000 lines new
|
||||
- Configuration: ~1,500 lines refactored
|
||||
- Tests: ~500 lines
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Strategic Positioning
|
||||
|
||||
### From Tool to Platform
|
||||
|
||||
v3.7.0 represents a shift in CC Switch's positioning:
|
||||
|
||||
| Aspect | v3.6 | v3.7.0 |
|
||||
| ----------------- | ------------------------ | ---------------------------- |
|
||||
| **Identity** | Provider Switcher | AI CLI Management Platform |
|
||||
| **Scope** | Configuration Management | Ecosystem Management |
|
||||
| **Applications** | Claude + Codex | Claude + Codex + Gemini |
|
||||
| **Capabilities** | Switch configs | Extend capabilities (Skills) |
|
||||
| **Customization** | Manual editing | Visual management (Prompts) |
|
||||
| **Integration** | Isolated apps | Unified management (MCP) |
|
||||
|
||||
### Six Pillars of AI CLI Management
|
||||
|
||||
1. **Configuration Management** - Provider switching and management
|
||||
2. **Capability Extension** - Skills installation and lifecycle
|
||||
3. **Behavior Customization** - System prompt presets
|
||||
4. **Ecosystem Integration** - Deep links and sharing
|
||||
5. **Multi-AI Support** - Claude/Codex/Gemini
|
||||
6. **Intelligent Detection** - Conflict prevention
|
||||
|
||||
---
|
||||
|
||||
## Download & Installation
|
||||
|
||||
### System Requirements
|
||||
|
||||
- **Windows**: Windows 10+
|
||||
- **macOS**: macOS 10.15 (Catalina)+
|
||||
- **Linux**: Ubuntu 22.04+ / Debian 11+ / Fedora 34+ / ArchLinux
|
||||
|
||||
### Download Links
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download:
|
||||
|
||||
- **Windows**: `CC-Switch-Windows.msi` or `-Portable.zip`
|
||||
- **macOS**: `CC-Switch-macOS.tar.gz` or `.zip`
|
||||
- **Linux**: `CC-Switch-Linux.AppImage` or `.deb`
|
||||
- **ArchLinux**: `paru -S cc-switch-bin`
|
||||
|
||||
### Homebrew (macOS)
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Notes
|
||||
|
||||
### From v3.6.x
|
||||
|
||||
**Automatic migration** - No action required, configs are fully compatible
|
||||
|
||||
### From v3.1.x or Earlier
|
||||
|
||||
**Two-step migration required**:
|
||||
|
||||
1. First upgrade to v3.2.x (performs one-time migration)
|
||||
2. Then upgrade to v3.7.0
|
||||
|
||||
### New Features
|
||||
|
||||
- **Skills**: No migration needed, start fresh
|
||||
- **Prompts**: Auto-import from live files on first launch
|
||||
- **Gemini**: Install Gemini CLI separately if needed
|
||||
- **MCP v3.7.0**: Backward compatible with previous configs
|
||||
|
||||
---
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
### Contributors
|
||||
|
||||
Thanks to all contributors who made this release possible:
|
||||
|
||||
- [@YoVinchen](https://github.com/YoVinchen) - Skills & Prompts & Gemini integration implementation
|
||||
- [@farion1231](https://github.com/farion1231) - From developer to issue responder
|
||||
- Community members for testing and feedback
|
||||
|
||||
### Sponsors
|
||||
|
||||
**Z.ai** - GLM CODING PLAN sponsor
|
||||
[Get 10% OFF with this link](https://z.ai/subscribe?ic=8JVLJQFSKB)
|
||||
|
||||
**PackyCode** - API relay service partner
|
||||
[Register with "cc-switch" code for 10% discount](https://www.packyapi.com/register?aff=cc-switch)
|
||||
|
||||
**ShanDianShuo** - Local-first AI voice input
|
||||
[Free download](https://shandianshuo.cn) for Mac/Win
|
||||
|
||||
---
|
||||
|
||||
## Feedback & Support
|
||||
|
||||
- **Issues**: [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/farion1231/cc-switch/discussions)
|
||||
- **Documentation**: [README](../README.md)
|
||||
- **Changelog**: [CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## What's Next
|
||||
|
||||
**v3.8.0 Preview** (Tentative):
|
||||
|
||||
- Local proxy functionality
|
||||
|
||||
Stay tuned for more updates!
|
||||
|
||||
---
|
||||
|
||||
**Happy Coding!**
|
||||
@@ -0,0 +1,481 @@
|
||||
# CC Switch v3.7.1
|
||||
|
||||
> 稳定性增强与用户体验改进
|
||||
|
||||
**[English Version →](v3.7.1-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## v3.7.1 更新内容
|
||||
|
||||
**发布日期**：2025-11-22
|
||||
**代码变更**：17 个文件，+524 / -81 行
|
||||
|
||||
### Bug 修复
|
||||
|
||||
- **修复 Skills 第三方仓库安装失败** (#268)
|
||||
修复使用自定义子目录的 skills 仓库无法安装的问题，支持类似 `ComposioHQ/awesome-claude-skills` 这样带子目录的仓库
|
||||
|
||||
- **修复 Gemini 配置持久化问题**
|
||||
解决在 Gemini 表单中编辑 settings.json 后，切换供应商时修改丢失的问题
|
||||
|
||||
- **防止对话框意外关闭**
|
||||
添加点击遮罩时的保护，避免误操作导致表单数据丢失，影响所有 11 个对话框组件
|
||||
|
||||
### 新增功能
|
||||
|
||||
- **Gemini 配置目录支持** (#255)
|
||||
在设置中添加 Gemini 配置目录选项，支持自定义 `~/.gemini/` 路径
|
||||
|
||||
- **ArchLinux 安装支持** (#259)
|
||||
添加 AUR 安装方式：`paru -S cc-switch-bin`
|
||||
|
||||
### 改进
|
||||
|
||||
- **Skills 错误消息国际化增强**
|
||||
新增 28+ 条详细错误消息（中英文），提供具体的解决建议，下载超时从 15 秒延长到 60 秒
|
||||
|
||||
- **代码格式化**
|
||||
应用统一的 Rust 和 TypeScript 代码格式化标准
|
||||
|
||||
### 下载
|
||||
|
||||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载最新版本
|
||||
|
||||
---
|
||||
|
||||
## v3.7.0 完整更新说明
|
||||
|
||||
> 从供应商切换器到 AI CLI 一体化管理平台
|
||||
|
||||
**发布日期**：2025-11-19
|
||||
**提交数量**：从 v3.6.0 开始 85 个提交
|
||||
**代码变更**：152 个文件，+18,104 / -3,732 行
|
||||
|
||||
---
|
||||
|
||||
## 新增功能
|
||||
|
||||
### Gemini CLI 集成
|
||||
|
||||
完整支持 Google Gemini CLI，成为第三个支持的应用（Claude Code、Codex、Gemini）。
|
||||
|
||||
**核心能力**：
|
||||
|
||||
- **双文件配置** - 同时支持 `.env` 和 `settings.json` 格式
|
||||
- **自动检测** - 自动检测 `GOOGLE_GEMINI_BASE_URL`、`GEMINI_MODEL` 等环境变量
|
||||
- **完整 MCP 支持** - 为 Gemini 提供完整的 MCP 服务器管理
|
||||
- **深度链接集成** - 通过 `ccswitch://` 协议导入配置
|
||||
- **系统托盘** - 从托盘菜单快速切换
|
||||
|
||||
**供应商预设**：
|
||||
|
||||
- **Google Official** - 支持 OAuth 认证
|
||||
- **PackyCode** - 合作伙伴集成
|
||||
- **自定义** - 完全自定义支持
|
||||
|
||||
**技术实现**：
|
||||
|
||||
- 新增后端模块：`gemini_config.rs`（20KB）、`gemini_mcp.rs`
|
||||
- 表单与环境编辑器同步
|
||||
- 双文件原子写入
|
||||
|
||||
---
|
||||
|
||||
### MCP v3.7.0 统一架构
|
||||
|
||||
MCP 管理系统完整重构，实现跨应用统一管理。
|
||||
|
||||
**架构改进**：
|
||||
|
||||
- **统一管理面板** - 单一界面管理 Claude/Codex/Gemini MCP 服务器
|
||||
- **SSE 传输类型** - 新增 Server-Sent Events 支持
|
||||
- **智能解析器** - 容错性 JSON 解析
|
||||
- **格式修正** - 自动修复 Codex `[mcp_servers]` 格式
|
||||
- **扩展字段** - 保留自定义 TOML 字段
|
||||
|
||||
**用户体验**：
|
||||
|
||||
- 表单中的默认应用选择
|
||||
- JSON 格式化器用于验证
|
||||
- 改进的视觉层次
|
||||
- 更好的错误消息
|
||||
|
||||
**导入/导出**：
|
||||
|
||||
- 统一从三个应用导入
|
||||
- 双向同步
|
||||
- 状态保持
|
||||
|
||||
---
|
||||
|
||||
### Claude Skills 管理系统
|
||||
|
||||
**约 2,000 行代码** - 完整的技能生态平台。
|
||||
|
||||
**GitHub 集成**：
|
||||
|
||||
- 从 GitHub 仓库自动扫描技能
|
||||
- 预配置仓库：
|
||||
- `ComposioHQ/awesome-claude-skills` - 精选集合
|
||||
- `anthropics/skills` - Anthropic 官方技能
|
||||
- `cexll/myclaude` - 社区贡献
|
||||
- 添加自定义仓库
|
||||
- 子目录扫描支持（`skillsPath`）
|
||||
|
||||
**生命周期管理**：
|
||||
|
||||
- **发现** - 自动检测 `SKILL.md` 文件
|
||||
- **安装** - 一键安装到 `~/.claude/skills/`
|
||||
- **卸载** - 安全移除并跟踪状态
|
||||
- **更新** - 检查更新（基础设施已就绪）
|
||||
|
||||
**技术架构**：
|
||||
|
||||
- **后端**：`SkillService`（526 行）集成 GitHub API
|
||||
- **前端**：SkillsPage、SkillCard、RepoManager
|
||||
- **UI 组件**：Badge、Card、Table（shadcn/ui）
|
||||
- **状态**：持久化存储在 `config.json`
|
||||
- **国际化**：47+ 个翻译键
|
||||
|
||||
---
|
||||
|
||||
### Prompts 管理系统
|
||||
|
||||
**约 1,300 行代码** - 完整的系统提示词管理。
|
||||
|
||||
**多预设管理**：
|
||||
|
||||
- 创建无限数量的提示词预设
|
||||
- 快速在预设间切换
|
||||
- 同时只能激活一个提示词
|
||||
- 活动提示词删除保护
|
||||
|
||||
**跨应用支持**：
|
||||
|
||||
- **Claude**：`~/.claude/CLAUDE.md`
|
||||
- **Codex**：`~/.codex/AGENTS.md`
|
||||
- **Gemini**：`~/.gemini/GEMINI.md`
|
||||
|
||||
**Markdown 编辑器**：
|
||||
|
||||
- 完整的 CodeMirror 6 集成
|
||||
- 语法高亮
|
||||
- 暗色主题（One Dark）
|
||||
- 实时预览
|
||||
|
||||
**智能同步**：
|
||||
|
||||
- **自动写入** - 立即写入 live 文件
|
||||
- **回填保护** - 切换前保存当前内容
|
||||
- **自动导入** - 首次启动从 live 文件导入
|
||||
- **修改保护** - 保留手动修改
|
||||
|
||||
**技术实现**：
|
||||
|
||||
- **后端**：`PromptService`（213 行）
|
||||
- **前端**：PromptPanel（177）、PromptFormModal（160）、MarkdownEditor（159）
|
||||
- **Hooks**：usePromptActions（152 行）
|
||||
- **国际化**：41+ 个翻译键
|
||||
|
||||
---
|
||||
|
||||
### 深度链接协议（ccswitch://）
|
||||
|
||||
通过 URL 方案一键导入供应商配置。
|
||||
|
||||
**功能特性**：
|
||||
|
||||
- 所有平台的协议注册
|
||||
- 从共享链接导入
|
||||
- 生命周期集成
|
||||
- 安全验证
|
||||
|
||||
---
|
||||
|
||||
### 环境变量冲突检测
|
||||
|
||||
智能检测和管理配置冲突。
|
||||
|
||||
**检测范围**：
|
||||
|
||||
- **Claude & Codex** - 跨应用冲突
|
||||
- **Gemini** - 自动发现
|
||||
- **MCP** - 服务器配置冲突
|
||||
|
||||
**管理功能**：
|
||||
|
||||
- 可视化冲突指示器
|
||||
- 解决建议
|
||||
- 覆盖警告
|
||||
- 更改前备份
|
||||
|
||||
---
|
||||
|
||||
## 改进优化
|
||||
|
||||
### 供应商管理
|
||||
|
||||
**新增预设**：
|
||||
|
||||
- **DouBaoSeed** - 字节跳动的豆包
|
||||
- **Kimi For Coding** - 月之暗面
|
||||
- **BaiLing** - 百灵 AI
|
||||
- **移除 AnyRouter** - 避免误导
|
||||
|
||||
**增强功能**：
|
||||
|
||||
- Codex 和 Gemini 的模型名称配置
|
||||
- 供应商备注字段用于组织
|
||||
- 增强的预设元数据
|
||||
|
||||
### 配置管理
|
||||
|
||||
- **通用配置迁移** - 从 localStorage 迁移到 `config.json`
|
||||
- **统一持久化** - 跨所有应用共享
|
||||
- **自动导入** - 首次启动配置导入
|
||||
- **回填优先级** - 正确处理 live 文件
|
||||
|
||||
### UI/UX 改进
|
||||
|
||||
**设计系统**：
|
||||
|
||||
- **macOS 原生** - 与系统对齐的配色方案
|
||||
- **窗口居中** - 默认居中位置
|
||||
- **视觉优化** - 改进的间距和层次
|
||||
|
||||
**交互优化**：
|
||||
|
||||
- **密码输入** - 修复 Edge/IE 显示按钮
|
||||
- **URL 溢出** - 修复卡片溢出
|
||||
- **错误复制** - 可复制到剪贴板的错误
|
||||
- **托盘同步** - 实时拖放同步
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 关键修复
|
||||
|
||||
- **用量脚本验证** - 边界检查
|
||||
- **Gemini 验证** - 放宽约束
|
||||
- **TOML 解析** - CJK 引号处理
|
||||
- **MCP 字段** - 自定义字段保留
|
||||
- **白屏** - FormLabel 崩溃修复
|
||||
|
||||
### 稳定性
|
||||
|
||||
- **托盘安全** - 模式匹配替代 unwrap
|
||||
- **错误隔离** - 托盘失败不阻塞操作
|
||||
- **导入分类** - 正确的类别分配
|
||||
|
||||
### UI 修复
|
||||
|
||||
- **模型占位符** - 移除误导性提示
|
||||
- **Base URL** - 第三方供应商自动填充
|
||||
- **拖拽排序** - 托盘菜单同步
|
||||
|
||||
---
|
||||
|
||||
## 技术改进
|
||||
|
||||
### 架构
|
||||
|
||||
**MCP v3.7.0**：
|
||||
|
||||
- 移除遗留代码（约 1,000 行）
|
||||
- 统一初始化结构
|
||||
- 保持向后兼容性
|
||||
- 全面的代码格式化
|
||||
|
||||
**平台兼容性**：
|
||||
|
||||
- Windows winreg API 修复（v0.52）
|
||||
- 安全模式匹配（无 `unwrap()`）
|
||||
- 跨平台托盘处理
|
||||
|
||||
### 配置
|
||||
|
||||
**同步机制**：
|
||||
|
||||
- 跨所有应用的 MCP 同步
|
||||
- Gemini 表单-编辑器同步
|
||||
- 双文件读取（.env + settings.json）
|
||||
|
||||
**验证增强**：
|
||||
|
||||
- 输入边界检查
|
||||
- TOML 引号规范化（CJK）
|
||||
- 自定义字段保留
|
||||
- 增强的错误消息
|
||||
|
||||
### 代码质量
|
||||
|
||||
**类型安全**：
|
||||
|
||||
- 完整的 TypeScript 覆盖
|
||||
- Rust 类型改进
|
||||
- API 契约验证
|
||||
|
||||
**测试**：
|
||||
|
||||
- 简化的断言
|
||||
- 更好的测试覆盖
|
||||
- 集成测试更新
|
||||
|
||||
**依赖项**：
|
||||
|
||||
- Tauri 2.8.x
|
||||
- Rust：`anyhow`、`zip`、`serde_yaml`、`tempfile`
|
||||
- 前端：CodeMirror 6 包
|
||||
- winreg 0.52（Windows）
|
||||
|
||||
---
|
||||
|
||||
## 技术统计
|
||||
|
||||
```
|
||||
总体变更：
|
||||
- 提交数：85
|
||||
- 文件数：152 个文件变更
|
||||
- 新增：+18,104 行
|
||||
- 删除：-3,732 行
|
||||
|
||||
新增模块：
|
||||
- Skills 管理：2,034 行（21 个文件）
|
||||
- Prompts 管理：1,302 行（20 个文件）
|
||||
- Gemini 集成：约 1,000 行
|
||||
- MCP 重构：约 3,000 行重构
|
||||
|
||||
代码分布：
|
||||
- 后端（Rust）：约 4,500 行新增
|
||||
- 前端（React）：约 3,000 行新增
|
||||
- 配置：约 1,500 行重构
|
||||
- 测试：约 500 行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 战略定位
|
||||
|
||||
### 从工具到平台
|
||||
|
||||
v3.7.0 代表了 CC Switch 定位的转变：
|
||||
|
||||
| 方面 | v3.6 | v3.7.0 |
|
||||
| -------- | -------------- | ----------------------- |
|
||||
| **身份** | 供应商切换器 | AI CLI 管理平台 |
|
||||
| **范围** | 配置管理 | 生态系统管理 |
|
||||
| **应用** | Claude + Codex | Claude + Codex + Gemini |
|
||||
| **能力** | 切换配置 | 扩展能力（Skills） |
|
||||
| **定制** | 手动编辑 | 可视化管理（Prompts） |
|
||||
| **集成** | 孤立应用 | 统一管理（MCP） |
|
||||
|
||||
### AI CLI 管理六大支柱
|
||||
|
||||
1. **配置管理** - 供应商切换和管理
|
||||
2. **能力扩展** - Skills 安装和生命周期
|
||||
3. **行为定制** - 系统提示词预设
|
||||
4. **生态集成** - 深度链接和共享
|
||||
5. **多 AI 支持** - Claude/Codex/Gemini
|
||||
6. **智能检测** - 冲突预防
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
### 系统要求
|
||||
|
||||
- **Windows**：Windows 10+
|
||||
- **macOS**：macOS 10.15（Catalina）+
|
||||
- **Linux**：Ubuntu 22.04+ / Debian 11+ / Fedora 34+ / ArchLinux
|
||||
|
||||
### 下载链接
|
||||
|
||||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载：
|
||||
|
||||
- **Windows**：`CC-Switch-Windows.msi` 或 `-Portable.zip`
|
||||
- **macOS**：`CC-Switch-macOS.tar.gz` 或 `.zip`
|
||||
- **Linux**：`CC-Switch-Linux.AppImage` 或 `.deb`
|
||||
- **ArchLinux**：`paru -S cc-switch-bin`
|
||||
|
||||
### Homebrew（macOS）
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 迁移说明
|
||||
|
||||
### 从 v3.6.x 升级
|
||||
|
||||
**自动迁移** - 无需任何操作，配置完全兼容
|
||||
|
||||
### 从 v3.1.x 或更早版本升级
|
||||
|
||||
**需要两步迁移**：
|
||||
|
||||
1. 首先升级到 v3.2.x（执行一次性迁移）
|
||||
2. 然后升级到 v3.7.0
|
||||
|
||||
### 新功能
|
||||
|
||||
- **Skills**：无需迁移，全新开始
|
||||
- **Prompts**：首次启动时从 live 文件自动导入
|
||||
- **Gemini**：需要单独安装 Gemini CLI
|
||||
- **MCP v3.7.0**：与之前的配置向后兼容
|
||||
|
||||
---
|
||||
|
||||
## 致谢
|
||||
|
||||
### 贡献者
|
||||
|
||||
感谢所有让这个版本成为可能的贡献者：
|
||||
|
||||
- [@YoVinchen](https://github.com/YoVinchen) - Skills & Prompts & Gemini 集成实现
|
||||
- [@farion1231](https://github.com/farion1231) - 从开发沦为 issue 回复机
|
||||
- 社区成员的测试和反馈
|
||||
|
||||
### 赞助商
|
||||
|
||||
**智谱AI** - GLM CODING PLAN 赞助商
|
||||
[使用此链接购买可享九折优惠](https://www.bigmodel.cn/claude-code?ic=RRVJPB5SII)
|
||||
|
||||
**PackyCode** - API 中转服务合作伙伴
|
||||
[使用 "cc-switch" 优惠码注册享 9 折优惠](https://www.packyapi.com/register?aff=cc-switch)
|
||||
|
||||
**闪电说** - 本地优先的 AI 语音输入法
|
||||
[免费下载](https://shandianshuo.cn) Mac/Win 双平台
|
||||
|
||||
---
|
||||
|
||||
## 反馈与支持
|
||||
|
||||
- **问题反馈**：[GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- **讨论**：[GitHub Discussions](https://github.com/farion1231/cc-switch/discussions)
|
||||
- **文档**：[README](../README_ZH.md)
|
||||
- **更新日志**：[CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## 未来展望
|
||||
|
||||
**v3.8.0 预览**（暂定）：
|
||||
|
||||
- 本地代理功能
|
||||
|
||||
敬请期待更多更新！
|
||||
|
||||
---
|
||||
|
||||
**Happy Coding!**
|
||||
@@ -0,0 +1,369 @@
|
||||
# CC Switch v3.8.0
|
||||
|
||||
> Persistence Architecture Upgrade, Laying the Foundation for Cloud Sync
|
||||
|
||||
**[中文版 →](v3.8.0-zh.md) | [日本語版 →](v3.8.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.8.0 is a major architectural upgrade that restructures the data persistence layer and user interface, laying the foundation for future cloud sync and local proxy features.
|
||||
|
||||
**Release Date**: 2025-11-28
|
||||
**Commits**: 51 commits since v3.7.1
|
||||
**Code Changes**: 207 files, +17,297 / -6,870 lines
|
||||
|
||||
---
|
||||
|
||||
## Major Updates
|
||||
|
||||
### Persistence Architecture Upgrade
|
||||
|
||||
Migrated from single JSON file storage to SQLite + JSON dual-layer architecture for hierarchical data management.
|
||||
|
||||
**Architecture Changes**:
|
||||
|
||||
```
|
||||
v3.7.x (Old) v3.8.0 (New)
|
||||
┌─────────────────┐ ┌─────────────────────────────────┐
|
||||
│ config.json │ │ SQLite (Syncable Data) │
|
||||
│ ┌───────────┐ │ │ ├─ providers Provider cfg │
|
||||
│ │ providers │ │ │ ├─ mcp_servers MCP servers │
|
||||
│ │ mcp │ │ ──> │ ├─ prompts Prompts │
|
||||
│ │ prompts │ │ │ ├─ skills Skills │
|
||||
│ │ settings │ │ │ └─ settings General cfg │
|
||||
│ └───────────┘ │ ├─────────────────────────────────┤
|
||||
└─────────────────┘ │ JSON (Device-level Data) │
|
||||
│ └─ settings.json Local settings│
|
||||
│ ├─ Window position │
|
||||
│ ├─ Path overrides │
|
||||
│ └─ Current provider ID │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Dual-layer Structure Design**:
|
||||
|
||||
| Layer | Storage | Data Types | Sync Strategy |
|
||||
| ---------- | ------- | ------------------------------- | --------------- |
|
||||
| Cloud Sync | SQLite | Providers, MCP, Prompts, Skills | Future syncable |
|
||||
| Device | JSON | Window state, local paths | Stays local |
|
||||
|
||||
**Technical Implementation**:
|
||||
|
||||
- **Schema Version Management** - Supports database structure upgrade migrations
|
||||
- **SQL Import/Export** - `backup.rs` supports SQL dump for cloud storage
|
||||
- **Transaction Support** - SQLite native transactions ensure data consistency
|
||||
- **Auto Migration** - Automatically migrates from `config.json` on first launch
|
||||
|
||||
**Modular Refactoring**:
|
||||
|
||||
```
|
||||
database/
|
||||
├── mod.rs Core Database struct and initialization
|
||||
├── schema.rs Table definitions, schema version migrations
|
||||
├── backup.rs SQL import/export, binary snapshot backup
|
||||
├── migration.rs JSON → SQLite data migration engine
|
||||
└── dao/ Data Access Object layer
|
||||
├── providers.rs Provider CRUD
|
||||
├── mcp.rs MCP server CRUD
|
||||
├── prompts.rs Prompts CRUD
|
||||
├── skills.rs Skills CRUD
|
||||
└── settings.rs Key-value settings storage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Brand New User Interface
|
||||
|
||||
Completely redesigned UI providing a more modern visual experience.
|
||||
|
||||
**Visual Improvements**:
|
||||
|
||||
- Redesigned interface layout
|
||||
- Unified component styles
|
||||
- Smoother transition animations
|
||||
- Optimized visual hierarchy
|
||||
|
||||
**Interaction Enhancements**:
|
||||
|
||||
- Redesigned header toolbar
|
||||
- Unified ConfirmDialog styling
|
||||
- Disabled overscroll bounce effect on main view
|
||||
- Improved form validation feedback
|
||||
|
||||
**Compatibility Adjustments**:
|
||||
|
||||
- Downgraded Tailwind CSS from v4 to v3.4 for better browser compatibility
|
||||
|
||||
---
|
||||
|
||||
### Japanese Language Support
|
||||
|
||||
Added Japanese interface support, expanding internationalization to three languages.
|
||||
|
||||
**Supported Languages**:
|
||||
|
||||
- Simplified Chinese
|
||||
- English
|
||||
- Japanese (New)
|
||||
|
||||
---
|
||||
|
||||
## New Features
|
||||
|
||||
### Skills Recursive Scanning
|
||||
|
||||
Skills management system now supports recursive scanning of repository directories, automatically discovering nested skill files.
|
||||
|
||||
**Improvements**:
|
||||
|
||||
- Support for multi-level directory structures
|
||||
- Automatic discovery of all `SKILL.md` files
|
||||
- Allow same-named skills from different repositories (using full path for deduplication)
|
||||
|
||||
---
|
||||
|
||||
### Provider Icon Configuration
|
||||
|
||||
Provider presets now support custom icon configuration.
|
||||
|
||||
**Features**:
|
||||
|
||||
- Preset providers include default icons
|
||||
- Icon settings preserved when duplicating providers
|
||||
- Custom icon colors
|
||||
|
||||
---
|
||||
|
||||
### Enhanced Form Validation
|
||||
|
||||
Provider forms now include required field validation with friendlier error messages.
|
||||
|
||||
**Improvements**:
|
||||
|
||||
- Real-time validation for required fields
|
||||
- Unified Toast notifications for validation errors
|
||||
- Clearer error messages
|
||||
|
||||
---
|
||||
|
||||
### Auto Launch on Startup
|
||||
|
||||
Added auto-launch functionality supporting Windows, macOS, and Linux platforms.
|
||||
|
||||
**Features**:
|
||||
|
||||
- One-click enable/disable in settings
|
||||
- Implemented using platform-native APIs
|
||||
- Windows uses Registry, macOS uses LaunchAgent, Linux uses XDG autostart
|
||||
|
||||
---
|
||||
|
||||
### New Provider Presets
|
||||
|
||||
- **MiniMax** - Official partner
|
||||
|
||||
---
|
||||
|
||||
## Bug Fixes
|
||||
|
||||
### Critical Fixes
|
||||
|
||||
**Custom Endpoints Lost Issue**
|
||||
|
||||
Fixed an issue where custom request URLs were unexpectedly lost when updating providers.
|
||||
|
||||
- Root Cause: `INSERT OR REPLACE` executes `DELETE + INSERT` under the hood in SQLite, triggering foreign key cascade deletion
|
||||
- Fix: Changed to use `UPDATE` statement for existing providers
|
||||
|
||||
**Gemini Configuration Issues**
|
||||
|
||||
- Fixed custom provider environment variables not correctly written to `.env` file
|
||||
- Fixed security auth config incorrectly written to other config files
|
||||
|
||||
**Provider Validation Issues**
|
||||
|
||||
- Fixed validation error when current provider ID doesn't exist
|
||||
- Fixed icon fields lost when duplicating providers
|
||||
|
||||
### Platform Compatibility
|
||||
|
||||
**Linux**
|
||||
|
||||
- Resolved WebKitGTK DMA-BUF rendering issue
|
||||
- Preserve user `.desktop` file customizations
|
||||
|
||||
### Other Fixes
|
||||
|
||||
- Fixed redundant usage queries when switching apps
|
||||
- Fixed DMXAPI preset using wrong auth token field
|
||||
- Fixed missing translation keys in deeplink components
|
||||
- Fixed usage script template initialization logic
|
||||
|
||||
---
|
||||
|
||||
## Technical Improvements
|
||||
|
||||
### Architecture Refactoring
|
||||
|
||||
**Provider Service Modularization**:
|
||||
|
||||
```
|
||||
services/provider/
|
||||
├── mod.rs Core service - add/update/delete/switch/validate
|
||||
├── live.rs Live config file operations
|
||||
├── gemini_auth.rs Gemini auth type detection
|
||||
├── endpoints.rs Custom endpoint management
|
||||
└── usage.rs Usage script execution
|
||||
```
|
||||
|
||||
**Deeplink Modularization**:
|
||||
|
||||
```
|
||||
deeplink/
|
||||
├── mod.rs Module exports
|
||||
├── parser.rs URL parsing
|
||||
├── provider.rs Provider import logic
|
||||
├── mcp.rs MCP import logic
|
||||
├── prompt.rs Prompt import
|
||||
├── skill.rs Skills import
|
||||
└── utils.rs Utility functions
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
**Cleanup**:
|
||||
|
||||
- Removed legacy JSON-era import/export dead code
|
||||
- Removed unused MCP type exports
|
||||
- Unified error handling approach
|
||||
|
||||
**Test Updates**:
|
||||
|
||||
- Migrated tests to SQLite database architecture
|
||||
- Updated component tests to match current implementation
|
||||
- Fixed MSW handlers to adapt to new API
|
||||
|
||||
---
|
||||
|
||||
## Technical Statistics
|
||||
|
||||
```
|
||||
Overall Changes:
|
||||
- Commits: 51
|
||||
- Files: 207 files changed
|
||||
- Additions: +17,297 lines
|
||||
- Deletions: -6,870 lines
|
||||
- Net: +10,427 lines
|
||||
|
||||
Commit Type Distribution:
|
||||
- fix: 25 (Bug fixes)
|
||||
- refactor: 11 (Code refactoring)
|
||||
- feat: 9 (New features)
|
||||
- test: 1 (Testing)
|
||||
- other: 5
|
||||
|
||||
Change Area Distribution:
|
||||
- Frontend source: 112 files
|
||||
- Rust backend: 63 files
|
||||
- Test files: 20 files
|
||||
- i18n files: 3 files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### Upgrading from v3.7.x
|
||||
|
||||
**Auto Migration** - Executes automatically on first launch:
|
||||
|
||||
1. Detects if `config.json` exists
|
||||
2. Migrates all data to SQLite within a transaction
|
||||
3. Migrates device-level settings to `settings.json`
|
||||
4. Shows migration success notification
|
||||
|
||||
**Data Safety**:
|
||||
|
||||
- Original `config.json` file is preserved (not deleted)
|
||||
- Error dialog displayed on migration failure, `config.json` preserved
|
||||
- Supports Dry-run mode to verify migration logic
|
||||
|
||||
---
|
||||
|
||||
## Download & Installation
|
||||
|
||||
### System Requirements
|
||||
|
||||
- **Windows**: Windows 10+
|
||||
- **macOS**: macOS 10.15 (Catalina)+
|
||||
- **Linux**: Ubuntu 22.04+ / Debian 11+ / Fedora 34+
|
||||
|
||||
### Download Links
|
||||
|
||||
Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download:
|
||||
|
||||
- **Windows**: `CC-Switch-v3.8.0-Windows.msi` or `-Portable.zip`
|
||||
- **macOS**: `CC-Switch-v3.8.0-macOS.tar.gz` or `.zip`
|
||||
- **Linux**: `CC-Switch-v3.8.0-Linux.AppImage` or `.deb`
|
||||
|
||||
### Homebrew (macOS)
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
Update:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
### Contributors
|
||||
|
||||
Thanks to all contributors who made this release possible:
|
||||
|
||||
- [@YoVinchen](https://github.com/YoVinchen) - UI and database refactoring
|
||||
- [@farion1231](https://github.com/farion1231) - Bug fixes and feature enhancements
|
||||
- Community members for testing and feedback
|
||||
|
||||
### Sponsors
|
||||
|
||||
**Zhipu AI** - GLM CODING PLAN Sponsor
|
||||
[Get 10% off with this link](https://z.ai/subscribe?ic=8JVLJQFSKB)
|
||||
|
||||
**PackyCode** - API Relay Service Partner
|
||||
[Use code "cc-switch" for 10% off registration](https://www.packyapi.com/register?aff=cc-switch)
|
||||
|
||||
**ShandianShuo** - Local-first AI Voice Input
|
||||
[Free download](https://shandianshuo.cn) for Mac/Windows
|
||||
|
||||
**MiniMax** - MiniMax M2 CODING PLAN Sponsor
|
||||
[Black Friday sale, plans starting at $2](https://platform.minimax.io/subscribe/coding-plan)
|
||||
|
||||
---
|
||||
|
||||
## Feedback & Support
|
||||
|
||||
- **Issue Reports**: [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/farion1231/cc-switch/discussions)
|
||||
- **Documentation**: [README](../README.md)
|
||||
- **Changelog**: [CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## Future Roadmap
|
||||
|
||||
**v3.9.0 Preview** (Tentative):
|
||||
|
||||
- Local proxy feature
|
||||
|
||||
Stay tuned for more updates!
|
||||
|
||||
---
|
||||
|
||||
**Happy Coding!**
|
||||
@@ -0,0 +1,315 @@
|
||||
# CC Switch v3.8.0
|
||||
|
||||
> 永続化アーキテクチャを刷新し、クラウド同期の土台を構築
|
||||
|
||||
**[English →](v3.8.0-en.md) | [中文版 →](v3.8.0-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.8.0 はデータ永続化レイヤーと UI を大幅に作り替え、今後のクラウド同期やローカルプロキシ機能に向けた基盤を整えたメジャーアップデートです。
|
||||
|
||||
**リリース日**: 2025-11-28
|
||||
**コミット数**: v3.7.1 以降 51 commits
|
||||
**変更量**: 207 files, +17,297 / -6,870 lines
|
||||
|
||||
---
|
||||
|
||||
## 主要アップデート
|
||||
|
||||
### 永続化アーキテクチャの刷新
|
||||
|
||||
単一の JSON 保存から、階層化された SQLite + JSON の二層構造へ移行。
|
||||
|
||||
**アーキテクチャ変更**:
|
||||
|
||||
```
|
||||
v3.7.x (旧) v3.8.0 (新)
|
||||
┌─────────────────┐ ┌─────────────────────────────────┐
|
||||
│ config.json │ │ SQLite (同期対象データ) │
|
||||
│ ┌───────────┐ │ │ ├─ providers プロバイダ設定 │
|
||||
│ │ providers │ │ │ ├─ mcp_servers MCP サーバー │
|
||||
│ │ mcp │ │ ──> │ ├─ prompts プロンプト │
|
||||
│ │ prompts │ │ │ ├─ skills Skills │
|
||||
│ │ settings │ │ │ └─ settings 汎用設定 │
|
||||
│ └───────────┘ │ ├─────────────────────────────────┤
|
||||
└─────────────────┘ │ JSON (デバイス固有データ) │
|
||||
│ └─ settings.json ローカル設定 │
|
||||
│ ├─ ウィンドウ位置 │
|
||||
│ ├─ パスの上書き │
|
||||
│ └─ 現在のプロバイダ ID │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
**二層構造の設計**:
|
||||
|
||||
| レイヤー | ストレージ | データ種別 | 同期戦略 |
|
||||
| -------- | ---------- | ----------------------------------- | ---------------- |
|
||||
| クラウド | SQLite | Providers, MCP, Prompts, Skills | 将来同期対象 |
|
||||
| デバイス | JSON | ウィンドウ状態、ローカルパス | ローカル保持 |
|
||||
|
||||
**実装ポイント**:
|
||||
|
||||
- **スキーマバージョン管理**: DB 構造のマイグレーションに対応
|
||||
- **SQL インポート/エクスポート**: `backup.rs` が SQL ダンプをサポート
|
||||
- **トランザクション対応**: SQLite ネイティブで整合性を確保
|
||||
- **自動マイグレーション**: 初回起動で `config.json` から自動移行
|
||||
|
||||
**モジュール分割**:
|
||||
|
||||
```
|
||||
database/
|
||||
├── mod.rs Database 構造体と初期化
|
||||
├── schema.rs テーブル定義とスキーマ移行
|
||||
├── backup.rs SQL インポート/エクスポートとスナップショット
|
||||
├── migration.rs JSON → SQLite 変換エンジン
|
||||
└── dao/ DAO レイヤー
|
||||
├── providers.rs プロバイダ CRUD
|
||||
├── mcp.rs MCP CRUD
|
||||
├── prompts.rs プロンプト CRUD
|
||||
├── skills.rs Skills CRUD
|
||||
└── settings.rs 設定 Key-Value 保存
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 新しいユーザーインターフェース
|
||||
|
||||
よりモダンな見た目と操作感に再設計。
|
||||
|
||||
- レイアウト全面刷新、コンポーネントスタイルを統一
|
||||
- トランジションを滑らかにし、視覚的階層を最適化
|
||||
- メインビューのオーバースクロールバウンスを無効化
|
||||
- ブラウザ互換性向上のため Tailwind CSS を v4→v3.4 にダウングレード
|
||||
|
||||
---
|
||||
|
||||
### 日語化
|
||||
|
||||
UI が日本語に対応し、国際化が 3 言語（中/英/日）へ拡大。
|
||||
|
||||
---
|
||||
|
||||
## 新機能
|
||||
|
||||
### Skills 递帰スキャン
|
||||
|
||||
Skills 管理がリポジトリを再帰的に走査し、ネストされた `SKILL.md` を自動検出。
|
||||
|
||||
- 複数階層のディレクトリに対応
|
||||
- すべての `SKILL.md` を自動発見
|
||||
- パスをキーにした重複排除で同名スキルを許容
|
||||
|
||||
### プロバイダアイコン設定
|
||||
|
||||
プリセットがデフォルトアイコンを持ち、複製してもアイコンを保持。カスタム色も設定可能。
|
||||
|
||||
### フォームバリデーション強化
|
||||
|
||||
必須項目にリアルタイム検証と分かりやすいエラーメッセージを追加し、トースト通知を統一。
|
||||
|
||||
### 自動起動
|
||||
|
||||
Windows/macOS/Linux で自動起動をサポート。
|
||||
|
||||
- 設定画面からワンクリックで ON/OFF
|
||||
- Registry / LaunchAgent / XDG autostart を使用
|
||||
|
||||
### 新プロバイダプリセット
|
||||
|
||||
- **MiniMax** - 公式パートナー
|
||||
|
||||
---
|
||||
|
||||
## バグ修正
|
||||
|
||||
### 重要修正
|
||||
|
||||
**カスタムエンドポイント消失**
|
||||
|
||||
- 原因: SQLite の `INSERT OR REPLACE` が内部で `DELETE + INSERT` を実行し、外部キーのカスケード削除が発生
|
||||
- 対応: 既存プロバイダ更新を `UPDATE` に変更
|
||||
|
||||
**Gemini 設定**
|
||||
|
||||
- カスタム環境変数が `.env` に正しく書き込まれない問題を修正
|
||||
- 認証設定が他ファイルに誤って書き込まれる問題を修正
|
||||
|
||||
**プロバイダ検証**
|
||||
|
||||
- 現在プロバイダ ID が欠落している場合のバリデーションエラーを修正
|
||||
- 複製時にアイコンフィールドが失われる問題を修正
|
||||
|
||||
### プラットフォーム互換性
|
||||
|
||||
**Linux**
|
||||
|
||||
- WebKitGTK の DMA-BUF 描画問題を解消
|
||||
- ユーザーの `.desktop` カスタマイズを保持
|
||||
|
||||
### その他修正
|
||||
|
||||
- アプリ切り替え時の不要な使用量クエリを削減
|
||||
- DMXAPI プリセットの誤ったトークンフィールドを修正
|
||||
- Deeplink コンポーネントの欠損翻訳キーを補完
|
||||
- 使用量スクリプトテンプレート初期化を修正
|
||||
|
||||
---
|
||||
|
||||
## 技術的改善
|
||||
|
||||
### アーキテクチャ再編
|
||||
|
||||
**Provider Service のモジュール化**:
|
||||
|
||||
```
|
||||
services/provider/
|
||||
├── mod.rs 追加/更新/削除/切替/検証の中核
|
||||
├── live.rs ライブ設定ファイル操作
|
||||
├── gemini_auth.rs Gemini 認証タイプ検出
|
||||
├── endpoints.rs カスタムエンドポイント管理
|
||||
└── usage.rs 使用量スクリプト実行
|
||||
```
|
||||
|
||||
**Deeplink のモジュール化**:
|
||||
|
||||
```
|
||||
deeplink/
|
||||
├── mod.rs エクスポート
|
||||
├── parser.rs URL パース
|
||||
├── provider.rs プロバイダ取り込み
|
||||
├── mcp.rs MCP 取り込み
|
||||
├── prompt.rs プロンプト取り込み
|
||||
├── skill.rs Skills 取り込み
|
||||
└── utils.rs ユーティリティ
|
||||
```
|
||||
|
||||
### コード品質
|
||||
|
||||
- レガシーな JSON 時代のインポート/エクスポート死蔵コードを削除
|
||||
- 使われていない MCP 型を削除し、エラーハンドリングを統一
|
||||
- テストを SQLite バックエンドに移行し、MSW ハンドラを最新 API に合わせて更新
|
||||
|
||||
---
|
||||
|
||||
## 技術統計
|
||||
|
||||
```
|
||||
全体変更:
|
||||
- コミット: 51
|
||||
- 変更ファイル: 207
|
||||
- 追加: +17,297 行
|
||||
- 削除: -6,870 行
|
||||
- 純増: +10,427 行
|
||||
|
||||
コミット種別:
|
||||
- fix: 25
|
||||
- refactor: 11
|
||||
- feat: 9
|
||||
- test: 1
|
||||
- other: 5
|
||||
|
||||
変更箇所:
|
||||
- フロントエンド: 112 files
|
||||
- Rust バックエンド: 63 files
|
||||
- テスト: 20 files
|
||||
- i18n: 3 files
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## マイグレーションガイド
|
||||
|
||||
### v3.7.x からのアップグレード
|
||||
|
||||
**自動マイグレーション**（初回起動時）:
|
||||
|
||||
1. `config.json` の存在を検出
|
||||
2. 全データをトランザクションで SQLite に移行
|
||||
3. デバイス設定を `settings.json` へ移行
|
||||
4. 移行成功の通知を表示
|
||||
|
||||
**データ保護**:
|
||||
|
||||
- 元の `config.json` は保持（削除しない）
|
||||
- 失敗時はエラーダイアログを表示し、`config.json` を温存
|
||||
- Dry-run モードで検証可能
|
||||
|
||||
---
|
||||
|
||||
## ダウンロード & インストール
|
||||
|
||||
### システム要件
|
||||
|
||||
- **Windows**: Windows 10+
|
||||
- **macOS**: macOS 10.15 (Catalina)+
|
||||
- **Linux**: Ubuntu 22.04+ / Debian 11+ / Fedora 34+
|
||||
|
||||
### ダウンロード
|
||||
|
||||
[Releases](https://github.com/farion1231/cc-switch/releases/latest) から入手:
|
||||
|
||||
- **Windows**: `CC-Switch-v3.8.0-Windows.msi` または `-Portable.zip`
|
||||
- **macOS**: `CC-Switch-v3.8.0-macOS.tar.gz` または `.zip`
|
||||
- **Linux**: `CC-Switch-v3.8.0-Linux.AppImage` または `.deb`
|
||||
|
||||
### Homebrew (macOS)
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
アップデート:
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 謝辞
|
||||
|
||||
### コントリビューター
|
||||
|
||||
- [@YoVinchen](https://github.com/YoVinchen) - UI とデータベースリファクタ
|
||||
- [@farion1231](https://github.com/farion1231) - バグ修正と機能拡張
|
||||
- コミュニティの皆さん - テストとフィードバック
|
||||
|
||||
### スポンサー
|
||||
|
||||
**Zhipu AI** - GLM CODING PLAN スポンサー
|
||||
[10% オフリンク](https://z.ai/subscribe?ic=8JVLJQFSKB)
|
||||
|
||||
**PackyCode** - API リレーサービスパートナー
|
||||
[登録時に「cc-switch」で 10% オフ](https://www.packyapi.com/register?aff=cc-switch)
|
||||
|
||||
**ShandianShuo** - ローカルファースト音声入力
|
||||
[Mac/Windows 無料ダウンロード](https://shandianshuo.cn)
|
||||
|
||||
**MiniMax** - MiniMax M2 CODING PLAN スポンサー
|
||||
[ブラックフライデーセール中、$2 から](https://platform.minimax.io/subscribe/coding-plan)
|
||||
|
||||
---
|
||||
|
||||
## フィードバック & サポート
|
||||
|
||||
- **Issue**: [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/farion1231/cc-switch/discussions)
|
||||
- **ドキュメント**: [README](../README.md)
|
||||
- **更新履歴**: [CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## 今後のロードマップ
|
||||
|
||||
**v3.9.0 予告（予定）**:
|
||||
|
||||
- ローカルプロキシ機能
|
||||
|
||||
続報にご期待ください！
|
||||
|
||||
---
|
||||
|
||||
**Happy Coding!**
|
||||
@@ -0,0 +1,369 @@
|
||||
# CC Switch v3.8.0
|
||||
|
||||
> 持久化架构升级，为云同步奠定基础
|
||||
|
||||
**[English Version →](v3.8.0-en.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.8.0 是一次重大的架构升级版本，重构了数据持久化层和用户界面，为未来的云同步和本地代理功能奠定基础。
|
||||
|
||||
**发布日期**：2025-11-28
|
||||
**提交数量**：从 v3.7.1 开始 51 个提交
|
||||
**代码变更**：207 个文件，+17,297 / -6,870 行
|
||||
|
||||
---
|
||||
|
||||
## 重大更新
|
||||
|
||||
### 持久化架构升级
|
||||
|
||||
从单一 JSON 文件存储迁移到 SQLite + JSON 双层架构，实现数据分层管理。
|
||||
|
||||
**架构变更**：
|
||||
|
||||
```
|
||||
v3.7.x (旧) v3.8.0 (新)
|
||||
┌─────────────────┐ ┌─────────────────────────────────┐
|
||||
│ config.json │ │ SQLite (可同步数据) │
|
||||
│ ┌───────────┐ │ │ ├─ providers 供应商配置 │
|
||||
│ │ providers │ │ │ ├─ mcp_servers MCP 服务器 │
|
||||
│ │ mcp │ │ ──> │ ├─ prompts 提示词 │
|
||||
│ │ prompts │ │ │ ├─ skills 技能 │
|
||||
│ │ settings │ │ │ └─ settings 通用设置 │
|
||||
│ └───────────┘ │ ├─────────────────────────────────┤
|
||||
└─────────────────┘ │ JSON (设备级数据) │
|
||||
│ └─ settings.json 本地设置 │
|
||||
│ ├─ 窗口位置 │
|
||||
│ ├─ 路径覆盖 │
|
||||
│ └─ 当前选中供应商 ID │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
**双层结构设计**：
|
||||
|
||||
| 层级 | 存储方式 | 数据类型 | 同步策略 |
|
||||
| -------- | -------- | ---------------------------- | ---------- |
|
||||
| 云同步层 | SQLite | 供应商、MCP、Prompts、Skills | 未来可同步 |
|
||||
| 设备层 | JSON | 窗口状态、本地路径、当前选择 | 保持本地 |
|
||||
|
||||
**技术实现**：
|
||||
|
||||
- **Schema 版本管理** - 支持数据库结构升级迁移
|
||||
- **SQL 导入导出** - `backup.rs` 支持 SQL dump，便于云端存储
|
||||
- **事务支持** - SQLite 原生事务保证数据一致性
|
||||
- **自动迁移** - 首次启动自动从 `config.json` 迁移数据
|
||||
|
||||
**模块化重构**：
|
||||
|
||||
```
|
||||
database/
|
||||
├── mod.rs 核心 Database 结构体和初始化
|
||||
├── schema.rs 表结构定义、Schema 版本迁移
|
||||
├── backup.rs SQL 导入导出、二进制快照备份
|
||||
├── migration.rs JSON → SQLite 数据迁移引擎
|
||||
└── dao/ 数据访问对象层
|
||||
├── providers.rs 供应商 CRUD
|
||||
├── mcp.rs MCP 服务器 CRUD
|
||||
├── prompts.rs 提示词 CRUD
|
||||
├── skills.rs Skills CRUD
|
||||
└── settings.rs 键值对设置存储
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 全新用户界面
|
||||
|
||||
完整重构的 UI 设计，提供更现代化的视觉体验。
|
||||
|
||||
**视觉改进**：
|
||||
|
||||
- 重新设计的界面布局
|
||||
- 统一的组件样式
|
||||
- 更流畅的过渡动画
|
||||
- 优化的视觉层次
|
||||
|
||||
**交互优化**：
|
||||
|
||||
- Header toolbar 重新设计
|
||||
- ConfirmDialog 样式统一
|
||||
- 禁用主视图 overscroll 弹跳效果
|
||||
- 改进的表单验证反馈
|
||||
|
||||
**兼容性调整**：
|
||||
|
||||
- Tailwind CSS 从 v4 降级到 v3.4，提升浏览器兼容性
|
||||
|
||||
---
|
||||
|
||||
### 日语支持
|
||||
|
||||
新增日语（日本語）界面支持，国际化语言扩展到三种。
|
||||
|
||||
**支持语言**：
|
||||
|
||||
- 简体中文
|
||||
- English
|
||||
- 日本語（新增）
|
||||
|
||||
---
|
||||
|
||||
## 新增功能
|
||||
|
||||
### Skills 递归扫描
|
||||
|
||||
Skills 管理系统支持递归扫描仓库目录，自动发现嵌套的技能文件。
|
||||
|
||||
**改进内容**：
|
||||
|
||||
- 支持多层目录结构
|
||||
- 自动发现所有 `SKILL.md` 文件
|
||||
- 允许不同仓库的同名技能（使用完整路径去重）
|
||||
|
||||
---
|
||||
|
||||
### 供应商图标配置
|
||||
|
||||
供应商预设支持自定义图标配置。
|
||||
|
||||
**功能特性**：
|
||||
|
||||
- 预设供应商包含默认图标
|
||||
- 复制供应商时保留图标设置
|
||||
- 图标颜色自定义
|
||||
|
||||
---
|
||||
|
||||
### 表单验证增强
|
||||
|
||||
供应商表单新增必填字段验证，提供更友好的错误提示。
|
||||
|
||||
**改进内容**：
|
||||
|
||||
- 必填字段实时校验
|
||||
- 统一使用 Toast 通知显示验证错误
|
||||
- 更清晰的错误信息
|
||||
|
||||
---
|
||||
|
||||
### 开机自启
|
||||
|
||||
新增开机自动启动功能，支持 Windows、macOS 和 Linux 三个平台。
|
||||
|
||||
**功能特性**：
|
||||
|
||||
- 在设置中一键开启/关闭
|
||||
- 使用平台原生 API 实现
|
||||
- Windows 使用注册表、macOS 使用 LaunchAgent、Linux 使用 XDG autostart
|
||||
|
||||
---
|
||||
|
||||
### 新增供应商预设
|
||||
|
||||
- **MiniMax** - 官方合作伙伴
|
||||
|
||||
---
|
||||
|
||||
## Bug 修复
|
||||
|
||||
### 关键修复
|
||||
|
||||
**自定义端点丢失问题**
|
||||
|
||||
修复更新供应商时自定义请求地址意外丢失的问题。
|
||||
|
||||
- 根因：`INSERT OR REPLACE` 在 SQLite 底层执行 `DELETE + INSERT`，触发外键级联删除
|
||||
- 修复：改用 `UPDATE` 语句更新已存在的供应商
|
||||
|
||||
**Gemini 配置问题**
|
||||
|
||||
- 修复自定义供应商环境变量未正确写入 `.env` 文件
|
||||
- 修复安全认证配置错误写入到其他配置文件
|
||||
|
||||
**供应商验证问题**
|
||||
|
||||
- 修复当前供应商 ID 不存在时的验证错误
|
||||
- 修复供应商复制时图标字段丢失
|
||||
|
||||
### 平台兼容性
|
||||
|
||||
**Linux**
|
||||
|
||||
- 解决 WebKitGTK DMA-BUF 渲染问题
|
||||
- 保留用户 `.desktop` 文件自定义
|
||||
|
||||
### 其他修复
|
||||
|
||||
- 修复切换应用时的冗余用量查询
|
||||
- 修复 DMXAPI 预设使用错误的认证令牌字段
|
||||
- 修复深链接组件缺少翻译键
|
||||
- 修复用量脚本模板初始化逻辑
|
||||
|
||||
---
|
||||
|
||||
## 技术改进
|
||||
|
||||
### 架构重构
|
||||
|
||||
**供应商服务模块化**：
|
||||
|
||||
```
|
||||
services/provider/
|
||||
├── mod.rs 核心服务 - add/update/delete/switch/validate
|
||||
├── live.rs Live 配置文件操作
|
||||
├── gemini_auth.rs Gemini 认证类型检测
|
||||
├── endpoints.rs 自定义端点管理
|
||||
└── usage.rs 用量脚本执行
|
||||
```
|
||||
|
||||
**深链接模块化**：
|
||||
|
||||
```
|
||||
deeplink/
|
||||
├── mod.rs 模块导出
|
||||
├── parser.rs URL 解析
|
||||
├── provider.rs 供应商导入逻辑
|
||||
├── mcp.rs MCP 导入逻辑
|
||||
├── prompt.rs 提示词导入
|
||||
├── skill.rs Skills 导入
|
||||
└── utils.rs 工具函数
|
||||
```
|
||||
|
||||
### 代码质量
|
||||
|
||||
**清理工作**：
|
||||
|
||||
- 移除 JSON 时代遗留的导入导出死代码
|
||||
- 移除未使用的 MCP 类型导出
|
||||
- 统一错误处理方式
|
||||
|
||||
**测试更新**：
|
||||
|
||||
- 迁移测试到 SQLite 数据库架构
|
||||
- 更新组件测试匹配当前实现
|
||||
- 修复 MSW handlers 适配新 API
|
||||
|
||||
---
|
||||
|
||||
## 技术统计
|
||||
|
||||
```
|
||||
总体变更：
|
||||
- 提交数：51
|
||||
- 文件数：207 个文件变更
|
||||
- 新增：+17,297 行
|
||||
- 删除：-6,870 行
|
||||
- 净增：+10,427 行
|
||||
|
||||
提交类型分布：
|
||||
- fix：25 个（Bug 修复）
|
||||
- refactor：11 个（代码重构）
|
||||
- feat：9 个（新功能）
|
||||
- test：1 个（测试）
|
||||
- 其他：5 个
|
||||
|
||||
改动区域分布：
|
||||
- 前端源码：112 个文件
|
||||
- Rust 后端：63 个文件
|
||||
- 测试文件：20 个文件
|
||||
- 国际化文件：3 个文件
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 迁移说明
|
||||
|
||||
### 从 v3.7.x 升级
|
||||
|
||||
**自动迁移** - 首次启动时自动执行：
|
||||
|
||||
1. 检测 `config.json` 是否存在
|
||||
2. 在事务中迁移所有数据到 SQLite
|
||||
3. 设备级设置迁移到 `settings.json`
|
||||
4. 显示迁移成功通知
|
||||
|
||||
**数据安全**：
|
||||
|
||||
- 原 `config.json` 文件保留不删除
|
||||
- 迁移失败时显示错误对话框，保留`config.json`
|
||||
- 支持 Dry-run 模式验证迁移逻辑
|
||||
|
||||
---
|
||||
|
||||
## 下载与安装
|
||||
|
||||
### 系统要求
|
||||
|
||||
- **Windows**：Windows 10+
|
||||
- **macOS**：macOS 10.15（Catalina）+
|
||||
- **Linux**：Ubuntu 22.04+ / Debian 11+ / Fedora 34+
|
||||
|
||||
### 下载链接
|
||||
|
||||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载：
|
||||
|
||||
- **Windows**：`CC-Switch-v3.8.0-Windows.msi` 或 `-Portable.zip`
|
||||
- **macOS**：`CC-Switch-v3.8.0-macOS.tar.gz` 或 `.zip`
|
||||
- **Linux**：`CC-Switch-v3.8.0-Linux.AppImage` 或 `.deb`
|
||||
|
||||
### Homebrew（macOS）
|
||||
|
||||
```bash
|
||||
brew tap farion1231/ccswitch
|
||||
brew install --cask cc-switch
|
||||
```
|
||||
|
||||
更新：
|
||||
|
||||
```bash
|
||||
brew upgrade --cask cc-switch
|
||||
```
|
||||
|
||||
## 致谢
|
||||
|
||||
### 贡献者
|
||||
|
||||
感谢所有让这个版本成为可能的贡献者：
|
||||
|
||||
- [@YoVinchen](https://github.com/YoVinchen) - UI 和数据库重构
|
||||
- [@farion1231](https://github.com/farion1231) - BUG 修复和功能增强
|
||||
- 社区成员的测试和反馈
|
||||
|
||||
### 赞助商
|
||||
|
||||
**智谱AI** - GLM CODING PLAN 赞助商
|
||||
[使用此链接购买可享九折优惠](https://www.bigmodel.cn/claude-code?ic=RRVJPB5SII)
|
||||
|
||||
**PackyCode** - API 中转服务合作伙伴
|
||||
[使用 "cc-switch" 优惠码注册享 9 折优惠](https://www.packyapi.com/register?aff=cc-switch)
|
||||
|
||||
**闪电说** - 本地优先的 AI 语音输入法
|
||||
[免费下载](https://shandianshuo.cn) Mac/Win 双平台
|
||||
|
||||
**MiniMax** - MiniMax M2 CODING PLAN 赞助商
|
||||
[黑五优惠进行中，套餐9.9元起](https://platform.minimaxi.com/subscribe/coding-plan)
|
||||
|
||||
---
|
||||
|
||||
## 反馈与支持
|
||||
|
||||
- **问题反馈**：[GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- **讨论**：[GitHub Discussions](https://github.com/farion1231/cc-switch/discussions)
|
||||
- **文档**：[README](../README_ZH.md)
|
||||
- **更新日志**：[CHANGELOG.md](../CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## 未来展望
|
||||
|
||||
**v3.9.0 预览**（暂定）：
|
||||
|
||||
- 本地代理功能
|
||||
|
||||
敬请期待更多更新！
|
||||
|
||||
---
|
||||
|
||||
**Happy Coding!**
|
||||
@@ -0,0 +1,188 @@
|
||||
# CC Switch v3.9.0
|
||||
|
||||
> Local API Proxy, Auto Failover, Universal Provider, and a more complete multi-app workflow
|
||||
|
||||
**[中文版 →](v3.9.0-zh.md) | [日本語版 →](v3.9.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CC Switch v3.9.0 is the stable release of the v3.9 beta series (`3.9.0-1`, `3.9.0-2`, `3.9.0-3`).
|
||||
It introduces a local API proxy with per-app takeover, automatic failover, universal providers, and many stability and UX improvements across Claude Code, Codex, and Gemini CLI.
|
||||
|
||||
**Release Date**: 2026-01-07
|
||||
|
||||
---
|
||||
|
||||
## Highlights
|
||||
|
||||
- Local API Proxy for Claude Code / Codex / Gemini CLI
|
||||
- Auto Failover with circuit breaker and per-app failover queues
|
||||
- Universal Provider: one shared config synced across apps (ideal for API gateways like NewAPI)
|
||||
- Skills improvements: multi-app support, unified management with SSOT + React Query
|
||||
- Common config snippets: extract reusable snippets from the editor or the current provider
|
||||
- MCP import: import MCP servers from installed apps
|
||||
- Usage improvements: auto-refresh, cache hit/creation metrics, and timezone fixes
|
||||
- Linux packaging: RPM and Flatpak artifacts
|
||||
|
||||
---
|
||||
|
||||
## Major Features
|
||||
|
||||
### Local API Proxy
|
||||
|
||||
- Runs a local high-performance HTTP proxy server (Axum-based)
|
||||
- Supports Claude Code, Codex, and Gemini CLI with a unified proxy
|
||||
- Per-app takeover: you can independently decide which app routes through the proxy
|
||||
- Live config takeover: backs up and redirects the CLI live config to the local proxy when takeover is enabled
|
||||
- Monitoring: request logging and usage statistics for easier debugging and cost tracking
|
||||
- Error request logging: keep detailed logs for failed proxy requests to simplify debugging (#401, thanks @yovinchen)
|
||||
|
||||
### Auto Failover (Circuit Breaker)
|
||||
|
||||
- Automatically detects provider failures and triggers protection (circuit breaker)
|
||||
- Automatically switches to a backup provider when the current one is unhealthy
|
||||
- Tracks provider health in real time, and keeps independent failover queues per app
|
||||
- When failover is disabled, timeout/retry related settings no longer affect normal request flow
|
||||
|
||||
### Skills Management
|
||||
|
||||
- Multi-app Skills support for Claude Code and Codex, with smoother migration from older skill layouts (#365, #378, thanks @yovinchen)
|
||||
- Unified Skills management architecture (SSOT + React Query) for more consistent state and refresh behavior
|
||||
- Better discovery UX and performance:
|
||||
- Skip hidden directories during discovery
|
||||
- Faster discovery with long-lived caching for discoverable skills
|
||||
- Clear loading indicators and more discoverable header actions (import/refresh)
|
||||
- Fix wrong skill repo branch (#505, thanks @kjasn)
|
||||
|
||||
### Universal Provider
|
||||
|
||||
- Add a shared provider configuration that can sync to Claude/Codex/Gemini (#348, thanks @Calcium-Ion)
|
||||
- Designed for API gateways that support multiple protocols (e.g., NewAPI)
|
||||
- Allows per-app default model mapping under a single provider
|
||||
|
||||
### Common Config Snippets (Claude/Codex/Gemini)
|
||||
|
||||
- Maintain a reusable "common config" snippet and merge/append it into providers that enable it
|
||||
- New extraction workflow:
|
||||
- Extract from the editor content (what you are currently editing)
|
||||
- Or extract from the current active provider when the editor content is not provided
|
||||
- Codex extraction is safer:
|
||||
- Removes provider-specific sections like `model_provider`, `model`, and the entire `model_providers` table
|
||||
- Preserves `base_url` under `[mcp_servers.*]` so MCP configs are not accidentally broken
|
||||
|
||||
### MCP Management
|
||||
|
||||
- Import MCP servers from installed apps
|
||||
- Improve robustness: skip sync when the target CLI app is not installed; handle invalid Codex `config.toml` gracefully (#461, thanks @majiayu000)
|
||||
- Windows compatibility: wrap npx/npm commands with `cmd /c` for MCP export
|
||||
|
||||
### Usage & Pricing
|
||||
|
||||
- Usage & pricing improvements: auto-refresh, cache hit/creation metrics, timezone handling fixes, and refreshed built-in pricing table (#508, thanks @yovinchen)
|
||||
- DeepLink support: import usage query configuration via deeplink (#400, thanks @qyinter)
|
||||
- Model extraction for usage statistics (#455, thanks @yovinchen)
|
||||
- Usage query credentials can fall back to provider config (#360, thanks @Sirhexs)
|
||||
|
||||
---
|
||||
|
||||
## UX Improvements
|
||||
|
||||
- Provider search filter: quickly find providers by name (#435, thanks @TinsFox)
|
||||
- Provider icon colors: customize provider icon colors for quicker visual identification (#385, thanks @yovinchen)
|
||||
- Keyboard shortcut: `Cmd/Ctrl + ,` opens Settings (#436, thanks @TinsFox)
|
||||
- Skip Claude Code first-run confirmation dialog (optional)
|
||||
- Closable toasts: close buttons for switch toast and all success toasts (#350, thanks @ForteScarlet)
|
||||
- Update badge navigation: clicking the update badge opens the About tab
|
||||
- Settings page tab style improvements (#342, thanks @wenyuanw)
|
||||
- Smoother transitions: fade transitions for app/view switching and exit animations for panels
|
||||
- Proxy takeover active theme: apply an emerald theme while takeover is active
|
||||
- Dark mode readability improvements for forms and labels
|
||||
- Better window dragging area for full-screen panels (#525, thanks @zerob13)
|
||||
|
||||
---
|
||||
|
||||
## Platform Notes
|
||||
|
||||
### Windows
|
||||
|
||||
- Prevent terminal windows from appearing during version checks
|
||||
- Improve window sizing defaults (minimum width/height)
|
||||
- Fix black screen on startup by using the system titlebar
|
||||
- Add a fallback for `crypto.randomUUID()` on older WebViews
|
||||
|
||||
### macOS
|
||||
|
||||
- Use `.app` bundle path for autostart to avoid terminal window popups (#462, thanks @majiayu000)
|
||||
- Improve tray/icon behavior and header alignment
|
||||
|
||||
---
|
||||
|
||||
## Packaging
|
||||
|
||||
- Linux: RPM and Flatpak packaging targets are now available for building release artifacts
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Security improvements for the JavaScript executor and usage script execution (#151, thanks @luojiyin1987).
|
||||
- SQL import is restricted to CC Switch exported backups to reduce the risk of importing unsafe or incompatible SQL dumps.
|
||||
- Proxy takeover modifies CLI live configs; CC Switch will back up the live config before redirecting it to the local proxy. If you want to revert, disable takeover/stop the proxy and restore from the backup when needed.
|
||||
|
||||
## Special Thanks
|
||||
|
||||
Special thanks to @xunyu @deijing @su-fen for their support and contributions. This release wouldn't be possible without you!
|
||||
|
||||
## 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.9.0-Windows.msi` | **Recommended** - MSI installer with auto-update support |
|
||||
| `CC-Switch-v3.9.0-Windows-Portable.zip` | Portable version, no installation required |
|
||||
|
||||
### macOS
|
||||
|
||||
| File | Description |
|
||||
| ------------------------------- | ----------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.9.0-macOS.zip` | **Recommended** - Extract and drag to Applications, Universal Binary |
|
||||
| `CC-Switch-v3.9.0-macOS.tar.gz` | For Homebrew installation and auto-update |
|
||||
|
||||
> **Note**: Since the author does not have an Apple Developer account, you may see an "unidentified developer" warning on first launch. Close the app, 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 |
|
||||
| --------------------------------------- | ------------------ | ---------------------------------------------------------------------- |
|
||||
| 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` | Make executable and run directly, or use AUR |
|
||||
| Other distros / Unsure | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |
|
||||
| Sandboxed installation | `.flatpak` | `flatpak install CC-Switch-*.flatpak` |
|
||||
@@ -0,0 +1,188 @@
|
||||
# CC Switch v3.9.0
|
||||
|
||||
> ローカル API プロキシ、自動フェイルオーバー、Universal Provider、多アプリ対応の強化
|
||||
|
||||
**[English →](v3.9.0-en.md) | [中文版 →](v3.9.0-zh.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概要
|
||||
|
||||
CC Switch v3.9.0 は v3.9 ベータ（`3.9.0-1`、`3.9.0-2`、`3.9.0-3`）の安定版です。
|
||||
ローカル API プロキシ（アプリ別テイクオーバー対応）、自動フェイルオーバー、Universal Provider を追加し、Claude Code / Codex / Gemini CLI の安定性と操作性を大きく改善しました。
|
||||
|
||||
**リリース日**：2026-01-07
|
||||
|
||||
---
|
||||
|
||||
## ハイライト
|
||||
|
||||
- ローカル API プロキシ：Claude Code / Codex / Gemini CLI を統一的にプロキシ
|
||||
- 自動フェイルオーバー：サーキットブレーカーとアプリ別のフェイルオーバーキュー
|
||||
- Universal Provider：1つの設定を複数アプリへ同期（NewAPI などのゲートウェイ向け）
|
||||
- Skills の改善：マルチアプリ対応、SSOT + React Query による管理の統一
|
||||
- 共通設定スニペット：エディタ内容または現在のプロバイダから抽出
|
||||
- MCP インポート：インストール済みアプリから MCP servers を取り込み
|
||||
- 使用量の改善：自動更新、キャッシュ指標、タイムゾーン修正
|
||||
- Linux パッケージ：RPM / Flatpak の成果物を追加
|
||||
|
||||
---
|
||||
|
||||
## 主要機能
|
||||
|
||||
### ローカル API プロキシ（Local API Proxy）
|
||||
|
||||
- ローカルで高性能な HTTP プロキシサーバーを起動（Axum ベース）
|
||||
- Claude Code / Codex / Gemini CLI の API リクエストを統一的に扱う
|
||||
- アプリ別テイクオーバー：アプリごとにプロキシ経由にするかを個別に切り替え可能
|
||||
- Live 設定テイクオーバー：有効化時に CLI の live 設定をバックアップし、ローカルプロキシへリダイレクト
|
||||
- 監視：リクエストログと使用量統計でデバッグとコスト把握を支援
|
||||
- エラーリクエストのログ：失敗したプロキシリクエストも詳細に記録してデバッグを容易に（#401、@yovinchen に感謝）
|
||||
|
||||
### 自動フェイルオーバー（Auto Failover / サーキットブレーカー）
|
||||
|
||||
- 障害を検知して保護（サーキットブレーカー）を自動で発動
|
||||
- 現在のプロバイダが不調な場合、バックアッププロバイダへ自動切り替え
|
||||
- アプリごとに独立したフェイルオーバーキューとヘルス状態を管理
|
||||
- フェイルオーバーを無効化している場合、タイムアウト/リトライ関連の設定は通常フローに影響しません
|
||||
|
||||
### Skills 管理
|
||||
|
||||
- Claude Code と Codex の Skills をマルチアプリで利用可能にし、旧レイアウトからの移行もよりスムーズに（#365、#378、@yovinchen に感謝）
|
||||
- SSOT + React Query による Skills 管理の統一で、状態の一貫性と更新挙動を改善
|
||||
- Discovery の体験と性能を改善：
|
||||
- スキャン時に隠しディレクトリをスキップ
|
||||
- Discoverable skills に長寿命キャッシュを適用して高速化
|
||||
- ローディング表示の改善と、インポート/更新などの操作導線を整理
|
||||
- Skills リポジトリのブランチ設定を修正（#505、@kjasn に感謝）
|
||||
|
||||
### Universal Provider
|
||||
|
||||
- 複数アプリで共有できるプロバイダ設定を追加（Claude/Codex/Gemini へ同期）（#348、@Calcium-Ion に感謝）
|
||||
- NewAPI のような複数プロトコル対応の API ゲートウェイを想定
|
||||
- 1つのプロバイダ内でアプリ別にデフォルトモデルを割り当て可能
|
||||
|
||||
### 共通設定スニペット（Claude/Codex/Gemini）
|
||||
|
||||
- 「共通設定スニペット」を保持し、有効化したプロバイダへマージ/追記
|
||||
- 新しい抽出フロー：
|
||||
- エディタの現在内容から抽出（編集している内容）
|
||||
- エディタ内容がない場合は、現在アクティブなプロバイダから抽出
|
||||
- Codex の抽出はより安全：
|
||||
- `model_provider`、`model`、および `model_providers` テーブル全体など、プロバイダ固有の設定を除去
|
||||
- `[mcp_servers.*]` 配下の `base_url` は保持し、MCP 設定を壊しにくくしています
|
||||
|
||||
### MCP 管理
|
||||
|
||||
- インストール済みアプリから MCP servers をインポート
|
||||
- 安定性向上：対象 CLI が未インストールなら同期をスキップし、無効な Codex `config.toml` も適切に扱います（#461、@majiayu000 に感謝）
|
||||
- Windows 互換性：MCP エクスポート時の npx/npm 呼び出しを `cmd /c` でラップ
|
||||
|
||||
### 使用量と価格データ
|
||||
|
||||
- 使用量/価格の改善：自動更新、キャッシュ指標、タイムゾーン修正、内蔵価格テーブル更新（#508、@yovinchen に感謝）
|
||||
- DeepLink 対応：deeplink から使用量クエリ設定をインポート（#400、@qyinter に感謝）
|
||||
- 使用量統計からモデル情報を抽出（#455、@yovinchen に感謝）
|
||||
- 使用量クエリ資格情報はプロバイダ設定へフォールバック可能（#360、@Sirhexs に感謝）
|
||||
|
||||
---
|
||||
|
||||
## 使い勝手の改善
|
||||
|
||||
- プロバイダ検索フィルター（名前で素早く検索）（#435、@TinsFox に感謝）
|
||||
- プロバイダのアイコン色：アイコンに任意の色を設定して見分けやすく（#385、@yovinchen に感謝）
|
||||
- ショートカット：`Cmd/Ctrl + ,` で設定を開く（#436、@TinsFox に感謝）
|
||||
- Claude Code の初回確認ダイアログをスキップ可能（任意）
|
||||
- トースト通知のクローズボタン：切り替え通知と成功通知を閉じられるように（#350、@ForteScarlet に感謝）
|
||||
- 更新バッジをクリックすると About タブへ移動
|
||||
- 設定ページのタブスタイル改善（#342、@wenyuanw に感謝）
|
||||
- アプリ/ビュー切り替えのフェードとパネル終了アニメーション
|
||||
- プロキシテイクオーバー中はエメラルド系テーマを適用して状態を分かりやすく
|
||||
- ダークモードの視認性改善
|
||||
- FullScreenPanel のウィンドウドラッグ領域を改善（#525、@zerob13 に感謝）
|
||||
|
||||
---
|
||||
|
||||
## プラットフォーム別メモ
|
||||
|
||||
### Windows
|
||||
|
||||
- バージョンチェック時にターミナルが表示されないよう改善
|
||||
- ウィンドウ最小サイズのデフォルトを調整
|
||||
- 起動時の黒画面を避けるため、システムタイトルバー方式を採用
|
||||
- 古い WebView 向けに `crypto.randomUUID()` のフォールバックを追加
|
||||
|
||||
### macOS
|
||||
|
||||
- 自動起動で `.app` バンドルパスを使用し、ターミナル表示を回避（#462、@majiayu000 に感謝）
|
||||
- トレイとヘッダー周りの体験を改善
|
||||
|
||||
---
|
||||
|
||||
## パッケージ
|
||||
|
||||
- Linux：RPM と Flatpak のパッケージングを追加し、リリース成果物の生成に対応
|
||||
|
||||
---
|
||||
|
||||
## 注意事項
|
||||
|
||||
- セキュリティ強化：JavaScript 実行器と使用量スクリプト実行に関するセキュリティ問題を修正（#151、@luojiyin1987 に感謝）。
|
||||
- SQL インポートは CC Switch がエクスポートしたバックアップのみに制限されます（安全性のため）。
|
||||
- プロキシのテイクオーバーは CLI の live 設定を変更します。CC Switch はリダイレクト前に live 設定をバックアップします。元に戻す場合はテイクオーバー無効化/プロキシ停止を行い、必要に応じてバックアップから復元してください。
|
||||
|
||||
## 特別な謝辞
|
||||
|
||||
@xunyu @deijing @su-fen の皆様のサポートと貢献に特別な感謝を申し上げます。皆様なしではこのリリースは実現しませんでした！
|
||||
|
||||
## ダウンロード & インストール
|
||||
|
||||
[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.9.0-Windows.msi` | **推奨** - MSI インストーラー、自動更新対応 |
|
||||
| `CC-Switch-v3.9.0-Windows-Portable.zip` | ポータブル版、インストール不要 |
|
||||
|
||||
### macOS
|
||||
|
||||
| ファイル | 説明 |
|
||||
| ------------------------------- | ----------------------------------------------------------------- |
|
||||
| `CC-Switch-v3.9.0-macOS.zip` | **推奨** - 解凍して Applications へドラッグ、Universal Binary |
|
||||
| `CC-Switch-v3.9.0-macOS.tar.gz` | Homebrew インストールおよび自動更新用 |
|
||||
|
||||
> **注意**: 作者が Apple Developer アカウントを持っていないため、初回起動時に「開発元が未確認」という警告が表示される場合があります。アプリを閉じてから、「システム設定」→「プライバシーとセキュリティ」→「このまま開く」をクリックすると、正常に開けるようになります。
|
||||
|
||||
### 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` |
|
||||
| サンドボックスで実行したい場合 | `.flatpak` | `flatpak install CC-Switch-*.flatpak` |
|
||||
@@ -0,0 +1,188 @@
|
||||
# CC Switch v3.9.0
|
||||
|
||||
> 本地 API 代理、自动故障切换、统一供应商与多应用工作流增强
|
||||
|
||||
**[English →](v3.9.0-en.md) | [日本語版 →](v3.9.0-ja.md)**
|
||||
|
||||
---
|
||||
|
||||
## 概览
|
||||
|
||||
CC Switch v3.9.0 是 v3.9 测试版序列（`3.9.0-1`、`3.9.0-2`、`3.9.0-3`）的稳定版。
|
||||
本次更新带来本地 API 代理（支持按应用接管）、自动故障切换、统一供应商（Universal Provider），并对 Claude Code / Codex / Gemini CLI 的稳定性与使用体验做了大量改进。
|
||||
|
||||
**发布日期**：2026-01-07
|
||||
|
||||
---
|
||||
|
||||
## 重点内容
|
||||
|
||||
- 本地 API 代理：Claude Code / Codex / Gemini CLI 统一接入
|
||||
- 自动故障切换：熔断保护 + 每个应用独立的 failover 队列
|
||||
- 统一供应商：一份配置可同步到多个应用（适合 NewAPI 等网关）
|
||||
- Skills 相关增强：支持多应用、管理架构统一（SSOT + React Query）
|
||||
- 通用配置片段：支持从编辑器内容或当前供应商提取可复用片段
|
||||
- MCP 导入：支持从已安装应用导入 MCP servers
|
||||
- 用量增强：自动刷新、缓存命中/创建指标、时区修复
|
||||
- Linux 打包：新增 RPM 与 Flatpak 制品
|
||||
|
||||
---
|
||||
|
||||
## 主要功能
|
||||
|
||||
### 本地 API 代理（Local API Proxy）
|
||||
|
||||
- 运行一个本地高性能 HTTP 代理服务（基于 Axum）
|
||||
- 统一代理 Claude Code、Codex、Gemini CLI 的 API 请求
|
||||
- 按应用接管：你可以分别控制每个应用是否走本地代理
|
||||
- Live 配置接管：启用接管时，会备份并重定向 CLI 的 live 配置到本地代理
|
||||
- 监控能力：记录请求日志与用量统计，便于排错与成本分析
|
||||
- 错误请求日志：代理会记录失败请求的详细信息，便于定位问题（#401，感谢 @yovinchen）
|
||||
|
||||
### 自动故障切换（Auto Failover / 熔断）
|
||||
|
||||
- 自动检测供应商异常并触发熔断保护
|
||||
- 当前供应商不可用时自动切换到备用供应商
|
||||
- 每个应用维护独立的 failover 队列，并实时追踪健康状态
|
||||
- 当关闭故障切换时，超时/重试相关配置不会影响正常请求流程
|
||||
|
||||
### Skills 管理
|
||||
|
||||
- Skills 支持 Claude Code 与 Codex 多应用使用，并提供旧结构到新结构的平滑迁移（#365、#378，感谢 @yovinchen）
|
||||
- Skills 管理架构统一（SSOT + React Query），状态刷新与数据一致性更稳定
|
||||
- 发现（Discovery）体验与性能改进：
|
||||
- 扫描时跳过隐藏目录
|
||||
- Discoverable skills 使用长生命周期缓存提升性能
|
||||
- 增加加载状态提示，导入/刷新等操作入口更显眼
|
||||
- 修复 Skills 仓库分支配置错误（#505，感谢 @kjasn）
|
||||
|
||||
### 统一供应商（Universal Provider）
|
||||
|
||||
- 新增“跨应用共享”的供应商配置，可同步到 Claude/Codex/Gemini（#348，感谢 @Calcium-Ion）
|
||||
- 适配支持多协议的 API 网关（例如 NewAPI）
|
||||
- 同一个供应商下可按应用分别设置默认模型映射
|
||||
|
||||
### 通用配置片段（Claude/Codex/Gemini）
|
||||
|
||||
- 维护一段“通用配置片段”，并将其合并/追加到启用该功能的供应商配置中
|
||||
- 新增“提取通用配置片段”工作流：
|
||||
- 优先从编辑器当前内容提取（你正在编辑的内容）
|
||||
- 若未提供编辑器内容，则从当前激活的供应商提取
|
||||
- Codex 场景提取更安全：
|
||||
- 自动移除 `model_provider`、`model` 以及整个 `model_providers` 表等供应商相关内容
|
||||
- 会保留 `[mcp_servers.*]` 下的 `base_url`，避免误伤 MCP 配置
|
||||
|
||||
### MCP 管理
|
||||
|
||||
- 支持从已安装应用导入 MCP servers
|
||||
- 同步更稳健：目标 CLI 未安装则跳过；无效的 Codex `config.toml` 可更优雅处理（#461，感谢 @majiayu000）
|
||||
- Windows 兼容性：MCP 导出相关的 npx/npm 调用使用 `cmd /c` 包裹
|
||||
|
||||
### 用量与计费数据
|
||||
|
||||
- 用量与计费增强：自动刷新、缓存命中/创建指标、时区修复，以及内置价格表更新（#508，感谢 @yovinchen）
|
||||
- 深链支持：可通过 deeplink 导入用量查询配置（#400，感谢 @qyinter）
|
||||
- 用量统计支持提取模型信息（#455，感谢 @yovinchen）
|
||||
- 用量查询凭证支持从供应商配置回退（#360，感谢 @Sirhexs）
|
||||
|
||||
---
|
||||
|
||||
## 体验优化
|
||||
|
||||
- 供应商搜索过滤：按名称快速查找（#435，感谢 @TinsFox）
|
||||
- 供应商图标颜色：支持为供应商图标设置自定义颜色，便于快速区分（#385，感谢 @yovinchen）
|
||||
- 快捷键：`Cmd/Ctrl + ,` 打开设置（#436，感谢 @TinsFox）
|
||||
- 可跳过 Claude Code 首次确认弹窗（可选）
|
||||
- Toast 通知可关闭：切换提示与成功提示都支持关闭按钮（#350，感谢 @ForteScarlet）
|
||||
- 点击更新徽章会自动跳转到 About 标签页
|
||||
- 设置页 Tab 样式改进（#342，感谢 @wenyuanw）
|
||||
- 更顺滑的切换动效：应用/视图淡入淡出与面板退出动画
|
||||
- 代理接管激活时应用翡翠绿主题，便于一眼识别当前状态
|
||||
- 深色模式可读性增强（表单与标签对比度等）
|
||||
- FullScreenPanel 的窗口拖拽区域优化（#525，感谢 @zerob13）
|
||||
|
||||
---
|
||||
|
||||
## 平台说明
|
||||
|
||||
### Windows
|
||||
|
||||
- 版本检查不再弹出终端窗口
|
||||
- 改进窗口尺寸默认值（最小宽高）
|
||||
- 修复部分设备启动黑屏问题（使用系统标题栏方案）
|
||||
- 兼容旧 WebView：为 `crypto.randomUUID()` 增加降级方案
|
||||
|
||||
### macOS
|
||||
|
||||
- 自启动使用 `.app bundle` 路径，避免弹出终端窗口（#462，感谢 @majiayu000）
|
||||
- 托盘与标题栏相关体验优化
|
||||
|
||||
---
|
||||
|
||||
## 打包
|
||||
|
||||
- Linux：新增 RPM 与 Flatpak 打包目标，用于生成发布制品
|
||||
|
||||
---
|
||||
|
||||
## 说明与注意事项
|
||||
|
||||
- 安全增强：修复 JavaScript 执行器与用量脚本相关的安全问题（#151，感谢 @luojiyin1987）。
|
||||
- 为降低导入风险，SQL 导入被限制为仅允许导入 CC Switch 自己导出的备份。
|
||||
- Proxy 接管会修改 CLI 的 live 配置；CC Switch 会在重定向前自动备份 live 配置。如需回退，可关闭接管/停止代理，并在必要时从备份恢复。
|
||||
|
||||
## 特别感谢
|
||||
|
||||
特别感谢 @xunyu @deijing @su-fen 做出的支持和贡献，没有你们就没有这个版本！
|
||||
|
||||
## 下载与安装
|
||||
|
||||
访问 [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.9.0-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||||
| `CC-Switch-v3.9.0-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||||
|
||||
### macOS
|
||||
|
||||
| 文件 | 说明 |
|
||||
| ------------------------------- | --------------------------------------------------------- |
|
||||
| `CC-Switch-v3.9.0-macOS.zip` | **推荐** - 解压后拖入 Applications 即可，Universal Binary |
|
||||
| `CC-Switch-v3.9.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` |
|
||||
| 沙箱隔离需求 | `.flatpak` | `flatpak install CC-Switch-*.flatpak` |
|
||||
@@ -0,0 +1,22 @@
|
||||
# CC Switch User Manual / 用户手册 / ユーザーマニュアル
|
||||
|
||||
> Claude Code / Claude Desktop / Codex / Gemini CLI / OpenCode / OpenClaw / Hermes
|
||||
|
||||
## Language / 语言 / 言語
|
||||
|
||||
| Language | Link |
|
||||
|----------|------|
|
||||
| [中文](./zh/README.md) | 简体中文用户手册 |
|
||||
| [English](./en/README.md) | English User Manual |
|
||||
| [日本語](./ja/README.md) | 日本語ユーザーマニュアル |
|
||||
|
||||
## Version / 版本 / バージョン
|
||||
|
||||
- Documentation version: v3.16.0
|
||||
- Last updated: 2026-05-29
|
||||
- Compatible with CC Switch v3.16.0+
|
||||
|
||||
## Links
|
||||
|
||||
- [GitHub Issues](https://github.com/farion1231/cc-switch/issues)
|
||||
- [GitHub Repository](https://github.com/farion1231/cc-switch)
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 85 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 69 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 63 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 29 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 63 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 82 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 68 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 69 KiB |
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user