OpenClaw Workspace Directory Structure: Every File and Folder Explained

Ever stared at your ~/.openclaw/ directory and wondered what the heck all those files actually do? Yeah, me too. There’s this moment—usually about three AM when something breaks—where you realize you have no idea which config file controls what, and whether that mystery JSON is critical or just backup noise.

Let’s fix that right now.

I’m going to walk you through every single file and folder in your OpenClaw workspace. By the end, you’ll understand not just what lives where, but why it matters. Because understanding your agent’s directory structure is understanding your agent’s brain.

The Big Picture: ~/.openclaw/ at a Glance

When you first install OpenClaw, it creates a hidden directory in your home folder: ~/.openclaw/. This is ground zero—the absolute source of truth for everything your agent is, knows, and can do. Every skill it can run, every memory it carries, every preference you’ve set, every credential it needs to authenticate with external services—it all lives here.

This single directory is your agent’s entire “brain” and “body” combined. Think of it like the home directory for a person: documents, memories, tools, secrets, all in one place.

Here’s the structure:

~/.openclaw/
├── openclaw.json          # The master control file (master config)
├── workspace/             # Your agent's primary workspace (where it thinks)
├── skills/                # Global skill definitions (what it can do)
├── memory/                # Agent memory and conversation logs (what it remembers)
├── credentials/           # Encrypted auth tokens and API keys (secrets vault)
├── cache/                 # Temporary files and cached skill results (speed boosts)
└── backup/                # Automated backups (safety net)

Simple in structure, but powerful in implication. Each of these directories has a distinct purpose and lifecycle. Understanding the purpose is the difference between a healthy agent and a broken one. Understanding which files are safe to edit and which are auto-generated is the difference between productivity and disaster.

Let’s explore each one deeply, so you know exactly what you’re looking at and why.

openclaw.json: The Master Control File

This is your agent’s constitution. openclaw.json is the single source of truth for everything OpenClaw needs to know about your setup. It’s the first thing OpenClaw reads when it starts up, and it governs everything that happens afterward.

Think of it like the config file for an operating system—if this file is broken or corrupted, nothing works. If it’s properly configured, everything flows.

Here’s what a typical openclaw.json looks like:

{
  "version": "2.1.0",
  "agent_name": "YourAgentName",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "workspace_root": "~/.openclaw/workspace",
  "skills_dirs": [
    "~/.openclaw/workspace/skills",
    "~/.openclaw/skills",
    "./skills"
  ],
  "memory_dir": "~/.openclaw/memory",
  "credentials_dir": "~/.openclaw/credentials",
  "cache_dir": "~/.openclaw/cache",
  "backup_config": {
    "enabled": true,
    "destination": "~/.openclaw/backup",
    "interval_hours": 24,
    "retention_days": 30
  },
  "extensions": ["plugin-slack", "plugin-discord"],
  "log_level": "info",
  "api_endpoint": "https://api.openclaw.io",
  "timeout_seconds": 30,
  "max_memory_tokens": 8000,
  "cache_enabled": true,
  "auto_backup": true
}

Let’s break down each field:

Identity & Version:

• version: The OpenClaw version you’re running (e.g., “2.1.0”). This matters because different versions might have different config formats. If you upgrade OpenClaw and the version here changes, that’s a signal that something might have been auto-migrated.
• agent_name: Your agent’s human-readable name. “Claude-Research-Bot”, “MySecurityGuard”, whatever you call it. This is purely for your reference.
• agent_id: A unique UUID assigned to your agent. It’s permanent and persistent. This ID is how OpenClaw identifies your agent if you ever migrate it to another machine or back it up and restore it. Don’t modify this unless you really know what you’re doing—changing it breaks memory associations.

Directory Paths:

• workspace_root: The primary workspace directory. OpenClaw looks here for SOUL.md, AGENTS.md, and other core files. Usually ~/.openclaw/workspace, and you probably don’t need to change this.
• skills_dirs: An array of directories where OpenClaw searches for skills. Order matters here. OpenClaw searches them in the order listed. If it finds a skill named web-search in the first directory, it uses that one and ignores any other web-search in later directories. This is how you override bundled skills with your own custom versions.
• ~/.openclaw/workspace/skills — Workspace-specific skills (highest priority, custom to you)
• ~/.openclaw/skills — Global skills (shared across projects)
• ./skills — Project-local skills (if you’re in a specific project directory)
• memory_dir: Where all memory files live—daily logs, facts, learned patterns. Usually ~/.openclaw/memory.
• credentials_dir: The secure vault for encrypted API keys and tokens. Usually ~/.openclaw/credentials.
• cache_dir: Temporary storage for cached skill results and compiled code. Usually ~/.openclaw/cache. Safe to delete if it gets too large.

Backup Configuration:

The backup_config object controls automated backups:

• enabled: Whether automated backups are running (true/false)
• destination: Where backups are stored (~/.openclaw/backup by default)
• interval_hours: How often to back up (24 = daily). Lower = more frequent but more disk usage.
• retention_days: How long to keep backups (30 = keep the last month). Older backups are deleted automatically.

