Openclaw Workspace

OpenClaw Workspace Skill

Overview

OpenClaw workspace files form the agent's "soul and memory" — they are injected into the system prompt on every turn (or on relevant turns), giving the agent its identity, behavioral rules, environmental knowledge, and long-term memory. Managing these files well is critical: bloat wastes tokens, redundancy creates confusion, and stale content leads to bad decisions.

Token budget: 20,000 chars per file, ~150,000 chars total across all bootstrap files.

File Inventory

Security rule: MEMORY.md must NEVER be loaded in group chats or sub-agent sessions — it contains private context that should not leak.

For full details on each file's design, anti-patterns, and section structure, see references/workspace-files.md.

Workspace Paths

Config key: agents.defaults.workspace or per-agent agents.list[].workspace.

Workflow: Audit Existing Workspace

Use when workspace files may be bloated, stale, or redundant.

1. Read all active files — AGENTS.md, SOUL.md, TOOLS.md, USER.md, IDENTITY.md, HEARTBEAT.md, BOOT.md, MEMORY.md 2. Check character counts:

   wc -c ~/.openclaw/workspace/AGENTS.md
   wc -c ~/.openclaw/workspace/SOUL.md
   wc -c ~/.openclaw/workspace/TOOLS.md
   wc -c ~/.openclaw/workspace/USER.md
   wc -c ~/.openclaw/workspace/IDENTITY.md
   wc -c ~/.openclaw/workspace/MEMORY.md
   # Or all at once:
   wc -c ~/.openclaw/workspace/*.md

3. Flag files over 10,000 chars — prime candidates for trimming or offloading to docs/ 4. Check for redundancy — same fact in SOUL.md and AGENTS.md? Same tool note in TOOLS.md and MEMORY.md? 5. Check for staleness — outdated SSH hosts, old tool names, deprecated rules, historical context that's no longer needed 6. Check MEMORY.md discipline — should contain curated facts, lessons learned, decisions, and critical rules — not raw session summaries or task-specific notes 7. Propose targeted edits — trim, move to docs/, or restructure

See references/optimization-guide.md for specific optimization strategies.

Workflow: Set Up New Workspace

Use when creating a workspace for a new agent from scratch.

File creation order (matters for boot sequence to work):

1. SOUL.md — persona and values first; everything else follows from identity 2. AGENTS.md — boot sequence, safety rules, checklist table 3. IDENTITY.md — name, emoji, avatar 4. USER.md — human profile and preferences (main agent only) 5. TOOLS.md — environment-specific notes (add as you discover env details) 6. MEMORY.md — start minimal; only truly universal iron laws 7. HEARTBEAT.md — periodic health checks (optional, add when needed) 8. BOOT.md — startup hooks (optional, only if hooks.internal.enabled = true) 9. BOOTSTRAP.md — first-run onboarding (optional; delete after first successful startup)

Minimal viable workspace: AGENTS.md + SOUL.md + TOOLS.md. Everything else is optional.

BOOTSTRAP.md note: If creating a BOOTSTRAP.md, include a self-deletion instruction at the end:

## Final Step
Delete this file: exec `rm ~/.openclaw/workspace/BOOTSTRAP.md`

Workflow: Memory Distillation

Use periodically (weekly or monthly) to keep MEMORY.md lean.

1. Read all recent daily logs: memory/YYYY-MM-DD.md files from the past period 2. Identify candidates for promotion to MEMORY.md:

• Rules violated more than once (recurring mistakes)
• Hard-won discoveries that aren't in skills docs
• Env-specific facts that should always be in context (not left to memory_search recall)

3. Check what's already in MEMORY.md — avoid duplicates 4. Draft additions — use iron-law format: concise, action-oriented, unambiguous 5. Archive old daily logs — move files older than 30 days to memory/archive/ or delete 6. Check MEMORY.md total size — keep under 10,000 chars; if larger, review for rules that are now stable enough to move to a skill's SKILL.md instead

Do NOT put in MEMORY.md:

• Long narratives or session summaries
• Things already covered in skill docs
• Anything specific to a single past task
• Episodic or task-specific memories (store those via memory_search/SQLite instead)

Workflow: Add or Update a Checklist

Use when adding a new high-risk operation type or updating an existing checklist.

1. Create or edit checklists/<operation-name>.md 2. Structure:

   # Checklist: <Operation Name>

   ## Pre-flight
   - [ ] Step 1
   - [ ] Step 2

   ## Execution
   - [ ] Step 3

   ## Verification
   - [ ] Confirm outcome
   - [ ] Log result in memory

3. Register in AGENTS.md — add a row to the checklists table:

   | <Operation description> | `checklists/<filename>.md` |

4. Keep checklists short — if a checklist exceeds ~50 lines, it's probably trying to be documentation; move narrative content to docs/ and keep only the actionable steps

Workflow: Update TOOLS.md

Use when adding a new tool, device, or environment capability.

TOOLS.md = environment-specific cheat sheet. It should contain:

• SSH hosts and common commands for this specific machine
• TTS provider, voice IDs, and any quirks
• Camera IDs or device names for this setup
• Node device IDs or names
• Any local aliases or shortcuts that aren't obvious

Do NOT put in TOOLS.md:

• General skill documentation (use skill SKILL.md files)
• Things that are the same across all environments
• Installation instructions (use docs/)

Format conventions:

# TOOLS.md - Local Notes

## SSH
- Main server: `ssh user@hostname`

## TTS
- Provider: Edge
- Voice: zh-CN-XiaoxiaoNeural

## Cameras
- Living room: node-id `abc123`, device `camera-0`

Common Issues

File exceeds token limit

Symptom: File is over 20,000 chars; OpenClaw may truncate it. Fix: Audit for content that belongs in docs/ (loaded on demand) instead of the bootstrap file. Move detailed references, historical context, and long examples out. Keep only what needs to be on every turn.

MEMORY.md leaking to groups

Symptom: Agent shares private context in group chats or Discord. Fix: Ensure MEMORY.md boot step in AGENTS.md is gated: "Main session only: Read MEMORY.md". Verify the agent's boot sequence explicitly checks session type before loading.

Boot sequence not loading files

Symptom: Agent doesn't know about content in SOUL.md, USER.md, or MEMORY.md at session start. Fix: Check that AGENTS.md boot sequence explicitly names each file to read. The agent won't auto-load files — it follows the boot sequence instructions in AGENTS.md. Verify hooks.internal.enabled = true in config if using BOOT.md.

MEMORY.md growing too large

Symptom: File approaches or exceeds 10,000 chars; reading it on every turn wastes significant context. Fix: Run memory distillation workflow. Move stable rules that have been incident-free for months into relevant skill SKILL.md files. Delete rules that are no longer relevant.

Workspace changes not taking effect

Symptom: Agent still uses old content after editing a workspace file. Fix: Workspace files are read at session start per the boot sequence. Restart the gateway or start a new session for changes to take effect.

Reference Files

openclaw-workspace

一个用于维护和优化 OpenClaw 工作区文件的 Claude Code 技能包。这些 Markdown 文件构成了 AI Agent 的"灵魂"、记忆系统与操作规程。

English →

---

这是什么？

OpenClaw 是一个自托管的多渠道 AI Agent 网关，支持 WhatsApp、Telegram、Discord、Slack 等平台。每个 OpenClaw Agent 都有一个工作区（workspace）——一个包含多个 Markdown 文件的目录，这些文件在每次对话轮次时被注入到系统提示词中，赋予 Agent 身份认同、行为规则、环境知识和长期记忆。

工作区文件功能强大，但需要精心管理：

• 内容过多 会在每次对话轮次中浪费大量 Token
• 文件间的重复内容 会导致混乱和自相矛盾
• 过时内容（旧的 SSH 主机、废弃的规则、已完成的任务）会悄无声息地降低 Agent 质量
• 缺少安全隔离 可能导致私密记忆泄露到群聊中

这个技能包让 Claude Code 具备正确审计、优化和构建 OpenClaw 工作区文件的能力。

---

工作区文件一览

Token 预算

安全规则

`MEMORY.md` 绝对不能在群聊或子 Agent 会话中加载。 它包含不应泄露的私密用户上下文。AGENTS.md 中的启动序列必须明确设置加载条件："仅主会话：读取 MEMORY.md"。

---

工作区目录结构

~/.openclaw/workspace/
├── AGENTS.md          # 操作手册——启动序列、规则、清单路由表
├── SOUL.md            # 人格、语气、价值观
├── TOOLS.md           # 环境专属信息：SSH 主机、TTS 声音、摄像头 ID
├── USER.md            # 用户画像（仅主会话）
├── IDENTITY.md        # 名称、Emoji、头像
├── HEARTBEAT.md       # 周期性任务指令
├── BOOT.md            # 启动钩子操作
├── BOOTSTRAP.md       # 首次初始化脚本（用完即删）
├── MEMORY.md          # 铁律规则（仅主会话）
├── memory/
│   ├── 2026-03-10.md  # 每日会话日志
│   └── archive/       # 归档的旧日志（超过 30 天）
├── checklists/
│   ├── deploy-agent.md
│   ├── gateway-restart.md
│   └── config-patch.md
└── docs/              # 按需文档（不会每次自动加载）
    ├── agent-rules-detail.md
    └── ssh-reference.md

---

各文件详解

AGENTS.md — 操作手册

这是每次会话中最先塑造 Agent 行为的文件（基础系统提示词之后）。它包含：

• 启动序列：有序列出需要在会话开始时读取的文件（SOUL → USER → MEMORY → 日志）
• 清单路由表：高风险操作 → 对应清单文件路径的映射
• 安全规则：哪些操作需要确认、哪些可以自主执行
• 群聊规则：在群聊中不应分享什么

注意：AGENTS.md 是规程文件，不是身份文件。人格和价值观属于 SOUL.md。

SOUL.md — 灵魂

用第二人称书写（"你不是一个聊天机器人，你正在成为某个人"），Agent 读取后将其内化为自我描述。

包含：核心价值观、边界与底线、语气风格、关于连续性的哲学（每次会话都是全新开始，工作区文件就是记忆）。

TOOLS.md — 本地环境备忘录

这是工作区中最容易被误用的文件。它应该是当前机器的环境专属速查表：SSH 主机、TTS 声音 ID、摄像头设备名称等。

子 Agent 也会收到此文件——这是它们唯一的环境知识来源。请保持简洁，50 行以内为佳。

USER.md — 用户画像

包含影响每次对话的人物相关事实：姓名、时区、语言偏好、沟通风格。

仅在主会话中加载——绝不在群聊或子 Agent 会话中加载。

MEMORY.md — 铁律规则

只保存"遗忘了就会出严重问题"的规则。每条规则要短且原子化，具有明确的行动指导意义。

定期精炼（每月一次）。已经几个月没有出过问题的规则，可以考虑迁移到技能的 SKILL.md 文件中（更合适的归宿）。

checklists/*.md — 操作清单

高风险操作（部署、网关重启、配置变更）的逐步指南。Agent 执行操作前主动读取对应清单。

正确模式：AGENTS.md 只保留一行路由表条目，完整清单放在 checklists/ 目录中（按需加载，不占用每轮 Token 预算）。

---

这个技能能做什么

安装后，Claude Code 将在以下五种主要工作流中调用此技能：

1. 审计现有工作区

读取所有工作区文件，检查字符数，识别冗余内容，发现过时条目，提出针对性的修改建议。

# 快速大小审计
wc -c ~/.openclaw/workspace/*.md

超过 10,000 字符的文件是修剪或将内容迁移到 docs/ 的首要候选。

2. 从零创建新工作区

按正确顺序创建工作区文件（SOUL → AGENTS → IDENTITY → USER → TOOLS → MEMORY → 可选文件），确保启动序列、安全隔离和清单路由表都正确配置。

最小可用工作区：AGENTS.md + SOUL.md + TOOLS.md。其余均为可选。

3. 记忆精炼

处理 memory/YYYY-MM-DD.md 每日日志，将其提炼进 MEMORY.md。将反复出现的错误和来之不易的规则提升为铁律格式，归档旧日志，并检查是否有已成熟的规则可以迁移到技能的 SKILL.md 中。

铁律格式：

N. **规则名称（分类）**：一句话规则。必要时在同一句中补充背景。

4. 添加或更新操作清单

为高风险操作创建 checklists/<操作>.md 文件，并在 AGENTS.md 清单路由表中注册。

清单结构：

# Checklist: <操作名称>

## 准备阶段
- [ ] 检查 X
- [ ] 验证 Y

## 执行阶段
- [ ] 执行 Z

## 验证阶段
- [ ] 确认结果
- [ ] 记录到记忆系统

5. 更新 TOOLS.md

添加新的环境专属条目（SSH 主机、TTS 声音、摄像头/设备 ID），清理过时条目。

---

如何安装

这是一个 Claude Code 技能。将其放入技能目录：

# 克隆到 Claude Code 技能目录
git clone https://github.com/win4r/openclaw-workspace ~/.claude/skills/openclaw-workspace

Claude Code 会自动检测并注册该技能，在技能列表中显示为：

openclaw-workspace — 维护或优化 OpenClaw 工作区文件时使用...

手动安装

将技能目录复制到 Claude Code 能识别的路径：

• ~/.claude/skills/openclaw-workspace/（推荐）
• 项目级：.claude/skills/openclaw-workspace/

---

如何使用

安装后，当你说以下内容时，Claude Code 会自动调用此技能：

• "检查我的 AGENTS.md 的 Token 效率"
• "帮我从零创建一个新的 OpenClaw 工作区"
• "把我的记忆日志精炼到 MEMORY.md 中"
• "为网关重启添加一个操作清单"
• "审计我的工作区文件是否有冗余"
• "我的 MEMORY.md 太大了，帮我清理一下"

也可以明确指定："使用 openclaw-workspace 技能来……"

---

Token 优化策略

什么时候把内容移到 docs/

docs/ 目录存放按需加载的内容，不会在每次轮次自动加载。这是降低每轮 Token 成本的主要手段。

应该移到 `docs/` 的内容：

• 只在特定操作类型时需要的内容（例如详细的渠道配置步骤）
• 叙述性说明而非规则或事实
• 特定过去任务的历史背景

应该保留在工作区文件中的内容：

• 影响每次轮次的内容（人格、安全规则、清单路由表）
• 在 Agent 收到任何消息之前就必须在上下文中的内容（启动序列文件）

冗余审计速查

文件大小阈值

---

常见问题

文件超出 Token 限制（> 20,000 字符）

将内容移到 docs/（按需加载，不是每次都加载）。只保留每次轮次都必须在上下文中的内容。

MEMORY.md 泄露到群聊

在 AGENTS.md 启动序列中添加明确的加载条件："2. 仅主会话：读取 MEMORY.md"。没有这个条件，Agent 可能会在任何上下文中加载它。

启动序列未加载文件

Agent 遵循 AGENTS.md 启动序列指令——它不会自动发现文件。确保每个文件都在启动序列中被明确命名。

工作区变更未生效

工作区文件在会话开始时读取。变更生效需要开始新会话或重启网关。

MEMORY.md 无限增长

每月执行一次记忆精炼。将成熟的规则迁移到技能 SKILL.md 文件中（针对工具特定规则的更合适归宿）。删除关于已完成任务的规则。

---

参考文件

---

相关资源

• OpenClaw — 本技能支持的网关
• openclaw 技能 — 网关操作、渠道配置、多 Agent 路由（独立技能包）

---

许可证

MIT

Buy Me a Coffee


My WeChat Group and My WeChat QR Code

<img src="https://github.com/win4r/AISuperDomain/assets/42172631/d6dcfd1a-60fa-4b6f-9d5e-1482150a7d95" width="186" height="300"> <img src="https://github.com/win4r/AISuperDomain/assets/42172631/7568cf78-c8ba-4182-aa96-d524d903f2bc" width="214.8" height="291"> <img src="https://github.com/win4r/AISuperDomain/assets/42172631/fefe535c-8153-4046-bfb4-e65eacbf7a33" width="207" height="281">

openclaw-workspace

A Claude Code skill for maintaining and optimizing OpenClaw workspace files — the markdown files that form an AI agent's soul, memory, and operating procedures.

中文文档 →

---

What is this?

OpenClaw is a self-hosted, multi-channel AI agent gateway (WhatsApp, Telegram, Discord, Slack, and more). Every OpenClaw agent has a workspace — a directory of markdown files that are injected into the system prompt on each turn, giving the agent its identity, behavioral rules, environmental knowledge, and long-term memory.

These workspace files are powerful but require careful management:

• Too much content wastes tokens on every single turn
• Redundancy between files creates confusion and contradictions
• Stale content (old SSH hosts, deprecated rules, finished tasks) silently degrades agent quality
• Missing security gates can leak private memory into group chats

This skill gives Claude Code the knowledge to audit, optimize, and build OpenClaw workspace files correctly.

---

Workspace Files Overview

Token Budget

Security Rule

`MEMORY.md` must NEVER be loaded in group chats or sub-agent sessions. It contains private user context that must not leak. The boot sequence in AGENTS.md must gate its loading explicitly: "Main session only: Read MEMORY.md".

---

Workspace Directory Structure

~/.openclaw/workspace/
├── AGENTS.md          # Operating manual — boot sequence, rules, checklists table
├── SOUL.md            # Persona, tone, values
├── TOOLS.md           # Env-specific: SSH hosts, TTS voices, camera IDs
├── USER.md            # Human profile (main sessions only)
├── IDENTITY.md        # Name, emoji, avatar
├── HEARTBEAT.md       # Periodic task instructions
├── BOOT.md            # Startup hook actions
├── BOOTSTRAP.md       # First-run onboarding (delete after use)
├── MEMORY.md          # Iron-law rules (main sessions only)
├── memory/
│   ├── 2026-03-10.md  # Daily session logs
│   └── archive/       # Old logs (> 30 days)
├── checklists/
│   ├── deploy-agent.md
│   ├── gateway-restart.md
│   └── config-patch.md
└── docs/              # On-demand docs (NOT auto-loaded every turn)
    ├── agent-rules-detail.md
    └── ssh-reference.md

---

What This Skill Does

When invoked, this skill guides Claude Code through five main workflows:

1. Audit Existing Workspace

Reads all workspace files, checks character counts, identifies bloat, spots redundancy between files, finds stale content, and proposes targeted edits.

# Quick size audit
wc -c ~/.openclaw/workspace/*.md

Files over 10,000 chars are prime candidates for trimming or moving content to docs/ (loaded on demand).

2. Set Up a New Workspace from Scratch

Creates workspace files in the correct order (SOUL → AGENTS → IDENTITY → USER → TOOLS → MEMORY → optional files). Ensures the boot sequence, security gates, and checklist table are all properly wired up.

Minimal viable workspace: AGENTS.md + SOUL.md + TOOLS.md. Everything else is optional.

3. Memory Distillation

Processes memory/YYYY-MM-DD.md daily logs into MEMORY.md. Promotes recurring mistakes and hard-won rules to iron-law format, archives old logs, and checks for rules that have matured enough to move to a skill's SKILL.md instead.

4. Add or Update Checklists

Creates checklists/<operation>.md files for high-risk operations (deploys, config changes, gateway restarts) and registers them in the AGENTS.md checklists routing table.

5. Update TOOLS.md

Adds new environment-specific entries (SSH hosts, TTS voices, camera/device IDs) and cleans out stale entries.

---

How to Install

This is a Claude Code skill. Place it in your skills directory:

# Clone into your Claude Code skills directory
git clone https://github.com/win4r/openclaw-workspace ~/.claude/skills/openclaw-workspace

Claude Code will automatically detect and register the skill. It will appear in the skill list as:

openclaw-workspace — Use when maintaining or optimizing OpenClaw workspace files...

Manual Installation

Copy the skill directory anywhere Claude Code looks for skills:

• ~/.claude/skills/openclaw-workspace/ (recommended)
• Per-project: .claude/skills/openclaw-workspace/

---

How to Use

Once installed, Claude Code will automatically invoke this skill when you:

• "Review my AGENTS.md for token efficiency"
• "Help me set up a new OpenClaw workspace"
• "Distill my memory logs into MEMORY.md"
• "Add a checklist for gateway restarts"
• "Audit my workspace files for redundancy"
• "My MEMORY.md is getting too large, help me clean it up"

You can also explicitly ask: "Use the openclaw-workspace skill to..."

---

Common Issues

File exceeds token limit (> 20,000 chars)

Move content to docs/ (loaded on demand, not every turn). Keep only what needs to be in context on every single turn.

MEMORY.md leaking to group chats

Add explicit gating in AGENTS.md boot sequence: "2. Main session only: Read MEMORY.md". Without this gate, the agent may load it in any context.

Boot sequence not loading files

The agent follows AGENTS.md boot sequence instructions — it won't auto-discover files. Make sure each file is explicitly named in the boot sequence.

Workspace changes not taking effect

Workspace files are read at session start. Start a new session or restart the gateway for changes to apply.

MEMORY.md growing unbounded

Run memory distillation monthly. Promote mature rules to skill SKILL.md files (more appropriate home for stable, tool-specific rules). Delete rules about completed tasks.

---

File Reference

---

Related

• OpenClaw — the gateway this skill supports
• openclaw skill — gateway operations, channel setup, multi-agent routing (separate skill)

---

License

MIT

Buy Me a Coffee


My WeChat Group and My WeChat QR Code

<img src="https://github.com/win4r/AISuperDomain/assets/42172631/d6dcfd1a-60fa-4b6f-9d5e-1482150a7d95" width="186" height="300"> <img src="https://github.com/win4r/AISuperDomain/assets/42172631/7568cf78-c8ba-4182-aa96-d524d903f2bc" width="214.8" height="291"> <img src="https://github.com/win4r/AISuperDomain/assets/42172631/fefe535c-8153-4046-bfb4-e65eacbf7a33" width="207" height="281">

Workspace Optimization Guide

Strategies for keeping workspace files lean, non-redundant, and within token budget.

Auditing File Sizes

Check character counts for all workspace files at once:

# All markdown files in workspace root
wc -c ~/.openclaw/workspace/*.md

# With human-readable totals (macOS)
ls -lh ~/.openclaw/workspace/*.md

# Check a specific workspace profile
wc -c ~/.openclaw/workspace-<profile>/*.md

Thresholds:

---

When to Move Content to docs/

The docs/ directory holds content that is referenced on demand — not loaded on every turn. Moving content there is the primary lever for reducing per-turn token cost.

Move to `docs/` when:

• Content is only needed for specific operation types (e.g., detailed channel configuration steps)
• Content is reference material that an agent looks up, not memorizes
• Content is long narrative explanation rather than rules or facts
• Content is specific to past tasks or historical context

Keep in workspace files when:

• Content affects every turn (persona, safety rules, checklist table)
• Content is short enough not to matter (< 200 chars)
• Content must be in context before the agent even receives a message (boot sequence files)

Examples:

• docs/agent-rules-detail.md — long explanations of group chat behavior, heartbeat policies
• docs/ssh-reference.md — full SSH setup guide (TOOLS.md keeps only the hostname)
• docs/channel-setup.md — channel configuration details (AGENTS.md just references it)

---

Checklist Pattern

Checklists are the canonical example of "reference on demand":

1. AGENTS.md holds only the routing table: | Deploy | checklists/deploy-agent.md | 2. The full checklist lives in checklists/deploy-agent.md 3. Agent reads the checklist file only when performing that operation

Wrong: Inline checklist steps in AGENTS.md (wastes tokens on every turn) Right: One-line table entry in AGENTS.md, full checklist in checklists/

---

Redundancy Audit

Common sources of redundancy to check:

---

Memory Distillation: Heartbeat vs Manual

官方推荐优先用 heartbeat 完成记忆精炼，而非纯手动触发。

在 Heartbeat 中自动精炼（推荐）

在 HEARTBEAT.md 里加入定期精炼任务：

## Memory Maintenance (every few days)
1. Read recent memory/YYYY-MM-DD.md files
2. Identify significant events, lessons, insights worth keeping long-term
3. Update MEMORY.md with distilled learnings
4. Remove outdated entries from MEMORY.md

配合 memory/heartbeat-state.json 记录上次精炼时间：

{
  "lastChecks": {
    "memoryDistillation": 1703275200,
    "email": 1703260800,
    "calendar": null
  }
}

手动精炼流程

Run this monthly (or when MEMORY.md exceeds 10,000 chars):

Step 1: Gather daily logs

ls ~/.openclaw/workspace/memory/ | sort

Read logs from the past 30 days. Look for:

• Rules the agent had to re-learn (same mistake appears multiple times)
• Hard-won environment facts that aren't in any skill doc
• Decisions that always get made the same way (good candidates for iron laws)

Step 2: Promote to MEMORY.md

For each candidate: 1. Check if the rule is already in MEMORY.md (avoid duplicates) 2. Check if the rule belongs in a skill SKILL.md instead (prefer skill docs for tool-specific rules) 3. Write in iron-law format: short, action-oriented, unambiguous

Iron law format:

N. **Rule name (category)**: One-sentence rule. Context if needed in same sentence.

Step 3: Archive old logs

# Archive logs older than 30 days
mkdir -p ~/.openclaw/workspace/memory/archive
find ~/.openclaw/workspace/memory -name "*.md" -mtime +30 -exec mv {} ~/.openclaw/workspace/memory/archive/ \;

Or simply delete them if they've been distilled:

find ~/.openclaw/workspace/memory -name "2025-*.md" -delete

Step 4: Review MEMORY.md for demotion

Check each rule in MEMORY.md:

• Has this rule been incident-free for 3+ months? Consider moving to a skill SKILL.md (more appropriate home)
• Is this rule covered by an existing skill doc now? Remove the duplicate
• Is this rule about a task that's now complete? Delete it

---

TOOLS.md Best Practices

TOOLS.md is loaded by sub-agents too — keep it tight.

Include:

## SSH
- main-server: ssh charles@192.168.1.10

## TTS
- Provider: Edge | Voice: zh-CN-XiaoxiaoNeural

## Cameras
- Living room: node node-home, device camera-0

Do not include:

• General SSH usage (sub-agents know SSH)
• TTS API docs (use skill docs)
• Configuration history ("used to be X, now Y")
• Anything over ~50 lines total

---

Checking Total Token Budget

Quick check of total bootstrap file size:

# Total size of all auto-loaded files
cat ~/.openclaw/workspace/AGENTS.md \
    ~/.openclaw/workspace/SOUL.md \
    ~/.openclaw/workspace/TOOLS.md \
    ~/.openclaw/workspace/USER.md \
    ~/.openclaw/workspace/IDENTITY.md \
    ~/.openclaw/workspace/MEMORY.md \
    2>/dev/null | wc -c

Target: Under 80,000 chars total for the regularly-loaded set. The 150,000 char budget includes HEARTBEAT.md and any other bootstrap files.

---

HEARTBEAT.md Optimization

两个官方推荐的配置优化：

1. 使用 `lightContext: true` 减少 token 消耗

在 openclaw.json 中为 heartbeat 开启精简模式：

{
  agents: {
    defaults: {
      heartbeat: {
        lightContext: true  // 最小化 bootstrap 注入
      }
    }
  }
}

2. OpenClaw 自动跳过空 HEARTBEAT.md

如果 HEARTBEAT.md 只包含空行和 Markdown 标题，OpenClaw 会自动跳过执行，节省 API 调用。所以保持文件简洁也有节省成本的效果。

---

Git 备份最佳实践

官方推荐用私有 Git 仓库备份工作区文件，方便跨机器迁移：

cd ~/.openclaw/workspace
git init
git remote add origin <your-private-repo>

应该提交的文件：

AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md
memory/YYYY-MM-DD.md
checklists/
docs/

绝对不要提交：

secrets、.env 文件、.key/.pem 文件、credentials/
任何包含 API key 或 token 的文件

迁移到新机器：

git clone <repo> ~/.openclaw/workspace
openclaw setup --workspace ~/.openclaw/workspace  # 补充缺失的模板文件

---

Quick Wins

When asked to optimize a workspace and time is short:

1. MEMORY.md audit — most frequent source of bloat; review each entry against the "curated essence" standard 2. Inline content in AGENTS.md — anything more than a one-liner that could be a docs/ reference 3. TOOLS.md cruft — SSH hosts that no longer exist, old device IDs, deprecated voice settings 4. USER.md staleness — preferences that changed, projects that ended, contacts that are no longer relevant 5. Checklist table vs inline steps — make sure AGENTS.md has the table, not the steps themselves 6. HEARTBEAT.md `lightContext` — enable in config if heartbeat token cost is high

Workspace Files Reference

Comprehensive reference for every OpenClaw workspace file — purpose, design principles, common anti-patterns, and section structure.

Token Budget

Files that exceed 20,000 chars will be truncated by OpenClaw. Files are read on every relevant turn, so token cost is multiplied by conversation length.

---

AGENTS.md

Purpose: The agent's operating manual — boot sequence, behavioral rules, checklists, safety constraints, and cross-cutting policies.

Loaded: Every turn, all agents (main and sub-agents).

Why it matters: This is the first file that shapes behavior after the base system prompt. A well-written AGENTS.md means the agent reliably follows the right procedures. A bloated one wastes tokens on every turn.

Required Sections

## Boot Sequence
Ordered list of files to read on session start.

## Memory
How to handle memory tools, daily logs, MEMORY.md.

## Checklists
Table: operation → checklist file path.

## Safety
What requires confirmation before acting.

## Groups
Behavior in group chats (what NOT to share).

## Heartbeats
How to use heartbeat turns productively.

## Tools
Where to find tool documentation.

Design Principles

• Boot sequence order is critical: SOUL → USER → MEMORY → daily logs. The agent builds up context in layers.
• The checklists table should list every high-risk operation type. If an operation isn't in the table, it won't be checked.
• Safety rules should be explicit: name the action type (delete, send, post, deploy) and the required behavior (ask, confirm, log).
• Keep behavioral rules minimal and action-oriented. Long prose explanations belong in docs/agent-rules-detail.md.

Anti-Patterns

• Duplicating content from SOUL.md (persona, values) — AGENTS.md is procedures, not identity
• Long narrative explanations — reference docs/ for details
• Listing tool documentation inline — use TOOLS.md and skill SKILL.md files
• Missing gating on MEMORY.md load: must say "Main session only"

---

SOUL.md

Purpose: The agent's persona, tone, values, and continuity philosophy. Answers "who are you and how do you show up?"

Loaded: Every turn, all agents.

Why it matters: Sets the agent's character consistently across all interactions. Without SOUL.md, agents feel generic and transactional.

Recommended Sections

## Core Truths
Fundamental behavioral principles (be genuine, have opinions, be resourceful).

## Boundaries
What the agent won't do or will always check before doing.

## Vibe
Tone and style guidance.

## Continuity
How the agent should think about session persistence and memory.

Design Principles

• Write in second person ("You're not a chatbot"). The agent reads this and internalizes it as self-description.
• Concise and evocative beats exhaustive. A few vivid principles are more effective than a long list.
• Continuity section matters: agents wake fresh each session and need to understand that workspace files are their memory.

Anti-Patterns

• Duplicating procedural rules from AGENTS.md — SOUL.md is identity, not operations
• Corporate HR policy tone — kills personality
• Contradiction with AGENTS.md safety rules — SOUL.md should reinforce, not conflict

---

TOOLS.md

Purpose: Environment-specific cheat sheet. Answers "what do I have access to on THIS machine?"

Loaded: On-demand reference; part of the standard bootstrap set received by all agents.

Why it matters: All agents (main and sub-agents) receive the standard bootstrap set: AGENTS.md, SOUL.md, USER.md, IDENTITY.md, TOOLS.md. TOOLS.md is the shared source of environment-specific knowledge (SSH hosts, camera IDs, TTS voices, device names).

Recommended Sections

## SSH
Hosts, common commands for this specific setup.

## TTS
Provider, voice ID, quirks.

## Cameras / Nodes
Device IDs or node names for this install.

## Misc
Any other env-specific notes.

Design Principles

• Environment-specific only. If it's the same on every install, it doesn't belong here.
• Keep it short. Sub-agents receive this file too — they shouldn't have to parse through 5,000 chars to find a camera ID.
• No installation instructions, no general tool documentation. Those go in docs/ or skill SKILL.md files.

Anti-Patterns

• Copying content from skill SKILL.md files (those are loaded on demand)
• General programming notes or language references
• Historical notes about past configurations that no longer apply

---

USER.md

Purpose: Human profile — who the agent is working with, their preferences, communication style, and relationship context.

Loaded: Every turn; part of the standard bootstrap set received by all agents.

Why it matters: Lets the agent personalize interactions without having to re-learn preferences from scratch each session.

Recommended Sections

## Identity
Name, timezone, primary language, role.

## Communication Preferences
Preferred response style, language(s), tone.

## Context
Key facts about the user's work, setup, or ongoing projects.

## Relationships
Family, colleagues, recurring contacts (if relevant).

Design Principles

• Include only facts that affect every conversation. Don't add things just because they're interesting.
• Update when preferences change — stale USER.md is worse than a minimal one.
• Sensitive personal information stays here, not in MEMORY.md (MEMORY.md has broader sub-agent loading risk).

Anti-Patterns

• Project-specific task notes (those go in daily memory logs or memory_search)
• Duplicating what's in IDENTITY.md or SOUL.md
• Sensitive private info that should never surface in any context (use MEMORY.md with its main-session-only gate instead)

---

IDENTITY.md

Purpose: The agent's name, avatar, emoji, and self-description for external presentation.

Loaded: Every turn.

Why it matters: Ensures consistent identity across channels (WhatsApp, Telegram, Discord) and avoids the agent expressing confusion about who it is.

Recommended Sections

## Name
Display name for messaging surfaces.

## Emoji / Avatar
Preferred emoji and avatar description.

## Self-Description
One-line summary of who the agent is (for introductions).

Design Principles

• Keep it very short — this file rarely needs more than 10–20 lines.
• Name and emoji should match what's configured in openclaw.json channels config.

Anti-Patterns

• Duplicating persona or values from SOUL.md
• Long biographical content — that belongs in SOUL.md

---

HEARTBEAT.md

Purpose: Instructions for what to do on periodic heartbeat turns — scheduled check-ins that happen even when no user message is received.

Loaded: On heartbeat turns (not every turn).

Why it matters: Lets the agent be productive between user messages — running health checks, processing queued items, monitoring systems, sending scheduled reports.

Recommended Sections

## Periodic Tasks
What to check or do on each heartbeat.

## Alerts
Conditions that should trigger an immediate notification.

## Health Checks
System/service health to verify.

Design Principles

• Each heartbeat task should have a clear termination condition — don't write open-ended instructions that lead to infinite loops.
• Alert conditions should be specific and actionable.
• Reference checklists for multi-step heartbeat tasks.

Anti-Patterns

• Instructions that always send a message (creates noise)
• Open-ended monitoring with no exit condition (causes loops)
• Duplicating daily task management from AGENTS.md

---

BOOT.md

Purpose: Actions to take on gateway startup — one-time initialization tasks, health checks, or first-turn behavior.

Loaded: On startup (requires hooks.internal.enabled = true in config).

Why it matters: Allows automated startup actions — checking service health, sending a "I'm online" notification, loading initial state.

Design Principles

• Keep startup actions fast and non-blocking.
• Health check failures should notify the user, not abort startup.
• Startup actions that require user confirmation should be skipped or logged, not blocked.

Anti-Patterns

• Long initialization sequences that delay first response
• Actions that modify config (use openclaw config set manually instead)
• Startup actions that duplicate what AGENTS.md boot sequence handles

---

BOOTSTRAP.md

Purpose: First-time onboarding script for new workspaces. Guides the agent through initial setup actions.

Loaded: New workspaces only (should be deleted after first successful run).

Why it matters: Allows complex first-time setup to be scripted — installing tools, running initial checks, setting up channels.

Design Principles

• Always end with a self-deletion step. BOOTSTRAP.md should instruct the agent to delete itself:

  ## Final Step
  This file's job is done. Delete it: exec `rm ~/.openclaw/workspace/BOOTSTRAP.md`

• Idempotent steps preferred — if bootstrap runs twice, it shouldn't break anything.

Anti-Patterns

• Forgetting to delete after use (BOOTSTRAP.md then wastes tokens on every turn forever)
• Putting ongoing operational rules here instead of AGENTS.md

---

MEMORY.md

Purpose: Long-term curated memory — significant events, decisions, opinions, lessons learned, and critical rules that must be in context every session.

Loaded: Main sessions only. NEVER in group chats or sub-agent sessions.

Why it matters: OpenClaw uses SQLite-based memory indexing (~/.openclaw/memory/<agentId>.sqlite) for episodic recall via memory_search. MEMORY.md complements this by holding the distilled essence that should always be in context — not just recallable on demand.

Design Principles

• Curated essence, not raw logs. Write significant events, thoughts, decisions, opinions, lessons learned. The daily logs are raw notes; MEMORY.md is the distilled wisdom.
• Short and atomic. Each entry should be one sentence to one short paragraph with clear implications.
• Security gating is mandatory. The boot sequence in AGENTS.md must gate MEMORY.md loading: "Main session only."
• Actively curate via heartbeat. Use periodic heartbeats to review daily logs and update MEMORY.md every few days. Remove outdated entries.

Anti-Patterns

• Raw session logs or conversation transcripts (those belong in daily logs)
• Rules that duplicate content in skill SKILL.md files
• Task-specific notes (use daily logs or memory_search)
• Loading in groups or sub-agents (NEVER)
• Growing indefinitely without periodic distillation

---

memory/YYYY-MM-DD.md (Daily Logs)

Purpose: Session-by-session logs for the current day — what was done, what was learned, what to remember.

Loaded: Per AGENTS.md boot sequence (agent reads yesterday's and today's logs on session start).

Why it matters: Provides short-term continuity — what was in-progress, what decisions were made today. Feeds the memory distillation process.

Design Principles

• Append-only during active sessions; summarize at end of day.
• Recommended: load today + yesterday in the boot sequence (gives short-term continuity without excessive token cost).
• Facts worth keeping long-term should be promoted to MEMORY.md or stored via memory_search (SQLite).
• Archive or delete logs older than 30 days.

---

checklists/*.md

Purpose: Step-by-step guides for high-risk operations. Loaded on demand, referenced from AGENTS.md checklists table.

Loaded: On demand (agent reads the specific file before performing the operation).

Why it matters: Prevents human error on irreversible operations (deploys, gateway restarts, config changes, external messages).

Structure Template

# Checklist: <Operation Name>

## Pre-flight
- [ ] Check X
- [ ] Verify Y

## Execution
- [ ] Do Z

## Verification
- [ ] Confirm outcome
- [ ] Log result

Design Principles

• Each checklist should be completable in one reading — no back-and-forth lookups needed.
• If a checklist exceeds ~50 lines, split it or move narrative context to docs/.
• Register every checklist in the AGENTS.md checklists table.

---

skills/ (Workspace-Local Skills)

Purpose: Workspace-specific skill overrides. If a skill here has the same name as a managed skill, the workspace version takes precedence.

Loaded: Dynamic, on name collision with managed skills.

Why it matters: Allows per-agent customization of skills without touching the global skills directory.

---

canvas/ (Canvas UI Files)

Purpose: Canvas UI files for Node display rendering (e.g., index.html).

Loaded: On demand by Node clients.

Why it matters: Enables custom visual interfaces displayed on connected nodes (iOS, Android, macOS app).