cc-switch 配置文件完全指南：从 ~/.cc-switch 存储布局到 SQLite SSOT 与各 CLI 配置文件的映射

本文以 cc-switch 官方用户手册的配置文件说明（docs/user-manual/ja/5-faq/5.1-config-files.md）为核心，完整梳理 cc-switch 自身的数据存储布局（~/.cc-switch/）、SQLite 数据库（SSOT）中的表结构、设备级 settings.json 的字段含义，以及它对 Claude Code、Codex、Gemini CLI、OpenCode、Hermes、OpenClaw 六类 CLI 配置文件（settings.json、config.toml、.env、config.yaml、JSON5 等）的读写规则与同步策略。读完本文，你将能够准确定位 cc-switch 的每一类数据文件、理解「数据库 → Live 配置文件 → 回填」的优先级链路，并在手动编辑、迁移与备份时做出正确的操作。

CC Switch 的数据存储

存储目录与自定义

cc-switch 的默认数据目录是 ~/.cc-switch/，所有应用级数据（数据库、设备设置、技能、备份）都集中在这里。该目录可以在设置中自定义，主要用于跨设备云同步场景。

从源码看，目录解析逻辑位于 src-tauri/src/config.rs 的 get_app_config_dir()：优先读取应用存储中的自定义目录覆盖值，否则回落到 <用户主目录>/.cc-switch/。该函数还包含一段针对 Windows 的兼容逻辑——若默认位置没有数据库而旧版 HOME 环境变量下存在遗留的 cc-switch.db，会回退到旧位置，避免「供应商凭空消失」的假象。另外 src-tauri/src/config.rs 的 get_home_dir() 注释明确指出：Windows 下刻意不用 HOME 环境变量，因为它可能被 Git/Cygwin/MSYS 等工具改写，导致数据库路径漂移。

目录结构

~/.cc-switch/
├── cc-switch.db      # SQLite 数据库（SSOT，单一事实源）
├── settings.json     # 设备级设置
├── skills/           # 技能 SSOT 目录
├── skill-backups/    # 技能备份（卸载时创建）
└── backups/          # 数据库备份

数据库内容：cc-switch.db 的表结构

cc-switch.db 是一个 SQLite 数据库，承载了 cc-switch 的全部可同步数据。文档列出的核心表如下：

表	内容
providers	供应商（Provider）配置
provider_endpoints	供应商端点候选列表
mcp_servers	MCP 服务器配置
prompts	提示词预设
skills	技能安装状态
skill_repos	技能仓库配置
proxy_config	代理配置
proxy_request_logs	代理请求日志
provider_health	供应商健康状态
model_pricing	模型定价
settings	应用设置

这些表的真实 DDL 定义在 src-tauri/src/database/schema.rs 的 create_tables_on_conn() 中，可以据此获得更精确的字段级细节：

• providers：主键为 (id, app_type)，即同一供应商 ID 在不同应用（claude/codex/gemini 等）下各自独立；settings_config 存完整配置 JSON，is_current 与 in_failover_queue 分别标记当前供应商和故障转移队列状态。
• mcp_servers：除 server_config 外，还带有 enabled_claude / enabled_codex / enabled_gemini / enabled_grokbuild / enabled_opencode / enabled_hermes 六个启用开关，说明一个 MCP 服务器可同时挂载到多个应用。
• proxy_config：按 app_type 主键分成多行（claude / codex / gemini / grokbuild），每应用独立配置监听端口（默认 15721）、重试次数、流式超时与熔断器阈值；建表时会为每个应用 seed 不同的默认值（如 claude 默认 6 次重试、90 秒首字节超时）。
• proxy_request_logs：记录每次请求的模型、token 数、成本、延迟、状态码与会话 ID，并建有按供应商、时间、模型、会话、状态码的多个索引，支撑用量看板。
• skills（v3.10.0+ 统一结构）：以 id 为主键，保存技能目录、来源仓库（repo_owner/repo_name/repo_branch）、内容哈希 content_hash 及各应用启用标志，支持更新检测。

