gateway.token から gateway.auth.token へ移り、対話シェルでは新しいグローバル openclaw が見えているのに launchd は古いプレフィックスを指している、あるいは gateway.bind を lan に広げたのに認証が追いつかずゲートウェイが待受を拒否する、といったパターンです。本稿ではアップグレード前のスナップショット、openclaw doctor と openclaw gateway status --deep の順序、二重バイナリの是正、ポート 18789 向けの再現可能な ssh -L と Tailscale、gateway install --force が本当に触る範囲までを一枚のランブックにします。導入チェックリスト と 24 時間安定稼働 の記事と併せて読むと、導入からアップグレード、常駐までの運用ループが閉じます。2026 年アップグレード後に起きやすい五つの失敗：まずモデルを疑わない
最近の OpenClaw ビルドはローカルゲートウェイのバインドと認証ガードを厳しくしています。gateway.bind がループバックから外れたのに有効な gateway.auth.token が無いと、起動は早い段階で失敗します。対話ログインでは新しいグローバル openclaw が解決される一方で launchd が古いプレフィックスを指していると、doctor は緑でも RPC プローブだけ落ちる典型的な二重心拍になります。三つ目は廃止予定の gateway.token キーだけが残り、新スキーマが無視するためダッシュボードが 401 を繰り返すパターンです。四つ目は状態ディレクトリをエンタープライズ同期やネットワークホーム配下に置き、アップグレード時の書き込みとデーモン読み取りが競合するケースです。五つ目はアプリケーション層の認証が整う前に 18789 をインターネット側インターフェースに晒し、スキャナ騒音とモデルタイムアウトの誤認を誘発する状況です。
次の五つのチェックポイントは順序を強制します。バージョンとファイルを凍結してから温度や API キーに触ってください。初回オンボーディングが未完了なら、導入チェックリスト を先に完了させ、アップグレード専用の手順に戻ってください。
キーのズレ： npm は上がったが gateway.auth.token が plist から見えるプロファイルに届いておらず、ダッシュボードと CLI が別断片を読んでいる。
二重バイナリ： which openclaw と plist の最初の ProgramArguments が一致しない。新フィールドは片側にしか適用されない。
バインドと認証のペア不備： lan だがトークンが無くゲートウェイが終了。ログにはバインド拒否の型が出やすい。
ポート表に所有者が無い： 18789 がデバッグ残骸で占有され、クリーンアップまで EADDRINUSE が残る。
生インターネット露出： トンネルやエッジ ACL 前に信頼できないインターフェースで待受すると無意味なリトライが増える。
アップグレードはバイナリ・plist メタデータ・設定ファイルの三つを揃える整列問題として扱い、その後でトンネルか制御されたバインド戦略を選びます。
環境継承の落とし穴もあります。launchd ジョブは対話シェルに足したエクスポートを自動では取り込みません。対話セッションでトークンを生成しシェル rc にだけ書いた場合、デーモンは永遠に見えません。サービスが既に読む設定へ機密を置くか、パッケージがサポートする env-file フックを使い、再起動後に doctor でサービス側の見え方を確認するのが耐久パターンです。変更チケットには plist ラベルの横に期待する CLI の SHA かセマンバージョンを書き、次のアップグレードで人間実行と監督実行の差が静かに広がらないようにします。
複数エンジニアが一台のクラウド Mac を共有する実験環境では、ランブックに短いローテーション記録を足します。誰が最後に force を走らせたか、どのプロファイルがゲートウェイを所有するか、一時的なバインド変更を戻したかです。共有ホストは各人が自分の PATH を普遍だと仮定するため二重心拍が増幅されます。バイナリ・plist ラベル・待受アドレスの権威ある表が一つあれば、金曜夜の当て推量を減らせます。
さらに、クラウドイメージの再ベイク後に Node のグローバルプレフィックスと plist の期待が食い違うと、アップグレード当日だけ症状が出ます。ゴールデンイメージの変更ログと doctor の警告閾値をチケットに貼り、週次レビューで差分を見える化すると、リリース夜の単発調査が減ります。観測性の話は 24 時間安定稼働 の heartbeat 節と合わせると、導入記事のポート表と矛盾しません。
比較：ループバックのみ、LAN プラストークン、トンネル経由のダッシュボード
クラウド Mac では既定の姿勢はループバックに SSH のローカル転送か、ACL のきつい Tailnet を重ねることです。18789 をパブリックインターフェースに直接バインドする脅威モデルとは異なります。ランブックの一枚目に表を置けば、当番がバインド変更を場当たりで議論しなくて済みます。
| モード | 向いている用途 | 前提 | 鋭い角 |
|---|---|---|---|
| loopback | 単一エンジニアの SSH とローカルブラウザ | 既定で最も単純。トークンは任意 | インターネットからのヘルスチェックはトンネル無しでは失敗する |
| lan + token | 固定 RFC1918 帯での内部プローブ | gateway.auth.token と最小限のファイアウォール穴 | plist 環境にトークンが無いとサービスが空振りする |
| SSH -L / Tailscale | ゼロトラストエッジ越しの運用 | SSH 鍵ローテーションと MagicDNS の計画 | ローカルポート衝突。スリープ後の再接続スクリプト |
| シグナル | 健全なときの意味 | 悪いときに最初に疑うもの |
|---|---|---|
openclaw doctor | スキーマ・トークン・ポート・スーパーバイザの一貫性 | 旧キー、PATH、同期ロック |
openclaw gateway status | ランタイムと RPC プローブ要約 | プロセスは生きているが RPC 死、トークンズレ |
openclaw gateway status --deep | 重複インストールとユーザー対システムユニットの示唆 | 二重 launchd ジョブ、古い plist |
誰が実行し、どの設定が読まれ、どのアドレスが待受するかをトンネルの前に揃えないと、不一致をより多くのノート PCへ拡散するだけです。
上流の切り分けは openclaw status、openclaw gateway status、openclaw logs --follow、openclaw doctor から始めます。クラウドイメージではゴールデンイメージ更新後に Node と plist 期待が一致するかも記録します。
Tailscale と SSH トンネルは運用コストが違います。Tailscale は小規模チームでもホスト毎の SSH フラグを覚えずに済む DNS 名と ACL を与えますが、パッチと監査の別依存鎖を増やします。SSH のポート転送は地味で、コンプライアンスが動く部品を最小化したいときに有利です。両方を組み合わせるチームもいます。Tailscale で到達性、ゲートウェイはループバックバインド、ACL で LAN バインドの事故をアップグレード中に出さない、という構成です。トンネルが落ちたときの劣化挙動も文書化し、エージェントが死んだソケットを叩き続けないようにします。
容量計画も忘れません。OpenClaw を上げても巨大ツールチェーンのメモリ圧は消えません。ログに OOM がゲートウェイ再起動の隣に出るなら、認証失敗とは別チケットで捕捉します。本サイトのストレージとメモリの記事は、M4 Pro の余裕が安定に効くか、監督メタデータの整理だけで足りるかの判断材料になります。
MagicDNS の名前解決と社内 CA の信頼鎖がズレると、ブラウザだけ異常に見えることがあります。その場合もまずゲートウェイ本体のループバック疎通を切り、次にトンネル端のポート衝突を見ます。順序を逆にすると半日かかります。
トークン移行と二重心拍：スーパーバイザに編集内容を読ませる
~/.openclaw/openclaw.json に gateway.auth.token が既にあるのにダッシュボードが 401 を返すなら、十個目のトークンを発行する段階ではありません。launchd の作業ディレクトリと OPENCLAW_STATE_DIR が対話シェルと一致するか確認します。一部のクラウドイメージは自動化ユーザーとログインユーザーでホームが分かれ、plist が別アカウントを指すと cat ではトークンが見えるのにサービスには無いという錯覚が起きます。
doctor が新しい設定を古いバイナリが触ったと報告するなら、先に PATH を直し、意図したインストールからスーパーバイザメタデータを入れ直します。古いバイナリがまだ監督下にある間に config set を連打すると、メタバージョンガードが UI フィードバック無しで変異を拒否することがあります。
openclaw doctor openclaw config get gateway.auth.token openclaw gateway status --deep openclaw gateway install --force openclaw gateway restart
注： 変更窓では openclaw.json、plist ラベル、openclaw --version の出力を三つ組でスナップショットし、単独ファイル復元ではなく三つ組でロールバックします。
引き継ぎでは上記四コマンドの出力を 24 時間安定稼働 記事の heartbeat 節の隣に貼り、夜勤がポート調整のチャット伝説に頼らないようにします。
CI がイメージを焼くなら、ビルド後に非対話で doctor を走らせ、定義した閾値を超えた警告でパイプラインを落とすスモークを足します。アップグレード退行を左に寄せられます。スモーク成果物はイメージのバージョン文字列の隣に置き、火曜と木曜のビルド差分を SSH 考古学無しで比較できます。
ループバック健全性から安全なリモート 18789 までの六再現手順
サーバ上でループバックが既に動いている前提です。そうでなければオンボーディングとデーモンは 導入チェックリスト に戻してください。ネットワークの誤りが認証失敗に見えないようにしてからリモート経路を足します。
ローカル実証： ホストで http://127.0.0.1:18789/ または文書のヘルスパスへ curl し HTTP コードを記録する。
経路選択： 単一ノート PC なら ssh -L 18789:127.0.0.1:18789 user@cloud-mac。広いチームは Tailscale と ACL を評価する。
衝突解消： ローカル 18789 が埋まっているなら ssh -L 19000:127.0.0.1:18789 と高いローカルポートで閲覧する。
トークン整合： トンネルでもブラウザにはゲートウェイトークンが届く。値はボルトに置き、チャットに貼らない。
切断計画： autossh 等で無人ジョブがゲートウェイ消失を仮定しないようにする。
チケット化： バインドモード・トンネルコマンド・ポート所有者をリージョンと SKU と同じ変更記録に載せ、調達は監査可能な注文導線へ寄せる。
三つの本番ゲートと gateway install --force を正当化する条件
版印の一致： meta.lastTouchedVersion と openclaw --version が一緒に動く。意図的ダウングレードは別方針で、黙って force を乱用しない。
単一監督源： 既定はホストあたり一つのユーザレベルゲートウェイユニット。deep で重複が見えたら余分を無効化してから force。
force の境界： plist のポートと実設定が食い違うとき、または doctor が明示的にスーパーバイザ更新を求めるとき。機密ローテーションやセキュリティグループレビューの代替ではない。
警告： ログと doctor を読まずに force を連打すると、単純なポート衝突が再起動ループになり、障害窓が広がります。
同僚のノート PCをゲートウェイホストに借りるより、レンタブルな KVMNODE クラウド Mac に OpenClaw を固定すると、バイナリパス・plist ラベル・トークン・トンネルコマンドを一枚の変更記録に載せやすい です。ノート PCはスリープと OS アップグレードで時間を失います。観測性・アップグレード巻き戻し・更新を週次レビューに載せなければならないチームには、複数メトロから選べる専用ベアメタルの方が散在ハードより実行しやすい ことが多いです。選んだリージョンで短期レンタルしアップグレードとトンネルを検証し、価格ページとヘルプセンターを見ながら M4 Pro と長期を決め、注文ページで容量を取る流れが、リリース夜のチャット依頼より追跡しやすいです。