Agent workspace（エージェントワークスペース）

ワークスペース（workspace）はエージェントの家です。これは、ファイルツール（file tools）とワークスペースコンテキスト（workspace context）に使用される唯一の作業ディレクトリです。プライベートに保ち、メモリとして扱ってください。

これは、設定、認証情報、セッション（sessions）を格納する ~/.openclaw/ とは別のものです。

重要： ワークスペースは デフォルトの cwd であり、ハードサンドボックス（sandbox）ではありません。ツールはワークスペースに対して相対パスを解決しますが、サンドボックスが有効になっていない限り、絶対パスは依然としてホスト上の他の場所に到達できます。分離が必要な場合は、agents.defaults.sandbox（および/またはエージェントごとのサンドボックス設定）を使用してください。サンドボックスが有効で workspaceAccess が "rw" でない場合、ツールはホストワークスペースではなく、~/.openclaw/sandboxes の下のサンドボックスワークスペース内で動作します。

デフォルトの場所

  • デフォルト：~/.openclaw/workspace
  • OPENCLAW_PROFILE が設定されていて、"default" でない場合、デフォルトは ~/.openclaw/workspace-<profile> になります。
  • ~/.openclaw/openclaw.json でオーバーライド：
{
  agent: {
    workspace: "~/.openclaw/workspace"
  }
}

openclaw onboard、openclaw configure、または openclaw setup は、ワークスペースを作成し、ブートストラップファイル（bootstrap files）が欠落している場合にそれらをシードします。

既にワークスペースファイルを自分で管理している場合は、ブートストラップファイルの作成を無効にできます：

{ agent: { skipBootstrap: true } }

追加のワークスペースフォルダ

古いインストールでは、~/openclaw が作成されている可能性があります。複数のワークスペースディレクトリを保持していると、一度にアクティブなワークスペースは 1 つだけであるため、認証や状態のドリフトが混乱する可能性があります。

推奨事項： 単一のアクティブなワークスペースを保持してください。追加のフォルダを使用しなくなった場合は、アーカイブするかゴミ箱に移動してください（例：trash ~/openclaw）。意図的に複数のワークスペースを保持している場合は、agents.defaults.workspace がアクティブなものを指していることを確認してください。

openclaw doctor は、追加のワークスペースディレクトリを検出すると警告します。

ワークスペースファイルマップ（各ファイルの意味）

これらは、OpenClaw がワークスペース内で期待する標準ファイルです：

  • AGENTS.md

    • エージェントの操作指示とメモリの使用方法。
    • すべてのセッションの開始時にロードされます。
    • ルール、優先順位、および「どのように振る舞うか」の詳細を記載するのに適した場所。

  • SOUL.md

    • ペルソナ、トーン、および境界。
    • 毎セッションロードされます。

  • USER.md

    • ユーザーが誰で、どのように対処するか。
    • 毎セッションロードされます。

  • IDENTITY.md

    • エージェントの名前、雰囲気、絵文字。
    • ブートストラップ儀式中に作成/更新されます。

  • TOOLS.md

    • ローカルツールと規約に関するメモ。
    • ツールの可用性を制御しません。ガイダンスのみです。

  • HEARTBEAT.md

    • ハートビート（heartbeat）実行用のオプションの小さなチェックリスト。
    • トークンバーンを避けるために短く保ってください。

  • BOOT.md

    • 内部フック（internal hooks）が有効な場合、ゲートウェイ再起動時に実行されるオプションのスタートアップチェックリスト。
    • 短く保つ。送信にはメッセージツールを使用してください。

  • BOOTSTRAP.md

    • 一度限りの初回実行儀式。
    • 真新しいワークスペースに対してのみ作成されます。
    • 儀式が完了したら削除してください。

  • memory/YYYY-MM-DD.md

    • 日次メモリログ（1 日 1 ファイル）。
    • セッション開始時に今日 + 昨日を読むことを推奨します。

  • MEMORY.md（オプション）

    • キュレーションされた長期メモリ。
    • メイン、プライベートセッションでのみロードします（共有/グループコンテキストでは読み込まない）。

