OpenClawワークスペース設定ガイド：作業ディレクトリを最適化

AIエージェントを開発していると、「エージェントがどこに情報を保存し、どのように過去の文脈を思い出しているのか」が気になりますよね。設定ファイルと作業用のデータが混ざってしまい、管理が複雑になってしまうのは、多くの開発者が直面する悩みです。

OpenClawでは、エージェントの「記憶」と「作業場」を明確に分けるために、専用のワークスペースを用意しています。この記事では、エージェントのホームグラウンドとなるワークスペースの仕組みと、その管理方法について解説します。

Agent workspace

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

これは、config、credentials、sessionsを保存する ~/.openclaw/ とは別の場所になります。

重要: ワークスペースは**デフォルトのcwd（カレントワーキングディレクトリ）**であり、厳密なサンドボックスではありません。各ツールはワークスペースを基準に相対パスを解決しますが、サンドボックスが有効でない限り、絶対パスを使用してホスト上の他の場所にアクセスできてしまいます。アイソレーションが必要な場合は、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 を実行すると、ワークスペースが作成され、ファイルが存在しない場合はブートストラップファイルが配置されます。サンドボックスのシードコピーは、ワークスペース内の通常のファイルのみを受け入れます。ソースワークスペースの外を指すシンボリックリンクやハードリンクのエイリアスは無視されます。

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

{ agent: { skipBootstrap: true } }

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

古いバージョンのインストールでは、~/openclaw が作成されている場合があります。複数のワークスペースディレクトリが存在すると、認証の混乱や状態の不一致を招く可能性があります。一度にアクティブにできるワークスペースは1つだけだからです。

推奨: アクティブなワークスペースは1つだけに絞ってください。使わなくなった古いフォルダがある場合は、アーカイブするかゴミ箱に移動（例: trash ~/openclaw）してください。意図的に複数のワークスペースを使い分けている場合は、agents.defaults.workspace が現在使用したい場所を指しているか確認してください。

openclaw doctor を実行すると、余分なワークスペースディレクトリが検出された場合に警告が表示されます。

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

OpenClawがワークスペース内で想定している標準的なファイルは以下の通りです。

AGENTS.md
- エージェントへの指示書と、メモリの使用方法について記述します。
- すべてのセッションの開始時に読み込まれます。
- ルール、優先順位、「どのように振る舞うべきか」の詳細を記すのに適した場所です。
SOUL.md
- ペルソナ、トーン、および境界線（やってはいけないこと）を記述します。
- 毎セッション読み込まれます。
USER.md
- ユーザーが誰であるか、どのように呼ぶべきかを記述します。
- 毎セッション読み込まれます。
IDENTITY.md
- エージェントの名前、雰囲気、絵文字を記述します。
- ブートストラップの儀式の間に作成・更新されます。
TOOLS.md
- ローカルツールや規約に関するメモです。
- ツールの可用性を制御するものではなく、あくまでガイドラインとして機能します。
HEARTBEAT.md
- オプションの、ハートビート実行用の小さなチェックリストです。
- トークンの消費を抑えるため、短く保ってください。
BOOT.md
- 内部フックが有効な場合に、Gatewayの再起動時に実行されるオプションのスタートアップチェックリストです。
- 短く保ち、外部への送信にはmessage toolを使用してください。
BOOTSTRAP.md
- 初回実行時のみ行われる儀式です。
- 新しいワークスペースに対してのみ作成されます。
- 儀式が完了したら削除してください。
memory/YYYY-MM-DD.md
- 日ごとのメモリログです（1日1ファイル）。
- セッション開始時に「今日＋昨日」分を読み込むのがおすすめです。
MEMORY.md（オプション）
- 整理された長期記憶です。
- メインのプライベートセッションでのみ読み込んでください（共有/グループコンテキストでは読み込まない）。

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

skills/（オプション）
- ワークスペース固有のスキルを格納します。
- 名前が衝突した場合、管理/バンドルされたスキルよりも優先されます。
canvas/（オプション）
- node表示用のCanvas UIファイル（例: canvas/index.html）を格納します。

ブートストラップファイルが不足している場合、OpenClawはセッションに「ファイル欠落」マーカーを挿入して続行します。大きなブートストラップファイルは挿入時に切り詰められます。制限を調整するには agents.defaults.bootstrapMaxChars（デフォルト: 20000）や agents.defaults.bootstrapTotalMaxChars（デフォルト: 150000）を使用してください。 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

GitHubで新しいプライベートリポジトリを作成します。
READMEで初期化しないでください（マージコンフリクトを避けるため）。
HTTPSのリモートURLをコピーします。
リモートを追加してプッシュします。

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

GitLabで新しいプライベートリポジトリを作成します。
READMEで初期化しないでください（マージコンフリクトを避けるため）。
HTTPSのリモートURLをコピーします。
リモートを追加してプッシュします。

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*

新しいマシンへのワークスペースの移動

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

高度な設定

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

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。