From 606e7bbe75db7f8285f7a3be006fac22b5d22796 Mon Sep 17 00:00:00 2001 From: Jason Date: Tue, 21 Jul 2026 23:14:45 +0800 Subject: [PATCH] docs(release): add v3.18.0 release notes --- docs/release-notes/v3.18.0-en.md | 331 +++++++++++++++++++++++++++++++ docs/release-notes/v3.18.0-ja.md | 331 +++++++++++++++++++++++++++++++ docs/release-notes/v3.18.0-zh.md | 331 +++++++++++++++++++++++++++++++ 3 files changed, 993 insertions(+) create mode 100644 docs/release-notes/v3.18.0-en.md create mode 100644 docs/release-notes/v3.18.0-ja.md create mode 100644 docs/release-notes/v3.18.0-zh.md diff --git a/docs/release-notes/v3.18.0-en.md b/docs/release-notes/v3.18.0-en.md new file mode 100644 index 000000000..95b90dc82 --- /dev/null +++ b/docs/release-notes/v3.18.0-en.md @@ -0,0 +1,331 @@ +# CC Switch v3.18.0 + +> This release lets you do two brand-new things: **hand xAI's Grok CLI (Grok Build) over to CC Switch** — it becomes the eighth managed app, with one-click provider switching, MCP / Skills sync, proxy takeover, and usage statistics all included; and **connect Grok to Claude Code, Claude Desktop, and Codex** — either by signing in with your xAI Grok account directly (device-code authorization, no API key, running on your Grok subscription, with a strict-gateway compatibility layer on the Codex side so codex 0.142+ works too), or with an xAI API key (Codex gets a native Responses direct-connection preset; Claude Code can go through local routing). Just as important is a wave of fixes: the **Codex usage double count introduced in v3.17.0 is fixed**, with an automatic data rebuild after upgrading so the dashboard numbers become real again; **codex 0.144.5+ failing to start because of the model catalog is fixed**; and switching providers on Windows no longer flashes a console window or freezes the UI. Diagnostic logs also move from "wiped on every startup" to persistent across restarts, size-rotated, and fully redacted — and a UI crash now leaves an on-disk report instead of just a blank white window. + +**[中文版 →](v3.18.0-zh.md) | [日本語版 →](v3.18.0-ja.md)** + +--- + +## Highlights: What You Can Do Now + +- **Manage Grok Build (xAI's Grok CLI)**: add, import, and one-click switch Grok Build providers just like Claude Code / Codex; MCP servers and Skills sync bidirectionally, prompts auto-import on first launch, and session management plus the usage dashboard cover it fully; you can also route it through the local proxy for independent routing, failover, and billing. +- **Connect Grok with your account or an API key — both paths work**: subscription users complete an xAI device-code sign-in under Settings → OAuth Auth Center (multiple accounts supported), and all three clients — Claude Code, Claude Desktop, Codex — run straight on your Grok subscription with no API key anywhere; pay-as-you-go users connect with an xAI API key instead — Codex has a ready-made "xAI (Grok)" preset connecting natively to `api.x.ai`, and Claude Code can connect through local routing following this release's new guide. The default model is `grok-4.5` throughout. +- **Get your Codex usage numbers back to reality**: the v3.17.0 fork / sub-agent double count is rooted out at the parser level; the first launch after upgrading automatically backs up the database and rebuilds Codex usage, and the usage page gains a manual "Rebuild Codex Usage" button. Note that on first launch the history is repaired **progressively** — the dashboard numbers first shrink, then fill back in as the background re-import proceeds; this is expected (see "Upgrade Notes"). +- **Upgrade the codex CLI without fear**: the "fails to start" problem caused by codex 0.144.5's strict model-catalog parsing is fixed — generated catalogs now backfill the parser-required fields automatically. +- **Switch smoothly on Windows**: switching providers or toggling takeover no longer flashes a black console window, and no longer freezes the UI for ~2 seconds (the freeze fix benefits all platforms). +- **Troubleshoot and share logs with more confidence**: diagnostic logs persist across restarts (20 MB × 4 rotation) and every egress is uniformly redacted — URL credentials, request/response bodies, and sensitive headers never reach disk anymore; a UI crash shows an error card with a Reload button, with the details written to disk. +- **Multi-turn reasoning and parallel tool calls no longer fall over**: the Responses↔Chat bridge fixes three classes of problems — reasoning content attached to the wrong message, parallel tool calls losing their IDs or their order, and tools with a null schema getting the whole request rejected by strict upstreams. +- **Use Kimi K3**: the Kimi open-platform presets for Codex / Hermes / OpenClaw / OpenCode gain K3 (1M context), with built-in pricing seeded so its usage no longer shows $0. + +--- + +## Usage Guides + +The new capabilities in this release land mainly in the provider presets, Settings → OAuth Auth Center, and the usage dashboard. The following docs are worth reading alongside it: + +- **[xAI Grok Account Sign-In (Settings → OAuth Auth Center)](../user-manual/en/1-getting-started/1.5-settings.md)**: the device-code login flow, multi-account management, and the integration's boundaries; please read the client-identity disclosure under "Risk Notice" below before use. +- **[Using Codex-Style Providers in Claude Code (local routing guide)](../guides/claude-codex-routing-guide-zh.md)** (currently Chinese only): a new step-by-step guide added in this release. Claude Code always speaks Anthropic Messages to the local `/v1/messages` route, and the local proxy converts each request to the upstream's Responses protocol — a gateway API key, a native Responses endpoint like xAI, or a ChatGPT subscription's Codex service all fit. +- **[Using Claude in Codex (local routing guide)](../guides/codex-claude-routing-guide-en.md)**: a new step-by-step guide in three languages, pairing with v3.17.0's native Anthropic Messages upstream to connect Codex to any Claude-family gateway that only offers `/v1/messages`. +- **[Usage Statistics](../user-manual/en/4-proxy/4.4-usage.md)**: understand the Usage Dashboard's data sources and how the statistics are counted. This release fixes the usage double count and adds the "Rebuild Codex Usage" maintenance action. + +--- + +> [!WARNING] +> +> ## Only Official Channels (Please Read) +> +> CC Switch is a **fully free and open-source** desktop app, and we **do not charge users any fees**. Please only obtain the software through the official channels listed below: +> +> | Channel | Only Official | +> | ------------------ | ------------------------------------------------------------------------------ | +> | Website | **[ccswitch.io](https://ccswitch.io)** | +> | Source | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** | +> | Downloads | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** | +> | Author | **[@farion1231](https://github.com/farion1231)** | +> | Report an Imposter | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** | +> +> **Any "CC Switch" website or client that asks you for payment, top-ups, or login credentials is fake.** If you have been tricked into paying, stop the transaction immediately and file a report through GitHub Issues. + +--- + +## Overview + +Both main threads of CC Switch v3.18.0 revolve around xAI Grok. The first is **Grok Build joining the managed apps**: xAI's Grok CLI (live config `~/.grok/config.toml`) becomes the eighth managed app alongside Claude Code, Claude Desktop, Codex, Gemini CLI, OpenCode, OpenClaw, and Hermes — provider add / import / one-click switch, bidirectional MCP and Skills sync, deep-link import, a standalone preset list, and proxy takeover with its own route namespace; the companion "Grok Official" entry supports official-login-state detection and import, and CC Switch never touches the official credentials. The second is **xAI Grok account OAuth sign-in**: device-code authorization replaces the API key, the local proxy injects the access token per request, and on the Claude Code / Claude Desktop side it performs the Anthropic Messages → xAI Responses conversion; the Codex side gets a managed OAuth preset with its own compatibility layer — the ChatGPT-backend-private shapes emitted by codex 0.142+ (namespace tool declarations, private fields) are deterministically flattened and stripped, so the strictly parsing xAI gateway no longer returns 422; API-key users get a separate "xAI (Grok)" native Responses direct-connection preset that goes through no conversion at all. + +On correctness, this release concentrates on **the Codex usage double count from v3.17.0**: the replay of the parent thread's history at the start of fork / sub-agent logs is no longer imported as new usage (the parser now only trusts explicit parent identity plus token-signature alignment), a one-time automatic usage rebuild runs after upgrading (schema v16), and the usage page gains a manual rebuild button; proxy-side usage logging becomes idempotent (replays of the same response no longer stack duplicate rows), and the usage page no longer freezes during large session imports. The **Codex conversion layer** gets four more fixes: tool schemas normalized to object type, reasoning attached forward across turns, streamed parallel tool calls keeping their IDs and order, and generated model catalogs backfilling the fields codex 0.144.5+ requires. The diagnostics story matures too: logs persist across restarts, rotate by size, and redact at every egress, and UI crashes are captured by an error boundary and written to disk. Rounding things out: Kimi K3 presets and pricing, corrected OpenClaw preset costs, SudoCode.us restored, and the first-run tray language following the system locale. + +**Release date**: 2026-07-21 + +**Stats**: 52 commits | 217 files changed | +21,452 / -6,285 lines + +--- + +## Added + +### Grok Build: The Eighth Managed App + +xAI's Grok CLI ("Grok Build", live config `~/.grok/config.toml`) is now a first-class citizen in CC Switch: provider add / import / one-click switch (with a "restart Grok Build to apply" toast), app visibility and config-directory override settings, session manager and usage dashboard coverage, prompts with first-launch auto-import, `ccswitch://` deep-link provider import, and local proxy takeover — with its own `/grokbuild/v1/responses` route namespace, an independent failover queue, and per-app proxy settings; forwarding reuses Codex's Responses path but never shares Codex's provider namespace or circuit-breaker state. + +MCP servers sync bidirectionally with Grok's `[mcp_servers]` table, with the dialect differences smoothed over: Grok infers the transport from `command` / `url` and uses a `headers` field, so exports strip the explicit `type` and rename `http_headers` to `headers`, while imports infer the transport back. Skills gain a Grok Build enable flag too. + +On presets, the Codex list was deliberately **not** borrowed (an early cut leaked China-direct providers and Codex default models into the Grok form); instead Grok Build ships its own curated list: only aggregators and relays that actually carry Grok models, with the default model normalized to `grok-4.5` (`x-ai/grok-4.5` on namespaced routers). The tools panel installs Grok via the official xAI installer first (`x.ai/cli/install.sh` / `install.ps1`), with the npm package `@xai-official/grok` as fallback; installs confirmed as native self-update via `grok update`, while npm installs keep npm-anchored updates — the self-update is gated on positive native detection, so it can never touch a different kind of install. UI copy is in sync across all four locales. ([#5453](https://github.com/farion1231/cc-switch/pull/5453)) + +### Grok Official Login: Detection, Import, and Protection + +A new "Grok Official" provider entry maps to the Grok CLI's own built-in xAI OAuth login: selecting it hides the connection fields and writes an empty `~/.grok/config.toml`, and CC Switch never stores or touches the official credentials. Live-config reads, backups, and official-state writes now use syntax-only TOML validation, so an official-login (empty) config round-trips normally; importing the live config while Grok is in official login state yields "Grok Official set as current" instead of an error, matching Codex behavior. Official-state detection is deliberately wired only into the manual import command — the startup auto-importer still rejects official-state configs, so a "Grok Official" entry you deleted never comes back on the next launch. Proxy takeover of an official-login Grok config is skipped automatically, with a clear rejection on the manual path, consistent with the existing "never proxy official providers" policy. + +### Sign In with Your xAI Grok Account: Claude Code and Claude Desktop + +Claude Code and Claude Desktop gain an "xAI (Grok)" preset that replaces the API key with an OAuth device-code login: requests go through the local proxy, which performs the Anthropic Messages → xAI Responses API conversion and injects the access token per request, with `grok-4.5` as the default model on every tier (the Claude Desktop preset maps the `claude-*`-style role IDs to `grok-4.5` upstream so it passes Desktop's third-party model validation). + +Settings → OAuth Auth Center gains an xAI section: device-code login (user code with a copy button, verification link, waiting / cancel / retry), multiple accounts with a default-account picker, per-account removal, and re-auth badges — an account whose refresh token was revoked stays visible as "expired" instead of disappearing, and auth status refetches every 15 seconds so a server-side revocation surfaces on its own. + +The integration's boundaries are pinned shut: no matter what the endpoint / format fields in the form say, the upstream is always `https://api.x.ai/v1/responses` (Responses format); OAuth endpoints are resolved via OIDC discovery but strictly validated to `auth.x.ai` over https; refresh tokens live in `~/.cc-switch/xai_oauth_auth.json` (`0600` on Unix; access tokens are memory-only); and OAuth error bodies never enter error messages or logs. Pricing for `grok-4.5` ($2 input / $6 output / $0.50 cache read per million tokens) is seeded in sync so its usage no longer records $0, with existing databases picking the row up automatically on next launch. Four-locale copy included. Please read the client-identity disclosure under "Risk Notice" before use. + +Not using OAuth and only have a pay-as-you-go xAI API key? You can still connect it to Claude Code: xAI's API endpoint is standard Responses protocol, so add it as an ordinary Responses provider — a custom provider with `https://api.x.ai/v1` and your API key, upstream format set to Responses, converted between Anthropic Messages ↔ Responses by local routing; it's the same recipe as the [Using Codex-Style Providers in Claude Code](../guides/claude-codex-routing-guide-zh.md) guide. On the Codex side there's a ready-made API-key preset — see the next section. + +### Codex Straight to xAI: Managed OAuth and Native API-Key Presets + +Codex gets two ways to talk to xAI directly — OAuth managed if you have a Grok subscription, native direct connection if you have an API key: + +- **The "xAI (Grok) OAuth" managed preset** runs Codex on a Grok subscription. The form hides the key / endpoint / format fields and shows the account picker, "fetch models" uses the signed-in account, and the provider is pinned to native Responses with the base URL and per-request token enforced by the proxy — edits are ignored, so the managed route cannot be redirected. Because codex 0.142+ emits ChatGPT-backend-private request shapes (`type:"namespace"` tool declarations make xAI's strict parser return a straight 422, plus private fields like `prompt_cache_retention`, `safety_identifier`, `external_web_access`, the `additional_tools` carrier, and sampling knobs grok-4.5 doesn't support), the OAuth route adds a compatibility layer on top of the native passthrough: namespace tools are flattened to top-level function tools (with the same sha256-truncated naming as the Chat path) and restored to namespaced form on the response side for both streaming and non-streaming, and unsupported fields are stripped — all deterministic field removals / structural lifts, never semantic rewrites, so prompt-cache prefixes stay stable. The layer is gated exclusively on the xAI OAuth provider type; no other provider's traffic is touched. +- **The "xAI (Grok)" API-key preset** connects natively to Responses at `api.x.ai/v1`, with a 500K-context `grok-4.5` catalog entry built in. This preset does **not** receive the xAI-specific compatibility transforms above — API-key users on codex 0.142+ can still hit xAI's strict parser, and the OAuth preset is the fully compatible path. + +xAI OAuth token failures are classified as non-retryable, so failover never quietly moves your conversation onto a different Grok account. + +### UI Crash Capture: On-Disk Reports and a Reload Screen + +A React error boundary now wraps the entire UI (including the database-recovery screen): a renderer crash shows a "Something went wrong in the interface" card with a Reload button instead of a blank white window, and global `error` / `unhandledrejection` handlers persist renderer errors to disk — previously a JS crash left zero on-disk evidence. Everything the frontend logs passes two redaction layers: a structured serializer that redacts by sensitive property name (`tokens` / `apiKeys` / `credentials` variants all normalized to match, hiding the entire value including nested objects) and by value shape (token prefixes, PEM headers, high-entropy opaque strings), then a single text egress whose ordered regex chain covers URL query values and credentials, auth headers and schemes, and named secret containers — even in double-encoded JSON. JSON arriving as a string is re-parsed and redacted structurally, and oversized structured input is dropped entirely rather than truncated — a truncated JSON string would fall back to the weaker text regexes and could leak. The settings toggles were also relabeled to say what they actually control: "Application Diagnostic Logs" (cc-switch.log) versus the proxy's "Record Request Usage" (the stats database, which never was a text log). Four locales in sync. + +### "Rebuild Codex Usage" Maintenance Button + +The usage dashboard's maintenance section gains "Rebuild Codex Usage": after backing up the database, it wipes only `codex_session`-sourced detail rows, their `_codex_session` daily rollups, and the Codex sync cursors, then re-imports every rollout file from scratch with the corrected parser — the recovery path for databases already inflated by the double-count bug below, and the retry path for deferred fork files whose parent log has since been restored. The manual rebuild fails hard when the pre-rebuild backup cannot be written (the automatic migration variant only warns, since blocking startup on an unwritable backup directory would be the worse outcome after an upgrade); the whole backup → reset → re-import sequence holds the session-sync lock, so the 60-second background sync cannot interleave with the wipe; and completion always sends exactly one frontend refresh notification — including when the re-import returns zero rows or fails — so the dashboard never keeps showing pre-reset numbers. Cursor cleanup matches rollout paths purely by shape (a `rollout-{uuid}` filename under a `sessions` / `archived_sessions` segment), so cursors recorded under an old `CODEX_HOME` are cleaned too. Four locales in sync. + +### Session Import Observability: Deferred Files and Suspected Duplicates + +Session sync results now report `filesScanned`, `deferredFiles` — fork rollouts whose parent log is missing or whose parent markers conflict are held back without writing a cursor, so a later sync or a manual rebuild retries them instead of importing on a guess — and `suspectedDuplicates`: a post-insert probe checks each imported row for a pre-existing same-fingerprint row (via the `idx_request_logs_dedup_lookup_expr` expression index) and logs a warning per hit. If the double-count bug ever regresses, it will announce itself in the logs instead of silently inflating the totals. + +### Kimi K3 in Presets and Built-In Pricing + +The Kimi open-platform presets for Codex / Hermes / OpenClaw / OpenCode gain Kimi K3 (1M context window), appended after K2.7 Code so existing default-model behavior is unchanged. The built-in pricing table gains `kimi-k3` (official list price: $3 input / $15 output / $0.30 cache read per million tokens) plus a bare `k3` alias — the Kimi For Coding subscription reports its model under the short id `k3`, which would otherwise match no pricing row (same precedent as the existing `hunyuan-hy3` / `hy3` pair). Existing databases pick both rows up automatically on next launch, without touching user-edited pricing. + +### SudoCode.us Returns, Coexisting with SudoCode.chat + +The two unrelated companies that happen to share the "SudoCode" name are now two separate presets: the sponsor is renamed "SudoCode.chat", and the previously replaced-in-place "SudoCode.us" returns with its original endpoints, models, and icon, plus a distinct Hermes slug so both can coexist in the additive `~/.hermes/config.yaml`. Counting the new Grok Build preset list, SudoCode.chat ships in seven apps and SudoCode.us in all eight. + +--- + +## Changed + +### Diagnostic Logs: Persistent Across Restarts, Size-Rotated, and Never Recording Secrets + +`cc-switch.log` is no longer wiped on every startup — the log that could have explained a crash used to be gone by the time the app reopened — and instead rotates at 20 MB with 4 archives kept (~100 MB cap, versus a single file that could balloon to 1 GB before); the previously unbounded `crash.log` rotates at 5 MB with 2 archives, with the check / rotate / append sequence under one lock so concurrent panics cannot lose an archive. + +Persistent logs make verbatim secrets a real exposure (users attach these files to public issues), so the same change scrubs every backend log egress: upstream URLs are logged with userinfo / query / fragment stripped (origin-only when no known secret is available to substitute, since a credential could be embedded in the path); request and response bodies are never logged — replaced by byte counts, a short hash, or a safe classification (`sse` / `html` / `json-like` / `binary-or-encoded`, …) that keeps the transform-debugging signal without the content; response headers go through an allowlist (unlisted headers log name-only); the secret values currently in use (API key, access token) are substituted out of any logged URL that carries them; and MCP custom-field values are omitted. The log plugin also registers earlier (updater / startup failures become diagnosable), the persisted log level applies as soon as the database opens and fails closed to Info, and the "Enable Diagnostic Logs" switch now gates frontend-originated log writes too. **Log files written by earlier versions are not retroactively scrubbed** — see "Upgrade Notes". + +### Preset Picker: Sponsors Grouped, Everything Else Alphabetized + +The preset picker's default order becomes four tiers: official first, then the prime partner, then sponsor presets (in the same order as the README sponsor table, which the preset files were physically reordered to match), then all remaining presets sorted alphabetically by display name instead of file order. An entry matching multiple tiers lands only in the earliest one, so nothing shows up twice. + +### Preset "Get API Key" Links Updated + +The key-application links on the RunAPI, ClaudeCN, ZetaAPI, and APINebula presets now open each provider's current registration / referral page (ClaudeCN also moved domains: claudecn.top → claudecn.ai). Referral tags remain confined to these links and the README — website links and API endpoints stay untouched. + +--- + +## Fixed + +### Codex Fork / Sub-Agent Replayed Parent History No Longer Counted as New Usage (the v3.17.0 Double Count) + +Fixes the v3.17.0 usage inflation: forking a Codex task or spawning a sub-agent in copy mode re-counted the parent conversation's token history as new usage — users reported single days jumping by billions of tokens, byte-identical parent/child rows, and empty forks carrying usage they never consumed. Fork / sub-agent rollout files begin by replaying the parent thread's history, and the old parser located the takeover boundary heuristically (the first `thread_settings_applied` event, object-shaped `subagent` source markers): the boundary landed too early when the parent's own settings changes appeared in the replay, and the current string-shaped source markers weren't recognized at all, importing the entire replayed parent history verbatim. The new parser trusts only explicit parent identity — `forked_from_id` on the child's `session_meta`, or `source.subagent.thread_spawn.parent_thread_id`, with a conflict between the two deferring the file — anchors each thread's identity to the rollout filename UUID, loads the parent rollout's own pre-fork token-count sequence, and strips the child's replayed prefix by aligning token signatures against it: replayed events only restore the cumulative baseline and are never inserted as rows. Sub-agent logs that carry no replayed history are now counted as live usage, also fixing the opposite-direction undercount where real sub-agent consumption was skipped as suspected replay. ([#5335](https://github.com/farion1231/cc-switch/issues/5335), [#5433](https://github.com/farion1231/cc-switch/issues/5433), [#5381](https://github.com/farion1231/cc-switch/issues/5381)) + +### Proxy Usage Logging Is Now Idempotent: Response-Scoped Stable Keys + +When a terminal usage event carried no message id — the norm for Codex `/responses` traffic through the local proxy — the dedup key fell back to a random UUID, so every retry / replay of the same upstream response minted a fresh key and `INSERT OR REPLACE` stacked a new row each time; one reporter's database held the same usage combination 2,078 times. The parser now takes the key from the response envelope itself — the Codex `response.completed` event's `response.id` (ids from `response.created` are discarded), Chat Completions `chatcmpl` ids, and the Gemini `responseId` — scoped as `session:{app_type}:{provider_id}:{id}`: the same response replayed against a different provider during failover still bills once per provider without cross-provider collisions (Claude keeps the bare `session:{id}` shape so proxy rows continue to converge with session-log imports). When no envelope id exists at all, the fallback is a deterministic SHA-256 over the response's usage semantics rather than a random UUID — an identical replay must collide into the same key for dedup to work — and the final database write becomes a guarded insert-if-absent within the dedup window instead of an unconditional REPLACE. ([#5496](https://github.com/farion1231/cc-switch/issues/5496)) + +### Usage Page No Longer Freezes During Large Session Imports + +Opening the usage page while a big import ran could lock the whole UI up: every inserted row fired a refresh notification, each notification made the frontend re-run all ~10 usage queries, and those queries contended with the importer for the single database connection while it parsed rollout files tens of megabytes large, line by line — on duplicate-inflated databases the three compounded each other. Session sync now notifies the frontend once per completed pass; all session importers are serialized behind a single-flight lock (a manual "sync now" queues behind the running pass instead of racing it); the blocking parse work runs on a dedicated blocking thread so it no longer starves the async runtime driving the UI's commands; and the 60-second background tick skips missed runs instead of bursting to catch up. + +### codex 0.144.5+ No Longer Fails to Start on CC Switch-Generated Model Catalogs + +codex ≥ 0.144.5 parses external model catalogs strictly and rejects the whole file when an entry is missing `supports_reasoning_summaries` — both the Codex CLI and the desktop app failed to launch, and deleting the generated catalog didn't help because any provider save regenerated it the same way. The root cause: CC Switch clones its catalog template from the machine-shared `models_cache.json`, whose field set is whatever the last-writing codex process produced — a coexisting older codex build kept rewriting the cache without the field the newer parser requires. Generated catalogs now backfill parser-required fields from the bundled static template, and only when absent (dynamic values always win); optional capability fields whose "missing = parser default" semantics must survive are deliberately not backfilled. + +### Windows: No More Console Flash or UI Freeze When Switching Providers + +Switching providers or toggling takeover on Windows flashed a transient console window and froze the UI for up to ~2 seconds. Three causes, three fixes: the `codex debug models --bundled` probe launches `codex.cmd` through `cmd.exe`, which in a GUI-subsystem app spawns its own console — the child process is now created with `CREATE_NO_WINDOW`; the model-catalog template was regenerated on every switch — it's now cached process-wide after the first successful load (failures stay retryable, so a bad first probe cannot poison the cache), and the Codex CLI starts at most once per app run; and `switch_provider` was a synchronous command on the main thread — it's now async with the real work on a blocking thread, still serialized by the per-app switch lock. The freeze fix benefits all platforms; the console-flash fix is Windows-specific. + +### Tool Schemas with Null, Missing, or Union Parameter Types Accepted by Strict Upstreams + +Built-in Codex tools such as `codex_app__automation_update` declare `parameters: null` (or `type: null`), which strict OpenAI-compatible upstreams like DeepSeek reject with a 400 for the entire request — killing tool-using sessions routed through the proxy. The Responses→Chat bridge now normalizes every tool's parameters to a `type:"object"` schema: null or missing parameters (including the nested-form missing case) become `{"type":"object","properties":{}}`, a non-object `type` (including `type: null`) is corrected to `"object"` in place, and top-level `oneOf` union schemas get a root `type:"object"` added with their branches preserved untouched. The same object-type guarantee was extended to the Codex→Anthropic tool path's `input_schema`. Existing `properties` / `required` are never dropped. ([#4706](https://github.com/farion1231/cc-switch/pull/4706), [#5315](https://github.com/farion1231/cc-switch/pull/5315), fixes #4705, #4783) + +### Reasoning Models Keep Their Thinking Across Multi-Turn Codex Chat Conversations + +With a reasoning model (e.g. kimi-k2-thinking) behind the proxy's Responses→Chat bridge, multi-turn history mangled the thinking: each turn's `reasoning` item got glued onto the tail of the **previous** assistant message, leaving the following assistant turn with no `reasoning_content` — models would visibly break off mid-conversation. Responses semantics place reasoning **before** the message it belongs to, so the bridge now attaches reasoning forward to the assistant message or tool call that follows it; genuine trailing reasoning back-attaches only at a confirmed tail (end of input, or a turn boundary such as an incoming user message — where it was previously silently discarded), appending to any embedded reasoning already present; and pending reasoning is always consumed at boundaries, so it can never leak across a user turn into a later assistant message. ([#5508](https://github.com/farion1231/cc-switch/pull/5508)) + +### Streamed Parallel Tool Calls Keep Their IDs and Their Order + +Two bugs in the Chat→Responses streaming bridge corrupted parallel tool calls from upstreams that split identity across chunks: a continuation delta carrying an empty `id` overwrote the real `call_id` (the Codex client then saw `call_id:""` and couldn't match tool results to calls), and tool calls were emitted the moment they individually became ready, so a later index whose name arrived early could jump ahead of an earlier one — reordering parallel calls. Empty ids are now ignored, and emission goes through a consecutive-index gate that releases tool calls strictly in Chat `index` order, waiting on any not-yet-identified earlier index; no fake call id is ever synthesized mid-stream (only as a last resort at stream finalization, which also skips nameless calls defensively and still emits sparse indexes). ([#5310](https://github.com/farion1231/cc-switch/pull/5310)) + +### Managed-OAuth Providers Reliably Flagged as "Needs Local Routing" + +The "needs routing" badge and switch-time warning were derived from the provider's API format — the wrong signal for managed-OAuth providers (Copilot, Codex OAuth, xAI), whose credential is injected by the proxy regardless of upstream format: a managed provider on a native format got no warning and failed silently without takeover. Routing need is now decided by a single shared predicate: official providers never need routing, managed-OAuth providers always do, and format-based rules apply only to the remaining cases. The switch-time gate also checks the right readiness signal per app: per-app takeover status for most apps (the old gate looked only at a global proxy-running flag, missing "the proxy runs but this app isn't taken over"), while Claude Desktop keeps watching the proxy process itself — the backend's takeover status has no Claude Desktop field, so a uniform per-app gate would have left Desktop warning forever. Claude Desktop provider forms now force proxy mode and lock the model-mapping toggle for every managed-OAuth type, not just xAI. Four locales in sync. + +### Tool Updates Work When Node Lives in nvm / fnm / mise + +Anchored npm update and repair commands invoked npm by absolute path, but npm's launcher resolves `node` via its `#!/usr/bin/env node` shebang against PATH — and a GUI-launched app inherits only the system PATH, without the version-manager directories, so updates for tools installed via nvm / fnm / mise silently failed. Every anchored npm invocation now prefixes PATH with npm's own sibling `bin` directory, so npm and its shebang resolve to the same Node install; the Codex self-repair (uninstall + reinstall) path is covered too. + +### Deleted Default Skill Repositories Stay Deleted + +Default Skill repositories were re-seeded on every startup by a "supplement missing defaults" pass, so a default repo you deleted silently returned on the next launch. Seeding is now one-time per database, tracked by a settings flag; databases that already contain repositories at upgrade time get the flag set without any re-seeding, so existing selections are untouched. ([#5356](https://github.com/farion1231/cc-switch/pull/5356)) + +### First-Run Tray Language Follows the System Locale + +Before any language was chosen in settings, the tray menu was hardcoded to Simplified Chinese — on English / Japanese / Traditional-Chinese systems the main UI correctly followed the OS locale while the tray disagreed, until the user switched language once. The tray now derives its first-run language from the OS locale with the same precedence rules as the frontend (including `zh-TW` / `zh-HK` / `zh-Hant` → Traditional Chinese); an explicitly chosen language always wins, and unreadable locales fall back to Chinese as before. ([#4355](https://github.com/farion1231/cc-switch/pull/4355)) + +### Failed Imports Show the Real Error and Refresh the List + +Every failed "import from live config" produced an empty error toast, because Tauri's `invoke` rejects with the backend's error **string** while the handler read `.message` off it. The backend's actual message is now shown (with a localized generic fallback), and the provider list refreshes even on failure, so side effects committed before the error are visible immediately. + +### OpenClaw Preset Model Costs Corrected to Official List Prices + +Fifteen OpenClaw preset entries carried cost values in the wrong unit or unconverted currency — the `cost` field is USD per million tokens, but e.g. `glm-5.1` was listed at `0.001/0.001` (≈1000× undervalued, so its usage showed near-zero cost) while `deepseek-v4-pro` carried unconverted CNY values (overvalued). All entries now carry official list prices in $/M; subscription-plan and free-tier endpoints deliberately show list prices too, so plan users see the standard value of their usage. Providers created from these presets going forward get the corrected values; previously added providers keep the config they were created with. + +### A Batch of Small UI Fixes + +- **AiHubMix icon**: the Codex app's AiHubMix preset was the only one missing its brand-icon fields and rendered a generic icon; it now matches the other apps. +- **Two missing locale keys backfilled**: the reason fragment in Codex's "needs routing because it uses Anthropic Messages format" toast rendered in Chinese inside an otherwise-localized sentence (`proxyReasonAnthropicMessages` existed in no locale file), and the provider form's key-status loading label had shipped only as a hardcoded default since April; both now exist in zh / en / ja / zh-TW. + +--- + +## Documentation + +### Codex ↔ Claude Routing Guides, Both Directions + +Two new guides complete the pair — "Claude models inside the Codex client" and "Responses providers inside the Claude Code client": + +- **[Using Claude in Codex](../guides/codex-claude-routing-guide-en.md)** (Chinese / English / Japanese, with screenshots): pairs with v3.17.0's native Anthropic Messages upstream to connect Codex to a Claude-family `/v1/messages` gateway; the v3.17.0 release notes now link to it. +- **[Using Codex-Style Providers in Claude Code](../guides/claude-codex-routing-guide-zh.md)** (Chinese, with screenshots): drive Claude Code with Responses-speaking providers (a gateway API key, or a ChatGPT subscription's Codex service) — Claude Code always speaks Anthropic Messages to the local `/v1/messages` route, and the proxy converts each request to the upstream's Responses protocol. + +### README Sponsor Updates + +SubRouter joins the sponsor table across the four README languages; the pinned Kimi sponsor copy is refreshed to K3 with banners served from the Moonshot CDN; RunAPI benefit copy is refreshed, and sponsor rows are reordered to match the in-app preset order. + +--- + +## Upgrade Notes + +### Automatic Database Migration and the One-Time Codex Usage Rebuild + +Upgrading from v3.17.0 runs three schema migrations in sequence (v13 → v16): v14 rebuilds the `proxy_config` table to admit Grok Build (existing per-app proxy settings are all carried over, and a `grokbuild` row is added); v15 adds Grok Build enablement columns to the MCP-server and Skills tables; and v16 triggers the one-time automatic Codex usage rebuild — the database is first backed up under `backups/`, `codex_session` data and cursors are reset, and the normal startup sync re-imports everything with the corrected parser. Typical datasets take seconds; the heaviest dataset measured (1,801 rollout files / 1.5 GB) took about 65 seconds. Later launches are incremental as before. If you're in the habit of rolling back to older versions, back up `~/.cc-switch/cc-switch.db` yourself first. + +**Please note on first launch**: the history repair completes **progressively** — the rebuild proceeds in the background with the startup sync, and during that window the Codex history numbers on the usage dashboard first drop to zero and then fill back in step by step. This is expected behavior, not data loss. The post-rebuild total will usually be **smaller** than before the upgrade: the part inflated by double counting is squeezed out, and what remains is your real usage. + +### Boundaries of the Rebuild + +- The rebuild recomputes usage from the rollout JSONL files, so **history whose source log was already deleted cannot be reconstructed**. +- Fork files whose parent rollout is missing are deferred and reported instead of imported on a guess; restore the parent log and run "Rebuild Codex Usage" to import them later. +- Historical proxy-source duplicate rows are permanently retained — the migration rebuilds only session-sourced data, and no cleanup pass for past proxy inflation exists; the idempotent logger only guarantees no new duplicates from this point on. + +### Old Log Files Are Not Retroactively Scrubbed + +From this release on, diagnostic logs are no longer cleared at startup and persist across restarts (up to ~100 MB of rotated runtime logs plus ~15 MB of crash logs). **Log files written by earlier versions are not retroactively scrubbed** and may contain API keys, tokens, or URLs with credentials — review pre-upgrade logs before sharing them publicly. + +### Grok Build Installs via the Official Installer Script + +Installing or reinstalling Grok Build now prefers the official xAI installer, fetching `x.ai/cli/install.sh` (or `install.ps1` on Windows) at install time, with npm as fallback; existing npm installs keep updating via npm. + +### Built-In Pricing Rows Auto-Appended + +New pricing rows (`grok-4.5`, `kimi-k3`, `k3`) are appended automatically on next launch via insert-if-absent; user-edited pricing rows are never overwritten. + +--- + +## Risk Notice + +### xAI Grok OAuth Sign-In (New in This Release — Please Read) + +This release's xAI Grok OAuth integration **reuses the public OAuth client identity and scopes registered for the official Grok CLI** (`client_id b1a00492-073a-47ea-816f-4c329264a828`, scope including `grok-cli:access`), rather than an application identity registered by CC Switch. xAI may not support this use, and **it could lead to account restriction or suspension — use at your own risk**. The feature is entirely opt-in: if you don't add an xAI provider, nothing changes. On first login it creates `~/.cc-switch/xai_oauth_auth.json` (refresh tokens only, `0600` on Unix; access tokens are held in memory) and contacts `auth.x.ai` and `api.x.ai` through your configured outbound proxy, with no local callback port. + +### Carried-Over Reverse-Proxy Notices + +**Codex OAuth reverse proxy**: using a ChatGPT subscription's Codex OAuth through a reverse proxy may violate OpenAI's terms of service. See the [v3.13.0 release notes](v3.13.0-en.md#️-risk-notice) for details. + +**Third-party provider routing**: when CC Switch's local proxy converts and forwards Codex, Claude Desktop, or Grok Build requests to third-party providers, each provider may have different requirements for billing, compliance, and data retention. Read the target provider's terms before use. + +By enabling these features, users accept the related risks. CC Switch is not responsible for account restrictions, warnings, or service suspensions caused by using these features. + +--- + +## Thanks + +Thanks to the following contributors for the features and fixes in v3.18.0: + +- [#5453](https://github.com/farion1231/cc-switch/pull/5453): first-class Grok Build support (the core of the eighth managed app), thanks @YUZHEthefool. +- [#5508](https://github.com/farion1231/cc-switch/pull/5508): attach reasoning forward across the Responses→Chat bridge, thanks @ka79376046. +- [#5310](https://github.com/farion1231/cc-switch/pull/5310): preserve streamed parallel tool-call identity and order, thanks @SaladDay. +- [#5315](https://github.com/farion1231/cc-switch/pull/5315): default Codex tool parameters to an object schema, thanks @Komikawayi. +- [#4706](https://github.com/farion1231/cc-switch/pull/4706): normalize tool parameter types for strict OpenAI-compatible providers, thanks @Ryan2128. +- [#5356](https://github.com/farion1231/cc-switch/pull/5356): keep deleted default Skill repositories deleted, thanks @allenxu09. +- [#4355](https://github.com/farion1231/cc-switch/pull/4355): first-run tray language follows the system locale, thanks @LaiYueTing. +- [#5138](https://github.com/farion1231/cc-switch/pull/5138): extend backend CI to Linux / Windows / macOS, thanks @zayokami. + +Thanks also to everyone who reported Codex usage anomalies, new-codex startup failures, and tool-call problems — this release's most important fixes came directly from reproduction clues in those real-world reports. + +--- + +## Download & Install + +Visit [Releases](https://github.com/farion1231/cc-switch/releases/latest) and download the build for your system. + +### System Requirements + +| System | Minimum Version | Architecture | +| ------- | -------------------- | ----------------------------------- | +| Windows | Windows 10 and later | x64 / ARM64 | +| macOS | macOS 12 (Monterey)+ | Intel (x64) / Apple Silicon (arm64) | +| Linux | See table below | x64 / ARM64 | + +### Windows + +| File | Description | +| ---------------------------------------- | ------------------------------------------------ | +| `CC-Switch-v3.18.0-Windows.msi` | **Recommended** - MSI installer with auto-update | +| `CC-Switch-v3.18.0-Windows-Portable.zip` | Portable build, unzip and run | + +Windows ARM64 devices should pick the artifact whose file name carries the `arm64` tag. + +### macOS + +| File | Description | +| -------------------------------- | ----------------------------------------------------- | +| `CC-Switch-v3.18.0-macOS.dmg` | **Recommended** - DMG installer, drag to Applications | +| `CC-Switch-v3.18.0-macOS.zip` | Unzip and drag to Applications, Universal Binary | +| `CC-Switch-v3.18.0-macOS.tar.gz` | For Homebrew install and auto-update | + +Homebrew install: + +```bash +brew install --cask cc-switch +``` + +Upgrade: + +```bash +brew upgrade --cask cc-switch +``` + +### Linux + +Linux assets are available for both **x86_64** and **ARM64** (`aarch64`). Choose the file whose architecture tag matches your machine's `uname -m` output: + +- `CC-Switch-v3.18.0-Linux-x86_64.AppImage` / `.deb` / `.rpm` +- `CC-Switch-v3.18.0-Linux-arm64.AppImage` / `.deb` / `.rpm` + +| Distribution | Recommended Format | Install Command | +| --------------------------------------- | ------------------ | ---------------------------------------------------------------------- | +| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb` | `sudo dpkg -i CC-Switch-*.deb` or `sudo apt install ./CC-Switch-*.deb` | +| Fedora / RHEL / CentOS / Rocky Linux | `.rpm` | `sudo rpm -i CC-Switch-*.rpm` or `sudo dnf install ./CC-Switch-*.rpm` | +| openSUSE | `.rpm` | `sudo zypper install ./CC-Switch-*.rpm` | +| Arch Linux / Manjaro | `.AppImage` | Make executable and run directly, or use AUR | +| Other distributions / unsure | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` | diff --git a/docs/release-notes/v3.18.0-ja.md b/docs/release-notes/v3.18.0-ja.md new file mode 100644 index 000000000..919862351 --- /dev/null +++ b/docs/release-notes/v3.18.0-ja.md @@ -0,0 +1,331 @@ +# CC Switch v3.18.0 + +> 本リリースでは、まったく新しい 2 つのことができるようになります。**xAI の Grok CLI（Grok Build）を CC Switch で管理する**——8 番目の管理対象アプリとして、プロバイダーのワンクリック切り替え、MCP / Skills 同期、プロキシテイクオーバー、使用量統計をすべて利用できます。そして **Grok を Claude Code、Claude Desktop、Codex へ接続する**——xAI Grok アカウントで直接サインインする方法（デバイスコード認証、API key 不要、Grok サブスクリプションで動作。Codex 側には厳格ゲートウェイ互換レイヤーがあり codex 0.142+ でも動きます）と、xAI API key で接続する方法（Codex にはネイティブ Responses 直結プリセット、Claude Code はローカルルーティング経由）の両方に対応します。修正も重要です。**v3.17.0 で混入した Codex 使用量の二重計上を修正**し、アップグレード後にデータを自動再構築してダッシュボードの数字を実態に戻します。**codex 0.144.5+ がモデルカタログ起因で起動できない問題も修正**。Windows でのプロバイダー切り替え時にコンソールウィンドウが一瞬表示されたり UI が固まったりする問題も解消しました。診断ログは「起動のたびに消去」から、再起動をまたいで保持・サイズローテーション・全面的な秘密情報除去へ移行し、UI クラッシュも真っ白な画面ではなくディスクに記録が残ります。 + +**[English →](v3.18.0-en.md) | [中文版 →](v3.18.0-zh.md)** + +--- + +## ハイライト：本リリースでできること + +- **Grok Build（xAI の Grok CLI）を管理**：Claude Code / Codex と同じように、Grok Build のプロバイダーを追加・インポート・ワンクリック切り替えできます。MCP サーバーと Skills は双方向同期、プロンプトは初回起動時に自動インポート、セッション管理と使用量ダッシュボードも完全対応。ローカルプロキシによるテイクオーバーで、独立したルーティング・failover・課金も利用できます。 +- **Grok の接続はアカウントでも API Key でも**：サブスクリプションユーザーは「設定 → OAuth 認証センター」でデバイスコードによる xAI サインインを行い（複数アカウント対応）、Claude Code・Claude Desktop・Codex の 3 クライアントが API key なしで Grok サブスクリプションで動きます。従量課金ユーザーは xAI API key で接続——Codex には `api.x.ai` へネイティブ直結する「xAI (Grok)」プリセットがあり、Claude Code は本リリースの新ガイドに沿ってローカルルーティングで接続できます。既定モデルはいずれも `grok-4.5` です。 +- **Codex の使用量を実態に戻す**：v3.17.0 の fork / サブエージェント二重計上をパーサーレベルで根治しました。アップグレード後の初回起動でデータベースをバックアップして Codex 使用量を自動再構築し、使用量ページには手動の「Codex 使用量を再構築」ボタンも追加。なお初回起動時の履歴修復は**段階的に**進みます——数字がいったん減り、バックグラウンドの再インポートに伴って徐々に埋め戻されるのは想定どおりの動作です（「アップグレード時の注意」参照）。 +- **codex CLI を安心してアップグレード**：codex 0.144.5 の厳格なモデルカタログ解析による「起動できない」問題を修正。生成カタログはパーサー必須フィールドを自動補完します。 +- **Windows でスムーズに切り替え**：プロバイダー切り替えやテイクオーバーの切り替えで黒いコンソールウィンドウが一瞬表示されることがなくなり、UI が約 2 秒固まる問題も解消しました（フリーズ修正は全プラットフォームに効きます）。 +- **ログの調査と共有をより安心に**：診断ログは再起動をまたいで保持（20 MB × 4 ローテーション）され、すべての出口で一律に秘密情報を除去——URL 内の認証情報、リクエスト / レスポンスボディ、機微なヘッダーはディスクに残りません。UI クラッシュはエラーカードと再読み込みボタンで受け止め、詳細をディスクへ記録します。 +- **マルチターンの reasoning と並列ツール呼び出しが壊れない**：Responses↔Chat ブリッジで、reasoning の誤った付け先、並列ツール呼び出しの ID 消失・順序入れ替わり、tool schema が null の場合にリクエスト全体が拒否される問題の 3 種類を修正しました。 +- **Kimi K3 を使う**：Codex / Hermes / OpenClaw / OpenCode の Kimi オープンプラットフォームプリセットに K3（1M コンテキスト）を追加し、内蔵価格も登録。使用量が $0 と表示されなくなります。 + +--- + +## 利用ガイド + +本リリースの新機能は、主にプロバイダープリセット、「設定 → OAuth 認証センター」、使用量ダッシュボードにあります。以下のドキュメントもあわせてご覧ください： + +- **[xAI Grok アカウントサインイン（設定 → OAuth 認証センター）](../user-manual/ja/1-getting-started/1.5-settings.md)**：デバイスコードログインの流れ、複数アカウント管理、連携の境界について説明します。利用前に下記「リスク通知」のクライアント識別情報の開示を必ずお読みください。 +- **[Claude Code で Codex 系プロバイダーを使う（ローカルルーティングガイド）](../guides/claude-codex-routing-guide-zh.md)**（現時点では中国語のみ）：本リリース追加のステップバイステップガイドです。Claude Code は常にローカルの `/v1/messages` ルートに対して Anthropic Messages を話し、ローカルプロキシが各リクエストを上流の Responses プロトコルへ変換します——ゲートウェイの API key、xAI のようなネイティブ Responses endpoint、ChatGPT サブスクリプションの Codex サービスのいずれにも使えます。 +- **[Codex で Claude を使う（ローカルルーティングガイド）](../guides/codex-claude-routing-guide-ja.md)**：本リリース追加の 3 言語ガイド。v3.17.0 の「ネイティブ Anthropic Messages 上流」と組み合わせ、`/v1/messages` のみを提供する Claude 系ゲートウェイへ Codex を接続します。 +- **[使用量統計](../user-manual/ja/4-proxy/4.4-usage.md)**：使用量ダッシュボードのデータソースと集計方法を確認できます。本リリースでは二重計上を修正し、「Codex 使用量を再構築」メンテナンス操作を追加しました。 + +--- + +> [!WARNING] +> +> ## 唯一の公式チャネル（必ずお読みください） +> +> CC Switch は**完全に無料・オープンソース**のデスクトップアプリで、**ユーザーから料金を徴収することはありません**。本ソフトウェアは下記の公式チャネルからのみ入手してください： +> +> | チャネル | 唯一の公式 | +> | ------------ | ------------------------------------------------------------------------------ | +> | 公式サイト | **[ccswitch.io](https://ccswitch.io)** | +> | ソースコード | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** | +> | ダウンロード | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** | +> | 作者 | **[@farion1231](https://github.com/farion1231)** | +> | 偽サイト通報 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** | +> +> **料金請求・チャージ・認証情報の提供を求める「CC Switch」サイトやクライアントはすべて偽物です。** 支払いを誘導された場合は直ちに操作を中止し、GitHub Issues からご報告ください。 + +--- + +## 概要 + +CC Switch v3.18.0 の 2 本柱はどちらも xAI Grok を中心に据えています。1 つ目は **Grok Build の管理対象アプリ入り**です。xAI の Grok CLI（live 設定 `~/.grok/config.toml`）が、Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes に並ぶ 8 番目の管理対象アプリになりました——プロバイダーの追加 / インポート / ワンクリック切り替え、MCP・Skills の双方向同期、ディープリンクインポート、独立したプリセットリスト、専用ルート名前空間つきのプロキシテイクオーバー。併設の「Grok 公式」エントリは公式ログイン状態の検出とインポートに対応し、CC Switch が公式認証情報に触れることはありません。2 つ目は **xAI Grok アカウントの OAuth サインイン**です。デバイスコード認証が API key を置き換え、ローカルプロキシがリクエストごとにアクセストークンを注入します。Claude Code / Claude Desktop 側では Anthropic Messages → xAI Responses の変換を行い、Codex 側は管理下 OAuth プリセットと専用互換レイヤーを備えます——codex 0.142+ が発する ChatGPT バックエンド固有の形（namespace ツール宣言や非公開フィールド）を決定的に平坦化・除去し、厳格に解析する xAI ゲートウェイが 422 を返さなくなります。API key ユーザーには、変換を一切通さない「xAI (Grok)」ネイティブ Responses 直結プリセットも用意しました。 + +正確性の面では、**v3.17.0 の Codex 使用量二重計上**を集中的に修正しました。fork / サブエージェントログ冒頭にある親スレッド履歴のリプレイを新規使用量として取り込まなくなり（パーサーは明示的な親識別子とトークン署名の照合のみを信頼）、アップグレード後に一度だけ使用量を自動再構築（schema v16）、使用量ページには手動再構築ボタンを追加。プロキシ側の使用量記録は冪等になり（同じレスポンスのリプレイが重複行を積み上げない）、大量セッションのインポート中に使用量ページが固まる問題も解消しました。**Codex 変換レイヤー**にはさらに 4 つの修正——tool schema の object 型への正規化、reasoning のターンをまたぐ前方アタッチ、ストリーミング並列ツール呼び出しの ID と順序の保持、codex 0.144.5+ が要求するカタログフィールドの補完。診断まわりも成熟し、ログは再起動をまたいで保持・サイズローテーション・全出口で秘密情報除去、UI クラッシュはエラーバウンダリで捕捉してディスクへ記録します。ほかにも Kimi K3 のプリセットと価格、OpenClaw プリセット価格の修正、SudoCode.us の復活、トレイの初回言語がシステムロケールに従う改善などを含みます。 + +**リリース日**: 2026-07-21 + +**Stats**: 52 commits | 217 files changed | +21,452 / -6,285 lines + +--- + +## 追加機能 + +### Grok Build：8 番目の管理対象アプリ + +xAI の Grok CLI（Grok Build、live 設定 `~/.grok/config.toml`）が CC Switch の第一級市民になりました。プロバイダーの追加 / インポート / ワンクリック切り替え（切り替え後は「Grok Build を再起動して適用」のトースト表示）、アプリ表示と設定ディレクトリ上書きの設定、セッション管理と使用量ダッシュボード対応、初回起動時のプロンプト自動インポート、`ccswitch://` ディープリンクによるプロバイダーインポート、そしてローカルプロキシテイクオーバー——専用の `/grokbuild/v1/responses` ルート名前空間、独立した failover キュー、アプリ別プロキシ設定を持ちます。転送は Codex の Responses 経路を再利用しますが、Codex のプロバイダー名前空間や circuit breaker の状態を共有することはありません。 + +MCP サーバーは Grok の `[mcp_servers]` テーブルと双方向同期し、方言の差異も吸収します。Grok は `command` / `url` からトランスポートを推定し `headers` フィールドを使うため、エクスポート時は明示的な `type` を取り除き `http_headers` を `headers` にリネームし、インポート時は逆方向に推定して戻します。Skills にも Grok Build の有効化フラグが付きました。 + +プリセットはあえて Codex のリストを流用**していません**（初期の実装では中国向け直結プロバイダーや Codex の既定モデルが Grok のフォームに混入していました）。Grok Build 専用に整理したリストとして、実際に Grok モデルを扱うアグリゲーターと中継サービスのみを収録し、既定モデルは `grok-4.5`（名前空間型ルーターでは `x-ai/grok-4.5`）に正規化しています。ツールパネルでの Grok インストールは xAI 公式インストーラー（`x.ai/cli/install.sh` / `install.ps1`）を優先し、npm パッケージ `@xai-official/grok` をフォールバックにします。ネイティブと確認されたインストールは `grok update` で自己更新し、npm インストールは npm 経由の更新を維持——自己更新はネイティブ検出が確定した場合にのみ動くため、別種のインストールを壊すことはありません。4 言語の UI 文言も同期済みです。（[#5453](https://github.com/farion1231/cc-switch/pull/5453)） + +### Grok 公式ログイン：検出・インポート・保護 + +新しい「Grok 公式」プロバイダーエントリは、Grok CLI 内蔵の xAI OAuth ログインに対応します。選択すると接続フィールドが隠れ、空の `~/.grok/config.toml` を書き込みます。CC Switch が公式認証情報を保存したり触れたりすることはありません。live 設定の読み取り・バックアップ・公式状態の書き込みは構文レベルのみの TOML 検証に変更され、公式ログイン状態（空の設定）が正常に往復します。Grok が公式ログイン状態のときに「live 設定からインポート」すると、エラーではなく「Grok 公式を現在のプロバイダーに設定しました」となり、Codex と同じ挙動になります。公式状態の検出は意図的に手動インポートコマンドだけに配線されています——起動時の自動インポートは公式状態の設定を引き続き拒否するため、削除した「Grok 公式」エントリが次回起動時に復活することはありません。公式ログイン設定へのプロキシテイクオーバーは自動的にスキップされ、手動操作でも明確に拒否されます。既存の「公式プロバイダーはプロキシしない」方針と一貫しています。 + +### xAI Grok アカウントでサインイン：Claude Code と Claude Desktop + +Claude Code と Claude Desktop に「xAI (Grok)」プリセットが加わり、API key の代わりに OAuth デバイスコードログインを使います。リクエストはローカルプロキシを通り、Anthropic Messages → xAI Responses API の変換とリクエストごとのアクセストークン注入が行われます。既定モデルは全 tier で `grok-4.5` です（Claude Desktop プリセットは `claude-*` 形式のロール ID を上流の `grok-4.5` にマッピングし、Desktop のサードパーティモデル検証を通過させます）。 + +「設定 → OAuth 認証センター」に xAI セクションが追加されました。デバイスコードログイン（コピー可能なユーザーコード、確認リンク、待機 / キャンセル / 再試行）、複数アカウントと既定アカウントの選択、アカウント別の削除、再認証バッジ——refresh token が失効したアカウントは消えるのではなく「期限切れ」として表示され続け、認証状態は 15 秒ごとに再取得されるため、サーバー側の失効も自然に表面化します。 + +連携の境界は固定されています。フォームの endpoint / 形式フィールドをどう変えても上流は常に `https://api.x.ai/v1/responses`（Responses 形式）。OAuth endpoint は OIDC discovery で解決しますが https の `auth.x.ai` のみに厳格検証。refresh token は `~/.cc-switch/xai_oauth_auth.json`（Unix ではパーミッション `0600`、access token はメモリのみ）。OAuth のエラーボディはエラーメッセージにもログにも決して入りません。`grok-4.5` の価格（100 万 token あたり入力 $2 / 出力 $6 / キャッシュ読み取り $0.50）も登録され、使用量が $0 と記録されなくなります。既存データベースは次回起動時に自動で行を取り込みます。4 言語対応。利用前に「リスク通知」のクライアント識別情報の開示をお読みください。 + +OAuth を使わず、従量課金の xAI API key しかない場合でも、Claude Code へ接続できます。xAI の API endpoint は標準の Responses プロトコルなので、通常の Responses プロバイダーとして追加してください——カスタムプロバイダーに `https://api.x.ai/v1` と API key を設定し、上流形式に Responses を選ぶと、ローカルルーティングが Anthropic Messages ↔ Responses を変換します。[Claude Code で Codex 系プロバイダーを使う](../guides/claude-codex-routing-guide-zh.md)ガイドと同じ手順です。Codex 側には既製の API key プリセットがあります（次節参照）。 + +### Codex から xAI へ直結：管理下 OAuth と API Key ネイティブの 2 プリセット + +Codex には xAI へ直結する 2 つの道があります——Grok サブスクリプションなら管理下 OAuth、API key ならネイティブ直結です： + +- **「xAI (Grok) OAuth」管理下プリセット**：Codex を Grok サブスクリプションで動かします。フォームは key / endpoint / 形式フィールドを隠してアカウント選択を表示し、「モデルを取得」はサインイン済みアカウントで実行。プロバイダーはネイティブ Responses に固定され、base URL とリクエストごとのトークンはプロキシが強制します——編集しても無視されるため、管理下ルートを別の宛先へ向けることはできません。codex 0.142+ は ChatGPT バックエンド固有のリクエスト形を発します（`type:"namespace"` ツール宣言は xAI の厳格パーサーで即 422。ほかに `prompt_cache_retention`、`safety_identifier`、`external_web_access`、`additional_tools` キャリア、grok-4.5 が対応しないサンプリングパラメータ）。そのため OAuth ルートはネイティブパススルーの上に互換レイヤーを重ねます。namespace ツールはトップレベルの function ツールへ平坦化（Chat 経路と同じ sha256 切り詰め命名）し、レスポンス側ではストリーミング・非ストリーミングの両方で namespace 形へ復元、未対応フィールドは除去——すべて決定的なフィールド削除 / 構造変換であり、意味的な書き換えは一切ないため、プロンプトキャッシュの前方一致は安定を保ちます。このレイヤーは xAI OAuth プロバイダー型だけにゲートされ、他のプロバイダーのトラフィックには触れません。 +- **「xAI (Grok)」API Key プリセット**：`api.x.ai/v1` のネイティブ Responses に直結し、500K コンテキストの `grok-4.5` カタログエントリを内蔵します。このプリセットには上記の xAI 専用互換変換は**適用されません**——codex 0.142+ の API key ユーザーは依然 xAI の厳格パーサーに当たる可能性があり、完全互換の道は OAuth プリセットです。 + +xAI OAuth のトークンエラーは再試行不能に分類されるため、failover が会話を別の Grok アカウントへ静かに移すことはありません。 + +### UI クラッシュの捕捉：エラーのディスク保存と再読み込み画面 + +React のエラーバウンダリが UI 全体（データベース復旧画面を含む）を包むようになりました。レンダラーがクラッシュすると、真っ白なウィンドウの代わりに「インターフェースでエラーが発生しました」カードと再読み込みボタンが表示され、グローバルの `error` / `unhandledrejection` ハンドラーがレンダラーのエラーをディスクへ永続化します——以前は JS クラッシュの証拠がディスクに一切残りませんでした。フロントエンドが書き出すログはすべて二層の秘密情報除去を通ります。構造化シリアライザーが機微なプロパティ名（`tokens` / `apiKeys` / `credentials` の変種を正規化して照合し、ネストされたオブジェクトを含む値全体を隠す）と値の形（トークン接頭辞、PEM ヘッダー、高エントロピーな不透明文字列）で除去し、次に唯一のテキスト出口の順序付き正規表現チェーンが URL クエリ値と認証情報、認証ヘッダーとスキーム、名前付きシークレットコンテナ（二重エンコードされた JSON も対象）をカバーします。文字列として届いた JSON は再パースして構造的に除去し、過大な構造化入力は切り詰めではなく全体を破棄します——切り詰められた JSON 文字列は弱いテキスト正規表現にフォールバックして漏えいの恐れがあるためです。設定のトグル名も実態に合わせて変更しました。「アプリ診断ログ」（cc-switch.log）と、プロキシの「リクエスト使用量を記録」（統計データベースであり、もともとテキストログではありません）です。4 言語同期。 + +### 「Codex 使用量を再構築」メンテナンス操作 + +使用量ダッシュボードのメンテナンスに「Codex 使用量を再構築」が加わりました。データベースをバックアップした後、`codex_session` ソースの明細行、対応する `_codex_session` 日次集計、Codex 同期カーソルだけを消去し、修正済みパーサーで全 rollout ファイルを最初から再インポートします——下記の二重計上バグで膨張したデータベースの復旧経路であり、親ログが復元された保留 fork ファイルの再試行経路でもあります。手動再構築は事前バックアップを書き込めない場合にハードフェイルします（自動移行版は警告のみ。アップグレード後にバックアップディレクトリ書き込み不能で起動がブロックされる方が悪い結果だからです）。バックアップ → リセット → 再インポートの全工程はセッション同期ロックを保持し、60 秒間隔のバックグラウンド同期が消去と交錯できません。完了時にはちょうど 1 回のフロントエンド更新通知を必ず送ります——再インポートが 0 行やエラーで終わった場合も含めて——のでダッシュボードがリセット前の数字のまま止まることはありません。カーソルの掃除はパスの形（`sessions` / `archived_sessions` セグメント配下の `rollout-{uuid}` ファイル名）だけで照合するため、旧 `CODEX_HOME` 配下に記録されたカーソルも掃除できます。4 言語同期。 + +### セッションインポートの可観測性：保留ファイルと重複疑い + +セッション同期の結果に `filesScanned`、`deferredFiles`、`suspectedDuplicates` が加わりました。`deferredFiles` は、親ログの欠落や親マーカーの矛盾がある fork rollout をカーソルを書かずに保留し、後の同期や手動再構築で再試行するものです——推測でインポートしません。`suspectedDuplicates` は、挿入後に各行を同一フィンガープリントの既存行と照合（`idx_request_logs_dedup_lookup_expr` 式インデックス経由）し、ヒットごとに警告を記録します。二重計上バグが将来再発しても、総量を静かに膨らませるのではなく、ログの中で自ら名乗り出ます。 + +### Kimi K3 のプリセットと内蔵価格 + +Codex / Hermes / OpenClaw / OpenCode の Kimi オープンプラットフォームプリセットに Kimi K3（1M コンテキストウィンドウ）を追加しました。K2.7 Code の後ろに追加したため、既存の既定モデルの挙動は変わりません。内蔵価格テーブルには `kimi-k3`（公式表示価格：100 万 token あたり入力 $3 / 出力 $15 / キャッシュ読み取り $0.30）と裸の `k3` エイリアスを追加——Kimi For Coding サブスクリプションはモデルを短縮 id `k3` で報告するため、これがないとどの価格行にも一致しません（既存の `hunyuan-hy3` / `hy3` ペアと同じ前例です）。既存データベースは次回起動時に両行を自動で取り込み、ユーザーが編集した価格には触れません。 + +### SudoCode.us が SudoCode.chat と並んで復活 + +たまたま「SudoCode」という名前を共有する無関係な 2 社が、別々のプリセットになりました。スポンサーは「SudoCode.chat」に改名し、以前その場で置き換えられていた「SudoCode.us」が元の endpoint・モデル・アイコンとともに復帰。Hermes の slug も区別され、追記型の `~/.hermes/config.yaml` の中で両者が共存できます。新しい Grok Build プリセットリストを含めると、SudoCode.chat は 7 アプリ、SudoCode.us は全 8 アプリに収録されています。 + +--- + +## 変更 + +### 診断ログ：再起動をまたいで保持、サイズローテーション、秘密情報は記録しない + +`cc-switch.log` は起動のたびに消去されなくなりました——クラッシュを説明できたはずのログが、アプリを開き直したときには消えていたのです。代わりに 20 MB でローテーションし、アーカイブを 4 つ保持します（上限約 100 MB。以前は単一ファイルが 1 GB まで膨張し得ました）。これまで無制限だった `crash.log` は 5 MB ローテーション・アーカイブ 2 つになり、チェック / ローテーション / 追記の一連の処理を 1 つのロックで包んで、並行 panic がアーカイブを失わないようにしました。 + +ログの永続化は、秘密情報の平文がそのまま露出リスクになることを意味します（ユーザーはこれらのファイルを公開 issue に添付します）。そこで同じ変更で、バックエンドのすべてのログ出口を洗浄しました。上流 URL は userinfo / query / fragment を取り除いた形でのみ記録（置換できる既知のシークレットがない場合は origin のみ。パスに認証情報が埋まっている可能性があるため）。リクエストとレスポンスのボディは一切記録せず、バイト数、短いハッシュ、または安全な分類（`sse` / `html` / `json-like` / `binary-or-encoded` など）に置き換え——変換デバッグに必要なシグナルは残り、中身は残りません。レスポンスヘッダーは許可リスト方式（リスト外は名前のみ記録）。現在使用中のシークレット値（API key、access token)は、それを含むあらゆる記録 URL から置換されます。MCP カスタムフィールドの値は省略。ログプラグインの登録は早められ（アップデーターや起動時の障害が診断可能に）、永続化されたログレベルはデータベースが開き次第適用され、障害時は Info へ安全側に倒れます。「診断ログを有効化」スイッチはフロントエンド発のログ書き込みも制御するようになりました。**アップグレード前の古いログファイルは遡って洗浄されません**——「アップグレード時の注意」を参照してください。 + +### プリセット選択：スポンサーをグループ化し、残りは名前順 + +プリセット選択の既定順序が 4 層になりました。公式が最初、次に主要パートナー、その後にスポンサープリセット（README のスポンサー表と同じ順序。プリセットファイルも物理的に並べ替えて揃えました）、最後に残りすべてをファイル順ではなく表示名のアルファベット順で並べます。複数の層に該当するエントリは最も早い層にだけ現れ、重複表示はありません。 + +### プリセットの「API Key を取得」リンクを更新 + +RunAPI、ClaudeCN、ZetaAPI、APINebula プリセットの key 申請リンクを、各社の現在の登録 / 紹介ページに更新しました（ClaudeCN はドメインも移転：claudecn.top → claudecn.ai）。紹介タグはこれらのリンクと README に限定され、公式サイトリンクと API endpoint には手を付けていません。 + +--- + +## 修正 + +### Codex fork / サブエージェントのリプレイ済み親履歴を新規使用量として計上しない（v3.17.0 の二重計上を根治） + +v3.17.0 の使用量膨張を修正します。Codex タスクの fork やコピーモードでのサブエージェント生成で、親会話の token 履歴が新規使用量として再計上されていました——1 日の使用量が数十億 token 跳ね上がる、親子でバイト単位に同一の行が並ぶ、空の fork が消費していない使用量を背負う、といった報告がありました。fork / サブエージェントの rollout ファイルは冒頭で親スレッドの履歴をリプレイします。旧パーサーは引き継ぎ境界をヒューリスティックに探していました（最初の `thread_settings_applied` イベント、オブジェクト形の `subagent` ソースマーカー）。親自身の設定変更がリプレイに現れると境界が早すぎる位置に落ち、現行の文字列形ソースマーカーはまったく認識されず、リプレイされた親履歴が丸ごとインポートされていました。新パーサーは明示的な親識別子だけを信頼します——子の `session_meta` の `forked_from_id` または `source.subagent.thread_spawn.parent_thread_id`。両者が矛盾する場合はファイルを保留します。スレッドの識別は rollout ファイル名の UUID に固定し、親 rollout 自身の fork 前 token カウント系列を読み込み、トークン署名の照合で子のリプレイ済みプレフィックスを取り除きます。リプレイイベントは累積ベースラインの復元にのみ使われ、行として挿入されることはありません。リプレイ履歴を持たないサブエージェントログは実使用量として計上されるようになり、実際のサブエージェント消費がリプレイ疑いとしてスキップされる逆方向の計上漏れも同時に修正しました。（[#5335](https://github.com/farion1231/cc-switch/issues/5335)、[#5433](https://github.com/farion1231/cc-switch/issues/5433)、[#5381](https://github.com/farion1231/cc-switch/issues/5381)） + +### プロキシ使用量記録を冪等に：レスポンス由来の安定キー + +終端の使用量イベントにメッセージ id がない場合（ローカルプロキシ経由の Codex `/responses` トラフィックでは通常）、重複排除キーはランダム UUID にフォールバックしていました——同じ上流レスポンスの再試行 / リプレイのたびに新しいキーが作られ、`INSERT OR REPLACE` が毎回新しい行を積み上げます。ある報告者のデータベースには同じ使用量の組み合わせが 2,078 回入っていました。パーサーはキーをレスポンスのエンベロープ自体から取るようになりました——Codex `response.completed` イベントの `response.id`（`response.created` の id は破棄）、Chat Completions の `chatcmpl` id、Gemini の `responseId`——スコープは `session:{app_type}:{provider_id}:{id}`。failover で同じレスポンスが別プロバイダーに再生された場合もプロバイダーごとに 1 回ずつ課金され、プロバイダー間で衝突しません（Claude は裸の `session:{id}` 形を維持し、プロキシ行はセッションログのインポートと収束し続けます）。エンベロープ id がまったくない場合のフォールバックは、ランダム UUID ではなくレスポンスの使用量セマンティクスに対する決定的 SHA-256 です——同一のリプレイが同じキーに衝突しなければ重複排除は成立しません。最終的なデータベース書き込みも、無条件の REPLACE から重複排除ウィンドウ内の「存在しなければ挿入」に変わりました。（[#5496](https://github.com/farion1231/cc-switch/issues/5496)） + +### 大量セッションインポート中に使用量ページが固まらない + +大きなインポートの実行中に使用量ページを開くと、UI 全体が固まることがありました。行を挿入するたびに更新通知が飛び、通知のたびにフロントエンドが約 10 個の使用量クエリをすべて再実行し、それらのクエリが、数十 MB の rollout ファイルを 1 行ずつ解析中のインポーターと唯一のデータベース接続を奪い合う——重複で膨張したデータベースでは三者が互いに増幅し合っていました。セッション同期は 1 パス完了ごとに 1 回だけ通知するようになり、すべてのセッションインポーターはシングルフライトロックの後ろで直列化され（手動の「今すぐ同期」は実行中のパスと競争せず、後ろに並びます）、ブロッキングな解析処理は専用のブロッキングスレッドへ移されて UI コマンドを駆動する非同期ランタイムを飢えさせなくなり、60 秒間隔のバックグラウンド実行は取りこぼし分をまとめて実行せずスキップします。 + +### codex 0.144.5+ が CC Switch 生成のモデルカタログで起動不能にならない + +codex ≥ 0.144.5 は外部モデルカタログを厳格に解析し、エントリに `supports_reasoning_summaries` がないとファイル全体を拒否します——Codex CLI もデスクトップアプリも起動できず、生成カタログを削除しても、プロバイダーを保存するたびに同じ形で再生成されるため解決しませんでした。根本原因は、CC Switch がカタログのテンプレートをマシン共有の `models_cache.json` から複製していることです。そのフィールド構成は最後に書き込んだ codex プロセス次第で、共存する旧版 codex が新パーサー必須のフィールドを持たない形でキャッシュを書き換え続けていました。生成カタログは、同梱の静的テンプレートからパーサー必須フィールドを補完するようになりました。補完は欠けている場合のみで（動的な値が常に優先）、「欠落 = パーサー既定値」のセマンティクスを保つべきオプションの能力フィールドは意図的に補完しません。 + +### Windows：プロバイダー切り替えでコンソールが一瞬表示されず、固まらない + +Windows でプロバイダーを切り替えたりテイクオーバーを切り替えたりすると、コンソールウィンドウが一瞬表示され、UI が最大約 2 秒固まっていました。原因は 3 つ、修正も 3 つです。`codex debug models --bundled` プローブは `cmd.exe` 経由で `codex.cmd` を起動しますが、GUI サブシステムのアプリではこれが独自のコンソールを生成します——子プロセスは `CREATE_NO_WINDOW` で作成するようにしました。モデルカタログのテンプレートは切り替えのたびに再生成されていました——初回の成功ロード後にプロセス全体でキャッシュし（失敗は再試行可能のままなので、初回プローブの失敗がキャッシュを汚しません）、Codex CLI の起動はアプリ実行ごとに最大 1 回になりました。`switch_provider` はメインスレッド上の同期コマンドでした——非同期化して実処理をブロッキングスレッドに移し、アプリ別の切り替えロックによる直列化は維持しています。フリーズ修正は全プラットフォームに効き、コンソール表示の修正は Windows 固有です。 + +### tool schema が null / 欠落 / union 型でも厳格上流に拒否されない + +Codex の組み込みツール（`codex_app__automation_update` など）は `parameters: null`（または `type: null`）を宣言しますが、DeepSeek のような厳格な OpenAI 互換上流はリクエスト全体を 400 で拒否し、プロキシ経由のツール利用セッションが死んでいました。Responses→Chat ブリッジはすべてのツールの parameters を `type:"object"` schema に正規化します。null または欠落（ネスト形の欠落を含む）は `{"type":"object","properties":{}}` に、object 以外の `type`（`type: null` を含む）はその場で `"object"` に修正、トップレベルの `oneOf` union schema にはルートの `type:"object"` を追加して分岐はそのまま保持します。同じ object 型の保証を Codex→Anthropic ツール経路の `input_schema` にも拡張しました。既存の `properties` / `required` を捨てることはありません。（[#4706](https://github.com/farion1231/cc-switch/pull/4706)、[#5315](https://github.com/farion1231/cc-switch/pull/5315)、#4705・#4783 を修正） + +### 推論モデルがマルチターンの Codex Chat 会話で思考を失わない + +推論モデル（kimi-k2-thinking など）をプロキシの Responses→Chat ブリッジで使うと、マルチターン履歴が思考を壊していました。各ターンの `reasoning` 項目が**前の**アシスタントメッセージの末尾に貼り付けられ、直後のアシスタントターンに `reasoning_content` がなくなる——モデルが会話の途中で目に見えて壊れていました。Responses のセマンティクスでは reasoning は属するメッセージの**前**に置かれます。ブリッジは reasoning を、その後に続くアシスタントメッセージまたはツール呼び出しへ前方アタッチするようになりました。本物の末尾 reasoning だけが、確定した末尾（入力の終端、またはユーザーメッセージのようなターン境界——以前はここで静かに破棄されていました）で後方アタッチされ、既に埋め込まれた reasoning があれば追記します。保留中の reasoning は境界で必ず消費されるため、ユーザーターンを越えて後のアシスタントメッセージへ漏れることはありません。（[#5508](https://github.com/farion1231/cc-switch/pull/5508)） + +### ストリーミング並列ツール呼び出しの ID と順序を保持 + +Chat→Responses ストリーミングブリッジの 2 つのバグが、チャンクをまたいで識別子が分割される上流からの並列ツール呼び出しを壊していました。空の `id` を持つ継続デルタが本物の `call_id` を上書きし（Codex クライアントは `call_id:""` を見てツール結果を呼び出しに対応付けられません）、ツール呼び出しは個別に準備でき次第送出されていたため、名前が先に届いた後方インデックスが前方インデックスを追い越し、並列呼び出しの順序が入れ替わっていました。空の id は無視されるようになり、送出は連続インデックスゲートを通って Chat の `index` 順で厳密に解放され、まだ識別されていない前方インデックスを待ちます。ストリーム途中で偽の call id を合成することはありません（ストリーム終端の最終手段としてのみ。そこでも名前のない呼び出しは防御的にスキップし、疎なインデックスはそのまま送出します）。（[#5310](https://github.com/farion1231/cc-switch/pull/5310)） + +### 管理下 OAuth プロバイダーを確実に「ローカルルーティング必要」と表示 + +「ルーティング必要」バッジと切り替え時の警告は、プロバイダーの API 形式から導出されていました。管理下 OAuth プロバイダー（Copilot、Codex OAuth、xAI）にとってこれは誤ったシグナルです——認証情報は上流形式に関係なくプロキシが注入するため、ネイティブ形式の管理下プロバイダーは警告を受けず、テイクオーバーなしで静かに失敗していました。ルーティングの要否は単一の共有述語で決まるようになりました。公式プロバイダーは決してルーティングを必要とせず、管理下 OAuth プロバイダーは常に必要とし、形式ベースのルールは残りのケースにのみ適用されます。切り替え時のゲートもアプリごとに正しい準備状態を確認します。ほとんどのアプリはアプリ別テイクオーバー状態（旧ゲートはグローバルなプロキシ実行フラグだけを見ており、「プロキシは動いているが当該アプリはテイクオーバーされていない」を見逃していました）、Claude Desktop は引き続きプロキシプロセス自体を監視します——バックエンドのテイクオーバー状態に Claude Desktop のフィールドがないため、一律のアプリ別ゲートでは Desktop が永遠に警告を出し続けます。Claude Desktop のプロバイダーフォームは、xAI だけでなくすべての管理下 OAuth 型でプロキシモードを強制し、モデルマッピングトグルをロックします。4 言語同期。 + +### Node が nvm / fnm / mise にある場合でもツール更新が動く + +アンカー付き npm の更新・修復コマンドは npm を絶対パスで呼び出しますが、npm のランチャーは `#!/usr/bin/env node` shebang で PATH から `node` を解決します——GUI 起動のアプリはシステム PATH しか継承せず、バージョンマネージャーのディレクトリを含まないため、nvm / fnm / mise でインストールしたツールの更新は静かに失敗していました。すべてのアンカー付き npm 呼び出しは、npm 自身の隣にある `bin` ディレクトリを PATH の先頭に追加するようになり、npm とその shebang が同じ Node インストールを解決します。Codex の自己修復（アンインストール + 再インストール）経路もカバーしています。 + +### 削除した既定 Skill リポジトリが復活しない + +既定の Skill リポジトリは、起動のたびに「欠けている既定を補充」する処理で再シードされ、削除した既定リポジトリが次回起動時に静かに戻っていました。シードはデータベースごとに 1 回だけになり、設定フラグで記録されます。アップグレード時に既にリポジトリを持つデータベースは再シードなしでフラグが立つため、既存の選択には触れません。（[#5356](https://github.com/farion1231/cc-switch/pull/5356)） + +### トレイの初回言語がシステムロケールに従う + +設定でまだ言語を選んでいない場合、トレイメニューは簡体字中国語に固定されていました——英語 / 日本語 / 繁体字中国語のシステムでは、メイン UI は正しく OS ロケールに従うのにトレイだけが食い違い、ユーザーが一度言語を切り替えるまで続いていました。トレイはフロントエンドと同じ優先順位で OS ロケールから初回言語を導出するようになりました（`zh-TW` / `zh-HK` / `zh-Hant` → 繁体字中国語を含む）。明示的に選んだ言語が常に優先され、ロケールを読めない場合は従来どおり中国語へフォールバックします。（[#4355](https://github.com/farion1231/cc-switch/pull/4355)） + +### インポート失敗時に実際のエラーを表示しリストを更新 + +「live 設定からインポート」が失敗するたびに空のエラートーストが出ていました。Tauri の `invoke` はバックエンドのエラー**文字列**で reject するのに、ハンドラーがその上の `.message` を読んでいたためです。バックエンドの実際のメッセージを表示するようになり（ローカライズされた汎用フォールバック付き）、失敗時にもプロバイダーリストを更新するため、エラー前にコミットされた副作用がすぐ見えます。 + +### OpenClaw プリセットのモデルコストを公式表示価格に修正 + +OpenClaw プリセットの 15 エントリが、誤った単位や未換算の通貨でコスト値を持っていました——`cost` フィールドは 100 万 token あたりの USD ですが、たとえば `glm-5.1` は `0.001/0.001`（約 1000 分の 1 に過小評価され、使用量のコストがほぼ 0 と表示）、`deepseek-v4-pro` は未換算の人民元値（過大評価）でした。全エントリを $/M の公式表示価格に修正。サブスクリプションプランや無料 tier の endpoint も意図的に表示価格を示し、プランユーザーが自分の使用量の標準価値を見られるようにしています。今後プリセットから作成するプロバイダーには修正値が入り、作成済みのプロバイダーは作成時の設定を保持します。 + +### UI の小さな修正 + +- **AiHubMix アイコン**：Codex アプリの AiHubMix プリセットだけがブランドアイコンのフィールドを欠き、汎用アイコンで表示されていました。他のアプリと揃いました。 +- **欠落していた 2 つのロケールキーを補完**：Codex の「Anthropic Messages 形式のためルーティングが必要」トーストの理由部分が、ローカライズ済みの文の中で中国語のまま表示されていました（`proxyReasonAnthropicMessages` がどの言語ファイルにも存在しなかったため）。プロバイダーフォームの key 状態読み込みラベルも 4 月からハードコードの既定値のみでした。両方とも zh / en / ja / zh-TW に揃いました。 + +--- + +## ドキュメント + +### Codex ↔ Claude 双方向ルーティングガイド + +「Codex クライアントで Claude モデルを使う」「Claude Code クライアントで Responses プロバイダーを使う」の両方向が、2 つの新ガイドで揃いました： + +- **[Codex で Claude を使う](../guides/codex-claude-routing-guide-ja.md)**（中 / 英 / 日 3 言語、スクリーンショット付き）：v3.17.0 のネイティブ Anthropic Messages 上流と組み合わせ、Claude 系の `/v1/messages` ゲートウェイへ Codex を接続します。v3.17.0 のリリースノートからもリンクされています。 +- **[Claude Code で Codex 系プロバイダーを使う](../guides/claude-codex-routing-guide-zh.md)**（中国語、スクリーンショット付き）：Responses を話すプロバイダー（ゲートウェイの API key、または ChatGPT サブスクリプションの Codex サービス）で Claude Code を動かします——Claude Code は常にローカルの `/v1/messages` ルートへ Anthropic Messages を話し、プロキシが各リクエストを上流の Responses プロトコルへ変換します。 + +### README のスポンサー欄を更新 + +SubRouter が 4 言語 README のスポンサー表に加わりました。ピン留めの Kimi スポンサー文言は K3 に更新され、バナーは Moonshot CDN から配信されます。RunAPI の特典文言も更新し、スポンサー行の順序をアプリ内プリセット順に揃えました。 + +--- + +## アップグレード時の注意 + +### データベース自動移行と Codex 使用量の一回限りの再構築 + +v3.17.0 からのアップグレードでは、3 つの schema 移行（v13 → v16）が連続実行されます。v14 は Grok Build を受け入れるために `proxy_config` テーブルを再構築（既存のアプリ別プロキシ設定はすべて引き継ぎ、`grokbuild` 行を追加）。v15 は MCP サーバーテーブルと Skills テーブルに Grok Build 有効化列を追加。v16 は一回限りの Codex 使用量自動再構築をトリガーします——データベースをまず `backups/` 配下へバックアップし、`codex_session` データとカーソルをリセットし、その後通常の起動時同期が修正済みパーサーですべてを再インポートします。一般的なデータ量なら数秒。実測で最も重いデータセット（rollout ファイル 1,801 個 / 1.5 GB）は約 65 秒でした。以後の起動は従来どおり増分です。旧バージョンへ戻す可能性がある場合は、先に `~/.cc-switch/cc-switch.db` を自分でバックアップしてください。 + +**初回起動時の注意**：履歴の修復は**段階的に**完了します——再構築は起動時同期と共にバックグラウンドで進み、その間、使用量ダッシュボードの Codex 履歴の数字はいったんゼロになり、その後少しずつ埋め戻されます。これは想定どおりの動作で、データ損失ではありません。再構築後の合計は通常、アップグレード前より**小さく**なります。二重計上で膨らんでいた分が絞り出され、残ったものが実際の使用量です。 + +### 再構築の境界 + +- 再構築は rollout JSONL ファイルから使用量を再計算するため、**ソースログが既に削除された履歴は復元できません**。 +- 親 rollout が欠けている fork ファイルは、推測でインポートせず保留として報告されます。親ログを復元してから「Codex 使用量を再構築」を実行すると取り込めます。 +- 過去のプロキシソースの重複行は恒久的に残ります——移行が再構築するのはセッションソースのデータだけで、過去のプロキシ膨張を掃除する処理は存在しません。冪等ロガーが保証するのは、今後新しい重複が生まれないことだけです。 + +### 古いログファイルは遡って洗浄されません + +本リリースから診断ログは起動時に消去されず、再起動をまたいで保持されます（ローテーション済みランタイムログ最大約 100 MB、クラッシュログ約 15 MB）。**旧バージョンが書き込んだログファイルは遡って洗浄されず**、API key、トークン、認証情報付き URL を含む可能性があります——公開の場で共有する前に、アップグレード前のログを確認してください。 + +### Grok Build のインストールは公式インストーラースクリプトを使用 + +Grok Build のインストール・再インストールは xAI 公式インストーラーを優先し、インストール時に `x.ai/cli/install.sh`（Windows では `install.ps1`）を外部取得します。npm はフォールバックです。既存の npm インストールは引き続き npm 経由で更新されます。 + +### 内蔵価格の行を自動追加 + +新しい価格行（`grok-4.5`、`kimi-k3`、`k3`）は次回起動時に「存在しなければ挿入」で自動追加されます。ユーザーが編集した価格行が上書きされることはありません。 + +--- + +## リスク通知 + +### xAI Grok OAuth サインイン（本リリース新規——必ずお読みください） + +本リリースの xAI Grok OAuth 連携は、**公式 Grok CLI 用に登録された公開 OAuth クライアント識別情報とスコープを再利用します**（`client_id b1a00492-073a-47ea-816f-4c329264a828`、scope に `grok-cli:access` を含む）。CC Switch 自身が登録したアプリケーション識別情報ではありません。xAI がこの利用方法を認めない可能性があり、**アカウントの制限や停止につながる恐れがあります——自己責任でご利用ください**。この機能は完全にオプトインです。xAI プロバイダーを追加しなければ、何も変わりません。初回ログイン時に `~/.cc-switch/xai_oauth_auth.json` を作成し（refresh token のみ保存、Unix ではパーミッション `0600`、access token はメモリのみ）、設定済みのアウトバウンドプロキシ経由で `auth.x.ai` と `api.x.ai` へ接続します。ローカルのコールバックポートはありません。 + +### 引き続き適用されるリバースプロキシ系の注意 + +**Codex OAuth リバースプロキシ**：ChatGPT サブスクリプションの Codex OAuth をリバースプロキシ経由で使用すると、OpenAI の利用規約に違反する可能性があります。詳細は [v3.13.0 release notes](v3.13.0-ja.md#️-リスクに関する注意事項) を参照してください。 + +**サードパーティプロバイダーのルーティング**：CC Switch ローカルプロキシで Codex、Claude Desktop、Grok Build のリクエストを変換してサードパーティプロバイダーへ転送する場合、課金・コンプライアンス・データ保持に関する制約はプロバイダーごとに異なります。利用前に対象プロバイダーの利用規約を確認してください。 + +上記機能を有効化したユーザーは、関連するリスクを自ら負うものとします。CC Switch は、これらの機能の利用によって発生したアカウント制限、警告、サービス停止について責任を負いません。 + +--- + +## 謝辞 + +v3.18.0 で機能と修正を届けてくださった以下のコントリビューターに感謝します： + +- [#5453](https://github.com/farion1231/cc-switch/pull/5453)：Grok Build の第一級サポート（8 番目の管理対象アプリの中核実装）、@YUZHEthefool に感謝。 +- [#5508](https://github.com/farion1231/cc-switch/pull/5508)：Responses→Chat ブリッジの reasoning 前方アタッチ、@ka79376046 に感謝。 +- [#5310](https://github.com/farion1231/cc-switch/pull/5310)：ストリーミング並列ツール呼び出しの ID と順序の保持、@SaladDay に感謝。 +- [#5315](https://github.com/farion1231/cc-switch/pull/5315)：Codex ツール parameters の object schema への正規化、@Komikawayi に感謝。 +- [#4706](https://github.com/farion1231/cc-switch/pull/4706)：厳格な OpenAI 互換プロバイダー向けのツール型正規化、@Ryan2128 に感謝。 +- [#5356](https://github.com/farion1231/cc-switch/pull/5356)：削除した既定 Skill リポジトリの復活防止、@allenxu09 に感謝。 +- [#4355](https://github.com/farion1231/cc-switch/pull/4355)：トレイ初回言語のシステムロケール追従、@LaiYueTing に感謝。 +- [#5138](https://github.com/farion1231/cc-switch/pull/5138)：バックエンド CI の Linux / Windows / macOS 3 プラットフォーム展開、@zayokami に感謝。 + +Codex 使用量の異常、新しい codex の起動失敗、ツール呼び出しの問題を報告してくださったすべてのユーザーにも感謝します。本リリースの最も重要な修正は、こうした実際の利用場面からの再現情報をもとにしています。 + +--- + +## ダウンロードとインストール + +[Releases](https://github.com/farion1231/cc-switch/releases/latest) から、お使いのシステムに対応するビルドをダウンロードしてください。 + +### システム要件 + +| システム | 最低バージョン | アーキテクチャ | +| -------- | ------------------------ | ----------------------------------- | +| Windows | Windows 10 以降 | x64 / ARM64 | +| macOS | macOS 12 (Monterey) 以降 | Intel (x64) / Apple Silicon (arm64) | +| Linux | 下表を参照 | x64 / ARM64 | + +### Windows + +| ファイル | 説明 | +| ---------------------------------------- | -------------------------------------------- | +| `CC-Switch-v3.18.0-Windows.msi` | **推奨** - 自動更新対応の MSI インストーラー | +| `CC-Switch-v3.18.0-Windows-Portable.zip` | ポータブル版、展開してそのまま実行できます | + +Windows ARM64 デバイスでは、ファイル名に `arm64` が含まれる対応する成果物を選択してください。 + +### macOS + +| ファイル | 説明 | +| -------------------------------- | ------------------------------------------------------ | +| `CC-Switch-v3.18.0-macOS.dmg` | **推奨** - DMG インストーラー、Applications へドラッグ | +| `CC-Switch-v3.18.0-macOS.zip` | 展開して Applications へドラッグ、Universal Binary | +| `CC-Switch-v3.18.0-macOS.tar.gz` | Homebrew インストールと自動更新用 | + +Homebrew インストール： + +```bash +brew install --cask cc-switch +``` + +更新： + +```bash +brew upgrade --cask cc-switch +``` + +### Linux + +Linux アセットは **x86_64** と **ARM64**（`aarch64`）の両方を提供します。ファイル名のアーキテクチャ識別子を、マシンの `uname -m` 出力に合わせて選択してください： + +- `CC-Switch-v3.18.0-Linux-x86_64.AppImage` / `.deb` / `.rpm` +- `CC-Switch-v3.18.0-Linux-arm64.AppImage` / `.deb` / `.rpm` + +| ディストリビューション | 推奨形式 | インストール方法 | +| --------------------------------------- | ----------- | -------------------------------------------------------------------------- | +| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb` | `sudo dpkg -i CC-Switch-*.deb` または `sudo apt install ./CC-Switch-*.deb` | +| Fedora / RHEL / CentOS / Rocky Linux | `.rpm` | `sudo rpm -i CC-Switch-*.rpm` または `sudo dnf install ./CC-Switch-*.rpm` | +| openSUSE | `.rpm` | `sudo zypper install ./CC-Switch-*.rpm` | +| Arch Linux / Manjaro | `.AppImage` | 実行権限を付与して直接実行、または AUR を利用 | +| その他 / 不明な場合 | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` | diff --git a/docs/release-notes/v3.18.0-zh.md b/docs/release-notes/v3.18.0-zh.md new file mode 100644 index 000000000..6b7d706e4 --- /dev/null +++ b/docs/release-notes/v3.18.0-zh.md @@ -0,0 +1,331 @@ +# CC Switch v3.18.0 + +> 这一版你可以做两件全新的事：**把 xAI 的 Grok CLI（Grok Build）交给 CC Switch 管理**——它成为第八个受管应用，供应商一键切换、MCP / Skills 同步、代理接管与用量统计一应俱全；以及**把 Grok 接进 Claude Code、Claude Desktop 和 Codex**——既可以直接用 xAI Grok 账号登录（设备码授权、无需 API Key，跑你的 Grok 订阅，Codex 侧自带严格网关兼容层，codex 0.142+ 也能跑通），也可以用 xAI API Key 接入（Codex 有原生 Responses 直连预设，Claude Code 可走本地路由）。同样重要的是一波修复：v3.17.0 引入的 **Codex 用量双计已修**，升级后自动重建数据，看板数字恢复真实；**codex 0.144.5+ 因模型目录无法启动的问题已修**；Windows 上切换供应商不再闪黑窗、不再卡住界面。诊断日志也从「每次启动清空」变为跨重启持久保留、按大小轮转、全面脱敏，界面崩溃会落盘留证而不再只剩一片白屏。 + +**[English →](v3.18.0-en.md) | [日本語版 →](v3.18.0-ja.md)** + +--- + +## 重点内容：你现在可以 + +- **管理 Grok Build（xAI 的 Grok CLI）**：像管理 Claude Code / Codex 一样添加、导入、一键切换 Grok Build 的供应商；MCP 服务器与 Skills 双向同步、提示词首启自动导入、会话管理与用量看板全覆盖；还可以走本地代理接管，获得独立的路由、failover 与计费。 +- **把 Grok 接进 Claude Code / Claude Desktop / Codex——账号登录与 API Key 双路径**：订阅用户在「设置 → OAuth 授权中心」用设备码完成 xAI 账号登录（支持多账号），三个客户端直接跑你的 Grok 订阅、全程无需 API Key；按量付费用户则用 xAI API Key 接入——Codex 有现成的「xAI (Grok)」预设原生直连 `api.x.ai`，Claude Code 可按本版新攻略走本地路由接入。默认模型均为 `grok-4.5`。 +- **把 Codex 的用量数字修回真实值**：v3.17.0 的 fork / 子代理双计问题已在解析器层根治；升级后首次启动自动备份并重建 Codex 用量，用量页里也新增了手动「重建 Codex 用量」按钮。注意首次启动时历史记录是**逐渐**修复的——看板数字先变少、再随后台重导逐步回填，属预期行为（见「升级提醒」）。 +- **放心升级 codex CLI**：codex 0.144.5 起严格解析模型目录导致的「无法启动」已修复，生成目录会自动补齐解析器必需字段。 +- **在 Windows 上顺滑切换**：切换供应商 / 开关接管不再闪过黑色控制台窗口，也不再卡住界面约 2 秒（卡顿修复对全平台生效）。 +- **更放心地排查与分享日志**：诊断日志跨重启保留（20 MB × 4 轮转）、所有出口统一脱敏——URL 凭据、请求响应体、敏感请求头都不会再落盘；界面崩溃有错误卡片和重载按钮，错误详情写入磁盘。 +- **多轮重推理、并行工具调用不再翻车**：Responses↔Chat 桥修复了推理内容错挂、并行工具调用 ID 丢失 / 乱序、工具 schema 为 null 被严格上游整单拒绝三类问题。 +- **用上 Kimi K3**：Codex / Hermes / OpenClaw / OpenCode 的 Kimi 开放平台预设加入 K3（1M 上下文），内置定价同步入库，用量不再显示 $0。 + +--- + +## 使用攻略 + +本版新能力主要落在供应商预设、「设置 → OAuth 授权中心」与用量看板里，建议结合以下文档了解： + +- **[xAI Grok 账号登录（设置 → OAuth 授权中心）](../user-manual/zh/1-getting-started/1.5-settings.md)**：设备码登录流程、多账号管理与集成边界说明；使用前请先阅读下方「风险提示」中的客户端身份披露。 +- **[在 Claude Code 中使用 Codex 类供应商（本地路由攻略）](../guides/claude-codex-routing-guide-zh.md)**：本版新增的中文分步攻略。Claude Code 始终对本地 `/v1/messages` 路由说 Anthropic Messages 协议，由本地代理把每个请求转换成上游的 Responses 协议——网关 API Key、xAI 这类原生 Responses 端点，或 ChatGPT 订阅的 Codex 服务都适用。 +- **[在 Codex 中用 Claude（本地路由攻略）](../guides/codex-claude-routing-guide-zh.md)**：本版新增的三语分步攻略，配合 v3.17.0 的「原生 Anthropic Messages 上游」功能，把 Codex 接到任何只提供 `/v1/messages` 的 Claude 系网关。 +- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：了解用量看板的数据来源与统计口径。本版修复用量双计并新增「重建 Codex 用量」维护操作。 + +--- + +> [!WARNING] +> +> ## 唯一官方渠道声明（请务必阅读） +> +> CC Switch 是**完全免费、开源**的桌面应用，**不会向用户收取任何费用**。请仅通过下列官方渠道获取本软件： +> +> | 类别 | 唯一官方 | +> | -------- | ------------------------------------------------------------------------------ | +> | 官网 | **[ccswitch.io](https://ccswitch.io)** | +> | 源码 | **[github.com/farion1231/cc-switch](https://github.com/farion1231/cc-switch)** | +> | 下载 | **[GitHub Releases](https://github.com/farion1231/cc-switch/releases)** | +> | 作者 | **[@farion1231](https://github.com/farion1231)** | +> | 举报山寨 | **[GitHub Issues](https://github.com/farion1231/cc-switch/issues)** | +> +> **任何向你收费、要求充值、或索取登录凭据的"CC Switch"网站或客户端均为假冒**。如果你被诱导支付了费用，请立即停止操作并通过 GitHub Issues 反馈。 + +--- + +## 概览 + +CC Switch v3.18.0 的两条主线都围绕 xAI Grok。第一条是 **Grok Build 加入受管应用**：xAI 的 Grok CLI（live 配置 `~/.grok/config.toml`）成为与 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes 并列的第八个受管应用——供应商添加 / 导入 / 一键切换、MCP 与 Skills 双向同步、深链导入、独立预设列表，以及带专属路由命名空间的代理接管；配套的「Grok 官方」条目支持官方登录态识别与导入，CC Switch 绝不触碰官方凭据。第二条是 **xAI Grok 账号 OAuth 登录**：设备码授权替代 API Key，本地代理逐请求注入访问令牌，Claude Code / Claude Desktop 侧完成 Anthropic Messages → xAI Responses 转换；Codex 侧则提供受管 OAuth 预设并自带兼容层——codex 0.142+ 发出的 ChatGPT 后端私有形态（namespace 工具声明、私有字段）会被确定性地展平与剥离，严格解析的 xAI 网关不再返回 422；API Key 用户则另有一条「xAI (Grok)」原生 Responses 直连预设，不经任何转换。 + +围绕正确性，本版集中修复了 **v3.17.0 的 Codex 用量双计**：fork / 子代理日志开头对父线程历史的重放不再被当作新用量导入（解析器改为只认显式父身份 + 令牌签名对齐），升级后自动执行一次性用量重建（schema v16），用量页新增手动重建按钮；代理侧用量记录改为幂等（同一响应重放不再堆叠重复行），大量会话导入时用量页不再卡死。**Codex 转换层**另有四处修复：工具 schema 归一为 object 类型、推理内容跨轮前向附挂、流式并行工具调用保 ID 保序、生成的模型目录补齐 codex 0.144.5+ 必需字段。诊断体系也走向成熟：日志跨重启持久、按大小轮转、所有出口脱敏，界面崩溃被错误边界捕获并落盘。此外还有 Kimi K3 预设与定价、OpenClaw 预设成本修正、SudoCode.us 回归、托盘首启语言跟随系统等一批改进。 + +**发布日期**：2026-07-21 + +**更新规模**：52 commits | 217 files changed | +21,452 / -6,285 lines + +--- + +## 新功能 + +### Grok Build：第八个受管应用 + +xAI 的 Grok CLI（Grok Build，live 配置 `~/.grok/config.toml`）现在是 CC Switch 的一等公民：供应商添加 / 导入 / 一键切换（切换后提示重启 Grok Build 生效）、应用显隐与配置目录覆盖设置、会话管理与用量看板覆盖、提示词首启自动导入、`ccswitch://` 深链导入供应商，以及本地代理接管——拥有专属的 `/grokbuild/v1/responses` 路由命名空间、独立的 failover 队列与按应用代理设置；转发复用 Codex 的 Responses 通路，但绝不与 Codex 共享供应商命名空间或熔断状态。 + +MCP 服务器与 Grok 的 `[mcp_servers]` 表双向同步，方言差异已被抹平：Grok 靠 `command` / `url` 推断传输类型且用 `headers` 字段，导出时会剥掉显式 `type` 并把 `http_headers` 重命名为 `headers`，导入时反向推断回来。Skills 也获得 Grok Build 启用开关。 + +预设方面刻意**没有**借用 Codex 列表（早期版本曾把国产直连供应商和 Codex 默认模型漏进 Grok 表单），而是独立整理了一份：只收录真正承载 Grok 模型的聚合与中转站，默认模型归一为 `grok-4.5`（命名空间路由站为 `x-ai/grok-4.5`）。工具面板安装 Grok 优先走 xAI 官方安装器（`x.ai/cli/install.sh` / `install.ps1`），npm 包 `@xai-official/grok` 作为兜底；被确认是原生安装的走 `grok update` 自更新，npm 安装保持 npm 锚定更新——自更新门控在「确定检测为原生」上，绝不会误伤另一种安装。四语界面文案同步就位。（[#5453](https://github.com/farion1231/cc-switch/pull/5453)） + +### Grok 官方登录：识别、导入与保护 + +新增「Grok 官方」供应商条目，对应 Grok CLI 自带的 xAI OAuth 登录：选中它会隐藏连接字段并写入一个空的 `~/.grok/config.toml`，CC Switch 从不存储、也从不触碰官方凭据。live 配置的读取、备份与官方态写入改用仅语法级的 TOML 校验，官方登录态（空配置）可以正常往返；Grok 处于官方登录态时「从 live 导入」会得到「已设 Grok 官方为当前」而不是报错，与 Codex 行为一致。官方态识别刻意只接线到手动导入命令——启动时的自动导入器仍会拒绝官方态配置，所以你删掉的「Grok 官方」条目绝不会在下次启动时复活。对官方登录配置的代理接管会被自动跳过，手动路径给出明确拒绝，与现有「不代理官方供应商」的策略一致。 + +### 用 xAI Grok 账号登录：Claude Code 与 Claude Desktop + +Claude Code 与 Claude Desktop 新增「xAI (Grok)」预设，用 OAuth 设备码登录代替 API Key：请求经本地代理完成 Anthropic Messages → xAI Responses API 转换并逐请求注入访问令牌，各档默认模型都是 `grok-4.5`（Claude Desktop 预设把 `claude-*` 形式的角色 ID 映射到上游 `grok-4.5`，以通过 Desktop 的第三方模型校验）。 + +「设置 → OAuth 授权中心」新增 xAI 区块：设备码登录（用户码带复制按钮、验证链接、等待 / 取消 / 重试）、多账号与默认账号选择、按账号移除、重授权徽标——刷新令牌被吊销的账号会以「已过期」状态保留可见而不是消失，授权状态每 15 秒自动刷新，服务端吊销会自己浮现出来。 + +集成边界是钉死的：无论表单里的端点 / 格式字段怎么改，上游始终是 `https://api.x.ai/v1/responses`（Responses 格式）；OAuth 端点经 OIDC 发现解析，但强制校验为 https 的 `auth.x.ai`；刷新令牌存于 `~/.cc-switch/xai_oauth_auth.json`（Unix 上 `0600`；访问令牌只存内存）；OAuth 错误响应体绝不进入错误信息或日志。`grok-4.5` 定价（$2 输入 / $6 输出 / $0.50 缓存读，每百万 token）同步入库，用量不再记 $0，存量数据库下次启动自动补行。四语文案同步。使用前请阅读「风险提示」中的客户端身份披露。 + +不用 OAuth、只有按量付费的 xAI API Key？同样能接进 Claude Code：xAI 的 API 端点就是标准 Responses 协议，把它当作一个普通的 Responses 供应商添加——自定义供应商填 `https://api.x.ai/v1` 与 API Key、上游格式选 Responses，经本地路由完成 Anthropic Messages ↔ Responses 转换，与〈[在 Claude Code 中使用 Codex 类供应商](../guides/claude-codex-routing-guide-zh.md)〉攻略是同一套玩法。Codex 侧则有现成的 API Key 预设，见下一节。 + +### Codex 直连 xAI：OAuth 受管与 API Key 原生双预设 + +Codex 获得两条直连 xAI 的路——有 Grok 订阅走 OAuth 受管，有 API Key 走原生直连： + +- **「xAI (Grok) OAuth」受管预设**：让 Codex 跑在 Grok 订阅上。表单隐藏密钥 / 端点 / 格式字段、显示账号选择器，「获取模型」用已登录账号发起；供应商被钉死为原生 Responses，base URL 与逐请求令牌由代理强制执行——改了也会被忽略，受管路由无法被重定向。由于 codex 0.142+ 会发出 ChatGPT 后端私有的请求形态（`type:"namespace"` 工具声明会让 xAI 严格解析器直接 422，另有 `prompt_cache_retention`、`safety_identifier`、`external_web_access`、`additional_tools` 载体字段和 grok-4.5 不支持的采样参数），OAuth 路由在原生透传上加了一层兼容层：namespace 工具被展平为顶层 function 工具（与 Chat 路径同款 sha256 截断命名）、响应侧流式与非流式都还原回 namespace 形态，不支持的字段被剥除——全部是确定性的字段删除 / 结构提升，绝无语义改写，prompt 缓存前缀保持稳定。兼容层只门控在 xAI OAuth 供应商类型上，任何其它供应商的流量都不受影响。 +- **「xAI (Grok)」API Key 预设**：直连 `api.x.ai/v1` 的原生 Responses，自带 500K 上下文的 `grok-4.5` 目录条目。该预设**不会**应用上述 xAI 专属兼容转换——codex 0.142+ 的 API Key 用户仍可能撞上 xAI 的严格解析器，OAuth 预设才是完全兼容的路径。 + +xAI OAuth 的令牌失败被归为不可重试错误，failover 绝不会把你的对话悄悄挪到另一个 Grok 账号上。 + +### 界面崩溃捕获：错误落盘与重载页 + +React 错误边界现在包住整个界面（包括数据库恢复界面）：渲染进程崩溃时显示「界面出错了」卡片和重载按钮，而不是一片白屏；全局 `error` / `unhandledrejection` 处理器把渲染端错误持久化到磁盘——此前一次 JS 崩溃在盘上零证据。前端写出的所有日志经过两层脱敏：结构化序列化器按敏感属性名（`tokens` / `apiKeys` / `credentials` 等变体归一匹配，整值含嵌套对象一起隐藏）与值形态（令牌前缀、PEM 头、高熵不透明串）脱敏，再经唯一文本出口的有序正则链覆盖 URL 查询值与凭据、认证头与 scheme、命名密钥容器（双重编码的 JSON 也覆盖）。字符串形态到达的 JSON 会被重新解析后做结构化脱敏；超大结构化输入整体丢弃而非截断——截断的 JSON 串会退化到较弱的文本正则，可能泄漏。设置里的开关文案也改为名副其实：「应用诊断日志」（cc-switch.log）与代理的「记录请求用量」（统计数据库，本来就不是文本日志）。四语同步。 + +### 「重建 Codex 用量」维护按钮 + +用量看板的维护区新增「重建 Codex 用量」：备份数据库后，只清除 `codex_session` 来源的明细行、对应的 `_codex_session` 日汇总与 Codex 同步游标，然后用修正后的解析器从头重导所有 rollout 文件——这是被下述双计 bug 污染的数据库的恢复路径，也是父日志恢复后延迟 fork 文件的重试路径。手动重建在备份写不出时会硬失败（自动迁移版只告警，因为在升级后因备份目录不可写而卡死启动是更糟的结局）；整个「备份 → 重置 → 重导」序列持有会话同步锁，60 秒后台同步无法与清除交错；完成时保证恰好发出一次前端刷新通知——包括重导为零行或失败的路径——看板绝不会停留在重置前的数字上。游标清理按路径形态匹配（`sessions` / `archived_sessions` 段下的 `rollout-{uuid}` 文件名），旧 `CODEX_HOME` 下记录的游标也能清到。四语同步。 + +### 会话导入可观测性：延迟文件与疑似重复 + +会话同步结果现在报告 `filesScanned`、`deferredFiles`——父日志缺失或父标记冲突的 fork rollout 会被搁置且不写游标，等后续同步或手动重建重试，而不是靠猜导入——以及 `suspectedDuplicates`：插入后逐行探测是否已存在同指纹行（走 `idx_request_logs_dedup_lookup_expr` 表达式索引），每次命中记一条警告。双计 bug 未来若复发，会在日志里自己喊出来，而不是无声地吹大总数。 + +### Kimi K3 预设与定价 + +Codex / Hermes / OpenClaw / OpenCode 的 Kimi 开放平台预设加入 Kimi K3（1M 上下文窗口），追加在 K2.7 Code 之后，现有默认模型行为不变。内置定价表新增 `kimi-k3`（官方牌价 $3 输入 / $15 输出 / $0.30 缓存读，每百万 token）与裸 `k3` 别名——Kimi For Coding 订阅上报的模型短 id 是 `k3`，否则匹配不到任何定价行（与现有 `hunyuan-hy3` / `hy3` 同款先例）。存量数据库下次启动自动补齐两行，不碰用户改过的定价。 + +### SudoCode.us 回归，与 SudoCode.chat 并存 + +两家恰好同名「SudoCode」的无关公司现在是两个独立预设：赞助商更名为「SudoCode.chat」，此前被原位替换掉的「SudoCode.us」带着原有端点、模型与图标回归，Hermes slug 也做了区分，两者可在累加式的 `~/.hermes/config.yaml` 中共存。算上新的 Grok Build 预设列表，SudoCode.chat 覆盖七个应用、SudoCode.us 覆盖全部八个。 + +--- + +## 变更 + +### 诊断日志：跨重启持久、按大小轮转、绝不记录密钥 + +`cc-switch.log` 不再在每次启动时被清空——过去能解释崩溃的日志，等应用重开时已经没了——改为 20 MB 轮转、保留 4 个归档（上限约 100 MB，对比过去单文件可膨胀到 1 GB）；此前无上限的 `crash.log` 改为 5 MB 轮转、保留 2 个归档，检查 / 轮转 / 追加序列在同一把锁下，并发 panic 不会丢归档。 + +日志持久化让明文密钥成为真实的暴露面（用户会把日志附到公开 issue 里），所以同一批改动里把后端所有日志出口都做了清洗：上游 URL 只记剥掉 userinfo / query / fragment 的形式（没有已知密钥可替换时只记 origin，因为凭据可能嵌在路径里）；请求与响应体一律不记——换成字节数、短哈希或安全分类（`sse` / `html` / `json-like` / `binary-or-encoded` 等），排查转换问题的信号还在、内容没了；响应头走白名单（名单外只记名字）；正在使用的密钥值（API Key、访问令牌）会从任何携带它的 URL 里被替换掉；MCP 自定义字段值一律省略。日志插件注册提前（更新器 / 启动期故障可诊断），持久化的日志级别在数据库打开后立即生效、故障时收敛到 Info，「启用诊断日志」开关现在也管前端发起的日志写入。**升级前的旧日志文件不会被追溯清洗**——见「升级提醒」。 + +### 预设选择器：赞助商分组，其余按名称排序 + +预设选择器的默认顺序改为四层：官方最前，其次首要合作伙伴，然后是赞助商预设（与 README 赞助商表同序，预设文件已物理重排对齐），最后所有其余预设按显示名字母序排列，不再按文件序。命中多层的条目只落在最早一层，不会重复出现。 + +### 预设「获取 API Key」链接更新 + +RunAPI、ClaudeCN、ZetaAPI、APINebula 预设的密钥申请链接更新为各家当前的注册 / 推荐页（ClaudeCN 同时迁移了域名：claudecn.top → claudecn.ai）。推荐标签仅限这些链接与 README——官网链接和 API 端点保持不动。 + +--- + +## 修复 + +### Codex fork / 子代理不再把重放的父历史当新用量（v3.17.0 双计根治） + +修复 v3.17.0 的用量膨胀：fork 一个 Codex 任务或以复制模式派生子代理时，父对话的 token 历史被当作新用量重复计入——有用户报告单日用量跳涨数十亿 token、父子行字节级相同、空 fork 背着从未消耗过的用量。fork / 子代理的 rollout 文件开头会重放父线程历史，旧解析器靠启发式找接管边界（第一个 `thread_settings_applied` 事件、对象形态的 `subagent` 来源标记）：父线程自己的设置变更出现在重放里时边界落得太早，而当前字符串形态的来源标记则完全识别不到，整段父历史被原样导入。新解析器只认显式父身份——子方 `session_meta` 上的 `forked_from_id` 或 `source.subagent.thread_spawn.parent_thread_id`，两者冲突时搁置该文件——线程身份锚定到 rollout 文件名 UUID，加载父 rollout 自己的 fork 前 token 计数序列，用令牌签名对齐剥掉子方的重放前缀：重放事件只用于恢复累计基线，绝不插行。不带重放历史的子代理日志现在按真实用量计入，反方向的漏计（真实子代理消耗被当作疑似重放跳过）同步修复。（[#5335](https://github.com/farion1231/cc-switch/issues/5335)、[#5433](https://github.com/farion1231/cc-switch/issues/5433)、[#5381](https://github.com/farion1231/cc-switch/issues/5381)） + +### 代理用量记录改为幂等：响应级稳定键 + +终态用量事件不带消息 id 时（经本地代理的 Codex `/responses` 流量是常态），去重键此前回退到随机 UUID——同一上游响应的每次重试 / 重放都造一个新键，`INSERT OR REPLACE` 每次都堆一行新的；有用户的数据库里同一用量组合出现了 2,078 次。解析器现在从响应信封本身取键——Codex `response.completed` 事件的 `response.id`（丢弃 `response.created` 的 id）、Chat Completions 的 `chatcmpl` id、Gemini 的 `responseId`——并按 `session:{app_type}:{provider_id}:{id}` 作用域化：failover 时同一响应打到不同供应商仍按供应商各记一次、互不碰撞（Claude 保持裸 `session:{id}` 形态，代理行继续与会话日志导入合流）。完全没有信封 id 时，兜底从响应的用量语义做确定性 SHA-256——相同重放必须撞进同一个键，去重才成立——最终写库也从无条件 REPLACE 改为去重窗口内的「不存在才插入」。（[#5496](https://github.com/farion1231/cc-switch/issues/5496)） + +### 大量会话导入时用量页不再卡死 + +导入大批会话时打开用量页可能整个卡住：每插入一行就发一次刷新通知，每次通知让前端重跑全部约 10 个用量查询，这些查询又与正在逐行解析几十 MB rollout 文件的导入器争抢唯一数据库连接——在被重复行吹大的数据库上三者互相放大。现在会话同步改为每轮完成只通知一次；所有会话导入器串行在单飞锁后（手动「立即同步」排队等待运行中的一轮，而不是与之竞争）；阻塞式解析挪到专用阻塞线程，不再饿死驱动界面命令的异步运行时；60 秒后台节拍错过就跳过，不再突发补跑。 + +### codex 0.144.5+ 不再因 CC Switch 生成的模型目录无法启动 + +codex ≥ 0.144.5 严格解析外部模型目录，条目缺 `supports_reasoning_summaries` 时整个文件被拒——Codex CLI 和桌面端都起不来，删掉生成目录也没用，因为任何一次供应商保存都会按同样方式重新生成。根因是 CC Switch 从机器共享的 `models_cache.json` 克隆目录模板，而它的字段集取决于最后写它的那个 codex 进程——共存的旧版 codex 一直在用缺字段的形态重写缓存。生成目录现在会从内置静态模板回填解析器必需字段，且只在缺失时回填（动态值永远优先）；「缺失即解析器默认值」的可选能力字段刻意不回填，语义必须保留。 + +### Windows：切换供应商不再闪黑窗、不再卡死 + +Windows 上切换供应商或开关接管会闪过一个控制台窗口、界面卡住约 2 秒。三个原因、三处修复：`codex debug models --bundled` 探测经 `cmd.exe` 启动 `codex.cmd`，GUI 子系统应用里这会弹出自己的控制台——子进程现在带 `CREATE_NO_WINDOW` 创建；模型目录模板此前每次切换都重新生成——现在首次成功加载后进程级缓存（失败保持可重试，坏的首次探测不会毒化缓存），Codex CLI 每次应用运行至多启动一次；`switch_provider` 此前是跑在主线程上的同步命令——现在异步化、真实工作在阻塞线程上，仍由按应用切换锁串行。卡顿修复对全平台生效，闪窗修复是 Windows 专属。 + +### 工具 schema 为 null / 缺失 / 联合类型不再被严格上游整单拒绝 + +Codex 内置工具（如 `codex_app__automation_update`）声明 `parameters: null`（或 `type: null`），DeepSeek 这类严格的 OpenAI 兼容上游会对整个请求返回 400，经代理路由的工具会话直接被杀。Responses→Chat 桥现在把每个工具的 parameters 归一为 `type:"object"` schema：null 或缺失（含嵌套形态的缺失）变为 `{"type":"object","properties":{}}`，非 object 的 `type`（含 `type: null`）原位纠正为 `"object"`，顶层 `oneOf` 联合 schema 补根 `type:"object"`、分支原样保留。同样的 object 类型保证扩展到了 Codex→Anthropic 工具路径的 `input_schema`。已有的 `properties` / `required` 绝不丢弃。（[#4706](https://github.com/farion1231/cc-switch/pull/4706)、[#5315](https://github.com/farion1231/cc-switch/pull/5315)，修复 #4705、#4783） + +### 推理模型在多轮 Codex Chat 对话中保住思考 + +推理模型（如 kimi-k2-thinking）走代理的 Responses→Chat 桥时，多轮历史会弄坏思考内容：每轮的 `reasoning` 条目被粘到**上一条**助手消息的尾巴上，紧随的助手轮反而没有 `reasoning_content`——模型会肉眼可见地中途断片。Responses 语义里推理位于它所属消息**之前**，桥现在把推理前向附挂到其后的助手消息或工具调用上；真正的尾部推理只在确凿的尾部（输入结束，或用户消息这样的轮次边界——此前在这里会被静默丢弃）向后附挂，并追加到已内嵌的推理之后；悬挂中的推理在边界处必被消费，绝不会跨过用户轮泄漏进后面的助手消息。（[#5508](https://github.com/farion1231/cc-switch/pull/5508)） + +### 流式并行工具调用保住 ID 与顺序 + +Chat→Responses 流式桥的两个 bug 会弄坏「身份分散在多个 chunk」的上游发来的并行工具调用：携带空 `id` 的续传增量会覆盖真实 `call_id`（Codex 客户端看到 `call_id:""`，工具结果对不上调用）；工具调用各自就绪就立即发出，名字先到的靠后索引能插到靠前索引前面——并行调用被重排。现在空 id 一律忽略；发射经过连续索引闸门，严格按 Chat `index` 顺序放行，未识别的靠前索引没就绪就等待；流中途绝不合成假 call id（只在流终结时作为最后手段，且防御性跳过无名调用、稀疏索引照常发出）。（[#5310](https://github.com/farion1231/cc-switch/pull/5310)） + +### 受管 OAuth 供应商可靠地标记为「需本地路由」 + +「需路由」徽标与切换时警告此前由供应商的 API 格式推导，对受管 OAuth 供应商（Copilot、Codex OAuth、xAI）这是错误信号——它们的凭据由代理注入、与上游格式无关，原生格式的受管供应商拿不到警告、不开接管就静默失败。路由需求现在由唯一共享谓词决定：官方供应商永不需要路由，受管 OAuth 供应商恒需要，格式规则只适用于其余情况。切换时的门槛也按应用查对了就绪信号：多数应用查按应用接管状态（旧门槛只看全局代理运行标志，漏掉「代理在跑但当前应用没被接管」），Claude Desktop 继续看代理进程本身——后端接管状态没有 Claude Desktop 字段，统一按应用查会让 Desktop 永远弹警告。Claude Desktop 供应商表单对所有受管 OAuth 类型强制代理模式并锁定模型映射开关，不再只对 xAI。四语同步。 + +### Node 装在 nvm / fnm / mise 里时工具更新可用 + +锚定的 npm 更新与修复命令按绝对路径调 npm，但 npm 启动器靠 `#!/usr/bin/env node` shebang 从 PATH 找 `node`——GUI 启动的应用只继承系统 PATH，不含版本管理器目录，nvm / fnm / mise 安装的工具更新静默失败。现在每个锚定 npm 调用都把 npm 自己的同级 `bin` 目录前置到 PATH，npm 与它的 shebang 解析到同一个 Node；Codex 自修复（卸载 + 重装）路径同样覆盖。 + +### 删除的默认 Skill 仓库不再复活 + +默认 Skill 仓库此前每次启动被「补齐缺失默认项」逻辑重新播种，删掉的默认仓库下次启动又静默回来。播种改为按数据库一次性，用设置标志记录；升级时已有仓库的数据库直接置标志、不再补种，现有选择不受影响。（[#5356](https://github.com/farion1231/cc-switch/pull/5356)） + +### 托盘首启语言跟随系统 + +设置里还没选过语言时，托盘菜单被硬编码为简体中文——英文 / 日文 / 繁中系统上主界面正确跟随系统语言、托盘却不一致，直到用户手动切一次语言。托盘现在按与前端相同的优先级从系统 locale 推导首启语言（含 `zh-TW` / `zh-HK` / `zh-Hant` → 繁体中文）；显式选择的语言永远优先，locale 读不到时照旧回落中文。（[#4355](https://github.com/farion1231/cc-switch/pull/4355)） + +### 导入失败显示真实错误并刷新列表 + +每次「从 live 配置导入」失败都弹一个空错误提示，因为 Tauri 的 `invoke` 以后端错误**字符串**拒绝，而处理器从它上面读 `.message`。现在显示后端真实报错（带本地化的通用兜底），失败时也会刷新供应商列表——报错前已提交的副作用立即可见。 + +### OpenClaw 预设模型成本修正为官方牌价 + +15 个 OpenClaw 预设条目的成本值单位错误或未换汇——`cost` 字段是美元每百万 token，例如 `glm-5.1` 记成 `0.001/0.001`（低估约 1000 倍，用量成本近乎 0），`deepseek-v4-pro` 则带着未换算的人民币值（高估）。所有条目改为官方牌价 $/M；订阅套餐与免费档端点也刻意展示牌价，套餐用户能看到自己用量的标准价值。今后从预设新建的供应商拿到修正值；已创建的供应商保持创建时的配置。 + +### 界面小修一组 + +- **AiHubMix 图标**：Codex 应用的 AiHubMix 预设此前缺品牌图标字段、渲染成通用图标，现与其它应用一致。 +- **两个缺失文案键补齐**：Codex「因使用 Anthropic Messages 格式需要路由」提示里的原因片段此前在非中文界面显示中文（`proxyReasonAnthropicMessages` 不存在于任何语言文件）；供应商表单的密钥状态加载标签自 4 月起只有硬编码默认值。两者已在 zh / en / ja / zh-TW 全部补齐。 + +--- + +## 文档 + +### Codex ↔ Claude 双向路由攻略 + +两篇新攻略把「Codex 客户端用 Claude 模型」「Claude Code 客户端用 Responses 供应商」补成了双向： + +- **[在 Codex 中用 Claude](../guides/codex-claude-routing-guide-zh.md)**（中 / 英 / 日三语，含截图）：配合 v3.17.0 的原生 Anthropic Messages 上游，把 Codex 接到 Claude 系 `/v1/messages` 网关；v3.17.0 的 release notes 已回链本攻略。 +- **[在 Claude Code 中使用 Codex 类供应商](../guides/claude-codex-routing-guide-zh.md)**（中文，含截图）：用 Responses 协议的供应商（网关 API Key，或 ChatGPT 订阅的 Codex 服务）驱动 Claude Code——Claude Code 始终对本地 `/v1/messages` 路由说 Anthropic Messages，由代理把每个请求转换成上游的 Responses 协议。 + +### README 赞助商更新 + +SubRouter 加入四语 README 赞助商表；置顶的 Kimi 赞助文案更新到 K3、横幅改由 Moonshot CDN 提供；RunAPI 权益文案刷新，赞助商行序与应用内预设顺序对齐。 + +--- + +## 升级提醒 + +### 数据库自动迁移与 Codex 用量一次性重建 + +从 v3.17.0 升级会连续执行三次 schema 迁移（v13 → v16）：v14 重建 `proxy_config` 表以纳入 Grok Build（现有按应用代理设置全部保留，并新增 `grokbuild` 行）；v15 给 MCP 服务器表与 Skills 表加 Grok Build 启用列；v16 触发一次性的 Codex 用量自动重建——数据库先备份到 `backups/` 下，`codex_session` 数据与游标被重置，随后正常的启动同步用修正后的解析器重导全部数据。典型数据量只需数秒；实测最重的数据集（1,801 个 rollout 文件 / 1.5 GB）约 65 秒。之后的启动照旧增量。若有回退旧版本的习惯，建议先自行备份 `~/.cc-switch/cc-switch.db`。 + +**首次启动时请留意**：历史记录的修复是**逐渐完成**的——重建随启动同步在后台进行，这段时间里用量看板的 Codex 历史数字会先清零、再逐步回填，属预期行为，不是数据丢失。重建完成后的总数通常会比升级前**更小**：被双计吹大的那部分被挤掉了，剩下的才是真实用量。 + +### 重建的边界 + +- 重建从 rollout JSONL 文件重新计算用量，**源日志已被删除的历史无法重建**。 +- 父 rollout 缺失的 fork 文件会被搁置并报告，而不是靠猜导入；恢复父日志后运行「重建 Codex 用量」可补导。 +- 历史上代理来源的重复行会永久保留——迁移只重建会话来源的数据，不存在针对过往代理膨胀的清理逻辑；幂等记录只保证从此不再产生新重复。 + +### 旧日志文件不会被追溯脱敏 + +诊断日志从本版起不再在启动时清空、跨重启持久保留（运行日志轮转上限约 100 MB，另有约 15 MB 崩溃日志）。**早期版本写下的日志文件不会被追溯清洗**，可能含有 API Key、令牌或带凭据的 URL——公开分享前请先检查升级前的旧日志。 + +### Grok Build 安装走官方安装脚本 + +安装或重装 Grok Build 现在优先使用 xAI 官方安装器，安装时会外联获取 `x.ai/cli/install.sh`（Windows 为 `install.ps1`），npm 作为兜底；已有的 npm 安装继续经 npm 更新。 + +### 内置定价自动补行 + +新定价行（`grok-4.5`、`kimi-k3`、`k3`）在下次启动时按「不存在才插入」自动追加；用户编辑过的定价行绝不被覆盖。 + +--- + +## 风险提示 + +### xAI Grok OAuth 登录（本版新增，请阅读） + +本版的 xAI Grok OAuth 集成**复用官方 Grok CLI 注册的公开 OAuth 客户端身份与权限范围**（`client_id b1a00492-073a-47ea-816f-4c329264a828`，scope 含 `grok-cli:access`），而不是 CC Switch 自己注册的应用身份。xAI 可能不支持这种用法，**使用可能导致账号被限制或封禁——风险自担**。该功能完全可选：不添加 xAI 供应商，一切照旧。首次登录会创建 `~/.cc-switch/xai_oauth_auth.json`（仅存刷新令牌，Unix 上权限 `0600`；访问令牌只存内存），并经你配置的出站代理访问 `auth.x.ai` 与 `api.x.ai`，无本地回调端口。 + +### 沿用的反向代理类提示 + +**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。 + +**第三方供应商路由**：通过 CC Switch 本地代理把 Codex、Claude Desktop 或 Grok Build 的请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。 + +用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。 + +--- + +## 致谢 + +感谢以下贡献者在 v3.18.0 中提交的功能与修复： + +- [#5453](https://github.com/farion1231/cc-switch/pull/5453)：Grok Build 一等公民支持（第八个受管应用的主体实现），感谢 @YUZHEthefool。 +- [#5508](https://github.com/farion1231/cc-switch/pull/5508)：Responses→Chat 桥推理内容前向附挂，感谢 @ka79376046。 +- [#5310](https://github.com/farion1231/cc-switch/pull/5310)：流式并行工具调用保 ID 保序，感谢 @SaladDay。 +- [#5315](https://github.com/farion1231/cc-switch/pull/5315)：Codex 工具 parameters 归一为 object schema，感谢 @Komikawayi。 +- [#4706](https://github.com/farion1231/cc-switch/pull/4706)：严格 OpenAI 兼容上游的工具类型归一，感谢 @Ryan2128。 +- [#5356](https://github.com/farion1231/cc-switch/pull/5356)：删除的默认 Skill 仓库不再复活，感谢 @allenxu09。 +- [#4355](https://github.com/farion1231/cc-switch/pull/4355)：托盘首启语言跟随系统 locale，感谢 @LaiYueTing。 +- [#5138](https://github.com/farion1231/cc-switch/pull/5138)：后端 CI 扩展到 Linux / Windows / macOS 三平台，感谢 @zayokami。 + +也感谢所有反馈 Codex 用量异常、codex 新版启动失败与工具调用问题的用户——本版最重要的几个修复都来自这些真实场景里的复现线索。 + +--- + +## 下载与安装 + +访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本。 + +### 系统要求 + +| 系统 | 最低版本 | 架构 | +| ------- | -------------------------- | ----------------------------------- | +| Windows | Windows 10 及以上 | x64 / ARM64 | +| macOS | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) | +| Linux | 见下表 | x64 / ARM64 | + +### Windows + +| 文件 | 说明 | +| ---------------------------------------- | ----------------------------------- | +| `CC-Switch-v3.18.0-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 | +| `CC-Switch-v3.18.0-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 | + +Windows ARM64 设备请选择文件名中带 `arm64` 标识的对应制品。 + +### macOS + +| 文件 | 说明 | +| -------------------------------- | --------------------------------------------- | +| `CC-Switch-v3.18.0-macOS.dmg` | **推荐** - DMG 安装包，拖入 Applications 即可 | +| `CC-Switch-v3.18.0-macOS.zip` | 解压后拖入 Applications，Universal Binary | +| `CC-Switch-v3.18.0-macOS.tar.gz` | 用于 Homebrew 安装和自动更新 | + +Homebrew 安装： + +```bash +brew install --cask cc-switch +``` + +更新： + +```bash +brew upgrade --cask cc-switch +``` + +### Linux + +Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本： + +- `CC-Switch-v3.18.0-Linux-x86_64.AppImage` / `.deb` / `.rpm` +- `CC-Switch-v3.18.0-Linux-arm64.AppImage` / `.deb` / `.rpm` + +| 发行版 | 推荐格式 | 安装方式 | +| --------------------------------------- | ----------- | ---------------------------------------------------------------------- | +| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb` | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` | +| Fedora / RHEL / CentOS / Rocky Linux | `.rpm` | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm` | +| openSUSE | `.rpm` | `sudo zypper install ./CC-Switch-*.rpm` | +| Arch Linux / Manjaro | `.AppImage` | 添加执行权限后直接运行，或使用 AUR | +| 其他发行版 / 不确定 | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage` |