🧹 OpenClaw Cleaner (清理大师)

项目目录清理与优化工具

English Version

安装

方式 1：本地安装（推荐用于 OpenClaw）

# 在项目目录中安装
npm install openclaw-cleaner

# 运行
node node_modules/openclaw-cleaner/scripts/cleaner.js health

方式 2：使用 npx（无需全局安装）

npx openclaw-cleaner health
npx openclaw-cleaner optimize
npx openclaw-cleaner snapshot --name my-snapshot

方式 3：全局安装

npm install -g openclaw-cleaner

# 可能需要配置 PATH
export PATH="$PATH:$(npm root -g)"

使用

方式 1：全局安装后直接运行

# 需要将 npm 全局路径添加到 PATH
export PATH="$PATH:$(npm root -g)"

# 或者重新加载 shell
source ~/.bashrc

# 然后直接运行
openclaw-cleaner health

方式 2：使用 npx（推荐）

# 无需安装，直接运行
npx openclaw-cleaner health
npx openclaw-cleaner optimize
npx openclaw-cleaner snapshot --name my-snapshot

方式 3：本地运行

# 克隆仓库
git clone https://github.com/computersniper/openclaw-cleaner.git
cd openclaw-cleaner

# 运行
node scripts/cleaner.js health

常见问题

command not found

在 OpenClaw 环境中，全局安装可能不在 PATH 中。请使用以下方法：

# 方法 1：使用 npx（推荐）
npx openclaw-cleaner health

# 方法 2：本地安装
npm install openclaw-cleaner
node node_modules/openclaw-cleaner/scripts/cleaner.js health

工作空间路径

默认操作当前目录：

# 当前目录
npx openclaw-cleaner health

# 指定路径
npx openclaw-cleaner health --path /your/workspace/path

备份文件位置

自动创建的备份和快照保存在工作空间的 .cleaner-backups 目录下：

<工作空间>/.cleaner-backups/
├── backups/           # 手动备份
├── snapshots/         # 文件快照
├── checkpoints/       # 检查点
└── progress/         # 任务进度

功能特性

✨ 核心功能

1. 目录健康检查 - 评估工作空间目录结构是否符合规范
2. 优化建议 - 提供具体的目录优化建议，减少冗余
3. 代理工作区域维护 - 确保各代理有独立的工作空间
4. 强力清理 - 完全删除指定skill的所有相关文件
5. 自动优化 - 一键优化，保留完整备份
6. 优先级管理 - 识别并调整低价值skill优先级
7. 快照管理 - 创建、列出、删除文件快照
8. 可视化 Diff - 对比快照差异，展示新增/删除/修改
9. 检查点 (Checkpoint) - 重要操作前自动保存，崩溃可恢复
10. 任务进度管理 - 长时间任务保存进度，支持断点续做

安装

# 本地安装
npm install openclaw-cleaner

# 或全局安装
npm install -g openclaw-cleaner

使用方法

命令行

# 检查目录健康度
openclaw-cleaner health

# 获取优化建议
openclaw-cleaner suggest

# 强力删除指定 skill
openclaw-cleaner remove <skill-name>

# 创建备份
openclaw-cleaner backup [name]

# 列出所有备份
openclaw-cleaner list-backups

# 自动优化
openclaw-cleaner optimize

# 创建快照
openclaw-cleaner snapshot --name my-snapshot

# 列出快照
openclaw-cleaner snapshot --list

# 对比快照差异
openclaw-cleaner diff --before <快照1> --after <快照2>

# Markdown 格式输出
openclaw-cleaner diff --before <快照1> --after <快照2> --markdown

Node.js API

const cleaner = require('openclaw-cleaner');

// 检查健康度
const health = cleaner.checkHealth();

// 自动优化
const result = cleaner.autoOptimize();

// 强力删除
const removed = cleaner.forceRemoveSkill('skill-name');

目录规范

推荐的工作空间结构：

/workspace/
├── agents/                    # 代理工作空间
│   ├── daily_assistant/      # 日常助理
│   │   ├── workspace/
│   │   ├── logs/
│   │   └── memory/
│   ├── coding_expert/        # 代码专家
│   │   ├── workspace/
│   │   ├── logs/
│   │   └── memory/
│   └── server_admin/        # 服务器管理员
│       ├── workspace/
│       ├── logs/
│       └── memory/
├── skills/                   # 技能目录
├── memory/                   # 记忆文件
│   └── YYYY-MM-DD.md       # 每日日志
├── shared/                   # 共享资源
├── AGENTS.md                # 工作空间指南
├── SOUL.md                  # 行为准则
├── USER.md                  # 用户信息
├── MEMORY.md                # 长期记忆
└── TOOLS.md                 # 工具配置

配置

可在项目根目录创建 cleaner-config.json:

{
  "backupDir": ".cleaner-backups",
  "maxBackups": 10,
  "ignorePatterns": [
    "*.log",
    "*.tmp",
    ".git"
  ],
  "autoOptimize": {
    "removeTempFiles": true,
    "compressOldMemory": true,
    "archiveDays": 30
  }
}

备份与回滚

所有优化操作自动创建备份，可通过 list-backups 查看，restore 回滚。

快照与 Diff

快照功能

快照可以捕获项目当前的文件状态，方便后续对比和回溯：

# 创建快照
openclaw-cleaner snapshot --name before-cleanup

# 列出所有快照
openclaw-cleaner snapshot --list

# 删除快照
openclaw-cleaner snapshot --delete <快照名>

Diff 对比

对比两个快照之间的差异，查看新增、删除、修改的文件：

# 对比两个快照
openclaw-cleaner diff --before <旧快照> --after <新快照>

# 输出 Markdown 格式报告
openclaw-cleaner diff --before <旧快照> --after <新快照> --markdown

检查点 (Checkpoint)

检查点用于在重要操作前保存状态，崩溃后可快速恢复：

# 创建检查点
openclaw-cleaner checkpoint --create before-dangerous-operation

# 列出所有检查点
openclaw-cleaner checkpoint --list

# 恢复到指定检查点
openclaw-cleaner checkpoint --restore <检查点ID>

# 删除检查点
openclaw-cleaner checkpoint --delete <检查点ID>

任务进度管理

长时间任务可以保存进度，中断后可从断点继续：

# 查看任务列表
openclaw-cleaner task --list

# 查看任务详情
openclaw-cleaner task --status <任务ID>

# 暂停任务
openclaw-cleaner task --pause <任务ID>

# 恢复任务
openclaw-cleaner task --resume <任务ID>

# 删除任务记录
openclaw-cleaner task --delete <任务ID>

程序化使用示例：

import ProgressSnapshotService from './src/services/ProgressSnapshotService.js';

const progress = new ProgressSnapshotService('/workspace');

// 开始长时间任务
const task = await progress.startTask('cleanup', [
  { file: 'file1.txt' },
  { file: 'file2.txt' },
  { file: 'file3.txt' },
]);

// 处理每个任务项
for (let i = 0; i < task.items.length; i++) {
  try {
    // 处理...
    await progress.markCompleted(task.id, i);
  } catch (error) {
    await progress.markFailed(task.id, i, error.message);
  }
}

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT