Skip to content
CC Switch WikiUnofficial Community Wiki

settings.json overwritten by cc-switch causing custom configuration loss (Claude Code)

Quick fix

Write non-env custom settings to “General Configuration” and select “Write General Configuration”; field-level merging is not planned.

Symptom

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

When cc-switch switches providers, it **fully overwrites** the `~/.claude/settings.json` file, causing carefully configured **spinnerVerbs (custom loading verbs)** and all other personal configuration to be lost.

Cause

Section titled “Cause”

When cc-switch takes over or switches providers, saves provider edits (including model changes), performs automatic failover, or starts after a restart, it fully rewrites ~/.claude/settings.json using the current provider configuration stored in its database. It retains only proxy fields such as ANTHROPIC_AUTH_TOKEN: PROXY_MANAGED and ANTHROPIC_BASE_URL: http://127.0.0.1:15721; manually added hooks, permissions, enabledPlugins, spinnerVerbs, and contextFiles are removed.

In #1570, the official response said v3.11.0 tried field-level merge, but it caused more complex state conflicts in practice, so v3.11.1 reverted to full overwrite. The current design treats request URLs and API keys as provider-specific, while shared settings are passed through General Configuration. It does not plan to change to field-level merging. Although these issues are CLOSED, they are a design tradeoff (WONTFIX), not a code fix. #2096 has a bug label but no stated fix version, so the issue remains in the listed versions. A user also reported in #2096 comments that “Extract from current editor” reads the provider database rather than the actual settings.json on disk; after a token is written as PROXY_MANAGED, Claude Code asks the user to sign in again.

Fix

Section titled “Fix”

  1. Move custom settings to “General Configuration”: open cc-switch → edit the provider → General Configuration panel → click “Extract from Current Provider” to extract non-env fields such as hooks, enabledPlugins, and spinnerVerbs. When creating or switching providers, keep “Write General Configuration” selected (selected by default) to preserve these settings during switching.

  2. For failover scenarios, configure all non-env content from the original settings.json in the “Configuration JSON / General Configuration” of every provider that may receive automatic failover, to prevent it from being reset after failover.

  3. Optional community workaround (unofficial): put custom settings in `~/.claude/settings.local.json` (Claude Code performs a deep merge and local has higher priority). Note that some fields, such as statusline, do not work in this file; it only affects model, API, and tool-related settings.

  4. Optional community workaround (unofficial): use the community-created skill ccswitch-sync (https://github.com/MorisCat/ccswitch-sync) to synchronize configuration automatically.

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”

This page is distilled from 4 real issues

FAQ

Section titled “FAQ”
Does putting configuration in settings.local.json solve it completely?
Only partially. Claude Code reads settings.json first, then settings.local.json, and deep-merges them; local keys with the same name have higher priority. However, users found that settings such as statusline do not work in settings.local.json; it mainly affects model, API, and tool-related settings.
Why not change directly to incremental merge (merge)?
Official response: v3.11.0 tried field-level merging, but it introduced more complex state conflicts, so v3.11.1 reverted to full overwrite. This is a design decision after weighing the tradeoffs. Field-level merging is not currently planned; use “General Configuration” to pass shared settings.
After switching, ANTHROPIC_AUTH_TOKEN becomes PROXY_MANAGED and Claude Code asks me to sign in again. What should I do?
This is the normal value written in proxy mode; users reported that saving the cc-switch provider configuration again can temporarily restore it. If settings.json is partially overwritten, write the complete configuration except env into the provider’s custom Config JSON as a temporary workaround.
After restarting the computer, enabledPlugins is removed and all plugins are disabled. What should I do?
After a restart, cc-switch takes over again and fully rewrites settings.json. Add the plugins to enable to cc-switch’s “General Configuration” and select writing General Configuration during switching/takeover to preserve them. Do not edit only settings.json manually, because it conflicts with the cc-switch database content.
Section titled “Related problems”
Provider API Key Overwritten: After Codex Restart or SwitchUpgrade to cc-switch v4.0.0 or later to prevent provider keys from overwriting each other and restore the official login state.6 issues mergedINVALID_API_KEY after switching providers in CodexUpgrade to v3.20.1 or later; third-party switching no longer writes to `auth.json`, preventing provider key/authentication mismatches.5 issues mergedANTHROPIC_CUSTOM_HEADERS not saved - Claude CodeUpdate to a version that includes PR #2929 and re-import; the Deep Link's config.env custom fields are preserved.1 issues merged

This is an unofficial community wiki with no affiliation to the cc-switch authors or the project itself. Its content is compiled from the project's public GitHub issues. This site distributes no software.