1. なぜバイナリ差し替えだけでは足りないか
~/.moltbot や旧プレフィックスが残ると ~/.openclaw と二重真実になります。doctor --fix は便利ですがチャネル署名やリバプロ変更は自動修復しません。認証 v2 はクライアント世代を揃えない限り「繋がった風」の沈黙を生みます。
2. 移行対照表
| 観点 | 以前 | 目標 |
|---|---|---|
| 状態ルート | ~/.moltbot 等 | ~/.openclaw + OPENCLAW_* |
| デーモン | 古いバイナリパス | plist の EnvironmentVariables を明示 |
| 認証 | v1 署名 | v2 nonce 揃え |
3. 五段階ランブック
- 状態・workspace・plist・バージョンをスナップショット。
doctorを fix なしで保存。- コピー環境で
--fixを試し diff を確認。 - シェル・CI・plist から旧プレフィックスを grep 除去。
- チャネル探針と最小 skill、失敗時は Gateway ロールバック記事へ。
4. 引用可能な閾値
- 同じ drift が 3 連続でチャネル接続を阻むなら、マイナー追従を止めディレクトリ移行を先に。
- 認証エラーが時間あたり 20% 超かつ単一ビルドに集中 → そのクライアントを v2 対応へ。
- plist と対話シェルで秘密鍵系
OPENCLAW_*が一つでも違えばゲート不合格。
5. リモート Mac / launchd 行列
| 症状 | 疑い | 対応 |
|---|---|---|
| 手動 OK / launchd NG | PATH やトークン未注入 | plist に明示書き込み |
| 一チャネルだけ無音 | Webhook 署名差分 | アップグレードノートで再ペア |
| skill EACCES | サンドボックス境界 | 公開面ハードニング記事と権限確認 |
6. FAQ
--fix は workspace を触る？ 設定ポインタを書き換える可能性があるため必ずスナップショット。
Docker は？ ホストとコンテナで真実源を一つに。bind-mount とホスト直編集を同時に続けると doctor --fix 実行中に競合します。
認証 v1 に一時退行できる？ 隔離ラボと廃止日付付きのみ。本番ではクライアント更新が正道です。
~/.moltbot をすぐ消していい？ 新ツリーに同等シークレットがあることとチャネル検証後に。 tarball は少なくとも一リリース周期保持。
doctor が緑でもチャネルが無音？ Webhook 配送ログと署名ヘッダを上流 SaaS 側で追う。doctor はローカル整合のみを見ます。
マイナー追従の頻度は？ 設定・認証に触れる記載があるたびに短い煙テストを。ドキュメントのみでも 1 チャネル＋1 skill は安い保険です。
7. 事例と深掘り
Slack だけ沈黙：plist の古いパス、.zshrc だけのトークン、署名ヘッダ不一致が重なった例。層を一つずつ直すより env 差分をゼロにした方が早い。
マイナー連続アップグレード向けの手順であり、大規模 2.0 移行は別記事の移行ランブックを先に完了させてください。
ステージング Mac で plist キーをミラーし、本番に触る前に doctor 差分を確定させるとユーザーへの再送を減らせます。
アップグレード直後はバインドアドレスとボリュームマウントを再確認。新デフォルトが公開面を狭めることがあります。
トークナイザ差分やプロキシタイムアウトも「ランダム無音」に見えるので、OpenClaw とセットで版を固定して記録してください。
変更チケットには解決済み openclaw バイナリのチェックサムを添付し、ロールバック時はパッケージ版だけでなく plist の実行パスも戻します。複数ユーザ機ではデーモンの UserName と鍵を持つアカウントがズレると認証が間欠的に失敗します。
Homebrew と npm グローバルが同居する場合、PATH の勝者を一つに決めてから doctor を実行。片方へ修正が入りもう一方が起動する分裂が起きやすいです。
8. 変更窓の観測セット
終了コード、チャネル探針成功率、skill コールドスタート中央値、認証失敗/時をセットで見る。四つ同時悪化はルート遷移、認証だけならクライアント行列。
ログに user-agent や端末 ID が出る場合は認証失敗をビルド別に束ねる。古いモバイルビルドがエラー大半を占め、サーバ退行と誤診しがちです。
| 信号 | 意味 | 次手 |
|---|---|---|
| 同じ欠落キーが連続 | ~/.openclaw への収束未完 | アップグレード停止し移行完了 |
| 対話 OK / デーモン NG | launchd 環境漂移 | plist とシェル env の差分 diff |
| 夜だけ失敗 | cron/launchd とログイン文脈のユーザー差 | 実行ユーザーと鍵可視性の照合 |
8.1 CI・ステージングと「latest」罠
CI で毎晩 npm i -g openclaw@latest を回して緑なら安全、は誤解です。ランナーの Node メジャー、既定シェルの PATH、成果物メタデータに解決 semver/digest が無いことが多い。CI でも本番と同じピンを貼り、絶対パス＋チェックサムをビルド成果に刻み、変更票はそれを引用してください。
本番と同じ Slack ワークスペースでステージング Gateway を動かすなら Bot かチャネルを分離。リハーサル中の webhook 誤配信が本番監査ログを汚します。本番 plist を複製して秘密と待受ポートだけ変え、同じ煙テストを通してください。ステージだけ EnvironmentVariables が増えたら「ステージを直す」のではなく本番へ構造を還流し漂移を解消します。
バージョン凍結中は OPENCLAW_CONFIG_ROOT の二重解釈を禁止し、plist か systemd drop-in の単一真実に寄せ、diff -u を票に添付します。
ヘルスチェック脚本も CLI 世代に合わせて更新し、ロールバック演習は前進と同じデータ（スナップショット・digest・探針）で実施します。
9. まとめ：Windows/Linux は分岐が増える
非 Mac ではサービス管理の層が増え、状態契約を凍結しない限り手戻りが膨らみます。リモート Apple Silicon Mac は launchd 例と創作自動化スタックの整合が取りやすく、検証工数を下げます。MACGPU は常駐検証向けリモート Mac を低摩擦で提供 — CTA はログイン不要。
認証 v2 移行直後は短命再接続が小さな VPS CPU を一時的に押し上げます。クライアント段階ロールアウトを制限するか、追従中だけホストを上げてください。
セキュリティレビューは doctor --fix が ACL を広げなかった証拠を求めがちです。敏感ディレクトリの ls -le 前後を変更記録に添付します。
10. インストール経路・Docker 本番との接続
npm グローバル、Compose、pnpm ソースはデータルートが異なります。どのチェーンを修復しているか先に固定し、パスを跨いだファイルコピーを避けます。
Compose がイメージ digest を固定しているなら、その digest も契約の一部。ホスト側 npm だけ上げてもコンテナ内焼き込み CLI は動きません。逆に ~/.openclaw を bind しつつホストでも同ツリーを編集すると fix 競合が出るので書き手を直列化するかステージングコピーを挟みます。
環境ごとに一枚の「アップグレードカード」：バイナリ絶対パス、plist ラベル、データルート、有効チャネル一覧。インシデント時の最初の添付はこれにします。
11. doctor が緑になった後の週次チェックリスト
ゼロ日：実トラフィック後にもう一度 doctor tarball を取得し、アップグレード前と diff。意図しないファイル移動があればリリースを止めます。一日目：デーモンアカウントと管理者アカウントの双方からチャネル探針。二日目：最も遅い skill を冷起動＋リトライで叩き、サンドボックス差分を先に炙ります。
三日目：認証エラーをクライアントビルド別に束ね、偏りがあれば強制更新枠を設定。四日目：バックアップとスナップショットの復元手順が現在の plist ラベルと一致するか確認。五日目：実行者とメトリクス監視者で短い振り返りを行い、アップグレードカードへ一行改善を残す。
環境はリスク順にずらし、段の間に少なくとも一昼夜の観測を挟みます。マーケ大型キャンペーンや四半期末フリーズは npm の公開日より優先して計画に入れます。
週が無事なら結果を doctor tarball と同じ場所にアーカイブ。フレークは担当と期限が決まるまでオープンに残します。
チェックリスト実行者をローテーションし、チェックリスト自体も VCS で版管理して成熟度の変化を diff で追えるようにします。