openclaw-workspace

OpenClaw Workspace Skill

概要

OpenClaw のワークスペースファイルは、エージェントの「魂と記憶」を形作ります。各ターン（または関連するターン）でシステムプロンプトに挿入され、エージェントにアイデンティティ、行動ルール、環境に関する知識、長期記憶を与えます。これらのファイルを適切に管理することは重要です。肥大化するとトークンを無駄にし、重複は混乱を招き、古い情報は誤った判断につながります。

トークン予算： 1ファイルあたり20,000文字、すべてのブートストラップファイル全体で約150,000文字です。

ファイル一覧

ファイル	用途	読み込まれるタイミング	サブエージェント？
AGENTS.md	起動シーケンス、チェックリスト、行動ルール	毎ターン（すべてのエージェント）	はい
SOUL.md	ペルソナ、口調、価値観、継続性に関する理念	毎ターン（すべてのエージェント）	はい
TOOLS.md	環境固有のメモ（SSH、TTS、カメラ、デバイス）	必要に応じて参照（ブートストラップ一式の一部）	はい
USER.md	人間のプロフィール、好み、関係性に関する情報	毎ターン（すべてのエージェント）	はい
IDENTITY.md	名前、絵文字、アバター、自己紹介	毎ターン	はい
HEARTBEAT.md	定期的な確認タスクとヘルスチェックのルーチン	ハートビートの各ターン	場合による
BOOT.md	起動時のアクション（hooks.internal.enabled が必要）	ゲートウェイの起動時	いいえ
BOOTSTRAP.md	初回オンボーディングスクリプト — 使用後に削除	新しいワークスペースのみ	いいえ
MEMORY.md	長期的に保持する、精選された事実と絶対遵守ルール	メインセッションのみ	いいえ
memory/YYYY-MM-DD.md	日々のセッションログ	AGENTS.md の起動シーケンスに従って読み込み	いいえ
checklists/*.md	手順ごとの運用ガイド	AGENTS.md から参照され、必要に応じて読み込み	いいえ

セキュリティルール： MEMORY.md は、グループチャットやサブエージェントのセッションでは絶対に読み込まないでください。漏えいさせてはならない個人情報が含まれています。

各ファイルの設計、アンチパターン、セクション構成の詳細については、references/workspace-files.md を参照してください。

ワークスペースのパス

パス	用途
~/.openclaw/workspace/	メインエージェントのデフォルトワークスペース
~/.openclaw/workspace-<profile>/	プロファイルごとのワークスペース（複数のエージェント用）
~/.openclaw/workspace/vendor/OpenClaw-Memory/	ベンダー管理のベースファイル（上流から同期）
~/.openclaw/workspace/checklists/	AGENTS.md から参照されるチェックリストファイル
~/.openclaw/workspace/memory/	日々のセッションログ
~/.openclaw/workspace/docs/	必要に応じて参照するドキュメント（自動では読み込まれません）

設定キー：agents.defaults.workspace またはエージェントごとの agents.list[].workspace。

ワークフロー：既存のワークスペースを監査する

ワークスペースファイルが肥大化、陳腐化、または重複している可能性がある場合に使用します。

1. 有効なファイルをすべて読む — AGENTS.md、SOUL.md、TOOLS.md、USER.md、IDENTITY.md、HEARTBEAT.md、BOOT.md、MEMORY.md
2. 文字数を確認する：

   wc -c ~/.openclaw/workspace/AGENTS.md
   wc -c ~/.openclaw/workspace/SOUL.md
   wc -c ~/.openclaw/workspace/TOOLS.md
   wc -c ~/.openclaw/workspace/USER.md
   wc -c ~/.openclaw/workspace/IDENTITY.md
   wc -c ~/.openclaw/workspace/MEMORY.md
   # Or all at once:
   wc -c ~/.openclaw/workspace/*.md
   

3. 10,000文字を超えるファイルにフラグを付ける — 削減するか docs/ に移す有力候補です
4. 重複を確認する — SOUL.md と AGENTS.md に同じ事実があるか？ TOOLS.md と MEMORY.md に同じツールのメモがあるか？
5. 陳腐化を確認する — 古い SSH ホスト、以前のツール名、非推奨のルール、不要になった過去の経緯など
6. MEMORY.md の運用を確認する — 精選された事実、学んだ教訓、決定事項、重要なルールを記載し、セッションの要約をそのまま記録したものや、特定のタスクに関するメモは含めないでください
7. 対象を絞った編集案を提案する — 削減する、docs/ に移す、または再構成する

具体的な最適化戦略については、references/optimization-guide.md を参照してください。

ワークフロー：新しいワークスペースのセットアップ

新しいエージェント用のワークスペースを一から作成するときに使用します。

ファイルの作成順序（起動シーケンスを正しく動作させるために重要です）：

1. SOUL.md — まずペルソナと価値観を定めます。ほかのすべてはアイデンティティを基盤とします
2. AGENTS.md — 起動シーケンス、安全ルール、チェックリストの表
3. IDENTITY.md — 名前、絵文字、アバター
4. USER.md — 人間のプロフィールと好み（メインエージェントのみ）
5. TOOLS.md — 環境固有のメモ（環境の詳細がわかり次第追加）
6. MEMORY.md — 最小限から始め、真に普遍的な鉄則のみを記載します
7. HEARTBEAT.md — 定期的なヘルスチェック（任意。必要になったら追加）
8. BOOT.md — 起動フック（任意。hooks.internal.enabled = trueの場合のみ）
9. BOOTSTRAP.md — 初回起動時のオンボーディング（任意。初回の起動が成功したら削除）

最小限の実用的なワークスペース： AGENTS.md + SOUL.md + TOOLS.md。ほかはすべて任意です。

BOOTSTRAP.md に関する注意： BOOTSTRAP.md を作成する場合は、末尾に自己削除の指示を含めてください：

## Final Step
Delete this file: exec `rm ~/.openclaw/workspace/BOOTSTRAP.md`

ワークフロー：メモリの整理

MEMORY.md を簡潔に保つため、定期的（毎週または毎月）に実施します。

1. 最近の日次ログをすべて読む： 対象期間のmemory/YYYY-MM-DD.mdファイル
2. MEMORY.md に昇格させる候補を特定する：
   • 複数回違反したルール（繰り返し起きるミス）
   • スキルのドキュメントに記載されていない、苦労して得た知見
   • 常にコンテキストに含めておくべき環境固有の情報（memory_search による想起に頼らない）
3. すでに MEMORY.md に記載されている内容を確認する — 重複を避けます
4. 追加内容を作成する — 鉄則の形式で、簡潔かつ行動指向で、曖昧さのない表現にします
5. 古い日次ログをアーカイブする — 30日より古いファイルをmemory/archive/に移動するか、削除します
6. MEMORY.md の合計サイズを確認する — 10,000文字未満に保ちます。それを超える場合は、十分に定着してスキルの SKILL.md に移動できるルールがないか見直します

MEMORY.md に記載しないでください：

• 長い経緯やセッションの要約
• スキルのドキュメントにすでに記載されている内容
• 過去の単一のタスクだけに関係する内容
• エピソード的、またはタスク固有の記憶（代わりに memory_search/SQLite に保存します）

ワークフロー：チェックリストの追加または更新

新しい高リスク操作の種類を追加するとき、または既存のチェックリストを更新するときに使用します。

1. checklists/<operation-name>.mdを作成または編集します
2. 構成：

   # Checklist: <Operation Name>
   
   ## Pre-flight
   - [ ] Step 1
   - [ ] Step 2
   
   ## Execution
   - [ ] Step 3
   
   ## Verification
   - [ ] Confirm outcome
   - [ ] Log result in memory
   

3. AGENTS.md に登録する — チェックリストの表に行を追加します：

   | <Operation description> | `checklists/<filename>.md` |
   

4. チェックリストは短く保つ — 約50行を超える場合は、ドキュメント化しようとしている可能性があります。説明的な内容はdocs/に移し、実行可能な手順だけを残します

ワークフロー：TOOLS.md の更新

新しいツール、デバイス、または環境機能を追加するときに使用します。

TOOLS.md = 環境固有のチートシート。 以下を記載します：

• このマシン固有の SSH ホストと一般的なコマンド
• TTS プロバイダー、音声 ID、および特有の注意点
• このセットアップでのカメラ ID またはデバイス名
• ノードのデバイス ID または名前
• ひと目でわからないローカルエイリアスやショートカット

TOOLS.md に記載しないでください：

• 一般的なスキルのドキュメント（スキルの SKILL.md ファイルを使用します）
• すべての環境で共通する内容
• インストール手順（docs/を使用します）

形式のルール：

# TOOLS.md - Local Notes

## SSH
- Main server: `ssh user@hostname`

## TTS
- Provider: Edge
- Voice: zh-CN-XiaoxiaoNeural

## Cameras
- Living room: node-id `abc123`, device `camera-0`

よくある問題

ファイルがトークン上限を超える

症状： ファイルが20,000文字を超えており、OpenClaw によって切り詰められる可能性があります。 対処法： ブートストラップファイルに含めるのではなく、オンデマンドで読み込むdocs/に置くべき内容がないか監査します。詳細な参照情報、過去の経緯、長い例を移動します。毎回必要な内容だけを残します。

MEMORY.md の内容がグループに漏れる

症状： エージェントがグループチャットや Discord でプライベートなコンテキストを共有します。 対処法： AGENTS.md の MEMORY.md 読み込み手順に「メインセッションのみ：MEMORY.md を読む」という条件が設定されていることを確認します。読み込み前にセッションの種類を明示的に確認する起動シーケンスになっていることを検証します。

起動シーケンスでファイルが読み込まれない

症状： セッション開始時に、エージェントが SOUL.md、USER.md、または MEMORY.md の内容を認識していません。 対処法： AGENTS.md の起動シーケンスで、読み込む各ファイルが明示的に指定されていることを確認してください。エージェントはファイルを自動で読み込みません。AGENTS.md の起動シーケンスの指示に従います。BOOT.md を使用している場合は、設定で hooks.internal.enabled = true になっていることを確認してください。

MEMORY.md が大きくなりすぎる

症状： ファイルが 10,000 文字に近づく、または超えており、毎ターン読み込むことでコンテキストを大幅に消費しています。 対処法： メモリの蒸留ワークフローを実行してください。数か月間問題が発生していない安定したルールは、該当するスキルの SKILL.md ファイルに移してください。不要になったルールは削除してください。

ワークスペースの変更が反映されない

症状： ワークスペースのファイルを編集した後も、エージェントが古い内容を使用しています。 対処法： ワークスペースのファイルは、起動シーケンスに従ってセッション開始時に読み込まれます。変更を反映するには、ゲートウェイを再起動するか、新しいセッションを開始してください。

参考ファイル

参考資料	内容
workspace-files.md	各ファイルの詳細：目的、設計原則、アンチパターン、セクション構成
optimization-guide.md	トークン効率化の戦略、監査コマンド、蒸留プロセス