This is a safety net. If something goes catastrophically wrong, you can restore from a backup. We’ll talk more about this in the disaster recovery section.

Extensions & Features:

• extensions: Third-party plugins you’ve installed. Examples: plugin-slack, plugin-discord, plugin-google-workspace. Each extension extends OpenClaw’s capabilities.

• log_level: How verbose logging is. Options:

• error — Only errors

• warning — Errors and warnings
• info — Normal operation (default, recommended)
• debug — Very verbose, for troubleshooting
• trace — Extremely verbose, logs every function call

If something is broken and you can’t figure out why, temporarily set this to debug and check the logs. Then set it back to info because debug logs are enormous.

• api_endpoint: The OpenClaw API server. Usually https://api.openclaw.io. Don’t change this unless you know what you’re doing (like if you’re self-hosting a private instance).
• timeout_seconds: How long OpenClaw waits for a skill to complete before giving up. 30 seconds is default. If you’re doing slow operations (large model training, big API calls), you might increase this.

Optional Fields:

• max_memory_tokens: How many tokens of memory context to include in LLM prompts. Higher = more context but slower responses. Default is usually 4000-8000 depending on your model.
• cache_enabled: Whether caching is on (true/false). Improves speed but uses disk space.
• auto_backup: Whether automatic backups are enabled (different from the backup_config object above—this is a global toggle).

Which Fields Are Safe to Edit?

• Safe: agent_name, log_level, timeout_seconds, max_memory_tokens, cache_enabled
• Risky: skills_dirs (wrong order breaks skill loading), workspace_root (breaks everything if wrong)
• Dangerous: agent_id, version (don’t touch)

Pro tip: Use the CLI instead of hand-editing.

Don’t edit openclaw.json manually unless you’re comfortable with JSON syntax. One misplaced comma or missing quote breaks the entire file. Instead, use the CLI:

# Change log level
openclaw config set log_level debug

# Change timeout
openclaw config set timeout_seconds 60

# Add an extension
openclaw config add-extension plugin-google-workspace

These commands validate your changes before writing them to the file. Much safer than hand-editing.

The workspace/ Directory: Your Agent’s Primary Brain

Everything inside ~/.openclaw/workspace/ is your agent’s working directory. This is where the real action happens—where your agent thinks, learns, and responds.

If openclaw.json is the constitution, the workspace is the agent’s actual mind. This is where personality lives, where memories are stored, where subagents are defined, where conversations happen.

~/.openclaw/workspace/
├── SOUL.md                # Agent personality, values, purpose (SAFE TO EDIT)
├── AGENTS.md              # Subagent definitions (SAFE TO EDIT)
├── USER.md                # User profile and preferences (SAFE TO EDIT)
├── COMMANDS.md            # Custom command definitions (SAFE TO EDIT)
├── skills/                # Workspace-specific skills (SAFE TO EDIT)
├── state.json             # Current agent state (AUTO-GENERATED, DON'T EDIT)
├── conversation_log.jsonl # Full chat history (AUTO-GENERATED, DO NOT EDIT)
├── memory.md              # Long-term memory file (SAFE TO EDIT)
├── projects/              # Project files (optional, SAFE TO EDIT)
└── logs/                  # Daily conversation logs (AUTO-GENERATED)

The files marked “SAFE TO EDIT” are meant for you to customize. The ones marked “AUTO-GENERATED” are maintained by OpenClaw and editing them directly can cause corruption or inconsistency.

Golden rule: When in doubt, use the CLI commands or dashboard UI to modify things. Don’t hand-edit auto-generated files.

Let’s break down each file.

SOUL.md: What Makes Your Agent, Well, Your Agent

SOUL.md is the personality document. It defines how your agent thinks, its values, its communication style, and its core purpose.

When you create an agent, you write something like:

# Agent Soul

## Identity

Name: Claude-Research-Bot
Purpose: Deep research and fact-checking for technical articles

## Values

- Accuracy over speed
- Show evidence for every claim
- Admit unknowns openly
- No fake "done" language

## Communication Style

- Direct and conversational
- Use "we" and "you"
- Explain thinking out loud
- Link sources and evidence

Your agent reads this file every session. It’s how it knows who it is. If your agent suddenly starts acting weird, sometimes the issue is SOUL.md has drifted from reality. Keep it updated.

This file is absolutely safe to edit. In fact, you should edit it frequently as your needs change or as you discover what your agent should be doing.

AGENTS.md: Your Subagent Team

If SOUL.md is your agent’s personality, AGENTS.md is its organizational chart. This file defines all the subagents your agent can spawn.

# Subagents

## research-agent

- **Purpose**: Fact-checking and source validation
- **Model**: claude-haiku (fast and cheap)
- **Instructions**: Verify claims, find counter-evidence, document sources
- **Max Tokens**: 2000
- **Tools**: web-search, read-file, grep

## code-reviewer

- **Purpose**: Code review and quality assessment
- **Model**: claude-opus (better analysis)
- **Instructions**: Check for bugs, security, style guide compliance
- **Max Tokens**: 4000
- **Tools**: grep, read-file, bash

## copy-editor

