「OpenClaw が壊れた」に見える三つの痛み
チケットは多くが現象語りです。背後には次の三パターンが重なります。
1) 経路の不一致。 スクリプト・グローバル CLI・Compose が混在すると設定やキャッシュの場所がずれ、障害時に「どれをバックアップし、どのユニットが本物か」で割れます。
2) データ契約なき版上げ。 状態を持ち越さないとクリーン化に見え、戻し方がないと非互換スキーマで痛みます。データディレクトリは移行の第一面です。
3) 切り分け階段の飛ばし。 再インストール前に、プロセスとポート、ゲートウェイ HTTP、openclaw doctor、再現ログの順を踏んでください。マウント漏れを見ずに node_modules 削除へ進むと層が隠れます。
Node・ロック／ダイジェスト・設定 tarball を記録する。
方式選択マトリクス：試用ノート、チーム標準、本番ホスト
設計レビューと障害時の両方で参照してください。OS が違ってもリスクの型は似ています。
| 経路 | 向いている場面 | 主なリスク | 最低限の統制 |
|---|---|---|---|
| install.sh 系の整備フロー | 個人の初回成功、デモ、ゴールデンパスオンボーディング | リリース間でスクリプトの中身が不透明に変わる | URL かチェックサムで固定、標準出力をログ、設定ディレクトリをスナップショット |
| npm または pnpm の CLI 導入 | 高速イテレーション、モノレポエンジニア、CI エージェント | グローバルとローカル CLI の混同、Node ドリフト | Volta や fnm で Node 固定、非 root のサービスユーザー、リポにロックファイル |
| Docker Compose スタック | 本番との同型、ポートとボリュームの再現 | ボリュームマウント誤り、イメージタグの漂流 | 名前付きボリュームか所有権が文書化されたバインド、ダイジェスト固定 |
迷うなら境界明示を優先。本番と私用ユーザーを混ぜない。
install.sh：速さと、依然として必要な規律
スクリプトは手順を畳すが checksum・秘密・プロキシは自前。踏み台は profile 副作用に注意。
SHA-256 固定とログ。終了後 doctor と 18789 等への HTTP プローブ。
典型：権限、SSL、実行ユーザーと監視ユーザー不一致。
npm と pnpm：Node 固定、グローバル CLI の得失、権限衛生
Volta/fnm で Node 固定。pnpm はディスク、npm は学習コスト。専用ユーザーで分離。
ミラー・タイムアウトは runbook、which openclaw、doctor。グローバル禁止は安定 npx／ラッパー。
Docker Compose：ボリューム、ポート、再起動方針、資源の下限
マウント誤りと UID 不一致が主因。ボリューム文書化、.env はローテ対象。
最小公開、TLS はプロキシ、RAM 約 1.5 GiB 目安、再起動で復帰。
コンテナも同順；ヘルスは LB と整合。
切り分けコマンド例（ホストまたはコンテナ）
openclaw status
curl -sS -m 5 http://127.0.0.1:18789/health || echo "gateway probe failed"
openclaw doctor
openclaw health --json > /tmp/openclaw-health-$(date +%Y%m%d%H%M).json
openclaw logs --follow
ポートはプロキシに合わせ、順序はプロセス→HTTP→doctor→health→ログです。
アップグレード、ロールバック、切り分け順、ホスト型リモート Mac が効くとき
アップグレード前に設定・環境・トークン・高コストキャッシュを tarball、digest／ロックと併記。ステージングで doctor／health の後に載せ替え。
ロールバックは成果物復元と旧タグ再起動。スキーマ移行はノート確認。
障害は status→HTTP→doctor→ログ。
- npm ci 固着： 先にミラー、MTU、CPU 抑制を疑う。
- doctor 緑でもチャネル沈黙： ブリッジとトークンへ。UI だけ信じない。
- Compose 版上げでマウント破損： データ触る前にパスを diff。
まとめ： 三経路は速度・快適さ・再現性のトレードオフ。バックアップ、Node 固定、切り分け順が契約化されていれば失敗も静かです。
限界： スリープ端末、個人アカウント混在、無文書の手編集はパッケージ以前の支配的要因です。
SFTPMAC： ホスト型リモート Mac は常時電源・Apple ツール・SFTP／rsync 同居向き、スリープとドリフト抑制。
二日のハッカソンなら？
install.sh か副作用の少ない npm スクリプト。退場前に設定をスナップショット。
規制本番なら？
ダイジェスト固定 Compose、保管庫からのシークレット注入、名前付きボリュームの自動バックアップ。
環境変更のたび doctor？
はい。ログを無目的に追うより安いです。
ファイル同期の横で OpenClaw を安定ホストするなら、SFTPMAC のプランで基準を置いてください。