luw2007/openclaw-workspace-clean-guide.md

## openclaw-workspace-clean-guide.md

      
    Raw
  

              openclaw-workspace-clean-guide.md
            
          
目标：让 `openclaw/workspace``永远“可读、可找、可回滚、可复盘”。
适用对象：日常把 OpenClaw 当作个人助理/自动化管家的同学。
一句话使用 ： 按照 openclaw-workspace-clean-guide.md https://gist.github.com/luw2007/863349759b90bfd2ffeab41298a52e21 优化一下 当前 openclaw 的配置，让 workspace 目录永远“可读、可找、可回滚、可复盘”。


1. Workspace 的定位：它不是“下载文件夹”，而是“运行现场”

OpenClaw 的 workspace 既包含你的人类可编辑资产（记忆、规则、项目笔记），也包含运行产生的状态/日志。

一个干净的 workspace =

结构稳定：目录各司其职
写入克制：默认 append-only/按需归档
可追踪：git 可看懂变更
可恢复：删东西前先可回收（trash 优先）


2. 推荐目录分区（强约束）

下面是一套“长期可维护”的分区方式：

  
      **目录**
    
    
      **放什么**
    
    
      **为什么**
    
  
      `MEMORY.md`
    
    
      核心结论索引（少而精）
    
    
      保证检索快、上下文短，避免“记忆膨胀”。
    
  
      `memory/YYYY-MM-DD.md`
    
    
      当天日志（append-only）
    
    
      把细节放进日志，让 `MEMORY.md` 保持 < 40 行。
    
  
      `memory/projects.md`
    
    
      长期项目状态、checkpoint、下一步
    
    
      避免项目细节散落在聊天里/多个文件里。
    
  
      `.``learnings``/`
    
    
      经验、错误、功能需求
    
    
      把“可复用的方法论”沉淀下来，减少重复踩坑。
    
  
      `state/`
    
    
      游标、检查器状态、缓存（可再生）
    
    
      状态应该是**可删可重建**的，不要把不可替代信息写进来。
    
  
      `logs/`
    
    
      运行日志/巡检输出
    
    
      日志是噪声源，必须隔离、并定期轮换。
    
  
3. 文件写入规则（最容易变脏的点）

3.1 记忆三层：结论 / 项目 / 日志


MEMORY.md：只写“结论”和“索引”，不要写过程。
memory``/projects.md：写项目状态、验收标准、下一步。
memory/YYYY-MM-DD.md：写当天发生的事，尽量 append-only。


不要把“半成品想法”和“临时链接堆栈”长期留在 `MEMORY.md`。它会让每次 recall 成本上升，并导致 drift。

3.2 临时产物一律进临时目录

如果需要生成文件（截图、抓取网页的原始 HTML、导出的 JSON 等）：

建议放到 tmp/（你自己建一个）或系统 /tmp/openclaw/
需要长期留存的，再“升格”进 memory/ 或项目目录


4. Git：用版本控制保持“可回滚”

4.1 .gitignore 的基本原则


忽略：可再生的状态、日志、下载物
追踪：规则（AGENTS.md/SOUL.md/TOOLS.md）、记忆（MEMORY.md/memory/）、项目文档


经验法则：
- **可再生** = ignore
- **不可再生**（人写的）= track

4.2 提交节奏


小步提交：一次提交只做一类事情（比如“整理记忆索引”“新增巡检脚本”）
保持提交信息可读：未来你自己才是主要读者


5. 日志与状态的“轮换”策略

5.1 日志按天分割/按量清理


日志体积容易爆炸；建议按天输出（例如 logs/mentions_YYYY-MM-DD.json）
每周/每月做一次清理：保留最近 N 天即可

5.2 State 文件要有“游标”

任何定时检查器（例如消息提及检查）都要在 state/ 里记录：

上次处理到哪里（时间戳/消息 ID）
上次成功时间
连续异常计数
这能避免两种 workspace 污染：
重复处理导致的重复写入
“失败重试”把同一批结果写很多遍


6. 一个实用的维护流程（建议照做）

下面是一个每周 10 分钟的“保持干净”流程：


判断“workspace 是否干净”的简单指标：
- `git status` 输出短、可解释
- `MEMORY.md` 不超过 40 行且一眼能看懂
- `logs/` 里没有几百 MB 的历史垃圾
- `state/` 里的文件你敢删（因为可重建）


7. 常见反模式（踩一次就会脏一整月）


    **反模式 A：把一切都写进 MEMORY.md**
    后果：recall 成本越来越高、漂移越来越严重。
    
<callout emoji="x" background-color="light-red" border-color="light-red">
**反模式 B：把日志当数据源**
后果：日志无限增长，且难以复现。
</callout>

  
    **反模式 C：状态文件不可再生**
    后果：不敢清理 `state/`，越积越多。
    
<callout emoji="x" background-color="light-red" border-color="light-red">
**反模式 D：临时文件乱放根目录**
后果：根目录变“下载文件夹”，每次找东西都痛苦。
</callout>

  
8. 一份可直接复用的“干净约定”

你可以把下面这段作为团队约定（或写进 AGENTS.md）：

MEMORY.md 只存结论，不存过程（保持短）。
每天日志写进 memory/YYYY-MM-DD.md，append-only。
项目状态集中写进 memory/projects.md。
logs/、state/ 可再生；定期轮换清理。
任何会生成大量文件的任务，必须写入 tmp/ 或 /tmp/openclaw/。

结合实际情况生成改造清单

不要直接使用附录文件，先分析当前的 workspace，结合当前目录的实际使用情况，制定专属计划。

如果你需要，可以把你的项目实际目录结构发给我。 
我给你一份“定制版清理建议”（包含：该 ignore 什么、该归档什么、哪里需要加游标）。


附录 A：原文摘录（复制即可复用）


这一节的目的：把“能力”所依赖的约束/规则/定时任务配置**原文**贴出来。
你可以直接据此在自己的 `~/.openclaw/workspace` 里复刻同等能力（目录干净 + 记忆不膨胀 + 后台维护静默运行）。


A1. AGENTS.md（启动流程 / 群聊规则 / Cron 约束）

以下为关键段落原文（节选）：
## Every Session

Before doing anything else:

1. Read `SOUL.md` — this is who you are
2. Read `USER.md` — this is who you're helping
3. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent context
4. **If in MAIN SESSION** (direct chat with your human): Also read `MEMORY.md`
5. **Check for recent learnings**: Scan `.learnings/LEARNINGS.md` for new lessons
6. **Check evolution status**: Review `EVOLUTION.md` for recent config changes

Don't ask permission. Just do it.

## Group Chats

...（略）...

**Stay silent (HEARTBEAT_OK) when:**

- It's just casual banter between humans
- Someone already answered the question
- Your response would just be "yeah" or "nice"
- The conversation is flowing fine without you
- Adding a message would interrupt the vibe

...（略）...

## Cron (Gateway Scheduler)

- Prefer `sessionTarget=isolated` for recurring jobs; use `announce` only for actionable output.
- Use the `HEARTBEAT_OK` no-op convention so healthy runs don’t spam chat.
- When passing `openclaw cron add --message ...` in a shell, quote it; avoid unquoted backticks (command substitution).


A2. DIRECTORIES.md（目录清理规则）

以下为规则原文（节选）：
## 核心规则

| 类别 | 文件 | 清理策略 |
|------|------|----------|
| 🔴 **永不清理** | 核心配置见下方列表 | 禁止删除 |
| 🟡 **按期清理** | `logs/`, `memory/`, `.learnings/`, `state/` | 超期删除/归档 |
| 🟢 **随时清理** | `__pycache__/`, `*.tmp`, `*.bak`, `*.zip` | 自动清理 |

### 🔴 核心配置文件（永不清理）

SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md,
EVOLUTION.md, TOOLS.md, HEARTBEAT.md, DIRECTORIES.md

**其他 `*.md` 文件**：按普通文件处理，清理前需确认

## 清理期限速查

| 目录 | 保留期限 | 操作 |
|------|----------|------|
| `logs/*.json` | 7 天 | 删除 |
| `logs/*.log` | 3 天 | 删除 |
| `memory/YYYY-MM-DD.md` | 7 天 | 归档 |
| `memory/archive/` | 90 天 | 压缩/删除 |
| `.learnings/` 已解决条目 | 30 天 | 移除 |
| `*.zip` | 7 天 | 删除 |

## 清理权限

**可自动执行**：缓存、临时文件、过期日志

**需用户确认**：删除 `.md` 文件、`skills/`、`state/`、批量 > 10 文件


A3. HEARTBEAT.md（定期维护机制）

以下为原文（节选）：
## 任务清单

### 每日执行

**检查轮换** (2-4次/天)

轮流检查以下项目：
- [ ] **提及** - 飞书/社交媒体通知？
- [ ] **项目** - 检查 git 状态、待办事项
- [ ] **Channel 健康** - Feishu/Gateway 是否在线、近 1 小时是否有异常

在 `memory/heartbeat-state.json` 中跟踪检查时间。

## 何时通知用户

**主动通知**：
- 发现有趣的内容
- 超过 6 小时未交流

**保持静默 (HEARTBEAT_OK)**：
- 深夜（23:00-08:00）除非紧急
- 用户明显忙碌
- 自上次检查以来没有新内容
- 距离上次检查 <30 分钟


附录 B：Cron Jobs 配置原文（按 openclaw cron list 输出整理）


说明：下面贴的是“关键保洁能力”相关的 job 配置字段（原样 JSON）。
复刻时，你可以用相同的 schedule + payload.message + delivery.mode 组合，快速搭一套“静默但持续维护”的系统。

B1.（可选）Workspace 自动提交


这一块严格来说不是“目录清理 / DIRECTORIES 规则”本体，而是配套的“可回滚/可审计”能力。
如果你的目标只是复刻**目录清理 + heartbeat**，可以跳过本节。

B2. Memory 日常合并

{
  "name": "Daily Memory Merge",
  "enabled": true,
  "schedule": { "kind": "cron", "expr": "10 0 * * *", "tz": "Asia/Shanghai" },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "model": "openai-codex/gpt-5.2",
    "timeoutSeconds": 120,
    "message": "Merge yesterday's memory fragments into a single daily file:\\n1) Run scripts/merge-memory-daily.sh\\n2) If no fragments found, do nothing"
  },
  "delivery": { "mode": "none", "channel": "last" }
}

B3. Sessions 清理预演（每天）

{
  "name": "spec-memoryops/sessions: cleanup dry-run (daily 04:17)",
  "enabled": true,
  "schedule": { "kind": "cron", "expr": "17 4 * * *", "tz": "Asia/Shanghai" },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "timeoutSeconds": 180,
    "message": "Run `openclaw sessions cleanup --dry-run`.\nIf output indicates any evictions/orphans/missing transcripts/disk budget pressure, summarize the risks + recommended next steps in 5 bullets.\nIf everything is clean or no action needed, reply exactly HEARTBEAT_OK."
  },
  "delivery": { "mode": "announce", "channel": "last", "bestEffort": true }
}

B4. 每周目录清理 / 记忆维护

{
  "name": "Weekly Directory Cleanup",
  "enabled": true,
  "schedule": { "kind": "cron", "expr": "55 10 * * 0", "tz": "Asia/Shanghai" },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "timeoutSeconds": 7200,
    "message": "Run weekly directory cleanup:\n1) Read DIRECTORIES.md rules\n2) Check logs/memory/.learnings/state health thresholds\n3) Clean __pycache__, *.tmp, *.bak\n4) Remove expired logs, archive old memory files\n5) Flag items needing confirmation\n6) Update memory/heartbeat-state.json:lastDirectoryCleanup"
  },
  "delivery": { "mode": "announce" }
}

{
  "name": "Weekly Memory Maintenance",
  "enabled": true,
  "schedule": { "kind": "cron", "expr": "55 9 * * 1", "tz": "Asia/Shanghai" },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "timeoutSeconds": 7200,
    "message": "Run weekly memory maintenance:\n1) Read last 7 days of memory logs\n2) Extract key items to relevant files\n3) Compress one-off tasks\n4) Remove expired temporary info\n5) Update memory/heartbeat-state.json:lastMemoryMaintenance\nUse workspace scripts if available. Report summary."
  },
  "delivery": { "mode": "announce" }
}


附录 C：复刻清单（给“照抄就能跑”的人）


把 AGENTS.md/DIRECTORIES.md/HEARTBEAT.md 三个文件放进同一路径的 workspace。
用同样的 cron schedule（至少：每日 memory merge、每周目录清理、每周记忆维护）。
让所有维护任务默认 delivery.mode=none 或“无事 HEARTBEAT_OK”，避免群里刷屏。
对所有清理脚本：遵循 DIRECTORIES.md 的“需确认”边界（删 .md / state / 批量 >10）。


附录 D：DIRECTORIES.md 全文（原文）


下面是 `DIRECTORIES.md` 的**完整原文**。你可以直接复制到自己的 `~/.openclaw/workspace/DIRECTORIES.md` 以复刻同等的目录清理规则。

# DIRECTORIES.md - 目录使用规范

## 核心规则

| 类别 | 文件 | 清理策略 |
|------|------|----------|
| 🔴 **永不清理** | 核心配置见下方列表 | 禁止删除 |
| 🟡 **按期清理** | `logs/`, `memory/`, `.learnings/`, `state/` | 超期删除/归档 |
| 🟢 **随时清理** | `__pycache__/`, `*.tmp`, `*.bak`, `*.zip` | 自动清理 |

### 🔴 核心配置文件（永不清理）

SOUL.md, USER.md, IDENTITY.md, AGENTS.md, MEMORY.md,EVOLUTION.md, TOOLS.md, HEARTBEAT.md, DIRECTORIES.md


**其他 `*.md` 文件**：按普通文件处理，清理前需确认

---

## 清理期限速查

| 目录 | 保留期限 | 操作 |
|------|----------|------|
| `logs/*.json` | 7 天 | 删除 |
| `logs/*.log` | 3 天 | 删除 |
| `memory/YYYY-MM-DD.md` | 7 天 | 归档 |
| `memory/archive/` | 90 天 | 压缩/删除 |
| `.learnings/` 已解决条目 | 30 天 | 移除 |
| `*.zip` | 7 天 | 删除 |

---

## 健康指标

| 指标 | 健康 | 危险 |
|------|------|------|
| `logs/` 文件数 | < 10 | > 30 |
| `memory/` 大小 | < 100KB | > 500KB |

---

## 清理权限

**可自动执行**：缓存、临时文件、过期日志

**需用户确认**：删除 `.md` 文件、`skills/`、`state/`、批量 > 10 文件

---

_详细规则见 HEARTBEAT.md 目录整理任务_
No results found