v3.20.1

# CC Switch v3.20.1

> 这一版围绕 Codex 补两笔硬账：**适配 Codex CLI 0.149**——第三方切换 401「Missing API key」的根治：切换改为 config-only，密钥随供应商表走、不再进 `auth.json`，一族让 0.149 拒绝启动的历史配置形态也在每次切换时自动修复；**同一 ChatGPT Team workspace 的多个账号不再互相覆盖**——存量托管账号需逐个重新登录一次（见升级提醒）。数据可靠性另有三条硬修复：供应商编辑必达 live 配置、Codex 编辑框不再串染别张卡的密钥、恢复备份不再清空手写的 prompt 文件。用量侧新增「自动扫描会话记录」开关，大会话文件的扫描从秒级降到毫秒级。本版**包含数据库迁移（v17 → v18）**，升级前自动备份，降级需还原备份。

**[English →](https://github.com/farion1231/cc-switch/blob/v3.20.1/docs/release-notes/v3.20.1-en.md) | [日本語版 →](https://github.com/farion1231/cc-switch/blob/v3.20.1/docs/release-notes/v3.20.1-ja.md)**

---

## 重点内容：你现在可以

- **在 Codex CLI ≥ 0.149 上正常切换第三方供应商**（[#6744](https://github.com/farion1231/cc-switch/issues/6744)）：0.149 起自定义 provider 不再从 `auth.json` 继承环境凭据，以旧默认方式（密钥只写 `auth.json`）完成的第三方切换一律 401。切换现已整体改为 config-only——密钥写进供应商自己的 `[model_providers.*]` 表（`experimental_bearer_token`，Codex 0.48 起支持），`auth.json` 回归纯粹的官方 ChatGPT 登录文件。
- **让同一 Team workspace 的多个 ChatGPT 账号安全共存**（[#6780](https://github.com/farion1231/cc-switch/pull/6780)，修复 [#2245](https://github.com/farion1231/cc-switch/issues/2245)）：此前账号以 workspace ID 为主键，同一 Team 两名成员会合并成一条记录、后登录者静默覆盖前者的令牌。现在同 workspace 登录并存为独立账号行，接管下的请求还会校验账号一致性——绝不把账单记到另一名成员头上。
- **相信「保存成功」四个字**（[#6779](https://github.com/farion1231/cc-switch/pull/6779)）：崩溃残留的接管备份行曾让活跃供应商的编辑只更新数据库、真正的配置文件纹丝不动。所有权判定已重建，编辑必达 live 配置。
- **在编辑框里看到这张卡自己的密钥**（[#6534](https://github.com/farion1231/cc-switch/pull/6534)，修复 [#6414](https://github.com/farion1231/cc-switch/issues/6414)）：共享的 `auth.json` 没有供应商身份，编辑活跃 Codex 供应商可能显示——保存后固化——另一张卡遗留的 key，同 base URL 的卡密钥互相趋同、报「model not found」。表单现在从 `config.toml` 里该卡自己的 bearer token 重建密钥。
- **放心恢复备份**（[#6810](https://github.com/farion1231/cc-switch/pull/6810)，修复 [#6778](https://github.com/farion1231/cc-switch/issues/6778)）：云端快照没有任何已启用 prompt 时，WebDAV/S3 下载或备份导入不再把本地手写的 `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `SOUL.md` 清成空文件。
- **关掉后台会话扫描**：用量页新增「自动扫描会话记录」开关，关闭即手动模式——仅在点击「立即同步」时扫描本地会话记录；代理接管的请求记账实时落库、与会话文件无关，照常记录。
- **看到 OpenCode Go 的订阅额度**：用量脚本的 Token Plan 查询现在识别 OpenCode Go，5 小时 / 周 / 月三个窗口的用量百分比与重置时间进入用量卡与托盘。
- **在 macOS 上把终端设为 Otty**（[#6620](https://github.com/farion1231/cc-switch/pull/6620)）：会话恢复、供应商终端与工具命令三处入口都可选。
- **让大会话文件的扫描从秒级降到毫秒级**：Claude 会话日志改为字节游标增量扫描，12 MB 活跃会话文件从整读 6.04 秒降到增量 9.3 毫秒。

---

## 使用攻略

- **[添加供应商](https://github.com/farion1231/cc-switch/blob/v3.20.1/docs/user-manual/zh/2-providers/2.1-add.md)**：Codex config-only 切换后的供应商管理入口。
- **[用量统计](https://github.com/farion1231/cc-switch/blob/v3.20.1/docs/user-manual/zh/4-proxy/4.4-usage.md)**：会话扫描开关与 Token Plan 额度查询的口径。

---

> [!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 反馈。

---

## 概览

这一版的主线在 Codex，起点是一次上游的兼容性断裂：Codex CLI 0.149 收紧了凭据继承，自定义 provider 不再读取 `auth.json` 里的环境凭据，以旧默认方式写入的第三方切换全部 401。CC Switch 的应对不是打补丁，而是把第三方切换整个改成 config-only——密钥随供应商自己的配置表走，`auth.json` 回归纯粹的官方 ChatGPT 登录文件；同时一族让 0.149 拒绝加载的历史配置形态（占用保留 id 的旧表、缺 `name` 的表、顶层 `openai_base_url` 旧式路由）在每次切换与接管投影时自动修复，并新增写前预检——0.149 无法加载的组合会被点名拒绝，而不是「切换成功」之后 Codex 起不来。

第二条主线是账号与数据安全：同一 ChatGPT Team workspace 的成员在认证中心不再互相覆盖（存量托管账号需重登一次）；供应商编辑保证必达 live 配置；Codex 编辑框不再串染别张卡的密钥；恢复备份不再清空手写的 prompt 文件。用量侧，会话扫描获得自动/手动开关与字节游标增量扫描（6.04 秒 → 9.3 毫秒），并顺手修掉三个 Claude 会话记账的正确性缺陷——这也是本版唯一数据库迁移（v17 → v18）的由来。

**发布日期**：2026-08-28

**更新规模**：26 commits | 66 files changed | +7,474 / -1,000 lines

---

## 新功能

### 会话记录扫描：自动/手动模式

用量页新增「自动扫描会话记录」卡片与开关（默认开启，升级后行为不变）。关闭后停止一切后台会话扫描——包括启动时的首轮——并出现「立即同步」按钮作为手动入口，完成后以提示显示导入条数、扫描文件数与错误计数。代理接管的请求记账是实时落库、从不读会话文件，无论开关如何都照常记录；启动时的成本回填只修数据库既有行，手动模式下也照常执行。

### OpenCode Go 订阅用量

用量脚本的 Token Plan 查询现在识别 OpenCode Go，在用量卡与托盘显示 5 小时 / 周 / 月三个窗口的用量百分比与重置时间，复用既有的配额层级展示。该端点只认 Bearer 认证（与推理侧只认 `x-api-key` 恰好相反）；密钥有效但未订阅 Go 计划时显示明确的提示（HTTP 403）而不是笼统的认证失败，零用量窗口会丢弃上游的占位重置时间，无法识别的响应形状报错而不是空卡。在 Claude Code、Claude Desktop、Codex、OpenCode 与 Pi 新添加的 OpenCode Go 供应商自动启用查询；OpenCode Zen 按量付费刻意不覆盖——该计划上游没有用量 API。

### Otty 终端支持（macOS）

「Otty」加入 macOS 终端选择器，覆盖会话恢复、供应商终端与工具命令三处入口。启动时先尝试经 Otty CLI 在既有窗口开新标签页，再退到新开 Otty 窗口；供应商终端与工具命令在失败时进一步回退到 Terminal.app，而会话恢复失败则直接报错——Otty CLI 缺失时附明确的安装提示——并把命令复制到剪贴板。CLI 探测覆盖应用包（系统与用户级）、Homebrew 路径与 PATH。用户手册的 macOS 终端表格也顺带修正——Kaku 与 Warp 早已支持却漏在表外。（[#6620](https://github.com/farion1231/cc-switch/pull/6620)）

---

## 变更

### Codex 第三方切换改为 config-only

切换到第三方 Codex 供应商时，密钥现在写进该供应商自己的 `[model_providers.*]` 表（`experimental_bearer_token` 字段，Codex 0.48 起支持），**不再写进 `auth.json`**——它回归纯粹的官方 ChatGPT 登录文件。背景是 Codex 0.149 停止让自定义 provider 从 `auth.json` 继承环境凭据，以旧默认方式（密钥只写 `auth.json`）完成的第三方切换从此 401。

「非接管切换时保留官方登录」开关随之只剩一个含义：开启时官方 ChatGPT 登录在第三方切换中完全不被触碰；关闭时**删除** `auth.json` 而不是用 API 密钥覆盖它（删除失败会弹出警告，提示官方登录仍留在 Codex 配置目录中）。两道安全闸现在在**每次第三方切换**都执行、不再只限保留模式：有密钥却没有任何 provider 表可以承载，或没有密钥却会回退到官方登录（`requires_openai_auth = true` 且无自有凭据，或裸的顶层 `openai_base_url` 路由），都会被点名拒绝——包括配置为空的第三方卡，它们此前一直静默搭乘 `auth.json`。活跃的带密钥第三方表上的 `requires_openai_auth` 会在每次直接切换时按保留开关重新戳记，让 Codex 的登录界面与磁盘上的实际状态一致。（[#6744](https://github.com/farion1231/cc-switch/issues/6744)、[#6746](https://github.com/farion1231/cc-switch/pull/6746)）

### TeamoRouter 预设迁至 teamorouter.cn

八个应用的预设全部指向 `api.teamorouter.cn`，旧 `.com` 端点在 Claude Code、Claude Desktop、Codex 与 Grok Build 上注册为可选择、可测速的后备端点。已保存的存量 TeamoRouter 供应商保持各自原有的 Base URL 不变。

---

## 修复

### 同一 workspace 的 ChatGPT 账号不再在认证中心合并

托管的 Codex OAuth 账号此前以 `chatgpt_account_id` 为主键——它标识的是 ChatGPT workspace 而不是人：同一 Team workspace 的两名成员会坍缩成一条记录，后登录者静默覆盖前者的令牌，供应商绑定跟着指向最后登录的人。账号现在以本地身份建键、保留 OIDC subject 作为用户身份凭证，同 workspace 登录并存为独立账号行。经接管路由的请求会额外对照绑定账号的 live 令牌校验：仍持有另一名成员登录态的 Codex 会话得到「请重启 Codex」的明确报错，而不是以错误身份被转发；外发的 workspace 请求头一律来自账号绑定而不是客户端自报。收养 CLI 轮转过的刷新令牌、以及移除账号时删除 `auth.json`，现在都要求可证明的所有权——CC Switch 不再可能收养或删除同 workspace 另一名成员的登录。每条账号行提供就地「重新登录」（绑定保留）；取消或被取代的设备登录会在 CC Switch 内部丢弃等待中的流程——被放弃的浏览器授权无法在几分钟后被提交、悄悄覆盖账号。不是合法 JWT 形状的 id_token 不再产生任何身份——畸形或截断的令牌永远无法冒充用户。（[#6780](https://github.com/farion1231/cc-switch/pull/6780)、[#6831](https://github.com/farion1231/cc-switch/pull/6831)，修复 [#2245](https://github.com/farion1231/cc-switch/issues/2245)）

### Codex 0.149 兼容修复族：存量配置不再让 Codex 拒绝启动

一族让 Codex 0.149 拒绝加载的配置形态——用户侧表现为「CC Switch 显示切换成功，Codex 却起不来」——现在在每次供应商切换与接管投影时自动修复。具体包括：早期接管投影写下的 `[model_providers.openai]` / `.ollama` / `.lmstudio` 遗留表（覆盖保留 id 会导致校验失败）被无损改名为 CC Switch 自有 id 并归一为可加载形状；没有 `name` 的 provider 表被回填（0.149 会因任何一张缺名表拒绝整份配置——Bedrock 表刻意保持无名，命名会破坏其内置合并）；携带可用密钥的旧式顶层 `openai_base_url` 路由被迁移成正规的自定义 provider 表（无密钥的这类路由会被切换时的安全闸拒绝）；新的写前预检对 0.149 无法加载的字段组合点名拒绝，而不是写出去当作「切换成功」。接管路由指向内置 `openai` provider 的卡改用官方支持的顶层字段而不是制造保留表，指向 `ollama` / `lmstudio` 的卡接管时显式报错。保留 id 清单与上游完全一致（大小写敏感；补入 `amazon-bedrock-runtime`，旧的 `oss` / `ollama-chat` 按普通自定义 provider 对待——它们的密钥终于能到达自己的表），内联的 `model_providers` 表也能接到注入的令牌，而不是留下一个死的顶层字段。

### 被拒绝的切换不再腐坏被拒的那张卡

live 写入校验现在作为预检、在当前供应商指针移动之前执行。此前写入层的拒绝发生在 `current` 已提交之后——下一次切换会把旧的 live 配置回填进这张被拒供应商的已存设置。

### 供应商编辑必达 live 配置文件

崩溃或恢复失败残留的接管备份行，会让活跃供应商的保存（Claude Desktop 除外）走上接管路径——只更新数据库与备份行，真正的配置文件无限期保持旧端点旧密钥。所有权现在由单一谓词裁定，要求接管的实际证据（live 文件中有占位符，或代理已启用且运行中且有备份行，或切换过程持有 per-app 锁且有备份行）；过期的备份行被刷新为与所编辑供应商一致，而不是劫持写入。统一供应商保存现在还会把每个生成的子配置重新投影到以它为活跃供应商的应用的 live 配置，逐应用报出失败名称而不是一律报成功。（[#6779](https://github.com/farion1231/cc-switch/pull/6779)）

### Codex 编辑框不再显示另一张卡的密钥

开启官方登录保留时，`auth.json` 是一个没有供应商身份的共享槽位，而编辑框播种表单时曾优先读它——编辑活跃的 Codex 供应商可能显示、并在保存时固化另一张卡遗留的密钥，让共享同一 Base URL 的卡密钥互相趋同（表现为「model not found」）。编辑框现在从 `config.toml` 里该供应商自己的 bearer token 重建密钥；官方类与纯 OAuth 供应商不受影响，而 `config.toml` 里没有自有 bearer token 的卡——旧版或手工维护的形态，本版起每次第三方切换都会写入——保持原有行为、继续读取 live `auth.json`（含手工修改）。（[#6534](https://github.com/farion1231/cc-switch/pull/6534)，修复 [#6414](https://github.com/farion1231/cc-switch/issues/6414)）

### 恢复不再清空非受管的 prompt 文件

WebDAV/S3 下载或备份导入时，若快照里某应用没有任何已启用的 prompt，该应用的 live prompt 文件（`CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `SOUL.md`）会被截断为空——摧毁从未进入同步载荷的本地手写内容。这样的恢复现在完全不碰该文件；从提示词面板里禁用最后一条 prompt 仍会照旧清空它。（[#6810](https://github.com/farion1231/cc-switch/pull/6810)，修复 [#6778](https://github.com/farion1231/cc-switch/issues/6778)）

### 恢复界面的退出按钮真的能退出了

`process:allow-exit` 权限缺失，v3.20.0 上「数据库版本过新」恢复界面的退出按钮、以及配置加载失败后的退出调用都被 IPC 层静默拒绝：退出按钮毫无反应（关闭窗口仍可退出），配置加载失败后应用径直进入正常界面而不是按设计退出。该问题由 @SaladDay 在 [#6567](https://github.com/farion1231/cc-switch/pull/6567) 更早独立发现并率先修复。

### Claude 会话记账正确性三修

随增量扫描器落地的三个数据准确性修复，均针对 Claude 会话日志路径。写到一半的日志行曾被旧的行号游标永久跳过（未完成的尾部推进了游标，补全后的消息再也不会被导入）——字节游标只在完整行之后提交，该消息下一轮即被拾取。被外部截断或改写的会话文件**从不重放**：重新导入明细行已被 30 天汇总清理的条目会让总数永久虚高，因此游标钉在新的文件末尾，被跳过的范围报告进同步结果的错误列表而不是静默丢弃（截断由游标越界发现，同尺寸改写由游标前字节的指纹发现）。文件中途的读取错误现在保留已提交的进度、下一轮从原处续读并上报，而不是返回一次干净的成功；游标预取失败会中止本轮，而不是表现得像首次扫描、把历史重复导入一遍。

---

## 性能

### Claude 会话日志：字节游标增量扫描

每轮扫描现在直接定位到上次提交的字节偏移、只读新追加的部分，而不是把变更过的文件从头读到尾——按改动自带的基准测试，12 MB 的活跃会话文件从整读解析 6.04 秒降到增量读取 9.3 毫秒。Claude、Gemini、OpenCode、Grok Build 与 Pi 的逐文件游标改为每个导入器每轮一次整表预取，而不是逐文件查询；Claude 路径上每个文件的导入与游标推进在同一事务中提交。1,017 个会话文件（409 MB）的冻结快照回放产出与旧扫描器逐位一致的汇总。需要一次 schema 迁移（v17 → v18），新增两个可空列——字节游标与尾部指纹；既有的行号游标在首轮扫描时就地转换，不重复导入任何内容。

### Pi 会话去重走上身份索引

合并的去重查询（跨两个身份列的 OR）只能约束数据源前缀，每条解析记录都要扫过账本里整个 Pi 区段——Pi 导入随用量历史增长越来越慢。现拆分为可走索引的点查询、结果完全一致，导入耗时不再随历史规模退化。（[#6667](https://github.com/farion1231/cc-switch/pull/6667)）

---

## 升级提醒

### 本版包含数据库迁移，降级需还原备份

schema 从 v17 迁移到 v18（会话扫描游标表新增字节游标与尾部指纹两列），迁移前自动创建备份。本版运行过一次后，旧版 CC Switch 会拒绝打开数据库——降级需还原该备份。旧的半行缺陷已漏掉的用量条目不做追溯找回——重放它们与重复导入已汇总的历史无法区分。

### Codex OAuth 存量账号需要重新登录一次

本版之前添加的每个托管 ChatGPT（Codex OAuth）账号都处于隔离状态，直到你在认证中心该账号行上点击「重新登录」——老记录以 ChatGPT workspace ID 为账号主键、没有单独记录的用户身份，普通的令牌刷新无法证明老记录属于哪个用户。供应商绑定会被保留，重新登录就地更新账号。请务必用账号行上的「重新登录」按钮：通过「添加账号」再登一次只会新建第二条记录（登录不再按 workspace 合并），老记录——以及绑定它的供应商——依然处于隔离状态。（[#6780](https://github.com/farion1231/cc-switch/pull/6780)）

### Codex 0.48 以前的版本失去第三方鉴权

config-only 切换写入的 provider 表令牌字段，0.48 以前的 Codex 从不读取。还在用旧版 Codex 的用户请升级 Codex。

### 保留开关关闭时，切换第三方会删除 auth.json

「非接管切换时保留官方登录」开关**关闭（默认）**时，切换到第三方 Codex 供应商现在会**删除** `auth.json`，而不是用 API 密钥覆盖它。要找回 ChatGPT 登录：切换到绑定了认证中心账号的官方供应商即可（登录会从托管账号完整写回）；跟随 Codex CLI 自身登录的未绑定官方卡则需要跑一次 `codex login`。想让官方登录跨第三方切换存活，把开关打开即可。

### 部分以前「能用」的 Codex 卡现在会在切换时被拒绝

配置为空的第三方卡（没有表可以承载密钥），以及依赖 `requires_openai_auth = true` 或裸 `openai_base_url` 路由去借用官方登录的无密钥卡，现在都会被点名拒绝。给这类卡补上正规的 `[model_providers.<id>]` 条目或 API 密钥即可。

### 存量 Codex 配置会在下次写入 live 时按 0.149 需要被重写

带可用密钥的旧式 `openai_base_url` 路由变成 `[model_providers.cc-switch]` 表、占用保留 id 的遗留表改名为 CC Switch 自有 id、缺失的 `name` 字段被回填；活跃带密钥第三方表上的 `requires_openai_auth` 在每次切换时按保留开关覆盖——你在该表上手工设置的值不会在切换后存活。

### 截断或被外部改写的 Claude 会话日志将被永久跳过（设计使然）

被改写的范围不重放（重放会与已清理的汇总重复计数），跳过的情况会报告在同步结果的错误列表里。

### #6534 修复前已经串染的密钥不会自动修复

如果共享同一 Base URL 的 Codex 供应商已经趋同到同一个 key，请在每张受影响的卡上重新填一次正确的密钥。

### 恢复行为变化（#6810）

恢复一份某应用没有任何已启用 prompt 的快照，现在会保留该应用的 live prompt 文件——客户端继续加载旧内容，即使提示词面板显示全部禁用。想清空它，在面板里启用再禁用一条 prompt（或自行编辑文件）。

### 统一供应商保存现在可能明确报错

若某应用的活跃供应商是生成的子配置、而其 live 配置文件写入失败，保存会报出该应用名称；数据库记录仍已保存——重试同步或重新切换一次该应用的供应商即可。

### TeamoRouter 存量供应商保持 `api.teamorouter.com`

从预设重新添加、或手动修改 Base URL，即可迁到 `.cn`。

### OpenCode Go 用量查询只对本版之后新增的供应商自动启用

存量卡请打开其用量脚本设置，选择 Token Plan 模板 → OpenCode Go 一次。

---

## 风险提示

### 沿用的提示

**xAI Grok OAuth 登录**：复用官方 Grok CLI 的公开 OAuth 客户端身份，使用可能导致账号被限制或封禁——详见 [v3.18.0 release notes](https://github.com/farion1231/cc-switch/blob/v3.20.1/docs/release-notes/v3.18.0-zh.md#风险提示)。

**Codex OAuth 反向代理**：使用 ChatGPT 订阅的 Codex OAuth 反代可能违反 OpenAI 服务条款，详情见 [v3.13.0 release notes](https://github.com/farion1231/cc-switch/blob/v3.20.1/docs/release-notes/v3.13.0-zh.md#️-风险提示)。

**SuperGrok 配额查询**：供应商卡片的配额展示依赖 grok.com 的非公开计费端点，xAI 调整接口后可能失效——详见 [v3.19.0 release notes](https://github.com/farion1231/cc-switch/blob/v3.20.1/docs/release-notes/v3.19.0-zh.md#风险提示)。

**第三方供应商路由**：通过 CC Switch 本地代理把 Codex、Claude Desktop 或 Grok Build 的请求转换并转发到第三方供应商时，各供应商对计费、合规与数据留存的约束不同，请在使用前阅读目标供应商的服务条款。

用户启用上述功能即表示自行承担相关风险。CC Switch 不对因使用这些功能而导致的任何账号限制、警告或服务暂停承担责任。

---

## 致谢

本版 26 个提交里有 8 个来自 5 位外部贡献者。

### 代码贡献

- 感谢 @SaladDay：workspace 账号隔离整条主线（[#6780](https://github.com/farion1231/cc-switch/pull/6780)）、JWT 身份解析对齐（[#6831](https://github.com/farion1231/cc-switch/pull/6831)）与 Pi 会话去重索引（[#6667](https://github.com/farion1231/cc-switch/pull/6667)）；退出按钮的权限缺失也是他在 [#6567](https://github.com/farion1231/cc-switch/pull/6567) 更早独立发现并率先修复的。
- 感谢 @YUZHEthefool：供应商编辑必达 live 配置（[#6779](https://github.com/farion1231/cc-switch/pull/6779)，与 @BingZi-233 协作）与 Codex 编辑框密钥串染修复（[#6534](https://github.com/farion1231/cc-switch/pull/6534)）——「修复」章节里两条数据正确性硬修复尽出于此。
- 感谢 @SailingLoong：恢复不再清空非受管 prompt 文件（[#6810](https://github.com/farion1231/cc-switch/pull/6810)）。
- 感谢 @yovinchen：Otty 终端支持（[#6620](https://github.com/farion1231/cc-switch/pull/6620)）。
- 感谢 @ISuuuu：WSL2 契约测试改走预编译产物（[#6472](https://github.com/farion1231/cc-switch/pull/6472)）。

### 问题反馈

- 感谢 @hlwhl 在 [#6744](https://github.com/farion1231/cc-switch/issues/6744) 对 Codex 0.149 凭据继承变化的精确报告——直接框定了本版最大主线的方向，并率先提出了修复 PR（[#6746](https://github.com/farion1231/cc-switch/pull/6746)）。
- 感谢 Team workspace 账号互覆问题的各位报告者：@cp7553479（[#2245](https://github.com/farion1231/cc-switch/issues/2245)）、@Smilenize（[#5885](https://github.com/farion1231/cc-switch/issues/5885)）、@yingjiezhao0820（[#6688](https://github.com/farion1231/cc-switch/issues/6688)）与 @buqi759（[#6738](https://github.com/farion1231/cc-switch/issues/6738)）。
- 感谢密钥串染家族的报告者：@Joaging（[#6414](https://github.com/farion1231/cc-switch/issues/6414)）、@KawaiiSh1zuku（[#6594](https://github.com/farion1231/cc-switch/issues/6594)）与 @Michael-py001（[#6827](https://github.com/farion1231/cc-switch/issues/6827)）。
- 感谢 @gyzerocc 报告 WebDAV 恢复清空 AGENTS.md（[#6778](https://github.com/farion1231/cc-switch/issues/6778)）——精确指出了触发条件。

---

## 下载与安装

访问 [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.20.1-Windows.msi`          | **推荐** - MSI 安装包，支持自动更新 |
| `CC-Switch-v3.20.1-Windows-Portable.zip` | 便携版，解压即用，不写入注册表      |

Windows ARM64 设备请选择文件名中带 `arm64` 标识的对应制品。

### macOS

| 文件                             | 说明                                          |
| -------------------------------- | --------------------------------------------- |
| `CC-Switch-v3.20.1-macOS.dmg`    | **推荐** - DMG 安装包，拖入 Applications 即可 |
| `CC-Switch-v3.20.1-macOS.zip`    | 解压后拖入 Applications，Universal Binary     |
| `CC-Switch-v3.20.1-macOS.tar.gz` | 用于 Homebrew 安装和自动更新                  |

Homebrew 安装：

```bash
brew install --cask cc-switch
```

更新：

```bash
brew upgrade --cask cc-switch
```

### Linux

Linux 资产同时提供 **x86_64** 和 **ARM64**（`aarch64`）两种架构。资产文件名中包含架构标识，请按你机器的 `uname -m` 输出选择对应版本：

- `CC-Switch-v3.20.1-Linux-x86_64.AppImage` / `.deb` / `.rpm`
- `CC-Switch-v3.20.1-Linux-arm64.AppImage` / `.deb` / `.rpm`

| 发行版                                  | 推荐格式    | 安装方式                                                               |
| --------------------------------------- | ----------- | ---------------------------------------------------------------------- |
| Ubuntu / Debian / Linux Mint / Pop!\_OS | `.deb`      | `sudo dpkg -i CC-Switch-*.deb` 或 `sudo apt install ./CC-Switch-*.deb` |
| Fedora / RHEL / CentOS / Rocky Linux    | `.rpm`      | `sudo rpm -i CC-Switch-*.rpm` 或 `sudo dnf install ./CC-Switch-*.rpm`  |
| openSUSE                                | `.rpm`      | `sudo zypper install ./CC-Switch-*.rpm`                                |
| Arch Linux / Manjaro                    | `.AppImage` | 添加执行权限后直接运行，或使用 AUR                                     |
| 其他发行版 / 不确定                     | `.AppImage` | `chmod +x CC-Switch-*.AppImage && ./CC-Switch-*.AppImage`              |