cc-switch/docs/user-manual/zh/5-faq/5.1-config-files.md

# 5.1 配置文件说明

## CC Switch 数据存储

### 存储目录

默认位置：`~/.cc-switch/`

可在设置中自定义位置（用于云同步）。

### 目录结构

```
~/.cc-switch/
├── cc-switch.db      # SQLite 数据库
├── settings.json     # 设备级设置
└── backups/          # 自动备份
    ├── backup-20251230-120000.json
    ├── backup-20251229-180000.json
    └── ...
```

### 数据库内容

`cc-switch.db` 是 SQLite 数据库，存储：

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

### 设备设置

`settings.json` 存储设备级设置：

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

这些设置不会跨设备同步。

### 自动备份

`backups/` 目录存储自动备份：

- 每次导入配置前自动创建
- 保留最近 10 个备份
- 文件名包含时间戳

## Claude Code 配置

### 配置目录

默认：`~/.claude/`

### 主要文件

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

### settings.json

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

MCP 服务器配置在 `~/.claude.json`：

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

## Codex 配置

### 配置目录

默认：`~/.codex/`

### 主要文件

```
~/.codex/
├── auth.json         # 认证配置
├── config.toml       # 主配置 + MCP
└── AGENTS.md         # 系统提示词
```

### auth.json

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

### config.toml

```toml
# 基础配置
base_url = "https://api.openai.com/v1"
model = "gpt-4"

# MCP 服务器
[mcp_servers.mcp-fetch]
command = "uvx"
args = ["mcp-server-fetch"]
```

## Gemini CLI 配置

### 配置目录

默认：`~/.gemini/`

### 主要文件

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

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

| 字段 | 说明 |
|------|------|
| `mcpServers` | MCP 服务器配置 |

## OpenCode 配置

### 配置目录

默认：`~/.opencode/`

### 主要文件

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

## OpenClaw 配置

### 配置目录

默认：`~/.openclaw/`

### 主要文件

```
~/.openclaw/
├── openclaw.json     # 主配置文件（JSON5 格式）
├── AGENTS.md         # 系统提示词
└── skills/           # 技能目录
    └── ...
```

### openclaw.json

OpenClaw 使用 JSON5 格式配置文件，主要包含以下部分：

```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"
      }
    }
  },
  // 工具配置
  tools: {},
  // 工作区文件配置
  workspace: {}
}
```

| 字段 | 说明 |
|------|------|
| `models.providers` | 供应商配置（映射为 CC Switch 的"供应商"） |
| `env` | 环境变量配置 |
| `agents.defaults` | Agent 默认模型设置 |
| `tools` | 工具配置 |
| `workspace` | 工作区文件管理 |

## 配置优先级

CC Switch 修改配置时的优先级：

1. **CC Switch 数据库** - 单一事实源 (SSOT)
2. **Live 配置文件** - 切换供应商时写入
3. **回填机制** - 编辑当前供应商时从 Live 文件读取

## 手动编辑配置

### 可以手动编辑

- CLI 工具的配置文件（会被 CC Switch 回填）
- CC Switch 的 `settings.json`

### 不建议手动编辑

- `cc-switch.db` 数据库文件
- 备份文件

### 编辑后同步

如果手动编辑了 CLI 工具的配置：

1. 打开 CC Switch
2. 编辑对应的供应商
3. 会看到手动修改的内容已回填
4. 保存以同步到数据库

## 配置迁移

### 从旧版本迁移

CC Switch v3.7.0 从 JSON 文件迁移到 SQLite：

- 首次启动自动迁移
- 迁移成功后显示提示
- 旧配置文件保留作为备份

### 跨设备迁移

1. 在源设备导出配置
2. 在目标设备导入配置
3. 或使用云同步功能

## 配置备份建议

### 定期备份

建议定期导出配置：

1. 设置 → 高级 → 数据管理
2. 点击「导出」
3. 保存到安全位置

### 备份内容

导出文件包含：

- 所有供应商配置
- MCP 服务器配置
- Prompts 预设
- 应用设置

### 不包含的内容

- 用量日志（数据量大）
- 设备级设置（不适合跨设备）