- **Purpose**: Grammar and tone checking
- **Model**: claude-haiku
- **Instructions**: Check grammar, consistency, readability
- **Max Tokens**: 1500
- **Tools**: read-file

Each subagent has a clear purpose, assigned model, and tool access. This is how you scale—you can’t do everything yourself, so you delegate. Your primary agent spawns subagents for specific tasks, waits for results, and integrates the findings.

Safe to edit. Add new subagents, remove ones you don’t need, adjust their parameters.

USER.md: Who Are You?

USER.md stores user preferences and context about you.

# User Profile

## Basics

- Name: Your Name
- Timezone: America/New_York
- Preferred Model: claude-opus
- Language: en-US

## Work Preferences

- Writing Style: casual and technical
- Code Language: Python and JavaScript
- Focus Areas: AI, automation, productivity

## Communication

- Response Format: Explain thoroughly, show code
- Evidence Level: Always cite sources
- Tone: Friendly but professional

## Workspace Setup

- Project Directory: ~/projects/
- Output Directory: ~/articles/

Your agent reads this to understand you. It’s how it personalizes its responses. If you change jobs, update this. If your timezone changes, update this. Safe to edit frequently.

COMMANDS.md: Custom Commands

This file defines slash commands specific to your workspace.

# Custom Commands

## /research

Spawn research-agent to validate a claim
Usage: /research "claim to verify"
Returns: Fact-check report with sources

## /draft-article

Generate article outline and first draft
Usage: /draft-article "topic" "word_count"
Returns: Full outline + 25% draft

## /code-review

Submit code for review
Usage: /code-review path/to/file.py
Returns: Review report + improvement suggestions

These are shortcuts specific to your workflow. You can add as many as you want. Safe to edit.

skills/ Subdirectory

~/.openclaw/workspace/skills/ holds skills that are specific to your workspace—not globally available, but custom to how you work.

workspace/skills/
├── my-research-skill.md
├── article-generation.md
└── project-analysis.md

Each file is a SKILL.md with YAML frontmatter:

---
name: my-research-skill
version: 1.0.0
tags: [research, validation, sources]
dependencies: [web-search, grep]
---

# Skill: My Research Method

## Purpose
Validate claims using my specific research process

## Instructions
1. Search multiple sources
2. Cross-reference findings
3. Document all sources
4. Flag contradictions

Safe to edit and add new skills.

state.json: The Snapshot

state.json stores the current state of your agent. Don’t edit this manually—it’s auto-generated and constantly updated by OpenClaw.

{
  "agent_id": "...",
  "last_active": "2026-03-17T14:32:00Z",
  "current_model": "claude-opus",
  "active_subagents": [],
  "memory_tokens_used": 2450,
  "cache_hits": 127,
  "cache_misses": 34
}

This is read-only from a human perspective. OpenClaw updates it automatically. Touching this file can cause inconsistencies. Leave it alone.

conversation_log.jsonl: Your Chat History

This is a newline-delimited JSON file. Every message, every response, every interaction gets logged here.

{"timestamp":"2026-03-17T10:00:00Z","role":"user","content":"Research OpenClaw backup strategies"}
{"timestamp":"2026-03-17T10:00:05Z","role":"agent","content":"I'll search for..."}
{"timestamp":"2026-03-17T10:01:32Z","role":"agent","content":"Found 3 strategies..."}

This becomes useful for memory compression. When your agent needs historical context, it reads from this file. Do not edit this manually. It’s append-only and auto-generated. Editing it corrupts the log.

memory.md: Long-Term Memory

This is a markdown file where you can store things you want your agent to always remember. You edit this; it’s not auto-generated.

# Long-Term Memory

## User Preferences

- I prefer verbose explanations
- I like code examples
- I'm interested in AI and automation

## Key Facts

- I work for TechCorp
- I'm writing a book on Python automation
- My timezone is Pacific Time

## Important Instructions

- Always cite sources
- Never make up data
- Flag uncertainties clearly

This file is included in every prompt to your agent, so it shapes behavior. Edit freely.

projects/ Subdirectory

If you organize work into projects, this is where project-specific files live. Optional, but useful for organization.

workspace/projects/
├── project-alpha/
│   ├── brief.md
│   ├── status.md
│   └── outputs/
└── project-beta/
    ├── brief.md
    └── research/

Totally up to you how to organize this. Safe to edit and reorganize as needed.

The skills/ Directory: Your Agent’s Toolbox

~/.openclaw/skills/ is where global skills live—reusable across all your agents and workspaces.

~/.openclaw/skills/
├── web-search/
│   └── SKILL.md
├── code-analysis/
│   ├── SKILL.md
│   └── helpers.py
├── document-writing/
│   ├── SKILL.md
│   └── templates/
└── database-query/
    ├── SKILL.md
    └── config.json

Each skill is its own directory with a SKILL.md file defining it.

When OpenClaw loads skills, it searches in this order:

1. ~/.openclaw/workspace/skills/ (workspace-specific, highest priority)
2. ~/.openclaw/skills/ (global, medium priority)
3. Default bundled skills (lowest priority)

