ClawdBotUI操作指南：Workspace目录结构说明与文件自动清理策略
1. ClawdBot是什么：一个真正属于你的本地AI助手
ClawdBot不是云端服务，也不是需要注册账号的SaaS工具。它是一个你可以在自己电脑、服务器甚至树莓派上完整运行的个人AI助手——所有推理、对话、文件处理都在你自己的设备上完成，数据从不离开你的控制范围。
它的后端由vLLM提供高性能模型服务能力，这意味着你能以极低的硬件门槛（比如一台8GB内存的笔记本）流畅运行Qwen3-4B这类高质量开源模型。没有API调用限制，没有按Token计费，没有隐私泄露风险。你输入的每句话、上传的每张图、生成的每段内容，都只存在于你的硬盘里。
很多人第一次听说ClawdBot时会下意识把它和ChatGPT或Claude对比，但这种对比本身就不成立——ClawdBot的定位完全不同：它不追求“最强大”，而是追求“最可控”；不强调“最智能”，而是强调“最可靠”。它像一个安静待命的数字同事，随时准备帮你整理会议纪要、翻译技术文档、分析项目日志，或者只是陪你头脑风暴写一封得体的邮件。
而ClawdBotUI，就是这个本地AI助手的可视化操作界面。它不是花哨的演示页面，而是一个真正为日常工程使用设计的控制台：你可以在这里管理模型、查看对话历史、配置工作区、监控资源占用，甚至一键触发文件清理。接下来的内容，就聚焦在两个最常被问到、也最容易被忽略的关键点上：Workspace目录到底长什么样？以及那些悄悄堆积的临时文件，到底该怎么安全又彻底地清理？
2. Workspace目录结构详解：不只是一个文件夹
当你在ClawdBotUI中看到“Workspace”这个词，它指的不是一个抽象概念，而是一个真实存在的、路径明确的文件系统位置。默认情况下，它被配置为/app/workspace（如配置文件所示），并且已通过Docker映射到宿主机的某个目录（通常是~/.clawdbot/workspace）。理解这个目录的内部结构，是高效使用ClawdBot的基础。
2.1 标准目录层级与核心子目录
进入/app/workspace后，你会看到几个命名清晰、职责分明的子目录。它们不是随机生成的，而是ClawdBot在运行过程中，根据不同任务类型自动创建和维护的：
conversations/：存放所有对话记录的JSON文件。每个文件以时间戳+会话ID命名（如20260125_142233_abc123.json），内容包含完整的用户提问、AI回复、使用的模型、耗时等元数据。这是你回溯历史、复现问题、导出知识库的唯一来源。uploads/：所有你通过UI上传的文件（图片、PDF、TXT等）都会先落在此处。文件名会被重命名为哈希值（如a1b2c3d4e5f67890.jpg），避免命名冲突，并附带一个同名的.meta.json文件，记录原始文件名、上传时间、MIME类型等信息。exports/：当你点击“导出对话”或“下载分析结果”时，生成的ZIP包、Markdown文档、CSV表格等，都会存放在这个目录。它是一个纯粹的输出区，内容可随时删除，不影响系统运行。cache/：这是最“隐形”但也最关键的目录。它存储模型推理过程中的中间缓存，比如：kv_cache/：vLLM的键值缓存快照，用于加速连续对话；embeddings/：文档切片后的向量表示，供RAG检索使用；thumbnails/：图片上传后自动生成的缩略图，用于UI快速预览。
重要提示：
cache/目录下的文件绝不能手动删除。vLLM的缓存有严格的生命周期管理，直接删掉KV缓存文件可能导致后续对话卡死或报错。正确的清理方式，我们会在下一节详细说明。
2.2 文件命名与元数据：让机器可读，也让人可查
ClawdBot在设计文件命名规则时，刻意避开了“user_report_v2_final_new.pdf”这类人类友好但机器难解析的名字。取而代之的是：
- 确定性哈希命名：所有上传文件、缓存块均使用SHA-256前16位作为文件名。这保证了相同内容的文件永远不会重复存储，也便于去重和校验。
- 结构化元数据：每个业务文件（如
conversations/下的JSON）都遵循统一Schema。例如，一段对话记录的JSON中，必含"session_id"、"model_used"、"timestamp_start"、"tokens_input"、"tokens_output"等字段。这意味着你可以用任何脚本（Python、jq、甚至Excel）轻松统计：“过去一周，我平均每次提问消耗多少token？”、“哪个模型被调用次数最多？”。
这种设计带来的实际好处是：当你的Workspace增长到几十GB时，你依然能用一条命令快速定位问题。比如，想找出所有超过5MB的上传图片，只需执行：
find /app/workspace/uploads -name "*.jpg" -size +5M -ls3. 文件自动清理策略：安全、可控、不误删
随着使用时间增长，Workspace目录会不可避免地膨胀。一张高清截图、一份百页PDF、一次长对话的缓存……日积月累，可能悄无声息地吃掉你一半的磁盘空间。ClawdBot没有采用“一刀切”的定时清理，而是提供了一套分层、可配置、带保护机制的自动清理策略。
3.1 三种清理模式：从保守到激进
在clawdbot.json配置文件中，"compaction"节点定义了清理行为。它支持三种模式，对应不同的安全等级和清理力度：
| 模式名称 | 触发条件 | 清理范围 | 安全等级 | 适用场景 |
|---|---|---|---|---|
safeguard（默认） | 每次启动ClawdBot时检查 | 只清理exports/中超过7天的文件；cache/中过期（>24h）且未被引用的缩略图 | 绝大多数用户，零风险，推荐新手长期使用 | |
balanced | 每小时后台检查一次 | 清理exports/（7天）、uploads/中无对应.meta.json的孤立文件、cache/thumbnails/（全部） | 中等活跃用户，希望保持Workspace整洁，同时保留所有原始上传 | |
aggressive | 每30分钟后台检查一次 | 清理exports/（3天）、uploads/（所有，仅保留最近30个）、cache/中所有过期缓存（包括KV） | 高频测试用户、资源极度紧张的嵌入式设备（如树莓派），需谨慎启用 |
关键区别在于
cache/kv_cache/：safeguard和balanced模式完全不碰KV缓存，因为它是vLLM性能的核心；只有aggressive模式会清理它，但这会导致下次对话启动变慢（需重建缓存），且可能中断正在进行的长会话。
3.2 如何修改清理策略：配置即生效
修改策略无需重启服务，只需编辑配置文件并发送一个轻量级重载信号：
- 打开配置文件：
nano /app/clawdbot.json- 找到
"compaction"节点，将"mode"的值改为所需模式：
"compaction": { "mode": "balanced" }- 保存后，执行重载命令（不中断服务）：
clawdbot config reload你将在终端看到类似提示：
🦞 Clawdbot 2026.1.24-3 — Compaction policy reloaded: mode=balanced, next check in 59m 23s.此时，新的清理策略已生效。你也可以通过UI左下角的“Status”面板，实时查看当前模式、下次清理时间、以及Workspace总大小。
3.3 手动触发清理：精准控制，立竿见影
除了自动策略，ClawdBot还提供了三个精准的手动清理命令，满足临时性、诊断性需求：
清理所有导出文件（最安全）：
clawdbot workspace clean exports立即清空
exports/目录，释放空间，无任何副作用。清理孤立上传文件（推荐定期执行）：
clawdbot workspace clean uploads --orphaned扫描
uploads/目录，删除所有没有对应.meta.json文件的“孤儿”文件。这些通常是上传失败、或被其他程序误删元数据后残留的垃圾。深度清理缓存（高级用户）：
clawdbot workspace clean cache --deep这会强制vLLM释放所有KV缓存，并清空
cache/embeddings/。执行前请确保没有进行中的长对话。执行后首次新对话会稍慢，但之后性能将恢复到最佳状态。
4. 实战建议：让Workspace始终清爽高效
光知道怎么清理还不够，真正的效率提升来自于建立一套符合你工作流的习惯。以下是基于大量用户反馈总结的几条实战建议：
4.1 建立“上传-处理-归档”闭环
很多用户把ClawdBot当作一个临时上传工具，传完就不管了。这恰恰是Workspace膨胀的主因。建议采用三步法：
- 上传时明确目的：在UI中上传文件前，先在心里问一句：“我这次是要让它帮我总结，还是提取表格，还是单纯存档？”
- 处理后立即归档：如果文件需要长期保存，处理完后立刻将其从
uploads/移动到你个人的Documents/AI-Projects/目录下，并在ClawdBotUI中点击该文件旁的“🗑 Remove from Workspace”按钮。 - 设置定期归档提醒：在手机日历中设置每周一上午10点的提醒：“检查ClawdBot uploads/，归档重要文件”。
这样，uploads/就真正变成了一个“临时中转站”，而非“永久仓库”。
4.2 利用对话标签，替代文件分类
ClawdBotUI支持给每段对话打多个标签（如#report、#code-review、#meeting-notes）。这比在文件系统里建一堆文件夹更灵活。当你需要查找某类内容时，直接在UI顶部搜索框输入tag:report，所有带此标签的对话会瞬间聚合。这不仅节省了文件系统管理精力，也让知识检索变得无比简单。
4.3 监控磁盘使用，防患于未然
ClawdBotUI右上角的“System Status”面板会显示Workspace当前占用的磁盘空间。建议养成习惯：每次打开UI时，花2秒扫一眼这个数字。如果发现它在一周内增长超过30%，就该执行一次clawdbot workspace clean uploads --orphaned，往往就能解决80%的异常增长。
5. 总结：掌控Workspace，就是掌控你的AI工作流
ClawdBot的Workspace，远不止是一个存放文件的目录。它是一个有生命、有逻辑、有策略的数字工作空间。理解它的结构，就是理解ClawdBot如何思考、如何记忆、如何为你服务；掌握它的清理策略，就是掌握一种数字时代的“断舍离”能力——在不牺牲功能的前提下，持续释放资源、降低维护成本、提升响应速度。
从今天开始，你可以做的三件小事：
- 花5分钟，用
ls -lh /app/workspace命令，亲自看看你的Workspace现在是什么样子； - 将
compaction.mode从默认的safeguard，尝试调整为balanced，观察一周内的变化； - 在下次上传重要文件前，先给它打上一个有意义的标签。
真正的技术自由，不在于拥有多少算力，而在于对每一个字节的来龙去脉，都了然于心。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
