Gateway

• 既定では、~/.openclaw/openclaw.json に gateway.mode=local が設定されていない限り、Gateway は起動を拒否します。アドホック/開発用の実行には --allow-unconfigured を使用します。
• openclaw onboard --mode local と openclaw setup は gateway.mode=local を書き込む想定です。ファイルが存在するのに gateway.mode がない場合は、暗黙的にローカルモードとみなすのではなく、破損または上書きされた設定として扱い、修復してください。
• ファイルが存在し、gateway.mode がない場合、Gateway はそれを疑わしい設定破損として扱い、ユーザーの代わりに「ローカルと推測」することを拒否します。
• 認証なしでループバックを越えてバインドすることはブロックされます（安全ガードレール）。
• SIGUSR1 は、許可されている場合にプロセス内再起動をトリガーします（commands.restart は既定で有効です。手動再起動をブロックするには commands.restart: false を設定しますが、Gateway ツール/設定の適用/更新は引き続き許可されます）。
• SIGINT/SIGTERM ハンドラーは Gateway プロセスを停止しますが、カスタムの端末状態は復元しません。CLI を TUI や raw モード入力でラップする場合は、終了前に端末を復元してください。

• レコードは運用メタデータを保持します。イベント名、カウント、バイトサイズ、メモリ読み取り値、キュー/セッション状態、チャネル/Plugin 名、編集済みセッションサマリーです。チャットテキスト、Webhook 本文、ツール出力、生のリクエストまたはレスポンス本文、トークン、Cookie、シークレット値、ホスト名、生のセッション ID は保持しません。レコーダーを完全に無効化するには diagnostics.enabled: false を設定します。
• 致命的な Gateway 終了、シャットダウンタイムアウト、再起動時の起動失敗では、レコーダーにイベントがある場合、OpenClaw は同じ診断スナップショットを ~/.openclaw/logs/stability/openclaw-stability-*.json に書き込みます。最新バンドルは openclaw gateway stability --bundle latest で確認します。--limit、--type、--since-seq もバンドル出力に適用されます。

• gateway status は、ローカル CLI 設定がない場合や無効な場合でも、診断用に引き続き利用できます。
• デフォルトの gateway status は、サービス状態、WebSocket 接続、ハンドシェイク時に見える認証機能を証明します。読み取り/書き込み/管理操作は証明しません。
• 診断プローブは、初回デバイス認証に対して変更を加えません。既存のキャッシュ済みデバイストークンがある場合はそれを再利用しますが、ステータス確認のためだけに新しい CLI デバイス ID や読み取り専用デバイスのペアリングレコードを作成することはありません。
• gateway status は、可能な場合、プローブ認証用に設定済みの認証 SecretRefs を解決します。
• 必須の認証 SecretRef がこのコマンドパスで未解決の場合、プローブの接続性/認証が失敗すると gateway status --json は rpc.authWarning を報告します。--token/--password を明示的に渡すか、先にシークレットソースを解決してください。
• プローブが成功した場合、未解決の auth-ref 警告は誤検知を避けるため抑制されます。
• 待ち受け中のサービスだけでは不十分で、読み取りスコープの RPC 呼び出しも正常である必要があるスクリプトや自動化では、--require-rpc を使用してください。
• --deep は、追加の launchd/systemd/schtasks インストールをベストエフォートでスキャンします。複数の Gateway らしきサービスが検出された場合、人間向け出力にはクリーンアップのヒントが表示され、ほとんどのセットアップでは 1 台のマシンにつき 1 つの Gateway を実行すべきだと警告します。
• --deep は、サービスプロセスが外部 supervisor による再起動のため正常終了した場合に、最近の Gateway supervisor 再起動ハンドオフも報告します。
• --deep は Plugin 対応モード（pluginValidation: "full"）で設定検証を実行し、設定済み Plugin マニフェストの警告（たとえばチャンネル設定メタデータの欠落）を表示するため、インストールや更新のスモークチェックで検出できます。デフォルトの gateway status は、Plugin 検証をスキップする高速な読み取り専用パスを維持します。
• 人間向け出力には、解決済みのファイルログパスに加えて、CLI とサービスの設定パス/有効性のスナップショットが含まれ、プロファイルや state-dir のずれを診断しやすくします。

• Linux systemd インストールでは、サービス認証ずれチェックがユニットから Environment= と EnvironmentFile= の値の両方を読み取ります（%h、引用符付きパス、複数ファイル、省略可能な - ファイルを含む）。
• ずれチェックは、マージされたランタイム環境（まずサービスコマンド環境、次にプロセス環境のフォールバック）を使用して gateway.auth.token SecretRefs を解決します。
• トークン認証が実質的に有効ではない場合（明示的な gateway.auth.mode が password/none/trusted-proxy、または mode が未設定でパスワードが優先され得るうえ、勝てるトークン候補がない場合）、トークンずれチェックは設定トークンの解決をスキップします。

