openclaw backup

OpenClaw の状態、設定、認証プロファイル、チャンネル／プロバイダーの認証情報、セッション、およびオプションでワークスペースのローカルバックアップアーカイブを作成します。

openclaw backup createopenclaw backup create --output ~/Backupsopenclaw backup create --dry-run --jsonopenclaw backup create --verifyopenclaw backup create --no-include-workspaceopenclaw backup create --only-configopenclaw backup verify ./2026-03-09T08-00-00.000+08-00-openclaw-backup.tar.gzopenclaw backup sqlite create --global --repository ~/Backups/openclaw-sqliteopenclaw backup sqlite create --agent main --repository ~/Backups/openclaw-sqliteopenclaw backup sqlite list --repository ~/Backups/openclaw-sqliteopenclaw backup sqlite verify ~/Backups/openclaw-sqlite/<snapshot-id>openclaw backup sqlite verify ~/Backups/openclaw-sqlite/<snapshot-id> --scratch ~/Private/openclaw-scratchopenclaw backup sqlite restore ~/Backups/openclaw-sqlite/<snapshot-id> --target ./restored/openclaw.sqlite

注記

• アーカイブには、解決済みのソースパスとアーカイブレイアウトを含む manifest.json が埋め込まれます。
• デフォルトの出力は、現在の作業ディレクトリに作成される、タイムスタンプ付きの .tar.gz アーカイブです。タイムスタンプ付きファイル名にはマシンのローカルタイムゾーンが使用され、UTC オフセットが含まれます。現在の作業ディレクトリがバックアップ対象のソースツリー内にある場合、OpenClaw はデフォルトのアーカイブ保存先としてホームディレクトリを使用します。
• 既存のアーカイブファイルは上書きされません。自己包含を避けるため、ソースの状態／ワークスペースツリー内の出力パスは拒否されます。
• openclaw backup verify <archive> は、アーカイブにルートマニフェストがちょうど 1 つ含まれていることを確認し、パストラバーサル形式のアーカイブパスと SQLite サイドカーを拒否し、マニフェストで宣言されたすべてのペイロードが存在することを確認し、各 SQLite スナップショットのファイル形式を検証し、OpenClaw の正規データベースに対して完全な整合性チェックとロールチェックを実行します。専用の Plugin スキーマは、所有者が定義した SQLite 機能を必要とする可能性があるため、不透明なものとして扱われます。openclaw backup create --verify は、アーカイブの書き込み直後にその検証を実行します。
• openclaw backup create --only-config は、アクティブな JSON 設定ファイルのみをバックアップします。

SQLite スナップショット

広範な状態アーカイブではなく、OpenClaw が所有する 1 つの SQLite データベース用の移植可能なアーティファクトが必要な場合は、openclaw backup sqlite を使用します。

スナップショットの作成では、次の名前付きソースのうち、ちょうど 1 つを指定できます。

リポジトリには、コミット済みスナップショットごとに 1 つのディレクトリが含まれます。各スナップショットディレクトリには、次のものだけが含まれます。

• manifest.json
• database.sqlite

スナップショット作成では、読み取り前に稼働中のデータベースを検証し、SQLite のオンラインバックアップ API を使用して、長時間の読み取りトランザクションを保持せずにコミット済み WAL 状態を取得し、稼働中のデータベースを閉じ、プライベートコピーを VACUUM で圧縮し、生成されたデータベースを再度検証して、既存のパスを上書きせずに完成したディレクトリを公開します。グローバルスナップショットでは、削除されたキューペイロードが空きページに残らないよう、圧縮前に一時的な配信キューの行を削除します。

移植用アーティファクトとして、稼働中の .sqlite、-wal、-shm、または -journal ファイルをコピーしないでください。完成したスナップショットディレクトリのみをコピーしてください。

SQLite スナップショットには、認証プロファイル、セッション状態、Plugin の状態、その他の機密レコードが含まれる場合があります。稼働中の OpenClaw 状態ディレクトリと同じ権限、暗号化、保持ポリシー、および保存先の制限をリポジトリに適用してください。

検証と復元

openclaw backup sqlite verify <snapshot-directory>openclaw backup sqlite restore <snapshot-directory> --target <new-database-path>

検証では、厳密なマニフェスト形式、アーティファクトのサイズと SHA-256、SQLite の整合性、外部キー、スキーマバージョン、データベースのロールと所有者、および OpenClaw が所有するインデックス定義を確認します。

検証では、パス名の競合によって SQLite が検査するバイト列を差し替えられないよう、内容が固定されたプライベートコピーを検証します。デフォルトでは、この一時コピーはスナップショットリポジトリの隣に作成され、コマンドが終了する前に削除されます。ステージングルートとその祖先チェーンでは、他のユーザーによる置き換えを防止する必要があります。POSIX のルートは現在のユーザーが所有し、グループ／全ユーザーによる書き込みが不可でなければなりません。/tmp のような sticky 属性を持つ祖先は、ユーザー所有の子について許可されます。ステージングを公開または置換可能にする macOS ACL の付与は拒否されます。Windows のルートと祖先は、現在のユーザーまたは信頼できる OS プリンシパルが所有し、信頼できないアクセスによるステージングを拒否する ACL が必要です。読み取り専用マウントまたはネットワーク共有の場合は、同等の暗号化と保存先制御を備えたストレージ上の --scratch <existing-private-directory> を渡します。

スナップショット作成では、データベースのバイト列をステージングまたは公開する前に、リポジトリに対して同じ所有者、ACL、祖先、およびパス同一性のチェックを適用します。

