CC Switch v3.19.0 实战指南：安全加固全面落地，并根治代理读图打爆上下文的问题-平芜编程栈

CC Switch v3.19.0 实战指南：安全加固全面落地，并根治代理读图打爆上下文的问题

【免费下载链接】cc-switchA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build & Hermes Agent. Only official website: ccswitch.io项目地址: https://gitcode.com/GitHub_Trending/cc/cc-switch

CC Switch v3.19.0（发布于 2026-07-30）是围绕"安心使用"展开的一次集中版本：一边对 Skill 安装、ccswitch://深链接导入、SQL 备份导入、通用配置合并与外部终端启动等入口做系统性安全加固，一边完成了一个关键代理正确性修复——让图片经代理转发时不再被当作纯文本计入 token，同时新增 models.dev 自动价格同步与 Grok 官方模式用量导入两项用量能力。读完本文，你能够理解每一项安全修复的攻击面与修复机制、掌握升级后必须手动处理的两个密钥事项，并能直接使用新版用量面板与更新镜像。

对应语言版本：中文版｜日本語版

[!WARNING]只通过官方渠道获取 CC Switch。CC Switch 是完全免费开源的桌面应用，不向用户收取任何费用。官方渠道仅包括官方网站 ccswitch.io、源码仓库 farion1231/cc-switch 的 GitHub 发布页以及作者 farion1231。任何要求付费、充值或提供登录凭据的"CC Switch"均为假冒，如被诱导付款请立即停止交易并通过 GitHub Issues 举报。

版本概览

v3.19.0 由两部分主导：一轮安全加固与一个重大代理正确性修复。

安全侧（PR #5811 及后续独立修复）：GitHub 仓库安装 Skill 防 zip-slip 与路径穿越并引入归档限制；关闭 Gemini 通用配置凭据泄漏通道，且升级后首次启动执行一次性清除；SQL 备份导入改在 SQLite authorizer 下执行并直接拒绝ATTACH等越界语句；通用配置片段合并不再跟随__proto__污染全局原型；外部终端启动改用 POSIX 单引号转义；ccswitch://导入确认完整展示 payload（凭据类取值脱敏）并高亮风险值，用量脚本默认禁用导入。
代理侧：工具结果中的媒体不再被序列化为工具文本，而是由每个协议转换桥以原生媒体格式重新发送，彻底终结"一张 113 KB 截图吃掉 10 万+ token、两三次截图让 Codex 会话反复 400 卡死"的问题（issue #4465、#5663）。
用量统计：models.dev 自动价格同步（可选项，PR #5734）＋手动改价/删价持久化到人类可编辑的~/.cc-switch/model-pricing.json；Grok CLI 官方 OAuth 模式（流量无法经过本地代理、此前完全不可见）的用量导入，以及 Provider 卡片上的 SuperGrok 订阅配额展示。
分发与体验：应用内更新优先走dl.ccswitch.io（Cloudflare R2 镜像，GitHub 为回退，签名校验不变）；Codex 用量导入对 fork 会话复用已解析的父 rollout 时间线（PR #5626）；预设默认模型升级为 Claude Opus 5、GPT-5.6 Sol、Gemini 3.6 Flash；修正 OpenClaw Kimi For Coding 预设地址；工具栏应用切换器改为纯图标。

本版本无数据库 schema 迁移（版本保持 v16），升级即开即用。

版本统计：38 个 commit ｜ 132 个文件变更｜ +14,926 / -1,415 行。

配套文档（建议配合阅读）：

用量统计：用量面板的数据来源与统计口径，本版本新增 models.dev 自动价格同步与 Grok 官方模式用量导入；
Deep-Link 导入（ccswitch://）：导入确认框各字段含义与usageEnabled等参数默认值（本版本起用量脚本默认禁用导入，文档已同步修正）；
SECURITY.md：本版本补齐了威胁模型与报告范围——哪些输入按不可信对待、哪些问题欢迎报告，一目了然。

代理修复：读图不再打爆上下文

这是本版本最重要的代理修复，修复了 issue #4465 与 #5663 中报告的真实场景。

