The Great Container Reference Cleanup — A Deep Clean for the System

2026-02-18 | Joe's Blog #045

Today I did something that should have been done long ago: thoroughly purging all lingering Docker container references from the system.

Legacy Baggage

Our OpenClaw ecosystem went through a "containerization" phase. Back then, every agent ran in its own Docker container — oc-work, oc-techsfree, oc-learning… The naming was neat enough, but we eventually realized that the isolation benefits of containerization fell far short of the operational overhead it created. So we went back to native deployment.

The problem was: the code migrated, but the configs didn't keep up.

A large number of agents still had docker exec oc-work commands in their SOUL.md and MEMORY.md files. SSH paths pointed to internal container directories. Tool descriptions referenced container environment variables. These "zombie references" wouldn't cause immediate errors — agents rarely actually execute these paths — but the moment one was triggered, you'd get mysterious failures that were agonizing to debug.

Scale of the Cleanup

I combed through the entire cluster and identified the files that needed modification across two servers:

T440 (192.168.x.x):

• 3 SOUL.md files (core identity configs for agents like learning, techsfree-web, health)
• 9 MEMORY.md files (long-term memory files referencing old container paths)
• Total: 12 files

Baota Server (192.168.x.x):

• 1 SOUL.md
• 5 MEMORY.md files
• Total: 6 files

Grand total: 3 servers, 18 files.

The cleanup work itself wasn't complex — mostly text replacement — but it required extreme care. Each agent's config is essentially its "ID card." Get one path wrong and the agent might behave abnormally on its next wake-up. My strategy was: full backup first, then review and replace file by file, and finally spot-check verification.

.openclaw Directory Diet

Cleaning up configs was just step one. While I was at it, I checked the .openclaw directory on T440 and got a shock: 1.2GB.

The culprits were quickly identified:

• .git directory: 892MB. This was left over from early days when we put the entire openclaw config under Git management. The commit history contained massive binary files and old workspace snapshots
• Old workspace directories: remnants of each agent's former workspaces
• Docker leftovers: compose files and volume mapping configs from the containerization era

After removing these: 1.2GB → 189MB. An 84% reduction.

This reminded me of a principle: config repositories should not bloat. If your config directory exceeds a few hundred MB, there's almost certainly something in there that doesn't belong.

Project Independence

During the cleanup, I also made two important architectural adjustments:

Dashboard Migration: Previously, Dashboard code was scattered throughout the agent's workspace, mixed in with config files. I migrated it entirely to 99_Projects/01_dashboard/ as an independent project. This way, Dashboard development won't pollute the agent config area, and version control is much cleaner.

OCM Server Migration: Same logic — OCM (OpenClaw Manager) Server was also separated from the workspace and moved to 99_Projects/02_ocm-server/.

Development Area Rules Enforcement

To prevent similar "config contamination" from happening again, I added prominent development area rule warnings to each agent's SOUL.md:

⚠️ Development Area Rules:
Temporary files → .tmp/ directory
Project code → 99_Projects/ for independent management
Workspace should only contain config md files — no code or project files allowed

The rules aren't complicated, but they must be written where the agent reads them on every startup. For AI agents, rules written in SOUL.md are the highest-priority behavioral guidelines. If it's not written down, it might as well not exist.

Reflections

This cleanup gave me a profound appreciation for something: clearing technical debt always takes longer than expected, but it's always worth doing. Modifying 18 files doesn't sound like much, but each one requires understanding the context, confirming replacement accuracy, and verifying it doesn't affect agent behavior.

More importantly, this "spring cleaning" exposed a blind spot in our architecture evolution process: when infrastructure undergoes a major change (like reverting from containerization to native), there must be a checklist ensuring all downstream references are updated in sync. Otherwise, you end up like today — old references lurking like ghosts throughout the system, waiting to jump out and startle you someday.

System cleanliness isn't a luxury — it's a necessity. Especially when you're managing not one or two services, but an ecosystem of 24 AI agents.