docs: update user manual to v3.12.3 with new features coverage (en/zh/ja)

Add documentation for features introduced since v3.12.0:

New docs:
- 3.4 Session Manager: browse, search, resume, delete sessions
- 3.5 Workspace & Daily Memory: OpenClaw workspace file editing

Updated docs:
- Add Lightweight Mode to interface overview and FAQ
- Add tray submenu structure (providers grouped by app)
- Add API Format selection (Anthropic/OpenAI Chat/OpenAI Responses)
- Add Auto-Fetch Models button documentation
- Add Claude Common Config quick toggles
- Add Codex 1M Context Window toggle
- Add Skill backup/restore lifecycle
- Expand Backup Management panel documentation
- Update WebDAV sync to v2 protocol with dual-layer versioning
- Add OpenCode/OpenClaw to quickstart activation table
- Update README version to v3.12.3

All changes synced across en, zh, and ja locales.
This commit is contained in:
Jason
2026-04-04 12:20:13 +08:00
parent fe525891d4
commit d9c0e4c452
39 changed files with 1282 additions and 97 deletions
@@ -100,10 +100,13 @@ CC Switch 在系统托盘显示图标,提供快速操作入口。
| 菜单项 | 功能 |
|--------|------|
| 打开主界面 | 显示主窗口并聚焦 |
| 应用分组 | 按 Claude/Codex/Gemini/OpenCode/OpenClaw 分组显示供应商 |
| 供应商列表 | 点击切换,当前启用的显示勾选标记 |
| 应用子菜单 | 按 Claude/Codex/Gemini/OpenCode/OpenClaw 分组的折叠子菜单(如 "Claude · PackyCode" |
| 供应商列表 | 在每个子菜单内,点击切换,当前启用的显示勾选标记 |
| 轻量模式 | 勾选框切换,进入/退出仅托盘运行模式 |
| 退出 | 完全退出应用 |
> **注意**:每个应用子菜单的标题会显示当前供应商名称(如 "Claude · PackyCode")。没有配置供应商的应用会显示禁用的"(无供应商)"条目。应用可见性由设置中的"应用可见性"选项控制。
### 多语言支持
托盘菜单支持三种语言,根据设置自动切换:
@@ -114,6 +117,17 @@ CC Switch 在系统托盘显示图标,提供快速操作入口。
| English | Open main window | Quit |
| 日本語 | メインウィンドウを開く | 終了 |
### 轻量模式
托盘菜单包含 **轻量模式** 切换开关(勾选框)。启用后:
- 主窗口关闭以释放资源
- 应用仅在系统托盘中运行
- 你仍可通过托盘子菜单切换供应商
- 在 macOS 上,Dock 图标也会隐藏
要退出轻量模式,取消勾选该选项或点击"打开主界面" — 主窗口将被重建并显示。
### 使用场景
托盘切换供应商无需打开主界面,适合:
@@ -121,6 +135,7 @@ CC Switch 在系统托盘显示图标,提供快速操作入口。
- 频繁切换供应商
- 主窗口最小化时快速操作
- 后台运行时管理配置
- 使用轻量模式以最小化资源占用
## 设置页面
@@ -33,8 +33,10 @@
| 应用 | 生效方式 |
|------|----------|
| Claude Code | ✅ 即时生效(支持热重载) |
| Codex | 需关闭并重新打开终端 |
| Codex | 需关闭并重新打开终端 |
| Gemini | ✅ 即时生效(每次请求重新读取配置) |
| OpenCode | 需要关闭并重新打开终端 |
| OpenClaw | 需要关闭并重新打开终端 |
### Claude Code 首次安装提示
@@ -64,6 +66,14 @@ codex
# Gemini - 启动后输入测试问题
gemini
> 你好,请简单介绍一下自己
# OpenCode - 启动后输入测试问题
opencode
> 你好,请简单介绍一下自己
# OpenClaw - 启动后输入测试问题
openclaw
> 你好,请简单介绍一下自己
```
如果 AI 能正常回复,说明配置成功。
@@ -167,37 +167,74 @@ CC Switch 自身数据的存储位置,默认为 `~/.cc-switch/`。
### 备份与恢复
管理自动备份:
备份管理面板提供对数据库备份的全面控制。
| 配置 | 说明 |
| -------- | -------------------------- |
| 备份间隔 | 自动备份的时间间隔(小时) |
| 保留数量 | 保留的备份份数 |
#### 自动备份设置
支持查看备份列表和从备份恢复。
| 配置 | 选项 | 默认值 |
| -------- | ---------------------------------- | --------- |
| 备份间隔 | 禁用、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 协议在多台设备间同步配置。
通过 WebDAV 协议在多台设备间同步配置。使用 **v2 协议**,支持双层版本控制,提高可靠性。
| 配置项 | 说明 |
| -------- | ------------------------------------- |
| 服务预设 | 坚果云 / Nextcloud / 群晖 / 自定义 |
| 服务地址 | WebDAV 服务器 URL |
| 用户名 | 登录用户名 |
| 密码 | 登录密码(应用专用密码 |
| 远程目录 | 远程存储路径(默认 `cc-switch-sync` |
| 配置名称 | 设备配置文件名(默认 `default` |
| 自动同步 | 开启后自动上传变更 |
| 配置项 | 说明 |
| -------- | ---------------------------------------------------------------------------- |
| 服务预设 | 坚果云 / Nextcloud / 群晖 / 自定义 |
| 服务地址 | WebDAV 服务器 URL |
| 用户名 | 登录用户名 |
| 密码 | 登录密码(应用专用密码;已保存的凭据在未修改时会被保留) |
| 远程目录 | 远程存储路径(默认 `cc-switch-sync` |
| 配置名称 | 设备配置文件名(默认 `default` |
| 自动同步 | 开启后按配置的间隔自动同步 |
操作:
#### 操作
- **测试连接**:验证 WebDAV 配置是否正确
- **保存**:保存配置并自动测试
- **上传**:将本地数据上传到远程
- **下载**:从远程下载数据到本地
| 操作 | 说明 |
| ------------ | -------------------------------------------------------------------------------------------- |
| **测试连接** | 验证 WebDAV URL、用户名和密码是否有效 |
| **上传** | 将本地数据库上传到远程,显示进度指示器 |
| **下载** | 下载远程数据库。下载前显示远程快照信息(协议版本、数据库版本、时间戳、大小)供确认。覆盖本地数据库前会自动创建安全备份 |
> ⚠️ **注意**:上传会覆盖远程数据,下载会覆盖本地数据。操作前请确认。
#### 自动同步
启用 **自动同步** 后:
- 首次激活时会显示确认对话框
- CC Switch 按配置的间隔自动将数据库同步到 WebDAV
- 面板中显示同步状态
#### 远程快照信息
下载前,CC Switch 会显示远程快照的详细信息:
- 协议版本(v2
- 数据库兼容版本
- 远程备份的时间戳
- 文件大小
- 兼容性状态(不兼容时显示警告)
> ⚠️ **注意**:上传会覆盖远程数据,下载会覆盖本地数据。下载前始终会自动创建安全备份。
### 日志配置
@@ -152,6 +152,22 @@
| AWS Bedrock | AWS Bedrock 服务 |
| OpenAI Compatible | OpenAI 兼容接口 |
## 自动获取模型
添加或编辑供应商时,可以自动从供应商端点获取可用模型列表:
1. 确保已填写 **API Key****端点地址**
2. 点击模型输入框旁的 **获取模型** 按钮(下载图标)
3. CC Switch 调用供应商的 `/v1/models` 端点获取模型列表
4. 从按供应商分组的下拉菜单中选择模型
此功能适用于所有支持 OpenAI 兼容 `/v1/models` API 的供应商。Claude、Codex、Gemini、OpenCode 和 OpenClaw 供应商均可使用。
**常见错误**
- **认证失败(401/403**:检查你的 API Key
- **端点不支持(404/405)**:该供应商未提供 `/v1/models` 端点
- **超时**:端点响应缓慢,请稍后重试
## 自定义配置
选择「自定义」预设后,需要手动编辑 JSON 配置。
@@ -316,6 +332,45 @@ CC Switch 支持两种方式导入供应商配置:
## 高级选项
### API 格式(仅 Claude
添加使用第三方 API 的 Claude 供应商时,可能需要在高级选项中选择正确的 **API 格式**
| 格式 | 说明 | 适用场景 |
|------|------|----------|
| **Anthropic Messages** | 原生 Anthropic API 格式(默认) | 直接 Anthropic API 或兼容代理 |
| **OpenAI Chat Completions** | OpenAI Chat API 格式,由代理自动转换 | 供应商仅支持 OpenAI Chat 格式 |
| **OpenAI Responses API** | OpenAI Responses API 格式,由代理自动转换 | 供应商仅支持 OpenAI Responses 格式 |
> **注意**:API 格式转换由代理服务处理。使用非 Anthropic 格式时,需要开启代理并启用应用接管才能正确转换请求/响应。详见 [4.1 代理服务](../4-proxy/4.1-service.md)。
当配置了非默认 API 格式时,高级选项区域会自动展开。
### Claude 通用配置快捷开关
编辑 Claude 供应商时,JSON 编辑器上方提供一组 **快捷开关**
| 开关 | 效果 | 配置变更 |
|------|------|----------|
| **隐藏署名** | 清除提交/PR 的署名元数据 | 设置 `attribution: {commit: "", pr: ""}` |
| **启用 Teammates** | 启用 Agent 团队功能 | 设置 `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"` |
| **启用工具搜索** | 启用工具搜索功能 | 设置 `env.ENABLE_TOOL_SEARCH = "true"` |
| **高效能模式** | 将 effort 级别设为 high | 设置 `effortLevel = "high"` |
| **禁用自动更新** | 阻止 Claude Code 自动更新 | 设置 `env.DISABLE_AUTOUPDATER = "1"` |
取消勾选开关时,对应的配置项会被完全移除。更改会实时反映在 JSON 编辑器中。
此外,**写入通用配置** 复选框可将全局配置片段合并到供应商中。点击 **编辑通用配置** 可自定义共享的配置片段。
### Codex 1M 上下文窗口
添加 Codex 供应商时,提供 **启用 1M 上下文窗口** 开关:
- **启用时**:在 config.toml 中设置 `model_context_window = 1000000` 并自动填充 `model_auto_compact_token_limit = 900000`
- **禁用时**:移除这两个字段
开关开启后显示的文本框可自定义自动压缩限制值。
### 自定义图标
点击名称左侧的图标区域,可以:
@@ -26,10 +26,12 @@
### 操作步骤
1. 右键点击系统托盘的 CC Switch 图标
2. 在菜单中找到对应应用(Claude/Codex/Gemini/OpenCode
3. 点击要切换的供应商名称
2. 将鼠标悬停在对应应用的子菜单上(如 "Claude · 当前供应商"
3. 点击要切换的供应商名称
4. 切换完成,托盘会短暂提示
> 供应商按应用类型(Claude/Codex/Gemini)组织到折叠子菜单中。子菜单标题显示当前激活的供应商名称。
### 托盘菜单结构
![image-20260108004348993](../../assets/image-20260108004348993.png)
@@ -52,6 +52,20 @@ JSON 格式的配置内容,包括:
这确保了 CC Switch 和 CLI 工具的配置始终同步。
## 自动获取模型
编辑供应商时,可以自动从供应商端点获取可用模型列表:
1. 确保已填写 API Key 和端点地址
2. 点击模型输入框旁的 **获取模型** 按钮(下载图标)
3. 从分组下拉菜单中选择模型
详细说明请参阅 [2.1 添加供应商 — 自动获取模型](./2.1-add.md#自动获取模型)。
## 通用配置快捷开关(Claude)
编辑 Claude 供应商时,JSON 编辑器上方提供常用设置的快捷开关,包括工具搜索、禁用自动更新、Teammates、高效能模式等。详见 [2.1 添加供应商 — Claude 通用配置快捷开关](./2.1-add.md#claude-通用配置快捷开关)。
## 修改 API Key
编辑供应商时,可以直接在 **API Key** 输入框中修改:
+21 -2
View File
@@ -118,8 +118,27 @@ CC Switch 提供强大的搜索和过滤功能:
### 卸载效果
- 删除本地技能文件夹
- 更新安装状态
- **自动备份**:删除前,技能会被备份到 `~/.cc-switch/skill-backups/`
- 从所有应用目录(Claude、Codex、Gemini、OpenCode)移除技能
- 从 SSOT 目录(`~/.cc-switch/skills/`)移除技能
- 从数据库删除技能记录
### 从备份恢复
如需恢复之前卸载的技能:
1. 打开 Skills 页面
2. 点击 **从备份恢复** 按钮
3. 从列表中选择要恢复的备份(显示技能名称和备份日期)
4. 技能将被恢复并为当前应用启用
### 删除备份
如需删除旧的技能备份:
1. 在恢复对话框中,找到要删除的备份
2. 点击备份条目旁的 **删除** 按钮
3. 确认删除 — 此操作不可撤销
## 仓库管理
@@ -0,0 +1,131 @@
# 3.4 会话管理器
会话管理器可让你在一处浏览、搜索和管理所有支持的 CLI 工具的对话会话。
## 支持的应用
| 应用 | 会话存储位置 |
|------|-------------|
| Claude Code | `~/.cache/claude/projects/*.jsonl` |
| Codex | Codex 配置会话目录 |
| OpenCode | `~/.local/share/opencode/`JSON 或 SQLite |
| OpenClaw | `~/.openclaw/agents/<agent>/sessions/*.jsonl` |
| Gemini CLI | `~/.cache/gemini/tmp/<project_hash>/chats/` |
## 打开会话管理器
点击主导航栏中的 **会话** 按钮。
> **注意**:会话按钮在所有五种应用模式下均可见。
## 界面布局
会话管理器采用 **双栏布局**
- **左侧面板**:会话列表,包含搜索和过滤工具栏
- **右侧面板**:选中会话的详情和对话历史
### 会话列表(左侧面板)
每个会话条目显示:
- 供应商图标
- 会话标题
- 最后活跃时间(相对格式,如"5 分钟前"
### 会话详情(右侧面板)
选中会话后,右侧面板显示:
- **标题**:来自会话标题、项目目录名称或会话 ID
- **最后活跃日期/时间**:完整时间戳
- **项目目录**:可点击复制完整路径(显示目录名,完整路径以提示框显示)
- **恢复命令**:以等宽字体显示(如可用)
- **对话历史**:完整消息记录
## 搜索与过滤
### 全文搜索
使用左侧面板顶部的搜索框,可搜索以下内容:
- 会话 ID
- 标题
- 摘要
- 项目目录
- 源文件路径
搜索支持前缀匹配,实时过滤结果。按 **Esc** 清除搜索。
### 供应商过滤
点击左侧面板右上角的供应商过滤下拉菜单,按应用过滤:
- **全部** — 显示所有供应商的会话
- **Claude Code**
- **Codex**
- **OpenCode**
- **OpenClaw**
- **Gemini CLI**
过滤可与搜索组合使用。
### 刷新
点击刷新按钮(圆形箭头图标),重新扫描所有供应商目录以发现新增或已删除的会话。
## 会话操作
### 恢复会话
点击选中会话上的 **恢复** 按钮(播放图标)继续对话。
**macOS 上**
- CC Switch 使用你偏好的终端启动恢复命令
- 终端会在会话的项目目录中打开
- 如果终端启动失败,命令会被复制到剪贴板
**支持的终端(macOS**Terminal.app、iTerm2、Ghostty、Kitty、WezTerm、Alacritty
**其他平台**
- 恢复命令会被复制到剪贴板
- 在终端中粘贴即可恢复会话
> 如果会话没有可用的恢复命令,恢复按钮将被禁用。
### 删除会话
点击 **删除** 按钮(垃圾桶图标)永久删除会话文件。删除前会显示确认对话框。
> 没有本地源路径的会话(如不可变会话)无法删除。
### 批量操作
批量管理多个会话:
1. 点击左侧面板工具栏中的 **批量模式** 按钮(复选框图标)
2. 使用出现的复选框选择会话
3. 使用 **全选** 选择所有过滤结果,或使用 **清除** 取消选择
4. 点击 **批量删除**(红色垃圾桶图标)删除所有选中的会话
删除前会显示确认对话框并展示数量。结果会报告成功删除的数量和失败的数量。
## 对话历史
### 消息显示
消息按角色以颜色区分:
- **用户** 消息:绿色,左对齐
- **AI**(助手)消息:蓝色,右对齐
- **系统** 消息:琥珀色
- **工具** 消息:紫色
### 目录导航
对于较长的对话,提供目录导航功能:
- **桌面端(XL+ 屏幕)**:右侧边栏显示用户消息预览
- **较小屏幕**:右下角浮动按钮(列表图标),点击打开对话框
点击任意条目可滚动到对应消息,消息会短暂高亮显示。
## 提示
- 会话按最后活跃时间排序(最新在前)
- 会话数量徽章会随搜索和过滤实时更新
- OpenCode 会话可能来自 JSON 文件和 SQLite 数据库 — 重复项会自动去重
@@ -0,0 +1,85 @@
# 3.5 工作区文件与每日记忆
## 概述
工作区面板为 **OpenClaw** 提供文件管理和每日记忆功能。你可以编辑工作区配置文件并维护每日记忆日志。
> 此功能为 OpenClaw 专属。当 OpenClaw 为当前选中的应用时,导航栏中会显示工作区按钮。
## 工作区文件
### 文件位置
所有工作区文件存储在 `~/.openclaw/workspace/`
点击面板顶部的目录路径可在文件管理器中打开。
### 可用文件
CC Switch 管理 9 个工作区文件,每个文件有特定用途:
| 文件 | 说明 |
|------|------|
| **AGENTS.md** | Agent 定义与配置 |
| **SOUL.md** | 系统灵魂/性格设置 |
| **USER.md** | 用户资料信息 |
| **IDENTITY.md** | 身份与角色定义 |
| **TOOLS.md** | 可用工具配置 |
| **MEMORY.md** | 系统记忆 |
| **HEARTBEAT.md** | 心跳配置 |
| **BOOTSTRAP.md** | 引导序列 |
| **BOOT.md** | 启动配置 |
### 文件状态
每个文件显示状态指示器:
- **绿色对勾**:文件已存在
- **空心圆圈**:文件尚未创建(首次保存时创建)
### 编辑文件
1. 点击任意文件卡片打开 Markdown 编辑器
2. 编辑内容
3. 点击 **保存** 将更改写入磁盘
如果文件尚不存在,将在首次保存时创建。
## 每日记忆
每日记忆功能提供按日期组织的日志系统,存储在 `~/.openclaw/workspace/memory/`
### 访问每日记忆
点击工作区文件网格中的 **每日记忆** 卡片,打开记忆面板。
### 文件列表
面板显示所有每日记忆文件,按日期排序(最新在前)。每个条目显示:
- **日期**(从文件名格式化,如 `2026-04-01.md`
- **文件大小**
- **预览**(内容的前 2 行)
### 创建今日笔记
点击 **创建今日** 按钮:
- 打开以今日日期命名的新笔记(`YYYY-MM-DD.md`
- 如果今日笔记已存在,则打开进行编辑
- 文件仅在点击保存后才会持久化
### 搜索
搜索所有每日记忆文件:
1.**Cmd/Ctrl+F** 或点击搜索图标
2. 输入搜索词
3. 结果显示匹配的文件,包含:
- 每个文件的匹配数量
- 匹配行的片段预览
- 文件日期和大小
**Esc** 关闭搜索。
### 编辑与删除
- **编辑**:点击文件条目在 Markdown 编辑器中打开
- **删除**:将鼠标悬停在文件条目上,点击删除图标。会显示确认对话框 — 删除操作不可撤销。
@@ -150,6 +150,20 @@ base_url = "http://127.0.0.1:15721/v1"
GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:15721
```
## API 格式转换
代理支持为配置了非 Anthropic 格式的供应商自动进行 API 格式转换。这使你可以将仅支持 OpenAI 兼容 API 的供应商用于 Claude Code。
| 供应商 API 格式 | 代理行为 |
|-----------------|----------|
| **Anthropic Messages** | 透传(不转换) |
| **OpenAI Chat Completions** | 将 Anthropic 请求转换为 OpenAI Chat 格式,响应反向转换 |
| **OpenAI Responses API** | 将 Anthropic 请求转换为 OpenAI Responses 格式,响应反向转换 |
API 格式在添加或编辑 Claude 供应商时于[高级选项](../2-providers/2.1-add.md#api-格式仅-claude)中按供应商配置。
> **注意**:格式转换需要代理运行并启用应用接管。转换同时支持流式和非流式请求。
## 停止代理
### 方式一:主界面开关
@@ -12,12 +12,11 @@
```
~/.cc-switch/
├── cc-switch.db # SQLite 数据库
├── cc-switch.db # SQLite 数据库SSOT
├── settings.json # 设备级设置
── backups/ # 自动备份
├── backup-20251230-120000.json
├── backup-20251229-180000.json
└── ...
── skills/ # 技能 SSOT 目录
├── skill-backups/ # 技能备份(卸载时创建)
└── db_backup_*.db # 数据库备份
```
### 数据库内容
@@ -183,6 +183,16 @@ chmod +x CC-Switch-*.AppImage
2. 手动下载最新版本安装
3. 如使用 Homebrew`brew upgrade --cask cc-switch`
## 轻量模式
### 如何进入轻量模式?
从系统托盘菜单切换"轻量模式"。主窗口关闭,CC Switch 仅作为托盘应用运行。再次切换或点击"打开主界面"即可退出。
### 轻量模式下应用占用更少内存?
是的。轻量模式会销毁主窗口及其 Web 视图,显著减少内存占用,同时保留托盘菜单功能。
## 获取帮助
### 提交 Issue
+8 -4
View File
@@ -24,7 +24,9 @@
├── 3. 扩展功能
│ ├── 3.1 MCP 服务器管理
│ ├── 3.2 Prompts 提示词管理
── 3.3 Skills 技能管理
── 3.3 Skills 技能管理
│ ├── 3.4 会话管理器
│ └── 3.5 工作区文件与每日记忆
├── 4. 代理与高可用
│ ├── 4.1 代理服务
@@ -69,6 +71,8 @@
| [3.1-mcp.md](./3-extensions/3.1-mcp.md) | MCP 协议、添加服务器、应用绑定 |
| [3.2-prompts.md](./3-extensions/3.2-prompts.md) | 创建预设、激活切换、智能回填 |
| [3.3-skills.md](./3-extensions/3.3-skills.md) | 发现技能、安装卸载、仓库管理 |
| [3.4-sessions.md](./3-extensions/3.4-sessions.md) | 会话浏览、搜索过滤、恢复与删除 |
| [3.5-workspace.md](./3-extensions/3.5-workspace.md) | OpenClaw 工作区文件、每日记忆 |
### 4. 代理与高可用
@@ -99,9 +103,9 @@
## 版本信息
- 文档版本:v3.12.0
- 最后更新:2026-03-09
- 适用于 CC Switch v3.12.0+
- 文档版本:v3.12.3
- 最后更新:2026-04-04
- 适用于 CC Switch v3.12.3+
## 贡献