问题机理：当客户端通过工具调用读图（Codex 的view_image，或任何返回图片的 MCP 工具）时，旧版协议转换会把整个图片块序列化进 tool message 的文本中，上游按纯文本对 base64 计数——约 9,000 倍膨胀，一张 113 KB 的 PNG 折算出 100,000+ prompt token。由于 Codex 每轮重放完整历史，两三次截图就能把会话挤出上下文窗口，会话被反复 400 卡死。

修复方式：代理现在把媒体载荷从工具结果中"抬出"，由各桥以原生格式重发——图片覆盖所有桥；文件与音频在目标协议支持的地方生效：

两条 Chat 桥（Claude→Chat、Codex Responses→Chat）承载图片/文件/音频，工具消息中留下短标记，媒体作为合成 user message 跟在工具批次之后；
Claude→Responses 恢复原生input_image；
Codex / GrokBuild→Anthropic 重建标准 Anthropic 图片块；
Claude→Gemini 在 Gemini 3 上使用多模态functionResponse.parts（旧模型用inlineData），仅接受内联 base64 图片。

检测覆盖带类型的 Responses 块、Anthropicsource块、MCPdata+mimeType结果以及整段图片 data URL，并能穿透数组与嵌套content包装（包括 JSON 编码的工具输出）；一旦判定输出含媒体，其中残留的 data URL 与裸 base64 会被折叠为占位符——裸 base64 单独出现绝不触发媒体检测，普通工具输出原样保留。不含媒体的工具结果在所有桥上与之前逐字节一致，prompt cache 前缀不受影响；发往上游的媒体块刻意不携带cache_control标记，以免 GLM、Qwen 等严格上游拒收。实测对 Kimi K3：同一轮重放稳定在约 12k 输入 token、99% 缓存命中率，此前每次重放需携带 85k+ 的 base64 文本。

实现入口在 tool_media.rs：该模块定义了ToolMediaScope（ImagesOnly/InlineImagesOnly/AllSupported）区分各桥支持的模态范围，plan_chat_tool_output_media在不改动无媒体输出的前提下构建"工具文本 + 媒体部分"的分离计划，flush_pending_chat_tool_media将累积的媒体作为合成 user 消息刷出；工具消息中的标记文本（如[cc-switch: tool result media moved to the following user message]）也定义于此，与文档描述完全对应。

"不支持图片回退"现在能看见工具结果里的图

"不支持图片回退"（unsupported image fallback）设置会在上游纯文本或拒收图片时用占位标记替换图片块，但它此前只能看见仍是结构化块的图片——已被展平为 base64 文本的工具结果图片对它不可见，纯文本上游只能失败且无法恢复。媒体清洗器现在在所有路径上对称地检测并剥离工具输出内的媒体，"发送前剥离"与"被拒后重试"两条路径都能救回这类轮次。由于检测深入到工具结果，回归测试固定了：反应式重试仍只在真正的模态拒绝时触发——上下文长度 400 不会被误判为图片拒绝而重试。

用量统计：models.dev 自动价格同步

用量面板的价格区域新增"models.dev 自动价格同步"卡片，默认关闭、手动开启：

开启时弹出确认，说明 CC Switch 将在启动时从 models.dev 刷新所选模型的价格（至多每 6 小时一次），且内置价与手动设置价同模型的匹配项都会被覆盖；
"选择模型"对话框提供 models.dev 全目录（可搜索、可过滤），另有"自动纳入常用模型"选项，覆盖 Claude、GPT、Gemini、Grok、DeepSeek、Qwen、MiMo、LongCat、Kimi、MiniMax、GLM 近期发布模型（每族最多 6 个，可逐个排除）；
卡片展示上次同步时间与错误信息，提供"立即同步"，可打开或重载本地价格文件。

前端同步逻辑见 modelsDevAutoSync.ts：常量MODELS_DEV_STARTUP_SYNC_INTERVAL_MS即 6 小时间隔，syncModelsDevPricing在开启且距上次同步超过间隔时才拉取目录并批量写入（updateModelPricingBatch），失败会记录错误但不阻塞启动；syncModelsDevPricingOnStartup保证每个渲染进程只跑一次。

