数据管理

了解 Wesclaw 如何存储和管理你的数据，以及如何进行备份、恢复、导出和隐私保护。

数据存储

存储架构

Wesclaw 采用本地优先（Local-First）的数据存储策略。桌面端的数据完全保存在你的电脑上。

数据根目录：
  macOS:   ~/Library/Application Support/wesclaw/
  Linux:   ~/.local/share/wesclaw/
  Windows: %APPDATA%\wesclaw\

目录结构

wesclaw/
├── hypervisor.db          # Cell 注册表（引擎管理数据）
├── cells/main/            # 主 Cell 数据（你的 AI 助手数据）
│   ├── meta.db            # Cell 元数据
│   ├── sessions.db        # 会话和记忆数据
│   ├── state.db           # 运行时状态（Traces、Observe）
│   ├── skills/            # 已安装的技能包
│   ├── knowledge/         # 知识库文件
│   ├── workspace/         # AI 产出的工作文件
│   └── .scratch/          # 临时计算文件（自动清理）
├── db/
│   └── wesclaw.db         # 应用层数据（对话列表、设置等）
├── crashes/               # 崩溃日志
└── logs/                  # 运行日志

数据类别

类别	存储位置	说明
对话记录	`cells/main/sessions.db`	所有聊天消息和会话
记忆	`cells/main/sessions.db`	AI 的记忆内容（四层）
技能	`cells/main/skills/`	已安装的技能文件
知识库	`cells/main/knowledge/`	上传的知识库文档
Agent 配置	`cells/main/state.db`	Agent 定义和设置
应用设置	`wesclaw.db`	界面偏好、应用配置
Provider 配置	`hypervisor.db`	AI 模型提供商配置
登录凭证	`db/wesclaw_auth.db`	登录会话信息

备份恢复

手动备份

方法一：整体备份

直接复制整个数据目录即可完成备份：

# macOS
cp -r ~/Library/Application\ Support/wesclaw/ ~/Desktop/wesclaw-backup/

# Linux
cp -r ~/.local/share/wesclaw/ ~/wesclaw-backup/

重要：备份时请先关闭 Wesclaw，确保数据库文件不被占用。

方法二：选择性备份

只备份关键数据：

# 备份会话和记忆
cp cells/main/sessions.db ~/backup/

# 备份应用配置
cp wesclaw.db ~/backup/

# 备份技能
cp -r cells/main/skills/ ~/backup/skills/

# 备份知识库
cp -r cells/main/knowledge/ ~/backup/knowledge/

自动备份

建议配置系统级的自动备份方案：

平台	推荐方案
macOS	Time Machine 自动包含
Linux	rsync 定时任务
Windows	文件历史记录

从备份恢复

关闭 Wesclaw
将备份文件复制到对应目录
重新启动 Wesclaw

# 关闭 Wesclaw 后执行
cp -r ~/Desktop/wesclaw-backup/ ~/Library/Application\ Support/wesclaw/

注意：恢复操作会覆盖当前数据，请确认后再执行。

数据导出

导出对话记录

将对话记录导出为可读格式：

导出方式：
- 设置 → 数据管理 → 导出对话
- 选择时间范围和格式

支持格式：
- Markdown（.md）
- JSON（.json）
- 纯文本（.txt）

导出 Cell 数据

利用引擎的 Cell 导出功能，完整导出所有数据：

设置 → 数据管理 → 导出 Cell

导出内容包括：
✅ 会话记录
✅ 记忆数据
✅ Agent 配置
✅ 技能
✅ 知识库
✅ 工作文件

导出格式：tar.gz 归档文件

导入 Cell 数据

将导出的 Cell 数据导入到另一台设备：

设置 → 数据管理 → 导入 Cell
选择之前导出的 .tar.gz 文件

隐私保护

数据本地化

桌面端的核心原则是数据不离开你的设备：

