docs(release): add v3.20.1 release notes

2026-09-03 06:52:23 +08:00 · 2026-08-28 08:19:45 +08:00
parent 9485cf2f3d
commit 3217f72596
3 changed files with 843 additions and 0 deletions
--- a/docs/release-notes/v3.20.1-en.md
+++ b/docs/release-notes/v3.20.1-en.md
@@ -0,0 +1,281 @@
+# CC Switch v3.20.1
+
+> This release settles two hard debts on the Codex side: **compatibility with Codex CLI 0.149** — the definitive fix for third-party switches failing with 401 "Missing API key": switching is now config-only, the key travels in the provider's own table and never enters `auth.json`, and a family of legacy config shapes that made 0.149 refuse to start is repaired automatically on every switch; and **ChatGPT accounts in the same Team workspace no longer overwrite each other** — existing managed accounts need one re-login each (see Upgrade Notes). Three data-reliability fixes land alongside: provider edits always reach the live config, the Codex edit dialog no longer shows another card's key, and restores no longer wipe hand-written prompt files. On the usage side there is a new "Auto-Scan Session Logs" switch, and scanning large session files drops from seconds to milliseconds. This release **includes a database migration (v17 → v18)** — a backup is created automatically before migrating, and downgrading requires restoring it.
+
+**[中文版 →](v3.20.1-zh.md) | [日本語版 →](v3.20.1-ja.md)**
+
+---
+
+## Highlights: What You Can Do Now
+
+- **Switch third-party providers normally on Codex CLI ≥ 0.149** ([#6744](https://github.com/farion1231/cc-switch/issues/6744)): since 0.149, custom providers no longer inherit ambient credentials from `auth.json`, so third-party switches made the old default way (key written only to `auth.json`) all failed with 401. Switching is now config-only across the board — the key goes into the provider's own `[model_providers.*]` table (`experimental_bearer_token`, honored since Codex 0.48), and `auth.json` returns to being purely the official ChatGPT login file.
+- **Let multiple ChatGPT accounts from one Team workspace coexist safely** ([#6780](https://github.com/farion1231/cc-switch/pull/6780), fixes [#2245](https://github.com/farion1231/cc-switch/issues/2245)): accounts used to be keyed by the workspace ID, so two members of one Team collapsed onto a single record, with the later login silently overwriting the earlier one's tokens. Same-workspace logins now coexist as separate account rows, and requests routed through takeover are validated against the bound account — a bill can never land on another member.
+- **Trust "saved successfully"** ([#6779](https://github.com/farion1231/cc-switch/pull/6779)): a takeover backup row left behind by a crash could make edits of the active provider update only the database while the real config file stayed untouched. Ownership is now decided by a rebuilt predicate; edits always reach the live config.
+- **See the card's own key in the edit dialog** ([#6534](https://github.com/farion1231/cc-switch/pull/6534), fixes [#6414](https://github.com/farion1231/cc-switch/issues/6414)): the shared `auth.json` has no provider identity, so editing the active Codex provider could display — and on save persist — a key left behind by a different card, making keys converge across cards sharing a base URL ("model not found"). The form now rebuilds the key from the card's own bearer token in `config.toml`.
+- **Restore backups with confidence** ([#6810](https://github.com/farion1231/cc-switch/pull/6810), fixes [#6778](https://github.com/farion1231/cc-switch/issues/6778)): when a cloud snapshot has no enabled prompt for an app, a WebDAV/S3 download or backup import no longer truncates your hand-written `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `SOUL.md` to empty.
+- **Turn off background session scanning**: the usage page gains an "Auto-Scan Session Logs" switch; off means manual mode — local session logs are scanned only when you click "Sync Now". Proxy-takeover request accounting records in real time, never reads session files, and keeps working either way.
+- **See your OpenCode Go subscription quota**: the usage-script Token Plan query now recognizes OpenCode Go, with 5-hour / weekly / monthly usage percentages and reset times in the usage card and tray.
+- **Set Otty as your terminal on macOS** ([#6620](https://github.com/farion1231/cc-switch/pull/6620)): available for session resume, provider terminals and tool commands.
+- **Scan large session files in milliseconds instead of seconds**: Claude session logs move to incremental byte-cursor scanning — a 12 MB active session file drops from a 6.04 s full parse to a 9.3 ms incremental read.
+
+---
+
+## Usage Guides
+
+- **[Adding Providers](../user-manual/en/2-providers/2.1-add.md)**: provider management after the Codex config-only switch.
+- **[Usage Statistics](../user-manual/en/4-proxy/4.4-usage.md)**: how the session-scan switch and the Token Plan quota query 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
+
+This release's main line runs through Codex, starting from an upstream compatibility break: Codex CLI 0.149 tightened credential inheritance — custom providers no longer read ambient credentials from `auth.json`, so every third-party switch written the old default way failed with 401. CC Switch's answer is not a patch but a redesign: third-party switching is now config-only — the key travels in the provider's own config table, and `auth.json` returns to being purely the official ChatGPT login file. Alongside it, a family of legacy config shapes 0.149 refuses to load (stale tables squatting on reserved ids, tables missing `name`, legacy top-level `openai_base_url` reroutes) is repaired automatically on every switch and takeover projection, and a new preflight refuses combinations 0.149 cannot load by name — instead of reporting a "successful" switch Codex cannot start from.
+
+The second line is account and data safety: members of one ChatGPT Team workspace no longer overwrite each other in the Auth Center (existing managed accounts need one re-login); provider edits are guaranteed to reach the live config; the Codex edit dialog no longer bleeds another card's key; restores no longer wipe hand-written prompt files. On the usage side, session scanning gains an auto/manual switch and an incremental byte-cursor scanner (6.04 s → 9.3 ms), with three Claude session-accounting correctness fixes along the way — the origin of this release's only database migration (v17 → v18).
+
+**Release date**: 2026-08-28
+
+**Change size**: 26 commits | 66 files changed | +7,474 / -1,000 lines
+
+---
+
+## Added
+
+### Session-Log Scanning: Auto/Manual Mode
+
+The usage page gains an "Auto-Scan Session Logs" card with a switch (on by default, so behavior is unchanged after upgrading). Turning it off stops all background session scanning — including the startup pass — and a "Sync Now" button appears as the manual entry point, reporting imported entries, files scanned and an error count when done. Proxy-takeover request accounting records in real time and never reads session files, so it keeps recording regardless of the switch; the startup cost backfill (which only patches existing database rows) still runs in manual mode.
+
+### OpenCode Go Subscription Usage
+
+The usage-script Token Plan query now recognizes OpenCode Go, showing 5-hour / weekly / monthly usage percentages with reset times in the usage card and tray, reusing the existing quota-tier display. The endpoint is Bearer-auth only (the exact opposite of the inference side, which only accepts `x-api-key`); a valid key without a Go subscription reports a distinct message (HTTP 403) instead of a generic auth failure, a zero-usage window drops the upstream's placeholder reset time, and an unrecognized response shape reports an error instead of an empty card. Newly added OpenCode Go providers in Claude Code, Claude Desktop, Codex, OpenCode and Pi enable the query automatically; OpenCode Zen pay-as-you-go is deliberately not covered — that plan has no usage API upstream.
+
+### Otty Terminal Support (macOS)
+
+"Otty" joins the macOS terminal picker, covering session resume, provider terminals and tool commands. Launching first attempts a new tab in the existing Otty window via the Otty CLI, then a new Otty window; provider terminals and tool commands additionally fall back to Terminal.app on failure, while a failed session resume reports the error — with an explicit install hint when the Otty CLI is missing — and copies the command to the clipboard. CLI discovery probes the app bundle (system and per-user), Homebrew paths and PATH. The user manual's macOS terminal tables were corrected along the way — Kaku and Warp were already supported but missing from the lists. ([#6620](https://github.com/farion1231/cc-switch/pull/6620))
+
+---
+
+## Changed
+
+### Codex Third-Party Switching Is Config-Only
+
+Switching to a third-party Codex provider now writes the API key into the provider's own `[model_providers.*]` table (the `experimental_bearer_token` field, honored since Codex 0.48) and **never writes it into `auth.json`** — which returns to being purely the official ChatGPT login file. The background: Codex 0.149 stopped letting custom providers inherit ambient credentials from `auth.json`, so third-party switches made the old default way (key written only to `auth.json`) started failing with 401.
+
+The "Keep official login for direct switches" toggle now has exactly one meaning: ON leaves the official ChatGPT login completely untouched across third-party switches; OFF **deletes** `auth.json` instead of overwriting it with the API key (a failed deletion surfaces a warning that the official login is still on disk in the Codex config directory). Two safety gates now run on **every third-party switch**, not just in preservation mode: a key with no provider table to hold it, and a keyless config that would fall back to the official login (`requires_openai_auth = true` without its own credentials, or a bare top-level `openai_base_url` reroute), are both refused by name — including third-party cards with an empty config, which previously rode silently in `auth.json`. `requires_openai_auth` on the active keyed third-party table is re-stamped on each direct switch to match the preservation toggle, so Codex's login screen agrees with what is actually on disk. ([#6744](https://github.com/farion1231/cc-switch/issues/6744), [#6746](https://github.com/farion1231/cc-switch/pull/6746))
+
+### TeamoRouter Presets Move to teamorouter.cn
+
+All eight app presets now point at `api.teamorouter.cn`, with the old `.com` endpoint registered as a selectable, speed-testable fallback candidate for Claude Code, Claude Desktop, Codex and Grok Build. Existing saved TeamoRouter providers keep whatever base URL they were saved with.
+
+---
+
+## Fixed
+
+### Same-Workspace ChatGPT Accounts No Longer Merge in the Auth Center
+
+Managed Codex OAuth accounts were keyed by `chatgpt_account_id` — which identifies a ChatGPT workspace, not a person: two members of one Team workspace collapsed onto a single record, the later login silently overwrote the earlier one's tokens, and provider bindings followed whoever logged in last. Accounts are now keyed locally, with the OIDC subject kept as proof of user identity, so same-workspace logins coexist as separate rows. Requests routed through takeover are additionally validated against the bound account's live token: a Codex session still holding another member's login gets an explicit "restart Codex" error instead of being forwarded under the wrong identity, and the outgoing workspace header always comes from the account binding rather than the client's own claim. Adopting a CLI-rotated refresh token, and deleting `auth.json` on account removal, both require provable ownership now — CC Switch can no longer adopt or delete another workspace member's login. Every account row offers in-place "Re-login" (bindings preserved); cancelling or superseding a device login drops the pending flow inside CC Switch — an abandoned browser authorization can no longer be committed minutes later to silently overwrite an account. An id_token that is not a well-formed JWT yields no identity at all — a malformed or truncated token can never stand in for a user. ([#6780](https://github.com/farion1231/cc-switch/pull/6780), [#6831](https://github.com/farion1231/cc-switch/pull/6831), fixes [#2245](https://github.com/farion1231/cc-switch/issues/2245))
+
+### Codex 0.149 Compatibility Repairs: Existing Configs No Longer Keep Codex From Starting
+
+A family of config shapes that made Codex 0.149 refuse to load — seen by users as "CC Switch says switched, Codex won't start" — is now repaired automatically on every provider switch and takeover projection. Specifically: leftover `[model_providers.openai]` / `.ollama` / `.lmstudio` tables (written by older takeover projections; overriding a reserved id fails validation) are renamed losslessly to a CC-Switch-owned id and normalized into a loadable shape; provider tables missing `name` are backfilled (0.149 rejects the whole config over any nameless table — Bedrock tables are deliberately left nameless, since naming them breaks their built-in merge); legacy top-level `openai_base_url` reroutes carrying a usable key are migrated into a proper custom provider table (a keyless reroute is refused by the switch-time safety gate instead); and a new preflight rejects field combinations 0.149 cannot load, naming the offending table, instead of writing them out as a "successful" switch. Takeover of a card routed at the built-in `openai` provider now uses the officially supported top-level knob instead of creating a reserved table, and takeover of `ollama`/`lmstudio`-routed cards fails with an explicit error. The reserved-id list now matches upstream exactly (case-sensitive; `amazon-bedrock-runtime` added, legacy `oss`/`ollama-chat` treated as ordinary custom providers — their keys finally reach their own tables), and inline `model_providers` tables receive the injected token instead of being left with a dead top-level field.
+
+### A Refused Switch No Longer Corrupts the Refused Card
+
+Live-write validation now runs as a preflight, before the current-provider pointer moves. Previously a write-layer refusal landed after `current` had already been committed — the next switch would backfill the old live config into the refused provider's saved settings.
+
+### Provider Edits Always Reach the Live Config File
+
+A takeover backup row left behind by a crash or failed restore made saves of the active provider (Claude Desktop excepted) take the takeover path — updating only the database and the backup row while the real config file silently kept the old endpoint and key, indefinitely. Ownership is now decided by a single predicate requiring actual evidence of takeover (a placeholder in the live file, or the proxy enabled and running with a backup row, or an in-flight switch holding the per-app lock alongside a backup row); stale backup rows are refreshed to match the edited provider instead of hijacking the write. Universal provider saves now also re-project each generated child into the live config of any app where it is the active provider, and report per-app failures by name instead of claiming success. ([#6779](https://github.com/farion1231/cc-switch/pull/6779))
+
+### Codex Edit Dialog No Longer Shows Another Provider's Key
+
+With official-login preservation enabled, `auth.json` is a shared slot with no provider identity, and the edit dialog used to prefer it when seeding the form — so editing the active Codex provider could display, and on save persist, a key left behind by a different card, making keys converge across cards sharing a base URL ("model not found" errors). The dialog now rebuilds the key from the provider's own bearer token in `config.toml`; official-category and OAuth-only providers are untouched, and a card whose `config.toml` carries no bearer token of its own — an older or hand-maintained shape, now that every third-party switch writes one — keeps the previous behavior of reading the live `auth.json`, manual edits included. ([#6534](https://github.com/farion1231/cc-switch/pull/6534), fixes [#6414](https://github.com/farion1231/cc-switch/issues/6414))
+
+### Restores No Longer Wipe Unmanaged Prompt Files
+
+A WebDAV/S3 download or backup import whose snapshot had no enabled prompt for an app truncated that app's live prompt file (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `SOUL.md`) to empty — destroying hand-written local content that was never part of the sync payload. Such a restore now leaves the file entirely untouched; disabling the last prompt from the Prompts panel still clears it as before. ([#6810](https://github.com/farion1231/cc-switch/pull/6810), fixes [#6778](https://github.com/farion1231/cc-switch/issues/6778))
+
+### Recovery-Screen Exit Buttons Actually Quit the App
+
+The `process:allow-exit` capability was missing, so on v3.20.0 the Quit button on the "database version too new" recovery screen, and the exit call after a config-load failure, were both silently rejected by the IPC layer: the Quit button did nothing (closing the window still quit the app), and after a config-load failure the app carried on into the normal UI instead of exiting as intended. This was independently discovered and fixed first by @SaladDay in [#6567](https://github.com/farion1231/cc-switch/pull/6567).
+
+### Three Claude Session-Accounting Correctness Fixes
+
+Three data-accuracy fixes land with the incremental scanner, all on the Claude session-log path. A log line caught mid-write used to be permanently skipped by the old line-number cursor (the unfinished tail advanced the cursor, so the completed message was never imported) — the byte cursor only commits past complete lines, so the message is picked up next round. An externally truncated or rewritten session file is **never replayed**: re-importing entries whose detail rows the 30-day rollup has already pruned would permanently inflate totals, so the cursor is pinned at the new end of file and the skipped range is reported in the sync result's error list instead of silently dropped (truncation is caught by the cursor overrunning the file; same-size rewrites by a fingerprint of the bytes before the cursor). Mid-file read errors now keep committed progress, resume from the same spot next round and are reported, instead of returning a clean success; a failed cursor prefetch aborts the round instead of behaving like a first-ever scan and double-importing history.
+
+---
+
+## Performance
+
+### Claude Session Logs: Incremental Byte-Cursor Scanning
+
+Each scan round now seeks straight to the last committed byte offset and reads only what was appended, instead of re-reading a changed file end to end — per the change's own benchmark, a 12 MB active session file drops from a 6.04 s full parse to a 9.3 ms incremental read. Per-file cursors for Claude, Gemini, OpenCode, Grok Build and Pi are prefetched with one table read per importer per round instead of one lookup per file; on the Claude path, each file's imports and its cursor advance commit in a single transaction. A frozen-snapshot replay over 1,017 session files (409 MB) produced aggregates identical to the old scanner. Requires a schema migration (v17 → v18) adding two nullable columns — the byte cursor and a tail fingerprint; existing line-number cursors are converted in place on the first scan without re-importing anything.
+
+### Pi Session Dedup Uses the Identity Indexes
+
+The combined dedup query (an OR across two identity columns) could only constrain the data-source prefix, scanning the entire Pi portion of the ledger for every parsed record — Pi imports got slower as usage history grew. It is now split into indexed point lookups with identical results, so import time no longer degrades with history size. ([#6667](https://github.com/farion1231/cc-switch/pull/6667))
+
+---
+
+## Upgrade Notes
+
+### This Release Includes a Database Migration; Downgrading Requires Restoring the Backup
+
+The schema migrates from v17 to v18 (a byte-cursor and a tail-fingerprint column on the session-scan cursor table), with a backup created automatically before migrating. Once this release has run, older CC Switch builds refuse to open the database — downgrading requires restoring that backup. Usage entries the old half-line bug had already skipped are not retroactively recovered — replaying them cannot be distinguished from re-importing already-rolled-up history.
+
+### Existing Codex OAuth Accounts Need One Re-Login
+
+Every managed ChatGPT (Codex OAuth) account added before this release is quarantined until you click "Re-login" on its row in the Auth Center — older records used the ChatGPT workspace ID as the account key and carry no separately recorded per-user identity, so an ordinary token refresh cannot prove which user an old record belongs to. Provider bindings are preserved; re-login updates the account in place. Be sure to use the row's "Re-login" button: signing in again through "Add account" only creates a second row (logins no longer merge by workspace) and leaves the old row — and any provider bound to it — still quarantined. ([#6780](https://github.com/farion1231/cc-switch/pull/6780))
+
+### Codex Releases Older Than 0.48 Lose Third-Party Authentication
+
+The provider-table token field that config-only switching writes is never read by pre-0.48 Codex. Upgrade Codex if you are still on an older build.
+
+### With the Preservation Toggle Off, Switching to a Third Party Deletes auth.json
+
+With the "Keep official login for direct switches" toggle **OFF (the default)**, switching to a third-party Codex provider now **deletes** `auth.json` rather than overwriting it with the API key. To get the ChatGPT login back: switch to an official provider bound to an Auth Center account (the login is written back in full from the stored account); an unbound official card that follows the Codex CLI's own login needs a `codex login` run. Turn the toggle ON to keep the official login across third-party switches.
+
+### Some Previously "Working" Codex Cards Are Now Refused at Switch Time
+
+Third-party cards with an empty config (no table to hold the key), and keyless cards relying on `requires_openai_auth = true` or a bare `openai_base_url` reroute to borrow the official login, are now refused by name. Add a proper `[model_providers.<id>]` entry or an API key to such cards.
+
+### Existing Codex Configs Are Rewritten on the Next Live Write Where 0.149 Requires It
+
+Legacy `openai_base_url` reroutes with a usable key become a `[model_providers.cc-switch]` table, stale reserved tables are renamed to a CC-Switch id, missing `name` fields are filled in, and `requires_openai_auth` on the active keyed third-party table is overridden on each switch to match the preservation toggle — a hand-set value on that table does not survive a switch.
+
+### Truncated or Externally Rewritten Claude Session Logs Are Skipped, Permanently and by Design
+
+The rewritten range is not replayed (replaying would double-count against already-pruned rollups), and the skip is reported in the sync result's error list.
+
+### Keys Already Cross-Contaminated Before the #6534 Fix Are Not Repaired Automatically
+
+If Codex providers sharing a base URL have already converged on one key, re-enter the correct key on each affected card once.
+
+### Restore Behavior Change (#6810)
+
+Restoring a snapshot in which an app has no enabled prompt now preserves that app's live prompt file — the client keeps loading its old content even though the Prompts panel shows everything disabled. Enable and then disable a prompt from the panel (or edit the file yourself) if you want it cleared.
+
+### Universal Provider Saves Can Now Fail Loudly
+
+If a live config file cannot be written for an app whose active provider is the generated child, the save reports an error naming that app; the database record is still saved — retry the sync or switch that app's provider once.
+
+### Existing TeamoRouter Providers Keep `api.teamorouter.com`
+
+Re-add from the preset, or edit the base URL, to move to `.cn`.
+
+### OpenCode Go Usage Auto-Enables Only for Providers Added After This Release
+
+For an existing card, open its usage-script settings and pick the Token Plan template → OpenCode Go once.
+
+---
+
+## Risk Notice
+
+### Carried-Over Notices
+
+**xAI Grok OAuth sign-in**: reuses the public OAuth client identity of the official Grok CLI; using it could lead to account restriction or suspension — see the [v3.18.0 release notes](v3.18.0-en.md#risk-notice) for details.
+
+**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.
+
+**SuperGrok quota queries**: the quota display on provider cards depends on a non-public billing endpoint at grok.com and may stop working once xAI changes the interface — see the [v3.19.0 release notes](v3.19.0-en.md#risk-notice) for details.
+
+**Third-party provider routing**: when the CC Switch local proxy converts and forwards Codex, Claude Desktop, or Grok Build requests to a third-party provider, each provider has different constraints on billing, compliance, and data retention. Please read the target provider's terms of service before use.
+
+By enabling these features, users accept the associated risks. CC Switch is not responsible for any account restriction, warning, or service suspension resulting from their use.
+
+---
+
+## Thanks
+
+Eight of this release's 26 commits come from 5 outside contributors.
+
+### Code Contributions
+
+- Thanks to @SaladDay: the entire workspace account-isolation line ([#6780](https://github.com/farion1231/cc-switch/pull/6780)), the JWT identity-parsing alignment ([#6831](https://github.com/farion1231/cc-switch/pull/6831)) and the Pi session-dedup indexes ([#6667](https://github.com/farion1231/cc-switch/pull/6667)); the missing exit-button capability was also independently discovered and fixed first by them in [#6567](https://github.com/farion1231/cc-switch/pull/6567).
+- Thanks to @YUZHEthefool: provider edits always reaching the live config ([#6779](https://github.com/farion1231/cc-switch/pull/6779), in collaboration with @BingZi-233) and the Codex edit-dialog key cross-contamination fix ([#6534](https://github.com/farion1231/cc-switch/pull/6534)) — the two hard data-correctness entries in "Fixed" are this work.
+- Thanks to @SailingLoong: restores keeping unmanaged prompt files intact ([#6810](https://github.com/farion1231/cc-switch/pull/6810)).
+- Thanks to @yovinchen: Otty terminal support ([#6620](https://github.com/farion1231/cc-switch/pull/6620)).
+- Thanks to @ISuuuu: the WSL2 contract tests running from prebuilt binaries ([#6472](https://github.com/farion1231/cc-switch/pull/6472)).
+
+### Issue Reports
+
+- Thanks to @hlwhl for the precise report on Codex 0.149's credential-inheritance change in [#6744](https://github.com/farion1231/cc-switch/issues/6744) — it framed this release's biggest line directly, and they were also first to propose a fix ([#6746](https://github.com/farion1231/cc-switch/pull/6746)).
+- Thanks to the reporters of the Team-workspace account-overwrite problem: @cp7553479 ([#2245](https://github.com/farion1231/cc-switch/issues/2245)), @Smilenize ([#5885](https://github.com/farion1231/cc-switch/issues/5885)), @yingjiezhao0820 ([#6688](https://github.com/farion1231/cc-switch/issues/6688)) and @buqi759 ([#6738](https://github.com/farion1231/cc-switch/issues/6738)).
+- Thanks to the key cross-contamination family: @Joaging ([#6414](https://github.com/farion1231/cc-switch/issues/6414)), @KawaiiSh1zuku ([#6594](https://github.com/farion1231/cc-switch/issues/6594)) and @Michael-py001 ([#6827](https://github.com/farion1231/cc-switch/issues/6827)).
+- Thanks to @gyzerocc for reporting the WebDAV restore wiping AGENTS.md ([#6778](https://github.com/farion1231/cc-switch/issues/6778)) — with the trigger condition pinpointed exactly.
+
+---
+
+## Download & Install
+
+Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) and download the build for your system, or get it from the official site [ccswitch.io](https://ccswitch.io) (downloads are distributed through Cloudflare edge nodes and do not depend on GitHub being reachable).
+
+### 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.20.1-Windows.msi`          | **Recommended** - MSI installer with auto-update |
+| `CC-Switch-v3.20.1-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.20.1-macOS.dmg`    | **Recommended** - DMG installer, drag to Applications |
+| `CC-Switch-v3.20.1-macOS.zip`    | Unzip and drag to Applications, Universal Binary      |
+| `CC-Switch-v3.20.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.20.1-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.20.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`              |
--- a/docs/release-notes/v3.20.1-ja.md
+++ b/docs/release-notes/v3.20.1-ja.md
@@ -0,0 +1,281 @@
+# CC Switch v3.20.1
+
+> 本リリースは Codex まわりの 2 つの大きな課題を解決します。**Codex CLI 0.149 への対応**——サードパーティ切り替えが 401「Missing API key」で失敗する問題の根治です。切り替えは config-only になり、キーはプロバイダ自身のテーブルに書かれ、`auth.json` には二度と入りません。0.149 が起動を拒否する一連の旧設定形状も、切り替えのたびに自動修復されます。もうひとつは **同じ ChatGPT Team ワークスペースの複数アカウントが互いを上書きしなくなったこと**——既存の管理対象アカウントは 1 回ずつ再ログインが必要です（アップグレード時の注意を参照）。データ信頼性の修正も 3 件：プロバイダ編集は必ず live 設定に届き、Codex の編集ダイアログが別カードのキーを表示することはなくなり、復元が手書きのプロンプトファイルを消すこともなくなりました。使用量側には「セッションログの自動スキャン」スイッチが加わり、大きなセッションファイルのスキャンは秒単位からミリ秒単位になりました。本リリースには**データベースマイグレーション（v17 → v18）が含まれます**——マイグレーション前にバックアップが自動作成され、ダウングレードにはその復元が必要です。
+
+**[English →](v3.20.1-en.md) | [中文版 →](v3.20.1-zh.md)**
+
+---
+
+## ハイライト：本リリースでできること
+
+- **Codex CLI ≥ 0.149 でサードパーティプロバイダを普通に切り替える**（[#6744](https://github.com/farion1231/cc-switch/issues/6744)）：0.149 以降、カスタムプロバイダは `auth.json` から環境認証情報を継承しなくなり、旧来の既定方式（キーを `auth.json` だけに書く）で行われたサードパーティ切り替えはすべて 401 で失敗していました。切り替えは全面的に config-only になりました——キーはプロバイダ自身の `[model_providers.*]` テーブル（`experimental_bearer_token`、Codex 0.48 から対応）に入り、`auth.json` は純粋な公式 ChatGPT ログインファイルに戻ります。
+- **同じ Team ワークスペースの複数の ChatGPT アカウントを安全に共存させる**（[#6780](https://github.com/farion1231/cc-switch/pull/6780)、[#2245](https://github.com/farion1231/cc-switch/issues/2245) を修正）：これまでアカウントはワークスペース ID をキーにしていたため、同じ Team の 2 人のメンバーは 1 件のレコードに統合され、後からログインした人が先の人のトークンを黙って上書きしていました。同一ワークスペースのログインは別々のアカウント行として共存し、引き継ぎ経由のリクエストは紐付けアカウントと照合されます——請求が別のメンバーに載ることはありません。
+- **「保存しました」を信じる**（[#6779](https://github.com/farion1231/cc-switch/pull/6779)）：クラッシュで残った引き継ぎバックアップ行のせいで、アクティブなプロバイダの編集がデータベースだけを更新し、実際の設定ファイルがまったく変わらないことがありました。所有権判定は作り直され、編集は必ず live 設定に届きます。
+- **編集ダイアログでそのカード自身のキーを見る**（[#6534](https://github.com/farion1231/cc-switch/pull/6534)、[#6414](https://github.com/farion1231/cc-switch/issues/6414) を修正）：共有の `auth.json` にはプロバイダの身元がなく、アクティブな Codex プロバイダを編集すると別カードの残置キーが表示され——保存すると固定化され——同じ Base URL を共有するカードのキーが互いに収斂していました（「model not found」）。フォームは `config.toml` 内のそのカード自身の bearer token からキーを再構築します。
+- **安心してバックアップを復元する**（[#6810](https://github.com/farion1231/cc-switch/pull/6810)、[#6778](https://github.com/farion1231/cc-switch/issues/6778) を修正）：クラウドスナップショットに有効なプロンプトがひとつもないアプリについて、WebDAV/S3 ダウンロードやバックアップインポートが手書きの `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `SOUL.md` を空に切り詰めることはなくなりました。
+- **バックグラウンドのセッションスキャンをオフにする**：使用量ページに「セッションログの自動スキャン」スイッチが加わりました。オフにすると手動モードになり、「今すぐ同期」を押したときだけローカルのセッションログをスキャンします。プロキシ引き継ぎのリクエスト計上はリアルタイムでデータベースに記録され、セッションファイルを読まないため、どちらでも記録は続きます。
+- **OpenCode Go のサブスクリプション残量を見る**：使用量スクリプトの Token Plan 照会が OpenCode Go を認識し、5 時間 / 週 / 月の 3 つのウィンドウの使用率とリセット時刻が使用量カードとトレイに表示されます。
+- **macOS でターミナルに Otty を選ぶ**（[#6620](https://github.com/farion1231/cc-switch/pull/6620)）：セッション再開・プロバイダターミナル・ツールコマンドの 3 か所で選べます。
+- **大きなセッションファイルのスキャンを秒からミリ秒にする**：Claude セッションログはバイトカーソルの増分スキャンに移行し、12 MB のアクティブなセッションファイルは全読み 6.04 秒から増分 9.3 ミリ秒になりました。
+
+---
+
+## 利用ガイド
+
+- **[プロバイダの追加](../user-manual/ja/2-providers/2.1-add.md)**：Codex config-only 切り替え後のプロバイダ管理の入口です。
+- **[使用量統計](../user-manual/ja/4-proxy/4.4-usage.md)**：セッションスキャンスイッチと Token Plan 残量照会の集計基準。
+
+---
+
+> [!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 からご報告ください。
+
+---
+
+## 概要
+
+本リリースの主軸は Codex にあり、出発点は上流の互換性の断絶です。Codex CLI 0.149 は認証情報の継承を厳格化し、カスタムプロバイダは `auth.json` の環境認証情報を読まなくなりました——旧来の既定方式で書かれたサードパーティ切り替えはすべて 401 で失敗します。CC Switch の答えはパッチではなく再設計です。サードパーティ切り替えは config-only になり——キーはプロバイダ自身の設定テーブルに入り、`auth.json` は純粋な公式 ChatGPT ログインファイルに戻ります。あわせて、0.149 が読み込みを拒否する一連の旧設定形状（予約 id を占有する古いテーブル、`name` のないテーブル、トップレベル `openai_base_url` の旧式ルーティング）は、切り替えと引き継ぎ投影のたびに自動修復され、新しい事前検証が 0.149 の読み込めない組み合わせを名指しで拒否します——「切り替え成功」の後に Codex が起動しない、という事態の代わりに。
+
+第 2 の主軸はアカウントとデータの安全です。同じ ChatGPT Team ワークスペースのメンバーが認証センターで互いを上書きすることはなくなり（既存の管理対象アカウントは 1 回の再ログインが必要）、プロバイダ編集は必ず live 設定に届き、Codex の編集ダイアログが別カードのキーを混入させることも、復元が手書きのプロンプトファイルを消すこともなくなりました。使用量側では、セッションスキャンに自動/手動スイッチとバイトカーソル増分スキャン（6.04 秒 → 9.3 ミリ秒）が加わり、Claude セッション計上の正確性の欠陥も 3 件修正されました——これが本リリース唯一のデータベースマイグレーション（v17 → v18）の由来です。
+
+**リリース日**：2026-08-28
+
+**変更規模**：26 commits | 66 files changed | +7,474 / -1,000 lines
+
+---
+
+## 新機能
+
+### セッションログスキャン：自動/手動モード
+
+使用量ページに「セッションログの自動スキャン」カードとスイッチが加わりました（既定はオン、アップグレード後の挙動は不変です）。オフにするとバックグラウンドのセッションスキャンは起動時の初回分も含めてすべて停止し、手動の入口として「今すぐ同期」ボタンが現れ、完了時にインポート件数・スキャンファイル数・エラー数を通知します。プロキシ引き継ぎのリクエスト計上はリアルタイムでデータベースに記録されセッションファイルを読まないため、スイッチに関係なく記録が続きます。起動時のコスト補填（データベースの既存行だけを修正）も手動モードで引き続き実行されます。
+
+### OpenCode Go サブスクリプション使用量
+
+使用量スクリプトの Token Plan 照会が OpenCode Go を認識し、5 時間 / 週 / 月の 3 つのウィンドウの使用率とリセット時刻を、既存のクォータ階層表示を再利用して使用量カードとトレイに表示します。エンドポイントは Bearer 認証のみ（`x-api-key` しか受け付けない推論側とちょうど正反対）。キーは有効でも Go サブスクリプションがない場合は、汎用の認証エラーではなく専用のメッセージ（HTTP 403）を表示し、使用量ゼロのウィンドウでは上流のプレースホルダーのリセット時刻を捨て、認識できないレスポンス形状では空のカードではなくエラーを報告します。Claude Code・Claude Desktop・Codex・OpenCode・Pi で新規追加した OpenCode Go プロバイダは照会を自動で有効化します。OpenCode Zen の従量課金は意図的に対象外です——このプランには上流に使用量 API がありません。
+
+### Otty ターミナル対応（macOS）
+
+「Otty」が macOS のターミナル選択肢に加わり、セッション再開・プロバイダターミナル・ツールコマンドの 3 つの入口をカバーします。起動時はまず Otty CLI 経由で既存ウィンドウの新しいタブを試み、次に新しい Otty ウィンドウへフォールバックします。プロバイダターミナルとツールコマンドは失敗時にさらに Terminal.app へフォールバックしますが、セッション再開の失敗はそのままエラーを報告し——Otty CLI が見つからない場合は明示的なインストール案内つき——コマンドをクリップボードにコピーします。CLI の探索はアプリバンドル（システムとユーザー単位）・Homebrew のパス・PATH を調べます。ユーザーマニュアルの macOS ターミナル表も修正されました——Kaku と Warp は以前から対応していたのに表に載っていませんでした。（[#6620](https://github.com/farion1231/cc-switch/pull/6620)）
+
+---
+
+## 変更
+
+### Codex のサードパーティ切り替えは config-only になりました
+
+サードパーティ Codex プロバイダへの切り替えは、API キーをそのプロバイダ自身の `[model_providers.*]` テーブル（`experimental_bearer_token` フィールド、Codex 0.48 から対応）に書き込み、**`auth.json` には二度と書きません**——`auth.json` は純粋な公式 ChatGPT ログインファイルに戻ります。背景は、Codex 0.149 がカスタムプロバイダによる `auth.json` の環境認証情報の継承をやめたことです。旧来の既定方式（キーを `auth.json` だけに書く）で行われたサードパーティ切り替えは、それ以来 401 で失敗していました。
+
+「直接切替時に公式ログインを保持」スイッチの意味はひとつだけになりました。オンなら公式 ChatGPT ログインはサードパーティ切り替えを通じて一切触れられません。オフなら `auth.json` を API キーで上書きする代わりに**削除**します（削除に失敗すると、公式ログインが Codex 設定ディレクトリに残っている旨の警告が表示されます）。2 つの安全ゲートは保持モードに限らず**サードパーティ切り替えのたびに**実行されます。キーがあるのに受け皿となるプロバイダテーブルがない設定、キーがないのに公式ログインへフォールバックしてしまう設定（自前の認証情報のない `requires_openai_auth = true`、あるいは裸のトップレベル `openai_base_url` ルーティング）は、どちらも名指しで拒否されます——空設定のサードパーティカード（これまで黙って `auth.json` に相乗りしていました）も含めてです。アクティブなキー付きサードパーティテーブルの `requires_openai_auth` は直接切り替えのたびに保持スイッチへ合わせて刻印し直され、Codex のログイン画面はディスク上の実態と一致します。（[#6744](https://github.com/farion1231/cc-switch/issues/6744)、[#6746](https://github.com/farion1231/cc-switch/pull/6746)）
+
+### TeamoRouter プリセットが teamorouter.cn へ移行
+
+8 アプリのプリセットはすべて `api.teamorouter.cn` を指すようになり、旧 `.com` エンドポイントは Claude Code・Claude Desktop・Codex・Grok Build で選択・速度測定可能なフォールバック候補として登録されます。保存済みの既存 TeamoRouter プロバイダは、それぞれ保存時の Base URL を保ちます。
+
+---
+
+## 修正
+
+### 同一ワークスペースの ChatGPT アカウントが認証センターで統合されなくなりました
+
+管理対象の Codex OAuth アカウントは `chatgpt_account_id` をキーにしていましたが、これは人ではなく ChatGPT ワークスペースを識別する値です。同じ Team ワークスペースの 2 人のメンバーは 1 件のレコードに統合され、後のログインが先のトークンを黙って上書きし、プロバイダの紐付けは最後にログインした人を指していました。アカウントはローカルの識別子をキーにし、ユーザー身元の証明として OIDC subject を保持するようになり、同一ワークスペースのログインは別々の行として共存します。引き継ぎ経由のリクエストは、さらに紐付けアカウントの live トークンと照合されます。別のメンバーのログイン状態を保持したままの Codex セッションは、誤った身元で転送される代わりに「Codex を再起動してください」という明確なエラーを受け取り、外向きのワークスペースヘッダは常にクライアントの自己申告ではなくアカウント紐付けに由来します。CLI がローテーションしたリフレッシュトークンの取り込みと、アカウント削除時の `auth.json` 削除は、いずれも証明可能な所有権を要求するようになりました——CC Switch が同一ワークスペースの別メンバーのログインを取り込んだり削除したりすることはもうできません。各アカウント行はその場で「再ログイン」（紐付けは保持）でき、デバイスログインのキャンセルや置き換えは保留中のフローを CC Switch 内部で破棄します——放置されたブラウザ認可が数分後にコミットされてアカウントを黙って上書きすることはできません。正しい JWT の形をしていない id_token は一切の身元を生みません——不正な形式や切り詰められたトークンがユーザーの代わりになることはありません。（[#6780](https://github.com/farion1231/cc-switch/pull/6780)、[#6831](https://github.com/farion1231/cc-switch/pull/6831)、[#2245](https://github.com/farion1231/cc-switch/issues/2245) を修正）
+
+### Codex 0.149 互換性修復の一群：既存設定が Codex の起動を妨げなくなりました
+
+Codex 0.149 に読み込みを拒否させる一連の設定形状——ユーザーには「CC Switch は切り替え成功と言うのに Codex が起動しない」と見えていました——が、プロバイダ切り替えと引き継ぎ投影のたびに自動修復されるようになりました。具体的には：古い引き継ぎ投影が書いた `[model_providers.openai]` / `.ollama` / `.lmstudio` の残置テーブル（予約 id の上書きは検証エラーになります）は CC Switch 自有の id へ無損失で改名され、読み込み可能な形に正規化されます。`name` のないプロバイダテーブルは補填されます（0.149 は名無しテーブルが 1 つでもあると設定全体を拒否します——Bedrock テーブルは意図的に名無しのままです。名前を付けると組み込みのマージが壊れるためです）。使用可能なキーを持つ旧式のトップレベル `openai_base_url` ルーティングは正規のカスタムプロバイダテーブルへ移行されます（キーのないルーティングは代わりに切り替え時の安全ゲートに拒否されます）。新しい事前検証は 0.149 の読み込めないフィールドの組み合わせを、問題のテーブルを名指しして拒否します——「切り替え成功」として書き出す代わりに。組み込み `openai` プロバイダへルーティングされたカードの引き継ぎは、予約テーブルを作る代わりに公式対応のトップレベル設定を使い、`ollama` / `lmstudio` へルーティングされたカードの引き継ぎは明示的なエラーで失敗します。予約 id リストは上流と完全に一致し（大文字小文字を区別。`amazon-bedrock-runtime` を追加、旧 `oss` / `ollama-chat` は通常のカスタムプロバイダとして扱われ、キーがようやく自分のテーブルに届きます）、インラインの `model_providers` テーブルも注入トークンを受け取ります——死んだトップレベルフィールドが残る代わりに。
+
+### 拒否された切り替えが、拒否されたカードを壊さなくなりました
+
+live 書き込みの検証は、現在プロバイダのポインタが動く前の事前検証として実行されるようになりました。以前は書き込み層の拒否が `current` のコミット後に起きていたため、次の切り替えが古い live 設定を拒否されたプロバイダの保存済み設定へ書き戻していました。
+
+### プロバイダ編集は必ず live 設定ファイルに届きます
+
+クラッシュや復元失敗で残った引き継ぎバックアップ行のせいで、アクティブなプロバイダの保存（Claude Desktop を除く）が引き継ぎ経路に乗ってしまい——データベースとバックアップ行だけを更新し、実際の設定ファイルは古いエンドポイントと古いキーのまま無期限に放置されていました。所有権は引き継ぎの実際の証拠を要求する単一の述語で判定されるようになりました（live ファイル内のプレースホルダー、またはプロキシが有効かつ稼働中でバックアップ行がある、または切り替え処理がアプリ単位のロックとバックアップ行を併せ持つ）。古いバックアップ行は書き込みを乗っ取る代わりに、編集されたプロバイダに合わせて更新されます。ユニバーサルプロバイダの保存は、生成された各子設定を、それをアクティブプロバイダとするアプリの live 設定へ再投影し、失敗をアプリ名つきで個別報告します——一律「成功」と言う代わりに。（[#6779](https://github.com/farion1231/cc-switch/pull/6779)）
+
+### Codex 編集ダイアログが別のプロバイダのキーを表示しなくなりました
+
+公式ログイン保持が有効なとき、`auth.json` はプロバイダの身元を持たない共有スロットであり、編集ダイアログはフォームの初期値としてそれを優先していました——アクティブな Codex プロバイダを編集すると、別カードの残置キーが表示され、保存で固定化され、同じ Base URL を共有するカードのキーが互いに収斂していました（「model not found」エラー）。ダイアログは `config.toml` 内のそのプロバイダ自身の bearer token からキーを再構築するようになりました。公式カテゴリと OAuth 専用のプロバイダは影響を受けません。また `config.toml` に自前の bearer token を持たないカード——旧バージョンや手書き保守の形状で、本リリースからはサードパーティ切り替えのたびに書き込まれます——は従来どおり live の `auth.json`（手動編集を含む）を読み続けます。（[#6534](https://github.com/farion1231/cc-switch/pull/6534)、[#6414](https://github.com/farion1231/cc-switch/issues/6414) を修正）
+
+### 復元が管理外のプロンプトファイルを消さなくなりました
+
+スナップショットにあるアプリの有効なプロンプトがひとつもない場合、WebDAV/S3 ダウンロードやバックアップインポートはそのアプリの live プロンプトファイル（`CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `SOUL.md`）を空に切り詰めていました——同期ペイロードに一度も含まれたことのない、ローカルの手書き内容を破壊していたのです。そのような復元はファイルに一切触れなくなりました。プロンプトパネルから最後のプロンプトを無効化した場合は、従来どおりファイルをクリアします。（[#6810](https://github.com/farion1231/cc-switch/pull/6810)、[#6778](https://github.com/farion1231/cc-switch/issues/6778) を修正）
+
+### リカバリ画面の終了ボタンが本当に終了するようになりました
+
+`process:allow-exit` 権限が欠けていたため、v3.20.0 では「データベースバージョンが新しすぎる」リカバリ画面の終了ボタンと、設定読み込み失敗後の終了呼び出しが、どちらも IPC 層に黙って拒否されていました。終了ボタンは何も起こさず（ウィンドウを閉じれば終了できました）、設定読み込み失敗後はアプリが意図された終了の代わりに通常の UI へ進んでいました。この問題は @SaladDay さんが [#6567](https://github.com/farion1231/cc-switch/pull/6567) でより早く独立に発見し、先に修正していたものです。
+
+### Claude セッション計上の正確性修正 3 件
+
+増分スキャナとともに、いずれも Claude セッションログ経路のデータ正確性修正が 3 件入りました。書き込み途中のログ行は、旧来の行番号カーソルに恒久的にスキップされていました（未完成の末尾がカーソルを進めてしまい、完成後のメッセージは二度とインポートされません）——バイトカーソルは完全な行までしかコミットしないため、そのメッセージは次のラウンドで取り込まれます。外部で切り詰められた・書き換えられたセッションファイルは**決して再取り込みしません**。30 日ロールアップが明細行をすでに整理した後の再インポートは合計を恒久的に水増しするため、カーソルは新しいファイル末尾に固定され、スキップされた範囲は黙って捨てられる代わりに同期結果のエラー一覧に報告されます（切り詰めはカーソルのファイル超過で、同サイズの書き換えはカーソル前バイトのフィンガープリントで検出します）。ファイル途中の読み取りエラーは、コミット済みの進捗を保持して次のラウンドに同じ位置から再開し、報告されます——きれいな成功を返す代わりに。カーソルの事前取得に失敗した場合はそのラウンドを中止します——初回スキャンのように振る舞って履歴を二重インポートする代わりに。
+
+---
+
+## パフォーマンス
+
+### Claude セッションログ：バイトカーソルによる増分スキャン
+
+各スキャンラウンドは、最後にコミットしたバイトオフセットへ直接シークし、追記された分だけを読みます——変更のあったファイルを最初から最後まで読み直す代わりに。変更に付属するベンチマークでは、12 MB のアクティブなセッションファイルが全読み解析 6.04 秒から増分読み取り 9.3 ミリ秒になりました。Claude・Gemini・OpenCode・Grok Build・Pi のファイル単位カーソルは、ファイルごとの照会の代わりにインポーターごとに毎ラウンド 1 回のテーブル読み取りで事前取得されます。Claude 経路では各ファイルのインポートとカーソル前進が単一トランザクションでコミットされます。1,017 個のセッションファイル（409 MB）の凍結スナップショット再生では、旧スキャナと完全に一致する集計が得られました。スキーマのマイグレーション（v17 → v18）が必要で、NULL 許容の 2 列——バイトカーソルと末尾フィンガープリント——を追加します。既存の行番号カーソルは初回スキャンでその場で変換され、何も再インポートしません。
+
+### Pi セッション重複排除がアイデンティティインデックスを使うようになりました
+
+統合された重複排除クエリ（2 つのアイデンティティ列にまたがる OR）はデータソース接頭辞しか絞り込めず、解析レコードごとに台帳の Pi 区画全体を走査していました——Pi のインポートは使用量履歴が増えるほど遅くなっていました。同一の結果を返すインデックス活用の点照会に分割され、インポート時間は履歴の規模で劣化しなくなりました。（[#6667](https://github.com/farion1231/cc-switch/pull/6667)）
+
+---
+
+## アップグレード時の注意
+
+### 本リリースにはデータベースマイグレーションが含まれ、ダウングレードにはバックアップの復元が必要です
+
+スキーマは v17 から v18 へ移行します（セッションスキャンのカーソルテーブルにバイトカーソルと末尾フィンガープリントの 2 列を追加）。マイグレーション前にバックアップが自動作成されます。本リリースを一度実行すると、旧バージョンの CC Switch はデータベースを開けなくなります——ダウングレードにはそのバックアップの復元が必要です。旧来の書き込み途中行の欠陥がすでに取りこぼした使用量エントリは遡って回収しません——その再取り込みは、ロールアップ済み履歴の再インポートと区別できないためです。
+
+### 既存の Codex OAuth アカウントは 1 回の再ログインが必要です
+
+本リリース以前に追加された管理対象 ChatGPT（Codex OAuth）アカウントはすべて、認証センターの該当アカウント行で「再ログイン」を押すまで隔離状態になります——旧レコードは ChatGPT ワークスペース ID をアカウントキーとして使い、個別に記録されたユーザー身元を持たないため、通常のトークン更新では旧レコードがどのユーザーのものか証明できません。プロバイダの紐付けは保持され、再ログインはアカウントをその場で更新します。必ずアカウント行の「再ログイン」ボタンを使ってください。「アカウントを追加」から再ログインしても 2 件目のレコードが作られるだけで（ログインはもうワークスペース単位で統合されません）、旧レコード——およびそれに紐付いたプロバイダ——は隔離されたままです。（[#6780](https://github.com/farion1231/cc-switch/pull/6780)）
+
+### Codex 0.48 より前のバージョンはサードパーティ認証を失います
+
+config-only 切り替えが書き込むプロバイダテーブルのトークンフィールドを、0.48 より前の Codex は一切読みません。古い Codex をお使いの場合はアップグレードしてください。
+
+### 保持スイッチがオフのとき、サードパーティへの切り替えは auth.json を削除します
+
+「直接切替時に公式ログインを保持」スイッチが**オフ（既定）**のとき、サードパーティ Codex プロバイダへの切り替えは `auth.json` を API キーで上書きする代わりに**削除**するようになりました。ChatGPT ログインを取り戻すには：認証センターのアカウントに紐付いた公式プロバイダへ切り替えれば、ログインは保存済みアカウントから完全に書き戻されます。Codex CLI 自身のログインに追従する紐付けなしの公式カードの場合は `codex login` の実行が必要です。公式ログインをサードパーティ切り替え越しに残したい場合は、スイッチをオンにしてください。
+
+### これまで「動いていた」一部の Codex カードは切り替え時に拒否されるようになります
+
+空設定のサードパーティカード（キーの受け皿となるテーブルがない）、および `requires_openai_auth = true` や裸の `openai_base_url` ルーティングで公式ログインを借用していたキーなしカードは、名指しで拒否されるようになりました。そうしたカードには正規の `[model_providers.<id>]` エントリか API キーを追加してください。
+
+### 既存の Codex 設定は、0.149 が必要とする範囲で次回の live 書き込み時に書き換えられます
+
+使用可能なキーを持つ旧式 `openai_base_url` ルーティングは `[model_providers.cc-switch]` テーブルになり、予約 id を占有する残置テーブルは CC Switch 自有の id へ改名され、欠けている `name` フィールドは補填されます。アクティブなキー付きサードパーティテーブルの `requires_openai_auth` は切り替えのたびに保持スイッチへ合わせて上書きされます——そのテーブルに手動設定した値は切り替え後には残りません。
+
+### 切り詰め・外部書き換えされた Claude セッションログは、設計として恒久的にスキップされます
+
+書き換えられた範囲は再取り込みされず（再取り込みは整理済みロールアップとの二重計上になります）、スキップは同期結果のエラー一覧に報告されます。
+
+### #6534 修正以前にすでに混入したキーは自動修復されません
+
+同じ Base URL を共有する Codex プロバイダのキーがすでに 1 つに収斂している場合は、影響を受けた各カードで正しいキーを一度入力し直してください。
+
+### 復元の挙動変更（#6810）
+
+あるアプリの有効なプロンプトがひとつもないスナップショットを復元しても、そのアプリの live プロンプトファイルは保持されるようになりました——プロンプトパネルではすべて無効と表示されていても、クライアントは古い内容を読み込み続けます。クリアしたい場合は、パネルでプロンプトを有効化してから無効化してください（またはファイルを直接編集してください）。
+
+### ユニバーサルプロバイダの保存は明示的に失敗することがあります
+
+生成された子設定をアクティブプロバイダとするアプリの live 設定ファイルへの書き込みに失敗した場合、保存はそのアプリ名を挙げてエラーを報告します。データベースのレコードは保存済みです——同期を再試行するか、そのアプリのプロバイダを一度切り替え直してください。
+
+### 既存の TeamoRouter プロバイダは `api.teamorouter.com` のままです
+
+プリセットから追加し直すか、Base URL を編集すれば `.cn` へ移行できます。
+
+### OpenCode Go の使用量照会は、本リリース以降に追加したプロバイダのみ自動で有効になります
+
+既存のカードでは、使用量スクリプト設定を開いて Token Plan テンプレート → OpenCode Go を一度選んでください。
+
+---
+
+## リスク通知
+
+### 継続してお伝えしている注意事項
+
+**xAI Grok OAuth サインイン**：公式 Grok CLI の公開 OAuth クライアント識別情報を再利用しており、利用によってアカウントの制限や停止につながる恐れがあります——詳細は [v3.18.0 release notes](v3.18.0-ja.md#リスク通知) を参照してください。
+
+**Codex OAuth リバースプロキシ**：ChatGPT サブスクリプションの Codex OAuth をリバースプロキシ経由で使用すると、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 release notes](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
+
+**SuperGrok の残量照会**：プロバイダカードの残量表示は grok.com の非公開の課金エンドポイントに依存しており、xAI がインターフェースを変更すると機能しなくなる可能性があります——詳細は [v3.19.0 release notes](v3.19.0-ja.md#リスク通知) を参照してください。
+
+**サードパーティプロバイダへのルーティング**：CC Switch のローカルプロキシで Codex・Claude Desktop・Grok Build のリクエストを変換してサードパーティのプロバイダへ転送する場合、課金・コンプライアンス・データ保持に関する制約はプロバイダごとに異なります。利用前に対象プロバイダの利用規約をお読みください。
+
+上記の機能を有効にした時点で、ユーザーは関連するリスクを自ら引き受けることになります。CC Switch は、これらの機能の利用に起因するアカウントの制限・警告・サービス停止について、一切の責任を負いません。
+
+---
+
+## 謝辞
+
+本リリースの 26 コミットのうち 8 は 5 名の外部コントリビューターによるものです。
+
+### コード貢献
+
+- @SaladDay さんに感謝します：ワークスペースアカウント分離の主軸全体（[#6780](https://github.com/farion1231/cc-switch/pull/6780)）、JWT 身元解析の整合（[#6831](https://github.com/farion1231/cc-switch/pull/6831)）、Pi セッション重複排除のインデックス化（[#6667](https://github.com/farion1231/cc-switch/pull/6667)）。終了ボタンの権限欠落も、[#6567](https://github.com/farion1231/cc-switch/pull/6567) でより早く独立に発見し先に修正されたのは同氏です。
+- @YUZHEthefool さんに感謝します：プロバイダ編集の live 設定への必達（[#6779](https://github.com/farion1231/cc-switch/pull/6779)、@BingZi-233 さんとの協働）と、Codex 編集ダイアログのキー混入修正（[#6534](https://github.com/farion1231/cc-switch/pull/6534)）——「修正」章のデータ正確性の 2 大項目はこの仕事です。
+- @SailingLoong さんに感謝します：復元時の管理外プロンプトファイルの保全（[#6810](https://github.com/farion1231/cc-switch/pull/6810)）。
+- @yovinchen さんに感謝します：Otty ターミナル対応（[#6620](https://github.com/farion1231/cc-switch/pull/6620)）。
+- @ISuuuu さんに感謝します：WSL2 契約テストのプリビルドバイナリ実行化（[#6472](https://github.com/farion1231/cc-switch/pull/6472)）。
+
+### 問題報告
+
+- [#6744](https://github.com/farion1231/cc-switch/issues/6744) で Codex 0.149 の認証情報継承の変化を正確に報告してくださった @hlwhl さんに感謝します——本リリース最大の主軸の方向を直接定めたうえ、最初に修正 PR（[#6746](https://github.com/farion1231/cc-switch/pull/6746)）を提案してくださったのも同氏です。
+- Team ワークスペースのアカウント上書き問題の報告者の皆さんに感謝します：@cp7553479 さん（[#2245](https://github.com/farion1231/cc-switch/issues/2245)）、@Smilenize さん（[#5885](https://github.com/farion1231/cc-switch/issues/5885)）、@yingjiezhao0820 さん（[#6688](https://github.com/farion1231/cc-switch/issues/6688)）、@buqi759 さん（[#6738](https://github.com/farion1231/cc-switch/issues/6738)）。
+- キー混入一族の報告者の皆さんに感謝します：@Joaging さん（[#6414](https://github.com/farion1231/cc-switch/issues/6414)）、@KawaiiSh1zuku さん（[#6594](https://github.com/farion1231/cc-switch/issues/6594)）、@Michael-py001 さん（[#6827](https://github.com/farion1231/cc-switch/issues/6827)）。
+- WebDAV 復元による AGENTS.md 消失を報告してくださった @gyzerocc さん（[#6778](https://github.com/farion1231/cc-switch/issues/6778)）に感謝します——トリガー条件が正確に特定されていました。
+
+---
+
+## ダウンロードとインストール
+
+[Releases](https://github.com/farion1231/cc-switch/releases/latest) からお使いのシステムに合ったビルドをダウンロードするか、公式サイト [ccswitch.io](https://ccswitch.io) から入手してください（ダウンロードは Cloudflare のエッジノード経由で配信され、GitHub への到達性に依存しません）。
+
+### システム要件
+
+| システム | 最低バージョン             | アーキテクチャ                      |
+| -------- | -------------------------- | ----------------------------------- |
+| Windows  | Windows 10 以降            | x64 / ARM64                         |
+| macOS    | macOS 12 (Monterey) 以降   | Intel (x64) / Apple Silicon (arm64) |
+| Linux    | 下表参照                   | x64 / ARM64                         |
+
+### Windows
+
+| ファイル                                 | 説明                                              |
+| ---------------------------------------- | ------------------------------------------------- |
+| `CC-Switch-v3.20.1-Windows.msi`          | **推奨** - MSI インストーラ、自動更新対応         |
+| `CC-Switch-v3.20.1-Windows-Portable.zip` | ポータブル版、解凍してすぐ使用、レジストリ不使用  |
+
+Windows ARM64 デバイスでは、ファイル名に `arm64` を含む成果物を選んでください。
+
+### macOS
+
+| ファイル                         | 説明                                                  |
+| -------------------------------- | ----------------------------------------------------- |
+| `CC-Switch-v3.20.1-macOS.dmg`    | **推奨** - DMG インストーラ、Applications へドラッグ  |
+| `CC-Switch-v3.20.1-macOS.zip`    | 解凍後 Applications へドラッグ、Universal Binary      |
+| `CC-Switch-v3.20.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.20.1-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.20.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`              |
--- a/docs/release-notes/v3.20.1-zh.md
+++ b/docs/release-notes/v3.20.1-zh.md
@@ -0,0 +1,281 @@
+# CC Switch v3.20.1
+
+> 这一版围绕 Codex 补两笔硬账：**适配 Codex CLI 0.149**——第三方切换 401「Missing API key」的根治：切换改为 config-only，密钥随供应商表走、不再进 `auth.json`，一族让 0.149 拒绝启动的历史配置形态也在每次切换时自动修复；**同一 ChatGPT Team workspace 的多个账号不再互相覆盖**——存量托管账号需逐个重新登录一次（见升级提醒）。数据可靠性另有三条硬修复：供应商编辑必达 live 配置、Codex 编辑框不再串染别张卡的密钥、恢复备份不再清空手写的 prompt 文件。用量侧新增「自动扫描会话记录」开关，大会话文件的扫描从秒级降到毫秒级。本版**包含数据库迁移（v17 → v18）**，升级前自动备份，降级需还原备份。
+
+**[English →](v3.20.1-en.md) | [日本語版 →](v3.20.1-ja.md)**
+
+---
+
+## 重点内容：你现在可以
+
+- **在 Codex CLI ≥ 0.149 上正常切换第三方供应商**（[#6744](https://github.com/farion1231/cc-switch/issues/6744)）：0.149 起自定义 provider 不再从 `auth.json` 继承环境凭据，以旧默认方式（密钥只写 `auth.json`）完成的第三方切换一律 401。切换现已整体改为 config-only——密钥写进供应商自己的 `[model_providers.*]` 表（`experimental_bearer_token`，Codex 0.48 起支持），`auth.json` 回归纯粹的官方 ChatGPT 登录文件。
+- **让同一 Team workspace 的多个 ChatGPT 账号安全共存**（[#6780](https://github.com/farion1231/cc-switch/pull/6780)，修复 [#2245](https://github.com/farion1231/cc-switch/issues/2245)）：此前账号以 workspace ID 为主键，同一 Team 两名成员会合并成一条记录、后登录者静默覆盖前者的令牌。现在同 workspace 登录并存为独立账号行，接管下的请求还会校验账号一致性——绝不把账单记到另一名成员头上。
+- **相信「保存成功」四个字**（[#6779](https://github.com/farion1231/cc-switch/pull/6779)）：崩溃残留的接管备份行曾让活跃供应商的编辑只更新数据库、真正的配置文件纹丝不动。所有权判定已重建，编辑必达 live 配置。
+- **在编辑框里看到这张卡自己的密钥**（[#6534](https://github.com/farion1231/cc-switch/pull/6534)，修复 [#6414](https://github.com/farion1231/cc-switch/issues/6414)）：共享的 `auth.json` 没有供应商身份，编辑活跃 Codex 供应商可能显示——保存后固化——另一张卡遗留的 key，同 base URL 的卡密钥互相趋同、报「model not found」。表单现在从 `config.toml` 里该卡自己的 bearer token 重建密钥。
+- **放心恢复备份**（[#6810](https://github.com/farion1231/cc-switch/pull/6810)，修复 [#6778](https://github.com/farion1231/cc-switch/issues/6778)）：云端快照没有任何已启用 prompt 时，WebDAV/S3 下载或备份导入不再把本地手写的 `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `SOUL.md` 清成空文件。
+- **关掉后台会话扫描**：用量页新增「自动扫描会话记录」开关，关闭即手动模式——仅在点击「立即同步」时扫描本地会话记录；代理接管的请求记账实时落库、与会话文件无关，照常记录。
+- **看到 OpenCode Go 的订阅额度**：用量脚本的 Token Plan 查询现在识别 OpenCode Go，5 小时 / 周 / 月三个窗口的用量百分比与重置时间进入用量卡与托盘。
+- **在 macOS 上把终端设为 Otty**（[#6620](https://github.com/farion1231/cc-switch/pull/6620)）：会话恢复、供应商终端与工具命令三处入口都可选。
+- **让大会话文件的扫描从秒级降到毫秒级**：Claude 会话日志改为字节游标增量扫描，12 MB 活跃会话文件从整读 6.04 秒降到增量 9.3 毫秒。
+
+---
+
+## 使用攻略
+
+- **[添加供应商](../user-manual/zh/2-providers/2.1-add.md)**：Codex config-only 切换后的供应商管理入口。
+- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：会话扫描开关与 Token Plan 额度查询的口径。
+
+---
+
+> [!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 反馈。
+
+---
+
+## 概览
+
+这一版的主线在 Codex，起点是一次上游的兼容性断裂：Codex CLI 0.149 收紧了凭据继承，自定义 provider 不再读取 `auth.json` 里的环境凭据，以旧默认方式写入的第三方切换全部 401。CC Switch 的应对不是打补丁，而是把第三方切换整个改成 config-only——密钥随供应商自己的配置表走，`auth.json` 回归纯粹的官方 ChatGPT 登录文件；同时一族让 0.149 拒绝加载的历史配置形态（占用保留 id 的旧表、缺 `name` 的表、顶层 `openai_base_url` 旧式路由）在每次切换与接管投影时自动修复，并新增写前预检——0.149 无法加载的组合会被点名拒绝，而不是「切换成功」之后 Codex 起不来。
+
+第二条主线是账号与数据安全：同一 ChatGPT Team workspace 的成员在认证中心不再互相覆盖（存量托管账号需重登一次）；供应商编辑保证必达 live 配置；Codex 编辑框不再串染别张卡的密钥；恢复备份不再清空手写的 prompt 文件。用量侧，会话扫描获得自动/手动开关与字节游标增量扫描（6.04 秒 → 9.3 毫秒），并顺手修掉三个 Claude 会话记账的正确性缺陷——这也是本版唯一数据库迁移（v17 → v18）的由来。
+
+**发布日期**：2026-08-28
+
+**更新规模**：26 commits | 66 files changed | +7,474 / -1,000 lines
+
+---
+
+## 新功能
+
+### 会话记录扫描：自动/手动模式
+
+用量页新增「自动扫描会话记录」卡片与开关（默认开启，升级后行为不变）。关闭后停止一切后台会话扫描——包括启动时的首轮——并出现「立即同步」按钮作为手动入口，完成后以提示显示导入条数、扫描文件数与错误计数。代理接管的请求记账是实时落库、从不读会话文件，无论开关如何都照常记录；启动时的成本回填只修数据库既有行，手动模式下也照常执行。
+
+### OpenCode Go 订阅用量
+
+用量脚本的 Token Plan 查询现在识别 OpenCode Go，在用量卡与托盘显示 5 小时 / 周 / 月三个窗口的用量百分比与重置时间，复用既有的配额层级展示。该端点只认 Bearer 认证（与推理侧只认 `x-api-key` 恰好相反）；密钥有效但未订阅 Go 计划时显示明确的提示（HTTP 403）而不是笼统的认证失败，零用量窗口会丢弃上游的占位重置时间，无法识别的响应形状报错而不是空卡。在 Claude Code、Claude Desktop、Codex、OpenCode 与 Pi 新添加的 OpenCode Go 供应商自动启用查询；OpenCode Zen 按量付费刻意不覆盖——该计划上游没有用量 API。
+
+### Otty 终端支持（macOS）
+
+「Otty」加入 macOS 终端选择器，覆盖会话恢复、供应商终端与工具命令三处入口。启动时先尝试经 Otty CLI 在既有窗口开新标签页，再退到新开 Otty 窗口；供应商终端与工具命令在失败时进一步回退到 Terminal.app，而会话恢复失败则直接报错——Otty CLI 缺失时附明确的安装提示——并把命令复制到剪贴板。CLI 探测覆盖应用包（系统与用户级）、Homebrew 路径与 PATH。用户手册的 macOS 终端表格也顺带修正——Kaku 与 Warp 早已支持却漏在表外。（[#6620](https://github.com/farion1231/cc-switch/pull/6620)）
+
+---
+
+## 变更
+
+### Codex 第三方切换改为 config-only
+
+切换到第三方 Codex 供应商时，密钥现在写进该供应商自己的 `[model_providers.*]` 表（`experimental_bearer_token` 字段，Codex 0.48 起支持），**不再写进 `auth.json`**——它回归纯粹的官方 ChatGPT 登录文件。背景是 Codex 0.149 停止让自定义 provider 从 `auth.json` 继承环境凭据，以旧默认方式（密钥只写 `auth.json`）完成的第三方切换从此 401。
+
+「非接管切换时保留官方登录」开关随之只剩一个含义：开启时官方 ChatGPT 登录在第三方切换中完全不被触碰；关闭时**删除** `auth.json` 而不是用 API 密钥覆盖它（删除失败会弹出警告，提示官方登录仍留在 Codex 配置目录中）。两道安全闸现在在**每次第三方切换**都执行、不再只限保留模式：有密钥却没有任何 provider 表可以承载，或没有密钥却会回退到官方登录（`requires_openai_auth = true` 且无自有凭据，或裸的顶层 `openai_base_url` 路由），都会被点名拒绝——包括配置为空的第三方卡，它们此前一直静默搭乘 `auth.json`。活跃的带密钥第三方表上的 `requires_openai_auth` 会在每次直接切换时按保留开关重新戳记，让 Codex 的登录界面与磁盘上的实际状态一致。（[#6744](https://github.com/farion1231/cc-switch/issues/6744)、[#6746](https://github.com/farion1231/cc-switch/pull/6746)）
+
+### TeamoRouter 预设迁至 teamorouter.cn
+
+八个应用的预设全部指向 `api.teamorouter.cn`，旧 `.com` 端点在 Claude Code、Claude Desktop、Codex 与 Grok Build 上注册为可选择、可测速的后备端点。已保存的存量 TeamoRouter 供应商保持各自原有的 Base URL 不变。
+
+---
+
+## 修复
+
+### 同一 workspace 的 ChatGPT 账号不再在认证中心合并
+
+托管的 Codex OAuth 账号此前以 `chatgpt_account_id` 为主键——它标识的是 ChatGPT workspace 而不是人：同一 Team workspace 的两名成员会坍缩成一条记录，后登录者静默覆盖前者的令牌，供应商绑定跟着指向最后登录的人。账号现在以本地身份建键、保留 OIDC subject 作为用户身份凭证，同 workspace 登录并存为独立账号行。经接管路由的请求会额外对照绑定账号的 live 令牌校验：仍持有另一名成员登录态的 Codex 会话得到「请重启 Codex」的明确报错，而不是以错误身份被转发；外发的 workspace 请求头一律来自账号绑定而不是客户端自报。收养 CLI 轮转过的刷新令牌、以及移除账号时删除 `auth.json`，现在都要求可证明的所有权——CC Switch 不再可能收养或删除同 workspace 另一名成员的登录。每条账号行提供就地「重新登录」（绑定保留）；取消或被取代的设备登录会在 CC Switch 内部丢弃等待中的流程——被放弃的浏览器授权无法在几分钟后被提交、悄悄覆盖账号。不是合法 JWT 形状的 id_token 不再产生任何身份——畸形或截断的令牌永远无法冒充用户。（[#6780](https://github.com/farion1231/cc-switch/pull/6780)、[#6831](https://github.com/farion1231/cc-switch/pull/6831)，修复 [#2245](https://github.com/farion1231/cc-switch/issues/2245)）
+
+### Codex 0.149 兼容修复族：存量配置不再让 Codex 拒绝启动
+
+一族让 Codex 0.149 拒绝加载的配置形态——用户侧表现为「CC Switch 显示切换成功，Codex 却起不来」——现在在每次供应商切换与接管投影时自动修复。具体包括：早期接管投影写下的 `[model_providers.openai]` / `.ollama` / `.lmstudio` 遗留表（覆盖保留 id 会导致校验失败）被无损改名为 CC Switch 自有 id 并归一为可加载形状；没有 `name` 的 provider 表被回填（0.149 会因任何一张缺名表拒绝整份配置——Bedrock 表刻意保持无名，命名会破坏其内置合并）；携带可用密钥的旧式顶层 `openai_base_url` 路由被迁移成正规的自定义 provider 表（无密钥的这类路由会被切换时的安全闸拒绝）；新的写前预检对 0.149 无法加载的字段组合点名拒绝，而不是写出去当作「切换成功」。接管路由指向内置 `openai` provider 的卡改用官方支持的顶层字段而不是制造保留表，指向 `ollama` / `lmstudio` 的卡接管时显式报错。保留 id 清单与上游完全一致（大小写敏感；补入 `amazon-bedrock-runtime`，旧的 `oss` / `ollama-chat` 按普通自定义 provider 对待——它们的密钥终于能到达自己的表），内联的 `model_providers` 表也能接到注入的令牌，而不是留下一个死的顶层字段。
+
+### 被拒绝的切换不再腐坏被拒的那张卡
+
+live 写入校验现在作为预检、在当前供应商指针移动之前执行。此前写入层的拒绝发生在 `current` 已提交之后——下一次切换会把旧的 live 配置回填进这张被拒供应商的已存设置。
+
+### 供应商编辑必达 live 配置文件
+
+崩溃或恢复失败残留的接管备份行，会让活跃供应商的保存（Claude Desktop 除外）走上接管路径——只更新数据库与备份行，真正的配置文件无限期保持旧端点旧密钥。所有权现在由单一谓词裁定，要求接管的实际证据（live 文件中有占位符，或代理已启用且运行中且有备份行，或切换过程持有 per-app 锁且有备份行）；过期的备份行被刷新为与所编辑供应商一致，而不是劫持写入。统一供应商保存现在还会把每个生成的子配置重新投影到以它为活跃供应商的应用的 live 配置，逐应用报出失败名称而不是一律报成功。（[#6779](https://github.com/farion1231/cc-switch/pull/6779)）
+
+### Codex 编辑框不再显示另一张卡的密钥
+
+开启官方登录保留时，`auth.json` 是一个没有供应商身份的共享槽位，而编辑框播种表单时曾优先读它——编辑活跃的 Codex 供应商可能显示、并在保存时固化另一张卡遗留的密钥，让共享同一 Base URL 的卡密钥互相趋同（表现为「model not found」）。编辑框现在从 `config.toml` 里该供应商自己的 bearer token 重建密钥；官方类与纯 OAuth 供应商不受影响，而 `config.toml` 里没有自有 bearer token 的卡——旧版或手工维护的形态，本版起每次第三方切换都会写入——保持原有行为、继续读取 live `auth.json`（含手工修改）。（[#6534](https://github.com/farion1231/cc-switch/pull/6534)，修复 [#6414](https://github.com/farion1231/cc-switch/issues/6414)）
+
+### 恢复不再清空非受管的 prompt 文件
+
+WebDAV/S3 下载或备份导入时，若快照里某应用没有任何已启用的 prompt，该应用的 live prompt 文件（`CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `SOUL.md`）会被截断为空——摧毁从未进入同步载荷的本地手写内容。这样的恢复现在完全不碰该文件；从提示词面板里禁用最后一条 prompt 仍会照旧清空它。（[#6810](https://github.com/farion1231/cc-switch/pull/6810)，修复 [#6778](https://github.com/farion1231/cc-switch/issues/6778)）
+
+### 恢复界面的退出按钮真的能退出了
+
+`process:allow-exit` 权限缺失，v3.20.0 上「数据库版本过新」恢复界面的退出按钮、以及配置加载失败后的退出调用都被 IPC 层静默拒绝：退出按钮毫无反应（关闭窗口仍可退出），配置加载失败后应用径直进入正常界面而不是按设计退出。该问题由 @SaladDay 在 [#6567](https://github.com/farion1231/cc-switch/pull/6567) 更早独立发现并率先修复。
+
+### Claude 会话记账正确性三修
+
+随增量扫描器落地的三个数据准确性修复，均针对 Claude 会话日志路径。写到一半的日志行曾被旧的行号游标永久跳过（未完成的尾部推进了游标，补全后的消息再也不会被导入）——字节游标只在完整行之后提交，该消息下一轮即被拾取。被外部截断或改写的会话文件**从不重放**：重新导入明细行已被 30 天汇总清理的条目会让总数永久虚高，因此游标钉在新的文件末尾，被跳过的范围报告进同步结果的错误列表而不是静默丢弃（截断由游标越界发现，同尺寸改写由游标前字节的指纹发现）。文件中途的读取错误现在保留已提交的进度、下一轮从原处续读并上报，而不是返回一次干净的成功；游标预取失败会中止本轮，而不是表现得像首次扫描、把历史重复导入一遍。
+
+---
+
+## 性能
+
+### Claude 会话日志：字节游标增量扫描
+
+每轮扫描现在直接定位到上次提交的字节偏移、只读新追加的部分，而不是把变更过的文件从头读到尾——按改动自带的基准测试，12 MB 的活跃会话文件从整读解析 6.04 秒降到增量读取 9.3 毫秒。Claude、Gemini、OpenCode、Grok Build 与 Pi 的逐文件游标改为每个导入器每轮一次整表预取，而不是逐文件查询；Claude 路径上每个文件的导入与游标推进在同一事务中提交。1,017 个会话文件（409 MB）的冻结快照回放产出与旧扫描器逐位一致的汇总。需要一次 schema 迁移（v17 → v18），新增两个可空列——字节游标与尾部指纹；既有的行号游标在首轮扫描时就地转换，不重复导入任何内容。
+
+### Pi 会话去重走上身份索引
+
+合并的去重查询（跨两个身份列的 OR）只能约束数据源前缀，每条解析记录都要扫过账本里整个 Pi 区段——Pi 导入随用量历史增长越来越慢。现拆分为可走索引的点查询、结果完全一致，导入耗时不再随历史规模退化。（[#6667](https://github.com/farion1231/cc-switch/pull/6667)）
+
+---
+
+## 升级提醒
+
+### 本版包含数据库迁移，降级需还原备份
+
+schema 从 v17 迁移到 v18（会话扫描游标表新增字节游标与尾部指纹两列），迁移前自动创建备份。本版运行过一次后，旧版 CC Switch 会拒绝打开数据库——降级需还原该备份。旧的半行缺陷已漏掉的用量条目不做追溯找回——重放它们与重复导入已汇总的历史无法区分。
+
+### Codex OAuth 存量账号需要重新登录一次
+
+本版之前添加的每个托管 ChatGPT（Codex OAuth）账号都处于隔离状态，直到你在认证中心该账号行上点击「重新登录」——老记录以 ChatGPT workspace ID 为账号主键、没有单独记录的用户身份，普通的令牌刷新无法证明老记录属于哪个用户。供应商绑定会被保留，重新登录就地更新账号。请务必用账号行上的「重新登录」按钮：通过「添加账号」再登一次只会新建第二条记录（登录不再按 workspace 合并），老记录——以及绑定它的供应商——依然处于隔离状态。（[#6780](https://github.com/farion1231/cc-switch/pull/6780)）
+
+### Codex 0.48 以前的版本失去第三方鉴权
+
+config-only 切换写入的 provider 表令牌字段，0.48 以前的 Codex 从不读取。还在用旧版 Codex 的用户请升级 Codex。
+
+### 保留开关关闭时，切换第三方会删除 auth.json
+
+「非接管切换时保留官方登录」开关**关闭（默认）**时，切换到第三方 Codex 供应商现在会**删除** `auth.json`，而不是用 API 密钥覆盖它。要找回 ChatGPT 登录：切换到绑定了认证中心账号的官方供应商即可（登录会从托管账号完整写回）；跟随 Codex CLI 自身登录的未绑定官方卡则需要跑一次 `codex login`。想让官方登录跨第三方切换存活，把开关打开即可。
+
+### 部分以前「能用」的 Codex 卡现在会在切换时被拒绝
+
+配置为空的第三方卡（没有表可以承载密钥），以及依赖 `requires_openai_auth = true` 或裸 `openai_base_url` 路由去借用官方登录的无密钥卡，现在都会被点名拒绝。给这类卡补上正规的 `[model_providers.<id>]` 条目或 API 密钥即可。
+
+### 存量 Codex 配置会在下次写入 live 时按 0.149 需要被重写
+
+带可用密钥的旧式 `openai_base_url` 路由变成 `[model_providers.cc-switch]` 表、占用保留 id 的遗留表改名为 CC Switch 自有 id、缺失的 `name` 字段被回填；活跃带密钥第三方表上的 `requires_openai_auth` 在每次切换时按保留开关覆盖——你在该表上手工设置的值不会在切换后存活。
+
+### 截断或被外部改写的 Claude 会话日志将被永久跳过（设计使然）
+
+被改写的范围不重放（重放会与已清理的汇总重复计数），跳过的情况会报告在同步结果的错误列表里。
+
+### #6534 修复前已经串染的密钥不会自动修复
+
+如果共享同一 Base URL 的 Codex 供应商已经趋同到同一个 key，请在每张受影响的卡上重新填一次正确的密钥。
+
+### 恢复行为变化（#6810）
+
+恢复一份某应用没有任何已启用 prompt 的快照，现在会保留该应用的 live prompt 文件——客户端继续加载旧内容，即使提示词面板显示全部禁用。想清空它，在面板里启用再禁用一条 prompt（或自行编辑文件）。
+
+### 统一供应商保存现在可能明确报错
+
+若某应用的活跃供应商是生成的子配置、而其 live 配置文件写入失败，保存会报出该应用名称；数据库记录仍已保存——重试同步或重新切换一次该应用的供应商即可。
+
+### TeamoRouter 存量供应商保持 `api.teamorouter.com`
+
+从预设重新添加、或手动修改 Base URL，即可迁到 `.cn`。
+
+### OpenCode Go 用量查询只对本版之后新增的供应商自动启用
+
+存量卡请打开其用量脚本设置，选择 Token Plan 模板 → OpenCode Go 一次。
+
+---
+
+## 风险提示
+
+### 沿用的提示
+
+**xAI Grok OAuth 登录**：复用官方 Grok CLI 的公开 OAuth 客户端身份，使用可能导致账号被限制或封禁——详见 [v3.18.0 release notes](v3.18.0-zh.md#风险提示)。
+
+**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
+
+**SuperGrok 配额查询**：供应商卡片的配额展示依赖 grok.com 的非公开计费端点，xAI 调整接口后可能失效——详见 [v3.19.0 release notes](v3.19.0-zh.md#风险提示)。
+
+**第三方供应商路由**：通过 CC Switch 本地代理把 Codex、Claude Desktop 或 Grok Build 的请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
+
+用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
+
+---
+
+## 致谢
+
+本版 26 个提交里有 8 个来自 5 位外部贡献者。
+
+### 代码贡献
+
+- 感谢 @SaladDay：workspace 账号隔离整条主线（[#6780](https://github.com/farion1231/cc-switch/pull/6780)）、JWT 身份解析对齐（[#6831](https://github.com/farion1231/cc-switch/pull/6831)）与 Pi 会话去重索引（[#6667](https://github.com/farion1231/cc-switch/pull/6667)）；退出按钮的权限缺失也是他在 [#6567](https://github.com/farion1231/cc-switch/pull/6567) 更早独立发现并率先修复的。
+- 感谢 @YUZHEthefool：供应商编辑必达 live 配置（[#6779](https://github.com/farion1231/cc-switch/pull/6779)，与 @BingZi-233 协作）与 Codex 编辑框密钥串染修复（[#6534](https://github.com/farion1231/cc-switch/pull/6534)）——「修复」章节里两条数据正确性硬修复尽出于此。
+- 感谢 @SailingLoong：恢复不再清空非受管 prompt 文件（[#6810](https://github.com/farion1231/cc-switch/pull/6810)）。
+- 感谢 @yovinchen：Otty 终端支持（[#6620](https://github.com/farion1231/cc-switch/pull/6620)）。
+- 感谢 @ISuuuu：WSL2 契约测试改走预编译产物（[#6472](https://github.com/farion1231/cc-switch/pull/6472)）。
+
+### 问题反馈
+
+- 感谢 @hlwhl 在 [#6744](https://github.com/farion1231/cc-switch/issues/6744) 对 Codex 0.149 凭据继承变化的精确报告——直接框定了本版最大主线的方向，并率先提出了修复 PR（[#6746](https://github.com/farion1231/cc-switch/pull/6746)）。
+- 感谢 Team workspace 账号互覆问题的各位报告者：@cp7553479（[#2245](https://github.com/farion1231/cc-switch/issues/2245)）、@Smilenize（[#5885](https://github.com/farion1231/cc-switch/issues/5885)）、@yingjiezhao0820（[#6688](https://github.com/farion1231/cc-switch/issues/6688)）与 @buqi759（[#6738](https://github.com/farion1231/cc-switch/issues/6738)）。
+- 感谢密钥串染家族的报告者：@Joaging（[#6414](https://github.com/farion1231/cc-switch/issues/6414)）、@KawaiiSh1zuku（[#6594](https://github.com/farion1231/cc-switch/issues/6594)）与 @Michael-py001（[#6827](https://github.com/farion1231/cc-switch/issues/6827)）。
+- 感谢 @gyzerocc 报告 WebDAV 恢复清空 AGENTS.md（[#6778](https://github.com/farion1231/cc-switch/issues/6778)）——精确指出了触发条件。
+
+---
+
+## 下载与安装
+
+访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本，或从官网 [ccswitch.io](https://ccswitch.io) 获取（下载经 Cloudflare 边缘节点分发，不依赖 GitHub 可达）。
+
+### 系统要求
+
+| 系统    | 最低版本                   | 架构                                |
+| ------- | -------------------------- | ----------------------------------- |
+| Windows | Windows 10 及以上          | x64 / ARM64                         |
+| macOS   | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | 见下表                     | x64 / ARM64                         |
+
+### Windows
+
+| 文件                                     | 说明                                |
+| ---------------------------------------- | ----------------------------------- |
+| `CC-Switch-v3.20.1-Windows.msi`          | **推荐** - MSI 安装包，支持自动更新 |
+| `CC-Switch-v3.20.1-Windows-Portable.zip` | 便携版，解压即用，不写入注册表      |
+
+Windows ARM64 设备请选择文件名中带 `arm64` 标识的对应制品。
+
+### macOS
+
+| 文件                             | 说明                                          |
+| -------------------------------- | --------------------------------------------- |
+| `CC-Switch-v3.20.1-macOS.dmg`    | **推荐** - DMG 安装包，拖入 Applications 即可 |
+| `CC-Switch-v3.20.1-macOS.zip`    | 解压后拖入 Applications，Universal Binary     |
+| `CC-Switch-v3.20.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.20.1-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.20.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`              |