手动价格持久化：本版本起手动改价与删价同时记录在~/.cc-switch/model-pricing.json（与数据库同目录的人类可编辑文件），每次启动重放——数据库重建后手动价格不再消失，删除的内置价格以 tombstone 记录、最终保持删除状态而不会被重新播种。注意该文件初始为空、刻意不从现有价格表回填（否则内置价全部变成覆盖项，阻碍未来内置价修正），所以升级前做的编辑仍只存在于数据库中——重新保存一次即可进入文件。当同步真正改变了某个价格，历史上从未计算过成本（为零或缺失）的用量行会按新价重算；已有成本的行保持原值。

此外 models.dev 列表过滤掉非文本与已弃用模型（音频/图片/视频/embedding 等），顺带让手动选价对话框更清爽。

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）；
导入行以上游 per-turn ID 为键，回滚的会话不会导致重复计数；配合结算窗口与近期代理活动检查，路由模式与官方模式混用时同一流量不会被计两次；
新行以供应商名"Grok Build (Session)"出现在仪表盘，应用过滤器新增 Grok Build 选项，数据源细分新增带独立图标的 "Grok Build Session" 条目，四种语言全覆盖。

SuperGrok 订阅配额上卡片

"official" 分类下的 Grok Build 供应商现在直接在卡片上显示 SuperGrok 订阅用量，与 Claude Code / Codex / Gemini 的官方订阅脚注并列：CC Switch 读取 Grok CLI 自己的 OAuth 凭据（~/.grok/auth.json）并查询 grok.com 的账单端点，获取配额窗口使用百分比与重置时间；重置间隔可识别时标注 "weekly"/"monthly"，否则落入新的 "Credits" 档（托盘用量摘要中渲染为c组）。瞬时网络失败保留上次读数并重试而非清空脚注；token 过期提示重新运行grok login。Claude Code、Claude Desktop 与 Codex 中受管的 xAI OAuth（SuperGrok）供应商自动获得同样的配额展示——数据来自绑定到该供应商的账号，用量脚本入口相应隐藏。注意：Grok Build 供应商是否算"official"现在仅由category字段决定，不再探测配置内容。

新增内置价格

claude-opus-5加入内置价格表：输入 $5 / 输出 $25，缓存读 $0.50 / 缓存写 $6.25（每百万 token），其用量不再显示 $0。播种采用 insert-if-absent，不覆盖已编辑的价格（Opus 5 fast mode 单独计费，刻意未列入）。

安全加固：九个条目，两项需要你行动

本节九项中，两项需要你动手：轮换进入过 Gemini 通用配置的密钥、检查曾通过ccswitch://导入的 MCP 条目——"升级须知"会给出具体做法。其余升级即生效，无需操作。

如果你从不打开别人发来的ccswitch://链接、也从没用过共享的 Gemini 通用配置，这九项大体意味着"今后出问题的面更小"；若两条中任一条适用于你，这个版本值得优先升级。

1. Gemini 通用配置不再泄漏密钥，升级后自动清除

旧版 Gemini 通用配置提取器只从共享片段中剔除GEMINI_API_KEY与GOOGLE_GEMINI_BASE_URL，其余env条目逐字复制——但GOOGLE_API_KEY是一等 Gemini 凭据，于是某账号的密钥（连同任何其它凭据样式的条目）被深合并进每个使用通用配置的 Gemini 供应商，并送往该供应商的 base URL——那很可能是一个第三方中转。

修复后：提取器跳过所有匹配凭据模式的键（与 Claude 提取器同一匹配器集合），前端片段校验器与之对齐，手动编辑也无法把凭据塞回去。由于 Gemini 片段一旦存在就永不重新提取，升级后首次启动还会执行一次性清除（scrub）：泄漏的凭据从片段本身、所有被合并过的供应商、以及~/.gemini/.env中清掉——按键名 + 精确值匹配，所以某供应商自己的同名但不同值的键不会误伤；env 文件的格式与注释被保留。

实现见 scrub_leaked_gemini_common_config：所有可能失败的步骤排在写入标记位之前（失败即带错返回，让下次启动原样重来），动手前向settings表写审计记录gemini_common_config_scrub_audit_v1——只记键名与受影响的供应商 id，绝不记值，因为settings表会随 WebDAV/S3 同步上传，留值等于把一次清除换成一份跨设备扩散、永不过期的明文副本。

2. Skill 仓库安装加固：路径穿越与归档限制