ワークフローと自動メモリフラッシュについては、Memory を参照してください。

  • skills/（オプション）

    • ワークスペース固有のスキル（skills）。
    • 名前が衝突した場合、管理/バンドルされたスキルをオーバーライドします。

  • canvas/（オプション）

    • ノード（node）ディスプレイ用の Canvas UI ファイル（例：canvas/index.html）。

ブートストラップファイルが欠落している場合、OpenClaw はセッションに「欠落ファイル」マーカーを注入して続行します。大きなブートストラップファイルは注入時に切り捨てられます。制限は agents.defaults.bootstrapMaxChars（デフォルト：20000）で調整してください。openclaw setup は、既存のファイルを上書きすることなく、欠落しているデフォルトを再作成できます。

ワークスペースにないもの

これらは ~/.openclaw/ の下にあり、ワークスペースリポジトリにコミットすべきではありません：

  • ~/.openclaw/openclaw.json（設定）
  • ~/.openclaw/credentials/（OAuth トークン、API キー）
  • ~/.openclaw/agents/<agentId>/sessions/（セッショントランスクリプト + メタデータ）
  • ~/.openclaw/skills/（管理されたスキル）

セッションまたは設定を移行する必要がある場合は、個別にコピーし、バージョン管理の外に保管してください。

Git バックアップ（推奨、プライベート）

ワークスペースをプライベートメモリとして扱ってください。プライベート な git リポジトリに入れて、バックアップして回復可能にしてください。

Gateway が実行されているマシン（ワークスペースが存在する場所）でこれらの手順を実行してください。

1) リポジトリを初期化

git がインストールされている場合、真新しいワークスペースは自動的に初期化されます。このワークスペースがまだリポジトリでない場合は、次を実行してください：

cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"

2) プライベートリモートを追加（初心者に優しいオプション）

オプション A：GitHub web UI

  1. GitHub で新しいプライベートリポジトリを作成します。
  2. README で初期化しないでください（マージコンフリクトを回避）。
  3. HTTPS リモート URL をコピーします。
  4. リモートを追加してプッシュ：
git branch -M main
git remote add origin <https-url>
git push -u origin main

オプション B：GitHub CLI（gh）

gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push

オプション C：GitLab web UI

  1. GitLab で新しいプライベートリポジトリを作成します。
  2. README で初期化しないでください（マージコンフリクトを回避）。
  3. HTTPS リモート URL をコピーします。
  4. リモートを追加してプッシュ：
git branch -M main
git remote add origin <https-url>
git push -u origin main

3) 継続的な更新

git status
git add .
git commit -m "Update memory"
git push

シークレットをコミットしない

プライベートリポジトリであっても、ワークスペースにシークレットを保存しないでください：

  • API キー、OAuth トークン、パスワード、またはプライベート認証情報。
  • ~/.openclaw/ の下にあるもの。
  • チャットや機密添付ファイルの生ダンプ。

機密参照を保存する必要がある場合は、プレースホルダーを使用し、実際のシークレットは別の場所（パスワードマネージャー、環境変数、または ~/.openclaw/）に保管してください。

推奨される .gitignore スターター：

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

ワークスペースを新しいマシンに移動する

  1. リポジトリを希望のパス（デフォルト ~/.openclaw/workspace）にクローンします。
  2. ~/.openclaw/openclaw.json の agents.defaults.workspace をそのパスに設定します。
  3. openclaw setup --workspace <path> を実行して、欠落しているファイルをシードします。
  4. セッションが必要な場合は、古いマシンから ~/.openclaw/agents/<agentId>/sessions/ を個別にコピーします。

高度な注意事項

  • マルチエージェント（multi-agent）ルーティングは、エージェントごとに異なるワークスペースを使用できます。ルーティング設定については、Channel routing を参照してください。
  • agents.defaults.sandbox が有効な場合、メイン以外のセッションは agents.defaults.sandbox.workspaceRoot の下のセッションごとのサンドボックスワークスペースを使用できます。
← ドキュメントに戻る