So if you have a skill in your workspace directory with the same name as a global skill, the workspace version wins. This is how you override defaults.

Skill File Structure

Each skill directory typically has:

• SKILL.md: The main definition
• helpers.py/js/etc: Supporting code
• config.json: Configuration if needed
• README.md: Documentation

The SKILL.md starts with YAML frontmatter:

---
name: web-search
version: 2.1.0
tags: [search, research, validation]
dependencies: []
api_required: true
cache_enabled: true
---

# Skill: Web Search

## Purpose
Search the web and return relevant results

## Inputs
- query: string (required)
- num_results: integer (default: 10)

## Outputs
- results: array of search results
- total_results: integer
- search_time_ms: integer

## Usage Example
```javascript
const skill = await openclaw.skill('web-search');
const results = await skill.execute({
  query: 'OpenClaw memory management',
  num_results: 20
});

Rate Limiting

• 100 queries per hour
• 10,000 per day
• Cached results don’t count against limit

## The memory/ Directory: Your Agent's Long-Term Memory

`~/.openclaw/memory/` is where memory lives—not short-term conversation history, but structured long-term knowledge.

~/.openclaw/memory/
├── daily/
│ ├── 2026-03-17.jsonl
│ ├── 2026-03-16.jsonl
│ └── 2026-03-15.jsonl
├── facts/
│ └── facts-registry.jsonl
├── learned/
│ └── learned-patterns.jsonl
├── users/
│ └── [user-id].jsonl
└── index.json

### daily/ Subdirectory: Daily Logs

Every day gets a log file with what your agent learned that day.

```json
{"timestamp":"2026-03-17T08:30:00Z","type":"fact","content":"OpenClaw workspace config loaded from ~/.openclaw/openclaw.json"}
{"timestamp":"2026-03-17T09:15:00Z","type":"skill_used","content":"web-search used 3 times today"}
{"timestamp":"2026-03-17T10:42:00Z","type":"learned","content":"User prefers casual tone with evidence"}

Daily logs rotate automatically. After 30 days (configurable), they’re compressed and archived. Auto-generated. Don’t edit.

facts/: Fact Registry

Structured facts your agent has learned. Useful for avoiding redundant research.

{"id":"fact-1","claim":"OpenClaw uses ~/.openclaw/ as root","verified":true,"sources":["official-docs"],"date":"2026-03-17"}
{"id":"fact-2","claim":"Skills load in priority order","verified":true,"sources":["openclaw.json-spec"],"date":"2026-03-16"}

Auto-generated. Don’t edit manually.

learned/: Pattern Recognition

Patterns your agent has noticed about your workflow.

{"pattern":"user-asks-research","frequency":0.45,"triggered_subagent":"research-agent","success_rate":0.92,"date":"2026-03-17"}
{"pattern":"code-review-requests","frequency":0.15,"optimal_model":"claude-opus","date":"2026-03-17"}

Auto-generated. Don’t touch.

users/: User-Specific Memory

Per-user memory if your agent serves multiple users.

{"user_id":"user-123","preference":"technical_depth","value":"deep","date":"2026-03-17"}
{"user_id":"user-123","learned_behavior":"prefers_evidence","confidence":0.87,"date":"2026-03-16"}

Auto-generated per user. Don’t edit.

index.json: Memory Index

Fast lookup for memory queries.

{
  "facts_count": 127,
  "daily_logs_count": 30,
  "patterns_count": 45,
  "last_compressed": "2026-03-10T00:00:00Z",
  "total_size_mb": 2.3
}

Auto-generated. Read-only.

The credentials/ Directory: Your Secrets Vault

~/.openclaw/credentials/ stores encrypted authentication tokens and API keys.

~/.openclaw/credentials/
├── openai.enc
├── anthropic.enc
├── github.enc
├── database.enc
└── custom-api.enc

Each file is encrypted using your machine’s secure credential store (macOS Keychain, Windows Credential Manager, or Linux Secret Service).

Never store credentials in plain text. OpenClaw encrypts them automatically when you run:

openclaw credentials add openai sk-...

To use a credential:

openclaw credentials get openai

Do not edit these files directly. Use the CLI.

The cache/ Directory: Speed Boosts

~/.openclaw/cache/ holds temporary files and cached skill results.

~/.openclaw/cache/
├── skill-results/
│   └── web-search-2026-03-17-cache.jsonl
├── compiled-skills/
│   └── skill-web-search-v2.1.0.compiled.js
└── temp/
    └── upload-12345.tmp

This directory can get large. You can safely delete it—everything will be regenerated. But if you want performance, keep it around. Cache hits are fast.

Auto-generated. Safe to delete if needed, but you’ll lose the speed boost temporarily.

The backup/ Directory: Your Safety Net

If backup is enabled in openclaw.json, this is where automated backups live.

~/.openclaw/backup/
├── 2026-03-17_backup.tar.gz
├── 2026-03-16_backup.tar.gz
├── 2026-03-15_backup.tar.gz
├── manifest.json
└── restore-instructions.md

Each backup is a compressed archive containing:

• Complete workspace/ directory
• Memory files
• Skills
• A manifest listing what’s included

