docs(release): add v4.0.9 release notes

docs/release-notes/v4.0.9-en.md

@@ -0,0 +1,61 @@
+# CC Switch v4.0.9
+
+### The fifth fix release for 4.0 stable
+
+This release reworks the whole flow for adding a provider: the form follows the order you fill it in, with the model list right after the address and Key; clicking "Fetch Models" opens a dialog automatically, with each model's context window and support for reasoning and image input already looked up; check the models you want and click "Apply" to add them to the list together with their parameters, and uncheck them in the same dialog to remove them; field descriptions move into "?", and hints follow whether the app is currently in Direct, Routing or Aggregation mode. It also fixes Codex new threads and automations failing on some upstreams and leaving the whole thread unable to continue: DeepSeek, OpenCode Zen and others reached through Routing via the Chat protocol returned 400, and xAI native Responses returned 422. For Claude Desktop in WSL2 and other clients that cannot reach this machine's loopback, you can now enter a "Connection address" under "Settings → Local routing". For everything new in 4.0, see the [v4.0 release notes](https://github.com/farion1231/cc-switch/blob/main/docs/release-notes/v4.0.4-en.md).
+
+---
+
+## A reworked flow for adding providers
+
+This release goes through the forms for adding and editing providers from top to bottom, mainly the three layouts for Claude Code, Codex and Aggregation. The model list used to sit under the advanced options, after the default model it determines; fetched models could only be added one at a time below the list, and each parameter filled in automatically then had to be checked one by one; nearly every field had a paragraph of gray text below it, and some hints did not match the mode you were actually in. Here is the flow now, in the order you fill it in:
+
+**1. Address, Key and upstream format.** First pick a preset or enter the address and Key. When you choose an upstream format, the hint follows the app's current mode: when the app is in Direct mode and the chosen format needs conversion, a hint below the format says either that this card is in use in Direct mode and requests will fail once it is saved with this format, or that this format needs a switch to Routing or Aggregation first. When Claude Code's upstream format is OpenAI Chat or Responses, authentication fields that would not be used are no longer shown.
+
+**2. Model list: fetch, pick, fill in parameters automatically.** Codex's model list has moved out of the advanced options to right after the address and Key, and is named "Models", as in the Aggregation layout. For Claude Code Aggregation, Codex, OpenCode and MiniMax Code, models are now added to the model list like this:
+
+1. Click "Fetch Models" on the model list.
+2. Once fetching succeeds, the "Select models" dialog opens automatically. Each model already shows its context window and whether it supports reasoning and image input; the values come from a preset with the same address first, then from models.dev looked up by the provider's address, and then from the model vendor's own entry.
+3. Check the models you want and click "Apply". New models are appended to the end of the list with their parameters filled in from the values shown in the dialog, and the "Filled in context window and other parameters for … Please double-check." prompt no longer appears.
+
+The same dialog also handles removal: checked means "in the list", configured models are checked by default, and unchecking them and clicking "Apply" removes them from the list; clicking "Cancel" changes nothing. Models that stay keep their original order and settings. Configured models the provider did not return this time are listed separately in a "Not in the provider's list" group and can be cleaned up at the same time. The dialog supports search, select all / select none and showing only selected models, and shows how many are selected; after one fetch, the button becomes "Select models", and clicking it again does not fetch again; when needed, click "Fetch again" in the dialog.
+
+**3. Default model: the first row of the list.** When Codex has a model list, the first row is the default model, and there is no longer a separate default model input box; renaming or deleting the first row changes the default model accordingly. When the list was empty, adding a model automatically puts the current default model in the first row, so adding a list does not change the default model. Cards without a model list still keep the default model input box: these cards use Codex's built-in `/model` menu, and once a list is added the menu shows only the models in the list. The Aggregation model lists also drop the ★ and "Make default model" on each row, and the rule is likewise that the first row is the default.
+
+**4. Subagents (Codex, new).** The Codex form adds "Sub-agent Model" and "Sub-agent reasoning effort", which map to the `config.toml` keys under `[agents]`: `default_subagent_model` and `default_subagent_reasoning_effort`. Leaving one empty deletes the corresponding key, and subagents use the main agent's setting; when you switch providers these two follow, and other settings under `[agents]` are left alone. When the model entered is not in the model list, the form says so and can add it with one click: Codex cannot get the context window of a model that is not in the list, and when Routing converts requests to the Chat / Anthropic protocol, that model is also replaced with the default model. In Aggregation mode these two are not written and subagents follow the main model, so that after the main agent switches to another provider's model, subagents are not sent back to the default provider.
+
+**5. Advanced options.** The "Full URL" switch is only useful for gateways with non-standard endpoint paths and has moved into the advanced options; for cards that already have it on, the advanced options expand automatically when editing. User-Agent and request overrides are merged into one block, with a single note that they only take effect in Routing and Aggregation modes.
+
+**Throughout the form: descriptions move into "?".** What a field is and when to use it now sit in the "?" after the field name; the page keeps only the consequences you need to watch for, such as having to restart Codex after changing the model list, or a 400 error when the max output exceeds the actual limit. On managed-account cards (Codex sign-in, xAI sign-in and Copilot), fields the backend never reads are no longer shown; the notice about leftover fields from older versions is shortened to one sentence; the description of Claude Desktop's model modes is now one sentence: use Direct when the provider offers native Claude models, and Model Mapping for third-party models such as DeepSeek and Kimi.
+
+## New
+
+**"Settings → Local routing" adds "Connection address".** The proxy address CC Switch writes into client configs (including Claude Desktop's gateway address) used to always be derived from the listen address, and when listening on `0.0.0.0` it wrote `127.0.0.1`. Claude Desktop sessions in WSL2 (NAT mode) cannot reach Windows' loopback, so they could never connect, and changing the listen address to `0.0.0.0` did not help. Now set the listen address to `0.0.0.0` and enter a Windows address that WSL can reach in "Connection address", and the proxy address written to clients uses it instead. Saving rewrites the clients currently going through Routing right away, without restarting the routing service. This setting is stored only on this device and is not carried to other devices by cloud sync.
+
+**New presets:** SoruxGPT, IKunCode, RunToken, BotCF, YYLX, TokenFlux and OpenModel.
+
+## Fixes
+
+- **When Codex created a new thread or ran an automation, DeepSeek and other upstreams returned 400 and the whole thread became unusable.** When the Codex desktop app creates a new thread, it inserts into the history a tool result with no matching tool call (the create_thread receipt). When Routing converted Responses to the Chat protocol, such results used to be sent as `role=tool` messages, and strict Chat upstreams such as DeepSeek and OpenCode Zen rejected every request in that thread. Tool results with no matching call are now turned into a marked user message, and any images in them are still sent as images; tool results that have a matching call are handled exactly as before.
+- **When Codex used xAI native Responses, it got 422 and the thread could not recover.** The receipts the Codex desktop app inserts (new thread, automation update, heartbeat, cross-thread message) have no `call_id`, so xAI rejects the whole request with "missing `call_id`", and since the receipts stay in the history, nothing in that thread could be sent afterwards. Now, only for requests going to xAI, these receipts are rewritten into user messages with the same marker, keeping their text and images; entries with a `call_id` and other upstreams are not affected.
+- **When Claude Code's upstream format was OpenAI Chat or Responses, Routing sent `x-api-key`.** The request header used to depend only on the Key's variable name, so cards using `ANTHROPIC_API_KEY` sent `x-api-key`, which OpenAI-format upstreams do not accept. OpenAI formats now always use `Authorization: Bearer`, and for Anthropic format the header is still decided by the variable name.
+- **Claude Code Aggregation mode used only the default provider's compatibility switches.** When a model from another provider was picked, requests could use features that provider does not support and fail. All members' settings are now merged according to the nature of each switch: features such as experimental betas, Artifacts and the auto mode server are turned off as soon as any one member turns them off; tool search, always-on effort, fine-grained tool streaming and similar are on only when all members turn them on. Switches related to the extra request body, thinking and the context window still follow the default provider.
+- **The interface language was wrong at startup and only corrected itself after opening Settings.** The language on the first screen came from the browser cache, so when the cache was empty or stale (for example after clearing WebView data, or copying `~/.cc-switch` to a new computer), the system language was shown first. The saved language setting is now read and applied right at startup.
+- **On macOS, API addresses on the local network could not be reached.** CC Switch now asks macOS for "Local Network" permission. The first time it connects to a local network address, the system shows an authorization prompt, and that request may still fail; click "Allow" and try again. If you denied it before, turn on CC Switch under "System Settings → Privacy & Security → Local Network".
+- **The page flashed when opening the provider edit panel.** The edit panel used to open a loading page first and then switch to the content; it now opens once the content is ready, keeping the same fade-in as the add panel.
+
+**Other:** The Flatpak build docs fix how the `--bundles` argument is written, and explain how to skip the update bundles when you don't have a signing private key.
+
+## Upgrade Notes
+
+**The database schema is unchanged**, still at 20. The new presets only affect newly added providers.
+
+---
+
+## Thanks
+
+Thanks to [@NeeYoonc](https://github.com/NeeYoonc) (tool results in Codex threads with no matching call no longer causing 400 from Chat upstreams), [@allenxu09](https://github.com/allenxu09) ("Connection address" for local routing), [@chivopic](https://github.com/chivopic) (macOS Local Network permission), [@NestorRay](https://github.com/NestorRay) (the flash when opening the edit panel) and [@zydo](https://github.com/zydo) (Flatpak build docs) for their contributions.
+
+Thanks to [@loulanyue](https://github.com/loulanyue) for submitting a fix for the same issue earlier, and to [@OriyukiAkari](https://github.com/OriyukiAkari) for confirming through testing that xAI native Responses had this issue too. Thanks to [@Z-Eternal](https://github.com/Z-Eternal), [@xulimeng2022](https://github.com/xulimeng2022), [@flame916](https://github.com/flame916), [@hej56230-commits](https://github.com/hej56230-commits), [@Soliton1912](https://github.com/Soliton1912), [@gggjjto](https://github.com/gggjjto), [@KinJ](https://github.com/KinJ) and [@xue-ding-e](https://github.com/xue-ding-e) for reporting issues, providing reproduction details and helping verify fixes.
+
+For the full technical details, see the [CHANGELOG](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md).

docs/release-notes/v4.0.9-ja.md

@@ -0,0 +1,61 @@
+# CC Switch v4.0.9
+
+### 4.0 正式版の 5 回目の修正リリース
+
+プロバイダーを追加する流れ全体を見直しました。フォームは入力する順に並び、アドレスと Key のすぐ後にモデル一覧が来ます。「モデル一覧を取得」を押すとダイアログが自動で開き、各モデルのコンテキストウィンドウや、推論と画像入力に対応しているかどうかがすでに調べてあります。チェックを入れて「適用」を押すとパラメータごと一覧に追加され、同じダイアログでチェックを外せば削除できます。項目の説明は「?」にまとめ、案内はアプリが現在、直接接続・ルーティング・集約のどのモードかに合わせて表示されます。また、Codex の新しいスレッドや自動化が一部の上流でエラーになり、スレッド全体を続けられなくなっていた問題を修正しました。ルーティング経由で Chat プロトコルに変換される DeepSeek、OpenCode Zen などでは 400、xAI のネイティブ Responses では 422 になっていました。WSL2 内の Claude Desktop など、ホストのループバックに接続できないクライアントのために、「設定 → ローカルルーティング」で「接続先アドレス」を入力できるようになりました。4.0 の更新内容の全体は [v4.0 リリースノート](https://github.com/farion1231/cc-switch/blob/main/docs/release-notes/v4.0.4-ja.md) をご覧ください。
+
+---
+
+## 見直したプロバイダー追加の流れ
+
+今回は、プロバイダーを追加・編集するフォームを最初から最後まで整理し直しました。主に Claude Code、Codex、集約の 3 つのレイアウトです。これまではモデル一覧が詳細オプションの中にあり、その一覧で決まるデフォルトモデルより後ろに置かれていました。取得したモデルは一覧の下で 1 つずつ追加するしかなく、追加した後も自動入力されたパラメータを 1 つずつ確認する必要がありました。ほぼすべての項目の下に灰色の説明文があり、実際に使っているモードと合わない案内もありました。現在は入力する順に、次のように進みます。
+
+**1. アドレス、Key、上流フォーマット。** まずプリセットを選ぶか、アドレスと Key を入力します。上流フォーマットを選ぶときの案内は、アプリの現在のモードに合わせて表示されます。アプリが直接接続モードのときに変換が必要なフォーマットを選ぶと、フォーマットの下に、このカードは直接接続で使用中のためこのフォーマットで保存するとリクエストが失敗すること、またはこのフォーマットはルーティングか集約に切り替えてから使う必要があることが表示されます。Claude Code の上流フォーマットで OpenAI Chat または Responses を選んだときは、使われない認証の項目を表示しなくなりました。
+
+**2. モデル一覧：取得、選択、パラメータの自動入力。** Codex のモデル一覧を詳細オプションから出してアドレスと Key のすぐ後に置き、集約レイアウトと同じく「モデル一覧」という名前にしました。Claude Code の集約、Codex、OpenCode、MiniMax Code のモデル一覧では、次のようにモデルを追加します。
+
+1. モデル一覧の「モデル一覧を取得」を押します。
+2. 取得に成功すると「モデルを選択」ダイアログが自動で開きます。各モデルの横にはコンテキストウィンドウと、推論と画像入力に対応しているかどうかがすでに表示されています。値はまず同じアドレスのプリセットから取り、次にプロバイダーのアドレスで models.dev を調べ、それでもなければモデルのベンダー自身のエントリを調べます。
+3. 使いたいモデルにチェックを入れ、「適用」を押します。新しいモデルは一覧の末尾に追加され、パラメータはダイアログに表示された値でそのまま入力されます。「……のコンテキスト長などのパラメータを補完しました。内容をご確認ください」という通知は表示されなくなりました。
+
+同じダイアログで削除もできます。チェックは「一覧にある」ことを表し、設定済みのモデルは最初からチェックが入っています。チェックを外して「適用」を押すと一覧から削除され、「キャンセル」を押すと何も変わりません。残ったモデルは元の順序と設定を保ちます。設定済みなのに今回プロバイダーから返されなかったモデルは「プロバイダーの一覧にないモデル」グループに分けて表示され、まとめて整理できます。ダイアログでは検索、すべて選択 / すべて解除、選択済みのみの表示ができ、選択数も表示されます。一度取得するとボタンは「モデルを選択」に変わり、もう一度押しても再取得はしません。必要なときはダイアログで「再取得」を押します。
+
+**3. デフォルトモデル：一覧の 1 行目。** Codex にモデル一覧があるときは 1 行目がデフォルトモデルになり、デフォルトモデルの入力欄は別に設けなくなりました。1 行目の名前を変えたり削除したりすると、デフォルトモデルもそれに合わせて変わります。一覧が空のときにモデルを追加すると、現在のデフォルトモデルが自動で 1 行目に置かれるため、一覧を追加したことでデフォルトモデルが変わってしまうことはありません。モデル一覧を設定していないカードでは、デフォルトモデルの入力欄が引き続き残ります。こうしたカードは Codex 自身の `/model` メニューを使っており、一覧を追加するとメニューには一覧にあるモデルしか残らないためです。集約のモデル一覧でも各行の ★ と「デフォルトモデルにする」をなくし、同じく 1 行目がデフォルトというルールにしました。
+
+**4. サブエージェント（Codex、新機能）。** Codex のフォームに「サブエージェントモデル」と「サブエージェントの推論強度」を追加しました。`config.toml` の `[agents]` の下にある `default_subagent_model` と `default_subagent_reasoning_effort` に対応します。空欄にすると対応するキーを削除し、サブエージェントはメインエージェントの設定を引き継ぎます。プロバイダーを切り替えるとこの 2 項目も切り替わり、`[agents]` の下のほかの設定は変更しません。入力したモデルがモデル一覧にないときはフォームが案内を表示し、ワンクリックで一覧に追加できます。一覧にないモデルは Codex がコンテキストウィンドウを取得できず、ルーティング経由で Chat / Anthropic プロトコルに変換するときにはデフォルトモデルに置き換えられてしまうためです。集約モードではこの 2 項目を書き込まず、サブエージェントはメインのモデルに従います。メインエージェントが別のプロバイダーのモデルに切り替えた後に、サブエージェントがデフォルトのプロバイダーに戻されてしまうのを防ぐためです。
+
+**5. 詳細オプション。** 「フル URL」スイッチはエンドポイントのパスが標準的でないゲートウェイでしか役に立たないため、詳細オプションに移しました。すでにオンにしているカードでは、編集時に詳細オプションが自動で開きます。User-Agent とリクエスト上書きは 1 つのブロックにまとめ、ルーティングモードと集約モードでのみ有効になることを明記しました。
+
+**フォーム全体：説明は「?」の中に。** 項目が何か、いつ使うかは、項目名の後ろの「?」に入れました。画面には、モデル一覧を変更したら Codex の再起動が必要、最大出力が実際の上限を超えると 400 になる、といった注意が必要な結果だけを残しています。マネージドアカウントのカード（Codex、xAI ログイン、Copilot）では、バックエンドがもともと読まない項目を表示しなくなりました。旧バージョンから残っている項目についての案内は 1 文に短くしました。Claude Desktop のモデルモードの説明も 1 文にしました。プロバイダーがネイティブの Claude モデルを提供している場合は直接接続、DeepSeek、Kimi などのサードパーティのモデルにはモデルマッピングを使います。
+
+## 新機能
+
+**「設定 → ローカルルーティング」に「接続先アドレス」を追加しました。** CC Switch がクライアントの設定に書き込むプロキシアドレス（Claude Desktop のゲートウェイアドレスを含む）は、これまで常に待ち受けアドレスから決めており、`0.0.0.0` で待ち受けているときは `127.0.0.1` を書き込んでいました。WSL2（NAT モード）内の Claude Desktop のセッションは Windows のループバックにアクセスできないため、ずっと接続できず、待ち受けアドレスを `0.0.0.0` に変えても解決しませんでした。現在は待ち受けアドレスを `0.0.0.0` にしたうえで、「接続先アドレス」に WSL からアクセスできる Windows のアドレスを入力すると、クライアントに書き込むプロキシアドレスにそれが使われます。保存するとルーティング中のクライアントの設定をすぐに書き換え、ルーティングサービスを再起動する必要はありません。この設定はこのデバイスにだけ保存され、クラウド同期でほかのデバイスに持ち込まれることはありません。
+
+**新しいプリセット：** SoruxGPT、IKunCode、RunToken、BotCF、YYLX、TokenFlux、OpenModel。
+
+## 修正
+
+- **Codex で新しいスレッドを作成したり自動化を実行したりすると、DeepSeek などの上流が 400 を返し、スレッド全体が使えなくなっていた問題。** Codex のデスクトップ版は新しいスレッドを作成するとき、対応するツール呼び出しのないツール結果（create_thread の受領通知）を履歴に挿入します。ルーティング経由で Responses を Chat プロトコルに変換するとき、こうした結果はこれまで `role=tool` メッセージとして送られており、DeepSeek や OpenCode Zen のような厳格な Chat の上流は、このスレッドのすべてのリクエストを拒否していました。現在は、対応する呼び出しが見つからないツール結果を、印の付いたユーザーメッセージに変えて送ります。中の画像はこれまでどおり画像として送ります。対応する呼び出しがあるツール結果は以前とまったく同じです。
+- **Codex で xAI のネイティブ Responses を使うと 422 になり、スレッドを復旧できなかった問題。** Codex のデスクトップ版が挿入する受領通知（新しいスレッドの作成、自動化の更新、ハートビート、スレッド間のメッセージ）には `call_id` がなく、xAI は「`call_id` がない」としてリクエスト全体を拒否します。受領通知は履歴に残り続けるため、そのスレッドではその後何も送れなくなっていました。現在は xAI に送るときだけ、こうした受領通知を同じ印の付いたユーザーメッセージに書き換え、テキストと画像は残します。`call_id` のある項目やほかの上流には影響しません。
+- **Claude Code の上流フォーマットで OpenAI Chat または Responses を選ぶと、ルーティングが `x-api-key` を送っていた問題。** これまではリクエストヘッダーを Key の変数名だけで決めていたため、`ANTHROPIC_API_KEY` を使うカードは `x-api-key` を送り、OpenAI 形式の上流には認識されませんでした。現在は OpenAI 形式では常に `Authorization: Bearer` を使い、Anthropic 形式では引き続き変数名で決めます。
+- **Claude Code の集約モードで、デフォルトのプロバイダーの互換スイッチしか使われていなかった問題。** ほかのプロバイダーのモデルが選ばれたとき、そのプロバイダーが対応していない機能を送ってエラーになることがありました。現在はスイッチの性質に応じて全メンバーの設定をまとめます。実験的 beta、Artifact、自動モードサーバーのように機能をオフにするものは、1 つのメンバーでもオフにしていればオフになります。ツール検索、effort を常に有効化、細粒度のツールストリーミングのようなものは、すべてのメンバーがオンのときだけオンになります。追加のリクエストボディ、思考、ウィンドウ関連のスイッチは、引き続きデフォルトのプロバイダーに従います。
+- **起動時に画面の言語が正しくなく、設定ページを開いてから元に戻っていた問題。** 最初の画面の言語はブラウザーのキャッシュから読んでおり、キャッシュが空か古いとき（WebView のデータを消去した、`~/.cc-switch` を新しいパソコンにコピーした、など）は、まずシステムの言語で表示されていました。現在は起動時に保存済みの言語設定を読み込み、すぐに適用します。
+- **macOS で LAN 内の API アドレスに接続できなかった問題。** CC Switch は macOS に「ローカルネットワーク」の権限を求めるようになりました。初めて LAN 内のアドレスに接続するときにシステムが許可を求めるダイアログを表示します。このときのリクエストは失敗することがありますが、「許可」を押してからやり直せば接続できます。以前に拒否したことがある場合は、「システム設定 → プライバシーとセキュリティ → ローカルネットワーク」で CC Switch をオンにしてください。
+- **プロバイダーの編集パネルを開くと、画面が一瞬ちらついていた問題。** 編集パネルはこれまで読み込み中の画面を先に開いてから内容に切り替えていました。現在は内容の準備ができてから開き、追加パネルと同じフェードインの効果は残しています。
+
+**その他：** Flatpak のビルドドキュメントで `--bundles` 引数の書き方を修正し、署名用の秘密鍵がない場合に更新パッケージの作成を省く方法を説明しました。
+
+## アップグレードに関する注意
+
+**データベースの構造は変わっていません。** バージョンは 20 のままです。新しいプリセットは新しく追加するプロバイダーにだけ影響します。
+
+---
+
+## 謝辞
+
+[@NeeYoonc](https://github.com/NeeYoonc)（Codex のスレッドで対応する呼び出しが見つからないツール結果によって Chat の上流が 400 を返さないように）、[@allenxu09](https://github.com/allenxu09)（ローカルルーティングの「接続先アドレス」）、[@chivopic](https://github.com/chivopic)（macOS のローカルネットワーク権限）、[@NestorRay](https://github.com/NestorRay)（編集パネルを開くときのちらつき）、[@zydo](https://github.com/zydo)（Flatpak のビルドドキュメント）の貢献に感謝します。
+
+同じ問題の修正を先に提出してくださった [@loulanyue](https://github.com/loulanyue)、xAI のネイティブ Responses でも同じ問題が起きることを実際に確かめてくださった [@OriyukiAkari](https://github.com/OriyukiAkari) に感謝します。問題の報告、再現情報の提供、検証に協力してくださった [@Z-Eternal](https://github.com/Z-Eternal)、[@xulimeng2022](https://github.com/xulimeng2022)、[@flame916](https://github.com/flame916)、[@hej56230-commits](https://github.com/hej56230-commits)、[@Soliton1912](https://github.com/Soliton1912)、[@gggjjto](https://github.com/gggjjto)、[@KinJ](https://github.com/KinJ)、[@xue-ding-e](https://github.com/xue-ding-e) にも感謝します。
+
+技術的な詳細は [CHANGELOG](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md) をご覧ください。

docs/release-notes/v4.0.9-zh.md

@@ -0,0 +1,61 @@
+# CC Switch v4.0.9
+
+### 4.0 正式版的第五个修复版本
+
+重新梳理了添加供应商的整个流程：表单按填写顺序排列，地址和 Key 之后就是模型列表；点「获取模型列表」后弹窗自动打开，每个模型的上下文窗口、是否支持推理和图片输入都已经查好，勾选后点「应用」就连同参数一起加进列表，同一个弹窗里取消勾选就能移除；字段说明收进「?」，提示会按应用当前是直连、路由还是聚合来显示。另外修复了 Codex 新建线程和自动化在部分上游报错、整个线程无法继续的问题：经路由转成 Chat 协议的 DeepSeek、OpenCode Zen 等报 400，xAI 原生 Responses 报 422。WSL2 里的 Claude Desktop 等连不上本机回环的客户端，现在可以在「设置 → 本地路由」填一个「连接地址」。4.0 完整的更新内容请见 [v4.0 发布说明](https://github.com/farion1231/cc-switch/blob/main/docs/release-notes/v4.0.4-zh.md)。
+
+---
+
+## 重新梳理的供应商添加流程
+
+这一版把添加和编辑供应商的表单从头到尾理了一遍，主要是 Claude Code、Codex 和聚合三种布局。以前模型列表收在高级选项里，排在它所决定的默认模型后面；获取到的模型只能在列表下方逐个添加，加完还要逐个核对自动填好的参数；几乎每个字段下面都有一段灰字，有些提示和你实际所处的模式对不上。现在按填写顺序走一遍：
+
+**1. 地址、Key 和上游格式。** 先选预设或填地址和 Key。选上游格式时，提示按应用当前的模式显示：应用处在直连模式时，如果选的格式需要转换，格式下面会提示这张卡正在直连使用、改成这种格式保存后请求会失败，或者这种格式要先切到路由或聚合才能用。Claude Code 的上游格式选 OpenAI Chat 或 Responses 时，不再显示用不上的认证字段。
+
+**2. 模型列表：获取、挑选、自动填参数。** Codex 的模型列表从高级选项里挪了出来，紧跟在地址和 Key 后面，和聚合布局一样叫「模型列表」。Claude Code 聚合、Codex、OpenCode 和 MiniMax Code 的模型列表现在这样添加模型：
+
+1. 点模型列表上的「获取模型列表」。
+2. 获取成功后「选择模型」弹窗自动打开。每个模型旁边已经显示好上下文窗口，以及是否支持推理和图片输入，数值来自同地址的预设，其次按供应商地址查 models.dev，再其次查模型厂商自己的条目。
+3. 勾选想要的模型，点「应用」。新模型追加到列表末尾，参数按弹窗里显示的值直接填好，不再弹「已补全……的上下文等参数，请核对」的提示。
+
+同一个弹窗也负责删除：勾选表示「在列表里」，已配置的模型默认勾选，取消勾选后点「应用」就会从列表移除，点「取消」什么都不改。留下的模型保持原来的顺序和设置。已配置但供应商这次没返回的模型，单独列在「不在供应商列表中」一组，也能一并清理。弹窗支持搜索、全选 / 全不选、只看已选，并显示已选数量；获取过一次后按钮变成「选择模型」，再点不会重新获取，需要时在弹窗里点「重新获取」。
+
+**3. 默认模型：列表第一行。** Codex 有模型列表时，第一行就是默认模型，不再单独有一个默认模型输入框；改名或删掉第一行，默认模型跟着变。列表原本为空时，添加模型会自动把当前的默认模型放在第一行，默认模型不会因为加了列表而变掉。没有配置模型列表的卡仍然保留默认模型输入框：这类卡用的是 Codex 自带的 `/model` 菜单，加上列表后菜单里只会剩下列表里的模型。聚合模型列表也去掉了每行的 ★ 和「设为默认模型」，规则同样是第一行即默认。
+
+**4. 子代理（Codex，新增）。** Codex 表单新增「子代理模型」和「子代理推理强度」，对应 `config.toml` 里 `[agents]` 下的 `default_subagent_model` 和 `default_subagent_reasoning_effort`。留空就删掉对应的键，子代理沿用主代理的设置；切换供应商时这两项跟着换，`[agents]` 下的其他设置不动。填的模型不在模型列表里时，表单会提示并可以一键加入：不在列表里的模型，Codex 拿不到它的上下文窗口，经路由转成 Chat / Anthropic 协议时还会被换成默认模型。聚合模式下不写这两项，子代理跟随主模型，以免主代理换到另一家的模型后，子代理又被送回默认供应商。
+
+**5. 高级选项。** 「完整 URL」开关只对端点路径不标准的网关有用，挪进了高级选项；已经打开它的卡，编辑时高级选项会自动展开。User-Agent 和请求覆盖合成一块，统一注明只在路由和聚合模式下生效。
+
+**贯穿整个表单：说明收进「?」。** 字段是什么、什么时候用，放在字段名后面的「?」里；页面上只留需要你注意的后果，比如改了模型列表要重启 Codex、最大输出超过实际上限会报 400。托管账号的卡（Codex、xAI 登录和 Copilot）上，后端本来就不读的字段不再显示；旧版残留字段的提示缩成一句话；Claude Desktop 的模型模式说明改成一句话：供应商提供原生 Claude 模型时用直连，DeepSeek、Kimi 等第三方模型用模型映射。
+
+## 新增
+
+**「设置 → 本地路由」新增「连接地址」。** CC Switch 写进客户端配置的代理地址（包括 Claude Desktop 的网关地址）以前总是按监听地址推导，监听 `0.0.0.0` 时写的是 `127.0.0.1`。WSL2（NAT 模式）里的 Claude Desktop 会话访问不到 Windows 的本机回环，所以一直连不上，把监听地址改成 `0.0.0.0` 也没用。现在把监听地址设为 `0.0.0.0`，再在「连接地址」里填 WSL 能访问到的 Windows 地址，写给客户端的代理地址就会改用它。保存后会直接改写正在走路由的客户端，不用重启路由服务。这个设置只保存在本机，不会随云同步带到其他设备。
+
+**新增预设：** SoruxGPT、IKunCode、RunToken、BotCF、YYLX、TokenFlux、OpenModel。
+
+## 修复
+
+- **Codex 新建线程或跑自动化时，DeepSeek 等上游报 400，整个线程用不了。** Codex 桌面版新建线程时会往历史里插入一条没有对应工具调用的工具结果（create_thread 回执）。经路由把 Responses 转成 Chat 协议时，这类结果以前被当成 `role=tool` 消息发出去，DeepSeek、OpenCode Zen 这类严格的 Chat 上游会拒绝这个线程里的每一次请求。现在这类找不到对应调用的工具结果会改成一条带标记的用户消息，里面的图片照常作为图片发送；有对应调用的工具结果和以前完全一样。
+- **Codex 用 xAI 原生 Responses 时报 422，线程无法恢复。** Codex 桌面版插入的回执（新建线程、自动化更新、心跳、跨线程消息）没有 `call_id`，xAI 会以「缺少 `call_id`」拒绝整个请求，而回执一直留在历史里，所以这个线程之后都发不出去。现在只在发往 xAI 时，把这类回执改写成带同样标记的用户消息，保留文字和图片；有 `call_id` 的条目和其他上游都不受影响。
+- **Claude Code 的上游格式选 OpenAI Chat 或 Responses 时，路由发出的是 `x-api-key`。** 以前请求头只看 Key 的变量名，用 `ANTHROPIC_API_KEY` 的卡会发 `x-api-key`，OpenAI 格式的上游不认。现在 OpenAI 格式一律用 `Authorization: Bearer`，Anthropic 格式仍按变量名决定。
+- **Claude Code 聚合模式只用默认供应商的兼容开关。** 选到其他供应商的模型时，可能发出那家不支持的功能而报错。现在按开关的性质合并所有成员的设置：关闭实验性 beta、Artifact、自动模式服务器这类，只要有一家关就关；工具搜索、始终启用 effort、细粒度工具流式这类，所有成员都开才开。额外请求体、思考和窗口相关的开关仍然跟随默认供应商。
+- **启动时界面语言不对，打开设置页后才变回来。** 首屏语言读的是浏览器缓存，缓存为空或过期时（比如清过 WebView 数据、把 `~/.cc-switch` 复制到新电脑）会先显示系统语言。现在启动时会读取保存的语言设置并立即应用。
+- **macOS 上连不上局域网里的 API 地址。** CC Switch 现在会向 macOS 申请「本地网络」权限。第一次连接局域网地址时系统会弹出授权，这次请求可能仍然失败，点「允许」后重试即可。如果以前点过拒绝，需要到「系统设置 → 隐私与安全性 → 本地网络」里打开 CC Switch。
+- **打开供应商编辑面板时页面闪一下。** 编辑面板以前先打开一个加载页再换成内容；现在等内容准备好再打开，保留和新增面板一样的淡入效果。
+
+**其他：** Flatpak 构建文档修正了 `--bundles` 参数的写法，并说明没有签名私钥时怎么跳过更新包。
+
+## 升级说明
+
+**数据库结构没有变化**，仍然是 20。新增预设只影响新添加的供应商。
+
+---
+
+## 致谢
+
+感谢 [@NeeYoonc](https://github.com/NeeYoonc)（Codex 线程里找不到对应调用的工具结果不再导致 Chat 上游报 400）、[@allenxu09](https://github.com/allenxu09)（本地路由的「连接地址」）、[@chivopic](https://github.com/chivopic)（macOS 本地网络权限）、[@NestorRay](https://github.com/NestorRay)（打开编辑面板时的闪烁）、[@zydo](https://github.com/zydo)（Flatpak 构建文档）的贡献。
+
+感谢 [@loulanyue](https://github.com/loulanyue) 更早提交了同一问题的修复，感谢 [@OriyukiAkari](https://github.com/OriyukiAkari) 实测确认 xAI 原生 Responses 也有这个问题。感谢 [@Z-Eternal](https://github.com/Z-Eternal)、[@xulimeng2022](https://github.com/xulimeng2022)、[@flame916](https://github.com/flame916)、[@hej56230-commits](https://github.com/hej56230-commits)、[@Soliton1912](https://github.com/Soliton1912)、[@gggjjto](https://github.com/gggjjto)、[@KinJ](https://github.com/KinJ)、[@xue-ding-e](https://github.com/xue-ding-e) 报告问题、提供复现信息和帮忙验证。
+
+完整的技术细节请见 [CHANGELOG](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md)。