除了文档列出的表，schema.rs 中还定义了若干支撑运行时的辅助表：stream_check_logs（流式连通性检测记录）、proxy_live_backup（代理接管前的 Live 配置备份）、usage_daily_rollups（用量日聚合）、session_log_sync（会话日志同步偏移）、session_usage_dedup（用量去重账本）以及 profiles（跨应用的项目档案）。这些表主要服务于用量统计与同步去重，一般不需要同步到别的设备——src-tauri/src/database/backup.rs 中的 SYNC_SKIP_TABLES 常量明确列出了 WebDAV/S3 云同步时会被跳过或本地保留的表，包括 proxy_request_logs、stream_check_logs、provider_health、usage_daily_rollups 等，这正解释了后文「导出/同步不包含用量日志」的设计。

数据库版本由 src-tauri/src/database/mod.rs 中的 SCHEMA_VERSION 常量控制（当前仓库中为 17）。schema.rs 的迁移循环会在启动时逐级把 user_version 迁移到最新，且整段迁移包裹在 SQLite SAVEPOINT 中，失败即回滚；如果检测到磁盘上的数据库版本比应用支持更新（version > SCHEMA_VERSION），会直接报错「数据库版本过新，请升级应用后再尝试」，防止旧版应用覆盖新库。此外 mod.rs 显示：当检测到需要迁移时，会先自动创建一份「迁移前数据库备份」（v{version} → v{SCHEMA_VERSION}），再执行迁移。

设备级设置 settings.json

settings.json 位于 ~/.cc-switch/ 下，保存不随云端同步的设备级设置，文档给出的典型内容：

{
  "language": "zh",
  "theme": "system",
  "windowBehavior": "minimize",
  "autoStart": false,
  "claudeConfigDir": null,
  "codexConfigDir": null,
  "geminiConfigDir": null,
  "opencodeConfigDir": null,
  "openclawConfigDir": null,
  "hermesConfigDir": null
}

这些设置不会在设备之间同步。其中几个 *ConfigDir 字段是关键：它们允许为每个 CLI 指定非默认的配置目录。从源码看，这些字段对应 src-tauri/src/settings.rs 中 AppSettings 的「设备级目录覆盖」区块（claude_config_dir、codex_config_dir、gemini_config_dir、grok_config_dir、opencode_config_dir、openclaw_config_dir、hermes_config_dir、pi_config_dir），取值 null 表示使用各 CLI 的默认目录。同一结构体中还持久化了当前供应商选择（current_provider_claude 等设备级字段，优先级高于数据库的 is_current 标记）、WebDAV/S3 同步配置、备份策略（backup_interval_hours，默认 24 小时；backup_retain_count，默认保留 10 份备份）等。src-tauri/src/config.rs 的 get_claude_config_dir() 展示了覆盖值的消费方式：有覆盖就用覆盖，否则回落到 ~/.claude/。

自动备份

backups/ 目录保存自动备份，文档说明其行为为：每次配置导入前自动创建；默认保留最新 10 份；文件名包含时间戳。

源码层面可以得到印证与补充：

• 备份实现在 src-tauri/src/database/backup.rs，提供 SQL 导出/导入与二进制快照两种形式，导出文件以 -- CC Switch SQLite 导出 注释头标识，导入时会通过 SQLite authorizer 钩子拒绝 ATTACH、VACUUM INTO 等能「逃逸临时库」的越界语句（见 backup.rs 的 import_authorizer），保证恢复外部备份文件时的安全边界。
• 「保留 10 份」对应 AppSettings.backup_retain_count 的默认值（见 settings.rs），即备份保留数量是可配置的。
• 除导入触发的备份外，schema 迁移前也会自动备份（见上文 mod.rs 的迁移前备份逻辑），两条路径共同覆盖了「用户操作」和「程序升级」两个高危数据变更点。

各 CLI 的配置布局

cc-switch 的核心工作方式是：把数据库中的供应商配置「翻译」写入各 CLI 自己的配置文件。以下按文档逐一说明各 CLI 的目录与文件，并结合源码指出 cc-switch 实际读写的位置。

Claude Code 的配置

默认配置目录：~/.claude/。主要文件：

~/.claude/
├── settings.json     # 主配置文件
├── CLAUDE.md         # 系统提示词
└── skills/           # 技能目录
    └── ...

settings.json 示例：

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-xxx",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  },
  "permissions": {
    "allow_file_access": true
  }
}

