feat(proxy): extend tool-result media handling to all conversion bridges

Generalize the Codex Responses-to-Chat tool media mechanism from 6c9d444c to the remaining protocol bridges, so image-bearing tool results are never tokenized as base64 text on any conversion path: - Claude-to-Chat: tool_result images become native image_url parts, batched into one synthetic user message after the tool message batch. - Claude-to-Responses: JSON-string, MCP, and nested variants are restored as native input_image parts inside function_call_output. - Codex/GrokBuild-to-Anthropic: non-standard tool images are restored as Anthropic image blocks (case-insensitive data:/http prefix parsing). - Claude-to-Gemini: Gemini 3 uses multimodal functionResponse.parts; older models get inlineData parts in the same user turn. The new InlineImagesOnly scope keeps remote URLs and malformed data URLs in the legacy text form instead of emitting fileData the API would reject. Shared changes in tool_media: - Centralize the plan/queue/flush helpers used by both Chat bridges. - strip_and_clamp_media_from_tool_value clamps residual base64 inside parsed JSON strings at any nesting depth before re-serialization. - Emitted Chat parts no longer carry cache_control or prompt_cache_breakpoint, preserving the strip-all-cache_control contract that strict upstreams (GLM/Qwen) depend on. - Media detection now requires full convertibility, keeping detection and extraction symmetric by construction. The media sanitizer detects and strips the new shapes symmetrically (Chat string tool results, Anthropic string tool results, Gemini inlineData/fileData and functionResponse.parts); the legacy typed-block replacement runs first so replacement stays a superset of detection and cache_control survives on replaced Anthropic blocks. No-media tool outputs keep byte-identical legacy representations on all bridges to protect prompt-cache prefixes.
fix(proxy): move Codex tool-result media out of stringified tool text
2026-07-24 21:30:17 +08:00 · 2026-07-24 12:12:22 +08:00 · 2026-07-24 10:16:57 +08:00 · 2026-07-23 17:00:09 +08:00 · 2026-07-23 17:00:03 +08:00 · 2026-07-23 16:59:41 +08:00
599 changed files with 118681 additions and 16225 deletions
@@ -0,0 +1,14 @@
+# Code owners for cc-switch
+#
+# Branch protection on `main` has "Require review from Code Owners" enabled.
+# With this file present, a PR cannot merge to `main` without an approval from
+# the owner below. This closes the gap where two collaborators could approve
+# each other's malicious PRs (a single non-owner approval is no longer enough).
+
+# Global fallback: every PR needs owner approval before merging to main.
+*                 @farion1231
+
+# Most sensitive paths — CI/signing/release and the Rust backend. Listed
+# explicitly so they stay locked even if the global rule above is relaxed later.
+/.github/         @farion1231
+/src-tauri/       @farion1231
@@ -0,0 +1,74 @@
+# Configuration for actions/labeler v5
+# Automatically labels PRs based on changed file paths
+
+frontend:
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/**"
+          - "index.html"
+          - "vite.config.ts"
+          - "vitest.config.ts"
+          - "tailwind.config.cjs"
+          - "postcss.config.cjs"
+          - "tsconfig.json"
+          - "tsconfig.node.json"
+          - "components.json"
+          - "tests/**"
+
+backend:
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src-tauri/**"
+
+i18n:
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/locales/**"
+
+actions:
+  - changed-files:
+      - any-glob-to-any-file:
+          - ".github/**"
+
+dependencies:
+  - changed-files:
+      - any-glob-to-any-file:
+          - "package.json"
+          - "pnpm-lock.yaml"
+          - "pnpm-workspace.yaml"
+          - "src-tauri/Cargo.toml"
+          - "src-tauri/Cargo.lock"
+
+documentation:
+  - changed-files:
+      - any-glob-to-any-file:
+          - "*.md"
+          - "docs/**"
+          - "LICENSE"
+
+mcp:
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/components/mcp/**"
+          - "src/lib/api/mcp.ts"
+          - "src-tauri/src/mcp/**"
+          - "src-tauri/src/claude_mcp.rs"
+          - "src-tauri/src/gemini_mcp.rs"
+          - "src-tauri/src/commands/mcp.rs"
+
+skills:
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/components/skills/**"
+          - "src/lib/api/skills.ts"
+          - "src-tauri/src/commands/skill.rs"
+          - "src-tauri/src/services/skill.rs"
+          - "src-tauri/src/database/dao/skills.rs"
+
+proxy:
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/components/proxy/**"
+          - "src/lib/api/proxy.ts"
+          - "src-tauri/src/proxy/**"
+          - "src-tauri/src/commands/proxy.rs"
@@ -55,7 +55,11 @@ jobs:

  backend:
    name: Backend Checks
-    runs-on: ubuntu-22.04
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, windows-latest, macos-latest]
    steps:
      - name: Checkout
        uses: actions/checkout@v6
@@ -66,6 +70,7 @@ jobs:
          components: rustfmt, clippy

      - name: Install Linux system deps
+        if: runner.os == 'Linux'
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
@@ -87,6 +92,7 @@ jobs:
          restore-keys: ${{ runner.os }}-cargo-

      - name: Create frontend dist placeholder
+        shell: bash
        run: mkdir -p dist

      - name: Check Rust formatting
@@ -0,0 +1,17 @@
+name: Label PRs
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/labeler@v5
+        with:
+          sync-labels: true
@@ -15,10 +15,14 @@ concurrency:
 jobs:
  release:
    runs-on: ${{ matrix.os }}
+    environment: release
    strategy:
+      fail-fast: false
      matrix:
        include:
          - os: windows-2022
+          - os: windows-11-arm
+            arch: arm64
          - os: ubuntu-22.04
          - os: ubuntu-22.04-arm
            arch: arm64
@@ -36,6 +40,11 @@ jobs:
      - name: Setup Rust
        uses: dtolnay/rust-toolchain@stable

+      - name: Add Windows ARM64 target
+        if: runner.os == 'Windows' && matrix.arch == 'arm64'
+        shell: pwsh
+        run: rustup target add aarch64-pc-windows-msvc
+
      - name: Add macOS targets
        if: runner.os == 'macOS'
        run: |
@@ -74,23 +83,50 @@ jobs:
            || sudo apt-get install -y --no-install-recommends libsoup2.4-dev

      - name: Setup pnpm
+        if: runner.os != 'Windows' || matrix.arch != 'arm64'
        uses: pnpm/action-setup@v6
        with:
          version: 10.12.3
          run_install: false

+      - name: Setup pnpm (Windows ARM64)
+        if: runner.os == 'Windows' && matrix.arch == 'arm64'
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+          corepack enable
+          corepack prepare pnpm@10.12.3 --activate
+          node --version
+          pnpm --version
+
      - name: Get pnpm store directory
+        if: runner.os != 'Windows' || matrix.arch != 'arm64'
        id: pnpm-store
        shell: bash
        run: echo "path=$(pnpm store path --silent)" >> $GITHUB_OUTPUT

      - name: Setup pnpm cache
+        if: runner.os != 'Windows' || matrix.arch != 'arm64'
        uses: actions/cache@v5
        with:
          path: ${{ steps.pnpm-store.outputs.path }}
          key: ${{ runner.os }}-${{ runner.arch }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: ${{ runner.os }}-${{ runner.arch }}-pnpm-store-

+      - name: Setup LLVM for Windows ARM64
+        if: runner.os == 'Windows' && matrix.arch == 'arm64'
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = 'Stop'
+          $llvmRoot = 'C:\Program Files\LLVM'
+          if (-not (Test-Path $llvmRoot)) {
+            throw "LLVM not found at $llvmRoot"
+          }
+          $llvmBin = Join-Path $llvmRoot 'bin'
+          "LIBCLANG_PATH=$llvmBin" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          "CLANG_PATH=$(Join-Path $llvmBin 'clang.exe')" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
+          $llvmBin | Out-File -FilePath $env:GITHUB_PATH -Append -Encoding utf8
+
      - name: Install frontend deps
        run: pnpm install --frozen-lockfile

@@ -223,7 +259,16 @@ jobs:

      - name: Build Tauri App (Windows)
        if: runner.os == 'Windows'
-        run: pnpm tauri build
+        shell: pwsh
+        env:
+          WINDOWS_RELEASE_ARCH: ${{ matrix.arch || 'x86_64' }}
+        run: |
+          $ErrorActionPreference = 'Stop'
+          if ($env:WINDOWS_RELEASE_ARCH -eq 'arm64') {
+            pnpm tauri build --target aarch64-pc-windows-msvc --bundles msi
+          } else {
+            pnpm tauri build
+          }

      - name: Build Tauri App (Linux)
        if: runner.os == 'Linux'
@@ -394,50 +439,75 @@ jobs:
      - name: Prepare Windows Assets
        if: runner.os == 'Windows'
        shell: pwsh
+        env:
+          WINDOWS_RELEASE_ARCH: ${{ matrix.arch || 'x86_64' }}
        run: |
          $ErrorActionPreference = 'Stop'
          New-Item -ItemType Directory -Force -Path release-assets | Out-Null
          $VERSION = $env:GITHUB_REF_NAME  # e.g., v3.5.0
+          $isArm64 = $env:WINDOWS_RELEASE_ARCH -eq 'arm64'
+          $targetRoot = if ($isArm64) { 'src-tauri/target/aarch64-pc-windows-msvc/release' } else { 'src-tauri/target/release' }
+          $assetSuffix = if ($isArm64) { '-arm64' } else { '' }
+
          # 仅打包 MSI 安装器 + .sig（用于 Updater）
-          $msi = Get-ChildItem -Path 'src-tauri/target/release/bundle/msi' -Recurse -Include *.msi -ErrorAction SilentlyContinue | Select-Object -First 1
+          $msi = Get-ChildItem -Path (Join-Path $targetRoot 'bundle/msi') -Recurse -Include *.msi -ErrorAction SilentlyContinue | Select-Object -First 1
          if ($null -eq $msi) {
            # 兜底：全局搜索 .msi
-            $msi = Get-ChildItem -Path 'src-tauri/target/release/bundle' -Recurse -Include *.msi -ErrorAction SilentlyContinue | Select-Object -First 1
+            $msi = Get-ChildItem -Path (Join-Path $targetRoot 'bundle') -Recurse -Include *.msi -ErrorAction SilentlyContinue | Select-Object -First 1
          }
          if ($null -ne $msi) {
-            $dest = "CC-Switch-$VERSION-Windows.msi"
+            $dest = "CC-Switch-$VERSION-Windows$assetSuffix.msi"
            Copy-Item $msi.FullName (Join-Path release-assets $dest)
            Write-Host "Installer copied: $dest"
            $sigPath = "$($msi.FullName).sig"
            if (Test-Path $sigPath) {
              Copy-Item $sigPath (Join-Path release-assets ("$dest.sig"))
              Write-Host "Signature copied: $dest.sig"
+            } elseif ($isArm64) {
+              throw "Signature not found for $($msi.Name)"
            } else {
              Write-Warning "Signature not found for $($msi.Name)"
            }
+          } elseif ($isArm64) {
+            throw 'No Windows ARM64 MSI installer found'
          } else {
            Write-Warning 'No Windows MSI installer found'
          }
+
          # 绿色版（portable）：仅可执行文件打 zip（不参与 Updater）
-          $exeCandidates = @(
-            'src-tauri/target/release/cc-switch.exe',
-            'src-tauri/target/x86_64-pc-windows-msvc/release/cc-switch.exe'
-          )
+          $exeCandidates = if ($isArm64) {
+            @('src-tauri/target/aarch64-pc-windows-msvc/release/cc-switch.exe')
+          } else {
+            @(
+              'src-tauri/target/release/cc-switch.exe',
+              'src-tauri/target/x86_64-pc-windows-msvc/release/cc-switch.exe'
+            )
+          }
          $exePath = $exeCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1
          if ($null -ne $exePath) {
            $portableDir = 'release-assets/CC-Switch-Portable'
            New-Item -ItemType Directory -Force -Path $portableDir | Out-Null
            Copy-Item $exePath $portableDir
            $portableIniPath = Join-Path $portableDir 'portable.ini'
-            $portableContent = @(
-              '# CC Switch portable build marker',
-              'portable=true'
-            )
+            $portableContent = if ($isArm64) {
+              @(
+                '# CC Switch portable ARM64 build marker',
+                'portable=true',
+                'arch=arm64'
+              )
+            } else {
+              @(
+                '# CC Switch portable build marker',
+                'portable=true'
+              )
+            }
            $portableContent | Set-Content -Path $portableIniPath -Encoding UTF8
-            $portableZip = "release-assets/CC-Switch-$VERSION-Windows-Portable.zip"
+            $portableZip = "release-assets/CC-Switch-$VERSION-Windows$assetSuffix-Portable.zip"
            Compress-Archive -Path "$portableDir/*" -DestinationPath $portableZip -Force
            Remove-Item -Recurse -Force $portableDir
-            Write-Host "Windows portable zip created: CC-Switch-$VERSION-Windows-Portable.zip"
+            Write-Host "Windows portable zip created: CC-Switch-$VERSION-Windows$assetSuffix-Portable.zip"
+          } elseif ($isArm64) {
+            throw 'Portable ARM64 exe not found'
          } else {
            Write-Warning 'Portable exe not found'
          }
@@ -550,7 +620,8 @@ jobs:
            ### 下载

            - **macOS**: `CC-Switch-${{ github.ref_name }}-macOS.dmg`（推荐）或 `CC-Switch-${{ github.ref_name }}-macOS.zip`（解压即用）
-            - **Windows**: `CC-Switch-${{ github.ref_name }}-Windows.msi`（安装版）或 `CC-Switch-${{ github.ref_name }}-Windows-Portable.zip`（绿色版）
+            - **Windows (x86_64)**: `CC-Switch-${{ github.ref_name }}-Windows.msi`（安装版）或 `CC-Switch-${{ github.ref_name }}-Windows-Portable.zip`（绿色版）
+            - **Windows (ARM64)**: `CC-Switch-${{ github.ref_name }}-Windows-arm64.msi`（安装版）或 `CC-Switch-${{ github.ref_name }}-Windows-arm64-Portable.zip`（绿色版）
            - **Linux (x86_64)**: `CC-Switch-${{ github.ref_name }}-Linux-x86_64.AppImage` / `.deb` / `.rpm`
            - **Linux (ARM64)**: `CC-Switch-${{ github.ref_name }}-Linux-arm64.AppImage` / `.deb` / `.rpm`

@@ -594,7 +665,8 @@ jobs:
          base_url="https://github.com/$REPO/releases/download/$TAG"
          # 初始化空平台映射
          mac_url=""; mac_sig=""
-          win_url=""; win_sig=""
+          win_x64_url=""; win_x64_sig=""
+          win_arm64_url=""; win_arm64_sig=""
          linux_x64_url=""; linux_x64_sig=""
          linux_arm64_url=""; linux_arm64_sig=""
          shopt -s nullglob
@@ -607,12 +679,14 @@ jobs:
              *.tar.gz)
                # 视为 macOS updater artifact
                mac_url="$url"; mac_sig="$sig_content";;
+              *-Windows-arm64.msi)
+                win_arm64_url="$url"; win_arm64_sig="$sig_content";;
+              *-Windows.msi)
+                win_x64_url="$url"; win_x64_sig="$sig_content";;
              *-Linux-arm64.AppImage|*-Linux-arm64.appimage)
                linux_arm64_url="$url"; linux_arm64_sig="$sig_content";;
              *-Linux-x86_64.AppImage|*-Linux-x86_64.appimage)
                linux_x64_url="$url"; linux_x64_sig="$sig_content";;
-              *.msi|*.exe)
-                win_url="$url"; win_sig="$sig_content";;
            esac
          done
          # 构造 JSON（仅包含存在的目标）
@@ -632,9 +706,14 @@ jobs:
                first=0
              done
            fi
-            if [ -n "$win_url" ] && [ -n "$win_sig" ]; then
+            if [ -n "$win_x64_url" ] && [ -n "$win_x64_sig" ]; then
              [ $first -eq 0 ] && echo ','
-              echo "    \"windows-x86_64\": {\"signature\": \"$win_sig\", \"url\": \"$win_url\"}"
+              echo "    \"windows-x86_64\": {\"signature\": \"$win_x64_sig\", \"url\": \"$win_x64_url\"}"
+              first=0
+            fi
+            if [ -n "$win_arm64_url" ] && [ -n "$win_arm64_sig" ]; then
+              [ $first -eq 0 ] && echo ','
+              echo "    \"windows-aarch64\": {\"signature\": \"$win_arm64_sig\", \"url\": \"$win_arm64_url\"}"
              first=0
            fi
            if [ -n "$linux_x64_url" ] && [ -n "$linux_x64_sig" ]; then
@@ -8,7 +8,7 @@ release/
 *.tsbuildinfo
 .npmrc
 CLAUDE.md
-# AGENTS.md
+AGENTS.md
 GEMINI.md
 /.claude
 /.codex
@@ -28,5 +28,4 @@ flatpak-repo/
 copilot-api
 .history
 CODEBUDDY.md
-.github
 mainWindow.js
@@ -5,7 +5,490 @@ All notable changes to CC Switch will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

-## [Unreleased]
+## [3.18.0] - 2026-07-21
+
+Development since v3.17.0 is headlined by Grok Build joining as the eighth managed app — full provider switching, proxy takeover on its own route namespace, MCP/Skills/prompts sync, a curated preset list, and a Grok Official entry with official-login import (schema v14/v15) — and by xAI Grok account sign-in over an OAuth device flow for Claude Code, Claude Desktop, and Codex, including a strict-gateway compatibility layer that lets codex 0.142+ drive a Grok subscription over native Responses. A usage-accounting repair wave fixes the v3.17.0 fork/sub-agent double count with a one-time automatic rebuild (schema v16) plus a manual rebuild action, makes proxy usage logging idempotent, and stops the usage page freezing during large imports. Diagnostics mature: logs persist across restarts under size rotation, every log egress redacts secrets, and renderer crashes are captured to disk behind an error boundary with a reload screen. The Codex conversion layer gets four correctness fixes — tool schemas normalized to object type, reasoning attached forward across turns, streamed tool-call identity and order preserved, and parser-required catalog fields backfilled so codex 0.144.5+ starts — while managed-OAuth providers are now reliably flagged as routing-required and Windows provider switches no longer flash a console window or freeze the UI. Rounded out by Kimi K3 presets and pricing, corrected OpenClaw preset costs, SudoCode.us restored beside SudoCode.chat, sponsor-grouped preset ordering, first-run tray language detection, and permanently deletable default Skill repositories.
+
+**Stats**: 52 commits | 217 files changed | +21,452 insertions | -6,285 deletions
+
+### Added
+
+- **Grok Build Becomes the Eighth Managed App**: xAI's Grok CLI ("Grok Build", live config `~/.grok/config.toml`) is now a first-class managed app alongside Claude Code, Claude Desktop, Codex, Gemini CLI, OpenCode, OpenClaw, and Hermes: full provider add/import/switch (with a "restart Grok Build to apply" toast), app visibility and config-directory override settings, session manager and usage dashboard coverage, prompts with first-launch auto-import, deep-link (`ccswitch://`) provider import, and proxy takeover with its own `/grokbuild/v1/responses` route namespace, failover queue, and per-app proxy settings row — it reuses the Codex Responses forwarding path but never shares Codex's provider namespace or circuit-breaker state. MCP servers sync bidirectionally into Grok's `[mcp_servers]` table with the dialect differences handled (Grok infers transport from `command`/`url` and uses `headers`, so exports strip the explicit `type` and rename `http_headers` to `headers`, while imports infer the transport back), and Skills gain a Grok Build enable flag. Instead of borrowing the Codex preset list (an early cut leaked China-official direct providers and Codex default models into the Grok form), Grok Build ships its own curated preset module: aggregators and relays that actually carry Grok models, default model normalized to `grok-4.5` (`x-ai/grok-4.5` on namespaced routers), with no `cn_official` category. The tools panel installs Grok via the official xAI installer (`x.ai/cli/install.sh` / `install.ps1`) with npm `@xai-official/grok` as fallback; installs detected as native (launcher in `~/.grok/bin` or `$GROK_BIN_DIR`, real target under `~/.grok/downloads/grok-*`) self-update via `grok update`, while npm installs keep npm-anchored updates — the self-update is gated on positive native detection so it can never mutate a different install. Localized in all four locales (zh/en/ja/zh-TW). (#5453)
+- **Grok Official Provider With Official-Login Import**: A "Grok Official" entry lets Grok Build fall back to the CLI's own built-in xAI OAuth login: selecting it hides the connection fields and writes an empty `~/.grok/config.toml`, and CC Switch never stores or touches those credentials. Live-config reads, backups, and official-state writes now use syntax-only TOML validation, so an official-login (empty) config round-trips instead of failing; importing the live config while Grok is in official login state yields "Grok Official set as current" instead of an error, matching Codex behavior. Official-state detection is deliberately wired only into the manual import command — the startup auto-importer still rejects official-state configs, so a deleted Grok Official entry is never resurrected on launch. Proxy takeover of an official-login Grok config is skipped automatically and rejected with a clear message on the manual path, consistent with the existing ban on proxying official providers.
+- **Sign In With Your xAI Grok Account (OAuth) in Claude Code and Claude Desktop**: New "xAI (Grok)" presets for Claude Code and Claude Desktop authenticate with an OAuth device-code login instead of an API key, routing requests through the local proxy which transforms Anthropic Messages traffic to the xAI Responses API and injects the access token per request (default model `grok-4.5` on every role; the Claude Desktop preset maps the branded `claude-*` role IDs to `grok-4.5` upstream so it passes Desktop's third-party model validation). A new xAI section in Settings → OAuth Auth Center handles device-code login (user code with copy button, verification link, waiting/cancel/retry), multiple accounts with a default-account picker, per-account removal, and re-auth badges — accounts whose refresh token was revoked stay visible as "expired" instead of disappearing, and auth status refetches every 15 s so server-side revocation surfaces on its own. The integration is pinned closed: upstream is always `https://api.x.ai/v1/responses` in Responses format regardless of what the editable endpoint/format fields say, OAuth endpoints are resolved via OIDC discovery but validated to `auth.x.ai` over https only, refresh tokens live in `~/.cc-switch/xai_oauth_auth.json` (`0600` on Unix; access tokens are memory-only), and OAuth error bodies are never embedded in error messages or logs. `grok-4.5` is also seeded into the built-in pricing table ($2 input / $6 output / $0.50 cache-read per 1M tokens), fixing the $0 cost the dashboard would otherwise record; existing databases pick the row up automatically on next launch. Localized in all four locales (zh/en/ja/zh-TW). See the upgrade notes for the client-identity disclosure.
+- **xAI (Grok) Codex Presets: OAuth Managed and Native-Responses API Key**: Codex gains two ways to talk to xAI directly. The "xAI (Grok) OAuth" managed preset drives Codex against a Grok subscription through the local proxy — the form hides the key/endpoint/format fields and shows the account picker, "fetch models" uses the signed-in account, and the provider is pinned to native Responses with the base URL and per-request token enforced by the proxy (edited base URLs or formats are ignored, so the managed route cannot be redirected). Because codex 0.142+ emits ChatGPT-backend-private shapes that xAI's strict parser rejects (`type:"namespace"` tool declarations → 422, plus private fields like `prompt_cache_retention`, `safety_identifier`, `external_web_access`, the `additional_tools` carrier, and grok-4.5-unsupported sampling knobs), the OAuth route gets a compatibility layer on the native passthrough: namespace tools are flattened to top-level function tools (using the same sha256-truncated naming as the Chat path) and restored to namespaced form in both streaming and non-streaming responses, and unsupported fields are stripped — all deterministic field-removal/structural lifts, never semantic rewrites, so prompt-cache prefixes stay stable. The layer is gated exclusively on the xAI OAuth provider type: no other provider's traffic is touched, including the second new preset, a plain "xAI (Grok)" API-key preset (native Responses against `api.x.ai/v1` with a 500K-context `grok-4.5` catalog entry) that does not receive these xAI-specific compatibility transforms — API-key users on codex 0.142+ can still hit xAI's strict parser, and the OAuth preset is the fully-compatible path. xAI OAuth token failures are classified non-retryable so failover never silently moves a conversation onto a different Grok account.
+- **Renderer Crash Capture With On-Disk Reports and a Reload Screen**: A React error boundary now wraps the UI (including the database-recovery screen), so a renderer crash shows a "Something went wrong in the interface" card with a Reload button instead of a blank white window, and global `error`/`unhandledrejection` handlers persist renderer errors to disk via the new `log:default` capability — previously a JS crash left zero on-disk evidence. Everything logged from the frontend passes two redaction layers: a structured serializer that redacts by sensitive property name (normalized so `tokens`/`apiKeys`/`credentials` variants all match, hiding the entire value including nested objects) and by value shape (token prefixes, PEM headers, high-entropy opaque strings), then a single text egress (`redactFrontendLogText`) whose ordered regex chain covers URL query values and credentials, auth headers and schemes, and named secret containers even in double-encoded JSON. JSON that arrives as a string is re-parsed and redacted structurally, and oversized structured input is dropped entirely rather than truncated — a truncated JSON string would fall back to the weaker text regexes and could leak. The settings toggles were also relabeled to say what they actually control: "Application Diagnostic Logs" (cc-switch.log) versus the proxy's "Record Request Usage" (the stats database, which never was a text log). Localized in all four locales (zh/en/ja/zh-TW).
+- **"Rebuild Codex Usage" Maintenance Action**: The usage dashboard's maintenance section gains a "Rebuild Codex Usage" button that backs up the database, wipes only `codex_session`-sourced detail rows, their `_codex_session` daily rollups, and the Codex sync cursors, then re-imports every rollout file from scratch with the corrected parser — the recovery path for databases already inflated by the fork double-count bug below, and the retry path for deferred fork files whose parent log has since been restored. The manual rebuild fails hard when the pre-rebuild backup cannot be written (unlike the automatic migration variant, which only warns, since blocking startup on an unwritable backup directory would leave the app unable to launch after upgrade), holds the session-sync lock across the whole backup → reset → reimport sequence so the 60-second background sync cannot interleave with the wipe, and always sends exactly one frontend refresh notification on completion — including when the reimport returns zero rows or fails after the reset — so the dashboard never keeps showing pre-reset numbers (`finish_codex_rebuild` in `commands/usage.rs`, pinned by two regression tests). Cursor deletion matches rollout paths purely by shape (`rollout-{uuid}` filename under a `sessions`/`archived_sessions` segment), so cursors recorded under an old `CODEX_HOME` are still cleaned. Localized in all four locales (zh/en/ja/zh-TW).
+- **Session Import Observability: Deferred Files and Suspected Duplicates**: Session sync results now report `filesScanned`, `deferredFiles` — fork rollouts whose parent log is missing or whose parent markers conflict, held back without writing a cursor so a later sync or manual rebuild retries them, instead of being imported on a guess — and `suspectedDuplicates`, backed by a post-insert probe that checks each imported row for a pre-existing same-fingerprint row (via the `idx_request_logs_dedup_lookup_expr` expression index) and logs a warning per hit, so any future regression of the double-count bug announces itself in the logs instead of silently inflating totals.
+- **Kimi K3 in Presets and Built-In Pricing**: The Kimi open-platform presets for Codex, Hermes, OpenClaw, and OpenCode gain the Kimi K3 model (1M context window), appended after K2.7 Code so existing default-model behavior is unchanged, and the built-in pricing table gains `kimi-k3` at the official list price ($3 input / $15 output / $0.30 cache-read per 1M tokens) plus a bare `k3` alias — the Kimi For Coding subscription reports its model under the short id `k3`, which would otherwise match no pricing row (same precedent as the existing `hunyuan-hy3`/`hy3` pair). Existing databases pick both rows up automatically on next launch without touching user-edited pricing.
+- **SudoCode.us Restored Alongside SudoCode.chat**: The two unrelated companies sharing the "SudoCode" name are now separate presets: the sponsor is renamed "SudoCode.chat", and the legacy "SudoCode.us" (which an earlier release had replaced in place) returns with its original endpoints and models, its own icon, and a distinct Hermes slug so both can coexist in the additive `~/.hermes/config.yaml`. Counting the new Grok Build preset list, SudoCode.chat now ships in seven apps and SudoCode.us in all eight.
+
+### Changed
+
+- **Diagnostic Logs Persist Across Restarts, Are Size-Rotated, and Never Record Secrets**: `cc-switch.log` is no longer wiped on every startup — the log that explained a crash used to be gone by the time the app reopened — and instead rotates at 20 MB with 4 archives kept (~100 MB cap, versus a single 1 GB file before); `crash.log`, previously unbounded, rotates at 5 MB with 2 archives, with the size-check/rotate/append sequence under one lock so concurrent panics cannot lose an archive. Because persistent logs make verbatim secrets a real exposure (users attach these files to public issues), every backend log egress was scrubbed in the same change: upstream URLs are logged with userinfo, query, and fragment stripped (origin-only when no known secret is available to scrub, since a credential could be embedded in the path), request and response bodies are never logged — replaced by byte counts, a short hash, or a safe classification (`sse`/`html`/`json-like`/`binary-or-encoded`/…) that preserves the transform-debugging signal without the content — response headers go through an allowlist (unlisted headers log name-only), the exact secret values in use (API key, access token) are scrubbed out of any logged URL that carries them, and MCP custom-field values are omitted. The log plugin also registers earlier (so updater/startup failures are diagnosable), the persisted log level applies as soon as the database opens and fails closed to Info, and the "Enable Diagnostic Logs" switch now gates frontend-originated log writes too. Pre-upgrade log files are not retroactively scrubbed — see upgrade notes.
+- **Preset Picker Groups Sponsors and Alphabetizes the Rest**: The picker's default ordering now has four tiers — official first, then the prime partner, then sponsor presets (in the same order as the README sponsor table, which the preset files were physically reordered to match), then all remaining presets sorted alphabetically by display name instead of file order. An entry matching multiple tiers lands only in the earliest, so nothing is listed twice.
+- **Preset "Get API Key" Links Updated to Current Referral URLs**: The key-application links on the RunAPI, ClaudeCN, ZetaAPI, and APINebula presets now open each provider's current registration/referral page (ClaudeCN also moved domains, claudecn.top → claudecn.ai). Referral tags remain confined to these links and the README — website links and API endpoints stay untouched.
+
+### Fixed
+
+- **Codex Fork/Sub-Agent Rollouts No Longer Import Replayed Parent History**: Fixes the v3.17.0 usage inflation where forking a Codex task or spawning a sub-agent in copy mode re-counted the parent conversation's token history as new usage — reports showed single days jumping by billions of tokens, duplicated parent/child rows that were byte-identical, and empty forks carrying usage they never consumed. Fork and sub-agent rollout files begin by replaying the parent thread's history, and the previous parser located the takeover boundary heuristically (first `thread_settings_applied` event, object-shaped `subagent` source markers): the boundary landed too early when the parent's own settings changes appeared in the replay, and was missed entirely for the current string-shaped source format, importing the whole replayed parent history. The parser now identifies a fork only by explicit parent identity — `forked_from_id` on the child's `session_meta` or `source.subagent.thread_spawn.parent_thread_id`, with a conflict between the two deferring the file — anchors each thread's identity to the rollout filename UUID, loads the parent rollout's own pre-fork token-count sequence, and strips the child's replayed prefix by aligning token signatures against it, so replayed events only restore the cumulative baseline and are never inserted as rows. Sub-agent logs that carry no replayed history are now counted as live usage, fixing the opposite-direction undercount where real sub-agent consumption was skipped as suspected replay. (#5335, #5433, #5381)
+- **Proxy Usage Logging Is Now Idempotent With Stable Response-Scoped Keys**: When a terminal usage event carried no message id — the norm for Codex `/responses` traffic through the local proxy — the dedup key fell back to a random UUID, so every retry or replay of the same upstream response minted a fresh key and `INSERT OR REPLACE` stacked a new row each time; one reporter's database held the same usage combination 2,078 times. The parser now derives the key from the response envelope itself — the Codex `response.completed` event's `response.id` (`response.created` ids are discarded), Chat Completions `chatcmpl` ids, and the Gemini `responseId` — scoped as `session:{app_type}:{provider_id}:{id}` so the same response replayed against a different provider during failover still bills once per provider without cross-provider collisions (Claude keeps the bare `session:{id}` shape so proxy rows continue to converge with session-log imports). When no envelope id exists at all, the fallback is a deterministic SHA-256 over the response's usage semantics rather than a random UUID — an identical replay must collide into the same key for dedup to work — and the final database write is a guarded insert-if-absent within the dedup window instead of an unconditional REPLACE. (#5496)
+- **Usage Page No Longer Freezes During Large Session Imports**: Opening the usage page while a big import ran could lock up the UI: every inserted row fired a refresh notification, each notification made the frontend re-run all ~10 usage queries, and those queries contended with the importer for the single database connection while it parsed rollout files tens of megabytes large line by line — on duplicate-inflated databases the row storm compounded all three. Session sync now notifies the frontend once per completed sync pass instead of once per row, all session importers are serialized behind a single-flight lock (a manual "sync now" queues behind the running pass instead of racing it), the blocking parse work runs on a dedicated blocking thread so it no longer starves the async runtime driving the UI's commands, and the 60-second background tick skips missed runs instead of bursting to catch up.
+- **Codex 0.144.5+ No Longer Fails to Start on CC Switch-Generated Model Catalogs**: codex ≥ 0.144.5 parses external model catalogs strictly and rejects the whole file when an entry is missing `supports_reasoning_summaries` — so both the Codex CLI and desktop app failed to launch, and deleting the generated catalog didn't help because any provider save regenerated it the same way. The root cause is that CC Switch clones its catalog template from the machine-shared `models_cache.json`, whose field set is whatever the last-writing codex process produced — a coexisting older codex build kept rewriting the cache without the field the newer parser requires. Generated catalogs now backfill parser-required fields from the bundled static template, only when absent (dynamic values always win), and deliberately do not backfill optional capability fields whose "missing = parser default" semantics must survive.
+- **Windows: No More Console Flash or UI Freeze When Switching Providers**: Switching providers or toggling takeover on Windows flashed a transient console window and froze the UI for up to ~2 seconds. Three causes, three fixes: the `codex debug models --bundled` probe launches `codex.cmd` through `cmd.exe`, which in a GUI-subsystem app spawns its own console — the child process is now created with `CREATE_NO_WINDOW`; the model-catalog template was regenerated on every switch — it is now cached process-wide after the first successful load (failures stay retryable so a bad first probe cannot poison the cache), so the Codex CLI starts at most once per app run; and `switch_provider` was a synchronous command running on the main thread — it is now async with the real work on a blocking thread, still serialized by the per-app switch lock. The freeze fix benefits all platforms; the console-flash fix is Windows-specific.
+- **Codex Tool Schemas With Null, Missing, or Union Parameter Types Are Accepted by Strict Upstreams**: Built-in Codex tools such as `codex_app__automation_update` declare `parameters: null` (or `type: null`), which strict OpenAI-compatible upstreams like DeepSeek reject with a 400 for the entire request, killing tool-using sessions routed through the proxy. The Responses→Chat bridge now normalizes every tool's parameters to a `type:"object"` schema — null or missing parameters (including the nested-form missing case) become `{"type":"object","properties":{}}`, a non-object `type` (including `type: null`) is coerced to `"object"` in place, and top-level `oneOf` union schemas get a root `type:"object"` added while their branches are preserved untouched. The same object-type guarantee was extended to the Codex→Anthropic tool path's `input_schema`. Existing `properties`/`required` are never dropped. (#4706, #5315; issues #4705, #4783)
+- **Reasoning Models Keep Their Thinking Across Multi-Turn Codex Chat Conversations**: With a reasoning model (e.g. kimi-k2-thinking) behind the proxy's Responses→Chat bridge, multi-turn history mangled the thinking: each turn's `reasoning` item was glued onto the tail of the _previous_ assistant message, leaving the following assistant turn with no `reasoning_content` — models would visibly break off mid-conversation. Responses semantics place reasoning _before_ the message it belongs to, so the bridge now attaches reasoning forward to the assistant message or tool call that follows it; genuine trailing reasoning back-attaches only at the true tail (end of input, or a turn boundary such as an incoming user message — where it was previously silently discarded), appending to any embedded reasoning already present, and pending reasoning is always consumed at boundaries so it can never leak across a user turn into a later assistant message. (#5508)
+- **Streamed Parallel Tool Calls Keep Their IDs and Their Order**: Two bugs in the Chat→Responses streaming bridge corrupted parallel tool calls from upstreams that split identity across chunks: a continuation delta carrying an empty `id` overwrote the real `call_id` (the Codex client then saw `call_id:""` and couldn't match tool results to calls), and tool calls were emitted the moment they individually became ready, so a later index whose name arrived early could jump ahead of an earlier one — reordering parallel calls. Empty ids are now ignored, and emission goes through a consecutive-index gate that releases tool calls strictly in Chat `index` order, waiting on any not-yet-identified earlier index; no fake call id is ever synthesized mid-stream (only as a last resort at stream finalization, which also skips nameless calls defensively and still emits sparse indexes). (#5310)
+- **Managed-OAuth Providers Are Reliably Flagged as Needing Local Routing**: The "needs routing" badge and switch-time warning were derived from the provider's API format, which is the wrong signal for managed-OAuth providers (Copilot, Codex OAuth, xAI) whose credential is injected by the proxy regardless of upstream format — a managed provider on a native format got no warning and failed silently without takeover. Routing need is now decided by a single shared predicate: official providers never need routing, managed-OAuth providers always do, and format-based rules apply only to the remaining cases per app. The switch-time gate also checks the right readiness signal per app: per-app takeover for most apps (the old gate looked only at a global proxy-running flag, missing the case where the proxy runs but the current app is not taken over), while Claude Desktop keeps watching the proxy process itself — the backend's takeover status has no Claude Desktop field, so a uniform per-app gate would have left Desktop warning forever. Claude Desktop provider forms now force proxy mode and lock the model-mapping toggle for every managed-OAuth type, not just xAI. Localized in all four locales (zh/en/ja/zh-TW).
+- **Tool Updates Work When Node Lives in nvm/fnm/mise Under a GUI Launch**: Anchored npm update and repair commands invoked npm by absolute path, but npm's launcher resolves `node` via its `#!/usr/bin/env node` shebang against PATH — and a GUI-launched app inherits only the system PATH, not the user's version-manager directories, so updates silently failed for tools installed via nvm/fnm/mise. Every anchored npm invocation now prefixes PATH with npm's own sibling `bin` directory, so both npm and its shebang resolve to the same Node install; the Codex self-repair (uninstall + reinstall) path is covered too.
+- **Deleted Default Skill Repositories Stay Deleted**: Default Skill repositories were re-seeded on every startup by a "supplement missing defaults" pass, so a default repo the user deleted silently returned on the next launch. Seeding is now one-time per database, tracked by a settings flag; databases that already contain repositories at upgrade time get the flag set without any re-seeding, so existing selections are untouched. (#5356)
+- **First-Run Tray Language Follows the System Locale**: Before any language was chosen in settings, the tray menu was hardcoded to Simplified Chinese even on English/Japanese/Traditional-Chinese systems where the main UI correctly followed the OS locale — tray and UI disagreed until the user switched language once. The tray now derives its first-run language from the OS locale with the same precedence rules as the frontend (including `zh-TW`/`zh-HK`/`zh-Hant` → Traditional Chinese); an explicitly chosen language always wins, and unreadable locales fall back to Chinese as before. (#4355)
+- **Failed Live-Config Imports Show the Real Error and Refresh the List**: Every failed "import from live config" produced an empty error toast, because Tauri's `invoke` rejects with the backend's error _string_ while the handler read `.message` off it; the actual backend message is now shown (with a localized generic fallback), and the provider list is refreshed even on failure so side effects committed before the error are visible immediately.
+- **OpenClaw Preset Model Costs Corrected to Official List Prices**: Fifteen OpenClaw preset entries carried cost values in the wrong unit or unconverted currency — the `cost` field is USD per million tokens, but e.g. `glm-5.1` was listed at `0.001/0.001` (≈1000× undervalued, so its usage showed near-zero cost) while `deepseek-v4-pro` carried unconverted CNY values (overvalued). All entries now carry official list prices in $/M; subscription-plan and free-tier endpoints deliberately show list prices too, so plan users see the standard value of their usage. Providers created from these presets going forward get the corrected values; previously added providers keep the config they were created with.
+- **AiHubMix Icon on the Codex Preset**: The Codex app's AiHubMix preset was the only one missing its brand icon fields and rendered a generic icon; it now matches the other apps.
+- **Two Missing Locale Keys Backfilled in All Four Locales**: The Codex "needs routing because it uses Anthropic Messages format" toast rendered its reason fragment in Chinese inside an otherwise-localized sentence because `proxyReasonAnthropicMessages` existed in no locale file, and the provider-form key-status loading label had shipped only as a hardcoded default since April; both now exist in zh/en/ja/zh-TW.
+
+### Docs
+
+- **Codex + Claude Local Routing Guide (Three Languages)**: New guide in Chinese, English, and Japanese on pointing Codex at a Claude-family `/v1/messages` gateway via the native Anthropic Messages upstream format introduced in v3.17.0, with screenshots; the v3.17.0 release notes now link to it.
+- **Claude Code via Codex Providers Guide (Chinese)**: New Chinese guide on using Responses-speaking providers (a gateway API key, or a ChatGPT subscription's Codex service) from Claude Code: Claude Code keeps talking Anthropic Messages to the local `/v1/messages` route, and the proxy converts each request to the upstream's Responses protocol. With screenshots.
+- **README Sponsor Updates**: SubRouter added as a sponsor across the four README languages; the pinned Kimi sponsor copy refreshed to K3 with banners served from the Moonshot CDN; RunAPI benefit copy refreshed and sponsor rows reordered to match the in-app preset order.
+
+### Internal
+
+- **Backend CI Now Covers Linux, Windows, and macOS**: Backend checks previously ran only on Ubuntu, so Windows/macOS-gated code paths were never compiled or tested in CI — the matrix now spans all three platforms, with the platform-gated tests repaired to pass everywhere (TOML literal-string path escapes, stale anchored-update expectations, and skill tests honoring the test home-directory override). No shipped behavior changes. (#5138)
+
+### Upgrade notes
+
+- Upgrading from v3.17.0 runs three schema migrations (v13 → v16): v14 rebuilds the `proxy_config` table to admit Grok Build (existing per-app proxy settings are carried over and a `grokbuild` row is added), v15 adds Grok Build enablement columns to the MCP-server and Skills tables, and v16 triggers the Codex usage rebuild described next.
+- Schema v16 performs a one-time automatic rebuild of Codex session usage on first launch after upgrading: the database is backed up under `backups/`, `codex_session` data and cursors are reset, and the normal startup sync re-imports everything with the corrected parser. Expect seconds for typical data; the heaviest dataset measured (1,801 rollout files / 1.5 GB) took about 65 seconds. Later launches are incremental as before.
+- The rebuild recomputes usage from the rollout JSONL files, so history whose source log was already deleted cannot be reconstructed.
+- Fork files whose parent rollout is missing are deferred and reported instead of guessed; restoring the parent log and running “Rebuild Codex Usage” imports them later.
+- Historical proxy-source duplicate rows are permanently retained — the migration rebuilds only session-sourced data, and no cleanup pass for past proxy inflation exists; the idempotent logger prevents new duplicates from this point on.
+- The xAI Grok OAuth integration reuses the official Grok CLI's public OAuth client identity and scopes (`client_id b1a00492-073a-47ea-816f-4c329264a828`, scope including `grok-cli:access`) rather than a CC Switch-registered application. xAI may not support this use, and it could lead to account restriction or suspension — use at your own risk. The feature is entirely opt-in; nothing changes unless you add an xAI provider. On first login it creates `~/.cc-switch/xai_oauth_auth.json` (refresh tokens only, `0600` on Unix; access tokens are held in memory) and contacts `auth.x.ai` and `api.x.ai` through the configured outbound proxy, with no local callback port.
+- Diagnostic logs are no longer cleared at startup and now persist across restarts (up to ~100 MB of rotated runtime logs plus ~15 MB of crash logs). Log files written by earlier versions are not retroactively scrubbed and may contain API keys, tokens, or URLs with credentials — review pre-upgrade logs before sharing them publicly.
+- Installing or reinstalling Grok Build now prefers the official xAI installer, fetching `x.ai/cli/install.sh` (or `install.ps1` on Windows) at install time, with npm as fallback; existing npm installs keep updating via npm.
+- New built-in pricing rows (`grok-4.5`, `kimi-k3`, `k3`) are appended automatically on next launch via insert-if-absent; user-edited pricing rows are never overwritten.
+
+## [3.17.0] - 2026-07-13
+
+Development since v3.16.5 is headlined by project profiles — named snapshots of provider/MCP/Skills/prompt state, switchable per scope from a new header switcher or the tray (schema v12) — and a deep Codex push: official ChatGPT-subscription sessions can now route through the local proxy takeover with a corrected client identity, gpt-5.6 lands across context-window injection and Sol/Terra/Luna pricing with 1.25× cache-write rates, and a native Anthropic Messages upstream joins the Codex format options. A proxy-correctness wave makes the Responses↔Anthropic bridges fail closed and round-trip reasoning/tool results losslessly, strengthens prompt-cache breakpoint injection, and fixes cache-write accounting across historical token semantics (schema v13); a config.toml hardening batch stops deleted MCP servers from resurrecting, fails MCP sync closed on unparseable files, extends switch-time common-config autosync to Codex, and moves the common-config merge to backend toml_edit. Usage tooling gains Zhipu team-plan quota queries, Codex sub-agent and free-plan accounting, and transient-failure retry, while Kimi For Coding's 256K window finally takes effect — rounded out by a Codex default-model form field, renamed-session titles, OpenCode form and live-sync fixes, and preset updates (SudoCode sponsorship, LongCat-2.0, GPT-5.6 defaults, Hunyuan Hy3 pricing).
+
+**Stats**: 69 commits | 172 files changed | +21,067 insertions | -2,464 deletions
+
+### Added
+
+- **Project Profiles for One-Click, Snapshot-Based Config Switching**: You can now save the current provider, MCP, Skills, and prompt state as a named "project" and re-apply it in one click from a new header switcher or the tray Projects submenu, so moving between per-project setups no longer means toggling each dimension by hand; it covers Claude Code, Claude Desktop, and Codex (Claude Desktop's only cc-switch-managed dimension is its provider, so its snapshots capture just that and leave the other dimensions untouched on apply). Projects are global shared entities, but capture and switching are per scope — Claude Code, Claude Desktop, and Codex each keep their own `current_profile_id_<scope>` marker and only touch their own payload slots, so picking a project on the Codex tab never disturbs the Claude config (slots use `Option` to distinguish "never captured" from "captured empty", preventing cross-side accidental disable). Applying is best-effort: `ProfileService::apply` (in `services/profile.rs`) reuses the existing switch primitives — provider switch, then minimal MCP/Skills toggle diffs, then prompt enable — and any dangling reference or per-item failure becomes a warning instead of rolling back. Switching first autosaves the leaving project's current state for the active scope, so a project always holds the configuration you last left it in, which is why there is no manual "update snapshot from current state" button. Before applying, proxy takeover is unconditionally disabled per app in the scope, the frontend invalidates takeover status, and the proxy server is stopped when the switch leaves no takeovers active so Claude Desktop's local-route master toggle reads off. Backed by a new `profiles` table introduced by the v11→v12 schema migration, wired into `commands/profile.rs`, `database/dao/profiles.rs`, the tray, and `components/profiles/`, localized in all four locales (zh/en/ja/zh-TW), with integration tests covering roundtrip, dangling refs, bidirectional autosave, and proxy-takeover teardown.
+- **Setting to Show or Hide the Project Switcher on the Main Page**: The header project switcher can now be turned off from a new "Show project switcher" toggle under the Homepage Display section of Settings, for users who don't use projects and prefer a cleaner header. It defaults to on (`show_profile_switcher` / `showProfileSwitcher`) so existing users keep the current behavior, and disabling it only hides the header control on every tab — projects and the tray Projects submenu remain fully usable. Localized in all four locales.
+- **Route Codex Official ChatGPT Sessions Through Proxy Takeover**: CC Switch can now route a Codex session authenticated with a ChatGPT subscription (native OAuth or API-key login, no stored API key) through the local proxy, so official-account traffic gets the same proxy routing, format conversion, and usage accounting that third-party providers already receive. The built-in `codex-official` "OpenAI Official" seed is restored if it was deleted (idempotent `ensure_codex_official_provider` command wired into the add-provider flow) and is now selectable during takeover from the provider panel and tray, with the provider card badge reading "Official Account Routing" while routing and "Codex Sign-in" otherwise; only that fixed seed qualifies (`is_codex_official_provider` / `official_provider_supports_proxy_takeover`, mirrored in the frontend `supportsOfficialProxyTakeover`), so copied UUID-based official entries stay blocked and still show "No Routing Support". Instead of writing an `OPENAI_API_KEY = PROXY_MANAGED` placeholder into `auth.json`, the official route projects a dedicated `cc-switch-official` `model_provider` into `config.toml` with `requires_openai_auth = true`, `wire_api = "responses"`, `supports_websockets = false`, and `base_url` pointing at the local proxy (`apply_codex_official_proxy_route`), so Codex forwards its own ChatGPT authorization to the proxy's `/responses` endpoint and the `codex-official` row never stores a credential (its `auth` stays `{}`). The forwarder passes the client's `Authorization` header through unchanged to the fixed first-party endpoint (`CHATGPT_CODEX_BASE_URL`, now shared by the Codex and Claude adapters), rejects a missing header or a stale `PROXY_MANAGED` placeholder with an actionable error (finish the ChatGPT login / restart Codex or start a new session), and treats official `401`/`403` and auth errors as non-retryable so failover never silently moves the conversation to another account or pollutes the circuit breaker. The native login is never overwritten — takeover preserves OAuth or API-key material into the backup (falling back to live `auth.json` when the backup is missing), config transforms in `codex_config.rs`/`services/proxy.rs` now fail closed instead of swallowing errors, and stale managed placeholders left in other provider tables are cleaned; the `preserveCodexOfficialAuthOnSwitch` setting copy was updated to clarify that takeover routing always preserves the official login and the toggle now only governs direct (non-routing) third-party switches.
+- **GPT-5.6 Context Window for Claude Code Codex Takeover**: When Claude Code is routed to a ChatGPT Codex (Codex OAuth) backend via proxy takeover, CC Switch now injects `CLAUDE_CODE_MAX_CONTEXT_TOKENS` and `CLAUDE_CODE_AUTO_COMPACT_WINDOW` set to `372000` into the effective live `settings.json`, so Claude Code stops assuming its default 200K window for the unrecognized GPT model id and auto-compacts before the upstream rejects an oversized prompt. 372000 matches the ChatGPT Codex catalog window for gpt-5.6 — the catalog lists a ~353K effective budget, not the 1.05M API spec — and Claude Code's built-in output reserve and compact buffer then keep the actual compact trigger below that budget. The defaults are gated on every configured model env key (`ANTHROPIC_MODEL`, the haiku/sonnet/opus/fable defaults, and `CLAUDE_CODE_SUBAGENT_MODEL`) starting with `gpt-5.6`: gpt-5.5's upstream catalog oscillates between 272K and 372K and must not inherit them; any non-gpt-5.6 or mixed mapping is skipped (and any value a legacy shared snippet dragged in is stripped), while an explicit user value always wins. The Codex OAuth presets for both Claude Code and Claude Desktop bump their default routes to the gpt-5.6 family (haiku → `gpt-5.6-luna`, main/sonnet/opus → `gpt-5.6`), the custom Codex `config.toml` template default model moves to gpt-5.6, and the Claude Code preset ships both context env keys pinned at 372000 (see the corresponding Changed entry on preset-pinned context windows). On switch-away backfill the injected values are stripped as the mirror-inverse of the injection conditions so program defaults never harden into per-provider explicit values, and both keys are held out of the shared Claude common-config snippet (`services/provider/mod.rs` strip list plus a guard in `live.rs`) because context limits must follow the actual upstream model; six Rust integration tests cover injection, user overrides, legacy-snippet strip, non-gpt5.6 skip, and the backfill round-trip. (openai/codex#31860)
+- **GPT-5.6 Sol/Terra/Luna Pricing With 1.25x Cache-Write Rate**: The usage dashboard now costs GPT-5.6 traffic using seeded pricing for the three tiers — Sol at 5 / 30 / 0.50, Terra at 2.50 / 15 / 0.25, and Luna at 1 / 6 / 0.10 USD per million input / output / cache-read tokens — cross-checked against OpenAI's pricing page and OpenRouter. Unlike GPT-5.5 and earlier, whose cache writes are seeded at zero, the 5.6 family bills prompt-cache writes at 1.25x the uncached input rate, so cache-write is seeded at 6.25 / 3.125 / 1.25 for Sol / Terra / Luna. The seed set also adds the bare `gpt-5.6` id as the official Sol alias plus effort-suffix variants (`-low`, `-medium`, `-high`, `-xhigh`, `-minimal`), all priced at Sol rates and mirroring the gpt-5.5 accounting shape. Rows are applied through the seed+repair dual-write path in `src-tauri/src/database/schema.rs`: a `repair_current_model_pricing` branch corrects the earlier zero cache-write seeds for the three tiers in existing databases, matching only rows still holding the exact old input/output/cache-read/cache-write values so user-customized prices survive, and no `SCHEMA_VERSION` bump is required.
+- **Native Anthropic Messages Protocol as Codex Upstream**: Codex providers can now target a gateway that only exposes the native Anthropic Messages protocol (`/v1/messages`) via a new `anthropic` value on the upstream-format selector in the Codex form; the local proxy performs bidirectional Responses↔Anthropic request, response, and streaming conversion (new `transform_codex_anthropic` / `streaming_codex_anthropic` modules). The form adds an auth-field selector — `ANTHROPIC_AUTH_TOKEN` sends `Authorization: Bearer` (default) and `ANTHROPIC_API_KEY` sends `x-api-key`, mutually exclusive — an optional Claude Code client-impersonation toggle (`impersonateClaudeCode`, off unless explicitly enabled, spoofing User-Agent / `anthropic-beta` / `x-app` / system-prompt first line and dropping Codex/OpenAI fingerprint headers), and a per-provider `maxOutputTokens` override (Codex omits `model_max_output_tokens`, so without it the path falls back to a conservative 8192 that can truncate long or thinking-heavy replies). The bridge injects standard 5-minute ephemeral `cache_control` so system/tools/history are cached rather than resent at full price, defers stripping the `[1m]` long-context marker until after catalog matching and re-emits the `context-1m-2025-08-07` beta header, gates extended thinking on the trailing turn only so history-resending sessions don't permanently lose it after the first tool call, disables native `web_search` for this profile, drops `tool_choice` when no tools survive filtering, treats a base URL already ending in `/v1/messages` as a full endpoint, and reports truncated streams as incomplete/failed instead of completed. (#5071)
+- **Default Model Field for Codex Provider Form**: The Codex provider form now exposes the top-level `model` key of `config.toml` as an editable field, so users can point an existing provider at a newly released model (e.g. `gpt-5.6`) without waiting for a preset update — preset changes only affect newly added providers, while existing ones keep their saved TOML. The field syncs bidirectionally with the TOML editor (mirroring the base-URL pattern), suggests models from the mapping catalog unioned with the provider's `/models` endpoint, offers a one-click "add to mapping" action when the value falls outside a non-empty catalog, and is hidden for official providers. Save-time catalog sync now backfills the first mapping row into the top-level `model` only when the field was left empty, so an explicit value always wins over the implicit row-0 fallback; model names and `base_url` are written with TOML basic-string escaping and control characters are stripped from field input, since `/models` ids are remote data and unescaped interpolation could inject `config.toml` lines such as a forged `[mcp_servers.*]`. The strict model-line matcher (`src/utils/providerConfigUtils.ts`) recognizes escaped output, empty strings, and single-quoted literals to keep extract/set round-trips stable, and the fetched model list is invalidated (with an in-flight sequence guard) whenever request identity changes — base URL, full-URL toggle, API key, or custom User-Agent — so the dropdown never shows a previous provider's models.
+- **Switch-Time Common-Config Autosync Now Covers Codex**: When switching away from a Codex provider with `common_config_enabled`, the service now re-extracts the shareable portion of its live `config.toml` into the stored common-config snippet — the same live-to-snippet sync that previously ran only for Claude — so preferences you tweak directly in the running Codex config propagate to every opted-in provider and a removed key isn't silently re-injected on the next switch. Codex was gated out before because its TOML extractor leaked provider-specific and injected content; `extract_codex_common_config` now strips top-level `model`, `model_provider`, `base_url`, and `wire_api`, the entire `[model_providers]` table, `mcp_servers` and the legacy `[mcp.servers]` form, the top-level `experimental_bearer_token` fallback (which would otherwise leak the API key into the shared snippet), the `model_catalog_json` catalog pointer, and the injected `web_search = "disabled"` sentinel, while keeping a user-set `web_search` value as a shareable preference. The sync in `services/provider/mod.rs` is scoped strictly to Claude and Codex (Gemini is still excluded), skipped when the snippet was explicitly cleared, and all failures are warn-only and never block the switch; the autosync-before-strip ordering also self-heals stale snippet values previously baked into provider snapshots, since the re-extracted snippet matches the live values and the value-match strip removes them on the same switch.
+- **Claude Subagent Model Configuration**: Claude providers can now pin a dedicated sub-agent model through a new "Subagent" row in the provider form, writing the `CLAUDE_CODE_SUBAGENT_MODEL` env key so Claude Code's spawned sub-agents run on a chosen (typically cheaper or faster) model. The row supports the `[1M]` marker but has no display-name field — it renders a "Not shown in /model" placeholder since the sub-agent model never appears in the `/model` menu — and the "quick set" button now fills it alongside the other tiers. On the proxy takeover path (`services/proxy.rs`), `CLAUDE_CODE_SUBAGENT_MODEL` is added to `CLAUDE_MODEL_OVERRIDE_ENV_KEYS` so it is written when a provider configures it and stale values are cleared when a provider omits it, and the model mapper (`proxy/model_mapper.rs`) gains a `subagent_model` field that passes a request through unchanged when its model (comparing with the 1M suffix stripped) matches the configured sub-agent model, instead of collapsing it to the default-model fallback. The key is also excluded from the shared Claude common-config snippet in `services/provider/mod.rs` so it can't leak across providers, and `modelRoleSubagent` / `modelNoDisplayName` labels were added in all four locales (zh/en/ja/zh-TW). (#4830)
+- **1M Context Checkbox on the Claude Fallback Model Field**: The Claude provider form's fallback model field (`ANTHROPIC_MODEL`, the "default/fallback model") now carries the same 1M checkbox that the role-specific Sonnet/Opus/Fable rows already had, so a fallback model backed by a 1M-token window can declare it instead of silently being treated as 200K. Checking the box appends the `[1M]` marker to the fallback model id and unchecking strips it, reusing the shared `hasClaudeOneMMarker` / `setClaudeOneMMarker` / `stripClaudeOneMMarker` helpers, and the checkbox is a no-op when the model field is empty. The marker is written in the documented uppercase form (`[1M]`), which Claude Code parses case-insensitively. This is a frontend-only change to `ClaudeFormFields.tsx`. (#5124, fixes #3679)
+- **Zhipu (智谱) Team Plan Quota Query Support**: Added quota-query support for Zhipu's team plan (团队套餐), which the personal-plan query could not reach: it hits the same `open.bigmodel.cn` quota endpoint with `?type=2` and requires two extra request headers, `bigmodel-organization` and `bigmodel-project`, so `detect_provider` cannot tell it apart from the personal plan by base URL alone. The usage-script modal gains a "Zhipu GLM Team" template with organization-ID and project-ID inputs (preserved when switching templates), and the backend routes on an explicit `coding_plan_provider == "zhipu_team"` identifier threaded through the usage script, IPC command, and background query path; the new `query_zhipu_team` in `services/coding_plan.rs` pins the CN site, appends `?type=2`, and shares response parsing (`zhipu_quota_from_body` / `parse_zhipu_token_tiers`) with the personal plan. All three of API key + organization ID + project ID are required — missing any one returns a NotFound that prompts the user to complete them (identifier match is case-insensitive) — and new copy was added across all four locales (zh/en/ja/zh-TW). (#5128)
+- **OpenCode Provider Form Gains Headers and Per-Model Token-Limit Editors**: The OpenCode provider form now exposes two previously unreachable config fields as structured editors: a Headers section for the provider's `options.headers` (arbitrary HTTP headers like `HTTP-Referer` or `X-Title` sent with provider requests) with add/remove rows and case-insensitive duplicate-name rejection that reverts the input on conflict, and per-model Token Limits (Context and Output number inputs writing `model.limit.context` / `model.limit.output`, where clearing the field removes it and negative or non-finite values are rejected while valid ones are truncated to integers). The Extra Options block was reworked into a collapsible section (its i18n label stays "Extra Options") that auto-expands when options already exist. Both the headers and extra-options editors switched their placeholder draft keys to colon-bearing prefixes (`draft-header:` / `draft-option:`) — a code comment notes a colon is invalid in an HTTP field name so a draft key cannot collide with a legitimate header, and the same technique now guards option keys — and those drafts are stripped on save, fixing a bug where the old filter discarded any real option key literally starting with `option-` (the former placeholder prefix). New i18n keys were added across all four locales (zh/en/ja/zh-TW), and `aria-label`s were added for the header add/remove and model-details toggle controls in `OpenCodeFormFields.tsx`; the headers state and draft-stripping logic live in `useOpencodeFormState.ts`. (#2907)
+- **Tencent Hunyuan Hy3 Model Pricing**: Seeded pricing for Tencent's Hunyuan Hy3 (released 2026-07-06, 256K context) so its usage is billed instead of showing $0. The rows are added to `seed_model_pricing` in `schema.rs` under both the `hunyuan-hy3` and `hy3` ids, since the upstream billing id isn't yet confirmed and one of the two should match logged usage. Prices follow Tencent's launch-day list rate (CNY 1 / 4 / 0.25 per Mtok input / output / cache-hit), converted at 1 USD ≈ 7.14 to $0.14 / $0.56 / $0.035, with `cache_write` left at `0` because no write rate is published. Hy3 actually uses input-length tiered billing (<16K / 16-32K / ≥32K) but the single-price table holds the lowest tier, so long-context requests are under-billed until this is revisited against the official billing page. Being a brand-new model it is seed-only, applied on next app start via `ensure_model_pricing_seeded` with no `SCHEMA_VERSION` bump.
+
+### Changed
+
+- **Codex Chat Prompt-Cache Routing**: Added provider-aware `prompt_cache_key` injection on the Codex Responses→Chat Completions bridge. Kimi Coding and OpenAI official endpoints are enabled automatically, Kimi's preset opts in explicitly, and unknown OpenAI-compatible gateways remain off to avoid strict-schema 400s. The key is taken from an explicit client value or a real client-provided session ID—never a generated per-request UUID—with an advanced Auto/Enabled/Disabled override in all four UI locales.
+- **Provider Connectivity Configuration Simplified**: Removed the obsolete per-provider `testConfig` override (timeout, retry count, and degraded-latency threshold) from provider forms, frontend/backend provider metadata, and reachability-check merging. The lightweight `base_url` probe now always uses the single global connectivity-check configuration, while automatic failover remains driven exclusively by its separate proxy timeout and circuit-breaker settings. Also renamed the remaining settings UI and API modules from model-test terminology to connectivity-check terminology, removed the retired first-use confirmation flag, and deleted stale model/prompt/error copy across all four locales.
+- **Codex Image Capabilities Are Inferred Without a User Toggle**: Generated Codex model catalogs now advertise only models in CC Switch's confirmed, exact text-only registry as `input_modalities = ["text"]`; GPT, aliases, new suffix variants, and all unknown models fail open to `["text", "image"]`. The rectifier's “Text-Only Model Preflight” switch continues to control only proactive proxy request-body replacement and does not change Codex's catalog declaration. Live catalog reverse-import also collapses inferred modalities instead of persisting them as hidden row overrides, so a later registry correction or a model's multimodal upgrade takes effect automatically; only declarations that differ from inference survive a DB-missing/import round-trip.
+- **Context Window Values Pinned in Presets Instead of Editable Form Fields**: The `Codex` (ChatGPT/GPT-5.6) and `Kimi For Coding` presets no longer surface the "Max Context Tokens" and "Auto Compact Window" inputs in the provider form; the numbers are now hardcoded directly in the preset env (`372000`/`372000` for Codex, `262144`/`262144` for Kimi For Coding) instead of being exposed as editable `templateValues`. This drops two fields most users never need to touch while keeping both env keys present on purpose: since Claude Code resolves the compact window as `min(model window, value)`, setting it equal to the declared context window is behavior-neutral today, but pinning it explicitly shields the local compaction trigger against remote-config experiments that dial it down. The rare user who wants different numbers can still edit `CLAUDE_CODE_MAX_CONTEXT_TOKENS` / `CLAUDE_CODE_AUTO_COMPACT_WINDOW` directly in the provider's JSON editor. The change is confined to `claudeProviderPresets.ts` and its tests.
+- **Universal Provider Auto-Syncs to Live Configs After Being Added**: Adding a universal (multi-app) provider through the Add Provider dialog now immediately pushes it to its live target configs instead of only saving it to the database, so the cross-app config lands in Claude/Codex/Gemini without a separate manual sync step. After `universalProvidersApi.upsert` succeeds, `AddProviderDialog` calls `universalProvidersApi.sync(provider.id)` and reports the combined outcome: a success toast (`universalProvider.addedAndSynced`) when the sync lands, or a non-blocking warning toast (`universalProvider.addedButSyncFailed`) when the provider was saved but the sync failed — while a save failure still aborts early with the existing error toast (`universalProvider.addFailed`) and never attempts the sync. The now-unused `universalProvider.addSuccess` key was removed from all four locales (zh/en/ja/zh-TW) and a new `universalProvider.addedButSyncFailed` key was added alongside the pre-existing `addedAndSynced` key. (#2811)
+- **SudoCode Promoted to Paid Sponsor Across Six Clients**: The existing SudoCode preset — previously a `sudocode.us` provider that collided by name with an unrelated service — is replaced in place by the new paid sponsor SudoCode on `sudocode.chat`, now marked `isPartner` (gold star) with `partnerPromotionKey: "sudocode"` and a four-locale promo blurb (zh/en/ja/zh-TW). The preset spans six clients: Claude Code, Claude Desktop, Codex, OpenCode, OpenClaw, and Hermes; the Gemini entry was removed as outside sponsor scope. All endpoints move to `api.sudocode.chat` (the presets that carry an `endpointCandidates` list — Claude Code, Claude Desktop, Codex — collapse it to that single host, dropping the old `sudocode.run` fallback), and the `apiKeyUrl` points to the attributed `sudocode.chat/register?utm_source=ccswitch&utm_medium=partner` signup while `websiteUrl` moves to `sudocode.chat`. Claude Code and Claude Desktop use direct Anthropic passthrough with no model mapping, whereas Codex/OpenCode/OpenClaw/Hermes default to `gpt-5.6-sol` (replacing the old `gpt-5.5`) — Codex/Hermes/OpenClaw over the native Responses format and OpenCode via `@ai-sdk/openai`. The provider icon is refreshed to the new brand PNG, and the promo copy surfaces that one key drives Claude Opus 4.8 on the Claude apps and GPT-5.6 on Codex plus a CNY ¥10 trial-credit offer.
+- **LongCat Presets Updated to LongCat-2.0**: The LongCat presets across Claude Code, Claude Desktop, Codex, Hermes, OpenClaw, and OpenCode now default to `LongCat-2.0` in place of the retired `LongCat-Flash-Chat` / `LongCat-2.0-Preview`, advertising the model's real 1M (1048576) context window and — for the Claude Code preset — a raised `CLAUDE_CODE_MAX_OUTPUT_TOKENS` of 131072 plus an added `ANTHROPIC_SMALL_FAST_MODEL` pin. OpenClaw's and OpenCode's base URL move to the `.../openai/v1` path (Codex and Hermes already used it), and the OpenClaw model entry gains `reasoning: false`, `input: ["text"]`, `maxTokens: 131072`, a bumped `contextWindow` of 1048576, and a new `compat.maxTokensField` (`max_tokens`) hint backed by a new optional `compat` field on the `OpenClawModel` type. Because LongCat-2.0 is text-only, the proxy's media sanitizer allowlist now classifies `longcat-2.0` (case-insensitively, keeping the retired `longcat-flash-chat` name for saved configs) so images pasted into a LongCat-2.0 session are replaced with the unsupported-image marker instead of being forwarded upstream and hard-rejected; a regression test covers the classification. (#4838)
+- **Volcengine/Doubao/BytePlus Website Links Restored to Invite Pages**: Reverts the v3.16.5 change (`56248087`) that had pointed the `火山Agentplan`, `DouBaoSeed`, and `BytePlus` presets' `websiteUrl` at their product homepages. Per the commit, the `websiteUrl` for these three presets is intentionally the same ccswitch-attributed campaign/invite link as `apiKeyUrl`, so it is restored across all six app preset files — `火山Agentplan` back to its `activity/codingplan` link, `BytePlus` to its `product/modelark` link, and `DouBaoSeed` to the Ark console API-key page, each carrying the `utm_*` attribution params. The `apiKeyUrl` links were already left intact by the reverted commit and are unchanged.
+- **Code0.ai Invite Link Updated to Agent Register URL**: The Code0.ai sponsor's `apiKeyUrl` moves from the `?source=ccswitch` referral to the new agent-register invite link `https://code0.ai/agent/register/B2XHxGjGmRvqgznY`, updated across all seven app presets and the Code0 sponsor rows in all four READMEs (`README.md`, `README_ZH.md`, `README_JA.md`, `README_DE.md`). The bare `code0.ai` API endpoint stays untouched.
+- **Dropped the Redundant OpenAI Compatible Preset**: Removed the `OpenAI Compatible` custom-template preset from the OpenCode and OpenClaw preset lists so the picker no longer shows two entries pointing at the same place. It was a duplicate entry point — the built-in `custom` provider flow already exposes an interface-format selector whose default (`@ai-sdk/openai-compatible` / `openai-completions`) seeds a byte-identical starting config. Existing providers are unaffected, since presets only seed form defaults on creation and saved providers store concrete `npm`/`baseUrl`/`apiKey`/`models` values; the `@ai-sdk/openai-compatible` dropdown label is deliberately kept as the format option users pick in the custom flow, not the deleted preset.
+
+### Fixed
+
+- **Align Codex OAuth Client Identity to Fix 404s on Newest ChatGPT Models**: The newest ChatGPT-gated subscription models (e.g. `gpt-5.6-luna`) now resolve correctly when routed through the local proxy takeover with an official Codex OAuth account, instead of returning a misleading `404 Model not found` even though the account had access. ChatGPT's Codex backend performs model cohort routing by the `originator`+`version` header pair, and cc-switch previously identified takeover requests as `originator: cc-switch` with no version, landing them in a cohort where `gpt-5.6-luna` resolved to an undeployed internal engine. The `CodexOAuth` auth strategy in `proxy/providers/claude.rs` now sends `originator: codex_cli_rs` paired with `version: 0.144.1`, matching the real Codex CLI and satisfying luna's `minimal_client_version` requirement of `0.144.0`. Both headers must be sent together (dropping either re-triggers the 404), and the `CODEX_OAUTH_CLIENT_VERSION` constant must be bumped whenever a newer target model raises the minimum. A direct HTTP A/B test against the live backend confirmed the old identity 404ed while the aligned identity completed successfully, so no WebSocket transport workaround is required.
+- **Fail Closed on Responses Upstream Failures Instead of Returning Empty Replies**: When the proxy bridges an Anthropic-format client (Claude Code / Claude Desktop pointed at a Responses gateway) to an OpenAI Responses upstream, a semantic upstream failure that arrives inside an HTTP 2xx body — a `{status:"failed"|"cancelled"}` object, an `error` envelope, or a `response.failed`/`error` SSE event before any output — is now surfaced as a real error so failover can select a different provider, instead of being converted into a silent, empty `end_turn`. The forwarder validates buffered/JSON bodies (`validate_responses_success_response`) and primes streaming responses up to 256 KB (`validate_responses_stream_start`) while still inside the retry loop, and the streaming converter emits an Anthropic `error` event then ignores every event after a terminal so a late delta cannot synthesize a spurious `message_start`. Streams that end cleanly after partial text now finalize as an explicit `max_tokens`-style incomplete turn with content blocks closed in protocol order, whereas a stream cut off mid tool-call or mid-reasoning (partial JSON or a missing thinking signature) yields a `stream_truncated` error rather than a corrupt turn, and on the Codex→Anthropic direction a truncated tool call is reported `incomplete` instead of `completed`. Gateways that ignore `stream:true` and return a single whole JSON document (even without a JSON content-type) are now recognized and expanded into a full Anthropic SSE lifecycle, and malformed client-supplied history is raised as an `InvalidRequest` — a `NonRetryable` category — so it fails fast instead of retrying across every provider. Touches `forwarder.rs`, `streaming_responses.rs`, `streaming_codex_anthropic.rs`, `transform_responses.rs`, and `transform_codex_anthropic.rs`.
+- **Preserve Reasoning, Tool Results, and System Roles Across the Responses/Anthropic Bridge**: Content and token accounting that crosses the Responses↔Anthropic bridge in multi-turn tool loops is now preserved instead of being dropped or corrupted. Encrypted Responses `reasoning` items round-trip losslessly by being carried inside a versioned bridge-owned Anthropic thinking `signature` (or a `redacted_thinking` `data` field, prefixed `ccswitch-openai-reasoning-v1:`) and restored on replay, orphaned reasoning-only assistant turns are discarded so they cannot brick the next request with a missing-following-item error, and the streaming converter now consumes the official `response.reasoning_summary_text.*` / `response.reasoning_text.*` event vocabulary (keeping `response.reasoning.*` as a compatibility alias), tracks concurrent items by stable id/output-index, emits the signature before closing the block, and recovers tool arguments from `*.done` / `output_item.done` events when a gateway skips deltas. Non-streaming Responses→Anthropic tool calls with empty arguments normalize to `{}`, invalid arguments in an incomplete turn degrade to `{}` with a warning, and invalid arguments on a completed response are rejected, while on the Codex→Anthropic request path malformed or non-object arguments raise a non-retryable `InvalidRequest`, incomplete historical tool calls are dropped, and only signed thinking blocks are re-encoded as encrypted reasoning. Structured tool results now keep their `is_error` flag, text, base64/URL images, and PDF/`input_file` documents in both directions instead of collapsing to a canonical JSON string, and historical `system`/`developer` messages are hoisted into Anthropic `system` rather than being silently demoted to user turns. For accounting, usage from a successful upstream request is recorded even when the subsequent conversion fails, and the Codex→Anthropic bridge keeps standard 5-minute prompt caching on by default while honoring the dedicated `cache_injection` sub-switch. Touches `reasoning_bridge.rs`, `transform_responses.rs`, `transform_codex_anthropic.rs`, `streaming_responses.rs`, `handlers.rs`, and `forwarder.rs`.
+- **Account for Cache-Write Tokens in Proxy Usage and Cost**: Prompt-cache write tokens are now billed correctly on the proxy usage dashboard. The parser reads cache writes from OpenAI/Codex-style usage details (`input_tokens_details.cache_write_tokens` and `prompt_tokens_details.cache_write_tokens`) and preserves them through every response-usage conversion path — Chat→Responses, Responses→Anthropic, Anthropic→Responses, and OpenAI/Chat→Anthropic (`transform_codex_chat.rs`, `transform_responses.rs`, `transform_codex_anthropic.rs`, `transform.rs`, `streaming.rs`) — so cache creation is no longer dropped when a request crosses a format boundary. Because a Codex/Gemini provider's reported `input_tokens` is inclusive of both cache reads and cache writes, the cost calculator now subtracts both before applying the input rate; previously only reads were removed, so cache-write tokens were double-charged at both the input rate and the cache-creation rate. To keep historical rows accurate across this shift, a new `input_token_semantics` column (schema v13; `0` legacy = subtract reads only, `1` total-inclusive = subtract reads and writes, `2` fresh = no subtraction) records how each row's `input_tokens` was stored, so the cost backfill subtracts reads only for pre-existing rows and reads-plus-writes for new total-inclusive rows, while daily rollups are normalized to fresh input and stamped `2`. v12 databases gain the column on both `proxy_request_logs` and `usage_daily_rollups` via `migrate_v12_to_v13`, and Claude-style rows stay fresh input with no subtraction.
+- **Stronger Prompt-Cache Breakpoint Injection on the Proxy Bridge**: On the proxy paths that inject Anthropic `cache_control` breakpoints — the `codex_responses_to_anthropic` takeover bridge and the Bedrock native optimizer — the injector now spends its four-breakpoint budget more effectively so long, tool-heavy conversations keep hitting the prompt cache instead of re-sending system, tools, and history at full price every turn. Beyond marking the tools tail, system tail, and the latest cacheable message, it now adds a second older user anchor (`msgs-prior-user`) when at least four messages exist and budget remains, keeping the stable prefix inside Anthropic's 20-block lookback from the newest breakpoint. Injection is short-circuited unless both the optimizer master switch (`enabled`) and the `cache_injection` sub-switch are on, `thinking`/`redacted_thinking` blocks are never chosen as cache targets, and injected markers use Anthropic's standard 5-minute TTL. Caller-owned breakpoints are preserved verbatim — never deleted, reordered, or rewritten — and when a caller already ships more than the supported four, the injector logs a warning, adds no automatic breakpoints, and leaves the markers in place (`cache_injector.rs`, `forwarder.rs`).
+- **Kimi For Coding's 256K Context Window Now Takes Effect**: The Kimi For Coding preset's standalone `CLAUDE_CODE_AUTO_COMPACT_WINDOW=262144` (added in #4401 and shipped in 3.16.4) never actually applied, because Claude Code caps unrecognized non-Claude model ids at a 200K window and resolves the compact window as `min(model window, value)`, clamping 262144 back down to 200K. The preset now pairs it with `CLAUDE_CODE_MAX_CONTEXT_TOKENS` (both pinned to 262144) and explicitly routes the endpoint's `kimi-for-coding` alias across `ANTHROPIC_MODEL` and all three tier keys (`ANTHROPIC_DEFAULT_HAIKU/SONNET/OPUS_MODEL`), since Claude Code ignores both context envs for `claude-`-prefixed ids — the non-Claude alias is what unlocks the enlarged window. For already-saved providers, `build_effective_settings_with_common_config` in `services/provider/live.rs` injects the same two context defaults (262144) into the effective live settings at switch time for any provider whose `ANTHROPIC_BASE_URL` is the Kimi coding endpoint (`https://api.kimi.com/coding`), with a mirror-inverse strip on backfill so an injected default never hardens into stored provider config and an explicit user value always wins. Because the alias routing lives only in the preset and not in the injection, a provider saved from the old preset — which set neither the alias nor `CLAUDE_CODE_MAX_CONTEXT_TOKENS` — stays effectively at 200K until the preset is re-applied. Three tests cover backfill injection, user-override preservation, and injected-only strip.
+- **Deleted Codex MCP Servers No Longer Resurrected on Provider Activation**: MCP servers are owned by the database `mcp_servers` table and the `[mcp_servers]` section in Codex's live `config.toml` is only a projection re-synced after every write, but switching away used to bake that projection into the stored provider snapshot — so a server you deleted in the app came back to life the next time you activated that provider, and per-entry reconcile (which only knows rows still in the DB) could never clean up the orphan. Switch-away backfill now strips `[mcp_servers]` (and the legacy `[mcp.servers]` form) from the stored settings via `strip_codex_mcp_servers_from_settings`, and any snapshot already polluted self-heals the next time you switch away from it. One user-visible consequence: a hand-written `[mcp_servers.*]` section in a Codex provider's config is stripped out of the stored snapshot the first time you switch away, so going forward define Codex MCP servers through the MCP manager (the DB `mcp_servers` table) rather than by hand-editing the provider config.
+- **Codex MCP Sync Fails Closed on an Unparseable config.toml**: When writing a single MCP server into Codex, `sync_single_server_to_codex` silently fell back to an empty `toml_edit` document if the existing `config.toml` failed to parse and then wrote the whole file back — wiping every other section (`model`, `model_providers`, comments) and leaving only the one synced `[mcp_servers.<id>]` entry, a destructive fallback left behind when an earlier fix (`3a548152`) hardened only the removal path. The sync path now returns an `McpValidation` error and leaves the file untouched, matching the fail-closed behavior already used on the read/validate path, so a temporarily malformed config can no longer be silently truncated to a single MCP table.
+- **MCP Operations Now Report Per-App Failures Instead of Silently Blocking Others**: Importing MCP servers from apps used to swallow every importer error with `unwrap_or(0)`, so a corrupt Codex `config.toml` surfaced only as "imported 0 servers" with no hint anything went wrong; `import_from_all_apps` now imports each app (claude/codex/gemini/opencode/hermes) best-effort and, when any fail, reports an aggregated error naming the failing apps alongside the count that did import, with the frontend refreshing the server list on settle so partially-imported servers still appear. On the projection side `sync_all_enabled` iterated every app with `?`, so one app's unparseable live file (e.g. a broken `~/.claude.json` that passes the existence gate but fails to parse) blocked every app behind it in iteration order and bubbled a false "switch failed" back even though the target app's live file and the database were already updated; switch and save now re-project only the target app through the new `sync_enabled_for_app` and degrade projection failure to a warning, while config-import and cloud-restore keep the all-apps sweep but collect failures best-effort. Toggling `unify_codex_session_history`, which rewrites the current official provider's live `config.toml` in full and drops the `[mcp_servers]` projection, now re-projects Codex MCP through that same target-only path so enabled servers no longer silently vanish until the next provider switch. In every degraded case the projection self-heals on the next switch or MCP toggle.
+- **Codex Common-Config Form Preserves Comments and Key Order**: Toggling "use common config" in the Codex provider form used to route the merge through the frontend `smol-toml` implementation, which re-serialized the whole document (parse → deep-merge → stringify): comments were dropped, keys were reordered, and empty parent table headers like `[model_providers]` were synthesized — the long-standing "config.toml keeps getting reordered" symptom. The merge now runs on a backend command backed by the same `merge_toml_table_like` / `remove_toml_table_like` used to write live configs, so the form preview and the live write share one merge semantic and hand-written formatting survives edit-time merges, and the frontend helper was deleted outright so the pattern can't come back. Because the operations are now async, a landing result is discarded unless it is still current: a per-hook sequence number covers rapid toggle/save races so an earlier merge resolving after a later removal can't flip the switch back (last operation wins), and a config-baseline check keeps a stale merge from clobbering a TOML the user hand-edited while the merge was in flight, with the checkbox self-healing via the existing inference effect.
+- **Inject a Single Auth Placeholder on Managed Claude Takeover**: Switching the managed Claude provider from a third-party endpoint (DeepSeek/MiMo/…) to a Codex-managed provider wrote both `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` as `PROXY_MANAGED` into `~/.claude/settings.json`, so Claude Code warned "Both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY set - auth may not work as expected" on every run — an accretion artifact of the original API-key insert (#1049, Copilot) and the later `ANTHROPIC_AUTH_TOKEN` preservation that avoided a login prompt (#3784), which added the token without removing the key. The `ManagedAccount` branch of `apply_claude_takeover_fields_for_provider` now clears all token keys and injects exactly one placeholder: `ANTHROPIC_AUTH_TOKEN` for Codex-managed providers and `ANTHROPIC_API_KEY` for Copilot; local-proxy auth is unaffected because the forwarder resolves the `PROXY_MANAGED` placeholder from either header. Because enabling takeover short-circuits (`return Ok(())`) when the live config already matches the current proxy, users upgrading with an existing double-key `settings.json` may need to toggle Claude routing off and back on once (or switch providers) to trigger the rewrite. (#4919, #5095)
+- **Skip Reachability Probes for Official Providers**: Health/connectivity checks no longer derive an unauthenticated probe target from an official provider's runtime adapter defaults. Batch `stream_check_all_providers` now skips any entry whose `category` is `official`, and `StreamCheckService::resolve_base_url` returns an explicit error for official providers instead of falling back to a first-party endpoint (e.g. `https://chatgpt.com/backend-api/codex`) and probing it without credentials — a request that is meaningless and always fails. The connectivity-check button is already hidden for these providers in `ProviderCard.tsx`, so this is defense-in-depth that also matters now that the built-in Codex official provider participates in takeover; a regression test covers the Codex official provider so a future adapter change cannot silently reintroduce the probe.
+- **Usage and Quota Queries Reject Transient Transport Failures So Retry and Keep-Last-Good Work**: Usage and quota queries frequently showed spurious "query failed" states that a manual refresh could not clear, because every transport-level failure — including read-timeouts mid-body — was folded into `Ok(success:false)`, so react-query's retry never fired and the failure body poisoned the cache as if it were real data. The `balance`, `coding_plan`, and `subscription` services now return `Err` for send failures and body-read failures, reading the body via `bytes()` before `serde_json::from_slice` (reqwest's `json()` wraps read errors as `Decode`, which made error-kind checks on it dead code), while auth/4xx/parse errors stay `Ok(success:false)` and surface immediately; the script path maps transient `AppError` keys (`request_failed` / `read_response_failed`) to `Err`, Volcengine gains a `Transient` call variant, HTTP 429 is now classified transient alongside 5xx, and expired-credential retries propagate the transient error instead of rewriting it as "OAuth token has expired". The command layer skips snapshot persistence, the `usage-cache-updated` emit, and tray refresh on `Err` so the cache bridge cannot overwrite retained data. On the frontend, `resolveDisplayUsage` (generalized to subscription quotas via a new options object carrying a `rejected` flag) re-anchors stale success data retained by react-query across rejections to `dataUpdatedAt` so it expires through the same 10-minute keep-last-good window instead of masking a longer outage indefinitely, `useSubscriptionQuota` / `useCodexOauthQuota` gain keep-last-good with per-scope snapshot reset, rejected queries with no displayable value synthesize a failure placeholder carrying the real error message so the footer keeps a retry entry point, and `UsageScriptModal` surfaces string rejections via `extractErrorMessage`. (#3820)
+- **Codex Sub-Agent Session Usage Now Counted in Local Statistics**: Token usage from Codex sub-agent (spawned agent) sessions was missing from local usage statistics because the parser keyed each session's synthetic `request_id` on `session_meta.session_id`, but a sub-agent's log carries the parent thread's `session_id` while its own unique identity lives in the `id` / `thread_id` field — so multiple sub-agents under one parent collapsed onto colliding request IDs and were dropped as duplicates. `session_usage_codex.rs` now extracts a unique `thread_id` per file (preferring `id` / `thread_id` over `session_id`) and prefixes request IDs with `codex_session:thread-v1:<thread_id>:<index>`, giving each sub-agent distinct rows. Because fork/sub-agent logs first replay the parent thread's history before the takeover event, the parser detects a history-snapshot boundary (via `forked_from_id` / `subagent` source markers plus a `thread_settings_applied` or `inter_agent_communication` event) and uses the replayed `token_count` events only to restore the cumulative baseline instead of double-counting them as new usage. Archived logs under `archived_sessions/` inherit the sync cursor from their original path by filename suffix, so re-parsing an archived copy imports only appended usage rather than re-importing the whole thread; the fix ships with unit tests covering identity extraction, replay-baseline accounting, distinct request IDs, and archived-cursor inheritance. (#5187)
+- **Codex Free-Plan 30-Day Quota Window Now Renders in Footer and Tray**: Codex free accounts are metered on a rolling 30-day secondary window (`limit_window_seconds = 2,592,000`) instead of the weekly window paid plans use, and although the backend already mapped this to the tier name `30_day`, neither the frontend `TIER_I18N_KEYS` whitelist nor the tray's `TIER_LABEL_GROUPS` month group recognized it — so `SubscriptionQuotaView` filtered the tier out and, since it is the only surviving tier for a free account, the quota footer rendered nothing while the tray's `format_subscription_summary` returned `None` and showed no quota at all. A single-sourced `TIER_THIRTY_DAY` ("30_day") constant now ties together the backend `window_seconds_to_tier_name` mapping (which maps `2_592_000` explicitly), the tray's month ("m") group, and the frontend whitelist (`30_day → subscription.thirtyDay`), with the `thirtyDay` label added to all four locales (zh/en/ja/zh-TW). Two regression tests lock in the window-seconds-to-tier mappings and assert that a 30-day-only Codex account still renders in the tray, guarding the invariant that any tier visible in the footer must not leave the tray blank. (#3651, #4886)
+- **Usage Dashboard Refresh Interval Persists Across Restarts**: The usage dashboard's auto-refresh cadence was component-local state that reset to 30s on every restart, so a user who chose a different interval (off, 5s, 10s, or 60s) had to re-select it each session. The dashboard now reads and writes the choice through a new `usageDashboardRefreshIntervalMs` app setting: `UsageDashboard` takes `refreshIntervalMs` / `onRefreshIntervalChange` props wired from `SettingsPage` to the persisted settings, initializes from the saved value (normalized to a known option, falling back to the 30s default for unrecognized values), and applies changes optimistically — invalidating the usage queries immediately — while rolling back the selection if the save fails. The field is added to the Rust `AppSettings` struct, the TypeScript `Settings` type, and the zod settings schema, and three component tests cover mount-from-saved, persist-on-change, and rollback-on-failure. (#5057)
+- **Exclude Fable Tier Model Env Keys From the Shared Claude Common Config**: Fable is Claude's fourth model-mapping tier (added in v3.16.3), but its `ANTHROPIC_DEFAULT_FABLE_MODEL` / `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` env keys were missing from the provider-specific exclusion list, so a provider's Fable model pin could leak into the shared common-config snippet and then be injected into other providers on the next switch. Both keys are now stripped in `extract_claude_common_config` alongside the haiku/sonnet/opus pins, guarded by a regression test. The same commit also completes Fable's proxy-takeover support: the two keys are added to `CLAUDE_MODEL_OVERRIDE_ENV_KEYS` (now 12 entries) and the takeover writes a stable `claude-fable-5` role alias (`CLAUDE_TAKEOVER_FABLE_MODEL`), reapplying it when the provider configures Fable and clearing stale values otherwise, mirroring the other three tiers; when Fable is unconfigured no alias is written and the mapper falls back fable→opus. (#5206, fixes #4272)
+- **Default Missing Tool Schema Types and Restore the API Key Field for Uncategorized Providers**: Two provider-facing fixes. First, when a client sends a tool whose Anthropic `input_schema` omits the top-level `type` or is an empty `{}`, the proxy passed the schema through the shared `clean_schema` helper without filling in the missing type, producing an OpenAI `parameters` object that strict gateways reject. `clean_schema` (defined once in `transform.rs` and reused by the Responses converter via `super::transform::clean_schema`, so both the Anthropic→OpenAI Chat and Responses paths pick up the change) now defaults a missing root `type` to `"object"` — adding an empty `properties: {}` only when properties is also absent — and applies the defaulting only to the root schema via a new `is_root` flag threaded through a `clean_schema_inner` helper, so nested sub-schemas (an `anyOf` string/null union, an `items`-only array) are preserved unchanged rather than having a spurious `type: "object"` forced onto them. Second, editing a provider with no category (a historically imported or hand-built custom provider) hid the Claude API key input, because `useApiKeyState` only showed and auto-created the field in add mode with a defined non-official category; the gate now keys off category alone, showing and populating the field for any provider that isn't `official` or `cloud_provider` — including the undefined-category edit case — while `official` (OAuth-only, input disabled) and `cloud_provider` (which use dedicated auth fields rather than an Anthropic key) stay conservative. New unit and hook tests cover both converters and the uncategorized/official/cloud-provider key paths. (#5069)
+- **Media Fallback for Volcano GLM 5.2 Text-Only Image 400s**: When the local proxy takes over a Volcano Coding Plan provider running GLM 5.2, image blocks in a request no longer produce a dead 400 — the rectifier's media fallback in `src-tauri/src/proxy/media_sanitizer.rs` now covers GLM 5.2 on both its preventive and reactive paths. Preventively, the text-only model registry gains `glm-5.2` as an exact tail match (deliberately not a prefix, so a future multimodal `glm-5.2v` variant following Zhipu's 4v/5v naming keeps its images), stripping image blocks before they reach the text-only endpoint. Reactively, because the gateway's error `Model only support text input` never mentions image/vision/media and drops the third-person `s`, a new self-evident phrase list (`only support text` / `only supports text`) now asserts a modality rejection on its own and bypasses the `mentions_image` gate that previously discarded the error before the fallback hints could run; the old `only supports text` hint is folded into that list. Regression tests exercise the verbatim #5025 error body, the `glm-5.2[1M]` mapped-model form, and a `glm-5.2v` negative assertion. (#5025)
+- **Display Renamed Codex Session Titles**: Sessions renamed inside Codex now show their renamed titles in the session manager instead of silently falling back to the original first-message text. The scanner (`src-tauri/src/session_manager/providers/codex.rs`) loads thread titles from Codex's `session_index.jsonl` and `state_5.sqlite` — resolving the DB path from `sqlite_home` / `CODEX_SQLITE_HOME` through a new shared `codex_state_db` module that deduplicates path resolution previously copy-pasted with the history-migration code — and prefers a stored thread title over the first user message when building each session's display title. The read-only title query adds a `busy_timeout` so a lookup during a concurrent Codex write no longer fails immediately with `SQLITE_BUSY` and drops back to the first message, and the `title == first_user_message` check is pushed into a NULL-safe SQL `WHERE` clause (matching Codex's `distinct_thread_metadata_title` semantics) so the potentially large `first_user_message` column no longer crosses into Rust. (#4927)
+- **Live Config Edits for OpenCode, OpenClaw, and Hermes Now Sync Into the Database on Startup**: The startup auto-import for the live-config-managed apps previously skipped any provider whose id already existed in the database, so edits made directly to the OpenCode, OpenClaw, or Hermes (`~/.hermes/config.yaml`) live files — a changed base URL, an added or renamed model — were never picked up after the first import and silently diverged from the app's stored copy. The `import_{opencode,openclaw,hermes}_providers_from_live` functions in `services/provider/live.rs` now look up each existing provider and, when its live `settings_config` differs, rewrite the stored provider from the live file (OpenCode additionally refreshes the display name from the live `name`, falling back to the existing name rather than the id); the returned count now covers both new imports and updates, and the startup log line changed from "Imported N" to "Synced N". The sync runs on every launch from `lib.rs::run()`, is a no-op when nothing changed, and is fully non-fatal — a provider that vanishes mid-import or a DB lookup error is warned and skipped, and users with no live file still take the quiet `Ok(0)` path. (#4712, #5098)
+- **OpenCode Session Resume Command Updated to Current CLI Syntax**: The Session Manager displayed and copied `opencode session resume <id>` as the resume command for OpenCode sessions, which is not the OpenCode CLI's current resume syntax, so pasting the copied command would not resume the session. Both the SQLite-scanned (`scan_sessions_sqlite`) and JSON-parsed (`parse_session`) session paths in `session_manager/providers/opencode.rs` now emit `opencode -s <id>` to match the CLI's actual resume flag. (#2359)
+
+### Docs
+
+- **Codex + Kimi Local Routing Guides**: New step-by-step guides explain how to run Kimi inside the Codex CLI through CC Switch's local routing, motivated by a protocol mismatch: the newer Codex CLI targets the OpenAI Responses API while both Kimi Open Platform and Kimi For Coding expose the OpenAI Chat Completions shape (`/chat/completions`), so pointing a Kimi endpoint straight at Codex typically 404s on `/responses` or yields streams Codex cannot parse. The guides walk through adding a Codex provider from the built-in `Kimi` (Open Platform, pay-as-you-go, `kimi-k2.7-code`) or `Kimi For Coding` (membership, `kimi-for-coding`) preset, and lay out the four-step conversion chain: Codex is written to talk to `http://127.0.0.1:15721/v1` with `wire_api = "responses"` kept in place, the provider's `meta.apiFormat = "openai_chat"` flags the real upstream as Chat, the route rewrites `/responses` to `/chat/completions` and converts the body, then converts the upstream Chat JSON/SSE back into the Responses shape Codex expects. Added under `docs/guides/` in English, Japanese, and Chinese with accompanying UI screenshots.
+- **new-api Sponsor Row in READMEs**: The open-source AI infrastructure project `new-api` is appended as the newest entry in the sponsor table across all four localized READMEs (`README.md`, `README_ZH.md`, `README_JA.md`, `README_DE.md`), along with its banner asset.
+
+### Internal
+
+- **Harden Release Supply Chain**: Added a `.github/CODEOWNERS` that, together with branch protection's Code Owners rule, requires owner review before any PR merges to `main` (with `/.github/` and `/src-tauri/` pinned explicitly alongside the global `*` fallback, all to `@farion1231`), gated the release job behind a `release` environment in `release.yml` so signing secrets unlock only after manual approval, and removed `.github` from `.gitignore` so the previously untracked `labeler.yml` and `workflows/labeler.yml` are now versioned.
+- **Settle pnpm Build-Script Approvals**: Approved `esbuild` (via `onlyBuiltDependencies`) and ignored `msw` (via `ignoredBuiltDependencies`) in `pnpm-workspace.yaml` so pnpm 10.13+ stops appending `allowBuilds` placeholders to the file on every install.
+- **Platform-Gate the Desktop-Scope Assertion in the Profile Roundtrip Test**: The `profile_roundtrip` integration test's Claude Desktop assertion is now `cfg`-gated to macOS/Windows to match the already cfg-gated desktop switch, so on Linux CI (where desktop live writes error) it expects the seeded `d1` instead of `d2` and no longer panics, poisons the shared test mutex, and cascades into two more failures.
+
+## [3.16.5] - 2026-07-01
+
+Development since v3.16.4 reworks the Codex native-Responses path — restoring a generated model catalog for proxy-less direct-connect, decoupling model mapping from the local-routing toggle, and adding a host/model-prefix blacklist that disables Codex's built-in web_search on gateways that reject it — alongside a broad wave of new provider presets (Qiniu and Code0.ai across all seven apps, the FennoAI/ZetaAPI/TeamoRouter/NekoCode partners, and the non-partner Amux), Claude Sonnet 5 pricing plus a default-tier bump to it, a categorized two-level session view with group-level batch selection, live auto-sync of the shared Claude common config on switch, and a run of credential-safety, tool-detection, Doubao model-id, branding, and icon-size fixes.
+
+**Stats**: 36 commits | 93 files changed | +5,678 insertions | -2,804 deletions
+
+### Added
+
+- **Codex Native Responses Direct-Connect Regenerates a Model Catalog**: Reverses the v3.16.4 direction that dropped the catalog — Codex providers now run in two explicit modes, and native direct-connect once again ships a catalog file. Providers with `apiFormat: "openai_responses"` run with no proxy, and cc-switch generates `~/.codex/cc-switch-model-catalog.json` (`CC_SWITCH_CODEX_MODEL_CATALOG_FILENAME`, provider id `custom`) so Codex Desktop actually shows the custom models and tools work without the freeform `apply_patch` (`type=custom`) tool that native gateways like MiMo reject — editing falls back to `shell_command`. Catalog generation is keyed on `apiFormat` via `CodexCatalogToolProfile` and decoupled from the route-takeover toggle, so a native provider persists a catalog without enabling local route mapping, while `openai_chat` keeps the existing Responses↔Chat proxy conversion unchanged. Codex's parser requires `base_instructions` on every entry, so the native template (`codex_native_responses_template.json`, slug `gpt-5.5`) carries a neutral default that per-vendor official text overrides (MiMo, MiniMax); synthesized catalogs for Qwen/Doubao/LongCat use the neutral default. Existing native providers must be re-saved once to regenerate a valid catalog (no DB migration).
+- **Categorized Session View With Two-Level Grouping**: The Session Manager gains a grouped view mode alongside the flat list, toggled via a List/ListTree Select in the toolbar and persisted to `localStorage` under `cc-switch.sessionManager.listViewMode`. The new `groupSessionsByProviderAndDirectory` helper builds a two-level hierarchy (provider group → project-directory group): directory groups are keyed by `getSessionDirectoryGroupKey(providerId, projectDir)` and labeled with `getBaseName(projectDir)`, and sessions lacking a `projectDir` fall into an "unknown directory" bucket (`UNKNOWN_PROJECT_DIR_KEY = __unknown_project_dir__`). Both levels are Radix Collapsible sections whose expansion state is serialized to `cc-switch.sessionManager.groupExpansionState` (pruned to valid keys after load), with a "collapse all" button; in batch mode each group header gains a tri-state checkbox that selects/deselects every selectable session (those with a `sourcePath`) at once, backed by a `Minus`-glyph indeterminate state added to `ui/checkbox.tsx` and a selected/selectable count badge. New keys were added across all four locales (zh/en/ja/zh-TW). The change is entirely frontend — no Tauri commands or DAO changes. (#4776)
+- **Qiniu (七牛云) Provider Preset Across All Seven Apps**: Added the Qiniu Cloud AI gateway as a partner aggregator spanning Claude Code, Claude Desktop, Codex, Gemini, OpenCode, OpenClaw, and Hermes — the widest coverage of the batch and the only one carrying a Gemini preset. Because Qiniu relays native Claude/GPT/Gemini rather than remapping to domestic models, Claude Code/Desktop use the Anthropic-compatible bare host with native passthrough (no model pinning), Codex hits native Responses at `https://api.qnaigc.com/bypass/openai/v1` defaulting to `gpt-5.5`, and Gemini uses `gemini-3.1-pro-preview` via `https://api.qnaigc.com/bypass/vertex`; OpenCode/OpenClaw/Hermes default to `gpt-5.5` over the OpenAI-compatible `/v1`. Each type carries `endpointCandidates` listing the `api.qnaigc.com` primary plus the `api.modelink.ai` overseas mirror for failover. It is marked `isPartner` with referral `https://s.qiniu.com/nMvAvy`, a localized display name via `nameKey` (`providerForm.presets.qiniu`) and a partner-promotion blurb in all four locales (zh/en/ja/zh-TW), and registers the `qiniu.png` icon through URL import plus `iconUrls` and metadata.
+- **FennoAI, ZetaAPI, and TeamoRouter Partner Presets**: Added three partner aggregators — FennoAI (`api.fenno.ai`), ZetaAPI (`api.zetaapi.ai`), and TeamoRouter (`api.teamorouter.com`) — each covering Claude Code, Claude Desktop, Codex, OpenCode, OpenClaw, and Hermes with no Gemini preset, since these relay native Claude/GPT only. In every case Claude Code/Desktop use the Anthropic-compatible bare host with native passthrough, Codex uses native Responses (FennoAI at `api.fenno.ai`, ZetaAPI and TeamoRouter at their `/v1` paths) defaulting to `gpt-5.5`, and OpenCode/OpenClaw/Hermes default to `gpt-5.5` over the OpenAI-compatible `/v1`. All three are `isPartner` with referral `apiKeyUrls` (FennoAI's ¥9.9 Coding Plan link, ZetaAPI's `zetaapi.ai/go/ccs`, TeamoRouter's `teamorouter.com` with `utm_source=cc_switch` — its in-app link stays English while README links are per-language), each ships a localized promo blurb in zh/en/ja/zh-TW plus a sponsor row in all four READMEs, and each registers its own icon (`fenno-icon.webp`, `zetaapi-icon.png`, `teamorouter`). Two carry surfaced discount codes: ZetaAPI gives a first-recharge 10% discount with promo code `CC-SWITCH`, and TeamoRouter gives new users 10% off their first top-up.
+- **Amux Aggregator Preset**: Added Amux (`api.amux.ai`) as a non-partner aggregator across Claude Code, Claude Desktop, Codex, OpenCode, OpenClaw, and Hermes, with no Gemini preset. Claude Code/Desktop use the bare Anthropic-compatible host, Codex uses native Responses over the `/v1` path, and the remaining three apps default to `gpt-5.5` over the OpenAI-compatible endpoint. Unlike the partner presets in this batch it carries no `isPartner` flag, referral link, or promo copy; the `amuxapi-icon.svg` is registered as an inline `currentColor` icon in `src/icons/extracted/index.ts` and `metadata.ts` rather than a raster URL import.
+- **Code0.ai Partner Preset Across All Seven Apps**: Added Code0.ai (`code0.ai`) as a partner aggregator spanning all seven apps — Claude Code, Claude Desktop, Codex, Gemini, OpenCode, OpenClaw, and Hermes. Claude Code, Claude Desktop, and Gemini use the bare `https://code0.ai` host (Anthropic-native passthrough with no model pinning for the two Claude apps, `gemini-3.1-pro-preview` for Gemini), Codex hits native Responses at `https://code0.ai/v1`, and OpenCode/OpenClaw/Hermes default to `gpt-5.5` over the OpenAI-compatible `/v1`. It is marked `isPartner` with a `?source=ccswitch` referral on the API-key signup link, a partner-promotion blurb surfacing the CC Switch test-credit offer in all four locales (zh/en/ja/zh-TW), a sponsor row in all four READMEs, and the `code0.png` icon registered via URL import.
+- **NekoCode Partner Preset Across Six Apps**: Added NekoCode (`nekocode.ai`) as a partner aggregator spanning six apps — Claude Code, Claude Desktop, Codex, OpenCode, OpenClaw, and Hermes (no Gemini preset). Claude Code and Claude Desktop use the bare `https://nekocode.ai` host (Anthropic-native passthrough with no model pinning), Codex hits native Responses at `https://nekocode.ai/v1`, and OpenCode/OpenClaw/Hermes default to `gpt-5.5` over the OpenAI-compatible `/v1`. It is marked `isPartner` with a `?aff=CCSWITCH` referral on the API-key signup link (kept off the actual request endpoints), a partner-promotion blurb in all four locales (zh/en/ja/zh-TW), and a sponsor row in all four READMEs, both surfacing the CC Switch offer — 10% off top-ups with promo code `cc-switch` at recharge. The `nekocode-icon.png` icon is registered via URL import.
+- **Claude Sonnet 5 Model Pricing**: Seeded a `claude-sonnet-5` pricing row in `schema.rs` at Anthropic list price — $3/$15 per Mtok input/output and $0.30/$3.75 cache read/write, identical to the Sonnet 4.6 rates. The introductory $2/$10 promo (valid through 2026-08-31) is deliberately not seeded, so accounting reflects steady-state list pricing rather than a temporary discount. The row is applied on next app start via `ensure_model_pricing_seeded` and requires no `SCHEMA_VERSION` bump.
+
+### Changed
+
+- **Decoupled Codex Model Mapping From the Local-Routing Toggle**: Aligns the Codex provider form with Claude Code — the model-mapping catalog is now independent of route takeover, since native Responses providers (MiMo, Doubao, MiniMax) need it for proxy-less direct connect while Chat providers use the proxy regardless of any per-provider flag. The "Needs Local Routing" toggle is removed: it had no backend field and only gated catalog/reasoning persistence, which is equivalent to whether the mapping is filled. Model mapping is now always shown for non-official providers and persisted whenever the list is non-empty (the backend already keys off `modelCatalog.models`), while reasoning visibility/persistence is gated on the Chat format instead of the toggle. The Chat upstream-format option is marked "routing required" with a refreshed advanced-section hint across all four locales (zh/en/ja/zh-TW), dead `localRouting*` keys are dropped, and the model-mapping block moves above the custom User-Agent block. Also fixes `useCodexConfigState` dropping `supportsParallelToolCalls`/`inputModalities`/`baseInstructions` when loading a saved provider — which silently lost parallel tools, image input, and the official base instructions on edit — by preserving them on load (camelCase and snake_case) and comparing them in the row sync.
+- **Auto-Sync Claude Common Config From Live settings.json on Switch**: When switching away from a Claude provider that has `common_config_enabled`, the service now re-extracts the shareable portion of its live `settings.json` and replaces the stored common-config snippet, instead of only writing the snippet one way. This captures config the user added directly in the running app (`enabledPlugins`, `hooks`, `env`, `theme`, shared prefs) so it isn't silently lost on the next switch, and it propagates deletions so a removed key isn't re-injected later. The sync in `services/provider/mod.rs` is scoped strictly to Claude providers with `common_config_enabled`, is skipped when the snippet was explicitly cleared, and all failures are non-fatal (warn-only) and never block the switch. Four integration tests cover capture / delete-sync / opt-out / cleared.
+- **Default Sonnet Tier Now Pins to Claude Sonnet 5**: Bumped every default Sonnet pin from `claude-sonnet-4-6`/`claude-sonnet-4.6` to `claude-sonnet-5` across all provider presets (`claudeProviderPresets`, `claudeDesktopProviderPresets`, `hermesProviderPresets`, `openclawProviderPresets`, `opencodeProviderPresets`, and universal `NEWAPI_DEFAULT_MODELS`), covering the `ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_OPUS_MODEL` env keys and prefixed variants like `anthropic/claude-sonnet-5` and `global.anthropic.claude-sonnet-5`. The Claude Desktop `DEFAULT_PROXY_ROUTES` sonnet `route_id` in `claude_desktop_config.rs` also moves to `claude-sonnet-5` (`supports_1m` preserved), and the route-derivation test expectations were updated to match. Non-Anthropic pins (gpt/gemini/glm/sonnet-4-5) were left untouched.
+- **Doubao Dated Model Id and YYMMDD Pricing Normalization**: Switched the Doubao (DouBaoSeed) preset model id to the dated form `doubao-seed-2-1-pro-260628` across every app surface (config default, generated Codex catalog, and OpenClaw namespaced refs), because Volcengine Ark rejects the bare `doubao-seed-2-1-pro` with a 404 ("model does not exist or you do not have access to it") even after activation and only accepts the full dated id. Because real usage now arrives with a date suffix, `strip_model_date_suffix` in `usage_stats.rs` was extended to also strip Volcengine's 6-digit YYMMDD form (`-260628`, `-250615`) in addition to the existing 8-digit YYYYMMDD/ISO handling; the 6-digit branch validates month 01-12 and day 01-31 to avoid eating non-date version suffixes like `-123456`, then falls back to `None` for exact matching. This keeps the bare-name seed row as the canonical pricing identity, fixing the $0-cost display for every Volcengine Doubao model. Unit and end-to-end regression tests were added.
+- **"Write Common Config" Renamed to "Apply Common Config"**: The original label "Write Common Config" (写入通用配置) was ambiguous about data-flow direction, reading as "write the current config INTO the common config" when the actual behavior is the reverse — the saved common-config snippet is merged INTO this provider's config. The checkbox is renamed to "Apply Common Config" across all four locales (zh/en/ja/zh-TW), including every hint/guide/notice reference and the `CommonConfigEditor` / `GeminiConfigSections` defaultValue fallbacks, and the Gemini hint wording is aligned with the claude/codex "when checked" phrasing. The Japanese user manual (`docs/user-manual/ja/2-providers/2.1-add.md`) and `README_JA.md` were also synced to 共通設定を適用 / 共有設定を適用. (#4829)
+- **OpenClaw Doubao Context Window Aligned to 262144**: The OpenClaw DouBaoSeed preset hard-coded `contextWindow` 128000 while the Codex preset/catalog used 262144 for the same model, giving OpenClaw users a too-small window that could compress or truncate long context prematurely. Bumped `openclawProviderPresets.ts` to 262144 and added a cross-preset consistency test asserting the OpenClaw and Codex Doubao context windows stay equal so the two sides cannot silently drift apart again.
+- **Volcengine/Doubao/BytePlus Website Links Restored to Official Homepages**: The `websiteUrl` for the 火山Agentplan, BytePlus, and DouBaoSeed presets had accidentally been set to the same invite/console link as `apiKeyUrl`, so the "visit official site" button routed users to the referral/API-key page instead of the product homepage. Restored clean official homepages across all six app preset files — 火山Agentplan to `https://www.volcengine.com/product/ark`, DouBaoSeed to `https://www.volcengine.com/product/doubao`, and BytePlus to `https://www.byteplus.com/en/product/modelark` (dropping the utm params) — while leaving the `apiKeyUrl` referral links intact.
+- **Kimi and SiliconFlow Referral Links Refreshed**: Updated two sponsor referral sets across presets and READMEs. Following Moonshot's console rebrand to Kimi, the Kimi preset referral links and the domestic (ZH) README banner moved to the new `platform.kimi.com` domain — the domestic console `platform.moonshot.cn/console` → `platform.kimi.com`, the API-key page → `platform.kimi.com/console/api-keys`, and the Coding Plan link `www.kimi.com/code/docs/` → `www.kimi.com/code/` — and the missing `?aff=cc-switch` attribution param was added to the codex and openclaw entries. API endpoints (`api.moonshot.cn`, `api.kimi.com/coding`) were left unchanged, and the presets have no overseas variant (the separate EN/DE/JA README switch to `platform.kimi.ai` is covered under Docs below). Separately, the SiliconFlow invite code was rotated from `drGuwc9k` to `YflgU2Ve` across all README locales and the claude, claude-desktop, codex, hermes, and openclaw presets.
+- **Downscaled Oversized Provider Icons to 256px**: Shrank a batch of bundled provider icons that shipped far larger than their ~32px on-screen render size in `ProviderIcon`, cutting bundle weight with no code, filename, or import changes (aspect ratio preserved, rendered via `<img>` object-contain). Raster PNGs: ZetaAPI 1254×1254/940KB→40KB, relaxcode 1462×1076/1.16MB→42KB, sudocode 2048×2048/432KB→37KB, hermes 512×512/125KB→38KB, claudecn 512×512/109KB→46KB, atlascloud 3525×3300/105KB→9KB. Two "fake vector" SVGs wrapping a single oversized base64 PNG were re-embedded at a 256px max dimension keeping the SVG wrapper: ccsub 1.16MB→60KB and shengsuanyun 212KB→51KB. Also removed `dds.svg`, a 1.4MB genuine 2222-path vector that was never imported in `index.ts` nor referenced under `src/`, so it only bloated the repo without ever shipping.
+
+### Fixed
+
+- **Disable web_search for Native Codex Gateways That Reject It**: Some native `/responses` gateways whose first-party models lack OpenAI's hosted `web_search` tool reject it with "tool type 'web_search' is not supported by this gateway phase" (`responses_feature_not_supported`), and Codex sends the tool by default (config-driven, not gated by the catalog's `supports_search_tool`), producing hard 400s. cc-switch now writes the top-level TOML line `web_search = "disabled"` for those vendors via `set_codex_native_web_search_field`, injected alongside `model_catalog_json` at switch time. Scope is a blacklist (default-on): only providers matched by `base_url` host — `CODEX_WEB_SEARCH_REJECT_HOSTS = xiaomimimo.com, longcat.chat, minimax.io, minimaxi.com` — or by model brand prefix — `CODEX_WEB_SEARCH_REJECT_MODEL_PREFIXES = mimo, longcat, minimax, qwen3-coder` — are disabled, so relays serving real GPT, DouBao, general Qwen, and any unknown provider keep Codex's default. The `qwen3-coder` prefix suppresses the tool for the native `qwen3-coder-plus` direct-connect preset (百炼/DashScope marks built-in tools unsupported for the coder series) while general Qwen models sharing the DashScope host stay enabled — matching is on the model axis (after stripping any aggregator `vendor/` path segment like `MiniMaxAI/MiniMax-M3` or `qwen/qwen3-coder-plus`), so it also catches aggregators such as SiliconFlow fronting a reject vendor's model. A blacklist was chosen over a fuzzy "is this GPT?" whitelist because wrongly keeping `web_search` ON fails with a hard 400, and an ownership sentinel means cc-switch only ever removes a `web_search` key whose value equals its own `disabled`, so existing providers need no re-save and switching back re-enables web search. Also corrects the LongCat-2.0-Preview preset context window from 131072 (128K) to its real 1048576 (1M), aligning with the MiMo/Qwen 2^20 convention, and tightens the native Responses preset tests to assert exact model→contextWindow catalogs instead of only checking catalog presence.
+- **Strip All Credential-Like Keys From the Shared Claude Common-Config Snippet**: `extract_claude_common_config` previously only redacted `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN`, but Claude providers legitimately carry other credentials (`OPENROUTER_API_KEY`, `GOOGLE_API_KEY`, and possibly OpenAI/Gemini/AWS Bedrock/Vertex secrets), which could leak into the shared snippet and then be injected into other providers. Extraction now pattern-matches and strips any credential-shaped env key (`*_API_KEY` / `*_AUTH_TOKEN` / `*secret*` / `*token*`, etc.), while preserving plural `*_TOKENS` values like `MAX_OUTPUT_TOKENS` as legitimately shareable. This also closes the same pre-existing leak in the manual Extract and one-time auto-extract paths, and is covered by a dedicated credential-stripping unit test.
+- **Usage-Script Credentials Persisted Only as Explicit Overrides**: Provider usage scripts store optional `api_key`/`base_url` fields that override the provider's live credentials when querying quota, but these were silently mirroring the provider's own credentials — so copying a provider or editing its main API key/base URL left the usage script pinned to the old endpoint and key, and quota queries kept hitting the stale target. `ProviderService::add`/`update` now run `normalize_usage_script_credential_overrides` before persisting: if the script's trimmed `api_key` or slash-normalized `base_url` matches the provider's resolved usage credentials (or is blank) it is cleared to `None` so the query falls back to `resolve_usage_credentials` from the live config, while genuinely distinct overrides are kept and `template_type == "token_plan"` scripts are left untouched. The deeplink import path gained matching `normalize_deeplink_api_key`/`base_url` helpers, and the frontend now invalidates `usageKeys.script(id, appId)` (including the `originalId` when a provider is renamed) on update so the homepage re-queries with the corrected config instead of the test-time cache. (#4654)
+- **Hermes Config Dir Now Resolves Correctly on Windows**: CC Switch hardcoded `~/.hermes` as the Hermes config directory, but Hermes itself resolves it via `get_hermes_home()` — the `HERMES_HOME` env var, then a platform default of `%LOCALAPPDATA%\hermes` on Windows (`~/.hermes` on mac/Linux). On Windows this meant CC Switch wrote provider configs to a path Hermes never reads, so provider switches had no effect. `get_hermes_dir()` now mirrors Hermes' own resolution order — `settings.hermes_config_dir` explicit override, then `HERMES_HOME` taken verbatim (trimmed, non-empty, no `~` expansion, matching Hermes' `Path(val)`), then the platform default reading the actual `LOCALAPPDATA` env var (falling back to `~\AppData\Local\hermes`) on Windows and `~/.hermes` elsewhere. This deliberately re-honors the `HERMES_HOME` that #3470 had dropped, since unlike Codex/Claude the Hermes Windows installer sets `HERMES_HOME` as a first-class mechanism for relocated installs. Config-dir tests were also isolated from ambient `HERMES_HOME`/`LOCALAPPDATA`. (#4680, refs #3178, #3470)
+- **Linux Wayland: Override the AppImage's Forced `GDK_BACKEND=x11`**: The AppImage's GTK launch hook (`linuxdeploy-plugin-gtk.sh`) unconditionally exports `GDK_BACKEND=x11` to dodge a historical native-Wayland crash (tauri-apps/tauri#8541). On newer Wayland + NVIDIA setups this forced XWayland leaves the WebKitGTK web content unable to receive pointer events — the GTK title bar stays clickable but the page is dead — and black-screens on resize; the existing `WEBKIT_DISABLE_*` mitigations don't help because the root cause is the forced window backend, not rendering. Since the hook also overrides any user-set `GDK_BACKEND`, there was no way to switch back without unpacking the AppImage. `main.rs` now reads an opt-in `CC_SWITCH_GDK_BACKEND` escape hatch (which the hook never touches) before GTK init: leaving it unset keeps the current x11 behavior unchanged (zero regression), while `CC_SWITCH_GDK_BACKEND=wayland` forces native Wayland. The override is generic, so users on tiling Wayland compositors hitting the inverse input bug can set `CC_SWITCH_GDK_BACKEND=x11`. (#4351, fixes #4350)
+- **Get API Key Link Now Shows in Claude Desktop, OpenClaw, and Hermes Forms**: The "Get API Key" link and partner-promotion block below the API key input was only wired for claude/codex/gemini/opencode. Claude Desktop rendered a bare Input that never showed it, and OpenClaw/Hermes were blocked by two gaps: `useApiKeyLink` whitelisted only those four appIds (so the link was suppressed even when a preset carried `apiKeyUrl`), and `useProviderCategory` only parsed the `/^(claude|codex|gemini|opencode)-(\d+)$/` preset-id pattern (so OpenClaw/Hermes category stayed undefined and the cn_official/aggregator/third_party link condition never held). `ClaudeDesktopProviderForm` now calls `useApiKeyLink` and uses the shared `ApiKeySection`; the `useApiKeyLink` whitelist and its `PresetEntry` union add claude-desktop/openclaw/hermes; and `useProviderCategory` now resolves openclaw/hermes preset categories. Additionally, `HermesFormFields` and `OpenClawFormFields` no longer let an "official" category disable the key input, since these apps have no OAuth-only official providers (e.g. Hermes' Nous Research is official but still needs a user-supplied key).
+- **Deduplicated Windows Codex npm Shims in Tool Detection**: On Windows, npm installs a tool as three sibling files — `codex.cmd`, `codex.exe`, and an extensionless Unix shim named `codex` — and CC Switch's `tool_executable_candidates` listed all three, so the extensionless shim (which Windows cannot execute directly) was probed as a redundant/failing candidate. `tool_executable_candidates` now appends the extensionless path only when `windows_runnable_sibling_for_extensionless_tool` finds no adjacent `.cmd`/`.exe` sibling, and `resolve_path_default` likewise prefers a runnable `.cmd`/`.exe` sibling before canonicalizing a bare extensionless PATH hit. This keeps version detection and launching anchored to the actually-runnable Windows shim instead of the shadowed Unix one. (#4782)
+- **Scroll Bounds for Long Select Dropdowns**: The `SelectContent` popover used `overflow-hidden` with no height cap, so dropdowns with many options (e.g. long model or provider lists) rendered taller than the viewport and clipped their overflowing items with no way to reach them. It now sets `max-h-[min(24rem,var(--radix-select-content-available-height))]` and `overflow-y-auto overflow-x-hidden`, bounding the content to 24rem or the Radix-computed available height and letting the list scroll vertically while still clipping horizontally. (#4798)
+- **Date-Range Picker Calendar Stays On-Screen in Narrow Popovers**: The custom date-range picker switched to its two-column layout (date fields | calendar) based on the viewport width via Tailwind's `sm:` (640px) breakpoint, but the popover is clamped to `100vw - 2rem` and anchored to its trigger with `align="end"`, so its real available width is narrower than the viewport. On narrow windows the two-column layout could activate while the popover only had room for one column, pushing the calendar column off the right edge where it was clipped — the month header and 4 of 7 weekday columns cut off and unreachable. The layout now keys off the popover's own inline size via a CSS container query (`w-[620px] max-w-[calc(100vw-2rem)]`) instead of the viewport, so it collapses to one column exactly when the popover itself is narrow, keeping the calendar fully visible at any window width. (#4860)
+
+### Docs
+
+- **Documented the `CC_SWITCH_GDK_BACKEND` Escape Hatch in README and User Manual**: Added an FAQ entry for the opt-in `CC_SWITCH_GDK_BACKEND` environment variable (see the corresponding Fixed entry) across all four README locales (`README.md`, `README_ZH.md`, `README_JA.md`, `README_DE.md`) and the zh/en/ja user-manual troubleshooting pages (`docs/user-manual/{zh,en,ja}/5-faq/5.2-questions.md`), explaining how Wayland + NVIDIA users can switch back to native Wayland when the webview goes click-dead and black-screens on resize, and how tiling-Wayland users can set it to `x11` for the inverse input bug.
+- **Overseas Kimi READMEs Point to platform.kimi.ai With a Coding Plan Link**: Updated the Kimi K2.7 Code partner section across the English, German, and Japanese READMEs so the banner image and both inline CTAs point to `https://platform.kimi.ai?aff=cc-switch` instead of the old `platform.kimi.com` host, keeping the `aff=cc-switch` referral tag intact. All four localized READMEs (`README.md`, `README_DE.md`, `README_JA.md`, `README_ZH.md`) also gained a new line promoting the Kimi For Coding subscription plan linked to `https://www.kimi.com/code/?aff=cc-switch`; note the ZH README kept its existing `platform.kimi.com` link and only received the Coding Plan addition.
+- **GitHub Global Top-100 Milestone Banner in v3.16.4 Release Notes**: Prepended a celebratory callout blockquote to all three localized v3.16.4 release notes (`docs/release-notes/v3.16.4-en.md`, `-ja.md`, `-zh.md`) announcing that CC Switch has entered the global top 100 GitHub projects by star count, thanking users, contributors, and stargazers. This is a docs-only addition to the release-notes header and does not change any product behavior.
+
+## [3.16.4] - 2026-06-27
+
+Development since v3.16.3 focuses on tightening the Codex proxy path — native OpenAI Responses migration for the major Chinese providers, a decoupled upstream-format selector, zstd request/error-body decompression, and a run of tool-call and OAuth-over-proxy fixes — alongside richer usage and pricing tooling (models.dev pricing import, Volcengine Ark coding/agent-plan quotas, live-tracking date ranges, GLM-5.2/Doubao Seed 2.1 pricing), new proxy and resilience capabilities (custom request header/body overrides, an in-app recovery screen for too-new databases, native Windows ARM64 builds), and a broad wave of preset and branding updates (the SubRouter and OpenCode Go subscriptions, the CTok→ETok rename, Kimi rebranding and prime-partner badges, and a Kimi K2.7 Code sponsor banner).
+
+**Stats**: 53 commits | 126 files changed | +8,149 insertions | -1,016 deletions
+
+### Added
+
+- **In-App Recovery Screen for a Too-New Database**: When the SQLite `user_version` is newer than the app supports (`SCHEMA_VERSION`) — e.g. after a downgrade or because a third-party client wrote the file — startup used to dead-end in a native Retry/Exit dialog where Retry just failed again. The app now boots a dedicated recovery screen offering an in-place "Upgrade app" button (download + install + restart with a progress bar) when an update is available, or a warning that even the latest build can't read the database when none is. The too-new check runs before any schema writes so the app never runs DDL against a database it can't understand, and native-close quits cleanly in recovery mode where no tray exists. (#4575)
+- **Local Proxy Request Overrides (Custom Headers and Body)**: Provider configs can now define custom request headers and request-body overrides that the local proxy applies when forwarding, exposed via a new field in the Claude and Codex provider forms. Inputs are validated, including a protected-header-name list that blocks overriding security-sensitive headers. (#4589)
+- **Volcengine Ark Coding/Agent Plan Usage Query**: Usage panels can now query coding-plan and agent-plan quota for Volcengine Ark. Because the Ark control-plane OpenAPI (`open.volcengineapi.com`) requires account-level AccessKey signing rather than the inference API key, the usage script gains a dedicated AK/SK input block, with a clickable link straight to the Volcengine IAM key-management console (`https://console.volcengine.com/iam/keymanage`), and the proxy implements Volcengine Signature V4 (an AWS SigV4 variant with fixed canonical header order, `HMAC-SHA256` algorithm, and `ark` service scope). It auto-detects the plan by probing `GetAFPUsage` (Agent Plan five-hour/weekly/monthly quotas) before falling back to `GetCodingPlanUsage`, parses the window label from the `Level` field (guarding `ResetTimestamp <= 0`), and adds a `monthly` tier label across the footer, tray menu, and all four locales.
+- **Import Model Pricing from models.dev**: The Add Pricing panel gains an "Import from models.dev" button that fetches `https://models.dev/api.json`, lets users full-text search the catalog, and imports the selected entry through the same `update_model_pricing` path as manual entry. Imported model IDs are normalized to match the backend's `clean_model_id_for_pricing` rules (strip vendor prefix, lowercase, drop `:` suffix, map `@` to `-`, drop the `[1m]` marker) so stored rows actually match cost-attribution lookups. A companion fix makes the scoped zero-cost backfill match raw model aliases (route prefixes, `:free` variants, date suffixes) in Rust instead of by exact SQL string, so newly priced alias rows get costed immediately rather than waiting for the next startup backfill (Fixes #4017). (#4079)
+- **Windows ARM64 Release Builds**: Releases now include native Windows ARM64 artifacts so ARM-based Windows devices get a matching build instead of relying on x64 emulation. The release matrix also runs each platform independently (fail-fast disabled) so a missing-secret failure on one job — e.g. macOS signing in forks — no longer cancels its siblings before they finish. (#3950)
+- **Live End Time for Custom Date Ranges**: The custom date-range picker gains an "End time follows current time" checkbox; when enabled the end time becomes read-only and tracks the current moment, so usage data always reflects up-to-the-second consumption from the chosen start. This is especially useful for watching real-time token use within a Coding Plan 5-hour quota window. `liveEndTime` is included in the React Query cache keys so a live range and a fixed range with the same stored endpoints no longer collide on a stale cache entry. (#4438)
+- **Source File Name in Session Detail Header**: The session detail header now shows the session log's file name (with the full path on hover and click-to-copy) alongside the project directory, so users can locate and open the underlying JSONL file directly from the UI. Long, space-less basenames such as ~70-char Codex rollout files are truncated at `max-w-[200px]` to keep them from overflowing into the action-button area on narrow windows. (#4113)
+- **Unmanaged-Skill Indicator on Import Button**: The top-bar Skills Import button now shows a green dot with a tooltip when local unmanaged skills are available to import, so you can tell at a glance that on-disk skills aren't tracked yet. The scan runs once on mount and is shared across navigations (30s `staleTime` + `keepPreviousData`) to avoid repeated disk IO.
+- **OpenCode Go Subscription Presets**: New OpenCode Go (`opencode.ai/zen/go`) presets for Claude, Codex, and OpenCode, authenticated with a plain pasteable API key (no OAuth). The Codex preset uses `openai_chat` conversion with a GLM/Kimi/DeepSeek/MiMo model catalog (and no static `codexChatReasoning`, so per-model capability is inferred), while OpenCode targets `/zen/go/v1` via `@ai-sdk/openai-compatible`. All four OpenCode Go presets — Claude, Claude Desktop, Codex, and OpenCode — carry a referral link and an in-app promo phrase; the promo banner is now gated on `partnerPromotionKey` alone rather than `isPartner`, so a preset can show a referral promo without earning the gold paid-partner star (this also re-surfaces the existing MiniMax promos).
+- **SubRouter Partner Provider**: Added SubRouter (`subrouter.ai`), an AI relay aggregator that exposes many models and providers behind a single key, as a preset across all seven managed apps — the Anthropic-format endpoint for Claude Code / Claude Desktop / OpenClaw / Hermes, the OpenAI-compatible `/v1` endpoint with `gpt-5.5` for Codex and OpenCode, and the Gemini-compatible `/v1beta` endpoint with `gemini-3.5-flash` for Gemini CLI — carrying its own brand icon, the gold partner star, four-locale promotion copy, and the affiliate registration link (`?aff=l3ri`) prefilled as the API-key signup URL. (#4522)
+- **Prime-Partner Preset Badge and Ordering**: First-party Moonshot Kimi presets (Kimi / Kimi For Coding / Kimi K2.7 Code) are now flagged as prime partners: instead of the gold star, they render a solid gold heart with no badge frame, and in the default (Original) sort they float to the top right after official-category presets, ahead of the rest. Grouping is a three-way partition so each group keeps its internal order and an official preset also flagged prime-partner stays only in the official group.
+- **Pricing for GLM-5.2 and Doubao Seed 2.1**: Seed model pricing now includes GLM-5.2 (#4385) and Doubao Seed 2.1 Pro/Turbo, so usage from these models is cost-attributed correctly instead of recording zero cost. Doubao prices use Volcengine's official list price (CNY converted at ~7.14); `cache_creation` is kept at 0 because Doubao bills cache storage by time rather than per-token writes, and the existing 2.0 rows are retained for historical accounting.
+- **Kimi For Coding Auto-Compact Window**: The Kimi For Coding preset now sets `CLAUDE_CODE_AUTO_COMPACT_WINDOW` to a default of 262144 to match the official Kimi docs, exposed via `templateValues` so users can customize the value for future models or performance tuning. (#4401)
+
+### Changed
+
+- **Native Responses API for CN Codex Providers**: Several Chinese providers (Qwen/DashScope Bailian, Xiaomi MiMo, Volcengine Doubao, Meituan LongCat, MiniMax CN/intl) now expose a native OpenAI Responses endpoint, so their Codex presets switch to `apiFormat: "openai_responses"` and reach the upstream directly instead of going through the Responses->Chat route-takeover conversion. Dropping the now-unused `codexChatReasoning` and `modelCatalog` also keeps the "local route mapping" toggle unchecked by default. SiliconFlow-hosted MiniMax stays `openai_chat` since it is a third-party endpoint rather than MiniMax's own base_url. Stale model ids on the remaining chat-only providers were refreshed as well (GLM 5.1->5.2, StepFun 3.5-flash-2603->3.7-flash, Ling 2.5-1T->2.6-1T).
+- **Decoupled Upstream Format Selector from Model-Mapping Toggle**: The Codex provider form used to tie Chat-format conversion and route takeover (model mapping) to a single toggle, so a provider serving a native Responses API could not use model mapping without forcing Chat Completions conversion. The upstream format (Chat Completions / Responses) is now an independent, always-visible selector, while the local-routing toggle solely gates the advanced sub-sections (model mapping catalog, plus reasoning capability when the format is Chat). Its initial state is derived from saved catalog presence with no new persisted field, and the `codexConfig` i18n strings were reworded across all four locales (zh/en/ja/zh-TW).
+- **Doubao Seed 2.1 Pro Preset**: The DouBaoSeed preset now targets `doubao-seed-2-1-pro` (replacing `doubao-seed-2-0-code-preview-latest`) across all six clients (claude, claude-desktop, codex, opencode, openclaw, hermes), with display names updated to "Doubao Seed 2.1 Pro" and the OpenClaw cost field corrected from 0.002/0.006 to 0.84/4.2 USD per 1M tokens to match the new model.
+- **CTok Rebranded to ETok**: Following the vendor's domain, endpoint, and trademark rename, all user-facing branding moves from CTok to ETok (`ctok.ai` -> `etok.ai`, `api.ctok.ai` -> `api.etok.ai`, internal id, display name, icons, and README partner banners) across every client preset. The Codex history-migration whitelist keeps `ctok` as a legacy id alongside the new `etok` so existing users' local session history stays correctly bucketed after the rename.
+- **Consistent Kimi Preset Naming**: The OpenCode and OpenClaw Kimi presets, previously labeled "Kimi K2.7 Code", are renamed to plain "Kimi" (along with the OpenCode provider display name) to match the other apps; the model label stays "Kimi K2.7 Code" since it describes the actual model.
+- **Dark Mode for JSON Editors**: The CodeMirror `JsonEditor` in the usage-script modal, provider form, and universal provider form now follows the app theme via `useDarkMode()`, switching to the `oneDark` editor theme instead of staying light while the rest of the app is dark. (#4556)
+- **Tighter Add Provider Header With Footer Hint**: The Add Provider dialog reduces the title-to-tabs and tabs-to-card vertical gaps from 24px to 12px and adds an always-visible pinned footer hint guiding users to fill in the fields below after choosing a preset. `FullScreenPanel` gains an optional `contentClassName` prop so the padding override is scoped to this panel without affecting others that share it.
+- **Theme-Adaptive Kimi Logo**: The inline Kimi placeholder mark is replaced with the vendor's refreshed logo. The K glyph uses `currentColor` so it follows the theme text color (dark in light mode, white in dark mode), while the brand accent dot is pinned to the new `#1783FF`, with the metadata fallback color aligned accordingly.
+- **Fable 5 Verified Banner Removed**: The Settings About page no longer shows the Fable 5 Verified commemorative banner that 3.16.3 added beside the app name to mark the special build; the banner image and its markup are dropped, returning the About panel to its standard version-badge layout.
+
+### Fixed
+
+- **Copilot/Codex OAuth Requests Now Honor the Global Proxy**: `CopilotAuthManager` and `CodexOAuthManager` hardcoded `Client::new()` at construction, so their auth flows (token exchange, `/models` listing, model-vendor checks, device-code and OAuth-refresh requests) ignored the configured global proxy and connected directly. With Copilot the direct connection returned zero Claude models, breaking live model resolution and causing the upstream to reject requests with `400 model_not_supported`. Both managers now fetch the shared client per request via `crate::proxy::http_client::get()`, so they follow the global proxy URL and pick up runtime proxy changes. Fixes #2016, #2931. (#4583)
+- **Compressed Request and Error Body Decompression**: Codex Desktop sends zstd-compressed request bodies when authenticated against the Codex backend, which broke local proxy routing because the handlers parsed the raw compressed bytes with `serde_json` directly. The proxy now decompresses request bodies (gzip/br/deflate plus new zstd support, including stacked codings like `gzip, zstd`) before JSON parsing across the three Codex handlers and strips the stale `content-encoding`/`content-length`/`transfer-encoding` headers so the forwarder regenerates them. Upstream non-2xx error bodies are decompressed the same way, so compressed rate-limit and auth details are no longer dropped and hidden from the client. Fixes #3764, #3696. (#3817)
+- **DeepSeek Endpoint `thinking: disabled` 400 Errors**: DeepSeek's Anthropic-compatible endpoint rejects requests where `thinking.type=disabled` coexists with effort parameters, returning HTTP 400, which broke Claude Code 2.1.166+ sub-agents (Workflow/Dynamic Workflow) that hardcode `thinking: disabled`. Rather than overriding the client's intent, the proxy now strips the conflicting `output_config.effort` / `reasoning_effort` parameters for the official DeepSeek endpoint, since sub-agents don't need to display reasoning. (#4239)
+- **Reverted Anthropic System-Message Hoisting**: Reverts #3775's hoisting of `role=system` messages out of `messages[]` into the top-level `system` field for Anthropic-compatible providers. DeepSeek's endpoint accepts inline system messages natively, and the rewrite altered the request prefix; leaving the messages in place preserves the prompt prefix and avoids a suspected cache hit-rate regression (refs #4297). The unrelated Windows test fixes and the tool-thinking-history normalization from #3775 are kept. (#3775)
+- **Chat Tool Calls with Missing Function Names**: Some upstreams send empty or absent function names in streaming tool-call deltas, which previously produced invalid Codex Chat output items (or an `unknown_tool` fallback). Accumulated tool-call state is no longer overwritten by empty deltas, and tool calls that never receive both a `call_id` and a valid name are skipped at finalization across the streaming, non-streaming, and legacy `function_call` paths. (#4159)
+- **Restored Cached Codex Tool Call Fields**: When Codex sends a follow-up Chat request referencing `previous_response_id`, its `function_call` items can arrive carrying only `call_id`. The history enrichment previously refilled only `reasoning`/`reasoning_content`, leaving the function `name`, `arguments`, `status`, and related fields empty; it now restores all cached tool-call fields from history so the call is reconstructed correctly for the Chat upstream. (#4160)
+- **Duplicate Codex base_url Entries in config.toml**: Writing the Codex `base_url` into `config.toml` only replaced or removed a single matching assignment per section, so a section that already contained multiple `base_url` lines kept the extras and accumulated duplicates. `setCodexBaseUrl` now collapses all matches in the target section or top level (replacing the first and removing the rest), and the TOML `base_url` regex handles escaped quotes. (#4316)
+- **CODEX_SQLITE_HOME State DB Probing for History Migration**: The Codex session-history migration only scanned `~/.codex/state_5.sqlite` and the `config.toml` `sqlite_home` location, so when Codex's SQLite state was relocated via the `CODEX_SQLITE_HOME` env var the state DB was never scanned and its threads kept their old provider bucket. The shared `codex_state_db_paths` helper used by both the third-party and unified-session migrations now falls back to `CODEX_SQLITE_HOME` (config `sqlite_home` still takes precedence).
+- **Provider Terminals Respect the User's Shell**: Launching a provider terminal on macOS/Linux hardcoded `bash`, so zsh/fish users' rc files never loaded. The launchers now detect the user's default shell from `$SHELL` (falling back to `/bin/zsh` on macOS, `/bin/bash` on Linux) and exec into it with clean-start flags, while the launch scripts themselves run through POSIX `sh` for portability (e.g. fish, NixOS where `/bin/sh` may not exist). (#4140, fixes #1546)
+- **Claude MCP Path Honors Custom Config Dir**: When a custom Claude config directory is configured, MCP server reads and writes now resolve to that directory's MCP file instead of the default location, keeping MCP state isolated per profile. The previous copy-on-access migration of the legacy file was removed in favor of resolving the override path directly. (#3431)
+- **Preset Search Results Clickable After Searching**: After searching in the Add Provider preset selector, results could no longer be clicked or selected. The `requestAnimationFrame` `select()` that raced with typing (and ate the first character, e.g. "gateway" -> "ateway") is removed, input autofocus is restored for the open-by-click path, and refocus is wired up for the Ctrl/Cmd+F shortcut while the box is open. The provider-list typing guard is also scoped to the Ctrl/Cmd+F branch so Escape still closes the search panel. (#4315)
+- **Skills Browser and Provider Card Display Fixes**: Fixed several display and interaction issues: the repo-manager action stays available while browsing skills.sh and Refresh stays available even when a repo returns no results; long provider names and website URLs on the provider card now truncate instead of overflowing; the OMO model-variant dropdown truncates its selected label with a full-text tooltip; and Select menu items show a checkmark on the active option. (#4323)
+- **Settings Scroll Resets on Tab Switch**: Switching tabs in the Settings dialog kept the previous tab's scroll position, sometimes landing partway down the new tab; the scroll container now resets to the top whenever the active tab changes. (#4165)
+
+### Docs
+
+- **Kimi Pinned Sponsor Banner**: The pinned sponsor banner at the top of all four README locales (en/zh/ja/de) now features Kimi K2.7 Code in place of the previous MiniMax M2.7 banner. The copy reflects the K2.7 Code release (a coding-focused agentic model that reduces thinking-token usage roughly 30% versus K2.6), the banner is served from in-repo assets (`assets/partners/banners/kimi-banner-en.png` / `kimi-banner-zh.png`) instead of the Moonshot CDN, and a clickable call-to-action links to the `aff=cc-switch` Moonshot console.
+- **Codex Unified Session-History Guide**: New trilingual (zh/en/ja) guide for the unified Codex session-history toggle, explaining what opt-in migration (on enable) and ledger-based restore (on disable) actually do, why session data is never truly deleted (tag-only rewrite plus automatic backups), and how to verify files on disk versus merely being filed under another provider drawer. It includes a symptom reference table for the common "my sessions are gone" misunderstanding plus on-disk verification commands for macOS/Linux/Windows, and is linked as the lead item in the v3.16.3 "Usage Guides" release notes.
+- **Simplified Homebrew Install Instructions**: The installation guide no longer instructs users to run `brew tap farion1231/ccswitch` before `brew install --cask cc-switch`; the deprecated tap step was removed from the en/ja/zh user manuals so the cask installs directly. (#4319)
+- **Star-History Global Rank Badge**: Added a star-history global rank badge next to the existing Trendshift badge in all four README locales, with light/dark theme variants.
+- **Volcengine Coding Plan Campaign Link**: The "中国大陆地区的开发者请点击这里" link in the ByteDance/Volcengine sponsor entry now points to the Volcengine `ai618` campaign page instead of the previous `codingplan` referral URL, updated across all four README locales.
+- **CCSub Sponsor Banner Vector Asset**: Replaced the low-res `ccsub.jpg` sponsor logo with a vector `ccsub.svg`, letterboxed from 2046x648 to 2046x850 (~2.406:1) so it matches the other sponsor-table banners and renders at the same 62px height. All four README locales point at the new asset.
+
+## [3.16.3] - 2026-06-14
+
+Development since v3.16.2 focuses on getting usage accounting right end-to-end — billing route-takeover and format-conversion traffic by the real upstream model and pricing basis (schema v11), counting Claude Code Workflow sub-agent sessions, folding Claude Desktop into the Claude view, refreshing the model pricing seed, and reworking the usage dashboard with global provider/model filters, brand-icon toolbars, and far more resilient quota queries — while hardening the proxy (mislabeled SSE bodies, Codex image rectification, OAuth token and takeover-residue recovery, Hermes duplicate YAML keys), reworking provider configuration (a custom User-Agent override, a unified Codex advanced section, searchable preset selection, a Fable 5 tier, and refreshed Kimi/Unity2/Volcengine/MiniMax presets), and smoothing the update, About-panel, and provider-health experiences.
+
+**Stats**: 59 commits | 130 files changed | +10,223 insertions | -4,232 deletions
+
+### Added
+
+- **Custom User-Agent Override**: Provider configs can now set a custom User-Agent that the proxy applies consistently across request forwarding, stream check, and model listing (`GET /v1/models`), so coding-plan upstreams that gate on UA no longer fail detection or return 403 while the proxy itself works. The Claude and Codex forms expose it in advanced settings with a curated presets dropdown (Claude Code / Kilo Code families that pass UA whitelists) and live non-blocking validation; stale custom UAs are dropped when switching to an official preset to avoid silently altering headers (#3671).
+- **Unified Codex Session History**: Official Codex sessions can now share a single resume-history bucket with cc-switch third-party sessions via an opt-in toggle under Settings → Codex App Enhancements, so the resume picker no longer hides them from each other. When enabled, the live `config.toml` routes official runs through a shared `custom` model_provider that mirrors the built-in OpenAI provider (`auth.json` is untouched); the toggle is forward-only by default but the enable dialog offers a checkbox to migrate existing official sessions (with per-generation backups), and the disable dialog offers a precise ledger-based restore that only reverts sessions originally recorded as `openai` while leaving sessions created during the toggle untouched.
+- **Dashboard-Wide Provider/Model Filters**: The provider and model filters move from inside the request-log table up to the top bar, applying globally to the hero summary, trend chart, request logs, and both stats tabs so you can scope the whole dashboard to a given source and model. Sources match by exact display name (so session placeholder rows like "Claude (Session)" are selectable) and models match by effective pricing model, with the model dropdown cascading from the selected source and both lists showing only options that have data in the current range.
+- **Refreshed Model Pricing Seed**: Added pricing for 9 models including Claude Fable 5, Grok 4.3, Mistral Medium 3.5 / Small 4, and Qwen 3.7 Max/Plus, and corrected 28 existing prices against current official vendor list pricing (GLM, Grok, MiMo, Doubao, Kimi, MiniMax, Mistral, Qwen) so usage cost estimates are accurate. Each change updates the seed for fresh installs and adds a guarded repair for existing databases without clobbering user-edited rows.
+- **Claude Fable 5 Model Tier**: Provider forms now expose `claude-fable-5` as a fourth model-mapping tier on both the Claude Code and Claude Desktop proxy paths, with a fable → opus → default fallback mirroring the official downgrade and the `fable-` prefix whitelisted for the Desktop 1.12603.1+ validator. A clarified four-language fallback hint warns that leaving a tier blank on third-party endpoints forwards the literal model name and 404s (#3980, #4026, #4049).
+- **Unity2.ai Partner Provider**: Added Unity2.ai, an AI API relay partner, as a preset across all seven managed apps (Claude Code, Codex, Gemini, OpenCode, OpenClaw, Claude Desktop, Hermes), each carrying the referral signup link and partner promotion copy in all four locales. Codex uses the bare base URL (the gateway exposes `/responses` at root) while OpenCode / OpenClaw / Hermes use the `/v1` chat-completions endpoint with `gpt-5.5`.
+- **Kimi K2.7 Code Model**: Added the `kimi-k2.7-code` model (in $0.95 / out $4.00 / cache-read $0.19 per 1M tokens, 256K context) and pointed all six official Moonshot Kimi presets (Claude Code, Codex, Claude Desktop, Hermes, OpenCode, OpenClaw) at it, renaming the OpenCode / OpenClaw presets to "Kimi K2.7 Code". The pricing seed applies on startup via the idempotent insert path, so existing users pick up the new pricing without a migration.
+- **Codex "Kimi For Coding" Preset Restored**: Re-added the Codex "Kimi For Coding" preset (`openai_chat`, `kimi-for-coding`, 256K context) with thinking mode enabled by default; it was previously removed because the coding endpoint rejects Codex's default `codex-cli` User-Agent with 403. It now works via proxy takeover combined with the custom User-Agent override (set to a whitelisted UA such as `claude-cli/*`).
+- **Pricing-Model Audit in Request Detail**: The request detail panel now shows the requested model and the pricing model when they differ from the response model, making route-takeover bills auditable directly from the usage UI.
+- **Preset Provider Search & Sorting**: The provider preset selector gains a searchable, sorted list with an inline search box (toggled via a magnifier icon, dismissed on ESC or outside click). Buttons use a responsive grid with consistent sizing and default icons, and search matches only provider display/raw names so URL fragments and shared category labels no longer produce noisy matches (#3975, #4183).
+- **Claude Mythos 5 Pricing**: Registered the `claude-mythos-5` model in the bundled model/pricing table (in $10 / out $50 per 1M tokens, cache read $1.00, cache write $12.50), so usage metering prices and displays it correctly (#4077).
+- **Fable 5 Verified Banner**: The Settings About page now displays a Fable 5 Verified banner beside the app name and version, marking this as a special build, with the version badge centered under the app name.
+
+### Changed
+
+- **Claude Desktop Usage Folded Into Claude**: The dashboard no longer shows a standalone "Claude Desktop" bucket, which only ever displayed a partial number (Desktop chat usage never passes through the proxy and its Code-tab sessions write into the shared `~/.claude/projects` tree). Desktop proxy traffic is now folded into the `claude` view for display while still recorded under its own `app_type` for route-takeover billing audit, with the real value visible in the request detail panel.
+- **Lightweight Provider Health Check**: The provider health check no longer sends a real streaming model request (which many third-party providers blocked with 401/403/WAF, causing false negatives); it now performs a lightweight HTTP reachability probe of the provider `base_url`, treating any HTTP response as reachable and counting only DNS/connect/TLS/timeout as failure. The connectivity button is hidden for official providers (which use OAuth with an empty base URL and no reliable reachability target), the real-request confirmation dialog and test model/prompt fields are removed, and the degraded-latency threshold is set to 6s with an 8s timeout. The reachability check never resets the circuit breaker, so failover detection stays driven solely by real proxy traffic.
+- **Codex Advanced Options Section**: The Codex provider form now folds local routing, model mapping, reasoning overrides, and custom User-Agent into a single collapsible advanced section mirroring the Claude form (auto-expanding when a UA is set or local routing is on). Custom User-Agent is now also configurable for native Responses providers, where it was previously reachable only with `openai_chat` routing enabled.
+- **Usage Toolbar Refresh and Layout**: The app filter now renders brand icons (via ProviderIcon, with a grid icon for "All") instead of text tabs that wrapped awkwardly in narrow windows, and the usage hero shows the selected app's brand icon with Codex recolored to a neutral gray matching OpenAI's monochrome branding. The click-to-cycle refresh button becomes a Select with a localized "off" label, and the top-bar controls are compacted and aligned into consistent width groups with truncated long date-range labels.
+- **Faster About Panel Loading**: The Settings About panel now loads progressively: the app version badge appears the instant it resolves instead of waiting for tool probes, each tool card updates the moment its own version check finishes (probes run concurrently rather than sequentially), and results are cached for the app session with a 10-minute TTL so reopening the About tab reuses cached values and revalidates stale ones in the background instead of re-probing all six tools every time.
+- **Volcengine Ark Coding Plan Promo**: Updated the Volcengine Ark preset across all six apps with the new Coding Plan invite link (replacing the old Agent Plan / activity links) and refreshed the partner promotion copy in all four locales (two-month 75% off plus invite code 6J6FV5N2), correcting the product name from Agent Plan to Coding Plan.
+- **MiniMax Demoted to Regular Provider**: Removed the gold partner star badge and the API-key promotion banner for MiniMax by dropping the `isPartner` flag from all its presets; it stays as a regular `cn_official` provider keeping its icon and theme. The promotion copy is kept dormant so the partnership can be re-enabled with a single line.
+- **LemonData Removed, SudoCode Demoted**: Removed the LemonData provider preset entirely from all apps along with its promotion copy, icons, and sponsor listings, and demoted SudoCode from a partner to a regular `third_party` provider by dropping its `isPartner` flag and promotion copy (it keeps its icon).
+- **AtlasCloud Codex GLM 5.1 Context Window**: Declared the 200,000-token context window for the `zai-org/glm-5.1` model in the AtlasCloud Codex preset, matching the other GLM 5.1 preset entries.
+
+### Fixed
+
+- **Route-Takeover Traffic Billed by the Real Upstream Model**: When a request was routed to a different upstream (env model mapping, Claude Desktop routes, Copilot normalization, Codex chat override), the proxy used to attribute and price usage by whatever model the upstream echoed back, recording kimi/glm tokens as `claude-*` and overstating cost roughly 5–25×. The forwarder now captures the real outbound model, attributes usage by upstream-echo then outbound then client alias, persists the actual pricing basis on every row (schema v11), and keeps that basis through cost backfill and 30-day rollup pruning; Claude Desktop traffic is now logged under its own `app_type` so its pricing overrides apply.
+- **Usage Metering on Format-Conversion Proxy Paths**: Audited and fixed token/cache accounting across the proxy's format-conversion paths (Chat, Responses, and Gemini converted to Anthropic). The proxy now records the actually returned model, injects `stream_options.include_usage` so OpenAI-compatible upstreams emit usage in streaming, excludes `cache_read` and `cache_creation` from input on Claude←OpenAI paths to stop double-billing cache tokens, subtracts cached Gemini prompt tokens, still records fully-cached requests, and skips synthetic all-zero usage that previously inflated request counts (#2774).
+- **In-App Update No Longer Hangs on Restart**: Installing an update from within the app no longer freezes on the "restarting" screen, leaving the new version installed but requiring a manual force-quit. The download-install-restart chain now runs entirely in the backend (a new `install_update_and_restart` command) with platform-aware install ordering and single-instance-lock teardown before re-exec, instead of depending on the old WebView to keep running JS after the app bundle was already swapped; exit requests are also classified so restart requests fall through to Tauri's default flow rather than deadlocking on the window-state plugin mutex (#4069, #4074).
+- **Codex Upgrade No Longer Breaks the Install**: Upgrading Codex from the Settings "About" tab no longer leaves it throwing "Missing optional dependency @openai/codex-…" errors. The upgrade chain previously ran `codex update` first, which on an npm install is a bare reinstall that reports success even when the per-platform binary fails to land; Codex is now removed from the self-update-first path and a runnable check triggers an uninstall+reinstall self-heal (scoped to npm-managed installs) that actually re-lands the missing platform binary.
+- **Codex OAuth Auth Token Preserved on Proxy Takeover**: Enabling proxy takeover for a Codex provider no longer strips the `ANTHROPIC_AUTH_TOKEN` placeholder, which previously broke Claude Code's login on hot-switches, fresh installs, and configs already stripped by older releases. The placeholder is now injected unconditionally for managed (non-Copilot) Codex providers, including URL-only ones; GitHub Copilot behavior (API_KEY only) is unchanged (#3789, #3784).
+- **Takeover-Residue Recovery Across Config-Dir Switches**: Restarting the app after changing the config directory while proxy takeover is active no longer leaves Claude/Codex/Gemini pointed at a dead local proxy. The old instance now restores the taken-over live files before restarting, the first-run import refuses to persist a takeover placeholder as a provider, and SSOT restore validates that the current provider's config is free of placeholders before writing it back (#4076).
+- **Mislabeled SSE Bodies in Format-Transform Fallback**: Requests routed through Claude/Codex format conversion no longer fail with an opaque 422 "Failed to parse upstream response" when a MaaS gateway force-streams a `stream:false` request and returns an SSE body under a non-SSE Content-Type. The proxy now sniffs for SSE on parse failure, aggregates the chunks into a single JSON, and runs the existing converter so clients still get a valid non-stream response; remaining parse failures are enriched with content-type, encoding, and body-snippet diagnostics, and deflate decoding now tries zlib before raw (#2234).
+- **Duplicate YAML Keys in Hermes Config**: Hermes config writes no longer accumulate duplicate top-level keys (e.g. `mcp_servers`) that caused "Failed to parse Hermes config as YAML: duplicate entry with key" errors. Section replacement now strips all stale occurrences from the remainder instead of degrading into appends, the dedup safety net handles both LF and CRLF line endings, and healing keeps the last (newest) occurrence to match Hermes's own last-wins PyYAML semantics (#3267, #3633, #2973, #2529, #3310, #3762).
+- **Usage Query Resilience and Error Clarity**: Usage cards no longer flip to red on a single transient blip: queries now retry once and keep showing the last successful result for up to 10 minutes on network/timeout/5xx failures, while deterministic failures (auth, empty key, unknown provider, 4xx) surface immediately and clear the snapshot so a stale quota can't resurface after credentials change. Native balance/coding-plan/subscription timeouts were raised from 10s to 15s for slow cross-border endpoints, and coding-plan now returns explicit "API key is empty" / "Unknown coding plan provider" errors instead of a blank failure.
+- **Usage Script Provider Credential Resolution**: Custom JS-script usage queries resolved `{{apiKey}}` / `{{baseUrl}}` by guessing env fields only, so providers that store credentials elsewhere (e.g. Codex's `auth.OPENAI_API_KEY` plus `config.toml` base_url) always got empty values and failed despite being fully configured. Script queries and the test/preview now reuse the same per-app credential resolver as the native balance path, with explicit non-empty script values still taking precedence (#1479).
+- **Claude Code Workflow Sub-Agent Usage Counted**: Local (no-proxy) session-log usage accounting missed Claude Code Workflow sub-agent traffic, under-counting overall usage by roughly 4.1% (concentrated in workflow/subagent transcripts). The scanner now descends into the deeper `subagents/workflows/wf_*/` transcript directories, and the parser no longer drops billable assistant messages that lack a `stop_reason` but already incurred input/cache token cost; dedup is unchanged so no usage is double-counted.
+- **Codex Image Rectifier for /responses Text-Only Upstreams**: Codex `/responses` requests carrying images and routed to text-only OpenAI-chat models (e.g. DeepSeek `deepseek-v4-flash`) no longer fail with HTTP 400 "unknown variant `image_url`". The media rectifier now also covers the Codex adapter, scanning the responses `input` for `input_image` blocks so it can proactively strip images for known text-only models and reactively retry with images replaced on upstream image-unsupported errors.
+- **Zhipu Coding-Plan Quota Window Mislabeling**: The Zhipu coding-plan view no longer swaps the 5-hour and weekly quota buckets in the final hours of each weekly cycle. The two windows are now classified by the explicit `unit` field (3 = 5-hour, 6 = weekly) instead of by sorting reset-time ascending, which mislabeled them exactly when users check their weekly quota most; the old reset-time heuristic remains as a fallback (#3036).
+- **Duplicate Provider Terminal Sessions on macOS**: Launching a provider terminal on macOS no longer opens an extra empty window alongside the command session; Terminal.app uses `launch` (not `activate`) on cold start and Ghostty uses an initial-command so a single session opens, with a fallback retained if the AppleScript path fails (#4156).
+- **Claude Desktop Model-Mapping Placeholders**: The Claude Desktop model-mapping form previously showed mismatched example brands across the menu display name and request model columns (DeepSeek vs Kimi), implying a display name maps to an unrelated model. Both placeholders are now derived from each row's role so they stay brand-consistent, with the lightweight Haiku tier using a flash example.
+- **Popovers Behind Fullscreen Panels**: Popovers and tooltips such as the provider preset search no longer render behind fullscreen panels and appear unresponsive on click; their z-index is raised above the fullscreen overlay while staying below modal dialogs.
+- **ToggleRow Icon Shrinking**: Toggle row icons no longer shrink or distort when paired with long descriptions, keeping the icon at a fixed size next to multi-line text.
+
+### Docs
+
+- **Release Notes Contributor Mentions**: Restored contributor mentions in the v3.16.1 and v3.16.2 release notes across all three locales.
+
+## [3.16.2] - 2026-06-07
+
+Development since v3.16.1 focuses on broadening data portability and usage observability — S3-compatible cloud sync, OpenCode session usage import, and an opt-in official-subscription quota template — while hardening Codex Chat Completions routing (stream truncation, `tool_choice` / custom-tool / reasoning-token edge cases, file and audio attachments, and a Codex CLI models endpoint), strengthening proxy robustness (ephemeral ports, takeover/placeholder restore, system-message normalization, clearer upstream errors, and a text-only image fallback), fixing coding-plan quota lookups (Zhipu, MiniMax) and several Windows/macOS issues, adding the CherryIN and ZenMux providers, and refreshing the user manual.
+
+**Stats**: 41 commits | 132 files changed | +11,116 insertions | -1,636 deletions
+
+### Added
+
+- **S3-Compatible Cloud Sync**: Cloud Sync now supports S3-compatible object storage as a second backend alongside WebDAV, using hand-rolled AWS Signature V4 signing for broad compatibility. The settings panel offers one-click presets for AWS S3, MinIO, Cloudflare R2, Alibaba Cloud OSS, Tencent Cloud COS, and Huawei OBS plus a custom endpoint, with connection testing, manual upload/download, and auto-sync on configuration changes (provider, endpoint, MCP, prompt, skill, settings, and proxy tables — not high-frequency data like usage logs); enabling S3 sync disables active WebDAV sync and vice versa (#1351).
+- **OpenCode Session Usage Sync**: Added OpenCode as a usage-statistics source that imports per-message token, cost, and model data from OpenCode's local SQLite database, with a new "OpenCode" app filter tab and an "OpenCode Session" data-source label. The database path respects `OPENCODE_DB` and `XDG_DATA_HOME` (defaulting to `~/.local/share/opencode` on all platforms), only finalized messages are imported, and the freshness check accounts for the WAL file so newly written sessions are not skipped (#3215).
+- **Official Subscription Quota Template**: Added an explicit, opt-in "official subscription" usage template for Claude, Codex, and Gemini official providers that queries plan quota via CLI/OAuth credentials, replacing the previous implicit auto-query. It is disabled by default and enabled from the usage-script modal with a configurable refresh interval.
+- **Unsupported Image Fallback Rectifier**: Added a proxy rectifier that replaces Anthropic image blocks with an `[Unsupported Image]` marker when the routed model is text-only (declared, or detected via a built-in model-name heuristic) or when the upstream rejects image input, so conversations are not interrupted. A new Settings toggle controls the fallback, with a separate toggle for the heuristic detection.
+- **ZenMux Token Plan Provider**: Added ZenMux as a Token Plan coding-plan provider that accepts a manually entered API key and base URL in the usage-script modal and renders its quota with USD-denominated used / limit values (#2709).
+- **CherryIN Preset**: Added the CherryIN aggregator gateway as a quick-config preset across all seven supported apps — Anthropic-format endpoint for Claude Code / Claude Desktop / OpenClaw / Hermes, `@ai-sdk/anthropic` for OpenCode, the OpenAI-compatible endpoint for Codex, and the Gemini-compatible endpoint for Gemini CLI — with the official brand icon, placed next to AiHubMix (#3643).
+- **CCSub Preset**: Added CCSub, a multi-model aggregator partner, as a quick-config preset across six apps — Claude Code, Claude Desktop, Codex, OpenCode, OpenClaw, and Hermes — with the official brand icon and the partner referral link prefilled as the API-key signup URL (`gpt-5.5` for the OpenAI-compatible Codex and OpenCode endpoints).
+- **Codex CLI Models Endpoint**: The local proxy now answers `GET /v1/models`, which Codex CLI probes at startup, returning the cc-switch-managed Codex model catalog. A stale-catalog guard parses the live `config.toml` and only serves the catalog when `model_catalog_json` still references the cc-switch-owned file, so a leftover catalog from a previous provider is not advertised (#3818).
+- **Codex Chat File and Audio Attachments**: The Codex Responses-to-Chat converter now maps `input_file` parts (carrying `file_id` or inline `file_data`) and `input_audio` parts into their Chat Completions equivalents, and emits top-level `input_*` items that were previously dropped, so file and audio attachments reach Chat-only Codex upstreams.
+
+### Changed
+
+- **Usage Dashboard Hero Redesign**: Restructured the Usage Dashboard hero and summary cards into a more compact layout, consolidating the real-token total, request count, and cost into a single top row (#3426).
+- **SSSAiCode Endpoint Refresh**: Updated the SSSAiCode preset's website, signup, and API base URLs to the `sssaicodeapi.com` domain and refreshed its endpoint nodes (default `node-hk.sssaicodeapi.com`, plus `node-hk.sssaiapi.com` and `node-cf.sssaicodeapi.com`) across all seven app presets.
+
+### Fixed
+
+- **Codex Chat Truncated Stream Detection**: When a Chat Completions upstream ends a stream without a `finish_reason` or `[DONE]`, CC Switch no longer reports it as a normal completion — it finalizes normally only when the stream truly finished, emits an incomplete (`max_output_tokens`) response when partial output was produced, and emits a failed `stream_truncated` event when nothing was produced. Late-arriving reasoning is also attached to still-active streamed tool calls.
+- **Codex Chat `tool_choice` Without Tools**: The Responses-to-Chat converter now drops `tool_choice` and `parallel_tool_calls` whenever the resulting tools array is absent or empty, so strict OpenAI-compatible upstreams (vLLM, enterprise gateways) no longer reject the request with "When using `tool_choice`, `tools` must be set." (#3640).
+- **Codex Custom Tool Metadata Over Chat Routing**: Custom Codex tools (such as the freeform `apply_patch` tool) now preserve their full original definition — including format and grammar metadata — as a compact, order-stable JSON block in the generated Chat function description instead of a generic placeholder, keeping them usable on Chat Completions upstreams (#3644).
+- **Codex Chat `reasoning_tokens` in Usage**: The Chat-to-Responses usage conversion now always includes `output_tokens_details.reasoning_tokens` (defaulting to 0), even when a provider omits `completion_tokens_details` or returns it as a non-object, satisfying the Codex CLI's strict requirement and avoiding repeated parse failures and retries (#3514).
+- **Codex Cross-Turn Reasoning for Custom and Search Tools**: The cross-turn reasoning cache in Codex Chat history now covers the full tool-call set (`function_call`, `custom_tool_call`, `tool_search_call`) and their outputs, so `apply_patch` and tool-search calls keep their `reasoning_content` when restored via `previous_response_id`.
+- **Ephemeral Proxy Port Resolution**: When the proxy listens on port 0 (OS-assigned), takeover now starts the proxy first to learn the real port and writes it into the Live configs and database, so client URLs no longer point at a broken `:0` address; the Claude Desktop gateway URL is rejected if no concrete port has been resolved.
+- **Proxy Placeholder Backup/Restore Loop**: If a previous proxy stop left the proxy placeholders in Live, taking over again no longer overwrites a good backup with the proxy config, and restore no longer writes the placeholder back to Live — both paths detect the placeholder state and rebuild Live from the current provider, fixing cases where the proxy toggle became a no-op and clients stayed pinned to the local proxy (#3689).
+- **Official Provider Block Under Proxy Takeover**: While Local Routing takeover is active, only providers explicitly categorized as official are blocked from switching, instead of also disabling custom providers whose endpoint lives in metadata or whose fields are unfilled. The disabled Enable button now shows a lighter hint tooltip in place of the red "Blocked" badge.
+- **Localhost Listen Address Normalization**: Saving the proxy with a listen address of `localhost` now normalizes it to `127.0.0.1` before persisting, avoiding binding inconsistencies (#3016).
+- **Anthropic System Message Normalization**: For Anthropic-format providers, system-role entries inside the `messages` array are collapsed and merged into the top-level `system` field (preserving order and any existing top-level system), preventing strict upstreams from rejecting non-leading system messages; OpenAI Chat routing is untouched (#3775).
+- **Claude Desktop 1M-Context Model Routing**: Claude Desktop appends a `[1m]` marker to the model name when the 1M-context beta is active (e.g. `claude-opus-4-8[1m]`). The proxy now strips that suffix before route lookup so exact, alias, legacy, and role-keyword matching resolve correctly, fixing `route_unknown` (HTTP 400) failures when switching to a 1M-capable model mid-conversation.
+- **Codex 413 Error Clarity**: When a Codex upstream gateway rejects an oversized request with HTTP 413, the proxy now returns a dedicated message identifying it as the provider's server-side body-size limit (not a CC Switch limit) with recovery steps (run `/compact`, drop large logs or inline images, or ask the provider to raise its limit), instead of echoing the raw upstream HTML page.
+- **Proxy Panel Error Detail**: When toggling proxy takeover fails, the proxy panel toast now includes the underlying backend error detail instead of only a generic failure message (#3656).
+- **Copilot Infinite-Whitespace Threshold**: Raised the streaming infinite-whitespace abort threshold from 20 to 500 consecutive whitespace characters, so legitimate tool calls with deeply indented code arguments are no longer falsely aborted while still catching the real Copilot infinite-whitespace bug (#2647).
+- **Subscription Tier Tray Rendering**: Fixed tray and quota rendering for official subscription tiers via a unified tier-to-label mapping: Claude/Codex no longer drop the seven-day window, Gemini Pro/Flash/Flash-Lite tiers no longer leak raw machine names, and multi-window plans (e.g. Opus + Sonnet) now display the worst utilization instead of the first match.
+- **Inflated Claude Stream Input Tokens**: Some Anthropic-compatible streaming providers (e.g. Qwen, MiniMax) report the full context as `input_tokens` in `message_start`, double-counting the cached portion and artificially lowering the displayed cache hit rate. The parser now prefers a smaller positive `input_tokens` from `message_delta` and adopts the paired cache counts from the same usage block; native Claude and OpenRouter-converted paths are unchanged.
+- **Zhipu Quota Query Endpoint Routing**: The Zhipu coding-plan quota lookup was hard-coded to `api.z.ai`, so users on the mainland China preset (`open.bigmodel.cn`) could not retrieve usage when the international endpoint was unreachable. The quota request now routes to the host matching the user's configured base URL (#3702).
+- **MiniMax Balance API and Pricing**: Adapted MiniMax coding-plan quota to its new balance API (which returns remaining-percent fields instead of usage counts that broke the old parser and left the tray blank), filtered out non-coding models (e.g. video), handled plans without a weekly limit, and seeded default pricing for MiniMax M3 (#3518).
+- **GLM Coding Plan Endpoints and Model Fetch**: Corrected the ZhiPu / Z.AI GLM Coding Plan presets to the `/api/coding/paas/v4` endpoints across Codex, OpenCode, OpenClaw, and Hermes, and taught the model-list probe to query `{base}/models` for base URLs that already end in a `/v{N}` segment (keeping `/v1/models` as a fallback), so the Fetch Models button no longer 404s on versioned endpoints (#3524).
+- **Codex Model Catalog Path Portability**: Codex now writes only the relative filename `cc-switch-model-catalog.json` to `config.toml` instead of an absolute path (Codex CLI resolves it from the config directory), fixing the model catalog breaking on WSL and symlinked setups where the absolute path could not be translated (#3614).
+- **APINebula OpenCode SDK**: The APINebula OpenCode preset now loads `@ai-sdk/openai-compatible` instead of `@ai-sdk/openai`, so requests use the OpenAI Chat Completions format the relay expects rather than the Responses API.
+- **Windows Tray Icon Residue on Exit**: Quitting CC Switch on Windows could leave a dead tray icon until hovered; the app now removes the tray icon before exiting so it disappears cleanly (#3797).
+- **Windows Taskbar Icon**: Set an explicit Windows AppUserModelID at runtime and stamped the installer's desktop and start-menu shortcuts with the same ID and product icon, so CC Switch shows the correct icon and groups properly in the taskbar (#3457).
+- **Windows Subdirectory Skill Updates**: Normalized backslash path separators to forward slashes when scanning installed skills on Windows, so skills nested in subdirectories (e.g. `skills/my-skill`) are matched by the update check instead of being silently skipped (#3430).
+- **macOS Input Auto-Capitalization**: Disabled autocomplete, autocorrect, autocapitalize, and spellcheck on the shared text Input component so macOS no longer auto-capitalizes or auto-corrects the first letter typed into configuration fields (#3626).
+- **Codex VS Code Session Previews**: Codex session previews for requests sent from VS Code could show selection or open-file content instead of the prompt when a markdown heading preceded the injected request. Both the backend title and frontend preview now match the last "## My request for Codex:" heading (the IDE injects the real request as the final section) (#3593).
+- **VS Code Wording in Chinese UI**: Corrected the "Apply to Claude Code plugin" description in the Simplified and Traditional Chinese locales to write "VS Code" properly instead of "Vscode", aligning with the English and Japanese strings (#3228).
+
+### Docs
+
+- **User Manual Refresh**: Refreshed the README locales and the en / zh / ja user manuals to reflect all seven supported apps (adding Claude Desktop and Hermes), corrected the OpenCode config path to `~/.config/opencode/` (`opencode.json`), documented Hermes configuration files, updated the language docs to four languages, revised per-app MCP / Prompts / Skills availability, noted that export produces a timestamped SQL backup including usage logs, and documented the pricing model-ID matching rules (#3411).
+- **Codex Official Auth Preservation Guide**: Added a trilingual (en / zh / ja) guide explaining how to keep Codex official remote control and plugins working while routing model traffic to third-party APIs, and linked it from the v3.16.1 release notes.
+- **README Release-Note Links and Sponsor Markup**: Updated the Release Notes links in all README locales to point at v3.16.1 and fixed broken smart-quote characters in the README_ZH sponsor blocks so their HTML attributes render correctly (#3772).
+
+## [3.16.1] - 2026-06-01
+
+Development since v3.16.0 focuses on hardening Codex provider switching and Local Routing takeover: preserving official OAuth auth and model catalogs across normal switches, hot-switches, backup restore, and edit flows; restoring Codex Chat tool/plugin compatibility over Chat Completions upstreams; improving Codex proxy diagnostics and CLI discovery; and documenting DeepSeek routing.
+
+**Stats**: 23 commits | 62 files changed | +5,603 insertions | -1,113 deletions
+
+### Added
+
+- **Codex Official Auth Preservation Setting**: Added an opt-in setting that keeps the official ChatGPT / Codex OAuth login in `auth.json` when switching third-party Codex providers, while moving third-party provider tokens into `config.toml` when enabled.
+- **Codex DeepSeek Routing Guides**: Added localized DeepSeek routing guides for Codex in English, Chinese, and Japanese, with screenshots covering provider routing requirements, Codex provider setup, and Local Routing takeover.
+
+### Changed
+
+- **Codex Auth Preservation Is Opt-In**: The new official-auth preservation setting now defaults to off, so third-party Codex switches keep the legacy behavior of writing the active provider auth unless users explicitly enable preservation.
+- **Codex Provider Switch Restart Hint**: Successful Codex provider switches now tell users to restart the Codex client so catalog and config changes take effect.
+- **Codex Proxy Takeover Switching Is Serialized**: Provider switches and takeover toggles now share a per-app lock and use backup / live placeholder ownership signals instead of lagging `enabled` or server-running flags, preventing normal live writes from racing a just-activated or temporarily stopped takeover.
+- **Codex Takeover Hot-Switch Display Refresh**: Hot-switching a Codex provider while Local Routing owns Live now refreshes the proxy-safe live provider id, model, and display name while keeping endpoints pointed at the local proxy.
+- **Sponsor Ordering**: Swapped the Shengsuanyun and AICodeMirror sponsor blocks across README locales.
+- **Docs Organization**: Moved the Chinese proxy guide under `docs/guides/` and removed the obsolete working-directory plan document.
+
+### Fixed
+
+- **Codex Provider Edit Dialog Under Takeover**: The Codex provider edit form now shows an explicit notice and storage-aware auth / config hints clarifying that it displays the stored provider config (not the proxy-managed live `auth.json` / `config.toml`), so the official OAuth token is no longer mistaken as lost while takeover is active. The dialog also treats takeover as active regardless of whether the proxy server is currently running.
+- **Codex OAuth Auth During Proxy Takeover**: Fixed multiple preserve-mode takeover paths that could clear or overwrite the official ChatGPT / Codex OAuth `auth.json`. Takeover detection now recognizes `PROXY_MANAGED` in `config.toml`, cleanup only removes placeholder bearer tokens, config-only takeover writes are used consistently, and mis-categorized third-party providers no longer trigger the official-provider auth overwrite path. Provider sync and switching now treat the restore backup and live placeholders as the takeover-ownership signal (instead of the lagging `enabled` / proxy-running flags) and serialize switch/takeover per app, so a just-activated or proxy-stopped takeover can no longer be overwritten by a normal live write.
+- **Codex Model Catalog Data Loss**: Fixed cases where Codex `modelCatalog` could be wiped by live-config backfill, active-provider edit dialogs, provider switches, or proxy takeover-off restore. Snapshot backups now keep existing `model_catalog_json` pointers, provider-rebuilt backups regenerate the catalog projection from the database source of truth, active edit dialogs prefer the DB catalog over lossy Live reconstruction, and provider switches always refresh the generated catalog JSON.
+- **Codex Chat Tools Over Chat Completions Routing**: Restored Codex `tool_search`, loaded namespace tools, custom tools, and tool outputs when third-party Codex providers are routed through Chat Completions. Non-streaming and streaming Chat responses now map back to the right Responses item types, including native `response.custom_tool_call_input.*` events for custom-tool streaming.
+- **Codex Proxy Error Diagnostics**: Codex forwarding failures now return richer JSON errors with provider, model, endpoint, upstream status, stable `cc_switch_*` codes, and HTTP statuses aligned with the canonical `ProxyError` response mapping.
+- **Codex Native Balance / Coding-Plan Queries**: Fixed native usage and plan lookups so each app resolves the correct provider credentials instead of leaking assumptions from another app surface.
+- **Codex CLI Discovery and Catalog Projection**: Fixed third-party Codex catalog projection that could fail when the Codex CLI was not reachable through one narrow PATH lookup, by adding multi-platform CLI discovery plus a bundled GPT-5.5 model-catalog template fallback.
+- **Claude Desktop Official Provider Creation**: Fixed adding the Claude Desktop Official provider when the official category/config path was selected.
+- **Anthropic Tool Thinking History for Kimi / Moonshot**: Added Kimi and Moonshot to the Anthropic-compatible tool-thinking history normalizer so later turns can replay reasoning and tool-call context correctly.
+- **Windows Tool Version Probing**: Fixed Windows version checks that could misquote `.cmd` / `.bat` commands and decode localized command output as mojibake, causing working tools to appear as "installed but not runnable".
+
+## [3.16.0] - 2026-05-29
+
+Development since v3.15.0 focuses on making third-party Codex providers work like first-class citizens through Chat Completions routing, stabilizing Codex provider identity and history, adding an in-app managed CLI tool lifecycle, expanding the partner preset catalog, refreshing the default model / pricing matrix around GPT-5.5 and Claude Opus 4.8, and improving usage observability, localization, docs, and proxy robustness.
+
+**Stats**: 101 commits | 221 files changed | +27,063 insertions | -3,052 deletions
+
+### Highlights
+
+- **Codex Chat Completions routing**: Codex providers can now be served by OpenAI-compatible Chat Completions upstreams. CC Switch converts Codex Responses requests into Chat Completions, rebuilds JSON and SSE responses back into Responses shape, preserves reasoning / `<think>` / tool-call state, normalizes error envelopes, and probes Chat-format providers correctly in Stream Check.
+- **Codex third-party provider state is unified and safer**: third-party Codex providers now share the stable `custom` model-provider bucket, with a one-shot migration for historical JSONL sessions and `state_5.sqlite` threads, plus fixes that preserve OAuth login state, user-selected catalog models, and user-authored provider ids during live reads / switches.
+- **Managed CLI tool management**: the About page is now a tool management panel for Claude, Codex, Gemini, OpenCode, OpenClaw, and Hermes, with install / update actions, update-all, conflict diagnostics, source-aware anchored upgrades, WSL handling, and visible "installed but not runnable" states.
+- **Provider ecosystem and model matrix refresh**: added APIKEY.FUN, APINebula, AtlasCloud, SudoCode, Xiaomi MiMo Token Plan, and Claude Desktop Official presets; refreshed partner links and default models / pricing across apps; upgraded the default Claude Opus model line to 4.8 and GPT defaults to 5.5 where applicable.
+- **Usage and docs polish**: Usage Dashboard updates now react immediately when logs are written, custom usage-script summaries and subagent session-log accounting were fixed, Traditional Chinese UI localization landed, and a German README plus expanded Claude Desktop / Codex Chat / tool-management manuals were added.
+- **Proxy and conversion hardening**: fixed Codex Chat reasoning / cache / usage edge cases, DeepSeek Anthropic tool-thinking history, Claude-compatible empty `tool_calls` streams, managed-account takeover auth, MiMo reasoning output, Gemini Native tool-call replay, and several panic-prone proxy paths.
+
+### Added
+
+- **Codex Chat Completions Routing**: Codex providers can now be served by upstreams that only speak the OpenAI Chat Completions API. CC Switch's local proxy converts Codex's outgoing Responses requests into Chat Completions and rebuilds the Chat response (both JSON and SSE) back into Responses shape, preserving `reasoning_content`, inline `<think>` blocks, streamed reasoning summaries, tool calls, and `previous_response_id` follow-ups. A bounded Codex Chat history cache restores tool calls before their tool outputs.
+- **22 Codex Third-Party Provider Presets with Chat Routing**: Enabled Chat Completions routing with explicit model catalogs for major Chinese/Asian providers — DeepSeek, Zhipu GLM (+ en), Kimi, MiniMax (+ en), StepFun (+ en), Baidu Qianfan Coding Plan, Bailian, ModelScope, Longcat, BaiLing, Xiaomi MiMo (+ Token Plan), Volcengine Agentplan, BytePlus, DouBao Seed, SiliconFlow (+ en), Novita AI, and Nvidia. Each preset declares its context window so the UI can size the model-mapping rows.
+- **Codex Model Mapping Table**: Codex provider forms now expose a model catalog (model + display name + context window per row) that is the single source of truth for the upstream model list, projected to `~/.codex/cc-switch-model-catalog.json`.
+- **Codex Chat Providers in Stream Check**: Stream Check now probes Chat-format Codex providers against `/chat/completions` with a Chat-shaped body instead of `/v1/responses`, and aligns its URL fallback order with the production `CodexAdapter` (origin-only base URLs hit `/v1/<endpoint>` first) so a non-404 error on the bare path no longer flags a working provider as down.
+- **Codex Chat Reasoning Auto-Detection**: When a Codex provider is served through Chat Completions routing, CC Switch now auto-detects the upstream's reasoning interface from its name, base URL, and model — injecting the correct thinking parameter (`thinking:{type}`, `enable_thinking`, `reasoning_split`, top-level `reasoning_effort`, or OpenRouter's native `reasoning:{effort}` object) with no manual setup. Aggregator/hosting platforms (OpenRouter, SiliconFlow) are matched platform-first, since the same model can expose different reasoning controls on different platforms. Providers that only expose a thinking on/off switch (Kimi, GLM, Qwen, MiniMax, MiMo, SiliconFlow) drop the effort *level* instead of forwarding an unsupported field — so changing Codex's reasoning effort has no effect for them — while providers with real effort tiers (DeepSeek, OpenRouter, and StepFun's `step-3.5-flash-2603` only) pass the level through. OpenRouter specifically uses the native `reasoning:{effort}` object, clamps `max` to `xhigh` (its enum has no `max`), and forwards an explicit `effort:"none"` so reasoning can be turned off.
+- **Codex Goal Mode and Remote Compaction Controls**: Codex config editing now exposes a Goal Mode toggle and a Remote Compaction toggle for third-party providers; new Codex templates default to `disable_response_storage = true` while still allowing explicit goal support.
+- **Xiaomi MiMo Token Plan Presets**: Added Xiaomi MiMo Token Plan presets with specs aligned to the official documentation (#2803).
+- **Claude Desktop Official Preset**: Added a Claude Desktop Official preset that restores the native Claude Desktop login, plus a localized Claude Desktop user guide (en / zh / ja).
+- **Managed CLI Tool Lifecycle**: Added silent install / update commands for managed CLI tools, latest-version checks, per-tool and batch actions, update-all, and diagnostics for multiple installations across PATH, Homebrew, npm, pnpm, bun, volta, fnm, nvm, scoop, WinGet, Windows native paths, and WSL.
+- **Source-Aware Tool Diagnostics**: The Settings / About surface can now diagnose conflicting tool installations, show the concrete install source and version for each path, and generate backend-planned upgrade commands anchored to the actual installation source.
+- **Real-Time Usage Refresh**: The backend now emits `usage-log-recorded` when proxy logs, session-log syncs, or rollups write usage data; Usage Dashboard listens for that event and invalidates its queries immediately instead of waiting for the next polling interval (#3027).
+- **Traditional Chinese Localization**: Added `zh-TW` UI localization and a settings language option (#3093).
+- **German README**: Added `README_DE.md` and linked it from the existing README language switchers (#2994).
+- **New Partner Presets**: Added APIKEY.FUN, APINebula, AtlasCloud, and SudoCode partner presets across the supported app surfaces, with partner copy, icons, and README entries.
+
+### Changed
+
+- **Codex Third-Party Providers Unified into a "custom" History Bucket**: Codex filters resume history by `model_provider`, so switching between provider-specific ids made past sessions appear to vanish. All third-party providers now normalize to a single stable `custom` bucket (reserved built-in ids like `openai` / `ollama` are preserved), with a one-shot device migration that rewrites historical JSONL sessions and the `state_5.sqlite` threads table and backs up originals under `~/.cc-switch/backups/codex-history-provider-migration-v1/`.
+- **Codex Provider Form Simplified**: Removed the API Format selector from the Codex form (`wire_api` is always `responses`, so the selector misleadingly implied a protocol change); the model mapping table is now the only source of truth with no hidden default entries, and the form notes that a Codex restart is required after catalog changes since `model_catalog_json` is loaded at startup. Only the "Needs Local Routing" toggle remains.
+- **Codex Local Routing Toggle Hints Rewritten**: Reframed the OFF / ON hints as action guidance (when to enable) rather than scenario descriptions, synced across zh / en / ja.
+- **Codex Live Config Preservation**: Live Codex config reads no longer force-rewrite a user's `model_provider` field, and provider-scoped `experimental_bearer_token` handling now preserves OAuth login state when switching between third-party providers.
+- **Tool Install / Upgrade Strategy**: Managed tool installation now prefers official native installers where available, falls back to package managers when appropriate, runs self-update first for compatible tools, anchors upgrades to the detected install source, and locks duplicate batch actions while work is in flight.
+- **About Page Becomes Tool Management**: The About settings page now presents installed / latest versions, install and update actions, conflict diagnostics, WSL shell preferences, and clearer status for broken or unrunnable tools.
+- **Default Models and Pricing Refreshed**: Upgraded the default Claude Opus model to 4.8, moved GPT-based presets and templates to GPT-5.5 where applicable, refreshed pricing seeds, aligned Claude Desktop model mapping with Claude Code's three-role tiers, and renamed the OpenCode Go preset to drop a stale model suffix.
+- **Partner Links Refreshed**: Updated ShengSuanYun referral links, Atlas Cloud UTM links, and partner copy across README locales and provider metadata.
+- **Homebrew Official Cask Installation**: Installation simplified to `brew install --cask cc-switch` now that CC Switch is in the official Homebrew repository; the personal-tap requirement was removed from all READMEs.
+- **Shared Frontend Utilities**: Replaced JSON stringify / parse deep-copy patterns with a shared `deepClone` helper and extracted a shared `useTauriEvent` hook (#3140).
+
+### Fixed
+
+- **Codex Chat Error Responses Converted to Responses Envelope**: The Codex Chat-to-Responses bridge previously passed upstream error bodies through untouched, leaving Codex clients unable to recognize MiniMax `base_resp`, raw OpenAI Chat errors, or plain-text / HTML error pages. Errors are now regularized into the standard `{error: {message, type, code, param}}` envelope with the original HTTP status preserved; non-JSON bodies are wrapped and truncated to 1KB at a UTF-8 char boundary. Also fixed a pre-existing append-vs-insert bug that emitted a duplicate `Content-Type` header on rewritten JSON bodies.
+- **Codex Mid-Stream System Messages Collapsed**: MiniMax's OpenAI-compatible endpoint strict-rejects any non-leading `system` message (error 2013). All `system` fragments are now collapsed into a single leading message (joined in original order), losslessly for permissive backends too.
+- **Codex Model Catalog Wiped After Restart**: Editing the active Codex provider triggered a live read that omitted `modelCatalog`, so a subsequent save silently destroyed user-configured model mappings. Live reads now reverse-parse the on-disk catalog projection to round-trip the same shape the save path writes.
+- **Codex Model Catalog Infinite Render Loop**: Broke a bidirectional sync cycle between the catalog table and its parent state that caused severe UI jittering when adding or editing entries.
+- **Codex Chat Preserves User-Selected Catalog Model**: A model the client selects from the catalog (e.g. via `/model`) is no longer overwritten by `config.toml`'s default model.
+- **Codex Chat Reasoning and Cache Stability**: Restored a unique call-id fallback when Codex omits or rewrites `previous_response_id`, stopped deriving cache identity from `previous_response_id`, and canonicalized parseable JSON string payloads in tool conversions for stable prefix-cache reuse.
+- **Codex Chat Streaming Usage Recovered**: The Responses-to-Chat conversion now injects `stream_options.include_usage` (merging into any client-provided `stream_options`) when a request is streaming, so OpenAI-compatible upstreams like Kimi and MiniMax emit the trailing usage chunk again. Previously their streamed token / cost / cache stats were recorded as zero on the Codex Chat path.
+- **Codex Chat Tool-Call Reasoning Backfill**: Thinking models like Kimi/Moonshot and DeepSeek reject an assistant message that carries `tool_calls` without a non-empty `reasoning_content`. When cross-turn history recovery misses (proxy restart, ambiguous `call_id`, or a turn with no upstream reasoning), a placeholder `reasoning_content` is now backfilled in a final pass — genuine trailing reasoning still attaches first — so the request no longer fails with `reasoning_content is missing in assistant tool call message`.
+- **Managed-Account Claude Takeover Auth**: Managed-account providers (GitHub Copilot / Codex OAuth) now drop token env keys and write only the `ANTHROPIC_API_KEY` placeholder when taking over Claude Live config, with an outbound guard that refuses to send the `PROXY_MANAGED` placeholder upstream.
+- **Claude Desktop Profile Sync During Takeover**: Claude Desktop profile data is now synced during proxy takeover, model routes align with the Claude Code three-role tiers, and the Cowork egress profile has been corrected (#3157, #3172).
+- **Managed-Account Takeover Model Fields**: Local Routing now sources takeover model fields from the target provider on managed accounts instead of carrying stale model values.
+- **DeepSeek Anthropic Tool Thinking History**: Normalized DeepSeek Anthropic-compatible tool-thinking history so later turns can replay reasoning / tool-call context without malformed messages (#3203).
+- **Claude-Compatible Empty Tool Calls in Streams**: Fixed a Claude-compatible streaming edge case where an empty `tool_calls` array reset block state and broke streamed responses (#2915).
+- **MiMo Reasoning for Claude Code Proxy**: Added MiMo `reasoning_content` support on the Claude Code proxy path (#2990).
+- **Gemini Native Tool-Call Robustness**: Fixed `functionResponse.name` resolution (422) and `thought_signature` replay (400) for synthesized tool-call IDs in long multi-turn sessions (#2814).
+- **Session Log Subagent Token Accounting**: `collect_jsonl_files()` now scans subagent JSONL logs that were previously missed, so subagent token usage is counted in session cost (session-log mode only) (#2821).
+- **Usage Dashboard / Sync Stability**: Fixed a Codex usage-sync panic on non-ASCII model names, custom usage-script summaries, and missing real-time refresh after usage rollups (#3027, #3129).
+- **ZhiPu Coding-Plan Quota Tier Ordering**: When the 5-hour bucket is at 0% utilization, ZhiPu's API omits `nextResetTime`; the old `i64::MAX` sentinel sorted those entries last, letting the weekly bucket incorrectly claim the five-hour slot. Tiers now sort so a missing `nextResetTime` maps to the five-hour bucket, so tray and usage quota display stays correct for ZhiPu coding plans.
+- **Skills Install by Key**: Installing from skills.sh search results now uses the unique key instead of the directory name, so skills that share a directory name install the correct one (#2784); also fixed a skill sync copy fallback (#2791).
+- **Usage Price Input Precision**: Reduced the price input step to 0.0001 so sub-cent costs like DeepSeek cache reads can be entered (#2793, closes #2503).
+- **Ghostty Clean Window Launch**: Ghostty now opens a single clean window instead of cloning existing tabs, and other terminals open a new window via `open -na` (#2801, closes #2798).
+- **Tool Version and Update Reliability**: Version probing no longer masks unrunnable installs, prerelease tools are handled correctly in version checks, batch updates run per tool, install / update buttons stay locked during preflight, anchored upgrade branches enforce absolute paths, and WSL installer paths use native Unix installers when needed.
+- **Codex mise Detection**: Fixed Codex mise environment detection (#2822).
+- **Codex Archived Sessions**: Codex archived sessions are now included in session discovery (#2861).
+- **Codex Chat Empty Tool Arguments**: Empty tool-call argument payloads are coerced to `{}` during Codex Chat conversion so upstreams and clients receive valid JSON.
+- **Claude Provider Deeplink Imports**: Importing Claude providers through deeplinks now preserves custom environment fields (#2928).
+- **OMO Recommended Models**: Synced OMO recommended models with upstream defaults and improved Fill Recommended feedback.
+- **ShengSuanYun Model IDs Prefixed for Routing**: ShengSuanYun (胜算云) presets now carry the vendor prefixes the upstream gateway requires — `anthropic/…`, `google/…`, and `openai/…` (e.g. `anthropic/claude-sonnet-4.6`, `google/gemini-3.1-pro-preview`) — across the Claude Code, Claude Desktop, Codex, Gemini, OpenCode, and OpenClaw presets, including the Claude Code routing env (`ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_{HAIKU,SONNET,OPUS}_MODEL`), so they resolve to valid upstream models instead of failing to route.
+- **ClaudeAPI Model Test Re-Enabled**: Reclassified the ClaudeAPI preset (Claude Code and Claude Desktop) from `third_party` to `aggregator` so its model test button is no longer disabled by the third-party Claude gate; the partner star is unaffected since it is driven by `isPartner`, not category.
+- **About Version Check**: Version checks now handle prerelease tool versions without misclassifying update state.
+- **App Switcher Text Clipping**: Removed a fixed width constraint that clipped app-switcher text (#3161).
+- **useEffect Race Condition**: Added an active-flag pattern to App.tsx effects to prevent listener leaks on unmount, and guarded against storing `undefined` language in localStorage (#2827).
+
+### Removed
+
+- **LionCC Sponsor and Presets**: Removed the LionCC sponsor entry and LionCCAPI presets across READMEs, provider configs, and locales (icon asset retained).
+- **AICoding Partner Entry**: Removed the AICoding partner from README sponsor listings, provider presets, and i18n metadata.
+- **Kimi For Coding Codex Preset**: Removed the Kimi For Coding preset from the Codex preset catalog.
+- **CLI Uninstall Command Hints**: Dropped generated CLI uninstall command hints from the tool-management UI while keeping conflict diagnostics visible.
+
+### Docs
+
+- **Codex Chat Provider Support**: Documented Chat Completions routing, provider support, reasoning auto-detection, and Local Routing guidance in the changelog and user manual.
+- **Settings Manual Refresh**: Updated settings documentation for the new managed tool lifecycle and Hermes installer behavior.
+- **Claude Desktop Guide**: Added localized Claude Desktop guide pages and screenshots for provider setup, import, model mapping, and Local Routing context.
+- **Installation Docs**: Updated installation docs and READMEs to recommend the official Homebrew cask and refreshed the v3.15.0 release-note imposter-site warning wording across locales.

 ## [3.15.0] - 2026-05-16

@@ -2,7 +2,7 @@

 # CC Switch

-### The All-in-One Manager for Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw & Hermes Agent
+### The All-in-One Manager for Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw & Hermes Agent

 [![Version](https://img.shields.io/github/v/release/farion1231/cc-switch?color=blue&label=version)](https://github.com/farion1231/cc-switch/releases)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/farion1231/cc-switch/releases)
@@ -10,10 +10,11 @@
 [![Downloads](https://img.shields.io/github/downloads/farion1231/cc-switch/total)](https://github.com/farion1231/cc-switch/releases/latest)

 <a href="https://trendshift.io/repositories/15372" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15372" alt="farion1231%2Fcc-switch | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+<a href="https://www.star-history.com/#farion1231/cc-switch&Date"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=farion1231/cc-switch&theme=dark" /><img alt="Star History Rank" src="https://api.star-history.com/badge?repo=farion1231/cc-switch" width="196" height="55" /></picture></a>

 ### 🌐 The Only Official Website: **[ccswitch.io](https://ccswitch.io)**

-English | [中文](README_ZH.md) | [日本語](README_JA.md) | [Changelog](CHANGELOG.md)
+English | [中文](README_ZH.md) | [日本語](README_JA.md) | [Deutsch](README_DE.md) | [Changelog](CHANGELOG.md)

 </div>

@@ -24,11 +25,11 @@ English | [中文](README_ZH.md) | [日本語](README_JA.md) | [Changelog](CHANG
 <details open>
 <summary>Click to collapse</summary>

-[![MiniMax](assets/partners/banners/minimax-en.jpeg)](https://platform.minimax.io/subscribe/coding-plan?code=ClLhgxr2je&source=link)
+[![Kimi K2.7 Code](https://gcdn.moonshot.cn/growth-cdn/sponsor/kimi-en.png)](https://platform.kimi.ai?aff=cc-switch)

-MiniMax-M2.7 is a next-generation large language model designed for autonomous evolution and real-world productivity. Unlike traditional models, M2.7 actively participates in its own improvement through agent teams, dynamic tool use, and reinforcement learning loops. It delivers strong performance in software engineering (56.22% on SWE-Pro, 55.6% on VIBE-Pro, 57.0% on Terminal Bench 2) and excels in complex office workflows, achieving a leading 1495 ELO on GDPval-AA. With high-fidelity editing across Word, Excel, and PowerPoint, and a 97% adherence rate across 40+ complex skills, M2.7 sets a new standard for building AI-native workflows and organizations.
+Kimi K3 is Moonshot AI's most capable model and the world's first open 3T-class model. With 2.8 trillion parameters, native vision, and a 1-million-token context window, K3 delivers frontier performance across long-horizon coding, knowledge work, and reasoning. CC Switch makes it easy to configure and switch to Kimi across agentic tools. **[Click here to start using Kimi](https://platform.kimi.ai?aff=cc-switch)**

-[Click](https://platform.minimax.io/subscribe/coding-plan?code=ClLhgxr2je&source=link) to get an exclusive 12% off the MiniMax Token Plan!
+Doing mostly coding work? Try the **[Kimi Code subscription](https://www.kimi.com/code/?aff=cc-switch)**.

 ---

@@ -39,13 +40,13 @@ MiniMax-M2.7 is a next-generation large language model designed for autonomous e
 </tr>

 <tr>
-<td width="180"><a href="https://aigocode.com/invite/CC-SWITCH"><img src="assets/partners/logos/aigocode.png" alt="AIGoCode" width="150"></a></td>
-<td>Thanks to AIGoCode for sponsoring this project! AIGoCode is an all-in-one platform that integrates Claude Code, Codex, and the latest Gemini models, providing you with stable, efficient, and highly cost-effective AI coding services. The platform offers flexible subscription plans, zero risk of account suspension, direct access with no VPN required, and lightning-fast responses. AIGoCode has prepared a special benefit for CC Switch users: if you register via <a href="https://aigocode.com/invite/CC-SWITCH">this link</a>, you'll receive an extra 10% bonus credit on your first top-up!</td>
+<td width="180"><a href="https://zetaapi.ai/go/u117"><img src="assets/partners/logos/zetaapi-banner.png" alt="ZetaAPI" width="150"></a></td>
+<td>Thanks to ZetaAPI for sponsoring this project! ZetaAPI focuses on real model fidelity, no watered-down responses, no quality degradation, and pricing as low as 35% of official rates. The platform does not mix traffic, secretly replace models with lower-quality alternatives, or use fake model routing. It supports Claude Code, Codex, Gemini, ChatGPT, and other mainstream AI models, helping users significantly reduce API costs while maintaining reliable model quality. At the same time, ZetaAPI provides enterprise-grade SLA-backed stability, standard API compatibility, one API key for multiple models, fast integration, and pay-as-you-go billing, making it suitable for AI products, coding agents, internal business tools, customer service systems, content generation, and automation workflows. If any model is verified to be inconsistent with its stated quality, ZetaAPI backs it with a 10x compensation guarantee, giving users a more stable, transparent, and trustworthy experience. Register via <a href="https://zetaapi.ai/go/u117">this link</a> and use the promo code CC-SWITCH during your first recharge to enjoy an exclusive 10% discount on your first top-up, just for CC Switch users!</td>
 </tr>

 <tr>
-<td width="180"><a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF"><img src="assets/partners/logos/shengsuanyun.png" alt="Shengsuanyun" width="150"></a></td>
-<td>Thanks to Shengsuanyun for sponsoring this project! Shengsuanyun is a super factory serving AI Native Teams — an industrial-grade AI task parallel execution platform. Its model marketplace aggregates Claude, ChatGPT, Gemini, and other domestic and international LLM and multimedia model capabilities with direct supply. Absolutely no reverse engineering or dilution — platform-wide model SLA availability reaches 99.7%, with <a href="https://watch.shengsuanyun.com/status/shengsuanyun">monitoring dashboards</a> showing green across the board. It also offers enterprise-grade custom gateways for fine-grained team cost and permission management, smart routing, security protection, and BYOK (Bring Your Own Key) hosting. The platform charges on a pay-per-use and tokens plan (coming soon) basis, with invoicing available. Register via <a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF">this link</a> as a new user to receive ¥10 in credits plus a 10% bonus on your first top-up.</td>
+<td width="180"><a href="https://apinebula.com/VjM74M"><img src="assets/partners/logos/apinebula_banner.png" alt="APINebula" width="150"></a></td>
+<td>Thanks to APINEBULA for sponsoring this project! APINEBULA, an enterprise-grade AI aggregation platform under Galaxy Video Bureau, leverages extensive platform resources to provide developers, teams, and enterprises with stable, cost-effective access to large language model APIs. The platform integrates leading, full-powered models like Claude, GPT, and Gemini, allowing you to connect to the world's top AI models through a single API, with prices starting as low as 10% of the original cost. Designed for AI programming, Agent development, and business system integration, APINEBULA supports enterprise-grade high concurrency, formal contracts, corporate bank transfers, and invoicing services. APINEBULA provides special discounts for our software users: register using <a href="https://apinebula.com/VjM74M">this link</a> and enter the <strong>"ccswitch"</strong> promo code during your first recharge to get <strong>10% off</strong>.</td>
 </tr>

 <tr>
@@ -61,24 +62,86 @@ It also supports enterprise-grade concurrency and provides a dedicated managemen
 Register now via <a href="https://pateway.ai/?ch=etzpm8&aff=WB6M6F67#/">this link</a> to receive $3 in trial credit. Top-ups go as low as 60% of the original price, with a two-way referral bonus of up to $150!</td>
 </tr>

+<tr>
+<td width="180"><a href="https://api.fenno.ai/register?redirect=/purchase?tab=subscription%26group=16&aff=P9MR3D3PLCNL"><img src="assets/partners/logos/fenno-banner.png" alt="Fenno.ai" width="150"></a></td>
+<td>Thanks to Fenno.ai for sponsoring this project! Fenno.ai is a stable and efficient API relay service provider, currently focused on Codex relay. It is compatible with the OpenAI and Anthropic protocols and can be flexibly used from Codex, Claude Code, OpenCode, and other mainstream coding tools. It reliably supports enterprise-grade workloads of hundreds of billions of tokens per day, with corporate (B2B) settlement and invoicing for both domestic and overseas entities. Fenno.ai offers an exclusive benefit for CC Switch users: subscribe via <a href="https://api.fenno.ai/register?redirect=/purchase?tab=subscription%26group=16&aff=P9MR3D3PLCNL">this link</a> to the incredible ¥9.9 Coding Plan worth $150 in credits, and earn up to 20% in referral rewards — invite more, earn more!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://runapi.co/register?aff=iOKB"><img src="assets/partners/logos/runapi.jpg" alt="RunAPI" width="150"></a></td>
+<td>Thanks to RunAPI for sponsoring this project! RunAPI is a high-performance and reliable AI model API gateway — one API key gives you access to 150+ mainstream models including OpenAI, Claude, Gemini, DeepSeek, and Grok, with prices as low as 10% of the official rate and excellent stability. It works seamlessly with Claude Code, OpenClaw, and other tools. Exclusive benefit for CC Switch users: register via <a href="https://runapi.co/register?aff=iOKB">this link</a> and enjoy a 10% discount on your first top-up!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://unity2.ai/register?source=ccs"><img src="assets/partners/logos/unity2.jpg" alt="Unity2.ai" width="150"></a></td>
+<td>Thanks to Unity2.ai for sponsoring this project! Unity2.ai is a high-performance AI model API relay platform for individual developers, teams, and enterprises. Long trusted by leading companies in China, it serves over 30 billion tokens per day and supports high concurrency at the 5,000 RPM level. It offers balance-based billing, first top-up bonuses, bundle subscriptions, corporate invoicing, and dedicated support. Register via <a href="https://unity2.ai/register?source=ccs">this link</a> to get $2 in credits, plus another $10 for joining the official group — up to $12 in free credits!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF"><img src="assets/partners/logos/shengsuanyun.png" alt="Shengsuanyun" width="150"></a></td>
+<td>Thanks to Shengsuanyun for sponsoring this project! Shengsuanyun is a super factory serving AI Native Teams — an industrial-grade AI task parallel execution platform. Its model marketplace aggregates Claude, ChatGPT, Gemini, and other domestic and international LLM and multimedia model capabilities with direct supply. Absolutely no reverse engineering or dilution — platform-wide model SLA availability reaches 99.7%, with <a href="https://watch.shengsuanyun.com/status/shengsuanyun">monitoring dashboards</a> showing green across the board. It also offers enterprise-grade custom gateways for fine-grained team cost and permission management, smart routing, security protection, and BYOK (Bring Your Own Key) hosting. The platform charges on a pay-per-use and tokens plan (coming soon) basis, with invoicing available. Register via <a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF">this link</a> as a new user to receive ¥10 in credits plus a 10% bonus on your first top-up.</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://aigocode.com/invite/CC-SWITCH"><img src="assets/partners/logos/aigocode.png" alt="AIGoCode" width="150"></a></td>
+<td>Thanks to AIGoCode for sponsoring this project! AIGoCode is an all-in-one platform that integrates Claude Code, Codex, and the latest Gemini models, providing you with stable, efficient, and highly cost-effective AI coding services. The platform offers flexible subscription plans, zero risk of account suspension, direct access with no VPN required, and lightning-fast responses. AIGoCode has prepared a special benefit for CC Switch users: if you register via <a href="https://aigocode.com/invite/CC-SWITCH">this link</a>, you'll receive an extra 10% bonus credit on your first top-up!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://subrouter.ai/register?aff=l3ri"><img src="assets/partners/logos/subrouter-banner.png" alt="SubRouter" width="150"></a></td>
+<td>Thanks to SubRouter for sponsoring this project! SubRouter is a marketplace and smart routing platform for AI service operators. Merchants can launch operating sites, publish packages, manage users, models, and pricing, while users discover services and access reliable AI models through one unified API. Register via <a href="https://subrouter.ai/register?aff=l3ri">this link</a>!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://apikey.fun/register?aff=CCSwitch"><img src="assets/partners/logos/apikey_banner.png" alt="APIKEY.FUN" width="150"></a></td>
+<td>Thanks to APIKEY.FUN for sponsoring this project! APIKEY.FUN is a professional enterprise-grade AI relay platform dedicated to providing stable, efficient, and low-cost AI model API access for enterprises and individual developers. The platform supports popular mainstream models such as Claude, OpenAI, and Gemini, with prices as low as 7% of official rates. Register through this project's <a href="https://apikey.fun/register?aff=CCSwitch">exclusive link</a> to enjoy an exclusive offer of up to <strong>permanent 5% off top-ups</strong>.</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://console.claudeapi.com/register?aff=pCLD"><img src="assets/partners/logos/claudeapi.png" alt="ClaudeAPI" width="150"></a></td>
+<td>This project is sponsored by <a href="https://console.claudeapi.com/register?aff=pCLD">Claude API</a>. Direct Claude API access — connect Claude Code and Agent apps in 3 minutes. New users can claim a free trial credit.Powered by official Anthropic API keys + AWS Bedrock official channels. No reverse engineering, no model degradation. Full support for Opus / Sonnet / Haiku model lineup, with official capabilities preserved including Tool Use, 1M context window, and more. Built for Claude Code power users, Agent engineers, and enterprise engineering teams. Invoicing and dedicated team support available. Click <a href="https://console.claudeapi.com/register?aff=pCLD">here</a> to register!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://code0.ai/agent/register/B2XHxGjGmRvqgznY"><img src="assets/partners/logos/code0.png" alt="code0.ai" width="150"></a></td>
+<td>Thanks to <a href="https://code0.ai/agent/register/B2XHxGjGmRvqgznY">code0.ai</a> for sponsoring this project! code0.ai is an AI coding service platform built for developers, supporting Claude Code, Codex, Gemini, and other mainstream AI coding capabilities. It helps individual developers and teams use AI Agents more stably and efficiently for coding, debugging, refactoring, and automation workflows. ccswitch users can contact customer support via the <a href="https://code0.ai/agent/register/B2XHxGjGmRvqgznY">code0.ai website</a> to claim test credits and experience a reliable AI coding service.</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://teamorouter.com/?utm_source=cc_switch&utm_medium=referral&utm_campaign=ai_directory"><img src="assets/partners/logos/TeamoRouter-banner.png" alt="TeamoRouter" width="150"></a></td>
+<td>Thanks to TeamoRouter for sponsoring this project! TeamoRouter is an enterprise-grade Agentic LLM gateway built for developers, AI teams, and businesses. Without requiring any subscriptions, it lets you access Claude Code, Codex, Gemini CLI, OpenAI Codex, and other popular AI agents through a single unified API, while offering API pricing at discounts of up to 90%.
+Unlike typical API relay services, TeamoRouter aggregates hundreds of official model providers and trusted infrastructure partners, including OpenAI, Anthropic, Vertex, Azure, and AWS bedrock. Every provider is verified for 100% Agent protocol compatibility, cache performance, and request traceability, ensuring stable quality instead of reverse-engineered or diluted endpoints. The platform delivers near-official TTFT, 99.6% SLA, enterprise-scale throughput up to 5,000 QPM, and industry-leading cache hit rates that dramatically reduce token costs for long-running agent workflows.
+TeamoRouter also offers enterprise features including centralized billing, team management, BYOK, smart routing, usage analytics, dynamic provider optimization, and dedicated support. For an even simpler experience, Teamo Desktop lets you use Claude Code, Codex, Gemini CLI, and other popular AI agents with one-click setup—no API key management or manual gateway configuration required. Register via <a href="https://teamorouter.com/?utm_source=cc_switch&utm_medium=referral&utm_campaign=ai_directory">this link</a> as a new user to receive 10% off your first top-up.</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.newapi.ai/"><img src="assets/partners/logos/newapi-banner.png" alt="new-api" width="150"></a></td>
+<td>Thanks to the open-source AI infrastructure project <a href="https://www.newapi.ai/">new-api</a> for its strong support of this project! new-api is an open-source AI infrastructure project from QuantumNous and one of the leading unified LLM access-and-distribution projects by activity and adoption, focused on helping developers, teams, and enterprises build manageable, scalable AI service platforms at lower cost. As a fellow project rooted in the open-source ecosystem, new-api hopes to sponsor and support the continued growth of more outstanding open-source projects. 🌟 Star new-api to show your support: <a href="https://github.com/QuantumNous/new-api">https://github.com/QuantumNous/new-api</a>. Website: <a href="https://www.newapi.ai/">https://www.newapi.ai/</a>.</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://claudecn.ai/register?aff=HEL9"><img src="assets/partners/logos/claudecn.jpg" alt="ClaudeCN" width="150"></a></td>
+<td>Thanks to ClaudeCN for sponsoring this project! ClaudeCN is an enterprise-grade AI gateway platform operated by a registered company. It delivers high-availability commercial API access to popular models including Claude, GPT, and DeepSeek, and is built around formal enterprise procurement workflows — corporate bank transfers, signed contracts, and full compliance. Register via <a href="https://claudecn.ai/register?aff=HEL9">this link</a>!</td>
+</tr>
+
 <tr>
 <td width="180"><a href="https://www.byteplus.com/en/product/modelark?utm_campaign=hw&utm_content=ccswitch&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch"><img src="assets/partners/logos/byteplus.png" alt="BytePlus" width="150"></a></td>
-<td>Thanks to Dola seed for sponsoring this project! Dola Seed 2.0 is a full‑modal general large model independently developed by ByteDance for the global market. Built on a unified multimodal architecture, it supports joint understanding and generation of text, images, audio, and video. It natively enables agent collaboration, with strong reasoning, long‑task execution, tool integration, and coding capabilities. It is widely applicable to smart cockpits, personal assistants, education, customer support, marketing, retail, and other scenarios. It excels in multimodal perception, end‑to‑end complex task delivery, stable interaction, and data security, and is readily accessible and deployable via the ModelArk platform.Register via <a href="https://www.byteplus.com/en/product/modelark?utm_campaign=hw&utm_content=ccswitch&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch">this link</a> to get 500,000 tokens of free inference quota per model.<a href="https://www.volcengine.com/activity/agentplan?utm_campaign=hw&utm_content=ccswitch&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch"> >>中国大陆地区的开发者请点击这里</a></td>
+<td>Thanks to Dola seed for sponsoring this project! Dola Seed 2.0 is a full‑modal general large model independently developed by ByteDance for the global market. Built on a unified multimodal architecture, it supports joint understanding and generation of text, images, audio, and video. It natively enables agent collaboration, with strong reasoning, long‑task execution, tool integration, and coding capabilities. It is widely applicable to smart cockpits, personal assistants, education, customer support, marketing, retail, and other scenarios. It excels in multimodal perception, end‑to‑end complex task delivery, stable interaction, and data security, and is readily accessible and deployable via the ModelArk platform.Register via <a href="https://www.byteplus.com/en/product/modelark?utm_campaign=hw&utm_content=ccswitch&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch">this link</a> to get 500,000 tokens of free inference quota per model.<a href="https://www.volcengine.com/activity/ai618?utm_campaign=hw&utm_content=hw&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch"> >>中国大陆地区的开发者请点击这里</a></td>
 </tr>

 <tr>
-<td width="180"><a href="https://cloud.siliconflow.cn/i/drGuwc9k"><img src="assets/partners/logos/silicon_en.jpg" alt="SiliconFlow" width="150"></a></td>
-<td>Thanks to SiliconFlow for sponsoring this project! SiliconFlow is a high-performance AI infrastructure and model API platform, providing fast and reliable access to language, speech, image, and video models in one place. With pay-as-you-go billing, broad multimodal model support, high-speed inference, and enterprise-grade stability, SiliconFlow helps developers and teams build and scale AI applications more efficiently. Register via <a href="https://cloud.siliconflow.cn/i/drGuwc9k">this link</a> and complete real-name verification to receive ¥16 in bonus credit, usable across models on the platform. SiliconFlow is also now compatible with OpenClaw, allowing users to connect a SiliconFlow API key and call major AI models for free.</td>
+<td width="180"><a href="https://cloud.siliconflow.cn/i/YflgU2Ve"><img src="assets/partners/logos/silicon_en.jpg" alt="SiliconFlow" width="150"></a></td>
+<td>Thanks to SiliconFlow for sponsoring this project! SiliconFlow is a high-performance AI infrastructure and model API platform, providing fast and reliable access to language, speech, image, and video models in one place. With pay-as-you-go billing, broad multimodal model support, high-speed inference, and enterprise-grade stability, SiliconFlow helps developers and teams build and scale AI applications more efficiently. Register via <a href="https://cloud.siliconflow.cn/i/YflgU2Ve">this link</a> and complete real-name verification to receive ¥16 in bonus credit, usable across models on the platform. SiliconFlow is also now compatible with OpenClaw, allowing users to connect a SiliconFlow API key and call major AI models for free.</td>
 </tr>

 <tr>
-<td width="180"><a href="https://cubence.com/signup?code=CCSWITCH&source=ccs"><img src="assets/partners/logos/cubence.png" alt="Cubence" width="150"></a></td>
-<td>Thanks to Cubence for sponsoring this project! Cubence is a reliable and efficient API relay service provider, offering relay services for Claude Code, Codex, Gemini, and more with flexible billing options including pay-as-you-go and monthly plans. Cubence provides special discounts for CC Switch users: register using <a href="https://cubence.com/signup?code=CCSWITCH&source=ccs">this link</a> and enter the "CCSWITCH" promo code during recharge to get 10% off every top-up!</td>
+<td width="180"><a href="https://nekocode.ai?aff=CCSWITCH"><img src="assets/partners/logos/nekocode-banner.png" alt="NekoCode" width="150"></a></td>
+<td>Thanks to <a href="https://nekocode.ai?aff=CCSWITCH">NekoCode</a> for sponsoring this project! NekoCode provides developers with a stable, efficient, and reliable API relay service for Claude, Codex, and other AI models. With transparent pricing and flexible pay-as-you-go billing, it offers a simple and cost-effective way to access AI models. CC Switch users can enjoy an exclusive 10% discount: register via <a href="https://nekocode.ai?aff=CCSWITCH">this link</a> and enter promo code <code>cc-switch</code> during recharge to receive 10% off your top-up!</td>
 </tr>

 <tr>
-<td width="180"><a href="https://www.dmxapi.cn/register?aff=bUHu"><img src="assets/partners/logos/dmx-en.jpg" alt="DMXAPI" width="150"></a></td>
-<td>Thanks to DMXAPI for sponsoring this project! DMXAPI provides global large model API services to 200+ enterprise users. One API key for all global models. Features include: instant invoicing, unlimited concurrency, starting from $0.15, 24/7 technical support. GPT/Claude/Gemini all at 32% off, domestic models 20-50% off, Claude Code exclusive models at 66% off! <a href="https://www.dmxapi.cn/register?aff=bUHu">Register here</a></td>
+<td width="180"><a href="https://www.atlascloud.ai/coding-plan?utm_source=github&utm_campaign=cc-switch"><img src="assets/partners/logos/atlascloud_banner.png" alt="Atlas Cloud" width="150"></a></td>
+<td>Atlas Cloud is a full-modal AI inference platform that gives developers a single AI API to access video generation, image generation, and LLM APIs. Instead of managing multiple vendor integrations, you connect once and get unified access to 300+ curated models across all modalities. Check out Atlas Cloud's new <a href="https://www.atlascloud.ai/coding-plan?utm_source=github&utm_campaign=cc-switch">coding plan</a> promotion for more budget-friendly API access!</td>
 </tr>

 <tr>
@@ -87,18 +150,8 @@ Register now via <a href="https://pateway.ai/?ch=etzpm8&aff=WB6M6F67#/">this lin
 </tr>

 <tr>
-<td width="180"><a href="https://aicoding.sh/i/CCSWITCH"><img src="assets/partners/logos/aicoding.jpg" alt="AICoding" width="150"></a></td>
-<td>Thanks to AICoding.sh for sponsoring this project! AICoding.sh — Global AI Model API Relay Service at Unbeatable Prices! Claude Code at 19% of original price, GPT at just 1%! Trusted by hundreds of enterprises for cost-effective AI services. Supports Claude Code, GPT, Gemini and major domestic models, with enterprise-grade high concurrency, fast invoicing, and 24/7 dedicated technical support. CC Switch users who register via <a href="https://aicoding.sh/i/CCSWITCH">this link</a> get 10% off their first top-up!</td>
-</tr>
-
-<tr>
-<td width="180"><a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch"><img src="assets/partners/logos/crazyrouter.png" alt="Crazyrouter" width="150"></a></td>
-<td>Thanks to Crazyrouter for sponsoring this project! Crazyrouter is a high-performance AI API aggregation platform — one API key for 300+ models including Claude Code, Codex, Gemini CLI, and more. All models at 55% of official pricing with auto-failover, smart routing, and unlimited concurrency. Crazyrouter offers an exclusive deal for CC Switch users: register via <a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch">this link</a> and contact customer support to claim <strong>$2 free credit</strong>, plus enter promo code `CCSWITCH` on your first top-up for an extra <strong>30% bonus credit</strong>! </td>
-</tr>
-
-<tr>
-<td width="180"><a href="https://www.right.codes/register?aff=CCSWITCH"><img src="assets/partners/logos/rightcode.jpg" alt="RightCode" width="150"></a></td>
-<td>Thank you to Right Code for sponsoring this project! Right Code reliably provides routing services for models such as Claude Code, Codex, and Gemini, with both pay-as-you-go and monthly subscription billing options available. Invoices are available upon top-up, and enterprise and team users can receive dedicated one-on-one support. Right Code also offers an exclusive discount for CC Switch users: register via <a href="https://www.right.codes/register?aff=CCSWITCH">this link</a>, and with every top-up you will receive pay-as-you-go credit equivalent to 5% of the amount paid.</td>
+<td width="180"><a href="https://www.ccsub.net/register?ref=Y6Z8DXEA"><img src="assets/partners/logos/ccsub.svg" alt="CCSub" width="150"></a></td>
+<td>Thanks to CCSub for sponsoring this project! CCSub is a stable, affordable AI API relay platform — your drop-in replacement for a Claude.ai subscription. One API key gives you access to Claude Opus 4.8, Sonnet, Haiku, GPT-5, Gemini, and DeepSeek at roughly 30% of direct API cost, with no VPN required from anywhere in the world. Compatible with Claude Code, Codex, Cursor, Cline, Continue, Windsurf, and all major AI coding tools. Register via <a href="https://www.ccsub.net/register?ref=Y6Z8DXEA">this link</a> and get $5 free credit on sign-up.</td>
 </tr>

 <tr>
@@ -112,33 +165,28 @@ Register now via <a href="https://pateway.ai/?ch=etzpm8&aff=WB6M6F67#/">this lin
 </tr>

 <tr>
-<td width="180"><a href="https://lemondata.cc/r/FFX1ZDUP"><img src="assets/partners/logos/lemondata.png" alt="LemonData" width="150"></a></td>
-<td>Thanks to LemonData for sponsoring this project! LemonData is a high-performance AI API aggregation platform — one API key for 300+ models including GPT, Claude, Gemini, DeepSeek, and more. All models priced 30–70% below official rates with auto-failover, smart routing, and unlimited concurrency. New users get $1 free credit instantly upon registration — sign up via <a href="https://lemondata.cc/r/FFX1ZDUP">this link</a>to claim your bonus and start building right away</strong>!</td>
+<td width="180"><a href="https://www.right.codes/register?aff=CCSWITCH"><img src="assets/partners/logos/rightcode.jpg" alt="RightCode" width="150"></a></td>
+<td>Thank you to Right Code for sponsoring this project! Right Code reliably provides routing services for models such as Claude Code, Codex, and Gemini, with both pay-as-you-go and monthly subscription billing options available. Invoices are available upon top-up, and enterprise and team users can receive dedicated one-on-one support. Right Code also offers an exclusive discount for CC Switch users: register via <a href="https://www.right.codes/register?aff=CCSWITCH">this link</a>, and with every top-up you will receive pay-as-you-go credit equivalent to 5% of the amount paid.</td>
 </tr>

 <tr>
-<td width="180"><a href="https://ctok.ai"><img src="assets/partners/logos/ctok.png" alt="CTok" width="150"></a></td>
-<td>Thanks to CTok.ai for sponsoring this project! CTok.ai is dedicated to building a one-stop AI programming tool service platform. We offer professional Claude Code packages and technical community services, with support for Google Gemini and OpenAI Codex. Through carefully designed plans and a professional tech community, we provide developers with reliable service guarantees and continuous technical support, making AI-assisted programming a true productivity tool. Click <a href="https://ctok.ai">here</a> to register!</td>
+<td width="180"><a href="https://etok.ai"><img src="assets/partners/logos/etok.png" alt="ETok" width="150"></a></td>
+<td>Thanks to ETok.ai for sponsoring this project! ETok.ai is dedicated to building a one-stop AI programming tool service platform. We offer professional Claude Code packages and technical community services, with support for Google Gemini and OpenAI Codex. Through carefully designed plans and a professional tech community, we provide developers with reliable service guarantees and continuous technical support, making AI-assisted programming a true productivity tool. Click <a href="https://etok.ai">here</a> to register!</td>
 </tr>

 <tr>
-<td width="180"><a href="https://vibecodingapi.ai"><img src="assets/partners/logos/lioncc.png" alt="LionCC" width="150"></a></td>
-<td>Thanks to LionCC for sponsoring this project! LionCC is built for Vibe Coders who pursue the ultimate development experience. We provide stable, low-latency, and competitively priced computing services for Claude Code, Codex, and OpenClaw, saving up to 50% in costs. After registering, add customer service on WeChat (HSQBJ088888888) with the code "cc-switch" to receive $10 in free credits (10 million tokens). For other collaborations, follow the blog @LionCC.ai. Click <a href="https://vibecodingapi.ai">here</a> to register!</td>
+<td width="180"><a href="https://cubence.com/signup?code=CCSWITCH&source=ccs"><img src="assets/partners/logos/cubence.png" alt="Cubence" width="150"></a></td>
+<td>Thanks to Cubence for sponsoring this project! Cubence is a reliable and efficient API relay service provider, offering relay services for Claude Code, Codex, Gemini, and more with flexible billing options including pay-as-you-go and monthly plans. Cubence provides special discounts for CC Switch users: register using <a href="https://cubence.com/signup?code=CCSWITCH&source=ccs">this link</a> and enter the "CCSWITCH" promo code during recharge to get 10% off every top-up!</td>
 </tr>

 <tr>
-<td width="180"><a href="https://console.claudeapi.com/register?aff=pCLD"><img src="assets/partners/logos/claudeapi.png" alt="ClaudeAPI" width="150"></a></td>
-<td>This project is sponsored by <a href="https://console.claudeapi.com/register?aff=pCLD">Claude API</a>. Direct Claude API access — connect Claude Code and Agent apps in 3 minutes. New users can claim a free trial credit.Powered by official Anthropic API keys + AWS Bedrock official channels. No reverse engineering, no model degradation. Full support for Opus / Sonnet / Haiku model lineup, with official capabilities preserved including Tool Use, 1M context window, and more. Built for Claude Code power users, Agent engineers, and enterprise engineering teams. Invoicing and dedicated team support available. Click <a href="https://console.claudeapi.com/register?aff=pCLD">here</a> to register!</td>
+<td width="180"><a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch"><img src="assets/partners/logos/crazyrouter.png" alt="Crazyrouter" width="150"></a></td>
+<td>Thanks to Crazyrouter for sponsoring this project! Crazyrouter is a high-performance AI API aggregation platform — one API key for 300+ models including Claude Code, Codex, Gemini CLI, and more. All models at 55% of official pricing with auto-failover, smart routing, and unlimited concurrency. Crazyrouter offers an exclusive deal for CC Switch users: register via <a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch">this link</a> and contact customer support to claim <strong>$2 free credit</strong>, plus enter promo code `CCSWITCH` on your first top-up for an extra <strong>30% bonus credit</strong>! </td>
 </tr>

 <tr>
-<td width="180"><a href="https://claudecn.top"><img src="assets/partners/logos/claudecn.jpg" alt="ClaudeCN" width="150"></a></td>
-<td>Thanks to ClaudeCN for sponsoring this project! ClaudeCN is an enterprise-grade AI gateway platform operated by a registered company. It delivers high-availability commercial API access to popular models including Claude, GPT, and DeepSeek, and is built around formal enterprise procurement workflows — corporate bank transfers, signed contracts, and full compliance. Register via <a href="https://claudecn.top">this link</a>!</td>
-</tr>
-
-<tr>
-<td width="180"><a href="https://runapi.co"><img src="assets/partners/logos/runapi.jpg" alt="RunAPI" width="150"></a></td>
-<td>Thanks to RunAPI for sponsoring this project! RunAPI is a high-performance and reliable AI model API gateway — one API key gives you access to 150+ mainstream models including OpenAI, Claude, Gemini, DeepSeek, and Grok, with prices as low as 10% of the official rate and excellent stability. It works seamlessly with Claude Code, OpenClaw, and other tools. Exclusive benefit for CC Switch users: register and contact customer support to claim a free ¥14 credit. Register via <a href="https://runapi.co">this link</a>!</td>
+<td width="180"><a href="https://www.dmxapi.cn/register?aff=bUHu"><img src="assets/partners/logos/dmx-en.jpg" alt="DMXAPI" width="150"></a></td>
+<td>Thanks to DMXAPI for sponsoring this project! DMXAPI provides global large model API services to 200+ enterprise users. One API key for all global models. Features include: instant invoicing, unlimited concurrency, starting from $0.15, 24/7 technical support. GPT/Claude/Gemini all at 32% off, domestic models 20-50% off, Claude Code exclusive models at 66% off! <a href="https://www.dmxapi.cn/register?aff=bUHu">Register here</a></td>
 </tr>

 </table>
@@ -147,13 +195,13 @@ Register now via <a href="https://pateway.ai/?ch=etzpm8&aff=WB6M6F67#/">this lin

 ## Why CC Switch?

-Modern AI-powered coding relies on CLI tools like Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw — but each has its own configuration format. Switching API providers means manually editing JSON, TOML, or `.env` files, and there is no unified way to manage MCP and Skills across multiple tools.
+Modern AI-powered coding relies on tools like Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, and Hermes — but each has its own configuration format. Switching API providers means manually editing JSON, TOML, or `.env` files, and there is no unified way to manage MCP and Skills across multiple tools.

-**CC Switch** gives you a single desktop app to manage all five CLI tools. Instead of editing config files by hand, you get a visual interface to import providers with one click, switch between them instantly, with 50+ built-in provider presets, unified MCP and Skills management, and system tray quick switching — all backed by a reliable SQLite database with atomic writes that protect your configs from corruption.
+**CC Switch** gives you a single desktop app to manage all supported AI tools. Instead of editing config files by hand, you get a visual interface to import providers with one click, switch between them instantly, with 50+ built-in provider presets, unified MCP and Skills management, and system tray quick switching — all backed by a reliable SQLite database with atomic writes that protect your configs from corruption.

- **One App, Five CLI Tools** — Manage Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw from a single interface
+- **One App, Eight Tools** — Manage Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, and Hermes from a single interface
 - **No More Manual Editing** — 50+ provider presets including AWS Bedrock, NVIDIA NIM, and community relays; just pick and switch
- **Unified MCP & Skills Management** — One panel to manage MCP servers and Skills across four apps with bidirectional sync
+- **Unified MCP & Skills Management** — One panel to manage MCP servers and Skills across Claude, Codex, Gemini, Grok Build, OpenCode, and Hermes with bidirectional sync
 - **System Tray Quick Switch** — Switch providers instantly from the tray menu, no need to open the full app
 - **Cloud Sync** — Sync provider data across devices via Dropbox, OneDrive, iCloud, or WebDAV servers
 - **Cross-Platform** — Native desktop app for Windows, macOS, and Linux, built with Tauri 2
@@ -167,22 +215,22 @@ Modern AI-powered coding relies on CLI tools like Claude Code, Codex, Gemini CLI

 ## Features

-[Full Changelog](CHANGELOG.md) | [Release Notes](docs/release-notes/v3.15.0-en.md)
+[Full Changelog](CHANGELOG.md) | [Release Notes](docs/release-notes/v3.16.1-en.md)

 ### Provider Management

- **5 CLI tools, 50+ presets** — Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw; copy your key and import with one click
- **Universal providers** — One config syncs to multiple apps (OpenCode, OpenClaw)
+- **8 supported tools, 50+ presets** — Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes; copy your key and import with one click
+- **Universal providers** — One config syncs to Claude Code, Codex, and Gemini CLI
 - One-click switching, system tray quick access, drag-and-drop sorting, import/export

 ### Proxy & Failover

 - **Local proxy with hot-switching** — Format conversion, auto-failover, circuit breaker, provider health monitoring, and request rectifier
- **App-level takeover** — Independently proxy Claude, Codex, or Gemini, down to individual providers
+- **App-level takeover** — Independently proxy Claude, Codex, Gemini, or Grok Build, down to individual providers

 ### MCP, Prompts & Skills

- **Unified MCP panel** — Manage MCP servers across 4 apps with bidirectional sync and Deep Link import
+- **Unified MCP panel** — Manage MCP servers across Claude, Codex, Gemini, Grok Build, OpenCode, and Hermes with bidirectional sync and Deep Link import
 - **Prompts** — Markdown editor with cross-app sync (CLAUDE.md / AGENTS.md / GEMINI.md) and backfill protection
 - **Skills** — One-click install from GitHub repos or ZIP files, custom repository management, with symlink and file copy support

@@ -192,21 +240,21 @@ Modern AI-powered coding relies on CLI tools like Claude Code, Codex, Gemini CLI

 ### Session Manager & Workspace

- Browse, search, and restore conversation history across all apps
+- Browse, search, and restore conversation history across supported session sources
 - **Workspace editor** (OpenClaw) — Edit agent files (AGENTS.md, SOUL.md, etc.) with Markdown preview

 ### System & Platform

 - **Cloud sync** — Custom config directory (Dropbox, OneDrive, iCloud, NAS) and WebDAV server sync
 - **Deep Link** (`ccswitch://`) — Import providers, MCP servers, prompts, and skills via URL
- Dark / Light / System theme, auto-launch, auto-updater, atomic writes, auto-backups, i18n (zh/en/ja)
+- Dark / Light / System theme, auto-launch, auto-updater, atomic writes, auto-backups, i18n (zh/zh-TW/en/ja)

 ## FAQ

 <details>
-<summary><strong>Which AI CLI tools does CC Switch support?</strong></summary>
+<summary><strong>Which AI tools does CC Switch support?</strong></summary>

-CC Switch supports five tools: **Claude Code**, **Codex**, **Gemini CLI**, **OpenCode**, and **OpenClaw**. Each tool has dedicated provider presets and configuration management.
+CC Switch supports eight tools: **Claude Code**, **Claude Desktop**, **Codex**, **Gemini CLI**, **Grok Build**, **OpenCode**, **OpenClaw**, and **Hermes**. Each tool has dedicated provider presets and configuration management.

 </details>

@@ -256,6 +304,19 @@ Add an official provider from the preset list. After switching to it, run the Lo

 </details>

+<details>
+<summary><strong>Linux (Wayland + NVIDIA): clicks don't register and the window black-screens on resize</strong></summary>
+
+The AppImage forces `GDK_BACKEND=x11` (XWayland) to avoid a historical native-Wayland crash. On newer Wayland + NVIDIA setups this can leave the web content area unclickable (the title-bar buttons still work) and black-screen on resize. Launch with the opt-in escape hatch to switch back to native Wayland:
+
+```bash
+CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
+```
+
+If you launch from a desktop icon, add it to the `.desktop` `Exec=` line (e.g. `env CC_SWITCH_GDK_BACKEND=wayland /path/to/AppImage`) or set it in your session environment. The variable is generic: on tiling Wayland compositors (sway/Hyprland) where clicks don't register, try `CC_SWITCH_GDK_BACKEND=x11` instead. Leaving it unset keeps the default behavior.
+
+</details>
+
 ## Documentation

 For detailed guides on every feature, check out the **[User Manual](docs/user-manual/en/README.md)** — covering provider management, MCP/Prompts/Skills, proxy & failover, and more.
@@ -275,8 +336,8 @@ For detailed guides on every feature, check out the **[User Manual](docs/user-ma

 - **MCP**: Click the "MCP" button → Add servers via templates or custom config → Toggle per-app sync
 - **Prompts**: Click "Prompts" → Create presets with Markdown editor → Activate to sync to live files
- **Skills**: Click "Skills" → Browse GitHub repos → One-click install to all apps
- **Sessions**: Click "Sessions" → Browse, search, and restore conversation history across all apps
+- **Skills**: Click "Skills" → Browse GitHub repos → One-click install to supported apps
+- **Sessions**: Click "Sessions" → Browse, search, and restore conversation history across supported session sources

 > **Note**: On first launch, you can manually import existing CLI tool configs as the default provider.

@@ -297,7 +358,6 @@ Download the latest `CC-Switch-v{version}-Windows.msi` installer or `CC-Switch-v
 **Method 1: Install via Homebrew (Recommended)**

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

@@ -368,7 +428,7 @@ Download the latest Linux build from the [Releases](../../releases) page:
 - **ProviderService**: Provider CRUD, switching, backfill, sorting
 - **McpService**: MCP server management, import/export, live file sync
 - **ProxyService**: Local proxy mode with hot-switching and format conversion
- **SessionManager**: Conversation history browsing across all supported apps
+- **SessionManager**: Conversation history browsing across supported session sources
 - **ConfigService**: Config import/export, backup rotation
 - **SpeedtestService**: API endpoint latency measurement

@@ -490,7 +550,7 @@ pnpm test:unit --coverage
 │   ├── lib/
 │   │   ├── api/                # Tauri API wrapper (type-safe)
 │   │   └── query/              # TanStack Query config
-│   ├── locales/                # Translations (zh/en/ja)
+│   ├── locales/                # Translations (zh/zh-TW/en/ja)
 │   ├── config/                 # Presets (providers/mcp)
 │   └── types/                  # TypeScript definitions
 ├── src-tauri/                  # Backend (Rust)
@@ -0,0 +1,589 @@
+<div align="center">
+
+# CC Switch
+
+### Der All-in-One-Manager für Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw & Hermes Agent
+
+[![Version](https://img.shields.io/github/v/release/farion1231/cc-switch?color=blue&label=version)](https://github.com/farion1231/cc-switch/releases)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/farion1231/cc-switch/releases)
+[![Built with Tauri](https://img.shields.io/badge/built%20with-Tauri%202-orange.svg)](https://tauri.app/)
+[![Downloads](https://img.shields.io/github/downloads/farion1231/cc-switch/total)](https://github.com/farion1231/cc-switch/releases/latest)
+
+<a href="https://trendshift.io/repositories/15372" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15372" alt="farion1231%2Fcc-switch | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+<a href="https://www.star-history.com/#farion1231/cc-switch&Date"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=farion1231/cc-switch&theme=dark" /><img alt="Star History Rank" src="https://api.star-history.com/badge?repo=farion1231/cc-switch" width="196" height="55" /></picture></a>
+
+### 🌐 Die einzige offizielle Website: **[ccswitch.io](https://ccswitch.io)**
+
+[English](README.md) | [中文](README_ZH.md) | [日本語](README_JA.md) | Deutsch | [Changelog](CHANGELOG.md)
+
+</div>
+
+## ❤️Sponsoren
+
+> [Möchten Sie hier erscheinen?](mailto:farion1231@gmail.com)
+
+<details open>
+<summary>Zum Einklappen klicken</summary>
+
+[![Kimi K2.7 Code](https://gcdn.moonshot.cn/growth-cdn/sponsor/kimi-en.png)](https://platform.kimi.ai?aff=cc-switch)
+
+Kimi K3 ist das bislang leistungsstärkste Modell von Moonshot AI und das weltweit erste offene Modell der 3T-Klasse. Mit 2,8 Billionen Parametern, nativen visuellen Fähigkeiten und einem Kontextfenster von 1 Million Token liefert K3 Spitzenleistung bei langfristigen Programmieraufgaben, Wissensarbeit und Reasoning. Mit CC Switch lässt sich Kimi in den verschiedensten Agenten-Tools bequem konfigurieren und umschalten. **[Hier klicken, um Kimi zu nutzen](https://platform.kimi.ai?aff=cc-switch)**
+
+Hauptsächlich mit Programmierung beschäftigt? Probieren Sie das **[Kimi-Code-Abo](https://www.kimi.com/code/?aff=cc-switch)** aus!
+
+---
+
+<table>
+<tr>
+<td width="180"><a href="https://www.packyapi.com/register?aff=cc-switch"><img src="assets/partners/logos/packycode.png" alt="PackyCode" width="150"></a></td>
+<td>Danke an PackyCode für die Unterstützung dieses Projekts! PackyCode ist ein zuverlässiger und effizienter API-Relay-Anbieter, der Relay-Dienste für Claude Code, Codex, Gemini und mehr bereitstellt. PackyCode bietet Sonderrabatte für Nutzer unserer Software: Registrieren Sie sich über <a href="https://www.packyapi.com/register?aff=cc-switch">diesen Link</a> und geben Sie beim ersten Aufladen den Gutscheincode „cc-switch" ein, um 10 % Rabatt zu erhalten.</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://zetaapi.ai/go/u117"><img src="assets/partners/logos/zetaapi-banner.png" alt="ZetaAPI" width="150"></a></td>
+<td>Danke an ZetaAPI für die Unterstützung dieses Projekts! ZetaAPI legt den Fokus auf echte Modelltreue — keine verwässerten Antworten, keine Qualitätsminderung — und Preise von nur 35 % der offiziellen Tarife. Die Plattform mischt keinen Traffic, ersetzt Modelle nicht heimlich durch minderwertige Alternativen und nutzt kein gefälschtes Modell-Routing. Sie unterstützt Claude Code, Codex, Gemini, ChatGPT und weitere gängige KI-Modelle und hilft Nutzern, die API-Kosten deutlich zu senken und gleichzeitig eine zuverlässige Modellqualität zu gewährleisten. Gleichzeitig bietet ZetaAPI eine SLA-gestützte Stabilität auf Unternehmensniveau, Standard-API-Kompatibilität, einen API-Key für mehrere Modelle, schnelle Integration und nutzungsbasierte Abrechnung — geeignet für KI-Produkte, Coding-Agents, interne Unternehmenstools, Kundenservice-Systeme, Content-Erstellung und Automatisierungs-Workflows. Falls bei einem Modell nachgewiesen wird, dass es nicht der angegebenen Qualität entspricht, sichert ZetaAPI dies mit einer 10-fachen Entschädigungsgarantie ab und bietet Nutzern ein stabileres, transparenteres und vertrauenswürdigeres Erlebnis. Registrieren Sie sich über <a href="https://zetaapi.ai/go/u117">diesen Link</a> und verwenden Sie bei Ihrer ersten Aufladung den Promo-Code CC-SWITCH, um als CC-Switch-Nutzer einen exklusiven Rabatt von 10 % auf Ihre erste Aufladung zu erhalten!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://apinebula.com/VjM74M"><img src="assets/partners/logos/apinebula_banner.png" alt="APINebula" width="150"></a></td>
+<td>Danke an APINEBULA für die Unterstützung dieses Projekts! APINEBULA ist eine Enterprise-KI-Aggregationsplattform unter Galaxy Video Bureau und nutzt umfangreiche Plattformressourcen, um Entwicklern, Teams und Unternehmen stabilen und kosteneffizienten Zugang zu APIs großer Sprachmodelle zu bieten. Die Plattform bündelt führende vollwertige Modelle wie Claude, GPT und Gemini. Über eine einzige API erhalten Sie Zugriff auf weltweit führende KI-Modelle, mit Preisen ab 10 % des Originalpreises. APINEBULA ist für KI-Programmierung, Agent-Entwicklung und Integration in Geschäftssysteme ausgelegt und unterstützt enterprise-grade hohe Parallelität, formale Verträge, Firmenüberweisungen und Rechnungsstellung. APINEBULA bietet Nutzern dieser Software besondere Rabatte: Registrieren Sie sich über <a href="https://apinebula.com/VjM74M">diesen Link</a> und geben Sie beim ersten Aufladen den Aktionscode <strong>"ccswitch"</strong> ein, um <strong>10 % Rabatt</strong> zu erhalten.</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.aicodemirror.com/register?invitecode=9915W3"><img src="assets/partners/logos/aicodemirror.jpg" alt="AICodeMirror" width="150"></a></td>
+<td>Danke an AICodeMirror für die Unterstützung dieses Projekts! AICodeMirror stellt offizielle, hochstabile Relay-Dienste für Claude Code / Codex / Gemini CLI bereit, mit unternehmensgerechter Nebenläufigkeit, schneller Rechnungsstellung und rund um die Uhr verfügbarem dediziertem technischem Support.
+Offizielle Kanäle von Claude Code / Codex / Gemini zu 38 % / 2 % / 9 % des Originalpreises, mit zusätzlichen Rabatten beim Aufladen! AICodeMirror bietet besondere Vorteile für CC-Switch-Nutzer: Registrieren Sie sich über <a href="https://www.aicodemirror.com/register?invitecode=9915W3">diesen Link</a> und erhalten Sie 20 % Rabatt auf Ihre erste Aufladung; Unternehmenskunden erhalten bis zu 25 % Rabatt!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://pateway.ai/?ch=etzpm8&aff=WB6M6F67#/"><img src="assets/partners/logos/pateway.png" alt="PatewayAI" width="150"></a></td>
+<td>Danke an PatewayAI für die Unterstützung dieses Projekts! PatewayAI ist ein API-Relay-Anbieter für anspruchsvolle KI-Entwickler, der sich auf das direkte Relayen offizieller hochwertiger Modell-APIs konzentriert. Er bietet die komplette Claude-Reihe und die Codex-Serie, zu 100 % aus offiziellen Kanälen bezogen — keine Verwässerung, keine Fälschungen, Überprüfung ausdrücklich erwünscht. Die Abrechnung ist transparent, und jede Rechnung auf Token-Ebene lässt sich Zeile für Zeile prüfen.
+Er unterstützt zudem unternehmensgerechte Nebenläufigkeit und stellt Unternehmenskunden eine dedizierte Verwaltungsplattform bereit — formelle Verträge und Rechnungsstellung sind verfügbar; Kontaktdaten finden Sie auf der offiziellen Website.
+Registrieren Sie sich jetzt über <a href="https://pateway.ai/?ch=etzpm8&aff=WB6M6F67#/">diesen Link</a> und erhalten Sie ein Testguthaben von 3 $. Aufladungen sind ab 60 % des Originalpreises möglich, mit einem beidseitigen Empfehlungsbonus von bis zu 150 $!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://api.fenno.ai/register?redirect=/purchase?tab=subscription%26group=16&aff=P9MR3D3PLCNL"><img src="assets/partners/logos/fenno-banner.png" alt="Fenno.ai" width="150"></a></td>
+<td>Danke an Fenno.ai für die Unterstützung dieses Projekts! Fenno.ai ist ein stabiler und effizienter API-Relay-Dienstleister, der sich derzeit hauptsächlich auf Codex-Relay konzentriert. Er ist mit den OpenAI- und Anthropic-Protokollen kompatibel und lässt sich flexibel mit Codex, Claude Code, OpenCode und anderen gängigen Coding-Tools nutzen. Er unterstützt zuverlässig Workloads auf Unternehmensniveau von Hunderten Milliarden Tokens pro Tag und bietet B2B-Abrechnung sowie Rechnungsstellung für Unternehmen im In- und Ausland. Fenno.ai bietet einen exklusiven Vorteil für CC-Switch-Nutzer: Abonnieren Sie über <a href="https://api.fenno.ai/register?redirect=/purchase?tab=subscription%26group=16&aff=P9MR3D3PLCNL">diesen Link</a> den unschlagbaren ¥9,9-Coding-Plan im Wert von $150 Guthaben und erhalten Sie bis zu 20% Empfehlungsprämien — je mehr Einladungen, desto mehr Belohnung!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://runapi.co/register?aff=iOKB"><img src="assets/partners/logos/runapi.jpg" alt="RunAPI" width="150"></a></td>
+<td>Danke an RunAPI für die Unterstützung dieses Projekts! RunAPI ist ein leistungsstarkes und zuverlässiges KI-Modell-API-Gateway — ein API-Schlüssel gibt Ihnen Zugriff auf mehr als 150 gängige Modelle, darunter OpenAI, Claude, Gemini, DeepSeek und Grok, zu Preisen ab 10 % des offiziellen Tarifs und mit ausgezeichneter Stabilität. Es arbeitet nahtlos mit Claude Code, OpenClaw und weiteren Werkzeugen zusammen. Exklusiver Vorteil für CC-Switch-Nutzer: Registrieren Sie sich über <a href="https://runapi.co/register?aff=iOKB">diesen Link</a> und erhalten Sie 10 % Rabatt auf Ihre erste Aufladung!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://unity2.ai/register?source=ccs"><img src="assets/partners/logos/unity2.jpg" alt="Unity2.ai" width="150"></a></td>
+<td>Danke an Unity2.ai für die Unterstützung dieses Projekts! Unity2.ai ist eine leistungsstarke AI-Modell-API-Relay-Plattform für Einzelentwickler, Teams und Unternehmen. Sie wird seit Langem von führenden Unternehmen in China genutzt, verarbeitet täglich über 30 Milliarden Tokens und unterstützt hohe Parallelität auf 5.000-RPM-Niveau. Geboten werden Guthaben-Abrechnung, Ersteinzahlungsbonus, Kombi-Abonnements, Firmenrechnungen und persönliche Betreuung. Registrieren Sie sich über <a href="https://unity2.ai/register?source=ccs">diesen Link</a> und erhalten Sie $2 Guthaben, plus weitere $10 für den Beitritt zur offiziellen Gruppe — bis zu $12 Gratis-Guthaben!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF"><img src="assets/partners/logos/shengsuanyun.png" alt="Shengsuanyun" width="150"></a></td>
+<td>Danke an Shengsuanyun für die Unterstützung dieses Projekts! Shengsuanyun ist eine Superfabrik für KI-native Teams — eine Plattform zur parallelen Ausführung von KI-Aufgaben in industrieller Qualität. Ihr Modellmarktplatz bündelt die Fähigkeiten von Claude, ChatGPT, Gemini und weiteren in- und ausländischen LLM- und Multimedia-Modellen mit Direktbezug. Absolut kein Reverse Engineering und keine Verwässerung — die plattformweite Modell-SLA-Verfügbarkeit erreicht 99,7 %, und die <a href="https://watch.shengsuanyun.com/status/shengsuanyun">Monitoring-Dashboards</a> zeigen durchgehend grün an. Es bietet außerdem unternehmensgerechte, anpassbare Gateways für fein abgestufte Kosten- und Berechtigungsverwaltung im Team, intelligentes Routing, Sicherheitsschutz und BYOK-Hosting (Bring Your Own Key). Die Plattform rechnet nach Nutzung sowie über einen Token-Plan (in Kürze verfügbar) ab, und Rechnungsstellung ist möglich. Registrieren Sie sich über <a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF">diesen Link</a> als Neukunde und erhalten Sie ein Guthaben von ¥10 sowie 10 % Bonus auf Ihre erste Aufladung.</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://aigocode.com/invite/CC-SWITCH"><img src="assets/partners/logos/aigocode.png" alt="AIGoCode" width="150"></a></td>
+<td>Danke an AIGoCode für die Unterstützung dieses Projekts! AIGoCode ist eine All-in-One-Plattform, die Claude Code, Codex und die neuesten Gemini-Modelle integriert und Ihnen stabile, effiziente und äußerst kostengünstige KI-Coding-Dienste bietet. Die Plattform stellt flexible Abonnementpläne bereit, birgt kein Risiko einer Kontosperrung, ermöglicht Direktzugriff ohne VPN und reagiert blitzschnell. AIGoCode hat ein besonderes Angebot für CC-Switch-Nutzer vorbereitet: Wenn Sie sich über <a href="https://aigocode.com/invite/CC-SWITCH">diesen Link</a> registrieren, erhalten Sie bei Ihrer ersten Aufladung zusätzliche 10 % Bonusguthaben!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://subrouter.ai/register?aff=l3ri"><img src="assets/partners/logos/subrouter-banner.png" alt="SubRouter" width="150"></a></td>
+<td>Danke an SubRouter für die Unterstützung dieses Projekts! SubRouter ist ein Marktplatz und eine intelligente Routing-Plattform für Betreiber von KI-Diensten. Händler können eigene Betriebsseiten starten, Pakete veröffentlichen sowie Nutzer, Modelle und Preise verwalten, während Nutzer im Marktplatz Dienste entdecken und über eine einzige einheitliche API zuverlässige und effiziente Modellaufrufe nutzen. Registrieren Sie sich über <a href="https://subrouter.ai/register?aff=l3ri">diesen Link</a>!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://apikey.fun/register?aff=CCSwitch"><img src="assets/partners/logos/apikey_banner.png" alt="APIKEY.FUN" width="150"></a></td>
+<td>Danke an APIKEY.FUN für die Unterstützung dieses Projekts! APIKEY.FUN ist eine professionelle KI-Relay-Plattform auf Enterprise-Niveau, die Unternehmen und einzelnen Entwicklern stabilen, effizienten und kostengünstigen Zugriff auf KI-Modell-APIs bietet. Die Plattform unterstützt beliebte Mainstream-Modelle wie Claude, OpenAI und Gemini, mit Preisen ab 7 % der offiziellen Tarife. Wer sich über den <a href="https://apikey.fun/register?aff=CCSwitch">exklusiven Link</a> dieses Projekts registriert, kann ein exklusives Angebot von bis zu <strong>dauerhaft 5 % Rabatt auf Aufladungen</strong> erhalten.</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://console.claudeapi.com/register?aff=pCLD"><img src="assets/partners/logos/claudeapi.png" alt="ClaudeAPI" width="150"></a></td>
+<td>Dieses Projekt wird von <a href="https://console.claudeapi.com/register?aff=pCLD">Claude API</a> gesponsert. Direkter Claude-API-Zugriff — verbinden Sie Claude Code und Agent-Apps in 3 Minuten. Neukunden können ein kostenloses Testguthaben einlösen. Betrieben mit offiziellen Anthropic-API-Schlüsseln + offiziellen AWS-Bedrock-Kanälen. Kein Reverse Engineering, keine Modellverschlechterung. Volle Unterstützung der Modellreihe Opus / Sonnet / Haiku, mit erhaltenen offiziellen Fähigkeiten einschließlich Tool Use, 1M-Kontextfenster und mehr. Entwickelt für Claude-Code-Power-User, Agent-Ingenieure und technische Unternehmensteams. Rechnungsstellung und dedizierter Team-Support verfügbar. Klicken Sie <a href="https://console.claudeapi.com/register?aff=pCLD">hier</a>, um sich zu registrieren!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://code0.ai/agent/register/B2XHxGjGmRvqgznY"><img src="assets/partners/logos/code0.png" alt="code0.ai" width="150"></a></td>
+<td>Vielen Dank an <a href="https://code0.ai/agent/register/B2XHxGjGmRvqgznY">code0.ai</a> für die Unterstützung dieses Projekts! code0.ai ist eine für Entwickler entwickelte AI-Coding-Service-Plattform, die Claude Code, Codex, Gemini und weitere gängige AI-Coding-Funktionen unterstützt. Sie hilft einzelnen Entwicklern und Teams, AI-Agents stabiler und effizienter für Programmierung, Debugging, Refactoring und Automatisierungs-Workflows zu nutzen. ccswitch-Nutzer können über die <a href="https://code0.ai/agent/register/B2XHxGjGmRvqgznY">code0.ai-Website</a> den Kundensupport kontaktieren, um Testguthaben zu erhalten und einen zuverlässigen AI-Coding-Service zu erleben.</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://teamorouter.com/?utm_source=cc_switch&utm_medium=referral&utm_campaign=ai_directory"><img src="assets/partners/logos/TeamoRouter-banner.png" alt="TeamoRouter" width="150"></a></td>
+<td>Danke an TeamoRouter für die Unterstützung dieses Projekts! TeamoRouter ist ein Agentic-LLM-Gateway in Enterprise-Qualität, das für Entwickler, KI-Teams und Unternehmen entwickelt wurde. Ganz ohne Abonnement können Sie über eine einzige einheitliche API auf Claude Code, Codex, Gemini CLI, OpenAI Codex und weitere beliebte KI-Agenten zugreifen — bei API-Preisen mit Rabatten von bis zu 90 %.
+Anders als typische API-Relay-Dienste bündelt TeamoRouter Hunderte offizieller Modellanbieter und vertrauenswürdiger Infrastrukturpartner, darunter OpenAI, Anthropic, Vertex, Azure und AWS Bedrock. Jeder Anbieter wird auf 100%ige Kompatibilität mit dem Agent-Protokoll, Cache-Performance und Nachverfolgbarkeit von Anfragen geprüft und liefert so stabile Qualität statt reverse-engineerter oder verwässerter Endpunkte. Die Plattform bietet nahezu offizielle TTFT, 99,6 % SLA, Durchsatz in Unternehmensgröße von bis zu 5.000 QPM und branchenführende Cache-Trefferquoten, die die Token-Kosten für langlaufende Agent-Workflows drastisch senken.
+TeamoRouter bietet außerdem Enterprise-Funktionen wie zentrale Abrechnung, Team-Verwaltung, BYOK, intelligentes Routing, Nutzungsanalysen, dynamische Anbieter-Optimierung und dedizierten Support. Für ein noch einfacheres Erlebnis können Sie mit Teamo Desktop Claude Code, Codex, Gemini CLI und weitere beliebte KI-Agenten per Ein-Klick-Einrichtung nutzen — ohne Verwaltung von API-Schlüsseln oder manuelle Gateway-Konfiguration. Registrieren Sie sich als neuer Nutzer über <a href="https://teamorouter.com/?utm_source=cc_switch&utm_medium=referral&utm_campaign=ai_directory">diesen Link</a> und erhalten Sie 10 % Rabatt auf Ihre erste Aufladung.</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.newapi.ai/"><img src="assets/partners/logos/newapi-banner.png" alt="new-api" width="150"></a></td>
+<td>Vielen Dank an das Open-Source-KI-Infrastrukturprojekt <a href="https://www.newapi.ai/">new-api</a> für die tatkräftige Unterstützung dieses Projekts! new-api ist ein Open-Source-KI-Infrastrukturprojekt von QuantumNous und eines der nach Aktivität und Verbreitung führenden Projekte für den einheitlichen Zugang zu und die Verteilung von LLMs, das sich darauf konzentriert, Entwicklern, Teams und Unternehmen beim Aufbau verwaltbarer und skalierbarer KI-Serviceplattformen zu geringeren Kosten zu helfen. Als ein ebenfalls im Open-Source-Ökosystem verwurzeltes Projekt möchte new-api durch Sponsoring die kontinuierliche Weiterentwicklung weiterer herausragender Open-Source-Projekte unterstützen. 🌟 Unterstützen Sie new-api mit einem Star: <a href="https://github.com/QuantumNous/new-api">https://github.com/QuantumNous/new-api</a>. Website: <a href="https://www.newapi.ai/">https://www.newapi.ai/</a>.</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://claudecn.ai/register?aff=HEL9"><img src="assets/partners/logos/claudecn.jpg" alt="ClaudeCN" width="150"></a></td>
+<td>Danke an ClaudeCN für die Unterstützung dieses Projekts! ClaudeCN ist eine unternehmensgerechte KI-Gateway-Plattform, die von einem eingetragenen Unternehmen betrieben wird. Sie bietet hochverfügbaren kommerziellen API-Zugriff auf beliebte Modelle wie Claude, GPT und DeepSeek und ist auf formelle Unternehmensbeschaffungsprozesse ausgerichtet — Banküberweisungen von Firmen, unterzeichnete Verträge und volle Compliance. Registrieren Sie sich über <a href="https://claudecn.ai/register?aff=HEL9">diesen Link</a>!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.byteplus.com/en/product/modelark?utm_campaign=hw&utm_content=ccswitch&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch"><img src="assets/partners/logos/byteplus.png" alt="BytePlus" width="150"></a></td>
+<td>Danke an Dola seed für die Unterstützung dieses Projekts! Dola Seed 2.0 ist ein voll-modales Allzweck-Großmodell, das von ByteDance eigenständig für den globalen Markt entwickelt wurde. Aufbauend auf einer einheitlichen multimodalen Architektur unterstützt es das gemeinsame Verstehen und Generieren von Text, Bildern, Audio und Video. Es ermöglicht von Haus aus die Zusammenarbeit von Agenten und verfügt über starke Fähigkeiten in den Bereichen Schlussfolgern, Ausführung langer Aufgaben, Werkzeugintegration und Programmierung. Es ist breit einsetzbar — etwa für intelligente Cockpits, persönliche Assistenten, Bildung, Kundensupport, Marketing, Einzelhandel und weitere Szenarien. Es überzeugt bei multimodaler Wahrnehmung, der Ende-zu-Ende-Bewältigung komplexer Aufgaben, stabiler Interaktion und Datensicherheit und ist über die ModelArk-Plattform einfach zugänglich und bereitstellbar. Registrieren Sie sich über <a href="https://www.byteplus.com/en/product/modelark?utm_campaign=hw&utm_content=ccswitch&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch">diesen Link</a> und erhalten Sie pro Modell ein kostenloses Inferenzkontingent von 500.000 Token.<a href="https://www.volcengine.com/activity/ai618?utm_campaign=hw&utm_content=hw&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch"> >>中国大陆地区的开发者请点击这里</a></td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://cloud.siliconflow.cn/i/YflgU2Ve"><img src="assets/partners/logos/silicon_en.jpg" alt="SiliconFlow" width="150"></a></td>
+<td>Danke an SiliconFlow für die Unterstützung dieses Projekts! SiliconFlow ist eine leistungsstarke KI-Infrastruktur- und Modell-API-Plattform, die schnellen und zuverlässigen Zugriff auf Sprach-, Audio-, Bild- und Videomodelle an einem Ort bietet. Mit nutzungsbasierter Abrechnung, breiter Unterstützung multimodaler Modelle, Hochgeschwindigkeitsinferenz und unternehmensgerechter Stabilität hilft SiliconFlow Entwicklern und Teams, KI-Anwendungen effizienter zu erstellen und zu skalieren. Registrieren Sie sich über <a href="https://cloud.siliconflow.cn/i/YflgU2Ve">diesen Link</a> und schließen Sie die Identitätsverifizierung ab, um ein Bonusguthaben von ¥16 zu erhalten, das für alle Modelle der Plattform nutzbar ist. SiliconFlow ist zudem nun mit OpenClaw kompatibel, sodass Nutzer einen SiliconFlow-API-Schlüssel verbinden und große KI-Modelle kostenlos aufrufen können.</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://nekocode.ai?aff=CCSWITCH"><img src="assets/partners/logos/nekocode-banner.png" alt="NekoCode" width="150"></a></td>
+<td>Vielen Dank an <a href="https://nekocode.ai?aff=CCSWITCH">NekoCode</a> für die Unterstützung dieses Projekts! NekoCode bietet Entwicklern einen stabilen, effizienten und zuverlässigen API-Relay-Dienst für Claude, Codex und weitere KI-Modelle. Mit transparenter Preisgestaltung und flexibler nutzungsbasierter Abrechnung bietet es einen einfachen und kostengünstigen Zugang zu KI-Modellen. CC-Switch-Nutzer erhalten einen exklusiven Rabatt von 10 %: Registrieren Sie sich über <a href="https://nekocode.ai?aff=CCSWITCH">diesen Link</a> und geben Sie beim Aufladen den Gutscheincode <code>cc-switch</code> ein, um 10 % Rabatt auf Ihre Aufladung zu erhalten!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.atlascloud.ai/coding-plan?utm_source=github&utm_campaign=cc-switch"><img src="assets/partners/logos/atlascloud_banner.png" alt="Atlas Cloud" width="150"></a></td>
+<td>Atlas Cloud ist eine vollmodale KI-Inferenzplattform, die Entwicklern über eine einzige KI-API Zugriff auf Videogenerierung, Bildgenerierung und LLM-APIs bietet. Statt mehrere Anbieterintegrationen zu verwalten, verbinden Sie sich einmal und erhalten einheitlichen Zugriff auf mehr als 300 kuratierte Modelle über alle Modalitäten hinweg. Sehen Sie sich die neue <a href="https://www.atlascloud.ai/coding-plan?utm_source=github&utm_campaign=cc-switch">Coding-Plan</a>-Aktion von Atlas Cloud für kostengünstigeren API-Zugang an!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.compshare.cn/coding-plan?ytag=GPU_YY_YX_git_cc-switch"><img src="assets/partners/logos/ucloud.png" alt="Compshare" width="150"></a></td>
+<td>Danke an Compshare für die Unterstützung dieses Projekts! Compshare ist die KI-Cloud-Plattform von UCloud, die mit nur einem Schlüssel stabile und umfassende in- und ausländische Modell-APIs bereitstellt. Sie bietet kostengünstige Coding-Plan-Pakete für inländische Modelle mit monatlicher und nutzungsbasierter Abrechnung sowie stabile, offiziell gerelayte ausländische Modelle. Unterstützt Claude Code, Codex und API-Zugriff. Unternehmensgerechte hohe Nebenläufigkeit, technischer Support rund um die Uhr und Self-Service-Rechnungsstellung. Wer sich über <a href="https://www.compshare.cn/coding-plan?ytag=GPU_YY_YX_git_cc-switch">diesen Link</a> registriert, erhält ein kostenloses Plattform-Testguthaben von 5 CNY!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.ccsub.net/register?ref=Y6Z8DXEA"><img src="assets/partners/logos/ccsub.svg" alt="CCSub" width="150"></a></td>
+<td>Danke an CCSub für die Unterstützung dieses Projekts! CCSub ist eine zuverlässige und kostengünstige AI-API-Relay-Plattform — Ihr direkter Ersatz für ein Claude.ai-Abonnement. Mit einem einzigen API-Schlüssel erhalten Sie Zugriff auf Claude Opus 4.8, Sonnet, Haiku, GPT-5, Gemini und DeepSeek zu etwa 30 % der Kosten der direkten API-Nutzung — ohne VPN, weltweit nutzbar. Kompatibel mit Claude Code, Codex, Cursor, Cline, Continue, Windsurf und allen gängigen AI-Coding-Tools. Registrieren Sie sich über <a href="https://www.ccsub.net/register?ref=Y6Z8DXEA">diesen Link</a> und erhalten Sie $5 Startguthaben bei der Anmeldung.</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.sssaicode.com/register?ref=DCP0SM"><img src="assets/partners/logos/sssaicode.png" alt="SSSAiCode" width="150"></a></td>
+<td>Danke an SSSAiCode für die Unterstützung dieses Projekts! SSSAiCode ist ein stabiler und zuverlässiger API-Relay-Dienst, der sich der Bereitstellung stabiler, zuverlässiger und erschwinglicher Claude- und Codex-Modelldienste widmet, mit schneller Rechnungsstellung am selben Tag. SSSAiCode bietet ein besonderes Angebot für CC-Switch-Nutzer: Registrieren Sie sich über <a href="https://www.sssaicode.com/register?ref=DCP0SM">diesen Link</a> und erhalten Sie bei jeder Aufladung 10 $ zusätzliches Guthaben!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.micuapi.ai/register?aff=aOYQ"><img src="assets/partners/logos/mikubanner.svg" alt="Micu" width="150"></a></td>
+<td>Danke an Micu API für die Unterstützung dieses Projekts! Micu API ist ein globaler LLM-Relay-Anbieter, der sich der Bereitstellung des besten Preis-Leistungs-Verhältnisses bei hoher Stabilität widmet. Gestützt auf ein eingetragenes Unternehmen als Kernabsicherung wird jedes Risiko einer Diensteinstellung ausgeschlossen, mit schneller offizieller Rechnungsstellung! Wir stehen für „kostenloses Ausprobieren": Aufladungen sind schon ab ¥1 ohne Mindestbetrag möglich, und gebührenfreie Rückerstattungen sind jederzeit möglich! Micu API bietet ein exklusives Angebot für CC-Switch-Nutzer: Registrieren Sie sich über <a href="https://www.micuapi.ai/register?aff=aOYQ">diesen Link</a> und geben Sie beim Aufladen den Gutscheincode „ccswitch" ein, um <strong>10 % Rabatt</strong> zu erhalten!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.right.codes/register?aff=CCSWITCH"><img src="assets/partners/logos/rightcode.jpg" alt="RightCode" width="150"></a></td>
+<td>Danke an Right Code für die Unterstützung dieses Projekts! Right Code stellt zuverlässig Routing-Dienste für Modelle wie Claude Code, Codex und Gemini bereit, wahlweise mit nutzungsbasierter Abrechnung oder monatlichem Abonnement. Rechnungen sind beim Aufladen verfügbar, und Unternehmens- sowie Teamkunden erhalten dedizierten Einzelsupport. Right Code bietet außerdem einen exklusiven Rabatt für CC-Switch-Nutzer: Registrieren Sie sich über <a href="https://www.right.codes/register?aff=CCSWITCH">diesen Link</a> und erhalten Sie bei jeder Aufladung nutzungsbasiertes Guthaben in Höhe von 5 % des gezahlten Betrags.</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://etok.ai"><img src="assets/partners/logos/etok.png" alt="ETok" width="150"></a></td>
+<td>Danke an ETok.ai für die Unterstützung dieses Projekts! ETok.ai widmet sich dem Aufbau einer Komplettlösung für KI-Programmierwerkzeuge. Wir bieten professionelle Claude-Code-Pakete und Dienste einer technischen Community, mit Unterstützung für Google Gemini und OpenAI Codex. Durch sorgfältig gestaltete Pläne und eine professionelle Tech-Community geben wir Entwicklern verlässliche Servicegarantien und kontinuierlichen technischen Support an die Hand und machen KI-gestützte Programmierung zu einem echten Produktivitätswerkzeug. Klicken Sie <a href="https://etok.ai">hier</a>, um sich zu registrieren!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://cubence.com/signup?code=CCSWITCH&source=ccs"><img src="assets/partners/logos/cubence.png" alt="Cubence" width="150"></a></td>
+<td>Danke an Cubence für die Unterstützung dieses Projekts! Cubence ist ein zuverlässiger und effizienter API-Relay-Anbieter, der Relay-Dienste für Claude Code, Codex, Gemini und mehr mit flexiblen Abrechnungsoptionen einschließlich nutzungsbasierter und monatlicher Pläne bereitstellt. Cubence bietet Sonderrabatte für CC-Switch-Nutzer: Registrieren Sie sich über <a href="https://cubence.com/signup?code=CCSWITCH&source=ccs">diesen Link</a> und geben Sie beim Aufladen den Gutscheincode „CCSWITCH" ein, um bei jeder Aufladung 10 % Rabatt zu erhalten!</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch"><img src="assets/partners/logos/crazyrouter.png" alt="Crazyrouter" width="150"></a></td>
+<td>Danke an Crazyrouter für die Unterstützung dieses Projekts! Crazyrouter ist eine leistungsstarke KI-API-Aggregationsplattform — ein API-Schlüssel für mehr als 300 Modelle, darunter Claude Code, Codex, Gemini CLI und weitere. Alle Modelle zu 55 % des offiziellen Preises, mit automatischem Failover, intelligentem Routing und unbegrenzter Nebenläufigkeit. Crazyrouter bietet ein exklusives Angebot für CC-Switch-Nutzer: Registrieren Sie sich über <a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch">diesen Link</a> und kontaktieren Sie den Kundensupport, um <strong>2 $ Gratisguthaben</strong> zu erhalten; geben Sie zusätzlich bei Ihrer ersten Aufladung den Gutscheincode `CCSWITCH` ein, um <strong>30 % Bonusguthaben</strong> zu bekommen! </td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.dmxapi.cn/register?aff=bUHu"><img src="assets/partners/logos/dmx-en.jpg" alt="DMXAPI" width="150"></a></td>
+<td>Danke an DMXAPI für die Unterstützung dieses Projekts! DMXAPI stellt mehr als 200 Unternehmenskunden globale Großmodell-API-Dienste bereit. Ein API-Schlüssel für alle Modelle weltweit. Zu den Funktionen gehören: sofortige Rechnungsstellung, unbegrenzte Nebenläufigkeit, ab 0,15 $, technischer Support rund um die Uhr. GPT/Claude/Gemini durchgehend zu 32 % Rabatt, inländische Modelle 20–50 % Rabatt, exklusive Claude-Code-Modelle zu 66 % Rabatt! <a href="https://www.dmxapi.cn/register?aff=bUHu">Hier registrieren</a></td>
+</tr>
+
+</table>
+
+</details>
+
+## Warum CC Switch?
+
+Modernes KI-gestütztes Programmieren stützt sich auf Werkzeuge wie Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw und Hermes — doch jedes hat sein eigenes Konfigurationsformat. Der Wechsel des API-Anbieters bedeutet, JSON-, TOML- oder `.env`-Dateien von Hand zu bearbeiten, und es gibt keine einheitliche Möglichkeit, MCP und Skills über mehrere Werkzeuge hinweg zu verwalten.
+
+**CC Switch** gibt Ihnen eine einzige Desktop-App, um alle unterstützten KI-Werkzeuge zu verwalten. Statt Konfigurationsdateien von Hand zu bearbeiten, erhalten Sie eine visuelle Oberfläche, um Anbieter mit einem Klick zu importieren und sofort zwischen ihnen zu wechseln — mit 50+ integrierten Anbieter-Presets, einheitlicher MCP- und Skills-Verwaltung und schnellem Umschalten über das System-Tray. Das Ganze gestützt auf eine zuverlässige SQLite-Datenbank mit atomaren Schreibvorgängen, die Ihre Konfigurationen vor Beschädigung schützen.
+
+- **Eine App, acht Werkzeuge** — Verwalten Sie Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw und Hermes über eine einzige Oberfläche
+- **Kein manuelles Bearbeiten mehr** — 50+ Anbieter-Presets einschließlich AWS Bedrock, NVIDIA NIM und Community-Relays; einfach auswählen und umschalten
+- **Einheitliche MCP- & Skills-Verwaltung** — Ein Panel zur Verwaltung von MCP-Servern und Skills für Claude, Codex, Gemini, Grok Build, OpenCode und Hermes mit bidirektionaler Synchronisierung
+- **Schnellumschaltung über System-Tray** — Wechseln Sie Anbieter sofort über das Tray-Menü, ohne die vollständige App öffnen zu müssen
+- **Cloud-Synchronisierung** — Synchronisieren Sie Anbieterdaten geräteübergreifend über Dropbox, OneDrive, iCloud oder WebDAV-Server
+- **Plattformübergreifend** — Native Desktop-App für Windows, macOS und Linux, gebaut mit Tauri 2
+- **Integrierte Hilfsprogramme** — Enthält diverse Hilfsprogramme für die Login-Bestätigung beim Erststart, das Umgehen von Signaturen, die Synchronisierung von Plugin-Erweiterungen und mehr
+
+## Screenshots
+
+|                  Hauptoberfläche                   |                  Anbieter hinzufügen                  |
+| :-----------------------------------------------: | :--------------------------------------------: |
+| ![Hauptoberfläche](assets/screenshots/main-en.png) | ![Anbieter hinzufügen](assets/screenshots/add-en.png) |
+
+## Funktionen
+
+[Vollständiges Changelog](CHANGELOG.md) | [Release Notes](docs/release-notes/v3.16.1-en.md)
+
+### Anbieterverwaltung
+
+- **8 unterstützte Werkzeuge, 50+ Presets** — Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes; Schlüssel kopieren und mit einem Klick importieren
+- **Universelle Anbieter** — Eine Konfiguration synchronisiert sich mit Claude Code, Codex und Gemini CLI
+- Umschaltung mit einem Klick, Schnellzugriff über System-Tray, Sortierung per Drag-and-drop, Import/Export
+
+### Proxy & Failover
+
+- **Lokaler Proxy mit Hot-Switching** — Formatkonvertierung, automatisches Failover, Circuit Breaker, Anbieter-Health-Monitoring und Request-Rectifier
+- **Übernahme auf App-Ebene** — Claude, Codex, Gemini oder Grok Build unabhängig über den Proxy leiten, bis hinunter auf einzelne Anbieter
+
+### MCP, Prompts & Skills
+
+- **Einheitliches MCP-Panel** — Verwalten Sie MCP-Server für Claude, Codex, Gemini, Grok Build, OpenCode und Hermes mit bidirektionaler Synchronisierung und Deep-Link-Import
+- **Prompts** — Markdown-Editor mit App-übergreifender Synchronisierung (CLAUDE.md / AGENTS.md / GEMINI.md) und Backfill-Schutz
+- **Skills** — Installation mit einem Klick aus GitHub-Repositorys oder ZIP-Dateien, Verwaltung eigener Repositorys, mit Unterstützung für Symlinks und Dateikopien
+
+### Nutzungs- & Kostenverfolgung
+
+- **Nutzungs-Dashboard** — Verfolgen Sie Ausgaben, Anfragen und Token mit Trenddiagrammen, detaillierten Anfrageprotokollen und eigener Preisgestaltung pro Modell
+
+### Session Manager & Workspace
+
+- Gesprächsverlauf aus unterstützten Sitzungsquellen durchsuchen, suchen und wiederherstellen
+- **Workspace-Editor** (OpenClaw) — Bearbeiten Sie Agent-Dateien (AGENTS.md, SOUL.md usw.) mit Markdown-Vorschau
+
+### System & Plattform
+
+- **Cloud-Synchronisierung** — Eigenes Konfigurationsverzeichnis (Dropbox, OneDrive, iCloud, NAS) und WebDAV-Server-Synchronisierung
+- **Deep Link** (`ccswitch://`) — Importieren Sie Anbieter, MCP-Server, Prompts und Skills per URL
+- Dunkles / Helles / System-Theme, automatischer Start, automatischer Updater, atomare Schreibvorgänge, automatische Backups, i18n (zh/zh-TW/en/ja)
+
+## FAQ
+
+<details>
+<summary><strong>Welche KI-Werkzeuge unterstützt CC Switch?</strong></summary>
+
+CC Switch unterstützt acht Werkzeuge: **Claude Code**, **Claude Desktop**, **Codex**, **Gemini CLI**, **Grok Build**, **OpenCode**, **OpenClaw** und **Hermes**. Jedes Werkzeug verfügt über dedizierte Anbieter-Presets und Konfigurationsverwaltung.
+
+</details>
+
+<details>
+<summary><strong>Muss ich das Terminal nach einem Anbieterwechsel neu starten?</strong></summary>
+
+Bei den meisten Werkzeugen ja — starten Sie Ihr Terminal oder das CLI-Werkzeug neu, damit die Änderungen wirksam werden. Die Ausnahme ist **Claude Code**, das derzeit das Hot-Switching von Anbieterdaten ohne Neustart unterstützt.
+
+</details>
+
+<details>
+<summary><strong>Meine Plugin-Konfiguration ist nach einem Anbieterwechsel verschwunden — was ist passiert?</strong></summary>
+
+CC Switch bietet eine Funktion „Gemeinsames Konfigurations-Snippet", um gemeinsame Daten (über API-Schlüssel und Endpunkte hinaus) zwischen Anbietern weiterzugeben. Gehen Sie zu „Anbieter bearbeiten" → „Panel für gemeinsame Konfiguration" → klicken Sie auf „Aus aktuellem Anbieter extrahieren", um alle gemeinsamen Daten zu speichern. Aktivieren Sie beim Anlegen eines neuen Anbieters die Option „Gemeinsame Konfiguration schreiben" (standardmäßig aktiviert), um die Plugin-Daten in den neuen Anbieter aufzunehmen. Alle Ihre Konfigurationspunkte bleiben im Standardanbieter erhalten, der beim ersten Start der App importiert wurde.
+
+</details>
+
+<details>
+<summary><strong>Installation unter macOS</strong></summary>
+
+CC Switch für macOS ist von Apple code-signiert und notarisiert. Sie können es direkt herunterladen und installieren — es sind keine zusätzlichen Schritte erforderlich. Wir empfehlen die Verwendung des `.dmg`-Installationsprogramms.
+
+</details>
+
+<details>
+<summary><strong>Warum kann ich den aktuell aktiven Anbieter nicht löschen?</strong></summary>
+
+CC Switch folgt dem Designprinzip der „minimalen Eingriffstiefe" — selbst wenn Sie die App deinstallieren, funktionieren Ihre CLI-Werkzeuge weiterhin normal. Das System behält immer eine aktive Konfiguration bei, da das Löschen aller Konfigurationen das entsprechende CLI-Werkzeug unbrauchbar machen würde. Wenn Sie ein bestimmtes CLI-Werkzeug selten verwenden, können Sie es in den Einstellungen ausblenden. Wie Sie zurück zum offiziellen Login wechseln, erfahren Sie in der nächsten Frage.
+
+</details>
+
+<details>
+<summary><strong>Wie wechsle ich zurück zum offiziellen Login?</strong></summary>
+
+Fügen Sie einen offiziellen Anbieter aus der Preset-Liste hinzu. Führen Sie nach dem Wechsel den Abmelde-/Anmelde-Vorgang aus; anschließend können Sie frei zwischen dem offiziellen Anbieter und Drittanbietern wechseln. Codex unterstützt den Wechsel zwischen verschiedenen offiziellen Anbietern, was das Umschalten zwischen mehreren Plus- oder Team-Konten erleichtert.
+
+</details>
+
+<details>
+<summary><strong>Wo werden meine Daten gespeichert?</strong></summary>
+
+- **Datenbank**: `~/.cc-switch/cc-switch.db` (SQLite — Anbieter, MCP, Prompts, Skills)
+- **Lokale Einstellungen**: `~/.cc-switch/settings.json` (gerätebezogene UI-Einstellungen)
+- **Backups**: `~/.cc-switch/backups/` (automatisch rotiert, behält die 10 neuesten)
+- **Skills**: `~/.cc-switch/skills/` (standardmäßig per Symlink mit den entsprechenden Apps verbunden)
+- **Skill-Backups**: `~/.cc-switch/skill-backups/` (vor der Deinstallation automatisch erstellt, behält die 20 neuesten)
+
+</details>
+
+<details>
+<summary><strong>Linux (Wayland + NVIDIA): Klicks im Webinhalt reagieren nicht, schwarzer Bildschirm beim Größenändern</strong></summary>
+
+Das AppImage erzwingt `GDK_BACKEND=x11` (XWayland), um einen historischen nativen Wayland-Absturz zu vermeiden. Auf neueren Wayland-+-NVIDIA-Systemen kann das dazu führen, dass der Webinhalt nicht anklickbar ist (die Titelleisten-Schaltflächen funktionieren weiterhin) und das Fenster beim Größenändern schwarz wird. Starten Sie mit dem optionalen Notausgang, um zu nativem Wayland zu wechseln:
+
+```bash
+CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
+```
+
+Wenn Sie über ein Desktop-Symbol starten, fügen Sie es der `Exec=`-Zeile der `.desktop`-Datei hinzu (z. B. `env CC_SWITCH_GDK_BACKEND=wayland /pfad/zum/AppImage`) oder setzen Sie es in Ihrer Sitzungsumgebung. Die Variable ist generisch: Auf Tiling-Wayland-Compositors (sway/Hyprland), bei denen Klicks nicht reagieren, versuchen Sie umgekehrt `CC_SWITCH_GDK_BACKEND=x11`. Bleibt sie ungesetzt, bleibt das Standardverhalten erhalten.
+
+</details>
+
+## Dokumentation
+
+Ausführliche Anleitungen zu jeder Funktion finden Sie im **[Benutzerhandbuch](docs/user-manual/en/README.md)** — es deckt Anbieterverwaltung, MCP/Prompts/Skills, Proxy & Failover und mehr ab.
+
+## Schnellstart
+
+### Grundlegende Verwendung
+
+1. **Anbieter hinzufügen**: Klicken Sie auf „Add Provider" → Wählen Sie ein Preset oder erstellen Sie eine eigene Konfiguration
+2. **Anbieter wechseln**:
+   - Hauptoberfläche: Anbieter auswählen → auf „Enable" klicken
+   - System-Tray: Anbietername direkt anklicken (sofort wirksam)
+3. **Wirksam werden**: Starten Sie Ihr Terminal oder das entsprechende CLI-Werkzeug neu, um die Änderungen anzuwenden (Claude Code erfordert keinen Neustart)
+4. **Zurück zum Offiziellen**: Fügen Sie ein „Official Login"-Preset hinzu, starten Sie das CLI-Werkzeug neu und folgen Sie dann seinem Login-/OAuth-Vorgang
+
+### MCP, Prompts, Skills & Sessions
+
+- **MCP**: Klicken Sie auf die Schaltfläche „MCP" → Server über Vorlagen oder eigene Konfiguration hinzufügen → Synchronisierung pro App umschalten
+- **Prompts**: Klicken Sie auf „Prompts" → Presets mit dem Markdown-Editor erstellen → Aktivieren, um mit den Live-Dateien zu synchronisieren
+- **Skills**: Klicken Sie auf „Skills" → GitHub-Repositorys durchsuchen → mit einem Klick in unterstützte Apps installieren
+- **Sessions**: Klicken Sie auf „Sessions" → Gesprächsverlauf aus unterstützten Sitzungsquellen durchsuchen, suchen und wiederherstellen
+
+> **Hinweis**: Beim Erststart können Sie bestehende CLI-Werkzeug-Konfigurationen manuell als Standardanbieter importieren.
+
+## Download & Installation
+
+### Systemanforderungen
+
+- **Windows**: Windows 10 und höher
+- **macOS**: macOS 12 (Monterey) und höher
+- **Linux**: Ubuntu 22.04+ / Debian 11+ / Fedora 34+ und andere gängige Distributionen
+
+### Windows-Nutzer
+
+Laden Sie das neueste Installationsprogramm `CC-Switch-v{version}-Windows.msi` oder die portable Version `CC-Switch-v{version}-Windows-Portable.zip` von der Seite [Releases](../../releases) herunter.
+
+### macOS-Nutzer
+
+**Methode 1: Installation über Homebrew (empfohlen)**
+
+```bash
+brew install --cask cc-switch
+```
+
+Aktualisieren:
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+**Methode 2: Manueller Download**
+
+Laden Sie `CC-Switch-v{version}-macOS.dmg` (empfohlen) oder `.zip` von der Seite [Releases](../../releases) herunter.
+
+> **Hinweis**: CC Switch für macOS ist von Apple code-signiert und notarisiert. Sie können es direkt installieren und öffnen.
+
+### Arch-Linux-Nutzer
+
+**Installation über paru (empfohlen)**
+
+```bash
+paru -S cc-switch-bin
+```
+
+### Linux-Nutzer
+
+Laden Sie den neuesten Linux-Build von der Seite [Releases](../../releases) herunter:
+
+- `CC-Switch-v{version}-Linux.deb` (Debian/Ubuntu)
+- `CC-Switch-v{version}-Linux.rpm` (Fedora/RHEL/openSUSE)
+- `CC-Switch-v{version}-Linux.AppImage` (universell)
+
+> **Flatpak**: Nicht in den offiziellen Releases enthalten. Sie können es selbst aus dem `.deb` bauen — eine Anleitung finden Sie unter [`flatpak/README.md`](flatpak/README.md).
+
+<details>
+<summary><strong>Architekturüberblick</strong></summary>
+
+### Designprinzipien
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Frontend (React + TS)                    │
+│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐    │
+│  │ Components  │  │    Hooks     │  │  TanStack Query  │    │
+│  │   (UI)      │──│ (Bus. Logic) │──│   (Cache/Sync)   │    │
+│  └─────────────┘  └──────────────┘  └──────────────────┘    │
+└────────────────────────┬────────────────────────────────────┘
+                         │ Tauri IPC
+┌────────────────────────▼────────────────────────────────────┐
+│                  Backend (Tauri + Rust)                     │
+│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐    │
+│  │  Commands   │  │   Services   │  │  Models/Config   │    │
+│  │ (API Layer) │──│ (Bus. Layer) │──│     (Data)       │    │
+│  └─────────────┘  └──────────────┘  └──────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Kern-Designmuster**
+
+- **SSOT** (Single Source of Truth): Alle Daten werden in `~/.cc-switch/cc-switch.db` (SQLite) gespeichert
+- **Zweischichtiger Speicher**: SQLite für synchronisierbare Daten, JSON für gerätebezogene Einstellungen
+- **Bidirektionale Synchronisierung**: Schreiben in Live-Dateien beim Umschalten, Backfill aus den Live-Dateien beim Bearbeiten des aktiven Anbieters
+- **Atomare Schreibvorgänge**: Das Muster aus temporärer Datei + Umbenennen verhindert die Beschädigung von Konfigurationen
+- **Nebenläufigkeitssicher**: Eine durch Mutex geschützte Datenbankverbindung vermeidet Race Conditions
+- **Geschichtete Architektur**: Klare Trennung (Commands → Services → DAO → Database)
+
+**Schlüsselkomponenten**
+
+- **ProviderService**: Anbieter-CRUD, Umschaltung, Backfill, Sortierung
+- **McpService**: Verwaltung von MCP-Servern, Import/Export, Synchronisierung von Live-Dateien
+- **ProxyService**: Lokaler Proxy-Modus mit Hot-Switching und Formatkonvertierung
+- **SessionManager**: Durchsuchen des Gesprächsverlaufs über alle unterstützten Apps hinweg
+- **ConfigService**: Konfigurations-Import/-Export, Backup-Rotation
+- **SpeedtestService**: Messung der Latenz von API-Endpunkten
+
+</details>
+
+<details>
+<summary><strong>Entwicklungsleitfaden</strong></summary>
+
+### Umgebungsanforderungen
+
+- Node.js 18+
+- pnpm 8+
+- Rust 1.85+
+- Tauri CLI 2.8+
+
+### Entwicklungsbefehle
+
+```bash
+# Abhängigkeiten installieren
+pnpm install
+
+# Entwicklungsmodus (Hot Reload)
+pnpm dev
+
+# Typprüfung
+pnpm typecheck
+
+# Code formatieren
+pnpm format
+
+# Codeformatierung prüfen
+pnpm format:check
+
+# Frontend-Unit-Tests ausführen
+pnpm test:unit
+
+# Tests im Watch-Modus ausführen (für die Entwicklung empfohlen)
+pnpm test:unit:watch
+
+# Anwendung bauen
+pnpm build
+
+# Debug-Version bauen
+pnpm tauri build --debug
+```
+
+### Entwicklung des Rust-Backends
+
+```bash
+cd src-tauri
+
+# Rust-Code formatieren
+cargo fmt
+
+# Clippy-Prüfungen ausführen
+cargo clippy
+
+# Backend-Tests ausführen
+cargo test
+
+# Bestimmte Tests ausführen
+cargo test test_name
+
+# Tests mit dem Feature test-hooks ausführen
+cargo test --features test-hooks
+```
+
+### Testleitfaden
+
+**Frontend-Tests**:
+
+- Verwendet **vitest** als Test-Framework
+- Verwendet **MSW (Mock Service Worker)**, um Tauri-API-Aufrufe zu mocken
+- Verwendet **@testing-library/react** für Komponententests
+
+**Tests ausführen**:
+
+```bash
+# Alle Tests ausführen
+pnpm test:unit
+
+# Watch-Modus (automatische erneute Ausführung)
+pnpm test:unit:watch
+
+# Mit Coverage-Bericht
+pnpm test:unit --coverage
+```
+
+### Tech-Stack
+
+**Frontend**: React 18 · TypeScript · Vite · TailwindCSS 3.4 · TanStack Query v5 · react-i18next · react-hook-form · zod · shadcn/ui · @dnd-kit
+
+**Backend**: Tauri 2.8 · Rust · serde · tokio · thiserror · tauri-plugin-updater/process/dialog/store/log
+
+**Testing**: vitest · MSW · @testing-library/react
+
+</details>
+
+<details>
+<summary><strong>Projektstruktur</strong></summary>
+
+```
+├── src/                        # Frontend (React + TypeScript)
+│   ├── components/
+│   │   ├── providers/          # Anbieterverwaltung
+│   │   ├── mcp/                # MCP-Panel
+│   │   ├── prompts/            # Prompts-Verwaltung
+│   │   ├── skills/             # Skills-Verwaltung
+│   │   ├── sessions/           # Session Manager
+│   │   ├── proxy/              # Proxy-Modus-Panel
+│   │   ├── openclaw/           # OpenClaw-Konfigurationspanels
+│   │   ├── settings/           # Einstellungen (Terminal/Backup/About)
+│   │   ├── deeplink/           # Deep-Link-Import
+│   │   ├── env/                # Verwaltung von Umgebungsvariablen
+│   │   ├── universal/          # App-übergreifende Konfiguration
+│   │   ├── usage/              # Nutzungsstatistik
+│   │   └── ui/                 # shadcn/ui-Komponentenbibliothek
+│   ├── hooks/                  # Eigene Hooks (Geschäftslogik)
+│   ├── lib/
+│   │   ├── api/                # Tauri-API-Wrapper (typsicher)
+│   │   └── query/              # TanStack-Query-Konfiguration
+│   ├── locales/                # Übersetzungen (zh/zh-TW/en/ja)
+│   ├── config/                 # Presets (providers/mcp)
+│   └── types/                  # TypeScript-Definitionen
+├── src-tauri/                  # Backend (Rust)
+│   └── src/
+│       ├── commands/           # Tauri-Befehlsschicht (nach Domäne)
+│       ├── services/           # Geschäftslogikschicht
+│       ├── database/           # SQLite-DAO-Schicht
+│       ├── proxy/              # Proxy-Modul
+│       ├── session_manager/    # Sitzungsverwaltung
+│       ├── deeplink/           # Deep-Link-Verarbeitung
+│       └── mcp/                # MCP-Synchronisierungsmodul
+├── tests/                      # Frontend-Tests
+└── assets/                     # Screenshots & Partnerressourcen
+```
+
+</details>
+
+## Mitwirken
+
+Issues und Vorschläge sind willkommen!
+
+Bitte stellen Sie vor dem Einreichen von PRs Folgendes sicher:
+
+- Typprüfung besteht: `pnpm typecheck`
+- Formatprüfung besteht: `pnpm format:check`
+- Unit-Tests bestehen: `pnpm test:unit`
+
+Eröffnen Sie für neue Funktionen bitte vor dem Einreichen eines PR ein Issue zur Diskussion. PRs für Funktionen, die nicht gut zum Projekt passen, können geschlossen werden.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=farion1231/cc-switch&type=Date)](https://www.star-history.com/#farion1231/cc-switch&Date)
+
+## Lizenz
+
+MIT © Jason Young
@@ -2,7 +2,7 @@

 # CC Switch

-### Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes Agent のオールインワン管理ツール
+### Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes Agent のオールインワン管理ツール

 [![Version](https://img.shields.io/github/v/release/farion1231/cc-switch?color=blue&label=version)](https://github.com/farion1231/cc-switch/releases)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/farion1231/cc-switch/releases)
@@ -10,10 +10,11 @@
 [![Downloads](https://img.shields.io/github/downloads/farion1231/cc-switch/total)](https://github.com/farion1231/cc-switch/releases/latest)

 <a href="https://trendshift.io/repositories/15372" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15372" alt="farion1231%2Fcc-switch | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+<a href="https://www.star-history.com/#farion1231/cc-switch&Date"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=farion1231/cc-switch&theme=dark" /><img alt="Star History Rank" src="https://api.star-history.com/badge?repo=farion1231/cc-switch" width="196" height="55" /></picture></a>

 ### 🌐 唯一の公式サイト：**[ccswitch.io](https://ccswitch.io)**

-[English](README.md) | [中文](README_ZH.md) | 日本語 | [Changelog](CHANGELOG.md)
+[English](README.md) | [中文](README_ZH.md) | 日本語 | [Deutsch](README_DE.md) | [Changelog](CHANGELOG.md)

 </div>

@@ -24,11 +25,11 @@
 <details open>
 <summary>クリックで折りたたむ</summary>

-[![MiniMax](assets/partners/banners/minimax-en.jpeg)](https://platform.minimax.io/subscribe/coding-plan?code=ClLhgxr2je&source=link)
+[![Kimi K2.7 Code](https://gcdn.moonshot.cn/growth-cdn/sponsor/kimi-en.png)](https://platform.kimi.ai?aff=cc-switch)

-MiniMax-M2.7 は、自律的進化と実世界の生産性向上のために設計された次世代大規模言語モデルです。従来のモデルとは異なり、M2.7 はエージェントチーム、動的ツール使用、強化学習ループを通じて自身の改善に積極的に参加します。ソフトウェアエンジニアリングにおいて優れた性能を発揮し（SWE-Pro で 56.22%、VIBE-Pro で 55.6%、Terminal Bench 2 で 57.0%）、複雑なオフィスワークフローにも秀でており、GDPval-AA で 1495 ELO のリーディングスコアを達成しています。Word・Excel・PowerPoint の高忠実度編集と、40 以上の複雑なスキルにわたる 97% の遵守率により、M2.7 は AI ネイティブなワークフローと組織構築の新基準を打ち立てます。
+Kimi K3 は Moonshot AI がこれまでに開発した中で最も高性能なモデルであり、世界初のオープンソース 3T クラスモデルです。2.8 兆パラメータ、ネイティブな視覚能力、100 万トークンのコンテキストウィンドウを備え、長期にわたるコーディング、ナレッジワーク、推論タスクにおいてフロンティア級の性能を発揮します。CC Switch を使えば、さまざまなエージェントツールで Kimi を手軽に設定・切り替えできます。**[ここをクリックして Kimi を使い始める](https://platform.kimi.ai?aff=cc-switch)**

-[こちら](https://platform.minimax.io/subscribe/coding-plan?code=ClLhgxr2je&source=link)から MiniMax Token Plan の限定 12% オフを入手！
+コーディング作業がメインですか？**[Kimi Code サブスクリプション](https://www.kimi.com/code/?aff=cc-switch)** をぜひお試しください！

 ---

@@ -39,13 +40,13 @@ MiniMax-M2.7 は、自律的進化と実世界の生産性向上のために設
 </tr>

 <tr>
-<td width="180"><a href="https://aigocode.com/invite/CC-SWITCH"><img src="assets/partners/logos/aigocode.png" alt="AIGoCode" width="150"></a></td>
-<td>本プロジェクトは AIGoCode のスポンサー提供でお届けしています。AIGoCode は、Claude Code・Codex・最新の Gemini モデルを統合したオールインワンのAIコーディングプラットフォームで、安定性・高速性・コストパフォーマンスに優れた開発サービスを提供します。柔軟なサブスクリプションプランを備え、レスポンスも非常に高速です。さらに、CC Switch ユーザー向けの特典として、<a href="https://aigocode.com/invite/CC-SWITCH">このリンク</a>から登録すると、初回チャージ時に10％分のボーナスクレジットが付与されます！</td>
+<td width="180"><a href="https://zetaapi.ai/go/u117"><img src="assets/partners/logos/zetaapi-banner.png" alt="ZetaAPI" width="150"></a></td>
+<td>本プロジェクトをご支援いただいている ZetaAPI に感謝します！ZetaAPI は、モデル品質の忠実性、水増しなし、性能劣化なし、公式価格の 35% から利用できる低価格を主な特徴としています。プラットフォームはトラフィックの混在、低品質モデルへの密かな切り替え、虚偽のモデルルーティングを行わず、Claude Code、Codex、Gemini、ChatGPT などの主要 AI モデルに対応しており、モデル品質を維持しながら API 利用コストを大幅に削減できます。同時に、ZetaAPI はエンタープライズ級の SLA 安定性保証、標準 API 互換、1つの Key による複数モデル接続、迅速な導入、従量課金などの機能を提供し、AI プロダクト、コード生成、企業内ツール、カスタマーサポート、コンテンツ生成、自動化ワークフローなどの用途に適しています。万が一、モデル品質が表記内容と一致しないことが確認された場合、ZetaAPI は 10 倍補償保証を提供し、ユーザーがより安定して、透明性高く、安心して利用できる環境を実現します。<a href="https://zetaapi.ai/go/u117">こちらのリンク</a>から登録し、初回チャージ時にプロモコード CC-SWITCH を使用すると、CC Switch ユーザー限定の初回チャージ 10% オフ特典をご利用いただけます！</td>
 </tr>

 <tr>
-<td width="180"><a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF"><img src="assets/partners/logos/shengsuanyun.png" alt="Shengsuanyun" width="150"></a></td>
-<td>胜算雲（Shengsuanyun）のご支援に感謝します！胜算雲は AI ネイティブチーム向けのスーパーファクトリーであり、産業グレードの AI タスク並列実行プラットフォームです。モデルマーケットプレイスでは Claude、ChatGPT、Gemini をはじめとする国内外の LLM およびマルチメディアモデルの計算リソースを集約・直接提供。リバースエンジニアリングや品質低下は一切なく、プラットフォーム全体のモデル SLA 可用性は 99.7% に達し、<a href="https://watch.shengsuanyun.com/status/shengsuanyun">監視ダッシュボード</a>は常時グリーン表示です。さらにエンタープライズ向けカスタムゲートウェイを提供し、チームのきめ細かなコスト・権限管理、スマートルーティング、セキュリティ保護、BYOK（自社キー持ち込み）ホスティングを実現します。従量課金およびトークンプラン（近日公開）対応で、請求書発行にも対応。<a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF">このリンク</a>から新規登録すると 10 元分のクレジットと初回チャージ 10% ボーナスが付与されます。</td>
+<td width="180"><a href="https://apinebula.com/VjM74M"><img src="assets/partners/logos/apinebula_banner.png" alt="APINebula" width="150"></a></td>
+<td>本プロジェクトは「APINEBULA」のスポンサーシップにより運営されています！APINEBULA は、「銀河録像局」傘下のエンタープライズ向け AI 統合プラットフォームです。大手の豊富なリソースを背景に、開発者、チーム、そして企業ユーザーの皆様へ、安定性とコストパフォーマンスに優れた大規模言語モデル（LLM）の API 連携サービスを提供しています。Claude、GPT、Gemini をはじめとする世界中の主要なフルスペック（満血）モデルを 1 つの API に集約。世界トップクラスの AI モデルを、<strong>最大 90% OFF（元の価格の 1 割〜）</strong>という圧倒的な低価格でご利用いただけます。また、企業向けの高度な並行処理（高コンカレンシー）、正式な契約締結、法人口座振り込み、請求書・領収書発行など、ビジネス利用に必要なサポートも万全です。AI プログラミング、AI エージェント開発、業務システムへの統合など、様々なシーンに最適です。<a href="https://apinebula.com/VjM74M">こちらのリンク</a>から登録し、チャージ時にプロモコード <strong>「ccswitch」を入力すると、さらに 10% OFF</strong> の割引特典が適用されます！</td>
 </tr>

 <tr>
@@ -61,24 +62,86 @@ Claude Code / Codex / Gemini 公式チャンネルが最安で元価格の 38% /
 現在、<a href="https://pateway.ai/?ch=etzpm8&aff=WB6M6F67#/">このリンク</a>からご登録いただくと $3 のトライアルクレジットを進呈。チャージは最安で元価格の 60%、友達紹介は双方にボーナスが付与され、紹介報酬は最大 $150！</td>
 </tr>

+<tr>
+<td width="180"><a href="https://api.fenno.ai/register?redirect=/purchase?tab=subscription%26group=16&aff=P9MR3D3PLCNL"><img src="assets/partners/logos/fenno-banner.png" alt="Fenno.ai" width="150"></a></td>
+<td>Fenno.ai のご支援に感謝します！Fenno.ai は安定かつ高効率な API 中継サービスプロバイダーで、現在は主に Codex の中継を提供しています。OpenAI および Anthropic プロトコルに対応し、Codex・Claude Code・OpenCode などの主要なコーディングツールから柔軟に利用できます。1 日あたり数千億トークンというエンタープライズ級の呼び出し需要を安定して支え、国内外の法人による B2B 決済・請求書発行に対応しています。Fenno.ai は CC Switch 利用者限定の特典を用意しています：<a href="https://api.fenno.ai/register?redirect=/purchase?tab=subscription%26group=16&aff=P9MR3D3PLCNL">こちらのリンク</a>から 9.9 元（150 ドル相当）のお得な Coding Plan を購入でき、友達紹介で最大 20% の特典がもらえます。紹介すればするほどお得です！</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://runapi.co/register?aff=iOKB"><img src="assets/partners/logos/runapi.jpg" alt="RunAPI" width="150"></a></td>
+<td>本プロジェクトのスポンサーである RunAPI に感謝いたします！RunAPI は高効率で安定した AI モデル API ゲートウェイです。一つの API Key で、OpenAI、Claude、Gemini、DeepSeek、Grok など 150 種類以上の主要モデルにアクセス可能。料金は公式価格の最大 10%、安定性にも優れ、Claude Code や OpenClaw などのツールとシームレスに連携できます。CC Switch ユーザー限定特典：<a href="https://runapi.co/register?aff=iOKB">こちらのリンク</a>から登録し、初回チャージで 10% オフの割引をお楽しみいただけます！</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://unity2.ai/register?source=ccs"><img src="assets/partners/logos/unity2.jpg" alt="Unity2.ai" width="150"></a></td>
+<td>Unity2.ai のご支援に感謝します！Unity2.ai は個人開発者・チーム・企業向けの高性能 AI モデル API リレープラットフォームです。中国の大手企業に長年利用されており、1 日 300 億トークン以上を処理し、5000 RPM クラスの高並列に対応しています。残高課金、初回チャージボーナス、組み合わせサブスクリプション、企業向け請求書発行、専任サポートを提供。<a href="https://unity2.ai/register?source=ccs">こちらのリンク</a>から登録すると $2 のクレジット、公式グループへの参加でさらに $10、最大 $12 の無料クレジットがもらえます！</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF"><img src="assets/partners/logos/shengsuanyun.png" alt="Shengsuanyun" width="150"></a></td>
+<td>胜算雲（Shengsuanyun）のご支援に感謝します！胜算雲は AI ネイティブチーム向けのスーパーファクトリーであり、産業グレードの AI タスク並列実行プラットフォームです。モデルマーケットプレイスでは Claude、ChatGPT、Gemini をはじめとする国内外の LLM およびマルチメディアモデルの計算リソースを集約・直接提供。リバースエンジニアリングや品質低下は一切なく、プラットフォーム全体のモデル SLA 可用性は 99.7% に達し、<a href="https://watch.shengsuanyun.com/status/shengsuanyun">監視ダッシュボード</a>は常時グリーン表示です。さらにエンタープライズ向けカスタムゲートウェイを提供し、チームのきめ細かなコスト・権限管理、スマートルーティング、セキュリティ保護、BYOK（自社キー持ち込み）ホスティングを実現します。従量課金およびトークンプラン（近日公開）対応で、請求書発行にも対応。<a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF">このリンク</a>から新規登録すると 10 元分のクレジットと初回チャージ 10% ボーナスが付与されます。</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://aigocode.com/invite/CC-SWITCH"><img src="assets/partners/logos/aigocode.png" alt="AIGoCode" width="150"></a></td>
+<td>本プロジェクトは AIGoCode のスポンサー提供でお届けしています。AIGoCode は、Claude Code・Codex・最新の Gemini モデルを統合したオールインワンのAIコーディングプラットフォームで、安定性・高速性・コストパフォーマンスに優れた開発サービスを提供します。柔軟なサブスクリプションプランを備え、レスポンスも非常に高速です。さらに、CC Switch ユーザー向けの特典として、<a href="https://aigocode.com/invite/CC-SWITCH">このリンク</a>から登録すると、初回チャージ時に10％分のボーナスクレジットが付与されます！</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://subrouter.ai/register?aff=l3ri"><img src="assets/partners/logos/subrouter-banner.png" alt="SubRouter" width="150"></a></td>
+<td>本プロジェクトをご支援いただいている SubRouter に感謝します！SubRouter は、AI サービス事業者向けのマーケットプレイス兼スマートルーティングプラットフォームです。事業者は独立した運営サイトを立ち上げ、プランを公開し、ユーザー・モデル・価格を管理でき、ユーザーはマーケットでサービスを見つけ、統一された API を通じて安定かつ高効率なモデル呼び出しを利用できます。<a href="https://subrouter.ai/register?aff=l3ri">こちらのリンク</a>から登録してください！</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://apikey.fun/register?aff=CCSwitch"><img src="assets/partners/logos/apikey_banner.png" alt="APIKEY.FUN" width="150"></a></td>
+<td>APIKEY.FUN のご支援に感謝します！APIKEY.FUN は、企業および個人開発者向けに安定・高効率・低コストな AI モデル API 接続サービスを提供する、プロフェッショナルなエンタープライズ級 AI リレープラットフォームです。Claude、OpenAI、Gemini などの主要人気モデルに対応し、料金は公式価格の 7% から利用できます。本プロジェクトの<a href="https://apikey.fun/register?aff=CCSwitch">専用リンク</a>から登録すると、最大で<strong>チャージ永久 5% オフ</strong>の特別優待も受けられます。</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://console.claudeapi.com/register?aff=pCLD"><img src="assets/partners/logos/claudeapi.png" alt="ClaudeAPI" width="150"></a></td>
+<td>本プロジェクトは <a href="https://console.claudeapi.com/register?aff=pCLD">Claude API</a> がスポンサーです。Claude API 直結 — わずか 3 分で Claude Code や Agent アプリに接続可能。新規ユーザーにはテストクレジットを提供しています。Anthropic 公式キーおよび AWS Bedrock 公式チャネルに基づいており、リバースエンジニアリングや性能劣化はありません。Opus / Sonnet / Haiku の全モデルラインナップをサポートし、Tool Use や 1M コンテキストなどの公式機能をすべて保持しています。Claude Code ヘビーユーザー、Agent エンジニア、企業技術チームに最適です。請求書発行およびチーム対応が可能です。<a href="https://console.claudeapi.com/register?aff=pCLD">こちら</a>から登録してください！</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://code0.ai/agent/register/B2XHxGjGmRvqgznY"><img src="assets/partners/logos/code0.png" alt="code0.ai" width="150"></a></td>
+<td>本プロジェクトをご支援いただいている <a href="https://code0.ai/agent/register/B2XHxGjGmRvqgznY">code0.ai</a> に感謝します！code0.ai は開発者向けの AI コーディングサービスプラットフォームで、Claude Code、Codex、Gemini などの主要な AI コーディング機能に対応しています。個人開発者やチームが、コーディング、デバッグ、リファクタリング、自動化ワークフローで AI Agent をより安定かつ効率的に活用できるよう支援します。ccswitch ユーザーは <a href="https://code0.ai/agent/register/B2XHxGjGmRvqgznY">code0.ai 公式サイト</a> からカスタマーサポートに連絡することで、テストクレジットを受け取り、信頼性の高い AI コーディングサービスを体験できます。</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://teamorouter.com/?utm_source=cc_switch&utm_medium=referral&utm_campaign=ai_directory"><img src="assets/partners/logos/TeamoRouter-banner.png" alt="TeamoRouter" width="150"></a></td>
+<td>このプロジェクトをご支援いただいている TeamoRouter に感謝します！TeamoRouter は、開発者、AI チーム、企業向けに構築されたエンタープライズグレードの Agentic LLM ゲートウェイです。サブスクリプション不要で、単一の統合 API を通じて Claude Code、Codex、Gemini CLI、OpenAI Codex、その他の人気 AI エージェントにアクセスでき、API 料金は最大 90% オフで利用できます。
+一般的な API リレーサービスとは異なり、TeamoRouter は OpenAI、Anthropic、Vertex、Azure、AWS Bedrock など、数百の公式モデルプロバイダーと信頼できるインフラパートナーを集約しています。各プロバイダーは、Agent プロトコルとの 100% 互換性、キャッシュ性能、リクエストの追跡可能性について検証されており、リバースエンジニアリングされたものや品質が薄められたエンドポイントではなく、安定した品質を提供します。プラットフォームは公式に近い TTFT、99.6% の SLA、最大 5,000 QPM のエンタープライズ規模のスループット、そして業界トップクラスのキャッシュヒット率を提供し、長時間稼働するエージェントワークフローのトークンコストを大幅に削減します。
+TeamoRouter は、集中請求、チーム管理、BYOK、スマートルーティング、利用状況分析、動的なプロバイダー最適化、専任サポートなどのエンタープライズ機能も提供しています。さらにシンプルな体験を求める場合は、Teamo Desktop を使うことで、Claude Code、Codex、Gemini CLI、その他の人気 AI エージェントをワンクリックで利用できます。API キー管理や手動のゲートウェイ設定は不要です。新規ユーザーとして<a href="https://teamorouter.com/?utm_source=cc_switch&utm_medium=referral&utm_campaign=ai_directory">こちらのリンク</a>から登録すると、初回チャージが 10% オフになります。</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.newapi.ai/"><img src="assets/partners/logos/newapi-banner.png" alt="new-api" width="150"></a></td>
+<td>オープンソースの AI インフラプロジェクト <a href="https://www.newapi.ai/">new-api</a> による本プロジェクトへの多大なご支援に感謝します！new-api は QuantumNous（锟腾科技）が開発したオープンソースの AI インフラプロジェクトであり、活発さと利用規模の面でリードする LLM 統合アクセス・配信プロジェクトの一つで、開発者・チーム・企業がより低コストで管理・拡張可能な AI サービスプラットフォームを構築できるよう支援することに注力しています。同じくオープンソースエコシステムに根ざすプロジェクトとして、new-api はスポンサーシップを通じて、より多くの優れたオープンソースプロジェクトの継続的な発展を支援したいと考えています。🌟 new-api への Star で応援をお願いします：<a href="https://github.com/QuantumNous/new-api">https://github.com/QuantumNous/new-api</a>。公式サイト：<a href="https://www.newapi.ai/">https://www.newapi.ai/</a>。</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://claudecn.ai/register?aff=HEL9"><img src="assets/partners/logos/claudecn.jpg" alt="ClaudeCN" width="150"></a></td>
+<td>本プロジェクトのスポンサーである ClaudeCN に感謝いたします！ClaudeCN は、実体のある企業によって運営されるエンタープライズ向け AI ゲートウェイプラットフォームです。Claude、GPT、DeepSeek など主要モデルへの高可用な商用 API アクセスを提供し、企業の調達プロセスにも対応 — 法人振込や正式契約に対応し、コンプライアンス面でも安心してご利用いただけます。<a href="https://claudecn.ai/register?aff=HEL9">こちら</a>からご登録ください！</td>
+</tr>
+
 <tr>
 <td width="180"><a href="https://www.byteplus.com/en/product/modelark?utm_campaign=hw&utm_content=ccswitch&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch"><img src="assets/partners/logos/byteplus.png" alt="BytePlus" width="150"></a></td>
-<td>Dola seed のご支援に感謝します！Dola Seed 2.0 は ByteDance がグローバル市場向けに独自開発したフルモーダル汎用大規模モデルです。統一されたマルチモーダルアーキテクチャを基盤に、テキスト・画像・音声・動画の統合的な理解と生成をサポートします。エージェント連携をネイティブに実現し、強力な推論、長時間タスクの実行、ツール統合、コーディング能力を備えています。スマートコックピット、パーソナルアシスタント、教育、カスタマーサポート、マーケティング、リテールなど幅広いシナリオに適用可能で、マルチモーダル認識、エンドツーエンドの複雑なタスク遂行、安定したインタラクション、データセキュリティに優れ、ModelArk プラットフォームを通じて手軽に利用・デプロイできます。<a href="https://www.byteplus.com/en/product/modelark?utm_campaign=hw&utm_content=ccswitch&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch">このリンク</a>からご登録いただくと、モデルごとに 500,000 トークンの無料推論クォータを進呈します。</td>
+<td>Dola seed のご支援に感謝します！Dola Seed 2.0 は ByteDance がグローバル市場向けに独自開発したフルモーダル汎用大規模モデルです。統一されたマルチモーダルアーキテクチャを基盤に、テキスト・画像・音声・動画の統合的な理解と生成をサポートします。エージェント連携をネイティブに実現し、強力な推論、長時間タスクの実行、ツール統合、コーディング能力を備えています。スマートコックピット、パーソナルアシスタント、教育、カスタマーサポート、マーケティング、リテールなど幅広いシナリオに適用可能で、マルチモーダル認識、エンドツーエンドの複雑なタスク遂行、安定したインタラクション、データセキュリティに優れ、ModelArk プラットフォームを通じて手軽に利用・デプロイできます。<a href="https://www.byteplus.com/en/product/modelark?utm_campaign=hw&utm_content=ccswitch&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch">このリンク</a>からご登録いただくと、モデルごとに 500,000 トークンの無料推論クォータを進呈します。<a href="https://www.volcengine.com/activity/ai618?utm_campaign=hw&utm_content=hw&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch"> >>中国大陆地区的开发者请点击这里</a></td>
 </tr>

 <tr>
-<td width="180"><a href="https://cloud.siliconflow.cn/i/drGuwc9k"><img src="assets/partners/logos/silicon_en.jpg" alt="SiliconFlow" width="150"></a></td>
-<td>SiliconFlow のご支援に感謝します！SiliconFlow は高性能 AI インフラストラクチャおよびモデル API プラットフォームで、言語・音声・画像・動画モデルへの高速かつ信頼性の高いアクセスをワンストップで提供します。従量課金制、豊富なマルチモーダルモデル対応、高速推論、エンタープライズグレードの安定性を備え、開発者やチームがより効率的に AI アプリケーションを構築・拡張できるようサポートします。<a href="https://cloud.siliconflow.cn/i/drGuwc9k">このリンク</a>から登録し、本人確認を完了すると、プラットフォーム内の全モデルで利用可能な ¥16 のボーナスクレジットが付与されます。SiliconFlow は OpenClaw にも対応しており、SiliconFlow の API キーを接続することで主要な AI モデルを無料で呼び出すことができます。</td>
+<td width="180"><a href="https://cloud.siliconflow.cn/i/YflgU2Ve"><img src="assets/partners/logos/silicon_en.jpg" alt="SiliconFlow" width="150"></a></td>
+<td>SiliconFlow のご支援に感謝します！SiliconFlow は高性能 AI インフラストラクチャおよびモデル API プラットフォームで、言語・音声・画像・動画モデルへの高速かつ信頼性の高いアクセスをワンストップで提供します。従量課金制、豊富なマルチモーダルモデル対応、高速推論、エンタープライズグレードの安定性を備え、開発者やチームがより効率的に AI アプリケーションを構築・拡張できるようサポートします。<a href="https://cloud.siliconflow.cn/i/YflgU2Ve">このリンク</a>から登録し、本人確認を完了すると、プラットフォーム内の全モデルで利用可能な ¥16 のボーナスクレジットが付与されます。SiliconFlow は OpenClaw にも対応しており、SiliconFlow の API キーを接続することで主要な AI モデルを無料で呼び出すことができます。</td>
 </tr>

 <tr>
-<td width="180"><a href="https://cubence.com/signup?code=CCSWITCH&source=ccs"><img src="assets/partners/logos/cubence.png" alt="Cubence" width="150"></a></td>
-<td>Cubence のご支援に感謝します！Cubence は Claude Code、Codex、Gemini などのリレーサービスを提供する信頼性の高い API 中継プラットフォームで、従量課金や月額プランなど柔軟な料金体系を提供しています。CC Switch ユーザー向けの特別割引：<a href="https://cubence.com/signup?code=CCSWITCH&source=ccs">このリンク</a>で登録し、チャージ時に「CCSWITCH」クーポンを入力すると、毎回 10% オフになります！</td>
+<td width="180"><a href="https://nekocode.ai?aff=CCSWITCH"><img src="assets/partners/logos/nekocode-banner.png" alt="NekoCode" width="150"></a></td>
+<td>本プロジェクトをご支援いただいている <a href="https://nekocode.ai?aff=CCSWITCH">NekoCode</a> に感謝します！NekoCode は、Claude や Codex などの AI モデルに対応した、安定性・効率性・信頼性に優れた API 中継サービスを提供しています。料金体系は明瞭で、柔軟な従量課金にも対応しています。CC Switch ユーザー限定の 10%オフ特典：<a href="https://nekocode.ai?aff=CCSWITCH">こちらのリンク</a> から登録し、チャージ時にクーポンコード <code>cc-switch</code> を入力すると、チャージが 10%オフになります！</td>
 </tr>

 <tr>
-<td width="180"><a href="https://www.dmxapi.cn/register?aff=bUHu"><img src="assets/partners/logos/dmx-en.jpg" alt="DMXAPI" width="150"></a></td>
-<td>DMXAPI のご支援に感謝します！DMXAPI は 200 社以上の企業ユーザーにグローバル大規模モデル API サービスを提供しています。1 つの API キーで全世界のモデルにアクセス可能。即時請求書発行、同時接続数無制限、最低 $0.15 から、24 時間年中無休のテクニカルサポート。GPT/Claude/Gemini が全て 32% オフ、国内モデルは 20〜50% オフ、Claude Code 専用モデルは 66% オフ実施中！<a href="https://www.dmxapi.cn/register?aff=bUHu">登録はこちら</a></td>
+<td width="180"><a href="https://www.atlascloud.ai/coding-plan?utm_source=github&utm_campaign=cc-switch"><img src="assets/partners/logos/atlascloud_banner.png" alt="Atlas Cloud" width="150"></a></td>
+<td>Atlas Cloud は、1 つの API で動画・画像生成や LLM（大規模言語モデル）を利用できる全モーダル対応の AI 推論プラットフォームです。複数のベンダーを個別に管理する手間を省き、一度の接続で 300 以上の厳選されたマルチモーダルモデルにアクセスできます。より低コストで API を利用できる、開発者向けの新しい<a href="https://www.atlascloud.ai/coding-plan?utm_source=github&utm_campaign=cc-switch">「コーディングプラン」</a>プロモーションをぜひチェックしてください！</td>
 </tr>

 <tr>
@@ -87,18 +150,8 @@ Claude Code / Codex / Gemini 公式チャンネルが最安で元価格の 38% /
 </tr>

 <tr>
-<td width="180"><a href="https://aicoding.sh/i/CCSWITCH"><img src="assets/partners/logos/aicoding.jpg" alt="AICoding" width="150"></a></td>
-<td>AICoding.sh のご支援に感謝します！AICoding.sh —— グローバル AI モデル API 超お得な中継サービス！Claude Code 81% オフ、GPT 99% オフ！数百社の企業に高コストパフォーマンスの AI サービスを提供。Claude Code、GPT、Gemini および国内主要モデルに対応、エンタープライズ級の高同時接続、迅速な請求書発行、24 時間年中無休の専属テクニカルサポート。<a href="https://aicoding.sh/i/CCSWITCH">こちらのリンク</a>から登録した CC Switch ユーザーは、初回チャージ 10% オフ！</td>
-</tr>
-
-<tr>
-<td width="180"><a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch"><img src="assets/partners/logos/crazyrouter.png" alt="Crazyrouter" width="150"></a></td>
-<td>Crazyrouter のご支援に感謝します！Crazyrouter は高性能 AI API アグリゲーションプラットフォームです。1 つの API キーで Claude Code、Codex、Gemini CLI など 300 以上のモデルにアクセス可能。全モデルが公式価格の 55% で利用でき、自動フェイルオーバー、スマートルーティング、無制限同時接続に対応。CC Switch ユーザー向けの限定特典：<a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch">こちらのリンク</a>から登録後、カスタマーサポートまでご連絡いただくと <strong>$2 の無料クレジット</strong> を受け取れます。さらに初回チャージ時にプロモコード `CCSWITCH` を入力すると <strong>30% のボーナスクレジット</strong> が追加されます！</td>
-</tr>
-
-<tr>
-<td width="180"><a href="https://www.right.codes/register?aff=CCSWITCH"><img src="assets/partners/logos/rightcode.jpg" alt="RightCode" width="150"></a></td>
-<td>本プロジェクトへのご支援として、Right Code にご協賛いただき誠にありがとうございます。Right Code は、Claude Code、Codex、Gemini などのモデル向け中継サービスを安定して提供しており、従量課金と月額プランの 2 つの料金体系から選択できます。チャージ後に請求書の発行が可能で、法人・チームのお客様には専任担当による個別対応も行っています。さらに、CC Switch ユーザー向けの特別優待として、<a href="https://www.right.codes/register?aff=CCSWITCH">こちらのリンク</a>から登録すると、チャージのたびに実際の支払額の 5% 相当の従量課金クレジットが付与されます。</td>
+<td width="180"><a href="https://www.ccsub.net/register?ref=Y6Z8DXEA"><img src="assets/partners/logos/ccsub.svg" alt="CCSub" width="150"></a></td>
+<td>CCSub のご支援に感謝します！CCSub は安定した低価格の AI API リレープラットフォームで、Claude Code 公式サブスクリプションの強力な代替です。1 つの API キーで Claude Opus 4.8、Sonnet 4.6、Haiku 4.5、GPT-5、Gemini、DeepSeek の全モデルを公式直接利用の約 1/3 のコストでご利用いただけます。VPN 不要で世界中から直接接続可能。Claude Code、Codex、Cursor、Cline、Continue、Windsurf など主要な AI コーディングツールすべてに対応しています。<a href="https://www.ccsub.net/register?ref=Y6Z8DXEA">こちらのリンク</a>から登録すると $5 の無料クレジットがもらえます。</td>
 </tr>

 <tr>
@@ -110,34 +163,30 @@ Claude Code / Codex / Gemini 公式チャンネルが最安で元価格の 38% /
 <td width="180"><a href="https://www.micuapi.ai/register?aff=aOYQ"><img src="assets/partners/logos/mikubanner.svg" alt="Micu" width="150"></a></td>
 <td>Micu API のご支援に感謝します！Micu API は、最高のコストパフォーマンスと高い安定性を追求するグローバル大規模言語モデル中継サービスプロバイダーです。法人企業がバックアップしており、サービス停止のリスクを排除、迅速な正規請求書発行に対応！「試行コストゼロ」をモットーに、最低 1 元からチャージ可能で手数料無料、いつでも返金可能！CC Switch ユーザー向けの限定特典：<a href="https://www.micuapi.ai/register?aff=aOYQ">こちらのリンク</a>から登録し、チャージ時にプロモコード「ccswitch」を入力すると <strong>10% 割引</strong> が適用されます！</td>
 </tr>
+
 <tr>
-<td width="180"><a href="https://lemondata.cc/r/FFX1ZDUP"><img src="assets/partners/logos/lemondata.png" alt="LemonData" width="150"></a></td>
-<td>LemonData のご支援に感謝します！LemonData は高性能 AI API アグリゲーションプラットフォームで、GPT、Claude、Gemini、DeepSeek など 300 以上のモデルに 1 つの API キーでアクセス可能。全モデルが公式価格の 30〜70% オフで自動フェイルオーバー、スマートルーティング、無制限同時接続に対応。新規ユーザーは登録だけで即座に $1 の無料クレジットを獲得 — <a href="https://lemondata.cc/r/FFX1ZDUP">こちらのリンク</a>から登録してボーナスを獲得し、すぐに開発を始めましょう！</td>
+<td width="180"><a href="https://www.right.codes/register?aff=CCSWITCH"><img src="assets/partners/logos/rightcode.jpg" alt="RightCode" width="150"></a></td>
+<td>本プロジェクトへのご支援として、Right Code にご協賛いただき誠にありがとうございます。Right Code は、Claude Code、Codex、Gemini などのモデル向け中継サービスを安定して提供しており、従量課金と月額プランの 2 つの料金体系から選択できます。チャージ後に請求書の発行が可能で、法人・チームのお客様には専任担当による個別対応も行っています。さらに、CC Switch ユーザー向けの特別優待として、<a href="https://www.right.codes/register?aff=CCSWITCH">こちらのリンク</a>から登録すると、チャージのたびに実際の支払額の 5% 相当の従量課金クレジットが付与されます。</td>
 </tr>

 <tr>
-<td width="180"><a href="https://ctok.ai"><img src="assets/partners/logos/ctok.png" alt="CTok" width="150"></a></td>
-<td>CTok.ai のご支援に感謝します！CTok.ai はワンストップ AI プログラミングツールサービスプラットフォームの構築に取り組んでいます。Claude Code のプロフェッショナルプランと技術コミュニティサービスを提供し、Google Gemini や OpenAI Codex にも対応しています。丁寧に設計されたプランと専門的な技術コミュニティを通じて、開発者に安定したサービス保証と継続的な技術サポートを提供し、AI アシストプログラミングを真の生産性ツールにします。<a href="https://ctok.ai">こちら</a>から登録してください！</td>
+<td width="180"><a href="https://etok.ai"><img src="assets/partners/logos/etok.png" alt="ETok" width="150"></a></td>
+<td>ETok.ai のご支援に感謝します！ETok.ai はワンストップ AI プログラミングツールサービスプラットフォームの構築に取り組んでいます。Claude Code のプロフェッショナルプランと技術コミュニティサービスを提供し、Google Gemini や OpenAI Codex にも対応しています。丁寧に設計されたプランと専門的な技術コミュニティを通じて、開発者に安定したサービス保証と継続的な技術サポートを提供し、AI アシストプログラミングを真の生産性ツールにします。<a href="https://etok.ai">こちら</a>から登録してください！</td>
 </tr>

 <tr>
-<td width="180"><a href="https://vibecodingapi.ai"><img src="assets/partners/logos/lioncc.png" alt="LionCC" width="150"></a></td>
-<td>LionCC のご支援に感謝します！LionCC は究極の開発体験を追求する「Vibe Coders」のために生まれました。Claude Code、Codex、OpenClaw 向けに安定・低遅延・お得な価格の計算リソースサービスを提供し、最大 50% のコスト削減を実現します。登録後、カスタマーサービスの WeChat（HSQBJ088888888）を追加し、合言葉「cc-switch」を送信すると、10 ドル分のクレジット（1,000 万トークン）がもらえます。その他のコラボレーションについてはブログ @LionCC.ai をフォローしてください。<a href="https://vibecodingapi.ai">こちら</a>から登録してください！</td>
+<td width="180"><a href="https://cubence.com/signup?code=CCSWITCH&source=ccs"><img src="assets/partners/logos/cubence.png" alt="Cubence" width="150"></a></td>
+<td>Cubence のご支援に感謝します！Cubence は Claude Code、Codex、Gemini などのリレーサービスを提供する信頼性の高い API 中継プラットフォームで、従量課金や月額プランなど柔軟な料金体系を提供しています。CC Switch ユーザー向けの特別割引：<a href="https://cubence.com/signup?code=CCSWITCH&source=ccs">このリンク</a>で登録し、チャージ時に「CCSWITCH」クーポンを入力すると、毎回 10% オフになります！</td>
 </tr>

 <tr>
-<td width="180"><a href="https://console.claudeapi.com/register?aff=pCLD"><img src="assets/partners/logos/claudeapi.png" alt="ClaudeAPI" width="150"></a></td>
-<td>本プロジェクトは <a href="https://console.claudeapi.com/register?aff=pCLD">Claude API</a> がスポンサーです。Claude API 直結 — わずか 3 分で Claude Code や Agent アプリに接続可能。新規ユーザーにはテストクレジットを提供しています。Anthropic 公式キーおよび AWS Bedrock 公式チャネルに基づいており、リバースエンジニアリングや性能劣化はありません。Opus / Sonnet / Haiku の全モデルラインナップをサポートし、Tool Use や 1M コンテキストなどの公式機能をすべて保持しています。Claude Code ヘビーユーザー、Agent エンジニア、企業技術チームに最適です。請求書発行およびチーム対応が可能です。<a href="https://console.claudeapi.com/register?aff=pCLD">こちら</a>から登録してください！</td>
+<td width="180"><a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch"><img src="assets/partners/logos/crazyrouter.png" alt="Crazyrouter" width="150"></a></td>
+<td>Crazyrouter のご支援に感謝します！Crazyrouter は高性能 AI API アグリゲーションプラットフォームです。1 つの API キーで Claude Code、Codex、Gemini CLI など 300 以上のモデルにアクセス可能。全モデルが公式価格の 55% で利用でき、自動フェイルオーバー、スマートルーティング、無制限同時接続に対応。CC Switch ユーザー向けの限定特典：<a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch">こちらのリンク</a>から登録後、カスタマーサポートまでご連絡いただくと <strong>$2 の無料クレジット</strong> を受け取れます。さらに初回チャージ時にプロモコード `CCSWITCH` を入力すると <strong>30% のボーナスクレジット</strong> が追加されます！</td>
 </tr>

 <tr>
-<td width="180"><a href="https://claudecn.top"><img src="assets/partners/logos/claudecn.jpg" alt="ClaudeCN" width="150"></a></td>
-<td>本プロジェクトのスポンサーである ClaudeCN に感謝いたします！ClaudeCN は、実体のある企業によって運営されるエンタープライズ向け AI ゲートウェイプラットフォームです。Claude、GPT、DeepSeek など主要モデルへの高可用な商用 API アクセスを提供し、企業の調達プロセスにも対応 — 法人振込や正式契約に対応し、コンプライアンス面でも安心してご利用いただけます。<a href="https://claudecn.top">こちら</a>からご登録ください！</td>
-</tr>
-
-<tr>
-<td width="180"><a href="https://runapi.co"><img src="assets/partners/logos/runapi.jpg" alt="RunAPI" width="150"></a></td>
-<td>本プロジェクトのスポンサーである RunAPI に感謝いたします！RunAPI は高効率で安定した AI モデル API ゲートウェイです。一つの API Key で、OpenAI、Claude、Gemini、DeepSeek、Grok など 150 種類以上の主要モデルにアクセス可能。料金は公式価格の最大 10%、安定性にも優れ、Claude Code や OpenClaw などのツールとシームレスに連携できます。CC Switch ユーザー限定特典：ご登録後にカスタマーサポートへご連絡いただくと、14 元の無料クレジットを進呈いたします。<a href="https://runapi.co">こちら</a>からご登録ください！</td>
+<td width="180"><a href="https://www.dmxapi.cn/register?aff=bUHu"><img src="assets/partners/logos/dmx-en.jpg" alt="DMXAPI" width="150"></a></td>
+<td>DMXAPI のご支援に感謝します！DMXAPI は 200 社以上の企業ユーザーにグローバル大規模モデル API サービスを提供しています。1 つの API キーで全世界のモデルにアクセス可能。即時請求書発行、同時接続数無制限、最低 $0.15 から、24 時間年中無休のテクニカルサポート。GPT/Claude/Gemini が全て 32% オフ、国内モデルは 20〜50% オフ、Claude Code 専用モデルは 66% オフ実施中！<a href="https://www.dmxapi.cn/register?aff=bUHu">登録はこちら</a></td>
 </tr>

 </table>
@@ -146,13 +195,13 @@ Claude Code / Codex / Gemini 公式チャンネルが最安で元価格の 38% /

 ## CC Switch を選ぶ理由

-最新の AI コーディングは Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw などの CLI ツールに依存していますが、各ツールの設定形式はバラバラです。API プロバイダを切り替えるたびに JSON、TOML、`.env` ファイルを手動で編集する必要があり、複数ツール間で MCP や Skills を統一的に管理する手段もありません。
+最新の AI コーディングは Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes などのツールに依存していますが、各ツールの設定形式はバラバラです。API プロバイダを切り替えるたびに JSON、TOML、`.env` ファイルを手動で編集する必要があり、複数ツール間で MCP や Skills を統一的に管理する手段もありません。

-**CC Switch** は、5 つの CLI ツールを 1 つのデスクトップアプリで一元管理できます。設定ファイルを手作業で編集する代わりに、ワンクリックでプロバイダをインポートし、瞬時に切り替えられるビジュアルインターフェースを提供します。50 以上の組み込みプリセット、統一 MCP・Skills 管理、システムトレイからの即時切り替え機能を搭載。すべてはアトミック書き込みによる信頼性の高い SQLite データベースに支えられており、設定の破損を防ぎます。
+**CC Switch** は、対応する AI ツールを 1 つのデスクトップアプリで一元管理できます。設定ファイルを手作業で編集する代わりに、ワンクリックでプロバイダをインポートし、瞬時に切り替えられるビジュアルインターフェースを提供します。50 以上の組み込みプリセット、統一 MCP・Skills 管理、システムトレイからの即時切り替え機能を搭載。すべてはアトミック書き込みによる信頼性の高い SQLite データベースに支えられており、設定の破損を防ぎます。

- **1 つのアプリで 5 つの CLI ツール** -- Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw を単一インターフェースで管理
+- **1 つのアプリで 8 つのツール** -- Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes を単一インターフェースで管理
 - **手動編集は不要** -- AWS Bedrock、NVIDIA NIM、コミュニティリレーなど 50 以上のプロバイダプリセットを内蔵。選んで切り替えるだけ
- **統一 MCP・Skills 管理** -- 1 つのパネルで 4 つのアプリの MCP サーバーと Skills を双方向同期で管理
+- **統一 MCP・Skills 管理** -- 1 つのパネルで Claude、Codex、Gemini、Grok Build、OpenCode、Hermes の MCP サーバーと Skills を双方向同期で管理
 - **システムトレイでクイック切り替え** -- トレイメニューから即座にプロバイダを切り替え。アプリを開く必要なし
 - **クラウド同期** -- Dropbox、OneDrive、iCloud、または WebDAV サーバー経由でデバイス間のプロバイダデータを同期
 - **クロスプラットフォーム** -- Tauri 2 で構築された Windows、macOS、Linux 対応のネイティブデスクトップアプリ
@@ -166,22 +215,22 @@ Claude Code / Codex / Gemini 公式チャンネルが最安で元価格の 38% /

 ## 特長

-[完全な更新履歴](CHANGELOG.md) | [リリースノート](docs/release-notes/v3.15.0-ja.md)
+[完全な更新履歴](CHANGELOG.md) | [リリースノート](docs/release-notes/v3.16.1-ja.md)

 ### プロバイダ管理

- **5 つの CLI ツール、50 以上のプリセット** -- Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw。キーをコピーしてワンクリックでインポート
- **ユニバーサルプロバイダ** -- 1 つの設定を複数アプリに同期（OpenCode、OpenClaw）
+- **8 つの対応ツール、50 以上のプリセット** -- Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes。キーをコピーしてワンクリックでインポート
+- **ユニバーサルプロバイダ** -- 1 つの設定を Claude Code、Codex、Gemini CLI に同期
 - ワンクリック切り替え、システムトレイクイックアクセス、ドラッグ＆ドロップ並び替え、インポート/エクスポート

 ### プロキシ & フェイルオーバー

 - **ローカルプロキシのホットスイッチ** -- フォーマット変換、自動フェイルオーバー、サーキットブレーカー、プロバイダヘルスモニタリング、リクエストレクティファイア
- **アプリレベルのテイクオーバー** -- Claude、Codex、Gemini を個別にプロキシ経由でルーティング、プロバイダ単位で設定可能
+- **アプリレベルのテイクオーバー** -- Claude、Codex、Gemini、Grok Build を個別にプロキシ経由でルーティング、プロバイダ単位で設定可能

 ### MCP、Prompts & Skills

- **統一 MCP パネル** -- 4 つのアプリの MCP サーバーを管理、双方向同期、Deep Link インポート対応
+- **統一 MCP パネル** -- Claude、Codex、Gemini、Grok Build、OpenCode、Hermes の MCP サーバーを管理、双方向同期、Deep Link インポート対応
 - **Prompts** -- Markdown エディタ、クロスアプリ同期（CLAUDE.md / AGENTS.md / GEMINI.md）、バックフィル保護
 - **Skills** -- GitHub リポジトリまたは ZIP ファイルからワンクリックインストール、カスタムリポジトリ管理、シンボリックリンクとファイルコピーに対応

@@ -191,21 +240,21 @@ Claude Code / Codex / Gemini 公式チャンネルが最安で元価格の 38% /

 ### Session Manager & ワークスペース

- すべてのアプリの会話履歴を閲覧・検索・復元
+- 対応するセッションソースの会話履歴を閲覧・検索・復元
 - **ワークスペースエディタ**（OpenClaw）-- エージェントファイル（AGENTS.md、SOUL.md など）を Markdown プレビュー付きで編集

 ### システム & プラットフォーム

 - **クラウド同期** -- カスタム設定ディレクトリ（Dropbox、OneDrive、iCloud、NAS）および WebDAV サーバー同期
 - **Deep Link** (`ccswitch://`) -- URL 経由でプロバイダ、MCP サーバー、Prompts、Skills をワンクリックインポート
- ダーク / ライト / システムテーマ、自動起動、自動アップデーター、アトミック書き込み、自動バックアップ、多言語対応（中/英/日）
+- ダーク / ライト / システムテーマ、自動起動、自動アップデーター、アトミック書き込み、自動バックアップ、多言語対応（簡体中文/繁體中文/英/日）

 ## よくある質問

 <details>
-<summary><strong>CC Switch はどの AI CLI ツールに対応していますか？</strong></summary>
+<summary><strong>CC Switch はどの AI ツールに対応していますか？</strong></summary>

-CC Switch は **Claude Code**、**Codex**、**Gemini CLI**、**OpenCode**、**OpenClaw** の 5 つのツールに対応しています。各ツールに専用のプロバイダプリセットと設定管理が用意されています。
+CC Switch は **Claude Code**、**Claude Desktop**、**Codex**、**Gemini CLI**、**Grok Build**、**OpenCode**、**OpenClaw**、**Hermes** の 8 つのツールに対応しています。各ツールに専用のプロバイダプリセットと設定管理が用意されています。

 </details>

@@ -219,7 +268,7 @@ CC Switch は **Claude Code**、**Codex**、**Gemini CLI**、**OpenCode**、**Op
 <details>
 <summary><strong>プロバイダを切り替えた後、プラグイン設定が消えてしまいました。どうすればよいですか？</strong></summary>

-CC Switch には「共有設定スニペット」機能があり、APIキーやエンドポイント以外の共通データをプロバイダ間で引き継ぐことができます。「プロバイダ編集」→「共有設定パネル」→「現在のプロバイダから抽出」をクリックして、すべての共通データを保存してください。新しいプロバイダを作成する際に「共有設定を書き込む」にチェック（デフォルトで有効）を入れれば、プラグインなどのデータが新しいプロバイダ設定に含まれます。すべての設定項目は、アプリ初回起動時にインポートされたデフォルトプロバイダに保存されており、失われることはありません。
+CC Switch には「共有設定スニペット」機能があり、APIキーやエンドポイント以外の共通データをプロバイダ間で引き継ぐことができます。「プロバイダ編集」→「共有設定パネル」→「現在のプロバイダから抽出」をクリックして、すべての共通データを保存してください。新しいプロバイダを作成する際に「共有設定を適用」にチェック（デフォルトで有効）を入れれば、プラグインなどのデータが新しいプロバイダ設定に含まれます。すべての設定項目は、アプリ初回起動時にインポートされたデフォルトプロバイダに保存されており、失われることはありません。

 </details>

@@ -255,6 +304,19 @@ CC Switch は「最小限の介入」という設計原則に従っています

 </details>

+<details>
+<summary><strong>Linux（Wayland + NVIDIA）：Web コンテンツがクリックできない・リサイズで黒画面になる</strong></summary>
+
+AppImage は過去のネイティブ Wayland クラッシュを避けるため `GDK_BACKEND=x11`（XWayland）を強制します。新しい Wayland + NVIDIA 環境ではこれが原因で Web コンテンツ領域がクリックできなくなり（タイトルバーのボタンは動作します）、リサイズ時に黒画面になることがあります。内蔵のエスケープハッチでネイティブ Wayland に戻せます：
+
+```bash
+CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
+```
+
+デスクトップアイコンから起動する場合は、`.desktop` の `Exec=` 行に追記するか（例：`env CC_SWITCH_GDK_BACKEND=wayland /path/to/AppImage`）、セッション環境で設定してください。この変数は汎用です：タイル型 Wayland コンポジタ（sway/Hyprland）でクリックが効かない場合は、逆に `CC_SWITCH_GDK_BACKEND=x11` を試してください。未設定の場合は既定の動作のままです。
+
+</details>
+
 ## ドキュメント

 各機能の詳しい使い方については、**[ユーザーマニュアル](docs/user-manual/ja/README.md)** をご覧ください。プロバイダ管理、MCP/Prompts/Skills、プロキシとフェイルオーバーなど、すべての機能を網羅しています。
@@ -274,8 +336,8 @@ CC Switch は「最小限の介入」という設計原則に従っています

 - **MCP**: 「MCP」ボタンをクリック → テンプレートまたはカスタム設定でサーバーを追加 → アプリごとの同期をトグルで切り替え
 - **Prompts**: 「Prompts」をクリック → Markdown エディタでプリセットを作成 → 有効化してライブファイルに同期
- **Skills**: 「Skills」をクリック → GitHub リポジトリを閲覧 → ワンクリックですべてのアプリにインストール
- **Sessions**: 「Sessions」をクリック → すべてのアプリの会話履歴を閲覧・検索・復元
+- **Skills**: 「Skills」をクリック → GitHub リポジトリを閲覧 → 対応アプリへワンクリックでインストール
+- **Sessions**: 「Sessions」をクリック → 対応するセッションソースの会話履歴を閲覧・検索・復元

 > **補足**: 初回起動時に、既存の CLI ツール設定を手動でインポートしてデフォルトプロバイダとして使用できます。

@@ -296,7 +358,6 @@ CC Switch は「最小限の介入」という設計原則に従っています
 **方法 1: Homebrew でインストール（推奨）**

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

@@ -489,7 +550,7 @@ pnpm test:unit --coverage
 │   ├── lib/
 │   │   ├── api/                # Tauri API ラッパー（型安全）
 │   │   └── query/              # TanStack Query 設定
-│   ├── locales/                # 翻訳 (zh/en/ja)
+│   ├── locales/                # 翻訳 (zh/zh-TW/en/ja)
 │   ├── config/                 # プリセット (providers/mcp)
 │   └── types/                  # TypeScript 型定義
 ├── src-tauri/                  # バックエンド (Rust)
@@ -2,7 +2,7 @@

 # CC Switch

-### Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 和 Hermes Agent 的全方位管理工具
+### Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw 和 Hermes Agent 的全方位管理工具

 [![Version](https://img.shields.io/github/v/release/farion1231/cc-switch?color=blue&label=version)](https://github.com/farion1231/cc-switch/releases)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/farion1231/cc-switch/releases)
@@ -10,10 +10,11 @@
 [![Downloads](https://img.shields.io/github/downloads/farion1231/cc-switch/total)](https://github.com/farion1231/cc-switch/releases/latest)

 <a href="https://trendshift.io/repositories/15372" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15372" alt="farion1231%2Fcc-switch | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+<a href="https://www.star-history.com/#farion1231/cc-switch&Date"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=farion1231/cc-switch&theme=dark" /><img alt="Star History Rank" src="https://api.star-history.com/badge?repo=farion1231/cc-switch" width="196" height="55" /></picture></a>

 ### 🌐 唯一官方网站：**[ccswitch.io](https://ccswitch.io)**

-[English](README.md) | 中文 | [日本語](README_JA.md) | [更新日志](CHANGELOG.md)
+[English](README.md) | 中文 | [日本語](README_JA.md) | [Deutsch](README_DE.md) | [更新日志](CHANGELOG.md)

 </div>

@@ -24,11 +25,11 @@
 <details open>
 <summary>点击折叠</summary>

-[![MiniMax](assets/partners/banners/minimax-zh.jpeg)](https://platform.minimaxi.com/subscribe/coding-plan?code=7kYF2VoaCn&source=link)
+[![Kimi K2.7 Code](https://gcdn.moonshot.cn/growth-cdn/sponsor/kimi-zh.png)](https://platform.kimi.com?aff=cc-switch)

-MiniMax M2.7 是 MiniMax 首个深度参与自我迭代的模型，可自主构建复杂 Agent Harness，并基于 Agent Teams、复杂 Skills、Tool Search Tool 等能力完成高复杂度生产力任务；其在软件工程、端到端项目交付及办公场景中表现优异，多项评测接近行业领先水平，同时具备稳定的复杂任务执行、环境交互能力以及良好的情商与身份保持能力。
+Kimi K3 是 Moonshot AI 迄今能力最强的模型，也是全球首个开源 3T 级模型。K3 拥有 2.8T 参数、原生视觉能力与 100 万 Token 上下文，在长程编码、知识工作和推理任务中展现前沿性能。使用 CC Switch，可以在各类 Agent 工具中便捷配置和切换 Kimi。**[点击此处开始使用 Kimi](https://platform.kimi.com?aff=cc-switch)**

-[点击此处](https://platform.minimaxi.com/subscribe/coding-plan?code=7kYF2VoaCn&source=link)享 MiniMax Token Plan 专属 88 折优惠！
+主要进行编程工作？可以试试 **[Kimi Code 订阅](https://www.kimi.com/code/?aff=cc-switch)**。

 ---

@@ -39,13 +40,13 @@ MiniMax M2.7 是 MiniMax 首个深度参与自我迭代的模型，可自主构
 </tr>

 <tr>
-<td width="180"><a href="https://aigocode.com/invite/CC-SWITCH"><img src="assets/partners/logos/aigocode.png" alt="AIGoCode" width="150"></a></td>
-<td>感谢 AIGoCode 赞助了本项目！AIGoCode 是一个集成了 Claude Code、Codex 以及 Gemini 最新模型的一站式平台，为你提供稳定、高效且高性价比的AI编程服务。本站提供灵活的订阅计划，零封号风险，国内直连，无需魔法，极速响应。AIGoCode 为 CC Switch 的用户提供了特别福利，通过<a href="https://aigocode.com/invite/CC-SWITCH">此链接</a>注册的用户首次充值可以获得额外10%奖励额度！</td>
+<td width="180"><a href="https://zetaapi.ai/go/u117"><img src="assets/partners/logos/zetaapi-banner.png" alt="ZetaAPI" width="150"></a></td>
+<td>感谢 ZetaAPI 赞助本项目！ZetaAPI 主打模型不掺水、保真不降智、价格低至官方价 35 折，平台不混量、不暗中替换低质量模型、不做虚假路由，支持 Claude Code、Codex、Gemini、ChatGPT 等主流模型接入，帮助用户在保证模型质量的同时大幅降低 API 使用成本。同时，ZetaAPI 提供企业级 SLA 稳定性保障、标准接口兼容、一个 Key 接入多模型、快速集成、按量计费等能力，适用于 AI 产品、代码生成、企业内部工具、客服系统、内容生产和自动化流程等场景。若经验证发现模型质量与标称不符，ZetaAPI 承诺假一赔十，让用户用得更稳定、更透明、更放心。通过<a href="https://zetaapi.ai/go/u117">此链接</a>注册，并在首次充值时使用优惠码 CC-SWITCH，即可享受 CC Switch 用户专属的首次充值九折优惠！</td>
 </tr>

 <tr>
-<td width="180"><a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF"><img src="assets/partners/logos/shengsuanyun.png" alt="Shengsuanyun" width="150"></a></td>
-<td>感谢胜算云赞助了本项目！胜算云是专为AI Native Teams服务的超级工厂，工业级AI任务并行执行平台，模型商城集采直供聚合接入了Claude、Chatgpt、Gemini等海内外LLM及图片视频多媒体模型算力，绝无逆向掺水、全站模型SLA可用性高达99.7%、<a href="https://watch.shengsuanyun.com/status/shengsuanyun">监测接口</a>日常全绿。更有企业级专属定制网关，实现团队精细化成本与权限管控，智能路由+安全防护+BYOK企业自带密钥托管。平台按量及tokens plan（即将上线）计费，可开票，使用<a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF">此链接</a>注册新用户可获10元模力及首充10%赠送。</td>
+<td width="180"><a href="https://apinebula.com/VjM74M"><img src="assets/partners/logos/apinebula_banner.png" alt="APINebula" width="150"></a></td>
+<td>感谢 APINEBULA 赞助本项目！APINEBULA 是银河录像局旗下的企业级 AI 聚合平台，背靠大平台资源，面向开发者、团队与企业用户提供稳定、高性价比的大模型 API 接入服务。平台聚合 Claude、GPT、Gemini 等主流满血模型，一个接口，接入全球顶尖 AI 大模型，各大模型价格低至 1 折起，支持企业级高并发、正式合同、对公打款与开票服务，适合 AI 编程、Agent 开发、业务系统集成等多种场景！使用<a href="https://apinebula.com/VjM74M">此链接</a>注册并在充值时填写 <strong>"ccswitch"</strong> 优惠码可享<strong>九折优惠</strong>！</td>
 </tr>

 <tr>
@@ -62,24 +63,85 @@ Claude Code / Codex / Gemini 官方渠道低至 3.8 / 0.2 / 0.9 折，充值更
 </tr>

 <tr>
-<td width="180"><a href="https://www.volcengine.com/activity/agentplan?utm_campaign=hw&utm_content=ccswitch&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch"><img src="assets/partners/logos/huoshan.png" alt="HuoShan" width="150"></a></td>
-<td>感谢火山方舟Agent Plan 模型赞助了本项目！方舟Agent Plan 模型订阅套餐集成了包含Doubao-Seed、Doubao-Seedance、Doubao-Seedream等在内的字节跳动自研SOTA级模型，覆盖文本、代码、图像、视频等多模态任务。同时支持一站式接入DeepSeek V4、GLM 5.1等主流大模型。超全模态模型与 Harness 升级一步到位，深度支持 Agent 框架与 AI 编程工具。方舟 Agent Plan 为 CC Switch 的用户提供了专属福利：通过<a href="https://www.volcengine.com/activity/agentplan?utm_campaign=hw&utm_content=ccswitch&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch">此链接</a>订阅方舟AgentPlan，新客户首月40元起！<a href="https://www.byteplus.com/en/product/modelark?utm_campaign=hw&utm_content=ccswitch&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch">>>For developers outside Mainland China, please click here</a></td>
+<td width="180"><a href="https://api.fenno.ai/register?redirect=/purchase?tab=subscription%26group=16&aff=P9MR3D3PLCNL"><img src="assets/partners/logos/fenno-banner.png" alt="Fenno.ai" width="150"></a></td>
+<td>感谢 Fenno.ai 赞助了本项目！Fenno.ai 是一家稳定、高效的 API 中转服务商，目前主要提供 Codex 中转服务，兼容 OpenAI 及 Anthropic 协议，可灵活接入 Codex、Claude Code、OpenCode 等主流编程工具，可稳定支撑千亿 Token/日的企业级调用需求，支持国内及海外主体公对公结算、开票。Fenno.ai 为 CC Switch 的用户提供了专属福利：通过<a href="https://api.fenno.ai/register?redirect=/purchase?tab=subscription%26group=16&aff=P9MR3D3PLCNL">此链接</a>即可订阅 9.9 元/150 刀额度的超值 Coding Plan，邀请好友最高可享 20% 奖励，多邀多得！</td>
 </tr>

 <tr>
-<td width="180"><a href="https://cloud.siliconflow.cn/i/drGuwc9k"><img src="assets/partners/logos/silicon_zh.jpg" alt="SiliconFlow" width="150"></a></td>
-<td>感谢硅基流动赞助了本项目！硅基流动是一个高性能 AI 基础设施与模型 API 平台，一站式提供语言、语音、图像、视频等多模态模型的快速、可靠访问。平台支持按量计费、丰富的多模态模型选择、高速推理和企业级稳定性，帮助开发者和团队更高效地构建和扩展 AI 应用。通过<a href="https://cloud.siliconflow.cn/i/drGuwc9k">此链接</a>注册并完成实名认证，即可获得 ¥16 奖励金，可在平台内跨模型使用。硅基流动现已兼容 OpenClaw，用户可接入硅基流动 API Key 免费调用主流 AI 模型。</td>
+<td width="180"><a href="https://runapi.co/register?aff=iOKB"><img src="assets/partners/logos/runapi.jpg" alt="RunAPI" width="150"></a></td>
+<td>感谢 RunAPI 赞助本项目！RunAPI 是高效稳定的 AI 模型 API 中转平台，一个 API Key 即可访问 OpenAI、Claude、Gemini、DeepSeek、Grok 等 150+ 主流模型，低至 1 折，极其稳定，可以无缝兼容 Claude Code、OpenClaw 等工具。RunAPI为CC switch的用户提供了特别福利，使用<a href="https://runapi.co/register?aff=iOKB">此链接</a>注册并首次充值即可享受10%的优惠折扣！</td>
 </tr>

 <tr>
-<td width="180"><a href="https://cubence.com/signup?code=CCSWITCH&source=ccs"><img src="assets/partners/logos/cubence.png" alt="Cubence" width="150"></a></td>
-<td>感谢 Cubence 赞助本项目！Cubence 是一家可靠高效的 API 中继服务提供商，提供对 Claude Code、Codex、Gemini 等模型的中继服务，并提供按量、包月等灵活的计费方式。Cubence 为 CC Switch 的用户提供了特别优惠：使用 <a href="https://cubence.com/signup?code=CCSWITCH&source=ccs">此链接</a> 注册，并在充值时输入 "CCSWITCH" 优惠码，每次充值均可享受九折优惠！</td>
+<td width="180"><a href="https://unity2.ai/register?source=ccs"><img src="assets/partners/logos/unity2.jpg" alt="Unity2.ai" width="150"></a></td>
+<td>感谢 Unity2.ai 赞助了本项目！Unity2.ai 是面向个人开发者、团队和企业的高性能 AI 模型 API 中转平台，长期服务国内头部企业，日均承载超 300 亿 token 调用，支持 5000 RPM 级高并发。支持余额计费、首充赠额、组合订阅、企业开票和专属对接。通过<a href="https://unity2.ai/register?source=ccs">此链接</a>注册可领取 $2 余额，加入官方群再送 $10 余额，最高可领 $12 免费额度！</td>
 </tr>

 <tr>
-<td width="180"><a href="https://www.dmxapi.cn/register?aff=bUHu"><img src="assets/partners/logos/dmx-zh.jpeg" alt="DMXAPI" width="150"></a></td>
-<td>感谢 DMXAPI（大模型API）赞助了本项目！ DMXAPI，一个Key用全球大模型。
-为200多家企业用户提供全球大模型API服务。· 充值即开票 ·当天开票 ·并发不限制  ·1元起充 ·  7x24 在线技术辅导，GPT/Claude/Gemini全部6.8折，国内模型5~8折，Claude Code 专属模型3.4折进行中！<a href="https://www.dmxapi.cn/register?aff=bUHu">点击这里注册</a></td>
+<td width="180"><a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF"><img src="assets/partners/logos/shengsuanyun.png" alt="Shengsuanyun" width="150"></a></td>
+<td>感谢胜算云赞助了本项目！胜算云是专为AI Native Teams服务的超级工厂，工业级AI任务并行执行平台，模型商城集采直供聚合接入了Claude、Chatgpt、Gemini等海内外LLM及图片视频多媒体模型算力，绝无逆向掺水、全站模型SLA可用性高达99.7%、<a href="https://watch.shengsuanyun.com/status/shengsuanyun">监测接口</a>日常全绿。更有企业级专属定制网关，实现团队精细化成本与权限管控，智能路由+安全防护+BYOK企业自带密钥托管。平台按量及tokens plan（即将上线）计费，可开票，使用<a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF">此链接</a>注册新用户可获10元模力及首充10%赠送。</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://aigocode.com/invite/CC-SWITCH"><img src="assets/partners/logos/aigocode.png" alt="AIGoCode" width="150"></a></td>
+<td>感谢 AIGoCode 赞助了本项目！AIGoCode 是一个集成了 Claude Code、Codex 以及 Gemini 最新模型的一站式平台，为你提供稳定、高效且高性价比的AI编程服务。本站提供灵活的订阅计划，零封号风险，国内直连，无需魔法，极速响应。AIGoCode 为 CC Switch 的用户提供了特别福利，通过<a href="https://aigocode.com/invite/CC-SWITCH">此链接</a>注册的用户首次充值可以获得额外10%奖励额度！</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://subrouter.ai/register?aff=l3ri"><img src="assets/partners/logos/subrouter-banner.png" alt="SubRouter" width="150"></a></td>
+<td>感谢 SubRouter 赞助本项目！SubRouter 是面向 AI 服务经营者的公开市场与智能路由平台。商家可快速开通独立经营站，发布套餐、管理用户与模型价格；用户可在市场发现服务，并通过统一 API 获得稳定高效的模型调用。通过<a href="https://subrouter.ai/register?aff=l3ri">此链接</a>注册！</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://apikey.fun/register?aff=CCSwitch"><img src="assets/partners/logos/apikey_banner.png" alt="APIKEY.FUN" width="150"></a></td>
+<td>感谢 APIKEY.FUN 赞助本项目！APIKEY.FUN 是一家专业的企业级 AI 中转站，致力于为企业和个人开发者提供稳定、高效、低成本的 AI 模型 API 接入服务。平台支持 Claude、OpenAI、Gemini 等主流热门模型，价格低至官方原价的 7%。通过本项目<a href="https://apikey.fun/register?aff=CCSwitch">专属链接</a>注册，还可享受最高 <strong>充值永久 95 折</strong> 专属优惠。</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://console.claudeapi.com/register?aff=pCLD"><img src="assets/partners/logos/claudeapi.png" alt="ClaudeAPI" width="150"></a></td>
+<td>本项目由 <a href="https://console.claudeapi.com/register?aff=pCLD">Claude API</a> 赞助。Claude API 直连，三分钟接入 Claude Code 与 Agent 应用 新用户可领取测试额度。基于 Anthropic 官方 Key + AWS Bedrock 官方渠道，非逆向、非降智，支持 Opus / Sonnet / Haiku 全系列模型，保留 Tool Use、1M 上下文等官方能力。适合 Claude Code 深度用户、Agent 工程师与企业技术团队，支持开票和团队对接。点击<a href="https://console.claudeapi.com/register?aff=pCLD">这里</a>注册！</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://code0.ai/agent/register/B2XHxGjGmRvqgznY"><img src="assets/partners/logos/code0.png" alt="code0.ai" width="150"></a></td>
+<td>感谢 <a href="https://code0.ai/agent/register/B2XHxGjGmRvqgznY">code0.ai</a> 赞助本项目！code0.ai 是专为开发者打造的 AI 编程服务平台，支持 Claude Code、Codex、Gemini 等主流 AI 编程能力，帮助个人开发者和团队更稳定、更高效地使用 AI Agent 完成代码开发、调试与自动化任务。ccswitch 用户可通过 <a href="https://code0.ai/agent/register/B2XHxGjGmRvqgznY">code0.ai 官网</a> 联系客服领取测试额度，体验高效稳定的 AI 编程服务！</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://teamorouter.com/zh?utm_source=cc_switch&utm_medium=referral&utm_campaign=ai_directory"><img src="assets/partners/logos/TeamoRouter-banner.png" alt="TeamoRouter" width="150"></a></td>
+<td>感谢 TeamoRouter 赞助本项目！TeamoRouter 是一款面向开发者、AI 团队和企业的企业级 Agentic LLM 网关。无需任何订阅，你就可以通过一个统一 API 访问 Claude Code、Codex、Gemini CLI、OpenAI Codex 以及其他热门 AI Agent，同时享受最高可达 90% 折扣的 API 价格。
+不同于常见的 API 中转服务，TeamoRouter 聚合了数百家官方模型提供商和可信基础设施合作伙伴，包括 OpenAI、Anthropic、Vertex、Azure 和 AWS Bedrock。每个提供商都经过验证，确保 100% 兼容 Agent 协议，并具备可靠的缓存性能和请求可追踪性，从而提供稳定质量，而不是反向工程或缩水后的接口。平台提供接近官方水平的 TTFT、99.6% SLA、最高 5,000 QPM 的企业级吞吐量，以及行业领先的缓存命中率，可大幅降低长时间运行的 Agent 工作流中的 token 成本。
+TeamoRouter 还提供企业级功能，包括集中账单、团队管理、BYOK、智能路由、用量分析、动态提供商优化和专属支持。为了获得更简单的使用体验，Teamo Desktop 支持你一键使用 Claude Code、Codex、Gemini CLI 和其他热门 AI Agent，无需管理 API Key，也无需手动配置网关。新用户通过<a href="https://teamorouter.com/zh?utm_source=cc_switch&utm_medium=referral&utm_campaign=ai_directory">此链接</a>注册，首次充值可享受 10% 折扣。</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.newapi.ai/"><img src="assets/partners/logos/newapi-banner.png" alt="new-api" width="150"></a></td>
+<td>感谢开源 AI 基础设施项目 <a href="https://www.newapi.ai/">new-api</a> 对本项目的鼎力支持！new-api 是由 QuantumNous（锟腾科技）推出的开源 AI 基础设施项目，也是活跃度与使用规模领先的大模型统一接入与分发项目之一，专注于帮助开发者、团队和企业以更低成本构建可管理、可扩展的 AI 服务平台。作为同样扎根开源生态的项目，new-api 希望通过赞助支持更多优秀开源项目持续发展。🌟 欢迎 Star 支持 new-api：<a href="https://github.com/QuantumNous/new-api">https://github.com/QuantumNous/new-api</a>，官网：<a href="https://www.newapi.ai/">https://www.newapi.ai/</a>。</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://claudecn.ai/register?aff=HEL9"><img src="assets/partners/logos/claudecn.jpg" alt="ClaudeCN" width="150"></a></td>
+<td>感谢 ClaudeCN 赞助本项目！ClaudeCN 由是一家实体企业运营的企业级AI中转平台。平台可提供高可用性的商用API服务，提供Claude、GPT、Deepseek等热门模型，支持企业采购流程，可对公打款、签约，服务合规有保障。点击<a href="https://claudecn.ai/register?aff=HEL9">此链接</a>注册！</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.volcengine.com/activity/ai618?utm_campaign=hw&utm_content=hw&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch"><img src="assets/partners/logos/huoshan.png" alt="HuoShan" width="150"></a></td>
+<td>感谢火山方舟 Agent Plan 模型赞助了本项目！方舟 Agent Plan 模型订阅套餐集成了包含 Doubao-Seed、Doubao-Seedance、Doubao-Seedream 等在内的字节跳动自研 SOTA 级模型，覆盖文本、代码、图像、视频等多模态任务。最新支持 MiniMax-M3、DeepSeek-V4 系列、GLM-5.1、Doubao-Seed-2.0 系列、Kimi-K2.6 等模型，工具不限。超全模态模型与 Harness 升级一步到位，深度支持 Agent 框架与 AI 编程工具。一次订阅，可以为不同任务切换合适的 AI 引擎。方舟 Coding Plan 为 CC Switch 的用户提供了专属福利：通过<a href="https://www.volcengine.com/activity/ai618?utm_campaign=hw&utm_content=hw&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch">此链接</a>订阅方舟 Coding Plan，新客户首两个月享 2.5 折优惠，再用专属邀请码 6J6FV5N2 领取奖励叠加 9.5 折，低至 9.4 元/月！<a href="https://www.byteplus.com/en/product/modelark?utm_campaign=hw&utm_content=ccswitch&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch">>>For developers outside Mainland China, please click here</a></td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://cloud.siliconflow.cn/i/YflgU2Ve"><img src="assets/partners/logos/silicon_zh.jpg" alt="SiliconFlow" width="150"></a></td>
+<td>感谢硅基流动赞助了本项目！硅基流动是一个高性能 AI 基础设施与模型 API 平台，一站式提供语言、语音、图像、视频等多模态模型的快速、可靠访问。平台支持按量计费、丰富的多模态模型选择、高速推理和企业级稳定性，帮助开发者和团队更高效地构建和扩展 AI 应用。通过<a href="https://cloud.siliconflow.cn/i/YflgU2Ve">此链接</a>注册并完成实名认证，即可获得 ¥16 奖励金，可在平台内跨模型使用。硅基流动现已兼容 OpenClaw，用户可接入硅基流动 API Key 免费调用主流 AI 模型。</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://nekocode.ai?aff=CCSWITCH"><img src="assets/partners/logos/nekocode-banner.png" alt="NekoCode" width="150"></a></td>
+<td>感谢 <a href="https://nekocode.ai?aff=CCSWITCH">NekoCode</a> 赞助本项目！NekoCode 为开发者提供稳定、高效、可靠的 Claude、Codex 等 AI 模型 API 中转服务，价格透明，接入便捷，支持灵活的按量计费。CC Switch 用户专享 9 折福利：通过 <a href="https://nekocode.ai?aff=CCSWITCH">此链接</a> 注册，并在充值时输入优惠码 <code>cc-switch</code>，即可享受充值 9 折优惠！</td>
+</tr>
+
+<tr>
+<td width="180"><a href="https://www.atlascloud.ai/coding-plan?utm_source=github&utm_campaign=cc-switch"><img src="assets/partners/logos/atlascloud_banner.png" alt="Atlas Cloud" width="150"></a></td>
+<td>Atlas Cloud 是一个全模态 AI 推理平台，通过单一 API 为开发者提供视频生成、图像生成及 LLM 接入。免去繁琐的多供应商对接，一次连接即可调用 300+ 款全模态精选模型。立即查看 Atlas Cloud 全新<a href="https://www.atlascloud.ai/coding-plan?utm_source=github&utm_campaign=cc-switch">“编程计划”</a>优惠，获取更具性价比的 API 接入！</td>
 </tr>

 <tr>
@@ -88,18 +150,8 @@ Claude Code / Codex / Gemini 官方渠道低至 3.8 / 0.2 / 0.9 折，充值更
 </tr>

 <tr>
-<td width="180"><a href="https://aicoding.sh/i/CCSWITCH"><img src="assets/partners/logos/aicoding.jpg" alt="AICoding" width="150"></a></td>
-<td>感谢 AICoding.sh 赞助了本项目！AICoding.sh —— 全球大模型 API 超值中转服务！Claude Code 1.9 折，GPT 0.1 折，已为数百家企业提供高性价比 AI 服务。支持 Claude Code、GPT、Gemini 及国内主流模型，企业级高并发、极速开票、7×24 专属技术支持，通过<a href="https://aicoding.sh/i/CCSWITCH">此链接</a> 注册的 CC Switch 用户，首充可享受九折优惠！</td>
-</tr>
-
-<tr>
-<td width="180"><a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch"><img src="assets/partners/logos/crazyrouter.png" alt="Crazyrouter" width="150"></a></td>
-<td>感谢 Crazyrouter 赞助了本项目！Crazyrouter 是一个高性能 AI API 聚合平台——一个 API Key 即可访问 300+ 模型，包括 Claude Code、Codex、Gemini CLI 等。全部模型低至官方定价的 55%，支持自动故障转移、智能路由和无限并发。Crazyrouter 为 CC Switch 用户提供了专属优惠：通过<a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch">此链接</a>注册后联系客服即可领取 <strong>$2 免费额度</strong>，首次充值时输入优惠码 `CCSWITCH` 还可获得额外 <strong>30% 奖励额度</strong>！</td>
-</tr>
-
-<tr>
-<td width="180"><a href="https://www.right.codes/register?aff=CCSWITCH"><img src="assets/partners/logos/rightcode.jpg" alt="RightCode" width="150"></a></td>
-<td>感谢 Right Code 赞助了本项目！Right Code 稳定提供 Claude Code、Codex、Gemini 等模型的中转服务，并可选按量、包月两种计费模式。充值即可开票，企业、团队用户一对一对接。同时为 CC Switch 的用户提供了特别优惠：通过<a href="https://www.right.codes/register?aff=CCSWITCH">此链接</a>注册，每次充值均可获得实付金额5%的按量额度！</td>
+<td width="180"><a href="https://www.ccsub.net/register?ref=Y6Z8DXEA"><img src="assets/partners/logos/ccsub.svg" alt="CCSub" width="150"></a></td>
+<td>感谢 CCSub 赞助本项目！CCSub 是稳定、实惠的 AI API 中转平台，是 Claude Code 官方订阅的超强平替。一个 API Key 即可调用 Claude Opus 4.8、Sonnet 4.6、Haiku 4.5、GPT-5、Gemini、DeepSeek 全系列模型，价格约为官方直连的 1/3，全球直连无需梯子。兼容 Claude Code、Codex、Cursor、Cline、Continue、Windsurf 等所有主流 AI 编程工具。通过<a href="https://www.ccsub.net/register?ref=Y6Z8DXEA">此链接</a>注册即送 $5 体验额度！</td>
 </tr>

 <tr>
@@ -111,34 +163,31 @@ Claude Code / Codex / Gemini 官方渠道低至 3.8 / 0.2 / 0.9 折，充值更
 <td width="180"><a href="https://www.micuapi.ai/register?aff=aOYQ"><img src="assets/partners/logos/mikubanner.svg" alt="Micu" width="150"></a></td>
 <td>感谢 米醋API 赞助了本项目！米醋API 是一家致力于提供极致性价比与高稳定性的全球大模型中转服务商。米醋API 背后有实体企业做核心保障，杜绝跑路风险，支持极速正规开票！我们主打“试错零成本”：1 元起充低门槛，0 手续费随时退款！米醋API 为本软件的用户提供了特别优惠，使用<a href="https://www.micuapi.ai/register?aff=aOYQ">此链接</a>注册并在充值时填写"ccswitch"优惠码可享九折优惠！</td>
 </tr>
+
 <tr>
-<td width="180"><a href="https://lemondata.cc/r/FFX1ZDUP"><img src="assets/partners/logos/lemondata.png" alt="LemonData" width="150"></a></td>
-<td>感谢 LemonData 赞助了本项目！LemonData 是一个高性能 AI API 聚合平台——一个 API Key 即可访问 GPT、Claude、Gemini、DeepSeek 等 300+ 模型。所有模型定价为官方价格的 30%-70%，支持自动故障转移、智能路由和无限并发。新用户注册即获 $1 免费额度——通过<a href="https://lemondata.cc/r/FFX1ZDUP">此链接</a>注册即可领取奖励，立即开始开发！</td>
+<td width="180"><a href="https://www.right.codes/register?aff=CCSWITCH"><img src="assets/partners/logos/rightcode.jpg" alt="RightCode" width="150"></a></td>
+<td>感谢 Right Code 赞助了本项目！Right Code 稳定提供 Claude Code、Codex、Gemini 等模型的中转服务，并可选按量、包月两种计费模式。充值即可开票，企业、团队用户一对一对接。同时为 CC Switch 的用户提供了特别优惠：通过<a href="https://www.right.codes/register?aff=CCSWITCH">此链接</a>注册，每次充值均可获得实付金额5%的按量额度！</td>
 </tr>

 <tr>
-<td width="180"><a href="https://ctok.ai"><img src="assets/partners/logos/ctok.png" alt="CTok" width="150"></a></td>
-<td>感谢 CTok.ai 赞助了本项目！CTok.ai 致力于打造一站式 AI 编程工具服务平台。我们提供 Claude Code 专业套餐及技术社群服务，同时支持 Google Gemini 和 OpenAI Codex。通过精心设计的套餐方案和专业的技术社群，为开发者提供稳定的服务保障和持续的技术支持，让 AI 辅助编程真正成为开发者的生产力工具。点击<a href="https://ctok.ai">这里</a>注册！</td>
+<td width="180"><a href="https://etok.ai"><img src="assets/partners/logos/etok.png" alt="ETok" width="150"></a></td>
+<td>感谢 ETok.ai 赞助了本项目！ETok.ai 致力于打造一站式 AI 编程工具服务平台。我们提供 Claude Code 专业套餐及技术社群服务，同时支持 Google Gemini 和 OpenAI Codex。通过精心设计的套餐方案和专业的技术社群，为开发者提供稳定的服务保障和持续的技术支持，让 AI 辅助编程真正成为开发者的生产力工具。点击<a href="https://etok.ai">这里</a>注册！</td>
 </tr>

 <tr>
-<td width="180"><a href="https://vibecodingapi.ai"><img src="assets/partners/logos/lioncc.png" alt="LionCC" width="150"></a></td>
-<td>感谢 LionCC 狮子API 赞助了本项目！LionCC 专为追求极致开发体验的”Vibe Coders”而生。我们提供稳定、低延迟、优惠价格的 Claude Code、Codex 及 OpenClaw 算力服务，可节约 50% 成本。注册后添加客服微信 HSQBJ088888888，发暗号 cc-switch 备注即可送 10 美金额度（1000 万 token 算力）。其他项目合作关注博客 @LionCC.ai，点击<a href=”https://vibecodingapi.ai”>这里</a>注册！</td>
+<td width="180"><a href="https://cubence.com/signup?code=CCSWITCH&source=ccs"><img src="assets/partners/logos/cubence.png" alt="Cubence" width="150"></a></td>
+<td>感谢 Cubence 赞助本项目！Cubence 是一家可靠高效的 API 中继服务提供商，提供对 Claude Code、Codex、Gemini 等模型的中继服务，并提供按量、包月等灵活的计费方式。Cubence 为 CC Switch 的用户提供了特别优惠：使用 <a href="https://cubence.com/signup?code=CCSWITCH&source=ccs">此链接</a> 注册，并在充值时输入 "CCSWITCH" 优惠码，每次充值均可享受九折优惠！</td>
 </tr>

 <tr>
-<td width="180"><a href="https://console.claudeapi.com/register?aff=pCLD"><img src="assets/partners/logos/claudeapi.png" alt="ClaudeAPI" width="150"></a></td>
-<td>本项目由 <a href="https://console.claudeapi.com/register?aff=pCLD">Claude API</a> 赞助。Claude API 直连，三分钟接入 Claude Code 与 Agent 应用 新用户可领取测试额度。基于 Anthropic 官方 Key + AWS Bedrock 官方渠道，非逆向、非降智，支持 Opus / Sonnet / Haiku 全系列模型，保留 Tool Use、1M 上下文等官方能力。适合 Claude Code 深度用户、Agent 工程师与企业技术团队，支持开票和团队对接。点击<a href="https://console.claudeapi.com/register?aff=pCLD">这里</a>注册！</td>
+<td width="180"><a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch"><img src="assets/partners/logos/crazyrouter.png" alt="Crazyrouter" width="150"></a></td>
+<td>感谢 Crazyrouter 赞助了本项目！Crazyrouter 是一个高性能 AI API 聚合平台——一个 API Key 即可访问 300+ 模型，包括 Claude Code、Codex、Gemini CLI 等。全部模型低至官方定价的 55%，支持自动故障转移、智能路由和无限并发。Crazyrouter 为 CC Switch 用户提供了专属优惠：通过<a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch">此链接</a>注册后联系客服即可领取 <strong>$2 免费额度</strong>，首次充值时输入优惠码 `CCSWITCH` 还可获得额外 <strong>30% 奖励额度</strong>！</td>
 </tr>

 <tr>
-<td width="180"><a href="https://claudecn.top"><img src="assets/partners/logos/claudecn.jpg" alt="ClaudeCN" width="150"></a></td>
-<td>感谢 ClaudeCN 赞助本项目！ClaudeCN 由是一家实体企业运营的企业级AI中转平台。平台可提供高可用性的商用API服务，提供Claude、GPT、Deepseek等热门模型，支持企业采购流程，可对公打款、签约，服务合规有保障。点击<a href="https://claudecn.top">此链接</a>注册！</td>
-</tr>
-
-<tr>
-<td width="180"><a href="https://runapi.co"><img src="assets/partners/logos/runapi.jpg" alt="RunAPI" width="150"></a></td>
-<td>感谢 RunAPI 赞助本项目！RunAPI 是高效稳定的 AI 模型 API 中转平台，一个 API Key 即可访问 OpenAI、Claude、Gemini、DeepSeek、Grok 等 150+ 主流模型，低至 1 折，极其稳定，可以无缝兼容 Claude Code、OpenClaw 等工具。RunAPI为CC switch的用户提供了特别福利，注册后联系客服可以领取14元额度，点击<a href="https://runapi.co">此链接</a>注册！</td>
+<td width="180"><a href="https://www.dmxapi.cn/register?aff=bUHu"><img src="assets/partners/logos/dmx-zh.jpeg" alt="DMXAPI" width="150"></a></td>
+<td>感谢 DMXAPI（大模型API）赞助了本项目！ DMXAPI，一个Key用全球大模型。
+为200多家企业用户提供全球大模型API服务。· 充值即开票 ·当天开票 ·并发不限制  ·1元起充 ·  7x24 在线技术辅导，GPT/Claude/Gemini全部6.8折，国内模型5~8折，Claude Code 专属模型3.4折进行中！<a href="https://www.dmxapi.cn/register?aff=bUHu">点击这里注册</a></td>
 </tr>

 </table>
@@ -147,13 +196,13 @@ Claude Code / Codex / Gemini 官方渠道低至 3.8 / 0.2 / 0.9 折，充值更

 ## 为什么选择 CC Switch？

-现代 AI 编程依赖于 Claude Code、Codex、Gemini CLI、OpenCode 和 OpenClaw 等 CLI 工具——但每个工具都有自己的配置格式。切换 API 供应商意味着手动编辑 JSON、TOML 或 `.env` 文件，而在多个工具之间缺乏一个统一管理 MCP, SKILLS 的方式。
+现代 AI 编程依赖于 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw 和 Hermes 等工具——但每个工具都有自己的配置格式。切换 API 供应商意味着手动编辑 JSON、TOML 或 `.env` 文件，而在多个工具之间缺乏一个统一管理 MCP, SKILLS 的方式。

-**CC Switch** 为你提供一个桌面应用来管理所有五个 CLI 工具。无需手动编辑配置文件，你将获得一个可视化界面，一键将供应商导入应用，一键在不同的供应商之间进行切换，内置 50+ 供应商预设、统一的 MCP, SKILLS 管理以及系统托盘即时切换功能——所有操作都基于可靠的 SQLite 数据库和原子写入机制，保护你的配置不被损坏。
+**CC Switch** 为你提供一个桌面应用来管理所有支持的 AI 工具。无需手动编辑配置文件，你将获得一个可视化界面，一键将供应商导入应用，一键在不同的供应商之间进行切换，内置 50+ 供应商预设、统一的 MCP, SKILLS 管理以及系统托盘即时切换功能——所有操作都基于可靠的 SQLite 数据库和原子写入机制，保护你的配置不被损坏。

- **一个应用，五个 CLI 工具** — 在单一界面中管理 Claude Code、Codex、Gemini CLI、OpenCode 和 OpenClaw
+- **一个应用，八个工具** — 在单一界面中管理 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw 和 Hermes
 - **告别手动编辑** — 50+ 供应商预设，包括 AWS Bedrock、NVIDIA NIM 和社区中转服务；一键即可切换
- **统一 MCP, SKILLS 管理** — 一个面板管理四个应用的 MCP, SKILLS, 支持双向同步
+- **统一 MCP, SKILLS 管理** — 一个面板管理 Claude、Codex、Gemini、Grok Build、OpenCode 和 Hermes 的 MCP, SKILLS, 支持双向同步
 - **系统托盘快速切换** — 从托盘菜单即时切换供应商，无需打开完整应用
 - **云同步** — 通过 Dropbox、OneDrive、iCloud 或 WebDAV 服务器在不同设备之间同步供应商数据
 - **跨平台** — 基于 Tauri 2 构建的原生桌面应用，支持 Windows、macOS 和 Linux
@@ -167,22 +216,22 @@ Claude Code / Codex / Gemini 官方渠道低至 3.8 / 0.2 / 0.9 折，充值更

 ## 功能特性

-[完整更新日志](CHANGELOG.md) | [发布说明](docs/release-notes/v3.15.0-zh.md)
+[完整更新日志](CHANGELOG.md) | [发布说明](docs/release-notes/v3.16.1-zh.md)

 ### 供应商管理

- **5 个 CLI 工具，50+ 预设** — Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw；复制 key 即可一键导入
- **通用供应商** — 一份配置同步到多个应用（OpenCode、OpenClaw）
+- **8 个支持工具，50+ 预设** — Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes；复制 key 即可一键导入
+- **通用供应商** — 一份配置同步到 Claude Code、Codex 和 Gemini CLI
 - 一键切换、系统托盘快速访问、拖拽排序、导入导出

 ### 代理与故障转移

 - **本地代理热切换** — 格式转换、自动故障转移、熔断器、供应商健康监控和整流器
- **应用级代理接管** — 独立为 Claude、Codex 或 Gemini 配置代理，具体到单个供应商
+- **应用级代理接管** — 独立为 Claude、Codex、Gemini 或 Grok Build 配置代理，具体到单个供应商

 ### MCP、Prompts 与 Skills

- **统一 MCP 面板** — 管理 4 个应用的 MCP 服务器，双向同步，支持 Deep Link 导入
+- **统一 MCP 面板** — 管理 Claude、Codex、Gemini、Grok Build、OpenCode 和 Hermes 的 MCP 服务器，双向同步，支持 Deep Link 导入
 - **Prompts** — Markdown 编辑器，跨应用同步（CLAUDE.md / AGENTS.md / GEMINI.md），回填保护
 - **Skills** — 从 GitHub 仓库或 ZIP 文件一键安装，自定义仓库管理，支持软连接和文件复制

@@ -192,21 +241,21 @@ Claude Code / Codex / Gemini 官方渠道低至 3.8 / 0.2 / 0.9 折，充值更

 ### 会话管理器与工作区

- 浏览、搜索和恢复全部应用对话历史
+- 浏览、搜索和恢复支持的会话来源
 - **工作区编辑器**（OpenClaw）— 编辑 Agent 文件（AGENTS.md、SOUL.md 等），支持 Markdown 预览

 ### 系统与平台

 - **云同步** — 自定义配置目录（Dropbox、OneDrive、iCloud、坚果云、NAS）及 WebDAV 服务器同步
 - **Deep Link** (`ccswitch://`) — 通过 URL 一键导入供应商、MCP 服务器、提示词和技能
- 深色 / 浅色 / 跟随系统主题、开机自启、自动更新、原子写入、自动备份、国际化（中/英/日）
+- 深色 / 浅色 / 跟随系统主题、开机自启、自动更新、原子写入、自动备份、国际化（简中/繁中/英/日）

 ## 常见问题

 <details>
-<summary><strong>CC Switch 支持哪些 AI CLI 工具？</strong></summary>
+<summary><strong>CC Switch 支持哪些 AI 工具？</strong></summary>

-CC Switch 支持五个工具：**Claude Code**、**Codex**、**Gemini CLI**、**OpenCode** 和 **OpenClaw**。每个工具都有专属的供应商预设和配置管理。
+CC Switch 支持八个工具：**Claude Code**、**Claude Desktop**、**Codex**、**Gemini CLI**、**Grok Build**、**OpenCode**、**OpenClaw** 和 **Hermes**。每个工具都有专属的供应商预设和配置管理。

 </details>

@@ -220,7 +269,7 @@ CC Switch 支持五个工具：**Claude Code**、**Codex**、**Gemini CLI**、**
 <details>
 <summary><strong>切换供应商之后我的插件配置怎么不见了？</strong></summary>

-CC Switch 使用“通用配置片段”功能，在不同的供应商之间传递 Key 和请求地址之外的通用数据，您可以在“编辑供应商”菜单的“通用配置面板”里，点击“从当前供应商提取”，把所有的通用数据提取到通用配置中，之后在新建“供应商”的时候，只要勾选“写入通用配置”（默认勾选），就会把插件等数据写入到新的供应商配置中。您的所有配置项都会保存在运行本软件的时候，第一次导入的默认供应商里面，不会丢失。
+CC Switch 使用“通用配置片段”功能，在不同的供应商之间传递 Key 和请求地址之外的通用数据，您可以在“编辑供应商”菜单的“通用配置面板”里，点击“从当前供应商提取”，把所有的通用数据提取到通用配置中，之后在新建“供应商”的时候，只要勾选“应用通用配置”（默认勾选），就会把插件等数据写入到新的供应商配置中。您的所有配置项都会保存在运行本软件的时候，第一次导入的默认供应商里面，不会丢失。

 </details>

@@ -258,6 +307,19 @@ CC Switch macOS 版本已通过 Apple 代码签名和公证，可直接下载安

 </details>

+<details>
+<summary><strong>Linux（Wayland + NVIDIA）：网页内容点不动、缩放后黑屏</strong></summary>
+
+AppImage 会强制 `GDK_BACKEND=x11`（走 XWayland）以规避历史上的原生 Wayland 崩溃。但在较新的 Wayland + NVIDIA 环境下，这会导致网页内容区点不动（标题栏按钮仍可点）、窗口缩放后黑屏。可用内置的逃生开关切回原生 Wayland：
+
+```bash
+CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
+```
+
+如果你是从桌面图标启动的，请把它写进 `.desktop` 的 `Exec=` 行（如 `env CC_SWITCH_GDK_BACKEND=wayland /path/to/AppImage`），或在会话环境中设置。该变量是通用的：在 tiling Wayland 合成器（sway/Hyprland）下若出现点击失效，可反过来设 `CC_SWITCH_GDK_BACKEND=x11`。不设置则保持默认行为。
+
+</details>
+
 ## 文档

 如需了解各项功能的详细使用方法，请查阅 **[用户手册](docs/user-manual/zh/README.md)** — 涵盖供应商管理、MCP/Prompts/Skills、代理与故障转移等全部功能。
@@ -277,8 +339,8 @@ CC Switch macOS 版本已通过 Apple 代码签名和公证，可直接下载安

 - **MCP**：点击"MCP"按钮 → 通过模板或自定义配置添加服务器 → 切换各应用同步开关
 - **Prompts**：点击"Prompts" → 使用 Markdown 编辑器创建预设 → 激活后同步到 live 文件
- **Skills**：点击"Skills" → 浏览 GitHub 仓库 → 一键安装到全部应用
- **会话**：点击"Sessions" → 浏览和搜索和恢复全部应用对话历史
+- **Skills**：点击"Skills" → 浏览 GitHub 仓库 → 一键安装到支持的应用
+- **会话**：点击"Sessions" → 浏览、搜索和恢复支持的会话来源

 > **注意**：首次启动可以手动导入现有 CLI 工具配置作为默认供应商。

@@ -299,7 +361,6 @@ CC Switch macOS 版本已通过 Apple 代码签名和公证，可直接下载安
 **方式一：通过 Homebrew 安装（推荐）**

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

@@ -492,7 +553,7 @@ pnpm test:unit --coverage
 │   ├── lib/
 │   │   ├── api/                # Tauri API 封装（类型安全）
 │   │   └── query/              # TanStack Query 配置
-│   ├── locales/                # 翻译 (zh/en/ja)
+│   ├── locales/                # 翻译 (zh/zh-TW/en/ja)
 │   ├── config/                 # 预设 (providers/mcp)
 │   └── types/                  # TypeScript 类型定义
 ├── src-tauri/                  # 后端 (Rust)
@@ -1,162 +0,0 @@
-/**
- * 统一供应商（Universal Provider）预设配置
- *
- * 统一供应商是跨应用共享的配置，修改后会自动同步到 Claude、Codex、Gemini 三个应用。
- * 适用于 NewAPI 等支持多种协议的 API 网关。
- */
-
-import type {
-  UniversalProvider,
-  UniversalProviderApps,
-  UniversalProviderModels,
-} from "@/types";
-
-/**
- * 统一供应商预设接口
- */
-export interface UniversalProviderPreset {
-  /** 预设名称 */
-  name: string;
-  /** 供应商类型标识 */
-  providerType: string;
-  /** 默认启用的应用 */
-  defaultApps: UniversalProviderApps;
-  /** 默认模型配置 */
-  defaultModels: UniversalProviderModels;
-  /** 网站链接 */
-  websiteUrl?: string;
-  /** 图标名称 */
-  icon?: string;
-  /** 图标颜色 */
-  iconColor?: string;
-  /** 描述 */
-  description?: string;
-  /** 是否为自定义模板（允许用户完全自定义） */
-  isCustomTemplate?: boolean;
-}
-
-/**
- * NewAPI 默认模型配置
- */
-const NEWAPI_DEFAULT_MODELS: UniversalProviderModels = {
-  claude: {
-    model: "claude-sonnet-4-20250514",
-    haikuModel: "claude-haiku-4-20250514",
-    sonnetModel: "claude-sonnet-4-20250514",
-    opusModel: "claude-sonnet-4-20250514",
-  },
-  codex: {
-    model: "gpt-4o",
-    reasoningEffort: "high",
-  },
-  gemini: {
-    model: "gemini-2.5-pro",
-  },
-};
-
-const N1N_DEFAULT_MODELS: UniversalProviderModels = {
-  claude: {
-    model: "claude-3-5-sonnet-20240620",
-    haikuModel: "claude-3-haiku-20240307",
-    sonnetModel: "claude-3-5-sonnet-20240620",
-    opusModel: "claude-3-opus-20240229",
-  },
-  codex: {
-    model: "gpt-4o",
-    reasoningEffort: "high",
-  },
-  gemini: {
-    model: "gemini-1.5-pro-latest",
-  },
-};
-
-/**
- * 统一供应商预设列表
- */
-export const universalProviderPresets: UniversalProviderPreset[] = [
-  {
-    name: "n1n.ai",
-    providerType: "n1n",
-    defaultApps: {
-      claude: true,
-      codex: true,
-      gemini: true,
-    },
-    defaultModels: N1N_DEFAULT_MODELS,
-    websiteUrl: "https://n1n.ai",
-    icon: "openai",
-    iconColor: "#000000",
-    description:
-      "n1n.ai - 聚合 OpenAI, Anthropic, Google 等主流大模型的一站式 AI 服务平台",
-  },
-  {
-    name: "NewAPI",
-    providerType: "newapi",
-    defaultApps: {
-      claude: true,
-      codex: true,
-      gemini: true,
-    },
-    defaultModels: NEWAPI_DEFAULT_MODELS,
-    websiteUrl: "https://www.newapi.pro",
-    icon: "newapi",
-    iconColor: "#00A67E",
-    description:
-      "NewAPI 是一个可自部署的 API 网关，支持 Anthropic、OpenAI、Gemini 等多种协议",
-  },
-  {
-    name: "自定义网关",
-    providerType: "custom_gateway",
-    defaultApps: {
-      claude: true,
-      codex: true,
-      gemini: true,
-    },
-    defaultModels: NEWAPI_DEFAULT_MODELS,
-    icon: "openai",
-    iconColor: "#6366F1",
-    description: "自定义配置的 API 网关",
-    isCustomTemplate: true,
-  },
-];
-
-/**
- * 根据预设创建统一供应商
- */
-export function createUniversalProviderFromPreset(
-  preset: UniversalProviderPreset,
-  id: string,
-  baseUrl: string,
-  apiKey: string,
-  customName?: string,
-): UniversalProvider {
-  return {
-    id,
-    name: customName || preset.name,
-    providerType: preset.providerType,
-    apps: { ...preset.defaultApps },
-    baseUrl,
-    apiKey,
-    models: JSON.parse(JSON.stringify(preset.defaultModels)), // Deep copy
-    websiteUrl: preset.websiteUrl,
-    icon: preset.icon,
-    iconColor: preset.iconColor,
-    createdAt: Date.now(),
-  };
-}
-
-/**
- * 获取预设的显示名称（用于 UI）
- */
-export function getPresetDisplayName(preset: UniversalProviderPreset): string {
-  return preset.name;
-}
-
-/**
- * 根据类型查找预设
- */
-export function findPresetByType(
-  providerType: string,
-): UniversalProviderPreset | undefined {
-  return universalProviderPresets.find((p) => p.providerType === providerType);
-}
@@ -0,0 +1,141 @@
+# Using GPT Models in Claude Code with CC Switch
+
+> Applies to CC Switch 3.17.0 and later. (Both integration methods in this guide existed in earlier versions, but the gpt-5.6 preset and the client-identity fix landed in 3.17.0; on older versions, requesting new models like `gpt-5.6-luna` falsely returns 404.) This guide is compiled from the repository's documentation and code, and all sample data has been de-identified.
+
+## Why local routing is needed
+
+Claude Code targets the Anthropic Messages protocol — that is, `/v1/messages` — whereas the upstreams for Codex-family models, whether the OpenAI Responses API exposed by a third-party gateway or the Codex service behind a ChatGPT subscription, all speak the Responses protocol. The two protocols use completely different request bodies, streaming events, and response structures, so putting such an endpoint directly into Claude Code's config leaves the upstream receiving a `/v1/messages` request it doesn't recognize — which can only fail.
+
+CC Switch's approach is to keep Claude Code always connected to the local route and still sending requests as Anthropic Messages; once the route detects that the active provider is Responses-format, it converts the request into Responses for the upstream, then converts the response back into the Messages shape it returns to Claude Code — tool calls, images, PDFs, and thinking configuration are all within the conversion scope.
+
+This guide covers both integration methods:
+
+- **Method 1 (API Key)**: you have a gateway endpoint and key compatible with the OpenAI Responses API, and you want to run the GPT-family models behind it inside Claude Code.
+- **Method 2 (ChatGPT subscription)**: you have a ChatGPT Plus/Pro subscription and use its quota directly by signing in through Codex OAuth — no API key needed at any point.
+
+The chain has four main steps:
+
+1. When Claude Code is taken over, `ANTHROPIC_BASE_URL` in `~/.claude/settings.json` is written as the local route address (default `http://127.0.0.1:15721`), the auth entry keeps only a placeholder, and real credentials never enter the live config.
+2. The provider's `API Format` is set to OpenAI Responses, telling the route that the real upstream speaks the Responses protocol.
+3. The route converts the `/v1/messages` request into a Responses request body for the upstream; Method 2 additionally carries the OAuth token and the official client identity to reach ChatGPT's Codex service.
+4. After the upstream responds, the route converts the Responses JSON/SSE back into the Messages shape Claude Code understands.
+
+![The Needs Routing marker on a GPT provider in the Claude provider list](../images/claude-codex-routing/01-claude-providers-require-routing.png)
+
+## Prerequisites
+
+- CC Switch installed and able to start (3.17.0 or later; see the version note at the top for why).
+- Claude Code installed and run at least once.
+- For Method 1: a service endpoint compatible with the OpenAI Responses API and its API Key; follow the gateway's documentation for the endpoint and model names. Note it's the **Responses API**, not Chat Completions; a gateway that only offers the Chat format still works — see the `API Format` note in Step 1.
+- For Method 2: a ChatGPT Plus/Pro subscription account.
+
+## Step 1: Add a provider
+
+### Method 1: Third-party Responses gateway (API Key)
+
+Open CC Switch, switch to the top-level `Claude Code` tab, click the plus button in the upper-right corner to add a provider, keep the default `Custom Configuration`, then fill in:
+
+- **Provider Name**: anything you like, e.g. `GPT Gateway`.
+- **API Key**: your gateway key. The real key is stored only in CC Switch and injected by the local route when forwarding.
+- **API Endpoint**: just the gateway's service root, e.g. `https://gpt-gateway.example.com`, without a trailing slash — the route sends requests to the gateway's Responses endpoint (`/v1/responses`) automatically. When the gateway path is unusual, turn on the `Full URL` toggle next to it and paste the complete endpoint verbatim.
+
+Then expand `Advanced Options`:
+
+- **API Format**: change from the default `Anthropic Messages (Native)` to **`OpenAI Responses API (Requires routing)`**. If the gateway only offers the Chat Completions protocol, choose `OpenAI Chat Completions (Requires routing)` here instead; every other step is identical.
+- **Auth Field**: keep the default `ANTHROPIC_AUTH_TOKEN (Default)`; the route sends `Authorization: Bearer <key>` to the upstream — exactly the auth header an OpenAI-compatible gateway expects. Unless the gateway's documentation explicitly requires `x-api-key`, don't switch to `ANTHROPIC_API_KEY`; the wrong choice typically shows up as 401/403.
+- **Model Mapping**: map Claude Code's model roles to the real models the gateway recognizes. **At minimum, fill in the `Default fallback model`** (e.g. `gpt-5.6`, per the gateway's documentation) — if left empty, unmatched requests pass through to the upstream under the original Claude model name and error out, while roles you haven't configured individually fall back to it. For finer control, specify per row: put your main model in `Sonnet`/`Opus`, and a cheap, fast model in `Haiku` (Claude Code's background sub-tasks use this tier). The `Display name` only affects what shows in the `/model` menu; leave it empty to show the real model name directly.
+- **Declare 1M**: the `1M` checkbox on each model-mapping row declares to Claude Code that the tier supports a 1M context. Check it only when the gateway truly serves that model with a window of one million tokens or more (e.g. a gateway offering gpt-5.6 at its API spec); otherwise long conversations will error out at the upstream's real ceiling.
+
+![Method 1: in Advanced Options, set API Format to OpenAI Responses, keep the default auth field, and map to the upstream's real models](../images/claude-codex-routing/02-responses-provider-form.png)
+
+After saving, a `Needs Routing` marker appears on the card — providers like this only work while local routing is running.
+
+### Method 2: ChatGPT subscription (Codex OAuth)
+
+Again on the `Claude Code` tab, click the plus button and pick the **`Codex`** preset with the OpenAI icon from the preset list — it appearing under the Claude Code tab is not a mistake; this preset is built precisely for "using a ChatGPT subscription inside Claude Code":
+
+- **No API Key and no address needed** — requests always go to ChatGPT's Codex service, so the address field in the form needs no changes.
+- Click **`Sign in with ChatGPT`**. This is a device-code flow: CC Switch opens the browser automatically and copies the verification code to the clipboard; paste the code on the browser page to complete authorization, while the app shows `Waiting for authorization...`.
+- After a successful sign-in, `Auth status` shows the signed-in account (email). Multiple accounts are supported: you can `Add another account`, `Set as default`, or pin a specific account to this provider; day-to-day management can also go through `Settings` → `OAuth Authentication Center`.
+- **FAST mode**: an optional toggle; when on, requests carry `service_tier="priority"` for lower latency but consume ChatGPT quota at a higher rate. Keep it off by default.
+- The model tiers are pre-filled: `Sonnet`/`Opus` map to `gpt-5.6`, and `Haiku` maps to `gpt-5.6-luna` (used for background sub-tasks — faster and lighter on quota).
+
+![Method 2: ChatGPT login status and account management in the Codex preset](../images/claude-codex-routing/03-codex-oauth-form.png)
+
+The login credentials are stored in `~/.cc-switch/codex_oauth_auth.json` (not `~/.codex/`), independent of the Codex CLI's own login; the token refreshes automatically before it expires.
+
+## Step 2: Enable local routing and take over Claude Code
+
+Go to the `Routing` page in Settings, expand `Local Routing`, and complete two toggles:
+
+1. Turn on the `Routing Master Switch` to start the local service (the first time you enable it, an explanatory confirmation dialog appears). The default address is `127.0.0.1:15721`.
+2. Turn on `Claude Code` under `Routing Enabled`. If you only want Claude Code to use routing, leave the other apps off.
+
+After takeover, CC Switch points Claude Code's live config at the local route, with only a placeholder in the auth entry; both Method 1's gateway key and Method 2's OAuth token are injected by the local route on forward.
+
+> **Note**: the live config is read when the Claude Code process starts. After you first enable takeover (or disable it to restore a direct connection), if Claude Code is already running, open a new terminal session. Afterward, switching providers in routing mode is a hot switch and needs no further restart.
+
+## Step 3: Switch providers and verify
+
+Return to the Claude Code provider list and click `Enable` on the target provider. If routing isn't running, CC Switch shows "This provider uses OpenAI Responses API format, requires the routing service to work properly. Start routing first." — this notice doesn't block the switch, but with routing off the request is bound to fail, so go back to Step 2 and turn it on.
+
+Inside Claude Code you can verify step by step:
+
+- Open a new session and use `/model` to view the model menu: each tier shows the display name from the model mapping (by default, Method 2 shows `gpt-5.6` and `gpt-5.6-luna`). A few spots in the UI may still show Claude-family model names — those are the internal role aliases the routing takeover uses; this is normal, and the `/model` menu and usage dashboard are authoritative.
+- Send a small question and watch the `Current Provider` on the Settings → Routing page change to your provider and `Total Requests` start to climb.
+- In the usage dashboard, these requests show under the upstream's real models: a tier mapped to `gpt-5.6` resolves to the Sol tier and displays as `GPT-5.6 Sol`, while `gpt-5.6-luna` displays as `GPT-5.6 Luna`; you can filter by provider to reconcile token usage.
+- The Method 2 provider card also shows subscription quota: utilization and reset countdowns for the 5-hour and 7-day windows, drawn from the ChatGPT account itself and shared with the official Codex client.
+
+## Capabilities and known limitations
+
+- **Prompt caching is automatic**: the route injects a stable `prompt_cache_key` per session, and together with OpenAI's automatic prefix caching, long conversations don't resend everything at full price each turn — no configuration needed.
+- **Thinking is mapped to reasoning effort**: Claude Code's thinking toggle and thinking level are mapped to GPT's `reasoning.effort` (low/medium/high); GPT's reasoning content round-trips across turns intact in encrypted form, so multi-turn reasoning coherence is unaffected by the conversion. Method 2 also accesses in stateless mode (`store:false`), leaving no conversation stored on OpenAI's servers.
+- **Tools and multimodal are fully converted**: multi-turn tool calls, image inputs, and PDF inputs are all fully converted.
+- **Context is managed against a 200K window**: Claude Code auto-compacts routed providers against a default 200K window. When the upstream's real window is larger (e.g. gpt-5.6 on ChatGPT's Codex service is 372K), anything beyond 200K currently goes unused — compaction triggers early, which is conservative but safe. The only switch to push past 200K today is the `1M` checkbox in the model mapping (a strict 1M declaration), for use only with Method 1 and only when the upstream truly serves the model at 1M or more; Method 2's upstream ceiling is 372K, short of 1M, so checking it would instead make long conversations error out at the upstream's real ceiling — keep it at the default.
+- **Output ceiling**: for Method 2, the output ceiling is controlled by the ChatGPT server (the `max_tokens` in Claude Code's request is not sent downstream); for Method 1, Claude Code's `max_tokens` is passed through as-is — no configuration needed.
+- **Web search is unavailable**: Claude Code's WebSearch relies on Anthropic's servers to run, which the GPT upstream can't take on, so for tasks involving web search, switch back to a Claude-family provider. Locally executed WebFetch is unaffected.
+- **Dashboard dollar amounts are for reference**: token counts are accurate, but the dollar figures are estimates converted at public API prices — Method 2's subscription traffic is estimated at GPT-5.6's public price, and Method 1's third-party gateways bill at their own rates, so both may differ from what you're actually charged and serve only for comparison. For Method 2, treat the window utilization on the provider card as authoritative for quota consumption.
+
+## FAQ
+
+**The upstream returns 401 or 403 (Method 1)**
+
+First confirm the `Auth Field` in Advanced Options is the default `ANTHROPIC_AUTH_TOKEN (Default)` — switching to `ANTHROPIC_API_KEY` sends `x-api-key`, which the vast majority of OpenAI-compatible gateways don't accept. Then confirm the key itself is valid and has balance.
+
+**Requesting new models like `gpt-5.6-luna` returns 404 Model not found (Method 2)**
+
+Upgrade to CC Switch 3.17.0 or later. On older versions the client identity wasn't aligned with the official Codex client, so the ChatGPT server resolves new models to a nonexistent engine.
+
+**The switch didn't take effect, or the `/model` menu still shows old names**
+
+Both the model menu and the route address are read when Claude Code starts: after first enabling takeover you must open a new terminal session; switching between providers is a hot switch, but the display names in the menu only refresh in a new session.
+
+**Claude Code reports "Codex OAuth authentication failed", or the card shows "Session expired" (Method 2)**
+
+The login credentials have expired. Go back to the provider form or `Settings` → `OAuth Authentication Center` and run through `Sign in with ChatGPT` again; no command-line steps are needed.
+
+**The conversation auto-compacts partway through**
+
+See "Capabilities and known limitations": routed providers are managed against a 200K window, so the compaction threshold comes early — this is expected behavior.
+
+**Restoring the official Claude setup**
+
+Switch back to an official provider, or turn off the `Claude Code` routing toggle on the Routing page — CC Switch restores the pre-takeover live config, and the official login credentials are unaffected throughout. After restoring, you'll again need to open a new terminal session.
+
+**Should you enable FAST mode? (Method 2)**
+
+Leaving it off is fine. Turn it on only if you're especially latency-sensitive and willing to accept faster quota consumption; if the ChatGPT server rejects the parameter, turning the toggle off restores things.
+
+## Compliance note
+
+Method 2 uses ChatGPT subscription quota outside the official Codex client, and this isn't a gray-area hack: Thibault Sottiaux (@thsottiaux), the OpenAI Codex lead, has publicly demonstrated and encouraged pointing Claude Code (the "orange crab", as he jokingly calls it) at GPT-5.6 Sol — using exactly a "local proxy + model alias" approach, the same category as Method 2 here. As the lead of the Codex product line, his active encouragement to use their own model inside a competitor's client shows that running GPT-family models in Claude Code on a subscription is a use the vendor welcomes and encourages people to try.
+
+Two practical reminders are still worth noting: first, this traffic is counted against the same subscription quota as the official Codex client, so heavy use hits the cap sooner; second, CC Switch's authentication center keeps a compliance notice out of caution ("Use your other subscriptions in Claude Code — please be mindful of compliance risks."), and whether this fits the terms that apply to your account is for you to check. When using a third-party gateway in Method 1, separately read the target gateway's terms on billing, compliance, and data retention.
+
+## References
+
+- [CC Switch User Manual: Add a Provider (incl. Codex OAuth reverse proxy and API formats)](../user-manual/en/2-providers/2.1-add.md)
+- [CC Switch User Manual: Proxy Service](../user-manual/en/4-proxy/4.1-service.md)
+- [CC Switch User Manual: App Routing](../user-manual/en/4-proxy/4.2-routing.md)
+- [CC Switch v3.17.0 Release Notes](../release-notes/v3.17.0-en.md)
+- Reverse guide: [Using Claude Models in Codex](./codex-claude-routing-guide-en.md)
@@ -0,0 +1,141 @@
+# CC Switch を使って Claude Code で GPT モデルを利用する
+
+> 対象バージョン: CC Switch 3.17.0 以降（本記事の 2 つの接続方法自体はより古いバージョンにもありますが、gpt-5.6 プリセットとクライアントアイデンティティの修正は 3.17.0 から導入されたため、古いバージョンで `gpt-5.6-luna` のような新しいモデルをリクエストすると 404 が誤って返ることがあります）。本記事はリポジトリ内のドキュメントとコードをもとに整理し、サンプルデータはすべて匿名化しています。
+
+## ローカルルーティングが必要な理由
+
+Claude Code が前提としているのは Anthropic Messages プロトコル、つまり `/v1/messages` です。一方で Codex 系モデルの上流——サードパーティゲートウェイが公開している OpenAI Responses API であれ、ChatGPT サブスクリプションの背後にある Codex サービスであれ——が話すのはすべて Responses プロトコルです。この 2 つのプロトコルは、リクエストボディ、ストリーミングイベント、レスポンス構造がまったく異なります。この種のアドレスをそのまま Claude Code の設定に入れても、上流が受け取るのは自分の知らない `/v1/messages` リクエストであり、結果は失敗にしかなりません。
+
+CC Switch では、Claude Code が常にローカルルートへ接続し、Anthropic Messages のままリクエストを送るようにします。ルートは現在のプロバイダーが Responses 形式だと判定すると、リクエストを Responses に変換して上流へ送り、最後にレスポンスを Messages 形式へ戻して Claude Code に返します——ツール呼び出し、画像、PDF、思考設定もすべて変換の対象です。
+
+対応する 2 つの接続方法を、本記事はどちらもカバーします：
+
+- **方式 1（API Key）**: OpenAI Responses API 互換のゲートウェイエンドポイントと Key を持っていて、その背後の GPT 系モデルを Claude Code で動かしたい場合。
+- **方式 2（ChatGPT サブスクリプション）**: ChatGPT Plus/Pro のサブスクリプションを持っていて、Codex OAuth ログインでサブスクリプション枠を直接使いたい場合。全工程で API Key は不要です。
+
+この経路は主に 4 つのステップに分かれます：
+
+1. Claude Code を引き継ぐと、`~/.claude/settings.json` の `ANTHROPIC_BASE_URL` がローカルルートのアドレス（デフォルトは `http://127.0.0.1:15721`）に書き換えられ、認証項目にはプレースホルダーだけが残り、実際の認証情報は live 設定には入りません。
+2. プロバイダーの `API フォーマット` を OpenAI Responses に設定し、実際の上流は Responses プロトコルだとルートに伝えます。
+3. ルートは `/v1/messages` リクエストを Responses のリクエストボディへ変換して上流へ送ります。方式 2 ではさらに OAuth token と公式クライアントのアイデンティティを付けて ChatGPT の Codex サービスにアクセスします。
+4. 上流から返ってきた後、ルートは Responses の JSON/SSE を Claude Code が理解できる Messages 形式へ変換して返します。
+
+![Claude プロバイダー一覧の GPT プロバイダーに付く「ルーティングが必要」マーク](../images/claude-codex-routing/01-claude-providers-require-routing.png)
+
+## 事前準備
+
+- インストール済みで起動できる CC Switch（3.17.0 以降、理由は冒頭のバージョン説明を参照）。
+- インストール済みで、少なくとも 1 回は実行したことのある Claude Code。
+- 方式 1 に必要なもの: OpenAI Responses API 互換のサービスエンドポイントと対応する API Key。エンドポイントアドレスとモデル名はゲートウェイのドキュメントに従ってください。注意すべきは **Responses API** であって Chat Completions ではないという点です。ゲートウェイが Chat 形式しか提供していない場合でも動作します。Step 1 の「API フォーマット」の説明を参照してください。
+- 方式 2 に必要なもの: ChatGPT Plus/Pro のサブスクリプションアカウント。
+
+## Step 1: プロバイダーを追加する
+
+### 方式 1: サードパーティ Responses ゲートウェイ（API Key）
+
+CC Switch を開き、上部の `Claude Code` タブへ切り替え、右上のプラスボタンからプロバイダーを追加します。デフォルトの `カスタム設定` のまま、次の項目を入力します：
+
+- **プロバイダー名**: 任意です。たとえば `GPT Gateway`。
+- **API Key**: あなたのゲートウェイの Key。実際の Key は CC Switch 内にのみ保存され、ローカルルートが転送時に注入します。
+- **API エンドポイント**: ゲートウェイのサービスルートアドレスを入力すれば十分です。たとえば `https://gpt-gateway.example.com`。末尾にスラッシュを付けないでください。ルートが自動的にそのゲートウェイの Responses エンドポイント（`/v1/responses`）へリクエストを送ります。ゲートウェイのパスが特殊な場合は、隣の `フル URL` スイッチをオンにして、完全なエンドポイントをそのまま貼り付けてください。
+
+続いて `高級オプション` を展開します：
+
+- **API フォーマット**: デフォルトの `Anthropic Messages（ネイティブ）` から **`OpenAI Responses API（ルーティングが必要）`** に変更します。ゲートウェイが Chat Completions プロトコルしか提供していない場合は、ここで `OpenAI Chat Completions（ルーティングが必要）` を選びます。その他のステップはまったく同じです。
+- **認証フィールド**: デフォルトの `ANTHROPIC_AUTH_TOKEN（デフォルト）` のままにします。ルートは `Authorization: Bearer <key>` を上流へ送ります——これはまさに OpenAI 互換ゲートウェイが期待する認証ヘッダーです。ゲートウェイのドキュメントが明確に `x-api-key` を要求している場合を除き、`ANTHROPIC_API_KEY` に変更しないでください。誤って変更した場合の典型的な症状は 401/403 です。
+- **モデルマッピング**: Claude Code のモデル役割を、ゲートウェイが認識する実際のモデルへマッピングします。**少なくとも `既定フォールバックモデル` は入力してください**（たとえば `gpt-5.6`。ゲートウェイのドキュメントに従ってください）——空欄のままだと、一致しなかったリクエストは元の Claude モデル名のまま上流へ転送されてエラーになります。個別に設定していない役割はこのフォールバックへ回帰します。より細かく設定するには、行ごとに指定します：`Sonnet`/`Opus` に主力モデル、`Haiku` に安価で高速なモデル（Claude Code のバックグラウンド小タスクがこの区分を使います）。`表示名` は `/model` メニューでの表示にのみ影響し、空欄なら実際のモデル名がそのまま表示されます。
+- **1M 対応を宣言**: モデルマッピングの各行にある `1M` チェックボックスは、その区分が 1M コンテキストに対応していることを Claude Code に宣言します。ゲートウェイが実際に 100 万トークン以上のウィンドウでそのモデルを提供している場合（たとえば API 仕様どおりに gpt-5.6 を提供するゲートウェイ）にのみチェックしてください。そうでないと、長い対話が上流の実際の上限で直接エラーになります。
+
+![方式 1: 高級オプションで API フォーマットを OpenAI Responses に設定し、認証フィールドはデフォルトのまま、上流の実際のモデルへマッピングする](../images/claude-codex-routing/02-responses-provider-form.png)
+
+保存すると、カードに `ルーティングが必要` のマークが表示されます——この種のプロバイダーは、ローカルルーティングが実行中でなければ正しく動作しません。
+
+### 方式 2: ChatGPT サブスクリプション（Codex OAuth）
+
+同じく `Claude Code` タブでプラスボタンを押し、プリセット一覧で OpenAI アイコンの付いた **`Codex`** プリセットを選びます——これが Claude Code タブの下に出ていても選択ミスではありません。このプリセットはまさに「Claude Code で ChatGPT サブスクリプションを使う」ために用意されたものです：
+
+- **API Key もアドレスの入力も不要です**——リクエストは常に ChatGPT の Codex サービスへ送られるため、フォームのアドレス項目は変更する必要がありません。
+- **`ChatGPT でログイン`** をクリックします。これはデバイスコードフローです：CC Switch が自動的にブラウザを開き、認証コードをクリップボードにコピーします。ブラウザのページで認証コードを貼り付けて認可を完了させてください。その間、アプリ内には `認証を待機中...` と表示されます。
+- ログインに成功すると、`認証状態` にログイン済みアカウント（メールアドレス）が表示されます。複数アカウントに対応しています：`別のアカウントを追加`、`デフォルトに設定`、またはこのプロバイダーで特定のアカウントを指定できます。日常的な管理は `設定` → `OAuth 認証センター` からも行えます。
+- **FAST モード**: 任意のスイッチです。オンにするとリクエストが `service_tier="priority"` を伴い、より低い遅延と引き換えに、より高いレートで ChatGPT のクォータを消費します。デフォルトはオフのままにしてください。
+- モデル区分はあらかじめ入力済みです：`Sonnet`/`Opus` が `gpt-5.6` に、`Haiku` が `gpt-5.6-luna` に対応します（バックグラウンドの小タスクがこれを使い、より速く、より枠を節約します）。
+
+![方式 2: Codex プリセットの ChatGPT ログイン状態とアカウント管理](../images/claude-codex-routing/03-codex-oauth-form.png)
+
+ログイン認証情報は `~/.cc-switch/codex_oauth_auth.json`（`~/.codex/` ではありません）に保存され、Codex CLI 自身のログインとは互いに影響しません。token は有効期限前に自動的に更新されます。
+
+## Step 2: ローカルルーティングを有効にして Claude Code をルーティングする
+
+設定の `ルーティング` ページに入り、`ローカルルーティング` を展開して、2 つのスイッチを設定します：
+
+1. `ルーティング総スイッチ` をオンにしてローカルサービスを起動します（初回起動時は説明の確認ダイアログが表示されます）。デフォルトアドレスは `127.0.0.1:15721` です。
+2. `ルーティング有効` で `Claude Code` をオンにします。Claude Code だけをルーティングしたい場合は、その他のアプリはオフのままで構いません。
+
+引き継ぎ後、CC Switch は Claude Code の live 設定をローカルルートへ向け、認証項目にはプレースホルダーだけが入ります。方式 1 のゲートウェイ Key も方式 2 の OAuth token も、いずれもローカルルートが転送時に注入します。
+
+> **注意**: live 設定は Claude Code プロセスの起動時に読み込まれます。初回の引き継ぎを有効にした後（または引き継ぎをオフにして直結に戻した後）、Claude Code が実行中の場合は、ターミナルセッションを開き直してください。その後、ルーティングモードでのプロバイダー切り替えはホットスワップになり、再起動は不要です。
+
+## Step 3: プロバイダーを切り替えて確認する
+
+Claude Code のプロバイダー一覧に戻り、目的のプロバイダーの `有効化` をクリックします。ルーティングが実行されていない場合、CC Switch は「このプロバイダーは OpenAI Responses API フォーマットを使用しており、ルーティングサービスが必要です。先にルーティングを起動してください」と表示します——この表示は切り替えを妨げませんが、ルーティングが未起動のままではリクエストは必ず失敗します。Step 2 に戻ってオンにすれば解決します。
+
+Claude Code に入ったら、段階的に確認できます：
+
+- 新しいセッションを開き、`/model` でモデルメニューを確認します：各区分にはモデルマッピングの表示名が表示されます（方式 2 のデフォルトは `gpt-5.6`、`gpt-5.6-luna`）。画面の一部の箇所には Claude 系のモデル名が現れることがあります——それはルーティング引き継ぎが使う内部の役割エイリアスであり、正常な現象です。`/model` メニューと使用量ダッシュボードを基準にしてください。
+- 小さな質問を 1 つ送り、設定 → ルーティングページの「現在のプロバイダー」があなたのプロバイダーに変わり、「総リクエスト数」が増え始めるのを確認します。
+- 使用量ダッシュボードでは、これらのリクエストが上流の実際のモデルで表示されます：`gpt-5.6` にマッピングされた区分は Sol 区分として解析され `GPT-5.6 Sol` と表示され、`gpt-5.6-luna` は `GPT-5.6 Luna` と表示されます。プロバイダーで絞り込んで token 使用量を照合できます。
+- 方式 2 のプロバイダーカードには、さらにサブスクリプション枠が表示されます：5 時間ウィンドウと 7 日ウィンドウの利用率とリセットまでのカウントダウンです。データは ChatGPT アカウント自体から取得され、公式 Codex クライアントと同じ枠を共有します。
+
+## 機能の範囲と既知の制限
+
+- **プロンプトキャッシュが自動で有効**: ルートは各セッションに安定した `prompt_cache_key` を注入し、OpenAI 側の自動プレフィックスキャッシュと組み合わせます。長い対話でも毎回全額で再送されることはなく、設定は不要です。
+- **思考を reasoning effort に換算**: Claude Code の思考スイッチと思考レベルは GPT の `reasoning.effort`（low/medium/high）へ換算されます。GPT の推論内容は暗号化された形態でターンをまたいで完全に再生され、複数ターンの推論の一貫性は変換の影響を受けません。方式 2 は同時にステルスモード（`store:false`）でアクセスし、OpenAI サーバー側にはセッションを残しません。
+- **ツールとマルチモーダルを完全変換**: 複数ターンのツール呼び出し、画像、PDF 入力はすべて完全に変換されます。
+- **コンテキストは 200K ウィンドウで管理**: Claude Code はルーティングプロバイダーに対して、デフォルトの 200K ウィンドウで自動圧縮を行います。上流の実際のウィンドウがより大きい場合（たとえば ChatGPT Codex サービスの gpt-5.6 は 372K）でも、200K を超える部分は現状では使われません——圧縮が早めにトリガーされ、保守的ですが安全です。200K を突破したい場合、現在唯一のスイッチはモデルマッピングの `1M` チェックボックス（厳密に 1M を宣言）で、方式 1 に限り、かつ上流が実際に 1M 以上でそのモデルを提供している場合にのみ使用します。方式 2 の上流上限は 372K で 1M には届かないため、チェックするとかえって長い対話が上流の実際の上限でエラーになります。デフォルトのままにしてください。
+- **出力上限**: 方式 2 の出力上限は ChatGPT サーバー側が制御します（Claude Code のリクエスト内の `max_tokens` は下流に送られません）。方式 1 は Claude Code の `max_tokens` をそのまま透過するため、設定は不要です。
+- **Web 検索は利用不可**: Claude Code の WebSearch は Anthropic サーバー側での実行に依存しており、GPT 上流では引き受けられません。Web 検索を伴うタスクは Claude 系プロバイダーへ切り替えることをおすすめします。ローカルで実行される WebFetch は影響を受けません。
+- **使用量ダッシュボードの金額は参考値**: token カウントは正確ですが、ドル金額は公開 API 価格に基づく概算です——方式 2 のサブスクリプショントラフィックは GPT-5.6 の公開価格で換算され、方式 1 のサードパーティゲートウェイはそれぞれのレートで課金されます。どちらも実際の請求額と一致しない可能性があり、比較用途に留めてください。方式 2 の枠の消費は、プロバイダーカード上のウィンドウ利用率を基準にしてください。
+
+## よくある質問
+
+**上流が 401 または 403 を返す（方式 1）**
+
+まず高級オプションの `認証フィールド` がデフォルトの `ANTHROPIC_AUTH_TOKEN（デフォルト）` になっているか確認してください——`ANTHROPIC_API_KEY` に変更すると `x-api-key` で送信され、大多数の OpenAI 互換ゲートウェイはこれを受け付けません。あわせて、Key 自体が有効で残高があることも確認してください。
+
+**`gpt-5.6-luna` などの新しいモデルをリクエストすると 404 Model not found が出る（方式 2）**
+
+CC Switch 3.17.0 以降にアップグレードしてください。古いバージョンではクライアントアイデンティティが公式 Codex クライアントに揃っておらず、ChatGPT サーバー側が新しいモデルを存在しないエンジンへ解決してしまいます。
+
+**切り替えても反映されない、または `/model` メニューが古い名前のまま**
+
+モデルメニューもルーティングアドレスも、Claude Code の起動時に読み込まれます：初回の引き継ぎを有効にした後は必ずターミナルセッションを開き直してください。プロバイダー間の切り替えはホットスワップですが、メニューの表示名は新しいセッションでなければ更新されません。
+
+**Claude Code に「Codex OAuth 認証に失敗しました」と出る、またはカードに「セッションが期限切れです」と表示される（方式 2）**
+
+ログイン認証情報が失効しています。プロバイダーフォーム、または `設定` → `OAuth 認証センター` に戻り、`ChatGPT でログイン` をもう一度実行してください。コマンドライン操作は一切不要です。
+
+**対話の途中で自動的に圧縮されてしまう**
+
+「機能の範囲」を参照してください：ルーティングプロバイダーは 200K ウィンドウで管理され、圧縮のしきい値もそれに合わせて早まります。想定どおりの動作です。
+
+**公式の Claude の使い方に戻したい**
+
+公式プロバイダーに切り替えるか、ルーティングページで `Claude Code` のルーティングスイッチをオフにしてください——CC Switch は引き継ぎ前の live 設定に戻し、公式ログインの認証情報は全工程を通じて影響を受けません。戻した後も同様にターミナルセッションを開き直す必要があります。
+
+**FAST モードをオンにすべきか（方式 2）**
+
+デフォルトのオフのままで構いません。遅延に特に敏感で、かつクォータのより速い消費を受け入れられる場合にのみオンにしてください。ChatGPT サーバー側がこのパラメータを拒否する場合は、スイッチをオフにすれば復旧します。
+
+## コンプライアンスに関する注意
+
+方式 2 は ChatGPT サブスクリプション枠を公式 Codex クライアント以外で使うものですが、これはグレーな手法ではありません：OpenAI Codex の責任者である Thibault Sottiaux（@thsottiaux）自身が、Claude Code（彼が「orange crab」と呼ぶもの）を GPT-5.6 Sol に向けて使うことを公開でデモし、推奨しています——用いているのはまさに「ローカルプロキシ + モデルエイリアス」であり、本記事の方式 2 と同じ類の手法です。Codex という製品ラインの責任者が、競合クライアントで自社モデルを使うことを自ら奨励しているのですから、サブスクリプションで Claude Code に GPT 系モデルを動かすことは、公式が歓迎し、試すことを推奨している使い方だと分かります。
+
+とはいえ、実務上の 2 点は依然として留意する価値があります：1 つは、この部分のトラフィックが公式 Codex クライアントと同じサブスクリプション枠に合算されるため、ヘビーユースではより速く上限に達すること。もう 1 つは、CC Switch の認証センターが念のためコンプライアンス上の注意（「Claude Code で他のサブスクリプションをご利用いただけます。コンプライアンスリスクにご注意ください。」）を残していることです。あなたのアカウントに適用される規約に沿うかどうかは、各自でご確認ください。方式 1 でサードパーティゲートウェイを使う場合は、対象ゲートウェイの課金・コンプライアンス・データ保持に関する規約を別途お読みください。
+
+## 参考リンク
+
+- [CC Switch ユーザーマニュアル: プロバイダーを追加（Codex OAuth リバースプロキシと API フォーマットを含む）](../user-manual/ja/2-providers/2.1-add.md)
+- [CC Switch ユーザーマニュアル: プロキシサービス](../user-manual/ja/4-proxy/4.1-service.md)
+- [CC Switch ユーザーマニュアル: アプリケーションルーティング](../user-manual/ja/4-proxy/4.2-routing.md)
+- [CC Switch v3.17.0 リリースノート](../release-notes/v3.17.0-ja.md)
+- 逆方向のガイド: [Codex で Claude モデルを使う](./codex-claude-routing-guide-ja.md)
@@ -0,0 +1,141 @@
+# 通过 CC Switch 在 Claude Code 中使用 GPT 模型
+
+> 适用版本：CC Switch 3.17.0 及以上（更早版本已具备本文两种接入方式，但 gpt-5.6 预设与客户端身份修复自 3.17.0 落地，低版本请求 `gpt-5.6-luna` 这类新模型会误报 404）。本文根据仓库内文档与代码整理，示例数据均已去敏。
+
+## 为什么需要本地路由
+
+Claude Code 面向的是 Anthropic Messages 协议，也就是 `/v1/messages`；而 Codex 系模型的上游——无论是第三方网关暴露的 OpenAI Responses API，还是 ChatGPT 订阅背后的 Codex 服务——说的都是 Responses 协议。两种协议的请求体、流式事件和返回结构完全不同，把这类地址直接填进 Claude Code 的配置里，上游收到的是它不认识的 `/v1/messages` 请求，结果只能是失败。
+
+CC Switch 的做法是让 Claude Code 始终连本机路由，仍以 Anthropic Messages 发送请求；路由识别当前供应商是 Responses 格式后，把请求转换成 Responses 发给上游，再把响应转换回 Messages 形态返回给 Claude Code——工具调用、图片、PDF、思考配置都在转换范围内。
+
+对应两种接入方式，本文都会覆盖：
+
+- **方式一（API Key）**：你手里有某个兼容 OpenAI Responses API 的网关端点和 Key，想在 Claude Code 里跑它背后的 GPT 系模型。
+- **方式二（ChatGPT 订阅）**：你有 ChatGPT Plus/Pro 订阅，通过 Codex OAuth 登录直接使用订阅额度，全程不需要 API Key。
+
+这条链路主要分成四步：
+
+1. 接管 Claude Code 后，`~/.claude/settings.json` 里的 `ANTHROPIC_BASE_URL` 会被写成本机路由地址（默认 `http://127.0.0.1:15721`），认证项只留占位符，真实凭据不进 live 配置。
+2. 供应商的 `API 格式` 设为 OpenAI Responses，告诉路由：真实上游说的是 Responses 协议。
+3. 路由把 `/v1/messages` 请求转换成 Responses 请求体发给上游；方式二还会带上 OAuth token 与官方客户端身份访问 ChatGPT 的 Codex 服务。
+4. 上游返回后，路由再把 Responses 的 JSON/SSE 转回 Claude Code 能理解的 Messages 形态。
+
+![Claude 供应商列表里 GPT 供应商的「需要路由」标记](../images/claude-codex-routing/01-claude-providers-require-routing.png)
+
+## 准备工作
+
+- 已安装并能启动的 CC Switch（3.17.0 及以上，原因见开头的版本说明）。
+- 已安装 Claude Code，并至少运行过一次。
+- 方式一需要：一个兼容 OpenAI Responses API 的服务端点和对应的 API Key，端点地址与模型名以网关文档为准。注意是 **Responses API**，不是 Chat Completions；网关只提供 Chat 格式时也能走通，见第一步「API 格式」处的说明。
+- 方式二需要：一个 ChatGPT Plus/Pro 订阅账号。
+
+## 第一步：添加供应商
+
+### 方式一：第三方 Responses 网关（API Key）
+
+打开 CC Switch，切到顶部的 `Claude Code` 标签，点击右上角加号添加供应商，保持默认的 `自定义配置`，然后填写：
+
+- **供应商名称**：随意，例如 `GPT Gateway`。
+- **API Key**：你的网关 Key。真实 Key 只保存在 CC Switch 里，由本地路由转发时注入。
+- **请求地址**：填网关服务根地址即可，例如 `https://gpt-gateway.example.com`，不要以斜杠结尾，路由会自动把请求打到该网关的 Responses 端点（`/v1/responses`）。网关路径特殊时，打开旁边的 `完整 URL` 开关原样粘贴完整端点。
+
+然后展开 `高级选项`：
+
+- **API 格式**：从默认的 `Anthropic Messages (原生)` 改成 **`OpenAI Responses API (需开启路由)`**。如果网关只提供 Chat Completions 协议，这里改选 `OpenAI Chat Completions (需开启路由)`，其余步骤完全相同。
+- **认证字段**：保持默认的 `ANTHROPIC_AUTH_TOKEN（默认）`，路由会以 `Authorization: Bearer <key>` 发给上游——这正是 OpenAI 兼容网关期望的认证头。除非网关文档明确要求 `x-api-key`，否则不要改成 `ANTHROPIC_API_KEY`，改错的典型表现是 401/403。
+- **模型映射**：把 Claude Code 的模型角色映射到网关认识的真实模型。**至少要填 `默认兜底模型`**（例如 `gpt-5.6`，以网关文档为准）——留空时未匹配的请求会以原始 Claude 模型名透传给上游而报错，未单独配置的角色则会回落到它。更精细的做法是按行指定：`Sonnet`/`Opus` 填主力模型，`Haiku` 填一个便宜快速的模型（Claude Code 的后台小任务走这一档）。`显示名称` 只影响 `/model` 菜单里的展示，留空则直接显示真实模型名。
+- **声明支持 1M**：模型映射每行的 `1M` 复选框会向 Claude Code 声明该档支持 1M 上下文。仅当网关确实以 100 万 token 及以上的窗口服务该模型时才勾选（例如按 API 规格提供 gpt-5.6 的网关），否则长对话会在上游真实上限处直接报错。
+
+![方式一：高级选项里把 API 格式设为 OpenAI Responses，认证字段保持默认，并映射到上游真实模型](../images/claude-codex-routing/02-responses-provider-form.png)
+
+保存后，卡片上会出现 `需要路由` 标记——这类供应商必须在本地路由运行时才能正常工作。
+
+### 方式二：ChatGPT 订阅（Codex OAuth）
+
+同样在 `Claude Code` 标签点加号，在预设列表里选择带 OpenAI 图标的 **`Codex`** 预设——它出现在 Claude Code 标签下没有选错，这个预设就是为「在 Claude Code 里用 ChatGPT 订阅」准备的：
+
+- **不需要 API Key，也不需要填地址**——请求固定发往 ChatGPT 的 Codex 服务，表单里的地址项无需改动。
+- 点击 **`使用 ChatGPT 登录`**。这是设备码流程：CC Switch 会自动打开浏览器并把验证码复制到剪贴板，在浏览器页面粘贴验证码完成授权即可，期间应用内显示 `等待授权中...`。
+- 登录成功后，`认证状态` 显示已登录账号（邮箱）。支持多账号：可 `添加其他账号`、`设为默认`，或在这个供应商上指定使用某个账号；日常管理也可以走 `设置` → `OAuth 认证中心`。
+- **FAST 模式**：可选开关，开启后请求携带 `service_tier="priority"` 换取更低延迟，但会按更高速率消耗 ChatGPT 配额，默认保持关闭。
+- 模型档位已预填好：`Sonnet`/`Opus` 对应 `gpt-5.6`，`Haiku` 对应 `gpt-5.6-luna`（后台小任务走它，更快更省额度）。
+
+![方式二：Codex 预设的 ChatGPT 登录状态与账号管理](../images/claude-codex-routing/03-codex-oauth-form.png)
+
+登录凭据保存在 `~/.cc-switch/codex_oauth_auth.json`（不是 `~/.codex/`），与 Codex CLI 自己的登录互不影响；token 会在到期前自动刷新。
+
+## 第二步：开启本地路由并接管 Claude Code
+
+进入设置里的 `路由` 页面，展开 `本地路由`，完成两个开关：
+
+1. 打开 `路由总开关`，启动本地服务（首次开启会弹出说明确认框）。默认地址是 `127.0.0.1:15721`。
+2. 在 `路由启用` 中打开 `Claude Code`。只想让 Claude Code 走路由的话，其余应用保持关闭。
+
+接管后，CC Switch 会把 Claude Code 的 live 配置指向本机路由，认证项只有占位符；方式一的网关 Key 和方式二的 OAuth token 都由本地路由在转发时注入。
+
+> **注意**：live 配置是 Claude Code 进程启动时读取的。首次开启接管（或关闭接管恢复直连）后，如果 Claude Code 正在运行，请重开一个终端会话。之后在路由模式下切换供应商就是热切换，无需再重启。
+
+## 第三步：切换供应商并验证
+
+回到 Claude Code 供应商列表，点击目标供应商的 `启用`。如果路由没有在运行，CC Switch 会提示「此供应商使用 OpenAI Responses 接口格式，需要路由服务才能正常使用，请先启动路由」——这个提示不会拦截切换，但路由未开时请求必然失败，回到第二步打开即可。
+
+进入 Claude Code 后可以逐级验证：
+
+- 新开会话，用 `/model` 查看模型菜单：各档显示的是模型映射里的显示名称（方式二默认即 `gpt-5.6`、`gpt-5.6-luna`）。界面个别位置仍可能出现 Claude 系的模型字样——那是路由接管使用的内部角色别名，属正常现象，以 `/model` 菜单和用量看板为准。
+- 发一个小问题，观察设置 → 路由页面的「当前 Provider」变成你的供应商、「总请求数」开始增长。
+- 用量看板里，这些请求会按上游真实模型显示：映射到 `gpt-5.6` 的档位解析为 Sol 档、显示为 `GPT-5.6 Sol`，`gpt-5.6-luna` 显示为 `GPT-5.6 Luna`，可按供应商筛选核对 token 用量。
+- 方式二的供应商卡片还会显示订阅额度：5 小时与 7 天窗口的利用率和重置倒计时，数据来自 ChatGPT 账号本身，与官方 Codex 客户端共用同一份额度。
+
+## 能力边界与已知限制
+
+- **提示缓存自动生效**：路由会为每个会话注入稳定的 `prompt_cache_key`，配合 OpenAI 侧的自动前缀缓存，长对话不会每轮全价重发，无需任何配置。
+- **思考折算为 reasoning effort**：Claude Code 的思考开关与思考等级会被折算成 GPT 的 `reasoning.effort`（low/medium/high）；GPT 的推理内容以加密形态跨轮完整回放，多轮推理连贯性不受转换影响。方式二同时以无痕模式（`store:false`）访问，不在 OpenAI 服务端留存会话。
+- **工具与多模态完整转换**：多轮工具调用、图片与 PDF 输入都被完整转换。
+- **上下文按 200K 窗口管理**：Claude Code 对路由供应商按默认 200K 窗口做自动压缩。上游实际窗口更大时（如 ChatGPT Codex 服务的 gpt-5.6 为 372K），超出 200K 的部分当前不会被用到——压缩会提前触发，保守但安全。想突破 200K，目前唯一的开关是模型映射里的 `1M` 复选框（严格声明 1M），仅限方式一且上游真按 1M 及以上服务该模型时使用；方式二的上游上限是 372K、够不到 1M，勾选反而会让长对话在上游真实上限处报错，请维持默认。
+- **输出上限**：方式二的输出上限由 ChatGPT 服务端控制（Claude Code 请求里的 `max_tokens` 不会下发）；方式一则原样透传 Claude Code 的 `max_tokens`，无需配置。
+- **联网搜索不可用**：Claude Code 的 WebSearch 依赖 Anthropic 服务端执行，GPT 上游无法承接，涉及联网搜索的任务建议切回 Claude 系供应商。本地执行的 WebFetch 不受影响。
+- **用量看板金额是参考值**：token 计数准确，但美元金额是按公开 API 价折算的估算——方式二订阅流量按 GPT-5.6 公开价折算，方式一的第三方网关按各自费率计费，两者都可能与真实扣费不符，仅供对比。方式二的额度消耗以供应商卡片上的窗口利用率为准。
+
+## 常见问题
+
+**上游返回 401 或 403（方式一）**
+
+先确认高级选项里的 `认证字段` 是默认的 `ANTHROPIC_AUTH_TOKEN（默认）`——改成 `ANTHROPIC_API_KEY` 会以 `x-api-key` 发送，绝大多数 OpenAI 兼容网关不接受。再确认 Key 本身有效、有余额。
+
+**请求 `gpt-5.6-luna` 等新模型报 404 Model not found（方式二）**
+
+升级到 CC Switch 3.17.0 及以上。旧版本的客户端身份未对齐官方 Codex 客户端，ChatGPT 服务端会把新模型解析到不存在的引擎。
+
+**切换后没生效，或 `/model` 菜单还是旧名字**
+
+模型菜单和路由地址都是 Claude Code 启动时读取的：首次开启接管后必须重开终端会话；供应商之间切换虽然是热切换，但菜单里的显示名称要新会话才刷新。
+
+**Claude Code 报「Codex OAuth 认证失败」或卡片显示「会话已过期」（方式二）**
+
+登录凭据已失效。回到供应商表单或 `设置` → `OAuth 认证中心`，重新走一遍 `使用 ChatGPT 登录` 即可；无需运行任何命令行操作。
+
+**对话进行到一半就自动压缩了**
+
+见「能力边界」：路由供应商按 200K 窗口管理，压缩阈值随之提前，属预期行为。
+
+**想恢复官方 Claude 用法**
+
+切回官方供应商，或在路由页面关闭 `Claude Code` 的路由开关——CC Switch 会恢复接管前的 live 配置，官方登录凭据全程不受影响。恢复后同样需要重开终端会话。
+
+**FAST 模式要不要开（方式二）**
+
+默认关闭即可。只有当你对延迟特别敏感、且愿意接受配额更快消耗时再打开；如果 ChatGPT 服务端拒绝该参数，关掉开关即可恢复。
+
+## 合规提示
+
+方式二把 ChatGPT 订阅额度用在官方 Codex 客户端之外，这并不是灰色玩法：OpenAI Codex 负责人 Thibault Sottiaux（@thsottiaux）就公开演示并鼓励过把 Claude Code（他戏称的「orange crab」）指向 GPT-5.6 Sol 使用——用的正是「本地代理 + 模型别名」，和本文方式二属于同一类做法。作为 Codex 这条产品线的负责人，他主动鼓励大家在竞品客户端里用自家模型，可见用订阅在 Claude Code 里跑 GPT 系模型，是官方乐见并鼓励尝试的用法。
+
+两点实务提醒仍值得留意：一是这部分流量与官方 Codex 客户端合并计入同一份订阅额度，重度使用会更快触顶；二是 CC Switch 认证中心出于稳妥保留了合规提示（「在 Claude Code 中使用您的其他订阅，请注意合规风险。」），是否符合你账号所适用的条款可自行留意。方式一使用第三方网关时，请另行阅读目标网关关于计费、合规与数据留存的条款。
+
+## 参考链接
+
+- [CC Switch 用户手册：添加供应商（含 Codex OAuth 反向代理与 API 格式）](../user-manual/zh/2-providers/2.1-add.md)
+- [CC Switch 用户手册：代理服务](../user-manual/zh/4-proxy/4.1-service.md)
+- [CC Switch 用户手册：应用路由](../user-manual/zh/4-proxy/4.2-routing.md)
+- [CC Switch v3.17.0 发布说明](../release-notes/v3.17.0-zh.md)
+- 反方向攻略：[在 Codex 中使用 Claude 模型](./codex-claude-routing-guide-zh.md)
@@ -0,0 +1,129 @@
+# Using Claude Models in Codex with CC Switch
+
+> Applies to CC Switch 3.17.0 and later (the Anthropic Messages upstream was introduced in 3.17.0). This guide is based on the repository documentation and code, and uses a Claude-family relay gateway as the example. Screenshots are generated from the current frontend UI with de-identified sample data to avoid exposing a real API key.
+
+## Why local routing is needed
+
+The newer Codex CLI targets the OpenAI Responses API, while the various Claude-family relay gateways and internal enterprise gateways expose the Anthropic Messages protocol — that is, `/v1/messages`. These two protocols use completely different request bodies, streaming events, and response structures, so putting such a gateway's endpoint directly into Codex configuration can only result in a request to `/responses` coming back 404.
+
+This feature targets the scenario where all you have is a `/v1/messages` endpoint: you have a key for some Claude-family relay gateway and want to run Claude-family models with Codex's interaction style; or your company has banned the Claude Code client for compliance reasons and kept only an approved Claude-family gateway — the model itself is available, and all that's missing is a permitted client, which Codex can now fill.
+
+CC Switch's approach is to keep Codex always talking to the local route and still sending Responses API requests; once the route detects that the active provider is Anthropic-format, it converts the request into Anthropic Messages for the upstream, then converts the response back into the Responses shape it returns to Codex.
+
+![Needs routing marker in the Codex provider list](../images/codex-claude-routing/01-codex-providers-require-routing.png)
+
+The chain has four main steps:
+
+1. When Codex is taken over, the local configuration is written as `http://127.0.0.1:15721/v1`, and `wire_api = "responses"` is forcibly kept in place.
+2. The provider's `anthropic` upstream format tells the route that the real upstream speaks the Anthropic Messages protocol.
+3. The route rewrites `/responses` to `/v1/messages` and converts the Responses request body into an Anthropic request body.
+4. After the upstream responds, the route converts the Anthropic JSON or SSE back into the Responses JSON/SSE that Codex understands — reasoning content, tool calls, and images are all within the conversion scope.
+
+## Prerequisites
+
+Prepare these three things first:
+
+- CC Switch installed and able to start (3.17.0 or later).
+- Codex CLI installed and run at least once, so the `~/.codex/` directory structure exists.
+- An API key that can reach an Anthropic Messages protocol endpoint (`/v1/messages`) — from some Claude-family relay gateway, or an internal enterprise Claude gateway; follow the gateway's documentation for its endpoint and auth method. Note: some providers restrict their Claude API to Claude Code only, so such a key may error out when used through Codex — if you're unsure, check with your provider first.
+
+The Codex tab currently has no built-in Anthropic preset, so the steps below use the `Custom Configuration` path — just four or five fields from start to finish.
+
+## Step 1: Add a Codex provider
+
+Open CC Switch, switch to the top-level `Codex` tab, click the plus button in the upper-right corner to add a provider, keep the default `Custom Configuration`, then fill in:
+
+- **Provider Name**: anything you like, e.g. `Claude Gateway`.
+- **API Key**: your gateway key. The real key is stored only in CC Switch and injected by the local route when forwarding, so it never enters Codex's live config.
+- **API Request URL**: just the gateway's service root, e.g. `https://claude-gateway.example.com`. It works with or without a trailing `/v1` — the route sends requests to `/v1/messages` automatically; don't assemble `/v1/messages` yourself (if your gateway documentation gives you a complete messages URL, you can turn on the `Full URL` toggle next to it and paste it verbatim). The yellow hint below the address bar, "compatible with OpenAI Response format", is generic copy written for the direct Responses scenario; when you choose the Anthropic format, just fill it in as this guide describes.
+- **Default Model**: enter a Claude model id the gateway recognizes, e.g. `claude-sonnet-5`; follow the model names in the gateway's documentation.
+
+Then expand `Advanced Options` and change `Upstream Format` from the default `Responses (native)` to **`Anthropic Messages (routing required)`**.
+
+![Codex provider form for a Claude gateway](../images/codex-claude-routing/02-claude-codex-provider-form.png)
+
+After selecting Anthropic Messages, three supporting fields appear below:
+
+![Advanced options for the Anthropic upstream](../images/codex-claude-routing/03-anthropic-advanced-options.png)
+
+- **Auth field**: determines which header carries the API key to the upstream; only one of the two is sent — choose per your gateway's documentation.
+  - `ANTHROPIC_AUTH_TOKEN (Authorization)`: sends `Authorization: Bearer <key>`. This is the default, and most Claude-family relay gateways use it.
+  - `ANTHROPIC_API_KEY (x-api-key)`: sends `x-api-key: <key>`. Some gateways that follow Anthropic's native header convention require this. Picking the wrong one usually shows up as 401 / 403.
+- **Emulate Claude Code client**: off by default. Turn it on only when the gateway or its upstream restricts usage to "Claude Code only"; when enabled, it spoofs the User-Agent, `anthropic-beta`, and `x-app` headers and injects the Claude Code identity as the first line of the system prompt. Ordinary gateways don't need it; if you're still rejected after enabling it, see "FAQ".
+- **Max output tokens**: the Anthropic protocol's `max_tokens` is required, and when a Codex request carries no output ceiling the route falls back to a conservative 8192, which may truncate long answers or deep reasoning (showing up as an incomplete reply, `stop_reason=max_tokens`). If you hit truncation, raise this to the model's real ceiling here — but don't exceed it, or the upstream will 400 outright.
+
+The `Model Mapping` in the same area is optional: add model ids like `claude-opus-4-8`, `claude-sonnet-5`, and `claude-haiku-4-5-20251001` (use the names your upstream recognizes) one per row, and CC Switch generates a model catalog so Codex's `/model` menu can list them; you can also leave it empty, in which case Codex just requests the default model.
+
+After you save the provider, a `Needs Routing` marker appears on the card — providers like this only work while local routing is running.
+
+## Step 2: Enable local routing and take over Codex
+
+Go to the `Routing` page in Settings, expand `Local Routing`, and complete two toggles:
+
+1. Turn on the `Routing Master Switch` to start the local service (the first time you enable it, an explanatory confirmation dialog appears). The default address is `127.0.0.1:15721`.
+2. Turn on `Codex` under `Routing Enabled`. If you only want Codex to use routing, you can leave Claude and Gemini off.
+
+![Enabling Codex takeover on the local routing page](../images/codex-claude-routing/04-local-route-codex-takeover.png)
+
+After takeover, CC Switch points Codex's live config at the local route (`base_url = http://127.0.0.1:15721/v1`), with only a placeholder in `auth.json`. The real Claude key stays in the CC Switch provider config and is injected by the local route on forward, using the auth field you selected.
+
+## Step 3: Switch providers and restart Codex
+
+Return to the Codex provider list and click `Enable` on the Claude provider. If routing isn't running, CC Switch shows "This provider uses Anthropic Messages API format, requires the routing service to work properly. Start routing first." — just go back to Step 2 and turn it on.
+
+After switching, restart the current Codex terminal session: `config.toml` and the model catalog are read when the Codex process starts, and a running process isn't guaranteed to hot-load them.
+
+Inside Codex you can verify step by step:
+
+- If you configured model mapping, use `/model` to check whether the Claude models now appear in the menu; without a mapping, Codex just uses the default model.
+- Send a small question and watch the "Current Provider" on the Settings → Routing page change from "Waiting for first request..." to your Claude provider, with "Total Requests" starting to climb.
+- In the usage dashboard, these requests show their model names faithfully as `claude-*`, and you can filter by provider to reconcile token usage.
+
+## Capabilities and known limitations
+
+- **Prompt caching is automatic**: the conversion bridge injects standard 5-minute prompt-cache markers (system prompt, tool definitions, and conversation history) per Anthropic's convention, so long conversations don't resend everything at full price each turn — no configuration needed.
+- **Reasoning and tools are lossless**: extended thinking content round-trips across the bridge intact, and multi-turn tool calls, image inputs, and PDF inputs are all fully converted.
+- **Supports the `[1m]` long-context marker**: when the default model or a model id in the mapping ends with `[1m]` (e.g. `claude-sonnet-5[1m]`), the route strips the marker and automatically adds the corresponding 1M-context beta header, provided the gateway supports that capability.
+- **Web search is unavailable**: in Anthropic upstream mode, Codex's built-in `web_search` is deliberately disabled — the conversion layer can't translate it for the Anthropic endpoint, and disabling it avoids presenting the model with a tool that's guaranteed to fail.
+- **Truncation is reported faithfully**: when the upstream stops at the output ceiling or the stream is cut off, Codex sees "incomplete" rather than a disguised success, making it easy to notice and raise the max output tokens.
+
+## FAQ
+
+**The upstream returns 401 or 403**
+
+Nine times out of ten the auth field doesn't match what the gateway wants: switch between `ANTHROPIC_AUTH_TOKEN (Authorization)` and `ANTHROPIC_API_KEY (x-api-key)` per your gateway's documentation and try again (most gateways use the default Bearer). Also confirm the key itself is valid and has balance.
+
+**Codex reports 404 or cannot find `/responses`**
+
+Usually Codex routing takeover isn't enabled, or you manually wrote the gateway's address directly into Codex — an Anthropic-protocol upstream has no `/responses` endpoint, so that always 404s. Check whether the current provider's `base_url` in `~/.codex/config.toml` points to `http://127.0.0.1:15721/v1`.
+
+**The upstream returns 404 (routing already enabled)**
+
+Check the API Request URL: it should be the gateway's service root, not an address carrying another protocol's path such as `/chat/completions`. When the gateway path is unusual, use the `Full URL` toggle to paste the complete messages endpoint directly.
+
+**Replies often get cut off mid-way**
+
+This is the default 8192 output ceiling showing up. Raise it in `Max output tokens` under the provider form's Advanced Options (don't exceed the model's/gateway's real ceiling), save, and retry.
+
+**`/model` doesn't show the Claude models**
+
+Confirm you've added entries to the model mapping, then restart Codex after saving the provider — the model catalog isn't hot-loaded by a running process. When the default model isn't in the mapping, the menu won't list it, but a direct request still works.
+
+**Web search doesn't work**
+
+By design; see "Capabilities and known limitations". For tasks that need web search, switch back to a Responses/Chat-format provider.
+
+**An error says usage is restricted to Claude Code**
+
+Some providers restrict their Claude API to the Claude Code client, so it gets rejected when going through this guide's chain via Codex. Try turning on the `Emulate Claude Code client` toggle in Advanced Options; if it still errors after that, the restriction is enforced on the provider's side — check with your provider whether your key can be used outside Claude Code. Keep this toggle off for ordinary gateways.
+
+## Compliance note
+
+Before using this in the "company bans the client but keeps only the gateway" scenario, it's worth confirming that doing so complies with your organization's specific policy — whether what's banned is a specific client or a manner of use differs from one place to the next. When using a third-party relay gateway, read the target gateway's terms on billing, compliance, and data retention.
+
+## References
+
+- [CC Switch User Manual: Proxy Service](../user-manual/en/4-proxy/4.1-service.md)
+- [CC Switch User Manual: App Routing](../user-manual/en/4-proxy/4.2-routing.md)
+- [CC Switch v3.17.0 Release Notes](../release-notes/v3.17.0-en.md)
+- This feature comes from community contribution [#5071](https://github.com/farion1231/cc-switch/pull/5071); thanks @yeeyzy.
@@ -0,0 +1,129 @@
+# CC Switch を使って Codex で Claude モデルを利用する
+
+> 対象バージョン: CC Switch 3.17.0 以降（「Anthropic Messages 上流」は 3.17.0 から導入）。本記事はリポジトリ内のドキュメントとコードをもとに整理し、Claude 系中継ゲートウェイを例に説明します。スクリーンショットは現在のフロントエンド UI から、実際の API Key が漏れないよう匿名化したサンプルデータで生成しています。
+
+## ローカルルーティングが必要な理由
+
+新しい Codex CLI は OpenAI Responses API を前提にしています。一方で各種 Claude 系中継ゲートウェイや企業内部ゲートウェイが公開しているのは Anthropic Messages プロトコル、つまり `/v1/messages` です。この 2 つのプロトコルは、リクエストボディ、ストリーミングイベント、レスポンス構造がまったく異なります。この種のゲートウェイのエンドポイントをそのまま Codex 設定に入れても、`/responses` へのリクエストが 404 になるだけです。
+
+この機能は「手元にあるのが `/v1/messages` エンドポイントだけ」という場面のためのものです。ある Claude 系中継ゲートウェイの Key を持っていて、Codex の操作感で Claude 系モデルを使いたい。あるいは会社がコンプライアンス方針で Claude Code クライアントを禁止し、承認済みの Claude 系ゲートウェイだけを残している——モデル自体は利用できるのに、許可されたクライアントがないだけです。その空白を Codex で埋められます。
+
+CC Switch では、Codex が常にローカルルートへ接続し、Responses API のままリクエストを送るようにします。ルートは現在のプロバイダーが Anthropic 形式だと判定すると、リクエストを Anthropic Messages に変換して上流へ送り、最後にレスポンスを Responses 形式へ戻して Codex に返します。
+
+![Codex プロバイダー一覧の「ルーティングが必要」マーク](../images/codex-claude-routing/01-codex-providers-require-routing.png)
+
+この経路は主に 4 つのステップに分かれます：
+
+1. Codex を引き継ぐと、ローカル設定は `http://127.0.0.1:15721/v1` に書き換えられ、`wire_api = "responses"` が強制的に維持されます。
+2. プロバイダーの上流フォーマット `anthropic` が、実際の上流は Anthropic Messages プロトコルだとルートに伝えます。
+3. ルートは `/responses` を `/v1/messages` に書き換え、Responses のリクエストボディを Anthropic のリクエストボディへ変換します。
+4. 上流から返ってきた後、ルートは Anthropic の JSON または SSE を Codex が理解できる Responses JSON/SSE へ変換して返します——推論内容、ツール呼び出し、画像もすべて変換対象です。
+
+## 事前準備
+
+先に次の 3 つを用意してください：
+
+- インストール済みで起動できる CC Switch（3.17.0 以降）。
+- インストール済みの Codex CLI。少なくとも 1 回は実行し、`~/.codex/` のディレクトリ構造が存在していること。
+- Anthropic Messages プロトコルのエンドポイント（`/v1/messages`）へアクセスできる API Key——ある Claude 系中継ゲートウェイ、または企業内部の Claude ゲートウェイのもの。エンドポイントと認証方式はゲートウェイのドキュメントに従ってください。注意：一部のプロバイダーは Claude API を Claude Code 内でのみ利用できるよう制限しており、この種の Key を Codex で使うとエラーになることがあります。判断がつかない場合は、先にプロバイダーへ問い合わせてください。
+
+Codex タブには現時点で Anthropic の内蔵プリセットがないため、以下では「カスタム設定」の手順で進めます。入力する項目は全体でも 4〜5 個です。
+
+## Step 1: Codex プロバイダーを追加する
+
+CC Switch を開き、上部の `Codex` タブへ切り替え、右上のプラスボタンからプロバイダーを追加します。デフォルトの `カスタム設定` のまま、次の項目を入力します：
+
+- **プロバイダー名**: 任意です。たとえば `Claude Gateway`。
+- **API Key**: あなたのゲートウェイの Key。実際の Key は CC Switch 内にのみ保存され、ローカルルートが転送時に注入するため、Codex の live 設定には入りません。
+- **API エンドポイント**: ゲートウェイのルートアドレスを入力すれば十分です。たとえば `https://claude-gateway.example.com`。`/v1` は付けても付けなくても正しく処理され、ルートが自動的に `/v1/messages` へリクエストを送ります。自分で `/v1/messages` を組み立てないでください（ゲートウェイのドキュメントが完全な messages URL を指定している場合は、隣の `フル URL` スイッチをオンにしてそのまま貼り付けても構いません）。アドレス欄の下に表示される「OpenAI Response 互換」という黄色のヒントは Responses 直結向けの汎用文言です。Anthropic フォーマットを選ぶ場合は本記事のとおりに入力してください。
+- **デフォルトモデル**: ゲートウェイが認識する Claude モデル ID を入力します。たとえば `claude-sonnet-5`。ゲートウェイのドキュメントにあるモデル名に従ってください。
+
+続いて `高級オプション` を展開し、`上流フォーマット` をデフォルトの `Responses（ネイティブ）` から **`Anthropic Messages（ルーティング必須）`** に変更します。
+
+![Claude ゲートウェイの Codex プロバイダーフォーム](../images/codex-claude-routing/02-claude-codex-provider-form.png)
+
+Anthropic Messages を選ぶと、下に 3 つの関連フィールドが追加で表示されます：
+
+![Anthropic 上流の高級オプション](../images/codex-claude-routing/03-anthropic-advanced-options.png)
+
+- **認証フィールド**: API Key をどのヘッダーで上流へ送るかを決めます。送信されるのはどちらか一方のみで、ゲートウェイのドキュメントに従って選びます。
+  - `ANTHROPIC_AUTH_TOKEN（Authorization）`: `Authorization: Bearer <key>` を送信します。デフォルト値で、多くの Claude 系中継ゲートウェイがこの方式を使います。
+  - `ANTHROPIC_API_KEY（x-api-key）`: `x-api-key: <key>` を送信します。Anthropic ネイティブのヘッダー規約を踏襲する一部のゲートウェイはこちらを要求します。選択を誤ると、通常 401 / 403 という形で現れます。
+- **Claude Code クライアントを模倣**: デフォルトはオフです。ゲートウェイ（またはその上流）が「Claude Code からのみ利用可能」と制限している場合にのみオンにします。オンにすると User-Agent・`anthropic-beta`・`x-app` ヘッダーを偽装し、システムプロンプトの先頭行に Claude Code のアイデンティティを注入します。通常のゲートウェイでは不要です。オンにしても拒否される場合の対処は「よくある質問」を参照してください。
+- **最大出力トークン**: Anthropic プロトコルの `max_tokens` は必須項目です。Codex のリクエストが出力上限を含まない場合、ルートは保守的に 8192 で補います。長い回答や深い思考では切り詰められることがあります（回答が不完全になる、`stop_reason=max_tokens` になる、といった形で現れます）。切り詰められたら、ここでモデルの実際の上限に合わせて引き上げてください。ただし超えないように——超えると上流が直接 400 を返します。
+
+同じエリアの `モデルマッピング` は任意です。`claude-opus-4-8`、`claude-sonnet-5`、`claude-haiku-4-5-20251001` のようなモデル ID（上流が認識する名前に従ってください）を 1 行ずつ追加すると、CC Switch がモデルカタログを生成し、Codex の `/model` メニューに一覧表示できるようになります。入力しなくても利用でき、その場合 Codex はデフォルトモデルを直接リクエストします。
+
+プロバイダーを保存すると、カードに `ルーティングが必要` のマークが表示されます——この種のプロバイダーは、ローカルルーティングが実行中でなければ正しく動作しません。
+
+## Step 2: ローカルルーティングを有効にして Codex をルーティングする
+
+設定の `ルーティング` ページに入り、`ローカルルーティング` を展開して、2 つのスイッチを設定します：
+
+1. `ルーティング総スイッチ` をオンにしてローカルサービスを起動します（初回起動時は説明の確認ダイアログが表示されます）。デフォルトアドレスは `127.0.0.1:15721` です。
+2. `ルーティング有効` で `Codex` をオンにします。Codex だけをルーティングしたい場合は、Claude と Gemini はオフのままで構いません。
+
+![ローカルルーティング画面で Codex のルーティングを有効化](../images/codex-claude-routing/04-local-route-codex-takeover.png)
+
+引き継ぎ後、CC Switch は Codex の live 設定をローカルルートへ向け（`base_url = http://127.0.0.1:15721/v1`）、`auth.json` にはプレースホルダーだけが入ります。実際の Claude Key は CC Switch のプロバイダー設定内に残り、ローカルルートが転送時に、あなたが選んだ認証フィールドに従って注入します。
+
+## Step 3: プロバイダーを切り替えて Codex を再起動する
+
+Codex プロバイダー一覧に戻り、Claude プロバイダーの `有効化` をクリックします。ルーティングが実行されていない場合、CC Switch は「このプロバイダーは Anthropic Messages API フォーマットを使用しており、ルーティングサービスが必要です。先にルーティングを起動してください」と表示します——Step 2 に戻ってオンにすれば解決します。
+
+切り替え後は、現在の Codex ターミナルセッションを再起動することをおすすめします。`config.toml` とモデルカタログは Codex プロセスの起動時に読み込まれるため、実行中のプロセスがホットロードするとは限りません。
+
+Codex に入ったら、段階的に確認できます：
+
+- モデルマッピングを設定している場合は、`/model` で Claude モデルがメニューに表示されているか確認します。マッピングを設定していない場合、Codex はデフォルトモデルを直接使います。
+- 小さな質問を 1 つ送り、設定 → ルーティングページの「現在のプロバイダー」が「最初のリクエスト待ち」からあなたの Claude プロバイダーに変わり、「総リクエスト数」が増え始めるのを確認します。
+- 使用量ダッシュボードでは、これらのリクエストのモデル名が `claude-*` としてそのまま表示され、プロバイダーで絞り込んで token 使用量を照合できます。
+
+## 機能の範囲と既知の制限
+
+- **プロンプトキャッシュが自動で有効**: 変換ブリッジは Anthropic 標準に従って 5 分のプロンプトキャッシュマーカー（システムプロンプト、ツール定義、対話履歴）を注入します。長い対話でも毎回全額で再送されることはなく、設定は不要です。
+- **推論とツールを無損失で往復**: extended thinking の内容はブリッジをまたいで往復しても保持され、複数ターンのツール呼び出し、画像、PDF 入力も完全に変換されます。
+- **`[1m]` 長コンテキストマーカーに対応**: デフォルトモデルやモデルマッピングのモデル ID が `[1m]` で終わる場合（例：`claude-sonnet-5[1m]`）、ルートはマーカーを取り除き、対応する 1M コンテキストの beta ヘッダーを自動で補います。ただし、ゲートウェイがその機能に対応していることが前提です。
+- **Web 検索は利用不可**: Anthropic 上流モードでは Codex の内蔵 `web_search` が意図的に無効化されます——変換層が Anthropic エンドポイントへ翻訳できないためで、必ず失敗するツールをモデルに提示しないための措置です。
+- **切り詰めをそのまま報告**: 上流が出力上限で止まったりストリームが切断されたりすると、Codex は偽装された成功ではなく「未完了」を受け取ります。これにより気づきやすくなり、最大出力トークンを引き上げる判断ができます。
+
+## よくある質問
+
+**上流が 401 または 403 を返す**
+
+ほとんどの場合、認証フィールドがゲートウェイの要求と一致していません。`ANTHROPIC_AUTH_TOKEN（Authorization）` と `ANTHROPIC_API_KEY（x-api-key）` を、ゲートウェイのドキュメントに従って切り替えて再試行してください（多くのゲートウェイはデフォルトの Bearer です）。あわせて、Key 自体が有効で残高があることも確認してください。
+
+**Codex が 404 を返す、または `/responses` が見つからない**
+
+多くの場合、Codex のルーティング引き継ぎが有効になっていないか、ゲートウェイのエンドポイントを手動で Codex に直接書いています——Anthropic プロトコルの上流には `/responses` エンドポイントが存在しないため、必ず 404 になります。`~/.codex/config.toml` の現在の provider の `base_url` が `http://127.0.0.1:15721/v1` を指しているか確認してください。
+
+**上流が 404 を返す（ルーティングは有効）**
+
+API エンドポイントを確認してください。ゲートウェイのルートアドレスであるべきで、`/chat/completions` のような別プロトコルのパスが付いたアドレスではいけません。ゲートウェイのパスが特殊な場合は、`フル URL` スイッチを使って完全な messages エンドポイントをそのまま貼り付けてください。
+
+**回答が途中で切り詰められることが多い**
+
+これはデフォルトの 8192 出力上限の現れです。プロバイダーフォームの高級オプションにある `最大出力トークン` で引き上げ（モデル / ゲートウェイの実際の上限を超えないように）、保存してから再試行してください。
+
+**`/model` に Claude モデルが表示されない**
+
+モデルマッピングにエントリが追加されていることを確認し、プロバイダーを保存してから Codex を再起動してください——モデルカタログは実行中のプロセスにはホットロードされません。デフォルトモデルがマッピングに含まれていない場合、メニューには表示されませんが、直接リクエストは有効です。
+
+**Web 検索が使えない**
+
+仕様どおりです。「機能の範囲と既知の制限」を参照してください。Web 検索が必要なタスクは、Responses / Chat フォーマットのプロバイダーへ切り替えることをおすすめします。
+
+**Claude Code でしか使えないというエラーが出る**
+
+一部のプロバイダーは、その Claude API を Claude Code クライアント内でのみ利用できるよう制限しており、本ガイドの経路で Codex から使うと拒否されます。高級オプションの `Claude Code クライアントを模倣` スイッチをオンにして試すことはできますが、それでもエラーになる場合、制限はプロバイダーのサーバー側にあります。その Key を Claude Code 以外で使えるかどうか、プロバイダーへ問い合わせて確認してください。通常のゲートウェイでは、このスイッチはオフのままにしてください。
+
+## コンプライアンスに関する注意
+
+「会社がクライアントを禁止し、ゲートウェイだけを残している」という場面で使う前に、この使い方が所属組織の具体的な方針に沿っているかを確認することをおすすめします——禁止されているのが特定のクライアントなのか、それともある種の利用方法なのかは、組織によって解釈が異なります。サードパーティ中継ゲートウェイを使う場合は、対象ゲートウェイの課金・コンプライアンス・データ保持に関する規約を必ずお読みください。
+
+## 参考リンク
+
+- [CC Switch ユーザーマニュアル: プロキシサービス](../user-manual/ja/4-proxy/4.1-service.md)
+- [CC Switch ユーザーマニュアル: アプリケーションルーティング](../user-manual/ja/4-proxy/4.2-routing.md)
+- [CC Switch v3.17.0 リリースノート](../release-notes/v3.17.0-ja.md)
+- この機能はコミュニティからの貢献 [#5071](https://github.com/farion1231/cc-switch/pull/5071) によるものです。@yeeyzy に感謝します。
@@ -0,0 +1,129 @@
+# 通过 CC Switch 在 Codex 中使用 Claude 模型
+
+> 适用版本：CC Switch 3.17.0 及以上（「Anthropic Messages 上游」自 3.17.0 引入）。本文根据仓库内文档与代码整理，以 Claude 系中转网关为例演示。截图来自当前前端界面，使用去敏示例数据生成，避免泄露真实 API Key。
+
+## 为什么需要本地路由
+
+新版 Codex CLI 面向的是 OpenAI Responses API，而各类 Claude 系中转网关、企业内部网关暴露的是 Anthropic Messages 协议，也就是 `/v1/messages`。这两种协议的请求体、流式事件和返回结构完全不同，把这类网关的接口地址直接填进 Codex 配置里，结果只能是请求 `/responses` 返回 404。
+
+这个功能面向的就是「手里只有 `/v1/messages` 端点」的场景：你有某个 Claude 系中转网关的 Key，想用 Codex 的交互习惯跑 Claude 系列模型；或者公司出于合规策略禁用了 Claude Code 客户端、只保留了经批准的 Claude 系网关——模型本身可用，缺的只是一个被允许的客户端，现在 Codex 可以补上这个位置。
+
+CC Switch 的做法是让 Codex 始终连本机路由，仍以 Responses API 发送请求；路由识别当前供应商是 Anthropic 格式后，把请求转换成 Anthropic Messages 发给上游，再把响应转换回 Responses 形态返回给 Codex。
+
+![Codex 供应商列表里的需要路由标记](../images/codex-claude-routing/01-codex-providers-require-routing.png)
+
+这条链路主要分成四步：
+
+1. Codex 接管时，本地配置会被写成 `http://127.0.0.1:15721/v1`，并强制保持 `wire_api = "responses"`。
+2. 供应商的上游格式 `anthropic` 会告诉路由：真实上游说的是 Anthropic Messages 协议。
+3. 路由把 `/responses` 改写到 `/v1/messages`，并把 Responses 请求体转换成 Anthropic 请求体。
+4. 上游返回后，路由再把 Anthropic 的 JSON 或 SSE 转回 Codex 能理解的 Responses JSON/SSE——推理内容、工具调用、图片都在转换范围内。
+
+## 准备工作
+
+你需要先准备好三样东西：
+
+- 已安装并能启动的 CC Switch（3.17.0 及以上）。
+- 已安装 Codex CLI，并至少运行过一次，让 `~/.codex/` 目录结构存在。
+- 一个能访问 Anthropic Messages 协议端点（`/v1/messages`）的 API Key——来自某个 Claude 系中转网关，或企业内部的 Claude 网关；端点地址和认证方式以网关文档为准。注意：部分供应商会限制其 Claude API 只能在 Claude Code 中使用，这类 Key 走 Codex 可能会报错，拿不准就先咨询供应商。
+
+Codex 页签目前没有 Anthropic 内置预设，下面走「自定义配置」路径，全程也就四五个字段。
+
+## 第一步：添加 Codex 供应商
+
+打开 CC Switch，切到顶部的 `Codex` 标签，点击右上角的加号添加供应商，保持默认的 `自定义配置`，然后填写：
+
+- **供应商名称**：随意，例如 `Claude Gateway`。
+- **API Key**：你的网关 Key。真实 Key 只保存在 CC Switch 里，由本地路由转发时注入，不会进入 Codex 的 live 配置。
+- **API 请求地址**：填网关服务根地址即可，例如 `https://claude-gateway.example.com`。带不带 `/v1` 都能被正确处理，路由会自动把请求打到 `/v1/messages`；不要自己拼 `/v1/messages`（如果网关文档给的就是完整 messages URL，打开旁边的 `完整 URL` 开关原样粘贴也可以）。地址栏下方那句「兼容 OpenAI Response 格式」的黄色提示是为 Responses 直连场景写的通用文案，选 Anthropic 格式时按本文填写即可。
+- **默认模型**：填网关认识的 Claude 模型 id，例如 `claude-sonnet-5`，以网关文档给出的模型名为准。
+
+然后展开 `高级选项`，把 `上游格式` 从默认的 `Responses（原生）` 改成 **`Anthropic Messages（需开启路由）`**。
+
+![Claude 网关的 Codex 供应商表单](../images/codex-claude-routing/02-claude-codex-provider-form.png)
+
+选中 Anthropic Messages 后，下方会多出三个配套字段：
+
+![Anthropic 上游的高级选项](../images/codex-claude-routing/03-anthropic-advanced-options.png)
+
+- **认证字段**：决定 API Key 以哪个请求头发给上游，两者只发其一，按网关文档选择。
+  - `ANTHROPIC_AUTH_TOKEN（Authorization）`：发 `Authorization: Bearer <key>`，是默认值，多数 Claude 系中转网关用这种。
+  - `ANTHROPIC_API_KEY（x-api-key）`：发 `x-api-key: <key>`，部分沿用 Anthropic 原生请求头约定的网关要求这种。选错通常表现为 401 / 403。
+- **模拟 Claude Code 客户端**：默认关闭。仅当网关或其上游限制「只能通过 Claude Code 使用」时才打开，开启后会伪装 User-Agent、`anthropic-beta`、`x-app` 请求头，并在系统提示首行注入 Claude Code 身份。普通网关不需要开；开启后仍被拒的处理见「常见问题」。
+- **最大输出 tokens**：Anthropic 协议的 `max_tokens` 是必填项，而 Codex 请求未携带输出上限时，路由按保守的 8192 兜底，长回答或深度思考可能被截断（表现为回复不完整、`stop_reason=max_tokens`）。遇到截断就在这里按模型真实上限调高，但不要超过——超了上游会直接 400。
+
+同区的 `模型映射` 是可选项：把 `claude-opus-4-8`、`claude-sonnet-5`、`claude-haiku-4-5-20251001` 这类模型 id（以你上游认识的名字为准）逐行加进去，CC Switch 会生成模型目录让 Codex 的 `/model` 菜单能列出它们；不填也能用，Codex 会直接请求默认模型。
+
+保存供应商后，卡片上会出现 `需要路由` 标记——这类供应商必须在本地路由运行时才能正常工作。
+
+## 第二步：开启本地路由并接管 Codex
+
+进入设置里的 `路由` 页面，展开 `本地路由`，完成两个开关：
+
+1. 打开 `路由总开关`，启动本地服务（首次开启会弹出一个说明确认框）。默认地址是 `127.0.0.1:15721`。
+2. 在 `路由启用` 中打开 `Codex`。如果只想让 Codex 走路由，可以保持 Claude、Gemini 关闭。
+
+![本地路由页面中启用 Codex 接管](../images/codex-claude-routing/04-local-route-codex-takeover.png)
+
+接管后，CC Switch 会把 Codex 的 live 配置指向本机路由（`base_url = http://127.0.0.1:15721/v1`），`auth.json` 里只有占位符。真实 Claude Key 仍保存在 CC Switch 的供应商配置里，由本地路由在转发时按你选的认证字段注入。
+
+## 第三步：切换供应商并重启 Codex
+
+回到 Codex 供应商列表，点击 Claude 供应商的 `启用`。如果路由没有在运行，CC Switch 会提示「此供应商使用 Anthropic Messages 接口格式，需要路由服务才能正常使用，请先启动路由」——回到第二步打开即可。
+
+切换后建议重启当前 Codex 终端会话：`config.toml` 和模型目录是 Codex 进程启动时读取的，运行中的进程不保证热加载。
+
+进入 Codex 后可以逐级验证：
+
+- 配置了模型映射的话，用 `/model` 查看 Claude 模型是否已出现在菜单里；没配映射时 Codex 直接用默认模型。
+- 发一个小问题，观察设置 → 路由页面的「当前 Provider」从「等待首次请求」变成你的 Claude 供应商、「总请求数」开始增长。
+- 用量看板里，这些请求的模型名会如实显示为 `claude-*`，可按供应商筛选核对 token 用量。
+
+## 能力边界与已知限制
+
+- **提示缓存自动生效**：转换桥会按 Anthropic 标准注入 5 分钟提示缓存标记（系统提示、工具定义与对话历史），长对话不会每轮全价重发，无需任何配置。
+- **推理与工具无损**：extended thinking 内容跨桥往返保留，多轮工具调用、图片与 PDF 输入都被完整转换。
+- **支持 `[1m]` 长上下文标记**：默认模型或模型映射里的模型 id 以 `[1m]` 结尾（如 `claude-sonnet-5[1m]`）时，路由会剥掉标记并自动补发对应的 1M 上下文 beta 头，前提是网关支持该能力。
+- **联网搜索不可用**：Anthropic 上游模式下 Codex 的内置 `web_search` 会被主动禁用——转换层无法把它翻译给 Anthropic 端点，禁用是为了不给模型呈现一个必然失败的工具。
+- **截断如实上报**：上游停在输出上限或流被掐断时，Codex 会看到「未完成」而不是被伪装的成功，方便你察觉并调高最大输出 tokens。
+
+## 常见问题
+
+**上游返回 401 或 403**
+
+十有八九是认证字段与网关要求不符：在 `ANTHROPIC_AUTH_TOKEN（Authorization）` 与 `ANTHROPIC_API_KEY（x-api-key）` 之间按网关文档换一个再试（多数网关用默认的 Bearer）。另外确认 Key 本身有效、有余额。
+
+**Codex 报 404 或找不到 `/responses`**
+
+通常是没有开启 Codex 路由接管，或者你手动把网关的地址直接写给了 Codex——Anthropic 协议的上游没有 `/responses` 端点，这样一定 404。检查 `~/.codex/config.toml` 里当前 provider 的 `base_url` 是否指向 `http://127.0.0.1:15721/v1`。
+
+**上游返回 404（路由已开启）**
+
+检查 API 请求地址：应该是网关的服务根地址，而不是带 `/chat/completions` 之类其它协议路径的地址。网关路径特殊时，用 `完整 URL` 开关直接粘贴完整的 messages 端点。
+
+**回复经常中途截断**
+
+这是默认 8192 输出上限的表现。在供应商表单高级选项的 `最大输出 tokens` 里调高（不要超过模型/网关真实上限），保存后重试。
+
+**`/model` 看不到 Claude 模型**
+
+确认模型映射里已添加条目，保存供应商后重启 Codex——模型目录不会被运行中的进程热加载。默认模型不在映射里时菜单不会列出它，但直接请求仍然有效。
+
+**联网搜索用不了**
+
+设计如此，见「能力边界」。需要联网搜索的任务建议切回 Responses/Chat 格式的供应商。
+
+**报错提示只能在 Claude Code 中使用**
+
+部分供应商会限制其 Claude API 只能在 Claude Code 客户端中使用，经 Codex 走本攻略的链路时会被拒绝。可以尝试打开高级选项里的 `模拟 Claude Code 客户端` 开关；若开启后仍然报错，说明限制在供应商服务端，请咨询供应商确认你的 Key 能否在 Claude Code 之外使用。普通网关请保持该开关关闭。
+
+## 合规提示
+
+在「公司禁客户端、只留网关」的场景下使用前，建议确认这样做符合你所在组织的具体政策——被禁的是特定客户端还是某种使用方式，各家口径不同。使用第三方中转网关时，请阅读目标网关关于计费、合规与数据留存的条款。
+
+## 参考链接
+
+- [CC Switch 用户手册：代理服务](../user-manual/zh/4-proxy/4.1-service.md)
+- [CC Switch 用户手册：应用路由](../user-manual/zh/4-proxy/4.2-routing.md)
+- [CC Switch v3.17.0 发布说明](../release-notes/v3.17.0-zh.md)
+- 功能来自社区贡献 [#5071](https://github.com/farion1231/cc-switch/pull/5071)，感谢 @yeeyzy
@@ -0,0 +1,101 @@
+# Using DeepSeek-Style Chat APIs in Codex: CC Switch Local Routing Guide
+
+> Applies to CC Switch 3.16.0 and nearby versions. This guide is based on the repository documentation and code, and uses DeepSeek as an example of an OpenAI Chat Completions-compatible API. Screenshots are generated from the current frontend UI with de-identified sample data to avoid exposing a real API key or account balance.
+
+## Why local routing is needed
+
+The newer Codex CLI targets the OpenAI Responses API, while DeepSeek, Kimi, MiniMax, SiliconFlow, and many other providers expose the OpenAI Chat Completions shape, usually `/chat/completions`. These two protocols use different request bodies, streaming events, and response structures. If you put a Chat endpoint directly into Codex configuration, common results include an incorrect model list, 404/400 requests, or streaming responses that Codex cannot parse correctly.
+
+CC Switch solves this by making Codex always talk to a local route and continue sending Responses API requests. The route detects whether the active provider is Chat-format, rewrites the request into Chat Completions for the upstream provider, and finally converts the Chat response back into the Responses shape that Codex understands.
+
+![Needs routing marker in the Codex provider list](../images/codex-deepseek-routing/01-codex-providers-require-routing.png)
+
+The chain has four main steps:
+
+1. When Codex routing is enabled, the local configuration is written as `http://127.0.0.1:15721/v1`, while `wire_api = "responses"` is kept in place.
+2. The provider's `meta.apiFormat = "openai_chat"` tells the route that the real upstream is Chat Completions.
+3. The route rewrites `/responses` or `/v1/responses` to `/chat/completions`, and converts the Responses request body into a Chat request body.
+4. After the upstream responds, the route converts the Chat JSON or SSE stream back into Responses JSON/SSE.
+
+## Prerequisites
+
+Prepare these three things first:
+
+- CC Switch installed and able to start.
+- Codex CLI installed and run at least once, so the `~/.codex/config.toml` directory structure exists.
+- An API key from DeepSeek or another Chat Completions provider.
+
+DeepSeek's official documentation currently lists the OpenAI-compatible base URL as `https://api.deepseek.com` (other providers often use a base URL with a `/v1` suffix), and the Chat API path as `/chat/completions`. CC Switch's DeepSeek preset already contains these details, so prefer the preset and do not manually assemble the endpoint path.
+
+## Step 1: Add a Codex provider
+
+Open CC Switch, switch to the top-level `Codex` tab, and click the plus button in the upper-right corner to add a provider.
+
+Choose the built-in `DeepSeek` preset. You only need to do two things:
+
+- Enter your DeepSeek API key.
+- Save the provider.
+
+![Local routing mapping in the DeepSeek Codex provider form](../images/codex-deepseek-routing/02-deepseek-codex-routing-form.png)
+
+The preset already includes DeepSeek's request base URL, default model, model menu, thinking/reasoning parameters, and automatically enables `Needs Local Routing`. You can adjust the default model or model display names if needed; the protocol conversion is handled by the routing layer.
+
+## Step 2: Enable local routing and route Codex
+
+Go to the `Routing` page in Settings, expand `Local Routing`, and complete two toggles:
+
+1. Turn on the main routing switch to start the local service. The default address is `127.0.0.1:15721`.
+2. Turn on `Codex` under `Routing Enabled`. If you only want Codex to use local routing, you can leave Claude and Gemini off.
+
+![Enabling Codex routing on the local routing page](../images/codex-deepseek-routing/03-local-route-codex-takeover.png)
+
+After routing is enabled, CC Switch points Codex's live configuration to the local route and manages authentication with a placeholder. The real DeepSeek key stays in the CC Switch provider configuration and is injected by the local route while forwarding requests, so you do not need to expose the key in Codex's live configuration.
+
+## Step 3: Switch providers and restart Codex
+
+Return to the Codex provider list and click `Enable` on the DeepSeek provider. If you see the `Needs Routing` marker, that provider must be used while routing is running; when the route is not started, CC Switch shows a prompt saying the routing service is required.
+
+After switching, restart the current Codex terminal session. This is recommended because:
+
+- The Codex process may already have read the old `config.toml`.
+- After `model_catalog_json` is generated, the `/model` menu usually needs a fresh process before it refreshes.
+
+Inside Codex, use `/model` to check whether the current model comes from the DeepSeek preset, such as `DeepSeek V4 Flash`. The Codex app currently does not support multi-model selection, so it defaults to the first configured model. Then send a small test prompt and confirm that the request count increases in the routing panel, or that a Codex request appears in usage/request logs.
+
+## How to handle other Chat providers
+
+DeepSeek, Kimi, MiniMax, SiliconFlow, and other common Chat-format providers already have presets in CC Switch, so use presets first. Only choose custom configuration for providers that are not covered by presets; in that case, fill in the API key, base URL, and models according to the provider's documentation, and set `API Format` to `OpenAI Chat Completions (requires routing)`.
+
+If the upstream provider directly supports the OpenAI Responses API, you do not need to enable `Needs Local Routing`; CC Switch can connect through Responses directly without Chat conversion.
+
+## FAQ
+
+**Codex reports 404 or cannot find `/responses`**
+
+Usually Codex routing is not enabled, or the upstream Chat base URL was written directly into Codex manually. Check whether `~/.codex/config.toml` points to `http://127.0.0.1:15721/v1`.
+
+**DeepSeek upstream reports 404**
+
+If you are using the built-in DeepSeek preset, first confirm that the active provider really comes from the preset and that Codex routing is enabled. Only custom providers require extra base URL checks: the base URL should be the service root, not the full endpoint path with `/chat/completions`.
+
+**`/model` does not show DeepSeek models**
+
+Restart Codex after saving the provider. CC Switch generates `cc-switch-model-catalog.json` and writes its path to `model_catalog_json`, but a running Codex process may not hot-load the model catalog.
+The Codex app currently does not support multi-model selection, so it uses the first configured model by default.
+
+**Routing is enabled, but requests still go to the wrong provider**
+
+Confirm that all three states match: the current provider under the Codex tab is DeepSeek; the local routing service is running; and the Codex toggle is enabled under `Routing Enabled`.
+
+**Can I use an official OpenAI Codex account through local routing?**
+
+Not recommended. CC Switch blocks switching to official providers while local routing takeover is enabled, because accessing official APIs through a proxy may create account risk. Routing is mainly intended for third-party, aggregator, or protocol-conversion scenarios.
+
+## References
+
+- [CC Switch User Manual: Add Provider](../user-manual/en/2-providers/2.1-add.md)
+- [CC Switch User Manual: Proxy Service](../user-manual/en/4-proxy/4.1-service.md)
+- [CC Switch User Manual: App Routing](../user-manual/en/4-proxy/4.2-routing.md)
+- [DeepSeek API Docs: Your First API Call](https://api-docs.deepseek.com/)
+- [DeepSeek API Docs: Create Chat Completion](https://api-docs.deepseek.com/api/create-chat-completion)
+- [DeepSeek API Docs: Multi-round Conversation](https://api-docs.deepseek.com/guides/multi_round_chat)
@@ -0,0 +1,101 @@
+# Codex で DeepSeek などの Chat 形式 API を使う: CC Switch ローカルルーティングガイド
+
+> 対象バージョン: CC Switch 3.16.0 およびその前後のバージョン。本記事はリポジトリ内のドキュメントとコードをもとに整理し、OpenAI Chat Completions 互換 API の例として DeepSeek を使用します。スクリーンショットは現在のフロントエンド UI から、実際の API Key やアカウント残高が漏れないよう匿名化したサンプルデータで生成しています。
+
+## ローカルルーティングが必要な理由
+
+新しい Codex CLI は OpenAI Responses API を前提にしています。一方で DeepSeek、Kimi、MiniMax、SiliconFlow など多くのプロバイダーが実際に公開しているのは OpenAI Chat Completions 形式、つまり `/chat/completions` です。この 2 つのプロトコルは、リクエストボディ、ストリーミングイベント、レスポンス構造が異なります。Chat エンドポイントをそのまま Codex 設定に入れると、モデル一覧が合わない、リクエストが 404/400 になる、ストリーミングレスポンスを Codex が正しく解析できない、といった問題が起きがちです。
+
+CC Switch では、Codex が常にローカルルートへ接続し、Responses API のままリクエストを送るようにします。ルート内部で現在のプロバイダーが Chat 形式かどうかを判定し、必要ならリクエストを Chat Completions に書き換えて上流へ送り、最後に Chat レスポンスを Codex が理解できる Responses 形式へ戻します。
+
+![Codex プロバイダー一覧のローカルルーティング必須マーク](../images/codex-deepseek-routing/01-codex-providers-require-routing.png)
+
+この経路は主に 4 つのステップに分かれます：
+
+1. Codex ルーティングを有効にすると、ローカル設定は `http://127.0.0.1:15721/v1` に書き換えられ、`wire_api = "responses"` は維持されます。
+2. Provider の `meta.apiFormat = "openai_chat"` が、実際の上流は Chat Completions だとルートに伝えます。
+3. ルートは `/responses` または `/v1/responses` を `/chat/completions` に書き換え、Responses のリクエストボディを Chat のリクエストボディへ変換します。
+4. 上流から返ってきた後、ルートは Chat の JSON または SSE ストリームを Responses JSON/SSE へ変換して返します。
+
+## 事前準備
+
+先に次の 3 つを用意してください：
+
+- インストール済みで起動できる CC Switch。
+- インストール済みの Codex CLI。少なくとも 1 回は実行し、`~/.codex/config.toml` のディレクトリ構造が存在していること。
+- DeepSeek または同種の Chat Completions プロバイダーの API Key。
+
+DeepSeek 公式ドキュメントでは、OpenAI 互換 base URL は現在 `https://api.deepseek.com`（他のプロバイダーでは `/v1` 付きの base URL もよくあります）、Chat API のパスは `/chat/completions` と記載されています。CC Switch の DeepSeek プリセットにはこれらの情報がすでに入っているため、まずはプリセットを使い、エンドポイントパスを手で組み立てる必要はありません。
+
+## Step 1: Codex プロバイダーを追加する
+
+CC Switch を開き、上部の `Codex` タブへ切り替え、右上のプラスボタンからプロバイダーを追加します。
+
+内蔵プリセットの `DeepSeek` を選びます。必要なのは次の 2 つだけです：
+
+- DeepSeek API Key を入力する。
+- プロバイダーを保存する。
+
+![DeepSeek Codex プロバイダーフォームのローカルルーティング設定](../images/codex-deepseek-routing/02-deepseek-codex-routing-form.png)
+
+プリセットには DeepSeek のリクエスト先、デフォルトモデル、モデルメニュー、thinking/reasoning パラメータがすでに含まれており、`ローカルルーティングが必要` も自動的に有効になります。必要に応じてデフォルトモデルやモデル表示名を調整できますが、プロトコル変換はルーティング層に任せれば十分です。
+
+## Step 2: ローカルルーティングを有効にして Codex をルーティングする
+
+設定の `ルーティング` ページに入り、`ローカルルーティング` を展開して、次の 2 つのスイッチを設定します：
+
+1. `ルーティング総スイッチ` をオンにしてローカルサービスを起動します。デフォルトアドレスは `127.0.0.1:15721` です。
+2. `ルーティング有効` で `Codex` をオンにします。Codex だけをルーティングしたい場合は、Claude と Gemini はオフのままで構いません。
+
+![ローカルルーティング画面で Codex ルーティングを有効化](../images/codex-deepseek-routing/03-local-route-codex-takeover.png)
+
+ルーティングを有効にすると、CC Switch は Codex の live 設定をローカルルートへ向け、認証はプレースホルダーで管理します。実際の DeepSeek Key は CC Switch の Provider 設定内に残り、ローカルルートが転送時に注入します。そのため、Codex の live 設定に Key を露出させる必要はありません。
+
+## Step 3: プロバイダーを切り替えて Codex を再起動する
+
+Codex プロバイダー一覧に戻り、DeepSeek プロバイダーの `有効化` をクリックします。`ルーティングが必要` の表示が見える場合、そのプロバイダーはルーティング実行中に使う必要があります。ルーティングが起動していない場合、CC Switch は「ルーティングサービスが必要」という趣旨のメッセージを表示します。
+
+切り替え後は、現在の Codex ターミナルセッションを再起動することをおすすめします。理由は次のとおりです：
+
+- Codex プロセスがすでに古い `config.toml` を読み込んでいる可能性があります。
+- `model_catalog_json` の生成後、`/model` メニューの更新には通常、新しいプロセスが必要です。
+
+Codex に入ったら、`/model` で現在のモデルが DeepSeek プリセット由来かどうかを確認します。たとえば `DeepSeek V4 Flash` などです。現在の Codex app は複数モデル選択に対応していないため、設定内の最初のモデルをデフォルトで使用します。その後、小さな質問を 1 つ送って、ルーティングパネルのリクエスト数が増えるか、usage / リクエストログに Codex リクエストが出るかを確認します。
+
+## 他の Chat プロバイダーの場合
+
+DeepSeek、Kimi、MiniMax、SiliconFlow など一般的な Chat 形式プロバイダーは CC Switch にプリセットがあるため、まずはプリセットを使ってください。プリセットにないプロバイダーだけ、カスタム設定を選びます。その場合は相手側のドキュメントに従って API Key、base URL、モデルを入力し、`API 形式` を `OpenAI Chat Completions (ルーティングが必要)` に設定します。
+
+上流が OpenAI Responses API を直接サポートしている場合は、`ローカルルーティングが必要` を有効にする必要はありません。その場合、CC Switch は Responses のまま直結でき、Chat 変換は行いません。
+
+## よくある質問
+
+**Codex が 404 を返す、または `/responses` が見つからない**
+
+多くの場合、Codex ルーティングが有効になっていないか、上流 Chat base URL を手動で Codex に直接書いています。`~/.codex/config.toml` が `http://127.0.0.1:15721/v1` を指しているか確認してください。
+
+**DeepSeek 上流が 404 を返す**
+
+内蔵 DeepSeek プリセットを使っている場合は、まず現在のプロバイダーが本当にプリセット由来であること、そして Codex ルーティングが有効であることを確認してください。カスタムプロバイダーを使っている場合だけ、base URL を追加で確認します。base URL はサービスのルートであり、`/chat/completions` 付きの完全なエンドポイントパスではありません。
+
+**`/model` に DeepSeek モデルが表示されない**
+
+プロバイダーを保存した後、Codex を再起動してください。CC Switch は `cc-switch-model-catalog.json` を生成し、そのパスを `model_catalog_json` に書き込みますが、実行中の Codex プロセスがモデルカタログをホットロードするとは限りません。
+現在の Codex app は複数モデル選択に対応していないため、設定内の最初のモデルをデフォルトで使用します。
+
+**ルーティングを有効にしたのに、リクエストが別のプロバイダーへ行く**
+
+次の 3 つの状態が一致しているか確認してください：Codex タブの現在のプロバイダーが DeepSeek であること、ローカルルーティングサービスが実行中であること、`ルーティング有効` で Codex スイッチがオンであること。
+
+**公式 OpenAI Codex アカウントをローカルルーティング経由で使えますか**
+
+おすすめしません。CC Switch はローカルルーティング有効中、公式プロバイダーへの切り替えをブロックします。プロキシ経由で公式 API にアクセスすると、アカウントリスクが発生する可能性があるためです。ルーティングは主にサードパーティ、集約サービス、またはプロトコル変換のための機能です。
+
+## 参考リンク
+
+- [CC Switch ユーザーマニュアル: プロバイダーの追加](../user-manual/ja/2-providers/2.1-add.md)
+- [CC Switch ユーザーマニュアル: プロキシサービス](../user-manual/ja/4-proxy/4.1-service.md)
+- [CC Switch ユーザーマニュアル: アプリケーションルーティング](../user-manual/ja/4-proxy/4.2-routing.md)
+- [DeepSeek API Docs: Your First API Call](https://api-docs.deepseek.com/)
+- [DeepSeek API Docs: Create Chat Completion](https://api-docs.deepseek.com/api/create-chat-completion)
+- [DeepSeek API Docs: Multi-round Conversation](https://api-docs.deepseek.com/guides/multi_round_chat)
@@ -0,0 +1,101 @@
+# 在 Codex 中用 DeepSeek 这类 Chat 格式 API：CC Switch 本地路由攻略
+
+> 适用版本：CC Switch 3.16.0 及附近版本。本文根据仓库内文档与代码整理，并用 DeepSeek 作为 OpenAI Chat Completions 兼容接口的示例。截图来自当前前端界面，使用去敏示例数据生成，避免泄露真实 API Key 或账户余额。
+
+## 为什么需要本地路由
+
+新版 Codex CLI 面向的是 OpenAI Responses API，而 DeepSeek、Kimi、MiniMax、SiliconFlow 等很多供应商实际暴露的是 OpenAI Chat Completions 形态，也就是 `/chat/completions`。这两种协议的请求体、流式事件和返回结构不同，直接把 Chat 接口填进 Codex 配置里，常见结果就是模型列表不对、请求 404/400，或者流式响应无法被 Codex 正确解析。
+
+CC Switch 的做法是让 Codex 始终连本机路由，仍以 Responses API 发送请求；路由在内部识别当前供应商是否是 Chat 格式，再把请求改写成 Chat Completions 发给上游，最后把 Chat 响应转换回 Responses 形态返回给 Codex。
+
+![Codex 供应商列表里的需要路由标记](../images/codex-deepseek-routing/01-codex-providers-require-routing.png)
+
+这条链路主要分成四步：
+
+1. Codex 接管时，本地配置会被写成 `http://127.0.0.1:15721/v1`，并强制保持 `wire_api = "responses"`。
+2. Provider 的 `meta.apiFormat = "openai_chat"` 会告诉路由：真实上游是 Chat Completions。
+3. 路由把 `/responses` 或 `/v1/responses` 改写到 `/chat/completions`，并把 Responses 请求体转换成 Chat 请求体。
+4. 上游返回后，路由再把 Chat 的 JSON 或 SSE 转回 Codex 能理解的 Responses JSON/SSE。
+
+## 准备工作
+
+你需要先准备好三样东西：
+
+- 已安装并能启动的 CC Switch。
+- 已安装 Codex CLI，并至少运行过一次，让 `~/.codex/config.toml` 目录结构存在。
+- DeepSeek 或同类 Chat Completions 供应商的 API Key。
+
+DeepSeek 官方文档目前写明 OpenAI 兼容 base URL 是 `https://api.deepseek.com`（其他供应商常见的是带 `/v1` 后缀的 base URL），Chat API 路径是 `/chat/completions`；CC Switch 的 DeepSeek 预设已经按这些信息配好，请优先使用预设，不需要手动拼接口路径。
+
+## 第一步：添加 Codex 供应商
+
+打开 CC Switch，切到顶部的 `Codex` 标签，点击右上角的加号添加供应商。
+
+选择内置预设里的 `DeepSeek`，只需要做两件事：
+
+- 填入 DeepSeek API Key。
+- 保存供应商。
+
+![DeepSeek Codex 供应商表单中的本地路由映射](../images/codex-deepseek-routing/02-deepseek-codex-routing-form.png)
+
+预设已经内置 DeepSeek 的请求地址、默认模型、模型菜单、thinking/reasoning 参数，并会自动打开 `需要本地路由映射`。你可以按需调整默认模型或模型显示名；协议转换交给路由层完成即可。
+
+## 第二步：开启本地路由并接管 Codex
+
+进入设置里的 `路由` 页面，展开 `本地路由`，完成两个开关：
+
+1. 打开 `路由总开关`，启动本地服务。默认地址是 `127.0.0.1:15721`。
+2. 在 `路由启用` 中打开 `Codex`。如果只想让 Codex 走路由，可以保持 Claude、Gemini 关闭。
+
+![本地路由页面中启用 Codex 接管](../images/codex-deepseek-routing/03-local-route-codex-takeover.png)
+
+接管后，CC Switch 会把 Codex 的 live 配置指向本机路由，并用占位符管理认证。真实 DeepSeek Key 仍保存在 CC Switch 的 Provider 配置里，由本地路由在转发时注入，不需要你把 Key 暴露给 Codex live 配置。
+
+## 第三步：切换供应商并重启 Codex
+
+回到 Codex 供应商列表，点击 DeepSeek 供应商的 `启用`。如果看到 `需要路由` 标记，说明这个供应商必须在路由运行时使用；没有启动路由时，CC Switch 会弹出“需要路由服务才能正常使用”的提示。
+
+切换后建议重启当前 Codex 终端会话。原因是：
+
+- Codex 进程可能已经读取过旧的 `config.toml`。
+- `model_catalog_json` 生成后，`/model` 菜单通常需要新进程才能刷新。
+
+进入 Codex 后，可以用 `/model` 查看当前模型是否来自 DeepSeek 预设，例如 `DeepSeek V4 Flash`。目前 Codex app 不支持多模型选择时，会默认使用配置里的第一个模型。随后发一个小问题，确认路由面板的请求数增长，或者在用量/请求日志里看到 Codex 请求即可。
+
+## 其它 Chat 供应商怎么处理
+
+DeepSeek、Kimi、MiniMax、SiliconFlow 等常见 Chat 格式供应商在 CC Switch 里已有预设，优先用预设即可。只有预设里没有的供应商，才需要选择自定义配置；这时按对方文档填 API Key、base URL 和模型，并把 `API 格式` 选为 `OpenAI Chat Completions (需开启路由)`。
+
+如果上游直接支持 OpenAI Responses API，就不需要打开 `需要本地路由映射`；这时 CC Switch 可以按 Responses 直连，不做 Chat 转换。
+
+## 常见问题
+
+**Codex 报 404 或找不到 `/responses`**
+
+通常是没有开启 Codex 接管，或者你手动把上游 Chat base URL 直接写给了 Codex。检查 `~/.codex/config.toml` 是否指向 `http://127.0.0.1:15721/v1`。
+
+**DeepSeek 上游报 404**
+
+如果用的是内置 DeepSeek 预设，先确认当前供应商确实来自预设，并且 Codex 路由已启用。只有在使用自定义供应商时，才需要额外检查 base URL：它应该是服务根地址，而不是带 `/chat/completions` 的完整接口路径。
+
+**`/model` 看不到 DeepSeek 模型**
+
+保存供应商后重启 Codex。CC Switch 会生成 `cc-switch-model-catalog.json` 并把路径写入 `model_catalog_json`，但正在运行的 Codex 进程不一定会热加载模型目录。
+目前 Codex app 不支持多模型选择，默认使用配置的第一个模型。
+
+**开了路由但请求仍走错供应商**
+
+确认三处状态一致：Codex 标签下当前供应商是 DeepSeek；本地路由服务正在运行；`路由启用` 里 Codex 开关已打开。
+
+**可以用官方 OpenAI Codex 账号走本地路由吗**
+
+不建议。CC Switch 会在本地路由接管模式下阻止切到官方供应商，因为用代理访问官方 API 可能带来账号风险。路由主要用于第三方、聚合或协议转换场景。
+
+## 参考链接
+
+- [CC Switch 用户手册：添加供应商](../user-manual/zh/2-providers/2.1-add.md)
+- [CC Switch 用户手册：代理服务](../user-manual/zh/4-proxy/4.1-service.md)
+- [CC Switch 用户手册：应用路由](../user-manual/zh/4-proxy/4.2-routing.md)
+- [DeepSeek API 文档：Your First API Call](https://api-docs.deepseek.com/)
+- [DeepSeek API 文档：Create Chat Completion](https://api-docs.deepseek.com/api/create-chat-completion)
+- [DeepSeek API 文档：Multi-round Conversation](https://api-docs.deepseek.com/guides/multi_round_chat)
@@ -0,0 +1,46 @@
+# Can't See Custom Models in the Codex Desktop App? (FAQ)
+
+> Applies to CC Switch v3.16.1 and later. This article explains "why the Codex desktop app can't see custom models" and the available mitigation; for the detailed step-by-step setup with screenshots, see [Keep Codex Remote Control and Official Plugins While Using Third-Party APIs](./codex-official-auth-preservation-guide-en.md).
+
+## Symptom
+
+After you switch Codex to a third-party / custom model in CC Switch (DeepSeek, Kimi, GLM, MiniMax, an aggregator, etc.):
+
+- The model picker in the **Codex desktop app** doesn't show these custom models — often only the official default model remains, and the reasoning level falls back to the official default;
+- but everything works fine in the **command-line `codex`** `/model` menu.
+
+Many users have run into this. Here's why, and what you can do about it.
+
+## Why this happens
+
+This is **not a CC Switch local-config problem and not a CC Switch bug** — it is the **Codex desktop app's (the upstream closed-source client's) own model-gating behavior**.
+
+The Codex desktop app's model picker decides which models to allow based on your **current login identity**: when it can't detect an official ChatGPT / Codex login state, it forces the picker back to the official default model and hides the custom models you configured through `config.toml` (the reasoning level falls back to the official default too). The upstream has marked "exposing custom-provider models in the desktop GUI" as not planned, so CC Switch cannot fully fix this at the desktop-GUI level.
+
+The command-line `codex` `/model` menu and request routing both recognize the custom providers in `config.toml` correctly — **only the desktop GUI picker is constrained by this gating layer**.
+
+## Mitigation: keep the official login
+
+The workaround is to **keep the official login state** so the desktop app's gating allows your custom models through. The key points are below (the full step-by-step setup with screenshots is in the linked guide):
+
+1. Log in once with an official ChatGPT / Codex account in Codex (a Free subscription is enough) to keep the official login state.
+2. In CC Switch, enable `Settings -> General -> Codex App Enhancements -> Keep official login when switching third-party providers` (**off by default**).
+3. Enable local routing and route Codex through it for this third-party provider (required for Chat Completions providers such as DeepSeek / Kimi / MiniMax).
+4. Fully quit and restart Codex.
+
+Once enabled, CC Switch preserves the official login state in `~/.codex/auth.json` when switching to a third-party provider and writes the third-party key into `config.toml`, so the desktop app still recognizes the official login identity, the gating lets your models through, and the custom models you configured reappear in the picker. **The preserved official token is never sent to the third party** — third-party model requests still use the key you configured, forwarded through the local route.
+
+> 📖 Detailed step-by-step setup: [Keep Codex Remote Control and Official Plugins While Using Third-Party APIs](./codex-official-auth-preservation-guide-en.md)
+
+## Still can't see them?
+
+- **Confirm the toggle is on**: this toggle is off by default, and many people overwrite the official login state the first time they switch to a third-party provider, which is exactly why the models disappear — enable it as above.
+- **The official login state expires**: if you haven't used the official login for several days, the picker may go empty again once the token expires — log in to the official account once more to restore it.
+- **Command-line fallback diagnosis**: run `codex debug models` to list the models actually available on the CLI side and confirm the model itself is configured correctly (the CLI is unaffected by this gating).
+- Individual Codex desktop versions may behave slightly differently; this is in the upstream client's domain, and no CC Switch version can fully fix it at the desktop-GUI level.
+
+## References
+
+- [Keep Codex Remote Control and Official Plugins While Using Third-Party APIs](./codex-official-auth-preservation-guide-en.md)
+- [Codex DeepSeek local routing hands-on guide](./codex-deepseek-routing-guide-en.md)
+- [Local Routing](../user-manual/en/4-proxy/4.2-routing.md)
@@ -0,0 +1,47 @@
+# Codex デスクトップアプリでカスタムモデルが見えない？（よくある質問）
+
+> 対象バージョン: CC Switch v3.16.1 以降。本記事は「なぜ Codex デスクトップアプリでカスタムモデルが見えないのか」と、使える緩和策を解説します。図入りの詳細な設定手順は [サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する](./codex-official-auth-preservation-guide-ja.md) を参照してください。
+
+## 現象
+
+CC Switch で Codex をサードパーティ / カスタムモデル（DeepSeek、Kimi、GLM、MiniMax、中継サービスなど）へ切り替えた後：
+
+- **Codex デスクトップアプリ**のモデルセレクタにこれらのカスタムモデルが表示されず、多くの場合は公式の既定モデルだけが残り、思考レベルも公式の既定へ戻ってしまう。
+- 一方で**コマンドライン `codex`** の `/model` ではすべて正常に表示される。
+
+多くのユーザーがこの現象に遭遇しています。以下で原因と対処を解説します。
+
+## なぜこうなるのか
+
+これは **CC Switch のローカル設定の問題でも、CC Switch のバグでもありません**。**Codex デスクトップアプリ（上流のクローズドソースクライアント）自身のモデルゲーティング挙動**です。
+
+Codex デスクトップアプリのモデルセレクタは、あなたの**現在のログイン ID** に応じてどのモデルを通すかを決めます。公式 ChatGPT / Codex のログイン状態を検出できないとき、セレクタを公式の既定モデルへ強制的に戻し、`config.toml` で設定したカスタムモデルを隠します（思考レベルもあわせて公式の既定へ戻ります）。公式は「デスクトップ GUI でカスタムプロバイダーのモデルを公開する」ことを not planned としてマークしているため、CC Switch がデスクトップ GUI のレベルでこれを根本的に修正することはできません。
+
+コマンドライン `codex` の `/model` とリクエストルーティングは `config.toml` 内のカスタムプロバイダーを正常に認識できます。**デスクトップ GUI のセレクタだけがこのゲーティングの制限を受けます**。
+
+## 緩和策: 公式ログインを保持する
+
+対処は**公式ログイン状態を保持する**ことで、デスクトップアプリのゲーティングにあなたのカスタムモデルを通させます。要点は次のとおりです（完全な図入り手順は下のリンク先のガイドを参照してください）：
+
+1. まず Codex で公式 ChatGPT / Codex に一度ログインし（Free サブスクリプションで構いません）、公式ログイン状態を保持する。
+2. CC Switch で `設定 → 一般 → Codex アプリ拡張 → サードパーティ切替時に公式ログインを保持` をオンにする（**デフォルトはオフ**）。
+3. そのサードパーティプロバイダーでローカルルーティングを有効化し、Codex のルーティングをオンにする（DeepSeek / Kimi / MiniMax など Chat Completions プロトコルのプロバイダーでは必須）。
+4. Codex を完全に終了して再起動する。
+
+オンにすると、CC Switch はサードパーティプロバイダーへ切り替える際に `~/.codex/auth.json` 内の公式ログイン状態を保持し、サードパーティの Key を `config.toml` へ書き込みます。これにより、デスクトップアプリは引き続き公式ログイン ID を認識してゲーティングを通すため、設定したカスタムモデルがセレクタに再び表示されます。**保持された公式 Token がサードパーティへ送られることはありません**——サードパーティのモデルリクエストは引き続き、設定した Key でローカルルーティング経由で転送されます。
+
+> 📖 詳細な図入り手順: [サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する](./codex-official-auth-preservation-guide-ja.md)
+
+## それでも見えない場合は
+
+- **スイッチがオンか確認する**: このスイッチはデフォルトでオフです。多くの人は初めてサードパーティへ切り替えたときに公式ログイン状態を上書きしてしまい、その結果見えなくなっています——上記の手順でオンにしてください。
+- **公式ログイン状態は期限切れになる**: 数日間公式ログインを使わないと、Token が失効した後にセレクタが再び空になることがあります——公式に一度ログインし直せば回復します。
+- **コマンドラインでの確認**: `codex debug models` を使うと CLI 側で実際に利用可能なモデルを一覧でき、モデル自体が正しく設定されていることを確認できます（CLI はこのゲーティングの影響を受けません）。
+- 個々の Codex デスクトップ版で挙動が多少異なる場合があります。これは上流クライアントの範疇であり、CC Switch のどのバージョンでもデスクトップ GUI のレベルで根本解決することはできません。
+
+## 参考リンク
+
+- [サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する](./codex-official-auth-preservation-guide-ja.md)
+- [Codex DeepSeek ローカルルーティング実践ガイド](./codex-deepseek-routing-guide-ja.md)
+- [ローカルルーティング](../user-manual/ja/4-proxy/4.2-routing.md)
+</content>
@@ -0,0 +1,46 @@
+# Codex 桌面应用里看不到自定义模型？（常见问题）
+
+> 适用版本：CC Switch v3.16.1 及以上。本文解释「为什么 Codex 桌面应用看不到自定义模型」以及可用的缓解办法；详细的图文配置步骤见 [使用第三方 API 时保留 Codex 远程操作和官方插件](./codex-official-auth-preservation-guide-zh.md)。
+
+## 现象
+
+在 CC Switch 里把 Codex 切换到第三方 / 自定义模型（DeepSeek、Kimi、GLM、MiniMax、中转站等）后：
+
+- **Codex 桌面应用**的模型选择器里看不到这些自定义模型，往往只剩官方默认模型，思考等级也回落到官方默认；
+- 但**命令行 `codex`** 的 `/model` 里一切正常。
+
+很多用户都遇到过这个现象，下面解释原因与办法。
+
+## 为什么会这样
+
+这**不是 CC Switch 的本地配置问题，也不是 CC Switch 的 bug**，而是 **Codex 桌面应用（上游闭源客户端）自身的模型门控行为**。
+
+Codex 桌面应用的模型选择器会按你**当前的登录身份**来决定放行哪些模型：当它检测不到官方 ChatGPT / Codex 登录态时，会把选择器强制回落到官方默认模型，把你通过 `config.toml` 配置的自定义模型藏起来（思考等级也会一并回落到官方默认）。官方已把「在桌面 GUI 里暴露自定义供应商模型」标记为 not planned，因此 CC Switch 无法从桌面 GUI 层面彻底修复它。
+
+命令行 `codex` 的 `/model` 与请求路由都能正常识别 `config.toml` 里的自定义供应商，**唯独桌面 GUI 的选择器受这层门控限制**。
+
+## 怎么缓解：保留官方登录
+
+办法是**保留官方登录态**，让桌面应用的门控放行你的自定义模型。要点如下（完整图文步骤见下方链接的攻略）：
+
+1. 先在 Codex 里登录一次官方 ChatGPT / Codex（Free 订阅即可），保留官方登录态。
+2. 在 CC Switch 开启 `设置 → 通用 → Codex 应用增强 → 切换第三方时保留官方登录`（**默认关闭**）。
+3. 为该第三方供应商开启本地路由并接管 Codex（Chat Completions 协议的供应商如 DeepSeek / Kimi / MiniMax 必须开启）。
+4. 完全退出并重启 Codex。
+
+开启后，CC Switch 在切换第三方供应商时会保留 `~/.codex/auth.json` 里的官方登录态、把第三方 Key 写进 `config.toml`，于是桌面应用仍识别官方登录身份、门控放行，你配置的自定义模型就会重新出现在选择器里。**保留的官方 Token 不会被发往第三方**——第三方模型请求仍用你配置的 Key 经本地路由转发。
+
+> 📖 详细图文步骤：[使用第三方 API 时保留 Codex 远程操作和官方插件](./codex-official-auth-preservation-guide-zh.md)
+
+## 仍然看不到怎么办
+
+- **确认开关已开**：该开关默认关闭，很多人第一次切到第三方就把官方登录态覆盖掉了，所以才看不到——按上面开启即可。
+- **官方登录态会过期**：如果连续几天没用过官方登录，Token 失效后选择器可能又变空——重新登录一次官方即可恢复。
+- **命令行兜底诊断**：用 `codex debug models` 可以列出 CLI 端实际可用的模型，确认模型本身已正确配置（CLI 不受此门控影响）。
+- 个别 Codex 桌面版本的行为可能略有差异；这属于上游客户端范畴，CC Switch 各版本都无法从桌面 GUI 层根治。
+
+## 参考链接
+
+- [使用第三方 API 时保留 Codex 远程操作和官方插件](./codex-official-auth-preservation-guide-zh.md)
+- [Codex DeepSeek 本地路由实战攻略](./codex-deepseek-routing-guide-zh.md)
+- [本地路由](../user-manual/zh/4-proxy/4.2-routing.md)
@@ -0,0 +1,112 @@
+# Using Kimi in Codex: CC Switch Local Routing Guide
+
+> Applies to CC Switch 3.16.5 and nearby versions. This guide is based on the repository documentation and code, and uses Kimi as an example of an OpenAI Chat Completions-compatible API. Screenshots are generated from the current frontend UI with de-identified sample data to avoid exposing a real API key or account balance.
+
+## Why local routing is needed
+
+The newer Codex CLI targets the OpenAI Responses API, while both the Kimi Open Platform and Kimi For Coding expose the OpenAI Chat Completions shape, `/chat/completions`. These two protocols use different request bodies, streaming events, and response structures. If you put a Kimi endpoint directly into Codex configuration, the usual result is a 404 on `/responses`, or streaming responses that Codex cannot parse correctly.
+
+The third-party tools officially supported by Kimi For Coding are Anthropic-compatible coding agents such as Claude Code and Roo Code — Codex is not on the list. To use Kimi inside Codex, you need a protocol conversion layer, and that is exactly what CC Switch Local Routing does.
+
+CC Switch solves this by making Codex always talk to a local route and continue sending Responses API requests. The route detects whether the active provider is Chat-format, rewrites the request into Chat Completions for the upstream provider, and finally converts the Chat response back into the Responses shape that Codex understands.
+
+![Needs routing marker in the Codex provider list](../images/codex-kimi-routing/01-codex-providers-require-routing.png)
+
+The chain has four main steps:
+
+1. When Codex routing is enabled, the local configuration is written as `http://127.0.0.1:15721/v1`, while `wire_api = "responses"` is kept in place.
+2. The provider's `meta.apiFormat = "openai_chat"` tells the route that the real upstream is Chat Completions.
+3. The route rewrites `/responses` or `/v1/responses` to `/chat/completions`, and converts the Responses request body into a Chat request body.
+4. After the upstream responds, the route converts the Chat JSON or SSE stream back into Responses JSON/SSE.
+
+## Prerequisites
+
+Prepare these three things first:
+
+- CC Switch installed and able to start.
+- Codex CLI installed and run at least once, so the `~/.codex/config.toml` directory structure exists.
+- A Kimi API key.
+
+Kimi API keys come from two different places, matching two different built-in presets in CC Switch:
+
+- **Kimi Open Platform** (platform.kimi.com): pay-as-you-go API keys billed by token usage, matching the `Kimi` preset. The OpenAI-compatible base URL is `https://api.moonshot.cn/v1` and the default model is `kimi-k2.7-code`.
+- **Kimi For Coding** (kimi.com/code): a dedicated key generated from the Kimi Code membership benefits, matching the `Kimi For Coding` preset. The base URL is `https://api.kimi.com/coding/v1` and the unified model is `kimi-for-coding`.
+
+Both presets already contain the correct endpoint and model details, so prefer the presets and do not manually assemble the endpoint path.
+
+## Step 1: Add a Codex provider
+
+Open CC Switch, switch to the top-level `Codex` tab, and click the plus button in the upper-right corner to add a provider.
+
+Depending on which kind of key you have, choose the built-in `Kimi` preset (Open Platform, pay-as-you-go) or `Kimi For Coding` preset (membership subscription). You only need to do two things:
+
+- Enter the matching Kimi API key.
+- Save the provider.
+
+![Upstream format in the Kimi Codex provider form](../images/codex-kimi-routing/02-kimi-codex-routing-form.png)
+
+The preset already includes Kimi's request base URL, default model, model menu, thinking/reasoning parameters, and presets `Upstream Format` under `Advanced Options` to `Chat Completions (routing required)`. You can adjust the default model or model display names if needed — for example, the Open Platform preset defaults to `kimi-k2.7-code`, and you can switch to `kimi-k2.7-code-highspeed` following the official documentation. The protocol conversion is handled by the routing layer.
+
+## Step 2: Enable local routing and route Codex
+
+Go to the `Routing` page in Settings, expand `Local Routing`, and complete two toggles:
+
+1. Turn on the main routing switch to start the local service. The default address is `127.0.0.1:15721`.
+2. Turn on `Codex` under `Routing Enabled`. If you only want Codex to use local routing, you can leave Claude and Gemini off.
+
+![Enabling Codex routing on the local routing page](../images/codex-kimi-routing/03-local-route-codex-takeover.png)
+
+After routing is enabled, CC Switch points Codex's live configuration to the local route and manages authentication with a placeholder. The real Kimi key stays in the CC Switch provider configuration and is injected by the local route while forwarding requests, so you do not need to expose the key in Codex's live configuration.
+
+## Step 3: Switch providers and restart Codex
+
+Return to the Codex provider list and click `Enable` on the Kimi provider. If you see the `Needs Routing` marker, that provider must be used while routing is running; when the route is not started, CC Switch shows a prompt saying the routing service is required.
+
+After switching, restart the current Codex terminal session. This is recommended because:
+
+- The Codex process may already have read the old `config.toml`.
+- After `model_catalog_json` is generated, the `/model` menu usually needs a fresh process before it refreshes.
+
+Inside Codex, use `/model` to check whether the current model comes from the Kimi preset, such as `Kimi K2.7 Code` or `Kimi For Coding`. The Codex app currently does not support multi-model selection, so it defaults to the first configured model. Then send a small test prompt and confirm that the request count increases in the routing panel, or that a Codex request appears in usage/request logs.
+
+## How to handle other Chat providers
+
+Kimi, DeepSeek, MiniMax, SiliconFlow, and other common Chat-format providers already have presets in CC Switch, so use presets first. Only choose custom configuration for providers that are not covered by presets; in that case, fill in the API key, base URL, and models according to the provider's documentation, and set `Upstream Format` under `Advanced Options` to `Chat Completions (routing required)`.
+
+If the upstream provider directly supports the OpenAI Responses API, set `Upstream Format` to `Responses`; CC Switch then connects through Responses directly without Chat conversion.
+
+## FAQ
+
+**Codex reports 404 or cannot find `/responses`**
+
+Usually Codex routing is not enabled, or the Kimi Chat base URL was written directly into Codex manually — the Kimi upstream has no `/responses` endpoint, so that always 404s. Check whether `~/.codex/config.toml` points to `http://127.0.0.1:15721/v1`.
+
+**Kimi upstream reports 401 or 403**
+
+First confirm the key matches the preset: Open Platform keys only work with the `Kimi` preset, and Kimi Code membership keys only work with the `Kimi For Coding` preset. The two key families are not interchangeable.
+
+**Kimi upstream reports 404**
+
+If you are using a built-in Kimi preset, first confirm that the active provider really comes from the preset and that Codex routing is enabled. Only custom providers require extra base URL checks: the base URL should be the service root, not the full endpoint path with `/chat/completions`.
+
+**`/model` does not show Kimi models**
+
+Restart Codex after saving the provider. CC Switch generates `cc-switch-model-catalog.json` and writes its path to `model_catalog_json`, but a running Codex process may not hot-load the model catalog.
+The Codex app currently does not support multi-model selection, so it uses the first configured model by default.
+
+**Routing is enabled, but requests still go to the wrong provider**
+
+Confirm that all three states match: the current provider under the Codex tab is Kimi; the local routing service is running; and the Codex toggle is enabled under `Routing Enabled`.
+
+**Can I use an official OpenAI Codex account through local routing?**
+
+Not recommended. CC Switch blocks switching to official providers while local routing takeover is enabled, because accessing official APIs through a proxy may create account risk. Routing is mainly intended for third-party, aggregator, or protocol-conversion scenarios.
+
+## References
+
+- [CC Switch User Manual: Add Provider](../user-manual/en/2-providers/2.1-add.md)
+- [CC Switch User Manual: Proxy Service](../user-manual/en/4-proxy/4.1-service.md)
+- [CC Switch User Manual: App Routing](../user-manual/en/4-proxy/4.2-routing.md)
+- [Kimi Open Platform: Using Kimi K2.7 Code in coding tools](https://platform.kimi.com/docs/guide/agent-support)
+- [Kimi Code Docs: Overview](https://www.kimi.com/code/docs/)
+- [Kimi Code Docs: Using with third-party coding agents](https://www.kimi.com/code/docs/third-party-tools/other-coding-agents.html)
@@ -0,0 +1,112 @@
+# Codex で Kimi を使う: CC Switch ローカルルーティングガイド
+
+> 対象バージョン: CC Switch 3.16.5 およびその前後のバージョン。本記事はリポジトリ内のドキュメントとコードをもとに整理し、OpenAI Chat Completions 互換 API の例として Kimi を使用します。スクリーンショットは現在のフロントエンド UI から、実際の API Key やアカウント残高が漏れないよう匿名化したサンプルデータで生成しています。
+
+## ローカルルーティングが必要な理由
+
+新しい Codex CLI は OpenAI Responses API を前提にしています。一方で Kimi オープンプラットフォームと Kimi For Coding が実際に公開しているのは、いずれも OpenAI Chat Completions 形式、つまり `/chat/completions` です。この 2 つのプロトコルは、リクエストボディ、ストリーミングイベント、レスポンス構造が異なります。Kimi のエンドポイントをそのまま Codex 設定に入れると、`/responses` へのリクエストが 404 になる、ストリーミングレスポンスを Codex が正しく解析できない、といった問題が起きがちです。
+
+Kimi For Coding が公式にサポートするサードパーティツールは、Claude Code や Roo Code など Anthropic 互換のコーディング Agent であり、Codex はリストに含まれていません。Codex で Kimi を使うにはプロトコル変換レイヤーが必要で、それこそが CC Switch のローカルルーティングの役割です。
+
+CC Switch では、Codex が常にローカルルートへ接続し、Responses API のままリクエストを送るようにします。ルート内部で現在のプロバイダーが Chat 形式かどうかを判定し、必要ならリクエストを Chat Completions に書き換えて上流へ送り、最後に Chat レスポンスを Codex が理解できる Responses 形式へ戻します。
+
+![Codex プロバイダー一覧のローカルルーティング必須マーク](../images/codex-kimi-routing/01-codex-providers-require-routing.png)
+
+この経路は主に 4 つのステップに分かれます：
+
+1. Codex ルーティングを有効にすると、ローカル設定は `http://127.0.0.1:15721/v1` に書き換えられ、`wire_api = "responses"` は維持されます。
+2. Provider の `meta.apiFormat = "openai_chat"` が、実際の上流は Chat Completions だとルートに伝えます。
+3. ルートは `/responses` または `/v1/responses` を `/chat/completions` に書き換え、Responses のリクエストボディを Chat のリクエストボディへ変換します。
+4. 上流から返ってきた後、ルートは Chat の JSON または SSE ストリームを Responses JSON/SSE へ変換して返します。
+
+## 事前準備
+
+先に次の 3 つを用意してください：
+
+- インストール済みで起動できる CC Switch。
+- インストール済みの Codex CLI。少なくとも 1 回は実行し、`~/.codex/config.toml` のディレクトリ構造が存在していること。
+- Kimi の API Key。
+
+Kimi の API Key には 2 つの取得元があり、CC Switch の 2 つの内蔵プリセットに対応します：
+
+- **Kimi オープンプラットフォーム**（platform.kimi.com）: トークン使用量に応じた従量課金の API Key。プリセット `Kimi` に対応し、OpenAI 互換 base URL は `https://api.moonshot.cn/v1`、デフォルトモデルは `kimi-k2.7-code` です。
+- **Kimi For Coding**（kimi.com/code）: Kimi メンバーシップの Kimi Code 特典から生成する専用 Key。プリセット `Kimi For Coding` に対応し、base URL は `https://api.kimi.com/coding/v1`、モデルは `kimi-for-coding` に統一されています。
+
+どちらのプリセットにも公式情報に基づくエンドポイントとモデルがすでに設定されているため、まずはプリセットを使い、エンドポイントパスを手で組み立てる必要はありません。
+
+## Step 1: Codex プロバイダーを追加する
+
+CC Switch を開き、上部の `Codex` タブへ切り替え、右上のプラスボタンからプロバイダーを追加します。
+
+手元の Key の種類に応じて、内蔵プリセットの `Kimi`（オープンプラットフォーム・従量課金）または `Kimi For Coding`（メンバーシップ）を選びます。必要なのは次の 2 つだけです：
+
+- 対応する Kimi API Key を入力する。
+- プロバイダーを保存する。
+
+![Kimi Codex プロバイダーフォームの上流フォーマット設定](../images/codex-kimi-routing/02-kimi-codex-routing-form.png)
+
+プリセットには Kimi のリクエスト先、デフォルトモデル、モデルメニュー、thinking/reasoning パラメータがすでに含まれており、`高級オプション` の `上流フォーマット` も `Chat Completions（ルーティング必須）` にプリセットされています。必要に応じてデフォルトモデルやモデル表示名を調整できます。たとえばオープンプラットフォームのプリセットはデフォルトが `kimi-k2.7-code` で、公式ドキュメントに従って `kimi-k2.7-code-highspeed` に変更することもできます。プロトコル変換はルーティング層に任せれば十分です。
+
+## Step 2: ローカルルーティングを有効にして Codex をルーティングする
+
+設定の `ルーティング` ページに入り、`ローカルルーティング` を展開して、次の 2 つのスイッチを設定します：
+
+1. `ルーティング総スイッチ` をオンにしてローカルサービスを起動します。デフォルトアドレスは `127.0.0.1:15721` です。
+2. `ルーティング有効` で `Codex` をオンにします。Codex だけをルーティングしたい場合は、Claude と Gemini はオフのままで構いません。
+
+![ローカルルーティング画面で Codex ルーティングを有効化](../images/codex-kimi-routing/03-local-route-codex-takeover.png)
+
+ルーティングを有効にすると、CC Switch は Codex の live 設定をローカルルートへ向け、認証はプレースホルダーで管理します。実際の Kimi Key は CC Switch の Provider 設定内に残り、ローカルルートが転送時に注入します。そのため、Codex の live 設定に Key を露出させる必要はありません。
+
+## Step 3: プロバイダーを切り替えて Codex を再起動する
+
+Codex プロバイダー一覧に戻り、Kimi プロバイダーの `有効化` をクリックします。`ルーティングが必要` の表示が見える場合、そのプロバイダーはルーティング実行中に使う必要があります。ルーティングが起動していない場合、CC Switch は「ルーティングサービスが必要」という趣旨のメッセージを表示します。
+
+切り替え後は、現在の Codex ターミナルセッションを再起動することをおすすめします。理由は次のとおりです：
+
+- Codex プロセスがすでに古い `config.toml` を読み込んでいる可能性があります。
+- `model_catalog_json` の生成後、`/model` メニューの更新には通常、新しいプロセスが必要です。
+
+Codex に入ったら、`/model` で現在のモデルが Kimi プリセット由来かどうかを確認します。たとえば `Kimi K2.7 Code` や `Kimi For Coding` などです。現在の Codex app は複数モデル選択に対応していないため、設定内の最初のモデルをデフォルトで使用します。その後、小さな質問を 1 つ送って、ルーティングパネルのリクエスト数が増えるか、usage / リクエストログに Codex リクエストが出るかを確認します。
+
+## 他の Chat プロバイダーの場合
+
+Kimi、DeepSeek、MiniMax、SiliconFlow など一般的な Chat 形式プロバイダーは CC Switch にプリセットがあるため、まずはプリセットを使ってください。プリセットにないプロバイダーだけ、カスタム設定を選びます。その場合は相手側のドキュメントに従って API Key、base URL、モデルを入力し、`高級オプション` の `上流フォーマット` を `Chat Completions（ルーティング必須）` に設定します。
+
+上流が OpenAI Responses API を直接サポートしている場合は、`上流フォーマット` を `Responses` にすれば、CC Switch は Responses のまま直結でき、Chat 変換は行いません。
+
+## よくある質問
+
+**Codex が 404 を返す、または `/responses` が見つからない**
+
+多くの場合、Codex ルーティングが有効になっていないか、Kimi の Chat base URL を手動で Codex に直接書いています。Kimi の上流には `/responses` エンドポイントが存在しないため、必ず 404 になります。`~/.codex/config.toml` が `http://127.0.0.1:15721/v1` を指しているか確認してください。
+
+**Kimi 上流が 401 または 403 を返す**
+
+まず Key とプリセットの組み合わせを確認してください。オープンプラットフォームの Key はプリセット `Kimi` 専用、Kimi Code 特典の Key はプリセット `Kimi For Coding` 専用で、2 種類の Key は相互に使えません。
+
+**Kimi 上流が 404 を返す**
+
+内蔵 Kimi プリセットを使っている場合は、まず現在のプロバイダーが本当にプリセット由来であること、そして Codex ルーティングが有効であることを確認してください。カスタムプロバイダーを使っている場合だけ、base URL を追加で確認します。base URL はサービスのルートであり、`/chat/completions` 付きの完全なエンドポイントパスではありません。
+
+**`/model` に Kimi モデルが表示されない**
+
+プロバイダーを保存した後、Codex を再起動してください。CC Switch は `cc-switch-model-catalog.json` を生成し、そのパスを `model_catalog_json` に書き込みますが、実行中の Codex プロセスがモデルカタログをホットロードするとは限りません。
+現在の Codex app は複数モデル選択に対応していないため、設定内の最初のモデルをデフォルトで使用します。
+
+**ルーティングを有効にしたのに、リクエストが別のプロバイダーへ行く**
+
+次の 3 つの状態が一致しているか確認してください：Codex タブの現在のプロバイダーが Kimi であること、ローカルルーティングサービスが実行中であること、`ルーティング有効` で Codex スイッチがオンであること。
+
+**公式 OpenAI Codex アカウントをローカルルーティング経由で使えますか**
+
+おすすめしません。CC Switch はローカルルーティング有効中、公式プロバイダーへの切り替えをブロックします。プロキシ経由で公式 API にアクセスすると、アカウントリスクが発生する可能性があるためです。ルーティングは主にサードパーティ、集約サービス、またはプロトコル変換のための機能です。
+
+## 参考リンク
+
+- [CC Switch ユーザーマニュアル: プロバイダーの追加](../user-manual/ja/2-providers/2.1-add.md)
+- [CC Switch ユーザーマニュアル: プロキシサービス](../user-manual/ja/4-proxy/4.1-service.md)
+- [CC Switch ユーザーマニュアル: アプリケーションルーティング](../user-manual/ja/4-proxy/4.2-routing.md)
+- [Kimi オープンプラットフォーム: コーディングツールで Kimi K2.7 Code を使う](https://platform.kimi.com/docs/guide/agent-support)
+- [Kimi Code ドキュメント: 概要](https://www.kimi.com/code/docs/)
+- [Kimi Code ドキュメント: サードパーティ Coding Agent での利用](https://www.kimi.com/code/docs/third-party-tools/other-coding-agents.html)
@@ -0,0 +1,112 @@
+# 在 Codex 中用 Kimi：CC Switch 本地路由攻略
+
+> 适用版本：CC Switch 3.16.5 及附近版本。本文根据仓库内文档与代码整理，并用 Kimi 作为 OpenAI Chat Completions 兼容接口的示例。截图来自当前前端界面，使用去敏示例数据生成，避免泄露真实 API Key 或账户余额。
+
+## 为什么需要本地路由
+
+新版 Codex CLI 面向的是 OpenAI Responses API，而 Kimi 开放平台和 Kimi For Coding 实际暴露的都是 OpenAI Chat Completions 形态，也就是 `/chat/completions`。这两种协议的请求体、流式事件和返回结构不同，直接把 Kimi 的接口地址填进 Codex 配置里，常见结果就是请求 `/responses` 返回 404，或者流式响应无法被 Codex 正确解析。
+
+Kimi For Coding 官方目前支持的第三方工具是 Claude Code、Roo Code 这类兼容 Anthropic 协议的编程 Agent，并没有覆盖 Codex。所以想在 Codex 里用 Kimi，需要一层协议转换——这正是 CC Switch 本地路由做的事。
+
+CC Switch 的做法是让 Codex 始终连本机路由，仍以 Responses API 发送请求；路由在内部识别当前供应商是否是 Chat 格式，再把请求改写成 Chat Completions 发给上游，最后把 Chat 响应转换回 Responses 形态返回给 Codex。
+
+![Codex 供应商列表里的需要路由标记](../images/codex-kimi-routing/01-codex-providers-require-routing.png)
+
+这条链路主要分成四步：
+
+1. Codex 接管时，本地配置会被写成 `http://127.0.0.1:15721/v1`，并强制保持 `wire_api = "responses"`。
+2. Provider 的 `meta.apiFormat = "openai_chat"` 会告诉路由：真实上游是 Chat Completions。
+3. 路由把 `/responses` 或 `/v1/responses` 改写到 `/chat/completions`，并把 Responses 请求体转换成 Chat 请求体。
+4. 上游返回后，路由再把 Chat 的 JSON 或 SSE 转回 Codex 能理解的 Responses JSON/SSE。
+
+## 准备工作
+
+你需要先准备好三样东西：
+
+- 已安装并能启动的 CC Switch。
+- 已安装 Codex CLI，并至少运行过一次，让 `~/.codex/config.toml` 目录结构存在。
+- 一个 Kimi API Key。
+
+Kimi 的 API Key 有两个来源，对应 CC Switch 里两个不同的内置预设：
+
+- **Kimi 开放平台**（platform.kimi.com）：按 token 用量计费的 API Key，对应预设 `Kimi`，OpenAI 兼容 base URL 是 `https://api.moonshot.cn/v1`，默认模型 `kimi-k2.7-code`。
+- **Kimi For Coding**（kimi.com/code）：Kimi 会员 Kimi Code 权益生成的专用 Key，对应预设 `Kimi For Coding`，base URL 是 `https://api.kimi.com/coding/v1`，模型统一为 `kimi-for-coding`。
+
+两个预设都已经按官方信息配好接口地址和模型，请优先使用预设，不需要手动拼接口路径。
+
+## 第一步：添加 Codex 供应商
+
+打开 CC Switch，切到顶部的 `Codex` 标签，点击右上角的加号添加供应商。
+
+按你手里 Key 的类型，在内置预设里选择 `Kimi`（开放平台按量计费）或 `Kimi For Coding`（会员订阅），然后只需要做两件事：
+
+- 填入对应的 Kimi API Key。
+- 保存供应商。
+
+![Kimi Codex 供应商表单中的上游格式设置](../images/codex-kimi-routing/02-kimi-codex-routing-form.png)
+
+预设已经内置 Kimi 的请求地址、默认模型、模型菜单、thinking/reasoning 参数，并把 `高级选项` 里的 `上游格式` 预设为 `Chat Completions（需开启路由）`。你可以按需调整默认模型或模型显示名——例如开放平台预设默认是 `kimi-k2.7-code`，也可以按官方文档换成 `kimi-k2.7-code-highspeed`；协议转换交给路由层完成即可。
+
+## 第二步：开启本地路由并接管 Codex
+
+进入设置里的 `路由` 页面，展开 `本地路由`，完成两个开关：
+
+1. 打开 `路由总开关`，启动本地服务。默认地址是 `127.0.0.1:15721`。
+2. 在 `路由启用` 中打开 `Codex`。如果只想让 Codex 走路由，可以保持 Claude、Gemini 关闭。
+
+![本地路由页面中启用 Codex 接管](../images/codex-kimi-routing/03-local-route-codex-takeover.png)
+
+接管后，CC Switch 会把 Codex 的 live 配置指向本机路由，并用占位符管理认证。真实 Kimi Key 仍保存在 CC Switch 的 Provider 配置里，由本地路由在转发时注入，不需要你把 Key 暴露给 Codex live 配置。
+
+## 第三步：切换供应商并重启 Codex
+
+回到 Codex 供应商列表，点击 Kimi 供应商的 `启用`。如果看到 `需要路由` 标记，说明这个供应商必须在路由运行时使用；没有启动路由时，CC Switch 会弹出“需要路由服务才能正常使用”的提示。
+
+切换后建议重启当前 Codex 终端会话。原因是：
+
+- Codex 进程可能已经读取过旧的 `config.toml`。
+- `model_catalog_json` 生成后，`/model` 菜单通常需要新进程才能刷新。
+
+进入 Codex 后，可以用 `/model` 查看当前模型是否来自 Kimi 预设，例如 `Kimi K2.7 Code` 或 `Kimi For Coding`。目前 Codex app 不支持多模型选择时，会默认使用配置里的第一个模型。随后发一个小问题，确认路由面板的请求数增长，或者在用量/请求日志里看到 Codex 请求即可。
+
+## 其它 Chat 供应商怎么处理
+
+Kimi、DeepSeek、MiniMax、SiliconFlow 等常见 Chat 格式供应商在 CC Switch 里已有预设，优先用预设即可。只有预设里没有的供应商，才需要选择自定义配置；这时按对方文档填 API Key、base URL 和模型，并把 `高级选项` 里的 `上游格式` 选为 `Chat Completions（需开启路由）`。
+
+如果上游直接支持 OpenAI Responses API，把 `上游格式` 选为 `Responses` 即可；这时 CC Switch 按 Responses 直连，不做 Chat 转换。
+
+## 常见问题
+
+**Codex 报 404 或找不到 `/responses`**
+
+通常是没有开启 Codex 接管，或者你手动把 Kimi 的 Chat base URL 直接写给了 Codex——Kimi 上游没有 `/responses` 端点，这样一定会 404。检查 `~/.codex/config.toml` 是否指向 `http://127.0.0.1:15721/v1`。
+
+**Kimi 上游报 401 或 403**
+
+先确认 Key 和预设是否匹配：开放平台的 Key 只能配 `Kimi` 预设，Kimi Code 会员权益的 Key 只能配 `Kimi For Coding` 预设，两套 Key 不能混用。
+
+**Kimi 上游报 404**
+
+如果用的是内置 Kimi 预设，先确认当前供应商确实来自预设，并且 Codex 路由已启用。只有在使用自定义供应商时，才需要额外检查 base URL：它应该是服务根地址，而不是带 `/chat/completions` 的完整接口路径。
+
+**`/model` 看不到 Kimi 模型**
+
+保存供应商后重启 Codex。CC Switch 会生成 `cc-switch-model-catalog.json` 并把路径写入 `model_catalog_json`，但正在运行的 Codex 进程不一定会热加载模型目录。
+目前 Codex app 不支持多模型选择，默认使用配置的第一个模型。
+
+**开了路由但请求仍走错供应商**
+
+确认三处状态一致：Codex 标签下当前供应商是 Kimi；本地路由服务正在运行；`路由启用` 里 Codex 开关已打开。
+
+**可以用官方 OpenAI Codex 账号走本地路由吗**
+
+不建议。CC Switch 会在本地路由接管模式下阻止切到官方供应商，因为用代理访问官方 API 可能带来账号风险。路由主要用于第三方、聚合或协议转换场景。
+
+## 参考链接
+
+- [CC Switch 用户手册：添加供应商](../user-manual/zh/2-providers/2.1-add.md)
+- [CC Switch 用户手册：代理服务](../user-manual/zh/4-proxy/4.1-service.md)
+- [CC Switch 用户手册：应用路由](../user-manual/zh/4-proxy/4.2-routing.md)
+- [Kimi 开放平台：在编程工具中使用 Kimi K2.7 Code 模型](https://platform.kimi.com/docs/guide/agent-support)
+- [Kimi Code 文档：概览](https://www.kimi.com/code/docs/)
+- [Kimi Code 文档：在第三方 Coding Agent 中使用](https://www.kimi.com/code/docs/third-party-tools/other-coding-agents.html)
@@ -0,0 +1,210 @@
+# Keep Codex Remote Control and Official Plugins While Using Third-Party APIs: CC Switch Setup Guide
+
+> Applies to CC Switch v3.16.1 and later. This guide is based on the current code, user manual, and v3.16.1 release notes. Screenshots use de-identified sample data and do not include real Access Tokens or API keys.
+
+## What this guide solves
+
+Many Codex users want both of these at the same time:
+
+1. Use models from DeepSeek, Kimi, GLM, MiniMax, SiliconFlow, or other third-party APIs, or use GPT models through an aggregator.
+2. Keep Codex official-app capabilities such as mobile remote control and official plugins.
+
+Previously, when switching to a third-party provider, the old behavior wrote the third-party API key into Codex `auth.json`, which could overwrite the original official ChatGPT / Codex login cache. The third-party model worked, but features that depend on the official login state disappeared.
+
+The **Codex App Enhancements** switch added in v3.16.1 solves this conflict: the official Access Token stays in `auth.json`, while third-party provider information is written to `config.toml`. Codex App can still see an official account, but actual model requests follow the third-party provider currently selected in CC Switch.
+
+This behavior already existed in v3.16.0 and was enabled by default. After some users reported that they did not want this behavior, v3.16.1 turned it into an explicit switch.
+
+## Quick answer
+
+Recommended order:
+
+1. In the CC Switch Codex panel, switch to `OpenAI Official`.
+2. Start Codex and log in once with an official ChatGPT / Codex account. A Free subscription is enough.
+3. Return to CC Switch and enable `Settings -> General -> Codex App Enhancements -> Keep official login when switching third-party providers`.
+4. Add or switch to a third-party Codex provider.
+5. If the provider uses the Chat Completions protocol, such as DeepSeek / Kimi / MiniMax, also enable local routing and route Codex through it.
+6. Restart Codex so `config.toml` and the model catalog are reloaded.
+
+![Codex App Enhancements switch in Settings](../images/codex-official-auth-preservation/01-codex-app-enhancement-setting.png)
+
+## Prerequisites
+
+Prepare the following:
+
+- CC Switch v3.16.1 or later.
+- Codex installed and able to start. Installing both the app and CLI is recommended.
+- An official ChatGPT / Codex account that can log in to Codex. A Free subscription is enough.
+- A third-party API key, such as DeepSeek, Kimi, GLM, MiniMax, OpenRouter, SiliconFlow, or similar.
+
+Do not manually copy or share the contents of `~/.codex/auth.json`. It stores official login cache and Access Tokens, so it is sensitive.
+
+## Step 1: Switch back to OpenAI Official and complete official login
+
+Open CC Switch and switch to the top-level `Codex` tab. First select the `OpenAI Official` provider, or add it from the preset providers if it is missing, and make it the current provider.
+
+![OpenAI Official and third-party providers in the Codex provider list](../images/codex-deepseek-routing/01-codex-providers-require-routing.png)
+
+Then start Codex, preferably the CLI, and follow the official login flow to sign in with your ChatGPT / Codex account. This account can be on the Free plan. In this setup, it mainly preserves the official identity required by Codex App, and does not pay for third-party model usage.
+
+After login, Codex stores the official login cache in `~/.codex/auth.json`. The key point for the following steps is: do not let third-party provider switching overwrite this file again.
+
+## Step 2: Enable Codex App Enhancements
+
+Return to CC Switch and open:
+
+```text
+Settings -> General -> Codex App Enhancements
+```
+
+Enable:
+
+```text
+Keep official login when switching third-party providers
+```
+
+This switch is off by default because some users do not want this behavior. Enable it only when you explicitly want "third-party API + official remote control / official plugins" at the same time.
+
+After it is enabled, backend switching for third-party Codex providers uses a config-only write path:
+
+- `auth.json`: keeps the official ChatGPT / Codex login cache.
+- `config.toml`: stores the active third-party provider's model, endpoint, `model_provider`, and provider-scoped `experimental_bearer_token`.
+
+## Step 3: Add a third-party Codex provider
+
+Return to the Codex panel and click the plus button in the upper-right corner to add a provider. Prefer built-in presets such as DeepSeek, Kimi, MiniMax, GLM, or SiliconFlow.
+
+Using DeepSeek as an example, after selecting the preset, you only need to enter the API key. The preset automatically configures the base URL, default model, model mapping table, and "Needs Local Routing" flag.
+
+![DeepSeek Codex provider form](../images/codex-deepseek-routing/02-deepseek-codex-routing-form.png)
+
+If your third-party provider natively supports the OpenAI Responses API, such as an aggregator that offers GPT models, local routing may not be needed.
+If it only supports OpenAI Chat Completions, which is common for DeepSeek / Kimi / MiniMax paths, local routing must be enabled so CC Switch can convert Codex Responses requests into Chat Completions requests.
+
+## Step 4: Enable local routing and route Codex when needed
+
+Open:
+
+```text
+Settings -> Routing -> Local Routing
+```
+
+Complete two actions:
+
+1. Turn on the main routing switch to start the local service. The default address is usually `127.0.0.1:15721`.
+2. Under `Routing Enabled`, turn on `Codex`.
+
+![Enabling Codex takeover on the local routing page](../images/codex-deepseek-routing/03-local-route-codex-takeover.png)
+
+After takeover, Codex's live `config.toml` temporarily points to the CC Switch local route. The real third-party API key remains in the CC Switch provider configuration, and is projected into the `experimental_bearer_token` in `config.toml` when providers are switched.
+
+## Step 5: Switch to the third-party provider and restart Codex
+
+Return to the Codex provider list and enable the third-party provider you just added. After switching, restarting Codex is recommended for two reasons:
+
+- Codex reads `config.toml` at startup.
+- The Codex `/model` menu usually needs a restart before it reloads `model_catalog_json`.
+
+After restart, you can run a quick verification:
+
+- In Codex App, the account information still shows the official account. This is expected.
+- In CC Switch, the current Codex provider is the third-party provider.
+- If local routing is enabled, request logs or routing stats show Codex requests going through the local route.
+- The third-party provider dashboard or balance records show actual model requests.
+
+## How it works
+
+Codex mainly uses two configuration files:
+
+```text
+~/.codex/auth.json
+~/.codex/config.toml
+```
+
+They have different responsibilities:
+
+- `auth.json` stores the official ChatGPT / Codex login cache, which Codex App needs to identify the official account and enable remote control and official plugins.
+- `config.toml` stores runtime configuration such as the current model provider, base URL, model, model catalog, and provider-scoped token.
+
+After `Keep official login when switching third-party providers` is enabled, CC Switch takes the third-party provider API key from the provider configuration and writes it under the current provider in `config.toml`:
+
+```toml
+model_provider = "custom"
+
+[model_providers.custom]
+name = "DeepSeek"
+base_url = "https://api.deepseek.com"
+wire_api = "responses"
+experimental_bearer_token = "sk-..."
+```
+
+At the same time, `auth.json` keeps the official login cache unchanged. Codex App can still identify the official account, while model requests follow the current provider and base URL in `config.toml`.
+
+If the provider uses the Chat Completions protocol, CC Switch local routing adds another conversion layer:
+
+```text
+Codex Responses request
+        |
+CC Switch local route
+        |
+Third-party Chat Completions API
+        |
+Converted back to Codex Responses response
+```
+
+This is why you can keep using official plugins / mobile remote control while moving model traffic to a third-party API.
+
+## Side effects to understand
+
+### Codex still shows the official account
+
+This is the easiest part to misunderstand. After this capability is enabled, Codex App reads the official login state from `auth.json`, so it continues to display the official account.
+
+That does not mean model requests are still going to official OpenAI. Actual traffic is determined by the current Codex provider in CC Switch, `config.toml`, and local routing logs.
+
+### Do not use the Codex account display to judge billing
+
+If you switch to DeepSeek, Codex can still display the official account, while model requests go to the DeepSeek API. Billing, quota, error codes, and data policy should all be understood according to the third-party provider. You can inspect specific request details in the usage panel.
+
+### Restart Codex after changing model mappings
+
+Codex reads the model catalog at startup. Even if CC Switch has generated a new model catalog, a running Codex process may not hot-load it, so restart Codex after editing model mappings.
+
+### Turning the switch off returns to the old behavior
+
+If `Keep official login when switching third-party providers` is turned off, third-party provider switching uses the compatibility behavior from older versions and may write `auth.json` again. If your goal is to keep official remote control and official plugins long term, keep this switch enabled.
+
+## FAQ
+
+**I switched to a third-party API. Why does Codex still show the official account?**
+
+This is expected. Official account information comes from `auth.json`; the actual model provider comes from `config.toml` and the current provider in CC Switch.
+
+**Is a Free subscription really enough?**
+
+Yes. The official account is mainly used to obtain and preserve the official login state required by Codex App. Third-party model requests use the third-party API key configured in CC Switch.
+
+**What should I do if official plugins or mobile remote control still do not work?**
+
+Switch back to `OpenAI Official`, restart Codex, and complete official login once. Then confirm `Settings -> General -> Codex App Enhancements -> Keep official login when switching third-party providers` is enabled in CC Switch before switching back to the third-party provider.
+
+**What if third-party requests return 404, the model list is wrong, or streaming responses are broken?**
+
+If the provider uses Chat Completions, confirm that the provider form has `Needs Local Routing` enabled, and that `Settings -> Routing` has both the main routing switch and Codex takeover enabled.
+
+**Can I switch back to OpenAI Official while local routing is enabled?**
+
+Not recommended. CC Switch tries to prevent switching to official providers while local routing takeover is active, because accessing official APIs through a proxy may create account risk. Use official login only to preserve `auth.json`, and route model traffic to third-party providers.
+
+**Why is this flow so complex? Can it be simplified?**
+
+Because Codex App Enhancements and routing takeover can create unnecessary trouble for users who do not need them, these features are explicit switches instead of always-on behavior.
+
+## References
+
+- [Can't see custom models in the Codex desktop app? (FAQ)](./codex-desktop-custom-model-visibility-en.md)
+- [Codex DeepSeek local routing hands-on guide](./codex-deepseek-routing-guide-en.md)
+- [Add a Codex provider: Chat Completions routing and model mapping](../user-manual/en/2-providers/2.1-add.md)
+- [Local Proxy Service](../user-manual/en/4-proxy/4.1-service.md)
+- [Local Routing](../user-manual/en/4-proxy/4.2-routing.md)
+- [CC Switch v3.16.1 Release Note](../release-notes/v3.16.1-en.md)
@@ -0,0 +1,210 @@
+# サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する: CC Switch 設定ガイド
+
+> 対象バージョン: CC Switch v3.16.1 以降。本記事は現在のコード、ユーザーマニュアル、v3.16.1 Release Note をもとに整理しています。スクリーンショットは匿名化したサンプルデータを使用しており、実際の Access Token や API Key は含まれていません。
+
+## このガイドで解決すること
+
+Codex を使うとき、多くのユーザーには次の 2 つの要望があります。
+
+1. DeepSeek、Kimi、GLM、MiniMax、SiliconFlow などのサードパーティ API、または中継サービス上の GPT モデルを使いたい。
+2. Codex 公式アプリのモバイルリモート操作、公式プラグインなどの機能は残したい。
+
+以前は、サードパーティプロバイダーへ切り替えると、旧動作ではサードパーティ API Key が Codex の `auth.json` に書き込まれ、元の公式 ChatGPT / Codex ログインキャッシュを上書きする可能性がありました。これによりサードパーティモデルは使えるものの、公式ログイン状態に依存する機能が消えてしまうことがありました。
+
+v3.16.1 で追加された **Codex アプリ拡張** スイッチは、この矛盾を解決するためのものです。公式 Access Token は `auth.json` に残し、サードパーティプロバイダー情報は `config.toml` に書き込みます。これにより Codex App は引き続き公式アカウントでログインしていると認識しつつ、実際のモデルリクエストは CC Switch で現在選択されているサードパーティプロバイダーへ流れます。
+
+この機能自体は v3.16.0 から存在し、当時はデフォルトで有効でした。ただし一部のユーザーから不要というフィードバックがあったため、v3.16.1 で明示的なスイッチになりました。
+
+## まず結論
+
+おすすめの手順は次のとおりです。
+
+1. CC Switch の Codex パネルで `OpenAI Official` に切り替える。
+2. Codex を起動し、公式 ChatGPT / Codex アカウントで一度ログインする。Free サブスクリプションでも構いません。
+3. CC Switch に戻り、`設定 → 一般 → Codex アプリ拡張 → サードパーティ切替時に公式ログインを保持` をオンにする。
+4. サードパーティ Codex プロバイダーを追加、または切り替える。
+5. そのプロバイダーが DeepSeek / Kimi / MiniMax などの Chat Completions プロトコルの場合は、ローカルルーティングも有効化し、Codex のルーティングをオンにする。
+6. Codex を再起動し、`config.toml` とモデルカタログを再読み込みさせる。
+
+![設定内の Codex アプリ拡張スイッチ](../images/codex-official-auth-preservation/01-codex-app-enhancement-setting.png)
+
+## 事前準備
+
+次のものを用意してください。
+
+- CC Switch v3.16.1 以降。
+- インストール済みで起動できる Codex。app と CLI の両方を入れておくことをおすすめします。
+- Codex にログインできる公式 ChatGPT / Codex アカウント。Free サブスクリプションで構いません。
+- DeepSeek、Kimi、GLM、MiniMax、OpenRouter、SiliconFlow などのサードパーティ API Key。
+
+`~/.codex/auth.json` の内容を手動でコピーしたり共有したりしないでください。このファイルには公式ログインキャッシュと Access Token が保存されており、機密情報です。
+
+## Step 1: OpenAI Official に戻して公式ログインを完了する
+
+CC Switch を開き、上部の `Codex` タブへ切り替えます。まず `OpenAI Official` プロバイダーを選択します。存在しない場合は、プリセットプロバイダーから追加して現在のプロバイダーにしてください。
+
+![Codex プロバイダー一覧内の OpenAI Official とサードパーティプロバイダー](../images/codex-deepseek-routing/01-codex-providers-require-routing.png)
+
+次に Codex を起動します。CLI の起動がおすすめです。Codex の公式ログインフローに従い、ChatGPT / Codex アカウントでログインします。このアカウントは Free プランでも問題ありません。この構成では、主に Codex App が必要とする公式ログイン ID を保持する役割であり、サードパーティモデルの課金には使いません。
+
+ログイン後、Codex は `~/.codex/auth.json` に公式ログインキャッシュを保存します。以降の重要なポイントは、サードパーティプロバイダー切り替えでこのファイルを上書きさせないことです。
+
+## Step 2: Codex アプリ拡張を有効化する
+
+CC Switch に戻り、次を開きます。
+
+```text
+設定 → 一般 → Codex アプリ拡張
+```
+
+次のスイッチをオンにします。
+
+```text
+サードパーティ切替時に公式ログインを保持
+```
+
+このスイッチはデフォルトでオフです。一部のユーザーはこの機能を必要としていないためです。「サードパーティ API + 公式リモート操作 / 公式プラグイン」を同時に使いたい場合だけ有効化してください。
+
+有効化すると、バックエンドで Codex サードパーティプロバイダーを切り替えるときに config-only の書き込み経路が使われます。
+
+- `auth.json`: 公式 ChatGPT / Codex ログインキャッシュを保持します。
+- `config.toml`: 現在のサードパーティプロバイダーのモデル、endpoint、`model_provider`、provider-scoped `experimental_bearer_token` を書き込みます。
+
+## Step 3: サードパーティ Codex プロバイダーを追加する
+
+Codex パネルに戻り、右上のプラスボタンからプロバイダーを追加します。DeepSeek、Kimi、MiniMax、GLM、SiliconFlow などの内蔵プリセットを優先して使うのがおすすめです。
+
+DeepSeek を例にすると、プリセットを選んだ後は API Key を入力するだけです。プリセットは base URL、デフォルトモデル、モデルマッピングテーブル、「ローカルルーティングが必要」設定を自動で構成します。
+
+![DeepSeek Codex プロバイダーフォーム](../images/codex-deepseek-routing/02-deepseek-codex-routing-form.png)
+
+サードパーティプロバイダーが OpenAI Responses API をネイティブにサポートしている場合、たとえば GPT モデルを提供する中継サービスであれば、ローカルルーティングは不要なことがあります。
+一方で DeepSeek / Kimi / MiniMax のように OpenAI Chat Completions だけをサポートする場合は、CC Switch が Codex の Responses リクエストを Chat Completions リクエストへ変換する必要があるため、ローカルルーティングを有効化してください。
+
+## Step 4: 必要に応じてローカルルーティングと Codex ルーティングを有効化する
+
+次を開きます。
+
+```text
+設定 → ルーティング → ローカルルーティング
+```
+
+次の 2 つを行います。
+
+1. `ルーティング総スイッチ` をオンにし、ローカルサービスを起動する。デフォルトアドレスは通常 `127.0.0.1:15721` です。
+2. `ルーティング有効` で `Codex` をオンにする。
+
+![ローカルルーティング画面で Codex ルーティングを有効化](../images/codex-deepseek-routing/03-local-route-codex-takeover.png)
+
+ルーティング有効化後、Codex の live `config.toml` は一時的に CC Switch のローカルルートを指します。実際のサードパーティ API Key は CC Switch のプロバイダー設定内に残り、プロバイダー切り替え時に `config.toml` の `experimental_bearer_token` へ投影されます。
+
+## Step 5: サードパーティプロバイダーへ切り替えて Codex を再起動する
+
+Codex プロバイダー一覧に戻り、先ほど追加したサードパーティプロバイダーを有効化します。切り替え後は Codex の再起動をおすすめします。理由は 2 つあります。
+
+- Codex は起動時に `config.toml` を読み込みます。
+- Codex の `/model` メニューは通常、再起動後に `model_catalog_json` を再読み込みします。
+
+再起動後、簡単に確認できます。
+
+- Codex App ではアカウント情報が引き続き公式アカウントとして表示される。これは期待される動作です。
+- CC Switch では現在の Codex プロバイダーがサードパーティプロバイダーになっている。
+- ローカルルーティングを有効化している場合、リクエストログまたはルーティング統計で Codex リクエストがローカルルートを通っていることを確認できる。
+- サードパーティプロバイダー側のダッシュボードや残高記録に実際のモデルリクエストが表示される。
+
+## 仕組み
+
+Codex の設定は主に 2 つのファイルに分かれています。
+
+```text
+~/.codex/auth.json
+~/.codex/config.toml
+```
+
+この 2 つは役割が異なります。
+
+- `auth.json` は公式 ChatGPT / Codex ログインキャッシュを保存します。Codex App が公式アカウント、リモート操作、公式プラグインを認識するために必要なログイン材料です。
+- `config.toml` は現在のモデルプロバイダー、base URL、モデル、モデルカタログ、provider-scoped token などの実行時設定を保存します。
+
+`サードパーティ切替時に公式ログインを保持` を有効化すると、CC Switch はサードパーティプロバイダー API Key をプロバイダー設定から取り出し、`config.toml` の現在の provider 配下へ書き込みます。
+
+```toml
+model_provider = "custom"
+
+[model_providers.custom]
+name = "DeepSeek"
+base_url = "https://api.deepseek.com"
+wire_api = "responses"
+experimental_bearer_token = "sk-..."
+```
+
+同時に、`auth.json` は公式ログインキャッシュを保持したままです。そのため Codex App 側では公式アカウントを認識でき、モデルリクエストは `config.toml` の現在の provider と base URL に従ってサードパーティ API へ向かいます。
+
+プロバイダーが Chat Completions プロトコルの場合、CC Switch のローカルルーティングがさらに変換層になります。
+
+```text
+Codex Responses リクエスト
+        |
+CC Switch ローカルルート
+        |
+サードパーティ Chat Completions API
+        |
+Codex Responses レスポンスへ変換
+```
+
+これにより、公式プラグイン / モバイルリモート操作を使い続けながら、モデル通信だけをサードパーティ API に切り替えられます。
+
+## 理解しておくべき副作用
+
+### Codex 内の表示アカウントは公式アカウントのまま
+
+ここが最も誤解されやすい点です。この機能を有効化すると、Codex App は `auth.json` 内の公式ログイン状態を見るため、公式アカウント情報を表示し続けます。
+
+ただし、これはモデルリクエストが公式 OpenAI に流れているという意味ではありません。実際の通信先は、CC Switch の現在の Codex プロバイダー、`config.toml`、ローカルルーティングログで判断してください。
+
+### Codex のアカウント表示で課金先を判断しない
+
+DeepSeek に切り替えた場合でも、Codex には公式アカウントが表示されます。しかしモデルリクエストは DeepSeek API へ送られます。課金、上限、エラーコード、データポリシーはサードパーティプロバイダー側の仕様として理解してください。具体的なリクエスト情報は使用量パネルで確認できます。
+
+### モデルマッピングを変更したら Codex を再起動する
+
+Codex のモデルカタログは起動時に読み込まれます。CC Switch が新しいモデルカタログを生成していても、実行中の Codex がホットロードするとは限りません。モデルマッピングを変更した後は Codex を再起動してください。
+
+### スイッチをオフにすると旧動作に戻る
+
+`サードパーティ切替時に公式ログインを保持` をオフにすると、サードパーティプロバイダー切り替えは旧バージョン互換の動作になり、`auth.json` が再度書き込まれる可能性があります。公式リモート操作と公式プラグインを長期的に保持したい場合は、このスイッチをオンのままにすることをおすすめします。
+
+## よくある質問
+
+**サードパーティ API に切り替えたのに、なぜ Codex はまだ公式アカウントを表示しますか？**
+
+これは期待される動作です。公式アカウント情報は `auth.json` から取得され、実際のモデルプロバイダーは `config.toml` と CC Switch の現在のプロバイダーで決まります。
+
+**Free サブスクリプションで本当に大丈夫ですか？**
+
+大丈夫です。ここでの公式アカウントは、Codex App が必要とする公式ログイン状態を取得・保持するために使います。サードパーティモデルリクエストは、CC Switch に設定したサードパーティ API Key を使います。
+
+**有効化しても公式プラグインやモバイルリモート操作が使えない場合は？**
+
+まず `OpenAI Official` に戻し、Codex を再起動して一度公式ログインを完了してください。その後、CC Switch の `設定 → 一般 → Codex アプリ拡張 → サードパーティ切替時に公式ログインを保持` がオンになっていることを確認し、再度サードパーティプロバイダーへ切り替えてください。
+
+**サードパーティリクエストが 404 になる、モデル一覧が違う、ストリーミング応答がおかしい場合は？**
+
+そのプロバイダーが Chat Completions プロトコルの場合、プロバイダーフォームで `ローカルルーティングが必要` が有効になっていること、さらに `設定 → ルーティング` でルーティング総スイッチと Codex ルーティングがオンになっていることを確認してください。
+
+**ローカルルーティング中に OpenAI Official へ戻せますか？**
+
+おすすめしません。CC Switch は、ローカルルーティングで Codex を管理している間に公式プロバイダーへ切り替えることをできるだけ防ぎます。プロキシ経由で公式 API にアクセスすると、アカウントリスクが発生する可能性があるためです。公式ログインは `auth.json` を保持するために使い、モデル通信はサードパーティプロバイダーへ切り替えるのがおすすめです。
+
+**なぜ手順がこんなに複雑なのですか？もっと簡単にできますか？**
+
+Codex アプリ拡張やルーティング管理は、必要ないユーザーにとっては余計なトラブルになり得るため、常時有効ではなく明示的なスイッチになっています。
+
+## 参考リンク
+
+- [Codex デスクトップアプリでカスタムモデルが見えない？（よくある質問）](./codex-desktop-custom-model-visibility-ja.md)
+- [Codex DeepSeek ローカルルーティング実践ガイド](./codex-deepseek-routing-guide-ja.md)
+- [Codex プロバイダーの追加: Chat Completions ルーティングとモデルマッピング](../user-manual/ja/2-providers/2.1-add.md)
+- [ローカルプロキシサービス](../user-manual/ja/4-proxy/4.1-service.md)
+- [ローカルルーティング](../user-manual/ja/4-proxy/4.2-routing.md)
+- [CC Switch v3.16.1 Release Note](../release-notes/v3.16.1-ja.md)
@@ -0,0 +1,210 @@
+# 使用第三方 API 时保留 Codex 远程操作和官方插件：CC Switch 配置攻略
+
+> 适用版本：CC Switch v3.16.1 及以上。本文根据当前代码、用户手册和 v3.16.1 Release Note 整理，截图使用去敏示例数据，不包含真实 Access Token 或 API Key。
+
+## 这篇攻略解决什么问题
+
+很多人使用 Codex 时有两个需求：
+
+1. 模型使用 DeepSeek、Kimi、GLM、MiniMax、硅基流动等第三方 API，或者在中转站使用 gpt 模型。
+2. 保留 Codex 官方 App 的手机远程操作、官方插件等能力。
+
+之前切换第三方供应商时，旧行为会把第三方 API Key 写进 Codex 的 `auth.json`，从而覆盖原来的官方 ChatGPT / Codex 登录缓存。这样第三方模型能用了，但依赖官方登录态的功能会消失。
+
+v3.16.1 新增的 **Codex 应用增强**开关就是为了解决这个矛盾：让官方 Access Token 继续留在 `auth.json`，而第三方供应商信息写入 `config.toml`。这样 Codex App 仍然认为你登录的是官方账号，但实际模型请求会走 CC Switch 当前选中的第三方供应商。
+
+v3.16.0 就有这个功能，并且默认开启，但是部分用户反映并不想要这个功能，所以在 v3.16.1 中把这个功能做成了开关。
+
+## 先看结论
+
+推荐顺序是：
+
+1. 在 CC Switch 的 Codex 面板切换到 `OpenAI Official`。
+2. 启动 Codex，并用官方 ChatGPT / Codex 账号登录一次，Free 订阅也可以。
+3. 回到 CC Switch，打开 `设置 → 通用 → Codex 应用增强 → 切换第三方时保留官方登录`。
+4. 添加或切换到第三方 Codex 供应商。
+5. 如果该供应商是 Chat Completions 协议，例如 DeepSeek / Kimi / MiniMax，需要同时开启本地路由并启用 Codex 接管。
+6. 重启 Codex，让 `config.toml` 和模型目录重新加载。
+
+![设置里的 Codex 应用增强开关](../images/codex-official-auth-preservation/01-codex-app-enhancement-setting.png)
+
+## 准备工作
+
+你需要准备：
+
+- CC Switch v3.16.1 或更新版本。
+- 已安装并能启动的 Codex（建议 app 和 cli 都安装）。
+- 一个可以登录 Codex 的官方 ChatGPT / Codex 账号，Free 订阅即可。
+- 一个第三方 API Key，例如 DeepSeek、Kimi、GLM、MiniMax、OpenRouter、硅基流动等。
+
+请不要手动复制或分享 `~/.codex/auth.json` 的内容。里面保存的是官方登录缓存和 Access Token，属于敏感信息。
+
+## 第一步：先切回 OpenAI Official 并完成官方登录
+
+打开 CC Switch，切到顶部的 `Codex` 标签页。先选择 `OpenAI Official` 供应商（如果没有的话，就在预设供应商当中添加一个），并把它设为当前供应商。
+
+![Codex 供应商列表中的 OpenAI Official 与第三方供应商](../images/codex-deepseek-routing/01-codex-providers-require-routing.png)
+
+接着启动 Codex（建议启动 cli），按 Codex 的官方登录流程登录你的 ChatGPT / Codex 账号。这个账号可以是 Free 订阅；在这个方案里，它主要负责保留 Codex 官方 App 需要识别的登录身份，不负责第三方模型的计费。
+
+登录完成后，Codex 会在 `~/.codex/auth.json` 中保存官方登录缓存。后面的关键点就是：不要再让第三方供应商切换覆盖这个文件。
+
+## 第二步：开启 Codex 应用增强
+
+回到 CC Switch，进入：
+
+```text
+设置 → 通用 → Codex 应用增强
+```
+
+打开：
+
+```text
+切换第三方时保留官方登录
+```
+
+这个开关默认关闭，是因为部分用户并不想要这个功能。只有在你明确需要“第三方 API + 官方远程操作 / 官方插件”同时存在时，才需要开启它。
+
+开启后，后端切换 Codex 第三方供应商时会走 config-only 写入路径：
+
+- `auth.json`：继续保留官方 ChatGPT / Codex 登录缓存。
+- `config.toml`：写入当前第三方供应商的模型、endpoint、`model_provider` 和 provider-scoped `experimental_bearer_token`。
+
+## 第三步：添加第三方 Codex 供应商
+
+回到 Codex 面板，点击右上角的加号添加供应商。推荐优先使用内置预设，例如 DeepSeek、Kimi、MiniMax、GLM、SiliconFlow 等。
+
+以 DeepSeek 为例，选择预设后只需要填 API Key。预设会自动配置 base URL、默认模型、模型映射表和“需要本地路由映射”。
+
+![DeepSeek Codex 供应商表单](../images/codex-deepseek-routing/02-deepseek-codex-routing-form.png)
+
+如果你的第三方供应商原生支持 OpenAI Responses API（比如提供 gpt 模型的中转站），可以不启用本地路由。
+如果它只支持 OpenAI Chat Completions，例如常见的 DeepSeek / Kimi / MiniMax 路径，就必须启用本地路由，让 CC Switch 把 Codex 的 Responses 请求转换成 Chat Completions 请求。
+
+## 第四步：需要时开启本地路由并接管 Codex
+
+进入：
+
+```text
+设置 → 路由 → 本地路由
+```
+
+完成两件事：
+
+1. 打开 `路由总开关`，启动本地服务。默认地址通常是 `127.0.0.1:15721`。
+2. 在 `路由启用` 中打开 `Codex`。
+
+![本地路由页面中启用 Codex 接管](../images/codex-deepseek-routing/03-local-route-codex-takeover.png)
+
+接管后，Codex 的 live `config.toml` 会临时指向 CC Switch 本地路由。真实第三方 API Key 仍然存储在 CC Switch 的供应商配置中，切换供应商时再投影到 `config.toml` 的 `experimental_bearer_token`。
+
+## 第五步：切换第三方供应商并重启 Codex
+
+回到 Codex 供应商列表，启用你刚添加的第三方供应商。切换完成后建议重启 Codex，原因有两个：
+
+- Codex 在启动时读取 `config.toml`。
+- Codex 的 `/model` 菜单通常需要重启后才会重新加载 `model_catalog_json`。
+
+重启后，你可以做一个简单验证：
+
+- 在 Codex App 里，账号信息仍然显示官方账号，这是预期行为。
+- 在 CC Switch 里，当前 Codex 供应商显示为第三方供应商。
+- 如果开启了本地路由，请求日志或路由统计会看到 Codex 请求经过本地路由。
+- 第三方供应商后台或余额记录会出现实际模型请求。
+
+## 背后的原理
+
+Codex 的配置主要分成两个文件：
+
+```text
+~/.codex/auth.json
+~/.codex/config.toml
+```
+
+这两个文件承担的职责不同：
+
+- `auth.json` 保存官方 ChatGPT / Codex 登录缓存，也就是 Codex App 识别官方账号、远程操作和官方插件所需的登录材料。
+- `config.toml` 保存当前模型供应商、base URL、模型、模型目录和 provider-scoped token 等运行配置。
+
+开启 `切换第三方时保留官方登录` 后，CC Switch 的切换逻辑会把第三方供应商 API Key 从供应商配置中取出，写到 `config.toml` 的当前 provider 下：
+
+```toml
+model_provider = "custom"
+
+[model_providers.custom]
+name = "DeepSeek"
+base_url = "https://api.deepseek.com"
+wire_api = "responses"
+experimental_bearer_token = "sk-..."
+```
+
+同时，`auth.json` 保持官方登录缓存不变。于是 Codex App 侧依然能识别官方账号；而模型请求会根据 `config.toml` 的当前 provider 和 base URL 走第三方 API。
+
+如果供应商是 Chat Completions 协议，CC Switch 本地路由会再做一层转换：
+
+```text
+Codex Responses 请求
+        ↓
+CC Switch 本地路由
+        ↓
+第三方 Chat Completions API
+        ↓
+转换回 Codex Responses 响应
+```
+
+这就是为什么你既能继续使用官方插件 / 手机远程操作，又能把模型流量切到第三方 API。
+
+## 需要理解的副作用
+
+### Codex 里显示的账号始终是官方账号
+
+这是最容易误解的一点。开启该能力后，Codex App 看到的是 `auth.json` 里的官方登录态，所以它会继续显示官方账号信息。
+
+但这不代表模型请求还在走官方 OpenAI。实际流量以 CC Switch 当前 Codex 供应商、`config.toml` 和本地路由日志为准。
+
+### 不要用 Codex 账号信息判断计费方
+
+如果你切到 DeepSeek，Codex 里仍然显示官方账号，但模型请求会走 DeepSeek API。计费、限额、错误码和数据策略都应按第三方供应商理解。可以查看设置用量面板里的具体请求信息。
+
+### 修改模型映射后要重启 Codex
+
+Codex 的模型目录是启动时读取的。即使 CC Switch 已经生成了新的模型目录，正在运行的 Codex 也不一定会热加载，所以修改模型映射后请重启 Codex。
+
+### 关闭开关会回到旧行为
+
+如果关闭 `切换第三方时保留官方登录`，第三方供应商切换会沿用兼容旧版本的行为，可能重新写入 `auth.json`。如果你的目标是长期保留官方远程操作和官方插件，建议保持该开关开启。
+
+## 常见问题
+
+**我已经切到第三方 API，为什么 Codex 还显示官方账号？**
+
+这是预期行为。官方账号信息来自 `auth.json`，模型请求的实际供应商来自 `config.toml` 和 CC Switch 当前供应商。
+
+**Free 订阅真的可以吗？**
+
+可以。这里的官方账号主要用于获取并保留 Codex App 需要的官方登录态。第三方模型请求使用的是你在 CC Switch 里配置的第三方 API Key。
+
+**开启后官方插件或手机远程操作还是不可用怎么办？**
+
+先切回 `OpenAI Official`，重新启动 Codex 并完成一次官方登录；然后确认 CC Switch 的 `设置 → 通用 → Codex 应用增强 → 切换第三方时保留官方登录` 已开启，再切回第三方供应商。
+
+**第三方请求 404、模型列表不对或流式响应异常怎么办？**
+
+如果该供应商是 Chat Completions 协议，请确认供应商表单里开启了 `需要本地路由映射`，并且 `设置 → 路由` 里已经启动路由总开关、启用 Codex 接管。
+
+**可以在本地路由模式下切回 OpenAI Official 吗？**
+
+不建议。CC Switch 会尽量阻止在本地路由接管模式下切到官方供应商，因为用代理访问官方 API 可能带来账号风险。建议官方登录只用于保留 `auth.json`，模型流量则切到第三方供应商。
+
+**为什么流程做的这么复杂？可以简化吗？**
+
+因为 Codex 增强开关和路由接管等一系列功能，如果用户并不需要的话，默认打开会带来不必要的麻烦，所以都做成了开关形式。
+
+## 参考链接
+
+- [Codex 桌面应用里看不到自定义模型？（常见问题）](./codex-desktop-custom-model-visibility-zh.md)
+- [Codex DeepSeek 本地路由实战攻略](./codex-deepseek-routing-guide-zh.md)
+- [添加 Codex 供应商：Chat Completions 路由与模型映射](../user-manual/zh/2-providers/2.1-add.md)
+- [本地代理服务](../user-manual/zh/4-proxy/4.1-service.md)
+- [本地路由](../user-manual/zh/4-proxy/4.2-routing.md)
+- [CC Switch v3.16.1 Release Note](../release-notes/v3.16.1-zh.md)
@@ -0,0 +1,467 @@
+# Unified Codex Session History: Feature Overview and Usage Guide (CC Switch)
+
+> Applies to CC Switch v3.16.x and later. This guide is based on the current code; every command and path can be verified by hand. Examples use de-identified data and contain no real session content or API keys.
+
+## What this feature is
+
+"Unified Codex session history" is a switch that CC Switch v3.16.x adds for Codex. You'll find it under **Settings -> General -> the "Codex App Enhancements" group** ("Codex App Enhancements" is the group title; the switch itself is called "Unified Codex session history"). Once enabled, **sessions from your official subscription (ChatGPT login / OpenAI API key) appear in the same history / resume list as sessions from every third-party provider CC Switch manages**—they are no longer split into two lists that can't see each other.
+
+## What problem it solves
+
+Codex classifies sessions by a "provider tag" (a field called `model_provider`), and **the resume / history list only shows sessions whose tag matches your currently active provider**. As a result, sessions are naturally sorted into two separate "drawers":
+
+- Sessions from your official subscription go under Codex's built-in **`openai`** tag;
+- Every third-party provider CC Switch manages goes under the **`custom`** tag.
+
+The two drawers can't see each other. If you **switch frequently between official and third-party**, you'll hit this kind of fragmentation: "the session I was just chatting in with the official account disappeared from the history list after I switched to a third-party provider"—it isn't actually gone, it's just been sorted into the other drawer. This split both makes it easy to believe a session was lost, and makes it inconvenient to review and resume all your sessions in one place.
+
+**This switch exists to eliminate that fragmentation**: it makes the official subscription run under the `custom` tag too, so official and third-party sessions merge into one list and everything is easy to find and resume in a single place.
+
+> ✅ **One important premise that runs through this whole guide, please remember it first**: this feature (unify / migrate / restore) **only ever rewrites that one classification tag `model_provider` in your session records, and it automatically makes a backup of the original file before every rewrite**. It never deletes, clears, or overwrites a single line of your conversations. So whenever this guide later mentions "some sessions are no longer visible," it almost always means "they've been sorted into the other drawer," not "the data is gone." If you're truly worried, jump straight to the [symptom reference table](#i-feel-like-my-sessions-are-gone-symptom-reference-table) and [verify the files are still there by hand](#verify-by-hand-your-session-files-are-still-on-disk-the-most-important-section).
+
+## How it works (one-line version)
+
+Think of it as **two drawers + automatic backup**:
+
+- By default, official sessions live in the `openai` drawer and third-party sessions live in the `custom` drawer, invisible to each other;
+- The switch makes **the official side use the `custom` drawer too**, merging the two drawers into one shared list;
+- You can optionally choose to "move" your **existing official sessions** into the shared drawer as well (this step is called **migration**; it's optional and requires you to opt in by checking a box), and **before anything is moved a backup copy is made first**, so the whole process is **reversible**;
+- **Authentication is completely unaffected**—your official subscription still uses your ChatGPT login and still goes through the official backend; only the session's classification tag changes.
+
+For the full mechanism (what gets injected, why it's reversible, how migration / restore guarantee no data loss) see [The core mental model](#the-core-mental-model-two-drawers--automatic-backup) and the [Advanced mechanism appendix](#advanced-mechanism-appendix-for-users-who-want-to-truly-understand-how-it-works) at the end.
+
+## How to use it (at a glance)
+
+1. **Enable**: Settings -> General -> Codex App Enhancements -> turn on "Unified Codex session history" -> in the dialog decide whether to check "Also migrate existing official session history" (check it if you want your **earlier** official sessions merged into the unified list too; leave it unchecked if you only want unification from now on) -> confirm. See [What happens when you enable it](#what-happens-when-you-enable-it-step-by-step).
+2. **Disable**: turn the same switch off -> in the dialog keep "restore exactly from backup" checked (it's checked by default) -> confirm, and the official sessions you migrated in will be precisely flipped back to the official list. See [What happens when you disable it](#what-happens-when-you-disable-it-step-by-step).
+3. **Feel like a session is gone?** Don't panic—jump to the [symptom reference table](#i-feel-like-my-sessions-are-gone-symptom-reference-table) to locate it by symptom, and use the commands in the [verify by hand](#verify-by-hand-your-session-files-are-still-on-disk-the-most-important-section) section to see for yourself that the files are all there.
+
+---
+
+## The core mental model: two drawers + automatic backup
+
+To understand this feature, you only need to remember two things: **drawers** and **backups**.
+
+### Drawers: how Codex classifies sessions
+
+Every time you start a Codex session, Codex records a tag `model_provider` in the session file header, marking "which provider this session was chatted with." Codex's **resume / history list is filtered precisely by the currently active tag**—it only shows sessions whose tag matches "the provider you're on right now."
+
+- Sessions from your official subscription (ChatGPT login / OpenAI API key) carry the built-in tag **`openai`**.
+- Every third-party provider CC Switch manages uses the tag **`custom`**.
+
+So by default, official sessions and third-party sessions are inherently invisible to each other—they live in two different drawers. This is **Codex's own design**, not CC Switch losing anything.
+
+```text
+Default state (unified switch off):
+   ┌───────────────────────┐     ┌──────────────────────────┐
+   │  openai drawer        │     │  custom drawer           │
+   │  (official sessions)  │     │  (third-party sessions)  │
+   └───────────────────────┘     └──────────────────────────┘
+       ▲                             ▲
+     visible only while            visible only while
+     on the official provider       on a third-party provider
+
+   The two drawers can't see each other.
+```
+
+**What the "Unified Codex session history" switch does is make the official subscription run under the `custom` tag too, merging the two drawers into one**, so official and third-party sessions appear in the same resume list. Note: **authentication doesn't change**—your official subscription still uses your ChatGPT login and still goes through the official backend; only the session's "classification tag" changes from `openai` to `custom`.
+
+```text
+After the unified switch is on:
+   ┌──────────────────────────────────────────────┐
+   │             custom shared drawer             │
+   │  official sessions  +  third-party sessions  │
+   │  (appear in the same history / resume list)  │
+   └──────────────────────────────────────────────┘
+```
+
+### Backups: a copy is made before every tag change
+
+"Merging the drawers" requires changing the tag of some official sessions from `openai` to `custom` (this step is called **migration**, and it's **optional and requires you to opt in**). And **before any rewrite, CC Switch first copies the original file untouched** to here:
+
+```text
+~/.cc-switch/backups/codex-official-history-unify-v1/<timestamp>/
+```
+
+This backup is the sole basis for "restore exactly from backup" later. It makes the whole process **reversible**: at any time you can turn off the switch and precisely flip the official sessions you migrated in back to the `openai` drawer.
+
+Remember these two words—**drawer** (a session just gets reclassified) and **backup** (a copy is always made before a change)—and everything that follows will be easy to understand.
+
+---
+
+## What happens when you enable it: step by step
+
+### Step 1: Find the switch
+
+```text
+Settings -> General -> Codex App Enhancements
+```
+
+In the "Codex App Enhancements" block there are two rows of switches; the **second row** (the blue history icon) is the subject of this guide:
+
+> **Unified Codex session history**
+
+Below it is a line of description text (verbatim):
+
+> When enabled, the official subscription runs under the shared "custom" provider id so official and third-party sessions appear in one history list, optionally migrating existing official sessions in (backed up first). When turning it off, the migrated sessions can be restored from backup. Note: resuming an old session across providers may fail because its encrypted_content reasoning can only be decrypted by the backend that created it.
+
+> **Note**: this single line of description already previews three things—sessions will appear in one list, you can optionally migrate them in with an automatic backup, and resuming across providers "may fail." Here, "fail" means **you can't resume / can't generate a new turn**, not "the record is lost." This is exactly the core misunderstanding we'll dig into below.
+
+### Step 2: Flip the switch from off to on -> a confirmation dialog pops up
+
+The moment you flip the switch on, CC Switch **does not save immediately**; instead it first pops up a confirmation dialog. The dialog text reads as follows (verbatim):
+
+- **Title**: Unified Codex session history
+- **Body**:
+
+  > When enabled, the official subscription and third-party providers share one session history list. Note: resuming an old session across providers may fail because its encrypted_content reasoning cannot be decrypted by another backend.
+  >
+  > You can also migrate your existing official session history into the shared list (originals are backed up to ~/.cc-switch/backups first and can be restored when you turn this off).
+
+- **Checkbox**: Also migrate existing official session history
+- **Confirm button**: I understand, enable
+- **Cancel button**: Cancel
+
+**This checkbox is unchecked by default.** This is an important fork in the road:
+
+| Your choice | Effect | Where your data is right now |
+|---|---|---|
+| **Unchecked** (default) | Only switches the tag. **Only official sessions created after enabling** land in the `custom` shared drawer | Your official sessions from **before** enabling keep the `openai` tag, stay exactly where they were, still in `~/.codex/sessions/` |
+| **Checked** | In addition to switching the tag, also migrates your **existing official sessions** from the `openai` drawer into the `custom` drawer | After being **copied to backup**, the old sessions' tag is rewritten to `custom`; the original data is covered by the backup |
+
+> **If you want "my earlier official sessions to appear in the unified list too," you must opt in by checking this box.** Otherwise you'll run into "scenario A" in the reference table below—the old sessions look "gone," when in fact they're just sitting in the original drawer.
+
+Click "Cancel" or click outside the dialog: the switch flips straight back to off and nothing happens.
+Click "I understand, enable": the switch is saved as on, and CC Switch persists the configuration in the background (and runs the migration if you checked it).
+
+### Step 3 (only if you checked migration): how migration runs + data safety
+
+If you check "Also migrate existing official session history," CC Switch runs this procedure on your existing official sessions:
+
+```text
+For each official (openai tag) session file:
+   ① First copy the original file untouched into the backup directory   <- data now has its first safety net
+   ② Using "write a temp file -> replace the whole thing" atomic style,
+      change only the model_provider in the session_meta line at the header
+      from "openai" to "custom"                                          <- not a single byte of the conversation body is touched
+   ③ Update the index database state_5.sqlite to switch the tag in the same transaction
+```
+
+- **Backup location**: `~/.cc-switch/backups/codex-official-history-unify-v1/<timestamp>/`. Each migration produces one timestamped "generation directory," containing `jsonl/` (session copies), `state/` (index DB copy), and `meta.json` (recording which Codex directory this migration belongs to).
+- **What's changed**: only the value of the single field `model_provider`. Your conversation content, reasoning content, and all body text are **kept exactly as is**.
+- **What's deleted**: **nothing**. The backup is a "copy," the rewrite is an "atomic replacement of the same file," and at no point is any session or index deleted. The file is complete at every moment (either the old content or the new content, never empty or half-written).
+
+After a successful migration, these existing official sessions show up in the unified list. **At this moment your data is**: ① the original copy in the backup directory; ② in the active file, only the classification tag changed, the content intact.
+
+> **Note**: enabling and migration themselves **do not pop a success toast**. Migration runs as a side task on the backend during save; in the UI you'll only see the switch turn on. So "I didn't see a migration-success popup" is normal and does not mean failure.
+
+---
+
+## What happens when you disable it: step by step
+
+### Step 1: Flip the switch from on to off -> probe for backups -> a confirmation dialog pops up
+
+When disabling, CC Switch **first spends a moment probing whether there's a migration backup**, then pops up a confirmation dialog (so the disable dialog has a slight delay, which is normal). The text reads as follows (verbatim):
+
+- **Title**: Turn off unified session history
+- **Body**:
+
+  > After turning this off, the official subscription and third-party providers return to separate history lists. Sessions created while it was on cannot be attributed to a provider, so they stay in the third-party history and the official subscription will not see them.
+
+- **Checkbox** (shown conditionally): Restore the official sessions migrated at enable time back to the official history (exact restore from backup)
+- **Confirm button**: Turn off
+- **Cancel button**: Cancel
+
+> **Key point**: the body says the official subscription **will not see them**—**won't see**, not **delete**. The new sessions you chatted during the unified period are still fully present in the `custom` drawer; after disabling, the official side simply won't see them.
+
+**This restore checkbox is checked by default.** In other words, the default behavior is "restore the official sessions you migrated in back to the official history at the same time you disable." You only need to keep it checked and click "Turn off."
+
+If the checkbox **doesn't appear**, the system has determined there's no backup that needs restoring (either you never checked migration, or no backup was found)—in that case your existing official sessions were never touched, and turning off the switch returns them to the `openai` drawer on their own.
+
+### Step 2: How restore runs (precise flip-back per the backup ledger)
+
+If you keep the box checked and click "Turn off," CC Switch's restore flow goes like this:
+
+```text
+① First copy the current state once more into a separate restore-backup directory
+   ~/.cc-switch/backups/codex-official-history-unify-restore-v1/<timestamp>/
+   (restore itself backs up first, so restore won't lose data either)
+② Comb through all migration backup generations, find the session ids "whose tag was originally openai," and assemble a "ledger"
+③ Only for sessions that are [both in the ledger AND currently still custom], change the tag back to "openai"
+```
+
+Note the **dual condition** in step ③—it must be in the ledger (proving it really was migrated from the official side) AND currently still `custom` (showing you haven't manually changed it). Only when both conditions hold does it get flipped back. This guarantees the restore is both precise and free of collateral damage.
+
+**At this moment your data is**: the migrated-back official sessions have their tag changed back to `openai` and reappear in the official list; meanwhile both the migration backup and the restore backup copies are still on disk.
+
+### Step 3: Read the toast, confirm the result
+
+Only the "disable + check restore" path pops a result toast. The toasts you may see (verbatim):
+
+| Toast you see | Meaning |
+|---|---|
+| **Official session history restored from backup ({{files}} session files, {{rows}} index rows)** | Restore succeeded. `{{files}}` / `{{rows}}` show the actual numbers |
+| **No restorable migration backup for the current Codex directory** | Nothing to restore (**does not mean data is lost**, see scenario E in the reference table) |
+| **Unified session history was re-enabled; restore skipped** | You turned the switch back on while restore was queued, so the system deliberately abandoned the restore (see scenario F) |
+| **Failed to restore official session history, please try again** | The restore process errored; just retry, the data is not corrupted |
+| **Save failed, please try again** | The disable save itself failed; in this case **restore is never triggered** and the switch flips back to its original position |
+
+> **A thoughtful safety design**: if the "disable the switch" save fails, CC Switch **never runs the restore**. Otherwise you'd end up in a torn state of "switch still on, but sessions flipped back to the openai bucket." When the save fails, the switch **automatically flips back to its original position**, so you won't be stuck in a fake state of "looks off but didn't actually save."
+
+---
+
+## "I feel like my sessions are gone?" symptom reference table
+
+The six scenarios below are the situations where users most easily believe "sessions are gone." **The truth in every one is: the data is intact, it just moved drawers or is temporarily out of sight.** Use this table to locate your symptom first, then read the detailed explanation below.
+
+| Scenario | What you see | The data truth | One-line fix |
+|---|---|---|---|
+| **A** Didn't check migration | Old official sessions not in the unified list | All present, still carry the `openai` tag | Re-enable and check migration, or turn off the switch |
+| **B** Cross-provider resume fails | Can't resume / errors out | Files intact, the ciphertext just can't be decrypted across backends | Resume on the original provider; to only read content, read the jsonl directly |
+| **C** Proxy takeover / injection refused | No migration and no restore | Migration was safely skipped, files untouched | Exit takeover -> restart and retry; or just turn off the switch |
+| **D** New sessions didn't return to official after restore | New sessions from the unified period aren't on the official side | They're in the `custom` drawer, untouched by design | Switch to a third-party provider to see them |
+| **E** Toast "no restorable backup" | Restore "failed" | Usually nothing was ever migrated, sessions are in the original drawer | Turn off the switch and the official sessions reappear automatically |
+| **F** Toast "switch was re-enabled, restore skipped" | Restore refused | Prevents a torn data state, nothing was changed | Fully turn off the switch first, then restore |
+
+### Scenario A: You enabled the switch but didn't check migration -> old official sessions "disappear"
+
+**Symptom**: you turned on the unified switch, but didn't check "Also migrate existing official session history" in the enable dialog (it's unchecked by default). After enabling, your earlier official sessions seem to be gone from the list.
+
+**The truth**: 100% of your data is present, not a single line moved. The switch only takes effect on official sessions "created after enabling"; your official sessions from **before** enabling still carry the `openai` tag and sit untouched in `~/.codex/sessions/`. You're now on the `custom` drawer, so naturally you can't see the old sessions left in the `openai` drawer—that's the entire reason for the "apparent disappearance."
+
+**What to do** (pick either):
+1. **Re-enable the switch and check "Also migrate existing official session history,"** which moves the old sessions to the `custom` drawer and they immediately appear in the unified list (automatic backup before the rewrite).
+2. **Or simply turn off the unified switch**, the official side runs on the `openai` drawer again, and the old sessions reappear right where they were.
+
+### Scenario B: Cross-provider resume of an old session fails -> you think "this session is broken / gone"
+
+**Symptom**: after unification, the list shows an old session chatted with "another provider." You switch to your current provider and click "Resume," but it errors out or can't connect.
+
+**The truth**: the session file is intact; what's lost is not data, it's "cross-backend decryption ability." A Codex session stores an encrypted block of reasoning content `encrypted_content`, and **this ciphertext can only be decrypted by the backend that originally generated it**. Using provider B to resume a session generated by provider A means B can't decrypt A's ciphertext -> resume fails. This is **a design limitation of upstream Codex (by design)** and has nothing to do with whether CC Switch touched the file. The text content of the session is readable at any time.
+
+> This is the **only "looks like a real problem" genuine exception** in this whole guide—but note: it just means **you can't resume (can't generate a new turn)**, and **the original file is still fully present**, the conversation text readable at any time.
+
+**What to do**:
+- **Resume with "the provider that originally created this session,"** so it can decrypt normally and connect.
+- Just want to read the history without continuing? Read that session's `.jsonl` file directly (commands at the end).
+- Rule of thumb: **cross-provider is better suited to "starting a new session"; resume old sessions on their original provider whenever possible.**
+
+### Scenario C: You enabled the switch and checked migration, but migration was silently skipped -> you think "migration lost the sessions"
+
+**Symptom**: you enabled the switch and checked migration, but the old official sessions neither entered the unified list nor could be restored when you turned the switch off (or the restore checkbox didn't even appear in the disable dialog, see scenario E). You suspect migration lost the sessions during the process.
+
+**The truth**: migration **never ran**, so it couldn't have lost anything—not a single character of your sessions was changed. CC Switch has a safety gate before migration: it checks whether Codex's live config (`~/.codex/config.toml`) is **actually** routed to the shared `custom` drawer right now, and only migrates if the routing truly went there. The following two situations are judged "not yet unified" (internal reason code `live_not_unified`), so CC Switch **deliberately skips the migration, preserves your switch and migration intent, and migrates later once the conditions are met**:
+
+- **During proxy takeover**: CC Switch's proxy has taken over the live config, and the live config during takeover doesn't carry the unified routing marker.
+- **Injection refused**: your `config.toml` already has a manually specified `model_provider`, or there's already a differently-shaped `[model_providers.custom]` table (possibly with a third-party address). To avoid incorrectly routing official traffic to a third-party backend, CC Switch would rather not inject and not migrate.
+
+Skipping migration = touching no session files. **No migration means nothing moved, so there's nothing to lose.** This is "safe deferral," not "failure with data loss."
+
+**What to do**:
+- Exit proxy takeover -> **restart CC Switch**: on startup it automatically retries migration (your migration intent is preserved the whole time).
+- Check `~/.codex/config.toml`: if there's a conflicting route you wrote by hand, clean up the conflict before enabling the switch.
+- If you'd rather not bother: just turn off the switch, the official sessions still display normally on the `openai` drawer, completely intact.
+
+### Scenario D: You turned off the switch and restored, but "the new sessions chatted during the unified period" didn't return to official -> you think "the new sessions are gone"
+
+**Symptom**: during the unified period, you chatted a few more new sessions with the official account. Later you turned off the switch, checked restore, and after restoring you find those new sessions didn't return to the official drawer.
+
+**The truth**: this is **intentional** design; the new sessions are perfectly fine in the `custom` drawer, visible and resumable. Restore is based on "the backup ledger from migration time"—**only sessions that were originally migrated in from the `openai` drawer** are recorded in the backup and get precisely flipped back to `openai`. The sessions you **created during the unified period** are in no backup ledger; and after unification both official and third-party use the `custom` tag, so **CC Switch can't tell whether a new session was chatted with the official account or a third-party**. To avoid wrongly stuffing third-party sessions into the official history, the product decision is: these new sessions all stay in the `custom` (third-party) history and are never moved automatically. The disable dialog's text says this explicitly too—"Sessions created while it was on cannot be attributed to a provider, so they stay in the third-party history."
+
+**What to do**:
+- Switch to any third-party provider (the `custom` drawer) to see these sessions in the history list.
+- To read content, read the `.jsonl` directly; to resume, follow scenario B's rule (go back to the backend that originally generated it).
+- If you really want to manually return **one specific** session to official: there's currently no automatic button (deliberately omitted, to avoid misjudging the direction). Advanced users can, **after backing up** that file first, manually change `model_provider` in the `session_meta` of the first line of its `.jsonl` from `custom` back to `openai` (an advanced operation; always make a copy before editing).
+
+### Scenario E: Restore toast "No restorable migration backup for the current Codex directory" -> you think "restore failed = data is gone"
+
+**Symptom**: you checked restore when turning off the switch, and got the toast "No restorable migration backup for the current Codex directory." You panic: restore failed, is the data completely gone?
+
+**The truth**: "nothing to restore" ≠ "data is lost." On the contrary, it's usually because **there was no migration that needed restoring**. Common reasons:
+
+- **You never checked "migrate existing official sessions" in the first place**: with no migration, there's naturally no migration backup and no sessions to flip back. Your old official sessions have been in the `openai` drawer all along and reappear after you turn off the switch (same as scenario A). (In this case, the disable dialog may **not even show the restore checkbox**—because the system can't find any backup.)
+- **You've already restored once**: the session tags have all been flipped back to `openai`, so clicking again naturally finds "no targets still in custom to restore"—this is **idempotent protection, not failure**.
+- **You switched Codex directories**: restore only recognizes the backup ledger belonging to the **current** directory; switch directories and it can't find the old directory's ledger. Just switch the directory back.
+
+In all three cases, no session was deleted.
+
+**What to do**: use the end-of-guide commands to count the total session files in `~/.codex/sessions/` and confirm the files are all there; then check whether `~/.cc-switch/backups/` contains a `codex-official-history-unify-v1` directory—if even this directory is absent, you never triggered a migration and the sessions have been in their original drawer all along.
+
+### Scenario F: Restore refused, toast "Unified session history was re-enabled; restore skipped"
+
+**Symptom**: you turned off the switch -> checked restore -> but you were quick and immediately turned the switch back on, then saw the toast "Unified session history was re-enabled; restore skipped."
+
+**The truth**: this is a safeguard against putting your data into a "torn" state, and again no sessions are lost. The restore action is "flip session tags from `custom` back to `openai`," but if the switch is on again at this moment, the live config is routing to `custom`—flipping history back to `openai` on one side while new sessions land in `custom` on the other would artificially tear sessions in two. So when CC Switch detects "the switch is on again," it **deliberately abandons this restore and changes nothing**. Sessions stay as they are, with no deletion or corruption.
+
+**What to do**: to truly restore, **turn the switch off and keep it off** (don't immediately turn it back on), then do disable + check restore; to keep things unified, don't restore, and let the sessions stay in the `custom` shared drawer for normal use.
+
+**The overriding principle: CC Switch's unify / migrate / restore only ever changes a single tag field in a session, and automatically backs up before every rewrite. It never deletes your conversations. Out of sight ≠ gone—look in the other drawer, or use the commands below to confirm with your own eyes.**
+
+---
+
+## Verify by hand: your session files are still on disk (the most important section)
+
+No amount of text beats seeing it for yourself. Below are the **real paths** (taken from the CC Switch source) and how to view session files and backup directories on different systems. **The whole process is read-only and changes nothing; you're strongly encouraged to try it by hand.**
+
+### The simplest way: open it directly in a file manager (no command line at all)
+
+- **macOS (Finder)**: press `Cmd + Shift + G`, paste `~/.codex/sessions` and hit Enter to see a pile of `.jsonl` session files and their modification times; for the backup directory paste `~/.cc-switch/backups`.
+- **Windows (File Explorer)**: paste `%USERPROFILE%\.codex\sessions` into the address bar and hit Enter to see the session folders and the `.jsonl` files inside; for the backup directory paste `%USERPROFILE%\.cc-switch\backups`.
+
+**As long as you can see a batch of `.jsonl` files here, that proves your session data is intact on disk.** The file count and modification times are more intuitive than any amount of text.
+
+### Where exactly your session / history files live
+
+| Content | Real path | Notes |
+|---|---|---|
+| **Session body (the core)** | `~/.codex/sessions/` (includes date-based subdirectories, recursive) | One `.jsonl` text file per session—**this is your conversation content** |
+| **Archived sessions** | `~/.codex/archived_sessions/` | Also `.jsonl` |
+| **Session index database** | `~/.codex/state_5.sqlite` | The `model_provider` column of the `threads` table is the "drawer tag"—**this is the actual classification source the resume list reads** |
+| **Migration backup** (auto-created when migration is enabled) | `~/.cc-switch/backups/codex-official-history-unify-v1/<timestamp>/` | Contains `jsonl/`, `state/`, `meta.json` |
+| **Restore backup** (auto-created when you restore) | `~/.cc-switch/backups/codex-official-history-unify-restore-v1/<timestamp>/` | A safety copy taken before restore |
+
+> **Note**: if you've changed the Codex directory in CC Switch, or set `sqlite_home` in `config.toml`, replace `~/.codex` above with your actual directory. Below, `~` = your user home directory.
+
+### macOS / Linux commands
+
+**1. Count the total number of session files (this is the hard evidence of "nothing lost")**
+
+```bash
+# Count the total number of session files -- as long as this number matches your expectation, the data is all there
+find ~/.codex/sessions ~/.codex/archived_sessions -name '*.jsonl' 2>/dev/null | wc -l
+
+# Show the 10 most recently modified session files
+find ~/.codex/sessions -name '*.jsonl' 2>/dev/null -print0 \
+  | xargs -0 ls -lt 2>/dev/null | head -10
+```
+
+**2. (Auxiliary) See how many sessions are in each "drawer"**
+
+```bash
+# Number of session files in the official drawer (openai)
+grep -rlE '"model_provider"[[:space:]]*:[[:space:]]*"openai"' ~/.codex/sessions 2>/dev/null | wc -l
+
+# Number of session files in the unified drawer (custom)
+grep -rlE '"model_provider"[[:space:]]*:[[:space:]]*"custom"' ~/.codex/sessions 2>/dev/null | wc -l
+
+# See the tag distribution at a glance
+grep -rhoE '"model_provider"[[:space:]]*:[[:space:]]*"[^"]*"' ~/.codex/sessions 2>/dev/null | sort | uniq -c
+```
+
+> **Important note, don't let this step scare you**: **early versions of Codex did not write the `model_provider` field into the `.jsonl`**, so these old official sessions **can't be counted** by the grep above—but they're still classified as `openai` in the index database `state_5.sqlite` and still show up in the resume list. So **judge "nothing lost" by the total file count from step 1**—the per-drawer grep is only there to help you understand the classification, and counting fewer than the total file count is **completely normal** and never means "a batch was lost."
+
+**3. (Advanced) Query the index database `state_5.sqlite`—the classification the resume list actually reads**
+
+```bash
+# Requires sqlite3 to be installed; skip if you don't have it
+sqlite3 ~/.codex/state_5.sqlite \
+  "SELECT COALESCE(model_provider,'<empty>'), COUNT(*) FROM threads GROUP BY 1;"
+```
+
+> This `threads` table is the actual classification source Codex's resume list reads; the `openai` row count ≈ the number of sessions you can see in your official drawer. It may not match step 2's jsonl grep—the reason is exactly what's described above: "old sessions don't write the jsonl field, but they're still openai in the index database." A mismatch between the two is not an anomaly.
+
+**4. Read the content of a specific session directly (confirm the conversation text is still there)**
+
+```bash
+# Replace <filename> with one of the .jsonl paths listed by ls above
+python3 -m json.tool < "<filename>.jsonl" 2>/dev/null | head -50
+
+# Or just open it in an editor (plain text)
+open -e "<filename>.jsonl"      # macOS
+```
+
+**5. Look at CC Switch's backup directory (proof that a copy was kept before migration / restore)**
+
+```bash
+ls -la ~/.cc-switch/backups/codex-official-history-unify-v1/ 2>/dev/null
+ls -la ~/.cc-switch/backups/codex-official-history-unify-restore-v1/ 2>/dev/null
+```
+
+### Windows commands (PowerShell)
+
+The session directory is usually at `C:\Users\<your username>\.codex\`, and backups at `C:\Users\<your username>\.cc-switch\backups\`.
+
+```powershell
+# 1. Total number of session files (hard evidence of "nothing lost")
+(Get-ChildItem "$env:USERPROFILE\.codex\sessions","$env:USERPROFILE\.codex\archived_sessions" -Recurse -Filter *.jsonl -ErrorAction SilentlyContinue).Count
+
+# 2. The 10 most recently modified sessions
+Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
+  Sort-Object LastWriteTime -Descending | Select-Object -First 10 FullName,LastWriteTime
+
+# 3. (Auxiliary) How many session files in the official (openai) / unified (custom) drawers
+(Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
+  Select-String -Pattern 'model_provider"\s*:\s*"openai"' -List).Count
+(Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
+  Select-String -Pattern 'model_provider"\s*:\s*"custom"' -List).Count
+
+# 4. Look at the backup directories
+Get-ChildItem "$env:USERPROFILE\.cc-switch\backups\codex-official-history-unify-v1" -ErrorAction SilentlyContinue
+Get-ChildItem "$env:USERPROFILE\.cc-switch\backups\codex-official-history-unify-restore-v1" -ErrorAction SilentlyContinue
+```
+
+> Same reminder: the step-3 grep counting **fewer** than the total file count is normal (old sessions don't write that field); judge "nothing lost" by the **total file count** from step 1.
+
+---
+
+## Advanced mechanism appendix (for users who want to truly understand how it works)
+
+### 1. The bucketing mechanism (the essence of the drawers)
+
+Codex's resume / history list filters by the currently active `model_provider` id with **exact string matching**. The **first line** of a session's `.jsonl` file is a `type:"session_meta"` record whose `payload.model_provider` is the drawer that session belongs to (`grep -rl` counts a file as long as the tag appears once anywhere in it, so no line-by-line parsing is needed; sessions from old versions that didn't write the field can't be counted). What actually drives the resume list is the `threads.model_provider` column of the index database `state_5.sqlite`. When `config.toml` has no explicit `model_provider`, the official subscription falls into the built-in default id `openai`; all of CC Switch's third-party providers uniformly use `custom`.
+
+### 2. What the switch does (injection, lives only in live)
+
+When enabled, CC Switch injects the following into the official live `config.toml`:
+
+```toml
+model_provider = "custom"
+
+[model_providers.custom]
+name = "OpenAI"
+requires_openai_auth = true
+supports_websockets = true
+wire_api = "responses"
+```
+
+Every field has a purpose: `requires_openai_auth = true` keeps authentication going through the ChatGPT login in `auth.json`, with the base_url defaulting back to the official Codex backend; `name = "OpenAI"` lets Codex's official feature gates (web search, remote compaction, etc.) keep matching; `supports_websockets = true` restores the capability that custom entries lose by default; `wire_api = "responses"` uses the official responses protocol. **The net effect is: authentication is unchanged, only the bucket name changed.**
+
+**Key invariant: this injection can only exist in the live `config.toml`, and is never written into the database's stored configuration.** When you switch away from the official provider and write live back to the database, CC Switch strips this injection precisely (it strips only when the shape exactly matches the injected artifact; a third-party-customized `custom` table is kept as is). Precisely because of this, "turning off the switch + switching once" fully restores live, and the database always holds your original clean official configuration—this is the cornerstone of the whole switch's reversibility.
+
+### 3. The two refusal gates for injection (corresponding to scenario C)
+
+- `config.toml` already has an explicit `model_provider` -> don't override the user's route;
+- A differently-shaped `[model_providers.custom]` table already exists (possibly with a third-party `base_url`) -> refuse injection, otherwise ChatGPT OAuth traffic would be routed to the wrong backend.
+
+When injection is refused, live is not unified, and the migration gate (checking whether live's `model_provider` equals `custom` after trim) judges `live_not_unified` -> skip migration, preserve intent, and do it later on the next startup retry. This is "safe deferral," not "failure with data loss."
+
+### 4. The three session classes (which determine the migration / restore boundary)
+
+- **Class A**: existing official sessions migrated in at enable time—the backup is the ledger, and they can be precisely restored back to `openai`;
+- **Class B**: created during the unified period—in no backup, and official / third-party can't be distinguished, so they're **never moved automatically** (stay `custom`);
+- **Class C**: pure third-party history from before enabling—never touched.
+
+### 5. The safety of migration / restore (data is never truly deleted; where the guarantee comes from)
+
+Four layers of design jointly guarantee that under **all paths, normal and abnormal**, the original session data is never truly deleted.
+
+- **Only change the field, never the body**: migration / restore only switch the `model_provider` value in session metadata between `openai` and `custom`; conversation content, `response_item`, and `encrypted_content` are all kept exactly as is.
+- **Always copy a backup before a rewrite**: jsonl uses file copy, the state DB uses a full SQLite copy, both stored in a timestamped generation directory. Migration backups live in `codex-official-history-unify-v1/`, restore backups in the separate `codex-official-history-unify-restore-v1/`—the two are kept apart to keep the ledger clean.
+- **Only move, never delete + atomic writes**: all jsonl rewrites go through "temp file + whole-file replacement," and the state DB goes through a transactional `UPDATE`, with no deletion of any session or index at any point. The file is complete at every moment.
+- **Pessimistic skip + idempotent and retryable**: when buckets are inconsistent (`live_not_unified`), it would rather not migrate; a single process lock serializes migration and restore to avoid "startup retry / post-save background task / disable-time restore" concurrently rewriting the same batch of files in both directions; the completion marker is bound to the Codex directory and written conditionally to prevent missed migrations; restore uses the "in the ledger + currently still custom" dual condition to prevent wrong changes. Restore scans the union of all backup generations, so even after many switch cycles it can still restore early-migrated sessions; a repeated restore returns `nothing_to_restore`, which is idempotent protection rather than failure.
+
+### 6. Cross-backend encrypted_content (corresponding to scenario B)
+
+The reasoning ciphertext inside a session can only be decrypted by the backend that generated it; upstream Codex by design does not support cross-backend decryption. This is the root cause of "resume failure" and has nothing to do with file integrity—the session `.jsonl` sits fully on disk and `encrypted_content` is intact too. Switching back to the original provider to resume, or starting a new session, both work fine.
+
+---
+
+## References
+
+- [Keep Codex Remote Control and Official Plugins While Using Third-Party APIs: CC Switch Setup Guide](./codex-official-auth-preservation-guide-en.md)
+- [Using DeepSeek-Style Chat APIs in Codex: CC Switch Local Routing Guide](./codex-deepseek-routing-guide-en.md)
+- The "Codex App Enhancements" section in the CC Switch user manual
+
+---
+
+**One last word for you**: what you see as "sessions disappeared / resume failed" is essentially **the session being moved to another history list (drawer), or the other backend being unable to decrypt the old reasoning content**; the files always sit untouched in `~/.codex/sessions/` (and `state_5.sqlite`). Checking "restore from backup" when you turn off the switch precisely flips the official sessions you migrated in back to the official list; and even if you don't restore, both the original `.jsonl` files and the backup copies under `~/.cc-switch/backups/codex-official-history-unify-*/` are all still there—**the data is never truly lost.**
@@ -0,0 +1,467 @@
+# Codex セッション履歴の統一: 機能紹介と利用ガイド（CC Switch）
+
+> 対象バージョン: CC Switch v3.16.x 以降。本記事は現在のコードをもとに整理しており、コマンドとパスはご自身で検証できます。例示には匿名化したデータを使用しており、実際のセッション内容や API Key は含まれていません。
+
+## この機能とは何か
+
+「Codex セッション履歴を統一」は、CC Switch v3.16.x が Codex 向けに新しく追加したスイッチです。その場所は **設定 → 一般 → 「Codex アプリ拡張」グループ** の中にあります（「Codex アプリ拡張」はこのグループの見出しで、スイッチ自体は「Codex セッション履歴を統一」という名前です）。オンにすると、**公式サブスクリプション（ChatGPT ログイン / OpenAI API Key）のセッションが、CC Switch で管理するすべてのサードパーティプロバイダーのセッションと同じ履歴 / セッション再開リストに表示されます**——もう、互いに見えない 2 つのリストに分断されることはありません。
+
+## どんな問題を解決するのか
+
+Codex は「プロバイダーのラベル」（`model_provider` というフィールド）でセッションを分類しており、しかも **セッション再開 / 履歴リストには、現在アクティブなプロバイダーと同じラベルのセッションしか表示しません**。そのため、セッションは自然と 2 つの「引き出し」に分けられてしまいます。
+
+- 公式サブスクリプションのセッションは、Codex 内蔵の **`openai`** ラベルに分類されます。
+- CC Switch が管理するすべてのサードパーティプロバイダーは、**`custom`** ラベルに分類されます。
+
+2 つの引き出しは互いに見えません。**公式とサードパーティを頻繁に切り替えている** 場合、この分断に遭遇します——「さっき公式で話したセッションが、サードパーティに切り替えたら履歴リストから消えた」というように。実際にはなくなっておらず、別の引き出しに分けられただけです。この分断は、セッションが失われたと誤解させやすいうえに、すべてのセッションを 1 か所でまとめて振り返ったり再開したりするのにも不便です。
+
+**このスイッチは、まさにこの分断を解消するためのものです**。公式サブスクリプションも `custom` ラベルで動作させることで、公式とサードパーティのセッションが同じリストに統合され、探すのも再開するのも 1 か所で済みます。
+
+> ✅ **本記事全体を貫く重要な前提を、まず覚えておいてください**: この機能（統一 / 移行 / 復元）は **常にセッション記録内のあの分類ラベル `model_provider` 1 つだけを書き換え、しかも毎回書き換える前に自動で元ファイルをバックアップします**。あなたの会話を 1 文たりとも削除・消去・上書きすることはありません。ですので、本記事の後半で「あるセッションが見えなくなった」とあっても、そのほとんどは「別の引き出しに分けられた」だけであり、「データが消えた」わけではありません——本当に心配なときは、[症状対照表](#会話が消えた症状対照表) と [自分の目でファイルが残っていることを確認する](#自分の目で確認-セッションファイルはディスク上に残っている最重要セクション) を直接ご覧ください。
+
+## 動作原理（一言版）
+
+これを **2 つの引き出し + 自動バックアップ** と考えてください。
+
+- デフォルトでは、公式セッションは `openai` の引き出しに、サードパーティのセッションは `custom` の引き出しにあり、互いに見えません。
+- スイッチは **公式も `custom` の引き出しを使うように** させ、2 つの引き出しを 1 つの共有リストに統合します。
+- **既存の公式の古いセッション** も一緒に共有の引き出しへ「移す」ことを選べます（この操作を **移行** と呼びます。任意で、能動的にチェックを入れる必要があります）。そして **いかなる移動の前にも、まずコピーをバックアップ** するので、プロセス全体が **可逆** です。
+- **認証はまったく影響を受けません**——公式サブスクリプションは引き続きあなたの ChatGPT ログインを使い、引き続き公式バックエンドを経由します。変わるのはセッションの分類ラベルだけです。
+
+完全な仕組み（何が注入されるのか、なぜ可逆なのか、移行 / 復元がどうやってデータ消失を防ぐのか）は、後述の [コア・メンタルモデル](#コアメンタルモデル-2-つの引き出し--自動バックアップ) と巻末の [応用原理付録](#応用原理付録仕組みを本当に理解したい人向け) をご覧ください。
+
+## 使い方（クイック）
+
+1. **有効化**: 設定 → 一般 → Codex アプリ拡張 → 「Codex セッション履歴を統一」をオン → ダイアログで「既存の公式セッション履歴も移行する」にチェックを入れるか決める（**以前** の公式セッションも統一リストに合流させたいならチェックを入れる。今後だけ統一したいならチェックを入れない）→ 確定。詳しくは [有効化したとき何が起きるか](#有効化したとき何が起きるか-ステップ別解説) を参照。
+2. **無効化**: 同じスイッチをオフにする → ダイアログで「バックアップから正確に復元する」のチェックを保持（デフォルトでチェック済み）→ 確定すれば、移行した公式セッションを正確に公式リストへ戻せます。詳しくは [無効化したとき何が起きるか](#無効化したとき何が起きるか-ステップ別解説) を参照。
+3. **セッションが消えた気がする？** 慌てずに [症状対照表](#会話が消えた症状対照表) へ進んで症状から原因を特定し、[自分の目で確認](#自分の目で確認-セッションファイルはディスク上に残っている最重要セクション) セクションのコマンドで、ファイルがすべて残っていることを自分の目で確かめてください。
+
+---
+
+## コア・メンタルモデル: 2 つの引き出し + 自動バックアップ
+
+この機能を理解するには、**引き出し** と **バックアップ** の 2 つだけ覚えれば十分です。
+
+### 引き出し: Codex はどうやってセッションを分類するか
+
+Codex セッションを 1 つ開くたびに、Codex はセッションファイルの先頭に `model_provider` というラベルを記録し、「このセッションはどのプロバイダーで話したか」を示します。Codex の **セッション再開 / 履歴リストは、現在アクティブなこのラベルで正確にフィルタリングされます**——「今あなたが使っているプロバイダー」と同じラベルのセッションだけが表示されます。
+
+- 公式サブスクリプション（ChatGPT ログイン / OpenAI API Key）のセッションのラベルは、内蔵の **`openai`** です。
+- CC Switch が管理するすべてのサードパーティプロバイダーは、一律にラベル **`custom`** を使います。
+
+そのためデフォルトでは、公式セッションとサードパーティセッションは生まれつき互いに見えません——2 つの異なる引き出しにあるからです。これは **Codex 自身の設計** であり、CC Switch が何かをなくしたわけではありません。
+
+```text
+デフォルト状態（統一スイッチをオンにしていない）：
+   ┌──────────────────────┐     ┌──────────────────────────────────┐
+   │  openai の引き出し   │     │  custom の引き出し               │
+   │  （公式セッション）  │     │  （サードパーティのセッション）  │
+   └──────────────────────┘     └──────────────────────────────────┘
+       ▲                            ▲
+     公式のときは                 サードパーティのときは
+     こちらだけ表示               こちらだけ表示
+
+   （2 つの引き出しは互いに見えない）
+```
+
+**「Codex セッション履歴を統一」スイッチがすることは、公式サブスクリプションも `custom` ラベルで動作させ、2 つの引き出しを 1 つに統合することです**。その結果、公式セッションとサードパーティセッションが同じセッション再開リストに表示されます。注意してほしいのは、**認証は変わらない** ということです——あなたの公式サブスクリプションは引き続き ChatGPT ログインを使い、引き続き公式バックエンドを経由します。変わるのはセッションの「分類ラベル」が `openai` から `custom` になることだけです。
+
+```text
+統一スイッチをオンにした後：
+   ┌────────────────────────────────────────────────┐
+   │              custom 共有引き出し               │
+   │  公式セッション ＋ サードパーティのセッション  │
+   │     （同じ履歴 / 再開リストに表示される）      │
+   └────────────────────────────────────────────────┘
+```
+
+### バックアップ: ラベルを変更する前に必ずコピーを取る
+
+「引き出しの統合」では、一部の公式セッションのラベルを `openai` から `custom` に変更する必要があります（この操作を **移行** と呼び、これは **任意で、あなたが能動的にチェックを入れる必要があります**）。そして **どの書き換えの前にも、CC Switch はまず元ファイルをそのままコピー** して、ここに保存します。
+
+```text
+~/.cc-switch/backups/codex-official-history-unify-v1/<時間スタンプ>/
+```
+
+このバックアップが、後の「バックアップから正確に復元する」ための唯一の拠り所です。これによってプロセス全体が **可逆** になります——いつでもスイッチをオフにして、移行した公式セッションを正確に `openai` の引き出しへ戻せます。
+
+この 2 つの言葉——**引き出し**（セッションは分類が変わるだけ）、**バックアップ**（変更前に必ずコピー）——を覚えておけば、以降の内容はすべて簡単に理解できます。
+
+---
+
+## 有効化したとき何が起きるか: ステップ別解説
+
+### Step 1: スイッチを見つける
+
+```text
+設定 → 一般 → Codex アプリ拡張
+```
+
+「Codex アプリ拡張」のセクションには 2 行のスイッチがあり、**2 行目**（青い履歴アイコン）が本ガイドの主役です。
+
+> **Codex セッション履歴を統一**
+
+その下には説明文があります（逐語）。
+
+> オンにすると、公式サブスクリプションも共有の custom プロバイダー ID で動作し、公式とサードパーティのセッションが同じ履歴リストに表示されます。既存の公式セッションの移行も選択できます（移行前に自動バックアップ）。オフにする際はバックアップから復元できます。注意：プロバイダーをまたいで古いセッションを再開すると、encrypted_content の推論内容を相手のバックエンドが復号できず、再開に失敗する場合があります。
+
+> **注意**: この説明文には、すでに 3 つのことが予告されています——同じリストに表示される、移行を選べて自動バックアップされる、プロバイダーをまたいだ再開は「失敗する場合がある」。ここでの「再開に失敗する」は **続けられない、新しいターンを生成できない** という意味であり、「記録が消える」ではありません。これこそ、この後で重点的に解きほぐす核心的な誤解です。
+
+### Step 2: スイッチをオフからオンに切り替える → 確認ダイアログが表示される
+
+スイッチをオンに切り替えると、CC Switch は **すぐには保存せず**、まず確認ダイアログを表示します。ダイアログの文言は次のとおりです（逐語）。
+
+- **タイトル**: Codex セッション履歴を統一
+- **本文**:
+
+  > オンにすると、公式サブスクリプションとサードパーティが同じセッション履歴リストを共有します。注意：プロバイダーをまたいで古いセッションを再開すると、encrypted_content を相手のバックエンドが復号できず失敗する場合があります。
+  >
+  > 既存の公式セッション履歴を共有リストへ移行することもできます（移行前に ~/.cc-switch/backups へ自動バックアップされ、オフにする際に復元を選択できます）。
+
+- **チェックボックス**: 既存の公式セッション履歴も移行する
+- **確認ボタン**: 理解しました、オンにする
+- **キャンセルボタン**: キャンセル
+
+**このチェックボックスはデフォルトでオフです。** これは重要な分岐点です。
+
+| あなたの選択 | 効果 | この時点でデータはどこにあるか |
+|---|---|---|
+| **チェックしない**（デフォルト） | ラベルを切り替えるだけ。**オンにした後に新規作成された公式セッションだけ** が `custom` の共有引き出しに入る | あなたが **オンにする前** の公式の古いセッションは、ラベルが `openai` のまま、その場で動かず、引き続き `~/.codex/sessions/` にある |
+| **チェックする** | ラベルの切り替えに加えて、**既存の公式の古いセッション** も `openai` の引き出しから `custom` の引き出しへ移行する | 古いセッションは **コピーしてバックアップ** された後、ラベルが `custom` に書き換えられる。元データはバックアップで保護される |
+
+> **「以前の公式セッションも統一リストに表示したい」なら、必ずこのチェックボックスを能動的にオンにしてください。** さもないと、下の対照表の「シナリオ A」に遭遇します——古いセッションが「消えた」ように見えますが、実際は元の引き出しに残っているだけです。
+
+「キャンセル」を押すか、ダイアログの外側をクリックすると、スイッチはそのままオフ状態に戻り、何も起きません。
+「理解しました、オンにする」を押すと、スイッチはオンとして保存され、CC Switch はバックグラウンドで設定をディスクに書き込みます（移行にチェックを入れていれば、移行を実行します）。
+
+### Step 3（移行にチェックを入れた場合のみ）: 移行はどう実行されるか + データの安全性
+
+「既存の公式セッション履歴も移行する」にチェックを入れた場合、CC Switch はあなたの公式の古いセッションに対して、次の一連の流れを実行します。
+
+```text
+公式（openai ラベル）の各セッションファイルについて：
+   ① まず元ファイルをそのままバックアップディレクトリへコピー          ← データの一次保険ができる
+   ② 「一時ファイルに書く → まるごと置換」という原子的な方法で、
+      先頭行 session_meta 内の model_provider を
+      "openai" から "custom" へ変更するだけ               ← 会話本文は 1 バイトも触らない
+   ③ インデックス DB state_5.sqlite も同じトランザクション内でラベルを変更
+```
+
+- **バックアップの場所**: `~/.cc-switch/backups/codex-official-history-unify-v1/<時間スタンプ>/`。移行のたびに、タイムスタンプ付きの「世代ディレクトリ」を生成し、その中に `jsonl/`（セッションのコピー）、`state/`（インデックス DB のコピー）、`meta.json`（この移行がどの Codex ディレクトリに属するかの記録）が含まれます。
+- **変更するもの**: `model_provider` というフィールドの値だけ。あなたの会話内容、推論内容、すべての本文は **そのまま保持** されます。
+- **削除するもの**: **何も削除しません**。バックアップは「コピー」、書き換えは「同一ファイルの原子的な置換」であり、全工程でセッションやインデックスを削除する操作は一切ありません。ファイルはいかなる時点でも完全です（古い内容か新しい内容かのどちらかであり、空や中途半端になることは決してありません）。
+
+移行が成功すると、これらの公式の古いセッションが統一リストに表示されます。**この時点でのあなたのデータ**: ① 元のコピーがバックアップディレクトリにある。② アクティブファイルは分類ラベルが変わっただけで、内容は無傷。
+
+> **注意**: 有効化と移行そのものは **成功通知を表示しません**。移行は保存時にバックエンドが付随的に実行するもので、UI 上ではスイッチがオン状態になったのが見えるだけです。ですので「移行成功のダイアログが見えなかった」のは正常であり、失敗を意味しません。
+
+---
+
+## 無効化したとき何が起きるか: ステップ別解説
+
+### Step 1: スイッチをオンからオフに切り替える → バックアップを探索 → 確認ダイアログが表示される
+
+無効化のとき、CC Switch はまず **一瞬かけて移行バックアップの有無を探索** し、それから確認ダイアログを表示します（そのため無効化のダイアログは少しだけ遅延しますが、これは正常です）。文言は次のとおりです（逐語）。
+
+- **タイトル**: セッション履歴の統一をオフにする
+- **本文**:
+
+  > オフにすると、公式サブスクリプションとサードパーティはそれぞれ独立した履歴リストに戻ります。オン期間中に作成されたセッションは提供元を判別できないため、サードパーティの履歴に残り、公式サブスクリプションからは見えなくなります。
+
+- **チェックボックス**（条件付き表示）: オンにした際に移行した公式セッションを公式履歴へ復元する（バックアップから正確に復元）
+- **確認ボタン**: オフにする
+- **キャンセルボタン**: キャンセル
+
+> **ポイント**: 本文が言っているのは「公式サブスクリプションからは **見えなくなる**」——**見えなくなる** であり、**削除される** ではありません。オン期間中に新たに話したセッションは、引き続き `custom` の引き出しに完全な形で残っており、オフにした後で公式側から見えなくなるだけです。
+
+**この復元チェックボックスはデフォルトでオンです。** つまりデフォルトの動作は「オフにすると同時に、移行した公式セッションを公式履歴へ正確に復元する」です。チェックを保持したまま「オフにする」を押すだけで構いません。
+
+チェックボックスが **表示されない** 場合は、復元が必要なバックアップがないとシステムが判断したことを意味します（移行に一度もチェックを入れていない、またはバックアップを探索できない）——この場合、あなたの公式の古いセッションは一度も変更されていないので、スイッチをオフにすれば自然と `openai` の引き出しに戻ります。
+
+### Step 2: 復元はどう実行されるか（バックアップ台帳に従って正確に戻す）
+
+チェックを保持して「オフにする」を押すと、CC Switch の復元フローは次のようになります。
+
+```text
+① まず現在の状態を独立した復元バックアップディレクトリへもう一度コピー
+   ~/.cc-switch/backups/codex-official-history-unify-restore-v1/<時間スタンプ>/
+   （復元自体もまずバックアップするので、復元でもデータは失われない）
+② すべての移行バックアップ世代を走査し、「当初のラベルが openai」のセッション id を集めて「台帳」を作る
+③ 【台帳に含まれ、かつ現在もまだ custom】のセッションだけ、ラベルを "openai" に戻す
+```
+
+③ のステップの **二重条件** に注意してください——台帳に含まれていること（当初確かに公式から移行されたものだと証明できる）に加えて、現在もまだ `custom` であること（あなたが手動で変更していないことを示す）。両方の条件を満たして初めて戻します。これにより、復元は正確であり、かつ誤って手を加えることもありません。
+
+**この時点でのあなたのデータ**: 戻された公式セッションはラベルが `openai` に変わり、再び公式リストに表示されます。同時に、移行バックアップと復元バックアップの 2 つのコピーがどちらもディスク上に残っています。
+
+### Step 3: 通知を見て、結果を確認する
+
+「オフにする + 復元にチェック」というパスだけが結果通知を表示します。表示され得る通知（逐語）。
+
+| 表示される通知 | 意味 |
+|---|---|
+| **バックアップから公式セッション履歴を復元しました（セッションファイル {{files}} 件、インデックス {{rows}} 行）** | 復元成功。`{{files}}` / `{{rows}}` の部分には実際の数字が表示される |
+| **現在の Codex ディレクトリに復元可能な移行バックアップはありません** | 復元できる内容がない（**データが消えたわけではない**。対照表シナリオ E を参照） |
+| **統一セッション履歴が再度有効化されたため、復元をスキップしました** | 復元のキュー待ち中にスイッチを再びオンにしたため、システムが復元を自発的に取りやめた（対照表シナリオ F を参照） |
+| **公式セッション履歴の復元に失敗しました。もう一度お試しください** | 復元の途中でエラー。もう一度試せばよく、データは破壊されていない |
+| **保存に失敗しました。もう一度お試しください** | オフにするステップの保存そのものが失敗。この場合 **復元は決して起動されず**、スイッチは元の位置に戻る |
+
+> **気の利いた安全設計**: 「スイッチをオフにする」ステップの保存が失敗した場合、CC Switch は **復元を決して実行しません**。さもないと「スイッチはまだオン、しかしセッションは `openai` バケットに戻された」という矛盾状態が生じてしまいます。保存失敗時、スイッチは **自動で元の位置に戻る** ので、「オフに見えるのに実は保存されていない」という偽の状態に取り残されることはありません。
+
+---
+
+## 「会話が消えた？」症状対照表
+
+以下の 6 つのシナリオは、ユーザーが最も「セッションが消えた」と誤解しやすいケースです。**どれも真相は: データは無傷で、引き出しが変わったか一時的に見えないだけ。** まずこの表で症状から原因を特定し、その後で下の詳細説明を読んでください。
+
+| シナリオ | あなたが見るもの | データの真相 | 一言での解決法 |
+|---|---|---|---|
+| **A** 移行にチェックなし | 公式の古いセッションが統一リストにない | すべて存在、`openai` ラベルのまま | 移行にチェックを入れて再度オンにする、またはスイッチをオフにする |
+| **B** プロバイダーをまたいだ再開が失敗 | 続けられない / エラー | ファイルは無傷、暗号文がバックエンドをまたいで復号できないだけ | 元のプロバイダーで再開する。内容だけ見るなら jsonl を直接読む |
+| **C** プロキシ接管 / 注入が拒否 | 移行も復元もされない | 移行が安全にスキップされ、ファイルは未変更 | 接管を終了 → 再起動して再試行。またはスイッチを直接オフにする |
+| **D** 復元後、新セッションが公式に戻らない | オン期間中の新セッションが公式にない | `custom` の引き出しにある、設計上動かさない | サードパーティプロバイダーに切り替えれば見える |
+| **E** 「復元可能なバックアップなし」と通知 | 復元が「失敗」 | 通常はそもそも移行していない、セッションは元の引き出しにある | スイッチをオフにすれば公式セッションが自動で再表示 |
+| **F** 「スイッチが再度有効化、復元スキップ」と通知 | 復元が拒否 | データの矛盾を防止、何も変更していない | まずスイッチを完全にオフにしてから復元する |
+
+### シナリオ A: スイッチをオンにしたが移行にチェックを入れなかった → 公式の古いセッションが「消えた」
+
+**現象**: 統一スイッチをオンにしたが、有効化ダイアログの「既存の公式セッション履歴も移行する」にチェックを入れなかった（デフォルトでチェックなし）。オンにした後で見ると、以前の公式の古いセッションがすべてリストにないように見える。
+
+**真相**: データは 100% すべて存在し、1 行も動いていません。スイッチは「オンにした後に新規作成された」公式セッションにのみ効きます。あなたが **オンにする前** の公式の古いセッションはラベルが `openai` のままで、そっくりそのまま `~/.codex/sessions/` に横たわっています。今あなたがアクティブにしているのは `custom` の引き出しなので、`openai` の引き出しに残った古いセッションが見えないのは当然です——これが「消えたように見える」理由のすべてです。
+
+**どうするか**（いずれか）:
+1. **スイッチを再度オンにするときに「既存の公式セッション履歴も移行する」にチェックを入れ**、古いセッションを `custom` の引き出しへ移せば、すぐに統一リストに表示されます（書き換え前に自動バックアップ）。
+2. **または単に統一スイッチをオフにする** と、公式は再び `openai` の引き出しで動作し、古いセッションがその場で再表示されます。
+
+### シナリオ B: プロバイダーをまたいで古いセッションを再開して失敗 → 「このセッションが壊れた / 消えた」と思う
+
+**現象**: 統一した後、リストに「別のプロバイダー」で話した古いセッションが見える。今のプロバイダーに切り替えて「再開」を押すと、エラーになったり繋がらなかったりする。
+
+**真相**: セッションファイルは完全に無傷で、失われたのはデータではなく「バックエンドをまたいだ復号能力」です。Codex セッションには暗号化された推論内容 `encrypted_content` が保存されており、**この暗号文は、それを生成したバックエンドだけが復号できます**。B プロバイダーで A プロバイダーが生成したセッションを再開しようとすると、B は A の暗号文を解けない → 再開失敗。これは **上流の Codex の設計上の制約（by design）** であり、CC Switch がファイルに手を加えたかどうかとは無関係です。セッション内の文字内容はいつでも読めます。
+
+> これは本記事全体で **唯一「本当に問題が起きたように見える」実在の例外** です——ただし注意してください: これは **再開できない（新しいターンを生成できない）** だけであり、**元ファイルは依然として完全に存在し**、会話の文字はいつでも読めます。
+
+**どうするか**:
+- **「このセッションを最初に作成したプロバイダー」で再開すれば**、正常に復号でき、繋がります。
+- 履歴の内容だけ見たくて、続ける必要がない場合は、そのセッションの `.jsonl` ファイルを直接読んでください（巻末にコマンドあり）。
+- 経験則: **プロバイダーをまたぐ場合は「新規セッションを始める」のが向いており、古いセッションはできるだけ元のプロバイダーで再開してください。**
+
+### シナリオ C: スイッチをオンにし移行にもチェックを入れたが、移行が静かにスキップされた → 「移行がセッションをなくした」と思う
+
+**現象**: オンにして移行にチェックを入れたのに、公式の古いセッションは統一リストに入らず、スイッチをオフにして復元しようとしても「復元できるものがない」と通知される（または無効化ダイアログに復元チェックボックスがそもそも現れない。シナリオ E を参照）。あなたは、移行の過程でセッションをなくしたのではと疑います。
+
+**真相**: 移行はそもそも **実行されていない** ので、なくすことも不可能です——あなたのセッションは 1 文字も変更されていません。CC Switch には移行前に安全ゲートがあります: Codex の live 設定（`~/.codex/config.toml`）が、この時点で **本当に** 共有の `custom` 引き出しへルーティングされているかを確認し、本当にルーティングされている場合だけ移行します。以下の 2 つのケースでは「まだ統一されていない」と判定され（内部の理由コード `live_not_unified`）、**移行を自発的にスキップし、あなたのスイッチと移行の意思は保持し、条件が満たされてから移行します**。
+
+- **プロキシ接管中**: CC Switch のプロキシが live 設定を接管しており、接管中の live には統一ルーティングのマークが付いていません。
+- **注入が拒否された**: あなたの `config.toml` にすでに手動指定の `model_provider` があるか、形態の異なる `[model_providers.custom]` テーブルが既に存在する（サードパーティのアドレスが付いている可能性がある）。公式トラフィックを誤ってサードパーティバックエンドへルーティングするのを避けるため、CC Switch は注入も移行もしないことを選びます。
+
+移行のスキップ = どのセッションファイルにも触れない。**移行していない＝動かしていない、消えようがない。** これは「安全な先送り」であり、「失敗してデータが消えた」ではありません。
+
+**どうするか**:
+- プロキシ接管を終了 → **CC Switch を再起動**: 起動時に自動で移行を再試行します（あなたの移行の意思はずっと保持されています）。
+- `~/.codex/config.toml` を確認: 手動で書いた競合するルーティングがあれば、競合を整理してからスイッチをオンにします。
+- どうしても手間をかけたくない場合は、スイッチをオフにすれば、公式セッションは引き続き `openai` の引き出しで正常に表示され、まったく無傷です。
+
+### シナリオ D: スイッチをオフにして復元したが、「オン期間中に新たに話したセッション」が公式に戻らない → 「新セッションが消えた」と思う
+
+**現象**: 統一をオンにしている間、公式でさらにいくつかの新セッションを話した。後でスイッチをオフにし、復元にチェックを入れた。復元が終わると、その数本の新セッションが公式の引き出しに戻っていない。
+
+**真相**: これは **意図的な** 設計で、新セッションはちゃんと `custom` の引き出しにあり、見えるし続けられます。復元の拠り所は「移行時のバックアップ台帳」です——**当初 `openai` の引き出しから移行されてきたセッションだけ** がバックアップに記録されており、正確に `openai` へ戻されます。あなたが **オン期間中に新規作成した** セッションはどのバックアップ台帳にもありません。しかも統一後は公式もサードパーティも `custom` ラベルを使うので、**CC Switch はこの新セッションが公式で話したものかサードパーティで話したものか判別できません**。サードパーティのセッションを公式履歴に誤って押し込まないため、プロダクトの決定として、これらの新セッションは一律に `custom`（サードパーティ）の履歴に残し、決して自動で動かしません。無効化ダイアログの文言もこれを明示しています——「オン期間中に作成されたセッションは提供元を判別できないため、サードパーティの履歴に残ります」。
+
+**どうするか**:
+- 任意のサードパーティプロバイダー（`custom` の引き出し）に切り替えれば、履歴リストでこれらのセッションが見えます。
+- 内容を見たいなら `.jsonl` を直接読み、再開したいならシナリオ B のルール（それを生成した元のバックエンドに戻る）に従ってください。
+- もし **ある 1 本** を手動で公式に戻したい場合: 現在は自動ボタンはありません（方向を誤判定するのを避けるため、あえて作っていません）。上級ユーザーは、そのファイルを **先にバックアップ** したうえで、`.jsonl` の 1 行目 `session_meta` 内の `model_provider` を `custom` から `openai` に手動で戻せます（上級操作です。変更前に必ずコピーを取ってください）。
+
+### シナリオ E: 復元時に「現在の Codex ディレクトリに復元可能な移行バックアップはありません」と通知 → 「復元失敗 = データが消えた」と思う
+
+**現象**: スイッチをオフにするときに復元にチェックを入れたら、「現在の Codex ディレクトリに復元可能な移行バックアップはありません」と通知が出た。あなたは慌てます: 復元すら失敗した、データは完全に消えたのでは？
+
+**真相**: 「復元できるものがない」≠「データが消えた」。むしろ逆で、通常は **そもそも復元すべき移行が存在しない** からです。よくある原因:
+
+- **当初「既存の公式セッションを移行する」にチェックを入れていない**: 移行していない以上、移行バックアップもなく、戻すべきセッションもありません。あなたの公式の古いセッションはずっと `openai` の引き出しにあり、スイッチをオフにすれば直接再表示されます（シナリオ A と同じ）。（この場合、無効化ダイアログは復元チェックボックスを **そもそも表示しない** こともあります——システムがバックアップを一切探索できないためです。）
+- **すでに一度復元済み**: セッションラベルはすべて `openai` に戻っており、もう一度押しても「まだ `custom` の対象がない」のは当然です——これは **冪等保護であり、失敗ではありません**。
+- **Codex ディレクトリを切り替えた**: 復元は **現在の** ディレクトリに属するバックアップ台帳しか認識しないので、ディレクトリを変えると旧ディレクトリの台帳が見つかりません。ディレクトリを戻せば解決します。
+
+この 3 つのケースでは、どのセッションも削除されていません。
+
+**どうするか**: 巻末のコマンドで `~/.codex/sessions/` 内のセッションファイル総数を数え、ファイルがすべて残っていることを確認してください。次に `~/.cc-switch/backups/` に `codex-official-history-unify-v1` ディレクトリがあるかを見てください——もしこのディレクトリすらなければ、あなたは一度も移行を起動しておらず、セッションはずっと元の引き出しにある、ということです。
+
+### シナリオ F: 復元が拒否され、「統一セッション履歴が再度有効化されたため、復元をスキップしました」と通知
+
+**現象**: スイッチをオフにする → 復元にチェック → 手が速くて、すぐにスイッチを再びオンにした。すると「統一セッション履歴が再度有効化されたため、復元をスキップしました」と通知が出た。
+
+**真相**: これはデータを「矛盾」状態にしてしまうのを防ぐ防護であり、セッションは同じく消えていません。復元の動作は「セッションラベルを `custom` から `openai` へ戻す」ことですが、この時点でスイッチが再びオンになっていると、live 設定は `custom` へルーティングしています——一方で履歴を `openai` へ戻し、一方で新セッションを `custom` に落とせば、セッションが人為的に 2 つに引き裂かれてしまいます。そのため CC Switch は「スイッチが再びオンになった」のを検知すると、**この復元を自発的に取りやめ、何も変更しません**。セッションは現状を維持し、削除も破壊もありません。
+
+**どうするか**: 本当に復元したいなら、**まずスイッチを安定してオフにし**（すぐにオンにし直さない）、それから「オフにする + 復元にチェック」を実行してください。統一を保ちたいなら、復元せず、セッションを `custom` の共有引き出しに残して通常どおり使ってください。
+
+**大原則: CC Switch の統一 / 移行 / 復元は、全工程でセッションの 1 つのラベルフィールドだけを変更し、しかも毎回書き換える前に自動でバックアップします。あなたの会話を削除することはありません。見えない ≠ 消えた——別の引き出しを見るか、下のコマンドで自分の目で確かめてください。**
+
+---
+
+## 自分の目で確認: セッションファイルはディスク上に残っている（最重要セクション）
+
+文字をいくら重ねるより、自分の目で見るのが一番です。以下に **実際のパス**（CC Switch のソースコードから取得）と、異なる OS でセッションファイル・バックアップディレクトリを見る方法を示します。**全工程は読み取りのみで変更なし。ぜひ一度ご自身で試してみてください。**
+
+### 最も簡単な方法: ファイルマネージャーで直接開く（コマンドライン完全不要）
+
+- **macOS（Finder）**: `Cmd + Shift + G` を押して `~/.codex/sessions` を貼り付けて Enter すれば、たくさんの `.jsonl` セッションファイルとその更新時刻が見えます。バックアップディレクトリは `~/.cc-switch/backups` を貼り付けます。
+- **Windows（エクスプローラー）**: アドレスバーに `%USERPROFILE%\.codex\sessions` を貼り付けて Enter すれば、セッションフォルダとその中の `.jsonl` が見えます。バックアップディレクトリは `%USERPROFILE%\.cc-switch\backups` を貼り付けます。
+
+**ここで一連の `.jsonl` ファイルが見えれば、それがセッションデータが無傷でディスク上にある証拠です。** ファイル数や更新時刻は、どんな文章よりも直感的です。
+
+### あなたのセッション / 履歴ファイルはどこにあるのか
+
+| 内容 | 実際のパス | 説明 |
+|---|---|---|
+| **セッション本文（コア）** | `~/.codex/sessions/`（日付別サブディレクトリを含む、再帰的） | セッション 1 つにつき 1 つの `.jsonl` テキストファイル。**これがあなたの会話内容** |
+| **アーカイブ済みセッション** | `~/.codex/archived_sessions/` | 同じく `.jsonl` |
+| **セッションインデックス DB** | `~/.codex/state_5.sqlite` | `threads` テーブルの `model_provider` 列が「引き出しラベル」。**これこそ、セッション再開リストが実際に読み取る分類のソース** |
+| **移行バックアップ**（移行をオンにすると自動生成） | `~/.cc-switch/backups/codex-official-history-unify-v1/<時間スタンプ>/` | `jsonl/`、`state/`、`meta.json` を含む |
+| **復元バックアップ**（復元を押すと自動生成） | `~/.cc-switch/backups/codex-official-history-unify-restore-v1/<時間スタンプ>/` | 復元前の安全なコピー |
+
+> **注意**: CC Switch で Codex ディレクトリを変更した場合や、`config.toml` で `sqlite_home` を設定している場合は、上記の `~/.codex` をあなたの実際のディレクトリに置き換えてください。以下の `~` = あなたのユーザーホームディレクトリ。
+
+### macOS / Linux コマンド
+
+**1. セッションファイル総数を数える（これこそ「消えていない」確固たる証拠）**
+
+```bash
+# セッションファイルの総数を数える —— この数が想定どおりなら、データはすべて残っている
+find ~/.codex/sessions ~/.codex/archived_sessions -name '*.jsonl' 2>/dev/null | wc -l
+
+# 最近更新されたセッションファイル上位 10 件を見る
+find ~/.codex/sessions -name '*.jsonl' 2>/dev/null -print0 \
+  | xargs -0 ls -lt 2>/dev/null | head -10
+```
+
+**2. （補助）各「引き出し」にそれぞれ何個のセッションがあるか見る**
+
+```bash
+# 公式の引き出し（openai）のセッションファイル数
+grep -rlE '"model_provider"[[:space:]]*:[[:space:]]*"openai"' ~/.codex/sessions 2>/dev/null | wc -l
+
+# 統一の引き出し（custom）のセッションファイル数
+grep -rlE '"model_provider"[[:space:]]*:[[:space:]]*"custom"' ~/.codex/sessions 2>/dev/null | wc -l
+
+# 各ラベルの分布をひと目で確認
+grep -rhoE '"model_provider"[[:space:]]*:[[:space:]]*"[^"]*"' ~/.codex/sessions 2>/dev/null | sort | uniq -c
+```
+
+> **重要なヒント、このステップに驚かないでください**: **初期バージョンの Codex は `.jsonl` に `model_provider` フィールドを書き込みません**。これらの古い公式セッションは上記の grep では **数えられません** が、インデックス DB `state_5.sqlite` では依然として `openai` に分類されており、セッション再開リストではちゃんと見えます。ですので **「セッションが消えていない」かの判断はステップ 1 のファイル総数を基準にしてください**——バケット別 grep は分類を理解する補助に過ぎず、数えた結果がファイル総数より少ないのは **まったく正常** であり、決して「ひとまとまり消えた」ことを意味しません。
+
+**3. （応用）インデックス DB `state_5.sqlite` を見る——セッション再開リストが実際に読む分類**
+
+```bash
+# sqlite3 がインストール済みであること；未インストールならスキップ可
+sqlite3 ~/.codex/state_5.sqlite \
+  "SELECT COALESCE(model_provider,'<空>'), COUNT(*) FROM threads GROUP BY 1;"
+```
+
+> この `threads` テーブルこそ、Codex のセッション再開リストが実際に読み取る分類のソースであり、`openai` の行数 ≈ あなたの公式の引き出しで見えるセッション数です。ステップ 2 の jsonl grep とは数が合わないことがあります——その理由は、上述の「古いセッションは jsonl フィールドを書き込まないが、インデックス DB では依然として openai」だからです。両者が合わないのは異常ではありません。
+
+**4. あるセッションの内容を直接読む（会話の文字が残っていることを確認）**
+
+```bash
+# <ファイル名> を、上の ls で表示された .jsonl のパスに置き換える
+python3 -m json.tool < "<ファイル名>.jsonl" 2>/dev/null | head -50
+
+# またはエディタで直接開いて見る（プレーンテキスト）
+open -e "<ファイル名>.jsonl"      # macOS
+```
+
+**5. CC Switch のバックアップディレクトリを見る（移行 / 復元の前に必ずコピーを残した証拠）**
+
+```bash
+ls -la ~/.cc-switch/backups/codex-official-history-unify-v1/ 2>/dev/null
+ls -la ~/.cc-switch/backups/codex-official-history-unify-restore-v1/ 2>/dev/null
+```
+
+### Windows コマンド（PowerShell）
+
+セッションディレクトリは通常 `C:\Users\<あなたのユーザー名>\.codex\` にあり、バックアップは `C:\Users\<あなたのユーザー名>\.cc-switch\backups\` にあります。
+
+```powershell
+# 1. セッションファイルの総数（「消えていない」ことの動かぬ証拠）
+(Get-ChildItem "$env:USERPROFILE\.codex\sessions","$env:USERPROFILE\.codex\archived_sessions" -Recurse -Filter *.jsonl -ErrorAction SilentlyContinue).Count
+
+# 2. 最近更新されたセッション上位 10 件
+Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
+  Sort-Object LastWriteTime -Descending | Select-Object -First 10 FullName,LastWriteTime
+
+# 3. （補助）公式(openai) / 統一(custom) の引き出しにそれぞれ何件のセッションファイルがあるか
+(Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
+  Select-String -Pattern 'model_provider"\s*:\s*"openai"' -List).Count
+(Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
+  Select-String -Pattern 'model_provider"\s*:\s*"custom"' -List).Count
+
+# 4. バックアップディレクトリを見る
+Get-ChildItem "$env:USERPROFILE\.cc-switch\backups\codex-official-history-unify-v1" -ErrorAction SilentlyContinue
+Get-ChildItem "$env:USERPROFILE\.cc-switch\backups\codex-official-history-unify-restore-v1" -ErrorAction SilentlyContinue
+```
+
+> 同じく注意: ステップ 3 の grep の数がファイル総数より **少なくなる** のは正常です（古いセッションはこのフィールドを書き込まないため）。「セッションが消えていない」の判断は、ステップ 1 の **ファイル総数** を基準にしてください。
+
+---
+
+## 応用原理付録（仕組みを本当に理解したい人向け）
+
+### 1. バケット分け機構（引き出しの本質）
+
+Codex のセッション再開 / 履歴リストは、現在アクティブな `model_provider` id で **厳密な文字列フィルタリング** を行います。セッションファイル `.jsonl` の **1 行目** は `type:"session_meta"` のレコードで、その `payload.model_provider` がそのセッションの属する引き出しです（`grep -rl` はファイル内にそのラベルが 1 回でも出現すればそのファイルをカウントするので、行ごとに解析する必要はありません。旧バージョンでこのフィールドを書き込んでいないセッションは数えられません）。セッション再開リストを実際に駆動するのはインデックス DB `state_5.sqlite` の `threads.model_provider` 列です。公式サブスクリプションは `config.toml` に明示的な `model_provider` がないとき、内蔵のデフォルト id `openai` に入ります。CC Switch のすべてのサードパーティプロバイダーは一律に `custom` を使います。
+
+### 2. スイッチがすること（注入、live にのみ存在）
+
+オンにすると、CC Switch は公式 live `config.toml` に次の内容を注入します。
+
+```toml
+model_provider = "custom"
+
+[model_providers.custom]
+name = "OpenAI"
+requires_openai_auth = true
+supports_websockets = true
+wire_api = "responses"
+```
+
+各フィールドには役割があります。`requires_openai_auth = true` は認証を引き続き `auth.json` 内の ChatGPT ログインで行わせ、base_url 未指定時は公式 Codex バックエンドへフォールバックさせます。`name = "OpenAI"` は Codex の公式機能ゲート（web search、リモート圧縮など）を引き続きヒットさせます。`supports_websockets = true` は custom エントリでデフォルトに失われる能力を補います。`wire_api = "responses"` は公式の responses プロトコルを使います。**正味の効果は: 認証は変わらず、バケット名が変わるだけ。**
+
+**重要な不変条件: この注入は live `config.toml` にのみ存在でき、決してデータベースの保存設定には書き込まれません。** 公式プロバイダーから切り替えて離れ、live をデータベースへ書き戻すとき、CC Switch はこの注入を正確に剥離します（形態が注入物と完全に一致するときだけ剥離し、サードパーティがカスタムした `custom` テーブルはそのまま保持します）。だからこそ「スイッチをオフにする + 一度切り替える」だけで live を完全に復元でき、データベースには常にあなた本来のクリーンな公式設定が保たれます——これがスイッチ全体の可逆性の礎です。
+
+### 3. 注入の 2 つの拒否ゲート（シナリオ C に対応）
+
+- `config.toml` に明示的な `model_provider` がすでにある → ユーザーのルーティングを上書きしない。
+- 形態の異なる `[model_providers.custom]` テーブルがすでに存在する（サードパーティの `base_url` が付いている可能性がある）→ 注入を拒否、さもないと ChatGPT OAuth トラフィックを誤ったバックエンドへルーティングしてしまう。
+
+注入を拒否したとき live は統一されず、移行ゲート（live の `model_provider` が trim 後に `custom` と等しいかを確認）が `live_not_unified` と判定 → 移行をスキップし、意思を保持し、次回起動の再試行時に行います。これは「安全な先送り」であり、「失敗してデータが消えた」ではありません。
+
+### 4. セッションの三分類（移行 / 復元の境界を決める）
+
+- **A 類**: オン時に移行した既存の公式セッション——バックアップが台帳であり、正確に `openai` へ復元可能。
+- **B 類**: オン期間中に新規作成——どのバックアップにもなく、公式 / サードパーティを判別不能、**決して自動で動かさない**（`custom` に残す）。
+- **C 類**: オン前の純粋なサードパーティ履歴——絶対に触れない。
+
+### 5. 移行 / 復元の安全性（データが本当に削除されることはない、その保証はどこから来るか）
+
+4 層の設計が共同で保証します: **正常・異常のあらゆるパス** において、元のセッションデータが本当に削除されることはありません。
+
+- **フィールドだけ変更、本文には触れない**: 移行 / 復元はセッションメタデータ内の `model_provider` の値を `openai` と `custom` の間で切り替えるだけで、会話内容、`response_item`、`encrypted_content` はすべてそのまま保持します。
+- **書き換え前に必ずコピーをバックアップ**: jsonl はファイルコピー、state DB は SQLite の完全なコピーで、タイムスタンプ付きの世代ディレクトリに保存します。移行バックアップは `codex-official-history-unify-v1/` に、復元バックアップは独立した `codex-official-history-unify-restore-v1/` にあり、台帳を純粋に保つため両者は分けられています。
+- **移すだけ削除しない + 原子書き込み**: すべての jsonl 書き換えは「一時ファイル + 全体置換」を経由し、state DB はトランザクション化された `UPDATE` を経由し、全工程でセッションやインデックスを削除する操作は一切ありません。ファイルはいかなる時点でも完全です。
+- **悲観的スキップ + 冪等で再試行可能**: バケットが不一致のとき（`live_not_unified`）は移行しないことを選びます。一つのプロセスロックが移行と復元を直列化し、「起動時の再試行 / 保存後のバックグラウンドタスク / 無効化時の復元」が同じ一群のファイルを並行して双方向に書き換えるのを防ぎます。完了マークは Codex ディレクトリに紐づけて条件付きで書き込み、移行漏れを防ぎます。復元は「台帳にある + 現在もまだ custom」の二重条件を使い、誤変更を防ぎます。復元スキャンはすべてのバックアップ世代の和集合を取り、何度もスイッチを切り替えた後でも初期に移行したセッションを復元できます。重複した復元は `nothing_to_restore` を返しますが、これは冪等保護であり失敗ではありません。
+
+### 6. バックエンドをまたいだ encrypted_content（シナリオ B に対応）
+
+セッション内の推論暗号文は、それを生成したバックエンドだけが復号でき、上流の Codex は by design でバックエンドをまたいだ復号をサポートしません。これが「再開失敗」の根本原因であり、ファイルの完全性とは無関係です——セッション `.jsonl` は完全にディスク上に横たわり、`encrypted_content` も無傷です。元のプロバイダーに戻して再開するか、新規セッションを始めれば、どちらも正常です。
+
+---
+
+## 参考リンク
+
+- [サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する: CC Switch 設定ガイド](./codex-official-auth-preservation-guide-ja.md)
+- [Codex で DeepSeek などの Chat 形式 API を使う: CC Switch ローカルルーティングガイド](./codex-deepseek-routing-guide-ja.md)
+- CC Switch ユーザーマニュアル内の「Codex アプリ拡張」関連の章
+
+---
+
+**最後に一言**: あなたが見た「セッションが消えた / 再開失敗」は、本質的には **セッションが別の履歴リスト（引き出し）に移されたか、相手のバックエンドが古い推論内容を復号できない** ことであり、ファイルは常にそっくりそのまま `~/.codex/sessions/`（および `state_5.sqlite`）に横たわっています。スイッチをオフにするとき「バックアップから復元する」にチェックを入れれば、移行した公式セッションを正確に公式リストへ戻せます。たとえ復元しなくても、元の `.jsonl` ファイルと `~/.cc-switch/backups/codex-official-history-unify-*/` 配下のバックアップコピーはどちらも残っています——**データが本当に失われることは決してありません。**
@@ -0,0 +1,467 @@
+# 统一 Codex 会话历史：功能介绍与使用攻略（CC Switch）
+
+> 适用版本：CC Switch v3.16.x 及以上。本文根据当前代码整理，命令与路径均可亲手验证；示例使用去敏数据，不包含真实会话内容或 API Key。
+
+## 这个功能是什么
+
+「统一 Codex 会话历史」是 CC Switch v3.16.x 为 Codex 新增的一个开关。它的位置在 **设置 → 通用 → 「Codex 应用增强」分组**里（"Codex 应用增强"是这个分组的标题，开关本身叫"统一 Codex 会话历史"）。开启后，**官方订阅（ChatGPT 登录 / OpenAI API Key）的会话，会和 CC Switch 管理的所有第三方供应商会话，出现在同一个历史 / 续聊列表里**——不再被分隔在两个互相看不见的列表中。
+
+## 它解决什么问题
+
+Codex 自己按"供应商标签"（一个叫 `model_provider` 的字段）给会话分类，而且**续聊 / 历史列表只显示和你当前激活的供应商同标签的会话**。于是会话天然被分进两个"抽屉"：
+
+- 官方订阅的会话，归在 Codex 内建的 **`openai`** 标签下；
+- CC Switch 管理的所有第三方供应商，归在 **`custom`** 标签下。
+
+两个抽屉互相看不见。如果你**经常在官方与第三方之间切换**，就会遇到这种割裂："刚才用官方聊的会话，切到第三方后在历史列表里找不到了"——它其实没丢，只是被分到了另一个抽屉。这种割裂既容易让人误以为会话丢失，也不方便把所有会话放在一处统一回顾、续聊。
+
+**这个开关就是为了消除这种割裂**：让官方订阅也以 `custom` 标签运行，于是官方与第三方会话合并进同一个列表，找起来、续起来都在一处。
+
+> ✅ **一个贯穿全文的重要前提，请先记住**：这个功能（统一 / 迁移 / 还原）**全程只改写会话记录里那一个归类标签 `model_provider`，而且每次改写前都会自动把原文件备份一份**。它不会删除、清空或覆盖你的任何一句对话。所以本文后面若提到"某些会话看不到了"，几乎都是"被分到了另一个抽屉"，而不是"数据没了"——真担心时，直接看 [症状对照表](#我感觉会话丢了症状对照表) 与 [亲手验证文件还在](#亲手验证你的会话文件还在硬盘上最重要的一节)。
+
+## 工作原理（一句话版）
+
+把它想成 **两个抽屉 + 自动备份**：
+
+- 默认时，官方会话在 `openai` 抽屉、第三方会话在 `custom` 抽屉，互不可见；
+- 开关让**官方也改用 `custom` 抽屉**，于是两个抽屉合并成一个共享列表；
+- 你可以选择把**现有的官方老会话**也一并"搬"进共享抽屉（这一步叫**迁移**，可选、需主动勾选），而**任何搬动前都会先复制一份备份**，所以整个过程**可逆**；
+- **认证完全不受影响**——官方订阅照常用你的 ChatGPT 登录、照常走官方后端，变的只是会话的归类标签。
+
+完整机制（注入了什么、为什么可逆、迁移/还原如何保证不丢数据）见下文 [核心心智模型](#核心心智模型两个抽屉--自动备份) 与文末 [进阶原理附录](#进阶原理附录给想真正搞懂机制的用户)。
+
+## 如何使用（速览）
+
+1. **开启**：设置 → 通用 → Codex 应用增强 → 打开「统一 Codex 会话历史」→ 在弹窗里决定是否勾选"同时迁入现有官方会话历史"（想让**以前**的官方会话也并进统一列表，就勾上；只想从现在起统一，就不勾）→ 确认。详见 [开启时会发生什么](#开启时会发生什么分步说明)。
+2. **关闭**：关掉同一开关 → 弹窗里保持勾选"按备份精确还原"（默认就勾着）→ 确认，即可把当初迁入的官方会话精确翻回官方列表。详见 [关闭时会发生什么](#关闭时会发生什么分步说明)。
+3. **感觉会话丢了？** 别慌，跳到 [症状对照表](#我感觉会话丢了症状对照表) 按症状定位，并用 [亲手验证](#亲手验证你的会话文件还在硬盘上最重要的一节) 一节的命令亲眼确认文件都在。
+
+---
+
+## 核心心智模型：两个抽屉 + 自动备份
+
+要理解这个功能，你只需要记住两件事：**抽屉**和**备份**。
+
+### 抽屉：Codex 怎么给会话分类
+
+你每开一个 Codex 会话，Codex 会在会话文件头部记一个标签 `model_provider`，标记"这条会话是用哪个供应商聊的"。Codex 的**续聊 / 历史列表是按当前激活的这个标签精确过滤的**——只显示和"你现在这个供应商"同标签的会话。
+
+- 官方订阅（ChatGPT 登录 / OpenAI API Key）的会话，标签是内建的 **`openai`**。
+- CC Switch 管理的所有第三方供应商，统一用标签 **`custom`**。
+
+所以默认情况下，官方会话和第三方会话天生互相看不见——它们在两个不同的抽屉里。这是 **Codex 自身的设计**，不是 CC Switch 弄丢了什么。
+
+```text
+默认状态（没开统一开关）：
+
+   ┌─────────────────┐        ┌─────────────────┐
+   │   openai 抽屉    │        │   custom 抽屉    │
+   │ （官方订阅会话）  │        │ （第三方供应商会话）│
+   └─────────────────┘        └─────────────────┘
+         ▲                            ▲
+   用官方时只看到这边            用第三方时只看到这边
+   （两个抽屉互相看不见）
+```
+
+**「统一 Codex 会话历史」开关做的事，就是让官方订阅也以 `custom` 标签运行，把两个抽屉合并成一个**，于是官方会话和第三方会话出现在同一个续聊列表里。注意：**认证没变**——你的官方订阅照常用你的 ChatGPT 登录、照常走官方后端，只是会话的"归类标签"从 `openai` 变成了 `custom`。
+
+```text
+开启统一开关后：
+
+   ┌─────────────────────────────────────────┐
+   │            custom 共享抽屉                │
+   │   官方订阅会话  +  第三方供应商会话         │
+   │   （出现在同一个历史 / 续聊列表里）          │
+   └─────────────────────────────────────────┘
+```
+
+### 备份：每次改标签前都先复制一份
+
+"合并抽屉"需要把一部分官方会话的标签从 `openai` 改成 `custom`（这一步叫**迁移**，且是**可选的、需要你主动勾选**）。而**任何一次改写之前，CC Switch 都会先把原文件原封不动地复制一份**到这里：
+
+```text
+~/.cc-switch/backups/codex-official-history-unify-v1/<时间戳>/
+```
+
+这份备份，就是日后"按备份精确还原"的唯一依据。它让整个过程变得**可逆**：你随时可以关掉开关，把当初迁进来的官方会话精确地翻回 `openai` 抽屉。
+
+记住这两个词——**抽屉**（会话只是换了归类）、**备份**（改前必先复制）——后面所有内容你都能轻松理解。
+
+---
+
+## 开启时会发生什么：分步说明
+
+### 第 1 步：找到开关
+
+```text
+设置 → 通用 → Codex 应用增强
+```
+
+在"Codex 应用增强"这个区块里有两行开关，**第二行**（蓝色历史图标）就是本攻略的主角：
+
+> **统一 Codex 会话历史**
+
+它下方有一段说明文字（逐字）：
+
+> 开启后，官方订阅将以共享的 custom 供应商标识运行，官方与第三方会话出现在同一历史列表中，并可选择把现有官方会话一并迁入（迁移前自动备份）。关闭开关时可按备份恢复迁入的会话。注意：跨供应商继续旧会话时，对方后端可能无法解密会话中的 encrypted_content 推理内容，导致继续失败
+
+> **注意**：这一句说明里已经预告了三件事——会出现在同一列表、可选迁入并自动备份、跨供应商续聊"可能继续失败"。这里的"继续失败"指的是**续不上、生成不了新回合**，不是"记录丢失"。这正是后面要重点拆解的核心误解。
+
+### 第 2 步：把开关从关拨到开 → 弹出确认窗
+
+一旦你把开关拨到开，CC Switch **不会立刻保存**，而是先弹出一个确认窗口。窗口文案如下（逐字）：
+
+- **标题**：统一 Codex 会话历史
+- **正文**：
+
+  > 开启后，官方订阅与第三方将共用同一个会话历史列表。注意：跨供应商继续旧会话时，可能因对方后端无法解密 encrypted_content 推理内容而失败。
+  >
+  > 可选择同时把现有官方会话历史迁入共享列表（迁移前自动备份到 ~/.cc-switch/backups，关闭开关时可选择恢复）。
+
+- **复选框**：同时迁入现有官方会话历史
+- **确认按钮**：我已了解，继续开启
+- **取消按钮**：取消
+
+**这个复选框默认是不勾选的。** 这是一个重要的分岔点：
+
+| 你的选择 | 效果 | 此刻你的数据在哪 |
+|---|---|---|
+| **不勾**（默认） | 只切换标识。**只有开启之后新建的官方会话**才会落进 `custom` 共享抽屉 | 你**开启前**的官方老会话，标签仍是 `openai`，原地未动，仍在 `~/.codex/sessions/` |
+| **勾上** | 除了切换标识，还会把**现有的官方老会话**也从 `openai` 抽屉迁进 `custom` 抽屉 | 老会话被**复制备份**后，标签改写为 `custom`；原始数据有备份兜底 |
+
+> **如果你希望"以前的官方会话也出现在统一列表里"，必须主动勾选这个复选框。** 否则你会遇到下面对照表里的"场景 A"——老会话看起来"不见了"，其实只是留在原抽屉里。
+
+点"取消"或点窗口外面：开关直接弹回关闭状态，什么都没发生。
+点"我已了解，继续开启"：开关保存为开启，CC Switch 在后台落盘配置（如果勾了迁移，就执行迁移）。
+
+### 第 3 步（仅当勾了迁移）：迁移如何执行 + 数据安全
+
+如果你勾了"同时迁入现有官方会话历史"，CC Switch 会对你的官方老会话做这套流程：
+
+```text
+对每个官方（openai 标签）会话文件：
+   ① 先把原文件原样复制一份到备份目录          ← 数据有了第一道保险
+   ② 用「写临时文件 → 整体替换」的原子方式，
+      只把头部那行 session_meta 里的 model_provider
+      从 "openai" 改成 "custom"               ← 对话正文一个字节都不动
+   ③ 索引数据库 state_5.sqlite 同步在一个事务里把标签改过来
+```
+
+- **备份位置**：`~/.cc-switch/backups/codex-official-history-unify-v1/<时间戳>/`，每次迁移生成一个带时间戳的"代际目录"，内含 `jsonl/`（会话副本）、`state/`（索引库副本）、`meta.json`（记录这次迁移属于哪个 Codex 目录）。
+- **改的是什么**：只有 `model_provider` 这一个字段值。你的对话内容、推理内容、所有正文**原样保留**。
+- **删的是什么**：**什么都没删**。备份是"复制"，改写是"原子替换同一个文件"，全程没有任何删除会话或索引的动作。文件在任何时刻都是完整的（要么是旧内容、要么是新内容，绝不会是空或半截）。
+
+迁移成功后，这些官方老会话就出现在统一列表里了。**此刻你的数据**：① 原始副本在备份目录；② 活动文件里只有归类标签变了，内容完好。
+
+> **注意**：开启与迁移本身**不会弹成功提示**。迁移是后端在保存时顺带跑的，UI 上你只会看到开关变成了打开状态。所以"没看到迁移成功的弹窗"是正常的，不代表失败。
+
+---
+
+## 关闭时会发生什么：分步说明
+
+### 第 1 步：把开关从开拨到关 → 探测备份 → 弹出确认窗
+
+关闭时，CC Switch 会**先花一瞬间探测有没有迁移备份**，然后弹出确认窗口（所以关闭弹窗会有一点点延迟，属正常）。文案如下（逐字）：
+
+- **标题**：关闭统一会话历史
+- **正文**：
+
+  > 关闭后，官方订阅与第三方将恢复各自独立的会话历史列表。开启期间产生的会话因无法区分来源，将留在第三方历史中，官方订阅将看不到它们。
+
+- **复选框**（条件显示）：把开启时迁入的官方会话还原回官方历史（按备份精确还原）
+- **确认按钮**：关闭
+- **取消按钮**：取消
+
+> **划重点**：正文说的是"官方订阅**将看不到它们**"——是**看不到**，不是**删除**。开启期间你新聊的会话仍然完整地在 `custom` 抽屉里，只是关闭后官方那一侧看不到而已。
+
+**这个还原复选框默认是勾选的。** 也就是说，默认行为就是"关闭的同时，把当初迁入的官方会话精确还原回官方历史"。你只要保持勾选、点"关闭"即可。
+
+如果复选框**没有出现**，说明系统判断当前没有需要还原的备份（要么你从没勾过迁移、要么探测不到备份）——这种情况下你的官方老会话从没被改动过，关掉开关它们自己就回到 `openai` 抽屉了。
+
+### 第 2 步：还原如何执行（按备份账本精确翻回）
+
+如果你保持勾选并点"关闭"，CC Switch 的还原流程是这样的：
+
+```text
+① 先把当前现场再复制一份到独立的还原备份目录
+   ~/.cc-switch/backups/codex-official-history-unify-restore-v1/<时间戳>/
+   （还原本身也先备份，所以还原也不会丢数据）
+② 翻遍所有迁移备份代际，找出"当初标签是 openai"的会话 id，组成一份"账本"
+③ 只对【既在账本里、当前又仍是 custom】的会话，把标签改回 "openai"
+```
+
+注意第 ③ 步的**双重条件**——既要在账本里（证明它当初确实是官方迁来的），又要当前仍是 `custom`（说明你没手动改过它）。两个条件都满足才翻回。这保证了还原既精确又不会误伤。
+
+**此刻你的数据**：被迁回的官方会话标签改回 `openai`，重新出现在官方列表；同时迁移备份和还原备份两份副本都还在硬盘上。
+
+### 第 3 步：看提示，确认结果
+
+只有"关闭 + 勾选还原"这条路径会弹结果提示。可能看到的提示（逐字）：
+
+| 你看到的提示 | 含义 |
+|---|---|
+| **已按备份还原官方会话历史（{{files}} 个会话文件、{{rows}} 条索引记录）** | 还原成功。`{{files}}` / `{{rows}}` 处会显示实际数字 |
+| **当前 Codex 目录没有可恢复的迁移备份** | 没有可还原的内容（**不等于数据丢了**，详见对照表场景 E） |
+| **统一会话历史开关已重新开启，已跳过还原** | 还原排队期间你又把开关打开了，系统主动放弃还原（详见对照表场景 F） |
+| **还原官方会话历史失败，请重试** | 还原过程报错，重试即可，数据未被破坏 |
+| **保存失败，请重试** | 关闭这一步保存本身就失败了；此时**绝不会触发还原**，开关弹回原位 |
+
+> **一个贴心的安全设计**：如果"关闭开关"这一步保存失败，CC Switch **绝不会去执行还原**。否则就会出现"开关还开着、会话却被翻回 openai 桶"的撕裂状态。保存失败时开关会**自动弹回原来的位置**，你不会停留在一个"看起来已关、实则没保存"的假状态里。
+
+---
+
+## "我感觉会话丢了？"症状对照表
+
+下面六个场景，是用户最容易误以为"会话丢了"的情形。**每一个的真相都是：数据完好，只是换了抽屉或暂时看不到。** 先用这张表按症状定位，再看下面的详细说明。
+
+| 场景 | 你看到的 | 数据真相 | 一句话解法 |
+|---|---|---|---|
+| **A** 没勾迁移 | 官方老会话不在统一列表 | 全在，仍带 `openai` 标签 | 重开并勾迁移，或关开关 |
+| **B** 跨供应商续聊失败 | 续不上 / 报错 | 文件完好，只是密文跨后端解不开 | 回原供应商续；只看内容直接读 jsonl |
+| **C** 代理接管 / 注入被拒 | 没迁也没还原 | 迁移被安全跳过，文件没动 | 退出接管 → 重启重试；或直接关开关 |
+| **D** 还原后新会话没回官方 | 开启期间新会话不在官方 | 在 `custom` 抽屉，设计上不动 | 切第三方供应商即可见 |
+| **E** 提示"没有可恢复备份" | 还原"失败" | 通常压根没迁移过，会话在原抽屉 | 关开关官方会话自动复现 |
+| **F** 提示"开关已重新开启，跳过还原" | 还原被拒 | 防数据撕裂，啥也没改 | 先彻底关开关再还原 |
+
+### 场景 A：开了开关但没勾迁移 → 官方老会话"不见了"
+
+**现象**：你开了统一开关，但开启弹窗里那个"同时迁入现有官方会话历史"没勾（它默认就不勾）。开启后一看，以前的官方老会话好像都不在列表里了。
+
+**真相**：数据 100% 都在，一行都没动。开关只对"开启之后新建"的官方会话生效，你**开启前**的官方老会话标签仍是 `openai`，原封不动地躺在 `~/.codex/sessions/` 里。你现在激活的是 `custom` 抽屉，自然看不到留在 `openai` 抽屉里的老会话——这就是"看起来消失"的全部原因。
+
+**怎么办**（任选其一）：
+1. **重新开启开关时勾上"同时迁入现有官方会话历史"**，把老会话换到 `custom` 抽屉，它们立刻出现在统一列表（改写前自动备份）。
+2. **或者干脆关掉统一开关**，官方重新以 `openai` 抽屉运行，老会话原地复现。
+
+### 场景 B：跨供应商续聊旧会话失败 → 以为"这条会话坏了 / 没了"
+
+**现象**：统一之后列表里能看到一条用"另一家供应商"聊出来的旧会话，你切到现在的供应商点"继续"，结果报错或接不上。
+
+**真相**：会话文件完好无损，丢的不是数据，是"跨后端解密能力"。Codex 会话里保存了一段加密的推理内容 `encrypted_content`，**这段密文只有当初生成它的那个后端能解密**。你用 B 供应商去续 A 供应商生成的会话，B 解不开 A 的密文 → 续聊失败。这是**上游 Codex 的设计限制（by design）**，与 CC Switch 是否动过文件无关。会话里的文字内容你随时能读到。
+
+> 这是整篇攻略里**唯一一个"看起来真出了问题"的真实例外**——但请注意：它只是**无法续聊（生成不了新回合）**，**原始文件依然完整存在**，对话文字随时可读。
+
+**怎么办**：
+- **用"当初创建这条会话的那个供应商"去续聊**，就能正常解密、接上。
+- 只想看历史内容、不必继续？直接读那条会话的 `.jsonl` 文件（文末有命令）。
+- 经验法则：**跨供应商更适合"开新会话"，老会话尽量回原供应商续。**
+
+### 场景 C：开了开关也勾了迁移，但迁移被静默跳过 → 以为"迁移把会话弄丢了"
+
+**现象**：你开启并勾了迁移，但官方老会话既没进统一列表、关开关想还原也提示没东西可还原（或者关闭弹窗里压根没出现还原复选框，参见场景 E）。你怀疑迁移过程中把会话搞丢了。
+
+**真相**：迁移根本**没执行**，所以也不可能弄丢——你的会话一个字都没被改。CC Switch 在迁移前有一道安全闸门：它会检查 Codex 的 live 配置（`~/.codex/config.toml`）此刻是否**真的**路由到了共享 `custom` 抽屉，只有真路由过去了才迁移。以下两种情况会判定"还没统一"（内部原因码 `live_not_unified`），于是**主动跳过迁移、保留你的开关和迁移意愿、等条件满足后再迁**：
+
+- **代理接管期间**：CC Switch 的代理接管了 live 配置，接管期的 live 不带统一路由标记。
+- **注入被拒**：你的 `config.toml` 已有手工指定的 `model_provider`，或已存在一张形态不同的 `[model_providers.custom]` 表（可能带第三方地址）。为避免把官方流量错误路由到第三方后端，CC Switch 宁可不注入、不迁移。
+
+跳过迁移 = 不碰任何会话文件。**没迁，等于没动，谈不上丢。** 这是"安全延后"，不是"失败丢数据"。
+
+**怎么办**：
+- 退出代理接管 → **重启 CC Switch**：启动时会自动重试迁移（你的迁移意愿一直保留着）。
+- 检查 `~/.codex/config.toml`：若有你手工写的冲突路由，整理掉冲突后再开开关。
+- 实在不想折腾：直接关开关，官方会话仍以 `openai` 抽屉正常显示，毫发无损。
+
+### 场景 D：关了开关并还原，但"开启期间新聊的会话"没回官方 → 以为"新会话丢了"
+
+**现象**：你开启统一期间，用官方又聊了几条新会话。后来关开关、勾了还原，还原完发现那几条新会话没回到官方抽屉。
+
+**真相**：这是**有意为之**的设计，新会话好端端在 `custom` 抽屉里，能看见、能续。还原的依据是"迁移时的备份账本"——**只有当初从 `openai` 抽屉迁进来的会话**，备份里有据可查，才会被精确翻回 `openai`。你**开启期间新建**的会话不在任何备份账本里；而且统一之后官方和第三方都用 `custom` 标签，**CC Switch 无法分辨这条新会话到底是官方聊的还是第三方聊的**。为了不把第三方会话误塞进官方历史，产品决策是：这些新会话一律留在 `custom`（第三方）历史里，绝不自动搬动。关闭弹窗的文案也明示了这一点——"开启期间产生的会话因无法区分来源，将留在第三方历史中"。
+
+**怎么办**：
+- 切到任意一个第三方供应商（`custom` 抽屉），就能在历史列表里看到这些会话。
+- 想看内容直接读 `.jsonl`；想续聊遵循场景 B 的规则（回到当初生成它的后端）。
+- 如果你确实想把**某一条**手动归回官方：目前没有自动按钮（刻意不做，避免误判方向）。进阶用户可在**先备份**该文件后，手动把它 `.jsonl` 第一行 `session_meta` 里的 `model_provider` 从 `custom` 改回 `openai`（属高阶操作，改前务必复制一份）。
+
+### 场景 E：还原提示"当前 Codex 目录没有可恢复的迁移备份" → 以为"还原失败 = 数据没了"
+
+**现象**：关开关时勾了还原，结果弹出提示"当前 Codex 目录没有可恢复的迁移备份"。你慌了：还原都失败了，是不是数据彻底没了？
+
+**真相**："没有可还原的东西"≠"数据丢了"。恰恰相反，通常是因为**根本没有需要还原的迁移**。常见原因：
+
+- **你当初没勾过"迁入现有官方会话"**：既然没迁移，自然没有迁移备份、也没有需要翻回去的会话。你的官方老会话一直在 `openai` 抽屉，关开关后直接复现（同场景 A）。（这种情况下，关闭弹窗甚至可能**根本不显示还原复选框**——因为系统探测不到任何备份。）
+- **已经还原过一遍了**：会话标签已全部翻回 `openai`，再点一次自然"没有仍是 custom 的目标可还原"——这是**幂等保护，不是失败**。
+- **切换过 Codex 目录**：还原只认属于**当前**目录的备份账本，换了目录就找不到旧目录的账本，把目录切回去即可。
+
+这三种情况下，没有任何会话被删除。
+
+**怎么办**：用文末命令统计 `~/.codex/sessions/` 里的会话文件总数，确认文件都在；再看 `~/.cc-switch/backups/` 里有没有 `codex-official-history-unify-v1` 目录——如果连这个目录都没有，说明你从没触发过迁移，会话一直在原抽屉。
+
+### 场景 F：还原被拒，提示"统一会话历史开关已重新开启，已跳过还原"
+
+**现象**：关开关 → 勾还原 → 你手很快，紧接着又把开关重新打开了，然后看到提示"统一会话历史开关已重新开启，已跳过还原"。
+
+**真相**：这是一道防护，防止把数据弄成"撕裂"状态，会话同样没丢。还原的动作是"把会话标签从 `custom` 翻回 `openai`"，但如果此刻开关又开着，live 配置正路由到 `custom`——一边把历史翻回 `openai`、一边新会话往 `custom` 落，会话会被人为撕成两半。所以 CC Switch 检测到"开关又开了"，**主动放弃这次还原、什么都不改**。会话维持现状，没有任何删除或破坏。
+
+**怎么办**：想真正还原，就**先把开关稳定地关掉**（别再立刻打开），再执行关闭 + 勾还原；想保持统一，就别还原，让会话留在 `custom` 共享抽屉正常使用。
+
+**总原则：CC Switch 的统一 / 迁移 / 还原全程只改会话的一个标签字段，并且每次改写前都自动备份。它不会删你的对话。看不见 ≠ 丢了——换个抽屉看，或用下面的命令亲眼确认。**
+
+---
+
+## 亲手验证：你的会话文件还在硬盘上（最重要的一节）
+
+文字再多，不如亲眼看见。下面给出**真实路径**（取自 CC Switch 源码）和在不同系统下查看会话文件、备份目录的方法。**全程只读不改，强烈建议你亲手试一遍。**
+
+### 最简单的方式：用文件管理器直接打开（完全不用命令行）
+
+- **macOS（Finder）**：按 `Cmd + Shift + G`，粘贴 `~/.codex/sessions` 回车，就能看到一堆 `.jsonl` 会话文件和它们的修改时间；备份目录粘贴 `~/.cc-switch/backups`。
+- **Windows（文件资源管理器）**：在地址栏粘贴 `%USERPROFILE%\.codex\sessions` 回车，就能看到会话文件夹和里面的 `.jsonl`；备份目录粘贴 `%USERPROFILE%\.cc-switch\backups`。
+
+**只要你能在这里看到一批 `.jsonl` 文件，就证明会话数据完好无损地在硬盘上。** 文件数量、修改时间，比任何文字都直观。
+
+### 你的会话 / 历史文件到底在哪
+
+| 内容 | 真实路径 | 说明 |
+|---|---|---|
+| **会话正文（核心）** | `~/.codex/sessions/`（含按日期分的子目录，递归） | 每个会话一个 `.jsonl` 文本文件，**这就是你的对话内容** |
+| **归档会话** | `~/.codex/archived_sessions/` | 同为 `.jsonl` |
+| **会话索引数据库** | `~/.codex/state_5.sqlite` | `threads` 表的 `model_provider` 列就是"抽屉标签"，**它才是续聊列表真正读取的归类来源** |
+| **迁移备份**（开启迁移时自动产生） | `~/.cc-switch/backups/codex-official-history-unify-v1/<时间戳>/` | 内含 `jsonl/`、`state/`、`meta.json` |
+| **还原备份**（点还原时自动产生） | `~/.cc-switch/backups/codex-official-history-unify-restore-v1/<时间戳>/` | 还原前的安全副本 |
+
+> **注意**：如果你在 CC Switch 里改过 Codex 目录，或在 `config.toml` 里设了 `sqlite_home`，请把上面的 `~/.codex` 换成你的实际目录。下文 `~` = 你的用户主目录。
+
+### macOS / Linux 命令
+
+**1. 数会话文件总数（这才是"没丢"的硬证据）**
+
+```bash
+# 统计会话文件总数 —— 只要这个数字符合你的预期，数据就都在
+find ~/.codex/sessions ~/.codex/archived_sessions -name '*.jsonl' 2>/dev/null | wc -l
+
+# 看最近修改的 10 个会话文件
+find ~/.codex/sessions -name '*.jsonl' 2>/dev/null -print0 \
+  | xargs -0 ls -lt 2>/dev/null | head -10
+```
+
+**2. （辅助）看每个"抽屉"各有多少会话**
+
+```bash
+# 官方抽屉（openai）会话文件数
+grep -rlE '"model_provider"[[:space:]]*:[[:space:]]*"openai"' ~/.codex/sessions 2>/dev/null | wc -l
+
+# 统一抽屉（custom）会话文件数
+grep -rlE '"model_provider"[[:space:]]*:[[:space:]]*"custom"' ~/.codex/sessions 2>/dev/null | wc -l
+
+# 看各标签分布一目了然
+grep -rhoE '"model_provider"[[:space:]]*:[[:space:]]*"[^"]*"' ~/.codex/sessions 2>/dev/null | sort | uniq -c
+```
+
+> **重要提示，别被这一步吓到**：**早期版本的 Codex 不在 `.jsonl` 里写 `model_provider` 字段**，这些旧官方会话用上面的 grep 是**数不到**的，但它们在索引库 `state_5.sqlite` 里仍然归类为 `openai`、续聊列表照样能看到。所以**判断"会话没丢"请以第 1 步的文件总数为准**——分桶 grep 只是帮你理解归类，数出来比文件总数少**完全正常**，绝不代表"丢了一批"。
+
+**3. （进阶）查索引库 `state_5.sqlite`——续聊列表真正读的归类**
+
+```bash
+# 需要已安装 sqlite3；没装可跳过
+sqlite3 ~/.codex/state_5.sqlite \
+  "SELECT COALESCE(model_provider,'<空>'), COUNT(*) FROM threads GROUP BY 1;"
+```
+
+> 这张 `threads` 表才是 Codex 续聊列表真正读取的归类来源，`openai` 行数 ≈ 你官方抽屉里能看到的会话数。它和第 2 步的 jsonl grep 可能对不上数——原因就是上面说的"旧会话不写 jsonl 字段，但索引库里仍是 openai"。两边对不上不是异常。
+
+**4. 直接读某条会话的内容（确认对话文字还在）**
+
+```bash
+# 把 <文件名> 换成上面 ls 列出的某个 .jsonl 路径
+python3 -m json.tool < "<文件名>.jsonl" 2>/dev/null | head -50
+
+# 或者直接用编辑器打开看（纯文本）
+open -e "<文件名>.jsonl"      # macOS
+```
+
+**5. 看 CC Switch 的备份目录（证明迁移 / 还原前都留了副本）**
+
+```bash
+ls -la ~/.cc-switch/backups/codex-official-history-unify-v1/ 2>/dev/null
+ls -la ~/.cc-switch/backups/codex-official-history-unify-restore-v1/ 2>/dev/null
+```
+
+### Windows 命令（PowerShell）
+
+会话目录通常在 `C:\Users\<你的用户名>\.codex\`，备份在 `C:\Users\<你的用户名>\.cc-switch\backups\`。
+
+```powershell
+# 1. 会话文件总数（"没丢"的硬证据）
+(Get-ChildItem "$env:USERPROFILE\.codex\sessions","$env:USERPROFILE\.codex\archived_sessions" -Recurse -Filter *.jsonl -ErrorAction SilentlyContinue).Count
+
+# 2. 最近修改的 10 个会话
+Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
+  Sort-Object LastWriteTime -Descending | Select-Object -First 10 FullName,LastWriteTime
+
+# 3. （辅助）官方(openai) / 统一(custom) 抽屉各多少会话文件
+(Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
+  Select-String -Pattern 'model_provider"\s*:\s*"openai"' -List).Count
+(Get-ChildItem "$env:USERPROFILE\.codex\sessions" -Recurse -Filter *.jsonl |
+  Select-String -Pattern 'model_provider"\s*:\s*"custom"' -List).Count
+
+# 4. 看备份目录
+Get-ChildItem "$env:USERPROFILE\.cc-switch\backups\codex-official-history-unify-v1" -ErrorAction SilentlyContinue
+Get-ChildItem "$env:USERPROFILE\.cc-switch\backups\codex-official-history-unify-restore-v1" -ErrorAction SilentlyContinue
+```
+
+> 同样提醒：第 3 步的 grep 数会**少于**文件总数属正常（旧会话不写该字段），请以第 1 步的**文件总数**作为"会话没丢"的判断依据。
+
+---
+
+## 进阶原理附录（给想真正搞懂机制的用户）
+
+### 1. 分桶机制（抽屉的本质）
+
+Codex 的续聊 / 历史列表按当前激活的 `model_provider` id **精确字符串过滤**。会话文件 `.jsonl` 的**第一行**是一条 `type:"session_meta"` 记录，其 `payload.model_provider` 即该会话所属抽屉（`grep -rl` 只要文件里出现一次该标签就计入该文件，因此无需逐行解析；旧版本未写该字段的会话则数不到）。真正驱动续聊列表的是索引库 `state_5.sqlite` 的 `threads.model_provider` 列。官方订阅在 `config.toml` 没有显式 `model_provider` 时落进内建默认 id `openai`；CC Switch 的所有第三方供应商统一用 `custom`。
+
+### 2. 开关做的事（注入，只活在 live）
+
+开启后，CC Switch 对官方 live `config.toml` 注入如下内容：
+
+```toml
+model_provider = "custom"
+
+[model_providers.custom]
+name = "OpenAI"
+requires_openai_auth = true
+supports_websockets = true
+wire_api = "responses"
+```
+
+每个字段都有作用：`requires_openai_auth = true` 让认证继续走 `auth.json` 里的 ChatGPT 登录、base_url 缺省回落官方 Codex 后端；`name = "OpenAI"` 让 Codex 的官方特性门控（web search、远程压缩等）继续命中；`supports_websockets = true` 补回 custom 条目默认丢失的能力；`wire_api = "responses"` 用官方 responses 协议。**净效果是：认证没变，只是桶名变了。**
+
+**关键不变量：这段注入只能存在于 live `config.toml`，绝不写进数据库的存储配置。** 切换离开官方供应商、把 live 回写数据库时，CC Switch 会把这段注入精确剥离（只在形态与注入产物完全一致时才剥，第三方自定义的 `custom` 表原样保留）。正因如此，"关掉开关 + 切换一次"就能彻底还原 live，数据库里始终是你原本干净的官方配置——这是整个开关可逆性的基石。
+
+### 3. 注入的两道拒绝闸（对应场景 C）
+
+- `config.toml` 已有显式 `model_provider` → 不覆盖用户路由；
+- 已存在形态不同的 `[model_providers.custom]` 表（可能带第三方 `base_url`）→ 拒绝注入，否则会把 ChatGPT OAuth 流量路由到错误后端。
+
+拒绝注入时 live 不统一，迁移闸门（检查 live 的 `model_provider` 是否 trim 后等于 `custom`）判定 `live_not_unified` → 跳过迁移、保留意愿、等下次启动重试时再做。这是"安全延后"，不是"失败丢数据"。
+
+### 4. 会话三分类（决定迁移 / 还原边界）
+
+- **A 类**：开启时迁入的存量官方会话——备份即账本，可精确还原回 `openai`；
+- **B 类**：开启期间新建——不在任何备份、官方 / 第三方不可分，**永不自动搬动**（留 `custom`）；
+- **C 类**：开启前的纯第三方历史——绝不触碰。
+
+### 5. 迁移 / 还原的安全性（数据不会被真正删除，保障来自哪里）
+
+四层设计共同保证：在**正常与异常的所有路径**下，原始会话数据都不会被真正删除。
+
+- **只改字段，不动正文**：迁移 / 还原只把会话元数据里的 `model_provider` 值在 `openai` 与 `custom` 之间切换，对话内容、`response_item`、`encrypted_content` 一律原样保留。
+- **改写前必先复制备份**：jsonl 用文件复制、state DB 用 SQLite 完整副本，存进时间戳代际目录。迁移备份在 `codex-official-history-unify-v1/`，还原备份在独立的 `codex-official-history-unify-restore-v1/`，两者分开以保持账本纯净。
+- **只移不删 + 原子写**：所有 jsonl 改写走"临时文件 + 整体替换"，state DB 走事务化 `UPDATE`，全程没有任何删除会话或索引的动作。文件在任一时刻都是完整的。
+- **悲观跳过 + 幂等可重试**：桶不一致时（`live_not_unified`）宁可不迁；一把进程锁串行化迁移与还原，避免"启动重试 / 保存后台任务 / 关闭还原"并发对同批文件双向改写；完成标记按 Codex 目录绑定、条件写入，防漏迁；还原用"在账本 + 当前仍 custom"双重条件，防误改。还原扫描全部备份代际取并集，多次开关循环后仍能还原早期迁入的会话；重复还原返回 `nothing_to_restore`，是幂等保护而非失败。
+
+### 6. 跨后端 encrypted_content（对应场景 B）
+
+会话内的推理密文只能被生成它的后端解密，上游 Codex by design 不支持跨后端解密。这是"续聊失败"的根因，与文件完整性无关——会话 `.jsonl` 完整躺在磁盘上、`encrypted_content` 也完好无损。换回原供应商续聊，或开新会话，都正常。
+
+---
+
+## 参考链接
+
+- [使用第三方 API 时保留 Codex 远程操作和官方插件：CC Switch 配置攻略](./codex-official-auth-preservation-guide-zh.md)
+- [在 Codex 中使用 DeepSeek 这类 Chat 格式 API：CC Switch 路由攻略](./codex-deepseek-routing-guide-zh.md)
+- CC Switch 用户手册中「Codex 应用增强」相关章节
+
+---
+
+**给你的最后一句话**：你看到的"会话不见了 / 续聊失败"，本质是**会话被换到了另一个历史列表（抽屉）里、或对方后端无法解密旧推理内容**，文件始终原封不动地躺在 `~/.codex/sessions/`（及 `state_5.sqlite`）里。关闭开关时勾选"按备份还原"即可把当初迁入的官方会话精确翻回官方列表；即便不还原，原始 `.jsonl` 文件和 `~/.cc-switch/backups/codex-official-history-unify-*/` 下的备份副本也都在——**数据绝不会真正丢失。**
@@ -6,6 +6,34 @@

 ---

+> [!WARNING]
+>
+> ## Only Official Channels (Please Read)
+>
+> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Multiple imposter websites have recently been spotted impersonating CC Switch to solicit payments and harvest account credentials, with some users already reporting financial losses. Please only obtain the software through the official channels listed below:
+>
+> | Channel            | Only Official                                                                  |
+> | ------------------ | ------------------------------------------------------------------------------ |
+> | Website            | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | Source             | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | Downloads          | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | Author             | **[@farion1231](https://github.com/farion1231)**                               |
+> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues so we can take down the imposter site as quickly as possible.
+
+---
+
+## Claude Desktop Guide
+
+The headline feature in this release is the **first-class Claude Desktop management panel**. If you already have many providers configured for Claude Code, start here:
+
+**[Use CC Switch to configure, manage, and switch Claude Desktop providers in one place](../user-manual/en/2-providers/2.6-claude-desktop.md)**
+
+The guide walks through one-click import from Claude Code, adding Claude Desktop-specific providers, direct mode vs. model-mapping mode, showing the hidden local-routing toggle, and returning to Claude Desktop's official sign-in mode.
+
+---
+
 ## Overview

 CC Switch v3.15.0 is a major release following the v3.14.x line, centered on **promoting Claude Desktop to a first-class managed surface**. It ships third-party provider switching through the in-app proxy gateway, role-based model mapping (`sonnet` / `opus` / `haiku`) with a `supports1m` long-context flag, Copilot/Codex OAuth provider reuse, a redesigned Claude Code import flow, app-switcher differentiation between "Claude Code" and "Claude Desktop", and 44 provider presets translated from the Claude Code catalog into the new Claude Desktop surface.
@@ -471,8 +499,9 @@ Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to dow

 ### Homebrew (macOS)

+> 🎉 CC Switch is now available in the official Homebrew cask repository — no need to add a custom tap!
+
 ```bash
-brew tap farion1231/ccswitch
 brew install --cask cc-switch
 ```

@@ -6,6 +6,34 @@

 ---

+> [!WARNING]
+>
+> ## 唯一の公式チャネル（必ずお読みください）
+>
+> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。最近、CC Switch の名を騙って課金を要求したり認証情報を収集する偽サイトが複数確認されており、一部のユーザーには既に金銭的被害が発生しています。本ソフトウェアは下記の公式チャネルからのみ入手してください：
+>
+> | チャネル     | 唯一の公式                                                                     |
+> | ------------ | ------------------------------------------------------------------------------ |
+> | 公式サイト   | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者         | **[@farion1231](https://github.com/farion1231)**                               |
+> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は、直ちに取引を中止し、偽サイトを速やかに削除できるよう GitHub Issues からご報告ください。
+
+---
+
+## Claude Desktop 利用ガイド
+
+本リリースの主役は **Claude Desktop の一等管理パネル**です。すでに Claude Code 側で多くのプロバイダーを設定している場合は、まずこのガイドをご覧ください：
+
+**[CC Switch で Claude Desktop プロバイダーを一括設定・管理・切り替える](../user-manual/ja/2-providers/2.6-claude-desktop.md)**
+
+このガイドでは、Claude Code から既存プロバイダーを一括インポートする方法、Claude Desktop 専用プロバイダーの追加、直結 / モデルマッピングの 2 モード、非表示のローカルルーティング切り替えを表示する設定、Claude Desktop 公式サインインモードへの復帰までを説明しています。
+
+---
+
 ## 概要

 CC Switch v3.15.0 は v3.14.x に続く大型バージョンアップで、コアの焦点は **Claude Desktop を一等管理パネルに昇格させること**にあります。これに合わせて、内蔵プロキシゲートウェイを介したサードパーティプロバイダーの切り替え、ロールベースのモデルマッピング（sonnet / opus / haiku）+ `supports1m` ロングコンテキストフラグ、Copilot / Codex OAuth プロバイダーの再利用、再設計された Claude Code インポートフロー、App スイッチャーでの「Claude Code」と「Claude Desktop」の視覚的な区別、そして Claude Code プリセットディレクトリから翻訳された 44 個の Claude Desktop プリセットを提供します。
@@ -471,8 +499,9 @@ Usage サマリーはキャッシュ正規化後の真の総トークン数 +

 ### Homebrew（macOS）

+> 🎉 CC Switch は Homebrew 公式 cask リポジトリに収録されました。カスタム tap の追加は不要です！
+
 ```bash
-brew tap farion1231/ccswitch
 brew install --cask cc-switch
 ```

@@ -6,6 +6,34 @@

 ---

+> [!WARNING]
+>
+> ## 唯一官方渠道声明（请务必阅读）
+>
+> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。最近发现多个山寨网站冒用 CC Switch 名义诱导用户付费、收集账号信息，部分已造成实际经济损失。请仅通过下列官方渠道获取本软件：
+>
+> | 类别     | 唯一官方                                                                       |
+> | -------- | ------------------------------------------------------------------------------ |
+> | 官网     | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | 源码     | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | 下载     | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者     | **[@farion1231](https://github.com/farion1231)**                               |
+> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈，让我们能尽快下线相关山寨站点。
+
+---
+
+## Claude Desktop 使用攻略
+
+本版本最主打的能力是 **Claude Desktop 一等管理面板**。如果你已经在 Claude Code 里配置了很多供应商，建议先阅读这篇攻略：
+
+**[使用 CC Switch，一键配置、管理和切换 Claude Desktop 供应商](../user-manual/zh/2-providers/2.6-claude-desktop.md)**
+
+攻略覆盖从 Claude Code 一键导入已有供应商、添加 Claude Desktop 专属供应商、直连 / 模型映射两种模式、本地路由开关显示设置，到恢复 Claude Desktop 官方登录模式的完整流程。
+
+---
+
 ## 概览

 CC Switch v3.15.0 是 v3.14.x 之后的一次大版本更新，核心聚焦在**把 Claude Desktop 升级为一等管理面板**，并配套提供第三方供应商通过内置代理网关进行切换、按角色的模型映射（sonnet / opus / haiku）+ `supports1m` 长上下文标志、Copilot/Codex OAuth 供应商复用、重新设计的 Claude Code 导入流程、App 切换器对"Claude Code"和"Claude Desktop"的可视化区分，以及 44 个从 Claude Code 预设目录翻译而来的 Claude Desktop 预设。
@@ -471,8 +499,9 @@ Release notes 模板中呈现 `ccswitch.io`。

 ### Homebrew（macOS）

+> 🎉 CC Switch 现已收录至 Homebrew 官方 cask 仓库，无需添加第三方 tap！
+
 ```bash
-brew tap farion1231/ccswitch
 brew install --cask cc-switch
 ```

@@ -0,0 +1,434 @@
+# CC Switch v3.16.0
+
+> Chat Completions → Responses format conversion for Codex (you can now use DeepSeek, Kimi, GLM in Codex!), unified Codex provider identity and history, an all-around upgraded app management surface, partner preset expansion, default model / pricing matrix upgraded to GPT-5.5 and Claude Opus 4.8, and proxy / format-conversion robustness hardening
+
+**[中文版 →](v3.16.0-zh.md) | [日本語版 →](v3.16.0-ja.md)**
+
+---
+
+## Usage Guide
+
+The two headline capabilities in this release are **Codex third-party provider Chat Completions routing** and **in-app managed CLI tool management**. If you want providers that only speak the OpenAI Chat protocol (DeepSeek, Kimi, MiniMax, etc.) to work directly in Codex, or want to install / upgrade CLI tools from one place inside the app, start with these guides:
+
+- **[Using DeepSeek in Codex: local routing hands-on guide](../guides/codex-deepseek-routing-guide-en.md)** — uses the built-in DeepSeek preset to walk through adding a Codex provider, enabling local routing, and verifying request forwarding.
+- **[Add a Codex provider: Chat Completions routing and model mapping](../user-manual/en/2-providers/2.1-add.md)** — covers the "Needs Local Routing" toggle, the model mapping table, and reasoning (thinking) auto-detection.
+- **[Settings → About: managed CLI tool management](../user-manual/en/1-getting-started/1.5-settings.md)** — covers version detection, per-tool / update-all upgrades, conflict diagnostics, and source-anchored upgrade commands.
+
+---
+
+> [!WARNING]
+>
+> ## Only Official Channels (Please Read)
+>
+> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Multiple imposter websites have recently been spotted impersonating CC Switch to solicit payments and harvest account credentials, with some users already reporting financial losses. Please only obtain the software through the official channels listed below:
+>
+> | Channel            | Only Official                                                                  |
+> | ------------------ | ------------------------------------------------------------------------------ |
+> | Website            | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | Source             | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | Downloads          | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | Author             | **[@farion1231](https://github.com/farion1231)**                               |
+> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues so we can take down the imposter site as quickly as possible.
+
+---
+
+## Overview
+
+CC Switch v3.16.0's development since v3.15.0 centers on **promoting third-party Codex providers to first-class citizens through Chat Completions routing**. Codex natively only speaks the OpenAI Responses API and GPT-family models; this release lets CC Switch's local proxy convert Codex's outgoing Responses requests into Chat Completions and rebuild the JSON and SSE streaming responses back into Responses shape, preserving `reasoning_content` / inline `<think>` blocks / streamed reasoning summaries / tool calls / `previous_response_id` follow-ups along the way, normalizing error envelopes, and probing Chat-format providers correctly in Stream Check. It ships 22 Chat-routing presets with explicit model catalogs (DeepSeek, Zhipu GLM, Kimi, MiniMax, StepFun, Baidu Qianfan, Bailian, ModelScope, Longcat, BaiLing, Xiaomi MiMo, Volcengine Agentplan, BytePlus, DouBao Seed, SiliconFlow, Novita AI, Nvidia, and more).
+
+Codex third-party providers' **identity and history** are unified and hardened this release: all third-party providers now normalize to the stable `custom` model-provider bucket, with a one-shot device migration that rewrites historical JSONL sessions and the `state_5.sqlite` threads table (originals backed up under `~/.cc-switch/backups/`), preventing past sessions from appearing to vanish when provider ids change. It also fixes OAuth login state, user-selected catalog models, and user-authored provider ids being overwritten during live reads / switches.
+
+This release also adds an **in-app managed CLI tool lifecycle**: the Settings / About tab becomes a tool management panel for Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes, with silent install / update, update-all, conflict diagnostics, source-aware anchored upgrades, WSL handling, and visible "installed but not runnable" states.
+
+The provider ecosystem and model matrix are refreshed in tandem: added APIKEY.FUN, APINebula, AtlasCloud, SudoCode, Xiaomi MiMo Token Plan, and Claude Desktop Official presets; refreshed partner links and default models / pricing across apps; upgraded the default Claude Opus line to **4.8** and GPT defaults to **5.5** where applicable. Plus extensive polish and fixes across usage observability, Traditional Chinese localization, docs, and proxy / format-conversion robustness.
+
+**Release date**: 2026-05-29
+
+**Stats**: 101 commits | 221 files changed | +27,063 insertions | -3,052 deletions
+
+---
+
+## Highlights
+
+- **Codex Chat Completions routing**: Codex providers can now be served by OpenAI-compatible Chat Completions upstreams. CC Switch converts Codex Responses requests into Chat Completions, rebuilds JSON and SSE responses back into Responses shape, preserves reasoning / `<think>` / tool-call state, normalizes error envelopes, and probes Chat-format providers correctly in Stream Check.
+- **Codex third-party provider state is unified and safer**: third-party Codex providers now share the stable `custom` model-provider bucket, with a one-shot migration for historical JSONL sessions and `state_5.sqlite` threads, plus fixes that preserve OAuth login state, user-selected catalog models, and user-authored provider ids during live reads / switches.
+- **Managed CLI tool management**: the About page is now a tool management panel for Claude, Codex, Gemini, OpenCode, OpenClaw, and Hermes, with install / update actions, update-all, conflict diagnostics, source-aware anchored upgrades, WSL handling, and visible "installed but not runnable" states.
+- **Provider ecosystem and model matrix refresh**: added APIKEY.FUN, APINebula, AtlasCloud, SudoCode, Xiaomi MiMo Token Plan, and Claude Desktop Official presets; refreshed partner links and default models / pricing across apps; upgraded the default Claude Opus model line to 4.8 and GPT defaults to 5.5 where applicable.
+- **Usage and docs polish**: Usage Dashboard updates now react immediately when logs are written, custom usage-script summaries and subagent session-log accounting were fixed, Traditional Chinese UI localization landed, and a German README plus expanded Claude Desktop / Codex Chat / tool-management manuals were added.
+- **Proxy and conversion hardening**: fixed Codex Chat reasoning / cache / usage edge cases, DeepSeek Anthropic tool-thinking history, Claude-compatible empty `tool_calls` streams, managed-account takeover auth, MiMo reasoning output, Gemini Native tool-call replay, and several panic-prone proxy paths.
+
+---
+
+## Added
+
+### Codex Chat Completions Routing
+
+Codex providers can now be served by upstreams that only speak the OpenAI Chat Completions API. CC Switch's local proxy converts Codex's outgoing Responses requests into Chat Completions and rebuilds the Chat response (both JSON and SSE) back into Responses shape, preserving `reasoning_content`, inline `<think>` blocks, streamed reasoning summaries, tool calls, and `previous_response_id` follow-ups. A bounded Codex Chat history cache restores tool calls before their tool outputs.
+
+> 💡 Special thanks to [@EldenPdx](https://github.com/EldenPdx) for PR [#2804](https://github.com/farion1231/cc-switch/pull/2804): this feature's Chat ↔ Responses format conversion references the implementation in his PR.
+
+### 22 Codex Third-Party Provider Presets with Chat Routing
+
+Enabled Chat Completions routing with explicit model catalogs for major Chinese/Asian providers — DeepSeek, Zhipu GLM (+ en), Kimi, MiniMax (+ en), StepFun (+ en), Baidu Qianfan Coding Plan, Bailian, ModelScope, Longcat, BaiLing, Xiaomi MiMo (+ Token Plan), Volcengine Agentplan, BytePlus, DouBao Seed, SiliconFlow (+ en), Novita AI, and Nvidia. Each preset declares its context window so the UI can size the model-mapping rows.
+
+### Codex Model Mapping Table
+
+Codex provider forms now expose a model catalog (model + display name + context window per row) that is the single source of truth for the upstream model list, projected to `~/.codex/cc-switch-model-catalog.json`.
+
+### Codex Chat Providers in Stream Check
+
+Stream Check now probes Chat-format Codex providers against `/chat/completions` with a Chat-shaped body instead of `/v1/responses`, and aligns its URL fallback order with the production `CodexAdapter` (origin-only base URLs hit `/v1/<endpoint>` first) so a non-404 error on the bare path no longer flags a working provider as down.
+
+### Codex Chat Reasoning Auto-Detection
+
+When a Codex provider is served through Chat Completions routing, CC Switch now auto-detects the upstream's reasoning interface from its name, base URL, and model — injecting the correct thinking parameter (`thinking:{type}`, `enable_thinking`, `reasoning_split`, top-level `reasoning_effort`, or OpenRouter's native `reasoning:{effort}` object) with no manual setup. Aggregator/hosting platforms (OpenRouter, SiliconFlow) are matched platform-first, since the same model can expose different reasoning controls on different platforms. Providers that only expose a thinking on/off switch (Kimi, GLM, Qwen, MiniMax, MiMo, SiliconFlow) drop the effort _level_ instead of forwarding an unsupported field — so changing Codex's reasoning effort has no effect for them — while providers with real effort tiers (DeepSeek, OpenRouter, and StepFun's `step-3.5-flash-2603` only) pass the level through. OpenRouter specifically uses the native `reasoning:{effort}` object, clamps `max` to `xhigh` (its enum has no `max`), and forwards an explicit `effort:"none"` so reasoning can be turned off.
+
+### Codex Goal Mode and Remote Compaction Controls
+
+Codex config editing now exposes a Goal Mode toggle and a Remote Compaction toggle for third-party providers; new Codex templates default to `disable_response_storage = true` while still allowing explicit goal support.
+
+### Xiaomi MiMo Token Plan Presets
+
+Added Xiaomi MiMo Token Plan presets with specs aligned to the official documentation (#2803, thanks @BlueOcean223).
+
+### Claude Desktop Official Preset
+
+Added a Claude Desktop Official preset that restores the native Claude Desktop login, plus a localized Claude Desktop user guide (en / zh / ja).
+
+### Managed CLI Tool Lifecycle
+
+Added silent install / update commands for managed CLI tools, latest-version checks, per-tool and batch actions, update-all, and diagnostics for multiple installations across PATH, Homebrew, npm, pnpm, bun, volta, fnm, nvm, scoop, WinGet, Windows native paths, and WSL.
+
+### Source-Aware Tool Diagnostics
+
+The Settings / About surface can now diagnose conflicting tool installations, show the concrete install source and version for each path, and generate backend-planned upgrade commands anchored to the actual installation source.
+
+### Real-Time Usage Refresh
+
+The backend now emits `usage-log-recorded` when proxy logs, session-log syncs, or rollups write usage data; Usage Dashboard listens for that event and invalidates its queries immediately instead of waiting for the next polling interval (#3027, thanks @in30mn1a).
+
+### Traditional Chinese Localization
+
+Added `zh-TW` UI localization and a settings language option (#3093, thanks @LaiYueTing).
+
+### German README
+
+Added `README_DE.md` and linked it from the existing README language switchers (#2994, thanks @flitzrrr).
+
+### New Partner Presets
+
+Added APIKEY.FUN, APINebula, AtlasCloud, and SudoCode partner presets across the supported app surfaces, with partner copy, icons, and README entries.
+
+---
+
+## Changed
+
+### Codex Third-Party Providers Unified into a "custom" History Bucket
+
+Codex filters resume history by `model_provider`, so switching between provider-specific ids made past sessions appear to vanish. All third-party providers now normalize to a single stable `custom` bucket (reserved built-in ids like `openai` / `ollama` are preserved), with a one-shot device migration that rewrites historical JSONL sessions and the `state_5.sqlite` threads table and backs up originals under `~/.cc-switch/backups/codex-history-provider-migration-v1/`.
+
+### Codex Provider Form Simplified
+
+Removed the API Format selector from the Codex form (`wire_api` is always `responses`, so the selector misleadingly implied a protocol change); the model mapping table is now the only source of truth with no hidden default entries, and the form notes that a Codex restart is required after catalog changes since `model_catalog_json` is loaded at startup. Only the "Needs Local Routing" toggle remains.
+
+### Codex Local Routing Toggle Hints Rewritten
+
+Reframed the OFF / ON hints as action guidance (when to enable) rather than scenario descriptions, synced across zh / en / ja.
+
+### Codex Live Config Preservation
+
+Live Codex config reads no longer force-rewrite a user's `model_provider` field, and provider-scoped `experimental_bearer_token` handling now preserves OAuth login state when switching between third-party providers.
+
+### Tool Install / Upgrade Strategy
+
+Managed tool installation now prefers official native installers where available, falls back to package managers when appropriate, runs self-update first for compatible tools, anchors upgrades to the detected install source, and locks duplicate batch actions while work is in flight.
+
+### About Page Becomes Tool Management
+
+The About settings page now presents installed / latest versions, install and update actions, conflict diagnostics, WSL shell preferences, and clearer status for broken or unrunnable tools.
+
+### Default Models and Pricing Refreshed
+
+Upgraded the default Claude Opus model to 4.8, moved GPT-based presets and templates to GPT-5.5 where applicable, refreshed pricing seeds, aligned Claude Desktop model mapping with Claude Code's three-role tiers, and renamed the OpenCode Go preset to drop a stale model suffix.
+
+### Partner Links Refreshed
+
+Updated ShengSuanYun referral links, Atlas Cloud UTM links, and partner copy across README locales and provider metadata.
+
+### Homebrew Official Cask Installation
+
+Installation simplified to `brew install --cask cc-switch` now that CC Switch is in the official Homebrew repository; the personal-tap requirement was removed from all READMEs.
+
+### Shared Frontend Utilities
+
+Replaced JSON stringify / parse deep-copy patterns with a shared `deepClone` helper and extracted a shared `useTauriEvent` hook (#3140, thanks @ChongBiaoZhang).
+
+---
+
+## Fixed
+
+### Codex Chat Error Responses Converted to Responses Envelope
+
+The Codex Chat-to-Responses bridge previously passed upstream error bodies through untouched, leaving Codex clients unable to recognize MiniMax `base_resp`, raw OpenAI Chat errors, or plain-text / HTML error pages. Errors are now regularized into the standard `{error: {message, type, code, param}}` envelope with the original HTTP status preserved; non-JSON bodies are wrapped and truncated to 1KB at a UTF-8 char boundary. Also fixed a pre-existing append-vs-insert bug that emitted a duplicate `Content-Type` header on rewritten JSON bodies.
+
+### Codex Mid-Stream System Messages Collapsed
+
+MiniMax's OpenAI-compatible endpoint strict-rejects any non-leading `system` message (error 2013). All `system` fragments are now collapsed into a single leading message (joined in original order), losslessly for permissive backends too.
+
+### Codex Model Catalog Wiped After Restart
+
+Editing the active Codex provider triggered a live read that omitted `modelCatalog`, so a subsequent save silently destroyed user-configured model mappings. Live reads now reverse-parse the on-disk catalog projection to round-trip the same shape the save path writes.
+
+### Codex Model Catalog Infinite Render Loop
+
+Broke a bidirectional sync cycle between the catalog table and its parent state that caused severe UI jittering when adding or editing entries.
+
+### Codex Chat Preserves User-Selected Catalog Model
+
+A model the client selects from the catalog (e.g. via `/model`) is no longer overwritten by `config.toml`'s default model.
+
+### Codex Chat Reasoning and Cache Stability
+
+Restored a unique call-id fallback when Codex omits or rewrites `previous_response_id`, stopped deriving cache identity from `previous_response_id`, and canonicalized parseable JSON string payloads in tool conversions for stable prefix-cache reuse.
+
+### Codex Chat Streaming Usage Recovered
+
+The Responses-to-Chat conversion now injects `stream_options.include_usage` (merging into any client-provided `stream_options`) when a request is streaming, so OpenAI-compatible upstreams like Kimi and MiniMax emit the trailing usage chunk again. Previously their streamed token / cost / cache stats were recorded as zero on the Codex Chat path.
+
+### Codex Chat Tool-Call Reasoning Backfill
+
+Thinking models like Kimi/Moonshot and DeepSeek reject an assistant message that carries `tool_calls` without a non-empty `reasoning_content`. When cross-turn history recovery misses (proxy restart, ambiguous `call_id`, or a turn with no upstream reasoning), a placeholder `reasoning_content` is now backfilled in a final pass — genuine trailing reasoning still attaches first — so the request no longer fails with `reasoning_content is missing in assistant tool call message`.
+
+### Managed-Account Claude Takeover Auth
+
+Managed-account providers (GitHub Copilot / Codex OAuth) now drop token env keys and write only the `ANTHROPIC_API_KEY` placeholder when taking over Claude Live config, with an outbound guard that refuses to send the `PROXY_MANAGED` placeholder upstream.
+
+### Claude Desktop Profile Sync During Takeover
+
+Claude Desktop profile data is now synced during proxy takeover, model routes align with the Claude Code three-role tiers, and the Cowork egress profile has been corrected (#3157, #3172, thanks @MelorTang, @JGSphaela).
+
+### Managed-Account Takeover Model Fields
+
+Local Routing now sources takeover model fields from the target provider on managed accounts instead of carrying stale model values.
+
+### DeepSeek Anthropic Tool Thinking History
+
+Normalized DeepSeek Anthropic-compatible tool-thinking history so later turns can replay reasoning / tool-call context without malformed messages (#3203, thanks @Q3yp).
+
+### Claude-Compatible Empty Tool Calls in Streams
+
+Fixed a Claude-compatible streaming edge case where an empty `tool_calls` array reset block state and broke streamed responses (#2915, thanks @zhizhuowq).
+
+### MiMo Reasoning for Claude Code Proxy
+
+Added MiMo `reasoning_content` support on the Claude Code proxy path (#2990, thanks @zhangyapu1).
+
+### Gemini Native Tool-Call Robustness
+
+Fixed `functionResponse.name` resolution (422) and `thought_signature` replay (400) for synthesized tool-call IDs in long multi-turn sessions (#2814, thanks @Tiancrimson).
+
+### Session Log Subagent Token Accounting
+
+`collect_jsonl_files()` now scans subagent JSONL logs that were previously missed, so subagent token usage is counted in session cost (session-log mode only) (#2821, thanks @LaoYueHanNi).
+
+### Usage Dashboard / Sync Stability
+
+Fixed a Codex usage-sync panic on non-ASCII model names, custom usage-script summaries, and missing real-time refresh after usage rollups (#3027, #3129, thanks @in30mn1a, @hanhan3344).
+
+### ZhiPu Coding-Plan Quota Tier Ordering
+
+When the 5-hour bucket is at 0% utilization, ZhiPu's API omits `nextResetTime`; the old `i64::MAX` sentinel sorted those entries last, letting the weekly bucket incorrectly claim the five-hour slot. Tiers now sort so a missing `nextResetTime` maps to the five-hour bucket, so tray and usage quota display stays correct for ZhiPu coding plans.
+
+### Skills Install by Key
+
+Installing from skills.sh search results now uses the unique key instead of the directory name, so skills that share a directory name install the correct one (#2784, thanks @zhaomoran); also fixed a skill sync copy fallback (#2791, thanks @rogerdigital).
+
+### Usage Price Input Precision
+
+Reduced the price input step to 0.0001 so sub-cent costs like DeepSeek cache reads can be entered (#2793, closes #2503, thanks @rogerdigital).
+
+### Ghostty Clean Window Launch
+
+Ghostty now opens a single clean window instead of cloning existing tabs, and other terminals open a new window via `open -na` (#2801, closes #2798, thanks @luw2007).
+
+### Tool Version and Update Reliability
+
+Version probing no longer masks unrunnable installs, prerelease tools are handled correctly in version checks, batch updates run per tool, install / update buttons stay locked during preflight, anchored upgrade branches enforce absolute paths, and WSL installer paths use native Unix installers when needed.
+
+### Codex mise Detection
+
+Fixed Codex mise environment detection (#2822, thanks @iambinlin).
+
+### Codex Archived Sessions
+
+Codex archived sessions are now included in session discovery (#2861, thanks @nanmen2).
+
+### Codex Chat Empty Tool Arguments
+
+Empty tool-call argument payloads are coerced to `{}` during Codex Chat conversion so upstreams and clients receive valid JSON.
+
+### Claude Provider Deeplink Imports
+
+Importing Claude providers through deeplinks now preserves custom environment fields (#2928, thanks @doutuifei).
+
+### OMO Recommended Models
+
+Synced OMO recommended models with upstream defaults and improved Fill Recommended feedback.
+
+### ShengSuanYun Model IDs Prefixed for Routing
+
+ShengSuanYun (胜算云) presets now carry the vendor prefixes the upstream gateway requires — `anthropic/…`, `google/…`, and `openai/…` (e.g. `anthropic/claude-sonnet-4.6`, `google/gemini-3.1-pro-preview`) — across the Claude Code, Claude Desktop, Codex, Gemini, OpenCode, and OpenClaw presets, including the Claude Code routing env (`ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_{HAIKU,SONNET,OPUS}_MODEL`), so they resolve to valid upstream models instead of failing to route.
+
+### ClaudeAPI Model Test Re-Enabled
+
+Reclassified the ClaudeAPI preset (Claude Code and Claude Desktop) from `third_party` to `aggregator` so its model test button is no longer disabled by the third-party Claude gate; the partner star is unaffected since it is driven by `isPartner`, not category.
+
+### About Version Check
+
+Version checks now handle prerelease tool versions without misclassifying update state.
+
+### App Switcher Text Clipping
+
+Removed a fixed width constraint that clipped app-switcher text (#3161, thanks @loocor).
+
+### useEffect Race Condition
+
+Added an active-flag pattern to App.tsx effects to prevent listener leaks on unmount, and guarded against storing `undefined` language in localStorage (#2827, thanks @Zylo206).
+
+---
+
+## Removed
+
+### LionCC Sponsor and Presets
+
+Removed the LionCC sponsor entry and LionCCAPI presets across READMEs, provider configs, and locales (icon asset retained).
+
+### AICoding Partner Entry
+
+Removed the AICoding partner from README sponsor listings, provider presets, and i18n metadata.
+
+### Kimi For Coding Codex Preset
+
+Removed the Kimi For Coding preset from the Codex preset catalog.
+
+### CLI Uninstall Command Hints
+
+Dropped generated CLI uninstall command hints from the tool-management UI while keeping conflict diagnostics visible.
+
+---
+
+## Docs
+
+### Codex Chat Provider Support
+
+Documented Chat Completions routing, provider support, reasoning auto-detection, and Local Routing guidance in the changelog and user manual.
+
+### Settings Manual Refresh
+
+Updated settings documentation for the new managed tool lifecycle and Hermes installer behavior.
+
+### Claude Desktop Guide
+
+Added localized Claude Desktop guide pages and screenshots for provider setup, import, model mapping, and Local Routing context.
+
+### Installation Docs
+
+Updated installation docs and READMEs to recommend the official Homebrew cask and refreshed the v3.15.0 release-note imposter-site warning wording across locales.
+
+---
+
+## ⚠️ Upgrade Notes
+
+### One-Shot Codex History Migration
+
+The first launch after upgrading runs a one-shot migration of Codex history: third-party providers are normalized into the `custom` bucket and historical JSONL sessions plus the `state_5.sqlite` threads table are rewritten. Originals are backed up under `~/.cc-switch/backups/codex-history-provider-migration-v1/`. This step fixes the "past sessions vanish after switching provider" problem — history resumes correctly after the migration.
+
+### Codex Catalog Changes Require a Restart
+
+Codex loads `model_catalog_json` at startup, so after editing the model mapping table in CC Switch you must **restart Codex** for the new catalog to take effect.
+
+### Reasoning Effort May Have No Effect for Chat-Routing Providers
+
+For providers that only expose a thinking on/off switch (Kimi, GLM, Qwen, MiniMax, MiMo, SiliconFlow), changing the reasoning effort in Codex (`model_reasoning_effort`: low / medium / high) **has no effect** — CC Switch will not forward an unsupported effort field to them. Only providers with real effort tiers (DeepSeek, OpenRouter, and StepFun's `step-3.5-flash-2603` only) actually honor the level.
+
+### Default Models Upgraded to Opus 4.8 / GPT-5.5
+
+The default Claude Opus model line is upgraded to 4.8 and GPT defaults to 5.5 where applicable. If you rely on a pinned older default model, check the model fields of the relevant presets / templates after upgrading.
+
+---
+
+## ⚠️ Risk Notice
+
+This release inherits the risk notices originally introduced in v3.12.3 / v3.13.0 / v3.15.0 for reverse-proxy-style features.
+
+**GitHub Copilot Reverse Proxy**: Using Copilot's reverse-proxy path may violate GitHub / Microsoft's terms of service. See the [v3.12.3 release notes](v3.12.3-en.md#️-risk-notice) for details.
+
+**Codex OAuth Reverse Proxy**: Using the Codex OAuth reverse proxy with a ChatGPT subscription may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details.
+
+**Codex Third-Party Provider Chat Routing**: Converting and forwarding Codex requests through CC Switch's local proxy to a third-party provider exposes those requests to that provider's billing, compliance, and data-retention policies — read the target provider's terms of service before using.
+
+**Claude Desktop Third-Party Provider Switching via Proxy Gateway**: Routing Claude Desktop traffic through CC Switch's in-app proxy gateway to a third-party provider exposes those requests to that provider's billing, compliance, and data-retention policies — read the target provider's terms of service before using.
+
+By enabling these features, users **accept all associated risks**. CC Switch is not responsible for any account restrictions, warnings, or service suspensions that result from using these features.
+
+---
+
+## Download & Installation
+
+Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) to download the appropriate version.
+
+### System Requirements
+
+| OS      | Minimum Version              | Architecture                        |
+| ------- | ---------------------------- | ----------------------------------- |
+| Windows | Windows 10 or later          | x64                                 |
+| macOS   | macOS 12 (Monterey) or later | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | See table below              | x64 / ARM64                         |
+
+### Windows
+
+| File                                     | Description                                           |
+| ---------------------------------------- | ----------------------------------------------------- |
+| `CC-Switch-v3.16.0-Windows.msi`          | **Recommended** - MSI installer, supports auto-update |
+| `CC-Switch-v3.16.0-Windows-Portable.zip` | Portable, extract and run, no registry writes         |
+
+### macOS
+
+| File                             | Description                                             |
+| -------------------------------- | ------------------------------------------------------- |
+| `CC-Switch-v3.16.0-macOS.dmg`    | **Recommended** - DMG installer, drag into Applications |
+| `CC-Switch-v3.16.0-macOS.zip`    | Extract and drag into Applications, Universal Binary    |
+| `CC-Switch-v3.16.0-macOS.tar.gz` | For Homebrew installation and auto-update               |
+
+> macOS builds are Apple code-signed and notarized — install directly.
+
+### Homebrew (macOS)
+
+> 🎉 CC Switch is now available in the official Homebrew cask repository — no need to add a custom tap!
+
+```bash
+brew install --cask cc-switch
+```
+
+Update:
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+> Linux artifacts are published for both **x86_64** and **ARM64** (`aarch64`). The architecture is included in the asset filename — pick the one matching your machine's `uname -m` output:
+>
+> - `CC-Switch-v3.16.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+> - `CC-Switch-v3.16.0-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| Distribution                            | Recommended | Installation                                                           |
+| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` or `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` or `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                    | `.AppImage` | Add execute permission and run, or use AUR                             |
+| Other distros / not sure                | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |
@@ -0,0 +1,434 @@
+# CC Switch v3.16.0
+
+> Codex 向けに Chat Completions → Responses フォーマット変換を追加（Codex で DeepSeek・Kimi・GLM が使えるようになりました！）、Codex プロバイダーの身元と履歴を統一、アプリ管理パネルの全方位強化、パートナープリセットの拡張、デフォルトモデル / 価格マトリクスを GPT-5.5 と Claude Opus 4.8 にアップグレード、プロキシ / フォーマット変換のロバスト性強化
+
+**[English →](v3.16.0-en.md) | [中文 →](v3.16.0-zh.md)**
+
+---
+
+## 利用ガイド
+
+本リリースの主役となる 2 つの機能は、**Codex サードパーティプロバイダーの Chat Completions ルーティング**と**アプリ内の管理対象 CLI ツール管理**です。OpenAI Chat プロトコルにしか対応していないプロバイダー（DeepSeek、Kimi、MiniMax など）を Codex で直接使いたい場合、またはアプリ内で CLI ツールの一括インストール / アップグレードをしたい場合は、まずこちらをご覧ください：
+
+- **[Codex で DeepSeek を使う: ローカルルーティング実践ガイド](../guides/codex-deepseek-routing-guide-ja.md)** —— DeepSeek 内蔵プリセットを例に、Codex プロバイダーの追加、ローカルルーティングの有効化、リクエスト転送の確認までを説明します。
+- **[Codex プロバイダーの追加: Chat Completions ルーティングとモデルマッピング](../user-manual/ja/2-providers/2.1-add.md)** —— 「ローカルルーティングが必要」トグル、モデルマッピングテーブル、思考能力（reasoning）の自動判別までの一連の流れを説明しています。
+- **[設定 → バージョン情報: 管理対象 CLI ツール管理](../user-manual/ja/1-getting-started/1.5-settings.md)** —— バージョン検出、個別アップグレード / 全体アップグレード、競合診断、インストール元にアンカーされたアップグレードコマンドを説明しています。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一の公式チャネル（必ずお読みください）
+>
+> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。最近、CC Switch の名を騙って課金を要求したり認証情報を収集する偽サイトが複数確認されており、一部のユーザーには既に金銭的被害が発生しています。本ソフトウェアは下記の公式チャネルからのみ入手してください：
+>
+> | チャネル     | 唯一の公式                                                                     |
+> | ------------ | ------------------------------------------------------------------------------ |
+> | 公式サイト   | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者         | **[@farion1231](https://github.com/farion1231)**                               |
+> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は、直ちに取引を中止し、偽サイトを速やかに削除できるよう GitHub Issues からご報告ください。
+
+---
+
+## 概要
+
+CC Switch v3.16.0 の v3.15.0 以降の開発のコアは、**サードパーティ Codex プロバイダーを Chat Completions ルーティングによって一等市民へ昇格させること**です。Codex はネイティブには OpenAI Responses API と GPT 系モデルしか認識しませんが、本リリースでは CC Switch のローカルプロキシが Codex の送出する Responses リクエストを Chat Completions に変換し、JSON と SSE のストリーミングレスポンスを Responses 形態へ再構築します。その道中で `reasoning_content` / インライン `<think>` ブロック / ストリーミング推論サマリー / ツール呼び出し / `previous_response_id` の継続を保持し、エラーエンベロープを正規化し、Stream Check で Chat 形式プロバイダーを正しくプローブします。あわせて明示的なモデルカタログ付きの 22 個の Chat ルーティングプリセット（DeepSeek、Zhipu GLM、Kimi、MiniMax、StepFun、Baidu Qianfan、Bailian、ModelScope、Longcat、BaiLing、Xiaomi MiMo、Volcengine Agentplan、BytePlus、DouBao Seed、SiliconFlow、Novita AI、Nvidia など）を出荷します。
+
+Codex サードパーティプロバイダーの**身元と履歴**は、本リリースで統一・堅牢化されました: すべてのサードパーティプロバイダーが安定した `custom` model-provider バケットに正規化され、過去の JSONL セッションと `state_5.sqlite` のスレッドテーブルを書き換える一回限りのデバイスマイグレーション（オリジナルは `~/.cc-switch/backups/` 配下にバックアップ）を提供することで、プロバイダー id の変更によって過去のセッションが消えたように見える問題を防ぎます。あわせて、live 読み取り / 切り替えの際に OAuth ログイン状態、ユーザーが選択したカタログモデル、ユーザー定義のプロバイダー id が上書きされる問題も修正しました。
+
+本リリースではさらに、**アプリ内蔵の受託 CLI ツールライフサイクル**を追加しました: 設定の「バージョン情報」タブが Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes のツール管理パネルに昇格し、サイレントインストール / 更新、全体アップグレード、競合診断、インストール元を考慮したアンカー型アップグレード、WSL の取り扱い、「インストール済みだが実行できない」状態の可視化に対応します。
+
+プロバイダーエコシステムとモデルマトリクスも並行してリフレッシュされました: APIKEY.FUN、APINebula、AtlasCloud、SudoCode、Xiaomi MiMo Token Plan、Claude Desktop 公式プリセットを追加; 各アプリのパートナーリンクとデフォルトモデル / 価格をリフレッシュ; デフォルトの Claude Opus ラインを **4.8** に、該当箇所の GPT デフォルトを **5.5** にアップグレード。さらに、Usage の可観測性、繁体字中国語ローカライズ、ドキュメント、プロキシ / フォーマット変換のロバスト性についても多くの改善と修正を行いました。
+
+**リリース日**: 2026-05-29
+
+**Stats**: 101 commits | 221 files changed | +27,063 insertions | -3,052 deletions
+
+---
+
+## ハイライト
+
+- **Codex Chat Completions ルーティング**: Codex プロバイダーを OpenAI 互換の Chat Completions 上流で提供できるようになりました。CC Switch は Codex の Responses リクエストを Chat Completions に変換し、JSON と SSE レスポンスを Responses 形態へ再構築し、reasoning / `<think>` / ツール呼び出し状態を保持し、エラーエンベロープを正規化し、Stream Check で Chat 形式プロバイダーを正しくプローブします
+- **Codex サードパーティプロバイダーの状態を統一しより安全に**: サードパーティ Codex プロバイダーは安定した `custom` model-provider バケットを共有するようになり、過去の JSONL セッションと `state_5.sqlite` スレッドの一回限りのマイグレーションに加え、live 読み取り / 切り替え時に OAuth ログイン状態、ユーザー選択のカタログモデル、ユーザー定義のプロバイダー id を保持する修正を実施
+- **受託 CLI ツール管理**: 「バージョン情報」ページが Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes のツール管理パネルに昇格し、インストール / 更新アクション、全体アップグレード、競合診断、インストール元にアンカーしたアップグレード、WSL の取り扱い、「インストール済みだが実行できない」状態の可視化を搭載
+- **プロバイダーエコシステムとモデルマトリクスのリフレッシュ**: APIKEY.FUN、APINebula、AtlasCloud、SudoCode、Xiaomi MiMo Token Plan、Claude Desktop 公式プリセットを追加; 各アプリのパートナーリンクとデフォルトモデル / 価格をリフレッシュ; デフォルトの Claude Opus を 4.8 に、該当箇所の GPT デフォルトを 5.5 にアップグレード
+- **Usage とドキュメントの磨き込み**: Usage ダッシュボードがログ書き込み時に即座に反応して更新、カスタム usage スクリプトのサマリーと subagent セッションログの計上を修正、繁体字中国語 UI ローカライズが着地、ドイツ語 README と拡充された Claude Desktop / Codex Chat / ツール管理マニュアルを追加
+- **プロキシと変換のハードニング**: Codex Chat の推論 / キャッシュ / usage のエッジケース、DeepSeek Anthropic ツール思考履歴、Claude 互換の空 `tool_calls` ストリーム、受託アカウントのテイクオーバー認証、MiMo 推論出力、Gemini Native ツール呼び出しの再生、いくつかのパニックしやすいプロキシパスを修正
+
+---
+
+## 追加機能
+
+### Codex Chat Completions ルーティング
+
+Codex プロバイダーを、OpenAI Chat Completions API しか話せない上流で提供できるようになりました。CC Switch のローカルプロキシは Codex の送出する Responses リクエストを Chat Completions に変換し、Chat レスポンス（JSON と SSE の両方）を Responses 形態へ再構築します。その際、`reasoning_content`、インライン `<think>` ブロック、ストリーミング推論サマリー、ツール呼び出し、`previous_response_id` の継続を保持します。有界の Codex Chat 履歴キャッシュが、ツール出力の前に対応するツール呼び出しを復元します。
+
+> 💡 [@EldenPdx](https://github.com/EldenPdx) の PR [#2804](https://github.com/farion1231/cc-switch/pull/2804) に特別な感謝を: 本機能の Chat ↔ Responses フォーマット変換の実装は、彼の PR の実装を参考にしています。
+
+### Chat ルーティング対応の 22 個の Codex サードパーティプロバイダープリセット
+
+主要な中国 / アジア系プロバイダー向けに、明示的なモデルカタログ付きで Chat Completions ルーティングを有効化しました —— DeepSeek、Zhipu GLM（+ 英語版）、Kimi、MiniMax（+ 英語版）、StepFun（+ 英語版）、Baidu Qianfan Coding Plan、Bailian、ModelScope、Longcat、BaiLing、Xiaomi MiMo（+ Token Plan）、Volcengine Agentplan、BytePlus、DouBao Seed、SiliconFlow（+ 英語版）、Novita AI、Nvidia。各プリセットは自身のコンテキストウィンドウを宣言するため、UI がモデルマッピング行のサイズを決定できます。
+
+### Codex モデルマッピングテーブル
+
+Codex プロバイダーフォームがモデルカタログ（行ごとに モデル + 表示名 + コンテキストウィンドウ）を公開するようになりました。これは上流モデルリストの唯一の信頼できる情報源であり、`~/.codex/cc-switch-model-catalog.json` に投影されます。
+
+### Stream Check の Codex Chat プロバイダー対応
+
+Stream Check は Chat 形式の Codex プロバイダーに対して、`/v1/responses` ではなく Chat 形態のボディで `/chat/completions` をプローブするようになりました。また URL のフォールバック順序を本番の `CodexAdapter` と揃え（origin のみの base URL はまず `/v1/<endpoint>` を叩く）、裸のパスでの 404 以外のエラーが、正常に動作しているプロバイダーをダウンと誤判定しなくなりました。
+
+### Codex Chat 思考能力（Reasoning）の自動判別
+
+Codex プロバイダーが Chat Completions ルーティング経由で提供される場合、CC Switch は上流の推論インターフェースを名前、base URL、モデル名から**自動判別**し、正しい思考パラメータ（`thinking:{type}`、`enable_thinking`、`reasoning_split`、トップレベルの `reasoning_effort`、または OpenRouter のネイティブ `reasoning:{effort}` オブジェクト）を手動設定なしで注入します。アグリゲーター / ホスティングプラットフォーム（OpenRouter、SiliconFlow）は**プラットフォーム優先**でマッチします。同じモデルでもプラットフォームによって異なる推論コントロールを公開する場合があるためです。思考の オン / オフ スイッチしか公開しないプロバイダー（Kimi、GLM、Qwen、MiniMax、MiMo、SiliconFlow）は、未対応のフィールドを転送する代わりに effort の*レベル*を破棄します —— そのため Codex の推論 effort を変更してもこれらには効果がありません —— 一方、本物の effort 階層を持つプロバイダー（DeepSeek、OpenRouter、および StepFun の `step-3.5-flash-2603` のみ）はレベルを透過させます。OpenRouter は特にネイティブ `reasoning:{effort}` オブジェクトを使用し、`max` を `xhigh` にクランプし（その enum に `max` はない）、推論をオフにできるよう明示的に `effort:"none"` を転送します。
+
+### Codex Goal Mode とリモートコンパクション制御
+
+Codex の設定編集で、サードパーティプロバイダー向けに Goal Mode トグルとリモートコンパクション（Remote Compaction）トグルを公開するようになりました; 新規 Codex テンプレートはデフォルトで `disable_response_storage = true` としつつ、明示的な goal サポートも許可します。
+
+### Xiaomi MiMo Token Plan プリセット
+
+公式ドキュメントに準拠した仕様で Xiaomi MiMo Token Plan プリセットを追加しました (#2803, 感謝 @BlueOcean223)。
+
+### Claude Desktop 公式プリセット
+
+ネイティブの Claude Desktop ログインを復元する Claude Desktop 公式プリセットと、ローカライズされた Claude Desktop ユーザーガイド（en / zh / ja）を追加しました。
+
+### 受託 CLI ツールライフサイクル
+
+受託 CLI ツール向けに、サイレントインストール / 更新コマンド、最新バージョンチェック、ツール単位およびバッチアクション、全体アップグレード、そして PATH、Homebrew、npm、pnpm、bun、volta、fnm、nvm、scoop、WinGet、Windows ネイティブパス、WSL をまたいだ複数インストールの診断を追加しました。
+
+### インストール元を考慮したツール診断
+
+設定 / バージョン情報の画面で、競合するツールインストールを診断し、各パスの具体的なインストール元とバージョンを表示し、実際のインストール元にアンカーされたバックエンド計画のアップグレードコマンドを生成できるようになりました。
+
+### リアルタイム Usage 更新
+
+バックエンドは、プロキシログ、セッションログ同期、ロールアップが usage データを書き込んだ際に `usage-log-recorded` を発行するようになりました; Usage ダッシュボードはそのイベントを購読し、次のポーリング間隔を待たずに即座にクエリを無効化します (#3027, 感謝 @in30mn1a)。
+
+### 繁体字中国語ローカライズ
+
+`zh-TW` の UI ローカライズと設定の言語オプションを追加しました (#3093, 感謝 @LaiYueTing)。
+
+### ドイツ語 README
+
+`README_DE.md` を追加し、既存の README 言語スイッチャーからリンクしました (#2994, 感謝 @flitzrrr)。
+
+### 新しいパートナープリセット
+
+対応する各アプリ面に APIKEY.FUN、APINebula、AtlasCloud、SudoCode のパートナープリセットを、パートナー文面、アイコン、README エントリとともに追加しました。
+
+---
+
+## 変更
+
+### Codex サードパーティプロバイダーを "custom" 履歴バケットに統一
+
+Codex は復元履歴を `model_provider` でフィルタリングするため、プロバイダー固有の id 間を切り替えると過去のセッションが消えたように見えていました。すべてのサードパーティプロバイダーは単一の安定した `custom` バケットに正規化されるようになり（`openai` / `ollama` のような予約済みの組み込み id は保持）、過去の JSONL セッションと `state_5.sqlite` のスレッドテーブルを書き換え、オリジナルを `~/.cc-switch/backups/codex-history-provider-migration-v1/` 配下にバックアップする一回限りのデバイスマイグレーションを伴います。
+
+### Codex プロバイダーフォームの簡素化
+
+Codex フォームから API Format セレクターを削除しました（`wire_api` は常に `responses` であり、セレクターはプロトコルを変更できるかのように誤解を招くため）; モデルマッピングテーブルが唯一の信頼できる情報源となり、隠れたデフォルトエントリはなくなりました。`model_catalog_json` は起動時に読み込まれるため、カタログ変更後は Codex の再起動が必要である旨をフォームに明記しています。残るのは「ローカルルーティングが必要」トグルのみです。
+
+### Codex ローカルルーティングトグルのヒント書き直し
+
+OFF / ON のヒントを、シナリオの説明ではなくアクションのガイダンス（いつ有効化すべきか）として再構成し、zh / en / ja で同期しました。
+
+### Codex Live 設定の保持
+
+Codex の live 設定読み取りがユーザーの `model_provider` フィールドを強制的に書き換えなくなり、プロバイダースコープの `experimental_bearer_token` 処理がサードパーティプロバイダー間の切り替え時に OAuth ログイン状態を保持するようになりました。
+
+### ツールのインストール / アップグレード戦略
+
+受託ツールのインストールは、可能な場合は公式のネイティブインストーラーを優先し、適切な場合はパッケージマネージャーにフォールバックし、互換性のあるツールではまず self-update を実行し、アップグレードを検出されたインストール元にアンカーし、作業中は重複するバッチアクションをロックするようになりました。
+
+### 「バージョン情報」ページがツール管理に
+
+「バージョン情報」設定ページが、インストール済み / 最新バージョン、インストールおよび更新アクション、競合診断、WSL シェル設定、壊れている / 実行できないツールのより明確なステータスを表示するようになりました。
+
+### デフォルトモデルと価格のリフレッシュ
+
+デフォルトの Claude Opus モデルを 4.8 にアップグレードし、該当箇所の GPT ベースのプリセットとテンプレートを GPT-5.5 に移行し、価格シードをリフレッシュし、Claude Desktop のモデルマッピングを Claude Code の三ロール階層に揃え、OpenCode の Go プリセットを古いモデルサフィックスを落とすようリネームしました。
+
+### パートナーリンクのリフレッシュ
+
+ShengSuanYun の紹介リンク、Atlas Cloud の UTM リンク、各 README ロケールおよびプロバイダーメタデータのパートナー文面を更新しました。
+
+### Homebrew 公式 Cask インストール
+
+CC Switch が公式 Homebrew リポジトリに収録されたため、インストールを `brew install --cask cc-switch` に簡素化しました; 個人 tap の要件はすべての README から削除しました。
+
+### 共有フロントエンドユーティリティ
+
+JSON stringify / parse によるディープコピーのパターンを共有の `deepClone` ヘルパーに置き換え、共有の `useTauriEvent` フックを抽出しました (#3140, 感謝 @ChongBiaoZhang)。
+
+---
+
+## 修正
+
+### Codex Chat エラーレスポンスを Responses エンベロープに変換
+
+Codex Chat → Responses ブリッジは以前、上流のエラーボディをそのまま透過させていたため、Codex クライアントが MiniMax の `base_resp`、生の OpenAI Chat エラー、プレーンテキスト / HTML のエラーページを認識できませんでした。エラーは標準の `{error: {message, type, code, param}}` エンベロープに整形され、元の HTTP ステータスが保持されるようになりました; 非 JSON ボディはラップされ、UTF-8 文字境界で 1KB に切り詰められます。また、書き換え後の JSON ボディに重複する `Content-Type` ヘッダーを出力していた既存の append-vs-insert バグも修正しました。
+
+### Codex のストリーム中間の system メッセージを折りたたみ
+
+MiniMax の OpenAI 互換エンドポイントは、先頭以外の `system` メッセージを厳格に拒否します（エラー 2013）。すべての `system` 断片は単一の先頭メッセージに折りたたまれるようになりました（元の順序で結合）。寛容なバックエンドに対しても損失なく行われます。
+
+### 再起動後に Codex モデルカタログが消える問題
+
+アクティブな Codex プロバイダーを編集すると `modelCatalog` を省略した live 読み取りがトリガーされ、その後の保存がユーザー設定のモデルマッピングを無言で破壊していました。live 読み取りはディスク上のカタログ投影を逆解析し、保存パスが書き込むのと同じ形態をラウンドトリップするようになりました。
+
+### Codex モデルカタログの無限レンダリングループ
+
+カタログテーブルとその親 state の間の双方向同期サイクルを断ち切りました。これはエントリの追加や編集時に深刻な UI のジッターを引き起こしていました。
+
+### Codex Chat がユーザー選択のカタログモデルを保持
+
+クライアントがカタログから選択したモデル（例: `/model` 経由）が、`config.toml` のデフォルトモデルによって上書きされなくなりました。
+
+### Codex Chat の推論とキャッシュの安定性
+
+Codex が `previous_response_id` を省略または書き換える際の一意な call-id フォールバックを復元し、`previous_response_id` からキャッシュの同一性を導出するのをやめ、ツール変換でパース可能な JSON 文字列ペイロードを正規化して安定したプレフィックスキャッシュ再利用を実現しました。
+
+### Codex Chat のストリーミング usage を復旧
+
+Responses → Chat 変換が、リクエストがストリーミングの場合に `stream_options.include_usage` を注入する（クライアント提供の `stream_options` にマージ）ようになり、Kimi や MiniMax のような OpenAI 互換上流が末尾の usage チャンクを再び発行するようになりました。以前は、これらのストリーミングのトークン / コスト / キャッシュ統計が Codex Chat パスでゼロとして記録されていました。
+
+### Codex Chat ツール呼び出しの推論バックフィル
+
+Kimi/Moonshot や DeepSeek のような思考モデルは、空でない `reasoning_content` を伴わない `tool_calls` を持つ assistant メッセージを拒否します。ターンをまたいだ履歴復元が失敗した場合（プロキシ再起動、曖昧な `call_id`、または上流の推論がないターン）、最終パスでプレースホルダーの `reasoning_content` をバックフィルするようになりました —— 本物の末尾推論が先に付加されます —— そのためリクエストが `reasoning_content is missing in assistant tool call message` で失敗しなくなりました。
+
+### 受託アカウントの Claude テイクオーバー認証
+
+受託アカウントのプロバイダー（GitHub Copilot / Codex OAuth）は、Claude Live 設定をテイクオーバーする際にトークン環境変数キーを破棄し、`ANTHROPIC_API_KEY` プレースホルダーのみを書き込むようになりました。さらに、`PROXY_MANAGED` プレースホルダーを上流に送信するのを拒否するアウトバウンドガードを備えます。
+
+### テイクオーバー中の Claude Desktop プロファイル同期
+
+プロキシテイクオーバー中に Claude Desktop プロファイルデータが同期されるようになり、モデルルートが Claude Code の三ロール階層に揃い、Cowork egress プロファイルが修正されました (#3157, #3172, 感謝 @MelorTang, @JGSphaela)。
+
+### 受託アカウントのテイクオーバーモデルフィールド
+
+ローカルルーティングは、受託アカウントにおいて、古いモデル値を持ち回るのではなく、ターゲットプロバイダーからテイクオーバーモデルフィールドを取得するようになりました。
+
+### DeepSeek Anthropic ツール思考履歴
+
+DeepSeek Anthropic 互換のツール思考履歴を正規化し、後続のターンが不正なメッセージなしで推論 / ツール呼び出しコンテキストを再生できるようにしました (#3203, 感謝 @Q3yp)。
+
+### Claude 互換のストリーム内の空ツール呼び出し
+
+空の `tool_calls` 配列がブロック状態をリセットしてストリーミングレスポンスを壊す、Claude 互換のストリーミングエッジケースを修正しました (#2915, 感謝 @zhizhuowq)。
+
+### Claude Code プロキシ向けの MiMo 推論
+
+Claude Code プロキシパスで MiMo の `reasoning_content` サポートを追加しました (#2990, 感謝 @zhangyapu1)。
+
+### Gemini Native ツール呼び出しのロバスト性
+
+長いマルチターンセッションにおける合成ツール呼び出し ID の `functionResponse.name` 解決（422）と `thought_signature` 再生（400）を修正しました (#2814, 感謝 @Tiancrimson)。
+
+### セッションログの subagent トークン計上
+
+`collect_jsonl_files()` がこれまで見落とされていた subagent の JSONL ログをスキャンするようになり、subagent のトークン使用量がセッションコストに計上されるようになりました（セッションログモードのみ）(#2821, 感謝 @LaoYueHanNi)。
+
+### Usage ダッシュボード / 同期の安定性
+
+非 ASCII モデル名による Codex usage 同期パニック、カスタム usage スクリプトのサマリー、usage ロールアップ後のリアルタイム更新の欠落を修正しました (#3027, #3129, 感謝 @in30mn1a, @hanhan3344)。
+
+### ZhiPu Coding-Plan のクォータ階層の並び順
+
+5 時間バケットの使用率が 0% の場合、ZhiPu の API は `nextResetTime` を省略します; 古い `i64::MAX` センチネルはこれらのエントリを最後にソートしていたため、週次バケットが五時間スロットを誤って占有していました。階層は、`nextResetTime` の欠落が五時間バケットにマップされるようにソートされるようになり、ZhiPu の coding plan でトレイと usage クォータの表示が正しく保たれます。
+
+### スキルを key でインストール
+
+skills.sh の検索結果からインストールする際に、ディレクトリ名ではなく一意の key を使用するようになり、ディレクトリ名を共有するスキルでも正しいものがインストールされます (#2784, 感謝 @zhaomoran); スキル同期のコピーフォールバックも修正しました (#2791, 感謝 @rogerdigital)。
+
+### Usage 価格入力の精度
+
+価格入力のステップを 0.0001 に下げ、DeepSeek のキャッシュ読み取りのような 1 セント未満のコストも入力できるようにしました (#2793, #2503 をクローズ, 感謝 @rogerdigital)。
+
+### Ghostty のクリーンウィンドウ起動
+
+Ghostty は既存タブを複製する代わりに単一のクリーンウィンドウを開くようになり、他のターミナルは `open -na` 経由で新しいウィンドウを開きます (#2801, #2798 をクローズ, 感謝 @luw2007)。
+
+### ツールバージョンと更新の信頼性
+
+バージョンプローブが実行できないインストールを覆い隠さなくなり、プレリリースツールがバージョンチェックで正しく扱われ、バッチ更新がツール単位で実行され、インストール / 更新ボタンがプリフライト中ロックされ続け、アンカー型アップグレードブランチが絶対パスを強制し、WSL のインストーラーパスが必要に応じてネイティブ Unix インストーラーを使用するようになりました。
+
+### Codex の mise 検出
+
+Codex の mise 環境検出を修正しました (#2822, 感謝 @iambinlin)。
+
+### Codex のアーカイブ済みセッション
+
+Codex のアーカイブ済みセッションがセッション検出に含まれるようになりました (#2861, 感謝 @nanmen2)。
+
+### Codex Chat の空ツール引数
+
+空のツール呼び出し引数ペイロードが Codex Chat 変換時に `{}` に強制変換され、上流とクライアントが有効な JSON を受け取るようになりました。
+
+### Claude プロバイダーの deeplink インポート
+
+deeplink 経由で Claude プロバイダーをインポートする際に、カスタム環境フィールドが保持されるようになりました (#2928, 感謝 @doutuifei)。
+
+### OMO 推奨モデル
+
+OMO の推奨モデルを上流のデフォルトと同期し、「推奨を入力」のフィードバックを改善しました。
+
+### ShengSuanYun のモデル ID にルーティング用プレフィックスを付与
+
+ShengSuanYun（胜算云）プリセットが、上流ゲートウェイが要求するベンダープレフィックス —— `anthropic/…`、`google/…`、`openai/…`（例: `anthropic/claude-sonnet-4.6`、`google/gemini-3.1-pro-preview`）—— を、Claude Code、Claude Desktop、Codex、Gemini、OpenCode、OpenClaw の各プリセットにわたって持つようになりました。Claude Code のルーティング環境変数（`ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_{HAIKU,SONNET,OPUS}_MODEL`）も含まれるため、ルーティングに失敗するのではなく有効な上流モデルに解決されます。
+
+### ClaudeAPI モデルテストの再有効化
+
+ClaudeAPI プリセット（Claude Code と Claude Desktop）を `third_party` から `aggregator` に再分類し、サードパーティ Claude ゲートによってモデルテストボタンが無効化されないようにしました; パートナースターは `isPartner` によって駆動され、category には依存しないため影響を受けません。
+
+### バージョン情報のバージョンチェック
+
+バージョンチェックがプレリリースのツールバージョンを、更新状態を誤分類することなく扱えるようになりました。
+
+### App スイッチャーのテキスト切れ
+
+App スイッチャーのテキストを切り取っていた固定幅の制約を削除しました (#3161, 感謝 @loocor)。
+
+### useEffect の競合状態
+
+App.tsx の effects に active フラグのパターンを追加してアンマウント時のリスナーリークを防止し、localStorage に `undefined` の言語を保存しないようガードしました (#2827, 感謝 @Zylo206)。
+
+---
+
+## 削除
+
+### LionCC スポンサーとプリセット
+
+LionCC スポンサーエントリと LionCCAPI プリセットを、各 README、プロバイダー設定、ロケールにわたって削除しました（アイコンアセットは保持）。
+
+### AICoding パートナーエントリ
+
+AICoding パートナーを README スポンサー一覧、プロバイダープリセット、i18n メタデータから削除しました。
+
+### Kimi For Coding の Codex プリセット
+
+Kimi For Coding プリセットを Codex プリセットカタログから削除しました。
+
+### CLI アンインストールコマンドのヒント
+
+ツール管理 UI から生成された CLI アンインストールコマンドのヒントを削除しつつ、競合診断は引き続き表示します。
+
+---
+
+## ドキュメント
+
+### Codex Chat プロバイダーサポート
+
+Chat Completions ルーティング、プロバイダーサポート、推論の自動判別、ローカルルーティングのガイダンスを changelog とユーザーマニュアルにドキュメント化しました。
+
+### 設定マニュアルのリフレッシュ
+
+新しい受託ツールライフサイクルと Hermes インストーラーの挙動について、設定ドキュメントを更新しました。
+
+### Claude Desktop ガイド
+
+プロバイダー設定、インポート、モデルマッピング、ローカルルーティングのコンテキストについて、ローカライズされた Claude Desktop ガイドページとスクリーンショットを追加しました。
+
+### インストールドキュメント
+
+公式 Homebrew cask を推奨するようインストールドキュメントと README を更新し、v3.15.0 リリースノートの偽サイト警告の文言を各ロケールでリフレッシュしました。
+
+---
+
+## ⚠️ アップグレード時の注意
+
+### Codex 履歴の一回限りのマイグレーション
+
+アップグレード後の初回起動で、Codex 履歴の一回限りのマイグレーションが実行されます: サードパーティプロバイダーが `custom` バケットに正規化され、過去の JSONL セッションと `state_5.sqlite` スレッドテーブルが書き換えられます。オリジナルは `~/.cc-switch/backups/codex-history-provider-migration-v1/` 配下にバックアップされます。このステップは「プロバイダー切り替え後に過去のセッションが消える」問題を修正するもので、マイグレーション後は履歴が正しく復元されます。
+
+### Codex のカタログ変更には再起動が必要
+
+Codex は `model_catalog_json` を起動時に読み込むため、CC Switch でモデルマッピングテーブルを編集した後は、新しいカタログを反映させるために **Codex を再起動**する必要があります。
+
+### Chat ルーティングのプロバイダーでは推論 effort が効かない場合がある
+
+思考の オン / オフ スイッチしか公開しないプロバイダー（Kimi、GLM、Qwen、MiniMax、MiMo、SiliconFlow）では、Codex で推論 effort（`model_reasoning_effort`: low / medium / high）を変更しても**効果がありません** —— CC Switch は未対応の effort フィールドをこれらに転送しません。本物の effort 階層を持つプロバイダー（DeepSeek、OpenRouter、および StepFun の `step-3.5-flash-2603` のみ）でのみ、レベルが実際に反映されます。
+
+### デフォルトモデルが Opus 4.8 / GPT-5.5 にアップグレード
+
+デフォルトの Claude Opus モデルラインが 4.8 に、該当箇所の GPT デフォルトが 5.5 にアップグレードされました。固定した古いデフォルトモデルに依存している場合は、アップグレード後に該当プリセット / テンプレートのモデルフィールドを確認してください。
+
+---
+
+## ⚠️ リスク通知
+
+本リリースは、リバースプロキシ系機能について v3.12.3 / v3.13.0 / v3.15.0 で提起されたリスク通知を継承します。
+
+**GitHub Copilot リバースプロキシ**: Copilot のリバースプロキシパスを使用すると、GitHub / Microsoft の利用規約に違反する可能性があります。詳細は [v3.12.3 リリースノート](v3.12.3-ja.md#️-リスクに関する注意事項) を参照してください。
+
+**Codex OAuth リバースプロキシ**: ChatGPT サブスクリプションを使用した Codex OAuth リバースプロキシは、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 リリースノート](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
+
+**Codex サードパーティプロバイダー Chat ルーティング**: CC Switch のローカルプロキシ経由で Codex のリクエストを変換し、サードパーティプロバイダーに転送する際、各プロバイダーの課金、コンプライアンス、データ保持に関する制約はそれぞれ異なります。利用前にターゲットプロバイダーの利用規約をお読みください。
+
+**Claude Desktop サードパーティプロバイダーのプロキシ切り替え**: CC Switch 内蔵プロキシゲートウェイ経由で Claude Desktop のリクエストをサードパーティプロバイダーに転送する際、サードパーティプロバイダーの課金、コンプライアンス、データ保持に関する制約はそれぞれ異なります。利用前にターゲットプロバイダーの利用規約をお読みください。
+
+ユーザーが上記機能を有効化することで、**すべてのリスクを自己責任で**受諾したものとみなされます。CC Switch は、これらの機能の使用に起因するアカウントの制限、警告、サービス停止について一切の責任を負いません。
+
+---
+
+## ダウンロード・インストール
+
+[Releases](https://github.com/farion1231/cc-switch/releases/latest) から対応バージョンをダウンロードしてください。
+
+### システム要件
+
+| OS      | 最小バージョン           | アーキテクチャ                      |
+| ------- | ------------------------ | ----------------------------------- |
+| Windows | Windows 10 以降          | x64                                 |
+| macOS   | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | 下表参照                 | x64 / ARM64                         |
+
+### Windows
+
+| ファイル                                 | 説明                                        |
+| ---------------------------------------- | ------------------------------------------- |
+| `CC-Switch-v3.16.0-Windows.msi`          | **推奨** - MSI インストーラー、自動更新対応 |
+| `CC-Switch-v3.16.0-Windows-Portable.zip` | ポータブル版、解凍して実行、レジストリ不要  |
+
+### macOS
+
+| ファイル                         | 説明                                                   |
+| -------------------------------- | ------------------------------------------------------ |
+| `CC-Switch-v3.16.0-macOS.dmg`    | **推奨** - DMG インストーラー、Applications にドラッグ |
+| `CC-Switch-v3.16.0-macOS.zip`    | 解凍して Applications にドラッグ、Universal Binary     |
+| `CC-Switch-v3.16.0-macOS.tar.gz` | Homebrew インストールと自動更新用                      |
+
+> macOS 版は Apple のコード署名および公証済みで、直接インストールして使用できます。
+
+### Homebrew（macOS）
+
+> 🎉 CC Switch は Homebrew 公式 cask リポジトリに収録されました。カスタム tap の追加は不要です！
+
+```bash
+brew install --cask cc-switch
+```
+
+更新:
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+> Linux 向けの成果物は **x86_64** と **ARM64**（`aarch64`）の両方が提供されます。ファイル名にアーキテクチャ識別子が含まれているため、`uname -m` の出力に応じて選択してください：
+>
+> - `CC-Switch-v3.16.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+> - `CC-Switch-v3.16.0-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| ディストリビューション                  | 推奨形式    | インストール方法                                                           |
+| --------------------------------------- | ----------- | -------------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` または `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` または `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                    |
+| Arch Linux / Manjaro                    | `.AppImage` | 実行権限を付与して実行、または AUR を使用                                  |
+| その他のディストリビューション / 不明   | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`                  |
@@ -0,0 +1,434 @@
+# CC Switch v3.16.0
+
+> 为 Codex 增加 Chat Completions -> Response 格式转换（你可以在 Codex 里使用 DeepSeek, Kimi, GLM 了！）、Codex 供应商身份与历史统一、应用管理面板全方位增强、合作伙伴预设扩张、默认模型 / 定价矩阵升级到 GPT-5.5 与 Claude Opus 4.8、代理与格式转换鲁棒性强化
+
+**[English →](v3.16.0-en.md) | [日本語版 →](v3.16.0-ja.md)**
+
+---
+
+## 使用攻略
+
+本版本最主打的两块能力是 **Codex 第三方供应商 Chat Completions 路由**与**应用内受管 CLI 工具管理**。如果你想让 DeepSeek、Kimi、MiniMax 这类只支持 OpenAI Chat 协议的供应商在 Codex 里直接可用，或者想在应用内一站式安装 / 升级 CLI 工具，建议先读这几篇：
+
+- **[在 Codex 中使用 DeepSeek：本地路由实战攻略](../guides/codex-deepseek-routing-guide-zh.md)** —— 以 DeepSeek 内置预设为例，演示从添加 Codex 供应商、开启本地路由到验证请求转发的完整路径。
+- **[添加 Codex 供应商：Chat Completions 路由与模型映射](../user-manual/zh/2-providers/2.1-add.md)** —— 覆盖「需要本地路由映射」开关、模型映射表、思考能力（reasoning）自适应识别的完整流程。
+- **[设置 → 关于：受管 CLI 工具管理](../user-manual/zh/1-getting-started/1.5-settings.md)** —— 覆盖版本检测、单独升级 / 全部升级、冲突诊断、按安装来源锚定的升级命令。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一官方渠道声明（请务必阅读）
+>
+> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。最近发现多个山寨网站冒用 CC Switch 名义诱导用户付费、收集账号信息，部分已造成实际经济损失。请仅通过下列官方渠道获取本软件：
+>
+> | 类别     | 唯一官方                                                                       |
+> | -------- | ------------------------------------------------------------------------------ |
+> | 官网     | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | 源码     | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | 下载     | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者     | **[@farion1231](https://github.com/farion1231)**                               |
+> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈，让我们能尽快下线相关山寨站点。
+
+---
+
+## 概览
+
+CC Switch v3.16.0 自 v3.15.0 以来的开发核心，是把**第三方 Codex 供应商通过 Chat Completions 路由升级为一等公民**。Codex 原生只认 OpenAI Responses API 与 GPT 系列模型，本版本让 CC Switch 的本地代理把 Codex 发出的 Responses 请求转换为上游的 Chat Completions，再把 JSON 与 SSE 流式响应重建回 Responses 形态，沿途保留 `reasoning_content` / 内联 `<think>` 块 / 流式推理摘要 / 工具调用 / `previous_response_id` 续接状态，并把错误信封规范化、在 Stream Check 中正确探测 Chat 格式供应商。配套上货 22 个带显式模型目录的 Chat 路由预设（DeepSeek、智谱 GLM、Kimi、MiniMax、StepFun、百度千帆、百炼、ModelScope、Longcat、百灵、小米 MiMo、火山 Agentplan、BytePlus、豆包 Seed、SiliconFlow、Novita AI、Nvidia 等）。
+
+Codex 第三方供应商的**身份与历史**这一版被统一并加固：所有第三方供应商现在归并到稳定的 `custom` model-provider 桶，并提供一次性设备迁移来改写历史 JSONL 会话与 `state_5.sqlite` 线程表（原文件备份在 `~/.cc-switch/backups/` 下），避免因供应商 id 变化导致过往会话"凭空消失"；同时修复了 live 读取 / 切换过程中 OAuth 登录态、用户选中的目录模型、用户自定义 provider id 被覆盖的问题。
+
+本版本还新增了**应用内受管 CLI 工具生命周期**：设置页的「关于」Tab 升级为 Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes 的工具管理面板，支持静默安装 / 更新、全部升级、冲突诊断、按安装来源锚定的升级，以及对 WSL 的处理和"已安装但跑不起来"状态的可见化。
+
+供应商生态与模型矩阵同步刷新：新增 APIKEY.FUN、APINebula、AtlasCloud、SudoCode、小米 MiMo Token Plan、Claude Desktop 官方预设；跨应用刷新合作伙伴链接与默认模型 / 定价；默认 Claude Opus 模型线升级到 **4.8**，适用处的 GPT 默认升级到 **5.5**。此外还在用量可观测性、繁体中文本地化、文档、以及代理 / 格式转换的鲁棒性上做了大量打磨与修复。
+
+**发布日期**：2026-05-29
+
+**更新规模**：101 commits | 221 files changed | +27,063 / -3,052 lines
+
+---
+
+## 重点内容
+
+- **Codex Chat Completions 路由**：Codex 供应商现在可以由仅支持 OpenAI Chat Completions 的上游提供服务。CC Switch 把 Codex 的 Responses 请求转成 Chat Completions、把 JSON 与 SSE 响应重建回 Responses 形态、保留 reasoning / `<think>` / 工具调用状态、规范化错误信封，并在 Stream Check 中正确探测 Chat 格式供应商
+- **Codex 第三方供应商身份与历史统一并更安全**：第三方 Codex 供应商现在共用稳定的 `custom` model-provider 桶，配一次性迁移改写历史 JSONL 会话与 `state_5.sqlite` 线程，并修复 live 读取 / 切换时 OAuth 登录态、用户选中的目录模型、用户自定义 provider id 的保留
+- **受管 CLI 工具管理**：「关于」页升级为 Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes 的工具管理面板，含安装 / 更新动作、全部升级、冲突诊断、按来源锚定的升级、WSL 处理，以及"已安装但跑不起来"状态可见化
+- **供应商生态与模型矩阵刷新**：新增 APIKEY.FUN、APINebula、AtlasCloud、SudoCode、小米 MiMo Token Plan、Claude Desktop 官方预设；跨应用刷新合作伙伴链接与默认模型 / 定价；默认 Claude Opus 升级到 4.8、适用处 GPT 默认升级到 5.5
+- **用量与文档打磨**：用量看板在日志写入时即时响应更新，修复自定义用量脚本摘要与 subagent 会话日志计费，繁体中文 UI 本地化落地，新增德文 README 与扩充后的 Claude Desktop / Codex Chat / 工具管理手册
+- **代理与转换硬化**：修复 Codex Chat 推理 / 缓存 / usage 边角情况、DeepSeek Anthropic 工具思考历史、Claude 兼容的空 `tool_calls` 流、受管账号接管鉴权、MiMo 推理输出、Gemini Native 工具调用重放，以及多条易 panic 的代理路径
+
+---
+
+## 新功能
+
+### Codex Chat Completions 路由
+
+Codex 供应商现在可以由只会说 OpenAI Chat Completions API 的上游提供服务。CC Switch 的本地代理把 Codex 发出的 Responses 请求转换为 Chat Completions，并把 Chat 响应（JSON 与 SSE 两种）重建回 Responses 形态，沿途保留 `reasoning_content`、内联 `<think>` 块、流式推理摘要、工具调用，以及 `previous_response_id` 续接。一个有界的 Codex Chat 历史缓存会在工具输出之前恢复对应的工具调用。
+
+> 💡 特别感谢 [@EldenPdx](https://github.com/EldenPdx) 的 PR [#2804](https://github.com/farion1231/cc-switch/pull/2804)：本功能的 Chat ↔ Responses 格式转换实现参考了他在该 PR 中的实现。
+
+### 22 个带 Chat 路由的 Codex 第三方供应商预设
+
+为主流中国开源模型启用了 Chat Completions 路由并带显式模型目录——DeepSeek、智谱 GLM（+ 英文站）、Kimi、MiniMax（+ 英文站）、StepFun（+ 英文站）、百度千帆 Coding Plan、百炼（Bailian）、ModelScope、Longcat、百灵（BaiLing）、小米 MiMo（+ Token Plan）、火山 Agentplan、BytePlus、豆包 Seed、SiliconFlow（+ 英文站）、Novita AI、Nvidia。每个预设都声明了自己的上下文窗口，便于 UI 给模型映射行确定尺寸。
+
+### Codex 模型映射表
+
+Codex 供应商表单现在提供模型目录（每行：模型 + 显示名 + 上下文窗口），它是上游模型列表的唯一真相来源，并投影到 `~/.codex/cc-switch-model-catalog.json`。
+
+### Stream Check 支持 Codex Chat 供应商
+
+Stream Check 现在对 Chat 格式的 Codex 供应商改用 Chat 形态的请求体打 `/chat/completions`，而不是 `/v1/responses`；并把 URL 回退顺序与生产环境的 `CodexAdapter` 对齐（仅 origin 的 base URL 先打 `/v1/<endpoint>`），这样裸路径上的非 404 错误不会再把一个正常工作的供应商误判为不可用。
+
+### Codex Chat 思考能力（Reasoning）自适应
+
+当 Codex 供应商走 Chat Completions 路由时，CC Switch 现在会**自动识别**上游的推理接口——依据是供应商的名称、base URL 和模型名——并注入正确的思考参数（`thinking:{type}`、`enable_thinking`、`reasoning_split`、顶层 `reasoning_effort`，或 OpenRouter 的原生 `reasoning:{effort}` 对象），无需手动配置。聚合 / 托管平台（OpenRouter、SiliconFlow）按**平台优先**匹配，因为同一个模型在不同平台上可能暴露不同的推理控制。只暴露"思考开 / 关"开关的供应商（Kimi、GLM、Qwen、MiniMax、MiMo、SiliconFlow）会**丢弃 effort 等级**而不是透传一个不支持的字段——因此在 Codex 里调节这类供应商的思考等级不会有任何效果——而有真实 effort 档位的供应商（DeepSeek、OpenRouter，以及 StepFun 仅 `step-3.5-flash-2603`）则会把等级透传上去。OpenRouter 特别使用原生 `reasoning:{effort}` 对象，把 `max` 钳到 `xhigh`（它的枚举里没有 `max`），并显式转发 `effort:"none"` 以便关闭推理。
+
+### Codex Goal Mode 与远程压缩控制
+
+Codex 配置编辑现在为第三方供应商暴露一个 Goal Mode 开关和一个远程压缩（Remote Compaction）开关；新建的 Codex 模板默认 `disable_response_storage = true`，同时仍允许显式开启 goal 支持。
+
+### 小米 MiMo Token Plan 预设
+
+新增小米 MiMo Token Plan 预设，规格与官方文档对齐（#2803，感谢 @BlueOcean223）。
+
+### Claude Desktop 官方预设
+
+新增一个 Claude Desktop 官方预设，用于恢复原生 Claude Desktop 登录，并附带本地化的 Claude Desktop 使用指南（中 / 英 / 日）。
+
+### 受管 CLI 工具生命周期
+
+为受管 CLI 工具新增静默安装 / 更新命令、最新版本检查、单工具与批量动作、全部升级，以及跨 PATH、Homebrew、npm、pnpm、bun、volta、fnm、nvm、scoop、WinGet、Windows 原生路径和 WSL 的多安装诊断。
+
+### 按来源感知的工具诊断
+
+设置 / 关于 页面现在可以诊断冲突的工具安装、为每条路径展示具体的安装来源与版本，并生成由后端规划、锚定到真实安装来源的升级命令。
+
+### 实时用量刷新
+
+后端现在在代理日志、会话日志同步或汇总写入用量数据时发出 `usage-log-recorded` 事件；用量看板监听该事件并立即让查询失效，而不是等到下一个轮询周期（#3027，感谢 @in30mn1a）。
+
+### 繁体中文本地化
+
+新增 `zh-TW` UI 本地化与一个设置语言选项（#3093，感谢 @LaiYueTing）。
+
+### 德文 README
+
+新增 `README_DE.md` 并从现有 README 的语言切换器中链接到它（#2994，感谢 @flitzrrr）。
+
+### 新合作伙伴预设
+
+跨各受支持的应用面新增 APIKEY.FUN、APINebula、AtlasCloud、SudoCode 合作伙伴预设，含合作伙伴文案、图标与 README 条目。
+
+---
+
+## 变更
+
+### Codex 第三方供应商统一进 "custom" 历史桶
+
+Codex 按 `model_provider` 过滤可恢复历史，因此在供应商专属 id 之间切换会让过去的会话看起来"消失"了。所有第三方供应商现在归并到单一稳定的 `custom` 桶（保留 `openai` / `ollama` 这类预留的内置 id），并配一次性设备迁移：改写历史 JSONL 会话与 `state_5.sqlite` 线程表，原文件备份到 `~/.cc-switch/backups/codex-history-provider-migration-v1/`。
+
+### Codex 供应商表单简化
+
+从 Codex 表单中移除了 API Format 选择器（`wire_api` 永远是 `responses`，该选择器会误导用户以为能改协议）；模型映射表现在是唯一真相来源，不再有隐藏的默认条目；表单注明改动目录后需要重启 Codex，因为 `model_catalog_json` 在启动时加载。表单只保留「需要本地路由映射」开关。
+
+### Codex 本地路由开关提示重写
+
+把「关 / 开」两段提示从"场景描述"改写为"动作指引"（什么时候该开），并在中 / 英 / 日三语同步。
+
+### Codex Live 配置保留
+
+Codex live 配置读取不再强制改写用户的 `model_provider` 字段；供应商作用域的 `experimental_bearer_token` 处理现在会在第三方供应商之间切换时保留 OAuth 登录态。
+
+### 工具安装 / 升级策略
+
+受管工具安装现在优先使用官方原生安装器（在有的情况下），适当时回退到包管理器，对兼容工具先跑 self-update，把升级锚定到检测到的安装来源，并在工作进行中锁定重复的批量动作。
+
+### 「关于」页升级为工具管理
+
+设置的「关于」页现在呈现已安装 / 最新版本、安装与更新动作、冲突诊断、WSL shell 偏好，以及对损坏或跑不起来工具更清晰的状态。
+
+### 默认模型与定价刷新
+
+默认 Claude Opus 模型升级到 4.8，适用处把基于 GPT 的预设与模板迁到 GPT-5.5，刷新定价种子，把 Claude Desktop 模型映射与 Claude Code 的三角色档位对齐，并重命名 OpenCode 的 Go 预设以去掉一个陈旧的模型后缀。
+
+### 合作伙伴链接刷新
+
+更新了胜算云推荐链接、Atlas Cloud 的 UTM 链接，以及跨各 README 语言版本与供应商元数据中的合作伙伴文案。
+
+### Homebrew 官方 Cask 安装
+
+由于 CC Switch 已进入 Homebrew 官方仓库，安装简化为 `brew install --cask cc-switch`；各 README 中移除了对私有 tap 的要求。
+
+### 共享前端工具
+
+用一个共享的 `deepClone` helper 替换 JSON stringify / parse 的深拷贝写法，并抽取了一个共享的 `useTauriEvent` hook（#3140，感谢 @ChongBiaoZhang）。
+
+---
+
+## 修复
+
+### Codex Chat 错误响应转换为 Responses 信封
+
+Codex Chat → Responses 桥接此前会原样透传上游错误体，导致 Codex 客户端无法识别 MiniMax 的 `base_resp`、裸 OpenAI Chat 错误，或纯文本 / HTML 错误页。现在错误会被规整为标准的 `{error: {message, type, code, param}}` 信封并保留原始 HTTP 状态码；非 JSON 体会被包裹并在 UTF-8 字符边界截断到 1KB。同时修复了一个既存的 append-vs-insert bug，它会在重写后的 JSON 体上产生重复的 `Content-Type` 头。
+
+### Codex 流中段 system 消息折叠
+
+MiniMax 的 OpenAI 兼容端点会严格拒绝任何非首位的 `system` 消息（错误 2013）。现在所有 `system` 片段会被折叠为单条首位消息（按原顺序拼接），对宽松后端也是无损的。
+
+### Codex 模型目录重启后被清空
+
+编辑当前激活的 Codex 供应商会触发一次省略了 `modelCatalog` 的 live 读取，于是随后的保存会静默销毁用户配置的模型映射。Live 读取现在会反向解析磁盘上的目录投影，往返出与保存路径写入的相同形状。
+
+### Codex 模型目录无限渲染循环
+
+打断了目录表格与其父状态之间的双向同步环路——它在添加或编辑条目时会导致 UI 严重抖动。
+
+### Codex Chat 保留用户选中的目录模型
+
+客户端从目录里选中的模型（例如通过 `/model`）不再被 `config.toml` 的默认模型覆盖。
+
+### Codex Chat 推理与缓存稳定性
+
+在 Codex 省略或改写 `previous_response_id` 时恢复一个唯一的 call-id 回退；停止从 `previous_response_id` 派生缓存身份；并在工具转换中对可解析的 JSON 字符串载荷做规范化，以便前缀缓存稳定复用。
+
+### Codex Chat 流式 usage 恢复
+
+Responses → Chat 转换现在会在请求为流式时注入 `stream_options.include_usage`（并入客户端提供的任何 `stream_options`），这样 Kimi、MiniMax 这类 OpenAI 兼容上游会重新吐出尾部的 usage 块。此前它们在 Codex Chat 路径上的流式 token / 成本 / 缓存统计都被记成了零。
+
+### Codex Chat 工具调用推理回填
+
+Kimi / Moonshot、DeepSeek 这类思考模型会拒绝携带 `tool_calls` 但 `reasoning_content` 为空的 assistant 消息。当跨轮历史恢复未命中时（代理重启、`call_id` 含糊，或某轮上游没有推理），现在会在最后一遍补回一个占位 `reasoning_content`——真实的尾部推理仍会优先附上——这样请求不再因 `reasoning_content is missing in assistant tool call message` 而失败。
+
+### 受管账号 Claude 接管鉴权
+
+受管账号供应商（GitHub Copilot / Codex OAuth）在接管 Claude live 配置时，现在会丢弃 token 环境变量键、只写入 `ANTHROPIC_API_KEY` 占位符，并带一个出站守卫拒绝把 `PROXY_MANAGED` 占位符发往上游。
+
+### 接管期间的 Claude Desktop profile 同步
+
+代理接管时现在会同步 Claude Desktop 的 profile 数据，模型路由与 Claude Code 的三角色档位对齐，并修正了 Cowork egress profile（#3157、#3172，感谢 @MelorTang、@JGSphaela）。
+
+### 受管账号接管的模型字段
+
+本地路由现在在受管账号上从目标供应商取接管模型字段，而不是携带陈旧的模型值。
+
+### DeepSeek Anthropic 工具思考历史
+
+规范化了 DeepSeek Anthropic 兼容的工具思考历史，让后续轮次能够重放推理 / 工具调用上下文而不产生畸形消息（#3203，感谢 @Q3yp）。
+
+### Claude 兼容流中的空工具调用
+
+修复了一个 Claude 兼容流式边角情况：空的 `tool_calls` 数组会重置块状态并破坏流式响应（#2915，感谢 @zhizhuowq）。
+
+### Claude Code 代理路径的 MiMo 推理
+
+在 Claude Code 代理路径上新增 MiMo 的 `reasoning_content` 支持（#2990，感谢 @zhangyapu1）。
+
+### Gemini Native 工具调用鲁棒性
+
+修复了长多轮会话中合成工具调用 ID 的 `functionResponse.name` 解析（422）与 `thought_signature` 重放（400）问题（#2814，感谢 @Tiancrimson）。
+
+### 会话日志 subagent token 计费
+
+`collect_jsonl_files()` 现在会扫描此前被漏掉的 subagent JSONL 日志，使 subagent 的 token 用量被计入会话成本（仅会话日志模式）（#2821，感谢 @LaoYueHanNi）。
+
+### 用量看板 / 同步稳定性
+
+修复了非 ASCII 模型名导致的 Codex 用量同步 panic、自定义用量脚本摘要，以及用量汇总后缺失实时刷新的问题（#3027、#3129，感谢 @in30mn1a、@hanhan3344）。
+
+### 智谱 Coding Plan 配额档位排序
+
+当 5 小时桶利用率为 0% 时，智谱 API 会省略 `nextResetTime`；旧的 `i64::MAX` 哨兵会把这类条目排到最后，导致周窗口错误地占用五小时槽位。现在档位排序会让缺失的 `nextResetTime` 映射到五小时桶，使智谱 Coding Plan 的托盘与用量配额显示保持正确。
+
+### 技能按 key 安装
+
+从 skills.sh 搜索结果安装时现在使用唯一 key 而不是目录名，使共享目录名的技能能安装到正确的那个（#2784，感谢 @zhaomoran）；同时修复了一处技能同步的复制回退（#2791，感谢 @rogerdigital）。
+
+### 用量价格输入精度
+
+把价格输入步长降到 0.0001，使 DeepSeek 缓存读取这类不足一分的成本也能录入（#2793，关闭 #2503，感谢 @rogerdigital）。
+
+### Ghostty 干净窗口启动
+
+Ghostty 现在打开单个干净窗口，而不是克隆已有标签页；其他终端则通过 `open -na` 打开新窗口（#2801，关闭 #2798，感谢 @luw2007）。
+
+### 工具版本与更新可靠性
+
+版本探测不再掩盖跑不起来的安装；预发布工具在版本检查中被正确处理；批量更新逐工具执行；安装 / 更新按钮在预检期间保持锁定；锚定升级分支强制使用绝对路径；WSL 安装器路径在需要时使用原生 Unix 安装器。
+
+### Codex mise 检测
+
+修复了 Codex 的 mise 环境检测（#2822，感谢 @iambinlin）。
+
+### Codex 归档会话
+
+Codex 的归档会话现在会被纳入会话发现（#2861，感谢 @nanmen2）。
+
+### Codex Chat 空工具参数
+
+在 Codex Chat 转换中，空的工具调用参数载荷会被强制为 `{}`，使上游与客户端收到合法 JSON。
+
+### Claude 供应商 deeplink 导入
+
+通过 deeplink 导入 Claude 供应商时现在会保留自定义环境字段（#2928，感谢 @doutuifei）。
+
+### OMO 推荐模型
+
+把 OMO 推荐模型与上游默认值同步，并改进了「填入推荐」的反馈。
+
+### 胜算云模型 ID 加前缀以正确路由
+
+胜算云（ShengSuanYun）预设现在带上了上游网关要求的厂商前缀——`anthropic/…`、`google/…`、`openai/…`（如 `anthropic/claude-sonnet-4.6`、`google/gemini-3.1-pro-preview`）——覆盖 Claude Code、Claude Desktop、Codex、Gemini、OpenCode、OpenClaw 各预设，含 Claude Code 路由环境变量（`ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_{HAIKU,SONNET,OPUS}_MODEL`），使它们解析到合法的上游模型而不是路由失败。
+
+### ClaudeAPI 重新启用模型测试
+
+把 ClaudeAPI 预设（Claude Code 与 Claude Desktop）从 `third_party` 重新归类为 `aggregator`，使其模型测试按钮不再被第三方 Claude 门禁禁用；合作伙伴金星不受影响，因为它由 `isPartner` 而非 category 驱动。
+
+### 关于页版本检查
+
+版本检查现在能处理预发布工具版本，不会再误判更新状态。
+
+### App 切换器文本裁切
+
+移除了一个会裁切 App 切换器文本的固定宽度约束（#3161，感谢 @loocor）。
+
+### useEffect 竞态条件
+
+为 `App.tsx` 的 effects 加了 active-flag 模式以防卸载时的监听器泄漏，并守卫了把 `undefined` 语言存进 localStorage 的情况（#2827，感谢 @Zylo206）。
+
+---
+
+## 移除
+
+### LionCC 赞助商与预设
+
+跨各 README、供应商配置与 locale 移除了 LionCC 赞助商条目与 LionCCAPI 预设（图标资源保留）。
+
+### AICoding 合作伙伴条目
+
+从 README 赞助商列表、供应商预设与 i18n 元数据中移除了 AICoding 合作伙伴。
+
+### Kimi For Coding 的 Codex 预设
+
+从 Codex 预设目录中移除了 Kimi For Coding 预设。
+
+### CLI 卸载命令提示
+
+从工具管理 UI 中去掉了生成的 CLI 卸载命令提示，同时保留冲突诊断的可见性。
+
+---
+
+## 文档
+
+### Codex Chat 供应商支持
+
+在 changelog 与用户手册中记录了 Chat Completions 路由、供应商支持、推理自适应识别，以及本地路由指引。
+
+### 设置手册刷新
+
+更新了设置文档，覆盖新的受管工具生命周期与 Hermes 安装器行为。
+
+### Claude Desktop 指南
+
+新增了本地化的 Claude Desktop 指南页与截图，覆盖供应商设置、导入、模型映射，以及本地路由上下文。
+
+### 安装文档
+
+更新了安装文档与 README，推荐官方 Homebrew cask，并跨各语言刷新了 v3.15.0 发布说明里关于山寨站点的警告措辞。
+
+---
+
+## ⚠️ 升级提醒
+
+### Codex 第三方供应商历史一次性迁移
+
+升级后首次启动会对 Codex 历史执行一次性迁移：把第三方供应商归并到 `custom` 桶，并改写历史 JSONL 会话与 `state_5.sqlite` 线程表。原文件会备份到 `~/.cc-switch/backups/codex-history-provider-migration-v1/`。这一步是为了修复"切换供应商后过往会话消失"的问题——迁移后历史能正常恢复。
+
+### Codex 改动模型目录需重启
+
+Codex 在启动时加载 `model_catalog_json`，因此在 CC Switch 里改动模型映射表后，需要**重启 Codex** 才能让新目录生效。
+
+### Chat 路由供应商的思考等级可能无效
+
+对只暴露"思考开 / 关"开关的供应商（Kimi、GLM、Qwen、MiniMax、MiMo、SiliconFlow），在 Codex 里调节思考等级（`model_reasoning_effort` 的 low / medium / high）**不会有任何效果**——CC Switch 不会把不被支持的 effort 字段透传给它们。只有具备真实 effort 档位的供应商（DeepSeek、OpenRouter，以及 StepFun 仅 `step-3.5-flash-2603`）调节等级才真正生效。
+
+### 默认模型升级到 Opus 4.8 / GPT-5.5
+
+默认 Claude Opus 模型线升级到 4.8，适用处的 GPT 默认升级到 5.5。如果你依赖某个固定的旧默认模型，升级后请检查相关预设 / 模板的模型字段是否符合预期。
+
+---
+
+## ⚠️ 风险提示
+
+本版本在涉及反向代理类功能上沿用 v3.12.3 / v3.13.0 / v3.15.0 提出的风险提示。
+
+**GitHub Copilot 反向代理**：使用 Copilot 的反代路径可能违反 GitHub / Microsoft 服务条款。详情见 [v3.12.3 release notes](v3.12.3-zh.md#️-风险提示)。
+
+**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
+
+**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束各不相同，请在使用前阅读目标供应商的服务条款。
+
+**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，第三方供应商对计费、合规与数据留存的约束各不相同，请在使用前阅读目标供应商的服务条款。
+
+用户启用上述功能即表示**自行承担所有风险**。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
+
+---
+
+## 下载与安装
+
+访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
+
+### 系统要求
+
+| 系统    | 最低版本                   | 架构                                |
+| ------- | -------------------------- | ----------------------------------- |
+| Windows | Windows 10 及以上          | x64                                 |
+| macOS   | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | 见下表                     | x64 / ARM64                         |
+
+### Windows
+
+| 文件                                     | 说明                                |
+| ---------------------------------------- | ----------------------------------- |
+| `CC-Switch-v3.16.0-Windows.msi`          | **推荐** - MSI 安装包，支持自动更新 |
+| `CC-Switch-v3.16.0-Windows-Portable.zip` | 便携版，解压即用，不写入注册表      |
+
+### macOS
+
+| 文件                             | 说明                                          |
+| -------------------------------- | --------------------------------------------- |
+| `CC-Switch-v3.16.0-macOS.dmg`    | **推荐** - DMG 安装包，拖入 Applications 即可 |
+| `CC-Switch-v3.16.0-macOS.zip`    | 解压后拖入 Applications，Universal Binary     |
+| `CC-Switch-v3.16.0-macOS.tar.gz` | 用于 Homebrew 安装和自动更新                  |
+
+> macOS 版本已通过 Apple 代码签名和公证，可直接安装使用。
+
+### Homebrew（macOS）
+
+> 🎉 CC Switch 现已收录至 Homebrew 官方 cask 仓库，无需添加第三方 tap！
+
+```bash
+brew install --cask cc-switch
+```
+
+更新：
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+> Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本：
+>
+> - `CC-Switch-v3.16.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+> - `CC-Switch-v3.16.0-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| 发行版                                  | 推荐格式    | 安装方式                                                               |
+| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                    | `.AppImage` | 添加执行权限后直接运行，或使用 AUR                                     |
+| 其他发行版 / 不确定                     | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |
@@ -0,0 +1,236 @@
+# CC Switch v3.16.1
+
+> Codex stability patch: because some users did not want CC Switch to change how Codex config files are written, Codex App Enhancements now has a switch and is off by default. After enabling it, you can keep using Codex mobile remote control, official plugins, and other official-app features while using third-party APIs; this release also includes a series of stability fixes.
+
+**[中文版 →](v3.16.1-zh.md) | [日本語版 →](v3.16.1-ja.md)**
+
+---
+
+## Usage Guides
+
+If you want to unlock official-subscription-only Codex remote control and official plugins while using third-party APIs, or want to use DeepSeek / Kimi / GLM / MiniMax and other Chat Completions upstreams in Codex, start with these docs:
+
+- **[Keep Codex remote control and official plugins while using third-party APIs](../guides/codex-official-auth-preservation-guide-en.md)**: explains how to complete official login first, enable Codex App Enhancements, keep official login state in `auth.json`, and route model traffic to third-party APIs.
+- **[Using DeepSeek in Codex: local routing hands-on guide](../guides/codex-deepseek-routing-guide-en.md)**: walks through adding a Codex provider, enabling local routing, and verifying request forwarding.
+- **[Add a Codex provider: Chat Completions routing and model mapping](../user-manual/en/2-providers/2.1-add.md)**: covers the "Needs Local Routing" option, model mapping table, and reasoning capability configuration.
+- **[Local Proxy Service](../user-manual/en/4-proxy/4.1-service.md)** and **[Local Routing](../user-manual/en/4-proxy/4.2-routing.md)**: explain the proxy service, live-config takeover, and related risk notes.
+
+---
+
+> [!WARNING]
+>
+> ## Only Official Channels (Please Read)
+>
+> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Please only obtain the software through the official channels listed below:
+>
+> | Channel            | Only Official                                                                  |
+> | ------------------ | ------------------------------------------------------------------------------ |
+> | Website            | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | Source             | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | Downloads          | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | Author             | **[@farion1231](https://github.com/farion1231)**                               |
+> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues.
+
+---
+
+## Overview
+
+CC Switch v3.16.1 is a Codex stability patch following v3.16.0. v3.16.0 promoted third-party Codex providers to first-class citizens through Chat Completions routing; this release focuses on several high-risk edges discovered in real use: official ChatGPT / Codex OAuth login state could be overwritten while switching third-party providers or during local routing takeover, the Codex model catalog could be cleared during live backfill, hot switching, takeover shutdown restore, or editing the active provider, and Codex `tool_search`, plugin / connector namespace tools, and custom tools were not fully restored back into Responses events on the Chat Completions upstream path.
+
+This release also hardens local routing takeover ownership checks. Provider switching and takeover toggles now run serially per app. When deciding whether the live files are proxy-managed, CC Switch no longer relies only on stale `enabled` state or whether the proxy service is currently running; it also checks backups and proxy placeholders in the live files. This prevents ordinary live writes from overwriting proxy-managed config immediately after takeover is enabled, while the proxy is temporarily stopped, or during hot switching.
+
+**Release date**: 2026-06-01
+
+**Stats**: 23 commits | 62 files changed | +5,603 insertions | -1,113 deletions
+
+---
+
+## Highlights
+
+- **Safer Codex OAuth and third-party provider switching**: added an optional official-auth preservation setting. When enabled, third-party provider tokens are written to `config.toml`, while official ChatGPT / Codex OAuth login stays in `auth.json`.
+- **Codex model catalogs are no longer silently wiped**: `modelCatalog` now treats the database as the source of truth, avoiding overwrites from live configs with missing catalog projections during live backfill, provider switching, takeover shutdown restore, and provider editing.
+- **Codex Chat tools / plugin routing restored**: `tool_search`, loaded namespace tools, and custom tools from Chat Completions upstreams are remapped back to Codex Responses shape; streaming custom tools now emit native `response.custom_tool_call_input.*` events.
+- **More stable local routing takeover and hot switching**: provider switching and takeover toggles are serialized per app. Hot switching refreshes provider display information in Codex live config while keeping the endpoint pointed at the local proxy.
+- **Diagnostics and platform compatibility fixes**: Codex proxy errors now include richer context; Codex CLI model-template discovery supports more platforms and falls back to a static GPT-5.5 template; Windows tool version detection fixes localized output and command quoting issues.
+
+---
+
+## Added
+
+### Codex Official Auth Preservation Setting
+
+Added an optional setting for preserving official ChatGPT / Codex OAuth login state when switching to third-party Codex providers. When enabled, CC Switch stores third-party provider API keys in the provider-scoped `experimental_bearer_token` inside Codex `config.toml` instead of overwriting the official login cache in `auth.json`.
+
+Because some users do not want this feature to change how config files are written, the setting is off by default and keeps the compatibility behavior from before v3.16.0. Users who need both official Codex login and third-party providers can manually enable it under Settings -> Codex App Enhancements.
+
+### Codex DeepSeek Routing Guide
+
+Added Codex DeepSeek routing guides in Chinese, English, and Japanese, covering provider routing requirements, the DeepSeek Codex provider form, and screenshot-based local routing takeover instructions.
+
+---
+
+## Changed
+
+### Codex Auth Preservation Is Now Opt-In
+
+Official auth preservation is off by default. Third-party Codex provider switching therefore keeps the old behavior unless the user opts in, avoiding surprise changes to how `auth.json` / `config.toml` are written.
+
+### Codex Restart Prompt After Provider Switching
+
+Codex loads the model catalog and part of its config at startup. After successfully switching a Codex provider, the UI now reminds the user to restart Codex so model catalog and config changes actually take effect.
+
+### Provider Switching and Takeover Toggles Are Serialized
+
+Codex / Claude / Gemini provider switching and local routing takeover toggles now share a per-app lock, avoiding concurrent writes to live config and backups. Ownership checks also prioritize live backups and the `PROXY_MANAGED` placeholder instead of relying only on whether the proxy service is running.
+
+### Codex Hot Switching Refreshes Display Info
+
+When hot switching Codex providers during local routing takeover, CC Switch refreshes the provider id, model, and display name in the live config so the Codex client menu follows the active provider. The base URL still stays pointed at the local proxy, preventing the real upstream endpoint from leaking back into the live file.
+
+---
+
+## Fixed
+
+### Codex Provider Editor Showing Live OAuth During Takeover
+
+When Codex is under local routing takeover, live `auth.json` / `config.toml` are temporarily rewritten by the proxy. Editing the active provider from those live files could incorrectly show proxy placeholders or official OAuth login as provider config. The editor now explicitly explains that it is showing the provider config stored in the database, not the proxy-managed live files; even if the proxy service is temporarily stopped, CC Switch still treats the app as under takeover when the takeover state indicates so.
+
+### Codex OAuth Cleared or Overwritten During Takeover
+
+Fixed multiple preserve-mode takeover paths that could clear or overwrite official ChatGPT / Codex OAuth `auth.json`. Takeover detection now recognizes `PROXY_MANAGED` in `config.toml`, cleanup only removes proxy placeholder tokens, and third-party providers misclassified as official no longer enter the official-auth overwrite path. Provider sync and switching also treat live backups and placeholders as takeover ownership signals, preventing normal live writes from overwriting proxy config right after takeover or while the proxy is paused.
+
+### Codex Model Catalog Data Loss
+
+Fixed cases where `modelCatalog` could be cleared during live backfill, active-provider editing, provider switching, and takeover shutdown restore. Snapshot backups preserve existing `model_catalog_json` pointers; backups rebuilt from providers regenerate catalog projections from the database source of truth; editing the active provider now prefers the database model catalog instead of trusting a live reverse-parse result that may have lost its projection.
+
+Provider switching also now always refreshes the generated Codex model catalog JSON ([#3360](https://github.com/farion1231/cc-switch/pull/3360), thanks @Postroggy).
+
+### Codex Chat Tools, Plugins, and Custom Tools Restored
+
+Fixed Chat Completions routing for third-party Codex providers so `tool_search`, loaded MCP / connector namespace tools, and custom tools are fully restored back into Codex Responses shape. Non-streaming and streaming Chat responses now recover the correct tool type, namespace, call id, and arguments from the original Responses request; custom-tool streaming now emits native `response.custom_tool_call_input.delta` and `response.custom_tool_call_input.done` events.
+
+### Fuller Codex Proxy Error Diagnostics
+
+When Codex forwarding fails, CC Switch now returns JSON errors that include provider, model, endpoint, upstream HTTP status, stable `cc_switch_*` error codes, and normalized HTTP status. This makes it much clearer which provider, endpoint, and upstream error caused the failure.
+
+### Codex Native Balance / Coding Plan Credential Lookup
+
+Fixed native balance and Coding Plan queries using credentials from the wrong app. Each app now resolves its own provider credentials instead of carrying authentication assumptions from another app surface into the query flow ([#3355](https://github.com/farion1231/cc-switch/pull/3355), thanks @SiskonEmilia).
+
+### Codex CLI Discovery and Model Catalog Template Fallback
+
+Fixed a too-narrow Codex CLI discovery path for third-party Codex model catalog projection. The backend now searches common Codex CLI install locations across platforms, and falls back to a built-in GPT-5.5 model catalog template if no template can be found ([#3382](https://github.com/farion1231/cc-switch/pull/3382), thanks @chofuhoyu).
+
+### Claude Desktop Official Provider Add Failure
+
+Fixed an error when adding the Claude Desktop Official provider ([#3405](https://github.com/farion1231/cc-switch/pull/3405), thanks @Eunknight).
+
+### Kimi / Moonshot Tool-Thinking History Normalization
+
+Added Kimi / Moonshot to the Anthropic-compatible tool-thinking history normalizer. Later turns can now correctly replay reasoning and tool-call context, avoiding failures caused by history messages that do not match upstream requirements ([#3377](https://github.com/farion1231/cc-switch/pull/3377), thanks @Neon-Wang).
+
+### Windows Tool Version Detection
+
+Fixed incorrect quoting for `.cmd` / `.bat` version commands on Windows, and fixed localized command output being decoded as mojibake. Previously, these issues could make runnable tools appear as "installed but not runnable."
+
+---
+
+## Upgrade Notes
+
+### Official OAuth Preservation Must Be Enabled Manually
+
+If you want official ChatGPT / Codex OAuth login to stay in `auth.json` while you frequently switch third-party Codex providers, enable Codex official auth preservation in Settings. It is off by default to keep compatibility for existing users.
+
+### Restart Codex After Editing Model Mappings
+
+Codex reads `model_catalog_json` at startup. Even though v3.16.1 fixes model catalog wiping, Codex still needs to be restarted after you edit the model mapping table so the `/model` menu refreshes.
+
+### During Takeover, the Editor Shows Stored Config, Not Live Files
+
+When local routing takeover is enabled, live `auth.json` / `config.toml` temporarily point to the CC Switch proxy. The provider editor therefore shows the provider config saved in the database. This is expected; after takeover is disabled, CC Switch restores live config from backups or the database source of truth.
+
+---
+
+## Risk Notice
+
+This release continues the risk notices from previous versions for reverse-proxy-style features.
+
+**Codex OAuth reverse proxy**: using a ChatGPT subscription's Codex OAuth through a reverse proxy may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details.
+
+**Codex third-party provider Chat routing**: when CC Switch local proxy converts and forwards Codex requests to third-party providers, each provider may have different requirements for billing, compliance, and data retention. Read the target provider's terms before use.
+
+**Claude Desktop third-party provider proxy switching**: when CC Switch's built-in proxy gateway forwards Claude Desktop requests to third-party providers, you must also follow the target provider's billing, compliance, and data-retention terms.
+
+By enabling these features, users accept the related risks. CC Switch is not responsible for account restrictions, warnings, or service suspensions caused by using these features.
+
+---
+
+## Thanks
+
+Thanks to the following contributors for fixes in v3.16.1:
+
+- [#3360](https://github.com/farion1231/cc-switch/pull/3360): always update Codex model catalog JSON when switching providers, thanks @Postroggy.
+- [#3355](https://github.com/farion1231/cc-switch/pull/3355): resolve native balance / Coding Plan credentials per app, thanks @SiskonEmilia.
+- [#3405](https://github.com/farion1231/cc-switch/pull/3405): fix Claude Desktop Official provider add failure, thanks @Eunknight.
+- [#3382](https://github.com/farion1231/cc-switch/pull/3382): Codex CLI multi-platform discovery and GPT-5.5 model template fallback, thanks @chofuhoyu.
+- [#3377](https://github.com/farion1231/cc-switch/pull/3377): Kimi / Moonshot tool-thinking history normalization, thanks @Neon-Wang.
+
+Thanks also to everyone who reported Codex OAuth, model catalog, local routing takeover, and Chat Completions tool-call issues after v3.16.0. Many of these fixes came directly from real-world reproduction details.
+
+---
+
+## Download & Install
+
+Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) and download the build for your system.
+
+### System Requirements
+
+| System  | Minimum Version          | Architecture                        |
+| ------- | ------------------------ | ----------------------------------- |
+| Windows | Windows 10 and later     | x64                                 |
+| macOS   | macOS 12 (Monterey)+     | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | See table below          | x64 / ARM64                         |
+
+### Windows
+
+| File                                     | Description                                     |
+| ---------------------------------------- | ----------------------------------------------- |
+| `CC-Switch-v3.16.1-Windows.msi`          | **Recommended** - MSI installer with auto-update |
+| `CC-Switch-v3.16.1-Windows-Portable.zip` | Portable build, unzip and run                   |
+
+### macOS
+
+| File                             | Description                                           |
+| -------------------------------- | ----------------------------------------------------- |
+| `CC-Switch-v3.16.1-macOS.dmg`    | **Recommended** - DMG installer, drag to Applications |
+| `CC-Switch-v3.16.1-macOS.zip`    | Unzip and drag to Applications, Universal Binary      |
+| `CC-Switch-v3.16.1-macOS.tar.gz` | For Homebrew install and auto-update                  |
+
+Homebrew install:
+
+```bash
+brew install --cask cc-switch
+```
+
+Upgrade:
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+Linux assets are available for both **x86_64** and **ARM64** (`aarch64`). Choose the file whose architecture tag matches your machine's `uname -m` output:
+
+- `CC-Switch-v3.16.1-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.16.1-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| Distribution                             | Recommended Format | Install Command                                                        |
+| ---------------------------------------- | ------------------ | ---------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS  | `.deb`             | `sudo dpkg -i CC-Switch-*.deb` or `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux     | `.rpm`             | `sudo rpm -i CC-Switch-*.rpm` or `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                 | `.rpm`             | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                     | `.AppImage`        | Make executable and run directly, or use AUR                           |
+| Other distributions / unsure             | `.AppImage`        | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |
@@ -0,0 +1,236 @@
+# CC Switch v3.16.1
+
+> Codex 安定性パッチ: 一部のユーザーから「設定ファイルの書き込み方式を変えたくない」というフィードバックがあったため、Codex アプリ拡張にスイッチを追加し、デフォルトではオフにしました。有効化すると、サードパーティ API を使いながら Codex のモバイルリモート操作、公式プラグインなどの公式アプリ機能を引き続き利用できます。本リリースには一連の安定性修正も含まれます。
+
+**[English →](v3.16.1-en.md) | [中文 →](v3.16.1-zh.md)**
+
+---
+
+## 利用ガイド
+
+サードパーティ API 利用中に、公式サブスクリプションでのみ使える Codex のリモート操作や公式プラグインを有効化したい場合、または DeepSeek / Kimi / GLM / MiniMax などの Chat Completions 上流を Codex で使いたい場合は、まず以下のドキュメントをご覧ください：
+
+- **[サードパーティ API 利用時に Codex のリモート操作と公式プラグインを保持する](../guides/codex-official-auth-preservation-guide-ja.md)**: 先に公式ログインを完了し、Codex アプリ拡張を有効化して、公式ログイン状態を `auth.json` に残したままモデル通信をサードパーティ API へ切り替える手順を説明します。
+- **[Codex で DeepSeek を使う: ローカルルーティング実践ガイド](../guides/codex-deepseek-routing-guide-ja.md)**: Codex プロバイダーの追加、ローカルルーティングの有効化、リクエスト転送の確認までを説明します。
+- **[Codex プロバイダーの追加: Chat Completions ルーティングとモデルマッピング](../user-manual/ja/2-providers/2.1-add.md)**: 「ローカルルーティングが必要」設定、モデルマッピングテーブル、思考能力の設定を説明します。
+- **[ローカルプロキシサービス](../user-manual/ja/4-proxy/4.1-service.md)** と **[ローカルルーティング](../user-manual/ja/4-proxy/4.2-routing.md)**: プロキシサービス、live 設定のテイクオーバー、関連するリスク注意事項を説明します。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一の公式チャネル（必ずお読みください）
+>
+> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。本ソフトウェアは下記の公式チャネルからのみ入手してください：
+>
+> | チャネル     | 唯一の公式                                                                     |
+> | ------------ | ------------------------------------------------------------------------------ |
+> | 公式サイト   | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者         | **[@farion1231](https://github.com/farion1231)**                               |
+> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は直ちに操作を中止し、GitHub Issues からご報告ください。
+
+---
+
+## 概要
+
+CC Switch v3.16.1 は v3.16.0 に続く Codex 安定性パッチです。v3.16.0 では Chat Completions ルーティングによってサードパーティ Codex プロバイダーを一等市民にしました。本リリースでは、実際の利用で見つかったいくつかの高リスクなエッジケースを中心に修正しています。具体的には、サードパーティプロバイダーの切り替えやローカルルーティングのテイクオーバー中に公式 ChatGPT / Codex OAuth ログイン状態が上書きされる問題、live バックフィル・ホットスイッチ・テイクオーバー解除時の復元・現在のプロバイダー編集で Codex モデルカタログが空になる問題、そして Chat Completions 上流パスで Codex の `tool_search`、プラグイン / コネクタの namespace ツール、カスタムツールが Responses イベントへ完全には復元されない問題です。
+
+本リリースではローカルルーティングのテイクオーバー所有権判定も強化しました。プロバイダー切り替えとテイクオーバートグルはアプリごとに直列実行されます。live ファイルがプロキシ管理下にあるかを判定するとき、遅延しがちな `enabled` 状態やプロキシサービスの起動状態だけに頼らず、バックアップと live 内のプロキシプレースホルダーも確認します。これにより、テイクオーバー直後、プロキシの一時停止中、ホットスイッチ中に、通常の live 書き込みがプロキシ管理設定を上書きしてしまうことを防ぎます。
+
+**リリース日**: 2026-06-01
+
+**Stats**: 23 commits | 62 files changed | +5,603 insertions | -1,113 deletions
+
+---
+
+## ハイライト
+
+- **Codex OAuth とサードパーティプロバイダー切り替えをより安全に**: 公式認証を保持する任意設定を追加しました。有効化すると、サードパーティプロバイダーの token は `config.toml` に書き込まれ、公式 ChatGPT / Codex OAuth ログインは `auth.json` に残ります。
+- **Codex モデルカタログが静かに消えないように**: `modelCatalog` はデータベースを信頼できる情報源として扱い、live バックフィル、プロバイダー切り替え、テイクオーバー解除時の復元、プロバイダー編集で、カタログ投影を失った live 設定によりデータベースが上書きされることを避けます。
+- **Codex Chat ツール / プラグインルーティングを復元**: Chat Completions 上流から返る `tool_search`、読み込み済み namespace ツール、カスタムツールを Codex Responses 形態へ再マッピングします。ストリーミングのカスタムツールはネイティブの `response.custom_tool_call_input.*` イベントを出力します。
+- **ローカルルーティングのテイクオーバーとホットスイッチがより安定**: プロバイダー切り替えとテイクオーバートグルはアプリごとに直列化されます。ホットスイッチ時は Codex live 内のプロバイダー表示情報を更新しつつ、endpoint は引き続きローカルプロキシを指します。
+- **診断とプラットフォーム互換性の修正**: Codex プロキシエラーがより豊富な文脈を返すようになりました。Codex CLI のモデルテンプレート探索はより多くのプラットフォームに対応し、静的な GPT-5.5 テンプレートのフォールバックを備えます。Windows のツールバージョン検出では、ローカライズ出力とコマンド引用符の問題を修正しました。
+
+---
+
+## 追加機能
+
+### Codex 公式認証保持設定
+
+サードパーティ Codex プロバイダーへ切り替えるときに、公式 ChatGPT / Codex OAuth ログイン状態を保持する任意設定を追加しました。有効化すると、CC Switch はサードパーティプロバイダーの API key を Codex `config.toml` の provider-scoped `experimental_bearer_token` に保存し、`auth.json` 内の公式ログインキャッシュを上書きしません。
+
+一部のユーザーはこの機能によって設定ファイルの書き込み方式が変わることを望んでいないため、この設定はデフォルトでオフです。v3.16.0 以前の互換動作を維持します。公式 Codex ログインとサードパーティプロバイダーを同時に使いたい場合は、「設定 → Codex アプリ拡張」で手動で有効化できます。
+
+### Codex DeepSeek ルーティングガイド
+
+Codex DeepSeek ルーティングガイドを中国語 / 英語 / 日本語で追加しました。プロバイダーのルーティング要件、DeepSeek Codex プロバイダーフォームの設定、ローカルルーティングのテイクオーバー手順をスクリーンショット付きで説明します。
+
+---
+
+## 変更
+
+### Codex 認証保持は opt-in に変更
+
+公式認証保持設定はデフォルトでオフです。これにより、サードパーティ Codex プロバイダーの切り替えは従来の動作を維持し、ユーザーが気づかないうちに `auth.json` / `config.toml` の書き込み方式が変わることを避けます。
+
+### Codex プロバイダー切り替え後に再起動を案内
+
+Codex はモデルカタログと一部の設定をクライアント起動時に読み込みます。Codex プロバイダーの切り替えに成功した後、UI は Codex の再起動を案内し、モデルカタログと設定変更が実際に反映されるようにします。
+
+### プロバイダー切り替えとテイクオーバートグルを直列化
+
+Codex / Claude / Gemini のプロバイダー切り替えとローカルルーティングのテイクオーバートグルは、アプリごとのロックを共有するようになりました。これにより、2 つの処理が同時に live 設定とバックアップを書き換えることを避けます。live がプロキシ管理下にあるかの判定も、プロキシサービスが起動しているかだけでなく、live バックアップと `PROXY_MANAGED` プレースホルダーを優先して確認します。
+
+### Codex ホットスイッチで表示情報を更新
+
+ローカルルーティングのテイクオーバー中に Codex プロバイダーをホットスイッチすると、CC Switch は live 設定内の provider id、モデル、表示名を更新し、Codex クライアントのメニューが現在のプロバイダーに追従するようにします。同時に base URL はローカルプロキシアドレスのまま維持し、実際の上流 endpoint が live ファイルへ戻ってしまうことを防ぎます。
+
+---
+
+## 修正
+
+### Codex テイクオーバー中の編集ダイアログが live OAuth を表示する問題
+
+Codex がローカルルーティングのテイクオーバー状態にあるとき、live の `auth.json` / `config.toml` はプロキシによって一時的に書き換えられています。この live を読み続けると、現在のプロバイダー編集時にプロキシプレースホルダーや公式 OAuth ログインをプロバイダー設定として誤表示してしまいます。現在の編集ダイアログは、ここに表示されるのがプロキシ管理下の live ファイルではなく、データベースに保存されたプロバイダー設定であることを明示します。プロキシサービスが一時停止していても、そのアプリがテイクオーバー状態であればテイクオーバーとして扱います。
+
+### Codex OAuth がテイクオーバー中に消去または上書きされる問題
+
+公式 ChatGPT / Codex OAuth `auth.json` を消去または上書きする可能性があった複数の preserve-mode テイクオーバーパスを修正しました。テイクオーバー判定は `config.toml` 内の `PROXY_MANAGED` を認識し、クリーンアップはプロキシプレースホルダー token だけを削除します。サードパーティプロバイダーが official と誤分類されても、公式 auth の上書きパスには入りません。プロバイダー同期と切り替えでは、live バックアップとプレースホルダーをテイクオーバー所有権のシグナルとして扱い、テイクオーバー直後やプロキシ一時停止中に通常の live 書き込みがプロキシ設定を上書きすることを防ぎます。
+
+### Codex モデルカタログのデータ消失
+
+live バックフィル、現在のプロバイダー編集、プロバイダー切り替え、テイクオーバー解除時の復元などで `modelCatalog` が空になる問題を修正しました。スナップショットバックアップは既存の `model_catalog_json` ポインターを保持します。プロバイダーから再構築されるバックアップは、データベースの信頼できる情報源からカタログ投影を再生成します。現在のプロバイダー編集時は、投影を失っている可能性のある live の逆解析結果ではなく、データベース内のモデルカタログを優先します。
+
+また、プロバイダー切り替え時には生成済みの Codex モデルカタログ JSON を常に更新するようになりました（[#3360](https://github.com/farion1231/cc-switch/pull/3360)、@Postroggy に感謝）。
+
+### Codex Chat ツール、プラグイン、カスタムツールの復元
+
+サードパーティ Codex プロバイダーが Chat Completions ルーティングを通るとき、`tool_search`、読み込み済みの MCP / connector namespace ツール、カスタムツールを Codex Responses 形態へ完全に復元できない問題を修正しました。非ストリーミングとストリーミングの Chat レスポンスは、元の Responses リクエストに基づいて正しいツール種別、namespace、call id、引数を復元します。カスタムツールのストリーミング出力は、ネイティブの `response.custom_tool_call_input.delta` と `response.custom_tool_call_input.done` イベントを発行します。
+
+### Codex プロキシエラー診断の拡充
+
+Codex の転送に失敗したとき、provider、model、endpoint、上流 HTTP ステータス、安定した `cc_switch_*` エラーコード、正規化された HTTP ステータスを含む JSON エラーを返すようになりました。これにより、どのプロバイダー、どの endpoint、どの上流エラーが原因なのかを追いやすくなります。
+
+### Codex ネイティブ残高 / Coding Plan の認証情報検索
+
+ネイティブ残高と Coding Plan の照会時に、別アプリの認証情報を誤って使う問題を修正しました。各 app は自分自身のプロバイダー認証情報を解析し、別のアプリ面の認証前提を照会フローへ持ち込まなくなりました（[#3355](https://github.com/farion1231/cc-switch/pull/3355)、@SiskonEmilia に感謝）。
+
+### Codex CLI 探索とモデルカタログテンプレートのフォールバック
+
+サードパーティ Codex モデルカタログ投影における Codex CLI の探索パスが狭すぎる問題を修正しました。バックエンドは複数プラットフォームの一般的な Codex CLI インストール場所を探し、それでもテンプレートが見つからない場合は内蔵の GPT-5.5 モデルカタログテンプレートへフォールバックします（[#3382](https://github.com/farion1231/cc-switch/pull/3382)、@chofuhoyu に感謝）。
+
+### Claude Desktop Official プロバイダー追加失敗
+
+Claude Desktop Official プロバイダー追加時のエラーを修正しました（[#3405](https://github.com/farion1231/cc-switch/pull/3405)、@Eunknight に感謝）。
+
+### Kimi / Moonshot ツール思考履歴の正規化
+
+Kimi / Moonshot を Anthropic 互換ツール思考履歴 normalizer に追加しました。後続ターンで reasoning と tool-call コンテキストを正しく再生できるようになり、履歴メッセージの形が上流要件に合わず失敗する問題を避けます（[#3377](https://github.com/farion1231/cc-switch/pull/3377)、@Neon-Wang に感謝）。
+
+### Windows ツールバージョン検出
+
+Windows で `.cmd` / `.bat` のバージョンコマンドに誤って引用符が付く問題と、ローカライズされたコマンド出力が文字化けしてデコードされる問題を修正しました。以前は、実行可能なツールが「インストール済みだが実行できない」と表示されることがありました。
+
+---
+
+## アップグレード時の注意
+
+### 公式 OAuth 保持は手動で有効化が必要
+
+公式 ChatGPT / Codex OAuth ログインを `auth.json` に長期保持しつつ、サードパーティ Codex プロバイダーを頻繁に切り替える場合は、設定で Codex 公式認証保持を有効化してください。既存ユーザーの互換動作を維持するため、デフォルトではオフです。
+
+### モデルマッピング変更後は Codex の再起動が必要
+
+Codex は起動時に `model_catalog_json` を読み込みます。v3.16.1 でモデルカタログが空になる問題は修正されていますが、モデルマッピングテーブルを変更した後は、`/model` メニューを更新するために Codex の再起動が必要です。
+
+### テイクオーバー中に編集するのは保存済み設定であり live ファイルではありません
+
+ローカルルーティングのテイクオーバーを有効化すると、live の `auth.json` / `config.toml` は一時的に CC Switch プロキシを指します。このときプロバイダー編集で表示されるのは、データベースに保存されたプロバイダー設定です。これは期待される動作です。テイクオーバーを無効化すると、CC Switch はバックアップまたはデータベースの信頼できる情報源から live 設定を復元します。
+
+---
+
+## リスク通知
+
+本リリースは、リバースプロキシ系機能に関する以前のリスク通知を引き続き適用します。
+
+**Codex OAuth リバースプロキシ**: ChatGPT サブスクリプションの Codex OAuth をリバースプロキシ経由で使用すると、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 release notes](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
+
+**Codex サードパーティプロバイダー Chat ルーティング**: CC Switch ローカルプロキシで Codex リクエストを変換し、サードパーティプロバイダーへ転送する場合、課金、コンプライアンス、データ保持に関する制約はプロバイダーごとに異なります。利用前に対象プロバイダーの利用規約を確認してください。
+
+**Claude Desktop サードパーティプロバイダープロキシ切り替え**: CC Switch 内蔵のプロキシゲートウェイで Claude Desktop のリクエストをサードパーティプロバイダーへ転送する場合も、対象プロバイダーの課金、コンプライアンス、データ保持に関する規約に従う必要があります。
+
+上記機能を有効化したユーザーは、関連するリスクを自ら負うものとします。CC Switch は、これらの機能の利用によって発生したアカウント制限、警告、サービス停止について責任を負いません。
+
+---
+
+## 謝辞
+
+v3.16.1 で修正を届けてくださった以下のコントリビューターに感謝します：
+
+- [#3360](https://github.com/farion1231/cc-switch/pull/3360): Codex プロバイダー切り替え時にモデルカタログ JSON を常に更新、@Postroggy に感謝。
+- [#3355](https://github.com/farion1231/cc-switch/pull/3355): ネイティブ残高 / Coding Plan 照会の認証情報を app ごとに解析、@SiskonEmilia に感謝。
+- [#3405](https://github.com/farion1231/cc-switch/pull/3405): Claude Desktop Official プロバイダー追加エラーを修正、@Eunknight に感謝。
+- [#3382](https://github.com/farion1231/cc-switch/pull/3382): Codex CLI の複数プラットフォーム探索と GPT-5.5 モデルテンプレートフォールバック、@chofuhoyu に感謝。
+- [#3377](https://github.com/farion1231/cc-switch/pull/3377): Kimi / Moonshot ツール思考履歴の正規化、@Neon-Wang に感謝。
+
+v3.16.0 リリース後に Codex OAuth、モデルカタログ、ローカルルーティングのテイクオーバー、Chat Completions ツール呼び出しの問題を報告してくださったすべてのユーザーにも感謝します。今回の多くの修正は、実際の利用シーンから得られた再現情報に基づいています。
+
+---
+
+## ダウンロードとインストール
+
+[Releases](https://github.com/farion1231/cc-switch/releases/latest) から、お使いのシステムに対応するビルドをダウンロードしてください。
+
+### システム要件
+
+| システム | 最低バージョン           | アーキテクチャ                    |
+| -------- | ------------------------ | --------------------------------- |
+| Windows  | Windows 10 以降          | x64                               |
+| macOS    | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
+| Linux    | 下表を参照               | x64 / ARM64                       |
+
+### Windows
+
+| ファイル                                 | 説明                                                |
+| ---------------------------------------- | --------------------------------------------------- |
+| `CC-Switch-v3.16.1-Windows.msi`          | **推奨** - 自動更新対応の MSI インストーラー        |
+| `CC-Switch-v3.16.1-Windows-Portable.zip` | ポータブル版、展開してそのまま実行できます          |
+
+### macOS
+
+| ファイル                         | 説明                                                    |
+| -------------------------------- | ------------------------------------------------------- |
+| `CC-Switch-v3.16.1-macOS.dmg`    | **推奨** - DMG インストーラー、Applications へドラッグ |
+| `CC-Switch-v3.16.1-macOS.zip`    | 展開して Applications へドラッグ、Universal Binary     |
+| `CC-Switch-v3.16.1-macOS.tar.gz` | Homebrew インストールと自動更新用                      |
+
+Homebrew インストール：
+
+```bash
+brew install --cask cc-switch
+```
+
+更新：
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+Linux アセットは **x86_64** と **ARM64**（`aarch64`）の両方を提供します。ファイル名にアーキテクチャ識別子が含まれているため、マシンの `uname -m` 出力に合わせて選択してください：
+
+- `CC-Switch-v3.16.1-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.16.1-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| ディストリビューション                  | 推奨形式    | インストール方法                                                       |
+| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` または `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` または `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                    | `.AppImage` | 実行権限を付与して直接起動、または AUR を使用                          |
+| その他 / 不明                           | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |
@@ -0,0 +1,236 @@
+# CC Switch v3.16.1
+
+> Codex 稳定性补丁：由于部分用户反映不希望改变配置文件的写入方式，因此为 Codex 增强模式添加开关并默认关闭。开启此开关后，你可以在使用第三方 API 的情况下继续使用 Codex 的手机远程操作、官方插件等功能；本版本也包含一系列稳定性修复。
+
+**[English →](v3.16.1-en.md) | [日本語版 →](v3.16.1-ja.md)**
+
+---
+
+## 使用攻略
+
+如果你希望在使用第三方 API 的时候解锁官方订阅才可以使用的远程操作 Codex、解锁官方插件，或希望在 Codex 中使用 DeepSeek / Kimi / GLM / MiniMax 等 Chat Completions 上游，建议先看这些文档：
+
+- **[使用第三方 API 时保留 Codex 远程操作和官方插件](../guides/codex-official-auth-preservation-guide-zh.md)**：说明如何先完成官方登录，再开启 Codex 应用增强，让官方登录态留在 `auth.json`，同时把模型流量切到第三方 API。
+- **[在 Codex 中使用 DeepSeek：本地路由实战攻略](../guides/codex-deepseek-routing-guide-zh.md)**：从添加 Codex 供应商、开启本地路由，到验证请求转发的完整路径。
+- **[添加 Codex 供应商：Chat Completions 路由与模型映射](../user-manual/zh/2-providers/2.1-add.md)**：覆盖「需要本地路由映射」、模型映射表与思考能力配置。
+- **[本地代理服务](../user-manual/zh/4-proxy/4.1-service.md)** 与 **[本地路由](../user-manual/zh/4-proxy/4.2-routing.md)**：了解代理服务、接管 live 配置、以及相关风险提示。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一官方渠道声明（请务必阅读）
+>
+> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。请仅通过下列官方渠道获取本软件：
+>
+> | 类别     | 唯一官方                                                                       |
+> | -------- | ------------------------------------------------------------------------------ |
+> | 官网     | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | 源码     | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | 下载     | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者     | **[@farion1231](https://github.com/farion1231)**                               |
+> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。
+
+---
+
+## 概览
+
+CC Switch v3.16.1 是 v3.16.0 之后的一版 Codex 稳定性补丁。v3.16.0 让第三方 Codex 供应商通过 Chat Completions 路由成为一等公民；这一版则主要处理真实使用中暴露出的几个高风险边角：官方 ChatGPT / Codex OAuth 登录态在第三方供应商切换或本地路由接管期间被覆盖，Codex 模型目录在 live 回填、热切换、关闭接管恢复或编辑当前供应商时被清空，以及 Codex 的 `tool_search`、插件 / 连接器命名空间、自定义工具在 Chat Completions 上游路径中没有完整恢复为 Responses 事件。
+
+这版也加固了本地路由接管的所有权判断：切换供应商和开启 / 关闭接管现在按应用串行执行，判断 live 文件是否由代理接管时不再只看滞后的 `enabled` 或代理服务是否正在运行，而是结合备份和 live 中的代理占位符。这样可以避免刚开启接管、代理临时停止，或热切换时的普通 live 写入把代理托管配置覆盖掉。
+
+**发布日期**：2026-06-01
+
+**更新规模**：23 commits | 62 files changed | +5,603 / -1,113 lines
+
+---
+
+## 重点内容
+
+- **Codex OAuth 与第三方供应商切换更安全**：新增可选的官方认证保留设置；开启后，第三方供应商 token 写入 `config.toml`，官方 ChatGPT / Codex OAuth 登录继续留在 `auth.json`。
+- **Codex 模型目录不再被静默清空**：`modelCatalog` 以数据库为真相来源，live 回填、供应商切换、接管关闭恢复、编辑弹窗都会避免用丢失投影的 live 配置覆盖数据库。
+- **Codex Chat 工具 / 插件路由恢复**：Chat Completions 上游返回的 `tool_search`、已加载命名空间工具、自定义工具会重新映射回 Codex Responses 形态；流式自定义工具现在发出原生 `response.custom_tool_call_input.*` 事件。
+- **本地路由接管与热切换更稳**：供应商切换和接管开关按 app 串行，热切换会刷新 Codex live 中的供应商显示信息，但 endpoint 仍保持指向本地代理。
+- **诊断与平台兼容性修复**：Codex 代理错误返回更丰富上下文；Codex CLI 模型模板发现支持更多平台并提供 GPT-5.5 静态兜底；Windows 工具版本探测修复乱码与误判。
+
+---
+
+## 新功能
+
+### Codex 官方认证保留设置
+
+新增一个可选设置，用于在切换第三方 Codex 供应商时保留官方 ChatGPT / Codex OAuth 登录态。开启后，CC Switch 会把第三方供应商的 API key 放进 Codex `config.toml` 的 provider-scoped `experimental_bearer_token`，而不是覆盖 `auth.json` 里的官方登录缓存。
+
+由于部分用户不希望此功能改变配置文件的写入方式，因此该设置默认关闭，保持 v3.16.0 之前的兼容行为。需要同时使用官方 Codex 登录和第三方供应商的用户，可以在“设置 → Codex 应用增强”里手动开启。
+
+### Codex DeepSeek 路由指南
+
+新增中 / 英 / 日三语的 Codex DeepSeek 路由指南，包含供应商路由要求、DeepSeek Codex 供应商表单配置，以及本地路由接管的截图说明。
+
+---
+
+## 变更
+
+### Codex 认证保留默认改为 opt-in
+
+官方认证保留设置默认关闭。这样第三方 Codex 供应商切换继续沿用旧行为，避免已有用户在不知情的情况下改变 `auth.json` / `config.toml` 的写入方式。
+
+### Codex 切换供应商后提示重启
+
+Codex 的模型目录与部分配置在客户端启动时加载。现在成功切换 Codex 供应商后，界面会提示用户重启 Codex，让模型目录和配置变化真正生效。
+
+### 供应商切换与接管开关串行化
+
+Codex / Claude / Gemini 的供应商切换与本地路由接管开关现在共享 per-app 锁，避免两个流程同时修改 live 配置和备份。判断 live 是否由代理接管时，也会优先看 live 备份与 `PROXY_MANAGED` 占位符，而不是只看代理服务是否正在运行。
+
+### Codex 热切换刷新显示信息
+
+在本地路由接管期间热切换 Codex 供应商时，CC Switch 会刷新 live 配置中的 provider id、模型和显示名称，让 Codex 客户端菜单能跟随当前供应商；同时 base URL 仍保持本地代理地址，避免真实上游 endpoint 泄回 live 文件。
+
+---
+
+## 修复
+
+### Codex 接管期间编辑弹窗误显示 live OAuth
+
+当 Codex 处于本地路由接管状态时，live `auth.json` / `config.toml` 已被代理临时改写。编辑当前供应商如果继续读取 live，就会把代理占位符或官方 OAuth 登录误显示成供应商配置。现在编辑弹窗会明确提示：此处显示的是数据库中存储的供应商配置，而不是代理托管的 live 文件；即使代理服务暂时停止，只要该 app 仍处于接管状态，也会按接管逻辑处理。
+
+### Codex OAuth 在接管期间被清空或覆盖
+
+修复多条 preserve-mode 接管路径，它们此前可能清空或覆盖官方 ChatGPT / Codex OAuth `auth.json`。现在接管检测会识别 `config.toml` 里的 `PROXY_MANAGED`，清理流程只移除代理占位符 token，第三方供应商错误归类为 official 时也不会再走官方 auth 覆盖路径。供应商同步与切换会把 live 备份和占位符视为接管所有权信号，避免正常 live 写入覆盖刚接管或代理暂停时的代理配置。
+
+### Codex 模型目录数据丢失
+
+修复 `modelCatalog` 在 live 回填、当前供应商编辑弹窗、供应商切换、关闭接管恢复等场景被清空的问题。快照备份会保留已有 `model_catalog_json` 指针；由供应商重建的备份会从数据库真相来源重新生成目录投影；编辑当前供应商时会优先使用数据库里的模型目录，而不是信任可能已经丢失投影的 live 反解结果。
+
+同时，供应商切换现在会始终刷新生成的 Codex 模型目录 JSON（[#3360](https://github.com/farion1231/cc-switch/pull/3360)，感谢 @Postroggy）。
+
+### Codex Chat 工具、插件和自定义工具恢复
+
+修复第三方 Codex 供应商走 Chat Completions 路由时，`tool_search`、已加载的 MCP / connector 命名空间工具、自定义工具无法完整恢复为 Codex Responses 形态的问题。非流式与流式 Chat 响应现在都会根据原始 Responses 请求恢复正确的工具类型、namespace、call id 与参数；自定义工具流式输出会发出原生的 `response.custom_tool_call_input.delta` 和 `response.custom_tool_call_input.done` 事件。
+
+### Codex 代理错误诊断更完整
+
+Codex 转发失败时，现在返回包含 provider、model、endpoint、上游 HTTP 状态、稳定 `cc_switch_*` 错误码和规范 HTTP 状态的 JSON 错误。这样排查「到底是哪个供应商、哪个 endpoint、哪种上游错误」会清楚很多。
+
+### Codex 原生余额 / Coding Plan 查询凭据
+
+修复原生余额与 Coding Plan 查询时跨 app 错用凭据的问题。现在每个 app 会解析自己的供应商凭据，不再把其他应用面的认证假设带进查询流程（[#3355](https://github.com/farion1231/cc-switch/pull/3355)，感谢 @SiskonEmilia）。
+
+### Codex CLI 发现与模型目录模板兜底
+
+修复第三方 Codex 模型目录投影对 Codex CLI 发现路径过窄的问题。现在后端会在多平台常见安装位置寻找 Codex CLI，并在仍找不到模板时使用内置 GPT-5.5 模型目录模板兜底（[#3382](https://github.com/farion1231/cc-switch/pull/3382)，感谢 @chofuhoyu）。
+
+### Claude Desktop 官方供应商添加失败
+
+修复添加 Claude Desktop 官方供应商时报错的问题（[#3405](https://github.com/farion1231/cc-switch/pull/3405)，感谢 @Eunknight）。
+
+### Kimi / Moonshot 工具思考历史规范化
+
+把 Kimi / Moonshot 加入 Anthropic 兼容工具思考历史 normalizer。后续轮次现在能正确重放 reasoning 与 tool-call 上下文，避免因为历史消息形态不符合上游要求而失败（[#3377](https://github.com/farion1231/cc-switch/pull/3377)，感谢 @Neon-Wang）。
+
+### Windows 工具版本探测
+
+修复 Windows 上 `.cmd` / `.bat` 版本命令被错误加引号，以及本地化命令输出被解码成乱码的问题。此前这些问题会让可运行的工具显示为「已安装但无法运行」。
+
+---
+
+## 升级提醒
+
+### 官方 OAuth 保留需要手动开启
+
+如果你希望官方 ChatGPT / Codex OAuth 登录长期保留在 `auth.json`，同时又频繁切换第三方 Codex 供应商，请在设置中开启 Codex 官方认证保留。默认关闭是为了保持老用户的兼容行为。
+
+### 修改模型映射后仍需重启 Codex
+
+Codex 在启动时读取 `model_catalog_json`。因此即使 v3.16.1 已修复模型目录被清空的问题，只要你修改了模型映射表，仍然需要重启 Codex 才能让 `/model` 菜单刷新。
+
+### 接管期间编辑的是存储配置，不是 live 文件
+
+本地路由接管开启后，live `auth.json` / `config.toml` 会临时指向 CC Switch 代理。此时编辑供应商时看到的是数据库里保存的供应商配置，属于预期行为；关闭接管后，CC Switch 会按备份或数据库真相来源恢复 live 配置。
+
+---
+
+## 风险提示
+
+本版本继续沿用此前版本对反向代理类功能的风险提示。
+
+**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
+
+**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
+
+**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，同样需要遵守目标供应商的计费、合规与数据留存约束。
+
+用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
+
+---
+
+## 致谢
+
+感谢以下贡献者在 v3.16.1 中提交修复：
+
+- [#3360](https://github.com/farion1231/cc-switch/pull/3360)：Codex 供应商切换时始终更新模型目录 JSON，感谢 @Postroggy。
+- [#3355](https://github.com/farion1231/cc-switch/pull/3355)：原生余额 / Coding Plan 查询按 app 解析凭据，感谢 @SiskonEmilia。
+- [#3405](https://github.com/farion1231/cc-switch/pull/3405)：修复 Claude Desktop 官方供应商添加报错，感谢 @Eunknight。
+- [#3382](https://github.com/farion1231/cc-switch/pull/3382)：Codex CLI 多平台发现与 GPT-5.5 模型模板兜底，感谢 @chofuhoyu。
+- [#3377](https://github.com/farion1231/cc-switch/pull/3377)：Kimi / Moonshot 工具思考历史规范化，感谢 @Neon-Wang。
+
+也感谢所有在 v3.16.0 发布后反馈 Codex OAuth、模型目录、本地路由接管和 Chat Completions 工具调用问题的用户。很多补丁都来自这些真实使用场景里的复现线索。
+
+---
+
+## 下载与安装
+
+访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
+
+### 系统要求
+
+| 系统    | 最低版本                   | 架构                                |
+| ------- | -------------------------- | ----------------------------------- |
+| Windows | Windows 10 及以上          | x64                                 |
+| macOS   | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | 见下表                     | x64 / ARM64                         |
+
+### Windows
+
+| 文件                                     | 说明                                |
+| ---------------------------------------- | ----------------------------------- |
+| `CC-Switch-v3.16.1-Windows.msi`          | **推荐** - MSI 安装包，支持自动更新 |
+| `CC-Switch-v3.16.1-Windows-Portable.zip` | 便携版，解压即用，不写入注册表      |
+
+### macOS
+
+| 文件                             | 说明                                          |
+| -------------------------------- | --------------------------------------------- |
+| `CC-Switch-v3.16.1-macOS.dmg`    | **推荐** - DMG 安装包，拖入 Applications 即可 |
+| `CC-Switch-v3.16.1-macOS.zip`    | 解压后拖入 Applications，Universal Binary     |
+| `CC-Switch-v3.16.1-macOS.tar.gz` | 用于 Homebrew 安装和自动更新                  |
+
+Homebrew 安装：
+
+```bash
+brew install --cask cc-switch
+```
+
+更新：
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本：
+
+- `CC-Switch-v3.16.1-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.16.1-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| 发行版                                  | 推荐格式    | 安装方式                                                               |
+| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                    | `.AppImage` | 添加执行权限后直接运行，或使用 AUR                                     |
+| 其他发行版 / 不确定                     | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |
@@ -0,0 +1,347 @@
+# CC Switch v3.16.2
+
+> Following the v3.16.1 Codex stability patch, this release mainly broadens data portability and usage observability — adding S3-compatible cloud sync, OpenCode session usage sync, and an official-subscription quota template — while continuing to harden Codex's Chat Completions routing for third-party providers, fixing a batch of Windows / macOS platform issues, adding the CherryIN and ZenMux providers, and fully refreshing the trilingual user manual.
+
+**[中文版 →](v3.16.2-zh.md) | [日本語版 →](v3.16.2-ja.md)**
+
+---
+
+## Usage Guides
+
+This release adds an S3 backend for cloud sync and more usage data sources. If you want to use them, start with these docs:
+
+- **[Settings](../user-manual/en/1-getting-started/1.5-settings.md)**: configure cloud sync (WebDAV / S3-compatible storage) on the settings page to back up and restore providers, MCP, prompts, skills, and other config across multiple devices.
+- **[Usage Statistics](../user-manual/en/4-proxy/4.4-usage.md)**: understand the Usage Dashboard's data sources (proxy logs, Codex / Gemini / OpenCode session sync) and how the statistics are counted.
+
+---
+
+> [!WARNING]
+>
+> ## Only Official Channels (Please Read)
+>
+> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Please only obtain the software through the official channels listed below:
+>
+> | Channel            | Only Official                                                                  |
+> | ------------------ | ------------------------------------------------------------------------------ |
+> | Website            | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | Source             | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | Downloads          | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | Author             | **[@farion1231](https://github.com/farion1231)**                               |
+> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues.
+
+---
+
+## Overview
+
+CC Switch v3.16.2 is a maintenance update following v3.16.1. After the previous release focused on the security of Codex official authentication and local routing takeover, this release concentrates on two things. First, broadening data portability and usage observability — adding S3-compatible cloud sync (a second cloud-backup backend alongside WebDAV), OpenCode session usage sync, and a quota-statistics template for official subscriptions. Second, continuing to polish the edges exposed when Codex routes third-party providers through Chat Completions — stream-truncation detection, `tool_choice` when tools is empty, custom-tool metadata, reasoning-token statistics, file / audio attachment conversion, and more.
+
+This release also fixes a batch of local proxy robustness issues (ephemeral port resolution, the takeover placeholder restore loop, Anthropic `system` message normalization, the upstream 413 message, and Claude Desktop's `[1m]` model routing), addresses several Windows / macOS platform experience issues, adds the CherryIN and ZenMux providers, and fully refreshes the trilingual user manual.
+
+**Release date**: 2026-06-07
+
+**Stats**: 41 commits | 132 files changed | +11,116 / -1,636 lines
+
+---
+
+## Highlights
+
+- **S3-compatible cloud sync**: adds S3-compatible object storage as a second cloud-backup backend alongside WebDAV, with one-click presets for AWS S3, MinIO, Cloudflare R2, Alibaba Cloud OSS, Tencent Cloud COS, Huawei OBS, and more.
+- **More usage data sources**: added OpenCode session usage sync, plus an official-subscription quota template for Claude / Codex / Gemini official providers (explicit toggle, off by default).
+- **Continued Codex Chat Completions routing hardening**: fixed stream-truncation misdetection, `tool_choice` rejection when tools is empty, custom-tool metadata loss, and missing reasoning-token stats, and added file / audio attachment conversion plus a `/v1/models` reachability endpoint.
+- **A more robust local proxy**: fixed ephemeral port (port 0) resolution, the takeover placeholder restore loop, Anthropic `system` message normalization, the upstream 413 message, and Claude Desktop 1M-context model routing.
+- **Platform and providers**: fixed Windows tray / taskbar icons, subdirectory skill updates, and macOS input auto-capitalization, and added the CherryIN and ZenMux providers.
+
+---
+
+## Added
+
+### S3-Compatible Cloud Sync
+
+Cloud Sync now supports S3-compatible object storage as a second backend alongside WebDAV, signing requests with a self-implemented AWS Signature V4 for the broadest possible compatibility. The settings page offers one-click presets for AWS S3, MinIO, Cloudflare R2, Alibaba Cloud OSS, Tencent Cloud COS, Huawei OBS, and a custom endpoint, with connection testing, manual upload / download, and auto-sync on configuration changes (the providers, endpoint, MCP, prompt, skill, settings, and proxy tables — **not** high-frequency data like usage logs). Enabling S3 sync disables a running WebDAV sync and vice versa (#1351).
+
+### OpenCode Session Usage Sync
+
+Added OpenCode as a usage-statistics source that reads per-message token, cost, and model data from OpenCode's local SQLite database and imports it into the usage records, with a dedicated "OpenCode" app filter tab and an "OpenCode Session" data-source label. The database path respects `OPENCODE_DB` and `XDG_DATA_HOME` (defaulting to `~/.local/share/opencode` on all platforms), only finalized messages are imported, and the freshness check includes the WAL file so just-written sessions are not skipped (#3215).
+
+### Official Subscription Quota Template
+
+Because some users were concerned that the IP issuing the usage query could differ from the IP issuing in-app requests, risking an account ban, the official-subscription usage template for Claude / Codex / Gemini official providers is now an explicit, opt-in template that queries plan quota via CLI / OAuth credentials, replacing the previous implicit auto-query for official providers. The template is off by default, is enabled from the usage-script modal, and supports a configurable refresh interval. When using this feature, enabling the proxy's TUN mode is recommended.
+
+### Text-Only Model Image Fallback Rectifier
+
+Added a proxy rectifier that replaces Anthropic image blocks with an `[Unsupported Image]` placeholder when the routed model is text-only (declared, or detected by a built-in model-name heuristic) or the upstream rejects image input, so conversations are not interrupted. The settings page provides a toggle for this fallback, plus a separate toggle for the heuristic detection (which can be turned off to avoid misjudging multimodal models).
+
+### ZenMux Token Plan Provider
+
+Added ZenMux as a Token Plan Coding Plan provider. You can manually enter its API key and base URL in the usage-script modal, and it renders used / quota in USD (#2709).
+
+### CherryIN Preset
+
+Added the CherryIN aggregator gateway as a quick-config preset across all 7 managed apps — Claude Code / Claude Desktop / OpenClaw / Hermes use the Anthropic-format endpoint (open.cherryin.net), OpenCode uses `@ai-sdk/anthropic` (`/v1`), Codex uses the OpenAI-compatible endpoint, and Gemini CLI uses the Gemini-compatible endpoint — with the official brand icon, placed next to AiHubMix (#3643).
+
+### Codex CLI Reachability Endpoint `/v1/models`
+
+The local proxy now responds to `GET /v1/models`, which Codex CLI probes at startup, returning the CC Switch-managed Codex model catalog. A stale-catalog guard was added: it parses the live `config.toml` and only serves the catalog when `model_catalog_json` still points at the CC Switch-owned catalog file, avoiding exposing a previous provider's leftover catalog to Codex (#3818).
+
+### Codex Chat File and Audio Attachments
+
+Codex's Responses→Chat conversion now maps `input_file` parts (carrying `file_id` or inline `file_data`) and `input_audio` parts into their Chat Completions equivalents, and emits top-level `input_*` items that were previously dropped, so file and audio attachments reach Chat-only Codex upstreams.
+
+---
+
+## Changed
+
+### Usage Dashboard Hero Redesign
+
+Rearranged the Usage Dashboard hero and summary cards into a more compact layout, consolidating the real-token total, request count, and cost into a single top row (#3426).
+
+### SSSAiCode Endpoint Refresh
+
+Updated the SSSAiCode preset's website, signup, and API base URLs to the `sssaicodeapi.com` domain, and refreshed its candidate endpoint nodes (default `node-hk.sssaicodeapi.com`, plus `node-hk.sssaiapi.com` and `node-cf.sssaicodeapi.com`) across all 7 app presets.
+
+---
+
+## Fixed
+
+### Codex Chat Stream Truncation Detection
+
+When a Chat Completions upstream ends a stream without a `finish_reason` or `[DONE]`, CC Switch no longer treats it as a normal completion: it finalizes normally only when the stream truly ended; emits an incomplete (`max_output_tokens`) response when partial output was produced; and emits a failed `stream_truncated` event when nothing was produced. Late-arriving reasoning is also backfilled onto still-active streaming tool calls.
+
+### Codex Chat `tool_choice` Without Tools
+
+The Responses→Chat conversion now drops `tool_choice` and `parallel_tool_calls` when the final tools array is missing or empty (including when all tools are filtered out), avoiding 503/400 errors from strict OpenAI-compatible upstreams (vLLM, enterprise gateways) with "When using `tool_choice`, `tools` must be set." (#3640).
+
+### Codex Custom Tool Metadata Preserved
+
+Custom Codex tools (such as the freeform `apply_patch` tool) now embed their full original definition — including format and grammar metadata — as a compact, order-stable JSON block in the generated Chat function description, instead of being replaced with a generic placeholder, so they remain usable on Chat Completions upstreams (#3644).
+
+### Codex Chat Usage Missing `reasoning_tokens`
+
+The Chat→Responses usage conversion now always includes `output_tokens_details.reasoning_tokens` (defaulting to 0), even when a provider omits `completion_tokens_details` or returns a non-object, satisfying Codex CLI's strict requirement and avoiding repeated response-parse failures and retries (#3514).
+
+### Cross-Turn Reasoning for Codex Custom / Search Tools
+
+The cross-turn reasoning cache in Codex Chat history now covers the full tool-call set (`function_call`, `custom_tool_call`, `tool_search_call`) and their outputs, not just plain function calls, so `apply_patch` and tool-search calls keep their own `reasoning_content` when restored via `previous_response_id`.
+
+### Ephemeral Port (port 0) Resolution
+
+When the proxy is configured to listen on port 0 (OS-assigned), takeover now starts the proxy first to obtain the real port before writing live configs and the database, avoiding client URLs pointing at an invalid `:0` address; if no concrete port has been resolved yet, the Claude Desktop gateway URL is rejected outright.
+
+### Proxy Placeholder Backup / Restore Loop
+
+If a previous proxy stop failed to restore the original live config and left proxy placeholders in live, taking over again no longer overwrites the good backup with the proxy config, and restore no longer writes the placeholder back to live: both paths detect the placeholder state and rebuild live from the current provider as the source of truth, fixing cases where the proxy toggle became a no-op and the client was pinned to the local proxy address (#3689).
+
+### Provider Switching Wrongly Blocked During Proxy Takeover
+
+During local routing takeover, only providers explicitly classified as official are now blocked from switching, instead of also disabling custom providers whose endpoint lives in meta or whose fields are simply unfilled. The disabled "Enable" button now shows a lighter hint tooltip instead of the previous red "Blocked" badge.
+
+### localhost Listen Address Normalization
+
+When saving the proxy with a listen address of `localhost`, it is now normalized to `127.0.0.1` before persisting, avoiding binding inconsistencies (#3016).
+
+### Anthropic `system` Message Normalization
+
+For Anthropic-format providers, system-role entries inside the `messages` array are now collapsed and merged into the top-level `system` field (preserving original order and any existing top-level system), avoiding strict upstreams rejecting non-leading system messages; OpenAI Chat routing is unaffected (#3775).
+
+### Claude Desktop 1M-Context Model Routing
+
+Claude Desktop appends a `[1m]` marker to the model name when the 1M-context beta is active (e.g. `claude-opus-4-8[1m]`). The proxy now strips that suffix before route matching so exact, alias, legacy, and role-keyword matching all resolve correctly, fixing `route_unknown` (HTTP 400) failures when switching to a 1M model mid-conversation; the original model name is still kept in the `route_unknown` error for diagnostics.
+
+### Codex 413 Error Message
+
+When a Codex upstream gateway rejects an oversized request body with HTTP 413, the proxy now returns a dedicated message explaining that this is the provider's server-side body-size limit (not a CC Switch local limit), with actionable recovery steps (run `/compact`, remove large logs or inline images, or ask the provider to raise the limit), instead of echoing the upstream's raw HTML error page.
+
+### Proxy Panel Error Detail
+
+When toggling proxy takeover fails, the proxy panel toast now includes the specific error detail returned by the backend, instead of only a generic failure message (#3656).
+
+### Copilot Infinite-Whitespace Threshold
+
+Raised the streaming infinite-whitespace abort threshold from 20 to 500 consecutive whitespace characters, avoiding false aborts of legitimate tool calls whose arguments contain deeply indented code (Python, YAML, Rust, Markdown), while still catching the real Copilot infinite-whitespace bug (#2647).
+
+### Subscription Tier Tray Rendering
+
+Via a unified tier-to-label mapping, fixed rendering of official subscription tiers in the tray and quota display: Claude / Codex no longer drop the 7-day window, Gemini Pro / Flash / Flash-Lite tiers no longer leak raw machine names, and multi-window plans (e.g. Opus + Sonnet) now show the worst utilization instead of the first match.
+
+### Inflated Claude Stream input_tokens
+
+Some Anthropic-compatible streaming providers (e.g. Qwen, MiniMax) report the full context as `input_tokens` in `message_start`, double-counting the cached portion already reported separately and artificially lowering the displayed cache hit rate. The parser now prefers the smaller positive `input_tokens` from `message_delta` and adopts the paired cache counts from the same usage block; native Claude and OpenRouter-converted paths are unchanged.
+
+### Zhipu Quota Query Endpoint Routing
+
+The Zhipu Coding Plan quota query was hard-coded to `api.z.ai`, so users on the mainland preset (`open.bigmodel.cn`) could not retrieve usage when the international endpoint was unreachable. The quota request now routes to the host matching the user's configured base URL (#3702).
+
+### MiniMax Balance API and Pricing
+
+Adapted MiniMax Coding Plan quota to its new balance API (which returns remaining-percent fields instead of the usage counts the old parser relied on, which left tiers empty and the tray showing no usage), filtered out non-coding models (such as video), handled plans without a weekly limit, and added default pricing for the MiniMax M3 model (#3518).
+
+### GLM Coding Plan Endpoints and Model Fetch
+
+Fixed the Zhipu / Z.AI GLM Coding Plan presets to the `/api/coding/paas/v4` endpoints (covering Codex, OpenCode, OpenClaw, Hermes), and made the model-list probe query `{base}/models` first for base URLs that already end in a `/v{N}` version segment (keeping `/v1/models` as a fallback), so the "Fetch models" button no longer 404s on versioned endpoints (#3524).
+
+### Codex Model Catalog Path Portability
+
+Codex now writes only the relative filename `cc-switch-model-catalog.json` to `config.toml` instead of an absolute path (Codex CLI resolves it from the config directory), fixing the model catalog breaking on WSL and symlinked setups where the absolute path could not be translated (#3614).
+
+### APINebula's OpenCode SDK
+
+The APINebula OpenCode preset now loads `@ai-sdk/openai-compatible` instead of `@ai-sdk/openai`, so requests use the OpenAI Chat Completions format the relay expects, rather than the Responses API that fails against chat-completions-only upstreams.
+
+### Windows Tray Icon Residue After Exit
+
+On Windows, quitting CC Switch could leave a dead tray icon behind until the mouse passed over it. The app now explicitly removes the tray icon before exiting, so it disappears cleanly when the process ends (#3797).
+
+### Windows Taskbar Icon
+
+Sets an explicit Windows AppUserModelID at runtime and writes the same ID and product icon onto the installer's desktop and start-menu shortcuts, so CC Switch shows the correct icon and groups properly in the taskbar (#3457).
+
+### Windows Update Check for Subdirectory Skills
+
+When scanning installed skills on Windows, backslash path separators are now normalized to forward slashes, so skills nested in subdirectories (e.g. `skills/my-skill`) are matched by the update check instead of being silently skipped (#3430).
+
+### macOS Input Auto-Capitalization
+
+Disabled autocomplete, autocorrect, autocapitalize, and spellcheck on the shared text Input component, so macOS no longer auto-capitalizes or auto-corrects the first letter typed into configuration fields (#3626).
+
+### Codex VS Code Session Previews
+
+For Codex requests sent from VS Code, the session preview could show selection or open-file content instead of the real prompt when a markdown heading preceded the injected request. The backend title and frontend preview now both match the last "## My request for Codex:" heading (the IDE injects the real request as the final section), so the preview reflects the user's prompt (#3593).
+
+### VS Code Wording in the Chinese UI
+
+Corrected the "Apply to Claude Code plugin" description in Simplified and Traditional Chinese to write "VS Code" properly instead of "Vscode", aligning with the English and Japanese strings (#3228).
+
+---
+
+## Documentation
+
+### User Manual Refresh
+
+Refreshed the README localizations and the en / zh / ja user manuals to reflect all 7 managed apps (adding Claude Desktop and Hermes to the intro and overview copy), corrected the OpenCode config path to `~/.config/opencode/` (`opencode.json`), documented Hermes config files, updated the language docs to four languages, corrected per-app MCP / prompt / skill support, noted that export now produces a timestamped SQL backup that includes usage logs, and documented the pricing model-ID matching rules (#3411).
+
+### Codex Official Auth Preservation Guide
+
+Added a Chinese / English / Japanese guide explaining how to keep Codex official remote control and official plugins working while routing model traffic to third-party APIs, and linked it from the v3.16.1 release notes.
+
+### README Links and Sponsor Markup
+
+Updated the Release Notes links in each language README to v3.16.1, and fixed broken curly-quote characters in the README_ZH sponsor blocks so their HTML attributes render correctly (#3772).
+
+---
+
+## Upgrade Notes
+
+### S3 and WebDAV Cloud Sync Are Mutually Exclusive
+
+Cloud Sync runs only one backend at a time. Enabling S3 auto-sync disables a running WebDAV auto-sync and vice versa. If you previously used WebDAV, make sure both ends are aligned before switching to S3, so you don't assume the old backend is still backing up.
+
+### Restart Codex After Editing Model Mappings
+
+Codex reads `model_catalog_json` at startup. Even though this release rewrites the model catalog to a relative path and adds the `/v1/models` reachability endpoint, you still need to restart Codex after editing the model mapping table for the `/model` menu to refresh.
+
+---
+
+## Risk Notice
+
+This release continues the risk notices from previous versions for reverse-proxy-style features.
+
+**Codex OAuth reverse proxy**: using a ChatGPT subscription's Codex OAuth through a reverse proxy may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details.
+
+**Codex third-party provider Chat routing**: when CC Switch local proxy converts and forwards Codex requests to third-party providers, each provider may have different requirements for billing, compliance, and data retention. Read the target provider's terms before use.
+
+**Claude Desktop third-party provider proxy switching**: when CC Switch's built-in proxy gateway forwards Claude Desktop requests to third-party providers, you must also follow the target provider's billing, compliance, and data-retention terms.
+
+By enabling these features, users accept the related risks. CC Switch is not responsible for account restrictions, warnings, or service suspensions caused by using these features.
+
+---
+
+## Thanks
+
+Thanks to the following contributors for the features and fixes in v3.16.2:
+
+- [#1351](https://github.com/farion1231/cc-switch/pull/1351): add S3-compatible cloud storage sync, thanks @keithyt06.
+- [#3215](https://github.com/farion1231/cc-switch/pull/3215): add OpenCode session usage sync, thanks @nothingness0db.
+- [#2709](https://github.com/farion1231/cc-switch/pull/2709): add the ZenMux Token Plan provider, thanks @Eter365.
+- [#3643](https://github.com/farion1231/cc-switch/pull/3643): add the CherryIN preset provider, thanks @zhibisora.
+- [#3818](https://github.com/farion1231/cc-switch/pull/3818): add the Codex CLI reachability `GET /v1/models` endpoint, thanks @CSberlin.
+- [#3426](https://github.com/farion1231/cc-switch/pull/3426): Usage Dashboard hero redesign, thanks @allenxu09.
+- [#3640](https://github.com/farion1231/cc-switch/pull/3640): drop `tool_choice` when tools is empty, thanks @Postroggy.
+- [#3644](https://github.com/farion1231/cc-switch/pull/3644): preserve Codex custom tool metadata in chat routing, thanks @LanternCX.
+- [#3514](https://github.com/farion1231/cc-switch/pull/3514): always include `reasoning_tokens` in Chat→Responses, thanks @yeeyzy.
+- [#3689](https://github.com/farion1231/cc-switch/pull/3689): skip backup / restore when live is already a proxy placeholder, thanks @YongmaoLuo.
+- [#3016](https://github.com/farion1231/cc-switch/pull/3016): normalize the localhost listen address, thanks @Alexlangl.
+- [#3775](https://github.com/farion1231/cc-switch/pull/3775): normalize Anthropic `system` messages, thanks @Dearli666.
+- [#3656](https://github.com/farion1231/cc-switch/pull/3656): improve error message display in the proxy panel, thanks @lzcndm.
+- [#2647](https://github.com/farion1231/cc-switch/pull/2647): raise the infinite-whitespace threshold 20 → 500, thanks @NiuBlibing.
+- [#3702](https://github.com/farion1231/cc-switch/pull/3702): route the Zhipu quota query to the configured base URL, thanks @YongmaoLuo.
+- [#3518](https://github.com/farion1231/cc-switch/pull/3518): adapt to the MiniMax new balance API and default pricing, thanks @LaoYueHanNi.
+- [#3524](https://github.com/farion1231/cc-switch/pull/3524): fix the Zhipu Coding Plan presets and model probing for versioned endpoints, thanks @makoMakoGo.
+- [#3614](https://github.com/farion1231/cc-switch/pull/3614): use a relative filename for the model catalog, thanks @steponeerror.
+- [#3797](https://github.com/farion1231/cc-switch/pull/3797): fix the Windows tray icon residue after exit, thanks @iAJue.
+- [#3457](https://github.com/farion1231/cc-switch/pull/3457): fix the Windows taskbar icon, thanks @ZhangNanNan1018.
+- [#3430](https://github.com/farion1231/cc-switch/pull/3430): normalize Windows path separators to match subdirectory skill updates, thanks @Ninthless.
+- [#3626](https://github.com/farion1231/cc-switch/pull/3626): disable macOS input auto-capitalization, thanks @ZHLHZHU.
+- [#3593](https://github.com/farion1231/cc-switch/pull/3593): fix Codex VS Code session previews, thanks @xwil1.
+- [#3228](https://github.com/farion1231/cc-switch/pull/3228): align the VS Code wording in the Chinese UI, thanks @Games55k.
+- [#3411](https://github.com/farion1231/cc-switch/pull/3411): refresh the user manual to reflect current app support, thanks @makoMakoGo.
+- [#3772](https://github.com/farion1231/cc-switch/pull/3772): fix README release-note links and sponsor markup, thanks @null-easy.
+
+Thanks also to everyone who reported Codex Chat routing, local proxy takeover, usage statistics, and platform compatibility issues after v3.16.1. Many of these fixes came directly from real-world reproduction details.
+
+---
+
+## Download & Install
+
+Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) and download the build for your system.
+
+### System Requirements
+
+| System  | Minimum Version          | Architecture                        |
+| ------- | ------------------------ | ----------------------------------- |
+| Windows | Windows 10 and later     | x64                                 |
+| macOS   | macOS 12 (Monterey)+     | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | See table below          | x64 / ARM64                         |
+
+### Windows
+
+| File                                     | Description                                      |
+| ---------------------------------------- | ------------------------------------------------ |
+| `CC-Switch-v3.16.2-Windows.msi`          | **Recommended** - MSI installer with auto-update |
+| `CC-Switch-v3.16.2-Windows-Portable.zip` | Portable build, unzip and run                    |
+
+### macOS
+
+| File                             | Description                                           |
+| -------------------------------- | ----------------------------------------------------- |
+| `CC-Switch-v3.16.2-macOS.dmg`    | **Recommended** - DMG installer, drag to Applications |
+| `CC-Switch-v3.16.2-macOS.zip`    | Unzip and drag to Applications, Universal Binary      |
+| `CC-Switch-v3.16.2-macOS.tar.gz` | For Homebrew install and auto-update                  |
+
+Homebrew install:
+
+```bash
+brew install --cask cc-switch
+```
+
+Upgrade:
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+Linux assets are available for both **x86_64** and **ARM64** (`aarch64`). Choose the file whose architecture tag matches your machine's `uname -m` output:
+
+- `CC-Switch-v3.16.2-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.16.2-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| Distribution                            | Recommended Format | Install Command                                                        |
+| --------------------------------------- | ------------------ | --------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`             | `sudo dpkg -i CC-Switch-*.deb` or `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`             | `sudo rpm -i CC-Switch-*.rpm` or `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`             | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                    | `.AppImage`        | Make executable and run directly, or use AUR                          |
+| Other distributions / unsure            | `.AppImage`        | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`             |
@@ -0,0 +1,347 @@
+# CC Switch v3.16.2
+
+> v3.16.1 の Codex 安定性パッチに続き、本リリースはデータの可搬性と用量の可観測性の拡張を主眼としています。S3 互換クラウド同期、OpenCode セッション用量同期、公式サブスクリプション残量テンプレートを追加し、Codex がサードパーティプロバイダーを Chat Completions ルーティングする際の堅牢性を引き続き強化しました。あわせて Windows / macOS のプラットフォーム問題を一括修正し、CherryIN・ZenMux プロバイダーを追加し、3 言語のユーザーマニュアルを全面的に刷新しました。
+
+**[English →](v3.16.2-en.md) | [中文 →](v3.16.2-zh.md)**
+
+---
+
+## 利用ガイド
+
+本リリースではクラウド同期の S3 バックエンドと、より多くの用量統計ソースを追加しました。利用したい場合は、まず以下のドキュメントをご覧ください：
+
+- **[設定](../user-manual/ja/1-getting-started/1.5-settings.md)**: 設定ページでクラウド同期（WebDAV / S3 互換ストレージ）を構成し、プロバイダー、MCP、プロンプト、スキルなどの設定を複数デバイス間でバックアップ・復元します。
+- **[用量統計](../user-manual/ja/4-proxy/4.4-usage.md)**: 用量ダッシュボードのデータソース（プロキシログ、Codex / Gemini / OpenCode セッション同期）と統計の数え方を確認できます。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一の公式チャネル（必ずお読みください）
+>
+> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。本ソフトウェアは下記の公式チャネルからのみ入手してください：
+>
+> | チャネル     | 唯一の公式                                                                     |
+> | ------------ | ------------------------------------------------------------------------------ |
+> | 公式サイト   | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者         | **[@farion1231](https://github.com/farion1231)**                               |
+> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は直ちに操作を中止し、GitHub Issues からご報告ください。
+
+---
+
+## 概要
+
+CC Switch v3.16.2 は v3.16.1 に続くメンテナンスアップデートです。前リリースでは Codex 公式認証とローカルルーティングのテイクオーバーのセキュリティ問題に集中しましたが、本リリースは 2 点に重きを置いています。1 つ目はデータの可搬性と用量の可観測性の拡張で、S3 互換クラウド同期（WebDAV に並ぶ 2 つ目のクラウドバックアップバックエンド）、OpenCode セッション用量同期、公式サブスクリプション向けの残量統計テンプレートを追加しました。2 つ目は、Codex がサードパーティプロバイダーを Chat Completions ルーティングする際に露呈したエッジケースの継続的な改善で、ストリーム切断の判定、tools が空のときの `tool_choice`、カスタムツールのメタデータ、推論トークン統計、ファイル / 音声添付の変換などです。
+
+本リリースではローカルプロキシの堅牢性に関する問題（一時ポートの解決、テイクオーバーのプレースホルダー復元ループ、Anthropic `system` メッセージの正規化、上流 413 の文言、Claude Desktop の `[1m]` モデルルーティング）を一括修正し、いくつかの Windows / macOS のプラットフォーム体験の問題に対処し、CherryIN・ZenMux の 2 プロバイダーを追加し、3 言語のユーザーマニュアルを全面的に刷新しました。
+
+**リリース日**: 2026-06-07
+
+**Stats**: 41 commits | 132 files changed | +11,116 / -1,636 lines
+
+---
+
+## ハイライト
+
+- **S3 互換クラウド同期**: WebDAV に並ぶ 2 つ目のクラウドバックアップバックエンドとして S3 互換オブジェクトストレージを追加。AWS S3、MinIO、Cloudflare R2、Alibaba Cloud OSS、Tencent Cloud COS、Huawei OBS などのワンクリックプリセットを内蔵します。
+- **より多くの用量データソース**: OpenCode セッション用量同期と、Claude / Codex / Gemini 公式プロバイダー向けの公式サブスクリプション残量テンプレート（明示的なトグル、デフォルトでオフ）を追加しました。
+- **Codex Chat Completions ルーティングの継続的な強化**: ストリーム切断の誤判定、tools が空のときの `tool_choice` 拒否、カスタムツールメタデータの欠落、推論トークン統計の欠落を修正し、ファイル / 音声添付の変換と `/v1/models` 到達性エンドポイントを追加しました。
+- **より堅牢なローカルプロキシ**: 一時ポート（port 0）の解決、テイクオーバーのプレースホルダー復元ループ、Anthropic `system` メッセージの正規化、上流 413 の文言、Claude Desktop の 1M コンテキストモデルルーティングを修正しました。
+- **プラットフォームとプロバイダー**: Windows のトレイ / タスクバーアイコン、サブディレクトリスキルの更新、macOS の入力自動大文字化を修正し、CherryIN・ZenMux プロバイダーを追加しました。
+
+---
+
+## 追加機能
+
+### S3 互換クラウド同期
+
+クラウド同期は WebDAV に並ぶ 2 つ目のバックエンドとして S3 互換オブジェクトストレージに対応しました。署名は自前実装の AWS Signature V4 を用い、できるだけ多くのサービスと互換性を持たせています。設定ページでは AWS S3、MinIO、Cloudflare R2、Alibaba Cloud OSS、Tencent Cloud COS、Huawei OBS、およびカスタム endpoint のワンクリックプリセットを提供し、接続テスト、手動アップロード / ダウンロード、設定変更時の自動同期（providers、endpoint、MCP、プロンプト、スキル、設定、プロキシなどの設定テーブル。用量ログのような高頻度書き込みデータは**含みません**）に対応します。S3 同期を有効化すると、実行中の WebDAV 同期は停止し、その逆も同様です（#1351）。
+
+### OpenCode セッション用量同期
+
+OpenCode を用量統計のソースとして追加しました。OpenCode のローカル SQLite データベースからメッセージごとの token、コスト、モデルのデータを読み取り、用量レコードへインポートします。専用の「OpenCode」アプリフィルタタブと「OpenCode Session」データソースラベルを備えます。データベースパスは `OPENCODE_DB` と `XDG_DATA_HOME` を尊重し（全プラットフォームで既定は `~/.local/share/opencode`）、完了済みのメッセージのみをインポートし、新鮮度判定で WAL ファイルも含めるため、書き込み直後のセッションがスキップされません（#3215）。
+
+### 公式サブスクリプション残量テンプレート
+
+用量照会を発行する IP とアプリ内リクエストを発行する IP が異なるとアカウント停止のリスクがある、という一部ユーザーの懸念を受けて、Claude / Codex / Gemini 公式プロバイダー向けに、CLI / OAuth 認証情報でプラン残量を照会する明示的・任意の「公式サブスクリプション」用量テンプレートを追加し、これまでの公式プロバイダーに対する暗黙の自動照会を置き換えました。このテンプレートはデフォルトでオフで、用量スクリプトのモーダルから有効化でき、更新間隔を設定できます。本機能を利用する際は、プロキシの TUN モードを有効化することを推奨します。
+
+### テキスト専用モデルの画像フォールバック整流器
+
+ルーティング先のモデルがテキスト専用（明示的な宣言、または内蔵のモデル名ヒューリスティックで判定）の場合、または上流が画像入力を拒否する場合に、Anthropic の画像ブロックを `[Unsupported Image]` プレースホルダーへ置き換えるプロキシ整流器を追加し、会話の中断を防ぎます。設定ページにこのフォールバックのトグルを用意し、さらにヒューリスティック検出を制御する別のトグル（マルチモーダルモデルの誤判定を避けるためオフにできます）を用意しました。
+
+### ZenMux Token Plan プロバイダー
+
+ZenMux を Token Plan 系の Coding Plan プロバイダーとして追加しました。用量スクリプトのモーダルで API key と base URL を手動入力でき、使用量 / 残量を米ドル建てでリッチに表示します（#2709）。
+
+### CherryIN プリセット
+
+CherryIN アグリゲーターゲートウェイをクイック設定プリセットとして、受管 7 アプリすべてに追加しました。Claude Code / Claude Desktop / OpenClaw / Hermes は Anthropic 形式の endpoint（open.cherryin.net）、OpenCode は `@ai-sdk/anthropic`（`/v1`）、Codex は OpenAI 互換 endpoint、Gemini CLI は Gemini 互換 endpoint を使用します。公式ブランドアイコン付きで、AiHubMix の隣に配置されます（#3643）。
+
+### Codex CLI 到達性エンドポイント `/v1/models`
+
+ローカルプロキシは、Codex CLI が起動時にプローブする `GET /v1/models` に応答し、CC Switch が管理する Codex モデルカタログを返すようになりました。あわせて古いカタログのガードを追加: live の `config.toml` を解析し、`model_catalog_json` が CC Switch 所有のカタログファイルを指している場合のみ提供することで、前のプロバイダーが残したカタログを Codex に見せてしまうことを防ぎます（#3818）。
+
+### Codex Chat のファイル・音声添付
+
+Codex の Responses→Chat 変換は、`input_file`（`file_id` またはインライン `file_data` を持つ）と `input_audio` のコンテンツ部分を Chat Completions の対応形態へマッピングし、これまで破棄されていたトップレベルの `input_*` 項目も出力するようになりました。これにより、ファイルと音声の添付が Chat のみ対応の Codex 上流へ届きます。
+
+---
+
+## 変更
+
+### 用量ダッシュボードのヒーロー再設計
+
+用量ダッシュボードのヒーロー領域とサマリーカードをよりコンパクトなレイアウトに再構成し、実トークン総量、リクエスト数、コストを最上部の 1 行にまとめました（#3426）。
+
+### SSSAiCode エンドポイント刷新
+
+SSSAiCode プリセットの公式サイト、登録、API base URL を `sssaicodeapi.com` ドメインへ更新し、endpoint 候補ノード（既定 `node-hk.sssaicodeapi.com`、ほかに `node-hk.sssaiapi.com` と `node-cf.sssaicodeapi.com`）を全 7 アプリのプリセットで刷新しました。
+
+---
+
+## 修正
+
+### Codex Chat ストリーム切断の判定
+
+Chat Completions 上流が `finish_reason` も `[DONE]` もなくストリームを終了した場合、CC Switch はこれを正常完了として扱わなくなりました: 本当に終了したときのみ正常に締め、部分的な出力があった場合は incomplete（`max_output_tokens`）レスポンスを、何も出力されなかった場合は失敗 `stream_truncated` イベントを発行します。遅れて届いた推論も、まだアクティブなストリーミングのツール呼び出しへバックフィルされます。
+
+### tools が空のときの Codex Chat `tool_choice`
+
+Responses→Chat 変換は、最終的な tools 配列が欠落または空（すべてのツールがフィルタで除外された場合を含む）のときに `tool_choice` と `parallel_tool_calls` を破棄するようになりました。これにより、厳格な OpenAI 互換上流（vLLM、エンタープライズゲートウェイ）が「When using `tool_choice`, `tools` must be set.」で 503/400 を返すことを避けます（#3640）。
+
+### Codex カスタムツールメタデータの保持
+
+カスタム Codex ツール（自由形式の `apply_patch` ツールなど）は、汎用プレースホルダーへ置き換えられる代わりに、format と grammar のメタデータを含む完全な元定義を、生成される Chat 関数の説明にコンパクトで順序の安定した JSON ブロックとして埋め込むようになりました。これにより Chat Completions 上流でも引き続き利用できます（#3644）。
+
+### Codex Chat 用量の `reasoning_tokens` 欠落
+
+Chat→Responses の用量変換は、プロバイダーが `completion_tokens_details` を省略したり非オブジェクトを返したりしても、常に `output_tokens_details.reasoning_tokens`（既定 0）を含めるようになりました。これにより Codex CLI の厳格な要件を満たし、レスポンス解析の失敗と再試行の繰り返しを避けます（#3514）。
+
+### Codex カスタム / 検索ツールのターン跨ぎ推論
+
+Codex Chat 履歴のターン跨ぎ推論キャッシュが、通常の関数呼び出しだけでなく、ツール呼び出しの全集合（`function_call`、`custom_tool_call`、`tool_search_call`）とその出力をカバーするようになりました。これにより `apply_patch` とツール検索の呼び出しは、`previous_response_id` で復元されるときにそれぞれの `reasoning_content` を保持します。
+
+### 一時ポート（port 0）の解決
+
+プロキシが port 0（OS 割り当て）でリッスンするよう構成されている場合、テイクオーバーはまずプロキシを起動して実際のポートを取得してから live 設定とデータベースへ書き込むようになり、クライアント URL が無効な `:0` アドレスを指すことを避けます。具体的なポートがまだ解決されていない場合、Claude Desktop のゲートウェイ URL は拒否されます。
+
+### プロキシプレースホルダーのバックアップ / 復元ループ
+
+前回プロキシ停止時に元の live 設定の復元に失敗し、プロキシプレースホルダーが live に残ってしまった場合でも、再度テイクオーバーする際に正常なバックアップをプロキシ設定で上書きすることはなくなり、復元時にプレースホルダーを live へ書き戻すこともなくなりました: いずれの経路もプレースホルダー状態を検知し、現在のプロバイダーを信頼できる情報源として live を再構築します。これにより、プロキシのトグルが何もしない状態になり、クライアントがローカルプロキシアドレスに固定されてしまう問題を修正しました（#3689）。
+
+### プロキシテイクオーバー中のプロバイダー切り替え誤ブロック
+
+ローカルルーティングのテイクオーバー中、明示的に official と分類されたプロバイダーのみが切り替えをブロックされるようになり、endpoint が meta に存在する、またはフィールドが未入力なだけのカスタムプロバイダーまで無効化することはなくなりました。無効化された「有効化」ボタンは、以前の赤い「ブロック済み」バッジの代わりに、より軽いヒントのツールチップを表示します。
+
+### localhost リッスンアドレスの正規化
+
+プロキシのリッスンアドレスを `localhost` で保存した場合、永続化前に `127.0.0.1` へ正規化されるようになり、バインドの不整合を避けます（#3016）。
+
+### Anthropic `system` メッセージの正規化
+
+Anthropic 形式のプロバイダーでは、`messages` 配列内の system ロールのエントリを折りたたんでトップレベルの `system` フィールドへマージするようになり（元の順序と既存のトップレベル system を保持）、厳格な上流が先頭以外の system メッセージを拒否することを避けます。OpenAI Chat ルーティングは影響を受けません（#3775）。
+
+### Claude Desktop 1M コンテキストモデルルーティング
+
+Claude Desktop は 1M コンテキスト beta が有効なとき、モデル名に `[1m]` マーカーを付加します（例: `claude-opus-4-8[1m]`）。プロキシはルーティング照合の前にこの接尾辞を除去するようになり、完全一致・エイリアス・旧名・ロールキーワードの照合がすべて正しく解決されます。これにより、会話の途中で 1M モデルへ切り替えたときの `route_unknown`（HTTP 400）の失敗を修正しました。診断用に、`route_unknown` エラーには元のモデル名を引き続き保持します。
+
+### Codex 413 エラーの文言
+
+Codex 上流ゲートウェイが過大なリクエストボディを HTTP 413 で拒否したとき、プロキシはこれが CC Switch のローカル制限ではなくプロバイダーのサーバー側ボディサイズ制限であることを説明する専用メッセージを返し、実行可能な回復手順（`/compact` の実行、大きなログやインライン画像の削除、プロバイダーへの上限引き上げ依頼）を提示するようになりました。上流の生の HTML エラーページをそのまま返すことはなくなりました。
+
+### プロキシパネルのエラー詳細
+
+プロキシのテイクオーバー切り替えに失敗したとき、プロキシパネルのトーストは、汎用の失敗メッセージだけでなく、バックエンドが返す具体的なエラー詳細を含めるようになりました（#3656）。
+
+### Copilot 無限空白検出のしきい値
+
+ストリーミングの無限空白の中断しきい値を、連続する空白文字 20 から 500 へ引き上げました。これにより、引数に深くインデントされたコード（Python、YAML、Rust、Markdown）を含む正当なツール呼び出しが誤って中断されることを避けつつ、本物の Copilot 無限空白バグは引き続き捕捉します（#2647）。
+
+### サブスクリプション階層のトレイ表示
+
+統一された階層→ラベルのマッピングにより、トレイと残量表示における公式サブスクリプション階層の表示を修正しました: Claude / Codex は 7 日ウィンドウを取りこぼさなくなり、Gemini Pro / Flash / Flash-Lite の階層は生のマシン名を漏らさなくなり、複数ウィンドウのプラン（Opus + Sonnet など）は最初の一致ではなく最悪の利用率を表示するようになりました。
+
+### Claude ストリームの input_tokens 過大計上
+
+一部の Anthropic 互換ストリーミングプロバイダー（Qwen、MiniMax など）は `message_start` で完全なコンテキストを `input_tokens` として報告し、別途報告済みのキャッシュ分を二重計上して、表示上のキャッシュヒット率を不当に低下させていました。パーサーは `message_delta` のより小さい正の `input_tokens` を優先し、同じ usage ブロックのキャッシュカウントを採用するようになりました。ネイティブ Claude と OpenRouter 変換の経路は変更ありません。
+
+### 智譜（Zhipu）残量照会の endpoint ルーティング
+
+智譜 Coding Plan の残量照会は `api.z.ai` にハードコードされていたため、本土プリセット（`open.bigmodel.cn`）のユーザーは国際 endpoint が到達不能なときに用量を取得できませんでした。残量リクエストは、ユーザーが構成した base URL に一致するホストへルーティングされるようになりました（#3702）。
+
+### MiniMax 残量 API と価格
+
+MiniMax Coding Plan の残量を新しい残量 API に対応させました（新 API は、旧パーサーが依存していた用量カウント（階層が空になりトレイに用量が表示されなくなる）の代わりに、残り割合のフィールドを返します）。非コーディングモデル（動画など）を除外し、週次上限のないプランに対応し、MiniMax M3 モデルの既定価格を追加しました（#3518）。
+
+### GLM Coding Plan の endpoint とモデル取得
+
+智譜 / Z.AI の GLM Coding Plan プリセットを `/api/coding/paas/v4` endpoint に修正し（Codex、OpenCode、OpenClaw、Hermes をカバー）、すでに `/v{N}` のバージョンセグメントで終わる base URL については、モデル一覧プローブが `{base}/models` を先に照会するようにしました（`/v1/models` はフォールバックとして保持）。これにより「モデル取得」ボタンがバージョン付き endpoint で 404 にならなくなりました（#3524）。
+
+### Codex モデルカタログパスの可搬性
+
+Codex は `config.toml` に絶対パスではなく相対ファイル名 `cc-switch-model-catalog.json` のみを書き込むようになりました（Codex CLI は設定ディレクトリから解決します）。これにより、絶対パスを変換できない WSL やシンボリックリンク環境でモデルカタログが壊れる問題を修正しました（#3614）。
+
+### APINebula の OpenCode SDK
+
+APINebula の OpenCode プリセットは `@ai-sdk/openai` ではなく `@ai-sdk/openai-compatible` を読み込むようになり、chat-completions のみ対応の上流で失敗する Responses API ではなく、このリレーが期待する OpenAI Chat Completions 形式でリクエストを行います。
+
+### Windows 終了後のトレイアイコン残留
+
+Windows では CC Switch を終了すると、マウスを重ねるまで無効なトレイアイコンが残ることがありました。アプリは終了前にトレイアイコンを明示的に削除するようになり、プロセス終了とともにきれいに消えます（#3797）。
+
+### Windows タスクバーアイコン
+
+実行時に Windows AppUserModelID を明示的に設定し、インストーラーが生成するデスクトップとスタートメニューのショートカットに同じ ID と製品アイコンを書き込みます。これにより CC Switch がタスクバーで正しいアイコンを表示し、正しくグループ化されます（#3457）。
+
+### Windows サブディレクトリスキルの更新チェック
+
+Windows でインストール済みスキルをスキャンする際、バックスラッシュのパス区切りをスラッシュへ正規化するようになり、サブディレクトリにネストされたスキル（`skills/my-skill` など）が静かにスキップされず、更新チェックで一致するようになりました（#3430）。
+
+### macOS の入力自動大文字化
+
+共有のテキスト Input コンポーネントで autocomplete、autocorrect、autocapitalize、spellcheck を無効化し、macOS が設定フィールドに入力された最初の文字を自動で大文字化・自動修正しないようにしました（#3626）。
+
+### Codex VS Code セッションプレビュー
+
+VS Code から送信された Codex リクエストでは、注入されたリクエストの前に markdown 見出しがあると、セッションプレビューが本当のプロンプトではなく選択範囲や開いているファイルの内容を表示することがありました。バックエンドのタイトルとフロントエンドのプレビューはいずれも、最後の「## My request for Codex:」見出しに一致するようになり（IDE は本当のリクエストを最後のセクションとして注入します）、プレビューがユーザーのプロンプトを反映します（#3593）。
+
+### 中国語 UI の VS Code 表記
+
+簡体字・繁体字中国語の「Claude Code プラグインに適用」の説明を、「Vscode」ではなく正しく「VS Code」と表記するよう修正し、英語・日本語の文言と揃えました（#3228）。
+
+---
+
+## ドキュメント
+
+### ユーザーマニュアル刷新
+
+README の各言語版と en / zh / ja のユーザーマニュアルを刷新し、受管 7 アプリすべてを反映（紹介と概要の文面に Claude Desktop と Hermes を追加）、OpenCode の設定パスを `~/.config/opencode/`（`opencode.json`）に修正、Hermes の設定ファイルの説明を追加、言語ドキュメントを 4 言語に更新、アプリごとの MCP / プロンプト / スキルの対応状況を訂正、エクスポートがタイムスタンプ付きで用量ログを含む SQL バックアップを生成することを記載、価格モデル ID のマッチングルールを追記しました（#3411）。
+
+### Codex 公式認証保持ガイド
+
+モデル通信をサードパーティ API へ切り替えつつ、Codex の公式リモート操作と公式プラグインを動作させ続ける方法を説明する中国語 / 英語 / 日本語のガイドを追加し、v3.16.1 のリリースノートからリンクしました。
+
+### README リンクとスポンサー表記
+
+各言語の README のリリースノートリンクを v3.16.1 に更新し、README_ZH のスポンサーブロックで壊れていた曲線引用符文字を修正して、HTML 属性が正しくレンダリングされるようにしました（#3772）。
+
+---
+
+## アップグレード時の注意
+
+### S3 と WebDAV のクラウド同期は排他
+
+クラウド同期は同時に 1 つのバックエンドのみを実行します。S3 自動同期を有効化すると、実行中の WebDAV 自動同期は停止し、その逆も同様です。以前 WebDAV を使っていた場合は、S3 へ切り替える前に両端のデータが揃っていることを確認し、旧バックエンドがまだバックアップしていると誤解しないようにしてください。
+
+### モデルマッピング変更後は Codex の再起動が必要
+
+Codex は起動時に `model_catalog_json` を読み込みます。本リリースでモデルカタログを相対パスへ書き換え、`/v1/models` 到達性エンドポイントを追加しましたが、モデルマッピングテーブルを変更した後は、`/model` メニューを更新するために Codex の再起動が必要です。
+
+---
+
+## リスク通知
+
+本リリースは、リバースプロキシ系機能に関する以前のリスク通知を引き続き適用します。
+
+**Codex OAuth リバースプロキシ**: ChatGPT サブスクリプションの Codex OAuth をリバースプロキシ経由で使用すると、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 release notes](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
+
+**Codex サードパーティプロバイダー Chat ルーティング**: CC Switch ローカルプロキシで Codex リクエストを変換し、サードパーティプロバイダーへ転送する場合、課金、コンプライアンス、データ保持に関する制約はプロバイダーごとに異なります。利用前に対象プロバイダーの利用規約を確認してください。
+
+**Claude Desktop サードパーティプロバイダープロキシ切り替え**: CC Switch 内蔵のプロキシゲートウェイで Claude Desktop のリクエストをサードパーティプロバイダーへ転送する場合も、対象プロバイダーの課金、コンプライアンス、データ保持に関する規約に従う必要があります。
+
+上記機能を有効化したユーザーは、関連するリスクを自ら負うものとします。CC Switch は、これらの機能の利用によって発生したアカウント制限、警告、サービス停止について責任を負いません。
+
+---
+
+## 謝辞
+
+v3.16.2 で機能と修正を届けてくださった以下のコントリビューターに感謝します：
+
+- [#1351](https://github.com/farion1231/cc-switch/pull/1351): S3 互換クラウドストレージ同期を追加、@keithyt06 に感謝。
+- [#3215](https://github.com/farion1231/cc-switch/pull/3215): OpenCode セッション用量同期を追加、@nothingness0db に感謝。
+- [#2709](https://github.com/farion1231/cc-switch/pull/2709): ZenMux Token Plan プロバイダーを追加、@Eter365 に感謝。
+- [#3643](https://github.com/farion1231/cc-switch/pull/3643): CherryIN プリセットプロバイダーを追加、@zhibisora に感謝。
+- [#3818](https://github.com/farion1231/cc-switch/pull/3818): Codex CLI 到達性確認用の `GET /v1/models` エンドポイントを追加、@CSberlin に感謝。
+- [#3426](https://github.com/farion1231/cc-switch/pull/3426): 用量ダッシュボードのヒーロー再設計、@allenxu09 に感謝。
+- [#3640](https://github.com/farion1231/cc-switch/pull/3640): tools が空のとき `tool_choice` を破棄、@Postroggy に感謝。
+- [#3644](https://github.com/farion1231/cc-switch/pull/3644): Chat ルーティングで Codex カスタムツールメタデータを保持、@LanternCX に感謝。
+- [#3514](https://github.com/farion1231/cc-switch/pull/3514): Chat→Responses で常に `reasoning_tokens` を含める、@yeeyzy に感謝。
+- [#3689](https://github.com/farion1231/cc-switch/pull/3689): live がすでにプロキシプレースホルダーのときバックアップ / 復元をスキップ、@YongmaoLuo に感謝。
+- [#3016](https://github.com/farion1231/cc-switch/pull/3016): localhost リッスンアドレスを正規化、@Alexlangl に感謝。
+- [#3775](https://github.com/farion1231/cc-switch/pull/3775): Anthropic `system` メッセージを正規化、@Dearli666 に感謝。
+- [#3656](https://github.com/farion1231/cc-switch/pull/3656): プロキシパネルのエラー表示を改善、@lzcndm に感謝。
+- [#2647](https://github.com/farion1231/cc-switch/pull/2647): 無限空白検出のしきい値を 20 → 500 へ引き上げ、@NiuBlibing に感謝。
+- [#3702](https://github.com/farion1231/cc-switch/pull/3702): 智譜の残量照会を構成済み base URL へルーティング、@YongmaoLuo に感謝。
+- [#3518](https://github.com/farion1231/cc-switch/pull/3518): MiniMax の新残量 API と既定価格に対応、@LaoYueHanNi に感謝。
+- [#3524](https://github.com/farion1231/cc-switch/pull/3524): 智譜 Coding Plan プリセットとバージョン付き endpoint のモデル探索を修正、@makoMakoGo に感謝。
+- [#3614](https://github.com/farion1231/cc-switch/pull/3614): モデルカタログを相対ファイル名に変更、@steponeerror に感謝。
+- [#3797](https://github.com/farion1231/cc-switch/pull/3797): Windows 終了後のトレイアイコン残留を修正、@iAJue に感謝。
+- [#3457](https://github.com/farion1231/cc-switch/pull/3457): Windows タスクバーアイコンを修正、@ZhangNanNan1018 に感謝。
+- [#3430](https://github.com/farion1231/cc-switch/pull/3430): Windows のパス区切りを正規化してサブディレクトリスキルの更新に対応、@Ninthless に感謝。
+- [#3626](https://github.com/farion1231/cc-switch/pull/3626): macOS の入力自動大文字化を無効化、@ZHLHZHU に感謝。
+- [#3593](https://github.com/farion1231/cc-switch/pull/3593): Codex VS Code セッションプレビューを修正、@xwil1 に感謝。
+- [#3228](https://github.com/farion1231/cc-switch/pull/3228): 中国語 UI の VS Code 表記を揃える、@Games55k に感謝。
+- [#3411](https://github.com/farion1231/cc-switch/pull/3411): 現行のアプリ対応を反映してユーザーマニュアルを刷新、@makoMakoGo に感謝。
+- [#3772](https://github.com/farion1231/cc-switch/pull/3772): README のリリースノートリンクとスポンサー表記を修正、@null-easy に感謝。
+
+v3.16.1 リリース後に Codex Chat ルーティング、ローカルプロキシのテイクオーバー、用量統計、プラットフォーム互換性の問題を報告してくださったすべてのユーザーにも感謝します。今回の多くの修正は、実際の利用シーンから得られた再現情報に基づいています。
+
+---
+
+## ダウンロードとインストール
+
+[Releases](https://github.com/farion1231/cc-switch/releases/latest) から、お使いのシステムに対応するビルドをダウンロードしてください。
+
+### システム要件
+
+| システム | 最低バージョン           | アーキテクチャ                      |
+| -------- | ------------------------ | ----------------------------------- |
+| Windows  | Windows 10 以降          | x64                                 |
+| macOS    | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
+| Linux    | 下表を参照               | x64 / ARM64                         |
+
+### Windows
+
+| ファイル                                 | 説明                                       |
+| ---------------------------------------- | ------------------------------------------ |
+| `CC-Switch-v3.16.2-Windows.msi`          | **推奨** - 自動更新対応の MSI インストーラー |
+| `CC-Switch-v3.16.2-Windows-Portable.zip` | ポータブル版、展開してそのまま実行できます |
+
+### macOS
+
+| ファイル                         | 説明                                                   |
+| -------------------------------- | ------------------------------------------------------ |
+| `CC-Switch-v3.16.2-macOS.dmg`    | **推奨** - DMG インストーラー、Applications へドラッグ |
+| `CC-Switch-v3.16.2-macOS.zip`    | 展開して Applications へドラッグ、Universal Binary      |
+| `CC-Switch-v3.16.2-macOS.tar.gz` | Homebrew インストールと自動更新用                      |
+
+Homebrew インストール：
+
+```bash
+brew install --cask cc-switch
+```
+
+更新：
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+Linux アセットは **x86_64** と **ARM64**（`aarch64`）の両方を提供します。ファイル名にアーキテクチャ識別子が含まれているため、マシンの `uname -m` 出力に合わせて選択してください：
+
+- `CC-Switch-v3.16.2-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.16.2-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| ディストリビューション                  | 推奨形式    | インストール方法                                                          |
+| --------------------------------------- | ----------- | ------------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` または `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` または `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                   |
+| Arch Linux / Manjaro                    | `.AppImage` | 実行権限を付与して直接起動、または AUR を使用                             |
+| その他 / 不明                           | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`                 |
@@ -0,0 +1,347 @@
+# CC Switch v3.16.2
+
+> 在 v3.16.1 的 Codex 稳定性补丁之后，这一版主要拓宽了数据的可携带性与用量观测能力——新增 S3 兼容云同步、OpenCode 会话用量同步、官方订阅额度模板——并继续加固 Codex 通过 Chat Completions 路由第三方供应商的稳健性，同时修复了一批 Windows / macOS 平台问题，新增 CherryIN、ZenMux 供应商，并全面刷新了三语用户手册。
+
+**[English →](v3.16.2-en.md) | [日本語版 →](v3.16.2-ja.md)**
+
+---
+
+## 使用攻略
+
+这一版新增了云同步的 S3 后端和更多用量统计来源，如果你想用上，可以先看这些文档：
+
+- **[设置](../user-manual/zh/1-getting-started/1.5-settings.md)**：在设置页配置云同步（WebDAV / S3 兼容存储），用于在多台设备间备份和恢复供应商、MCP、提示词、技能等配置。
+- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：了解用量看板的数据来源（代理日志、Codex / Gemini / OpenCode 会话同步）与统计口径。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一官方渠道声明（请务必阅读）
+>
+> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。请仅通过下列官方渠道获取本软件：
+>
+> | 类别     | 唯一官方                                                                       |
+> | -------- | ------------------------------------------------------------------------------ |
+> | 官网     | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | 源码     | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | 下载     | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者     | **[@farion1231](https://github.com/farion1231)**                               |
+> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。
+
+---
+
+## 概览
+
+CC Switch v3.16.2 是 v3.16.1 之后的一版维护更新。在上一版集中处理 Codex 官方鉴权与本地路由接管的安全问题之后，这一版把重心放在两件事上：一是拓宽数据的可携带性和用量观测——新增 S3 兼容云同步（WebDAV 之外的第二套云备份后端）、OpenCode 会话用量同步，以及面向官方订阅的额度统计模板；二是继续打磨 Codex 通过 Chat Completions 路由第三方供应商时暴露出来的边角问题——流式截断判定、空 tools 下的 `tool_choice`、自定义工具元数据、推理 token 统计、文件 / 音频附件转换等。
+
+此外，本版还修复了一批本地代理的稳健性问题（临时端口解析、接管占位符还原死循环、Anthropic `system` 消息归一化、上游 413 文案、Claude Desktop 的 `[1m]` 模型路由），处理了若干 Windows / macOS 平台体验问题，并新增 CherryIN、ZenMux 两个供应商，同时全面刷新了三语用户手册。
+
+**发布日期**：2026-06-07
+
+**更新规模**：41 commits | 132 files changed | +11,116 / -1,636 lines
+
+---
+
+## 重点内容
+
+- **S3 兼容云同步**：在 WebDAV 之外新增 S3 兼容对象存储作为第二套云备份后端，内置 AWS S3、MinIO、Cloudflare R2、阿里云 OSS、腾讯云 COS、华为 OBS 等一键预设。
+- **更多用量统计来源**：新增 OpenCode 会话用量同步，以及面向 Claude / Codex / Gemini 官方订阅的额度统计模板（显式开关、默认关闭）。
+- **Codex Chat Completions 路由继续加固**：修复流式截断误判、空 tools 下 `tool_choice` 被拒、自定义工具元数据丢失、推理 token 统计缺失，并支持文件 / 音频附件转换与 `/v1/models` 探活端点。
+- **本地代理更稳**：修复临时端口（port 0）解析、接管占位符还原死循环、Anthropic `system` 消息归一化、上游 413 文案，以及 Claude Desktop 1M 上下文模型路由。
+- **平台与供应商**：修复 Windows 托盘 / 任务栏图标、子目录技能更新、macOS 输入自动大写等问题，并新增 CherryIN、ZenMux 供应商。
+
+---
+
+## 新功能
+
+### S3 兼容云同步
+
+云同步现在支持 S3 兼容对象存储作为 WebDAV 之外的第二套后端，签名采用自实现的 AWS Signature V4，以兼容尽可能多的服务。设置页提供 AWS S3、MinIO、Cloudflare R2、阿里云 OSS、腾讯云 COS、华为 OBS 以及自定义 endpoint 的一键预设，支持连接测试、手动上传 / 下载，以及在配置变更时自动同步（providers、endpoint、MCP、提示词、技能、设置、代理等配置表，**不含**用量日志这类高频写入数据）。开启 S3 同步会停用正在运行的 WebDAV 同步，反之亦然（[#1351](https://github.com/farion1231/cc-switch/pull/1351)）。
+
+### OpenCode 会话用量同步
+
+新增 OpenCode 作为用量统计来源，从 OpenCode 本地 SQLite 数据库读取每条消息的 token、成本和模型数据并导入用量记录，并提供独立的「OpenCode」应用筛选页签和「OpenCode Session」数据来源标签。数据库路径会遵循 `OPENCODE_DB` 和 `XDG_DATA_HOME`（在所有平台默认 `~/.local/share/opencode`），只导入已完成的消息，并在判断新鲜度时把 WAL 文件一并计入，避免刚写入的会话被跳过（[#3215](https://github.com/farion1231/cc-switch/pull/3215)）。
+
+### 官方订阅额度模板
+
+由于部分用户担心发起用量查询的 IP 和发起应用内请求的不一致导致封号风险，因此为 Claude / Codex / Gemini 官方供应商新增一个显式、可选的「官方订阅」用量模板，通过 CLI / OAuth 凭据查询套餐额度，替代此前对官方供应商的隐式自动查询。该模板默认关闭，需要在用量脚本弹窗里开启，并可配置刷新间隔。使用此功能建议开启代理的 TUN 模式。
+
+### 文本模型图片回退整流器
+
+新增一个代理整流器：当路由到的模型仅支持文本（显式声明，或由内置的模型名启发式判定），或上游拒绝图片输入时，会把 Anthropic 图片块替换为 `[Unsupported Image]` 占位标记，避免对话被中断。设置页提供该回退功能的开关，并单独提供一个开关控制启发式检测（可关闭以避免误判多模态模型）。
+
+### ZenMux Token Plan 供应商
+
+新增 ZenMux 作为 Token Plan 类的 Coding Plan 供应商，可在用量脚本弹窗里手动填写 API key 和 base URL，并以美元口径富展示已用 / 额度（[#2709](https://github.com/farion1231/cc-switch/pull/2709)）。
+
+### CherryIN 预设
+
+新增 CherryIN 聚合网关作为快捷配置预设，覆盖全部 7 个受管应用——Claude Code / Claude Desktop / OpenClaw / Hermes 使用 Anthropic 格式端点（open.cherryin.net），OpenCode 使用 `@ai-sdk/anthropic`（`/v1`），Codex 使用 OpenAI 兼容端点，Gemini CLI 使用 Gemini 兼容端点，附带官方品牌图标，位置紧挨 AiHubMix（[#3643](https://github.com/farion1231/cc-switch/pull/3643)）。
+
+### Codex CLI 模型探活端点 `/v1/models`
+
+本地代理现在会响应 Codex CLI 启动时探测的 `GET /v1/models`，返回 CC Switch 托管的 Codex 模型目录。同时加入了过期目录守卫：解析 live 的 `config.toml`，仅当 `model_catalog_json` 仍指向 CC Switch 持有的目录文件时才提供，避免把上一个供应商遗留的目录暴露给 Codex（[#3818](https://github.com/farion1231/cc-switch/pull/3818)）。
+
+### Codex Chat 文件与音频附件
+
+Codex 的 Responses→Chat 转换现在会把 `input_file`（携带 `file_id` 或内联 `file_data`）和 `input_audio` 内容部分映射为 Chat Completions 的对应形态，并补发此前会被丢弃的顶层 `input_*` 项，让文件和音频附件能够送达只支持 Chat 的 Codex 上游。
+
+---
+
+## 变更
+
+### 用量看板 Hero 重新设计
+
+把用量看板的 Hero 区与汇总卡片重排为更紧凑的布局，将真实 token 总量、请求数和成本合并到顶部一行展示（[#3426](https://github.com/farion1231/cc-switch/pull/3426)）。
+
+### SSSAiCode 端点刷新
+
+把 SSSAiCode 预设的官网、注册和 API base URL 更新到 `sssaicodeapi.com` 域名，并刷新其端点候选节点（默认 `node-hk.sssaicodeapi.com`，另含 `node-hk.sssaiapi.com` 和 `node-cf.sssaicodeapi.com`），覆盖全部 7 个应用预设。
+
+---
+
+## 修复
+
+### Codex Chat 流式截断判定
+
+当 Chat Completions 上游在没有 `finish_reason` 或 `[DONE]` 的情况下结束流时，CC Switch 不再把它当作正常完成：只有流真正结束才正常收尾；已产出部分内容时发出 incomplete（`max_output_tokens`）响应；完全没有产出时发出失败的 `stream_truncated` 事件。晚到的推理内容也会回填到仍在进行的流式工具调用上。
+
+### Codex Chat 空 tools 下的 `tool_choice`
+
+Responses→Chat 转换现在会在最终 tools 数组缺失或为空（包括所有工具被过滤掉）时一并丢弃 `tool_choice` 和 `parallel_tool_calls`，避免严格的 OpenAI 兼容上游（vLLM、企业网关）以"When using `tool_choice`, `tools` must be set."报 503/400（[#3640](https://github.com/farion1231/cc-switch/pull/3640)）。
+
+### Codex 自定义工具元数据保留
+
+自定义 Codex 工具（如自由格式的 `apply_patch` 工具）现在会把完整的原始定义——包括 format 和 grammar 元数据——以紧凑、顺序稳定的 JSON 块嵌入生成的 Chat 函数描述中，而不是替换成通用占位符，从而在 Chat Completions 上游上仍可正常使用（[#3644](https://github.com/farion1231/cc-switch/pull/3644)）。
+
+### Codex Chat 用量缺少 `reasoning_tokens`
+
+Chat→Responses 的用量转换现在总会包含 `output_tokens_details.reasoning_tokens`（默认 0），即使供应商省略 `completion_tokens_details` 或返回非对象也是如此，满足 Codex CLI 的严格要求，避免反复的响应解析失败和重试（[#3514](https://github.com/farion1231/cc-switch/pull/3514)）。
+
+### Codex 自定义工具 / 搜索工具的跨轮推理
+
+Codex Chat 历史里的跨轮推理缓存现在覆盖完整的工具调用集合（`function_call`、`custom_tool_call`、`tool_search_call`）及其输出，而不再仅限普通函数调用，因此 `apply_patch` 和工具搜索调用在通过 `previous_response_id` 恢复时能保留各自的 `reasoning_content`。
+
+### 临时端口（port 0）解析
+
+当代理被配置为监听 0 端口（由系统分配）时，接管流程现在会先启动代理以拿到真实端口，再写入 live 配置和数据库，避免客户端 URL 指向无效的 `:0` 地址；若还没解析出具体端口，Claude Desktop 的网关 URL 会被直接拒绝。
+
+### 代理占位符备份 / 恢复死循环
+
+如果上一次停止代理时未能还原原始 live 配置、把代理占位符遗留在了 live 中，再次接管时不会再用代理配置覆盖掉正常备份，恢复时也不会把占位符写回 live：两条路径都会识别占位符状态并以当前供应商为真相来源重建 live，修复了代理开关变成空操作、客户端被钉死在本地代理地址的问题（[#3689](https://github.com/farion1231/cc-switch/pull/3689)）。
+
+### 代理接管期间误拦截供应商切换
+
+在本地路由接管期间，现在只有显式归类为官方的供应商会被禁止切换，而不会再把端点存在 meta 里、或字段尚未填写的自定义供应商一并禁用。被禁用的「启用」按钮现在以更轻量的提示气泡替代原先的红色「已拦截」标记。
+
+### localhost 监听地址归一化
+
+保存代理时如果监听地址填的是 `localhost`，现在会先归一化为 `127.0.0.1` 再持久化，避免绑定不一致（[#3016](https://github.com/farion1231/cc-switch/pull/3016)）。
+
+### Anthropic `system` 消息归一化
+
+对 Anthropic 格式的供应商，`messages` 数组里的 system 角色条目现在会被折叠并合并到顶层 `system` 字段（保留原顺序以及已有的顶层 system），避免严格上游拒绝非首位的 system 消息；OpenAI Chat 路由不受影响（[#3775](https://github.com/farion1231/cc-switch/pull/3775)）。
+
+### Claude Desktop 1M 上下文模型路由
+
+Claude Desktop 在 1M 上下文 beta 激活时会给模型名追加 `[1m]` 标记（如 `claude-opus-4-8[1m]`）。代理现在会在路由匹配前先剥掉该后缀，让精确、别名、旧名和角色关键词匹配都能正确命中，修复了对话中途切换到 1M 模型时的 `route_unknown`（HTTP 400）失败；诊断用的 `route_unknown` 错误里仍保留原始模型名。
+
+### Codex 413 错误文案
+
+当 Codex 上游网关以 HTTP 413 拒绝过大的请求体时，代理现在返回专门的提示，说明这是供应商服务端的请求体大小限制（而非 CC Switch 本地限制），并给出可操作的恢复步骤（运行 `/compact`、移除大段日志或内联图片，或请供应商调高限制），不再原样回显上游的 HTML 错误页。
+
+### 代理面板错误详情
+
+切换代理接管失败时，代理面板的提示现在会带上后端返回的具体错误详情，而不是只显示一句笼统的失败信息（[#3656](https://github.com/farion1231/cc-switch/pull/3656)）。
+
+### Copilot 无限空白检测阈值
+
+把流式无限空白的中断阈值从 20 调高到 500 个连续空白字符，避免参数里含深层缩进代码（Python、YAML、Rust、Markdown）的正常工具调用被误判中断，同时仍能捕获真正的 Copilot 无限空白 bug（[#2647](https://github.com/farion1231/cc-switch/pull/2647)）。
+
+### 订阅档位托盘渲染
+
+通过统一的档位到标签映射，修复官方订阅档位在托盘和额度展示上的渲染问题：Claude / Codex 不再漏掉 7 天窗口，Gemini Pro / Flash / Flash-Lite 档位不再泄露原始机器名，多窗口套餐（如 Opus + Sonnet）现在按最差利用率展示而非取第一个匹配。
+
+### Claude 流式 input_tokens 虚高
+
+部分 Anthropic 兼容的流式供应商（如 Qwen、MiniMax）会在 `message_start` 里把完整上下文当作 `input_tokens` 上报，重复计入了已经单独统计的缓存部分，导致显示的缓存命中率被人为拉低。现在解析器会优先采用 `message_delta` 中更小的正 `input_tokens`，并采用同一 usage 块里配套的缓存计数；原生 Claude 和 OpenRouter 转换路径不变。
+
+### 智谱配额查询端点路由
+
+智谱 Coding Plan 的配额查询此前被硬编码到 `api.z.ai`，导致使用大陆预设（`open.bigmodel.cn`）的用户在国际端点不可达时查不到用量。现在配额请求会路由到与用户所配 base URL 匹配的主机（[#3702](https://github.com/farion1231/cc-switch/pull/3702)）。
+
+### MiniMax 余额接口与定价
+
+适配 MiniMax Coding Plan 配额的新余额接口（新接口返回剩余百分比字段，而非旧解析器依赖、会导致档位为空、托盘不再显示用量的用量计数），过滤掉非编程模型（如视频），兼容无周限额的套餐，并为 MiniMax M3 模型补充了默认定价（[#3518](https://github.com/farion1231/cc-switch/pull/3518)）。
+
+### GLM Coding Plan 端点与模型拉取
+
+把智谱 / Z.AI 的 GLM Coding Plan 预设修正到 `/api/coding/paas/v4` 端点（覆盖 Codex、OpenCode、OpenClaw、Hermes），并让模型列表探测对已经以 `/v{N}` 版本段结尾的 base URL 改为先查 `{base}/models`（保留 `/v1/models` 作为兜底），让「拉取模型」按钮不再在带版本号的端点上 404（[#3524](https://github.com/farion1231/cc-switch/pull/3524)）。
+
+### Codex 模型目录路径可移植性
+
+Codex 现在只把相对文件名 `cc-switch-model-catalog.json` 写入 `config.toml`，而不是绝对路径（Codex CLI 会从配置目录解析它），修复了在 WSL 和符号链接环境下绝对路径无法转换、导致模型目录失效的问题（[#3614](https://github.com/farion1231/cc-switch/pull/3614)）。
+
+### APINebula 的 OpenCode SDK
+
+APINebula 的 OpenCode 预设现在加载 `@ai-sdk/openai-compatible` 而非 `@ai-sdk/openai`，让请求使用该中转期望的 OpenAI Chat Completions 格式，而不是只支持 chat-completions 的上游会失败的 Responses API。
+
+### Windows 退出后托盘图标残留
+
+在 Windows 上退出 CC Switch 可能会留下一个失效的托盘图标，直到鼠标划过才消失。现在应用会在退出前显式移除托盘图标，让它随进程结束干净消失（[#3797](https://github.com/farion1231/cc-switch/pull/3797)）。
+
+### Windows 任务栏图标
+
+在运行时显式设置 Windows AppUserModelID，并给安装器生成的桌面和开始菜单快捷方式写入相同的 ID 和产品图标，让 CC Switch 在任务栏上显示正确图标并正确归组（[#3457](https://github.com/farion1231/cc-switch/pull/3457)）。
+
+### Windows 子目录技能的更新检查
+
+在 Windows 上扫描已安装技能时，把反斜杠路径分隔符归一化为正斜杠，让嵌套在子目录里的技能（如 `skills/my-skill`）能被更新检查匹配到，而不是被静默跳过（[#3430](https://github.com/farion1231/cc-switch/pull/3430)）。
+
+### macOS 输入自动大写
+
+为共享的文本 Input 组件关闭自动完成、自动纠错、自动大写和拼写检查，让 macOS 不再对配置字段里输入的首字母自动大写或自动纠正（[#3626](https://github.com/farion1231/cc-switch/pull/3626)）。
+
+### Codex VS Code 会话预览
+
+从 VS Code 发起的 Codex 请求，其会话预览在注入请求前存在 markdown 标题时，可能显示选区或打开文件的内容而非真实提示。现在后端标题和前端预览都会匹配最后一个「## My request for Codex:」标题（IDE 把真实请求作为最后一节注入），让预览反映用户的提示（[#3593](https://github.com/farion1231/cc-switch/pull/3593)）。
+
+### 中文界面 VS Code 文案
+
+把简体和繁体中文里「应用到 Claude Code 插件」的描述改为正确书写「VS Code」而非「Vscode」，与英文、日文文案对齐（[#3228](https://github.com/farion1231/cc-switch/pull/3228)）。
+
+---
+
+## 文档
+
+### 用户手册刷新
+
+刷新了 README 各语言版本以及 en / zh / ja 用户手册，使其反映全部 7 个受管应用（在介绍和总览文案里补上 Claude Desktop 与 Hermes），把 OpenCode 配置路径修正为 `~/.config/opencode/`（`opencode.json`），补充了 Hermes 配置文件说明，把语言文档更新为四种语言，订正各应用 MCP / 提示词 / 技能的支持情况，说明导出现在会生成带时间戳、含用量日志的 SQL 备份，并补充了定价模型 ID 匹配规则（[#3411](https://github.com/farion1231/cc-switch/pull/3411)）。
+
+### Codex 官方认证保留指南
+
+新增中 / 英 / 日三语指南，说明如何在把模型流量切到第三方 API 的同时，保留 Codex 官方远程操作和官方插件的可用性，并从 v3.16.1 release notes 链接到该指南。
+
+### README 链接与赞助商标记
+
+把各语言 README 里的 Release Notes 链接更新到 v3.16.1，并修复 README_ZH 赞助商区块里损坏的弯引号字符，让其 HTML 属性能正确渲染（[#3772](https://github.com/farion1231/cc-switch/pull/3772)）。
+
+---
+
+## 升级提醒
+
+### S3 与 WebDAV 云同步互斥
+
+云同步同一时间只会运行一套后端。开启 S3 自动同步会停用正在运行的 WebDAV 自动同步，反之亦然。如果你之前用的是 WebDAV，切到 S3 前请确认两端数据已对齐，避免误以为旧后端仍在备份。
+
+### 修改模型映射后仍需重启 Codex
+
+Codex 在启动时读取 `model_catalog_json`。即使本版已把模型目录改写为相对路径并新增了 `/v1/models` 探活端点，只要你修改了模型映射表，仍然需要重启 Codex 才能让 `/model` 菜单刷新。
+
+---
+
+## 风险提示
+
+本版本继续沿用此前版本对反向代理类功能的风险提示。
+
+**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
+
+**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
+
+**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，同样需要遵守目标供应商的计费、合规与数据留存约束。
+
+用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
+
+---
+
+## 致谢
+
+感谢以下贡献者在 v3.16.2 中提交的功能与修复：
+
+- [#1351](https://github.com/farion1231/cc-switch/pull/1351)：新增 S3 兼容云存储同步，感谢 @keithyt06。
+- [#3215](https://github.com/farion1231/cc-switch/pull/3215)：新增 OpenCode 会话用量同步，感谢 @nothingness0db。
+- [#2709](https://github.com/farion1231/cc-switch/pull/2709)：新增 ZenMux Token Plan 供应商，感谢 @Eter365。
+- [#3643](https://github.com/farion1231/cc-switch/pull/3643)：新增 CherryIN 预设供应商，感谢 @zhibisora。
+- [#3818](https://github.com/farion1231/cc-switch/pull/3818)：新增 Codex CLI 探活用的 `GET /v1/models` 端点，感谢 @CSberlin。
+- [#3426](https://github.com/farion1231/cc-switch/pull/3426)：用量看板 Hero 重新设计，感谢 @allenxu09。
+- [#3640](https://github.com/farion1231/cc-switch/pull/3640)：空 tools 时丢弃 `tool_choice`，感谢 @Postroggy。
+- [#3644](https://github.com/farion1231/cc-switch/pull/3644)：Chat 路由保留 Codex 自定义工具元数据，感谢 @LanternCX。
+- [#3514](https://github.com/farion1231/cc-switch/pull/3514)：Chat→Responses 始终包含 `reasoning_tokens`，感谢 @yeeyzy。
+- [#3689](https://github.com/farion1231/cc-switch/pull/3689)：live 已是代理占位符时跳过备份 / 恢复，感谢 @YongmaoLuo。
+- [#3016](https://github.com/farion1231/cc-switch/pull/3016)：归一化 localhost 监听地址，感谢 @Alexlangl。
+- [#3775](https://github.com/farion1231/cc-switch/pull/3775)：规范化 Anthropic `system` 消息，感谢 @Dearli666。
+- [#3656](https://github.com/farion1231/cc-switch/pull/3656)：改进代理面板错误信息展示，感谢 @lzcndm。
+- [#2647](https://github.com/farion1231/cc-switch/pull/2647)：调高无限空白检测阈值 20 → 500，感谢 @NiuBlibing。
+- [#3702](https://github.com/farion1231/cc-switch/pull/3702)：智谱配额查询按所配 base URL 路由，感谢 @YongmaoLuo。
+- [#3518](https://github.com/farion1231/cc-switch/pull/3518)：适配 MiniMax 余额查询新接口与默认定价，感谢 @LaoYueHanNi。
+- [#3524](https://github.com/farion1231/cc-switch/pull/3524)：修复智谱 Coding Plan 预设与带版本号端点的模型探测，感谢 @makoMakoGo。
+- [#3614](https://github.com/farion1231/cc-switch/pull/3614)：模型目录改用相对文件名，感谢 @steponeerror。
+- [#3797](https://github.com/farion1231/cc-switch/pull/3797)：修复 Windows 退出后托盘图标残留，感谢 @iAJue。
+- [#3457](https://github.com/farion1231/cc-switch/pull/3457)：修复 Windows 任务栏图标，感谢 @ZhangNanNan1018。
+- [#3430](https://github.com/farion1231/cc-switch/pull/3430)：归一化 Windows 路径分隔符以匹配子目录技能更新，感谢 @Ninthless。
+- [#3626](https://github.com/farion1231/cc-switch/pull/3626)：关闭 macOS 输入框自动大写，感谢 @ZHLHZHU。
+- [#3593](https://github.com/farion1231/cc-switch/pull/3593)：修复 Codex VS Code 会话预览，感谢 @xwil1。
+- [#3228](https://github.com/farion1231/cc-switch/pull/3228)：对齐中文界面 VS Code 文案，感谢 @Games55k。
+- [#3411](https://github.com/farion1231/cc-switch/pull/3411)：刷新用户手册以反映当前应用支持，感谢 @makoMakoGo。
+- [#3772](https://github.com/farion1231/cc-switch/pull/3772)：修复 README release note 链接与赞助商标记，感谢 @null-easy。
+
+也感谢所有在 v3.16.1 发布后反馈 Codex Chat 路由、本地代理接管、用量统计和平台兼容性问题的用户，很多补丁都来自这些真实使用场景里的复现线索。
+
+---
+
+## 下载与安装
+
+访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
+
+### 系统要求
+
+| 系统    | 最低版本                   | 架构                                |
+| ------- | -------------------------- | ----------------------------------- |
+| Windows | Windows 10 及以上          | x64                                 |
+| macOS   | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | 见下表                     | x64 / ARM64                         |
+
+### Windows
+
+| 文件                                     | 说明                                |
+| ---------------------------------------- | ----------------------------------- |
+| `CC-Switch-v3.16.2-Windows.msi`          | **推荐** - MSI 安装包，支持自动更新 |
+| `CC-Switch-v3.16.2-Windows-Portable.zip` | 便携版，解压即用，不写入注册表      |
+
+### macOS
+
+| 文件                             | 说明                                          |
+| -------------------------------- | --------------------------------------------- |
+| `CC-Switch-v3.16.2-macOS.dmg`    | **推荐** - DMG 安装包，拖入 Applications 即可 |
+| `CC-Switch-v3.16.2-macOS.zip`    | 解压后拖入 Applications，Universal Binary     |
+| `CC-Switch-v3.16.2-macOS.tar.gz` | 用于 Homebrew 安装和自动更新                  |
+
+Homebrew 安装：
+
+```bash
+brew install --cask cc-switch
+```
+
+更新：
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本：
+
+- `CC-Switch-v3.16.2-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.16.2-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| 发行版                                  | 推荐格式    | 安装方式                                                               |
+| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                    | `.AppImage` | 添加执行权限后直接运行，或使用 AUR                                     |
+| 其他发行版 / 不确定                     | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |
@@ -0,0 +1,340 @@
+# CC Switch v3.16.3
+
+> 🎉 **CC Switch has passed 100,000 Stars!**
+> Thank you to every user, contributor, and Star — you are the reason it has come this far. 🙏
+
+> 💎 **This release was developed with help from the Claude Fable 5 model** — it helped untangle several critical, error-prone pieces of logic: the attribution chain that bills route-takeover traffic by the real upstream model, the metering and de-duplication of cache tokens on format-conversion paths, the in-app update restart deadlock, and the migration / restore invariants of Codex unified session history. This is also why this release adds a **Fable 5 Verified** badge to the About page.
+
+> After v3.16.2 broadened data portability and usage observability, this release puts the focus on "making usage billing truly accurate" — billing by the real upstream model, fixing cache double-counting on format-conversion paths, counting Claude Code Workflow sub-agent usage (schema v11), and a round of redesign for the usage dashboard (dashboard-wide provider / model filters, a brand-icon toolbar, and more resilient quota queries) — while also hardening a batch of local proxy and platform issues, adding a custom User-Agent override, a Codex unified session history toggle, and a Claude Fable 5 tier.
+
+**[中文版 →](v3.16.3-zh.md) | [日本語版 →](v3.16.3-ja.md)**
+
+---
+
+## Usage Guides
+
+This release adds a **Codex unified session history** toggle — it migrates / restores sessions, and if used without care it can make you think sessions were "lost," so it is well worth reading its guide first. This release also changes how usage is counted and reworks the dashboard quite a bit, so both are worth starting with:
+
+- **[Codex Unified Session History: Feature Overview and Usage Guide](../guides/codex-unified-session-history-guide-en.md)**: what "unify / migrate / restore" actually changes, why your data is never truly lost, and how to verify and precisely restore sessions when you can't see them. **If you used this toggle or worry a session is gone, read this first.**
+- **[Usage Statistics](../user-manual/en/4-proxy/4.4-usage.md)**: understand the Usage Dashboard's data sources (proxy logs, session sync) and how the statistics are counted. This release adds dashboard-wide provider / model filters and surfaces the real pricing model for route-takeover traffic.
+- **[Settings](../user-manual/en/1-getting-started/1.5-settings.md)**: the custom User-Agent override, the Codex unified session history toggle, and other switches live in the provider form's advanced options and on the settings page.
+
+---
+
+> [!WARNING]
+>
+> ## Only Official Channels (Please Read)
+>
+> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Please only obtain the software through the official channels listed below:
+>
+> | Channel            | Only Official                                                                  |
+> | ------------------ | ------------------------------------------------------------------------------ |
+> | Website            | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | Source             | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | Downloads          | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | Author             | **[@farion1231](https://github.com/farion1231)**                               |
+> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues.
+
+---
+
+## Overview
+
+CC Switch v3.16.3 is a maintenance update following v3.16.2. After the previous release concentrated on broadening data portability and usage observability, this release puts the focus on "making usage billing truly accurate" — billing by the real upstream model rather than whatever the upstream echoes back, fixing the cache-token double-counting on format-conversion paths (Chat / Responses / Gemini converted to Anthropic), folding Claude Code Workflow sub-agent usage into the local statistics, and persisting the actual pricing basis used by each record as schema v11. The usage dashboard was reworked along with it, adding dashboard-wide provider / model filters, a brand-icon toolbar, and more resilient quota queries (retry on failure plus keeping the last successful result).
+
+In addition, this release hardens a batch of local proxy robustness issues (aggregating SSE responses returned under a mislabeled Content-Type, Codex `/responses` image rectification for text-only models, recovery of Codex OAuth credentials and takeover residue, duplicate YAML keys in Hermes config), reworks the provider configuration experience (a custom User-Agent override, a unified Codex advanced section, searchable and sortable presets, a Claude Fable 5 tier), adds a Codex unified session history toggle, and fixes the in-app update hang, the Codex upgrade that broke the install, duplicate macOS terminal windows, and more.
+
+**Release date**: 2026-06-14
+
+**Stats**: 59 commits | 130 files changed | +10,223 / -4,232 lines
+
+---
+
+## Highlights
+
+- **More accurate usage billing**: route-takeover traffic is now billed by the real upstream model (not the alias the upstream echoes back), format-conversion paths no longer count cache tokens into input twice, and Claude Code Workflow sub-agent usage is now counted — with the pricing basis persisted as schema v11.
+- **Usage dashboard redesign**: provider / model filters are promoted from inside the request-log table up to dashboard-wide filters, the app filter switches to brand icons, and quota queries gain retry-on-failure plus "keep the last successful result" so a single network blip no longer turns cards red.
+- **Custom User-Agent override**: providers can set a custom UA that applies consistently across forwarding, connectivity detection, and model listing, getting past coding-plan upstreams that gate on a UA whitelist (which is how the Codex "Kimi For Coding" preset was restored).
+- **Codex unified session history**: a new opt-in toggle lets official Codex sessions share a single resume-history bucket with third-party sessions, with optional migration of existing sessions and precise ledger-based restore.
+- **Proxy and platform hardening**: aggregating mislabeled SSE responses, Codex image rectification, takeover-residue recovery, Hermes YAML de-duplication; in-app updates no longer hang on "restarting", and Codex upgrades no longer break the install.
+
+---
+
+## Added
+
+### Custom User-Agent Override
+
+Provider configs can now set a custom User-Agent that the proxy applies consistently across request forwarding, stream check, and model listing (`GET /v1/models`), so coding-plan upstreams that gate on UA no longer fail detection or return 403 while the proxy itself works. The Claude and Codex forms expose it in advanced settings with a curated presets dropdown (Claude Code / Kilo Code families that pass UA whitelists) and live non-blocking validation; stale custom UAs are dropped when switching to an official preset to avoid silently altering headers (#3671).
+
+### Unified Codex Session History
+
+Official Codex sessions can now share a single resume-history bucket with cc-switch third-party sessions via an opt-in toggle under Settings → Codex App Enhancements, so the resume picker no longer hides them from each other. When enabled, the live `config.toml` routes official runs through a shared `custom` model_provider that mirrors the built-in OpenAI provider (`auth.json` is untouched); the toggle is forward-only by default but the enable dialog offers a checkbox to migrate existing official sessions (with per-generation backups), and the disable dialog offers a precise ledger-based restore that only reverts sessions originally recorded as `openai` while leaving sessions created during the toggle untouched.
+
+### Dashboard-Wide Provider / Model Filters
+
+The provider and model filters move from inside the request-log table up to the top bar, applying globally to the hero summary, trend chart, request logs, and both stats tabs so you can scope the whole dashboard to a given source and model. Sources match by exact display name (so session placeholder rows like "Claude (Session)" are selectable) and models match by effective pricing model, with the model dropdown cascading from the selected source and both lists showing only options that have data in the current range.
+
+### Refreshed Model Pricing Seed
+
+Added pricing for 9 models including Claude Fable 5, Grok 4.3, Mistral Medium 3.5 / Small 4, and Qwen 3.7 Max/Plus, and corrected 28 existing prices against current official vendor list pricing (GLM, Grok, MiMo, Doubao, Kimi, MiniMax, Mistral, Qwen) so usage cost estimates are accurate. Each change updates the seed for fresh installs and adds a guarded repair for existing databases without clobbering user-edited rows.
+
+### Claude Fable 5 Model Tier
+
+Provider forms now expose `claude-fable-5` as a fourth model-mapping tier on both the Claude Code and Claude Desktop proxy paths, with a fable → opus → default fallback mirroring the official downgrade and the `fable-` prefix whitelisted for the Desktop 1.12603.1+ validator. A clarified four-language fallback hint warns that leaving a tier blank on third-party endpoints forwards the literal model name and 404s (#3980, #4026, #4049).
+
+### Unity2.ai Partner Provider
+
+Added Unity2.ai, an AI API relay partner, as a preset across all seven managed apps (Claude Code, Codex, Gemini, OpenCode, OpenClaw, Claude Desktop, Hermes), each carrying the referral signup link and partner promotion copy in all four locales. Codex uses the bare base URL (the gateway exposes `/responses` at root) while OpenCode / OpenClaw / Hermes use the `/v1` chat-completions endpoint with `gpt-5.5`.
+
+### Kimi K2.7 Code Model
+
+Added the `kimi-k2.7-code` model (in $0.95 / out $4.00 / cache-read $0.19 per 1M tokens, 256K context) and pointed all six official Moonshot Kimi presets (Claude Code, Codex, Claude Desktop, Hermes, OpenCode, OpenClaw) at it, renaming the OpenCode / OpenClaw presets to "Kimi K2.7 Code". The pricing seed applies on startup via the idempotent insert path, so existing users pick up the new pricing without a migration.
+
+### Codex "Kimi For Coding" Preset Restored
+
+Re-added the Codex "Kimi For Coding" preset (`openai_chat`, `kimi-for-coding`, 256K context) with thinking mode enabled by default; it was previously removed because the coding endpoint rejects Codex's default `codex-cli` User-Agent with 403. It now works via proxy takeover combined with the custom User-Agent override (set to a whitelisted UA such as `claude-cli/*`).
+
+### Pricing-Model Audit in Request Detail
+
+The request detail panel now shows the requested model and the pricing model when they differ from the response model, making route-takeover bills auditable directly from the usage UI.
+
+### Preset Provider Search & Sorting
+
+The provider preset selector gains a searchable, sorted list with an inline search box (toggled via a magnifier icon, dismissed on ESC or outside click). Buttons use a responsive grid with consistent sizing and default icons, and search matches only provider display/raw names so URL fragments and shared category labels no longer produce noisy matches (#3975, #4183).
+
+### Claude Mythos 5 Pricing
+
+Registered the `claude-mythos-5` model in the bundled model/pricing table (in $10 / out $50 per 1M tokens, cache read $1.00, cache write $12.50), so usage metering prices and displays it correctly (#4077).
+
+### Fable 5 Verified Banner
+
+The Settings About page now displays a Fable 5 Verified banner beside the app name and version, marking this as a special build, with the version badge centered under the app name.
+
+---
+
+## Changed
+
+### Claude Desktop Usage Folded Into Claude
+
+The dashboard no longer shows a standalone "Claude Desktop" bucket, which only ever displayed a partial number (Desktop chat usage never passes through the proxy and its Code-tab sessions write into the shared `~/.claude/projects` tree). Desktop proxy traffic is now folded into the `claude` view for display while still recorded under its own `app_type` for route-takeover billing audit, with the real value visible in the request detail panel.
+
+### Lightweight Provider Health Check
+
+The provider health check no longer sends a real streaming model request (which many third-party providers blocked with 401/403/WAF, causing false negatives); it now performs a lightweight HTTP reachability probe of the provider `base_url`, treating any HTTP response as reachable and counting only DNS/connect/TLS/timeout as failure. The connectivity button is hidden for official providers (which use OAuth with an empty base URL and no reliable reachability target), the real-request confirmation dialog and test model/prompt fields are removed, and the degraded-latency threshold is set to 6s with an 8s timeout. The reachability check never resets the circuit breaker, so failover detection stays driven solely by real proxy traffic.
+
+### Codex Advanced Options Section
+
+The Codex provider form now folds local routing, model mapping, reasoning overrides, and custom User-Agent into a single collapsible advanced section mirroring the Claude form (auto-expanding when a UA is set or local routing is on). Custom User-Agent is now also configurable for native Responses providers, where it was previously reachable only with `openai_chat` routing enabled.
+
+### Usage Toolbar Refresh and Layout
+
+The app filter now renders brand icons (via ProviderIcon, with a grid icon for "All") instead of text tabs that wrapped awkwardly in narrow windows, and the usage hero shows the selected app's brand icon with Codex recolored to a neutral gray matching OpenAI's monochrome branding. The click-to-cycle refresh button becomes a Select with a localized "off" label, and the top-bar controls are compacted and aligned into consistent width groups with truncated long date-range labels.
+
+### Faster About Panel Loading
+
+The Settings About panel now loads progressively: the app version badge appears the instant it resolves instead of waiting for tool probes, each tool card updates the moment its own version check finishes (probes run concurrently rather than sequentially), and results are cached for the app session with a 10-minute TTL so reopening the About tab reuses cached values and revalidates stale ones in the background instead of re-probing all six tools every time.
+
+### Volcengine Ark Coding Plan Promo
+
+Updated the Volcengine Ark preset across all six apps with the new Coding Plan invite link (replacing the old Agent Plan / activity links) and refreshed the partner promotion copy in all four locales (two-month 75% off plus invite code 6J6FV5N2), correcting the product name from Agent Plan to Coding Plan.
+
+### MiniMax Demoted to Regular Provider
+
+Removed the gold partner star badge and the API-key promotion banner for MiniMax by dropping the `isPartner` flag from all its presets; it stays as a regular `cn_official` provider keeping its icon and theme. The promotion copy is kept dormant so the partnership can be re-enabled with a single line.
+
+### LemonData Removed, SudoCode Demoted
+
+Removed the LemonData provider preset entirely from all apps along with its promotion copy, icons, and sponsor listings, and demoted SudoCode from a partner to a regular `third_party` provider by dropping its `isPartner` flag and promotion copy (it keeps its icon).
+
+### AtlasCloud Codex GLM 5.1 Context Window
+
+Declared the 200,000-token context window for the `zai-org/glm-5.1` model in the AtlasCloud Codex preset, matching the other GLM 5.1 preset entries.
+
+---
+
+## Fixed
+
+### Route-Takeover Traffic Billed by the Real Upstream Model
+
+When a request was routed to a different upstream (env model mapping, Claude Desktop routes, Copilot normalization, Codex chat override), the proxy used to attribute and price usage by whatever model the upstream echoed back, recording kimi/glm tokens as `claude-*` and overstating cost roughly 5–25×. The forwarder now captures the real outbound model, attributes usage by upstream-echo then outbound then client alias, persists the actual pricing basis on every row (schema v11), and keeps that basis through cost backfill and 30-day rollup pruning; Claude Desktop traffic is now logged under its own `app_type` so its pricing overrides apply.
+
+### Usage Metering on Format-Conversion Proxy Paths
+
+Audited and fixed token/cache accounting across the proxy's format-conversion paths (Chat, Responses, and Gemini converted to Anthropic). The proxy now records the actually returned model, injects `stream_options.include_usage` so OpenAI-compatible upstreams emit usage in streaming, excludes `cache_read` and `cache_creation` from input on Claude←OpenAI paths to stop double-billing cache tokens, subtracts cached Gemini prompt tokens, still records fully-cached requests, and skips synthetic all-zero usage that previously inflated request counts (#2774).
+
+### In-App Update No Longer Hangs on Restart
+
+Installing an update from within the app no longer freezes on the "restarting" screen, leaving the new version installed but requiring a manual force-quit. The download-install-restart chain now runs entirely in the backend (a new `install_update_and_restart` command) with platform-aware install ordering and single-instance-lock teardown before re-exec, instead of depending on the old WebView to keep running JS after the app bundle was already swapped; exit requests are also classified so restart requests fall through to Tauri's default flow rather than deadlocking on the window-state plugin mutex (#4069, #4074).
+
+### Codex Upgrade No Longer Breaks the Install
+
+Upgrading Codex from the Settings "About" tab no longer leaves it throwing "Missing optional dependency @openai/codex-…" errors. The upgrade chain previously ran `codex update` first, which on an npm install is a bare reinstall that reports success even when the per-platform binary fails to land; Codex is now removed from the self-update-first path and a runnable check triggers an uninstall+reinstall self-heal (scoped to npm-managed installs) that actually re-lands the missing platform binary.
+
+### Codex OAuth Auth Token Preserved on Proxy Takeover
+
+Enabling proxy takeover for a Codex provider no longer strips the `ANTHROPIC_AUTH_TOKEN` placeholder, which previously broke Claude Code's login on hot-switches, fresh installs, and configs already stripped by older releases. The placeholder is now injected unconditionally for managed (non-Copilot) Codex providers, including URL-only ones; GitHub Copilot behavior (API_KEY only) is unchanged (#3789, #3784).
+
+### Takeover-Residue Recovery Across Config-Dir Switches
+
+Restarting the app after changing the config directory while proxy takeover is active no longer leaves Claude/Codex/Gemini pointed at a dead local proxy. The old instance now restores the taken-over live files before restarting, the first-run import refuses to persist a takeover placeholder as a provider, and SSOT restore validates that the current provider's config is free of placeholders before writing it back (#4076).
+
+### Mislabeled SSE Bodies in Format-Transform Fallback
+
+Requests routed through Claude/Codex format conversion no longer fail with an opaque 422 "Failed to parse upstream response" when a MaaS gateway force-streams a `stream:false` request and returns an SSE body under a non-SSE Content-Type. The proxy now sniffs for SSE on parse failure, aggregates the chunks into a single JSON, and runs the existing converter so clients still get a valid non-stream response; remaining parse failures are enriched with content-type, encoding, and body-snippet diagnostics, and deflate decoding now tries zlib before raw (#2234).
+
+### Duplicate YAML Keys in Hermes Config
+
+Hermes config writes no longer accumulate duplicate top-level keys (e.g. `mcp_servers`) that caused "Failed to parse Hermes config as YAML: duplicate entry with key" errors. Section replacement now strips all stale occurrences from the remainder instead of degrading into appends, the dedup safety net handles both LF and CRLF line endings, and healing keeps the last (newest) occurrence to match Hermes's own last-wins PyYAML semantics (#3267, #3633, #2973, #2529, #3310, #3762).
+
+### Usage Query Resilience and Error Clarity
+
+Usage cards no longer flip to red on a single transient blip: queries now retry once and keep showing the last successful result for up to 10 minutes on network/timeout/5xx failures, while deterministic failures (auth, empty key, unknown provider, 4xx) surface immediately and clear the snapshot so a stale quota can't resurface after credentials change. Native balance/coding-plan/subscription timeouts were raised from 10s to 15s for slow cross-border endpoints, and coding-plan now returns explicit "API key is empty" / "Unknown coding plan provider" errors instead of a blank failure.
+
+### Usage Script Provider Credential Resolution
+
+Custom JS-script usage queries resolved `{{apiKey}}` / `{{baseUrl}}` by guessing env fields only, so providers that store credentials elsewhere (e.g. Codex's `auth.OPENAI_API_KEY` plus `config.toml` base_url) always got empty values and failed despite being fully configured. Script queries and the test/preview now reuse the same per-app credential resolver as the native balance path, with explicit non-empty script values still taking precedence (#1479).
+
+### Claude Code Workflow Sub-Agent Usage Counted
+
+Local (no-proxy) session-log usage accounting missed Claude Code Workflow sub-agent traffic, under-counting overall usage by roughly 4.1% (concentrated in workflow/subagent transcripts). The scanner now descends into the deeper `subagents/workflows/wf_*/` transcript directories, and the parser no longer drops billable assistant messages that lack a `stop_reason` but already incurred input/cache token cost; dedup is unchanged so no usage is double-counted.
+
+### Codex Image Rectifier for /responses Text-Only Upstreams
+
+Codex `/responses` requests carrying images and routed to text-only OpenAI-chat models (e.g. DeepSeek `deepseek-v4-flash`) no longer fail with HTTP 400 "unknown variant `image_url`". The media rectifier now also covers the Codex adapter, scanning the responses `input` for `input_image` blocks so it can proactively strip images for known text-only models and reactively retry with images replaced on upstream image-unsupported errors.
+
+### Zhipu Coding-Plan Quota Window Mislabeling
+
+The Zhipu coding-plan view no longer swaps the 5-hour and weekly quota buckets in the final hours of each weekly cycle. The two windows are now classified by the explicit `unit` field (3 = 5-hour, 6 = weekly) instead of by sorting reset-time ascending, which mislabeled them exactly when users check their weekly quota most; the old reset-time heuristic remains as a fallback (#3036).
+
+### Duplicate Provider Terminal Sessions on macOS
+
+Launching a provider terminal on macOS no longer opens an extra empty window alongside the command session; Terminal.app uses `launch` (not `activate`) on cold start and Ghostty uses an initial-command so a single session opens, with a fallback retained if the AppleScript path fails (#4156).
+
+### Claude Desktop Model-Mapping Placeholders
+
+The Claude Desktop model-mapping form previously showed mismatched example brands across the menu display name and request model columns (DeepSeek vs Kimi), implying a display name maps to an unrelated model. Both placeholders are now derived from each row's role so they stay brand-consistent, with the lightweight Haiku tier using a flash example.
+
+### Popovers Behind Fullscreen Panels
+
+Popovers and tooltips such as the provider preset search no longer render behind fullscreen panels and appear unresponsive on click; their z-index is raised above the fullscreen overlay while staying below modal dialogs.
+
+### ToggleRow Icon Shrinking
+
+Toggle row icons no longer shrink or distort when paired with long descriptions, keeping the icon at a fixed size next to multi-line text.
+
+---
+
+## Documentation
+
+### Release Notes Contributor Mentions
+
+Restored contributor mentions in the v3.16.1 and v3.16.2 release notes across all three locales.
+
+---
+
+## Upgrade Notes
+
+### Pricing Database schema v11 Auto-Migration
+
+This release adds a `pricing_model` column to `proxy_request_logs` and rebuilds the rollup by `request_model` + `pricing_model`, migrating automatically on startup with no manual action required. Historical rows have their cost frozen at write time and are not recalculated (rows with `app_type="claude"` mix native and converted sources); only real but previously un-priced takeover rows stay at zero cost until pricing is supplied and then backfilled.
+
+### Model Mapping Adds a Fourth Tier (Fable 5)
+
+The Claude Code and Claude Desktop model mappings now have four tiers (Sonnet / Opus / Fable / Haiku). Older three-tier providers pick up the `claude-fable-5` tier after being reopened and saved; leaving that tier blank means it inherits Sonnet. Note: leaving any tier blank on third-party endpoints forwards the literal model name of that tier and may 404, so fill it in as needed.
+
+### The "Kimi For Coding" Preset Needs Proxy Takeover + a Whitelisted UA
+
+The restored Codex "Kimi For Coding" preset is still rejected with 403 if used with the default `codex-cli` User-Agent. To use it, enable proxy takeover and set the custom User-Agent in the provider's advanced options to a whitelisted UA (such as `claude-cli/*`).
+
+### Provider Health Check Semantics Changed
+
+The health check changed from "send a real model request" to "HTTP reachability probe". Note that reachable ≠ usable: a host that returns 403 is reachable but may be broken for real traffic. Failover decisions remain driven solely by real proxy traffic and are unaffected by the health check.
+
+---
+
+## Risk Notice
+
+This release continues the risk notices from previous versions for reverse-proxy-style features.
+
+**Codex OAuth reverse proxy**: using a ChatGPT subscription's Codex OAuth through a reverse proxy may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details.
+
+**Codex third-party provider Chat routing**: when CC Switch local proxy converts and forwards Codex requests to third-party providers, each provider may have different requirements for billing, compliance, and data retention. Read the target provider's terms before use.
+
+**Claude Desktop third-party provider proxy switching**: when CC Switch's built-in proxy gateway forwards Claude Desktop requests to third-party providers, you must also follow the target provider's billing, compliance, and data-retention terms.
+
+By enabling these features, users accept the related risks. CC Switch is not responsible for account restrictions, warnings, or service suspensions caused by using these features.
+
+---
+
+## Thanks
+
+Thanks to the following contributors for the features and fixes in v3.16.3:
+
+- [#3789](https://github.com/farion1231/cc-switch/pull/3789): preserve Codex OAuth auth token on takeover, thanks @codeasier.
+- [#2774](https://github.com/farion1231/cc-switch/pull/2774): fix model / input-token recording on Completions→Anthropic, thanks @LaoYueHanNi.
+- [#4069](https://github.com/farion1231/cc-switch/pull/4069): fix the deadlock on relaunch after an in-app update, thanks @thisTom.
+- [#4156](https://github.com/farion1231/cc-switch/pull/4156): fix duplicate provider terminal sessions on macOS, thanks @thisTom.
+- [#3267](https://github.com/farion1231/cc-switch/pull/3267): fix duplicate YAML keys in the Hermes config, thanks @que3sui.
+- [#1479](https://github.com/farion1231/cc-switch/pull/1479): fix usage script provider credential resolution, thanks @pa001024.
+- [#3975](https://github.com/farion1231/cc-switch/pull/3975): add preset search and sorting, thanks @Nastem.
+- [#4183](https://github.com/farion1231/cc-switch/pull/4183): adjust the preset-provider button appearance and search-box position, thanks @WangJiati.
+- [#4077](https://github.com/farion1231/cc-switch/pull/4077): add claude-mythos-5 model pricing, thanks @osscv.
+
+Thanks also to everyone who reported usage billing, local proxy robustness, Codex upgrade, and platform compatibility issues after v3.16.2. Many of these fixes came directly from real-world reproduction details.
+
+---
+
+## Download & Install
+
+Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) and download the build for your system.
+
+### System Requirements
+
+| System  | Minimum Version          | Architecture                        |
+| ------- | ------------------------ | ----------------------------------- |
+| Windows | Windows 10 and later     | x64                                 |
+| macOS   | macOS 12 (Monterey)+     | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | See table below          | x64 / ARM64                         |
+
+### Windows
+
+| File                                     | Description                                      |
+| ---------------------------------------- | ------------------------------------------------ |
+| `CC-Switch-v3.16.3-Windows.msi`          | **Recommended** - MSI installer with auto-update |
+| `CC-Switch-v3.16.3-Windows-Portable.zip` | Portable build, unzip and run                    |
+
+### macOS
+
+| File                             | Description                                           |
+| -------------------------------- | ----------------------------------------------------- |
+| `CC-Switch-v3.16.3-macOS.dmg`    | **Recommended** - DMG installer, drag to Applications |
+| `CC-Switch-v3.16.3-macOS.zip`    | Unzip and drag to Applications, Universal Binary      |
+| `CC-Switch-v3.16.3-macOS.tar.gz` | For Homebrew install and auto-update                  |
+
+Homebrew install:
+
+```bash
+brew install --cask cc-switch
+```
+
+Upgrade:
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+Linux assets are available for both **x86_64** and **ARM64** (`aarch64`). Choose the file whose architecture tag matches your machine's `uname -m` output:
+
+- `CC-Switch-v3.16.3-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.16.3-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| Distribution                            | Recommended Format | Install Command                                                        |
+| --------------------------------------- | ------------------ | --------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`             | `sudo dpkg -i CC-Switch-*.deb` or `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`             | `sudo rpm -i CC-Switch-*.rpm` or `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`             | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                    | `.AppImage`        | Make executable and run directly, or use AUR                          |
+| Other distributions / unsure            | `.AppImage`        | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`             |
@@ -0,0 +1,340 @@
+# CC Switch v3.16.3
+
+> 🎉 **CC Switch が 100,000 Star を突破しました！**
+> すべてのユーザー・コントリビューター・Star をくださった方々に感謝します —— 皆さんのおかげでここまで来ました。🙏
+
+> 💎 **本リリースは Claude Fable 5 モデルの協力のもとで開発されました**——重要かつ間違えやすいロジックの整理を手伝ってくれました: ルーティングテイクオーバー時に本物の上流モデルで課金する帰属チェーン、形式変換経路でのキャッシュ token の計上と重複排除、アプリ内更新の再起動デッドロック、そして Codex 統一セッション履歴の移行 / 復元の不変条件です。本リリースの「バージョン情報」ページに **Fable 5 Verified** バッジを新設したのもこのためです。
+
+> v3.16.2 でデータの可搬性と使用量の可観測性を広げたのに続き、本リリースは「使用量の課金を本当に正確にする」ことに重きを置いています——本物の上流モデルで課金し、形式変換経路でのキャッシュの二重計上を修正し、Claude Code Workflow のサブ agent の使用量を統計に取り込み（schema v11）、使用量ダッシュボードを一通り刷新しました（全体に効くプロバイダー / モデルフィルタ、ブランドアイコンのツールバー、より安定した残量照会）。あわせて一連のローカルプロキシとプラットフォームの問題を補強し、カスタム User-Agent オーバーライド、Codex 統一セッション履歴のトグル、Claude Fable 5 階層を新設しました。
+
+**[English →](v3.16.3-en.md) | [中文版 →](v3.16.3-zh.md)**
+
+---
+
+## 利用ガイド
+
+本リリースでは **Codex 統一セッション履歴** のトグルを新設しました——セッションの移行 / 復元を伴い、操作を誤ると「セッションが消えた」と誤解しやすいため、まずこのガイドを読むことを強くおすすめします。また使用量統計の数え方とダッシュボードにも多くの調整を加えたので、あわせて以下をご覧ください：
+
+- **[Codex セッション履歴の統一: 機能紹介と利用ガイド](../guides/codex-unified-session-history-guide-ja.md)**: 「統一 / 移行 / 復元」が実際に何を変えるのか、なぜデータが本当に失われないのか、そしてセッションが見えないときの自己点検と正確な復元の方法を解説します。**このトグルを使った、またはセッションが消えたと心配な方は、まずこちらをお読みください。**
+- **[使用量統計](../user-manual/ja/4-proxy/4.4-usage.md)**: 使用量ダッシュボードのデータソース（プロキシログ、セッション同期）と集計の仕組みを確認できます。本リリースで全体に効くプロバイダー / モデルフィルタを追加し、ルーティングテイクオーバー時の本物の課金モデルを表示するようにしました。
+- **[設定](../user-manual/ja/1-getting-started/1.5-settings.md)**: カスタム User-Agent オーバーライド、Codex 統一セッション履歴などのトグルは、プロバイダーフォームの高度なオプションと設定ページにあります。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一の公式チャネル（必ずお読みください）
+>
+> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。本ソフトウェアは下記の公式チャネルからのみ入手してください：
+>
+> | チャネル     | 唯一の公式                                                                     |
+> | ------------ | ------------------------------------------------------------------------------ |
+> | 公式サイト   | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者         | **[@farion1231](https://github.com/farion1231)**                               |
+> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は直ちに操作を中止し、GitHub Issues からご報告ください。
+
+---
+
+## 概要
+
+CC Switch v3.16.3 は v3.16.2 に続くメンテナンスアップデートです。前リリースではデータの可搬性と使用量の可観測性の拡張に集中しましたが、本リリースは「使用量の課金を本当に正確にする」ことに重きを置いています——上流が返すエイリアスではなく本物の上流モデルで課金し、形式変換（Chat / Responses / Gemini を Anthropic へ）経路でのキャッシュ token の二重計上を修正し、Claude Code Workflow のサブ agent の使用量をローカル統計に取り込み、schema v11 で各レコードが実際に使用した課金根拠を永続化しました。使用量ダッシュボードもこれにあわせて一通り刷新し、全体に効くプロバイダー / モデルフィルタ、ブランドアイコンのツールバー、より安定した残量照会（失敗時の再試行 + 前回成功した結果の保持）を追加しました。
+
+さらに本リリースでは、一連のローカルプロキシの堅牢性に関する問題（Content-Type が誤ってラベル付けされた SSE レスポンスの集約、Codex `/responses` のテキスト専用モデル向け画像整流、Codex OAuth 認証情報とテイクオーバー残留の復元、Hermes 設定の重複 YAML キー）を補強し、プロバイダー設定まわりを作り直し（カスタム User-Agent オーバーライド、Codex フォームの高度なオプションへの統合、プリセット検索とソート、Claude Fable 5 階層）、Codex 統一セッション履歴のトグルを新設し、アプリ内更新のハング、Codex のアップグレードによるインストール破損、macOS の重複ターミナルウィンドウなどの問題を修正しました。
+
+**リリース日**: 2026-06-14
+
+**Stats**: 59 commits | 130 files changed | +10,223 / -4,232 lines
+
+---
+
+## ハイライト
+
+- **使用量の課金がより正確に**: ルーティングテイクオーバーのトラフィックを本物の上流モデルで課金するようになり（上流が返すエイリアスではなく）、形式変換経路でキャッシュ token を input に二重計上しなくなり、Claude Code Workflow のサブ agent の使用量も統計に取り込みました——schema v11 で課金根拠を永続化します。
+- **使用量ダッシュボードの刷新**: プロバイダー / モデルフィルタをリクエストログテーブルから全体フィルタへ引き上げ、アプリフィルタをブランドアイコンに変更し、残量照会に失敗時の再試行と「前回成功した結果の保持」を追加して、一度のネットワークのゆらぎでカードが赤くならないようにしました。
+- **カスタム User-Agent オーバーライド**: プロバイダーにカスタム UA を設定でき、転送・接続性チェック・モデル一覧の 3 か所で一貫して有効になり、UA ホワイトリストで制限する Coding Plan 上流を通過できます（これにより Codex「Kimi For Coding」プリセットを復活させました）。
+- **Codex 統一セッション履歴**: 公式 Codex セッションとサードパーティセッションが同じ resume 履歴バケットを共有できる任意のトグルを新設し、既存セッションの任意移行と台帳に基づく精密な復元を備えます。
+- **プロキシとプラットフォームの補強**: 誤ラベルの SSE レスポンスの集約、Codex 画像整流、テイクオーバー残留の復元、Hermes YAML 重複排除。アプリ内更新が「再起動中」でハングしなくなり、Codex のアップグレードでインストールを壊さなくなりました。
+
+---
+
+## 追加機能
+
+### カスタム User-Agent オーバーライド
+
+プロバイダー設定でカスタム User-Agent を設定できるようになり、プロキシがリクエスト転送、接続性チェック、モデル一覧（`GET /v1/models`）の 3 つの経路で一貫して適用します。これにより、UA ホワイトリストで制限する Coding Plan 上流で「検出は失敗 / モデル一覧は 403 なのにプロキシ本体は正常に動く」という不整合が起きなくなります。Claude と Codex のフォームはいずれも高度なオプションでこのフィールドを公開し、厳選した UA プリセットのドロップダウン（Claude Code / Kilo Code など UA ホワイトリストを通過できるファミリー）とリアルタイムで非ブロッキングな形式検証を備えます。公式プリセットへ切り替えると残っていたカスタム UA は破棄され、リクエストヘッダーを密かに変更しないようにします（[#3671](https://github.com/farion1231/cc-switch/pull/3671)）。
+
+### Codex 統一セッション履歴
+
+任意のトグル（設定 → Codex アプリ拡張）を新設し、公式 Codex セッションと CC Switch のサードパーティセッションが同じ resume 履歴バケットを共有できるようにしました。resume セレクタが両者を互いに隠さなくなります。有効化すると、live の `config.toml` は公式の実行を、内蔵 OpenAI プロバイダーをミラーした共有 `custom` model_provider へルーティングします（`auth.json` は変更しません）。デフォルトでは今後のセッションにのみ有効です。有効化ダイアログには既存の公式セッションを共有バケットへ移行できるチェックボックスがあり（世代ごとのバックアップ付き）、無効化ダイアログにはバックアップ台帳に基づく精密な復元が用意されています——バックアップ内で `openai` として記録されたセッションのみを巻き戻し、有効化中に新規作成されたセッションは決して変更しません。
+
+### 使用量ダッシュボードの全体プロバイダー / モデルフィルタ
+
+プロバイダーフィルタとモデルフィルタを、リクエストログテーブルの内部からトップバーへ引き上げ、Hero サマリー、トレンドグラフ、リクエストログ、2 つの統計タブ全体に効くようにしました。ダッシュボード全体を特定のソースとモデルで絞り込めます。ソースは表示名で厳密に一致するため「Claude (Session)」のようなセッションのプレースホルダー行も選択でき、モデルは有効な課金モデルで一致し、モデルのドロップダウンは選択したソースに応じてカスケードし、どちらの一覧も現在の期間にデータがある選択肢のみを表示します。
+
+### モデル価格シードの刷新
+
+`seed_model_pricing` の全件価格点検を実施しました: 9 個のモデルの価格を新規追加し（Claude Fable 5、Grok 4.3、Mistral Medium 3.5 / Small 4、Qwen 3.7 Max/Plus などを含む）、各ベンダー公式の定価に合わせて既存価格 28 か所を訂正し（GLM、Grok、MiMo、Doubao、Kimi、MiniMax、Mistral、Qwen）、使用量コストの見積りをより正確にしました。各変更はシード（新規インストールに影響）を更新すると同時に、`repair_current_model_pricing` に旧→新のガードを 1 件追加します（既存データベースを修復し、ユーザーが手動で編集した行は上書きしません）。
+
+### Claude Fable 5 モデル階層
+
+プロバイダーフォームは、Claude Code と Claude Desktop の両プロキシ経路で `claude-fable-5` を 4 つ目のモデルマッピング階層として公開するようになりました。フォールバックチェーンは fable → opus → default で、公式の降格と一致し、Claude Desktop 1.12603.1+ の検証器で `fable-` プレフィックスを許可しました。4 言語のフォールバックヒントも明確化しました: サードパーティの endpoint である階層を空のままにすると、その階層のモデル名がそのまま透過されて 404 になります（[#3980](https://github.com/farion1231/cc-switch/issues/3980)、[#4026](https://github.com/farion1231/cc-switch/issues/4026)、[#4049](https://github.com/farion1231/cc-switch/issues/4049)）。
+
+### Unity2.ai パートナープロバイダー
+
+Unity2.ai（AI API 中継のパートナー）をプリセットとして追加し、管理対象の 7 アプリすべて（Claude Code、Codex、Gemini、OpenCode、OpenClaw、Claude Desktop、Hermes）をカバーしました。各プリセットには紹介登録リンクを付け、4 言語でパートナー宣伝文を補いました。Codex は素の base URL を使用し（このゲートウェイはルートパスに `/responses` を公開）、OpenCode / OpenClaw / Hermes は `/v1` chat-completions の endpoint を使用し、`gpt-5.5` を既定モデルとします。
+
+### Kimi K2.7 Code モデル
+
+`kimi-k2.7-code` モデル（入力 $0.95 / 出力 $4.00 / キャッシュ読み取り $0.19、100 万 token あたり、256K コンテキスト）を新規追加し、6 つの公式 Moonshot Kimi プリセットすべて（Claude Code、Codex、Claude Desktop、Hermes、OpenCode、OpenClaw）をこれに向けました。OpenCode / OpenClaw のプリセットは「Kimi K2.7 Code」へ改名しました。価格シードは起動時の冪等な挿入経路で有効になるため、既存ユーザーは移行なしで新価格を取得できます。
+
+### Codex「Kimi For Coding」プリセットの復活
+
+Codex「Kimi For Coding」プリセット（`openai_chat`、`kimi-for-coding`、256K コンテキスト）を再追加し、思考モードをデフォルトで有効にしました。以前これを削除したのは、このコーディング endpoint が Codex 既定の `codex-cli` User-Agent を 403 で拒否するためでしたが、現在はプロキシテイクオーバー + カスタム User-Agent オーバーライド（ホワイトリストの UA、例 `claude-cli/*` に設定）を使えば正常に使えます。
+
+### リクエスト詳細での課金モデル監査
+
+リクエスト詳細パネルは、「リクエストされたモデル」「課金モデル」がレスポンスのモデルと一致しないときにそれらをすべて表示するようになり、ルーティングテイクオーバーが生む請求を使用量画面から直接照合できます。
+
+### プリセットプロバイダーの検索とソート
+
+プリセットプロバイダーのセレクタが、検索・ソート可能な一覧になり、インライン検索ボックスを備えました（虫眼鏡アイコンで切り替え、ESC または外側クリックで畳む）。ボタンはレスポンシブグリッドに変わってサイズが統一され、既定アイコンを表示します。検索はプロバイダーの表示名 / 生の名前のみに一致するため、URL の断片や共有のカテゴリラベルがノイズ一致を生まなくなります（[#3975](https://github.com/farion1231/cc-switch/pull/3975)、[#4183](https://github.com/farion1231/cc-switch/pull/4183)）。
+
+### Claude Mythos 5 の価格
+
+内蔵のモデル / 価格表に `claude-mythos-5` モデル（入力 $10 / 出力 $50、100 万 token あたり；キャッシュ読み取り $1.00、キャッシュ書き込み $12.50）を登録し、使用量統計が正しく課金・表示できるようにしました（[#4077](https://github.com/farion1231/cc-switch/pull/4077)）。
+
+### Fable 5 Verified バッジ
+
+設定の「バージョン情報」ページが、アプリ名とバージョンの隣に Fable 5 Verified バッジを表示し、これが特別ビルドであることを示すようになりました。バージョンバッジもアプリ名の下に中央揃えしました。
+
+---
+
+## 変更
+
+### Claude Desktop の使用量を Claude に折りたたみ
+
+ダッシュボードは独立した「Claude Desktop」バケットを表示しなくなりました——これは常に不完全な数字しか表示できませんでした（Desktop のチャット使用量はそもそもプロキシを経由せず、その Code タブのセッションは内蔵の Claude Code ランタイムが共有の `~/.claude/projects` ディレクトリへ書き込んでいるだけです）。Desktop のプロキシトラフィックは表示上 `claude` に折りたたまれますが、記帳層はルーティングテイクオーバー課金の監査のために引き続き自身の `app_type` で記録し、本物の値はリクエスト詳細パネルで確認できます。
+
+### 軽量化したプロバイダーヘルスチェック
+
+プロバイダーヘルスチェックは、本物のストリーミングモデルリクエストを送らなくなりました（多くのサードパーティプロバイダーが 401/403/WAF でブロックし、利用不可の誤検知を生むため）。代わりにプロバイダーの `base_url` へ軽量な HTTP 到達性プローブを 1 回行います: あらゆる HTTP レスポンスを到達可能とみなし、DNS / 接続 / TLS / タイムアウトのみを失敗とします。公式プロバイダー（OAuth を使用し、base_url が意図的に空で、信頼できる到達性ターゲットがない）は接続性チェックのボタンを隠します。従来の「本物のリクエストを送る」確認ダイアログ、テストモデル / プロンプトのフィールドは削除し、劣化レイテンシのしきい値を 6s、タイムアウトを 8s としました。この到達性チェックは決してサーキットブレーカーをリセットしません——到達可能 ≠ 利用可能（403 を返す host は到達可能でも、本物のトラフィックには壊れています）。フェイルオーバーの判定は引き続き本物のプロキシトラフィックのみで駆動されます。
+
+### Codex の高度なオプション領域の統合
+
+Codex プロバイダーフォームは、ローカルルーティング、モデルマッピング、推論オーバーライド、カスタム User-Agent を展開可能な高度なオプション領域に折りたたみ、Claude フォームと揃えました（UA が設定されているか、ローカルルーティングが有効なときは自動展開）。カスタム User-Agent はネイティブ Responses プロバイダーでも設定できるようになりました。以前は `openai_chat` ルーティングを有効にしたときにしか触れられませんでした。
+
+### 使用量ツールバーとレイアウトの刷新
+
+アプリフィルタはブランドアイコン（ProviderIcon 経由、「すべて」はグリッドアイコン）で描画するように変更し、狭いウィンドウで折り返すと見栄えの悪かったテキストタブを置き換えました。使用量 Hero も選択したアプリのブランドアイコンを表示し、Codex のテーマ色をエメラルドからニュートラルグレーへ変更して、OpenAI のモノクロブランドに合わせました。クリックで循環切り替えしていた更新ボタンは、ローカライズした「オフ」ラベルを持つドロップダウン選択に変更し、トップバーのコントロールも圧縮して幅のグループを揃え、長すぎる日付範囲のラベルは省略表示するようにしました。
+
+### バージョン情報パネルの読み込みを高速化
+
+設定の「バージョン情報」パネルが段階的に読み込むようになりました: アプリのバージョンバッジは解決した瞬間に表示され、ツールのプローブを待たなくなります。各ツールカードは自身のバージョン検出が完了した時点で即座に更新されます（プローブは直列ではなく並行に実行）。プローブ結果はアプリのセッション中、10 分の TTL 付きでキャッシュされるため、「バージョン情報」タブを再度開くとキャッシュ値を再利用し、期限切れの項目だけをバックグラウンドで再検証します。毎回 6 つのツールすべてを再プローブすることはなくなりました。
+
+### 火山方舟 Coding Plan の宣伝更新
+
+火山方舟（Volcengine Ark）プリセットを 6 アプリすべてで新しい Coding Plan 招待リンクへ更新し（旧 Agent Plan / キャンペーンリンクを置き換え）、4 言語でパートナー宣伝文を刷新しました（2 か月 75% 割引 + 招待コード 6J6FV5N2）。製品名も Agent Plan から Coding Plan へ訂正しました。
+
+### MiniMax を通常プロバイダーへ降格
+
+MiniMax の金色のパートナースター印と API key 宣伝バナーを削除し（全プリセットから `isPartner` フラグを除去）、引き続き通常の `cn_official` プロバイダーとしてアイコンとテーマを保持します。宣伝文は休眠状態のまま残し、必要であれば 1 行で提携関係を再有効化できます。
+
+### LemonData を削除、SudoCode を降格
+
+LemonData プロバイダープリセットを完全に削除し（宣伝文、アイコン、スポンサー項目もあわせて）、SudoCode をパートナーから通常の `third_party` プロバイダーへ降格しました（`isPartner` フラグと宣伝文を外し、アイコンは保持）。
+
+### AtlasCloud Codex GLM 5.1 のコンテキストウィンドウ
+
+AtlasCloud Codex プリセットの `zai-org/glm-5.1` モデルに 200,000 token のコンテキストウィンドウを宣言し、ほかの GLM 5.1 プリセット項目に揃えました。
+
+---
+
+## 修正
+
+### ルーティングテイクオーバーのトラフィックを本物の上流モデルで課金
+
+リクエストが別の上流へルーティングされた場合（env モデルマッピング、Claude Desktop ルーティング、Copilot 正規化、Codex chat オーバーライド）、プロキシは以前、上流が返したモデルで帰属・課金していたため、kimi / glm の token を `claude-*` として記録・課金し、コストが約 5〜25 倍に過大評価されていました。現在は転送器が本物のアウトバウンドモデルを捕捉し、「上流が返した値 → アウトバウンドモデル → クライアントのエイリアス」の順で帰属し、各行に実際に使用した課金根拠を永続化します（schema v11）。この根拠はコストのバックフィルと 30 日 rollup のプルーニングまで一貫して使われます。Claude Desktop のトラフィックも自身の `app_type` で記録されるようになり、その価格オーバーライドが正しく効くようになりました。
+
+### 形式変換経路での使用量計上
+
+プロキシの各形式変換経路（Chat、Responses、Gemini を Anthropic へ）での token / キャッシュの計上を監査・修正しました。プロキシは実際に返ったモデルを記録し、`stream_options.include_usage` を注入して OpenAI 互換の上流がストリーミング時に usage を吐くようにし、Claude←OpenAI 経路では `cache_read` と `cache_creation` を input から除外してキャッシュ token の二重計上を防ぎ、Gemini のキャッシュ済みプロンプト token を差し引き、完全にキャッシュヒットしたリクエストも引き続き記録し、過去にリクエスト数を水増ししていた合成の全ゼロ usage をスキップするようになりました（[#2774](https://github.com/farion1231/cc-switch/pull/2774)）。
+
+### アプリ内更新がハングしなくなった
+
+アプリ内から更新をインストールするとき、「再起動中」の画面でハングしなくなりました——以前は新版がインストール済みなのに、手動で強制終了せざるを得ない状況が起きていました。ダウンロード—インストール—再起動の一連の流れは、完全にバックエンドで実行するようになり（`install_update_and_restart` コマンドを新設）、プラットフォームごとにインストール順序を決め、再実行の前にまず単一インスタンスロックを破棄します。アプリパッケージがすでに置き換えられた後に古い WebView が JS を走らせ続けることに依存しなくなりました。終了リクエストも分類して、再起動リクエストが Tauri の既定フローに落ちるようにし、ウィンドウ状態プラグインのミューテックスでデッドロックしないようにしました（[#4069](https://github.com/farion1231/cc-switch/pull/4069)、[#4074](https://github.com/farion1231/cc-switch/pull/4074)）。
+
+### Codex のアップグレードがインストールを壊さなくなった
+
+設定の「バージョン情報」ページから Codex をアップグレードしても、「Missing optional dependency @openai/codex-…」エラーを投げなくなりました。アップグレードのチェーンは以前まず `codex update` を実行しますが、これは npm インストール下では実質的に素の再インストールであり、対応するプラットフォームのバイナリがインストールされていなくても成功を報告していました。現在は Codex を「self-update 優先」経路から除外し、runnable 検出が「アンインストール + 再インストール」の自己修復を駆動するようにしました（npm 管理のインストールに限定）。これが、欠けたプラットフォームバイナリを本当に補える唯一の修正です。
+
+### テイクオーバー時に Codex OAuth 認証情報を保持
+
+Codex プロバイダーでプロキシテイクオーバーを有効にするとき、`ANTHROPIC_AUTH_TOKEN` プレースホルダーを剥がさなくなりました——以前これはホットスイッチ、新規インストール、そして旧バージョンがすでに剥がしてしまった live 設定で、Claude Code のログインを壊していました。現在は管理対象（非 Copilot）の Codex プロバイダーに対して、URL のみのプロバイダーを含め無条件にこのプレースホルダーを注入します。GitHub Copilot の挙動（API_KEY のみ）は変わりません（[#3789](https://github.com/farion1231/cc-switch/pull/3789)、[#3784](https://github.com/farion1231/cc-switch/issues/3784)）。
+
+### 設定ディレクトリをまたぐ切り替えでのテイクオーバー残留の復元
+
+プロキシテイクオーバーが有効なときに設定ディレクトリを変更してアプリを再起動しても、Claude / Codex / Gemini を失効したローカルプロキシに向けたままにしなくなりました。現在は旧インスタンスが再起動の前にテイクオーバーされた live ファイルを先に復元し、初回実行のインポートはテイクオーバープレースホルダーをプロバイダーとして永続化することを拒否し、SSOT の復元も書き戻す前に、現在のプロバイダーの設定にプレースホルダーが含まれないことを検証します（[#4076](https://github.com/farion1231/cc-switch/pull/4076)）。
+
+### 形式変換フォールバックでの誤ラベル SSE レスポンスの集約
+
+Claude / Codex の形式変換を経たリクエストで、MaaS ゲートウェイが `stream:false` のリクエストを強制的にストリーミングし、非 SSE の Content-Type で SSE レスポンスボディを返したとき、難解な 422「Failed to parse upstream response」で失敗しなくなりました。プロキシは解析失敗時に SSE かどうかを検出し、チャンクを単一の JSON に集約してから既存の変換器を走らせ、クライアントが引き続き有効な非ストリーミングレスポンスを受け取れるようにします。残った解析失敗には content-type、エンコーディング、レスポンスボディの抜粋などの診断情報を付け、deflate のデコードも先に zlib を、次に素のストリームを試すように変更しました（[#2234](https://github.com/farion1231/cc-switch/pull/2234)）。
+
+### Hermes 設定の重複 YAML キー
+
+Hermes 設定の書き込みは、重複したトップレベルキー（`mcp_servers` など）を累積しなくなりました。これは「Failed to parse Hermes config as YAML: duplicate entry with key」エラーを引き起こしていました。セクションの置換は、追加へ退化する代わりに、残りのテキストから古いコピーをすべて取り除くようになりました。重複排除のセーフティネットは LF と CRLF の行末を両方処理します。修復時には最後（最新）のコピーを保持し、Hermes 自身の PyYAML ベースの「後勝ち」セマンティクスに揃えます（[#3267](https://github.com/farion1231/cc-switch/pull/3267)、[#3633](https://github.com/farion1231/cc-switch/issues/3633)、[#2973](https://github.com/farion1231/cc-switch/issues/2973)、[#2529](https://github.com/farion1231/cc-switch/issues/2529)、[#3310](https://github.com/farion1231/cc-switch/issues/3310)、[#3762](https://github.com/farion1231/cc-switch/issues/3762)）。
+
+### 使用量照会の堅牢性とエラーの明確さ
+
+使用量カードは、一度の瞬間的なゆらぎだけで赤くならなくなりました: 照会は一度再試行し、ネットワーク / タイムアウト / 5xx のような一時的な失敗下では前回成功した結果を最大 10 分間表示し続けます。一方、確定的な失敗（認証、空の key、未知のプロバイダー、4xx）は即座に表面化してスナップショットをクリアし、認証情報の変更後に古い残量が再び現れるのを防ぎます。ネイティブ残量 / Coding Plan / サブスクリプション照会のタイムアウトは、応答の遅い国際 endpoint に合わせて 10s から 15s へ引き上げました。Coding Plan も空白の失敗ではなく、明確な「API key is empty」/「Unknown coding plan provider」エラーを返すようになりました。
+
+### 使用量スクリプトのプロバイダー認証情報の解決
+
+カスタム JS スクリプトの使用量照会は、以前 env フィールドを推測して `{{apiKey}}` / `{{baseUrl}}` を解決していたため、認証情報を別の場所に置くアプリ（Codex の `auth.OPENAI_API_KEY` に加え `config.toml` の base_url など）は、プロバイダーが完全に設定されていても常に空の値となり失敗していました。スクリプト照会とそのテスト / プレビューは、ネイティブ残量経路と同じアプリごとの認証情報リゾルバを再利用するようになり、スクリプト内で明示的に記入した非空の値は引き続き優先されます（[#1479](https://github.com/farion1231/cc-switch/pull/1479)）。
+
+### Claude Code Workflow サブ agent の使用量集計
+
+ローカル（プロキシなし）のセッションログ使用量集計は、以前 Claude Code Workflow のサブ agent のトラフィックを取りこぼしており、全体の使用量が約 4.1% 過小評価されていました（workflow / subagent のセッションレコードに集中）。スキャナーはさらに一段深い `subagents/workflows/wf_*/` のレコードディレクトリまで掘り下げるようになり、パーサーも `stop_reason` を欠いているがすでに input / キャッシュ token のコストを生んだ assistant メッセージを捨てなくなりました。重複排除のロジックは変わらないため、重複計上はしません。
+
+### Codex `/responses` のテキスト専用モデル向け画像整流
+
+画像を伴い、テキストのみ対応の OpenAI-chat モデル（DeepSeek `deepseek-v4-flash` など）へルーティングされた Codex `/responses` リクエストが、HTTP 400「unknown variant `image_url`」で失敗しなくなりました。メディア整流器が Codex アダプターもカバーするようになり、responses の `input` 内の `input_image` ブロックをスキャンします。これにより、既知のテキスト専用モデルに対しては画像をプロアクティブに剥がし、上流が「画像非対応」を報告したときにも画像を置き換えて再試行できます。
+
+### 智譜 Coding Plan のクォータウィンドウの誤ラベル
+
+智譜 Coding Plan ビューは、各週周期の最後の数時間で 5 時間ウィンドウと週ウィンドウを取り違えてラベル付けしなくなりました。両ウィンドウは今や明示的な `unit` フィールドで分類され（3 = 5 時間、6 = 週）、リセット時刻の昇順ソートに頼らなくなりました——後者はユーザーが週クォータを最も照会するタイミングで、ちょうど両者を取り違えてラベル付けしていました。フィールドが欠けているときは引き続き従来のリセット時刻ヒューリスティックへフォールバックします（[#3036](https://github.com/farion1231/cc-switch/pull/3036)）。
+
+### macOS の重複プロバイダーターミナルウィンドウ
+
+macOS でプロバイダーターミナルを起動するとき、コマンドセッションの隣に空のウィンドウをもう 1 つ開かなくなりました。Terminal.app はコールドスタート時に `activate` ではなく `launch` を使い、Ghostty は初期コマンドを使うことで、単一のセッションだけを開きます。AppleScript 経路が失敗したときのフォールバックも残してあります（[#4156](https://github.com/farion1231/cc-switch/pull/4156)）。
+
+### Claude Desktop モデルマッピングのプレースホルダー
+
+Claude Desktop モデルマッピングフォームは、以前「メニュー表示名」と「リクエストモデル」の 2 列で一貫しないブランド例（DeepSeek vs Kimi）を使い、ある表示名が無関係なモデルへマッピングされるかのように見せていました。現在は両方のプレースホルダーが各行のロールから導かれ、ブランドの一貫性を保ち、軽量な Haiku 階層は flash の例を使います。
+
+### ポップオーバーが全画面パネルに隠れる
+
+プロバイダープリセット検索のようなポップオーバーやツールチップが、全画面パネルの後ろに描画されてクリックが効かないように見える問題がなくなりました。これらの z-index を全画面オーバーレイの上に引き上げつつ、モーダルダイアログよりは低く保ちました。
+
+### ToggleRow アイコンの縮み
+
+トグル行のアイコンは、長い説明と並んでも縮んだり歪んだりしなくなり、複数行のテキストの隣でアイコンが固定サイズを保ちます。
+
+---
+
+## ドキュメント
+
+### Release Notes の貢献者謝辞の復元
+
+v3.16.1 と v3.16.2 の release notes の貢献者謝辞を 3 言語で復元しました。
+
+---
+
+## アップグレード時の注意
+
+### 価格ライブラリ schema v11 の自動移行
+
+本リリースは `proxy_request_logs` に `pricing_model` 列を新設し、`request_model` + `pricing_model` で rollup を再構築しました。起動時に自動移行し、手動操作は不要です。過去の行のコストは書き込み時に確定済みで再計算されません（`app_type="claude"` の行はネイティブと変換の 2 種類のソースが混在しています）。本物だが当時課金されなかったテイクオーバー行のみがゼロコストのまま残り、価格が補われた後にバックフィルされます。
+
+### モデルマッピングに 4 つ目の階層（Fable 5）を追加
+
+Claude Code と Claude Desktop のモデルマッピングは 4 階層（Sonnet / Opus / Fable / Haiku）になりました。従来の 3 階層プロバイダーは、再度開いて保存すると `claude-fable-5` 階層が補われます。この階層を空のままにすると Sonnet を継承します。注意: サードパーティの endpoint でいずれかの階層を空のままにすると、その階層のモデル名がそのまま透過されて 404 になる可能性があるため、必要に応じて記入してください。
+
+### 「Kimi For Coding」プリセットはプロキシテイクオーバー + ホワイトリスト UA が必要
+
+復活した Codex「Kimi For Coding」プリセットは、既定の `codex-cli` User-Agent をそのまま使うと依然 403 になります。利用するには、プロキシテイクオーバーを有効にし、プロバイダーの高度なオプションでカスタム User-Agent をホワイトリストの UA（`claude-cli/*` など）に設定してください。
+
+### プロバイダーヘルスチェックのセマンティクス変更
+
+ヘルスチェックは「本物のモデルリクエストを送る」から「HTTP 到達性プローブ」へ変わりました。到達可能 ≠ 利用可能であることにご注意ください: 403 を返す host は到達可能でも、本物のトラフィックには壊れている可能性があります。フェイルオーバーの判定は引き続き本物のプロキシトラフィックのみで駆動され、ヘルスチェックの影響を受けません。
+
+---
+
+## リスク通知
+
+本リリースは、リバースプロキシ系機能に関する以前のリスク通知を引き続き適用します。
+
+**Codex OAuth リバースプロキシ**: ChatGPT サブスクリプションの Codex OAuth をリバースプロキシ経由で使用すると、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 release notes](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
+
+**Codex サードパーティプロバイダー Chat ルーティング**: CC Switch ローカルプロキシで Codex リクエストを変換し、サードパーティプロバイダーへ転送する場合、課金・コンプライアンス・データ保持に関する制約はプロバイダーごとに異なります。利用前に対象プロバイダーの利用規約を確認してください。
+
+**Claude Desktop サードパーティプロバイダープロキシ切り替え**: CC Switch 内蔵のプロキシゲートウェイで Claude Desktop のリクエストをサードパーティプロバイダーへ転送する場合も、対象プロバイダーの課金・コンプライアンス・データ保持に関する規約に従う必要があります。
+
+上記機能を有効化したユーザーは、関連するリスクを自ら負うものとします。CC Switch は、これらの機能の利用によって発生したアカウント制限、警告、サービス停止について責任を負いません。
+
+---
+
+## 謝辞
+
+v3.16.3 で機能と修正を届けてくださった以下のコントリビューターに感謝します：
+
+- [#3789](https://github.com/farion1231/cc-switch/pull/3789): テイクオーバー時に Codex OAuth 認証情報を保持、@codeasier に感謝。
+- [#2774](https://github.com/farion1231/cc-switch/pull/2774): Completions を Anthropic へ変換する際に実際に返ったモデルを記録せず input token の計算が誤っていた問題を修正、@LaoYueHanNi に感謝。
+- [#4069](https://github.com/farion1231/cc-switch/pull/4069): アプリ内更新後の再起動デッドロックを修正、@thisTom に感謝。
+- [#4156](https://github.com/farion1231/cc-switch/pull/4156): macOS の重複プロバイダーターミナルウィンドウを修正、@thisTom に感謝。
+- [#3267](https://github.com/farion1231/cc-switch/pull/3267): Hermes 設定の重複 YAML キーを修正、@que3sui に感謝。
+- [#1479](https://github.com/farion1231/cc-switch/pull/1479): 使用量スクリプトのプロバイダー認証情報の解決を修正、@pa001024 に感謝。
+- [#3975](https://github.com/farion1231/cc-switch/pull/3975): プリセットプロバイダーの検索とソートを追加、@Nastem に感謝。
+- [#4183](https://github.com/farion1231/cc-switch/pull/4183): プリセットプロバイダーボタンの外観と検索ボックスの位置を調整、@WangJiati に感謝。
+- [#4077](https://github.com/farion1231/cc-switch/pull/4077): claude-mythos-5 モデルの価格を追加、@osscv に感謝。
+
+v3.16.2 リリース後に使用量の課金、ローカルプロキシの堅牢性、Codex のアップグレード、プラットフォーム互換性の問題を報告してくださったすべてのユーザーにも感謝します。今回の多くの修正は、実際の利用シーンから得られた再現情報に基づいています。
+
+---
+
+## ダウンロードとインストール
+
+[Releases](https://github.com/farion1231/cc-switch/releases/latest) から、お使いのシステムに対応するビルドをダウンロードしてください。
+
+### システム要件
+
+| システム | 最低バージョン           | アーキテクチャ                      |
+| -------- | ------------------------ | ----------------------------------- |
+| Windows  | Windows 10 以降          | x64                                 |
+| macOS    | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
+| Linux    | 下表を参照               | x64 / ARM64                         |
+
+### Windows
+
+| ファイル                                 | 説明                                         |
+| ---------------------------------------- | -------------------------------------------- |
+| `CC-Switch-v3.16.3-Windows.msi`          | **推奨** - 自動更新対応の MSI インストーラー |
+| `CC-Switch-v3.16.3-Windows-Portable.zip` | ポータブル版、展開してそのまま実行できます   |
+
+### macOS
+
+| ファイル                         | 説明                                                   |
+| -------------------------------- | ------------------------------------------------------ |
+| `CC-Switch-v3.16.3-macOS.dmg`    | **推奨** - DMG インストーラー、Applications へドラッグ |
+| `CC-Switch-v3.16.3-macOS.zip`    | 展開して Applications へドラッグ、Universal Binary      |
+| `CC-Switch-v3.16.3-macOS.tar.gz` | Homebrew インストールと自動更新用                      |
+
+Homebrew インストール：
+
+```bash
+brew install --cask cc-switch
+```
+
+更新：
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+Linux アセットは **x86_64** と **ARM64**（`aarch64`）の両方を提供します。ファイル名にアーキテクチャ識別子が含まれているため、マシンの `uname -m` 出力に合わせて選択してください：
+
+- `CC-Switch-v3.16.3-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.16.3-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| ディストリビューション                  | 推奨形式    | インストール方法                                                          |
+| --------------------------------------- | ----------- | ------------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` または `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` または `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                   |
+| Arch Linux / Manjaro                    | `.AppImage` | 実行権限を付与して直接起動、または AUR を使用                             |
+| その他 / 不明                           | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`                 |
@@ -0,0 +1,340 @@
+# CC Switch v3.16.3
+
+> 🎉 **CC Switch 突破 100,000 Star！**
+> 感谢每一位用户、贡献者与 Star —— 是你们让它走到这里。🙏
+
+> 💎 **本版由 Claude Fable 5 模型协助开发**——它帮忙梳理清楚了多处关键且容易出错的逻辑：路由接管时按真实上游模型计费的归因链、格式转换路径上缓存 token 的计量与去重、应用内更新的重启死锁，以及 Codex 统一会话历史的迁移 / 还原不变量。这也是本版在「关于」页新增 **Fable 5 Verified** 标识的由来。
+
+> 在 v3.16.2 拓宽数据可携带性与用量观测之后，这一版把重心放在「让用量计费真正准确」——按真实上游模型计费、修正格式转换路径上的缓存双算、把 Claude Code Workflow 子 agent 的用量纳入统计（schema v11），并对用量看板做了一轮改版（全局供应商 / 模型筛选、品牌图标工具栏、更稳的额度查询）；同时加固了一批本地代理与平台问题，新增自定义 User-Agent 覆盖、Codex 统一会话历史开关与 Claude Fable 5 档位。
+
+**[English →](v3.16.3-en.md) | [日本語版 →](v3.16.3-ja.md)**
+
+---
+
+## 使用攻略
+
+本版新增了 **Codex 统一会话历史** 开关——它涉及会话的迁移 / 还原，操作不当时容易让人误以为"会话丢了"，强烈建议先读这篇攻略；用量统计的口径和看板这一版也做了较多调整，一并附上：
+
+- **[Codex 统一会话历史：功能介绍与使用攻略](../guides/codex-unified-session-history-guide-zh.md)**：讲清"统一 / 迁移 / 还原"到底改了什么、为什么数据不会真正丢失，以及看不到会话时如何自查与精确还原。**用过这个开关、或担心会话丢失，请务必先读。**
+- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：了解用量看板的数据来源（代理日志、会话同步）与统计口径，本版新增了全局的供应商 / 模型筛选，并把路由接管的真实计价模型展示了出来。
+- **[设置](../user-manual/zh/1-getting-started/1.5-settings.md)**：自定义 User-Agent 覆盖、Codex 统一会话历史等开关都在供应商表单的高级选项与设置页里。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一官方渠道声明（请务必阅读）
+>
+> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。请仅通过下列官方渠道获取本软件：
+>
+> | 类别     | 唯一官方                                                                       |
+> | -------- | ------------------------------------------------------------------------------ |
+> | 官网     | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | 源码     | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | 下载     | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者     | **[@farion1231](https://github.com/farion1231)**                               |
+> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。
+
+---
+
+## 概览
+
+CC Switch v3.16.3 是 v3.16.2 之后的一版维护更新。在上一版集中拓宽数据可携带性与用量观测之后，这一版把重心放在「让用量计费真正准确」这件事上——按真实上游模型计费而非上游回显、修正格式转换（Chat / Responses / Gemini 转 Anthropic）路径上的缓存 token 双算、把 Claude Code Workflow 子 agent 的用量纳入本地统计，并以 schema v11 持久化每条记录实际使用的定价依据；用量看板也随之做了一轮改版，新增全局的供应商 / 模型筛选、品牌图标工具栏，以及更稳的额度查询（失败重试 + 保留上次成功结果）。
+
+此外，本版还加固了一批本地代理的稳健性问题（错标 Content-Type 的 SSE 响应聚合、Codex `/responses` 文本模型图像整流、Codex OAuth 凭据与接管残留的恢复、Hermes 配置重复 YAML 键），重做了供应商配置体验（自定义 User-Agent 覆盖、Codex 表单统一进高级选项、预设搜索与排序、Claude Fable 5 档位），新增 Codex 统一会话历史开关，并修复了应用内更新卡死、Codex 升级损坏安装、macOS 重复终端窗口等问题。
+
+**发布日期**：2026-06-14
+
+**更新规模**：59 commits | 130 files changed | +10,223 / -4,232 lines
+
+---
+
+## 重点内容
+
+- **用量计费更准**：路由接管的流量现在按真实上游模型计费（而非上游回显的别名），格式转换路径不再把缓存 token 重复计入 input，Claude Code Workflow 子 agent 的用量也纳入了统计——以 schema v11 持久化定价依据。
+- **用量看板改版**：供应商 / 模型筛选从请求日志表提升为全局筛选，应用筛选改用品牌图标，额度查询加入失败重试与「保留上次成功结果」，单次网络抖动不再让卡片变红。
+- **自定义 User-Agent 覆盖**：供应商可设置自定义 UA，并在转发、连通性检测、模型列表三处一致生效，绕过按 UA 白名单放行的 Coding Plan 上游（借此恢复了 Codex「Kimi For Coding」预设）。
+- **Codex 统一会话历史**：新增可选开关，让官方 Codex 会话与第三方会话共享同一份 resume 历史桶，附带可选的存量迁移与按账本精确还原。
+- **代理与平台加固**：错标 SSE 响应聚合、Codex 图像整流、接管残留恢复、Hermes YAML 去重；应用内更新不再卡在「重启中」，Codex 升级不再把安装弄坏。
+
+---
+
+## 新功能
+
+### 自定义 User-Agent 覆盖
+
+供应商配置现在可以设置自定义 User-Agent，并由代理在请求转发、连通性检测和模型列表（`GET /v1/models`）三条路径上一致应用，因此按 UA 白名单放行的 Coding Plan 上游不会再出现「检测失败 / 模型列表 403、但代理本身却能正常工作」的不一致。Claude 和 Codex 表单都在高级选项里暴露该字段，配有精选的 UA 预设下拉（Claude Code / Kilo Code 等能通过 UA 白名单的家族）和实时、非阻塞的格式校验；切换到官方预设时会丢弃残留的自定义 UA，避免悄悄改动请求头（[#3671](https://github.com/farion1231/cc-switch/pull/3671)）。
+
+### Codex 统一会话历史
+
+新增一个可选开关（设置 → Codex 应用增强），让官方 Codex 会话与 CC Switch 的第三方会话共享同一份 resume 历史桶，resume 选择器不再把两者互相隐藏。开启后，live 的 `config.toml` 会把官方运行路由到一个镜像内建 OpenAI 供应商的共享 `custom` model_provider（`auth.json` 不动）。默认只对未来会话生效；开启弹窗提供一个勾选项，可把已有官方会话迁入共享桶（含逐代备份），关闭弹窗则提供按备份账本精确还原——只回退备份中记录为 `openai` 的会话，开启期间新建的会话永不被改动。
+
+### 用量看板全局供应商 / 模型筛选
+
+供应商和模型筛选从请求日志表内部提升到了顶栏，对 Hero 汇总、趋势图、请求日志和两个统计页签全局生效，可以把整个看板按某个来源和模型缩小范围。来源按展示名精确匹配（因此像「Claude (Session)」这样的会话占位行也可选），模型按有效计价模型匹配，模型下拉会随所选来源级联，且两个列表只列出当前时间范围内有数据的选项。
+
+### 模型定价种子刷新
+
+对 `seed_model_pricing` 做了一次全量核价：新增 9 个模型的定价（含 Claude Fable 5、Grok 4.3、Mistral Medium 3.5 / Small 4、Qwen 3.7 Max/Plus 等），并按各厂商官方 list 价订正了 28 处既有价格（GLM、Grok、MiMo、Doubao、Kimi、MiniMax、Mistral、Qwen），让用量成本估算更准确。每处改动都同时更新种子（影响全新安装）并向 `repair_current_model_pricing` 加一条旧→新守卫（修复存量数据库，且不覆盖用户手改过的行）。
+
+### Claude Fable 5 模型档位
+
+供应商表单现在在 Claude Code 和 Claude Desktop 两条代理路径上都暴露 `claude-fable-5` 作为第四个模型映射档位，回落链为 fable → opus → default，与官方降级一致，并为 Claude Desktop 1.12603.1+ 的校验器放行了 `fable-` 前缀。四语回落提示也做了澄清：在第三方端点上把某一档留空，会原样透传该档的字面模型名并 404（[#3980](https://github.com/farion1231/cc-switch/issues/3980)、[#4026](https://github.com/farion1231/cc-switch/issues/4026)、[#4049](https://github.com/farion1231/cc-switch/issues/4049)）。
+
+### Unity2.ai 合作伙伴供应商
+
+新增 Unity2.ai（一个 AI API 中转合作伙伴）作为预设，覆盖全部 7 个受管应用（Claude Code、Codex、Gemini、OpenCode、OpenClaw、Claude Desktop、Hermes），每个预设都带上推广注册链接，并在四种语言里补充了合作伙伴推广文案。Codex 使用裸 base URL（该网关在根路径暴露 `/responses`），OpenCode / OpenClaw / Hermes 使用 `/v1` chat-completions 端点并以 `gpt-5.5` 为预设模型。
+
+### Kimi K2.7 Code 模型
+
+新增 `kimi-k2.7-code` 模型（输入 $0.95 / 输出 $4.00 / 缓存读取 $0.19，每百万 token，256K 上下文），并把全部 6 个官方 Moonshot Kimi 预设（Claude Code、Codex、Claude Desktop、Hermes、OpenCode、OpenClaw）指向它，OpenCode / OpenClaw 预设更名为「Kimi K2.7 Code」。定价种子通过启动时的幂等插入路径生效，存量用户无需迁移即可获得新价。
+
+### 恢复 Codex「Kimi For Coding」预设
+
+重新加入 Codex「Kimi For Coding」预设（`openai_chat`、`kimi-for-coding`、256K 上下文），默认开启思考模式。此前它被移除是因为该编程端点会以 403 拒绝 Codex 默认的 `codex-cli` User-Agent；现在借助代理接管 + 自定义 User-Agent 覆盖（设为 `claude-cli/*` 等白名单 UA）即可正常使用。
+
+### 请求详情的计价模型审计
+
+请求详情面板现在会在「请求的模型」「计价模型」与响应模型不一致时把它们都显示出来，让路由接管产生的账单可以直接在用量界面里核对。
+
+### 预设供应商搜索与排序
+
+预设供应商选择器现在是一个可搜索、可排序的列表，配有内联搜索框（点放大镜图标切换，按 ESC 或点击外部收起）。按钮改为响应式网格、尺寸统一并显示默认图标，搜索只匹配供应商的展示名 / 原始名，因此 URL 片段和共享的分类标签不会再产生噪声匹配（[#3975](https://github.com/farion1231/cc-switch/pull/3975)、[#4183](https://github.com/farion1231/cc-switch/pull/4183)）。
+
+### Claude Mythos 5 定价
+
+在内置模型 / 定价表里登记 `claude-mythos-5` 模型（输入 $10 / 输出 $50，每百万 token；缓存读取 $1.00、缓存写入 $12.50），让用量统计能正确计价并展示（[#4077](https://github.com/farion1231/cc-switch/pull/4077)）。
+
+### Fable 5 Verified 标识
+
+设置「关于」页现在会在应用名与版本旁展示 Fable 5 Verified 标识，标明这是一个特别构建，版本徽标也居中到了应用名下方。
+
+---
+
+## 变更
+
+### Claude Desktop 用量折叠进 Claude
+
+看板不再展示独立的「Claude Desktop」分桶——它一直只能显示一个不完整的数字（Desktop 聊天用量根本不经过代理，而其 Code 页签的会话只是内嵌的 Claude Code 运行时写进共享的 `~/.claude/projects` 目录）。Desktop 的代理流量现在在展示上折叠进 `claude`，但记账层仍按它自己的 `app_type` 记录以便路由接管计费审计，真实值可在请求详情面板看到。
+
+### 轻量化供应商健康检查
+
+供应商健康检查不再发送真实的流式模型请求（很多第三方供应商会以 401/403/WAF 拦截，造成误报不可用），改为对供应商 `base_url` 做一次轻量的 HTTP 可达性探测：任何 HTTP 响应都视为可达，只有 DNS / 连接 / TLS / 超时才算失败。官方供应商（使用 OAuth、base_url 故意为空、没有可靠的可达性目标）会隐藏连通性按钮，原先「发送真实请求」的确认弹窗以及测试模型 / 提示词字段都被移除，降级延迟阈值设为 6s、超时 8s。该可达性检查永不重置熔断器——可达不等于可用（403 的 host 可达，但对真实流量是坏的），失败转移仍只由真实代理流量驱动。
+
+### Codex 高级选项区整合
+
+Codex 供应商表单现在把本地路由、模型映射、推理覆盖和自定义 User-Agent 折叠进一个可展开的高级选项区，与 Claude 表单一致（设置了 UA 或开启本地路由时自动展开）。自定义 User-Agent 现在对原生 Responses 供应商也可配置，此前它只有在开启 `openai_chat` 路由时才能触及。
+
+### 用量工具栏与布局刷新
+
+应用筛选改用品牌图标（经 ProviderIcon，「全部」用网格图标）渲染，取代在窄窗口下换行难看的文字页签；用量 Hero 也会显示所选应用的品牌图标，并把 Codex 的主题色从翠绿改为中性灰，贴合 OpenAI 的单色品牌。点击循环切换的刷新按钮改成了带本地化「关闭」标签的下拉选择，顶栏控件也压缩并对齐成统一的宽度分组，过长的日期范围标签做了截断处理。
+
+### 关于面板加载更快
+
+设置「关于」面板现在渐进式加载：应用版本徽标在解析完成的瞬间就显示，不再等待工具探测；每张工具卡片在自己的版本检测完成时立即更新（探测并发执行而非串行）；探测结果在应用会话期内缓存并带 10 分钟 TTL，因此再次打开「关于」页签会复用缓存值、并在后台对过期项重新校验，而不是每次都把 6 个工具全部重探一遍。
+
+### 火山方舟 Coding Plan 推广更新
+
+把火山方舟（Volcengine Ark）预设在全部 6 个应用里更新到新的 Coding Plan 邀请链接（替换旧的 Agent Plan / 活动链接），并在四种语言里刷新了合作伙伴推广文案（两个月 75% 折扣 + 邀请码 6J6FV5N2），把产品名从 Agent Plan 订正为 Coding Plan。
+
+### MiniMax 降为普通供应商
+
+移除 MiniMax 的金色合作伙伴星标和 API key 推广横幅（从所有预设里删掉 `isPartner` 标志），它继续作为常规 `cn_official` 供应商保留图标与主题。推广文案保持休眠状态，必要时一行即可重新启用合作关系。
+
+### 移除 LemonData、SudoCode 降级
+
+彻底移除 LemonData 供应商预设（连同其推广文案、图标和赞助商条目），并把 SudoCode 从合作伙伴降为常规 `third_party` 供应商（去掉 `isPartner` 标志和推广文案，保留图标）。
+
+### AtlasCloud Codex GLM 5.1 上下文窗口
+
+为 AtlasCloud Codex 预设里的 `zai-org/glm-5.1` 模型声明 200,000 token 的上下文窗口，与其他 GLM 5.1 预设条目对齐。
+
+---
+
+## 修复
+
+### 路由接管流量按真实上游模型计费
+
+当请求被路由到了不同的上游（env 模型映射、Claude Desktop 路由、Copilot 归一化、Codex chat 覆盖）时，代理过去会按上游回显的模型来归因和计价，把 kimi / glm 的 token 记成、并按 `claude-*` 计价，成本被高估约 5–25 倍。现在转发器会捕获真实的出站模型，按「上游回显 → 出站模型 → 客户端别名」的顺序归因，并在每行持久化实际使用的定价依据（schema v11），该依据会贯穿成本回填和 30 天 rollup 裁剪；Claude Desktop 流量现在也记在它自己的 `app_type` 下，使其定价覆盖能正确生效。
+
+### 格式转换路径的用量计量
+
+审计并修复了代理各条格式转换路径（Chat、Responses、Gemini 转 Anthropic）上的 token / 缓存计量。代理现在会记录实际返回的模型，注入 `stream_options.include_usage` 让 OpenAI 兼容上游在流式时吐出 usage，在 Claude←OpenAI 路径上把 `cache_read` 和 `cache_creation` 从 input 中排除以阻止缓存 token 双计费，扣减 Gemini 的缓存提示 token，仍记录完全命中缓存的请求，并跳过过去会虚增请求数的合成全零 usage（[#2774](https://github.com/farion1231/cc-switch/pull/2774)）。
+
+### 应用内更新不再卡死
+
+从应用内安装更新时不再卡在「重启中」界面——过去会出现新版已装好、却必须手动强制退出的情况。下载—安装—重启整条链路现在完全在后端执行（新增 `install_update_and_restart` 命令），按平台决定安装顺序，并在重新执行前先销毁单实例锁，而不再依赖旧 WebView 在应用包已被替换之后继续跑 JS；退出请求也做了分类，让重启请求落到 Tauri 默认流程，而不是在窗口状态插件的互斥锁上死锁（[#4069](https://github.com/farion1231/cc-switch/pull/4069)、[#4074](https://github.com/farion1231/cc-switch/pull/4074)）。
+
+### Codex 升级不再损坏安装
+
+从设置「关于」页升级 Codex 不再让它抛出「Missing optional dependency @openai/codex-…」错误。升级链此前会先跑 `codex update`，而它在 npm 安装下其实是一次裸的重装、即便对应平台的二进制没装上也会报告成功；现在 Codex 已从「优先 self-update」路径里移除，并由一个 runnable 检测触发「卸载 + 重装」自愈（仅限 npm 管理的安装），这是唯一能真正补回缺失平台二进制的修复。
+
+### 接管时保留 Codex OAuth 凭据
+
+为 Codex 供应商开启代理接管时不再剥掉 `ANTHROPIC_AUTH_TOKEN` 占位符——此前这会在热切换、全新安装、以及被旧版本已剥过的 live 配置上破坏 Claude Code 的登录。现在对受管（非 Copilot）的 Codex 供应商无条件注入该占位符，包括只有 URL 的供应商；GitHub Copilot 的行为（仅 API_KEY）不变（[#3789](https://github.com/farion1231/cc-switch/pull/3789)、[#3784](https://github.com/farion1231/cc-switch/issues/3784)）。
+
+### 跨配置目录切换的接管残留恢复
+
+在代理接管激活时更改配置目录后重启应用，不再把 Claude / Codex / Gemini 留在指向已失效的本地代理上。现在旧实例会在重启前先还原被接管的 live 文件，首次运行的导入会拒绝把接管占位符当作供应商持久化，SSOT 还原也会在写回前校验当前供应商的配置里不含占位符（[#4076](https://github.com/farion1231/cc-switch/pull/4076)）。
+
+### 格式转换兜底里错标的 SSE 响应聚合
+
+经 Claude / Codex 格式转换的请求，当 MaaS 网关把一个 `stream:false` 的请求强制流式、并以非 SSE 的 Content-Type 返回 SSE 响应体时，不再以一句晦涩的 422「Failed to parse upstream response」失败。代理现在会在解析失败时嗅探 SSE、把分片聚合成单个 JSON 再跑既有转换器，让客户端仍能拿到有效的非流式响应；剩余的解析失败会附带 content-type、编码和响应体片段等诊断信息，deflate 解码也改为先尝试 zlib 再尝试裸流（[#2234](https://github.com/farion1231/cc-switch/pull/2234)）。
+
+### Hermes 配置重复 YAML 键
+
+Hermes 配置写入不再累积重复的顶层键（如 `mcp_servers`），那会导致「Failed to parse Hermes config as YAML: duplicate entry with key」错误。区段替换现在会从剩余文本里清除所有过期副本，而不是退化成追加；去重保护层同时处理 LF 和 CRLF 行尾；修复时保留最后（最新）的那份副本，与 Hermes 自身基于 PyYAML 的「后者胜」语义一致（[#3267](https://github.com/farion1231/cc-switch/pull/3267)、[#3633](https://github.com/farion1231/cc-switch/issues/3633)、[#2973](https://github.com/farion1231/cc-switch/issues/2973)、[#2529](https://github.com/farion1231/cc-switch/issues/2529)、[#3310](https://github.com/farion1231/cc-switch/issues/3310)、[#3762](https://github.com/farion1231/cc-switch/issues/3762)）。
+
+### 用量查询韧性与错误清晰度
+
+用量卡片不再因为单次瞬时抖动就变红：查询现在会重试一次，并在网络 / 超时 / 5xx 这类瞬时失败下继续展示上次成功的结果最多 10 分钟；而确定性失败（鉴权、空 key、未知供应商、4xx）会立即暴露并清空快照，避免凭据变更后陈旧额度又冒出来。原生余额 / Coding Plan / 订阅查询的超时从 10s 提高到 15s 以适配跨境慢端点，Coding Plan 也会返回明确的「API key is empty」/「Unknown coding plan provider」错误，而不是一句空白的失败。
+
+### 用量脚本供应商凭据解析
+
+自定义 JS 脚本的用量查询此前只靠猜测 env 字段来解析 `{{apiKey}}` / `{{baseUrl}}`，因此凭据存放在别处的应用（如 Codex 的 `auth.OPENAI_API_KEY` 加 `config.toml` 里的 base_url）总是拿到空值、即便供应商已完整配置也会失败。脚本查询及其测试 / 预览现在复用与原生余额路径相同的按应用凭据解析器，脚本里显式填写的非空值仍然优先（[#1479](https://github.com/farion1231/cc-switch/pull/1479)）。
+
+### Claude Code Workflow 子 agent 用量统计
+
+本地（无代理）的会话日志用量统计此前漏掉了 Claude Code Workflow 子 agent 的流量，整体用量被低估约 4.1%（集中在 workflow / subagent 的会话记录里）。扫描器现在会深入更深一层的 `subagents/workflows/wf_*/` 记录目录，解析器也不再丢弃那些缺少 `stop_reason`、但已经产生 input / 缓存 token 成本的 assistant 消息；去重逻辑不变，因此不会重复计数。
+
+### Codex `/responses` 文本模型图像整流
+
+携带图片、且被路由到只支持文本的 OpenAI-chat 模型（如 DeepSeek `deepseek-v4-flash`）的 Codex `/responses` 请求，不再以 HTTP 400「unknown variant `image_url`」失败。媒体整流器现在也覆盖 Codex 适配器，会扫描 responses 的 `input` 里的 `input_image` 块，从而既能为已知的纯文本模型主动剥掉图片，也能在上游报「不支持图片」时把图片替换后重试。
+
+### 智谱 Coding Plan 配额窗口误标
+
+智谱 Coding Plan 视图不再在每个周周期的最后几个小时把 5 小时窗口和周窗口标反。两个窗口现在按显式的 `unit` 字段分类（3 = 5 小时、6 = 周），而不再靠按重置时间升序排序——后者恰好在用户最常查周额度的时候把两者标反；当字段缺失时仍回退到旧的重置时间启发式（[#3036](https://github.com/farion1231/cc-switch/pull/3036)）。
+
+### macOS 重复供应商终端窗口
+
+在 macOS 上启动供应商终端时不再在命令会话旁多开一个空窗口；Terminal.app 在冷启动时改用 `launch`（而非 `activate`），Ghostty 使用初始命令，从而只打开单个会话，并在 AppleScript 路径失败时保留回退方案（[#4156](https://github.com/farion1231/cc-switch/pull/4156)）。
+
+### Claude Desktop 模型映射占位符
+
+Claude Desktop 模型映射表单此前在「菜单展示名」和「请求模型」两列用了不一致的示例品牌（DeepSeek vs Kimi），暗示一个展示名会映射到不相关的模型。现在两个占位符都由每行的角色派生，从而保持品牌一致，轻量的 Haiku 档使用 flash 示例。
+
+### 弹层被全屏面板遮挡
+
+像供应商预设搜索这样的弹层和提示气泡不再渲染到全屏面板后面、看起来点了没反应；它们的 z-index 被提到全屏遮罩之上，同时仍低于模态对话框。
+
+### ToggleRow 图标被挤压
+
+开关行的图标在配上长描述时不再被压缩或变形，让图标在多行文字旁保持固定大小。
+
+---
+
+## 文档
+
+### Release Notes 贡献者致谢恢复
+
+恢复了 v3.16.1 与 v3.16.2 release notes 在三种语言里的贡献者致谢。
+
+---
+
+## 升级提醒
+
+### 定价库 schema v11 自动迁移
+
+本版给 `proxy_request_logs` 新增了 `pricing_model` 列、并按 `request_model` + `pricing_model` 重建了 rollup，启动时自动迁移、无需手动操作。历史行的成本在写入时已冻结、不会重算（`app_type="claude"` 的行混合了原生与转换两类来源）；只有真实但当时未计价的接管行会保持零成本、待定价补齐后再回填。
+
+### 模型映射新增第四档（Fable 5）
+
+Claude Code 与 Claude Desktop 的模型映射现在是四档（Sonnet / Opus / Fable / Haiku）。老的三档供应商在重新打开并保存后会补上 `claude-fable-5` 档；该档留空表示继承 Sonnet。注意：在第三方端点上把任意一档留空，会原样透传该档的字面模型名并可能 404，请按需填写。
+
+### 「Kimi For Coding」预设需要代理接管 + 白名单 UA
+
+恢复的 Codex「Kimi For Coding」预设直接用默认的 `codex-cli` User-Agent 仍会被 403。要使用它，请开启代理接管，并在供应商高级选项里把自定义 User-Agent 设为白名单 UA（如 `claude-cli/*`）。
+
+### 供应商健康检查语义变化
+
+健康检查从「发送真实模型请求」改为「HTTP 可达性探测」。请注意可达 ≠ 可用：一个返回 403 的 host 是可达的，但对真实流量可能是坏的。失败转移的判定仍只由真实代理流量驱动，不受健康检查影响。
+
+---
+
+## 风险提示
+
+本版本继续沿用此前版本对反向代理类功能的风险提示。
+
+**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
+
+**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
+
+**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，同样需要遵守目标供应商的计费、合规与数据留存约束。
+
+用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
+
+---
+
+## 致谢
+
+感谢以下贡献者在 v3.16.3 中提交的功能与修复：
+
+- [#3789](https://github.com/farion1231/cc-switch/pull/3789)：接管时保留 Codex OAuth 凭据，感谢 @codeasier。
+- [#2774](https://github.com/farion1231/cc-switch/pull/2774)：修复 Completions 转 Anthropic 时不记录实际返回模型、input token 计算错误，感谢 @LaoYueHanNi。
+- [#4069](https://github.com/farion1231/cc-switch/pull/4069)：修复应用内更新后重启死锁，感谢 @thisTom。
+- [#4156](https://github.com/farion1231/cc-switch/pull/4156)：修复 macOS 重复供应商终端窗口，感谢 @thisTom。
+- [#3267](https://github.com/farion1231/cc-switch/pull/3267)：修复 Hermes 配置重复 YAML 键，感谢 @que3sui。
+- [#1479](https://github.com/farion1231/cc-switch/pull/1479)：修复用量脚本供应商凭据解析，感谢 @pa001024。
+- [#3975](https://github.com/farion1231/cc-switch/pull/3975)：新增预设供应商搜索与排序，感谢 @Nastem。
+- [#4183](https://github.com/farion1231/cc-switch/pull/4183)：调整预设供应商按钮外观与搜索框位置，感谢 @WangJiati。
+- [#4077](https://github.com/farion1231/cc-switch/pull/4077)：新增 claude-mythos-5 模型定价，感谢 @osscv。
+
+也感谢所有在 v3.16.2 发布后反馈用量计费、本地代理稳健性、Codex 升级与平台兼容性问题的用户，很多补丁都来自这些真实使用场景里的复现线索。
+
+---
+
+## 下载与安装
+
+访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
+
+### 系统要求
+
+| 系统    | 最低版本                   | 架构                                |
+| ------- | -------------------------- | ----------------------------------- |
+| Windows | Windows 10 及以上          | x64                                 |
+| macOS   | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | 见下表                     | x64 / ARM64                         |
+
+### Windows
+
+| 文件                                     | 说明                                |
+| ---------------------------------------- | ----------------------------------- |
+| `CC-Switch-v3.16.3-Windows.msi`          | **推荐** - MSI 安装包，支持自动更新 |
+| `CC-Switch-v3.16.3-Windows-Portable.zip` | 便携版，解压即用，不写入注册表      |
+
+### macOS
+
+| 文件                             | 说明                                          |
+| -------------------------------- | --------------------------------------------- |
+| `CC-Switch-v3.16.3-macOS.dmg`    | **推荐** - DMG 安装包，拖入 Applications 即可 |
+| `CC-Switch-v3.16.3-macOS.zip`    | 解压后拖入 Applications，Universal Binary     |
+| `CC-Switch-v3.16.3-macOS.tar.gz` | 用于 Homebrew 安装和自动更新                  |
+
+Homebrew 安装：
+
+```bash
+brew install --cask cc-switch
+```
+
+更新：
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本：
+
+- `CC-Switch-v3.16.3-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.16.3-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| 发行版                                  | 推荐格式    | 安装方式                                                               |
+| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                    | `.AppImage` | 添加执行权限后直接运行，或使用 AUR                                     |
+| 其他发行版 / 不确定                     | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |
@@ -0,0 +1,354 @@
+# CC Switch v3.16.4
+
+> 🎉 **CC Switch is now in the global top 100 on GitHub by stars!**
+> Thank you to every user, contributor, and Star — you brought it here. 🙏
+
+> After v3.16.3 made usage billing accurate, this release shifts the focus to polishing the Codex proxy chain and enriching the usage / pricing tooling — migrating Chinese providers to native Responses, decoupling the upstream-format selector from model mapping, decompressing zstd request / error bodies, and a batch of tool-call and OAuth-through-proxy fixes — while also adding local proxy request overrides, an in-app recovery screen when the database version is too new, native Windows ARM64 builds, and a wave of preset and branding updates (SubRouter, OpenCode Go, the CTok→ETok rename, the Kimi brand refresh, and a prime-partner badge).
+
+**[中文版 →](v3.16.4-zh.md) | [日本語版 →](v3.16.4-ja.md)**
+
+---
+
+## Usage Guides
+
+This release is mostly polish and expansion, with the new capabilities landing mainly in the usage dashboard and the provider form's advanced options. The following docs are worth reading alongside it:
+
+- **[Can't see custom models in the Codex desktop app?](../guides/codex-desktop-custom-model-visibility-en.md)**: many users report that their configured third-party / custom models do not show up in the Codex desktop app's model picker. This is the Codex desktop app's **own upstream gating behavior** (it gates the model picker by official login state), not a CC Switch local-config problem, and **this release (v3.16.4) does not change it**. The doc explains the cause and the available mitigation (keep official login + route takeover).
+- **[Usage Statistics](../user-manual/en/4-proxy/4.4-usage.md)**: understand the Usage Dashboard's data sources and how the statistics are counted. This release adds bulk import of model pricing from models.dev, AK/SK usage queries for Volcengine Ark Coding / Agent Plan, and a live end time for custom date ranges.
+- **[Settings](../user-manual/en/1-getting-started/1.5-settings.md)**: local proxy request overrides (custom headers / request body), the Codex upstream-format selector, the local routing toggle, and more live in the provider form's advanced options.
+
+---
+
+> [!WARNING]
+>
+> ## Only Official Channels (Please Read)
+>
+> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Please only obtain the software through the official channels listed below:
+>
+> | Channel            | Only Official                                                                  |
+> | ------------------ | ------------------------------------------------------------------------------ |
+> | Website            | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | Source             | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | Downloads          | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | Author             | **[@farion1231](https://github.com/farion1231)**                               |
+> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues.
+
+---
+
+## Overview
+
+CC Switch v3.16.4 is a maintenance update following v3.16.3. This release tightens the Codex proxy chain — switching several Chinese providers that have native OpenAI Responses endpoints to the native format (dropping the Responses→Chat route-takeover conversion), promoting "upstream format" out of the "local routing" toggle into its own control, adding decompression for zstd request and error response bodies, and fixing a string of tool-call and "OAuth module bypassing the global proxy" issues.
+
+Alongside that, this release enriches the usage and pricing tooling (import pricing from models.dev, AK/SK usage queries for Volcengine Ark Coding / Agent Plan, a live end time for custom date ranges, GLM-5.2 and Doubao Seed 2.1 pricing), adds a batch of proxy and resilience capabilities (custom header / request-body overrides, an in-app recovery screen when the database version is too new, native Windows ARM64 builds), and brings a wave of preset and branding updates (SubRouter and OpenCode Go subscriptions, the CTok→ETok rename, the Kimi brand refresh and prime-partner badge, and a Kimi K2.7 Code sponsor banner).
+
+**Release date**: 2026-06-27
+
+**Stats**: 53 commits | 126 files changed | +8,149 / -1,016 lines
+
+---
+
+## Highlights
+
+- **Native Responses for Chinese Codex providers**: Qwen / DashScope, Xiaomi MiMo, Volcengine Doubao, Meituan LongCat, and MiniMax (domestic / international) now connect directly to their native Responses endpoints instead of going through the Responses→Chat format-conversion takeover, for a shorter and more stable chain.
+- **Local proxy request overrides**: providers can configure custom header and request-body overrides, applied by the local proxy when forwarding, with interception validation that blocks protected security headers.
+- **In-app recovery screen for a too-new database**: when the SQLite version is newer than the current app supports, you no longer get stuck in a native dialog where "retry just fails again"; instead you are guided to a recovery screen that can upgrade the app in one click.
+- **Richer usage / pricing tooling**: bulk import of model pricing from models.dev, AK/SK usage queries for Volcengine Ark Coding / Agent Plan, a live end time for custom date ranges, and pricing for GLM-5.2 and Doubao Seed 2.1.
+- **New presets and branding updates**: added SubRouter and OpenCode Go subscription presets, renamed CTok to ETok, refreshed the Kimi brand mark, and added a prime-partner heart badge to the official Kimi presets.
+- **Native Windows ARM64 builds**: release artifacts now include native ARM64 builds, so ARM Windows devices no longer depend on x64 emulation.
+
+---
+
+## Added
+
+### In-App Recovery Screen for a Too-New Database
+
+When the SQLite `user_version` is newer than the current app's supported `SCHEMA_VERSION` (for example after downgrading to an older release, or because a third-party client wrote the file), startup used to die in a native "retry / quit" dialog — where "retry" just fails again. The app now routes to a dedicated recovery screen: when an update is available it offers a one-click "Upgrade App" button (download + install + restart, with a progress bar), and when none is available it explains that even the latest version cannot read this database. The "too new" check runs before any write to the database, so the app never runs DDL against a database it cannot understand; a native close in recovery mode exits cleanly (the tray has not been created yet). ([#4575](https://github.com/farion1231/cc-switch/pull/4575))
+
+### Local Proxy Request Overrides (Custom Headers and Request Body)
+
+Provider configs can now define custom header and request-body overrides that the local proxy applies when forwarding, exposed via new fields in the Claude and Codex provider forms. Input is validated against a protected-header list that blocks overriding security-sensitive headers. ([#4589](https://github.com/farion1231/cc-switch/pull/4589))
+
+### Volcengine Ark Coding / Agent Plan Usage Queries
+
+The usage panel can now query Volcengine Ark's Coding Plan and Agent Plan quotas. Because the Ark control-plane OpenAPI (`open.volcengineapi.com`) requires an account-level AccessKey signature rather than an inference API key, the usage script gains a dedicated AK/SK input area with a clickable link straight to the Volcengine IAM key-management console (`https://console.volcengine.com/iam/keymanage`); the proxy implements Volcengine Signature V4 (an AWS SigV4 variant: a fixed canonical-header order, the `HMAC-SHA256` algorithm, and the `ark` service scope). It first probes `GetAFPUsage` (the Agent Plan's 5-hour / weekly / monthly quotas) to auto-detect the plan and falls back to `GetCodingPlanUsage`, parsing the window label from the `Level` field (with a guard for `ResetTimestamp <= 0`), and adds the `monthly` tier label across the usage footer, the tray menu, and all four locales.
+
+### Import Model Pricing from models.dev
+
+The "Add Pricing" panel gains an "Import from models.dev" button: it fetches `https://models.dev/api.json`, supports full-text search across the entire catalog, and imports the selected entries through the same `update_model_pricing` path as manual entry. Imported model ids are normalized by the backend's `clean_model_id_for_pricing` rules (strip the provider prefix, lowercase, truncate the `:` suffix, map `@` to `-`, drop the `[1m]` marker) so the persisted rows actually match cost-attribution queries. A companion fix changes "backfill zero-cost over a range" to match in Rust by raw model alias (route prefixes, `:free` variants, date suffixes) rather than by exact SQL string match, so newly priced alias rows are priced immediately instead of waiting for the next startup backfill (fixes [#4017](https://github.com/farion1231/cc-switch/issues/4017)). ([#4079](https://github.com/farion1231/cc-switch/pull/4079))
+
+### Native Windows ARM64 Builds
+
+Release artifacts now include native Windows ARM64 builds, so ARM Windows devices can grab the matching native build instead of relying on x64 emulation. The release matrix now also runs each platform independently (fail-fast disabled), so a job that fails for a missing secret (e.g. macOS signing in a fork) no longer cancels its still-running siblings. ([#3950](https://github.com/farion1231/cc-switch/pull/3950))
+
+### Live End Time for Custom Date Ranges
+
+The custom date-range picker gains a "follow the current time as the end time" checkbox; when enabled, the end time becomes read-only and tracks now, so usage data always reflects the live consumption from the chosen start to the present moment. This is especially useful within the Coding Plan's 5-hour quota window. `liveEndTime` is now part of the React Query cache key, so a live range and a fixed range with the same endpoint no longer share the same stale cache entry. ([#4438](https://github.com/farion1231/cc-switch/pull/4438))
+
+### Source File Name in the Session Detail Header
+
+The session detail header now shows the session log's file name next to the project directory (hover for the full path, click to copy), so you can locate and open the underlying JSONL file directly from the UI. For long file names without spaces, such as the ~70-character Codex rollout names, it truncates at `max-w-[200px]` to avoid overflowing into the action buttons in a narrow window. ([#4113](https://github.com/farion1231/cc-switch/pull/4113))
+
+### Unmanaged-Skill Hint on the Import Button
+
+The Skills import button in the top bar now shows a green dot and a tooltip when there are unmanaged Skills on disk available to import, so you can tell at a glance that a Skill on disk hasn't been brought under management yet. The scan runs once on mount and is shared across navigations (30s `staleTime` + `keepPreviousData`) to avoid redundant disk IO.
+
+### OpenCode Go Subscription Presets
+
+Added the OpenCode Go (`opencode.ai/zen/go`) preset, covering Claude, Codex, and OpenCode, using a paste-ready bare API key (no OAuth). The Codex preset uses `openai_chat` conversion with a GLM / Kimi / DeepSeek / MiMo model catalog (and without a static `codexChatReasoning`, inferring each model's capabilities), while OpenCode points at `/zen/go/v1` via `@ai-sdk/openai-compatible`. All four OpenCode Go presets — Claude, Claude Desktop, Codex, and OpenCode — carry the referral link and in-app promotion copy; the promotion banner now shows on `partnerPromotionKey` alone (no longer bound to `isPartner`), so a preset can surface a referral promotion without earning the gold paid-partner star (which incidentally brings the existing MiniMax promotion back into view).
+
+### Prime-Partner Preset Badge and Sorting
+
+The first-party Moonshot Kimi presets (Kimi / Kimi For Coding / Kimi K2.7 Code) are now marked as prime partners: instead of the gold star they render a solid gold heart (no badge border) and, in the default (Original) sort, float to just after the official-category presets and before the rest. The grouping is done with a three-way partition that keeps each group's internal order, and an official preset that is also marked prime-partner stays only in the official group.
+
+### GLM-5.2 and Doubao Seed 2.1 Pricing
+
+The seed model pricing now includes GLM-5.2 ([#4385](https://github.com/farion1231/cc-switch/pull/4385)) and Doubao Seed 2.1 Pro / Turbo, so these models' usage is priced correctly instead of being recorded at zero cost. Doubao prices use Volcengine's official list pricing (converted at roughly 7.14); `cache_creation` stays at 0 because Doubao bills cache storage by time rather than by token writes, and the existing 2.0 rows are retained for historical accounting.
+
+### Kimi For Coding Auto-Compact Window
+
+The Kimi For Coding preset now defaults `CLAUDE_CODE_AUTO_COMPACT_WINDOW` to 262144, matching Kimi's official documentation, and exposes it via `templateValues` so users can customize the value for future models or performance tuning. ([#4401](https://github.com/farion1231/cc-switch/pull/4401))
+
+### SubRouter Partner Provider
+
+Added SubRouter (`subrouter.ai`, an AI relay aggregator that lets one key reach many models across many providers) as a preset covering all seven managed apps — an Anthropic-format endpoint for Claude Code / Claude Desktop / OpenClaw / Hermes, an OpenAI-compatible `/v1` endpoint (`gpt-5.5`) for Codex and OpenCode, and a Gemini-compatible `/v1beta` endpoint (`gemini-3.5-flash`) for Gemini CLI — with its own brand icon, a gold partner star, four-language promotion copy, and a referral signup link prefilled to the API-key registration page (`?aff=l3ri`). ([#4522](https://github.com/farion1231/cc-switch/pull/4522))
+
+---
+
+## Changed
+
+### Chinese Codex Providers Use the Native Responses API
+
+Several Chinese providers (Qwen / DashScope, Xiaomi MiMo, Volcengine Doubao, Meituan LongCat, MiniMax domestic / international) now expose native OpenAI Responses endpoints, so their Codex presets switch to `apiFormat: "openai_responses"`, connecting directly to the upstream instead of going through the Responses→Chat route-takeover conversion. Dropping the no-longer-needed `codexChatReasoning` and `modelCatalog` also keeps the "local routing mapping" toggle unchecked by default. SiliconFlow-hosted MiniMax stays on `openai_chat` because that is a third-party endpoint, not MiniMax's own base_url. The remaining chat-based providers also refreshed stale model ids (GLM 5.1→5.2, StepFun 3.5-flash-2603→3.7-flash, Ling 2.5-1T→2.6-1T).
+
+### Upstream-Format Selector Decoupled from the Model-Mapping Toggle
+
+The Codex provider form previously bound Chat format conversion and route takeover (model mapping) to the same toggle, which meant a provider offering a native Responses API couldn't use model mapping without forcing Chat Completions conversion. "Upstream format" (Chat Completions / Responses) is now a separate, always-visible selector, while the local routing toggle only controls the advanced subsection (the model-mapping catalog, plus reasoning capabilities when the format is Chat). Its initial state is derived from whether a saved catalog exists, adding no new persisted field; the four-language (zh / en / ja / zh-TW) `codexConfig` copy was rewritten to match.
+
+### Doubao Seed 2.1 Pro Preset
+
+The DouBaoSeed preset now points to `doubao-seed-2-1-pro` (replacing `doubao-seed-2-0-code-preview-latest`) across all six clients (claude, claude-desktop, codex, opencode, openclaw, hermes), updates the display name to "Doubao Seed 2.1 Pro", and corrects the OpenClaw cost fields from 0.002 / 0.006 to 0.84 / 4.2 USD per million tokens to match the new model.
+
+### CTok Renamed to ETok
+
+Following the vendor's domain, endpoint, and trademark rename, all user-facing branding migrates from CTok to ETok (`ctok.ai`→`etok.ai`, `api.ctok.ai`→`api.etok.ai`, plus the internal id, display name, icon, and README partner banner), across every client preset. The Codex history-migration whitelist still keeps `ctok` as a legacy id alongside the new `etok`, so existing users' local session history stays correctly bucketed after the rename.
+
+### Kimi Preset Naming Unified
+
+The Kimi presets that OpenCode and OpenClaw previously labeled "Kimi K2.7 Code" are renamed to "Kimi" to match the other apps (OpenCode's provider display name is renamed too); the model label still keeps "Kimi K2.7 Code" because it describes the actual model.
+
+### JSON Editor Dark Mode
+
+The CodeMirror `JsonEditor` in the usage-script dialog, the provider form, and the universal provider form now follows the app theme via `useDarkMode()`, switching to the `oneDark` editor theme instead of staying light while the rest of the app is already dark. ([#4556](https://github.com/farion1231/cc-switch/pull/4556))
+
+### More Compact "Add Provider" Header and Footer Hint
+
+The "Add Provider" dialog tightens the vertical spacing from the title to the tabs and from the tabs to the cards from 24px to 12px, and adds an always-visible fixed footer hint guiding users to fill in the fields below after choosing a preset. `FullScreenPanel` gains an optional `contentClassName` prop so the padding override applies only to this panel without affecting other panels that share it.
+
+### Theme-Adaptive Kimi Mark
+
+The inline Kimi placeholder mark is replaced with the vendor's refreshed mark. The K glyph uses `currentColor` so it follows the theme text color (dark in light mode, white in dark mode), while the brand accent color is fixed to the new `#1783FF`, with the metadata fallback color aligned accordingly.
+
+### Removed the Fable 5 Verified Banner
+
+The Settings About page no longer shows the Fable 5 Verified commemorative banner that 3.16.3 added beside the app name to mark a special build; the banner image and its marker are removed, and the About panel returns to the standard version-badge layout.
+
+---
+
+## Fixed
+
+### Copilot / Codex OAuth Requests Now Honor the Global Proxy
+
+`CopilotAuthManager` and `CodexOAuthManager` hardcoded `Client::new()` at construction, so their auth flows (token exchange, fetching the `/models` list, determining model vendor, device-code and OAuth refresh requests) ignored the configured global proxy and connected directly to the target services. On Copilot, a direct connection made `/models` return 0 Claude models, breaking live model resolution, and the upstream rejected requests with `400 model_not_supported`. Both managers now pull from the shared client on each request (`crate::proxy::http_client::get()`), honoring the global proxy URL and supporting runtime hot reload. Fixes [#2016](https://github.com/farion1231/cc-switch/issues/2016) and [#2931](https://github.com/farion1231/cc-switch/issues/2931). ([#4583](https://github.com/farion1231/cc-switch/pull/4583))
+
+### Decompressing Compressed Request and Error Bodies
+
+Codex Desktop sends zstd-compressed request bodies when authenticating to the Codex backend, which broke local proxy routing because the handlers parsed the raw compressed bytes directly with `serde_json`. The proxy now decompresses the request body before JSON parsing (gzip / br / deflate, plus the newly added zstd support, including stacked encodings like `gzip, zstd`), across three Codex handlers, and strips the stale `content-encoding` / `content-length` / `transfer-encoding` request headers so the forwarder regenerates them. Upstream non-2xx error bodies are decompressed the same way, so compressed rate-limit and auth details are no longer dropped and hidden from the client. Fixes [#3764](https://github.com/farion1231/cc-switch/issues/3764) and [#3696](https://github.com/farion1231/cc-switch/issues/3696). ([#3817](https://github.com/farion1231/cc-switch/pull/3817))
+
+### DeepSeek Endpoint 400 with `thinking: disabled`
+
+DeepSeek's Anthropic-compatible endpoint rejects requests where `thinking.type=disabled` coexists with an effort parameter, returning HTTP 400, which broke Claude Code 2.1.166+ sub-agents (Workflow / Dynamic Workflow) that hardcode `thinking: disabled`. Rather than overriding the client's intent, the proxy now strips the conflicting `output_config.effort` / `reasoning_effort` parameters for the official DeepSeek endpoint, since sub-agents don't need to surface reasoning anyway. ([#4239](https://github.com/farion1231/cc-switch/pull/4239))
+
+### Reverted Hoisting Anthropic system Messages
+
+Reverted the [#3775](https://github.com/farion1231/cc-switch/pull/3775) change that hoisted `role=system` messages on Anthropic-compatible providers from `messages[]` up to the top-level `system` field. The DeepSeek endpoint natively accepts inline system messages, and the rewrite changed the request prefix; keeping messages in place preserves the prompt prefix and avoids a suspected cache-hit-rate regression (see [#4297](https://github.com/farion1231/cc-switch/issues/4297)). The unrelated Windows test fix and the tool-thinking-history normalization from #3775 are retained.
+
+### Chat Tool Calls Missing Function Names
+
+Some upstreams send empty or missing function names in streaming tool-call deltas, which used to produce invalid Codex Chat output items (or an `unknown_tool` fallback). Accumulated tool-call state is no longer overwritten by an empty delta, and tool calls that never receive a `call_id` and a valid name are skipped at finalization, across the streaming, non-streaming, and legacy `function_call` paths. ([#4159](https://github.com/farion1231/cc-switch/pull/4159))
+
+### Restore Cached Codex Tool-Call Fields
+
+When Codex makes a follow-up Chat request that references a `previous_response_id`, its `function_call` items may carry only the `call_id`. History enhancement previously backfilled only `reasoning` / `reasoning_content`, leaving the function's `name`, `arguments`, `status`, and other fields empty; it now restores all cached tool-call fields from history so the call can be correctly reconstructed for the Chat upstream. ([#4160](https://github.com/farion1231/cc-switch/pull/4160))
+
+### Duplicate Codex base_url Entries in config.toml
+
+Writing Codex's `base_url` into `config.toml` previously replaced or removed only one matching assignment per section, so a section that already contained multiple `base_url` lines kept the extras and accumulated duplicates. `setCodexBaseUrl` now collapses all matches in the target section or at the top level (replacing the first, removing the rest), and the TOML `base_url` regex now handles escaped quotes. ([#4316](https://github.com/farion1231/cc-switch/pull/4316))
+
+### History Migration Probes the CODEX_SQLITE_HOME State DB
+
+Codex session-history migration previously scanned only `~/.codex/state_5.sqlite` and the `sqlite_home` location in `config.toml`, so when Codex's SQLite state was relocated via the `CODEX_SQLITE_HOME` environment variable, the state DB was never scanned and its threads stayed in the old provider bucket. The `codex_state_db_paths` helper shared by both the third-party and unified-session migrations now falls back to `CODEX_SQLITE_HOME` (the `sqlite_home` in `config` still takes precedence).
+
+### Provider Terminal Honors the User Shell
+
+Launching a provider terminal on macOS / Linux previously hardcoded `bash`, so zsh / fish users' rc files weren't loaded. The launcher now detects the user's default shell from `$SHELL` (falling back to `/bin/zsh` on macOS, `/bin/bash` on Linux) and execs into it with the clean-start flag, while the launch script itself now uses POSIX `sh` for portability (e.g. fish, and NixOS where `/bin/sh` may not exist). ([#4140](https://github.com/farion1231/cc-switch/pull/4140), fixes [#1546](https://github.com/farion1231/cc-switch/issues/1546))
+
+### Claude MCP Paths Honor the Custom Config Directory
+
+When a custom Claude config directory is configured, MCP server reads and writes now resolve to the MCP file under that directory instead of the default location, isolating MCP state per profile. The old "copy on access" migration of the legacy file was removed in favor of resolving the override path directly. ([#3431](https://github.com/farion1231/cc-switch/pull/3431))
+
+### Preset Results Clickable After Search
+
+After searching in the "Add Provider" preset selector, results briefly couldn't be clicked or selected. The `requestAnimationFrame` `select()` that fought the input and swallowed the first character (e.g. "gateway" → "ateway") was removed, input auto-focus on the open-and-click path was restored, and pressing Ctrl/Cmd+F while the search box is already open now refocuses it. The provider list's typing guard was also narrowed to the Ctrl/Cmd+F branch so Escape can still close the search panel. ([#4315](https://github.com/farion1231/cc-switch/pull/4315))
+
+### Skills Browsing and Provider Card Display Fixes
+
+Fixed several display and interaction issues: repository management actions stay available while browsing skills.sh, and refresh stays available when a repository returns empty results; overly long provider names and website URLs on provider cards now truncate instead of overflowing; the OMO model-variant dropdown truncates the selected label with a full-text tooltip; and Select menu items show a checkmark on the currently selected item. ([#4323](https://github.com/farion1231/cc-switch/pull/4323))
+
+### Reset Scroll When Switching Settings Tabs
+
+Switching tabs in the Settings dialog used to keep the previous tab's scroll position, sometimes landing halfway down the new tab; the scroll container now resets to the top whenever the active tab changes. ([#4165](https://github.com/farion1231/cc-switch/pull/4165))
+
+---
+
+## Documentation
+
+### Kimi Pinned Sponsor Banner
+
+The pinned sponsor banner at the top of all four README languages (en / zh / ja / de) is now Kimi K2.7 Code, replacing the previous MiniMax M2.7 banner. The copy reflects the K2.7 Code release (a coding-oriented agentic model with thinking-token usage down roughly 30% from K2.6), the banner is now served from in-repo assets (`assets/partners/banners/kimi-banner-en.png` / `kimi-banner-zh.png`) instead of the Moonshot CDN, and it carries a clickable call to action pointing at the `aff=cc-switch` Moonshot console.
+
+### Codex Unified Session History Guide
+
+Added a three-language (zh / en / ja) guide explaining what the unified Codex session history toggle's enable-time migration (when enabled) and ledger-based restore (when disabled) actually do, why session data is never truly deleted (only re-tagged + auto-backed-up), and how to verify whether files really are on disk or were just filed into another provider's drawer. It includes a symptom table for the common "my sessions are gone" misunderstanding and disk-verification commands for macOS / Linux / Windows, and is linked as the first item in the v3.16.3 release notes' "Usage Guides".
+
+### Simplified Homebrew Install Instructions
+
+The install guide no longer asks users to run `brew tap farion1231/ccswitch` before `brew install --cask cc-switch`; this deprecated tap step is removed from the en / ja / zh user manuals, and the cask now installs directly. ([#4319](https://github.com/farion1231/cc-switch/pull/4319))
+
+### Star-History Global Ranking Badge
+
+Added a star-history global ranking badge next to the existing Trendshift badge across all four README languages, with light / dark theme variants.
+
+### Volcengine Ark Coding Plan Activity Link
+
+The "developers in mainland China click here" link in the ByteDance / Volcengine Ark sponsor entry now points to Volcengine's `ai618` activity page, replacing the previous `codingplan` referral URL, across all four README languages.
+
+### CCSub Sponsor Banner Vector Asset
+
+Replaced the low-resolution `ccsub.jpg` sponsor logo with the vector `ccsub.svg`, letterboxed from 2046x648 to 2046x850 (roughly 2.406:1) so it matches the other sponsor-table banners and renders at the same 62px height. All four README languages point to the new asset.
+
+---
+
+## Upgrade Notes
+
+### Chinese Codex Providers' Native Responses Migration
+
+This release switches the Codex presets of several Chinese providers with native Responses endpoints (Qwen / DashScope, Xiaomi MiMo, Volcengine Doubao, Meituan LongCat, MiniMax domestic / international) to `openai_responses` and removes their `modelCatalog`. Existing providers already configured from these presets are unaffected and keep their configuration as-is; if you want to switch to native Responses (dropping the format-conversion takeover), re-pick the preset once and save. SiliconFlow-hosted MiniMax stays on `openai_chat` and is not part of this migration.
+
+### Recovery from a Too-New Database
+
+If you opened the database with a higher version of CC Switch and then switched back to an older version, the older version will enter the new "database version too new" recovery screen on startup and guide you to upgrade to a version that can read the database. This is expected behavior — upgrading to the latest version restores normal operation.
+
+---
+
+## Risk Notice
+
+This release continues the risk notices from previous versions for reverse-proxy-style features.
+
+**Codex OAuth reverse proxy**: using a ChatGPT subscription's Codex OAuth through a reverse proxy may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details.
+
+**Codex third-party provider Chat routing**: when CC Switch local proxy converts and forwards Codex requests to third-party providers, each provider may have different requirements for billing, compliance, and data retention. Read the target provider's terms before use.
+
+**Claude Desktop third-party provider proxy switching**: when CC Switch's built-in proxy gateway forwards Claude Desktop requests to third-party providers, you must also follow the target provider's billing, compliance, and data-retention terms.
+
+By enabling these features, users accept the related risks. CC Switch is not responsible for account restrictions, warnings, or service suspensions caused by using these features.
+
+---
+
+## Thanks
+
+Thanks to the following contributors for the features and fixes in v3.16.4:
+
+- [#3817](https://github.com/farion1231/cc-switch/pull/3817): decompress the request body before forwarding and add zstd support, thanks @chenx-dust.
+- [#4583](https://github.com/farion1231/cc-switch/pull/4583): fix the Copilot / Codex OAuth modules bypassing the global proxy and causing Claude model 400s, thanks @zymouse.
+- [#4589](https://github.com/farion1231/cc-switch/pull/4589): add local proxy request overrides (custom headers and request body), thanks @mfzzf.
+- [#4575](https://github.com/farion1231/cc-switch/pull/4575): add an in-app recovery screen for a too-new database version, thanks @SaladDay.
+- [#4556](https://github.com/farion1231/cc-switch/pull/4556): wire dark mode into the JsonEditor in several places, thanks @TanKimzeg.
+- [#4438](https://github.com/farion1231/cc-switch/pull/4438): add a live end time for custom date ranges, thanks @arichyx.
+- [#3950](https://github.com/farion1231/cc-switch/pull/3950): add Windows ARM64 release support, thanks @MOON-DREAM-STARS.
+- [#4401](https://github.com/farion1231/cc-switch/pull/4401): add CLAUDE_CODE_AUTO_COMPACT_WINDOW to the Kimi For Coding preset, thanks @cyijun.
+- [#4323](https://github.com/farion1231/cc-switch/pull/4323): fix the Skills management and model-config interaction display, thanks @thisTom.
+- [#3431](https://github.com/farion1231/cc-switch/pull/3431): align Claude MCP paths to the custom config directory, thanks @makoMakoGo.
+- [#4159](https://github.com/farion1231/cc-switch/pull/4159): skip Chat tool calls missing function names, thanks @hueifeng.
+- [#4385](https://github.com/farion1231/cc-switch/pull/4385): add glm-5.2 pricing, thanks @arichyx.
+- [#4079](https://github.com/farion1231/cc-switch/pull/4079): support importing model pricing from models.dev, thanks @kingcanfish.
+- [#4315](https://github.com/farion1231/cc-switch/pull/4315): fix preset results not being clickable / selectable after search, thanks @RuixeWolf.
+- [#4316](https://github.com/farion1231/cc-switch/pull/4316): prevent duplicate Codex base_url entries, thanks @jeffwcx.
+- [#4140](https://github.com/farion1231/cc-switch/pull/4140): make the provider terminal honor the user shell, thanks @zkforge.
+- [#4113](https://github.com/farion1231/cc-switch/pull/4113): show the source file name in the session detail header, thanks @xu-song.
+- [#4160](https://github.com/farion1231/cc-switch/pull/4160): restore cached Codex tool-call fields, thanks @chen-985211.
+- [#4239](https://github.com/farion1231/cc-switch/pull/4239): strip the effort parameter when thinking:disabled on DeepSeek endpoints, thanks @maskshell.
+- [#4165](https://github.com/farion1231/cc-switch/pull/4165): reset scroll when switching settings tabs, thanks @Muleizhang.
+- [#4319](https://github.com/farion1231/cc-switch/pull/4319): remove the deprecated Homebrew tap step, thanks @tianpeng-dev.
+- [#4522](https://github.com/farion1231/cc-switch/pull/4522): add the SubRouter provider preset, thanks @abingyyds.
+
+Thanks also to everyone who reported Codex proxy chain, usage billing, local proxy robustness, and platform compatibility issues after the v3.16.3 release. Many of these patches came directly from real-world reproduction clues.
+
+---
+
+## Download & Install
+
+Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) and download the build for your system.
+
+### System Requirements
+
+| System  | Minimum Version          | Architecture                        |
+| ------- | ------------------------ | ----------------------------------- |
+| Windows | Windows 10 and later     | x64 / ARM64                         |
+| macOS   | macOS 12 (Monterey)+     | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | See table below          | x64 / ARM64                         |
+
+### Windows
+
+| File                                     | Description                                      |
+| ---------------------------------------- | ------------------------------------------------ |
+| `CC-Switch-v3.16.4-Windows.msi`          | **Recommended** - MSI installer with auto-update |
+| `CC-Switch-v3.16.4-Windows-Portable.zip` | Portable build, unzip and run                    |
+
+Windows ARM64 devices should pick the artifact whose file name carries the `arm64` tag.
+
+### macOS
+
+| File                             | Description                                           |
+| -------------------------------- | ----------------------------------------------------- |
+| `CC-Switch-v3.16.4-macOS.dmg`    | **Recommended** - DMG installer, drag to Applications |
+| `CC-Switch-v3.16.4-macOS.zip`    | Unzip and drag to Applications, Universal Binary      |
+| `CC-Switch-v3.16.4-macOS.tar.gz` | For Homebrew install and auto-update                  |
+
+Homebrew install:
+
+```bash
+brew install --cask cc-switch
+```
+
+Upgrade:
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+Linux assets are available for both **x86_64** and **ARM64** (`aarch64`). Choose the file whose architecture tag matches your machine's `uname -m` output:
+
+- `CC-Switch-v3.16.4-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.16.4-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| Distribution                            | Recommended Format | Install Command                                                        |
+| --------------------------------------- | ------------------ | --------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`             | `sudo dpkg -i CC-Switch-*.deb` or `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`             | `sudo rpm -i CC-Switch-*.rpm` or `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`             | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                    | `.AppImage`        | Make executable and run directly, or use AUR                          |
+| Other distributions / unsure            | `.AppImage`        | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`             |
@@ -0,0 +1,356 @@
+# CC Switch v3.16.4
+
+> 🎉 **CC Switch が GitHub の全世界 Star ランキングでトップ 100 入り！**
+> ここまで支えてくださったすべてのユーザー、コントリビューター、そして Star に感謝します。🙏
+
+> v3.16.3 で「使用量の課金を正確にする」ことに取り組んだのに続き、本リリースは Codex プロキシ経路の磨き込みと、使用量 / 価格ツールの拡充に重きを置いています——国産プロバイダーのネイティブ Responses への移行、上流の形式セレクタとモデルマッピングの分離、zstd リクエスト / エラーボディの展開、そしてツール呼び出しと OAuth がプロキシを経由するようにする一連の修正です。あわせて、ローカルプロキシのリクエストオーバーライド、データベースのバージョンが新しすぎる場合のアプリ内リカバリ画面、ネイティブ Windows ARM64 ビルドを新設し、一連のプリセットとブランドの更新（SubRouter、OpenCode Go、CTok→ETok の改名、Kimi のブランド刷新と prime-partner バッジ）を届けます。
+
+**[English →](v3.16.4-en.md) | [中文版 →](v3.16.4-zh.md)**
+
+---
+
+## 利用ガイド
+
+本リリースは磨き込みと拡張が中心で、新しい機能の多くは使用量パネルとプロバイダーフォームの高度なオプションに収まっています。以下のドキュメントとあわせてご覧ください：
+
+- **[Codex デスクトップでカスタムモデルが見えない？](../guides/codex-desktop-custom-model-visibility-ja.md)**: Codex デスクトップアプリで、設定したサードパーティ / カスタムモデルが見えないというフィードバックが少なくありません。これは Codex デスクトップアプリ**上流自身のゲーティング挙動**（公式ログイン状態に応じてモデルセレクタを通す）であり、CC Switch のローカル設定の問題ではありません。**本リリース（v3.16.4）でこの点に変更はありません**。ドキュメントでは原因と、使える緩和策（公式ログインの保持 + ルーティングテイクオーバー）を解説しています。
+- **[使用量統計](../user-manual/ja/4-proxy/4.4-usage.md)**: 使用量ダッシュボードのデータソースと集計の仕組みを確認できます。本リリースでは models.dev からのモデル価格一括インポート、火山方舟 Coding / Agent Plan の AK/SK 使用量照会、カスタム日付範囲の「リアルタイム終了時刻」を追加しました。
+- **[設定](../user-manual/ja/1-getting-started/1.5-settings.md)**: ローカルプロキシのリクエストオーバーライド（カスタムリクエストヘッダー / リクエストボディ）、Codex の上流形式セレクタやローカルルーティングのトグルは、いずれもプロバイダーフォームの高度なオプションにあります。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一の公式チャネル（必ずお読みください）
+>
+> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。本ソフトウェアは下記の公式チャネルからのみ入手してください：
+>
+> | チャネル     | 唯一の公式                                                                     |
+> | ------------ | ------------------------------------------------------------------------------ |
+> | 公式サイト   | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者         | **[@farion1231](https://github.com/farion1231)**                               |
+> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は直ちに操作を中止し、GitHub Issues からご報告ください。
+
+---
+
+## 概要
+
+CC Switch v3.16.4 は v3.16.3 に続くメンテナンスアップデートです。本リリースは Codex プロキシ経路まわりを一通り締め直しました——ネイティブの OpenAI Responses endpoint を備える複数の国産プロバイダーをネイティブ形式へ切り替え（Responses→Chat のルーティングテイクオーバー変換を省く）、「上流形式」を「ローカルルーティング」トグルから独立させ、zstd のリクエストとエラーレスポンスボディの展開を補い、ツール呼び出しと「OAuth モジュールがグローバルプロキシをバイパスする」一連の問題を修正しました。
+
+あわせて本リリースでは使用量と価格のツールを拡充し（models.dev からの価格インポート、火山方舟 Coding / Agent Plan の AK/SK 使用量照会、カスタム日付範囲のリアルタイム終了時刻、GLM-5.2 と Doubao Seed 2.1 の価格）、一連のプロキシと堅牢性の機能を新設し（カスタムリクエストヘッダー / リクエストボディのオーバーライド、データベースのバージョンが新しすぎる場合のアプリ内リカバリ画面、ネイティブ Windows ARM64 ビルド）、一連のプリセットとブランドの更新（SubRouter と OpenCode Go のサブスクリプション、CTok→ETok の改名、Kimi のブランド刷新と prime-partner バッジ、Kimi K2.7 Code スポンサーバナー）を届けます。
+
+**リリース日**: 2026-06-27
+
+**Stats**: 53 commits | 126 files changed | +8,149 / -1,016 lines
+
+---
+
+## ハイライト
+
+- **国産 Codex プロバイダーがネイティブ Responses を使用**: 千問 / 百炼、小米 MiMo、火山 Doubao、美団 LongCat、MiniMax（国内 / 国際）が、それぞれのネイティブ Responses endpoint に直結するようになり、Responses→Chat の形式変換テイクオーバーを経由しなくなりました。経路が短く、より安定します。
+- **ローカルプロキシのリクエストオーバーライド**: プロバイダーにカスタムリクエストヘッダーとリクエストボディのオーバーライドを設定でき、ローカルプロキシが転送時に適用します。保護対象のセキュリティ関連リクエストヘッダーにはブロック検証を行います。
+- **データベースのバージョンが新しすぎる場合のアプリ内リカバリ画面**: SQLite のバージョンが現在のアプリのサポート範囲より新しいとき、「再試行しても再び失敗するだけ」のネイティブダイアログで詰まらず、ワンクリックでアプリを更新できるリカバリ画面へ案内します。
+- **より充実した使用量 / 価格ツール**: models.dev からのモデル価格一括インポート、火山方舟 Coding / Agent Plan の AK/SK 使用量照会、カスタム日付範囲の「リアルタイム終了時刻」、そして GLM-5.2 と Doubao Seed 2.1 の価格。
+- **新しいプリセットとブランド更新**: SubRouter と OpenCode Go のサブスクリプションプリセットを追加し、CTok を ETok へ改名し、Kimi のブランドアイコンを刷新し、公式 Kimi プリセットに prime-partner のハートバッジを付けました。
+- **ネイティブ Windows ARM64 ビルド**: 配布物にネイティブ ARM64 版を追加し、ARM アーキテクチャの Windows デバイスは x64 エミュレーションに頼る必要がなくなりました。
+
+---
+
+## 追加機能
+
+### データベースのバージョンが新しすぎる場合のアプリ内リカバリ画面
+
+SQLite の `user_version` が現在のアプリのサポートする `SCHEMA_VERSION` より新しいとき（旧版へダウングレードした、あるいはサードパーティクライアントがこのファイルを書いた場合など）、これまでは起動時にネイティブの「再試行 / 終了」ダイアログで詰まっていました——しかし「再試行」は再び失敗するだけです。現在はアプリが専用のリカバリ画面へ案内します: 利用可能な更新があればワンクリックの「アプリを更新」ボタン（ダウンロード + インストール + 再起動、プログレスバー付き）を提供し、利用可能な更新がない場合は最新版であってもこのデータベースを読めない旨を案内します。この「バージョンが新しすぎる」チェックは、あらゆる書き込み動作の前に行われるため、アプリが読めないデータベースに対して DDL を実行することは決してありません。リカバリモードでのネイティブな終了はクリーンに終了します（この時点ではトレイがまだ作成されていません）。（[#4575](https://github.com/farion1231/cc-switch/pull/4575)）
+
+### ローカルプロキシのリクエストオーバーライド（カスタムリクエストヘッダーとリクエストボディ）
+
+プロバイダー設定で、カスタムリクエストヘッダーとリクエストボディのオーバーライドを定義できるようになり、ローカルプロキシが転送時に適用します。Claude と Codex のプロバイダーフォームの新しいフィールドから公開します。入力は検証を経て、その中にセキュリティに敏感なリクエストヘッダーの上書きを防ぐ保護対象リクエストヘッダーのリストを含みます。（[#4589](https://github.com/farion1231/cc-switch/pull/4589)）
+
+### 火山方舟 Coding / Agent Plan 使用量照会
+
+使用量パネルから火山方舟（Volcengine Ark）の Coding Plan と Agent Plan のクォータを照会できるようになりました。方舟のコントロールプレーン OpenAPI（`open.volcengineapi.com`）が要求するのは推論 API key ではなくアカウント単位の AccessKey 署名であるため、使用量スクリプトに独立した AK/SK 入力欄を新設し、火山 IAM のキー管理コンソール（`https://console.volcengine.com/iam/keymanage`）へ直接飛べるクリック可能なリンクを添えました。プロキシは火山署名 V4（AWS SigV4 の変種: 固定された canonical header 順、`HMAC-SHA256` アルゴリズム、`ark` サービス scope）を実装しています。まず `GetAFPUsage`（Agent Plan の 5 時間 / 週 / 月クォータ）をプローブしてプランを自動判定し、失敗した場合は `GetCodingPlanUsage` へフォールバックして `Level` フィールドからウィンドウラベルを解析し（`ResetTimestamp <= 0` にはガードを設けます）、あわせて使用量フッター、トレイメニュー、4 言語に `monthly` 階層のラベルを補いました。
+
+### models.dev からのモデル価格インポート
+
+「価格を追加」パネルに「models.dev からインポート」ボタンを新設しました: `https://models.dev/api.json` を取得し、カタログ全体の全文検索に対応し、選択した項目を手入力と同じ `update_model_pricing` 経路でインポートします。インポートされた model id は、バックエンドの `clean_model_id_for_pricing` ルール（プロバイダープレフィックスの除去、小文字化、`:` サフィックスの切り捨て、`@` を `-` へマッピング、`[1m]` マーカーの除去）で正規化されるため、保存される行がコスト帰属クエリと本当にマッチするようになります。あわせて、「範囲ごとのゼロコストバックフィル」を、精密な SQL 文字列マッチではなく Rust 側で元の model エイリアス（ルーティングプレフィックス、`:free` 変種、日付サフィックス）でマッチするように修正したため、新しい価格のエイリアス行が次回起動時のバックフィルを待たず即座に課金されるようになりました（[#4017](https://github.com/farion1231/cc-switch/issues/4017) を修正）。（[#4079](https://github.com/farion1231/cc-switch/pull/4079)）
+
+### ネイティブ Windows ARM64 ビルド
+
+配布物にネイティブの Windows ARM64 制品が含まれるようになり、ARM アーキテクチャの Windows デバイスは対応するネイティブビルドを入手でき、x64 エミュレーションに頼る必要がなくなりました。リリースマトリクスも各プラットフォームが独立して走るように変更し（fail-fast を無効化）、あるジョブがキー欠如で失敗しても（fork での macOS 署名など）、まだ完了していない同列のジョブをまとめてキャンセルしないようにしました。（[#3950](https://github.com/farion1231/cc-switch/pull/3950)）
+
+### カスタム日付範囲のリアルタイム終了時刻
+
+カスタム日付範囲セレクタに「終了時刻を現在時刻に追従」チェックボックスを新設しました。有効にすると終了時刻は読み取り専用になり、今この瞬間に自動追従するため、使用量データは選択した起点から現在までのリアルタイムの消費を常に反映します。これは Coding Plan の 5 時間クォータウィンドウで特に有用です。`liveEndTime` は React Query のキャッシュキーに取り込んだため、リアルタイム範囲と終点が同じ固定範囲が同一の古いキャッシュ項目を共有することはなくなりました。（[#4438](https://github.com/farion1231/cc-switch/pull/4438)）
+
+### セッション詳細ヘッダーにソースファイル名を表示
+
+セッション詳細ヘッダーが、プロジェクトディレクトリの隣にセッションログのファイル名を表示するようになりました（ホバーで完全パスを確認、クリックでコピー）。これにより、画面から直接、基礎となる JSONL ファイルを特定して開けます。~70 文字の Codex rollout のような空白を含まない長いファイル名は `max-w-[200px]` で切り詰め、狭いウィンドウで操作ボタン領域へあふれ出るのを防ぎます。（[#4113](https://github.com/farion1231/cc-switch/pull/4113)）
+
+### インポートボタンの未管理 Skill ヒント
+
+トップバーの Skills インポートボタンが、ローカルにインポート可能な未管理の Skill が存在するとき、緑のドットとヒントを表示するようになり、ディスク上の Skill がまだ管理対象になっていないことが一目で分かります。このスキャンはマウント時に一度実行され、複数のナビゲーションをまたいで共有され（30s の `staleTime` + `keepPreviousData`）、ディスク IO の重複を避けます。
+
+### OpenCode Go サブスクリプションプリセット
+
+OpenCode Go（`opencode.ai/zen/go`）プリセットを追加し、Claude、Codex、OpenCode をカバーし、そのまま貼り付けられる素の API key（OAuth なし）を使用します。Codex プリセットは `openai_chat` 変換を使い、GLM / Kimi / DeepSeek / MiMo のモデルカタログを備え（静的な `codexChatReasoning` は付けず、モデルごとに能力を推論します）、OpenCode は `@ai-sdk/openai-compatible` 経由で `/zen/go/v1` を指します。4 つの OpenCode Go プリセット——Claude、Claude Desktop、Codex、OpenCode——にはいずれも紹介リンクとアプリ内宣伝文を付けました。宣伝バナーは `partnerPromotionKey` だけで表示できるようになり（`isPartner` への紐付けを解除）、あるプリセットが金色の有料パートナースターを得ずに紹介宣伝を表示できるようになりました（これにより既存の MiniMax 宣伝も再表示されます）。
+
+### Prime-Partner プリセットバッジとソート
+
+第一方 Moonshot Kimi プリセット（Kimi / Kimi For Coding / Kimi K2.7 Code）が prime partner としてマークされるようになりました: 金色のスターは表示せず、塗りつぶしの金色ハート（バッジ枠なし）を描画し、既定（Original）ソートでは公式カテゴリプリセットの後、その他より前に浮かびます。グルーピングは 3 方向の partition で実装し、各グループは内部順序を保ち、prime-partner としてもマークされた公式プリセットは公式グループにのみ残ります。
+
+### GLM-5.2 と Doubao Seed 2.1 の価格
+
+シードモデル価格に GLM-5.2（[#4385](https://github.com/farion1231/cc-switch/pull/4385)）と Doubao Seed 2.1 Pro / Turbo を追加し、これらのモデルの使用量がゼロコストではなく正しく課金されるようにしました。Doubao の価格は火山公式の定価を採用し（約 7.14 のレートで換算）、`cache_creation` は 0 のままです。Doubao はキャッシュストレージを token 書き込みではなく時間で課金するためで、既存の 2.0 行も過去の記帳のために残します。
+
+### Kimi For Coding 自動圧縮ウィンドウ
+
+Kimi For Coding プリセットが `CLAUDE_CODE_AUTO_COMPACT_WINDOW` を既定で 262144 に設定するようになり、Kimi 公式ドキュメントと一致させ、`templateValues` 経由で公開して、将来のモデルや性能チューニングのためにユーザーがこの値をカスタマイズできるようにしました。（[#4401](https://github.com/farion1231/cc-switch/pull/4401)）
+
+### SubRouter パートナープロバイダー
+
+SubRouter（`subrouter.ai`、1 つの key で複数モデル・複数プロバイダーにアクセスできる AI 中継アグリゲーター）をプリセットとして追加し、管理対象の 7 アプリすべてをカバーしました——Claude Code / Claude Desktop / OpenClaw / Hermes 向けには Anthropic 形式 endpoint、Codex と OpenCode 向けには OpenAI 互換の `/v1` endpoint（`gpt-5.5`）、Gemini CLI 向けには Gemini 互換の `/v1beta` endpoint（`gemini-3.5-flash`）——自前のブランドアイコン、金色のパートナースター、4 言語の宣伝文、そして API key の登録ページへ事前入力された紹介登録リンク（`?aff=l3ri`）を備えます。（[#4522](https://github.com/farion1231/cc-switch/pull/4522)）
+
+---
+
+## 変更
+
+### 国産 Codex プロバイダーがネイティブ Responses API を使用
+
+複数の国産プロバイダー（千問 / DashScope 百炼、小米 MiMo、火山 Doubao、美団 LongCat、MiniMax 国内 / 国際）がネイティブの OpenAI Responses endpoint を公開したため、それらの Codex プリセットを `apiFormat: "openai_responses"` へ切り替え、Responses→Chat のルーティングテイクオーバー変換を経由せず上流に直結するようにしました。不要になった `codexChatReasoning` と `modelCatalog` を外したことで、「ローカルルーティングマッピング」トグルも既定で未選択のままになります。SiliconFlow がホストする MiniMax は `openai_chat` のままです。これは MiniMax 自身の base_url ではなくサードパーティの endpoint だからです。引き続き chat を使う他のプロバイダーも、古くなった model id を更新しました（GLM 5.1→5.2、StepFun 3.5-flash-2603→3.7-flash、Ling 2.5-1T→2.6-1T）。
+
+### 上流形式セレクタとモデルマッピングトグルの分離
+
+Codex プロバイダーフォームは以前、Chat 形式変換とルーティングテイクオーバー（モデルマッピング）を同じトグルに束ねていたため、ネイティブ Responses API を提供するプロバイダーが Chat Completions 変換を強制せずにモデルマッピングを使うことができませんでした。現在は「上流形式」（Chat Completions / Responses）が独立して常に見えるセレクタになり、ローカルルーティングトグルは高度なサブ領域（モデルマッピングカタログ、および形式が Chat のときの推論能力）の制御だけを担います。その初期状態は保存済みカタログの有無から導かれ、永続化フィールドは増やしません。`codexConfig` の 4 言語（zh / en / ja / zh-TW）の文言もあわせて書き直しました。
+
+### Doubao Seed 2.1 Pro プリセット
+
+DouBaoSeed プリセットが、6 つのクライアントすべて（claude、claude-desktop、codex、opencode、openclaw、hermes）で `doubao-seed-2-1-pro` を指すようになり（`doubao-seed-2-0-code-preview-latest` を置き換え）、表示名を「Doubao Seed 2.1 Pro」に更新し、OpenClaw のコストフィールドを新モデルに合わせて 0.002 / 0.006 から 0.84 / 4.2 ドル毎 100 万 token へ訂正しました。
+
+### CTok を ETok へ改名
+
+ベンダーによるドメイン・endpoint・商標の改名に合わせ、ユーザーに見えるブランドをすべて CTok から ETok へ移行しました（`ctok.ai`→`etok.ai`、`api.ctok.ai`→`api.etok.ai`、および内部 id、表示名、アイコン、README パートナーバナー）。各クライアントプリセットを網羅します。Codex 履歴移行のホワイトリストでは、改名後も既存ユーザーのローカルセッション履歴が正しく分類されるよう、旧 id の `ctok` を新しい `etok` と並存させたまま残します。
+
+### Kimi プリセットの命名統一
+
+OpenCode と OpenClaw で以前「Kimi K2.7 Code」とマークされていた Kimi プリセットを、他のアプリと一致する「Kimi」へ改名しました（OpenCode のプロバイダー表示名もあわせて改名）。モデルラベルは引き続き「Kimi K2.7 Code」のままです。これは実際のモデルを表しているためです。
+
+### JSON エディタのダークモード
+
+使用量スクリプトのダイアログ、プロバイダーフォーム、ユニバーサルプロバイダーフォーム内の CodeMirror `JsonEditor` が、`useDarkMode()` を通じてアプリのテーマに追従し、`oneDark` エディタテーマへ切り替わるようになり、アプリの他の部分がすでにダークなのにライトのままになることがなくなりました。（[#4556](https://github.com/farion1231/cc-switch/pull/4556)）
+
+### よりコンパクトな「プロバイダーを追加」のタイトルとフッターヒント
+
+「プロバイダーを追加」ダイアログで、タイトルからタブ、タブからカードへの縦方向の間隔を 24px から 12px へ詰め、プリセットを選んだ後に下のフィールドを記入するよう案内する、常に見える固定フッターヒントを新設しました。`FullScreenPanel` には任意の `contentClassName` プロパティを追加し、パディングの上書きをこのパネルだけに作用させ、これを共有する他のパネルに影響しないようにしました。
+
+### テーマ追従の Kimi アイコン
+
+インラインの Kimi プレースホルダーマーカーを、ベンダーが刷新したアイコンへ置き換えました。K 字形は `currentColor` を使うため、テーマのテキスト色に追従し（ライトモードは濃く、ダークモードは白く）、ブランドのアクセント色は新しい `#1783FF` に固定し、メタデータのフォールバック色もそれに合わせました。
+
+### Fable 5 Verified 記念バナーの削除
+
+設定の「バージョン情報」ページが、3.16.3 で特別ビルドを示すためにアプリ名の隣に付けていた Fable 5 Verified 記念バナーを表示しなくなりました。バナー画像とそのマーカーを削除し、「バージョン情報」パネルは標準のバージョンバッジレイアウトに戻りました。
+
+---
+
+## 修正
+
+### Copilot / Codex OAuth リクエストがグローバルプロキシに従うように
+
+`CopilotAuthManager` と `CodexOAuthManager` は構築時に `Client::new()` をハードコードしていたため、それらの認証フロー（token の交換、`/models` リストの取得、model vendor の判定、device-code と OAuth のリフレッシュリクエスト）が設定済みのグローバルプロキシを無視し、対象サービスへ直結していました。Copilot では、直結により `/models` が Claude モデルを 0 個返し、live のモデル解決が失効し、上流が `400 model_not_supported` でリクエストを拒否していました。現在は両 manager が、リクエストのたびに共有クライアント（`crate::proxy::http_client::get()`）からその場で取得するように変更され、グローバルプロキシ URL に従い、ランタイムのホット更新にも対応します。[#2016](https://github.com/farion1231/cc-switch/issues/2016)、[#2931](https://github.com/farion1231/cc-switch/issues/2931) を修正。（[#4583](https://github.com/farion1231/cc-switch/pull/4583)）
+
+### 圧縮されたリクエストボディとエラーボディの展開
+
+Codex Desktop は Codex バックエンドへ認証するとき zstd 圧縮のリクエストボディを送ります。これがローカルプロキシのルーティングを壊していました。ハンドラーが生の圧縮バイトをそのまま `serde_json` で解析していたためです。プロキシは現在、JSON 解析の前にリクエストボディを展開し（gzip / br / deflate に加え、新たに zstd に対応、`gzip, zstd` のような積み重ねエンコーディングを含む）、3 つの Codex ハンドラーをカバーし、古くなった `content-encoding` / `content-length` / `transfer-encoding` リクエストヘッダーを剥がして転送器に再生成させます。上流の非 2xx のエラーボディも同様に展開されるため、圧縮されたレート制限や認証の詳細がクライアントに対して破棄・隠蔽されることがなくなりました。[#3764](https://github.com/farion1231/cc-switch/issues/3764)、[#3696](https://github.com/farion1231/cc-switch/issues/3696) を修正。（[#3817](https://github.com/farion1231/cc-switch/pull/3817)）
+
+### DeepSeek endpoint で `thinking: disabled` のときの 400 エラー
+
+DeepSeek の Anthropic 互換 endpoint は、`thinking.type=disabled` と effort パラメータが共存するリクエストを HTTP 400 で拒否します。これは Claude Code 2.1.166+ で `thinking: disabled` をハードコードするサブ agent（Workflow / Dynamic Workflow）を壊していました。プロキシは現在、クライアントの意図を上書きするのではなく、公式 DeepSeek endpoint に対しては競合する `output_config.effort` / `reasoning_effort` パラメータを剥がします。サブ agent はそもそも推論の表示を必要としないためです。（[#4239](https://github.com/farion1231/cc-switch/pull/4239)）
+
+### Anthropic system メッセージの引き上げをロールバック
+
+Anthropic 互換プロバイダーの `role=system` メッセージを `messages[]` からトップレベルの `system` フィールドへ引き上げる [#3775](https://github.com/farion1231/cc-switch/pull/3775) の変更をロールバックしました。DeepSeek endpoint はそもそもインラインの system メッセージをネイティブに受け付けますが、この書き換えはリクエストのプレフィックスを変えてしまいました。メッセージを元の位置に保つことで prompt プレフィックスを保持し、一見キャッシュヒット率の後退と思われる現象を回避します（[#4297](https://github.com/farion1231/cc-switch/issues/4297) を参照）。#3775 由来の、無関係な Windows テスト修正と tool-thinking-history の正規化は残します。
+
+### Chat ツール呼び出しの関数名欠落
+
+一部の上流は、ストリーミングのツール呼び出し増分で空の、または欠落した関数名を送ります。これは以前、無効な Codex Chat の出力項（または `unknown_tool` フォールバック）を生んでいました。現在は累積したツール呼び出し状態が空の増分で上書きされることがなくなり、最後まで `call_id` と有効な名前を得られなかったツール呼び出しは最終化フェーズでスキップされます。ストリーミング、非ストリーミング、旧版 `function_call` の 3 経路をカバーします。（[#4159](https://github.com/farion1231/cc-switch/pull/4159)）
+
+### Codex のキャッシュされたツール呼び出しフィールドの復元
+
+Codex が `previous_response_id` を参照する後続の Chat リクエストを発行するとき、その `function_call` 項が `call_id` だけを携える場合があります。履歴拡張は以前 `reasoning` / `reasoning_content` だけをバックフィルし、関数の `name`、`arguments`、`status` などのフィールドを空のまま残していました。現在は履歴からキャッシュされたツール呼び出しフィールドをすべて復元し、その呼び出しを Chat 上流向けに正しく再構築できるようにします。（[#4160](https://github.com/farion1231/cc-switch/pull/4160)）
+
+### config.toml 内の重複した Codex base_url 項
+
+Codex の `base_url` を `config.toml` へ書き込むとき、以前は各セクションで一致する代入を 1 つだけ置換または削除していたため、すでに複数行の `base_url` を含むセクションでは余分な項が残り、重複が累積していました。`setCodexBaseUrl` は現在、対象セクションまたはトップレベルの一致をすべて折りたたみ（最初の 1 つを置換し、残りを削除）、TOML の `base_url` 正規表現もエスケープされた引用符を処理します。（[#4316](https://github.com/farion1231/cc-switch/pull/4316)）
+
+### 履歴移行が CODEX_SQLITE_HOME の状態 DB をプローブ
+
+Codex セッション履歴の移行は、以前 `~/.codex/state_5.sqlite` と `config.toml` の `sqlite_home` の場所だけをスキャンしていたため、Codex の SQLite 状態が `CODEX_SQLITE_HOME` 環境変数で再配置されたとき、状態 DB は一度もスキャンされず、その threads は古いプロバイダーバケットに残ったままでした。サードパーティ移行と統一セッション移行の両方が共有する `codex_state_db_paths` ヘルパーが、現在は `CODEX_SQLITE_HOME` へフォールバックします（`config` 内の `sqlite_home` は引き続き優先）。
+
+### プロバイダーターミナルがユーザーの shell を尊重
+
+macOS / Linux でプロバイダーターミナルを起動するとき、以前は `bash` をハードコードしていたため、zsh / fish ユーザーの rc ファイルが読み込まれませんでした。ランチャーは現在、`$SHELL` からユーザーの既定 shell を検出し（macOS は `/bin/zsh`、Linux は `/bin/bash` へフォールバック）、クリーンスタートのフラグ付きで exec します。一方、起動スクリプト自体は移植性のために POSIX `sh` を使うようにしました（fish や、`/bin/sh` が存在しないことのある NixOS など）。（[#4140](https://github.com/farion1231/cc-switch/pull/4140)、[#1546](https://github.com/farion1231/cc-switch/issues/1546) を修正）
+
+### Claude MCP のパスがカスタム設定ディレクトリを尊重
+
+カスタムの Claude 設定ディレクトリが設定されているとき、MCP server の読み書きが、既定の場所ではなくそのディレクトリ配下の MCP ファイルへ解決されるようになり、MCP の状態が profile ごとに分離されます。旧ファイルに対する以前の「アクセス時コピー」移行は削除し、オーバーライドパスへ直接解決するようにしました。（[#3431](https://github.com/farion1231/cc-switch/pull/3431)）
+
+### 検索後にプリセット結果をクリック可能に
+
+「プロバイダーを追加」のプリセットセレクタで検索した後、結果がクリックも選択もできなくなることがありました。入力と競合して先頭文字を飲み込んでいた（「gateway」→「ateway」など）`requestAnimationFrame` の `select()` を削除し、すぐクリックできる経路の入力オートフォーカスを復元し、検索ボックスが開いているときに Ctrl/Cmd+F を押せば再フォーカスするようにもしました。プロバイダーリストのタイピングガードも Ctrl/Cmd+F 分岐に絞り込み、Escape で引き続き検索パネルを閉じられるようにしました。（[#4315](https://github.com/farion1231/cc-switch/pull/4315)）
+
+### Skills ブラウズとプロバイダーカードの表示修正
+
+いくつかの表示とインタラクションの問題を修正しました: skills.sh をブラウズ中もリポジトリ管理操作が引き続き使え、リポジトリが空の結果を返したときも更新が引き続き使え、プロバイダーカード上の長すぎるプロバイダー名やウェブサイト URL があふれずに切り詰められ、OMO のモデル変種ドロップダウンが選択ラベルを切り詰めて完全な内容をツールチップで示し、Select のメニュー項目が現在選択中の項目にチェックマークを表示します。（[#4323](https://github.com/farion1231/cc-switch/pull/4323)）
+
+### 設定タブ切り替え時のスクロールリセット
+
+設定ダイアログ内でタブを切り替えると前のタブのスクロール位置が引き継がれ、新しいタブの途中で止まることがありました。現在はアクティブなタブが変わるたびに、スクロールコンテナがトップへリセットされます。（[#4165](https://github.com/farion1231/cc-switch/pull/4165)）
+
+---
+
+## ドキュメント
+
+### Kimi ピン留めスポンサーバナー
+
+4 言語すべての README（en / zh / ja / de）の冒頭のピン留めスポンサーバナーが、これまでの MiniMax M2.7 バナーに代わって Kimi K2.7 Code になりました。文言は K2.7 Code のリリース（コーディング向けの agentic モデルで、思考 token の使用量が K2.6 比で約 30% 低減）を反映し、バナーは Moonshot CDN ではなくリポジトリ内のリソース（`assets/partners/banners/kimi-banner-en.png` / `kimi-banner-zh.png`）から提供し、`aff=cc-switch` の Moonshot コンソールを指すクリック可能な行動喚起を添えました。
+
+### Codex 統一セッション履歴ガイド
+
+3 言語（zh / en / ja）のガイドを新設し、Codex 統一セッション履歴トグルの有効化時の移行（有効化時）と台帳に基づく復元（無効化時）が実際に何をするのか、なぜセッションデータが本当に削除されないのか（マーカーの変更 + 自動バックアップのみ）、そしてファイルが本当にディスク上にあるのか、それとも別のプロバイダードロワーに分類されただけなのかを照合する方法を解説しました。「セッションが消えた」という、よくある誤解に対する症状の対照表と、macOS / Linux / Windows のディスク照合コマンドを含み、v3.16.3 の「利用ガイド」release notes の冒頭項としてリンクしました。
+
+### Homebrew インストール手順の簡素化
+
+インストールガイドが、`brew install --cask cc-switch` の前に `brew tap farion1231/ccswitch` を実行するようユーザーに求めなくなりました。この廃止された tap 手順を en / ja / zh のユーザーマニュアルから削除し、cask を直接インストールできるようにしました。（[#4319](https://github.com/farion1231/cc-switch/pull/4319)）
+
+### Star-History 世界ランキングバッジ
+
+4 言語すべての README で、既存の Trendshift バッジの隣に star-history の世界ランキングバッジを新設し、ライト / ダークテーマの変種を付けました。
+
+### 火山方舟 Coding Plan キャンペーンリンク
+
+ByteDance / 火山方舟スポンサー項目内の「中国本土の開発者はこちらをクリック」リンクが、これまでの `codingplan` 紹介 URL に代わって火山の `ai618` キャンペーンページを指すようになり、4 言語すべての README をカバーします。
+
+### CCSub スポンサーバナーのベクター素材
+
+低解像度の `ccsub.jpg` スポンサーロゴをベクターの `ccsub.svg` へ置き換え、2046x648 のレターボックスから 2046x850（約 2.406:1）へ拡げ、他のスポンサー表バナーと揃えて同じ 62px の高さで描画されるようにしました。4 言語すべての README が新しい素材を指します。
+
+---
+
+## アップグレード時の注意
+
+### 国産 Codex プロバイダーのネイティブ Responses 移行
+
+本リリースは、ネイティブ Responses endpoint を備える複数の国産プロバイダー（千問 / 百炼、小米 MiMo、火山 Doubao、美団 LongCat、MiniMax 国内 / 国際）の Codex プリセットを `openai_responses` へ切り替え、`modelCatalog` を削除しました。すでにこれらのプリセットをもとに設定済みの既存プロバイダーは影響を受けず、設定はそのまま保たれます。ネイティブ Responses（形式変換テイクオーバーを省く）へ切り替えたい場合は、プリセットからもう一度選び直して保存してください。SiliconFlow がホストする MiniMax は引き続き `openai_chat` を使い、今回の移行の対象外です。
+
+### データベースのバージョンが新しすぎる場合の復旧
+
+より高いバージョンの CC Switch でデータベースを開いた後、旧版へ戻した場合、旧版は起動時に新しい「データベースのバージョンが新しすぎる」リカバリ画面に入り、そのデータベースを読めるバージョンへのアップグレードへ案内します。これは期待される動作です——最新版へアップグレードすれば正常に戻ります。
+
+---
+
+## リスク通知
+
+本リリースは、リバースプロキシ系機能に関する以前のリスク通知を引き続き適用します。
+
+**Codex OAuth リバースプロキシ**: ChatGPT サブスクリプションの Codex OAuth をリバースプロキシ経由で使用すると、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 release notes](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
+
+**Codex サードパーティプロバイダー Chat ルーティング**: CC Switch ローカルプロキシで Codex リクエストを変換し、サードパーティプロバイダーへ転送する場合、課金・コンプライアンス・データ保持に関する制約はプロバイダーごとに異なります。利用前に対象プロバイダーの利用規約を確認してください。
+
+**Claude Desktop サードパーティプロバイダープロキシ切り替え**: CC Switch 内蔵のプロキシゲートウェイで Claude Desktop のリクエストをサードパーティプロバイダーへ転送する場合も、対象プロバイダーの課金・コンプライアンス・データ保持に関する規約に従う必要があります。
+
+上記機能を有効化したユーザーは、関連するリスクを自ら負うものとします。CC Switch は、これらの機能の利用によって発生したアカウント制限、警告、サービス停止について責任を負いません。
+
+---
+
+## 謝辞
+
+v3.16.4 で機能と修正を届けてくださった以下のコントリビューターに感謝します：
+
+- [#3817](https://github.com/farion1231/cc-switch/pull/3817): 転送前にリクエストボディを展開し zstd に対応、@chenx-dust に感謝。
+- [#4583](https://github.com/farion1231/cc-switch/pull/4583): Copilot / Codex OAuth モジュールがグローバルプロキシをバイパスし Claude モデルが 400 になる問題を修正、@zymouse に感謝。
+- [#4589](https://github.com/farion1231/cc-switch/pull/4589): ローカルプロキシのリクエストオーバーライド（カスタムリクエストヘッダーとリクエストボディ）を追加、@mfzzf に感謝。
+- [#4575](https://github.com/farion1231/cc-switch/pull/4575): データベースのバージョンが新しすぎる場合のアプリ内リカバリ画面を追加、@SaladDay に感謝。
+- [#4556](https://github.com/farion1231/cc-switch/pull/4556): 複数箇所の JsonEditor にダークモードを導入、@TanKimzeg に感謝。
+- [#4438](https://github.com/farion1231/cc-switch/pull/4438): カスタム日付範囲のリアルタイム終了時刻を追加、@arichyx に感謝。
+- [#3950](https://github.com/farion1231/cc-switch/pull/3950): Windows ARM64 リリースのサポートを追加、@MOON-DREAM-STARS に感謝。
+- [#4401](https://github.com/farion1231/cc-switch/pull/4401): Kimi For Coding プリセットに CLAUDE_CODE_AUTO_COMPACT_WINDOW を追加、@cyijun に感謝。
+- [#4323](https://github.com/farion1231/cc-switch/pull/4323): Skills 管理とモデル設定のインタラクション表示を修正、@thisTom に感謝。
+- [#3431](https://github.com/farion1231/cc-switch/pull/3431): カスタム設定ディレクトリの Claude MCP パスを揃える、@makoMakoGo に感謝。
+- [#4159](https://github.com/farion1231/cc-switch/pull/4159): 関数名を欠く Chat ツール呼び出しをスキップ、@hueifeng に感謝。
+- [#4385](https://github.com/farion1231/cc-switch/pull/4385): glm-5.2 の価格を追加、@arichyx に感謝。
+- [#4079](https://github.com/farion1231/cc-switch/pull/4079): models.dev からのモデル価格インポートに対応、@kingcanfish に感謝。
+- [#4315](https://github.com/farion1231/cc-switch/pull/4315): プリセット検索後に結果をクリック選択できない問題を修正、@RuixeWolf に感謝。
+- [#4316](https://github.com/farion1231/cc-switch/pull/4316): 重複した Codex base_url 項を防止、@jeffwcx に感謝。
+- [#4140](https://github.com/farion1231/cc-switch/pull/4140): プロバイダーターミナルがユーザーの shell を尊重するように、@zkforge に感謝。
+- [#4113](https://github.com/farion1231/cc-switch/pull/4113): セッション詳細ヘッダーにソースファイル名を表示、@xu-song に感謝。
+- [#4160](https://github.com/farion1231/cc-switch/pull/4160): Codex のキャッシュされたツール呼び出しフィールドを復元、@chen-985211 に感謝。
+- [#4239](https://github.com/farion1231/cc-switch/pull/4239): DeepSeek endpoint で thinking:disabled のとき effort パラメータを剥がす、@maskshell に感謝。
+- [#4165](https://github.com/farion1231/cc-switch/pull/4165): 設定タブ切り替え時にスクロールをリセット、@Muleizhang に感謝。
+- [#4319](https://github.com/farion1231/cc-switch/pull/4319): 廃止された Homebrew tap 手順を削除、@tianpeng-dev に感謝。
+- [#4522](https://github.com/farion1231/cc-switch/pull/4522): SubRouter プロバイダープリセットを追加、@abingyyds に感謝。
+
+v3.16.3 リリース後に Codex プロキシ経路、使用量の課金、ローカルプロキシの堅牢性、プラットフォーム互換性の問題を報告してくださったすべてのユーザーにも感謝します。今回の多くのパッチは、こうした実際の利用シーンから得られた再現の手がかりに基づいています。
+
+---
+
+## ダウンロードとインストール
+
+[Releases](https://github.com/farion1231/cc-switch/releases/latest) から、お使いのシステムに対応するビルドをダウンロードしてください。
+
+### システム要件
+
+| システム | 最低バージョン           | アーキテクチャ                      |
+| -------- | ------------------------ | ----------------------------------- |
+| Windows  | Windows 10 以降          | x64 / ARM64                         |
+| macOS    | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
+| Linux    | 下表を参照               | x64 / ARM64                         |
+
+### Windows
+
+| ファイル                                 | 説明                                         |
+| ---------------------------------------- | -------------------------------------------- |
+| `CC-Switch-v3.16.4-Windows.msi`          | **推奨** - 自動更新対応の MSI インストーラー |
+| `CC-Switch-v3.16.4-Windows-Portable.zip` | ポータブル版、展開してそのまま実行できます   |
+
+Windows ARM64 デバイスをお使いの場合は、ファイル名に `arm64` 識別子が含まれる対応する制品を選択してください。
+
+### macOS
+
+| ファイル                         | 説明                                                   |
+| -------------------------------- | ------------------------------------------------------ |
+| `CC-Switch-v3.16.4-macOS.dmg`    | **推奨** - DMG インストーラー、Applications へドラッグ |
+| `CC-Switch-v3.16.4-macOS.zip`    | 展開して Applications へドラッグ、Universal Binary      |
+| `CC-Switch-v3.16.4-macOS.tar.gz` | Homebrew インストールと自動更新用                      |
+
+Homebrew インストール：
+
+```bash
+brew install --cask cc-switch
+```
+
+更新：
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+Linux アセットは **x86_64** と **ARM64**（`aarch64`）の両方を提供します。ファイル名にアーキテクチャ識別子が含まれているため、マシンの `uname -m` 出力に合わせて選択してください：
+
+- `CC-Switch-v3.16.4-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.16.4-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| ディストリビューション                  | 推奨形式    | インストール方法                                                          |
+| --------------------------------------- | ----------- | ------------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` または `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` または `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                   |
+| Arch Linux / Manjaro                    | `.AppImage` | 実行権限を付与して直接起動、または AUR を使用                             |
+| その他 / 不明                           | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`                 |
+</content>
+</invoke>
@@ -0,0 +1,354 @@
+# CC Switch v3.16.4
+
+> 🎉 **CC Switch 跻身 GitHub 全球 Star 排行榜前 100！**
+> 感谢每一位用户、贡献者与 Star —— 是你们让它走到这里。🙏
+
+> 继 v3.16.3 把「用量计费做准」之后，这一版把重心放在打磨 Codex 代理链路与丰富用量 / 定价工具上——国产供应商原生 Responses 迁移、上游格式选择器与模型映射解耦、zstd 请求 / 错误体解压，以及一批工具调用与 OAuth 走代理的修复；同时新增本地代理请求覆盖、数据库版本过新时的应用内恢复屏、原生 Windows ARM64 构建，并带来一波预设与品牌更新（SubRouter、OpenCode Go、CTok→ETok 改名、Kimi 品牌刷新与 prime-partner 徽标）。
+
+**[English →](v3.16.4-en.md) | [日本語版 →](v3.16.4-ja.md)**
+
+---
+
+## 使用攻略
+
+本版以打磨与扩展为主，新增的能力主要落在用量面板与供应商表单的高级选项里，建议结合以下文档了解：
+
+- **[Codex 桌面看不到自定义模型？](../guides/codex-desktop-custom-model-visibility-zh.md)**：不少用户反馈在 Codex 桌面应用里看不到配置的第三方 / 自定义模型。这是 Codex 桌面应用**上游自身的门控行为**（按官方登录状态放行模型选择器），并非 CC Switch 的本地配置问题，**本版（v3.16.4）未对此做改动**；文档里说明了原因，以及可用的缓解办法（保留官方登录 + 路由接管）。
+- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：了解用量看板的数据来源与统计口径。本版新增了从 models.dev 批量导入模型定价、火山方舟 Coding / Agent Plan 的 AK/SK 用量查询，以及自定义日期范围的「实时结束时间」。
+- **[设置](../user-manual/zh/1-getting-started/1.5-settings.md)**：本地代理请求覆盖（自定义请求头 / 请求体）、Codex 上游格式选择器与本地路由开关等都在供应商表单的高级选项里。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一官方渠道声明（请务必阅读）
+>
+> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。请仅通过下列官方渠道获取本软件：
+>
+> | 类别     | 唯一官方                                                                       |
+> | -------- | ------------------------------------------------------------------------------ |
+> | 官网     | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | 源码     | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | 下载     | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者     | **[@farion1231](https://github.com/farion1231)**                               |
+> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。
+
+---
+
+## 概览
+
+CC Switch v3.16.4 是 v3.16.3 之后的一版维护更新。这一版围绕 Codex 代理链路做了一轮收紧——为多家具备原生 OpenAI Responses 端点的国产供应商切换到原生格式（省去 Responses→Chat 的路由接管转换）、把「上游格式」从「本地路由」开关里独立出来、补上 zstd 请求与错误响应体的解压，并修了一串工具调用与「OAuth 模块绕过全局代理」的问题。
+
+与此同时，本版还丰富了用量与定价工具（从 models.dev 导入定价、火山方舟 Coding / Agent Plan 的 AK/SK 用量查询、自定义日期范围的实时结束时间、GLM-5.2 与豆包 Seed 2.1 定价），新增了一批代理与韧性能力（自定义请求头 / 请求体覆盖、数据库版本过新时的应用内恢复屏、原生 Windows ARM64 构建），并带来一波预设与品牌更新（SubRouter 与 OpenCode Go 订阅、CTok→ETok 改名、Kimi 品牌刷新与 prime-partner 徽标、Kimi K2.7 Code 赞助横幅）。
+
+**发布日期**：2026-06-27
+
+**更新规模**：53 commits | 126 files changed | +8,149 / -1,016 lines
+
+---
+
+## 重点内容
+
+- **国产 Codex 供应商走原生 Responses**：千问 / 百炼、小米 MiMo、火山豆包、美团 LongCat、MiniMax（国内 / 国际）现在直连各自的原生 Responses 端点，不再经过 Responses→Chat 的格式转换接管，链路更短、更稳。
+- **本地代理请求覆盖**：供应商可配置自定义请求头与请求体覆盖，由本地代理在转发时应用，并对受保护的安全请求头做了拦截校验。
+- **数据库版本过新的应用内恢复屏**：当 SQLite 版本比当前应用支持的更新时，不再死在「重试只会再次失败」的原生弹窗里，而是引导到一个可一键升级应用的恢复界面。
+- **更丰富的用量 / 定价工具**：从 models.dev 批量导入模型定价、火山方舟 Coding / Agent Plan 的 AK/SK 用量查询、自定义日期范围的「实时结束时间」，以及 GLM-5.2 与豆包 Seed 2.1 的定价。
+- **新预设与品牌更新**：新增 SubRouter 与 OpenCode Go 订阅预设，CTok 改名为 ETok，刷新 Kimi 品牌标识并为官方 Kimi 预设加上 prime-partner 心形徽标。
+- **原生 Windows ARM64 构建**：发布产物新增原生 ARM64 版本，ARM 架构的 Windows 设备不再依赖 x64 模拟。
+
+---
+
+## 新功能
+
+### 数据库版本过新时的应用内恢复屏
+
+当 SQLite 的 `user_version` 比当前应用支持的 `SCHEMA_VERSION` 更新时（例如降级回旧版、或被第三方客户端写过该文件），启动过去会死在一个原生的「重试 / 退出」弹窗里——而「重试」只会再次失败。现在应用会引导到一个专门的恢复界面：有可用更新时提供一键「升级应用」按钮（下载 + 安装 + 重启，带进度条），没有可用更新时则提示即便是最新版也读不了这个数据库。该「版本过新」检查在任何写库动作之前进行，因此应用永远不会对一个读不懂的数据库执行 DDL；恢复模式下的原生关闭会干净退出（此时托盘尚未创建）。（[#4575](https://github.com/farion1231/cc-switch/pull/4575)）
+
+### 本地代理请求覆盖（自定义请求头与请求体）
+
+供应商配置现在可以定义自定义请求头与请求体覆盖，由本地代理在转发时应用，并通过 Claude 与 Codex 供应商表单里的新字段暴露。输入会经过校验，其中包含一份受保护的请求头名单，用于阻止覆盖安全敏感的请求头。（[#4589](https://github.com/farion1231/cc-switch/pull/4589)）
+
+### 火山方舟 Coding / Agent Plan 用量查询
+
+用量面板现在可以查询火山方舟（Volcengine Ark）的 Coding Plan 与 Agent Plan 配额。由于方舟控制面 OpenAPI（`open.volcengineapi.com`）要求的是账号级 AccessKey 签名、而非推理 API key，用量脚本新增了独立的 AK/SK 输入区，并配有一个直达火山 IAM 密钥管理控制台（`https://console.volcengine.com/iam/keymanage`）的可点击链接；代理实现了火山签名 V4（一个 AWS SigV4 变体：固定的 canonical header 顺序、`HMAC-SHA256` 算法、`ark` 服务 scope）。它会先探测 `GetAFPUsage`（Agent Plan 的 5 小时 / 周 / 月配额）自动判定套餐，失败再回退到 `GetCodingPlanUsage`，从 `Level` 字段解析窗口标签（并对 `ResetTimestamp <= 0` 做守卫），同时在用量页脚、托盘菜单与四种语言里补上了 `monthly` 档标签。
+
+### 从 models.dev 导入模型定价
+
+「添加定价」面板新增了一个「从 models.dev 导入」按钮：拉取 `https://models.dev/api.json`，支持全文搜索整个目录，并通过与手动录入相同的 `update_model_pricing` 路径导入所选条目。导入的 model id 会按后端的 `clean_model_id_for_pricing` 规则归一化（剥供应商前缀、转小写、截断 `:` 后缀、把 `@` 映射为 `-`、丢掉 `[1m]` 标记），让落库的行真正能匹配成本归因查询。配套修复让「按范围回填零成本」改用 Rust 端按原始 model 别名（路由前缀、`:free` 变体、日期后缀）匹配，而不再用精确 SQL 字符串匹配，从而新定价的别名行能立刻被计价、而不必等下次启动回填（修复 [#4017](https://github.com/farion1231/cc-switch/issues/4017)）。（[#4079](https://github.com/farion1231/cc-switch/pull/4079)）
+
+### 原生 Windows ARM64 构建
+
+发布产物现在包含原生的 Windows ARM64 制品，ARM 架构的 Windows 设备可以拿到对应的原生构建，不必再依赖 x64 模拟。发布矩阵也改为各平台独立运行（关闭 fail-fast），因此某个任务缺少密钥而失败（例如 fork 里的 macOS 签名）不会再把尚未完成的同级任务一并取消。（[#3950](https://github.com/farion1231/cc-switch/pull/3950)）
+
+### 自定义日期范围的实时结束时间
+
+自定义日期范围选择器新增了一个「结束时间跟随当前时间」勾选框；开启后结束时间变为只读并自动跟随此刻，因此用量数据始终反映从所选起点到当下的实时消耗。这在 Coding Plan 的 5 小时配额窗口里尤其有用。`liveEndTime` 已纳入 React Query 的缓存键，因此一个实时范围和一个端点相同的固定范围不会再共用同一个陈旧缓存项。（[#4438](https://github.com/farion1231/cc-switch/pull/4438)）
+
+### 会话详情头显示源文件名
+
+会话详情头现在会在项目目录旁显示会话日志的文件名（悬停看完整路径、可点击复制），方便用户直接从界面定位并打开底层的 JSONL 文件。对于像 ~70 字符的 Codex rollout 这类没有空格的长文件名，会截断到 `max-w-[200px]`，避免在窄窗口里溢出到操作按钮区。（[#4113](https://github.com/farion1231/cc-switch/pull/4113)）
+
+### 导入按钮的未托管 Skill 提示
+
+顶栏的 Skills 导入按钮现在会在本地存在未托管的 Skill 可导入时显示一个绿点与提示，让你一眼看出磁盘上的 Skill 还没被纳管。该扫描在挂载时执行一次，并在多次导航间共享（30s `staleTime` + `keepPreviousData`），避免重复磁盘 IO。
+
+### OpenCode Go 订阅预设
+
+新增 OpenCode Go（`opencode.ai/zen/go`）预设，覆盖 Claude、Codex 与 OpenCode，使用可直接粘贴的纯 API key（无 OAuth）。Codex 预设走 `openai_chat` 转换并带 GLM / Kimi / DeepSeek / MiMo 模型目录（且不带静态 `codexChatReasoning`，按每个模型推断能力），OpenCode 则通过 `@ai-sdk/openai-compatible` 指向 `/zen/go/v1`。四个 OpenCode Go 预设——Claude、Claude Desktop、Codex、OpenCode——都带上了推荐链接与应用内推广文案；推广横幅现在仅凭 `partnerPromotionKey` 即可展示（不再绑定 `isPartner`），因此一个预设可以展示推荐推广却不获得金色付费合作伙伴星标（这也顺带让既有的 MiniMax 推广重新显示出来）。
+
+### Prime-Partner 预设徽标与排序
+
+第一方 Moonshot Kimi 预设（Kimi / Kimi For Coding / Kimi K2.7 Code）现在被标记为 prime partner：不再显示金色星标，而是渲染一颗实心金色心形（无徽标边框），并在默认（Original）排序里浮到官方分类预设之后、其余之前。分组用三路 partition 实现，每组保持内部顺序，且一个同时被标为 prime-partner 的官方预设只会留在官方组里。
+
+### GLM-5.2 与豆包 Seed 2.1 定价
+
+种子模型定价现在包含 GLM-5.2（[#4385](https://github.com/farion1231/cc-switch/pull/4385)）与豆包 Seed 2.1 Pro / Turbo，让这些模型的用量被正确计价、而不是记成零成本。豆包价格采用火山官方 list 价（按约 7.14 的汇率折算）；`cache_creation` 保持为 0，因为豆包按时间而非按 token 写入计费缓存存储，既有的 2.0 行也保留以供历史记账。
+
+### Kimi For Coding 自动压缩窗口
+
+Kimi For Coding 预设现在把 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 默认设为 262144，与 Kimi 官方文档一致，并通过 `templateValues` 暴露，方便用户为将来的模型或性能调优自定义该值。（[#4401](https://github.com/farion1231/cc-switch/pull/4401)）
+
+### SubRouter 合作伙伴供应商
+
+新增 SubRouter（`subrouter.ai`，一个让一把 key 访问多模型多供应商的 AI 中转聚合商）作为预设，覆盖全部 7 个受管应用——Anthropic 格式端点用于 Claude Code / Claude Desktop / OpenClaw / Hermes，OpenAI 兼容的 `/v1` 端点（`gpt-5.5`）用于 Codex 与 OpenCode，Gemini 兼容的 `/v1beta` 端点（`gemini-3.5-flash`）用于 Gemini CLI——带上自有品牌图标、金色合作伙伴星标、四语推广文案，以及预填为 API key 注册地址的推荐注册链接（`?aff=l3ri`）。（[#4522](https://github.com/farion1231/cc-switch/pull/4522)）
+
+---
+
+## 变更
+
+### 国产 Codex 供应商走原生 Responses API
+
+多家国产供应商（千问 / DashScope 百炼、小米 MiMo、火山豆包、美团 LongCat、MiniMax 国内 / 国际）现在暴露了原生的 OpenAI Responses 端点，因此它们的 Codex 预设切换到 `apiFormat: "openai_responses"`，直连上游而不再经过 Responses→Chat 的路由接管转换。丢掉不再需要的 `codexChatReasoning` 与 `modelCatalog` 也让「本地路由映射」开关默认保持未勾选。SiliconFlow 托管的 MiniMax 仍保持 `openai_chat`，因为那是第三方端点、并非 MiniMax 自家 base_url。其余仍走 chat 的供应商也刷新了过期的 model id（GLM 5.1→5.2、StepFun 3.5-flash-2603→3.7-flash、Ling 2.5-1T→2.6-1T）。
+
+### 上游格式选择器与模型映射开关解耦
+
+Codex 供应商表单此前把 Chat 格式转换与路由接管（模型映射）绑在同一个开关上，导致一个提供原生 Responses API 的供应商无法在不强制 Chat Completions 转换的情况下使用模型映射。现在「上游格式」（Chat Completions / Responses）成了一个独立、始终可见的选择器，而本地路由开关只负责控制高级子区（模型映射目录，以及格式为 Chat 时的推理能力）。它的初始状态由已保存目录是否存在派生，不新增持久化字段；`codexConfig` 的四语（zh / en / ja / zh-TW）文案也随之重写。
+
+### 豆包 Seed 2.1 Pro 预设
+
+DouBaoSeed 预设现在在全部 6 个客户端（claude、claude-desktop、codex、opencode、openclaw、hermes）指向 `doubao-seed-2-1-pro`（替换 `doubao-seed-2-0-code-preview-latest`），展示名更新为「Doubao Seed 2.1 Pro」，并把 OpenClaw 的成本字段从 0.002 / 0.006 订正为 0.84 / 4.2 美元每百万 token 以匹配新模型。
+
+### CTok 改名为 ETok
+
+随着厂商对域名、端点与商标的更名，所有面向用户的品牌从 CTok 迁移到 ETok（`ctok.ai`→`etok.ai`、`api.ctok.ai`→`api.etok.ai`，以及内部 id、展示名、图标和 README 合作伙伴横幅），覆盖每一个客户端预设。Codex 历史迁移白名单里仍保留 `ctok` 作为旧 id、与新 `etok` 并存，以保证改名后存量用户的本地会话历史仍被正确分桶。
+
+### Kimi 预设命名统一
+
+OpenCode 与 OpenClaw 此前被标为「Kimi K2.7 Code」的 Kimi 预设，更名为与其它应用一致的「Kimi」（OpenCode 的供应商展示名也一并更名）；模型标签仍保留「Kimi K2.7 Code」，因为它描述的是实际模型。
+
+### JSON 编辑器暗色模式
+
+用量脚本弹窗、供应商表单与通用供应商表单里的 CodeMirror `JsonEditor` 现在会通过 `useDarkMode()` 跟随应用主题，切换到 `oneDark` 编辑器主题，而不再在应用其余部分已是暗色时仍停留在亮色。（[#4556](https://github.com/farion1231/cc-switch/pull/4556)）
+
+### 更紧凑的「添加供应商」标题与底部提示
+
+「添加供应商」对话框把标题到页签、页签到卡片的纵向间距从 24px 收到 12px，并新增一个始终可见的固定底部提示，引导用户在选好预设后填写下方字段。`FullScreenPanel` 新增可选的 `contentClassName` 属性，让内边距覆盖只作用于此面板、不影响其它共用它的面板。
+
+### 主题自适应的 Kimi 标识
+
+内联的 Kimi 占位标记替换为厂商刷新后的标识。K 字形使用 `currentColor`，因此会跟随主题文字色（亮色模式深、暗色模式白），而品牌点缀色固定为新的 `#1783FF`，元数据回退色也相应对齐。
+
+### 移除 Fable 5 Verified 纪念横幅
+
+设置「关于」页不再显示 3.16.3 为标明特别构建而加在应用名旁的 Fable 5 Verified 纪念横幅；横幅图片及其标记被移除，「关于」面板回到标准的版本徽标布局。
+
+---
+
+## 修复
+
+### Copilot / Codex OAuth 请求现在遵循全局代理
+
+`CopilotAuthManager` 与 `CodexOAuthManager` 在构造时写死了 `Client::new()`，导致它们的认证流程（换 token、拉 `/models` 列表、判定 model vendor、device-code 与 OAuth 刷新请求）无视配置的全局代理、直连目标服务。在 Copilot 上，直连会让 `/models` 返回 0 个 Claude 模型，使 live 模型解析失效，上游以 `400 model_not_supported` 拒绝请求。现在两个 manager 都改为每次请求从共享客户端现取（`crate::proxy::http_client::get()`），从而遵循全局代理 URL 并支持运行时热更新。修复 [#2016](https://github.com/farion1231/cc-switch/issues/2016)、[#2931](https://github.com/farion1231/cc-switch/issues/2931)。（[#4583](https://github.com/farion1231/cc-switch/pull/4583)）
+
+### 压缩请求体与错误体的解压
+
+Codex Desktop 在对 Codex 后端认证时会发送 zstd 压缩的请求体，这会破坏本地代理路由，因为处理器直接用 `serde_json` 解析原始压缩字节。代理现在会在 JSON 解析前对请求体解压（gzip / br / deflate，外加新增的 zstd 支持，包括 `gzip, zstd` 这类堆叠编码），覆盖三个 Codex 处理器，并剥掉过期的 `content-encoding` / `content-length` / `transfer-encoding` 请求头让转发器重新生成。上游非 2xx 的错误体也以同样方式解压，因此压缩过的限流与鉴权细节不再被丢弃、对客户端隐藏。修复 [#3764](https://github.com/farion1231/cc-switch/issues/3764)、[#3696](https://github.com/farion1231/cc-switch/issues/3696)。（[#3817](https://github.com/farion1231/cc-switch/pull/3817)）
+
+### DeepSeek 端点 `thinking: disabled` 的 400 错误
+
+DeepSeek 的 Anthropic 兼容端点会拒绝 `thinking.type=disabled` 与 effort 参数共存的请求、返回 HTTP 400，这会破坏 Claude Code 2.1.166+ 那些硬编码 `thinking: disabled` 的子 agent（Workflow / Dynamic Workflow）。代理现在不是去覆盖客户端的意图，而是对官方 DeepSeek 端点剥掉冲突的 `output_config.effort` / `reasoning_effort` 参数，因为子 agent 本就不需要展示推理。（[#4239](https://github.com/farion1231/cc-switch/pull/4239)）
+
+### 回滚 Anthropic system 消息上提
+
+回滚了 [#3775](https://github.com/farion1231/cc-switch/pull/3775) 把 Anthropic 兼容供应商的 `role=system` 消息从 `messages[]` 上提到顶层 `system` 字段的改动。DeepSeek 端点本就原生接受内联的 system 消息，而该重写改变了请求前缀；保持消息原位能保留 prompt 前缀，避免一处疑似的缓存命中率回退（参见 [#4297](https://github.com/farion1231/cc-switch/issues/4297)）。来自 #3775 的、不相关的 Windows 测试修复以及 tool-thinking-history 归一化都保留。
+
+### Chat 工具调用缺函数名
+
+一些上游会在流式工具调用增量里发送空的或缺失的函数名，过去这会产生无效的 Codex Chat 输出项（或一个 `unknown_tool` 回退）。现在累积的工具调用状态不会再被空增量覆盖，而那些始终没拿到 `call_id` 与有效名字的工具调用会在最终化阶段被跳过，覆盖流式、非流式与旧版 `function_call` 三条路径。（[#4159](https://github.com/farion1231/cc-switch/pull/4159)）
+
+### 恢复 Codex 缓存的工具调用字段
+
+当 Codex 发起一个引用 `previous_response_id` 的后续 Chat 请求时，它的 `function_call` 项可能只携带 `call_id`。历史增强此前只回填 `reasoning` / `reasoning_content`，留空了函数的 `name`、`arguments`、`status` 等字段；现在它会从历史里恢复全部缓存的工具调用字段，让该调用能为 Chat 上游正确重建。（[#4160](https://github.com/farion1231/cc-switch/pull/4160)）
+
+### config.toml 里重复的 Codex base_url 条目
+
+把 Codex 的 `base_url` 写入 `config.toml` 时此前每个区段只替换或移除一个匹配的赋值，因此一个已经含多行 `base_url` 的区段会留下多余项、累积重复。`setCodexBaseUrl` 现在会折叠目标区段或顶层的所有匹配（替换第一处、移除其余），TOML 的 `base_url` 正则也处理了转义引号。（[#4316](https://github.com/farion1231/cc-switch/pull/4316)）
+
+### 历史迁移探测 CODEX_SQLITE_HOME 的状态库
+
+Codex 会话历史迁移此前只扫描 `~/.codex/state_5.sqlite` 与 `config.toml` 的 `sqlite_home` 位置，因此当 Codex 的 SQLite 状态通过 `CODEX_SQLITE_HOME` 环境变量被重定位时，状态库从未被扫描、其 threads 仍留在旧的供应商分桶里。第三方与统一会话两套迁移共用的 `codex_state_db_paths` 辅助函数现在会回退到 `CODEX_SQLITE_HOME`（`config` 里的 `sqlite_home` 仍优先）。
+
+### 供应商终端尊重用户 shell
+
+在 macOS / Linux 上启动供应商终端时此前硬编码了 `bash`，导致 zsh / fish 用户的 rc 文件不会加载。启动器现在会从 `$SHELL` 检测用户默认 shell（macOS 回退 `/bin/zsh`、Linux 回退 `/bin/bash`）并以干净启动的 flag exec 进去，而启动脚本本身改走 POSIX `sh` 以保证可移植性（例如 fish，以及 `/bin/sh` 可能不存在的 NixOS）。（[#4140](https://github.com/farion1231/cc-switch/pull/4140)，修复 [#1546](https://github.com/farion1231/cc-switch/issues/1546)）
+
+### Claude MCP 路径尊重自定义配置目录
+
+当配置了自定义的 Claude 配置目录时，MCP server 的读写现在会解析到该目录下的 MCP 文件、而非默认位置，让 MCP 状态按 profile 隔离。此前对旧文件的「访问即拷贝」迁移被移除，改为直接解析覆盖路径。（[#3431](https://github.com/farion1231/cc-switch/pull/3431)）
+
+### 搜索后预设结果可点击
+
+在「添加供应商」预设选择器里搜索后，结果一度无法点击或选中。那个与输入打架、会吃掉首字符（如「gateway」→「ateway」）的 `requestAnimationFrame` `select()` 被移除，开箱即点路径的输入自动聚焦被恢复，当搜索框已打开时按 Ctrl/Cmd+F 也接上了重新聚焦。供应商列表的打字守卫也被收窄到 Ctrl/Cmd+F 分支，从而 Escape 仍能关闭搜索面板。（[#4315](https://github.com/farion1231/cc-switch/pull/4315)）
+
+### Skills 浏览与供应商卡片显示修复
+
+修复了若干显示与交互问题：浏览 skills.sh 时仓库管理操作保持可用，仓库返回空结果时刷新也保持可用；供应商卡片上过长的供应商名与网站 URL 现在会截断而非溢出；OMO 模型变体下拉会截断所选标签并配全文提示；Select 菜单项会在当前选中项上显示对勾。（[#4323](https://github.com/farion1231/cc-switch/pull/4323)）
+
+### 切换设置页签时重置滚动
+
+在设置对话框里切换页签会保留上一个页签的滚动位置，有时会停在新页签的中途；现在每当激活页签变化时，滚动容器都会重置到顶部。（[#4165](https://github.com/farion1231/cc-switch/pull/4165)）
+
+---
+
+## 文档
+
+### Kimi 置顶赞助横幅
+
+全部四种 README 语言（en / zh / ja / de）顶部的置顶赞助横幅现在换成了 Kimi K2.7 Code，取代此前的 MiniMax M2.7 横幅。文案反映 K2.7 Code 发布（一个面向编程的 agentic 模型，思考 token 用量较 K2.6 降低约 30%），横幅改由仓库内资源（`assets/partners/banners/kimi-banner-en.png` / `kimi-banner-zh.png`）提供、不再走 Moonshot CDN，并附一个指向 `aff=cc-switch` Moonshot 控制台的可点击行动号召。
+
+### Codex 统一会话历史攻略
+
+新增三语（zh / en / ja）攻略，讲清统一 Codex 会话历史开关的开启迁移（启用时）与按账本还原（禁用时）到底做了什么、为什么会话数据从不会真正删除（只改标记 + 自动备份），以及如何核对文件是真在磁盘上、还是只是被归到了另一个供应商抽屉里。它包含一张针对常见「我的会话不见了」误解的症状对照表，以及 macOS / Linux / Windows 的磁盘核对命令，并作为首项链入 v3.16.3 的「使用攻略」release notes。
+
+### 简化 Homebrew 安装说明
+
+安装指南不再要求用户在 `brew install --cask cc-switch` 之前先运行 `brew tap farion1231/ccswitch`；这个已废弃的 tap 步骤已从 en / ja / zh 用户手册里移除，cask 现在可直接安装。（[#4319](https://github.com/farion1231/cc-switch/pull/4319)）
+
+### Star-History 全球排名徽标
+
+在全部四种 README 语言里、既有的 Trendshift 徽标旁新增了一个 star-history 全球排名徽标，并带亮 / 暗主题变体。
+
+### 火山方舟 Coding Plan 活动链接
+
+ByteDance / 火山方舟赞助条目里的「中国大陆地区的开发者请点击这里」链接现在指向火山的 `ai618` 活动页，取代此前的 `codingplan` 推荐 URL，覆盖全部四种 README 语言。
+
+### CCSub 赞助横幅矢量资源
+
+把低分辨率的 `ccsub.jpg` 赞助 logo 替换为矢量的 `ccsub.svg`，并从 2046x648 letterbox 到 2046x850（约 2.406:1），使其与其它赞助表横幅匹配、以相同的 62px 高度渲染。全部四种 README 语言都指向新资源。
+
+---
+
+## 升级提醒
+
+### 国产 Codex 供应商原生 Responses 迁移
+
+本版把多家具备原生 Responses 端点的国产供应商（千问 / 百炼、小米 MiMo、火山豆包、美团 LongCat、MiniMax 国内 / 国际）的 Codex 预设切换为 `openai_responses` 并移除了 `modelCatalog`。已经基于这些预设配置过的存量供应商不受影响、配置保持原样；如果你希望改用原生 Responses（省去格式转换接管），可以重新从预设选择一次并保存。SiliconFlow 托管的 MiniMax 仍走 `openai_chat`，不在此次迁移之列。
+
+### 数据库版本过新的恢复
+
+如果你曾用更高版本的 CC Switch 打开过数据库、再切回旧版，旧版启动时会进入新的「数据库版本过新」恢复屏，并引导你升级到能读懂该数据库的版本。这是预期行为——升级到最新版即可恢复正常。
+
+---
+
+## 风险提示
+
+本版本继续沿用此前版本对反向代理类功能的风险提示。
+
+**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
+
+**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
+
+**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，同样需要遵守目标供应商的计费、合规与数据留存约束。
+
+用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
+
+---
+
+## 致谢
+
+感谢以下贡献者在 v3.16.4 中提交的功能与修复：
+
+- [#3817](https://github.com/farion1231/cc-switch/pull/3817)：转发前解压请求体并支持 zstd，感谢 @chenx-dust。
+- [#4583](https://github.com/farion1231/cc-switch/pull/4583)：修复 Copilot / Codex OAuth 模块绕过全局代理导致 Claude 模型 400，感谢 @zymouse。
+- [#4589](https://github.com/farion1231/cc-switch/pull/4589)：新增本地代理请求覆盖（自定义请求头与请求体），感谢 @mfzzf。
+- [#4575](https://github.com/farion1231/cc-switch/pull/4575)：新增数据库版本过新时的应用内恢复屏，感谢 @SaladDay。
+- [#4556](https://github.com/farion1231/cc-switch/pull/4556)：为多处 JsonEditor 接入暗色模式，感谢 @TanKimzeg。
+- [#4438](https://github.com/farion1231/cc-switch/pull/4438)：新增自定义日期范围的实时结束时间，感谢 @arichyx。
+- [#3950](https://github.com/farion1231/cc-switch/pull/3950)：新增 Windows ARM64 发布支持，感谢 @MOON-DREAM-STARS。
+- [#4401](https://github.com/farion1231/cc-switch/pull/4401)：为 Kimi For Coding 预设添加 CLAUDE_CODE_AUTO_COMPACT_WINDOW，感谢 @cyijun。
+- [#4323](https://github.com/farion1231/cc-switch/pull/4323)：修复 Skills 管理与模型配置的交互展示，感谢 @thisTom。
+- [#3431](https://github.com/farion1231/cc-switch/pull/3431)：对齐自定义配置目录的 Claude MCP 路径，感谢 @makoMakoGo。
+- [#4159](https://github.com/farion1231/cc-switch/pull/4159)：跳过缺函数名的 Chat 工具调用，感谢 @hueifeng。
+- [#4385](https://github.com/farion1231/cc-switch/pull/4385)：新增 glm-5.2 定价，感谢 @arichyx。
+- [#4079](https://github.com/farion1231/cc-switch/pull/4079)：支持从 models.dev 导入模型定价，感谢 @kingcanfish。
+- [#4315](https://github.com/farion1231/cc-switch/pull/4315)：修复搜索预设后结果无法点击选中，感谢 @RuixeWolf。
+- [#4316](https://github.com/farion1231/cc-switch/pull/4316)：防止重复的 Codex base_url 条目，感谢 @jeffwcx。
+- [#4140](https://github.com/farion1231/cc-switch/pull/4140)：让供应商终端尊重用户 shell，感谢 @zkforge。
+- [#4113](https://github.com/farion1231/cc-switch/pull/4113)：在会话详情头显示源文件名，感谢 @xu-song。
+- [#4160](https://github.com/farion1231/cc-switch/pull/4160)：恢复 Codex 缓存的工具调用字段，感谢 @chen-985211。
+- [#4239](https://github.com/farion1231/cc-switch/pull/4239)：DeepSeek 端点 thinking:disabled 时剥掉 effort 参数，感谢 @maskshell。
+- [#4165](https://github.com/farion1231/cc-switch/pull/4165)：切换设置页签时重置滚动，感谢 @Muleizhang。
+- [#4319](https://github.com/farion1231/cc-switch/pull/4319)：移除已废弃的 Homebrew tap 步骤，感谢 @tianpeng-dev。
+- [#4522](https://github.com/farion1231/cc-switch/pull/4522)：新增 SubRouter 供应商预设，感谢 @abingyyds。
+
+也感谢所有在 v3.16.3 发布后反馈 Codex 代理链路、用量计费、本地代理稳健性与平台兼容性问题的用户，很多补丁都来自这些真实使用场景里的复现线索。
+
+---
+
+## 下载与安装
+
+访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
+
+### 系统要求
+
+| 系统    | 最低版本                   | 架构                                |
+| ------- | -------------------------- | ----------------------------------- |
+| Windows | Windows 10 及以上          | x64 / ARM64                         |
+| macOS   | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | 见下表                     | x64 / ARM64                         |
+
+### Windows
+
+| 文件                                     | 说明                                |
+| ---------------------------------------- | ----------------------------------- |
+| `CC-Switch-v3.16.4-Windows.msi`          | **推荐** - MSI 安装包，支持自动更新 |
+| `CC-Switch-v3.16.4-Windows-Portable.zip` | 便携版，解压即用，不写入注册表      |
+
+Windows ARM64 设备请选择文件名中带 `arm64` 标识的对应制品。
+
+### macOS
+
+| 文件                             | 说明                                          |
+| -------------------------------- | --------------------------------------------- |
+| `CC-Switch-v3.16.4-macOS.dmg`    | **推荐** - DMG 安装包，拖入 Applications 即可 |
+| `CC-Switch-v3.16.4-macOS.zip`    | 解压后拖入 Applications，Universal Binary     |
+| `CC-Switch-v3.16.4-macOS.tar.gz` | 用于 Homebrew 安装和自动更新                  |
+
+Homebrew 安装：
+
+```bash
+brew install --cask cc-switch
+```
+
+更新：
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本：
+
+- `CC-Switch-v3.16.4-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.16.4-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| 发行版                                  | 推荐格式    | 安装方式                                                               |
+| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                    | `.AppImage` | 添加执行权限后直接运行，或使用 AUR                                     |
+| 其他发行版 / 不确定                     | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |
@@ -0,0 +1,278 @@
+# CC Switch v3.16.5
+
+> The centerpiece of this release is **getting native-Responses direct-connect properly adapted for domestic (Chinese) model providers** — generating Codex model catalogs for providers with native Responses endpoints (Xiaomi MiMo, Volcengine Doubao, Qwen3-Coder, Meituan LongCat, MiniMax) so the Codex desktop app can actually see these models and their built-in tools work, and automatically disabling `web_search` for the few domestic gateways that reject it so requests are no longer hard-rejected. Two other important improvements: when you switch providers, the plugins, environment variables, etc. you added inside the app are **automatically written back to the common config and carried over to the next provider**; and Linux (Wayland + NVIDIA) users hitting the "title bar clicks, page is dead, black screen on resize" problem now have an environment-variable escape hatch. This release also brings Claude Sonnet 5 pricing and a default-tier bump, a two-level grouped session view, and a batch of credential-safety and platform-compatibility fixes.
+
+**[中文版 →](v3.16.5-zh.md) | [日本語版 →](v3.16.5-ja.md)**
+
+---
+
+## Usage Guides
+
+The new capabilities in this release land mainly in the Codex provider form, the session panel, and usage / common config. The following docs are worth reading alongside it:
+
+- **[Can't see custom models in the Codex desktop app?](../guides/codex-desktop-custom-model-visibility-en.md)**: this release reworks **model-catalog generation for native direct-connect** — when a Codex provider connects directly via native Responses (`openai_responses`), CC Switch generates `~/.codex/cc-switch-model-catalog.json` so the Codex desktop app can display the configured custom models and their tools work. If you previously configured a native Codex provider, **re-save it once** to regenerate the catalog (see "Upgrade Notes" below).
+- **[Usage Statistics](../user-manual/en/4-proxy/4.4-usage.md)**: understand the Usage Dashboard's data sources and how the statistics are counted. This release adds Claude Sonnet 5 pricing and fixes usage-script credentials being persisted as "explicit overrides".
+- **[Settings](../user-manual/en/1-getting-started/1.5-settings.md)**: the Codex upstream-format selector and local routing toggle, and Claude's common config (now renamed "Apply Common Config" and auto-synced on switch) all live in the provider form's advanced options.
+
+---
+
+> [!WARNING]
+>
+> ## Only Official Channels (Please Read)
+>
+> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Please only obtain the software through the official channels listed below:
+>
+> | Channel            | Only Official                                                                  |
+> | ------------------ | ------------------------------------------------------------------------------ |
+> | Website            | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | Source             | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | Downloads          | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | Author             | **[@farion1231](https://github.com/farion1231)**                               |
+> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues.
+
+---
+
+## Overview
+
+CC Switch v3.16.5 is a maintenance update following v3.16.4, centered on **making native Codex direct-connect work end-to-end for domestic model providers**. v3.16.4 already switched Qwen / DashScope, Xiaomi MiMo, Volcengine Doubao, Meituan LongCat, and MiniMax to native Responses endpoints; this release goes a step further and generates the **model catalog** Codex needs (`~/.codex/cc-switch-model-catalog.json`), so the Codex desktop app can really see these custom models and invoke their built-in tools, and it fully decouples model mapping from the "local routing" toggle. For the few domestic gateways whose first-party models don't support OpenAI's built-in `web_search` (MiMo, LongCat, MiniMax, Qwen3-Coder), this release also disables that tool automatically, so Codex's default doesn't trigger a hard 400.
+
+For everyday use, this release makes Claude's **common config auto-sync and carry over when you switch providers** — the plugins, environment variables, theme, etc. you added inside the running app are first written back to the common config and then handed to the next provider, so they're not lost on switch; it adds an escape-hatch environment variable for Linux (Wayland + NVIDIA) users hitting click-dead / black-screen issues; it adds Claude Sonnet 5 pricing and bumps the default Sonnet tier to it; it brings a two-level "provider → project directory" grouped session view; and it fixes a string of credential-safety (the common-config snippet now strips all secrets, usage-script credentials are only kept as explicit overrides), platform-compatibility (Hermes Windows config directory, Windows Codex npm shims), and UI (long dropdown scrolling, narrow-window date-range picker) issues. It also adds several new provider presets, ready to pick out of the box.
+
+**Release date**: 2026-07-01
+
+**Stats**: 36 commits | 93 files changed | +5,678 / -2,804 lines
+
+---
+
+## Highlights
+
+- **Native Codex direct-connect actually works for domestic model providers**: CC Switch generates a Codex model catalog (`~/.codex/cc-switch-model-catalog.json`) for domestic providers like Xiaomi MiMo, Volcengine Doubao, Qwen3-Coder, Meituan LongCat, and MiniMax, so the Codex desktop app can see these models and their built-in tools work; and it auto-disables `web_search` for the domestic gateways that reject it (MiMo, LongCat, MiniMax, Qwen3-Coder) to avoid hard 400s. **Existing native providers need a one-time re-save** to regenerate the catalog.
+- **Common config auto-synced and carried over on switch**: when you switch away from a Claude provider that has the common config enabled, the plugins, environment variables, theme, and hooks you added inside the app are first written back to the common config and then handed to the next provider — no longer overwritten and lost on switch.
+- **Escape hatch for Linux Wayland click-dead / black-screen**: when you hit "title bar clicks, page doesn't, black screen on resize" on Wayland + NVIDIA, launch with `CC_SWITCH_GDK_BACKEND=wayland` to switch back to native Wayland (set it to `x11` for the inverse problem on tiling compositors).
+- **Claude Sonnet 5**: adds Sonnet 5 pricing and bumps each preset's default Sonnet tier to `claude-sonnet-5`.
+- **Categorized session view with grouping**: the session panel gains a two-level "provider → project directory" grouped view, with a tri-state checkbox on each group header for one-click batch selection.
+- **New provider presets**: adds Qiniu, FennoAI, ZetaAPI, TeamoRouter, NekoCode, Code0.ai, and Amux presets across the managed apps, ready to pick out of the box.
+
+---
+
+## Added
+
+### Native Codex Direct-Connect for Domestic Model Providers (Generated Model Catalog)
+
+This release makes native Codex direct-connect work for domestic providers. After v3.16.4 switched Xiaomi MiMo, Volcengine Doubao, Qwen3-Coder, Meituan LongCat, and MiniMax to native Responses (`apiFormat: "openai_responses"`), this release reverses the then-current "drop the model catalog on native direct-connect" approach: when these providers connect directly without the local proxy, CC Switch generates `~/.codex/cc-switch-model-catalog.json` for them, so the Codex desktop app really shows these custom models and their built-in tools work — without triggering the freeform `apply_patch` (`type=custom`) tool that native gateways like MiMo reject (editing falls back to `shell_command`). Catalog generation is keyed on `apiFormat` and decoupled from the "local routing" toggle, so a native provider persists a catalog without turning on local route mapping, while `openai_chat` keeps the existing Responses↔Chat proxy conversion unchanged. Because Codex's parser requires `base_instructions` on every entry, the native template carries a neutral default that each vendor's official copy overrides (MiMo, MiniMax). **Existing native providers need a one-time re-save to generate a valid catalog** (no database migration).
+
+Alongside that, for the few domestic gateways whose first-party models don't support OpenAI's built-in `web_search` tool (MiMo, LongCat, MiniMax, Qwen3-Coder), this release auto-disables the tool on switch, so Codex's default doesn't include it and get hard-rejected with a 400 (see "Fixed" below).
+
+### Categorized Session View with Grouping
+
+The Session Manager panel gains a grouped view alongside the existing flat list, toggled via a List / ListTree selector in the toolbar, with view mode and expansion state persisted to `localStorage`. Grouping builds a two-level "provider → project directory" hierarchy: sessions are grouped by project directory name, and sessions with no project directory fall into an "unknown directory" bucket. Both levels are collapsible sections, with a "collapse all" button; in batch mode, each group header shows a tri-state checkbox that selects / deselects every selectable session in that group at once, along with a selected / selectable count badge. Copy across all four locales (zh / en / ja / zh-TW) is in sync. The change is entirely front-end, with no backend commands or data-access changes. ([#4776](https://github.com/farion1231/cc-switch/pull/4776))
+
+### Claude Sonnet 5 Model Pricing
+
+Added a `claude-sonnet-5` pricing row in `schema.rs` at Anthropic list pricing — \$3 / \$15 per million input / output tokens and \$0.30 / \$3.75 cache read / write, matching Sonnet 4.6. The introductory \$2 / \$10 promotion (valid through 2026-08-31) is deliberately not seeded, so accounting reflects steady-state list pricing rather than a temporary discount. The row is applied on the app's next start via `ensure_model_pricing_seeded`, with no `SCHEMA_VERSION` bump.
+
+### New Provider Presets
+
+This release adds a batch of provider presets; pick one and fill in your own API key to use it:
+
+- **Qiniu**: covers all seven managed apps (including Gemini), relaying native Claude / GPT / Gemini.
+- **FennoAI / ZetaAPI / TeamoRouter / NekoCode**: each covers six apps (Claude, Claude Desktop, Codex, OpenCode, OpenClaw, Hermes).
+- **Code0.ai**: covers all seven apps (including Gemini).
+- **Amux**: covers six apps.
+
+Each preset's endpoints and default models are configured for the corresponding app — the Claude family connects directly to an Anthropic-compatible host, Codex uses native Responses, and the rest use the OpenAI-compatible `/v1`.
+
+---
+
+## Changed
+
+### Common Config Auto-Synced and Carried Over on Provider Switch
+
+This is a very practical change in this release: when you switch away from a Claude provider that has the common config enabled, the service first **re-extracts the shareable portion from its live `settings.json` and updates the common config**, then hands it to the next provider, instead of only writing one way. As a result, the plugins (`enabledPlugins`), hooks, environment variables (`env`), theme (`theme`), and other shared config you added directly in the running app are not silently lost on switch, but automatically follow along to the next provider; deletions sync too (a removed key is not re-injected). This sync is strictly scoped to Claude providers that have the common config enabled, is skipped when it was explicitly cleared, and all failures are non-fatal (warn only) and never block the switch.
+
+### Codex Model Mapping Decoupled from the "Local Routing" Toggle
+
+The Codex provider form aligns with Claude Code — the model-mapping catalog is now independent of route takeover, because native Responses providers (MiMo, Doubao, MiniMax) need it for proxy-less direct-connect, while Chat providers go through the proxy regardless. The "needs local routing" toggle is removed (it had no backend field and only gated catalog / reasoning persistence, which is equivalent to whether the mapping is filled in). Model mapping is now always shown for non-official providers and persisted whenever it's non-empty, while reasoning visibility / persistence is gated on the Chat format instead. Copy across all four locales (zh / en / ja / zh-TW) was rewritten accordingly. As a side fix, `useCodexConfigState` no longer drops `supportsParallelToolCalls` / `inputModalities` / `baseInstructions` when loading a saved provider (which used to silently lose parallel tools, image input, and the official base instructions on edit).
+
+### Default Sonnet Tier Bumped to Claude Sonnet 5
+
+Bumped the default Sonnet tier in each provider preset from `claude-sonnet-4-6` to `claude-sonnet-5` (across the claude / claude-desktop / hermes / openclaw / opencode presets and the universal `NEWAPI_DEFAULT_MODELS`), covering keys like `ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_OPUS_MODEL` and their prefixed variants. Claude Desktop's default-route sonnet `route_id` also migrates to `claude-sonnet-5`. Non-Anthropic pins (gpt / gemini / glm / sonnet-4-5) are left unchanged.
+
+### Doubao Dated Model Id and Pricing Normalization
+
+The Doubao (DouBaoSeed) preset's model id switches to the dated form `doubao-seed-2-1-pro-260628` (across all apps), because Volcengine Ark rejects the bare `doubao-seed-2-1-pro` with a 404 and only accepts the full dated id. Since real usage now carries a date suffix, `strip_model_date_suffix` was extended to also strip Volcengine's 6-digit YYMMDD form (validating month 01-12 and day 01-31 to avoid eating non-date version suffixes like `-123456`), so it normalizes back to hit the bare-name seed row in the pricing table, fixing the \$0-cost display for Doubao models.
+
+### "Write Common Config" Renamed to "Apply Common Config"
+
+The original label "Write Common Config" was ambiguous about data-flow direction (it read like "write the current config into the common config"), whereas the actual behavior is the reverse — it merges the saved common-config snippet into this provider's config. The checkbox is renamed to "Apply Common Config" across all four locales (zh / en / ja / zh-TW), including every hint / guide / notice reference, with the Japanese user manual and `README_JA.md` synced too. ([#4829](https://github.com/farion1231/cc-switch/pull/4829))
+
+### Other Preset and Asset Adjustments
+
+- **OpenClaw Doubao context aligned to 262144**: OpenClaw's DouBaoSeed preset previously hardcoded 128000 while the Codex side used 262144 for the same model, giving OpenClaw users too small a window; the two are now aligned, with a cross-preset consistency test to prevent drift.
+- **Volcengine / Doubao / BytePlus website links corrected**: the "visit website" links on these three presets had been mistakenly set to console / signup links, and are restored to clean product homepages.
+- **Downscale oversized provider icons to 256px**: a batch of bundled icons were far larger than their ~32px on-screen render size; downscaling significantly reduces their size with no code / filename / import changes (e.g. ZetaAPI 940KB→40KB, relaxcode 1.16MB→42KB), and the never-referenced 1.4MB `dds.svg` orphan was removed.
+
+---
+
+## Fixed
+
+### Disable web_search for Native Codex Gateways That Reject It
+
+Some native `/responses` gateways whose first-party models lack OpenAI's hosted `web_search` tool reject it with "tool type 'web_search' is not supported", and Codex sends the tool by default, producing a hard 400. CC Switch now writes the top-level TOML line `web_search = "disabled"` for those vendors on switch. The scope is a blacklist (default-on): only providers matched by `base_url` host (`xiaomimimo.com`, `longcat.chat`, `minimax.io`, `minimaxi.com`) or by model brand prefix (`mimo`, `longcat`, `minimax`, `qwen3-coder`) are disabled, so relays serving real GPT, Doubao, general Qwen, and any unknown provider keep Codex's default. The `qwen3-coder` prefix only suppresses native `qwen3-coder-plus` (Bailian / DashScope marks built-in tools unsupported for the coder series), while general Qwen sharing the same host stays enabled; matching is on the model axis (stripping any aggregator `vendor/` path segment), so it also catches cases like SiliconFlow fronting a reject vendor's model. A blacklist was chosen over a fuzzy "is this GPT?" whitelist because wrongly keeping `web_search` on fails with a hard 400; an ownership sentinel ensures CC Switch only ever removes a `disabled` value it wrote itself, so existing providers need no re-save and switching back re-enables it. As a side fix, the LongCat-2.0-Preview preset's context window is corrected from 131072 (128K) to the real 1048576 (1M).
+
+### Strip All Credential-Like Keys from the Shared Claude Common-Config Snippet
+
+`extract_claude_common_config` previously only redacted `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN`, but Claude providers legitimately carry other credentials (`OPENROUTER_API_KEY`, `GOOGLE_API_KEY`, and possibly OpenAI / Gemini / AWS Bedrock / Vertex secrets), which could leak into the shared snippet and then be injected into other providers. Extraction now pattern-matches and strips any credential-shaped env key (`*_API_KEY` / `*_AUTH_TOKEN` / `*secret*` / `*token*`, etc.), while preserving legitimately shareable plural `*_TOKENS` values like `MAX_OUTPUT_TOKENS`. This also closes the same leak on the manual "Extract" and one-time auto-extract paths.
+
+### Usage-Script Credentials Persisted Only as Explicit Overrides
+
+Provider usage scripts store optional `api_key` / `base_url` fields that override the live credentials when querying quota, but they used to silently mirror the provider's own credentials — so copying a provider or editing its main API key / base URL left the usage script pinned to the old endpoint and key, and quota queries kept hitting a stale target. `ProviderService` now normalizes before persisting: if the script's `api_key` or `base_url` matches the provider's resolved usage credentials (or is blank), it is cleared to `None` so queries fall back to the live config; genuinely different overrides are kept (`token_plan` scripts are left alone). The deeplink import path gets matching normalization too, and the front-end invalidates the relevant cache keys on update so the home page re-queries with the corrected config. ([#4654](https://github.com/farion1231/cc-switch/pull/4654))
+
+### Hermes Config Directory Resolves Correctly on Windows
+
+CC Switch hardcoded `~/.hermes` as the Hermes config directory, but Hermes itself resolves it via the `HERMES_HOME` environment variable, then a platform default (`%LOCALAPPDATA%\hermes` on Windows). On Windows this meant CC Switch wrote provider configs to a path Hermes never reads, so provider switches had no effect. `get_hermes_dir()` now mirrors Hermes' own resolution order — explicit override, then `HERMES_HOME` (taken verbatim, no `~` expansion), then the platform default — re-honoring the `HERMES_HOME` that #3470 had dropped (Hermes' Windows installer sets it as the first-class mechanism for relocated installs). ([#4680](https://github.com/farion1231/cc-switch/pull/4680), see #3178, #3470)
+
+### Linux Wayland: Override the AppImage's Forced `GDK_BACKEND=x11`
+
+The AppImage's GTK launch hook unconditionally exports `GDK_BACKEND=x11` to dodge a historical native-Wayland crash. On newer Wayland + NVIDIA setups, this forced XWayland leaves the WebKitGTK web content unable to receive pointer events (the title bar clicks, the page is dead) and black-screens on resize, and the existing `WEBKIT_DISABLE_*` mitigations don't help because the root cause is the forced window backend, not rendering. `main.rs` now reads an optional `CC_SWITCH_GDK_BACKEND` escape hatch before GTK init (the AppImage's launch hook never touches it): leaving it unset keeps current behavior (zero regression). When you hit the problem above, launch with it set to switch back to native Wayland:
+
+```bash
+CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
+```
+
+The override is generic — if you're on a tiling Wayland compositor hitting the inverse input problem, set `CC_SWITCH_GDK_BACKEND=x11` instead. ([#4351](https://github.com/farion1231/cc-switch/pull/4351), fixes #4350)
+
+### "Get API Key" Link Now Shows in Claude Desktop, OpenClaw, and Hermes Forms
+
+The "Get API Key" link and partner-promotion block below the API key input was only wired for claude / codex / gemini / opencode. Claude Desktop rendered a bare input that never showed it, and OpenClaw / Hermes were blocked by two gaps (the whitelist only listed those four appIds, and category parsing only recognized those four preset-id patterns). Claude Desktop now uses the shared `ApiKeySection`, and both the whitelist and category parsing were extended to claude-desktop / openclaw / hermes; additionally, the Hermes / OpenClaw forms no longer let an "official" category disable the key input (these apps have no OAuth-only official providers — e.g. Hermes' Nous Research is official but still needs a user-supplied key).
+
+### Deduplicate Windows Codex npm Shims
+
+On Windows, npm installs a tool as three sibling files — `codex.cmd`, `codex.exe`, and an extensionless Unix shim `codex` — and CC Switch previously listed all three as candidates, so the non-executable extensionless shim was probed as a redundant / failing candidate. It now appends the extensionless path only when there's no runnable `.cmd` / `.exe` sibling adjacent, and path resolution prefers the runnable `.cmd` / `.exe`, anchoring version detection and launch to the actually-runnable Windows shim. ([#4782](https://github.com/farion1231/cc-switch/pull/4782))
+
+### Scroll Bounds for Long Select Dropdowns
+
+`SelectContent` previously used `overflow-hidden` with no height cap, so dropdowns with many options (e.g. long model / provider lists) rendered taller than the viewport and clipped their overflow with no way to reach it. It now sets `max-h-[min(24rem,var(--radix-select-content-available-height))]` and `overflow-y-auto`, bounding the content to 24rem or the Radix-computed available height and allowing vertical scrolling. ([#4798](https://github.com/farion1231/cc-switch/pull/4798))
+
+### Date-Range Picker Calendar Stays On-Screen in Narrow Popovers
+
+The custom date-range picker previously switched to its two-column layout (date fields | calendar) based on the **viewport** width (Tailwind's `sm:` 640px breakpoint), but the popover is clamped to `100vw - 2rem` and anchored to its trigger, so its real available width is narrower than the viewport. On narrow windows the two-column layout could activate while the popover only had room for one column, pushing the calendar column off the right edge where it was clipped (the month header and 4 of 7 weekday columns cut off and unreachable). The layout now keys off the popover's own inline size via a CSS container query, so it collapses to one column exactly when the popover itself is narrow, keeping the calendar fully visible at any window width. ([#4860](https://github.com/farion1231/cc-switch/pull/4860))
+
+---
+
+## Documentation
+
+### `CC_SWITCH_GDK_BACKEND` Escape Hatch Documented
+
+Added an FAQ entry for the optional `CC_SWITCH_GDK_BACKEND` environment variable across all four README languages and the zh / en / ja user-manual troubleshooting pages, explaining how Wayland + NVIDIA users can switch back to native Wayland when the web content goes "click-dead + black screen on resize", and how tiling-Wayland users can set it to `x11` for the inverse input problem.
+
+### Overseas Kimi READMEs Point to platform.kimi.ai
+
+The Kimi K2.7 Code partner section in the English, German, and Japanese READMEs now points its banner and inline calls to action at `https://platform.kimi.ai?aff=cc-switch` (keeping the referral tag), and all four READMEs gained a line promoting the Kimi For Coding subscription linked to `https://www.kimi.com/code/?aff=cc-switch`.
+
+---
+
+## Upgrade Notes
+
+### Existing Native Codex Providers Need a One-Time Re-Save
+
+This release reworks model-catalog generation for native Responses direct-connect. If you previously configured a Codex provider using native Responses (`openai_responses`), **re-pick the preset or open the provider and save it once** to generate the new `~/.codex/cc-switch-model-catalog.json` — that's what lets the Codex desktop app show the custom models and makes the tools work. This requires no database migration and does not affect providers on the `openai_chat` format.
+
+### web_search Blacklist Is Default Behavior
+
+For known-to-reject-`web_search` domestic native gateways (Xiaomi MiMo, Meituan LongCat, MiniMax, Qwen3-Coder), this release automatically writes `web_search = "disabled"` on switch. Relays serving real GPT, Doubao, general Qwen, and unknown providers are unaffected and keep Codex's default. The switch is managed by CC Switch with an ownership sentinel, so switching back to a provider not on the blacklist restores it automatically, with no manual intervention.
+
+### Default Sonnet Tier Change
+
+Claude-family providers newly created from a preset now have their default Sonnet tier pointing to `claude-sonnet-5`. Existing configured providers are unaffected and keep their configuration as-is; to switch to Sonnet 5, re-pick the preset and save.
+
+---
+
+## Risk Notice
+
+This release continues the risk notices from previous versions for reverse-proxy-style features.
+
+**Codex OAuth reverse proxy**: using a ChatGPT subscription's Codex OAuth through a reverse proxy may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details.
+
+**Codex third-party provider Chat routing**: when CC Switch local proxy converts and forwards Codex requests to third-party providers, each provider may have different requirements for billing, compliance, and data retention. Read the target provider's terms before use.
+
+**Claude Desktop third-party provider proxy switching**: when CC Switch's built-in proxy gateway forwards Claude Desktop requests to third-party providers, you must also follow the target provider's billing, compliance, and data-retention terms.
+
+By enabling these features, users accept the related risks. CC Switch is not responsible for account restrictions, warnings, or service suspensions caused by using these features.
+
+---
+
+## Thanks
+
+Thanks to the following contributors for the features and fixes in v3.16.5:
+
+- [#4776](https://github.com/farion1231/cc-switch/pull/4776): add the categorized session view and group management, thanks @alkaid616.
+- [#4829](https://github.com/farion1231/cc-switch/pull/4829): rename "Write Common Config" to "Apply Common Config", thanks @arichyx.
+- [#4654](https://github.com/farion1231/cc-switch/pull/4654): persist usage-script credentials only as explicit overrides, thanks @yyhhyyyyyy.
+- [#4680](https://github.com/farion1231/cc-switch/pull/4680): fix Hermes provider config not taking effect on Windows, thanks @thisTom.
+- [#4782](https://github.com/farion1231/cc-switch/pull/4782): deduplicate Windows Codex npm shims, thanks @justjavac.
+- [#4798](https://github.com/farion1231/cc-switch/pull/4798): fix long dropdown lists not being scrollable, thanks @xwil1.
+- [#4351](https://github.com/farion1231/cc-switch/pull/4351): allow overriding the AppImage's forced `GDK_BACKEND=x11` via `CC_SWITCH_GDK_BACKEND`, thanks @BoneLiu.
+- [#4860](https://github.com/farion1231/cc-switch/pull/4860): keep the date-range picker calendar on-screen in narrow popovers, thanks @SaladDay.
+
+Thanks also to everyone who reported native Codex direct-connect, common config, credential reuse, and platform compatibility issues after the v3.16.4 release. Many of these patches came directly from real-world reproduction clues.
+
+---
+
+## Download & Install
+
+Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) and download the build for your system.
+
+### System Requirements
+
+| System  | Minimum Version          | Architecture                        |
+| ------- | ------------------------ | ----------------------------------- |
+| Windows | Windows 10 and later     | x64 / ARM64                         |
+| macOS   | macOS 12 (Monterey)+     | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | See table below          | x64 / ARM64                         |
+
+### Windows
+
+| File                                     | Description                                      |
+| ---------------------------------------- | ------------------------------------------------ |
+| `CC-Switch-v3.16.5-Windows.msi`          | **Recommended** - MSI installer with auto-update |
+| `CC-Switch-v3.16.5-Windows-Portable.zip` | Portable build, unzip and run                    |
+
+Windows ARM64 devices should pick the artifact whose file name carries the `arm64` tag.
+
+### macOS
+
+| File                             | Description                                           |
+| -------------------------------- | ----------------------------------------------------- |
+| `CC-Switch-v3.16.5-macOS.dmg`    | **Recommended** - DMG installer, drag to Applications |
+| `CC-Switch-v3.16.5-macOS.zip`    | Unzip and drag to Applications, Universal Binary      |
+| `CC-Switch-v3.16.5-macOS.tar.gz` | For Homebrew install and auto-update                  |
+
+Homebrew install:
+
+```bash
+brew install --cask cc-switch
+```
+
+Upgrade:
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+Linux assets are available for both **x86_64** and **ARM64** (`aarch64`). Choose the file whose architecture tag matches your machine's `uname -m` output:
+
+- `CC-Switch-v3.16.5-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.16.5-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| Distribution                            | Recommended Format | Install Command                                                        |
+| --------------------------------------- | ------------------ | --------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`             | `sudo dpkg -i CC-Switch-*.deb` or `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`             | `sudo rpm -i CC-Switch-*.rpm` or `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`             | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                    | `.AppImage`        | Make executable and run directly, or use AUR                          |
+| Other distributions / unsure            | `.AppImage`        | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`             |
@@ -0,0 +1,278 @@
+# CC Switch v3.16.5
+
+> 本リリースの目玉は、**ネイティブ Responses 形式の国産モデルプロバイダーをきちんと適合させたこと**です——ネイティブ Responses endpoint を備えるプロバイダー（小米 MiMo、火山 Doubao、Qwen3-Coder、美団 LongCat、MiniMax）向けに Codex モデルカタログを生成し、Codex デスクトップがこれらのモデルを表示でき、内蔵ツールも正しく動くようにしました。また、`web_search` を拒否する一部の国産ゲートウェイに対しては、そのツールを自動で無効化し、リクエストがハード拒否されないようにします。ほかに 2 つの重要な改善があります: プロバイダーを切り替えるとき、アプリ内で追加したプラグインや環境変数などが**自動的に共通設定へ書き戻され、次のプロバイダーへ引き継がれます**。そして Linux（Wayland + NVIDIA）で「タイトルバーは押せるのにページが反応しない、リサイズで黒画面」になる問題も、環境変数のスイッチで自力回避できるようになりました。本リリースはさらに Claude Sonnet 5 の価格と既定階層の引き上げ、2 段階グルーピングのセッションビュー、そして一連の認証情報の安全性とプラットフォーム互換性の修正を届けます。
+
+**[English →](v3.16.5-en.md) | [中文版 →](v3.16.5-zh.md)**
+
+---
+
+## 利用ガイド
+
+本リリースの新機能は、主に Codex プロバイダーフォーム、セッションパネル、使用量 / 共通設定に収まっています。以下のドキュメントとあわせてご覧ください：
+
+- **[Codex デスクトップでカスタムモデルが見えない？](../guides/codex-desktop-custom-model-visibility-ja.md)**: 本リリースは**ネイティブ直結時のモデルカタログ生成**を作り直しました——Codex プロバイダーがネイティブ Responses（`openai_responses`）で直結するとき、CC Switch が `~/.codex/cc-switch-model-catalog.json` を生成し、Codex デスクトップが設定済みのカスタムモデルを表示でき、ツールも動くようにします。以前にネイティブ Codex プロバイダーを設定していた場合は、新しいカタログを生成するために**一度保存し直して**ください（下記「アップグレード時の注意」を参照）。
+- **[使用量統計](../user-manual/ja/4-proxy/4.4-usage.md)**: 使用量ダッシュボードのデータソースと集計の仕組みを確認できます。本リリースでは Claude Sonnet 5 の価格を追加し、使用量スクリプトの認証情報が「明示的なオーバーライド」として永続化される問題を修正しました。
+- **[設定](../user-manual/ja/1-getting-started/1.5-settings.md)**: Codex の上流形式セレクタとローカルルーティングのトグル、Claude の共通設定（「共通設定を適用」に改名され、切り替え時に自動同期）は、いずれもプロバイダーフォームの高度なオプションにあります。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一の公式チャネル（必ずお読みください）
+>
+> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。本ソフトウェアは下記の公式チャネルからのみ入手してください：
+>
+> | チャネル     | 唯一の公式                                                                     |
+> | ------------ | ------------------------------------------------------------------------------ |
+> | 公式サイト   | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者         | **[@farion1231](https://github.com/farion1231)**                               |
+> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は直ちに操作を中止し、GitHub Issues からご報告ください。
+
+---
+
+## 概要
+
+CC Switch v3.16.5 は v3.16.4 に続くメンテナンスアップデートで、その中心は**国産モデルプロバイダーの Codex ネイティブ直結をエンドツーエンドで通すこと**です。v3.16.4 ですでに千問 / DashScope 百炼、小米 MiMo、火山 Doubao、美団 LongCat、MiniMax をネイティブ Responses endpoint へ切り替えていましたが、本リリースはさらに Codex が必要とする**モデルカタログ**（`~/.codex/cc-switch-model-catalog.json`）を生成し、Codex デスクトップがこれらのカスタムモデルを本当に表示でき、内蔵ツールも呼び出せるようにし、モデルマッピングを「ローカルルーティング」トグルから完全に分離しました。第一方モデルが OpenAI 内蔵の `web_search` に対応しない一部の国産ゲートウェイ（MiMo、LongCat、MiniMax、Qwen3-Coder）については、本リリースがそのツールを自動で無効化し、Codex の既定でそれが付いてハード 400 を招くことを避けます。
+
+日々の使い勝手の面では、本リリースは Claude の**共通設定をプロバイダー切り替え時に自動で同期・引き継ぐ**ようにしました——アプリ内で直接追加したプラグイン、環境変数、テーマなどが、まず共通設定へ書き戻され、次のプロバイダーへ渡されるため、切り替え時に失われません。Linux（Wayland + NVIDIA）でクリック無反応 / 黒画面になるユーザー向けに、自力回避できる環境変数を追加し、Claude Sonnet 5 の価格を補って既定の Sonnet 階層をそれへ引き上げ、「プロバイダー → プロジェクトディレクトリ」の 2 段階グルーピングのセッションビューを届け、一連の認証情報の安全性（共通設定スニペットからすべての秘密情報を除去、使用量スクリプトの認証情報は明示的なオーバーライドとしてのみ保持）、プラットフォーム互換性（Hermes の Windows 設定ディレクトリ、Windows の Codex npm シム）、UI（長いドロップダウンのスクロール、狭いウィンドウの日付範囲セレクタ）の問題を修正しました。あわせて、いくつかのプロバイダープリセットも追加し、そのまますぐ選べます。
+
+**リリース日**: 2026-07-01
+
+**Stats**: 36 commits | 93 files changed | +5,678 / -2,804 lines
+
+---
+
+## ハイライト
+
+- **国産モデルプロバイダーの Codex ネイティブ直結が本当に使える**: 小米 MiMo、火山 Doubao、Qwen3-Coder、美団 LongCat、MiniMax などの国産プロバイダー向けに Codex モデルカタログ（`~/.codex/cc-switch-model-catalog.json`）を生成し、Codex デスクトップがこれらのモデルを表示でき、内蔵ツールが動くようにします。あわせて `web_search` を拒否する国産ゲートウェイ（MiMo、LongCat、MiniMax、Qwen3-Coder）に対してはそのツールを自動で無効化し、ハード 400 を避けます。**既存のネイティブプロバイダーは、新しいカタログ生成のために一度保存し直す必要があります。**
+- **共通設定を切り替え時に自動同期・引き継ぎ**: 共通設定を有効にした Claude プロバイダーから切り替えるとき、アプリ内で追加したプラグイン、環境変数、テーマ、hooks が、まず共通設定へ書き戻され、次のプロバイダーへ渡されます——切り替え時に上書きで失われることがなくなりました。
+- **Linux Wayland のクリック無反応 / 黒画面の回避スイッチ**: Wayland + NVIDIA で「タイトルバーは押せるのにページが反応しない、リサイズで黒画面」に遭遇したら、`CC_SWITCH_GDK_BACKEND=wayland` で起動すればネイティブ Wayland へ切り替えられます（タイリング系コンポジタで逆の問題に遭遇する場合は `x11` に設定）。
+- **Claude Sonnet 5**: Sonnet 5 の価格を追加し、各プリセットの既定 Sonnet 階層を `claude-sonnet-5` へ引き上げます。
+- **セッションの分類ビューとグルーピング**: セッションパネルに「プロバイダー → プロジェクトディレクトリ」の 2 段階グルーピングビューを新設し、グループヘッダーの 3 状態チェックボックスでワンクリックの一括選択に対応します。
+- **新しいプロバイダープリセット**: 七牛云、FennoAI、ZetaAPI、TeamoRouter、NekoCode、Code0.ai、Amux などのプロバイダープリセットを、管理対象アプリ全体に追加し、そのまますぐ選べます。
+
+---
+
+## 追加機能
+
+### 国産モデルプロバイダーの Codex ネイティブ直結（モデルカタログの生成）
+
+本リリースは、国産プロバイダーの Codex ネイティブ直結を通しました。v3.16.4 で小米 MiMo、火山 Doubao、Qwen3-Coder、美団 LongCat、MiniMax をネイティブ Responses（`apiFormat: "openai_responses"`）へ切り替えたのに続き、本リリースは当時の「ネイティブ直結ならモデルカタログを削除する」やり方を覆しました: これらのプロバイダーがローカルプロキシを経由せず直結するとき、CC Switch が `~/.codex/cc-switch-model-catalog.json` を生成し、Codex デスクトップがこれらのカスタムモデルを本当に表示でき、内蔵ツールも動くようにします——MiMo のようなネイティブゲートウェイが拒否する freeform `apply_patch`（`type=custom`）ツールを発生させません（編集は `shell_command` へフォールバック）。カタログ生成は `apiFormat` で判定され、「ローカルルーティング」トグルから分離されているため、ネイティブプロバイダーはローカルルートマッピングを有効にしなくてもカタログを永続化します。一方 `openai_chat` 形式は、既存の Responses↔Chat プロキシ変換をそのまま保ちます。Codex のパーサーは各項目に `base_instructions` を要求するため、ネイティブテンプレートは中立の既定値を携え、各ベンダーの公式文面がそれを上書きします（MiMo、MiniMax）。**既存のネイティブプロバイダーは、有効なカタログを生成するために一度保存し直す必要があります**（データベース移行は不要）。
+
+あわせて、第一方モデルが OpenAI 内蔵の `web_search` ツールに対応しない一部の国産ゲートウェイ（MiMo、LongCat、MiniMax、Qwen3-Coder）については、本リリースが切り替え時にそのツールを自動で無効化し、Codex の既定でそれが付いてハード 400 で拒否されるのを避けます（下記「修正」を参照）。
+
+### セッションの分類ビューとグルーピング
+
+セッション管理パネルに、既存のフラットなリストに加えてグルーピングビューを新設し、ツールバーの List / ListTree セレクタで切り替え、ビューモードと展開状態を `localStorage` に永続化します。グルーピングは「プロバイダー → プロジェクトディレクトリ」の 2 段階階層を構築します: プロジェクトディレクトリ名でグループ化し、プロジェクトディレクトリを持たないセッションは「不明なディレクトリ」バケットに入ります。両方の段階が折りたたみ可能な区画で、「すべて折りたたむ」ボタンを備えます。バッチモードでは、各グループヘッダーに 3 状態チェックボックスが現れ、そのグループ内の選択可能なセッションをすべて一括で選択 / 解除でき、選択数 / 選択可能数のバッジも表示します。4 言語（zh / en / ja / zh-TW）の文言は同期済みです。この変更は完全にフロントエンドで、バックエンドのコマンドやデータアクセス層には手を加えていません。（[#4776](https://github.com/farion1231/cc-switch/pull/4776)）
+
+### Claude Sonnet 5 のモデル価格
+
+`schema.rs` に `claude-sonnet-5` の価格行を Anthropic の定価で追加しました——入力 / 出力が 100 万 token あたり \$3 / \$15、キャッシュ読み書きが \$0.30 / \$3.75 で、Sonnet 4.6 と同一です。導入期の \$2 / \$10 プロモーション（2026-08-31 まで有効）は意図的にシードせず、記帳が一時的な割引ではなく定常の定価を反映するようにしています。この行はアプリの次回起動時に `ensure_model_pricing_seeded` 経由で適用され、`SCHEMA_VERSION` の引き上げは不要です。
+
+### 新しいプロバイダープリセット
+
+本リリースは一連のプロバイダープリセットを追加しました。選択して自分の API key を入力すればすぐ使えます：
+
+- **七牛云（Qiniu）**: 管理対象の 7 アプリすべて（Gemini を含む）をカバーし、ネイティブ Claude / GPT / Gemini を中継します。
+- **FennoAI / ZetaAPI / TeamoRouter / NekoCode**: それぞれ 6 アプリ（Claude、Claude Desktop、Codex、OpenCode、OpenClaw、Hermes）をカバーします。
+- **Code0.ai**: 7 アプリすべて（Gemini を含む）をカバーします。
+- **Amux**: 6 アプリをカバーします。
+
+各プリセットの endpoint と既定モデルは対応するアプリに合わせて設定済みです——Claude 系は Anthropic 互換ホストへ直結、Codex はネイティブ Responses、その他は OpenAI 互換の `/v1` を使います。
+
+---
+
+## 変更
+
+### プロバイダー切り替え時に共通設定を自動同期・引き継ぎ
+
+これは本リリースのとても実用的な変更です: 共通設定を有効にした Claude プロバイダーから切り替えるとき、サービスはまずその live の `settings.json` から**共有可能な部分を再抽出して共通設定を更新し**、次のプロバイダーへ渡します。以前のような一方向の書き込みだけではありません。これにより、実行中のアプリで直接追加したプラグイン（`enabledPlugins`）、hooks、環境変数（`env`）、テーマ（`theme`）などの共有設定が、切り替え時に静かに失われることなく、自動的に次のプロバイダーへ引き継がれます。削除も同期されます（削除されたキーは再注入されません）。この同期は共通設定を有効にした Claude プロバイダーに厳密に限定され、明示的にクリアされた場合はスキップされ、すべての失敗は非致命的（警告のみ）で、切り替えを妨げることは決してありません。
+
+### Codex のモデルマッピングと「ローカルルーティング」トグルの分離
+
+Codex プロバイダーフォームが Claude Code に揃いました——モデルマッピングカタログがルーティングテイクオーバーから独立しました。ネイティブ Responses プロバイダー（MiMo、Doubao、MiniMax）はプロキシなし直結のためにそれを必要とする一方、Chat プロバイダーはいずれにせよプロキシを経由するためです。「ローカルルーティングが必要」トグルは削除されました（バックエンドのフィールドを持たず、カタログ / 推論の永続化を制御していただけで、これはマッピングが記入されているかどうかと等価です）。モデルマッピングは非公式プロバイダーに対して常に表示され、空でなければ永続化されます。一方、推論能力の表示 / 永続化は Chat 形式で制御されるようになりました。4 言語（zh / en / ja / zh-TW）の文言もあわせて書き直しました。副次的な修正として、`useCodexConfigState` が保存済みプロバイダーを読み込むときに `supportsParallelToolCalls` / `inputModalities` / `baseInstructions` を落とす問題（編集時に並列ツール、画像入力、公式の base instructions を静かに失っていた）も修正しました。
+
+### 既定の Sonnet 階層を Claude Sonnet 5 へ引き上げ
+
+各プロバイダープリセットの既定 Sonnet 階層を `claude-sonnet-4-6` から `claude-sonnet-5` へ引き上げました（claude / claude-desktop / hermes / openclaw / opencode のプリセットとユニバーサルの `NEWAPI_DEFAULT_MODELS` をカバー）。`ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_OPUS_MODEL` などのキーとそのプレフィックス付き変種が対象です。Claude Desktop の既定ルートの sonnet `route_id` もあわせて `claude-sonnet-5` へ移行しました。非 Anthropic の pin（gpt / gemini / glm / sonnet-4-5）はそのままです。
+
+### Doubao の日付付き model id と価格の正規化
+
+Doubao（DouBaoSeed）プリセットの model id を日付付きの `doubao-seed-2-1-pro-260628` へ切り替えました（各アプリをカバー）。火山方舟が素の `doubao-seed-2-1-pro` を 404 で拒否し、完全な日付付き id のみを受け付けるためです。実際の使用量が日付サフィックスを伴うようになったため、`strip_model_date_suffix` を火山の 6 桁 YYMMDD 形式も剥がせるように拡張し（`-123456` のような非日付のバージョンサフィックスを誤って食わないよう、月 01-12・日 01-31 を検証）、価格表の素の名前のシード行にマッチするよう正規化して、Doubao モデルが \$0 コストで表示される問題を修正しました。
+
+###「共通設定を書き込む」を「共通設定を適用」へ改名
+
+元のラベル「共通設定を書き込む」はデータの流れの方向が曖昧でした（「現在の設定を共通設定へ書き込む」と読めた）。実際の挙動は逆で——保存済みの共通設定スニペットをこのプロバイダーの設定へマージするものです。チェックボックスを 4 言語（zh / en / ja / zh-TW）で「共通設定を適用」へ改名し、すべてのヒント / ガイド / 説明の参照を含め、日本語ユーザーマニュアルと `README_JA.md` もあわせて同期しました。（[#4829](https://github.com/farion1231/cc-switch/pull/4829)）
+
+### その他のプリセットと素材の調整
+
+- **OpenClaw の Doubao コンテキストを 262144 へ整合**: OpenClaw の DouBaoSeed プリセットは以前 128000 をハードコードしていましたが、Codex 側は同モデルで 262144 を使っており、OpenClaw ユーザーのウィンドウが小さすぎました。両者を整合させ、再びずれないようクロスプリセットの一貫性テストを追加しました。
+- **火山 / Doubao / BytePlus の公式サイトリンクを訂正**: これら 3 つのプリセットの「公式サイトを訪問」リンクが、誤ってコンソール / 登録リンクに設定されていたため、クリーンな製品トップページへ戻しました。
+- **過大なプロバイダーアイコンを 256px へダウンスケール**: 一連のバンドルアイコンが、実際の描画サイズ（~32px）よりはるかに大きかったため、ダウンスケールで大幅に容量を削減しました（コード / ファイル名 / インポートの変更なし。例: ZetaAPI 940KB→40KB、relaxcode 1.16MB→42KB）。また、一度も参照されていない 1.4MB の `dds.svg` 孤立ファイルを削除しました。
+
+---
+
+## 修正
+
+### `web_search` を拒否するネイティブ Codex ゲートウェイでは無効化
+
+一部のネイティブ `/responses` ゲートウェイは、第一方モデルが OpenAI のホスト型 `web_search` ツールを備えないため、それを「tool type 'web_search' is not supported」で拒否します。そして Codex は既定でそのツールを送るため、ハード 400 を招きます。CC Switch は現在、これらのベンダーに対して切り替え時にトップレベルの TOML 行 `web_search = "disabled"` を書き込みます。スコープはブラックリスト（既定オン）で、`base_url` ホスト（`xiaomimimo.com`、`longcat.chat`、`minimax.io`、`minimaxi.com`）または model のブランドプレフィックス（`mimo`、`longcat`、`minimax`、`qwen3-coder`）に一致するプロバイダーだけが無効化されるため、本物の GPT、Doubao、一般の Qwen、そして未知のプロバイダーはいずれも Codex の既定を保ちます。`qwen3-coder` プレフィックスはネイティブの `qwen3-coder-plus` だけを抑制し（百炼 / DashScope は coder 系で内蔵ツールを非対応と示します）、同じホストを共有する一般の Qwen は有効のままです。マッチングは model 軸で行われ（アグリゲーターの `vendor/` パスセグメントを剥がす）、SiliconFlow が拒否ベンダーのモデルを前面に立てるようなケースも捕捉します。曖昧な「これは GPT か？」というホワイトリストではなくブラックリストを選んだのは、`web_search` を誤ってオンのままにするとハード 400 で失敗するためです。所有権のセンチネルにより、CC Switch は自らが書いた `disabled` 値だけを削除するため、既存プロバイダーは保存し直す必要がなく、切り替えて戻せば再び有効になります。副次的な修正として、LongCat-2.0-Preview プリセットのコンテキストウィンドウを 131072（128K）から本来の 1048576（1M）へ訂正しました。
+
+### 共有される Claude 共通設定スニペットからすべての認証情報系キーを除去
+
+`extract_claude_common_config` は以前 `ANTHROPIC_API_KEY` と `ANTHROPIC_AUTH_TOKEN` だけをマスクしていましたが、Claude プロバイダーは正当に他の認証情報（`OPENROUTER_API_KEY`、`GOOGLE_API_KEY`、場合によっては OpenAI / Gemini / AWS Bedrock / Vertex の秘密情報）を携えることがあり、それらが共有スニペットへ漏れ、他のプロバイダーへ注入されるおそれがありました。抽出は現在、認証情報の形をした環境変数キー（`*_API_KEY` / `*_AUTH_TOKEN` / `*secret*` / `*token*` など）をパターンマッチで除去し、`MAX_OUTPUT_TOKENS` のような正当に共有可能な複数形 `*_TOKENS` の値は保持します。手動の「抽出」と一度きりの自動抽出の経路にあった同じ漏れも、あわせて塞ぎました。
+
+### 使用量スクリプトの認証情報は明示的なオーバーライドとしてのみ永続化
+
+プロバイダーの使用量スクリプトは、クォータ照会時に live の認証情報を上書きする任意の `api_key` / `base_url` フィールドを保持しますが、これらが以前はプロバイダー自身の認証情報を静かにミラーしていました——そのため、プロバイダーを複製したり、メインの API key / base URL を編集したりすると、使用量スクリプトが古い endpoint と key に固定されたまま残り、クォータ照会が古い対象を叩き続けていました。`ProviderService` は現在、永続化の前に正規化します: スクリプトの `api_key` または `base_url` がプロバイダーの解決済み使用量認証情報と一致する（または空の）場合は `None` にクリアして、照会が live 設定へフォールバックするようにします。本当に異なるオーバーライドは保持されます（`token_plan` スクリプトはそのまま）。deeplink インポート経路にも同様の正規化を加え、フロントエンドは更新時に関連するキャッシュキーを無効化して、ホームページが訂正済みの設定で再照会するようにします。（[#4654](https://github.com/farion1231/cc-switch/pull/4654)）
+
+### Hermes 設定ディレクトリが Windows で正しく解決されるように
+
+CC Switch は Hermes の設定ディレクトリとして `~/.hermes` をハードコードしていましたが、Hermes 自身は `HERMES_HOME` 環境変数、次にプラットフォーム既定（Windows では `%LOCALAPPDATA%\hermes`）で解決します。Windows ではこれにより、CC Switch がプロバイダー設定を Hermes が決して読まないパスへ書いていたため、プロバイダーの切り替えが効きませんでした。`get_hermes_dir()` は現在、Hermes 自身の解決順序——明示的なオーバーライド、次に `HERMES_HOME`（そのまま使用、`~` 展開なし）、次にプラットフォーム既定——をミラーし、#3470 が落としていた `HERMES_HOME` を再び尊重します（Hermes の Windows インストーラーは、再配置されたインストールの第一級の仕組みとしてそれを設定します）。（[#4680](https://github.com/farion1231/cc-switch/pull/4680)、#3178、#3470 を参照）
+
+### Linux Wayland: AppImage が強制する `GDK_BACKEND=x11` を上書き可能に
+
+AppImage の GTK 起動フックは、歴史的なネイティブ Wayland のクラッシュを避けるために `GDK_BACKEND=x11` を無条件でエクスポートします。新しめの Wayland + NVIDIA 環境では、この強制された XWayland により WebKitGTK のウェブコンテンツがポインタイベントを受け取れなくなり（タイトルバーは押せてもページは反応しない）、リサイズで黒画面になります。既存の `WEBKIT_DISABLE_*` の緩和策は効きません。根本原因が描画ではなく、強制されたウィンドウバックエンドだからです。`main.rs` は現在、GTK の初期化前に任意の `CC_SWITCH_GDK_BACKEND` 回避スイッチを読みます（AppImage の起動フックはそれに触れません）: 未設定なら現状のまま（回帰ゼロ）。上記の問題に遭遇したら、これを設定してネイティブ Wayland へ切り替えて起動できます:
+
+```bash
+CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
+```
+
+この上書きは汎用です——タイリング系 Wayland コンポジタで逆の入力問題に遭遇する場合は、代わりに `CC_SWITCH_GDK_BACKEND=x11` に設定してください。（[#4351](https://github.com/farion1231/cc-switch/pull/4351)、#4350 を修正）
+
+###「API Key を取得」リンクが Claude Desktop / OpenClaw / Hermes フォームでも表示されるように
+
+API key 入力欄の下の「API Key を取得」リンクとパートナー宣伝ブロックは、以前 claude / codex / gemini / opencode にしか配線されていませんでした。Claude Desktop はそれを表示しない素の入力欄を描画し、OpenClaw / Hermes は 2 つの欠落（ホワイトリストがその 4 つの appId しか列挙しておらず、カテゴリ解析もその 4 つのプリセット id パターンしか認識しなかった）にブロックされていました。Claude Desktop は現在、共有の `ApiKeySection` を使い、ホワイトリストとカテゴリ解析の両方を claude-desktop / openclaw / hermes へ拡張しました。さらに、Hermes / OpenClaw のフォームは「公式」カテゴリで key 入力欄を無効化しなくなりました（これらのアプリには OAuth 専用の公式プロバイダーが存在しません——例えば Hermes の Nous Research は公式ですが、それでもユーザー入力の key が必要です）。
+
+### Windows の Codex npm シムの重複排除
+
+Windows では、npm がツールを 3 つの兄弟ファイル——`codex.cmd`、`codex.exe`、拡張子なしの Unix シム `codex`——としてインストールし、CC Switch は以前この 3 つすべてを候補に列挙していたため、実行できない拡張子なしシムが冗長 / 失敗する候補としてプローブされていました。現在は、隣接する実行可能な `.cmd` / `.exe` の兄弟が見つからない場合にのみ拡張子なしパスを追加し、パス解決も実行可能な `.cmd` / `.exe` を優先して、バージョン検出と起動を実際に実行可能な Windows シムに固定します。（[#4782](https://github.com/farion1231/cc-switch/pull/4782)）
+
+### 長い Select ドロップダウンのスクロール境界
+
+`SelectContent` は以前、高さの上限なしで `overflow-hidden` を使っていたため、選択肢の多いドロップダウン（長いモデル / プロバイダーのリストなど）がビューポートより高く描画され、あふれた項目が切り取られて届かなくなっていました。現在は `max-h-[min(24rem,var(--radix-select-content-available-height))]` と `overflow-y-auto` を設定し、内容を 24rem または Radix が計算した利用可能高さに収め、縦方向のスクロールを許可します。（[#4798](https://github.com/farion1231/cc-switch/pull/4798)）
+
+### 日付範囲セレクタのカレンダーが狭いポップオーバーでも画面内に収まるように
+
+カスタム日付範囲セレクタは以前、2 列レイアウト（日付フィールド | カレンダー）への切り替えを**ビューポート**幅（Tailwind の `sm:` 640px ブレークポイント）で判定していましたが、ポップオーバーは `100vw - 2rem` に制限され、トリガーにアンカーされているため、実際に使える幅はビューポートより狭くなります。狭いウィンドウでは、ポップオーバーに 1 列分しか収まらないのに 2 列レイアウトが有効化されることがあり、カレンダー列が右端の外へ押し出されて切り取られていました（月ヘッダーと 7 列中 4 列の曜日が切れて届かない）。レイアウトは現在、CSS コンテナクエリでポップオーバー自身のインラインサイズに基づいて切り替わるため、ポップオーバー自体が狭いときにちょうど 1 列へ折りたたまれ、どのウィンドウ幅でもカレンダーが完全に見えるようになりました。（[#4860](https://github.com/farion1231/cc-switch/pull/4860)）
+
+---
+
+## ドキュメント
+
+### `CC_SWITCH_GDK_BACKEND` 回避スイッチのドキュメント化
+
+任意の `CC_SWITCH_GDK_BACKEND` 環境変数について、4 言語すべての README と zh / en / ja のユーザーマニュアルのトラブルシューティングページに FAQ 項目を追加し、Wayland + NVIDIA ユーザーがウェブコンテンツの「クリック無反応 + リサイズで黒画面」時にネイティブ Wayland へ切り替える方法、そしてタイリング系 Wayland ユーザーが逆の入力問題で `x11` に設定する方法を解説しました。
+
+### 海外向け Kimi README が platform.kimi.ai を指すように
+
+英語・ドイツ語・日本語の README の Kimi K2.7 Code パートナー段落で、バナーとインラインの行動喚起を `https://platform.kimi.ai?aff=cc-switch` へ向け（紹介タグは維持）、4 言語すべての README に `https://www.kimi.com/code/?aff=cc-switch` へリンクした Kimi For Coding サブスクリプションの宣伝行を追加しました。
+
+---
+
+## アップグレード時の注意
+
+### 既存のネイティブ Codex プロバイダーは一度保存し直しが必要
+
+本リリースは、ネイティブ Responses 直結のモデルカタログ生成を作り直しました。以前にネイティブ Responses（`openai_responses`）を使う Codex プロバイダーを設定していた場合は、新しい `~/.codex/cc-switch-model-catalog.json` を生成するために、**プリセットから選び直すか、プロバイダーを開いて一度保存し直して**ください——それが、Codex デスクトップにカスタムモデルを表示させ、ツールを動かすための鍵です。これはデータベース移行を必要とせず、`openai_chat` 形式のプロバイダーには影響しません。
+
+### `web_search` ブラックリストは既定の挙動
+
+`web_search` を拒否することが分かっている国産ネイティブゲートウェイ（小米 MiMo、美団 LongCat、MiniMax、Qwen3-Coder）に対しては、本リリースが切り替え時に自動で `web_search = "disabled"` を書き込みます。本物の GPT、Doubao、一般の Qwen、そして未知のプロバイダーは影響を受けず、Codex の既定を保ちます。このスイッチは CC Switch が所有権のセンチネルで管理するため、ブラックリストにないプロバイダーへ切り替えて戻せば自動的に復元され、手動の介入は不要です。
+
+### 既定の Sonnet 階層の変化
+
+プリセットから新規作成した Claude 系プロバイダーは、既定の Sonnet 階層が `claude-sonnet-5` を指すようになりました。設定済みの既存プロバイダーは影響を受けず、設定はそのまま保たれます。Sonnet 5 へ切り替えたい場合は、プリセットから選び直して保存してください。
+
+---
+
+## リスク通知
+
+本リリースは、リバースプロキシ系機能に関する以前のリスク通知を引き続き適用します。
+
+**Codex OAuth リバースプロキシ**: ChatGPT サブスクリプションの Codex OAuth をリバースプロキシ経由で使用すると、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 release notes](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
+
+**Codex サードパーティプロバイダー Chat ルーティング**: CC Switch ローカルプロキシで Codex リクエストを変換し、サードパーティプロバイダーへ転送する場合、課金・コンプライアンス・データ保持に関する制約はプロバイダーごとに異なります。利用前に対象プロバイダーの利用規約を確認してください。
+
+**Claude Desktop サードパーティプロバイダープロキシ切り替え**: CC Switch 内蔵のプロキシゲートウェイで Claude Desktop のリクエストをサードパーティプロバイダーへ転送する場合も、対象プロバイダーの課金・コンプライアンス・データ保持に関する規約に従う必要があります。
+
+上記機能を有効化したユーザーは、関連するリスクを自ら負うものとします。CC Switch は、これらの機能の利用によって発生したアカウント制限、警告、サービス停止について責任を負いません。
+
+---
+
+## 謝辞
+
+v3.16.5 で機能と修正を届けてくださった以下のコントリビューターに感謝します：
+
+- [#4776](https://github.com/farion1231/cc-switch/pull/4776): セッションの分類ビューとグループ管理を追加、@alkaid616 に感謝。
+- [#4829](https://github.com/farion1231/cc-switch/pull/4829):「共通設定を書き込む」を「共通設定を適用」へ改名、@arichyx に感謝。
+- [#4654](https://github.com/farion1231/cc-switch/pull/4654): 使用量スクリプトの認証情報を明示的なオーバーライドとしてのみ永続化、@yyhhyyyyyy に感謝。
+- [#4680](https://github.com/farion1231/cc-switch/pull/4680): Windows で Hermes プロバイダー設定が効かない問題を修正、@thisTom に感謝。
+- [#4782](https://github.com/farion1231/cc-switch/pull/4782): Windows の Codex npm シムを重複排除、@justjavac に感謝。
+- [#4798](https://github.com/farion1231/cc-switch/pull/4798): 長いドロップダウンリストがスクロールできない問題を修正、@xwil1 に感謝。
+- [#4351](https://github.com/farion1231/cc-switch/pull/4351): AppImage が強制する `GDK_BACKEND=x11` を `CC_SWITCH_GDK_BACKEND` で上書き可能に、@BoneLiu に感謝。
+- [#4860](https://github.com/farion1231/cc-switch/pull/4860): 日付範囲セレクタのカレンダーが狭いポップオーバーでも画面内に収まるように、@SaladDay に感謝。
+
+v3.16.4 リリース後に Codex ネイティブ直結、共通設定、認証情報の再利用、プラットフォーム互換性の問題を報告してくださったすべてのユーザーにも感謝します。今回の多くのパッチは、こうした実際の利用シーンから得られた再現の手がかりに基づいています。
+
+---
+
+## ダウンロードとインストール
+
+[Releases](https://github.com/farion1231/cc-switch/releases/latest) から、お使いのシステムに対応するビルドをダウンロードしてください。
+
+### システム要件
+
+| システム | 最低バージョン           | アーキテクチャ                      |
+| -------- | ------------------------ | ----------------------------------- |
+| Windows  | Windows 10 以降          | x64 / ARM64                         |
+| macOS    | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
+| Linux    | 下表を参照               | x64 / ARM64                         |
+
+### Windows
+
+| ファイル                                 | 説明                                         |
+| ---------------------------------------- | -------------------------------------------- |
+| `CC-Switch-v3.16.5-Windows.msi`          | **推奨** - 自動更新対応の MSI インストーラー |
+| `CC-Switch-v3.16.5-Windows-Portable.zip` | ポータブル版、展開してそのまま実行できます   |
+
+Windows ARM64 デバイスをお使いの場合は、ファイル名に `arm64` 識別子が含まれる対応する制品を選択してください。
+
+### macOS
+
+| ファイル                         | 説明                                                   |
+| -------------------------------- | ------------------------------------------------------ |
+| `CC-Switch-v3.16.5-macOS.dmg`    | **推奨** - DMG インストーラー、Applications へドラッグ |
+| `CC-Switch-v3.16.5-macOS.zip`    | 展開して Applications へドラッグ、Universal Binary      |
+| `CC-Switch-v3.16.5-macOS.tar.gz` | Homebrew インストールと自動更新用                      |
+
+Homebrew インストール：
+
+```bash
+brew install --cask cc-switch
+```
+
+更新：
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+Linux アセットは **x86_64** と **ARM64**（`aarch64`）の両方を提供します。ファイル名にアーキテクチャ識別子が含まれているため、マシンの `uname -m` 出力に合わせて選択してください：
+
+- `CC-Switch-v3.16.5-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.16.5-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| ディストリビューション                  | 推奨形式    | インストール方法                                                          |
+| --------------------------------------- | ----------- | ------------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` または `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` または `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                   |
+| Arch Linux / Manjaro                    | `.AppImage` | 実行権限を付与して直接起動、または AUR を使用                             |
+| その他 / 不明                           | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`                 |
@@ -0,0 +1,278 @@
+# CC Switch v3.16.5
+
+> 这一版的重头戏是**让原生 Responses 格式的国产模型供应商真正适配到位**——为小米 MiMo、火山豆包、千问 Qwen3-Coder、美团 LongCat、MiniMax 等具备原生 Responses 端点的供应商生成 Codex 模型目录，让 Codex 桌面能看到这些模型、内置工具也能正常工作，并对少数拒收 `web_search` 的国产网关自动禁用该工具、避免请求被硬性拒绝。另有两处重要改进：切换供应商时，你在应用内新增的插件、环境变量等会**自动回写到通用配置并带给下一个供应商**；Linux（Wayland + NVIDIA）上「标题栏能点、页面点不动、缩放黑屏」的问题，现在也能用一个环境变量开关自救。本版还带来 Claude Sonnet 5 定价与默认档升级、两级分组的会话视图，以及一批凭据安全与平台兼容修复。
+
+**[English →](v3.16.5-en.md) | [日本語版 →](v3.16.5-ja.md)**
+
+---
+
+## 使用攻略
+
+本版的新能力主要落在 Codex 供应商表单、会话面板与用量 / 通用配置里，建议结合以下文档了解：
+
+- **[Codex 桌面看不到自定义模型？](../guides/codex-desktop-custom-model-visibility-zh.md)**：本版重做了**原生直连时的模型目录生成**——当 Codex 供应商使用原生 Responses（`openai_responses`）直连时，CC Switch 会生成 `~/.codex/cc-switch-model-catalog.json`，让 Codex 桌面能显示配置的自定义模型、工具也可用。若你此前配过原生 Codex 供应商，请**重新保存一次**以生成新目录（详见下方「升级提醒」）。
+- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：了解用量看板的数据来源与统计口径。本版新增了 Claude Sonnet 5 定价，并修复了用量脚本凭据被当作「显式覆盖」持久化的问题。
+- **[设置](../user-manual/zh/1-getting-started/1.5-settings.md)**：Codex 上游格式选择器与本地路由开关、Claude 通用配置（现更名为「应用通用配置」并支持切换时自动同步）都在供应商表单的高级选项里。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一官方渠道声明（请务必阅读）
+>
+> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。请仅通过下列官方渠道获取本软件：
+>
+> | 类别     | 唯一官方                                                                       |
+> | -------- | ------------------------------------------------------------------------------ |
+> | 官网     | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | 源码     | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | 下载     | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者     | **[@farion1231](https://github.com/farion1231)**                               |
+> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。
+
+---
+
+## 概览
+
+CC Switch v3.16.5 是 v3.16.4 之后的一版维护更新，核心是把**国产模型供应商的 Codex 原生直连做通**。v3.16.4 已经把千问 / 百炼、小米 MiMo、火山豆包、美团 LongCat、MiniMax 等供应商切到了原生 Responses 端点，本版进一步为它们生成 Codex 所需的**模型目录**（`~/.codex/cc-switch-model-catalog.json`），让 Codex 桌面真正能看到这些自定义模型、内置工具也能正常调用，并把模型映射从「本地路由」开关里彻底解耦。针对少数第一方模型不支持 OpenAI 内置 `web_search` 的国产网关（MiMo、LongCat、MiniMax、Qwen3-Coder），本版还会自动禁用该工具，避免 Codex 默认带上它触发硬 400。
+
+围绕日常使用体验，本版让 Claude 的**通用配置在切换供应商时自动同步并传递**——你在应用内新增的插件、环境变量、主题等会先回写到通用配置、再带给下一个供应商，不会在切换时丢失；给 Linux（Wayland + NVIDIA）上点击失灵 / 黑屏的用户加了一个可自救的环境变量开关；补上 Claude Sonnet 5 定价并把默认 Sonnet 档升级到它；带来「供应商 → 项目目录」两级分组的会话视图；并修了一串凭据安全（通用配置片段剥离全部密钥、用量脚本凭据仅作显式覆盖）、平台兼容（Hermes Windows 配置目录、Windows Codex npm 影子命令）与界面（长下拉滚动、窄窗口日期选择器）的问题。此外也新增了若干供应商预设，开箱即可选用。
+
+**发布日期**：2026-07-01
+
+**更新规模**：36 commits | 93 files changed | +5,678 / -2,804 lines
+
+---
+
+## 重点内容
+
+- **让国产模型供应商的 Codex 原生直连真正可用**：为小米 MiMo、火山豆包、千问 Qwen3-Coder、美团 LongCat、MiniMax 等国产供应商生成 Codex 模型目录（`~/.codex/cc-switch-model-catalog.json`），让 Codex 桌面能看到这些模型、内置工具可用；并对拒收 `web_search` 的国产网关（MiMo、LongCat、MiniMax、Qwen3-Coder）自动禁用该工具、避免硬 400。**存量原生供应商需重存一次**以生成新目录。
+- **通用配置切换时自动同步并传递**：切走一个启用了通用配置的 Claude 供应商时，你在应用内新增的插件、环境变量、主题、hooks 会先自动回写到通用配置，再带给下一个供应商——不再在切换时被覆盖丢失。
+- **Linux Wayland 点击失灵 / 黑屏的自救开关**：遇到 Wayland + NVIDIA 上「标题栏能点、页面点不动、缩放黑屏」时，用 `CC_SWITCH_GDK_BACKEND=wayland` 启动即可切回原生 Wayland（平铺式合成器上遇到反向问题可设为 `x11`）。
+- **Claude Sonnet 5**：新增 Sonnet 5 定价，并把各预设的默认 Sonnet 档升级到 `claude-sonnet-5`。
+- **会话分类视图与分组管理**：会话面板新增「供应商 → 项目目录」两级分组视图，分组头支持三态复选框一键批量选择。
+- **新增供应商预设**：新增七牛云、FennoAI、ZetaAPI、TeamoRouter、NekoCode、Code0.ai、Amux 等供应商预设，覆盖各受管应用，开箱即可选用。
+
+---
+
+## 新功能
+
+### 国产模型供应商的 Codex 原生直连（生成模型目录）
+
+本版把国产供应商的 Codex 原生直连做通了。继 v3.16.4 把小米 MiMo、火山豆包、千问 Qwen3-Coder、美团 LongCat、MiniMax 等供应商切换到原生 Responses（`apiFormat: "openai_responses"`）之后，本版推翻了当时「原生直连就删掉模型目录」的做法：这些供应商不经过本地代理直连时，CC Switch 会为它们生成 `~/.codex/cc-switch-model-catalog.json`，让 Codex 桌面真正显示这些自定义模型、内置工具也能用——不会触发像 MiMo 这类原生网关会拒绝的 freeform `apply_patch`（`type=custom`）工具（编辑回退到 `shell_command`）。目录生成按 `apiFormat` 判定、与「本地路由」开关解耦，因此一个原生供应商无需开启本地路由映射也会持久化目录；而 `openai_chat` 格式仍保持既有的 Responses↔Chat 代理转换不变。由于 Codex 解析器要求每个条目都带 `base_instructions`，原生模板携带一个中性默认值、由各厂商官方文案覆盖（MiMo、MiniMax）。**存量原生供应商需重新保存一次以生成有效目录**（无需数据库迁移）。
+
+配套地，对少数第一方模型不支持 OpenAI 内置 `web_search` 工具的国产网关（MiMo、LongCat、MiniMax、Qwen3-Coder），本版会在切换时自动禁用该工具，避免 Codex 默认带上它、被网关以硬 400 拒绝（详见下方「修复」）。
+
+### 会话分类视图与分组管理
+
+会话管理面板在原有平铺列表之外新增了分组视图，通过工具栏的 List / ListTree 选择器切换，视图模式与展开状态都持久化到 `localStorage`。分组构建「供应商 → 项目目录」两级层级：按项目目录名归组，缺少项目目录的会话落入「未知目录」桶。两级都是可折叠区块，并提供「全部折叠」按钮；在批量模式下，每个分组头会出现一个三态复选框，可一键选中 / 取消该组内全部可选会话，并显示已选 / 可选计数徽标。四语（zh / en / ja / zh-TW）文案已同步。该改动完全在前端，不涉及后端命令或数据访问层。（[#4776](https://github.com/farion1231/cc-switch/pull/4776)）
+
+### Claude Sonnet 5 模型定价
+
+在 `schema.rs` 里按 Anthropic list 价新增 `claude-sonnet-5` 定价行——输入 / 输出 \$3 / \$15 每百万 token、缓存读写 \$0.30 / \$3.75，与 Sonnet 4.6 一致。介绍期 \$2 / \$10 促销（有效期至 2026-08-31）刻意不入表，让记账反映稳态 list 价而非临时折扣。该行在应用下次启动时通过 `ensure_model_pricing_seeded` 应用，无需 `SCHEMA_VERSION` 变更。
+
+### 新增供应商预设
+
+本版新增了一批供应商预设，选中后填入自己的 API Key 即可使用：
+
+- **七牛云（Qiniu）**：覆盖全部 7 个受管应用（含 Gemini），中转原生 Claude / GPT / Gemini。
+- **FennoAI / ZetaAPI / TeamoRouter / NekoCode**：各覆盖 6 个应用（Claude、Claude Desktop、Codex、OpenCode、OpenClaw、Hermes）。
+- **Code0.ai**：覆盖全部 7 个应用（含 Gemini）。
+- **Amux**：覆盖 6 个应用。
+
+各预设的端点与默认模型已按对应应用配好——Claude 类走 Anthropic 兼容主机直连、Codex 走原生 Responses、其余走 OpenAI 兼容 `/v1`。
+
+---
+
+## 变更
+
+### 切换供应商时自动同步并传递通用配置
+
+这是本版一个很实用的改动：切走一个启用了通用配置的 Claude 供应商时，服务会先从它的 live `settings.json` 里**重新提取可共享部分、更新到通用配置**，再带给下一个供应商，而不再只是单向写入。这样一来，你在运行中的应用里直接新增的插件（`enabledPlugins`）、hooks、环境变量（`env`）、主题（`theme`）等共享配置就不会在切换时被静默丢失，而是自动跟着走到下一个供应商；删除也会同步（移除的键不会被再次注入）。该同步严格限定在启用了通用配置的 Claude 供应商，被显式清空时会跳过，且所有失败都是非致命（仅告警）、永不阻断切换。
+
+### Codex 模型映射与「本地路由」开关解耦
+
+Codex 供应商表单向 Claude Code 对齐——模型映射目录现在独立于路由接管，因为原生 Responses 供应商（MiMo、豆包、MiniMax）需要它来做无代理直连，而 Chat 供应商无论如何都走代理。「需要本地路由」开关被移除（它没有后端字段，只是门控目录 / 推理的持久化，等价于「映射是否填了」）。模型映射现在对非官方供应商始终显示、非空即持久化，而推理能力的显示 / 持久化改由 Chat 格式门控。四语（zh / en / ja / zh-TW）文案随之重写。顺带修复了 `useCodexConfigState` 在加载已存供应商时丢掉 `supportsParallelToolCalls` / `inputModalities` / `baseInstructions` 的问题（会在编辑时静默丢失并行工具、图像输入与官方 base instructions）。
+
+### 默认 Sonnet 档升级到 Claude Sonnet 5
+
+把各供应商预设里的默认 Sonnet 档从 `claude-sonnet-4-6` 升级到 `claude-sonnet-5`（覆盖 claude / claude-desktop / hermes / openclaw / opencode 预设与通用 `NEWAPI_DEFAULT_MODELS`），涉及 `ANTHROPIC_MODEL` / `ANTHROPIC_DEFAULT_SONNET_MODEL` / `ANTHROPIC_DEFAULT_OPUS_MODEL` 等键及其带前缀变体。Claude Desktop 的默认路由 sonnet `route_id` 也一并迁移到 `claude-sonnet-5`。非 Anthropic 的 pin（gpt / gemini / glm / sonnet-4-5）保持不变。
+
+### 豆包带日期 model id 与定价归一化
+
+豆包（DouBaoSeed）预设的 model id 切换到带日期的 `doubao-seed-2-1-pro-260628`（覆盖各应用），因为火山方舟会以 404 拒绝裸名 `doubao-seed-2-1-pro`、只接受完整带日期 id。由于真实用量现在带日期后缀，`strip_model_date_suffix` 扩展为也能剥掉火山的 6 位 YYMMDD 形式（并校验月 01-12、日 01-31 以免误伤 `-123456` 这类非日期版本后缀），从而归一化命中定价表里的裸名 seed 行、修复豆包模型显示 \$0 成本的问题。
+
+###「写入通用配置」更名为「应用通用配置」
+
+原标签「写入通用配置」在数据流向上有歧义（读起来像「把当前配置写进通用配置」），而实际行为相反——是把已存的通用配置片段合并进本供应商配置。复选框在四语（zh / en / ja / zh-TW）里更名为「应用通用配置」，包括所有提示 / 攻略 / 说明引用，日文用户手册与 `README_JA.md` 也一并同步。（[#4829](https://github.com/farion1231/cc-switch/pull/4829)）
+
+### 其它预设与资源调整
+
+- **OpenClaw 豆包上下文对齐 262144**：OpenClaw 的 DouBaoSeed 预设此前硬编码 128000，而 Codex 侧同模型用 262144，导致 OpenClaw 用户窗口偏小；已对齐并加了跨预设一致性测试防止再次漂移。
+- **火山 / 豆包 / BytePlus 官网链接订正**：这三个预设的「访问官网」链接被误设成了控制台 / 注册链接，已恢复为干净的产品主页。
+- **过大的供应商图标降采样到 256px**：一批捆绑图标此前远大于其 ~32px 的实际渲染尺寸，降采样后显著减小体积、无代码 / 文件名 / 导入改动（如 ZetaAPI 940KB→40KB、relaxcode 1.16MB→42KB），并删除了从未被引用的 1.4MB `dds.svg` 孤儿。
+
+---
+
+## 修复
+
+### 对拒收 `web_search` 的原生 Codex 网关禁用该工具
+
+一些原生 `/responses` 网关的第一方模型不具备 OpenAI 内置的 `web_search` 工具，会以「tool type 'web_search' is not supported」拒绝，而 Codex 默认就会带上该工具，导致硬 400。CC Switch 现在会为这些厂商写入顶层 TOML 行 `web_search = "disabled"`。作用域是一份黑名单（默认开启）：仅命中 `base_url` 主机（`xiaomimimo.com`、`longcat.chat`、`minimax.io`、`minimaxi.com`）或模型品牌前缀（`mimo`、`longcat`、`minimax`、`qwen3-coder`）的供应商会被禁用，因此中转真 GPT、豆包、通用 Qwen 及任何未知供应商都保持 Codex 默认。其中 `qwen3-coder` 前缀只压制原生 `qwen3-coder-plus`（百炼 / DashScope 对 coder 系标记内置工具不支持），共享同一主机的通用 Qwen 保持开启；匹配走模型轴（会剥掉聚合器的 `vendor/` 路径段），因此也能兜住硅基流动这类中转拒收厂商模型的情形。选黑名单而非模糊的「是不是 GPT」白名单，是因为误让 `web_search` 保持开启会以硬 400 失败；同时用归属哨兵保证 CC Switch 只会移除由它自己写入的 `disabled` 值，因此存量供应商无需重存、切回也会重新启用。此外顺带把 LongCat-2.0-Preview 预设的上下文窗口从 131072（128K）订正为真实的 1048576（1M）。
+
+### 通用配置片段剥离全部凭据类键
+
+`extract_claude_common_config` 此前只脱敏 `ANTHROPIC_API_KEY` 与 `ANTHROPIC_AUTH_TOKEN`，但 Claude 供应商合法地携带其它凭据（`OPENROUTER_API_KEY`、`GOOGLE_API_KEY`，可能还有 OpenAI / Gemini / AWS Bedrock / Vertex 密钥），这些可能泄漏进共享片段、再被注入到其它供应商。提取现在会按模式匹配并剥掉任何凭据形态的环境变量键（`*_API_KEY` / `*_AUTH_TOKEN` / `*secret*` / `*token*` 等），同时保留 `MAX_OUTPUT_TOKENS` 这类合法可共享的复数 `*_TOKENS` 值。手动「提取」与一次性自动提取路径的同一泄漏也一并堵上。
+
+### 用量脚本凭据仅作显式覆盖持久化
+
+供应商用量脚本存有可选的 `api_key` / `base_url` 字段用于查询配额时覆盖 live 凭据，但它们此前会静默镜像供应商自身的凭据——因此复制供应商或修改主 API key / base URL 后，用量脚本仍 pin 在旧端点旧 key，配额查询一直打向陈旧目标。现在 `ProviderService` 在持久化前会归一化：若脚本的 `api_key` 或 `base_url` 与供应商解析出的用量凭据相同（或为空）就清为 `None`，让查询回退到 live 配置；真正不同的覆盖才保留（`token_plan` 类脚本不动）。deeplink 导入路径也加了对应的归一化，前端在更新时会失效相关缓存键让首页用修正后的配置重新查询。（[#4654](https://github.com/farion1231/cc-switch/pull/4654)）
+
+### Hermes 配置目录在 Windows 上正确解析
+
+CC Switch 此前硬编码 `~/.hermes` 作为 Hermes 配置目录，但 Hermes 自身是按 `HERMES_HOME` 环境变量、再退到平台默认（Windows 上 `%LOCALAPPDATA%\hermes`）解析的。在 Windows 上这意味着 CC Switch 把供应商配置写到了 Hermes 根本不读的路径，导致供应商切换无效。`get_hermes_dir()` 现在镜像 Hermes 自己的解析顺序——显式覆盖、`HERMES_HOME`（原样取用、不做 `~` 展开）、平台默认——从而重新尊重被 #3470 丢掉的 `HERMES_HOME`（Hermes 的 Windows 安装器把它作为重定位安装的首要机制）。（[#4680](https://github.com/farion1231/cc-switch/pull/4680)，参见 #3178、#3470）
+
+### Linux Wayland：允许覆盖 AppImage 强制的 `GDK_BACKEND=x11`
+
+AppImage 的 GTK 启动钩子无条件导出 `GDK_BACKEND=x11` 以规避一个历史上的原生 Wayland 崩溃。在较新的 Wayland + NVIDIA 环境上，这个被强制的 XWayland 会让 WebKitGTK 网页内容收不到指针事件（标题栏可点、页面却死了）、并在缩放时黑屏，而既有的 `WEBKIT_DISABLE_*` 缓解不起作用，因为根因是被强制的窗口后端而非渲染。`main.rs` 现在会在 GTK 初始化前读取一个可选的 `CC_SWITCH_GDK_BACKEND` 逃生开关（AppImage 的启动钩子从不改动它）：不设保持现状（零回归）。遇到上述问题时，用它切回原生 Wayland 启动即可：
+
+```bash
+CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage
+```
+
+该覆盖是通用的——若你在平铺式 Wayland 合成器上遇到的是反向的输入问题，则改设为 `CC_SWITCH_GDK_BACKEND=x11`。（[#4351](https://github.com/farion1231/cc-switch/pull/4351)，修复 #4350）
+
+### Claude Desktop / OpenClaw / Hermes 表单显示「获取 API Key」链接
+
+API key 输入框下的「获取 API Key」链接与合作推广块此前只对 claude / codex / gemini / opencode 生效。Claude Desktop 渲染的是不显示它的裸输入框，而 OpenClaw / Hermes 则被两处遗漏挡住（白名单只列了那四个 appId、供应商分类解析只认那四类预设 id 模式）。现在 Claude Desktop 改用共享的 `ApiKeySection`，白名单与分类解析都补上了 claude-desktop / openclaw / hermes；此外 Hermes / OpenClaw 表单不再让「官方」分类禁用 key 输入（这两个应用没有只走 OAuth 的官方供应商，如 Hermes 的 Nous Research 虽是官方但仍需用户自填 key）。
+
+### 去重 Windows 上的 Codex npm 影子命令
+
+在 Windows 上，npm 会把一个工具装成三个同名兄弟文件——`codex.cmd`、`codex.exe` 和一个无扩展名的 Unix shim `codex`——而 CC Switch 此前把三者都列为候选，导致无法直接执行的无扩展名 shim 被当作多余 / 失败候选去探测。现在仅当相邻没有可执行的 `.cmd` / `.exe` 兄弟时才追加无扩展名路径，路径解析也会优先选可执行的 `.cmd` / `.exe`，从而把版本探测与启动锚定到真正可运行的 Windows shim 上。（[#4782](https://github.com/farion1231/cc-switch/pull/4782)）
+
+### 长下拉列表的滚动边界
+
+`SelectContent` 弹层此前用 `overflow-hidden` 且没有高度上限，因此选项很多的下拉（如长模型 / 供应商列表）会渲染得比视口还高、把溢出项裁掉且无法触及。现在它设了 `max-h-[min(24rem,var(--radix-select-content-available-height))]` 与 `overflow-y-auto`，把内容限制在 24rem 或 Radix 计算出的可用高度内并允许纵向滚动。（[#4798](https://github.com/farion1231/cc-switch/pull/4798)）
+
+### 日期范围选择器的日历在窄弹层里保持可见
+
+自定义日期范围选择器此前按**视口宽度**（Tailwind `sm:` 640px 断点）切换两列布局（日期字段 | 日历），但弹层被夹在 `100vw - 2rem` 且锚定到触发器，实际可用宽度比视口窄。在窄窗口上，两列布局可能在弹层只放得下一列时被激活，把日历列挤出右边界裁掉（月份头与 7 列里的 4 列被切掉且无法触及）。现在布局改用 **CSS 容器查询**按弹层自身的行内尺寸切换，因此只有当弹层本身窄时才收成一列，让日历在任意窗口宽度下都完整可见。（[#4860](https://github.com/farion1231/cc-switch/pull/4860)）
+
+---
+
+## 文档
+
+### `CC_SWITCH_GDK_BACKEND` 逃生开关文档
+
+为可选的 `CC_SWITCH_GDK_BACKEND` 环境变量新增了 FAQ 条目，覆盖全部四种 README 语言与 zh / en / ja 用户手册的排障页，说明 Wayland + NVIDIA 用户如何在网页内容「点击失灵 + 缩放黑屏」时切回原生 Wayland，以及平铺式 Wayland 用户如何设为 `x11` 处理反向输入问题。
+
+### Kimi 海外 README 指向 platform.kimi.ai
+
+英语、德语、日语 README 的 Kimi K2.7 Code 合作段落的横幅与内联行动号召改指 `https://platform.kimi.ai?aff=cc-switch`（保留推荐标签），四语 README 也都新增了一行指向 `https://www.kimi.com/code/?aff=cc-switch` 的 Kimi For Coding 订阅推广。
+
+---
+
+## 升级提醒
+
+### 原生 Codex 供应商需重存一次
+
+本版重做了原生 Responses 直连的模型目录生成。如果你此前配过使用原生 Responses（`openai_responses`）的 Codex 供应商，请**重新从预设选择或打开该供应商并保存一次**，以生成新的 `~/.codex/cc-switch-model-catalog.json`——这样 Codex 桌面才能显示自定义模型、工具才可用。此过程无需数据库迁移，也不影响走 `openai_chat` 格式的供应商。
+
+### `web_search` 黑名单是默认行为
+
+对小米 MiMo、美团 LongCat、MiniMax、千问 Qwen3-Coder 这些已知拒收 `web_search` 的原生网关，本版会在切换时自动写入 `web_search = "disabled"`。中转真 GPT、豆包、通用 Qwen 及未知供应商不受影响、保持 Codex 默认。该开关由 CC Switch 用归属哨兵管理，切回到未命中黑名单的供应商会自动恢复，无需手动干预。
+
+### 默认 Sonnet 档变化
+
+新从预设创建的 Claude 类供应商，其默认 Sonnet 档现在指向 `claude-sonnet-5`。已配置好的存量供应商不受影响、配置保持原样；如需改用 Sonnet 5，可重新从预设选择一次并保存。
+
+---
+
+## 风险提示
+
+本版本继续沿用此前版本对反向代理类功能的风险提示。
+
+**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
+
+**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
+
+**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，同样需要遵守目标供应商的计费、合规与数据留存约束。
+
+用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
+
+---
+
+## 致谢
+
+感谢以下贡献者在 v3.16.5 中提交的功能与修复：
+
+- [#4776](https://github.com/farion1231/cc-switch/pull/4776)：新增会话分类视图与分组管理，感谢 @alkaid616。
+- [#4829](https://github.com/farion1231/cc-switch/pull/4829)：把「写入通用配置」更名为「应用通用配置」，感谢 @arichyx。
+- [#4654](https://github.com/farion1231/cc-switch/pull/4654)：让用量脚本凭据仅作显式覆盖持久化，感谢 @yyhhyyyyyy。
+- [#4680](https://github.com/farion1231/cc-switch/pull/4680)：修复 Windows 上 Hermes 供应商配置不生效，感谢 @thisTom。
+- [#4782](https://github.com/farion1231/cc-switch/pull/4782)：去重 Windows 上的 Codex npm 影子命令，感谢 @justjavac。
+- [#4798](https://github.com/farion1231/cc-switch/pull/4798)：修复长下拉列表无法滚动，感谢 @xwil1。
+- [#4351](https://github.com/farion1231/cc-switch/pull/4351)：允许通过 `CC_SWITCH_GDK_BACKEND` 覆盖 AppImage 强制的 `GDK_BACKEND=x11`，感谢 @BoneLiu。
+- [#4860](https://github.com/farion1231/cc-switch/pull/4860)：让日期范围选择器的日历在窄弹层里保持可见，感谢 @SaladDay。
+
+也感谢所有在 v3.16.4 发布后反馈 Codex 原生直连、通用配置、凭据复用与平台兼容性问题的用户，很多补丁都来自这些真实使用场景里的复现线索。
+
+---
+
+## 下载与安装
+
+访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
+
+### 系统要求
+
+| 系统    | 最低版本                   | 架构                                |
+| ------- | -------------------------- | ----------------------------------- |
+| Windows | Windows 10 及以上          | x64 / ARM64                         |
+| macOS   | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | 见下表                     | x64 / ARM64                         |
+
+### Windows
+
+| 文件                                     | 说明                                |
+| ---------------------------------------- | ----------------------------------- |
+| `CC-Switch-v3.16.5-Windows.msi`          | **推荐** - MSI 安装包，支持自动更新 |
+| `CC-Switch-v3.16.5-Windows-Portable.zip` | 便携版，解压即用，不写入注册表      |
+
+Windows ARM64 设备请选择文件名中带 `arm64` 标识的对应制品。
+
+### macOS
+
+| 文件                             | 说明                                          |
+| -------------------------------- | --------------------------------------------- |
+| `CC-Switch-v3.16.5-macOS.dmg`    | **推荐** - DMG 安装包，拖入 Applications 即可 |
+| `CC-Switch-v3.16.5-macOS.zip`    | 解压后拖入 Applications，Universal Binary     |
+| `CC-Switch-v3.16.5-macOS.tar.gz` | 用于 Homebrew 安装和自动更新                  |
+
+Homebrew 安装：
+
+```bash
+brew install --cask cc-switch
+```
+
+更新：
+
+```bash
+brew upgrade --cask cc-switch
+```
+
+### Linux
+
+Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本：
+
+- `CC-Switch-v3.16.5-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.16.5-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| 发行版                                  | 推荐格式    | 安装方式                                                               |
+| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                    | `.AppImage` | 添加执行权限后直接运行，或使用 AUR                                     |
+| 其他发行版 / 不确定                     | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |
@@ -0,0 +1,366 @@
+# CC Switch v3.17.0
+
+> This release brings a long-awaited capability: **one-click "Projects" switching** — save your current provider, MCP, Skills, and memory files as a single named snapshot, swap the whole set for another one from the title bar or tray with a single click, and have the state of the project you're leaving automatically saved back on the way out. The Codex side gets plenty too: **your official ChatGPT subscription account can now route through the local proxy as well**, getting the same routing and usage statistics as third-party providers; the GPT-5.6 family's context window and Sol / Terra / Luna three-tier pricing land in one step; and a native Anthropic Messages upstream format is added — is Claude Code banned at your company but the Claude API isn't? You can now **use Claude-family models directly inside Codex**. On top of that comes a big wave of correctness fixes: upstream failures no longer turn into "empty replies", cache-write tokens are no longer double-billed, deleted MCP servers no longer come back from the dead, and Kimi For Coding's 256K window finally takes effect for real.
+
+**[中文版 →](v3.17.0-zh.md) | [日本語版 →](v3.17.0-ja.md)**
+
+---
+
+## Usage Guides
+
+The new capabilities in this release land mainly in the project switcher at the top of the home page, the Codex provider form, and the usage dashboard. The following docs are worth reading alongside it:
+
+- **[Using Claude in Codex (local routing guide)](../guides/codex-claude-routing-guide-en.md)**: a new step-by-step guide for this release's native Anthropic Messages upstream. It walks through setting a Codex provider's upstream format to `anthropic` to connect to any Claude-family gateway that only offers `/v1/messages`, and use Claude-family models inside Codex.
+- **[Using Kimi inside Codex (local routing guide)](../guides/codex-kimi-routing-guide-en.md)**: a new step-by-step guide added in this release. Newer Codex CLI speaks the OpenAI Responses protocol, while the Kimi Open Platform and Kimi For Coding expose Chat Completions endpoints, so a direct connection usually 404s; the guide walks through using the built-in `Kimi` / `Kimi For Coding` presets together with local routing to handle the protocol conversion.
+- **[Codex Official Login Preservation](../guides/codex-official-auth-preservation-guide-en.md)**: understand how CC Switch preserves your official ChatGPT login when you switch to a third-party provider. This release goes a step further — the official account itself can now route through the proxy too (see "Added" below).
+- **[Usage Statistics](../user-manual/en/4-proxy/4.4-usage.md)**: understand the Usage Dashboard's data sources and how the statistics are counted. This release fixes cache-write billing, fills in Codex subagent session accounting, and adds GPT-5.6 and Hunyuan Hy3 pricing.
+
+---
+
+> [!WARNING]
+>
+> ## Only Official Channels (Please Read)
+>
+> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Please only obtain the software through the official channels listed below:
+>
+> | Channel            | Only Official                                                                  |
+> | ------------------ | ------------------------------------------------------------------------------ |
+> | Website            | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | Source             | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | Downloads          | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | Author             | **[@farion1231](https://github.com/farion1231)**                               |
+> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues.
+
+---
+
+## Overview
+
+CC Switch v3.17.0 is a major feature release following v3.16.5, centered on **Projects**: you can save the current provider, MCP, Skills, and memory-file state of Claude Code / Claude Desktop / Codex as a named snapshot — say a "Development" set for a coding directory and a "Drawing" set for a writing-and-drawing directory — and swap the whole set with one click from the switcher at the top of the home page or the "Projects" tray submenu. Before you switch, the state of the project you're about to leave is automatically saved back, so a project always holds exactly what you last left it as. The second main thread is Codex: **your official ChatGPT subscription account can now be taken over by the local proxy route** (no API key needed — Codex's own login credentials are passed through verbatim and your official login is never overwritten); paired with a corrected client identity, the latest subscription models like `gpt-5.6-luna` no longer falsely 404; GPT-5.6's 372K context-window injection, Sol / Terra / Luna three-tier pricing (including the 1.25× cache-write rate), and preset default models all land together; and the Codex upstream format gains a native Anthropic Messages protocol — which targets a very real scenario: plenty of companies ban the Claude Code client but do **not** ban the Claude API, and those users can now point Codex directly at the Claude API (or any gateway that only offers `/v1/messages`) and keep using Claude-family models inside Codex.
+
+For everyday-use correctness, this release makes three concentrated waves of fixes. **Proxy bridge**: semantic failures returned inside a 2xx are no longer turned into an empty reply but trigger failover instead; reasoning content, tool results, and the system role round-trip losslessly across the Responses↔Anthropic bridge; prompt-cache breakpoint injection is more thorough, so long conversations no longer resend everything at full price each turn. **Usage billing**: cache-write tokens were previously billed twice — once at the input rate and once at the cache-creation rate — and are now corrected (the database is upgraded to schema v13 so historical data stays consistent); usage and quota queries automatically retry on transient network failures and no longer cache a failure body as real data. **Codex `config.toml`**: MCP servers you deleted in the app no longer come back on provider switch; when parsing a live file fails, sync errors out rather than blanking the whole file; and the "Apply Common Config" merge is moved to the backend so comments and key order are no longer scrambled. Also included: Kimi For Coding's 256K window finally taking effect, Codex subagent and free-tier quota accounting filled in, Zhipu team-plan quota queries, OpenCode form enhancements, and a batch of preset updates.
+
+**Release date**: 2026-07-13
+
+**Stats**: 69 commits | 172 files changed | +21,067 / -2,464 lines
+
+---
+
+## Highlights
+
+- **One-click "Projects" switching**: save your provider, MCP, Skills, and memory files as a single named snapshot (say one set for coding, another for writing and drawing) and swap the whole thing with one click from the top of the home page or the tray; the state of the project you leave is saved back automatically on switch. Covers three scopes — Claude Code, Claude Desktop, and Codex — that don't interfere with one another.
+- **Official Codex account can route through the proxy too**: a Codex session logged in with a ChatGPT subscription can now route through the local proxy, getting routing and usage statistics identical to third-party providers; the official login credentials are never overwritten or stored.
+- **GPT-5.6 fully in place**: a 372K context window is auto-injected when Claude Code routes through Codex takeover; Sol / Terra / Luna three-tier pricing is seeded (cache writes billed at 1.25× the input rate); the relevant presets' default models are bumped to the gpt-5.6 family; and, with the client identity corrected, `gpt-5.6-luna` no longer falsely 404s.
+- **Use Claude-family models inside Codex (native Anthropic Messages upstream)**: plenty of companies ban the Claude Code client but not the Claude API — now, by setting a Codex provider's upstream format to `anthropic`, you can connect directly to the Claude API or any gateway that only offers `/v1/messages`, with the local proxy handling the two-way Responses↔Anthropic conversion and standard 5-minute prompt-cache injection built in.
+- **Proxy bridge correctness fixes**: upstream failures fail closed and trigger failover instead of an empty reply; reasoning / tool results / the system role survive the bridge losslessly; cache writes are no longer double-billed; breakpoint injection is more thorough.
+- **Codex config.toml hardening**: deleted MCP servers no longer come back; MCP sync errors out rather than blanking the file on a parse failure; common-config merges preserve comments and key order.
+- **Kimi For Coding 256K finally works**: the previous 262144 compaction window never actually took effect (clamped back to Claude Code's 200K default); this release fills in the model-alias routing and window injection; existing providers need to re-apply the preset (see "Upgrade Notes").
+
+---
+
+## Added
+
+### Projects: Named Snapshots of a Whole Configuration, Switched in One Click
+
+This is the headline feature of the release. You can save your current provider, MCP, Skills, and memory-file state as a named "project", then swap the whole set with one click from the project switcher at the top of the home page or the "Projects" tray submenu, instead of toggling each piece by hand.
+
+Here's a typical scenario: you have one directory for coding and another for writing or drawing. Coding wants one provider, plus MCP like filesystem / GitHub, code-review Skills, and a memory file spelling out your engineering conventions; writing or drawing often wants a different provider, a different set of MCP, and completely different prompts. Bouncing between the two used to mean switching providers, toggling MCP and Skills one by one, and then editing the memory file; now you save the two states as two projects — "Development" and "Drawing" — and when you switch directories to work, one click in CC Switch puts the whole configuration in place.
+
+Projects span three scopes — Claude Code, Claude Desktop, and Codex (the only dimension CC Switch manages for Claude Desktop is the provider, so its snapshots contain only the provider and applying one touches no other dimension).
+
+A few design points worth knowing:
+
+- **Projects are global entities, switched per scope**: the same project records its own current project and snapshot slot separately on the Claude Code / Claude Desktop / Codex sides, so switching projects on the Codex tab never touches Claude's configuration.
+- **Switching auto-saves**: before you switch projects, the state of the project you're about to leave in the current scope is first saved back automatically — so a project always holds exactly what you last left it as, with no (and no need for a) manual "update snapshot" button.
+- **Applying is best-effort**: applying a snapshot reuses the existing switch primitives (switch the provider first, then do the minimal MCP / Skills diff toggles, then enable memory files); if something a snapshot references has been deleted, it's only warned and skipped, never rolled back wholesale.
+- **Auto-disables proxy takeover**: before applying a project, proxy takeover for each app in that scope is disabled first, to avoid the snapshot state fighting with the routing state.
+
+If you don't use Projects, you can turn off "Show project switcher" under Settings → Home Display, which only hides the home-page entry — the tray submenu and project data are unaffected. It's backed by a new `profiles` table (the database migrates automatically, no manual steps), with UI copy in sync across all four locales.
+
+### Proxy Route Takeover for the Official Codex ChatGPT Account
+
+A Codex session using a ChatGPT subscription (OAuth or API-key login) can now route through CC Switch's local proxy too — official-account traffic gets routing, format conversion, and usage statistics identical to third-party providers. Just pick the built-in "OpenAI Official" entry in the provider panel or tray to take it over (if you deleted it before, it's restored automatically when you add a provider); the card badge shows "Official account routing" while routing.
+
+The implementation deliberately achieves **zero credential storage**: instead of writing any placeholder key to `auth.json`, it projects a dedicated `model_provider` pointing at the local proxy into `config.toml`, and Codex sends its own ChatGPT authorization header to the proxy, which passes it through verbatim to the official endpoint — the credentials on the `codex-official` line are always empty. The official login itself is never overwritten: on takeover, OAuth / API-key material is preserved into the backup, and a 401 / 403 from the official side is treated as a non-retryable error, so failover never quietly moves your conversation to another account. Accordingly, the copy for the "Preserve Codex official login on switch" setting has been updated — under route takeover the official login is always preserved, so that toggle now only governs third-party direct switches that don't route through the proxy.
+
+### GPT-5.6: Context Window, Preset Defaults, and Three-Tier Pricing
+
+Three things were done around the GPT-5.6 family:
+
+- **372K context-window injection**: when Claude Code routes to the ChatGPT Codex (Codex OAuth) backend through proxy takeover, `CLAUDE_CODE_MAX_CONTEXT_TOKENS` and `CLAUDE_CODE_AUTO_COMPACT_WINDOW` (both 372000) are auto-injected into the live `settings.json`, so Claude Code no longer auto-compacts prematurely at its default 200K window nor overflows the upstream. The injection is strictly gated: it only injects when every configured model key points at the gpt-5.6 family (gpt-5.5's catalog window swings between 272K and 372K, so it's deliberately not inherited); your manually set values always win; and it's stripped on switch-away under mirrored conditions, so a program default is never baked into your provider config.
+- **Preset default-model bump**: the Codex OAuth presets for Claude Code and Claude Desktop bump their default routes to the gpt-5.6 family (haiku → `gpt-5.6-luna`, main model / sonnet / opus → `gpt-5.6`), and the custom Codex `config.toml` template's default model follows suit.
+- **Sol / Terra / Luna three-tier pricing**: the usage dashboard seeds all three tiers at official rates — Sol 5 / 30 / 0.50, Terra 2.50 / 15 / 0.25, Luna 1 / 6 / 0.10 (USD per million tokens, input / output / cache read). Unlike 5.5 and earlier, the 5.6 family bills **prompt-cache writes at 1.25× the input rate** (Sol 6.25 / Terra 3.125 / Luna 1.25), seeded accordingly, with existing rows previously billed at 0 auto-repaired; bare `gpt-5.6` and its per-effort suffix variants align to the Sol rate.
+
+### Use Claude-Family Models inside Codex: Native Anthropic Messages Upstream
+
+This feature comes from a very real need: **plenty of companies ban the Claude Code client for compliance reasons, but do not ban the Claude API.** For those users the model itself is available; what's missing is a permitted client — and Codex can now fill that slot. Pick the new `anthropic` option in a Codex provider's upstream-format selector, and you can connect directly to the Claude API or any gateway offering the native Anthropic Messages protocol (`/v1/messages`); the local proxy handles the two-way conversion of requests, responses, and streaming between Responses and Anthropic, and you chat and use tools inside Codex as usual while Claude-family models run behind the scenes. The form provides the supporting pieces: an auth-field selector (`ANTHROPIC_AUTH_TOKEN` sends `Authorization: Bearer`, the default; or `ANTHROPIC_API_KEY` sends `x-api-key`), an optional Claude Code client-impersonation toggle (off by default), and a per-provider max-output-token override (Codex doesn't send `model_max_output_tokens`, and when unset it falls back to a conservative 8192, which may truncate long or heavy-reasoning replies). The conversion bridge auto-injects standard 5-minute prompt-cache markers (system prompt, tools, and history go through the cache instead of being resent at full price each turn), supports the `[1m]` long-context marker with the corresponding beta header, and reports a truncated stream faithfully as incomplete rather than disguising it as success. ([#5071](https://github.com/farion1231/cc-switch/pull/5071))
+
+### "Default Model" Field Added to the Codex Provider Form
+
+The top-level `model` key in `config.toml` is now an editable field in the form: when a new model (e.g. `gpt-5.6`) ships, you can point an existing provider at it directly without waiting for a preset update (presets only affect newly added providers). The field is two-way synced with the TOML editor, its candidate list is the union of the model-mapping catalog and the provider's `/models` endpoint, and when a value isn't in the catalog it offers a one-click "Add to mapping". An explicitly entered value always wins over the implicit backfill from the mapping's first row; model names and `base_url` are TOML-escaped on write, eliminating any chance that remote data from `/models` injects a forged config line.
+
+### Common-Config Switch Auto-Sync Extended to Codex
+
+The "on switch-away, write shared preferences from the live config back to the common config" behavior v3.16.5 added for Claude now covers Codex: when you switch away from a Codex provider that has the common config enabled, the shareable portion is first re-extracted from its live `config.toml` to update the common config and then carried to the next provider — the preferences you edited directly in the running Codex config are no longer lost on switch, and deleted keys aren't quietly re-injected. The extractor strictly strips provider-specific and injected content (`model` / `model_provider` / `base_url` / `wire_api`, the entire `[model_providers]` table, the MCP projection, the API-key fallback field, the model-catalog pointer, and the injected `web_search` sentinel), so secrets never enter the shared snippet. All failures only warn and never block the switch.
+
+### Claude Subagent Model Configuration
+
+The Claude provider form gains a "subagent" model row that writes `CLAUDE_CODE_SUBAGENT_MODEL`, letting subagents spawned by Claude Code run on a model you specify (usually a cheaper or faster one). It supports the `[1M]` marker; since the subagent model never appears in the `/model` menu, the row shows a "not shown in /model" placeholder with no display-name field. The proxy takeover path and the model mapper support it too: when the request model matches the configured subagent model it's passed through as-is instead of being folded to the default model; the key is also excluded from the shared common config so it doesn't leak across providers. ([#4830](https://github.com/farion1231/cc-switch/pull/4830))
+
+### 1M Context Checkbox for the Fallback Model Field
+
+The Claude form's fallback model field (`ANTHROPIC_MODEL`) now carries the same 1M checkbox that the Sonnet / Opus / Fable tiers have long had: when the fallback model is backed by a 1M window you can declare it faithfully, instead of it being silently treated as 200K. Checking it appends the `[1M]` marker to the model id, unchecking strips it. ([#5124](https://github.com/farion1231/cc-switch/pull/5124), fixes #3679)
+
+### Zhipu Team-Plan Quota Query
+
+Zhipu's team plan (team-edition Coding Plan) uses the same quota endpoint but requires `?type=2` and two extra request headers (`bigmodel-organization` / `bigmodel-project`), which the personal-edition query can't reach. The usage-script dialog gains a "Zhipu GLM Team" template; fill in the API key + organization ID + project ID to query team quota, and if any of the three is missing you get a clear prompt to complete it. Copy is in sync across all four locales. ([#5128](https://github.com/farion1231/cc-switch/pull/5128))
+
+### OpenCode Form: Headers and Per-Model Token-Limit Editors
+
+The OpenCode provider form fills in two pieces of config that previously required hand-editing JSON: a **Headers editor** (provider-level `options.headers`, such as the `HTTP-Referer` / `X-Title` that OpenRouter's leaderboard wants, with add/remove rows and case-insensitive deduplication) and **per-model token limits** (`model.limit.context` / `model.limit.output` numeric inputs, cleared to remove). The "extra options" block becomes a collapsible section that auto-expands when it has content; along the way, a fix stops the old placeholder filter from wrongly deleting genuine option keys that start with `option-`. ([#2907](https://github.com/farion1231/cc-switch/pull/2907))
+
+### New Model Pricing: Tencent Hunyuan Hy3
+
+Seeded pricing for Tencent Hunyuan Hy3 (256K context), released 2026-07-06 (converted from the launch-day list price of CNY 1 / 4 / 0.25 per million tokens); both the `hunyuan-hy3` and `hy3` ids now hit, so their usage no longer shows $0. Note that Hy3 is actually tiered by input length, and the current price table is seeded at the lowest tier, so long-context requests will underestimate cost — to be corrected once the official billing page is clear.
+
+---
+
+## Changed
+
+### Codex Chat Routing Injects prompt_cache_key to Improve Cache Hits
+
+When Codex routes through the local proxy and converts to a Chat Completions upstream, it now injects `prompt_cache_key` in a provider-aware way: auto-enabled for Kimi Coding and the OpenAI official endpoint, explicitly on for the Kimi preset, and left off for unknown OpenAI-compatible gateways to avoid a 400 from strict-schema gateways. The key value only ever takes an explicit client value or a real client session ID, and never generates a random UUID (which would drop every request into a different cache bucket, defeating the purpose). Advanced options offer an auto / enabled / disabled tri-state override.
+
+### Codex Image Capability Auto-Inferred, Manual Toggle Removed
+
+The generated Codex model catalog now only declares `input_modalities = ["text"]` for models on CC Switch's confirmed **exact text-only roster**; GPT, aliases, new suffix variants, and any unknown model all fail open to `["text", "image"]` — fixing GPT-family models being falsely reported as "images not supported" in the Codex IDE extension. The rectifier's "text-only model precheck" toggle continues to govern only the proxy-side active request rewriting, not the catalog declaration; catalog reverse-import also collapses the inferable capability away, so a future roster correction or a model upgrading to multimodal takes effect automatically.
+
+### Context-Window Parameters Pinned into Presets, No Longer Form Fields
+
+The `Codex` (ChatGPT / GPT-5.6) and `Kimi For Coding` presets no longer show the "Max Context Tokens" and "Auto-Compact Window" inputs in the form; the values are pinned directly in the preset env (Codex 372000 / 372000, Kimi For Coding 262144 / 262144) — the vast majority of users never need to touch these two numbers. The two keys are kept in env on purpose: pinning them explicitly makes the local compaction trigger point immune to a remote experimental config dialing it down. The rare users who do want to change the numbers can still edit both keys directly in the provider's JSON editor.
+
+### Provider Connectivity Configuration Simplified
+
+Removed the obsolete per-provider `testConfig` overrides (timeout, retry count, degradation delay threshold): the lightweight `base_url` probe now always uses the global connectivity-check config, while automatic failover remains fully driven by the proxy's separate timeout and circuit-breaker settings. The settings UI and interface naming also migrate from "model test" terminology to "connectivity check".
+
+### Universal (Multi-App) Provider Auto-Synced After Adding
+
+After adding a universal (multi-app) provider through the "Add Provider" dialog, it's now immediately pushed to each live target config, no longer requiring a manual sync afterward. A sync failure doesn't block the add — the provider is saved, with a non-blocking warning shown if the sync fails. ([#2811](https://github.com/farion1231/cc-switch/pull/2811))
+
+### Preset Updates
+
+- **LongCat-2.0**: the Meituan LongCat presets across the board (Claude Code / Claude Desktop / Codex / Hermes / OpenClaw / OpenCode) upgrade from the retired `LongCat-Flash-Chat` / `LongCat-2.0-Preview` to `LongCat-2.0`, declaring the real 1M (1048576) context window. LongCat-2.0 is a text-only model, and the proxy's media-scrub whitelist is updated in sync — images pasted into a conversation are replaced with an unsupported marker rather than hard-rejected upstream. ([#4838](https://github.com/farion1231/cc-switch/pull/4838))
+- **SudoCode**: the old `sudocode.us` preset is replaced in place by the new sponsor SudoCode at `sudocode.chat`, covering six clients (the Claude family connects directly to Anthropic passthrough; Codex / OpenCode / OpenClaw / Hermes default to `gpt-5.6-sol`).
+- **Volcengine / Doubao / BytePlus website links**: reverted v3.16.5's change of these three presets' `websiteUrl` to product homepages, restoring the attribution-parameter campaign / invite links (this is by design).
+- **Code0.ai**: the invite link is updated to the new agent signup link; the API endpoint is unchanged.
+- **Removed duplicate OpenAI Compatible presets**: the `OpenAI Compatible` custom-template entry was removed from the OpenCode and OpenClaw preset lists — the built-in `custom` provider flow already offers the same starting point, so the selector no longer shows two entries pointing at the same place. Existing providers are unaffected.
+
+---
+
+## Fixed
+
+### Codex OAuth Client Identity Aligned: Fixes 404 on Latest ChatGPT Models
+
+When routing through local proxy takeover with an official Codex OAuth account, the latest subscription models (e.g. `gpt-5.6-luna`) previously returned a misleading `404 Model not found` — even though the account had access. The root cause is that ChatGPT's Codex backend does model-group routing by the `originator` + `version` headers, and cc-switch previously self-reported `originator: cc-switch` with no version, which routed it to a group where luna wasn't yet deployed. Takeover requests now send the same `originator: codex_cli_rs` + `version: 0.144.1` as the real Codex CLI, satisfying luna's minimum client-version requirement — confirmed fixed by A/B testing against the real backend.
+
+### Responses Upstream Failures No Longer Turn into Empty Replies
+
+When the proxy bridges an Anthropic-format client (Claude Code / Claude Desktop) to an OpenAI Responses upstream, a semantic failure hidden inside an HTTP 2xx body (a `status:"failed"` object, an `error` envelope, or a `response.failed` SSE event before the first output) was previously converted into a silent empty turn. These failures are now recognized as real errors inside the retry loop, so failover can retry with a different provider; a stream that ends cleanly but with incomplete content is faithfully marked truncated rather than complete; a gateway that ignores `stream:true` and returns the whole JSON document is recognized and expanded into a full streaming lifecycle; and when the client history itself is malformed, it errors immediately instead of retrying a guaranteed-to-fail request against every provider.
+
+### Reasoning, Tool Results, and the System Role Preserved Across the Responses/Anthropic Bridge
+
+Content crossing the Responses↔Anthropic bridge in multi-turn tool loops is no longer lost or corrupted: encrypted reasoning entries round-trip losslessly (also eliminating the problem where a failed round-trip got the next request rejected upstream); the streaming converter supports the official reasoning event vocabulary and recovers tool arguments from the terminal event when a gateway skips the deltas; a structured tool result's `is_error` flag, images, and PDF documents are fully preserved in both directions instead of being flattened into a single JSON string; and `system` / `developer` messages in history are correctly promoted to Anthropic `system` instead of being silently demoted to user turns. On billing, when the upstream request succeeds but the subsequent conversion fails, usage is still recorded rather than dropped.
+
+### Cache-Write Tokens No Longer Double-Billed
+
+The `input_tokens` reported by Codex / Gemini-style providers include both cache reads and cache writes, but the cost calculation previously only subtracted cache reads — so cache-write tokens were **billed twice**, once at the input rate and once at the cache-creation rate. Both are now deducted first, and the cache-write number is no longer lost across format conversions (Chat↔Responses↔Anthropic). To keep historical data consistent, the database adds a column recording the storage semantics of each row's `input_tokens` (schema v12→v13 auto-migration): old rows are recomputed under the old semantics, new rows under the new, and Claude-style rows are unaffected.
+
+### Stronger Prompt-Cache Breakpoint Injection
+
+On the proxy paths that inject Anthropic `cache_control` breakpoints (the Codex takeover bridge and the Bedrock native optimizer), the injector now uses the four-breakpoint budget more thoroughly: beyond the tail of tools, the tail of the system prompt, and the latest cacheable message, when budget remains it also anchors an earlier user message, keeping the stable prefix within Anthropic's 20-block lookback window — so long, tool-heavy conversations keep hitting the prompt cache instead of resending the system prompt, tools, and history at full price each turn. Caller-supplied breakpoints are preserved as-is (never removed, reordered, or rewritten); injected markers all use the standard 5-minute TTL.
+
+### Kimi For Coding's 256K Context Window Actually Takes Effect
+
+The `CLAUDE_CODE_AUTO_COMPACT_WINDOW=262144` added to the Kimi For Coding preset in 3.16.4 in fact **never took effect**: Claude Code caps unrecognized model ids at a 200K window and takes the compaction window as `min(model window, configured value)`, so 262144 got clamped back to 200K. This release fills in the two missing pieces — the preset now also pins `CLAUDE_CODE_MAX_CONTEXT_TOKENS`, and it explicitly routes each tier's model to the endpoint's `kimi-for-coding` alias (a `claude-` prefixed id makes Claude Code ignore both window parameters; a non-Claude alias is the key to unlocking the large window). Saved providers also get these two window defaults auto-injected on switch, but **the alias routing only lives in the preset** — a provider saved from the old preset is still effectively 200K and needs a one-time re-apply of the preset (see "Upgrade Notes").
+
+### Deleted Codex MCP Servers No Longer Come Back
+
+The authoritative MCP-server data lives in the database, and the `[mcp_servers]` in the Codex live `config.toml` is only a projection re-synced after every write — but on switch-away this projection was baked into the provider snapshot, so a server you deleted in the app came back to life the next time you activated that provider, and per-entry reconciliation could never clear the orphan. On switch-away, `[mcp_servers]` (including the legacy `[mcp.servers]`) is now stripped from the stored snapshot, and an already-polluted snapshot self-heals on its next switch-away. One visible side effect: a hand-written `[mcp_servers.*]` section in a Codex provider config is stripped out of the snapshot on its first switch-away — from now on, define Codex's MCP servers through the MCP manager (see "Upgrade Notes").
+
+### More Robust MCP Sync: No File-Blanking on Parse Failure, Per-App Errors
+
+Two fixes. First, when writing a single MCP server to Codex, if the existing `config.toml` fails to parse, the old logic fell back to an empty document and wrote the whole thing back — **the entire file was blanked** down to that one MCP entry; it now returns a validation error and leaves the file untouched. Second, "Import from App" previously swallowed each importer's error as 0, so a broken Codex config would only show "imported 0 servers"; it now imports best-effort per app and, on failure, reports exactly which app failed. The projection on switch and save is also scoped to the target app only, so one app's live-file parse failure no longer blocks the others by association, nor falsely reports an already-successful switch as a failure.
+
+### Codex Common-Config Merge Preserves Comments and Key Order
+
+Checking / unchecking "Apply Common Config" in the Codex provider form previously went through a front-end TOML implementation that reformatted the whole file (parse → merge → serialize): comments were dropped, keys were reordered, and empty table headers like `[model_providers]` appeared out of nowhere — the culprit behind "config.toml keeps getting reordered". The merge now goes through a backend command sharing the same merge semantics as writing the live config, so hand-written formatting fully survives the mid-edit merge; a double guard (operation sequence number + config baseline check) was also added for the fast-switch race introduced by going async, so an earlier-issued-but-later-arriving stale result doesn't overwrite newer state.
+
+### Managed Claude Takeover Injects Only a Single Auth Placeholder
+
+When switching from a third-party endpoint to a Codex-managed provider, `~/.claude/settings.json` had both `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` placeholders written, causing Claude Code to warn "Both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY set" on every launch. It now injects only one: Codex-managed uses `ANTHROPIC_AUTH_TOKEN`, Copilot uses `ANTHROPIC_API_KEY`, and any other token key is cleared. Note: after upgrading, if the live config already carries both keys, the "skip rewrite if config unchanged" short-circuit means the warning may persist — toggle the Claude route off and on once (or switch providers once) to trigger a rewrite (see "Upgrade Notes"). ([#5095](https://github.com/farion1231/cc-switch/pull/5095), fixes #4919)
+
+### Usage and Quota Queries: Auto-Retry on Transient Failures, No Longer Poison the Cache
+
+Usage and quota queries frequently showed a "query failed" that a manual refresh couldn't clear, because all transport-layer failures (including a mid-read timeout while reading the response body) were folded into "succeeded, but the result is a failure" — so the front-end's auto-retry never fired, and the failure body was cached as real data. Transport failures now return an error faithfully: react-query's auto-retry kicks in, HTTP 429 is treated as transient like 5xx, retained last-good data expires normally on a 10-minute window, and the footer keeps a retry entry and the real error message in the failure state. (fixes [#3820](https://github.com/farion1231/cc-switch/issues/3820))
+
+### Codex Subagent Session Usage Counted in Local Statistics
+
+The token usage of Codex subagent (spawned agent) sessions previously never made it into local statistics: subagent logs carry the parent thread's `session_id`, so multiple subagents' records collided and were discarded as duplicates. The parser now builds a unique identity from each file's own `thread_id`, and recognizes the replay of the parent thread's history at the start of a subagent log — using it only to recover the cumulative baseline, not to double-bill; archived logs also inherit the sync cursor by filename, so re-parsing only imports the new portion. ([#5187](https://github.com/farion1231/cc-switch/pull/5187))
+
+### Codex Free-Tier 30-Day Quota Window Displays Correctly
+
+Codex free accounts are metered on a rolling 30-day window (rather than the paid tier's weekly window), but the front-end whitelist and tray grouping didn't recognize the `30_day` tier — with a free account's only tier filtered out, the quota footer went entirely blank and the tray showed no quota at all. The 30-day tier now renders correctly in both the footer and the tray, with labels in sync across all four locales. ([#4886](https://github.com/farion1231/cc-switch/pull/4886), fixes #3651)
+
+### Usage Dashboard Refresh Interval Persisted
+
+The usage dashboard's auto-refresh interval was previously component-local state that reset to 30 seconds on every restart. It's now persisted via a new app setting, with changes applied optimistically and rolled back automatically on save failure. ([#5057](https://github.com/farion1231/cc-switch/pull/5057))
+
+### Fable-Tier Model Keys No Longer Leak into the Common Config
+
+Fable is the fourth Claude model-mapping tier added in v3.16.3, but its two keys `ANTHROPIC_DEFAULT_FABLE_MODEL(_NAME)` were left off the provider-specific exclusion list — so one provider's Fable model pin could leak into the shared common config and then be injected into other providers. It's now stripped like the haiku / sonnet / opus tiers, and Fable-tier proxy takeover support was filled in along the way (writing a stable role alias on takeover, cleaning up stale values on switch-away). ([#5206](https://github.com/farion1231/cc-switch/pull/5206), fixes #4272)
+
+### Tool-Schema Default-Type Fallback and API Key Input for Uncategorized Providers
+
+Two provider-side fixes: when a client-sent tool's `input_schema` lacks a top-level `type` (or is an empty `{}`), the proxy conversion would be rejected by a strict gateway; the root schema now auto-fills `type: "object"` (only the root, leaving nested subschemas untouched); and the issue where an uncategorized provider imported from history or hand-built showed no Claude API Key input on edit is fixed — the field now shows for any provider that isn't an official / cloud-vendor category. ([#5069](https://github.com/farion1231/cc-switch/pull/5069))
+
+### Image-Request Fallback for the Text-Only GLM 5.2 Model
+
+When the local proxy takes over Volcengine Coding Plan running GLM 5.2, image blocks in a request no longer produce an unrecoverable 400: the text-only roster exactly includes `glm-5.2` (deliberately not prefix-matching, so a future multimodal `glm-5.2v` isn't caught), and the preventive path strips images before the request goes out; the gateway's error message that doesn't contain the word image (`Model only support text input`) is also recognized by the reactive path's self-identifying-phrase roster, triggering the media fallback. (fixes [#5025](https://github.com/farion1231/cc-switch/issues/5025))
+
+### A Batch of Small Session and Live-Config Sync Fixes
+
+- **Show renamed Codex session titles**: a session you renamed inside Codex now shows the new title in the session manager instead of falling back to the first message text; reads during concurrent writes no longer fail immediately. ([#4927](https://github.com/farion1231/cc-switch/pull/4927))
+- **OpenCode / OpenClaw / Hermes live edits synced into the store on startup**: editing a live config file directly (changing the base URL, adding a model) was previously never picked up after the first import; it's now diffed against the store on every startup and updated on difference, all non-fatal. ([#4712](https://github.com/farion1231/cc-switch/pull/4712), [#5098](https://github.com/farion1231/cc-switch/pull/5098))
+- **OpenCode session-resume command updated**: the resume command the session manager shows and copies is corrected from the outdated `opencode session resume <id>` to the current CLI's `opencode -s <id>`. ([#2359](https://github.com/farion1231/cc-switch/pull/2359))
+- **Official providers skip the connectivity probe**: the connectivity check no longer derives a guaranteed-to-fail credential-less first-party endpoint probe for official-category providers (e.g. hitting `chatgpt.com/backend-api/codex` bare); batch checks skip it, and an individual resolve reports a clear error.
+
+---
+
+## Documentation
+
+### Codex + Kimi Local Routing Guide
+
+A new step-by-step guide (in Chinese / English / Japanese, with UI screenshots) explaining how to use Kimi inside Codex CLI via CC Switch's local routing: newer Codex CLI speaks the OpenAI Responses protocol, while the Kimi Open Platform (pay-as-you-go, `kimi-k2.7-code`) and Kimi For Coding (membership, `kimi-for-coding`) both expose Chat Completions endpoints, so a direct connection usually 404s on `/responses`. The guide covers the whole flow from adding a provider from the built-in preset to the four-step protocol-conversion chain.
+
+### README Sponsor Update
+
+The open-source AI infrastructure project `new-api` joins the sponsor table in the four-language READMEs.
+
+---
+
+## Upgrade Notes
+
+### Kimi For Coding Providers Need a Preset Re-Apply
+
+If you're using a provider created from the Kimi For Coding preset, please **re-pick it from the preset and save once**: the key to the 256K window — routing each tier's model to the `kimi-for-coding` alias — only lives in the new preset, so a provider saved from the old preset still compacts prematurely at 200K even after upgrading.
+
+### Hand-Written Codex `[mcp_servers.*]` Will Be Stripped from the Snapshot
+
+To root out "deleted MCP servers coming back", switching away from a Codex provider strips the `[mcp_servers]` section from the stored snapshot. If you have an MCP server hand-written directly in a Codex provider config, it will disappear from the snapshot on the first switch-away from that provider — please instead define Codex's MCP servers through the MCP manager (MCP tab), where the entries are authoritative and get projected into the live config automatically.
+
+### The Dual-Auth-Key Warning May Need a One-Time Manual Rewrite
+
+If Claude Code still warns "Both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY set" after upgrading, it's because the takeover logic short-circuits and skips the rewrite when the live config is unchanged. Toggle Claude's route off and on once (or switch providers once) to write the corrected single-placeholder config, and the warning goes away.
+
+### Automatic Database Migration
+
+On the first launch of v3.17.0, the database automatically migrates from schema v11 to v13 (adding the projects table and the usage-semantics column), with no manual steps. If you're in the habit of rolling back to an older version, back up `~/.cc-switch/cc-switch.db` first.
+
+---
+
+## Risk Notice
+
+This release continues the risk notices from previous versions for reverse-proxy-style features.
+
+**Codex OAuth reverse proxy**: using a ChatGPT subscription's Codex OAuth through a reverse proxy may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details. The "official ChatGPT account proxy route takeover" added in this release is the same class of usage, so please be aware of the same risk.
+
+**Codex third-party provider Chat routing**: when CC Switch local proxy converts and forwards Codex requests to third-party providers, each provider may have different requirements for billing, compliance, and data retention. Read the target provider's terms before use.
+
+**Claude Desktop third-party provider proxy switching**: when CC Switch's built-in proxy gateway forwards Claude Desktop requests to third-party providers, you must also follow the target provider's billing, compliance, and data-retention terms.
+
+By enabling these features, users accept the related risks. CC Switch is not responsible for account restrictions, warnings, or service suspensions caused by using these features.
+
+---
+
+## Thanks
+
+Thanks to the following contributors for the features and fixes in v3.17.0:
+
+- [#5071](https://github.com/farion1231/cc-switch/pull/5071): add the native Anthropic Messages protocol as a Codex upstream, thanks @yeeyzy.
+- [#4830](https://github.com/farion1231/cc-switch/pull/4830): add Claude subagent model configuration, thanks @AkimioJR.
+- [#5124](https://github.com/farion1231/cc-switch/pull/5124): add the 1M checkbox to the fallback model field, thanks @salarkhannn.
+- [#5128](https://github.com/farion1231/cc-switch/pull/5128): add Zhipu team-plan quota queries, thanks @zhanxin-xu.
+- [#2907](https://github.com/farion1231/cc-switch/pull/2907): add the Headers and token-limit editors to the OpenCode form, thanks @git1677967754.
+- [#2811](https://github.com/farion1231/cc-switch/pull/2811): auto-sync universal providers after adding, thanks @hubutui.
+- [#4838](https://github.com/farion1231/cc-switch/pull/4838): upgrade the LongCat presets to LongCat-2.0, thanks @solthx.
+- [#5095](https://github.com/farion1231/cc-switch/pull/5095): inject only a single auth placeholder on managed Claude takeover, thanks @fengshao1227.
+- [#5187](https://github.com/farion1231/cc-switch/pull/5187): count Codex subagent session usage in statistics, thanks @starmiaoa.
+- [#4886](https://github.com/farion1231/cc-switch/pull/4886): fix the Codex free-tier 30-day quota window not showing, thanks @SaladDay.
+- [#5057](https://github.com/farion1231/cc-switch/pull/5057), [#4927](https://github.com/farion1231/cc-switch/pull/4927), [#2359](https://github.com/farion1231/cc-switch/pull/2359): persist the refresh interval, show renamed session titles, and correct the OpenCode resume command, thanks @makoMakoGo.
+- [#5206](https://github.com/farion1231/cc-switch/pull/5206): exclude Fable model keys from the common config, thanks @fzh365.
+- [#5069](https://github.com/farion1231/cc-switch/pull/5069): tool-schema default-type fallback and API Key input restoration, thanks @Komikawayi.
+- [#4712](https://github.com/farion1231/cc-switch/pull/4712), [#5098](https://github.com/farion1231/cc-switch/pull/5098): sync OpenCode / OpenClaw / Hermes live config on startup, thanks @allenxu09.
+
+Thanks also to everyone who reported Codex official routing, cache billing, MCP sync, and quota query issues — a good portion of this release's fixes came directly from reproduction clues in these real-world scenarios.
+
+---
+
+## Download & Install
+
+Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) and download the build for your system.
+
+### System Requirements
+
+| System  | Minimum Version      | Architecture                        |
+| ------- | -------------------- | ----------------------------------- |
+| Windows | Windows 10 and later | x64 / ARM64                         |
+| macOS   | macOS 12 (Monterey)+ | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | See table below      | x64 / ARM64                         |
+
+### Windows
+
+| File                                     | Description                                      |
+| ---------------------------------------- | ------------------------------------------------ |
+| `CC-Switch-v3.17.0-Windows.msi`          | **Recommended** - MSI installer with auto-update |
+| `CC-Switch-v3.17.0-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.17.0-macOS.dmg`    | **Recommended** - DMG installer, drag to Applications |
+| `CC-Switch-v3.17.0-macOS.zip`    | Unzip and drag to Applications, Universal Binary      |
+| `CC-Switch-v3.17.0-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.17.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.17.0-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`              |
+
+</content>
+</invoke>
@@ -0,0 +1,363 @@
+# CC Switch v3.17.0
+
+> 本リリースでは、長らく待ち望まれていた**「プロジェクト」のワンクリック切り替え**を追加しました。現在のプロバイダー、MCP、Skills、メモリファイルを名前付きスナップショットとしてまとめて保存し、タイトルバーやトレイから別の構成へ一括で切り替えられます。切り替え時には、離れる側のプロジェクトの現在状態も自動保存されます。Codex 側も大きく進化しました。**公式 ChatGPT サブスクリプションアカウントもローカルプロキシ経由でルーティング**できるようになり、サードパーティプロバイダーと同じルーティング・使用量統計を利用できます。GPT-5.6 ファミリーのコンテキストウィンドウと Sol / Terra / Luna の 3 段階価格にも対応しました。さらに、ネイティブ Anthropic Messages 上流形式を追加——勤務先で Claude Code クライアントは禁止されていても Claude API は禁止されていませんか？これで **Codex の中から Claude 系モデルを直接利用できます**。このほか、上流エラーが「空の応答」になる問題、キャッシュ書き込み token の二重課金、削除した MCP サーバーの復活、Kimi For Coding の 256K ウィンドウが実際には効いていなかった問題など、多数の正確性の問題を修正しました。
+
+**[English →](v3.17.0-en.md) | [中文版 →](v3.17.0-zh.md)**
+
+---
+
+## 利用ガイド
+
+本リリースの新機能は、主にホーム画面上部のプロジェクト切り替え、Codex プロバイダーフォーム、使用量ダッシュボードにあります。以下のドキュメントもあわせてご覧ください：
+
+- **[Codex で Claude を使う（ローカルルーティングガイド）](../guides/codex-claude-routing-guide-ja.md)**：本リリースの「ネイティブ Anthropic Messages 上流」に対応した新しいステップバイステップガイドです。Codex プロバイダーの上流形式を `anthropic` にして、`/v1/messages` のみを提供する Claude 系ゲートウェイへ接続し、Codex の中で Claude 系モデルを使う手順を説明します。
+- **[Codex で Kimi を使う（ローカルルーティングガイド）](../guides/codex-kimi-routing-guide-ja.md)**：新しい Codex CLI は OpenAI Responses 形式を使いますが、Kimi Open Platform と Kimi For Coding は Chat Completions endpoint を提供するため、直接接続すると通常は 404 になります。このガイドでは、内蔵の `Kimi` / `Kimi For Coding` プリセットとローカルルーティングを使ったプロトコル変換を説明します。
+- **[Codex の公式ログインを保持する](../guides/codex-official-auth-preservation-guide-ja.md)**：サードパーティプロバイダーへ切り替える際に、CC Switch が公式 ChatGPT ログインをどう保持するかを説明します。本リリースではさらに、公式アカウント自体をプロキシ経由でルーティングできるようになりました。
+- **[使用量統計](../user-manual/ja/4-proxy/4.4-usage.md)**：使用量ダッシュボードのデータソースと集計方法を確認できます。本リリースではキャッシュ書き込み課金を修正し、Codex サブエージェントの使用量を補完し、GPT-5.6 と Hunyuan Hy3 の価格を追加しました。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一の公式チャネル（必ずお読みください）
+>
+> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。本ソフトウェアは下記の公式チャネルからのみ入手してください：
+>
+> | チャネル     | 唯一の公式                                                                     |
+> | ------------ | ------------------------------------------------------------------------------ |
+> | 公式サイト   | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者         | **[@farion1231](https://github.com/farion1231)**                               |
+> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は直ちに操作を中止し、GitHub Issues からご報告ください。
+
+---
+
+## 概要
+
+CC Switch v3.17.0 は v3.16.5 に続く大型機能リリースです。中心となるのは**「プロジェクト」**です。Claude Code / Claude Desktop / Codex の現在のプロバイダー、MCP、Skills、メモリファイルを名前付きスナップショットとして保存できます。たとえば、プログラミング用ディレクトリには「開発」、文章作成やイラスト用ディレクトリには「イラスト」という構成を用意し、ホーム上部またはトレイの「プロジェクト」サブメニューからワンクリックで一括切り替えできます。切り替える前には、離れるプロジェクトの現在状態が自動で書き戻されるため、各プロジェクトには最後に離れた時点の構成が常に保持されます。
+
+もう一つの柱は Codex です。**ChatGPT サブスクリプションでログインした公式アカウントもローカルプロキシでルーティング**できるようになりました。API key は不要で、Codex 自身のログイン情報をそのまま転送し、公式ログインを上書きしません。クライアント識別情報も修正され、`gpt-5.6-luna` など最新のサブスクリプションモデルが誤って 404 になる問題を解消しました。GPT-5.6 の 372K コンテキスト注入、Sol / Terra / Luna の 3 段階価格（キャッシュ書き込みは 1.25 倍）、プリセットの既定モデルも同時に対応しています。さらに Codex の上流形式にネイティブ Anthropic Messages を追加しました。これは、**Claude Code クライアントは禁止していても Claude API は禁止していない企業が多い**という現実的な利用場面を想定したものです。Codex を Claude API、または `/v1/messages` のみを提供するゲートウェイへ接続し、Codex の中で Claude 系モデルを使えます。
+
+正確性についても、3 つの領域を集中的に改善しました。**プロキシ変換**では、HTTP 2xx 内の上流エラーを空の応答に変換せず failover へ渡し、Responses↔Anthropic 間で reasoning、ツール結果、system role を保持し、プロンプトキャッシュのブレークポイントを強化しました。**使用量と課金**では、キャッシュ書き込み token が入力料金とキャッシュ作成料金の両方で計上されていた問題を修正し、ネットワークの一時障害で使用量キャッシュが壊れないようにしました。**Codex `config.toml`** では、削除した MCP サーバーの復活を防ぎ、解析不能なファイルを同期時に消去しないよう fail-closed にし、共通設定のマージでコメントやキー順序を維持するようにしました。Kimi For Coding の 256K ウィンドウ、Codex サブエージェントと無料プランの使用量表示、Zhipu チームプランのクォータ照会、OpenCode フォームの強化も含まれます。
+
+**リリース日**: 2026-07-13
+
+**Stats**: 69 commits | 172 files changed | +21,067 / -2,464 lines
+
+---
+
+## ハイライト
+
+- **「プロジェクト」をワンクリック切り替え**：プロバイダー、MCP、Skills、メモリファイルをまとめて名前付きスナップショットとして保存できます（たとえばプログラミング用と、文章作成・イラスト用）。ホーム上部またはトレイから一括切り替えでき、離れるプロジェクトの現在状態は自動保存されます。Claude Code、Claude Desktop、Codex の各スコープは互いに干渉しません。
+- **Codex の公式アカウントもプロキシルーティング可能に**：ChatGPT サブスクリプションでログインした Codex セッションをローカルプロキシ経由で扱い、サードパーティプロバイダーと同じルーティング・使用量統計を利用できます。公式ログイン情報は保存も上書きもしません。
+- **GPT-5.6 に全面対応**：Claude Code の Codex テイクオーバー時に 372K コンテキストを注入し、Sol / Terra / Luna の価格（キャッシュ書き込みは入力価格の 1.25 倍）を追加。プリセットも GPT-5.6 ファミリーへ更新し、クライアント識別修正で `gpt-5.6-luna` の誤った 404 を解消しました。
+- **Codex で Claude 系モデルを使用（ネイティブ Anthropic Messages 上流）**：Claude Code クライアントは禁止されていても Claude API は禁止されていない企業環境で、Codex の上流形式を `anthropic` に設定すれば Claude API または `/v1/messages` ゲートウェイへ接続できます。ローカルプロキシが Responses↔Anthropic を双方向変換します。
+- **プロキシ変換の正確性を改善**：上流エラーを空の応答にせず failover へ渡し、reasoning / ツール結果 / system role を保持。キャッシュ書き込みの二重課金も修正しました。
+- **Codex `config.toml` を堅牢化**：削除済み MCP サーバーの復活を防ぎ、解析エラー時にファイルを消去せず、共通設定マージでコメントとキー順序を保持します。
+- **Kimi For Coding の 256K が実際に有効に**：以前の 262144 設定は Claude Code の 200K 上限に抑えられていました。本リリースでモデル別名とウィンドウ設定を補完します。既存プロバイダーはプリセットを適用し直してください。
+
+---
+
+## 追加機能
+
+### 「プロジェクト」：構成一式を保存してワンクリック切り替え
+
+本リリースの中心機能です。現在のプロバイダー、MCP、Skills、メモリファイルを名前付き「プロジェクト」として保存し、ホーム上部のプロジェクト切り替えまたはトレイの「プロジェクト」サブメニューから一括で切り替えられます。項目ごとに手作業で切り替える必要はありません。
+
+典型的な例を挙げます。あるディレクトリではプログラミングを行い、別のディレクトリでは文章を書いたりイラストを作ったりするとします。プログラミングには専用のプロバイダー、ファイルシステム / GitHub MCP、コードレビュー Skills、開発ルールを書いたメモリファイルが必要です。一方、文章作成やイラストでは別のプロバイダー、別の MCP、まったく異なるプロンプトを使います。以前は作業を移るたびに、プロバイダーを変え、MCP と Skills を一つずつ切り替え、メモリファイルも変更する必要がありました。今後は 2 つの構成を「開発」と「イラスト」というプロジェクトに保存し、作業ディレクトリを変えるときに **CC Switch で一度クリックするだけ**で構成一式を切り替えられます。ディレクトリに応じて自動切り替えする機能ではなく、ユーザーが明示的に選ぶ仕組みです。
+
+設計上のポイント：
+
+- **プロジェクトは共有、切り替えはスコープ別**：同じプロジェクトでも Claude Code / Claude Desktop / Codex はそれぞれ独立した現在位置とスナップショットを持ちます。Codex タブで切り替えても Claude の設定には触れません。
+- **切り替え時に自動保存**：新しいプロジェクトへ移る前に、離れるプロジェクトの現在状態をそのスコープへ自動で書き戻します。このため手動の「現在状態で更新」ボタンは不要です。
+- **適用はベストエフォート**：既存の切り替え処理を再利用し、プロバイダー、MCP / Skills の差分、メモリファイルの順に適用します。削除済み項目への参照は警告してスキップし、全体をロールバックしません。
+- **プロキシテイクオーバーを自動解除**：スナップショットを適用する前に対象スコープのテイクオーバーを無効化し、ルーティング状態との競合を避けます。
+
+プロジェクトを使わない場合は、「設定 → ホームページ表示」の「プロジェクト切り替えを表示」をオフにできます。ホームの入口だけが非表示になり、トレイのサブメニューやプロジェクトデータはそのまま利用できます。新しい `profiles` テーブルへのデータベース移行は自動です。
+
+### Codex 公式 ChatGPT アカウントのプロキシルーティング
+
+ChatGPT サブスクリプション（OAuth または API-key ログイン）で使う Codex セッションを、CC Switch のローカルプロキシ経由でルーティングできるようになりました。サードパーティプロバイダーと同じルーティング、形式変換、使用量統計を利用できます。プロバイダーパネルまたはトレイで内蔵の「OpenAI Official」を選択してください。削除済みの場合は、プロバイダー追加時に自動復元されます。
+
+実装では**認証情報を保存しない**ことを重視しています。`auth.json` にダミーの API key を書かず、ローカルプロキシを指す専用 `model_provider` を `config.toml` へ投影します。Codex 自身の ChatGPT Authorization header をプロキシが公式 endpoint へそのまま転送し、`codex-official` 行の認証情報は常に空です。テイクオーバー時も OAuth / API-key 情報をバックアップへ保持します。公式 endpoint の 401 / 403 は再試行不能として扱い、failover が別アカウントへ会話を移したり circuit breaker を汚したりしません。「切り替え時に Codex 公式ログインを保持」設定は、今後、ルーティングを使わないサードパーティへの直接切り替えだけを制御します。
+
+### GPT-5.6：コンテキスト、プリセット、3 段階価格
+
+- **372K コンテキスト注入**：Claude Code を ChatGPT Codex（Codex OAuth）へルーティングすると、`CLAUDE_CODE_MAX_CONTEXT_TOKENS` と `CLAUDE_CODE_AUTO_COMPACT_WINDOW` を 372000 で注入します。全設定モデルが GPT-5.6 ファミリーの場合だけ適用し、GPT-5.5 や混在マッピングには適用しません。ユーザーの明示設定が常に優先され、切り替え後に既定値が保存設定へ固着しないよう逆変換で除去します。
+- **プリセット更新**：Claude Code / Claude Desktop の Codex OAuth プリセットを GPT-5.6 ファミリーへ更新（haiku → `gpt-5.6-luna`、main / sonnet / opus → `gpt-5.6`）。Codex `config.toml` テンプレートも更新しました。
+- **Sol / Terra / Luna 価格**：100 万 token あたりの入力 / 出力 / キャッシュ読み取りを、Sol 5 / 30 / 0.50、Terra 2.50 / 15 / 0.25、Luna 1 / 6 / 0.10 USD で登録。GPT-5.6 のキャッシュ書き込みは入力の 1.25 倍（6.25 / 3.125 / 1.25）で、既存データベースの誤ったゼロ値も安全に修復します。
+
+### Codex で Claude 系モデルを使う：ネイティブ Anthropic Messages 上流
+
+この機能は、**Claude Code クライアントを禁止していても Claude API は禁止していない企業が多い**という現実的な要望から生まれました。モデルは利用できるのに、許可されたクライアントがない——その空白を Codex で埋められます。Codex プロバイダーの上流形式で `anthropic` を選ぶと、Claude API またはネイティブ Anthropic Messages（`/v1/messages`）のみを提供するゲートウェイへ接続できます。ローカルプロキシが Responses↔Anthropic のリクエスト、応答、ストリームを双方向変換するため、Codex の操作感のまま Claude 系モデルとの対話やツール利用が可能です。
+
+フォームには、認証フィールド選択（既定の `ANTHROPIC_AUTH_TOKEN` は `Authorization: Bearer`、`ANTHROPIC_API_KEY` は `x-api-key`）、任意の Claude Code クライアント偽装（既定オフ）、プロバイダー別 `maxOutputTokens` を追加しました。変換ブリッジは system、tools、history に標準 5 分の `cache_control` を注入し、`[1m]` 長コンテキストマーカーと beta header に対応します。途中で切れたストリームは成功として偽装せず、未完了 / 失敗として報告します。（[#5071](https://github.com/farion1231/cc-switch/pull/5071)）
+
+### Codex プロバイダーフォームに「既定モデル」欄を追加
+
+`config.toml` トップレベルの `model` をフォームから編集できます。新モデル（例：`gpt-5.6`）が公開されたとき、プリセット更新を待たずに既存プロバイダーを切り替えられます。TOML エディターと双方向同期し、モデルマッピングと `/models` endpoint の候補を表示します。明示値はマッピング先頭行より常に優先され、remote の model id を書き込む際は TOML エスケープと制御文字除去を行います。
+
+### Codex でも切り替え時に共通設定を自動同期
+
+v3.16.5 で Claude に追加した live 設定から共通設定への自動書き戻しを Codex にも拡張しました。共通設定を有効にした Codex プロバイダーから離れるとき、live `config.toml` の共有可能な部分を再抽出し、次のプロバイダーへ渡します。`model` / `model_provider` / `base_url` / `wire_api`、`[model_providers]`、MCP 投影、API key、モデルカタログ、CC Switch が注入した `web_search` は除外されるため、プロバイダー固有情報や秘密情報は共有されません。失敗は警告のみで切り替えを妨げません。
+
+### Claude サブエージェントモデル設定
+
+Claude プロバイダーフォームに「サブエージェント」モデル行を追加し、`CLAUDE_CODE_SUBAGENT_MODEL` を設定できるようにしました。サブエージェントを安価または高速なモデルへ固定でき、`[1M]` マーカーにも対応します。プロキシテイクオーバーとモデルマッパーもこの設定を認識し、共通設定からは除外されるため他プロバイダーへ漏れません。（[#4830](https://github.com/farion1231/cc-switch/pull/4830)）
+
+### フォールバックモデルにも 1M チェックボックス
+
+Claude フォームのフォールバックモデル（`ANTHROPIC_MODEL`）に、Sonnet / Opus / Fable と同じ 1M チェックボックスを追加しました。チェックすると model id に `[1M]` が付き、解除すると除去されます。（[#5124](https://github.com/farion1231/cc-switch/pull/5124)、#3679 を修正）
+
+### Zhipu チームプランのクォータ照会
+
+使用量スクリプトに「Zhipu GLM Team（智谱团队）」テンプレートを追加しました。API Key、組織 ID、プロジェクト ID を入力すると、`?type=2` と必要な request headers を使ってチームプランのクォータを照会します。3 項目のいずれかが欠けている場合は補完を案内します。（[#5128](https://github.com/farion1231/cc-switch/pull/5128)）
+
+### OpenCode フォーム：Headers とモデル別 Token 上限
+
+OpenCode プロバイダーフォームに、`options.headers`（`HTTP-Referer` / `X-Title` など）と、モデル別の Context / Output token 上限（`model.limit.context` / `model.limit.output`）の編集 UI を追加しました。「Extra Options」は折りたたみ式になり、既存値があれば自動展開します。旧 draft prefix のため正当な `option-` で始まるキーが消える問題も修正しました。（[#2907](https://github.com/farion1231/cc-switch/pull/2907)）
+
+### Tencent Hunyuan Hy3 の価格
+
+2026-07-06 公開の Hunyuan Hy3（256K context）に価格を追加し、使用量が $0 と表示されないようにしました。`hunyuan-hy3` と `hy3` の両方を登録しています。実際の Hy3 は入力長で段階課金されますが、現在の単一価格テーブルでは最安段階を使用するため、長コンテキストでは費用を過小評価する可能性があります。
+
+---
+
+## 変更
+
+### Codex Chat に `prompt_cache_key` を供給
+
+Responses→Chat Completions 変換で、プロバイダーを考慮した `prompt_cache_key` を注入します。Kimi Coding と OpenAI 公式 endpoint は自動有効、Kimi プリセットは明示的に有効、未知の互換ゲートウェイは schema 400 を避けるため無効のままです。値はクライアントの明示値または実際の session ID だけを使い、リクエストごとのランダム UUID は生成しません。高度な設定で Auto / Enabled / Disabled を選べます。
+
+### Codex の画像対応を自動推定
+
+生成した Codex モデルカタログは、CC Switch が確認済みの**完全一致 text-only リスト**にあるモデルだけを `["text"]` として宣言します。GPT、alias、新しい suffix、未知のモデルは `["text", "image"]` へ fail-open します。これにより GPT 系モデルが Codex IDE で「画像非対応」と誤表示される問題を解消しました。整流器の text-only preflight は代理側の本文処理だけを制御し、カタログ宣言には影響しません。
+
+### コンテキスト値をフォームではなくプリセットへ固定
+
+`Codex`（ChatGPT / GPT-5.6）と `Kimi For Coding` の「Max Context Tokens」「Auto Compact Window」をフォームから外し、プリセット env に固定しました（Codex は 372000 / 372000、Kimi For Coding は 262144 / 262144）。遠隔実験でローカルの圧縮点が引き下げられないよう、2 つの env key 自体は意図的に残しています。必要な場合はプロバイダーの JSON エディターから直接編集できます。
+
+### プロバイダー接続確認を簡素化
+
+古いプロバイダー別 `testConfig`（timeout、retry、degraded latency）を削除し、軽量 `base_url` probe はグローバル設定だけを使うようにしました。自動 failover は引き続き独立した proxy timeout と circuit breaker 設定で動作します。「model test」関連の UI / API 名も「connectivity check」へ統一しました。
+
+### Universal Provider を追加後すぐ live 設定へ同期
+
+複数アプリ向け Universal Provider を追加すると、DB 保存後に Claude / Codex / Gemini 等の live 設定へすぐ同期します。同期に失敗しても保存は取り消さず、非ブロッキング警告を表示します。（[#2811](https://github.com/farion1231/cc-switch/pull/2811)）
+
+### プリセット更新
+
+- **LongCat-2.0**：Claude Code / Claude Desktop / Codex / Hermes / OpenClaw / OpenCode の既定モデルを廃止済みの名称から `LongCat-2.0` へ更新し、実際の 1M context を宣言しました。text-only モデルとして media sanitizer にも追加し、画像は上流で 400 になる前に非対応マーカーへ置換します。（[#4838](https://github.com/farion1231/cc-switch/pull/4838)）
+- **SudoCode**：旧 `sudocode.us` プリセットを新しいスポンサー SudoCode（`sudocode.chat`）へ置き換え、6 クライアントをカバーします。Codex / OpenCode / OpenClaw / Hermes の既定は `gpt-5.6-sol` です。
+- **火山 / Doubao / BytePlus**：v3.16.5 で製品ページへ変更した `websiteUrl` を、帰属パラメータ付きのキャンペーン / 招待リンクへ戻しました。これは意図された設定です。
+- **Code0.ai**：招待リンクを新しい agent 登録 URL へ更新。API endpoint は変更していません。
+- **重複した OpenAI Compatible プリセットを削除**：OpenCode / OpenClaw では内蔵 `custom` フローが同じ初期設定を提供するため、重複エントリだけを削除しました。既存プロバイダーには影響しません。
+
+---
+
+## 修正
+
+### Codex OAuth のクライアント識別を修正し最新モデルの 404 を解消
+
+公式 Codex OAuth をローカルプロキシで使うと、権限がある `gpt-5.6-luna` が `404 Model not found` になることがありました。ChatGPT Codex backend が `originator` + `version` の組み合わせで model cohort を選ぶ一方、CC Switch は `originator: cc-switch` かつ version なしで送っていたことが原因です。現在は実際の Codex CLI と同じ `originator: codex_cli_rs` + `version: 0.144.1` を送り、luna の最低バージョン要件を満たします。実 endpoint への A/B テストでも修正を確認しました。
+
+### Responses 上流エラーを空の応答にしない
+
+Anthropic クライアントを Responses 上流へつなぐ際、HTTP 2xx body 内の `{status:"failed"}`、error envelope、出力前の `response.failed` SSE event が空の `end_turn` に変換されていました。現在は retry loop 内で実エラーとして検出し、failover が別プロバイダーを選べます。途中終了した stream は不完全または切断エラーとして報告し、`stream:true` を無視して JSON 全体を返す gateway にも対応します。不正なクライアント履歴は再試行不能エラーとして即座に返します。
+
+### Responses / Anthropic 間で reasoning・ツール結果・system role を保持
+
+暗号化 reasoning を署名付き thinking block として往復し、公式 reasoning stream events、欠落 delta の tool arguments、`is_error`、画像、PDF / `input_file` を保持します。履歴中の `system` / `developer` message は user 発言へ降格せず Anthropic `system` へ移します。上流リクエストが成功した後に変換エラーとなった場合も使用量を記録します。
+
+### キャッシュ書き込み token の二重課金を修正
+
+Codex / Gemini の `input_tokens` は cache read と cache write を含みますが、以前は read だけを差し引いたため、write token が入力料金と cache creation 料金の両方で計上されていました。現在は両方を差し引き、Chat↔Responses↔Anthropic の変換でも cache write 値を保持します。schema v13 の `input_token_semantics` により、既存行は旧方式、新規行は新方式で安全に計算します。
+
+### プロンプトキャッシュのブレークポイント注入を強化
+
+ツール末尾、system 末尾、最新の cacheable message に加え、予算があれば古い user message にも anchor を追加します。長い tool-heavy 会話でも安定 prefix が Anthropic の 20-block lookback 内に残ります。呼び出し側が付けた breakpoint は削除・並べ替え・書き換えせず、4 個を超えている場合は警告して自動注入しません。注入 TTL は標準の 5 分です。
+
+### Kimi For Coding の 256K context を実際に有効化
+
+`CLAUDE_CODE_AUTO_COMPACT_WINDOW=262144` だけでは、未知の非 Claude model を Claude Code が 200K とみなすため 200K に抑えられていました。本リリースは `CLAUDE_CODE_MAX_CONTEXT_TOKENS` を追加し、すべての model tier を `kimi-for-coding` alias へ明示的にルーティングします。既存プロバイダーには window 値を live 設定へ注入しますが、alias は新プリセットにのみ含まれるため、旧プリセット利用者は適用し直す必要があります。
+
+### 削除した Codex MCP サーバーが復活しないように
+
+Codex live `config.toml` の `[mcp_servers]` は DB の投影ですが、切り替え時にプロバイダースナップショットへ保存されていたため、アプリで削除したサーバーが次回有効化時に復活していました。切り替え時に `[mcp_servers]` と旧 `[mcp.servers]` を保存設定から除去し、汚染済みスナップショットも次回切り替えで自己修復します。手書きの `[mcp_servers.*]` も除去対象になるため、今後は MCP 管理画面を使用してください。
+
+### MCP 同期：解析エラー時にファイルを消去せず、アプリ別に失敗を報告
+
+Codex `config.toml` が解析不能な状態で MCP を 1 件同期すると、以前は空の TOML へフォールバックしてファイル全体を上書きし、その MCP だけを残していました。現在は検証エラーを返し、元ファイルを変更しません。全アプリからのインポートも失敗を 0 件として隠さず、成功分を取り込んだうえで失敗したアプリ名をまとめて報告します。切り替え・保存時の投影は対象アプリだけに限定し、他アプリの破損に巻き込まれません。
+
+### Codex 共通設定マージでコメントとキー順序を保持
+
+フロントエンドの TOML parse → merge → stringify は、コメントを削除し、キーを並べ替え、空の table header を作っていました。マージを backend の `toml_edit` ベース処理へ移し、フォームプレビューと live 書き込みで同じ意味論を使うようにしました。非同期化に伴う race も operation sequence と config baseline の 2 段階で防ぎます。
+
+### 管理下 Claude テイクオーバーでは auth placeholder を 1 つだけ注入
+
+Codex 管理プロバイダーへ切り替えると `ANTHROPIC_API_KEY` と `ANTHROPIC_AUTH_TOKEN` の両方が `PROXY_MANAGED` になり、Claude Code が毎回警告していました。現在は Codex で `ANTHROPIC_AUTH_TOKEN`、Copilot で `ANTHROPIC_API_KEY` の 1 つだけを使います。既存の二重設定は短絡処理で自動書き換えされない場合があるため、Claude ルーティングを一度オフ / オンするか、プロバイダーを切り替えてください。（[#5095](https://github.com/farion1231/cc-switch/pull/5095)、#4919 を修正）
+
+### 使用量・クォータ照会の一時障害を再試行し、キャッシュを汚さない
+
+通信失敗や body 読み取り timeout が `success:false` の正常結果として扱われ、再試行されず、失敗データが cache に保存されていました。現在は一時的な transport error、HTTP 429、5xx をエラーとして返し、react-query の retry を有効にします。最後の正常値は 10 分の保持期間に従い、失敗時も footer に retry 操作と実エラーを表示します。（[#3820](https://github.com/farion1231/cc-switch/issues/3820)）
+
+### Codex サブエージェントの使用量をローカル統計へ追加
+
+サブエージェントログは親 thread の `session_id` を持つため、複数サブエージェントの request ID が衝突し重複として破棄されていました。各ファイルの `thread_id` を優先して一意な ID を作り、ログ冒頭の親履歴 replay は累積 baseline の復元だけに使って二重計上を防ぎます。archive 後も元ファイルの cursor を継承します。（[#5187](https://github.com/farion1231/cc-switch/pull/5187)）
+
+### Codex 無料プランの 30 日クォータを footer とトレイに表示
+
+無料アカウントの `30_day` window が UI whitelist と tray grouping に含まれず、唯一の tier が消えてクォータ表示全体が空になっていました。30 日 tier を単一の定数で backend / tray / frontend に追加し、4 言語のラベルを用意しました。（[#4886](https://github.com/farion1231/cc-switch/pull/4886)、#3651 を修正）
+
+### 使用量ダッシュボードの更新間隔を永続化
+
+自動更新の off / 5s / 10s / 30s / 60s 選択をアプリ設定へ保存し、再起動後も維持します。変更は即時反映し、保存失敗時は元の値へ戻します。（[#5057](https://github.com/farion1231/cc-switch/pull/5057)）
+
+### Fable model key を Claude 共通設定から除外
+
+`ANTHROPIC_DEFAULT_FABLE_MODEL` / `_NAME` が除外リストから漏れ、あるプロバイダーの Fable mapping が共通設定経由で他へ流れる可能性がありました。Haiku / Sonnet / Opus と同様に除外し、Fable の proxy takeover role alias も補完しました。（[#5206](https://github.com/farion1231/cc-switch/pull/5206)、#4272 を修正）
+
+### tool schema の既定 `type` と未分類プロバイダーの API Key 欄
+
+Anthropic tool の root `input_schema` に `type` がない場合、厳格な OpenAI gateway が変換後の schema を拒否していました。root にだけ `type: "object"` を補い、nested schema は変更しません。また、過去にインポートした category なしのカスタムプロバイダーを編集すると API Key 欄が隠れる問題を修正しました。（[#5069](https://github.com/farion1231/cc-switch/pull/5069)）
+
+### Volcano GLM 5.2 の text-only 画像 400 を回避
+
+GLM 5.2 を完全一致の text-only model として登録し、画像 block を上流送信前に置換します。将来の multimodal `glm-5.2v` を誤判定しないよう prefix match は使いません。`Model only support text input` という image の語を含まないエラーも reactive fallback で認識します。（[#5025](https://github.com/farion1231/cc-switch/issues/5025)）
+
+### セッションと live 設定の小修正
+
+- **Codex で変更したセッションタイトルを表示**：`session_index.jsonl` / `state_5.sqlite` の保存タイトルを優先し、同時書き込み時は busy timeout を使います。（[#4927](https://github.com/farion1231/cc-switch/pull/4927)）
+- **OpenCode / OpenClaw / Hermes の live 編集を起動時に DB へ同期**：base URL や model を直接変更した場合も、毎回の起動で差分を取り込みます。（[#4712](https://github.com/farion1231/cc-switch/pull/4712)、[#5098](https://github.com/farion1231/cc-switch/pull/5098)）
+- **OpenCode の再開コマンドを更新**：`opencode session resume <id>` を現在の `opencode -s <id>` へ修正しました。（[#2359](https://github.com/farion1231/cc-switch/pull/2359)）
+- **公式プロバイダーの接続 probe をスキップ**：認証情報なしでは必ず失敗する公式 endpoint を batch connectivity check で probe しません。
+
+---
+
+## ドキュメント
+
+### Codex + Kimi ローカルルーティングガイド
+
+Kimi を Codex CLI で使うための手順を、中国語 / 英語 / 日本語とスクリーンショット付きで追加しました。Codex は Responses、Kimi Open Platform（`kimi-k2.7-code`）と Kimi For Coding（`kimi-for-coding`）は Chat Completions を使うため、内蔵プリセットから追加し、CC Switch のローカルルーティングで双方向変換する流れを説明します。
+
+### README のスポンサー欄を更新
+
+オープンソース AI インフラプロジェクト `new-api` を 4 言語 README のスポンサー表へ追加しました。
+
+---
+
+## アップグレード時の注意
+
+### Kimi For Coding プロバイダーはプリセットを適用し直してください
+
+Kimi For Coding を使用している場合は、**新しいプリセットを選び直して保存**してください。256K を有効にする鍵である `kimi-for-coding` alias への各 model tier のルーティングは新プリセットにのみ含まれます。旧プリセットのままでは、アップグレード後も実際のウィンドウは 200K です。
+
+### 手書きの Codex `[mcp_servers.*]` はスナップショットから除去されます
+
+削除済み MCP サーバーの復活を防ぐため、Codex プロバイダーから切り替えるとき `[mcp_servers]` を保存スナップショットから除去します。手書きした MCP 定義も初回切り替え時に消えるため、今後は MCP 管理画面で定義してください。DB の `mcp_servers` が正本となり、live config へ自動投影されます。
+
+### auth 二重キー警告は一度手動で書き換えを発火させる必要があります
+
+アップグレード後も Claude Code が「Both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY set」と警告する場合は、live config が一致しているとテイクオーバー処理が書き換えを省略するためです。Claude ルーティングを一度オフにしてからオンに戻すか、プロバイダーを一度切り替えると、単一 placeholder に修正されます。
+
+### データベースは自動移行されます
+
+v3.17.0 の初回起動時に schema v11 から v13（プロジェクトテーブルと input token semantics）へ自動移行します。手動操作は不要です。古いバージョンへ戻す可能性がある場合は、先に `~/.cc-switch/cc-switch.db` をバックアップしてください。
+
+---
+
+## リスク通知
+
+本リリースは、リバースプロキシ系機能に関する以前のリスク通知を引き続き適用します。
+
+**Codex OAuth リバースプロキシ**：ChatGPT サブスクリプションの Codex OAuth をリバースプロキシ経由で使用すると、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 release notes](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。本リリースで追加した「公式 ChatGPT アカウントのプロキシルーティング」も同じ種類の利用方法であり、同様のリスクがあります。
+
+**Codex サードパーティプロバイダー Chat ルーティング**：CC Switch ローカルプロキシで Codex リクエストを変換し、サードパーティプロバイダーへ転送する場合、課金・コンプライアンス・データ保持に関する制約はプロバイダーごとに異なります。利用前に対象プロバイダーの利用規約を確認してください。
+
+**Claude Desktop サードパーティプロバイダープロキシ切り替え**：CC Switch 内蔵のプロキシゲートウェイで Claude Desktop のリクエストをサードパーティプロバイダーへ転送する場合も、対象プロバイダーの課金・コンプライアンス・データ保持に関する規約に従う必要があります。
+
+上記機能を有効化したユーザーは、関連するリスクを自ら負うものとします。CC Switch は、これらの機能の利用によって発生したアカウント制限、警告、サービス停止について責任を負いません。
+
+---
+
+## 謝辞
+
+v3.17.0 で機能と修正を届けてくださった以下のコントリビューターに感謝します：
+
+- [#5071](https://github.com/farion1231/cc-switch/pull/5071)：Codex の上流としてネイティブ Anthropic Messages protocol を追加、@yeeyzy に感謝。
+- [#4830](https://github.com/farion1231/cc-switch/pull/4830)：Claude サブエージェントモデル設定を追加、@AkimioJR に感謝。
+- [#5124](https://github.com/farion1231/cc-switch/pull/5124)：フォールバックモデルに 1M チェックボックスを追加、@salarkhannn に感謝。
+- [#5128](https://github.com/farion1231/cc-switch/pull/5128)：Zhipu チームプランのクォータ照会を追加、@zhanxin-xu に感謝。
+- [#2907](https://github.com/farion1231/cc-switch/pull/2907)：OpenCode フォームに headers と token 上限編集を追加、@git1677967754 に感謝。
+- [#2811](https://github.com/farion1231/cc-switch/pull/2811)：Universal Provider の追加後自動同期、@hubutui に感謝。
+- [#4838](https://github.com/farion1231/cc-switch/pull/4838)：LongCat プリセットを LongCat-2.0 へ更新、@solthx に感謝。
+- [#5095](https://github.com/farion1231/cc-switch/pull/5095)：管理下 Claude テイクオーバーの auth placeholder を 1 つに修正、@fengshao1227 に感謝。
+- [#5187](https://github.com/farion1231/cc-switch/pull/5187)：Codex サブエージェントの使用量統計を修正、@starmiaoa に感謝。
+- [#4886](https://github.com/farion1231/cc-switch/pull/4886)：Codex 無料プランの 30 日クォータ表示を修正、@SaladDay に感謝。
+- [#5057](https://github.com/farion1231/cc-switch/pull/5057)、[#4927](https://github.com/farion1231/cc-switch/pull/4927)、[#2359](https://github.com/farion1231/cc-switch/pull/2359)：更新間隔の永続化、変更済みセッションタイトル表示、OpenCode 再開コマンド修正、@makoMakoGo に感謝。
+- [#5206](https://github.com/farion1231/cc-switch/pull/5206)：Fable model key を共通設定から除外、@fzh365 に感謝。
+- [#5069](https://github.com/farion1231/cc-switch/pull/5069)：tool schema の既定 type と API Key 欄を修正、@Komikawayi に感謝。
+- [#4712](https://github.com/farion1231/cc-switch/pull/4712)、[#5098](https://github.com/farion1231/cc-switch/pull/5098)：OpenCode / OpenClaw / Hermes の live 設定同期、@allenxu09 に感謝。
+
+Codex 公式ルーティング、キャッシュ課金、MCP 同期、クォータ照会について報告してくださったすべてのユーザーにも感謝します。本リリースの多くの修正は、実際の利用場面から得られた再現情報をもとにしています。
+
+---
+
+## ダウンロードとインストール
+
+[Releases](https://github.com/farion1231/cc-switch/releases/latest) から、お使いのシステムに対応するビルドをダウンロードしてください。
+
+### システム要件
+
+| システム | 最低バージョン           | アーキテクチャ                      |
+| -------- | ------------------------ | ----------------------------------- |
+| Windows  | Windows 10 以降          | x64 / ARM64                         |
+| macOS    | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
+| Linux    | 下表を参照               | x64 / ARM64                         |
+
+### Windows
+
+| ファイル                                 | 説明                                         |
+| ---------------------------------------- | -------------------------------------------- |
+| `CC-Switch-v3.17.0-Windows.msi`          | **推奨** - 自動更新対応の MSI インストーラー |
+| `CC-Switch-v3.17.0-Windows-Portable.zip` | ポータブル版、展開してそのまま実行できます   |
+
+Windows ARM64 デバイスでは、ファイル名に `arm64` が含まれる対応する成果物を選択してください。
+
+### macOS
+
+| ファイル                         | 説明                                                   |
+| -------------------------------- | ------------------------------------------------------ |
+| `CC-Switch-v3.17.0-macOS.dmg`    | **推奨** - DMG インストーラー、Applications へドラッグ |
+| `CC-Switch-v3.17.0-macOS.zip`    | 展開して Applications へドラッグ、Universal Binary     |
+| `CC-Switch-v3.17.0-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.17.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.17.0-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| ディストリビューション                  | 推奨形式    | インストール方法                                                           |
+| --------------------------------------- | ----------- | -------------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` または `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` または `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                    |
+| Arch Linux / Manjaro                    | `.AppImage` | 実行権限を付与して直接起動、または AUR を使用                              |
+| その他 / 不明                           | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`                  |
@@ -0,0 +1,363 @@
+# CC Switch v3.17.0
+
+> 这一版带来一个盼了很久的能力：**「项目」一键切换**——把当前的供应商、MCP、Skills、记忆文件整套保存为命名快照，在标题栏或托盘里一键换成另一套，切换时还会自动把你离开的项目当前状态存回去。Codex 侧同样收获颇丰：**官方 ChatGPT 订阅账号现在也能走本地代理路由**，享受与第三方供应商相同的路由与用量统计；GPT-5.6 全家的上下文窗口与 Sol / Terra / Luna 三档定价一步到位；还新增了原生 Anthropic Messages 上游格式——所在企业禁用了 Claude Code、但没有禁用 Claude API？现在可以**在 Codex 里直接用上 Claude 系列模型**。此外是一大波正确性修复：上游失败不再变成「空回复」、缓存写入不再被双重计费、删掉的 MCP 服务器不再复活、Kimi For Coding 的 256K 窗口终于真正生效。
+
+**[English →](v3.17.0-en.md) | [日本語版 →](v3.17.0-ja.md)**
+
+---
+
+## 使用攻略
+
+本版的新能力主要落在主页顶部的项目切换器、Codex 供应商表单与用量看板里，建议结合以下文档了解：
+
+- **[在 Codex 中用 Claude（本地路由攻略）](../guides/codex-claude-routing-guide-zh.md)**：本版新增的分步攻略，配合「原生 Anthropic Messages 上游」功能使用。攻略讲解如何把 Codex 供应商的上游格式选为 `anthropic`，接入任何只提供 `/v1/messages` 的 Claude 系网关，在 Codex 里用上 Claude 系列模型。
+- **[在 Codex 里使用 Kimi（本地路由攻略）](../guides/codex-kimi-routing-guide-zh.md)**：本版新增的分步攻略。较新的 Codex CLI 走 OpenAI Responses 协议，而 Kimi 开放平台与 Kimi For Coding 暴露的是 Chat Completions 端点，直连通常 404；攻略讲解如何用内置的 `Kimi` / `Kimi For Coding` 预设配合本地路由完成协议转换。
+- **[Codex 官方登录保留](../guides/codex-official-auth-preservation-guide-zh.md)**：了解 CC Switch 如何在切换第三方供应商时保留你的官方 ChatGPT 登录。本版在此基础上更进一步——官方账号本身也可以走代理路由（见下方「新功能」）。
+- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：了解用量看板的数据来源与统计口径。本版修正了缓存写入计费、补齐了 Codex 子代理会话统计，并新增 GPT-5.6 与混元 Hy3 定价。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一官方渠道声明（请务必阅读）
+>
+> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。请仅通过下列官方渠道获取本软件：
+>
+> | 类别     | 唯一官方                                                                       |
+> | -------- | ------------------------------------------------------------------------------ |
+> | 官网     | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | 源码     | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | 下载     | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者     | **[@farion1231](https://github.com/farion1231)**                               |
+> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。
+
+---
+
+## 概览
+
+CC Switch v3.17.0 是 v3.16.5 之后的一个功能大版本，核心是**「项目」**：你可以把 Claude Code / Claude Desktop / Codex 当前的供应商、MCP、Skills、记忆文件状态保存为命名快照——比如编程目录一套「开发」、写作绘图目录一套「创作」——在主页顶部的切换器或托盘的「项目」子菜单里一键整套切换——切换前会自动把你正要离开的项目状态存回去，所以项目里保存的永远是你上次离开时的样子。第二条主线是 Codex：**官方 ChatGPT 订阅账号现在也能走本地代理路由接管**（不需要 API Key，Codex 自己的登录凭据原样透传，绝不覆盖你的官方登录）；配合修正后的客户端身份，`gpt-5.6-luna` 这类最新订阅模型不再误报 404；GPT-5.6 的 372K 上下文窗口注入、Sol / Terra / Luna 三档定价（含 1.25 倍缓存写入费率）与预设默认模型同步就位；Codex 上游格式还新增了原生 Anthropic Messages 协议——它瞄准一个很现实的场景：不少企业禁用了 Claude Code 客户端、但并没有禁用 Claude API，这些用户现在可以让 Codex 直连 Claude API（或任何只提供 `/v1/messages` 的网关），在 Codex 里照常使用 Claude 系列模型。
+
+围绕日常使用的正确性，本版做了三波集中修复。**代理桥**：上游在 2xx 里返回的语义失败不再被转成空回复，而是触发 failover；推理内容、工具结果、system 角色跨 Responses↔Anthropic 桥无损往返；提示缓存断点注入更充分，长对话不再每轮全价重发。**用量计费**：缓存写入 token 此前被同时按输入价和缓存创建价双重计费，现已修正（数据库升级到 schema v13 以保证历史数据口径不乱）；用量与配额查询遇到网络瞬时失败会自动重试、不再把失败体当真实数据缓存。**Codex `config.toml`**：在应用里删掉的 MCP 服务器不再随供应商切换复活；live 文件解析失败时同步宁可报错也不再清空整个文件；「使用通用配置」的合并挪到后端执行，注释与键序不再被打乱。另有 Kimi For Coding 256K 窗口真正生效、Codex 子代理与免费版配额统计补齐、智谱团队套餐配额查询、OpenCode 表单增强与一批预设更新。
+
+**发布日期**：2026-07-13
+
+**更新规模**：69 commits | 172 files changed | +21,067 / -2,464 lines
+
+---
+
+## 重点内容
+
+- **「项目」一键切换**：把供应商、MCP、Skills、记忆文件整套保存为命名快照（比如编程一套、写作绘图一套），从主页顶部或托盘一键切换；切换时自动保存离开项目的当前状态。覆盖 Claude Code、Claude Desktop、Codex 三个作用域，互不干扰。
+- **Codex 官方账号也能走代理路由**：ChatGPT 订阅登录的 Codex 会话可通过本地代理路由，获得与第三方供应商一致的路由与用量统计；官方登录凭据绝不被覆盖或存储。
+- **GPT-5.6 全面就位**：Claude Code 走 Codex 接管时自动注入 372K 上下文窗口；Sol / Terra / Luna 三档定价入库（缓存写入按 1.25 倍输入价计费）；相关预设默认模型升级到 gpt-5.6 家族；修正客户端身份后 `gpt-5.6-luna` 不再误报 404。
+- **在 Codex 里使用 Claude 系列模型（原生 Anthropic Messages 上游）**：不少企业禁用了 Claude Code 客户端、但没有禁用 Claude API——现在把 Codex 供应商的上游格式选为 `anthropic`，即可直连 Claude API 或任何只提供 `/v1/messages` 的网关，本地代理完成 Responses↔Anthropic 双向转换，自带标准 5 分钟提示缓存注入。
+- **代理桥正确性修复**：上游失败 fail-closed 触发 failover 而非空回复；推理 / 工具结果 / system 角色跨桥无损；缓存写入不再双重计费；断点注入更充分。
+- **Codex config.toml 加固**：删掉的 MCP 服务器不再复活；解析失败时 MCP 同步宁可报错也不清空文件；通用配置合并保留注释与键序。
+- **Kimi For Coding 256K 真正生效**：此前的 262144 压缩窗口从未实际生效（被 Claude Code 的 200K 默认钳回），本版补齐模型别名路由与窗口注入；存量供应商需重新套用预设（见「升级提醒」）。
+
+---
+
+## 新功能
+
+### 「项目」：整套配置的命名快照与一键切换
+
+这是本版的头号功能。你可以把当前的供应商、MCP、Skills、记忆文件状态保存为一个命名「项目」，之后在主页顶部的项目切换器或托盘的「项目」子菜单里一键整套切换，不必再逐项手动勾选。
+
+举个典型场景：你有一个目录用来编程、另一个目录用来写作或绘图。编程时要的是一套供应商，配上文件系统 / GitHub 这类 MCP、代码审查 Skills 和写着工程约定的记忆文件；写作或绘图时往往换另一家供应商、另一组 MCP 和完全不同的提示词。以前在两件事之间来回，意味着切供应商、逐个开关 MCP 和 Skills、再改记忆文件；现在把两套状态分别存成「开发」和「绘图」两个项目，换目录干活时在 CC Switch 里点一下，整套配置随之就位。
+
+项目功能覆盖 Claude Code、Claude Desktop 与 Codex 三个作用域（Claude Desktop 由 CC Switch 管理的维度只有供应商，因此其快照只含供应商、应用时不动其它维度）。
+
+几个值得了解的设计：
+
+- **项目是全局实体、按作用域切换**：同一个项目在 Claude Code / Claude Desktop / Codex 三侧各自记录自己的当前项目与快照槽位，在 Codex 页签切换项目绝不会动到 Claude 的配置。
+- **切换即自动保存**：切换项目前，会先把你正要离开的项目在当前作用域下的状态自动存回去——所以项目里保存的永远是你上次离开它时的样子，不需要（也没有）手动「更新快照」按钮。
+- **应用是尽力而为的**：套用快照复用现有的切换原语（先切供应商，再做 MCP / Skills 的最小差异开关，最后启用记忆文件）；快照里引用的某项如果已被删除，只会告警跳过，不会整体回滚。
+- **自动关闭代理接管**：套用项目前会先关闭该作用域内各应用的代理接管，避免快照状态和路由状态打架。
+
+不用项目功能的用户可以在「设置 → 主页显示」里关闭「显示项目切换」，只隐藏主页入口，托盘子菜单与项目数据不受影响。底层由新的 `profiles` 表支撑（数据库自动迁移，无需手动操作），四语界面文案同步就位。
+
+### Codex 官方 ChatGPT 账号的代理路由接管
+
+用 ChatGPT 订阅（OAuth 或 API-key 登录）的 Codex 会话，现在也可以走 CC Switch 的本地代理路由了——官方账号流量获得与第三方供应商一致的路由、格式转换与用量统计。在供应商面板或托盘里选择内置的「OpenAI Official」条目进行接管即可（如果你此前删掉过它，添加供应商时会自动恢复）；路由中的卡片徽标显示「官方账号路由中」。
+
+实现上刻意做到**零凭据存储**：不向 `auth.json` 写任何占位密钥，而是往 `config.toml` 投影一个指向本地代理的专用 `model_provider`，Codex 把自己的 ChatGPT 授权头原样发给代理、代理原样透传给官方端点——`codex-official` 这一行的凭据永远是空的。官方登录本身绝不被覆盖：接管时 OAuth / API-key 材料会保留进备份；官方端返回的 401 / 403 被视为不可重试错误，failover 绝不会把你的对话悄悄挪到另一个账号上。相应地，「切换时保留 Codex 官方登录」这个设置项的文案已更新——路由接管场景下官方登录总是被保留，该开关现在只管不走路由的第三方直切。
+
+### GPT-5.6：上下文窗口、预设默认与三档定价
+
+围绕 GPT-5.6 家族做了三件事：
+
+- **372K 上下文窗口注入**：Claude Code 经代理接管路由到 ChatGPT Codex（Codex OAuth）后端时，自动往生效的 `settings.json` 注入 `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 与 `CLAUDE_CODE_AUTO_COMPACT_WINDOW`（均为 372000），让 Claude Code 不再按默认 200K 窗口过早自动压缩、也不再撑爆上游。注入门控严格：只有当所有已配置的模型键都指向 gpt-5.6 家族时才注入（gpt-5.5 的目录窗口在 272K / 372K 间摇摆，故意不继承）；你手动设置的值永远优先；切走时按镜像条件剥离，程序默认永远不会固化进你的供应商配置。
+- **预设默认模型升级**：Claude Code 与 Claude Desktop 的 Codex OAuth 预设默认路由升级到 gpt-5.6 家族（haiku → `gpt-5.6-luna`，主模型 / sonnet / opus → `gpt-5.6`），自定义 Codex `config.toml` 模板的默认模型同步跟进。
+- **Sol / Terra / Luna 三档定价**：用量看板按官方价目为三档入库——Sol 5 / 30 / 0.50、Terra 2.50 / 15 / 0.25、Luna 1 / 6 / 0.10（美元每百万 token，输入 / 输出 / 缓存读）。与 5.5 及更早版本不同，5.6 家族的**提示缓存写入按 1.25 倍输入价计费**（Sol 6.25 / Terra 3.125 / Luna 1.25），已按此入库并自动修复此前按 0 计的存量行；裸 `gpt-5.6` 及各 effort 后缀变体按 Sol 价对齐。
+
+### 在 Codex 里使用 Claude 系列模型：原生 Anthropic Messages 上游
+
+这个功能来自一个很现实的诉求：**不少企业出于合规策略禁用了 Claude Code 客户端，但并没有禁用 Claude API**。对这些用户来说，模型本身是可用的，缺的只是一个被允许的客户端——现在 Codex 可以补上这个位置。在 Codex 供应商的上游格式选择器里选新增的 `anthropic`，即可直连 Claude API 或任何只提供原生 Anthropic Messages 协议（`/v1/messages`）的网关，本地代理完成 Responses↔Anthropic 的请求、响应与流式双向转换，你在 Codex 里照常对话、照常用工具，背后跑的是 Claude 系列模型。表单配套提供：认证字段选择器（`ANTHROPIC_AUTH_TOKEN` 发 `Authorization: Bearer`，默认；或 `ANTHROPIC_API_KEY` 发 `x-api-key`）、可选的 Claude Code 客户端伪装开关（默认关闭）、以及按供应商的最大输出 token 覆盖（Codex 不发 `model_max_output_tokens`，不设置时回退到保守的 8192，可能截断长回复或重思考回复）。转换桥自动注入标准 5 分钟提示缓存标记（系统提示、工具与历史走缓存而非每轮全价重发），支持 `[1m]` 长上下文标记并补发对应 beta 头，截断的流会如实上报为未完成而不是伪装成功。（[#5071](https://github.com/farion1231/cc-switch/pull/5071)）
+
+### Codex 供应商表单新增「默认模型」输入框
+
+`config.toml` 顶层的 `model` 键现在是表单里的一个可编辑字段：新模型（如 `gpt-5.6`）发布后，你可以直接把现有供应商指过去，不必等预设更新（预设只影响新添加的供应商）。字段与 TOML 编辑器双向同步，候选列表来自模型映射目录与供应商 `/models` 端点的并集，值不在目录里时提供一键「加入映射」。显式填写的值永远优先于映射第一行的隐式回填；模型名与 `base_url` 写入时做了 TOML 转义，杜绝 `/models` 返回的远端数据注入伪造配置行的可能。
+
+### 通用配置切换自动同步扩展到 Codex
+
+v3.16.5 给 Claude 加的「切走时自动把 live 配置里的共享偏好回写到通用配置」现在覆盖 Codex 了：切走一个启用了通用配置的 Codex 供应商时，会先从它的 live `config.toml` 重新提取可共享部分更新到通用配置，再带给下一个供应商——你直接在运行中的 Codex 配置里改的偏好不再在切换时丢失，删掉的键也不会被悄悄注回。提取器会严格剥离供应商专属与注入内容（`model` / `model_provider` / `base_url` / `wire_api`、整个 `[model_providers]` 表、MCP 投影、API key 兜底字段、模型目录指针与注入的 `web_search` 哨兵），密钥永远不会进入共享片段。所有失败仅告警、绝不阻断切换。
+
+### Claude 子代理模型配置
+
+Claude 供应商表单新增「子代理」模型行，写入 `CLAUDE_CODE_SUBAGENT_MODEL`，让 Claude Code 派生的子代理跑在你指定的（通常更便宜或更快的）模型上。支持 `[1M]` 标记；由于子代理模型不会出现在 `/model` 菜单里，该行显示「不在 /model 中展示」占位而没有显示名字段。代理接管路径与模型映射器已同步支持：请求模型与配置的子代理模型一致时原样放行，不再被折叠到默认模型；该键也被排除在共享通用配置之外，不会跨供应商泄漏。（[#4830](https://github.com/farion1231/cc-switch/pull/4830)）
+
+### 回退模型字段的 1M 上下文复选框
+
+Claude 表单的回退模型字段（`ANTHROPIC_MODEL`）现在带上了 Sonnet / Opus / Fable 各档早已有的 1M 复选框：回退模型背后是 1M 窗口时可以如实声明，不再被静默当作 200K。勾选即在模型 id 后追加 `[1M]` 标记，取消即剥离。（[#5124](https://github.com/farion1231/cc-switch/pull/5124)，修复 #3679）
+
+### 智谱团队套餐配额查询
+
+智谱的团队套餐（团队版 Coding Plan）走同一个配额端点但需要 `?type=2` 与两个额外请求头（`bigmodel-organization` / `bigmodel-project`），个人版查询够不到。用量脚本弹窗新增「Zhipu GLM Team（智谱团队）」模板，填入 API Key + 组织 ID + 项目 ID 即可查询团队配额；三项缺一会明确提示补全。四语文案同步。（[#5128](https://github.com/farion1231/cc-switch/pull/5128)）
+
+### OpenCode 表单：请求头与模型 Token 上限编辑器
+
+OpenCode 供应商表单补上了两块此前只能手改 JSON 的配置：**Headers 编辑器**（供应商级 `options.headers`，如 OpenRouter 排行榜要求的 `HTTP-Referer` / `X-Title`，支持增删行、大小写不敏感去重）与**按模型 Token 上限**（`model.limit.context` / `model.limit.output` 数字输入，清空即移除）。「额外选项」块改为可折叠区，已有内容时自动展开；顺带修复了旧占位符过滤会误删真实以 `option-` 开头的选项键的问题。（[#2907](https://github.com/farion1231/cc-switch/pull/2907)）
+
+### 新增模型定价：腾讯混元 Hy3
+
+为 2026-07-06 发布的腾讯混元 Hy3（256K 上下文）入库定价（按发布日牌价 CNY 1 / 4 / 0.25 每百万 token 折算），`hunyuan-hy3` 与 `hy3` 两个 id 都能命中，其用量不再显示 $0。注意 Hy3 实际是按输入长度分档计费，当前单价表按最低档入库，长上下文请求会低估成本，待官方计费页明确后再修正。
+
+---
+
+## 变更
+
+### Codex Chat 路由注入 prompt_cache_key，提升缓存命中
+
+Codex 经本地路由转换到 Chat Completions 上游时，现在会按供应商感知地注入 `prompt_cache_key`：Kimi Coding 与 OpenAI 官方端点自动启用、Kimi 预设显式开启，未知的 OpenAI 兼容网关保持关闭以避免严格 schema 网关报 400。键值只取显式客户端值或真实的客户端会话 ID，绝不生成随机 UUID（那会让每个请求落到不同缓存桶、适得其反）。高级选项里提供自动 / 启用 / 禁用三态覆盖。
+
+### Codex 图片能力自动推断，去掉手动开关
+
+生成的 Codex 模型目录现在只把 CC Switch 确认过的**精确文本-only 名录**内的模型声明为 `input_modalities = ["text"]`；GPT、别名、新后缀变体和一切未知模型一律 fail-open 到 `["text", "image"]`——修复了 GPT 系模型在 Codex IDE 扩展里被误报「不支持图片」的问题。整流器的「纯文本模型预检」开关继续只管代理侧的主动请求改写，不影响目录声明；目录反向导入也会把可推断的能力坍缩掉，未来名录修正或模型升级多模态时自动生效。
+
+### 上下文窗口参数钉进预设，不再作为表单字段
+
+`Codex`（ChatGPT / GPT-5.6）与 `Kimi For Coding` 预设不再在表单里展示「最大上下文 Tokens」「自动压缩窗口」两个输入框，数值直接钉死在预设 env 里（Codex 372000 / 372000，Kimi For Coding 262144 / 262144）——绝大多数用户从不需要碰这两个数字。两个键刻意保留在 env 里：显式钉住能让本地压缩触发点免疫远端实验性配置的下调。极少数想改数字的用户仍可在供应商的 JSON 编辑器里直接编辑这两个键。
+
+### 供应商连通性配置简化
+
+移除了过时的按供应商 `testConfig` 覆盖（超时、重试次数、降级延迟阈值）：轻量的 `base_url` 探测现在始终使用全局连通性检查配置，自动 failover 仍完全由代理超时与熔断器的独立设置驱动。设置界面与接口命名也从「模型测试」术语统一迁移到「连通性检查」。
+
+### 通用（多应用）供应商添加后自动同步
+
+通过「添加供应商」弹窗添加通用（多应用）供应商后，现在会立即推送到各 live 目标配置，不再需要手动再点一次同步。同步失败不阻塞添加——供应商已保存但同步失败时给出非阻断的警告提示。（[#2811](https://github.com/farion1231/cc-switch/pull/2811)）
+
+### 预设更新
+
+- **LongCat-2.0**：美团 LongCat 预设全线（Claude Code / Claude Desktop / Codex / Hermes / OpenClaw / OpenCode）从已退役的 `LongCat-Flash-Chat` / `LongCat-2.0-Preview` 升级到 `LongCat-2.0`，声明真实的 1M（1048576）上下文窗口。LongCat-2.0 是纯文本模型，代理的媒体清洗白名单已同步收录——粘贴进会话的图片会被替换为不支持标记而不是被上游硬拒。（[#4838](https://github.com/farion1231/cc-switch/pull/4838)）
+- **SudoCode**：原 `sudocode.us` 预设原位替换为 `sudocode.chat` 的新赞助商 SudoCode，覆盖六个客户端（Claude 系直连 Anthropic 透传，Codex / OpenCode / OpenClaw / Hermes 默认 `gpt-5.6-sol`）。
+- **火山 / 豆包 / BytePlus 官网链接**：撤销了 v3.16.5 把这三个预设 `websiteUrl` 改为产品主页的改动，恢复为带归因参数的活动 / 邀请链接（这是有意为之的设计）。
+- **Code0.ai**：邀请链接更新为新的 agent 注册链接；API 端点不变。
+- **删除重复的 OpenAI Compatible 预设**：OpenCode 与 OpenClaw 预设列表里的 `OpenAI Compatible` 自定义模板条目被移除——内置的 `custom` 供应商流程本就提供相同的起点，选择器里不再出现两个指向同一处的入口。存量供应商不受影响。
+
+---
+
+## 修复
+
+### Codex OAuth 客户端身份对齐：修复最新 ChatGPT 模型 404
+
+用官方 Codex OAuth 账号经本地代理接管路由时，最新的订阅模型（如 `gpt-5.6-luna`）此前会返回误导性的 `404 Model not found`——明明账号有权限。根因是 ChatGPT 的 Codex 后端按 `originator` + `version` 头做模型分组路由，而 cc-switch 此前自报 `originator: cc-switch` 且不带版本号，被路由到一个 luna 尚未部署的分组。现在接管请求发送与真实 Codex CLI 一致的 `originator: codex_cli_rs` + `version: 0.144.1`，满足 luna 的最低客户端版本要求，经真实后端 A/B 实测确认修复。
+
+### Responses 上游失败不再变成空回复
+
+代理把 Anthropic 格式客户端（Claude Code / Claude Desktop）桥接到 OpenAI Responses 上游时，上游藏在 HTTP 2xx 体里的语义失败（`status:"failed"` 对象、`error` 信封、首个输出前的 `response.failed` SSE 事件）此前会被转换成一个悄无声息的空回合。现在这些失败在重试循环内就被识别为真实错误，failover 能够换一个供应商重试；干净结束但内容不完整的流会如实标记为截断而非完成；无视 `stream:true` 直接返回整个 JSON 文档的网关也能被识别并展开为完整的流式生命周期；客户端历史本身格式错误时立即报错，不再拿着必败的请求把每个供应商都重试一遍。
+
+### 跨 Responses/Anthropic 桥保留推理、工具结果与 system 角色
+
+多轮工具循环里跨 Responses↔Anthropic 桥的内容不再丢失或损坏：加密的推理（reasoning）条目无损往返（往返失败会导致下一轮请求被上游拒绝的问题同步消除）；流式转换器支持官方的推理事件词汇表并在网关跳过增量时从终结事件恢复工具参数；结构化工具结果的 `is_error` 标志、图片与 PDF 文档在两个方向都完整保留，不再被压平成一个 JSON 字符串；历史里的 `system` / `developer` 消息被正确提升为 Anthropic `system`，不再被静默降级成用户发言。计费上，上游请求成功但后续转换失败时用量照记，不再漏账。
+
+### 缓存写入 token 不再双重计费
+
+Codex / Gemini 类供应商上报的 `input_tokens` 同时包含缓存读与缓存写，而成本计算此前只减掉了缓存读——缓存写入 token 被按输入价和缓存创建价**计了两次费**。现在两者都会先行扣除，并且缓存写入数字在跨格式转换（Chat↔Responses↔Anthropic）时不再丢失。为了让历史数据口径不乱，数据库新增一列记录每行 `input_tokens` 的存储语义（schema v12→v13 自动迁移）：旧行按旧口径回算、新行按新口径，Claude 类行不受影响。
+
+### 更强的提示缓存断点注入
+
+在注入 Anthropic `cache_control` 断点的代理路径上（Codex 接管桥与 Bedrock 原生优化器），注入器现在会更充分地使用四个断点预算：除了工具尾、系统尾与最新可缓存消息外，预算有余时再给较早的用户消息加一个锚点，让稳定前缀保持在 Anthropic 20 块回看窗口内——长的、工具密集的对话能持续命中提示缓存，而不是每轮把系统提示、工具与历史全价重发。调用方自带的断点被原样保留（绝不删除、重排或改写）；注入的标记一律使用标准 5 分钟 TTL。
+
+### Kimi For Coding 的 256K 上下文窗口真正生效
+
+Kimi For Coding 预设在 3.16.4 加的 `CLAUDE_CODE_AUTO_COMPACT_WINDOW=262144` 其实**从未生效**：Claude Code 对不认识的模型 id 按 200K 窗口封顶，且压缩窗口取 `min(模型窗口, 设定值)`，262144 被钳回 200K。本版补齐了缺失的两环——预设同时钉上 `CLAUDE_CODE_MAX_CONTEXT_TOKENS`，并把各档模型显式路由到端点的 `kimi-for-coding` 别名（`claude-` 前缀 id 会让 Claude Code 无视这两个窗口参数，非 Claude 别名才是解锁大窗口的关键）。已保存的供应商在切换时也会自动注入这两个窗口默认值，但**别名路由只存在于预设里**——旧预设存下来的供应商实际仍是 200K，需要重新套用一次预设（见「升级提醒」）。
+
+### 删除的 Codex MCP 服务器不再复活
+
+MCP 服务器的权威数据在数据库里，Codex live `config.toml` 中的 `[mcp_servers]` 只是每次写入后重新同步的投影——但切走供应商时这份投影会被固化进供应商快照，导致你在应用里删掉的服务器在下次激活该供应商时死而复生，且逐条对账永远清不掉这个孤儿。现在切走时会把 `[mcp_servers]`（含旧式 `[mcp.servers]`）从存储快照中剥离，已被污染的快照在下次切走时自愈。一个可见的副作用：手写在 Codex 供应商配置里的 `[mcp_servers.*]` 段会在首次切走时被剥出快照——今后请通过 MCP 管理器定义 Codex 的 MCP 服务器（见「升级提醒」）。
+
+### MCP 同步更健壮：解析失败不清空文件、按应用报错
+
+两处修复。其一，向 Codex 写入单个 MCP 服务器时，如果现有 `config.toml` 解析失败，旧逻辑会退到空文档再整体写回——**整个文件被清空**、只剩那一个 MCP 条目；现在直接返回校验错误并保持文件原样。其二，「从应用导入」此前把每个导入器的错误吞成 0，坏掉的 Codex 配置只会显示「导入了 0 个服务器」；现在逐应用尽力导入、失败时报出具体是哪个应用出了问题。切换与保存时的投影也改为只针对目标应用，一个应用的 live 文件解析失败不再连坐阻塞其它应用、也不再把已经成功的切换误报为失败。
+
+### Codex 通用配置合并保留注释与键序
+
+Codex 供应商表单里勾选 / 取消「应用通用配置」此前走前端 TOML 实现整篇重排（解析 → 合并 → 序列化）：注释被丢弃、键被重排、还会凭空多出 `[model_providers]` 这类空表头——就是「config.toml 老被重排」的元凶。现在合并走后端命令、与写 live 配置共用同一套合并语义，手写格式在编辑期合并中完整幸存；针对异步化引入的快速切换竞态也加了双重守卫（操作序号 + 配置基线核对），先发后至的旧结果不会覆盖新状态。
+
+### 受管 Claude 接管只注入单个 auth 占位符
+
+从第三方端点切到 Codex 受管供应商时，`~/.claude/settings.json` 里会同时写入 `ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN` 两个占位符，导致 Claude Code 每次启动都警告「Both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY set」。现在只注入一个：Codex 受管走 `ANTHROPIC_AUTH_TOKEN`、Copilot 走 `ANTHROPIC_API_KEY`，其余 token 键一律清除。注意：升级后如果 live 配置已带着双键，由于「配置未变则跳过重写」的短路逻辑，警告可能仍在——把 Claude 路由开关关再开一次（或切换一次供应商）即可触发重写（见「升级提醒」）。（[#5095](https://github.com/farion1231/cc-switch/pull/5095)，修复 #4919）
+
+### 用量与配额查询：瞬时失败可自动重试、不再毒化缓存
+
+用量与配额查询频繁出现手动刷新也清不掉的「查询失败」，根因是所有传输层失败（包括读响应体中途超时）都被折叠成了「成功但结果为失败」——前端的自动重试从不触发，失败体还被当作真实数据缓存。现在传输失败如实返回错误：react-query 自动重试生效，HTTP 429 与 5xx 一样按瞬时失败处理，保留的上次成功数据按 10 分钟窗口正常过期，失败状态下页脚保留重试入口与真实错误信息。（修复 [#3820](https://github.com/farion1231/cc-switch/issues/3820)）
+
+### Codex 子代理会话用量计入本地统计
+
+Codex 子代理（spawned agent）会话的 token 用量此前完全没进本地统计：子代理日志里携带的是父线程的 `session_id`，多个子代理的记录互相碰撞、被当作重复丢弃。现在解析器按每个文件自己的 `thread_id` 建立唯一身份，并识别子代理日志开头对父线程历史的重放、只用它恢复累计基线而不重复计费；归档日志也按文件名继承同步游标，重新解析只导入新增部分。（[#5187](https://github.com/farion1231/cc-switch/pull/5187)）
+
+### Codex 免费版 30 天配额窗口正常显示
+
+Codex 免费账号按 30 天滚动窗口计量（而非付费版的周窗口），但前端白名单和托盘分组都不认识 `30_day` 这个档位——免费账号唯一的档位被过滤掉后，配额页脚整个空白、托盘也不显示任何配额。现在 30 天档位在页脚和托盘都正常渲染，四语标签同步。（[#4886](https://github.com/farion1231/cc-switch/pull/4886)，修复 #3651）
+
+### 用量看板刷新间隔持久化
+
+用量看板的自动刷新间隔此前是组件内状态，每次重启都重置回 30 秒。现在通过新的应用设置持久化，改动乐观生效、保存失败自动回滚。（[#5057](https://github.com/farion1231/cc-switch/pull/5057)）
+
+### Fable 档模型键不再泄漏进通用配置
+
+Fable 是 v3.16.3 加入的第四个 Claude 模型映射档，但它的 `ANTHROPIC_DEFAULT_FABLE_MODEL(_NAME)` 两个键漏在了供应商专属排除名单之外——某个供应商的 Fable 模型钉选可能泄漏进共享通用配置、再被注入到其它供应商。现已与 haiku / sonnet / opus 三档一样剥离，并顺带补全了 Fable 档的代理接管支持（接管时写入稳定的角色别名、切走时清理陈旧值）。（[#5206](https://github.com/farion1231/cc-switch/pull/5206)，修复 #4272）
+
+### 工具 schema 缺省 type 兜底与无分类供应商的 API Key 输入框
+
+两个供应商侧修复：客户端发来的工具如果 `input_schema` 缺顶层 `type`（或干脆是空 `{}`），代理转换后会被严格网关拒绝，现在根 schema 自动补 `type: "object"`（只补根、不动嵌套子 schema）；历史导入或手工构建的无分类供应商在编辑时看不到 Claude API Key 输入框的问题也已修复——现在只要不是官方 / 云厂商类供应商就显示该字段。（[#5069](https://github.com/farion1231/cc-switch/pull/5069)）
+
+### GLM 5.2 纯文本模型的图片请求兜底
+
+本地代理接管火山 Coding Plan 跑 GLM 5.2 时，请求里的图片块不再产生一个无法恢复的 400：文本-only 名录精确收录 `glm-5.2`（刻意不用前缀匹配，未来的多模态 `glm-5.2v` 不受牵连），预防路径在请求到达前剥离图片；网关那句不含 image 字样的报错（`Model only support text input`）也被反应路径的自证短语名录识别，触发媒体兜底。（修复 [#5025](https://github.com/farion1231/cc-switch/issues/5025)）
+
+### 会话与 live 配置同步小修一组
+
+- **显示重命名的 Codex 会话标题**：在 Codex 里重命名过的会话，会话管理器现在显示新标题而不是回退到首条消息文本；并发写入时的读取也不再立即失败。（[#4927](https://github.com/farion1231/cc-switch/pull/4927)）
+- **OpenCode / OpenClaw / Hermes 的 live 编辑在启动时同步入库**：直接改 live 配置文件（换 base URL、加模型）此前在首次导入后就再也不会被拾取；现在每次启动时对比 live 与库存，差异即更新，全程非致命。（[#4712](https://github.com/farion1231/cc-switch/pull/4712)、[#5098](https://github.com/farion1231/cc-switch/pull/5098)）
+- **OpenCode 会话恢复命令更新**：会话管理器展示与复制的恢复命令从过时的 `opencode session resume <id>` 更正为当前 CLI 的 `opencode -s <id>`。（[#2359](https://github.com/farion1231/cc-switch/pull/2359)）
+- **官方供应商跳过连通性探测**：连通性检查不再对官方类供应商推导出一个无凭据必失败的第一方端点探测（例如裸打 `chatgpt.com/backend-api/codex`），批量检查直接跳过、单独解析明确报错。
+
+---
+
+## 文档
+
+### Codex + Kimi 本地路由攻略
+
+新增分步攻略（中 / 英 / 日三语，含界面截图），讲解如何借助 CC Switch 的本地路由在 Codex CLI 里使用 Kimi：较新的 Codex CLI 走 OpenAI Responses 协议，而 Kimi 开放平台（按量付费，`kimi-k2.7-code`）与 Kimi For Coding（会员制，`kimi-for-coding`）暴露的都是 Chat Completions 端点，直连通常在 `/responses` 上 404。攻略覆盖从内置预设添加供应商到四步协议转换链的完整流程。
+
+### README 赞助商更新
+
+开源 AI 基建项目 `new-api` 加入四语 README 的赞助商表。
+
+---
+
+## 升级提醒
+
+### Kimi For Coding 供应商需重新套用预设
+
+如果你在用 Kimi For Coding 预设创建的供应商，请**重新从预设选择一次并保存**：256K 窗口的关键——把各档模型路由到 `kimi-for-coding` 别名——只存在于新版预设里，旧预设存下来的供应商即使升级后实际仍按 200K 窗口过早压缩。
+
+### 手写的 Codex `[mcp_servers.*]` 会被剥出快照
+
+为了根治「删掉的 MCP 服务器复活」，切走 Codex 供应商时会把 `[mcp_servers]` 段从存储快照中剥离。如果你有直接手写在某个 Codex 供应商配置里的 MCP 服务器，它会在首次切走该供应商时从快照消失——请改用 MCP 管理器（MCP 页签）定义 Codex 的 MCP 服务器，那里的条目才是权威数据、会被自动投影到 live 配置。
+
+### 双 auth 键警告可能需要手动触发一次重写
+
+如果升级后 Claude Code 仍提示「Both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY set」，这是因为 live 配置未变时接管逻辑会短路跳过重写。把 Claude 的路由开关关掉再打开一次（或切换一次供应商）即可写入修正后的单占位符配置，警告随之消失。
+
+### 数据库自动迁移
+
+首次启动 v3.17.0 时数据库会自动从 schema v11 迁移到 v13（新增项目表与用量语义列），无需任何手动操作。如果你有回退到旧版本的习惯，建议先备份 `~/.cc-switch/cc-switch.db`。
+
+---
+
+## 风险提示
+
+本版本继续沿用此前版本对反向代理类功能的风险提示。
+
+**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。本版新增的「官方 ChatGPT 账号代理路由接管」同样属于此类用法，请知悉相同的风险。
+
+**Codex 第三方供应商 Chat 路由**：通过 CC Switch 本地代理把 Codex 请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
+
+**Claude Desktop 第三方供应商代理切换**：通过 CC Switch 内置代理网关把 Claude Desktop 的请求转到第三方供应商时，同样需要遵守目标供应商的计费、合规与数据留存约束。
+
+用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
+
+---
+
+## 致谢
+
+感谢以下贡献者在 v3.17.0 中提交的功能与修复：
+
+- [#5071](https://github.com/farion1231/cc-switch/pull/5071)：新增原生 Anthropic Messages 协议作为 Codex 上游，感谢 @yeeyzy。
+- [#4830](https://github.com/farion1231/cc-switch/pull/4830)：新增 Claude 子代理模型配置，感谢 @AkimioJR。
+- [#5124](https://github.com/farion1231/cc-switch/pull/5124)：给回退模型字段加上 1M 复选框，感谢 @salarkhannn。
+- [#5128](https://github.com/farion1231/cc-switch/pull/5128)：新增智谱团队套餐配额查询，感谢 @zhanxin-xu。
+- [#2907](https://github.com/farion1231/cc-switch/pull/2907)：OpenCode 表单新增请求头与 Token 上限编辑器，感谢 @git1677967754。
+- [#2811](https://github.com/farion1231/cc-switch/pull/2811)：通用供应商添加后自动同步，感谢 @hubutui。
+- [#4838](https://github.com/farion1231/cc-switch/pull/4838)：LongCat 预设升级到 LongCat-2.0，感谢 @solthx。
+- [#5095](https://github.com/farion1231/cc-switch/pull/5095)：受管 Claude 接管只注入单个 auth 占位符，感谢 @fengshao1227。
+- [#5187](https://github.com/farion1231/cc-switch/pull/5187)：Codex 子代理会话用量计入统计，感谢 @starmiaoa。
+- [#4886](https://github.com/farion1231/cc-switch/pull/4886)：修复 Codex 免费版 30 天配额窗口不显示，感谢 @SaladDay。
+- [#5057](https://github.com/farion1231/cc-switch/pull/5057)、[#4927](https://github.com/farion1231/cc-switch/pull/4927)、[#2359](https://github.com/farion1231/cc-switch/pull/2359)：刷新间隔持久化、重命名会话标题显示与 OpenCode 恢复命令修正，感谢 @makoMakoGo。
+- [#5206](https://github.com/farion1231/cc-switch/pull/5206)：Fable 模型键排除出通用配置，感谢 @fzh365。
+- [#5069](https://github.com/farion1231/cc-switch/pull/5069)：工具 schema 缺省 type 兜底与 API Key 输入框恢复，感谢 @Komikawayi。
+- [#4712](https://github.com/farion1231/cc-switch/pull/4712)、[#5098](https://github.com/farion1231/cc-switch/pull/5098)：OpenCode / OpenClaw / Hermes live 配置启动同步，感谢 @allenxu09。
+
+也感谢所有反馈 Codex 官方路由、缓存计费、MCP 同步与配额查询问题的用户——本版相当一部分修复来自这些真实使用场景里的复现线索。
+
+---
+
+## 下载与安装
+
+访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
+
+### 系统要求
+
+| 系统    | 最低版本                   | 架构                                |
+| ------- | -------------------------- | ----------------------------------- |
+| Windows | Windows 10 及以上          | x64 / ARM64                         |
+| macOS   | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | 见下表                     | x64 / ARM64                         |
+
+### Windows
+
+| 文件                                     | 说明                                |
+| ---------------------------------------- | ----------------------------------- |
+| `CC-Switch-v3.17.0-Windows.msi`          | **推荐** - MSI 安装包，支持自动更新 |
+| `CC-Switch-v3.17.0-Windows-Portable.zip` | 便携版，解压即用，不写入注册表      |
+
+Windows ARM64 设备请选择文件名中带 `arm64` 标识的对应制品。
+
+### macOS
+
+| 文件                             | 说明                                          |
+| -------------------------------- | --------------------------------------------- |
+| `CC-Switch-v3.17.0-macOS.dmg`    | **推荐** - DMG 安装包，拖入 Applications 即可 |
+| `CC-Switch-v3.17.0-macOS.zip`    | 解压后拖入 Applications，Universal Binary     |
+| `CC-Switch-v3.17.0-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.17.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.17.0-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| 发行版                                  | 推荐格式    | 安装方式                                                               |
+| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                    | `.AppImage` | 添加执行权限后直接运行，或使用 AUR                                     |
+| 其他发行版 / 不确定                     | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |
@@ -0,0 +1,331 @@
+# CC Switch v3.18.0
+
+> This release lets you do two brand-new things: **hand xAI's Grok CLI (Grok Build) over to CC Switch** — it becomes the eighth managed app, with one-click provider switching, MCP / Skills sync, proxy takeover, and usage statistics all included; and **connect Grok to Claude Code, Claude Desktop, and Codex** — either by signing in with your xAI Grok account directly (device-code authorization, no API key, running on your Grok subscription, with a strict-gateway compatibility layer on the Codex side so codex 0.142+ works too), or with an xAI API key (Codex gets a native Responses direct-connection preset; Claude Code can go through local routing). Just as important is a wave of fixes: the **Codex usage double count introduced in v3.17.0 is fixed**, with an automatic data rebuild after upgrading so the dashboard numbers become real again; **codex 0.144.5+ failing to start because of the model catalog is fixed**; and switching providers on Windows no longer flashes a console window or freezes the UI. Diagnostic logs also move from "wiped on every startup" to persistent across restarts, size-rotated, and fully redacted — and a UI crash now leaves an on-disk report instead of just a blank white window.
+
+**[中文版 →](v3.18.0-zh.md) | [日本語版 →](v3.18.0-ja.md)**
+
+---
+
+## Highlights: What You Can Do Now
+
+- **Manage Grok Build (xAI's Grok CLI)**: add, import, and one-click switch Grok Build providers just like Claude Code / Codex; MCP servers and Skills sync bidirectionally, prompts auto-import on first launch, and session management plus the usage dashboard cover it fully; you can also route it through the local proxy for independent routing, failover, and billing.
+- **Connect Grok with your account or an API key — both paths work**: subscription users complete an xAI device-code sign-in under Settings → OAuth Auth Center (multiple accounts supported), and all three clients — Claude Code, Claude Desktop, Codex — run straight on your Grok subscription with no API key anywhere; pay-as-you-go users connect with an xAI API key instead — Codex has a ready-made "xAI (Grok)" preset connecting natively to `api.x.ai`, and Claude Code can connect through local routing following this release's new guide. The default model is `grok-4.5` throughout.
+- **Get your Codex usage numbers back to reality**: the v3.17.0 fork / sub-agent double count is rooted out at the parser level; the first launch after upgrading automatically backs up the database and rebuilds Codex usage, and the usage page gains a manual "Rebuild Codex Usage" button. Note that on first launch the history is repaired **progressively** — the dashboard numbers first shrink, then fill back in as the background re-import proceeds; this is expected (see "Upgrade Notes").
+- **Upgrade the codex CLI without fear**: the "fails to start" problem caused by codex 0.144.5's strict model-catalog parsing is fixed — generated catalogs now backfill the parser-required fields automatically.
+- **Switch smoothly on Windows**: switching providers or toggling takeover no longer flashes a black console window, and no longer freezes the UI for ~2 seconds (the freeze fix benefits all platforms).
+- **Troubleshoot and share logs with more confidence**: diagnostic logs persist across restarts (20 MB × 4 rotation) and every egress is uniformly redacted — URL credentials, request/response bodies, and sensitive headers never reach disk anymore; a UI crash shows an error card with a Reload button, with the details written to disk.
+- **Multi-turn reasoning and parallel tool calls no longer fall over**: the Responses↔Chat bridge fixes three classes of problems — reasoning content attached to the wrong message, parallel tool calls losing their IDs or their order, and tools with a null schema getting the whole request rejected by strict upstreams.
+- **Use Kimi K3**: the Kimi open-platform presets for Codex / Hermes / OpenClaw / OpenCode gain K3 (1M context), with built-in pricing seeded so its usage no longer shows $0.
+
+---
+
+## Usage Guides
+
+The new capabilities in this release land mainly in the provider presets, Settings → OAuth Auth Center, and the usage dashboard. The following docs are worth reading alongside it:
+
+- **[xAI Grok Account Sign-In (Settings → OAuth Auth Center)](../user-manual/en/1-getting-started/1.5-settings.md)**: the device-code login flow, multi-account management, and the integration's boundaries; please read the client-identity disclosure under "Risk Notice" below before use.
+- **[Using GPT Models in Claude Code (local routing guide)](../guides/claude-codex-routing-guide-en.md)** (now in Chinese / English / Japanese): a new step-by-step guide added in this release. Claude Code always speaks Anthropic Messages to the local `/v1/messages` route, and the local proxy converts each request to the upstream's Responses protocol — a gateway API key, a native Responses endpoint like xAI, or a ChatGPT subscription's Codex service all fit.
+- **[Using Claude Models in Codex (local routing guide)](../guides/codex-claude-routing-guide-en.md)**: a new step-by-step guide in three languages, pairing with v3.17.0's native Anthropic Messages upstream to connect Codex to any Claude-family gateway that only offers `/v1/messages`.
+- **[Usage Statistics](../user-manual/en/4-proxy/4.4-usage.md)**: understand the Usage Dashboard's data sources and how the statistics are counted. This release fixes the usage double count and adds the "Rebuild Codex Usage" maintenance action.
+
+---
+
+> [!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
+
+Both main threads of CC Switch v3.18.0 revolve around xAI Grok. The first is **Grok Build joining the managed apps**: xAI's Grok CLI (live config `~/.grok/config.toml`) becomes the eighth managed app alongside Claude Code, Claude Desktop, Codex, Gemini CLI, OpenCode, OpenClaw, and Hermes — provider add / import / one-click switch, bidirectional MCP and Skills sync, deep-link import, a standalone preset list, and proxy takeover with its own route namespace; the companion "Grok Official" entry supports official-login-state detection and import, and CC Switch never touches the official credentials. The second is **xAI Grok account OAuth sign-in**: device-code authorization replaces the API key, the local proxy injects the access token per request, and on the Claude Code / Claude Desktop side it performs the Anthropic Messages → xAI Responses conversion; the Codex side gets a managed OAuth preset with its own compatibility layer — the ChatGPT-backend-private shapes emitted by codex 0.142+ (namespace tool declarations, private fields) are deterministically flattened and stripped, so the strictly parsing xAI gateway no longer returns 422; API-key users get a separate "xAI (Grok)" native Responses direct-connection preset that goes through no conversion at all.
+
+On correctness, this release concentrates on **the Codex usage double count from v3.17.0**: the replay of the parent thread's history at the start of fork / sub-agent logs is no longer imported as new usage (the parser now only trusts explicit parent identity plus token-signature alignment), a one-time automatic usage rebuild runs after upgrading (schema v16), and the usage page gains a manual rebuild button; proxy-side usage logging becomes idempotent (replays of the same response no longer stack duplicate rows), and the usage page no longer freezes during large session imports. The **Codex conversion layer** gets four more fixes: tool schemas normalized to object type, reasoning attached forward across turns, streamed parallel tool calls keeping their IDs and order, and generated model catalogs backfilling the fields codex 0.144.5+ requires. The diagnostics story matures too: logs persist across restarts, rotate by size, and redact at every egress, and UI crashes are captured by an error boundary and written to disk. Rounding things out: Kimi K3 presets and pricing, corrected OpenClaw preset costs, SudoCode.us restored, and the first-run tray language following the system locale.
+
+**Release date**: 2026-07-21
+
+**Stats**: 52 commits | 217 files changed | +21,452 / -6,285 lines
+
+---
+
+## Added
+
+### Grok Build: The Eighth Managed App
+
+xAI's Grok CLI ("Grok Build", live config `~/.grok/config.toml`) is now a first-class citizen in CC Switch: provider add / import / one-click switch (with a "restart Grok Build to apply" toast), app visibility and config-directory override settings, session manager and usage dashboard coverage, prompts with first-launch auto-import, `ccswitch://` deep-link provider import, and local proxy takeover — with its own `/grokbuild/v1/responses` route namespace, an independent failover queue, and per-app proxy settings; forwarding reuses Codex's Responses path but never shares Codex's provider namespace or circuit-breaker state.
+
+MCP servers sync bidirectionally with Grok's `[mcp_servers]` table, with the dialect differences smoothed over: Grok infers the transport from `command` / `url` and uses a `headers` field, so exports strip the explicit `type` and rename `http_headers` to `headers`, while imports infer the transport back. Skills gain a Grok Build enable flag too.
+
+On presets, the Codex list was deliberately **not** borrowed (an early cut leaked China-direct providers and Codex default models into the Grok form); instead Grok Build ships its own curated list: only aggregators and relays that actually carry Grok models, with the default model normalized to `grok-4.5` (`x-ai/grok-4.5` on namespaced routers). The tools panel installs Grok via the official xAI installer first (`x.ai/cli/install.sh` / `install.ps1`), with the npm package `@xai-official/grok` as fallback; installs confirmed as native self-update via `grok update`, while npm installs keep npm-anchored updates — the self-update is gated on positive native detection, so it can never touch a different kind of install. UI copy is in sync across all four locales. ([#5453](https://github.com/farion1231/cc-switch/pull/5453))
+
+### Grok Official Login: Detection, Import, and Protection
+
+A new "Grok Official" provider entry maps to the Grok CLI's own built-in xAI OAuth login: selecting it hides the connection fields and writes an empty `~/.grok/config.toml`, and CC Switch never stores or touches the official credentials. Live-config reads, backups, and official-state writes now use syntax-only TOML validation, so an official-login (empty) config round-trips normally; importing the live config while Grok is in official login state yields "Grok Official set as current" instead of an error, matching Codex behavior. Official-state detection is deliberately wired only into the manual import command — the startup auto-importer still rejects official-state configs, so a "Grok Official" entry you deleted never comes back on the next launch. Proxy takeover of an official-login Grok config is skipped automatically, with a clear rejection on the manual path, consistent with the existing "never proxy official providers" policy.
+
+### Sign In with Your xAI Grok Account: Claude Code and Claude Desktop
+
+Claude Code and Claude Desktop gain an "xAI (Grok)" preset that replaces the API key with an OAuth device-code login: requests go through the local proxy, which performs the Anthropic Messages → xAI Responses API conversion and injects the access token per request, with `grok-4.5` as the default model on every tier (the Claude Desktop preset maps the `claude-*`-style role IDs to `grok-4.5` upstream so it passes Desktop's third-party model validation).
+
+Settings → OAuth Auth Center gains an xAI section: device-code login (user code with a copy button, verification link, waiting / cancel / retry), multiple accounts with a default-account picker, per-account removal, and re-auth badges — an account whose refresh token was revoked stays visible as "expired" instead of disappearing, and auth status refetches every 15 seconds so a server-side revocation surfaces on its own.
+
+The integration's boundaries are pinned shut: no matter what the endpoint / format fields in the form say, the upstream is always `https://api.x.ai/v1/responses` (Responses format); OAuth endpoints are resolved via OIDC discovery but strictly validated to `auth.x.ai` over https; refresh tokens live in `~/.cc-switch/xai_oauth_auth.json` (`0600` on Unix; access tokens are memory-only); and OAuth error bodies never enter error messages or logs. Pricing for `grok-4.5` ($2 input / $6 output / $0.50 cache read per million tokens) is seeded in sync so its usage no longer records $0, with existing databases picking the row up automatically on next launch. Four-locale copy included. Please read the client-identity disclosure under "Risk Notice" before use.
+
+Not using OAuth and only have a pay-as-you-go xAI API key? You can still connect it to Claude Code: xAI's API endpoint is standard Responses protocol, so add it as an ordinary Responses provider — a custom provider with `https://api.x.ai/v1` and your API key, upstream format set to Responses, converted between Anthropic Messages ↔ Responses by local routing; it's the same recipe as the [Using GPT Models in Claude Code](../guides/claude-codex-routing-guide-en.md) guide. On the Codex side there's a ready-made API-key preset — see the next section.
+
+### Codex Straight to xAI: Managed OAuth and Native API-Key Presets
+
+Codex gets two ways to talk to xAI directly — OAuth managed if you have a Grok subscription, native direct connection if you have an API key:
+
+- **The "xAI (Grok) OAuth" managed preset** runs Codex on a Grok subscription. The form hides the key / endpoint / format fields and shows the account picker, "fetch models" uses the signed-in account, and the provider is pinned to native Responses with the base URL and per-request token enforced by the proxy — edits are ignored, so the managed route cannot be redirected. Because codex 0.142+ emits ChatGPT-backend-private request shapes (`type:"namespace"` tool declarations make xAI's strict parser return a straight 422, plus private fields like `prompt_cache_retention`, `safety_identifier`, `external_web_access`, the `additional_tools` carrier, and sampling knobs grok-4.5 doesn't support), the OAuth route adds a compatibility layer on top of the native passthrough: namespace tools are flattened to top-level function tools (with the same sha256-truncated naming as the Chat path) and restored to namespaced form on the response side for both streaming and non-streaming, and unsupported fields are stripped — all deterministic field removals / structural lifts, never semantic rewrites, so prompt-cache prefixes stay stable. The layer is gated exclusively on the xAI OAuth provider type; no other provider's traffic is touched.
+- **The "xAI (Grok)" API-key preset** connects natively to Responses at `api.x.ai/v1`, with a 500K-context `grok-4.5` catalog entry built in. This preset does **not** receive the xAI-specific compatibility transforms above — API-key users on codex 0.142+ can still hit xAI's strict parser, and the OAuth preset is the fully compatible path.
+
+xAI OAuth token failures are classified as non-retryable, so failover never quietly moves your conversation onto a different Grok account.
+
+### UI Crash Capture: On-Disk Reports and a Reload Screen
+
+A React error boundary now wraps the entire UI (including the database-recovery screen): a renderer crash shows a "Something went wrong in the interface" card with a Reload button instead of a blank white window, and global `error` / `unhandledrejection` handlers persist renderer errors to disk — previously a JS crash left zero on-disk evidence. Everything the frontend logs passes two redaction layers: a structured serializer that redacts by sensitive property name (`tokens` / `apiKeys` / `credentials` variants all normalized to match, hiding the entire value including nested objects) and by value shape (token prefixes, PEM headers, high-entropy opaque strings), then a single text egress whose ordered regex chain covers URL query values and credentials, auth headers and schemes, and named secret containers — even in double-encoded JSON. JSON arriving as a string is re-parsed and redacted structurally, and oversized structured input is dropped entirely rather than truncated — a truncated JSON string would fall back to the weaker text regexes and could leak. The settings toggles were also relabeled to say what they actually control: "Application Diagnostic Logs" (cc-switch.log) versus the proxy's "Record Request Usage" (the stats database, which never was a text log). Four locales in sync.
+
+### "Rebuild Codex Usage" Maintenance Button
+
+The usage dashboard's maintenance section gains "Rebuild Codex Usage": after backing up the database, it wipes only `codex_session`-sourced detail rows, their `_codex_session` daily rollups, and the Codex sync cursors, then re-imports every rollout file from scratch with the corrected parser — the recovery path for databases already inflated by the double-count bug below, and the retry path for deferred fork files whose parent log has since been restored. The manual rebuild fails hard when the pre-rebuild backup cannot be written (the automatic migration variant only warns, since blocking startup on an unwritable backup directory would be the worse outcome after an upgrade); the whole backup → reset → re-import sequence holds the session-sync lock, so the 60-second background sync cannot interleave with the wipe; and completion always sends exactly one frontend refresh notification — including when the re-import returns zero rows or fails — so the dashboard never keeps showing pre-reset numbers. Cursor cleanup matches rollout paths purely by shape (a `rollout-{uuid}` filename under a `sessions` / `archived_sessions` segment), so cursors recorded under an old `CODEX_HOME` are cleaned too. Four locales in sync.
+
+### Session Import Observability: Deferred Files and Suspected Duplicates
+
+Session sync results now report `filesScanned`, `deferredFiles` — fork rollouts whose parent log is missing or whose parent markers conflict are held back without writing a cursor, so a later sync or a manual rebuild retries them instead of importing on a guess — and `suspectedDuplicates`: a post-insert probe checks each imported row for a pre-existing same-fingerprint row (via the `idx_request_logs_dedup_lookup_expr` expression index) and logs a warning per hit. If the double-count bug ever regresses, it will announce itself in the logs instead of silently inflating the totals.
+
+### Kimi K3 in Presets and Built-In Pricing
+
+The Kimi open-platform presets for Codex / Hermes / OpenClaw / OpenCode gain Kimi K3 (1M context window), appended after K2.7 Code so existing default-model behavior is unchanged. The built-in pricing table gains `kimi-k3` (official list price: $3 input / $15 output / $0.30 cache read per million tokens) plus a bare `k3` alias — the Kimi For Coding subscription reports its model under the short id `k3`, which would otherwise match no pricing row (same precedent as the existing `hunyuan-hy3` / `hy3` pair). Existing databases pick both rows up automatically on next launch, without touching user-edited pricing.
+
+### SudoCode.us Returns, Coexisting with SudoCode.chat
+
+The two unrelated companies that happen to share the "SudoCode" name are now two separate presets: the sponsor is renamed "SudoCode.chat", and the previously replaced-in-place "SudoCode.us" returns with its original endpoints, models, and icon, plus a distinct Hermes slug so both can coexist in the additive `~/.hermes/config.yaml`. Counting the new Grok Build preset list, SudoCode.chat ships in seven apps and SudoCode.us in all eight.
+
+---
+
+## Changed
+
+### Diagnostic Logs: Persistent Across Restarts, Size-Rotated, and Never Recording Secrets
+
+`cc-switch.log` is no longer wiped on every startup — the log that could have explained a crash used to be gone by the time the app reopened — and instead rotates at 20 MB with 4 archives kept (~100 MB cap, versus a single file that could balloon to 1 GB before); the previously unbounded `crash.log` rotates at 5 MB with 2 archives, with the check / rotate / append sequence under one lock so concurrent panics cannot lose an archive.
+
+Persistent logs make verbatim secrets a real exposure (users attach these files to public issues), so the same change scrubs every backend log egress: upstream URLs are logged with userinfo / query / fragment stripped (origin-only when no known secret is available to substitute, since a credential could be embedded in the path); request and response bodies are never logged — replaced by byte counts, a short hash, or a safe classification (`sse` / `html` / `json-like` / `binary-or-encoded`, …) that keeps the transform-debugging signal without the content; response headers go through an allowlist (unlisted headers log name-only); the secret values currently in use (API key, access token) are substituted out of any logged URL that carries them; and MCP custom-field values are omitted. The log plugin also registers earlier (updater / startup failures become diagnosable), the persisted log level applies as soon as the database opens and fails closed to Info, and the "Enable Diagnostic Logs" switch now gates frontend-originated log writes too. **Log files written by earlier versions are not retroactively scrubbed** — see "Upgrade Notes".
+
+### Preset Picker: Sponsors Grouped, Everything Else Alphabetized
+
+The preset picker's default order becomes four tiers: official first, then the prime partner, then sponsor presets (in the same order as the README sponsor table, which the preset files were physically reordered to match), then all remaining presets sorted alphabetically by display name instead of file order. An entry matching multiple tiers lands only in the earliest one, so nothing shows up twice.
+
+### Preset "Get API Key" Links Updated
+
+The key-application links on the RunAPI, ClaudeCN, ZetaAPI, and APINebula presets now open each provider's current registration / referral page (ClaudeCN also moved domains: claudecn.top → claudecn.ai). Referral tags remain confined to these links and the README — website links and API endpoints stay untouched.
+
+---
+
+## Fixed
+
+### Codex Fork / Sub-Agent Replayed Parent History No Longer Counted as New Usage (the v3.17.0 Double Count)
+
+Fixes the v3.17.0 usage inflation: forking a Codex task or spawning a sub-agent in copy mode re-counted the parent conversation's token history as new usage — users reported single days jumping by billions of tokens, byte-identical parent/child rows, and empty forks carrying usage they never consumed. Fork / sub-agent rollout files begin by replaying the parent thread's history, and the old parser located the takeover boundary heuristically (the first `thread_settings_applied` event, object-shaped `subagent` source markers): the boundary landed too early when the parent's own settings changes appeared in the replay, and the current string-shaped source markers weren't recognized at all, importing the entire replayed parent history verbatim. The new parser trusts only explicit parent identity — `forked_from_id` on the child's `session_meta`, or `source.subagent.thread_spawn.parent_thread_id`, with a conflict between the two deferring the file — anchors each thread's identity to the rollout filename UUID, loads the parent rollout's own pre-fork token-count sequence, and strips the child's replayed prefix by aligning token signatures against it: replayed events only restore the cumulative baseline and are never inserted as rows. Sub-agent logs that carry no replayed history are now counted as live usage, also fixing the opposite-direction undercount where real sub-agent consumption was skipped as suspected replay. ([#5335](https://github.com/farion1231/cc-switch/issues/5335), [#5433](https://github.com/farion1231/cc-switch/issues/5433), [#5381](https://github.com/farion1231/cc-switch/issues/5381))
+
+### Proxy Usage Logging Is Now Idempotent: Response-Scoped Stable Keys
+
+When a terminal usage event carried no message id — the norm for Codex `/responses` traffic through the local proxy — the dedup key fell back to a random UUID, so every retry / replay of the same upstream response minted a fresh key and `INSERT OR REPLACE` stacked a new row each time; one reporter's database held the same usage combination 2,078 times. The parser now takes the key from the response envelope itself — the Codex `response.completed` event's `response.id` (ids from `response.created` are discarded), Chat Completions `chatcmpl` ids, and the Gemini `responseId` — scoped as `session:{app_type}:{provider_id}:{id}`: the same response replayed against a different provider during failover still bills once per provider without cross-provider collisions (Claude keeps the bare `session:{id}` shape so proxy rows continue to converge with session-log imports). When no envelope id exists at all, the fallback is a deterministic SHA-256 over the response's usage semantics rather than a random UUID — an identical replay must collide into the same key for dedup to work — and the final database write becomes a guarded insert-if-absent within the dedup window instead of an unconditional REPLACE. ([#5496](https://github.com/farion1231/cc-switch/issues/5496))
+
+### Usage Page No Longer Freezes During Large Session Imports
+
+Opening the usage page while a big import ran could lock the whole UI up: every inserted row fired a refresh notification, each notification made the frontend re-run all ~10 usage queries, and those queries contended with the importer for the single database connection while it parsed rollout files tens of megabytes large, line by line — on duplicate-inflated databases the three compounded each other. Session sync now notifies the frontend once per completed pass; all session importers are serialized behind a single-flight lock (a manual "sync now" queues behind the running pass instead of racing it); the blocking parse work runs on a dedicated blocking thread so it no longer starves the async runtime driving the UI's commands; and the 60-second background tick skips missed runs instead of bursting to catch up.
+
+### codex 0.144.5+ No Longer Fails to Start on CC Switch-Generated Model Catalogs
+
+codex ≥ 0.144.5 parses external model catalogs strictly and rejects the whole file when an entry is missing `supports_reasoning_summaries` — both the Codex CLI and the desktop app failed to launch, and deleting the generated catalog didn't help because any provider save regenerated it the same way. The root cause: CC Switch clones its catalog template from the machine-shared `models_cache.json`, whose field set is whatever the last-writing codex process produced — a coexisting older codex build kept rewriting the cache without the field the newer parser requires. Generated catalogs now backfill parser-required fields from the bundled static template, and only when absent (dynamic values always win); optional capability fields whose "missing = parser default" semantics must survive are deliberately not backfilled.
+
+### Windows: No More Console Flash or UI Freeze When Switching Providers
+
+Switching providers or toggling takeover on Windows flashed a transient console window and froze the UI for up to ~2 seconds. Three causes, three fixes: the `codex debug models --bundled` probe launches `codex.cmd` through `cmd.exe`, which in a GUI-subsystem app spawns its own console — the child process is now created with `CREATE_NO_WINDOW`; the model-catalog template was regenerated on every switch — it's now cached process-wide after the first successful load (failures stay retryable, so a bad first probe cannot poison the cache), and the Codex CLI starts at most once per app run; and `switch_provider` was a synchronous command on the main thread — it's now async with the real work on a blocking thread, still serialized by the per-app switch lock. The freeze fix benefits all platforms; the console-flash fix is Windows-specific.
+
+### Tool Schemas with Null, Missing, or Union Parameter Types Accepted by Strict Upstreams
+
+Built-in Codex tools such as `codex_app__automation_update` declare `parameters: null` (or `type: null`), which strict OpenAI-compatible upstreams like DeepSeek reject with a 400 for the entire request — killing tool-using sessions routed through the proxy. The Responses→Chat bridge now normalizes every tool's parameters to a `type:"object"` schema: null or missing parameters (including the nested-form missing case) become `{"type":"object","properties":{}}`, a non-object `type` (including `type: null`) is corrected to `"object"` in place, and top-level `oneOf` union schemas get a root `type:"object"` added with their branches preserved untouched. The same object-type guarantee was extended to the Codex→Anthropic tool path's `input_schema`. Existing `properties` / `required` are never dropped. ([#4706](https://github.com/farion1231/cc-switch/pull/4706), [#5315](https://github.com/farion1231/cc-switch/pull/5315), fixes #4705, #4783)
+
+### Reasoning Models Keep Their Thinking Across Multi-Turn Codex Chat Conversations
+
+With a reasoning model (e.g. kimi-k2-thinking) behind the proxy's Responses→Chat bridge, multi-turn history mangled the thinking: each turn's `reasoning` item got glued onto the tail of the **previous** assistant message, leaving the following assistant turn with no `reasoning_content` — models would visibly break off mid-conversation. Responses semantics place reasoning **before** the message it belongs to, so the bridge now attaches reasoning forward to the assistant message or tool call that follows it; genuine trailing reasoning back-attaches only at a confirmed tail (end of input, or a turn boundary such as an incoming user message — where it was previously silently discarded), appending to any embedded reasoning already present; and pending reasoning is always consumed at boundaries, so it can never leak across a user turn into a later assistant message. ([#5508](https://github.com/farion1231/cc-switch/pull/5508))
+
+### Streamed Parallel Tool Calls Keep Their IDs and Their Order
+
+Two bugs in the Chat→Responses streaming bridge corrupted parallel tool calls from upstreams that split identity across chunks: a continuation delta carrying an empty `id` overwrote the real `call_id` (the Codex client then saw `call_id:""` and couldn't match tool results to calls), and tool calls were emitted the moment they individually became ready, so a later index whose name arrived early could jump ahead of an earlier one — reordering parallel calls. Empty ids are now ignored, and emission goes through a consecutive-index gate that releases tool calls strictly in Chat `index` order, waiting on any not-yet-identified earlier index; no fake call id is ever synthesized mid-stream (only as a last resort at stream finalization, which also skips nameless calls defensively and still emits sparse indexes). ([#5310](https://github.com/farion1231/cc-switch/pull/5310))
+
+### Managed-OAuth Providers Reliably Flagged as "Needs Local Routing"
+
+The "needs routing" badge and switch-time warning were derived from the provider's API format — the wrong signal for managed-OAuth providers (Copilot, Codex OAuth, xAI), whose credential is injected by the proxy regardless of upstream format: a managed provider on a native format got no warning and failed silently without takeover. Routing need is now decided by a single shared predicate: official providers never need routing, managed-OAuth providers always do, and format-based rules apply only to the remaining cases. The switch-time gate also checks the right readiness signal per app: per-app takeover status for most apps (the old gate looked only at a global proxy-running flag, missing "the proxy runs but this app isn't taken over"), while Claude Desktop keeps watching the proxy process itself — the backend's takeover status has no Claude Desktop field, so a uniform per-app gate would have left Desktop warning forever. Claude Desktop provider forms now force proxy mode and lock the model-mapping toggle for every managed-OAuth type, not just xAI. Four locales in sync.
+
+### Tool Updates Work When Node Lives in nvm / fnm / mise
+
+Anchored npm update and repair commands invoked npm by absolute path, but npm's launcher resolves `node` via its `#!/usr/bin/env node` shebang against PATH — and a GUI-launched app inherits only the system PATH, without the version-manager directories, so updates for tools installed via nvm / fnm / mise silently failed. Every anchored npm invocation now prefixes PATH with npm's own sibling `bin` directory, so npm and its shebang resolve to the same Node install; the Codex self-repair (uninstall + reinstall) path is covered too.
+
+### Deleted Default Skill Repositories Stay Deleted
+
+Default Skill repositories were re-seeded on every startup by a "supplement missing defaults" pass, so a default repo you deleted silently returned on the next launch. Seeding is now one-time per database, tracked by a settings flag; databases that already contain repositories at upgrade time get the flag set without any re-seeding, so existing selections are untouched. ([#5356](https://github.com/farion1231/cc-switch/pull/5356))
+
+### First-Run Tray Language Follows the System Locale
+
+Before any language was chosen in settings, the tray menu was hardcoded to Simplified Chinese — on English / Japanese / Traditional-Chinese systems the main UI correctly followed the OS locale while the tray disagreed, until the user switched language once. The tray now derives its first-run language from the OS locale with the same precedence rules as the frontend (including `zh-TW` / `zh-HK` / `zh-Hant` → Traditional Chinese); an explicitly chosen language always wins, and unreadable locales fall back to Chinese as before. ([#4355](https://github.com/farion1231/cc-switch/pull/4355))
+
+### Failed Imports Show the Real Error and Refresh the List
+
+Every failed "import from live config" produced an empty error toast, because Tauri's `invoke` rejects with the backend's error **string** while the handler read `.message` off it. The backend's actual message is now shown (with a localized generic fallback), and the provider list refreshes even on failure, so side effects committed before the error are visible immediately.
+
+### OpenClaw Preset Model Costs Corrected to Official List Prices
+
+Fifteen OpenClaw preset entries carried cost values in the wrong unit or unconverted currency — the `cost` field is USD per million tokens, but e.g. `glm-5.1` was listed at `0.001/0.001` (≈1000× undervalued, so its usage showed near-zero cost) while `deepseek-v4-pro` carried unconverted CNY values (overvalued). All entries now carry official list prices in $/M; subscription-plan and free-tier endpoints deliberately show list prices too, so plan users see the standard value of their usage. Providers created from these presets going forward get the corrected values; previously added providers keep the config they were created with.
+
+### A Batch of Small UI Fixes
+
+- **AiHubMix icon**: the Codex app's AiHubMix preset was the only one missing its brand-icon fields and rendered a generic icon; it now matches the other apps.
+- **Two missing locale keys backfilled**: the reason fragment in Codex's "needs routing because it uses Anthropic Messages format" toast rendered in Chinese inside an otherwise-localized sentence (`proxyReasonAnthropicMessages` existed in no locale file), and the provider form's key-status loading label had shipped only as a hardcoded default since April; both now exist in zh / en / ja / zh-TW.
+
+---
+
+## Documentation
+
+### Codex ↔ Claude Routing Guides, Both Directions
+
+Two new guides complete the pair — "Claude models inside the Codex client" and "Responses providers inside the Claude Code client":
+
+- **[Using Claude Models in Codex](../guides/codex-claude-routing-guide-en.md)** (Chinese / English / Japanese, with screenshots): pairs with v3.17.0's native Anthropic Messages upstream to connect Codex to a Claude-family `/v1/messages` gateway; the v3.17.0 release notes now link to it.
+- **[Using GPT Models in Claude Code](../guides/claude-codex-routing-guide-en.md)** (Chinese / English / Japanese, with screenshots): drive Claude Code with Responses-speaking providers (a gateway API key, or a ChatGPT subscription's Codex service) — Claude Code always speaks Anthropic Messages to the local `/v1/messages` route, and the proxy converts each request to the upstream's Responses protocol.
+
+### README Sponsor Updates
+
+SubRouter joins the sponsor table across the four README languages; the pinned Kimi sponsor copy is refreshed to K3 with banners served from the Moonshot CDN; RunAPI benefit copy is refreshed, and sponsor rows are reordered to match the in-app preset order.
+
+---
+
+## Upgrade Notes
+
+### Automatic Database Migration and the One-Time Codex Usage Rebuild
+
+Upgrading from v3.17.0 runs three schema migrations in sequence (v13 → v16): v14 rebuilds the `proxy_config` table to admit Grok Build (existing per-app proxy settings are all carried over, and a `grokbuild` row is added); v15 adds Grok Build enablement columns to the MCP-server and Skills tables; and v16 triggers the one-time automatic Codex usage rebuild — the database is first backed up under `backups/`, `codex_session` data and cursors are reset, and the normal startup sync re-imports everything with the corrected parser. Typical datasets take seconds; the heaviest dataset measured (1,801 rollout files / 1.5 GB) took about 65 seconds. Later launches are incremental as before. If you're in the habit of rolling back to older versions, back up `~/.cc-switch/cc-switch.db` yourself first.
+
+**Please note on first launch**: the history repair completes **progressively** — the rebuild proceeds in the background with the startup sync, and during that window the Codex history numbers on the usage dashboard first drop to zero and then fill back in step by step. This is expected behavior, not data loss. The post-rebuild total will usually be **smaller** than before the upgrade: the part inflated by double counting is squeezed out, and what remains is your real usage.
+
+### Boundaries of the Rebuild
+
+- The rebuild recomputes usage from the rollout JSONL files, so **history whose source log was already deleted cannot be reconstructed**.
+- Fork files whose parent rollout is missing are deferred and reported instead of imported on a guess; restore the parent log and run "Rebuild Codex Usage" to import them later.
+- Historical proxy-source duplicate rows are permanently retained — the migration rebuilds only session-sourced data, and no cleanup pass for past proxy inflation exists; the idempotent logger only guarantees no new duplicates from this point on.
+
+### Old Log Files Are Not Retroactively Scrubbed
+
+From this release on, diagnostic logs are no longer cleared at startup and persist across restarts (up to ~100 MB of rotated runtime logs plus ~15 MB of crash logs). **Log files written by earlier versions are not retroactively scrubbed** and may contain API keys, tokens, or URLs with credentials — review pre-upgrade logs before sharing them publicly.
+
+### Grok Build Installs via the Official Installer Script
+
+Installing or reinstalling Grok Build now prefers the official xAI installer, fetching `x.ai/cli/install.sh` (or `install.ps1` on Windows) at install time, with npm as fallback; existing npm installs keep updating via npm.
+
+### Built-In Pricing Rows Auto-Appended
+
+New pricing rows (`grok-4.5`, `kimi-k3`, `k3`) are appended automatically on next launch via insert-if-absent; user-edited pricing rows are never overwritten.
+
+---
+
+## Risk Notice
+
+### xAI Grok OAuth Sign-In (New in This Release — Please Read)
+
+This release's xAI Grok OAuth integration **reuses the public OAuth client identity and scopes registered for the official Grok CLI** (`client_id b1a00492-073a-47ea-816f-4c329264a828`, scope including `grok-cli:access`), rather than an application identity registered by CC Switch. xAI may not support this use, and **it could lead to account restriction or suspension — use at your own risk**. The feature is entirely opt-in: if you don't add an xAI provider, nothing changes. On first login it creates `~/.cc-switch/xai_oauth_auth.json` (refresh tokens only, `0600` on Unix; access tokens are held in memory) and contacts `auth.x.ai` and `api.x.ai` through your configured outbound proxy, with no local callback port.
+
+### Carried-Over Reverse-Proxy Notices
+
+**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.
+
+**Third-party provider routing**: when CC Switch's local proxy converts and forwards Codex, Claude Desktop, or Grok Build requests to third-party providers, each provider may have different requirements for billing, compliance, and data retention. Read the target provider's terms before use.
+
+By enabling these features, users accept the related risks. CC Switch is not responsible for account restrictions, warnings, or service suspensions caused by using these features.
+
+---
+
+## Thanks
+
+Thanks to the following contributors for the features and fixes in v3.18.0:
+
+- [#5453](https://github.com/farion1231/cc-switch/pull/5453): first-class Grok Build support (the core of the eighth managed app), thanks @YUZHEthefool.
+- [#5508](https://github.com/farion1231/cc-switch/pull/5508): attach reasoning forward across the Responses→Chat bridge, thanks @ka79376046.
+- [#5310](https://github.com/farion1231/cc-switch/pull/5310): preserve streamed parallel tool-call identity and order, thanks @SaladDay.
+- [#5315](https://github.com/farion1231/cc-switch/pull/5315): default Codex tool parameters to an object schema, thanks @Komikawayi.
+- [#4706](https://github.com/farion1231/cc-switch/pull/4706): normalize tool parameter types for strict OpenAI-compatible providers, thanks @Ryan2128.
+- [#5356](https://github.com/farion1231/cc-switch/pull/5356): keep deleted default Skill repositories deleted, thanks @allenxu09.
+- [#4355](https://github.com/farion1231/cc-switch/pull/4355): first-run tray language follows the system locale, thanks @LaiYueTing.
+- [#5138](https://github.com/farion1231/cc-switch/pull/5138): extend backend CI to Linux / Windows / macOS, thanks @zayokami.
+
+Thanks also to everyone who reported Codex usage anomalies, new-codex startup failures, and tool-call problems — this release's most important fixes came directly from reproduction clues in those real-world reports.
+
+---
+
+## Download & Install
+
+Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) and download the build for your system.
+
+### System Requirements
+
+| System  | Minimum Version      | Architecture                        |
+| ------- | -------------------- | ----------------------------------- |
+| Windows | Windows 10 and later | x64 / ARM64                         |
+| macOS   | macOS 12 (Monterey)+ | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | See table below      | x64 / ARM64                         |
+
+### Windows
+
+| File                                     | Description                                      |
+| ---------------------------------------- | ------------------------------------------------ |
+| `CC-Switch-v3.18.0-Windows.msi`          | **Recommended** - MSI installer with auto-update |
+| `CC-Switch-v3.18.0-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.18.0-macOS.dmg`    | **Recommended** - DMG installer, drag to Applications |
+| `CC-Switch-v3.18.0-macOS.zip`    | Unzip and drag to Applications, Universal Binary      |
+| `CC-Switch-v3.18.0-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.18.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.18.0-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| Distribution                            | Recommended Format | Install Command                                                        |
+| --------------------------------------- | ------------------ | ---------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`             | `sudo dpkg -i CC-Switch-*.deb` or `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`             | `sudo rpm -i CC-Switch-*.rpm` or `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`             | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                    | `.AppImage`        | Make executable and run directly, or use AUR                           |
+| Other distributions / unsure            | `.AppImage`        | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |
@@ -0,0 +1,331 @@
+# CC Switch v3.18.0
+
+> 本リリースでは、まったく新しい 2 つのことができるようになります。**xAI の Grok CLI（Grok Build）を CC Switch で管理する**——8 番目の管理対象アプリとして、プロバイダーのワンクリック切り替え、MCP / Skills 同期、プロキシテイクオーバー、使用量統計をすべて利用できます。そして **Grok を Claude Code、Claude Desktop、Codex へ接続する**——xAI Grok アカウントで直接サインインする方法（デバイスコード認証、API key 不要、Grok サブスクリプションで動作。Codex 側には厳格ゲートウェイ互換レイヤーがあり codex 0.142+ でも動きます）と、xAI API key で接続する方法（Codex にはネイティブ Responses 直結プリセット、Claude Code はローカルルーティング経由）の両方に対応します。修正も重要です。**v3.17.0 で混入した Codex 使用量の二重計上を修正**し、アップグレード後にデータを自動再構築してダッシュボードの数字を実態に戻します。**codex 0.144.5+ がモデルカタログ起因で起動できない問題も修正**。Windows でのプロバイダー切り替え時にコンソールウィンドウが一瞬表示されたり UI が固まったりする問題も解消しました。診断ログは「起動のたびに消去」から、再起動をまたいで保持・サイズローテーション・全面的な秘密情報除去へ移行し、UI クラッシュも真っ白な画面ではなくディスクに記録が残ります。
+
+**[English →](v3.18.0-en.md) | [中文版 →](v3.18.0-zh.md)**
+
+---
+
+## ハイライト：本リリースでできること
+
+- **Grok Build（xAI の Grok CLI）を管理**：Claude Code / Codex と同じように、Grok Build のプロバイダーを追加・インポート・ワンクリック切り替えできます。MCP サーバーと Skills は双方向同期、プロンプトは初回起動時に自動インポート、セッション管理と使用量ダッシュボードも完全対応。ローカルプロキシによるテイクオーバーで、独立したルーティング・failover・課金も利用できます。
+- **Grok の接続はアカウントでも API Key でも**：サブスクリプションユーザーは「設定 → OAuth 認証センター」でデバイスコードによる xAI サインインを行い（複数アカウント対応）、Claude Code・Claude Desktop・Codex の 3 クライアントが API key なしで Grok サブスクリプションで動きます。従量課金ユーザーは xAI API key で接続——Codex には `api.x.ai` へネイティブ直結する「xAI (Grok)」プリセットがあり、Claude Code は本リリースの新ガイドに沿ってローカルルーティングで接続できます。既定モデルはいずれも `grok-4.5` です。
+- **Codex の使用量を実態に戻す**：v3.17.0 の fork / サブエージェント二重計上をパーサーレベルで根治しました。アップグレード後の初回起動でデータベースをバックアップして Codex 使用量を自動再構築し、使用量ページには手動の「Codex 使用量を再構築」ボタンも追加。なお初回起動時の履歴修復は**段階的に**進みます——数字がいったん減り、バックグラウンドの再インポートに伴って徐々に埋め戻されるのは想定どおりの動作です（「アップグレード時の注意」参照）。
+- **codex CLI を安心してアップグレード**：codex 0.144.5 の厳格なモデルカタログ解析による「起動できない」問題を修正。生成カタログはパーサー必須フィールドを自動補完します。
+- **Windows でスムーズに切り替え**：プロバイダー切り替えやテイクオーバーの切り替えで黒いコンソールウィンドウが一瞬表示されることがなくなり、UI が約 2 秒固まる問題も解消しました（フリーズ修正は全プラットフォームに効きます）。
+- **ログの調査と共有をより安心に**：診断ログは再起動をまたいで保持（20 MB × 4 ローテーション）され、すべての出口で一律に秘密情報を除去——URL 内の認証情報、リクエスト / レスポンスボディ、機微なヘッダーはディスクに残りません。UI クラッシュはエラーカードと再読み込みボタンで受け止め、詳細をディスクへ記録します。
+- **マルチターンの reasoning と並列ツール呼び出しが壊れない**：Responses↔Chat ブリッジで、reasoning の誤った付け先、並列ツール呼び出しの ID 消失・順序入れ替わり、tool schema が null の場合にリクエスト全体が拒否される問題の 3 種類を修正しました。
+- **Kimi K3 を使う**：Codex / Hermes / OpenClaw / OpenCode の Kimi オープンプラットフォームプリセットに K3（1M コンテキスト）を追加し、内蔵価格も登録。使用量が $0 と表示されなくなります。
+
+---
+
+## 利用ガイド
+
+本リリースの新機能は、主にプロバイダープリセット、「設定 → OAuth 認証センター」、使用量ダッシュボードにあります。以下のドキュメントもあわせてご覧ください：
+
+- **[xAI Grok アカウントサインイン（設定 → OAuth 認証センター）](../user-manual/ja/1-getting-started/1.5-settings.md)**：デバイスコードログインの流れ、複数アカウント管理、連携の境界について説明します。利用前に下記「リスク通知」のクライアント識別情報の開示を必ずお読みください。
+- **[Claude Code で GPT モデルを使う（ローカルルーティングガイド）](../guides/claude-codex-routing-guide-ja.md)**（中国語 / 英語 / 日本語）：本リリース追加のステップバイステップガイドです。Claude Code は常にローカルの `/v1/messages` ルートに対して Anthropic Messages を話し、ローカルプロキシが各リクエストを上流の Responses プロトコルへ変換します——ゲートウェイの API key、xAI のようなネイティブ Responses endpoint、ChatGPT サブスクリプションの Codex サービスのいずれにも使えます。
+- **[Codex で Claude モデルを使う（ローカルルーティングガイド）](../guides/codex-claude-routing-guide-ja.md)**：本リリース追加の 3 言語ガイド。v3.17.0 の「ネイティブ Anthropic Messages 上流」と組み合わせ、`/v1/messages` のみを提供する Claude 系ゲートウェイへ Codex を接続します。
+- **[使用量統計](../user-manual/ja/4-proxy/4.4-usage.md)**：使用量ダッシュボードのデータソースと集計方法を確認できます。本リリースでは二重計上を修正し、「Codex 使用量を再構築」メンテナンス操作を追加しました。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一の公式チャネル（必ずお読みください）
+>
+> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。本ソフトウェアは下記の公式チャネルからのみ入手してください：
+>
+> | チャネル     | 唯一の公式                                                                     |
+> | ------------ | ------------------------------------------------------------------------------ |
+> | 公式サイト   | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者         | **[@farion1231](https://github.com/farion1231)**                               |
+> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は直ちに操作を中止し、GitHub Issues からご報告ください。
+
+---
+
+## 概要
+
+CC Switch v3.18.0 の 2 本柱はどちらも xAI Grok を中心に据えています。1 つ目は **Grok Build の管理対象アプリ入り**です。xAI の Grok CLI（live 設定 `~/.grok/config.toml`）が、Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes に並ぶ 8 番目の管理対象アプリになりました——プロバイダーの追加 / インポート / ワンクリック切り替え、MCP・Skills の双方向同期、ディープリンクインポート、独立したプリセットリスト、専用ルート名前空間つきのプロキシテイクオーバー。併設の「Grok 公式」エントリは公式ログイン状態の検出とインポートに対応し、CC Switch が公式認証情報に触れることはありません。2 つ目は **xAI Grok アカウントの OAuth サインイン**です。デバイスコード認証が API key を置き換え、ローカルプロキシがリクエストごとにアクセストークンを注入します。Claude Code / Claude Desktop 側では Anthropic Messages → xAI Responses の変換を行い、Codex 側は管理下 OAuth プリセットと専用互換レイヤーを備えます——codex 0.142+ が発する ChatGPT バックエンド固有の形（namespace ツール宣言や非公開フィールド）を決定的に平坦化・除去し、厳格に解析する xAI ゲートウェイが 422 を返さなくなります。API key ユーザーには、変換を一切通さない「xAI (Grok)」ネイティブ Responses 直結プリセットも用意しました。
+
+正確性の面では、**v3.17.0 の Codex 使用量二重計上**を集中的に修正しました。fork / サブエージェントログ冒頭にある親スレッド履歴のリプレイを新規使用量として取り込まなくなり（パーサーは明示的な親識別子とトークン署名の照合のみを信頼）、アップグレード後に一度だけ使用量を自動再構築（schema v16）、使用量ページには手動再構築ボタンを追加。プロキシ側の使用量記録は冪等になり（同じレスポンスのリプレイが重複行を積み上げない）、大量セッションのインポート中に使用量ページが固まる問題も解消しました。**Codex 変換レイヤー**にはさらに 4 つの修正——tool schema の object 型への正規化、reasoning のターンをまたぐ前方アタッチ、ストリーミング並列ツール呼び出しの ID と順序の保持、codex 0.144.5+ が要求するカタログフィールドの補完。診断まわりも成熟し、ログは再起動をまたいで保持・サイズローテーション・全出口で秘密情報除去、UI クラッシュはエラーバウンダリで捕捉してディスクへ記録します。ほかにも Kimi K3 のプリセットと価格、OpenClaw プリセット価格の修正、SudoCode.us の復活、トレイの初回言語がシステムロケールに従う改善などを含みます。
+
+**リリース日**: 2026-07-21
+
+**Stats**: 52 commits | 217 files changed | +21,452 / -6,285 lines
+
+---
+
+## 追加機能
+
+### Grok Build：8 番目の管理対象アプリ
+
+xAI の Grok CLI（Grok Build、live 設定 `~/.grok/config.toml`）が CC Switch の第一級市民になりました。プロバイダーの追加 / インポート / ワンクリック切り替え（切り替え後は「Grok Build を再起動して適用」のトースト表示）、アプリ表示と設定ディレクトリ上書きの設定、セッション管理と使用量ダッシュボード対応、初回起動時のプロンプト自動インポート、`ccswitch://` ディープリンクによるプロバイダーインポート、そしてローカルプロキシテイクオーバー——専用の `/grokbuild/v1/responses` ルート名前空間、独立した failover キュー、アプリ別プロキシ設定を持ちます。転送は Codex の Responses 経路を再利用しますが、Codex のプロバイダー名前空間や circuit breaker の状態を共有することはありません。
+
+MCP サーバーは Grok の `[mcp_servers]` テーブルと双方向同期し、方言の差異も吸収します。Grok は `command` / `url` からトランスポートを推定し `headers` フィールドを使うため、エクスポート時は明示的な `type` を取り除き `http_headers` を `headers` にリネームし、インポート時は逆方向に推定して戻します。Skills にも Grok Build の有効化フラグが付きました。
+
+プリセットはあえて Codex のリストを流用**していません**（初期の実装では中国向け直結プロバイダーや Codex の既定モデルが Grok のフォームに混入していました）。Grok Build 専用に整理したリストとして、実際に Grok モデルを扱うアグリゲーターと中継サービスのみを収録し、既定モデルは `grok-4.5`（名前空間型ルーターでは `x-ai/grok-4.5`）に正規化しています。ツールパネルでの Grok インストールは xAI 公式インストーラー（`x.ai/cli/install.sh` / `install.ps1`）を優先し、npm パッケージ `@xai-official/grok` をフォールバックにします。ネイティブと確認されたインストールは `grok update` で自己更新し、npm インストールは npm 経由の更新を維持——自己更新はネイティブ検出が確定した場合にのみ動くため、別種のインストールを壊すことはありません。4 言語の UI 文言も同期済みです。（[#5453](https://github.com/farion1231/cc-switch/pull/5453)）
+
+### Grok 公式ログイン：検出・インポート・保護
+
+新しい「Grok 公式」プロバイダーエントリは、Grok CLI 内蔵の xAI OAuth ログインに対応します。選択すると接続フィールドが隠れ、空の `~/.grok/config.toml` を書き込みます。CC Switch が公式認証情報を保存したり触れたりすることはありません。live 設定の読み取り・バックアップ・公式状態の書き込みは構文レベルのみの TOML 検証に変更され、公式ログイン状態（空の設定）が正常に往復します。Grok が公式ログイン状態のときに「live 設定からインポート」すると、エラーではなく「Grok 公式を現在のプロバイダーに設定しました」となり、Codex と同じ挙動になります。公式状態の検出は意図的に手動インポートコマンドだけに配線されています——起動時の自動インポートは公式状態の設定を引き続き拒否するため、削除した「Grok 公式」エントリが次回起動時に復活することはありません。公式ログイン設定へのプロキシテイクオーバーは自動的にスキップされ、手動操作でも明確に拒否されます。既存の「公式プロバイダーはプロキシしない」方針と一貫しています。
+
+### xAI Grok アカウントでサインイン：Claude Code と Claude Desktop
+
+Claude Code と Claude Desktop に「xAI (Grok)」プリセットが加わり、API key の代わりに OAuth デバイスコードログインを使います。リクエストはローカルプロキシを通り、Anthropic Messages → xAI Responses API の変換とリクエストごとのアクセストークン注入が行われます。既定モデルは全 tier で `grok-4.5` です（Claude Desktop プリセットは `claude-*` 形式のロール ID を上流の `grok-4.5` にマッピングし、Desktop のサードパーティモデル検証を通過させます）。
+
+「設定 → OAuth 認証センター」に xAI セクションが追加されました。デバイスコードログイン（コピー可能なユーザーコード、確認リンク、待機 / キャンセル / 再試行）、複数アカウントと既定アカウントの選択、アカウント別の削除、再認証バッジ——refresh token が失効したアカウントは消えるのではなく「期限切れ」として表示され続け、認証状態は 15 秒ごとに再取得されるため、サーバー側の失効も自然に表面化します。
+
+連携の境界は固定されています。フォームの endpoint / 形式フィールドをどう変えても上流は常に `https://api.x.ai/v1/responses`（Responses 形式）。OAuth endpoint は OIDC discovery で解決しますが https の `auth.x.ai` のみに厳格検証。refresh token は `~/.cc-switch/xai_oauth_auth.json`（Unix ではパーミッション `0600`、access token はメモリのみ）。OAuth のエラーボディはエラーメッセージにもログにも決して入りません。`grok-4.5` の価格（100 万 token あたり入力 $2 / 出力 $6 / キャッシュ読み取り $0.50）も登録され、使用量が $0 と記録されなくなります。既存データベースは次回起動時に自動で行を取り込みます。4 言語対応。利用前に「リスク通知」のクライアント識別情報の開示をお読みください。
+
+OAuth を使わず、従量課金の xAI API key しかない場合でも、Claude Code へ接続できます。xAI の API endpoint は標準の Responses プロトコルなので、通常の Responses プロバイダーとして追加してください——カスタムプロバイダーに `https://api.x.ai/v1` と API key を設定し、上流形式に Responses を選ぶと、ローカルルーティングが Anthropic Messages ↔ Responses を変換します。[Claude Code で GPT モデルを使う](../guides/claude-codex-routing-guide-ja.md)ガイドと同じ手順です。Codex 側には既製の API key プリセットがあります（次節参照）。
+
+### Codex から xAI へ直結：管理下 OAuth と API Key ネイティブの 2 プリセット
+
+Codex には xAI へ直結する 2 つの道があります——Grok サブスクリプションなら管理下 OAuth、API key ならネイティブ直結です：
+
+- **「xAI (Grok) OAuth」管理下プリセット**：Codex を Grok サブスクリプションで動かします。フォームは key / endpoint / 形式フィールドを隠してアカウント選択を表示し、「モデルを取得」はサインイン済みアカウントで実行。プロバイダーはネイティブ Responses に固定され、base URL とリクエストごとのトークンはプロキシが強制します——編集しても無視されるため、管理下ルートを別の宛先へ向けることはできません。codex 0.142+ は ChatGPT バックエンド固有のリクエスト形を発します（`type:"namespace"` ツール宣言は xAI の厳格パーサーで即 422。ほかに `prompt_cache_retention`、`safety_identifier`、`external_web_access`、`additional_tools` キャリア、grok-4.5 が対応しないサンプリングパラメータ）。そのため OAuth ルートはネイティブパススルーの上に互換レイヤーを重ねます。namespace ツールはトップレベルの function ツールへ平坦化（Chat 経路と同じ sha256 切り詰め命名）し、レスポンス側ではストリーミング・非ストリーミングの両方で namespace 形へ復元、未対応フィールドは除去——すべて決定的なフィールド削除 / 構造変換であり、意味的な書き換えは一切ないため、プロンプトキャッシュの前方一致は安定を保ちます。このレイヤーは xAI OAuth プロバイダー型だけにゲートされ、他のプロバイダーのトラフィックには触れません。
+- **「xAI (Grok)」API Key プリセット**：`api.x.ai/v1` のネイティブ Responses に直結し、500K コンテキストの `grok-4.5` カタログエントリを内蔵します。このプリセットには上記の xAI 専用互換変換は**適用されません**——codex 0.142+ の API key ユーザーは依然 xAI の厳格パーサーに当たる可能性があり、完全互換の道は OAuth プリセットです。
+
+xAI OAuth のトークンエラーは再試行不能に分類されるため、failover が会話を別の Grok アカウントへ静かに移すことはありません。
+
+### UI クラッシュの捕捉：エラーのディスク保存と再読み込み画面
+
+React のエラーバウンダリが UI 全体（データベース復旧画面を含む）を包むようになりました。レンダラーがクラッシュすると、真っ白なウィンドウの代わりに「インターフェースでエラーが発生しました」カードと再読み込みボタンが表示され、グローバルの `error` / `unhandledrejection` ハンドラーがレンダラーのエラーをディスクへ永続化します——以前は JS クラッシュの証拠がディスクに一切残りませんでした。フロントエンドが書き出すログはすべて二層の秘密情報除去を通ります。構造化シリアライザーが機微なプロパティ名（`tokens` / `apiKeys` / `credentials` の変種を正規化して照合し、ネストされたオブジェクトを含む値全体を隠す）と値の形（トークン接頭辞、PEM ヘッダー、高エントロピーな不透明文字列）で除去し、次に唯一のテキスト出口の順序付き正規表現チェーンが URL クエリ値と認証情報、認証ヘッダーとスキーム、名前付きシークレットコンテナ（二重エンコードされた JSON も対象）をカバーします。文字列として届いた JSON は再パースして構造的に除去し、過大な構造化入力は切り詰めではなく全体を破棄します——切り詰められた JSON 文字列は弱いテキスト正規表現にフォールバックして漏えいの恐れがあるためです。設定のトグル名も実態に合わせて変更しました。「アプリ診断ログ」（cc-switch.log）と、プロキシの「リクエスト使用量を記録」（統計データベースであり、もともとテキストログではありません）です。4 言語同期。
+
+### 「Codex 使用量を再構築」メンテナンス操作
+
+使用量ダッシュボードのメンテナンスに「Codex 使用量を再構築」が加わりました。データベースをバックアップした後、`codex_session` ソースの明細行、対応する `_codex_session` 日次集計、Codex 同期カーソルだけを消去し、修正済みパーサーで全 rollout ファイルを最初から再インポートします——下記の二重計上バグで膨張したデータベースの復旧経路であり、親ログが復元された保留 fork ファイルの再試行経路でもあります。手動再構築は事前バックアップを書き込めない場合にハードフェイルします（自動移行版は警告のみ。アップグレード後にバックアップディレクトリ書き込み不能で起動がブロックされる方が悪い結果だからです）。バックアップ → リセット → 再インポートの全工程はセッション同期ロックを保持し、60 秒間隔のバックグラウンド同期が消去と交錯できません。完了時にはちょうど 1 回のフロントエンド更新通知を必ず送ります——再インポートが 0 行やエラーで終わった場合も含めて——のでダッシュボードがリセット前の数字のまま止まることはありません。カーソルの掃除はパスの形（`sessions` / `archived_sessions` セグメント配下の `rollout-{uuid}` ファイル名）だけで照合するため、旧 `CODEX_HOME` 配下に記録されたカーソルも掃除できます。4 言語同期。
+
+### セッションインポートの可観測性：保留ファイルと重複疑い
+
+セッション同期の結果に `filesScanned`、`deferredFiles`、`suspectedDuplicates` が加わりました。`deferredFiles` は、親ログの欠落や親マーカーの矛盾がある fork rollout をカーソルを書かずに保留し、後の同期や手動再構築で再試行するものです——推測でインポートしません。`suspectedDuplicates` は、挿入後に各行を同一フィンガープリントの既存行と照合（`idx_request_logs_dedup_lookup_expr` 式インデックス経由）し、ヒットごとに警告を記録します。二重計上バグが将来再発しても、総量を静かに膨らませるのではなく、ログの中で自ら名乗り出ます。
+
+### Kimi K3 のプリセットと内蔵価格
+
+Codex / Hermes / OpenClaw / OpenCode の Kimi オープンプラットフォームプリセットに Kimi K3（1M コンテキストウィンドウ）を追加しました。K2.7 Code の後ろに追加したため、既存の既定モデルの挙動は変わりません。内蔵価格テーブルには `kimi-k3`（公式表示価格：100 万 token あたり入力 $3 / 出力 $15 / キャッシュ読み取り $0.30）と裸の `k3` エイリアスを追加——Kimi For Coding サブスクリプションはモデルを短縮 id `k3` で報告するため、これがないとどの価格行にも一致しません（既存の `hunyuan-hy3` / `hy3` ペアと同じ前例です）。既存データベースは次回起動時に両行を自動で取り込み、ユーザーが編集した価格には触れません。
+
+### SudoCode.us が SudoCode.chat と並んで復活
+
+たまたま「SudoCode」という名前を共有する無関係な 2 社が、別々のプリセットになりました。スポンサーは「SudoCode.chat」に改名し、以前その場で置き換えられていた「SudoCode.us」が元の endpoint・モデル・アイコンとともに復帰。Hermes の slug も区別され、追記型の `~/.hermes/config.yaml` の中で両者が共存できます。新しい Grok Build プリセットリストを含めると、SudoCode.chat は 7 アプリ、SudoCode.us は全 8 アプリに収録されています。
+
+---
+
+## 変更
+
+### 診断ログ：再起動をまたいで保持、サイズローテーション、秘密情報は記録しない
+
+`cc-switch.log` は起動のたびに消去されなくなりました——クラッシュを説明できたはずのログが、アプリを開き直したときには消えていたのです。代わりに 20 MB でローテーションし、アーカイブを 4 つ保持します（上限約 100 MB。以前は単一ファイルが 1 GB まで膨張し得ました）。これまで無制限だった `crash.log` は 5 MB ローテーション・アーカイブ 2 つになり、チェック / ローテーション / 追記の一連の処理を 1 つのロックで包んで、並行 panic がアーカイブを失わないようにしました。
+
+ログの永続化は、秘密情報の平文がそのまま露出リスクになることを意味します（ユーザーはこれらのファイルを公開 issue に添付します）。そこで同じ変更で、バックエンドのすべてのログ出口を洗浄しました。上流 URL は userinfo / query / fragment を取り除いた形でのみ記録（置換できる既知のシークレットがない場合は origin のみ。パスに認証情報が埋まっている可能性があるため）。リクエストとレスポンスのボディは一切記録せず、バイト数、短いハッシュ、または安全な分類（`sse` / `html` / `json-like` / `binary-or-encoded` など）に置き換え——変換デバッグに必要なシグナルは残り、中身は残りません。レスポンスヘッダーは許可リスト方式（リスト外は名前のみ記録）。現在使用中のシークレット値（API key、access token)は、それを含むあらゆる記録 URL から置換されます。MCP カスタムフィールドの値は省略。ログプラグインの登録は早められ（アップデーターや起動時の障害が診断可能に）、永続化されたログレベルはデータベースが開き次第適用され、障害時は Info へ安全側に倒れます。「診断ログを有効化」スイッチはフロントエンド発のログ書き込みも制御するようになりました。**アップグレード前の古いログファイルは遡って洗浄されません**——「アップグレード時の注意」を参照してください。
+
+### プリセット選択：スポンサーをグループ化し、残りは名前順
+
+プリセット選択の既定順序が 4 層になりました。公式が最初、次に主要パートナー、その後にスポンサープリセット（README のスポンサー表と同じ順序。プリセットファイルも物理的に並べ替えて揃えました）、最後に残りすべてをファイル順ではなく表示名のアルファベット順で並べます。複数の層に該当するエントリは最も早い層にだけ現れ、重複表示はありません。
+
+### プリセットの「API Key を取得」リンクを更新
+
+RunAPI、ClaudeCN、ZetaAPI、APINebula プリセットの key 申請リンクを、各社の現在の登録 / 紹介ページに更新しました（ClaudeCN はドメインも移転：claudecn.top → claudecn.ai）。紹介タグはこれらのリンクと README に限定され、公式サイトリンクと API endpoint には手を付けていません。
+
+---
+
+## 修正
+
+### Codex fork / サブエージェントのリプレイ済み親履歴を新規使用量として計上しない（v3.17.0 の二重計上を根治）
+
+v3.17.0 の使用量膨張を修正します。Codex タスクの fork やコピーモードでのサブエージェント生成で、親会話の token 履歴が新規使用量として再計上されていました——1 日の使用量が数十億 token 跳ね上がる、親子でバイト単位に同一の行が並ぶ、空の fork が消費していない使用量を背負う、といった報告がありました。fork / サブエージェントの rollout ファイルは冒頭で親スレッドの履歴をリプレイします。旧パーサーは引き継ぎ境界をヒューリスティックに探していました（最初の `thread_settings_applied` イベント、オブジェクト形の `subagent` ソースマーカー）。親自身の設定変更がリプレイに現れると境界が早すぎる位置に落ち、現行の文字列形ソースマーカーはまったく認識されず、リプレイされた親履歴が丸ごとインポートされていました。新パーサーは明示的な親識別子だけを信頼します——子の `session_meta` の `forked_from_id` または `source.subagent.thread_spawn.parent_thread_id`。両者が矛盾する場合はファイルを保留します。スレッドの識別は rollout ファイル名の UUID に固定し、親 rollout 自身の fork 前 token カウント系列を読み込み、トークン署名の照合で子のリプレイ済みプレフィックスを取り除きます。リプレイイベントは累積ベースラインの復元にのみ使われ、行として挿入されることはありません。リプレイ履歴を持たないサブエージェントログは実使用量として計上されるようになり、実際のサブエージェント消費がリプレイ疑いとしてスキップされる逆方向の計上漏れも同時に修正しました。（[#5335](https://github.com/farion1231/cc-switch/issues/5335)、[#5433](https://github.com/farion1231/cc-switch/issues/5433)、[#5381](https://github.com/farion1231/cc-switch/issues/5381)）
+
+### プロキシ使用量記録を冪等に：レスポンス由来の安定キー
+
+終端の使用量イベントにメッセージ id がない場合（ローカルプロキシ経由の Codex `/responses` トラフィックでは通常）、重複排除キーはランダム UUID にフォールバックしていました——同じ上流レスポンスの再試行 / リプレイのたびに新しいキーが作られ、`INSERT OR REPLACE` が毎回新しい行を積み上げます。ある報告者のデータベースには同じ使用量の組み合わせが 2,078 回入っていました。パーサーはキーをレスポンスのエンベロープ自体から取るようになりました——Codex `response.completed` イベントの `response.id`（`response.created` の id は破棄）、Chat Completions の `chatcmpl` id、Gemini の `responseId`——スコープは `session:{app_type}:{provider_id}:{id}`。failover で同じレスポンスが別プロバイダーに再生された場合もプロバイダーごとに 1 回ずつ課金され、プロバイダー間で衝突しません（Claude は裸の `session:{id}` 形を維持し、プロキシ行はセッションログのインポートと収束し続けます）。エンベロープ id がまったくない場合のフォールバックは、ランダム UUID ではなくレスポンスの使用量セマンティクスに対する決定的 SHA-256 です——同一のリプレイが同じキーに衝突しなければ重複排除は成立しません。最終的なデータベース書き込みも、無条件の REPLACE から重複排除ウィンドウ内の「存在しなければ挿入」に変わりました。（[#5496](https://github.com/farion1231/cc-switch/issues/5496)）
+
+### 大量セッションインポート中に使用量ページが固まらない
+
+大きなインポートの実行中に使用量ページを開くと、UI 全体が固まることがありました。行を挿入するたびに更新通知が飛び、通知のたびにフロントエンドが約 10 個の使用量クエリをすべて再実行し、それらのクエリが、数十 MB の rollout ファイルを 1 行ずつ解析中のインポーターと唯一のデータベース接続を奪い合う——重複で膨張したデータベースでは三者が互いに増幅し合っていました。セッション同期は 1 パス完了ごとに 1 回だけ通知するようになり、すべてのセッションインポーターはシングルフライトロックの後ろで直列化され（手動の「今すぐ同期」は実行中のパスと競争せず、後ろに並びます）、ブロッキングな解析処理は専用のブロッキングスレッドへ移されて UI コマンドを駆動する非同期ランタイムを飢えさせなくなり、60 秒間隔のバックグラウンド実行は取りこぼし分をまとめて実行せずスキップします。
+
+### codex 0.144.5+ が CC Switch 生成のモデルカタログで起動不能にならない
+
+codex ≥ 0.144.5 は外部モデルカタログを厳格に解析し、エントリに `supports_reasoning_summaries` がないとファイル全体を拒否します——Codex CLI もデスクトップアプリも起動できず、生成カタログを削除しても、プロバイダーを保存するたびに同じ形で再生成されるため解決しませんでした。根本原因は、CC Switch がカタログのテンプレートをマシン共有の `models_cache.json` から複製していることです。そのフィールド構成は最後に書き込んだ codex プロセス次第で、共存する旧版 codex が新パーサー必須のフィールドを持たない形でキャッシュを書き換え続けていました。生成カタログは、同梱の静的テンプレートからパーサー必須フィールドを補完するようになりました。補完は欠けている場合のみで（動的な値が常に優先）、「欠落 = パーサー既定値」のセマンティクスを保つべきオプションの能力フィールドは意図的に補完しません。
+
+### Windows：プロバイダー切り替えでコンソールが一瞬表示されず、固まらない
+
+Windows でプロバイダーを切り替えたりテイクオーバーを切り替えたりすると、コンソールウィンドウが一瞬表示され、UI が最大約 2 秒固まっていました。原因は 3 つ、修正も 3 つです。`codex debug models --bundled` プローブは `cmd.exe` 経由で `codex.cmd` を起動しますが、GUI サブシステムのアプリではこれが独自のコンソールを生成します——子プロセスは `CREATE_NO_WINDOW` で作成するようにしました。モデルカタログのテンプレートは切り替えのたびに再生成されていました——初回の成功ロード後にプロセス全体でキャッシュし（失敗は再試行可能のままなので、初回プローブの失敗がキャッシュを汚しません）、Codex CLI の起動はアプリ実行ごとに最大 1 回になりました。`switch_provider` はメインスレッド上の同期コマンドでした——非同期化して実処理をブロッキングスレッドに移し、アプリ別の切り替えロックによる直列化は維持しています。フリーズ修正は全プラットフォームに効き、コンソール表示の修正は Windows 固有です。
+
+### tool schema が null / 欠落 / union 型でも厳格上流に拒否されない
+
+Codex の組み込みツール（`codex_app__automation_update` など）は `parameters: null`（または `type: null`）を宣言しますが、DeepSeek のような厳格な OpenAI 互換上流はリクエスト全体を 400 で拒否し、プロキシ経由のツール利用セッションが死んでいました。Responses→Chat ブリッジはすべてのツールの parameters を `type:"object"` schema に正規化します。null または欠落（ネスト形の欠落を含む）は `{"type":"object","properties":{}}` に、object 以外の `type`（`type: null` を含む）はその場で `"object"` に修正、トップレベルの `oneOf` union schema にはルートの `type:"object"` を追加して分岐はそのまま保持します。同じ object 型の保証を Codex→Anthropic ツール経路の `input_schema` にも拡張しました。既存の `properties` / `required` を捨てることはありません。（[#4706](https://github.com/farion1231/cc-switch/pull/4706)、[#5315](https://github.com/farion1231/cc-switch/pull/5315)、#4705・#4783 を修正）
+
+### 推論モデルがマルチターンの Codex Chat 会話で思考を失わない
+
+推論モデル（kimi-k2-thinking など）をプロキシの Responses→Chat ブリッジで使うと、マルチターン履歴が思考を壊していました。各ターンの `reasoning` 項目が**前の**アシスタントメッセージの末尾に貼り付けられ、直後のアシスタントターンに `reasoning_content` がなくなる——モデルが会話の途中で目に見えて壊れていました。Responses のセマンティクスでは reasoning は属するメッセージの**前**に置かれます。ブリッジは reasoning を、その後に続くアシスタントメッセージまたはツール呼び出しへ前方アタッチするようになりました。本物の末尾 reasoning だけが、確定した末尾（入力の終端、またはユーザーメッセージのようなターン境界——以前はここで静かに破棄されていました）で後方アタッチされ、既に埋め込まれた reasoning があれば追記します。保留中の reasoning は境界で必ず消費されるため、ユーザーターンを越えて後のアシスタントメッセージへ漏れることはありません。（[#5508](https://github.com/farion1231/cc-switch/pull/5508)）
+
+### ストリーミング並列ツール呼び出しの ID と順序を保持
+
+Chat→Responses ストリーミングブリッジの 2 つのバグが、チャンクをまたいで識別子が分割される上流からの並列ツール呼び出しを壊していました。空の `id` を持つ継続デルタが本物の `call_id` を上書きし（Codex クライアントは `call_id:""` を見てツール結果を呼び出しに対応付けられません）、ツール呼び出しは個別に準備でき次第送出されていたため、名前が先に届いた後方インデックスが前方インデックスを追い越し、並列呼び出しの順序が入れ替わっていました。空の id は無視されるようになり、送出は連続インデックスゲートを通って Chat の `index` 順で厳密に解放され、まだ識別されていない前方インデックスを待ちます。ストリーム途中で偽の call id を合成することはありません（ストリーム終端の最終手段としてのみ。そこでも名前のない呼び出しは防御的にスキップし、疎なインデックスはそのまま送出します）。（[#5310](https://github.com/farion1231/cc-switch/pull/5310)）
+
+### 管理下 OAuth プロバイダーを確実に「ローカルルーティング必要」と表示
+
+「ルーティング必要」バッジと切り替え時の警告は、プロバイダーの API 形式から導出されていました。管理下 OAuth プロバイダー（Copilot、Codex OAuth、xAI）にとってこれは誤ったシグナルです——認証情報は上流形式に関係なくプロキシが注入するため、ネイティブ形式の管理下プロバイダーは警告を受けず、テイクオーバーなしで静かに失敗していました。ルーティングの要否は単一の共有述語で決まるようになりました。公式プロバイダーは決してルーティングを必要とせず、管理下 OAuth プロバイダーは常に必要とし、形式ベースのルールは残りのケースにのみ適用されます。切り替え時のゲートもアプリごとに正しい準備状態を確認します。ほとんどのアプリはアプリ別テイクオーバー状態（旧ゲートはグローバルなプロキシ実行フラグだけを見ており、「プロキシは動いているが当該アプリはテイクオーバーされていない」を見逃していました）、Claude Desktop は引き続きプロキシプロセス自体を監視します——バックエンドのテイクオーバー状態に Claude Desktop のフィールドがないため、一律のアプリ別ゲートでは Desktop が永遠に警告を出し続けます。Claude Desktop のプロバイダーフォームは、xAI だけでなくすべての管理下 OAuth 型でプロキシモードを強制し、モデルマッピングトグルをロックします。4 言語同期。
+
+### Node が nvm / fnm / mise にある場合でもツール更新が動く
+
+アンカー付き npm の更新・修復コマンドは npm を絶対パスで呼び出しますが、npm のランチャーは `#!/usr/bin/env node` shebang で PATH から `node` を解決します——GUI 起動のアプリはシステム PATH しか継承せず、バージョンマネージャーのディレクトリを含まないため、nvm / fnm / mise でインストールしたツールの更新は静かに失敗していました。すべてのアンカー付き npm 呼び出しは、npm 自身の隣にある `bin` ディレクトリを PATH の先頭に追加するようになり、npm とその shebang が同じ Node インストールを解決します。Codex の自己修復（アンインストール + 再インストール）経路もカバーしています。
+
+### 削除した既定 Skill リポジトリが復活しない
+
+既定の Skill リポジトリは、起動のたびに「欠けている既定を補充」する処理で再シードされ、削除した既定リポジトリが次回起動時に静かに戻っていました。シードはデータベースごとに 1 回だけになり、設定フラグで記録されます。アップグレード時に既にリポジトリを持つデータベースは再シードなしでフラグが立つため、既存の選択には触れません。（[#5356](https://github.com/farion1231/cc-switch/pull/5356)）
+
+### トレイの初回言語がシステムロケールに従う
+
+設定でまだ言語を選んでいない場合、トレイメニューは簡体字中国語に固定されていました——英語 / 日本語 / 繁体字中国語のシステムでは、メイン UI は正しく OS ロケールに従うのにトレイだけが食い違い、ユーザーが一度言語を切り替えるまで続いていました。トレイはフロントエンドと同じ優先順位で OS ロケールから初回言語を導出するようになりました（`zh-TW` / `zh-HK` / `zh-Hant` → 繁体字中国語を含む）。明示的に選んだ言語が常に優先され、ロケールを読めない場合は従来どおり中国語へフォールバックします。（[#4355](https://github.com/farion1231/cc-switch/pull/4355)）
+
+### インポート失敗時に実際のエラーを表示しリストを更新
+
+「live 設定からインポート」が失敗するたびに空のエラートーストが出ていました。Tauri の `invoke` はバックエンドのエラー**文字列**で reject するのに、ハンドラーがその上の `.message` を読んでいたためです。バックエンドの実際のメッセージを表示するようになり（ローカライズされた汎用フォールバック付き）、失敗時にもプロバイダーリストを更新するため、エラー前にコミットされた副作用がすぐ見えます。
+
+### OpenClaw プリセットのモデルコストを公式表示価格に修正
+
+OpenClaw プリセットの 15 エントリが、誤った単位や未換算の通貨でコスト値を持っていました——`cost` フィールドは 100 万 token あたりの USD ですが、たとえば `glm-5.1` は `0.001/0.001`（約 1000 分の 1 に過小評価され、使用量のコストがほぼ 0 と表示）、`deepseek-v4-pro` は未換算の人民元値（過大評価）でした。全エントリを $/M の公式表示価格に修正。サブスクリプションプランや無料 tier の endpoint も意図的に表示価格を示し、プランユーザーが自分の使用量の標準価値を見られるようにしています。今後プリセットから作成するプロバイダーには修正値が入り、作成済みのプロバイダーは作成時の設定を保持します。
+
+### UI の小さな修正
+
+- **AiHubMix アイコン**：Codex アプリの AiHubMix プリセットだけがブランドアイコンのフィールドを欠き、汎用アイコンで表示されていました。他のアプリと揃いました。
+- **欠落していた 2 つのロケールキーを補完**：Codex の「Anthropic Messages 形式のためルーティングが必要」トーストの理由部分が、ローカライズ済みの文の中で中国語のまま表示されていました（`proxyReasonAnthropicMessages` がどの言語ファイルにも存在しなかったため）。プロバイダーフォームの key 状態読み込みラベルも 4 月からハードコードの既定値のみでした。両方とも zh / en / ja / zh-TW に揃いました。
+
+---
+
+## ドキュメント
+
+### Codex ↔ Claude 双方向ルーティングガイド
+
+「Codex クライアントで Claude モデルを使う」「Claude Code クライアントで Responses プロバイダーを使う」の両方向が、2 つの新ガイドで揃いました：
+
+- **[Codex で Claude モデルを使う](../guides/codex-claude-routing-guide-ja.md)**（中 / 英 / 日 3 言語、スクリーンショット付き）：v3.17.0 のネイティブ Anthropic Messages 上流と組み合わせ、Claude 系の `/v1/messages` ゲートウェイへ Codex を接続します。v3.17.0 のリリースノートからもリンクされています。
+- **[Claude Code で GPT モデルを使う](../guides/claude-codex-routing-guide-ja.md)**（中 / 英 / 日 3 言語、スクリーンショット付き）：Responses を話すプロバイダー（ゲートウェイの API key、または ChatGPT サブスクリプションの Codex サービス）で Claude Code を動かします——Claude Code は常にローカルの `/v1/messages` ルートへ Anthropic Messages を話し、プロキシが各リクエストを上流の Responses プロトコルへ変換します。
+
+### README のスポンサー欄を更新
+
+SubRouter が 4 言語 README のスポンサー表に加わりました。ピン留めの Kimi スポンサー文言は K3 に更新され、バナーは Moonshot CDN から配信されます。RunAPI の特典文言も更新し、スポンサー行の順序をアプリ内プリセット順に揃えました。
+
+---
+
+## アップグレード時の注意
+
+### データベース自動移行と Codex 使用量の一回限りの再構築
+
+v3.17.0 からのアップグレードでは、3 つの schema 移行（v13 → v16）が連続実行されます。v14 は Grok Build を受け入れるために `proxy_config` テーブルを再構築（既存のアプリ別プロキシ設定はすべて引き継ぎ、`grokbuild` 行を追加）。v15 は MCP サーバーテーブルと Skills テーブルに Grok Build 有効化列を追加。v16 は一回限りの Codex 使用量自動再構築をトリガーします——データベースをまず `backups/` 配下へバックアップし、`codex_session` データとカーソルをリセットし、その後通常の起動時同期が修正済みパーサーですべてを再インポートします。一般的なデータ量なら数秒。実測で最も重いデータセット（rollout ファイル 1,801 個 / 1.5 GB）は約 65 秒でした。以後の起動は従来どおり増分です。旧バージョンへ戻す可能性がある場合は、先に `~/.cc-switch/cc-switch.db` を自分でバックアップしてください。
+
+**初回起動時の注意**：履歴の修復は**段階的に**完了します——再構築は起動時同期と共にバックグラウンドで進み、その間、使用量ダッシュボードの Codex 履歴の数字はいったんゼロになり、その後少しずつ埋め戻されます。これは想定どおりの動作で、データ損失ではありません。再構築後の合計は通常、アップグレード前より**小さく**なります。二重計上で膨らんでいた分が絞り出され、残ったものが実際の使用量です。
+
+### 再構築の境界
+
+- 再構築は rollout JSONL ファイルから使用量を再計算するため、**ソースログが既に削除された履歴は復元できません**。
+- 親 rollout が欠けている fork ファイルは、推測でインポートせず保留として報告されます。親ログを復元してから「Codex 使用量を再構築」を実行すると取り込めます。
+- 過去のプロキシソースの重複行は恒久的に残ります——移行が再構築するのはセッションソースのデータだけで、過去のプロキシ膨張を掃除する処理は存在しません。冪等ロガーが保証するのは、今後新しい重複が生まれないことだけです。
+
+### 古いログファイルは遡って洗浄されません
+
+本リリースから診断ログは起動時に消去されず、再起動をまたいで保持されます（ローテーション済みランタイムログ最大約 100 MB、クラッシュログ約 15 MB）。**旧バージョンが書き込んだログファイルは遡って洗浄されず**、API key、トークン、認証情報付き URL を含む可能性があります——公開の場で共有する前に、アップグレード前のログを確認してください。
+
+### Grok Build のインストールは公式インストーラースクリプトを使用
+
+Grok Build のインストール・再インストールは xAI 公式インストーラーを優先し、インストール時に `x.ai/cli/install.sh`（Windows では `install.ps1`）を外部取得します。npm はフォールバックです。既存の npm インストールは引き続き npm 経由で更新されます。
+
+### 内蔵価格の行を自動追加
+
+新しい価格行（`grok-4.5`、`kimi-k3`、`k3`）は次回起動時に「存在しなければ挿入」で自動追加されます。ユーザーが編集した価格行が上書きされることはありません。
+
+---
+
+## リスク通知
+
+### xAI Grok OAuth サインイン（本リリース新規——必ずお読みください）
+
+本リリースの xAI Grok OAuth 連携は、**公式 Grok CLI 用に登録された公開 OAuth クライアント識別情報とスコープを再利用します**（`client_id b1a00492-073a-47ea-816f-4c329264a828`、scope に `grok-cli:access` を含む）。CC Switch 自身が登録したアプリケーション識別情報ではありません。xAI がこの利用方法を認めない可能性があり、**アカウントの制限や停止につながる恐れがあります——自己責任でご利用ください**。この機能は完全にオプトインです。xAI プロバイダーを追加しなければ、何も変わりません。初回ログイン時に `~/.cc-switch/xai_oauth_auth.json` を作成し（refresh token のみ保存、Unix ではパーミッション `0600`、access token はメモリのみ）、設定済みのアウトバウンドプロキシ経由で `auth.x.ai` と `api.x.ai` へ接続します。ローカルのコールバックポートはありません。
+
+### 引き続き適用されるリバースプロキシ系の注意
+
+**Codex OAuth リバースプロキシ**：ChatGPT サブスクリプションの Codex OAuth をリバースプロキシ経由で使用すると、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 release notes](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。
+
+**サードパーティプロバイダーのルーティング**：CC Switch ローカルプロキシで Codex、Claude Desktop、Grok Build のリクエストを変換してサードパーティプロバイダーへ転送する場合、課金・コンプライアンス・データ保持に関する制約はプロバイダーごとに異なります。利用前に対象プロバイダーの利用規約を確認してください。
+
+上記機能を有効化したユーザーは、関連するリスクを自ら負うものとします。CC Switch は、これらの機能の利用によって発生したアカウント制限、警告、サービス停止について責任を負いません。
+
+---
+
+## 謝辞
+
+v3.18.0 で機能と修正を届けてくださった以下のコントリビューターに感謝します：
+
+- [#5453](https://github.com/farion1231/cc-switch/pull/5453)：Grok Build の第一級サポート（8 番目の管理対象アプリの中核実装）、@YUZHEthefool に感謝。
+- [#5508](https://github.com/farion1231/cc-switch/pull/5508)：Responses→Chat ブリッジの reasoning 前方アタッチ、@ka79376046 に感謝。
+- [#5310](https://github.com/farion1231/cc-switch/pull/5310)：ストリーミング並列ツール呼び出しの ID と順序の保持、@SaladDay に感謝。
+- [#5315](https://github.com/farion1231/cc-switch/pull/5315)：Codex ツール parameters の object schema への正規化、@Komikawayi に感謝。
+- [#4706](https://github.com/farion1231/cc-switch/pull/4706)：厳格な OpenAI 互換プロバイダー向けのツール型正規化、@Ryan2128 に感謝。
+- [#5356](https://github.com/farion1231/cc-switch/pull/5356)：削除した既定 Skill リポジトリの復活防止、@allenxu09 に感謝。
+- [#4355](https://github.com/farion1231/cc-switch/pull/4355)：トレイ初回言語のシステムロケール追従、@LaiYueTing に感謝。
+- [#5138](https://github.com/farion1231/cc-switch/pull/5138)：バックエンド CI の Linux / Windows / macOS 3 プラットフォーム展開、@zayokami に感謝。
+
+Codex 使用量の異常、新しい codex の起動失敗、ツール呼び出しの問題を報告してくださったすべてのユーザーにも感謝します。本リリースの最も重要な修正は、こうした実際の利用場面からの再現情報をもとにしています。
+
+---
+
+## ダウンロードとインストール
+
+[Releases](https://github.com/farion1231/cc-switch/releases/latest) から、お使いのシステムに対応するビルドをダウンロードしてください。
+
+### システム要件
+
+| システム | 最低バージョン           | アーキテクチャ                      |
+| -------- | ------------------------ | ----------------------------------- |
+| Windows  | Windows 10 以降          | x64 / ARM64                         |
+| macOS    | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) |
+| Linux    | 下表を参照               | x64 / ARM64                         |
+
+### Windows
+
+| ファイル                                 | 説明                                         |
+| ---------------------------------------- | -------------------------------------------- |
+| `CC-Switch-v3.18.0-Windows.msi`          | **推奨** - 自動更新対応の MSI インストーラー |
+| `CC-Switch-v3.18.0-Windows-Portable.zip` | ポータブル版、展開してそのまま実行できます   |
+
+Windows ARM64 デバイスでは、ファイル名に `arm64` が含まれる対応する成果物を選択してください。
+
+### macOS
+
+| ファイル                         | 説明                                                   |
+| -------------------------------- | ------------------------------------------------------ |
+| `CC-Switch-v3.18.0-macOS.dmg`    | **推奨** - DMG インストーラー、Applications へドラッグ |
+| `CC-Switch-v3.18.0-macOS.zip`    | 展開して Applications へドラッグ、Universal Binary     |
+| `CC-Switch-v3.18.0-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.18.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.18.0-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| ディストリビューション                  | 推奨形式    | インストール方法                                                           |
+| --------------------------------------- | ----------- | -------------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` または `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` または `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                    |
+| Arch Linux / Manjaro                    | `.AppImage` | 実行権限を付与して直接実行、または AUR を利用                              |
+| その他 / 不明な場合                     | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`                  |
@@ -0,0 +1,331 @@
+# CC Switch v3.18.0
+
+> 这一版你可以做两件全新的事：**把 xAI 的 Grok CLI（Grok Build）交给 CC Switch 管理**——它成为第八个受管应用，供应商一键切换、MCP / Skills 同步、代理接管与用量统计一应俱全；以及**把 Grok 接进 Claude Code、Claude Desktop 和 Codex**——既可以直接用 xAI Grok 账号登录（设备码授权、无需 API Key，跑你的 Grok 订阅，Codex 侧自带严格网关兼容层，codex 0.142+ 也能跑通），也可以用 xAI API Key 接入（Codex 有原生 Responses 直连预设，Claude Code 可走本地路由）。同样重要的是一波修复：v3.17.0 引入的 **Codex 用量双计已修**，升级后自动重建数据，看板数字恢复真实；**codex 0.144.5+ 因模型目录无法启动的问题已修**；Windows 上切换供应商不再闪黑窗、不再卡住界面。诊断日志也从「每次启动清空」变为跨重启持久保留、按大小轮转、全面脱敏，界面崩溃会落盘留证而不再只剩一片白屏。
+
+**[English →](v3.18.0-en.md) | [日本語版 →](v3.18.0-ja.md)**
+
+---
+
+## 重点内容：你现在可以
+
+- **管理 Grok Build（xAI 的 Grok CLI）**：像管理 Claude Code / Codex 一样添加、导入、一键切换 Grok Build 的供应商；MCP 服务器与 Skills 双向同步、提示词首启自动导入、会话管理与用量看板全覆盖；还可以走本地代理接管，获得独立的路由、failover 与计费。
+- **把 Grok 接进 Claude Code / Claude Desktop / Codex——账号登录与 API Key 双路径**：订阅用户在「设置 → OAuth 授权中心」用设备码完成 xAI 账号登录（支持多账号），三个客户端直接跑你的 Grok 订阅、全程无需 API Key；按量付费用户则用 xAI API Key 接入——Codex 有现成的「xAI (Grok)」预设原生直连 `api.x.ai`，Claude Code 可按本版新攻略走本地路由接入。默认模型均为 `grok-4.5`。
+- **把 Codex 的用量数字修回真实值**：v3.17.0 的 fork / 子代理双计问题已在解析器层根治；升级后首次启动自动备份并重建 Codex 用量，用量页里也新增了手动「重建 Codex 用量」按钮。注意首次启动时历史记录是**逐渐**修复的——看板数字先变少、再随后台重导逐步回填，属预期行为（见「升级提醒」）。
+- **放心升级 codex CLI**：codex 0.144.5 起严格解析模型目录导致的「无法启动」已修复，生成目录会自动补齐解析器必需字段。
+- **在 Windows 上顺滑切换**：切换供应商 / 开关接管不再闪过黑色控制台窗口，也不再卡住界面约 2 秒（卡顿修复对全平台生效）。
+- **更放心地排查与分享日志**：诊断日志跨重启保留（20 MB × 4 轮转）、所有出口统一脱敏——URL 凭据、请求响应体、敏感请求头都不会再落盘；界面崩溃有错误卡片和重载按钮，错误详情写入磁盘。
+- **多轮重推理、并行工具调用不再翻车**：Responses↔Chat 桥修复了推理内容错挂、并行工具调用 ID 丢失 / 乱序、工具 schema 为 null 被严格上游整单拒绝三类问题。
+- **用上 Kimi K3**：Codex / Hermes / OpenClaw / OpenCode 的 Kimi 开放平台预设加入 K3（1M 上下文），内置定价同步入库，用量不再显示 $0。
+
+---
+
+## 使用攻略
+
+本版新能力主要落在供应商预设、「设置 → OAuth 授权中心」与用量看板里，建议结合以下文档了解：
+
+- **[xAI Grok 账号登录（设置 → OAuth 授权中心）](../user-manual/zh/1-getting-started/1.5-settings.md)**：设备码登录流程、多账号管理与集成边界说明；使用前请先阅读下方「风险提示」中的客户端身份披露。
+- **[在 Claude Code 中使用 GPT 模型（本地路由攻略）](../guides/claude-codex-routing-guide-zh.md)**：本版新增的分步攻略，现已中 / 英 / 日三语齐全。Claude Code 始终对本地 `/v1/messages` 路由说 Anthropic Messages 协议，由本地代理把每个请求转换成上游的 Responses 协议——网关 API Key、xAI 这类原生 Responses 端点，或 ChatGPT 订阅的 Codex 服务都适用。
+- **[在 Codex 中使用 Claude 模型（本地路由攻略）](../guides/codex-claude-routing-guide-zh.md)**：本版新增的三语分步攻略，配合 v3.17.0 的「原生 Anthropic Messages 上游」功能，把 Codex 接到任何只提供 `/v1/messages` 的 Claude 系网关。
+- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：了解用量看板的数据来源与统计口径。本版修复用量双计并新增「重建 Codex 用量」维护操作。
+
+---
+
+> [!WARNING]
+>
+> ## 唯一官方渠道声明（请务必阅读）
+>
+> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。请仅通过下列官方渠道获取本软件：
+>
+> | 类别     | 唯一官方                                                                       |
+> | -------- | ------------------------------------------------------------------------------ |
+> | 官网     | **[ccswitch.io](https://ccswitch.io)**                                         |
+> | 源码     | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** |
+> | 下载     | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)**        |
+> | 作者     | **[@farion1231](https://github.com/farion1231)**                               |
+> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)**            |
+>
+> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。
+
+---
+
+## 概览
+
+CC Switch v3.18.0 的两条主线都围绕 xAI Grok。第一条是 **Grok Build 加入受管应用**：xAI 的 Grok CLI（live 配置 `~/.grok/config.toml`）成为与 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes 并列的第八个受管应用——供应商添加 / 导入 / 一键切换、MCP 与 Skills 双向同步、深链导入、独立预设列表，以及带专属路由命名空间的代理接管；配套的「Grok 官方」条目支持官方登录态识别与导入，CC Switch 绝不触碰官方凭据。第二条是 **xAI Grok 账号 OAuth 登录**：设备码授权替代 API Key，本地代理逐请求注入访问令牌，Claude Code / Claude Desktop 侧完成 Anthropic Messages → xAI Responses 转换；Codex 侧则提供受管 OAuth 预设并自带兼容层——codex 0.142+ 发出的 ChatGPT 后端私有形态（namespace 工具声明、私有字段）会被确定性地展平与剥离，严格解析的 xAI 网关不再返回 422；API Key 用户则另有一条「xAI (Grok)」原生 Responses 直连预设，不经任何转换。
+
+围绕正确性，本版集中修复了 **v3.17.0 的 Codex 用量双计**：fork / 子代理日志开头对父线程历史的重放不再被当作新用量导入（解析器改为只认显式父身份 + 令牌签名对齐），升级后自动执行一次性用量重建（schema v16），用量页新增手动重建按钮；代理侧用量记录改为幂等（同一响应重放不再堆叠重复行），大量会话导入时用量页不再卡死。**Codex 转换层**另有四处修复：工具 schema 归一为 object 类型、推理内容跨轮前向附挂、流式并行工具调用保 ID 保序、生成的模型目录补齐 codex 0.144.5+ 必需字段。诊断体系也走向成熟：日志跨重启持久、按大小轮转、所有出口脱敏，界面崩溃被错误边界捕获并落盘。此外还有 Kimi K3 预设与定价、OpenClaw 预设成本修正、SudoCode.us 回归、托盘首启语言跟随系统等一批改进。
+
+**发布日期**：2026-07-21
+
+**更新规模**：52 commits | 217 files changed | +21,452 / -6,285 lines
+
+---
+
+## 新功能
+
+### Grok Build：第八个受管应用
+
+xAI 的 Grok CLI（Grok Build，live 配置 `~/.grok/config.toml`）现在是 CC Switch 的一等公民：供应商添加 / 导入 / 一键切换（切换后提示重启 Grok Build 生效）、应用显隐与配置目录覆盖设置、会话管理与用量看板覆盖、提示词首启自动导入、`ccswitch://` 深链导入供应商，以及本地代理接管——拥有专属的 `/grokbuild/v1/responses` 路由命名空间、独立的 failover 队列与按应用代理设置；转发复用 Codex 的 Responses 通路，但绝不与 Codex 共享供应商命名空间或熔断状态。
+
+MCP 服务器与 Grok 的 `[mcp_servers]` 表双向同步，方言差异已被抹平：Grok 靠 `command` / `url` 推断传输类型且用 `headers` 字段，导出时会剥掉显式 `type` 并把 `http_headers` 重命名为 `headers`，导入时反向推断回来。Skills 也获得 Grok Build 启用开关。
+
+预设方面刻意**没有**借用 Codex 列表（早期版本曾把国产直连供应商和 Codex 默认模型漏进 Grok 表单），而是独立整理了一份：只收录真正承载 Grok 模型的聚合与中转站，默认模型归一为 `grok-4.5`（命名空间路由站为 `x-ai/grok-4.5`）。工具面板安装 Grok 优先走 xAI 官方安装器（`x.ai/cli/install.sh` / `install.ps1`），npm 包 `@xai-official/grok` 作为兜底；被确认是原生安装的走 `grok update` 自更新，npm 安装保持 npm 锚定更新——自更新门控在「确定检测为原生」上，绝不会误伤另一种安装。四语界面文案同步就位。（[#5453](https://github.com/farion1231/cc-switch/pull/5453)）
+
+### Grok 官方登录：识别、导入与保护
+
+新增「Grok 官方」供应商条目，对应 Grok CLI 自带的 xAI OAuth 登录：选中它会隐藏连接字段并写入一个空的 `~/.grok/config.toml`，CC Switch 从不存储、也从不触碰官方凭据。live 配置的读取、备份与官方态写入改用仅语法级的 TOML 校验，官方登录态（空配置）可以正常往返；Grok 处于官方登录态时「从 live 导入」会得到「已设 Grok 官方为当前」而不是报错，与 Codex 行为一致。官方态识别刻意只接线到手动导入命令——启动时的自动导入器仍会拒绝官方态配置，所以你删掉的「Grok 官方」条目绝不会在下次启动时复活。对官方登录配置的代理接管会被自动跳过，手动路径给出明确拒绝，与现有「不代理官方供应商」的策略一致。
+
+### 用 xAI Grok 账号登录：Claude Code 与 Claude Desktop
+
+Claude Code 与 Claude Desktop 新增「xAI (Grok)」预设，用 OAuth 设备码登录代替 API Key：请求经本地代理完成 Anthropic Messages → xAI Responses API 转换并逐请求注入访问令牌，各档默认模型都是 `grok-4.5`（Claude Desktop 预设把 `claude-*` 形式的角色 ID 映射到上游 `grok-4.5`，以通过 Desktop 的第三方模型校验）。
+
+「设置 → OAuth 授权中心」新增 xAI 区块：设备码登录（用户码带复制按钮、验证链接、等待 / 取消 / 重试）、多账号与默认账号选择、按账号移除、重授权徽标——刷新令牌被吊销的账号会以「已过期」状态保留可见而不是消失，授权状态每 15 秒自动刷新，服务端吊销会自己浮现出来。
+
+集成边界是钉死的：无论表单里的端点 / 格式字段怎么改，上游始终是 `https://api.x.ai/v1/responses`（Responses 格式）；OAuth 端点经 OIDC 发现解析，但强制校验为 https 的 `auth.x.ai`；刷新令牌存于 `~/.cc-switch/xai_oauth_auth.json`（Unix 上 `0600`；访问令牌只存内存）；OAuth 错误响应体绝不进入错误信息或日志。`grok-4.5` 定价（$2 输入 / $6 输出 / $0.50 缓存读，每百万 token）同步入库，用量不再记 $0，存量数据库下次启动自动补行。四语文案同步。使用前请阅读「风险提示」中的客户端身份披露。
+
+不用 OAuth、只有按量付费的 xAI API Key？同样能接进 Claude Code：xAI 的 API 端点就是标准 Responses 协议，把它当作一个普通的 Responses 供应商添加——自定义供应商填 `https://api.x.ai/v1` 与 API Key、上游格式选 Responses，经本地路由完成 Anthropic Messages ↔ Responses 转换，与〈[在 Claude Code 中使用 GPT 模型](../guides/claude-codex-routing-guide-zh.md)〉攻略是同一套玩法。Codex 侧则有现成的 API Key 预设，见下一节。
+
+### Codex 直连 xAI：OAuth 受管与 API Key 原生双预设
+
+Codex 获得两条直连 xAI 的路——有 Grok 订阅走 OAuth 受管，有 API Key 走原生直连：
+
+- **「xAI (Grok) OAuth」受管预设**：让 Codex 跑在 Grok 订阅上。表单隐藏密钥 / 端点 / 格式字段、显示账号选择器，「获取模型」用已登录账号发起；供应商被钉死为原生 Responses，base URL 与逐请求令牌由代理强制执行——改了也会被忽略，受管路由无法被重定向。由于 codex 0.142+ 会发出 ChatGPT 后端私有的请求形态（`type:"namespace"` 工具声明会让 xAI 严格解析器直接 422，另有 `prompt_cache_retention`、`safety_identifier`、`external_web_access`、`additional_tools` 载体字段和 grok-4.5 不支持的采样参数），OAuth 路由在原生透传上加了一层兼容层：namespace 工具被展平为顶层 function 工具（与 Chat 路径同款 sha256 截断命名）、响应侧流式与非流式都还原回 namespace 形态，不支持的字段被剥除——全部是确定性的字段删除 / 结构提升，绝无语义改写，prompt 缓存前缀保持稳定。兼容层只门控在 xAI OAuth 供应商类型上，任何其它供应商的流量都不受影响。
+- **「xAI (Grok)」API Key 预设**：直连 `api.x.ai/v1` 的原生 Responses，自带 500K 上下文的 `grok-4.5` 目录条目。该预设**不会**应用上述 xAI 专属兼容转换——codex 0.142+ 的 API Key 用户仍可能撞上 xAI 的严格解析器，OAuth 预设才是完全兼容的路径。
+
+xAI OAuth 的令牌失败被归为不可重试错误，failover 绝不会把你的对话悄悄挪到另一个 Grok 账号上。
+
+### 界面崩溃捕获：错误落盘与重载页
+
+React 错误边界现在包住整个界面（包括数据库恢复界面）：渲染进程崩溃时显示「界面出错了」卡片和重载按钮，而不是一片白屏；全局 `error` / `unhandledrejection` 处理器把渲染端错误持久化到磁盘——此前一次 JS 崩溃在盘上零证据。前端写出的所有日志经过两层脱敏：结构化序列化器按敏感属性名（`tokens` / `apiKeys` / `credentials` 等变体归一匹配，整值含嵌套对象一起隐藏）与值形态（令牌前缀、PEM 头、高熵不透明串）脱敏，再经唯一文本出口的有序正则链覆盖 URL 查询值与凭据、认证头与 scheme、命名密钥容器（双重编码的 JSON 也覆盖）。字符串形态到达的 JSON 会被重新解析后做结构化脱敏；超大结构化输入整体丢弃而非截断——截断的 JSON 串会退化到较弱的文本正则，可能泄漏。设置里的开关文案也改为名副其实：「应用诊断日志」（cc-switch.log）与代理的「记录请求用量」（统计数据库，本来就不是文本日志）。四语同步。
+
+### 「重建 Codex 用量」维护按钮
+
+用量看板的维护区新增「重建 Codex 用量」：备份数据库后，只清除 `codex_session` 来源的明细行、对应的 `_codex_session` 日汇总与 Codex 同步游标，然后用修正后的解析器从头重导所有 rollout 文件——这是被下述双计 bug 污染的数据库的恢复路径，也是父日志恢复后延迟 fork 文件的重试路径。手动重建在备份写不出时会硬失败（自动迁移版只告警，因为在升级后因备份目录不可写而卡死启动是更糟的结局）；整个「备份 → 重置 → 重导」序列持有会话同步锁，60 秒后台同步无法与清除交错；完成时保证恰好发出一次前端刷新通知——包括重导为零行或失败的路径——看板绝不会停留在重置前的数字上。游标清理按路径形态匹配（`sessions` / `archived_sessions` 段下的 `rollout-{uuid}` 文件名），旧 `CODEX_HOME` 下记录的游标也能清到。四语同步。
+
+### 会话导入可观测性：延迟文件与疑似重复
+
+会话同步结果现在报告 `filesScanned`、`deferredFiles`——父日志缺失或父标记冲突的 fork rollout 会被搁置且不写游标，等后续同步或手动重建重试，而不是靠猜导入——以及 `suspectedDuplicates`：插入后逐行探测是否已存在同指纹行（走 `idx_request_logs_dedup_lookup_expr` 表达式索引），每次命中记一条警告。双计 bug 未来若复发，会在日志里自己喊出来，而不是无声地吹大总数。
+
+### Kimi K3 预设与定价
+
+Codex / Hermes / OpenClaw / OpenCode 的 Kimi 开放平台预设加入 Kimi K3（1M 上下文窗口），追加在 K2.7 Code 之后，现有默认模型行为不变。内置定价表新增 `kimi-k3`（官方牌价 $3 输入 / $15 输出 / $0.30 缓存读，每百万 token）与裸 `k3` 别名——Kimi For Coding 订阅上报的模型短 id 是 `k3`，否则匹配不到任何定价行（与现有 `hunyuan-hy3` / `hy3` 同款先例）。存量数据库下次启动自动补齐两行，不碰用户改过的定价。
+
+### SudoCode.us 回归，与 SudoCode.chat 并存
+
+两家恰好同名「SudoCode」的无关公司现在是两个独立预设：赞助商更名为「SudoCode.chat」，此前被原位替换掉的「SudoCode.us」带着原有端点、模型与图标回归，Hermes slug 也做了区分，两者可在累加式的 `~/.hermes/config.yaml` 中共存。算上新的 Grok Build 预设列表，SudoCode.chat 覆盖七个应用、SudoCode.us 覆盖全部八个。
+
+---
+
+## 变更
+
+### 诊断日志：跨重启持久、按大小轮转、绝不记录密钥
+
+`cc-switch.log` 不再在每次启动时被清空——过去能解释崩溃的日志，等应用重开时已经没了——改为 20 MB 轮转、保留 4 个归档（上限约 100 MB，对比过去单文件可膨胀到 1 GB）；此前无上限的 `crash.log` 改为 5 MB 轮转、保留 2 个归档，检查 / 轮转 / 追加序列在同一把锁下，并发 panic 不会丢归档。
+
+日志持久化让明文密钥成为真实的暴露面（用户会把日志附到公开 issue 里），所以同一批改动里把后端所有日志出口都做了清洗：上游 URL 只记剥掉 userinfo / query / fragment 的形式（没有已知密钥可替换时只记 origin，因为凭据可能嵌在路径里）；请求与响应体一律不记——换成字节数、短哈希或安全分类（`sse` / `html` / `json-like` / `binary-or-encoded` 等），排查转换问题的信号还在、内容没了；响应头走白名单（名单外只记名字）；正在使用的密钥值（API Key、访问令牌）会从任何携带它的 URL 里被替换掉；MCP 自定义字段值一律省略。日志插件注册提前（更新器 / 启动期故障可诊断），持久化的日志级别在数据库打开后立即生效、故障时收敛到 Info，「启用诊断日志」开关现在也管前端发起的日志写入。**升级前的旧日志文件不会被追溯清洗**——见「升级提醒」。
+
+### 预设选择器：赞助商分组，其余按名称排序
+
+预设选择器的默认顺序改为四层：官方最前，其次首要合作伙伴，然后是赞助商预设（与 README 赞助商表同序，预设文件已物理重排对齐），最后所有其余预设按显示名字母序排列，不再按文件序。命中多层的条目只落在最早一层，不会重复出现。
+
+### 预设「获取 API Key」链接更新
+
+RunAPI、ClaudeCN、ZetaAPI、APINebula 预设的密钥申请链接更新为各家当前的注册 / 推荐页（ClaudeCN 同时迁移了域名：claudecn.top → claudecn.ai）。推荐标签仅限这些链接与 README——官网链接和 API 端点保持不动。
+
+---
+
+## 修复
+
+### Codex fork / 子代理不再把重放的父历史当新用量（v3.17.0 双计根治）
+
+修复 v3.17.0 的用量膨胀：fork 一个 Codex 任务或以复制模式派生子代理时，父对话的 token 历史被当作新用量重复计入——有用户报告单日用量跳涨数十亿 token、父子行字节级相同、空 fork 背着从未消耗过的用量。fork / 子代理的 rollout 文件开头会重放父线程历史，旧解析器靠启发式找接管边界（第一个 `thread_settings_applied` 事件、对象形态的 `subagent` 来源标记）：父线程自己的设置变更出现在重放里时边界落得太早，而当前字符串形态的来源标记则完全识别不到，整段父历史被原样导入。新解析器只认显式父身份——子方 `session_meta` 上的 `forked_from_id` 或 `source.subagent.thread_spawn.parent_thread_id`，两者冲突时搁置该文件——线程身份锚定到 rollout 文件名 UUID，加载父 rollout 自己的 fork 前 token 计数序列，用令牌签名对齐剥掉子方的重放前缀：重放事件只用于恢复累计基线，绝不插行。不带重放历史的子代理日志现在按真实用量计入，反方向的漏计（真实子代理消耗被当作疑似重放跳过）同步修复。（[#5335](https://github.com/farion1231/cc-switch/issues/5335)、[#5433](https://github.com/farion1231/cc-switch/issues/5433)、[#5381](https://github.com/farion1231/cc-switch/issues/5381)）
+
+### 代理用量记录改为幂等：响应级稳定键
+
+终态用量事件不带消息 id 时（经本地代理的 Codex `/responses` 流量是常态），去重键此前回退到随机 UUID——同一上游响应的每次重试 / 重放都造一个新键，`INSERT OR REPLACE` 每次都堆一行新的；有用户的数据库里同一用量组合出现了 2,078 次。解析器现在从响应信封本身取键——Codex `response.completed` 事件的 `response.id`（丢弃 `response.created` 的 id）、Chat Completions 的 `chatcmpl` id、Gemini 的 `responseId`——并按 `session:{app_type}:{provider_id}:{id}` 作用域化：failover 时同一响应打到不同供应商仍按供应商各记一次、互不碰撞（Claude 保持裸 `session:{id}` 形态，代理行继续与会话日志导入合流）。完全没有信封 id 时，兜底从响应的用量语义做确定性 SHA-256——相同重放必须撞进同一个键，去重才成立——最终写库也从无条件 REPLACE 改为去重窗口内的「不存在才插入」。（[#5496](https://github.com/farion1231/cc-switch/issues/5496)）
+
+### 大量会话导入时用量页不再卡死
+
+导入大批会话时打开用量页可能整个卡住：每插入一行就发一次刷新通知，每次通知让前端重跑全部约 10 个用量查询，这些查询又与正在逐行解析几十 MB rollout 文件的导入器争抢唯一数据库连接——在被重复行吹大的数据库上三者互相放大。现在会话同步改为每轮完成只通知一次；所有会话导入器串行在单飞锁后（手动「立即同步」排队等待运行中的一轮，而不是与之竞争）；阻塞式解析挪到专用阻塞线程，不再饿死驱动界面命令的异步运行时；60 秒后台节拍错过就跳过，不再突发补跑。
+
+### codex 0.144.5+ 不再因 CC Switch 生成的模型目录无法启动
+
+codex ≥ 0.144.5 严格解析外部模型目录，条目缺 `supports_reasoning_summaries` 时整个文件被拒——Codex CLI 和桌面端都起不来，删掉生成目录也没用，因为任何一次供应商保存都会按同样方式重新生成。根因是 CC Switch 从机器共享的 `models_cache.json` 克隆目录模板，而它的字段集取决于最后写它的那个 codex 进程——共存的旧版 codex 一直在用缺字段的形态重写缓存。生成目录现在会从内置静态模板回填解析器必需字段，且只在缺失时回填（动态值永远优先）；「缺失即解析器默认值」的可选能力字段刻意不回填，语义必须保留。
+
+### Windows：切换供应商不再闪黑窗、不再卡死
+
+Windows 上切换供应商或开关接管会闪过一个控制台窗口、界面卡住约 2 秒。三个原因、三处修复：`codex debug models --bundled` 探测经 `cmd.exe` 启动 `codex.cmd`，GUI 子系统应用里这会弹出自己的控制台——子进程现在带 `CREATE_NO_WINDOW` 创建；模型目录模板此前每次切换都重新生成——现在首次成功加载后进程级缓存（失败保持可重试，坏的首次探测不会毒化缓存），Codex CLI 每次应用运行至多启动一次；`switch_provider` 此前是跑在主线程上的同步命令——现在异步化、真实工作在阻塞线程上，仍由按应用切换锁串行。卡顿修复对全平台生效，闪窗修复是 Windows 专属。
+
+### 工具 schema 为 null / 缺失 / 联合类型不再被严格上游整单拒绝
+
+Codex 内置工具（如 `codex_app__automation_update`）声明 `parameters: null`（或 `type: null`），DeepSeek 这类严格的 OpenAI 兼容上游会对整个请求返回 400，经代理路由的工具会话直接被杀。Responses→Chat 桥现在把每个工具的 parameters 归一为 `type:"object"` schema：null 或缺失（含嵌套形态的缺失）变为 `{"type":"object","properties":{}}`，非 object 的 `type`（含 `type: null`）原位纠正为 `"object"`，顶层 `oneOf` 联合 schema 补根 `type:"object"`、分支原样保留。同样的 object 类型保证扩展到了 Codex→Anthropic 工具路径的 `input_schema`。已有的 `properties` / `required` 绝不丢弃。（[#4706](https://github.com/farion1231/cc-switch/pull/4706)、[#5315](https://github.com/farion1231/cc-switch/pull/5315)，修复 #4705、#4783）
+
+### 推理模型在多轮 Codex Chat 对话中保住思考
+
+推理模型（如 kimi-k2-thinking）走代理的 Responses→Chat 桥时，多轮历史会弄坏思考内容：每轮的 `reasoning` 条目被粘到**上一条**助手消息的尾巴上，紧随的助手轮反而没有 `reasoning_content`——模型会肉眼可见地中途断片。Responses 语义里推理位于它所属消息**之前**，桥现在把推理前向附挂到其后的助手消息或工具调用上；真正的尾部推理只在确凿的尾部（输入结束，或用户消息这样的轮次边界——此前在这里会被静默丢弃）向后附挂，并追加到已内嵌的推理之后；悬挂中的推理在边界处必被消费，绝不会跨过用户轮泄漏进后面的助手消息。（[#5508](https://github.com/farion1231/cc-switch/pull/5508)）
+
+### 流式并行工具调用保住 ID 与顺序
+
+Chat→Responses 流式桥的两个 bug 会弄坏「身份分散在多个 chunk」的上游发来的并行工具调用：携带空 `id` 的续传增量会覆盖真实 `call_id`（Codex 客户端看到 `call_id:""`，工具结果对不上调用）；工具调用各自就绪就立即发出，名字先到的靠后索引能插到靠前索引前面——并行调用被重排。现在空 id 一律忽略；发射经过连续索引闸门，严格按 Chat `index` 顺序放行，未识别的靠前索引没就绪就等待；流中途绝不合成假 call id（只在流终结时作为最后手段，且防御性跳过无名调用、稀疏索引照常发出）。（[#5310](https://github.com/farion1231/cc-switch/pull/5310)）
+
+### 受管 OAuth 供应商可靠地标记为「需本地路由」
+
+「需路由」徽标与切换时警告此前由供应商的 API 格式推导，对受管 OAuth 供应商（Copilot、Codex OAuth、xAI）这是错误信号——它们的凭据由代理注入、与上游格式无关，原生格式的受管供应商拿不到警告、不开接管就静默失败。路由需求现在由唯一共享谓词决定：官方供应商永不需要路由，受管 OAuth 供应商恒需要，格式规则只适用于其余情况。切换时的门槛也按应用查对了就绪信号：多数应用查按应用接管状态（旧门槛只看全局代理运行标志，漏掉「代理在跑但当前应用没被接管」），Claude Desktop 继续看代理进程本身——后端接管状态没有 Claude Desktop 字段，统一按应用查会让 Desktop 永远弹警告。Claude Desktop 供应商表单对所有受管 OAuth 类型强制代理模式并锁定模型映射开关，不再只对 xAI。四语同步。
+
+### Node 装在 nvm / fnm / mise 里时工具更新可用
+
+锚定的 npm 更新与修复命令按绝对路径调 npm，但 npm 启动器靠 `#!/usr/bin/env node` shebang 从 PATH 找 `node`——GUI 启动的应用只继承系统 PATH，不含版本管理器目录，nvm / fnm / mise 安装的工具更新静默失败。现在每个锚定 npm 调用都把 npm 自己的同级 `bin` 目录前置到 PATH，npm 与它的 shebang 解析到同一个 Node；Codex 自修复（卸载 + 重装）路径同样覆盖。
+
+### 删除的默认 Skill 仓库不再复活
+
+默认 Skill 仓库此前每次启动被「补齐缺失默认项」逻辑重新播种，删掉的默认仓库下次启动又静默回来。播种改为按数据库一次性，用设置标志记录；升级时已有仓库的数据库直接置标志、不再补种，现有选择不受影响。（[#5356](https://github.com/farion1231/cc-switch/pull/5356)）
+
+### 托盘首启语言跟随系统
+
+设置里还没选过语言时，托盘菜单被硬编码为简体中文——英文 / 日文 / 繁中系统上主界面正确跟随系统语言、托盘却不一致，直到用户手动切一次语言。托盘现在按与前端相同的优先级从系统 locale 推导首启语言（含 `zh-TW` / `zh-HK` / `zh-Hant` → 繁体中文）；显式选择的语言永远优先，locale 读不到时照旧回落中文。（[#4355](https://github.com/farion1231/cc-switch/pull/4355)）
+
+### 导入失败显示真实错误并刷新列表
+
+每次「从 live 配置导入」失败都弹一个空错误提示，因为 Tauri 的 `invoke` 以后端错误**字符串**拒绝，而处理器从它上面读 `.message`。现在显示后端真实报错（带本地化的通用兜底），失败时也会刷新供应商列表——报错前已提交的副作用立即可见。
+
+### OpenClaw 预设模型成本修正为官方牌价
+
+15 个 OpenClaw 预设条目的成本值单位错误或未换汇——`cost` 字段是美元每百万 token，例如 `glm-5.1` 记成 `0.001/0.001`（低估约 1000 倍，用量成本近乎 0），`deepseek-v4-pro` 则带着未换算的人民币值（高估）。所有条目改为官方牌价 $/M；订阅套餐与免费档端点也刻意展示牌价，套餐用户能看到自己用量的标准价值。今后从预设新建的供应商拿到修正值；已创建的供应商保持创建时的配置。
+
+### 界面小修一组
+
+- **AiHubMix 图标**：Codex 应用的 AiHubMix 预设此前缺品牌图标字段、渲染成通用图标，现与其它应用一致。
+- **两个缺失文案键补齐**：Codex「因使用 Anthropic Messages 格式需要路由」提示里的原因片段此前在非中文界面显示中文（`proxyReasonAnthropicMessages` 不存在于任何语言文件）；供应商表单的密钥状态加载标签自 4 月起只有硬编码默认值。两者已在 zh / en / ja / zh-TW 全部补齐。
+
+---
+
+## 文档
+
+### Codex ↔ Claude 双向路由攻略
+
+两篇新攻略把「Codex 客户端用 Claude 模型」「Claude Code 客户端用 Responses 供应商」补成了双向：
+
+- **[在 Codex 中使用 Claude 模型](../guides/codex-claude-routing-guide-zh.md)**（中 / 英 / 日三语，含截图）：配合 v3.17.0 的原生 Anthropic Messages 上游，把 Codex 接到 Claude 系 `/v1/messages` 网关；v3.17.0 的 release notes 已回链本攻略。
+- **[在 Claude Code 中使用 GPT 模型](../guides/claude-codex-routing-guide-zh.md)**（中 / 英 / 日三语，含截图）：用 Responses 协议的供应商（网关 API Key，或 ChatGPT 订阅的 Codex 服务）驱动 Claude Code——Claude Code 始终对本地 `/v1/messages` 路由说 Anthropic Messages，由代理把每个请求转换成上游的 Responses 协议。
+
+### README 赞助商更新
+
+SubRouter 加入四语 README 赞助商表；置顶的 Kimi 赞助文案更新到 K3、横幅改由 Moonshot CDN 提供；RunAPI 权益文案刷新，赞助商行序与应用内预设顺序对齐。
+
+---
+
+## 升级提醒
+
+### 数据库自动迁移与 Codex 用量一次性重建
+
+从 v3.17.0 升级会连续执行三次 schema 迁移（v13 → v16）：v14 重建 `proxy_config` 表以纳入 Grok Build（现有按应用代理设置全部保留，并新增 `grokbuild` 行）；v15 给 MCP 服务器表与 Skills 表加 Grok Build 启用列；v16 触发一次性的 Codex 用量自动重建——数据库先备份到 `backups/` 下，`codex_session` 数据与游标被重置，随后正常的启动同步用修正后的解析器重导全部数据。典型数据量只需数秒；实测最重的数据集（1,801 个 rollout 文件 / 1.5 GB）约 65 秒。之后的启动照旧增量。若有回退旧版本的习惯，建议先自行备份 `~/.cc-switch/cc-switch.db`。
+
+**首次启动时请留意**：历史记录的修复是**逐渐完成**的——重建随启动同步在后台进行，这段时间里用量看板的 Codex 历史数字会先清零、再逐步回填，属预期行为，不是数据丢失。重建完成后的总数通常会比升级前**更小**：被双计吹大的那部分被挤掉了，剩下的才是真实用量。
+
+### 重建的边界
+
+- 重建从 rollout JSONL 文件重新计算用量，**源日志已被删除的历史无法重建**。
+- 父 rollout 缺失的 fork 文件会被搁置并报告，而不是靠猜导入；恢复父日志后运行「重建 Codex 用量」可补导。
+- 历史上代理来源的重复行会永久保留——迁移只重建会话来源的数据，不存在针对过往代理膨胀的清理逻辑；幂等记录只保证从此不再产生新重复。
+
+### 旧日志文件不会被追溯脱敏
+
+诊断日志从本版起不再在启动时清空、跨重启持久保留（运行日志轮转上限约 100 MB，另有约 15 MB 崩溃日志）。**早期版本写下的日志文件不会被追溯清洗**，可能含有 API Key、令牌或带凭据的 URL——公开分享前请先检查升级前的旧日志。
+
+### Grok Build 安装走官方安装脚本
+
+安装或重装 Grok Build 现在优先使用 xAI 官方安装器，安装时会外联获取 `x.ai/cli/install.sh`（Windows 为 `install.ps1`），npm 作为兜底；已有的 npm 安装继续经 npm 更新。
+
+### 内置定价自动补行
+
+新定价行（`grok-4.5`、`kimi-k3`、`k3`）在下次启动时按「不存在才插入」自动追加；用户编辑过的定价行绝不被覆盖。
+
+---
+
+## 风险提示
+
+### xAI Grok OAuth 登录（本版新增，请阅读）
+
+本版的 xAI Grok OAuth 集成**复用官方 Grok CLI 注册的公开 OAuth 客户端身份与权限范围**（`client_id b1a00492-073a-47ea-816f-4c329264a828`，scope 含 `grok-cli:access`），而不是 CC Switch 自己注册的应用身份。xAI 可能不支持这种用法，**使用可能导致账号被限制或封禁——风险自担**。该功能完全可选：不添加 xAI 供应商，一切照旧。首次登录会创建 `~/.cc-switch/xai_oauth_auth.json`（仅存刷新令牌，Unix 上权限 `0600`；访问令牌只存内存），并经你配置的出站代理访问 `auth.x.ai` 与 `api.x.ai`，无本地回调端口。
+
+### 沿用的反向代理类提示
+
+**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
+
+**第三方供应商路由**：通过 CC Switch 本地代理把 Codex、Claude Desktop 或 Grok Build 的请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
+
+用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
+
+---
+
+## 致谢
+
+感谢以下贡献者在 v3.18.0 中提交的功能与修复：
+
+- [#5453](https://github.com/farion1231/cc-switch/pull/5453)：Grok Build 一等公民支持（第八个受管应用的主体实现），感谢 @YUZHEthefool。
+- [#5508](https://github.com/farion1231/cc-switch/pull/5508)：Responses→Chat 桥推理内容前向附挂，感谢 @ka79376046。
+- [#5310](https://github.com/farion1231/cc-switch/pull/5310)：流式并行工具调用保 ID 保序，感谢 @SaladDay。
+- [#5315](https://github.com/farion1231/cc-switch/pull/5315)：Codex 工具 parameters 归一为 object schema，感谢 @Komikawayi。
+- [#4706](https://github.com/farion1231/cc-switch/pull/4706)：严格 OpenAI 兼容上游的工具类型归一，感谢 @Ryan2128。
+- [#5356](https://github.com/farion1231/cc-switch/pull/5356)：删除的默认 Skill 仓库不再复活，感谢 @allenxu09。
+- [#4355](https://github.com/farion1231/cc-switch/pull/4355)：托盘首启语言跟随系统 locale，感谢 @LaiYueTing。
+- [#5138](https://github.com/farion1231/cc-switch/pull/5138)：后端 CI 扩展到 Linux / Windows / macOS 三平台，感谢 @zayokami。
+
+也感谢所有反馈 Codex 用量异常、codex 新版启动失败与工具调用问题的用户——本版最重要的几个修复都来自这些真实场景里的复现线索。
+
+---
+
+## 下载与安装
+
+访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。
+
+### 系统要求
+
+| 系统    | 最低版本                   | 架构                                |
+| ------- | -------------------------- | ----------------------------------- |
+| Windows | Windows 10 及以上          | x64 / ARM64                         |
+| macOS   | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
+| Linux   | 见下表                     | x64 / ARM64                         |
+
+### Windows
+
+| 文件                                     | 说明                                |
+| ---------------------------------------- | ----------------------------------- |
+| `CC-Switch-v3.18.0-Windows.msi`          | **推荐** - MSI 安装包，支持自动更新 |
+| `CC-Switch-v3.18.0-Windows-Portable.zip` | 便携版，解压即用，不写入注册表      |
+
+Windows ARM64 设备请选择文件名中带 `arm64` 标识的对应制品。
+
+### macOS
+
+| 文件                             | 说明                                          |
+| -------------------------------- | --------------------------------------------- |
+| `CC-Switch-v3.18.0-macOS.dmg`    | **推荐** - DMG 安装包，拖入 Applications 即可 |
+| `CC-Switch-v3.18.0-macOS.zip`    | 解压后拖入 Applications，Universal Binary     |
+| `CC-Switch-v3.18.0-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.18.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
+- `CC-Switch-v3.18.0-Linux-arm64.AppImage` / `.deb` / `.rpm`
+
+| 发行版                                  | 推荐格式    | 安装方式                                                               |
+| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
+| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` |
+| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm`  |
+| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                |
+| Arch Linux / Manjaro                    | `.AppImage` | 添加执行权限后直接运行，或使用 AUR                                     |
+| 其他发行版 / 不确定                     | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |
@@ -1,6 +1,6 @@
 # CC Switch User Manual / 用户手册 / ユーザーマニュアル

-> Claude Code / Codex / Gemini CLI / OpenCode / OpenClaw
+> Claude Code / Claude Desktop / Codex / Gemini CLI / OpenCode / OpenClaw / Hermes

 ## Language / 语言 / 言語

@@ -12,9 +12,9 @@

 ## Version / 版本 / バージョン

- Documentation version: v3.13.0
- Last updated: 2026-04-08
- Compatible with CC Switch v3.13.0+
+- Documentation version: v3.16.0
+- Last updated: 2026-05-29
+- Compatible with CC Switch v3.16.0+

 ## Links

--- a/Show More
+++ b/Show More