# 1.5 个性化配置

本节介绍如何根据个人偏好配置 CC Switch。

## 打开设置

- 点击左上角 **⚙️** 按钮
- 或使用快捷键 `Cmd/Ctrl + ,`

## 语言设置

CC Switch 支持四种语言：

| 语言     | 说明     |
| -------- | -------- |
| 简体中文 | 默认语言 |
| 繁體中文 | 繁体中文界面 |
| English  | 英文界面 |
| 日本語   | 日文界面 |

切换语言后立即生效，无需重启。

## 主题设置

| 选项     | 说明                        |
| -------- | --------------------------- |
| 跟随系统 | 自动匹配系统的深色/浅色模式 |
| 浅色     | 始终使用浅色主题            |
| 深色     | 始终使用深色主题            |

## 窗口行为

### 开机自启

开启后，系统启动时自动运行 CC Switch。

- **Windows**：通过注册表实现
- **macOS**：通过 LaunchAgent 实现
- **Linux**：通过 XDG autostart 实现

### 关闭行为

| 选项         | 说明                         |
| ------------ | ---------------------------- |
| 最小化到托盘 | 点击关闭按钮时隐藏到系统托盘 |
| 直接退出     | 点击关闭按钮时完全退出应用   |

推荐使用「最小化到托盘」，方便通过托盘快速切换供应商。

### 轻量模式

v3.13.0 起新增「轻量模式」——一种**仅托盘运行**的状态，用于把空闲时的桌面占用降到最低。

**触发方式**：右键系统托盘图标 → 点击「轻量模式」。主窗口会被**销毁**（而不是隐藏），UI 资源和内存随之释放。

**退出方式**：从托盘菜单点击「打开主界面」，或通过深链接 / 再次启动 CC Switch。窗口会按需**重建**，状态保持一致。

| 特性         | 最小化到托盘         | 轻量模式                 |
| ------------ | -------------------- | ------------------------ |
| UI 进程      | 保留在内存中         | 完全销毁                 |
| 空闲资源占用 | 与正常运行相当       | 接近零                   |
| 再次打开速度 | 瞬时（直接显示）     | 略慢（需要重建窗口）     |
| 托盘切换功能 | 可用                 | 可用                     |
| 深链接唤起   | 可用                 | 可用（按需重建）         |

> 💡 **使用场景**：如果你 CC Switch 长时间常驻后台，主要通过托盘菜单切换供应商，开启轻量模式能显著降低内存占用。

> ⚠️ **注意**：轻量模式状态不持久 — 下次正常启动时会回到普通模式。需要长期使用可搭配开机自启。

### Claude 插件集成

开启后，CC Switch 在切换供应商时会自动同步配置到 VS Code 中的 Claude Code 插件（写入 `~/.claude/config.json` 的 `primaryApiKey`）。

> 💡 **使用场景**：如果你同时使用 Claude Code CLI 和 VS Code 插件，开启此选项可以保持两者配置一致。

### 跳过 Claude 引导

开启后，跳过 Claude Code 的新手引导流程，适合已熟悉 Claude Code 的用户。

> ⚠️ **注意**：此选项会写入 `~/.claude/settings.json` 的 `skipIntroduction` 字段。

### 应用可见性

选择在应用切换器中显示哪些应用。每个应用可以独立开关，但至少保留一个。

可配置的应用：Claude、Claude Desktop、Codex、Gemini、OpenCode、OpenClaw、Hermes。

> 💡 **使用场景**：如果你只使用 Claude Code 和 Codex CLI，可以隐藏其他应用，保持界面简洁。

### Skills 同步方式

设置技能安装到各应用目录时的同步方式：

| 方式              | 说明                                                 |
| ----------------- | ---------------------------------------------------- |
| 软链接（Symlink） | 创建符号链接指向技能源文件，占用空间小，更新实时同步 |
| 复制（Copy）      | 将技能文件完整复制到目标目录                         |

> 💡 **推荐**：默认使用软链接方式。如果遇到权限问题，可切换为复制方式。

### 终端设置

选择 CC Switch 打开终端时使用的终端应用程序。

支持的终端（按平台）：

| 平台    | 终端选项                                                           |
| ------- | ------------------------------------------------------------------ |
| macOS   | Terminal、iTerm2、Alacritty、Kitty、Ghostty、WezTerm               |
| Windows | CMD、PowerShell、Windows Terminal                                  |
| Linux   | GNOME Terminal、Konsole、Xfce4 Terminal、Alacritty、Kitty、Ghostty |

## 目录配置

### 应用配置目录

CC Switch 自身数据的存储位置，默认为 `~/.cc-switch/`。

### CLI 工具目录

