From 3d176b98cc0bfd151a42882e88ab59b62083b92f Mon Sep 17 00:00:00 2001 From: Jason Date: Mon, 13 Jul 2026 23:41:54 +0800 Subject: [PATCH] docs(release): add v3.17.0 release notes --- docs/release-notes/v3.17.0-en.md | 364 +++++++++++++++++++++++++++++++ docs/release-notes/v3.17.0-ja.md | 362 ++++++++++++++++++++++++++++++ docs/release-notes/v3.17.0-zh.md | 362 ++++++++++++++++++++++++++++++ 3 files changed, 1088 insertions(+) create mode 100644 docs/release-notes/v3.17.0-en.md create mode 100644 docs/release-notes/v3.17.0-ja.md create mode 100644 docs/release-notes/v3.17.0-zh.md diff --git a/docs/release-notes/v3.17.0-en.md b/docs/release-notes/v3.17.0-en.md new file mode 100644 index 000000000..7cfecb39a --- /dev/null +++ b/docs/release-notes/v3.17.0-en.md @@ -0,0 +1,364 @@ +# 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 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 ` to the current CLI's `opencode -s `. ([#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` | + + diff --git a/docs/release-notes/v3.17.0-ja.md b/docs/release-notes/v3.17.0-ja.md new file mode 100644 index 000000000..301e562ad --- /dev/null +++ b/docs/release-notes/v3.17.0-ja.md @@ -0,0 +1,362 @@ +# 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 で 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 ` を現在の `opencode -s ` へ修正しました。（[#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` | diff --git a/docs/release-notes/v3.17.0-zh.md b/docs/release-notes/v3.17.0-zh.md new file mode 100644 index 000000000..4fda9f5f9 --- /dev/null +++ b/docs/release-notes/v3.17.0-zh.md @@ -0,0 +1,362 @@ +# 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 里使用 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 ` 更正为当前 CLI 的 `opencode -s `。（[#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` |