cc-switch 配置文件详解:数据存储、SSOT 机制与各 CLI 工具配置落盘【免费下载链接】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 的官方 FAQ 文档 5.1 Configuration Files 展开,系统讲解 cc-switch 自身的数据存储结构(~/.cc-switch/目录、SQLite 数据库、设备级设置与自动备份),以及它对 Claude Code、Codex、Gemini CLI、OpenCode、Hermes、OpenClaw 六款 CLI 工具配置文件的读写规则与优先级机制。读完本篇,你将能够准确定位各类配置文件的默认路径与字段含义,理解数据库为单一事实来源(SSOT) 实时配置文件回写 手动修改回填的同步模型,并掌握安全地手动编辑与跨设备迁移配置的操作方法。一、cc-switch 的数据存储1.1 存储目录cc-switch 自身数据默认存放在用户主目录下的~/.cc-switch/,并且可以在设置中自定义该目录位置(便于配合云同步方案)。从源码实现看,目录解析逻辑位于 get_app_config_dir:若用户在设置中指定了自定义目录(app_config_dir覆盖项),优先使用自定义值;否则回落到~/.cc-switch/;在 Windows 上还有一个兼容逻辑:旧版本 v3.10.3 曾直接读取HOME环境变量,可能与真实用户目录不一致。当默认位置不存在数据库、而HOME指向的旧位置存在cc-switch.db时,代码会自动回退到旧位置,避免供应商凭空消失的数据丢失观感;测试环境下可通过CC_SWITCH_TEST_HOME环境变量显式覆盖 home 目录,用于 CI 隔离真实用户数据(见 get_home_dir 的注释说明)。1.2 目录结构~/.cc-switch/ ├── cc-switch.db # SQLite 数据库 (SSOT) ├── settings.json # 设备级设置 ├── skills/ # Skill SSOT 目录 ├── skill-backups/ # Skill 备份(卸载时创建) └── backups/ # 数据库备份各目录职责与源码对应关系:目录/文件职责源码依据cc-switch.dbSQLite 数据库,所有核心配置的单一事实来源(SSOT),路径由 Database 初始化 拼接get_app_config_dir()/cc-switch.db得到src-tauri/src/database/mod.rssettings.json设备级设置(语言、主题、窗口行为等,不跨设备同步)src-tauri/src/settings.rsskills/Skill 的 SSOT 存储目录,v3.10.0 起 Skills 的 SSOT 从数据库迁移到文件系统 数据库统一结构,实际文件存放在此处,再同步到各应用目录src-tauri/src/commands/skill.rs、src-tauri/src/database/dao/skills.rsskill-backups/卸载 Skill 时创建的备份官方文档说明backups/自动数据库备份,详见 1.5 节src-tauri/src/database/backup.rs1.3 数据库内容cc-switch.db是一个 SQLite 数据库,按官方文档记载,其承载的核心表包括:表内容providers供应商配置provider_endpoints供应商端点候选列表mcp_serversMCP 服务器配置prompts提示词预设skillsSkill 安装状态skill_reposSkill 仓库配置proxy_config代理配置proxy_request_logs代理请求日志provider_health供应商健康状态model_pricing模型定价settings应用设置结合 schema.rs 中的建表语句,可以进一步确认这些表的结构与默认值,例如:providers表以(id, app_type)为复合主键,settings_config字段存放供应商的完整配置 JSON,is_current标记当前激活供应商,in_failover_queue标记是否参与故障转移队列,meta存放扩展元数据(默认{});provider_endpoints通过外键ON DELETE CASCADE级联删除,即删除供应商时其端点候选一并清理;mcp_servers表为每个受支持的应用(codex、claude、gemini、grokbuild、opencode、hermes 等)维护独立的启用开关位(如enabled_claude、enabled_codex);proxy_config表为按应用分行的三行结构(app_type为主键,取值claude/codex/gemini/grokbuild),内置监听地址127.0.0.1、默认端口15721、重试次数、流式首字节/空闲超时、熔断器阈值等默认值,建库时会INSERT OR IGNORE注入四个应用的种子默认值(如 claude 的max_retries6、streaming_first_byte_timeout90,codex 的max_retries3、streaming_first_byte_timeout60等,见 schema.rs#L126-L183);proxy_request_logs记录每次代理请求的 token 数、分维度费用(input/output/cache read/cache creation)、延迟、状态码等,并按(provider_id, app_type)、created_at、model、session_id、status_code建立索引以支撑用量查询。除文档列出的核心表外,schema 中还包含stream_check_logs(流检查记录)、proxy_live_backup(live 配置备份)、usage_daily_rollups(日聚合统计)、session_log_sync、session_usage_dedup、profiles(项目级 Profile)等辅助表,从源码结构看,这些主要服务于用量统计与路由接管能力,不属于用户手工管理范畴。1.4 设备级设置 settings.jsonsettings.json存放设备级设置,典型内容如下:{ language: zh, theme: system, windowBehavior: minimize, autoStart: false, claudeConfigDir: null, codexConfigDir: null, geminiConfigDir: null, opencodeConfigDir: null, openclawConfigDir: null, hermesConfigDir: null }要点:前几项(语言、主题、关闭行为、自启动)只影响本机体验,官方文档明确说明这些设置不会在设备间同步;各*ConfigDir字段默认为null,表示使用默认配置目录;一旦填值,cc-switch 就会改写目标应用的配置目录。这一点在源码中有直接印证,例如 get_claude_config_dir:若存在自定义的 Claude 配置目录则直接返回,否则回落到~/.claude;从源码结构看,设备级设置的解析结构定义在 src-tauri/src/settings.rs,其中还包含应用可见性开关(如visibleApps中 Hermes 默认不显示,需手动启用)与 WebDAV 云同步设置等扩展字段,说明该文件的实际内容可能比上例更丰富,新增字段均以序列化默认值兼容旧版本。1.5 自动备份backups/目录存放自动创建的数据库备份:每次配置导入前自动创建;保留最近 10 份;文件名包含时间戳。源码层面(backup.rs)可以看到更完整的备份策略:备份命名形如db_backup_YYYYMMDD_HHMMSS.db,时间戳取自本地时间;若同一秒内产生多份备份,会追加_1、_2后缀避免冲突;备份并非简单复制文件,而是先写入.cc-switch-backup-*.tmp临时文件,通过 SQLite 在线 Backup API 完整复制数据库,再执行validate_sqlite_integrity完整性校验,最后才原子发布为最终文件名——备份发现与保留计数只会在完整镜像发布后看到最终路径;保留清理时,新创建的安全备份与被恢复选中的源文件都被列入受保护清单,绝不会被清理任务误删;若保留配额小到同时容纳不下两者,代码选择临时超出配额而不是删除恢复操作的任意一侧;其他特殊场景的备份也落在该目录下,例如 Codex 官方历史统一迁移前,会把jsonl/state DB 备份到~/.cc-switch/backups/codex-official-history-unify-v1/(见 codex_history_migration.rs)。二、各 CLI 工具的配置目录与关键文件cc-switch 的核心工作方式是:把各 CLI 工具的供应商/密钥/端点配置统一管进自己的数据库,切换供应商时再落盘到各工具的实时配置文件。下面按工具逐一说明默认目录、关键文件与字段含义。2.1 Claude Code默认配置目录:~/.claude/~/.claude/ ├── settings.json # 主配置文件 ├── CLAUDE.md # 系统提示词 └── skills/ # Skills 目录 └── ...settings.json示例:{ env: { ANTHROPIC_API_KEY: sk-xxx, ANTHROPIC_BASE_URL: https://api.anthropic.com }, permissions: { allow_file_access: true } }字段说明env.ANTHROPIC_API_KEYAPI Keyenv.ANTHROPIC_BASE_URLAPI 端点(可选)env.ANTHROPIC_AUTH_TOKEN替代认证方式MCP 服务器配置不在~/.claude/内,而是位于家目录下的~/.claude.json:{ mcpServers: { mcp-fetch: { command: uvx, args: [mcp-server-fetch] } } }源码中有两处值得注意的实现细节:主配置文件路径由 get_claude_settings_path 解析:优先使用settings.json;若存在旧版命名的claude.json则继续沿用(向后兼容);否则回落到标准名settings.json,新文件不再生成为claude.json;MCP 路径解析在 get_claude_mcp_path:默认即~/.claude.json;当用户自定义了 Claude 配置目录且该目录恰好是默认~/.claude时,MCP 仍取根目录的~/.claude.json;在 Windows 下若自定义目录是 WSL UNC 路径(如\\wsl$\Ubuntu\home\user\.claude),代码会把 MCP 文件定位到 WSL 内的~/.claude.json而非嵌套的.claude/.claude.json(相关逻辑与用例见 config.rs#L113-L169 及测试wsl_unc_home_default_uses_split_mcp_path)。2.2 Codex默认配置目录:~/.codex/~/.codex/ ├── auth.json # 认证配置 ├── config.toml # 主配置 MCP └── AGENTS.md # 系统提示词auth.json:{ OPENAI_API_KEY: sk-xxx }config.toml:# 基础配置 base_url https://api.openai.com/v1 model gpt-4 # MCP 服务器 [mcp_servers.mcp-fetch] command uvx args [mcp-server-fetch]base_url与model是供应商切换时最常变化的字段;[mcp_servers.*]段与 Claude 的mcpServers对象一一对应,只是序列化为 TOML 表。cc-switch 对 Codex 配置目录的读写统一经由 src-tauri/src/codex_config.rs,官方历史数据统一迁移(仅迁移本机~/.codex历史、完成标记写入设备级settings.json)的实现见 src-tauri/src/codex_history_migration.rs。2.3 Gemini CLI默认配置目录:~/.gemini/~/.gemini/ ├── .env # 环境变量(API Key) ├── settings.json # 主配置 MCP └── GEMINI.md # 系统提示词.env:GEMINI_API_KEYxxx GOOGLE_GEMINI_BASE_URLhttps://generativelanguage.googleapis.com GEMINI_MODELgemini-prosettings.json(仅存放 MCP 配置):{ mcpServers: { mcp-fetch: { command: uvx, args: [mcp-server-fetch] } } }字段说明mcpServersMCP 服务器配置源码印证:MCP 读写集中在 gemini_mcp.rs,其注释明确Gemini MCP 配置文件路径为~/.gemini/settings.json,写入时先读取现有文件、要求根节点是对象,再更新mcpServers映射。另外 gemini_config.rs 显示settings.json还会被用于写入security.auth.selectedType等认证字段(例如 Google 官方 OAuth 模式与第三方 API 模式的切换),这是官方文档未展开但实际会触碰到的字段。2.4 OpenCode默认配置目录:~/.config/opencode/~/.config/opencode/ ├── opencode.json # 主配置文件 ├── AGENTS.md # 系统提示词 └── skills/ # Skills 目录 └── ...OpenCode 使用opencode.json作为主配置,供应商信息写入其中的模型/供应商段;具体解析与写入逻辑见 src-tauri/src/opencode_config.rs。注意其默认目录遵循 XDG 约定(~/.config/前缀),与其余工具的~/.隐藏目录约定不同,在手动查找文件时容易遗漏。2.5 Hermes默认配置目录:~/.hermes/~/.hermes/ ├── config.yaml # 主配置:设置、供应商与 MCP 配置 ├── .env # API Key 与密钥 ├── SOUL.md # 角色身份/人格 ├── memories/ │ ├── MEMORY.md # Agent 记忆 │ └── USER.md # 用户画像记忆 ├── skills/ # 生效的 Skills 目录 ├── state.db # SQLite 会话数据库 └── sessions/ # Gateway 转录与可选 JSON 快照config.yaml使用 YAML 格式,cc-switch 对其的读写约定如下:MCP 服务器写入mcp_servers段;可编辑的供应商条目写入custom_providers;只读条目来自 Hermes 自身的providers字典(cc-switch 只读取、不覆盖);切换供应商时更新model.provider/model.default字段。相关实现见 src-tauri/src/hermes_config.rs,YAML 解析与custom_providers/mcp_servers段的处理逻辑都集中于此;Hermes 在 cc-switch 中属于默认不显示的应用(见 settings.rs 中 VisibleApps 默认值),需在设置中手动启用后才会出现在管理界面。2.6 OpenClaw默认配置目录:~/.openclaw/~/.openclaw/ ├── openclaw.json # 主配置文件(JSON5 格式) └── skills/ # Skills 目录 └── ...openclaw.json采用 JSON5 格式(允许注释与非引号键名),主要段落:{ // 模型供应商配置 models: { mode: merge, providers: { custom-provider: { baseUrl: https://api.example.com/v1, apiKey: your-api-key, api: openai-completions, models: [{ id: model-id, name: Model Name }] } } }, // 环境变量 env: { ANTHROPIC_API_KEY: sk-... }, // Agent 默认配置 agents: { defaults: { model: { primary: provider/model }, workspace: ~/.openclaw/workspace } }, // 工具配置 tools: {} }字段说明models.providers供应商配置(映射到 cc-switch 的供应商)env环境变量配置agents.defaultsAgent 默认模型设置tools工具配置agents.defaults.workspace工作区目录路径models.mode: merge表示自定义供应商与内置供应商合并生效;agents.defaults.model.primary采用provider/model的寻址格式,是切换供应商后实际路由的落点。三、配置优先级与回填机制cc-switch 修改配置时遵循固定的优先级顺序:cc-switch 数据库—— 单一事实来源(SSOT),所有界面操作最终都持久化到这里;实时配置文件—— 切换供应商时,把数据库中的配置写回对应 CLI 工具的 live 文件(如~/.claude/settings.json、~/.codex/config.toml);回填(backfill)机制—— 在 cc-switch 中编辑当前供应商时,会先读取 live 文件的最新内容,把用户在文件里的手动修改反映到编辑表单中,保存后再同步回数据库。这一数据库优先、文件可回填的双向模型,解释了为什么 cc-switch 可以放心地改写外部 CLI 工具的配置,又不会丢失用户的手动修改。从源码结构看,写入侧还有一套保证一致性的细节,位于 src-tauri/src/config.rs:确定性序列化:写 JSON 前会递归按键字母序排序(sort_json_keys),同一逻辑配置无论键的插入顺序如何,写出的字节序列完全一致——这降低了文件级 diff/同步工具产生无意义变更的概率,相关行为由sort_json_keys_*系列单测锁定;原子写入:atomic_write 先写临时文件(文件名.tmp.pid.ns.counter)再 rename 替换,避免半写状态损坏 CLI 工具的配置;Unix 上包含凭据的文件(如 API Key)通过atomic_write_private固定使用0600权限;Windows 兼容:替换时优先调用ReplaceFileW,对 WSL UNC 路径不支持替换的情形降级为rename,并有专门的CC_SWITCH_WSL_TEST_DIR集成测试覆盖。四、手动编辑配置的边界4.1 可以安全手动编辑各 CLI 工具自己的配置文件(~/.claude/settings.json、~/.codex/config.toml等)——cc-switch 会在编辑当前供应商时将其回填;cc-switch 的settings.json(设备级设置)。4.2 不建议手动编辑cc-switch.db数据库文件(它是 SQLite 二进制,手工改动极易破坏完整性;备份恢复应使用应用内功能);backups/目录下的备份文件。4.3 手动编辑后的同步步骤如果你直接改了 CLI 工具的配置:打开 cc-switch;编辑对应供应商;此时应能看到手动修改已被回填到表单;保存,将改动同步回数据库。跳过保存这一步的话,下次在 cc-switch 中切换供应商,数据库里的旧值会覆盖你的手动修改——这就是数据库是 SSOT的直接后果,值得在操作时留意。五、配置迁移与备份5.1 从旧版本迁移cc-switch v3.7.0 起数据层从 JSON 文件迁移到 SQLite:首次启动时自动迁移;迁移成功后显示通知;旧配置文件保留为备份,不会删除。另外,更早的 v1 版 JSON 格式(~/.cc-switch/config.json顶层无version: 2结构)在当前版本已不再支持运行时自动迁移,源码中的处理是弹出诊断信息,提示用户安装 v3.2.x 版本执行一次性迁移,或手动把顶层结构调整为{version: 2, claude: {...}, codex: {...}, mcp: {...}}形式(见 app_config.rs#L611-L612);迁移前旧配置会被备份为~/.cc-switch/config.json.bak。数据库层自身的增量 schema 迁移则统一由 database/migration.rs 在打开数据库时应用。5.2 跨设备迁移在源设备导出配置;在目标设备导入配置;或者直接使用云同步功能(WebDAV 同步设置见 src-tauri/src/settings.rs 中的WebDavSyncSettings结构)。每次导入前会自动触发数据库安全备份(见 1.5 节),因此导入操作自带回滚路径。5.3 备份建议定期备份:设置 → 高级 → 数据管理,点击导出,将文件保存到安全位置。导出内容:全部供应商配置;MCP 服务器配置;提示词预设;应用设置。不包含的内容:用量日志(数据量大);设备级设置(不适合跨设备,如窗口行为、自启动、本机自定义配置目录等)。六、要点回顾关注点结论数据总目录~/.cc-switch/,可在设置中自定义;数据库cc-switch.db是 SSOT核心表providers、provider_endpoints、mcp_servers、prompts、skills、skill_repos、proxy_config、proxy_request_logs、provider_health、model_pricing、settings,定义见 schema.rs设备级设置settings.json,不跨设备同步,包含各工具配置目录覆盖项自动备份backups/下保留最近 10 份带时间戳的 SQLite 安全备份,导入前自动创建各工具落盘Claude:~/.claude/~/.claude.json;Codex:~/.codex/;Gemini:~/.gemini/;OpenCode:~/.config/opencode/;Hermes:~/.hermes/;OpenClaw:~/.openclaw/优先级数据库 → live 配置文件 → 编辑时回填手动编辑CLI 配置文件可改(记得回应用内保存);cc-switch.db与备份文件不建议手改理解这套SSOT 落盘 回填的模型后,无论是排查为什么界面里的供应商和 CLI 实际读到的不一致,还是规划多设备云同步方案,都可以依据本文的路径与源码定位快速定位问题。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 cc-switch 配置文件详解:数据存储、SSOT 机制与各 CLI 工具配置落盘
cc-switch 配置文件详解:数据存储、SSOT 机制与各 CLI 工具配置落盘【免费下载链接】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 的官方 FAQ 文档 5.1 Configuration Files 展开,系统讲解 cc-switch 自身的数据存储结构(~/.cc-switch/目录、SQLite 数据库、设备级设置与自动备份),以及它对 Claude Code、Codex、Gemini CLI、OpenCode、Hermes、OpenClaw 六款 CLI 工具配置文件的读写规则与优先级机制。读完本篇,你将能够准确定位各类配置文件的默认路径与字段含义,理解数据库为单一事实来源(SSOT) 实时配置文件回写 手动修改回填的同步模型,并掌握安全地手动编辑与跨设备迁移配置的操作方法。一、cc-switch 的数据存储1.1 存储目录cc-switch 自身数据默认存放在用户主目录下的~/.cc-switch/,并且可以在设置中自定义该目录位置(便于配合云同步方案)。从源码实现看,目录解析逻辑位于 get_app_config_dir:若用户在设置中指定了自定义目录(app_config_dir覆盖项),优先使用自定义值;否则回落到~/.cc-switch/;在 Windows 上还有一个兼容逻辑:旧版本 v3.10.3 曾直接读取HOME环境变量,可能与真实用户目录不一致。当默认位置不存在数据库、而HOME指向的旧位置存在cc-switch.db时,代码会自动回退到旧位置,避免供应商凭空消失的数据丢失观感;测试环境下可通过CC_SWITCH_TEST_HOME环境变量显式覆盖 home 目录,用于 CI 隔离真实用户数据(见 get_home_dir 的注释说明)。1.2 目录结构~/.cc-switch/ ├── cc-switch.db # SQLite 数据库 (SSOT) ├── settings.json # 设备级设置 ├── skills/ # Skill SSOT 目录 ├── skill-backups/ # Skill 备份(卸载时创建) └── backups/ # 数据库备份各目录职责与源码对应关系:目录/文件职责源码依据cc-switch.dbSQLite 数据库,所有核心配置的单一事实来源(SSOT),路径由 Database 初始化 拼接get_app_config_dir()/cc-switch.db得到src-tauri/src/database/mod.rssettings.json设备级设置(语言、主题、窗口行为等,不跨设备同步)src-tauri/src/settings.rsskills/Skill 的 SSOT 存储目录,v3.10.0 起 Skills 的 SSOT 从数据库迁移到文件系统 数据库统一结构,实际文件存放在此处,再同步到各应用目录src-tauri/src/commands/skill.rs、src-tauri/src/database/dao/skills.rsskill-backups/卸载 Skill 时创建的备份官方文档说明backups/自动数据库备份,详见 1.5 节src-tauri/src/database/backup.rs1.3 数据库内容cc-switch.db是一个 SQLite 数据库,按官方文档记载,其承载的核心表包括:表内容providers供应商配置provider_endpoints供应商端点候选列表mcp_serversMCP 服务器配置prompts提示词预设skillsSkill 安装状态skill_reposSkill 仓库配置proxy_config代理配置proxy_request_logs代理请求日志provider_health供应商健康状态model_pricing模型定价settings应用设置结合 schema.rs 中的建表语句,可以进一步确认这些表的结构与默认值,例如:providers表以(id, app_type)为复合主键,settings_config字段存放供应商的完整配置 JSON,is_current标记当前激活供应商,in_failover_queue标记是否参与故障转移队列,meta存放扩展元数据(默认{});provider_endpoints通过外键ON DELETE CASCADE级联删除,即删除供应商时其端点候选一并清理;mcp_servers表为每个受支持的应用(codex、claude、gemini、grokbuild、opencode、hermes 等)维护独立的启用开关位(如enabled_claude、enabled_codex);proxy_config表为按应用分行的三行结构(app_type为主键,取值claude/codex/gemini/grokbuild),内置监听地址127.0.0.1、默认端口15721、重试次数、流式首字节/空闲超时、熔断器阈值等默认值,建库时会INSERT OR IGNORE注入四个应用的种子默认值(如 claude 的max_retries6、streaming_first_byte_timeout90,codex 的max_retries3、streaming_first_byte_timeout60等,见 schema.rs#L126-L183);proxy_request_logs记录每次代理请求的 token 数、分维度费用(input/output/cache read/cache creation)、延迟、状态码等,并按(provider_id, app_type)、created_at、model、session_id、status_code建立索引以支撑用量查询。除文档列出的核心表外,schema 中还包含stream_check_logs(流检查记录)、proxy_live_backup(live 配置备份)、usage_daily_rollups(日聚合统计)、session_log_sync、session_usage_dedup、profiles(项目级 Profile)等辅助表,从源码结构看,这些主要服务于用量统计与路由接管能力,不属于用户手工管理范畴。1.4 设备级设置 settings.jsonsettings.json存放设备级设置,典型内容如下:{ language: zh, theme: system, windowBehavior: minimize, autoStart: false, claudeConfigDir: null, codexConfigDir: null, geminiConfigDir: null, opencodeConfigDir: null, openclawConfigDir: null, hermesConfigDir: null }要点:前几项(语言、主题、关闭行为、自启动)只影响本机体验,官方文档明确说明这些设置不会在设备间同步;各*ConfigDir字段默认为null,表示使用默认配置目录;一旦填值,cc-switch 就会改写目标应用的配置目录。这一点在源码中有直接印证,例如 get_claude_config_dir:若存在自定义的 Claude 配置目录则直接返回,否则回落到~/.claude;从源码结构看,设备级设置的解析结构定义在 src-tauri/src/settings.rs,其中还包含应用可见性开关(如visibleApps中 Hermes 默认不显示,需手动启用)与 WebDAV 云同步设置等扩展字段,说明该文件的实际内容可能比上例更丰富,新增字段均以序列化默认值兼容旧版本。1.5 自动备份backups/目录存放自动创建的数据库备份:每次配置导入前自动创建;保留最近 10 份;文件名包含时间戳。源码层面(backup.rs)可以看到更完整的备份策略:备份命名形如db_backup_YYYYMMDD_HHMMSS.db,时间戳取自本地时间;若同一秒内产生多份备份,会追加_1、_2后缀避免冲突;备份并非简单复制文件,而是先写入.cc-switch-backup-*.tmp临时文件,通过 SQLite 在线 Backup API 完整复制数据库,再执行validate_sqlite_integrity完整性校验,最后才原子发布为最终文件名——备份发现与保留计数只会在完整镜像发布后看到最终路径;保留清理时,新创建的安全备份与被恢复选中的源文件都被列入受保护清单,绝不会被清理任务误删;若保留配额小到同时容纳不下两者,代码选择临时超出配额而不是删除恢复操作的任意一侧;其他特殊场景的备份也落在该目录下,例如 Codex 官方历史统一迁移前,会把jsonl/state DB 备份到~/.cc-switch/backups/codex-official-history-unify-v1/(见 codex_history_migration.rs)。二、各 CLI 工具的配置目录与关键文件cc-switch 的核心工作方式是:把各 CLI 工具的供应商/密钥/端点配置统一管进自己的数据库,切换供应商时再落盘到各工具的实时配置文件。下面按工具逐一说明默认目录、关键文件与字段含义。2.1 Claude Code默认配置目录:~/.claude/~/.claude/ ├── settings.json # 主配置文件 ├── CLAUDE.md # 系统提示词 └── skills/ # Skills 目录 └── ...settings.json示例:{ env: { ANTHROPIC_API_KEY: sk-xxx, ANTHROPIC_BASE_URL: https://api.anthropic.com }, permissions: { allow_file_access: true } }字段说明env.ANTHROPIC_API_KEYAPI Keyenv.ANTHROPIC_BASE_URLAPI 端点(可选)env.ANTHROPIC_AUTH_TOKEN替代认证方式MCP 服务器配置不在~/.claude/内,而是位于家目录下的~/.claude.json:{ mcpServers: { mcp-fetch: { command: uvx, args: [mcp-server-fetch] } } }源码中有两处值得注意的实现细节:主配置文件路径由 get_claude_settings_path 解析:优先使用settings.json;若存在旧版命名的claude.json则继续沿用(向后兼容);否则回落到标准名settings.json,新文件不再生成为claude.json;MCP 路径解析在 get_claude_mcp_path:默认即~/.claude.json;当用户自定义了 Claude 配置目录且该目录恰好是默认~/.claude时,MCP 仍取根目录的~/.claude.json;在 Windows 下若自定义目录是 WSL UNC 路径(如\\wsl$\Ubuntu\home\user\.claude),代码会把 MCP 文件定位到 WSL 内的~/.claude.json而非嵌套的.claude/.claude.json(相关逻辑与用例见 config.rs#L113-L169 及测试wsl_unc_home_default_uses_split_mcp_path)。2.2 Codex默认配置目录:~/.codex/~/.codex/ ├── auth.json # 认证配置 ├── config.toml # 主配置 MCP └── AGENTS.md # 系统提示词auth.json:{ OPENAI_API_KEY: sk-xxx }config.toml:# 基础配置 base_url https://api.openai.com/v1 model gpt-4 # MCP 服务器 [mcp_servers.mcp-fetch] command uvx args [mcp-server-fetch]base_url与model是供应商切换时最常变化的字段;[mcp_servers.*]段与 Claude 的mcpServers对象一一对应,只是序列化为 TOML 表。cc-switch 对 Codex 配置目录的读写统一经由 src-tauri/src/codex_config.rs,官方历史数据统一迁移(仅迁移本机~/.codex历史、完成标记写入设备级settings.json)的实现见 src-tauri/src/codex_history_migration.rs。2.3 Gemini CLI默认配置目录:~/.gemini/~/.gemini/ ├── .env # 环境变量(API Key) ├── settings.json # 主配置 MCP └── GEMINI.md # 系统提示词.env:GEMINI_API_KEYxxx GOOGLE_GEMINI_BASE_URLhttps://generativelanguage.googleapis.com GEMINI_MODELgemini-prosettings.json(仅存放 MCP 配置):{ mcpServers: { mcp-fetch: { command: uvx, args: [mcp-server-fetch] } } }字段说明mcpServersMCP 服务器配置源码印证:MCP 读写集中在 gemini_mcp.rs,其注释明确Gemini MCP 配置文件路径为~/.gemini/settings.json,写入时先读取现有文件、要求根节点是对象,再更新mcpServers映射。另外 gemini_config.rs 显示settings.json还会被用于写入security.auth.selectedType等认证字段(例如 Google 官方 OAuth 模式与第三方 API 模式的切换),这是官方文档未展开但实际会触碰到的字段。2.4 OpenCode默认配置目录:~/.config/opencode/~/.config/opencode/ ├── opencode.json # 主配置文件 ├── AGENTS.md # 系统提示词 └── skills/ # Skills 目录 └── ...OpenCode 使用opencode.json作为主配置,供应商信息写入其中的模型/供应商段;具体解析与写入逻辑见 src-tauri/src/opencode_config.rs。注意其默认目录遵循 XDG 约定(~/.config/前缀),与其余工具的~/.隐藏目录约定不同,在手动查找文件时容易遗漏。2.5 Hermes默认配置目录:~/.hermes/~/.hermes/ ├── config.yaml # 主配置:设置、供应商与 MCP 配置 ├── .env # API Key 与密钥 ├── SOUL.md # 角色身份/人格 ├── memories/ │ ├── MEMORY.md # Agent 记忆 │ └── USER.md # 用户画像记忆 ├── skills/ # 生效的 Skills 目录 ├── state.db # SQLite 会话数据库 └── sessions/ # Gateway 转录与可选 JSON 快照config.yaml使用 YAML 格式,cc-switch 对其的读写约定如下:MCP 服务器写入mcp_servers段;可编辑的供应商条目写入custom_providers;只读条目来自 Hermes 自身的providers字典(cc-switch 只读取、不覆盖);切换供应商时更新model.provider/model.default字段。相关实现见 src-tauri/src/hermes_config.rs,YAML 解析与custom_providers/mcp_servers段的处理逻辑都集中于此;Hermes 在 cc-switch 中属于默认不显示的应用(见 settings.rs 中 VisibleApps 默认值),需在设置中手动启用后才会出现在管理界面。2.6 OpenClaw默认配置目录:~/.openclaw/~/.openclaw/ ├── openclaw.json # 主配置文件(JSON5 格式) └── skills/ # Skills 目录 └── ...openclaw.json采用 JSON5 格式(允许注释与非引号键名),主要段落:{ // 模型供应商配置 models: { mode: merge, providers: { custom-provider: { baseUrl: https://api.example.com/v1, apiKey: your-api-key, api: openai-completions, models: [{ id: model-id, name: Model Name }] } } }, // 环境变量 env: { ANTHROPIC_API_KEY: sk-... }, // Agent 默认配置 agents: { defaults: { model: { primary: provider/model }, workspace: ~/.openclaw/workspace } }, // 工具配置 tools: {} }字段说明models.providers供应商配置(映射到 cc-switch 的供应商)env环境变量配置agents.defaultsAgent 默认模型设置tools工具配置agents.defaults.workspace工作区目录路径models.mode: merge表示自定义供应商与内置供应商合并生效;agents.defaults.model.primary采用provider/model的寻址格式,是切换供应商后实际路由的落点。三、配置优先级与回填机制cc-switch 修改配置时遵循固定的优先级顺序:cc-switch 数据库—— 单一事实来源(SSOT),所有界面操作最终都持久化到这里;实时配置文件—— 切换供应商时,把数据库中的配置写回对应 CLI 工具的 live 文件(如~/.claude/settings.json、~/.codex/config.toml);回填(backfill)机制—— 在 cc-switch 中编辑当前供应商时,会先读取 live 文件的最新内容,把用户在文件里的手动修改反映到编辑表单中,保存后再同步回数据库。这一数据库优先、文件可回填的双向模型,解释了为什么 cc-switch 可以放心地改写外部 CLI 工具的配置,又不会丢失用户的手动修改。从源码结构看,写入侧还有一套保证一致性的细节,位于 src-tauri/src/config.rs:确定性序列化:写 JSON 前会递归按键字母序排序(sort_json_keys),同一逻辑配置无论键的插入顺序如何,写出的字节序列完全一致——这降低了文件级 diff/同步工具产生无意义变更的概率,相关行为由sort_json_keys_*系列单测锁定;原子写入:atomic_write 先写临时文件(文件名.tmp.pid.ns.counter)再 rename 替换,避免半写状态损坏 CLI 工具的配置;Unix 上包含凭据的文件(如 API Key)通过atomic_write_private固定使用0600权限;Windows 兼容:替换时优先调用ReplaceFileW,对 WSL UNC 路径不支持替换的情形降级为rename,并有专门的CC_SWITCH_WSL_TEST_DIR集成测试覆盖。四、手动编辑配置的边界4.1 可以安全手动编辑各 CLI 工具自己的配置文件(~/.claude/settings.json、~/.codex/config.toml等)——cc-switch 会在编辑当前供应商时将其回填;cc-switch 的settings.json(设备级设置)。4.2 不建议手动编辑cc-switch.db数据库文件(它是 SQLite 二进制,手工改动极易破坏完整性;备份恢复应使用应用内功能);backups/目录下的备份文件。4.3 手动编辑后的同步步骤如果你直接改了 CLI 工具的配置:打开 cc-switch;编辑对应供应商;此时应能看到手动修改已被回填到表单;保存,将改动同步回数据库。跳过保存这一步的话,下次在 cc-switch 中切换供应商,数据库里的旧值会覆盖你的手动修改——这就是数据库是 SSOT的直接后果,值得在操作时留意。五、配置迁移与备份5.1 从旧版本迁移cc-switch v3.7.0 起数据层从 JSON 文件迁移到 SQLite:首次启动时自动迁移;迁移成功后显示通知;旧配置文件保留为备份,不会删除。另外,更早的 v1 版 JSON 格式(~/.cc-switch/config.json顶层无version: 2结构)在当前版本已不再支持运行时自动迁移,源码中的处理是弹出诊断信息,提示用户安装 v3.2.x 版本执行一次性迁移,或手动把顶层结构调整为{version: 2, claude: {...}, codex: {...}, mcp: {...}}形式(见 app_config.rs#L611-L612);迁移前旧配置会被备份为~/.cc-switch/config.json.bak。数据库层自身的增量 schema 迁移则统一由 database/migration.rs 在打开数据库时应用。5.2 跨设备迁移在源设备导出配置;在目标设备导入配置;或者直接使用云同步功能(WebDAV 同步设置见 src-tauri/src/settings.rs 中的WebDavSyncSettings结构)。每次导入前会自动触发数据库安全备份(见 1.5 节),因此导入操作自带回滚路径。5.3 备份建议定期备份:设置 → 高级 → 数据管理,点击导出,将文件保存到安全位置。导出内容:全部供应商配置;MCP 服务器配置;提示词预设;应用设置。不包含的内容:用量日志(数据量大);设备级设置(不适合跨设备,如窗口行为、自启动、本机自定义配置目录等)。六、要点回顾关注点结论数据总目录~/.cc-switch/,可在设置中自定义;数据库cc-switch.db是 SSOT核心表providers、provider_endpoints、mcp_servers、prompts、skills、skill_repos、proxy_config、proxy_request_logs、provider_health、model_pricing、settings,定义见 schema.rs设备级设置settings.json,不跨设备同步,包含各工具配置目录覆盖项自动备份backups/下保留最近 10 份带时间戳的 SQLite 安全备份,导入前自动创建各工具落盘Claude:~/.claude/~/.claude.json;Codex:~/.codex/;Gemini:~/.gemini/;OpenCode:~/.config/opencode/;Hermes:~/.hermes/;OpenClaw:~/.openclaw/优先级数据库 → live 配置文件 → 编辑时回填手动编辑CLI 配置文件可改(记得回应用内保存);cc-switch.db与备份文件不建议手改理解这套SSOT 落盘 回填的模型后,无论是排查为什么界面里的供应商和 CLI 实际读到的不一致,还是规划多设备云同步方案,都可以依据本文的路径与源码定位快速定位问题。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考