可以自定义各 CLI 工具的配置目录：

| 配置          | 默认值         | 说明                 |
| ------------- | -------------- | -------------------- |
| Claude 目录   | `~/.claude/`   | Claude Code 配置目录 |
| Codex 目录    | `~/.codex/`    | Codex 配置目录       |
| Gemini 目录   | `~/.gemini/`   | Gemini CLI 配置目录  |
| OpenCode 目录 | `~/.config/opencode/` | OpenCode 配置目录    |
| OpenClaw 目录 | `~/.openclaw/` | OpenClaw 配置目录    |
| Hermes 目录   | `~/.hermes/`   | Hermes 配置目录      |

> ⚠️ **注意**：修改目录后需要重启应用，且对应的 CLI 工具也需要配置相同的目录。

## 数据管理

### 导出配置

点击「导出」按钮，保存包含以下内容的 SQL 备份文件：

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

导出文件名格式为 `cc-switch-export-{timestamp}.sql`。

### 导入配置

1. 点击「选择文件」
2. 选择之前导出的备份文件
3. 点击「导入」
4. 确认覆盖现有配置

> ⚠️ **注意**：导入会覆盖现有配置，建议先导出当前配置作为备份。

## 代理设置

设置 → 代理 Tab

代理 Tab 集中管理所有代理相关功能：

### 本地代理

启动/停止本地代理服务，配置监听地址和端口。详见 [4.1 代理服务](../4-proxy/4.1-service.md)。

### 故障转移

按应用（Claude/Codex/Gemini）配置故障转移队列和自动切换策略。详见 [4.3 故障转移](../4-proxy/4.3-failover.md)。

### 定价矫正器

配置模型定价矫正规则，用于代理计费统计的校准。

### 全局出站代理

配置 CC Switch 的出站 HTTP/HTTPS 代理，适用于需要通过代理访问外部 API 的场景。

## 高级设置

设置 → 高级 Tab

### 配置目录

自定义各应用的配置文件目录。详见下方「目录配置」章节。

### 数据管理

导入/导出配置备份。详见下方「数据管理」章节。

### 备份与恢复

备份管理面板提供对数据库备份的全面控制。

#### 自动备份设置

| 配置     | 选项                               | 默认值    |
| -------- | ---------------------------------- | --------- |
| 备份间隔 | 禁用、6h、12h、24h、48h、7d        | 24 小时   |
| 保留数量 | 3、5、10、15、20、30、50           | 10 个备份 |

设置间隔后，CC Switch 会按计划自动备份数据库。超出保留数量的旧备份会自动删除。

#### 备份列表

面板显示所有现有备份，包含：
- **显示名称**（根据时间戳自动生成，如 `db_backup_20260315_143000`）
- **创建时间**
- **文件大小**（如 "1.5 MB"）

#### 备份操作

| 操作         | 说明                                                                     |
| ------------ | ------------------------------------------------------------------------ |
| **立即备份** | 立即创建一个备份                                                         |
| **恢复**     | 从选定的备份恢复数据库。恢复前会自动创建当前数据库的安全备份             |
| **重命名**   | 修改备份的显示名称                                                       |
| **删除**     | 永久删除备份（需确认）                                                   |

> ⚠️ **重要**：恢复备份会覆盖当前数据库。恢复操作前始终会自动创建安全备份，以便在需要时恢复。

### 云同步（WebDAV）

通过 WebDAV 协议在多台设备间同步配置。使用 **v2 协议**，支持双层版本控制，提高可靠性。

| 配置项   | 说明                                                                         |
| -------- | ---------------------------------------------------------------------------- |
| 服务预设 | 坚果云 / Nextcloud / 群晖 / 自定义                                           |
| 服务地址 | WebDAV 服务器 URL                                                            |
| 用户名   | 登录用户名                                                                   |
| 密码     | 登录密码（应用专用密码；已保存的凭据在未修改时会被保留）                     |
| 远程目录 | 远程存储路径（默认 `cc-switch-sync`）                                        |
| 配置名称 | 设备配置文件名（默认 `default`）                                             |
| 自动同步 | 开启后按配置的间隔自动同步                                                   |

#### 操作

| 操作         | 说明                                                                                         |
| ------------ | -------------------------------------------------------------------------------------------- |
| **测试连接** | 验证 WebDAV URL、用户名和密码是否有效                                                        |
| **上传**     | 将本地数据库上传到远程，显示进度指示器                                                       |
| **下载**     | 下载远程数据库。下载前显示远程快照信息（协议版本、数据库版本、时间戳、大小）供确认。覆盖本地数据库前会自动创建安全备份 |

#### 自动同步