復元では検証を繰り返し、新しいターゲットにのみ書き込みます。既存のターゲット、-wal、-shm、または -journal サイドカーを拒否し、稼働中の OpenClaw データベースをインプレースで置換することはありません。ターゲットの親には、検証用スクラッチと同じパスセキュリティ要件が適用されます。復元されたデータベースの有効化は、明示的なオフラインでのオペレーター操作として残されます。

スナップショットリポジトリはローカルディレクトリです。スケジューリング、アップロード、保持、増分 WAL バンドル、フェイルオーバー、および起動時の復元動作は、意図的にこのコマンドの対象外とされています。

バックアップ対象

openclaw backup create は、ローカルの OpenClaw インストールからソースを計画します。

• 状態ディレクトリ（通常は ~/.openclaw）
• アクティブな設定ファイルのパス
• 状態ディレクトリ外に存在する場合の、解決済み credentials/ ディレクトリ
• --no-include-workspace を渡さない限り、現在の設定から検出されたワークスペースディレクトリ

認証プロファイルやその他のエージェントごとのランタイム状態は、状態ディレクトリ内の SQLite（agents/<agentId>/agent/openclaw-agent.sqlite）に保存されるため、状態バックアップのエントリによって自動的に対象となります。

--only-config は、状態、認証情報ディレクトリ、およびワークスペースの検出をスキップし、アクティブな設定ファイルのパスのみをアーカイブします。

OpenClaw はアーカイブを構築する前にパスを正規化します。設定、認証情報ディレクトリ、またはワークスペースがすでに状態ディレクトリ内にある場合、それらが最上位のバックアップソースとして個別に重複することはありません。存在しないパスはスキップされます。

アーカイブ作成中、OpenClaw は tar が読み取る前に、稼働中に変更されることが既知のパスを除外します。これにより、記録されたファイルサイズと同時書き込みの競合を回避します。このフィルターは、バックアップ対象の各状態ディレクトリ内で、次の状態ディレクトリ相対ルールを適用します。

これらのルールは、状態ディレクトリ外のワークスペースファイルを除外しません。また、この表に一致する完了済みのトランスクリプトファイルとログファイルも除外されるため、必要に応じてそれらのレコードを別途保持してください。JSON 結果の skippedVolatileCount は、意図的に除外されたファイル数を報告します。

状態ディレクトリ内の SQLite データベースは、SQLite のオンラインバックアップ API を使用して取得され、削除済みページの残留データがアーカイブに入らないよう VACUUM でオフライン圧縮されます。また、稼働中の WAL／SHM ファイルはコピーされません。利用できない所有者定義の SQLite 機能を必要とする Plugin 所有のデータベースは、直接ファイルコピーにフォールバックせず、失敗時に閉じられます。ワークスペースのバックアップを通じて含まれる SQLite ファイルはワークスペースファイルとしてコピーされ、圧縮の保証対象にはなりません。

状態ディレクトリの extensions/ ツリーにあるインストール済み Plugin のソースファイルとマニフェストファイルは含まれますが、その配下の node_modules/ 依存関係ツリーは、再構築可能なインストールアーティファクトとしてスキップされます。アーカイブの復元後、復元した Plugin が依存関係の欠落を報告する場合は、openclaw plugins update <id> を使用するか、openclaw plugins install <spec> --force で再インストールしてください。

状態ディレクトリ内にある、インストーラー管理および再構築可能なランタイムルートもスキップされます：dev/、git/、npm/、レガシーの npm-runtime/、および tools/。これらには、権威あるユーザー状態ではなく、管理対象のチェックアウト、パッケージツリー、ダウンロード済みランタイムが含まれます。復元後に、対応するランタイムまたは Plugin を再インストールまたは更新してください。これらのルートのいずれかに明示的に設定された設定ファイル、認証情報ディレクトリ、またはワークスペースは引き続き含まれます。

無効な設定の場合の動作

openclaw backup は通常の設定事前チェックを回避するため、復旧中でも使用できます。ワークスペースの検出は有効な設定に依存するため、設定ファイルが存在していても無効で、ワークスペースのバックアップが有効なままの場合、openclaw backup create は即座に失敗します。

この状況で部分バックアップを行うには、--no-include-workspace を指定して再実行します。これにより、状態、設定、および外部の認証情報ディレクトリを対象に保ちながら、ワークスペースの検出を完全にスキップします。

--only-config は、ワークスペースの検出のために設定を解析しないため、設定が不正な場合でも機能します。

サイズとパフォーマンス

OpenClaw は、バックアップの最大サイズやファイルごとのサイズ制限を組み込みでは適用しません。アーカイブへの書き込みで 5 分間データが生成されない場合、無期限に停止し続けるのではなく失敗し、部分的な一時ファイルを削除します。それ以外の実用上の制限は、次の要因によって決まります。

• 一時アーカイブの書き込みと最終アーカイブに必要な空き容量
• 大規模なワークスペースツリーを走査し、.tar.gz に圧縮する時間
• --verify または openclaw backup verify でアーカイブを再スキャンする時間
• 保存先ファイルシステムの動作：OpenClaw は、最終アーカイブパスに処理中のコピーが公開されることがないよう、上書きしないハードリンクによる公開を必要とします。未対応のファイルシステムでは、対処可能なエラーを表示して失敗します

公開後に最終ディレクトリの永続性確認が失敗した場合、コマンドは失敗を報告しますが、同時に置き換えられたエントリを削除するリスクを避けるため、完成した最終エントリを保持します。

通常、大規模なワークスペースがアーカイブサイズの主な要因です。より小さく高速なバックアップには --no-include-workspace を、最小のアーカイブには --only-config を使用します。

関連項目

• CLI リファレンス