Gateway

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

• レコードは運用メタデータを保持します: イベント名、カウント、バイトサイズ、メモリ読み取り値、キュー/セッション状態、承認 id、チャネル/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 を明示的に渡すか、先にシークレットソースを解決してください。
• プローブが成功した場合、誤検知を避けるため未解決の認証参照警告は抑制されます。
• プローブが有効な場合、実行中の Gateway が報告すれば JSON 出力には gateway.version が含まれます。後続のハンドシェイクプローブがバージョンメタデータを提供できない場合、--require-rpc は status.runtimeVersion RPC ペイロードにフォールバックできます。
• リッスン中のサービスだけでは不十分で、読み取りスコープの RPC 呼び出しも正常である必要があるスクリプトや自動化では、--require-rpc を使用します。
• --deep は、追加の launchd/systemd/schtasks インストールをベストエフォートでスキャンします。複数の gateway らしいサービスが検出された場合、人間向け出力はクリーンアップのヒントを出力し、ほとんどのセットアップでは 1 台のマシンにつき 1 つの gateway を実行すべきだと警告します。
• --deep は、サービスプロセスが外部スーパーバイザー再起動のために正常終了した場合、最近の Gateway スーパーバイザー再起動の引き継ぎも報告します。
• --deep は plugin 対応モード（pluginValidation: "full"）で設定検証を実行し、設定済み plugin マニフェスト警告（たとえばチャンネル設定メタデータの欠落）を表面化するため、インストールおよび更新のスモークチェックで検出できます。デフォルトの gateway status は plugin 検証をスキップする高速な読み取り専用パスを維持します。
• 人間向け出力には、プロファイルまたは状態ディレクトリのずれを診断しやすくするため、解決済みファイルログパスと CLI 対サービス設定パス/有効性スナップショットが含まれます。

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

• 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 やペアリング状態は作成しません。
• 終了コードが非ゼロになるのは、プローブされた対象のどれにも到達できない場合だけです。

トップレベル:

• 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 scope の欠落により詳細 RPC が失敗しました。

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

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

• ssh_tunnel_failed: SSH トンネルのセットアップに失敗しました。コマンドは直接プローブにフォールバックしました。
• multiple_gateways: 別個の gateway ID に到達できたか、OpenClaw が到達可能な対象が同じ gateway であることを証明できませんでした。同じ gateway への SSH トンネル、proxy URL、または設定済みリモート URL は、この警告をトリガーしません。
• 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 なしで正常に再有効化します。KeepAlive と RunAtLoad を永続的に抑制し、次に明示的な gateway start が実行されるまで Gateway が再生成されないようにするには、--disable を渡します。手動停止を再起動やシステム再起動後も維持したい場合に使用します。
• gateway restart --safe は、実行中の Gateway にアクティブな作業を事前確認させ、アクティブな作業が完了した後に集約された再起動を 1 回スケジュールします。デフォルトの安全な再起動は、設定された gateway.reload.deferralTimeoutMs（デフォルト 5 分）までアクティブな作業を待機します。その時間枠が期限切れになると、再起動は強制されます。強制しない無期限の安全待機にするには、gateway.reload.deferralTimeoutMs を 0 に設定します。--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 に裏付けられた gateway.auth.password を優先してください。
• 推論認証モードでは、シェルのみの OPENCLAW_GATEWAY_PASSWORD はインストール時のトークン要件を緩和しません。管理対象サービスをインストールするときは、永続設定（gateway.auth.password または設定 env）を使用してください。
• gateway.auth.token と gateway.auth.password の両方が設定され、gateway.auth.mode が未設定の場合、モードが明示的に設定されるまでインストールはブロックされます。