所有对话记录存储在本地 SQLite 数据库中
记忆数据保存在本地
知识库文件保存在本地
不会自动上传数据到任何云服务

AI 模型交互

与 AI 模型的通信是必要的数据传输：

数据流	传输内容	说明
发送到模型	对话消息、系统提示词	经过加密的 HTTPS 传输
从模型返回	AI 回复内容	经过加密的 HTTPS 传输
不传输	历史记忆、本地文件、知识库原文	仅在本地使用

记忆内容只在需要时被注入到提示词中发送给模型，而非自动上传。

凭证加密

API Key 等敏感凭证采用 AES-256-GCM 加密存储：

明文凭证 → AES-256-GCM 加密 → 密文存入 hypervisor.db
                ↑
           spec.key（本地密钥文件）

密钥文件 spec.key 权限为 0600
未经加密的明文凭证不会出现在配置文件中
导出 Cell 数据时，凭证不包含在导出包中

日志隐私

应用日志中不记录以下信息：

API Key 和密码（已脱敏）
对话的完整内容
用户的个人身份信息

存储优化

磁盘占用查看

设置 → 数据管理 → 存储统计

会话数据：xxx MB
记忆数据：xxx MB
知识库：xxx MB
技能：xxx MB
日志文件：xxx MB
缓存/临时文件：xxx MB
---
总计：xxx MB

清理方案

清理临时文件

.scratch/ 目录中的临时文件在每次 Run 结束后自动清理。如果异常退出导致残留：

设置 → 数据管理 → 清理临时文件

清理旧对话

长期使用后，对话记录可能占用较多空间：

设置 → 数据管理 → 对话管理
- 删除 30 天前的对话
- 删除指定对话
- 清空所有对话（谨慎！）

清理日志

设置 → 数据管理 → 日志管理
- 清理 30 天前的日志
- 当前日志大小：xxx MB

数据库优化

长期使用后数据库可能出现碎片，可以进行优化：

设置 → 数据管理 → 数据库优化

执行 VACUUM 操作，压缩数据库文件。
注意：此操作期间 Wesclaw 可能短暂卡顿。

数据迁移

换机迁移

将数据从旧电脑迁移到新电脑：

方法一：整体迁移

1. 在旧电脑关闭 Wesclaw
2. 复制整个数据目录到 U 盘或网络
3. 在新电脑安装 Wesclaw（先不启动）
4. 将备份的数据目录复制到新电脑对应位置
5. 启动 Wesclaw

方法二：Cell 导出/导入

1. 在旧电脑：设置 → 导出 Cell → 保存 .tar.gz 文件
2. 传输文件到新电脑
3. 在新电脑：设置 → 导入 Cell → 选择 .tar.gz 文件

Cell 导入/导出不包含 API Key 等凭证信息，需要在新电脑上重新配置。

跨平台迁移

从 macOS 迁移到 Linux（或反向）：

使用 Cell 导出功能
传输导出文件
在目标平台导入

数据格式兼容不同操作系统，无需额外转换。

常见问题

数据目录在哪里

macOS:   ~/Library/Application Support/wesclaw/
Linux:   ~/.local/share/wesclaw/
Windows: %APPDATA%\wesclaw\

也可以通过环境变量 WESCLAW_DATA_DIR 自定义位置。

数据目录很大怎么办

排查大文件：

# macOS / Linux
du -sh ~/Library/Application\ Support/wesclaw/*
du -sh ~/Library/Application\ Support/wesclaw/cells/main/*

通常占用空间最多的是知识库文件和会话数据。

误删了数据怎么办

如果有 Time Machine 或其他备份，从备份恢复
如果没有备份，已删除的数据无法恢复
建议定期备份重要数据

多设备同步

Wesclaw 桌面端目前不提供内置的多设备同步功能。如需多设备使用：

使用 Cell 导出/导入手动同步
或使用 Wesclaw SaaS 版，数据自动在云端同步