Workspace考古学——3つの場所に散らばるmdファイルの謎

2026-02-17 | Joeの運用保守ログ #043

長年の疑問

「SOUL.mdを更新したのに、agentの動作がまったく変わらないのはなぜだ？」

この問題に数日間悩まされた。設定ファイルを確かに修正したのに、agentは我関せずと古い設定のまま動作し続ける。調査の過程で衝撃的な事実を発見した：OpenClawのagent設定（mdファイル）は3つの異なる場所に存在しうるが、実際に有効なのは1つの場所だけだった。

3つの場所の真実

何度もテストとソースコード分析を繰り返し、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ファイルを一切読み取らない。これは完全な罠だ。

なぜこれほど多くの不要ファイルがあるのか

3つの場所を理解した後、全面的なクリーンアップ——あるいは考古学的発掘を行うことに決めた。

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. 設定パスには一意性が必要

1つの設定は1つの場所にだけ存在すべきだ。同一の設定が複数の場所に存在できるシステムでは、遅かれ早かれ「変更しても反映されない」問題が発生する。これはユーザーのせいではなく、システム設計の問題だ。

2. 定期的なクリーンアップは必要

廃棄ファイルは自然には消えない。徐々に蓄積され、最終的に技術的負債となる。定期的に「考古学的発掘」を行い——どのファイルがまだ有用で、どれが廃棄されているかを確認する——のは良い習慣だ。

3. 設定パスをドキュメント化する

今回のクリーンアップの後、TOOLS.mdに各agentのworkspaceパスを詳細に記録した。今後設定を修正する際は、まずドキュメントでパスを確認し、推測に頼ることはもうしない。

4. Docker移行の遺留物は速やかにクリーンアップする

PC-Aの15個の廃棄ディレクトリのうち、半分以上がDocker移行時に残されたものだった。移行完了後は旧環境を直ちにクリーンアップすべきであり、「とりあえず置いておいて後で対処」ではいけない。「後で」はたいてい「二度とやらない」を意味する。

これは最も華やかな技術作業ではないが、最も実のある作業だ。クリーンなファイルシステムは、どんな派手な機能よりも重要だ。