変更メモ、意思決定マトリックス、8 ステップのランブック、チケットライン、VNC コンソール
OpenClaw v2026.4.25プラグインの起動をコールド永続レジストリ: 起動時に、エージェントは拡張機能ツリー全体をたどるのではなく、厳選されたメタデータを読み取ります。これにより、インストールと更新の動作がより予測可能になりますが、新しい障害モードが発生します。オペレータは参照します空に見えるプラグイン ペイン、アップグレード後の長い最初のコールド スタート、npm グローバル ビルド ID とゲートウェイ UI の間のドリフト。リリースノートでもこう呼びかけています強化のインストールと更新プラス混合バージョンのゲートウェイの検証—つまり、CLI、ゲートウェイプロセス、および launchd plist 内のパッケージパス同じバージョンのストーリーを伝える必要があります。この記事は、v2026.4.25 チャネル ペアリングとゲートウェイの安全性ガイド: QR と Mission Control をクリティカル パスから遠ざけながら、プラグイン プレーンの安定性に重点を置いています。と一緒にお読みください段階的リリース操作、Docker Compose の公式ウォークスルー、v2026.4.5 破壊的アップグレードランブックとよくあるエラーこれにより、「IM チャネルは緑色」と「拡張機能レジストリは正常」を区別できるようになります。
「コールド レジストリ」、「メタデータ修復」、および「混合バージョン検証」というフレーズは、測定可能な動作を説明します。まず、起動はコールドリードです。ディスク上のインデックスが半分移行されている場合、「レジストリが破損しています」というエラー行は表示されません。特に小型 SSD と共同テナント I/O を備えたリモート Mac では、Node がインデックスを再構築している間、空白のプラグイン画面が表示されたり、数分間停止したりすることがあります。第 2 に、インストール パスはローカル インストール メタデータに依存するようになりました。それは部分的な npm ダウンロードに耐える必要があります。 tarball が途中で停止すると、プラグイン行にバージョン ラベルが付いているものの、実行可能なバイナリが残らない可能性があります。これはまさに、次のような種類のバグです。openclaw plugins repairおよび関連する再インデックス コマンドは、対処することを目的としています。3 番目に、バージョンの混在は実行時のトポロジの問題です。シェルの CLI は次のように解決される可能性があります。/opt/homebrew/...launchd がポイントを維持している間ProgramArguments年上の人でdist/index.jsまたは、Docker コンテナーが、修復を実行したばかりのホストとは異なる構成ルートをマウントします。これらのパスが収束するまで、ポート 18789 のコンソールは、インストールしたと思われるビルドとは異なるビルドを読み取ります。
以下の 5 つの項目は、チームが証拠収集をスキップして「すべてを再インストールする」ことにジャンプした場合にチケットに表示される項目です。これらを非表示コストセクションとして変更リクエストにコピーできます。
コールドスタートスパイク:最初の完全なインデックスまたは修復パスにより、CPU とノードのイベント ループが固定される可能性があります。ノイズの多い隣接ディスクを備えた 32 GB のリモート インスタンスでは、プロセスがまだシャード ファイルを書き換えているにもかかわらず、セッションがハングしているように見えます。
半分インストールされているプラグイン:バンドルの取得中にネットワークが切断されると、欠落しているネイティブ モジュールを参照するマニフェスト行が作成される可能性があり、修復によってツリーが調整されるまで、UI には「バージョンは既知、有効化スイッチは何も行われません」として表示されます。
複数のインストール ルート:自作/opt/homebrew、 遺産/usr/local、チェックインnode_modules開発者チェックアウト内のツリーはすべて OpenClaw ビルドをホストできます。 launchd ジョブは依然として最も古いパスにバインドされている可能性があり、対話型シェルがすでに 4.25 である場合、ログに混合バージョンの警告が表示されます。
権限とサンドボックス:レジストリ キャッシュ ディレクトリにファイルを作成できないヘルパーは、鮮明な EPERM ではなく、一般的な「プラグインのロードに失敗しました」というログを記録することが多いため、macOS 上の長期間有効なエージェントの場合と同じ TCC と所有権パスが必要になります。これをリモート Mac TCC チェックリスト症状が UI 表面に触れるオートメーションに関係している場合。
チャンネルの健全性はプラグインの健全性ではありません。IM QR パスが成功すると、1 つのコネクタへの配信が証明されます。それはありますないレジストリとゲートウェイが同意していることを証明します。拡張機能がサイレントに失敗する間に「運用準備完了」チケットをクローズしないように、別の作業項目でこれらの承認行に署名します。
コールドレジストリの特典再現可能な設置面。 Docker は、ノード エンジンと openclaw パッケージを 1 つのイメージ レイヤーに固定できますが、ホスト上で修復してコンテナーに古いボリュームを読み取らせると、ホストにマウントをバインドすると混合ルートが再導入される可能性があります。ベアメタルnpm install -gロールフォワードは迅速ですが、規律が求められます。すべての修理、ドクター ラン、および plist 編集では、同じ macOS ユーザー最終的には 18789 UI が表示されます。そうでない場合、ディスク上のレジストリとユーザーごとのキャッシュが分岐します。このテーブルを変更レコードの添付ファイルとして使用します。これは、インシデントがモデルの停止ではなく、ボリュームの不一致であったことを証明する最速の方法でもあります。
| 寸法 | ベアメタル npm または pnpm | Docker Compose | よくある誤読 |
|---|---|---|---|
| バージョンの調整 | launchd、PATH、およびシェルの初期化ファイルに依存します | イメージタグとマウントされた構成ディレクトリに依存します | チェックのみopenclaw --versionSSH セッションでは、ライブ ゲートウェイと一致することはありませんargv |
| 修復シナリオ | 適切なホストレジストリ上で動作します | 同じボリューム上のコンテナ内で同等のコマンドを実行する必要がある | コンテナがイメージ内のフリーズしたパスを指している間にホストで修復する |
| ロールバック速度 | 既知の tarball を復元し、サーバーを高速にロックします | 画像にタグを付け直し、docker compose up | スナップショットを使用せずにホストとイメージの両方をアップグレードし、2 つの不良レイヤーを一度にデバッグする |
| 可観測性 | macOS ログ ストリームとローカル ブラウザから 127.0.0.1:18789 | 追加docker logsおよびコンテナローカルカール | SSHtailただし、バンドル ハッシュを比較するために DevTools を開かないでください。 |
ルール：Gateway を起動するプロセスによって製品バージョンが定義されます。 CLI は単なる別のクライアントです。
この順序は意図的に厳密です。突然変異前の証拠。ホットトラフィックが発生している場合は、フリーズウィンドウを事前にアナウンスし、言語を借用してください。フリーズと例外操作ガイドのセクション。ディスクの空き領域をキャプチャします。コールド レジストリの作業は、APFS 上の空き領域が約 10 ～ 15 パーセント未満のものに影響されます。パッケージを変更した後は、必ずスレッド化してくださいopenclaw doctorまず、長時間実行されるサブコマンドに触れる前に、サポートが検索可能なものを取得します。リリースノートに修復動詞が記載されている場合は、組織で標準化されている動詞を使用してください。reindex, repair、またはその両方 - 部分的に成功しても混合メタデータが残るため、完全な stderr を保持します。
ゲートウェイのみを再起動する後CLI、plist、コンテナのエントリポイントが一致していると確信できます。新しいレジストリに対して古いプロセスを再起動すると、チームは破損のように見えるわかりにくいロック エラーを作成します。 HTTP サーフェスは、一貫したビルド文字列を公開する必要があります。/versionまたは、ログのバナー、UI の About ペイン、およびopenclaw --version。 3 つのうちのいずれかが異なっている場合、作業は完了していません。
バックアップ:OpenClaw 設定ルート、プラグイン データ ディレクトリ、および launchd plist をエクスポートします。記録openclaw --versionそして完全なゲートウェイargvからpsバンプの前。
フリーズさんはこう書いています。ウィンドウ中は自動的に一時停止しますskill updateジョブとアドホック プラグインは他のメンテナからインストールされるため、2 つの移行が交互に行われることはありません。
パッケージをバンプします。サポートされているチャネルを v2026.4.25 に移動します。グローバル npm については、確認してくださいwhich openclawそしてlaunchdProgramArguments同じプレフィックスを参照します。
医者を実行してください:プラグイン、レジストリ、またはゲートウェイの行を、タイミング警告も含めてそのままチケットに貼り付けます。
プラグインの修復またはインデックスの再作成を実行します。実時間とディスク書き込みを監視します。失敗した場合は、最後の 3 行のスクリーンショットではなく、完全な標準エラー出力を保持します。
ゲートウェイを再起動します。バージョンが一致している場合にのみ実行されるため、古いプロセスが新しいレイアウトに古いロックを保持することはありません。
混合バージョンの検証:CLI、HTTP バージョン エンドポイント、UI のバージョン情報またはフッター領域を比較します。
VNC の受け入れ:グラフィカルセッションで開くhttp://127.0.0.1:18789(または文書化されたトンネル)、拡張リスト、モデル認証カード、およびエラー ドロワーを検証します。変更内容にスクリーンショットを添付します。
mixed-version triage in three checks: 1) CLI: openclaw --version 2) Process: ps — note dist/index.js path in argv 3) UI: footer or About, plus response headers in DevTools for the gateway route
注記：Docker の場合、修復とドクターの実行場所 (ホストとホストの違い) を文書化します。docker compose exec) を Runbook に追加し、それを のボリューム レイアウトと一致させます。作成ガイドそのため、善意の SSH セッションではコンテナーが非同期化されません。
注意：バックアップなしで、週末にメジャー バージョンをジャンプしたり、SecretRef を書き換えたり、チャネル ルーティングを再構成したりしないでください。それが安全命令に抵触する場合、v2026.4.5 重大な変更記事では、より厳格な方法を選択してください。
SSH は引き続き次の用途に適したツールですdoctor, repair、構造化ログ。UI、ブラウザ拡張機能の同意、トグルが実際に持続するかどうかを制御しますlaunchd ジョブを所有する同じユーザーのデスクトップ セッションが依然として必要です。以下のグリッドは、VNC 上の 1 回のオンコール パスに合わせたサイズになっています。ネイティブ モジュールまたは不可解なロード エラーでスタックした場合は、よくある10のエラーパターンガイドに従ってキーワードをマップし、この Runbook のステップ 5 に戻って、2 回目のコールド スタートで障害が再現されるかどうかを確認します。
| チェック | 何をするか | 合格基準 |
|---|---|---|
| バージョントライアングル | CLI、プロセス argv、および 18789 の UI の About またはフッターを比較します。 | 3 つすべてに、出荷する予定の同じメジャーとマイナーが表示されます |
| プラグイン一覧 | コールド スタート後、拡張機能のページを一度開き、リストが安定するまで待ちます | カウントが変更前のベースラインと一致するか、デルタが変更レコードに文書化されます |
| モデル認可 | 依存する OAuth 更新パスをトリガーします。レート制限バナーに注意してください | タイムボックス内に無制限の 401 または 429 ループはありません |
| ディスクとI/O | まだ実行中の場合は、アクティビティ モニターを使用して再インデックス中の読み取り/書き込みを監視します。 | スパイクは減衰し、空き領域は安全マージンを超えたままになります |
| 回帰煙 | 最もリスクの低いチャネルに小規模なプローブを送信します | セクション 01 のように、チャンネルの健全性はプラグインの健全性とは別の項目です。 |
IM オンボーディング、18789 安全パターン、同じコントロール プレーンの隣にある SSH ポート転送。
読む →ラインをフリーズし、ラインをいつ解除するか、リリースがすぐに出荷される場合はツリーをロールバックします。
読む →ボリューム コントラクト、ポート 18789、および VNC ホスト上のコンテナ内の UI の検証。
読む →Doctor を実行し、修復またはインデックスを再作成して、バージョンが混在した状態ではないことを証明します。 Gateway をブラインドで再インストールすると、次のコールド スタートが延期されるだけで、古い plist またはボリュームが表示されるはずの差分は失われます。
launchd は依然として古いものを指していますdist対話型シェルが新しいグローバル インストールを使用している間、または Docker ホスト パスとコンテナー パスがバインド マウントの下で異なるツリーを参照しているときに、このエントリが表示されます。
CLI とログ、はい。コントロール サーフェスといくつかの macOS 権限には、引き続きグラフィカル セッションが必要です。ゲートウェイ プロセスと同じユーザー アカウントの VNC でセクション 05 テーブルを使用します。
コールド レジストリは、「起動するたびにツリー全体をスキャンする」ことと引き換えに、「インストール メタデータとバージョン ラインを所有する」ことになります。運用上のフォロースルーは、予測可能な I/O スパイクインデックスの再作成中、launchd プレフィックスと npm プレフィックス間の緊密な結合、 そして承認はブラウザセッションで発生する必要があります。。 SSH ログのみを読み取る場合、「チャネルは問題ありません」と「拡張子は問題ありません」を 1 つのチケットにマージすることになり、スタックの半分しか検証されていないときにゴーストを追いかけて何日も無駄にすることになります。
机の下の Mac には、スリープ、電源、Apple Silicon のサーマルを管理する人が依然として必要です。あSSH とスケジュールされた VNC の両方を備えたリースされたクラウド Mac誰かをクローゼットの棚に飛ばすことなく、18789 について 2 番目の目を得るには、多くの場合、この方法がよりクリーンな方法です。経済性とは、誰が深夜のドライブ交換やコロハンドを運ぶかということであり、OpenClaw が「簡単」かどうかではありません。
これらのチェックリストに沿ったプロジェクト スコープの Apple Silicon ノードをレンタルするには、次を使用します。VNCMac: のクラウドMac購入プランのページ、およびホームページ製品のコンテキストに合わせて。保管してくださいペアリングそしてドッカー記事は同じ実行フォルダー内にあるため、チーム全体がピクセルからプロセス リストまでの 1 つのマップを共有します。