OpenClaw gatewayのトラブルシューティング

高速トリアージのページで足りない場合、ドキュメントは詳細なgatewayランブックを案内します。これは修正方法を延々と並べたものではなく索引で、コマンドの順序、正常なgatewayが示すシグナル、固定アンカーを持つ6つの症状別ページで構成されています。最も役立つのは、アップグレード直後に壊れるものをまとめた短いリストです。以下がその全体像です。

コマンドの順序と6つのページ

• status、gateway status、log follow、doctor、channel probeの各コマンドをこの順で実行します。正常な状態とは、gateway statusで実行中のランタイム、okの接続プローブ、capability行が表示され、doctorがブロッキングとなる設定やサービスの問題を報告せず、probeがアカウントごとのトランスポートの状態をライブで表示し、対応している場合はworksまたはaudit okのマーカーが付くことです。
• 「アップデートとロールバック」は、アップデート、ダウングレード、スプリットブレイン状態のインストールによってgatewayが停止したままになったり、不整合を起こしたりしたケースを扱います。内容は、アップデート後の問題、準備済みモデルランタイムの公開タイムアウト、新しい設定に対するガード、検索パスの修正、サービスの再インストール、古いラッパーの削除、ロールバック後のプロトコル不一致です。「スキルとモデルプロバイダー」は、スキップされたスキルルート、長いコンテキストでのレート制限エラーとその対処（標準ウィンドウ、対象となる認証情報、フォールバックモデル）、ブロックされた上流の応答、そしてプローブには通るのにエージェントの実行に失敗するローカルのOpenAI互換バックエンドを扱います。
• 「エージェントの応答とコントロールインターフェース」は、ストレージエラーで失敗する実行、返信が届かない場合、ダッシュボードの接続性、接続と認証のシグネチャ（認証詳細コードの早見表と、connectチャレンジ、ペイロード署名、デバイスnonceの各ステップ）を扱います。「Gatewayのサービスとプロセス」は、起動しない、または動作し続けないサービス、ダッシュボードに触れるまで黙って停止するmacOSのgateway、重複したlaunch agentによるスーパーバイザーのループ、高いメモリ使用量での終了を扱います。
• 「設定の検証とプローブ」は、無効として拒否された設定（何が起きたのか、確認と修復、よくあるシグネチャと修正方法）と、gateway probeの警告を扱います。「チャネル配信とツール」は、接続済みなのにメッセージが流れないチャネル、スケジュール配信とハートビート配信、ツールが失敗するペアリング済みノード、ブラウザツールの失敗、プラグインと実行ファイルのシグネチャ、ブラウザセッションのシグネチャ、要素、スクリーンショット、アップロードのシグネチャを扱います。以前の単一ページにあった古いアンカーはすべて、今も新しい移動先に解決されます。

アップグレード後の不具合のほとんどは、設定のずれか、新たに適用されるようになった、より厳格なデフォルトによるものです。

アップグレード後に何かが壊れたら

索引には3つのチェックがそのまま載っています。1つ目は、認証とURLの上書きの挙動です。gatewayのモード、リモートURL、認証モードを確認してください。モードがremoteに設定されていると、ローカルのサービスは正常なのに、コマンドラインがリモートのgatewayを対象にしている場合があります。また、URLを明示した呼び出しは保存済みの認証情報にフォールバックしません。connect-failedのシグネチャはURLのターゲットが間違っていることを、unauthorizedのシグネチャはエンドポイントには到達できているものの認証が間違っていることを意味します。2つ目は、bindと認証のガードレールが厳しくなったことです。ループバック以外へのbindには有効な認証経路、つまり共有トークンかパスワード、または正しく設定された非ループバックの信頼済みプロキシが必要で、古いトークンキーは現在の認証トークンキーの代わりにはなりません。認証なしでのbindの拒否と、ランタイムが実行中なのに接続プローブが失敗する状態がそのシグネチャです。3つ目は、ペアリングとデバイスIDの状態です。デバイスとチャネルのペアリングを一覧表示し、ダッシュボードやノードの保留中のデバイス承認と、ポリシーやIDの変更後に保留になっている承認を探してください。device identity requiredとpairing requiredがそのシグネチャです。それでもサービスの設定とランタイムが一致しない場合は、同じプロファイルとstateディレクトリからサービスのメタデータを再インストールし、再起動します。

シグナルの読み方

• 実行中のランタイムと失敗した接続プローブという組み合わせは、最も多くを物語ります。プロセスは生きているのに、コマンドラインが現在のURLと認証ではそこに到達できないということなので、修正すべきはサービスではなく、モード、URL、トークンです。
• アップグレード後のdevice identity requiredのシグネチャは、クライアントのバグではありません。デバイス認証が強制されるようになり、ダッシュボードやノードに保留中の承認が必要になったということで、それはdevicesとpairingの一覧に表示されます。
• probeはアカウントごとに行われます。2つのアカウントを持つチャネルでは、一方のトランスポートが動作し、もう一方が失敗していることがあり、ステータス行だけではそれがわかりません。

トランスポートは接続しているのに挙動がおかしい場合については、チャネルレベルの姉妹記事であるOpenClawチャネルのトラブルシューティングを、この手順が頼りにしている修復コマンドについてはOpenClaw doctorをご覧ください。

なぜ索引なのか

ランブックを症状の領域ごとに分けることで、何かが停止している最中でも読み切れる短さに各ページを保てます。また、アンカーが保持されているため、古いスレッドやissueからのリンクも正しいセクションにたどり着きます。コマンドの順序も意図的です。最も広いシグナルから最も狭いシグナルへと進み、doctorがprobeより前にあるのは、probeが失敗として報告するはずの設定ミスをdoctorが修復するからです。3つ目のチェックで探す承認についてはOpenClawのペアリングで、最初の2つのチェックで確認するキーについてはOpenClawの設定で説明しています。

Dialiでは

Dialiでは、エンジンの設定がダッシュボードから生成され、リリースのたびに置き換えられるため、アップグレード後のセクションで説明されているずれの大部分がなくなります。また、同じ手順がホスト型エンジンでもそのまま使えます。ホスト型アシスタントについてはDialiのマネージドOpenClawホスティングで、その周囲の境界についてはDialiのセキュリティで説明しています。

• 5つのコマンドを順番に。ランタイムが実行中でprobeがokなら正常です。
• 症状別の6つのページ。古いアンカーはすべて今も有効です。
• アップグレード後は、モードとURL、bindと認証、ペアリング状態を確認します。