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/

You can change the "CC Switch Configuration Directory" under "Settings → Data → Location" (for cloud sync). A restart is required after changing it; CC Switch doesn't move existing files for you, so copy them over manually first.

Directory Structure

~/.cc-switch/
├── cc-switch.db            # SQLite database (SSOT)
├── settings.json           # Device-level settings
├── live-state.json         # Device state: whether each tool is direct or on local routing, and what was last written
├── codex-login-stash.json  # Stashed official Codex login (restored when you switch back to an official provider)
├── copilot_auth.json       # GitHub Copilot login credentials (Accounts)
├── codex_oauth_auth.json   # ChatGPT / Codex OAuth login credentials (Accounts)
├── xai_oauth_auth.json     # xAI OAuth login credentials (Accounts)
├── skills/                 # Master copies of skills (when the storage location is "CC Switch")
├── skill-backups/          # Skill backups (created on uninstall)
├── backups/                # Database backups and environment variable backups
│   └── live-first-write/   # Each tool's config file as it was before CC Switch first rewrote it
├── logs/                   # App diagnostic logs (cc-switch.log and rotated files)
└── crash.log               # Crash log

settings.json, live-state.json, codex-login-stash.json, and backups/live-first-write/ belong to this computer only: they always stay in ~/.cc-switch/, don't move with the "CC Switch Configuration Directory" setting, and aren't included in cloud sync.

live-state.json records whether each switch-style app (Claude Code, Codex, Gemini CLI, Grok Build) is currently Direct, Routing or Aggregation, and what CC Switch last wrote into each tool's config file. After quitting CC Switch or restarting after a crash, it relies on this file to restore the config files to the right state, so please don't edit it by hand.

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
profiles	Projects (a full set of provider, MCP, Skills and prompt states)
proxy_config	Local routing configuration (per app)
proxy_request_logs	Per-request usage details (routed requests and session log imports)
usage_daily_rollups	Daily rollups of usage older than 30 days
provider_health	Provider health status
model_pricing	Model pricing
settings	App settings

Device Settings

settings.json stores device-level settings:

{
  "language": "zh",
  "showInTray": true,
  "minimizeToTrayOnClose": true,
  "launchOnStartup": false,
  "claudeConfigDir": null,
  "codexConfigDir": null,
  "geminiConfigDir": null,
  "grokConfigDir": null,
  "opencodeConfigDir": null,
  "openclawConfigDir": null,
  "hermesConfigDir": null,
  "piConfigDir": null
}

Besides these, each app's "current provider" is also recorded in this file (the direct pointer). These settings are not synced across devices. Each app's config directory is changed under "Settings → App config"; Claude Desktop and MiniMax Code don't support overriding the directory.

Automatic Backups

The backups/ directory stores database backups:

• Backed up automatically at the interval set in "Settings → Data → Backup & Restore" (24 hours by default)
• Also created automatically before overwriting operations such as importing configuration, restoring a backup or downloading from the cloud
• Retains the most recent 10 backups by default
• File names include timestamps

Besides database backups, CC Switch leaves backups elsewhere too (environment variable cleanup backups, skill backups, original config files, and so on). "Other Backups" below "Backup & Restore" in "Settings → Data" lists these locations and their sizes, and you can clean them up by category.

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

When switching providers, CC Switch changes only the key fields in settings.json: connection and auth variables in env such as ANTHROPIC_* and AWS_*, protocol selectors such as CLAUDE_CODE_USE_BEDROCK, and top-level keys such as model and apiKeyHelper, plus a few compatibility options that belong to the provider (such as CLAUDE_CODE_DISABLE_ARTIFACT and the context window). permissions, hooks, enabledPlugins, statusLine, and everything else are left alone.

MCP Configuration

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

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

Claude Desktop Configuration

Claude Desktop is a switch-style app, but its config directory can't be overridden in CC Switch.

System	Location
macOS	~/Library/Application Support/Claude/ and Claude-3p/
Windows	The Claude and Claude-3p directories under %LOCALAPPDATA%
Linux	~/.config/Claude/ and Claude-3p/

