エージェントワークスペース

ワークスペースはエージェントのホームディレクトリです。ファイルツールやワークスペースコンテキストで使用される唯一の作業ディレクトリであり、プライベートな領域としてメモリのように扱ってください。

これは設定、認証情報、セッションを格納する ~/.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再起動時に実行されるオプションの起動チェックリスト。
    • 短くしてください。送信にはメッセージツールを使用します。

  • BOOTSTRAP.md

    • 初回実行時の一度きりの儀式。
    • 新規ワークスペースでのみ作成されます。
    • 儀式の完了後に削除してください。

  • memory/YYYY-MM-DD.md

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

  • MEMORY.md（オプション）

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

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

  • skills/（オプション）

    • ワークスペース固有のスキル。
    • 名前が衝突した場合、マネージド/バンドルスキルをオーバーライドします。

  • canvas/（オプション）

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

ブートストラップファイルが欠落している場合、OpenClawはセッションに「missing file」マーカーを注入して処理を続行します。大きなブートストラップファイルは注入時に切り詰められます。制限は 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

  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/ を別途コピー。

上級者向けメモ

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