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
├── settings.json     # Device-level settings
└── backups/          # Automatic backups
    ├── backup-20251230-120000.json
    ├── backup-20251229-180000.json
    └── ...
```

### 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:

```json
{
  "language": "zh",
  "theme": "system",
  "windowBehavior": "minimize",
  "autoStart": false,
  "claudeConfigDir": null,
  "codexConfigDir": null,
  "geminiConfigDir": null,
  "opencodeConfigDir": null,
  "openclawConfigDir": 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

```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`:

```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

```json
{
  "OPENAI_API_KEY": "sk-xxx"
}
```

### config.toml

```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

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

### settings.json

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

| Field | Description |
|-------|-------------|
| `mcpServers` | MCP server configuration |

## OpenCode Configuration

### Configuration Directory

Default: `~/.opencode/`

### Key Files

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

## OpenClaw Configuration

### Configuration Directory

Default: `~/.openclaw/`

### Key Files

```
~/.openclaw/
├── openclaw.json     # Main configuration file (JSON5 format)
├── AGENTS.md         # System prompt
└── skills/           # Skills directory
    └── ...
```

### openclaw.json

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

```json5
{
  // 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 model configuration
  agents: {
    defaults: {
      model: {
        primary: "provider/model"
      }
    }
  },
  // Tool configuration
  tools: {},
  // Workspace file configuration
  workspace: {}
}
```

| 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 |
| `workspace` | Workspace file management |

## 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)