从 GitHub 仓库安装或浏览 Skill 此前可能写到目标目录之外：归档条目拼接到目标路径前未做规范化，含..的 ZIP 可逃逸解压目录（zip-slip）；仓库坐标从未校验，形如../../../releases/download/v1/evil的分支名可把下载重定向到任意 release 资源——而 Skill 仓库可通过不可信的ccswitch://深链接添加且默认启用，仅打开 Skills 面板就足以触发下载。来自备份恢复、同步快照与"从应用导入"的 Skilldirectory值同样未校验就拼进路径，卸载时可能对外部目录remove_dir_all。

现在：每个落点都校验目录名，仓库 owner/name/branch 在唯一的下载收口点做白名单校验，解压有硬性上限（10,000 条目、写入 512 MB、下载 128 MB、符号链接目标 4 KB，自引用链接拒绝），新错误消息四语言齐备。

3. 深链接导入确认：全量展示，标出风险

此前ccswitch://MCP 导入确认只渲染单行截断的Command:，args、url、env一律不显示——携带command: "sh"+args: ["-c", "curl …|sh"]与LD_PRELOAD环境变量的链接在界面上只显示为无害的sh，点确认后却会被写进每个应用的 live MCP 文件。

现在确认框逐行渲染命令、每个参数、URL 与环境变量，换行不截断；键名含 TOKEN / KEY / SECRET / PASSWORD 的 env 值显示为前缀 + 星号（脱敏实现见 deeplinkRisk.ts 的maskSensitiveValue：超过 8 字符保留前 4 位，否则全星号）。值得多看一眼的值被高亮并归入警告块：

shell 解释器携带内联执行标志：isInlineCommandFlag按形态而非字面量判定——POSIX 侧匹配-+ 字母串中含c的并写短开关（-c、-lc、-eco），Windows 侧匹配/c、/k（大小写不敏感、可带后缀），PowerShell 匹配-Command的任意合法缩写（-comm、-c）以及-EncodedCommand/-e/-ec（见 classifyCommand）；
改变进程加载行为的环境变量：ENV_HIJACK_PATTERNS覆盖LD_*、DYLD_*、NODE_OPTIONS、NODE_EXTRA_CA_CERTS、PYTHONPATH、PYTHONSTARTUP、RUBYOPT、PERL5OPT、JAVA_TOOL_OPTIONS、BASH_ENV、ENV、IFS、PATH、HTTP(S)_PROXY；
指向环回/内网/云元数据的端点：classifyEndpoint做字面量匹配（含169.254.169.254元数据地址、RFC 1918、fc00::/7、IPv4-mapped IPv6），源码注释明确解释了为何不做 DNS 解析——解析引入超时且结果可能与客户端实际连接时不同（DNS rebinding），作为提示用途字面量匹配足够。

标记纯属提示、从不拦截导入——本地 Ollama 端点完全正常。供应商确认获得同样处理；"将立即写入所有指定应用"的警告改为无条件显示，不再受链接可控字段门控。源码注释（deeplinkRisk.ts 头部）也点明了设计立场：深链接携带自定义 endpoint 与 env 是第三方供应商的正常配置能力，真正的缺口是用户点"导入"时看不见自己在同意什么——补的是可见性，不是黑名单。

4. 深链接用量脚本：默认禁用，先见代码再用

通过深链接导入的用量查询脚本是每次查询用量都会执行的 JavaScript，此前可在你从未见过代码的情况下被启用：后端把"提供了代码"当作"同意执行"，确认框只显示启用/禁用徽章。现在脚本默认禁用——链接必须显式携带usageEnabled=true才请求启用——确认框在可滚动、完整换行的代码块中展示解码后的完整脚本，并警告启用后会被执行。解码失败时回退展示原始 payload，畸形脚本无法伪装成"没有脚本"（对应 decodeDeeplinkPayload：解码失败回落到原始串、绝不返回空串——空会让整块内容凭空消失，那正是攻击者想要的效果）。脚本代码仍存于供应商，审阅后可在应用内手动启用。

5. URL-safe Base64 曾让整个确认框变空白

上一节修复"确认框显示不够"，这一条修复"确认框什么都显示不出来"。后端接受四种 Base64 变体（含 RFC 4648 §5 的 URL-safe 字母表），而前端atob只认标准字母表、且解码失败时原样返回输入而非抛错——同一段 payload 后端解码成功并导入，前端却拿着一团解不开的字符。用量脚本与系统提示词因此显示为不透明 Base64；MCP 配置最糟：JSON.parse失败被组件吞掉，确认框渲染 "0 servers" 与空列表，后端却照旧把真实条目写进 live MCP 文件。payload 中把一个/改成_就足够——确认框变空白、导入照常工作，上一节刚补上的全量展示也随之失效。