• Reachable: yes は、少なくとも 1 つの対象が WebSocket 接続を受け入れたことを意味します。
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only は、認証についてプローブが証明できた内容を報告します。到達可能性とは別です。
• Read probe: ok は、読み取りスコープの詳細 RPC 呼び出し（health/status/system-presence/config.get）も成功したことを意味します。
• Read probe: limited - missing scope: operator.read は、接続は成功したが読み取りスコープの RPC が制限されていることを意味します。これは完全な失敗ではなく、劣化した 到達可能性として報告されます。
• Connect: ok の後の Read probe: failed は、Gateway が WebSocket 接続を受け入れたものの、後続の読み取り診断がタイムアウトしたか失敗したことを意味します。これも到達不能な Gateway ではなく、劣化した 到達可能性です。
• gateway status と同様に、probe は既存のキャッシュ済みデバイス認証を再利用しますが、初回デバイス ID やペアリング状態は作成しません。
• 終了コードが 0 以外になるのは、プローブ対象のどれにも到達できない場合だけです。

トップレベル:

• ok: 少なくとも 1 つの対象に到達できます。
• degraded: 少なくとも 1 つの対象が接続を受け入れたものの、完全な詳細 RPC 診断を完了しませんでした。
• capability: 到達可能な対象全体で見つかった最良の機能（read_only、write_capable、admin_capable、pairing_pending、connected_no_operator_scope、または unknown）。
• primaryTargetId: アクティブな勝者として扱う最良の対象。優先順は、明示的な URL、SSH トンネル、設定済みリモート、local loopback です。
• warnings[]: code、message、任意の targetIds を持つベストエフォートの警告レコード。
• network: 現在の設定とホストネットワークから導出された local loopback/tailnet URL のヒント。
• discovery.timeoutMs と discovery.count: このプローブパスで使用された実際の検出予算/結果数。

対象ごと（targets[].connect）:

• ok: 接続後の到達可能性 + 劣化分類。
• rpcOk: 完全な詳細 RPC の成功。
• scopeLimited: 必要な operator スコープがないため詳細 RPC が失敗しました。

対象ごと（targets[].auth）:

• role: 利用可能な場合、hello-ok で報告された認証ロール。
• scopes: 利用可能な場合、hello-ok で報告された付与済みスコープ。
• capability: その対象について表示される認証機能の分類。

• ssh_tunnel_failed: SSH トンネルのセットアップに失敗しました。コマンドは直接プローブにフォールバックしました。
• multiple_gateways: 複数の対象に到達できました。レスキュー bot など、分離されたプロファイルを意図的に実行している場合を除き、これは通常ではありません。
• auth_secretref_unresolved: 設定済みの認証 SecretRef を、失敗した対象向けに解決できませんでした。
• probe_scope_limited: WebSocket 接続は成功しましたが、読み取りプローブが operator.read の欠落により制限されました。

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun>, --token, --wrapper <path>, --force, --json
• gateway restart: --safe, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start: --json
• gateway stop: --disable, --json

• 管理対象サービスを再起動するには gateway restart を使用します。再起動の代替として gateway stop と gateway start を連結しないでください。
• macOS では、gateway stop はデフォルトで launchctl bootout を使用します。これにより、無効化を永続化せずに現在のブートセッションから LaunchAgent が削除されます。KeepAlive の自動復旧は今後のクラッシュに対して引き続き有効で、gateway start は手動の launchctl enable なしで正常に再有効化します。Gateway が次の明示的な gateway start まで再起動しないよう、KeepAlive と RunAtLoad を永続的に抑制するには --disable を渡します。手動停止を再起動やシステム再起動後も維持する必要がある場合に使用してください。
• gateway restart --safe は、実行中の Gateway にアクティブな OpenClaw 作業の事前確認を要求し、返信配信、埋め込み実行、タスク実行がドレインされるまで再起動を延期します。--safe は --force または --wait と組み合わせることはできません。
• gateway restart --wait 30s は、その再起動について設定済みの再起動ドレイン予算を上書きします。単位なしの数値はミリ秒です。s、m、h などの単位を使用できます。--wait 0 は無期限に待機します。
• gateway restart --safe --skip-deferral は OpenClaw 対応の安全な再起動を実行しますが、延期ゲートをバイパスするため、ブロッカーが報告されても Gateway はただちに再起動を発行します。停止したタスク実行の延期に対するオペレーター用のエスケープハッチです。--safe が必要です。
• gateway restart --force はアクティブ作業のドレインをスキップし、ただちに再起動します。オペレーターが一覧表示されたタスクブロッカーをすでに確認しており、Gateway を今すぐ戻したい場合に使用します。
• ライフサイクルコマンドはスクリプト用に --json を受け付けます。

• トークン認証でトークンが必要で、gateway.auth.token が SecretRef 管理の場合、gateway install は SecretRef が解決可能であることを検証しますが、解決済みトークンをサービス環境メタデータに永続化しません。
• トークン認証でトークンが必要で、設定済みのトークン SecretRef が未解決の場合、フォールバックのプレーンテキストを永続化するのではなく、インストールは安全側で失敗します。
• gateway run のパスワード認証では、インラインの --password よりも OPENCLAW_GATEWAY_PASSWORD、--password-file、または SecretRef-backed gateway.auth.password を優先してください。
• 推論された認証モードでは、シェルだけの OPENCLAW_GATEWAY_PASSWORD はインストール時のトークン要件を緩和しません。管理対象サービスをインストールする場合は、永続的な設定（gateway.auth.password または config env）を使用してください。
• gateway.auth.token と gateway.auth.password の両方が設定され、gateway.auth.mode が未設定の場合、mode が明示的に設定されるまでインストールはブロックされます。