启用 **自动同步** 后：
- 首次激活时会显示确认对话框
- CC Switch 按配置的间隔自动将数据库同步到 WebDAV
- 面板中显示同步状态

#### 远程快照信息

下载前，CC Switch 会显示远程快照的详细信息：
- 协议版本（v2）
- 数据库兼容版本
- 远程备份的时间戳
- 文件大小
- 兼容性状态（不兼容时显示警告）

> ⚠️ **注意**：上传会覆盖远程数据，下载会覆盖本地数据。下载前始终会自动创建安全备份。

### 日志配置

| 配置项   | 说明                                |
| -------- | ----------------------------------- |
| 启用日志 | 开启/关闭应用日志记录               |
| 日志级别 | error / warn / info / debug / trace |

日志级别说明：

- **error** - 仅记录错误
- **warn** - 记录警告和错误
- **info** - 记录一般信息（推荐）
- **debug** - 记录调试信息
- **trace** - 记录所有详细信息

## OAuth 认证中心（Beta）

设置 → **OAuth 认证中心** Tab

v3.13.0 新增的 **OAuth 认证中心**（Beta）统一管理第三方 OAuth 凭据，目前支持三类账号：

| 账号类型                     | 用途                                            |
| ---------------------------- | ----------------------------------------------- |
| **GitHub Copilot**           | 配合 Copilot 反向代理使用                       |
| **ChatGPT (Codex OAuth)**    | 配合 Codex OAuth 反向代理使用，管理 ChatGPT 账号   |
| **xAI (Grok OAuth)**         | 配合 xAI Responses API 反向代理使用               |

**你可以在这里**：

- 通过 Device Code 流程登录 ChatGPT / GitHub / xAI 账号
- 查看已登录账号列表和认证状态
- 为多账号设置默认账号
- 移除单个账号或一键注销所有账号

xAI 集成使用 OAuth 2.0 Device Authorization Grant，不使用本机回环回调。其网络依赖契约如下：

| 依赖 | 端点 |
| ---- | ---- |
| OpenID discovery | `https://auth.x.ai/.well-known/openid-configuration` |
| 设备授权 | discovery 返回的 `device_authorization_endpoint`（当前为 `https://auth.x.ai/oauth2/device/code`） |
| Token 交换/刷新 | discovery 返回的 `token_endpoint`（当前为 `https://auth.x.ai/oauth2/token`） |
| 推理 | `https://api.x.ai/v1/responses` |
| 模型发现 | `https://api.x.ai/v1/models` |

流程不占用任何本地回调端口；认证和模型请求均复用 CC Switch 的全局出站代理设置。

xAI 集成**不使用**注册给 CC Switch 的 OAuth 应用，而是复用 xAI 官方 Grok CLI 注册的公共 OAuth 客户端身份与 scope（`client_id: b1a00492-073a-47ea-816f-4c329264a828`，包含 `grok-cli:access`）获取账号型 API 访问权限。

> ⚠️ **警告**：这些账号型反向代理使用逆向接入的 OAuth 流程，存在账号与服务条款风险。复用上游产品的 OAuth 客户端可能不受官方支持，并可能导致服务商限制或封禁账号。请在使用前审阅对应服务商条款并自行承担风险；现有 Codex 流程另见 [2.1 添加供应商 → Codex OAuth 反向代理](../2-providers/2.1-add.md#codex-oauth-反向代理claude-供应商) 的完整风险提示。

## 关于页面

设置 → 关于 Tab

### 版本信息

显示当前 CC Switch 版本号，支持：

- 查看发布说明
- 检查更新
- 下载并安装新版本

### 本地环境检查

自动检测已安装的 CLI 工具版本：

| 工具     | 检测内容           |
| -------- | ------------------ |
| Claude   | 当前版本、最新版本 |
| Codex    | 当前版本、最新版本 |
| Gemini   | 当前版本、最新版本 |
| OpenCode | 当前版本、最新版本 |
| OpenClaw | 当前版本、最新版本 |
| Hermes   | 当前版本、最新版本 |

点击「刷新」按钮可重新检测；检测到新版时可单独升级，也可以点击「全部升级」。未检测到的工具会显示安装按钮。安装与升级在后台静默执行，按钮上会显示进度，完成后自动刷新版本。

### 手动安装命令

提供快速安装/升级 CLI 工具的命令（该区域默认折叠，点击标题展开）：

```bash
npm i -g @anthropic-ai/claude-code@latest
npm i -g @openai/codex@latest
npm i -g @google/gemini-cli@latest
npm i -g opencode-ai@latest
npm i -g openclaw@latest
python3 -m pip install --upgrade "hermes-agent[web]"
```

点击「复制」按钮可复制到剪贴板。