前端解码器现在先归一化 URL-safe 字母表再解码，确认框所显示永远等于将导入的内容；共享解码器首次获得单元测试，含一个前置自断言，确保样例真的落在 URL-safe 分支而非两种编码碰巧相同。

该缺陷影响 v3.8.0 起的所有版本。若你曾通过ccswitch://链接导入过 MCP 服务器，值得检查——见下文"升级须知"。

6. SQL 导入拒绝越出导入数据库的语句

此前导入数据库备份只校验文件头注释，随后整段文本直接交给execute_batch——精心构造的备份可以ATTACH DATABASE在用户可写任意位置创建 SQLite 文件，且副作用发生在导入自身状态校验之前，所以即使整体导入失败，文件也已经落盘；WebDAV / S3 同步快照走同一代码路径。

现在：外部批处理期间安装 SQLite authorizer（结束后立即移除，应用自身的 schema 维护不受影响）：ATTACH/DETACH、VACUUM、虚表创建（csvfile 等文件支撑模块可读写任意路径）以及 SQLite 报告为 unknown 的一切动作全部拒绝——未来新语句默认失败；PRAGMA 仅放行导出器实际写入的foreign_keys与user_version两项。

7. 通用配置片段的原型污染

应用、移除、比较通用配置片段的三个 walker 过去都跟随__proto__进入全局Object.prototype：JSON.parse('{"__proto__":{…}}')产生自有可枚举属性，合并即把攻击者选定的值写到全局原型上——而settings表在同步时整体被远端覆盖，一旦恶意 WebDAV / S3 快照落盘，打开一次供应商表单即足以触发合并。现在三个 walker 均跳过__proto__、constructor、prototype；"已应用通用配置"的比较额外要求自有属性，顺带修掉一个可见怪象——{"__proto__":{}}过去被判定为任何配置的子集。

8. 启动外部终端时目录名的命令注入

在外部终端恢复会话时，cd行过去用双引号包裹工作目录，仅转义反斜杠与双引号——但双引号内 shell 仍会展开$(…)、反引号与$VAR，而这个值正是 CLI 会话历史中记录的真实项目路径，macOS 上目录名可以合法包含这些字符。这样命名一个文件夹，点"恢复"就会在你的终端里执行内嵌命令，全程不涉及任何被破坏的组件。

现在：拼装 shell 行的三个启动器（Terminal.app、iTerm、kitty）改用 POSIX 单引号转义——单引号内什么也不展开（穿过 Terminal / iTerm 的 AppleScript 引号层也做了安全处理）；Ghostty、WezTerm / Kaku、Alacritty 本就以独立参数传目录，起始即安全。

9. GrokBuild 凭据解析不再替换或内联环境变量键

GrokBuild 凭据提取过去在配置声明的env_key变量未设置时回退到进程级XAI_API_KEY——静默替换成另一个账号的密钥，送往配置指向的任何 base URL。现在凭据只来自显式内联api_key或env_key精确命名的环境变量。深链接导入不再把环境变量解析为明文api_key；只携带env_key名称的链接被拒绝并提示手动添加——照单全收意味着受害者的环境键在请求时仍会被解析、发往链接声明的地址。顺带修复：base URL 解析与凭据解析解耦——此前凭据缺失会把 base URL 一起清空，导致 macOS（GUI 进程不继承 shell 环境）上 UI 显示的地址与实际使用的不一致，且用量脚本的{{baseUrl}}展开为空。

其它修复

手工编辑过的配置文件不再导致崩溃或吞掉编辑

~/.codex/config.toml中存在mcp_servers但不是表（如mcp_servers = "x"）时，MCP 同步曾在切换中途 panic——且发生在数据库与 live 配置均已写入之后，留下半应用状态；现在非表值被警告并规范化为空表，Codex 与 GrokBuild 写入器同样修复。
内联表形式（合法 TOML）存在镜像问题：MCP 删除静默无效而 UI 报告成功、base_url编辑写入 Codex 从不读取的层级——均已处理。
根节点或provider/mcp段是数组/标量的opencode.json不再 panic，而是带错误拒绝（而非重建），你自己的model与theme设置不会被清掉。

