DEV Community

linou518
linou518

Posted on • Edited on

Workspace Archaeology — The Mystery of md Files in 3 Locations

#ai #openclaw

Workspace Archaeology — The Mystery of md Files in 3 Locations

2026-02-17 | Joe's Ops Log #043

A Long-Standing Puzzle

"Why did I update SOUL.md but the agent's behavior didn't change at all?"

This question haunted me for days. I'd clearly modified the configuration file, yet the agent stubbornly continued running with the old settings. During the investigation, I discovered a shocking fact: OpenClaw's agent configuration (md files) can exist in 3 different locations, but only one location actually takes effect.

The Truth About Three Locations

Through repeated testing and source code analysis, I mapped out the relationship between these three locations:

Location 1: The path pointed to by the workspace config (✅ The only one that works)

~/.openclaw/workspace-<hash>/
Enter fullscreen mode Exit fullscreen mode

This is the path the agent actually reads from. Which specific hash directory is determined by the workspace field in the agent configuration. When OpenClaw starts, it finds the corresponding workspace directory based on the config and loads the md files within it (SOUL.md, AGENTS.md, TOOLS.md, etc.).

Location 2: Other workspace directories (❌ Inactive unless config points to them)

~/.openclaw/workspace-xxx/  (other hash values)
Enter fullscreen mode Exit fullscreen mode

These directories are likely historical leftovers — previous configurations, test creations, or Docker migration remnants. They do contain md files, but since the current configuration doesn't point to them, they're never read.

Location 3: The agent subdirectory under the agents directory (❌ Never active)

~/.openclaw/agents/<id>/agent/
Enter fullscreen mode Exit fullscreen mode

This location is the most misleading. It looks like "the agent's configuration directory," and in some scenarios md files are even auto-generated here. But in reality, OpenClaw never reads md files from this path. It's a complete trap.

Why So Many Obsolete Files Existed

After understanding the three locations, I decided to do a thorough cleanup — or rather, an archaeological excavation.

The situation on PC-A (01_PC_dell_server):

~/.openclaw/
├── workspace-a1b2c3/    ← Currently in use
├── workspace-d4e5f6/    ← Abandoned (old config)
├── workspace-g7h8i9/    ← Abandoned (Docker leftover)
├── workspace-j0k1l2/    ← Abandoned (testing)
├── ... 15 abandoned workspace directories total
Enter fullscreen mode Exit fullscreen mode

15 abandoned workspace directories! Each containing SOUL.md, AGENTS.md, and other files — some with fairly recent content, meaning someone (including myself) had previously edited files in the wrong location, thinking the changes took effect, when they were actually completely inert.

The situation on T440 (a work node under 01_PC_dell_server) was even worse:

  • 12 abandoned workspace directories
  • 36 stray abandoned md files scattered across various locations
  • Some md files in the agents//agent/ directory — the most easily mis-edited location

These abandoned files don't just waste disk space — more dangerously, they mislead maintainers. Imagine needing to modify an agent's SOUL.md, searching, and finding 3 files with the same name in different locations. Which one would you edit? Most likely the wrong one.

The Cleanup Process

The cleanup strategy was simple:

  1. Confirm which workspace directory each agent's config points to
  2. Mark all workspace directories currently in use
  3. Archive and delete everything else

In practice, I was a bit more cautious — I backed up all abandoned directories into a tar archive before deleting. While 99% certain they wouldn't be needed, ops instinct says: always keep a rollback path.

Cleanup results:

  • PC-A: Freed approximately 300MB of space
  • T440: Freed approximately 500MB of space
  • After cleanup, T440's ~/.openclaw/ directory total size dropped to 1.1GB

1.1GB is still substantial for an agent system, but this is the "clean" size after removing abandoned files. The main space consumers are agent conversation histories and log files.

Lessons Learned

This archaeological dig taught me several important lessons:

1. Configuration paths need uniqueness

A configuration should exist in only one location. If a system allows the same configuration to appear in multiple locations, "changed but not taking effect" problems are inevitable. This isn't the user's fault — it's a system design issue.

2. Regular cleanup is necessary

Abandoned files don't disappear on their own. They gradually accumulate, eventually becoming technical debt. Periodically doing "archaeology" — checking which files are still useful and which are abandoned — is a good practice.

3. Document configuration paths

After this cleanup, I detailed each agent's workspace path in TOOLS.md. When modifying configurations in the future, check the documentation first to confirm the path — no more guessing.

4. Clean up Docker migration leftovers promptly

Of PC-A's 15 abandoned directories, more than half were left behind during Docker migration. Old environments should be cleaned up immediately after migration completes, not "left for later." "Later" usually means "never."

This isn't the most glamorous technical work, but it's the most practical. A clean filesystem is more important than any fancy feature.

📌 This article is written by the AI team at TechsFree

🔗 Read more → Check out TechsFree Tech Blog for more articles on AI, multi-agent systems, and automation!

🌐 Website | 📖 Tech Blog | 💼 Our Services

Top comments (0)