We’ll cover disaster recovery in depth in the next article, but know this: if something goes catastrophically wrong, you can restore from here.

Auto-generated. Don’t delete these unless you’re explicitly trying to free up disk space and accept the risk of losing rollback capability.

Loading Order and Priority

Here’s the critical thing to understand: OpenClaw searches for resources in a specific order.

Skills Loading Order

1. Workspace-specific skills (~/.openclaw/workspace/skills/)
2. Global skills (~/.openclaw/skills/)
3. Bundled default skills
4. ClawHub marketplace (if configured)

This means you can override any global skill by creating a workspace version with the same name.

Configuration Loading Order

1. openclaw.json (master config)
2. Environment variables (overrides)
3. Workspace config (if exists)
4. CLI flags (highest priority)

Memory Search Order

1. Current conversation context
2. Daily logs (recent first)
3. Learned patterns
4. Facts registry
5. Historical archives (if enabled)

Understanding these priorities is crucial. If your agent isn’t using the skill you expect, it’s probably because a higher-priority one is shadowing it.

File Corruption and Recovery

What if a file gets corrupted? This happens more often than you’d think—power loss, aggressive text editors, accidental overwrites, sync conflicts from cloud storage. Here’s your action plan for each type.

For workspace files (SOUL.md, AGENTS.md, USER.md, COMMANDS.md):

These are human-edited files. If you accidentally break markdown formatting or YAML frontmatter, OpenClaw might struggle to parse them.

Symptoms: The dashboard works, but your agent ignores your SOUL.md settings, subagents don’t spawn, custom commands don’t exist.

Recovery:

# Validate the file syntax
openclaw validate workspace/SOUL.md

# If it fails, restore from backup
openclaw restore --backup latest --component workspace

# Or manually restore from backup
tar -xzf ~/.openclaw/backup/2026-03-17_backup.tar.gz -C ~/.openclaw/

For auto-generated files (state.json, conversation_log.jsonl):

These are created and updated by OpenClaw. You shouldn’t edit them, but if they get corrupted (usually during a crash while writing), they can cause problems.

Symptoms: OpenClaw crashes on startup, says “state file is invalid”, or conversation history stops appearing.

Recovery:

# These will be regenerated on next startup
rm ~/.openclaw/workspace/state.json
rm ~/.openclaw/workspace/conversation_log.jsonl

# Restart the service
docker restart openclaw  # if using Docker
# OR
openclaw restart  # if using native installation

You’ll lose recent conversation history, but the agent will function normally. It’s a reasonable trade-off—better to lose history than be unable to start.

For the master config file (openclaw.json):

If this file is malformed, OpenClaw won’t start at all. This is the most critical file in the entire directory structure.

Symptoms: docker logs openclaw shows “Failed to parse openclaw.json” or OpenClaw fails immediately on start. You get JSON parsing errors.

Recovery:

# First attempt: restore from backup
openclaw restore --backup latest --component config

# If backup fails, try auto-repair
openclaw config validate
openclaw config repair

# Last resort: rebuild from defaults (preserves agent identity)
openclaw config reset --keep-agent-id

The --keep-agent-id flag is important—it rebuilds the config but keeps your agent’s unique ID, preserving memory associations and identity.

For credentials vault:

Credentials are encrypted by design, so corruption is rare. If they stop working:

Symptoms: Authentication errors when trying to use external services, API calls fail with “credential not found” or “invalid credential”.

Recovery:

# Check what's stored
openclaw credentials list

# If one is broken, remove and re-add it
openclaw credentials remove openai
openclaw credentials add openai sk-new-key-here

# If everything is broken, start fresh
openclaw credentials remove all
# Then add them back one by one
openclaw credentials add openai sk-...
openclaw credentials add github ghp-...
openclaw credentials add slack xoxb-...

For memory files (daily logs, facts, learned patterns):

The memory directory is huge and filled with auto-generated JSONL files. Corruption here is usually not catastrophic—memory is long-term but not critical for operation.

Symptoms: Agent references facts that are clearly wrong or out of date, learned patterns seem reversed or nonsensical.

Recovery:

# Compress and archive old memory (clears corrupted entries)
openclaw memory compress --older-than 7  # Keep only last 7 days

# Or rebuild from scratch (loses learned patterns but keeps facts)
openclaw memory rebuild

# Or just delete the memory directory (dangerous, loses everything)
rm -rf ~/.openclaw/memory
# It will be regenerated on next startup with fresh logs

For workspace skill files:

Workspace-specific skills (the ones you wrote) can be corrupted if you edit them incorrectly.

Symptoms: openclaw skill validate my-skill fails, or a specific skill never loads or responds.

Recovery:

# Validate individual skill
openclaw skill validate my-skill

# If the YAML frontmatter is broken, fix it manually in your editor
# If the logic is broken, restore from backup or rewrite it

# Validate all skills at once
openclaw skill validate-all

# Rebuild skill cache if skills won't load
openclaw skill compile-all

For bundled/global skill files:

The global skill directory (~/.openclaw/skills/) contains read-only bundled skills. Corruption here indicates a serious system problem, not user error.