代理转换扛住畸形上游响应

上游网关的畸形数据过去可直接击垮本地代理：Anthropic SSE 流中非对象的message或content_block、以及顶层为 JSON 数组/标量的缓冲响应体（忽略stream: true的网关会这样返回），都命中 panic 的索引赋值；现在流以正常失败事件结束。畸形content_block头部额外被恢复为文本块——仅净化为空对象虽止住 panic，却让其后所有内容被静默丢弃、模型看起来"什么都没说"；坏头部之后的 delta 通常完整，所以常见情形现在直接通过，发生替换时记录警告。

Grok Build 成本回填不再高估

回填缺失成本例程过去只把 Codex 与 Gemini 视为"上报输入 token 已含缓存读"的供应商，而 Grok Build 遵循同一约定——回填的 Grok Build 行按全量输入计价后再对缓存读计一次价，成本虚高。缓存包含型供应商集合现在在唯一定义处维护，路由日志、成本计算器与回填例程共用，三者不可能再不一致。注意：已被旧回填触碰过的行保留原值——回填只处理零成本行，从不改写已有的正成本。

OpenClaw 的 Kimi For Coding 地址修正

OpenClaw 预设此前指向通用平台端点https://api.kimi.com/v1，那不是 Kimi For Coding 订阅使用的地址，coding-plan 密钥无法工作。已修正为https://api.kimi.com/coding/v1，表单占位符与默认值同步更新。从旧预设创建的供应商需手动指向新地址。

其它变更

预设默认模型升级：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。所有镜像位置同步更新——universal / NewAPI 默认值、Codex 自定义config.toml模板、推荐列表、表单占位符、四种语言文案；gemini-3.6-flash价格同步播种入数据库（$1.50 / $7.50，缓存读 $0.15，每百万 token）。Code0 与 Qiniu Gemini 预设仍钉在gemini-3.1-pro-preview，一并对齐 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——release manifest 的 Cloudflare R2 镜像——GitHub Releases 作为回退，检查与下载更新不再依赖 GitHub 可达。镜像 manifest 把各平台下载都指向同一 bucket，minisign 签名保持原样：签名覆盖文件内容而非 URL，每个下载的构件仍对照内置公钥校验，镜像本身永不被信任。发布由 release 门控的同步工作流处理，仅当标签确实是 GitHub 的releases/latest时才重写根 manifest，镜像永远不可能把用户回退到旧版本。

端点列表内置于应用二进制中（见 tauri.conf.json），因此现有安装直到升级到包含此变更的版本前仍只查询 GitHub；此后dl.ccswitch.io镜像优先、GitHub 回退。

Codex 用量导入：fork 会话更快

