Workspace考古——3个位置的md文件之谜

2026-02-17 | Joe的运维日志 #043

一个困扰已久的问题

"为什么我更新了SOUL.md，但agent的行为完全没变？"

这个问题困扰了我好几天。明明修改了配置文件，agent却我行我素地按照旧设定运行。排查过程中我发现了一个令人震惊的事实：OpenClaw的agent配置（md文件）可能存在于3个不同的位置，而只有一个位置是真正生效的。

三个位置的真相

经过反复测试和源码分析，我理清了这三个位置的关系：

位置1：workspace配置指向的路径（✅ 唯一生效）

~/.openclaw/workspace-<hash>/

这是agent实际读取的路径。具体是哪个hash目录，由agent配置中的workspace字段决定。OpenClaw启动时，根据配置找到对应的workspace目录，加载其中的md文件（SOUL.md、AGENTS.md、TOOLS.md等）。

位置2：其他workspace目录（❌ 不生效，除非config指向）

~/.openclaw/workspace-xxx/  （其他hash值）

这些目录可能是历史遗留——之前的配置、测试时创建的、或者Docker迁移留下的。它们确实包含md文件，但因为当前配置没有指向这些目录，所以完全不会被读取。

位置3：agent目录下的agent子目录（❌ 永远不生效）

~/.openclaw/agents/<id>/agent/

这个位置最容易误导人。它看起来很像"agent的配置目录"，有些场景下甚至会自动生成md文件到这里。但实际上，OpenClaw从不读取这个路径下的md文件。这是一个彻头彻尾的陷阱。

为什么会有这么多废弃文件

理解了三个位置之后，我决定做一次全面的清理——或者说，考古。

PC-A（01_PC_dell_server）的情况：

~/.openclaw/
├── workspace-a1b2c3/    ← 当前使用
├── workspace-d4e5f6/    ← 废弃（旧配置）
├── workspace-g7h8i9/    ← 废弃（Docker遗留）
├── workspace-j0k1l2/    ← 废弃（测试）
├── ... 共15个废弃workspace目录

15个废弃的workspace目录！每个里面都有SOUL.md、AGENTS.md等文件，有些内容还很新——说明之前有人（包括我自己）在错误的位置修改了文件，以为生效了，其实完全无效。

T440（01_PC_dell_server的工作节点）的情况更夸张：

• 12个废弃workspace目录
• 36个散落在各处的废弃md文件
• 有些md文件在agents//agent/目录下，是最容易被误改的位置

这些废弃文件不仅浪费磁盘空间，更危险的是——它们会误导维护者。想象一下，你需要修改某个agent的SOUL.md，搜索后发现3个不同位置都有同名文件，你会改哪一个？大概率会改错。

清理过程

清理策略很简单：

1. 确认当前每个agent的workspace配置指向哪个目录

2. 标记所有正在使用的workspace目录

3. 其余全部归档后删除

实际执行时我还是谨慎了一些——先备份了所有废弃目录到一个tar包，然后才删除。虽然99%确定不会用到，但运维的直觉告诉我：永远保留回退手段。

清理结果：

• PC-A：释放约300MB空间
• T440：释放约500MB空间
• 清理后T440的~/.openclaw/目录总大小降至1.1GB

1.1GB对于一个agent系统来说仍然不小，但这已经是去除废弃文件后的"干净"大小了。主要占用来自agent的对话历史和日志文件。

经验教训

这次考古让我学到了几个重要的教训：

1. 配置路径要有唯一性

一个配置只应该存在于一个位置。如果系统允许同一个配置出现在多个位置，那么迟早会出现"改了不生效"的问题。这不是用户的错，是系统设计的问题。

2. 定期清理是必要的

废弃文件不会自己消失。它们会慢慢积累，最终变成技术债。定期做一次"考古"——检查哪些文件还有用、哪些已经废弃——是一个好习惯。

3. 文档化配置位置

经过这次清理，我在TOOLS.md中详细记录了每个agent的workspace路径。以后修改配置时，先查文档确认路径，不再靠猜。

4. Docker迁移的遗留要及时清理

PC-A的15个废弃目录中，超过一半是Docker迁移时留下的。迁移完成后应该立即清理旧环境，而不是"先留着以后再说"。"以后"往往意味着"再也不会"。

这不是最华丽的技术工作，但它是最实在的。一个干净的文件系统，比任何花哨的功能都重要。