2026年 OpenClaw 大規模アップグレード実践：2026.3.22 破壊的変更後の doctor 修復、Plugin SDK 移行と OPENCLAW_* 環境変数対照（リモート Mac SSH で再現できる手順）
2026.3.22 系では設定・プラグイン・ランタイム検査の契約が厳格化されます。本稿ではリモート Mac への SSH セッションを前提に、アップグレード → doctor → カスタムプラグインの Plugin SDK 化 → OPENCLAW_* の整合まで、ヘッドレス運用が途切れない順序でまとめます。
2026.3.22 以降に壊れやすいポイント
多くのチームで次の 3 系統が衝突します。launchd／LaunchAgent が新しい環境変数を読まないまま、SDK 以前のフック面を狙う拡張が残っている、旧ビルドでは黙認されていた不完全設定が表に出る、というパターンです。初めて導入する場合は、 2026年 OpenClaw インストール経路はどう選ぶ？公式 install.sh・npm・Docker Compose の比較意思決定＋ヘッドレス Mac の SSH トラブルシュート で、再現性のあるプロビジョニングとヘッドレス前提の切り分けを先に押さえておくと安全です。
- doctor のゲート：プラグインのマニフェストや API プロファイルが欠けると、ヘルスチェックがフェイルクローズになります。
- プラグイン ABI：SDK バージョン未宣言のレガシー
extensions/*.jsはスキップされるか、明示的にエラーになります。 - 環境名前空間：非推奨名は既定の探索パスから外れ、マイナー間で安定が保証されるのは
OPENCLAW_*系です。
リモート Mac SSH での再現チェックリスト
最初は対話型 SSH セッションで一通り実行してください。CI など非対話シェルはプロファイルを読まず、macOS サービスや cron と同じく環境変数が落ちる典型原因になります。専有ノードを Runner 化する場合は、 2026年 GitHub Actions セルフホスト macOS Runner 運用の意思決定：Runner 最低バージョン、登録／サービス化のトラブルシュート、専有リモート Mac ノード選定マトリクス の観点と併せて、ログインユーザと LaunchAgent の所有者を揃えてください。
ssh user@your-mac— ホームが固定の自動化用ユーザを推奨します。- シェルを確認：
echo $SHELLと、デーモンが読むファイル（~/.zprofile/~/.bash_profile）を一致させます。 - ランタイムを固定：アップグレード前後で
openclaw --version（またはパッケージマネージャ相当）を記録します。 - インプレースで更新（npm、インストールスクリプト、tar など、当初の供給経路に合わせる）し、新しい SSH セッションを開いてから doctor を実行します。
OPENCLAW_*は、LaunchAgent のProgramArgumentsラッパがsourceするのと同一ファイルに記述します。
doctor：想定される修復と順序
openclaw doctor（または配布物ドキュメントのヘルス系サブコマンド）を正とします。自動マイグレーション適用の前後で、計 2 回実行するのが扱いやすいです。
典型的な修復シーケンス
- プラグインの「マニフェスト欠落」を解消 — SDK バージョン、権限、エントリモジュールパスを揃えます。
- API プロファイルを修復 — ベース URL、既定モデル ID、シークレット参照を新スキーマに合わせます。
- アップグレードで状態が
~/.openclaw配下へ移った場合はデータディレクトリを再リンクします（公式手順に従って調整）。 - レポートがクリーンになるまで doctor を繰り返し、その後に launchd サービスを再起動します。
Plugin SDK 移行（実務的なカットオーバー）
各カスタム連携を Plugin SDK パッケージへ移します。sdk バージョンの宣言、ランタイムが期待するライフサイクル（activate、ツール登録、teardown 等）、Node 製ツールならプラグイン側 package.json で依存を固定します。
- レガシーロジックを
src/index.ts（または.js）へ移し、SDK のアダプタ型に合わせます。 - 直接のファイルシステム前提はやめ、ホストから注入されるワークスペースハンドルを使います。
- 本番エージェントと同一ユーザ・同一 env ファイルで、SSH 越しにヘッドレス実行する結合テストを足します。
OPENCLAW_* 環境変数対照（チートシート）
以下は 2026 年統一プレフィックスに沿った名称です。値は例示です。非推奨エイリアスは旧 launchd plist を grep するときの目印として併記します。
| 変数 | 役割 | 例／メモ |
|---|---|---|
OPENCLAW_HOME |
状態・設定のルート | ~/.openclaw — OPENCLAW_CONFIG_DIR のみに散らしていた構成の置き換え先 |
OPENCLAW_API_PROFILE |
既定の LLM プロファイル ID | production-east |
OPENCLAW_LOG_LEVEL |
デーモン詳細度 | アップグレード直後の調査は info / debug |
OPENCLAW_PLUGIN_PATH |
追加プラグインルート | コロン区切り。SDK パッケージは宣言したルート配下に置く |
OPENCLAW_DISABLE_TELEMETRY |
プライバシー | 規制ホストでは 1 |
OPENCLAW_SSH_BIND |
リバーストンネル／ローカル bind | 127.0.0.1:18765 — Mac mini 側ファイアウォールと整合 |
env を編集したあとは、launchctl kickstart -k gui/$(id -u)/com.your.openclaw（ラベルは環境に合わせる）や、システム設定からユーザエージェントを再起動します。必ず OpenClaw データディレクトリを所有する同一 macOS ユーザで操作してください。
ロールバックの姿勢
OPENCLAW_HOME の tarball と、直前のバイナリまたは npm プレフィックスを残します。doctor で状態を整合できない場合はディレクトリを戻し旧版を再インストールし、SDK マニフェスト検査に落ちる最小プラグインを再現ケースとして添えると修正が早いです。
このアップグレード経路でリモート Mac mini が有利な理由
OpenClaw の更新は長寿命プロセスと POSIX 環境の一貫性に敏感です。macOS はネイティブな Unix ユーザランドと LaunchAgent のパスが読みやすく、Apple Silicon の性能をノート PC の発熱なしに 24 時間回せます。Mac mini M4 は待機電力が非常に低く、SSH 接続・doctor 実行・プラグインビルドをいつでも受け付ける専用ノードとして、破壊的マイグレーションの試行錯誤に向いています。
Gatekeeper・SIP・FileVault は一般的な Windows 自動化ホストより攻撃面を抑え、ユニファイドメモリはマルチツールエージェント負荷でも応答性を保ちやすいです。本文の手順を最も摩擦なく回すなら Mac mini M4 はコストパフォーマンスに優れた選択肢のひとつです。 SSHMac のトップページでプランを確認し、マネージドなリモート Mac 運用と組み合わせてください。