导入与重建 Codex 用量统计不再对同一父 rollout 文件按每个 fork 点重读一次：每个父~/.codex/sessions/*.jsonl只解析一次为内存 token 时间线，供所有从其 fork 出的子会话共享，每个子会话的截断点变成内存过滤器。缓存以文件身份戳（修改时间、大小，外加 Unix 的 device/inode 或 Windows 的卷序列号 + 文件 ID）校验，父文件被追加、轮转或替换时重新读取而非提供陈旧数据。提速幅度取决于 fork 密度：fork 密集的历史省掉大量冗余解析，fork 稀疏的历史基本不变——两种情况下导入结果都逐字节一致。

工具栏应用切换器改为纯图标

切换按钮不再在图标旁渲染文字标签——受管应用增至八个后，标签几乎总是被溢出检测折叠，基于 ResizeObserver 的自动压缩逻辑被移除，仅显示图标。应用名保留在 hover tooltip，读屏器仍可通过aria-label触达。

赞助商标识域名与邀请链接刷新

多个赞助商迁移域名，预设地址、备用端点、邀请链接与 README 行同步更新（PackyCode →www.packyapi.ai、RightCode →www.rightapi.ai、ClaudeAPI →www.apito.ai、APINebula →apinebula.ai、AICodeMirror →.ai、AICoding →.inc、AIGoCode →.app），并移除两个已失效的备用端点。已创建供应商保留数据库中存储的旧地址——要迁移到新域名，请手动编辑地址或从刷新后的预设重建供应商。

预设目录更新

A6API（为同一模型自动挑选多个上游最优结果的聚合平台）加入八个应用的赞助商预设；PackyCode 预设在支持备用端点的五种预设类型（Claude Code / Claude Desktop / Codex / Gemini CLI / Grok Build）上新增三个备用地址，可在端点管理器与测速中选择；AICoding 合作预设回归七个应用；赞助商排序与 README 对齐。

升级须知

本版本无数据库迁移

v3.19.0 不含 schema 迁移（版本保持 v16），升级后立即可用，无需等待数据重建。

一次性 Gemini 密钥清除（必读）

升级后首次启动会在常规配置提取前执行一次性 Gemini 通用配置清除。部分 Gemini 供应商之后可能报告缺少 API Key：条目按凭据样式的键名加精确值匹配删除，通常被删的是经共享片段泄漏进来的其它供应商凭据（该供应商自己的原值在泄漏发生时已被覆盖、无法恢复）——但你有意在多个 Gemini 供应商间复用的同值密钥也会被一并删掉。无论哪种情况，先轮换再重填：任何进入过共享 Gemini 片段的密钥都应视为已暴露。被删键名与受影响供应商 id（从不含值）记录在settings表的gemini_common_config_scrub_audit_v1中，可据此定位每个需要重填密钥的供应商。

曾通过深链接导入过 MCP？值得检查（必读）

本版本之前，ccswitch://MCP 导入确认可能无法显示即将写入的内容：参数与环境变量根本不渲染（command: "sh"+args: ["-c", …]显示为无害的sh），payload 若为 URL-safe Base64 编码则整个列表显示 "0 servers"——两种情况下后端都照常把条目写进各应用的 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）在下次启动时以 insert-if-absent 追加——播种从不覆盖你编辑过的价格。~/.cc-switch/model-pricing.json初始为空，只记录本版本起做出的手动改价与删价——更早的编辑不会迁入；要让其幸存数据库重建，重新保存一次即可。models.dev 自动同步在开启前保持关闭；开启后它是唯一会覆盖匹配价格（无论内置还是手动编辑）的路径。

GrokBuild 隐式环境变量回退已移除

依赖隐式XAI_API_KEY环境回退的 GrokBuild 供应商现在需要显式api_key或命名正确的env_key。

Grok 官方模式用量有意延迟

官方模式的 Grok 用量在约十分钟加一个同步周期之后出现——事件先结算，再与代理记录行比对以防重复计数；若窗口内路由流量与官方流量交替，部分官方轮次会被跳过而非冒险重复计数。旧成本回填高估的 Grok Build 行保留原值——回填只处理零成本行，从不修正已有正成本。

赞助域名迁移不改变现有供应商

已创建供应商保留数据库中存储的旧地址，仍指向旧域名。要迁移，请手动编辑供应商地址，或从刷新后的预设重建。

风险提示

SuperGrok 配额查询（本版本新增）：供应商卡片上的 SuperGrok 配额展示读取 Grok CLI 自己的 OAuth 凭据（~/.grok/auth.json）并查询 grok.com 的账单端点——该端点无公开文档，响应解析基于对当前格式的观测，xAI 变更接口后此功能可能失效（届时卡片降级为不显示配额，不影响其它部分）。CC Switch 不存储也不修改这些凭据。

沿承提示：

xAI Grok OAuth 登录：复用官方 Grok CLI 的公开 OAuth 客户端身份，使用可能导致账号限制或封禁——详见 v3.18.0 发布说明；
Codex OAuth 反向代理：通过反向代理使用 ChatGPT 订阅的 Codex OAuth 可能违反 OpenAI 服务条款——详见 v3.13.0 发布说明；
第三方供应商路由：本地代理把 Codex、Claude Desktop 或 Grok Build 请求转换转发到第三方供应商时，各供应商对计费、合规与数据保留的要求可能不同，使用前请阅读目标供应商条款。

启用这些功能即视为接受相关风险。CC Switch 不对因使用这些功能导致的账号限制、警告或服务中止负责。

下载与安装

从 farion1231/cc-switch 的 GitHub Releases 页下载对应系统的构建，或从官网 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 安装：

brew install --cask cc-switch

升级：

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`