跳转到内容
CC Switch WikiUnofficial Community Wiki

settings.json 被 cc-switch 覆盖导致自定义配置丢失（Claude Code）

Quick fix

把除 env 外的自定义配置（hooks、插件、spinnerVerbs 等）写进供应商的「通用配置」并勾选「写入通用配置」；官方不改为字段级合并。

Symptom

Section titled “Symptom”
报错原文
cc-switch 在切换 provider 时会**完全覆盖** `~/.claude/settings.json` 文件，导致用户精心配置的 **spinnerVerbs（自定义加载动词）** 以及其他个人配置全部丢失。

Cause

Section titled “Cause”

cc-switch 在接管/切换供应商、编辑保存供应商（模型改动）、自动故障转移甚至重启后启动时，会把 `~/.claude/settings.json` 全量重写为当前供应商在数据库中保存的配置（仅保留 env 等代理字段，如 `ANTHROPIC_AUTH_TOKEN: PROXY_MANAGED`、`ANTHROPIC_BASE_URL: http://127.0.0.1:15721`），用户手工写入的 hooks、permissions、enabledPlugins、spinnerVerbs、contextFiles 等字段被直接删除。

官方在 #1570 中说明：v3.11.0 曾尝试字段级合并（merge）方案，但实际运行引入了更复杂的状态冲突，v3.11.1 回滚为全量覆盖。当前设计为「请求地址和 API Key 是供应商独有，其他共享配置通过通用配置在供应商间传递」，明确表示暂不计划改为字段级合并。这些 issue 虽然都是 CLOSED，但并非代码修复，而是设计取舍（WONTFIX），#2096 标有 bug 标签且未提及修复版本，因此问题在所列版本内仍然存在。另有用户报告（#2096 评论）「从当前编辑器提取」功能有缺陷：它读取的是供应商数据库而不是磁盘上真实的 settings.json，且 token 被写成 PROXY_MANAGED 后 Claude Code 会要求重新登录。

Fix

Section titled “Fix”

  1. 把自定义配置迁移到「通用配置」：打开 cc-switch → 编辑供应商 → 通用配置面板 → 点击「从当前供应商提取」，把 hooks、enabledPlugins、spinnerVerbs 等非 env 字段提取进去；之后新建或切换供应商时保持勾选「写入通用配置」（默认勾选），即可在切换时保留这些配置。

  2. 如果涉及故障转移场景，把原 settings.json 中除 env 以外的全部内容，配置到每个要自动转移的供应商的「配置 JSON / 通用配置」里，避免转移后被重置。

  3. 可选的社区方案（非官方）：把自定义配置放入 `~/.claude/settings.local.json`（Claude Code 会深度合并且 local 优先级更高），但注意 statusline 等部分字段在该文件中不生效，仅影响模型、API、工具类配置。

  4. 可选的社区方案（非官方）：使用社区用户制作的 skill ccswitch-sync（https://github.com/MorisCat/ccswitch-sync）自动同步配置。

Affected Versions

Section titled “Affected Versions”
ToolClaude Code
Versioncc-switch 3.9.1 - 3.13.0（报告受影响版本；官方未发布字段级合并修复，v3.11.0 的合并尝试已在 v3.11.1 回滚）
PlatformsWindowsmacOS

Source Issues

Section titled “Source Issues”

本页汇总自 4 个真实 issue

FAQ

Section titled “FAQ”
把配置放到 settings.local.json 里能彻底解决吗？
只能部分解决。Claude Code 会先读 settings.json 再读 settings.local.json 并深度合并，local 同名键优先级更高；但用户实测 statusline 等配置放在 settings.local.json 中不生效，它主要影响模型、API、工具类配置。
为什么不直接改成增量合并（merge）？
官方回应：v3.11.0 尝试过字段级合并，但引入了更复杂的状态冲突问题，v3.11.1 回滚为全量覆盖。这是权衡后的设计决策，暂不计划改为字段级合并，建议通过「通用配置」功能传递共享配置。
切换后 ANTHROPIC_AUTH_TOKEN 变成 PROXY_MANAGED，Claude Code 要求重新登录怎么办？
这是代理模式下的正常写入值；用户报告重新保存一次 cc-switch 的供应商配置可暂时恢复。若 settings.json 被部分覆盖，可把完整配置（除 env 外）写入供应商的自定义 Config JSON 作为临时方案。
重启电脑后 enabledPlugins 被删除、插件全被禁用怎么办？
因为重启后 cc-switch 启动时会重新接管并全量重写 settings.json。把要启用的插件写入 cc-switch 的「通用配置」，切换/接管时勾选写入通用配置即可保留；不要只手动改 settings.json，它会和 cc-switch 数据库内容冲突。

相关问题

Section titled “相关问题”
供应商 API Key 被覆盖：Codex 重启或切换后升级到 cc-switch v4.0.0 或更高版本；该版本重写了切换逻辑，避免供应商密钥互相覆盖并恢复官方登录态。6 issues merged提示INVALID_API_KEY，Codex 切换供应商后认证不匹配升级至 v3.20.1 或更高版本；维护者称第三方切换不再写入 auth.json，避免供应商密钥与认证配置错配。5 issues mergedANTHROPIC_CUSTOM_HEADERS 未被保存 - Claude Code更新到包含 PR #2929 的版本后重新导入，Deep Link 的 config.env 自定义字段会被保留。1 issues merged

这是一个非官方社区 wiki，与 cc-switch 作者及项目本身无隶属关系。内容整理自项目公开的 GitHub issues。本站不分发任何软件。