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