openclaw gateway ... 配下にあります。
Bonjour 検出
ローカル mDNS + ワイドエリア DNS-SD のセットアップ。
検出の概要
OpenClaw が Gateway をアドバタイズして見つける仕組み。
設定
トップレベルの Gateway 設定キー。
Gateway を実行する
起動時の動作
起動時の動作
~/.openclaw/openclaw.jsonでgateway.mode=localが設定されていない限り、起動を拒否します。アドホック/開発用の実行には--allow-unconfiguredを使用してください。これは設定を書き込んだり修復したりせずにガードをバイパスします。openclaw onboard --mode localとopenclaw setupはgateway.mode=localを書き込みます。設定ファイルは存在するがgateway.modeが欠けている場合、それは破損/上書きされた設定として扱われ、Gateway はユーザーの代わりにlocalを推測することを拒否します。オンボーディングを再実行するか、キーを手動で設定するか、--allow-unconfiguredを渡してください。- 認証なしで loopback を超えてバインドすることはブロックされます。
--bindの値lan、tailnet、customは、現時点では IPv4 のみのパスで解決されます。IPv6 のみの持ち込みホスト構成では、Gateway の前段に IPv4 サイドカーまたはプロキシが必要です。SIGUSR1は、許可されている場合にプロセス内再起動をトリガーします。commands.restart（デフォルト: 有効）は外部から送信されるSIGUSR1を制御します。手動の OS シグナルによる再起動をブロックしつつ、gateway restartコマンド、gateway ツール、config-apply/update による再起動は引き続き許可するには、これをfalseに設定します。SIGINT/SIGTERMはプロセスを停止しますが、カスタム端末状態は復元しません。CLI を TUI や raw モード入力でラップしている場合は、終了前に端末を自分で復元してください。
オプション
WebSocket ポート（設定/env からのデフォルト。通常は
18789）。バインドモード:
loopback（デフォルト）、lan、tailnet、auto、custom。connect.params.auth.token 用の共有トークン。設定されている場合は OPENCLAW_GATEWAY_TOKEN がデフォルトです。認証モード:
none、token、password、trusted-proxy。--auth password 用のパスワード。Gateway パスワードをファイルから読み取ります。
Tailscale 公開:
off、serve、funnel。シャットダウン時に Tailscale serve/funnel 設定をリセットします。
gateway.mode=local の強制なしで起動します。アドホック/開発用ブートストラップのみ。設定を永続化または修復しません。存在しない場合は開発用設定 + ワークスペースを作成します（
BOOTSTRAP.md はスキップ）。開発用設定、認証情報、セッション、ワークスペースをリセットします。
--dev が必要です。起動前にターゲットポート上の既存リスナーをすべて終了します。
stdout/stderr への詳細ログ出力。
コンソールには CLI バックエンドログのみを表示します（stdout/stderr も有効にします）。
WebSocket ログスタイル:
auto、full、compact。--ws-log compact のエイリアス。生のモデルストリームイベントを JSONL にログ出力します。
生ストリーム JSONL パス。
--claude-cli-logs は --cli-backend-logs の非推奨エイリアスです。
--bind custom では、gateway.customBindHost を IPv4 アドレスに設定します。そのアドレスが利用できない場合、Gateway は 0.0.0.0 にフォールバックします。IPv6 のみの持ち込みホスト構成では、Gateway の前段に IPv4 サイドカーまたはプロキシが必要です。
Gateway を再起動する
--safe は、実行中の Gateway にアクティブな作業の事前チェックを依頼し、その作業がドレインした後に 1 回にまとめた再起動をスケジュールします。待機は gateway.reload.deferralTimeoutMs（デフォルト: 5 分 / 300000）で上限が設定されます。予算が切れると再起動は強制されます。強制せずに無期限で待つ（まだ保留中であることを定期的に警告する）には、deferralTimeoutMs: 0 を設定します。--safe は --force または --wait と組み合わせることはできません。
--skip-deferral は safe restart のアクティブ作業延期ゲートをバイパスするため、報告されたブロッカーがあっても Gateway はすぐに再起動します。これには --safe が必要です。延期が暴走タスクで詰まっている場合に使用します。
--wait <duration> は、通常（non-safe）の再起動のドレイン予算を上書きします。単位なしのミリ秒、または単位サフィックス ms、s、m、h、d（例: 30s、5m、1h30m）を受け付けます。--wait 0 は無期限に待機します。--force または --safe とは互換性がありません。
--force はアクティブ作業のドレインをスキップし、ただちに再起動します。通常の restart（フラグなし）は既存のサービスマネージャー再起動動作を維持します。
Gateway プロファイリング
OPENCLAW_GATEWAY_STARTUP_TRACE=1は、各フェーズのeventLoopMax遅延と Plugin ルックアップテーブルのタイミング（installed-index、manifest registry、startup planning、owner-map work）を含む起動時のフェーズタイミングをログ出力します。OPENCLAW_GATEWAY_RESTART_TRACE=1は、再起動スコープのrestart trace:行をログ出力します。シグナル処理、アクティブ作業のドレイン、シャットダウンフェーズ、次回起動、ready タイミング、メモリメトリクスが含まれます。OPENCLAW_DIAGNOSTICS=timelineとOPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>は、外部 QA ハーネス向けにベストエフォートの JSONL 起動診断タイムラインを書き込みます（設定diagnostics.flags: ["timeline"]と同等。パスは引き続き env のみです）。イベントループサンプルを含めるにはOPENCLAW_DIAGNOSTICS_EVENT_LOOP=1を追加します。pnpm buildの後にpnpm test:startup:gateway -- --runs 5 --warmup 1を実行すると、ビルド済み CLI エントリに対して Gateway 起動をベンチマークします。対象は、最初のプロセス出力、/healthz、/readyz、起動トレースタイミング、イベントループ遅延、Plugin ルックアップテーブルのタイミングです。pnpm buildの後にpnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5を実行すると、macOS または Linux 上のプロセス内再起動をベンチマークします（Windows ではサポートされません。再起動にはSIGUSR1が必要です）。SIGUSR1を使用し、子プロセスで両方のトレースを有効にし、次の/healthz、次の/readyz、ダウンタイム、ready タイミング、CPU、RSS、再起動トレースメトリクスを記録します。/healthzは liveness、/readyzは利用可能な readiness です。トレース行とベンチマーク出力は所有者帰属のシグナルとして扱い、単一のスパンやサンプルからの完全な性能結論として扱わないでください。
実行中の Gateway を問い合わせる
すべての問い合わせコマンドは WebSocket RPC を使用します。- 出力モード
- 共有オプション
- デフォルト: 人間が読みやすい形式（TTY では色付き）。
--json: 機械可読 JSON（スタイル/スピナーなし）。--no-color（またはNO_COLOR=1）: 人間向けレイアウトを維持しつつ ANSI を無効化します。
--url を設定すると、CLI は設定や環境の認証情報にフォールバックしません。--token または --password を明示的に渡してください。明示的な認証情報がない場合はエラーです。gateway health
/healthz は liveness プローブです。サーバーが HTTP に応答できるようになるとすぐに返ります。/readyz はより厳格で、起動時の Plugin サイドカー、チャンネル、または設定済みフックがまだ安定していない間は赤のままです。ローカルまたは認証済みの詳細な /readyz レスポンスには、eventLoop 診断ブロック（遅延、使用率、CPU コア比率、degraded フラグ）が含まれます。
このポート上の local loopback Gateway を対象にします。この呼び出しでは
OPENCLAW_GATEWAY_URL と OPENCLAW_GATEWAY_PORT を上書きします。gateway usage-cost
セッションログから usage-cost サマリーを取得します。
含める日数。
サマリーのスコープを、設定済みの 1 つのエージェント ID に限定します。
設定済みのすべてのエージェントを集計します。
--agent と組み合わせることはできません。gateway stability
実行中の Gateway から最近の診断 stability recorder を取得します。
含める最近のイベントの最大数（最大
1000）。診断イベントタイプでフィルターします。例:
payload.large または diagnostic.memory.pressure。診断シーケンス番号より後のイベントのみを含めます。
実行中の Gateway を呼び出す代わりに、永続化された stability bundle を読み取ります。
--bundle latest（または単独の --bundle）は state ディレクトリ配下の最新 bundle を選びます。bundle JSON パスを直接渡すこともできます。stability の詳細を出力する代わりに、共有可能なサポート診断 zip を書き込みます。
--export の出力パス。プライバシーと bundle の動作
プライバシーと bundle の動作
- レコードは運用メタデータを保持します。イベント名、件数、バイトサイズ、メモリ読み取り値、キュー/セッション状態、承認 ID、チャンネル/Plugin 名、編集済みセッションサマリーが含まれます。チャットテキスト、webhook 本文、ツール出力、生のリクエスト/レスポンス本文、トークン、Cookie、シークレット値、ホスト名、生のセッション ID は除外されます。recorder を完全に無効化するには
diagnostics.enabled: falseを設定します。 - Gateway の致命的な終了、シャットダウンのタイムアウト、再起動時の起動失敗は、recorder にイベントがある場合、同じ診断スナップショットを
~/.openclaw/logs/stability/openclaw-stability-*.jsonに書き込みます。最新の bundle はopenclaw gateway stability --bundle latestで調べます。--limit、--type、--since-seqは bundle 出力にも適用されます。
gateway diagnostics export
バグ報告用に設計されたローカル診断 zip を書き込みます。プライバシーモデルと bundle の内容については、Diagnostics Export を参照してください。
出力 zip パス。デフォルトは状態ディレクトリ配下のサポートエクスポートです。
含めるサニタイズ済みログ行の最大数。
検査するログバイト数の最大値。
ヘルススナップショット用の Gateway WebSocket URL。
ヘルススナップショット用の Gateway トークン。
ヘルススナップショット用の Gateway パスワード。
ステータス/ヘルススナップショットのタイムアウト。
永続化された安定性バンドルの検索をスキップします。
書き込まれたパス、サイズ、マニフェストを JSON として出力します。
manifest.json（ファイル一覧）、summary.md（Markdown サマリー）、diagnostics.json（トップレベルの設定/ログ/検出/安定性/ステータス/ヘルスのサマリー）、config/sanitized.json、status/gateway-status.json、health/gateway-health.json、logs/openclaw-sanitized.jsonl、stability/latest.json が含まれます。
これは共有されることを想定して設計されています。デバッグに有用な運用詳細（安全なログフィールド、サブシステム名、ステータスコード、所要時間、設定済みモード、ポート、plugin/provider ID、秘密ではない機能設定、秘匿化された運用ログメッセージ）は保持し、チャット本文、webhook 本文、ツール出力、認証情報、Cookie、アカウント/メッセージ識別子、プロンプト/指示テキスト、ホスト名、シークレット値は省略または秘匿化します。ログメッセージがユーザー/チャット/ツールのペイロードテキストに見える場合（例: “user said”、“chat text”、“tool output”、“webhook body”）、エクスポートではメッセージが省略された事実とそのバイト数のみを保持します。
gateway status
Gateway サービス（launchd/systemd/schtasks）と、任意の接続性/認証プローブを表示します。
明示的なプローブ対象を追加します。設定済みのリモート + localhost も引き続きプローブされます。
プローブ用のトークン認証。
プローブ用のパスワード認証。
プローブのタイムアウト。
接続性プローブをスキップします（サービスのみの表示）。
システムレベルのサービスもスキャンします。
接続性プローブを読み取りプローブに昇格し、失敗した場合はゼロ以外で終了します。
--no-probe とは併用できません。ステータスの意味
ステータスの意味
- ローカル CLI 設定が欠落または無効な場合でも、診断用に引き続き利用できます。
- デフォルト出力は、サービス状態、WebSocket 接続、ハンドシェイク時点で見える認証機能を証明します。読み取り/書き込み/管理操作を証明するものではありません。
- プローブは初回デバイス認証に対して非変更です。既存のキャッシュ済みデバイストークンがある場合は再利用しますが、ステータス確認だけのために新しい CLI デバイス ID や読み取り専用ペアリングレコードを作成することはありません。
- 可能な場合、プローブ認証用に設定済み認証 SecretRef を解決します。必須の SecretRef が未解決の場合、プローブの接続性/認証が失敗すると
--jsonはrpc.authWarningを報告します。--token/--passwordを明示的に渡すか、シークレットソースを修正してください。未解決認証の警告は、プローブが成功すると抑制されます。 - JSON 出力には、実行中の Gateway が報告する場合に
gateway.versionが含まれます。ハンドシェイクプローブがバージョンメタデータを提供できない場合、--require-rpcはstatus.runtimeVersionRPC ペイロードにフォールバックできます。 - リスニング中のサービスだけでは不十分で、読み取りスコープ RPC も正常である必要があるスクリプト/自動化では、
--require-rpcを使用します。 --deepは追加の launchd/systemd/schtasks インストールをスキャンします。複数の gateway らしきサービスが見つかった場合、人間向け出力はクリーンアップのヒント（通常はマシンごとに 1 つの gateway を実行）を表示し、関連がある場合は最近のスーパーバイザー再起動の引き継ぎを報告します。--deepは plugin 対応モード（pluginValidation: "full"）で設定検証も実行し、plugin マニフェスト警告（例: チャンネル設定メタデータの欠落）を表示します。デフォルトのgateway statusは、plugin 検証をスキップする高速な読み取り専用パスを維持します。- 人間向け出力には、プロファイルまたは状態ディレクトリのずれの診断に役立つように、解決済みファイルログパスと CLI 対サービスの設定パス/妥当性が含まれます。
Linux systemd 認証ドリフトチェック
Linux systemd 認証ドリフトチェック
- サービス認証ドリフトチェックは、ユニットから
Environment=とEnvironmentFile=の両方を読み取ります（%h、引用符付きパス、複数ファイル、任意の-ファイルを含む）。 - マージされたランタイム環境（最初にサービスコマンド環境、次にプロセス環境へのフォールバック）を使用して、
gateway.auth.tokenSecretRef を解決します。 - トークンドリフトチェックは、トークン認証が実質的に有効でない場合（
gateway.auth.modeが明示的にpassword/none/trusted-proxy、またはモード未設定でパスワードが勝ち得てトークン候補が勝ち得ない場合）、設定トークンの解決をスキップします。
gateway probe
「すべてをデバッグする」コマンドです。常に次をプローブします。
- 設定済みのリモート gateway（設定されている場合）、および
- localhost（ループバック）。リモートが設定されている場合でも同様です。
--url を渡すと、その明示的な対象が両方より前に追加されます。人間向け出力では、対象に URL (explicit)、Remote (configured) / Remote (configured, inactive)、Local loopback というラベルが付けられます。
複数のプローブ対象に到達可能な場合、すべて出力されます。SSH トンネル、TLS/proxy URL、設定済みリモート URL は、異なるトランスポートポートでも同じ gateway を指すことがあります。
multiple_gateways は、別個または ID が曖昧な到達可能 gateway のために予約されています。複数の gateway の実行は、分離されたプロファイル（例: レスキューボット）ではサポートされますが、ほとんどのインストールでは単一の gateway を実行します。ローカル local loopback プローブ対象と SSH トンネルのリモートポートにこのポートを使用します。
--url がない場合、これは設定済み gateway 環境 URL、環境ポート、またはリモート対象の代わりに、ローカル local loopback 対象のみを選択します。解釈
解釈
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は、WebSocket は接続されたものの、後続の読み取り診断がタイムアウトまたは失敗したことを意味します。これも到達不能ではなく劣化です。gateway statusと同様に、probe は既存のキャッシュ済みデバイス認証を再利用しますが、初回デバイス ID やペアリング状態は作成しません。- 終了コードがゼロ以外になるのは、プローブされた対象が 1 つも到達可能でない場合のみです。
JSON 出力
JSON 出力
トップレベル:
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）: 利用可能な場合は hello-ok で報告された role と scopes、および表示された capability 分類。SSH 経由のリモート（Mac アプリ互換）
macOS アプリの「Remote over SSH」モードは、ローカルポートフォワードを使用し、ループバック専用のリモート gateway をws://127.0.0.1:<port> で到達可能にします。
CLI の同等操作:
user@host または user@host:port（ポートのデフォルトは 22）。ID ファイル。
解決済み検出エンドポイント（
local. と、設定済みの広域ドメインがある場合はそれを加えたもの）から、最初に検出された gateway ホストを SSH 対象として選択します。TXT のみのヒントは無視されます。gateway.remote.sshTarget、gateway.remote.sshIdentity。
gateway call <method>
低レベル RPC ヘルパー。
params 用の JSON オブジェクト文字列。
Gateway WebSocket URL。
Gateway トークン。
Gateway パスワード。
タイムアウト予算。
主に、最終ペイロードの前に中間イベントをストリームするエージェント形式の RPC 向けです。
機械可読な JSON 出力。
--params は有効な JSON である必要があり、各メソッドは独自の param 形状を検証します（余分なフィールドや名前の誤ったフィールドは拒否されます）。Gateway サービスの管理
ラッパーを使用したインストール
管理対象サービスを別の実行ファイルを通じて起動する必要がある場合、たとえばシークレットマネージャーのシムや run-as ヘルパーを使う場合は、--wrapper を使用します。ラッパーは通常の Gateway 引数を受け取り、最終的にそれらの引数で openclaw または Node を exec する責任を持ちます。
gateway install は、パスが実行可能ファイルであることを検証し、ラッパーをサービスの ProgramArguments に書き込み、後続の強制再インストール、更新、doctor 修復のためにサービス環境へ OPENCLAW_WRAPPER を永続化します。
OPENCLAW_WRAPPER をクリアします。
コマンドオプション
コマンドオプション
gateway status:--url,--token,--password,--timeout,--no-probe,--require-rpc,--deep,--jsongateway install:--port,--runtime <node|bun>(デフォルト:node),--token,--wrapper <path>,--force,--jsongateway restart:--safe,--skip-deferral,--force,--wait <duration>,--jsongateway uninstall|start:--jsongateway 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を渡します。手動停止を再起動後も維持したい場合に使用してください。 - ライフサイクルコマンドはスクリプト用途向けに
--jsonを受け付けます。
インストール時の認証と SecretRef
インストール時の認証と SecretRef
- トークン認証でトークンが必要で、
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が未設定の場合、モードが明示的に設定されるまでインストールはブロックされます。
Gatewayを検出する (Bonjour)
gateway discover は Gatewayビーコン (_openclaw-gw._tcp) をスキャンします。
- マルチキャスト DNS-SD:
local. - ユニキャスト DNS-SD (広域 Bonjour): ドメインを選択し (例:
openclaw.internal.)、分割 DNS と DNS サーバーを設定します。Bonjour を参照してください。
role (Gateway のロールヒント)、transport (トランスポートヒント、例: gateway)、gatewayPort (WebSocket ポート、通常は 18789)、tailnetDns (利用可能な場合は MagicDNS ホスト名)、gatewayTls / gatewayTlsSha256 (TLS 有効 + 証明書フィンガープリント)。sshPort と cliPath は完全検出モード (discovery.mdns.mode: "full"、デフォルトは "minimal" で、これらは省略されます) の場合にのみ公開されます。クライアントはその場合、SSH ターゲットのデフォルトとしてポート 22 を使用します。
gateway discover
コマンドごとのタイムアウト (参照/解決)。
機械可読な出力 (スタイル設定/スピナーも無効化します)。
local.に加えて、有効化されている場合は設定済みの広域ドメインをスキャンします。- JSON 出力の
wsUrlは、lanHostやtailnetDnsのような TXT のみのヒントからではなく、解決済みサービスエンドポイントから導出されます。 discovery.mdns.modeは、local.mDNS と広域 DNS-SD の両方でsshPort/cliPathの公開を制御します (上記参照)。