字段	说明
env.ANTHROPIC_API_KEY	API 密钥
env.ANTHROPIC_BASE_URL	API 端点（可选）
env.ANTHROPIC_AUTH_TOKEN	替代认证方式

MCP 服务器配置不在 ~/.claude/ 内，而是位于用户主目录下的 ~/.claude.json：

{
  "mcpServers": {
    "mcp-fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

源码印证：src-tauri/src/config.rs 中，get_default_claude_mcp_path() 固定返回 ~/.claude.json；get_claude_settings_path() 则体现了新旧文件名兼容策略——优先使用 ~/.claude/settings.json，若该文件不存在而旧版 claude.json 存在则继续沿用旧文件，全新安装才创建 settings.json。若用户通过设备设置覆盖了 Claude 配置目录，MCP 文件路径会派生为「覆盖目录下相邻的 .claude.json」，Windows 下还特别处理了 WSL 路径（\\wsl$\... 前缀）回推默认位置的情况。这些细节解释了为什么换机器或改过目录后，MCP 配置仍然能被 cc-switch 正确找到。

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"]

即 Codex 采用 TOML 格式，端点与模型放在顶层键，MCP 服务器挂在 [mcp_servers.<name>] 表下，与 Claude 的 JSON 结构完全不同——这正是 cc-switch 需要按应用类型分别「翻译」配置的原因。

Gemini CLI 的配置

默认配置目录：~/.gemini/。主要文件：

~/.gemini/
├── .env              # 环境变量（API Key）
├── settings.json     # 主配置 + MCP
└── GEMINI.md         # 系统提示词

.env：

GEMINI_API_KEY=xxx
GOOGLE_GEMINI_BASE_URL=https://generativelanguage.googleapis.com
GEMINI_MODEL=gemini-pro

settings.json：

{
  "mcpServers": {
    "mcp-fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

字段	说明
mcpServers	MCP 服务器配置

源码印证：src-tauri/src/gemini_config.rs 中 get_gemini_settings_path() 的注释明确写明「返回路径：~/.gemini/settings.json（与 .env 文件同级）」，与文档描述一致。

OpenCode 的配置

默认配置目录：~/.config/opencode/。主要文件：

~/.config/opencode/
├── opencode.json     # 主配置文件
├── AGENTS.md         # 系统提示词
└── skills/           # 技能目录
    └── ...

OpenCode 的凭证与端点配置集中在 opencode.json 主配置文件中，AGENTS.md 承担系统提示词职责，技能则通过技能同步机制写入 skills/ 目录（cc-switch 支持 symlink 或 copy 两种同步方式，默认优先 symlink）。

Hermes 的配置

默认配置目录：~/.hermes/。主要文件：

~/.hermes/
├── config.yaml       # 主配置、供应商、MCP 配置
├── .env              # API 密钥与机密
├── SOUL.md           # Profile 身份/人格
├── memories/
│   ├── MEMORY.md     # 代理记忆
│   └── USER.md       # 用户画像记忆
├── skills/           # 生效的技能目录
├── state.db          # SQLite 会话数据库
└── sessions/         # Gateway 转录与可选 JSON 快照

Hermes 使用 YAML 配置，cc-switch 与它的交互规则在文档中有明确界定：MCP 服务器写入 mcp_servers 键；可编辑的供应商条目写入 custom_providers；Hermes 内置 providers 字典中的只读条目仅被读取、不会被修改；供应商切换时更新 model.provider / model.default 两个字段。这种「只写自定义区、不碰内置区」的策略避免了与 Hermes 自身升级带来的预设供应商冲突。

OpenClaw 的配置

默认配置目录：~/.openclaw/。主要文件：

~/.openclaw/
├── openclaw.json     # 主配置文件（JSON5 格式）
└── skills/           # 技能目录
    └── ...

OpenClaw 使用 JSON5 格式（允许注释与非引号键名），openclaw.json 主要包含以下部分：

{
  // 模型供应商配置
  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.defaults	Agent 默认模型配置
tools	工具配置
agents.defaults.workspace	工作区目录路径

配置优先级

当 cc-switch 修改配置时，遵循文档给出的三级优先级：

1. CC Switch 数据库（cc-switch.db）——单一事实源（SSOT）；
2. Live 配置文件——切换供应商时由数据库写入各 CLI 的实时配置文件；
3. 回填（backfill）机制——在编辑当前供应商时，从 Live 文件读取最新值合并回数据库，防止用户在 CLI 侧的手动修改被覆盖丢失。

这个链路在源码中也能找到对应物：proxy_live_backup 表保存代理接管前的原始 Live 配置（可回滚）；settings.json 中的 current_provider_* 设备级字段决定了「当前供应商」的判定，从而决定回填读哪个供应商条目。

手动编辑配置

可以手动编辑的内容

• CLI 工具自身的配置文件（~/.claude/settings.json、~/.codex/config.toml 等）——cc-switch 会通过回填机制把它们拉回数据库；
• cc-switch 的 ~/.cc-switch/settings.json。

不建议手动编辑的内容

• cc-switch.db 数据库文件（直接改库可能破坏外键、版本标记与聚合统计的一致性，且下次启动的迁移检查以 user_version 为准）；
• backups/ 下的备份文件。

编辑后的同步步骤

如果手动修改了某个 CLI 的配置，按文档建议的操作顺序：

1. 打开 cc-switch；
2. 编辑对应的供应商；
3. 确认表单中已回填手动修改的内容（回填机制生效的标志）；
4. 保存，将变更同步进数据库。

配置迁移

旧版本迁移

cc-switch 在 v3.7.0 将数据层从 JSON 文件迁移到 SQLite。迁移行为：

• 首次启动新版本时自动执行，无需手动操作；
• 迁移成功后界面会显示通知；
• 旧配置文件作为备份保留，不会删除。

当前仓库的迁移体系在此基础上演进：schema.rs 实现了从 user_version 0 到 17 的逐级迁移链（含 v10 增加 Hermes 支持、v12 增加 profiles 表、v14 增加 Grok Build 代理配置等里程碑），每一步失败都会通过 SAVEPOINT 回滚，且迁移前自动落一份备份（mod.rs）。

跨设备迁移

三种途径：

1. 在源设备导出配置，在目标设备导入（见下节）；
2. 使用云端同步功能（WebDAV/S3 同步设置位于 AppSettings 的 webdav_sync / s3_sync 字段）；
3. 直接复制自定义的 ~/.cc-switch/ 目录（文档开头提到的「自定义目录用于云同步」场景）。

注意：settings.json 中的设备级设置（目录覆盖、当前供应商等）不参与跨设备同步，目标设备需要重新确认本地路径。

备份建议

定期备份

文档建议在「设置 → 高级 → 数据管理」中点击「导出」，定期将配置导出并保存到安全位置。导出产物为带注释头的 SQL 文本（-- CC Switch SQLite 导出），可用 backup.rs 中定义的格式验证并回导。

备份包含的内容

• 全部供应商配置（providers / provider_endpoints）；
• MCP 服务器配置（mcp_servers）；
• 提示词预设（prompts）；
• 应用设置（settings）及技能、技能仓库、定价等核心表。

不包含的内容

• 用量日志（proxy_request_logs、usage_daily_rollups、stream_check_logs 等）——数据量大，且各设备会独立重新积累；
• 设备级设置（settings.json 的内容）——不适合跨设备搬迁。

这与 backup.rs 中 SYNC_SKIP_TABLES / SYNC_PRESERVE_TABLES 的划分一致：云同步导出会跳过日志类表，而导入时这些表在本地数据库中的现有数据会被保留，从而保证「备份只备份配置，不搬运动态数据」的语义。

小结

cc-switch 的文件布局可以概括为「一个 SSOT + 一层 Live 视图」：~/.cc-switch/cc-switch.db 是唯一权威数据源，各 CLI 的 settings.json / config.toml / config.yaml / JSON5 文件是它的实时投影；settings.json（设备级）与 backups/（自动备份）分别处理「机器专属状态」和「数据变更保险」。理解了 src-tauri/src/config.rs 的路径解析、src-tauri/src/database/schema.rs 的表结构与迁移链、以及 src-tauri/src/database/backup.rs 的同步表划分，你就能在手动编辑、换机迁移和故障恢复时准确判断哪些文件可以动、哪些文件不应该动、以及改动后如何通过回填与保存让数据库重新成为单一事实源。