既に OpenClaw 旧版を使っていて 2026.3.x へアップグレードしたいが、設定の互換性が心配？2026.3.x ではデフォルトの設定ロジック（tools.profile、ACP dispatch など）が変更され、旧チュートリアルの書き方が効かなくなることがあります。本稿では移行する理由、アップグレード前に必須のバックアップと確認、5 ステップの移行フロー（インストール/アップグレード → onboard ウィザード → API と権限 → デーモン → 検証）、および権限の巻き戻し・ポート競合・環境変数など VNC リモート Mac でのよくある落とし穴と FAQ を説明し、一度で通すためのポイントをまとめます。
① 2026.3.x でなぜ移行が必要？旧チュートリアルと主な変更点
2026.3.x ではセキュリティとデフォルト動作が厳格化されています。新規インストール時は tools.profile がデフォルトで messaging（メッセージ/セッション系ツールのみ）になり、ファイル読み書きやターミナル実行に依存しているとアップグレード後に「権限なし」になります。ACP の dispatch はデフォルト有効で、マルチエージェントのルーティングが変わる可能性があり、プラグインの HTTP 登録方法も変更されています。そのため旧設定のままや旧チュートリアルのコピペでは、アップグレード後に動かなくなりがちです。
| 変更項目 | 旧版での一般的な状態 | 2026.3.x デフォルト/推奨 |
|---|---|---|
| tools.profile | 未設定または coding/full | 新規インストール時は messaging；読み書き/実行が必要な場合は coding または full に変更 |
| acp.dispatch | 多くの場合未設定 | デフォルト enabled；/acp のみで自動ルーティング不要なら無効化可 |
| プラグイン HTTP 登録 | registerHttpHandler など | 登録の挙動が変更；プラグインのコードとドキュメントを確認 |
② アップグレード前に必須：バックアップ・バージョン確認・依存関係確認
次の 3 つをアップグレード前に済ませておくと、失敗や設定消失からの復旧がしやすくなります。
設定とワークスペースのバックアップ
~/.openclaw/openclaw.json と ~/.openclaw/workspace/ を安全な場所にコピー。別マシンへ移行する場合は両方コピーしたうえで openclaw doctor と openclaw gateway restart を実行。
バージョンと依存関係
Node バージョン（20 以上推奨）を確認；openclaw doctor で移行・修復；openclaw config validate で設定の文法を確認。
現在の tools と ACP の確認
openclaw config get tools で現在の profile を確認；ACP を使っている場合は acp.dispatch.enabled が想定どおりか確認。
③ 5 ステップ移行：インストール/アップグレード → onboard ウィザード → API と権限 → デーモン → 検証
ステップ 1：npm install -g openclaw@latest または公式インストールスクリプトで 2026.3.x にアップグレード。
ステップ 2：openclaw onboard で設定ウィザードを起動し、利用形態（個人/チーム）、インストール種別（QuickStart など）、AI モデルと API（OpenAI/Claude/サードパーティ）を選択。
ステップ 3：~/.openclaw/openclaw.json で tools.profile を coding（通常のファイル・実行）または full に設定または確認；ACP の自動ルーティングを止める場合は acp.dispatch.enabled: false を設定。
ステップ 4：daemon/LaunchAgent を使う場合は openclaw onboard --install-daemon を実行するかドキュメントに従ってデーモンを設定し、plist/環境変数に正しい PATH と API 関連変数が含まれるようにする。
ステップ 5：openclaw gateway restart のあと openclaw health でサービスが起動していることを確認；リモート Mac では VNC でデスクトップに接続して一通り操作し、未処理の権限ダイアログがないことを確認することを推奨。
④ よくある落とし穴：権限巻き戻し・ポート競合・環境変数・VNC リモート Mac
権限の巻き戻し：アップグレード後に「読み/書き/実行の権限なし」になる場合は、tools.profile が messaging になっていることが多い。coding または full に戻して gateway を再起動。
ポート競合：ポート使用中と出たら lsof -i :ポート番号 でプロセスを確認し、終了するか設定で別ポートに変更。
環境変数：launchd や PM2 で起動する場合は、plist や ecosystem で PATH と API 関連変数を明示的に設定する。そうしないと対話ターミナルでは動いてもバックグラウンドサービスでエラーになることがあります。
VNC リモート Mac：アップグレードと初回認証時は必ず VNC でデスクトップに接続し、システムの権限ダイアログや Keychain を処理できるようにする。アップグレード後は SSH で自動化してもよい。SSH のみの環境でアップグレードするとダイアログをクリックできず止まることがあります。
openclaw doctor を実行して移行・修復を適用することを推奨；別マシンへ移行する場合は ~/.openclaw/ と ~/.openclaw/workspace/ の両方をコピーすると設定・チャネル状態・認証情報を維持できます。⑤ FAQ：ロールバック・マルチインスタンス・当サイトのトラブルシュート記事へのリンク
ロールバックするには？ openclaw.json とワークスペースのバックアップがあれば、復元して旧版の npm パッケージをインストールし、サービスを再起動。バックアップがなければ新しい挙動に合わせて再設定が必要です。
マルチインスタンスの移行は？ インスタンスごとに設定ディレクトリが別；それぞれバックアップして個別にアップグレード・検証し、ポートと profile を区別して設定。
当サイトの関連記事：インストール失敗や実行エラーは《OpenClaw よくあるエラーとトラブルシュート》を参照；リモート Mac で認証ダイアログを扱う場合は《OpenClaw グラフィカル認証と安全隔離》；環境選定は《OpenClaw v2026.3.7 環境選型》を参照。
結び：リモート Mac で OpenClaw をアップグレードするなら VNC 環境がおすすめな理由
2026.3.x の設定移行では「初回実行」やシステム権限・Keychain のダイアログが複数回出ることがあり、SSH だけではそれらをクリックできず途中で止まることがあります。VNC のリモート Macなら、onboard の完了、ダイアログの処理、openclaw health やログの確認をローカルと同様に行え、アップグレードの流れが明確で障害対応も早くなります。「アップグレード後に起動しない」「権限が合わない」の繰り返しを減らしたいなら、VNCMac のリモート Mac ノードでアップグレードと検証を行い、必要に応じて SSH で日常の自動化をする構成が、安定していて時間の節約にもなります。