CC-Switch/docs/user-manual/en/5-faq/5.1-config-files.md

5.1 Configuration Files

CC Switch Data Storage

Storage Directory

Default location: ~/.cc-switch/

Customizable location in settings (for cloud sync).

Directory Structure

~/.cc-switch/
├── cc-switch.db      # SQLite database (SSOT)
├── settings.json     # Device-level settings
├── skills/           # Skill SSOT directory
├── skill-backups/    # Skill backups (created on uninstall)
└── backups/          # Database backups

Database Contents

cc-switch.db is a SQLite database that stores:

Table	Contents
providers	Provider configurations
provider_endpoints	Provider endpoint candidate list
mcp_servers	MCP server configurations
prompts	Prompt presets
skills	Skill installation status
skill_repos	Skill repository configurations
proxy_config	Proxy configuration
proxy_request_logs	Proxy request logs
provider_health	Provider health status
model_pricing	Model pricing
settings	App settings

Device Settings

settings.json stores device-level settings:

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

These settings are not synced across devices.

Automatic Backups

The backups/ directory stores automatic backups:

• Automatically created before each configuration import
• Retains the most recent 10 backups
• File names include timestamps

Claude Code Configuration

Configuration Directory

Default: ~/.claude/

Key Files

~/.claude/
├── settings.json     # Main configuration file
├── CLAUDE.md         # System prompt
└── skills/           # Skills directory
    └── ...

settings.json

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

Field	Description
env.ANTHROPIC_API_KEY	API key
env.ANTHROPIC_BASE_URL	API endpoint (optional)
env.ANTHROPIC_AUTH_TOKEN	Alternative authentication method

MCP Configuration

MCP server configuration is in ~/.claude.json:

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

Codex Configuration

Configuration Directory

Default: ~/.codex/

Key Files

~/.codex/
├── auth.json         # Authentication configuration
├── config.toml       # Main configuration + MCP
└── AGENTS.md         # System prompt

auth.json

{
  "OPENAI_API_KEY": "sk-xxx"
}

config.toml

# Basic configuration
base_url = "https://api.openai.com/v1"
model = "gpt-4"

# MCP servers
[mcp_servers.mcp-fetch]
command = "uvx"
args = ["mcp-server-fetch"]

Gemini CLI Configuration

Configuration Directory

Default: ~/.gemini/

Key Files

~/.gemini/
├── .env              # Environment variables (API Key)
├── settings.json     # Main configuration + MCP
└── GEMINI.md         # System prompt

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

Field	Description
mcpServers	MCP server configuration

OpenCode Configuration

Configuration Directory

Default: ~/.config/opencode/

Key Files

~/.config/opencode/
├── opencode.json     # Main configuration file
├── AGENTS.md         # System prompt
└── skills/           # Skills directory
    └── ...

Hermes Configuration

Configuration Directory

Default: ~/.hermes/

Key Files

~/.hermes/
├── config.yaml       # Main settings, providers, and MCP configuration
├── .env              # API keys and secrets
├── SOUL.md           # Profile identity/persona
├── memories/
│   ├── MEMORY.md     # Agent memory
│   └── USER.md       # User profile memory
├── skills/           # Active skills directory
├── state.db          # SQLite session database
└── sessions/         # Gateway transcripts and optional JSON snapshots

config.yaml

Hermes uses YAML configuration. CC Switch writes MCP servers to mcp_servers, writes editable provider entries to custom_providers, reads read-only entries from Hermes' providers dict, and updates model.provider / model.default when switching providers.

OpenClaw Configuration

Configuration Directory

Default: ~/.openclaw/

Key Files

~/.openclaw/
├── openclaw.json     # Main configuration file (JSON5 format)
└── skills/           # Skills directory
    └── ...

openclaw.json

OpenClaw uses a JSON5 format configuration file with the following main sections:

{
  // Model provider configuration
  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" }]
      }
    }
  },
  // Environment variables
  env: {
    ANTHROPIC_API_KEY: "sk-..."
  },
  // Agent default configuration
  agents: {
    defaults: {
      model: {
        primary: "provider/model"
      },
      workspace: "~/.openclaw/workspace"
    }
  },
  // Tool configuration
  tools: {}
}

Field	Description
models.providers	Provider configuration (mapped to CC Switch's "providers")
env	Environment variable configuration
agents.defaults	Agent default model settings
tools	Tool configuration
agents.defaults.workspace	Workspace directory path

Configuration Priority

CC Switch's priority when modifying configurations:

1. CC Switch Database - Single source of truth (SSOT)
2. Live Configuration Files - Written when switching providers
3. Backfill Mechanism - Reads from live files when editing the current provider

Manual Configuration Editing

Safe to Edit Manually

• CLI tool configuration files (will be backfilled by CC Switch)
• CC Switch's settings.json

Not Recommended to Edit Manually

• cc-switch.db database file
• Backup files

Sync After Editing

If you manually edit CLI tool configurations:

1. Open CC Switch
2. Edit the corresponding provider
3. You will see the manual changes have been backfilled
4. Save to sync to the database

Configuration Migration

Migrating from Older Versions

CC Switch v3.7.0 migrated from JSON files to SQLite:

• Automatic migration on first launch
• Displays a notification upon successful migration
• Old configuration files are retained as backups

Cross-device Migration

1. Export configuration on the source device
2. Import configuration on the target device
3. Or use the cloud sync feature

Configuration Backup Recommendations

Regular Backups

It is recommended to regularly export configurations:

1. Settings > Advanced > Data Management
2. Click "Export"
3. Save to a secure location

Backup Contents

The export file includes:

• All provider configurations
• MCP server configurations
• Prompt presets
• App settings

Not Included

• Usage logs (large data volume)
• Device-level settings (not suitable for cross-device)