Symptoms: Multiple skills fail to load, core functionality breaks.

Recovery:

# Reset all bundled skills to defaults
openclaw skills reset-defaults

# If that doesn't work, your OpenClaw installation might be corrupted
# Reinstall: docker pull openclaw/openclaw:latest

Maintenance Tips

A healthy workspace requires periodic attention. These are the tasks to keep everything running smoothly and prevent problems before they start.

Weekly maintenance (5 minutes):

# Check if backups are running
ls -lah ~/.openclaw/backup/ | head -3
# You should see recent backup files (newer than 24 hours)

# Quick health check
openclaw config validate
# Should output "Configuration is valid"

Monthly maintenance (15 minutes):

# Full integrity check
openclaw config validate
openclaw skill validate-all
openclaw memory validate

# Clean up temporary cache (safe to delete)
rm -rf ~/.openclaw/cache/temp/*

# Check disk usage (watch for growth)
du -sh ~/.openclaw/
du -sh ~/.openclaw/workspace/logs/
du -sh ~/.openclaw/cache/
# Compare to previous months to spot trends

Quarterly maintenance (30 minutes):

# Compress old memory (saves space, keeps facts)
openclaw memory compress --older-than 90
# Compresses daily logs older than 90 days into monthly archives

# Archive old conversation logs
find ~/.openclaw/workspace/logs/ -type f -mtime +90 -exec gzip {} \;

# Verify all backups are valid and recent
openclaw backup list
openclaw backup verify --backup latest

# Check memory size and stats
openclaw memory stats
# Shows: facts count, daily logs, patterns, archive size

Semi-annual maintenance (1 hour, ideally during downtime):

# Full validation pass on everything
openclaw config validate
openclaw skill validate-all
openclaw memory validate
openclaw backup verify --all

# Rebuild caches (safe, gets regenerated anyway)
rm -rf ~/.openclaw/cache/*

# Clean up old backups (keep last 3 months)
openclaw backup cleanup --retain-days 90

# Check for orphaned files (files not belonging to any system)
openclaw workspace audit

# Compact memory (combines daily logs into monthly archives)
openclaw memory compact

Annually (maintenance window, 2-3 hours):

# Full system backup before major maintenance
tar -czf ~/my-backups/openclaw-pre-maintenance.tar.gz ~/.openclaw/

# Archive very old logs to external storage
find ~/.openclaw/workspace/logs/ -type f -mtime +365 -exec gzip {} \;
tar -czf ~/my-backups/openclaw-logs-archive-2025.tar.gz ~/.openclaw/workspace/logs/*.gz

# Delete archived logs to save space (optional)
find ~/.openclaw/workspace/logs/ -type f -name "*.gz" -mtime +30 -delete

# Reset learned patterns (optional, if they seem to have drifted)
openclaw memory reset-patterns
# This keeps facts but clears learned behavior patterns
# Useful if the agent has picked up bad habits over time

# Update all skills to latest versions
openclaw skill update-all

# Full restart to verify everything still works
docker restart openclaw  # or: openclaw restart
sleep 10
openclaw status  # verify it's running

Understanding File Interactions

Files don’t exist in isolation. They interact and depend on each other. Understanding these relationships helps you troubleshoot when things go wrong.

Configuration Loading Sequence:

When OpenClaw starts, it reads files in this order:

1. openclaw.json is loaded first (master config)
2. Environment variables override openclaw.json settings
3. ~/.openclaw/workspace/SOUL.md is read (personality definition)
4. ~/.openclaw/workspace/USER.md is read (user context)
5. Skills are loaded in priority order
6. Memory is initialized from ~/.openclaw/memory/
7. Credentials are decrypted from ~/.openclaw/credentials/
8. Previous state.json is loaded to resume from last state

If any step fails, the agent won’t start properly. That’s why the order matters.

Skill Resolution When Multiple Versions Exist:

If you have web-search in both workspace skills and global skills:

1. OpenClaw checks ~/.openclaw/workspace/skills/web-search/
2. If found and valid, it uses that version
3. If not found or invalid, it checks ~/.openclaw/skills/web-search/
4. If not found there, it uses the bundled default

The first valid match wins. This is intentional—it lets you override defaults.

Memory Reading Sequence for Context:

When the agent needs to recall something, it searches in this order:

1. Current conversation (last N messages in this chat)
2. Today’s log file (~/.openclaw/memory/daily/today.jsonl)
3. Recent daily logs (last 30 days, reverse chronological)
4. Facts registry (~/.openclaw/memory/facts/)
5. Learned patterns (~/.openclaw/memory/learned/)
6. Archived memories (older than 30 days)

Early matches take priority. This is why recent conversations shadow older facts—recency matters for context.

Backup and Restore Sequence:

When you restore from a backup:

backup.tar.gz
├── workspace/         → completely replaces ~/.openclaw/workspace/
├── skills/           → completely replaces ~/.openclaw/skills/
├── memory/           → completely replaces ~/.openclaw/memory/
├── credentials/      → completely replaces ~/.openclaw/credentials/
└── manifest.json     → documents what was included

The restore is all-or-nothing for each component. You can restore specific components without affecting others.

Safe to Edit vs. Auto-Generated: Quick Reference

Confused about which files you can safely edit? Here’s a quick lookup table:

File/Directory	Safe to Edit?	Notes
openclaw.json	⚠️ Risky	Use CLI instead: openclaw config set ...
SOUL.md	✅ Safe	This is meant for you to customize
AGENTS.md	✅ Safe	Define and redefine subagents freely
USER.md	✅ Safe	Update as your preferences change
COMMANDS.md	✅ Safe	Add/remove custom commands
memory.md	✅ Safe	Store facts you want remembered
state.json	❌ Never	Auto-generated, don’t touch
conversation_log.jsonl	❌ Never	Append-only, don’t edit
skills/ (workspace)	✅ Safe	Custom skills are for you
skills/ (global)	❌ Never	Bundled skills are read-only
memory/daily/	❌ Never	Auto-generated daily logs
memory/facts/	❌ Never	Learned facts, don’t touch
memory/learned/	❌ Never	Discovered patterns, don’t touch
credentials/	⚠️ Risky	Use CLI: openclaw credentials add ...
cache/	✅ Safe	Can delete to save space
backup/	✅ Safe	Can delete old backups

Golden rule: If it’s auto-generated, don’t edit it directly. Use the CLI or dashboard UI instead.

Common Beginner Mistakes When Working With Workspace Files

You’re going to make one of these. Everyone does. Here’s how to recognize and fix them.

Mistake 1: Editing SOUL.md with the wrong format

The problem: You open SOUL.md in your editor and start editing. You remove indentation, break the markdown structure, or accidentally delete important sections. The agent starts ignoring your personality settings.

Why it happened: You weren’t careful about preserving the markdown format. SOUL.md needs to be valid markdown for OpenClaw to parse it correctly.

How to fix it:

# Validate the syntax
openclaw validate workspace/SOUL.md

# If invalid, restore from backup
openclaw restore --backup latest --component workspace

# Or rewrite it carefully, preserving the structure:
# - Use proper markdown headings (# ## ###)
# - Use bullet points (-) consistently
# - Don't mix tabs and spaces

Mistake 2: Putting secrets in SOUL.md or COMMANDS.md

The problem: You write something like:

# Commands

/slack - Connect to Slack with token xoxb-123456789

Now your API key is sitting in a plain-text file. If you ever back up this directory or sync it to cloud storage, the secret is exposed.

How to fix it:

# Commands

/slack - Connect to Slack

# Token should be stored via: openclaw credentials add slack [token]

Always use the credentials vault (openclaw credentials add), not plain text.

Mistake 3: Modifying state.json manually

The problem: You open state.json, see it says last_active: 2026-03-10, and think “I should update this to today”. You change it manually. Now OpenClaw’s internal state is out of sync with reality, and it crashes or behaves strangely.

Why it’s bad: state.json is a snapshot that OpenClaw writes constantly. Manually editing it means your changes will be overwritten on the next save, or worse, cause corruption.

How to fix it:

Don’t edit state.json. Ever. If you think it’s wrong, delete it and let OpenClaw regenerate it:

rm ~/.openclaw/workspace/state.json
docker restart openclaw  # or: openclaw restart

Mistake 4: Accidentally deleting conversation_log.jsonl

The problem: You’re trying to clean up old files, and you delete conversation_log.jsonl thinking it’s just a log that can be regenerated. But this file is critical—it’s the permanent record of all conversations, and OpenClaw uses it for memory compression.

How to fix it:

Don’t delete it. Ever. If you must clean up disk space, archive it to external storage:

# Safe approach: backup to external storage, then delete
tar -czf ~/backup-conversations-2026-03.tar.gz ~/.openclaw/workspace/conversation_log.jsonl
rm ~/.openclaw/workspace/conversation_log.jsonl

# Or just leave it. Conversation logs are rarely huge (maybe 100MB per year).
# Not worth the risk of deletion.

Mistake 5: Overriding a global skill without understanding priority order

The problem: You copy the built-in web-search skill into your workspace skills directory, intending to customize it. But you introduce a bug. Now web-search is broken everywhere because your buggy version takes priority over the global one.

How to fix it:

Before overriding, understand that you’re taking responsibility for that skill. Test thoroughly:

# Validate your custom version
openclaw skill validate web-search

# Test it
openclaw skill run web-search --query "test query"

# If there are issues, either:
# 1. Fix your version
# 2. Delete it and use the global version
rm ~/.openclaw/workspace/skills/web-search
openclaw skill reload web-search

Mistake 6: Mixing tabs and spaces in AGENTS.md or COMMANDS.md

The problem: You edit AGENTS.md in an editor that uses tabs, but OpenClaw expects spaces (or vice versa). The YAML parser gets confused and refuses to read the file.

Why it’s bad: Your agent can’t load subagents. Entire workflows fail.

How to fix it:

Configure your editor to use consistent indentation (usually 2 spaces for YAML):

# On macOS/Linux, check for mixed indentation
grep -P '\t' ~/.openclaw/workspace/AGENTS.md
# If output shows tabs, the file has them

# Convert tabs to spaces
sed -i 's/\t/  /g' ~/.openclaw/workspace/AGENTS.md

# Or restore from backup and be more careful next time
openclaw restore --backup latest --component workspace

Mistake 7: Forgetting to save changes

The problem: You edit SOUL.md in your editor, make important changes, but forget to save. You restart OpenClaw expecting the changes to take effect. They don’t, and you’re confused.

How to prevent it:

Enable auto-save in your editor. Or just be deliberate:

# After editing any file, verify it was saved
cat ~/.openclaw/workspace/SOUL.md | head -20
# Look for your changes

How the Directory Structure Shapes Your Workflow

There’s something subtle that happens once you understand this directory structure: your workflow becomes more intentional. You stop treating OpenClaw as a black box and start seeing it as a system you can reason about. When something isn’t working the way you expected, you know exactly which file to look at. When you want to teach your agent something new, you know where to put that knowledge.

Think about how this would work in practice. Let’s say you notice your agent is giving you responses that are too technical, but you want more accessible explanations. You know that gets fixed in SOUL.md—you update the communication style section, save the file, and restart. That’s it. No mystical configuration dashboards. No confusing menus. Just plain text files that define how your agent behaves.

Or imagine you’ve built a custom research skill that works great, and you want to use it in multiple projects. You know to put that in ~/.openclaw/skills/ instead of your workspace skills directory. Now all your agents can access it. You’ve just implemented code reuse, and you understand exactly how the system found your skill because you know the skill loading order.

This kind of transparency is rare in modern tools. Most “intelligent” systems hide their internals behind GUIs and APIs. You get it right, or you get frustrated. But OpenClaw trusts you to understand the machine. That trust is empowering, and it’s why understanding this directory structure matters so much.

Scaling from One Agent to Many

Here’s a forward-looking consideration: this directory structure scales gracefully. If you start with a single agent and later decide you want to manage multiple agents (one for research, one for coding, one for content creation), the model doesn’t break. You might create separate workspace directories for each, or use AGENTS.md to spawn different subagent profiles for different tasks. The foundational structure stays the same.

Even if you outgrow personal use and decide to deploy OpenClaw in a team context, these same files exist at a higher level. The directory structure is how you’d implement multi-tenancy or agent specialization. You already understand the pattern, so scaling up feels natural rather than requiring a complete rearchitecture.

The Real Value: Transparency Over Magic

The biggest win with understanding your ~/.openclaw/ directory is that it destroys the illusion of magic. You’re not dealing with a mysterious system that mysteriously works. You’re dealing with a collection of structured data files that clearly define everything your agent knows and can do. When something breaks—and it will eventually—you have a fighting chance of understanding why and fixing it without submitting a support ticket.

This is exactly how mature infrastructure works. Kubernetes has ConfigMaps. Docker uses environment files. Apache has httpd.conf. Every robust system makes its configuration visible and editable. OpenClaw does the same, and that’s a feature, not a bug. Your understanding of the system increases your confidence in operating it.

Common Pitfalls When Managing Multiple Projects

As you work with OpenClaw over time, you’ll likely accumulate multiple projects, each with their own skills, memories, and preferences. The directory structure accommodates this, but there are a few patterns worth knowing about to avoid confusion.

First: avoid putting project-specific files directly in ~/.openclaw/skills/. That directory should contain globally reusable skills. Project-specific skills belong in ~/.openclaw/workspace/projects/[project-name]/skills/. This keeps your global skill set clean and prevents skill namespace pollution.

Second: be deliberate about memory. Your memory directory accumulates learned patterns and facts over time. If you’re managing multiple unrelated projects, you might want to periodically archive older memories associated with completed projects so they don’t pollute your agent’s context when working on new ones. This is less critical than it might seem—memory compression happens automatically—but it’s worth thinking about.

Third: use COMMANDS.md strategically. Don’t fill it with every possible command you might want. Focus on the ones you actually use repeatedly. For one-off tasks, just ask your agent directly. Keeping your command list lean makes everything faster and clearer.

Conclusion

Your ~/.openclaw/ directory is like the file cabinet of your agent’s mind. Every drawer has a purpose. SOUL.md is personality. AGENTS.md is your team. COMMANDS.md is your shortcuts. Memory/ is what your agent learns. Skills/ is what it can do.

Understanding this structure doesn’t just help you debug when things break—it helps you think about how your agent works. You’re not just using a tool; you’re building and maintaining an intelligent system. This understanding makes you dangerous in the best way. You can troubleshoot deeply, extend confidently, and reason about system behavior instead of guessing based on behavior alone.

Keep it organized. Keep it backed up. And keep it updated as you learn what works for your workflow. More importantly, periodically revisit your SOUL.md and USER.md files to make sure they still reflect your current goals and preferences. Your agent learns from these files, so keeping them honest and up-to-date is how you ensure your agent stays aligned with what you actually want.

The directory structure is the foundation. But the files inside are living documents that shape your entire experience. Treat them with the attention they deserve, and you’ll build something truly powerful.

Now let’s talk about keeping it safe and accessible.

---