node-connect

Node Connect

目標：正確なクライアントを正確な Gateway に接続し、そのクライアントの新しい接続を検証します。

1. 接続先を固定する

変更を加える前に、接続先の環境／プロファイル、OpenClaw バイナリ、設定／状態のルート、Gateway URL／ポート、サービスを記録します。

• すべての設定、ログ、サービス、デバイス、ノードのコマンドでは、指定されたデプロイ用ラッパー／プロファイルを使用します。
• 素の openclaw、検証環境、または名前の似た別のデプロイに切り替えないでください。
• グローバルの実行ファイルが古い場合は、所有元を通じて接続先を指定して実行します。
• ステータス、設定、ログ、プロセスの識別情報が、すべて同じ Gateway を示していることを確認します。

ペアリングや認証を変更する前に、接続先の Gateway を特定します。

2. クライアントを分類する

コマンドを選ぶ前に、依頼内容と Gateway ログからクライアントを分類します。

• Control UI ブラウザー： ユーザーがブラウザー、ダッシュボード、Control UI、または WebChat と述べている場合。ログに client=openclaw-control-ui または mode=webchat と表示されます。
• ネイティブのモバイル／ノード： 公式アプリに Connect、Scan 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. ルートを検証する

同じマシン、LAN、テールネット、パブリックなリバースプロキシのいずれかを選びます。混在させないでください。

• ブラウザーの Control UI でデバイス ID を利用するには、HTTPS または localhost が必要です。リモートの HTTP（平文）テールネット／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 に記載しないでください。
• 1 回限りの署名付きハンドオフには、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 を承認します。
• 検証済みの Tailscale 接続が成功しても、保留中またはペアリング済みデバイスの行が作成されない場合があります。これは正常です。
• 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 → Devices → Pair device からコピーしてもらうか、エージェントのツール環境外のターミナルで openclaw qr --setup-code-only を実行し、公式アプリに直接貼り付けてもらいます。エージェント／チャット／ツールの出力を介して転送しないでください。URL／認証を修正した後や有効期限が切れた後は、新しいコードを生成します。

アプリに pairing required と表示された場合：

openclaw devices list
openclaw devices approve --latest   # preview only; exits without approval
openclaw devices approve <requestId>
openclaw nodes status

--latest は現在の要求をプレビューするだけであり、承認として扱ってはいけません。再試行によって要求が置き換わることがあるため、正確な ID を指定するコマンドを実行する直前に再一覧表示します。順番、経過時間、類似性に基づいて承認しないでください。

6. 照合して完了する

承認する前に、利用可能な要求、デバイス／公開鍵、クライアント、モード／ロール、プラットフォーム、アドレス、ユーザー、再試行時刻の情報を照合します。

最終変更後の新たな試行で、適用されるすべてのチェックに合格した場合にのみ、成功を宣言します。

• 正確なクライアントがロックされた Gateway に到達する。
• 意図した認証が成功する。
• ブラウザーが初期リクエストを完了する、またはネイティブノードが openclaw nodes status に表示される。
• 正確なリクエスト ID を使って承認する。
• その直後に認証、ペアリング、再接続の失敗が発生しない。

QR／セットアップコード、ブラウザーの起動、空の保留中リスト、承認、ペアリング済みデバイス数、Tailscale の ping は、それぞれ 1 つの遷移しか証明しません。

診断結果、選択した経路／認証方法、正確なクライアントで確認できた証拠、および未解決の失敗した遷移を報告します。