mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-07-31 11:01:36 +08:00
Jason
354 lines
41 KiB
Markdown
354 lines
41 KiB
Markdown
# CC Switch v3.19.0
|
||
|
||
> 这一版的主线是**让你更放心**：一波集中式安全加固——Skill 安装、`ccswitch://` 导入确认、SQL 备份导入、通用配置合并、终端启动全部收紧，其中两条需要你花一分钟确认——Gemini 通用配置的密钥泄漏已修复并在升级后自动清洗（**需要你轮换密钥**），`ccswitch://` 的 MCP 导入确认框此前可能显示不出即将写入的命令（**若你曾打开过来源不明的导入链接，建议核对一次**），两条都见「升级提醒」；一个代理正确性大修——**通过代理读图不再撑爆上下文**（一张截图曾经吃掉 10 万+ token，两三张就能把 Codex 会话卡死在 400 上）。省心的部分同样实在：**模型定价可以交给 models.dev 自动维护**、Grok CLI 官方登录模式的用量与 SuperGrok 订阅余量终于进看板、**应用内更新改走 `dl.ccswitch.io` 镜像**——GitHub 访问不畅也能顺利升级。
|
||
|
||
**[English →](v3.19.0-en.md) | [日本語版 →](v3.19.0-ja.md)**
|
||
|
||
---
|
||
|
||
## 重点内容：你现在可以
|
||
|
||
- **在代理下正常读图，不再撑爆上下文**：Codex 的 `view_image`、返回图片的 MCP 工具，图片此前被序列化成工具文本、按纯文本计 token（约 9,000 倍膨胀）；现在所有转换桥都把图片还原为原生格式再上送（文件与音频在两条 Chat 桥上一并支持）。真实测试里同一回放轮从 85k+ token 降到约 12k、缓存命中 99%。
|
||
- **把模型定价交给 models.dev 自动维护**：用量面板新增「models.dev 自动定价同步」（默认关闭）。开启后启动时自动刷新所选模型的价格（每 6 小时至多一次），可在完整目录里挑选要跟踪的模型，或让它自动包含各家最新的常用模型。手工改价与删价从本版起会记入 `~/.cc-switch/model-pricing.json`，数据库重建也不丢。
|
||
- **看到 Grok 官方模式的用量与订阅余量**：Grok CLI 用官方 OAuth 登录时无法走本地代理，此前这部分消耗完全不可见；现在会从会话日志导入逐轮用量，看板里以「Grok Build (Session)」呈现。官方类 Grok Build 供应商卡片还会直接显示 SuperGrok 订阅的额度用量与重置时间。
|
||
- **更放心地点开 `ccswitch://` 导入链接**：确认框现在完整展示命令、每个参数、URL 与环境变量（凭据类值脱敏显示），高亮标记值得多看一眼的值——shell 内联执行、改变加载行为的环境变量、内网 / 元数据地址；用量查询脚本会显示完整代码，且**默认以禁用状态导入**。
|
||
- **确认 Gemini 供应商里不再夹带别人的密钥**：通用配置共享片段此前会把 `GOOGLE_API_KEY` 等凭据复制进每个使用它的 Gemini 供应商；本版关闭该路径，升级后首次启动自动执行一次性清洗。**凡是进过共享 Gemini 片段的密钥都应视为已暴露，请先轮换再重填**（见「升级提醒」）。
|
||
- **在 GitHub 访问不畅时照常更新应用**：应用内更新器优先查询 `https://dl.ccswitch.io/latest.json`（Cloudflare R2 镜像），GitHub 作为回落；minisign 签名校验不变，镜像本身不被信任。
|
||
- **新建供应商时直接用上最新模型**：预设默认模型升级为 Claude Opus 5、GPT-5.6 Sol 与 Gemini 3.6 Flash，配套定价同步入库；已创建的供应商保持原样。
|
||
- **更快导入 fork 密集的 Codex 用量历史**：父 rollout 文件只解析一次、跨全部 fork 点共享，fork 密集的历史重建明显提速，导入结果逐字节不变。
|
||
|
||
---
|
||
|
||
## 使用攻略
|
||
|
||
本版新能力主要落在用量面板与 `ccswitch://` 深链导入上，建议结合以下文档了解：
|
||
|
||
- **[用量统计](../user-manual/zh/4-proxy/4.4-usage.md)**：用量看板的数据来源与统计口径。本版新增 models.dev 自动定价同步与 Grok 官方模式用量导入。
|
||
- **[深链导入（ccswitch://）](../user-manual/zh/5-faq/5.3-deeplink.md)**：导入确认框的字段说明与 `usageEnabled` 等参数的默认值（本版起用量脚本默认禁用导入，文档已同步修正）。
|
||
- **[安全策略（SECURITY.md）](../../SECURITY.md)**：本版补齐了威胁模型与报告范围——哪些输入被视为不可信、哪些问题欢迎报告，一目了然。
|
||
|
||
---
|
||
|
||
> [!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.19.0 由一波安全加固与一个代理正确性大修领衔。安全侧（[#5811](https://github.com/farion1231/cc-switch/pull/5811) 及后续独立修复）：从 GitHub 仓库安装 Skill 加固了 zip-slip 与路径穿越并设归档上限；Gemini 通用配置的密钥泄漏被关闭，升级后首次启动自动执行一次性清洗，把已经泄漏进其它供应商配置的密钥清理干净；导入 SQL 备份改在 SQLite authorizer 下执行，`ATTACH` 等能触及导入库之外的语句一律拒绝；通用配置片段合并不再跟随 `__proto__` 污染全局原型；外部终端启动改用 POSIX 单引号转义，目录名再也注入不了命令；`ccswitch://` 导入确认框完整展示载荷（凭据类值脱敏显示）并标记风险值，用量脚本默认禁用导入。代理侧，工具结果里的图片不再被序列化成工具文本，而是在各转换桥还原为原生媒体上送（文件与音频在两条 Chat 桥上一并支持）——终结了「一张 113 KB 截图吃掉 10 万+ token、两三张图把 Codex 会话卡死在 400 上」的问题（[#4465](https://github.com/farion1231/cc-switch/issues/4465)、[#5663](https://github.com/farion1231/cc-switch/issues/5663)）。
|
||
|
||
用量统计获得两块新能力：**models.dev 自动定价同步**（可选开启，[#5734](https://github.com/farion1231/cc-switch/pull/5734)），配套把手工改价 / 删价持久化到人类可编辑的 `~/.cc-switch/model-pricing.json`；以及 **Grok CLI 官方 OAuth 模式的用量导入**——这条流量无法走本地代理，此前完全不可见——外加供应商卡片上的 SuperGrok 订阅配额展示。围绕分发与体验：应用内更新优先走 `dl.ccswitch.io` 的 Cloudflare R2 镜像（GitHub 回落，签名校验不变）；Codex 用量导入对 fork 会话重用已解析的父 rollout 时间线（[#5626](https://github.com/farion1231/cc-switch/pull/5626)）；预设默认模型升级为 Claude Opus 5、GPT-5.6 Sol 与 Gemini 3.6 Flash；OpenClaw 的 Kimi For Coding 预设修正了 base URL；工具栏应用切换器改为纯图标。本版**没有数据库 schema 迁移**，升级轻量。
|
||
|
||
**发布日期**：2026-07-30
|
||
|
||
**更新规模**：38 commits | 132 files changed | +14,926 / -1,415 lines
|
||
|
||
---
|
||
|
||
## 新功能
|
||
|
||
### models.dev 自动定价同步
|
||
|
||
用量面板的定价区新增「models.dev 自动定价同步」卡片，**默认关闭、需手动开启**：开启时会有确认说明——CC Switch 将在启动时（每 6 小时至多一次）从 models.dev 刷新所选模型的价格，**同名模型的内置价与手工价都会被覆盖**。「选择模型」对话框提供完整的 models.dev 目录（可搜索筛选），另有「自动包含常用模型」选项，覆盖 Claude、GPT、Gemini、Grok、DeepSeek、Qwen、MiMo、LongCat、Kimi、MiniMax、GLM 各家最近发布的模型（每族至多 6 个，可单独排除）。卡片显示上次同步时间与错误，提供「立即同步」，还能打开或重载本地定价文件。
|
||
|
||
从本版起，手工改价与删价会同时记入数据库旁边的人类可编辑文件 `~/.cc-switch/model-pricing.json`，每次启动重放——数据库重建后手工定价不再丢失，删掉的内置价也终于能删得掉（以墓碑记录，不再被重新播种）。注意该文件创建时为空、**刻意不从既有定价表回填**（否则内置价会被一并写成覆盖项、挡掉将来的内置价修正），升级前的改价仍只存在数据库里，重存一次即可入文件。同步真的改了价格时，会把**从未算出成本**（零或缺失）的历史用量行按新价补算——已有成本的行保持原值；拉取失败或离线绝不阻塞启动。models.dev 列表还过滤掉了非文本与已弃用的模型（音频 / 图像 / 视频 / embedding 等），手动选价对话框一并清爽了。（[#5734](https://github.com/farion1231/cc-switch/pull/5734)）
|
||
|
||
### Grok 官方模式的用量，终于进看板
|
||
|
||
Grok CLI 用官方 OAuth 登录时无法经本地代理路由——Grok 以空配置作为模式开关，没有地方能把它指向 CC Switch——这部分消耗此前在用量看板里完全不可见。现在 CC Switch 会随常规会话日志同步，从 `~/.grok/sessions`（含归档会话）的 `updates.jsonl` 里按 `turn_completed` 事件导入逐轮用量：成本优先采用 CLI 自己上报的精确数字，缺失时回落本地定价（内置定价表新增 `grok-4.5-build`，$2 输入 / $6 输出 / $0.30 缓存读，每百万 token）。导入行以上游逐轮 ID 为键，回卷会话不会造成重复计数；沉淀窗口加近期代理活动检查，确保同一流量在「路由 + 官方」混用时也不会算两次。看板里新行以「Grok Build (Session)」供应商名呈现，应用筛选器新增 Grok Build 选项，数据来源分栏新增「Grok Build Session」条目与专属图标，四语齐全。
|
||
|
||
### 供应商卡片上的 SuperGrok 订阅配额
|
||
|
||
类别为「官方」的 Grok Build 供应商，卡片上现在直接显示 SuperGrok 订阅用量——与 Claude Code / Codex / Gemini 的官方订阅页脚并列：CC Switch 读取 Grok CLI 自己的 OAuth 凭据（`~/.grok/auth.json`），查询 grok.com 计费端点获取额度窗口的已用百分比与重置时间；重置间隔可识别时标注为「周」或「月」，否则归入新的「Credits」档（托盘用量摘要中以 `c` 组呈现）。网络瞬断时保留上一次读数并重试，不清空页脚；令牌过期会提示重新 `grok login`。Claude Code、Claude Desktop 与 Codex 里的受管 xAI OAuth（SuperGrok）供应商也自动获得同款配额展示——数据来自绑定到该供应商的账号，用量脚本入口随之隐藏。注意 Grok Build 供应商的「官方」判定现在只看 `category` 字段，不再探测配置内容。
|
||
|
||
### Claude Opus 5 内置定价
|
||
|
||
`claude-opus-5` 加入内置定价表：$5 输入 / $25 输出、$0.50 缓存读 / $6.25 缓存写（每百万 token），用量不再显示 $0。按「不存在才插入」播种，改过的价格不受影响（Opus 5 fast 模式走独立计费，刻意未入表）。
|
||
|
||
### 预设目录更新
|
||
|
||
A6API（同模型多上游自动择优的聚合平台）加入八个应用的赞助商预设；PackyCode 预设在支持备用端点的五类预设（Claude Code / Claude Desktop / Codex / Gemini CLI / Grok Build）上新增三个备用地址，可在地址管理器与测速里选择；AICoding 合作伙伴预设回归七个应用；赞助商排序与 README 重新对齐。
|
||
|
||
---
|
||
|
||
## 变更
|
||
|
||
### 预设默认模型升级：Claude Opus 5、GPT-5.6 Sol、Gemini 3.6 Flash
|
||
|
||
内置预设的默认模型全面来到当前一代：`claude-opus-5` 替换 `claude-opus-4-8`（三种命名形态全覆盖），`gpt-5.6-sol` 替换 `gpt-5.5` 与裸 `gpt-5.6`，`gemini-3.6-flash` 替换 `gemini-3.5-flash`。同步更新了所有镜像位置——通用 / NewAPI 默认值、Codex 自定义 `config.toml` 模板、推荐列表、表单占位符与四语文案；`gemini-3.6-flash` 定价同步入库（$1.50 / $7.50、缓存读 $0.15，每百万 token）。仍钉在 `gemini-3.1-pro-preview` 的 Code0 与七牛 Gemini 预设一并对齐到 3.6 Flash——这是**有意的档位调整**：3.6 没有 Pro 版，3.5 Pro 仍限合作测试。**默认值只影响新建供应商**，已保存的供应商维持创建时的模型；Claude Desktop 的 opus 路由现值前进到 `claude-opus-5`，`claude-opus-4-8` 转入兼容别名槽，存量配置照常解析。
|
||
|
||
### 应用内更新改走 ccswitch.io 镜像
|
||
|
||
更新器现在优先查询 `https://dl.ccswitch.io/latest.json`——发布清单的 Cloudflare R2 镜像——GitHub Releases 作为回落，检查与下载更新不再依赖 GitHub 可达。镜像清单把各平台下载指向同一存储桶，而 minisign 签名保持不动：签名覆盖的是文件内容而非 URL，每个下载产物仍会对着内置公钥校验，**镜像本身始终不被信任**。发布由 release 门控的同步工作流负责，只有当 tag 确为 GitHub 的 `releases/latest` 时才改写根清单，镜像永远不会把用户往回推到旧版本。
|
||
|
||
### Codex 用量导入：fork 会话提速
|
||
|
||
导入与重建 Codex 用量统计不再对同一个父 rollout 文件按 fork 点逐次重读：每个父 `~/.codex/sessions/*.jsonl` 只解析一次，生成内存中的 token 时间线，由所有从它 fork 出的子会话共享，各子会话的截断点改为内存过滤。缓存以文件身份戳校验（修改时间、大小，加 Unix 的 device/inode 或 Windows 的卷序列号 + 文件 ID），被追加、轮转或替换的父文件会重读而不是拿到陈旧数据。提速幅度取决于 fork 密度：fork 密集的历史冗余解析大幅减少，fork 稀少的历史基本不变——两种情况下导入结果都逐字节一致。（[#5626](https://github.com/farion1231/cc-switch/pull/5626)）
|
||
|
||
### 工具栏应用切换器改为纯图标
|
||
|
||
切换器按钮不再在图标旁渲染文字标签——受管应用增至八个后，标签本来就几乎总是被溢出检测收起，于是移除了基于 ResizeObserver 的自动紧凑机制，始终只显示图标。应用名保留在悬停提示里，读屏器经 `aria-label` 照常可及。
|
||
|
||
### 赞助商域名与推荐链接刷新
|
||
|
||
多家赞助商迁移了域名，预设地址、备用端点、推荐链接与 README 行已同步（PackyCode → `www.packyapi.ai`、RightCode → `www.rightapi.ai`、ClaudeAPI → `www.apito.ai`、APINebula → `apinebula.ai`、AICodeMirror → `.ai`、AICoding → `.inc`、AIGoCode → `.app`），顺带移除了两个已失效的备用端点。**已创建的供应商保留数据库里存的旧地址**——想迁到新域名，手动改地址或从刷新后的预设重建即可。
|
||
|
||
---
|
||
|
||
## 修复
|
||
|
||
### 通过代理读图不再撑爆上下文
|
||
|
||
客户端经工具调用读取图片时——Codex 的 `view_image`，或任何返回图片的 MCP 工具——代理的协议转换会把整个图片块序列化进工具消息的文本里，上游按纯文本给 base64 计 token：约 9,000 倍的膨胀，一张 113 KB 的 PNG 折算 10 万+ prompt token；Codex 每轮重放全部历史，两三张截图就足以把会话顶出上下文窗口、卡死在反复的 400 上（[#4465](https://github.com/farion1231/cc-switch/issues/4465)、[#5663](https://github.com/farion1231/cc-switch/issues/5663)）。
|
||
|
||
代理现在把媒体载荷从工具结果里提出来、按各桥的原生格式重新上送——**图片全桥覆盖，文件与音频在目标协议支持处生效**：两条 Chat 桥（Claude→Chat、Codex Responses→Chat）承载图片 / 文件 / 音频，工具消息里留下简短标记、媒体作为合成用户消息紧随工具批次之后；Claude→Responses 还原原生 `input_image`，Codex / GrokBuild→Anthropic 重建标准 Anthropic 图片块，Claude→Gemini 在 Gemini 3 上用多模态 `functionResponse.parts`（旧型号用 `inlineData`），只接受内联 base64 图片。检测覆盖有类型的 Responses 块、Anthropic `source` 块、MCP `data`+`mimeType` 结果与整串图片 data URL，可穿透数组与嵌套 `content` 包装（含 JSON 编码的工具输出）；一旦判定输出含媒体，其中残留的 data URL 与裸 base64 会被折叠成占位——**裸 base64 本身从不触发媒体判定**，普通工具输出原样不动。不含媒体的工具结果在所有桥上保持与之前逐字节一致，prompt 缓存前缀不受影响；上送的媒体块刻意不带 `cache_control` 标记，GLM、Qwen 这类严格上游不会拒收。对 Kimi K3 的端到端实测：同一回放轮稳定在约 12k 输入 token、缓存命中 99%，此前每次重放要背 85k+ 的 base64 文本。
|
||
|
||
### 「不支持图片回退」现在能看到工具结果里的图
|
||
|
||
「不支持图片回退」设置会在供应商仅文本或上游拒图时用占位标记替换图片块，但它此前只能看到仍是结构化块的图片——已被打平成 base64 文本的工具结果图片对它不可见，仅文本上游直接失败、无从恢复。媒体清洗器现在在每条路径上对称地检测并剥离工具输出内的媒体，发送前剥离与被拒后重试两条路都能救回这类轮次；由于该检测现在也深入工具结果，一条回归测试钉住了反应式重试仍只对真正的模态拒绝触发——上下文超限的 400 不会被误当拒图去重试。
|
||
|
||
### Grok Build 成本回填不再高估
|
||
|
||
补算缺失成本的例程此前只把 Codex 与 Gemini 视为「上报输入 token 已含缓存读」的供应商，而 Grok Build 同属该口径——被回填的 Grok Build 行按全量输入计价、缓存读又计一次，成本虚高。缓存含入式供应商集合现在只定义一处，由路由记录器、成本计算器与回填例程共享，三者不再可能各说各话。注意此前已被旧回填修过的行保持原值——回填只处理零成本行，从不改写已有正成本。
|
||
|
||
### 手工编辑的配置文件不再让应用崩溃或吞掉编辑
|
||
|
||
`~/.codex/config.toml` 里 `mcp_servers` 存在但不是表（比如 `mcp_servers = "x"`）时，MCP 同步会在切换中途 panic——且发生在数据库与 live 配置都已写入之后，留下半套用的切换；非表值现在先告警再归一为空表，Codex 与 GrokBuild 写入器同步修复。内联表形态（合法 TOML）有镜像问题：MCP 删除静默无效而界面报成功、`base_url` 编辑写到 Codex 根本不读的层级——均已处理。根节点、`provider` 或 `mcp` 段是数组 / 标量的 `opencode.json` 不再 panic，这类文件会被报错拒绝而不是重建，你自己的 `model`、`theme` 设置不会被抹掉。（[#5811](https://github.com/farion1231/cc-switch/pull/5811)）
|
||
|
||
### 代理转换扛得住畸形上游响应
|
||
|
||
上游网关的畸形数据此前可能直接干掉本地代理而不是产生错误：Anthropic SSE 流里非对象的 `message` 或 `content_block`、缓冲响应体是顶层 JSON 数组或标量（无视 `stream: true` 的网关就返回这种）都会命中 panic 的索引赋值；流现在以正常的失败事件收尾。畸形的 `content_block` 头还会被恢复为文本块——只把它净化成空对象虽止住 panic，却让后续内容全部被静默丢弃、模型看起来什么都没说——由于坏头之后的增量通常是完好的，常见情况现在能通传，替换发生时记一条警告。（[#5811](https://github.com/farion1231/cc-switch/pull/5811)）
|
||
|
||
### OpenClaw 的 Kimi For Coding 地址修正
|
||
|
||
OpenClaw 预设此前指向通用平台端点 `https://api.kimi.com/v1`，而 Kimi For Coding 订阅走的不是它，coding 套餐的 key 用不了。地址修正为 `https://api.kimi.com/coding/v1`，表单占位符与默认值同步更新。**从旧预设创建的供应商需手动改到新地址。**
|
||
|
||
---
|
||
|
||
## 安全加固
|
||
|
||
本节九条里，**有两件事需要你动手**：轮换进过 Gemini 通用配置的密钥，以及核对曾经通过 `ccswitch://` 导入的 MCP 条目——「升级提醒」里写明了怎么做。其余的升级即生效，不需要你操作。
|
||
|
||
如果你从不点开别人发来的 `ccswitch://` 链接，也没用过共享的 Gemini 通用配置，那这九条对你的意义主要是「以后更不容易出事」；如果两条里有一条对得上，**这一版值得优先升级**。
|
||
|
||
### Gemini 通用配置不再泄漏密钥，升级后自动清洗
|
||
|
||
Gemini 通用配置提取器此前只从共享片段里剥掉 `GEMINI_API_KEY` 与 `GOOGLE_GEMINI_BASE_URL`，其余 `env` 条目原样复制——而 `GOOGLE_API_KEY` 正是 Gemini 的一等凭据，某个账号的 key（连同其它长得像凭据的条目）会被深合并进每一个使用通用配置的 Gemini 供应商，并发往对方的 base URL——那可能是第三方中转。提取器现在跳过一切命中凭据模式的键（与 Claude 提取器同一套匹配器），前端片段校验器同步对齐，手工编辑也塞不回去。由于 Gemini 片段一旦存在就不再重提取，升级后首次启动还会执行**一次性清洗**：把已经泄漏的凭据从片段、从每个被合并到的供应商、从 `~/.gemini/.env` 里清掉——按键名**加值**全等匹配，供应商自己的同名不同值 key 不受牵连——并保留 env 文件的排版与注释。清洗细节与注意事项见「升级提醒」。（[#5811](https://github.com/farion1231/cc-switch/pull/5811)）
|
||
|
||
### Skill 仓库安装加固：路径穿越与归档上限
|
||
|
||
从 GitHub 仓库安装或浏览 Skill 此前可能写到目标目录之外：归档条目未经归一就拼上目标路径，带 `..` 的 ZIP 能逃出解压目录（zip-slip）；仓库坐标从未校验，`../../../releases/download/v1/evil` 这样的分支名能把下载重定向到任意 release 资产——而 Skill 仓库可经不可信的 `ccswitch://` 深链添加且默认启用，打开 Skills 面板就足以触发下载。来自备份恢复、同步快照与「从应用导入」的 Skill `directory` 值同样未经校验就拼路径，卸载可能 `remove_dir_all` 到受管目录之外。所有落点现在都校验目录名，仓库 owner / 名称 / 分支在唯一下载汇聚点白名单化，解压设硬上限（10,000 条目、写入 512 MB、下载 128 MB、符号链接目标 4 KB，自指链接拒绝），新错误信息四语齐全。（[#5811](https://github.com/farion1231/cc-switch/pull/5811)）
|
||
|
||
### 深链导入确认框：看全内容，标记风险
|
||
|
||
`ccswitch://` 的 MCP 导入确认框此前只渲染一行会被截断的 `Command:`，`args`、`url`、`env` 一概不显示——链接带上 `command: "sh"` 加 `args: ["-c", "curl …|sh"]` 和一个 `LD_PRELOAD` 环境变量，显示出来只是一个人畜无害的 `sh`，确认后却被写进各应用的 live MCP 文件。确认框现在把命令、每个参数、URL 与环境变量逐行渲染，换行而非截断，不会有内容被裁掉看不见（键名含 TOKEN / KEY / SECRET / PASSWORD 的 env 值以前缀加星号脱敏显示）；值得多看一眼的值会被高亮并汇总进警告块：带内联执行标志的 shell 解释器（含 `bash -lc`、`cmd /C`、PowerShell `-Command` 缩写等组合形态）、改变进程加载行为的环境变量（`LD_*`、`DYLD_*`、`NODE_OPTIONS`、`PYTHONPATH`、`PATH`、代理变量等）、指向回环 / 内网 / 云元数据地址的端点。标记纯属提示、从不拦截导入——本地 Ollama 端点是再正常不过的用法。供应商确认框获得同款处理；「将立即写入所有指定应用」的警告改为无条件显示，不再受链接可控字段的门控。
|
||
|
||
### 深链用量脚本：默认禁用导入，代码先看后用
|
||
|
||
经深链导入的用量查询脚本是每次查用量都会执行的 JavaScript，此前可能全程没见过代码就被启用：后端把「带了代码」当作「同意执行」，确认框只显示启用 / 禁用徽标、从不显示脚本体。脚本现在**默认禁用**——链接必须显式携带 `usageEnabled=true` 才请求启用——确认框以可滚动、完整换行的代码块显示解码后的全部脚本，并警告启用后将会执行。解码失败时回落显示原始载荷，畸形脚本不可能伪装成「没有脚本」。脚本代码照常存到供应商上，审阅后可在应用内手动开启。
|
||
|
||
### URL-safe Base64 曾让确认框整块变空
|
||
|
||
上面两条修的是「确认框显示得不够」，这一条修的是「确认框可以什么都不显示」。后端接受四种 Base64 变体（含 RFC 4648 §5 的 URL-safe 字母表），而前端的 `atob` 只认标准字母表、解不开时**原样返回输入而不报错**——于是同一段载荷，后端解码成功并导入，前端拿到的是一坨解不开的字符。用量脚本与系统提示词因此显示成不透明的 Base64；**MCP 配置最糟：`JSON.parse` 失败被组件吞掉，确认框渲染成「0 个服务器」加一张空列表，而后端照常把真实条目写进 live MCP 文件**。把载荷里一个 `/` 换成 `_` 就够了——确认框变空，导入功能完好，上面两条刚补上的完整展示随之一并失效。
|
||
|
||
前端解码器现在先归一 URL-safe 字母表再解码，确认框显示的永远与将要导入的一致；共享解码器首次有了单元测试，用例内含前置自检，确保样本真的落在 URL-safe 分支上而不是碰巧两种编码相同。
|
||
|
||
> 这条缺陷影响 v3.8.0 起的所有版本。若你曾通过 `ccswitch://` 链接导入过 MCP 服务器，建议检查一次——见「升级提醒」。
|
||
|
||
### SQL 导入拒绝触及导入库之外的语句
|
||
|
||
导入数据库备份此前只校验文件头注释，之后整段文本直接交给 `execute_batch`——精心构造的备份可以 `ATTACH DATABASE` 在用户可写的任意位置创建 SQLite 文件，且该副作用发生在导入自身的状态校验之前，导入整体失败文件也已落地；WebDAV / S3 同步快照走的是同一条代码路径。现在外部批次执行期间安装 SQLite authorizer（结束立即卸下，应用自身的 schema 维护不受影响）：`ATTACH` / `DETACH`、`VACUUM`、虚表创建（csvfile 这类文件后端模块能读写任意路径）以及一切 SQLite 报告为未知的动作一律拒绝——未来的新语句默认失败；PRAGMA 只放行导出器实际会写的 `foreign_keys` 与 `user_version` 两个。
|
||
|
||
### 通用配置片段的原型污染
|
||
|
||
应用、移除、比对通用配置片段的三个遍历器此前都会跟着 `__proto__` 走进全局 `Object.prototype`：`JSON.parse('{"__proto__":{…}}')` 产出的是自有可枚举属性，合并会把攻击者指定的值写上全局原型——而 `settings` 表在同步时会被远端整表覆盖，恶意 WebDAV / S3 快照落地后，打开一次供应商表单就触发合并。三个遍历器现在一律跳过 `__proto__`、`constructor`、`prototype`；「已应用通用配置」的比对同时要求自有属性，顺带修掉一个可见怪象——`{"__proto__":{}}` 此前被判定为任何配置的子集。
|
||
|
||
### 终端启动的目录名命令注入
|
||
|
||
在外部终端恢复会话时，`cd` 行此前用双引号包裹工作目录、只转义反斜杠和双引号——双引号里 shell 照样展开 `$(…)`、反引号与 `$VAR`，而这个值是 CLI 会话历史里记录的真实项目路径，macOS 上目录名合法地可以包含这些字符。文件夹起了那样的名字，点「恢复」就会在你的终端里执行内嵌命令，全程无需任何被攻破的组件。三个拼 shell 行的启动器——Terminal.app、iTerm、kitty——改用 POSIX 单引号转义，任何内容都不展开（穿过 Terminal / iTerm 所需的 AppleScript 引号层同样安全）；Ghostty、WezTerm / Kaku、Alacritty 本就把目录作为独立参数传递，原本安全。
|
||
|
||
### GrokBuild 凭据解析不再替换或内联环境密钥
|
||
|
||
GrokBuild 凭据提取此前在配置指定的 `env_key` 变量未设置时回落到进程级 `XAI_API_KEY`——静默替换成另一个账号的 key、发往配置指向的任意 base URL；凭据现在只来自显式的内联 `api_key` 或 `env_key` 精确命名的环境变量。深链导入不再把环境变量解析成明文 `api_key`；只带 `env_key` 名字的链接会被拒绝并提示手动添加——照单全收意味着请求时仍会解析受害者的环境密钥、送往链接声明的地址。顺带修复：base URL 解析与凭据解析解耦，此前凭据缺失连 base URL 一起清空，macOS（GUI 进程不继承 shell 环境）上界面显示的地址与实际使用的不一致、用量脚本的 `{{baseUrl}}` 展开为空。（[#5811](https://github.com/farion1231/cc-switch/pull/5811)）
|
||
|
||
---
|
||
|
||
## 文档
|
||
|
||
### 「在 Claude Code 中使用 GPT 模型」攻略补齐英日双语
|
||
|
||
此前仅有中文的本地路由攻略现已完整移植为英文与日文，端到端覆盖两条接入路径：第三方 OpenAI Responses 网关（API Key），以及 ChatGPT Plus/Pro 订阅经 Codex 设备码 OAuth 登录。两篇路由攻略同时改题为「用什么模型」而非「什么客户端对」——《[在 Claude Code 中使用 GPT 模型](../guides/claude-codex-routing-guide-zh.md)》《[在 Codex 中使用 Claude 模型](../guides/codex-claude-routing-guide-zh.md)》——所有交叉链接（含三语 v3.18.0 release notes）改为指向读者语言的版本。
|
||
|
||
### 用户手册：深链 `usageEnabled` 默认值修正
|
||
|
||
三语用户手册的深链参考此前声称 `usageEnabled` 默认为 `true`，实际默认 `false`、与导入器一致。手册现在写明正确默认值，并补充两个推论：导入前确认框会完整显示脚本代码；未显式 `usageEnabled=true` 时脚本以禁用状态导入，可稍后在应用内开启。
|
||
|
||
### SECURITY.md：威胁模型与报告范围
|
||
|
||
`SECURITY.md` 补齐双语威胁模型与明确的范围内 / 范围外清单，报告按「谁控制这个输入」而非「值最终到了哪个 API」分诊：内置 WebView 渲染器声明为受信组件（附四条可独立验证的事实与失效触发条件）；深链载荷、WebDAV / S3 恢复数据、导入文件、上游 API 响应、本地代理的入站请求全部列为不可信输入、欢迎报告。
|
||
|
||
---
|
||
|
||
## 升级提醒
|
||
|
||
### 本版没有数据库迁移
|
||
|
||
v3.19.0 不含 schema 迁移（版本号保持 v16），升级即用，无需等待数据重建。
|
||
|
||
### Gemini 密钥一次性清洗（请读）
|
||
|
||
升级后首次启动会在常规配置提取前执行一次性的 Gemini 通用配置清洗。**部分 Gemini 供应商随后可能提示缺少 API Key**：条目按凭据型键名加值全等匹配删除，通常删掉的是经共享片段泄漏进来的其它供应商凭据（该供应商自己的原值在泄漏发生时已被覆盖、无法找回）——但**你有意在多个 Gemini 供应商间复用的同值 key 也会被一并移除**。无论哪种情况，请先轮换再重填：**凡是进过共享 Gemini 片段的密钥都应视为已暴露**。删除的键名与受影响的供应商 id（绝不含值）记录在 `settings` 表的 `gemini_common_config_scrub_audit_v1` 下，可据此逐一定位需要重新填写密钥的供应商。
|
||
|
||
### 曾用深链导入过 MCP？建议检查一次（请读）
|
||
|
||
本版之前，`ccswitch://` 的 MCP 导入确认框可能**显示不出即将写入的内容**：参数与环境变量一概不渲染（`command: "sh"` 加 `args: ["-c", …]` 显示成一个无害的 `sh`），若载荷用 URL-safe Base64 编码，则整个列表显示成「0 个服务器」——而后端两种情况都照常把条目写进各应用的 live MCP 文件。这两条缺陷影响 **v3.8.0 起的所有版本**，本版一并修复。
|
||
|
||
利用需要你亲自打开攻击者提供的链接并点「导入」，因此绝大多数用户不受影响。**如果你确实从不完全信任的来源打开过 `ccswitch://` MCP 导入链接**，建议在 MCP 面板逐条核对，或直接检查 `~/.claude.json` 的 `mcpServers`（Codex 见 `~/.codex/config.toml` 的 `mcp_servers`），确认没有你不认识的条目——MCP 服务器会在 CLI 下次启动时作为子进程执行。
|
||
|
||
### 深链用量脚本默认禁用
|
||
|
||
携带用量查询脚本的深链现在默认以禁用状态导入，除非链接显式携带 `usageEnabled=true`。依赖自动启用的链接（例如部分合作伙伴的一键配置链接）会导入脚本但不开启用量查询——审阅代码后在供应商编辑器里手动开启即可。应用内手工配置的用量脚本不受影响。
|
||
|
||
### 新默认模型只影响新建供应商
|
||
|
||
已保存的供应商维持创建时的模型 ID，想用新模型需手动编辑。Claude Desktop 的 opus 路由现值前进到 `claude-opus-5`、`claude-opus-4-8` 移入兼容别名槽，存量配置照常解析。
|
||
|
||
### 定价播种与本地定价文件
|
||
|
||
新定价行（`claude-opus-5`、`gemini-3.6-flash`、`grok-4.5-build`）在下次启动按「不存在才插入」追加——**播种绝不覆盖你改过的价格**。`~/.cc-switch/model-pricing.json` 创建时为空，只记录本版之后的手工改价与删价——更早的改价不会迁入，想让它们扛住数据库重建，重存一次即可。models.dev 自动同步保持关闭直到你手动开启；一旦开启，它是唯一会覆盖同名价格（内置与手工皆然）的路径。
|
||
|
||
### GrokBuild 隐式环境变量回落已移除
|
||
|
||
依赖隐式 `XAI_API_KEY` 环境回落的 GrokBuild 供应商，现在需要显式的 `api_key` 或正确命名的 `env_key`。
|
||
|
||
### Grok 官方模式用量有意延迟
|
||
|
||
官方模式的 Grok 用量会延迟约十分钟加一个同步周期出现——事件先沉淀、再与代理记录的行核对防止双计；若路由流量与官方流量在窗口内交替，部分官方轮会被跳过而不是冒险重复计数。被旧成本回填高估过的 Grok Build 行保持原值——回填只处理零成本行，从不修订已有正成本。
|
||
|
||
### 更新镜像自下个版本起生效
|
||
|
||
更新器端点列表内置在应用二进制里，现有安装在升级到含本改动的版本之前仍然只查 GitHub；此后优先 `dl.ccswitch.io` 镜像、GitHub 回落。
|
||
|
||
### 赞助商域名迁移不改存量供应商
|
||
|
||
已创建的供应商保留数据库中存储的旧地址，仍指向旧域名。想迁到新域名，手动修改供应商地址，或从刷新后的预设重新创建。
|
||
|
||
---
|
||
|
||
## 风险提示
|
||
|
||
### SuperGrok 配额查询（本版新增）
|
||
|
||
供应商卡片的 SuperGrok 配额展示会读取 Grok CLI 自己的 OAuth 凭据（`~/.grok/auth.json`）并查询 grok.com 的计费端点——该端点并非公开文档化接口，其响应解析基于对现有格式的观察，xAI 调整接口后此功能可能失效（届时卡片降级为不显示配额，其余功能不受影响）。CC Switch 不会存储或修改这些凭据。
|
||
|
||
### 沿用的提示
|
||
|
||
**xAI Grok OAuth 登录**：复用官方 Grok CLI 的公开 OAuth 客户端身份，使用可能导致账号被限制或封禁——详见 [v3.18.0 release notes](v3.18.0-zh.md#风险提示)。
|
||
|
||
**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](v3.13.0-zh.md#️-风险提示)。
|
||
|
||
**第三方供应商路由**：通过 CC Switch 本地代理把 Codex、Claude Desktop 或 Grok Build 的请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。
|
||
|
||
用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。
|
||
|
||
---
|
||
|
||
## 致谢
|
||
|
||
这一版的安全加固几乎全部来自外部——一个 PR，加上收到的安全报告。
|
||
|
||
### 代码贡献
|
||
|
||
- [#5811](https://github.com/farion1231/cc-switch/pull/5811)：Skill 安装的 zip-slip 与仓库坐标穿越、Gemini 通用配置密钥泄漏与一次性清洗、GrokBuild 凭据解析、多处 panic 路径修复，感谢 @zayokami。这是本版单个来源里覆盖面最广的一份工作。
|
||
- [#5734](https://github.com/farion1231/cc-switch/pull/5734)：models.dev 自动定价同步，感谢 @YUZHEthefool。
|
||
- [#5626](https://github.com/farion1231/cc-switch/pull/5626)：Codex fork 会话用量导入提速，感谢 @ayanamislover（与 @SaladDay 共同署名）。
|
||
|
||
### 安全报告
|
||
|
||
本版「安全加固」里的四条修复来自私下发来的安全报告。感谢 **23pds**（SlowMist 慢雾）与 **zues devil**——逐条归属如下：
|
||
|
||
- **深链导入确认框只显示一行会被截断的 `Command:`**——`args`、`url`、`env` 一概不渲染，`sh -c` 加 `LD_PRELOAD` 的载荷在界面上看起来只是一个 `sh`。这是本版影响面最大的一条。（23pds，SlowMist）
|
||
- **导入 SQL 备份未受约束**——`ATTACH DATABASE` 能在用户可写的任意位置创建文件，且副作用发生在导入自身的校验之前。（zues devil）
|
||
- **外部终端启动的目录名命令注入**——`cd` 行用双引号包裹，`$(…)` 照常展开，而这个值是会话历史里记录的真实项目路径。（zues devil 与 23pds 各自独立报告，分别指向内置启动器与自定义模板两条路径）
|
||
- **通用配置片段合并的原型污染**——三个遍历器都会跟着 `__proto__` 走进全局 `Object.prototype`。（23pds，SlowMist）
|
||
|
||
报告同时促使我们补齐了 [SECURITY.md](../../SECURITY.md) 的威胁模型与报告范围——在此之前，这个项目只写了怎么报告，没写什么算漏洞。
|
||
|
||
其余两条深链修复（用量脚本默认禁用、URL-safe Base64 绕过）是在审查上述修复本身时发现的，不在原始报告内。
|
||
|
||
### 问题反馈
|
||
|
||
感谢在 [#4465](https://github.com/farion1231/cc-switch/issues/4465) 与 [#5663](https://github.com/farion1231/cc-switch/issues/5663) 中反馈代理读图撑爆上下文的用户——本版最重要的代理修复来自这些真实场景的复现线索。
|
||
|
||
---
|
||
|
||
## 下载与安装
|
||
|
||
访问 [Releases](https://github.com/farion1231/cc-switch/releases/latest) 下载对应版本，或从官网 [ccswitch.io](https://ccswitch.io) 获取（本版起下载经 Cloudflare 边缘节点分发，不再依赖 GitHub 可达）。
|
||
|
||
### 系统要求
|
||
|
||
| 系统 | 最低版本 | 架构 |
|
||
| ------- | -------------------------- | ----------------------------------- |
|
||
| Windows | Windows 10 及以上 | x64 / ARM64 |
|
||
| macOS | macOS 12 (Monterey) 及以上 | Intel (x64) / Apple Silicon (arm64) |
|
||
| Linux | 见下表 | x64 / ARM64 |
|
||
|
||
### Windows
|
||
|
||
| 文件 | 说明 |
|
||
| ---------------------------------------- | ----------------------------------- |
|
||
| `CC-Switch-v3.19.0-Windows.msi` | **推荐** - MSI 安装包，支持自动更新 |
|
||
| `CC-Switch-v3.19.0-Windows-Portable.zip` | 便携版，解压即用，不写入注册表 |
|
||
|
||
Windows ARM64 设备请选择文件名中带 `arm64` 标识的对应制品。
|
||
|
||
### macOS
|
||
|
||
| 文件 | 说明 |
|
||
| -------------------------------- | --------------------------------------------- |
|
||
| `CC-Switch-v3.19.0-macOS.dmg` | **推荐** - DMG 安装包，拖入 Applications 即可 |
|
||
| `CC-Switch-v3.19.0-macOS.zip` | 解压后拖入 Applications，Universal Binary |
|
||
| `CC-Switch-v3.19.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.19.0-Linux-x86_64.AppImage` / `.deb` / `.rpm`
|
||
- `CC-Switch-v3.19.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` |
|