Claude/claude_desktop_config.json        # Claude Desktop's main config
Claude-3p/claude_desktop_config.json     # Config for third-party inference (gateway) mode
Claude-3p/configLibrary/*.json           # Gateway configs written by CC Switch

In the default "Direct" mode, CC Switch writes the provider address and Key straight into the gateway config; in "Model mapping" mode, the gateway config points to the /claude-desktop prefix of local routing, and the real address and Key are kept only in CC Switch, so CC Switch must keep running. After switching, quit Claude Desktop completely and reopen it.

Claude Desktop has no MCP, Skills, prompt or session data of its own: those pages operate on Claude Code's data.

Codex Configuration

Configuration Directory

Default: ~/.codex/

Key Files

~/.codex/
├── auth.json                     # OpenAI official ChatGPT login credentials
├── config.toml                   # Main configuration + MCP
├── cc-switch-model-catalog.json  # Model catalog generated by CC Switch
└── AGENTS.md                     # System prompt

auth.json

auth.json only holds the OpenAI official ChatGPT login credentials, written by Codex's codex login. When you switch to a third-party provider, CC Switch does not write the third-party API Key into this file. When local routing is off, whether a direct switch keeps the official login is controlled by "Keep official login for direct switches" in "Settings → App config" (off by default, meaning auth.json is deleted); while routing, the official login is always kept. Before deleting it, CC Switch stashes this login in ~/.cc-switch/codex-login-stash.json and puts it back unchanged when you switch back to the official provider, so you don't need to log in again.

config.toml

# Basic configuration
model_provider = "custom"
model = "gpt-5.6-sol"

[model_providers.custom]
name = "custom"
base_url = "https://api.example.com/v1"
wire_api = "responses"
experimental_bearer_token = "sk-xxx"   # API Key of the third-party provider

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

Every third-party provider is written as the [model_providers.custom] table, with the API Key in that table's experimental_bearer_token. In Routing or Aggregation mode, this holds the local routing address and the Key is replaced with the placeholder PROXY_MANAGED. For providers with model mapping configured, a model_catalog_json entry pointing to cc-switch-model-catalog.json is also written.

When switching providers, CC Switch changes only the key fields in config.toml: top-level keys such as model_provider, model, and the reasoning effort, the [model_providers.custom] table, and a few compatibility options (such as model_context_window and web_search). [mcp_servers], [projects], your own other provider tables, comments, and formatting are left alone.

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
security.auth.selectedType	Auth method: oauth-personal for the Google official provider, gemini-api-key for all others
model.name	Model name

When switching providers, CC Switch changes only the key-field lines in .env (GEMINI_API_KEY, GEMINI_MODEL, GOOGLE_*, etc.), leaving variables you added yourself, comments, and line order alone; in settings.json it changes only the two keys security.auth.selectedType and model.name. Both files are updated together in a single operation.

OpenCode Configuration

Configuration Directory

Default: ~/.config/opencode/

Key Files

~/.config/opencode/
├── opencode.json     # Main configuration file; MCP is under the mcp key
├── AGENTS.md         # System prompt
└── skills/           # Skills directory
    └── ...

Grok Build Configuration

Configuration Directory

Default: ~/.grok/

Key Files

~/.grok/
├── config.toml       # Main configuration, providers and MCP ([mcp_servers])
├── AGENTS.md         # System prompt
├── skills/           # Skills directory
└── sessions/         # Session logs

Grok Build is a switch-mode app. When switching providers, CC Switch changes only default under [models] in config.toml and the [model."<name>"] table it points to; [mcp_servers] and other model tables you added yourself are left alone.

When switching away, CC Switch deletes the table it wrote last time (the table name is recorded in ~/.cc-switch/live-state.json), not whichever table default points to now. So even if you changed the default model in Grok Build's /settings, switching away won't delete your own table by mistake or leave the previous provider's table behind.

Hermes Configuration

Configuration Directory

Default: ~/.hermes/ (on Windows the default is %LOCALAPPDATA%\hermes\; can also be set with the HERMES_HOME environment variable)

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

Pi Configuration

Configuration Directory

Default: ~/.pi/agent/ (can be overridden with the PI_CODING_AGENT_DIR environment variable or "Pi Configuration Directory" in settings)

Key Files

~/.pi/agent/
├── models.json       # Custom providers and models (written by CC Switch)
├── mcp.json          # MCP servers (written by CC Switch)
├── settings.json     # Pi global settings, including the current defaultProvider / defaultModel (read-only for CC Switch)
├── auth.json         # Pi login credentials (CC Switch neither reads nor writes it)
├── AGENTS.md         # Global prompt
├── skills/           # Skills directory
└── sessions/         # Session logs

CC Switch only manages the provider nodes explicitly written in models.json, and never copies Pi's built-in providers or models into it; login is handled by Pi's own /login.

MiniMax Code Configuration

Configuration Directory

Default: ~/.minimax/ (can be set with the MINIMAX_DATA_DIR or MAVIS_DATA_DIR environment variable)

Key Files

~/.minimax/
├── config.yaml       # Main configuration; custom providers live under custom_provider
├── mcp.json          # MCP servers
├── AGENTS.md         # Global prompt (up to 32 KiB)
└── skills/           # Skills directory

CC Switch only manages nodes in custom_provider whose kind is omitted or set to custom; MiniMax official account nodes are managed by MiniMax Code itself. A provider referenced by MiniMax Code's default model can't be deleted or disabled. Before writing, CC Switch acquires the directory lock config.yaml.lock, which is compatible with MiniMax Code.

Who Manages What

The config files of switch-style apps (Claude Code, Codex, Gemini CLI, and Grok Build) are managed in two parts (additive apps OpenCode, OpenClaw, Hermes, Pi and MiniMax Code write each provider into the config file as a whole entry, with several coexisting and nothing replaced on switching):

Part	Includes	Stored in	Changed by
Key fields	Endpoint, key, model name, API protocol, etc., plus a few compatibility options that belong to the provider	Each provider in the CC Switch database	CC Switch, which replaces them with the target provider's values when switching
Global settings	Everything else: plugins, hooks, permissions, MCP, settings you added yourself, comments	The tool's own config file	You and the tool; CC Switch writes them only when you change them through the edit panel

For exactly which keys each app changes, see the app sections above.

Manual Configuration Editing

Safe to Edit Manually

• Global settings in the tool's config file: edit them directly. Switching providers won't touch them, and you don't need to sync them back into CC Switch.
• CC Switch's settings.json

Replaced Even If You Edit Them

• Key fields in the tool's config file (endpoint, key, model, etc.): a value you edit by hand stays in effect until the next switch; switching replaces it with the target provider's value, and CC Switch doesn't save it back to the provider. To change it for good, edit that provider in CC Switch.

Not Recommended to Edit Manually

• cc-switch.db database file
• live-state.json, codex-login-stash.json
• Backup files

When a Config File Has a Format Error

CC Switch writes a config file only if it can read it correctly. If a manual edit breaks the config file (for example, a missing comma in JSON), switching reports "Cannot parse … (line N, column M) … Nothing was written, so your configuration is unchanged" and every file stays as it was. Fix it at the reported position, then switch again.

Backup Before the First Write

Before CC Switch rewrites a tool's config file for the first time, it backs up the original to ~/.cc-switch/backups/live-first-write/, once per file. If your configuration doesn't look as expected after upgrading, you can recover the pre-upgrade original from there.

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 → Data → Data Management
2. Click "Export SQL Backup"
3. Save to a secure location

Backup Contents

The export file is a complete SQL database backup, including:

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

Not Included

• Device-level settings (settings.json, not suitable for cross-device)

💡 Cloud sync differs from export: cloud sync does not upload data that only makes sense on the local machine, such as usage logs.