メンテナンス

移行ガイド

このガイドでは、OpenClaw Gateway をオンボーディングをやり直さずに別のマシンに移行します。移行の概念はシンプルです:

  • ステートディレクトリ ($OPENCLAW_STATE_DIR、デフォルト: ~/.openclaw/) をコピーします — これには設定、認証、セッション、チャネルの状態が含まれます。
  • あなたのワークスペース (デフォルト: ~/.openclaw/workspace/) をコピーします — これにはエージェントファイル（メモリ、プロンプトなど）が含まれます。

しかし、プロファイル、パーミッション、部分的なコピーに関する一般的な落とし穴があります。

開始前に（何を移行するか）

1) ステートディレクトリを特定する

ほとんどのインストールではデフォルトを使用しています:

  • ステートディレクトリ: ~/.openclaw/

ただし、以下を使用している場合は異なる場合があります:

  • --profile <name> (多くの場合 ~/.openclaw-<profile>/ になります)
  • OPENCLAW_STATE_DIR=/some/path

わからない場合は、古いマシンで実行してください:

openclaw status

出力内の OPENCLAW_STATE_DIR / プロファイルに関する言及を探してください。複数のゲートウェイを実行している場合は、各プロファイルに対して繰り返してください。

2) ワークスペースを特定する

一般的なデフォルト:

  • ~/.openclaw/workspace/ (推奨ワークスペース)
  • 作成したカスタムフォルダ

ワークスペースは、MEMORY.md、USER.md、memory/*.md などのファイルが存在する場所です。

3) 何が保持されるかを理解する

両方のステートディレクトリとワークスペースをコピーすると、以下が保持されます:

  • ゲートウェイ設定 (openclaw.json)
  • 認証プロファイル / APIキー / OAuthトークン
  • セッション履歴 + エージェント状態
  • チャネル状態 (例: WhatsApp ログイン/セッション)
  • ワークスペースファイル (メモリ、スキルノートなど)

ワークスペースのみをコピーした場合 (例: Git経由)、以下は保持されません:

  • セッション
  • 認証情報
  • チャネルログイン

これらは $OPENCLAW_STATE_DIR の下に存在します。

移行手順（推奨）

ステップ 0 — バックアップを作成する（古いマシン）

古いマシンで、まずゲートウェイを停止し、ファイルがコピー中に変更されないようにします:

openclaw gateway stop

（任意ですが推奨）ステートディレクトリとワークスペースをアーカイブします:

# プロファイルやカスタムロケーションを使用している場合はパスを調整してください
cd ~
tar -czf openclaw-state.tgz .openclaw

tar -czf openclaw-workspace.tgz .openclaw/workspace

複数のプロファイル/ステートディレクトリ (例: ~/.openclaw-main, ~/.openclaw-work) がある場合は、それぞれをアーカイブしてください。

ステップ 1 — 新しいマシンに OpenClaw をインストールする

新しいマシンで、CLI (および必要に応じて Node) をインストールします:

この段階では、オンボーディングによって新しい ~/.openclaw/ が作成されても問題ありません — 次のステップで上書きします。

ステップ 2 — ステートディレクトリ + ワークスペースを新しいマシンにコピーする

両方をコピーします:

  • $OPENCLAW_STATE_DIR (デフォルト ~/.openclaw/)
  • ワークスペース (デフォルト ~/.openclaw/workspace/)

一般的な方法:

  • tarball を scp で転送して展開
  • SSH 経由で rsync -a
  • 外部ドライブ

コピー後、以下を確認してください:

  • 隠しディレクトリが含まれていること (例: .openclaw/)
  • ゲートウェイを実行するユーザーに対してファイルの所有権が正しいこと

ステップ 3 — Doctor を実行する（マイグレーション + サービス修復）

新しいマシンで:

openclaw doctor

Doctor は「安全で退屈な」コマンドです。サービスを修復し、設定マイグレーションを適用し、不一致について警告します。その後:

openclaw gateway restart
openclaw status

一般的な落とし穴（および回避方法）

落とし穴: プロファイル / ステートディレクトリの不一致

古いゲートウェイをプロファイル (または OPENCLAW_STATE_DIR) 付きで実行していて、新しいゲートウェイが異なるものを使用している場合、以下のような症状が現れます:

  • 設定変更が反映されない
  • チャネルが欠落している / ログアウトしている
  • 空のセッション履歴

修正: 移行したのと同じプロファイル/ステートディレクトリを使用してゲートウェイ/サービスを実行し、次を再実行します:

openclaw doctor

落とし穴: openclaw.json のみをコピーする

openclaw.json だけでは不十分です。多くのプロバイダーは以下の下に状態を保存します:

  • $OPENCLAW_STATE_DIR/credentials/
  • $OPENCLAW_STATE_DIR/agents/<agentId>/...

常に $OPENCLAW_STATE_DIR フォルダ全体を移行してください。

落とし穴: パーミッション / 所有権

root としてコピーしたりユーザーを変更したりした場合、ゲートウェイが認証情報/セッションを読み取れない可能性があります。修正: ステートディレクトリ + ワークスペースがゲートウェイを実行するユーザーによって所有されていることを確認してください。

落とし穴: リモート/ローカルモード間の移行

  • あなたの UI (WebUI/TUI) がリモートゲートウェイを指している場合、セッションストア + ワークスペースはリモートホストが所有します。
  • あなたのラップトップを移行しても、リモートゲートウェイの状態は移動しません。

リモートモードの場合は、ゲートウェイホストを移行してください。

落とし穴: バックアップ内のシークレット

$OPENCLAW_STATE_DIR にはシークレット (APIキー、OAuthトークン、WhatsApp認証情報) が含まれています。バックアップは本番シークレットとして扱ってください:

  • 暗号化して保存する
  • 安全でないチャネルでの共有を避ける
  • 漏洩の疑いがある場合はキーをローテーションする

検証チェックリスト

新しいマシンで、以下を確認してください:

  • openclaw status がゲートウェイの実行中を示している
  • チャネルがまだ接続されている (例: WhatsApp が再ペアリングを必要としない)
  • ダッシュボードが開き、既存のセッションが表示される
  • ワークスペースファイル (メモリ、設定) が存在する

関連項目

アップデートアンインストール