Node Connect は何をしますか？
目標: 1つの特定のクライアントを1つの特定のGatewayに対して修正し、そのクライアントの新しい接続が正常に行えることを証明する。
1. 対象を固定する
何かを変更する前に、対象の環境/プロファイル、OpenClawバイナリ、設定/状態ルート、Gateway URL/ポート、およびサービスを記録する。
- すべての設定、ログ、サービス、デバイス、ノードコマンドには、名前付きデプロイメントラッパー/プロファイルを使用する。
- 裸の
openclaw、証明環境、または同名のデプロイメントにドリフトしてはならない。 - グローバル実行可能ファイルが古い場合は、その所有者を通じて対象を呼び出す。
- ステータス、設定、ログ、プロセスIDが同じGatewayを記述していることを確認する。
ペアリングや認証を変更する前に、対象のGatewayを特定する。
2. クライアントを分類する
コマンドを選択する前に、リクエストとGatewayログから分類する:
- Control UIブラウザ: ユーザーがブラウザ、ダッシュボード、Control UI、またはウェブチャットと言う。ログには
client=openclaw-control-uiまたはmode=webchatが表示される。 - ネイティブモバイル/ノード: 公式アプリが「接続」、「QRスキャン」、またはセットアップコードを表示する。ログ/リクエストメタデータにネイティブクライアントまたは
role=nodeが表示される。
電話はどちらのクライアントにもなり得る。電話のブラウザに対して openclaw qr や openclaw nodes status を使用してはならない。これらはネイティブモバイル/ノードのペアリングに属する。
3. 失敗する試行を観察する
ロックされた対象に対して以下を実行する:
openclaw gateway status --deep
openclaw logs --follow --json
openclaw devices list
openclaw config get gateway.mode
openclaw config get gateway.bind
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.allowTailscale
openclaw config get gateway.tailscale.mode
ログがライブの状態で、クライアントに一度再試行させる。そのクライアントID、モード、プラットフォーム、アドレス、認証結果、デバイスID、ユーザー、クローズコードを相関させる。他のペアリング済みデバイスは無視する。
最初の失敗遷移を解釈する:
- Gatewayの試行が一致しない: ルート、DNS、TLS、オリジン、またはプロキシの問題。
token_missing、password_missing、不一致、またはTailscale IDの失敗: 認証はペアリング前に失敗している。そのため、保留リストが空であることは想定内。pairing required: ルートと認証は成功。正確な保留リクエストを承認する。client connected:conn、client、mode、roleを該当クライアントに一致させる。アドミッションはhello応答の前に行われる。その後1006が続く場合、認証/ペアリングを保持し、hello配信、ライフサイクル、トランスポート、プロキシ、または再接続を調査する。古いビルドではauthenticated user connected/webchat connectedレコードが重複して出力され、エフェメラルクライアントが省略される場合がある。- 対応するアプリケーションレベルのアドミッションレコードがない
1006は、認証/ペアリングを証明しない。より前のハンドシェイク遷移を調査する。
4. ルートを証明する
トポロジーを1つ選択する: 同一マシン、LAN、tailnet、またはパブリックリバースプロキシ。これらを混在させてはならない。
- ブラウザのControl UIには、ブラウザデバイスIDのためにHTTPSまたはlocalhostが必要。リモートの平文HTTP Tailnet/LAN URLは有効な代替手段ではない。
gateway.tailscale.mode=offは、OpenClawがServe/Funnelを管理していないことを意味する。Tailscaleまたは外部管理のServeルートが存在しないことを証明するものではない。- Tailscaleが関与する場合、OpenClawの設定から推測するのではなく、ライブ状態を調査する:
tailscale status --json
tailscale serve status --json
クライアントのURLを、ロックされたGatewayに到達するリスナー/プロキシルートと一致させる。
5A. Control UIブラウザレーン
ペアリングリクエストを探す前に、ブラウザ認証を復元する:
- トークン/パスワード認証の場合、Control UIの設定に資格情報を入力する。永続的なシークレットをチャット、ログ、またはURLに入れてはならない。
- Gatewayホスト上の
openclaw dashboardを、ワンタイム署名ハンドオフのために優先的に使用する。オペレーターがそのホストのクリップボードを取得できる場合にのみ--no-openを使用し、ホストのブラウザ/クリップボードをエージェントツールの外に保つ。dashboard --jsonをキャプチャしてはならない。これはハンドオフと共有資格情報を公開する可能性がある。ループバックハンドオフURLをリモート電話に中継、書き換え、または送信してはならない。 - Tailscale Serveの場合、ライブルートと転送されたIDを確認する。意図した信頼境界に対してのみ
gateway.auth.allowTailscaleを有効にする。ブラウザデバイスIDで検証されたTailscale Control UI認証は、ペアリングをスキップできる。
認証が成功した後:
- 再試行する。認証前の試行からペアリングを推測してはならない。トークン/パスワード認証は
pairing requiredを明らかにすることがある。検証されたTailscale IDはそれをスキップできる。 - ログに
pairing requiredと表示された場合、デバイスを再度リストし、正確なリクエストIDを承認する。 - 検証されたTailscape接続が成功した場合、保留中またはペアリング済みデバイスの行が正しく作成されないことがある。
- 繰り返し
1006が発生した後は、認証/ペアリングを保持し、再接続の証拠を調査する。
5B. ネイティブモバイル/ノードレーン
セットアップ資格情報を公開せずに、ロックされた対象を介してネイティブルートを調査する:
openclaw qr --json | jq '{gatewayUrl, gatewayUrls, auth, access, accessDowngraded, urlSource}'
リモートGatewayを制御するCLIの場合は、--json の前に --remote を追加する。これにより gateway.remote.url とリモート資格情報が選択される。難読化フィルタが利用できない場合、生のQR JSONをエージェントから見える出力で実行してはならない。
gatewayUrl と urlSource を確認する。セットアップコードはパスワードと同等である。オペレーターに Control UI → デバイス → デバイスをペアリング からコピーさせるか、エージェントツールの外にあるターミナルで openclaw qr --setup-code-only を実行し、公式アプリに直接貼り付けさせる。エージェント/チャット/ツールの出力を介して中継してはならない。URL/認証の修正または期限切れの後は、新しいコードを生成する。
アプリが pairing required を報告した場合:
openclaw devices list
openclaw devices approve --latest # プレビューのみ。承認なしで終了。
openclaw devices approve <requestId>
openclaw nodes status
--latest は現在のリクエストをプレビューするだけであり、承認と見なしてはならない。正確なIDコマンドの直前に再度リストする。なぜなら、再試行によってリクエストが置き換えられる可能性があるからです。位置、経過時間、または類似性によって承認してはならない。
6. 相関させて終了する
承認前に、利用可能なリクエスト、デバイス/公開鍵、クライアント、モード/ロール、プラットフォーム、アドレス、ユーザー、再試行時刻の情報を一致させる。
以下のすべての該当チェックが最新の変更後に行われた新しい試行によって証明された場合のみ、成功を宣言する:
- 該当クライアントがロックされたGatewayに到達すること。
- 意図した認証が成功すること。
- ブラウザが初期リクエストを完了するか、ネイティブノードが
openclaw nodes statusに表示されること。 - 承認に正確なリクエストIDが使用されたこと。
- 直後に認証、ペアリング、または再接続の失敗がないこと。
QR/セットアップコード、起動されたブラウザ、空の保留リスト、承認、ペアリング済みデバイス数、またはTailscale pingは、1つの遷移のみを証明する。
診断結果、選択されたルート/認証レーン、該当クライアントの証拠、および残っている失敗遷移を報告する。